@indigoai-us/hq-cli 5.106.3 → 5.107.0

package/dist/utils/client-health-contract.js

@@ -0,0 +1,306 @@
+/**
+ * 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}).
+ */
+// ─── Contract version ────────────────────────────────────────────────────────
+export const CLIENT_HEALTH_CONTRACT_VERSION = 1;
+// ─── Closed enums ────────────────────────────────────────────────────────────
+export const CLIENT_HEALTH_PLATFORMS = ["macos", "windows", "linux"];
+export const CLIENT_HEALTH_ARCHS = ["x64", "arm64"];
+/** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
+export const CLIENT_HEALTH_SOURCES = ["desktop", "cli"];
+/**
+ * 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 const CLIENT_HEALTH_SYNC_STATES = [
+    "idle",
+    "syncing",
+    "paused",
+    "conflict_blocked",
+    "error",
+    "never_synced",
+];
+/**
+ * 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 const CLIENT_HEALTH_UPDATER_STATES = [
+    "unchecked",
+    "up_to_date",
+    "update_available",
+    "update_downloading",
+    "update_ready",
+    "update_failed",
+    "unsupported",
+];
+/** Closed failure/blocker reason codes — the ONLY reasons that cross the wire. */
+export const CLIENT_HEALTH_FAILURE_REASONS = [
+    "SYNC_PAUSED",
+    "CONFLICT_BLOCKED",
+    "DESKTOP_OUTDATED",
+    "CLI_OUTDATED",
+    "CORE_OUTDATED",
+    "AUTH_EXPIRED",
+    "UPDATE_FAILED",
+    "RUNNER_FAILED",
+    "PERMISSION_DENIED",
+    "DISK_FULL",
+    "HEARTBEAT_STALE",
+];
+/**
+ * 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 const CLIENT_HEALTH_REPAIR_KINDS = [
+    "CHECK_NOW",
+    "RETRY_SYNC",
+    "RESUME_SYNC",
+    "REPAIR_CLI",
+    "UPDATE_CORE",
+    "APPLY_DESKTOP_UPDATE",
+    "RESTART_APP",
+];
+/** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
+export const CLIENT_HEALTH_COMMAND_STATES = [
+    "queued",
+    "acknowledged",
+    "running",
+    "succeeded",
+    "failed",
+    "expired",
+];
+/** Closed diagnostic probe identifiers (US-007). */
+export const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
+    "auth",
+    "runner",
+    "cli",
+    "core",
+    "updater",
+    "sync",
+    "conflicts",
+    "storage",
+    "permissions",
+];
+export const CLIENT_HEALTH_CHECK_STATUSES = ["pass", "fail", "skip"];
+// ─── Bounds ──────────────────────────────────────────────────────────────────
+export const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
+export const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100_000;
+export const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100_000;
+export const CLIENT_HEALTH_MAX_CHECKS = 16;
+export class ClientHealthContractError extends Error {
+    code;
+    field;
+    constructor(code, field, detail) {
+        super(`client-health contract violation [${code}] at ${field}${detail ? `: ${detail}` : ""}`);
+        this.name = "ClientHealthContractError";
+        this.code = code;
+        this.field = field;
+    }
+}
+// ─── Value validators (fail closed) ──────────────────────────────────────────
+const INSTALLATION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}$/;
+const COMMAND_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}$/;
+/** Same shape sync-auth-middleware.ts enforces on x-hq-*-version headers. */
+const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+/**
+ * Secret-shaped prefixes rejected outright even when the charset is otherwise
+ * legal (JWTs, cloud keys, PATs, bot tokens fit in 64 bounded chars).
+ */
+const SECRET_PREFIXES = ["AKIA", "ASIA", "ghp_", "gho_", "github_pat_", "xox", "sk-", "eyJ", "-----BEGIN"];
+function assertSafeBoundedString(field, value) {
+    if (value === undefined || value === null)
+        throw new ClientHealthContractError("MISSING_FIELD", field);
+    if (typeof value !== "string")
+        throw new ClientHealthContractError("INVALID_TYPE", field, "expected string");
+    if (value.length === 0 || value.length > CLIENT_HEALTH_MAX_STRING_LENGTH) {
+        throw new ClientHealthContractError("OUT_OF_BOUNDS", field, `length must be 1..${CLIENT_HEALTH_MAX_STRING_LENGTH}`);
+    }
+    // Raw logs / free-form shell text: any whitespace, newline, or shell metacharacter.
+    if (/[\s;|&$<>`'"(){}*?!#=,]/.test(value)) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "free-form text is not a contract value");
+    }
+    // Customer paths: separators, home refs, drive letters.
+    if (value.includes("/") || value.includes("\\") || value.startsWith("~") || /^[A-Za-z]:/.test(value)) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "path-shaped value rejected");
+    }
+    for (const prefix of SECRET_PREFIXES) {
+        if (value.startsWith(prefix)) {
+            throw new ClientHealthContractError("UNSAFE_VALUE", field, "secret-shaped value rejected");
+        }
+    }
+    return value;
+}
+function assertVersion(field, value) {
+    const safe = assertSafeBoundedString(field, value);
+    if (!SEMVER.test(safe))
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "expected a SemVer version");
+    return safe;
+}
+function assertIsoUtc(field, value) {
+    const safe = assertSafeBoundedString(field, value);
+    if (!ISO_UTC.test(safe) || !Number.isFinite(Date.parse(safe))) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "expected ISO-8601 UTC timestamp");
+    }
+    return safe;
+}
+function assertEnum(field, value, allowed) {
+    const safe = assertSafeBoundedString(field, value);
+    if (!allowed.includes(safe)) {
+        throw new ClientHealthContractError("UNKNOWN_ENUM_VALUE", field, `"${safe.slice(0, 32)}" is not allowed`);
+    }
+    return safe;
+}
+function assertBoundedInt(field, value, max) {
+    if (value === undefined || value === null)
+        throw new ClientHealthContractError("MISSING_FIELD", field);
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new ClientHealthContractError("INVALID_TYPE", field, "expected integer");
+    }
+    if (value < 0 || value > max)
+        throw new ClientHealthContractError("OUT_OF_BOUNDS", field);
+    return value;
+}
+function asRecord(field, value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ClientHealthContractError("INVALID_TYPE", field, "expected object");
+    }
+    return value;
+}
+// ─── Parsers ─────────────────────────────────────────────────────────────────
+/**
+ * Parse + validate one heartbeat. Unknown extra fields are ignored (additive
+ * tolerance); every consumed value fails closed on unsafe content.
+ */
+export function parseClientHealthHeartbeat(input) {
+    const raw = asRecord("heartbeat", input);
+    const contractVersion = assertBoundedInt("contractVersion", raw.contractVersion, 1_000);
+    if (contractVersion < 1 || contractVersion > CLIENT_HEALTH_CONTRACT_VERSION) {
+        throw new ClientHealthContractError("UNSUPPORTED_CONTRACT_VERSION", "contractVersion");
+    }
+    const installationId = assertSafeBoundedString("installationId", raw.installationId);
+    if (!INSTALLATION_ID.test(installationId)) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", "installationId");
+    }
+    const rawVersions = asRecord("versions", raw.versions);
+    const versions = {};
+    for (const key of ["desktop", "cli", "core", "syncRunner"]) {
+        if (rawVersions[key] !== undefined)
+            versions[key] = assertVersion(`versions.${key}`, rawVersions[key]);
+    }
+    const heartbeat = {
+        contractVersion,
+        installationId,
+        source: assertEnum("source", raw.source, CLIENT_HEALTH_SOURCES),
+        platform: assertEnum("platform", raw.platform, CLIENT_HEALTH_PLATFORMS),
+        arch: assertEnum("arch", raw.arch, CLIENT_HEALTH_ARCHS),
+        sentAt: assertIsoUtc("sentAt", raw.sentAt),
+        sequence: assertBoundedInt("sequence", raw.sequence, Number.MAX_SAFE_INTEGER),
+        versions,
+        syncState: assertEnum("syncState", raw.syncState, CLIENT_HEALTH_SYNC_STATES),
+        consecutiveFailures: assertBoundedInt("consecutiveFailures", raw.consecutiveFailures, CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES),
+    };
+    if (raw.lastSyncAttemptAt !== undefined)
+        heartbeat.lastSyncAttemptAt = assertIsoUtc("lastSyncAttemptAt", raw.lastSyncAttemptAt);
+    if (raw.lastSyncSuccessAt !== undefined)
+        heartbeat.lastSyncSuccessAt = assertIsoUtc("lastSyncSuccessAt", raw.lastSyncSuccessAt);
+    if (raw.conflictCount !== undefined) {
+        heartbeat.conflictCount = assertBoundedInt("conflictCount", raw.conflictCount, CLIENT_HEALTH_MAX_CONFLICT_COUNT);
+    }
+    if (raw.updaterState !== undefined) {
+        heartbeat.updaterState = assertEnum("updaterState", raw.updaterState, CLIENT_HEALTH_UPDATER_STATES);
+    }
+    if (raw.failureReason !== undefined) {
+        heartbeat.failureReason = assertEnum("failureReason", raw.failureReason, CLIENT_HEALTH_FAILURE_REASONS);
+    }
+    return heartbeat;
+}
+/** Parse + validate one diagnostic/repair command receipt. Unknown kinds fail closed. */
+export function parseClientHealthCommandReceipt(input) {
+    const raw = asRecord("receipt", input);
+    const contractVersion = assertBoundedInt("contractVersion", raw.contractVersion, 1_000);
+    if (contractVersion < 1 || contractVersion > CLIENT_HEALTH_CONTRACT_VERSION) {
+        throw new ClientHealthContractError("UNSUPPORTED_CONTRACT_VERSION", "contractVersion");
+    }
+    const commandId = assertSafeBoundedString("commandId", raw.commandId);
+    if (!COMMAND_ID.test(commandId))
+        throw new ClientHealthContractError("UNSAFE_VALUE", "commandId");
+    const installationId = assertSafeBoundedString("installationId", raw.installationId);
+    if (!INSTALLATION_ID.test(installationId))
+        throw new ClientHealthContractError("UNSAFE_VALUE", "installationId");
+    const receipt = {
+        contractVersion,
+        commandId,
+        installationId,
+        kind: assertEnum("kind", raw.kind, CLIENT_HEALTH_REPAIR_KINDS),
+        state: assertEnum("state", raw.state, CLIENT_HEALTH_COMMAND_STATES),
+        revision: assertBoundedInt("revision", raw.revision, Number.MAX_SAFE_INTEGER),
+        occurredAt: assertIsoUtc("occurredAt", raw.occurredAt),
+    };
+    if (raw.failureReason !== undefined) {
+        receipt.failureReason = assertEnum("failureReason", raw.failureReason, CLIENT_HEALTH_FAILURE_REASONS);
+    }
+    if (raw.checks !== undefined) {
+        if (!Array.isArray(raw.checks))
+            throw new ClientHealthContractError("INVALID_TYPE", "checks", "expected array");
+        if (raw.checks.length > CLIENT_HEALTH_MAX_CHECKS)
+            throw new ClientHealthContractError("OUT_OF_BOUNDS", "checks");
+        receipt.checks = raw.checks.map((entry, index) => {
+            const check = asRecord(`checks[${index}]`, entry);
+            const result = {
+                check: assertEnum(`checks[${index}].check`, check.check, CLIENT_HEALTH_DIAGNOSTIC_CHECKS),
+                status: assertEnum(`checks[${index}].status`, check.status, CLIENT_HEALTH_CHECK_STATUSES),
+            };
+            if (check.reason !== undefined) {
+                result.reason = assertEnum(`checks[${index}].reason`, check.reason, CLIENT_HEALTH_FAILURE_REASONS);
+            }
+            return result;
+        });
+    }
+    return receipt;
+}
+// ─── Sequence discipline ─────────────────────────────────────────────────────
+/**
+ * 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 function shouldApplyHeartbeat(storedSequence, incomingSequence) {
+    if (storedSequence === undefined)
+        return true;
+    return incomingSequence > storedSequence;
+}
+//# sourceMappingURL=client-health-contract.js.map

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

@@ -0,0 +1,134 @@
+/**
+ * CLI client-health contribution (client-sync-health-control-plane US-003).
+ *
+ * Sends best-effort heartbeats to the authenticated control-plane endpoint
+ * `POST /v1/client-health/heartbeat` (US-001, hq-pro) using the US-000 wire
+ * contract adapter (`client-health-contract.ts` — never redefined here), so
+ * CLI-only users and version mismatches surface in the same installation
+ * health model the desktop app feeds.
+ *
+ * Discipline (mirrors `cli-telemetry.ts` `emitCliSessionStarted`):
+ *   - Uses only an ALREADY-CACHED session: never refreshes tokens, never
+ *     opens a browser.
+ *   - Bounded by a short timeout ({@link CLIENT_HEALTH_TIMEOUT_MS}); every
+ *     failure is swallowed. A heartbeat can never delay or change a command's
+ *     result or exit code.
+ *   - Machine identities send their ID token (custom:entityType claims), so
+ *     the server attributes the snapshot to the machine principal, not a
+ *     human. The CLI never sends identity fields in the body — the server
+ *     resolves the owning principal from the verified token (US-001 rejects
+ *     caller-supplied identity outright).
+ *   - Sync state is read through the engine's `listJournals()` — the ONLY
+ *     correct enumeration of per-scope journals (single-path reconstruction
+ *     regressed before: feedback_9fbf1f82 / feedback_46288b7b).
+ *
+ * Local state (installation identity + monotonic sequence + sync outcome
+ * counters) lives at `{stateDir}/cli-client-health.json` next to the sync
+ * journals. The installation ID is a stable RANDOM identifier — never a
+ * hardware fingerprint; HMAC'ing happens server-side (US-001).
+ */
+import { isExpiring, loadCachedTokens } from "./cognito-session.js";
+import { type VersionInfo } from "./feedback-versions.js";
+import { type ClientHealthArch, type ClientHealthHeartbeat, type ClientHealthPlatform } from "./client-health-contract.js";
+/** Same bound as CLI telemetry: a heartbeat may never stall a command. */
+export declare const CLIENT_HEALTH_TIMEOUT_MS = 1200;
+export declare const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
+export interface CliClientHealthState {
+    /** Stable random installation identity — regenerated only if invalid. */
+    installationId: string;
+    /** Highest heartbeat sequence this installation has emitted. */
+    sequence: number;
+    /** Consecutive failed CLI sync commands since the last success. */
+    consecutiveFailures: number;
+    lastSyncAttemptAt?: string;
+    lastSyncSuccessAt?: string;
+}
+export declare function newInstallationId(): string;
+/**
+ * Load (or initialize) the persisted installation state. Any read/parse
+ * problem or invalid field degrades to a fresh value — health capture must
+ * never break a CLI command.
+ */
+export declare function loadClientHealthState(stateDir: string): CliClientHealthState;
+/** Best-effort persist — a read-only disk must never fail a command. */
+export declare function persistClientHealthState(stateDir: string, state: CliClientHealthState): void;
+/**
+ * Strictly-increasing sequence: wall-clock ms when it is ahead (keeps
+ * separate processes ordered without locking), else last + 1.
+ */
+export declare function nextHeartbeatSequence(state: CliClientHealthState, nowMs: number): number;
+export declare function detectClientHealthPlatform(platform?: NodeJS.Platform): ClientHealthPlatform | null;
+export declare function detectClientHealthArch(arch?: string): ClientHealthArch | null;
+interface JournalLike {
+    journal: {
+        lastSync?: string | null;
+    };
+}
+/**
+ * Latest engine-recorded sync time across ALL journal shards, normalized to
+ * contract ISO-UTC. Null when nothing has ever synced.
+ */
+export declare function latestJournalSyncTime(journals: readonly JournalLike[]): string | null;
+export type ClientHealthEventKind = "invocation" | "sync_attempt" | "sync_success" | "sync_failure";
+export interface BuildCliHeartbeatInput {
+    kind: ClientHealthEventKind;
+    state: CliClientHealthState;
+    sequence: number;
+    versions: VersionInfo;
+    /** Latest engine journal sync time (see {@link latestJournalSyncTime}). */
+    journalLastSyncAt: string | null;
+    now: Date;
+    platform?: ClientHealthPlatform | null;
+    arch?: ClientHealthArch | null;
+}
+/**
+ * Build one contract-valid CLI heartbeat, or null when this environment
+ * cannot be represented in the closed contract enums (unknown platform/arch)
+ * — in which case nothing is sent, per fail-closed design.
+ */
+export declare function buildCliHeartbeat(input: BuildCliHeartbeatInput): ClientHealthHeartbeat | null;
+export type HeartbeatPoster = (heartbeat: ClientHealthHeartbeat, token: string, signal: AbortSignal) => Promise<unknown>;
+export interface ClientHealthDeps {
+    now?: () => Date;
+    stateDir?: () => string;
+    loadTokens?: typeof loadCachedTokens;
+    machineIdentity?: () => boolean;
+    expiring?: typeof isExpiring;
+    versions?: () => VersionInfo;
+    journals?: () => readonly JournalLike[];
+    post?: HeartbeatPoster;
+    timeoutMs?: number;
+}
+/**
+ * Apply one health event: update local installation state, then — only when a
+ * healthy cached session exists — emit one bounded, fully-swallowed heartbeat.
+ * NEVER throws and never refreshes auth.
+ *
+ * The ENTIRE async contribution — not just the POST — is bounded by
+ * `deps.timeoutMs` (default {@link CLIENT_HEALTH_TIMEOUT_MS}): the commander
+ * preAction hook and the post-sync `succeeded()`/`failed()` calls AWAIT this
+ * promise on the command path, so a hung dependency (e.g. a poster that
+ * ignores its abort signal) must never delay a command past the bound. On
+ * timeout the pending work is abandoned silently.
+ */
+export declare function contributeClientHealth(kind: ClientHealthEventKind, deps?: ClientHealthDeps): Promise<void>;
+/**
+ * Fire-once-per-process invocation heartbeat (commander preAction seam, next
+ * to `emitCliSessionStarted`). Reports the real CLI + Core versions, platform,
+ * stable installation ID, and the invocation timestamp.
+ */
+export declare function reportCliClientHealthInvocation(deps?: ClientHealthDeps): Promise<void>;
+export interface SyncHealthReport {
+    /** Report the terminal outcome. Bounded, swallowed, safe to await. */
+    succeeded(): Promise<void>;
+    failed(): Promise<void>;
+}
+/**
+ * Report a CLI sync command run: an attempt heartbeat now (fire-and-forget)
+ * and a final success/failure heartbeat when the caller resolves the outcome.
+ * This is DIRECT reporting from the sync command — never reconstructed from
+ * cli_session_started analytics.
+ */
+export declare function beginSyncHealthReport(deps?: ClientHealthDeps): SyncHealthReport;
+export {};
+//# sourceMappingURL=client-health.d.ts.map