From 69a10d9b0b410f382054e4898dbe6dbd524b2fbf Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 23:52:25 +0100 Subject: [PATCH] fix(kit): name the real service, not "Notion API" or the sample, and pin cli-core 0.696.0 Notion's OpenAPI description exposed three gaps in a CLI made with --spec-url: - the service name kept the title's trailing "API": "the raw Notion API API"; - session, MCP and offline texts said "Example Comments", the sample's name; - a required Notion-Version header with a default was still demanded (fixed in cli-core 0.696.0; the seed api test now leaves such a flag out). SERVICE moves to src/identity.ts, and new writes the service's name there and into docs/index.md, docs/security.md and the skill. The seed api test also typechecks for a spec without securitySchemes (PokeAPI). Pins cli-core 0.696.0 and cli-base 0.116.0 (GET /me is named -get). Co-Authored-By: Claude Opus 5.5 --- changes/fix-notion-service-name.md | 22 +++++++++++++++++++ kit/seeds/shared/src/api.test.ts | 12 ++++++---- kit/src/new.ts | 23 ++++++++++++++++---- kit/src/spec.ts | 35 ++++++++++++++++++++++++++++++ kit/test/spec-url.test.ts | 12 +++++++--- package.json | 4 ++-- pnpm-lock.yaml | 22 +++++++++---------- src/commands/session.ts | 3 +-- src/context.ts | 4 ++-- src/identity.ts | 3 +++ src/program.ts | 3 +-- 11 files changed, 113 insertions(+), 30 deletions(-) create mode 100644 changes/fix-notion-service-name.md diff --git a/changes/fix-notion-service-name.md b/changes/fix-notion-service-name.md new file mode 100644 index 0000000..d0bf7b1 --- /dev/null +++ b/changes/fix-notion-service-name.md @@ -0,0 +1,22 @@ +### Fixed + +- **A CLI made from an OpenAPI description names the service without a trailing "API".** Notion's description is + titled "Notion API", and `api --help`, `api list`, the README, the skill and the MCP texts said "the raw Notion API + API". `new` now takes "Notion" as the service's name; the download line still shows the description's own title. +- **The sign-in, the MCP server and an offline refusal name the real service, not the sample's.** `session --help` + said "keep this profile's Example Comments token" in a CLI made for Notion. The CLI's service name is now `SERVICE` + in `src/identity.ts`, and `new` writes the service's name there; the sample's `comments` group and its transport + keep "Example Comments". +- **A required parameter with a default needs no flag.** With cli-core 0.696.0, Notion's page-markdown calls + send `Notion-Version: 2026-03-11` by themselves instead of stopping with `required option '--notion-version + ' not specified`. The generated `src/api.test.ts` leaves such a parameter out, so it checks this. +- **A CLI made from a description without sign-in typechecks again.** PokeAPI's manifest has no `securitySchemes`, + and the generated `src/api.test.ts` read it, so `pnpm bootstrap` stopped at `ci:quick`. +- **The docs and the skill of a CLI made with `--spec-url` say its `api` group reaches the service.** They said its + one service was the sample. + +### Changed — may break callers + +- **With cli-base 0.116.0, `GET /v1/users/me` is `users-me-get`, not `users-me-list`.** A path ending in `/me` + reads one item. A CLI generated before keeps its names until it regenerates. +- **A new CLI pins `@wirecat/cli-core` 0.696.0 and `@wirecat/cli-base` 0.116.0**, which carry the two fixes above. diff --git a/kit/seeds/shared/src/api.test.ts b/kit/seeds/shared/src/api.test.ts index fb555ae..092cb2d 100644 --- a/kit/seeds/shared/src/api.test.ts +++ b/kit/seeds/shared/src/api.test.ts @@ -1,7 +1,7 @@ import { mkdirSync, rmSync, writeFileSync } from "node:fs" import { join } from "node:path" import { fakeApi, sampleOf } from "@wirecat/cli-base/codegen" -import { apiFlagOf, manifestBaseUrl, sendsBytes } from "@wirecat/cli-core/cli" +import { apiFlagOf, manifestBaseUrl, type ServiceApiManifest, sendsBytes } from "@wirecat/cli-core/cli" import { afterEach, expect, it } from "vitest" import { API } from "./config.js" import { definitions } from "./generated/definitions.js" @@ -21,14 +21,17 @@ afterEach(() => { type Operation = (typeof API.manifest.operations)[number] +// A spec without sign-in, such as PokeAPI's, gives the manifest no securitySchemes. +const { security, securitySchemes }: ServiceApiManifest = API.manifest + // The fake checks each call's path, parameters and body, and the token where its security, else the spec's, names it. const fake = () => fakeApi({ operations: API.manifest.operations, definitions, baseUrl: manifestBaseUrl(API.manifest), - security: API.manifest.security, - securitySchemes: API.manifest.securitySchemes, + ...(security ? { security } : {}), + ...(securitySchemes ? { securitySchemes } : {}), token: FAKE_TOKEN, }) @@ -42,7 +45,8 @@ const deleteKeys = [ const argsOf = (operation: Operation) => [ ...operation.parameters - .filter((parameter) => parameter.required) + // A required parameter with a default is left out: the command sends the default itself. + .filter((parameter) => parameter.required && parameter.schema.default === undefined) .flatMap((parameter) => [`--${apiFlagOf(parameter.name)}`, String(sampleOf(parameter.schema, definitions))]), ...(sendsBytes(operation) ? ["--body-file", upload] : []), ...(operation.request?.schema diff --git a/kit/src/new.ts b/kit/src/new.ts index 0328084..e23d1b0 100644 --- a/kit/src/new.ts +++ b/kit/src/new.ts @@ -24,6 +24,7 @@ import { renderTemplate, type TemplateSource } from "./source.js" import { replaceOnce, SWAGGER_PEERS, + serviceOf, specKindOf, specSeeds, withApiCommand, @@ -32,6 +33,8 @@ import { withApiSkill, withApiSkillLink, withDownloadedSpec, + withService, + withServicePage, withSpecPackage, } from "./spec.js" import { type DownloadedSpec, downloadSpec, type SpecFetch } from "./spec-url.js" @@ -805,7 +808,7 @@ export const runNew = async ( ) const answers = collected.answers const names = withFreePrefix(loaded ? { ...collected.names, prefix: loaded.config.identity.prefix } : collected.names) - const service = loaded?.config.identity.service ?? downloaded?.title + const service = loaded?.config.identity.service ?? (downloaded && serviceOf(downloaded.title)) if (preset && isWireCat(names)) throw new Error(`--preset ${preset} is for a CLI outside WireCat; ${names.package} is a WireCat package`) const description = preset ? GENERIC_DESCRIPTION : DESCRIPTION @@ -853,7 +856,11 @@ export const runNew = async ( api: Boolean(spec), }), "SECURITY.md": ownRepository(names), - "docs/security.md": ownRepository(names), + "docs/security.md": (text: string) => { + const own = ownRepository(names)(text) + return spec && service ? withServicePage("docs/security.md", own, service) : own + }, + ...(spec && service ? { "docs/index.md": (text: string) => withServicePage("docs/index.md", text, service) } : {}), "CHANGELOG.md": () => cliChangelog(names, source), [VERSION_FILE]: (text) => text.replace(/VERSION = "[^"]*"/, 'VERSION = "0.0.0"'), [IDENTITY_FILE]: (text) => { @@ -866,8 +873,9 @@ export const runNew = async ( ), downloaded?.hosts ?? [], ) + const named = service ? withService(identity, service) : identity const kinds = loaded?.config.source?.kinds - return loaded?.config.source ? withSyncs(identity, Array.isArray(kinds) ? kinds.map(String) : []) : identity + return loaded?.config.source ? withSyncs(named, Array.isArray(kinds) ? kinds.map(String) : []) : named }, "AGENTS.md": (text) => withReference(text, category), "cspell.json": withReferenceWords, @@ -882,7 +890,14 @@ export const runNew = async ( const agentSkill = `skills/${appNameOf(names)}/SKILL.md` for (const [path, file] of rendered) { if (file.kind === "file") hashes[path] = sha256(file.content) - const rewrite = rewrites[path] ?? (spec && path === agentSkill ? withApiSkillLink : undefined) + const rewrite = + rewrites[path] ?? + (spec && path === agentSkill + ? (text: string) => { + const linked = withApiSkillLink(text) + return service ? withServicePage(agentSkill, linked, service) : linked + } + : undefined) const content = rewrite ? rewrite(file.content.toString("utf8")) : file.content if (content.includes(`${prefixOf(names)}_`)) prefixed.push(path) await writeOut(target, path, content, file.mode) diff --git a/kit/src/spec.ts b/kit/src/spec.ts index 0b4b242..e9ababe 100644 --- a/kit/src/spec.ts +++ b/kit/src/spec.ts @@ -226,3 +226,38 @@ export const withDownloadedSpec = ( ) return files } + +// "Notion API" names the API; the commands already add "API" after the service's name. +export const serviceOf = (title: string): string => title.replace(/\s+API$/i, "") || title + +// The pages say the sample is the CLI's one service, which stops being true once the api group reaches a real one. +const SAMPLE_ONLY: Readonly string]>> = { + "docs/index.md": [ + / Its one service is a sample,\nExample Comments, made up to show how a command reaches a service; its address never resolves\./, + (service) => + `\nIts \`api\` group reaches ${service}, one command per operation of its API description. The sample's \`comments\`` + + "\ngroup shows how a command reaches a service; its made-up address never resolves.", + ], + "docs/security.md": [ + / Its one service is\nthe sample, Example Comments, whose address never resolves\. /, + (service) => `\nIts \`api\` group reaches ${service}; the sample's made-up address never resolves.\n`, + ], + SKILL: [ + / Its one service is a made-up sample, Example Comments\./, + (service) => ` Its api group reaches ${service}.`, + ], +} + +export const withServicePage = (path: string, text: string, service: string): string => { + const [from, to] = SAMPLE_ONLY[path.endsWith("SKILL.md") ? "SKILL" : path] ?? [] + if (!from || !to) throw new Error(`${path}: no sample sentence known to rewrite`) + return replaceOnce(path, text, from, to(service)) +} + +export const withService = (text: string, service: string): string => + replaceOnce( + "src/identity.ts", + text, + /^\/\/ SAMPLE: your service's name.*\nexport const SERVICE = .*$/m, + `export const SERVICE = ${JSON.stringify(service)}`, + ) diff --git a/kit/test/spec-url.test.ts b/kit/test/spec-url.test.ts index 72fb852..c9d526b 100644 --- a/kit/test/spec-url.test.ts +++ b/kit/test/spec-url.test.ts @@ -11,7 +11,7 @@ afterAll(removeTempDirs) const YAML_SPEC = `openapi: 3.0.3 info: - title: Acme Notes + title: Acme Notes API version: "1" servers: - url: /v1 @@ -61,7 +61,7 @@ describe("downloadSpec", () => { expect(spec).toMatchObject({ kind: "openapi", file: "openapi.yaml", - title: "Acme Notes", + title: "Acme Notes API", operations: 2, hosts: ["docs.notes.example"], prefix: ["api"], @@ -142,12 +142,18 @@ describe("new --spec-url", () => { ]) expect(read(dir, "src/identity.ts")).toContain('hosts: ["comments.example.invalid", "docs.notes.example"],') expect(read(dir, "src/config.ts")).toContain('service: "Acme Notes",') + expect(read(dir, "src/identity.ts")).toContain('\nexport const SERVICE = "Acme Notes"\n') + expect(read(dir, "src/identity.ts")).not.toContain("SAMPLE: your service's name") + for (const page of ["docs/index.md", "docs/security.md", "skills/example-cal-cli/SKILL.md"]) { + expect(read(dir, page)).toContain("group reaches Acme Notes") + expect(read(dir, page)).not.toContain("Example Comments") + } expect(read(dir, "scripts/generate.ts")).toContain('group: "cal"') expect(read(dir, "scripts/generate.ts")).toContain('names: { fromPath: true, segments: { "api": "" } }') expect(read(dir, "scripts/spec-model.ts")).toContain('"url": "https://docs.notes.example/v1"') expect(JSON.parse(read(dir, "package.json")).devDependencies.yaml).toBeTruthy() expect(read(dir, "docs/dev/DESIGN.md")).toContain("**API description:** OpenAPI 3.0 or 3.1") - expect(out).toContain("Downloaded Acme Notes, 2 operations, into spec/cal/openapi.yaml") + expect(out).toContain("Downloaded Acme Notes API, 2 operations, into spec/cal/openapi.yaml") const readme = read(dir, "README.md") expect(readme.split("\n")[0]).toBe("# cal: Acme Notes CLI for AI agents") expect(readme).toContain("**Every operation of the Acme Notes API is a command.**") diff --git a/package.json b/package.json index ac5eac4..429aed0 100644 --- a/package.json +++ b/package.json @@ -90,8 +90,8 @@ "kit:docs": "cspell lint --config cspell.json --no-progress --no-summary kit/*.md SKILL.md && rumdl check --config config/wirecat/rumdl.toml kit/*.md SKILL.md" }, "dependencies": { - "@wirecat/cli-base": "0.114.0", - "@wirecat/cli-core": "0.695.0", + "@wirecat/cli-base": "0.116.0", + "@wirecat/cli-core": "0.696.0", "commander": "15.0.0", "valibot": "1.5.0", "yaml": "2.9.1" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 54d0b28..ceba67a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -13,11 +13,11 @@ importers: .: dependencies: '@wirecat/cli-base': - specifier: 0.114.0 - version: 0.114.0(@scalar/openapi-upgrader@0.4.6)(commander@15.0.0)(esbuild@0.28.2)(typescript@7.0.2)(vitest@5.0.5) + 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.695.0 - version: 0.695.0(@wirecat/cli-base@0.114.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.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) commander: specifier: 15.0.0 version: 15.0.0 @@ -1173,8 +1173,8 @@ packages: '@wasm-audio-decoders/opus-ml@0.0.3': resolution: {integrity: sha512-SEeTmk0eb3q5etJA/NHCRWW6BivTx9tqvNTmG0kg2ynuATEQRUZnwQE6Ibvl1BBvqIGHqI57+qyJMWmJBwb5XQ==} - '@wirecat/cli-base@0.114.0': - resolution: {integrity: sha512-TnZOIQlzvE11V6ihZnYxmFei/uJNOk8UAEl8ECSr+lSf5qCkNp+4jhSnOYzlZv0hRTZq2haGi/QFHMc6R+2rCw==} + '@wirecat/cli-base@0.116.0': + resolution: {integrity: sha512-FHsybz3IYfxsm8NRkiwfZ7CP6yf24tgq/KWZPBqVJ9HObqtOZ5nh8OhEPj7Dl/ifU7AdqOBaH+UCsxYCMynU2w==} engines: {node: '>=22'} hasBin: true peerDependencies: @@ -1201,8 +1201,8 @@ packages: '@wirecat/cli-core-sqlite@1.1.0': resolution: {integrity: sha512-GpGlh/dAIX/nblBYCdT6DfWSLFxav9mxxeELQAfEuw+QZdT9unKxbi5xa02s/s4JS1P7n0PQx2sCABj4FlMRNw==} - '@wirecat/cli-core@0.695.0': - resolution: {integrity: sha512-e1zpmcyF7jPJ54AjJ9wpLc8ON1pm0xggYN/SBfc9IlRRsQy5QTzjEW25rjrG7afbetlh/M/2Zolz1fZ1HisTAw==} + '@wirecat/cli-core@0.696.0': + resolution: {integrity: sha512-zUpuXCK6xs6O8lnYzJuf5Tv2Yh6/iQRGQJzRk0Qf9OXgD7XzRqM6YmDYoyzMR4XLMXpKstFW95L19rKMUurm+A==} engines: {node: ^22.16.0 || >=24} hasBin: true peerDependencies: @@ -3198,7 +3198,7 @@ snapshots: dependencies: '@wasm-audio-decoders/common': 9.0.7 - '@wirecat/cli-base@0.114.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-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)': dependencies: '@valibot/to-json-schema': 1.8.0(valibot@1.5.0(typescript@7.0.2)) cli-table3: 0.6.5 @@ -3219,7 +3219,7 @@ snapshots: '@wirecat/cli-core-sqlite@1.1.0': {} - '@wirecat/cli-core@0.695.0(@wirecat/cli-base@0.114.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.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)': dependencies: '@anthropic-ai/sdk': 1.3.0(zod@4.6.7) '@bomb.sh/tab': 0.0.22(commander@15.0.0) @@ -3229,7 +3229,7 @@ snapshots: '@valibot/to-json-schema': 1.8.0(valibot@1.5.0(typescript@7.0.2)) '@wasm-audio-decoders/flac': 0.2.11 '@wasm-audio-decoders/ogg-vorbis': 0.1.20 - '@wirecat/cli-base': 0.114.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-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) '@wirecat/cli-core-onnx': 1.2.0 '@wirecat/cli-core-sqlite': 1.1.0 '@xmldom/xmldom': 0.9.12 diff --git a/src/commands/session.ts b/src/commands/session.ts index 4cf8644..7aeb24d 100644 --- a/src/commands/session.ts +++ b/src/commands/session.ts @@ -26,8 +26,7 @@ import { import { Command } from "commander" import { configuration } from "../config.js" import { contextOf, refuseOffline, serviceFor, withService } from "../context.js" -import { IDENTITY } from "../identity.js" -import { SERVICE } from "../sample/transport.js" +import { IDENTITY, SERVICE } from "../identity.js" // `session start | status | end | list` is every provider CLI's sign-in (WC-ACCT-12). Keep it; replace the token // prompt and the `me` check with your service's. A service with OAuth signs in through cli-core's oauth module diff --git a/src/context.ts b/src/context.ts index 8406f82..6baadc9 100644 --- a/src/context.ts +++ b/src/context.ts @@ -10,9 +10,9 @@ import { import { Pacer, pacePathFor } from "@wirecat/cli-core/sends" import type { Command } from "commander" import { configuration } from "./config.js" -import { IDENTITY } from "./identity.js" +import { IDENTITY, SERVICE } from "./identity.js" import { type CommentsService, commentsService } from "./sample/comments.js" -import { SERVICE, transport } from "./sample/transport.js" +import { transport } from "./sample/transport.js" /** What a test hands `run()` beside cli-core's own: the fake service in place of the network (WC-ARCH-10). */ export interface ServiceEnvironment extends BaseEnvironment { diff --git a/src/identity.ts b/src/identity.ts index e03c161..ce00073 100644 --- a/src/identity.ts +++ b/src/identity.ts @@ -2,6 +2,9 @@ import type { ManifestIdentity } from "@wirecat/cli-base/wcat/manifest" import type { AppIdentity } from "@wirecat/cli-core/cli" import { VERSION } from "./version.js" +// SAMPLE: your service's name, as the sign-in, the MCP server and an offline refusal say it. +export const SERVICE = "Example Comments" + export const PACKAGE = "@wirecat/clidev-cli" export const IDENTITY: AppIdentity = { diff --git a/src/program.ts b/src/program.ts index 91ac281..7c9cd1b 100644 --- a/src/program.ts +++ b/src/program.ts @@ -21,8 +21,7 @@ import type { Command } from "commander" import { commentsCommand } from "./commands/comments.js" import { sessionCommand } from "./commands/session.js" import { configuration } from "./config.js" -import { IDENTITY, PACKAGE, SKILL } from "./identity.js" -import { SERVICE } from "./sample/transport.js" +import { IDENTITY, PACKAGE, SERVICE, SKILL } from "./identity.js" const update = appUpdate({ packageName: PACKAGE,