Repository navigation
Improvements: agent-ready spec, API keys, Octane image, make:endpoint - #5
Merged
Merged
Conversation
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.
|
Note Currently processing new changes in this PR. This may take a few minutes, please wait... ⚙️ Run configuration
⛔ Files ignored due to path filters: 1
📒 Files selected for processing: 66
✨ Finishing Touches
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. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
token_id,id,hashandtokenwere 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 throughApp\Http\Payloads\RouteParameter. A malformed ID is now a 404 problem rather than a 422.{"message"}. They use Scribe'sResponseattribute aliased asScribeResponse, which my earlier rewrite missed..legible.yamlfails on any warning or a score under 95, and accepts validation'serrorsmember with a reason. CI downloads a pinned, checksum-verified legible and checks the spec the test suite regenerates.Scoped API keys:
POST /v1/auth/tokenssanctum.abilities.available).API_KEY_DEFAULT_DAYS,API_KEY_MAX_DAYS).sanctum.expirationwas a 120-minute cap on every token, which would have expired a key with the session that made it. Every token now carries its ownexpires_at, and session tokens still lastSANCTUM_EXPIRATIONminutes.App\Support\AccessTokensissues both kinds, replacing the copies inLoginControllerandRegisterController.Queued emails
Verification and reset emails are now queued notifications, sent in the language of the request that asked for them.
Production image
dunglas/frankenphp:1.13.1-php8.5-trixie), non-root, on port 8000, with a host-aware health check on/up.php artisan queue:work.config/scribe.phpreferenced Scribe's classes, and Scribe is a dev dependency, so every artisan command failed in any production install. It now returns early without Scribe.laravel/octane2.22.0,laminas/laminas-diactoros3.9.0 andsymfony/psr-http-message-bridge8.1.9 are added tovet.json. The latter two were reviewed for install-time hooks, network endpoints, dynamic code, shell execution and secret reads.Vet:
laravel/*trusted by policylaravel/*skips the 7-day release hold.laravel/*, the bot records their trust and commitsvet.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:endpointphp artisan make:endpoint Projects/CreateProject --method=POST --uri=/projectswrites:queryParameters()on a GETidempotenton a POSTPint formats the output, and the stubs are in
stubs/endpoint.What it can't know stays visible:
501.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
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:
instanceand outgoing requests lost the trace.instanceof its own request, with no carry-over between requests, and the CI image job now asserts it.