@duyquangnvx/create-agent-cli 0.15.1 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.17.0 (2026-10-27)
+
+### Added
+
+- A fifth Effect, `act`, for a Command that changes the state of a program already running, such as a page in a browser tab, rather than files or remote services. It is declared as a read Command is, with `run` and the new `ActCommand` type, and cannot declare a Plan or `rows`. Its help says so and that running it again may act again, its `--help --json` gives `"effect": "act"`, and of the Standard flags it gets only `--json`. The agent-cli skill says when to pick `act` over `read` and `write`.
+- The Scaffolder's `AGENTS.md` names the `act` and `serve` Effects beside `read`, `write` and `destructive`.
+
+### Upgrade from v0.16.0
+
+- Nothing to do.
+
+## v0.16.0 (2026-10-27)
+
+### Changed
+
+- **Breaking:** a Packaged skill's `AGENTS.md` block is the text the CLI declares as `skill: { packaged, agents }`, written verbatim between its markers; the Runtime no longer composes a sentence from `description` and the run-as. Without `agents`, `skill install` writes no block and names no `CLAUDE.md` hand edit, its `--json` `agentsMd` is `null`, and `doctor` has no `agents` row. A CLI relying on the old block declares `agents` to keep one, and the Scaffolder's `--dependency` template declares none.
+
 ## v0.15.1 (2026-10-27)
 
 ### Fixed

package/dist/bin.js

@@ -6429,6 +6429,7 @@ const FORCE_FLAG = standardFlag("--force", {
 });
 const EFFECT_FLAGS = {
 	read: [JSON_FLAG],
+	act: [JSON_FLAG],
 	write: [JSON_FLAG, DRY_RUN_FLAG],
 	destructive: [
 		JSON_FLAG,
@@ -7390,7 +7391,6 @@ function dependencyInstall(cli, install) {
 		runAs,
 		builtIns: () => ({}),
 		exitClasses: [],
-		agentsCaveat: `and only from a package that has \`${install.package}\` in its dependencies; from anywhere else npx reports the package missing`,
 		check: (launch) => checkOf$1(cli, install, runAs, launch)
 	};
 }
@@ -7492,12 +7492,6 @@ function hubSkill(cli, source) {
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/agents-md.js
-/** One paragraph telling every session that the CLI exists, how to run it and which skill to load. */
-function agentsBlock(cli, { runAs, agentsCaveat }) {
-	const what = cli.description.replace(/\.$/, "");
-	const run = `Run it as \`${runAs}\`${agentsCaveat === void 0 ? "" : `, ${agentsCaveat}`}`;
-	return `\`${cli.name}\`: ${what}. ${run}. Load the \`${cli.name}\` skill before using it.`;
-}
 function markersOf(name) {
 	return {
 		begin: `<!-- BEGIN:${name} -->`,
@@ -7505,33 +7499,32 @@ function markersOf(name) {
 	};
 }
 /** `text` with the CLI's block between its markers, appended when they are missing; nothing else changes. */
-function withBlock(cli, install, text) {
-	const { begin, end } = markersOf(cli.name);
-	const whole = `${begin}\n${agentsBlock(cli, install)}\n${end}`;
+function withBlock({ name, text: block }, text) {
+	const { begin, end } = markersOf(name);
+	const whole = `${begin}\n${block}\n${end}`;
 	const start = text.indexOf(begin);
 	const stop = start === -1 ? -1 : text.indexOf(end, start);
 	if (stop !== -1) return `${text.slice(0, start)}${whole}${text.slice(stop + end.length)}`;
 	if (text === "") return `${whole}\n`;
 	return `${text}${text.endsWith("\n") ? "" : "\n"}\n${whole}\n`;
 }
-async function agentsMdAt(cli, install, root) {
+async function agentsMdAt(agents, root) {
 	const path = join(root, "AGENTS.md");
 	const existing = await orMissing(readFile(path, "utf8"));
-	const block = agentsBlock(cli, install);
 	if (existing === void 0) return {
 		path,
-		block,
+		agents,
 		change: "create"
 	};
-	if (withBlock(cli, install, existing) === existing) return {
+	if (withBlock(agents, existing) === existing) return {
 		path,
-		block,
+		agents,
 		change: null
 	};
 	return {
 		path,
-		block,
-		change: existing.includes(markersOf(cli.name).begin) ? "rewrite" : "add"
+		agents,
+		change: existing.includes(markersOf(agents.name).begin) ? "rewrite" : "add"
 	};
 }
 async function handEditsAt(root) {
@@ -7540,25 +7533,26 @@ async function handEditsAt(root) {
 	if (text === void 0 || text.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md")) return [];
 	return [`add a line \`@AGENTS.md\` to ${claudeMd}, so Claude Code reads AGENTS.md`];
 }
-function agentsRow(cli, install) {
+function agentsRow(agents, install) {
+	const { name } = agents;
 	return {
 		name: "agents",
 		advisory: true,
 		run: async (ctx) => {
 			const root = await projectRootOf(ctx.cwd);
-			const { path, change } = await agentsMdAt(cli, install, root);
+			const { path, change } = await agentsMdAt(agents, root);
 			const fix = `${install.runAs} skill install`;
 			if (change === "rewrite") return {
 				state: "problem",
-				message: `${path} holds a ${cli.name} block other than the one ${fix} writes`,
+				message: `${path} holds a ${name} block other than the one ${fix} writes`,
 				fix
 			};
 			if (change !== null) return {
 				state: "problem",
-				message: `${path} holds no ${cli.name} block, so sessions in this repo do not know ${cli.name}`,
+				message: `${path} holds no ${name} block, so sessions in this repo do not know ${name}`,
 				fix
 			};
-			const holds = `${path} holds the ${cli.name} block`;
+			const holds = `${path} holds the ${name} block`;
 			const [edit] = await handEditsAt(root);
 			return edit === void 0 ? {
 				state: "ok",
@@ -7936,14 +7930,14 @@ const installSchema = object({
 	agentsMd: object({
 		path: string(),
 		changed: boolean()
-	}),
+	}).nullable(),
 	handEdits: array(string())
 });
 async function sameContent(left, right) {
 	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
 	return a.equals(b);
 }
-async function planOf(cli, folder, install, cwd, packageRoot) {
+async function planOf(cli, folder, agents, cwd, packageRoot) {
 	const source = join(packageRoot, folder);
 	const { root, copy } = await skillCopyOf(cli, cwd);
 	const [shipped, present] = await Promise.all([filesIn(source), filesIn(copy)]);
@@ -7955,8 +7949,8 @@ async function planOf(cli, folder, install, cwd, packageRoot) {
 		replace: shipped.filter((_file, index) => differs[index]),
 		remove: present.filter((file) => !shipped.includes(file)),
 		sameVersion: (await skillVersionsOf(source, copy)).same,
-		agentsMd: await agentsMdAt(cli, install, root),
-		handEdits: await handEditsAt(root)
+		agentsMd: agents === void 0 ? null : await agentsMdAt(agents, root),
+		handEdits: agents === void 0 ? [] : await handEditsAt(root)
 	};
 }
 const BLOCK_VERBS = {
@@ -7970,11 +7964,11 @@ function renderPlan(cli, plan) {
 		...plan.replace.map((file) => `  replace ${file}`),
 		...plan.remove.map((file) => `  remove ${file}`)
 	];
-	const { path, block, change } = plan.agentsMd;
+	const { agentsMd } = plan;
 	return [
 		files.length === 0 ? `the ${cli.name} skill at ${plan.copy} already matches the package` : `would copy the ${cli.name} skill to ${plan.copy}:`,
 		...files,
-		change === null ? `${path} already holds the ${cli.name} block` : `would ${BLOCK_VERBS[change]} ${path}:\n${block}`,
+		...agentsMd === null ? [] : [agentsMd.change === null ? `${agentsMd.path} already holds the ${cli.name} block` : `would ${BLOCK_VERBS[agentsMd.change]} ${agentsMd.path}:\n${agentsMd.agents.text}`],
 		...plan.handEdits.map((edit) => `by hand: ${edit}`)
 	].join("\n");
 }
@@ -7982,7 +7976,7 @@ function renderInstalled(cli, data) {
 	const { written, removed, agentsMd } = data;
 	return [
 		written.length + removed.length === 0 ? `the ${cli.name} skill at ${data.copy} already matches the package` : `copied the ${cli.name} skill to ${data.copy}: wrote ${written.length} files, removed ${removed.length}`,
-		agentsMd.changed ? `wrote the ${cli.name} block in ${agentsMd.path}` : `${agentsMd.path} already holds the ${cli.name} block`,
+		...agentsMd === null ? [] : [agentsMd.changed ? `wrote the ${cli.name} block in ${agentsMd.path}` : `${agentsMd.path} already holds the ${cli.name} block`],
 		...data.handEdits.map((edit) => `by hand: ${edit}`)
 	].join("\n");
 }
@@ -7995,11 +7989,11 @@ function editedRemovals(plan, ctx) {
 	});
 }
 /** The built-in `skill install`, for a CLI whose skill ships in its package. */
-function skillInstallCommand(cli, folder, install) {
+function skillInstallCommand(cli, folder, install, agents) {
 	const { runAs } = install;
 	return defineCommand$1({
 		name: "install",
-		description: "copy this CLI's skill into the project and write its AGENTS.md block",
+		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its AGENTS.md block",
 		examples: [{
 			command: `${runAs} skill install`,
 			note: "install the skill this version ships"
@@ -8010,24 +8004,24 @@ function skillInstallCommand(cli, folder, install) {
 		effect: "write",
 		output: installSchema,
 		force: "replace or remove hand-edited files of a skill copy at the package's version",
-		plan: (_input, ctx) => planOf(cli, folder, install, ctx.cwd, ctx.packageRoot),
+		plan: (_input, ctx) => planOf(cli, folder, agents, ctx.cwd, ctx.packageRoot),
 		outputs: (plan) => plan.sameVersion ? [...plan.write, ...plan.replace].map((file) => join(plan.copy, file)) : [],
 		apply: async (plan, ctx) => {
 			if (plan.sameVersion && plan.remove.length > 0 && !ctx.force) throw editedRemovals(plan, ctx);
 			for (const file of [...plan.write, ...plan.replace]) await ctx.files.write(join(plan.copy, file), await readFile(join(plan.source, file)));
 			for (const file of plan.remove) await ctx.files.remove(join(plan.copy, file));
-			const { path, change } = plan.agentsMd;
-			if (change !== null) {
-				const existing = await orMissing(readFile(path, "utf8")) ?? "";
-				await ctx.files.write(path, withBlock(cli, install, existing));
+			const { agentsMd } = plan;
+			if (agentsMd !== null && agentsMd.change !== null) {
+				const existing = await orMissing(readFile(agentsMd.path, "utf8")) ?? "";
+				await ctx.files.write(agentsMd.path, withBlock(agentsMd.agents, existing));
 			}
 			return {
 				copy: plan.copy,
 				written: [...plan.write, ...plan.replace].sort(),
 				removed: [...plan.remove],
-				agentsMd: {
-					path,
-					changed: change !== null
+				agentsMd: agentsMd === null ? null : {
+					path: agentsMd.path,
+					changed: agentsMd.change !== null
 				},
 				handEdits: [...plan.handEdits]
 			};
@@ -8102,16 +8096,20 @@ async function notice(cli, folder, install, { builtIn, bin }, ctx) {
 	if (finding.state !== "problem") return;
 	ctx.notice(finding.fix === void 0 ? finding.message : `${finding.message}; run \`${finding.fix}\``);
 }
-/** A skill shipped in the package at `folder`, which `skill install` copies to the project root. */
-function packagedSkill(cli, folder, install) {
+/** A skill shipped in the package at `packaged`, which `skill install` copies to the project root. */
+function packagedSkill(cli, { packaged: folder, agents: text }, install) {
+	const agents = text === void 0 ? void 0 : {
+		name: cli.name,
+		text
+	};
 	return {
 		kind: "packaged",
-		builtIns: { skill: { install: skillInstallCommand(cli, folder, install) } },
+		builtIns: { skill: { install: skillInstallCommand(cli, folder, install, agents) } },
 		rows: [{
 			name: "skill",
 			advisory: true,
 			run: (ctx) => findingOf(cli, folder, install, ctx)
-		}, agentsRow(cli, install)],
+		}, ...agents === void 0 ? [] : [agentsRow(agents, install)]],
 		notice: (launch, ctx) => notice(cli, folder, install, launch, ctx),
 		findingAt: (_version, ctx) => findingOf(cli, folder, install, ctx)
 	};
@@ -8121,7 +8119,7 @@ function packagedSkill(cli, folder, install) {
 /** A Packaged skill, or else a Skill Hub's, also for a CLI that declares no `skill`. */
 function skillOf(cli, install) {
 	const { skill } = cli;
-	return skill !== void 0 && "packaged" in skill ? packagedSkill(cli, skill.packaged, install) : hubSkill(cli, skill?.source);
+	return skill !== void 0 && "packaged" in skill ? packagedSkill(cli, skill, install) : hubSkill(cli, skill?.source);
 }
 //#endregion
 //#region ../agent-cli/dist/interrupts.js
@@ -8509,7 +8507,6 @@ function globalInstall(cli, install) {
 		runAs: runAsOf(cli),
 		builtIns: (launch) => ({ update: updateCommand(cli, install, skillOf(cli, adapter), launch) }),
 		exitClasses: ["source"],
-		agentsCaveat: void 0,
 		check: (launch) => checkOf(cli, install, launch)
 	};
 	return adapter;
@@ -8525,7 +8522,6 @@ function noInstall(cli) {
 		runAs: runAsOf(cli),
 		builtIns: () => ({}),
 		exitClasses: [],
-		agentsCaveat: void 0,
 		check: () => ({
 			install: skipped,
 			release: async () => ({ skipped: await skipped() })
@@ -9120,6 +9116,7 @@ function groupHelp(group, style) {
 }
 const EFFECT_NOTES = {
 	read: "changes nothing",
+	act: "changes the state of a running program, not files or services; may act again each time it runs",
 	write: "changes something; show the Plan with --dry-run",
 	destructive: "changes something hard to undo; show the Plan with --dry-run, run with --confirm",
 	serve: "changes nothing; prints its data at once, then runs until Ctrl-C, which exits 0"
@@ -9509,7 +9506,7 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, page, invoca
 		...input,
 		...page
 	}, ctx), (data, style) => command.render(data, style));
-	if (command.effect === "read") return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
+	if (command.effect === "read" || command.effect === "act") return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
 	if (command.effect === "serve") {
 		let end = () => {};
 		const ended = new Promise((resolve) => {
@@ -10258,14 +10255,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.15.1";
+var version$1 = "0.17.0";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "da48f36",
+	"sha": "8bb3938",
 	"dirty": false,
-	"builtAt": "2026-10-27T08:31:19.000Z"
+	"builtAt": "2026-10-27T10:54:44.000Z"
 };
 //#endregion
 //#region src/fill.ts

package/package.json

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

package/template/AGENTS.md

@@ -19,7 +19,7 @@ Greenfield with no deployments or users: change code directly. Breaking changes
 ## Coding standards
 
 - Every Command is declared in `src/cli.ts` with the `defineCommand` that `agentCli<Ports>()` returns: a description, realistic examples, Zod schemas for args and options (with `.describe()` on each field), and its Effect.
-- A Command never prints. A `read` Command returns data from `run` and turns it into short text in `render`. A `write` or `destructive` Command returns a Plan from `plan`, with no side effects, and performs it in `apply`; the Runtime adds `--dry-run`, and `--confirm` for a destructive one.
+- A Command never prints. A `read` Command returns data from `run` and turns it into short text in `render`. An `act` Command, which changes the state of a program already running rather than files or services, does the same with no Plan. A `write` or `destructive` Command returns a Plan from `plan`, with no side effects, and performs it in `apply`; the Runtime adds `--dry-run`, and `--confirm` for a destructive one. A `serve` Command returns data from `start` and keeps running until `ctx.signal` aborts.
 - A Command that writes files names them in `outputs(plan)`, and the Runtime refuses to overwrite one without `--force`. A Command that costs money states it in `cost(plan)`, a sentence or `undefined` when cheap, and the Runtime refuses a costly run without `--yes`.
 - A Command reaches a remote service through a port: an interface in `src/ports.ts`, built by the `ports` factory passed to `defineCli` and read as `ctx.ports`. It writes files through `ctx.files` and runs programs through `ctx.spawn`, so a test replaces each of them.
 - Every error code is declared once in a `defineErrors` table passed to `defineCli({ errors })`, with the Exit class that must act on it and an optional `details` schema, and thrown through `cliError(errors, code, { message, hint })`, whose `hint` names the command to run next. An undeclared code, and anything else thrown, becomes an internal error (exit 70), whose stack trace `{{debugVariable}}=1` shows.