@groundtrack/hooks 0.1.17 → 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.17",
+  "version": "0.1.18",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",