heximon 0.0.1 → 0.1.1

package/dist/skills-command-W72zUEYD.mjs

@@ -0,0 +1,940 @@
+import { createRequire } from "node:module";
+import { cancel, confirm, intro, log, outro, password, select, text } from "@clack/prompts";
+import process from "node:process";
+import { spawn } from "node:child_process";
+import { defineCommand } from "citty";
+import { dirname, join, relative, resolve } from "pathe";
+import { cp, lstat, mkdir, readFile, readdir, rm, stat, symlink, writeFile } from "node:fs/promises";
+//#region src/prompter.ts
+/** Thrown when the operator cancels an interactive prompt (Ctrl-C). */
+var PromptCancelledError = class extends Error {
+	constructor() {
+		super("Prompt cancelled.");
+		this.name = "PromptCancelledError";
+	}
+};
+//#endregion
+//#region src/clack-prompter.ts
+/**
+* The {@link Prompter} port backed by `@clack/prompts` — the one interactive surface the CLI exposes. A cancelled
+* prompt (clack's sentinel symbol) is normalized to a thrown {@link PromptCancelledError} so the credential
+* resolver handles one cancel failure mode.
+*/
+var ClackPrompter = class {
+	/** @throws PromptCancelledError when cancelled. */
+	async secret(message) {
+		const value = await password({ message });
+		if (typeof value === "symbol") throw new PromptCancelledError();
+		return value;
+	}
+	/** @throws PromptCancelledError when cancelled. */
+	async text(message) {
+		const value = await text({ message });
+		if (typeof value === "symbol") throw new PromptCancelledError();
+		return value;
+	}
+};
+//#endregion
+//#region src/cli-environment.ts
+/** Detects how the CLI is being run, so the deploy credential ladder knows whether interactive prompting is safe. */
+var CliEnvironment = class {
+	/**
+	* Whether this is an interactive session a prompt may block on: a real TTY on stdin AND not a CI runner. In CI
+	* (or a piped/non-TTY invocation) the deploy credential ladder must fail fast on a missing value rather than
+	* hang on a prompt no one can answer.
+	*/
+	static isInteractive() {
+		return process.stdin.isTTY === true && process.env["CI"] === void 0;
+	}
+};
+//#endregion
+//#region src/registry-access.ts
+/** The verdict {@link RegistryAccess.probe} classifies an `npm view` attempt into. */
+const RegistryAccessStatus = {
+	/** The probe package resolved — the registry is reachable and authorized. */
+	Ok: "ok",
+	/** The registry rejected the request for lacking (or holding invalid) credentials. */
+	Unauthorized: "unauthorized",
+	/** The registry could not be reached at all (DNS, network, timeout, an unrecognized failure). */
+	Unreachable: "unreachable",
+	/** The registry was reached and authorized the request, but the probe package is not there. */
+	NotFound: "not-found"
+};
+/**
+* Probes whether `@heximon/*` packages are readable from GitHub Packages, the private registry the
+* framework publishes to (the `heximon` CLI itself stays on public npm). A scaffolded project needs a
+* `.npmrc` scope line plus a token in the user's `~/.npmrc`; this probe reuses npm's own config
+* resolution — the same files npm itself reads — so the verdict matches what an install would do.
+*/
+var RegistryAccess = class RegistryAccess {
+	/** The private registry `@heximon/*` packages publish to. */
+	static gitHubPackagesRegistry = "https://npm.pkg.github.com";
+	/** The package probed to decide reachability — small, always published, always current. */
+	static probePackage = "@heximon/runtime";
+	/** The scope line a scaffolded project's `.npmrc` carries, routing `@heximon/*` to GitHub Packages. */
+	static npmrcScopeLine = `@heximon:registry=${RegistryAccess.gitHubPackagesRegistry}`;
+	run;
+	/**
+	* @param run - The process runner to probe with. Defaults to spawning `npm` for real; a test injects a
+	* stub so the probe never touches the network.
+	*/
+	constructor(run = (command, commandArguments) => RegistryAccess.spawnProcess(command, commandArguments)) {
+		this.run = run;
+	}
+	/**
+	* Runs `npm view @heximon/runtime version` against GitHub Packages and classifies the result.
+	*
+	* @returns The classified verdict, with the raw output kept as `detail` for diagnostics.
+	*/
+	async probe() {
+		const result = await this.run("npm", [
+			"view",
+			RegistryAccess.probePackage,
+			"version",
+			`--registry=${RegistryAccess.gitHubPackagesRegistry}`,
+			"--json"
+		]);
+		const combined = `${result.stdout}\n${result.stderr}`;
+		const detail = combined.trim();
+		if (result.exitCode === 0) return {
+			status: RegistryAccessStatus.Ok,
+			detail: detail.length === 0 ? void 0 : detail
+		};
+		if (/E401|E403|ENEEDAUTH/.test(combined)) return {
+			status: RegistryAccessStatus.Unauthorized,
+			detail
+		};
+		if (/E404/.test(combined)) return {
+			status: RegistryAccessStatus.NotFound,
+			detail
+		};
+		return {
+			status: RegistryAccessStatus.Unreachable,
+			detail
+		};
+	}
+	/**
+	* The fix instructions printed when {@link probe} does not report {@link RegistryAccessStatus.Ok}.
+	*
+	* @param status - The non-Ok verdict, when known — shapes the wording between an auth fix and a network hint.
+	*/
+	static fixInstructions(status = RegistryAccessStatus.Unauthorized) {
+		if (status === RegistryAccessStatus.Unreachable) return [
+			`Cannot reach ${RegistryAccess.gitHubPackagesRegistry}.`,
+			"Check your network connection.",
+			"Then run the install again."
+		].join("\n");
+		return [
+			"Cannot read @heximon/* from GitHub Packages.",
+			"Add these lines to ~/.npmrc:",
+			`  ${RegistryAccess.npmrcScopeLine}`,
+			"  //npm.pkg.github.com/:_authToken=<a GitHub token with the read:packages scope>",
+			"Then run the install again."
+		].join("\n");
+	}
+	/** The default {@link ProcessRunner}: spawns `npm` for real, capturing stdout/stderr. */
+	static spawnProcess(command, commandArguments) {
+		return new Promise((resolveRun) => {
+			const child = spawn(command, commandArguments, { shell: false });
+			let stdout = "";
+			let stderr = "";
+			child.stdout.on("data", (chunk) => {
+				stdout += chunk.toString();
+			});
+			child.stderr.on("data", (chunk) => {
+				stderr += chunk.toString();
+			});
+			child.on("error", (error) => {
+				resolveRun({
+					exitCode: 1,
+					stdout: "",
+					stderr: error.message
+				});
+			});
+			child.on("close", (exitCode) => {
+				resolveRun({
+					exitCode: exitCode ?? 1,
+					stdout,
+					stderr
+				});
+			});
+		});
+	}
+};
+//#endregion
+//#region src/project-scaffolder.ts
+/**
+* A template fetch that failed — the giget ref could not be downloaded. Distinct from every local failure so a
+* caller may retry another ref without also retrying (or cleaning up after) a validation or manifest error.
+*/
+var TemplateDownloadError = class extends Error {
+	/** The giget source string that could not be fetched. */
+	gigetSource;
+	constructor(gigetSource, cause) {
+		super(`Could not download the template ${gigetSource}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		this.name = "TemplateDownloadError";
+		this.gigetSource = gigetSource;
+	}
+};
+/**
+* Materializes a new Heximon project from a starters template: resolves the template directory name from
+* the {@link TemplateSelection}, fetches (giget) or copies (local) it, then stamps the project name and
+* the `@heximon/*` dependency ranges onto the fetched `package.json`. Pure filesystem work — prompting,
+* git, and dependency installation live with the CLI command.
+*/
+var ProjectScaffolder = class ProjectScaffolder {
+	/** A project/directory name: lowercase npm-safe segments (no scopes — the directory is the name). */
+	static projectNamePattern = /^[a-z0-9][a-z0-9._-]*$/;
+	/**
+	* Resolve the concrete template directory name for a selection — the validator variant is a `-zod` /
+	* `-valibot` suffix; `"none"` selects the base directory.
+	*
+	* @param selection - The template + validator axes.
+	* @returns The starters directory name (e.g. `"database-valibot"`).
+	*/
+	static templateNameOf(selection) {
+		return selection.validator === "none" ? selection.template : `${selection.template}-${selection.validator}`;
+	}
+	/**
+	* Validate a project name for use as both the directory and the `package.json` name.
+	*
+	* @param name - The candidate name.
+	* @returns `undefined` when valid, else a human-readable problem statement.
+	*/
+	static validateProjectName(name) {
+		if (name.length === 0) return "The project name is empty.";
+		if (!ProjectScaffolder.projectNamePattern.test(name)) return `"${name}" is not a valid project name — use lowercase letters, digits, and . _ - (it becomes the directory and package name).`;
+	}
+	/**
+	* Materialize the project: fetch/copy the template into `<parentDirectory>/<projectName>` and stamp the
+	* manifest. A target directory that already holds content is refused, never overwritten.
+	*
+	* @param request - What to scaffold, from where, and with which stamped versions.
+	* @returns The created project directory + the resolved template name.
+	*/
+	async scaffold(request) {
+		const templateName = ProjectScaffolder.templateNameOf(request);
+		const { projectDirectory } = await ProjectScaffolder.prepareTarget(request.parentDirectory, request.projectName);
+		if (request.source.localDirectory !== void 0) await cp(join(request.source.localDirectory, templateName), projectDirectory, { recursive: true });
+		else if (request.source.gigetSource !== void 0) await ProjectScaffolder.fetchTemplate(request.source.gigetSource, projectDirectory);
+		else throw new Error("No template source: provide a giget source or a local starters directory.");
+		await this.stampManifest(projectDirectory, request);
+		await ProjectScaffolder.writeNpmrc(projectDirectory, request.heximonVersion);
+		return {
+			projectDirectory,
+			templateName
+		};
+	}
+	/**
+	* Accept a target directory: the name must be valid, the resolved path must stay a direct child of the
+	* parent, and the directory must be absent or empty. A directory holding content is refused outright —
+	* `create` never overwrites.
+	*
+	* @param parentDirectory - The directory the project directory is created under.
+	* @param projectName - The candidate project (directory + package) name.
+	* @returns The accepted target, and whether this call created the directory.
+	*/
+	static async prepareTarget(parentDirectory, projectName) {
+		const problem = ProjectScaffolder.validateProjectName(projectName);
+		if (problem !== void 0) throw new Error(problem);
+		const parent = resolve(parentDirectory);
+		const projectDirectory = resolve(parent, projectName);
+		if (projectDirectory === parent || dirname(projectDirectory) !== parent) throw new Error(`"${projectName}" resolves to ${projectDirectory}, which is outside ${parent} — the project directory must be a direct child of the parent directory.`);
+		const entries = await ProjectScaffolder.readEntries(projectDirectory);
+		if (entries === void 0) {
+			await mkdir(projectDirectory, { recursive: true });
+			return {
+				projectDirectory,
+				createdDirectory: true
+			};
+		}
+		if (entries.length > 0) throw new Error(`The directory ${projectDirectory} already exists and is not empty — choose another name, or remove the directory yourself.`);
+		return {
+			projectDirectory,
+			createdDirectory: false
+		};
+	}
+	/**
+	* Discard what a failed scaffold left in a prepared target: the directory itself when this run created it,
+	* otherwise only the entries — a pre-existing directory was empty when accepted, so nothing else is ours.
+	*/
+	static async discardPreparedTarget(target) {
+		if (target.createdDirectory) {
+			await rm(target.projectDirectory, {
+				recursive: true,
+				force: true
+			});
+			return;
+		}
+		for (const entry of await ProjectScaffolder.readEntries(target.projectDirectory) ?? []) await rm(join(target.projectDirectory, entry), {
+			recursive: true,
+			force: true
+		});
+	}
+	/** Fetch a giget template, tagging a fetch failure so a caller can tell it from a local error. */
+	static async fetchTemplate(gigetSource, projectDirectory) {
+		const { downloadTemplate } = await import("giget");
+		try {
+			await downloadTemplate(gigetSource, { dir: projectDirectory });
+		} catch (error) {
+			throw new TemplateDownloadError(gigetSource, error);
+		}
+	}
+	/**
+	* Rewrite the scaffolded `package.json`: the project name, and every `@heximon/*` range to the CLI's
+	* lockstep version (`^<version>`) or `workspace:*`.
+	*/
+	async stampManifest(projectDirectory, request) {
+		const manifestPath = join(projectDirectory, "package.json");
+		const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+		manifest["name"] = request.projectName;
+		const range = request.heximonVersion === "workspace" ? "workspace:*" : `^${request.heximonVersion}`;
+		for (const section of ["dependencies", "devDependencies"]) {
+			const record = manifest[section];
+			if (record === void 0) continue;
+			for (const dependencyName of Object.keys(record)) if (dependencyName.startsWith("@heximon/") || dependencyName === "heximon") record[dependencyName] = range;
+		}
+		await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+	}
+	/**
+	* Write the `.npmrc` scope line that routes `@heximon/*` installs to GitHub Packages — skipped when the
+	* template already ships its own `.npmrc` (never overwritten), and in workspace mode (`heximonVersion ===
+	* "workspace"`), where the `@heximon/*` ranges are workspace links and need no registry at all.
+	*/
+	static async writeNpmrc(projectDirectory, heximonVersion) {
+		if (heximonVersion === "workspace") return;
+		const npmrcPath = join(projectDirectory, ".npmrc");
+		if (await ProjectScaffolder.pathExists(npmrcPath)) return;
+		await writeFile(npmrcPath, `${RegistryAccess.npmrcScopeLine}\n`);
+	}
+	/** Whether a filesystem path exists, of any kind. */
+	static async pathExists(path) {
+		try {
+			await stat(path);
+			return true;
+		} catch (error) {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		}
+	}
+	/** A directory's entries, or `undefined` when the directory does not exist. */
+	static async readEntries(directory) {
+		try {
+			return await readdir(directory);
+		} catch (error) {
+			if (error.code === "ENOENT") return;
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/skill-installer.ts
+/**
+* Installs the published Heximon agent skill into a scaffolded project from the docs site's RFC 8615
+* well-known endpoint — `/.well-known/skills/index.json` plus `/.well-known/skills/<name>/<file>`, the
+* same layout `npx skills add https://heximon.dev` consumes (Docus serves the docs repo's `skills/`
+* directory there natively). Best-effort by contract: the caller treats a throw as a skippable step with
+* a printed hint, never a scaffold failure.
+*/
+var SkillInstaller = class SkillInstaller {
+	sourceUrl;
+	/** The published docs site serving the skill. */
+	static defaultSourceUrl = "https://heximon.dev";
+	/** Where skills land inside the project — the universal agent layout; `.claude/skills` symlinks here. */
+	static targetDirectory = ".agents/skills";
+	/** Per-agent skills directories, each created as a relative symlink onto {@link targetDirectory}. */
+	static agentSymlinks = [".claude/skills"];
+	/** Per-request timeout — scaffolding must never hang on an unreachable docs deploy. */
+	static fetchTimeoutMs = 15e3;
+	constructor(sourceUrl = SkillInstaller.defaultSourceUrl) {
+		this.sourceUrl = sourceUrl;
+	}
+	/**
+	* Install every skill the source publishes into `projectDirectory`.
+	*
+	* @returns The installed skills, in index order.
+	* @throws {Error} When the index is unreachable/malformed or any listed file fails to download.
+	*/
+	async install(projectDirectory) {
+		const base = this.sourceUrl.replace(/\/+$/, "");
+		const index = await SkillInstaller.fetchIndex(`${base}/.well-known/skills/index.json`);
+		const installed = [];
+		for (const entry of index) {
+			const files = entry.files.filter((file) => SkillInstaller.isSafeRelativePath(file));
+			for (const file of files) {
+				const content = await SkillInstaller.fetchText(`${base}/.well-known/skills/${entry.name}/${file}`);
+				const targetPath = join(projectDirectory, SkillInstaller.targetDirectory, entry.name, file);
+				await mkdir(dirname(targetPath), { recursive: true });
+				await writeFile(targetPath, content);
+			}
+			installed.push({
+				name: entry.name,
+				fileCount: files.length
+			});
+		}
+		if (installed.length === 0) throw new Error(`No skills published at ${base}/.well-known/skills/index.json`);
+		await SkillInstaller.linkAgentDirectories(projectDirectory);
+		return installed;
+	}
+	/**
+	* Point each per-agent skills directory (`.claude/skills`) at the universal `.agents/skills` copy via a
+	* relative symlink, so every agent convention reads the one install. Best-effort: an existing entry is
+	* left untouched, and a filesystem that cannot symlink (e.g. Windows without developer mode) is not an
+	* install failure — the universal copy stands on its own.
+	*/
+	static async linkAgentDirectories(projectDirectory) {
+		for (const agentDirectory of SkillInstaller.agentSymlinks) {
+			const linkPath = join(projectDirectory, agentDirectory);
+			const parentSegments = agentDirectory.split("/").slice(0, -1);
+			const relativeTarget = join(...parentSegments.map(() => ".."), SkillInstaller.targetDirectory);
+			try {
+				await lstat(linkPath);
+				continue;
+			} catch {}
+			try {
+				await mkdir(dirname(linkPath), { recursive: true });
+				await symlink(relativeTarget, linkPath, "dir");
+			} catch {}
+		}
+	}
+	/** Fetch and validate the discovery index, keeping only well-shaped entries with safe names. */
+	static async fetchIndex(indexUrl) {
+		const body = await SkillInstaller.fetchJson(indexUrl);
+		if (!Array.isArray(body.skills)) throw new Error(`Malformed skills index at ${indexUrl}`);
+		return body.skills.flatMap((entry) => typeof entry.name === "string" && /^[a-z0-9][a-z0-9-]*$/.test(entry.name) && Array.isArray(entry.files) ? [{
+			name: entry.name,
+			files: entry.files.filter((file) => typeof file === "string")
+		}] : []);
+	}
+	/** A relative file path with no traversal, absolute prefix, or backslash trickery. */
+	static isSafeRelativePath(file) {
+		return file.length > 0 && !file.startsWith("/") && !file.includes("\\") && !file.split("/").includes("..");
+	}
+	static async fetchJson(url) {
+		const response = await fetch(url, { signal: AbortSignal.timeout(SkillInstaller.fetchTimeoutMs) });
+		if (!response.ok) throw new Error(`GET ${url} failed with ${response.status.toString()}`);
+		return response.json();
+	}
+	static async fetchText(url) {
+		const response = await fetch(url, { signal: AbortSignal.timeout(SkillInstaller.fetchTimeoutMs) });
+		if (!response.ok) throw new Error(`GET ${url} failed with ${response.status.toString()}`);
+		return response.text();
+	}
+};
+//#endregion
+//#region src/skill-sources.ts
+/**
+* The project's recorded agent-skill sources, persisted as `heximon.skills` in its `package.json`.
+*
+* The manifest rather than the config sidecar, for one reason: `heximon create` records the default source
+* before an app exists to compile, and a tool reads the list without evaluating any TypeScript. Every entry
+* is a base URL {@link SkillInstaller} can install from — the same value `npx skills add <url>` takes.
+*/
+var SkillSources = class SkillSources {
+	/** The `package.json` member holding the framework's own manifest block. */
+	static manifestKey = "heximon";
+	/** The member of that block holding the source list. */
+	static listKey = "skills";
+	/**
+	* The sources recorded for a project, in the order they were added.
+	*
+	* @param projectDirectory - The project root holding `package.json`.
+	* @returns The recorded base URLs; empty when the manifest records none (or has no readable list).
+	* @throws {Error} When `package.json` is missing or is not readable JSON — a project whose manifest cannot
+	*   be read is not one to silently report as having no skills.
+	*/
+	static async read(projectDirectory) {
+		const block = (await SkillSources.readManifest(projectDirectory))[SkillSources.manifestKey];
+		if (typeof block !== "object" || block === null || Array.isArray(block)) return [];
+		const list = block[SkillSources.listKey];
+		return Array.isArray(list) ? list.filter((entry) => typeof entry === "string") : [];
+	}
+	/**
+	* Record one source, leaving every other manifest member untouched.
+	*
+	* @param projectDirectory - The project root holding `package.json`.
+	* @param sourceUrl - The base URL to record, normalized by {@link normalize} first.
+	* @returns `true` when the source was added, `false` when it was already recorded — so recording twice is
+	*   a no-op the caller can report as such rather than a duplicated entry.
+	*/
+	static async record(projectDirectory, sourceUrl) {
+		const normalized = SkillSources.normalize(sourceUrl);
+		const manifest = await SkillSources.readManifest(projectDirectory);
+		const existingBlock = manifest[SkillSources.manifestKey];
+		const block = typeof existingBlock === "object" && existingBlock !== null && !Array.isArray(existingBlock) ? { ...existingBlock } : {};
+		const recorded = Array.isArray(block[SkillSources.listKey]) ? block[SkillSources.listKey].filter((entry) => typeof entry === "string") : [];
+		if (recorded.includes(normalized)) return false;
+		block[SkillSources.listKey] = [...recorded, normalized];
+		manifest[SkillSources.manifestKey] = block;
+		await writeFile(join(projectDirectory, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+		return true;
+	}
+	/**
+	* The canonical form of a source URL: trailing slashes removed, so `https://heximon.dev/` and
+	* `https://heximon.dev` are one recorded entry rather than two installs of the same site.
+	*/
+	static normalize(sourceUrl) {
+		return sourceUrl.replace(/\/+$/, "");
+	}
+	/** Whether a string is an absolute `http`/`https` URL — the only form the installer can fetch from. */
+	static isInstallable(sourceUrl) {
+		try {
+			const url = new URL(sourceUrl);
+			return url.protocol === "http:" || url.protocol === "https:";
+		} catch {
+			return false;
+		}
+	}
+	/** The project manifest as a mutable record. */
+	static async readManifest(projectDirectory) {
+		const manifestPath = join(projectDirectory, "package.json");
+		const contents = await readFile(manifestPath, "utf8");
+		const manifest = JSON.parse(contents);
+		if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) throw new Error(`${manifestPath} is not a JSON object.`);
+		return manifest;
+	}
+};
+//#endregion
+//#region src/create-command.ts
+/** The `heximon create` verb: scaffold a new Heximon app from the starters templates. */
+const createCommand = defineCommand({
+	meta: {
+		name: "create",
+		description: "Scaffold a new Heximon app from a starter template (minimal or database, with an optional zod/valibot validator)."
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "The project directory (and package) name.",
+			required: false
+		},
+		cwd: {
+			type: "string",
+			description: "Parent directory to create the project in.",
+			default: "."
+		},
+		template: {
+			type: "string",
+			description: "Starter template: minimal | database."
+		},
+		validator: {
+			type: "string",
+			description: "Request-body validator baked into the starter: zod | valibot | none."
+		},
+		pm: {
+			type: "string",
+			description: "Package manager for the install step + printed commands (npm/pnpm/yarn/bun). Default: detected from the invoking manager."
+		},
+		install: {
+			type: "boolean",
+			description: "Install dependencies after scaffolding (--no-install to skip)."
+		},
+		git: {
+			type: "boolean",
+			description: "Initialize a git repository in the new project (skipped automatically inside an existing repository).",
+			default: true
+		},
+		yes: {
+			type: "boolean",
+			description: "Accept every default without prompting (non-interactive/CI).",
+			default: false
+		},
+		skills: {
+			type: "boolean",
+			description: "Install the Heximon agent skill from heximon.dev into .agents/skills, with .claude/skills symlinked onto it (--no-skills to skip).",
+			default: true
+		},
+		local: {
+			type: "string",
+			description: "Maintainer path: scaffold from a local starters directory instead of fetching from GitHub."
+		},
+		workspace: {
+			type: "boolean",
+			description: "Maintainer path: stamp workspace:* onto the @heximon/* ranges (in-monorepo dogfooding).",
+			default: false
+		},
+		"skip-registry-check": {
+			type: "boolean",
+			description: "Skip the GitHub Packages read check before installing (@heximon/* publishes there; heximon itself is public npm).",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const interactive = CliEnvironment.isInteractive() && !args.yes;
+		const packageManager = CreateDefaults.resolvePackageManager(args.pm);
+		intro("heximon create");
+		try {
+			let projectName = args.name;
+			if (projectName === void 0 || projectName.length === 0) {
+				if (interactive) {
+					const answer = await text({
+						message: "Project name",
+						placeholder: CreateDefaults.projectName,
+						defaultValue: CreateDefaults.projectName,
+						validate: (value) => ProjectScaffolder.validateProjectName(value === void 0 || value === "" ? CreateDefaults.projectName : value)
+					});
+					if (typeof answer === "symbol") {
+						cancel("Cancelled — nothing created.");
+						process.exitCode = 1;
+						return;
+					}
+					projectName = answer;
+				} else projectName = CreateDefaults.projectName;
+			}
+			const nameProblem = ProjectScaffolder.validateProjectName(projectName);
+			if (nameProblem !== void 0) throw new Error(nameProblem);
+			const selection = await CreateDefaults.resolveSelection(args.template, args.validator, { interactive });
+			if (selection === void 0) {
+				cancel("Cancelled — nothing created.");
+				process.exitCode = 1;
+				return;
+			}
+			const scaffolder = new ProjectScaffolder();
+			const heximonVersion = args.workspace ? "workspace" : CreateDefaults.cliVersion();
+			const parentDirectory = resolve(process.cwd(), args.cwd);
+			const templateName = ProjectScaffolder.templateNameOf(selection);
+			let result;
+			if (args.local !== void 0) result = await scaffolder.scaffold({
+				...selection,
+				projectName,
+				parentDirectory,
+				heximonVersion,
+				source: { localDirectory: resolve(process.cwd(), args.local) }
+			});
+			else result = await CreateDefaults.scaffoldFromStarters(scaffolder, {
+				selection,
+				projectName,
+				parentDirectory,
+				heximonVersion,
+				templateName
+			});
+			log.success(`Scaffolded ${result.templateName} into ${result.projectDirectory}.`);
+			if (args.git && !args.workspace) {
+				const initialized = await CreateDefaults.initializeGit(result.projectDirectory);
+				log.info(initialized ? "Initialized a git repository." : "Skipped git init (already inside a repository, or git is unavailable).");
+			}
+			let installNow = args.install;
+			if (installNow === void 0 && interactive) {
+				const answer = await confirm({ message: `Install dependencies with ${packageManager}?` });
+				if (typeof answer === "symbol") {
+					cancel("Cancelled after scaffolding — the project directory was kept.");
+					process.exitCode = 1;
+					return;
+				}
+				installNow = answer;
+			}
+			const willInstall = installNow === true || installNow === void 0 && args.yes;
+			let installedDependencies = false;
+			if (willInstall) {
+				const registryReport = args.workspace || args["skip-registry-check"] ? { status: RegistryAccessStatus.Ok } : await new RegistryAccess().probe();
+				if (registryReport.status === RegistryAccessStatus.Ok) {
+					log.info(`Installing dependencies with ${packageManager}…`);
+					await CreateDefaults.runInstall(packageManager, result.projectDirectory);
+					log.success("Dependencies installed.");
+					installedDependencies = true;
+				} else {
+					log.error(RegistryAccess.fixInstructions(registryReport.status));
+					process.exitCode = 1;
+				}
+			}
+			if (args.skills) try {
+				const installed = await new SkillInstaller().install(result.projectDirectory);
+				await SkillSources.record(result.projectDirectory, SkillInstaller.defaultSourceUrl);
+				log.success(`Installed the ${installed.map((skill) => skill.name).join(", ")} agent skill into .agents/skills (.claude/skills symlinked), recorded in package.json.`);
+			} catch {
+				log.info(`Could not fetch the agent skill — install it later with: npx skills add ${SkillInstaller.defaultSourceUrl}`);
+			}
+			const changeDirectory = relative(process.cwd(), result.projectDirectory);
+			const steps = [
+				`cd ${changeDirectory === "" ? "." : changeDirectory}`,
+				...installedDependencies ? [] : [`${packageManager} install`],
+				`${packageManager} run dev`
+			];
+			outro(`Done. Next steps:\n\n  ${steps.join("\n  ")}\n\nThen: curl http://localhost:3000`);
+		} catch (error) {
+			cancel(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		}
+	}
+});
+/**
+* The `create` command's defaults + environment glue: package-manager detection, the CLI's own lockstep
+* version, the starters giget refs (version branch → main fallback), git init, and the install spawn.
+*/
+var CreateDefaults = class CreateDefaults {
+	/** The default project (directory + package) name when none is given. */
+	static projectName = "my-heximon-app";
+	/** The GitHub repository the published templates are fetched from. */
+	static startersRepository = "heximon/starters";
+	/**
+	* The CLI's own version — the framework version, since `heximon` releases in the lockstep group. It is
+	* what `@heximon/*` ranges are stamped to.
+	*
+	* @returns The version from this package's own manifest.
+	*/
+	static cliVersion() {
+		return createRequire(import.meta.url)("../package.json").version;
+	}
+	/**
+	* Detect the invoking package manager from `npm_config_user_agent` (the create-vite trick).
+	*
+	* @param override - An explicit `--pm` value, which wins when given.
+	* @returns One of npm/pnpm/yarn/bun.
+	*/
+	static resolvePackageManager(override) {
+		if (override !== void 0 && [
+			"npm",
+			"pnpm",
+			"yarn",
+			"bun"
+		].includes(override)) return override;
+		const userAgent = process.env["npm_config_user_agent"] ?? "";
+		for (const manager of [
+			"pnpm",
+			"yarn",
+			"bun"
+		]) if (userAgent.startsWith(`${manager}/`)) return manager;
+		return "npm";
+	}
+	/**
+	* Resolve the template + validator axes from flags, prompts, or defaults.
+	*
+	* @param template - The `--template` flag value, if any.
+	* @param validator - The `--validator` flag value, if any.
+	* @param options - Whether prompting is allowed.
+	* @returns The resolved selection, or `undefined` when the user cancelled a prompt.
+	*/
+	static async resolveSelection(template, validator, options) {
+		let resolvedTemplate = CreateDefaults.narrow(template, ["minimal", "database"]);
+		let resolvedValidator = CreateDefaults.narrow(validator, [
+			"zod",
+			"valibot",
+			"none"
+		]);
+		if (template !== void 0 && resolvedTemplate === void 0) throw new Error(`Unknown template "${template}" — expected minimal or database.`);
+		if (validator !== void 0 && resolvedValidator === void 0) throw new Error(`Unknown validator "${validator}" — expected zod, valibot, or none.`);
+		if (resolvedTemplate === void 0) {
+			if (options.interactive) {
+				const answer = await select({
+					message: "Template",
+					options: [{
+						value: "minimal",
+						label: "minimal — the smallest real app"
+					}, {
+						value: "database",
+						label: "database — CRUD over Drizzle + libsql/SQLite"
+					}]
+				});
+				if (typeof answer === "symbol") return;
+				resolvedTemplate = answer;
+			} else resolvedTemplate = "minimal";
+		}
+		if (resolvedValidator === void 0) {
+			if (options.interactive) {
+				const answer = await select({
+					message: "Request-body validator",
+					options: [
+						{
+							value: "zod",
+							label: "zod (the docs default)"
+						},
+						{
+							value: "valibot",
+							label: "valibot"
+						},
+						{
+							value: "none",
+							label: "none — hand-checked bodies"
+						}
+					]
+				});
+				if (typeof answer === "symbol") return;
+				resolvedValidator = answer;
+			} else resolvedValidator = "zod";
+		}
+		return {
+			template: resolvedTemplate,
+			validator: resolvedValidator
+		};
+	}
+	/**
+	* Scaffold from the published starters repository: try the CLI's `v<major.minor>` branch first (the
+	* templates matching this CLI's framework minor), falling back to `main`.
+	*
+	* The target is accepted before the first attempt, so a refusal (bad name, escaping path, existing
+	* content) never reaches the retry — the cleanup below discards only what this call itself created.
+	*/
+	static async scaffoldFromStarters(scaffolder, request) {
+		const [major = "0", minor = "0"] = CreateDefaults.cliVersion().split(".");
+		const base = `gh:${CreateDefaults.startersRepository}/${request.templateName}`;
+		const target = await ProjectScaffolder.prepareTarget(request.parentDirectory, request.projectName);
+		try {
+			return await CreateDefaults.attemptScaffold(scaffolder, request, `${base}#v${major}.${minor}`);
+		} catch (error) {
+			await ProjectScaffolder.discardPreparedTarget(target);
+			if (!(error instanceof TemplateDownloadError)) throw error;
+		}
+		try {
+			return await CreateDefaults.attemptScaffold(scaffolder, request, `${base}#main`);
+		} catch (error) {
+			await ProjectScaffolder.discardPreparedTarget(target);
+			throw error;
+		}
+	}
+	/**
+	* `git init` the project directory, unless it already sits inside a work tree (or git is unavailable).
+	*
+	* @returns Whether a repository was initialized.
+	*/
+	static async initializeGit(projectDirectory) {
+		if (await CreateDefaults.run("git", ["rev-parse", "--is-inside-work-tree"], {
+			cwd: projectDirectory,
+			captureOnly: true
+		}) === 0) return false;
+		return await CreateDefaults.run("git", ["init"], {
+			cwd: projectDirectory,
+			captureOnly: true
+		}) === 0;
+	}
+	/** Run `<pm> install` in the project directory with inherited stdio (the user sees the real output). */
+	static async runInstall(packageManager, projectDirectory) {
+		const exitCode = await CreateDefaults.run(packageManager, ["install"], {
+			cwd: projectDirectory,
+			captureOnly: false
+		});
+		if (exitCode !== 0) throw new Error(`${packageManager} install failed (exit ${exitCode}) — run it manually inside the project.`);
+	}
+	/** Run one starters attempt against a single giget ref. */
+	static attemptScaffold(scaffolder, request, gigetSource) {
+		return scaffolder.scaffold({
+			...request.selection,
+			projectName: request.projectName,
+			parentDirectory: request.parentDirectory,
+			heximonVersion: request.heximonVersion,
+			source: { gigetSource }
+		});
+	}
+	/** Narrow a raw flag value to one of the allowed literals, or `undefined`. */
+	static narrow(value, allowed) {
+		return allowed.includes(value) ? value : void 0;
+	}
+	/** Spawn a child process and resolve its exit code (non-zero-safe; spawn errors resolve to 1). */
+	static run(command, commandArguments, options) {
+		return new Promise((resolveExit) => {
+			const child = spawn(command, commandArguments, {
+				cwd: options.cwd,
+				stdio: options.captureOnly ? "ignore" : "inherit",
+				shell: false
+			});
+			child.on("error", () => resolveExit(1));
+			child.on("close", (code) => resolveExit(code ?? 1));
+		});
+	}
+};
+//#endregion
+//#region src/skills-command.ts
+/** The shared behavior behind `heximon skills add` and `heximon skills sync`. */
+var SkillsRunner = class SkillsRunner {
+	/** The argument every `skills` subcommand takes. */
+	static baseArgs = { cwd: {
+		type: "string",
+		description: "Project root directory.",
+		default: "."
+	} };
+	/**
+	* Install one source into `projectDirectory`, logging what landed.
+	*
+	* @returns `true` when the install succeeded; a failure is logged and reported to the caller, never thrown,
+	*   so `sync` over several sources still attempts the rest.
+	*/
+	static async install(projectDirectory, sourceUrl) {
+		try {
+			const installed = await new SkillInstaller(sourceUrl).install(projectDirectory);
+			log.success(`${sourceUrl} → ${SkillsRunner.describe(installed)} in .agents/skills`);
+			return true;
+		} catch (error) {
+			log.error(`${sourceUrl} — ${error instanceof Error ? error.message : String(error)}`);
+			return false;
+		}
+	}
+	/** One install's skills, as `name (n files)` entries. */
+	static describe(installed) {
+		return installed.map((skill) => `${skill.name} (${skill.fileCount.toString()} files)`).join(", ");
+	}
+};
+const addCommand = defineCommand({
+	meta: {
+		name: "add",
+		description: "Record an agent-skill source in package.json and install it into .agents/skills."
+	},
+	args: {
+		...SkillsRunner.baseArgs,
+		url: {
+			type: "positional",
+			description: `The site publishing the skills (default ${SkillInstaller.defaultSourceUrl}).`,
+			required: false
+		}
+	},
+	async run({ args }) {
+		const projectDirectory = resolve(process.cwd(), args.cwd);
+		const requested = args.url ?? SkillInstaller.defaultSourceUrl;
+		const sourceUrl = SkillSources.normalize(requested);
+		intro("heximon skills add");
+		if (!SkillSources.isInstallable(sourceUrl)) {
+			process.exitCode = 1;
+			outro(`'${requested}' is not an absolute http(s) URL — pass the site publishing the skills.`);
+			return;
+		}
+		if (!await SkillsRunner.install(projectDirectory, sourceUrl)) {
+			process.exitCode = 1;
+			outro("Nothing was installed, so nothing was recorded.");
+			return;
+		}
+		const added = await SkillSources.record(projectDirectory, sourceUrl);
+		outro(added ? `Recorded ${sourceUrl} in package.json (heximon.skills). Re-install it any time with \`heximon skills sync\`.` : `${sourceUrl} was already recorded — the install refreshed it.`);
+	}
+});
+const syncCommand = defineCommand({
+	meta: {
+		name: "sync",
+		description: "Re-install every agent-skill source package.json records."
+	},
+	args: SkillsRunner.baseArgs,
+	async run({ args }) {
+		const projectDirectory = resolve(process.cwd(), args.cwd);
+		intro("heximon skills sync");
+		const sources = await SkillSources.read(projectDirectory);
+		if (sources.length === 0) {
+			outro("No skill sources recorded in package.json (heximon.skills) — add one with `heximon skills add <url>`.");
+			return;
+		}
+		let failures = 0;
+		for (const sourceUrl of sources) if (!await SkillsRunner.install(projectDirectory, sourceUrl)) failures += 1;
+		if (failures > 0) {
+			process.exitCode = 1;
+			outro(`${failures.toString()} of ${sources.length.toString()} source(s) failed — see above.`);
+			return;
+		}
+		outro(`${sources.length.toString()} source(s) re-installed into .agents/skills.`);
+	}
+});
+/**
+* The `heximon skills` command — install the published agent skills into a project and keep the list of
+* sources in `package.json` (`heximon.skills`), so a second machine or a fresh clone reproduces the same
+* install with one verb instead of a remembered URL.
+*
+* `heximon create` already installs the default source and records it, so an existing project's first use of
+* this command is usually `sync` after a clone, or `add` for a second, private skill site.
+*/
+const skillsCommand = defineCommand({
+	meta: {
+		name: "skills",
+		description: "Install and re-install the agent skills a project records in its package.json."
+	},
+	subCommands: {
+		add: addCommand,
+		sync: syncCommand
+	}
+});
+//#endregion
+export { SkillInstaller as a, RegistryAccess as c, ClackPrompter as d, PromptCancelledError as f, SkillSources as i, RegistryAccessStatus as l, CreateDefaults as n, ProjectScaffolder as o, createCommand as r, TemplateDownloadError as s, skillsCommand as t, CliEnvironment as u };