@duyquangnvx/create-agent-cli 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.20.0 (2026-10-28)
+
+### Changed
+
+- **Breaking:** the hints of `OUTPUT_EXISTS` and `ALREADY_EXISTS` read `once the user agrees to replace it, run the Next step` (`them` for several, and `remove` for `skill install` removing an edited file), `NOT_CONFIRMED`'s reads `once the user approves the cost, run the Next step`, and those of `CONFIRMATION_REQUIRED` and `CONFIRMATION_MISMATCH` read `once the user confirms the target, run the Next step`, so an agent asks before adding `--force`, `--yes` or `--confirm` without a skill telling it to. The docs' example `bundle` gives `BUNDLE_EXISTS` the same kind of hint.
+- **Breaking:** the scaffolded skill's Recovering from errors section tells the agent to do what the hint says, and keeps a row only for `LANGUAGE_UNSUPPORTED`, which now asks the user whether an English card will do before running the Next step. The rows for `OUTPUT_EXISTS`, `NOT_CONFIRMED` and every exit code are gone, since the hints and `--help` say the same.
+
+### Fixed
+
+- `--force` in help reads `replace a file the run writes that already exists; --dry-run lists every file it writes`, since `--dry-run` lists the files a run writes, not which of them exist.
+
 ## v0.19.0 (2026-10-28)
 
 ### Added

package/dist/bin.js

@@ -6471,7 +6471,7 @@ const YES_FLAG = standardFlag("--yes", {
 	schema: boolean()
 });
 const FORCE_FLAG = standardFlag("--force", {
-	description: "replace the files the run writes when they exist; --dry-run lists them",
+	description: "replace a file the run writes that already exists; --dry-run lists every file it writes",
 	takes: "nothing",
 	schema: boolean()
 });
@@ -6764,9 +6764,9 @@ function toolRows(tools, commands) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "fb29229",
+		"sha": "330940a",
 		"dirty": false,
-		"builtAt": "2026-10-28T10:00:56.000Z"
+		"builtAt": "2026-10-28T15:25:01.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -8022,7 +8022,7 @@ async function checkOutputs({ rerun, commandLine, force, files }, outputs) {
 	throw new CliError({
 		code: OUTPUT_EXISTS,
 		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
-		hint: `to replace ${them}, run the Next step`,
+		hint: `once the user agrees to replace ${them}, run the Next step`,
 		next: [rerun({ add: [FORCE_FLAG.flag] })]
 	});
 }
@@ -8044,7 +8044,7 @@ function outputsGuard(files, cwd) {
 			throw new CliError({
 				code: ALREADY_EXISTS,
 				message: error.message,
-				hint: "to replace it, run the Next step",
+				hint: "once the user agrees to replace it, run the Next step",
 				next: [forceStep]
 			}, { cause: error });
 		}
@@ -8170,7 +8170,7 @@ function editedRemovals(plan, ctx) {
 	return new CliError({
 		code: OUTPUT_EXISTS,
 		message: `skill install would remove ${plan.remove.map((file) => join(plan.copy, file)).join(", ")}`,
-		hint: `to remove ${them}, run the Next step`,
+		hint: `once the user agrees to remove ${them}, run the Next step`,
 		next: [ctx.rerun({ add: [FORCE_FLAG.flag] })]
 	});
 }
@@ -10706,7 +10706,7 @@ const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
 function checkConfirmation({ rerun, commandLine, given }, expected) {
 	if (given === expected) return;
 	const advice = {
-		hint: "to confirm, run the Next step",
+		hint: "once the user confirms the target, run the Next step",
 		next: [rerun({
 			remove: [CONFIRM_FLAG.flag],
 			add: [CONFIRM_FLAG.flag, expected]
@@ -10732,7 +10732,7 @@ function checkCost({ rerun, commandLine, yes }, cost) {
 	throw new CliError({
 		code: NOT_CONFIRMED,
 		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-		hint: "to approve the cost, run the Next step",
+		hint: "once the user approves the cost, run the Next step",
 		next: [rerun({ add: [YES_FLAG.flag] })]
 	});
 }
@@ -11290,7 +11290,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.19.0",
+	version: "0.20.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.19.0",
+  "version": "0.20.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.19.0",
+    "@duyquangnvx/agent-cli": "0.20.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/template/skills/{{binName}}/SKILL.md

@@ -47,18 +47,10 @@ Pass `--json` whenever you parse the output: stdout then holds only the data. A
 
 ## Recovering from errors
 
-Errors go to stderr and end with a `hint:` line, then a `run:` line for each command to run next, in order. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` or `{"notice":"..."}` while it runs, then `{ errors: [{ code, message, hint, next }] }` as the last line, `next` holding those commands when there are any. Match the first row that fits:
+Errors go to stderr and end with a `hint:` line, then a `run:` line for each command to run next, in order. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` or `{"notice":"..."}` while it runs, then `{ errors: [{ code, message, hint, next }] }` as the last line, `next` holding those commands when there are any. Do what the hint says, except for a code below:
 
-| Code or exit | What to do |
+| Code | What to do |
 |---|---|
-| `OUTPUT_EXISTS` | The run would overwrite a file. Ask the user before adding `--force`. |
-| `NOT_CONFIRMED` | The run costs money. Tell the user the cost from the message; add `--yes` only once they approve it. |
-| `LANGUAGE_UNSUPPORTED` | The greetings service lacks that language. Run the Next step's English card, or ask the user for another language. |
-| exit 1 | You called it wrong. Fix what the message and hint point at, then run it again. |
-| exit 2 | Something on this machine needs a person. Tell the user what the hint says and ask them to fix it. |
-| exit 3 | The source it talks to is broken. Tell the user; running it again won't help. |
-| exit 75 | Nobody needs to act. Wait, then run it again, as the hint says. |
-| exit 70, `INTERNAL` | A bug in {{binName}}. Run it once more with `{{debugVariable}}=1` for the stack trace, then give the user stderr verbatim. |
-| exit 130 or 143 | It was interrupted. Run it again only if the user still wants it. |
-
-<!-- Add a row above the exit rows for each CliError code {{binName}} throws, saying what to do about it. -->
+| `LANGUAGE_UNSUPPORTED` | The user asked for that language. Ask whether an English card will do before running the Next step. |
+
+<!-- Add a row for each code {{binName}} throws whose right move goes beyond its hint. A guardrail on a flag goes in the workflow step that passes it instead. -->