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
9 changes: 9 additions & 0 deletions changes/new-short-summary.md
Original file line number Diff line number Diff line change
@@ -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 `<PREFIX>_CLI_` (`WC<PREFIX>_` for a WireCat
package) and the summary says so, in place of a list of files to rename by hand.
11 changes: 6 additions & 5 deletions kit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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/<command>/` 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).

Expand Down
86 changes: 28 additions & 58 deletions kit/src/new.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.<owner>/.
Expand Down Expand Up @@ -652,50 +652,27 @@ export const markExecutable = async (cwd: string, paths: string[]): Promise<void
if (paths.length) await run("git", ["add", "--chmod=+x", "--", ...paths], { cwd })
}

export const manualSteps = (names: Names, dir: string, preset?: string): string[] => [
`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 <account>, and run ${join(dir, "bin/live")} <account> 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 <account> 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<string, string> = {
// 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<string, string> = {
// 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 <account>, and run ${join(dir, "bin/live")} <account> 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[] => {
Expand Down Expand Up @@ -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`)
Expand Down Expand Up @@ -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.`,
Expand All @@ -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)
? [
Expand Down
48 changes: 48 additions & 0 deletions kit/src/rename.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string> = {
// 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<string, string> = {
// 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.`,
]
: []),
]
}
2 changes: 1 addition & 1 deletion kit/test/from-config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",')
})

Expand Down
22 changes: 18 additions & 4 deletions kit/test/new.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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("&&")
})
Expand Down Expand Up @@ -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 () => {
Expand Down Expand Up @@ -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] ?? ""
Expand All @@ -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")
Expand Down
4 changes: 3 additions & 1 deletion kit/test/preset.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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")
})

Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Loading