@groundtrack/hooks 0.1.7 → 0.1.8

package/dist/setup/connections.d.ts

@@ -0,0 +1,26 @@
+import type { Agent } from "../agents.js";
+import { type SetupEnvironment } from "./agents.js";
+import { type AgentPlan } from "./plan.js";
+export type CommandResult = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+};
+export type ClientCommand = {
+    binary: string;
+    args: string[];
+};
+export type ClientRunner = (command: ClientCommand, context: SetupEnvironment, interactive: boolean) => Promise<CommandResult>;
+export type Connection = {
+    agent: Agent;
+    status: "ready" | "authenticated" | "needs_project_approval" | "manual" | "failed";
+    command?: ClientCommand;
+    offer: boolean;
+    detail?: string;
+};
+/** Probe output can include headers. Keep it bounded and private; never persist or print it. */
+export declare const runClient: ClientRunner;
+export declare function prepareConnections(agents: AgentPlan[], context: SetupEnvironment, url: string, runner?: ClientRunner): Promise<Connection[]>;
+export declare function connectionPrompt(agents: AgentPlan[]): string;
+export declare function connectAgents(connections: Connection[], context: SetupEnvironment, runner?: ClientRunner, onStart?: (agent: Agent) => void): Promise<Connection[]>;
+export declare function formatNextSteps(agents: AgentPlan[], context: SetupEnvironment, connections?: Connection[]): string;

package/dist/setup/connections.js

@@ -0,0 +1,210 @@
+import { spawn } from "node:child_process";
+import { stripVTControlCharacters } from "node:util";
+import { configPaths, executable, readConfig, serverMap } from "./agents.js";
+import { readFile } from "./files.js";
+import { activationSteps } from "./plan.js";
+/** Probe output can include headers. Keep it bounded and private; never persist or print it. */
+export const runClient = (command, context, interactive) => new Promise((resolve) => {
+    const child = spawn(command.binary, command.args, {
+        cwd: context.repoDir,
+        env: context.env,
+        stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
+        timeout: interactive ? undefined : 5_000,
+        windowsHide: true,
+        shell: context.platform === "win32" && /\.(?:cmd|bat)$/i.test(command.binary),
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+        stdout = (stdout + chunk.toString()).slice(-65_536);
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr = (stderr + chunk.toString()).slice(-65_536);
+    });
+    child.once("error", () => resolve({ exitCode: null, stdout: "", stderr: "" }));
+    child.once("close", (exitCode) => resolve({ exitCode, stdout, stderr }));
+});
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function codexServer(result) {
+    if (result.exitCode !== 0)
+        return undefined;
+    try {
+        return record(JSON.parse(result.stdout));
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasAuthOptions(server) {
+    return [
+        "oauth",
+        "auth",
+        "bearer_token_env_var",
+        "http_headers",
+        "env_http_headers",
+        "http_headers_helper",
+    ].some((key) => server[key] != null);
+}
+async function prepareConnection(agent, context, url, runner) {
+    const binary = executable(agent.agent, context);
+    const base = { agent: agent.agent, offer: false };
+    if (agent.agent === "cursor" || !binary)
+        return { ...base, status: "manual" };
+    const command = {
+        binary,
+        args: agent.agent === "opencode" ? ["mcp", "auth", agent.alias] : ["mcp", "login", agent.alias],
+    };
+    if (agent.agent === "opencode") {
+        const probe = await runner({ binary, args: ["mcp", "auth", "list"] }, context, false);
+        const alias = agent.alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const output = stripVTControlCharacters(probe.stdout);
+        if (probe.exitCode === 0 &&
+            new RegExp(`(?:^|\\s)${alias}\\s+authenticated\\s*$`, "im").test(output))
+            return { ...base, status: "authenticated" };
+        return {
+            ...base,
+            status: "ready",
+            command,
+            offer: !agent.existingConnection ||
+                new RegExp(`(?:^|\\s)${alias}\\s+(?:not authenticated|expired)`, "i").test(output),
+        };
+    }
+    if (agent.agent === "claude") {
+        const probe = await runner({ binary, args: ["mcp", "get", agent.alias] }, context, false);
+        const output = stripVTControlCharacters(`${probe.stdout}\n${probe.stderr}`);
+        if (/pending approval|awaiting approval/i.test(output))
+            return { ...base, status: "needs_project_approval" };
+        if (/status:\s*[^a-z0-9\n]*connected\b/i.test(output) && probe.exitCode === 0)
+            return { ...base, status: "authenticated" };
+        if (/status:[^\n]*disabled/i.test(output))
+            return {
+                ...base,
+                status: "failed",
+                detail: "Re-enable Groundtrack in Claude Code's /mcp panel.",
+            };
+        if (probe.exitCode !== 0)
+            return {
+                ...base,
+                status: "manual",
+                detail: "Open this project in Claude Code and use /mcp to approve and connect Groundtrack.",
+            };
+        return {
+            ...base,
+            status: "ready",
+            command,
+            offer: !agent.existingConnection || /needs authentication|not authenticated/i.test(output),
+        };
+    }
+    if (agent.agent === "codex") {
+        const probe = await runner({ binary, args: ["mcp", "get", agent.alias, "--json"] }, context, false);
+        let server = codexServer(probe);
+        if (!server && /no mcp server named/i.test(probe.stderr + probe.stdout)) {
+            // Untrusted project config is intentionally invisible to Codex. Supply only the
+            // selected endpoint for this login invocation; never grant project/hook trust.
+            const path = configPaths("codex", context).project;
+            const configured = record(serverMap("codex", readConfig("codex", readFile(path) ?? ""))[agent.alias]);
+            if (!configured || configured.url !== url || hasAuthOptions(configured))
+                return { ...base, status: "needs_project_approval" };
+            // Override the map so aliases containing dots remain literal TOML keys.
+            const override = `mcp_servers={${JSON.stringify(agent.alias)}={url=${JSON.stringify(url)}}}`;
+            const prefix = ["-c", override];
+            server = codexServer(await runner({ binary, args: [...prefix, "mcp", "get", agent.alias, "--json"] }, context, false));
+            command.args = [...prefix, "mcp", "login", agent.alias];
+        }
+        if (!server)
+            return {
+                ...base,
+                status: "manual",
+                detail: "Open and trust this project in Codex, then connect Groundtrack in /mcp or Settings → MCP servers.",
+            };
+        const transport = record(server.transport);
+        if (server.enabled === false || transport?.url !== url || transport.type !== "streamable_http")
+            return {
+                ...base,
+                status: "failed",
+                detail: "Codex is loading a disabled or different Groundtrack server. Resolve it in Codex's MCP settings before signing in.",
+            };
+        if (hasAuthOptions(transport))
+            return {
+                ...base,
+                status: "manual",
+                detail: "Codex uses the credentials configured for this server. Verify its connection in Codex.",
+            };
+    }
+    return { ...base, status: "ready", command, offer: !agent.existingConnection };
+}
+export async function prepareConnections(agents, context, url, runner = runClient) {
+    return Promise.all(agents.map(async (agent) => {
+        try {
+            return await prepareConnection(agent, context, url, runner);
+        }
+        catch {
+            return {
+                agent: agent.agent,
+                status: "manual",
+                offer: false,
+                detail: "Could not check this agent's sign-in requirements. Finish connecting in the agent.",
+            };
+        }
+    }));
+}
+export function connectionPrompt(agents) {
+    const names = new Intl.ListFormat("en", { style: "long", type: "conjunction" }).format(agents.map((agent) => agent.name));
+    return `Connect Groundtrack to ${names} now?`;
+}
+export async function connectAgents(connections, context, runner = runClient, onStart = () => { }) {
+    const results = [];
+    for (const connection of connections) {
+        if (connection.status !== "ready" || !connection.command) {
+            results.push(connection);
+            continue;
+        }
+        onStart(connection.agent);
+        let result;
+        try {
+            result = await runner(connection.command, context, true);
+        }
+        catch {
+            result = { exitCode: null, stdout: "", stderr: "" };
+        }
+        results.push({
+            ...connection,
+            offer: false,
+            status: result.exitCode === 0 ? "authenticated" : "failed",
+            detail: result.exitCode === 0
+                ? undefined
+                : "Sign-in did not complete. Your configuration is saved; finish connecting in the agent.",
+        });
+    }
+    return results;
+}
+export function formatNextSteps(agents, context, connections = []) {
+    const lines = [
+        "",
+        "Connection status and next steps",
+        `Project: ${context.repoDir}`,
+        "Run any remaining commands from this project folder.",
+    ];
+    for (const agent of agents) {
+        const connection = connections.find((item) => item.agent === agent.agent);
+        const authenticated = connection?.status === "authenticated";
+        const label = authenticated
+            ? "signed in to Groundtrack"
+            : connection?.status === "needs_project_approval"
+                ? "project approval needed"
+                : connection?.status === "failed"
+                    ? "sign-in needs attention"
+                    : "configured · finish connecting in the agent";
+        lines.push("", `${agent.name} — ${label}`);
+        if (connection?.detail)
+            lines.push(`  ${connection.detail}`);
+        for (const step of activationSteps(agent.agent, agent.alias, agent.existingConnection, authenticated))
+            lines.push(`  ${step}`);
+    }
+    lines.push("", "Files are configured. Live connection and hook activation must be verified in each agent.", "Add another agent anytime: groundtrack setup", "");
+    return lines.join("\n");
+}

package/dist/setup/files.d.ts

@@ -0,0 +1,18 @@
+export type FileChange = {
+    path: string;
+    before: string | null;
+    after: string;
+    mode: number;
+};
+/** Refuse links at every level, including dangling links and linked config directories. */
+export declare function checkPath(path: string): void;
+export declare function readFile(path: string): string | null;
+export declare class FilePlan {
+    private files;
+    read(path: string): string | null;
+    set(path: string, after: string): void;
+    get changes(): FileChange[];
+}
+export declare function writeAtomic(path: string, text: string, mode: number): void;
+/** Back up before applying; roll back our writes on failure without overwriting concurrent edits. */
+export declare function applyChanges(changes: FileChange[], backupRoot: string, write?: typeof writeAtomic): string | null;

package/dist/setup/files.js

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** Refuse links at every level, including dangling links and linked config directories. */
+export function checkPath(path) {
+    const absolute = resolve(path);
+    const parent = dirname(absolute);
+    if (parent !== absolute)
+        checkPath(parent);
+    try {
+        if (lstatSync(absolute).isSymbolicLink())
+            throw new Error(`Symbolic link at ${absolute}. Update its target explicitly before setup.`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+export function readFile(path) {
+    checkPath(path);
+    try {
+        if (!lstatSync(path).isFile())
+            throw new Error(`Expected a regular file: ${path}`);
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export class FilePlan {
+    files = new Map();
+    read(path) {
+        return this.files.get(path)?.after ?? readFile(path);
+    }
+    set(path, after) {
+        const before = this.files.get(path)?.before ?? readFile(path);
+        if (before === after) {
+            this.files.delete(path);
+            return;
+        }
+        this.files.set(path, {
+            path,
+            before,
+            after,
+            mode: before === null ? 0o644 : lstatSync(path).mode & 0o777,
+        });
+    }
+    get changes() {
+        return [...this.files.values()];
+    }
+}
+export function writeAtomic(path, text, mode) {
+    checkPath(path);
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = join(dirname(path), `.groundtrack-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, text, { mode, flag: "wx" });
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/** Back up before applying; roll back our writes on failure without overwriting concurrent edits. */
+export function applyChanges(changes, backupRoot, write = writeAtomic) {
+    if (!changes.length)
+        return null;
+    for (const change of changes) {
+        if (readFile(change.path) !== change.before)
+            throw new Error(`${change.path} changed after the preview. Run setup again.`);
+    }
+    checkPath(backupRoot);
+    const backupDir = join(backupRoot, randomUUID());
+    mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(backupDir, "files.json"), JSON.stringify(changes.map(({ path, before, mode }) => ({ path, before, mode }))), { mode: 0o600, flag: "wx" });
+    const written = [];
+    try {
+        for (const change of changes) {
+            if (readFile(change.path) !== change.before)
+                throw new Error(`${change.path} changed while setup was running.`);
+            write(change.path, change.after, change.mode);
+            written.push(change);
+        }
+    }
+    catch {
+        for (const change of written.reverse()) {
+            try {
+                if (readFile(change.path) !== change.after)
+                    continue;
+                if (change.before === null)
+                    rmSync(change.path);
+                else
+                    writeAtomic(change.path, change.before, change.mode);
+            }
+            catch {
+                /* The private backup is retained if a file cannot be restored. */
+            }
+        }
+        throw new Error(`Setup could not save every file. Previous changes were rolled back where possible. Backups: ${backupDir}. Run setup again after resolving the file conflict.`);
+    }
+    return backupDir;
+}

package/dist/setup/plan.d.ts

@@ -0,0 +1,30 @@
+import { type Agent } from "../agents.js";
+import { type SetupEnvironment } from "./agents.js";
+import { type FileChange } from "./files.js";
+export type AgentPlan = {
+    agent: Agent;
+    name: string;
+    alias: string;
+    existingConnection: boolean;
+    changes: FileChange[];
+    issue: string | null;
+    activation: "unverified";
+    nextSteps: string[];
+};
+export type SetupPlan = {
+    agents: AgentPlan[];
+    shared: FileChange[];
+    sharedIssue: string | null;
+};
+export declare function activationSteps(agent: Agent, alias: string, existing: boolean, authenticated?: boolean): string[];
+export declare function buildSetupPlan(context: SetupEnvironment, agents: Agent[], url: string): SetupPlan;
+export declare function planSummary(plan: SetupPlan, context: SetupEnvironment): {
+    agent: "claude" | "codex" | "cursor" | "opencode";
+    name: string;
+    status: string;
+    issue: string | null;
+    activation: "unverified";
+    files: string[];
+    nextSteps: string[];
+}[];
+export declare function selectionChange(context: SetupEnvironment, agents: Agent[]): FileChange[];