Skip to content

Improvements: agent-ready spec, API keys, Octane image, make:endpoint - #5

Merged
JustSteveKing merged 9 commits into
mainfrom
improvements
Oct 20, 2026
Merged

JustSteveKing merged 9 commits into
mainfrom
improvements

Conversation

@JustSteveKing

@JustSteveKing JustSteveKing commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

Nine commits, one per change. 102 tests pass; Pint, PHPStan (level 10) and legible are clean, and the new image job boots the container on every push.

Agent-ready OpenAPI, gated in CI

legible scored the spec 90 (3 errors, 14 warnings). It now scores 100.

  • Argument collisions. Form Requests merged route parameters into validation, so token_id, id, hash and token were documented as body fields as well as path ones. Path parameters are now validated by route constraints (whereNumber, whereUlid, a hash pattern), and payloads read them through App\Http\Payloads\RouteParameter. A malformed ID is now a 404 problem rather than a 422.
  • Stale error examples. Six still showed {"message"}. They use Scribe's Response attribute aliased as ScribeResponse, which my earlier rewrite missed.
  • Descriptions. Every operation's description now says what it does, when to use it and what it returns.
  • Missing errors. Forgot-password and the reset-token read now document their 422 (and 429).
  • 204s are documented with no content.
  • The gate. .legible.yaml fails on any warning or a score under 95, and accepts validation's errors member with a reason. CI downloads a pinned, checksum-verified legible and checks the spec the test suite regenerates.

Scoped API keys: POST /v1/auth/tokens

  • No escalation. A key can only hold abilities that the token creating it holds, out of the abilities routes check (sanctum.abilities.available).
  • Expiry. 90 days by default, at most 365 (API_KEY_DEFAULT_DAYS, API_KEY_MAX_DAYS).
  • Idempotent, so a retry can't mint a second key.
  • Global expiry is off. sanctum.expiration was a 120-minute cap on every token, which would have expired a key with the session that made it. Every token now carries its own expires_at, and session tokens still last SANCTUM_EXPIRATION minutes.
  • Shared issuing. App\Support\AccessTokens issues both kinds, replacing the copies in LoginController and RegisterController.

Queued emails

Verification and reset emails are now queued notifications, sent in the language of the request that asked for them.

Production image

  • What it is. Octane on FrankenPHP (pinned dunglas/frankenphp:1.13.1-php8.5-trixie), non-root, on port 8000, with a host-aware health check on /up.
  • Queue worker. The same image runs one: php artisan queue:work.
  • Production bug found while building it. config/scribe.php referenced Scribe's classes, and Scribe is a dev dependency, so every artisan command failed in any production install. It now returns early without Scribe.
  • Smoke-tested locally, and now in CI. Problem responses carry HSTS and the request ID, plain HTTP and untrusted hosts are refused, and the locale resets between requests under Octane.
  • Packages. laravel/octane 2.22.0, laminas/laminas-diactoros 3.9.0 and symfony/psr-http-message-bridge 8.1.9 are added to vet.json. The latter two were reviewed for install-time hooks, network endpoints, dynamic code, shell execution and secret reads.

Vet: laravel/* trusted by policy

  • No hold. laravel/* skips the 7-day release hold.
  • No review when it's the only change. When every package a weekly update changed is laravel/*, the bot records their trust and commits vet.json, so that PR needs no review. The decision compares the two locks in jq; I tested it on mixed, Laravel-only and unchanged updates.

make:endpoint

php artisan make:endpoint Projects/CreateProject --method=POST --uri=/projects writes:

  • the controller, with Scribe attributes and its 401, 403 and 422 problems
  • the Form Request, with queryParameters() on a GET
  • the payload
  • a Pest test whose 401 and 403 cases pass at once
  • the route, with auth, rate limit, ability, name, and idempotent on a POST

Pint formats the output, and the stubs are in stubs/endpoint.

What it can't know stays visible:

  • The controller answers 501.
  • Path parameters get a TODO to constrain them.
  • The description is TODO, and a new contract test plus legible fail CI until it's written.

It also stops Scribe renaming {project} to {id}, which broke the spec's match with the routes.

I tested it end to end in a copy of Kit with four endpoints (POST, GET with a parameter, DELETE, public GET): the generated code passes Pint and PHPStan, the guard tests pass, and the TODO guard fails as intended. Command tests run against a temporary base path, so they are safe under --parallel.

Also

  • Rector removed until it's configured.
  • AGENTS.md and the README cover all of the above.

api-toolbox 0.3.1

api-toolbox#2, released as v0.3.1, fixes two Octane bugs found while smoke-testing the image. Kit now requires it:

  • What was wrong. Under Octane, problems lost their instance and outgoing requests lost the trace.
  • Vet. It records the update after checking the release diff is exactly the two reviewed files.
  • Proof. The rebuilt image gives each problem the instance of its own request, with no carry-over between requests, and the CI image job now asserts it.

rector/rector and driftingly/rector-laravel were installed without a
rector.php, so nothing ran them. vet.json drops their entries.
The token, verification and reset-token Form Requests merged route
parameters into validation, so Scribe documented token_id, id, hash and
token as body fields as well as path ones, and email on a GET as a body
field. legible reports that as an argument collision: flattened into
one tool input, the two names clash.

Path parameters are now validated by route constraints (whereNumber,
whereUlid, a 40-hex hash), so a malformed one is a 404 problem rather
than a 422. Payloads read them through App\Http\Payloads\RouteParameter.
DeleteTokenRequest and VerifyEmailRequest had nothing left and are
removed; ShowResetPasswordTokenRequest keeps email, documented as a
query parameter through queryParameters().
legible scored the spec 90 with 3 errors and 14 warnings. Now 100:

- Six error examples still showed {"message"}: they use Scribe's
  Response attribute aliased as ScribeResponse, which the earlier
  rewrite missed. They are problem details now.
- Every operation's description says what it does, when to use it and
  what it returns. Descriptions are the prose that survives conversion
  into a tool definition.
- Forgot-password and the reset-token read document their 422 (and
  429) instead of no error at all.
- 204s are documented without content (NoContentOpenApiGenerator):
  Scribe gave them a nullable JSON body.

.legible.yaml fails on any warning or a score under 95, and accepts the
validation problems' extra errors member with the reason. CI downloads
a pinned, checksum-verified legible and checks the spec the test suite
regenerates.
Machine clients and agents had no way to get a token without signing
in with a password, which grants the session defaults. An API key now
takes a name, abilities and an optional expiry:

- Abilities must be held by the token creating the key, and be ones a
  route checks (sanctum.abilities.available), so a narrow key can
  never mint a broader one. The endpoint needs auth:tokens:create,
  which session tokens get by default.
- Keys expire after 90 days by default, at most 365
  (API_KEY_DEFAULT_DAYS, API_KEY_MAX_DAYS).
- The request is idempotent, so a retry cannot mint a second key.

sanctum.expiration was a global 120-minute cap on every token, which
would have expired an API key with the session that made it. It is off;
every token carries its own expires_at, and session tokens still last
SANCTUM_EXPIRATION minutes. App\Support\AccessTokens issues both kinds,
replacing the copies in LoginController and RegisterController.
Both were sent inside the request, so a slow mail server slowed
registration, resend and forgot-password. They are now queued
notifications (App\Notifications), sent in the locale of the request
that asked for them, since a queued job otherwise runs in the default
locale. Queueing the reset email also stops forgot-password taking
measurably longer when the account exists.
Vet has no wildcard trust, so the policy has two parts. laravel/* is
excluded from the 7-day release hold in vet.json. And when every
package a weekly update changed is laravel/*, the bot records their
trust (vet --fresh) and commits vet.json with the PR, which then needs
no review. Anything else changing still waits for one.

The decision compares the lock before and after the update in jq;
removed packages do not count, since removing code adds nothing to
trust.
A Dockerfile on dunglas/frankenphp (PHP 8.5, pinned) runs Octane in
worker mode on port 8000, as a non-root user, with OPcache tuned for
production and a health check on /up. The same image runs a queue
worker when given a command: `docker run <image> php artisan
queue:work`. The entrypoint caches config, routes and events from the
runtime environment before starting.

Building it found a bug in any production install: config/scribe.php
references Scribe's classes, and Scribe is a dev dependency, so every
artisan command failed without dev packages. The config now returns
nothing when Scribe is absent.

Kit holds no request state outside scoped bindings, and Octane resets
locale and auth between requests (the smoke test checks Spanish then
English). A CI job builds the image, boots it with production settings
and requests /up and a problem through proxy headers.

laravel/octane 2.22.0, laminas/laminas-diactoros 3.9.0 and
symfony/psr-http-message-bridge 8.1.9 are recorded in vet.json. The
latter two were reviewed for install-time hooks, network endpoints,
dynamic code, shell execution and secret reads; nothing found.
php artisan make:endpoint Projects/CreateProject --method=POST
--uri=/projects writes the six pieces AGENTS.md describes: a controller
with Scribe attributes and its 401, 403 and 422 problems, a Form
Request (with queryParameters() on a GET, so Scribe never documents a
body), a payload, a Pest test whose 401 and 403 cases pass at once and
whose success case is a todo, and the route with auth, rate limit,
ability, name, and idempotent on a POST. --guest, --ability and
--force adjust it; missing input is prompted for. Stubs live in
stubs/endpoint for projects to change, and Pint formats the output.

What it cannot know stays visible: the controller answers 501, path
parameters get a TODO to constrain them, and the description is three
TODO sentences. A new contract test fails while the spec says TODO, and
legible fails the identical descriptions, so an endpoint cannot ship
half documented. It prints the steps it does not take for you, such as
adding the ability to config/sanctum.php.

Scribe renamed {project} to {id} when it guessed at route model
binding, so the spec no longer matched the routes. Path parameters are
now documented as the routes name them.
AGENTS.md now starts endpoints with make:endpoint, says path parameters
are validated by route constraints, covers abilities and API keys,
Octane-safe code and the queue worker, the laravel/* trust policy, and
legible as the fourth check. The README adds the API key endpoint, the
generator, deployment, the queue worker in Quick Start, and the new CI
jobs and files.
@coderabbitai

coderabbitai Bot commented Oct 20, 2026

Copy link
Copy Markdown

Review in Change Stack →

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: b4ec4e58-824a-4d34-bc9f-1bfb828ff0db
📥 Commits

Reviewing files that changed from the base of the PR and between 1c59af9 and e252912.

⛔ Files ignored due to path filters: 1
  • composer.lock is excluded by !**/*.lock
📒 Files selected for processing: 66
  • .dockerignore
  • .env.example
  • .github/workflows/ci-tests.yml
  • .github/workflows/dependency-updates.yml
  • .gitignore
  • .legible.yaml
  • .scribe/endpoints.cache/00.yaml
  • .scribe/endpoints/00.yaml
  • AGENTS.md
  • Dockerfile
  • README.md
  • app/Console/Commands/EndpointBlueprint.php
  • app/Console/Commands/MakeEndpointCommand.php
  • app/Http/Controllers/Api/V1/Auth/CreateTokenController.php
  • app/Http/Controllers/Api/V1/Auth/DeleteAllTokensController.php
  • app/Http/Controllers/Api/V1/Auth/DeleteTokenController.php
  • app/Http/Controllers/Api/V1/Auth/ForgotPasswordController.php
  • app/Http/Controllers/Api/V1/Auth/ListTokensController.php
  • app/Http/Controllers/Api/V1/Auth/LoginController.php
  • app/Http/Controllers/Api/V1/Auth/LogoutController.php
  • app/Http/Controllers/Api/V1/Auth/MeController.php
  • app/Http/Controllers/Api/V1/Auth/RegisterController.php
  • app/Http/Controllers/Api/V1/Auth/ResetPasswordController.php
  • app/Http/Controllers/Api/V1/Auth/SendEmailVerificationNotificationController.php
  • app/Http/Controllers/Api/V1/Auth/ShowResetPasswordTokenController.php
  • app/Http/Controllers/Api/V1/Auth/VerifyEmailController.php
  • app/Http/Payloads/RouteParameter.php
  • app/Http/Payloads/V1/CreateTokenPayload.php
  • app/Http/Payloads/V1/DeleteTokenPayload.php
  • app/Http/Payloads/V1/ShowResetPasswordTokenPayload.php
  • app/Http/Payloads/V1/VerifyEmailPayload.php
  • app/Http/Requests/Auth/CreateTokenRequest.php
  • app/Http/Requests/Auth/DeleteTokenRequest.php
  • app/Http/Requests/Auth/ShowResetPasswordTokenRequest.php
  • app/Http/Requests/Auth/VerifyEmailRequest.php
  • app/Models/User.php
  • app/Notifications/ResetPassword.php
  • app/Notifications/VerifyEmail.php
  • app/Providers/AppServiceProvider.php
  • app/Support/AccessTokens.php
  • app/Support/NoContentOpenApiGenerator.php
  • composer.json
  • config/octane.php
  • config/sanctum.php
  • config/scribe.php
  • docker/entrypoint.sh
  • docker/healthcheck.php
  • docker/php.ini
  • lang/en/api.php
  • lang/es/api.php
  • public/docs/collection.json
  • public/docs/index.html
  • public/docs/openapi.yaml
  • routes/api/v1.php
  • stubs/endpoint/controller.stub
  • stubs/endpoint/payload.stub
  • stubs/endpoint/request.stub
  • stubs/endpoint/test.stub
  • tests/Feature/AuthRecoveryTest.php
  • tests/Feature/AuthSecurityTest.php
  • tests/Feature/AuthTokenManagementTest.php
  • tests/Feature/AuthTokenTest.php
  • tests/Feature/IdempotencyKeyTest.php
  • tests/Feature/MakeEndpointCommandTest.php
  • tests/Feature/OpenApiContractTest.php
  • vet.json
+--------------------------------------------------------------------------------+
| Alea Iacta Est, Bugs Delenda Est. The die is cast, the bugs must be destroyed. |
+--------------------------------------------------------------------------------+
  \
   \     /)/)
        ( '')
        /  |
      o(___)
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@JustSteveKing
JustSteveKing merged commit 60a42e0 into main Oct 20, 2026
8 of 9 checks passed
@JustSteveKing
JustSteveKing deleted the improvements branch October 20, 2026 10:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant