Skip to content

feat(codegen): a WordPress API from the site's own index, and permission keys from a field's value - #647

Merged
leemour merged 1 commit into
mainfrom
feat/wp-json-spec
Nov 18, 2026
Merged

leemour merged 1 commit into
mainfrom
feat/wp-json-spec

Conversation

@leemour

@leemour leemour commented Nov 18, 2026

Copy link
Copy Markdown
Member

Task

C3 of the content category, cli-base half: read a WordPress site's API from its own index, and give a publishing write a permission key, so the WordPress CLI's raw api group cannot publish past a profile that denies it.

Why

WordPress publishes no OpenAPI. And a key that only checks "is this flag true" cannot say "status is publish": an agent could publish with a plain POST /wp/v2/posts, whatever posts.publish says (RISK-2323 in the content-category plan).

What

  • syncWpJson / readWpJson / wpJsonToOpenApi. One call, GET /wp-json/?context=help, returns every route with its arguments and its answer's schema. I checked on WordPress 6.9.4 that this schema equals what OPTIONS returns, for all 78 routes callable directly. So the snapshot is one file, not one OPTIONS call per route as the plan said.
    • The snapshot drops the site's name, address and links, and keeps provenance with the hash.
    • The converter writes OpenAPI 3.1, and the existing adaptOpenApi reads it. WordPress 6.9.4's wp/v2 gives 152 operations (getWpV2Posts, postWpV2PostsById…), and the generated types, schemas and manifest compile.
    • GET reads and DELETE deletes, with force in the query. POST/PUT/PATCH becomes one POST write.
    • A collection read answers a list.
    • An array in the query travels comma-separated. Checked on WordPress: include=1,5 returns both posts, while include=1&include=5 returns only the last.
    • A route whose value may hold a slash (templates, plugins, fonts) is left out and listed. So is every namespace not offered.
    • A route still a pattern, two routes on one path, or an untyped argument stops generation unless exclude names it.
  • permissions.valueKeys. { key: "publish", field: "status", values: ["publish", "future"] } gives <group>.publish to a write whose status enum lists those values, through refs and unions too. On WordPress 6.9.4 that covers posts, pages, media, blocks, navigation and menu items.
    • A field that defaults to such a value makes the key always apply. That's templates, template parts and new menu items, where leaving status out publishes.
    • A read that filters by the value, and a field without such an enum (a comment's status), get no key.
    • OperationPermission.values carries it, and the coverage page says "status is publish or future".
    • The plan put this in overrides. As a rule beside deletingFlags, one entry covers every post type.
  • sha256 and sortKeys move to snapshot.ts. Discovery and GraphQL each had a copy.

Not here: cli-core's runtime check of values (next PR, on this release); wp-json as a config spec.kind in cli-template (the WordPress pilot); paging: WordPress pages by headers, so pagination: true finds none yet. Basic sign-in in fakeApi was already in 0.117.0 (#643); a test here runs the generated WordPress manifest through it.

Testing

  • src/codegen/wp-json.test.ts runs on an excerpt of WordPress 6.9.4's real index. The excerpt is in test/fixtures/wp-json/, with GPL notice. The tests cover:
    • ids and methods, and where each argument goes;
    • draft 4 quirks: required in both spellings, bool, untyped objects, patternProperties;
    • the omissions and the failures;
    • publish keys, including the default-publish case, refs, unions and reads;
    • fakeApi with an application password;
    • sync and read, including a password in the URL and a changed hash.
  • The full 6.9.4 snapshot was converted and its generated code compiled. Full suite: 1,272 tests. Typecheck, lint and docs check pass.
  • A fresh review found a bypass: templates and menu items default status to publish. It's fixed with the rest of that review's findings. _method / X-HTTP-Method-Override can't be sent, because cli-core's api group only takes declared parameters.

🤖 Generated with Claude Code

…ion keys from a field's value

WordPress has no OpenAPI, but /wp-json/?context=help lists every route with its arguments and the schema of its
answer, the same one OPTIONS returns. syncWpJson keeps that one answer without the site's name, address and links;
wpJsonToOpenApi turns a namespace's routes into OpenAPI 3.1 for adaptOpenApi: 152 operations from WordPress 6.9.4's
wp/v2, ids from the method and path. A route whose value may hold a slash, and every namespace not offered, is left
out and listed; an array in the query travels comma-separated, as PHP keeps only the last of a repeated name
(checked on WordPress 6.9.4).

permissions.valueKeys gives <group>.<key> to a write or delete whose field lists one of the values in its enum,
through a reference or a union: status publish or future needs posts.publish, so a profile that denies publishing
also stops the raw api group (RISK-2323). Where the field defaults to such a value (templates, template parts, menu
items), the key applies on every call. A read that filters by the value gets none. OperationPermission.values carries
it; cli-core checks it in the body and the query.

sha256 and sortKeys move to snapshot.ts: discovery and graphql had a copy each.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit e2be460 into main Nov 18, 2026
10 checks passed
@leemour
leemour deleted the feat/wp-json-spec branch November 18, 2026 10:49
@leemour leemour mentioned this pull request Nov 18, 2026
leemour added a commit that referenced this pull request Nov 18, 2026
Carries #647 (`wpJsonToOpenApi`, `permissions.valueKeys`), the only
change since 0.117.0. Minor: the Unreleased section has Added.
cli-core's check of the new `values` waits on this version.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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