From 86aac8db8eb9512c7b274720a24e23f2a74f0089 Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 22:48:53 +0100 Subject: [PATCH 1/2] feat(cli): send a GraphQL operation through the api group and serviceApiCall L2 of the source-manifest plan, on cli-base 0.115.0's graphql binding. A call is one POST of the document graphqlDocument builds; the variables are --body with each flag over it, read by its schema, and the request schema sees them merged. errors[] fails even at HTTP 200, named by extensions.code, never by the message; the answer is data.. --all pages by pageInfo through the existing cursor style. ApiCommandInput.selection lets a source ask for more than the generated selection. Co-Authored-By: Claude Opus 5.5 --- changes/feat-graphql-executor.md | 12 ++ package.json | 4 +- pnpm-lock.yaml | 16 +- src/cli/bot/api-http.ts | 116 ++++++++++++++- src/cli/bot/api.ts | 15 +- src/cli/service-api-graphql.test.ts | 220 ++++++++++++++++++++++++++++ src/cli/service-api-manifest.ts | 11 +- src/cli/service-api.ts | 9 +- test/fixtures/graphql-tracker.ts | 165 +++++++++++++++++++++ 9 files changed, 544 insertions(+), 24 deletions(-) create mode 100644 changes/feat-graphql-executor.md create mode 100644 src/cli/service-api-graphql.test.ts create mode 100644 test/fixtures/graphql-tracker.ts diff --git a/changes/feat-graphql-executor.md b/changes/feat-graphql-executor.md new file mode 100644 index 000000000..9108f0384 --- /dev/null +++ b/changes/feat-graphql-executor.md @@ -0,0 +1,12 @@ +### Added + +- **The `api` group and `serviceApiCall` send a GraphQL operation** of a manifest that cli-base 0.115.0 generates + from a schema. Each call is one POST of the document `graphqlDocument` builds; the variables are `--body` as one + object with each flag over it, read by its schema (a number, true or false, JSON for an input object), and a name + the operation does not declare is refused before anything is sent. `errors[]` is a failure even at HTTP 200, named + by its `extensions.code` and never by the service's message; the answer is `data.`. `--all` pages by + `pageInfo`. `ApiCommandInput.selection` gives a source a deeper selection than the generated one. + +### Changed — may break callers + +- **cli-core needs `@wirecat/cli-base` 0.115.0 or later**, whose manifest has the `graphql` binding. diff --git a/package.json b/package.json index 256c5a257..879575f45 100644 --- a/package.json +++ b/package.json @@ -313,7 +313,7 @@ "@types/pngjs": "6.0.5", "@types/ssh2": "1.15.5", "@vitest/coverage-v8": "^5.0.5", - "@wirecat/cli-base": "0.112.0", + "@wirecat/cli-base": "0.115.0", "@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0", "ajv": "8.17.1", "commander": "15.0.0", @@ -337,7 +337,7 @@ }, "peerDependencies": { "@napi-rs/canvas": ">=0.1.69 <2", - "@wirecat/cli-base": ">=0.112.0 <1.0.0", + "@wirecat/cli-base": ">=0.115.0 <1.0.0", "commander": ">=15", "mysql2": "^3.24.6", "pg": "^8.23.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0b9068b9b..dbbc49cae 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -177,11 +177,11 @@ importers: specifier: ^5.0.5 version: 5.0.5(vitest@5.0.5) '@wirecat/cli-base': - specifier: 0.112.0 - version: 0.112.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5) + specifier: 0.115.0 + version: 0.115.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5) '@wirecat/cli-core-legacy-tags': specifier: npm:@wirecat/cli-core@0.414.0 - version: '@wirecat/cli-core@0.414.0(@napi-rs/canvas@1.0.13)(@wirecat/cli-base@0.112.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5))(commander@15.0.0)(typescript@7.0.2)(zod@4.6.7)' + version: '@wirecat/cli-core@0.414.0(@napi-rs/canvas@1.0.13)(@wirecat/cli-base@0.115.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5))(commander@15.0.0)(typescript@7.0.2)(zod@4.6.7)' ajv: specifier: 8.17.1 version: 8.17.1 @@ -1373,8 +1373,8 @@ packages: '@wasm-audio-decoders/opus-ml@0.0.3': resolution: {integrity: sha512-SEeTmk0eb3q5etJA/NHCRWW6BivTx9tqvNTmG0kg2ynuATEQRUZnwQE6Ibvl1BBvqIGHqI57+qyJMWmJBwb5XQ==} - '@wirecat/cli-base@0.112.0': - resolution: {integrity: sha512-TMk4qGU/C4vb3rEphKTkH6mAriIDXW4qnmReH37+TLp0f9ngDBJPZfNqVN5UlG1rKqWOCzomk+jY2Ynf5HUnAQ==} + '@wirecat/cli-base@0.115.0': + resolution: {integrity: sha512-+Q2gV7+Vrc+1g8Uet6Ep3Y4SxlKH6iQdNTu0dcrx3WT2mgXpn+99YvqNjZElGEAShMnsGyqgwGZHwXvFmUZang==} engines: {node: '>=22'} hasBin: true peerDependencies: @@ -3766,7 +3766,7 @@ snapshots: dependencies: '@wasm-audio-decoders/common': 9.0.7 - '@wirecat/cli-base@0.112.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5)': + '@wirecat/cli-base@0.115.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5)': dependencies: '@valibot/to-json-schema': 1.8.0(valibot@1.5.0(typescript@7.0.2)) cli-table3: 0.6.5 @@ -3792,7 +3792,7 @@ snapshots: '@wirecat/cli-core-sqlite@1.1.0': {} - '@wirecat/cli-core@0.414.0(@napi-rs/canvas@1.0.13)(@wirecat/cli-base@0.112.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5))(commander@15.0.0)(typescript@7.0.2)(zod@4.6.7)': + '@wirecat/cli-core@0.414.0(@napi-rs/canvas@1.0.13)(@wirecat/cli-base@0.115.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5))(commander@15.0.0)(typescript@7.0.2)(zod@4.6.7)': dependencies: '@anthropic-ai/sdk': 0.131.0(zod@4.6.7) '@bomb.sh/tab': 0.0.22(commander@15.0.0) @@ -3800,7 +3800,7 @@ snapshots: '@modelcontextprotocol/server': 2.3.0 '@resvg/resvg-js': 2.6.2 '@valibot/to-json-schema': 1.8.0(valibot@1.5.0(typescript@7.0.2)) - '@wirecat/cli-base': 0.112.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5) + '@wirecat/cli-base': 0.115.0(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5) '@wirecat/cli-core-onnx': 1.0.1 '@wirecat/cli-core-sqlite': 1.0.1 '@xmldom/xmldom': 0.9.12 diff --git a/src/cli/bot/api-http.ts b/src/cli/bot/api-http.ts index 4f7993fca..0f5a6f12a 100644 --- a/src/cli/bot/api-http.ts +++ b/src/cli/bot/api-http.ts @@ -1,12 +1,12 @@ -import { CliError, wallClock } from "@wirecat/cli-base" -import type { ManifestOperation } from "@wirecat/cli-base/codegen" +import { CliError, type ErrorCode, wallClock } from "@wirecat/cli-base" +import { type GraphqlBinding, graphqlDocument, type ManifestOperation } from "@wirecat/cli-base/codegen" import { type FetchLike, providerWaitMs, readJsonResponse, statusToCode } from "@wirecat/cli-base/http" import type { Command } from "commander" import { providerRequest } from "../command-runs.js" import { outputFor } from "../context.js" import { itemOf, renderAnswer } from "../envelope.js" import type { ApiCommandInput } from "./api.js" -import { parseApiJson, sendsBytes } from "./api-input.js" +import { apiJson, parseApiJson, sendsBytes } from "./api-input.js" export interface HttpApiRequest { method: string @@ -66,6 +66,7 @@ export const httpApiRequest = ( baseUrl: string, ): HttpApiRequest => { const { binding } = operation + if (binding.kind === "graphql") return graphqlRequest(operation, binding, input, baseUrl) if (binding.kind !== "http") throw new CliError("configuration_error", `${operation.command} is not an HTTP operation`) if (unsendableBody(operation)) @@ -107,9 +108,114 @@ export const httpApiRequest = ( return { method: binding.method, url, headers, ...(body === undefined ? {} : { body }) } } +/** + * A GraphQL operation's variables: the body's (`--body`, all of them as one object) with each flag over it, read by + * the variable's schema. A name the operation does not declare is refused before anything is sent. + */ +export const graphqlVariables = ( + operation: ManifestOperation, + body: string | undefined, + fields: Readonly>, +): Record => { + const { binding } = operation + if (binding.kind !== "graphql") + throw new CliError("configuration_error", `${operation.command} is not a GraphQL operation`) + const given = body?.trim() ? parseApiJson(body) : {} + if (given === null || typeof given !== "object" || Array.isArray(given)) + throw new CliError("validation_error", `${operation.command} takes its variables as one JSON object`, { + sent: false, + }) + const variables: Record = { ...(given as Record) } + for (const [name, raw] of Object.entries(fields)) { + const schema = operation.parameters.find((one) => one.in === "body" && one.name === name)?.schema + variables[name] = flagValue(operation, name, raw, schema?.type) + } + const unknown = Object.keys(variables).filter((name) => !(name in binding.variables)) + if (unknown.length > 0) + throw new CliError("validation_error", `${operation.command} has no variable ${unknown.join(", ")}`, { + sent: false, + }) + return variables +} + +const flagValue = (operation: ManifestOperation, name: string, raw: string, type: string | undefined): unknown => { + if (type === "integer" || type === "number") { + const number = Number(raw) + if (raw.trim() === "" || !Number.isFinite(number)) + throw new CliError("validation_error", `--${name} of ${operation.command} takes a number`, { sent: false }) + return number + } + if (type === "boolean") { + if (raw !== "true" && raw !== "false") + throw new CliError("validation_error", `--${name} of ${operation.command} takes true or false`, { sent: false }) + return raw === "true" + } + if (type === "object" || type === "array") return parseApiJson(raw) + // An input object or a list given as JSON; an enum's value, behind a ref too, is a bare word. + if (type === "ref" && /^\s*[{["]/.test(raw)) return parseApiJson(raw) + return raw +} + +/** One GraphQL operation as a POST of its one document to the endpoint, with its variables. */ +const graphqlRequest = ( + operation: ManifestOperation, + binding: GraphqlBinding, + input: ApiCommandInput, + baseUrl: string, +): HttpApiRequest => { + const variables = graphqlVariables(operation, input.body, input.fields) + const headers = new Headers(input.headers) + headers.set("accept", "application/json") + headers.set("content-type", "application/json") + const query = graphqlDocument(binding, input.selection) + return { method: "POST", url: new URL(baseUrl), headers, body: apiJson({ query, variables }) } +} + /** `/v1/pages/{page_id}` → `/v1/pages/:page_id`: the run record keeps the template, never an id. */ const templateOf = (path: string): string => path.replace(/\{([^}]+)\}/g, ":$1") +/** What the run record names a request by: the path template, or a GraphQL operation's root field. */ +const endpointOf = (operation: ManifestOperation): string => + operation.binding.kind === "http" + ? templateOf(operation.binding.path) + : operation.binding.kind === "graphql" + ? `${operation.binding.operation} ${operation.binding.field}` + : "" + +// Common GraphQL server codes (Apollo's names) as the CLI's; any other is the provider's. +const GRAPHQL_CODES: Readonly> = { + UNAUTHENTICATED: "authentication_error", + AUTHENTICATION_ERROR: "authentication_error", + FORBIDDEN: "permission_error", + RATELIMITED: "rate_limited", + BAD_USER_INPUT: "validation_error", + GRAPHQL_VALIDATION_FAILED: "validation_error", + INVALID_INPUT: "validation_error", +} + +/** + * A GraphQL answer comes with HTTP 200 even when it failed: `errors[]` is the failure, named by its first + * `extensions.code`, never by the service's own message (WC-SECR-6). Otherwise the answer is `data.`. + */ +const graphqlAnswer = (service: string, operation: ManifestOperation, answer: unknown): unknown => { + const { binding } = operation + if (binding.kind !== "graphql") return answer + const { data, errors } = (answer ?? {}) as { data?: Record | null; errors?: unknown } + if (Array.isArray(errors) && errors.length > 0) { + const code = (errors[0] as { extensions?: { code?: unknown } } | null)?.extensions?.code + const known = typeof code === "string" ? GRAPHQL_CODES[code.toUpperCase()] : undefined + const writes = operation.effect !== "read" + throw new CliError( + (known ?? "provider_error") as ErrorCode, + `${service} refused ${operation.command}${typeof code === "string" ? ` (${code})` : ""}` + + (writes && data?.[binding.field] != null ? "; part of it may have been done, check before repeating" : ""), + ) + } + if (!data || !(binding.field in data)) + throw new CliError("invalid_response", `${service} answered ${operation.command} without data.${binding.field}`) + return data[binding.field] +} + const answerOf = async (response: Response, maxBytes: number): Promise => { if (response.status === 204 || !response.body || response.headers.get("content-length") === "0") return {} return readJsonResponse(response, { maxBytes }) @@ -126,7 +232,7 @@ export const httpApiSend = (options: HttpApiSendOptions) => async (command: Command, operation: ManifestOperation, request: HttpApiRequest): Promise => { const writes = operation.effect !== "read" - const template = templateOf(operation.binding.kind === "http" ? operation.binding.path : "") + const template = endpointOf(operation) const end = providerRequest(`${request.method} ${template}`, undefined, { method: request.method, endpointTemplate: template, @@ -164,7 +270,7 @@ export const httpApiSend = throw failed } end({ status }) - return answer + return graphqlAnswer(options.service, operation, answer) } /** diff --git a/src/cli/bot/api.ts b/src/cli/bot/api.ts index 26cb03741..30587407f 100644 --- a/src/cli/bot/api.ts +++ b/src/cli/bot/api.ts @@ -4,7 +4,8 @@ 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 { apiFlagOf, apiOptionKey, readApiBody, readApiBytes, sendsBytes } from "./api-input.js" +import { graphqlVariables } from "./api-http.js" +import { apiFlagOf, apiJson, apiOptionKey, readApiBody, readApiBytes, sendsBytes } from "./api-input.js" export interface ApiCommandInput { path: Record @@ -16,6 +17,8 @@ export interface ApiCommandInput { bytes?: Uint8Array bodySource?: "argument" | "stdin" | "file" tokenProfile?: string + /** A GraphQL operation's selection in place of its default, for a source that needs more than one level. */ + selection?: string } export interface ApiCommands { @@ -45,7 +48,9 @@ export const generatedApiCommand = (api: ApiCommands): Command => { const binding = operation.binding.kind === "http" ? `${operation.binding.method} ${operation.binding.path}` - : operation.binding.name + : operation.binding.kind === "graphql" + ? `${operation.binding.operation} ${operation.binding.field}` + : operation.binding.name const command = annotate(new Command(operation.command), { effects: operation.effect === "read" ? REMOTE_READ : REMOTE_WRITE, }).description(`${operation.summary ?? operation.id} — ${operation.effect} (${binding})`) @@ -123,7 +128,11 @@ export const generatedApiCommand = (api: ApiCommands): Command => { const text = (api.readBody ?? ((_command, body) => readApiBody(body)))(this, options) if (options.body !== undefined) input.bodySource = options.body === "-" ? "stdin" : "argument" else if (options.bodyFile !== undefined) input.bodySource = options.bodyFile === "-" ? "stdin" : "file" - const body = operation.binding.kind === "rpc" ? text : api.checkBody ? api.checkBody(operation, text) : text + // A GraphQL body is all the variables: the flags join it here, so the schema check sees what is sent. + const given = + operation.binding.kind === "graphql" ? apiJson(graphqlVariables(operation, text, input.fields)) : text + if (operation.binding.kind === "graphql") input.fields = {} + const body = operation.binding.kind === "rpc" ? text : api.checkBody ? api.checkBody(operation, given) : given if (body !== undefined) input.body = body await api.execute(this, operation, input) }) diff --git a/src/cli/service-api-graphql.test.ts b/src/cli/service-api-graphql.test.ts new file mode 100644 index 000000000..d0b4ee80b --- /dev/null +++ b/src/cli/service-api-graphql.test.ts @@ -0,0 +1,220 @@ +import { mkdtempSync, rmSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { captureStreams } from "@wirecat/cli-base" +import { + adaptGraphql, + definitionsGenerator, + type GraphqlFakeAnswer, + type GraphqlFakeCall, + generate, + graphqlFake, + manifestGenerator, + type SchemaNode, +} from "@wirecat/cli-base/codegen" +import { integer } from "@wirecat/cli-base/codegen/runtime" +import { hostFetch } from "@wirecat/cli-base/http" +import { memoryKeyring } from "@wirecat/cli-base/testing" +import * as v from "valibot" +import { afterEach, expect, it } from "vitest" +import { trackerIntrospection } from "../../test/fixtures/graphql-tracker.js" +import { run } from "./program.js" +import { serviceApiCall } from "./service-api-call.js" +import type { ServiceApiManifest } from "./service-api-manifest.js" +import { settingsFor } from "./settings.js" +import { serviceApiCommand } from "./shared-command-exports.js" + +const URL_ = "https://api.tracker.example/graphql" +const model = adaptGraphql(trackerIntrospection(), { url: URL_, scalars: { DateTime: { type: "string" } } }) +// What a CLI's pnpm generate writes, read back. +const generated = generate( + model, + [manifestGenerator({ path: "manifest.ts" }), definitionsGenerator({ path: "definitions.ts" })], + { banner: [], permissions: { group: "issues" } }, +) +const constant = (path: string, name: string) => { + const content = generated.find((one) => one.path === path)?.content ?? "" + const start = content.indexOf("=", content.indexOf(`export const ${name}`)) + 1 + const end = content.indexOf("\n\nexport const", start) + return JSON.parse(content.slice(start, end < 0 ? undefined : end)) +} +const manifest: ServiceApiManifest = { + servers: [{ url: URL_ }], + securitySchemes: { key: { type: "apiKey", in: "header", name: "Authorization" } }, + security: [{ key: [] }], + operations: constant("manifest.ts", "operations"), +} +const definitions = constant("definitions.ts", "definitions") as Record +const app = { command: "track", appName: "track-cli", envPrefix: "TRACK", description: "synthetic", version: "1.0.0" } + +const roots: string[] = [] +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) +}) + +type Answers = Record GraphqlFakeAnswer> +const fakeOf = (answers: Answers = {}) => + graphqlFake({ + operations: manifest.operations, + definitions, + url: URL_, + auth: { header: "Authorization", value: "key-1" }, + answers, + }) + +// Copied from what valibotGenerator writes for the two operations; its file imports a types module a test lacks. +const SCHEMAS: Record = { + IssueRequest: v.looseObject({ id: v.string() }), + IssuesRequest: v.looseObject({ + first: v.optional(v.nullable(integer())), + after: v.optional(v.nullable(v.string())), + includeArchived: v.optional(v.nullable(v.boolean())), + }), +} + +const setup = (answers: Answers = {}) => { + const root = mkdtempSync(join(tmpdir(), "graphql-api-")) + roots.push(root) + const env = { HOME: root, TRACK_STATE_DIR: join(root, "state"), TRACK_CONFIG_DIR: join(root, "config") } + const fake = fakeOf(answers) + const configuration = settingsFor(app) + const definition = { + app, + configuration, + commands: () => [ + serviceApiCommand({ + app, + configuration, + manifest, + service: "Tracker", + fetch: () => hostFetch({ hosts: ["api.tracker.example"], fetch: fake.fetch as typeof fetch }), + token: () => "key-1", + schemas: async () => SCHEMAS, + definitions: async () => definitions, + }), + ], + } + const cli = async (argv: string[]) => { + const streams = captureStreams() + const code = await run(argv, definition, { streams, env, keyring: memoryKeyring(), tty: false }) + const out = streams.stdout.join("") + const err = streams.stderr.join("") + return { + code, + json: out.startsWith("{") ? JSON.parse(out) : undefined, + error: err.startsWith("{") ? JSON.parse(err).error : undefined, + } + } + return { cli, fake } +} + +const issue = (id: string) => ({ + id, + identifier: `T-${id}`, + title: `issue ${id}`, + description: null, + priority: 1, + createdAt: "2026-11-01T00:00:00Z", + updatedAt: "2026-11-02T00:00:00Z", + archivedAt: null, + state: { id: "s1" }, + team: { id: "t1" }, + assignee: null, +}) + +it("a query is one POST of its document; flags join --body as variables, read by their schema", async () => { + const { cli, fake } = setup({ + issues: () => ({ data: { nodes: [issue("a")], pageInfo: { hasNextPage: false, endCursor: null } } }), + }) + const listed = await cli([ + "work", + "api", + "issues", + "--first", + "2", + "--include-archived", + "true", + "--order-by", + "updatedAt", + "--body", + '{"filter":{"updatedAt":{"gt":"2026-11-01T00:00:00Z"}}}', + "--json", + ]) + expect(fake.refusals).toEqual([]) + expect(listed.error?.message).toBeUndefined() + expect(listed.json.item.nodes[0].identifier).toBe("T-a") + expect(fake.refusals).toEqual([]) + expect(fake.calls[0]?.variables).toEqual({ + first: 2, + includeArchived: true, + orderBy: "updatedAt", + filter: { updatedAt: { gt: "2026-11-01T00:00:00Z" } }, + }) + const one = await cli(["work", "api", "issue", "--id", "a", "--json"]) + expect(one.json.item).toMatchObject({ id: expect.any(String), state: { id: expect.any(String) } }) + expect(fake.calls[1]?.variables).toEqual({ id: "a" }) + expect(fake.refusals).toEqual([]) +}) + +it("errors[] is a failure at HTTP 200, named by its code and never by the service's message", async () => { + const { cli } = setup({ + issue: () => ({ errors: [{ message: "Entity not found: secret-title", extensions: { code: "FORBIDDEN" } }] }), + }) + const failed = await cli(["work", "api", "issue", "--id", "a", "--json"]) + expect(failed.code).not.toBe(0) + expect(failed.error.code).toBe("permission_error") + expect(failed.error.message).not.toContain("secret-title") +}) + +it("a flag of the wrong type or an undeclared variable is refused before anything is sent", async () => { + const { cli, fake } = setup() + expect((await cli(["work", "api", "issues", "--first", "many", "--json"])).error.message).toContain("takes a number") + expect((await cli(["work", "api", "issue", "--body", '{"id":"a","nope":1}', "--json"])).error.message).toContain( + "has no variable nope", + ) + expect(fake.calls).toEqual([]) +}) + +it("--all follows pageInfo.endCursor through after, one document per page", async () => { + const { cli, fake } = setup({ + issues: ({ variables }) => + variables.after === "c1" + ? { data: { nodes: [issue("b")], pageInfo: { hasNextPage: false, endCursor: null } } } + : { data: { nodes: [issue("a")], pageInfo: { hasNextPage: true, endCursor: "c1" } } }, + }) + const all = await cli(["work", "api", "issues", "--first", "1", "--all", "--json"]) + expect(all.error?.message).toBeUndefined() + expect(JSON.stringify(all.json)).toContain("T-b") + expect(fake.calls.map((one) => one.variables)).toEqual([{ first: 1 }, { first: 1, after: "c1" }]) +}) + +it("serviceApiCall sends a source's own deeper selection and answers data.", async () => { + const fake = fakeOf({ issue: () => ({ data: { id: "a", state: { id: "s1", name: "Todo", type: "unstarted" } } }) }) + const call = serviceApiCall({ + manifest, + service: "Tracker", + fetch: hostFetch({ hosts: ["api.tracker.example"], fetch: fake.fetch as typeof fetch }), + token: () => "key-1", + }) + const answer = await call("issue", { + path: {}, + query: {}, + headers: {}, + fields: { id: "a" }, + selection: "id state { id name type }", + }) + expect(answer).toEqual({ id: "a", state: { id: "s1", name: "Todo", type: "unstarted" } }) + expect(fake.refusals).toEqual([]) + expect(fake.calls[0]?.query).toContain("state { id name type }") +}) + +it("the request schema sees the flags: a number flag passes, a missing required variable is refused unsent", async () => { + const { cli, fake } = setup({ + issues: () => ({ data: { nodes: [], pageInfo: { hasNextPage: false, endCursor: null } } }), + }) + expect((await cli(["work", "api", "issues", "--first", "2", "--json"])).error?.message).toBeUndefined() + const missing = await cli(["work", "api", "issue", "--json"]) + expect(missing.error.code).toBe("validation_error") + expect(missing.error.message).toContain("id") + expect(fake.calls).toHaveLength(1) +}) diff --git a/src/cli/service-api-manifest.ts b/src/cli/service-api-manifest.ts index 3235c215c..7fce73427 100644 --- a/src/cli/service-api-manifest.ts +++ b/src/cli/service-api-manifest.ts @@ -181,9 +181,10 @@ const numberOf = (value: unknown): number | undefined => { export const parameterValue = (input: ApiCommandInput, parameter: { in: "query" | "body"; name: string }): unknown => parameter.in === "query" ? input.query[parameter.name] - : input.body === undefined - ? undefined - : (parseApiJson(input.body) as Record | null)?.[parameter.name] + : (input.fields[parameter.name] ?? + (input.body === undefined + ? undefined + : (parseApiJson(input.body) as Record | null)?.[parameter.name])) export const withValue = ( input: ApiCommandInput, @@ -192,7 +193,9 @@ export const withValue = ( ): ApiCommandInput => { if (parameter.in === "query") return { ...input, query: { ...input.query, [parameter.name]: String(value) } } const body = input.body === undefined ? {} : parseApiJson(input.body) - return { ...input, body: apiJson({ ...(body as Record), [parameter.name]: value }) } + // A flag of the same name would stand over the body, and every page would ask for the first. + const { [parameter.name]: _, ...fields } = input.fields + return { ...input, fields, body: apiJson({ ...(body as Record), [parameter.name]: value }) } } /** One page's items, and how to ask for the next: new flags, the next page's whole URL, or `undefined` at the end. */ diff --git a/src/cli/service-api.ts b/src/cli/service-api.ts index 6da96a481..24e83058b 100644 --- a/src/cli/service-api.ts +++ b/src/cli/service-api.ts @@ -177,8 +177,13 @@ export const serviceApiPermissions = ( const rowOf = (operation: ManifestOperation) => ({ command: operation.command, - method: operation.binding.kind === "http" ? operation.binding.method : "", - path: operation.binding.kind === "http" ? operation.binding.path : "", + method: operation.binding.kind === "http" ? operation.binding.method : "POST", + path: + operation.binding.kind === "http" + ? operation.binding.path + : operation.binding.kind === "graphql" + ? `${operation.binding.operation} ${operation.binding.field}` + : "", effect: operation.effect, summary: operation.summary ?? "", }) diff --git a/test/fixtures/graphql-tracker.ts b/test/fixtures/graphql-tracker.ts new file mode 100644 index 000000000..39d715d7c --- /dev/null +++ b/test/fixtures/graphql-tracker.ts @@ -0,0 +1,165 @@ +// A hand-made introspection result shaped like Linear's: Relay connections, an input object, an enum, a custom +// scalar, wrapped types, and Delete, Archive and Unarchive mutations. Not Linear's real schema. +type Ref = { kind: string; name: string | null; ofType: Ref | null } + +const named = (kind: string, name: string): Ref => ({ kind, name, ofType: null }) +const scalar = (name: string) => named("SCALAR", name) +const object = (name: string) => named("OBJECT", name) +const input = (name: string) => named("INPUT_OBJECT", name) +const nonNull = (of: Ref): Ref => ({ kind: "NON_NULL", name: null, ofType: of }) +const list = (of: Ref): Ref => ({ kind: "LIST", name: null, ofType: of }) + +const arg = (name: string, type: Ref, defaultValue: string | null = null) => ({ + name, + description: null, + type, + defaultValue, +}) +const field = (name: string, type: Ref, args: ReturnType[] = [], description: string | null = null) => ({ + name, + description, + args, + type, + isDeprecated: false, +}) +const type = (kind: string, name: string, rest: Record = {}) => ({ + kind, + name, + description: null, + fields: null, + inputFields: null, + enumValues: null, + possibleTypes: null, + ...rest, +}) +const page = [arg("first", scalar("Int"), "50"), arg("after", scalar("String"))] +const connection = (name: string, node: string) => + type("OBJECT", `${name}Connection`, { + fields: [field("nodes", nonNull(list(nonNull(object(node))))), field("pageInfo", nonNull(object("PageInfo")))], + }) + +export const trackerIntrospection = () => ({ + data: { + __schema: { + queryType: { name: "Query" }, + mutationType: { name: "Mutation" }, + types: [ + type("SCALAR", "String"), + type("SCALAR", "ID"), + type("SCALAR", "Int"), + type("SCALAR", "Float"), + type("SCALAR", "Boolean"), + type("SCALAR", "DateTime"), + type("OBJECT", "Query", { + fields: [ + field( + "issues", + nonNull(object("IssueConnection")), + [ + ...page, + arg("filter", input("IssueFilter")), + arg("includeArchived", scalar("Boolean")), + arg("orderBy", named("ENUM", "PaginationOrderBy")), + ], + "All issues.\nPaged.", + ), + field("issue", nonNull(object("Issue")), [arg("id", nonNull(scalar("String")))], "One issue by its id."), + field("teams", nonNull(object("TeamConnection")), page), + field("users", nonNull(object("UserConnection")), [...page, arg("includeArchived", scalar("Boolean"))]), + field("workflowStates", nonNull(object("WorkflowStateConnection")), page), + field("viewer", nonNull(object("User"))), + field("maybeIssue", object("Issue"), [arg("id", nonNull(scalar("String")))]), + field("recentIssues", nonNull(list(nonNull(object("Issue")))), [ + arg("limit", nonNull(scalar("Int")), "10"), + ]), + field("search", nonNull(list(nonNull(named("UNION", "SearchResult")))), [ + arg("term", nonNull(scalar("String"))), + ]), + ], + }), + type("OBJECT", "Mutation", { + fields: [ + field("issueCreate", nonNull(object("IssuePayload")), [arg("input", nonNull(input("IssueCreateInput")))]), + field("issueDelete", nonNull(object("DeletePayload")), [arg("id", nonNull(scalar("String")))]), + field("issueArchive", nonNull(object("ArchivePayload")), [arg("id", nonNull(scalar("String")))]), + field("issueUnarchive", nonNull(object("ArchivePayload")), [arg("id", nonNull(scalar("String")))]), + ], + }), + type("OBJECT", "Issue", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("identifier", nonNull(scalar("String"))), + field("title", nonNull(scalar("String"))), + field("description", scalar("String")), + field("priority", nonNull(scalar("Float"))), + field("createdAt", nonNull(scalar("DateTime"))), + field("updatedAt", nonNull(scalar("DateTime"))), + field("archivedAt", scalar("DateTime")), + field("state", nonNull(object("WorkflowState"))), + field("team", nonNull(object("Team"))), + field("assignee", object("User")), + field("labels", nonNull(object("IssueLabelConnection")), page), + field("history", nonNull(object("IssueLabelConnection")), [arg("since", nonNull(scalar("DateTime")))]), + { ...field("legacyKey", scalar("String")), isDeprecated: true }, + ], + }), + type("OBJECT", "WorkflowState", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("name", nonNull(scalar("String"))), + field("type", nonNull(scalar("String"))), + field("team", nonNull(object("Team"))), + ], + }), + type("OBJECT", "Team", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("key", nonNull(scalar("String"))), + field("name", nonNull(scalar("String"))), + ], + }), + type("OBJECT", "User", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("name", nonNull(scalar("String"))), + field("email", nonNull(scalar("String"))), + field("active", nonNull(scalar("Boolean"))), + ], + }), + type("OBJECT", "IssueLabel", { + fields: [field("id", nonNull(scalar("ID"))), field("name", nonNull(scalar("String")))], + }), + type("OBJECT", "PageInfo", { + fields: [field("hasNextPage", nonNull(scalar("Boolean"))), field("endCursor", scalar("String"))], + }), + connection("Issue", "Issue"), + connection("Team", "Team"), + connection("User", "User"), + connection("WorkflowState", "WorkflowState"), + connection("IssueLabel", "IssueLabel"), + type("OBJECT", "IssuePayload", { + fields: [field("success", nonNull(scalar("Boolean"))), field("issue", object("Issue"))], + }), + type("OBJECT", "DeletePayload", { fields: [field("success", nonNull(scalar("Boolean")))] }), + type("OBJECT", "ArchivePayload", { fields: [field("success", nonNull(scalar("Boolean")))] }), + type("UNION", "SearchResult", { possibleTypes: [{ name: "Issue" }, { name: "Team" }] }), + type("ENUM", "PaginationOrderBy", { enumValues: [{ name: "createdAt" }, { name: "updatedAt" }] }), + type("INPUT_OBJECT", "IssueFilter", { + inputFields: [arg("updatedAt", input("DateComparator"))], + }), + type("INPUT_OBJECT", "DateComparator", { + inputFields: [arg("gt", scalar("DateTime")), arg("gte", scalar("DateTime"))], + }), + type("INPUT_OBJECT", "IssueCreateInput", { + inputFields: [ + arg("title", nonNull(scalar("String"))), + arg("teamId", nonNull(scalar("String"))), + arg("description", scalar("String")), + arg("priority", nonNull(scalar("Int")), "0"), + ], + }), + type("OBJECT", "__Schema", { fields: [] }), + ], + }, + }, +}) From e10ff1216ca436ebb9b0c99f4d5c42560cff5270 Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 23:04:51 +0100 Subject: [PATCH 2/2] fix(cli): GraphQL review fixes: write outcome, run record, flag values, echoed codes From the review of #3097: a write that errors[] does not show as undone is outcome_unknown; a GraphQL flag is the body and stays out of the run's files; the run log records the failure and names the endpoint query/issues; digits go as written, without 0x or 1e; a code is repeated only when it is a plain constant; a CLI's failure is asked first; a missing required variable is refused unsent in serviceApiCall too; the POST never follows a redirect; the credential check comes before the GraphQL branch; graphqlVariables lives in api-input. Co-Authored-By: Claude Opus 5.5 --- changes/feat-graphql-executor.md | 14 ++-- src/cli/bot/api-http.ts | 111 +++++++++++----------------- src/cli/bot/api-input.ts | 62 ++++++++++++++++ src/cli/bot/api.ts | 13 +++- src/cli/service-api-graphql.test.ts | 78 ++++++++++++++----- src/cli/service-api.ts | 3 +- 6 files changed, 186 insertions(+), 95 deletions(-) diff --git a/changes/feat-graphql-executor.md b/changes/feat-graphql-executor.md index 9108f0384..ab4d26f45 100644 --- a/changes/feat-graphql-executor.md +++ b/changes/feat-graphql-executor.md @@ -1,11 +1,15 @@ ### Added - **The `api` group and `serviceApiCall` send a GraphQL operation** of a manifest that cli-base 0.115.0 generates - from a schema. Each call is one POST of the document `graphqlDocument` builds; the variables are `--body` as one - object with each flag over it, read by its schema (a number, true or false, JSON for an input object), and a name - the operation does not declare is refused before anything is sent. `errors[]` is a failure even at HTTP 200, named - by its `extensions.code` and never by the service's message; the answer is `data.`. `--all` pages by - `pageInfo`. `ApiCommandInput.selection` gives a source a deeper selection than the generated one. + from a schema. Each call is one POST of the document `graphqlDocument` builds, never sent again on a redirect. + The variables are `--body` as one object with each flag over it, read by its schema: digits as written, `true` or + `false`, JSON for an input object. A variable the operation does not declare, or a required one left out, is + refused before anything is sent. The flags of a GraphQL operation are its body and stay out of the run's files. +- **`errors[]` is a failure even at HTTP 200.** A CLI's own `failure` names it first; else its `extensions.code` + does, repeated only when it is a plain constant, never the service's message. A write is `outcome_unknown` unless + the code says nothing ran and no data came back. The answer is `data.`; `--all` pages by `pageInfo`. +- **`ApiCommandInput.selection`** gives a source a deeper selection than the generated one. `api list` and the run + record name a GraphQL operation as `POST` `query/issues`. ### Changed — may break callers diff --git a/src/cli/bot/api-http.ts b/src/cli/bot/api-http.ts index 0f5a6f12a..43aa6b6d3 100644 --- a/src/cli/bot/api-http.ts +++ b/src/cli/bot/api-http.ts @@ -6,7 +6,7 @@ import { providerRequest } from "../command-runs.js" import { outputFor } from "../context.js" import { itemOf, renderAnswer } from "../envelope.js" import type { ApiCommandInput } from "./api.js" -import { apiJson, parseApiJson, sendsBytes } from "./api-input.js" +import { apiJson, graphqlVariables, parseApiJson, sendsBytes } from "./api-input.js" export interface HttpApiRequest { method: string @@ -66,8 +66,7 @@ export const httpApiRequest = ( baseUrl: string, ): HttpApiRequest => { const { binding } = operation - if (binding.kind === "graphql") return graphqlRequest(operation, binding, input, baseUrl) - if (binding.kind !== "http") + if (binding.kind !== "http" && binding.kind !== "graphql") throw new CliError("configuration_error", `${operation.command} is not an HTTP operation`) if (unsendableBody(operation)) throw new CliError( @@ -81,6 +80,7 @@ export const httpApiRequest = ( `${operation.command} answers with a credential, which the generated command never prints; nothing was sent`, { sent: false }, ) + if (binding.kind === "graphql") return graphqlRequest(operation, binding, input, baseUrl) if (Object.keys(input.fields).length > 0) throw new CliError("configuration_error", `${operation.command} has body fields as flags, which HTTP cannot send`) if (!/^\/(?!\/)/.test(binding.path)) @@ -108,54 +108,6 @@ export const httpApiRequest = ( return { method: binding.method, url, headers, ...(body === undefined ? {} : { body }) } } -/** - * A GraphQL operation's variables: the body's (`--body`, all of them as one object) with each flag over it, read by - * the variable's schema. A name the operation does not declare is refused before anything is sent. - */ -export const graphqlVariables = ( - operation: ManifestOperation, - body: string | undefined, - fields: Readonly>, -): Record => { - const { binding } = operation - if (binding.kind !== "graphql") - throw new CliError("configuration_error", `${operation.command} is not a GraphQL operation`) - const given = body?.trim() ? parseApiJson(body) : {} - if (given === null || typeof given !== "object" || Array.isArray(given)) - throw new CliError("validation_error", `${operation.command} takes its variables as one JSON object`, { - sent: false, - }) - const variables: Record = { ...(given as Record) } - for (const [name, raw] of Object.entries(fields)) { - const schema = operation.parameters.find((one) => one.in === "body" && one.name === name)?.schema - variables[name] = flagValue(operation, name, raw, schema?.type) - } - const unknown = Object.keys(variables).filter((name) => !(name in binding.variables)) - if (unknown.length > 0) - throw new CliError("validation_error", `${operation.command} has no variable ${unknown.join(", ")}`, { - sent: false, - }) - return variables -} - -const flagValue = (operation: ManifestOperation, name: string, raw: string, type: string | undefined): unknown => { - if (type === "integer" || type === "number") { - const number = Number(raw) - if (raw.trim() === "" || !Number.isFinite(number)) - throw new CliError("validation_error", `--${name} of ${operation.command} takes a number`, { sent: false }) - return number - } - if (type === "boolean") { - if (raw !== "true" && raw !== "false") - throw new CliError("validation_error", `--${name} of ${operation.command} takes true or false`, { sent: false }) - return raw === "true" - } - if (type === "object" || type === "array") return parseApiJson(raw) - // An input object or a list given as JSON; an enum's value, behind a ref too, is a bare word. - if (type === "ref" && /^\s*[{["]/.test(raw)) return parseApiJson(raw) - return raw -} - /** One GraphQL operation as a POST of its one document to the endpoint, with its variables. */ const graphqlRequest = ( operation: ManifestOperation, @@ -168,7 +120,8 @@ const graphqlRequest = ( headers.set("accept", "application/json") headers.set("content-type", "application/json") const query = graphqlDocument(binding, input.selection) - return { method: "POST", url: new URL(baseUrl), headers, body: apiJson({ query, variables }) } + // A 307 or 308 would send the variables again, to wherever it points. + return { method: "POST", url: new URL(baseUrl), headers, body: apiJson({ query, variables }), redirect: "error" } } /** `/v1/pages/{page_id}` → `/v1/pages/:page_id`: the run record keeps the template, never an id. */ @@ -179,11 +132,11 @@ const endpointOf = (operation: ManifestOperation): string => operation.binding.kind === "http" ? templateOf(operation.binding.path) : operation.binding.kind === "graphql" - ? `${operation.binding.operation} ${operation.binding.field}` + ? `${operation.binding.operation}/${operation.binding.field}` : "" // Common GraphQL server codes (Apollo's names) as the CLI's; any other is the provider's. -const GRAPHQL_CODES: Readonly> = { +const GRAPHQL_CODES = { UNAUTHENTICATED: "authentication_error", AUTHENTICATION_ERROR: "authentication_error", FORBIDDEN: "permission_error", @@ -191,31 +144,47 @@ const GRAPHQL_CODES: Readonly> = { BAD_USER_INPUT: "validation_error", GRAPHQL_VALIDATION_FAILED: "validation_error", INVALID_INPUT: "validation_error", -} +} satisfies Record + +// A refusal of these kinds means the service did nothing, so a write that got one is not in doubt. +const NOTHING_RAN = new Set(["authentication_error", "permission_error", "rate_limited", "validation_error"]) /** - * A GraphQL answer comes with HTTP 200 even when it failed: `errors[]` is the failure, named by its first - * `extensions.code`, never by the service's own message (WC-SECR-6). Otherwise the answer is `data.`. + * A GraphQL answer comes with HTTP 200 even when it failed: `errors[]` is the failure, named by the CLI's own + * `failure`, else by its first `extensions.code`, never by the service's message (WC-SECR-6). A write that failed in + * any other way, or answered data too, may have landed (WC-LIFE-9). Otherwise the answer is `data.`. */ -const graphqlAnswer = (service: string, operation: ManifestOperation, answer: unknown): unknown => { +const graphqlAnswer = (options: HttpApiSendOptions, operation: ManifestOperation, answer: unknown): unknown => { const { binding } = operation if (binding.kind !== "graphql") return answer const { data, errors } = (answer ?? {}) as { data?: Record | null; errors?: unknown } if (Array.isArray(errors) && errors.length > 0) { - const code = (errors[0] as { extensions?: { code?: unknown } } | null)?.extensions?.code - const known = typeof code === "string" ? GRAPHQL_CODES[code.toUpperCase()] : undefined + const own = options.failure?.(200, answer, operation) + if (own) throw own + const raw = (errors[0] as { extensions?: { code?: unknown } } | null)?.extensions?.code + // The code is the service's text too: only a plain constant is repeated. + const code = typeof raw === "string" && /^[A-Z][A-Z0-9_]{0,40}$/.test(raw) ? raw : undefined + const known: ErrorCode = (code && GRAPHQL_CODES[code as keyof typeof GRAPHQL_CODES]) || "provider_error" const writes = operation.effect !== "read" - throw new CliError( - (known ?? "provider_error") as ErrorCode, - `${service} refused ${operation.command}${typeof code === "string" ? ` (${code})` : ""}` + - (writes && data?.[binding.field] != null ? "; part of it may have been done, check before repeating" : ""), - ) + if (writes && (!NOTHING_RAN.has(known) || data?.[binding.field] != null)) return outcomeUnknown(options.service) + throw new CliError(known, `${options.service} refused ${operation.command}${code ? ` (${code})` : ""}`, { + retryable: known === "rate_limited", + }) } if (!data || !(binding.field in data)) - throw new CliError("invalid_response", `${service} answered ${operation.command} without data.${binding.field}`) + throw new CliError( + "invalid_response", + `${options.service} answered ${operation.command} without data.${binding.field}`, + ) return data[binding.field] } +const outcomeUnknown = (service: string): never => { + throw new CliError("outcome_unknown", `${service} did not confirm a write; check it before repeating the write`, { + retryable: false, + }) +} + const answerOf = async (response: Response, maxBytes: number): Promise => { if (response.status === 204 || !response.body || response.headers.get("content-length") === "0") return {} return readJsonResponse(response, { maxBytes }) @@ -269,8 +238,14 @@ export const httpApiSend = end({ status, error: failed }) throw failed } - end({ status }) - return graphqlAnswer(options.service, operation, answer) + try { + const result = graphqlAnswer(options, operation, answer) + end({ status }) + return result + } catch (error) { + end({ status, error }) + throw error + } } /** diff --git a/src/cli/bot/api-input.ts b/src/cli/bot/api-input.ts index 3429a3025..1d5e575cf 100644 --- a/src/cli/bot/api-input.ts +++ b/src/cli/bot/api-input.ts @@ -160,3 +160,65 @@ export const apiPlainJson = (value: unknown): unknown => isLosslessNumber(inner) && !isSafeNumber(inner.value) ? inner.toString() : finite(key, inner), ) ?? "null", ) + +/** A JSON object with no lossless number at its top: what a GraphQL body of variables must be. */ +const isVariables = (value: unknown): value is Record => + value !== null && typeof value === "object" && !Array.isArray(value) && !isLosslessNumber(value) + +/** + * A GraphQL operation's variables: the body's (`--body`, all of them as one object) with each flag over it, read by + * the variable's schema. A name the operation does not declare, or a required one left out, is refused unsent. + */ +export const graphqlVariables = ( + operation: ManifestOperation, + body: string | undefined, + fields: Readonly>, +): Record => { + const { binding } = operation + if (binding.kind !== "graphql") + throw new CliError("configuration_error", `${operation.command} is not a GraphQL operation`) + const given = body?.trim() ? parseApiJson(body) : {} + if (!isVariables(given)) + throw new CliError("validation_error", `${operation.command} takes its variables as one JSON object`, { + sent: false, + }) + const variables: Record = { ...given } + for (const [name, raw] of Object.entries(fields)) { + const schema = operation.parameters.find((one) => one.in === "body" && one.name === name)?.schema + variables[name] = flagValue(operation, name, raw, schema?.type) + } + const unknown = Object.keys(variables).filter((name) => !(name in binding.variables)) + if (unknown.length > 0) + throw new CliError("validation_error", `${operation.command} has no variable ${unknown.join(", ")}`, { + sent: false, + }) + const missing = Object.entries(binding.variables) + .filter(([name, type]) => type.endsWith("!") && variables[name] == null) + .map(([name]) => `--${apiFlagOf(name)}`) + if (missing.length > 0) + throw new CliError("validation_error", `${operation.command} needs ${missing.join(", ")}`, { sent: false }) + return variables +} + +const DECIMAL = /^-?\d+(\.\d+)?$/ + +const flagValue = (operation: ManifestOperation, name: string, raw: string, type: string | undefined): unknown => { + const flag = `--${apiFlagOf(name)} of ${operation.command}` + if (type === "integer" || type === "number") { + // Number() would take 0x10 and 1e1, and round a long id; the digits go as written. + if (!(type === "integer" ? DIGITS : DECIMAL).test(raw.trim())) + throw new CliError("validation_error", `${flag} takes ${type === "integer" ? "a whole number" : "a number"}`, { + sent: false, + }) + return new LosslessNumber(raw.trim()) + } + if (type === "boolean") { + if (raw !== "true" && raw !== "false") + throw new CliError("validation_error", `${flag} takes true or false`, { sent: false }) + return raw === "true" + } + if (type === "object" || type === "array" || type === "unknown") return parseApiJson(raw) + // An input object or a list given as JSON; an enum's value, behind a ref too, is a bare word. + if (type === "ref" && /^\s*[{["]/.test(raw)) return parseApiJson(raw) + return raw +} diff --git a/src/cli/bot/api.ts b/src/cli/bot/api.ts index 30587407f..582f1bbbd 100644 --- a/src/cli/bot/api.ts +++ b/src/cli/bot/api.ts @@ -4,8 +4,15 @@ 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 { graphqlVariables } from "./api-http.js" -import { apiFlagOf, apiJson, apiOptionKey, readApiBody, readApiBytes, sendsBytes } from "./api-input.js" +import { + apiFlagOf, + apiJson, + apiOptionKey, + graphqlVariables, + readApiBody, + readApiBytes, + sendsBytes, +} from "./api-input.js" export interface ApiCommandInput { path: Record @@ -60,6 +67,8 @@ export const generatedApiCommand = (api: ApiCommands): Command => { `--${apiFlagOf(parameter.name)} `, parameter.description?.split("\n")[0] ?? parameter.name, ) + // A GraphQL flag is the request body, which never reaches the run's files (SEC-196). + if (operation.binding.kind === "graphql" && parameter.in === "body") secretInput(option) if (parameter.required && parameter.in !== "body") { // A required parameter the spec gives a default (Notion's `Notion-Version`) is sent with it, never asked for. const fallback = scalarOf(parameter.schema.default) diff --git a/src/cli/service-api-graphql.test.ts b/src/cli/service-api-graphql.test.ts index d0b4ee80b..5a90ae4c9 100644 --- a/src/cli/service-api-graphql.test.ts +++ b/src/cli/service-api-graphql.test.ts @@ -1,4 +1,4 @@ -import { mkdtempSync, rmSync } from "node:fs" +import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs" import { tmpdir } from "node:os" import { join } from "node:path" import { captureStreams } from "@wirecat/cli-base" @@ -18,7 +18,9 @@ import { memoryKeyring } from "@wirecat/cli-base/testing" import * as v from "valibot" import { afterEach, expect, it } from "vitest" import { trackerIntrospection } from "../../test/fixtures/graphql-tracker.js" +import { commandPermissions } from "./permission-keys.js" import { run } from "./program.js" +import { serviceApiPermissions } from "./service-api.js" import { serviceApiCall } from "./service-api-call.js" import type { ServiceApiManifest } from "./service-api-manifest.js" import { settingsFor } from "./settings.js" @@ -47,6 +49,12 @@ const manifest: ServiceApiManifest = { const definitions = constant("definitions.ts", "definitions") as Record const app = { command: "track", appName: "track-cli", envPrefix: "TRACK", description: "synthetic", version: "1.0.0" } +const filesUnder = (dir: string): string[] => + readdirSync(dir).flatMap((name) => { + const path = join(dir, name) + return statSync(path).isDirectory() ? filesUnder(path) : [path] + }) + const roots: string[] = [] afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) @@ -77,23 +85,22 @@ const setup = (answers: Answers = {}) => { roots.push(root) const env = { HOME: root, TRACK_STATE_DIR: join(root, "state"), TRACK_CONFIG_DIR: join(root, "config") } const fake = fakeOf(answers) - const configuration = settingsFor(app) - const definition = { + mkdirSync(env.TRACK_CONFIG_DIR, { recursive: true }) + writeFileSync( + join(env.TRACK_CONFIG_DIR, "config.json"), + JSON.stringify({ profiles: { work: { permissions: { api: "allow" } } } }), + ) + const api = { app, - configuration, - commands: () => [ - serviceApiCommand({ - app, - configuration, - manifest, - service: "Tracker", - fetch: () => hostFetch({ hosts: ["api.tracker.example"], fetch: fake.fetch as typeof fetch }), - token: () => "key-1", - schemas: async () => SCHEMAS, - definitions: async () => definitions, - }), - ], + manifest, + service: "Tracker", + fetch: () => hostFetch({ hosts: ["api.tracker.example"], fetch: fake.fetch as typeof fetch }), + token: () => "key-1", + schemas: async () => SCHEMAS, + definitions: async () => definitions, } + const configuration = settingsFor(app, { permissions: commandPermissions(serviceApiPermissions(api)) }) + const definition = { app, configuration, commands: () => [serviceApiCommand({ ...api, configuration })] } const cli = async (argv: string[]) => { const streams = captureStreams() const code = await run(argv, definition, { streams, env, keyring: memoryKeyring(), tty: false }) @@ -105,7 +112,7 @@ const setup = (answers: Answers = {}) => { error: err.startsWith("{") ? JSON.parse(err).error : undefined, } } - return { cli, fake } + return { cli, fake, root } } const issue = (id: string) => ({ @@ -158,17 +165,50 @@ it("a query is one POST of its document; flags join --body as variables, read by it("errors[] is a failure at HTTP 200, named by its code and never by the service's message", async () => { const { cli } = setup({ - issue: () => ({ errors: [{ message: "Entity not found: secret-title", extensions: { code: "FORBIDDEN" } }] }), + issue: ({ variables }) => ({ + errors: [ + { + message: "Entity not found: secret-title", + extensions: { code: variables.id === "a" ? "FORBIDDEN" : "pii a@b.c in a code" }, + }, + ], + }), }) const failed = await cli(["work", "api", "issue", "--id", "a", "--json"]) expect(failed.code).not.toBe(0) expect(failed.error.code).toBe("permission_error") expect(failed.error.message).not.toContain("secret-title") + const odd = await cli(["work", "api", "issue", "--id", "b", "--json"]) + expect(odd.error.code).toBe("provider_error") + expect(odd.error.message).not.toContain("a@b.c") +}) + +it("a write that errors[] does not show as undone is outcome_unknown; its flags stay out of the run's files", async () => { + const marker = "secret-title-marker" + const { cli, root } = setup({ + issueCreate: ({ variables }) => + (variables.input as { title: string }).title === "refused" + ? { errors: [{ message: "x", extensions: { code: "BAD_USER_INPUT" } }] } + : { data: { success: true }, errors: [{ message: "x", extensions: { code: "INTERNAL_SERVER_ERROR" } }] }, + }) + const create = (title: string) => + cli(["work", "api", "issue-create", "--input", JSON.stringify({ title, teamId: "t1" }), "--record", "--json"]) + expect((await create("refused")).error.code).toBe("validation_error") + const unsure = await create(marker) + expect(unsure.error.code).toBe("outcome_unknown") + const files = filesUnder(root).filter((one) => !one.endsWith("config.json")) + expect(files.some((one) => one.endsWith("run.json"))).toBe(true) + for (const one of files) expect(readFileSync(one).includes(marker), one).toBe(false) + const events = files.filter((one) => one.endsWith("events.jsonl")).map((one) => readFileSync(one, "utf8")) + expect(events.join("")).toContain("mutation/issueCreate") }) it("a flag of the wrong type or an undeclared variable is refused before anything is sent", async () => { const { cli, fake } = setup() - expect((await cli(["work", "api", "issues", "--first", "many", "--json"])).error.message).toContain("takes a number") + for (const bad of ["many", "0x10", "1e1"]) + expect((await cli(["work", "api", "issues", "--first", bad, "--json"])).error.message).toContain( + "takes a whole number", + ) expect((await cli(["work", "api", "issue", "--body", '{"id":"a","nope":1}', "--json"])).error.message).toContain( "has no variable nope", ) diff --git a/src/cli/service-api.ts b/src/cli/service-api.ts index 24e83058b..fe00d2738 100644 --- a/src/cli/service-api.ts +++ b/src/cli/service-api.ts @@ -177,7 +177,8 @@ export const serviceApiPermissions = ( const rowOf = (operation: ManifestOperation) => ({ command: operation.command, - method: operation.binding.kind === "http" ? operation.binding.method : "POST", + method: + operation.binding.kind === "http" ? operation.binding.method : operation.binding.kind === "graphql" ? "POST" : "", path: operation.binding.kind === "http" ? operation.binding.path