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

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duyquangnvx/create-agent-cli` (the Scaffolder), which are released together at one version, 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: an export, a Cli or Command field, a built-in Command, a flag, a `--json` field, an exit code, the scaffolded template or the skill. A release turns `## Unreleased` into `## vX.Y.Z (YYYY-MM-DD)`.
+
+## Unreleased
+
+## v0.2.0 (2026-10-19)
+
+### Changed
+
+- **Breaking:** a List Command is declared by its row schema alone: a read Command sets `rows: rowSchema` in place of `output`, and the Runtime adds `--limit`, `--cursor` and `--fields`, passes `limit` and `cursor` to `run` and gives help JSON the page of rows as its output schema. A described or otherwise wrapped row schema keeps `--fields`, and a write or destructive Command with `rows` fails type checking. The exports `pageOf` and `pageOptions` are removed; the agent-cli skill and the scaffolded template use `rows`.
+- **Breaking:** help and `--help --json` list `--limit`, `--cursor` and `--fields` under Standard flags instead of among the Command's options, so help JSON's `options` no longer has `fields`, `limit` or `cursor`. Each entry of help JSON's `standardFlags` carries the JSON Schema of the flag's value as `schema`, such as `--limit`'s positive integer with default 20.
+- **Breaking:** `defineCommand` throws, and type checking fails, when a Command declares an arg or option named like any Standard flag, whether or not that Command gets the flag: `json`, `help`, `h`, `version`, `dry-run` (key `dryRun`), `confirm`, `limit`, `cursor` or `fields`.
+
+### Fixed
+
+- `--help` or `-h` after `--` is an argument, as every other word after `--` is, instead of showing help.
+
+## v0.1.0 (2026-10-18)
+
+### Added
+
+- The Runtime, `@duyquangnvx/agent-cli`: `defineCli` and `defineCommand` declare Commands with Zod arguments and options and a read, write or destructive Effect, and the Runtime owns parsing, layered help, `--json` output, errors with codes and hints, and exit codes 0, 1 and 2. Write and destructive Commands get `--dry-run` from their Plan, destructive ones a confirmation, and `pageOptions`, `pageOf` and `paginate` page a list. `runCli` runs a CLI in-process for tests; `runProcess` runs it as a bin, which exits once its output is written.
+- The Scaffolder, `@duyquangnvx/create-agent-cli`: `npm create @duyquangnvx/agent-cli <name>` creates a repo for a new Agent CLI with one example Command, its test, a skeleton skill, the gate scripts and a first commit.
+- Every multi-Command CLI has a built-in `doctor`: one row per check (`node`, `install`, `registry`, `skill`, then the CLI's own `doctor` rows), each under its own 10 s deadline, followed by the commands that fix each problem. It exits 1 with `DOCTOR_PROBLEMS` when a row is a problem; `--json` returns the rows as data.
+- Every multi-Command CLI has a built-in `update`, which installs the latest version from the CLI's registry with `npm install --global`, prints the upgrade notes from the new `CHANGELOG.md` for each version it passed, and says to update the skill. `--dry-run` shows the version it would install. Ctrl-C never stops npm halfway: once the install has started it finishes, and `update` fails with `INTERRUPTED` saying the new version is installed. It fails with `NOT_GLOBAL_INSTALL`, `REGISTRY_UNREACHABLE`, `REGISTRY_AUTH`, `NO_LATEST` or `INSTALL_FAILED`.
+- A Cli declares `install` (a global npm install of its package from its registry), `engines` and `doctor` rows, which `doctor` and `update` read.
+- A Command whose `output` is a `pageOf(row)` schema accepts `--fields`, which keeps only the named columns in both text and `--json` output; an unknown name is a usage error listing the valid ones.
+- `--help --json` at any level returns the Commands, arguments, options, Effects and examples as data, with each Command's output JSON Schema from its `output`.
+- Ctrl-C or SIGTERM aborts the Command's `ctx.signal` and the run fails with `INTERRUPTED`; a second signal exits at once with 130 or 143. `ctx.deadline(ms)` returns a signal that aborts with `DEADLINE_EXCEEDED`, `ctx.runToEnd(work)` marks a step the process finishes before it exits, and `runCli` takes a `signal` to cancel a run in-process.
+- A Cli with `build` prints `--version` as `X.Y.Z (sha)`, or `X.Y.Z (sha+dirty)` for a build from an unclean tree.
+- A scaffolded CLI bundles the Runtime and zod with tsdown, which stamps its version and commit into `--version`; both are devDependencies, so its own version alone decides its behaviour.
+- A scaffolded CLI declares a global install from npmjs and releases with `@duyquangnvx/release`, which stamps its skill and checks its `--version` before publishing.
+- The agent-cli skill, which teaches a Coding agent to build an Agent CLI on the Runtime: `npx skills add` installs it from this repo's `release` branch, and it names the Runtime version it describes.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @duyquangnvx/create-agent-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Creates a new Agent CLI repository already wired to [`@duyquangnvx/agent-cli`](https://www.npmjs.com/package/@duyquangnvx/agent-cli):
+
+```sh
+pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does"
+```
+
+The new repository has one example Command and its test, a bundled build that stamps the commit into `--version`, CI, a release script, a CHANGELOG, an `AGENTS.md` and a skeleton skill for the new CLI. Pass `--dry-run` to see what it would write.
+
+See the [repository](https://github.com/duyquangnvx/cli-for-agent) for an overview and the [agent-cli skill](https://github.com/duyquangnvx/cli-for-agent/blob/release/skills/agent-cli/SKILL.md) for how to build on it.