@canonical/pragma-cli 0.34.0 → 0.35.0

package/dist/src/capabilities/setup/operations/setupMcp.js

@@ -0,0 +1,207 @@
+/**
+ * `setup mcp` — register the pragma MCP server in detected AI harnesses.
+ *
+ * Split into `detectMcp` (harness detection runs FOR REAL up front, via
+ * `runTask` over safe reads, and the resolved config targets are deduplicated
+ * into per-file {@link TargetGroup}s for the chosen `--scope`) and `composeMcp`
+ * (a pure, re-runnable write body driven by the SELECTED groups). Each write is
+ * a distinct `(path, mcpKey)` so two harnesses sharing a file (VS Code + Cline)
+ * each preserve the other. What a run SAYS about each file is the plan row's
+ * per-file children, not a log line composed here.
+ *
+ * Detection ALSO reads each group's existing config (via `readMcpConfigFrom`,
+ * FOR REAL up front) and classifies every group as `absent` (no pragma entry
+ * yet), `configured` (the pragma entry already matches what we'd write), or
+ * `drifted` (a pragma entry exists but differs). The wizard shows that prior
+ * state in each row and DEFAULT-DESELECTS the already-`configured` files; the
+ * write itself stays idempotent (a re-merge of the identical entry is
+ * byte-for-byte), so a re-run is a no-op the recap reports as "unchanged" — the
+ * same state-awareness `setup skills` has always had.
+ */
+import { dirname } from "node:path";
+import { mkdir, sequence_ } from "@canonical/task";
+import { MCP_SERVER_NAME } from "../../../constants.js";
+/**
+ * The argv a registered harness spawns to reach the server.
+ *
+ * The server verb is `mcp serve`: `mcp` is the noun, and the noun on its own is
+ * not the server entry. An entry still carrying the old single-token `mcp`
+ * spawns something that no longer serves, so it must not survive.
+ *
+ * It does not have to: `mcpEntryMatches` treats `args` as a controlled field,
+ * so an entry written before this rename classifies as `drifted` on the very
+ * next detection and the ordinary forward write repairs it. That is the whole
+ * migration — no flag, no prompt, no compatibility branch — and the run after
+ * it converges, because the repaired entry then matches byte for byte.
+ */
+const MCP_SERVE_ARGV = ["mcp", "serve"];
+/**
+ * The pragma MCP server entry we register — the SINGLE source of truth both the
+ * classifier (does the existing entry match this?) and the writer (`composeMcp`)
+ * consume, so "already configured" means byte-for-byte what a write would emit.
+ *
+ * The entry is BAND-shaped: a project-band entry records the project root as
+ * `cwd` (that binding is the point of a per-repo registration), while a
+ * global-band entry OMITS `cwd` entirely — a per-user server must not be
+ * pinned to whatever directory `setup mcp --global` happened to run from
+ * (observed: a global registration from `~/Downloads` permanently served
+ * `~/Downloads`, and re-running from repo B "repaired" it to repo B,
+ * ping-ponging the machine band between projects). The per-harness
+ * serializers already omit an undefined `cwd`, and the matcher treats an
+ * omitted controlled field as must-be-absent, so a stale global entry still
+ * carrying a `cwd` classifies as `drifted` and converges on the next write.
+ *
+ * @param cwd - The project root (recorded only on project-band entries).
+ * @param band - The config band the entry is written to.
+ * @returns The pragma {@link McpServerConfig}.
+ */
+export function pragmaMcpEntry(cwd, band) {
+    return band === "project"
+        ? { command: MCP_SERVER_NAME, args: [...MCP_SERVE_ARGV], cwd }
+        : { command: MCP_SERVER_NAME, args: [...MCP_SERVE_ARGV] };
+}
+/**
+ * Classify one target group against its on-disk config: `absent` when no pragma
+ * entry exists in ANY of the group's writes, `configured` when EVERY write
+ * already carries a matching pragma entry, `drifted` otherwise (present in at
+ * least one write but not matching everywhere). Reads each write's file for real
+ * via `readMcpConfigFrom`, and matches each raw entry against what THAT write's
+ * per-harness serializer would emit for the group's BAND (`mcpEntryMatches`
+ * compares the serializer's controlled fields — so a global entry still
+ * pinning a `cwd` reads as drifted — and ignores extra keys a harness or user
+ * added, so we never churn a file we did not author).
+ *
+ * @param group - The target group whose writes to inspect.
+ * @param want - The canonical pragma entry for the group's band.
+ * @param harnessesApi - The dynamically imported harnesses module.
+ * @param runTask - The node Task interpreter.
+ * @returns The group's {@link McpTargetState}.
+ * @note Impure — reads each write's config file.
+ */
+async function classifyGroup(group, want, harnessesApi, runTask) {
+    let present = 0;
+    let matching = 0;
+    for (const write of group.writes) {
+        const servers = await runTask(harnessesApi.readMcpConfigFrom(write));
+        const existing = servers[MCP_SERVER_NAME];
+        if (existing === undefined)
+            continue;
+        present += 1;
+        if (harnessesApi.mcpEntryMatches(existing, want, write.serializeEntry)) {
+            matching += 1;
+        }
+    }
+    if (present === 0)
+        return "absent";
+    if (matching === group.writes.length)
+        return "configured";
+    return "drifted";
+}
+/**
+ * Detect the AI harnesses present in the project (real reads, up front),
+ * resolve+dedup their config targets for the chosen scope, AND read each
+ * group's existing config to classify it `absent`/`configured`/`drifted` — so
+ * the wizard can show prior state and default-deselect already-`configured`
+ * files.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param band - The band being planned (global or project).
+ * @returns The band's target groups, their prior states, + the config writer.
+ * @note Impure — reads the filesystem via `detectHarnesses` + `readMcpConfigFrom`.
+ */
+export async function detectMcp(rt, band) {
+    const cwd = rt.cwd;
+    const [{ detectHarnesses, groupTargetsForScope, mcpEntryMatches, readMcpConfigFrom, readPlatformEnv, removeMcpConfigFrom, writeMcpConfigTargets, }, { runTask },] = await Promise.all([
+        import("@canonical/harnesses"),
+        import("@canonical/task/node"),
+    ]);
+    const platform = readPlatformEnv();
+    const detected = await runTask(detectHarnesses(cwd, platform));
+    const groups = groupTargetsForScope(detected, cwd, band, platform);
+    // Read each group's existing config (for real, up front) so the recap/preview
+    // and the default selection reflect true prior state — the same discipline
+    // `detectSkills` uses for its per-link create/skip/replace decision. The
+    // wanted entry is BAND-shaped (a global entry omits `cwd`), so it is built
+    // per group, not once.
+    const stateByPath = new Map();
+    await Promise.all(groups.map(async (group) => {
+        const state = await classifyGroup(group, pragmaMcpEntry(cwd, group.scope), { readMcpConfigFrom, mcpEntryMatches }, runTask);
+        stateByPath.set(group.path, state);
+    }));
+    return {
+        groups,
+        stateByPath,
+        cwd,
+        platform,
+        writeMcpConfigTargets,
+        removeMcpConfigFrom,
+    };
+}
+/**
+ * The prior state of a group, defaulting to `absent` for an unknown path (so a
+ * caller never has to guard the map lookup).
+ */
+export function mcpGroupState(d, path) {
+    return d.stateByPath.get(path) ?? "absent";
+}
+/** The target groups the user selected (by path), or all when none recorded. */
+export function selectedGroups(d, selectedPaths) {
+    return d.groups.filter((g) => selectedPaths.includes(g.path));
+}
+/**
+ * Compose the per-target config writes for the SELECTED groups (pure —
+ * re-runnable; builds ABSOLUTE config paths itself). An already-`configured`
+ * group composes NOTHING: the entry on disk is byte-for-byte what a write would
+ * emit, so re-writing it would only move an mtime. Removal no longer depends on
+ * the forward plan having written something ({@link composeMcpRemoval}), which
+ * is what used to force the redundant write.
+ *
+ * The task carries no log effects — the plan row owns what the run says.
+ *
+ * @param d - The detection gathered up front.
+ * @param groups - The target groups the user chose (a subset of `d.groups`).
+ * @returns A Task that writes the pragma MCP config into each chosen file.
+ */
+export function composeMcp(d, groups) {
+    // Re-runnable combinators (NOT a single-use `gen`): `execute` interprets the
+    // task twice (preview + perform). One combined write per file keeps a shared
+    // file (VS Code + Cline) a single read-modify-write — dry-run safe. The
+    // written entry is BAND-shaped per group (a global entry omits `cwd`).
+    const pending = groups.filter((group) => mcpGroupState(d, group.path) !== "configured");
+    return sequence_(pending.map((group) => d.writeMcpConfigTargets(group.writes, MCP_SERVER_NAME, pragmaMcpEntry(d.cwd, group.scope))));
+}
+/**
+ * The groups this band OWNS right now — every file where detection classifies a
+ * pragma entry as present (`configured` or `drifted`). Removal acts on exactly
+ * this set, so a file that never carried the entry is never rewritten and a
+ * foreign server in a file that does is never touched.
+ */
+export const ownedMcpGroups = (d) => d.groups.filter((group) => mcpGroupState(d, group.path) !== "absent");
+/**
+ * Compose the removal of the pragma entry from every owned file.
+ *
+ * The FORWARD side of this task must be walkable without reading anything.
+ * `runUndo` collects undos by walking the forward task with effects MOCKED —
+ * real `Exists`, but `ReadFile` deliberately returns a placeholder, so that the
+ * walk cannot observe the forward run's own edits. Re-asserting the entry here
+ * (the obvious composition, and the one this had) put a read-parse-merge on
+ * that walk: the placeholder is not JSON, the parse failed closed, and the
+ * collection aborted before gathering a single undo. `setup mcp --undo` could
+ * not remove anything, and said so by refusing a config that was perfectly
+ * valid.
+ *
+ * So the forward effect is a `mkdir` of the config's own directory — which
+ * already exists, reads nothing, and is a genuine no-op — carrying the
+ * key-scoped removal as its `undo`. Phase two then runs that removal against
+ * the real file. Only the pragma key is ever deleted; a foreign server in the
+ * same file is never touched.
+ *
+ * @param d - The detection gathered up front.
+ * @returns A Task whose undo removes the pragma entry from each owned file.
+ */
+export function composeMcpRemoval(d) {
+    return sequence_(ownedMcpGroups(d).map((group) => mkdir(dirname(group.path), true, {
+        undo: sequence_(group.writes.map((write) => d.removeMcpConfigFrom(write, MCP_SERVER_NAME))),
+    })));
+}
+//# sourceMappingURL=setupMcp.js.map

package/dist/src/capabilities/setup/operations/setupMcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupMcp.js","sourceRoot":"","sources":["../../../../../src/capabilities/setup/operations/setupMcp.ts"],"names":[],"mappings":"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"}

package/dist/src/capabilities/setup/operations/setupSkills.js

@@ -0,0 +1,316 @@
+/**
+ * `setup skills` — symlink discovered skills into harness skill directories.
+ *
+ * BAND-MATCHED: the band picks the source root AND the link destination, and
+ * the two always match.
+ *
+ * - global (the default): INSTALLED skills (`$XDG_DATA_HOME/<bin>/skills`, where
+ *   `sources update` puts package skills) link into user-level harness skill
+ *   directories — the cross-client `~/.agents/skills`, plus the user-level
+ *   directory of each detected harness whose user-level location is verified.
+ * - project (`--local`): PROJECT skills (`<cwd>/.<bin>/skills`) link into the
+ *   project's harness directories — the checked-in, team-shared arrangement.
+ *
+ * Cross-band linking is what this replaces: linking installed skills into a
+ * repository's directories leaks machine state into a checkout, and linking a
+ * repository's skills into the home directory applies one project's skills
+ * machine-wide. Neither is ever what the user asked for.
+ *
+ * Split into `detectSkills` (discovery, harness detection, and the per-link
+ * create/skip/replace DECISION, all against the real filesystem up front, so
+ * the plan and the recap reflect true state) and pure compose bodies performing
+ * only the symlink/delete effects the dry-run interpreter mocks.
+ */
+import { lstatSync, readdirSync, readlinkSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { deleteFile, mkdir, sequence_, symlink, } from "@canonical/task";
+/** Cross-client skill directory, shared across all harnesses. */
+const CROSS_CLIENT_DIR = ".agents/skills";
+/**
+ * The harnesses whose USER-LEVEL skills directory is verified against the
+ * harness's own documentation, and therefore safe to link into on the global
+ * band. A harness absent from this set simply contributes no global link
+ * directory: an invented `~/.<something>/skills` would be a directory nothing
+ * reads, and creating it would be litter dressed up as configuration.
+ *
+ * The path itself is still the registry's — `skillsPath` is a function of a
+ * root, so a user-level location is `skillsPath(home)`. What lives here is only
+ * the JUDGEMENT that the location has been confirmed.
+ */
+const VERIFIED_GLOBAL_SKILL_HARNESSES = new Set([
+    "claude-code",
+]);
+/**
+ * Whether a link's destination lives INSIDE the band's skill root — the
+ * ownership test, and the one that decides what `--undo` deletes.
+ *
+ * A raw `readlink` target may be relative, so it is resolved against the link's
+ * own directory first; then containment is tested by PATH SEGMENT. A string
+ * prefix answered yes for `<root>-backup/foo`, so a user's own link into a
+ * sibling directory was classified as ours and removed by `--undo` — a file we
+ * never created and had no business deleting.
+ *
+ * The root itself is not "inside" it: a link pointing AT the root is not one of
+ * the per-skill links this command writes.
+ *
+ * @param root - The band's skill source root, absolute.
+ * @param linkPath - The absolute path of the link being classified.
+ * @param rawTarget - The link's destination exactly as `readlink` reported it.
+ * @returns Whether the destination is a path under the root.
+ * @note Pure — it resolves and compares strings, and reads nothing.
+ */
+function withinRoot(root, linkPath, rawTarget) {
+    const destination = resolve(dirname(linkPath), rawTarget);
+    const rel = relative(root, destination);
+    return (rel.length > 0 &&
+        rel !== ".." &&
+        !rel.startsWith(`..${sep}`) &&
+        !isAbsolute(rel));
+}
+/**
+ * Classify a link path WITHOUT following it: absent, a symlink (with its raw
+ * target, resolving or not), or a real (non-symlink) entry. `lstat`-based, the
+ * same classification `sources/installSkills.ts`'s `linkState` uses — probing
+ * with `existsSync` FOLLOWS the link, so a DANGLING symlink read as "absent",
+ * the plan said `created`, and the real `symlink()` crashed EEXIST while the
+ * dry-run previewed a clean create.
+ */
+function linkState(linkPath) {
+    let stat;
+    try {
+        stat = lstatSync(linkPath);
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    if (stat.isSymbolicLink()) {
+        try {
+            return { kind: "symlink", target: readlinkSync(linkPath) };
+        }
+        catch {
+            return { kind: "other" };
+        }
+    }
+    return { kind: "other" };
+}
+/**
+ * The link directories for a band. Project: every detected harness's
+ * project-rooted skills directory plus the cross-client one, exactly as
+ * before. Global: the same construction rooted at the user's home directory,
+ * but only for the harnesses in {@link VERIFIED_GLOBAL_SKILL_HARNESSES} —
+ * plus the cross-client directory, which every client reads by convention.
+ *
+ * @param detected - The detected harnesses.
+ * @param band - The band being set up.
+ * @param root - The band's link root (`cwd` for project, home for global).
+ * @returns The deduplicated target directories, first-seen wins.
+ */
+function linkTargets(detected, band, root) {
+    const seen = new Set();
+    const targets = [];
+    for (const d of detected) {
+        if (band === "global" &&
+            !VERIFIED_GLOBAL_SKILL_HARNESSES.has(d.harness.id)) {
+            continue;
+        }
+        const dir = d.harness.skillsPath(root);
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        targets.push({ dir, name: d.harness.name });
+    }
+    const crossDir = resolve(root, CROSS_CLIENT_DIR);
+    if (!seen.has(crossDir))
+        targets.push({ dir: crossDir, name: CROSS_CLIENT_DIR });
+    return targets;
+}
+/**
+ * Every owned link sitting in the target directories that the per-skill pass
+ * did not already visit.
+ *
+ * The forward pass enumerates CURRENT skills, so it can only ever see links a
+ * skill still exists for. Once the source root is emptied — or one skill is
+ * removed upstream — the link it left behind is invisible to that pass, and
+ * removal derived from it found nothing to do. Ownership is the same
+ * containment test the forward pass applies, so a user's own link is no more
+ * removable here than it is there.
+ *
+ * @param targets - The band's link directories.
+ * @param sourceRoot - The band's skill source root.
+ * @param covered - Link paths the per-skill pass already decided.
+ * @returns The owned links no current skill accounts for.
+ * @note Impure — reads each target directory and lstats its entries.
+ */
+function orphanedLinks(targets, sourceRoot, covered) {
+    const orphans = [];
+    for (const { dir, name } of targets) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue; // The directory does not exist — it holds no links.
+        }
+        for (const entry of entries) {
+            const linkPath = resolve(dir, entry);
+            if (covered.has(linkPath))
+                continue;
+            const state = linkState(linkPath);
+            if (state.kind !== "symlink")
+                continue;
+            if (!withinRoot(sourceRoot, linkPath, state.target))
+                continue;
+            orphans.push({
+                skillName: entry,
+                target: resolve(dirname(linkPath), state.target),
+                linkPath,
+                action: "skipped",
+                harnessName: name,
+                blocked: false,
+                owned: true,
+            });
+        }
+    }
+    return orphans;
+}
+/**
+ * Discover the band's skills, detect harnesses, and decide each link action
+ * (real filesystem, up front).
+ *
+ * Target discovery runs even when the band holds NO skills: the directories are
+ * where this command's own links live, and a removal has to be able to find
+ * them after the source root has been emptied.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param band - Which band to plan: global (installed skills) or project.
+ * @returns The band's link plan.
+ * @note Impure — reads the filesystem (skills + harnesses + existing links).
+ */
+export async function detectSkills(rt, band) {
+    const cwd = rt.cwd;
+    const [{ discoverSkillsFrom, installedSkillsDir, projectSkillsDir }, { detectHarnesses, readPlatformEnv, userHome }, { runTask },] = await Promise.all([
+        import("../../skill/discover.js"),
+        import("@canonical/harnesses"),
+        import("@canonical/task/node"),
+    ]);
+    const sourceRoot = band === "project" ? projectSkillsDir(cwd) : installedSkillsDir();
+    const linkRoot = band === "project" ? cwd : userHome(readPlatformEnv());
+    const skills = discoverSkillsFrom([sourceRoot]);
+    const detected = await runTask(detectHarnesses(cwd));
+    const targets = linkTargets(detected, band, linkRoot);
+    // Decide each action against REAL fs (so the preview is accurate). Dangling
+    // or wrong-target symlinks are `replaced` (delete + relink); a real
+    // (non-symlink) file or directory at the path is `skipped` — a hand-placed
+    // skill is never this command's to delete.
+    const actions = [];
+    for (const { dir, name } of targets) {
+        for (const skill of skills) {
+            const linkPath = resolve(dir, skill.folderName);
+            const state = linkState(linkPath);
+            const action = state.kind === "absent"
+                ? "created"
+                : state.kind === "symlink" && state.target === skill.sourcePath
+                    ? "skipped"
+                    : state.kind === "symlink"
+                        ? "replaced"
+                        : "skipped";
+            actions.push({
+                skillName: skill.name,
+                target: skill.sourcePath,
+                linkPath,
+                action,
+                harnessName: name,
+                blocked: state.kind === "other",
+                owned: state.kind === "symlink" &&
+                    withinRoot(sourceRoot, linkPath, state.target),
+            });
+        }
+    }
+    const warnings = actions
+        .filter((a) => a.action === "replaced")
+        .map((a) => `Replaced a stale symlink for ${a.skillName} in ${a.harnessName}`);
+    return {
+        band,
+        sourceRoot,
+        available: skills.length > 0,
+        targets,
+        actions,
+        orphans: orphanedLinks(targets, sourceRoot, new Set(actions.map((a) => a.linkPath))),
+        skillCount: skills.length,
+        harnessCount: targets.length,
+        warnings,
+    };
+}
+/**
+ * Compose the (re)link effects from a detection (builds ABSOLUTE link paths
+ * itself).
+ *
+ * Built from re-runnable combinators (NOT a single-use `gen`) because `execute`
+ * interprets the task twice (preview + perform). `created` links carry an undo;
+ * a `replaced` link is delete-then-relink (idempotent); `skipped` is a no-op —
+ * and a detection where every action is `skipped` composes NOTHING, so a
+ * converged re-run performs zero filesystem mutations.
+ *
+ * @param d - The detection gathered up front.
+ * @returns A Task that mkdirs each needed target and creates/replaces links.
+ */
+export function composeSkills(d) {
+    const pending = d.actions.filter((a) => a.action !== "skipped");
+    if (!d.available || pending.length === 0)
+        return sequence_([]);
+    const dirs = new Set(pending.map((a) => dirname(a.linkPath)));
+    const tasks = [...dirs]
+        .sort()
+        .map((dir) => mkdir(dir, true));
+    for (const a of pending) {
+        if (a.action === "created") {
+            tasks.push(symlink(a.target, a.linkPath, { undo: deleteFile(a.linkPath) }));
+        }
+        else {
+            tasks.push(deleteFile(a.linkPath));
+            tasks.push(symlink(a.target, a.linkPath, { undo: deleteFile(a.linkPath) }));
+        }
+    }
+    return sequence_(tasks);
+}
+/**
+ * The links this band OWNS right now — every existing symlink pointing into the
+ * band's skill root, including dangling ones, ones already correct, and the
+ * ones no current skill accounts for. This is what removal acts on, and it is
+ * deliberately NOT the forward plan: undoing a freshly composed forward plan on
+ * an already-linked tree reversed the mkdirs and removed nothing, while
+ * reporting a step count.
+ */
+/**
+ * The named reason a skills row skips, shared by the setup plan and the doctor
+ * row so the two surfaces cannot word the same finding differently. Two strings
+ * for one condition is how a user ends up unsure whether they are looking at one
+ * problem or two.
+ *
+ * @param sourceRoot - The band's skill source root, already root-relative.
+ * @param band - The band being reported.
+ * @returns The reason line.
+ */
+export const skillsSkipReason = (sourceRoot, band) => band === "project"
+    ? `no project skills (${sourceRoot} is absent)`
+    : "no skills installed";
+export const ownedSkillLinks = (d) => [
+    ...d.actions.filter((a) => a.owned),
+    ...d.orphans,
+];
+/**
+ * Compose the removal of every owned link. Each forward effect re-asserts the
+ * link (idempotent) and carries its deletion as `undo`, which is what the undo
+ * interpreter executes — so the reversal is composed from what detection says
+ * this command owns, never from what a fresh forward plan would create.
+ *
+ * @param d - The detection gathered up front.
+ * @returns A Task whose undo removes every owned link.
+ */
+export function composeSkillsRemoval(d) {
+    const owned = ownedSkillLinks(d);
+    if (owned.length === 0)
+        return sequence_([]);
+    return sequence_(owned.map((a) => symlink(a.target, a.linkPath, { undo: deleteFile(a.linkPath) })));
+}
+//# sourceMappingURL=setupSkills.js.map

package/dist/src/capabilities/setup/operations/setupSkills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupSkills.js","sourceRoot":"","sources":["../../../../../src/capabilities/setup/operations/setupSkills.ts"],"names":[],"mappings":"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"}

package/dist/src/capabilities/setup/plan.js

@@ -0,0 +1,128 @@
+/**
+ * The setup plan — ONE structure with four readers.
+ *
+ * `--dry-run` prints it, the wizard edits its `selected` flags, progress reports
+ * one line per row as its outcome lands, and the recap is the same rows with
+ * `outcome` filled. `--format json` emits `{ scope, roots, rows }` verbatim.
+ * Doctor reads the same target table (see {@link ./targets.js}) so the two
+ * surfaces cannot disagree about what they looked at.
+ *
+ * The shape is deliberately flat and JSON-ready: no class, no live handle, no
+ * task. A row is a fact about what a run WOULD do (or, once `outcome` is set,
+ * what it did), which is why the plan can be rendered before, during, and after
+ * the run without any reader having to know which phase produced it.
+ *
+ * This module is pure data + pure derivations. It carries no import of the
+ * operations, the harnesses runtime, or React — so the renderers, the doctor
+ * checks, and the verb can all reach it without dragging anything heavy along.
+ */
+import { isAbsolute, relative, sep } from "node:path";
+/** The five setup targets, in table (and therefore display) order. */
+export const TARGET_IDS = [
+    "config",
+    "completions",
+    "lsp",
+    "mcp",
+    "skills",
+];
+/**
+ * Whether a plan action would touch the filesystem. `none` and `skip` are the
+ * two quiet outcomes: a converged re-run composes no effects at all, so mtimes
+ * stay untouched and a second `--yes` writes nothing.
+ */
+export const isActionable = (action) => action === "install" ||
+    action === "update" ||
+    action === "link" ||
+    action === "remove";
+/**
+ * Default selection for a freshly built row: actionable rows are pre-selected,
+ * already-current rows are shown de-selected, and a skip is never selectable.
+ */
+export const defaultSelected = (action) => isActionable(action);
+/** The rows a run acts on: selected, and not a skip. */
+export const selectedRows = (plan) => plan.rows.filter((row) => row.selected && row.action !== "skip");
+/**
+ * THE exit rule (and the reason it is stated once, here): a run fails only when
+ * a selected row was attempted and did not happen. Every selected row ending
+ * `done`, `noop` or `skipped` exits 0 — including a headless box where nothing
+ * is installable, because a skip is "nothing to do here, honestly named", the
+ * same semantics doctor gives its skip glyph. Punishing a converged or benignly
+ * empty state with a non-zero exit makes a dotfiles script fail on a machine
+ * with an exotic shell, which teaches people to ignore the exit code.
+ *
+ * @param plan - The plan, with outcomes filled in.
+ * @returns Whether any selected row ended `failed`.
+ */
+export const planExitFailed = (plan) => plan.rows.some((row) => row.outcome?.status === "failed");
+/**
+ * `N of M targets` — the recap headline's counts.
+ *
+ * M is the rows this run took RESPONSIBILITY for: every row that reached an
+ * outcome other than `skipped`. That is deliberately not "rows with the checkbox
+ * ticked". An already-current row is offered de-selected because there is
+ * nothing to do to it, so counting ticks reported a fully converged machine as
+ * `0 of 0 configured` — a sentence that describes a machine where nothing
+ * worked exactly as it describes one where everything already did.
+ *
+ * Skips stay out of both counts: a target that cannot act on this machine is
+ * neither a success nor a shortfall, and it is already named on its own row.
+ * A row the user deselected has no outcome at all and is likewise absent.
+ *
+ * @param plan - The plan, with outcomes filled in.
+ * @returns The headline's numerator and denominator.
+ */
+export function planTally(plan) {
+    const accountable = plan.rows.filter((row) => row.outcome !== undefined && row.outcome.status !== "skipped");
+    const configured = accountable.filter((row) => row.outcome?.status === "done" ||
+        row.outcome?.status === "noop" ||
+        row.outcome?.status === "removed" ||
+        row.outcome?.status === "kept");
+    return { configured: configured.length, accountable: accountable.length };
+}
+/**
+ * Render one absolute path relative to whichever root contains it — the header
+ * names both roots once, so a row never repeats a 120-character prefix. The
+ * global root prints as `~`; the project root prints as `.`. A path under
+ * neither root stays absolute, because shortening it would be a guess — and a
+ * sibling directory whose name merely EXTENDS a root's is under neither.
+ *
+ * The project root is tried FIRST: a project checked out inside the home
+ * directory sits under both, and the more specific root is the informative one.
+ *
+ * @param path - An absolute path.
+ * @param roots - The plan's two named roots.
+ * @returns The root-relative rendering.
+ */
+export function shortenPath(path, roots) {
+    for (const [root, marker] of [
+        [roots.project, "."],
+        [roots.global, "~"],
+    ]) {
+        if (!root)
+            continue;
+        if (path === root)
+            return marker;
+        // Containment is a question about path SEGMENTS, and the separator is the
+        // host's. Testing `startsWith(root + "/")` answered no for every Windows
+        // path `node:path` produces, so the plan printed absolute paths where it
+        // had just named the root they sit under — and it answered YES for a
+        // sibling whose name merely extends the root's.
+        const rel = relative(root, path);
+        if (rel.length === 0 ||
+            rel === ".." ||
+            rel.startsWith(`..${sep}`) ||
+            isAbsolute(rel)) {
+            continue;
+        }
+        return `${marker}${sep}${rel}`;
+    }
+    return path;
+}
+/** Replace a row's outcome, leaving every other field untouched. */
+export const withOutcome = (row, outcome) => ({
+    ...row,
+    outcome,
+});
+/** Replace a plan's rows (the wizard's edit, and the apply phase's fill-in). */
+export const withRows = (plan, rows) => ({ ...plan, rows });
+//# sourceMappingURL=plan.js.map