magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/gitignore-detector.ts

@@ -0,0 +1,167 @@
+/**
+ * Detect violations of the resolved gitignore manifest against a working
+ * tree. Emits one Violation per offending path.
+ *
+ * Strategy:
+ *   - For ignore rules: ask `git ls-files` whether the path (or anything
+ *     under it for directory-style rules) is currently tracked. If so,
+ *     it's "tracked-but-should-ignore" (destructive). Then check whether
+ *     the existing .gitignore covers the path; if not, that's
+ *     "missing-from-gitignore" (safe additive fix).
+ *   - For track rules: ask `git check-ignore` whether the path is being
+ *     excluded by the current .gitignore. If yes, "ignored-but-should-track"
+ *     (destructive — must remove the .gitignore line). If the path exists
+ *     on disk but isn't tracked and isn't ignored, "untracked-and-should-track".
+ *
+ * Glob expansion is intentionally limited: we treat patterns as literals
+ * with directory-suffix awareness ("foo/" matches anything under foo/).
+ * Full gitignore-syntax glob expansion is deferred — git itself handles
+ * the heavy lifting via ls-files / check-ignore.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ResolvedManifest, Violation } from "../types/gitignore.js";
+
+export async function detectViolations(
+	cwd: string,
+	resolved: ResolvedManifest,
+): Promise<Violation[]> {
+	if (!(await isGitRepo(cwd))) return [];
+
+	const violations: Violation[] = [];
+	const trackedFiles = await listTrackedFiles(cwd);
+	const trackedSet = new Set(trackedFiles);
+
+	for (const rule of resolved.rules) {
+		if (rule.action === "ignore") {
+			const tracked = matchesTrackedFile(rule.pattern, trackedSet);
+			if (tracked.length > 0) {
+				for (const path of tracked) {
+					violations.push({
+						kind: "tracked-but-should-ignore",
+						path,
+						source: rule.source,
+						severity: "destructive",
+					});
+				}
+			} else {
+				// Not tracked — check if .gitignore covers it. If not, suggest
+				// a safe additive fix (append to .gitignore).
+				const ignored = await pathIsIgnored(cwd, rule.pattern);
+				if (!ignored) {
+					violations.push({
+						kind: "missing-from-gitignore",
+						path: rule.pattern,
+						source: rule.source,
+						severity: "safe",
+					});
+				}
+			}
+		} else {
+			// action === "track"
+			const ignored = await pathIsIgnored(cwd, rule.pattern);
+			if (ignored) {
+				violations.push({
+					kind: "ignored-but-should-track",
+					path: rule.pattern,
+					source: rule.source,
+					severity: "destructive",
+				});
+				continue;
+			}
+			const isTracked = trackedSet.has(rule.pattern);
+			const existsOnDisk = existsSync(join(cwd, rule.pattern));
+			if (existsOnDisk && !isTracked) {
+				violations.push({
+					kind: "untracked-and-should-track",
+					path: rule.pattern,
+					source: rule.source,
+					severity: "destructive",
+				});
+			}
+		}
+	}
+
+	return violations;
+}
+
+/**
+ * Match a pattern against the tracked-files set. Directory-style patterns
+ * (trailing "/") match every tracked path under that prefix.
+ */
+function matchesTrackedFile(pattern: string, tracked: Set<string>): string[] {
+	if (pattern.endsWith("/")) {
+		const prefix = pattern;
+		return Array.from(tracked).filter((p) => p.startsWith(prefix));
+	}
+	if (pattern.includes("*")) {
+		// Very limited literal-prefix glob handling. Full expansion is git's job.
+		const star = pattern.indexOf("*");
+		const prefix = pattern.slice(0, star);
+		return Array.from(tracked).filter((p) => p.startsWith(prefix));
+	}
+	return tracked.has(pattern) ? [pattern] : [];
+}
+
+async function isGitRepo(cwd: string): Promise<boolean> {
+	try {
+		await runGit(["rev-parse", "--is-inside-work-tree"], cwd);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function listTrackedFiles(cwd: string): Promise<string[]> {
+	try {
+		const out = await runGit(["ls-files"], cwd);
+		return out
+			.split("\n")
+			.map((l) => l.trim())
+			.filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+async function pathIsIgnored(cwd: string, path: string): Promise<boolean> {
+	try {
+		// git check-ignore exits 0 when path IS ignored, 1 when NOT, >1 on error.
+		await runGit(["check-ignore", "--quiet", "--", path], cwd);
+		return true;
+	} catch (err) {
+		// exit code 1 = not ignored (expected), anything else swallowed.
+		if (err instanceof GitError && err.code === 1) return false;
+		return false;
+	}
+}
+
+class GitError extends Error {
+	constructor(
+		public code: number,
+		public stderr: string,
+	) {
+		super(`git exited ${code}: ${stderr}`);
+	}
+}
+
+function runGit(args: string[], cwd: string): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const proc = spawn("git", args, { cwd });
+		let stdout = "";
+		let stderr = "";
+		proc.stdout.on("data", (b) => {
+			stdout += b.toString();
+		});
+		proc.stderr.on("data", (b) => {
+			stderr += b.toString();
+		});
+		proc.on("error", reject);
+		proc.on("close", (code) => {
+			if (code === 0) resolve(stdout);
+			else reject(new GitError(code ?? -1, stderr));
+		});
+	});
+}

package/src/services/gitignore-fixer.ts

@@ -0,0 +1,280 @@
+/**
+ * Apply fixes for gitignore violations. Two flavors:
+ *
+ *   - `applySafeFixes`: additive — appends missing patterns to .gitignore
+ *     under a "# Added by magus" header. Idempotent (re-running is a no-op
+ *     because patterns are already present).
+ *
+ *   - `applyDestructiveFix`: index-mutating — runs `git rm --cached <path>`
+ *     for tracked-but-should-ignore, `git add <path>` (after making sure
+ *     gitignore has any needed `!` exceptions) for ignored-but-should-track /
+ *     untracked-and-should-track.
+ *     Each call handles ONE violation; the caller is responsible for confirming
+ *     each one with the user.
+ *
+ * `formatViolationSummary` is a pure helper for the warning line + TUI.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getGitignoreRuleReason } from "../data/gitignore-reasons.js";
+import type { Violation } from "../types/gitignore.js";
+
+const MAGUS_HEADER = "# Added by magus";
+
+export interface SafeFixResult {
+	appended: string[];
+	alreadyPresent: string[];
+}
+
+export async function applySafeFixes(
+	cwd: string,
+	violations: Violation[],
+): Promise<SafeFixResult> {
+	const safe = violations.filter(
+		(v) => v.severity === "safe" && v.kind === "missing-from-gitignore",
+	);
+	if (safe.length === 0) {
+		return { appended: [], alreadyPresent: [] };
+	}
+
+	const gitignorePath = join(cwd, ".gitignore");
+	const existing = existsSync(gitignorePath)
+		? await readFile(gitignorePath, "utf8")
+		: "";
+	const lines = new Set(
+		existing
+			.split("\n")
+			.map((l) => l.trim())
+			.filter(Boolean),
+	);
+
+	const appended: string[] = [];
+	const alreadyPresent: string[] = [];
+	for (const v of safe) {
+		if (lines.has(v.path)) {
+			alreadyPresent.push(v.path);
+		} else {
+			appended.push(v.path);
+			lines.add(v.path);
+		}
+	}
+
+	if (appended.length === 0) return { appended, alreadyPresent };
+
+	const block = [
+		"",
+		MAGUS_HEADER,
+		...appended.flatMap(formatGitignoreEntry),
+		"",
+	].join("\n");
+
+	if (existing.length > 0 && !existing.endsWith("\n")) {
+		await appendFile(gitignorePath, `\n${block}`);
+	} else {
+		await appendFile(gitignorePath, block);
+	}
+
+	return { appended, alreadyPresent };
+}
+
+export interface DestructiveFixResult {
+	applied: boolean;
+	message: string;
+}
+
+export async function applyDestructiveFix(
+	cwd: string,
+	violation: Violation,
+	rulePattern = violation.path,
+): Promise<DestructiveFixResult> {
+	switch (violation.kind) {
+		case "tracked-but-should-ignore": {
+			await runGit(["rm", "--cached", "--", violation.path], cwd);
+			// Then make sure .gitignore has the entry so it stays out
+			await appendIfMissing(cwd, rulePattern);
+			return {
+				applied: true,
+				message: `Removed ${violation.path} from index and added ${rulePattern} to .gitignore`,
+			};
+		}
+		case "ignored-but-should-track": {
+			await stripGitignoreLine(cwd, violation.path);
+			await appendTrackExceptionsIfNeeded(cwd, violation.path);
+			if (!existsSync(join(cwd, violation.path))) {
+				return {
+					applied: true,
+					message: `Made ${violation.path} trackable; file does not exist yet`,
+				};
+			}
+			try {
+				await runGit(["add", "--", violation.path], cwd);
+			} catch (err) {
+				return {
+					applied: false,
+					message: `Removed .gitignore line but git add failed: ${
+						err instanceof Error ? err.message : String(err)
+					}`,
+				};
+			}
+			return {
+				applied: true,
+				message: `Removed .gitignore line and staged ${violation.path}`,
+			};
+		}
+		case "untracked-and-should-track": {
+			await appendTrackExceptionsIfNeeded(cwd, violation.path);
+			await runGit(["add", "--", violation.path], cwd);
+			return { applied: true, message: `Staged ${violation.path}` };
+		}
+		case "missing-from-gitignore": {
+			// Treat as a safe append for symmetry — caller can route through here too.
+			await appendIfMissing(cwd, rulePattern);
+			return { applied: true, message: `Added ${rulePattern} to .gitignore` };
+		}
+	}
+}
+
+export function formatViolationSummary(violations: Violation[]): string {
+	if (violations.length === 0) return "No gitignore issues detected.";
+
+	const byKind = new Map<string, Violation[]>();
+	for (const v of violations) {
+		const arr = byKind.get(v.kind) ?? [];
+		arr.push(v);
+		byKind.set(v.kind, arr);
+	}
+
+	const labels: Record<Violation["kind"], string> = {
+		"tracked-but-should-ignore": "tracked but should be ignored",
+		"ignored-but-should-track": "ignored but should be tracked",
+		"untracked-and-should-track": "exist but not tracked (should be)",
+		"missing-from-gitignore": "missing from .gitignore",
+	};
+
+	const lines: string[] = [];
+	for (const [kind, vs] of byKind.entries()) {
+		lines.push(`  ${labels[kind as Violation["kind"]]}: ${vs.length}`);
+		for (const v of vs.slice(0, 5)) {
+			lines.push(`    - ${v.path}`);
+		}
+		if (vs.length > 5) lines.push(`    … and ${vs.length - 5} more`);
+	}
+	return lines.join("\n");
+}
+
+async function appendIfMissing(cwd: string, pattern: string): Promise<void> {
+	const gitignorePath = join(cwd, ".gitignore");
+	const existing = existsSync(gitignorePath)
+		? await readFile(gitignorePath, "utf8")
+		: "";
+	const lines = existing.split("\n").map((l) => l.trim());
+	if (lines.includes(pattern)) return;
+	// Only emit the "# Added by magus" header once — when fixing several
+	// entries in one pass (F), the file already has the header from the first.
+	const needsHeader = !lines.includes(MAGUS_HEADER);
+	const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+	const header = needsHeader ? `${MAGUS_HEADER}\n` : "";
+	const block = `${prefix}${header}${formatGitignoreEntry(pattern).join("\n")}\n`;
+	await appendFile(gitignorePath, block);
+}
+
+function formatGitignoreEntry(pattern: string): string[] {
+	return [`# ${getGitignoreRuleReason("ignore", pattern)}`, pattern];
+}
+
+async function appendTrackExceptionsIfNeeded(
+	cwd: string,
+	path: string,
+): Promise<void> {
+	if (!(await pathIsIgnored(cwd, path))) return;
+
+	const gitignorePath = join(cwd, ".gitignore");
+	const existing = existsSync(gitignorePath)
+		? await readFile(gitignorePath, "utf8")
+		: "";
+	const lines = new Set(
+		existing
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean),
+	);
+	const additions = unignorePatternsForPath(path).filter(
+		(line) => !lines.has(line),
+	);
+	if (additions.length === 0) return;
+
+	const block = [
+		existing.length > 0 && !existing.endsWith("\n") ? "\n" : "",
+		MAGUS_HEADER,
+		`# ${getGitignoreRuleReason("track", path)}`,
+		...additions,
+		"",
+	].join("\n");
+	await appendFile(gitignorePath, block);
+}
+
+function unignorePatternsForPath(path: string): string[] {
+	const normalized = path.replace(/^\/+/, "").replace(/\/+$/, "");
+	if (!normalized) return [];
+	const parts = normalized.split("/");
+	const patterns: string[] = [];
+	for (let i = 0; i < parts.length - 1; i++) {
+		patterns.push(`!/${parts.slice(0, i + 1).join("/")}/`);
+	}
+	patterns.push(`!/${normalized}`);
+	return patterns;
+}
+
+async function stripGitignoreLine(cwd: string, pattern: string): Promise<void> {
+	const gitignorePath = join(cwd, ".gitignore");
+	if (!existsSync(gitignorePath)) return;
+	const content = await readFile(gitignorePath, "utf8");
+	const filtered = content
+		.split("\n")
+		.filter((line) => line.trim() !== pattern)
+		.join("\n");
+	if (filtered !== content) {
+		await writeFile(gitignorePath, filtered);
+	}
+}
+
+async function pathIsIgnored(cwd: string, path: string): Promise<boolean> {
+	try {
+		await runGit(["check-ignore", "--quiet", "--", path], cwd);
+		return true;
+	} catch (err) {
+		if (err instanceof GitError && err.code === 1) return false;
+		return false;
+	}
+}
+
+class GitError extends Error {
+	constructor(
+		public code: number,
+		public stderr: string,
+	) {
+		super(`git exited ${code}: ${stderr}`);
+	}
+}
+
+function runGit(args: string[], cwd: string): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const proc = spawn("git", args, { cwd });
+		let stdout = "";
+		let stderr = "";
+		proc.stdout.on("data", (b) => {
+			stdout += b.toString();
+		});
+		proc.stderr.on("data", (b) => {
+			stderr += b.toString();
+		});
+		proc.on("error", reject);
+		proc.on("close", (code) => {
+			if (code === 0) resolve(stdout);
+			else reject(new GitError(code ?? -1, stderr));
+		});
+	});
+}

package/src/services/gitignore-resolver.ts

@@ -0,0 +1,208 @@
+/**
+ * Three-tier gitignore manifest resolver.
+ *
+ * Precedence (lowest → highest, last-wins):
+ *   1. Built-in defaults (shipped with magus)
+ *   2. Global manifest at ~/.claude/gitignore.json (team-level, manually shared)
+ *   3. Project manifest at <cwd>/.claude/gitignore.json
+ *
+ * `extends` references are resolved against BUILTIN_TEMPLATES. Within a single
+ * tier, the same pattern cannot appear in both `ignore` and `track` — that
+ * throws. Across tiers, the higher-precedence tier wins; losers are recorded
+ * in `conflicts` so the TUI can show "global says ignore .env, project
+ * overrides to track."
+ */
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BUILTIN_DEFAULTS } from "../data/gitignore-defaults.js";
+import { BUILTIN_TEMPLATES } from "../data/gitignore-templates.js";
+import type {
+	GitignoreManifest,
+	ResolvedConflict,
+	ResolvedManifest,
+	ResolvedRule,
+	RuleAction,
+	Tier,
+} from "../types/gitignore.js";
+
+export interface ResolveOptions {
+	/** Override $HOME (test seam). */
+	homeDir?: string;
+	/** Optional logger for non-fatal warnings (malformed JSON, missing template). */
+	logger?: (msg: string) => void;
+}
+
+const TIER_ORDER: Tier[] = ["builtin", "global", "project"];
+
+export async function resolveGitignore(
+	projectCwd: string,
+	opts: ResolveOptions = {},
+): Promise<ResolvedManifest> {
+	const home = opts.homeDir ?? homedir();
+	const log = opts.logger ?? (() => {});
+
+	const tierManifests = new Map<Tier, GitignoreManifest>();
+
+	// 1. Built-in (always present)
+	tierManifests.set("builtin", BUILTIN_DEFAULTS);
+
+	// 2. Global ~/.claude/gitignore.json
+	const globalPath = join(home, ".claude", "gitignore.json");
+	const globalManifest = await readManifest(globalPath, log);
+	if (globalManifest) tierManifests.set("global", globalManifest);
+
+	// 3. Project .claude/gitignore.json
+	const projectPath = join(projectCwd, ".claude", "gitignore.json");
+	const projectManifest = await readManifest(projectPath, log);
+	if (projectManifest) tierManifests.set("project", projectManifest);
+
+	// Apply `extends` for each tier (templates count as part of their tier)
+	for (const tier of TIER_ORDER) {
+		const m = tierManifests.get(tier);
+		if (!m?.extends?.length) continue;
+		const merged: GitignoreManifest = {
+			ignore: [...m.ignore],
+			track: [...m.track],
+		};
+		for (const tplName of m.extends) {
+			const tpl = BUILTIN_TEMPLATES[tplName];
+			if (!tpl) {
+				log(`[gitignore] unknown template "${tplName}" in ${tier} manifest`);
+				continue;
+			}
+			merged.ignore.push(...tpl.ignore);
+			merged.track.push(...tpl.track);
+		}
+		tierManifests.set(tier, merged);
+	}
+
+	// Validate intra-tier consistency
+	for (const [tier, m] of tierManifests.entries()) {
+		const ig = new Set(m.ignore);
+		for (const t of m.track) {
+			if (ig.has(t)) {
+				throw new Error(
+					`Intra-tier conflict in ${tier} manifest: "${t}" is in both ignore and track`,
+				);
+			}
+		}
+	}
+
+	// Merge across tiers — last-wins, track conflicts
+	const ruleByPattern = new Map<
+		string,
+		{
+			action: RuleAction;
+			source: Tier;
+			history: Array<{ tier: Tier; action: RuleAction }>;
+		}
+	>();
+
+	for (const tier of TIER_ORDER) {
+		const m = tierManifests.get(tier);
+		if (!m) continue;
+		for (const p of dedupe(m.ignore)) {
+			pushRule(ruleByPattern, p, "ignore", tier);
+		}
+		for (const p of dedupe(m.track)) {
+			pushRule(ruleByPattern, p, "track", tier);
+		}
+	}
+
+	const rules: ResolvedRule[] = [];
+	const conflicts: ResolvedConflict[] = [];
+
+	for (const [pattern, entry] of ruleByPattern.entries()) {
+		rules.push({ pattern, action: entry.action, source: entry.source });
+
+		const losers = entry.history.filter(
+			(h) => h.tier !== entry.source || h.action !== entry.action,
+		);
+		if (losers.length > 0 && hasActionDisagreement(entry.history)) {
+			conflicts.push({
+				pattern,
+				winner: entry.source,
+				losers: losers.filter((l) => l.action !== entry.action),
+			});
+		}
+	}
+
+	return { rules, conflicts };
+}
+
+function pushRule(
+	map: Map<
+		string,
+		{
+			action: RuleAction;
+			source: Tier;
+			history: Array<{ tier: Tier; action: RuleAction }>;
+		}
+	>,
+	pattern: string,
+	action: RuleAction,
+	tier: Tier,
+): void {
+	const existing = map.get(pattern);
+	if (existing) {
+		existing.history.push({ tier, action });
+		existing.action = action;
+		existing.source = tier;
+	} else {
+		map.set(pattern, { action, source: tier, history: [{ tier, action }] });
+	}
+}
+
+function hasActionDisagreement(
+	history: Array<{ tier: Tier; action: RuleAction }>,
+): boolean {
+	const actions = new Set(history.map((h) => h.action));
+	return actions.size > 1;
+}
+
+function dedupe(xs: string[]): string[] {
+	return Array.from(new Set(xs));
+}
+
+async function readManifest(
+	path: string,
+	log: (msg: string) => void,
+): Promise<GitignoreManifest | null> {
+	if (!existsSync(path)) return null;
+	try {
+		const raw = await readFile(path, "utf8");
+		const parsed = JSON.parse(raw);
+		if (!isManifest(parsed)) {
+			log(
+				`[gitignore] ${path} is not a valid manifest (expected { ignore: string[], track: string[] })`,
+			);
+			return null;
+		}
+		return parsed;
+	} catch (err) {
+		log(
+			`[gitignore] failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return null;
+	}
+}
+
+function isManifest(x: unknown): x is GitignoreManifest {
+	if (!x || typeof x !== "object") return false;
+	const m = x as Record<string, unknown>;
+	if (!Array.isArray(m.ignore) || !m.ignore.every((p) => typeof p === "string"))
+		return false;
+	if (!Array.isArray(m.track) || !m.track.every((p) => typeof p === "string"))
+		return false;
+	if (m.extends !== undefined) {
+		if (
+			!Array.isArray(m.extends) ||
+			!m.extends.every((p) => typeof p === "string")
+		)
+			return false;
+	}
+	return true;
+}