@indigoai-us/hq-cli 5.294.0 → 5.295.0

package/dist/lib/doctor/client-health-sentry.js

@@ -1,286 +0,0 @@
-import { randomUUID as cryptoRandomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { CLI_VERSION } from "../../cli-version.js";
-import { readSyncVersion } from "../../utils/feedback-versions.js";
-import { readHqVersion } from "../../utils/pack-contributions.js";
-export const CLIENT_HEALTH_SENTRY_NOT_HANDLED_EXIT_CODE = 10;
-export const CLIENT_HEALTH_SENTRY_MAX_INPUT_BYTES = 2 * 1024 * 1024;
-export const CLIENT_HEALTH_SENTRY_MAX_FINDINGS = 250;
-export const CLIENT_HEALTH_INSTALL_ID_FILENAME = "install-id";
-export const CLIENT_HEALTH_LAST_RESULT_FILENAME = "last-result.json";
-const STATE_DIRECTORY = path.join("workspace", ".hq-client-health");
-const REASON_CODES = new Set([
-    "core-version-unavailable",
-    "core-update-available",
-    "no-local-tree",
-    "never-synced",
-    "invalid-last-sync",
-    "stale-threshold",
-    "manifest-unavailable",
-    "manifest-state-unavailable",
-    "no-manifest-scopes",
-    "never-uploaded",
-    "invalid-upload-time",
-    "unresolved-company-uid",
-    "realtime-lag-stuck",
-    "receiver-permission-denied",
-    "runner-restart-loop",
-    "device-limit-backoff",
-    "repeated-conflicts",
-]);
-const FIX_OUTCOMES = new Set(["not_auto_fixable", "fix_failed", "fix_timed_out"]);
-const INSTALL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-const VERSION = /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?$/;
-const PLATFORMS = new Set([
-    "aix", "android", "darwin", "freebsd", "haiku", "linux", "openbsd",
-    "sunos", "win32", "cygwin",
-]);
-const ARCHITECTURES = new Set([
-    "arm", "arm64", "ia32", "loong64", "mips", "mipsel", "ppc", "ppc64",
-    "riscv64", "s390x", "x64",
-]);
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function cleanVersion(value) {
-    return value && VERSION.test(value) ? value : "unknown";
-}
-function cleanPlatform(value) {
-    return PLATFORMS.has(value) ? value : "unknown";
-}
-function cleanArchitecture(value) {
-    return ARCHITECTURES.has(value) ? value : "unknown";
-}
-/** Collapse company-specific doctor ids before any value can enter a Sentry event. */
-export function normalizeClientHealthCheckId(checkId) {
-    if (checkId === "sync.update.core")
-        return checkId;
-    if (checkId === "sync.runtime" || checkId.startsWith("sync.runtime."))
-        return "sync.runtime";
-    if (checkId === "sync.journal.__hq_personal_vault__")
-        return "sync.journal.personal_vault";
-    if (checkId === "sync.manifest.__hq_personal_vault__")
-        return "sync.manifest.personal_vault";
-    const match = /^sync\.(journal|manifest)\.([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/.exec(checkId);
-    if (!match)
-        return "other";
-    const family = match[1];
-    const scope = match[2];
-    if (scope === "personal")
-        return `sync.${family}.personal`;
-    if (family === "manifest" && scope.startsWith("unresolved."))
-        return "other";
-    return `sync.${family}.company`;
-}
-function companySlugForCheck(checkId, checkClass) {
-    if (checkClass !== "sync.journal.company" && checkClass !== "sync.manifest.company") {
-        return null;
-    }
-    const match = /^sync\.(?:journal|manifest)\.([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/.exec(checkId);
-    return match?.[1] ?? null;
-}
-function safeReasonCode(value) {
-    return typeof value === "string" && REASON_CODES.has(value) ? value : "none";
-}
-function safeFixOutcome(value) {
-    return FIX_OUTCOMES.has(value) ? value : "not_auto_fixable";
-}
-/** Keep only the doctor fields needed for safe health reporting. */
-export function parseClientHealthDoctorFindings(input) {
-    if (Buffer.byteLength(input, "utf8") > CLIENT_HEALTH_SENTRY_MAX_INPUT_BYTES) {
-        throw new Error("Client health doctor input exceeds its size limit");
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(input);
-    }
-    catch {
-        throw new Error("Client health doctor input is invalid JSON");
-    }
-    if (!isRecord(parsed) || !Array.isArray(parsed.results)) {
-        throw new Error("Client health doctor input has no results array");
-    }
-    const findings = [];
-    for (const value of parsed.results) {
-        if (!isRecord(value) || value.family !== "sync")
-            continue;
-        if (value.status !== "FAIL" && value.status !== "WARN")
-            continue;
-        if (value.checkId === "sync.update.core" && value.status === "WARN")
-            continue;
-        const checkId = typeof value.checkId === "string" &&
-            /^sync\.[A-Za-z0-9._-]{1,160}$/.test(value.checkId)
-            ? value.checkId
-            : "unknown";
-        const checkClass = normalizeClientHealthCheckId(checkId);
-        findings.push({
-            checkClass,
-            companySlug: companySlugForCheck(checkId, checkClass),
-            reasonCode: safeReasonCode(value.reasonCode),
-            status: value.status,
-        });
-        if (findings.length > CLIENT_HEALTH_SENTRY_MAX_FINDINGS) {
-            throw new Error("Client health doctor input has too many sync findings");
-        }
-    }
-    return findings;
-}
-function defaultVersions(hqRoot) {
-    let core;
-    try {
-        core = readHqVersion(hqRoot);
-    }
-    catch {
-        core = null;
-    }
-    let sync;
-    try {
-        sync = readSyncVersion();
-    }
-    catch {
-        sync = null;
-    }
-    return { cli: CLI_VERSION, core, sync };
-}
-function stateDirectory(hqRoot) {
-    const root = fs.realpathSync(hqRoot);
-    const workspacePath = path.join(root, "workspace");
-    fs.mkdirSync(workspacePath, { recursive: true, mode: 0o700 });
-    const workspaceStat = fs.lstatSync(workspacePath);
-    if (!workspaceStat.isDirectory() || workspaceStat.isSymbolicLink()) {
-        throw new Error("Client health state workspace is not a local directory");
-    }
-    const directory = path.join(root, STATE_DIRECTORY);
-    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-    const directoryStat = fs.lstatSync(directory);
-    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
-        throw new Error("Client health state directory is not a local directory");
-    }
-    fs.chmodSync(directory, 0o700);
-    return directory;
-}
-function readInstallId(filePath) {
-    try {
-        const fileStat = fs.lstatSync(filePath);
-        if (!fileStat.isFile() || fileStat.isSymbolicLink()) {
-            throw new Error("Client health install id is not a regular local file");
-        }
-        const value = fs.readFileSync(filePath, "utf8").trim();
-        if (!INSTALL_ID.test(value))
-            throw new Error("Client health install id is invalid");
-        fs.chmodSync(filePath, 0o600);
-        return value;
-    }
-    catch (error) {
-        if (isRecord(error) && error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-}
-/** Store a random UUID once per local HQ install, without using host identity. */
-export function getOrCreateClientHealthInstallId(hqRoot, randomUUID = cryptoRandomUUID) {
-    const directory = stateDirectory(hqRoot);
-    const filePath = path.join(directory, CLIENT_HEALTH_INSTALL_ID_FILENAME);
-    const current = readInstallId(filePath);
-    if (current)
-        return current;
-    const candidate = randomUUID();
-    if (!INSTALL_ID.test(candidate))
-        throw new Error("Client health random id source returned an invalid id");
-    try {
-        fs.writeFileSync(filePath, `${candidate}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
-        return candidate;
-    }
-    catch (error) {
-        if (!isRecord(error) || error.code !== "EEXIST")
-            throw error;
-        const raced = readInstallId(filePath);
-        if (!raced)
-            throw new Error("Client health install id was not created");
-        return raced;
-    }
-}
-function nextStep(checkClass) {
-    switch (checkClass) {
-        case "sync.update.core":
-            return "HQ couldn't update itself automatically. Run `hq update` or `/update-hq`, then restart this session.";
-        case "sync.journal.personal":
-        case "sync.journal.personal_vault":
-            return "HQ hasn't synced your personal files in over 7 days and the automatic fix did not work. Run `hq sync` and check the result. If it fails, run `hq doctor` and send the output to support.";
-        case "sync.journal.company":
-            return "HQ hasn't synced this company's files in over 7 days and the automatic fix did not work. Run `hq sync` and check the result. If it fails, run `hq doctor` and send the output to support.";
-        case "sync.manifest.personal":
-        case "sync.manifest.personal_vault":
-            return "HQ couldn't read your personal sync list. Run `hq doctor --fix`. If it still fails, run `hq login` again.";
-        case "sync.manifest.company":
-            return "HQ couldn't read a company sync manifest. Run `hq doctor --fix`. If it still fails, run `hq login` again.";
-        default:
-            return "HQ still reports a sync health issue after its automatic fix. Run `hq doctor` and send the output to support.";
-    }
-}
-function writeLastResult(hqRoot, finding, outcome, randomUUID) {
-    const directory = stateDirectory(hqRoot);
-    const result = {
-        check_class: finding.checkClass,
-        outcome,
-        next_step: nextStep(finding.checkClass),
-        result_id: randomUUID(),
-    };
-    if (!INSTALL_ID.test(result.result_id))
-        throw new Error("Client health result id source returned an invalid id");
-    const filePath = path.join(directory, CLIENT_HEALTH_LAST_RESULT_FILENAME);
-    const tempPath = path.join(directory, `${CLIENT_HEALTH_LAST_RESULT_FILENAME}.${result.result_id}.tmp`);
-    fs.writeFileSync(tempPath, `${JSON.stringify(result, null, 2)}\n`, {
-        encoding: "utf8",
-        flag: "wx",
-        mode: 0o600,
-    });
-    fs.renameSync(tempPath, filePath);
-    return result;
-}
-function buildEvent(finding, installId, outcome, failingCount, versions, platform, arch) {
-    const reasonCode = finding.reasonCode;
-    return {
-        message: `Client health: ${finding.checkClass} unresolved after hq doctor --fix`,
-        level: "warning",
-        fingerprint: ["client-health", finding.checkClass, reasonCode],
-        tags: {
-            check_class: finding.checkClass,
-            reason_code: reasonCode,
-            fix_outcome: outcome,
-            status: finding.status,
-            failing_check_count: String(failingCount),
-            cli_version: cleanVersion(versions.cli),
-            core_version: cleanVersion(versions.core),
-            sync_version: cleanVersion(versions.sync),
-            platform: cleanPlatform(platform),
-            arch: cleanArchitecture(arch),
-        },
-        user: { id: installId, ip_address: null },
-    };
-}
-/**
- * Report only after every finding's company has opted in. A mixed rollout
- * falls back as one batch so the old path cannot duplicate partially sent rows.
- */
-export async function handleClientHealthSentryReport(input, dependencies) {
-    const findings = parseClientHealthDoctorFindings(input.doctorJson);
-    if (findings.length === 0)
-        return "handled";
-    const outcome = safeFixOutcome(input.fixOutcome);
-    const companySlugs = [...new Set(findings.map((finding) => finding.companySlug))];
-    const enabled = await Promise.all(companySlugs.map((companySlug) => dependencies.resolveFlagForCompany(companySlug)));
-    if (enabled.some((value) => value !== true))
-        return "not_handled";
-    const randomUUID = dependencies.randomUUID ?? cryptoRandomUUID;
-    const installId = getOrCreateClientHealthInstallId(input.hqRoot, randomUUID);
-    const versions = (dependencies.versions ?? defaultVersions)(input.hqRoot);
-    const events = findings.map((finding) => buildEvent(finding, installId, outcome, findings.length, versions, cleanPlatform((dependencies.platform ?? (() => process.platform))()), cleanArchitecture((dependencies.arch ?? os.arch)())));
-    writeLastResult(input.hqRoot, findings[0], outcome, randomUUID);
-    if (!(await dependencies.sendEvents(events)))
-        return "send_failed";
-    return "handled";
-}
-//# sourceMappingURL=client-health-sentry.js.map

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

@@ -1,26 +0,0 @@
-export declare const OUTPOST_SNAPSHOT_CACHE_TTL_MS = 3000;
-export declare const OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS = 45000;
-export interface OutpostSnapshotCachePolicy {
-    ttlMs?: number;
-    staleLockMs?: number;
-    lockWaitMs?: number;
-    pollMs?: number;
-    now?: () => number;
-    sleep?: (ms: number) => Promise<void>;
-    acquireLock?: (lockPath: string, token: string, nowMs: number) => void;
-}
-/** Deduplicates identical remote snapshot queries within one command invocation. */
-export declare class OutpostSnapshotInvocationMemo {
-    private readonly requests;
-    getOrCreate<T>(outpostId: string, query: unknown, fetch: () => Promise<T>): Promise<T>;
-}
-export declare function outpostLaneListSnapshotKey(outpostId: string, normalizedQuery: unknown): string;
-export declare function outpostSnapshotCachePath(hqRoot: string, key: string): string;
-export declare function getOrFetchOutpostSnapshot<T>(input: {
-    hqRoot: string;
-    key: string;
-    isValue: (value: unknown) => value is T;
-    fetch: () => Promise<T>;
-    policy?: OutpostSnapshotCachePolicy;
-}): Promise<T>;
-//# sourceMappingURL=outpost-snapshot-cache.d.ts.map

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

@@ -1,215 +0,0 @@
-import { createHash, randomBytes } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { LanesError } from "./errors.js";
-export const OUTPOST_SNAPSHOT_CACHE_TTL_MS = 3_000;
-export const OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS = 45_000;
-const CACHE_RELATIVE_PATH = path.join("workspace", "lanes-runs", ".cache", "outpost-snapshots");
-const CACHE_SCHEMA_VERSION = "hq-lanes-outpost-snapshot-cache.v1";
-const LOCK_POLL_MS = 20;
-const LOCK_WAIT_MS = 60_000;
-/** Deduplicates identical remote snapshot queries within one command invocation. */
-export class OutpostSnapshotInvocationMemo {
-    requests = new Map();
-    getOrCreate(outpostId, query, fetch) {
-        const key = JSON.stringify([outpostId, query]);
-        const existing = this.requests.get(key);
-        if (existing)
-            return existing;
-        const request = fetch();
-        this.requests.set(key, request);
-        return request;
-    }
-}
-export function outpostLaneListSnapshotKey(outpostId, normalizedQuery) {
-    return JSON.stringify(["lane-list", outpostId, normalizedQuery]);
-}
-export function outpostSnapshotCachePath(hqRoot, key) {
-    const digest = createKeyDigest(key);
-    return path.join(hqRoot, CACHE_RELATIVE_PATH, `${digest}.json`);
-}
-export async function getOrFetchOutpostSnapshot(input) {
-    const policy = input.policy ?? {};
-    const now = policy.now ?? Date.now;
-    const ttlMs = policy.ttlMs ?? OUTPOST_SNAPSHOT_CACHE_TTL_MS;
-    const staleLockMs = policy.staleLockMs ?? OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS;
-    const lockWaitMs = policy.lockWaitMs ?? LOCK_WAIT_MS;
-    const pollMs = policy.pollMs ?? LOCK_POLL_MS;
-    const sleep = policy.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-    const filePath = outpostSnapshotCachePath(input.hqRoot, input.key);
-    const cached = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
-    if (cached !== undefined)
-        return cached;
-    const lockPath = `${filePath}.lock`;
-    const token = `${process.pid}:${randomBytes(12).toString("hex")}`;
-    const startedAt = now();
-    const acquireLock = policy.acquireLock ?? createCacheLock;
-    while (true) {
-        try {
-            acquireLock(lockPath, token, now());
-            break;
-        }
-        catch (err) {
-            const code = err.code;
-            if (code !== "EEXIST") {
-                process.stderr.write(`${JSON.stringify({
-                    event: "lanes.outpost_snapshot_cache_lock_unavailable",
-                    error: typeof code === "string" ? code : "UnknownError",
-                    fallback: "uncached",
-                })}\n`);
-                const value = await input.fetch();
-                if (!input.isValue(value)) {
-                    throw new LanesError("outpost_snapshot_cache_value_invalid", "Outpost snapshot fetch returned an invalid value", { key: input.key });
-                }
-                return value;
-            }
-            if (recoverStaleLock(lockPath, staleLockMs, now()))
-                continue;
-            const afterWait = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
-            if (afterWait !== undefined)
-                return afterWait;
-            if (now() - startedAt >= lockWaitMs) {
-                throw new LanesError("outpost_snapshot_cache_lock_timeout", "Timed out waiting for an Outpost snapshot refresh", { path: lockPath });
-            }
-            await sleep(pollMs);
-        }
-    }
-    try {
-        const afterLock = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
-        if (afterLock !== undefined)
-            return afterLock;
-        const value = await input.fetch();
-        if (!input.isValue(value)) {
-            throw new LanesError("outpost_snapshot_cache_value_invalid", "Outpost snapshot fetch returned an invalid value", { key: input.key });
-        }
-        writeCache(filePath, input.key, value, now());
-        return value;
-    }
-    finally {
-        releaseLock(lockPath, token);
-    }
-}
-function createCacheLock(lockPath, token, nowMs) {
-    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-    const lockFd = fs.openSync(lockPath, "wx", 0o600);
-    try {
-        fs.writeSync(lockFd, `${token}\n${nowMs}\n`);
-    }
-    catch (err) {
-        try {
-            fs.closeSync(lockFd);
-        }
-        catch (closeErr) {
-            process.stderr.write(`lanes snapshot cache: lock close failed: ${errorText(closeErr)}\n`);
-        }
-        releaseLock(lockPath, token);
-        throw err;
-    }
-    fs.closeSync(lockFd);
-}
-function createKeyDigest(key) {
-    // A lane-list query can contain lane ids. Keep raw ids out of cache filenames.
-    return createHash("sha256").update(key).digest("hex");
-}
-function readFreshCache(filePath, key, nowMs, ttlMs, isValue) {
-    let contents;
-    try {
-        contents = fs.readFileSync(filePath, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return undefined;
-        process.stderr.write(`lanes snapshot cache: read failed: ${errorText(err)}\n`);
-        return undefined;
-    }
-    let raw;
-    try {
-        raw = JSON.parse(contents);
-    }
-    catch (err) {
-        process.stderr.write(`lanes snapshot cache: ignoring malformed cache: ${errorText(err)}\n`);
-        return undefined;
-    }
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-        return undefined;
-    const entry = raw;
-    if (Object.keys(entry).length !== 4 ||
-        entry.schema_version !== CACHE_SCHEMA_VERSION ||
-        entry.key !== key ||
-        !Number.isSafeInteger(entry.cached_at) ||
-        entry.cached_at > nowMs ||
-        nowMs - entry.cached_at >= ttlMs ||
-        !isValue(entry.value))
-        return undefined;
-    return entry.value;
-}
-function writeCache(filePath, key, value, nowMs) {
-    const temporaryPath = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
-    try {
-        const fd = fs.openSync(temporaryPath, "wx", 0o600);
-        try {
-            fs.writeFileSync(fd, `${JSON.stringify({
-                schema_version: CACHE_SCHEMA_VERSION,
-                key,
-                cached_at: nowMs,
-                value,
-            })}\n`);
-            fs.fsyncSync(fd);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        fs.renameSync(temporaryPath, filePath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(temporaryPath);
-        }
-        catch (cleanupErr) {
-            if (cleanupErr.code !== "ENOENT") {
-                process.stderr.write(`lanes snapshot cache: temp cleanup failed: ${errorText(cleanupErr)}\n`);
-            }
-        }
-        // The cache is an optimization; a successful, validated remote result stays usable.
-        process.stderr.write(`lanes snapshot cache: write failed: ${errorText(err)}\n`);
-    }
-}
-function recoverStaleLock(lockPath, staleLockMs, nowMs) {
-    let stat;
-    try {
-        stat = fs.statSync(lockPath);
-    }
-    catch (err) {
-        return err.code === "ENOENT";
-    }
-    if (nowMs - stat.mtimeMs <= staleLockMs)
-        return false;
-    const stalePath = `${lockPath}.stale.${process.pid}.${randomBytes(6).toString("hex")}`;
-    try {
-        fs.renameSync(lockPath, stalePath);
-        fs.unlinkSync(stalePath);
-        return true;
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === "ENOENT")
-            return true;
-        throw new LanesError("outpost_snapshot_cache_lock_recovery_failed", `Could not recover a stale Outpost snapshot lock: ${errorText(err)}`, { path: lockPath });
-    }
-}
-function releaseLock(lockPath, token) {
-    try {
-        const contents = fs.readFileSync(lockPath, "utf8");
-        if (contents.split("\n", 1)[0] === token)
-            fs.unlinkSync(lockPath);
-    }
-    catch (err) {
-        if (err.code !== "ENOENT") {
-            process.stderr.write(`lanes snapshot cache: lock release failed: ${errorText(err)}\n`);
-        }
-    }
-}
-function errorText(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-//# sourceMappingURL=outpost-snapshot-cache.js.map

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

@@ -1,21 +0,0 @@
-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