@duyquangnvx/create-agent-cli 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.9.1 (2026-10-20)
+
+### Fixed
+
+- A clean build of the Scaffolder, and of a scaffolded CLI, stamps its commit's time as `builtAt` instead of the time it was built, so rebuilding a commit gives the same bundle and a rerun of a release cut off after its publish can check what it published. A dirty build still stamps the time it was built. v0.9.0 of `@duyquangnvx/create-agent-cli` was published, but its release could not finish for this reason, so its skill never reached the Skill Hub.
+
+## v0.9.0 (2026-10-20)
+
+### Added
+
+- The Scaffolder's `--skill-hub <git URL>` names the Skill Hub each release commits the new CLI's skill to: it becomes `skill.source` in `defineCli`, `skillHub` in `scripts/release.ts` and the README's skill line. See ADR 0009. It refuses a URL that does not end in `.git` or holds a query or fragment, and with it a name the release cannot put in a hub (`SKILL_NAME_INVALID`).
+
+### Changed
+
+- **Breaking:** `doctor`'s `skill` row and `update`'s `next` install the skill only from a declared `skill.source`, no longer from package.json `repository` at `#release`, a branch `@duyquangnvx/release` 0.4 stops moving. A CLI without `skill.source` still gets `skills update` for an older copy.
+- **Breaking:** the Scaffolder's `--repository` only sets package.json `repository`; the skill line comes from `--skill-hub`. The scaffolded template releases with `@duyquangnvx/release` 0.4.0.
+- **Breaking:** the agent-cli skill installs from the Skill Hub: `npx skills add https://github.com/duyquangnvx/skills.git --skill agent-cli -g`.
+
 ## v0.8.0 (2026-10-20)
 
 ### Changed

package/README.md

@@ -3,9 +3,9 @@
 Creates a new Agent CLI repository already wired to [`@duyquangnvx/agent-cli`](https://www.npmjs.com/package/@duyquangnvx/agent-cli):
 
 ```sh
-pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does" --repository https://github.com/<owner>/<name>
+pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does" --skill-hub https://github.com/<owner>/skills.git
 ```
 
-The new repository has an Error table, a port, two example Commands (one writing a file at a cost) and their test, a bundled build that stamps the commit and build time into `--version`, CI, a release script, a CHANGELOG, an `AGENTS.md`, and a skeleton skill for the new CLI whose setup reference installs, checks and updates it, so a user installs the skill first and lets their agent do the rest. `--repository` names where that skill is installed from. Pass `--dry-run` to see what it would write.
+The new repository has an Error table, a port, two example Commands (one writing a file at a cost) and their test, a bundled build that stamps the commit and build time into `--version`, CI, a release script, a CHANGELOG, an `AGENTS.md`, and a skeleton skill for the new CLI whose setup reference installs, checks and updates it, so a user installs the skill first and lets their agent do the rest. `--skill-hub` names the Skill Hub each release commits that skill to and agents install it from. Pass `--dry-run` to see what it would write.
 
-See the [repository](https://github.com/duyquangnvx/cli-for-agent) for an overview and the [agent-cli skill](https://github.com/duyquangnvx/cli-for-agent/blob/release/skills/agent-cli/SKILL.md) for how to build on it.
+See the [repository](https://github.com/duyquangnvx/cli-for-agent) for an overview and the [agent-cli skill](https://github.com/duyquangnvx/cli-for-agent/blob/main/skills/agent-cli/SKILL.md) for how to build on it.

package/dist/bin.js

@@ -7049,36 +7049,8 @@ async function globalInstallOf(bin, ctx) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/manifest.js
-const link$1 = union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0);
-const manifestSchema = object({
-	repository: link$1,
-	bugs: link$1
-});
-const NO_MANIFEST = {};
-function manifestAt(packageRoot) {
-	let manifest;
-	try {
-		manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-	} catch {
-		return NO_MANIFEST;
-	}
-	const parsed = manifestSchema.safeParse(manifest);
-	return parsed.success ? parsed.data : NO_MANIFEST;
-}
-//#endregion
 //#region ../agent-cli/dist/built-ins/skills.js
 const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
-/** The branch a release moves to the released commit, which holds the skill of that version. */
-const RELEASE_BRANCH$1 = "release";
-const SHORTHAND = /^(?:(?:github:)?[\w.-]+\/[\w.-]+|gitlab:[\w.-]+(?:\/[\w.-]+)+)$/;
-const GIT_URL_PROTOCOLS = /* @__PURE__ */ new Set([
-	"https:",
-	"http:",
-	"ssh:",
-	"git:"
-]);
-const SCP_STYLE = /^[\w.-]+@[\w.-]+:[\w./-]+$/;
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
 const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
 /** The version a SKILL.md's frontmatter `metadata.version` states. */
@@ -7127,18 +7099,6 @@ async function skillCopies(cliName, version, { cwd, env }) {
 	}
 	return copies;
 }
-function sourceFromRepository(repository) {
-	if (SHORTHAND.test(repository)) return `${repository}#${RELEASE_BRANCH$1}`;
-	const url = repository.replace(/^git\+/, "");
-	if (!(URL.canParse(url) && GIT_URL_PROTOCOLS.has(new URL(url).protocol)) && !SCP_STYLE.test(url)) return void 0;
-	return `${url.endsWith(".git") ? url : `${url}.git`}#${RELEASE_BRANCH$1}`;
-}
-/** What the installer installs the CLI's skill from: the declared source, else the package's repository. */
-function skillSource({ skill }, packageRoot) {
-	if (skill !== void 0) return skill.source;
-	const { repository } = manifestAt(packageRoot);
-	return repository === void 0 ? void 0 : sourceFromRepository(repository);
-}
 function fixFor(cliName, copies, source) {
 	const has = (wanted) => copies.some(({ state }) => state === wanted);
 	const update = `npx -y skills update ${cliName}`;
@@ -7151,7 +7111,7 @@ async function skillReport(cli, version, ctx) {
 	const copies = await skillCopies(cli.name, version, ctx);
 	return {
 		copies,
-		fix: fixFor(cli.name, copies, skillSource(cli, ctx.packageRoot))
+		fix: fixFor(cli.name, copies, cli.skill?.source)
 	};
 }
 //#endregion
@@ -8785,6 +8745,18 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, page, invoca
 	}
 	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
 }
+const manifestSchema = object({ bugs: union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0) });
+const NO_MANIFEST = {};
+function manifestAt(packageRoot) {
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	} catch {
+		return NO_MANIFEST;
+	}
+	const parsed = manifestSchema.safeParse(manifest);
+	return parsed.success ? parsed.data : NO_MANIFEST;
+}
 //#endregion
 //#region ../agent-cli/dist/parse-input.js
 const NO_INPUT = object({});
@@ -9437,14 +9409,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.8.0";
+var version$1 = "0.9.1";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "d2cc610",
+	"sha": "3014a0a",
 	"dirty": false,
-	"builtAt": "2026-10-20T09:33:37.544Z"
+	"builtAt": "2026-10-20T10:05:03.000Z"
 };
 //#endregion
 //#region src/steps.ts
@@ -9578,8 +9550,17 @@ const version = version$1;
 //#region src/create.ts
 const { defineCommand } = agentCli();
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?([a-z0-9][a-z0-9._-]*)$/;
-const RELEASE_BRANCH = "release";
-const NO_REPOSITORY = "<!-- Set `repository` in package.json, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
+const SKILL_HUB_ANCHORS = [{
+	file: "src/cli.ts",
+	before: "  commands: {",
+	line: (hub) => `  skill: { source: ${JSON.stringify(hub)} },\n`
+}, {
+	file: "scripts/release.ts",
+	before: "  smoke: {",
+	line: (hub) => `  skillHub: ${JSON.stringify(hub)},\n`
+}];
 function errorCode(error) {
 	return error instanceof Error && "code" in error ? error.code : void 0;
 }
@@ -9592,9 +9573,16 @@ async function isFree(path) {
 		throw error;
 	}
 }
-function skillInstallLine(repository, binName) {
-	if (repository === void 0) return NO_REPOSITORY;
-	return `\`! npx -y skills add ${`${repository.endsWith(".git") ? repository : `${repository}.git`}#${RELEASE_BRANCH}`} --skill ${binName} -g\``;
+function skillInstallLine(skillHub, binName) {
+	return skillHub === void 0 ? NO_SKILL_HUB : `\`! npx -y skills add ${skillHub} --skill ${binName} -g\``;
+}
+async function setSkillHub(root, skillHub) {
+	for (const { file, before, line } of SKILL_HUB_ANCHORS) {
+		const path = join(root, file);
+		const text = await readFile(path, "utf8");
+		if (!text.includes(before)) throw new Error(`the template's ${file} has no \`${before}\` line to put the Skill Hub before`);
+		await writeFile(path, text.replace(before, `${line(skillHub)}${before}`));
+	}
 }
 const MANIFEST = record(string(), unknown());
 async function setRepository(root, repository) {
@@ -9603,6 +9591,13 @@ async function setRepository(root, repository) {
 	const entries = Object.entries(manifest).flatMap((entry) => entry[0] === "description" ? [entry, ["repository", repository]] : [entry]);
 	await writeFile(path, `${JSON.stringify(Object.fromEntries(entries), null, 2)}\n`);
 }
+function ensureSkillName(binName) {
+	if (!SKILL_NAME.test(binName)) throw new UsageError({
+		code: "SKILL_NAME_INVALID",
+		message: `${binName} cannot name a skill in a Skill Hub, whose names are lowercase letters, digits and single hyphens`,
+		hint: "choose a name such as my-cli, or leave out --skill-hub"
+	});
+}
 async function ensureFree(path) {
 	if (!await isFree(path)) throw new UsageError({
 		code: "TARGET_NOT_EMPTY",
@@ -9623,10 +9618,12 @@ const create = defineCommand({
 		description: string().default("An Agent CLI.").describe("one line saying what the CLI does"),
 		install: boolean().default(true).describe("run pnpm install"),
 		git: boolean().default(true).describe("create a git repository with an initial commit"),
-		repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository, where its skill is installed from")
+		repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository"),
+		skillHub: url({ protocol: /^https$/ }).refine((url) => new URL(url).search === "" && new URL(url).hash === "", "must name the hub's repository with no query or fragment").refine((url) => new URL(url).pathname.endsWith(".git"), "must end in .git").optional().describe("the https git URL of the Skill Hub each release commits the CLI's skill to")
 	}),
-	plan: async ({ name, description, install, git, repository }, ctx) => {
+	plan: async ({ name, description, install, git, repository, skillHub }, ctx) => {
 		const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
+		if (skillHub !== void 0) ensureSkillName(binName);
 		const path = resolve(ctx.cwd, binName);
 		await ensureFree(path);
 		const values = {
@@ -9635,7 +9632,7 @@ const create = defineCommand({
 			description,
 			debugVariable: debugVariable(binName),
 			runtimeVersion: version,
-			skillInstall: skillInstallLine(repository, binName)
+			skillInstall: skillInstallLine(skillHub, binName)
 		};
 		return {
 			path,
@@ -9646,13 +9643,15 @@ const create = defineCommand({
 				git
 			}),
 			install,
-			repository
+			repository,
+			skillHub
 		};
 	},
 	apply: async (plan, ctx) => {
 		await mkdir(plan.path, { recursive: true });
 		await writeTemplate(plan.path, plan.files, plan.values);
 		if (plan.repository !== void 0) await setRepository(plan.path, plan.repository);
+		if (plan.skillHub !== void 0) await setSkillHub(plan.path, plan.skillHub);
 		await runSteps(plan.steps, plan.path, ctx);
 		return {
 			path: plan.path,

package/package.json

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

package/template/package.json

@@ -29,7 +29,7 @@
     "@biomejs/biome": "2.5.15",
     "@duyquangnvx/agent-cli": "{{runtimeVersion}}",
     "@duyquangnvx/harness": "0.3.1",
-    "@duyquangnvx/release": "0.2.0",
+    "@duyquangnvx/release": "0.4.0",
     "@types/node": "^22.19.0",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",

package/template/pnpm-workspace.yaml

@@ -1,4 +1,5 @@
-# A fresh project pins the Runtime release it was created with, which can be younger than
-# pnpm's minimum release age.
+# A fresh project pins the Runtime and release versions it was created with, which can be younger
+# than pnpm's minimum release age.
 minimumReleaseAgeExclude:
   - "@duyquangnvx/agent-cli"
+  - "@duyquangnvx/release"

package/template/test/cli.test.ts

@@ -186,7 +186,7 @@ describe("install lines", () => {
     expect(await text("README.md")).toContain(`\`! ${install}\``);
   });
 
-  test.skipIf(!("repository" in manifest))(
+  test.skipIf(cli.skill === undefined)(
     "the README installs the skill with doctor's skill line",
     async () => {
       const { skill } = await doctorFixes();

package/template/tsdown.config.ts

@@ -14,10 +14,12 @@ function git(args: readonly string[]): string {
   }
 }
 
+const dirty = git(["status", "--porcelain"]) !== "";
 const build = {
   sha: git(["rev-parse", "--short=7", "HEAD"]),
-  dirty: git(["status", "--porcelain"]) !== "",
-  builtAt: new Date().toISOString(),
+  dirty,
+  // A clean build stamps its commit's time, so a release that rebuilds a commit gets the same bundle.
+  builtAt: new Date(dirty ? Date.now() : git(["log", "-1", "--format=%cI", "HEAD"])).toISOString(),
 };
 
 export default defineConfig({