@duyquangnvx/create-agent-cli 0.0.0-stage → 0.2.1

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "create-agent-cli": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@duyquangnvx/agent-cli": "0.2.1",
+    "tsdown": "0.23.0",
+    "zod": "4.6.7"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }

package/template/AGENTS.md

@@ -0,0 +1,30 @@
+# {{packageName}}
+
+{{description}} An Agent CLI: its main callers are LLM coding agents running it through a shell, so it never prompts, keeps output short, and tells the caller what to run next when something fails. It is built on [`@duyquangnvx/agent-cli`](https://www.npmjs.com/package/@duyquangnvx/agent-cli), the Runtime, which owns parsing, help, output, errors and exit codes.
+
+## Project status
+
+Greenfield with no deployments or users: change code directly. Breaking changes are welcome; no feature flags, shims, or backward compatibility.
+
+## Commands
+
+| | |
+|---|---|
+| `pnpm test` | vitest |
+| `pnpm typecheck` | tsc |
+| `pnpm lint` | Biome; `pnpm exec biome check --write` fixes formatting |
+| `pnpm build` | bundles `dist/`, the `{{binName}}` bin, with the Runtime and the commit it is built from |
+| `pnpm release` | publishes to npm through `@duyquangnvx/release`; run `pnpm release --dry-run` to check it |
+
+## Coding standards
+
+- Every Command is declared in `src/cli.ts` with `defineCommand`: a description, realistic examples, Zod schemas for args and options (with `.describe()` on each field), and its Effect.
+- A Command never prints. A `read` Command returns data from `run` and turns it into short text in `render`. A `write` or `destructive` Command returns a Plan from `plan`, with no side effects, and performs it in `apply`; the Runtime adds `--dry-run`, and `--confirm` for a destructive one.
+- A failure the caller can act on is a `CliError` with a `code`, a `message`, a `hint` naming the command to run next, and `retryable`. Anything else becomes an internal error, whose stack trace `{{debugVariable}}=1` shows.
+- A Command that lists many items declares its row schema as `rows` and returns `paginate(items, { limit, cursor })`; the Runtime adds `--limit`, `--cursor` and `--fields`.
+- Tests drive the CLI through `runCli` and assert only stdout, stderr and the exit code, as `test/cli.test.ts` does.
+- A change a user of `{{binName}}` would notice gets an entry under `## Unreleased` in `CHANGELOG.md`, in the format its opening paragraph states.
+
+## Agent skills
+
+`skills/{{binName}}/SKILL.md` is the agent skill: when to use `{{binName}}`, its workflows and how to recover from its errors. Update it with any change to those, and leave flag details to `--help`.

package/template/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+What changed in each release of `{{packageName}}`, newest first, in the format of [Keep a Changelog 2.0](https://keepachangelog.com/en/2.0.0/). Each change lands under `## Unreleased` as it merges, grouped under `### Added`, `### Changed`, `### Fixed` or `### Removed`. A breaking change starts with `**Breaking:**` and names what breaks: a Command, a flag, a `--json` field, an exit code or the skill. A release turns `## Unreleased` into `## vX.Y.Z (YYYY-MM-DD)`.
+
+## Unreleased

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/README.md

@@ -0,0 +1,14 @@
+# {{packageName}}
+
+{{description}}
+
+Built on [`@duyquangnvx/agent-cli`](https://www.npmjs.com/package/@duyquangnvx/agent-cli): declare Commands in `src/cli.ts` and test them through `runCli`, as `test/cli.test.ts` does.
+
+```sh
+pnpm test       # vitest
+pnpm typecheck  # tsc
+pnpm lint       # biome
+pnpm build      # bundles dist/, the {{binName}} bin, stamped with the commit
+```
+
+Set `{{debugVariable}}=1` to see the stack trace of an internal error.

package/template/_gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/template/_github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+      - run: pnpm lint
+      - run: pnpm test

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.tsbuildinfo

package/template/biome.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
+  "extends": ["@duyquangnvx/harness/biome"]
+}

package/template/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.0.0",
+  "description": "{{description}}",
+  "type": "module",
+  "packageManager": "pnpm@12.9.1",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "bin": {
+    "{{binName}}": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc",
+    "lint": "biome ci",
+    "test": "vitest run",
+    "release": "node scripts/release.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@duyquangnvx/agent-cli": "{{runtimeVersion}}",
+    "@duyquangnvx/harness": "0.3.1",
+    "@duyquangnvx/release": "0.2.0",
+    "@types/node": "^22.19.0",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5",
+    "zod": "4.6.7"
+  }
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+# A fresh project pins the Runtime release it was created with, which can be younger than
+# pnpm's minimum release age.
+minimumReleaseAgeExclude:
+  - "@duyquangnvx/agent-cli"

package/template/scripts/release.ts

@@ -0,0 +1,6 @@
+import { release } from "@duyquangnvx/release";
+
+process.exitCode = release({
+  skill: "skills/{{binName}}/SKILL.md",
+  smoke: { cli: true },
+});

package/template/skills/{{binName}}/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: {{binName}}
+description: >-
+  {{description}} Use when a task needs what `{{binName}}` does, or when a `{{binName}}` command fails.
+allowed-tools: Bash({{binName}} --version)
+metadata:
+  version: "0.0.0"
+---
+
+<!-- A skeleton to rewrite around {{binName}}'s real Commands. Leave flags out: `--help` is generated from the code and stays in sync with it, this file does not. -->
+
+# {{binName}}
+
+`{{binName}} --help` lists the Commands, and `{{binName}} <command> --help` shows a Command's examples, args, options and the flags the Runtime adds. This file covers the work around them.
+
+## Installed CLI
+
+!`{{binName}} --version 2>&1 || echo "{{binName}}: not installed"`
+
+The line above should show 0.0.0, the version this skill describes. If it says {{binName}} is not installed or shows another version, tell the user before going on.
+
+## When to use
+
+<!-- The tasks {{binName}} is for, and the nearby tasks it is not for. -->
+
+- Greeting someone by name.
+
+## Workflows
+
+<!-- Each main task as steps naming the Commands it runs, in order. Move a long workflow to a file under references/ and link it. -->
+
+### Greet someone
+
+1. Run `{{binName}} greet <name> --json`.
+2. Read `greeting` from the JSON on stdout.
+
+Pass `--json` whenever you parse the output: stdout then holds only the data. A Command that changes something takes `--dry-run`, which prints its Plan and changes nothing: run it first when unsure. A destructive Command also needs `--confirm=<target>`, and its error's hint gives the exact command.
+
+## Recovering from errors
+
+Errors go to stderr and end with a `hint:` line naming the next step. Under `--json` they are one object with `code`, `message`, `hint` and `retryable`. Match the first row that fits:
+
+| Code or exit | What to do |
+|---|---|
+| exit 2 | You called it wrong. Fix the input the message names, as the hint says, and run it again. |
+| `INTERNAL` | A bug in {{binName}}. Run it once more with `{{debugVariable}}=1` for the stack trace, then give the user stderr verbatim. |
+| exit 1, `retryable: true` | Run it again once. |
+| exit 1 | Fix what the message and hint point at, then run it again. Ask the user when the fix is their choice. |
+
+<!-- Add a row for each CliError code {{binName}} throws, saying what to do about it. -->

package/template/src/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runProcess } from "@duyquangnvx/agent-cli";
+import { cli } from "./cli.js";
+
+await runProcess(cli);

package/template/src/build.ts

@@ -0,0 +1,6 @@
+import type { Cli } from "@duyquangnvx/agent-cli";
+
+// tsdown.config.ts stamps this into the bundle; the source run unbundled, as in tests, has none.
+declare const __BUILD__: Cli["build"];
+
+export const build: Cli["build"] = typeof __BUILD__ === "undefined" ? undefined : __BUILD__;

package/template/src/cli.ts

@@ -0,0 +1,32 @@
+import { defineCli, defineCommand } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+import manifest from "../package.json" with { type: "json" };
+import { build } from "./build.js";
+
+const greet = defineCommand({
+  name: "greet",
+  description: "Greet someone by name",
+  examples: [
+    { command: "{{binName}} greet Ana", note: "say hello to Ana" },
+    { command: "{{binName}} greet Ana --json", note: "get the greeting as JSON" },
+  ],
+  effect: "read",
+  args: z.object({
+    name: z.string().min(1).describe("who to greet"),
+  }),
+  run: ({ name }) => ({ greeting: `Hello, ${name}!` }),
+  render: ({ greeting }) => greeting,
+});
+
+export const cli = defineCli({
+  name: "{{binName}}",
+  version: manifest.version,
+  build,
+  install: {
+    mode: "global",
+    package: manifest.name,
+    registry: manifest.publishConfig.registry,
+  },
+  engines: manifest.engines,
+  commands: { greet },
+});

package/template/test/cli.test.ts

@@ -0,0 +1,27 @@
+import { runCli } from "@duyquangnvx/agent-cli";
+import { describe, expect, test } from "vitest";
+import { cli } from "../src/cli.ts";
+
+const options = { env: {}, cwd: "." };
+
+describe("greet", () => {
+  test("prints the greeting", async () => {
+    const result = await runCli(cli, ["greet", "Ana"], options);
+
+    expect(result).toEqual({ stdout: "Hello, Ana!\n", stderr: "", exitCode: 0 });
+  });
+
+  test("prints the data as JSON with --json", async () => {
+    const result = await runCli(cli, ["greet", "Ana", "--json"], options);
+
+    expect(JSON.parse(result.stdout)).toEqual({ greeting: "Hello, Ana!" });
+  });
+
+  test("a missing name is a usage error", async () => {
+    const result = await runCli(cli, ["greet"], options);
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toMatch(/<name>: required/);
+  });
+});

package/template/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "module": "nodenext",
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src", "test", "scripts", "tsdown.config.ts", "vitest.config.ts"]
+}

package/template/tsdown.config.ts

@@ -0,0 +1,30 @@
+import { execFileSync } from "node:child_process";
+import { defineConfig } from "tsdown";
+
+function git(args: readonly string[]): string {
+  try {
+    return execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    throw new Error("the build stamps the commit it is made from: commit to git first", {
+      cause: error,
+    });
+  }
+}
+
+const build = {
+  sha: git(["rev-parse", "--short=7", "HEAD"]),
+  dirty: git(["status", "--porcelain"]) !== "",
+};
+
+export default defineConfig({
+  entry: ["src/bin.ts"],
+  platform: "node",
+  format: "esm",
+  fixedExtension: false,
+  // The bin bundles the Runtime and zod, so only this CLI's own release changes its behaviour.
+  deps: { onlyBundle: false },
+  define: { __BUILD__: JSON.stringify(build) },
+});

package/template/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+  },
+});