@duyquangnvx/create-agent-cli 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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

package/dist/bin.js

@@ -7700,10 +7700,20 @@ function checkErrors(errors, label, table) {
 	if (unknown.length > 0) throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
 }
 function defineCommandFor() {
-	return declared;
+	return {
+		list: withEffect("read"),
+		read: withEffect("read"),
+		act: withEffect("act"),
+		serve: withEffect("serve"),
+		write: withEffect("write"),
+		destructive: withEffect("destructive")
+	};
 }
-function declared(command) {
-	return command;
+function withEffect(effect) {
+	return (command) => ({
+		...command,
+		effect
+	});
 }
 const defineCommand$1 = defineCommandFor();
 //#endregion
@@ -7724,9 +7734,9 @@ function cliErrorOf(code, init, options) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "b509cf2",
+		"sha": "0478338",
 		"dirty": false,
-		"builtAt": "2026-11-09T01:38:28.000Z"
+		"builtAt": "2026-11-09T05:16:34.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -8604,7 +8614,7 @@ function renderSetup(cli, install, setup) {
 }
 /** The built-in `setup`, which runs from any copy, such as npx's, so it never asks to be the global one. */
 function setupCommand(cli, install, launch) {
-	return defineCommand$1({
+	return defineCommand$1.write({
 		description: "install this CLI and its skill on this machine",
 		examples: [{
 			command: `${cli.name} setup`,
@@ -8613,7 +8623,6 @@ function setupCommand(cli, install, launch) {
 			command: `${cli.name} setup --dry-run`,
 			note: "show what it would change"
 		}],
-		effect: "write",
 		errors: [
 			NOT_GLOBAL_INSTALL,
 			NOT_ON_PATH,
@@ -8705,7 +8714,7 @@ function interruptedAfterInstall(plan) {
 }
 /** The built-in `update`, for a CLI installed globally with npm. */
 function updateCommand(cli, install, launch) {
-	return defineCommand$1({
+	return defineCommand$1.write({
 		description: "install the latest version of this CLI from its registry",
 		examples: [{
 			command: `${cli.name} update`,
@@ -8714,7 +8723,6 @@ function updateCommand(cli, install, launch) {
 			command: `${cli.name} update --dry-run`,
 			note: "show the version it would install"
 		}],
-		effect: "write",
 		errors: [NOT_GLOBAL_INSTALL, ...NPM_ERRORS],
 		output: updateSchema,
 		plan: async (_input, ctx) => {
@@ -9077,7 +9085,7 @@ function renderInstalled(cli, data) {
 }
 /** The built-in `skill install`, for a CLI whose skill ships in its package. */
 function skillInstallCommand(cli, folder, agents) {
-	return defineCommand$1({
+	return defineCommand$1.write({
 		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its Agents section",
 		examples: [{
 			command: `${cli.name} skill install`,
@@ -9086,7 +9094,6 @@ function skillInstallCommand(cli, folder, agents) {
 			command: `${cli.name} skill install --dry-run`,
 			note: "show what it would change"
 		}],
-		effect: "write",
 		output: installSchema,
 		plan: (_input, ctx) => planOf(cli, folder, agents, ctx),
 		apply: async (plan, ctx) => {
@@ -9428,7 +9435,7 @@ function checkedRows(error, problems, table) {
 }
 /** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
 function doctorCommand(cli, launch) {
-	const doctor = defineCommand$1({
+	const doctor = defineCommand$1.read({
 		description: "check the setup and say what fixes each problem",
 		examples: [{
 			command: `${cli.name} doctor`,
@@ -9437,7 +9444,6 @@ function doctorCommand(cli, launch) {
 			command: `${cli.name} doctor --json`,
 			note: "get the rows and fixes as data"
 		}],
-		effect: "read",
 		output: reportSchema,
 		run: async (_input, ctx) => {
 			const rowsScope = {
@@ -9634,7 +9640,7 @@ function checkDocs({ name, docs }) {
 	if (docs === void 0) return;
 	if (!(docs !== "" && !isAbsolute(docs) && !normalize(docs).startsWith(".."))) throw new Error(`${name} declares docs ${JSON.stringify(docs)}: name a folder inside its package, relative to the package root`);
 }
-function checkCli(cli) {
+function checkDeclared(cli) {
 	const table = errorTableOf(cli);
 	checkDocs(cli);
 	if (cli.commands === void 0) {
@@ -9707,16 +9713,17 @@ function resolved(cli) {
 }
 /**
 * Takes the CLI's ports factory, Project file and Error table once; the `defineCommand`,
-* `defineCli` and `cliError` it returns are typed by them.
+* `defineDoctorCheck`, `defineCli` and `cliError` it returns are typed by them.
 */
 function agentCli(values = {}) {
 	checkOwnCodes(errorTableOf(values));
 	return {
 		defineCommand: defineCommandFor(),
-		defineCli: (cli) => checkCli({
+		defineCli: (cli) => checkDeclared({
 			...resolved(cli),
 			...values
 		}),
+		defineDoctorCheck: (row) => row,
 		cliError: cliErrorOf
 	};
 }
@@ -11744,7 +11751,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.28.0",
+	version: "0.29.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },
@@ -12031,13 +12038,12 @@ async function ensureFree(path) {
 //#region src/bin.ts
 await runProcess(defineCli({
 	manifest: package_default,
-	command: defineCommand({
+	command: defineCommand.write({
 		description: "Create a new Agent CLI project in ./<name>",
 		examples: [{
 			command: "create-agent-cli weather --description \"Weather forecasts\"",
 			note: "create ./weather, install dependencies and make the first commit"
 		}],
-		effect: "write",
 		errors: ["STEP_FAILED"],
 		args: object({ name: string().regex(PACKAGE_NAME, "must be a lowercase npm package name, such as weather or @me/weather").describe("package name; its unscoped part names the bin and the directory") }),
 		options: object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.28.0",
+    "@duyquangnvx/agent-cli": "0.29.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/template/biome.json

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

package/template/package.json

@@ -28,9 +28,9 @@
     "release": "node scripts/release.ts"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
+    "@biomejs/biome": "2.6.2",
     "@duyquangnvx/agent-cli": "{{runtimeVersion}}",
-    "@duyquangnvx/harness": "0.3.1",
+    "@duyquangnvx/harness": "0.5.2",
     "@duyquangnvx/release": "0.9.0",
     "@types/node": "^22.19.0",
     "tsdown": "0.23.0",

package/template/src/cli.ts

@@ -9,7 +9,7 @@ const { defineCli, defineCommand } = agentCli({ errors, ports });
 const FREE_LANGUAGE = "en";
 const PRICE_PER_CARD = "$0.01";
 
-const greet = defineCommand({
+const greet = defineCommand.read({
   description: "Greet someone by name",
   examples: [
     {
@@ -21,14 +21,13 @@ const greet = defineCommand({
       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}!` }),
 });
 
-const card = defineCommand({
+const card = defineCommand.write({
   description: "Write a greeting card to <name>.txt",
   help:
     `A card in English is free; one in another language costs ${PRICE_PER_CARD} and needs --yes. ` +
@@ -47,7 +46,6 @@ const card = defineCommand({
       note: "sign the card from Ben and Cy",
     },
   ],
-  effect: "write",
   errors: ["LANGUAGE_UNSUPPORTED"],
   args: z.object({
     name: z

package/template/test/cli.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { type Files, runCli } from "@duyquangnvx/agent-cli";
-import { checkExamples } from "@duyquangnvx/agent-cli/testing";
+import { checkCli } from "@duyquangnvx/agent-cli/testing";
 import { describe, expect, test } from "vitest";
 import manifest from "../package.json" with { type: "json" };
 import { cli } from "../src/cli.ts";
@@ -74,8 +74,8 @@ function run(
   return runCli(cli, argv, { cwd: CWD, files, ports: { greetings }, stdin });
 }
 
-test("every example parses, names a Command and passes its schemas", async () => {
-  await checkExamples(cli);
+test("every example runs, every Command help shows has one, and every arg and option is described", async () => {
+  await checkCli(cli);
 });
 
 describe("greet", () => {