@hagicode/skillsbase 0.1.0-dev.1.1.426f4b0

package/dist/cli.mjs

@@ -0,0 +1,1109 @@
+import path from "node:path";
+import { promises } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+//#region src/lib/output.ts
+var CliError = class extends Error {
+	exitCode;
+	details;
+	nextSteps;
+	constructor(message, options = {}) {
+		super(message);
+		this.name = "CliError";
+		this.exitCode = options.exitCode ?? 1;
+		this.details = options.details ?? [];
+		this.nextSteps = options.nextSteps ?? [];
+	}
+};
+function printCommandUsage(stdout) {
+	stdout.write([
+		"Usage: skillsbase <command> [options]",
+		"",
+		"Commands:",
+		"  init            Create the managed repository baseline",
+		"  sync            Reconcile managed skills from sources.yaml",
+		"  add             Add a skill to a source block and sync",
+		"  remove          Remove a skill from a source block and sync",
+		"  github_action   Generate managed GitHub Actions assets",
+		"",
+		"Global Options:",
+		"  --repo <path>               Target repository path (default: current directory)",
+		"  --allow-missing-sources     Skip missing local source roots during sync/add/remove",
+		"  --help, -h                  Show help",
+		"  --version, -v               Show version",
+		""
+	].join("\n"));
+}
+function printCommandResult(result, output) {
+	const lines = [
+		`## ${result.title ?? result.command}`,
+		"",
+		`repository: ${result.repository}`,
+		`exit_code: ${result.exitCode ?? 0}`
+	];
+	if (result.schema) lines.push(`schema: ${result.schema}`);
+	if (result.items?.length) {
+		lines.push("", "items:");
+		for (const item of result.items) lines.push(`- ${item}`);
+	}
+	if (result.nextSteps?.length) {
+		lines.push("", "next:");
+		for (const nextStep of result.nextSteps) lines.push(`- ${nextStep}`);
+	}
+	lines.push("");
+	output.write(`${lines.join("\n")}\n`);
+}
+//#endregion
+//#region src/lib/constants.ts
+var MANAGED_SIGNATURE = "Managed by skillsbase CLI";
+var DEFAULT_SKILLS_CLI_VERSION = "1.4.8";
+var DEFAULT_INSTALL_AGENT = "codex";
+var DEFAULT_SKILLS_ROOT = "skills";
+var DEFAULT_METADATA_FILE = ".skill-source.json";
+var DEFAULT_MANAGED_BY = "skillsbase";
+var DEFAULT_NODE_VERSION = "22.12.0";
+//#endregion
+//#region src/lib/files.ts
+async function pathExists(targetPath) {
+	try {
+		await promises.access(targetPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readFileIfExists(targetPath, encoding = "utf8") {
+	if (!await pathExists(targetPath)) return null;
+	return promises.readFile(targetPath, encoding);
+}
+async function ensureDirectory(targetPath) {
+	await promises.mkdir(targetPath, { recursive: true });
+}
+async function listDirectories(rootPath) {
+	if (!await pathExists(rootPath)) return [];
+	return (await promises.readdir(rootPath, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+}
+async function collectRelativeFiles(rootPath, basePath = rootPath) {
+	const entries = await promises.readdir(rootPath, { withFileTypes: true });
+	const files = [];
+	for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
+		const absolutePath = path.join(rootPath, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...await collectRelativeFiles(absolutePath, basePath));
+			continue;
+		}
+		if (entry.isFile()) files.push(toPosix(path.relative(basePath, absolutePath)));
+	}
+	return files;
+}
+async function readTree(rootPath) {
+	const files = await collectRelativeFiles(rootPath);
+	const tree = /* @__PURE__ */ new Map();
+	for (const relativePath of files) tree.set(relativePath, await promises.readFile(path.join(rootPath, relativePath)));
+	return tree;
+}
+async function writeTree(rootPath, tree) {
+	await promises.rm(rootPath, {
+		recursive: true,
+		force: true
+	});
+	await promises.mkdir(rootPath, { recursive: true });
+	for (const [relativePath, content] of [...tree.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+		const targetPath = path.join(rootPath, relativePath);
+		await promises.mkdir(path.dirname(targetPath), { recursive: true });
+		await promises.writeFile(targetPath, content);
+	}
+}
+async function removeIfEmptyUpward(startPath, stopPath) {
+	let currentPath = startPath;
+	const normalizedStop = path.resolve(stopPath);
+	while (currentPath.startsWith(normalizedStop) && currentPath !== normalizedStop) {
+		if (!await pathExists(currentPath)) {
+			currentPath = path.dirname(currentPath);
+			continue;
+		}
+		if ((await promises.readdir(currentPath)).length > 0) return;
+		await promises.rmdir(currentPath);
+		currentPath = path.dirname(currentPath);
+	}
+}
+function stableJson(value) {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+function toPosix(filePath) {
+	return filePath.split(path.sep).join(path.posix.sep);
+}
+//#endregion
+//#region src/lib/manifest.ts
+function parseScalar(rawValue) {
+	const value = rawValue.trim();
+	if (value.length === 0) return "";
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (/^-?\d+$/.test(value)) return Number(value);
+	if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+	return value;
+}
+function quoteYamlString(value) {
+	if (value === "") return "\"\"";
+	if (/^[A-Za-z0-9._/@:+-]+$/.test(value)) return value;
+	return JSON.stringify(value);
+}
+function validateSource(source) {
+	for (const key of [
+		"key",
+		"label",
+		"kind",
+		"root",
+		"targetPrefix",
+		"include"
+	]) if (!(key in source)) throw new CliError(`Source "${source.key ?? "<unknown>"}" is missing key "${key}".`, { details: ["Repair `sources.yaml` or rerun `skillsbase init`."] });
+	if (!Array.isArray(source.include) || source.include.some((value) => typeof value !== "string")) throw new CliError(`Source "${source.key}" must define an include list.`, { details: ["Use `include: []` only via the CLI serializer; do not change its type."] });
+	return {
+		key: String(source.key),
+		label: String(source.label),
+		kind: String(source.kind),
+		root: String(source.root),
+		targetPrefix: String(source.targetPrefix),
+		include: [...source.include]
+	};
+}
+function isRemoteRepositorySource(source) {
+	return source.kind === "github-repository";
+}
+function buildSourcePath(source, originalName) {
+	if (isRemoteRepositorySource(source)) return `${source.root}@${originalName}`;
+	return path.join(source.root, originalName);
+}
+function resolveSourceRoot(repoPath, source) {
+	if (isRemoteRepositorySource(source) || path.isAbsolute(source.root)) return source.root;
+	return path.resolve(repoPath, source.root);
+}
+function resolveSourcePath(repoPath, source, originalName) {
+	if (isRemoteRepositorySource(source)) return buildSourcePath(source, originalName);
+	return path.join(resolveSourceRoot(repoPath, source), originalName);
+}
+function cloneSource(source) {
+	return {
+		...source,
+		include: [...source.include ?? []]
+	};
+}
+function cloneManifestWithSources(manifest, sources) {
+	return {
+		...manifest,
+		sources: sources.map(cloneSource)
+	};
+}
+function sortInclude(include) {
+	return [...include].sort((left, right) => left.localeCompare(right));
+}
+function assertManifestHasSources(manifest) {
+	if (manifest.sources.length === 0) throw new CliError("Manifest does not declare any source blocks.", { details: ["Run `skillsbase init` first or add a source block to `sources.yaml`."] });
+}
+function getSourceKeys(manifest) {
+	return manifest.sources.map((source) => source.key).join(", ");
+}
+function findSourceByKey(manifest, sourceKey) {
+	const source = manifest.sources.find((candidate) => candidate.key === sourceKey);
+	if (!source) throw new CliError(`Unknown source key: ${sourceKey}`, { details: [`Declared sources: ${getSourceKeys(manifest)}`] });
+	return source;
+}
+function findSourcesBySkill(manifest, skillName) {
+	return manifest.sources.filter((source) => source.include.includes(skillName));
+}
+function buildMissingSkillError(skillName, options = {}) {
+	const matchingKeys = options.matchingKeys ?? [];
+	const details = options.sourceKey ? [`skill: ${skillName}`, `source: ${options.sourceKey}`] : [`skill: ${skillName}`];
+	if (matchingKeys.length > 0) details.push(`matching sources: ${matchingKeys.join(", ")}`);
+	return new CliError(options.sourceKey == null ? `Skill "${skillName}" is not declared in sources.yaml.` : `Skill "${skillName}" is not declared in source "${options.sourceKey}".`, { details });
+}
+function createManifest(repoPath, options = {}) {
+	return {
+		version: 1,
+		skillsRoot: DEFAULT_SKILLS_ROOT,
+		metadataFile: DEFAULT_METADATA_FILE,
+		managedBy: DEFAULT_MANAGED_BY,
+		remoteRepository: options.remoteRepository ?? path.basename(repoPath),
+		staleCleanup: true,
+		skillsCliVersion: DEFAULT_SKILLS_CLI_VERSION,
+		installAgent: DEFAULT_INSTALL_AGENT,
+		sources: options.sources ?? [],
+		manifestPath: path.join(repoPath, "sources.yaml"),
+		repoPath
+	};
+}
+function serialiseManifest(manifest) {
+	const lines = [
+		"# Managed by skillsbase CLI.",
+		"# Edit source entries to add or remove managed skills.",
+		`version: ${manifest.version}`,
+		`skillsRoot: ${quoteYamlString(manifest.skillsRoot)}`,
+		`metadataFile: ${quoteYamlString(manifest.metadataFile)}`,
+		`managedBy: ${quoteYamlString(manifest.managedBy)}`,
+		`remoteRepository: ${quoteYamlString(manifest.remoteRepository)}`,
+		`staleCleanup: ${manifest.staleCleanup ? "true" : "false"}`,
+		`skillsCliVersion: ${quoteYamlString(manifest.skillsCliVersion ?? "1.4.8")}`,
+		`installAgent: ${quoteYamlString(manifest.installAgent ?? "codex")}`,
+		"sources:"
+	];
+	for (const source of manifest.sources) {
+		lines.push(`  - key: ${quoteYamlString(source.key)}`);
+		lines.push(`    label: ${quoteYamlString(source.label)}`);
+		lines.push(`    kind: ${quoteYamlString(source.kind)}`);
+		lines.push(`    root: ${quoteYamlString(source.root)}`);
+		lines.push(`    targetPrefix: ${quoteYamlString(source.targetPrefix ?? "")}`);
+		lines.push("    include:");
+		for (const skillName of source.include ?? []) lines.push(`      - ${quoteYamlString(skillName)}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+function validateManifest(manifest) {
+	for (const key of [
+		"version",
+		"skillsRoot",
+		"metadataFile",
+		"managedBy",
+		"remoteRepository",
+		"staleCleanup",
+		"sources"
+	]) if (!(key in manifest)) throw new CliError(`Missing required manifest key: ${key}`, { details: ["Run `skillsbase init` to recreate the baseline contract."] });
+	if (!Array.isArray(manifest.sources) || typeof manifest.version !== "number" || typeof manifest.skillsRoot !== "string" || typeof manifest.metadataFile !== "string" || typeof manifest.managedBy !== "string" || typeof manifest.remoteRepository !== "string" || typeof manifest.staleCleanup !== "boolean") throw new CliError("Manifest `sources` must be a list.", { details: ["Repair `sources.yaml` and try again."] });
+	return {
+		version: manifest.version,
+		skillsRoot: manifest.skillsRoot,
+		metadataFile: manifest.metadataFile,
+		managedBy: manifest.managedBy,
+		remoteRepository: manifest.remoteRepository,
+		staleCleanup: manifest.staleCleanup,
+		skillsCliVersion: typeof manifest.skillsCliVersion === "string" ? manifest.skillsCliVersion : DEFAULT_SKILLS_CLI_VERSION,
+		installAgent: typeof manifest.installAgent === "string" ? manifest.installAgent : DEFAULT_INSTALL_AGENT,
+		sources: manifest.sources.map(validateSource),
+		manifestPath: typeof manifest.manifestPath === "string" ? manifest.manifestPath : "",
+		repoPath: typeof manifest.repoPath === "string" ? manifest.repoPath : "",
+		skillsRootPath: typeof manifest.skillsRootPath === "string" ? manifest.skillsRootPath : void 0
+	};
+}
+async function loadManifest(repoPath) {
+	const manifestPath = path.join(repoPath, "sources.yaml");
+	if (!await pathExists(manifestPath)) throw new CliError("Missing `sources.yaml`.", { details: [`Repository: ${repoPath}`, "Run `skillsbase init` first, then retry the command."] });
+	const text = await promises.readFile(manifestPath, "utf8");
+	const manifest = { sources: [] };
+	const lines = text.split(/\r?\n/);
+	let currentSource = null;
+	let currentListKey = null;
+	for (const [index, rawLine] of lines.entries()) {
+		const line = rawLine.replace(/\s+$/, "");
+		const lineNumber = index + 1;
+		if (line.length === 0 || line.trimStart().startsWith("#")) continue;
+		const topLevelMatch = /^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/.exec(line);
+		if (topLevelMatch && !line.startsWith(" ")) {
+			const [, key, value] = topLevelMatch;
+			if (key === "sources") {
+				currentSource = null;
+				currentListKey = null;
+			} else manifest[key] = parseScalar(value);
+			continue;
+		}
+		const sourceStartMatch = /^  - key:\s*(.+)$/.exec(line);
+		if (sourceStartMatch) {
+			currentSource = {
+				key: String(parseScalar(sourceStartMatch[1])),
+				include: []
+			};
+			manifest.sources.push(currentSource);
+			currentListKey = null;
+			continue;
+		}
+		const sourcePropertyMatch = /^    ([A-Za-z][A-Za-z0-9]*):\s*(.*)$/.exec(line);
+		if (sourcePropertyMatch && currentSource) {
+			const [, key, value] = sourcePropertyMatch;
+			if (value.length === 0) {
+				currentSource[key] = [];
+				currentListKey = key;
+			} else {
+				currentSource[key] = parseScalar(value);
+				currentListKey = null;
+			}
+			continue;
+		}
+		const listItemMatch = /^      - (.+)$/.exec(line);
+		if (listItemMatch && currentSource && currentListKey) {
+			const listValue = currentSource[currentListKey];
+			if (!Array.isArray(listValue)) throw new CliError(`Invalid list state for "${currentListKey}" at line ${lineNumber}.`);
+			listValue.push(parseScalar(listItemMatch[1]));
+			continue;
+		}
+		throw new CliError(`Unsupported sources.yaml syntax at line ${lineNumber}.`, { details: [rawLine] });
+	}
+	const validated = validateManifest(manifest);
+	return {
+		...validated,
+		manifestPath,
+		repoPath,
+		skillsRootPath: path.join(repoPath, validated.skillsRoot)
+	};
+}
+async function saveManifest(manifest) {
+	const nextText = serialiseManifest(manifest);
+	await promises.writeFile(manifest.manifestPath, nextText, "utf8");
+}
+function buildManifestEntries(manifest, repoPath = manifest.repoPath) {
+	const entries = [];
+	for (const source of manifest.sources) {
+		const resolvedSourceRoot = resolveSourceRoot(repoPath, source);
+		for (const originalName of source.include ?? []) {
+			const targetName = `${source.targetPrefix ?? ""}${originalName}`;
+			entries.push({
+				sourceKey: source.key,
+				sourceLabel: source.label,
+				sourceKind: source.kind,
+				remoteSource: isRemoteRepositorySource(source),
+				sourceRoot: source.root,
+				sourcePath: buildSourcePath(source, originalName),
+				resolvedSourceRoot,
+				resolvedSourcePath: resolveSourcePath(repoPath, source, originalName),
+				originalName,
+				targetName,
+				targetPath: path.join(repoPath, manifest.skillsRoot, targetName),
+				targetPathRelative: toPosix(path.join(manifest.skillsRoot, targetName))
+			});
+		}
+	}
+	const collisions = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const keys = collisions.get(entry.targetName) ?? [];
+		keys.push(entry.sourceKey);
+		collisions.set(entry.targetName, keys);
+	}
+	const duplicateTargets = [...collisions.entries()].filter(([, keys]) => keys.length > 1);
+	if (duplicateTargets.length > 0) throw new CliError(`Manifest target-name collision detected: ${duplicateTargets.map(([targetName, keys]) => `${targetName} (${keys.join(", ")})`).join(", ")}`, { details: ["Adjust `targetPrefix` or `include` entries in `sources.yaml`."] });
+	return entries.sort((left, right) => left.targetName.localeCompare(right.targetName));
+}
+function addSkillToManifest(manifest, skillName, options = {}) {
+	assertManifestHasSources(manifest);
+	const selectedSource = options.sourceKey == null ? manifest.sources[0] : findSourceByKey(manifest, options.sourceKey);
+	return cloneManifestWithSources(manifest, manifest.sources.map((source) => {
+		if (source.key !== selectedSource.key) return source;
+		return {
+			...source,
+			include: sortInclude(new Set(source.include ?? []).add(skillName))
+		};
+	}));
+}
+function removeSkillFromManifest(manifest, skillName, options = {}) {
+	assertManifestHasSources(manifest);
+	const selectedSource = options.sourceKey == null ? null : findSourceByKey(manifest, options.sourceKey);
+	if (selectedSource != null) {
+		if (!selectedSource.include.includes(skillName)) {
+			const matchingKeys = findSourcesBySkill(manifest, skillName).map((source) => source.key);
+			throw buildMissingSkillError(skillName, {
+				sourceKey: selectedSource.key,
+				matchingKeys
+			});
+		}
+		return cloneManifestWithSources(manifest, manifest.sources.map((source) => {
+			if (source.key !== selectedSource.key) return source;
+			return {
+				...source,
+				include: sortInclude(source.include.filter((candidate) => candidate !== skillName))
+			};
+		}));
+	}
+	const matchingSources = findSourcesBySkill(manifest, skillName);
+	if (matchingSources.length === 0) throw buildMissingSkillError(skillName);
+	if (matchingSources.length > 1) {
+		const matchingKeys = matchingSources.map((source) => source.key).sort((left, right) => left.localeCompare(right));
+		throw new CliError(`Skill "${skillName}" is declared in multiple sources.`, { details: [`matching sources: ${matchingKeys.join(", ")}`, `Use \`skillsbase remove ${skillName} --source <key>\` to disambiguate.`] });
+	}
+	const [uniqueSource] = matchingSources;
+	return cloneManifestWithSources(manifest, manifest.sources.map((source) => {
+		if (source.key !== uniqueSource.key) return source;
+		return {
+			...source,
+			include: sortInclude(source.include.filter((candidate) => candidate !== skillName))
+		};
+	}));
+}
+function buildMetadata(manifest, entry, installRecord) {
+	return {
+		schemaVersion: 1,
+		managed: true,
+		managedBy: manifest.managedBy,
+		sourceKey: entry.sourceKey,
+		sourceKind: entry.sourceKind,
+		sourceLabel: entry.sourceLabel,
+		sourceRoot: entry.sourceRoot,
+		sourcePath: entry.sourcePath,
+		originalName: entry.originalName,
+		targetName: entry.targetName,
+		targetPath: entry.targetPathRelative,
+		remoteRepository: manifest.remoteRepository,
+		installAgent: manifest.installAgent,
+		installReference: installRecord.installReference,
+		installedMetadata: installRecord.installedMetadata,
+		files: [...installRecord.files].sort((left, right) => left.localeCompare(right))
+	};
+}
+//#endregion
+//#region src/lib/installer.ts
+var execFile$1 = promisify(execFile);
+var INSTALL_TIMEOUT_MS = 18e4;
+var REMOTE_INSTALL_RETRIES = 3;
+var NPM_ENV_KEYS_TO_UNSET = [
+	"INIT_CWD",
+	"npm_command",
+	"npm_config_local_prefix",
+	"npm_config_prefix",
+	"npm_execpath",
+	"npm_lifecycle_event",
+	"npm_lifecycle_script",
+	"npm_package_json",
+	"npm_prefix"
+];
+function toInstallReference(entry) {
+	if (entry.remoteSource) return entry.sourcePath;
+	if (path.isAbsolute(entry.sourcePath) || entry.sourcePath.startsWith(`.${path.sep}`) || entry.sourcePath === ".") return entry.sourcePath;
+	return `.${path.sep}${entry.sourcePath}`;
+}
+function buildNpxArgs(manifest, subcommand, extraArgs) {
+	return [
+		"--yes",
+		`skills@${manifest.skillsCliVersion}`,
+		subcommand,
+		...extraArgs
+	];
+}
+function renderExecFailure(error) {
+	if (error instanceof Error) {
+		const execError = error;
+		return execError.stderr ?? execError.stdout ?? execError.message;
+	}
+	return String(error);
+}
+async function execSkillsAdd(repoPath, manifest, installReference, options) {
+	const childEnv = { ...options.env ?? process.env };
+	for (const key of NPM_ENV_KEYS_TO_UNSET) delete childEnv[key];
+	childEnv.INIT_CWD = repoPath;
+	await execFile$1("npx", buildNpxArgs(manifest, "add", [
+		installReference,
+		"--agent",
+		manifest.installAgent,
+		"--copy",
+		"-y"
+	]), {
+		cwd: repoPath,
+		env: childEnv,
+		maxBuffer: 16 * 1024 * 1024,
+		timeout: INSTALL_TIMEOUT_MS
+	});
+}
+async function installIntoCurrentRepository(repoPath, manifest, entry, options = {}) {
+	const installReference = toInstallReference(entry);
+	const installPath = path.join(repoPath, ".agents", "skills", entry.originalName);
+	const lockPath = path.join(repoPath, "skills-lock.json");
+	const snapshot = {
+		installPath,
+		lockPath,
+		installTree: await snapshotTree(installPath),
+		lockText: await readFileIfExists(lockPath),
+		installReference
+	};
+	const attempts = entry.remoteSource ? REMOTE_INSTALL_RETRIES : 1;
+	const failures = [];
+	for (let attempt = 1; attempt <= attempts; attempt += 1) try {
+		await execSkillsAdd(repoPath, manifest, installReference, options);
+		failures.length = 0;
+		break;
+	} catch (error) {
+		failures.push(`attempt ${attempt}/${attempts}: ${renderExecFailure(error)}`);
+		await restoreSnapshot(snapshot);
+		if (attempt === attempts) break;
+	}
+	if (failures.length > 0) throw new CliError(`skills install failed for ${entry.originalName}.`, { details: failures });
+	if (!await pathExists(installPath)) throw new CliError(`skills install did not create ${path.relative(repoPath, installPath)}.`, { details: ["The `npx skills` install output was not in the expected current-repository shape."] });
+	return {
+		installPath,
+		lockPath,
+		installReference,
+		snapshot
+	};
+}
+async function cleanupInstalledSkill(repoPath, _manifest, entry, installState, _options = {}) {
+	try {
+		await restoreSnapshot(installState.snapshot);
+		await removeIfEmptyUpward(path.join(repoPath, ".agents", "skills"), repoPath);
+	} catch (restoreError) {
+		const restoreMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
+		throw new CliError(`Cleanup failed for ${entry.originalName}.`, { details: [restoreMessage] });
+	}
+}
+async function snapshotTree(rootPath) {
+	if (!await pathExists(rootPath)) return null;
+	const entries = await promises.readdir(rootPath, { withFileTypes: true });
+	const tree = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const absolutePath = path.join(rootPath, entry.name);
+		if (entry.isDirectory()) {
+			const nested = await snapshotTree(absolutePath);
+			if (!nested) continue;
+			for (const [relativePath, content] of nested.entries()) tree.set(path.join(entry.name, relativePath), content);
+			continue;
+		}
+		if (entry.isFile()) tree.set(entry.name, await promises.readFile(absolutePath));
+	}
+	return tree;
+}
+async function restoreSnapshot(snapshot) {
+	if (snapshot.installTree == null) await promises.rm(snapshot.installPath, {
+		recursive: true,
+		force: true
+	});
+	else {
+		await promises.rm(snapshot.installPath, {
+			recursive: true,
+			force: true
+		});
+		await promises.mkdir(snapshot.installPath, { recursive: true });
+		for (const [relativePath, content] of snapshot.installTree.entries()) {
+			const targetPath = path.join(snapshot.installPath, relativePath);
+			await promises.mkdir(path.dirname(targetPath), { recursive: true });
+			await promises.writeFile(targetPath, content);
+		}
+	}
+	if (snapshot.lockText == null) await promises.rm(snapshot.lockPath, { force: true });
+	else await promises.writeFile(snapshot.lockPath, snapshot.lockText, "utf8");
+	await removeIfEmptyUpward(path.dirname(snapshot.installPath), path.dirname(snapshot.lockPath));
+}
+//#endregion
+//#region src/lib/skill-converter.ts
+function rewriteSkillName(content, targetName) {
+	const frontmatterMatch = /^---\n([\s\S]*?)\n---/.exec(content);
+	if (!frontmatterMatch) throw new CliError("Installed SKILL.md is missing YAML frontmatter.", { details: ["The upstream skill must contain a valid `name` field."] });
+	if (!/^name:\s*.+$/m.test(frontmatterMatch[1])) throw new CliError("Installed SKILL.md frontmatter is missing a `name` field.");
+	const updatedFrontmatter = frontmatterMatch[1].replace(/^name:\s*.+$/m, `name: ${targetName}`);
+	return content.replace(frontmatterMatch[0], `---\n${updatedFrontmatter}\n---`);
+}
+async function convertInstalledSkill(_manifest, entry, installState) {
+	const installedPath = installState.installPath;
+	const skillPath = path.join(installedPath, "SKILL.md");
+	try {
+		await promises.access(skillPath);
+	} catch {
+		throw new CliError(`Installed skill is missing SKILL.md: ${entry.originalName}`);
+	}
+	const filePaths = await collectRelativeFiles(installedPath);
+	const outputTree = /* @__PURE__ */ new Map();
+	for (const relativePath of filePaths) {
+		if (relativePath === "hagicode-skill.json" || relativePath === ".skill-source.json") continue;
+		const absolutePath = path.join(installedPath, relativePath);
+		if (relativePath === "SKILL.md") {
+			const content = await promises.readFile(absolutePath, "utf8");
+			outputTree.set(relativePath, Buffer.from(rewriteSkillName(content, entry.targetName), "utf8"));
+			continue;
+		}
+		outputTree.set(relativePath, await promises.readFile(absolutePath));
+	}
+	const installedMetadataPath = path.join(installedPath, "hagicode-skill.json");
+	let installedMetadata;
+	try {
+		installedMetadata = JSON.parse(await promises.readFile(installedMetadataPath, "utf8"));
+	} catch {
+		installedMetadata = {
+			schemaVersion: 1,
+			source: entry.sourceRoot,
+			skillSlug: entry.originalName,
+			installReference: installState.installReference,
+			synthesizedBy: "skillsbase"
+		};
+	}
+	return {
+		files: [...outputTree.keys()].sort((left, right) => left.localeCompare(right)),
+		outputTree,
+		installedMetadata,
+		installReference: installState.installReference,
+		targetName: entry.targetName,
+		targetPath: entry.targetPath,
+		targetPathRelative: entry.targetPathRelative
+	};
+}
+//#endregion
+//#region src/lib/sync-engine.ts
+async function assertSourceState(entry, allowMissingSources) {
+	if (entry.remoteSource) return { skip: false };
+	if (!await pathExists(entry.resolvedSourceRoot)) {
+		if (allowMissingSources) return {
+			skip: true,
+			reason: `missing source root: ${entry.resolvedSourceRoot}`
+		};
+		throw new CliError(`Managed source root does not exist: ${entry.resolvedSourceRoot}`, { details: ["Use `skillsbase sync --allow-missing-sources` to skip missing roots."] });
+	}
+	if (!await pathExists(entry.resolvedSourcePath)) throw new CliError(`Managed skill is missing from source root: ${entry.resolvedSourcePath}`, { details: [`source: ${entry.sourceKey}`, `skill: ${entry.originalName}`] });
+	return { skip: false };
+}
+async function assertManagedTargetWritable(manifest, entry) {
+	if (!await pathExists(entry.targetPath)) return;
+	const metadataPath = path.join(entry.targetPath, manifest.metadataFile);
+	if (!await pathExists(metadataPath)) throw new CliError(`Refusing to overwrite unmanaged directory: ${entry.targetPathRelative}`, { details: ["Add metadata manually or remove the conflicting directory first."] });
+	const metadata = JSON.parse(await promises.readFile(metadataPath, "utf8"));
+	if (!metadata.managed || metadata.managedBy !== manifest.managedBy) throw new CliError(`Refusing to overwrite unmanaged directory: ${entry.targetPathRelative}`, { details: [`Found metadata managedBy=${JSON.stringify(metadata.managedBy)}`] });
+}
+async function snapshotTargetDirectory(targetPath) {
+	if (!await pathExists(targetPath)) return null;
+	return {
+		path: targetPath,
+		tree: await readTree(targetPath)
+	};
+}
+async function restoreTargetDirectory(snapshot) {
+	if (snapshot == null) return;
+	await writeTree(snapshot.path, snapshot.tree);
+}
+async function compareTarget(manifest, entry, desiredTree, desiredMetadata) {
+	if (!await pathExists(entry.targetPath)) return [`missing target directory: ${entry.targetPathRelative}`];
+	const actualFiles = (await collectRelativeFiles(entry.targetPath)).sort((left, right) => left.localeCompare(right));
+	const desiredFiles = [...desiredTree.keys(), manifest.metadataFile].sort((left, right) => left.localeCompare(right));
+	if (JSON.stringify(actualFiles) !== JSON.stringify(desiredFiles)) return [`file set drift: ${entry.targetPathRelative}`];
+	const actualTree = await readTree(entry.targetPath);
+	for (const [relativePath, buffer] of desiredTree.entries()) {
+		const actual = actualTree.get(relativePath);
+		if (!actual || !actual.equals(buffer)) return [`file content drift: ${entry.targetPathRelative}/${relativePath}`];
+	}
+	const metadataPath = path.join(entry.targetPath, manifest.metadataFile);
+	if (await promises.readFile(metadataPath, "utf8") !== stableJson(desiredMetadata)) return [`metadata drift: ${entry.targetPathRelative}/${manifest.metadataFile}`];
+	return [];
+}
+async function reconcileStaleTargets(repoPath, manifest, declaredTargets, check) {
+	const changes = [];
+	const skillsRootPath = path.join(repoPath, manifest.skillsRoot);
+	const existingDirectories = await listDirectories(skillsRootPath);
+	for (const directoryName of existingDirectories) {
+		if (declaredTargets.has(directoryName)) continue;
+		const candidatePath = path.join(skillsRootPath, directoryName);
+		const metadataPath = path.join(candidatePath, manifest.metadataFile);
+		if (!await pathExists(metadataPath)) continue;
+		const metadata = JSON.parse(await promises.readFile(metadataPath, "utf8"));
+		if (!metadata.managed || metadata.managedBy !== manifest.managedBy) continue;
+		if (check) {
+			changes.push(`stale managed directory: ${path.posix.join(manifest.skillsRoot, directoryName)}`);
+			continue;
+		}
+		await promises.rm(candidatePath, {
+			recursive: true,
+			force: true
+		});
+		changes.push(`removed stale: ${path.posix.join(manifest.skillsRoot, directoryName)}`);
+	}
+	return changes;
+}
+async function executeSync(options) {
+	const { repoPath, manifest, check, allowMissingSources, env } = options;
+	const entries = buildManifestEntries(manifest, repoPath);
+	const items = [];
+	const skipped = [];
+	const declaredTargets = new Set(entries.map((entry) => entry.targetName));
+	const preparedEntries = [];
+	const checkSnapshots = /* @__PURE__ */ new Map();
+	await ensureDirectory(path.join(repoPath, manifest.skillsRoot));
+	if (check) for (const entry of entries) checkSnapshots.set(entry.targetPath, await snapshotTargetDirectory(entry.targetPath));
+	for (const entry of entries) {
+		if ((await assertSourceState(entry, allowMissingSources)).skip) {
+			skipped.push(`${entry.sourceKey}: ${entry.originalName}`);
+			continue;
+		}
+		const installState = await installIntoCurrentRepository(repoPath, manifest, entry, { env });
+		try {
+			const converted = await convertInstalledSkill(manifest, entry, installState);
+			const metadata = buildMetadata(manifest, entry, {
+				installReference: converted.installReference,
+				installedMetadata: converted.installedMetadata,
+				files: converted.files
+			});
+			preparedEntries.push({
+				entry,
+				converted,
+				metadata
+			});
+		} finally {
+			await cleanupInstalledSkill(repoPath, manifest, entry, installState, { env });
+		}
+	}
+	if (check) for (const prepared of preparedEntries) {
+		await restoreTargetDirectory(checkSnapshots.get(prepared.entry.targetPath) ?? null);
+		items.push(...await compareTarget(manifest, prepared.entry, prepared.converted.outputTree, prepared.metadata));
+	}
+	else for (const prepared of preparedEntries) {
+		await assertManagedTargetWritable(manifest, prepared.entry);
+		const nextTree = new Map(prepared.converted.outputTree);
+		nextTree.set(manifest.metadataFile, Buffer.from(stableJson(prepared.metadata), "utf8"));
+		await writeTree(prepared.entry.targetPath, nextTree);
+		items.push(`synced: ${prepared.entry.targetPathRelative}`);
+	}
+	items.push(...await reconcileStaleTargets(repoPath, manifest, declaredTargets, check));
+	if (skipped.length > 0) items.push(`skipped missing sources: ${skipped.join(", ")}`);
+	const driftDetected = check && items.some((item) => !item.startsWith("skipped "));
+	return {
+		command: "sync",
+		title: check ? "skillsbase sync --check" : "skillsbase sync",
+		repository: repoPath,
+		exitCode: driftDetected ? 1 : 0,
+		schema: "spec-driven",
+		items: items.length > 0 ? items : [check ? "no drift detected" : "nothing to sync"],
+		nextSteps: driftDetected ? ["skillsbase sync"] : []
+	};
+}
+//#endregion
+//#region src/commands/add.ts
+async function runAddCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	const sourceFlag = typeof context.flags.source === "string" ? context.flags.source : void 0;
+	const repoPath = path.resolve(repoFlag ?? context.cwd);
+	const skillName = context.args[0];
+	if (!skillName) throw new CliError("`skillsbase add` requires a skill name.", { details: ["Usage: `skillsbase add <skill-name> [--source <key>]`."] });
+	const nextManifest = addSkillToManifest(await loadManifest(repoPath), skillName, { sourceKey: sourceFlag });
+	await saveManifest(nextManifest);
+	const result = await executeSync({
+		repoPath,
+		manifest: nextManifest,
+		env: context.env,
+		check: false,
+		allowMissingSources: context.flags["allow-missing-sources"] === true
+	});
+	return {
+		...result,
+		title: `skillsbase add ${skillName}`,
+		items: [`manifest updated: ${path.relative(repoPath, nextManifest.manifestPath) || "sources.yaml"}`, ...result.items]
+	};
+}
+//#endregion
+//#region src/lib/templates.ts
+var moduleDir = path.dirname(fileURLToPath(import.meta.url));
+var templateRootCandidates = [path.resolve(moduleDir, "..", "..", "templates"), path.resolve(moduleDir, "..", "templates")];
+async function resolveTemplateRoot() {
+	for (const candidate of templateRootCandidates) if (await pathExists(candidate)) return candidate;
+	throw new CliError("Unable to locate the bundled templates directory.");
+}
+async function renderTemplate(relativePath, variables) {
+	const templateRoot = await resolveTemplateRoot();
+	const templatePath = path.join(templateRoot, relativePath);
+	let content = await promises.readFile(templatePath, "utf8");
+	for (const [key, value] of Object.entries(variables)) content = content.replaceAll(`{{${key}}}`, value);
+	return content;
+}
+function managedMarkerFor(targetPath) {
+	if (targetPath.endsWith(".md")) return `<!-- ${MANAGED_SIGNATURE}. -->`;
+	return `# ${MANAGED_SIGNATURE}.`;
+}
+function isManagedContent(targetPath, content) {
+	return content.includes(managedMarkerFor(targetPath));
+}
+async function writeManagedFile(targetPath, content, options = {}) {
+	const marker = managedMarkerFor(targetPath);
+	if (!content.includes(marker)) throw new CliError(`Managed template is missing its marker: ${targetPath}`);
+	const current = await pathExists(targetPath) ? await promises.readFile(targetPath, "utf8") : null;
+	if (current === content) return {
+		status: "unchanged",
+		path: targetPath
+	};
+	if (current != null && !isManagedContent(targetPath, current) && !options.force) throw new CliError(`Refusing to overwrite unmanaged file: ${targetPath}`, { details: ["Use `--force` to replace the conflicting file."] });
+	await promises.mkdir(path.dirname(targetPath), { recursive: true });
+	await promises.writeFile(targetPath, content, "utf8");
+	return {
+		status: current == null ? "created" : "updated",
+		path: targetPath
+	};
+}
+async function writeGithubActions(repoPath, options = {}) {
+	const kind = options.kind ?? "workflow";
+	const variables = { NODE_VERSION: DEFAULT_NODE_VERSION };
+	const targets = [];
+	if (kind === "workflow" || kind === "all") targets.push({
+		relativePath: path.join(".github", "workflows", "skills-sync.yml"),
+		template: path.join("workflows", "skills-sync.yml")
+	}, {
+		relativePath: path.join(".github", "workflows", "skills-manage.yml"),
+		template: path.join("workflows", "skills-manage.yml")
+	});
+	if (kind === "workflow" || kind === "action" || kind === "all") targets.push({
+		relativePath: path.join(".github", "actions", "skillsbase-sync", "action.yml"),
+		template: path.join("actions", "skillsbase-sync", "action.yml")
+	}, {
+		relativePath: path.join(".github", "actions", "skillsbase-manage", "action.yml"),
+		template: path.join("actions", "skillsbase-manage", "action.yml")
+	});
+	if (targets.length === 0) throw new CliError(`Unsupported github_action kind: ${kind}`, { details: ["Supported values: workflow, action, all."] });
+	const items = [];
+	for (const target of targets) {
+		const content = await renderTemplate(target.template, variables);
+		const status = await writeManagedFile(path.join(repoPath, target.relativePath), content, { force: Boolean(options.force) });
+		items.push(`${status.status}: ${target.relativePath}`);
+	}
+	return {
+		command: "github_action",
+		title: `skillsbase github_action --kind ${kind}`,
+		repository: repoPath,
+		exitCode: 0,
+		items,
+		nextSteps: []
+	};
+}
+//#endregion
+//#region src/commands/github-action.ts
+async function runGithubActionCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	const kindFlag = typeof context.flags.kind === "string" ? context.flags.kind : void 0;
+	return writeGithubActions(path.resolve(repoFlag ?? context.cwd), {
+		kind: kindFlag ?? "workflow",
+		force: context.flags.force === true
+	});
+}
+//#endregion
+//#region src/lib/repo-init.ts
+function defaultRoots(options = {}) {
+	const home = os.homedir();
+	return {
+		firstPartyRoot: path.resolve(options.firstPartyRoot ?? path.join(home, ".agents", "skills")),
+		systemRoot: path.resolve(options.systemRoot ?? path.join(home, ".codex", "skills", ".system"))
+	};
+}
+async function createDefaultSource(key, label, kind, root, targetPrefix) {
+	return {
+		key,
+		label,
+		kind,
+		root,
+		targetPrefix,
+		include: await pathExists(root) ? await listDirectories(root) : []
+	};
+}
+async function initialiseRepository(repoPath, options = {}) {
+	await ensureDirectory(repoPath);
+	const roots = defaultRoots(options);
+	const manifestPath = path.join(repoPath, "sources.yaml");
+	const createdItems = [];
+	const preservedItems = [];
+	if (!await pathExists(manifestPath)) {
+		const sources = [await createDefaultSource("first-party", "First-party local skills", "first-party", roots.firstPartyRoot, ""), await createDefaultSource("system", "Mirrored system skills", "mirrored-system", roots.systemRoot, "system-")];
+		await saveManifest(createManifest(repoPath, {
+			remoteRepository: options.remoteRepository ?? path.basename(repoPath),
+			sources
+		}));
+		createdItems.push("sources.yaml");
+	} else preservedItems.push("sources.yaml");
+	await ensureDirectory(path.join(repoPath, "skills"));
+	await ensureDirectory(path.join(repoPath, "docs"));
+	await ensureDirectory(path.join(repoPath, ".github", "actions", "skillsbase-sync"));
+	await ensureDirectory(path.join(repoPath, ".github", "workflows"));
+	const writeStatuses = [];
+	for (const file of [{
+		relativePath: path.join("skills", "README.md"),
+		template: "skills/README.md",
+		variables: {}
+	}, {
+		relativePath: path.join("docs", "maintainer-workflow.md"),
+		template: "docs/maintainer-workflow.md",
+		variables: {}
+	}]) {
+		const content = await renderTemplate(file.template, file.variables);
+		const status = await writeManagedFile(path.join(repoPath, file.relativePath), content, { force: Boolean(options.force) });
+		writeStatuses.push(`${status.status}: ${file.relativePath}`);
+	}
+	const actionResult = await writeGithubActions(repoPath, {
+		kind: "all",
+		force: Boolean(options.force)
+	});
+	return {
+		command: "init",
+		title: "skillsbase init",
+		repository: repoPath,
+		exitCode: 0,
+		schema: "spec-driven",
+		items: [
+			...createdItems.map((item) => `created: ${item}`),
+			...preservedItems.map((item) => `preserved: ${item}`),
+			...writeStatuses,
+			...actionResult.items ?? []
+		],
+		nextSteps: ["skillsbase sync"]
+	};
+}
+//#endregion
+//#region src/commands/init.ts
+async function runInitCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	return initialiseRepository(path.resolve(repoFlag ?? context.cwd), {
+		firstPartyRoot: typeof context.flags["first-party-root"] === "string" ? context.flags["first-party-root"] : void 0,
+		systemRoot: typeof context.flags["system-root"] === "string" ? context.flags["system-root"] : void 0,
+		remoteRepository: typeof context.flags["remote-repository"] === "string" ? context.flags["remote-repository"] : void 0,
+		force: context.flags.force === true
+	});
+}
+//#endregion
+//#region src/commands/remove.ts
+async function runRemoveCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	const sourceFlag = typeof context.flags.source === "string" ? context.flags.source : void 0;
+	const repoPath = path.resolve(repoFlag ?? context.cwd);
+	const skillName = context.args[0];
+	if (!skillName) throw new CliError("`skillsbase remove` requires a skill name.", { details: ["Usage: `skillsbase remove <skill-name> [--source <key>]`."] });
+	const nextManifest = removeSkillFromManifest(await loadManifest(repoPath), skillName, { sourceKey: sourceFlag });
+	await saveManifest(nextManifest);
+	const result = await executeSync({
+		repoPath,
+		manifest: nextManifest,
+		env: context.env,
+		check: false,
+		allowMissingSources: context.flags["allow-missing-sources"] === true
+	});
+	return {
+		...result,
+		command: "remove",
+		title: `skillsbase remove ${skillName}`,
+		items: [`manifest updated: ${path.relative(repoPath, nextManifest.manifestPath) || "sources.yaml"}`, ...result.items]
+	};
+}
+//#endregion
+//#region src/commands/sync.ts
+async function runSyncCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	const repoPath = path.resolve(repoFlag ?? context.cwd);
+	return executeSync({
+		repoPath,
+		manifest: await loadManifest(repoPath),
+		check: context.flags.check === true,
+		allowMissingSources: context.flags["allow-missing-sources"] === true,
+		env: context.env
+	});
+}
+//#endregion
+//#region src/lib/parse-argv.ts
+var booleanFlags = new Set([
+	"help",
+	"version",
+	"check",
+	"allow-missing-sources",
+	"force"
+]);
+function parseArgv(argv) {
+	const result = {
+		command: null,
+		args: [],
+		flags: {},
+		help: false,
+		version: false
+	};
+	let index = 0;
+	while (index < argv.length) {
+		const token = argv[index];
+		if (result.command == null && !token.startsWith("-")) {
+			result.command = token;
+			index += 1;
+			continue;
+		}
+		if (token === "--help" || token === "-h") {
+			result.help = true;
+			index += 1;
+			continue;
+		}
+		if (token === "--version" || token === "-v") {
+			result.version = true;
+			index += 1;
+			continue;
+		}
+		if (token.startsWith("--")) {
+			const [flagName, inlineValue] = token.slice(2).split("=", 2);
+			if (booleanFlags.has(flagName)) {
+				result.flags[flagName] = inlineValue == null ? true : inlineValue !== "false";
+				index += 1;
+				continue;
+			}
+			const nextValue = inlineValue ?? argv[index + 1];
+			if (nextValue == null) throw new CliError(`Missing value for --${flagName}.`);
+			result.flags[flagName] = nextValue;
+			index += inlineValue == null ? 2 : 1;
+			continue;
+		}
+		if (token.startsWith("-")) throw new CliError(`Unsupported short option: ${token}`, { details: ["Use long-form flags for command options."] });
+		if (result.command != null) result.args.push(token);
+		index += 1;
+	}
+	return result;
+}
+//#endregion
+//#region src/cli.ts
+var commandMap = new Map([
+	["init", runInitCommand],
+	["sync", runSyncCommand],
+	["add", runAddCommand],
+	["remove", runRemoveCommand],
+	["github_action", runGithubActionCommand],
+	["github-action", runGithubActionCommand]
+]);
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+async function runCli(argv, environment = {}) {
+	const io = {
+		stdout: environment.stdout ?? process.stdout,
+		stderr: environment.stderr ?? process.stderr
+	};
+	const cwd = path.resolve(environment.cwd ?? process.cwd());
+	const env = {
+		...process.env,
+		...environment.env ?? {}
+	};
+	try {
+		const parsed = parseArgv(argv);
+		if (parsed.help || !parsed.command) {
+			printCommandUsage(io.stdout);
+			return 0;
+		}
+		if (parsed.version) {
+			io.stdout.write("skillsbase 0.1.0\n");
+			return 0;
+		}
+		const command = commandMap.get(parsed.command);
+		if (!command) throw new CliError(`Unknown command: ${parsed.command}`, {
+			exitCode: 1,
+			details: ["Use `skillsbase --help` to view supported commands."]
+		});
+		const result = await command({
+			cwd,
+			env,
+			io,
+			command: parsed.command,
+			args: parsed.args,
+			flags: parsed.flags,
+			rawArgv: argv
+		});
+		printCommandResult(result, io.stdout);
+		return result.exitCode ?? 0;
+	} catch (error) {
+		if (error instanceof CliError) {
+			printCommandResult({
+				command: "error",
+				title: error.message,
+				repository: cwd,
+				exitCode: error.exitCode ?? 1,
+				items: error.details ?? [],
+				nextSteps: error.nextSteps ?? []
+			}, io.stderr);
+			return error.exitCode ?? 1;
+		}
+		printCommandResult({
+			command: "error",
+			title: getErrorMessage(error),
+			repository: cwd,
+			exitCode: 1
+		}, io.stderr);
+		return 1;
+	}
+}
+//#endregion
+//#region src/cli-entry.ts
+var exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);
+//#endregion