tunestra 0.0.0 → 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,1881 @@
+#!/usr/bin/env node
+import { t as VERSION } from "./src-DSbrKtiC.mjs";
+import { Command } from "@commander-js/extra-typings";
+import pc from "picocolors";
+import { copyFile, lstat, mkdir, readFile, readdir, readlink, rename, rm, rmdir, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { glob } from "tinyglobby";
+import { prettifyError, z } from "zod";
+import { parse } from "yaml";
+import { downloadTemplate } from "giget";
+import { createHash } from "node:crypto";
+//#region src/shared/constants/files.ts
+/** Preset manifest, in the root of every preset. */
+const PRESET_MANIFEST = "tunestra.preset.yaml";
+/** Project config, in the root of the project. */
+const PROJECT_CONFIG = "tunestra.yaml";
+/** Project artifacts: the same layout as a preset. */
+const PROJECT_DIR = ".tunestra";
+/** Main instructions of a level, and the index that tunestra generates. */
+const INSTRUCTIONS_FILE = "AGENTS.md";
+//#endregion
+//#region src/shared/constants/output.ts
+/** What the plan asks to put at a path in the project. */
+const OutputKind = {
+	/** A file with the given content. */
+	File: "file",
+	/** A copy of a source file, byte for byte. */
+	Copy: "copy",
+	/** A relative symbolic link. */
+	Symlink: "symlink"
+};
+/** First line of every generated markdown file; tunestra recognizes its files by it. */
+const GENERATED_MARKER = "<!-- Generated by tunestra";
+const GENERATED_NOTICE = `${GENERATED_MARKER}. Do not edit: change the sources and run \`tunestra setup\`. -->`;
+/** Shared output that any agent can read. */
+const AGENTS_DIR = ".agents";
+/** Rules for every agent, ordered from specific to general by their file names. */
+const AGENTS_RULES_DIR = `${AGENTS_DIR}/rules`;
+/** Skills in the Agent Skills layout that several agents read. */
+const AGENTS_SKILLS_DIR = `${AGENTS_DIR}/skills`;
+/** What tunestra generated last time. */
+const STATE_DIR = ".tunestra/state";
+const GITIGNORE_FILE = ".gitignore";
+/** The registry of outputs from the last setup. */
+const STATE_FILE = `${STATE_DIR}/outputs.json`;
+/** Repositories of git sources, downloaded on every setup. */
+const SOURCES_DIR = `${STATE_DIR}/sources`;
+//#endregion
+//#region src/shared/errors/tunestra-error.ts
+/** An error caused by the user's input: a broken manifest, a missing file and so on. */
+var TunestraError = class extends Error {
+	name = "TunestraError";
+	/** Every problem behind this error; one item for a simple error. */
+	problems;
+	constructor(message, problems = [message]) {
+		super(message);
+		this.problems = problems;
+	}
+};
+//#endregion
+//#region src/shared/errors/create-problems-error.ts
+/** Builds one error from several problems, so that the user can fix them all at once. */
+function createProblemsError(problems) {
+	const [firstProblem] = problems;
+	if (problems.length === 1 && typeof firstProblem === "string") return new TunestraError(firstProblem);
+	const list = problems.map(formatProblem).join("\n\n");
+	return new TunestraError(`Found ${problems.length} problems:\n\n${list}`, problems);
+}
+/** Numbers a problem and indents its next lines under the number. */
+function formatProblem(problem, index) {
+	const number = `${index + 1}. `;
+	const indent = " ".repeat(number.length);
+	const [firstLine, ...nextLines] = problem.trimEnd().split("\n");
+	const indentedLines = nextLines.map((line) => indentLine(line, indent));
+	return [`${number}${firstLine}`, ...indentedLines].join("\n");
+}
+/** Leaves empty lines empty, so that the message has no trailing spaces. */
+function indentLine(line, indent) {
+	const text = line.trimEnd();
+	if (text === "") return text;
+	return `${indent}${text}`;
+}
+//#endregion
+//#region src/shared/utils/fs.ts
+/** A missing path is `false`; any other failure, like no permission, is thrown. */
+async function checkExists(path) {
+	try {
+		await stat(path);
+		return true;
+	} catch (error) {
+		if (isMissingPathError(error)) return false;
+		throw error;
+	}
+}
+function isMissingPathError(error) {
+	if (error instanceof Error) return "code" in error && error.code === "ENOENT";
+	return false;
+}
+/**
+* Files matching the pattern, without dotfiles. Sorted so that the output does not depend
+* on the file system.
+*/
+async function listFiles(dir, pattern) {
+	return (await glob(pattern, {
+		cwd: dir,
+		onlyFiles: true
+	})).sort();
+}
+/** Every file in the directory, dotfiles included, sorted. */
+async function listAllFiles(dir) {
+	return (await glob("**/*", {
+		cwd: dir,
+		dot: true,
+		onlyFiles: true
+	})).sort();
+}
+/** What is at a path, without following a symbolic link. */
+const PathType = {
+	Missing: "missing",
+	Symlink: "symlink",
+	Directory: "directory",
+	File: "file"
+};
+async function getPathType(path) {
+	try {
+		const stats = await lstat(path);
+		const isSymlink = stats.isSymbolicLink();
+		const isDirectory = stats.isDirectory();
+		if (isSymlink) return PathType.Symlink;
+		if (isDirectory) return PathType.Directory;
+		return PathType.File;
+	} catch (error) {
+		if (isMissingPathError(error)) return PathType.Missing;
+		throw error;
+	}
+}
+/** The text of a file, or `undefined` when there is no such file. */
+async function readFileIfExists(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (isMissingPathError(error)) return;
+		throw error;
+	}
+}
+//#endregion
+//#region src/shared/constants/agents.ts
+/** Agents that tunestra generates configuration for. */
+const Agent = { Claude: "claude" };
+//#endregion
+//#region src/init/render-config.ts
+const EXTENDS_EXAMPLE = "#   - github:<owner>/<repo>/<path>#<ref>";
+/** The first tunestra.yaml of a project, with a hint when there are no presets yet. */
+function renderConfig(presets) {
+	const hasPresets = presets.length > 0;
+	const presetLines = presets.map((preset) => `  - ${JSON.stringify(preset)}`);
+	return [
+		"# tunestra: https://github.com/sensetive5/tunestra",
+		"# Presets, from general to specific:",
+		...hasPresets ? ["extends:", ...presetLines] : ["extends: []", EXTENDS_EXAMPLE],
+		"agents:",
+		`  - ${Agent.Claude}`,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/init/run-init.ts
+const CLAUDE_FILE$1 = "CLAUDE.md";
+const CLAUDE_RULE = `${PROJECT_DIR}/rules/claude-md.md`;
+const PROJECT_INSTRUCTIONS = `${PROJECT_DIR}/${INSTRUCTIONS_FILE}`;
+const CLAUDE_IMPORT = `@${INSTRUCTIONS_FILE}`;
+/**
+* Creates tunestra.yaml. Hand-written AGENTS.md and CLAUDE.md become sources in .tunestra/,
+* because setup will generate both files from now on.
+*/
+async function runInit(projectDir, options) {
+	const configPath = join(projectDir, PROJECT_CONFIG);
+	const agentsPath = join(projectDir, INSTRUCTIONS_FILE);
+	const claudePath = join(projectDir, CLAUDE_FILE$1);
+	const hasConfig = await checkExists(configPath);
+	const agentsContent = await readHandWritten(agentsPath);
+	const claudeContent = await readHandWritten(claudePath);
+	const problems = await findConflicts(projectDir, hasConfig, agentsContent, claudeContent);
+	if (problems.length > 0) throw createProblemsError(problems);
+	const steps = [];
+	const warnings = [];
+	if (typeof agentsContent === "string") {
+		await moveFile(projectDir, INSTRUCTIONS_FILE, PROJECT_INSTRUCTIONS);
+		steps.push(`Moved ${INSTRUCTIONS_FILE} to ${PROJECT_INSTRUCTIONS}`);
+	}
+	if (typeof claudeContent === "string") {
+		const onlyImportsAgents = claudeContent.trim() === CLAUDE_IMPORT;
+		const hasImports = claudeContent.includes("@");
+		if (onlyImportsAgents) {
+			await rm(claudePath);
+			steps.push(`Removed ${CLAUDE_FILE$1}: it only imported ${INSTRUCTIONS_FILE}`);
+		} else {
+			await moveFile(projectDir, CLAUDE_FILE$1, CLAUDE_RULE);
+			steps.push(`Moved ${CLAUDE_FILE$1} to ${CLAUDE_RULE}`);
+			if (hasImports) warnings.push(`${CLAUDE_RULE} may have @imports; their paths are relative to the old place, so check them`);
+		}
+	}
+	const config = renderConfig(options.presets);
+	await writeFile(configPath, config);
+	steps.push(`Created ${PROJECT_CONFIG}`);
+	return {
+		steps,
+		warnings
+	};
+}
+/** The text of a file that people wrote; a file that tunestra generated does not count. */
+async function readHandWritten(path) {
+	const content = await readFileIfExists(path);
+	if (content?.startsWith("<!-- Generated by tunestra") === true) return;
+	return content;
+}
+async function findConflicts(projectDir, hasConfig, agentsContent, claudeContent) {
+	const problems = [];
+	const instructionsPath = join(projectDir, PROJECT_INSTRUCTIONS);
+	const claudeRulePath = join(projectDir, CLAUDE_RULE);
+	const hasInstructions = await checkExists(instructionsPath);
+	const hasClaudeRule = await checkExists(claudeRulePath);
+	if (hasConfig) problems.push(`${PROJECT_CONFIG} already exists. Run tunestra setup instead`);
+	if (typeof agentsContent === "string" && hasInstructions) problems.push(`${PROJECT_INSTRUCTIONS} already exists, so ${INSTRUCTIONS_FILE} cannot move there`);
+	if (typeof claudeContent === "string" && hasClaudeRule) problems.push(`${CLAUDE_RULE} already exists, so ${CLAUDE_FILE$1} cannot move there`);
+	return problems;
+}
+async function moveFile(projectDir, from, to) {
+	const fromPath = join(projectDir, from);
+	const toPath = join(projectDir, to);
+	const toDir = dirname(toPath);
+	await mkdir(toDir, { recursive: true });
+	await rename(fromPath, toPath);
+}
+//#endregion
+//#region src/cli/commands/init.ts
+async function describeInit(projectDir, options) {
+	const report = await runInit(projectDir, options);
+	const check = pc.green("✔");
+	const warningIcon = pc.yellow("⚠");
+	const steps = report.steps.map((step) => `${check} ${step}`);
+	const warnings = report.warnings.map((warning) => `${warningIcon} ${warning}`);
+	const nextStep = options.presets.length > 0 ? "Next: run tunestra setup." : "Next: add presets to extends in tunestra.yaml, then run tunestra setup.";
+	return [
+		...steps,
+		...warnings,
+		"",
+		nextStep
+	].join("\n");
+}
+//#endregion
+//#region src/shared/constants/levels.ts
+/** Levels of a shared preset, from specific to general. */
+const PresetLevel = {
+	Team: "team",
+	Domain: "domain",
+	Base: "base"
+};
+/** Every level of the chain; the project is the most specific one. */
+const Level = {
+	Project: "project",
+	...PresetLevel
+};
+/**
+* Order of levels from specific to general. The number also prefixes generated rule files,
+* so that agents read specific rules first: `10-project-architecture.md`.
+*/
+const LEVEL_RANK = {
+	[Level.Project]: 10,
+	[Level.Team]: 20,
+	[Level.Domain]: 30,
+	[Level.Base]: 40
+};
+//#endregion
+//#region src/shared/utils/guards.ts
+function isString(value) {
+	return typeof value === "string";
+}
+function isKeyValueMap(value) {
+	if (value === null) return false;
+	if (Array.isArray(value)) return false;
+	return typeof value === "object";
+}
+//#endregion
+//#region src/shared/schemas/preset.ts
+const keys = z.array(z.string().min(1)).readonly();
+const stringMap = z.record(z.string(), z.string());
+const skillName = z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "Use lowercase letters, digits and single hyphens").max(64);
+const excludeSchema = z.strictObject({
+	rules: keys.optional(),
+	skills: keys.optional(),
+	commands: keys.optional(),
+	mcp: keys.optional()
+});
+const mcpPatchSchema = z.strictObject({
+	command: z.string().optional(),
+	args: z.array(z.string()).readonly().optional(),
+	url: z.string().optional(),
+	env: stringMap.optional(),
+	headers: stringMap.optional()
+});
+const overridesSchema = z.strictObject({ mcp: z.record(z.string(), mcpPatchSchema).optional() });
+const presetManifestSchema = z.strictObject({
+	name: z.string().min(1),
+	level: z.enum(PresetLevel),
+	description: z.string().optional(),
+	extends: z.array(z.string().min(1)).readonly().default([]),
+	exclude: excludeSchema.default({}),
+	overrides: overridesSchema.default({})
+});
+const projectConfigSchema = z.strictObject({
+	name: z.string().min(1).optional(),
+	extends: z.array(z.string().min(1)).readonly().default([]),
+	agents: z.array(z.enum(Agent)).min(1).readonly().default([Agent.Claude]),
+	exclude: excludeSchema.default({}),
+	overrides: overridesSchema.default({})
+});
+const mcpServerSchema = z.strictObject({
+	description: z.string().optional(),
+	type: z.enum([
+		"stdio",
+		"http",
+		"sse"
+	]).optional(),
+	command: z.string().optional(),
+	args: z.array(z.string()).readonly().optional(),
+	env: stringMap.optional(),
+	url: z.string().optional(),
+	headers: stringMap.optional()
+}).refine((server) => [server.command, server.url].filter(isString).length === 1, { message: "Set either \"command\" (local server) or \"url\" (remote server)" });
+//#endregion
+//#region src/shared/errors/get-error-message.ts
+/** The message of anything thrown: `catch` gives `unknown`, not always an `Error`. */
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+//#endregion
+//#region src/shared/utils/validate.ts
+/** Checks data with a schema; `what` names the checked thing in the error. */
+function validate(data, schema, what) {
+	const result = schema.safeParse(data);
+	if (result.success) return result.data;
+	throw new TunestraError(`Invalid ${what}:\n${prettifyError(result.error)}`);
+}
+//#endregion
+//#region src/shared/utils/yaml.ts
+/** Parses YAML; an empty document becomes an empty object. `what` names it in the error. */
+function parseYaml(content, what) {
+	try {
+		return parse(content) ?? {};
+	} catch (error) {
+		throw new TunestraError(`Invalid ${what}: ${getErrorMessage(error)}`);
+	}
+}
+async function readYaml(file, schema, what) {
+	return validate(parseYaml(await readFile(file, "utf8"), `YAML in ${file}`), schema, `${what} ${file}`);
+}
+//#endregion
+//#region src/shared/utils/settled.ts
+function isFulfilled(result) {
+	return result.status === "fulfilled";
+}
+/** Narrows the results of `Promise.allSettled`, tuples included, to fulfilled ones. */
+function isEveryFulfilled(results) {
+	return results.every(isFulfilled);
+}
+function getValues(results) {
+	return results.map((result) => result.value);
+}
+/**
+* Builds one error from every rejected result, in the order of the results, so the message
+* does not depend on which promise settles first. An error that is not caused by the user's
+* input is returned as is.
+*/
+function buildResultsError(results) {
+	const problems = [];
+	for (const result of results) {
+		if (isFulfilled(result)) continue;
+		const reason = result.reason;
+		if (reason instanceof TunestraError) {
+			problems.push(...reason.problems);
+			continue;
+		}
+		return reason;
+	}
+	return createProblemsError(problems);
+}
+/**
+* Maps every item with an async function at the same time. Returns the values in the order
+* of the items, or throws one error with the problems of every failed item.
+*/
+async function mapSettled(items, map) {
+	const mappings = items.map((item) => map(item));
+	const results = await Promise.allSettled(mappings);
+	if (isEveryFulfilled(results)) return getValues(results);
+	throw buildResultsError(results);
+}
+//#endregion
+//#region src/shared/schemas/frontmatter.ts
+const ruleFrontmatterSchema = z.looseObject({ description: z.string().optional() });
+const skillFrontmatterSchema = z.looseObject({
+	name: skillName.optional(),
+	description: z.string().min(1)
+});
+const commandFrontmatterSchema = z.looseObject({ description: z.string().optional() });
+//#endregion
+//#region src/presets/frontmatter.ts
+/**
+* A YAML block between two `---` lines at the very start of the file.
+* Group 1 is the YAML; it is missing when the block is empty.
+*
+* Matches:        "---\ndescription: Hi\n---\n# Title"  → group 1 = "description: Hi"
+* Matches:        "---\n---\nText"                       → group 1 = undefined
+* Does not match: "# Title\n---\nkey: value\n---"         (not at the start of the file)
+*/
+const FRONTMATTER_PATTERN = /^---\r?\n(?:([\s\S]*?)\r?\n)?---(?:\r?\n|$)/;
+/** Splits a markdown file into YAML frontmatter and body. A file without frontmatter has empty data. */
+function parseFrontmatter(text, file) {
+	const match = FRONTMATTER_PATTERN.exec(text);
+	if (match === null) return {
+		data: {},
+		body: text
+	};
+	const data = parseYaml(match.at(1) ?? "", `frontmatter in ${file}`);
+	if (isKeyValueMap(data)) return {
+		data,
+		body: text.slice(match[0].length)
+	};
+	throw new TunestraError(`Invalid frontmatter in ${file}: expected key-value pairs`);
+}
+//#endregion
+//#region src/presets/artifacts/commands.ts
+async function loadCommands(dir) {
+	return mapSettled(await listFiles(dir, "commands/*.md"), (source) => loadCommand(dir, source));
+}
+async function loadCommand(dir, source) {
+	const file = join(dir, source);
+	const content = await readFile(file, "utf8");
+	const { data } = parseFrontmatter(content, file);
+	const frontmatter = validate(data, commandFrontmatterSchema, `frontmatter in ${file}`);
+	return {
+		key: basename(source, ".md"),
+		source,
+		description: frontmatter.description,
+		content
+	};
+}
+//#endregion
+//#region src/presets/artifacts/mcp-servers.ts
+async function loadMcpServers(dir) {
+	return mapSettled(await listFiles(dir, "mcp/*.yaml"), (source) => loadMcpServer(dir, source));
+}
+async function loadMcpServer(dir, source) {
+	const { description, ...config } = await readYaml(join(dir, source), mcpServerSchema, "MCP server");
+	return {
+		key: basename(source, ".yaml"),
+		source,
+		description,
+		config
+	};
+}
+//#endregion
+//#region src/presets/artifacts/rules.ts
+const INSTRUCTIONS_DESCRIPTION = "Main instructions of the level";
+function buildInstructionsKey(presetName) {
+	return `instructions@${presetName}`;
+}
+/** The level instructions from AGENTS.md come first, then rules/*.md by name. */
+async function loadRules(dir, presetName) {
+	const instructionsLoading = loadInstructions(dir, presetName);
+	const rulesLoading = mapSettled(await listFiles(dir, "rules/*.md"), (source) => loadRule(dir, source));
+	const results = await Promise.allSettled([instructionsLoading, rulesLoading]);
+	if (isEveryFulfilled(results) === false) throw buildResultsError(results);
+	const [instructionsResult, rulesResult] = results;
+	const instructions = instructionsResult.value;
+	const rules = rulesResult.value;
+	if (instructions === void 0) return rules;
+	return [instructions, ...rules];
+}
+async function loadInstructions(dir, presetName) {
+	const file = join(dir, INSTRUCTIONS_FILE);
+	if (await checkExists(file) === false) return;
+	const key = buildInstructionsKey(presetName);
+	const body = await readFile(file, "utf8");
+	return {
+		key,
+		source: INSTRUCTIONS_FILE,
+		description: INSTRUCTIONS_DESCRIPTION,
+		body
+	};
+}
+async function loadRule(dir, source) {
+	const file = join(dir, source);
+	const { data, body } = parseFrontmatter(await readFile(file, "utf8"), file);
+	const frontmatter = validate(data, ruleFrontmatterSchema, `frontmatter in ${file}`);
+	return {
+		key: basename(source, ".md"),
+		source,
+		description: frontmatter.description,
+		body
+	};
+}
+//#endregion
+//#region src/presets/artifacts/skills.ts
+async function loadSkills(dir) {
+	const skills = await mapSettled(await listFiles(dir, "skills/*/SKILL.md"), (manifest) => loadSkill(dir, manifest));
+	const problems = findDuplicateSkills(skills, dir);
+	if (problems.length > 0) throw createProblemsError(problems);
+	return skills;
+}
+async function loadSkill(dir, manifest) {
+	const file = join(dir, manifest);
+	const source = dirname(manifest);
+	const { data } = parseFrontmatter(await readFile(file, "utf8"), file);
+	const frontmatter = validate(data, skillFrontmatterSchema, `frontmatter in ${file}`);
+	const folderName = basename(source);
+	const key = frontmatter.name ?? validate(folderName, skillName, `skill folder ${source}`);
+	const files = await listAllFiles(join(dir, source));
+	return {
+		key,
+		source,
+		description: frontmatter.description,
+		files
+	};
+}
+function findDuplicateSkills(skills, dir) {
+	const sources = /* @__PURE__ */ new Map();
+	const problems = [];
+	for (const skill of skills) {
+		const duplicate = sources.get(skill.key);
+		if (typeof duplicate === "string") problems.push(`Skills ${duplicate} and ${skill.source} in ${dir} have the same name "${skill.key}"`);
+		sources.set(skill.key, skill.source);
+	}
+	return problems;
+}
+//#endregion
+//#region src/presets/artifacts/load-artifacts.ts
+/** Loads every kind of artifact at the same time and reports the problems of all of them. */
+async function loadArtifacts(dir, presetName) {
+	const rulesLoading = loadRules(dir, presetName);
+	const skillsLoading = loadSkills(dir);
+	const commandsLoading = loadCommands(dir);
+	const mcpLoading = loadMcpServers(dir);
+	const results = await Promise.allSettled([
+		rulesLoading,
+		skillsLoading,
+		commandsLoading,
+		mcpLoading
+	]);
+	if (isEveryFulfilled(results) === false) throw buildResultsError(results);
+	const [rulesResult, skillsResult, commandsResult, mcpResult] = results;
+	return {
+		rules: rulesResult.value,
+		skills: skillsResult.value,
+		commands: commandsResult.value,
+		mcp: mcpResult.value
+	};
+}
+//#endregion
+//#region src/presets/load-project.ts
+async function loadProject(dir) {
+	const root = resolve(dir);
+	const configPath = join(root, PROJECT_CONFIG);
+	if (await checkExists(configPath) === false) throw new TunestraError(`${PROJECT_CONFIG} not found in ${root}. Run \`tunestra init\` first`);
+	const config = await readYaml(configPath, projectConfigSchema, "project config");
+	const folderName = basename(root);
+	const name = config.name ?? folderName;
+	const artifactsDir = join(root, PROJECT_DIR);
+	const artifacts = await loadArtifacts(artifactsDir, name);
+	return {
+		...config,
+		name,
+		level: Level.Project,
+		description: void 0,
+		dir: root,
+		artifactsDir,
+		remote: void 0,
+		...artifacts
+	};
+}
+//#endregion
+//#region src/shared/utils/paths.ts
+/** Generated files always use `/`, so they are the same on every system. */
+function toPosixPath(path) {
+	return path.split(sep).join("/");
+}
+function relativePosix(from, to) {
+	return toPosixPath(relative(from, to));
+}
+//#endregion
+//#region src/sources/parse-git-source.ts
+/**
+* A reference to a preset in a git repository.
+* Groups: 1 provider, 2 owner, 3 repository, 4 path inside it, 5 ref.
+*
+* Matches:        "github:org/presets/team#v1" → github, org, presets, team, v1
+* Matches:        "gitlab:org/presets#main"    → gitlab, org, presets, undefined, main
+* Matches:        "github:org/presets/a/b"     → github, org, presets, a/b, undefined
+* Does not match: "../presets/team" (a local path), "github:presets" (no owner)
+*/
+const GIT_SOURCE_PATTERN = /^(github|gitlab):([^/#]+)\/([^/#]+)(?:\/([^#]+))?(?:#(.+))?$/;
+/** `undefined` for a reference that is not a git source, like a relative path. */
+function parseGitSource(ref) {
+	const match = GIT_SOURCE_PATTERN.exec(ref);
+	if (match === null) return;
+	const [, provider, owner, repo, path, gitRef] = match;
+	if ((provider === "github" || provider === "gitlab") && typeof owner === "string" && typeof repo === "string") return {
+		provider,
+		owner,
+		repo,
+		path: path ?? "",
+		ref: gitRef
+	};
+}
+/** The repository with its ref, without the path: `github:org/presets#v1`. */
+function describeRepository(source) {
+	const repository = `${source.provider}:${source.owner}/${source.repo}`;
+	if (source.ref === void 0) return repository;
+	return `${repository}#${source.ref}`;
+}
+/** The full reference back: `github:org/presets/team#v1`. */
+function describeGitSource(source) {
+	return `${`${source.provider}:${source.owner}/${source.repo}`}${source.path === "" ? "" : `/${source.path}`}${source.ref === void 0 ? "" : `#${source.ref}`}`;
+}
+//#endregion
+//#region src/sources/download-repository.ts
+/** Token for private repositories; tunestra's own name, whatever does the download. */
+const GIT_TOKEN_VARIABLE = "TUNESTRA_GIT_TOKEN";
+/** Downloads a repository as an archive over HTTPS, so git is not needed. */
+const downloadRepository = async (source, dir) => {
+	const repository = describeRepository(source);
+	const token = process.env[GIT_TOKEN_VARIABLE];
+	const options = createDownloadOptions(dir, token);
+	try {
+		await downloadTemplate(repository, options);
+	} catch (error) {
+		throw new TunestraError(`Could not download ${repository}: ${getErrorMessage(error)}. Check the name and the ref; for a private repository, set ${GIT_TOKEN_VARIABLE} to a token with read access`);
+	}
+};
+/** The token is passed only when it is set. */
+function createDownloadOptions(dir, token) {
+	const options = {
+		dir,
+		force: true,
+		forceClean: true,
+		silent: true
+	};
+	if (token === void 0) return options;
+	return {
+		...options,
+		auth: token
+	};
+}
+//#endregion
+//#region src/sources/create-source-resolver.ts
+function createSourceResolver(projectDir, download = downloadRepository) {
+	const downloads = /* @__PURE__ */ new Map();
+	const repositories = [];
+	/** Each repository at each ref is downloaded once, however many presets come from it. */
+	const fetchRepository = (source) => {
+		const key = describeRepository(source);
+		const started = downloads.get(key);
+		if (typeof started === "object") return started;
+		const refName = source.ref ?? "HEAD";
+		const refFolder = encodeURIComponent(refName);
+		const root = join(projectDir, SOURCES_DIR, source.provider, source.owner, source.repo, refFolder);
+		const repository = {
+			root,
+			source
+		};
+		const downloading = download(source, root).then(() => repository);
+		repositories.push(repository);
+		downloads.set(key, downloading);
+		return downloading;
+	};
+	const findRepository = (dir) => {
+		return repositories.find((repository) => isInside(repository.root, dir));
+	};
+	const resolveRef = async (ref, fromDir) => {
+		const gitSource = parseGitSource(ref);
+		if (typeof gitSource === "object") {
+			const repository = await fetchRepository(gitSource);
+			return checkInside(repository, join(repository.root, gitSource.path), ref);
+		}
+		const dir = resolve(fromDir, ref);
+		const repository = findRepository(fromDir);
+		if (repository === void 0) return dir;
+		return checkInside(repository, dir, ref);
+	};
+	const describeRemote = (dir) => {
+		const repository = findRepository(dir);
+		if (repository === void 0) return;
+		const path = relative(repository.root, dir);
+		return describeGitSource({
+			...repository.source,
+			path: toPosixPath(path)
+		});
+	};
+	return {
+		resolve: resolveRef,
+		describeRemote
+	};
+}
+/** A preset from git can only reach presets of the same repository with a relative path. */
+function checkInside(repository, dir, ref) {
+	if (isInside(repository.root, dir)) return dir;
+	throw new TunestraError(`"${ref}" points outside of ${describeRepository(repository.source)}. A preset from git can only extend presets of the same repository or other git sources`);
+}
+function isInside(root, dir) {
+	const path = relative(root, dir);
+	const isParent = path === ".." || path.startsWith(`..${sep}`);
+	const isOtherDrive = isAbsolute(path);
+	return isParent === false && isOtherDrive === false;
+}
+//#endregion
+//#region src/chain/check-chain.ts
+/** A level can extend the same or a more general level, never a more specific one. */
+function findLevelProblems(graph) {
+	const problems = [];
+	const links = [...graph.parents];
+	for (const [dir, parentDirs] of links) {
+		const child = graph.levels.get(dir);
+		if (child === void 0) continue;
+		for (const parentDir of parentDirs) {
+			const parent = graph.levels.get(parentDir);
+			if (parent === void 0) continue;
+			if (LEVEL_RANK[parent.level] < LEVEL_RANK[child.level]) problems.push(`${child.name} (${child.level}) extends ${parent.name} (${parent.level}), a more specific level. A level can only extend the same or a more general level`);
+		}
+	}
+	return problems;
+}
+/** Names identify levels in keys like `instructions@team`, so they must be unique. */
+function findDuplicateNames(levels) {
+	const dirs = /* @__PURE__ */ new Map();
+	const problems = [];
+	for (const level of levels) {
+		const otherDir = dirs.get(level.name);
+		if (typeof otherDir === "string") problems.push(`Two levels have the same name "${level.name}": ${otherDir} and ${level.dir}`);
+		dirs.set(level.name, level.dir);
+	}
+	return problems;
+}
+//#endregion
+//#region src/chain/linearize-chain.ts
+/**
+* Puts the levels in order with a depth-first walk from the project: parents first, in the
+* order of `extends`, then the level itself. A level that is reached twice is added once.
+*/
+function linearizeChain(graph) {
+	const levels = [];
+	const visited = /* @__PURE__ */ new Set();
+	const problems = /* @__PURE__ */ new Set();
+	const visit = (dir, path) => {
+		if (path.includes(dir)) {
+			const cycle = describeCycle(graph, path, dir);
+			problems.add(`Cycle in extends: ${cycle}`);
+			return;
+		}
+		if (visited.has(dir)) return;
+		const parentDirs = graph.parents.get(dir) ?? [];
+		const nextPath = [...path, dir];
+		for (const parentDir of parentDirs) visit(parentDir, nextPath);
+		visited.add(dir);
+		const level = graph.levels.get(dir);
+		if (level === void 0) return;
+		levels.push(level);
+	};
+	visit(graph.project.dir, []);
+	return {
+		levels,
+		problems: [...problems]
+	};
+}
+/** Names of the levels in the cycle, for example `team → base → team`. */
+function describeCycle(graph, path, dir) {
+	const start = path.indexOf(dir);
+	const names = path.slice(start).map((cycleDir) => describeLevel(graph, cycleDir));
+	const repeatedName = describeLevel(graph, dir);
+	return [...names, repeatedName].join(" → ");
+}
+function describeLevel(graph, dir) {
+	return graph.levels.get(dir)?.name ?? dir;
+}
+//#endregion
+//#region src/presets/load-preset.ts
+async function loadPreset(dir) {
+	const root = resolve(dir);
+	const manifestPath = join(root, PRESET_MANIFEST);
+	if (await checkExists(manifestPath) === false) throw new TunestraError(`${root} is not a preset: ${PRESET_MANIFEST} is missing`);
+	const manifest = await readYaml(manifestPath, presetManifestSchema, "preset manifest");
+	const artifacts = await loadArtifacts(root, manifest.name);
+	return {
+		...manifest,
+		description: manifest.description,
+		dir: root,
+		artifactsDir: root,
+		remote: void 0,
+		...artifacts
+	};
+}
+//#endregion
+//#region src/chain/load-preset-graph.ts
+/**
+* Loads the presets of the project, then the presets they extend, and so on. Each step loads
+* its presets in parallel; a preset that several levels extend is loaded once.
+*/
+async function loadPresetGraph(project, resolver) {
+	const levels = /* @__PURE__ */ new Map();
+	const parents = /* @__PURE__ */ new Map();
+	let pending = [project];
+	levels.set(project.dir, project);
+	while (pending.length > 0) {
+		const dirsToLoad = /* @__PURE__ */ new Set();
+		for (const preset of pending) {
+			const parentDirs = await mapSettled(preset.extends, (ref) => resolver.resolve(ref, preset.dir));
+			parents.set(preset.dir, parentDirs);
+			for (const parentDir of parentDirs) if (levels.has(parentDir) === false) dirsToLoad.add(parentDir);
+		}
+		pending = await mapSettled([...dirsToLoad], (dir) => loadRemotePreset(dir, resolver));
+		for (const preset of pending) levels.set(preset.dir, preset);
+	}
+	return {
+		project,
+		levels,
+		parents
+	};
+}
+async function loadRemotePreset(dir, resolver) {
+	const preset = await loadPreset(dir);
+	const remote = resolver.describeRemote(dir);
+	return {
+		...preset,
+		remote
+	};
+}
+//#endregion
+//#region src/chain/load-chain.ts
+/** Loads the project with every preset it extends and puts them in order. */
+async function loadChain(projectDir, options = {}) {
+	const project = await loadProject(projectDir);
+	const graph = await loadPresetGraph(project, createSourceResolver(project.dir, options.download));
+	const linearization = linearizeChain(graph);
+	const levelProblems = findLevelProblems(graph);
+	const nameProblems = findDuplicateNames(linearization.levels);
+	const problems = [
+		...linearization.problems,
+		...levelProblems,
+		...nameProblems
+	];
+	if (problems.length > 0) throw createProblemsError(problems);
+	return {
+		project,
+		levels: linearization.levels
+	};
+}
+//#endregion
+//#region src/generate/describe-source.ts
+/** Files built from the whole chain, like AGENTS.md: there is no single file to edit. */
+const SETUP_SOURCE = "tunestra.yaml and its presets";
+/**
+* Where to edit an artifact, for messages to people: a path from the project, or the file
+* in its git source, because the downloaded copy is replaced on every setup.
+*/
+function describeArtifactSource(projectDir, origin, source) {
+	if (typeof origin.remote === "string") return `${source} in ${origin.remote}`;
+	return relativePosix(projectDir, join(origin.artifactsDir, source));
+}
+//#endregion
+//#region src/shared/utils/outputs.ts
+function createFileOutput(path, content, source) {
+	return {
+		kind: OutputKind.File,
+		path,
+		source,
+		content
+	};
+}
+//#endregion
+//#region src/agents/claude/mcp-json.ts
+/** `.mcp.json` in the shape Claude Code reads: `{ "mcpServers": { "<key>": config } }`. */
+function renderMcpJson(servers) {
+	const entries = servers.map((server) => [server.artifact.key, server.artifact.config]);
+	const content = { mcpServers: Object.fromEntries(entries) };
+	return `${JSON.stringify(content, null, 2)}\n`;
+}
+//#endregion
+//#region src/agents/claude/claude-adapter.ts
+const CLAUDE_FILE = "CLAUDE.md";
+const RULES_DIR = ".claude/rules/tunestra";
+const SKILLS_DIR = ".claude/skills";
+const COMMANDS_DIR = ".claude/commands";
+const MCP_FILE = ".mcp.json";
+const MCP_SOURCE = "the mcp/ folders of tunestra.yaml and its presets";
+/**
+* Claude Code reads CLAUDE.md, so it imports AGENTS.md. Rules are copied to `.claude/rules`,
+* which Claude Code loads in every session; a symlink to a directory outside `.claude`
+* would need an approval. Skills are symlinks to the shared `.agents/skills`.
+*/
+const claudeAdapter = {
+	agent: Agent.Claude,
+	plan: planClaude
+};
+function planClaude(context) {
+	const { resolution, ruleFiles } = context;
+	const projectDir = resolution.chain.project.dir;
+	const claudeContent = `${GENERATED_NOTICE}\n@${INSTRUCTIONS_FILE}\n`;
+	const claudeFile = createFileOutput(CLAUDE_FILE, claudeContent, SETUP_SOURCE);
+	const ruleCopies = ruleFiles.map(copyRule);
+	const skillLinks = resolution.skills.map((skill) => linkSkill(projectDir, skill));
+	const commandFiles = resolution.commands.map((command) => {
+		const path = `${COMMANDS_DIR}/${command.artifact.key}.md`;
+		const source = describeArtifactSource(projectDir, command.origin, command.artifact.source);
+		return createFileOutput(path, command.artifact.content, source);
+	});
+	const outputs = [
+		claudeFile,
+		...ruleCopies,
+		...skillLinks,
+		...commandFiles
+	];
+	if (resolution.mcp.length > 0) {
+		const mcpJson = renderMcpJson(resolution.mcp);
+		const mcpFile = createFileOutput(MCP_FILE, mcpJson, MCP_SOURCE);
+		outputs.push(mcpFile);
+	}
+	return {
+		outputs,
+		ignoredPaths: [
+			`${RULES_DIR}/`,
+			`${SKILLS_DIR}/`,
+			`${COMMANDS_DIR}/`,
+			MCP_FILE
+		],
+		protectedPaths: [CLAUDE_FILE]
+	};
+}
+function copyRule(ruleFile) {
+	const fileName = posix.basename(ruleFile.path);
+	return createFileOutput(`${RULES_DIR}/${fileName}`, ruleFile.content, ruleFile.source);
+}
+function linkSkill(projectDir, skill) {
+	const { key } = skill.artifact;
+	const path = `${SKILLS_DIR}/${key}`;
+	const target = `../../${AGENTS_SKILLS_DIR}/${key}`;
+	const source = describeArtifactSource(projectDir, skill.origin, skill.artifact.source);
+	return {
+		kind: OutputKind.Symlink,
+		path,
+		source,
+		target
+	};
+}
+//#endregion
+//#region src/agents/adapters.ts
+/** Every supported agent; Codex comes in v0.2. */
+const AGENT_ADAPTERS = { [Agent.Claude]: claudeAdapter };
+//#endregion
+//#region src/shared/utils/markdown.ts
+/**
+* A pipe or a line break inside a cell would break the table.
+*
+* Matches: "|" in "a | b", "\n" and "\r\n" in "line one\nline two"
+*/
+const TABLE_BREAKING_PATTERN = /\||\r?\n/g;
+function renderTable(header, rows) {
+	return [
+		renderRow(header),
+		`|${header.map(() => "---").join("|")}|`,
+		...rows.map(renderRow)
+	].join("\n");
+}
+function renderRow(cells) {
+	return `| ${cells.map(escapeCell).join(" | ")} |`;
+}
+function escapeCell(cell) {
+	return cell.replace(TABLE_BREAKING_PATTERN, replaceTableBreaking);
+}
+function replaceTableBreaking(match) {
+	if (match === "|") return "\\|";
+	return " ";
+}
+//#endregion
+//#region src/generate/describe-origin.ts
+/** For example `team, overrides base` or `base, patched by team`. */
+function describeOrigin(resolved) {
+	const parts = [resolved.origin.level];
+	const hasOverrides = resolved.overrides.length > 0;
+	const isPatched = resolved.patchedBy.length > 0;
+	if (hasOverrides) {
+		const names = joinNames(resolved.overrides);
+		parts.push(`overrides ${names}`);
+	}
+	if (isPatched) {
+		const names = joinNames(resolved.patchedBy);
+		parts.push(`patched by ${names}`);
+	}
+	return parts.join(", ");
+}
+function joinNames(origins) {
+	return origins.map((origin) => origin.name).join(", ");
+}
+//#endregion
+//#region src/generate/rule-file.ts
+/**
+* `<rank>-<level>-<key>.md`, so that a plain sort puts specific rules first. Level
+* instructions become `instructions`, with the preset name when it differs from the level.
+*/
+function buildRuleFileName(rule) {
+	const rank = LEVEL_RANK[rule.origin.level];
+	const slug = buildRuleSlug(rule);
+	return `${rank}-${rule.origin.level}-${slug}.md`;
+}
+/** The rule text with a header that tells where it comes from and what it overrides. */
+function renderRuleFile(rule) {
+	const sourceFile = join(rule.origin.artifactsDir, rule.artifact.source);
+	const sourcePath = relativePosix(rule.origin.dir, sourceFile);
+	const levelLine = renderLevelLine(rule);
+	return [
+		`${GENERATED_MARKER} from ${rule.origin.name}:${sourcePath}. Do not edit. -->`,
+		levelLine,
+		"",
+		rule.artifact.body
+	].join("\n");
+}
+function buildRuleSlug(rule) {
+	const instructionsKey = buildInstructionsKey(rule.origin.name);
+	const isInstructions = rule.artifact.key === instructionsKey;
+	const isNamedAsLevel = rule.origin.name === rule.origin.level;
+	if (isInstructions === false) return rule.artifact.key;
+	if (isNamedAsLevel) return "instructions";
+	return `instructions-${rule.origin.name}`;
+}
+/** For example `> Level: team, preset: team. Overrides: base.` */
+function renderLevelLine(rule) {
+	const line = `> Level: ${rule.origin.level}, preset: ${rule.origin.name}.`;
+	if (rule.overrides.length > 0) return `${line} Overrides: ${joinNames(rule.overrides)}.`;
+	return line;
+}
+//#endregion
+//#region src/generate/index-sections.ts
+const HIERARCHY_INTRO = "Instructions are ordered from specific to general. When two instructions conflict, follow the one from the higher level in this list.";
+const RULES_INTRO = "Always follow these rules. Claude Code loads them automatically; other agents should read them before starting work.";
+const SKILLS_INTRO = "Use a skill when the task matches its description.";
+const CHANGING_SECTION = [
+	"## Changing this setup",
+	"",
+	"Do not edit this file or the generated directories. Edit the sources (`tunestra.yaml`, `.tunestra/` or the presets above) and run `tunestra setup`."
+].join("\n");
+function renderHierarchy(chain) {
+	const table = renderTable([
+		"#",
+		"Level",
+		"Preset",
+		"Source"
+	], chain.levels.toReversed().map((level, index) => {
+		const number = String(index + 1);
+		const source = describeLevelSource(chain, level);
+		return [
+			number,
+			level.level,
+			level.name,
+			source
+		];
+	}));
+	return renderSection("Hierarchy", HIERARCHY_INTRO, table);
+}
+function renderRules(rules) {
+	const table = renderTable([
+		"Rule",
+		"Level",
+		"Description",
+		"File"
+	], rules.map((rule) => {
+		const origin = describeOrigin(rule);
+		const description = rule.artifact.description ?? "";
+		const fileName = buildRuleFileName(rule);
+		return [
+			rule.artifact.key,
+			origin,
+			description,
+			`${AGENTS_RULES_DIR}/${fileName}`
+		];
+	}));
+	return renderSection("Rules", RULES_INTRO, table);
+}
+function renderSkills(skills) {
+	const table = renderTable([
+		"Skill",
+		"Level",
+		"When to use",
+		"File"
+	], skills.map((skill) => {
+		const origin = describeOrigin(skill);
+		const file = `${AGENTS_SKILLS_DIR}/${skill.artifact.key}/SKILL.md`;
+		return [
+			skill.artifact.key,
+			origin,
+			skill.artifact.description,
+			file
+		];
+	}));
+	return renderSection("Skills", SKILLS_INTRO, table);
+}
+function renderCommands(commands) {
+	return renderSection("Commands", void 0, renderTable([
+		"Command",
+		"Level",
+		"Description"
+	], commands.map((command) => {
+		const origin = describeOrigin(command);
+		const description = command.artifact.description ?? "";
+		return [
+			`/${command.artifact.key}`,
+			origin,
+			description
+		];
+	})));
+}
+function renderMcpServers(servers) {
+	return renderSection("MCP servers", void 0, renderTable([
+		"Server",
+		"Level",
+		"Description"
+	], servers.map((server) => {
+		const origin = describeOrigin(server);
+		const description = server.artifact.description ?? "";
+		return [
+			server.artifact.key,
+			origin,
+			description
+		];
+	})));
+}
+/** The project shows its config file; a preset shows its git reference or its path. */
+function describeLevelSource(chain, level) {
+	if (level.dir === chain.project.dir) return PROJECT_CONFIG;
+	if (typeof level.remote === "string") return level.remote;
+	return relativePosix(chain.project.dir, level.dir);
+}
+function renderSection(title, intro, table) {
+	const heading = `## ${title}`;
+	if (intro === void 0) return [
+		heading,
+		"",
+		table
+	].join("\n");
+	return [
+		heading,
+		"",
+		intro,
+		"",
+		table
+	].join("\n");
+}
+//#endregion
+//#region src/generate/agents-index.ts
+/**
+* AGENTS.md: an index of the setup, not the rules themselves. It lists the levels, every
+* rule, skill, command and MCP server, where each comes from and where its file is.
+*/
+function renderAgentsIndex(resolution) {
+	const title = `# AI agent context: ${resolution.chain.project.name}`;
+	const hierarchy = renderHierarchy(resolution.chain);
+	const sections = [
+		GENERATED_NOTICE,
+		title,
+		hierarchy
+	];
+	const hasRules = resolution.rules.length > 0;
+	const hasSkills = resolution.skills.length > 0;
+	const hasCommands = resolution.commands.length > 0;
+	const hasMcpServers = resolution.mcp.length > 0;
+	if (hasRules) {
+		const rules = renderRules(resolution.rules);
+		sections.push(rules);
+	}
+	if (hasSkills) {
+		const skills = renderSkills(resolution.skills);
+		sections.push(skills);
+	}
+	if (hasCommands) {
+		const commands = renderCommands(resolution.commands);
+		sections.push(commands);
+	}
+	if (hasMcpServers) {
+		const servers = renderMcpServers(resolution.mcp);
+		sections.push(servers);
+	}
+	sections.push(CHANGING_SECTION);
+	return `${sections.join("\n\n")}\n`;
+}
+//#endregion
+//#region src/generate/plan-setup.ts
+/**
+* Builds every output without touching the disk: the shared files that any agent can read
+* (AGENTS.md, `.agents/`), then the native files of each agent of the project.
+*/
+function planSetup(resolution) {
+	const projectDir = resolution.chain.project.dir;
+	const index = renderAgentsIndex(resolution);
+	const indexFile = createFileOutput(INSTRUCTIONS_FILE, index, SETUP_SOURCE);
+	const ruleFiles = resolution.rules.map((rule) => planRuleFile(projectDir, rule));
+	const skillCopies = resolution.skills.flatMap((skill) => planSkillCopies(projectDir, skill));
+	const outputs = [
+		indexFile,
+		...ruleFiles,
+		...skillCopies
+	];
+	const ignoredPaths = [`${AGENTS_DIR}/`];
+	const protectedPaths = [INSTRUCTIONS_FILE];
+	const context = {
+		resolution,
+		ruleFiles
+	};
+	for (const agent of resolution.chain.project.agents) {
+		const agentPlan = AGENT_ADAPTERS[agent].plan(context);
+		outputs.push(...agentPlan.outputs);
+		ignoredPaths.push(...agentPlan.ignoredPaths);
+		protectedPaths.push(...agentPlan.protectedPaths);
+	}
+	ignoredPaths.push(`${STATE_DIR}/`);
+	const problems = findPathConflicts(outputs);
+	if (problems.length > 0) throw createProblemsError(problems);
+	return {
+		outputs,
+		ignoredPaths,
+		protectedPaths
+	};
+}
+function planRuleFile(projectDir, rule) {
+	const fileName = buildRuleFileName(rule);
+	return createFileOutput(`${AGENTS_RULES_DIR}/${fileName}`, renderRuleFile(rule), describeArtifactSource(projectDir, rule.origin, rule.artifact.source));
+}
+/** The skill is copied as a whole, with every file of its directory. */
+function planSkillCopies(projectDir, skill) {
+	const sourceDir = join(skill.origin.artifactsDir, skill.artifact.source);
+	const outputDir = `${AGENTS_SKILLS_DIR}/${skill.artifact.key}`;
+	return skill.artifact.files.map((file) => {
+		const path = `${outputDir}/${file}`;
+		const from = join(sourceDir, file);
+		const source = relativePosix(projectDir, from);
+		return {
+			kind: OutputKind.Copy,
+			path,
+			source,
+			from
+		};
+	});
+}
+/** Two outputs at one path would silently overwrite each other. */
+function findPathConflicts(outputs) {
+	const seen = /* @__PURE__ */ new Set();
+	const problems = [];
+	for (const output of outputs) {
+		if (seen.has(output.path)) problems.push(`Two generated files have the same path: ${output.path}`);
+		seen.add(output.path);
+	}
+	return problems;
+}
+//#endregion
+//#region src/shared/constants/artifacts.ts
+/** Kinds of artifacts; the values match the folder-based fields of a preset and of `exclude`. */
+const ArtifactKind = {
+	Rules: "rules",
+	Skills: "skills",
+	Commands: "commands",
+	Mcp: "mcp"
+};
+//#endregion
+//#region src/inheritance/inherit-artifacts.ts
+/**
+* Walks the levels from general to specific. On each level: drop the excluded keys, patch
+* the inherited artifacts, then add the level's own artifacts; the same key replaces the
+* inherited one.
+*/
+function inheritArtifacts(levels, kind, selectArtifacts, patchArtifacts = skipPatches) {
+	const inherited = /* @__PURE__ */ new Map();
+	const problems = [];
+	for (const level of levels) {
+		const excludeProblems = excludeArtifacts(inherited, level, kind);
+		const patchProblems = patchArtifacts(inherited, level);
+		const ownArtifacts = selectArtifacts(level);
+		const origin = createOrigin(level);
+		problems.push(...excludeProblems, ...patchProblems);
+		for (const artifact of ownArtifacts) addArtifact(inherited, artifact, origin);
+	}
+	return {
+		artifacts: orderFromSpecific(levels, inherited, selectArtifacts),
+		problems
+	};
+}
+function createOrigin(level) {
+	return {
+		name: level.name,
+		level: level.level,
+		dir: level.dir,
+		artifactsDir: level.artifactsDir,
+		remote: level.remote
+	};
+}
+function skipPatches() {
+	return [];
+}
+function excludeArtifacts(inherited, level, kind) {
+	const keys = level.exclude[kind] ?? [];
+	const problems = [];
+	for (const key of keys) if (inherited.delete(key) === false) problems.push(`${level.name}: exclude.${kind} lists "${key}", but no more general level has it`);
+	return problems;
+}
+function addArtifact(inherited, artifact, origin) {
+	const overrides = collectOverrides(inherited.get(artifact.key));
+	inherited.set(artifact.key, {
+		artifact,
+		origin,
+		overrides,
+		patchedBy: []
+	});
+}
+function collectOverrides(previous) {
+	if (previous === void 0) return [];
+	return [...previous.overrides, previous.origin];
+}
+/** Specific levels first, so that agents read the rules that win first. */
+function orderFromSpecific(levels, inherited, selectArtifacts) {
+	const ordered = [];
+	const specificFirst = levels.toReversed();
+	for (const level of specificFirst) {
+		const ownArtifacts = selectArtifacts(level);
+		for (const artifact of ownArtifacts) {
+			const resolved = inherited.get(artifact.key);
+			if (resolved?.origin.name === level.name) ordered.push(resolved);
+		}
+	}
+	return ordered;
+}
+//#endregion
+//#region src/shared/utils/records.ts
+/** Merges two string maps; keys of `patch` win. Missing on both sides stays missing. */
+function mergeRecords(base, patch) {
+	if (base === void 0 && patch === void 0) return;
+	return {
+		...base,
+		...patch
+	};
+}
+//#endregion
+//#region src/inheritance/patch-mcp-config.ts
+/** `env` and `headers` are merged by key; `command`, `args` and `url` are replaced. */
+function patchMcpConfig(config, patch) {
+	const command = patch.command ?? config.command;
+	const args = patch.args ?? config.args;
+	const url = patch.url ?? config.url;
+	const env = mergeRecords(config.env, patch.env);
+	const headers = mergeRecords(config.headers, patch.headers);
+	return {
+		...config,
+		command,
+		args,
+		url,
+		env,
+		headers
+	};
+}
+//#endregion
+//#region src/inheritance/patch-mcp-servers.ts
+/** Applies `overrides.mcp` of a level to the MCP servers it inherits. */
+const patchMcpServers = (inherited, level) => {
+	const patches = level.overrides.mcp ?? {};
+	const patchEntries = Object.entries(patches);
+	const problems = [];
+	for (const [key, patch] of patchEntries) {
+		const server = inherited.get(key);
+		if (server === void 0) {
+			problems.push(`${level.name}: overrides.mcp lists "${key}", but no more general level has this MCP server`);
+			continue;
+		}
+		const patched = applyPatch(server, level, patch);
+		if (mcpServerSchema.safeParse(patched.artifact.config).success === false) problems.push(`${level.name}: after the patch, MCP server "${key}" must have either "command" or "url"`);
+		inherited.set(key, patched);
+	}
+	return problems;
+};
+function applyPatch(server, level, patch) {
+	const config = patchMcpConfig(server.artifact.config, patch);
+	const origin = createOrigin(level);
+	const artifact = {
+		...server.artifact,
+		config
+	};
+	const patchedBy = [...server.patchedBy, origin];
+	return {
+		...server,
+		artifact,
+		patchedBy
+	};
+}
+//#endregion
+//#region src/inheritance/apply-inheritance.ts
+/** Resolves every kind of artifact along the chain and reports all problems together. */
+function applyInheritance(chain) {
+	const rules = inheritArtifacts(chain.levels, ArtifactKind.Rules, (level) => level.rules);
+	const skills = inheritArtifacts(chain.levels, ArtifactKind.Skills, (level) => level.skills);
+	const commands = inheritArtifacts(chain.levels, ArtifactKind.Commands, (level) => level.commands);
+	const mcp = inheritArtifacts(chain.levels, ArtifactKind.Mcp, (level) => level.mcp, patchMcpServers);
+	const problems = [
+		...rules.problems,
+		...skills.problems,
+		...commands.problems,
+		...mcp.problems
+	];
+	if (problems.length > 0) throw createProblemsError(problems);
+	return {
+		chain,
+		rules: rules.artifacts,
+		skills: skills.artifacts,
+		commands: commands.artifacts,
+		mcp: mcp.artifacts
+	};
+}
+//#endregion
+//#region src/shared/schemas/state.ts
+const fileRecordSchema = z.strictObject({ hash: z.string() });
+const symlinkRecordSchema = z.strictObject({ target: z.string() });
+const stateSchema = z.strictObject({
+	version: z.literal(1),
+	outputs: z.record(z.string(), z.union([fileRecordSchema, symlinkRecordSchema]))
+});
+//#endregion
+//#region src/state/read-state.ts
+/** The state of the last setup; a project that never ran setup has an empty one. */
+async function readState(projectDir) {
+	const file = join(projectDir, STATE_FILE);
+	const content = await readFileIfExists(file);
+	if (content === void 0) return createEmptyState();
+	return validate(parseJson(content, file), stateSchema, `state file ${file}. Delete it and run tunestra setup again`);
+}
+function createEmptyState() {
+	return {
+		version: 1,
+		outputs: {}
+	};
+}
+function parseJson(content, file) {
+	try {
+		return JSON.parse(content);
+	} catch (error) {
+		throw new TunestraError(`Invalid state file ${file}: ${getErrorMessage(error)}. Delete it and run tunestra setup again`);
+	}
+}
+//#endregion
+//#region src/setup/write-outputs.ts
+/** Writes every output in parallel and reports the problems of all of them together. */
+async function writeOutputs(projectDir, outputs) {
+	await mapSettled(outputs, (output) => writeOutput(projectDir, output));
+}
+async function writeOutput(projectDir, output) {
+	const path = join(projectDir, output.path);
+	const dir = dirname(path);
+	await mkdir(dir, { recursive: true });
+	switch (output.kind) {
+		case OutputKind.File:
+			await removeSymlink(path);
+			await writeFile(path, output.content);
+			return;
+		case OutputKind.Copy:
+			await removeSymlink(path);
+			await copyFile(output.from, path);
+			return;
+		case OutputKind.Symlink:
+			await replaceSymlink(path, output);
+			return;
+	}
+}
+/** Replaces only a symlink: a real file or directory at this path belongs to someone else. */
+async function replaceSymlink(path, output) {
+	const pathType = await getPathType(path);
+	if (pathType === PathType.Directory || pathType === PathType.File) throw new TunestraError(`${output.path} already exists and was not created by tunestra. Move it away and run tunestra setup again`);
+	if (pathType === PathType.Symlink) await unlink(path);
+	await symlink(output.target, path);
+}
+/** Writing a file through a symlink would change the file it points to. */
+async function removeSymlink(path) {
+	if (await getPathType(path) === PathType.Symlink) await unlink(path);
+}
+//#endregion
+//#region src/state/write-state.ts
+/** Paths are sorted, so that the file only changes when the outputs change. */
+async function writeState(projectDir, state) {
+	const file = join(projectDir, STATE_FILE);
+	const dir = dirname(file);
+	const entries = Object.keys(state.outputs).sort().map((path) => [path, state.outputs[path]]);
+	const outputs = Object.fromEntries(entries);
+	const content = {
+		version: state.version,
+		outputs
+	};
+	const text = `${JSON.stringify(content, null, 2)}\n`;
+	await mkdir(dir, { recursive: true });
+	await writeFile(file, text);
+}
+//#endregion
+//#region src/sync/remove-outputs.ts
+/** Removes stale outputs, then the directories that they leave empty. */
+async function removeOutputs(projectDir, paths) {
+	await mapSettled(paths, (path) => removeOutput(projectDir, path));
+	for (const path of paths) await removeEmptyParents(projectDir, path);
+}
+async function removeOutput(projectDir, path) {
+	const fullPath = join(projectDir, path);
+	await rm(fullPath, { force: true });
+}
+/** Goes up from the removed path until a directory has other files or the project is reached. */
+async function removeEmptyParents(projectDir, path) {
+	let dir = dirname(path);
+	while (dir !== ".") {
+		const fullDir = join(projectDir, dir);
+		if ((await readEntries(fullDir))?.length === 0 === false) return;
+		await rmdir(fullDir);
+		dir = dirname(dir);
+	}
+}
+/** A directory that is already gone counts as not empty: there is nothing to remove. */
+async function readEntries(dir) {
+	try {
+		return await readdir(dir);
+	} catch (error) {
+		if (isMissingPathError(error)) return;
+		throw error;
+	}
+}
+//#endregion
+//#region src/sync/apply-sync.ts
+/** Removes stale outputs first, so that a file can become a directory and back. */
+async function applySync(projectDir, sync) {
+	await removeOutputs(projectDir, sync.removals);
+	await writeOutputs(projectDir, sync.outputs);
+	await writeState(projectDir, sync.state);
+}
+//#endregion
+//#region src/shared/utils/hash.ts
+function hashContent(content) {
+	const hash = createHash("sha256");
+	hash.update(content);
+	return hash.digest("hex");
+}
+//#endregion
+//#region src/sync/create-record.ts
+/** How an output will look on the disk once it is written. */
+async function createRecord(output) {
+	switch (output.kind) {
+		case OutputKind.File: return { hash: hashContent(output.content) };
+		case OutputKind.Copy: return { hash: hashContent(await readFile(output.from)) };
+		case OutputKind.Symlink: return { target: output.target };
+	}
+}
+//#endregion
+//#region src/sync/inspect-path.ts
+async function inspectPath(path) {
+	const type = await getPathType(path);
+	if (type === PathType.Symlink) return {
+		type,
+		target: await readlink(path)
+	};
+	if (type === PathType.File) {
+		const content = await readFile(path);
+		return {
+			type,
+			hash: hashContent(content),
+			isMarked: content.subarray(0, 26).toString("utf8") === GENERATED_MARKER
+		};
+	}
+	return { type };
+}
+/** A file matches a record by its hash, a symlink by its target. */
+function matchesRecord(entry, record) {
+	if (entry.type === PathType.File && "hash" in record) return entry.hash === record.hash;
+	if (entry.type === PathType.Symlink && "target" in record) return entry.target === record.target;
+	return false;
+}
+//#endregion
+//#region src/sync/check-output.ts
+/**
+* Compares an output with the disk and the last setup. A file that tunestra wrote and
+* someone edited is replaced with a warning; a file that tunestra never wrote stops setup.
+*/
+async function checkOutput(output, context) {
+	const path = join(context.projectDir, output.path);
+	const record = await createRecord(output);
+	const disk = await inspectPath(path);
+	const previousRecord = context.previous.outputs[output.path];
+	if (isSafeToWrite(disk, record, previousRecord)) return createCheck(output, record, void 0);
+	const isRecorded = typeof previousRecord === "object";
+	const isReplaceable = disk.type === PathType.File || disk.type === PathType.Symlink;
+	if (isRecorded && isReplaceable) return createCheck(output, record, `${output.path} was edited by hand; tunestra replaced it. Edit ${output.source} instead`);
+	if (context.protectedPaths.includes(output.path)) throw new TunestraError(`${output.path} was written by hand, and setup would overwrite it. Move its text to .tunestra/AGENTS.md or to a rule in .tunestra/rules/, then delete ${output.path} and run tunestra setup again`);
+	throw new TunestraError(`${output.path} already exists, and tunestra did not create it. Move it away and run tunestra setup again`);
+}
+/**
+* Nothing to lose: the path is empty, already has the new content, still has what tunestra
+* wrote last time, or is a generated markdown file whose record was lost.
+*/
+function isSafeToWrite(disk, record, previousRecord) {
+	if (disk.type === PathType.Missing) return true;
+	if (matchesRecord(disk, record)) return true;
+	if (previousRecord === void 0) return disk.type === PathType.File && disk.isMarked;
+	return matchesRecord(disk, previousRecord);
+}
+function createCheck(output, record, warning) {
+	return {
+		path: output.path,
+		record,
+		warning
+	};
+}
+//#endregion
+//#region src/sync/check-stale-output.ts
+/**
+* A path that the last setup wrote and this one does not. Generated files are never kept:
+* an edited one is removed too, with a warning, so that the lost edit does not go unnoticed.
+* Only a directory is left alone, because tunestra never writes directories in its place.
+*/
+async function checkStaleOutput(projectDir, path, record) {
+	const disk = await inspectPath(join(projectDir, path));
+	const isMissing = disk.type === PathType.Missing;
+	const isDirectory = disk.type === PathType.Directory;
+	const isUnchanged = matchesRecord(disk, record);
+	if (isMissing) return createStaleCheck(path, false, void 0);
+	if (isDirectory) return createStaleCheck(path, false, `${path} is no longer generated, but it is a directory now, so tunestra left it`);
+	if (isUnchanged) return createStaleCheck(path, true, void 0);
+	return createStaleCheck(path, true, `${path} is no longer generated and was edited by hand; tunestra removed it`);
+}
+function createStaleCheck(path, isRemovable, warning) {
+	return {
+		path,
+		isRemovable,
+		warning
+	};
+}
+//#endregion
+//#region src/sync/plan-sync.ts
+/** Reads the disk, but writes nothing; problems of every output are reported together. */
+async function planSync(projectDir, plan, previous) {
+	const context = {
+		projectDir,
+		previous,
+		protectedPaths: plan.protectedPaths
+	};
+	const paths = plan.outputs.map((output) => output.path);
+	const outputPaths = new Set(paths);
+	const staleEntries = Object.entries(previous.outputs).filter(([path]) => outputPaths.has(path) === false);
+	const outputChecks = await mapSettled(plan.outputs, (output) => checkOutput(output, context));
+	const staleChecks = await mapSettled(staleEntries, ([path, record]) => checkStaleOutput(projectDir, path, record));
+	const removals = staleChecks.filter((check) => check.isRemovable).map((check) => check.path);
+	const warnings = [...outputChecks, ...staleChecks].map((check) => check.warning).filter(isString);
+	const recordEntries = outputChecks.map((check) => [check.path, check.record]);
+	const state = {
+		version: 1,
+		outputs: Object.fromEntries(recordEntries)
+	};
+	return {
+		outputs: plan.outputs,
+		removals,
+		warnings,
+		state
+	};
+}
+//#endregion
+//#region src/generate/gitignore.ts
+const BLOCK_START = "# >>> tunestra (generated, do not edit)";
+const BLOCK_START_PREFIX = "# >>> tunestra";
+const BLOCK_END = "# <<< tunestra";
+/** Paths are relative to the project and get a leading `/`, so they match only at the root. */
+function renderGitignoreBlock(paths) {
+	const lines = paths.map((path) => `/${path}`);
+	return [
+		BLOCK_START,
+		...lines,
+		BLOCK_END
+	].join("\n");
+}
+/** Replaces the tunestra block in `.gitignore`, or adds it at the end; other lines stay. */
+function updateGitignore(existing, block) {
+	if (existing === void 0) return `${block}\n`;
+	const start = existing.indexOf(BLOCK_START_PREFIX);
+	const end = existing.indexOf(BLOCK_END);
+	if (start >= 0 && end > start) return `${existing.slice(0, start)}${block}${existing.slice(end + 14)}`;
+	const content = existing.trimEnd();
+	if (content === "") return `${block}\n`;
+	return `${content}\n\n${block}\n`;
+}
+/** Removes the tunestra block and the empty lines around it; other lines stay as they are. */
+function removeGitignoreBlock(existing) {
+	const start = existing.indexOf(BLOCK_START_PREFIX);
+	const end = existing.indexOf(BLOCK_END);
+	if ((start >= 0 && end > start) === false) return existing;
+	const parts = [existing.slice(0, start).trimEnd(), existing.slice(end + 14).trim()].filter((part) => part.length > 0);
+	if (parts.length === 0) return "";
+	return `${parts.join("\n\n")}\n`;
+}
+//#endregion
+//#region src/setup/update-gitignore-file.ts
+async function updateGitignoreFile(projectDir, paths) {
+	const file = join(projectDir, GITIGNORE_FILE);
+	const content = updateGitignore(await readFileIfExists(file), renderGitignoreBlock(paths));
+	await writeFile(file, content);
+}
+//#endregion
+//#region src/setup/run-setup.ts
+/**
+* Loads the chain, resolves inheritance, compares the outputs with the last setup and
+* writes the configuration of every agent.
+*/
+async function runSetup(projectDir, options) {
+	const chain = await loadChain(projectDir);
+	const resolution = applyInheritance(chain);
+	const plan = planSetup(resolution);
+	const previous = await readState(chain.project.dir);
+	const sync = await planSync(chain.project.dir, plan, previous);
+	const report = {
+		resolution,
+		sync
+	};
+	if (options.dryRun) return report;
+	await applySync(chain.project.dir, sync);
+	await updateGitignoreFile(chain.project.dir, plan.ignoredPaths);
+	return report;
+}
+//#endregion
+//#region src/cli/commands/describe-resolution.ts
+/** For --verbose: every artifact, the level it comes from and the file to edit. */
+function describeResolution(resolution) {
+	const projectDir = resolution.chain.project.dir;
+	return [
+		describeSection("Rules", resolution.rules, projectDir),
+		describeSection("Skills", resolution.skills, projectDir),
+		describeSection("Commands", resolution.commands, projectDir),
+		describeSection("MCP servers", resolution.mcp, projectDir)
+	].filter((section) => section.length > 0).join("\n\n");
+}
+function describeSection(title, artifacts, projectDir) {
+	if (artifacts.length === 0) return "";
+	const rows = artifacts.map((resolved) => {
+		const origin = describeOrigin(resolved);
+		const source = describeArtifactSource(projectDir, resolved.origin, resolved.artifact.source);
+		return [
+			resolved.artifact.key,
+			origin,
+			source
+		];
+	});
+	const keyWidth = measureColumn(rows, 0);
+	const originWidth = measureColumn(rows, 1);
+	return [title, ...rows.map(([key = "", origin = "", source = ""]) => {
+		return `  ${key.padEnd(keyWidth)}  ${origin.padEnd(originWidth)}  ${source}`;
+	})].join("\n");
+}
+function measureColumn(rows, column) {
+	const widths = rows.map((row) => row[column]?.length ?? 0);
+	return Math.max(...widths);
+}
+//#endregion
+//#region src/cli/commands/setup.ts
+async function describeSetup(projectDir, options) {
+	const report = await runSetup(projectDir, options);
+	const summary = describeSync(report.sync, options);
+	if (options.verbose) return `${describeResolution(report.resolution)}
+
+${summary}`;
+	return summary;
+}
+function describeSync(sync, options) {
+	const warningIcon = pc.yellow("⚠");
+	const lines = sync.warnings.map((warning) => `${warningIcon} ${warning}`);
+	const writeCount = sync.outputs.length;
+	const removeCount = sync.removals.length;
+	if (options.dryRun) {
+		const writes = sync.outputs.map((output) => `  write   ${output.path}`);
+		const removals = sync.removals.map((path) => `  remove  ${path}`);
+		lines.push(...writes, ...removals, "", "Nothing was written (--dry-run).");
+		return lines.join("\n");
+	}
+	const check = pc.green("✔");
+	lines.push(`${check} Generated ${writeCount} files, removed ${removeCount} stale files.`);
+	lines.push("Commit AGENTS.md and CLAUDE.md; the rest is in .gitignore.");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/uninstall/remove-gitignore-block.ts
+/** A .gitignore that had only the tunestra block is removed, because tunestra created it. */
+async function removeGitignoreBlockFile(projectDir) {
+	const file = join(projectDir, GITIGNORE_FILE);
+	const existing = await readFileIfExists(file);
+	if (existing === void 0) return;
+	const content = removeGitignoreBlock(existing);
+	if (content === "") {
+		await rm(file);
+		return;
+	}
+	await writeFile(file, content);
+}
+//#endregion
+//#region src/uninstall/run-uninstall.ts
+/**
+* Removes everything that the last setup generated, the block in .gitignore and
+* .tunestra/state/. The sources, tunestra.yaml and .tunestra/, stay.
+*/
+async function runUninstall(projectDir, options) {
+	const state = await readState(projectDir);
+	const checks = await mapSettled(Object.entries(state.outputs), ([path, record]) => checkStaleOutput(projectDir, path, record));
+	const removals = checks.filter((check) => check.isRemovable).map((check) => check.path);
+	const warnings = checks.map((check) => check.warning).filter(isString);
+	if (options.dryRun) return {
+		removals,
+		warnings
+	};
+	const stateDir = join(projectDir, STATE_DIR);
+	await removeOutputs(projectDir, removals);
+	await removeGitignoreBlockFile(projectDir);
+	await rm(stateDir, {
+		recursive: true,
+		force: true
+	});
+	return {
+		removals,
+		warnings
+	};
+}
+//#endregion
+//#region src/cli/commands/uninstall.ts
+async function describeUninstall(projectDir, options) {
+	const report = await runUninstall(projectDir, options);
+	const warningIcon = pc.yellow("⚠");
+	const lines = report.warnings.map((warning) => `${warningIcon} ${warning}`);
+	const count = report.removals.length;
+	if (options.dryRun) {
+		const removals = report.removals.map((path) => `  remove  ${path}`);
+		lines.push(...removals, "", "Nothing was removed (--dry-run).");
+		return lines.join("\n");
+	}
+	const check = pc.green("✔");
+	lines.push(`${check} Removed ${count} generated files and the tunestra block in .gitignore.`);
+	lines.push("tunestra.yaml and .tunestra/ are kept: they are your sources.");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/cli/run-command.ts
+/** Prints the report of a command; an error in the user's input is shown without a stack. */
+async function runCommand(action) {
+	try {
+		const report = await action();
+		console.log(report);
+	} catch (error) {
+		if (error instanceof TunestraError) {
+			const message = pc.red(error.message);
+			console.error(message);
+			process.exitCode = 1;
+			return;
+		}
+		throw error;
+	}
+}
+//#endregion
+//#region src/cli/index.ts
+const program = new Command().name("tunestra").description("Tune your AI agents to play as one orchestra.").version(VERSION);
+program.command("init").description("Create tunestra.yaml and move hand-written AGENTS.md and CLAUDE.md to .tunestra/").option("--extends <presets...>", "presets to extend, from general to specific", []).action(async (options) => {
+	const projectDir = process.cwd();
+	const initOptions = { presets: options.extends };
+	await runCommand(() => describeInit(projectDir, initOptions));
+});
+program.command("setup").description("Generate agent configuration from tunestra.yaml and its presets").option("--dry-run", "show the plan without writing files", false).option("-v, --verbose", "show where every artifact comes from", false).action(async (options) => {
+	const projectDir = process.cwd();
+	await runCommand(() => describeSetup(projectDir, options));
+});
+program.command("uninstall").description("Remove everything tunestra generated; tunestra.yaml and .tunestra/ stay").option("--dry-run", "show what would be removed without removing it", false).action(async (options) => {
+	const projectDir = process.cwd();
+	await runCommand(() => describeUninstall(projectDir, options));
+});
+await program.parseAsync();
+//#endregion
+export {};