@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/utils/registry-client.ts

@@ -1,204 +0,0 @@
-/**
- * Registry client — reads registry URL from packages/sources.yaml and provides
- * API methods for the HQ package registry (US-004 base, US-005 full client).
- *
- * Auth tokens are NEVER written to stdout or logs.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { resolveDefaultHqRoot } from './cognito-session.js';
-import { parseUserYaml } from './user-yaml-error.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface SourceEntry {
-  name: string;
-  url: string;
-  type: string;
-  auth: string;
-}
-
-interface SourcesFile {
-  sources: SourceEntry[];
-}
-
-export interface PackageMeta {
-  slug: string;
-  name: string;
-  description: string;
-  tier: string;
-  latest_version: string;
-  author?: string;
-}
-
-export interface PackageListResponse {
-  packages: PackageMeta[];
-}
-
-export interface PackageResponse {
-  package: PackageMeta;
-  versions: { version: string; published_at: string }[];
-}
-
-export interface EntitlementEntry {
-  slug: string;
-  tier: string;
-  granted_at: string;
-  expires_at?: string;
-}
-
-export interface EntitlementListResponse {
-  entitlements: EntitlementEntry[];
-}
-
-export interface EntitlementCheckResponse {
-  entitled: boolean;
-  tier?: string;
-  expires_at?: string;
-}
-
-export interface DownloadResponse {
-  url: string;
-  sha256: string;
-  signature?: string;
-}
-
-// ---------------------------------------------------------------------------
-// URL helper (unchanged from US-004)
-// ---------------------------------------------------------------------------
-
-/**
- * Read the registry URL from packages/sources.yaml in the user's HQ root.
- * Returns the URL of the first source entry.
- * Throws if sources.yaml is missing or has no sources.
- */
-export function getRegistryUrl(): string {
-  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
-  const sourcesPath = path.join(hqRoot, 'packages', 'sources.yaml');
-
-  if (!fs.existsSync(sourcesPath)) {
-    throw new Error(
-      `No packages/sources.yaml found at ${sourcesPath}. Is your HQ packages directory set up?`
-    );
-  }
-
-  const content = fs.readFileSync(sourcesPath, 'utf-8');
-  const parsed = parseUserYaml<SourcesFile>(content, sourcesPath);
-
-  if (!parsed?.sources?.length) {
-    throw new Error('No sources defined in packages/sources.yaml');
-  }
-
-  return parsed.sources[0].url;
-}
-
-// ---------------------------------------------------------------------------
-// RegistryClient
-// ---------------------------------------------------------------------------
-
-export class RegistryClient {
-  private baseUrl: string;
-  private authToken?: string;
-
-  constructor(baseUrl: string, authToken?: string) {
-    this.baseUrl = baseUrl.replace(/\/+$/, '');
-    this.authToken = authToken;
-  }
-
-  // ---- helpers ----
-
-  private headers(auth: boolean): Record<string, string> {
-    const h: Record<string, string> = {
-      Accept: 'application/json',
-    };
-    if (auth && this.authToken) {
-      h['Authorization'] = `Bearer ${this.authToken}`;
-    }
-    return h;
-  }
-
-  private async request<T>(
-    method: string,
-    urlPath: string,
-    opts: { auth?: boolean; body?: unknown; timeout?: number } = {}
-  ): Promise<T> {
-    const auth = opts.auth ?? false;
-    const url = `${this.baseUrl}${urlPath}`;
-
-    const init: RequestInit = {
-      method,
-      headers: this.headers(auth),
-      signal: AbortSignal.timeout(opts.timeout ?? 30_000),
-    };
-
-    if (opts.body) {
-      (init.headers as Record<string, string>)['Content-Type'] =
-        'application/json';
-      init.body = JSON.stringify(opts.body);
-    }
-
-    const res = await fetch(url, init);
-
-    if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      throw new Error(
-        `Registry API ${method} ${urlPath} failed (${res.status}): ${text}`
-      );
-    }
-
-    return (await res.json()) as T;
-  }
-
-  // ---- public (no auth) ----
-
-  async listPackages(opts?: {
-    tier?: string;
-    q?: string;
-  }): Promise<PackageListResponse> {
-    const params = new URLSearchParams();
-    if (opts?.tier) params.set('tier', opts.tier);
-    if (opts?.q) params.set('q', opts.q);
-    const qs = params.toString();
-    return this.request<PackageListResponse>(
-      'GET',
-      `/packages${qs ? `?${qs}` : ''}`
-    );
-  }
-
-  async getPackage(slug: string): Promise<PackageResponse> {
-    return this.request<PackageResponse>('GET', `/packages/${encodeURIComponent(slug)}`);
-  }
-
-  // ---- auth required ----
-
-  async getMyEntitlements(): Promise<EntitlementListResponse> {
-    return this.request<EntitlementListResponse>('GET', '/entitlements', {
-      auth: true,
-    });
-  }
-
-  async checkEntitlement(slug: string): Promise<EntitlementCheckResponse> {
-    return this.request<EntitlementCheckResponse>(
-      'GET',
-      `/entitlements/${encodeURIComponent(slug)}`,
-      { auth: true }
-    );
-  }
-
-  async getDownloadUrl(
-    slug: string,
-    version?: string
-  ): Promise<DownloadResponse> {
-    const params = new URLSearchParams();
-    if (version) params.set('version', version);
-    const qs = params.toString();
-    return this.request<DownloadResponse>(
-      'GET',
-      `/packages/${encodeURIComponent(slug)}/download${qs ? `?${qs}` : ''}`,
-      { auth: true }
-    );
-  }
-}

package/src/utils/registry.ts

@@ -1,90 +0,0 @@
-/**
- * Registry YAML helpers — read/write packages/registry.yaml (US-005)
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import * as yaml from 'js-yaml';
-import { parseUserYaml } from './user-yaml-error.js';
-
-export interface RegistryEntry {
-  name: string;
-  slug: string;
-  version: string;
-  source: string;
-  license_key?: string;
-  scope?: string;
-  installed_at: string;
-  updated_at: string;
-}
-
-interface RegistryFile {
-  packages: RegistryEntry[];
-}
-
-function registryPath(hqRoot: string): string {
-  return path.resolve(hqRoot, 'packages', 'registry.yaml');
-}
-
-/**
- * Read all entries from packages/registry.yaml.
- * Returns an empty array if the file does not exist.
- */
-export function readRegistry(hqRoot: string): RegistryEntry[] {
-  const filePath = registryPath(hqRoot);
-  if (!fs.existsSync(filePath)) {
-    return [];
-  }
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const parsed = parseUserYaml<RegistryFile | null>(content, filePath);
-  return parsed?.packages ?? [];
-}
-
-/**
- * Write the full registry back to packages/registry.yaml.
- */
-export function writeRegistry(
-  hqRoot: string,
-  entries: RegistryEntry[]
-): void {
-  const filePath = registryPath(hqRoot);
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  const content = yaml.dump(
-    { packages: entries },
-    { lineWidth: 120, noRefs: true }
-  );
-  fs.writeFileSync(filePath, content, 'utf-8');
-}
-
-/**
- * Add or update an entry in packages/registry.yaml.
- * If an entry with the same slug exists, it is replaced.
- */
-export function addToRegistry(
-  hqRoot: string,
-  entry: RegistryEntry
-): void {
-  const entries = readRegistry(hqRoot);
-  const idx = entries.findIndex((e) => e.slug === entry.slug);
-  if (idx >= 0) {
-    entries[idx] = entry;
-  } else {
-    entries.push(entry);
-  }
-  writeRegistry(hqRoot, entries);
-}
-
-/**
- * Remove an entry by slug from packages/registry.yaml.
- * No-op if the slug is not found.
- */
-export function removeFromRegistry(
-  hqRoot: string,
-  slug: string
-): void {
-  const entries = readRegistry(hqRoot).filter((e) => e.slug !== slug);
-  writeRegistry(hqRoot, entries);
-}

package/src/utils/resolve-vault-credential.test.ts

@@ -1,69 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-vi.mock("./cognito-session.js", () => ({
-  ensureCognitoToken: vi.fn(async () => "cognito-token"),
-}));
-
-import { ensureCognitoToken } from "./cognito-session.js";
-import {
-  assertCognitoOnlyCommand,
-  HQ_API_KEY_PREFIX,
-  peekHqApiKey,
-  resolveVaultCredential,
-} from "./resolve-vault-credential.js";
-
-afterEach(() => {
-  delete process.env.HQ_API_KEY;
-  vi.clearAllMocks();
-});
-
-describe("peekHqApiKey", () => {
-  it("returns undefined when unset or blank", () => {
-    expect(peekHqApiKey()).toBeUndefined();
-    process.env.HQ_API_KEY = "   ";
-    expect(peekHqApiKey()).toBeUndefined();
-  });
-
-  it("returns trimmed value when set", () => {
-    process.env.HQ_API_KEY = "  hqk_abc  ";
-    expect(peekHqApiKey()).toBe("hqk_abc");
-  });
-});
-
-describe("resolveVaultCredential", () => {
-  it("uses Cognito when HQ_API_KEY is unset", async () => {
-    const cred = await resolveVaultCredential();
-    expect(cred).toEqual({ kind: "cognito", token: "cognito-token" });
-    expect(ensureCognitoToken).toHaveBeenCalledOnce();
-  });
-
-  it("returns api-key credential for hqk_ without calling Cognito", async () => {
-    process.env.HQ_API_KEY = `${HQ_API_KEY_PREFIX}valid`;
-    const cred = await resolveVaultCredential();
-    expect(cred).toEqual({
-      kind: "api-key",
-      token: `${HQ_API_KEY_PREFIX}valid`,
-    });
-    expect(ensureCognitoToken).not.toHaveBeenCalled();
-  });
-
-  it("fails closed on invalid prefix (no Cognito fallback)", async () => {
-    process.env.HQ_API_KEY = "hqk_totally_invalid".replace("hqk_", "bad_");
-    process.env.HQ_API_KEY = "not_a_vault_key";
-    await expect(resolveVaultCredential()).rejects.toThrow(/must start with/);
-    expect(ensureCognitoToken).not.toHaveBeenCalled();
-  });
-});
-
-describe("assertCognitoOnlyCommand", () => {
-  it("no-ops when HQ_API_KEY unset", () => {
-    expect(() => assertCognitoOnlyCommand("secrets list")).not.toThrow();
-  });
-
-  it("throws when HQ_API_KEY is set", () => {
-    process.env.HQ_API_KEY = `${HQ_API_KEY_PREFIX}x`;
-    expect(() => assertCognitoOnlyCommand("secrets list")).toThrow(
-      /not supported for API keys/,
-    );
-  });
-});

package/src/utils/resolve-vault-credential.ts

@@ -1,60 +0,0 @@
-import { ensureCognitoToken } from "./cognito-session.js";
-
-/** Vault API keys issued by `hq api-keys create` (hq-pro). */
-export const HQ_API_KEY_PREFIX = "hqk_";
-
-export type VaultCredential =
-  | { kind: "api-key"; token: string }
-  | { kind: "cognito"; token: string };
-
-/**
- * Raw HQ_API_KEY from the environment, trimmed. Undefined when unset/empty.
- * Does not validate prefix — use {@link resolveVaultCredential} for that.
- */
-export function peekHqApiKey(): string | undefined {
-  const raw = process.env.HQ_API_KEY;
-  if (raw === undefined) return undefined;
-  const trimmed = raw.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-/**
- * Resolve vault auth for CLI commands.
- *
- * When `HQ_API_KEY` is set it is authoritative: must be a vault key (`hqk_…`)
- * and Cognito is never used as a fallback (fail-closed). When unset, uses the
- * cached Cognito session (interactive login if needed).
- */
-export async function resolveVaultCredential(options?: {
-  interactive?: boolean;
-}): Promise<VaultCredential> {
-  const apiKey = peekHqApiKey();
-  if (apiKey !== undefined) {
-    if (!apiKey.startsWith(HQ_API_KEY_PREFIX)) {
-      throw new Error(
-        `HQ_API_KEY must start with '${HQ_API_KEY_PREFIX}' (vault API key). ` +
-          `Got a value that is not a vault key — refusing to fall back to Cognito. ` +
-          `Unset HQ_API_KEY to use your session, or create a key with \`hq api-keys create\`.`,
-      );
-    }
-    return { kind: "api-key", token: apiKey };
-  }
-
-  const token = await ensureCognitoToken({
-    interactive: options?.interactive,
-  });
-  return { kind: "cognito", token };
-}
-
-/**
- * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
- * (list, set, ACL, api-keys admin, etc.).
- */
-export function assertCognitoOnlyCommand(commandLabel: string): void {
-  if (peekHqApiKey() === undefined) return;
-  throw new Error(
-    `HQ_API_KEY is set; '${commandLabel}' is not supported for API keys. ` +
-      `API keys support scoped secret reads via \`hq secrets get\`, \`hq secrets exec\`, ` +
-      `and \`hq secrets env\`. Unset HQ_API_KEY to use your Cognito session.`,
-  );
-}

package/src/utils/sandbox-runner-client.test.ts

@@ -1,279 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { SandboxRunnerClient } from "./sandbox-runner-client.js";
-
-function jsonRes(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { "Content-Type": "application/json" },
-  });
-}
-
-describe("SandboxRunnerClient", () => {
-  it("posts jobs to the configured runner URL with the caller JWT", async () => {
-    const fetchImpl = vi.fn<typeof fetch>(async () =>
-      jsonRes({ jobId: "job_1", status: "queued" }),
-    );
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example/",
-      fetchImpl,
-    });
-
-    const result = await client.startJob("jwt-token", {
-      companyUid: "cmp_123",
-      secretNames: ["API_KEY"],
-      command: "node script.js --x",
-    });
-
-    expect(result).toEqual({ jobId: "job_1", status: "queued" });
-    expect(fetchImpl).toHaveBeenCalledWith("https://runner.example/jobs", {
-      method: "POST",
-      headers: {
-        Authorization: "Bearer jwt-token",
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        companyUid: "cmp_123",
-        secretNames: ["API_KEY"],
-        command: "node script.js --x",
-      }),
-    });
-  });
-
-  it("retries startJob after fetch rejects twice then succeeds", async () => {
-    const fetchImpl = vi
-      .fn<typeof fetch>()
-      .mockRejectedValueOnce(new TypeError("fetch failed"))
-      .mockRejectedValueOnce(new Error("ECONNRESET"))
-      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }));
-    const sleep = vi.fn(async () => {});
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-      sleep,
-    });
-
-    await expect(
-      client.startJob("jwt-token", {
-        companyUid: "cmp_123",
-        secretNames: ["API_KEY"],
-        command: "node script.js",
-      }),
-    ).resolves.toEqual({ jobId: "job_1", status: "queued" });
-    expect(fetchImpl).toHaveBeenCalledTimes(3);
-    expect(sleep).toHaveBeenCalledTimes(2);
-  });
-
-  it("retries startJob after a retryable 503 response", async () => {
-    const fetchImpl = vi
-      .fn<typeof fetch>()
-      .mockResolvedValueOnce(jsonRes({ message: "warming up" }, 503))
-      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }));
-    const sleep = vi.fn(async () => {});
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-      sleep,
-    });
-
-    await expect(
-      client.startJob("jwt-token", {
-        companyUid: "cmp_123",
-        secretNames: ["API_KEY"],
-        command: "node script.js",
-      }),
-    ).resolves.toEqual({ jobId: "job_1", status: "queued" });
-    expect(fetchImpl).toHaveBeenCalledTimes(2);
-    expect(sleep).toHaveBeenCalledTimes(1);
-  });
-
-  it.each([400, 401])("does not retry startJob on %i responses", async (status) => {
-    const fetchImpl = vi.fn<typeof fetch>(async () =>
-      jsonRes({ message: "bad request" }, status),
-    );
-    const sleep = vi.fn(async () => {});
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-      sleep,
-    });
-
-    await expect(
-      client.startJob("jwt-token", {
-        companyUid: "cmp_123",
-        secretNames: ["API_KEY"],
-        command: "node script.js",
-      }),
-    ).rejects.toThrow("Sandbox Runner rejected job: bad request");
-    expect(fetchImpl).toHaveBeenCalledTimes(1);
-    expect(sleep).not.toHaveBeenCalled();
-  });
-
-  it("throws a clear exhaustion error after maxAttempts transient failures", async () => {
-    const fetchImpl = vi
-      .fn<typeof fetch>()
-      .mockRejectedValue(new TypeError("fetch failed"));
-    const sleep = vi.fn(async () => {});
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-      retry: { maxAttempts: 3 },
-      sleep,
-    });
-
-    await expect(
-      client.startJob("jwt-token", {
-        companyUid: "cmp_123",
-        secretNames: ["API_KEY"],
-        command: "node script.js",
-      }),
-    ).rejects.toThrow(
-      "Sandbox Runner did not respond after 3 attempts (cold start or transient network); last error: fetch failed",
-    );
-    expect(fetchImpl).toHaveBeenCalledTimes(3);
-    expect(sleep).toHaveBeenCalledTimes(2);
-  });
-
-  it("polls queued and running states until succeeded", async () => {
-    const fetchImpl = vi
-      .fn<typeof fetch>()
-      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }))
-      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "running" }))
-      .mockResolvedValueOnce(
-        jsonRes({
-          jobId: "job_1",
-          status: "succeeded",
-          output: "ok\n",
-          exitCode: 0,
-          success: true,
-        }),
-      );
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-    });
-
-    const result = await client.pollJob("jwt-token", "job_1", {
-      intervalMs: 0,
-    });
-
-    expect(result).toEqual({
-      jobId: "job_1",
-      status: "succeeded",
-      output: "ok\n",
-      exitCode: 0,
-      success: true,
-    });
-    expect(fetchImpl).toHaveBeenCalledTimes(3);
-    expect(fetchImpl).toHaveBeenNthCalledWith(
-      1,
-      "https://runner.example/jobs/job_1",
-      { headers: { Authorization: "Bearer jwt-token" } },
-    );
-  });
-
-  it("tolerates one transient fetch rejection while polling", async () => {
-    const fetchImpl = vi
-      .fn<typeof fetch>()
-      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }))
-      .mockRejectedValueOnce(new TypeError("fetch failed"))
-      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "running" }))
-      .mockResolvedValueOnce(
-        jsonRes({
-          jobId: "job_1",
-          status: "succeeded",
-          output: "ok\n",
-          exitCode: 0,
-          success: true,
-        }),
-      );
-    const sleep = vi.fn(async () => {});
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-      sleep,
-    });
-
-    await expect(
-      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
-    ).resolves.toMatchObject({
-      jobId: "job_1",
-      status: "succeeded",
-      output: "ok\n",
-      exitCode: 0,
-      success: true,
-    });
-    expect(fetchImpl).toHaveBeenCalledTimes(4);
-  });
-
-  it("returns failed terminal jobs with error details", async () => {
-    const fetchImpl = vi.fn<typeof fetch>(async () =>
-      jsonRes({
-        jobId: "job_1",
-        status: "failed",
-        output: "boom\n",
-        exitCode: 2,
-        success: false,
-      }),
-    );
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-    });
-
-    await expect(
-      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
-    ).resolves.toMatchObject({
-      jobId: "job_1",
-      status: "failed",
-      error: undefined,
-      output: "boom\n",
-      exitCode: 2,
-      success: false,
-    });
-  });
-
-  // The wire shape the server actually sends when it could not RUN the command:
-  // a reason, and no exit code, because nothing ever exited.
-  it("surfaces the reason on a job the sandbox could not execute", async () => {
-    const fetchImpl = vi.fn<typeof fetch>(async () =>
-      jsonRes({
-        jobId: "job_1",
-        status: "failed",
-        error: "Sandbox max-exec exceeded (28000ms)",
-      }),
-    );
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-    });
-
-    await expect(
-      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
-    ).resolves.toMatchObject({
-      jobId: "job_1",
-      status: "failed",
-      error: "Sandbox max-exec exceeded (28000ms)",
-      exitCode: undefined,
-      output: undefined,
-    });
-  });
-
-  it("uses the requested job id when the live status response omits it", async () => {
-    const fetchImpl = vi.fn<typeof fetch>(async () =>
-      jsonRes({ status: "succeeded", output: "ok\n" }),
-    );
-    const client = new SandboxRunnerClient({
-      baseUrl: "https://runner.example",
-      fetchImpl,
-    });
-
-    await expect(client.getJob("jwt-token", "job_live")).resolves.toEqual({
-      jobId: "job_live",
-      status: "succeeded",
-      output: "ok\n",
-      error: undefined,
-      exitCode: undefined,
-      success: undefined,
-    });
-  });
-});