@indigoai-us/hq-cli 5.106.3 → 5.107.0

package/dist/utils/client-health.js

@@ -0,0 +1,376 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+import { getStateDir, listJournals } from "@indigoai-us/hq-cloud";
+import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
+import { vaultApiFetch } from "./vault-api.js";
+import { collectVersions } from "./feedback-versions.js";
+import { CLIENT_HEALTH_CONTRACT_VERSION, parseClientHealthHeartbeat, } from "./client-health-contract.js";
+/** Same bound as CLI telemetry: a heartbeat may never stall a command. */
+export const CLIENT_HEALTH_TIMEOUT_MS = 1_200;
+export const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
+/**
+ * Pre-filter mirror of the contract's SemVer shape (the contract keeps its
+ * validators private). A version failing this is DROPPED individually so one
+ * malformed component version (e.g. a hand-edited core.yaml) never suppresses
+ * the whole heartbeat; `parseClientHealthHeartbeat` remains the final
+ * fail-closed gate before anything crosses the wire.
+ */
+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 INSTALLATION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}$/;
+export function newInstallationId() {
+    // 32 lowercase hex chars: always starts alphanumeric, always in-charset,
+    // always inside the contract's 8..64 length bounds.
+    return randomBytes(16).toString("hex");
+}
+function stateFilePath(stateDir) {
+    return path.join(stateDir, CLIENT_HEALTH_STATE_FILE);
+}
+/** True only when `target` exists and is a directory; never throws. */
+function isDirectory(target) {
+    try {
+        return fs.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function loadClientHealthState(stateDir) {
+    let raw = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(stateFilePath(stateDir), "utf-8"));
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            raw = parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt state file: start fresh.
+    }
+    const installationId = typeof raw.installationId === "string" &&
+        INSTALLATION_ID.test(raw.installationId)
+        ? raw.installationId
+        : newInstallationId();
+    const sequence = typeof raw.sequence === "number" &&
+        Number.isSafeInteger(raw.sequence) &&
+        raw.sequence >= 0
+        ? raw.sequence
+        : 0;
+    const consecutiveFailures = typeof raw.consecutiveFailures === "number" &&
+        Number.isSafeInteger(raw.consecutiveFailures) &&
+        raw.consecutiveFailures >= 0
+        ? raw.consecutiveFailures
+        : 0;
+    const state = {
+        installationId,
+        sequence,
+        consecutiveFailures,
+    };
+    if (typeof raw.lastSyncAttemptAt === "string") {
+        state.lastSyncAttemptAt = raw.lastSyncAttemptAt;
+    }
+    if (typeof raw.lastSyncSuccessAt === "string") {
+        state.lastSyncSuccessAt = raw.lastSyncSuccessAt;
+    }
+    return state;
+}
+/** Best-effort persist — a read-only disk must never fail a command. */
+export function persistClientHealthState(stateDir, state) {
+    try {
+        fs.mkdirSync(stateDir, { recursive: true });
+        fs.writeFileSync(stateFilePath(stateDir), `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+    }
+    catch {
+        // Best effort only.
+    }
+}
+/**
+ * Strictly-increasing sequence: wall-clock ms when it is ahead (keeps
+ * separate processes ordered without locking), else last + 1.
+ */
+export function nextHeartbeatSequence(state, nowMs) {
+    return Math.max(state.sequence + 1, nowMs);
+}
+// ─── Environment mapping ─────────────────────────────────────────────────────
+export function detectClientHealthPlatform(platform = process.platform) {
+    switch (platform) {
+        case "darwin":
+            return "macos";
+        case "win32":
+            return "windows";
+        case "linux":
+            return "linux";
+        default:
+            return null;
+    }
+}
+export function detectClientHealthArch(arch = process.arch) {
+    switch (arch) {
+        case "x64":
+            return "x64";
+        case "arm64":
+            return "arm64";
+        default:
+            return null;
+    }
+}
+/**
+ * Latest engine-recorded sync time across ALL journal shards, normalized to
+ * contract ISO-UTC. Null when nothing has ever synced.
+ */
+export function latestJournalSyncTime(journals) {
+    let latest = null;
+    for (const entry of journals) {
+        const value = entry.journal?.lastSync;
+        if (typeof value !== "string")
+            continue;
+        const parsed = Date.parse(value);
+        if (!Number.isFinite(parsed))
+            continue;
+        if (latest === null || parsed > latest)
+            latest = parsed;
+    }
+    return latest === null ? null : new Date(latest).toISOString();
+}
+/**
+ * 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 function buildCliHeartbeat(input) {
+    const platform = input.platform !== undefined ? input.platform : detectClientHealthPlatform();
+    const arch = input.arch !== undefined ? input.arch : detectClientHealthArch();
+    if (!platform || !arch)
+        return null;
+    const versions = {};
+    if (SEMVER.test(input.versions.cli))
+        versions.cli = input.versions.cli;
+    if (input.versions.core && SEMVER.test(input.versions.core)) {
+        versions.core = input.versions.core;
+    }
+    // `VersionInfo.sync` is the HQ Sync desktop (menubar) app version recorded
+    // at ~/.hq/sync-version.json — the contract's `desktop` slot.
+    if (input.versions.sync && SEMVER.test(input.versions.sync)) {
+        versions.desktop = input.versions.sync;
+    }
+    const lastSyncSuccessAt = latestIso(input.state.lastSyncSuccessAt, input.journalLastSyncAt);
+    let syncState;
+    switch (input.kind) {
+        case "sync_attempt":
+            syncState = "syncing";
+            break;
+        case "sync_failure":
+            syncState = "error";
+            break;
+        default:
+            syncState = lastSyncSuccessAt ? "idle" : "never_synced";
+            break;
+    }
+    const heartbeat = {
+        contractVersion: CLIENT_HEALTH_CONTRACT_VERSION,
+        installationId: input.state.installationId,
+        source: "cli",
+        platform,
+        arch,
+        sentAt: input.now.toISOString(),
+        sequence: input.sequence,
+        versions,
+        syncState,
+        consecutiveFailures: input.state.consecutiveFailures,
+    };
+    if (input.state.lastSyncAttemptAt !== undefined) {
+        heartbeat.lastSyncAttemptAt = input.state.lastSyncAttemptAt;
+    }
+    if (lastSyncSuccessAt !== null) {
+        heartbeat.lastSyncSuccessAt = lastSyncSuccessAt;
+    }
+    return heartbeat;
+}
+function latestIso(a, b) {
+    const times = [a, b]
+        .map((value) => (typeof value === "string" ? Date.parse(value) : NaN))
+        .filter((value) => Number.isFinite(value));
+    if (times.length === 0)
+        return null;
+    return new Date(Math.max(...times)).toISOString();
+}
+const defaultPoster = (heartbeat, token, signal) => vaultApiFetch({
+    token,
+    path: "/v1/client-health/heartbeat",
+    method: "POST",
+    body: heartbeat,
+    signal,
+});
+/**
+ * Resolve when `work` settles OR after `ms` milliseconds — whichever comes
+ * first. Never rejects. The timer is unref'd so a pending contribution can
+ * never keep the process alive, and cleared on settle so tests don't leak.
+ */
+function settleWithin(work, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+        const done = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        work.then(done, done);
+    });
+}
+/**
+ * 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 async function contributeClientHealth(kind, deps = {}) {
+    await settleWithin(contributeClientHealthUnbounded(kind, deps), deps.timeoutMs ?? CLIENT_HEALTH_TIMEOUT_MS);
+}
+async function contributeClientHealthUnbounded(kind, deps) {
+    try {
+        const now = (deps.now ?? (() => new Date()))();
+        const stateDir = (deps.stateDir ?? getStateDir)();
+        // No HQ state dir means no HQ installation on this machine: no journals,
+        // no cached session, nothing to report. Health capture must OBSERVE an
+        // installation, never CREATE one — running any CLI command on a clean
+        // machine must not leave a ~/.hq behind (regression: the codex-skill-bridge
+        // differential e2e caught the preAction hook manufacturing ~/.hq +
+        // cli-client-health.json in a fresh HOME).
+        if (!isDirectory(stateDir))
+            return;
+        const state = loadClientHealthState(stateDir);
+        switch (kind) {
+            case "sync_attempt":
+                state.lastSyncAttemptAt = now.toISOString();
+                break;
+            case "sync_success":
+                state.lastSyncSuccessAt = now.toISOString();
+                state.consecutiveFailures = 0;
+                break;
+            case "sync_failure":
+                state.consecutiveFailures += 1;
+                break;
+            default:
+                break;
+        }
+        const cached = (deps.loadTokens ?? loadCachedTokens)();
+        const expiring = deps.expiring ?? isExpiring;
+        const machine = deps.machineIdentity ?? isMachineIdentity;
+        // Machine identities authenticate the vault API with their ID token (its
+        // custom:entityType claims keep the principal distinguishable server-side).
+        let token;
+        if (cached && !expiring(cached, 120)) {
+            token = machine() ? cached.idToken : cached.accessToken;
+        }
+        if (!token) {
+            // Still persist local outcome counters so the next authenticated
+            // heartbeat reports them.
+            persistClientHealthState(stateDir, state);
+            return;
+        }
+        const sequence = nextHeartbeatSequence(state, now.getTime());
+        state.sequence = sequence;
+        persistClientHealthState(stateDir, state);
+        let journalLastSyncAt = null;
+        try {
+            journalLastSyncAt = latestJournalSyncTime((deps.journals ?? listJournals)());
+        }
+        catch {
+            // Journal enumeration is best effort.
+        }
+        const heartbeat = buildCliHeartbeat({
+            kind,
+            state,
+            sequence,
+            versions: (deps.versions ?? collectVersions)(),
+            journalLastSyncAt,
+            now,
+        });
+        if (!heartbeat)
+            return;
+        // Final fail-closed gate: never send anything the shared contract rejects.
+        // The PARSED value is what crosses the wire — the contract's return value
+        // defines the payload, so unknown extra fields can never ride along via
+        // JSON.stringify of the locally-built object.
+        const wireHeartbeat = parseClientHealthHeartbeat(heartbeat);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), deps.timeoutMs ?? CLIENT_HEALTH_TIMEOUT_MS);
+        timeout.unref?.();
+        try {
+            await (deps.post ?? defaultPoster)(wireHeartbeat, token, controller.signal);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Health contribution is best effort and must never affect a CLI command.
+    }
+}
+// ─── Command wiring ──────────────────────────────────────────────────────────
+let invocationPromise;
+/**
+ * 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 function reportCliClientHealthInvocation(deps) {
+    invocationPromise ??= contributeClientHealth("invocation", deps);
+    return invocationPromise;
+}
+/**
+ * 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 function beginSyncHealthReport(deps = {}) {
+    const attempt = contributeClientHealth("sync_attempt", deps);
+    const finish = (kind) => attempt
+        .then(() => contributeClientHealth(kind, deps))
+        .catch(() => undefined);
+    return {
+        succeeded: () => finish("sync_success"),
+        failed: () => finish("sync_failure"),
+    };
+}
+//# sourceMappingURL=client-health.js.map

package/dist/utils/hook-trust.d.ts

@@ -2,12 +2,49 @@ export interface CodexRpcClient {
     request(method: string, params: unknown): Promise<unknown>;
     close(): Promise<void>;
 }
+/**
+ * The home directory every runtime's config is resolved under.
+ *
+ * `HOME=''` is not the same as `HOME` unset: with `??` an empty-but-set `HOME`
+ * survives the fallback, and every `path.join(home, ...)` below it silently
+ * becomes a RELATIVE path — pointing `~/.claude.json` at a same-named file in
+ * the cwd, reading it, writing it, and dropping a backup beside it, while the
+ * user's real config goes untouched. Empty means "no home", exactly as the
+ * safe-write substrate's `resolveEnv` treats it.
+ *
+ * Exported for tests; production callers get it through `DEFAULT_DEPS`.
+ */
+export declare function defaultHomeDir(): string;
 export interface HookTrustDependencies {
     createCodexClient: (cwd: string) => Promise<CodexRpcClient>;
     homeDir?: () => string;
+    /**
+     * Reads a config file as text. Injected only so tests can reproduce the race
+     * the Claude leg guards against — Claude rewriting `~/.claude.json` between
+     * our read and our commit — which no other seam can reach.
+     */
+    readConfigText?: (file: string) => string;
+}
+/** Per-call knobs the `hq reindex` orchestration passes down. */
+export interface HookTrustOptions {
+    /**
+     * Extra spellings of the HQ root to trust, beyond `hqRoot` itself.
+     *
+     * `hq reindex` canonicalizes its root before doing anything else, so by the
+     * time trust runs the symlink the user actually typed (and that Claude may
+     * have keyed `projects` under) is already gone. The command passes the
+     * pre-realpath path here so both spellings converge.
+     */
+    rootAliases?: string[];
+    /**
+     * How long to wait for a contended config lock. `hq reindex --from-hook`
+     * passes 0: a lifecycle hook must never stall the agent behind another HQ
+     * process's write, and trust converges on the next reindex anyway.
+     */
+    lockWaitMs?: number;
 }
 export interface RuntimeHookTrustResult {
-    runtime: 'codex' | 'grok';
+    runtime: 'codex' | 'grok' | 'claude';
     status: 'trusted' | 'unchanged' | 'skipped' | 'failed';
     trusted: number;
     reason?: string;
@@ -16,6 +53,29 @@ export interface RuntimeHookTrustResult {
 export declare function createCodexAppServerClient(cwd: string, executable?: string, args?: string[]): Promise<CodexRpcClient>;
 /** Trust only hooks declared by this HQ root's project `.codex/` layer. */
 export declare function trustCodexProjectHooks(hqRoot: string, deps?: HookTrustDependencies): Promise<RuntimeHookTrustResult>;
+/**
+ * Mark this HQ root as a trusted Claude Code workspace.
+ *
+ * WHY reindex owns this: Claude's trust is per FOLDER, not per hook — the same
+ * flag gates project `.claude/settings.json` hooks AND the `.claude/skills/`
+ * plugin scan. An untrusted HQ root loads neither, and Claude reports it as
+ * "skipped because this workspace was not trusted when plugins were scanned".
+ * So the Claude leg looks like the Grok leg (write folder trust into the
+ * runtime's own config) rather than the Codex leg (trust individual hooks).
+ *
+ * Setting the key is the runtime's own documented alternative to the dialog;
+ * Claude Code's error text names it directly: "Run Claude Code in that folder
+ * once and accept the trust dialog, or set
+ * projects[<path>].hasTrustDialogAccepted: true".
+ *
+ * `~/.claude.json` is a live, high-traffic file — Claude rewrites it after
+ * every session — so this reuses the MCP registration machinery rather than a
+ * bare read/write: the advisory lock is held across read->merge->write, a
+ * backup is taken before the first written byte, and the commit is a
+ * temp+fsync+rename. `JSON.stringify(doc, null, 2)` reproduces Claude's own
+ * formatting byte-for-byte, so an unrelated key is never reformatted.
+ */
+export declare function trustClaudeProjectFolder(hqRoot: string, deps?: HookTrustDependencies, options?: HookTrustOptions): RuntimeHookTrustResult;
 /**
  * Grok trusts hooks at folder scope, and on observed builds project
  * .grok/hooks often never load, so the user-global bridge under ~/.grok/hooks
@@ -28,5 +88,5 @@ export declare function trustCodexProjectHooks(hqRoot: string, deps?: HookTrustD
  */
 export declare function trustGrokProjectHooks(hqRoot: string, deps?: HookTrustDependencies): RuntimeHookTrustResult;
 /** Converge hook trust without turning an absent runtime into a reindex failure. */
-export declare function trustHqRuntimeHooks(hqRoot: string, deps?: HookTrustDependencies): Promise<RuntimeHookTrustResult[]>;
+export declare function trustHqRuntimeHooks(hqRoot: string, deps?: HookTrustDependencies, options?: HookTrustOptions): Promise<RuntimeHookTrustResult[]>;
 //# sourceMappingURL=hook-trust.d.ts.map