magus-cli 7.9.1 → 7.10.1

package/src/__tests__/worktree-profiles.test.ts

@@ -0,0 +1,583 @@
+/**
+ * The other working trees of a repository that carry a magus manifest but have
+ * no profile in effect — found read-only, then set up with the declared profile.
+ *
+ * Written from the spec alone (docs/plans/2026-10-09-worktree-profile-setup.md,
+ * "Fix 2"), never from the implementation. Exercised against real git
+ * repositories with real linked worktrees: the function exists to agree with
+ * git about which working trees there are, and a stubbed `git worktree list`
+ * would confirm a wrong parse just as happily as a right one.
+ *
+ * Every test builds its own repository under the OS temp dir and runs with HOME
+ * (and the git/XDG config that hangs off it) pointed at a scratch folder, so
+ * nothing here reads or writes the real ~/.claude.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import { clearWorktreeCache } from "../services/git-worktree.js";
+import { detectProfileStartupNeed } from "../services/profile-startup.js";
+import {
+	findUnsetWorktrees,
+	setUpWorktrees,
+} from "../services/worktree-profiles.js";
+import type { ProfileManifest } from "../types/index.js";
+
+const TIMEOUT = 30_000;
+
+// GUESS: a profile with an empty `plugins` map and no marketplaces is a valid
+// manifest entry, and activating it renders the project's files without any
+// install, CLI call or network. The plan asks for "zero or few plugins so
+// activation needs no network"; zero is the surest way to get that.
+const TEAM: ProfileManifest = {
+	version: 2,
+	profiles: {
+		team: { name: "Team", plugins: {} },
+		solo: { name: "Solo", plugins: {} },
+	},
+	default: "team",
+};
+
+/** Same profiles, but this branch declares a different default. */
+const SOLO_DEFAULT: ProfileManifest = { ...TEAM, default: "solo" };
+
+/** Profiles, but no declared default: a human has to choose. */
+const NO_DEFAULT: ProfileManifest = {
+	version: 2,
+	profiles: TEAM.profiles,
+};
+
+// The files magus generates are git-ignored, exactly as in a real profiled
+// project — which is why git never hands them to a new worktree.
+const GITIGNORE = [
+	".claude/settings.json",
+	".mcp.json",
+	".claude/profiles/",
+	"",
+].join("\n");
+
+// Isolate from the operator's git config: signing, a default branch name or a
+// global excludes file would otherwise leak into these repositories.
+const GIT_CFG = [
+	"-c",
+	"user.name=test",
+	"-c",
+	"user.email=test@example.com",
+	"-c",
+	"commit.gpgsign=false",
+	"-c",
+	"init.defaultBranch=main",
+];
+
+const git = (cwd: string, ...args: string[]): string =>
+	execFileSync("git", [...GIT_CFG, ...args], {
+		cwd,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	}).trim();
+
+// ─── Environment isolation ───────────────────────────────────────────────────
+
+/**
+ * Variables that would point git (ours or the module's) somewhere other than
+ * the scratch repository — set when the suite runs from inside a git hook — or
+ * that would let either read the operator's configuration.
+ */
+const ENV_KEYS = [
+	"HOME",
+	"CLAUDE_CONFIG_DIR",
+	"XDG_CONFIG_HOME",
+	"XDG_CACHE_HOME",
+	"GIT_CONFIG_NOSYSTEM",
+	"GIT_CEILING_DIRECTORIES",
+	"GIT_DIR",
+	"GIT_WORK_TREE",
+	"GIT_INDEX_FILE",
+	"GIT_COMMON_DIR",
+	"GIT_OBJECT_DIRECTORY",
+	"GIT_PREFIX",
+] as const;
+
+let savedEnv: Record<string, string | undefined> = {};
+
+function setEnv(key: string, value: string | undefined): void {
+	if (value === undefined) {
+		delete process.env[key];
+	} else {
+		process.env[key] = value;
+	}
+}
+
+// ─── Fixture ─────────────────────────────────────────────────────────────────
+
+interface Fixture {
+	/** realpath'd scratch root: on macOS os.tmpdir() is a symlink, git reports real paths. */
+	base: string;
+	home: string;
+	/** The main working tree, folder "repo", branch main, TEAM manifest. */
+	main: string;
+	/** Linked worktree "alpha", TEAM manifest. */
+	alpha: string;
+	/** Linked worktree "zeta", TEAM manifest. */
+	zeta: string;
+	/** Paths whose permissions a test removed; restored before cleanup. */
+	locked: string[];
+}
+
+let fx: Fixture;
+
+async function writeManifest(
+	tree: string,
+	manifest: ProfileManifest,
+): Promise<void> {
+	await fs.outputFile(
+		path.join(tree, ".claude", "profiles.json"),
+		`${JSON.stringify(manifest, null, 2)}\n`,
+	);
+}
+
+/**
+ * Add a linked worktree at `<base>/<name>` on a new branch.
+ *
+ * `from: "bare"` starts it at the commit before any manifest existed, so the
+ * branch is not a magus project. `manifest` commits a different manifest on
+ * that worktree's own branch.
+ */
+async function addWorktree(
+	name: string,
+	opts: { from?: "bare" | "main"; manifest?: ProfileManifest } = {},
+): Promise<string> {
+	const at = path.join(fx.base, name);
+	const start = opts.from === "bare" ? "bare" : "main";
+	git(fx.main, "worktree", "add", "-q", "-b", `wt-${name}`, at, start);
+	if (opts.manifest) {
+		await writeManifest(at, opts.manifest);
+		git(at, "add", "-A");
+		git(at, "commit", "-qm", `manifest for ${name}`);
+	}
+	return at;
+}
+
+async function buildFixture(): Promise<Fixture> {
+	const base = await fs.realpath(
+		await fs.mkdtemp(path.join(os.tmpdir(), "magus-wt-profiles-")),
+	);
+	const home = path.join(base, "home");
+	await fs.ensureDir(path.join(home, ".claude"));
+	await fs.ensureDir(path.join(home, ".config"));
+
+	savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+	for (const key of ENV_KEYS) setEnv(key, undefined);
+	setEnv("HOME", home);
+	setEnv("CLAUDE_CONFIG_DIR", path.join(home, ".claude"));
+	setEnv("XDG_CONFIG_HOME", path.join(home, ".config"));
+	setEnv("XDG_CACHE_HOME", path.join(home, ".cache"));
+	setEnv("GIT_CONFIG_NOSYSTEM", "1");
+
+	const main = path.join(base, "repo");
+	await fs.ensureDir(main);
+	git(main, "init", "-q");
+	await fs.writeFile(path.join(main, "README.md"), "hello\n");
+	await fs.writeFile(path.join(main, ".gitignore"), GITIGNORE);
+	git(main, "add", "-A");
+	git(main, "commit", "-qm", "initial");
+	// A branch from before the project adopted magus profiles.
+	git(main, "branch", "bare");
+
+	await writeManifest(main, TEAM);
+	git(main, "add", "-A");
+	git(main, "commit", "-qm", "magus manifest");
+
+	fx = {
+		base,
+		home,
+		main,
+		alpha: "",
+		zeta: "",
+		locked: [],
+	};
+	// Created out of name order, so a sorted result is the module's doing.
+	fx.zeta = await addWorktree("zeta");
+	fx.alpha = await addWorktree("alpha");
+	return fx;
+}
+
+beforeEach(async () => {
+	clearWorktreeCache();
+	await buildFixture();
+});
+
+afterEach(async () => {
+	for (const p of fx.locked) {
+		try {
+			await fs.chmod(p, 0o755);
+		} catch {
+			// already gone
+		}
+	}
+	for (const [key, value] of Object.entries(savedEnv)) setEnv(key, value);
+	await fs.remove(fx.base);
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Every path under `root` with its type, size and mtime — directories too,
+ * since a created-then-removed file still moves its directory's mtime. lstat,
+ * so a symlink is recorded as itself and never followed out of the tree.
+ */
+async function snapshot(root: string): Promise<string[]> {
+	const out: string[] = [];
+	async function walk(dir: string): Promise<void> {
+		const entries = await fs.readdir(dir);
+		for (const entry of entries) {
+			const full = path.join(dir, entry);
+			const st = await fs.lstat(full);
+			const kind = st.isDirectory() ? "d" : st.isSymbolicLink() ? "l" : "f";
+			out.push(`${path.relative(root, full)} ${kind} ${st.size} ${st.mtimeMs}`);
+			if (st.isDirectory()) await walk(full);
+		}
+	}
+	const st = await fs.lstat(root);
+	out.push(`. d ${st.size} ${st.mtimeMs}`);
+	await walk(root);
+	return out.sort();
+}
+
+/** A tree's snapshot without its `.git` entry (a linked worktree's is a file). */
+async function snapshotTree(tree: string): Promise<string[]> {
+	return (await snapshot(tree)).filter(
+		(line) => !line.startsWith(".git ") && !line.startsWith(`.git${path.sep}`),
+	);
+}
+
+const names = (list: { name: string }[]): string[] => list.map((w) => w.name);
+
+async function stateOf(tree: string): Promise<string> {
+	return (await detectProfileStartupNeed(tree)).state;
+}
+
+// ─── findUnsetWorktrees ──────────────────────────────────────────────────────
+
+describe("findUnsetWorktrees", () => {
+	test(
+		"from the main tree: every linked worktree with a manifest and no profile, sorted by name, main excluded",
+		async () => {
+			const found = await findUnsetWorktrees(fx.main);
+
+			// zeta was created first; the order is the module's sort, not git's.
+			expect(names(found)).toEqual(["alpha", "zeta"]);
+			expect(names(found)).toEqual([...names(found)].sort());
+			expect(names(found)).not.toContain("repo");
+
+			const byName = new Map(found.map((w) => [w.name, w]));
+			for (const [name, tree] of [
+				["alpha", fx.alpha],
+				["zeta", fx.zeta],
+			] as const) {
+				const entry = byName.get(name);
+				expect(entry).toBeDefined();
+				if (!entry) continue;
+				expect(path.isAbsolute(entry.path)).toBe(true);
+				expect(entry.path).toBe(tree);
+				expect(entry.name).toBe(path.basename(tree));
+				expect(entry.state).not.toBe("ok");
+				// The state is detectProfileStartupNeed's, for THAT tree.
+				expect(entry.state).toBe(await stateOf(tree));
+				// A fresh worktree of a repo that declares its default: nothing to
+				// replace, so it can be set up without asking.
+				expect(entry.declaredDefault).toBe("team");
+				expect(entry.autoActivate).toBe(true);
+			}
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"from a linked worktree: the unset main tree is listed, the caller's own tree is not",
+		async () => {
+			const found = await findUnsetWorktrees(fx.zeta);
+
+			// "repo" sorts after "alpha" though git lists the main tree first.
+			expect(names(found)).toEqual(["alpha", "repo"]);
+			expect(names(found)).not.toContain("zeta");
+			const mainEntry = found.find((w) => w.name === "repo");
+			expect(mainEntry?.path).toBe(fx.main);
+			expect(mainEntry?.state).not.toBe("ok");
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"called from a subfolder, that folder's own working tree is still excluded",
+		async () => {
+			const sub = path.join(fx.main, "packages", "app");
+			await fs.ensureDir(sub);
+
+			const found = await findUnsetWorktrees(sub);
+
+			expect(names(found)).toEqual(["alpha", "zeta"]);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"a worktree whose folder was deleted without `git worktree remove` is skipped, not thrown on",
+		async () => {
+			const gone = await addWorktree("gone");
+			await fs.remove(gone);
+
+			const found = await findUnsetWorktrees(fx.main);
+
+			expect(names(found)).toEqual(["alpha", "zeta"]);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"a worktree on a branch without a manifest is skipped",
+		async () => {
+			await addWorktree("before-magus", { from: "bare" });
+			expect(
+				await fs.pathExists(
+					path.join(fx.base, "before-magus", ".claude", "profiles.json"),
+				),
+			).toBe(false);
+
+			const found = await findUnsetWorktrees(fx.main);
+
+			expect(names(found)).toEqual(["alpha", "zeta"]);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"a worktree that needs a choice is listed, but not as automatic",
+		async () => {
+			// No declared default on this branch: someone has to pick.
+			const choose = await addWorktree("choose", { manifest: NO_DEFAULT });
+			// A declared default, but a hand-written settings file would be replaced.
+			const kept = await addWorktree("kept");
+			await fs.outputJson(path.join(kept, ".claude", "settings.json"), {
+				enabledPlugins: { "dev@magus": true },
+			});
+
+			const found = await findUnsetWorktrees(fx.main);
+			const byName = new Map(found.map((w) => [w.name, w]));
+
+			expect(names(found)).toEqual(["alpha", "choose", "kept", "zeta"]);
+			expect(byName.get("choose")?.path).toBe(choose);
+			expect(byName.get("choose")?.declaredDefault).toBeNull();
+			expect(byName.get("choose")?.autoActivate).toBe(false);
+			expect(byName.get("kept")?.autoActivate).toBe(false);
+			expect(byName.get("alpha")?.autoActivate).toBe(true);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"writes nothing: every path and mtime under the repo, the worktrees and HOME is unchanged",
+		async () => {
+			// Include the awkward cases so their code paths run under the snapshot.
+			const gone = await addWorktree("gone");
+			await fs.remove(gone);
+			await addWorktree("before-magus", { from: "bare" });
+			await addWorktree("choose", { manifest: NO_DEFAULT });
+
+			// base holds the main tree (with .git), every worktree, and HOME.
+			const before = await snapshot(fx.base);
+			await findUnsetWorktrees(fx.main);
+			await findUnsetWorktrees(fx.alpha);
+			const after = await snapshot(fx.base);
+
+			expect(after).toEqual(before);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"not a git repository: an empty list",
+		async () => {
+			const plain = path.join(fx.base, "plain");
+			await writeManifest(plain, TEAM);
+			// Stop git's discovery at the temp dir, in case it sits inside a repo.
+			setEnv("GIT_CEILING_DIRECTORIES", path.dirname(fx.base));
+
+			expect(await findUnsetWorktrees(plain)).toEqual([]);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"a worktree that has been set up is no longer listed",
+		async () => {
+			const before = await findUnsetWorktrees(fx.main);
+			const alpha = before.filter((w) => w.name === "alpha");
+			expect(alpha).toHaveLength(1);
+
+			await setUpWorktrees(alpha);
+
+			expect(await stateOf(fx.alpha)).toBe("ok");
+			expect(names(await findUnsetWorktrees(fx.main))).toEqual(["zeta"]);
+		},
+		TIMEOUT,
+	);
+});
+
+// ─── setUpWorktrees ──────────────────────────────────────────────────────────
+
+describe("setUpWorktrees", () => {
+	test(
+		"activates the declared profile in each automatic worktree, from that worktree's own manifest",
+		async () => {
+			// This branch declares a different default — the result must name it.
+			const beta = await addWorktree("beta", { manifest: SOLO_DEFAULT });
+			const mainBefore = await snapshotTree(fx.main);
+
+			const found = await findUnsetWorktrees(fx.main);
+			expect(names(found)).toEqual(["alpha", "beta", "zeta"]);
+
+			const results = await setUpWorktrees(found);
+			const sorted = [...results].sort((a, b) => a.name.localeCompare(b.name));
+
+			expect(sorted).toEqual([
+				{ path: fx.alpha, name: "alpha", ok: true, profileId: "team" },
+				{ path: beta, name: "beta", ok: true, profileId: "solo" },
+				{ path: fx.zeta, name: "zeta", ok: true, profileId: "team" },
+			]);
+			for (const tree of [fx.alpha, beta, fx.zeta]) {
+				expect(await stateOf(tree)).toBe("ok");
+			}
+			expect(await findUnsetWorktrees(fx.main)).toEqual([]);
+
+			// The caller's own tree was not in the list and is not touched: nothing
+			// is copied between worktrees.
+			expect(await snapshotTree(fx.main)).toEqual(mainBefore);
+			expect(await stateOf(fx.main)).not.toBe("ok");
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"the main tree, found from a linked worktree, is set up too",
+		async () => {
+			const found = await findUnsetWorktrees(fx.zeta);
+			const mainEntry = found.filter((w) => w.name === "repo");
+			expect(mainEntry).toHaveLength(1);
+
+			const results = await setUpWorktrees(mainEntry);
+
+			expect(results).toEqual([
+				{ path: fx.main, name: "repo", ok: true, profileId: "team" },
+			]);
+			expect(await stateOf(fx.main)).toBe("ok");
+			expect(names(await findUnsetWorktrees(fx.alpha))).toEqual(["zeta"]);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"entries that are not automatic are neither returned nor touched",
+		async () => {
+			const choose = await addWorktree("choose", { manifest: NO_DEFAULT });
+			const kept = await addWorktree("kept");
+			await fs.outputJson(path.join(kept, ".claude", "settings.json"), {
+				enabledPlugins: { "dev@magus": true },
+			});
+
+			const found = await findUnsetWorktrees(fx.main);
+			expect(found.filter((w) => !w.autoActivate).map((w) => w.name)).toEqual([
+				"choose",
+				"kept",
+			]);
+			const chooseBefore = await snapshotTree(choose);
+			const keptBefore = await snapshotTree(kept);
+
+			const results = await setUpWorktrees(found);
+
+			expect(names(results).sort()).toEqual(["alpha", "zeta"]);
+			expect(results.every((r) => r.ok)).toBe(true);
+			expect(await snapshotTree(choose)).toEqual(chooseBefore);
+			expect(await snapshotTree(kept)).toEqual(keptBefore);
+			expect(names(await findUnsetWorktrees(fx.main))).toEqual([
+				"choose",
+				"kept",
+			]);
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"a worktree deleted after detection fails with a reason; the others still succeed",
+		async () => {
+			const found = await findUnsetWorktrees(fx.main);
+			expect(names(found)).toEqual(["alpha", "zeta"]);
+
+			await fs.remove(fx.alpha);
+			const results = await setUpWorktrees(found);
+
+			const alpha = results.find((r) => r.name === "alpha");
+			const zeta = results.find((r) => r.name === "zeta");
+			expect(results).toHaveLength(2);
+			expect(alpha?.path).toBe(fx.alpha);
+			expect(alpha?.ok).toBe(false);
+			if (alpha && !alpha.ok) {
+				expect(typeof alpha.reason).toBe("string");
+				expect(alpha.reason.trim().length).toBeGreaterThan(0);
+			}
+			expect(zeta).toEqual({
+				path: fx.zeta,
+				name: "zeta",
+				ok: true,
+				profileId: "team",
+			});
+			expect(await stateOf(fx.zeta)).toBe("ok");
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"a worktree that cannot be written fails with a reason; the others still succeed",
+		async () => {
+			const found = await findUnsetWorktrees(fx.main);
+			expect(names(found)).toEqual(["alpha", "zeta"]);
+
+			// Read-only after detection: the folder and its .claude directory.
+			const claudeDir = path.join(fx.zeta, ".claude");
+			fx.locked.push(claudeDir, fx.zeta);
+			await fs.chmod(claudeDir, 0o555);
+			await fs.chmod(fx.zeta, 0o555);
+
+			const results = await setUpWorktrees(found);
+
+			const alpha = results.find((r) => r.name === "alpha");
+			const zeta = results.find((r) => r.name === "zeta");
+			expect(results).toHaveLength(2);
+			expect(zeta?.path).toBe(fx.zeta);
+			expect(zeta?.ok).toBe(false);
+			if (zeta && !zeta.ok) {
+				expect(zeta.reason.trim().length).toBeGreaterThan(0);
+			}
+			expect(alpha).toEqual({
+				path: fx.alpha,
+				name: "alpha",
+				ok: true,
+				profileId: "team",
+			});
+			expect(await stateOf(fx.alpha)).toBe("ok");
+			expect(await stateOf(fx.zeta)).not.toBe("ok");
+		},
+		TIMEOUT,
+	);
+
+	test(
+		"nothing to set up: an empty result",
+		async () => {
+			expect(await setUpWorktrees([])).toEqual([]);
+		},
+		TIMEOUT,
+	);
+});

package/src/cli/doctor.ts

@@ -8,7 +8,8 @@
  *      in `requires` (plus the profiles' cliTools), probed with each
  *      declaration's own check. `--fix` lists every install once, asks once
  *      (`--yes` skips the question) and installs through the deps executor.
- *      `--json` prints only this section, as one document on stdout, and
+ *      `--json` prints only this section and section 6's list, as one
+ *      document on stdout, and
  *      `--fix --json` repairs only this section: dependencies, nothing else.
  *   2. Profile state — which profile is active (strictly), what the next magus
  *      command would record or regenerate (with `--fix`, it does it now and
@@ -18,6 +19,9 @@
  *   3. Convention compliance — .gitignore + CLAUDE.md blocks (ported engine).
  *   4. Model routing — config validity, hook registration, and drift.
  *   5. Plugin loads — what Claude Code will load here vs what is installed.
+ *   6. Worktrees — the repository's other working trees with no profile set
+ *      up, read only (`worktreesWithoutProfile` in `--json`); `magus update`
+ *      sets them up.
  *
  * A file that exists and does not parse — the global settings, the project's
  * `.claude/profiles.json` or its `.claude/settings.json`, Claude Code's
@@ -82,6 +86,7 @@ import {
 	switchHint,
 } from "../services/profile-state.js";
 import { resolveAllProfiles } from "../services/resolver.js";
+import { findUnsetWorktrees } from "../services/worktree-profiles.js";
 import type {
 	ClaudeSettings,
 	InstalledPluginEntry,
@@ -90,6 +95,7 @@ import type {
 } from "../types/index.js";
 import { resolveExecutable } from "../utils/command-utils.js";
 import { depsSectionLines, fixDeps, renderApplyText } from "./deps-view.js";
+import { worktreeLines } from "./update-view.js";
 
 /**
  * `--project <dir>`: the directory to check, or null for the current one. A
@@ -232,6 +238,14 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	unfixable += await checkPluginLoads(projectPath);
 
 	if (problems === 0 && unfixable === 0) console.log("\n✓ No problems found.");
+
+	// 6. Other worktrees of this repository with no profile set up. After the
+	// verdict, which is about this folder: these are other projects. Reported
+	// only — doctor never writes them, `--fix` included — and outside the exit
+	// code; `magus update` sets them up.
+	const worktrees = await findUnsetWorktrees(projectPath);
+	for (const line of worktreeLines(worktrees, null)) console.log(line);
+
 	return doctorExitCode({ fixable: problems, unfixable, fix });
 }
 
@@ -320,7 +334,15 @@ async function runDepsJson(
 		}
 	}
 	const report = depsReportJson(state, env, applied);
-	process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+	// The other worktrees of this repository with no profile set up. Read
+	// only, under `--fix` too, and no part of the exit code: they are other
+	// projects, and `magus update` is what sets them up.
+	const worktreesWithoutProfile = (await findUnsetWorktrees(projectPath)).map(
+		(w) => ({ name: w.name, path: w.path, state: w.state }),
+	);
+	process.stdout.write(
+		`${JSON.stringify({ ...report, worktreesWithoutProfile }, null, 2)}\n`,
+	);
 	const healthy =
 		report.deps.every((d) => d.status === "present") &&
 		report.invalid.length === 0 &&