@groundtrack/hooks 0.1.7 → 0.1.9

package/dist/setup/agents.js

@@ -0,0 +1,160 @@
+import { AGENTS, AGENT_IDS, isAgent, resolveAgent } from "../agents.js";
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { at, object, readJson, readToml } from "./config.js";
+import { readFile } from "./files.js";
+export const MCP_URL = "https://app.groundtrack.dev/api/mcp";
+export function environment(options = {}) {
+    let repoDir = resolve(options.repoDir ?? process.cwd());
+    if (!options.repoDir) {
+        try {
+            repoDir = execFileSync("git", ["-C", repoDir, "rev-parse", "--show-toplevel"], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 2_000,
+            }).trim();
+        }
+        catch {
+            /* A non-Git project can still use Groundtrack. */
+        }
+    }
+    return {
+        repoDir: realpathSync(repoDir),
+        homeDir: realpathSync(resolve(options.homeDir ?? homedir())),
+        env: options.env ?? process.env,
+        platform: options.platform ?? process.platform,
+    };
+}
+export function agentId(value) {
+    const agent = resolveAgent(value);
+    if (!agent)
+        throw new Error(`Unknown agent: ${value}. Choose ${AGENT_IDS.join(", ")}.`);
+    return agent.id;
+}
+export function executable(name, context) {
+    for (const dir of (context.env.PATH ?? "")
+        .split(context.platform === "win32" ? ";" : delimiter)
+        .filter(Boolean)) {
+        const suffixes = context.platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+        for (const suffix of suffixes) {
+            const path = join(dir, name + suffix);
+            try {
+                accessSync(path, constants.X_OK);
+                return path;
+            }
+            catch {
+                /* Continue through PATH. */
+            }
+        }
+    }
+    return null;
+}
+export function stateDir(context) {
+    return join(context.env.XDG_CONFIG_HOME || join(context.homeDir, ".config"), "groundtrack");
+}
+function firstExisting(paths) {
+    return paths.find((path) => existsSync(path)) ?? paths[0];
+}
+export function configPaths(agent, context) {
+    const { repoDir, homeDir, env } = context;
+    switch (agent) {
+        case "claude": {
+            const dir = env.CLAUDE_CONFIG_DIR || join(homeDir, ".claude");
+            return {
+                project: join(repoDir, ".mcp.json"),
+                user: env.CLAUDE_CONFIG_DIR ? join(dir, ".claude.json") : join(homeDir, ".claude.json"),
+                presence: [dir, join(repoDir, ".claude")],
+            };
+        }
+        case "codex": {
+            const dir = env.CODEX_HOME || join(homeDir, ".codex");
+            return {
+                project: join(repoDir, ".codex/config.toml"),
+                user: join(dir, "config.toml"),
+                presence: [
+                    dir,
+                    join(repoDir, ".codex"),
+                    ...(context.platform === "darwin"
+                        ? ["/Applications/Codex.app", join(homeDir, "Applications/Codex.app")]
+                        : []),
+                ],
+            };
+        }
+        case "cursor":
+            return {
+                project: join(repoDir, ".cursor/mcp.json"),
+                user: join(homeDir, ".cursor/mcp.json"),
+                presence: [
+                    join(homeDir, ".cursor"),
+                    join(repoDir, ".cursor"),
+                    ...(context.platform === "darwin"
+                        ? ["/Applications/Cursor.app", join(homeDir, "Applications/Cursor.app")]
+                        : []),
+                ],
+            };
+        case "opencode": {
+            const dir = join(env.XDG_CONFIG_HOME || join(homeDir, ".config"), "opencode");
+            return {
+                project: firstExisting([
+                    "opencode.jsonc",
+                    "opencode.json",
+                    ".opencode/opencode.jsonc",
+                    ".opencode/opencode.json",
+                ].map((path) => join(repoDir, path))),
+                user: env.OPENCODE_CONFIG ||
+                    firstExisting([join(dir, "opencode.jsonc"), join(dir, "opencode.json")]),
+                presence: [dir, join(repoDir, ".opencode")],
+            };
+        }
+    }
+}
+export function serverPath(agent, config) {
+    if (agent === "codex")
+        return ["mcp_servers"];
+    if (agent !== "opencode")
+        return ["mcpServers"];
+    const native = at(config, ["mcp", "servers"]);
+    return native && typeof native === "object" && !("type" in native) ? ["mcp", "servers"] : ["mcp"];
+}
+export function readConfig(agent, text) {
+    return agent === "codex" ? readToml(text) : readJson(text);
+}
+export function serverMap(agent, config) {
+    return object(at(config, serverPath(agent, config)) ?? {}, "MCP servers");
+}
+export function isGroundtrack(alias, value, url) {
+    return (alias.toLowerCase().includes("groundtrack") ||
+        (typeof value === "object" && value !== null && "url" in value && value.url === url));
+}
+export function discoverAgents(context, url = MCP_URL) {
+    return AGENTS.map((agent) => {
+        const paths = configPaths(agent.id, context);
+        const detected = [...paths.presence, paths.project, paths.user].some((path) => existsSync(path)) ||
+            Boolean(executable(agent.id, context));
+        let configured = false;
+        let issue = null;
+        try {
+            for (const path of [paths.project, paths.user]) {
+                const text = readFile(path);
+                if (text !== null &&
+                    Object.entries(serverMap(agent.id, readConfig(agent.id, text))).some(([alias, value]) => isGroundtrack(alias, value, url)))
+                    configured = true;
+            }
+        }
+        catch (error) {
+            issue = error instanceof Error ? error.message : "Configuration could not be read.";
+        }
+        return { ...agent, detected, configured, issue };
+    });
+}
+export function savedAgents(context) {
+    const text = readFile(join(stateDir(context), "setup.json"));
+    if (text === null)
+        return null;
+    const value = readJson(text);
+    if (value.version !== 1 || !Array.isArray(value.agents))
+        throw new Error("Groundtrack's saved selection is invalid. Choose agents with --agent to replace it.");
+    return [...new Set(value.agents.filter(isAgent))];
+}

package/dist/setup/cli.d.ts

@@ -0,0 +1,16 @@
+import { type Agent } from "../agents.js";
+export declare const USAGE: string;
+export type Arguments = {
+    command: "setup" | "status" | "version" | "help";
+    agents: Agent[];
+    allDetected: boolean;
+    yes: boolean;
+    json: boolean;
+    dryRun: boolean;
+    connect: boolean;
+    repoDir?: string;
+    homeDir?: string;
+    url: string;
+};
+export declare function parseArguments(input: string[]): Arguments;
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/setup/cli.js

@@ -0,0 +1,332 @@
+import { connectAgents, connectionPrompt, formatNextSteps, prepareConnections, } from "./connections.js";
+import { AGENT_IDS, requiresHookRuntime } from "../agents.js";
+import { spawn, spawnSync } from "node:child_process";
+import { basename, join } from "node:path";
+import * as prompts from "@clack/prompts";
+import { compareVersions } from "../doctor.js";
+import { packageVersion } from "../version.js";
+import { MCP_URL, agentId, discoverAgents, environment, executable, savedAgents, stateDir, } from "./agents.js";
+import { applyChanges } from "./files.js";
+import { buildSetupPlan, planSummary, selectionChange } from "./plan.js";
+export const USAGE = `Groundtrack — shared memory in your coding agents
+
+Usage:
+  groundtrack setup                         Choose agents for this project
+  groundtrack setup --agent codex           Add Codex; keep existing setup
+  groundtrack setup --agent claude --agent cursor --yes
+  groundtrack setup --all-detected --yes     Configure detected agents
+  groundtrack status                       Check selected agents
+  groundtrack doctor [--fix]                Check or repair using the same flow
+  groundtrack import [options]              Import local coding-agent sessions
+  groundtrack version
+
+Options:
+  --agent, --client NAME   ${AGENT_IDS.join(", ")} (repeatable)
+  --all-detected          Explicitly select agents detected on this machine
+  --repo PATH            Project directory (default: current directory)
+  --scope project        Configure this project; other scopes are not supported
+  --url URL              Groundtrack MCP endpoint (default: hosted Groundtrack)
+  --yes, -y              Apply the selected setup without another prompt
+  --dry-run              Preview files and next steps without changing anything
+  --connect              Start supported agents' sign-in flows in this terminal
+  --json                 Machine-readable status; explicit --yes required to apply
+  --help, -h             Show help
+`;
+export function parseArguments(input) {
+    const argv = [...input];
+    const result = {
+        command: "status",
+        agents: [],
+        allDetected: false,
+        yes: false,
+        json: false,
+        dryRun: false,
+        connect: false,
+        url: MCP_URL,
+    };
+    if (argv.includes("--help") || argv.includes("-h"))
+        return { ...result, command: "help" };
+    let command = argv[0]?.startsWith("-") ? "doctor" : (argv.shift() ?? "doctor");
+    if (argv.includes("--version"))
+        command = "version";
+    if (!["setup", "status", "doctor", "version"].includes(command))
+        throw new Error(`Unknown command: ${command}. Run groundtrack --help.`);
+    result.command = command === "doctor" ? "status" : command;
+    const take = (index, flag) => {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-"))
+            throw new Error(`${flag} requires a value.`);
+        return value;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--agent" || arg === "--client")
+            result.agents.push(agentId(take(i++, arg)));
+        else if (arg === "--repo")
+            result.repoDir = take(i++, arg);
+        else if (arg === "--home")
+            result.homeDir = take(i++, arg);
+        else if (arg === "--url")
+            result.url = take(i++, arg);
+        else if (arg === "--scope") {
+            if (take(i++, arg) !== "project")
+                throw new Error("Setup currently supports --scope project. Choose agents independently of project scope.");
+        }
+        else if (arg === "--yes" || arg === "-y")
+            result.yes = true;
+        else if (arg === "--json")
+            result.json = true;
+        else if (arg === "--dry-run")
+            result.dryRun = true;
+        else if (arg === "--connect")
+            result.connect = true;
+        else if (arg === "--all-detected")
+            result.allDetected = true;
+        else if (arg === "--fix" && command === "doctor")
+            result.command = "setup";
+        else if (arg !== "--version")
+            throw new Error(`Unknown option: ${arg}. Run groundtrack --help.`);
+    }
+    result.agents = [...new Set(result.agents)];
+    if (result.allDetected && result.agents.length)
+        throw new Error("Choose --agent or --all-detected, not both.");
+    if (result.connect && (result.command !== "setup" || result.json || result.dryRun))
+        throw new Error("Use --connect with interactive setup, without --json or --dry-run.");
+    const url = new URL(result.url);
+    if ((url.protocol !== "https:" &&
+        !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new Error("Use an HTTPS MCP URL (or local HTTP), without credentials, query parameters, or fragments.");
+    }
+    result.url = url.href.replace(/\/$/, "");
+    return result;
+}
+function runtimeVersion(context) {
+    const binary = executable("groundtrack-hook", context);
+    if (!binary)
+        return null;
+    const result = spawnSync(binary, ["version", "--json"], {
+        env: context.env,
+        encoding: "utf8",
+        timeout: 2_000,
+        windowsHide: true,
+        shell: context.platform === "win32",
+    });
+    try {
+        const value = JSON.parse(result.stdout);
+        return result.status === 0 &&
+            value &&
+            typeof value === "object" &&
+            "version" in value &&
+            typeof value.version === "string"
+            ? value.version
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function run(binary, args, context, inherit = false) {
+    return new Promise((resolve) => {
+        const child = spawn(binary, args, {
+            cwd: context.repoDir,
+            env: context.env,
+            stdio: inherit ? "inherit" : "ignore",
+            windowsHide: true,
+            shell: context.platform === "win32",
+            timeout: inherit ? undefined : 120_000,
+        });
+        child.once("error", () => resolve(false));
+        child.once("close", (code) => resolve(code === 0));
+    });
+}
+function printPlan(plan, context, runtimeReady) {
+    process.stdout.write(`\nGroundtrack · ${basename(context.repoDir)}\nProject: ${context.repoDir}\n\n`);
+    for (const agent of planSummary(plan, context)) {
+        process.stdout.write(`  ${agent.status === "blocked" ? "!" : agent.status === "configured" ? "✓" : "+"} ${agent.name}: ${agent.status === "configured" ? "already configured" : agent.status === "blocked" ? agent.issue : "ready to set up"}\n`);
+        for (const path of agent.files)
+            process.stdout.write(`      ${path}\n`);
+    }
+    if (plan.shared.length)
+        process.stdout.write("  + Update shared AGENTS.md instructions\n");
+    if (!runtimeReady)
+        process.stdout.write("  + Install the shared Groundtrack hook runtime once\n");
+    process.stdout.write("\nScope: this project. Existing agent connections are kept.\n");
+}
+export async function runCli(argv) {
+    const args = parseArguments(argv);
+    if (args.command === "help") {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (args.command === "version") {
+        process.stdout.write(args.json ? `${JSON.stringify({ version: packageVersion() })}\n` : `${packageVersion()}\n`);
+        return;
+    }
+    const context = environment({ repoDir: args.repoDir, homeDir: args.homeDir });
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !args.json);
+    if (args.connect && !interactive)
+        throw new Error("--connect needs an interactive terminal. Run setup there, or use the per-agent sign-in instructions after setup.");
+    const discovered = discoverAgents(context, args.url);
+    let saved = null;
+    try {
+        saved = savedAgents(context);
+    }
+    catch (error) {
+        if (!args.agents.length && !args.allDetected)
+            throw error;
+    }
+    let targets = args.agents.length
+        ? args.agents
+        : args.allDetected
+            ? discovered.filter((agent) => agent.detected).map((agent) => agent.id)
+            : (saved ?? []);
+    let picked = false;
+    if (args.command === "setup" && !args.agents.length && !args.allDetected && interactive) {
+        prompts.intro(`Set up Groundtrack · ${basename(context.repoDir)}`);
+        const selection = await prompts.multiselect({
+            message: "Which coding agents do you use?",
+            options: discovered.map((agent) => ({
+                value: agent.id,
+                label: agent.name,
+                hint: agent.issue
+                    ? "configuration needs attention"
+                    : agent.configured
+                        ? "already configured · keep"
+                        : agent.detected
+                            ? "detected"
+                            : "not detected · can still set up",
+            })),
+            initialValues: saved ?? discovered.filter((agent) => agent.detected).map((agent) => agent.id),
+            required: false,
+        });
+        if (prompts.isCancel(selection) || selection.length === 0) {
+            prompts.cancel("No agents selected. Nothing changed.");
+            return;
+        }
+        targets = selection;
+        picked = true;
+    }
+    if (args.command === "status" && !targets.length)
+        targets = discovered
+            .filter((agent) => agent.detected || agent.configured)
+            .map((agent) => agent.id);
+    if (!targets.length) {
+        if (args.command === "setup")
+            throw new Error("Choose your agents: groundtrack setup --agent claude --agent codex --agent cursor --yes. In an interactive terminal, run groundtrack setup to choose from a list. No files changed.");
+        process.stdout.write(args.json
+            ? `${JSON.stringify({ agents: [], detected: discovered, runtime: null })}\n`
+            : "Groundtrack is not configured here. Run groundtrack setup to choose your agents.\n");
+        return;
+    }
+    const plan = buildSetupPlan(context, targets, args.url);
+    const needsRuntime = targets.some(requiresHookRuntime);
+    const installedVersion = needsRuntime ? runtimeVersion(context) : null;
+    const runtimeReady = !needsRuntime ||
+        (installedVersion !== null && compareVersions(installedVersion, packageVersion()) >= 0);
+    if (args.command === "status" || args.dryRun) {
+        if (args.json)
+            process.stdout.write(`${JSON.stringify({ agents: planSummary(plan, context), detected: discovered, runtimeReady, sharedIssue: plan.sharedIssue, sharedFiles: plan.shared.map((change) => change.path), dryRun: args.dryRun }, null, 2)}\n`);
+        else {
+            printPlan(plan, context, runtimeReady);
+            const other = discovered.filter((agent) => agent.detected && !targets.includes(agent.id));
+            if (other.length)
+                process.stdout.write(`\nAlso detected: ${other.map((agent) => agent.name).join(", ")}. Add them with groundtrack setup.\n`);
+            process.stdout.write("\nLive connection: not checked from this terminal.\nRun groundtrack setup to add or repair agents.\n");
+        }
+        process.exitCode =
+            plan.sharedIssue || plan.agents.some((agent) => agent.issue)
+                ? 1
+                : args.dryRun
+                    ? 0
+                    : !runtimeReady || plan.shared.length || plan.agents.some((agent) => agent.changes.length)
+                        ? 1
+                        : 0;
+        return;
+    }
+    if (!args.yes && !interactive)
+        throw new Error("Setup needs confirmation. Use --yes with your selected --agent values, or run groundtrack setup in an interactive terminal. No files changed.");
+    if (!args.json)
+        printPlan(plan, context, runtimeReady);
+    const ready = plan.agents.filter((agent) => !agent.issue);
+    if (plan.sharedIssue || !ready.length) {
+        if (args.json)
+            process.stdout.write(`${JSON.stringify({ agents: planSummary(plan, context), sharedIssue: plan.sharedIssue, applied: false })}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!args.yes &&
+        (!runtimeReady || plan.shared.length || ready.some((agent) => agent.changes.length))) {
+        const approved = await prompts.confirm({
+            message: `Configure ${ready.length} ${ready.length === 1 ? "agent" : "agents"} for this project?`,
+            initialValue: true,
+        });
+        if (prompts.isCancel(approved) || !approved) {
+            prompts.cancel("Nothing changed.");
+            return;
+        }
+    }
+    if (!runtimeReady && ready.some((agent) => requiresHookRuntime(agent.agent))) {
+        if (context.env.GROUNDTRACK_DOCTOR_SKIP_INSTALL === "1")
+            throw new Error("The Groundtrack hook runtime is missing or outdated. Install @groundtrack/hooks before applying this setup.");
+        const spinner = interactive ? prompts.spinner() : null;
+        spinner?.start("Installing the shared hook runtime");
+        const installed = await run("npm", ["install", "--global", `@groundtrack/hooks@${packageVersion()}`], context);
+        spinner?.stop(installed ? "Hook runtime installed" : "Hook runtime installation failed");
+        const version = runtimeVersion(context);
+        if (!installed || !version || compareVersions(version, packageVersion()) < 0)
+            throw new Error("The hook runtime could not be installed or is not on PATH. Run npm install --global @groundtrack/hooks, ensure groundtrack-hook is on PATH, then retry. Agent configuration was not changed.");
+    }
+    const preferences = picked ? targets : [...new Set([...(saved ?? []), ...targets])];
+    const changes = [
+        ...plan.shared,
+        ...ready.flatMap((agent) => agent.changes),
+        ...selectionChange(context, preferences),
+    ];
+    const backupDir = applyChanges(changes, join(stateDir(context), "backups"));
+    const after = buildSetupPlan(context, targets, args.url);
+    const localReady = !after.sharedIssue &&
+        !after.shared.length &&
+        after.agents.every((agent) => !agent.issue && !agent.changes.length);
+    let signInFailed = false;
+    if (args.json) {
+        process.stdout.write(`${JSON.stringify({ agents: planSummary(after, context), localReady, applied: true, changedFiles: changes.map((change) => change.path), backupDir }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`\n${ready.length} ${ready.length === 1 ? "agent configured" : "agents configured"}. ${changes.length ? `${changes.length} files updated.` : "Everything is already current."}\n`);
+        let connections = [];
+        if (interactive) {
+            const spinner = prompts.spinner();
+            spinner.start("Checking sign-in requirements");
+            connections = await prepareConnections(ready, context, args.url);
+            spinner.stop("Sign-in requirements checked");
+            signInFailed = connections.some((connection) => connection.status === "failed");
+            for (const connection of connections.filter((item) => item.status === "needs_project_approval")) {
+                const agent = ready.find((item) => item.agent === connection.agent);
+                process.stdout.write(`${agent.name}: approve this project in the agent before signing in.\n`);
+            }
+        }
+        const eligible = connections.filter((connection) => connection.status === "ready" && (args.connect || connection.offer));
+        let shouldConnect = args.connect;
+        if (interactive && !args.yes && eligible.length && !shouldConnect) {
+            const answer = await prompts.confirm({
+                message: connectionPrompt(ready.filter((agent) => eligible.some((item) => item.agent === agent.agent))),
+                initialValue: true,
+            });
+            shouldConnect = !prompts.isCancel(answer) && answer;
+        }
+        if (shouldConnect) {
+            const results = await connectAgents(eligible, context, undefined, (id) => {
+                const name = ready.find((agent) => agent.agent === id).name;
+                process.stdout.write(`\nConnecting Groundtrack to ${name}…\n`);
+            });
+            signInFailed ||= results.some((result) => result.status === "failed");
+            connections = connections.map((connection) => results.find((result) => result.agent === connection.agent) ?? connection);
+        }
+        process.stdout.write(formatNextSteps(ready, context, connections));
+    }
+    process.exitCode = localReady && !signInFailed ? 0 : 1;
+}

package/dist/setup/config.d.ts

@@ -0,0 +1,9 @@
+export type JsonObject = Record<string, unknown>;
+export type ConfigPath = Array<string | number>;
+export declare function object(value: unknown, label: string): JsonObject;
+export declare function at(value: unknown, path: ConfigPath): unknown;
+export declare function readJson(text: string): JsonObject;
+export declare function setJson(text: string, path: ConfigPath, value: unknown): string;
+export declare function readToml(text: string): JsonObject;
+/** Edit only the requested value; retain comments, quoting and unrelated tables. */
+export declare function setToml(text: string, path: ConfigPath, value: unknown): string;

package/dist/setup/config.js

@@ -0,0 +1,143 @@
+import { applyEdits, modify, parse, parseTree, printParseErrorCode, } from "jsonc-parser";
+import { getStaticTOMLValue, parseTOML, traverseNodes } from "toml-eslint-parser";
+export function object(value, label) {
+    if (value == null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object. Existing configuration was left unchanged.`);
+    }
+    return value;
+}
+export function at(value, path) {
+    return path.reduce((current, key) => {
+        if (!current || typeof current !== "object")
+            return undefined;
+        return current[key];
+    }, value);
+}
+function checkDuplicateKeys(node) {
+    if (node?.type === "object") {
+        const keys = node.children?.map((child) => child.children?.[0]?.value) ?? [];
+        if (new Set(keys).size !== keys.length) {
+            throw new Error("Configuration contains duplicate keys. Resolve them before running setup.");
+        }
+    }
+    for (const child of node?.children ?? [])
+        checkDuplicateKeys(child);
+}
+export function readJson(text) {
+    const errors = [];
+    const value = parse(text || "{}", errors, { allowTrailingComma: true });
+    if (value === undefined &&
+        errors.every((error) => printParseErrorCode(error.error) === "ValueExpected"))
+        return {};
+    if (errors.length)
+        throw new Error(`Invalid JSON at offset ${errors[0].offset}. Fix the file and retry.`);
+    checkDuplicateKeys(parseTree(text || "{}"));
+    return object(value, "Configuration");
+}
+export function setJson(text, path, value) {
+    readJson(text);
+    const source = !parseTree(text) ? `${text}${text && !text.endsWith("\n") ? "\n" : ""}{}\n` : text;
+    const indent = /\n([\t ]+)\S/.exec(source)?.[1];
+    const updated = applyEdits(source, modify(source, path, value, {
+        formattingOptions: {
+            insertSpaces: !indent?.includes("\t"),
+            tabSize: indent?.length ?? 2,
+            eol: source.includes("\r\n") ? "\r\n" : "\n",
+        },
+    }));
+    readJson(updated);
+    return updated;
+}
+function tomlAst(text) {
+    try {
+        return parseTOML(text);
+    }
+    catch {
+        // Parser diagnostics can contain credentials from the offending line.
+        throw new Error("Invalid TOML. Fix the file before running setup; its contents were not changed.");
+    }
+}
+export function readToml(text) {
+    return object(getStaticTOMLValue(tomlAst(text)), "Configuration");
+}
+function nodePath(node) {
+    if (node.type === "TOMLTable")
+        return node.resolvedKey;
+    if (node.type === "Program" || node.type === "TOMLTopLevelTable")
+        return [];
+    if (node.type === "TOMLKeyValue")
+        return [...nodePath(node.parent), ...getStaticTOMLValue(node.key)];
+    if (node.parent?.type === "TOMLArray") {
+        return [...nodePath(node.parent), node.parent.elements.indexOf(node)];
+    }
+    return node.parent ? nodePath(node.parent) : [];
+}
+function renderToml(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(renderToml).join(", ")}]`;
+    return `{ ${Object.entries(object(value, "TOML value"))
+        .map(([key, item]) => `${JSON.stringify(key)} = ${renderToml(item)}`)
+        .join(", ")} }`;
+}
+/** Edit only the requested value; retain comments, quoting and unrelated tables. */
+export function setToml(text, path, value) {
+    const ast = tomlAst(text);
+    let match;
+    const containers = [];
+    traverseNodes(ast, {
+        enterNode(node) {
+            const resolved = nodePath(node);
+            if (node.type === "TOMLKeyValue" && JSON.stringify(resolved) === JSON.stringify(path))
+                match = node;
+            if (["TOMLTable", "TOMLInlineTable", "TOMLTopLevelTable"].includes(node.type) &&
+                resolved.length < path.length &&
+                resolved.every((part, index) => part === path[index]) &&
+                path.slice(resolved.length).every((part) => typeof part === "string")) {
+                containers.push(node);
+            }
+        },
+        leaveNode() { },
+    });
+    let updated;
+    if (match) {
+        updated =
+            text.slice(0, match.value.range[0]) + renderToml(value) + text.slice(match.value.range[1]);
+    }
+    else {
+        const container = containers.sort((a, b) => nodePath(b).length - nodePath(a).length)[0];
+        if (!container)
+            throw new Error("This TOML layout cannot be updated automatically. Existing configuration was left unchanged.");
+        const key = path
+            .slice(nodePath(container).length)
+            .map((part) => JSON.stringify(part))
+            .join(".");
+        const entry = `${key} = ${renderToml(value)}`;
+        if (container.type === "TOMLInlineTable") {
+            const offset = container.range[1] - 1;
+            updated =
+                text.slice(0, offset).trimEnd() +
+                    `${container.body.length ? ", " : " "}${entry} ` +
+                    text.slice(offset);
+        }
+        else {
+            const firstTable = container.type === "TOMLTopLevelTable"
+                ? container.body.find((node) => node.type === "TOMLTable")
+                : undefined;
+            const position = firstTable?.range[0] ?? container.range[1];
+            // Insert after the complete line, including a possible trailing comment.
+            const newline = firstTable ? position : text.indexOf("\n", position);
+            const offset = newline < 0 ? text.length : firstTable ? position : newline + 1;
+            const eol = text.includes("\r\n") ? "\r\n" : "\n";
+            updated =
+                text.slice(0, offset) +
+                    (offset && text[offset - 1] !== "\n" ? eol : "") +
+                    entry +
+                    eol +
+                    text.slice(offset);
+        }
+    }
+    readToml(updated);
+    return updated;
+}