@indigoai-us/hq-cli 5.60.0 → 5.62.0

package/src/commands/outposts.ts

@@ -0,0 +1,338 @@
+/**
+ * `hq outposts` — manage your personal HQ Outposts (EC2 boxes) from the
+ * terminal instead of the web console. Targets the hq-pro `/outpost/*`
+ * control plane on `DEFAULT_VAULT_API_URL` via the shared `vaultApiFetch`
+ * helper — the same routes the console's outpost panel calls.
+ *
+ * Outposts are PERSONAL / caller-scoped: hq-pro keys every `/outpost/*` route
+ * on the caller's Cognito sub, so there is no `--company`. `--id <outpostId>`
+ * selects a specific box (passed as the `outpostId` query param); when omitted
+ * hq-pro targets the caller's primary slot.
+ *
+ * Subcommands:
+ *   hq outposts list                — every Outpost you own (row summaries)
+ *   hq outposts status [--id]       — live detail for one box
+ *   hq outposts codex-enable [--id] — enable / retry Codex on the box
+ *   hq outposts login [--id]        — request a fresh login URL
+ *   hq outposts destroy [--id] --yes — tear the box down (destructive; flag-guarded)
+ *
+ * NOTE: hq-pro exposes no rename or settings-mutation route for Outposts (the
+ * web console can't rename them either), so this CLI wraps only the lifecycle
+ * and status routes that exist. Renaming an Outpost is not a backend capability.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+
+/** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
+export class OutpostHttpError extends Error {
+  status: number;
+  step?: string;
+  constructor(status: number, message: string, step?: string) {
+    super(message);
+    this.name = "OutpostHttpError";
+    this.status = status;
+    this.step = step;
+  }
+}
+
+/** Row summary from `GET /outpost/list`. */
+export interface OutpostSummary {
+  outpostId: string;
+  state: string;
+  instanceName: string;
+  region: string;
+  agentRuntime: string;
+  platform: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Authenticated JSON round-trip against the outpost control plane. Throws
+ * `OutpostHttpError` on any non-2xx (never swallows — hq-never-swallow-errors),
+ * decoding hq-pro's `{ error | message, step }` envelope for the reason. The
+ * `step` is preserved so callers can recognise the `destroy` route's
+ * `teardown-incomplete` 409 (which means "retry", not "failed").
+ */
+export async function outpostRequest<T>(opts: {
+  token: string;
+  path: string;
+  method?: string;
+  query?: Record<string, string>;
+}): Promise<T> {
+  const res = await vaultApiFetch(opts);
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as {
+      error?: unknown;
+      message?: string;
+      step?: string;
+    };
+    const message =
+      typeof body.message === "string"
+        ? body.message
+        : typeof body.error === "string"
+          ? body.error
+          : res.statusText;
+    throw new OutpostHttpError(res.status, message, body.step);
+  }
+  return (await res.json()) as T;
+}
+
+export async function listOutposts(token: string): Promise<OutpostSummary[]> {
+  const data = await outpostRequest<{ outposts: OutpostSummary[] }>({
+    token,
+    path: "/outpost/list",
+  });
+  return data.outposts ?? [];
+}
+
+export async function getOutpostStatus(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/status",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+export async function enableCodex(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/codex/enable",
+    method: "POST",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+export async function regenerateLoginUrl(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/regenerate-login-url",
+    method: "POST",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+export async function destroyOutpost(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/destroy",
+    method: "POST",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+function fail(err: unknown): never {
+  if (err instanceof OutpostHttpError) {
+    console.error(chalk.red(err.message));
+  } else {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+  process.exit(1);
+}
+
+/** Print a top-level object as `key: value`, JSON-ifying nested values. */
+function printKeyValues(obj: Record<string, unknown>): void {
+  for (const [k, v] of Object.entries(obj)) {
+    const rendered = v && typeof v === "object" ? JSON.stringify(v) : String(v);
+    console.log(`${chalk.bold(k)}: ${rendered}`);
+  }
+}
+
+export function registerOutpostsCommand(program: Command): void {
+  const outposts = program
+    .command("outposts")
+    .description("Manage your personal HQ Outposts (EC2 boxes)");
+
+  outposts
+    .command("list")
+    .description("List every Outpost you own")
+    .option("--json", "Emit raw JSON")
+    .action(async function (this: Command, opts: { json?: boolean }) {
+      try {
+        const token = await ensureCognitoToken();
+        const rows = await listOutposts(token);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
+          return;
+        }
+        if (rows.length === 0) {
+          console.log(chalk.gray("You don't own any Outposts yet."));
+          return;
+        }
+        const idW = Math.max(2, ...rows.map((r) => (r.outpostId ?? "").length));
+        const stateW = Math.max(5, ...rows.map((r) => (r.state ?? "").length));
+        const nameW = Math.max(
+          4,
+          ...rows.map((r) => (r.instanceName ?? "").length),
+        );
+        const regionW = Math.max(6, ...rows.map((r) => (r.region ?? "").length));
+        const rtW = Math.max(
+          7,
+          ...rows.map((r) => (r.agentRuntime ?? "").length),
+        );
+        console.log(
+          chalk.bold(
+            [
+              "ID".padEnd(idW),
+              "STATE".padEnd(stateW),
+              "INSTANCE".padEnd(nameW),
+              "REGION".padEnd(regionW),
+              "RUNTIME".padEnd(rtW),
+              "PLATFORM",
+            ].join("  "),
+          ),
+        );
+        for (const r of rows) {
+          console.log(
+            [
+              (r.outpostId ?? "").padEnd(idW),
+              (r.state ?? "").padEnd(stateW),
+              (r.instanceName ?? "").padEnd(nameW),
+              (r.region ?? "").padEnd(regionW),
+              (r.agentRuntime ?? "").padEnd(rtW),
+              r.platform ?? "",
+            ].join("  "),
+          );
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("status")
+    .description("Show live detail for one Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        const status = await getOutpostStatus(token, opts.id);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+          return;
+        }
+        printKeyValues(status);
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("codex-enable")
+    .description("Enable (or retry) Codex on an Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        const result = await enableCodex(token, opts.id);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+          return;
+        }
+        console.log(chalk.green("Codex enablement requested for the Outpost."));
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("login")
+    .description("Request a fresh login URL for an Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        const result = await regenerateLoginUrl(token, opts.id);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+          return;
+        }
+        console.log(
+          chalk.green(
+            "Login-URL regeneration requested. The box mints a fresh URL shortly — " +
+              "check `hq outposts status` to pick it up.",
+          ),
+        );
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("destroy")
+    .description("Tear down (permanently destroy) an Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--yes", "Confirm the irreversible teardown (required)")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; yes?: boolean },
+    ) {
+      const target = opts.id ?? "your primary Outpost";
+      if (!opts.yes) {
+        console.error(
+          chalk.yellow(
+            `This will permanently destroy ${target} and delete its cloud resources. ` +
+              `This cannot be undone.\n` +
+              `Re-run with --yes to confirm: hq outposts destroy${opts.id ? ` --id ${opts.id}` : ""} --yes`,
+          ),
+        );
+        process.exit(1);
+      }
+      try {
+        const token = await ensureCognitoToken();
+        await destroyOutpost(token, opts.id);
+        console.log(chalk.green(`Destroyed ${target}.`));
+      } catch (err) {
+        // A 409 teardown-incomplete is not a failure — the gateway's 30s cap
+        // fired while the Lambda keeps working. The row is preserved and the
+        // operation is idempotent, so tell the caller to retry.
+        if (
+          err instanceof OutpostHttpError &&
+          (err.status === 409 || err.step === "teardown-incomplete")
+        ) {
+          console.log(
+            chalk.yellow(
+              `Teardown still in progress for ${target} — this is expected for large boxes. ` +
+                `Re-run the same destroy command to finish (it's idempotent).`,
+            ),
+          );
+          return;
+        }
+        fail(err);
+      }
+    });
+}

package/src/commands/pack-install.ts

@@ -68,6 +68,80 @@ import {
 import { readCache, listSecretCacheScopes } from '../utils/secrets-cache.js';
 import type { PackManifest, PackContributeKey } from '../types.js';
 
+const PACK_UPDATE_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+const PACK_UPDATE_FETCH_TIMEOUT_MS = 3_000;
+
+interface PackUpdateCacheEntry {
+  latest: string;
+  fetchedAt: number;
+}
+
+interface PackUpdateCacheFile {
+  entries: Record<string, PackUpdateCacheEntry>;
+}
+
+export interface ResolveLatestOptions {
+  forceRefresh?: boolean;
+  now?: number;
+  cacheTtlMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+const gitLsRemoteMemo = new Map<string, string>();
+
+function packUpdateCachePath(): string {
+  return path.join(os.homedir(), '.hq', 'pack-update-cache.json');
+}
+
+function readPackUpdateCache(): PackUpdateCacheFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(packUpdateCachePath(), 'utf-8')) as Partial<PackUpdateCacheFile>;
+    if (!parsed || typeof parsed !== 'object' || !parsed.entries || typeof parsed.entries !== 'object') {
+      return { entries: {} };
+    }
+    return { entries: parsed.entries as Record<string, PackUpdateCacheEntry> };
+  } catch {
+    return { entries: {} };
+  }
+}
+
+function writePackUpdateCache(cache: PackUpdateCacheFile): void {
+  try {
+    const file = packUpdateCachePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache));
+  } catch {
+    // best-effort; update checks must never fail because the cache is unwritable
+  }
+}
+
+function cachedLatest(cacheKey: string, opts: ResolveLatestOptions): string | undefined {
+  if (opts.forceRefresh) return undefined;
+  const entry = readPackUpdateCache().entries[cacheKey];
+  if (!entry || typeof entry.latest !== 'string' || typeof entry.fetchedAt !== 'number') return undefined;
+  const now = opts.now ?? Date.now();
+  const ttl = opts.cacheTtlMs ?? PACK_UPDATE_CACHE_TTL_MS;
+  return now - entry.fetchedAt <= ttl ? entry.latest : undefined;
+}
+
+function storeCachedLatest(cacheKey: string, latest: string, opts: ResolveLatestOptions): void {
+  const cache = readPackUpdateCache();
+  cache.entries[cacheKey] = { latest, fetchedAt: opts.now ?? Date.now() };
+  writePackUpdateCache(cache);
+}
+
+async function latestWithDiskCache(
+  cacheKey: string,
+  opts: ResolveLatestOptions,
+  refresh: () => Promise<string | undefined> | string | undefined,
+): Promise<string | undefined> {
+  const cached = cachedLatest(cacheKey, opts);
+  if (cached) return cached;
+  const latest = await refresh();
+  if (latest) storeCachedLatest(cacheKey, latest, opts);
+  return latest;
+}
+
 // ---------------------------------------------------------------------------
 // Source classification
 // ---------------------------------------------------------------------------
@@ -676,17 +750,37 @@ function rsyncDir(src: string, dest: string): void {
  */
 function isNamedRef(url: string, ref: string): boolean {
   try {
-    const out = execFileSync(
-      'git',
-      ['ls-remote', '--heads', '--tags', url, ref],
-      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
-    );
+    const out = gitLsRemote(['--heads', '--tags', url, ref]);
     return out.trim().length > 0;
   } catch {
     return false;
   }
 }
 
+function gitLsRemote(args: string[]): string {
+  const key = args.join('\0');
+  const cached = gitLsRemoteMemo.get(key);
+  if (cached !== undefined) return cached;
+  const out = execFileSync(
+    'git',
+    ['ls-remote', ...args],
+    { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
+  );
+  gitLsRemoteMemo.set(key, out);
+  return out;
+}
+
+async function fetchLatestNpmVersion(pkg: string, opts: ResolveLatestOptions): Promise<string | undefined> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const res = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`, {
+    headers: { Accept: 'application/json' },
+    signal: AbortSignal.timeout(PACK_UPDATE_FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`registry returned ${res.status}`);
+  const body = (await res.json()) as { version?: unknown };
+  return typeof body.version === 'string' ? body.version : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Update-availability probe (no install) — used by `hq packs update --check-only`
 // ---------------------------------------------------------------------------
@@ -711,6 +805,10 @@ function gitRefFromSource(source: string): string | undefined {
   return ref;
 }
 
+function isFullGitSha(ref: string): boolean {
+  return /^[0-9a-f]{40}$/i.test(ref);
+}
+
 /**
  * Probe whether a newer version of an already-installed pack is available,
  * WITHOUT fetching or installing. Reuses the same git/npm primitives as the
@@ -720,10 +818,11 @@ function gitRefFromSource(source: string): string | undefined {
  * @param source         the stamped `source:` from the installed package.yaml
  * @param installedVersion the installed pack's manifest `version` (npm compare)
  */
-export function resolveLatest(
+export async function resolveLatest(
   source: string,
   installedVersion?: string,
-): LatestResult {
+  opts: ResolveLatestOptions = {},
+): Promise<LatestResult> {
   let transport: Transport;
   try {
     transport = classify(source);
@@ -755,15 +854,14 @@ export function resolveLatest(
     const current =
       installedVersion ?? (source.lastIndexOf('@') > 0 ? source.slice(source.lastIndexOf('@') + 1) : undefined);
     try {
-      const latest = execFileSync('npm', ['view', pkg, 'version'], {
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-      }).trim();
+      const latest = await latestWithDiskCache(`npm:${pkg}`, opts, () =>
+        fetchLatestNpmVersion(pkg, opts),
+      );
       const updateAvailable =
         current && latest ? semverGt(latest, current) : null;
       return { transport, current, latest, updateAvailable };
     } catch (e) {
-      return { transport, current, updateAvailable: null, error: `npm view failed: ${(e as Error).message}` };
+      return { transport, current, updateAvailable: null, error: `npm registry check failed: ${(e as Error).message}` };
     }
   }
 
@@ -778,13 +876,12 @@ export function resolveLatest(
   const current = gitRefFromSource(source);
   // If install followed a named ref (branch/tag), compare that ref's tip;
   // otherwise (default SHA-pin) compare the default branch HEAD.
-  const refArg = current && isNamedRef(url, current) ? current : 'HEAD';
+  const refArg = current && !isFullGitSha(current) && isNamedRef(url, current) ? current : 'HEAD';
   try {
-    const out = execFileSync('git', ['ls-remote', url, refArg], {
-      encoding: 'utf-8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    const latest = out.split(/\s+/)[0] || undefined;
+    const latest = await latestWithDiskCache(`git:${url}#${refArg}`, opts, () => {
+      const out = gitLsRemote([url, refArg]).trim();
+      return out.split(/\s+/)[0] || undefined;
+    });
     const updateAvailable =
       current && latest ? !latest.startsWith(current) && !current.startsWith(latest) : null;
     return { transport, current, latest, updateAvailable };

package/src/commands/pack-update-cache.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+
+vi.mock('child_process', () => ({
+  execFileSync: vi.fn(),
+  spawnSync: vi.fn(() => ({ status: 0 })),
+}));
+
+vi.mock('../utils/vault-api.js', () => ({
+  vaultApiFetchPublic: vi.fn(),
+}));
+
+const tmpHome = path.join(os.tmpdir(), `hq-pack-update-cache-${process.pid}`);
+
+beforeEach(() => {
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.mkdirSync(tmpHome, { recursive: true });
+  vi.stubEnv('HOME', tmpHome);
+  vi.mocked(execFileSync).mockReset();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+async function loadModule() {
+  vi.resetModules();
+  return await import('./pack-install.js');
+}
+
+describe('resolveLatest pack update cache', () => {
+  it('fetches npm registry metadata over HTTP once, then compares cached latest against the installed version at read time', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: '2.0.0' }),
+    } as unknown as Response);
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { resolveLatest } = await loadModule();
+
+    const staleInstall = await resolveLatest('@scope/pack@1.0.0', '1.0.0', {
+      forceRefresh: true,
+    });
+    const currentInstall = await resolveLatest('@scope/pack@1.0.0', '2.0.0');
+
+    expect(staleInstall).toMatchObject({
+      transport: 'npm',
+      current: '1.0.0',
+      latest: '2.0.0',
+      updateAvailable: true,
+    });
+    expect(currentInstall).toMatchObject({
+      transport: 'npm',
+      current: '2.0.0',
+      latest: '2.0.0',
+      updateAvailable: false,
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(execFileSync)).not.toHaveBeenCalledWith(
+      'npm',
+      ['view', '@scope/pack', 'version'],
+      expect.anything(),
+    );
+    expect(fs.existsSync(path.join(tmpHome, '.hq', 'pack-update-cache.json'))).toBe(true);
+  });
+
+  it('bypasses a fresh npm cache entry when forceRefresh is set', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ version: '2.0.0' }),
+      } as unknown as Response)
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ version: '3.0.0' }),
+      } as unknown as Response);
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { resolveLatest } = await loadModule();
+
+    await resolveLatest('@scope/pack@1.0.0', '1.0.0', { forceRefresh: true });
+    const refreshed = await resolveLatest('@scope/pack@1.0.0', '1.0.0', {
+      forceRefresh: true,
+    });
+
+    expect(refreshed).toMatchObject({
+      latest: '3.0.0',
+      updateAvailable: true,
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('shares git ls-remote probes by URL and ref within one process', async () => {
+    vi.mocked(execFileSync).mockImplementation((_cmd, args) => {
+      const argv = args as string[];
+      if (argv[1] === '--heads') return '';
+      if (argv[0] === 'ls-remote') return 'abcdef1234567890\tHEAD\n';
+      throw new Error(`unexpected command: ${argv.join(' ')}`);
+    });
+
+    const { resolveLatest } = await loadModule();
+
+    const first = await resolveLatest('https://example.test/repo.git#123456', '1.0.0');
+    const second = await resolveLatest('https://example.test/repo.git#123456', '1.0.0');
+
+    expect(first.latest).toBe('abcdef1234567890');
+    expect(second.latest).toBe('abcdef1234567890');
+    const lsRemoteCalls = vi
+      .mocked(execFileSync)
+      .mock.calls.filter(([cmd, args]) => cmd === 'git' && (args as string[])[0] === 'ls-remote');
+    expect(lsRemoteCalls).toHaveLength(2);
+  });
+
+  it('uses a fresh git disk cache entry without probing git for SHA-pinned sources', async () => {
+    const installedSha = '1111111111111111111111111111111111111111';
+    vi.mocked(execFileSync).mockImplementation((_cmd, args) => {
+      const argv = args as string[];
+      if (argv[0] === 'ls-remote') return 'abcdef1234567890\tHEAD\n';
+      throw new Error(`unexpected command: ${argv.join(' ')}`);
+    });
+
+    const firstModule = await loadModule();
+    await firstModule.resolveLatest(`https://example.test/repo.git#${installedSha}`, '1.0.0', {
+      forceRefresh: true,
+    });
+
+    vi.mocked(execFileSync).mockReset();
+    const secondModule = await loadModule();
+    const cached = await secondModule.resolveLatest(
+      `https://example.test/repo.git#${installedSha}`,
+      '1.0.0',
+    );
+
+    expect(cached).toMatchObject({
+      transport: 'git',
+      current: installedSha,
+      latest: 'abcdef1234567890',
+      updateAvailable: true,
+    });
+    expect(vi.mocked(execFileSync)).not.toHaveBeenCalled();
+  });
+});