From a0d0f9695aa04a69b5080373b2127536a0c70aab Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 23:41:36 +0100 Subject: [PATCH 1/3] feat(kit): new --spec graphql and a tracker category for new --from-config new --spec graphql makes the api group from a GraphQL schema: with --spec-url (a config's spec.from) it asks the endpoint for its schema by introspection, as pnpm spec:sync does later. The graphql seed folder has sync-spec, spec-model over adaptGraphql, a generate.ts whose auth names the header the key travels in, and an api test over graphqlFake. new --from-config with category tracker and a source mounts cli-core's tracker commands over trackerSourceFromManifest, with a test that checks the source against the generated API and syncs through the CLI over a fake of the schema. The source check reads a tracker source too. cli-base 0.115.0, which has the graphql spec kind. Co-Authored-By: Claude Opus 5.5 --- changes/feat-tracker-graphql.md | 9 + kit/README.md | 20 +- kit/seeds/config/scripts/source-check.ts | 6 + kit/seeds/config/src/commands/tracker.ts | 77 ++++ kit/seeds/config/src/testing/fake-api.ts | 35 +- .../config/src/tracker-contracts.test.ts | 28 ++ kit/seeds/graphql/scripts/generate.ts | 71 +++ kit/seeds/graphql/scripts/spec-model.ts | 20 + kit/seeds/graphql/scripts/sync-spec.ts | 10 + kit/seeds/graphql/spec/clidev/provenance.json | 6 + kit/seeds/graphql/spec/clidev/schema.json | 414 ++++++++++++++++++ kit/seeds/graphql/src/api.test.ts | 85 ++++ kit/skills/new-cli/SKILL.md | 6 +- kit/src/from-config.ts | 14 +- kit/src/interview.ts | 5 +- kit/src/main.ts | 2 +- kit/src/new.ts | 48 +- kit/src/spec-url.ts | 40 ++ kit/src/spec.ts | 16 +- kit/test/from-config.test.ts | 2 +- kit/test/new.test.ts | 8 +- kit/test/seeds.test.ts | 31 ++ kit/test/spec-url.test.ts | 30 +- 23 files changed, 930 insertions(+), 53 deletions(-) create mode 100644 changes/feat-tracker-graphql.md create mode 100644 kit/seeds/config/src/commands/tracker.ts create mode 100644 kit/seeds/config/src/tracker-contracts.test.ts create mode 100644 kit/seeds/graphql/scripts/generate.ts create mode 100644 kit/seeds/graphql/scripts/spec-model.ts create mode 100644 kit/seeds/graphql/scripts/sync-spec.ts create mode 100644 kit/seeds/graphql/spec/clidev/provenance.json create mode 100644 kit/seeds/graphql/spec/clidev/schema.json create mode 100644 kit/seeds/graphql/src/api.test.ts diff --git a/changes/feat-tracker-graphql.md b/changes/feat-tracker-graphql.md new file mode 100644 index 0000000..bfce091 --- /dev/null +++ b/changes/feat-tracker-graphql.md @@ -0,0 +1,9 @@ +### Added + +- **`new --spec graphql` makes the api group from a GraphQL schema.** With `--spec-url` (or a config's `spec.from`), + `new` asks the endpoint for its schema by introspection, as `pnpm spec:sync` does later, and `pnpm generate` makes + one command of each query and mutation. A GraphQL schema names no sign-in, so the header the key travels in is + `auth` in `scripts/generate.ts`. +- **A `tracker` category.** `new --from-config` with `category: "tracker"` and a `source` mounts cli-core's tracker + commands (`sync`, `issues`, `projects`, `teams`…) over `trackerSourceFromManifest`, with a test that checks the + source against the generated API and syncs through the CLI over a fake of the schema. diff --git a/kit/README.md b/kit/README.md index d05bff4..c858a6d 100644 --- a/kit/README.md +++ b/kit/README.md @@ -89,16 +89,22 @@ read before the CLI has `node_modules`: its import resolves to the kit's own cli - `pnpm generate` first writes `src/generated/wirecat-config.ts` from the config (`scripts/from-config.ts`): the token check, the source and the hooks, which `src/` reads; the config stays the one file to edit. -- A CRM `source` needs `auth: { preset: "token", verify }`; `new` writes the files below only for what the config +- A `source` (a `crm` or a `tracker` category) needs `auth: { preset: "token", verify }`; `new` writes the files below only for what the config holds at `new`, and `pnpm generate` then reads their values again. - With `auth.verify`, `session start` is cli-core's `tokenSessionCommand`: it checks a token with that operation and keeps the account's id from the answer. - With a `source`, `src/commands/crm.ts` mounts cli-core's CRM commands (`sync`, `store status`, `deals`, `search`…) - over `crmSourceFromManifest`, the store keyed by the account `session start` checked. + over `crmSourceFromManifest`, the store keyed by the account `session start` checked. A `tracker` source gets + `src/commands/tracker.ts` in its place: cli-core's tracker commands (`sync`, `issues`, `projects`…) over + `trackerSourceFromManifest`, usually with `spec: { kind: "graphql", from: "" }`. `new` asks the endpoint + for its schema by introspection; a GraphQL schema names no sign-in, so the header the key travels in is `auth` in + `scripts/generate.ts`, the sample's `Authorization` until you check the service's documentation. - Tests come with them: `src/commands/session.test.ts` signs in against a fake of the API, and `src/crm-contracts.test.ts` runs `crmSourceContract` and `crmSyncContract`. `lint/contract-exceptions.json` excepts `crmWriteContract`, as the source only reads. A list the generator finds no paging for fails the contract's - cut-list case on purpose: describe the paging in the API description or an override. + cut-list case on purpose: describe the paging in the API description or an override. A tracker's + `src/tracker-contracts.test.ts` checks the source against the generated API and syncs through the CLI over a fake + of the schema. - `pnpm source:check` checks the source's operations and every path its map reads against the generated API, after `pnpm generate`. @@ -112,15 +118,15 @@ choices. Nothing is guessed. | `--package` | the npm package name | | `--owner` | the GitHub owner | | `--tagline` | the line WireCat Desktop shows, at most 55 characters; left out, it is made from the description | -| `--category` | one for each of cli-core's kinds: `messenger`, `mail`, `notes`, `files`, `meetings`, `calendar`, `crm` | +| `--category` | one for each of cli-core's kinds: `messenger`, `mail`, `notes`, `files`, `meetings`, `calendar`, `crm`; and `tracker` | | `--content-lang` | language codes, several: `en,ru` | | `--sign-in` | `oauth`, `token`, `session`, `none` | | `--api` | `official-client`, `official-docs`, `unofficial` | -| `--spec` | `openapi`, `swagger`, `discovery`, `none`; left out with `--spec-url`, it is the downloaded description's | -| `--spec-url` | the URL of the service's OpenAPI 3 or Swagger 2.0 description, JSON or YAML | +| `--spec` | `openapi`, `swagger`, `discovery`, `graphql`, `none`; left out with `--spec-url`, it is the downloaded description's | +| `--spec-url` | the URL of the service's OpenAPI 3 or Swagger 2.0 description, JSON or YAML; with `--spec graphql`, the endpoint | | `--filters` | several of `time`, `person`, `container`, `text`, `status` | | `--never-store` | several of `tokens`, `codes`, `secret-links`, `content` | -| `--untrusted` | several of `files`, `links`, `names`, and for its category `messages` (messenger, mail), `records` (crm), `invitations` (calendar), `transcripts` (meetings); or `none` alone | +| `--untrusted` | several of `files`, `links`, `names`, and for its category `messages` (messenger, mail), `records` (crm), `issues` (tracker), `invitations` (calendar), `transcripts` (meetings); or `none` alone | Every question except the names, `--tagline` and `--content-lang` also takes `other:`. `--tagline` is the one answer with a default: left out, it is the description cut on a word at 55 characters, and in a terminal an empty diff --git a/kit/seeds/config/scripts/source-check.ts b/kit/seeds/config/scripts/source-check.ts index 60913a2..ca8e958 100644 --- a/kit/seeds/config/scripts/source-check.ts +++ b/kit/seeds/config/scripts/source-check.ts @@ -1,5 +1,6 @@ import { crmManifestProblems, parseCrmManifest } from "@wirecat/cli-core/crm" import { parseCliConfig } from "@wirecat/cli-core/manifest" +import { parseTrackerManifest } from "@wirecat/cli-core/tracker" import { definitions } from "../dist/generated/definitions.js" import * as api from "../dist/generated/manifest.js" import config from "../wirecat.config.ts" @@ -21,6 +22,11 @@ const problemsOf = (): { problems: string[]; crm: boolean } => { ? [`auth.verify: ${verify.operation} is not a read, and session start sends only reads`] : [] if (!cli.source) return { problems: verifying, crm: false } + if (cli.category === "tracker") { + // Refuses a map path the selection leaves out, which would read as "the tracker cleared it". + parseTrackerManifest(cli.source, api) + return { problems: verifying, crm: true } + } return { problems: [...verifying, ...crmManifestProblems(parseCrmManifest(cli.source, api), api, definitions)], crm: true, diff --git a/kit/seeds/config/src/commands/tracker.ts b/kit/seeds/config/src/commands/tracker.ts new file mode 100644 index 0000000..db8418c --- /dev/null +++ b/kit/seeds/config/src/commands/tracker.ts @@ -0,0 +1,77 @@ +import { CliError } from "@wirecat/cli-base" +import { hostFetch, retrying } from "@wirecat/cli-base/http" +import { recalledAccount, serviceApiCall } from "@wirecat/cli-core/cli" +import { openCrmStore } from "@wirecat/cli-core/crm/cli" +import { Pacer, pacePathFor } from "@wirecat/cli-core/sends" +import type { MessageStore } from "@wirecat/cli-core/store" +import { addTrackerCommands, type TrackerRun, trackerSourceFromManifest } from "@wirecat/cli-core/tracker" +import { Command } from "commander" +import { API } from "../config.js" +import { contextOf, PACE, tokenOf } from "../context.js" +import { HOOKS, SOURCE } from "../generated/wirecat-config.js" +import { DESKTOP, IDENTITY } from "../identity.js" + +const provider = (): string => { + if (typeof SOURCE?.provider !== "string") throw new CliError("configuration_error", "wirecat.config.ts has no source") + return SOURCE.provider +} + +// A tracker's items are not a kind the shared search reads yet, so the store gets no provider entry. +const openStore = async (env: NodeJS.ProcessEnv, { readOnly = false } = {}): Promise => { + const { ensureSqlite } = await import("@wirecat/cli-core/sqlite-runtime") + await ensureSqlite() + const { openStore: open, storePath } = await import("@wirecat/cli-core/store") + return open({ + path: storePath(env), + env, + command: IDENTITY.command, + version: IDENTITY.version, + ...(readOnly ? { readOnly } : {}), + }) +} + +// The account is the one `session start` checked the token against; the store keeps each account's rows apart. +const accountOf = (command: Command) => { + const { env, profile } = contextOf(command) + const account = recalledAccount(IDENTITY, provider(), profile, env) + if (!account) + throw new CliError( + "authentication_error", + `${profile} is not signed in; run ${IDENTITY.command} ${profile} session start`, + { reason: "auth.missing" }, + ) + return account +} + +const open = async (command: Command, { readOnly }: { readOnly: boolean }): Promise => { + const { env, profile, environment } = contextOf(command) + const { store, account } = await openCrmStore({ + app: IDENTITY, + env, + profile, + readOnly, + provider: provider(), + open: openStore, + account: () => accountOf(command), + }) + const fetch = retrying( + hostFetch({ hosts: DESKTOP.hosts ?? [], ...(environment.fetch ? { fetch: environment.fetch } : {}) }), + { pacer: new Pacer(pacePathFor(IDENTITY, profile, env), PACE) }, + ) + const call = serviceApiCall({ manifest: API.manifest, service: API.service, fetch, token: () => tokenOf(command) }) + let source: ReturnType | undefined + return { + account, + store, + source: () => + (source ??= trackerSourceFromManifest(SOURCE, { api: API.manifest, call, ...(HOOKS ? { hooks: HOOKS } : {}) })), + close: () => store.close(), + } +} + +/** cli-core's tracker commands over the source wirecat.config.ts describes: sync, issues and the lists. */ +export const trackerCommands = (): Command[] => { + const holder = new Command(IDENTITY.command) + addTrackerCommands(holder, { app: IDENTITY, open }) + return [...holder.commands] +} diff --git a/kit/seeds/config/src/testing/fake-api.ts b/kit/seeds/config/src/testing/fake-api.ts index c5a3410..c2fb4d7 100644 --- a/kit/seeds/config/src/testing/fake-api.ts +++ b/kit/seeds/config/src/testing/fake-api.ts @@ -1,4 +1,4 @@ -import { fakeApi } from "@wirecat/cli-base/codegen" +import { fakeApi, graphqlFake } from "@wirecat/cli-base/codegen" import { manifestBaseUrl } from "@wirecat/cli-core/cli" import { API } from "../config.js" import { definitions } from "../generated/definitions.js" @@ -6,16 +6,33 @@ import { definitions } from "../generated/definitions.js" /** The token fakeServiceApi takes; never a real one (WC-TEST-2). */ export const FAKE_API_TOKEN = "fake0api0token" +const graphql = API.manifest.operations.some((operation) => operation.binding.kind === "graphql") + +// A GraphQL schema names no sign-in: the header is the one scripts/generate.ts sets in `auth`. +const graphqlAuth = (token: string) => { + const scheme = Object.values(API.manifest.securitySchemes ?? {})[0] as { type?: string; in?: string; name?: string } + return scheme?.type === "apiKey" && scheme.in === "header" && scheme.name + ? { header: scheme.name, value: token } + : { header: "Authorization", value: `Bearer ${token}` } +} + /** The service's API as its description says, answering only `token`: a sample of each answer schema. */ export const fakeServiceApi = (token = FAKE_API_TOKEN) => - fakeApi({ - operations: API.manifest.operations, - definitions, - baseUrl: manifestBaseUrl(API.manifest), - security: API.manifest.security, - securitySchemes: API.manifest.securitySchemes, - token, - }) + graphql + ? graphqlFake({ + operations: API.manifest.operations, + definitions, + url: manifestBaseUrl(API.manifest), + auth: graphqlAuth(token), + }) + : fakeApi({ + operations: API.manifest.operations, + definitions, + baseUrl: manifestBaseUrl(API.manifest), + security: API.manifest.security, + securitySchemes: API.manifest.securitySchemes, + token, + }) type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise diff --git a/kit/seeds/config/src/tracker-contracts.test.ts b/kit/seeds/config/src/tracker-contracts.test.ts new file mode 100644 index 0000000..4425e4a --- /dev/null +++ b/kit/seeds/config/src/tracker-contracts.test.ts @@ -0,0 +1,28 @@ +import { memoryKeyring } from "@wirecat/cli-base" +import { parseTrackerManifest } from "@wirecat/cli-core/tracker" +import { expect, it } from "vitest" +import { API } from "./config.js" +import { SOURCE } from "./generated/wirecat-config.js" +import { FAKE_API_TOKEN, fakeServiceApi } from "./testing/fake-api.js" +import { runCli } from "./testing/harness.js" + +it("the source in wirecat.config.ts reads only what the generated API offers and selects", () => { + expect(() => parseTrackerManifest(SOURCE, API.manifest)).not.toThrow() +}) + +// The fake answers a sample of each selection, so this checks the calls, not the mapping of real rows. +it("sync through this CLI sends only calls the schema allows, under the account session start checked", async () => { + const keyring = memoryKeyring() + const fake = fakeServiceApi() + const started = await runCli(["personal", "session", "start", "--json"], { + keyring, + service: fake, + stdin: FAKE_API_TOKEN, + }) + expect(started.code, started.err).toBe(0) + const synced = await runCli(["personal", "sync", "--json"], { keyring, service: fake }) + expect(synced.code, synced.err).toBe(0) + const listed = await runCli(["personal", "issues", "list", "--json"], { keyring, service: fake }) + expect(listed.code, listed.err).toBe(0) + expect(fake.refusals).toEqual([]) +}) diff --git a/kit/seeds/graphql/scripts/generate.ts b/kit/seeds/graphql/scripts/generate.ts new file mode 100644 index 0000000..936009c --- /dev/null +++ b/kit/seeds/graphql/scripts/generate.ts @@ -0,0 +1,71 @@ +import { execFileSync } from "node:child_process" +import { existsSync } from "node:fs" +import { join, resolve } from "node:path" +import { + coverageGenerator, + definitionsGenerator, + generate, + manifestGenerator, + typesGenerator, + valibotGenerator, + writeArtifacts, +} from "@wirecat/cli-base/codegen" +import { specModel } from "./spec-model.ts" + +// The service's API description → src/generated/ and docs/dev/API_COVERAGE.md. Each correction below is read from +// the service's documentation, never guessed; cli-base docs/standards/kit-surface.md says what each one does. +const root = resolve(import.meta.dirname, "..") +// A fresh CLI has no src/generated/ yet and cannot build without it, so build runs this with --if-missing first. +if (process.argv.includes("--if-missing") && existsSync(join(root, "src/generated/manifest.ts"))) process.exit(0) +const { model, notes } = await specModel(root) +const artifacts = generate( + model, + [ + typesGenerator({ path: "src/generated/types.ts" }), + valibotGenerator({ path: "src/generated/schemas.ts", typesImport: "./types.js" }), + manifestGenerator({ path: "src/generated/manifest.ts" }), + definitionsGenerator({ path: "src/generated/definitions.ts" }), + coverageGenerator({ + path: "docs/dev/API_COVERAGE.md", + title: "API coverage", + command: (operation) => `clidev api ${operation.command}`, + }), + ], + { + banner: ["Source: spec/clidev/, checked against provenance.json", "Run: pnpm generate"], + // SAMPLE: operation id → { effect, reason } where the HTTP method misleads, as a POST that deletes. + overrides: {}, + // SAMPLE: true when the service's POST …/search and …/query only read. + readingPosts: false, + // SAMPLE: command names from the paths; map an operation whose name comes out wrong in `commands`. + names: { fromPath: true }, + // SAMPLE: the permission group, and the body fields or query parameters that delete when true. + permissions: { group: "comments", deletingFlags: [] }, + // SAMPLE: how each read pages, found from the spec; an override's `pagination` wins. + pagination: true, + // SAMPLE: a GraphQL schema names no sign-in, so the header the token travels in is set here, from the service's + // documentation: an API key as it is (`Authorization: `), or `{ type: "http", scheme: "bearer" }`. + auth: { + securitySchemes: { key: { type: "apiKey", in: "header", name: "Authorization" } }, + security: [{ key: [] }], + reason: "a GraphQL schema names no sign-in; the service's documentation sends the key in Authorization", + }, + }, +) +const coverage = artifacts.find((artifact) => artifact.path === "docs/dev/API_COVERAGE.md") +if (coverage && notes.length) + coverage.content += ["", "## Spec corrections", "", ...notes.map((n) => `- ${n}`), ""].join("\n") +const format = (path: string, content: string) => + path.endsWith(".ts") + ? execFileSync( + process.execPath, + [`${root}/node_modules/@biomejs/biome/bin/biome`, "check", "--write", `--stdin-file-path=${path}`], + { cwd: root, encoding: "utf8", input: content, maxBuffer: 64 * 1024 * 1024 }, + ) + : content +const check = process.argv.includes("--check") +const stale = writeArtifacts(artifacts, { root, check, format }) +if (check && stale.length) { + process.stderr.write(`Generated files are stale: ${stale.join(", ")}; run pnpm generate\n`) + process.exitCode = 1 +} diff --git a/kit/seeds/graphql/scripts/spec-model.ts b/kit/seeds/graphql/scripts/spec-model.ts new file mode 100644 index 0000000..162d2fb --- /dev/null +++ b/kit/seeds/graphql/scripts/spec-model.ts @@ -0,0 +1,20 @@ +import { join } from "node:path" +import { type ApiModel, adaptGraphql, readGraphql } from "@wirecat/cli-base/codegen" + +// SAMPLE: the endpoint every operation is sent to. +const URL = "https://comments.example.invalid/graphql" + +/** The schema as committed; readGraphql refuses one whose hash no longer matches provenance.json. */ +export const specModel = async (root: string): Promise<{ model: ApiModel; notes: string[] }> => { + const dir = join(root, "spec/clidev") + const model = adaptGraphql(readGraphql(dir), { + url: URL, + sourceUrl: URL, + // SAMPLE: the schema's own scalars as the JSON they travel as, such as { DateTime: { type: "string" } }; a scalar + // left out stops generation. + scalars: {}, + // SAMPLE: field → why the CLI leaves it out, as `mutation.` when both roots have one of that name. + exclude: {}, + }) + return { model, notes: [] } +} diff --git a/kit/seeds/graphql/scripts/sync-spec.ts b/kit/seeds/graphql/scripts/sync-spec.ts new file mode 100644 index 0000000..a75fb15 --- /dev/null +++ b/kit/seeds/graphql/scripts/sync-spec.ts @@ -0,0 +1,10 @@ +import { resolve } from "node:path" +import { syncGraphql } from "@wirecat/cli-base/codegen" + +// SAMPLE: the endpoint; a service that answers introspection only when signed in takes `headers` read from the +// keyring here, never written. The made-up Example Comments address never resolves. +await syncGraphql({ + url: "https://comments.example.invalid/graphql", + dir: resolve(import.meta.dirname, "../spec/clidev"), +}) +process.stderr.write("The GraphQL schema is refreshed; review its diff, then run pnpm generate\n") diff --git a/kit/seeds/graphql/spec/clidev/provenance.json b/kit/seeds/graphql/spec/clidev/provenance.json new file mode 100644 index 0000000..4cee29f --- /dev/null +++ b/kit/seeds/graphql/spec/clidev/provenance.json @@ -0,0 +1,6 @@ +{ + "source": "https://comments.example.invalid/graphql", + "sha256": "d7edcd7d435219f677916dab06fcf56423250500bb933183ce43458be2fd9685", + "retrieved_at": "2026-11-17T00:00:00.000Z", + "normalization": "types sorted by name, object keys sorted, 2-space JSON" +} diff --git a/kit/seeds/graphql/spec/clidev/schema.json b/kit/seeds/graphql/spec/clidev/schema.json new file mode 100644 index 0000000..2157a81 --- /dev/null +++ b/kit/seeds/graphql/spec/clidev/schema.json @@ -0,0 +1,414 @@ +{ + "__schema": { + "mutationType": { + "name": "Mutation" + }, + "queryType": { + "name": "Query" + }, + "types": [ + { + "description": null, + "enumValues": null, + "fields": null, + "inputFields": null, + "kind": "SCALAR", + "name": "Boolean", + "possibleTypes": null + }, + { + "description": "A comment", + "enumValues": null, + "fields": [ + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "id", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "body", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "createdAt", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + ], + "inputFields": null, + "kind": "OBJECT", + "name": "Comment", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": [ + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "nodes", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Comment", + "ofType": null + } + } + } + } + }, + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "pageInfo", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + } + } + ], + "inputFields": null, + "kind": "OBJECT", + "name": "CommentConnection", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": null, + "inputFields": [ + { + "defaultValue": null, + "description": "The comment's text", + "name": "body", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + ], + "kind": "INPUT_OBJECT", + "name": "CommentCreateInput", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": [ + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "success", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + } + }, + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "comment", + "type": { + "kind": "OBJECT", + "name": "Comment", + "ofType": null + } + } + ], + "inputFields": null, + "kind": "OBJECT", + "name": "CommentPayload", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": [ + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "success", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + } + } + ], + "inputFields": null, + "kind": "OBJECT", + "name": "DeletePayload", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": null, + "inputFields": null, + "kind": "SCALAR", + "name": "ID", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": null, + "inputFields": null, + "kind": "SCALAR", + "name": "Int", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": [ + { + "args": [ + { + "defaultValue": null, + "description": null, + "name": "input", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CommentCreateInput", + "ofType": null + } + } + } + ], + "description": "Adds a comment", + "isDeprecated": false, + "name": "commentCreate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CommentPayload", + "ofType": null + } + } + }, + { + "args": [ + { + "defaultValue": null, + "description": null, + "name": "id", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + } + ], + "description": "Deletes a comment", + "isDeprecated": false, + "name": "commentDelete", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DeletePayload", + "ofType": null + } + } + } + ], + "inputFields": null, + "kind": "OBJECT", + "name": "Mutation", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": [ + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "hasNextPage", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + } + }, + { + "args": [], + "description": null, + "isDeprecated": false, + "name": "endCursor", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + ], + "inputFields": null, + "kind": "OBJECT", + "name": "PageInfo", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": [ + { + "args": [ + { + "defaultValue": null, + "description": "How many comments on one page", + "name": "first", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + { + "defaultValue": null, + "description": "The cursor of the page before", + "name": "after", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + ], + "description": "Every comment, newest first", + "isDeprecated": false, + "name": "comments", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CommentConnection", + "ofType": null + } + } + }, + { + "args": [ + { + "defaultValue": null, + "description": "The comment's id", + "name": "id", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + } + ], + "description": "One comment by its id", + "isDeprecated": false, + "name": "comment", + "type": { + "kind": "OBJECT", + "name": "Comment", + "ofType": null + } + } + ], + "inputFields": null, + "kind": "OBJECT", + "name": "Query", + "possibleTypes": null + }, + { + "description": null, + "enumValues": null, + "fields": null, + "inputFields": null, + "kind": "SCALAR", + "name": "String", + "possibleTypes": null + } + ] + } +} diff --git a/kit/seeds/graphql/src/api.test.ts b/kit/seeds/graphql/src/api.test.ts new file mode 100644 index 0000000..ffa6c6d --- /dev/null +++ b/kit/seeds/graphql/src/api.test.ts @@ -0,0 +1,85 @@ +import { mkdirSync, rmSync, writeFileSync } from "node:fs" +import { join } from "node:path" +import { graphqlFake, sampleOf } from "@wirecat/cli-base/codegen" +import { apiFlagOf, manifestBaseUrl, sendsBytes } from "@wirecat/cli-core/cli" +import { afterEach, expect, it } from "vitest" +import { API } from "./config.js" +import { definitions } from "./generated/definitions.js" +import { FAKE_TOKEN } from "./testing/fake-comments.js" +import { runCli } from "./testing/harness.js" + +const configFile = join(process.env.CLIDEV_CONFIG_DIR ?? "", "config.json") +const upload = join(process.env.CLIDEV_CONFIG_DIR ?? "", "..", "upload.bin") +const withPermissions = (permissions: Record) => { + mkdirSync(join(configFile, ".."), { recursive: true }) + writeFileSync(configFile, JSON.stringify({ profiles: { personal: { permissions } } })) +} +afterEach(() => { + rmSync(configFile, { force: true }) + rmSync(upload, { force: true }) +}) + +type Operation = (typeof API.manifest.operations)[number] + +// The fake checks each call's document against the schema (the operation, the selection, the variables) and the key. +const fake = () => + graphqlFake({ + operations: API.manifest.operations, + definitions, + url: manifestBaseUrl(API.manifest), + auth: { header: "Authorization", value: FAKE_TOKEN }, + }) + +const deleteKeys = [ + ...new Set( + API.manifest.operations.flatMap((operation) => + (operation.permissions ?? []).map((permission) => permission.key).filter((key) => key.endsWith(".delete")), + ), + ), +] + +const argsOf = (operation: Operation) => [ + ...operation.parameters + .filter((parameter) => parameter.required) + .flatMap((parameter) => [`--${apiFlagOf(parameter.name)}`, String(sampleOf(parameter.schema, definitions))]), + ...(sendsBytes(operation) ? ["--body-file", upload] : []), + ...(operation.request?.schema + ? ["--body", JSON.stringify(sampleOf({ type: "ref", ref: operation.request.schema }, definitions))] + : []), + ...(operation.effect === "destructive" ? ["--yes"] : []), +] + +it("the spec offers operations", () => { + expect(API.manifest.operations.length).toBeGreaterThan(0) +}) + +// One test each, so a large API stays inside the per-test timeout and a failure names its operation. +it.each(API.manifest.operations.map((operation) => [operation.command, operation] as const))( + "sends %s as the spec describes it", + async (_, operation) => { + writeFileSync(upload, new Uint8Array([0x89, 0x50, 0x4e, 0x47])) + withPermissions({ api: "allow", ...Object.fromEntries(deleteKeys.map((key) => [key, "allow"])) }) + const service = fake() + const ran = await runCli(["personal", "api", operation.command, ...argsOf(operation), "--json"], { service }) + expect(ran.code, ran.err).toBe(0) + expect(service.refusals).toEqual([]) + expect(service.calls).toHaveLength(1) + }, +) + +const destructive = API.manifest.operations.filter((operation) => operation.effect === "destructive") + +// A service whose API only reads has no delete to check. +it.runIf(destructive.length > 0)( + "a delete through api checks the manifest's delete key too, before anything is sent", + async () => { + expect(deleteKeys.length).toBeGreaterThan(0) + withPermissions({ api: "allow", ...Object.fromEntries(deleteKeys.map((key) => [key, "deny"])) }) + const service = fake() + for (const operation of destructive) { + const ran = await runCli(["personal", "api", operation.command, ...argsOf(operation), "--json"], { service }) + expect(ran.json()).toMatchObject({ error: { code: "permission_error" } }) + } + expect(service.calls).toEqual([]) + }, +) diff --git a/kit/skills/new-cli/SKILL.md b/kit/skills/new-cli/SKILL.md index b8a0fec..0a2cd96 100644 --- a/kit/skills/new-cli/SKILL.md +++ b/kit/skills/new-cli/SKILL.md @@ -108,14 +108,14 @@ without one: ```sh npx @wirecat/cli-template new -cli --command --package @wirecat/-cli --owner WireCatLabs \ - --category messenger|mail|notes|files|meetings|calendar|crm|other: \ + --category messenger|mail|notes|files|meetings|calendar|crm|tracker|other: \ --content-lang \ --sign-in oauth|token|session|none \ --api official-client|official-docs|unofficial \ - --spec openapi|swagger|discovery|none \ + --spec openapi|swagger|discovery|graphql|none \ --filters time,person,container,text,status \ --never-store tokens,codes,secret-links,content \ - --untrusted messages,records,invitations,transcripts,files,links,names|none + --untrusted messages,records,issues,invitations,transcripts,files,links,names|none ``` `--api` is what the service offers; `--spec` is the API description `new` builds the `api` group from. With a spec, diff --git a/kit/src/from-config.ts b/kit/src/from-config.ts index a6706ad..0cb9e42 100644 --- a/kit/src/from-config.ts +++ b/kit/src/from-config.ts @@ -46,12 +46,14 @@ export const loadCliConfig = async (path: string): Promise => { throw new Error(`${path}: export the config as default: export default defineCli({…})`) const config = parseCliConfig(module.default) const verifies = config.auth.preset === "token" && config.auth.verify !== undefined - // The CRM commands key the store by the account session start checked; the sample's session checks nothing real. + // The source's commands key the store by the account session start checked; the sample's session checks nothing. if (config.source && !verifies) throw new Error( - 'wirecat.config: auth: a CRM source needs auth: { preset: "token", verify: { … } } yet, so session start ' + + 'wirecat.config: auth: a source needs auth: { preset: "token", verify: { … } } yet, so session start ' + "checks the token and names the account", ) + if (config.category === "crm" && config.spec.kind === "graphql") + throw new Error("wirecat.config: a CRM source reads an OpenAPI description yet; spec.kind graphql is for a tracker") return { config, text: await readFile(full, "utf8"), pending: notWiredYet(config), verifies } } @@ -64,9 +66,15 @@ const notWiredYet = (config: CliConfig): string[] => [ ...(config.auth.preset === "token" && !config.auth.verify ? ["auth.verify: the call that checks a token; without it at new, session keeps the template's sample"] : []), - ...(config.source + ...(config.source && config.category === "crm" ? ["source: the CRM's write commands (crmWriteContract is excepted in lint/contract-exceptions.json)"] : []), + ...(config.source && config.category === "tracker" + ? ["source: the tracker's write commands, and its items in the shared search; sync and the reads are built"] + : []), + ...(config.spec.kind === "graphql" + ? ["auth: the header the key travels in is the sample's Authorization in scripts/generate.ts; check its docs"] + : []), ] /** The answers the config gives; the rest come from flags or the terminal, as without it. */ diff --git a/kit/src/interview.ts b/kit/src/interview.ts index e6d3134..00377a9 100644 --- a/kit/src/interview.ts +++ b/kit/src/interview.ts @@ -63,7 +63,8 @@ export const INTERVIEW: Question[] = [ title: "Category", flag: "category", text: "What kind of tool is it?", - choices: Object.values(CATEGORIES), + // A tracker's items are not a kind a search reads yet, so it has no key in CATEGORIES. + choices: [...Object.values(CATEGORIES), { value: "tracker", label: "issue tracker (issues, projects, teams)" }], }, { key: "contentLang", @@ -105,6 +106,7 @@ export const INTERVIEW: Question[] = [ { value: "openapi", label: "OpenAPI 3.0 or 3.1" }, { value: "swagger", label: "Swagger 2.0" }, { value: "discovery", label: "Google Discovery" }, + { value: "graphql", label: "a GraphQL schema (introspection)" }, { value: "none", label: "none" }, ], }, @@ -145,6 +147,7 @@ export const INTERVIEW: Question[] = [ choices: [ { value: "messages", label: "messages from other people", categories: ["messenger", "mail"] }, { value: "records", label: "deals, contacts and comments others entered", categories: ["crm"] }, + { value: "issues", label: "issues and comments others wrote", categories: ["tracker"] }, { value: "invitations", label: "invitations and event descriptions from others", categories: ["calendar"] }, { value: "transcripts", label: "what other attendees said or wrote", categories: ["meetings"] }, { value: "files", label: "files and attachments" }, diff --git a/kit/src/main.ts b/kit/src/main.ts index 5119c68..127b1b3 100644 --- a/kit/src/main.ts +++ b/kit/src/main.ts @@ -17,7 +17,7 @@ new asks for every missing answer in a terminal; without one, a missing answer i --owner the GitHub owner of the repository --tagline ${TAGLINE_QUESTION.text}; left out, it is made from the description --spec-url download the service's OpenAPI 3 or Swagger 2.0 description, JSON or YAML, for the api group; - https only, or http from localhost + with --spec graphql, ask that endpoint for its schema; https only, or http from localhost --from-config take the names, the API description's URL, the sign-in and the category from a wirecat.config.ts (defineCli from @wirecat/cli-core/manifest), and copy it into the CLI with pnpm source:check; leave out and the flags it sets diff --git a/kit/src/new.ts b/kit/src/new.ts index db7424b..7bb8844 100644 --- a/kit/src/new.ts +++ b/kit/src/new.ts @@ -37,7 +37,7 @@ import { withServicePage, withSpecPackage, } from "./spec.js" -import { type DownloadedSpec, downloadSpec, type SpecFetch } from "./spec-url.js" +import { type DownloadedSpec, downloadSpec, introspectSpec, type SpecFetch } from "./spec-url.js" const run = promisify(execFile) @@ -515,10 +515,11 @@ export const withoutSignInCheck = (text: string): string => { export const withoutApiSignIn = (path: string, text: string): string => { const cuts: Record = { "src/commands/api.ts": [/^ \* The token is the profile's own.*\n/m, /^ {4}token: tokenOf,\n/m, /, tokenOf(?= \})/], - "src/api.test.ts": [/^import \{ FAKE_TOKEN \} from .*\n/m, /^ {4}token: FAKE_TOKEN,\n/m], + "src/api.test.ts": [/^import \{ FAKE_TOKEN \} from .*\n/m, /^ {4}(token: FAKE_TOKEN|auth: \{ .* \}),\n/m], + "scripts/generate.ts": [/^ {4}\/\/ SAMPLE: a GraphQL schema names no sign-in[\s\S]*?\n {4}\},\n/m], } const own = cuts[path] - if (!own) return text + if (!own || (path === "scripts/generate.ts" && !text.includes("auth: {"))) return text if (own.some((cut) => !cut.test(text))) throw new Error(`${path}: no token to take out of the api group`) return own.reduce((rest, cut) => rest.replace(cut, ""), text) } @@ -715,8 +716,9 @@ export const sharedListEntries = (names: Names, tagline: string, time: MonthlyTi const specFromUrl = async (args: NewArgs, fetch: SpecFetch | undefined): Promise => { const url = args.flags["spec-url"] if (url === undefined) return undefined - const downloaded = await downloadSpec(url, fetch) const given = args.flags.spec + if (given === "graphql") return introspectSpec(url, fetch) + const downloaded = await downloadSpec(url, fetch) if (given !== undefined && given !== downloaded.kind) throw new Error( `--spec ${given}: ${downloaded.url} is ${downloaded.kind === "swagger" ? "Swagger 2.0" : "OpenAPI 3"}`, @@ -729,19 +731,26 @@ const SOURCE_CHECK = "scripts/source-check.ts" const FROM_CONFIG = "scripts/from-config.ts" const SESSION = ["src/commands/session.ts", "src/commands/session.test.ts", "src/testing/fake-api.ts"] const CRM = ["src/commands/crm.ts", "src/crm-contracts.test.ts", "lint/contract-exceptions.json"] +const TRACKER = ["src/commands/tracker.ts", "src/tracker-contracts.test.ts"] + +const sourceKind = (config: LoadedConfig["config"]): "crm" | "tracker" => + config.category === "tracker" ? "tracker" : "crm" -/** cli-core's CRM commands over the config's source, beside the api group. */ -export const withCrmCommands = (text: string): string => +const sourceSeeds = (config: LoadedConfig["config"]): string[] => + !config.source ? [] : sourceKind(config) === "tracker" ? TRACKER : CRM + +/** cli-core's commands for the config's source (`crm` or `tracker`), beside the api group. */ +export const withSourceCommands = (text: string, kind: "crm" | "tracker" = "crm"): string => replaceOnce( "src/program.ts", replaceOnce( "src/program.ts", text, 'import { apiCommand } from "./commands/api.js"\n', - 'import { apiCommand } from "./commands/api.js"\nimport { crmCommands } from "./commands/crm.js"\n', + `import { apiCommand } from "./commands/api.js"\nimport { ${kind}Commands } from "./commands/${kind}.js"\n`, ), /^( +)apiCommand\(\),\n/m, - "$1apiCommand(),\n$1...crmCommands(),\n", + `$1apiCommand(),\n$1...${kind}Commands(),\n`, ) const RUN_SCOPE = "src/run-scope.test.ts" @@ -750,7 +759,10 @@ const RUN_SCOPE = "src/run-scope.test.ts" * run-scope over a config's wiring: `session start` checks the token with the API, so the answering fake answers the * API's host too; `sync` is cli-core's, run in its own run and tested by crmSyncContract. */ -export const withConfigRunScope = (text: string, { verifies, crm }: { verifies: boolean; crm: boolean }): string => { +export const withConfigRunScope = ( + text: string, + { verifies, source }: { verifies: boolean; source?: "crm" | "tracker" }, +): string => { const answering = verifies ? replaceOnce( RUN_SCOPE, @@ -764,16 +776,16 @@ export const withConfigRunScope = (text: string, { verifies, crm }: { verifies: "fetch: withServiceApi(fakeComments(), FAKE_TOKEN).fetch, stdin: stdin()", ) : text - return crm + const sync = { + crm: ' sync: "cli-core\'s addCrmCommands runs it in its run; src/crm-contracts.test.ts runs crmSyncContract",', + tracker: ' sync: "cli-core\'s addTrackerCommands runs it in its run; src/tracker-contracts.test.ts syncs",', + } + return source ? replaceOnce( RUN_SCOPE, answering, ' "mcp serve": "listens until stopped",\n', - [ - ' "mcp serve": "listens until stopped",', - ' sync: "cli-core\'s addCrmCommands runs it in its run; src/crm-contracts.test.ts runs crmSyncContract",', - "", - ].join("\n"), + [' "mcp serve": "listens until stopped",', sync[source], ""].join("\n"), ) : answering } @@ -839,14 +851,14 @@ export const runNew = async ( loaded ? withConfigRunScope(withApiRunScope(text), { verifies: loaded.verifies, - crm: Boolean(loaded.config.source), + ...(loaded.config.source ? { source: sourceKind(loaded.config) } : {}), }) : withApiRunScope(text), } : {}), "src/program.ts": (text: string) => { const api = spec ? withApiCommand(text) : text - const program = loaded?.config.source ? withCrmCommands(api) : api + const program = loaded?.config.source ? withSourceCommands(api, sourceKind(loaded.config)) : api return answers.signIn?.[0] === "none" ? withoutSignInCheck(program) : program }, "README.md": () => @@ -914,7 +926,7 @@ export const runNew = async ( } if (loaded) { await writeOut(target, CONFIG_FILE, loaded.text) - const seeds = [SOURCE_CHECK, FROM_CONFIG, ...(loaded.verifies ? SESSION : []), ...(loaded.config.source ? CRM : [])] + const seeds = [SOURCE_CHECK, FROM_CONFIG, ...(loaded.verifies ? SESSION : []), ...sourceSeeds(loaded.config)] for (const path of seeds) await writeOut(target, path, await readFile(join(source.root, "kit/seeds/config", path))) } if (!rendered.has("AGENTS.md")) await writeOut(target, "AGENTS.md", withReference("", category)) diff --git a/kit/src/spec-url.ts b/kit/src/spec-url.ts index 778817b..056e5f6 100644 --- a/kit/src/spec-url.ts +++ b/kit/src/spec-url.ts @@ -1,4 +1,7 @@ import { createHash } from "node:crypto" +import { mkdtemp, readFile, rm } from "node:fs/promises" +import { tmpdir } from "node:os" +import { join } from "node:path" import { isRecord } from "./manifest.js" import type { SpecKind } from "./spec.js" @@ -16,6 +19,8 @@ export type DownloadedSpec = { kind: Exclude file: string text: string + /** provenance.json as written; absent, new writes it from `url` and `sha256`. */ + provenance?: string sha256: string title: string operations: number @@ -169,3 +174,38 @@ export const downloadSpec = async ( ...serversOf(kind, document, url), } } + +const rootFields = (schema: unknown): number => { + const inner = isRecord(schema) && isRecord(schema.__schema) ? schema.__schema : {} + const roots = [inner.queryType, inner.mutationType].flatMap((root) => (isRecord(root) ? [root.name] : [])) + const types = Array.isArray(inner.types) ? inner.types.filter(isRecord) : [] + return types + .filter((type) => roots.includes(type.name)) + .reduce((sum, type) => sum + (Array.isArray(type.fields) ? type.fields.length : 0), 0) +} + +/** The endpoint's schema, asked by introspection as `pnpm spec:sync` asks it, so the first sync is no diff. */ +export const introspectSpec = async (raw: string, fetch: SpecFetch = globalThis.fetch): Promise => { + const url = checkSpecUrl(raw) + const dir = await mkdtemp(join(tmpdir(), "clidev-graphql-")) + try { + const { syncGraphql } = await import("@wirecat/cli-base/codegen") + const provenance = await syncGraphql({ url: url.href, dir, fetch: fetch as typeof globalThis.fetch }) + const text = await readFile(join(dir, "schema.json"), "utf8") + return { + url: url.href, + kind: "graphql", + file: "schema.json", + text, + provenance: await readFile(join(dir, "provenance.json"), "utf8"), + sha256: provenance.sha256, + title: url.hostname, + operations: rootFields(JSON.parse(text)), + hosts: [url.hostname], + patches: [], + prefix: [], + } + } finally { + await rm(dir, { recursive: true, force: true }) + } +} diff --git a/kit/src/spec.ts b/kit/src/spec.ts index e9ababe..3bd1f23 100644 --- a/kit/src/spec.ts +++ b/kit/src/spec.ts @@ -6,7 +6,7 @@ import { renameContent, renamer } from "./rename.js" import type { TemplateSource } from "./source.js" import type { DownloadedSpec } from "./spec-url.js" -export const SPEC_KINDS = ["openapi", "swagger", "discovery"] as const +export const SPEC_KINDS = ["openapi", "swagger", "discovery", "graphql"] as const export type SpecKind = (typeof SPEC_KINDS)[number] export const specKindOf = (answer: string | undefined): SpecKind | undefined => @@ -28,7 +28,8 @@ const walk = async (dir: string): Promise => { export const specSeeds = async (source: TemplateSource, names: Names, kind: SpecKind): Promise> => { const rename = renamer(source.manifest.placeholders, names) const files = new Map() - for (const part of ["shared", kind === "discovery" ? "" : "openapi-scripts", kind].filter(Boolean)) { + const openapi = kind === "openapi" || kind === "swagger" + for (const part of ["shared", openapi ? "openapi-scripts" : "", kind].filter(Boolean)) { const dir = join(source.root, SEEDS, part) for (const full of await walk(dir)) { const path = relative(dir, full).split(sep).join("/") @@ -63,7 +64,7 @@ export const withSpecPackage = ( step("build", `${GENERATE} --if-missing`) step("typecheck", `${GENERATE} --if-missing`) scripts["spec:sync"] = "node --experimental-strip-types scripts/sync-spec.ts" - if (kind !== "discovery") { + if (kind === "openapi" || kind === "swagger") { if (!yaml) throw new Error("the template's package.json pins no yaml, which reads a YAML description") pkg.devDependencies = { ...(isRecord(pkg.devDependencies) ? pkg.devDependencies : {}), yaml } } @@ -190,7 +191,7 @@ export const withApiSkill = (text: string): string => ], ].reduce((rest, [from = "", to = ""]) => replaceOnce("scripts/commands.ts", rest, from, to), text) -const SAMPLE_DOCUMENTS = ["openapi.json", "swagger.json", "provenance.json"] +const SAMPLE_DOCUMENTS = ["openapi.json", "swagger.json", "schema.json", "provenance.json"] /** The seeds with the downloaded description in place of the sample's, its corrections, and its own permission group. */ export const withDownloadedSpec = ( @@ -206,12 +207,17 @@ export const withDownloadedSpec = ( retrieved_at: now.toISOString(), } files.set(`${dir}/${spec.file}`, Buffer.from(spec.text)) - files.set(`${dir}/provenance.json`, Buffer.from(`${JSON.stringify(provenance, null, 2)}\n`)) + files.set(`${dir}/provenance.json`, Buffer.from(spec.provenance ?? `${JSON.stringify(provenance, null, 2)}\n`)) const edit = (path: string, from: string, to: string) => { const text = files.get(path)?.toString("utf8") ?? "" files.set(path, Buffer.from(replaceOnce(path, text, from, to))) } edit("scripts/generate.ts", 'group: "comments"', `group: ${JSON.stringify(names.command)}`) + if (spec.kind === "graphql") { + const sample = '"https://comments.example.invalid/graphql"' + edit("scripts/spec-model.ts", sample, JSON.stringify(spec.url)) + edit("scripts/sync-spec.ts", sample, JSON.stringify(spec.url)) + } if (spec.prefix.length) edit( "scripts/generate.ts", diff --git a/kit/test/from-config.test.ts b/kit/test/from-config.test.ts index 614cb9a..c8245e3 100644 --- a/kit/test/from-config.test.ts +++ b/kit/test/from-config.test.ts @@ -119,7 +119,7 @@ describe("new --from-config", () => { CONFIG.replace('category: "other",', 'category: "crm",\n source: { provider: "acme" },'), ) - await expect(loadCliConfig(join(cwd, "wirecat.config.ts"))).rejects.toThrow("a CRM source needs auth") + await expect(loadCliConfig(join(cwd, "wirecat.config.ts"))).rejects.toThrow("a source needs auth") }) it("refuses a flag or a folder name the config already sets", async () => { diff --git a/kit/test/new.test.ts b/kit/test/new.test.ts index 6aee0a9..2b609a8 100644 --- a/kit/test/new.test.ts +++ b/kit/test/new.test.ts @@ -189,12 +189,12 @@ describe("new", () => { const cwd = tempDir("ask") const source = await loadSource(fixture("0.1.0", V1)) const { category: _, filters: __, owner: ___, ...flags } = NOTES_FLAGS - const terminal = io(["Example-Org", "", "9", "1", "2,6", "by location"], true) + const terminal = io(["Example-Org", "", "10", "1", "2,6", "by location"], true) await runNew(cwd, source, { name: "cal-cli", flags }, terminal) const design = read(join(cwd, "cal-cli"), "docs/dev/DESIGN.md") - expect(terminal.text()).toContain('"9" is not one of the choices') + expect(terminal.text()).toContain('"10" is not one of the choices') expect(design).toContain("**Category:** messenger") expect(design).toContain("**How people filter:** by person, other: by location") expect(JSON.parse(read(join(cwd, "cal-cli"), "template.json")).names.owner).toBe("Example-Org") @@ -210,8 +210,8 @@ describe("new", () => { } }) - it("offers one category for each of cli-core's kinds", () => { - expect(INTERVIEW.find((question) => question.key === "category")?.choices).toHaveLength(KINDS.length) + it("offers one category for each of cli-core's kinds, and the tracker", () => { + expect(INTERVIEW.find((question) => question.key === "category")?.choices).toHaveLength(KINDS.length + 1) }) it("offers the untrusted input of the category in the menu, and takes any choice as a flag", async () => { diff --git a/kit/test/seeds.test.ts b/kit/test/seeds.test.ts index 6584793..9d7411b 100644 --- a/kit/test/seeds.test.ts +++ b/kit/test/seeds.test.ts @@ -35,6 +35,28 @@ describe("the --spec seeds", () => { }) }) +it("graphql: the endpoint as its one server, one command per root field, a delete key, a key in a header", async () => { + const model = await modelOf("graphql", "graphql") + const [manifest] = generate(model, [manifestGenerator({ path: "manifest.ts" })], { + banner: ["test"], + names: { fromPath: true }, + permissions: { group: "comments" }, + auth: { + securitySchemes: { key: { type: "apiKey", in: "header", name: "Authorization" } }, + security: [{ key: [] }], + reason: "test", + }, + }) + + expect(model.servers?.map((one) => one.url)).toEqual(["https://comments.example.invalid/graphql"]) + for (const command of ["comments", "comment", "comment-create", "comment-delete"]) + expect(manifest?.content).toContain(`"command": "${command}"`) + expect(manifest?.content).toContain('"key": "comments.delete"') + expect(readFileSync(join(seeds, "graphql/scripts/generate.ts"), "utf8")).toContain( + 'securitySchemes: { key: { type: "apiKey", in: "header", name: "Authorization" } }', + ) +}) + it("gives a CLI without sign-in an api group and a test fake with no token", () => { const seed = (path: string) => readFileSync(join(seeds, "shared", path), "utf8") const api = withoutApiSignIn("src/commands/api.ts", seed("src/commands/api.ts")) @@ -45,3 +67,12 @@ it("gives a CLI without sign-in an api group and a test fake with no token", () expect(withoutApiSignIn("src/config.ts", "as it was")).toBe("as it was") expect(() => withoutApiSignIn("src/commands/api.ts", "")).toThrow("src/commands/api.ts: no token to take out") }) + +it("takes the key out of a GraphQL CLI without sign-in: the fake's header and the generator's auth", () => { + const seed = (path: string) => readFileSync(join(seeds, "graphql", path), "utf8") + const test = withoutApiSignIn("src/api.test.ts", seed("src/api.test.ts")) + const generator = withoutApiSignIn("scripts/generate.ts", seed("scripts/generate.ts")) + expect(test).not.toContain("FAKE_TOKEN") + expect(generator).not.toContain("auth:") + expect(generator).toContain("pagination: true,\n },") +}) diff --git a/kit/test/spec-url.test.ts b/kit/test/spec-url.test.ts index c9d526b..0d96d20 100644 --- a/kit/test/spec-url.test.ts +++ b/kit/test/spec-url.test.ts @@ -1,5 +1,5 @@ import { createHash } from "node:crypto" -import { existsSync } from "node:fs" +import { existsSync, readFileSync } from "node:fs" import { join } from "node:path" import { afterAll, describe, expect, it } from "vitest" import { runNew } from "../src/new.js" @@ -189,3 +189,31 @@ describe("a CLI made with --spec", () => { expect(read(join(cwd, "cal-cli"), "scripts/generate.ts")).toContain('process.argv.includes("--if-missing")') }) }) + +describe("new --spec graphql --spec-url", () => { + const root = join(import.meta.dirname, "../..") + const schema = readFileSync(join(import.meta.dirname, "../seeds/graphql/spec/clidev/schema.json"), "utf8") + const flags = { ...NOTES_FLAGS, spec: "graphql", "spec-url": "https://api.notes.example/graphql" } + + it("asks the endpoint for its schema as spec:sync does, and points the scripts at it", async () => { + const cwd = tempDir("spec-graphql") + const { fetch, asked } = serve({ body: JSON.stringify({ data: JSON.parse(schema) }) }) + + const out = await runNew(cwd, await loadSource(root), { name: "cal-cli", flags }, io(), fetch) + + const dir = join(cwd, "cal-cli") + expect(asked.map((one) => [one.url, one.init.method])).toEqual([["https://api.notes.example/graphql", "POST"]]) + expect(read(dir, "spec/cal/schema.json")).toBe(schema) + const provenance = JSON.parse(read(dir, "spec/cal/provenance.json")) + expect(provenance).toMatchObject({ + source: "https://api.notes.example/graphql", + sha256: createHash("sha256").update(schema).digest("hex"), + }) + expect(read(dir, "scripts/spec-model.ts")).toContain('const URL = "https://api.notes.example/graphql"') + expect(read(dir, "scripts/sync-spec.ts")).toContain('url: "https://api.notes.example/graphql"') + expect(read(dir, "scripts/generate.ts")).toContain('group: "cal"') + expect(read(dir, "src/identity.ts")).toContain('"api.notes.example"') + expect(JSON.parse(read(dir, "package.json")).devDependencies.yaml).toBeUndefined() + expect(out).toContain("Downloaded api.notes.example, 4 operations, into spec/cal/schema.json") + }) +}) From af5a85876c4dd5cf5c04fafea1ce07bf325b71bd Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 23:48:14 +0100 Subject: [PATCH 2/3] fix(kit): a tracker CLI without hooks types them as a tracker's, and its sync test fails on a failed kind Co-Authored-By: Claude Opus 5.5 --- kit/seeds/config/scripts/from-config.ts | 18 ++++++++++++------ kit/seeds/config/scripts/source-check.ts | 14 +++++++------- kit/seeds/config/src/tracker-contracts.test.ts | 2 ++ kit/src/from-config.ts | 2 +- kit/src/new.ts | 2 +- kit/src/spec-url.ts | 1 + 6 files changed, 24 insertions(+), 15 deletions(-) diff --git a/kit/seeds/config/scripts/from-config.ts b/kit/seeds/config/scripts/from-config.ts index 04f4c58..193f1d3 100644 --- a/kit/seeds/config/scripts/from-config.ts +++ b/kit/seeds/config/scripts/from-config.ts @@ -5,7 +5,7 @@ import { parseCliConfig } from "@wirecat/cli-core/manifest" import config from "../wirecat.config.ts" // wirecat.config.ts → src/generated/wirecat-config.ts, what the CLI reads of it at run time: the call that checks a -// token and the CRM source. src/ cannot import the config itself: it sits outside src/ and the bin is bundled. +// token and the source. src/ cannot import the config itself: it sits outside src/ and the bin is bundled. const root = join(import.meta.dirname, "..") const out = join(root, "src/generated/wirecat-config.ts") if (process.argv.includes("--if-missing") && existsSync(out)) process.exit(0) @@ -42,11 +42,17 @@ const text = formatted( "", ...(hooksImport ? [`export { hooks as HOOKS } from "${hooksImport}"`] - : [ - 'import type { CrmManifestHooks } from "@wirecat/cli-core/crm"', - "", - "export const HOOKS: CrmManifestHooks | undefined = undefined", - ]), + : cli.category === "tracker" + ? [ + 'import type { TrackerManifestHooks } from "@wirecat/cli-core/tracker"', + "", + "export const HOOKS: TrackerManifestHooks | undefined = undefined", + ] + : [ + 'import type { CrmManifestHooks } from "@wirecat/cli-core/crm"', + "", + "export const HOOKS: CrmManifestHooks | undefined = undefined", + ]), "", ].join("\n"), ) diff --git a/kit/seeds/config/scripts/source-check.ts b/kit/seeds/config/scripts/source-check.ts index ca8e958..5ba8319 100644 --- a/kit/seeds/config/scripts/source-check.ts +++ b/kit/seeds/config/scripts/source-check.ts @@ -8,7 +8,7 @@ import config from "../wirecat.config.ts" // wirecat.config.ts against the generated API: its shape, the auth.verify call, then each source operation and every // path its map reads. // Run after pnpm generate, which builds dist/. -const problemsOf = (): { problems: string[]; crm: boolean } => { +const problemsOf = (): { problems: string[]; source: boolean } => { try { const cli = parseCliConfig(config) const verify = cli.auth.preset === "none" ? undefined : cli.auth.verify @@ -21,22 +21,22 @@ const problemsOf = (): { problems: string[]; crm: boolean } => { : operation.effect !== "read" ? [`auth.verify: ${verify.operation} is not a read, and session start sends only reads`] : [] - if (!cli.source) return { problems: verifying, crm: false } + if (!cli.source) return { problems: verifying, source: false } if (cli.category === "tracker") { // Refuses a map path the selection leaves out, which would read as "the tracker cleared it". parseTrackerManifest(cli.source, api) - return { problems: verifying, crm: true } + return { problems: verifying, source: true } } return { problems: [...verifying, ...crmManifestProblems(parseCrmManifest(cli.source, api), api, definitions)], - crm: true, + source: true, } } catch (error) { - return { problems: [error instanceof Error ? error.message : String(error)], crm: false } + return { problems: [error instanceof Error ? error.message : String(error)], source: false } } } -const { problems, crm } = problemsOf() +const { problems, source } = problemsOf() for (const problem of problems) process.stderr.write(`${problem}\n`) if (problems.length) process.exit(1) -process.stdout.write(`wirecat.config.ts: ${crm ? "the source matches the generated API" : "ok"}\n`) +process.stdout.write(`wirecat.config.ts: ${source ? "the source matches the generated API" : "ok"}\n`) diff --git a/kit/seeds/config/src/tracker-contracts.test.ts b/kit/seeds/config/src/tracker-contracts.test.ts index 4425e4a..0bc3865 100644 --- a/kit/seeds/config/src/tracker-contracts.test.ts +++ b/kit/seeds/config/src/tracker-contracts.test.ts @@ -22,6 +22,8 @@ it("sync through this CLI sends only calls the schema allows, under the account expect(started.code, started.err).toBe(0) const synced = await runCli(["personal", "sync", "--json"], { keyring, service: fake }) expect(synced.code, synced.err).toBe(0) + // A kind that failed is a partial answer with exit 0: its issues name it. + expect(synced.json().issues ?? []).toEqual([]) const listed = await runCli(["personal", "issues", "list", "--json"], { keyring, service: fake }) expect(listed.code, listed.err).toBe(0) expect(fake.refusals).toEqual([]) diff --git a/kit/src/from-config.ts b/kit/src/from-config.ts index 0cb9e42..2b15986 100644 --- a/kit/src/from-config.ts +++ b/kit/src/from-config.ts @@ -72,7 +72,7 @@ const notWiredYet = (config: CliConfig): string[] => [ ...(config.source && config.category === "tracker" ? ["source: the tracker's write commands, and its items in the shared search; sync and the reads are built"] : []), - ...(config.spec.kind === "graphql" + ...(config.spec.kind === "graphql" && config.auth.preset !== "none" ? ["auth: the header the key travels in is the sample's Authorization in scripts/generate.ts; check its docs"] : []), ] diff --git a/kit/src/new.ts b/kit/src/new.ts index 7bb8844..18299c8 100644 --- a/kit/src/new.ts +++ b/kit/src/new.ts @@ -757,7 +757,7 @@ const RUN_SCOPE = "src/run-scope.test.ts" /** * run-scope over a config's wiring: `session start` checks the token with the API, so the answering fake answers the - * API's host too; `sync` is cli-core's, run in its own run and tested by crmSyncContract. + * API's host too; `sync` is cli-core's, run in its own run and tested by the source's contracts test. */ export const withConfigRunScope = ( text: string, diff --git a/kit/src/spec-url.ts b/kit/src/spec-url.ts index 056e5f6..5398550 100644 --- a/kit/src/spec-url.ts +++ b/kit/src/spec-url.ts @@ -192,6 +192,7 @@ export const introspectSpec = async (raw: string, fetch: SpecFetch = globalThis. const { syncGraphql } = await import("@wirecat/cli-base/codegen") const provenance = await syncGraphql({ url: url.href, dir, fetch: fetch as typeof globalThis.fetch }) const text = await readFile(join(dir, "schema.json"), "utf8") + if (text.length > SPEC_MAX_BYTES) throw new Error(`${url.href}'s schema is larger than 20 MB; check it by hand`) return { url: url.href, kind: "graphql", From 92cefe8777769d77f4fe29aa62c326f79716c9bc Mon Sep 17 00:00:00 2001 From: leemour Date: Wed, 18 Nov 2026 00:11:12 +0100 Subject: [PATCH 3/3] chore(deps): cli-core 0.697.0, with the tracker category and the GraphQL executor Co-Authored-By: Claude Opus 5.5 --- changes/feat-tracker-graphql.md | 5 +++++ kit/test/package.test.ts | 2 +- package.json | 2 +- pnpm-lock.yaml | 12 ++++++------ 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/changes/feat-tracker-graphql.md b/changes/feat-tracker-graphql.md index bfce091..7904779 100644 --- a/changes/feat-tracker-graphql.md +++ b/changes/feat-tracker-graphql.md @@ -7,3 +7,8 @@ - **A `tracker` category.** `new --from-config` with `category: "tracker"` and a `source` mounts cli-core's tracker commands (`sync`, `issues`, `projects`, `teams`…) over `trackerSourceFromManifest`, with a test that checks the source against the generated API and syncs through the CLI over a fake of the schema. + +### Changed — may break callers + +- **cli-core 0.697.0**, which has the tracker category, `trackerSourceFromManifest` and the + GraphQL executor. diff --git a/kit/test/package.test.ts b/kit/test/package.test.ts index 4c0a210..7669fb9 100644 --- a/kit/test/package.test.ts +++ b/kit/test/package.test.ts @@ -110,7 +110,7 @@ describe("the packed bin", () => { expect(result.status).toBe(1) expect(result.stderr).toContain( - "--category: messenger, mail, notes, files, meetings, calendar, crm, or other:", + "--category: messenger, mail, notes, files, meetings, calendar, crm, tracker, or other:", ) }) diff --git a/package.json b/package.json index 4806f68..bf0f343 100644 --- a/package.json +++ b/package.json @@ -91,7 +91,7 @@ }, "dependencies": { "@wirecat/cli-base": "0.116.0", - "@wirecat/cli-core": "0.696.0", + "@wirecat/cli-core": "0.697.0", "commander": "15.0.0", "valibot": "1.5.0", "yaml": "2.9.1" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ceba67a..9d3ba3a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -16,8 +16,8 @@ importers: specifier: 0.116.0 version: 0.116.0(@scalar/openapi-upgrader@0.4.6)(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5) '@wirecat/cli-core': - specifier: 0.696.0 - version: 0.696.0(@wirecat/cli-base@0.116.0(@scalar/openapi-upgrader@0.4.6)(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) + specifier: 0.697.0 + version: 0.697.0(@wirecat/cli-base@0.116.0(@scalar/openapi-upgrader@0.4.6)(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) commander: specifier: 15.0.0 version: 15.0.0 @@ -1201,13 +1201,13 @@ packages: '@wirecat/cli-core-sqlite@1.1.0': resolution: {integrity: sha512-GpGlh/dAIX/nblBYCdT6DfWSLFxav9mxxeELQAfEuw+QZdT9unKxbi5xa02s/s4JS1P7n0PQx2sCABj4FlMRNw==} - '@wirecat/cli-core@0.696.0': - resolution: {integrity: sha512-zUpuXCK6xs6O8lnYzJuf5Tv2Yh6/iQRGQJzRk0Qf9OXgD7XzRqM6YmDYoyzMR4XLMXpKstFW95L19rKMUurm+A==} + '@wirecat/cli-core@0.697.0': + resolution: {integrity: sha512-bhe0JqXPjSUxWFjUKEycRtqfdEismM7Rksn/BWrbx9ysUqrT/SBGd9kHpGlKKSxJL8j5OtXQZiZ+y4RVAJUHqA==} engines: {node: ^22.16.0 || >=24} hasBin: true 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 @@ -3219,7 +3219,7 @@ snapshots: '@wirecat/cli-core-sqlite@1.1.0': {} - '@wirecat/cli-core@0.696.0(@wirecat/cli-base@0.116.0(@scalar/openapi-upgrader@0.4.6)(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.697.0(@wirecat/cli-base@0.116.0(@scalar/openapi-upgrader@0.4.6)(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': 1.3.0(zod@4.6.7) '@bomb.sh/tab': 0.0.22(commander@15.0.0)