@indigoai-us/hq-cli 5.106.3 → 5.107.0

package/dist/lib/doctor/checks/sync-health.js

@@ -0,0 +1,279 @@
+/**
+ * Versions & sync health — the doctor family the registry docblock always
+ * anticipated (client-sync-health-control-plane US-015).
+ *
+ * Reports, per install:
+ *   - the CLI / Core / desktop (hq-sync menubar) component versions, from the
+ *     same collectors the feedback and client-health paths use (US-003), so
+ *     `hq doctor --json` shows exactly what a heartbeat would report;
+ *   - whether a newer hq-core release is known to be available — read OFFLINE
+ *     from the cache stamped by the `check-hq-update` SessionStart hook
+ *     (`workspace/.hq-update-check/last-check.json`), never from the network,
+ *     preserving the doctor's offline contract (no cache → UNTESTED, not PASS);
+ *   - per-company sync journal staleness via the engine's `listJournals()` —
+ *     the ONLY correct enumeration of per-scope journal shards
+ *     (single-path reconstruction regressed before: feedback_9fbf1f82 /
+ *     feedback_46288b7b).
+ *
+ * Caution paid for in blood (bridge-health false positives): a machine with no
+ * journals at all is NA, not WARN — CLI-only installs never sync locally and
+ * must not read as degraded. Staleness warns only on a corroborated signal: a
+ * journal that EXISTS and carries a parseable, old `lastSync`.
+ *
+ * Every dependency is injectable so the family is unit-testable without an HQ
+ * tree, a state dir, or the wall clock.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { listJournals } from "@indigoai-us/hq-cloud";
+import { CLI_VERSION } from "../../../cli-version.js";
+import { readSyncVersion } from "../../../utils/feedback-versions.js";
+import { readHqVersion } from "../../../utils/pack-contributions.js";
+/** The id of the versions/sync family. */
+export const SYNC_FAMILY_ID = "sync";
+/** Human title for grouped output. */
+export const SYNC_FAMILY_TITLE = "Versions & sync";
+/**
+ * A journal shard older than this is reported stale. Seven days: long enough
+ * that a laptop shut over a weekend never warns, short enough that a silently
+ * dead sync runner surfaces well before data divergence becomes painful.
+ */
+export const STALE_JOURNAL_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
+/** The offline update cache written by the check-hq-update SessionStart hook. */
+export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "last-check.json");
+function defaultVersions(hqRoot) {
+    return {
+        cli: CLI_VERSION,
+        core: safeReadCore(hqRoot),
+        desktop: safeReadDesktop(),
+    };
+}
+function safeReadCore(hqRoot) {
+    try {
+        return readHqVersion(hqRoot);
+    }
+    catch {
+        return null;
+    }
+}
+function safeReadDesktop() {
+    try {
+        return readSyncVersion();
+    }
+    catch {
+        return null;
+    }
+}
+const DEFAULT_DEPS = {
+    versions: defaultVersions,
+    // Deliberately NOT wrapped in a try/catch: an enumeration failure must
+    // surface as UNKNOWN in `journalResults`, never be collapsed into the
+    // empty-list (NA, "cloud sync not in use") case. False healthy is worse
+    // than no check.
+    journals: () => listJournals(),
+    now: () => new Date(),
+};
+/** The versions/sync check family. Registered in `createDefaultRegistry`. */
+export const syncHealthFamily = {
+    id: SYNC_FAMILY_ID,
+    title: SYNC_FAMILY_TITLE,
+    run: (context) => Promise.resolve(checkSyncHealth(context)),
+};
+/** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
+export function checkSyncHealth(context, deps = DEFAULT_DEPS) {
+    try {
+        return [
+            ...versionResults(context, deps),
+            ...updateAvailabilityResult(context, deps),
+            ...journalResults(deps),
+        ];
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.error",
+                message: `versions/sync checks could not run: ${error.message}`,
+            },
+        ];
+    }
+}
+// ─── Component versions ──────────────────────────────────────────────────────
+function versionResults(context, deps) {
+    const versions = deps.versions(context.hqRoot);
+    const results = [
+        {
+            status: "PASS",
+            checkId: "sync.versions.cli",
+            message: `hq-cli ${versions.cli}.`,
+        },
+    ];
+    if (versions.core) {
+        results.push({
+            status: "PASS",
+            checkId: "sync.versions.core",
+            message: `hq-core ${versions.core} (core/core.yaml hqVersion).`,
+        });
+    }
+    else {
+        results.push({
+            status: "WARN",
+            checkId: "sync.versions.core",
+            target: path.join(context.hqRoot, "core", "core.yaml"),
+            message: "hq-core version could not be read from core/core.yaml — the scaffold may be missing or pre-v12.",
+            remediation: "Run /update-hq to (re)install the hq-core scaffold.",
+        });
+    }
+    // Desktop absence is NA, never WARN: hq-sync is optional (CLI-only and CI
+    // machines legitimately run without it), so "not installed" is not degraded.
+    results.push(versions.desktop
+        ? {
+            status: "PASS",
+            checkId: "sync.versions.desktop",
+            message: `hq-sync desktop ${versions.desktop} (~/.hq/sync-version.json).`,
+        }
+        : {
+            status: "NA",
+            checkId: "sync.versions.desktop",
+            message: "hq-sync desktop app not detected (~/.hq/sync-version.json absent) — not required on CLI-only installs.",
+        });
+    return results;
+}
+// ─── Update availability (offline, from the SessionStart hook's cache) ───────
+function updateAvailabilityResult(context, deps) {
+    const cachePath = path.join(context.hqRoot, UPDATE_CACHE_RELPATH);
+    let latest = null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+        const value = parsed?.latest;
+        if (typeof value === "string" && /^\d+\.\d+\.\d+$/.test(value)) {
+            latest = value;
+        }
+    }
+    catch {
+        // Missing or malformed cache: fall through to UNTESTED.
+    }
+    if (!latest) {
+        return [
+            {
+                status: "UNTESTED",
+                checkId: "sync.update.core",
+                target: cachePath,
+                message: "Latest hq-core release unknown — no update-check cache yet (written by the check-hq-update SessionStart hook; the doctor never goes to the network for it).",
+            },
+        ];
+    }
+    const core = deps.versions(context.hqRoot).core;
+    if (!core) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.update.core",
+                message: `Latest hq-core release is v${latest}, but the local core version could not be read to compare.`,
+            },
+        ];
+    }
+    if (semverGt(latest, core)) {
+        return [
+            {
+                status: "WARN",
+                checkId: "sync.update.core",
+                message: `hq-core update available: local v${core}, latest v${latest}.`,
+                remediation: "Run /update-hq in a fresh session to upgrade.",
+            },
+        ];
+    }
+    return [
+        {
+            status: "PASS",
+            checkId: "sync.update.core",
+            message: `hq-core is up to date (local v${core}, latest known v${latest}).`,
+        },
+    ];
+}
+/** True when `a` > `b` for plain X.Y.Z versions. Non-numeric parts compare 0. */
+export function semverGt(a, b) {
+    const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da !== db)
+            return da > db;
+    }
+    return false;
+}
+// ─── Per-journal staleness ───────────────────────────────────────────────────
+function journalResults(deps) {
+    // Enumeration failure (throw / IO error) is UNKNOWN — which FAILS per the
+    // doctor's exit-code contract — never NA: a broken or unreadable journal
+    // store must not read as "cloud sync not in use" (a false healthy). Only a
+    // SUCCESSFUL enumeration that finds nothing is the benign CLI-only case.
+    let journals;
+    try {
+        journals = deps.journals();
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.journals",
+                message: `Sync journal enumeration failed: ${error instanceof Error ? error.message : String(error)}`,
+                remediation: "Check that the HQ state directory is readable, then re-run `hq doctor`.",
+            },
+        ];
+    }
+    // No journals is NA, never WARN: a CLI-only install has nothing to sync
+    // locally and must not read as degraded (bridge-health false-positive
+    // lesson — warn only on corroborated signals).
+    if (journals.length === 0) {
+        return [
+            {
+                status: "NA",
+                checkId: "sync.journals",
+                message: "No local sync journals found — HQ cloud sync is not in use on this machine.",
+            },
+        ];
+    }
+    const nowMs = deps.now().getTime();
+    return journals.map((entry) => {
+        const lastSync = entry.journal?.lastSync;
+        const checkId = `sync.journal.${entry.slug}`;
+        if (typeof lastSync !== "string" || lastSync.length === 0) {
+            return {
+                status: "WARN",
+                checkId,
+                target: entry.path,
+                message: `Sync journal '${entry.slug}' exists but has never recorded a successful sync.`,
+                remediation: "Run /hq-sync (or `hq sync`) to complete a first sync.",
+            };
+        }
+        const parsed = Date.parse(lastSync);
+        if (!Number.isFinite(parsed)) {
+            return {
+                status: "UNKNOWN",
+                checkId,
+                target: entry.path,
+                message: `Sync journal '${entry.slug}' has an unparseable lastSync (${lastSync}).`,
+            };
+        }
+        const ageMs = nowMs - parsed;
+        if (ageMs > STALE_JOURNAL_THRESHOLD_MS) {
+            const days = Math.floor(ageMs / 86_400_000);
+            return {
+                status: "WARN",
+                checkId,
+                target: entry.path,
+                message: `Sync journal '${entry.slug}' is stale: last successful sync ${days} day${days === 1 ? "" : "s"} ago (${lastSync}).`,
+                remediation: "Run /hq-sync (or `hq sync`) and check the sync runner.",
+            };
+        }
+        return {
+            status: "PASS",
+            checkId,
+            target: entry.path,
+            message: `Sync journal '${entry.slug}' is fresh (last sync ${lastSync}).`,
+        };
+    });
+}
+//# sourceMappingURL=sync-health.js.map

package/dist/lib/doctor/registry.js

@@ -20,6 +20,7 @@ import { checkGrokWiring } from "./checks/grok-wiring.js";
 import { checkRuntimeProbe } from "./checks/runtime-probe.js";
 import { runtimeHealthFamily } from "./checks/runtime-health.js";
 import { integrationsFamily } from "./checks/integrations.js";
+import { syncHealthFamily } from "./checks/sync-health.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -181,6 +182,11 @@ export function createDefaultRegistry() {
     // The engine remains family-agnostic: integrations is one bounded,
     // read-only inventory family, registered alongside all other checks.
     registry.register(integrationsFamily);
+    // Versions & sync (US-015): CLI/Core/desktop component versions, offline
+    // update availability, and per-company sync journal staleness — the family
+    // this registry's docblock always anticipated. Local-only reads, so the
+    // doctor's offline contract is preserved.
+    registry.register(syncHealthFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/main.js

@@ -90,6 +90,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
@@ -289,7 +290,12 @@ registerDoctorCommand(program);
 // from `hq doctor` (hook guardrails). Does not start MQTT listen.
 registerMeshCommand(program);
 program.hook("preAction", async () => {
-    await emitCliSessionStarted();
+    // Both are best-effort, bounded (1.2s), and fully swallowed: neither can
+    // delay past its bound or change the command's result or exit code.
+    await Promise.all([
+        emitCliSessionStarted(),
+        reportCliClientHealthInvocation(),
+    ]);
 });
 export async function runCli() {
     // Set when a self-update re-exec'd this command on a newer CLI: the child

package/dist/utils/client-health-contract.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Client-health wire contract (client-sync-health-control-plane US-000).
+ *
+ * ONE versioned contract shared in spirit across four adapters:
+ *
+ *   - hq-pro            src/sync/server/client-health-contract.ts   (reference)
+ *   - hq-desktop-app    crates/hq-desktop-core/src/client_health.rs
+ *   - hq-cli            src/utils/client-health-contract.ts         (this file)
+ *   - indigo-gtm-hq     src/lib/client-health.ts
+ *
+ * Every adapter uses the SAME field names and the SAME enum values, verified
+ * per-repo against byte-equivalent canonical fixtures (here embedded in
+ * src/utils/client-health-contract.test.ts). The interface, not repository
+ * internals, is the shared test surface.
+ *
+ * Design rules (PRD notes + securityNotes):
+ *
+ *   - ADDITIVE + tolerant of older clients: every non-identity field is
+ *     optional-friendly, and unknown EXTRA fields are ignored (a newer client
+ *     talking to an older server must not fail). Absence of `updaterState`
+ *     means "an older client that never reported it"; the closed value
+ *     "unchecked" means "the updater has not run yet" — the two are distinct
+ *     and must survive the wire.
+ *   - FAIL CLOSED on values: enums are closed sets. Free-form shell text,
+ *     customer file paths, secret-shaped values, raw logs, and unknown repair
+ *     kinds are rejected with a typed {@link ClientHealthContractError}.
+ *   - Device identity: clients send only the stable random `installationId`.
+ *     HMAC'ing of device identifiers happens server-side (US-001, modeled on
+ *     scope-sync-mode-repository.ts) and never crosses this wire contract.
+ *   - Monotonic `sequence`: the server keeps the highest sequence seen per
+ *     installation and drops older/replayed heartbeats
+ *     ({@link shouldApplyHeartbeat}).
+ */
+export declare const CLIENT_HEALTH_CONTRACT_VERSION = 1;
+export declare const CLIENT_HEALTH_PLATFORMS: readonly ["macos", "windows", "linux"];
+export type ClientHealthPlatform = (typeof CLIENT_HEALTH_PLATFORMS)[number];
+export declare const CLIENT_HEALTH_ARCHS: readonly ["x64", "arm64"];
+export type ClientHealthArch = (typeof CLIENT_HEALTH_ARCHS)[number];
+/** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
+export declare const CLIENT_HEALTH_SOURCES: readonly ["desktop", "cli"];
+export type ClientHealthSource = (typeof CLIENT_HEALTH_SOURCES)[number];
+/**
+ * Current sync state of the installation. `paused` and `conflict_blocked` are
+ * first-class states (not failures folded into `error`) because support treats
+ * them differently: pause may be intentional and conflicts are user-owned.
+ */
+export declare const CLIENT_HEALTH_SYNC_STATES: readonly ["idle", "syncing", "paused", "conflict_blocked", "error", "never_synced"];
+export type ClientHealthSyncState = (typeof CLIENT_HEALTH_SYNC_STATES)[number];
+/**
+ * Updater state. ABSENCE of the field means the client is too old to report
+ * it; `"unchecked"` means the updater exists but has not checked yet. Do not
+ * collapse the two (US-000 acceptance: Unchecked vs Absent must survive).
+ */
+export declare const CLIENT_HEALTH_UPDATER_STATES: readonly ["unchecked", "up_to_date", "update_available", "update_downloading", "update_ready", "update_failed", "unsupported"];
+export type ClientHealthUpdaterState = (typeof CLIENT_HEALTH_UPDATER_STATES)[number];
+/** Closed failure/blocker reason codes — the ONLY reasons that cross the wire. */
+export declare const CLIENT_HEALTH_FAILURE_REASONS: readonly ["SYNC_PAUSED", "CONFLICT_BLOCKED", "DESKTOP_OUTDATED", "CLI_OUTDATED", "CORE_OUTDATED", "AUTH_EXPIRED", "UPDATE_FAILED", "RUNNER_FAILED", "PERMISSION_DENIED", "DISK_FULL", "HEARTBEAT_STALE"];
+export type ClientHealthFailureReason = (typeof CLIENT_HEALTH_FAILURE_REASONS)[number];
+/**
+ * Repair/diagnostic command allowlist (US-006/US-009 consume these shapes).
+ * A desired-state interface, never a remote shell — any kind outside this set
+ * fails closed.
+ */
+export declare const CLIENT_HEALTH_REPAIR_KINDS: readonly ["CHECK_NOW", "RETRY_SYNC", "RESUME_SYNC", "REPAIR_CLI", "UPDATE_CORE", "APPLY_DESKTOP_UPDATE", "RESTART_APP"];
+export type ClientHealthRepairKind = (typeof CLIENT_HEALTH_REPAIR_KINDS)[number];
+/** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
+export declare const CLIENT_HEALTH_COMMAND_STATES: readonly ["queued", "acknowledged", "running", "succeeded", "failed", "expired"];
+export type ClientHealthCommandState = (typeof CLIENT_HEALTH_COMMAND_STATES)[number];
+/** Closed diagnostic probe identifiers (US-007). */
+export declare const CLIENT_HEALTH_DIAGNOSTIC_CHECKS: readonly ["auth", "runner", "cli", "core", "updater", "sync", "conflicts", "storage", "permissions"];
+export type ClientHealthDiagnosticCheck = (typeof CLIENT_HEALTH_DIAGNOSTIC_CHECKS)[number];
+export declare const CLIENT_HEALTH_CHECK_STATUSES: readonly ["pass", "fail", "skip"];
+export type ClientHealthCheckStatus = (typeof CLIENT_HEALTH_CHECK_STATUSES)[number];
+export declare const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
+export declare const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100000;
+export declare const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100000;
+export declare const CLIENT_HEALTH_MAX_CHECKS = 16;
+/**
+ * The four client versions. All optional: a CLI-only installation has no
+ * desktop/syncRunner version, and older clients may omit any of them.
+ */
+export interface ClientHealthVersions {
+    desktop?: string;
+    cli?: string;
+    core?: string;
+    syncRunner?: string;
+}
+export interface ClientHealthHeartbeat {
+    contractVersion: number;
+    /** Stable random installation identity — NOT a hardware fingerprint. */
+    installationId: string;
+    source: ClientHealthSource;
+    platform: ClientHealthPlatform;
+    arch: ClientHealthArch;
+    /** Client-side emit time (liveness); the server also stamps receive time. */
+    sentAt: string;
+    /** Monotonic per-installation sequence — older/replayed values never overwrite newer state. */
+    sequence: number;
+    versions: ClientHealthVersions;
+    syncState: ClientHealthSyncState;
+    /** Last time a sync RUN started — distinct from success. */
+    lastSyncAttemptAt?: string;
+    /** Advances only on genuine success (including no-change runs). */
+    lastSyncSuccessAt?: string;
+    consecutiveFailures: number;
+    conflictCount?: number;
+    updaterState?: ClientHealthUpdaterState;
+    failureReason?: ClientHealthFailureReason;
+}
+export interface ClientHealthCheckResult {
+    check: ClientHealthDiagnosticCheck;
+    status: ClientHealthCheckStatus;
+    /** Present only on `fail` — a closed reason code, never prose. */
+    reason?: ClientHealthFailureReason;
+}
+/**
+ * Receipt for a diagnostic or repair command (US-006+ store these). `checks`
+ * is only meaningful for `CHECK_NOW`.
+ */
+export interface ClientHealthCommandReceipt {
+    contractVersion: number;
+    commandId: string;
+    installationId: string;
+    kind: ClientHealthRepairKind;
+    state: ClientHealthCommandState;
+    /** Monotonic per-command revision — out-of-order receipt updates fail closed downstream. */
+    revision: number;
+    occurredAt: string;
+    checks?: ClientHealthCheckResult[];
+    failureReason?: ClientHealthFailureReason;
+}
+export type ClientHealthContractErrorCode = "MISSING_FIELD" | "INVALID_TYPE" | "UNKNOWN_ENUM_VALUE" | "UNSAFE_VALUE" | "OUT_OF_BOUNDS" | "UNSUPPORTED_CONTRACT_VERSION";
+export declare class ClientHealthContractError extends Error {
+    readonly code: ClientHealthContractErrorCode;
+    readonly field: string;
+    constructor(code: ClientHealthContractErrorCode, field: string, detail?: string);
+}
+/**
+ * Parse + validate one heartbeat. Unknown extra fields are ignored (additive
+ * tolerance); every consumed value fails closed on unsafe content.
+ */
+export declare function parseClientHealthHeartbeat(input: unknown): ClientHealthHeartbeat;
+/** Parse + validate one diagnostic/repair command receipt. Unknown kinds fail closed. */
+export declare function parseClientHealthCommandReceipt(input: unknown): ClientHealthCommandReceipt;
+/**
+ * True when an incoming heartbeat sequence may replace the stored snapshot.
+ * Equal or older sequences are late deliveries/replays: drop them (the server
+ * answers idempotently and the current snapshot remains unchanged).
+ */
+export declare function shouldApplyHeartbeat(storedSequence: number | undefined, incomingSequence: number): boolean;
+//# sourceMappingURL=client-health-contract.d.ts.map