From 57b97972aa2fc8455c98d932da28dabdac98b779 Mon Sep 17 00:00:00 2001 From: leemour Date: Thu, 19 Nov 2026 05:23:11 +0100 Subject: [PATCH] feat(cli): mount generated api operations in subgroups, api An operation whose manifest names a group (cli-base names.groups) is mounted as api , the command without the repeated group word, and checked against its path: api.contacts.list, with api.contacts covering the group. alsoChecks, the delete defaults, api list (path and group) and api show (quoted path, old name or id) follow the path. A profile that still names the old flat key api.contacts-list keeps its hold on that one command: the key is known, checked beside the new one through the keyed guard (deny refuses, ask asks, readonly stops a write), lifts nothing with allow, and warns to rename it. The old path stops working (WC-CMD-8). A manifest without groups mounts flat as before. Co-Authored-By: Claude Opus 5.5 --- changes/feat-api-subgroups.md | 10 ++ src/cli/bot/api.ts | 37 +++++- src/cli/service-api-groups.test.ts | 175 +++++++++++++++++++++++++++++ src/cli/service-api.ts | 96 +++++++++++----- 4 files changed, 288 insertions(+), 30 deletions(-) create mode 100644 changes/feat-api-subgroups.md create mode 100644 src/cli/service-api-groups.test.ts diff --git a/changes/feat-api-subgroups.md b/changes/feat-api-subgroups.md new file mode 100644 index 000000000..e0baed2e4 --- /dev/null +++ b/changes/feat-api-subgroups.md @@ -0,0 +1,10 @@ +### Added + +- **The generated `api` group mounts subgroups: `api `.** An operation whose manifest names a `group` + (cli-base's `names.groups`) is mounted under it without the repeated word, so `contacts-list` in `contacts` is + `api contacts list`, checked against `api.contacts.list`; `api.contacts` covers the whole group. A profile that still + names the old flat key `api.contacts-list` keeps its hold on that one command: it is checked beside the new key, from + the command line and over MCP, warns to rename it, and only ever tightens. The old path `api contacts-list` stops + working. `api show` takes the path (quoted, `api show "contacts list"`), the old name or the operation id, and `api list` prints the path and the group. + A manifest without groups mounts flat, as before, so nothing changes until a CLI regenerates with groups and + releases the move as a breaking change. diff --git a/src/cli/bot/api.ts b/src/cli/bot/api.ts index 582f1bbbd..cc022e7b1 100644 --- a/src/cli/bot/api.ts +++ b/src/cli/bot/api.ts @@ -3,7 +3,7 @@ import type { ManifestOperation, SchemaNode } from "@wirecat/cli-base/codegen" import { annotate } from "@wirecat/cli-base/commands" import { Command, Option } from "commander" import { secretInput } from "../../runs/run-context.js" -import { REMOTE_READ, REMOTE_WRITE } from "../effects.js" +import { NO_EFFECTS, REMOTE_READ, REMOTE_WRITE } from "../effects.js" import { apiFlagOf, apiJson, @@ -38,6 +38,19 @@ export interface ApiCommands { /** An upload's file, `-` for stdin. */ readBytes?: (command: Command, path: string) => Uint8Array execute: (command: Command, operation: ManifestOperation, input: ApiCommandInput) => Promise + /** Called with each operation's command once it is built, before it is mounted. */ + configure?: (command: Command, operation: ManifestOperation) => void +} + +/** + * The words after `api`: `contacts-list` in the group `contacts` is `contacts list`, `move-page` in `pages` keeps its + * name, and an operation without a group stays `api `. The same rule as cli-base's `apiCommandPath`; `group` + * is read as optional, so a manifest generated before groups mounts flat, as it always did. + */ +export const apiPathOf = (operation: ManifestOperation): string[] => { + const { command, group } = operation as ManifestOperation & { group?: string } + if (!group) return [command] + return [group, command.startsWith(`${group}-`) ? command.slice(group.length + 1) : command] } const scalarOf = (value: unknown): string | undefined => @@ -51,6 +64,7 @@ export const generatedApiCommand = (api: ApiCommands): Command => { "--store-token ", "keep a returned authentication token only in this bot profile's OS keyring; never print it", ) + const subgroups = new Set() for (const operation of api.operations) { const binding = operation.binding.kind === "http" @@ -58,7 +72,8 @@ export const generatedApiCommand = (api: ApiCommands): Command => { : operation.binding.kind === "graphql" ? `${operation.binding.operation} ${operation.binding.field}` : operation.binding.name - const command = annotate(new Command(operation.command), { + const path = apiPathOf(operation) + const command = annotate(new Command(path.at(-1)), { effects: operation.effect === "read" ? REMOTE_READ : REMOTE_WRITE, }).description(`${operation.summary ?? operation.id} — ${operation.effect} (${binding})`) for (const parameter of operation.parameters) { @@ -145,7 +160,23 @@ export const generatedApiCommand = (api: ApiCommands): Command => { if (body !== undefined) input.body = body await api.execute(this, operation, input) }) - group.addCommand(command) + api.configure?.(command, operation) + const [first] = path + const taken = group.commands.find((one) => one.name() === first) + // A command and a group of one name would put an operation under another's command, or answer with the wrong one. + if (taken && (path.length === 1 || !subgroups.has(taken))) + throw new CliError("configuration_error", `api ${first} is both a group and an operation: rename one`) + if (path.length === 1 || first === undefined) { + group.addCommand(command) + continue + } + const subgroup = + taken ?? annotate(new Command(first), { effects: NO_EFFECTS }).description(`the ${first} operations`) + if (!taken) { + subgroups.add(subgroup) + group.addCommand(subgroup) + } + subgroup.addCommand(command) } return group } diff --git a/src/cli/service-api-groups.test.ts b/src/cli/service-api-groups.test.ts new file mode 100644 index 000000000..7b0e959f8 --- /dev/null +++ b/src/cli/service-api-groups.test.ts @@ -0,0 +1,175 @@ +import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { captureStreams } from "@wirecat/cli-base" +import type { ManifestOperation } from "@wirecat/cli-base/codegen" +import { hostFetch } from "@wirecat/cli-base/http" +import { describe, expect, it } from "vitest" +import { generatedApiCommand } from "./bot/api.js" +import { commandPermissions } from "./permission-keys.js" +import { run } from "./program.js" +import { serviceApiPermissions } from "./service-api.js" +import type { ServiceApiManifest } from "./service-api-manifest.js" +import { settingsFor } from "./settings.js" +import { serviceApiCommand } from "./shared-command-exports.js" + +const app = { + command: "crm", + appName: "crm-cli", + envPrefix: "CRM", + description: "a CRM", + version: "1.0.0", + messenger: false, +} + +type Operation = ManifestOperation & { group?: string } + +const operation = (command: string, method: "GET" | "POST" | "DELETE", path: string, group?: string): Operation => ({ + id: command, + command, + ...(group ? { group } : {}), + binding: { kind: "http", method, path }, + effect: method === "GET" ? "read" : method === "DELETE" ? "destructive" : "write", + tags: [], + parameters: [], + ...(method === "DELETE" ? { permissions: [{ key: "records.delete" }] } : {}), +}) + +const operations: Operation[] = [ + operation("contacts-list", "GET", "/contacts", "contacts"), + operation("contacts-create", "POST", "/contacts", "contacts"), + operation("contacts-delete", "DELETE", "/contacts/1", "contacts"), + operation("move-page", "POST", "/pages/move", "pages"), + operation("pages-list", "GET", "/pages", "pages"), + operation("status", "GET", "/status"), +] + +const manifest: ServiceApiManifest = { operations, servers: [{ url: "https://api.crm.test" }] } + +const fixture = (saved: Record = {}) => { + const root = mkdtempSync(join(tmpdir(), "service-api-groups-")) + const env = { + CRM_CONFIG_DIR: join(root, "config"), + CRM_STATE_DIR: join(root, "state"), + MESSAGING_STORE: join(root, "w.db"), + } + mkdirSync(env.CRM_CONFIG_DIR, { recursive: true }) + writeFileSync(join(env.CRM_CONFIG_DIR, "config.json"), JSON.stringify({ profiles: { work: { permissions: saved } } })) + const sent: string[] = [] + const configuration = settingsFor(app, { permissions: commandPermissions(serviceApiPermissions({ manifest })) }) + const definition = { + app, + configuration, + commands: () => [ + serviceApiCommand({ + manifest, + app, + configuration, + service: "CRM", + fetch: () => + hostFetch({ + hosts: ["api.crm.test"], + fetch: async (input, init) => { + sent.push(`${init?.method ?? "GET"} ${new URL(String(input)).pathname}`) + return Response.json({ ok: true }) + }, + }), + schemas: async () => ({}), + definitions: async () => ({}), + }), + ], + } + const cli = async (...args: string[]) => { + const streams = captureStreams() + const code = await run(args, definition, { streams, env, tty: false }) + const out = streams.stdout.join("") + const err = streams.stderr.join("") + return { + code, + json: out.startsWith("{") ? JSON.parse(out) : undefined, + // A warning may come first on stderr. + error: err.includes('{"error"') + ? (JSON.parse(err.slice(err.indexOf('{"error"'))).error as { code: string; message: string }) + : undefined, + err, + } + } + return { cli, sent } +} + +describe("api subgroups", () => { + it("mounts a grouped operation as api and keeps the rest flat; the old path is gone", async () => { + const { cli, sent } = fixture() + expect((await cli("work", "api", "contacts", "list", "--json")).code).toBe(0) + expect((await cli("work", "api", "pages", "move-page", "--json")).code).toBe(0) + expect((await cli("work", "api", "status", "--json")).code).toBe(0) + expect(sent).toEqual(["GET /contacts", "POST /pages/move", "GET /status"]) + expect((await cli("work", "api", "contacts-list", "--json")).code).not.toBe(0) + expect(sent).toHaveLength(3) + }) + + it("lists the path and the group, and shows an operation by its path, its old name or its id", async () => { + const { cli } = fixture() + const { json } = await cli("work", "api", "list", "--json") + expect(json.items.map((one: { command: string; group: string | null }) => [one.command, one.group])).toEqual([ + ["contacts list", "contacts"], + ["contacts create", "contacts"], + ["contacts delete", "contacts"], + ["pages move-page", "pages"], + ["pages list", "pages"], + ["status", null], + ]) + for (const name of ["contacts list", "contacts-list"]) + expect((await cli("work", "api", "show", name, "--json")).json.item.operation.id).toBe("contacts-list") + }) + + it("checks the path as the key, so one key covers a whole group", async () => { + const { cli, sent } = fixture({ "api.contacts": "deny" }) + expect((await cli("work", "api", "contacts", "list", "--json")).error).toMatchObject({ code: "permission_error" }) + expect((await cli("work", "api", "contacts", "create", "--json")).error).toMatchObject({ + code: "permission_error", + }) + expect((await cli("work", "api", "pages", "list", "--json")).code).toBe(0) + expect(sent).toEqual(["GET /pages"]) + }) + + it("keeps an old flat key as an alias that only tightens, and says to rename it", async () => { + const denied = fixture({ "api.contacts-list": "deny" }) + const refused = await denied.cli("work", "api", "contacts", "list", "--json") + expect(refused.error).toMatchObject({ code: "permission_error" }) + expect(refused.err).toContain("rename it to api.contacts.list") + expect(denied.sent).toEqual([]) + + const loose = fixture({ "api.contacts": "deny", "api.contacts-list": "allow" }) + expect((await loose.cli("work", "api", "contacts", "list", "--json")).error).toMatchObject({ + code: "permission_error", + }) + expect(loose.sent).toEqual([]) + + const readonly = fixture({ "api.contacts-list": "readonly", "api.contacts-create": "readonly" }) + expect((await readonly.cli("work", "api", "contacts", "list", "--json")).code).toBe(0) + expect((await readonly.cli("work", "api", "contacts", "create", "--json")).error).toMatchObject({ + code: "permission_error", + }) + expect(readonly.sent).toEqual(["GET /contacts"]) + }) + + it("puts the new key on a delete's default and shows the old key in --dry-run", () => { + const permissions = serviceApiPermissions({ manifest }) + expect(permissions.defaults["api.contacts.delete"]).toBe("ask") + expect(permissions.defaults["api.contacts-delete"]).toBeUndefined() + expect(permissions.extra).toContain("api.contacts-list") + expect(permissions.alsoChecks(["api", "contacts", "delete"])).toEqual([ + "records.delete", + { key: "api.contacts-delete", when: "while a profile still names this old key" }, + ]) + expect(permissions.alsoChecks(["api", "status"])).toEqual([]) + }) + + it("refuses a group and an operation of one name", () => { + const clash = [operation("contacts", "GET", "/contacts"), ...operations] + expect(() => + generatedApiCommand({ operations: clash, checkParameter: () => undefined, execute: async () => {} }), + ).toThrow("api contacts is both a group and an operation") + }) +}) diff --git a/src/cli/service-api.ts b/src/cli/service-api.ts index 8ca146adb..7ec9e5cb1 100644 --- a/src/cli/service-api.ts +++ b/src/cli/service-api.ts @@ -12,7 +12,7 @@ import type { Level, PermissionKey } from "../sends/permissions.js" import { levelFor } from "../sends/permissions.js" import { newOperationId } from "../sends/send-id.js" import { refusedPlace } from "../sends/upload.js" -import { type ApiCommandInput, generatedApiCommand } from "./bot/api.js" +import { type ApiCommandInput, apiPathOf, generatedApiCommand } from "./bot/api.js" import { type HttpApiRequest, httpApiExchange, httpApiRequest, unsendableBody } from "./bot/api-http.js" import { apiJson, @@ -113,7 +113,20 @@ const MOST_PAGES = 500 const isObject = (value: unknown): value is Record => !!value && typeof value === "object" && !Array.isArray(value) -const keyOf = (operation: ManifestOperation): PermissionKey => `api.${operation.command}` +const keyOf = (operation: ManifestOperation): PermissionKey => ["api", ...apiPathOf(operation)].join(".") + +/** `contacts list`: what follows `api` on the command line. */ +const pathOf = (operation: ManifestOperation): string => apiPathOf(operation).join(" ") + +/** + * The key a grouped operation had while `api` was flat, `api.contacts-list`. A profile that still names it keeps its + * hold on that one command: checked beside the new key, it only ever tightens. A group never takes an old command's + * name (the generator refuses it), so the old key never reaches past its command. + */ +const formerKeyOf = (operation: ManifestOperation): PermissionKey | undefined => { + const former = `api.${operation.command}` + return former === keyOf(operation) ? undefined : former +} const permissionsOf = (operation: ManifestOperation): readonly OperationPermission[] => operation.permissions ?? [] @@ -195,18 +208,29 @@ export const serviceApiPermissions = ( extra: readonly PermissionKey[] } => { const checks = new Map() - for (const operation of input.manifest.operations) - checks.set(operation.command, [ + const former: PermissionKey[] = [] + for (const operation of input.manifest.operations) { + const old = formerKeyOf(operation) + if (old) former.push(old) + checks.set(pathOf(operation), [ ...permissionsOf(operation).map((permission) => { const when = whenOf(permission) return when === undefined ? permission.key : { key: permission.key, when } }), ...(input.bodyPermissions?.[operation.command] ?? []).map(({ key, when }) => ({ key, when })), + ...(old ? [{ key: old, when: "while a profile still names this old key" }] : []), ]) - const keys = [...new Set([...checks.values()].flat().map((one) => (typeof one === "string" ? one : one.key)))] + } + const keys = [ + ...new Set( + [...checks.values()] + .flat() + .flatMap((one) => (typeof one === "string" ? [one] : former.includes(one.key) ? [] : [one.key])), + ), + ] return { - extra: keys, - alsoChecks: (path) => (path[0] === "api" && path.length === 2 ? (checks.get(path[1] ?? "") ?? []) : []), + extra: [...keys, ...former], + alsoChecks: (path) => (path[0] === "api" ? (checks.get(path.slice(1).join(" ")) ?? []) : []), defaults: { ...Object.fromEntries(keys.map((key) => [key, "ask" as const])), ...Object.fromEntries( @@ -217,7 +241,8 @@ export const serviceApiPermissions = ( } const rowOf = (operation: ManifestOperation) => ({ - command: operation.command, + command: pathOf(operation), + group: apiPathOf(operation).length > 1 ? apiPathOf(operation)[0] : null, method: operation.binding.kind === "http" ? operation.binding.method : operation.binding.kind === "graphql" ? "POST" : "", path: @@ -283,9 +308,10 @@ const serviceApiCore = (options: ServiceApiOptions) => { }) const operationOf = (name: string): ManifestOperation => { - const found = operations.find((operation) => operation.command === name || operation.id === name) + const named = (one: ManifestOperation) => pathOf(one) === name || one.command === name || one.id === name + const found = operations.find(named) if (found) return found - const id = manifest.operations.find((one) => one.command === name || one.id === name)?.id ?? name + const id = manifest.operations.find(named)?.id ?? name const why = options.excluded?.find((one) => one.id === name) ?? left.find((one) => one.id === id) throw new CliError( "not_found", @@ -378,12 +404,26 @@ const serviceApiCore = (options: ServiceApiOptions) => { } } - return { operations, left, baseUrlOf, defaults, exchange, operationOf, readsFreely, signed, write } + /** The old flat key, when the profile names it: on a read only its refusal or its question applies. */ + const formerKeys = (command: Command, operation: ManifestOperation): PermissionKey[] => { + const former = formerKeyOf(operation) + if (!former) return [] + const { settings, renderer } = baseContext(command, configuration.resolveSettings) + const level = settings.permissions[former] + if (level === undefined) return [] + renderer.warn( + `permissions name ${former}, the old key of api ${pathOf(operation)}: rename it to ${keyOf(operation)}`, + ) + return operation.effect === "read" && level !== "deny" && level !== "ask" ? [] : [former] + } + + return { operations, left, baseUrlOf, defaults, exchange, formerKeys, operationOf, readsFreely, signed, write } } export const serviceApiCommand = (options: ServiceApiOptions): Command => { const { app, configuration } = options - const { operations, baseUrlOf, exchange, operationOf, readsFreely, signed, write } = serviceApiCore(options) + const { operations, baseUrlOf, exchange, formerKeys, operationOf, readsFreely, signed, write } = + serviceApiCore(options) const send = async (command: Command, operation: ManifestOperation, request: HttpApiRequest) => (await exchange(command, operation, request)).answer let schemas: Readonly> | undefined @@ -391,6 +431,9 @@ export const serviceApiCommand = (options: ServiceApiOptions): Command => { if (!schemas) throw new CliError("configuration_error", "the api schemas were not loaded before the command ran") return schemas } + const load = async () => { + schemas ??= await options.schemas() + } /** Every page, in one run; a next page outside the server's address is never sent the sign-in. */ const allPages = async (command: Command, operation: ManifestOperation, input: ApiCommandInput) => { const pagination = operation.pagination as NonNullable @@ -438,7 +481,7 @@ export const serviceApiCommand = (options: ServiceApiOptions): Command => { renderAnswer( command, outputFor(command), - listOf(`api ${operation.command}`, { items, limit: items.length, has_more: false }), + listOf(`api ${pathOf(operation)}`, { items, limit: items.length, has_more: false }), ) } @@ -461,8 +504,13 @@ export const serviceApiCommand = (options: ServiceApiOptions): Command => { refuseOwnFiles(command, path) return readApiBytes(path) }, + configure: (command, operation) => { + if (operation.pagination && !operation.parameters.some(({ name }) => name === "all")) + command.option("--all", "read every page, as the API pages it") + command.hook("preAction", load) + }, execute: async (command, operation, input) => { - const extra = serviceApiKeys(options, operation, input) + const extra = [...serviceApiKeys(options, operation, input), ...formerKeys(command, operation)] const read = readsFreely(command, operation, extra) if (operation.pagination && command.opts<{ all?: unknown }>().all === true) { if (!read) @@ -500,10 +548,12 @@ export const serviceApiCommand = (options: ServiceApiOptions): Command => { const show = annotate(new Command("show"), { effects: NO_EFFECTS, - examples: [`${app.command} api show ${operations[0]?.command ?? ""} --json`], + examples: [ + `${app.command} api show ${operations[0] ? JSON.stringify(pathOf(operations[0])) : ""} --json`, + ], }) .description(`show one operation's parameters and request schema, without calling ${options.service}`) - .argument("", "the operation, as api list prints it") + .argument("", "the operation as api list prints it (quoted), its old name, or its operation id") .action(async function (this: Command, name: string) { const operation = operationOf(name) const definitions = await options.definitions() @@ -519,15 +569,7 @@ export const serviceApiCommand = (options: ServiceApiOptions): Command => { `the raw ${options.service} API, one command per operation of its OpenAPI document`, ) group.addCommand(list).addCommand(show) - const load = async () => { - schemas ??= await options.schemas() - } - for (const child of generated.commands) { - const operation = operations.find((one) => one.command === child.name()) - if (operation?.pagination && !operation.parameters.some(({ name }) => name === "all")) - child.option("--all", "read every page, as the API pages it") - group.addCommand(child.hook("preAction", load)) - } + for (const child of [...generated.commands]) group.addCommand(child) return group } @@ -565,7 +607,7 @@ const writerBody = ( * can be asked. A read that no key guards goes through `serviceApiCall`. */ export const serviceApiWriter = (options: ServiceApiOptions): ServiceApiWrite => { - const { baseUrlOf, operationOf, signed, write } = serviceApiCore(options) + const { baseUrlOf, formerKeys, operationOf, signed, write } = serviceApiCore(options) return async (command, name, input, { confirmed } = {}) => { const operation = operationOf(name) // The api group offers only declared parameters; code must not reach further, as WordPress's `_method` turns a @@ -607,6 +649,6 @@ export const serviceApiWriter = (options: ServiceApiOptions): ServiceApiWrite => operation, httpApiRequest(operation, writerBody(operation, input, schemas), baseUrlOf(command)), ) - return write(command, operation, extra, request, confirmed) + return write(command, operation, [...extra, ...formerKeys(command, operation)], request, confirmed) } }