@bunizao/cli-kit 0.5.1 → 0.7.0

package/README.md

@@ -26,6 +26,7 @@ import {
   createProgram,
   insertDefaultVerb,
   mutating,
+  SHARED_NOUNS,
   type NounSpec,
 } from "@bunizao/cli-kit";
 
@@ -35,17 +36,19 @@ const program = createProgram({
   description: "Example CLI",
 });
 
-const units = program.command("units").aliases(["courses", "projects"]);
-units.command("list").action(listUnits);
-units.command("show <unit>").action(showUnit);
-mutating(units.command("set <unit> <state>")).action(setUnitState);
+const courses = program.command("courses").aliases(["units", "projects"]);
+courses.command("list").action(listCourses);
+courses.command("show <course>").action(showCourse);
+const tasks = program.command("tasks");
+tasks.command("list <course>").action(listTasks);
+mutating(tasks.command("set <course> <task> <state>")).action(setTaskState);
 
 const nouns: readonly NounSpec[] = [
+  SHARED_NOUNS.courses,
   {
-    name: "units",
-    aliases: ["courses", "projects"],
-    verbs: ["list", "show", "set"],
-    defaultByArity: { 0: "list", 1: "show" },
+    name: "tasks",
+    verbs: ["list", "set"],
+    defaultByArity: { 1: "list" },
     valueFlags: [],
   },
 ];
@@ -163,13 +166,128 @@ aliases, positional arguments, options, enum values, nested commands, and `mutat
 commands at noun depth must use a verb exported in `VERBS`; unsupported verbs throw. `auth` and
 `skills` are action groups rather than domain nouns and are not assigned a `verb` field.
 
-The exit-code table, error vocabulary, and verb set are public versioned API. Changing one requires
-a major package release.
+A top-level command named after a shared noun's alias throws, and so does a verb that shared noun
+does not offer.
+
+The exit-code table, error vocabulary, verb set, and shared nouns are public versioned API. Changing
+one requires a major package release.
 
 The conformance suite is isolated under `conformance/`. Until all three CLIs have published their
 normalized releases, missing binaries are reported as skipped tests. Its CI workflow installs the
 published packages before running the suite.
 
+## Shared nouns
+
+`SHARED_NOUNS` holds the nouns every CLI names the same way. A CLI that offers one uses its spec
+as is, or with fewer verbs and its own `valueFlags`; domain nouns such as `tasks` or `lessons`
+stay with each CLI.
+
+| Noun | Aliases | Verbs | Default by arity |
+|---|---|---|---|
+| `courses` | `units`, `projects` | list, show, get | 0 list, 1 show |
+| `grades` | | list | 0 list, 1 list |
+
+`courses` is canonical because Ed and Moodle both call them courses; `units` is an Australian usage.
+
+Each `grades` row carries `grade` and `max` as numbers or `null`, and a `status` from
+`GRADE_STATUSES`: `graded`, `ungraded`, `unreleased` (marked but not released to the student),
+`not_submitted`, or `unavailable` (the platform refused or failed for that row). Display strings
+such as a letter grade or a range are optional extra fields.
+
+## Intents, skills and plugins
+
+An `Intent` maps what a person says to the command and the MCP tool that answer it. One list of
+intents is the single source for the skill, the MCP tool descriptions and the agent packaging:
+
+```ts
+const INTENTS: readonly Intent[] = [
+  {
+    when: "my grades / what did I get",
+    what: "Graded items per course with grade, max and status.",
+    command: "example grades [COURSE]",
+    tool: "list_grades",
+    refs: "course code, name or id",
+    then: "show the item for feedback",
+    cost: "small",
+  },
+];
+
+server.registerTool("list_grades", { description: toolDescription(INTENTS[0]) /* , schema */ }, handler);
+
+const files = agentFiles({
+  skill: {
+    name: "example-cli",
+    description: "Reads Example courses, grades and deadlines",
+    useWhen: 'the user names Example or asks "what\'s due", "my grades"',
+    title: "Example CLI",
+    intents: INTENTS,
+    mcpServer: "example",
+    workflows: [{ title: "Submit an assignment", steps: ["...", "Check the submission status"] }],
+    program: commandsJson(program),
+  },
+  version,
+  repository: "https://github.com/example/example-cli",
+  author: { name: "example" },
+  mcpServers: { example: { command: "npx", args: ["-y", "example-cli", "mcp"] } },
+});
+writeAgentFiles(process.cwd(), files); // { check: true } returns stale paths for CI
+```
+
+`agentFiles` returns, by path from the repository root:
+
+- `skills/<name>/SKILL.md`, which `npx skills add owner/repo` and Claude Code both find. An agent
+  loads it whole, so it stays short: one table of what the user says against the CLI command and
+  the `server:tool` MCP tool, the workflows as copyable checklists, the rules and the setup. A CLI
+  with a mutating command gets the shared dry-run, confirm, apply, read-back workflow first. Each
+  tool's full description stays with the MCP server.
+- The frontmatter description is `description` then "Use when `useWhen`". `renderSkill` throws
+  when the name or description breaks the Agent Skills limits (lowercase hyphenated name, 1024
+  characters, no `<` or `>`) or uses "I" or "you" outside quotes.
+- `skills/<name>/references/commands.md`: every command with its arguments, options and whether
+  it mutates, plus the exit codes. Pages in `references` are written next to it.
+- `skills/<name>/agents/openai.yaml`, when `openai` metadata is given.
+- `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`: the repository is a Claude
+  Code plugin, which loads `skills/` by default, and its own marketplace. Install with
+  `claude plugin marketplace add owner/repo`, then `claude plugin install example-cli@example-cli`.
+  A repository with a root `CLAUDE.md` gets one validator warning, since that file is not plugin
+  context; `claude plugin validate .` passes, `--strict` does not.
+
+`writeAgentFiles` never deletes, so a CLI moving to this layout removes its old root `SKILL.md`,
+`references/` and `agents/` itself.
+
+An MCP server that runs on Cloudflare Workers imports `toolDescription` from
+`@bunizao/cli-kit/intents`, which pulls in neither commander nor Node builtins.
+
+`checkIntentCommands(program, nouns, intents)` throws when an intent's command no longer parses:
+a renamed noun or verb, a removed option, or the wrong binary name. Call it from the CLI's tests
+so the skill and the MCP descriptions cannot drift from the command tree.
+
+### Trigger evals
+
+`evals/trigger.mjs` checks whether the descriptions route requests to the right skill. It puts
+every sibling skill in one Codex workspace, so they compete as they do for a student who has all
+three installed. A skill that steals its sibling's requests looks like the sibling undertriggering
+when either is tested alone. For each query it records which `skills/<name>/` Codex opens first.
+
+```bash
+node evals/trigger.mjs \
+  --skill ../moodle-cli/skills/moodle-cli \
+  --skill ../ontrack-cli/skills/ontrack-cli \
+  --skill ../edstem-cli/skills/edstem-cli \
+  --runs 3
+```
+
+- The folder name is the skill name. `--pool` defaults to `evals/trigger-pool.json`: 29
+  requests, each with the skill it should reach or `none`. `--model` defaults to Codex's configured
+  model. `--out` keeps every run's pick and first command.
+- Each Codex run is killed at its first command, and each skill's binary (`moodle`, `ontrack`,
+  `edstem`) is a failing stub first on `PATH`, so nothing reaches a real account. `HOME` is a
+  temporary folder that hides the user's own skills; `CODEX_HOME` keeps the sign-in.
+- A run costs about 16k input tokens, so the default 29 × 3 is about 1.4M. Results move by about
+  one run per query between passes, so compare changes across three runs, not one.
+- This measures Codex, not Claude. Claude Code reads the same folder layout and frontmatter, but
+  its routing can differ.
+
 ## Prompts and progress
 
 `createUi` gives every CLI the same interactive surface, drawn with `@clack/prompts` on
@@ -187,8 +305,10 @@ spin.stop("Uploaded 2 files");
 ui.outro("Done");
 ```
 
-`select` switches to type-to-filter above `AUTOCOMPLETE_FROM` choices. Ctrl+C inside a
-prompt throws a `cancelled` error (exit 130). `confirm(plan, options)` is built on the same
+`select` switches to type-to-filter above `AUTOCOMPLETE_FROM` choices, or always with
+`{ search: true }`; every typed word must appear in the label or hint, in any order.
+`{ initial }` highlights a row. A multi-step picker passes `{ back: true }` and gets `BACK`
+when the person presses Escape. Ctrl+C inside a prompt throws a `cancelled` error (exit 130). `confirm(plan, options)` is built on the same
 layer and keeps its contract: `--dry-run` prints the plan, `--yes` skips the question, a pipe
 without `--yes` is a usage error.
 

package/dist/index.d.ts

@@ -4,9 +4,11 @@ export * from "./color.js";
 export * from "./confirm.js";
 export * from "./errors.js";
 export * from "./help.js";
+export * from "./intents.js";
 export * from "./nouns.js";
 export * from "./output.js";
 export * from "./program.js";
 export * from "./report.js";
+export * from "./skills.js";
 export * from "./ui.js";
 export * from "./theme.js";

package/dist/index.js

@@ -4,9 +4,11 @@ export * from "./color.js";
 export * from "./confirm.js";
 export * from "./errors.js";
 export * from "./help.js";
+export * from "./intents.js";
 export * from "./nouns.js";
 export * from "./output.js";
 export * from "./program.js";
 export * from "./report.js";
+export * from "./skills.js";
 export * from "./ui.js";
 export * from "./theme.js";

package/dist/intents.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from "commander";
+import { type NounSpec } from "./nouns.js";
+/**
+ * One thing a person asks for, mapped to the CLI command and the MCP tool that answer it.
+ * The skill, the MCP tool descriptions and the help text all render from these fields.
+ */
+export interface Intent {
+    /** What the person says, e.g. "my grades / what did I get". */
+    readonly when: string;
+    /** What comes back, as a sentence. */
+    readonly what: string;
+    /** The command as typed, with placeholders such as UNIT; omitted for an MCP-only tool. */
+    readonly command?: string;
+    /** The MCP tool for the same request; omitted for a CLI-only command. */
+    readonly tool?: string;
+    /** Where nearby requests go instead, e.g. "get_thread for thread bodies". */
+    readonly instead?: string;
+    /** The references and arguments it accepts. */
+    readonly refs?: string;
+    /** The usual next step. */
+    readonly then?: string;
+    /** Rough response size. */
+    readonly cost?: string;
+}
+/** The MCP tool description for an intent: prose, because a model reads it. */
+export declare function toolDescription(intent: Intent): string;
+/**
+ * Throw when an intent's command no longer parses against the program: a renamed noun or verb,
+ * a wrong binary name, or an option that was removed. Run it in the CLI's tests.
+ */
+export declare function checkIntentCommands(program: Command, nouns: readonly NounSpec[], intents: readonly Intent[]): void;

package/dist/intents.js

@@ -0,0 +1,70 @@
+import { insertDefaultVerb } from "./nouns.js";
+/** The MCP tool description for an intent: prose, because a model reads it. */
+export function toolDescription(intent) {
+    return [
+        sentence(intent.what),
+        sentence(`Use when the user says "${intent.when}"`),
+        intent.instead && sentence(`Instead: ${intent.instead}`),
+        intent.refs && sentence(`Input: ${intent.refs}`),
+        intent.then && sentence(`Then: ${intent.then}`),
+        intent.cost && sentence(`Cost: ${intent.cost}`),
+    ].filter(Boolean).join(" ");
+}
+/**
+ * Throw when an intent's command no longer parses against the program: a renamed noun or verb,
+ * a wrong binary name, or an option that was removed. Run it in the CLI's tests.
+ */
+export function checkIntentCommands(program, nouns, intents) {
+    const problems = intents.flatMap((intent) => (intent.command ? commandProblems(program, nouns, intent.command) : []));
+    if (problems.length)
+        throw new Error(`Intent commands out of date:\n${problems.join("\n")}`);
+}
+const ALWAYS_ACCEPTED = new Set(["-h", "--help", "-V", "--version"]);
+function commandProblems(program, nouns, text) {
+    const [binary, ...rest] = words(text);
+    if (binary !== program.name())
+        return [`${text}: starts with "${binary}", not "${program.name()}"`];
+    const argv = insertDefaultVerb(rest.map(unwrapOptionalFlag), nouns);
+    const path = [program];
+    let unmatched;
+    for (const token of argv) {
+        if (token.startsWith("-"))
+            continue;
+        const current = path.at(-1);
+        const child = current.commands.find((command) => command.name() === token || command.aliases().includes(token));
+        if (!child) {
+            unmatched = token;
+            break;
+        }
+        path.push(child);
+    }
+    const problems = [];
+    const resolved = path.at(-1);
+    // A group that takes no arguments of its own must be followed by one of its commands.
+    if (unmatched !== undefined && resolved.commands.length && !resolved.registeredArguments.length) {
+        problems.push(`${text}: "${unmatched}" is not a command of "${path.map((command) => command.name()).join(" ")}"`);
+    }
+    const options = new Set(path.flatMap((command) => command.options.flatMap(optionNames)));
+    for (const token of argv) {
+        const flag = token.split("=")[0] ?? token;
+        if (flag.startsWith("-") && !ALWAYS_ACCEPTED.has(flag) && !options.has(flag)) {
+            problems.push(`${text}: unknown option "${flag}"`);
+        }
+    }
+    return problems;
+}
+// Quoted strings and bracketed placeholders such as <lesson id> stay one word.
+function words(text) {
+    return text.replace(/^`|`$/g, "").match(/"[^"]*"|'[^']*'|<[^>]*>|\[[^\]]*\]|\S+/g) ?? [];
+}
+// `[--final]` documents an optional flag; check it like `--final`.
+function unwrapOptionalFlag(token) {
+    const inner = /^\[(-[^\s\]]+)/.exec(token);
+    return inner?.[1] ?? token;
+}
+function optionNames(option) {
+    return [option.long, option.short].filter((name) => Boolean(name));
+}
+function sentence(text) {
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}

package/dist/nouns.d.ts

@@ -6,4 +6,30 @@ export interface NounSpec {
     /** Option flags whose following token is a value, not a positional argument. */
     readonly valueFlags?: readonly string[];
 }
+/**
+ * Nouns every CLI names the same way. A CLI that offers one uses its spec as is, or with fewer
+ * verbs and its own valueFlags, so `moodle grades` and `edstem grades` read alike.
+ */
+export declare const SHARED_NOUNS: {
+    readonly courses: {
+        readonly name: "courses";
+        readonly aliases: readonly ["units", "projects"];
+        readonly verbs: readonly ["list", "show", "get"];
+        readonly defaultByArity: {
+            readonly 0: "list";
+            readonly 1: "show";
+        };
+    };
+    readonly grades: {
+        readonly name: "grades";
+        readonly verbs: readonly ["list"];
+        readonly defaultByArity: {
+            readonly 0: "list";
+            readonly 1: "list";
+        };
+    };
+};
+/** The `status` of one row in `grades` output. */
+export declare const GRADE_STATUSES: readonly ["graded", "ungraded", "unreleased", "not_submitted", "unavailable"];
+export type GradeStatus = (typeof GRADE_STATUSES)[number];
 export declare function insertDefaultVerb(argv: readonly string[], nouns: readonly NounSpec[]): string[];

package/dist/nouns.js

@@ -1,3 +1,22 @@
+/**
+ * Nouns every CLI names the same way. A CLI that offers one uses its spec as is, or with fewer
+ * verbs and its own valueFlags, so `moodle grades` and `edstem grades` read alike.
+ */
+export const SHARED_NOUNS = {
+    courses: {
+        name: "courses",
+        aliases: ["units", "projects"],
+        verbs: ["list", "show", "get"],
+        defaultByArity: { 0: "list", 1: "show" },
+    },
+    grades: {
+        name: "grades",
+        verbs: ["list"],
+        defaultByArity: { 0: "list", 1: "list" },
+    },
+};
+/** The `status` of one row in `grades` output. */
+export const GRADE_STATUSES = ["graded", "ungraded", "unreleased", "not_submitted", "unavailable"];
 const GLOBAL_VALUE_FLAGS = new Set(["--fields", "-o", "--output"]);
 export function insertDefaultVerb(argv, nouns) {
     const result = [...argv];

package/dist/program.js

@@ -1,8 +1,10 @@
 import { Command } from "commander";
 import { colorEnabled } from "./color.js";
 import { styledHelp } from "./help.js";
+import { SHARED_NOUNS } from "./nouns.js";
 export const VERBS = ["list", "show", "read", "get", "search", "send", "submit", "set", "mark-read"];
 const VERB_SET = new Set(VERBS);
+const SHARED = Object.values(SHARED_NOUNS);
 const mutations = new WeakSet();
 const ACTION_GROUPS = new Set(["auth", "skills"]);
 const ACTIONS = {
@@ -53,9 +55,20 @@ function describe(command, noun) {
     if (noun && ACTION_GROUPS.has(noun) && !ACTIONS[noun]?.has(command.name())) {
         throw new Error(`Unsupported action "${command.name()}" on group "${noun}".`);
     }
+    // A shared noun's name and aliases belong to that noun alone, whether used as a name or an alias.
+    for (const word of noun ? [] : [currentNoun, ...command.aliases()]) {
+        const owner = SHARED.find((spec) => spec.name === word || spec.aliases?.includes(word));
+        if (owner && owner.name !== currentNoun) {
+            throw new Error(`"${word}" belongs to the shared noun "${owner.name}"; name that command "${owner.name}".`);
+        }
+    }
     if (verb && !VERB_SET.has(verb)) {
         throw new Error(`Unsupported verb "${verb}" on noun "${noun}".`);
     }
+    const shared = SHARED.find((spec) => spec.name === noun);
+    if (verb && shared && !shared.verbs.includes(verb)) {
+        throw new Error(`Unsupported verb "${verb}" on shared noun "${noun}".`);
+    }
     return {
         name: command.name(),
         noun: currentNoun,

package/dist/skills.d.ts

@@ -0,0 +1,92 @@
+import type { Intent } from "./intents.js";
+import type { ProgramDescription } from "./program.js";
+export interface SkillOptions {
+    /** The skill and plugin name, e.g. "edstem-cli". */
+    readonly name: string;
+    /** What the skill does, in the third person. It is also the plugin's description. */
+    readonly description: string;
+    /**
+     * When an agent should load the skill, rendered after the description as "Use when …". Name the
+     * site and quote what people say; agents undertrigger, so list more phrases rather than fewer.
+     */
+    readonly useWhen: string;
+    readonly title: string;
+    /** Markdown between the title and the intent table: the surfaces and the reference vocabulary. */
+    readonly intro?: string;
+    readonly intents: readonly Intent[];
+    /** The MCP server name tools are qualified with: "moodle" renders `moodle:due`. Required when an intent has a tool. */
+    readonly mcpServer?: string;
+    /** Multi-step tasks rendered as checklists, after the shared one for mutating commands. */
+    readonly workflows?: readonly Workflow[];
+    /** Rules for this CLI only; the shared contract rules are always included. */
+    readonly rules?: readonly string[];
+    /** Markdown for the Setup section. */
+    readonly setup?: string;
+    /** `commandsJson(program)` output. */
+    readonly program: ProgramDescription;
+}
+export interface Workflow {
+    /** An imperative title, e.g. "Submit an assignment". */
+    readonly title: string;
+    /** In order; end with a step that checks the result. */
+    readonly steps: readonly string[];
+}
+/** A local stdio server, or a hosted Streamable HTTP server. */
+export type McpServer = {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+} | {
+    readonly type: "http";
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+};
+export interface AgentFilesOptions {
+    readonly skill: SkillOptions;
+    readonly version: string;
+    /** The GitHub repository URL; it is also the plugin's homepage. */
+    readonly repository: string;
+    readonly author: {
+        readonly name: string;
+        readonly url?: string;
+    };
+    readonly license?: string;
+    readonly keywords?: readonly string[];
+    /** MCP servers the Claude Code plugin starts, keyed by server name. */
+    readonly mcpServers?: Readonly<Record<string, McpServer>>;
+    /** Codex skill metadata, written to agents/openai.yaml in the skill folder. */
+    readonly openai?: {
+        readonly displayName: string;
+        readonly shortDescription: string;
+        readonly defaultPrompt: string;
+    };
+    /** Hand-written reference pages by file name, written next to the command reference. */
+    readonly references?: Readonly<Record<string, string>>;
+}
+/** Where agentFiles puts the full command tree, relative to the skill folder; SKILL.md links to it. */
+export declare const COMMAND_REFERENCE = "references/commands.md";
+/** The frontmatter description: what the skill does, then when to use it. */
+export declare function skillDescription(options: Pick<SkillOptions, "description" | "useWhen">): string;
+/**
+ * SKILL.md for one CLI: what people say, what to run, the workflows, the rules and the setup.
+ * An agent loads it whole, so the command tree lives in COMMAND_REFERENCE and each MCP tool's
+ * full description stays with the server. Throws when the name or description breaks the
+ * Agent Skills limits.
+ */
+export declare function renderSkill(options: SkillOptions): string;
+/** The full command tree and the exit codes, written to COMMAND_REFERENCE. */
+export declare function renderCommandReference(program: ProgramDescription): string;
+/**
+ * Every agent packaging file for one CLI repository, keyed by path from the repository root:
+ * the skill folder skills/<name>/ (SKILL.md, its references and Codex's agents/openai.yaml), which
+ * `npx skills add` and Claude Code both find, plus the Claude Code plugin and its single-plugin
+ * marketplace.
+ */
+export declare function agentFiles(options: AgentFilesOptions): Record<string, string>;
+/**
+ * Write generated files under root. With `check`, write nothing and return the paths whose
+ * content differs, so CI can fail on a stale commit.
+ */
+export declare function writeAgentFiles(root: string, files: Readonly<Record<string, string>>, options?: {
+    check?: boolean;
+}): string[];

package/dist/skills.js

@@ -0,0 +1,225 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stringify } from "yaml";
+import { EXIT_CODES } from "./errors.js";
+/** Where agentFiles puts the full command tree, relative to the skill folder; SKILL.md links to it. */
+export const COMMAND_REFERENCE = "references/commands.md";
+const RULES = {
+    narrow: "Start from the table row that matches the request: the narrowest command or tool answers sooner and costs fewer tokens than a broad listing.",
+    output: "Piped output is JSON. `--fields a,b` keeps only those top-level fields, which keeps long lists cheap.",
+    read: "`read` prints Markdown and changes nothing upstream, so it is safe to run unasked.",
+    mutate: "Change something upstream only when the user asked for that change: other people see it, and most changes cannot be undone.",
+    secrets: "Keep tokens, cookies and session files out of replies, logs and files; each one is a live sign-in.",
+    errors: "A failure prints one error with a `hint` on stderr; follow the hint before retrying.",
+};
+const MUTATION_WORKFLOW = {
+    title: "Change something upstream",
+    steps: [
+        "Check the user asked for this change, on these targets",
+        "Run the command with `--dry-run` and show the plan",
+        "Get the user's yes to that plan",
+        "Run it again with `--yes`",
+        "Read the result back with the matching `list` or `show` and report what changed",
+    ],
+};
+/** The frontmatter description: what the skill does, then when to use it. */
+export function skillDescription(options) {
+    return `${sentence(options.description)} Use when ${sentence(options.useWhen)}`;
+}
+/**
+ * SKILL.md for one CLI: what people say, what to run, the workflows, the rules and the setup.
+ * An agent loads it whole, so the command tree lives in COMMAND_REFERENCE and each MCP tool's
+ * full description stays with the server. Throws when the name or description breaks the
+ * Agent Skills limits.
+ */
+export function renderSkill(options) {
+    const description = skillDescription(options);
+    const problems = frontmatterProblems(options.name, description);
+    if (problems.length)
+        throw new Error(`Skill "${options.name}" frontmatter:\n${problems.join("\n")}`);
+    const binary = options.program.name;
+    const hasRead = someCommand(options.program, (command) => command.verb === "read");
+    const hasMutation = someCommand(options.program, (command) => command.mutating);
+    const workflows = [...(hasMutation ? [MUTATION_WORKFLOW] : []), ...(options.workflows ?? [])];
+    return [
+        stringifyFrontmatter({ name: options.name, description }),
+        `# ${options.title}`,
+        options.intro,
+        "## What the user says, and what to run",
+        intentTable(options),
+        workflows.length
+            ? ["## Workflows", "Copy the checklist into your reply and tick each step as it is done; the last step is what shows the change landed.", ...workflows.map(renderWorkflow)].join("\n\n")
+            : undefined,
+        "## Rules",
+        [
+            RULES.narrow,
+            RULES.output,
+            ...(hasRead ? [RULES.read] : []),
+            ...(hasMutation ? [RULES.mutate] : []),
+            RULES.secrets,
+            RULES.errors,
+            ...(options.rules ?? []),
+            `Every command, argument, option and exit code is in [${COMMAND_REFERENCE}](${COMMAND_REFERENCE}); \`${binary} commands --json\` is the source of truth.`,
+        ]
+            .map((rule) => `- ${rule}`)
+            .join("\n"),
+        options.setup ? `## Setup\n\n${options.setup}` : undefined,
+    ].filter((section) => Boolean(section)).join("\n\n") + "\n";
+}
+/** The full command tree and the exit codes, written to COMMAND_REFERENCE. */
+export function renderCommandReference(program) {
+    const exitCodes = Object.entries(EXIT_CODES).map(([code, exit]) => [String(exit), code]);
+    return [
+        `# ${program.name} commands`,
+        `Generated from \`${program.name} commands --json\` for version ${program.version}.`,
+        markdownTable(["Command", "Description", "Arguments", "Options", "Mutating"], program.commands.flatMap((command) => commandRows(program.name, command))),
+        "## Exit codes",
+        "With `--json`, a failure is one `{ ok: false, error: { code, message, hint } }` object on stderr.",
+        markdownTable(["Exit", "Error code"], [["0", "success"], ...exitCodes]),
+    ].join("\n\n") + "\n";
+}
+/**
+ * Every agent packaging file for one CLI repository, keyed by path from the repository root:
+ * the skill folder skills/<name>/ (SKILL.md, its references and Codex's agents/openai.yaml), which
+ * `npx skills add` and Claude Code both find, plus the Claude Code plugin and its single-plugin
+ * marketplace.
+ */
+export function agentFiles(options) {
+    const { skill } = options;
+    const folder = `skills/${skill.name}`;
+    const files = {
+        [`${folder}/SKILL.md`]: renderSkill(skill),
+        [`${folder}/${COMMAND_REFERENCE}`]: renderCommandReference(skill.program),
+    };
+    for (const [name, content] of Object.entries(options.references ?? {})) {
+        files[`${folder}/${dirname(COMMAND_REFERENCE)}/${name}`] = content;
+    }
+    if (options.openai) {
+        files[`${folder}/agents/openai.yaml`] = stringify({
+            interface: {
+                display_name: options.openai.displayName,
+                short_description: options.openai.shortDescription,
+                default_prompt: options.openai.defaultPrompt,
+            },
+        }, { lineWidth: 0 });
+    }
+    // The repository root is the plugin root; Claude Code loads skills/ from it by default.
+    files[".claude-plugin/plugin.json"] = json({
+        name: skill.name,
+        version: options.version,
+        description: skill.description,
+        author: options.author,
+        homepage: options.repository,
+        repository: options.repository,
+        ...(options.license ? { license: options.license } : {}),
+        ...(options.keywords?.length ? { keywords: options.keywords } : {}),
+        ...(options.mcpServers ? { mcpServers: options.mcpServers } : {}),
+    });
+    files[".claude-plugin/marketplace.json"] = json({
+        name: skill.name,
+        description: skill.description,
+        owner: options.author,
+        plugins: [{ name: skill.name, source: "./", description: skill.description }],
+    });
+    return files;
+}
+/**
+ * Write generated files under root. With `check`, write nothing and return the paths whose
+ * content differs, so CI can fail on a stale commit.
+ */
+export function writeAgentFiles(root, files, options = {}) {
+    const stale = Object.entries(files)
+        .filter(([path, content]) => readOrEmpty(join(root, path)) !== content)
+        .map(([path]) => path);
+    if (options.check)
+        return stale;
+    for (const path of stale) {
+        mkdirSync(dirname(join(root, path)), { recursive: true });
+        writeFileSync(join(root, path), files[path], "utf8");
+    }
+    return stale;
+}
+// The limits from the Agent Skills spec, plus the third person: the description is read as
+// part of the system prompt, where "I" and "you" point at the wrong speaker.
+function frontmatterProblems(name, description) {
+    const problems = [];
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || name.length > 64)
+        problems.push(`name must be lowercase words joined by hyphens, at most 64 characters`);
+    if (/anthropic|claude/.test(name))
+        problems.push(`name must not contain "anthropic" or "claude"`);
+    if (description.length > 1024)
+        problems.push(`description is ${description.length} characters; the limit is 1024`);
+    if (/[<>]/.test(description))
+        problems.push("description must not contain < or >");
+    // Quoted phrases are what the user says, so "my grades" is fine there.
+    const unquoted = description.replace(/"[^"]*"|“[^”]*”/g, "");
+    const person = /\b(?:I|me|my|we|our|you|your)\b/i.exec(unquoted);
+    if (person)
+        problems.push(`description must be in the third person outside quotes; found "${person[0]}"`);
+    return problems;
+}
+function intentTable(options) {
+    const { intents, mcpServer } = options;
+    if (!mcpServer && intents.some((intent) => intent.tool)) {
+        throw new Error(`Skill "${options.name}" has MCP tools but no mcpServer to qualify them with.`);
+    }
+    const columns = [["The user says", (intent) => intent.when]];
+    if (intents.some((intent) => intent.command))
+        columns.push(["CLI", (intent) => (intent.command ? `\`${intent.command}\`` : "")]);
+    if (intents.some((intent) => intent.tool))
+        columns.push(["MCP tool", (intent) => (intent.tool ? `\`${mcpServer}:${intent.tool}\`` : "")]);
+    if (intents.some((intent) => intent.then))
+        columns.push(["Then", (intent) => intent.then ?? ""]);
+    return markdownTable(columns.map(([header]) => header), intents.map((intent) => columns.map(([, cell]) => cell(intent))));
+}
+// A fenced block, so the agent copies it verbatim and ticks it in its reply.
+function renderWorkflow(workflow) {
+    return [`### ${workflow.title}`, ["```text", ...workflow.steps.map((step) => `- [ ] ${step}`), "```"].join("\n")].join("\n\n");
+}
+function someCommand(program, test) {
+    return program.commands.some(function visit(command) {
+        return test(command) || command.commands.some(visit);
+    });
+}
+function commandRows(binary, command, parents = []) {
+    const path = [...parents, command.name];
+    const row = [
+        `\`${[binary, ...path].join(" ")}\``,
+        command.description,
+        command.positionals.map((argument) => {
+            const name = argument.variadic ? `${argument.name}...` : argument.name;
+            return argument.required ? `<${name}>` : `[${name}]`;
+        }).join(" "),
+        command.options.map((option) => option.flags).join("<br>"),
+        command.mutating ? "yes" : "no",
+    ];
+    return [row, ...command.commands.flatMap((child) => commandRows(binary, child, path))];
+}
+function stringifyFrontmatter(fields) {
+    return `---\n${stringify(fields, { lineWidth: 0 })}---`;
+}
+function markdownTable(headers, rows) {
+    return [
+        `| ${headers.join(" | ")} |`,
+        `| ${headers.map(() => "---").join(" | ")} |`,
+        ...rows.map((row) => `| ${row.map(escapeCell).join(" | ")} |`),
+    ].join("\n");
+}
+function escapeCell(value) {
+    return value.replace(/\|/g, "\\|").replace(/\n/g, "<br>");
+}
+function sentence(text) {
+    const trimmed = text.trim();
+    return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+function json(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function readOrEmpty(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/theme.js

@@ -10,8 +10,8 @@ const TONE_STYLE = {
 // Checked in order: a negated word ("not graded") must win over the word it contains.
 const TONE_WORDS = [
     ["muted", /^(?:-|—|none|n\/a|unknown)$|\b(?:not[ _](?:started|submitted|graded|attempted|available|yet)|no submission|un(?:attempted|graded|submitted)|archived|hidden|unlisted|inactive|closed|disabled)\b/iu],
-    ["danger", /\b(?:overdue|late|fail(?:ed|ure)?|error|missing|rejected|need(?:s)?[ _]help|blocked|expired|redo|resubmit|demonstrate|exceeded)\b/iu],
-    ["warning", /\b(?:pending|draft|working|in[ _]progress|due soon|today|tomorrow|awaiting|unanswered|scheduled|discuss|attempted|partial)\b/iu],
+    ["danger", /\b(?:overdue|late|fail(?:ed|ure)?|error|missing|rejected|need(?:s)?[ _]help|blocked|expired|redo|resubmit|demonstrate|exceeded|unavailable)\b/iu],
+    ["warning", /\b(?:pending|draft|working|in[ _]progress|due soon|today|tomorrow|awaiting|unanswered|scheduled|discuss|attempted|partial|unreleased)\b/iu],
     ["success", /\b(?:complete[d]?|done|submitted|graded|accepted|passed|resolved|answered|ready[ _]for[ _]feedback|active|signed in|ok|success(?:ful)?|enrolled)\b/iu],
     ["accent", /\b(?:announcement|pinned|staff|endorsed|official|urgent)\b/iu],
     ["info", /\b(?:question|post|note|general|info)\b/iu],

package/dist/ui.d.ts

@@ -9,6 +9,19 @@ export interface Choice<T> {
     readonly label: string;
     readonly hint?: string;
 }
+/** What `select` resolves when the person presses Escape on a prompt opened with `back: true`. */
+export declare const BACK: unique symbol;
+export interface SelectOptions<T> {
+    /** Type-to-filter at any length; a short list still wants it when the person knows the name. */
+    readonly search?: boolean;
+    /** The row highlighted when the list opens. */
+    readonly initial?: T;
+    /**
+     * Escape resolves `BACK` instead of cancelling, so a multi-step picker can return to the
+     * previous step. Ctrl+C still cancels.
+     */
+    readonly back?: boolean;
+}
 export interface UiOptions {
     /** Keyboard input. Defaults to `process.stdin`. */
     readonly input?: NodeJS.ReadStream;
@@ -30,6 +43,8 @@ export interface Spinner {
     /** End the step and leave `message` (or the last running text) as the permanent line. */
     stop(message?: string): void;
     error(message?: string): void;
+    /** End the step and erase it, for progress whose outcome is printed elsewhere. */
+    clear(): void;
 }
 export interface Ui {
     readonly interactive: boolean;
@@ -47,10 +62,14 @@ export interface Ui {
     spinner(): Spinner;
     /**
      * Let the person pick one row. Above `AUTOCOMPLETE_FROM` choices the list becomes
-     * type-to-filter, because arrowing through thirty forum threads is not a picker.
+     * type-to-filter, because arrowing through thirty forum threads is not a picker. The
+     * filter matches every typed word anywhere in the label or hint, in any order.
      * Without a terminal this throws a usage error that lists the choices.
      */
-    select<T>(message: string, choices: readonly Choice<T>[]): Promise<T>;
+    select<T>(message: string, choices: readonly Choice<T>[], options: SelectOptions<T> & {
+        readonly back: true;
+    }): Promise<T | typeof BACK>;
+    select<T>(message: string, choices: readonly Choice<T>[], options?: SelectOptions<T>): Promise<T>;
     /** Yes or no. Without a terminal this throws a usage error. */
     confirm(message: string, options?: {
         readonly initial?: boolean;

package/dist/ui.js

@@ -6,6 +6,8 @@ import * as clack from "@clack/prompts";
 import { isAgentEnvironment } from "./audience.js";
 import { colorEnabled, painter } from "./color.js";
 import { CliError } from "./errors.js";
+/** What `select` resolves when the person presses Escape on a prompt opened with `back: true`. */
+export const BACK = Symbol("cli-kit.back");
 export const AUTOCOMPLETE_FROM = 8;
 /**
  * Every CLI in the family draws the same way: prompts, steps and spinners on stderr
@@ -18,8 +20,15 @@ export function createUi(options = {}) {
     const output = options.output ?? process.stderr;
     const interactive = options.interactive
         ?? (Boolean(input.isTTY) && Boolean(output.isTTY) && !isAgentEnvironment(options.env));
-    const common = { input, output, ...(options.signal ? { signal: options.signal } : {}) };
-    const plain = (text) => output.write(`${text}\n`);
+    // Escape erases the abandoned step and the answer above it, so going back looks like
+    // the earlier question was never answered. That needs to know how many rows each prompt
+    // drew; clack redraws with relative moves, so counting newlines and cursor-up/down
+    // sequences written through the ui gives it.
+    let row = 0;
+    const answered = [];
+    const drawn = interactive ? trackRows(output, delta => { row += delta; }) : output;
+    const common = { input, output: drawn, ...(options.signal ? { signal: options.signal } : {}) };
+    const plain = (text) => drawn.write(`${text}\n`);
     const paint = painter(colorEnabled(output, options.env));
     return {
         interactive,
@@ -30,7 +39,7 @@ export function createUi(options = {}) {
                 return;
             }
             const lines = art.replace(/^\n+|\s+$/gu, "").split("\n").map(line => paint("cyan", line));
-            output.write(`${lines.join("\n")}\n${tagline ? `${paint("dim", tagline)}\n` : ""}\n`);
+            drawn.write(`${lines.join("\n")}\n${tagline ? `${paint("dim", tagline)}\n` : ""}\n`);
         },
         intro: title => (interactive ? clack.intro(title, common) : plain(title)),
         outro: message => (interactive ? clack.outro(message, common) : plain(message)),
@@ -41,11 +50,31 @@ export function createUi(options = {}) {
         spinner() {
             if (interactive) {
                 const inner = clack.spinner(common);
+                // Clack's spinner holds stdin in raw mode and answers Ctrl+C with process.exit(0),
+                // which skips the caller's cleanup and leaves half-written files behind. Handing
+                // the key back to the terminal makes it a real SIGINT: the spinner erases itself,
+                // the CLI's own handler runs, and a CLI without one still dies as Ctrl+C always has.
+                const onInterrupt = () => {
+                    process.off("SIGINT", onInterrupt);
+                    inner.clear();
+                    if (!process.listenerCount("SIGINT"))
+                        process.kill(process.pid, "SIGINT");
+                };
+                const end = (finish) => {
+                    process.off("SIGINT", onInterrupt);
+                    finish();
+                };
                 return {
-                    start: message => inner.start(message),
+                    start: message => {
+                        inner.start(message);
+                        if (process.stdin.isTTY)
+                            process.stdin.setRawMode(false);
+                        process.prependListener("SIGINT", onInterrupt);
+                    },
                     message: message => inner.message(message),
-                    stop: message => inner.stop(message),
-                    error: message => inner.error(message),
+                    stop: message => end(() => inner.stop(message)),
+                    error: message => end(() => inner.error(message)),
+                    clear: () => end(() => inner.clear()),
                 };
             }
             // A pipe is read after the fact: only the outcome of a step is worth a line.
@@ -55,9 +84,10 @@ export function createUi(options = {}) {
                 message: message => { running = message; },
                 stop: message => plain(message ?? running),
                 error: message => plain(`error: ${message ?? running}`),
+                clear: () => { running = ""; },
             };
         },
-        async select(message, choices) {
+        async select(message, choices, selectOptions = {}) {
             if (!choices.length)
                 throw new CliError("unexpected", `Nothing to choose for "${message}".`);
             if (!interactive) {
@@ -65,10 +95,33 @@ export function createUi(options = {}) {
             }
             // `Option<T>` is conditional on T being primitive, which an open generic cannot resolve.
             const list = choices.map(c => ({ value: c.value, label: c.label, ...(c.hint ? { hint: c.hint } : {}) }));
-            const picked = choices.length >= AUTOCOMPLETE_FROM
-                ? await clack.autocomplete({ message, options: list, placeholder: "Type to filter", maxItems: AUTOCOMPLETE_FROM, ...common })
-                : await clack.select({ message, options: list, ...common });
-            return unwrap(picked);
+            const initial = selectOptions.initial !== undefined ? { initialValue: selectOptions.initial } : {};
+            // Clack reports Escape and Ctrl+C as the same cancel, so the key itself tells them apart.
+            let escaped = false;
+            const onKey = (_, key) => { escaped = key?.name === "escape"; };
+            if (selectOptions.back)
+                input.on("keypress", onKey);
+            const start = row;
+            let picked;
+            try {
+                picked = selectOptions.search || choices.length >= AUTOCOMPLETE_FROM
+                    ? await clack.autocomplete({ message, options: list, placeholder: "Type to filter", maxItems: AUTOCOMPLETE_FROM, filter: matchesWords, ...initial, ...common })
+                    : await clack.select({ message, options: list, ...initial, ...common });
+            }
+            finally {
+                input.off("keypress", onKey);
+            }
+            if (selectOptions.back && escaped && clack.isCancel(picked)) {
+                // The answer above is erased too only when nothing was drawn between it and this step.
+                const previous = answered.at(-1)?.end === start ? answered.pop() : undefined;
+                const up = row - (previous?.start ?? start);
+                if (up > 0)
+                    drawn.write(`\u001b[${up}A\r\u001b[J`);
+                return BACK;
+            }
+            const value = unwrap(picked);
+            answered.push({ start, end: row });
+            return value;
         },
         async confirm(message, confirmOptions = {}) {
             if (!interactive)
@@ -117,6 +170,32 @@ export function createUi(options = {}) {
         },
     };
 }
+// "2086 week 5" should find "FIT2086 · Week 5": each typed word on its own, anywhere in
+// the label or hint. A number starts a run of digits, so "5" finds "Week 5" and "2086"
+// finds "FIT2086", but "5" does not find "Week 15".
+function matchesWords(search, option) {
+    const text = `${option.label ?? ""} ${option.hint ?? ""}`.toLowerCase();
+    return search.toLowerCase().split(/\s+/u).filter(Boolean).every(word => /^\d+$/u.test(word)
+        ? new RegExp(`(?<!\\d)${word}`, "u").test(text)
+        : text.includes(word));
+}
+// Everything else about the stream (columns, isTTY, resize events) is the real one.
+function trackRows(output, moved) {
+    const write = (chunk, ...rest) => {
+        for (const match of String(chunk).matchAll(/\u001b\[(\d*)([AB])|\n/gu)) {
+            moved(match[0] === "\n" ? 1 : (match[2] === "A" ? -1 : 1) * Number(match[1] || 1));
+        }
+        return output.write(chunk, ...rest);
+    };
+    return new Proxy(output, {
+        get(target, property) {
+            if (property === "write")
+                return write;
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
 /** Ctrl+C or Escape inside a prompt is the person's decision, reported with exit 130 like a signal. */
 function unwrap(value) {
     if (clack.isCancel(value))

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@bunizao/cli-kit",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Shared command-line contract for Bunizao CLI tools",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./intents": {
+      "types": "./dist/intents.d.ts",
+      "import": "./dist/intents.js"
     }
   },
   "files": [