@groundtrack/hooks 0.1.16 → 0.1.18

package/README.md

@@ -88,7 +88,12 @@ live activation needs attention. No synthetic engineering event is required.
 ## Doctor compatibility
 
 `groundtrack doctor` is an alias for `status`; `groundtrack doctor --fix` uses the
-same setup and repair flow. Existing single-client commands continue to work:
+same setup and repair flow. Doctor checks for a newer published hooks package;
+when one is available, upgrade before repairing with an older bundled policy.
+If the registry is unavailable, Doctor still checks local configuration and
+preserves managed instructions newer than its own template. When invoked through
+`npx`, Doctor checks the globally installed hook runtime rather than the
+temporary executable provided by `npx`. Existing single-client commands continue to work:
 
 ```sh
 groundtrack doctor --fix --client codex

package/dist/doctor.js

@@ -228,9 +228,10 @@ function upsertCodexHook(content, matcher) {
 function managedContentIsCurrent(content, desired) {
     if (!content)
         return false;
-    const start = content.indexOf(MANAGED_START);
-    const end = content.indexOf(MANAGED_END, start);
-    return start >= 0 && end >= 0 && content.slice(start, end + MANAGED_END.length) === desired;
+    const managed = /<!-- groundtrack:start version=(\d+) -->[\s\S]*?<!-- groundtrack:end -->/.exec(content);
+    const desiredVersion = /<!-- groundtrack:start version=(\d+) -->/.exec(desired)?.[1];
+    return ((managed != null && desiredVersion != null && Number(managed[1]) > Number(desiredVersion)) ||
+        managed?.[0] === desired);
 }
 export function claudeInstructionsAreCurrent(content) {
     if (!content)
@@ -271,8 +272,12 @@ function removeLegacyAgentInstructions(content) {
 }
 export function upsertManagedContent(content, desired, migrateLegacyAgentInstructions = false) {
     const existing = content ?? "";
-    const managed = /<!-- groundtrack:start version=\d+ -->[\s\S]*?<!-- groundtrack:end -->/;
-    if (managed.test(existing)) {
+    const managed = /<!-- groundtrack:start version=(\d+) -->[\s\S]*?<!-- groundtrack:end -->/;
+    const match = managed.exec(existing);
+    if (match) {
+        const desiredVersion = /<!-- groundtrack:start version=(\d+) -->/.exec(desired)?.[1];
+        if (desiredVersion && Number(match[1]) > Number(desiredVersion))
+            return existing;
         return `${existing.replace(managed, desired).trimEnd()}\n`;
     }
     const base = (migrateLegacyAgentInstructions ? removeLegacyAgentInstructions(existing) : existing).trimEnd();
@@ -371,7 +376,8 @@ export function runDoctor(options) {
     const matcher = matcherForAliases(aliases);
     const checks = [];
     const changedFiles = [];
-    if (options.latestVersion && compareVersions(options.latestVersion, version) > 0) {
+    const upgradeNeeded = options.latestVersion && compareVersions(options.latestVersion, version) > 0;
+    if (upgradeNeeded) {
         checks.push({
             id: "cli-version",
             label: "Groundtrack package",
@@ -387,6 +393,8 @@ export function runDoctor(options) {
             detail: options.latestVersion ? `${version} (latest)` : `${version} (offline bundled state)`,
         });
     }
+    if (upgradeNeeded && options.fix)
+        return { version, clients, aliases, checks, changedFiles, healthy: false };
     let runtimeVersion = options.installedHookVersion;
     if (runtimeVersion === undefined)
         runtimeVersion = installedHookVersion();

package/dist/setup/cli.d.ts

@@ -2,6 +2,7 @@ import { type Agent } from "../agents.js";
 export declare const USAGE: string;
 export type Arguments = {
     command: "setup" | "status" | "version" | "help";
+    doctor: boolean;
     agents: Agent[];
     allDetected: boolean;
     yes: boolean;

package/dist/setup/cli.js

@@ -36,6 +36,7 @@ export function parseArguments(input) {
     const argv = [...input];
     const result = {
         command: "status",
+        doctor: false,
         agents: [],
         allDetected: false,
         yes: false,
@@ -51,6 +52,7 @@ export function parseArguments(input) {
         command = "version";
     if (!["setup", "status", "doctor", "version"].includes(command))
         throw new Error(`Unknown command: ${command}. Run groundtrack --help.`);
+    result.doctor = command === "doctor";
     result.command = command === "doctor" ? "status" : command;
     const take = (index, flag) => {
         const value = argv[index + 1];
@@ -105,6 +107,23 @@ export function parseArguments(input) {
     return result;
 }
 function runtimeVersion(context) {
+    if (context.env.npm_command === "exec") {
+        const result = spawnSync("npm", ["ls", "--global", "@groundtrack/hooks", "--depth=0", "--json"], {
+            env: context.env,
+            encoding: "utf8",
+            timeout: 5_000,
+            windowsHide: true,
+            shell: context.platform === "win32",
+        });
+        try {
+            const value = JSON.parse(result.stdout);
+            const version = value.dependencies?.["@groundtrack/hooks"]?.version;
+            return typeof version === "string" ? version : null;
+        }
+        catch {
+            return null;
+        }
+    }
     const binary = executable("groundtrack-hook", context);
     if (!binary)
         return null;
@@ -129,6 +148,26 @@ function runtimeVersion(context) {
         return null;
     }
 }
+function publishedVersion(context) {
+    if (context.env.GROUNDTRACK_DOCTOR_LATEST_VERSION !== undefined)
+        return context.env.GROUNDTRACK_DOCTOR_LATEST_VERSION || null;
+    const result = spawnSync("npm", ["view", "@groundtrack/hooks", "version", "--json"], {
+        env: context.env,
+        encoding: "utf8",
+        timeout: 5_000,
+        windowsHide: true,
+        shell: context.platform === "win32",
+    });
+    if (result.status !== 0)
+        return null;
+    try {
+        const version = JSON.parse(result.stdout);
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
 function run(binary, args, context, inherit = false) {
     return new Promise((resolve) => {
         const child = spawn(binary, args, {
@@ -143,7 +182,7 @@ function run(binary, args, context, inherit = false) {
         child.once("close", (code) => resolve(code === 0));
     });
 }
-function printPlan(plan, context, runtimeReady) {
+function printPlan(plan, context, runtimeReady, installedVersion) {
     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`);
@@ -153,7 +192,9 @@ function printPlan(plan, context, runtimeReady) {
     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(installedVersion
+            ? `  + Upgrade the shared Groundtrack hook runtime from ${installedVersion} to ${packageVersion()}\n`
+            : "  + 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) {
@@ -168,6 +209,33 @@ export async function runCli(argv) {
     }
     const context = environment({ repoDir: args.repoDir, homeDir: args.homeDir });
     const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !args.json);
+    const latestVersion = args.doctor ? publishedVersion(context) : null;
+    const upgradeNeeded = latestVersion != null && compareVersions(latestVersion, packageVersion()) > 0;
+    if (upgradeNeeded) {
+        const command = "npm install --global @groundtrack/hooks@latest";
+        const retry = args.command === "setup" ? "groundtrack doctor --fix" : "groundtrack doctor";
+        if (!args.json)
+            process.stdout.write(`Groundtrack Doctor ${packageVersion()} is outdated; ${latestVersion} is available. Upgrade before checking or repairing this project.\n`);
+        if (args.command === "setup" && interactive && !args.yes) {
+            const approved = await prompts.confirm({
+                message: `Upgrade Groundtrack globally to ${latestVersion} now?`,
+                initialValue: true,
+            });
+            if (!prompts.isCancel(approved) && approved) {
+                const installed = await run("npm", ["install", "--global", "@groundtrack/hooks@latest"], context, true);
+                if (installed) {
+                    process.stdout.write(`Upgrade complete. Rerun ${retry} to check this project.\n`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+        }
+        process.stdout.write(args.json
+            ? `${JSON.stringify({ installedVersion: packageVersion(), latestVersion, upgradeCommand: command, applied: false })}\n`
+            : `Run \`${command}\`, then rerun \`${retry}\`. No project files changed.\n`);
+        process.exitCode = 1;
+        return;
+    }
     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);
@@ -231,7 +299,7 @@ export async function runCli(argv) {
         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);
+            printPlan(plan, context, runtimeReady, installedVersion);
             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`);
@@ -250,7 +318,7 @@ export async function runCli(argv) {
     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);
+        printPlan(plan, context, runtimeReady, installedVersion);
     const ready = plan.agents.filter((agent) => !agent.issue);
     if (plan.sharedIssue || !ready.length) {
         if (args.json)
@@ -269,6 +337,7 @@ export async function runCli(argv) {
             return;
         }
     }
+    let runtimeUpdated = false;
     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.");
@@ -279,6 +348,7 @@ export async function runCli(argv) {
         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.");
+        runtimeUpdated = true;
     }
     const preferences = picked ? targets : [...new Set([...(saved ?? []), ...targets])];
     const changes = [
@@ -296,7 +366,7 @@ export async function runCli(argv) {
         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`);
+        process.stdout.write(`\n${ready.length} ${ready.length === 1 ? "agent configured" : "agents configured"}. ${changes.length ? `${changes.length} files updated.` : runtimeUpdated ? "Hook runtime upgraded. No project files changed." : "Everything is already current."}\n`);
         let connections = [];
         if (interactive) {
             const spinner = prompts.spinner();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundtrack/hooks",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",

package/templates/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- groundtrack:start version=4 -->
+<!-- groundtrack:start version=5 -->
 
 ## Groundtrack
 
@@ -8,7 +8,7 @@ Use Groundtrack as the shared engineering memory for this repository.
 - 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.
-- Once the effect of a search is known, call `report_experience_use` with its retrieval id. Report when a result changed the approach or avoided a failure, and report `not_helpful` when none applied.
+- Only call `report_experience_use` if `search_experiences` returned experiences; skip it for empty results, even with a retrieval id. For non-empty results, report when one changed the approach or avoided a failure, and report `not_helpful` after review when none applied.
 - After a task reaches a concrete result, call `record_outcome` with a short title, a concise summary, and the retrieval ids for searches that contributed. Include measurements only for sourced, quantified impact on time, cost, reliability, quality, performance, or throughput; tests, typechecks, lint, and builds are validation rather than impact. Include avoided work only when it was explicitly estimated, and never infer unknown values.
 - After a non-obvious discovery, decision, workaround, correction, or failed approach that would help a future agent, call `store_event` promptly with a concise title and an explanation of what happened and why it matters.
 - Do not store routine implementation details, obvious facts, unrestricted transcripts, or secrets.