magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/styles-manager.ts

@@ -0,0 +1,1294 @@
+/**
+ * Styles manager — discovery and composition of communication style presets.
+ *
+ * ## What a "style" is
+ *
+ * Claude Code activates exactly ONE output style at a time. The preset model
+ * is compositional instead — one verbosity preset plus any number of
+ * modifiers — so the combination has to be flattened into a single generated
+ * style file before the harness ever sees it. That flattening is what
+ * `composeStyleFile` does here.
+ *
+ * ## Where the presets come from
+ *
+ * `data/styles/*.md`, embedded in the binary at build time. They used to ship
+ * in the `style@magus` plugin and be discovered on disk, which meant two
+ * implementations of one composer and an empty Styles tab for anyone without
+ * the plugin. The plugin was retired at Marketplace 10.0.0; this is now the
+ * only composer, and the presets travel with the binary that parses them.
+ *
+ * ## Profile awareness
+ *
+ * `.claude/settings.json` is a symlink into `.claude/_profiles/<name>/` when a
+ * profile is active, so writing `outputStyle` through it lands in that
+ * profile. But `materializeProfile` REWRITES that file from the manifest on
+ * every `magus install`, so the live write alone silently regresses. The
+ * selection is therefore also recorded in `.claude/profiles.json` under
+ * `profiles.<name>.settings.outputStyle`, which is the durable source.
+ *
+ * The generated style file is named per-profile (`composed-<name>`) so two
+ * profiles can hold different styles without clobbering each other's file
+ * while both point at the same name.
+ */
+
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import { findCommunityStyle } from "../data/community-styles.js";
+import { EMBEDDED_PRESETS } from "../data/styles/index.js";
+import {
+	getManifestPath,
+	mergeManifestSettings,
+	readManifest,
+	writeManifest,
+} from "./manifest.js";
+import { updateSettingsFile } from "./settings-file.js";
+import { activeProfile } from "./symlink-manager.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * The id namespace fetched styles live in. `community:<sourceId>--<slug>`.
+ *
+ * Exported because `.claude/style.json` carries these ids verbatim and both the
+ * adapter and the screen need to split one back into a registry coordinate.
+ */
+export const COMMUNITY_ID_PREFIX = "community:";
+
+export type StyleAxis = "verbosity" | "modifier";
+
+/** A preset embedded in this binary, from `data/styles/`. */
+export interface StylePreset {
+	kind: "preset";
+	/** Selection key. Equals `name` — presets share one namespace. */
+	id: string;
+	name: string;
+	/**
+	 * What lists show. From the preset's `title:` frontmatter, else the slug.
+	 * Display only — the CLI, declarations, and hashes all use `name`, the
+	 * same split the `builtin-` captures already have.
+	 */
+	displayName: string;
+	axis: StyleAxis;
+	summary: string;
+	/** Preset names that cancel this one out when both are selected. */
+	conflicts: string[];
+	/** Template presets ship an empty table and cannot be applied directly. */
+	template: boolean;
+	body: string;
+	/**
+	 * What the detail panel shows under "Source". A label rather than a real
+	 * path: an embedded preset has no file on disk, and the open-in-editor
+	 * action refuses presets before it ever reads this.
+	 */
+	path: string;
+}
+
+/**
+ * Where an importable style came from, which is what decides how it is grouped
+ * and whether it travels with the repository.
+ *
+ * - `anthropic` — a Claude Code built-in captured by
+ *   `scripts/capture-builtin.ts`. Its text ships inside the Claude Code
+ *   binary, so the file is a snapshot that goes stale on the next upgrade.
+ * - `team` — project-scoped, so it lives in the repo and commits with it. This
+ *   is the one everyone on the project gets.
+ * - `personal` — user-scoped, so it exists only on this machine.
+ * - `community` — someone else's style, fetched from their GitHub repo on an
+ *   explicit user action and cached outside `~/.claude/output-styles/`. We
+ *   store no copy of the text until the user asks for one, and the file carries
+ *   the coordinates it came from.
+ */
+export type StyleOrigin = "anthropic" | "team" | "personal" | "community";
+
+/**
+ * Where a community style's words came from, as its own frontmatter records it.
+ *
+ * Read from text already on disk, so populating it costs no network call and
+ * `loadStyles` stays offline on every render. `source` is THE marker — its
+ * presence is what classifies the file as `community` in the first place.
+ *
+ * The two sentinels the fetcher writes are normalised back to null here, so the
+ * detail panel never has to know the words "unknown" and "unlicensed": a pin we
+ * could not resolve and a repo that grants no licence are both ABSENCES, and
+ * rendering them as values would let "unlicensed" read as an SPDX id.
+ */
+export interface CommunityProvenance {
+	/** `owner/name` of the upstream repository. */
+	source: string;
+	/** Path within that repository, including its styles directory. */
+	path: string | null;
+	/** The git ref we asked for — usually `HEAD`. */
+	ref: string | null;
+	/** Short commit sha this copy is pinned at, or null if none was resolved. */
+	commit: string | null;
+	/** `sha256:<64 hex>` over the RAW upstream bytes at fetch time. */
+	sha256: string | null;
+	/** Local date of the fetch, YYYY-MM-DD. */
+	fetched: string | null;
+	/** SPDX id, or null when upstream grants no redistribution licence. */
+	licence: string | null;
+	author: string | null;
+}
+
+/** An output style already on this machine, importable into a composition. */
+export interface ImportedStyle {
+	kind: "imported";
+	/** Selection key, `"user:name"` or `"project:name"` — scopes may collide. */
+	id: string;
+	/** The on-disk name. This is what `style-imports` records — never display-only. */
+	name: string;
+	/**
+	 * What to show in the list. For a captured built-in this is Anthropic's own
+	 * name ("Explanatory"), not the `builtin-explanatory` slug the file carries.
+	 * Display only — composing still round-trips through `id`/`name`.
+	 */
+	displayName: string;
+	/**
+	 * Which directory it was read from. `community` is the magus cache, not a
+	 * Claude Code styles directory — see `communityCacheDirOrNull`.
+	 */
+	scope: "user" | "project" | "community";
+	origin: StyleOrigin;
+	/**
+	 * True when magus owns this copy: it lives in the community cache, so it
+	 * is re-fetchable and safe to delete. False for everything the user wrote or
+	 * placed themselves, INCLUDING a community-marked file they copied into
+	 * `~/.claude/output-styles/` — the marker says where the words came from, the
+	 * directory says whose copy it is, and those are different questions.
+	 */
+	managed: boolean;
+	description: string;
+	/** File mtime as YYYY-MM-DD — when this copy was last written. */
+	updatedAt: string | null;
+	/** For a captured built-in: the Claude Code version it was taken from. */
+	capturedFrom: string | null;
+	/** For a community style: where its words came from. Null for everything else. */
+	community: CommunityProvenance | null;
+	body: string;
+	path: string;
+}
+
+export type StyleSource = StylePreset | ImportedStyle;
+
+/** Everything the Styles screen needs for one project, in one read. */
+export interface StylesSnapshot {
+	presets: StylePreset[];
+	imports: ImportedStyle[];
+	/** Selection recorded in the generated style file; null if never applied. */
+	applied: { presets: string[]; imports: string[]; hash: string | null } | null;
+	/** The project's committed choice, `.claude/style.json`. */
+	declaration: StyleDeclaration | null;
+	/** Whether this machine's active style matches that declaration. */
+	status: StyleSyncStatus;
+	/** Where the generated style file is (or would be) written. */
+	stylePath: string;
+	/** The settings.json that carries `outputStyle`. */
+	settingsPath: string;
+	/** Name of the generated style, e.g. "composed" or "composed-dev". */
+	styleName: string;
+	/** Active profile name, when .claude/settings.json is a profile symlink. */
+	profile: string | null;
+	/** The value currently in settings.json, whatever set it. */
+	currentOutputStyle: string | null;
+}
+
+/**
+ * The project's committed style choice: `.claude/style.json`.
+ *
+ * The generated `composed.md` is an ARTIFACT — it is what Claude Code reads.
+ * This is the DECLARATION: the short, reviewable statement of what the project
+ * wants, which is the thing worth committing and arguing about in a pull
+ * request. A teammate who clones the repo gets the declaration, and magus
+ * can tell them their local artifact does not match it yet.
+ */
+export interface StyleDeclaration {
+	version: 1;
+	presets: string[];
+	imports: string[];
+	/**
+	 * Hash of the composition this declaration produced when it was written.
+	 *
+	 * Over the source BODIES, not just their names: the same preset names
+	 * compose to different text after a plugin update, and "you have the right
+	 * names" is not the same claim as "you have the right rules".
+	 */
+	hash: string;
+	updatedAt: string;
+}
+
+/** How the local generated style relates to the committed declaration. */
+export type StyleSyncState =
+	/** No `.claude/style.json` — the project has not declared a style. */
+	| "undeclared"
+	/** Declared, but this machine has not applied it (or applied something else). */
+	| "not-applied"
+	/** Applied, but the composition would differ now — usually a pulled change. */
+	| "stale"
+	/** The active style matches the declaration exactly. */
+	| "in-sync";
+
+export interface StyleSyncStatus {
+	state: StyleSyncState;
+	/** One line explaining the state, safe to show in the status bar. */
+	detail: string;
+	/** Names the declaration asks for that no longer resolve, and cannot be got. */
+	missing: string[];
+	/**
+	 * Missing `community:` ids the registry still knows how to fetch.
+	 *
+	 * DISJOINT from `missing`, because they are different situations wearing the
+	 * same shape: a name in `missing` is a dead end the user can do nothing
+	 * about, and one in `fetchable` is a single keypress from resolved. Reporting
+	 * both as "missing" is what would turn this feature's best case — a team
+	 * commits a style choice including third-party text and everyone gets it —
+	 * into an unactionable error.
+	 */
+	fetchable: string[];
+}
+
+export interface ApplyResult {
+	stylePath: string;
+	settingsPath: string;
+	styleName: string;
+	profile: string | null;
+	/** True when the selection was also recorded in .claude/profiles.json. */
+	recordedInManifest: boolean;
+	/** The committed declaration that was written — commit this. */
+	declarationPath: string;
+	hash: string;
+	presets: string[];
+	imports: string[];
+	bytes: number;
+}
+
+// ─── Frontmatter ──────────────────────────────────────────────────────────────
+
+type Frontmatter = Record<string, string>;
+
+/**
+ * Split `---` frontmatter from a markdown body.
+ *
+ * Deliberately not a YAML parser: the keys we read are flat scalars, and
+ * pulling in a YAML dependency to read five strings would be the tail wagging
+ * the dog. Quote-unescaping is included because a `description:` containing a
+ * colon has to be quoted to stay valid YAML for every other reader.
+ */
+export function splitFrontmatter(text: string): {
+	frontmatter: Frontmatter;
+	body: string;
+} {
+	const lines = text.replace(/^\uFEFF/, "").split("\n");
+	if (lines[0]?.trim() !== "---") {
+		return { frontmatter: {}, body: text.trim() };
+	}
+
+	let close = -1;
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i].trim() === "---") {
+			close = i;
+			break;
+		}
+	}
+	if (close === -1) return { frontmatter: {}, body: text.trim() };
+
+	const frontmatter: Frontmatter = {};
+	for (const line of lines.slice(1, close)) {
+		const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+		if (!match) continue;
+		let value = match[2].trim();
+		const quoted =
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"));
+		if (quoted && value.length >= 2) {
+			value = value.slice(1, -1).replace(/\\(["\\])/g, "$1");
+		}
+		frontmatter[match[1].toLowerCase()] = value;
+	}
+
+	return {
+		frontmatter,
+		body: lines
+			.slice(close + 1)
+			.join("\n")
+			.trim(),
+	};
+}
+
+function asBool(value: string | undefined): boolean | null {
+	if (value === undefined) return null;
+	const normalized = value.trim().toLowerCase();
+	if (normalized === "true" || normalized === "yes") return true;
+	if (normalized === "false" || normalized === "no") return false;
+	return null;
+}
+
+function splitList(value: string | undefined): string[] {
+	if (!value) return [];
+	return value
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+}
+
+async function markdownFiles(dir: string): Promise<string[]> {
+	try {
+		if (!(await fs.pathExists(dir))) return [];
+		if (!(await fs.stat(dir)).isDirectory()) return [];
+		const entries = await fs.readdir(dir);
+		const files: string[] = [];
+		for (const entry of entries) {
+			if (!entry.endsWith(".md")) continue;
+			const full = path.join(dir, entry);
+			try {
+				if ((await fs.stat(full)).isFile()) files.push(full);
+			} catch {
+				/* unreadable entry — skip */
+			}
+		}
+		return files.sort();
+	} catch {
+		return [];
+	}
+}
+
+// ─── Presets ────────────────────────────────────────────────────────────────
+
+/**
+ * Parse the embedded preset files into usable presets.
+ *
+ * Synchronous and infallible by construction: the text is inlined at build
+ * time, so there is no directory to miss, no plugin to be uninstalled, and no
+ * version of the files other than the one this binary was built with. The
+ * frontmatter contract is `name`, `title`, `axis`, `summary`, `conflicts`,
+ * `template` — see `data/styles/index.ts`.
+ */
+export function loadPresets(): StylePreset[] {
+	const presets: StylePreset[] = [];
+	for (const { file, text } of EMBEDDED_PRESETS) {
+		const { frontmatter, body } = splitFrontmatter(text);
+		const name = frontmatter.name || file.replace(/\.md$/, "");
+		presets.push({
+			kind: "preset",
+			id: name,
+			name,
+			displayName: frontmatter.title || name,
+			axis: frontmatter.axis === "verbosity" ? "verbosity" : "modifier",
+			summary: frontmatter.summary || "",
+			conflicts: splitList(frontmatter.conflicts),
+			template: asBool(frontmatter.template) === true,
+			body,
+			path: `bundled with magus · styles/${file}`,
+		});
+	}
+	return presets;
+}
+
+/**
+ * Where fetched community styles are cached, or null when a test has not
+ * isolated itself.
+ *
+ * Deliberately NOT `~/.claude/output-styles/`. A fetched style is a copy of
+ * someone else's text that magus can overwrite or delete without asking; the
+ * output-styles directories are the user's own, and putting a re-fetchable copy
+ * in them makes "delete this" and "delete my work" the same keypress.
+ *
+ * The null case mirrors `catalog-cache-store.ts`. Under `bun test`, a `home`
+ * that is still the operator's real one means the test never isolated itself —
+ * it gets an empty Community section rather than reading, and later possibly
+ * writing, the operator's live cache. A test that DOES pass a temporary home
+ * gets a working directory, which is what makes the classification tests
+ * possible at all.
+ */
+export function communityCacheDirOrNull(home: string): string | null {
+	const configDir = process.env.CLAUDE_CONFIG_DIR;
+	if (configDir) return path.join(configDir, "magus", "community-styles");
+	if (process.env.NODE_ENV === "test" && home === os.homedir()) return null;
+	return path.join(home, ".claude", "magus", "community-styles");
+}
+
+async function readImportable(
+	projectPath: string,
+	generatedNames: string[],
+	home: string,
+): Promise<ImportedStyle[]> {
+	const communityDir = communityCacheDirOrNull(home);
+	const scopes: Array<{ scope: ImportedStyle["scope"]; dir: string }> = [
+		{ scope: "user", dir: path.join(home, ".claude", "output-styles") },
+		{
+			scope: "project",
+			dir: path.join(projectPath, ".claude", "output-styles"),
+		},
+	];
+	// A third entry in the SAME array, which is why the cache is flat: it reuses
+	// the non-recursive `markdownFiles` verbatim, and `.pending/` (downloaded but
+	// not accepted updates) is invisible to discovery by construction rather than
+	// by a filter someone could drop.
+	if (communityDir) scopes.push({ scope: "community", dir: communityDir });
+
+	const found: ImportedStyle[] = [];
+	for (const { scope, dir } of scopes) {
+		for (const file of await markdownFiles(dir)) {
+			const { frontmatter, body } = splitFrontmatter(
+				await fs.readFile(file, "utf8"),
+			);
+			const basename = path.basename(file, ".md");
+			const declared = frontmatter.name || basename;
+
+			// A comma in `name` corrupts the declaration round trip: `composeStyleFile`
+			// serialises `style-imports` comma-separated and `readApplied` splits it
+			// back on commas, so an id containing one returns as two bogus ids and
+			// `computeStyleStatus` reports `stale` forever with no way to converge.
+			// The basename cannot carry one, and keeping the declared value as
+			// `displayName` means the user still sees the name they wrote. Fixing the
+			// SERIALISATION instead would change the format every already-written
+			// composed.md carries, so every user's next load would report a spurious
+			// drift — a worse trade for a bug that is latent rather than live.
+			const hasComma = declared.includes(",");
+			const name = hasComma ? basename : declared;
+
+			// Never import a file we generate — it would compound on every apply.
+			if (generatedNames.includes(name)) continue;
+
+			// Classification is by MARKER, never by directory, and in this order.
+			// `captured-style` keeps precedence: capture-builtin.ts writes it with
+			// Anthropic's own name for the style, and a captured built-in is an
+			// Anthropic style wherever it sits. The `builtin-` name prefix is only a
+			// fallback, because a file the user happened to call `builtin-…` is
+			// theirs, not Anthropic's.
+			const capturedStyle = frontmatter["captured-style"];
+			const isAnthropic = Boolean(capturedStyle) || name.startsWith("builtin-");
+			// `community-source` names the repo the words came from. It travels with
+			// the file, so a copy the user moves into their own output-styles
+			// directory still reports its origin honestly — it is simply no longer
+			// `managed`, so nothing offers to update or delete it.
+			const isCommunity =
+				!isAnthropic && Boolean(frontmatter["community-source"]);
+
+			found.push({
+				kind: "imported",
+				id: `${scope}:${name}`,
+				name,
+				// Display only. The registry carries upstream's own name ("Spartan",
+				// "Zen Master") because the fetched file's `name` is the coordinate id,
+				// which is machinery. Same split as the `builtin-` handling above.
+				displayName: isAnthropic
+					? capturedStyle || stripBuiltinPrefix(name)
+					: hasComma
+						? declared
+						: isCommunity
+							? (findCommunityStyle(name)?.displayName ?? name)
+							: name,
+				scope,
+				origin: isAnthropic
+					? "anthropic"
+					: isCommunity
+						? "community"
+						: scope === "project"
+							? "team"
+							: "personal",
+				// Only what magus put in its own cache. A stray hand-written file
+				// in that directory is still not ours to overwrite.
+				managed: scope === "community" && isCommunity,
+				description: frontmatter.description || "",
+				updatedAt: await fileDate(file),
+				capturedFrom: frontmatter["captured-from"] || null,
+				community: isCommunity ? readProvenance(frontmatter) : null,
+				body,
+				path: file,
+			});
+		}
+	}
+	return found;
+}
+
+/**
+ * Lift the `community-*` keys out of a fetched file's frontmatter.
+ *
+ * The two sentinels the fetcher stamps — `unknown` for an unresolved pin and
+ * `unlicensed` for a repo that grants no licence — come back as null. They exist
+ * in the FILE because a blank value there would read as a truncated write; they
+ * must not survive into the model, where "unlicensed" would render in the
+ * licence slot as though it were an SPDX id.
+ */
+function readProvenance(
+	frontmatter: Record<string, string>,
+): CommunityProvenance {
+	const value = (key: string, sentinel?: string): string | null => {
+		const raw = frontmatter[key]?.trim();
+		if (!raw || raw === sentinel) return null;
+		return raw;
+	};
+	return {
+		source: frontmatter["community-source"] ?? "",
+		path: value("community-path"),
+		ref: value("community-ref"),
+		commit: value("community-commit", "unknown"),
+		sha256: value("community-sha256"),
+		fetched: value("community-fetched"),
+		licence: value("community-licence", "unlicensed"),
+		author: value("community-author"),
+	};
+}
+
+/** `builtin-plain-text` -> `Plain text`. Only a fallback; see readImportable. */
+export function stripBuiltinPrefix(name: string): string {
+	const bare = name.replace(/^builtin-/, "").replace(/-/g, " ");
+	return bare ? bare.charAt(0).toUpperCase() + bare.slice(1) : name;
+}
+
+/** Last-written date as YYYY-MM-DD, or null if the file cannot be stat'd. */
+async function fileDate(file: string): Promise<string | null> {
+	try {
+		const { mtime } = await fs.stat(file);
+		// Local date, not toISOString(): the user reads this against their own
+		// calendar, and UTC would show yesterday for anything written after 5pm
+		// in a western timezone.
+		const pad = (n: number) => String(n).padStart(2, "0");
+		return `${mtime.getFullYear()}-${pad(mtime.getMonth() + 1)}-${pad(mtime.getDate())}`;
+	} catch {
+		return null;
+	}
+}
+
+// ─── Hashing and the committed declaration ────────────────────────────────────
+
+/**
+ * Fingerprint a resolved composition.
+ *
+ * Covers each source's id AND body, in order, because all three of those change
+ * what Claude Code is actually told:
+ *
+ *  - a different set of presets,
+ *  - the same set in a different order (specific-after-broad matters),
+ *  - the same set whose text changed under a plugin update.
+ *
+ * Hashing only the names would answer "did someone pick differently" and miss
+ * the third case entirely, which is the one nobody notices by eye.
+ *
+ * The integrity block is hashed too, even though it is not a source. It is text
+ * the model is given, it can change under a magus upgrade, and the third
+ * case above is exactly "the text changed while the names did not" — leaving it
+ * out would let `computeStyleStatus` report `in-sync` for a file that still
+ * carries the old block. Revising the block therefore costs every project one
+ * "project style changed — press a to re-apply", which is the honest signal.
+ */
+export function styleHash(sources: StyleSource[]): string {
+	const hash = createHash("sha256");
+	for (const source of sources) {
+		hash.update(source.id);
+		hash.update("");
+		hash.update(source.body);
+		hash.update("");
+	}
+	hash.update(INTEGRITY_BLOCK);
+	return `sha256:${hash.digest("hex").slice(0, 32)}`;
+}
+
+export function declarationPath(projectPath: string): string {
+	return path.join(projectPath, ".claude", "style.json");
+}
+
+/** Read the committed declaration, or null when the project has none. */
+export async function readStyleDeclaration(
+	projectPath: string,
+): Promise<StyleDeclaration | null> {
+	const file = declarationPath(projectPath);
+	try {
+		if (!(await fs.pathExists(file))) return null;
+		const parsed = (await fs.readJson(file)) as Partial<StyleDeclaration>;
+		if (!Array.isArray(parsed.presets) || !Array.isArray(parsed.imports)) {
+			return null;
+		}
+		return {
+			version: 1,
+			presets: parsed.presets.filter((v): v is string => typeof v === "string"),
+			imports: parsed.imports.filter((v): v is string => typeof v === "string"),
+			hash: typeof parsed.hash === "string" ? parsed.hash : "",
+			updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+		};
+	} catch {
+		// A corrupt declaration is reported as "none" rather than crashing the
+		// screen; re-applying rewrites it.
+		return null;
+	}
+}
+
+async function writeStyleDeclaration(
+	projectPath: string,
+	declaration: StyleDeclaration,
+): Promise<void> {
+	const file = declarationPath(projectPath);
+	await fs.ensureDir(path.dirname(file));
+	await fs.writeJson(file, declaration, { spaces: 2 });
+}
+
+/**
+ * Resolve the declaration against what is on this machine right now.
+ *
+ * Returns the sources in composition order plus anything that no longer
+ * resolves — a preset the plugin dropped, or an imported style the teammate
+ * who committed the declaration has but this machine does not.
+ */
+export function resolveDeclaration(
+	declaration: StyleDeclaration,
+	presets: StylePreset[],
+	imports: ImportedStyle[],
+): { sources: StyleSource[]; missing: string[]; fetchable: string[] } {
+	const missing: string[] = [];
+	const fetchable: string[] = [];
+
+	const chosenPresets: StylePreset[] = [];
+	for (const name of declaration.presets) {
+		const match = presets.find((preset) => preset.name === name);
+		if (match) chosenPresets.push(match);
+		else missing.push(name);
+	}
+
+	const chosenImports: ImportedStyle[] = [];
+	for (const id of declaration.imports) {
+		const match = imports.find((style) => style.id === id);
+		if (match) {
+			chosenImports.push(match);
+			continue;
+		}
+		// The whole reason community ids are registry COORDINATES rather than the
+		// file's own `frontmatter.name`: this lookup happens on a machine that has
+		// fetched nothing, so the id has to resolve before any file exists.
+		if (
+			id.startsWith(COMMUNITY_ID_PREFIX) &&
+			findCommunityStyle(id.slice(COMMUNITY_ID_PREFIX.length))
+		) {
+			fetchable.push(id);
+		} else {
+			missing.push(id);
+		}
+	}
+
+	return {
+		sources: orderSources(chosenPresets, chosenImports),
+		missing,
+		fetchable,
+	};
+}
+
+/**
+ * Compare the committed declaration with what is actually live here.
+ *
+ * The comparison recomputes the hash from CURRENT source bodies rather than
+ * trusting the one stored in the declaration. That is the whole point: it
+ * answers "would applying this right now produce what I already have", which
+ * catches a pulled change, a plugin update, and a machine that never applied.
+ */
+export function computeStyleStatus(args: {
+	declaration: StyleDeclaration | null;
+	presets: StylePreset[];
+	imports: ImportedStyle[];
+	/** Hash recorded in the local generated style file, if it exists. */
+	localHash: string | null;
+	/** Whether settings.json actually points at our generated style. */
+	isActive: boolean;
+}): StyleSyncStatus {
+	const { declaration, presets, imports, localHash, isActive } = args;
+
+	if (!declaration) {
+		return {
+			state: "undeclared",
+			detail: "no project style committed",
+			missing: [],
+			fetchable: [],
+		};
+	}
+
+	const { sources, missing, fetchable } = resolveDeclaration(
+		declaration,
+		presets,
+		imports,
+	);
+	const expected = styleHash(sources);
+
+	// Said in preference to every other detail below, because it is the only one
+	// naming an action that CONVERGES. "press a" on a declaration whose community
+	// style is not on this machine re-applies a smaller set and leaves the
+	// difference in place, so the message would still be true next time.
+	const needsFetch =
+		fetchable.length > 0
+			? `project style needs ${fetchable.length} community style${
+					fetchable.length === 1 ? "" : "s"
+				} — press f`
+			: null;
+
+	if (!isActive || !localHash) {
+		return {
+			state: "not-applied",
+			detail: needsFetch ?? "project style not applied here — press a",
+			missing,
+			fetchable,
+		};
+	}
+	if (localHash !== expected || needsFetch) {
+		// A pending fetch never reports in-sync even when the hashes agree. They
+		// agree because the un-fetched style was left out of BOTH sides, which is
+		// the composition matching itself rather than matching the declaration.
+		return {
+			state: "stale",
+			detail: needsFetch ?? "project style changed — press a to re-apply",
+			missing,
+			fetchable,
+		};
+	}
+	return {
+		state: "in-sync",
+		detail: "matches the project style",
+		missing,
+		fetchable,
+	};
+}
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+
+const DEFAULT_STYLE_NAME = "composed";
+
+/**
+ * The generated style's name for this project.
+ *
+ * Per-profile when a profile is active. Without this, two profiles both write
+ * `composed.md` and both point `outputStyle` at "composed": the second apply
+ * silently rewrites the first profile's style while its settings still claim
+ * the old one. Naming the file after the profile keeps them independent.
+ */
+export function generatedStyleName(profile: string | null): string {
+	if (!profile) return DEFAULT_STYLE_NAME;
+	const slug = profile
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+	return slug ? `${DEFAULT_STYLE_NAME}-${slug}` : DEFAULT_STYLE_NAME;
+}
+
+function stylePathFor(projectPath: string, styleName: string): string {
+	return path.join(projectPath, ".claude", "output-styles", `${styleName}.md`);
+}
+
+function settingsPathFor(projectPath: string): string {
+	return path.join(projectPath, ".claude", "settings.json");
+}
+
+// ─── Snapshot ─────────────────────────────────────────────────────────────────
+
+/** Read the selection a previously generated style file recorded. */
+export async function readApplied(stylePath: string): Promise<{
+	presets: string[];
+	imports: string[];
+	hash: string | null;
+} | null> {
+	if (!(await fs.pathExists(stylePath))) return null;
+	const { frontmatter } = splitFrontmatter(
+		await fs.readFile(stylePath, "utf8"),
+	);
+	const clean = (value: string | undefined) =>
+		!value || value === "none" ? [] : splitList(value);
+	return {
+		presets: clean(frontmatter["style-presets"]),
+		imports: clean(frontmatter["style-imports"]),
+		// Absent on a file written before hashing existed; treated as "unknown",
+		// which reads as out-of-date and prompts a re-apply. That is the safe
+		// direction to be wrong in.
+		hash: frontmatter["style-hash"] || null,
+	};
+}
+
+async function readOutputStyle(settingsPath: string): Promise<string | null> {
+	try {
+		if (!(await fs.pathExists(settingsPath))) return null;
+		const raw = (await fs.readFile(settingsPath, "utf8")).trim();
+		if (!raw) return null;
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		return typeof parsed.outputStyle === "string" ? parsed.outputStyle : null;
+	} catch {
+		return null;
+	}
+}
+
+export interface LoadStylesOptions {
+	/**
+	 * Home directory to read user-scoped styles from. Defaults to the real one.
+	 * Overridable so a test does not depend on whatever the developer happens to
+	 * have in ~/.claude/output-styles.
+	 */
+	home?: string;
+}
+
+/** One read of everything the Styles screen renders. */
+export async function loadStyles(
+	projectPath: string,
+	options: LoadStylesOptions = {},
+): Promise<StylesSnapshot> {
+	const home = options.home ?? os.homedir();
+	const profile = await activeProfile(projectPath);
+	const styleName = generatedStyleName(profile);
+	const stylePath = stylePathFor(projectPath, styleName);
+	const settingsPath = settingsPathFor(projectPath);
+
+	const presets = loadPresets();
+	// Exclude every name we might generate, not just the current one — a style
+	// left over from another profile is ours, not the user's, and importing it
+	// would nest a composition inside a composition.
+	const imports = await readImportable(
+		projectPath,
+		[DEFAULT_STYLE_NAME, styleName],
+		home,
+	);
+
+	// `applied` means "these rules are in force", which takes BOTH the generated
+	// file recording them and settings.json pointing at that file. Reading the
+	// file alone reports a cleared style as still live, because clearing removes
+	// the pointer and deliberately leaves the file on disk.
+	const currentOutputStyle = await readOutputStyle(settingsPath);
+	const applied =
+		currentOutputStyle === styleName ? await readApplied(stylePath) : null;
+
+	const declaration = await readStyleDeclaration(projectPath);
+	const status = computeStyleStatus({
+		declaration,
+		presets,
+		imports,
+		localHash: applied?.hash ?? null,
+		isActive: currentOutputStyle === styleName,
+	});
+
+	return {
+		presets,
+		imports,
+		applied,
+		declaration,
+		status,
+		stylePath,
+		settingsPath,
+		styleName,
+		profile,
+		currentOutputStyle,
+	};
+}
+
+// ─── Validation ───────────────────────────────────────────────────────────────
+
+/**
+ * Why a selection cannot be applied. Empty array means it is valid.
+ *
+ * The rules are the plugin's, and they are not cosmetic: two verbosity presets
+ * are contradictory instructions that cancel out, producing a style that reads
+ * as if it were carefully configured and behaves as if it were not.
+ */
+export function validateSelection(chosen: StylePreset[]): string[] {
+	const errors: string[] = [];
+
+	for (const preset of chosen) {
+		if (preset.template) {
+			errors.push(
+				`"${preset.name}" is a template preset — fill it in and save it to .claude/output-styles/ first, then import it.`,
+			);
+		}
+	}
+
+	const verbosity = chosen.filter((preset) => preset.axis === "verbosity");
+	if (verbosity.length > 1) {
+		errors.push(
+			`Pick exactly one verbosity preset. Got: ${verbosity
+				.map((preset) => preset.name)
+				.join(", ")}. They contradict each other and cancel out.`,
+		);
+	}
+
+	const seen = new Set<string>();
+	for (const preset of chosen) {
+		for (const conflict of preset.conflicts) {
+			if (!chosen.some((other) => other.name === conflict)) continue;
+			// Report a conflicting pair once, not once from each side.
+			const key = [preset.name, conflict].sort().join("|");
+			if (seen.has(key)) continue;
+			seen.add(key);
+			errors.push(`"${preset.name}" conflicts with "${conflict}".`);
+		}
+	}
+
+	return errors;
+}
+
+/**
+ * Order the selected sources for composition.
+ *
+ * Imports first, then verbosity, then modifiers — specific-after-broad, so a
+ * preset rule refines an imported personality rather than being buried by it.
+ */
+export function orderSources(
+	presets: StylePreset[],
+	imports: ImportedStyle[],
+): StyleSource[] {
+	const verbosity = presets.filter((preset) => preset.axis === "verbosity");
+	const modifiers = presets.filter((preset) => preset.axis === "modifier");
+	return [...imports, ...verbosity.slice(0, 1), ...modifiers];
+}
+
+// ─── Composition ──────────────────────────────────────────────────────────────
+
+/** Claude Code truncates long descriptions in the picker; stay well under. */
+const MAX_DESCRIPTION = 200;
+
+/**
+ * The shared integrity block. Appended to EVERY composition, unconditionally.
+ *
+ * A composed style is arbitrary instruction text assembled from several
+ * sources, and once the `community` origin lands one of those sources is
+ * third-party writing fetched from someone else's repository. We cannot detect
+ * prompt injection in it and will not pretend to. What we can do is state, at
+ * the end of the prompt, the things style is never allowed to change — so a
+ * rule that says "be brief" cannot be read as licence to trim a command, and a
+ * rule that says "no hedging" cannot be read as licence to drop a warning.
+ *
+ * It lives in the BODY, not the frontmatter, because only the body reaches the
+ * model. That is a real cost paid on every request, and it is the exception to
+ * the "provenance goes in frontmatter" rule directly above: provenance is for
+ * the human reading the file, this is for the model reading the prompt.
+ *
+ * It goes LAST for the same reason `orderSources` puts imports first —
+ * specific-after-broad, so later text refines earlier text rather than being
+ * buried by it.
+ *
+ * This is the only copy. It used to be duplicated in the retired style
+ * plugin's composer, with a test comparing the two; both are gone, so nothing
+ * can drift from it any more. It is still asserted to reach EVERY composition
+ * in `__tests__/styles-manager.test.ts` — that check is what matters, since
+ * the block is the security backstop on arbitrary assembled instruction text.
+ */
+export const INTEGRITY_BLOCK = `## Style limits
+
+These rules override everything above. Style decides how an answer is worded;
+it never decides what is true.
+
+- Never reword, shorten, or tidy code, commands, file paths, identifiers, error
+  text, log output, or numbers to fit a style rule. Reproduce them exactly,
+  including the parts that read badly.
+- A brevity rule may cut prose. It may never cut a flag from a command, a
+  segment from a path, a digit from a figure, or the line of a stack trace that
+  names the failure.
+- Quote real output rather than paraphrasing it. When it is too long to
+  include, quote the part that decides the answer and say what was left out.
+- Never soften or drop a security warning, a data-loss risk, or a caveat that
+  would change what the reader does next. State it plainly, even under a rule
+  that bans hedging.
+- Ask before any destructive or irreversible action and name exactly what would
+  be lost. No verbosity or brevity rule suppresses that confirmation.
+- Say when something is unverified, failing, or unknown. A rule against filler
+  bans padding, not honesty.`;
+
+function describe(sources: StyleSource[]): string {
+	const names = sources.map((source) => source.name).join(", ");
+	const text = `Composed communication style: ${names || "no rules selected"}`;
+	const clipped =
+		text.length > MAX_DESCRIPTION
+			? `${text.slice(0, MAX_DESCRIPTION - 1)}\u2026`
+			: text;
+	// The value carries ": " from the label and preset names may carry anything.
+	// Unquoted, YAML reads that as a nested mapping and the frontmatter fails to
+	// parse — so always quote, and escape what would close the quote.
+	return `"${clipped.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** Render the single generated output-style file for a selection. */
+export function composeStyleFile(
+	styleName: string,
+	sources: StyleSource[],
+): string {
+	const presets = sources.filter(
+		(source): source is StylePreset => source.kind === "preset",
+	);
+	const imports = sources.filter(
+		(source): source is ImportedStyle => source.kind === "imported",
+	);
+
+	// Provenance goes in FRONTMATTER, not the body: Claude Code splits the file
+	// and only the body becomes the prompt, so a marker in the body is paid for
+	// on every request forever.
+	const lines: string[] = [
+		"---",
+		`name: ${styleName}`,
+		`description: ${describe(sources)}`,
+		// Without this, Claude Code drops its own coding-discipline block from the
+		// system prompt. A style about how to COMMUNICATE has no business
+		// switching off how to write code.
+		"keep-coding-instructions: true",
+		'generated-by: "magus Styles tab. Hand edits are lost on the next apply."',
+		`style-presets: ${presets.map((preset) => preset.name).join(", ") || "none"}`,
+		`style-imports: ${imports.map((style) => style.id).join(", ") || "none"}`,
+		// Fingerprint of the rules this file was built from. Recomputing it from
+		// the declaration and comparing tells a teammate whether their local copy
+		// is what the project currently asks for — see computeStyleStatus.
+		`style-hash: ${styleHash(sources)}`,
+		"---",
+		"",
+	];
+
+	for (const style of imports) {
+		lines.push(`## Imported: ${style.name}`, "", style.body, "");
+	}
+
+	if (presets.length > 0) {
+		lines.push("## Communication style", "");
+		for (const preset of presets) {
+			lines.push(preset.body, "");
+		}
+	}
+
+	// Unconditional, and last. A composition with no sources still gets it —
+	// there is no selection for which "do not rewrite an error message" stops
+	// applying.
+	lines.push(INTEGRITY_BLOCK, "");
+
+	return `${lines
+		.join("\n")
+		.replace(/\n{3,}/g, "\n\n")
+		.trimEnd()}\n`;
+}
+
+// ─── Apply ────────────────────────────────────────────────────────────────────
+
+/**
+ * Set `outputStyle` in settings.json, preserving everything else.
+ *
+ * Writes in place, and refuses a file it cannot parse — both are
+ * `updateSettingsFile`'s contract, and both are documented there.
+ */
+async function setOutputStyle(
+	settingsPath: string,
+	styleName: string,
+): Promise<void> {
+	await updateSettingsFile(settingsPath, (settings) => {
+		settings.outputStyle = styleName;
+	});
+}
+
+/**
+ * Record the style in the committed manifest so it survives re-materialization.
+ * Returns false when there is no active profile or no manifest entry for it —
+ * both are normal, and neither is an error.
+ *
+ * `mergeManifestSettings` is shared with model routing, which writes the same
+ * `profiles.<name>.settings` for the same reason. It throws on a manifest it
+ * cannot parse rather than reporting a success it did not achieve.
+ */
+async function recordInManifest(
+	projectPath: string,
+	profile: string | null,
+	styleName: string,
+): Promise<boolean> {
+	return mergeManifestSettings(projectPath, profile, {
+		outputStyle: styleName,
+	});
+}
+
+export interface ApplyStylesArgs {
+	projectPath: string;
+	presets: StylePreset[];
+	imports: ImportedStyle[];
+}
+
+/**
+ * Compose the selection, write it, activate it, and verify by re-reading.
+ *
+ * Verification is deliberate: a write that reported success but produced a
+ * style file with `keep-coding-instructions` missing would strip Claude Code's
+ * coding rules, and nothing downstream would notice.
+ */
+export async function applyStyles({
+	projectPath,
+	presets,
+	imports,
+}: ApplyStylesArgs): Promise<ApplyResult> {
+	const errors = validateSelection(presets);
+	if (errors.length > 0) throw new Error(errors.join(" "));
+	if (presets.length === 0 && imports.length === 0) {
+		throw new Error("Nothing selected. Pick at least one style.");
+	}
+
+	const profile = await activeProfile(projectPath);
+	const styleName = generatedStyleName(profile);
+	const stylePath = stylePathFor(projectPath, styleName);
+	const settingsPath = settingsPathFor(projectPath);
+
+	const sources = orderSources(presets, imports);
+	const contents = composeStyleFile(styleName, sources);
+
+	await fs.ensureDir(path.dirname(stylePath));
+	await fs.writeFile(stylePath, contents, "utf8");
+	await setOutputStyle(settingsPath, styleName);
+
+	// Verify by re-reading, not by trusting the write.
+	const verify = splitFrontmatter(await fs.readFile(stylePath, "utf8"));
+	const problems: string[] = [];
+	if (verify.frontmatter.name !== styleName) {
+		problems.push(
+			`style file name is "${verify.frontmatter.name}", expected "${styleName}"`,
+		);
+	}
+	if (asBool(verify.frontmatter["keep-coding-instructions"]) !== true) {
+		problems.push(
+			"keep-coding-instructions is not true — coding rules would be dropped",
+		);
+	}
+	if ((await readOutputStyle(settingsPath)) !== styleName) {
+		problems.push("settings outputStyle did not take");
+	}
+	if (problems.length > 0) {
+		throw new Error(`Verification failed — ${problems.join("; ")}`);
+	}
+
+	const recordedInManifest = await recordInManifest(
+		projectPath,
+		profile,
+		styleName,
+	);
+
+	// Write the declaration LAST, once the artifact is verified. It is the thing
+	// that gets committed and that teammates are told to match, so it must never
+	// claim a composition that failed to produce a valid file.
+	const hash = styleHash(sources);
+	const declaration: StyleDeclaration = {
+		version: 1,
+		presets: presets.map((preset) => preset.name),
+		imports: imports.map((style) => style.id),
+		hash,
+		updatedAt: new Date().toISOString(),
+	};
+	await writeStyleDeclaration(projectPath, declaration);
+
+	return {
+		stylePath,
+		settingsPath,
+		styleName,
+		profile,
+		recordedInManifest,
+		declarationPath: declarationPath(projectPath),
+		hash,
+		presets: declaration.presets,
+		imports: declaration.imports,
+		bytes: Buffer.byteLength(contents, "utf8"),
+	};
+}
+
+// ─── Authoring a team style ───────────────────────────────────────────────────
+
+/** Filename-safe slug. Rejects anything that would escape the styles dir. */
+export function styleSlug(input: string): string {
+	return input
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+export interface CreatedStyle {
+	path: string;
+	name: string;
+	/** True when the file already existed and was left untouched. */
+	existed: boolean;
+}
+
+/**
+ * Scaffold a project-scoped style the team can edit and commit.
+ *
+ * Project scope is the whole point: `<project>/.claude/output-styles/` lives in
+ * the repository, so the style travels with the project instead of being one
+ * person's machine-local preference.
+ *
+ * This writes a starting file rather than opening an editor — magus owns the
+ * terminal, and suspending an OpenTUI app to hand the TTY to `$EDITOR` is a
+ * reliable way to leave the terminal in a broken state. The caller shows the
+ * path; the user edits it and presses `r`.
+ *
+ * An existing file is never overwritten: that would silently destroy work the
+ * team had already committed.
+ */
+export async function createTeamStyle(
+	projectPath: string,
+	rawName: string,
+): Promise<CreatedStyle> {
+	const name = styleSlug(rawName);
+	if (!name) {
+		throw new Error(
+			`"${rawName}" has no letters or digits to make a filename from.`,
+		);
+	}
+	if (
+		name === DEFAULT_STYLE_NAME ||
+		name.startsWith(`${DEFAULT_STYLE_NAME}-`)
+	) {
+		throw new Error(
+			`"${name}" is the name magus generates. Pick another, or it would be overwritten on the next apply.`,
+		);
+	}
+
+	const file = path.join(projectPath, ".claude", "output-styles", `${name}.md`);
+	if (await fs.pathExists(file)) {
+		return { path: file, name, existed: true };
+	}
+
+	const scaffold = [
+		"---",
+		`name: ${name}`,
+		`description: "Team communication style: ${name}"`,
+		// Same reasoning as the composed file: a style about how to COMMUNICATE
+		// must not switch off Claude Code's own coding rules.
+		"keep-coding-instructions: true",
+		"---",
+		"",
+		`## ${name}`,
+		"",
+		"Replace this with the rules for this project. Write them as short,",
+		"checkable instructions — each one something a reader could tell was",
+		"followed or not. For example:",
+		"",
+		"- Name the file and line when describing a change.",
+		"- Report a failing test with its actual output, never a paraphrase.",
+		"",
+		"Commit this file with the project so everyone gets the same style.",
+		"",
+	].join("\n");
+
+	await fs.ensureDir(path.dirname(file));
+	await fs.writeFile(file, scaffold, "utf8");
+	return { path: file, name, existed: false };
+}
+
+/**
+ * Deactivate: drop `outputStyle` from settings.json (and the manifest entry).
+ * The generated file is left on disk — it is cheap, and keeping it means an
+ * accidental clear is one re-apply away from being undone.
+ */
+export async function clearStyle(projectPath: string): Promise<void> {
+	const settingsPath = settingsPathFor(projectPath);
+	// The guard stays: a project that never had a style must not gain a
+	// settings.json just because the style was cleared.
+	if (await fs.pathExists(settingsPath)) {
+		await updateSettingsFile(settingsPath, (settings) => {
+			// The key must be ABSENT, not present-and-undefined: Claude Code reads
+			// presence, and an `= undefined` assignment still answers `in` checks.
+			// biome-ignore lint/performance/noDelete: removal is the intent, not a shortcut
+			delete settings.outputStyle;
+		});
+	}
+
+	const profile = await activeProfile(projectPath);
+	if (!profile) return;
+	if (!(await fs.pathExists(getManifestPath(projectPath)))) return;
+	const manifest = await readManifest(projectPath);
+	const entry = manifest.profiles[profile];
+	if (!entry?.settings || !("outputStyle" in entry.settings)) return;
+	// The guard above uses `in`, so assigning undefined would make a second call
+	// a no-op that still leaves the key serialized into profiles.json.
+	// biome-ignore lint/performance/noDelete: removal is the intent, not a shortcut
+	delete entry.settings.outputStyle;
+	entry.updatedAt = new Date().toISOString();
+	await writeManifest(manifest, projectPath);
+}