Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions changes/fix-notion-service-name.md
Original file line number Diff line number Diff line change
@@ -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
<value>' 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.
12 changes: 8 additions & 4 deletions kit/seeds/shared/src/api.test.ts
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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,
})

Expand All @@ -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
Expand Down
23 changes: 19 additions & 4 deletions kit/src/new.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import { renderTemplate, type TemplateSource } from "./source.js"
import {
replaceOnce,
SWAGGER_PEERS,
serviceOf,
specKindOf,
specSeeds,
withApiCommand,
Expand All @@ -32,6 +33,8 @@ import {
withApiSkill,
withApiSkillLink,
withDownloadedSpec,
withService,
withServicePage,
withSpecPackage,
} from "./spec.js"
import { type DownloadedSpec, downloadSpec, type SpecFetch } from "./spec-url.js"
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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) => {
Expand All @@ -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,
Expand All @@ -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)
Expand Down
35 changes: 35 additions & 0 deletions kit/src/spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Record<string, [RegExp, (service: string) => 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)}`,
)
12 changes: 9 additions & 3 deletions kit/test/spec-url.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"],
Expand Down Expand Up @@ -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.**")
Expand Down
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
22 changes: 11 additions & 11 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions src/commands/session.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions src/context.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
3 changes: 3 additions & 0 deletions src/identity.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
3 changes: 1 addition & 2 deletions src/program.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading