@duyquangnvx/create-agent-cli 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## 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