@catalyst-cloud/cli 0.14.1 → 0.14.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.14.3
+
+- Setup can open the workspace's Linear approval from a personal login and wait for a fresh connection check before continuing. A saved credential alone does not count as connected.
+- Workspace approval links stay out of logs and receipts. Interrupted setup resumes with a fresh check, and older clouds keep their supported read-only verification path.
+
+## 0.14.2
+
+Choose an existing Linear team and its accessible repositories in the setup flow. Saved repository choices are checked again against current access and IDs before later setup.
+
+Interactive onboarding uses Clack for the shared plan choice, grouped progress and browser-wait spinners. Local sync is offered within the plan; unattended, JSON and dry-run output keep their plain defaults. Cancelling saves resumable progress and releases only the current setup lock.
+
+`catalyst onboard` runs setup steps with a private saved record and resumes by checking their current state. `--dry-run --json` prints a plan without changing files; `--only` completes a named step without claiming full onboarding. Sign-in validates the live person and workspace, and fake-HOME runs preserve legacy services and data.
+
+`catalyst ready --onboarding` distinguishes failed checks from missing evidence and reports observed work separately. Local sync is optional and can be included with `--local-sync`. Steps whose cloud capabilities are unavailable remain unfinished with a supported resume command. The installer handoff stays gated until its live prerequisites are verified.
+
 ## 0.14.1
 
 Legacy cleanup keeps all shared Catalyst config and data folders, including with the historical --data flag. It no longer removes ~/.catalyst/bin wholesale or recursively deletes directories. The onboarding skill keeps data and no longer offers data deletion.

package/README.md

@@ -114,6 +114,20 @@ A keyless session's access token is short-lived and rotates on its own: every re
 
 The setup skill Catalyst seeds into your repository ends by pointing at this same command. That served skill lives in the Catalyst Cloud application, not here; this is the only connect step a customer runs. Your cloud account's **account key** (Settings → Account keys, admin-minted) is a different credential — for a host or daemon that runs unattended — and is not what a person connects their own agent with: it would strip your name from everything your agent writes, and `login` says so if you use one.
 
+## Run and resume setup
+
+Run `catalyst onboard` for the steps supported by your installed CLI and cloud. The command shows its plan, opens supported browser consent links and saves progress. Resume with the same command; it rechecks completed steps before continuing. A missing cloud capability stays unfinished. In an interactive terminal, use the arrow keys to review the plan and choose cloud reads or optional local sync. Browser waits show progress. `--yes`, `--json`, `--dry-run` and non-terminal output stay plain.
+
+```sh
+catalyst onboard --dry-run --json
+catalyst onboard
+catalyst ready --onboarding --json
+```
+
+The dry run writes no files. `--only <step>` runs one step and reports its scope separately from full onboarding. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. The private receipt is `install/last-run.json` under your machine's Catalyst state directory; credentials stay in the login config. A fake HOME reports old services and keeps them intact.
+
+Local sync is optional. Include it in the plan with `--local-sync` when you need local SQL or offline access. A resume keeps that choice. Readiness distinguishes failed checks from missing evidence and reports observed project work separately from unfinished setup.
+
 ## Requirements
 
 - Node 22.15 or newer (Node 26 works), or bun 1.4 or newer. The bundle uses Node's built-in SQLite module (and, on bun, bun's own `node:sqlite`) for the optional local replica, so there is no native dependency to build; if `better-sqlite3` resolves on the machine it is used instead. `catalyst ready` names the exact reason when the runtime is too old, and `catalyst runtime install` installs a pinned Node under this CLI's own cache — without touching your machine's default Node — if you would rather not upgrade it.

package/dist/args.js

@@ -41,6 +41,9 @@ export const FLAG_TABLES = {
     },
     install: {},
     onboard: {
+        team: { value: true, help: "explicitly select an existing Linear team by ID or unique key" },
+        repo: { value: true, repeat: true, help: "explicitly select an accessible repository as owner/name (repeatable)" },
+        "local-sync": { value: false, help: "include the optional local sync setup in this plan" },
         "resume-from": { value: true, help: "resume at a verified onboarding step" },
         only: { value: true, help: "run only the named onboarding step" },
         yes: { value: false, help: "accept the plan's default choices" },
@@ -232,6 +235,8 @@ export const FLAG_TABLES = {
         role: { value: true, help: "accept: the role recording the answer" },
     },
     ready: {
+        onboarding: { value: false, help: "check current onboarding evidence and observed project work" },
+        "local-sync": { value: false, help: "include the selected local sync mode" },
         offline: {
             value: false,
             help: "skip the published-release check (no network)",
@@ -381,7 +386,7 @@ export const FLAG_TABLES = {
 };
 export const VERB_USAGE = {
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
-    onboard: "onboard [--resume-from <step>] [--only <step>] [--yes] [--dry-run] [--json]",
+    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--resume-from <step>] [--only <step>] [--local-sync] [--yes] [--dry-run] [--json]",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",
@@ -398,7 +403,7 @@ export const VERB_USAGE = {
     watch: "watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file <path>] [--from cursor|head]",
     write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--description|--stdin] [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
     ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
-    ready: "ready [--json] [--offline]",
+    ready: "ready [--onboarding] [--local-sync] [--json] [--offline]",
     accounts: "accounts [--json]",
     mcp: "mcp <add <name> --url URL <--auth none|--bearer SECRET_NAME|--header NAME=SECRET_NAME...>|list|remove <name>> [--json]",
     team: "team <list|check <KEY>|check --all|map <KEY> [--stage role=StateName]... [--yes --plan-hash H]|adopt <KEY> [--undo] [--yes --plan-hash H]|migrate <KEY> [--choice sourceId=destinationId]... [--retire] [--yes --plan-hash H]|checklist <KEY>> [--json]",

package/dist/cli.js

@@ -1,6 +1,7 @@
 // cli.ts — the `catalyst` dispatcher (npm: @catalyst-cloud/cli). Verbs live in
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
-import { existsSync } from "node:fs";
+import { existsSync, openSync, closeSync } from "node:fs";
+import { ReadStream as TerminalInput } from "node:tty";
 import { parseArgs, positionals, verbHelp } from "./args.js";
 import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, installerOwnsSkills, INSTALL_COMMAND, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
 import { loadContract, pickPath } from "./contract.js";
@@ -30,10 +31,14 @@ import { cmdTeam } from "./team.js";
 import { cmdCapabilities } from "./capabilities.js";
 import { cmdProject } from "./project.js";
 import { cmdRepo } from "./repo.js";
-import { cmdLegacy, findLegacy } from "./legacy.js";
+import { cmdLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdConnections } from "./connections.js";
-import { cmdOnboard } from "./onboard.js";
+import { cmdOnboard, onboardErrorJournal } from "./onboard.js";
+import { createClackOnboardUi, shouldUseOnboardUi } from "./onboard-ui.js";
+import { createOnboardRuntime } from "./onboard-runtime.js";
+import { onboardingReadyReport, observeCloudOnboarding } from "./onboard-ready.js";
+import { selectedOnboardTeam } from "./onboard-existing.js";
 export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, LEGACY_PACKAGE_NAME, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, modernCliPath, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
     "catalyst-github",
@@ -214,43 +219,78 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         return 0;
     }
     try {
-        migrateLegacyCliPath(ctx);
-        maybePrintUpdateNotice(args, ctx);
+        if (args.command !== "onboard") {
+            migrateLegacyCliPath(ctx);
+            maybePrintUpdateNotice(args, ctx);
+        }
         switch (args.command) {
             case "login":
                 return await cmdLogin(args, ctx, deps);
             case "install":
                 return cmdInstall(args, ctx);
-            case "onboard":
-                return await cmdOnboard(args, ctx, {
-                    runStep: async (id, stepCtx) => {
-                        if (id !== "legacy")
-                            return { state: "skipped" };
-                        const before = findLegacy(stepCtx.home, process.platform).filter((item) => !item.data).length;
-                        const safeCtx = args.json
-                            ? { ...stepCtx, stdout: stepCtx.stderr }
-                            : stepCtx;
-                        const legacyArgs = {
-                            ...args,
-                            command: "legacy",
-                            subcommand: null,
-                            rest: [],
-                            flags: { remove: true, yes: true },
-                            json: false,
-                            help: false,
-                            version: false,
-                        };
-                        const code = await cmdLegacy(legacyArgs, safeCtx, deps.legacy ?? {});
-                        if (code !== 0)
-                            throw new CliError("legacy cleanup did not finish", "onboard-legacy-failed", 10);
-                        const after = findLegacy(stepCtx.home, process.platform).filter((item) => !item.data).length;
-                        return {
-                            state: after === 0 ? "done" : "skipped",
-                            evidence: { found: before, remaining: after },
-                        };
-                    },
-                    isTty: deps.isTty ?? stdinIsTty,
-                }, readManifest().version);
+            case "onboard": {
+                let ui;
+                let terminal;
+                let input = process.stdin;
+                const originalRaw = Boolean(input.isRaw);
+                if (shouldUseOnboardUi(args, Boolean(process.stdout.isTTY))) {
+                    if (!input.isTTY) {
+                        try {
+                            const fd = openSync("/dev/tty", "r");
+                            try {
+                                terminal = new TerminalInput(fd);
+                                input = terminal;
+                            }
+                            catch (error) {
+                                closeSync(fd);
+                                throw error;
+                            }
+                        }
+                        catch {
+                            ctx.stderr("No controlling terminal is available; using the displayed defaults.");
+                        }
+                    }
+                    if (input.isTTY) {
+                        try {
+                            ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout });
+                        }
+                        catch (error) {
+                            terminal?.destroy();
+                            throw error;
+                        }
+                    }
+                }
+                try {
+                    return await cmdOnboard(args, ctx, {
+                        ...createOnboardRuntime(args, ctx, {
+                            ui,
+                            signinTimeoutMs: deps.onboardSigninTimeoutMs,
+                            login: (stepCtx, signal) => cmdLogin({ ...args, command: "login", flags: {}, json: false }, stepCtx, {
+                                ...deps, signal, isTty: () => true,
+                                waitForApproval: ui ? run => ui.wait("Waiting for Catalyst approval", run) : undefined,
+                            }, true),
+                            ready: async (stepCtx, journal) => {
+                                const team = selectedOnboardTeam(journal);
+                                const report = await onboardingReadyReport(stepCtx, { teamIds: team ? [team] : undefined, localSync: journal?.localSync ?? args.flags["local-sync"] === true, observe: observeCloudOnboarding });
+                                const failed = report.checks.some(check => check.required && check.state === "fail");
+                                return { state: report.state === "complete" ? "done" : failed ? "failed" : "waiting", reason: report.state === "complete" ? undefined : "onboarding_checks_pending",
+                                    evidence: { checks: report.checks.length, passed: report.checks.filter(check => check.state === "pass").length } };
+                            },
+                            legacy: deps.legacy,
+                            openBrowser: deps.openBrowser,
+                            sleep: deps.sleep,
+                            skillNames: CUSTOMER_SKILLS,
+                        }),
+                        ...(deps.isTty ? { isTty: deps.isTty } : {}),
+                    }, readManifest().version);
+                }
+                finally {
+                    ui?.dispose();
+                    if (input.isTTY && input.isRaw !== originalRaw)
+                        input.setRawMode(originalRaw);
+                    terminal?.destroy();
+                }
+            }
             case "notice":
                 return 0;
             case "status":
@@ -332,6 +372,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             return 1;
         }
         if (err instanceof CliError) {
+            if (args.command === "onboard" && args.json)
+                ctx.stdout(JSON.stringify(onboardErrorJournal(ctx, manifest.version, err.exitCode)));
             ctx.stderr(`catalyst: ${err.message}`);
             return err.exitCode;
         }
@@ -376,7 +418,12 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "legacy",
     "onboard",
 ].map((v) => [v, true]));
-async function cmdLogin(args, ctx, deps) {
+async function cmdLogin(args, ctx, deps, personalOnly = false) {
+    const checkCancelled = () => {
+        if (deps.signal?.aborted)
+            throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11);
+    };
+    checkCancelled();
     const manifest = readManifest();
     const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
     const baseUrl = normalizeBaseUrl(args.baseUrl ?? ctx.env.CATALYST_CLOUD_BASE_URL ?? DEFAULT_BASE_URL);
@@ -389,8 +436,14 @@ async function cmdLogin(args, ctx, deps) {
             isTty: deps.isTty ?? stdinIsTty,
             openBrowser: deps.openBrowser ?? defaultOpenBrowser,
             sleep: deps.sleep,
+            signal: deps.signal,
+            waitForApproval: deps.waitForApproval,
         })).accessToken;
+    checkCancelled();
     const me = await fetchMe(baseUrl, bearer, ctx.fetch);
+    checkCancelled();
+    if (personalOnly && !me.user)
+        throw new CliError("onboarding needs your personal login; sign in as yourself", "onboard-person-required", 12);
     let existing;
     try {
         existing = loadConfig(ctx.home);
@@ -416,6 +469,7 @@ async function cmdLogin(args, ctx, deps) {
         cliPath: cliPath(),
         replicaDb: existing?.replicaDb ?? defaultReplicaDbFor(ctx.home),
     };
+    checkCancelled();
     const written = writeConfig(ctx.home, config);
     ctx.stdout(`Connected to ${me.name} (${me.slug}) — account ${me.account}`);
     if (me.user) {
@@ -431,10 +485,12 @@ async function cmdLogin(args, ctx, deps) {
         : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
     ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     try {
-        const loaded = await loadContract(ctx, config, { refresh: true });
+        const loaded = await loadContract(ctx, config, { refresh: true, signal: deps.signal });
+        checkCancelled();
         ctx.stdout(`Tenant contract ${loaded.doc.contractVersion} cached at ${loaded.path}`);
     }
     catch (err) {
+        checkCancelled();
         if (err instanceof CliError &&
             (err.code === "contract-forbidden" || err.code === "contract-version")) {
             ctx.stderr(`[catalyst] ${err.message}`);
@@ -443,6 +499,7 @@ async function cmdLogin(args, ctx, deps) {
             throw err;
         }
     }
+    checkCancelled();
     if (previous && previous !== manifest.version) {
         const entry = parseChangelogEntry(readChangelog(), manifest.version);
         ctx.stdout(updateNoticeLine(previous, manifest.version, entry));

package/dist/contract.js

@@ -63,6 +63,9 @@ export function assertContractRange(version, range) {
  * naming both versions.
  */
 export async function loadContract(ctx, cfg, opts = {}) {
+    const cancelled = () => { if (opts.signal?.aborted)
+        throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11); };
+    cancelled();
     const path = contractPathFor(ctx.home);
     const cached = readContractCache(ctx.home);
     const nowMs = ctx.now().getTime();
@@ -85,6 +88,7 @@ export async function loadContract(ctx, cfg, opts = {}) {
         res = await api.getJson(CONTRACT_ROUTE, { etag: cached?.etag ?? null, accept: [304] });
     }
     catch (err) {
+        cancelled();
         if (err instanceof CliError && err.status === 403) {
             throw new CliError(`GET ${CONTRACT_ROUTE} refused (403): this cloud is older than the bundle and does not yet admit a personal key on the contract — update the cloud, or log in with the tenant's account key until it is`, "contract-forbidden", 2, 403);
         }
@@ -97,6 +101,7 @@ export async function loadContract(ctx, cfg, opts = {}) {
         }
         throw err;
     }
+    cancelled();
     if (res.status === 304) {
         if (!cached)
             throw new CliError(`GET ${CONTRACT_ROUTE} answered 304 with no cache to revalidate`, "contract-shape");

package/dist/env/parse-env.js

@@ -7,7 +7,9 @@ export function filterEnvFileNames(text, selected) {
         const trimmed = line.trim();
         if (trimmed === "" || trimmed.startsWith("#"))
             continue;
-        const assignment = trimmed.startsWith("export ") ? trimmed.slice("export ".length) : trimmed;
+        const assignment = trimmed.startsWith("export ")
+            ? trimmed.slice("export ".length)
+            : trimmed;
         const equals = assignment.indexOf("=");
         if (equals < 0)
             continue;
@@ -17,7 +19,37 @@ export function filterEnvFileNames(text, selected) {
         lines.push(line);
         found.add(name);
     }
-    return { text: lines.length === 0 ? "" : `${lines.join("\n")}\n`, found: [...found].sort((a, b) => a.localeCompare(b, "en")) };
+    return {
+        text: lines.length === 0 ? "" : `${lines.join("\n")}\n`,
+        found: [...found].sort((a, b) => a.localeCompare(b, "en")),
+    };
+}
+/** List dotenv assignment names without returning or logging values. */
+export function envFileNames(text) {
+    return envFileInventory(text).names;
+}
+/** Inventory assignments without values, preserving duplicate names (including `export NAME`). */
+export function envFileInventory(text) {
+    const counts = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const assignment = trimmed.startsWith("export ")
+            ? trimmed.slice("export ".length)
+            : trimmed;
+        const equals = assignment.indexOf("=");
+        if (equals < 0)
+            continue;
+        const name = assignment.slice(0, equals).trim();
+        if (name !== "")
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+    const sorted = [...counts.keys()].sort((a, b) => a.localeCompare(b, "en"));
+    return {
+        names: sorted,
+        duplicateNames: sorted.filter((name) => (counts.get(name) ?? 0) > 1),
+    };
 }
 /** Parse dotenv assignments using the mirror import grammar, after the caller has locally selected
  * names. Values stay in this process and are posted one at a time to the documented write route. */
@@ -27,7 +59,9 @@ export function parseEnvAssignments(text, selected) {
         const trimmed = rawLine.trim();
         if (trimmed === "" || trimmed.startsWith("#"))
             continue;
-        const assignment = trimmed.startsWith("export ") ? trimmed.slice("export ".length) : trimmed;
+        const assignment = trimmed.startsWith("export ")
+            ? trimmed.slice("export ".length)
+            : trimmed;
         const equals = assignment.indexOf("=");
         if (equals < 0)
             continue;
@@ -36,7 +70,9 @@ export function parseEnvAssignments(text, selected) {
             continue;
         const rawValue = assignment.slice(equals + 1);
         let value = rawValue.trim();
-        if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
             value = value.slice(1, -1);
         }
         else {

package/dist/env/selected-import.js

@@ -0,0 +1,249 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { envFileInventory, filterEnvFileNames } from "./parse-env.js";
+const NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+const SNAPSHOT_KEY = randomBytes(32);
+function normalizeNames(names) {
+    const valid = new Set();
+    let invalidNameCount = 0;
+    for (const entry of names) {
+        if (typeof entry !== "string") {
+            invalidNameCount += 1;
+            continue;
+        }
+        for (const raw of entry.split(",")) {
+            const name = raw.trim();
+            if (name === "")
+                continue;
+            if (!NAME_RE.test(name))
+                invalidNameCount += 1;
+            else
+                valid.add(name);
+        }
+    }
+    return {
+        names: [...valid].sort((a, b) => a.localeCompare(b, "en")),
+        invalidNameCount,
+    };
+}
+function snapshotId(text, requestedNames, allowedNames, invalidNameCount, invalidAuthorityNameCount) {
+    return createHmac("sha256", SNAPSHOT_KEY)
+        .update(JSON.stringify([
+        text,
+        requestedNames,
+        normalizeNames(allowedNames),
+        invalidNameCount,
+        invalidAuthorityNameCount,
+    ]))
+        .digest("hex");
+}
+function isSafeCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function matchesSnapshot(text, names, allowedNames, invalidNameCount, invalidAuthorityNameCount, expected) {
+    if (!isSafeCount(invalidNameCount) ||
+        !isSafeCount(invalidAuthorityNameCount) ||
+        invalidAuthorityNameCount > invalidNameCount) {
+        return false;
+    }
+    const actual = Buffer.from(snapshotId(text, names, allowedNames, invalidNameCount, invalidAuthorityNameCount), "hex");
+    const wanted = Buffer.from(expected, "hex");
+    return actual.length === wanted.length && timingSafeEqual(actual, wanted);
+}
+/** Plan one explicit Q4 selection against a file and declaration allowlist. Invalid input is
+ * reduced to a count before it can enter the plan. `allowedNames` is deliberately not retained. */
+function planSelectedNameImport(input) {
+    const requested = normalizeNames(input.requestedNames);
+    const available = normalizeNames(input.availableNames);
+    const allowlist = normalizeNames(input.allowedNames);
+    const duplicates = normalizeNames(input.duplicateNames ?? []);
+    const allowed = new Set(allowlist.names);
+    const availableSet = new Set(available.names);
+    const requestedNames = requested.names;
+    const selectedNames = requestedNames.filter((name) => allowed.has(name) && availableSet.has(name));
+    const unknownNames = requestedNames.filter((name) => !allowed.has(name));
+    const missingNames = requestedNames.filter((name) => allowed.has(name) && !availableSet.has(name));
+    const selectedDuplicates = duplicates.names.filter((name) => selectedNames.includes(name));
+    const invalidNameCount = requested.invalidNameCount +
+        available.invalidNameCount +
+        allowlist.invalidNameCount +
+        duplicates.invalidNameCount;
+    const invalidAuthorityNameCount = available.invalidNameCount +
+        allowlist.invalidNameCount +
+        duplicates.invalidNameCount;
+    const state = invalidNameCount === 0 &&
+        unknownNames.length === 0 &&
+        missingNames.length === 0 &&
+        selectedDuplicates.length === 0
+        ? "ready"
+        : "rejected";
+    const plan = {
+        state,
+        requestedNames,
+        selectedNames,
+        missingNames,
+        unknownNames,
+        duplicateNames: selectedDuplicates,
+        invalidNameCount,
+        invalidAuthorityNameCount,
+        snapshotId: "",
+    };
+    return Object.freeze({
+        ...plan,
+        requestedNames: Object.freeze([...requestedNames]),
+        selectedNames: Object.freeze([...selectedNames]),
+        missingNames: Object.freeze([...missingNames]),
+        unknownNames: Object.freeze([...unknownNames]),
+        duplicateNames: Object.freeze([...selectedDuplicates]),
+        invalidAuthorityNameCount,
+        snapshotId: "",
+    });
+}
+function planWithSnapshot(input) {
+    const inventory = envFileInventory(input.text);
+    const plan = planSelectedNameImport({
+        requestedNames: input.requestedNames,
+        availableNames: inventory.names,
+        duplicateNames: inventory.duplicateNames,
+        allowedNames: input.allowedNames,
+    });
+    return Object.freeze({
+        ...plan,
+        snapshotId: snapshotId(input.text, plan.requestedNames, input.allowedNames, plan.invalidNameCount, plan.invalidAuthorityNameCount),
+    });
+}
+function uncertainResult(base, selectedNames) {
+    return {
+        ...base,
+        state: "uncertain",
+        writtenNames: [],
+        failedNames: [],
+        uncertainNames: [...selectedNames],
+        count: {
+            selected: selectedNames.length,
+            written: 0,
+            failed: 0,
+            uncertain: selectedNames.length,
+        },
+    };
+}
+function sanitizeWriterResult(value, selectedNames) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    if (!Object.hasOwn(record, "writtenNames") &&
+        !Object.hasOwn(record, "failedNames")) {
+        return null;
+    }
+    const readNames = (field) => {
+        if (!Object.hasOwn(record, field))
+            return [];
+        const raw = record[field];
+        if (raw === undefined)
+            return null;
+        if (!Array.isArray(raw))
+            return null;
+        const entries = Array.from(raw);
+        if (!entries.every((name) => typeof name === "string" && NAME_RE.test(name)) ||
+            entries.some((name) => !selectedNames.includes(name))) {
+            return null;
+        }
+        return [...new Set(entries)];
+    };
+    const writtenNames = readNames("writtenNames");
+    const failedNames = readNames("failedNames");
+    if (writtenNames === null || failedNames === null)
+        return null;
+    return { writtenNames, failedNames };
+}
+/** Convenience for Q4: inventory and build the value-free plan in one call. */
+export function planSelectedNameImportFromText(input) {
+    return planWithSnapshot(input);
+}
+/** Execute only the selection reviewed against this exact source snapshot. The authoritative
+ * declaration allowlist is supplied separately from the plan so mutating/forging a plan cannot
+ * widen write capability. */
+export async function executeSelectedNameImport(text, plan, allowedNames, writer) {
+    const currentPlan = planWithSnapshot({
+        text,
+        requestedNames: plan.requestedNames,
+        allowedNames,
+    });
+    const matchesReviewedPlan = matchesSnapshot(text, plan.requestedNames, allowedNames, plan.invalidNameCount, plan.invalidAuthorityNameCount, plan.snapshotId);
+    const authenticatedAuthorityCount = matchesReviewedPlan &&
+        plan.invalidAuthorityNameCount === currentPlan.invalidAuthorityNameCount;
+    const base = {
+        requestedNames: [...currentPlan.requestedNames],
+        selectedNames: [...currentPlan.selectedNames],
+        missingNames: [...currentPlan.missingNames],
+        unknownNames: [...currentPlan.unknownNames],
+        duplicateNames: [...currentPlan.duplicateNames],
+        invalidNameCount: authenticatedAuthorityCount
+            ? plan.invalidNameCount
+            : currentPlan.invalidAuthorityNameCount,
+    };
+    if (plan.state !== "ready" ||
+        currentPlan.state !== "ready" ||
+        !matchesReviewedPlan ||
+        currentPlan.snapshotId !== plan.snapshotId) {
+        return {
+            ...base,
+            state: "rejected",
+            writtenNames: [],
+            failedNames: [],
+            uncertainNames: [],
+            count: {
+                selected: currentPlan.selectedNames.length,
+                written: 0,
+                failed: 0,
+                uncertain: 0,
+            },
+        };
+    }
+    if (currentPlan.selectedNames.length === 0) {
+        return {
+            ...base,
+            state: "written",
+            writtenNames: [],
+            failedNames: [],
+            uncertainNames: [],
+            count: { selected: 0, written: 0, failed: 0, uncertain: 0 },
+        };
+    }
+    const filtered = filterEnvFileNames(text, new Set(currentPlan.selectedNames));
+    let outcome;
+    try {
+        const rawOutcome = await writer(filtered.text, [
+            ...currentPlan.selectedNames,
+        ]);
+        outcome = sanitizeWriterResult(rawOutcome, currentPlan.selectedNames);
+    }
+    catch {
+        return uncertainResult(base, currentPlan.selectedNames);
+    }
+    if (outcome === null)
+        return uncertainResult(base, currentPlan.selectedNames);
+    const selected = new Set(currentPlan.selectedNames);
+    const reportedWritten = normalizeNames(outcome.writtenNames ?? []).names.filter((name) => selected.has(name));
+    const reportedFailed = normalizeNames(outcome.failedNames ?? []).names.filter((name) => selected.has(name));
+    const conflicting = new Set(reportedWritten.filter((name) => reportedFailed.includes(name)));
+    const writtenNames = reportedWritten.filter((name) => !conflicting.has(name));
+    const failed = new Set(reportedFailed);
+    for (const name of currentPlan.selectedNames)
+        if (!writtenNames.includes(name))
+            failed.add(name);
+    const failedNames = currentPlan.selectedNames.filter((name) => failed.has(name));
+    return {
+        ...base,
+        state: "written",
+        writtenNames,
+        failedNames,
+        uncertainNames: [],
+        count: {
+            selected: currentPlan.selectedNames.length,
+            written: writtenNames.length,
+            failed: failedNames.length,
+            uncertain: 0,
+        },
+    };
+}