@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/node-preflight.ts

@@ -1,67 +0,0 @@
-/**
- * Runtime Node.js version guard for the hq CLI.
- *
- * HQ tooling requires Node.js 20 or newer. On older runtimes (notably Node 18)
- * the CLI dies with cryptic failures long before reaching any of its own code:
- * a native-module ABI mismatch from a prebuilt dependency, and a missing
- * `util.styleText` (added in Node 20). Those errors give the user no hint that
- * the real problem is just an old Node.
- *
- * This module exists to fail fast with an actionable message instead. It is
- * imported FIRST by every CLI entry point (`index.ts`, `bin/hq-auth-refresh.ts`)
- * so the check runs before commander, Sentry, or any dependency that needs a
- * Node 20+ API or a newer native ABI is evaluated. ES modules evaluate their
- * imports in source order, so as long as this is the first import in the entry
- * module, the guard short-circuits an unsupported runtime cleanly.
- *
- * Keep this file dependency-free — it must not import anything that could itself
- * fail to load on the very runtime it is trying to detect.
- */
-
-export const MIN_NODE_MAJOR = 20;
-
-export interface NodeVersionCheck {
-  ok: boolean;
-  major: number;
-  message?: string;
-}
-
-/**
- * Pure check: is the given Node version string (e.g. "18.19.0") supported?
- * Defaults to the running runtime's version. An unparseable version is treated
- * as supported so we never block a user on a version string we can't read.
- */
-export function checkNodeVersion(
-  versionString: string = process.versions.node,
-): NodeVersionCheck {
-  const major = Number.parseInt(String(versionString).split(".")[0] ?? "", 10);
-
-  if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR) {
-    return { ok: true, major };
-  }
-
-  const message =
-    `hq requires Node.js ${MIN_NODE_MAJOR} or newer — you are running Node ${versionString}.\n` +
-    `Older versions fail with native-module ABI mismatches and missing APIs.\n` +
-    `Please upgrade to Node ${MIN_NODE_MAJOR}+ (https://nodejs.org/) and run hq again.`;
-
-  return { ok: false, major, message };
-}
-
-/**
- * Side-effecting guard run on import: prints the upgrade message to stderr and
- * exits 1 on an unsupported runtime. A no-op on Node 20+. Set
- * `HQ_SKIP_NODE_PREFLIGHT=1` to bypass (used by the test runner, which already
- * runs on a supported Node).
- */
-export function enforceNodeVersion(): void {
-  if (process.env.HQ_SKIP_NODE_PREFLIGHT) return;
-
-  const result = checkNodeVersion();
-  if (!result.ok && result.message) {
-    process.stderr.write(`${result.message}\n`);
-    process.exit(1);
-  }
-}
-
-enforceNodeVersion();

package/src/outpost/session-heartbeat-bounds.test.ts

@@ -1,195 +0,0 @@
-/**
- * Payload bounding for the Outpost session heartbeat.
- *
- * ## Why this exists
- *
- * The heartbeat enumerates every Claude transcript and Codex rollout on the
- * box. On a long-lived Outpost that is an archive, not a status: the box this
- * was first run against had **8,258 Claude transcripts and 1,082 Codex
- * rollouts — 9,340 sessions — of which 15 had any activity in the last 15
- * minutes.** Publishing all of them produced a payload of roughly 1.9 MB.
- *
- * AWS IoT Core rejects anything over 128 KB, so the very first real publish
- * failed with `payload larger than 131072 bytes`. Every subsequent one would
- * have too. The heartbeat is a liveness signal; it must carry what is live.
- *
- * Two rules, both tested here:
- *   1. `ended` sessions are not published — they are history, and re-sending
- *      thousands of them every five seconds is the bug.
- *   2. Whatever survives that filter is still bounded by BYTES, because a busy
- *      box could exceed the limit on live sessions alone. When the bound bites
- *      it is reported, never silent — a truncated payload that looks complete
- *      is how you get a wrong dashboard instead of a missing one.
- */
-
-import { describe, expect, it } from "vitest";
-import {
-  DEFAULT_LIVENESS_THRESHOLDS,
-  IOT_PAYLOAD_BUDGET_BYTES,
-  collectSessions,
-  type DirEntry,
-  type FileStat,
-  type FileSystemPort,
-} from "./session-heartbeat.js";
-
-const NOW = new Date("2026-07-29T12:00:00.000Z");
-const NOW_MS = NOW.getTime();
-
-/**
- * A fake Claude tree with `count` transcripts, each aged `ageSecondsFor(i)`.
- * Codex enumeration sees an empty tree.
- */
-function claudeTreeFs(
-  count: number,
-  ageSecondsFor: (i: number) => number,
-): FileSystemPort {
-  const names = Array.from(
-    { length: count },
-    (_, i) =>
-      `${i.toString(16).padStart(8, "0")}-aaaa-bbbb-cccc-dddddddddddd.jsonl`,
-  );
-  const ageOf = new Map<string, number>();
-  names.forEach((n, i) => ageOf.set(n, ageSecondsFor(i)));
-
-  return {
-    async readDir(path: string): Promise<DirEntry[]> {
-      if (path.endsWith("/.claude/projects")) {
-        return [{ name: "-home-ec2-user-hq", isDirectory: true, isFile: false }];
-      }
-      if (path.endsWith("/.claude/projects/-home-ec2-user-hq")) {
-        return names.map((name) => ({
-          name,
-          isDirectory: false,
-          isFile: true,
-        }));
-      }
-      return [];
-    },
-    async stat(path: string): Promise<FileStat> {
-      const name = path.split("/").pop() ?? "";
-      const age = ageOf.get(name) ?? 0;
-      const mtimeMs = NOW_MS - age * 1000;
-      return { mtimeMs, birthtimeMs: mtimeMs, size: 1024 };
-    },
-    async readTextFile() {
-      return "";
-    },
-    async readBounded() {
-      // A realistic cwd/model sniff, so each record is a realistic size.
-      return JSON.stringify({
-        cwd: "/home/ec2-user/hq/repos/private/some-longish-repo-name",
-        model: "claude-opus-4-8",
-      });
-    },
-  };
-}
-
-const config = { personUid: "prs_01TEST", home: "/home/ec2-user", now: () => NOW };
-
-describe("payload bounding", () => {
-  it("publishes live sessions and drops the ended archive", async () => {
-    // 500 sessions: the first 5 active, the rest ancient — the real shape of
-    // a box that has been running for weeks.
-    const fs = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
-
-    const payload = await collectSessions(config, { fs });
-
-    expect(payload.sessions).toHaveLength(5);
-    expect(payload.sessions.every((s) => s.status !== "ended")).toBe(true);
-  });
-
-  it("reports how many sessions exist, not just how many it sent", async () => {
-    const fs = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
-
-    const payload = await collectSessions(config, { fs });
-
-    // Silent filtering reads as "this box has 5 sessions". It has 500.
-    expect(payload.totalSessions).toBe(500);
-    expect(payload.sessions.length).toBeLessThan(payload.totalSessions);
-  });
-
-  it("keeps idle sessions — only `ended` is archive", async () => {
-    // 2s → running, 5min → idle, 30d → ended.
-    const fs = claudeTreeFs(3, (i) => [2, 300, 60 * 60 * 24 * 30][i]!);
-
-    const payload = await collectSessions(config, { fs });
-
-    const statuses = payload.sessions.map((s) => s.status).sort();
-    expect(statuses).toEqual(["idle", "running"]);
-  });
-
-  it("stays under the IoT limit even when every session is live", async () => {
-    // 5,000 sessions all active — the size bound, not the status filter, is
-    // what has to hold here.
-    const fs = claudeTreeFs(5000, () => 2);
-
-    const payload = await collectSessions(config, { fs });
-    const bytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
-
-    expect(bytes).toBeLessThanOrEqual(IOT_PAYLOAD_BUDGET_BYTES);
-    // The real AWS IoT Core ceiling. The budget must leave headroom under it.
-    expect(bytes).toBeLessThan(131072);
-  });
-
-  it("flags truncation rather than quietly shortening the list", async () => {
-    const fs = claudeTreeFs(5000, () => 2);
-
-    const payload = await collectSessions(config, { fs });
-
-    expect(payload.truncated).toBe(true);
-    expect(payload.totalSessions).toBe(5000);
-    expect(payload.sessions.length).toBeLessThan(5000);
-  });
-
-  it("does not flag truncation when everything fits", async () => {
-    const fs = claudeTreeFs(3, () => 2);
-
-    const payload = await collectSessions(config, { fs });
-
-    expect(payload.truncated).toBe(false);
-    expect(payload.sessions).toHaveLength(3);
-    expect(payload.totalSessions).toBe(3);
-  });
-
-  it("reads transcript bodies ONLY for sessions it will publish", async () => {
-    // The enumerator statted every file AND did a 16 KiB bounded read on each,
-    // before anything was filtered. On the first real box that was 9,340 reads
-    // per tick, every 5 seconds — ~150 MB of disk for 15 useful records, on
-    // the exact resource that had already taken the machine down once.
-    const reads: string[] = [];
-    const base = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
-    const fs: FileSystemPort = {
-      ...base,
-      async readBounded(path, maxBytes, from) {
-        reads.push(path);
-        return base.readBounded(path, maxBytes, from);
-      },
-    };
-
-    const payload = await collectSessions(config, { fs });
-
-    expect(payload.sessions).toHaveLength(5);
-    // Five live sessions ⇒ five reads, not five hundred.
-    expect(reads).toHaveLength(5);
-  });
-
-  it("keeps the MOST RECENTLY ACTIVE sessions when it has to choose", async () => {
-    // Index 0 is freshest, index N oldest — all still within `idle`.
-    const fs = claudeTreeFs(5000, (i) => 1 + i * (1 / 10));
-
-    const payload = await collectSessions(config, { fs });
-
-    expect(payload.truncated).toBe(true);
-    // Dropping the newest and keeping stale ones would make the live view
-    // wrong in the one way that matters.
-    const kept = payload.sessions
-      .map((s) => Date.parse(s.lastActivityAt!))
-      .sort((a, b) => a - b);
-    const oldestKept = kept[0]!;
-    const cutoff =
-      NOW_MS - DEFAULT_LIVENESS_THRESHOLDS.idleWithinSeconds * 1000;
-    expect(oldestKept).toBeGreaterThan(cutoff);
-    // The single freshest session must always survive.
-    expect(Math.max(...kept)).toBe(NOW_MS - 1000);
-  });
-});

package/src/outpost/session-heartbeat-guard.test.ts

@@ -1,105 +0,0 @@
-/**
- * The no-secrets guard must catch credentials WITHOUT catching ordinary paths.
- *
- * Both halves matter equally, and the second is easy to get wrong. The guard
- * throws, and a throw fails the whole tick — so a pattern that matches a
- * legitimate directory name silently disables reporting for the entire box
- * until that session ages out.
- *
- * The original marker list held `sk-` and `asia` as bare substrings. `sk-`
- * matches `task-runner`, `flask-app`, `disk-usage`, `risk-model`. Anyone who
- * created a repo with one of those names would have taken the heartbeat down
- * across the box, with the service still reporting active — the exact failure
- * shape this whole change exists to remove.
- */
-
-import { describe, expect, it } from "vitest";
-import {
-  assertNoSecretsInPayload,
-  type AgentSession,
-  type SessionsHeartbeatPayload,
-} from "./session-heartbeat.js";
-
-function payloadWith(over: Partial<AgentSession>): SessionsHeartbeatPayload {
-  const session: AgentSession = {
-    id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
-    tool: "claude",
-    origin: "outpost",
-    cwd: "/home/ec2-user/hq",
-    project: "hq",
-    company: null,
-    model: "claude-opus-4-8",
-    status: "running",
-    startedAt: "2026-07-29T12:00:00.000Z",
-    lastActivityAt: "2026-07-29T12:00:00.000Z",
-    source: "/home/ec2-user/.claude/projects/-home-ec2-user-hq/x.jsonl",
-    ...over,
-  };
-  return {
-    type: "sessions",
-    origin: "outpost",
-    emittedAt: "2026-07-29T12:00:00.000Z",
-    sessions: [session],
-  };
-}
-
-describe("ordinary paths must never trip the guard", () => {
-  // Every one of these contains `sk-` or `asia` and would have thrown before.
-  const innocentPaths = [
-    "/home/ec2-user/hq/repos/private/task-runner",
-    "/home/ec2-user/hq/repos/public/flask-app",
-    "/home/ec2-user/hq/tools/disk-usage",
-    "/home/ec2-user/hq/models/risk-model",
-    "/home/ec2-user/hq/regions/asia-pacific",
-    "/home/ec2-user/hq/repos/private/password-manager",
-    "/home/ec2-user/hq/kiosk-display",
-  ];
-
-  for (const cwd of innocentPaths) {
-    it(`allows ${cwd.split("/").pop()}`, () => {
-      const project = cwd.split("/").pop()!;
-      expect(() =>
-        assertNoSecretsInPayload(payloadWith({ cwd, project, source: `${cwd}/s.jsonl` })),
-      ).not.toThrow();
-    });
-  }
-
-  it("allows a model id that merely starts with the letters sk", () => {
-    expect(() =>
-      assertNoSecretsInPayload(payloadWith({ model: "sk-lite-preview" })),
-    ).not.toThrow();
-  });
-});
-
-describe("real credentials must still be caught", () => {
-  const leaks: [string, Partial<AgentSession>][] = [
-    ["an Anthropic key", { model: "sk-ant-api03-AbCdEfGhIjKlMnOpQrStUv" }],
-    ["an OpenAI-style key", { model: "sk-AbCdEfGhIjKlMnOpQrStUvWxYz012345" }],
-    ["a long-lived AWS key id", { project: "AKIAIOSFODNN7EXAMPLE" }],
-    ["an STS temp key id", { project: "ASIAIOSFODNN7EXAMPLE" }],
-    ["a PEM private key", { cwd: "-----BEGIN RSA PRIVATE KEY-----" }],
-    ["an authorization header", { model: "authorization: xyz" }],
-    ["a bearer token", { model: "Bearer abcdefghijklmnop0123" }],
-    ["an instance token header", { project: "x-outpost-instance-token" }],
-    ["a refresh token field", { model: 'refresh_token="abc"' }],
-    ["a password field", { model: "password=hunter2" }],
-    ["a secret access key", { project: "secretaccesskey" }],
-    ["a session token", { project: "sessiontoken" }],
-  ];
-
-  for (const [what, over] of leaks) {
-    it(`rejects ${what}`, () => {
-      expect(() => assertNoSecretsInPayload(payloadWith(over))).toThrow(
-        /refusing to publish/,
-      );
-    });
-  }
-});
-
-describe("non-whitelisted fields are still rejected", () => {
-  it("refuses a payload carrying an extra field", () => {
-    const p = payloadWith({});
-    (p.sessions[0] as unknown as Record<string, unknown>).transcript = "secret";
-    expect(() => assertNoSecretsInPayload(p)).toThrow(/non-whitelisted/);
-  });
-});

package/src/outpost/session-heartbeat-publisher.test.ts

@@ -1,178 +0,0 @@
-/**
- * Tests for the on-box realtime publisher (mission-control US-009):
- *   - defaultRealtimeCredentialsFetcher POSTs the box's JWT to
- *     /v1/realtime/credentials and parses the response
- *   - createIotPublishPort vends scoped creds, builds an IoT client, publishes
- *     to the caller's topic, caches the client until near-expiry, and re-guards
- *     the no-secrets contract at the transport boundary
- */
-
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { mockClient } from "aws-sdk-client-mock";
-import {
-  IoTDataPlaneClient,
-  PublishCommand,
-} from "@aws-sdk/client-iot-data-plane";
-import {
-  createIotPublishPort,
-  defaultRealtimeCredentialsFetcher,
-  type RealtimeCredentialsResponse,
-} from "./session-heartbeat-publisher";
-import type { SessionsHeartbeatPayload } from "./session-heartbeat";
-
-const PERSON = "prs_alice";
-const TOPIC = `hq/${PERSON}/sessions`;
-const NOW = new Date("2026-06-15T18:55:00.000Z");
-
-function credsResponse(
-  expiresInMs: number,
-): RealtimeCredentialsResponse {
-  return {
-    credentials: {
-      accessKeyId: "ASIAEXAMPLE",
-      secretAccessKey: "secret",
-      sessionToken: "token",
-      expiration: new Date(NOW.getTime() + expiresInMs).toISOString(),
-    },
-    iotEndpoint: "abc123-ats.iot.us-east-1.amazonaws.com",
-    region: "us-east-1",
-    topic: TOPIC,
-    expiresAt: new Date(NOW.getTime() + expiresInMs).toISOString(),
-  };
-}
-
-function cleanPayload(): SessionsHeartbeatPayload {
-  return {
-    type: "sessions",
-    origin: "outpost",
-    emittedAt: NOW.toISOString(),
-    sessions: [
-      {
-        id: "x",
-        tool: "claude",
-        origin: "outpost",
-        cwd: "/home/ec2-user/hq",
-        project: "hq",
-        company: null,
-        model: "claude-opus-4",
-        status: "running",
-        startedAt: null,
-        lastActivityAt: NOW.toISOString(),
-        source: "/home/ec2-user/.claude/projects/p/x.jsonl",
-      },
-    ],
-  };
-}
-
-describe("defaultRealtimeCredentialsFetcher", () => {
-  it("POSTs the JWT to /v1/realtime/credentials and returns the parsed body", async () => {
-    const body = credsResponse(3_600_000);
-    const fetchImpl = vi.fn().mockResolvedValue({
-      ok: true,
-      status: 200,
-      statusText: "OK",
-      json: async () => body,
-    } as Response);
-    const fetcher = defaultRealtimeCredentialsFetcher({
-      apiBaseUrl: "https://hqapi.hq.computer",
-      getJwt: async () => "JWT123",
-      fetchImpl: fetchImpl as unknown as typeof fetch,
-    });
-    const out = await fetcher();
-    expect(out).toEqual(body);
-    const [url, init] = fetchImpl.mock.calls[0];
-    expect(url).toBe("https://hqapi.hq.computer/v1/realtime/credentials");
-    expect(init.method).toBe("POST");
-    expect(init.headers.authorization).toBe("Bearer JWT123");
-  });
-
-  it("throws on a non-ok response", async () => {
-    const fetchImpl = vi.fn().mockResolvedValue({
-      ok: false,
-      status: 403,
-      statusText: "Forbidden",
-      json: async () => ({}),
-    } as Response);
-    const fetcher = defaultRealtimeCredentialsFetcher({
-      apiBaseUrl: "https://hqapi.hq.computer",
-      getJwt: async () => "JWT",
-      fetchImpl: fetchImpl as unknown as typeof fetch,
-    });
-    await expect(fetcher()).rejects.toThrow(/403/);
-  });
-});
-
-describe("createIotPublishPort", () => {
-  const iotMock = mockClient(IoTDataPlaneClient);
-  beforeEach(() => iotMock.reset());
-
-  it("publishes the payload to the caller's topic via IoT", async () => {
-    iotMock.on(PublishCommand).resolves({});
-    const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
-    const publish = createIotPublishPort({
-      fetchCredentials,
-      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
-      now: () => NOW,
-    });
-
-    const payload = cleanPayload();
-    await publish(TOPIC, payload);
-
-    const call = iotMock.commandCalls(PublishCommand)[0];
-    expect(call.args[0].input.topic).toBe(TOPIC);
-    const sent = JSON.parse(
-      Buffer.from(call.args[0].input.payload as Uint8Array).toString("utf8"),
-    );
-    expect(sent.type).toBe("sessions");
-    expect(sent.sessions[0].id).toBe("x");
-  });
-
-  it("caches the vended creds/client until near expiry, then re-vends", async () => {
-    iotMock.on(PublishCommand).resolves({});
-    const fetchCredentials = vi
-      .fn()
-      .mockResolvedValueOnce(credsResponse(3_600_000))
-      .mockResolvedValueOnce(credsResponse(3_600_000));
-    const publish = createIotPublishPort({
-      fetchCredentials,
-      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
-      now: () => NOW,
-    });
-
-    await publish(TOPIC, cleanPayload());
-    await publish(TOPIC, cleanPayload());
-    // Second publish reuses the cached client — creds vended once.
-    expect(fetchCredentials).toHaveBeenCalledTimes(1);
-  });
-
-  it("re-vends when the cached creds are within the refresh skew of expiry", async () => {
-    iotMock.on(PublishCommand).resolves({});
-    const fetchCredentials = vi
-      .fn()
-      // expires in 30s — inside the 60s refresh skew, so every call re-vends
-      .mockResolvedValue(credsResponse(30_000));
-    const publish = createIotPublishPort({
-      fetchCredentials,
-      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
-      now: () => NOW,
-    });
-    await publish(TOPIC, cleanPayload());
-    await publish(TOPIC, cleanPayload());
-    expect(fetchCredentials).toHaveBeenCalledTimes(2);
-  });
-
-  it("re-guards the no-secrets contract at the transport boundary", async () => {
-    iotMock.on(PublishCommand).resolves({});
-    const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
-    const publish = createIotPublishPort({
-      fetchCredentials,
-      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
-      now: () => NOW,
-    });
-    const dirty = cleanPayload();
-    // Smuggle a secret into a whitelisted field — the publisher must refuse.
-    dirty.sessions[0].model = "sk-ant-leaked-key";
-    await expect(publish(TOPIC, dirty)).rejects.toThrow(/secret marker/);
-    expect(iotMock.commandCalls(PublishCommand)).toHaveLength(0);
-  });
-});