@groundtrack/hooks 0.1.7 → 0.1.8

package/dist/setup/plan.js

@@ -0,0 +1,324 @@
+import { AGENTS } from "../agents.js";
+import { join, relative } from "node:path";
+import { AGENT_INSTRUCTION_BODY } from "../agent-instructions.js";
+import { CLAUDE_INSTRUCTION_BODY, claudeInstructionsAreCurrent, claudeUsesInlineGroundtrackInstructions, upsertManagedContent, } from "../doctor.js";
+import { configPaths, isGroundtrack, readConfig, serverMap, serverPath, stateDir, } from "./agents.js";
+import { at, object, readJson, readToml, setJson, setToml } from "./config.js";
+import { FilePlan } from "./files.js";
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function array(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array. Fix its configuration and retry.`);
+    return value;
+}
+function ownedHook(value) {
+    const command = record(value)?.command;
+    return typeof command === "string" && /(?:^|[/\\\s])groundtrack-hook(?:\s|$)/.test(command);
+}
+function matcherMatches(value, aliases) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return aliases.every((alias) => new RegExp(value).test(`mcp__${alias}__store_event`) &&
+            new RegExp(value).test(`mcp__${alias}__search_experiences`));
+    }
+    catch {
+        return false;
+    }
+}
+function matcher(aliases) {
+    return `^mcp__(?:${aliases.map((alias) => alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})__(store_event|search_experiences)$`;
+}
+function commandHook(command) {
+    return {
+        type: "command",
+        command,
+        timeout: 5,
+        statusMessage: "Adding Groundtrack session metadata",
+    };
+}
+function hasHook(config, aliases, command) {
+    return array(at(config, ["hooks", "PreToolUse"]), "PreToolUse hooks").some((entry) => {
+        const group = record(entry);
+        return (matcherMatches(group?.matcher, aliases) &&
+            array(group?.hooks, "Hook commands").some((hook) => record(hook)?.command === command && record(hook)?.type === "command"));
+    });
+}
+/** Remove only our commands from shared groups, leaving other commands and their matchers intact. */
+function upsertCommandHook(text, aliases, command) {
+    const config = readJson(text);
+    if (hasHook(config, aliases, command))
+        return text;
+    const groups = array(at(config, ["hooks", "PreToolUse"]), "PreToolUse hooks");
+    let updated = text;
+    for (let i = groups.length - 1; i >= 0; i--) {
+        const hooks = array(record(groups[i])?.hooks, "Hook commands");
+        if (!hooks.some(ownedHook))
+            continue;
+        if (hooks.every(ownedHook))
+            updated = setJson(updated, ["hooks", "PreToolUse", i], undefined);
+        else
+            for (let j = hooks.length - 1; j >= 0; j--)
+                if (ownedHook(hooks[j]))
+                    updated = setJson(updated, ["hooks", "PreToolUse", i, "hooks", j], undefined);
+    }
+    if (at(readJson(updated), ["hooks", "PreToolUse"]) === undefined)
+        updated = setJson(updated, ["hooks", "PreToolUse"], []);
+    return setJson(updated, ["hooks", "PreToolUse", -1], {
+        matcher: matcher(aliases),
+        hooks: [commandHook(command)],
+    });
+}
+function jsonFile(files, path) {
+    return readJson(files.read(path) ?? "{}");
+}
+function managedInstructions(source, desired, name) {
+    const starts = source?.match(/<!-- groundtrack:start\b/g)?.length ?? 0;
+    const ends = source?.match(/<!-- groundtrack:end -->/g)?.length ?? 0;
+    if (starts !== ends || starts > 1)
+        throw new Error(`${name} has incomplete or duplicate Groundtrack markers. Resolve them before setup.`);
+    return upsertManagedContent(source, desired, true);
+}
+function planClaude(files, context, aliases) {
+    const userPath = join(context.env.CLAUDE_CONFIG_DIR || join(context.homeDir, ".claude"), "settings.json");
+    const user = jsonFile(files, userPath);
+    const projectPath = join(context.repoDir, ".claude/settings.json");
+    const project = jsonFile(files, projectPath);
+    const local = jsonFile(files, join(context.repoDir, ".claude/settings.local.json"));
+    const connectionSettings = jsonFile(files, configPaths("claude", context).user);
+    const localConnection = record(at(connectionSettings, ["projects", context.repoDir])) ?? {};
+    if ([user, project, local, connectionSettings, localConnection].some((config) => {
+        const disabled = config.disabledMcpServers;
+        return Array.isArray(disabled) && aliases.some((alias) => disabled.includes(alias));
+    })) {
+        throw new Error("Groundtrack is disabled in Claude Code. Re-enable the server in /mcp, then run setup again.");
+    }
+    if ([user, project, local].some((config) => config.disableAllHooks === true || config.allowManagedHooksOnly === true)) {
+        throw new Error("Claude Code's settings disable project hooks. Enable them in Claude Code, then run setup again.");
+    }
+    if (!hasHook(user, aliases, "groundtrack-hook claude") &&
+        !hasHook(local, aliases, "groundtrack-hook claude")) {
+        files.set(projectPath, upsertCommandHook(files.read(projectPath) ?? "", aliases, "groundtrack-hook claude"));
+    }
+    const bridgePath = join(context.repoDir, "CLAUDE.md");
+    const bridge = files.read(bridgePath);
+    if (!claudeInstructionsAreCurrent(bridge)) {
+        files.set(bridgePath, managedInstructions(bridge, claudeUsesInlineGroundtrackInstructions(bridge)
+            ? AGENT_INSTRUCTION_BODY
+            : CLAUDE_INSTRUCTION_BODY, "CLAUDE.md"));
+    }
+}
+function planCodex(files, context, aliases) {
+    const overridePath = join(context.repoDir, "AGENTS.override.md");
+    const override = files.read(overridePath);
+    if (override !== null)
+        files.set(overridePath, managedInstructions(override, AGENT_INSTRUCTION_BODY, "AGENTS.override.md"));
+    const paths = configPaths("codex", context);
+    const project = readToml(files.read(paths.project) ?? "");
+    const user = readToml(files.read(paths.user) ?? "");
+    const hookEnabled = at(project, ["features", "hooks"]) ??
+        at(project, ["features", "codex_hooks"]) ??
+        at(user, ["features", "hooks"]) ??
+        at(user, ["features", "codex_hooks"]);
+    if (hookEnabled === false || user.allow_managed_hooks_only === true)
+        throw new Error("Codex's settings disable project hooks. Enable them in Codex, then run setup again.");
+    const userHooksPath = join(context.env.CODEX_HOME || join(context.homeDir, ".codex"), "hooks.json");
+    const hookPath = join(context.repoDir, ".codex/hooks.json");
+    if ([project, user, jsonFile(files, userHooksPath), jsonFile(files, hookPath)].some((config) => hasHook(config, aliases, "groundtrack-hook")))
+        return;
+    // Repair legacy inline Groundtrack hooks in place without serializing the TOML document.
+    const groups = array(at(project, ["hooks", "PreToolUse"]), "Codex PreToolUse hooks");
+    for (let index = 0; index < groups.length; index++) {
+        const hooks = array(record(groups[index])?.hooks, "Codex hook commands");
+        if (!hooks.some(ownedHook))
+            continue;
+        if (!hooks.every(ownedHook))
+            throw new Error("A Codex hook group mixes Groundtrack and other commands. Separate that group before repairing it.");
+        let updated = setToml(files.read(paths.project) ?? "", ["hooks", "PreToolUse", index, "matcher"], matcher(aliases));
+        for (let j = 0; j < hooks.length; j++)
+            for (const [key, value] of Object.entries(commandHook("groundtrack-hook"))) {
+                updated = setToml(updated, ["hooks", "PreToolUse", index, "hooks", j, key], value);
+            }
+        files.set(paths.project, updated);
+        return;
+    }
+    files.set(hookPath, upsertCommandHook(files.read(hookPath) ?? "", aliases, "groundtrack-hook"));
+}
+function planCursor(files, context) {
+    const path = join(context.repoDir, ".cursor/hooks.json");
+    let text = files.read(path) ?? "";
+    const config = readJson(text);
+    const hooks = array(at(config, ["hooks", "preToolUse"]), "Cursor preToolUse hooks");
+    const desired = {
+        command: "groundtrack-hook",
+        matcher: "MCP:.*(store_event|search_experiences)|MCP:(store_event|search_experiences)",
+    };
+    if (hooks.some((hook) => record(hook)?.command === desired.command && record(hook)?.matcher === desired.matcher))
+        return;
+    if (config.version !== undefined && config.version !== 1)
+        throw new Error("Unsupported Cursor hooks version. Update Groundtrack before changing this file.");
+    if (config.version === undefined)
+        text = setJson(text, ["version"], 1);
+    for (let i = hooks.length - 1; i >= 0; i--)
+        if (ownedHook(hooks[i]))
+            text = setJson(text, ["hooks", "preToolUse", i], undefined);
+    if (at(readJson(text), ["hooks", "preToolUse"]) === undefined)
+        text = setJson(text, ["hooks", "preToolUse"], []);
+    files.set(path, setJson(text, ["hooks", "preToolUse", -1], desired));
+}
+function planOpenCode(files, context) {
+    const path = configPaths("opencode", context).project;
+    const text = files.read(path) ?? "";
+    const config = readJson(text);
+    const plugins = array(config.plugin, "OpenCode plugins");
+    if (plugins.some((plugin) => typeof plugin === "string" && /^@groundtrack\/opencode-plugin(?:@|$)/.test(plugin)))
+        return;
+    files.set(path, setJson(text, ["plugin"], [...plugins, "@groundtrack/opencode-plugin"]));
+}
+export function activationSteps(agent, alias, existing, authenticated = false) {
+    const verify = "In a new session, ask: Verify Groundtrack's connection and hook context with search_experiences.";
+    const signIn = existing ? "If asked to sign in, " : "Sign in: ";
+    switch (agent) {
+        case "claude":
+            return [
+                ...(!authenticated
+                    ? [
+                        "Open this project in Claude Code and approve Groundtrack from .mcp.json if prompted.",
+                        `${signIn}use /mcp in Claude Code, or run claude mcp login ${alias} after approval.`,
+                    ]
+                    : []),
+                verify,
+            ];
+        case "codex":
+            return [
+                "Open and trust this project in Codex so it can load the project's MCP configuration.",
+                ...(!authenticated
+                    ? [`${signIn}run codex mcp login ${alias}, or connect in Codex Settings → MCP servers.`]
+                    : []),
+                "Review and trust the Groundtrack hook in /hooks, or accept Codex's hook approval prompt.",
+                verify,
+            ];
+        case "cursor":
+            return ["Open Cursor Settings → Tools & MCP → Groundtrack and connect if prompted.", verify];
+        case "opencode":
+            return [
+                ...(!authenticated ? [`${signIn}run opencode mcp auth ${alias}.`] : []),
+                "Restart OpenCode to load the plugin.",
+                verify,
+            ];
+    }
+}
+function buildAgentPlan(agent, context, url) {
+    const name = AGENTS.find((item) => item.id === agent).name;
+    const files = new FilePlan();
+    let alias = "groundtrack";
+    let existingConnection = false;
+    try {
+        const paths = configPaths(agent, context);
+        const project = readConfig(agent, files.read(paths.project) ?? "");
+        const user = readConfig(agent, files.read(paths.user) ?? "");
+        const maps = [serverMap(agent, project), serverMap(agent, user)];
+        if (agent === "claude")
+            maps.unshift(object(at(user, ["projects", context.repoDir, "mcpServers"]) ?? {}, "Claude local MCP servers"));
+        const candidates = maps.flatMap((map) => Object.entries(map).filter(([key, value]) => isGroundtrack(key, value, url)));
+        for (const [key, value] of candidates) {
+            const server = record(value);
+            if (server?.url !== url || server.command !== undefined)
+                throw new Error(`Existing ${name} server "${key}" has a different endpoint or transport. Use the matching --url or resolve it in the agent's settings.`);
+            if (server.enabled === false || server.disabled === true)
+                throw new Error(`Groundtrack is disabled in ${name}. Enable it in the agent's settings, then retry.`);
+            // The current runtime identifies Groundtrack tools by their server name.
+            if (!key.toLowerCase().includes("groundtrack") || !/^[a-zA-Z0-9_.-]+$/.test(key))
+                throw new Error(`Server "${key}" needs a Groundtrack-compatible alias containing "groundtrack" (letters, numbers, dots, hyphens, underscores). Rename it in ${name} before setup.`);
+        }
+        if (candidates.length) {
+            alias = candidates[0][0];
+            existingConnection = true;
+        }
+        else {
+            const config = agent === "opencode"
+                ? { type: "remote", url, enabled: true }
+                : agent === "claude"
+                    ? { type: "http", url }
+                    : { url };
+            const path = [...serverPath(agent, project), alias];
+            files.set(paths.project, agent === "codex"
+                ? setToml(files.read(paths.project) ?? "", path, config)
+                : setJson(files.read(paths.project) ?? "", path, config));
+        }
+        const aliases = candidates.length ? [...new Set(candidates.map(([key]) => key))] : [alias];
+        if (agent === "claude")
+            planClaude(files, context, aliases);
+        if (agent === "codex")
+            planCodex(files, context, aliases);
+        if (agent === "cursor")
+            planCursor(files, context);
+        if (agent === "opencode")
+            planOpenCode(files, context);
+        return {
+            agent,
+            name,
+            alias,
+            existingConnection,
+            changes: files.changes,
+            issue: null,
+            activation: "unverified",
+            nextSteps: activationSteps(agent, alias, existingConnection),
+        };
+    }
+    catch (error) {
+        return {
+            agent,
+            name,
+            alias,
+            existingConnection,
+            changes: [],
+            issue: error instanceof Error ? error.message : "Configuration could not be read.",
+            activation: "unverified",
+            nextSteps: [],
+        };
+    }
+}
+export function buildSetupPlan(context, agents, url) {
+    const files = new FilePlan();
+    let sharedIssue = null;
+    try {
+        const path = join(context.repoDir, "AGENTS.md");
+        const source = files.read(path);
+        files.set(path, managedInstructions(source, AGENT_INSTRUCTION_BODY, "AGENTS.md"));
+    }
+    catch (error) {
+        sharedIssue = error instanceof Error ? error.message : "Cannot update AGENTS.md.";
+    }
+    return {
+        agents: [...new Set(agents)].map((agent) => buildAgentPlan(agent, context, url)),
+        shared: files.changes,
+        sharedIssue,
+    };
+}
+export function planSummary(plan, context) {
+    return plan.agents.map((agent) => ({
+        agent: agent.agent,
+        name: agent.name,
+        status: plan.sharedIssue || agent.issue
+            ? "blocked"
+            : agent.changes.length || plan.shared.length
+                ? "needs_setup"
+                : "configured",
+        issue: plan.sharedIssue ?? agent.issue,
+        activation: agent.activation,
+        files: agent.changes.map((change) => relative(context.repoDir, change.path)),
+        nextSteps: agent.nextSteps,
+    }));
+}
+export function selectionChange(context, agents) {
+    const files = new FilePlan();
+    files.set(join(stateDir(context), "setup.json"), `${JSON.stringify({ version: 1, agents }, null, 2)}\n`);
+    return files.changes.map((change) => ({ ...change, mode: 0o600 }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundtrack/hooks",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",
@@ -19,6 +19,7 @@
   "files": [
     "dist/",
     "templates/",
+    "src/agents.ts",
     "README.md",
     "LICENSE"
   ],
@@ -33,7 +34,14 @@
       "types": "./dist/agent-instructions.d.ts",
       "default": "./dist/agent-instructions.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./agents": {
+      "types": "./src/agents.ts",
+      "browser": "./src/agents.ts",
+      "workerd": "./src/agents.ts",
+      "development": "./src/agents.ts",
+      "default": "./dist/agents.js"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -47,6 +55,11 @@
     "test": "pnpm run build && node --import tsx --test test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"
   },
+  "dependencies": {
+    "@clack/prompts": "0.11.0",
+    "jsonc-parser": "3.3.1",
+    "toml-eslint-parser": "0.10.0"
+  },
   "devDependencies": {
     "@groundtrack/typescript": "workspace:*",
     "@types/node": "^25.9.1",

package/src/agents.ts

@@ -0,0 +1,37 @@
+/** Shared by the CLI, browser UI, hooks, and server. Keep this module dependency-free. */
+export const AGENTS = [
+  {
+    id: "claude",
+    name: "Claude Code",
+    aliases: ["claude-code"],
+    source: "claude_code",
+    enrichment: "command",
+  },
+  { id: "codex", name: "Codex", aliases: [], source: "codex", enrichment: "command" },
+  { id: "cursor", name: "Cursor", aliases: [], source: "cursor", enrichment: "command" },
+  { id: "opencode", name: "OpenCode", aliases: [], source: "opencode", enrichment: "plugin" },
+] as const;
+
+export type AgentDefinition = (typeof AGENTS)[number];
+export type Agent = AgentDefinition["id"];
+export type CommandHookAgent = Extract<AgentDefinition, { enrichment: "command" }>["id"];
+export const AGENT_IDS = AGENTS.map((agent) => agent.id);
+
+export function isAgent(value: unknown): value is Agent {
+  return AGENTS.some((agent) => agent.id === value);
+}
+
+export function resolveAgent(value: string): AgentDefinition | undefined {
+  return AGENTS.find(
+    (agent) => agent.id === value || agent.aliases.some((alias) => alias === value),
+  );
+}
+
+export function agentFromClientName(value: string | null | undefined): AgentDefinition | undefined {
+  const normalized = value?.trim().toLowerCase() ?? "";
+  return AGENTS.find((agent) => normalized.includes(agent.id));
+}
+
+export function requiresHookRuntime(id: Agent): boolean {
+  return AGENTS.some((agent) => agent.id === id && agent.enrichment === "command");
+}

package/templates/AGENTS.md

@@ -1,9 +1,10 @@
-<!-- groundtrack:start version=3 -->
+<!-- groundtrack:start version=4 -->
 
 ## Groundtrack
 
 Use Groundtrack as the shared engineering memory for this repository.
 
+- At session start, check whether Groundtrack tools are available, using tool discovery if the client supports it. If `search_experiences` is unavailable, or a Groundtrack call reports connection, sign-in, or hook-setup problems, tell the user promptly, once per session unless the problem changes. Give the setup command for the current agent from this repository's root, for example `npx --yes --package @groundtrack/hooks@latest groundtrack setup --agent codex` when running in Codex. If the current agent is unclear, omit `--agent` to use the picker. Continue the user's task; when Groundtrack cannot be used, say so rather than claiming a successful lookup or inventing retrieved experiences.
 - Before non-trivial investigation or implementation where prior decisions, failures, or constraints could matter, call `search_experiences`. Start with a focused description of the work, then inspect the results and search one or two materially different adjacent concepts when related components, constraints, failure modes, or prior decisions could change the approach. Do not stop merely because the first search has no exact match; try a meaningfully broader or neighboring query. Keep this expansion bounded, and also search before repeating an approach that may already have been tried.
 - When a relevant experience needs more context or verification, call `get_experience_events` with its id to inspect the underlying raw evidence and provenance.
 - Apply relevant current experiences and heed any caveats that an experience was contradicted, superseded, or expired.