Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,27 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
[`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).

## Unreleased

### Added

- **A WordPress API from the site's own index: `syncWpJson`, `readWpJson` and `wpJsonToOpenApi`.** WordPress has no
OpenAPI, but `/wp-json/?context=help` lists every route with its arguments and the schema of its answer.
`syncWpJson` keeps that one answer, without the site's name, address and links, with its provenance;
`wpJsonToOpenApi` turns the routes of the namespaces a CLI offers into OpenAPI 3.1 for `adaptOpenApi`. WordPress
6.9.4's `wp/v2` gives 152 operations (`getWpV2Posts`, `postWpV2PostsById`…). A route whose value may hold a slash
(templates, plugins, fonts) is left out and listed in `omissions`. Watch for: an array argument in the query is
one comma-separated string, as WordPress splits it and PHP keeps only the last of a repeated name, so it loses
its `enum`; WordPress's lists
page by headers, so `pagination: true` finds no paging for them yet.
- **A permission key from a field's value: `permissions.valueKeys`.** `{ key: "publish", field: "status", values:
["publish", "future"] }` gives `posts.publish` to a write that sends `status: "publish"`, in the body or the query,
so a profile that denies publishing also stops the raw `api` group. Where the field defaults to such a value
(WordPress's templates, template parts and menu items), the key applies on every call, as leaving the field out
publishes. `OperationPermission.values` carries it in the manifest, and the coverage page's "When" says `` `status` is publish or future ``. Watch for: cli-core checks
`values` only from the release that reads them; an older cli-core asks for the key on every call of that operation,
as it does for a key with no flags.

## 0.117.0 — 18.11.2026

### Added
Expand Down
19 changes: 19 additions & 0 deletions docs/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,25 @@ is the GraphQL counterpart of `fakeApi`: it takes only a document `graphqlDocume
type lacks, an object selected without fields and variables that break their schema, and answers `{ data: { <field> } }`
within the selection, or a scenario's `errors` with HTTP 200.

**A WordPress site describes its own API.** WordPress publishes no OpenAPI, but one call to
`/wp-json/?context=help` lists every route with its arguments and the schema of its answer, the same schema an
`OPTIONS` call returns. `syncWpJson({ root, dir, version })` asks for it and writes `wp-json.json`, without the site's
name, address and links, with a `provenance.json` that keeps the URL it asked, without a user or password; take it from a plain WordPress in Docker, as the CLI serves every
site, and give the WordPress `version`, which the index does not say. `readWpJson(dir)` loads it back and stops on a
changed hash. `wpJsonToOpenApi(index, { namespaces, exclude, site, version })` turns the routes of `namespaces`
(`["wp/v2"]`) into an OpenAPI 3.1 document for `adaptOpenApi`, with its `omissions`. GET reads, DELETE deletes with
its arguments in the query (`force`), and a route that takes POST, PUT and PATCH gets one write, POST, whose
arguments are its JSON body. Ids come from the method and path: `getWpV2Posts`, `postWpV2PostsById`. A collection read
(it takes `page` and `per_page`) answers a list of the route's schema. An array argument in the query becomes one
comma-separated string, which WordPress splits; PHP would keep only the last of a repeated name. The string loses the
array's `enum`, so WordPress, not the CLI, refuses a wrong value in it. The server is
`https://{site}/wp-json` and the sign-in an application password by Basic. A route whose value may hold a slash (a
template's `theme//slug`, a plugin's `dir/file`) fits no path segment and is left out, listed in `omissions` with the
namespaces not offered; a route
that is still a pattern, a second route on one path or an argument with no type stops generation, unless `exclude`
names the route with a reason. WordPress answers a list without its page count in the body, so `pagination: true`
finds no paging for it.

The generated schemas import `@wirecat/cli-base/codegen/runtime` at run time — a few number
helpers, not the generator. Numbers are expected from a lossless JSON parser (`lossless-json`): a
64-bit integer comes out as its exact decimal string, and any other integer that does not fit a JS
Expand Down
10 changes: 9 additions & 1 deletion docs/standards/kit-surface.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ what it cannot do yet.
| Swagger 1.2 (Yandex Disk) | `upgradeToOpenApi3(listing, declarations)`: the resource listing, and each API declaration keyed by its `apis[].path`, fetched from the listing's `basePath` followed by that path |
| Google Discovery | `adaptDiscovery(readDiscovery(dir))`, snapshots written by `syncDiscovery` |
| GraphQL (Linear) | `adaptGraphql(readGraphql(dir), { url, scalars })`, the introspection result written by `syncGraphql` |
| WordPress's REST index | `adaptOpenApi(wpJsonToOpenApi(readWpJson(dir), { namespaces: ["wp/v2"] }).document)`, the index written by `syncWpJson` |

`upgradeToOpenApi3` converts with [swagger-converter](https://github.com/apigee-127/swagger-converter) (1.2 → 2.0) and
[@scalar/openapi-upgrader](https://github.com/scalar/scalar/tree/main/packages/openapi-upgrader) (2.0 → 3.0). They are
Expand Down Expand Up @@ -106,14 +107,21 @@ From the source the generator reads:
empty or not in kebab case stops generation; map that operation in `commands`. `segments` renames a path segment
or, with `""`, leaves it out: `{ "0-3": "deals", crm: "", objects: "" }`. Without `names` the command is the operation
id in kebab case, as before.
- **`permissions`**: `{ group, deletingFlags, shares }`. `group` is a name (`files`) or a function of the operation, for
- **`permissions`**: `{ group, deletingFlags, shares, valueKeys }`. `group` is a name (`files`) or a function of the operation, for
example the first word of its `command` (set only with `names`). Each key lands in the manifest as the operation's `permissions`.
- `<group>.delete` for every destructive operation (Yandex Disk's `DELETE /trash/resources` empties the whole
trash), and for every operation that takes a flag in `deletingFlags`, as a top-level body field (Notion's
`archived`, `in_trash`, a subtype's included) or a query parameter (Yandex Disk's `permanently`, `overwrite`). The
key applies when the flag is `true`. A flag no operation takes stops generation.
- `<group>.share` for the operation ids in `shares`: a public link opens a file to anyone, which is neither a
plain write nor a delete.
- `<group>.<key>` for each of `valueKeys`, `{ key, field, values }`, on every write or delete whose body field or
query parameter `field` lists one of `values` in its `enum`, through a reference or a union too: WordPress
publishes by `status: "publish"`, so `{ key: "publish", field: "status", values: ["publish", "future"] }` gives
`posts.publish` and `pages.publish`. The key applies when the call sends one of those values, in the body or the
query; where the field's default is one of them (a WordPress template), leaving it out publishes too, and the key
always applies. A read that filters by the value gets no key, nor a field of that name without such an enum (a
comment's `status`); a rule no write matches stops generation.

Which flags delete is the CLI's call: read the service's documentation, and count an undocumented flag as a delete.
A flag counts on every method, a GET included: Yandex Disk's upload link is a GET whose `overwrite` replaces a file.
Expand Down
16 changes: 1 addition & 15 deletions src/codegen/discovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@
* Strict like `adaptOpenApi`: an unknown schema keyword, format or parameter location stops generation.
* Effects come from the HTTP verb; a method the verb misjudges is corrected with `generate`'s `overrides`.
*/
import { createHash } from "node:crypto"
import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
import { join } from "node:path"
import type { ApiModel, ApiOperation, ApiSchema, Effect, HttpMethod, SchemaNode } from "./model.js"
import { CodegenError } from "./pipeline.js"
import { sha256, sortKeys } from "./snapshot.js"

type Json = Record<string, unknown>

Expand Down Expand Up @@ -305,20 +305,6 @@ export interface SyncDiscoveryOptions {
fetch?: typeof globalThis.fetch
}

const sha256 = (bytes: string | Buffer): string => createHash("sha256").update(bytes).digest("hex")

/** Google serves the same revision with its keys in a different order each time; arrays keep theirs. */
const sortKeys = (value: unknown): unknown =>
Array.isArray(value)
? value.map(sortKeys)
: object(value)
? Object.fromEntries(
Object.keys(value)
.sort()
.map((key) => [key, sortKeys(value[key])]),
)
: value

const NORMALIZATION = "object keys sorted, 2-space JSON; values and array order unchanged"

/**
Expand Down
15 changes: 1 addition & 14 deletions src/codegen/graphql.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@
* ends in `Delete` or `Archive` deletes. A Relay connection pages as a `cursor`: `after`, `pageInfo.endCursor`.
* SDL is not read: that needs graphql-js, and codegen adds no runtime dependency.
*/
import { createHash } from "node:crypto"
import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
import { join } from "node:path"
import type { ApiModel, ApiOperation, ApiSchema, GraphqlBinding, Pagination, SchemaNode } from "./model.js"
import { CodegenError } from "./pipeline.js"
import { sha256, sortKeys } from "./snapshot.js"

type Json = Record<string, unknown>

Expand Down Expand Up @@ -406,19 +406,6 @@ export interface GraphqlProvenance {
normalization: string
}

const sha256 = (bytes: string | Buffer): string => createHash("sha256").update(bytes).digest("hex")

const sortKeys = (value: unknown): unknown =>
Array.isArray(value)
? value.map(sortKeys)
: object(value)
? Object.fromEntries(
Object.keys(value)
.sort()
.map((key) => [key, sortKeys(value[key])]),
)
: value

const byName = (list: unknown): unknown =>
Array.isArray(list)
? [...list].sort((a, b) => String((a as Json)?.name).localeCompare(String((b as Json)?.name)))
Expand Down
10 changes: 9 additions & 1 deletion src/codegen/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* manifest and a coverage page. Build-time, apart from the small helpers a CLI reads the generated
* files with (`identifier`, `requestSchema`), and format-neutral: it parses no file format and
* adds no runtime dependency. `adaptOpenApi` reads an OpenAPI document and `adaptDiscovery` Google Discovery
* documents the consumer has parsed, and `adaptGraphql` a GraphQL introspection result; `upgradeToOpenApi3` brings Swagger 1.2 and 2.0 to OpenAPI 3 through two optional
* documents the consumer has parsed, and `adaptGraphql` a GraphQL introspection result; `wpJsonToOpenApi` turns WordPress's REST index into OpenAPI; `upgradeToOpenApi3` brings Swagger 1.2 and 2.0 to OpenAPI 3 through two optional
* peer dependencies. `fakeApi` serves the generated manifest as a strict fake for a CLI's tests, and `signInRequirements` with
* `signInPlace` say which sign-in a call needs and where its token goes (Basic included). An adapter from
* Postman or anything else lives in the consumer.
Expand Down Expand Up @@ -111,3 +111,11 @@ export { API_SKILL_GROUPS, API_SKILL_INDEX, type ApiSkillOptions, apiSkillFiles
export { upgradeToOpenApi3 } from "./swagger.js"
export { typesGenerator } from "./typescript.js"
export { type ValibotOptions, valibotGenerator } from "./valibot.js"
export {
readWpJson,
syncWpJson,
type WpJsonOptions,
type WpJsonProvenance,
type WpJsonResult,
wpJsonToOpenApi,
} from "./wp-json.js"
12 changes: 7 additions & 5 deletions src/codegen/manifest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -197,10 +197,12 @@ export const coverageGenerator =
const guarded = model.operations.flatMap((operation) =>
(operation.permissions ?? []).map((permission) => ({ id: operation.id, permission })),
)
const when = ({ body, query }: OperationPermission) =>
[...(body ?? []).map((flag) => `body \`${flag}\``), ...(query ?? []).map((flag) => `query \`${flag}\``)].join(
" or ",
)
const when = ({ body, query, values }: OperationPermission) =>
[
...(body ?? []).map((flag) => `body \`${flag}\` is true`),
...(query ?? []).map((flag) => `query \`${flag}\` is true`),
...Object.entries(values ?? {}).map(([field, listed]) => `\`${field}\` is ${listed.join(" or ")}`),
].join(" or ")
const content = [
`# ${options.title}`,
"",
Expand Down Expand Up @@ -254,7 +256,7 @@ export const coverageGenerator =
"|---|---|---|",
...guarded.map(({ id, permission }) => {
const flags = when(permission)
return `| \`${id}\` | \`${permission.key}\` | ${flags ? `${flags} is true` : "always"} |`
return `| \`${id}\` | \`${permission.key}\` | ${flags || "always"} |`
}),
]
: []),
Expand Down
10 changes: 9 additions & 1 deletion src/codegen/model.ts
Original file line number Diff line number Diff line change
Expand Up @@ -175,13 +175,21 @@ export type Pagination =
/** The answer holds the next page's whole URL. */
| { style: "link"; next: string; items?: string }

/** A key a call must pass: always, or, when `body` or `query` is given, only when one of those flags is `true`. */
/**
* A key a call must pass: always, or, when `body`, `query` or `values` is given, only when one of those flags is `true`
* or one of those fields holds one of its values.
*/
export interface OperationPermission {
key: string
/** Top-level request body fields. */
body?: readonly string[]
/** Query parameters. */
query?: readonly string[]
/**
* A top-level body field or query parameter of this name holding one of these values: `{ status: ["publish"] }`.
* Both places count, as a service that merges them (WordPress) publishes from either.
*/
values?: Readonly<Record<string, readonly string[]>>
}

/** The scheme names an operation needs, each with its OAuth scopes; one requirement of the list is enough. */
Expand Down
71 changes: 66 additions & 5 deletions src/codegen/pipeline.ts
Original file line number Diff line number Diff line change
Expand Up @@ -201,10 +201,22 @@ export interface PermissionRule {
deletingFlags?: readonly string[]
/** Operation ids that make something public, as a share link does: neither a plain write nor a delete. */
shares?: readonly string[]
/**
* A field whose value is the change, not a flag: WordPress publishes by `status: "publish"`. Each gives
* `<group>.<key>` to every write or delete whose body field or query parameter `field` lists one of `values` in its
* `enum`, so a field of the same name that means something else (a comment's `status`) gets no key, nor does a read
* that filters by the value. Where the field's default is one of `values` (a WordPress template), leaving it out
* publishes too, and the key always applies.
*/
valueKeys?: readonly { key: string; field: string; values: readonly string[] }[]
}

/** The top-level property names a body may carry, through references, inheritance, unions and subtypes. */
const bodyFields = (node: SchemaNode, schemas: ReadonlyMap<string, ApiSchema>, seen = new Set<string>()): string[] => {
/** The top-level properties a body may carry, through references, inheritance, unions and subtypes. */
const bodyFields = (
node: SchemaNode,
schemas: ReadonlyMap<string, ApiSchema>,
seen = new Set<string>(),
): [string, SchemaNode][] => {
switch (node.type) {
case "ref": {
const target = schemas.get(node.ref)
Expand All @@ -216,7 +228,7 @@ const bodyFields = (node: SchemaNode, schemas: ReadonlyMap<string, ApiSchema>, s
return [...bodyFields(target.schema, schemas, inner), ...subtypes]
}
case "object":
return Object.keys(node.properties)
return Object.entries(node.properties)
case "union":
case "allOf":
return node.of.flatMap((member) => bodyFields(member, schemas, seen))
Expand All @@ -234,10 +246,58 @@ export const applyPermissionRule = (model: ApiModel, rule: PermissionRule): ApiM
const fields = new Map(
model.operations.map((operation) => [
operation.id,
new Set(operation.requestBody?.schema ? bodyFields(operation.requestBody.schema, schemas) : []),
new Map(operation.requestBody?.schema ? bodyFields(operation.requestBody.schema, schemas) : []),
]),
)
const fieldsOf = (operation: ApiOperation) => fields.get(operation.id) ?? new Set<string>()
const fieldsOf = (operation: ApiOperation) => fields.get(operation.id) ?? new Map<string, SchemaNode>()
/** The enums and defaults of a field, through references and every alternative of a union. */
const valuesIn = (
node: SchemaNode | undefined,
seen = new Set<string>(),
): { enums: unknown[]; defaults: unknown[] } => {
if (!node) return { enums: [], defaults: [] }
const own = {
enums: "enum" in node && node.enum ? [...node.enum] : [],
defaults: node.default === undefined ? [] : [node.default],
}
const inner =
node.type === "ref" && !seen.has(node.ref)
? [valuesIn(schemas.get(node.ref)?.schema, new Set([...seen, node.ref]))]
: node.type === "union" || node.type === "allOf"
? node.of.map((member) => valuesIn(member, seen))
: []
return {
enums: [...own.enums, ...inner.flatMap((one) => one.enums)],
defaults: [...own.defaults, ...inner.flatMap((one) => one.defaults)],
}
}
const valuesOf = (operation: ApiOperation, name: string) => {
const nodes = [
fieldsOf(operation).get(name),
operation.parameters.find((parameter) => parameter.in === "query" && parameter.name === name)?.schema,
].map((node) => valuesIn(node))
return { enums: nodes.flatMap((one) => one.enums), defaults: nodes.flatMap((one) => one.defaults) }
}
const valueKeys = rule.valueKeys ?? []
// A field whose default is one of the values publishes when the call leaves it out: the key then always applies.
const valued = (operation: ApiOperation): OperationPermission[] =>
operation.effect === "read"
? []
: valueKeys.flatMap(({ key, field, values }) => {
const { enums, defaults } = valuesOf(operation, field)
const named = values.filter((value) => enums.includes(value))
if (named.length === 0) return []
return defaults.some((value) => values.includes(value as string))
? [{ key }]
: [{ key, values: { [field]: named } }]
})
const idle = valueKeys.filter(
({ key }) => !model.operations.some((operation) => valued(operation).some((one) => one.key === key)),
)
if (idle.length > 0)
throw new CodegenError(
idle.map(({ field, values }) => `valueKeys: no write lists ${values.join(" or ")} in the enum of "${field}"`),
)
const unused = flags.filter(
(flag) =>
!model.operations.some(
Expand Down Expand Up @@ -267,6 +327,7 @@ export const applyPermissionRule = (model: ApiModel, rule: PermissionRule): ApiM
...(query.length > 0 ? { query } : {}),
})
}
for (const permission of valued(operation)) permissions.push({ ...permission, key: `${group}.${permission.key}` })
return permissions.length > 0 ? { ...operation, permissions } : operation
}),
}
Expand Down
16 changes: 16 additions & 0 deletions src/codegen/snapshot.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
import { createHash } from "node:crypto"

/** The hash a snapshot's `provenance.json` keeps, so a hand edit or a changed file stops generation. */
export const sha256 = (bytes: string | Buffer): string => createHash("sha256").update(bytes).digest("hex")

/** A service may send the same description with its keys in another order each time; arrays keep theirs. */
export const sortKeys = (value: unknown): unknown =>
Array.isArray(value)
? value.map(sortKeys)
: value && typeof value === "object"
? Object.fromEntries(
Object.keys(value)
.sort()
.map((key) => [key, sortKeys((value as Record<string, unknown>)[key])]),
)
: value
Loading
Loading