@indigoai-us/hq-cli 5.318.1-beta.0 → 5.320.0

package/dist/lib/lanes/orphaned-dropbox.d.ts

@@ -0,0 +1,24 @@
+import type { LaneCompanyRef } from "./types.js";
+export interface OrphanedBareIdDropbox {
+    ulid: string;
+    canonical_lane_ids: string[];
+    message_count: number;
+    newest_message_at: string | null;
+    source_dir: string;
+}
+/** Finds bare-ULID run folders that have no bare lane record but do have a canonical lane. */
+export declare function findOrphanedBareIdDropboxes(hqRoot: string, company?: LaneCompanyRef): OrphanedBareIdDropbox[];
+export interface RepairOrphanedDropboxResult {
+    ulid: string;
+    canonical_lane_id: string;
+    message_count: number;
+    newest_message_at: string | null;
+    applied: boolean;
+    archived_dir?: string;
+}
+export declare function repairOrphanedBareIdDropbox(hqRoot: string, ulidInput: string, options: {
+    apply: boolean;
+    enabled: boolean;
+    now: Date;
+}): RepairOrphanedDropboxResult;
+//# sourceMappingURL=orphaned-dropbox.d.ts.map

package/dist/lib/lanes/orphaned-dropbox.js

@@ -0,0 +1,213 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+import { LANES_RUNS_REL } from "./spawn.js";
+import { readAllLanes, tryReadLane } from "./store.js";
+import { resolveLaneCompany } from "./lane-company.js";
+const ULID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+function fail(error, message, details = {}) {
+    throw new LanesError(error, message, details);
+}
+function laneUlid(laneId) {
+    const prefix = laneId.slice(0, 26);
+    if (!ULID_PATTERN.test(prefix))
+        return null;
+    return laneId.length === 26 || laneId[26] === "_" ? prefix.toUpperCase() : null;
+}
+function checkedInbox(sourceDir) {
+    const dropboxDir = path.join(sourceDir, "dropbox");
+    const inbox = path.join(dropboxDir, "inbox.jsonl");
+    try {
+        const dropboxStat = fs.lstatSync(dropboxDir);
+        if (!dropboxStat.isDirectory() || dropboxStat.isSymbolicLink()) {
+            return fail("orphaned_dropbox_invalid", "Orphaned dropbox path must be a regular directory", { path: dropboxDir });
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { inbox, messages: [] };
+        if (error instanceof LanesError)
+            throw error;
+        return fail("orphaned_dropbox_unreadable", `Could not inspect orphaned dropbox: ${error instanceof Error ? error.message : String(error)}`, { path: dropboxDir });
+    }
+    let stat;
+    try {
+        stat = fs.lstatSync(inbox);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { inbox, messages: [] };
+        return fail("orphaned_dropbox_unreadable", `Could not inspect orphaned inbox: ${error instanceof Error ? error.message : String(error)}`, { path: inbox });
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        return fail("orphaned_dropbox_invalid", "Orphaned inbox must be a regular file", { path: inbox });
+    }
+    let text;
+    try {
+        text = fs.readFileSync(inbox, "utf8");
+    }
+    catch (error) {
+        return fail("orphaned_dropbox_unreadable", `Could not read orphaned inbox: ${error instanceof Error ? error.message : String(error)}`, { path: inbox });
+    }
+    const messages = [];
+    for (const [index, line] of text.split(/\r?\n/).entries()) {
+        if (line.trim() === "")
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            return fail("orphaned_dropbox_message_invalid", "Orphaned inbox contains malformed JSONL", { path: inbox, line: index + 1 });
+        }
+        if (value === null || typeof value !== "object" || Array.isArray(value) || typeof value.text !== "string") {
+            return fail("orphaned_dropbox_message_invalid", "Orphaned inbox contains an invalid dropbox message", { path: inbox, line: index + 1 });
+        }
+        messages.push(value);
+    }
+    return { inbox, messages };
+}
+function canonicalLanesByUlid(hqRoot) {
+    const grouped = new Map();
+    for (const lane of readAllLanes(hqRoot)) {
+        const ulid = laneUlid(lane.lane_id);
+        if (!ulid)
+            continue;
+        grouped.set(ulid, [...(grouped.get(ulid) ?? []), lane]);
+    }
+    return grouped;
+}
+/** Finds bare-ULID run folders that have no bare lane record but do have a canonical lane. */
+export function findOrphanedBareIdDropboxes(hqRoot, company) {
+    const runsRoot = path.join(hqRoot, LANES_RUNS_REL);
+    let entries;
+    try {
+        const stat = fs.lstatSync(runsRoot);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            return fail("orphaned_dropbox_runs_invalid", "Lane runs path must be a regular directory", { path: runsRoot });
+        }
+        entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        if (error instanceof LanesError)
+            throw error;
+        return fail("orphaned_dropbox_runs_unreadable", `Could not list lane runs: ${error instanceof Error ? error.message : String(error)}`, { path: runsRoot });
+    }
+    const lanesByUlid = canonicalLanesByUlid(hqRoot);
+    const findings = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !ULID_PATTERN.test(entry.name))
+            continue;
+        const ulid = entry.name.toUpperCase();
+        if (tryReadLane(hqRoot, entry.name) !== null)
+            continue;
+        const canonicalLanes = lanesByUlid.get(ulid) ?? [];
+        const visibleLanes = company === undefined ? canonicalLanes : canonicalLanes.filter((lane) => {
+            const resolved = resolveLaneCompany(hqRoot, lane).company;
+            return resolved?.slug === company.slug && resolved.uid === company.uid;
+        });
+        const canonicalLaneIds = visibleLanes.map((lane) => lane.lane_id);
+        if (canonicalLaneIds.length === 0)
+            continue;
+        const sourceDir = path.join(runsRoot, entry.name);
+        const { messages } = checkedInbox(sourceDir);
+        const newest = messages.reduce((current, message) => {
+            if (typeof message.at !== "string")
+                return current;
+            const ms = Date.parse(message.at);
+            if (!Number.isFinite(ms) || (current !== null && current.ms >= ms))
+                return current;
+            return { at: message.at, ms };
+        }, null);
+        findings.push({
+            ulid,
+            canonical_lane_ids: canonicalLaneIds,
+            message_count: messages.length,
+            newest_message_at: newest?.at ?? null,
+            source_dir: sourceDir,
+        });
+    }
+    return findings.sort((a, b) => a.ulid.localeCompare(b.ulid));
+}
+export function repairOrphanedBareIdDropbox(hqRoot, ulidInput, options) {
+    const ulid = ulidInput.trim().toUpperCase();
+    if (!ULID_PATTERN.test(ulid))
+        return fail("orphaned_dropbox_ulid_invalid", "Expected a 26-character ULID", { ulid: ulidInput });
+    const finding = findOrphanedBareIdDropboxes(hqRoot).find((entry) => entry.ulid === ulid);
+    if (!finding)
+        return fail("orphaned_dropbox_not_found", `No orphaned bare-ID dropbox was found for ${ulid}`, { ulid });
+    if (finding.canonical_lane_ids.length !== 1) {
+        return fail("orphaned_dropbox_lane_ambiguous", `ULID ${ulid} matches more than one lane record`, { ulid, lane_ids: finding.canonical_lane_ids });
+    }
+    const canonicalLaneId = finding.canonical_lane_ids[0];
+    if (tryReadLane(hqRoot, canonicalLaneId) === null) {
+        return fail("orphaned_dropbox_lane_changed", `Canonical lane ${canonicalLaneId} disappeared before repair`, { ulid, lane_id: canonicalLaneId });
+    }
+    const { messages } = checkedInbox(finding.source_dir);
+    const newest = messages.reduce((current, message) => {
+        if (typeof message.at !== "string")
+            return current;
+        const ms = Date.parse(message.at);
+        if (!Number.isFinite(ms) || (current !== null && current.ms >= ms))
+            return current;
+        return { at: message.at, ms };
+    }, null);
+    const result = {
+        ulid,
+        canonical_lane_id: canonicalLaneId,
+        message_count: messages.length,
+        newest_message_at: newest?.at ?? null,
+        applied: false,
+    };
+    if (!options.apply)
+        return result;
+    if (!options.enabled)
+        return fail("orphaned_dropbox_repair_disabled", "Applying orphaned dropbox repairs requires the lanes.orphaned-bare-id-dropbox-repair flag", { ulid });
+    const archiveName = `${ulid}.orphaned-${options.now.toISOString().replaceAll(/[:.]/g, "-")}`;
+    const archivedDir = path.join(path.dirname(finding.source_dir), archiveName);
+    if (fs.existsSync(archivedDir))
+        return fail("orphaned_dropbox_archive_exists", "Orphaned dropbox archive path already exists", { ulid, path: archivedDir });
+    if (messages.length > 0) {
+        const targetRunDir = path.join(hqRoot, LANES_RUNS_REL, canonicalLaneId);
+        const targetDropboxDir = path.join(targetRunDir, "dropbox");
+        fs.mkdirSync(targetRunDir, { recursive: true });
+        for (const dir of [targetRunDir, targetDropboxDir]) {
+            try {
+                const stat = fs.lstatSync(dir);
+                if (!stat.isDirectory() || stat.isSymbolicLink()) {
+                    return fail("orphaned_dropbox_target_invalid", "Canonical dropbox path must be a regular directory", { path: dir });
+                }
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    return fail("orphaned_dropbox_target_unreadable", `Could not inspect canonical dropbox path: ${error instanceof Error ? error.message : String(error)}`, { path: dir });
+                }
+                fs.mkdirSync(dir);
+            }
+        }
+        const targetInbox = path.join(targetDropboxDir, "inbox.jsonl");
+        try {
+            const stat = fs.lstatSync(targetInbox);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                return fail("orphaned_dropbox_target_invalid", "Canonical inbox must be a regular file", { path: targetInbox });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                return fail("orphaned_dropbox_target_unreadable", `Could not inspect canonical inbox: ${error instanceof Error ? error.message : String(error)}`, { path: targetInbox });
+            }
+        }
+        const redeliveredAt = options.now.toISOString();
+        const redelivered = messages.map((message) => ({
+            ...message,
+            redelivered: true,
+            redelivered_from: ulid,
+            redelivered_at: redeliveredAt,
+        }));
+        fs.appendFileSync(targetInbox, `${redelivered.map((message) => JSON.stringify(message)).join("\n")}\n`, "utf8");
+    }
+    fs.renameSync(finding.source_dir, archivedDir);
+    return { ...result, applied: true, archived_dir: archivedDir };
+}
+//# sourceMappingURL=orphaned-dropbox.js.map

package/dist/lib/lanes/tracker-checks.d.ts

@@ -69,7 +69,7 @@ export interface TrackerCheckFinding {
     [key: string]: unknown;
 }
 export interface TrackerCheckResult {
-    id: "questions" | "lead_lanes" | "freshness" | "blockers" | "kpis" | "directives" | "orphaned_lane";
+    id: "questions" | "lead_lanes" | "freshness" | "blockers" | "kpis" | "directives" | "orphaned_lane" | "orphaned_bare_id_dropbox";
     result: "ok" | "failing";
     items: TrackerCheckFinding[];
 }

package/dist/utils/package-use-lease.d.ts

@@ -0,0 +1,25 @@
+export declare class PackageUseUpdatePendingError extends Error {
+    constructor(message: string);
+}
+export interface PackageUseLease {
+    readonly leasePath: string;
+    release(): void;
+}
+export interface PackageUseLeaseRecord {
+    pid: number;
+    start_time_ms: number;
+    hq_version: string;
+}
+export declare function npmPrefix(root: string, platform?: NodeJS.Platform): string | null;
+export declare function packageUseLeaseDirectory(prefix: string, stateDirectory?: string): string;
+export declare function packageUseUpdateRequestPath(prefix: string, stateDirectory?: string): string;
+declare function waitForUpdateRequest(requestPath: string, timeoutMs: number): void;
+export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string): PackageUseLease;
+export declare function acquireCurrentPackageUseLease(): PackageUseLease | null;
+/** True while the desktop updater owns the per-prefix update request. */
+export declare function currentPackageUseUpdateRequested(): boolean;
+export declare const __test__: {
+    waitForUpdateRequest: typeof waitForUpdateRequest;
+};
+export {};
+//# sourceMappingURL=package-use-lease.d.ts.map

package/dist/utils/package-use-lease.js

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
+const CLI_NAME = "@indigoai-us/hq-cli";
+const UPDATE_REQUEST = "update.pending.json";
+export class PackageUseUpdatePendingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PackageUseUpdatePendingError";
+    }
+}
+function errorLabel(error) {
+    if (error && typeof error === "object") {
+        const value = error;
+        if (typeof value.code === "string")
+            return value.code;
+        if (typeof value.name === "string")
+            return value.name;
+    }
+    return "unknown error";
+}
+function readPackage(directory) {
+    try {
+        return JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8"));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw new Error(`Unable to inspect the HQ CLI install (${errorLabel(error)})`, { cause: error });
+    }
+}
+function findCliPackage(directory) {
+    while (true) {
+        const pkg = readPackage(directory);
+        if (pkg?.name === CLI_NAME) {
+            return { root: directory, version: typeof pkg.version === "string" ? pkg.version : "unknown" };
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+function isPnpmGlobal(root) {
+    const normalized = root.replace(/\\/g, "/").replace(/\/+$/, "");
+    const parts = normalized.split("/").filter(Boolean);
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        if (parts[i] === "global" && (/^\d+$/.test(parts[i + 1]) || /^v\d+$/.test(parts[i + 1])))
+            return true;
+    }
+    const home = process.env.PNPM_HOME?.replace(/\\/g, "/").replace(/\/+$/, "");
+    const globalRoot = home ? `${home}/global` : null;
+    const left = process.platform === "win32" ? normalized.toLowerCase() : normalized;
+    const right = globalRoot && process.platform === "win32" ? globalRoot.toLowerCase() : globalRoot;
+    return Boolean(right && (left === right || left.startsWith(`${right}/`)));
+}
+function isBunGlobal(root) {
+    const parts = root.replace(/\\/g, "/").split("/").filter(Boolean);
+    return parts.some((part, i) => part === "install" && parts[i + 1] === "global" && parts[i + 2] === "node_modules");
+}
+export function npmPrefix(root, platform = process.platform) {
+    const normalized = root.replace(/\\/g, "/").replace(/\/+$/, "");
+    const parts = normalized.split("/");
+    const index = parts.lastIndexOf("node_modules");
+    if (index < 0)
+        return null;
+    const end = parts[index - 1] === "lib" ? index - 1 : index;
+    const prefix = parts.slice(0, end).join("/");
+    if (platform === "win32" && /^[a-z]:$/i.test(prefix))
+        return `${prefix}/`;
+    if (!prefix && normalized.startsWith("/"))
+        return "/";
+    return prefix || null;
+}
+function packageUseStateDirectory() {
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (!localAppData)
+            throw new Error("LOCALAPPDATA is unavailable for the HQ CLI package-use lease");
+        return path.join(localAppData, "hq-cli", "state", "package-use");
+    }
+    return path.join(process.env.XDG_STATE_HOME?.trim() || path.join(os.homedir(), ".local", "state"), "hq-cli", "package-use");
+}
+function normalizedPrefix(prefix) {
+    let canonical = realpathSync.native(prefix).replace(/\\/g, "/");
+    canonical = canonical.replace(/^\\\\\?\\UNC\\/i, "//").replace(/^\\\\\?\\/, "");
+    return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+export function packageUseLeaseDirectory(prefix, stateDirectory = packageUseStateDirectory()) {
+    const digest = createHash("sha256").update(normalizedPrefix(prefix), "utf8").digest("hex");
+    return path.join(stateDirectory, digest);
+}
+export function packageUseUpdateRequestPath(prefix, stateDirectory) {
+    return path.join(packageUseLeaseDirectory(prefix, stateDirectory), UPDATE_REQUEST);
+}
+function waitForUpdateRequest(requestPath, timeoutMs) {
+    const started = Date.now();
+    const sleeper = new Int32Array(new SharedArrayBuffer(4));
+    while (true) {
+        try {
+            const request = JSON.parse(readFileSync(requestPath, "utf8"));
+            const pid = request.pid;
+            if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+                throw new Error("invalid update request");
+            }
+            try {
+                process.kill(pid, 0);
+            }
+            catch (error) {
+                if (error.code === "ESRCH") {
+                    rmSync(requestPath, { force: true });
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw new Error(`Unable to read the HQ CLI update request (${errorLabel(error)})`, { cause: error });
+        }
+        if (Date.now() - started >= timeoutMs) {
+            throw new PackageUseUpdatePendingError("The HQ CLI package is being updated; retry after the update finishes");
+        }
+        Atomics.wait(sleeper, 0, 0, 100);
+    }
+}
+export function acquirePackageUseLease(prefix, hqVersion, stateDirectory) {
+    const directory = packageUseLeaseDirectory(prefix, stateDirectory);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const requestPath = path.join(directory, UPDATE_REQUEST);
+    const record = {
+        pid: process.pid,
+        start_time_ms: Math.floor(performance.timeOrigin),
+        hq_version: hqVersion,
+    };
+    const leasePath = path.join(directory, `${record.pid}-${record.start_time_ms}.json`);
+    const tempPath = `${leasePath}.${Math.random().toString(36).slice(2)}.tmp`;
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        process.removeListener("exit", releaseOnExit);
+        try {
+            rmSync(leasePath, { force: true });
+        }
+        catch (error) {
+            process.stderr.write(`hq-cli package-use lease release failed (${errorLabel(error)})\n`);
+        }
+    };
+    const releaseOnExit = () => release();
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        waitForUpdateRequest(requestPath, 30_000);
+        try {
+            writeFileSync(tempPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
+            renameSync(tempPath, leasePath);
+        }
+        catch (error) {
+            rmSync(tempPath, { force: true });
+            throw new Error(`Unable to publish the HQ CLI package-use lease (${errorLabel(error)})`, { cause: error });
+        }
+        if (!exists(requestPath)) {
+            process.once("exit", releaseOnExit);
+            return { leasePath, release };
+        }
+        rmSync(leasePath, { force: true });
+    }
+    throw new PackageUseUpdatePendingError("An HQ CLI update is waiting for the package lease; retry when it finishes");
+}
+function exists(file) {
+    try {
+        readFileSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function acquireCurrentPackageUseLease() {
+    const pkg = findCliPackage(path.dirname(fileURLToPath(import.meta.url)));
+    if (!pkg || isPnpmGlobal(pkg.root) || isBunGlobal(pkg.root))
+        return null;
+    const prefix = npmPrefix(pkg.root);
+    if (!prefix)
+        return null;
+    if (process.platform !== "win32") {
+        const parts = pkg.root.replace(/\\/g, "/").replace(/\/+$/, "").split("/").filter(Boolean);
+        const nodeModules = parts.lastIndexOf("node_modules");
+        if (nodeModules > 0 && parts[nodeModules - 1] !== "lib")
+            return null;
+    }
+    return acquirePackageUseLease(prefix, pkg.version);
+}
+/** True while the desktop updater owns the per-prefix update request. */
+export function currentPackageUseUpdateRequested() {
+    const pkg = findCliPackage(path.dirname(fileURLToPath(import.meta.url)));
+    if (!pkg || isPnpmGlobal(pkg.root) || isBunGlobal(pkg.root))
+        return false;
+    const prefix = npmPrefix(pkg.root);
+    if (!prefix)
+        return false;
+    return exists(packageUseUpdateRequestPath(prefix));
+}
+export const __test__ = {
+    waitForUpdateRequest,
+};
+//# sourceMappingURL=package-use-lease.js.map

package/package.json

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