diff --git a/changes/new-short-summary.md b/changes/new-short-summary.md new file mode 100644 index 0000000..970fabb --- /dev/null +++ b/changes/new-short-summary.md @@ -0,0 +1,9 @@ +### Changed — may break callers + +- **`new` ends with a short summary.** "Try it" lists the four lines that make the CLI and show its commands. "Before + the first commit" is one new script, `pnpm bootstrap`, in place of seven commands: it runs the lint fix, the + generator twice, the contract and MCP snapshot updates and `ci:quick`. A `--preset generic` CLI gets two publishing + steps with paths relative to it, in place of three long ones with absolute paths. +- **`new` picks a free environment prefix by itself.** When the command word's prefix is one the service's own tools + read (`NOTION_`, `GH_`, `GITHUB_`, `HUBSPOT_`), the CLI is made with `_CLI_` (`WC_` for a WireCat + package) and the summary says so, in place of a list of files to rename by hand. diff --git a/kit/README.md b/kit/README.md index ae03e1f..d05bff4 100644 --- a/kit/README.md +++ b/kit/README.md @@ -24,10 +24,11 @@ npx @wirecat/cli-template remove-sample It sets up what CI's `repo-setup` job (`cli-dev repo-check`) checks in the files: a monthly cron minute and a parity group in `config/parity-groups.json`. A WireCat CLI gets a free minute inside WC-CI-9's window, from the table in cli-base's `docs/standards/ci.md`; a CLI outside `@wirecat` gets one after that window. It then prints the steps that -need a person: four for a WireCat CLI, three outside `@wirecat`. For a WireCat CLI it also prints the entries to -paste into cli-base's minute table, cli-core's `WIRECAT_TOOLS` and cli-docs' `tools.json`. It warns when the -environment prefix or the keyring service is a name the service's own tools already use, such as `NOTION_` or -`notion-cli`. +need a person: four for a WireCat CLI, two with `--preset generic`. Before them it prints how to try the CLI, and +`pnpm bootstrap`, the one script that readies it for the first commit. For a WireCat CLI it also prints the entries to +paste into cli-base's minute table, cli-core's `WIRECAT_TOOLS` and cli-docs' `tools.json`. When the command word's +environment prefix is one the service's own tools read, such as `NOTION_`, it makes the CLI with `NOTION_CLI_` +(`WCNOTION_` for a WireCat package) and says so. It warns when the keyring service is taken, such as `notion-cli`. The steps run the owner's scripts the CLI gets, each one readable file that prints its plan and asks first: @@ -44,7 +45,7 @@ With `--spec` other than `none`, `new` also builds the `api` group from the serv per operation through cli-core's `serviceApiCommand`, its permissions, its tests against cli-base's `fakeApi`, and the agent skill's API pages from `apiSkillFiles`. It writes a sample description of the made-up Example Comments service to `spec//` with `provenance.json`, `scripts/sync-spec.ts`, `scripts/spec-model.ts` and `scripts/generate.ts`, -puts the API step in front of `pnpm generate` and `generate:check`, and prints the steps that regenerate the +and puts the API step in front of `pnpm generate` and `generate:check`; `pnpm bootstrap` then regenerates the contracts. Swagger 2.0 adds cli-base's converter, `@scalar/openapi-upgrader`, to `devDependencies`. The order of work is in the new-cli skill's [references/openapi.md](skills/new-cli/references/openapi.md). diff --git a/kit/src/new.ts b/kit/src/new.ts index 14cd208..0328084 100644 --- a/kit/src/new.ts +++ b/kit/src/new.ts @@ -19,7 +19,7 @@ import { type Question, } from "./interview.js" import { type CliManifest, isRecord, MANIFEST, type Names, sha256 } from "./manifest.js" -import { appNameOf, prefixOf } from "./rename.js" +import { appNameOf, isWireCat, nameClashes, prefixOf, withFreePrefix } from "./rename.js" import { renderTemplate, type TemplateSource } from "./source.js" import { replaceOnce, @@ -64,7 +64,7 @@ export const withReferenceWords = (text: string): string => { return `${JSON.stringify({ ...config, words: [...new Set([...words, ...REFERENCE_NAMES])] }, null, 2)}\n` } -export const isWireCat = (names: Names): boolean => names.package.startsWith("@wirecat/") +export { isWireCat } // The MCP Registry takes dev.wirecat/ names only from wirecat.dev's DNS key, which only WireCatLabs holds; anyone // else signs in with GitHub, which grants io.github./. @@ -652,50 +652,27 @@ export const markExecutable = async (cwd: string, paths: string[]): Promise [ - `1. After the first commit, run node ${join(dir, "bin/setup-github")}: it creates ${names.owner}/${names.name}, main's ruleset and the npm environment, and asks first. Add any secrets CI needs.`, - `2. ${preset ? "Optional, since bin/release does not ask for it outside WireCat: before a release," : "Before each release, the first too:"} replace the sample's reads and its "# Needs:" lines in scripts/live.sh, store the test account's token once with secret-tool store --label="${names.command} live check" service ${appNameOf(names)}-live account , and run ${join(dir, "bin/live")} on the release pull request's branch: it commits the record there and names it under Conformance (WC-REL-17).`, - `3. Once the first release pull request is merged, publish it from main with ${join(dir, "bin/release")} --first; it then says how to set npm trusted publishing (WC-REL-11). Every later release is bin/release.`, - ...(isWireCat(names) - ? [ - "4. Join WireCat's shared lists with the entries below: one pull request to cli-base (the monthly minute in WC-CI-9's table, the command in PARITY_GROUPS' all group), one to cli-core's WIRECAT_TOOLS, and after the first release one to cli-docs' tools.json.", - ] - : []), +const presetSteps = (names: Names): string[] => [ + `1. After the first commit, run node bin/setup-github: it creates ${names.owner}/${names.name} on GitHub, and asks first.`, + "2. Once the first release pull request is merged, run node bin/release --first.", + "Optional before a release: node bin/live records a check against the real service.", "CI's repo-setup job (cli-dev repo-check) fails until step 1 is done.", ] -// Names the service's own tools already use. A CLI with the same environment prefix reads their token as its own; one -// with the same keyring service overwrites their sign-in. Each entry names where it was seen. -const TAKEN_PREFIXES: Record = { - // notion-cli BUG-759 (cli-factory plan, notion lessons). - NOTION: "Notion's MCP server reads NOTION_TOKEN", - // The cli-factory plan, 6.3.6. - HUBSPOT: "HubSpot's own tools read HUBSPOT_ variables", - // https://cli.github.com/manual/gh_help_environment - GH: "GitHub's gh reads GH_TOKEN", - GITHUB: "GitHub's gh reads GITHUB_TOKEN", -} -const TAKEN_SERVICES: Record = { - // notion-cli RISK-2303 (cli-factory plan, notion lessons). - "notion-cli": "Notion's ntn keeps its sign-in under the keyring service notion-cli", -} - -export const nameClashes = (names: Names, files: string[]): string[] => { - const prefix = prefixOf(names) - const app = appNameOf(names) - return [ - ...(TAKEN_PREFIXES[prefix] - ? [ - `${prefix}_: ${TAKEN_PREFIXES[prefix]}, so ${names.command} would take its token. Pick another prefix (notion-cli uses WCNOTION): envPrefix in src/identity.ts and ${prefix}_ in ${files.join(", ")}. upgrade merges the template's own files, scripts/sandboxed.ts and docs/dev/TESTING.md, with ${prefix}_ in them: check them after each upgrade.`, - ] - : []), - ...(TAKEN_SERVICES[app] - ? [ - `keyring service ${app}: ${TAKEN_SERVICES[app]}, so a sign-in would replace it. Pick another name: appName in src/identity.ts.`, - ] - : []), - ] -} +export const manualSteps = (names: Names, dir: string, preset?: string): string[] => + preset + ? presetSteps(names) + : [ + `1. After the first commit, run node ${join(dir, "bin/setup-github")}: it creates ${names.owner}/${names.name}, main's ruleset and the npm environment, and asks first. Add any secrets CI needs.`, + `2. ${preset ? "Optional, since bin/release does not ask for it outside WireCat: before a release," : "Before each release, the first too:"} replace the sample's reads and its "# Needs:" lines in scripts/live.sh, store the test account's token once with secret-tool store --label="${names.command} live check" service ${appNameOf(names)}-live account , and run ${join(dir, "bin/live")} on the release pull request's branch: it commits the record there and names it under Conformance (WC-REL-17).`, + `3. Once the first release pull request is merged, publish it from main with ${join(dir, "bin/release")} --first; it then says how to set npm trusted publishing (WC-REL-11). Every later release is bin/release.`, + ...(isWireCat(names) + ? [ + "4. Join WireCat's shared lists with the entries below: one pull request to cli-base (the monthly minute in WC-CI-9's table, the command in PARITY_GROUPS' all group), one to cli-core's WIRECAT_TOOLS, and after the first release one to cli-docs' tools.json.", + ] + : []), + "CI's repo-setup job (cli-dev repo-check) fails until step 1 is done.", + ] // Ready to paste; the TODO values are the ones only a person can write. export const sharedListEntries = (names: Names, tagline: string, time: MonthlyTime, service?: string): string[] => { @@ -827,7 +804,7 @@ export const runNew = async ( io, ) const answers = collected.answers - const names = loaded ? { ...collected.names, prefix: loaded.config.identity.prefix } : collected.names + const names = withFreePrefix(loaded ? { ...collected.names, prefix: loaded.config.identity.prefix } : collected.names) const service = loaded?.config.identity.service ?? downloaded?.title if (preset && isWireCat(names)) throw new Error(`--preset ${preset} is for a CLI outside WireCat; ${names.package} is a WireCat package`) @@ -944,7 +921,7 @@ export const runNew = async ( const warnings = languageWarnings(answers.contentLang ?? [], category === "messenger") const clashes = nameClashes(names, prefixed) return [ - `Created ${target} from ${source.name}@${source.version}.`, + `Created ${names.name} from ${source.name}@${source.version}.`, ...(downloaded ? [ `Downloaded ${downloaded.title}, ${downloaded.operations} operations, into spec/${names.command}/${downloaded.file}; pnpm generate makes one command of each.`, @@ -957,27 +934,20 @@ export const runNew = async ( ...(clashes.length ? ["", "Names the service's own tools use:", ...clashes.map((clash) => ` ${clash}`)] : []), ...(warnings.length ? ["", "Content languages:", ...warnings.map((warning) => ` ${warning}`)] : []), "", - "Next:", + "Try it:", ` cd ${names.name}`, " pnpm install", - " pnpm lint:fix", " pnpm generate", + ` node dist/bin/${names.command}.js ${spec ? "api list" : "--help"}`, + "", + "Before the first commit:", + " pnpm bootstrap", ...(loaded ? [" pnpm source:check"] : []), - ...(spec - ? [ - " pnpm exec cli-contract contracts/plan.json --update", - " pnpm exec vitest run src/mcp.test.ts --update", - " pnpm lint:fix", - // The first generate writes the skill's parts, which the commands page lists only from the second. - " pnpm generate", - ] - : []), - " pnpm ci:quick", " git add -A", ' git commit -m "chore: start from @wirecat/cli-template"', ` then give the agent docs/dev/DESIGN.md; every account command passes a profile, e.g. ${names.command} personal config show`, "", - "Steps that need a person:", + preset ? "To publish:" : "Steps that need a person:", ...manualSteps(names, target, preset).map((step) => ` ${step}`), ...(isWireCat(names) ? [ diff --git a/kit/src/rename.ts b/kit/src/rename.ts index 70f282a..58e829d 100644 --- a/kit/src/rename.ts +++ b/kit/src/rename.ts @@ -66,3 +66,51 @@ export const stripKit = (path: string, content: Buffer): Buffer => { .replace(/"!?(\.\/)?kit\/[^"]*",\s*/g, "") return stripped === text ? content : Buffer.from(stripped, "utf8") } + +export const isWireCat = (names: Names): boolean => names.package.startsWith("@wirecat/") + +// Names the service's own tools already use. A CLI with the same environment prefix reads their token as its own; one +// with the same keyring service overwrites their sign-in. Each entry names where it was seen. +const TAKEN_PREFIXES: Record = { + // notion-cli BUG-759 (cli-factory plan, notion lessons). + NOTION: "Notion's MCP server reads NOTION_TOKEN", + // The cli-factory plan, 6.3.6. + HUBSPOT: "HubSpot's own tools read HUBSPOT_ variables", + // https://cli.github.com/manual/gh_help_environment + GH: "GitHub's gh reads GH_TOKEN", + GITHUB: "GitHub's gh reads GITHUB_TOKEN", +} +const TAKEN_SERVICES: Record = { + // notion-cli RISK-2303 (cli-factory plan, notion lessons). + "notion-cli": "Notion's ntn keeps its sign-in under the keyring service notion-cli", +} + +// A prefix the service's own tools read is replaced before any file is written, so nobody has to rename it by hand. +export const withFreePrefix = (names: Names): Names => { + const prefix = prefixOf(names) + if (names.prefix !== undefined || !TAKEN_PREFIXES[prefix]) return names + return { ...names, prefix: isWireCat(names) ? `WC${prefix}` : `${prefix}_CLI` } +} + +export const nameClashes = (names: Names, files: string[]): string[] => { + const prefix = prefixOf(names) + const taken = upperCommand(names.command) + const app = appNameOf(names) + return [ + ...(taken !== prefix && TAKEN_PREFIXES[taken] + ? [ + `${taken}_: ${TAKEN_PREFIXES[taken]}, so this CLI reads ${prefix}_ variables instead (envPrefix in src/identity.ts).`, + ] + : []), + ...(TAKEN_PREFIXES[prefix] + ? [ + `${prefix}_: ${TAKEN_PREFIXES[prefix]}, so ${names.command} would take its token. Pick another prefix (notion-cli uses WCNOTION): envPrefix in src/identity.ts and ${prefix}_ in ${files.join(", ")}. upgrade merges the template's own files, scripts/sandboxed.ts and docs/dev/TESTING.md, with ${prefix}_ in them: check them after each upgrade.`, + ] + : []), + ...(TAKEN_SERVICES[app] + ? [ + `keyring service ${app}: ${TAKEN_SERVICES[app]}, so a sign-in would replace it. Pick another name: appName in src/identity.ts.`, + ] + : []), + ] +} diff --git a/kit/test/from-config.test.ts b/kit/test/from-config.test.ts index 113f400..614cb9a 100644 --- a/kit/test/from-config.test.ts +++ b/kit/test/from-config.test.ts @@ -65,7 +65,7 @@ describe("new --from-config", () => { "node --experimental-strip-types scripts/source-check.ts", ) expect(read(dir, "scripts/source-check.ts")).toContain("crmManifestProblems(parseCrmManifest(") - expect(out).toContain(" pnpm generate\n pnpm source:check\n") + expect(out).toContain(" pnpm bootstrap\n pnpm source:check\n") expect(out).toContain('"displayName": "Acme",') }) diff --git a/kit/test/new.test.ts b/kit/test/new.test.ts index a5cc27c..6aee0a9 100644 --- a/kit/test/new.test.ts +++ b/kit/test/new.test.ts @@ -76,7 +76,7 @@ describe("new", () => { const { out } = await makeNew(NOTES_FLAGS) expect(out).toContain( - "\n cd cal-cli\n pnpm install\n pnpm lint:fix\n pnpm generate\n pnpm ci:quick\n git add -A\n", + "\n cd cal-cli\n pnpm install\n pnpm generate\n node dist/bin/cal.js --help\n\nBefore the first commit:\n pnpm bootstrap\n git add -A\n", ) expect(out).not.toContain("&&") }) @@ -302,7 +302,8 @@ describe("new from this repository", () => { expect(pkg.scripts.generate).toMatch(/^node --experimental-strip-types scripts\/generate.ts && /) expect(pkg.scripts["generate:check"]).toContain("scripts/generate.ts --check && ") expect(Boolean(pkg.devDependencies["@scalar/openapi-upgrader"])).toBe(spec === "swagger") - expect(out).toContain("cli-contract contracts/plan.json --update") + expect(pkg.scripts.bootstrap).toContain("cli-contract contracts/plan.json --update") + expect(out).toContain(" pnpm bootstrap\n") }) it("--spec none adds no api group", async () => { @@ -470,9 +471,9 @@ describe("new from this repository", () => { }) it.each([ - ["@wirecat/notion-cli", "notion", "NOTION_: Notion's MCP server reads NOTION_TOKEN"], + ["@wirecat/notion-cli", "notion", "NOTION_: Notion's MCP server reads NOTION_TOKEN, so this CLI reads WCNOTION_"], ["@wirecat/notion-cli", "wcnotion", "keyring service notion-cli: Notion's ntn"], - ["@example/gh-tool", "gh", "GH_: GitHub's gh reads GH_TOKEN"], + ["@example/gh-tool", "gh", "GH_: GitHub's gh reads GH_TOKEN, so this CLI reads GH_CLI_"], ])("warns when %s with the command %s takes a name the service's own tools use", async (pkg, command, warning) => { const cwd = tempDir("clash") const name = pkg.split("/")[1] ?? "" @@ -487,6 +488,19 @@ describe("new from this repository", () => { expect(out).toContain(warning) }) + it("writes the free prefix into the files, so no file reads the service's own variables", async () => { + const cwd = tempDir("clash") + await runNew( + cwd, + await loadSource(root), + { name: "gh-tool", flags: { ...NOTES_FLAGS, package: "@example/gh-tool", command: "gh" } }, + io(), + ) + + expect(read(join(cwd, "gh-tool"), "src/identity.ts")).toContain('"GH_CLI"') + expect(read(join(cwd, "gh-tool"), "docs/configuration.md")).toContain("GH_CLI_") + }) + it("makes the owner the copyright holder of an outside package, under the same Apache-2.0 text", async () => { const template = read(root, "LICENSE") const outside = read(await makeReal(NOTES_FLAGS), "LICENSE") diff --git a/kit/test/preset.test.ts b/kit/test/preset.test.ts index dce71a9..c117746 100644 --- a/kit/test/preset.test.ts +++ b/kit/test/preset.test.ts @@ -27,7 +27,9 @@ describe("new --preset generic", () => { expect(JSON.parse(read(dir, "template.json")).preset).toBe("generic") expect(read(dir, "src/identity.ts")).toContain(' tagline: "A CLI and MCP server, started from cli-template",\n') expect(read(dir, "docs/dev/DESIGN.md")).toContain("**Category:** other: api\n") - expect(out).toContain("2. Optional, since bin/release does not ask for it outside WireCat") + expect(out).toContain("To publish:\n 1. After the first commit, run node bin/setup-github") + expect(out).toContain("2. Once the first release pull request is merged, run node bin/release --first.") + expect(out).not.toContain(dir) expect(out).not.toContain("Entries for step 4") }) diff --git a/package.json b/package.json index b3fd4ab..ac5eac4 100644 --- a/package.json +++ b/package.json @@ -78,6 +78,7 @@ "audit:commands": "pnpm build && node --experimental-strip-types scripts/sandboxed.ts cli-dev audit --family --cli dist/bin/clidev.js --differences lint/audit-differences.json", "deps:check": "pnpm peers check && node --experimental-strip-types scripts/one-cli-base.ts", "ci:quick": "pnpm typecheck && pnpm deps:check && pnpm lint:commands", + "bootstrap": "pnpm lint:fix && pnpm generate && cli-contract contracts/plan.json --update && vitest run src/mcp.test.ts --update && pnpm lint:fix && pnpm generate && pnpm ci:quick", "release:check": "pnpm standards:check && pnpm deps:check && pnpm lint && pnpm typecheck && pnpm test:coverage && pnpm lint:commands && pnpm audit:commands && pnpm contracts:check && pnpm test:matrix:check && pnpm docs:check && pnpm generate:check && pnpm version:check && pnpm security:no-leak && pnpm package:check", "prepare": "lefthook install || true", "prepack": "pnpm build",