@clipboard-health/groundcrew 3.2.1 → 3.4.0

package/README.md

@@ -522,9 +522,9 @@ Cross-team projects work — the orchestrator caches the in-progress state ID pe
 </details>
 
 <details>
-<summary>Claude launches in bypass-permissions mode by default</summary>
+<summary>Claude launches in auto mode by default</summary>
 
-Groundcrew creates isolated per-ticket worktrees for unattended runs, so the shipped `claude` command is `claude --permission-mode bypassPermissions` to avoid workspace-trust and tool-permission prompts blocking automation. Override `models.definitions.claude.cmd` for a stricter mode.
+Groundcrew creates isolated per-ticket worktrees for unattended runs, so the shipped `claude` command is `claude --permission-mode auto` to let Claude proceed without stopping for clarifying questions while keeping its built-in safety prompts intact. Override `models.definitions.claude.cmd` for `bypassPermissions` if you need to suppress tool-permission prompts entirely, or for a stricter mode.
 
 </details>
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAyKA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAgOA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCvD"}

package/dist/cli.js

@@ -8,7 +8,11 @@ import { resumeWorkspaceCli } from "./commands/resumeWorkspace.js";
 import { sandboxCli } from "./commands/sandbox/index.js";
 import { setupReposCli } from "./commands/setupRepos.js";
 import { setupWorkspaceCli } from "./commands/setupWorkspace.js";
-import { errorMessage, readTicketArgument, writeError, writeOutput } from "./lib/util.js";
+import { createDefaultUpgradeCliOptions, upgradeCli } from "./commands/upgrade.js";
+import { computeUpgradeNudge, defaultUpgradeCheckCachePath, fetchLatestVersion, } from "./lib/upgrade.js";
+import { errorMessage, readEnvironmentVariable, readTicketArgument, writeError, writeOutput, } from "./lib/util.js";
+const NUDGE_TTL_MS = 6 * 60 * 60 * 1000;
+const NUDGE_FETCH_TIMEOUT_MS = 1000;
 const requireFromCli = createRequire(import.meta.url);
 function setupUsage() {
     return "Usage: crew setup repos [--dry-run] [<repo>...]";
@@ -51,6 +55,30 @@ async function runCli(argv) {
     }
     await setupWorkspaceCli(ticket, { dryRun });
 }
+async function upgradeCliInvoke(argv) {
+    const metadata = packageMetadata();
+    await upgradeCli(argv, async () => await createDefaultUpgradeCliOptions({
+        currentVersion: metadata.version,
+        packageName: metadata.name,
+        cliMetaUrl: import.meta.url,
+    }));
+}
+async function maybeRunUpgradeNudge(metadata) {
+    const message = await computeUpgradeNudge({
+        currentVersion: metadata.version,
+        packageName: metadata.name,
+        cachePath: defaultUpgradeCheckCachePath(),
+        ttlMs: NUDGE_TTL_MS,
+        fetchTimeoutMs: NUDGE_FETCH_TIMEOUT_MS,
+        registry: readEnvironmentVariable("npm_config_registry"),
+        noUpgradeCheck: readEnvironmentVariable("GROUNDCREW_NO_UPGRADE_CHECK") === "1",
+        now: Date.now,
+        fetcher: fetchLatestVersion,
+    });
+    if (message !== undefined) {
+        writeError(message);
+    }
+}
 async function doctorCli(argv) {
     let ticket;
     const remainingArgs = [];
@@ -119,6 +147,11 @@ const SUBCOMMANDS = {
         usage: "repos [--dry-run] [<repo>...]",
         invoke: setupCli,
     },
+    upgrade: {
+        summary: "Install the latest version of crew (or pin to a specific version)",
+        usage: "[<version>] [--check]",
+        invoke: upgradeCliInvoke,
+    },
 };
 function printHelp() {
     const width = Math.max(...Object.keys(SUBCOMMANDS).map((key) => key.length));
@@ -134,10 +167,13 @@ function printHelp() {
     }
     writeOutput("\nSee README.md for full configuration and behavior.");
 }
+function packageMetadata() {
+    // oxlint-disable-next-line typescript-eslint/no-unsafe-assignment -- package.json is shipped with this package and is the metadata source of truth.
+    const metadata = requireFromCli("../package.json");
+    return metadata;
+}
 function packageVersion() {
-    // oxlint-disable-next-line typescript-eslint/no-unsafe-assignment -- package.json is shipped with this package and is the version source of truth.
-    const packageMetadata = requireFromCli("../package.json");
-    return packageMetadata.version;
+    return packageMetadata().version;
 }
 export async function run(argv) {
     const [subcommand, ...rest] = argv;
@@ -159,6 +195,14 @@ export async function run(argv) {
         process.exitCode = 1;
         return;
     }
+    if (subcommand !== "upgrade") {
+        try {
+            await maybeRunUpgradeNudge(packageMetadata());
+        }
+        catch {
+            // Passive nudge is never load-bearing; never block the user's command.
+        }
+    }
     try {
         await command.invoke(rest);
     }

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,34 @@
+import { type InstallKind, type NpmRunResult } from "../lib/npmGlobal.ts";
+import { type VersionFetcher } from "../lib/upgrade.ts";
+export interface UpgradeCliOptions {
+    currentVersion: string;
+    packageName: string;
+    resolveInstall: () => Promise<UpgradeInstallDetails>;
+    fetcher: VersionFetcher;
+    runInstall: (options: {
+        packageName: string;
+        version: string;
+        npmBin: string;
+    }) => Promise<NpmRunResult>;
+    registry?: string | undefined;
+    fetchTimeoutMs: number;
+    /** Path of the upgrade-availability cache that the nudge reads. We prime
+     * it from `--check` and the default install path so the next non-upgrade
+     * subcommand can render the nudge without paying the network cost. */
+    cachePath: string;
+    now: () => number;
+}
+export interface UpgradeInstallDetails {
+    installKind: InstallKind;
+    installPath: string;
+    npmBin: string | undefined;
+}
+export type UpgradeCliOptionsInput = UpgradeCliOptions | (() => Promise<UpgradeCliOptions>);
+export declare function upgradeCli(argv: string[], optionsInput: UpgradeCliOptionsInput): Promise<void>;
+export interface CreateUpgradeOptionsArgs {
+    currentVersion: string;
+    packageName: string;
+    cliMetaUrl: string;
+}
+export declare function createDefaultUpgradeCliOptions(args: CreateUpgradeOptionsArgs): Promise<UpgradeCliOptions>;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/commands/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAK3B,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACrD,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,CAAC,OAAO,EAAE;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB;;0EAEsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAQD,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,CAAC,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;AA0D5F,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,YAAY,EAAE,sBAAsB,GACnC,OAAO,CAAC,IAAI,CAAC,CAyCf;AAyFD,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CA2B5B"}

package/dist/commands/upgrade.js

@@ -0,0 +1,196 @@
+import { runCommand } from "../lib/commandRunner.js";
+import { which } from "../lib/host.js";
+import { classifyInstall, createDefaultNpmSpawner, detectInstallPath, detectIsSymlink, detectNpmRootGlobal, runNpmInstallGlobal, } from "../lib/npmGlobal.js";
+import { compareVersions, defaultUpgradeCheckCachePath, fetchAndPrimeUpgradeCheckCache, fetchLatestVersion, parseVersion, } from "../lib/upgrade.js";
+import { errorMessage, readEnvironmentVariable, writeError, writeOutput } from "../lib/util.js";
+const EXPLICIT_FETCH_TIMEOUT_MS = 5000;
+function parseArgs(argv) {
+    let check = false;
+    let pinnedVersion;
+    for (const arg of argv) {
+        if (arg === "--help" || arg === "-h") {
+            return { kind: "help" };
+        }
+        if (arg === "--check") {
+            check = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { kind: "error", message: `crew upgrade: unknown argument: ${arg}` };
+        }
+        if (pinnedVersion !== undefined) {
+            return { kind: "error", message: "crew upgrade: too many positional arguments" };
+        }
+        pinnedVersion = arg;
+    }
+    if (check && pinnedVersion !== undefined) {
+        return { kind: "error", message: "crew upgrade: --check does not accept a version argument" };
+    }
+    if (check) {
+        return { kind: "check" };
+    }
+    return { kind: "install", pinnedVersion };
+}
+function printHelp() {
+    writeOutput("Usage: crew upgrade [<version>] [--check]");
+    writeOutput("");
+    writeOutput("Install the latest version of crew.");
+    writeOutput("");
+    writeOutput("Arguments:");
+    writeOutput("  <version>      Install an exact version (upgrade or downgrade)");
+    writeOutput("");
+    writeOutput("Options:");
+    writeOutput("  --check        Report availability without installing");
+    writeOutput("  -h, --help     Show this help");
+}
+function refusalMessage(kind, installPath, packageName) {
+    return `crew is not installed globally (${kind} at ${installPath}). Run 'npm install -g ${packageName}' to use 'crew upgrade'.`;
+}
+async function resolveOptions(options) {
+    if (typeof options === "function") {
+        return await options();
+    }
+    return options;
+}
+export async function upgradeCli(argv, optionsInput) {
+    const parsed = parseArgs(argv);
+    if (parsed.kind === "error") {
+        writeError(parsed.message);
+        process.exitCode = 1;
+        return;
+    }
+    if (parsed.kind === "help") {
+        printHelp();
+        return;
+    }
+    const options = await resolveOptions(optionsInput);
+    if (parsed.kind === "check") {
+        await runCheck(options);
+        return;
+    }
+    let targetVersion;
+    if (parsed.pinnedVersion === undefined) {
+        const fetched = await fetchOrFail(options);
+        if (fetched === undefined) {
+            return;
+        }
+        if (compareVersions(options.currentVersion, fetched) >= 0) {
+            writeOutput(`crew is up to date (${fetched})`);
+            return;
+        }
+        targetVersion = fetched;
+    }
+    else {
+        const resolved = resolvePinnedVersion(options, parsed.pinnedVersion);
+        if (resolved === undefined) {
+            return;
+        }
+        targetVersion = resolved;
+    }
+    const npmBin = await resolveGlobalNpmBin(options);
+    if (npmBin === undefined) {
+        return;
+    }
+    await runInstallAndReport(options, npmBin, targetVersion);
+}
+async function resolveGlobalNpmBin(options) {
+    const install = await options.resolveInstall();
+    if (install.installKind !== "global") {
+        writeError(refusalMessage(install.installKind, install.installPath, options.packageName));
+        process.exitCode = 1;
+        return undefined;
+    }
+    if (install.npmBin === undefined) {
+        writeError("crew upgrade: npm is required on PATH but was not found.");
+        process.exitCode = 1;
+        return undefined;
+    }
+    return install.npmBin;
+}
+async function runCheck(options) {
+    const latest = await fetchOrFail(options);
+    if (latest === undefined) {
+        return;
+    }
+    if (compareVersions(options.currentVersion, latest) >= 0) {
+        writeOutput(`crew is up to date (${latest})`);
+        return;
+    }
+    writeOutput(`${latest} available (you are on ${options.currentVersion}); run \`crew upgrade\``);
+}
+async function fetchOrFail(options) {
+    try {
+        return await fetchAndPrimeUpgradeCheckCache({
+            packageName: options.packageName,
+            cachePath: options.cachePath,
+            fetchTimeoutMs: options.fetchTimeoutMs,
+            registry: options.registry,
+            now: options.now,
+            fetcher: options.fetcher,
+        });
+    }
+    catch (error) {
+        writeError(`crew upgrade: could not reach npm registry: ${errorMessage(error)}`);
+        process.exitCode = 1;
+        return undefined;
+    }
+}
+function resolvePinnedVersion(options, pinnedVersion) {
+    try {
+        parseVersion(pinnedVersion);
+    }
+    catch (error) {
+        writeError(`crew upgrade: ${errorMessage(error)}`);
+        process.exitCode = 1;
+        return undefined;
+    }
+    if (options.currentVersion === pinnedVersion) {
+        writeOutput(`crew is already on ${pinnedVersion}`);
+        return undefined;
+    }
+    const cmp = compareVersions(options.currentVersion, pinnedVersion);
+    if (cmp > 0) {
+        writeOutput(`downgrading ${options.currentVersion} → ${pinnedVersion}`);
+    }
+    return pinnedVersion;
+}
+async function runInstallAndReport(options, npmBin, version) {
+    const result = await options.runInstall({
+        packageName: options.packageName,
+        version,
+        npmBin,
+    });
+    if (result.exitCode === 0) {
+        return;
+    }
+    if (result.sawEacces) {
+        writeError("crew upgrade: install failed with EACCES (permission denied). Your global npm prefix may require elevated permissions — see https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally");
+    }
+    process.exitCode = result.exitCode;
+}
+export async function createDefaultUpgradeCliOptions(args) {
+    return {
+        currentVersion: args.currentVersion,
+        packageName: args.packageName,
+        resolveInstall: async () => {
+            const installPath = detectInstallPath(args.cliMetaUrl);
+            const npmBin = await which("npm");
+            const npmRootGlobal = npmBin === undefined ? undefined : detectNpmRootGlobal(npmBin, runCommand);
+            const installKind = classifyInstall({
+                installPath,
+                npmRootGlobal,
+                isSymlink: detectIsSymlink,
+            });
+            return { installKind, installPath, npmBin };
+        },
+        fetcher: fetchLatestVersion,
+        runInstall: async (options) => await runNpmInstallGlobal({
+            ...options,
+            spawner: createDefaultNpmSpawner(process.stderr),
+        }),
+        fetchTimeoutMs: EXPLICIT_FETCH_TIMEOUT_MS,
+        registry: readEnvironmentVariable("npm_config_registry"),
+        cachePath: defaultUpgradeCheckCachePath(),
+        now: Date.now,
+    };
+}

package/dist/lib/config.d.ts

@@ -100,7 +100,7 @@ export interface ModelDefinition {
      * for execution. The rendered prompt is appended as a single quoted
      * positional argument. `{{worktree}}` is replaced before launch.
      *
-     * Keep this agent-native (e.g., `claude --permission-mode bypassPermissions`).
+     * Keep this agent-native (e.g., `claude --permission-mode auto`).
      * Groundcrew adds the Safehouse wrapper.
      */
     cmd: string;

package/dist/lib/config.js

@@ -42,7 +42,7 @@ const DEFAULT_ORCHESTRATOR = {
 };
 const DEFAULT_MODEL_DEFINITIONS = {
     claude: {
-        cmd: "claude --permission-mode bypassPermissions",
+        cmd: "claude --permission-mode auto",
         color: "#C15F3C",
         usage: { codexbar: { provider: "claude" } },
     },

package/dist/lib/npmGlobal.d.ts

@@ -0,0 +1,29 @@
+export type InstallKind = "global" | "linked" | "npx" | "project" | "unknown";
+export interface ClassifyInstallOptions {
+    installPath: string;
+    npmRootGlobal: string | undefined;
+    isSymlink: (path: string) => boolean;
+}
+export declare function classifyInstall(options: ClassifyInstallOptions): InstallKind;
+export interface NpmSpawnerResult {
+    exitCode: number;
+    stderrText: string;
+}
+export type NpmSpawner = (command: string, args: readonly string[]) => Promise<NpmSpawnerResult>;
+export interface NpmRunResult {
+    exitCode: number;
+    sawEacces: boolean;
+}
+export interface RunNpmInstallOptions {
+    packageName: string;
+    version: string;
+    npmBin: string;
+    spawner: NpmSpawner;
+}
+export declare function runNpmInstallGlobal(options: RunNpmInstallOptions): Promise<NpmRunResult>;
+export declare function detectInstallPath(cliMetaUrl: string): string;
+export type NpmRootRunner = (command: string, args: readonly string[]) => string;
+export declare function detectNpmRootGlobal(npmBin: string, runner: NpmRootRunner): string | undefined;
+export declare function detectIsSymlink(path: string): boolean;
+export declare function createDefaultNpmSpawner(passthroughStderr: NodeJS.WritableStream): NpmSpawner;
+//# sourceMappingURL=npmGlobal.d.ts.map

package/dist/lib/npmGlobal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npmGlobal.d.ts","sourceRoot":"","sources":["../../src/lib/npmGlobal.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,WAAW,CAY5E;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEjG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAO9F;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAEjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAM7F;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED,wBAAgB,uBAAuB,CAAC,iBAAiB,EAAE,MAAM,CAAC,cAAc,GAAG,UAAU,CAmB5F"}

package/dist/lib/npmGlobal.js

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import { lstatSync } from "node:fs";
+import { dirname, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+export function classifyInstall(options) {
+    const { installPath, npmRootGlobal, isSymlink } = options;
+    if (npmRootGlobal !== undefined && installPath.startsWith(`${npmRootGlobal}${sep}`)) {
+        return isSymlink(installPath) ? "linked" : "global";
+    }
+    if (installPath.includes(`${sep}_npx${sep}`)) {
+        return "npx";
+    }
+    if (installPath.includes(`${sep}node_modules${sep}`)) {
+        return "project";
+    }
+    return "unknown";
+}
+export async function runNpmInstallGlobal(options) {
+    const args = ["install", "-g", `${options.packageName}@${options.version}`];
+    const result = await options.spawner(options.npmBin, args);
+    return {
+        exitCode: result.exitCode,
+        sawEacces: result.stderrText.includes("EACCES"),
+    };
+}
+export function detectInstallPath(cliMetaUrl) {
+    return dirname(dirname(fileURLToPath(cliMetaUrl)));
+}
+export function detectNpmRootGlobal(npmBin, runner) {
+    try {
+        return runner(npmBin, ["root", "-g"]);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function detectIsSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function createDefaultNpmSpawner(passthroughStderr) {
+    return async (command, args) => await new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], { stdio: ["inherit", "inherit", "pipe"] });
+        const { stderr } = child;
+        const chunks = [];
+        stderr.on("data", (chunk) => {
+            chunks.push(chunk);
+            passthroughStderr.write(chunk);
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve({
+                exitCode: code ?? 1,
+                stderrText: Buffer.concat(chunks).toString("utf8"),
+            });
+        });
+    });
+}

package/dist/lib/upgrade.d.ts

@@ -0,0 +1,66 @@
+interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export declare function parseVersion(version: string): Version;
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+export declare function normalizeRegistry(registry: string | undefined): string;
+export interface FetchOptions {
+    timeoutMs: number;
+    registry?: string | undefined;
+}
+export declare function fetchLatestVersion(packageName: string, options: FetchOptions): Promise<string>;
+export interface UpgradeCheckCacheEntry {
+    latest: string;
+    fetchedAt: number;
+    registry: string;
+}
+export interface PrimeUpgradeCheckCacheOptions {
+    path: string;
+    latest: string;
+    registry?: string | undefined;
+    now: () => number;
+}
+export type UpgradeCheckCacheResult = {
+    kind: "missing";
+} | {
+    kind: "fresh";
+    entry: UpgradeCheckCacheEntry;
+} | {
+    kind: "stale";
+    entry: UpgradeCheckCacheEntry;
+};
+export declare function defaultUpgradeCheckCachePath(): string;
+export declare function readUpgradeCheckCache(path: string, options: {
+    now: () => number;
+    ttlMs: number;
+    registry?: string | undefined;
+}): UpgradeCheckCacheResult;
+export declare function writeUpgradeCheckCache(path: string, entry: UpgradeCheckCacheEntry): void;
+export declare function primeUpgradeCheckCache(options: PrimeUpgradeCheckCacheOptions): void;
+export declare function composeNudgeMessage(current: string, latest: string): string | undefined;
+export type VersionFetcher = (packageName: string, options: FetchOptions) => Promise<string>;
+export interface FetchAndPrimeUpgradeCheckCacheOptions {
+    packageName: string;
+    cachePath: string;
+    fetchTimeoutMs: number;
+    registry?: string | undefined;
+    now: () => number;
+    fetcher: VersionFetcher;
+}
+export declare function fetchAndPrimeUpgradeCheckCache(options: FetchAndPrimeUpgradeCheckCacheOptions): Promise<string>;
+export interface ComputeUpgradeNudgeOptions {
+    currentVersion: string;
+    packageName: string;
+    cachePath: string;
+    ttlMs: number;
+    fetchTimeoutMs: number;
+    registry?: string | undefined;
+    noUpgradeCheck: boolean;
+    now: () => number;
+    fetcher: VersionFetcher;
+}
+export declare function computeUpgradeNudge(options: ComputeUpgradeNudgeOptions): Promise<string | undefined>;
+export {};
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/lib/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/lib/upgrade.ts"],"names":[],"mappings":"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"}

package/dist/lib/upgrade.js

@@ -0,0 +1,178 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { errorMessage, readEnvironmentVariable } from "./util.js";
+const NUMERIC_IDENTIFIER_PATTERN = String.raw `0|[1-9]\d*`;
+const VERSION_RE = new RegExp(String.raw `^(${NUMERIC_IDENTIFIER_PATTERN})\.(${NUMERIC_IDENTIFIER_PATTERN})\.(${NUMERIC_IDENTIFIER_PATTERN})$`);
+export function parseVersion(version) {
+    const match = VERSION_RE.exec(version);
+    if (!match) {
+        throw new Error(`invalid version: ${JSON.stringify(version)}`);
+    }
+    return {
+        // oxlint-disable typescript/no-non-null-assertion -- VERSION_RE guarantees groups 1–3 on match; group 4 is optional.
+        major: Number.parseInt(match[1], 10),
+        minor: Number.parseInt(match[2], 10),
+        patch: Number.parseInt(match[3], 10),
+        // oxlint-enable typescript/no-non-null-assertion
+    };
+}
+export function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    for (const key of ["major", "minor", "patch"]) {
+        if (left[key] !== right[key]) {
+            return left[key] > right[key] ? 1 : -1;
+        }
+    }
+    return 0;
+}
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export function normalizeRegistry(registry) {
+    return (registry ?? DEFAULT_REGISTRY).replace(/\/$/, "");
+}
+function encodePackageNameForRegistry(packageName) {
+    return encodeURIComponent(packageName).replace(/^%40/, "@");
+}
+export async function fetchLatestVersion(packageName, options) {
+    const registry = normalizeRegistry(options.registry);
+    const url = `${registry}/${encodePackageNameForRegistry(packageName)}/latest`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, options.timeoutMs);
+    try {
+        let response;
+        try {
+            response = await fetch(url, { signal: controller.signal });
+        }
+        catch (error) {
+            throw new Error(`registry request failed: ${errorMessage(error)}`, { cause: error });
+        }
+        if (!response.ok) {
+            throw new Error(`registry returned ${response.status} for ${url}`);
+        }
+        const body = await response.json();
+        if (typeof body !== "object" || body === null || !("version" in body)) {
+            throw new TypeError(`registry response missing 'version' field`);
+        }
+        const { version } = body;
+        if (typeof version !== "string") {
+            throw new TypeError(`registry response 'version' field is not a string`);
+        }
+        parseVersion(version);
+        return version;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function defaultUpgradeCheckCachePath() {
+    const override = readEnvironmentVariable("XDG_CACHE_HOME");
+    const base = override === undefined || override.length === 0 ? join(homedir(), ".cache") : override;
+    return join(base, "groundcrew", "upgrade-check.json");
+}
+function parseCacheEntry(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const candidate = value;
+    if (typeof candidate.latest !== "string" ||
+        typeof candidate.fetchedAt !== "number" ||
+        typeof candidate.registry !== "string") {
+        return undefined;
+    }
+    try {
+        parseVersion(candidate.latest);
+    }
+    catch {
+        return undefined;
+    }
+    return { latest: candidate.latest, fetchedAt: candidate.fetchedAt, registry: candidate.registry };
+}
+export function readUpgradeCheckCache(path, options) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return { kind: "missing" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "missing" };
+    }
+    const entry = parseCacheEntry(parsed);
+    if (!entry) {
+        return { kind: "missing" };
+    }
+    if (entry.registry !== normalizeRegistry(options.registry)) {
+        return { kind: "missing" };
+    }
+    const ageMs = options.now() - entry.fetchedAt;
+    return ageMs >= options.ttlMs ? { kind: "stale", entry } : { kind: "fresh", entry };
+}
+export function writeUpgradeCheckCache(path, entry) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(entry));
+}
+function writeUpgradeCheckCacheBestEffort(path, entry) {
+    try {
+        writeUpgradeCheckCache(path, entry);
+    }
+    catch {
+        // Upgrade-check cache writes are best-effort; callers should keep using current data.
+    }
+}
+export function primeUpgradeCheckCache(options) {
+    writeUpgradeCheckCacheBestEffort(options.path, {
+        latest: options.latest,
+        fetchedAt: options.now(),
+        registry: normalizeRegistry(options.registry),
+    });
+}
+export function composeNudgeMessage(current, latest) {
+    if (compareVersions(current, latest) >= 0) {
+        return undefined;
+    }
+    return `[crew] ${latest} available — run \`crew upgrade\` (you have ${current})`;
+}
+export async function fetchAndPrimeUpgradeCheckCache(options) {
+    const latest = await options.fetcher(options.packageName, {
+        timeoutMs: options.fetchTimeoutMs,
+        registry: options.registry,
+    });
+    primeUpgradeCheckCache({
+        path: options.cachePath,
+        latest,
+        registry: options.registry,
+        now: options.now,
+    });
+    return latest;
+}
+export async function computeUpgradeNudge(options) {
+    if (options.noUpgradeCheck) {
+        return undefined;
+    }
+    const cacheResult = readUpgradeCheckCache(options.cachePath, {
+        now: options.now,
+        ttlMs: options.ttlMs,
+        registry: options.registry,
+    });
+    if (cacheResult.kind === "fresh") {
+        return composeNudgeMessage(options.currentVersion, cacheResult.entry.latest);
+    }
+    try {
+        const latest = await fetchAndPrimeUpgradeCheckCache(options);
+        return composeNudgeMessage(options.currentVersion, latest);
+    }
+    catch {
+        if (cacheResult.kind === "stale") {
+            return composeNudgeMessage(options.currentVersion, cacheResult.entry.latest);
+        }
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",