@duyquangnvx/create-agent-cli 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.29.0 (2026-11-09)
+
+### Added
+
+- `agentCli` returns `defineDoctorCheck`, which types a `doctor` row's `ctx` by the CLI's ports and Project file and its `errors` by the Error table, so a row needs no `DoctorCheck<Ports, Settings>` annotation and a code the table lacks is a type error.
+
+### Changed
+
+- **Breaking:** `defineCommand`, as `agentCli` returns it, is one method per Effect: `defineCommand.read`, `.act`, `.write`, `.destructive`, `.serve`, and `.list` for a List Command. A Command no longer declares `effect`, which the method sets, and `defineCommand.read` no longer takes `rows`. Each method has one signature, so a type error names the property at fault, such as a `run` returning a string where `output` has a number, rather than an Effect. The scaffolded template uses the methods.
+- **Breaking:** `checkExamples` from `@duyquangnvx/agent-cli/testing` is `checkCli`, since it checks more than examples; the scaffolded template's test calls it.
+- **Breaking:** `checkCli` also fails on a Command help shows that has no example, and on an arg or option without `.describe()`, so a CLI's test that passed `checkExamples` may fail until it adds them.
+- `ctx.secret` with a name the Command does not declare is a type error that names the declared Secrets, or reads `"the Command declares no secrets"` when it declares none, rather than one about `never`.
+- The scaffolded template pins `@biomejs/biome` 2.6.2 and `@duyquangnvx/harness` 0.5.2, the versions the Runtime itself is checked with.
+
+### Upgrade from v0.28.0
+
+- Call `checkCli` where the CLI's tests called `checkExamples`, then give each Command and field it names an example or a `.describe()`.
+- Declare each Command with the method of its Effect and delete its `effect`: `defineCommand({ effect: "write", … })` becomes `defineCommand.write({ … })`, and a read Command that declares `rows` becomes `defineCommand.list({ … })`.
+
+## v0.28.0 (2026-11-09)
+
+### Added
+
+- `ctx.platform`, also on `PortsBase` and the Side task's run, is the platform the run is on: `process.platform`, or `runCli`'s `platform` in a test, so a Command's own Windows branch runs on any OS.
+
+### Changed
+
+- **Breaking:** `Files` gains a required `realPath(path)`, the path with every symlink resolved or `undefined` when nothing is there, and `FileStat` a required `folder`, whether the path is a folder. A hand-written `Files`, such as a test's fake, fails to compile until it has both.
+- `runCli`'s `platform` option replaces `process.platform` wherever the Runtime reads it, not only in hint wording: a declared tool is looked for with `PATHEXT` under `"win32"`, and the Built-in Commands pick npm's `npm.cmd`, global bin folder and `node_modules` folder by it, so a test runs the Windows branches on any OS.
+- `skill install` fails as a bug (exit 70) when the package lacks its own `SKILL.md`, rather than emptying the project's copy.
+- **Breaking:** a Runtime code only some Commands reach (`NOT_GLOBAL_INSTALL`, `NOT_ON_PATH`, `REGISTRY_UNREACHABLE`, `REGISTRY_AUTH`, `INSTALL_FAILED`, `NPM_FAILED`, `NO_LATEST`, `DOCTOR_PROBLEMS`) goes in the `errors` of each Command that throws it, the Built-in Commands included, as a code of the Error table does; a run ending in one its Command does not declare fails as a bug (exit 70). A code any Command can meet, such as `NOT_FOUND`, still needs no declaration. `--help --json` lists each Built-in Command's `errors` with their classes.
+- **Breaking:** a `DoctorCheck` lists in `errors` the codes of the Error table, and the Runtime codes only some Commands reach, that it fails with, thrown or as its finding's `code`; a row that is not advisory failing with one it does not declare fails `doctor` as a bug (exit 70), and `defineCli` throws on one the table lacks. `doctor`'s `errors` in `--help --json` are `DOCTOR_PROBLEMS` and the codes of every row that is not advisory, rather than the whole Error table.
+- A run failing before its Command starts, at the operator check, parsing its input or reading the Project file, reports `INTERRUPTED` (exit 130 or 143) once it was interrupted, and `DEADLINE_EXCEEDED` once the run deadline ran out, as a failure of the Command itself does, rather than the error the gate threw.
+- The exit codes `--help` lists come from the codes the CLI's Commands declare, the Built-in Commands included, and its Error table: exit 3 shows exactly when one of them has class `source`.
+
+### Fixed
+
+- Under `runCli`, a Next step must run as given, as an example must: one that does not pass its Command's schemas, such as one missing a required option or holding `<id>` for a number, fails the run as a bug (exit 70) naming it and why, with the reason `checkExamples` gives for the same line. It used to pass when it only routed to a Command without unknown options.
+- The Built-in Commands read through `ctx.files`, so a Skill copy, `AGENTS.md` or `package.json` that `setup`, `update` or `skill install` may not read fails with `PERMISSION_DENIED` (exit 2) and its hint, as a write there does, rather than with `INTERNAL` (exit 70); `doctor` reports it in the row as `PERMISSION_DENIED` rather than as a bug.
+
+### Upgrade from v0.27.0
+
+- Give each hand-written `Files` a `realPath` and each `FileStat` it returns a `folder`, as the template's `test/cli.test.ts` does.
+- Add to a Command's `errors` each Runtime code only some Commands reach that it throws, such as `NO_LATEST`.
+- Add to each `doctor` row's `errors` each code of the Error table it throws or returns, its ports' and helpers' included, such as a store row's `CORRUPT_DATA`.
+
 ## v0.27.0 (2026-11-08)
 
 ### Added