@indigoai-us/hq-cli 5.286.0 → 5.287.0

package/dist/lib/lanes/outpost-snapshot-refresh.d.ts

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+export declare const OUTPOST_SNAPSHOT_REFRESH_LOCK_STALE_AFTER_MS: number;
+export interface SnapshotRefreshChildRuntime {
+    pid: number;
+    once: (event: "exit", listener: () => void) => unknown;
+}
+export interface StartSnapshotRefreshDeps {
+    spawn?: typeof spawn;
+    now?: () => number;
+    pid?: number;
+    isProcessAlive?: (pid: number) => boolean;
+    entryPath?: string;
+    beforeStaleLockClaim?: () => void;
+    writeError?: (message: string) => void;
+}
+export declare function outpostSnapshotRefreshLockPath(root: string, env?: NodeJS.ProcessEnv): string;
+/** Start the detached remote snapshot refresh unless this HQ root is refreshing already. */
+export declare function startOutpostLaneSnapshotRefresh(root: string, env?: NodeJS.ProcessEnv, deps?: StartSnapshotRefreshDeps): void;
+/** Adopt the launcher lock in the detached child and remove it on normal exit. */
+export declare function registerOutpostLaneSnapshotRefreshChild(env?: NodeJS.ProcessEnv, runtime?: SnapshotRefreshChildRuntime): boolean;
+//# sourceMappingURL=outpost-snapshot-refresh.d.ts.map

package/dist/lib/lanes/outpost-snapshot-refresh.js

@@ -0,0 +1,329 @@
+import { randomUUID, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const STATE_DIR_ENV = "HQ_LANES_SNAPSHOT_REFRESH_STATE_DIR";
+const CHILD_LOCK_PATH_ENV = "HQ_INTERNAL_LANES_SNAPSHOT_REFRESH_LOCK_PATH";
+const CHILD_LOCK_TOKEN_ENV = "HQ_INTERNAL_LANES_SNAPSHOT_REFRESH_LOCK_TOKEN";
+// One Outpost summary pickup has a 20-second timeout. Thirty minutes leaves
+// ample time for lists spanning many Outposts while bounding abandoned locks.
+export const OUTPOST_SNAPSHOT_REFRESH_LOCK_STALE_AFTER_MS = 30 * 60 * 1_000;
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function writeError(message) {
+    process.stderr.write(`${message}\n`);
+}
+export function outpostSnapshotRefreshLockPath(root, env = process.env) {
+    const stateBase = env[STATE_DIR_ENV]?.trim() || path.join(env.XDG_STATE_HOME?.trim() || path.join(os.homedir(), ".local", "state"), "hq-cli");
+    if (!path.isAbsolute(stateBase))
+        throw new Error(`${STATE_DIR_ENV} must resolve to an absolute path`);
+    const canonicalRoot = fs.realpathSync(path.resolve(root));
+    const rootHash = createHash("sha256").update(canonicalRoot).digest("hex");
+    return path.join(stateBase, "lanes-snapshot-refresh", `${rootHash}.lock`);
+}
+function parseLock(filePath, content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`could not read lock ${filePath}: ${errorMessage(err)}`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`invalid lock data in ${filePath}`);
+    }
+    const lock = value;
+    if (!Number.isSafeInteger(lock.pid) || (lock.pid ?? 0) <= 0 ||
+        !Number.isFinite(lock.startedAt) || (lock.startedAt ?? 0) < 0 ||
+        typeof lock.token !== "string" || lock.token.length === 0) {
+        throw new Error(`invalid lock fields in ${filePath}`);
+    }
+    return lock;
+}
+function readLock(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`could not read lock ${filePath}: ${errorMessage(err)}`);
+    }
+    return parseLock(filePath, content);
+}
+function observeLock(filePath) {
+    const descriptor = fs.openSync(filePath, "r");
+    try {
+        const stat = fs.fstatSync(descriptor);
+        const content = fs.readFileSync(descriptor, "utf8");
+        try {
+            return { lock: parseLock(filePath, content), content, stat };
+        }
+        catch (err) {
+            return { lock: null, content, stat, invalidReason: errorMessage(err) };
+        }
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true;
+        throw err;
+    }
+}
+function writeLockExclusive(filePath, lock) {
+    const descriptor = fs.openSync(filePath, "wx", 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(lock)}\n`, "utf8");
+        fs.fsyncSync(descriptor);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            // Keep the original write error as the actionable cause.
+        }
+        throw err;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function writeLockReplacement(filePath, lock) {
+    const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    const descriptor = fs.openSync(temporaryPath, "wx", 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(lock)}\n`, "utf8");
+        fs.fsyncSync(descriptor);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporaryPath);
+        }
+        catch {
+            // Keep the original write error as the actionable cause.
+        }
+        throw err;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    try {
+        fs.renameSync(temporaryPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporaryPath);
+        }
+        catch {
+            // Keep the rename error as the actionable cause.
+        }
+        throw err;
+    }
+}
+function releaseLock(filePath, token) {
+    try {
+        if (readLock(filePath).token === token)
+            fs.unlinkSync(filePath);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            writeError(`lanes snapshot refresh could not release its lock: ${errorMessage(err)}`);
+        }
+    }
+}
+function updateLockOwner(filePath, token, pid) {
+    const lock = readLock(filePath);
+    if (lock.token !== token)
+        throw new Error(`lock ownership changed at ${filePath}`);
+    writeLockReplacement(filePath, { ...lock, pid });
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+ * Claim the exact stale inode before unlinking it. Claim paths are stable for
+ * one inode, so two contenders cannot both remove the same expired lock.
+ */
+function claimStaleLock(filePath, observed) {
+    const claimPath = `${filePath}.claim-${observed.stat.dev}-${observed.stat.ino}`;
+    try {
+        fs.linkSync(filePath, claimPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST" || code === "ENOENT")
+            return false;
+        throw err;
+    }
+    let claimedStaleLock = false;
+    let claimError;
+    try {
+        const claimStat = fs.statSync(claimPath);
+        const currentStat = fs.statSync(filePath);
+        if (sameFile(observed.stat, claimStat) && sameFile(observed.stat, currentStat)) {
+            const claimContent = fs.readFileSync(claimPath, "utf8");
+            const currentContent = fs.readFileSync(filePath, "utf8");
+            if (claimContent === observed.content && currentContent === observed.content) {
+                fs.unlinkSync(filePath);
+                claimedStaleLock = true;
+            }
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            claimError = err;
+    }
+    try {
+        fs.unlinkSync(claimPath);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            claimError ??= err;
+    }
+    if (claimError)
+        throw claimError;
+    return claimedStaleLock;
+}
+function acquireLock(root, env, deps) {
+    const filePath = outpostSnapshotRefreshLockPath(root, env);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const lock = {
+            pid: deps.pid ?? process.pid,
+            startedAt: (deps.now ?? Date.now)(),
+            token: randomUUID(),
+        };
+        try {
+            writeLockExclusive(filePath, lock);
+            return lock;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        let existing;
+        try {
+            existing = observeLock(filePath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const staleSince = existing.lock?.startedAt ?? existing.stat.mtimeMs;
+        const ageMs = (deps.now ?? Date.now)() - staleSince;
+        const oldEnough = ageMs >= OUTPOST_SNAPSHOT_REFRESH_LOCK_STALE_AFTER_MS;
+        if (!existing.lock) {
+            if (!oldEnough) {
+                throw new Error(`malformed lock ${filePath} is not old enough to recover: ${existing.invalidReason}`);
+            }
+        }
+        else {
+            const alive = (deps.isProcessAlive ?? processIsAlive)(existing.lock.pid);
+            if (!oldEnough || alive)
+                return null;
+        }
+        deps.beforeStaleLockClaim?.();
+        if (!claimStaleLock(filePath, existing))
+            return null;
+    }
+    // Another caller may have replaced a stale lock during recovery. Fail closed
+    // and let the next list call retry rather than risking a second refresh.
+    return null;
+}
+/** Start the detached remote snapshot refresh unless this HQ root is refreshing already. */
+export function startOutpostLaneSnapshotRefresh(root, env = process.env, deps = {}) {
+    const report = deps.writeError ?? writeError;
+    let entry;
+    try {
+        const currentEntry = deps.entryPath ?? process.argv[1];
+        if (!currentEntry)
+            throw new Error("process.argv[1] is empty");
+        entry = fs.realpathSync(currentEntry);
+    }
+    catch (err) {
+        report(`lanes snapshot refresh could not resolve the running CLI entry: ${errorMessage(err)}`);
+        return;
+    }
+    let lock;
+    let filePath;
+    try {
+        filePath = outpostSnapshotRefreshLockPath(root, env);
+        lock = acquireLock(root, env, deps);
+    }
+    catch (err) {
+        report(`lanes snapshot refresh could not acquire its lock: ${errorMessage(err)}`);
+        return;
+    }
+    if (!lock)
+        return;
+    let child;
+    try {
+        const childEnv = {
+            ...env,
+            HQ_ROOT: root,
+            HQ_NO_UPDATE_CHECK: "1",
+            HQ_INTERNAL_LANES_REFRESH_REMOTE_SNAPSHOT: "1",
+            [CHILD_LOCK_PATH_ENV]: filePath,
+            [CHILD_LOCK_TOKEN_ENV]: lock.token,
+        };
+        const spawnChild = deps.spawn ?? spawn;
+        child = spawnChild(process.execPath, [...process.execArgv, entry, "lanes", "list", "--json"], {
+            cwd: root,
+            detached: true,
+            stdio: ["ignore", "ignore", "inherit"],
+            env: childEnv,
+        });
+        child.once("error", (err) => {
+            releaseLock(filePath, lock.token);
+            report(`lanes snapshot refresh could not start: ${errorMessage(err)}`);
+        });
+        if (child.pid)
+            updateLockOwner(filePath, lock.token, child.pid);
+        child.unref();
+    }
+    catch (err) {
+        try {
+            child?.kill();
+        }
+        catch {
+            // Spawn failure is already reported below; the lock is still released.
+        }
+        releaseLock(filePath, lock.token);
+        report(`lanes snapshot refresh could not start: ${errorMessage(err)}`);
+    }
+}
+/** Adopt the launcher lock in the detached child and remove it on normal exit. */
+export function registerOutpostLaneSnapshotRefreshChild(env = process.env, runtime = process) {
+    const filePath = env[CHILD_LOCK_PATH_ENV];
+    const token = env[CHILD_LOCK_TOKEN_ENV];
+    if (!filePath && !token)
+        return false;
+    if (!filePath || !token) {
+        writeError("lanes snapshot refresh child has incomplete lock metadata");
+        return false;
+    }
+    try {
+        updateLockOwner(filePath, token, runtime.pid);
+    }
+    catch (err) {
+        writeError(`lanes snapshot refresh child could not register its lock: ${errorMessage(err)}`);
+        return false;
+    }
+    runtime.once("exit", () => releaseLock(filePath, token));
+    return true;
+}
+//# sourceMappingURL=outpost-snapshot-refresh.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.286.0",
+  "version": "5.287.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {