grounder 0.4.0 → 0.6.0

package/dist/commands/setup.js

@@ -0,0 +1,210 @@
+import { mkdir } from "node:fs/promises";
+import { runtimeCliPath } from "../agents/hook-runtime.js";
+import { resolveAgents } from "../agents/index.js";
+import { homeConfigPath, InvalidHomeConfigError, readHomeConfig, withHomeDir, writeHomeConfig, } from "../connector/home.js";
+import { ledgerVersionChanged, readGrounderState, statePath, } from "../connector/state.js";
+import { isUnsupportedSchemaError } from "../connector/unsupported-schema.js";
+import { helpExitCode } from "../help.js";
+import { VERSION } from "../index.js";
+import { flagBool, flagStrings, parseArgs } from "../util/parse-args.js";
+import { resolveUserPath } from "../util/path.js";
+import { confirm } from "../util/prompt.js";
+import { projectsParent } from "../vault/layout.js";
+import { applyAgentInstalls } from "./apply.js";
+import { renderAgentErrors, renderModifiedNote, renderSummary, renderTable, rowsFromApplyResult, stateRow, } from "./render-artifact-table.js";
+/**
+ * Read the existing home config for the "already exists with a different
+ * vault" conflict check. A corrupt/invalid file has no value worth
+ * conflict-checking — treat it as absent so `setup` can recreate it without
+ * requiring the user to manually delete it first.
+ */
+async function readExistingHomeForSetup() {
+    try {
+        return { home: await readHomeConfig(), invalidReason: null };
+    }
+    catch (error) {
+        const reason = error instanceof InvalidHomeConfigError
+            ? error.reason
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        return { home: null, invalidReason: reason };
+    }
+}
+export async function runSetup(argv) {
+    const helpCode = helpExitCode(argv, "setup");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    const { positional, flags, repeated } = parseArgs(argv);
+    const vaultPathArg = positional[0];
+    const yes = flagBool(flags, "yes", "y");
+    const force = flagBool(flags, "force", "f");
+    const hooks = flagBool(flags, "hooks");
+    const dryRun = flagBool(flags, "dry-run");
+    const agents = flagStrings(repeated, "agent");
+    if (!vaultPathArg) {
+        process.stderr.write("Usage: grounder setup <path>\n");
+        return 1;
+    }
+    return runSetupWithOptions({
+        vaultPath: vaultPathArg,
+        yes,
+        force,
+        hooks,
+        dryRun,
+        agents: agents.length > 0 ? agents : undefined,
+    });
+}
+export async function runSetupWithOptions(options) {
+    return withHomeDir(options.homeDir, async () => {
+        const vaultRoot = resolveUserPath(options.vaultPath);
+        const yes = options.yes ?? false;
+        const force = options.force ?? false;
+        const hooks = options.hooks ?? false;
+        const dryRun = options.dryRun ?? false;
+        const homeDir = options.homeDir;
+        const { home: existingHome, invalidReason } = await readExistingHomeForSetup();
+        const projectsDir = projectsParent(vaultRoot);
+        const agents = await resolveAgents(options.agents);
+        if (existingHome && existingHome.vaultRoot !== vaultRoot && !force) {
+            process.stderr.write(`Home config already exists with vault ${existingHome.vaultRoot}. Use --force to overwrite.\n`);
+            return 1;
+        }
+        if (invalidReason) {
+            process.stdout.write(dryRun
+                ? `Would replace invalid home config (${invalidReason}).\n`
+                : `Will replace invalid home config (${invalidReason}).\n`);
+        }
+        process.stdout.write(`Vault root: ${vaultRoot}\n`);
+        process.stdout.write("Connect to a markdown vault (once per machine).\n");
+        process.stdout.write(dryRun ? "Would write:\n" : "Will write:\n");
+        // One label column shared by every preview line — "runtime" (not "grounder
+        // runtime") so it's no wider than it needs to be and lines up with the
+        // agent ids instead of forcing its own, much wider, column.
+        const previewLabelWidth = Math.max("home".length, "vault".length, "runtime".length, ...agents.map((agent) => agent.id.length));
+        process.stdout.write(`  ${"home".padEnd(previewLabelWidth)} ${homeConfigPath(homeDir)}\n`);
+        process.stdout.write(`  ${"vault".padEnd(previewLabelWidth)} 10-Projects/ (if missing)\n`);
+        if (agents.length > 0) {
+            process.stdout.write(`  ${"runtime".padEnd(previewLabelWidth)} ${runtimeCliPath(homeDir)}\n`);
+        }
+        for (const agent of agents) {
+            const label = agent.id.padEnd(previewLabelWidth);
+            for (const artifactPath of agent.expectedArtifacts(homeDir)) {
+                process.stdout.write(`  ${label} ${artifactPath}\n`);
+            }
+            if (hooks && agent.expectedHookArtifacts) {
+                for (const hookPath of agent.expectedHookArtifacts(homeDir)) {
+                    process.stdout.write(`  ${label} hook ${hookPath}\n`);
+                }
+            }
+        }
+        if (agents.length === 0) {
+            process.stdout.write("  (no supported agents detected — skipping agent artifacts)\n");
+        }
+        process.stdout.write("\n");
+        if (dryRun) {
+            let priorState;
+            let applyResult;
+            try {
+                priorState = await readGrounderState(homeDir);
+                applyResult = await applyAgentInstalls({
+                    agents,
+                    force,
+                    hooks,
+                    // `setup` never retires legacy pre-skill command files, even with
+                    // `--force` — see docs/upgrading.md and ApplyAgentInstallsOptions#retireLegacy.
+                    retireLegacy: false,
+                    dryRun: true,
+                    homeDir,
+                    grounderVersion: VERSION,
+                });
+            }
+            catch (error) {
+                if (isUnsupportedSchemaError(error)) {
+                    process.stderr.write(`${error.message}\n`);
+                    return 1;
+                }
+                const detail = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`Dry run failed: agent install would not succeed:\n  ${detail}\n`);
+                return 1;
+            }
+            if (agents.length === 0) {
+                return 0;
+            }
+            // A dry run never writes `~/.grounder/config.json` — if it doesn't
+            // already exist (first-time setup, or one whose config is invalid and
+            // would be replaced), `grounder migrate --force` would fail with "No
+            // home config found" until this exact command is re-run without
+            // `--dry-run`. Point the reader at that instead of a command that
+            // can't work yet.
+            const forceCommand = existingHome
+                ? "grounder migrate"
+                : `grounder setup ${options.vaultPath}`;
+            const hadAgentError = reportAgentInstalls(applyResult, priorState, homeDir, true, forceCommand);
+            return hadAgentError ? 1 : 0;
+        }
+        if (!yes) {
+            const proceed = await confirm("Proceed?");
+            if (!proceed) {
+                process.stdout.write("Aborted.\n");
+                return 0;
+            }
+        }
+        await writeHomeConfig({ vaultRoot });
+        await mkdir(projectsDir, { recursive: true });
+        process.stdout.write("✓ Wrote home config\n");
+        process.stdout.write(`✓ Vault scaffold: ${projectsDir}\n`);
+        let priorState;
+        let applyResult;
+        try {
+            priorState = await readGrounderState(homeDir);
+            applyResult = await applyAgentInstalls({
+                agents,
+                force,
+                hooks,
+                retireLegacy: false,
+                homeDir,
+                grounderVersion: VERSION,
+            });
+        }
+        catch (error) {
+            if (isUnsupportedSchemaError(error)) {
+                process.stderr.write(`${error.message}\n`);
+                return 1;
+            }
+            const detail = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`\nHome config and vault scaffold were written, but agent skill files/hooks were not installed:\n  ${detail}\n`);
+            return 1;
+        }
+        if (agents.length === 0) {
+            return 0;
+        }
+        // Real setup has already written a valid home config by this point
+        // (above), so `grounder migrate --force` always works as the remediation
+        // command here.
+        const hadAgentError = reportAgentInstalls(applyResult, priorState, homeDir, false, "grounder migrate");
+        return hadAgentError ? 1 : 0;
+    });
+}
+/**
+ * Render the table/summary/conflict-note block shared by a dry-run preview
+ * and a real apply — same rows, same wording, only `renderSummary`'s tense
+ * differs, so a dry run tells the truth about what a real run would show.
+ * Returns whether any agent's hook step failed (see
+ * `AgentApplyResult#error`), so the caller can exit non-zero without
+ * duplicating that check.
+ */
+function reportAgentInstalls(applyResult, priorState, homeDir, dryRun, forceCommand) {
+    const rows = rowsFromApplyResult(applyResult);
+    const ledgerChanged = applyResult.agents.some((a) => a.ledgerChanged) || ledgerVersionChanged(priorState, VERSION);
+    rows.push(stateRow(ledgerChanged, priorState, statePath(homeDir)));
+    process.stdout.write("\n");
+    renderTable(rows);
+    process.stdout.write("\n");
+    renderSummary(rows, dryRun);
+    renderModifiedNote(rows, forceCommand);
+    renderAgentErrors(applyResult);
+    return applyResult.agents.some((a) => a.error !== undefined);
+}
+//# sourceMappingURL=setup.js.map

package/dist/commands/setup.js.map

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

package/dist/commands/status.d.ts

@@ -1,7 +1,14 @@
 export interface StatusOptions {
     cwd?: string;
     homeDir?: string;
+    json?: boolean;
 }
+/**
+ * Bump whenever `writeJsonOutput`'s payload shape changes (fields added,
+ * removed, or renamed) — consumers (the VS Code extension's `status.ts`)
+ * compare this directly instead of inferring compatibility structurally.
+ */
+export declare const STATUS_JSON_SCHEMA_VERSION = 1;
 export declare function runStatus(argv: string[]): Promise<number>;
 export declare function runStatusWithOptions(options?: StatusOptions): Promise<number>;
 //# sourceMappingURL=status.d.ts.map

package/dist/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAO/D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4EvF"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAoWD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAoC5C,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB/D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUvF"}

package/dist/commands/status.js

@@ -1,36 +1,30 @@
 import path from "node:path";
-import { ALL_AGENTS } from "../agents/index.js";
 import { currentBranch, findGitRoot } from "../connector/git.js";
 import { homeConfigPath, readHomeConfig, withHomeDir } from "../connector/home.js";
 import { findLinkedRepoRoot, readRepoConfig, repoConfigPath, } from "../connector/repo.js";
-import { isInstallSchemaStale, readGrounderState, statePath } from "../connector/state.js";
+import { readGrounderState, statePath } from "../connector/state.js";
 import { isUnsupportedSchemaError } from "../connector/unsupported-schema.js";
-import { resolveLogsDir, resolveNotesDir, resolvePlansDir, resolveVaultRoot, } from "../connector/vault.js";
+import { resolveLogsDir, resolveNotesDir, resolvePlansDir, resolveProjectVaultRoot, resolveVaultRoot, } from "../connector/vault.js";
 import { helpExitCode } from "../help.js";
 import { VERSION } from "../index.js";
+import { flagBool, parseArgs } from "../util/parse-args.js";
+import { installDriftDetected } from "./install-drift.js";
 import { writeSection } from "./output.js";
 import { packageVersionNotice } from "./package-version-notice.js";
 const LABEL_WIDTH = 12;
-const VAULT_INIT = "grounder vault init <path>";
-const REPO_INIT = "grounder init";
-const REPO_INIT_FORCE = "grounder init --force";
+const VAULT_INIT = "grounder setup <path>";
+const REPO_INIT = "grounder link";
+const REPO_INIT_FORCE = "grounder link --force";
 const MIGRATE = "grounder migrate";
 const MIGRATE_FORCE = "grounder migrate --force";
 const UPGRADE_GROUNDER = "upgrade grounder";
+const USAGE = "Usage: grounder status [--json]\n";
 function statusLine(label, value) {
     return `  ${label.padEnd(LABEL_WIDTH)}${value}\n`;
 }
 function errorDetail(error) {
     return error instanceof Error ? error.message : String(error);
 }
-async function writeGitLine(gitRoot) {
-    if (!gitRoot) {
-        return;
-    }
-    const branch = await currentBranch(gitRoot);
-    const gitValue = branch !== undefined ? `${gitRoot}  (branch: ${branch})` : gitRoot;
-    process.stdout.write(statusLine("Git:", gitValue));
-}
 async function tryReadHome() {
     try {
         return { home: await readHomeConfig(), invalid: null };
@@ -51,94 +45,290 @@ async function tryReadRepo(linkedRoot) {
         };
     }
 }
-async function writeInstallStateLine(homeDir) {
+async function gatherStateInfo(homeDir) {
     try {
         const state = await readGrounderState(homeDir);
         if (!state) {
-            process.stdout.write(statusLine("State:", `missing → ${MIGRATE_FORCE}`));
-            return;
-        }
-        process.stdout.write(statusLine("State:", statePath(homeDir)));
-        const packageNotice = packageVersionNotice(VERSION, state.grounderVersion);
-        if (packageNotice) {
-            process.stdout.write(statusLine("Package:", packageNotice.status));
-        }
-        if (isInstallSchemaStale(state, ALL_AGENTS)) {
-            process.stdout.write(statusLine("Schemas:", `ledger stale → ${MIGRATE}`));
-        }
-        else {
-            process.stdout.write(statusLine("Schemas:", "current"));
+            return {
+                path: statePath(homeDir),
+                status: "missing",
+                packageNotice: null,
+                installCurrent: null,
+            };
         }
+        const notice = packageVersionNotice(VERSION, state.grounderVersion);
+        const drift = await installDriftDetected(state, homeDir);
+        return {
+            path: statePath(homeDir),
+            status: "ok",
+            packageNotice: notice,
+            installCurrent: !drift,
+        };
+    }
+    catch (error) {
+        return {
+            path: statePath(homeDir),
+            status: isUnsupportedSchemaError(error) ? "unsupported" : "invalid",
+            packageNotice: null,
+            installCurrent: null,
+        };
+    }
+}
+async function gatherMachine(homeInvalid, home, homeDir) {
+    const configPath = homeConfigPath(homeDir);
+    if (homeInvalid) {
+        return { configPath, configState: "invalid", vaultRoot: null, state: null };
+    }
+    if (!home) {
+        return { configPath, configState: "missing", vaultRoot: null, state: null };
+    }
+    return {
+        configPath,
+        configState: "ok",
+        vaultRoot: resolveVaultRoot(home),
+        state: await gatherStateInfo(homeDir),
+    };
+}
+async function gatherGit(gitRoot) {
+    if (!gitRoot) {
+        return null;
+    }
+    const branch = await currentBranch(gitRoot);
+    return { root: gitRoot, branch: branch ?? null };
+}
+async function gatherProject(params) {
+    const { cwd, gitRoot, linkedRoot, repo, repoInvalid, repoUnsupported, home } = params;
+    if (!linkedRoot) {
+        return {
+            linked: false,
+            folder: null,
+            isAncestorLink: false,
+            configPath: null,
+            configState: "missing",
+            projectId: null,
+            vaultRoot: null,
+            notesDir: null,
+            logsDir: null,
+            plansDir: null,
+            git: null,
+        };
+    }
+    const git = await gatherGit(gitRoot);
+    const isAncestorLink = linkedRoot !== cwd;
+    const configPath = repoConfigPath(linkedRoot);
+    if (repoInvalid || !repo) {
+        const configState = repoUnsupported
+            ? "unsupported"
+            : repoInvalid
+                ? "invalid"
+                : "missing";
+        return {
+            linked: true,
+            folder: linkedRoot,
+            isAncestorLink,
+            configPath,
+            configState,
+            projectId: null,
+            vaultRoot: null,
+            notesDir: null,
+            logsDir: null,
+            plansDir: null,
+            git,
+        };
+    }
+    return {
+        linked: true,
+        folder: linkedRoot,
+        isAncestorLink,
+        configPath,
+        configState: "ok",
+        projectId: repo.projectId,
+        vaultRoot: home ? resolveProjectVaultRoot(home, repo) : null,
+        notesDir: home ? resolveNotesDir(home, repo) : null,
+        logsDir: home ? resolveLogsDir(home, repo) : null,
+        plansDir: home ? resolvePlansDir(home, repo) : null,
+        git,
+    };
+}
+async function gatherStatus(options) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const { home, invalid: homeInvalid } = await tryReadHome();
+    const gitRoot = await findGitRoot(cwd);
+    const linkedRoot = await findLinkedRepoRoot(cwd, gitRoot);
+    const { repo, invalid: repoInvalid, unsupported: repoUnsupported, } = linkedRoot
+        ? await tryReadRepo(linkedRoot)
+        : { repo: null, invalid: null, unsupported: false };
+    const machine = await gatherMachine(homeInvalid, home, options.homeDir);
+    const project = await gatherProject({
+        cwd,
+        gitRoot,
+        linkedRoot,
+        repo,
+        repoInvalid,
+        repoUnsupported,
+        home,
+    });
+    return { cwd, machine, project };
+}
+/**
+ * `findLinkedRepoRoot` walks up to the nearest `.grounder.json`, so a
+ * subdirectory of a linked repo inherits that link. Surface it explicitly
+ * when `linkedRoot` isn't `cwd` itself, so callers (agents included) don't
+ * mistake an ancestor's link for this exact folder being linked.
+ */
+function writeAncestorNoteIfAny(cwd, folder) {
+    if (folder === cwd) {
+        return;
+    }
+    process.stdout.write(statusLine("Note:", `linked ancestor — ${cwd} itself is unlinked; grounder link here would create a separate project`));
+}
+function writeGitLine(git) {
+    if (!git) {
+        return;
+    }
+    const value = git.branch !== null ? `${git.root}  (branch: ${git.branch})` : git.root;
+    process.stdout.write(statusLine("Git:", value));
+}
+function writeStateLines(state) {
+    if (state.status === "missing") {
+        process.stdout.write(statusLine("State:", `missing → ${MIGRATE_FORCE}`));
+        return;
+    }
+    if (state.status === "unsupported") {
+        process.stdout.write(statusLine("State:", `unsupported → ${UPGRADE_GROUNDER}`));
+        return;
     }
-    catch {
+    if (state.status === "invalid") {
         process.stdout.write(statusLine("State:", `invalid → ${MIGRATE_FORCE}`));
+        return;
     }
+    process.stdout.write(statusLine("State:", state.path));
+    if (state.packageNotice) {
+        process.stdout.write(statusLine("Package:", state.packageNotice.status));
+    }
+    process.stdout.write(statusLine("Install:", state.installCurrent ? "current" : `outdated → ${MIGRATE}`));
+}
+function writeTextOutput(status) {
+    const { cwd, machine, project } = status;
+    writeSection("Machine");
+    if (machine.configState === "invalid") {
+        process.stdout.write(statusLine("Config:", `invalid → ${VAULT_INIT}`));
+    }
+    else if (machine.configState === "missing") {
+        process.stdout.write(statusLine("Config:", `missing → ${VAULT_INIT}`));
+    }
+    else {
+        process.stdout.write(statusLine("Config:", machine.configPath));
+        process.stdout.write(statusLine("Vault:", machine.vaultRoot));
+        writeStateLines(machine.state);
+    }
+    process.stdout.write("\n");
+    writeSection("Project");
+    if (!project.linked) {
+        process.stdout.write(statusLine("Linked:", "no"));
+        if (machine.configState === "ok") {
+            process.stdout.write(statusLine("Config:", `missing → ${REPO_INIT}`));
+        }
+        return;
+    }
+    const folder = project.folder;
+    if (project.configState !== "ok") {
+        const fix = project.configState === "unsupported"
+            ? UPGRADE_GROUNDER
+            : machine.configState === "ok"
+                ? REPO_INIT_FORCE
+                : VAULT_INIT;
+        process.stdout.write(statusLine("Linked:", project.configState === "unsupported" ? `unsupported → ${fix}` : `incomplete → ${fix}`));
+        process.stdout.write(statusLine("Folder:", folder));
+        writeAncestorNoteIfAny(cwd, folder);
+        process.stdout.write(statusLine("Config:", project.configState === "unsupported"
+            ? `unsupported → ${UPGRADE_GROUNDER}`
+            : project.configState === "invalid"
+                ? `invalid → ${REPO_INIT_FORCE}`
+                : `missing → ${REPO_INIT}`));
+        writeGitLine(project.git);
+        return;
+    }
+    process.stdout.write(statusLine("Linked:", "yes"));
+    process.stdout.write(statusLine("Folder:", folder));
+    writeAncestorNoteIfAny(cwd, folder);
+    process.stdout.write(statusLine("Config:", project.configPath));
+    process.stdout.write(statusLine("Id:", project.projectId));
+    if (project.notesDir) {
+        process.stdout.write(statusLine("In Vault:", project.vaultRoot));
+        process.stdout.write(statusLine("Notes:", project.notesDir));
+        process.stdout.write(statusLine("Logs:", project.logsDir));
+        process.stdout.write(statusLine("Plans:", project.plansDir));
+    }
+    writeGitLine(project.git);
+}
+/**
+ * Bump whenever `writeJsonOutput`'s payload shape changes (fields added,
+ * removed, or renamed) — consumers (the VS Code extension's `status.ts`)
+ * compare this directly instead of inferring compatibility structurally.
+ */
+export const STATUS_JSON_SCHEMA_VERSION = 1;
+function writeJsonOutput(status) {
+    const { machine, project } = status;
+    const payload = {
+        schemaVersion: STATUS_JSON_SCHEMA_VERSION,
+        machine: {
+            configPath: machine.configPath,
+            configState: machine.configState,
+            vaultRoot: machine.vaultRoot,
+            state: machine.state
+                ? {
+                    path: machine.state.path,
+                    status: machine.state.status,
+                    packageVersionNotice: machine.state.packageNotice?.message ?? null,
+                    installCurrent: machine.state.installCurrent,
+                }
+                : null,
+        },
+        project: {
+            linked: project.linked,
+            folder: project.folder,
+            isAncestorLink: project.isAncestorLink,
+            configPath: project.configPath,
+            configState: project.configState,
+            projectId: project.projectId,
+            vaultRoot: project.vaultRoot,
+            notesDir: project.notesDir,
+            logsDir: project.logsDir,
+            plansDir: project.plansDir,
+            git: project.git,
+        },
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
 }
 export async function runStatus(argv) {
     const helpCode = helpExitCode(argv, "status");
     if (helpCode !== null) {
         return helpCode;
     }
-    return runStatusWithOptions({});
+    const { positional, flags } = parseArgs(argv);
+    if (positional.length > 0) {
+        process.stderr.write(USAGE);
+        return 1;
+    }
+    const allowedFlags = new Set(["json"]);
+    for (const key of flags.keys()) {
+        if (!allowedFlags.has(key)) {
+            process.stderr.write(USAGE);
+            return 1;
+        }
+    }
+    return runStatusWithOptions({ json: flagBool(flags, "json") });
 }
 export async function runStatusWithOptions(options = {}) {
     return withHomeDir(options.homeDir, async () => {
-        const cwd = path.resolve(options.cwd ?? process.cwd());
-        const { home, invalid: homeInvalid } = await tryReadHome();
-        const gitRoot = await findGitRoot(cwd);
-        const linkedRoot = await findLinkedRepoRoot(cwd, gitRoot);
-        const { repo, invalid: repoInvalid, unsupported: repoUnsupported, } = linkedRoot
-            ? await tryReadRepo(linkedRoot)
-            : { repo: null, invalid: null, unsupported: false };
-        writeSection("Machine");
-        if (homeInvalid) {
-            process.stdout.write(statusLine("Config:", `invalid → ${VAULT_INIT}`));
-        }
-        else if (!home) {
-            process.stdout.write(statusLine("Config:", `missing → ${VAULT_INIT}`));
+        const status = await gatherStatus(options);
+        if (options.json) {
+            writeJsonOutput(status);
         }
         else {
-            process.stdout.write(statusLine("Config:", homeConfigPath()));
-            process.stdout.write(statusLine("Vault:", resolveVaultRoot(home)));
-            await writeInstallStateLine(options.homeDir);
-        }
-        process.stdout.write("\n");
-        writeSection("Project");
-        if (!linkedRoot) {
-            process.stdout.write(statusLine("Linked:", "no"));
-            if (home) {
-                process.stdout.write(statusLine("Config:", `missing → ${REPO_INIT}`));
-            }
-            return 0;
-        }
-        if (repoInvalid || !repo) {
-            const fix = repoUnsupported ? UPGRADE_GROUNDER : home ? REPO_INIT_FORCE : VAULT_INIT;
-            process.stdout.write(statusLine("Linked:", repoUnsupported ? `unsupported → ${fix}` : `incomplete → ${fix}`));
-            process.stdout.write(statusLine("Folder:", linkedRoot));
-            process.stdout.write(statusLine("Config:", repoUnsupported
-                ? `unsupported → ${UPGRADE_GROUNDER}`
-                : repoInvalid
-                    ? `invalid → ${REPO_INIT_FORCE}`
-                    : `missing → ${REPO_INIT}`));
-            await writeGitLine(gitRoot);
-            return 0;
-        }
-        if (!home) {
-            process.stdout.write(statusLine("Linked:", `incomplete → ${VAULT_INIT}`));
-            process.stdout.write(statusLine("Folder:", linkedRoot));
-            process.stdout.write(statusLine("Config:", repoConfigPath(linkedRoot)));
-            process.stdout.write(statusLine("Id:", repo.projectId));
-            await writeGitLine(gitRoot);
-            return 0;
+            writeTextOutput(status);
         }
-        process.stdout.write(statusLine("Linked:", "yes"));
-        process.stdout.write(statusLine("Folder:", linkedRoot));
-        process.stdout.write(statusLine("Config:", repoConfigPath(linkedRoot)));
-        process.stdout.write(statusLine("Id:", repo.projectId));
-        process.stdout.write(statusLine("Notes:", resolveNotesDir(home, repo)));
-        process.stdout.write(statusLine("Logs:", resolveLogsDir(home, repo)));
-        process.stdout.write(statusLine("Plans:", resolvePlansDir(home, repo)));
-        await writeGitLine(gitRoot);
         return 0;
     });
 }