magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/symlink-manager.ts

@@ -0,0 +1,189 @@
+/**
+ * Profile symlink manager.
+ *
+ * Materialized profiles live at `.claude/_profiles/<name>/` (generated,
+ * gitignored). The active profile is made "live" by symlinking the shared
+ * config files into place:
+ *
+ *   .claude/settings.json  ->  .claude/_profiles/<name>/settings.json
+ *   .claude/skills         ->  .claude/_profiles/<name>/skills
+ *   .mcp.json              ->  .claude/_profiles/<name>/mcp.json
+ *   .claude/models.json    ->  .claude/_profiles/<name>/models.json
+ *
+ * Switching profiles just repoints these links — no network, no reinstall.
+ * settings.local.json is NEVER linked: it holds personal credentials and must
+ * survive switches untouched.
+ *
+ * models.json is the one link whose target is OPTIONAL: a profile that declares
+ * no routing has none, and the rule below (remove a link into _profiles/ whose
+ * target is gone) is what keeps a dangling `.claude/models.json` out of the
+ * repo. A dangling one would not be harmless — `.claude/` is committed, so it
+ * would ship to every teammate.
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+
+/**
+ * Paths that must be gitignored once a project uses profiles: the generated
+ * build output plus the active-profile symlinks. Only .claude/profiles.json is
+ * the committed source of truth. settings.local.json is intentionally NOT here
+ * (it's already gitignored elsewhere and holds personal credentials).
+ */
+export const PROFILE_GITIGNORE_ENTRIES = [
+	".claude/_profiles/",
+	".claude/settings.json",
+	".claude/skills",
+	".claude/models.json",
+	".mcp.json",
+];
+
+/** The generated, gitignored directory holding materialized profiles. */
+export function profilesRoot(projectPath?: string): string {
+	const base = projectPath ?? process.cwd();
+	return path.join(base, ".claude", "_profiles");
+}
+
+/** The materialized directory for one profile. */
+export function profileDir(name: string, projectPath?: string): string {
+	return path.join(profilesRoot(projectPath), name);
+}
+
+/** The artifacts an active profile links into place. */
+export type ProfileLinkKey = "settings" | "skills" | "mcp" | "models";
+
+/** The set of links an active profile owns, as [linkPath, targetPath] pairs. */
+export function linkTargets(
+	name: string,
+	projectPath?: string,
+): Array<{ key: ProfileLinkKey; link: string; target: string }> {
+	const base = projectPath ?? process.cwd();
+	const dir = profileDir(name, projectPath);
+	return [
+		{
+			key: "settings",
+			link: path.join(base, ".claude", "settings.json"),
+			target: path.join(dir, "settings.json"),
+		},
+		{
+			key: "skills",
+			link: path.join(base, ".claude", "skills"),
+			target: path.join(dir, "skills"),
+		},
+		{
+			key: "mcp",
+			link: path.join(base, ".mcp.json"),
+			target: path.join(dir, "mcp.json"),
+		},
+		{
+			key: "models",
+			link: path.join(base, ".claude", "models.json"),
+			target: path.join(dir, "models.json"),
+		},
+	];
+}
+
+/**
+ * Point `link` at `target` with a relative symlink. Any existing file, dir, or
+ * link at `link` is removed first. The target need not exist yet (dangling
+ * links are tolerated so a profile can be activated before every artifact is
+ * materialized), but its parent is created.
+ */
+async function relink(link: string, target: string): Promise<void> {
+	await fs.ensureDir(path.dirname(link));
+	await fs.remove(link);
+	const rel = path.relative(path.dirname(link), target);
+	await fs.symlink(rel, link);
+}
+
+/**
+ * Activate a profile: repoint every shared-config symlink into its
+ * materialized directory. Only links whose target exists in the profile dir
+ * are created (e.g. a profile with no skills/ dir gets no skills symlink).
+ */
+export async function activateProfile(
+	name: string,
+	projectPath?: string,
+): Promise<void> {
+	const dir = profileDir(name, projectPath);
+	if (!(await fs.pathExists(dir))) {
+		throw new Error(
+			`Profile "${name}" is not materialized (${dir} missing). Run \`magus install ${name}\`.`,
+		);
+	}
+	for (const { link, target } of linkTargets(name, projectPath)) {
+		await syncLink(link, target, projectPath);
+	}
+}
+
+/**
+ * Point one link at its target, or remove it when the profile has no such
+ * artifact. A link is only removed when it points into `_profiles/` — a real
+ * file the user put there is never clobbered.
+ */
+async function syncLink(
+	link: string,
+	target: string,
+	projectPath?: string,
+): Promise<void> {
+	if (await fs.pathExists(target)) {
+		await relink(link, target);
+		return;
+	}
+	if (await isProfileLink(link, projectPath)) await fs.remove(link);
+}
+
+/**
+ * Sync ONE of the active profile's links, leaving the others alone.
+ *
+ * `activateProfile` repoints all four, which is right when switching profiles
+ * and wrong when only one artifact changed: `magus models use` would replace
+ * a project's real `.mcp.json` with a symlink as a side effect of choosing a
+ * model. This is the narrow door for that case.
+ */
+export async function syncProfileLink(
+	name: string,
+	key: ProfileLinkKey,
+	projectPath?: string,
+): Promise<void> {
+	const entry = linkTargets(name, projectPath).find((t) => t.key === key);
+	if (!entry) return;
+	await syncLink(entry.link, entry.target, projectPath);
+}
+
+/** Is `link` a symlink pointing into `.claude/_profiles/`? */
+async function isProfileLink(
+	link: string,
+	projectPath?: string,
+): Promise<boolean> {
+	try {
+		const stat = await fs.lstat(link);
+		if (!stat.isSymbolicLink()) return false;
+		const resolved = path.resolve(path.dirname(link), await fs.readlink(link));
+		return resolved.startsWith(profilesRoot(projectPath) + path.sep);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The name of the currently active profile, derived from where
+ * .claude/settings.json points. Returns null if it isn't a profile symlink.
+ */
+export async function activeProfile(
+	projectPath?: string,
+): Promise<string | null> {
+	const base = projectPath ?? process.cwd();
+	const link = path.join(base, ".claude", "settings.json");
+	try {
+		const stat = await fs.lstat(link);
+		if (!stat.isSymbolicLink()) return null;
+		const resolved = path.resolve(path.dirname(link), await fs.readlink(link));
+		const root = profilesRoot(projectPath) + path.sep;
+		if (!resolved.startsWith(root)) return null;
+		// resolved = <root>/<name>/settings.json → take the first segment.
+		return resolved.slice(root.length).split(path.sep)[0] ?? null;
+	} catch {
+		return null;
+	}
+}

package/src/services/terminology-filler.ts

@@ -0,0 +1,266 @@
+/**
+ * Fill the `terminology` template preset from the project's own codebase.
+ *
+ * `terminology` ships as a template: a vocabulary table with a placeholder row,
+ * useless until someone fills it with THIS project's words. Doing that by hand
+ * means reading the codebase and noticing where two names describe one concept
+ * — exactly the sort of survey a coding agent is good at.
+ *
+ * ## Why Claude only returns rows
+ *
+ * The subprocess is asked for table rows and nothing else; magus does the
+ * file writing. Two reasons, both practical:
+ *
+ *  1. **No write permission is needed.** `claude -p` runs with read-only tools,
+ *     so the worst case of a bad run is a useless answer, never a modified
+ *     repository.
+ *  2. **The template's fixed rules cannot be lost.** Everything below the table
+ *     is substantive guidance that must survive verbatim. Asking a model to
+ *     reproduce a whole file invites it to paraphrase; asking for six table
+ *     rows does not.
+ *
+ * The TUI stays on screen throughout: the child's stdio is piped, never
+ * inherited, so it cannot take the terminal away from OpenTUI the way
+ * `runClaude` deliberately does for CLI use.
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "fs-extra";
+import { which } from "../utils/command-utils.js";
+
+export interface TerminologyRow {
+	use: string;
+	not: string;
+	because: string;
+}
+
+/** The placeholder row the shipped template carries. */
+const PLACEHOLDER = /^\|.*filled during.*\|.*$/im;
+
+/** Table rows are asked for in this exact shape, so the parse can be strict. */
+export function parseTerminologyRows(stdout: string): TerminologyRow[] {
+	const rows: TerminologyRow[] = [];
+	for (const raw of stdout.split("\n")) {
+		const line = raw.trim();
+		if (!line.startsWith("|")) continue;
+
+		// The trailing pipe is optional. Both are valid markdown and a model
+		// asked for `| a | b | c |` will sometimes emit it without the closer —
+		// discarding that row would silently lose a real term.
+		const cells = line
+			.slice(1)
+			.replace(/\|$/, "")
+			.split("|")
+			.map((cell) => cell.trim());
+		if (cells.length !== 3) continue;
+
+		// A model that ignores "no header row" tends to emit the header and the
+		// `|---|---|---|` separator anyway. Both are noise, not data.
+		if (cells.every((cell) => /^:?-{2,}:?$/.test(cell))) continue;
+		if (cells[0].toLowerCase() === "use" && cells[1].toLowerCase() === "not") {
+			continue;
+		}
+		if (!cells[0] || !cells[1]) continue;
+
+		rows.push({ use: cells[0], not: cells[1], because: cells[2] });
+	}
+	return rows;
+}
+
+/**
+ * Put the rows into the template, replacing its placeholder.
+ *
+ * Everything else in the body — the heading, the opening statement, and the
+ * rules below the table — is copied through untouched.
+ */
+export function fillTemplate(
+	templateBody: string,
+	rows: TerminologyRow[],
+): string {
+	if (rows.length === 0) {
+		throw new Error("No usable table rows were produced.");
+	}
+	const rendered = rows
+		.map((row) => `| ${row.use} | ${row.not} | ${row.because} |`)
+		.join("\n");
+
+	if (PLACEHOLDER.test(templateBody)) {
+		return templateBody.replace(PLACEHOLDER, rendered);
+	}
+	// The template changed shape upstream. Appending after the separator is
+	// still better than silently returning a table with no rows.
+	return templateBody.replace(/^(\|\s*-{2,}.*\|)\s*$/im, `$1\n${rendered}`);
+}
+
+/** The complete output-style file for the filled terminology preset. */
+export function terminologyStyleFile(body: string): string {
+	return [
+		"---",
+		"name: terminology",
+		'description: "Project vocabulary — one name per concept"',
+		// Same reasoning as everywhere else: a communication style must not
+		// switch off Claude Code's coding rules.
+		"keep-coding-instructions: true",
+		'generated-by: "magus Styles tab, filled from the codebase by Claude Code."',
+		"---",
+		"",
+		body.trim(),
+		"",
+	].join("\n");
+}
+
+export function buildPrompt(templateBody: string): string {
+	return [
+		"You are filling in one table for a project's communication-style guide.",
+		"",
+		"Read enough of this codebase to identify its domain vocabulary: the nouns",
+		"that name its core concepts, and the places where two different words are",
+		"used for the same thing.",
+		"",
+		"Output ONLY markdown table rows, one per line, in exactly this form:",
+		"",
+		"| use | not | because |",
+		"",
+		"Rules:",
+		"- No header row, no `|---|` separator, no code fence, no commentary.",
+		"- Between 5 and 15 rows.",
+		// Bounded on purpose: without a budget this wanders a large repository
+		// for many minutes, and the marginal term found on the 80th file is not
+		// worth the wait.
+		"- Budget yourself: read at most ~25 files. Prefer README, the main",
+		"  entry points, type definitions and directory names over exhaustive",
+		"  coverage — the vocabulary shows up there first.",
+		"- Every row must come from THIS codebase. Do not invent generic examples.",
+		"- `use` is the name the project should standardise on.",
+		"- `not` is a synonym actually present in the repo, or one a newcomer would",
+		"  plausibly reach for.",
+		"- `because` is one clause, lower case, no trailing full stop.",
+		"",
+		"For context, this is the guide the table goes into:",
+		"",
+		templateBody,
+	].join("\n");
+}
+
+/**
+ * How long to let the survey run before giving up.
+ *
+ * Generous, because reading a large repository legitimately takes minutes — but
+ * bounded, because without it a wedged subprocess leaves the screen showing
+ * "reading the codebase" forever with no way back.
+ */
+export const FILL_TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface FillTerminologyArgs {
+	projectPath: string;
+	/** Body of the shipped `terminology` preset, table placeholder included. */
+	templateBody: string;
+	/** Injectable for tests. Returns the subprocess's stdout. */
+	run?: (prompt: string, projectPath: string) => Promise<string>;
+}
+
+export interface FillTerminologyResult {
+	path: string;
+	rows: TerminologyRow[];
+}
+
+/**
+ * Run Claude Code over the project and write the filled preset.
+ *
+ * Written to the PROJECT's output-styles directory, so the vocabulary it
+ * discovers commits with the repository — a project's terminology is a team
+ * fact, not one person's setting.
+ */
+export async function fillTerminology({
+	projectPath,
+	templateBody,
+	run = runClaudeHeadless,
+}: FillTerminologyArgs): Promise<FillTerminologyResult> {
+	const stdout = await run(buildPrompt(templateBody), projectPath);
+	const rows = parseTerminologyRows(stdout);
+	if (rows.length === 0) {
+		throw new Error(
+			"Claude Code returned no usable table rows — nothing was written.",
+		);
+	}
+
+	const file = path.join(
+		projectPath,
+		".claude",
+		"output-styles",
+		"terminology.md",
+	);
+	await fs.ensureDir(path.dirname(file));
+	await fs.writeFile(
+		file,
+		terminologyStyleFile(fillTemplate(templateBody, rows)),
+		"utf8",
+	);
+	return { path: file, rows };
+}
+
+/**
+ * `claude -p` with read-only tools, stdio piped.
+ *
+ * `--allowedTools` is the point: the subprocess can look at the repository and
+ * cannot change it, so a bad run costs time and nothing else.
+ */
+async function runClaudeHeadless(
+	prompt: string,
+	projectPath: string,
+): Promise<string> {
+	const claudePath = await which("claude");
+	if (!claudePath) {
+		throw new Error(
+			"claude CLI not found in PATH. Install it with: npm install -g @anthropic-ai/claude-code",
+		);
+	}
+
+	return new Promise((resolve, reject) => {
+		const child = spawn(
+			claudePath,
+			["-p", prompt, "--allowedTools", "Read,Grep,Glob"],
+			{
+				cwd: projectPath,
+				// Piped, never inherited — inheriting would hand our TTY to the
+				// child and tear the TUI apart mid-render.
+				stdio: ["ignore", "pipe", "pipe"],
+			},
+		);
+
+		let out = "";
+		let err = "";
+		child.stdout.on("data", (chunk) => {
+			out += String(chunk);
+		});
+		child.stderr.on("data", (chunk) => {
+			err += String(chunk);
+		});
+
+		const timer = setTimeout(() => {
+			child.kill("SIGTERM");
+			reject(
+				new Error(
+					`Gave up after ${Math.round(FILL_TIMEOUT_MS / 60000)} minutes — nothing was written. Try again, or fill the table by hand.`,
+				),
+			);
+		}, FILL_TIMEOUT_MS);
+
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.once("close", (code) => {
+			clearTimeout(timer);
+			if (code === 0) resolve(out);
+			else {
+				reject(
+					new Error(
+						`claude exited ${code}${err.trim() ? `: ${err.trim().split("\n")[0]}` : ""}`,
+					),
+				);
+			}
+		});
+	});
+}