@duyquangnvx/create-agent-cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.7.0 (2026-10-20)
+
+### Added
+
+- Every Runtime code is exported under its name: `OUTPUT_EXISTS`, `PROJECT_INVALID`, `INVALID_INPUT`, `UNKNOWN_OPTION`, `UNKNOWN_COMMAND`, `UNKNOWN_FIELD`, `CONFIRMATION_REQUIRED`, `CONFIRMATION_MISMATCH`, `NOT_CONFIRMED`, `TOOL_FAILED`, `TOOL_MISSING`, `DOCTOR_PROBLEMS`, `INTERNAL`, `NOT_GLOBAL_INSTALL`, `REGISTRY_UNREACHABLE`, `REGISTRY_AUTH`, `INSTALL_FAILED`, `NPM_FAILED` and `NO_LATEST`. The agent-cli skill says which of them a Command may throw, and asserts codes through them.
+- A CLI's `doctor` rows read the Project file as `ctx.project`, which was always `undefined` there. `doctor` reads the file once for all its rows; a row that reads `ctx.project` while the file is unusable is skipped, since the `project` row reports it. See `DoctorCheck.run`. The agent-cli skill's example adds a `tag` row that reads it.
+
+### Changed
+
+- **Breaking:** `doctor`'s `project` row carries the code of the failed read, so a Project file its schema rejects fails `doctor` with `PROJECT_INVALID` instead of `DOCTOR_PROBLEMS` (still exit 2), the code a Command fails with on the same file. The row's message adds the error's hint.
+
+## v0.6.0 (2026-10-20)
+
+### Changed
+
+- **Breaking:** `defineCli` requires `description`, one line that root help and root `--help --json` print; for a single-Command CLI it replaces the Command's own line at the root. The scaffolded template passes its package.json `description`, which `--description` sets.
+- **Breaking:** `Context` requires `timeout` and `PortsBase` requires `envFile` (see Added), so a `ctx` or `PortsBase` built by hand, such as a test's fake, stops type-checking until it has them.
+- **Breaking:** an `orStdin` arg read from a pipe that sends nothing for 30 s fails the run with the new code `STDIN_STALLED` (exit 1) instead of waiting forever; a terminal is never bounded. See the exports `STDIN_STALLED` and `STDIN_IDLE_MS`.
+- **Breaking:** text that opens with `-` and holds whitespace, such as `"- a red apple"`, given to a Command whose `orStdin` arg is left out, fails with `UNKNOWN_OPTION` instead of `INVALID_INPUT` (still exit 1), its hint naming the command line that sends the text through a heredoc.
+- **Breaking:** `--cursor` is an opaque string, and a List Command's `run` receives `cursor` as a string. `paginate` still pages a list held in memory and refuses a cursor it never gave as a usage error.
+- The agent-cli skill keeps in `SKILL.md` what every Command needs, ending on the list a finished Command meets, and moves long runs, ports, `doctor` rows and testing into `references/`. Its description now triggers on starting any CLI.
+- The agent-cli skill points at the Runtime's types for its API reference: the JSDoc on its exports, shipped in `dist/index.d.ts`, now carries the contracts the skill used to list (exit codes, defaults, what `--dry-run` shows), and the skill keeps only what a type cannot show.
+
+### Added
+
+- A new CLI's skill installs its CLI: the Scaffolder writes `references/setup.md` beside the skill, which walks the agent through installing, checking and updating the CLI, and the README gives the skill's install line, then the CLI's. The new CLI's test fails when those lines differ from what `doctor` gives. `--repository <url>` sets package.json `repository`, where the skill is installed from.
+- `ctx.timeout(ms)` bounds a call that Ctrl-C must not cut short, such as a billed call inside `ctx.runToEnd`; see `Context.timeout`. The agent-cli skill's remote-services reference uses it.
+- `defineCli({ sideTask })` runs a Side task, such as a usage count, beside each Command run, without changing its output or exit code; see `Cli.sideTask`, `SideTaskRun` and `SIDE_TASK_WAIT_MS`. The agent-cli skill's example counts its runs with one.
+- `PortsBase.envFile`, and so `ctx.envFile`: the `.env` path `ctx.secret` reads, for a missing-key hint or a `doctor` row to name.
+- `ctx.files.mkdir(path, { mode })` sets the mode of each folder it creates; see `MkdirOptions.mode`.
+- The hint of an `INTERNAL` error (exit 70) names package.json `bugs`, a URL or `{ url }`, as where to report it.
+- `page(items, next)` returns a page whose source pages itself, such as a remote API: `next` is the source's own cursor, which the Runtime puts in the page's `next` command line.
+- The agent-cli skill covers what the Runtime leaves to a CLI: remote services (classifying failures, polite retries, requests that start a job or bill, paid calls, SDK and LLM calls), shipping (install lines, release, the CLI's own skill, an `AGENTS.md` block), a daemon or store that outlives a run, and queues and progress in long runs.
+- The agent-cli skill teaches the agent-first rules the Runtime leaves to a CLI: data carries names beside ids and absolute paths, reads and changes sit under distinct leading words for permission rules, a write Command is safe to run again, long jobs split into a start and a `--wait` check, and a CLI is evaluated on real agent transcripts. Its example's `export` and `bundle` return absolute paths.
+
+### Fixed
+
+- `doctor`'s `skill` row installs a GitHub `owner/repo` shorthand `repository` from its `release` branch (`owner/repo#release`), as it does every other source, instead of from the default branch, which may describe what is still unreleased. It also reads npm's `github:owner/repo` and `gitlab:group/repo` shorthands, which gave no fix before.
+- **Breaking:** an `AggregateError` held inside another exits by the first Exit class among its leaves, each printed with its hint, instead of exit 70. An empty one is still reported as itself.
+- **Breaking:** a Project file that cannot be read fails with `PERMISSION_DENIED` (exit 2), and a folder in its place with `NOT_A_FILE` (exit 1), instead of exit 70; `doctor` reports either in its `project` row.
+- **Breaking:** once `ctx.deadline` fires, only an error that is not a `CliError` and holds the deadline's abort in its `cause` chain becomes `DEADLINE_EXCEEDED`, instead of every error that is not a `CliError`: a wrapper that drops the abort now exits 70, not 75, and a `CliError` keeps its own code. See `Context.deadline`. The agent-cli skill teaches keeping the abort as `cause`.
+- `doctor`'s `skill` row fixes a copy with no `metadata.version` with `npx -y skills add <source> --skill <name> -g` when the source is known, since `skills update` skips copies it did not install, and with `skills update` then that line when another copy is older than the CLI. Without a source it still suggests `skills update`.
+- `update`'s `next` gives the fix `doctor`'s `skill` row would, against the version it installed, instead of always `npx -y skills update <name>`: `skills add <source>` for a missing copy or one with no `metadata.version`, nothing for a copy already newer. With nothing to install, `next` fixes copies older than the latest release instead of staying empty, and the text output prints it.
+- `doctor`'s `skill` row gives no fix for a copy newer than the build, instead of `<cli> update`, which a CLI without `install` lacks; the `registry` row still says when the build is older than the latest release.
+
 ## v0.5.0 (2026-10-19)
 
 ### Added

package/README.md

@@ -3,9 +3,9 @@
 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"
+pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does" --repository https://github.com/<owner>/<name>
 ```
 
-The new repository has an Error table, a port, two example Commands (one writing a file at a cost) and their test, a bundled build that stamps the commit and build time 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.
+The new repository has an Error table, a port, two example Commands (one writing a file at a cost) and their test, a bundled build that stamps the commit and build time into `--version`, CI, a release script, a CHANGELOG, an `AGENTS.md`, and a skeleton skill for the new CLI whose setup reference installs, checks and updates it, so a user installs the skill first and lets their agent do the rest. `--repository` names where that skill is installed from. 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.