@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -0,0 +1,343 @@
+/**
+ * Synthesize a setup invocation as a summon `GeneratorDefinition` driven by the
+ * TARGET TABLE, so the run-all and every sub-verb flow through the same
+ * `execute` seam `create` uses — inheriting the Ink wizard, the recap/confirm
+ * gate, live progress, colours, and the shared cancel fixes by construction.
+ *
+ * The shape mirrors `create`: detection runs FOR REAL up front (once per
+ * target/band, in `detectTargets`), then a PURE `generate` composes only the
+ * effects for the SELECTED rows. `generate` must stay re-interpretable —
+ * `execute` invokes it more than once (the confirm-gate preview and the build) —
+ * so it is composed from combinators and does no reads of its own.
+ *
+ * The wizard is the PLAN'S EDITOR, not a parallel path: its choices are the plan
+ * rows, and what it edits is each row's `selected` flag. There is exactly one
+ * list of things this command can do, and the preview, the wizard, the progress
+ * lines and the recap are four views of it.
+ *
+ * This module carries NO static import of `@canonical/summon-core` VALUES or of
+ * React/Ink — it only `import type`s the generator shape and builds plain object
+ * literals over `@canonical/task`. It is itself reached only through the verb's
+ * lazy dynamic import, so the fast paths stay free of it.
+ */
+import { flatMap, pure, recover, sequence_, warn, } from "@canonical/task";
+import { BIN_NAME } from "../../../constants.js";
+import { PragmaError } from "../../../kernel/error/index.js";
+import { buildPlan, detectionFailure, detectTargets, draftFor, resolveRoots, } from "../buildPlan.js";
+import { isActionable, TARGET_IDS, withRows, } from "../plan.js";
+/** The answer key the run-all's row multiselect writes. */
+const ROWS_ANSWER = "targets";
+/** The answer key the opt-in per-file MCP narrowing writes. */
+const MCP_FILES_ANSWER = "mcpTargets";
+/** The answer key the opt-in per-editor LSP narrowing writes. */
+const LSP_EDITORS_ANSWER = "lspEditors";
+/** Which answer key carries a target's per-child selection, if it has one. */
+const CHILD_ANSWER = {
+    mcp: MCP_FILES_ANSWER,
+    lsp: LSP_EDITORS_ANSWER,
+};
+/** A row's identity in an answer bag: band-qualified, so `both` stays unambiguous. */
+const rowKey = (band, target) => `${band}:${target}`;
+/**
+ * Where a failed row's error lands during interpretation.
+ *
+ * Per-row failure isolation needs somewhere to put "row X failed with Y", and
+ * `execute` yields only the generator's answers and effects — the value of the
+ * composed task is discarded. So the recover handlers record here, and the head
+ * of the sequence CLEARS it: `generate` is invoked fresh per interpretation, so
+ * the clear runs first on every drive and the last drive (the real one, which
+ * follows `execute`'s mocked preview) is the one whose records survive. The
+ * composition itself stays pure and re-interpretable — nothing is captured in
+ * the task, only written while it runs.
+ */
+class OutcomeSink {
+    errors = new Map();
+    /** Forget every recorded failure — run at the head of each interpretation. */
+    clear() {
+        this.errors.clear();
+    }
+    record(key, error) {
+        this.errors.set(key, error);
+    }
+    get(key) {
+        return this.errors.get(key);
+    }
+    get failureCount() {
+        return this.errors.size;
+    }
+}
+/** The {@link PragmaError} a row failure carries, or a wrapper around it. */
+const rowPragmaError = (error) => error.cause instanceof PragmaError
+    ? error.cause
+    : new PragmaError({ code: "UNSUPPORTED", message: error.message });
+/**
+ * Run the chosen rows with per-row failure isolation. The rows are independent
+ * installers, so one unsatisfiable prerequisite must not consume the others: a
+ * sequenced composition let a failing editor sideload abort the run before MCP
+ * or skills ever executed, so on every machine without a usable editor CLI the
+ * single advertised onboarding command configured nothing that mattered.
+ *
+ * Each row runs under a `recover` frame: the failure is reported inline (a
+ * `warn` right where it happened), recorded on the sink, and the remaining rows
+ * still run. The aggregate outcome is decided afterwards by the caller reading
+ * the sink — a run whose every failure is recorded does NOT rethrow, because the
+ * recap is the report and the exit code comes from the plan's own rule.
+ *
+ * Only failures travelling the task FAILURE CHANNEL are isolable — a synchronous
+ * throw bypasses the trampoline's recovery frames — which is why the row bodies
+ * raise via `checkExecOk`/`failPragma`, never a bare throw. Interruption bypasses
+ * recovery by interpreter invariant, so Ctrl-C still stops the whole run.
+ */
+const runRowsIsolated = (sink, rows) => flatMap(pure(undefined), () => {
+    sink.clear();
+    return sequence_(rows.map(({ key, task }) => recover(task, (error) => flatMap(warn(`The ${key.split(":")[1]} step did not complete — continuing with the remaining targets.`), () => {
+        sink.record(key, error);
+        return pure(undefined);
+    }))));
+});
+/** Build a generator's `meta` (no stamping — the version is just header text). */
+const buildMeta = (rt, title) => ({
+    name: title,
+    displayName: title,
+    description: `Configure ${BIN_NAME} on this machine`,
+    version: rt.version,
+});
+/** Read a multiselect answer as a string array. */
+const readList = (answers, key) => Array.isArray(answers[key]) ? answers[key] : undefined;
+/**
+ * The wizard's row multiselect — its choices ARE the plan rows. Actionable rows
+ * are pre-selected; an already-current row is offered DE-selected, so a re-run
+ * never proposes to rewrite what is already correct. A skip row is not a choice
+ * at all (summon's choice shape has no disabled state) but stays a visible row
+ * in the plan and the recap, carrying its reason.
+ */
+const buildRowsPrompt = (plan) => {
+    const choices = plan.rows
+        .filter((row) => row.action !== "skip")
+        .map((row) => ({
+        label: `${row.target} — ${row.detail}${row.action === "none" ? " (already configured)" : ""}`,
+        value: rowKey(row.band, row.target),
+    }));
+    return {
+        name: ROWS_ANSWER,
+        type: "multiselect",
+        message: "Which targets would you like to configure?",
+        choices,
+        default: plan.rows
+            .filter((row) => row.selected)
+            .map((row) => rowKey(row.band, row.target)),
+    };
+};
+/** The opt-in "customize which files" gate — defaults to false. */
+const buildCustomizePrompt = (when) => ({
+    name: "customize",
+    type: "confirm",
+    message: `Customize which files ${BIN_NAME} configures?`,
+    default: false,
+    when,
+});
+/**
+ * The per-file MCP multiselect — one row per deduplicated config file, across
+ * every band the run covers. An already-current file is DEFAULT-DESELECTED; a
+ * file that is absent or drifted stays selected. Retained unchanged from the
+ * landed opt-in narrowing: it is row-level CHILD selection, which is exactly
+ * what the plan's child rows are.
+ */
+const buildChildPrompt = (plan, target, message, when) => {
+    const children = childrenOf(plan, target);
+    return {
+        name: CHILD_ANSWER[target],
+        type: "multiselect",
+        message,
+        when,
+        choices: children.map((child) => ({
+            label: `${child.label} — ${child.action}`,
+            value: child.key,
+        })),
+        default: children
+            .filter((child) => child.action !== "unchanged")
+            .map((child) => child.key),
+    };
+};
+/** Every child row a target contributes, across the bands in the plan. */
+const childrenOf = (plan, target) => plan.rows
+    .filter((row) => row.target === target)
+    .flatMap((row) => row.children ?? []);
+/** Whether a row was chosen: by the wizard's answer, else by its own default. */
+const isChosen = (row, chosen) => row.action !== "skip" &&
+    (chosen === undefined
+        ? row.selected
+        : chosen.includes(rowKey(row.band, row.target)));
+/**
+ * What a row DID, as a past-tense word. The row's detail says what and where;
+ * the note says what happened to it, so a progress line and a recap line read
+ * as sentences rather than as two halves of one.
+ */
+const ACTION_NOTES = {
+    install: "installed",
+    update: "updated",
+    link: "linked",
+    remove: "removed",
+};
+/**
+ * The `2 added, 1 updated` note a row's children produce — counted over the
+ * children the run KEPT, not the ones it was offered.
+ *
+ * `kept` is the row's own child answer: the MCP files, or the LSP editors, the
+ * wizard narrowed to. Counting the plan's children instead recapped `2 added`
+ * for a run the user had just narrowed to one file, so the plan and the result
+ * described different work. Absent (`undefined`) means the narrowing prompt was
+ * never answered, which is the same thing the compose bodies read as "all".
+ *
+ * @param row - The plan row.
+ * @param kept - The child keys the run retained, or `undefined` for all.
+ * @returns The counts note, or `undefined` when the row has no children.
+ */
+function childNote(row, kept) {
+    const children = (row.children ?? []).filter((child) => kept === undefined || kept.includes(child.key));
+    if (children.length === 0)
+        return undefined;
+    const count = (action) => children.filter((child) => child.action === action).length;
+    const parts = [
+        count("add") > 0 ? `${count("add")} added` : "",
+        count("update") > 0 ? `${count("update")} updated` : "",
+        count("unchanged") > 0 ? `${count("unchanged")} unchanged` : "",
+    ].filter((part) => part.length > 0);
+    return parts.length > 0 ? parts.join(", ") : undefined;
+}
+/**
+ * Build one invocation: detect, plan, synthesize the generator, and expose the
+ * projection back onto the plan.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param mode - The entry point: the run-all, or one target.
+ * @param scope - The resolved band selection.
+ * @param removal - Compose the removal (`--undo`) instead of the install.
+ * @returns The plan, the generator, and the answers-to-plan projection.
+ * @note Impure — runs every selected target's real detection.
+ */
+export async function buildSetupRun(rt, mode, scope, removal = false) {
+    const ids = mode === "all" ? [...TARGET_IDS] : [mode];
+    const roots = await resolveRoots(rt);
+    const detected = await detectTargets(rt, ids, scope);
+    const plan = buildPlan(scope, roots, detected, ids, removal);
+    const sink = new OutcomeSink();
+    const prompts = [];
+    if (mode === "all")
+        prompts.push(buildRowsPrompt(plan));
+    // A target is worth narrowing only when it has more than one child to choose
+    // between. `mcp` offers its config files; `lsp` offers the editors on PATH —
+    // a machine with several VS Code forks should not have the extension pushed
+    // into all of them just because they are installed.
+    const narrowable = [
+        ["mcp", "Configure MCP for which files?"],
+        ["lsp", "Install the extension into which editors?"],
+    ].filter(([target]) => !removal && childrenOf(plan, target).length > 1);
+    if (narrowable.length > 0) {
+        const anyChosen = (answers) => {
+            const chosen = readList(answers, ROWS_ANSWER);
+            return narrowable.some(([target]) => plan.rows.some((row) => row.target === target && isChosen(row, chosen)));
+        };
+        prompts.push(buildCustomizePrompt(anyChosen));
+        for (const [target, message] of narrowable) {
+            const rowChosen = (answers) => {
+                const chosen = readList(answers, ROWS_ANSWER);
+                return plan.rows.some((row) => row.target === target && isChosen(row, chosen));
+            };
+            prompts.push(buildChildPrompt(plan, target, message, (answers) => answers.customize === true && rowChosen(answers)));
+        }
+    }
+    /** The detection behind a row, for composing and for re-reading its draft. */
+    const detectionFor = (row) => detected.find((d) => d.target.id === row.target && d.band === row.band);
+    const generator = {
+        meta: buildMeta(rt, mode === "all" ? `${BIN_NAME} setup` : `${BIN_NAME} setup ${mode}`),
+        prompts,
+        generate: (answers) => {
+            const chosen = readList(answers, ROWS_ANSWER);
+            const tasks = plan.rows.flatMap((row) => {
+                if (!isChosen(row, chosen))
+                    return [];
+                const hit = detectionFor(row);
+                if (hit === undefined)
+                    return [];
+                // Each target reads ITS OWN child answer. One shared list was handing
+                // MCP file paths to every other target's compose.
+                const key = CHILD_ANSWER[row.target];
+                const children = key === undefined ? undefined : readList(answers, key);
+                const task = removal
+                    ? hit.target.composeRemoval(hit.detection)
+                    : hit.target.compose(hit.detection, children);
+                return [{ key: rowKey(row.band, row.target), task }];
+            });
+            return runRowsIsolated(sink, tasks);
+        },
+    };
+    /** The outcome one row ended in, read off the sink and its own draft. */
+    const outcomeFor = (row, chosen, answers) => {
+        const hit = detectionFor(row);
+        // A row whose DETECTION threw has no draft to read and nothing to compose,
+        // and it is not a skip: the target was requested and did not happen. It
+        // reports `failed` with its own cause, exactly as a failed compose does, so
+        // the run names it instead of reporting a clean sweep over its siblings.
+        const failure = hit === undefined ? undefined : detectionFailure(hit);
+        if (failure !== undefined)
+            return { status: "failed", note: failure };
+        const draft = hit === undefined ? undefined : draftFor(hit, roots, removal);
+        if (row.action === "skip") {
+            return {
+                status: "skipped",
+                ...(draft?.remedy === undefined ? {} : { remedy: draft.remedy }),
+            };
+        }
+        // An already-current row reports `noop` whether or not it was selected. It
+        // is offered DE-selected (there is nothing to do to it), and returning no
+        // outcome at all left a converged re-run with a plan-shaped output that
+        // claimed nothing had run — while the row still rendered a bare green ✓.
+        // Convergence is a real result: one quiet line per row, zero writes.
+        if (row.action === "none")
+            return { status: "noop", note: "unchanged" };
+        if (!isChosen(row, chosen))
+            return undefined;
+        const error = sink.get(rowKey(row.band, row.target));
+        if (error !== undefined) {
+            const pragma = rowPragmaError(error);
+            return {
+                status: "failed",
+                note: pragma.message,
+                ...(pragma.recovery?.message === undefined
+                    ? {}
+                    : { remedy: pragma.recovery.message }),
+            };
+        }
+        if (!isActionable(row.action))
+            return { status: "noop" };
+        // A removal never borrows the forward child summary: its children are the
+        // files the entry is being taken OUT of, and counting them as "1 updated"
+        // described the opposite of what the run had just done.
+        const childKey = CHILD_ANSWER[row.target];
+        const kept = childKey === undefined ? undefined : readList(answers, childKey);
+        const note = removal
+            ? ACTION_NOTES[row.action]
+            : (childNote(row, kept) ?? ACTION_NOTES[row.action]);
+        return {
+            status: removal ? "removed" : "done",
+            ...(note === undefined ? {} : { note }),
+        };
+    };
+    return {
+        plan,
+        generator,
+        applied: (answers) => {
+            const chosen = readList(answers, ROWS_ANSWER);
+            return withRows(plan, plan.rows.map((row) => {
+                const outcome = outcomeFor(row, chosen, answers);
+                return {
+                    ...row,
+                    selected: isChosen(row, chosen),
+                    ...(outcome === undefined ? {} : { outcome }),
+                };
+            }));
+        },
+    };
+}
+//# sourceMappingURL=setupGenerator.js.map

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

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

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

@@ -0,0 +1,277 @@
+/**
+ * `setup lsp` — ensure the Terrazzo LSP extension is installed in every
+ * VS Code-family editor present on this machine.
+ *
+ * There is no marketplace listing yet: the install is a VSIX SIDELOAD. The
+ * published npm package bundles the VSIX, so the install is two exec steps —
+ * fetch the package into a pragma-owned staging dir (`bun add`, so the VSIX
+ * lands at a DURABLE path a user can retry by hand, not bunx's ephemeral
+ * `/tmp/bunx-…` cache), then `<editor cli> --install-extension <vsix>` for
+ * each detected editor. The package's own `install.mjs` bin is deliberately
+ * NOT used: it hardcodes the `code` CLI, which is precisely what left
+ * VSCodium/Cursor/Windsurf/Antigravity machines unable to install at all.
+ *
+ * `detectLsp` probes FOR REAL up front, and spawns NOTHING: an editor is
+ * "present" when its CLI resolves on PATH (the `editorClis` registry names
+ * them), and "installed" when its extensions dir holds a
+ * `canonical.terrazzo-lsp-extension-<version>/` entry. Running
+ * `--list-extensions` instead would be the natural probe, but Cursor's Linux
+ * launcher OPENS THE EDITOR on that flag — a detection step must never launch
+ * an app, so the fs is the source of truth. The full extension id is matched
+ * (not the old `terrazzo` substring, which any other terrazzo-named extension
+ * could false-positive).
+ *
+ * No editor CLI found is a NAMED SKIP, not an error: the message says what was
+ * looked for and what to do, and the run exits 0 — there is nothing on this
+ * machine the step could honestly fail at. Real failures (fetch, sideload)
+ * travel the task failure channel (`checkExecOk`) with a recovery that names a
+ * command runnable on THIS machine, so the run-all can isolate the step
+ * (S1-1) and a direct `setup lsp` still renders the original error.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { exec, flatMap, mkdir, sequence_, } from "@canonical/task";
+import { BIN_NAME } from "../../../constants.js";
+import { checkExecOk, guardMissingBinary } from "../../shared/index.js";
+/** The full extension id, as the editor's extensions dir spells it. */
+const EXTENSION_ID = "canonical.terrazzo-lsp-extension";
+/** The npm package whose tarball bundles the VSIX. */
+const LSP_PACKAGE = "@canonical/terrazzo-lsp-extension";
+/**
+ * Whether an editor CLI resolves on PATH, given the candidate paths the host
+ * would consider for it.
+ *
+ * The candidates come from `@canonical/harnesses`' `executableCandidates` —
+ * the same helper harness detection resolves `process` signals with — rather
+ * than from a local `PATH`-join here. That local version joined the BARE name
+ * onto each PATH directory, which resolves nothing on Windows: `code`,
+ * `codium` and friends install as `.cmd` shims, so every installed editor
+ * went unseen and `setup lsp` took the no-editor path. That path is a named
+ * SKIP, so the run exited 0 reporting a clean answer on a machine that had
+ * the editor — a wrong skip reads as correct, which is worse than a wrong
+ * failure. One implementation of the platform rules means the probe cannot
+ * drift away from detection's.
+ */
+const cliOnPath = (candidates) => candidates.some((candidate) => existsSync(candidate));
+/**
+ * The oldest extension release whose bundled language server actually starts.
+ *
+ * Every VSIX before this one ships the server as ~166 loose modules importing
+ * `colorjs.io`, `@lezer/common` and `@lezer/css` by BARE SPECIFIER, with no
+ * `node_modules` beside them — so the server dies on load under `node` and
+ * under `bun --no-install`. It appeared to work only because the extension
+ * prefers Bun, and Bun silently fetches missing packages from the network at
+ * spawn time; a machine without that behaviour got a language server that
+ * never started, and one with it got a server resolving unpinned dependencies
+ * over the wire. Fixed in 0.8.3, which bundles the server into one file
+ * (canonical/design-tokens#110).
+ */
+const MIN_EXTENSION_VERSION = "0.8.3";
+/** {@link MIN_EXTENSION_VERSION}, parsed once. */
+const MINIMUM = MIN_EXTENSION_VERSION.split(".").map(Number);
+/**
+ * A version this check can actually read: dot-separated digit runs, nothing
+ * else. Deliberately strict — see {@link parseVersion}.
+ */
+const NUMERIC_VERSION = /^\d+(?:\.\d+)*$/;
+/**
+ * Parse a dotted numeric version, or `undefined` when it is not one.
+ *
+ * `Number.parseInt` is the wrong tool here and quietly breaks the fail-closed
+ * rule this module claims: it accepts numeric PREFIXES, so `1.0.0junk` reads
+ * as `[1, 0, 0]`, and `|| 0` turns a `NaN` component into a zero, so
+ * `1.invalid.0` also reads as `[1, 0, 0]`. Both then compare NEWER than the
+ * minimum and report a broken extension as installed — the exact wrong-skip
+ * this version check exists to prevent, reintroduced by the parser.
+ *
+ * So the whole string is validated before any component is trusted.
+ */
+const parseVersion = (value) => NUMERIC_VERSION.test(value)
+    ? value.split(".").map((part) => Number(part))
+    : undefined;
+/** Compare two dotted numeric versions. Returns <0, 0, >0 like a comparator. */
+const compareVersions = (left, right) => {
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+};
+/**
+ * Whether an editor's extensions dir holds a copy new enough to WORK.
+ *
+ * Version-aware on purpose. Matching any `canonical.terrazzo-lsp-extension-*`
+ * entry meant a machine carrying a build whose server cannot start reported
+ * `installed`, so `setup lsp` skipped it and `doctor` called it healthy —
+ * a wrong skip that reads as correct, which is worse than a wrong failure and
+ * is exactly the trap this module's docblock warns about elsewhere. Everyone
+ * who ran `setup lsp` before {@link MIN_EXTENSION_VERSION} would have kept a
+ * dead language server forever, with nothing telling them why.
+ *
+ * An unparseable suffix counts as too old: a directory this function cannot
+ * read the version of is one it cannot vouch for.
+ */
+const extensionInstalled = (editor, platform) => {
+    let entries;
+    try {
+        entries = readdirSync(editor.extensionsDir(platform));
+    }
+    catch {
+        return false; // No extensions dir — nothing installed.
+    }
+    const prefix = `${EXTENSION_ID}-`;
+    return entries.some((entry) => {
+        const lower = entry.toLowerCase();
+        if (!lower.startsWith(prefix))
+            return false;
+        const version = parseVersion(lower.slice(prefix.length));
+        if (version === undefined)
+            return false; // Unreadable: cannot vouch for it.
+        return compareVersions(version, MINIMUM) >= 0;
+    });
+};
+/**
+ * Probe every registry editor: CLI presence via PATH lookup, installed-state
+ * via the extensions dir — no spawns (see the module docblock for why).
+ *
+ * @param _cwd - Unused; kept so every `detectX` shares the (cwd) shape.
+ * @returns The detected {@link LspDetection}.
+ * @note Impure — reads PATH dirs and editor extension dirs off the real fs.
+ */
+export async function detectLsp(_cwd) {
+    const { editorClis, executableCandidates, readPlatformEnv, userDataBase } = await import("@canonical/harnesses");
+    const platform = readPlatformEnv();
+    const editors = editorClis
+        .filter((editor) => cliOnPath(executableCandidates(editor.cli, platform)))
+        .map((editor) => ({
+        editor,
+        installed: extensionInstalled(editor, platform),
+    }));
+    const state = editors.length === 0
+        ? "unknown"
+        : editors.every((e) => e.installed)
+            ? "installed"
+            : "absent";
+    return {
+        available: true,
+        state,
+        editors,
+        probed: editorClis.map((editor) => editor.cli),
+        stagingDir: join(userDataBase(platform), BIN_NAME, "lsp"),
+    };
+}
+/**
+ * The editors an install would act on: those missing the extension, narrowed to
+ * the user's per-editor selection when the wizard collected one.
+ *
+ * A machine commonly has several VS Code forks installed and the user wants the
+ * extension in one of them. Installing into all of them because they are on
+ * PATH is the same overreach the MCP row already avoids by offering its files.
+ *
+ * @param d - The detection gathered up front.
+ * @param chosen - Selected editor CLI names, or undefined for "all pending".
+ * @returns The editors to install into.
+ */
+export const selectedEditors = (d, chosen) => {
+    const pending = d.editors.filter((e) => !e.installed);
+    return chosen === undefined
+        ? pending
+        : pending.filter((e) => chosen.includes(e.editor.cli));
+};
+/** The editor names in a detection (for messages/results). */
+export const lspEditorNames = (d) => d.editors.map((e) => e.editor.name);
+/**
+ * The named-skip reason for a machine with no VS Code-family CLI on PATH. It
+ * names every CLI that was probed, because a skip the user cannot act on is
+ * only honest if it says what would have counted.
+ *
+ * @param d - The detection gathered up front.
+ * @returns The reason line.
+ */
+export const lspSkipReason = (d) => `no VS Code-family editor CLI on PATH (${d.probed.join(", ")})`;
+/**
+ * The remedy beneath that skip. It states plainly that nothing is possible here
+ * yet rather than offering a command for a binary this machine lacks — the rule
+ * every remedy line in this capability holds to.
+ */
+export const LSP_SKIP_REMEDY = "no action is possible on this machine yet — install VS Code or VSCodium, then run this again";
+/**
+ * Compose the LSP-install effects for a detection.
+ *
+ * Built from re-runnable combinators (NOT a single-use `gen`) because
+ * `execute` interprets the task twice (preview + perform); a dry-run mocks
+ * every exec (exit 0), so the preview shows the fetch + per-editor sideloads
+ * without spawning. Failures travel the task failure channel with
+ * machine-honest recoveries (see module docblock).
+ *
+ * @param d - The detection gathered up front.
+ * @returns A Task installing the extension into each editor missing it.
+ */
+export function composeLsp(d, chosen) {
+    // Nothing to install: no editor CLI on PATH (a named skip the plan row
+    // carries) or every detected editor already has it. Both compose NOTHING —
+    // what the run SAYS about this target is the plan row's business.
+    if (d.state !== "absent")
+        return sequence_([]);
+    const pending = selectedEditors(d, chosen);
+    // Every pending editor was deselected — there is no fetch to do either.
+    if (pending.length === 0)
+        return sequence_([]);
+    const vsixPath = lspVsixPath(d);
+    // Fetch the VSIX-bundling package into the pragma-owned staging dir. `bun`
+    // (not bunx) so the unpacked package — and its VSIX — survives at a stable
+    // path the recovery lines below can honestly point at.
+    const fetchCommand = `bun add ${LSP_PACKAGE}@latest`;
+    const fetchVsix = guardMissingBinary("bun", {
+        message: `Install Bun (https://bun.sh), then run \`${BIN_NAME} setup lsp\` again.`,
+    }, sequence_([
+        mkdir(d.stagingDir, true),
+        flatMap(exec("bun", ["add", `${LSP_PACKAGE}@latest`], d.stagingDir), (result) => checkExecOk(fetchCommand, result, {
+            message: "The extension package cannot be fetched — this machine cannot reach registry.npmjs.org. Check the connection, then run " +
+                `\`${BIN_NAME} setup lsp\` again.`,
+        })),
+    ]));
+    const sideloads = pending.map(({ editor }) => {
+        const command = `${editor.cli} --install-extension ${vsixPath}`;
+        return guardMissingBinary(editor.cli, {
+            message: `The \`${editor.cli}\` CLI disappeared from PATH mid-run — restore it, then run \`${BIN_NAME} setup lsp\` again.`,
+        }, flatMap(exec(editor.cli, ["--install-extension", vsixPath], d.stagingDir), (result) => checkExecOk(command, result, {
+            message: `${editor.name} refused the VSIX (its output is above). The file is kept at ${vsixPath} — retry by hand with ` +
+                `\`${command}\`, or update ${editor.name} first.`,
+        })));
+    });
+    return sequence_([fetchVsix, ...sideloads]);
+}
+/**
+ * Compose the removal — deliberately empty. An extension install is an `exec`,
+ * and an `exec` carries no reversal: pretending otherwise is what made
+ * `setup lsp --undo` report a step count for work it never did. The honest
+ * answer is the plan row's, which names the editor CLI that CAN uninstall it
+ * (see {@link lspUninstallRemedy}) or states that this machine has none.
+ *
+ * @param _d - The detection (unused; the shape is the table's).
+ * @returns An empty Task.
+ */
+export function composeLspRemoval(_d) {
+    return sequence_([]);
+}
+/**
+ * The uninstall instruction for a detection — a command that runs on THIS
+ * machine, or `undefined` when no editor CLI was found and there is therefore
+ * nothing honest to print.
+ *
+ * @param d - The detection gathered up front.
+ * @returns The uninstall command, or undefined.
+ */
+export function lspUninstallRemedy(d) {
+    const cli = d.editors.at(0)?.editor.cli;
+    return cli === undefined
+        ? undefined
+        : `${cli} --uninstall-extension ${EXTENSION_ID}`;
+}
+/** The VSIX path a failed sideload leaves behind for a manual retry. */
+export function lspVsixPath(d) {
+    return join(d.stagingDir, "node_modules", ...LSP_PACKAGE.split("/"), "terrazzo-lsp.vsix");
+}
+//# sourceMappingURL=setupLsp.js.map

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

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