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
10 changes: 10 additions & 0 deletions changes/feat-api-subgroups.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
### Added

- **The generated `api` group mounts subgroups: `api <group> <command>`.** 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.
37 changes: 34 additions & 3 deletions src/cli/bot/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -38,6 +38,19 @@ export interface ApiCommands {
/** An upload's file, `-` for stdin. */
readBytes?: (command: Command, path: string) => Uint8Array<ArrayBuffer>
execute: (command: Command, operation: ManifestOperation, input: ApiCommandInput) => Promise<void>
/** 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 <command>`. 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 =>
Expand All @@ -51,14 +64,16 @@ export const generatedApiCommand = (api: ApiCommands): Command => {
"--store-token <profile>",
"keep a returned authentication token only in this bot profile's OS keyring; never print it",
)
const subgroups = new Set<Command>()
for (const operation of api.operations) {
const binding =
operation.binding.kind === "http"
? `${operation.binding.method} ${operation.binding.path}`
: 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) {
Expand Down Expand Up @@ -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
}
175 changes: 175 additions & 0 deletions src/cli/service-api-groups.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, string> = {}) => {
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 <group> <command> 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")
})
})
Loading
Loading