@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/types.ts

@@ -1,146 +0,0 @@
-/**
- * HQ Module Manifest Types (US-001)
- *
- * `modules.yaml` hosts two kinds of entries, discriminated by `strategy`:
- *   - link | merge | copy  → git-repo-based module sync (existing flow)
- *   - package              → hq-pack content pack installed via `hq install`
- *                            (new in hq-core v12.0.0; see
- *                            knowledge/public/hq-core/package-yaml-spec.md)
- */
-
-import type { ContributionKey } from './utils/contribution-table.js';
-
-export type LegacyStrategy = 'link' | 'merge' | 'copy';
-export type SyncStrategy = LegacyStrategy | 'package';
-export type AccessLevel = 'public' | 'team' | `role:${string}`;
-
-export interface PathMapping {
-  src: string;   // Path within module repo
-  dest: string;  // Path in HQ tree (relative to HQ root)
-}
-
-export interface LegacyModuleDefinition {
-  name: string;
-  repo: string;              // Git URL (https or git@)
-  branch?: string;           // Default: main
-  strategy: LegacyStrategy;
-  paths: PathMapping[];      // What to sync and where
-  access?: AccessLevel;
-}
-
-export interface PackModuleDefinition {
-  name: string;              // e.g. 'hq-pack-gstack'
-  strategy: 'package';
-  source: string;            // '@scope/name@ver' | git URL#sha | local path
-  version?: string;          // semver from the pack's package.yaml
-  installed_at?: string;     // e.g. 'packages/hq-pack-gstack'
-  installed_at_iso?: string; // ISO timestamp
-  resolved_sha?: string;     // git transport only
-  access?: AccessLevel;
-}
-
-export type ModuleDefinition = LegacyModuleDefinition | PackModuleDefinition;
-
-export interface ModulesManifest {
-  version: '1';
-  modules: ModuleDefinition[];
-}
-
-export interface ModuleLock {
-  version: '1';
-  locked: Record<string, string>; // module name -> commit SHA
-}
-
-export interface SyncState {
-  version: '1';
-  files: Record<string, {
-    hash: string;          // SHA256 of file content at sync time
-    syncedAt: string;      // ISO timestamp
-    fromModule: string;    // Module that provided this file
-  }>;
-}
-
-export interface SyncResult {
-  module: string;
-  success: boolean;
-  action: 'cloned' | 'fetched' | 'synced' | 'skipped';
-  message?: string;
-  filesChanged?: number;
-}
-
-// ---------------------------------------------------------------------------
-// hq-pack content-pack manifest (packages/{name}/package.yaml).
-//
-// Distinct from packages/hq-cli/src/schemas/hq-package.schema.json, which
-// covers the entitlement-gated registry flow (`hq packages install <slug>`).
-// ---------------------------------------------------------------------------
-
-/**
- * The `contributes.*` keys a pack may declare. DERIVED (US-003) from the single
- * declarative contribution registry in `utils/contribution-table.ts` -- adding
- * a contribution type is one row there, and this union updates automatically.
- * Do NOT restate the keys here.
- */
-export type PackContributeKey = ContributionKey;
-
-/**
- * Pack authorship attribution (US-001). OPTIONAL and backwards-compatible —
- * packs published before this field still validate. When present, install can
- * attribute the pack to a creator: `uid` is the HQ person UID, `handle` the
- * creator's marketplace handle, `displayName` the human-readable name.
- */
-export interface PackAuthor {
-  uid: string;
-  handle: string;
-  displayName: string;
-}
-
-/**
- * A pack-to-pack dependency (M0). OPTIONAL and backwards-compatible — packs
- * published before this field omit `requires.packs` and install unchanged. When
- * present, each entry names another content pack that MUST already be installed
- * before this one (enforced at install time by `assertPackDependencies`, which
- * tracks installed packs by FILESYSTEM PRESENCE — not `modules.yaml`). `version`
- * is an optional semver RANGE the installed dependency must satisfy.
- */
-export interface PackDependency {
-  name: string;     // ^hq-pack-[a-z0-9][a-z0-9-]*$
-  version?: string; // optional semver range
-}
-
-export interface PackManifest {
-  name: string;                 // ^hq-pack-[a-z0-9][a-z0-9-]*$
-  version: string;              // semver
-  publisher: string;            // @scope
-  access: 'public' | 'private';
-  /**
-   * Host + pack prerequisites. `hqCore` is a required semver RANGE the host HQ
-   * must satisfy. `packs` (M0) is an OPTIONAL list of other content packs that
-   * must be installed first — see PackDependency.
-   */
-  requires: { hqCore: string; packs?: PackDependency[] };
-  contributes: Partial<Record<PackContributeKey, string[]>>;
-  description?: string;
-  license?: string;
-  repository?: string;
-  keywords?: string[];
-  conditional?: string;         // bash predicate; skip install if exits non-zero
-  /**
-   * Pack authorship attribution (US-001). Optional — absent on legacy packs.
-   */
-  author?: PackAuthor;
-  /**
-   * Declared capabilities the pack touches (US-001), e.g. hooks/scripts/
-   * network/fs/secrets. Optional, free-form string entries — surfaced to the
-   * user at install time for an at-a-glance trust signal. Reserved here; not
-   * yet enforced.
-   */
-  capabilities?: string[];
-  /**
-   * Post-install initialization (US-004/US-005). Optional — absent on legacy
-   * packs. `entrypoint` names a declared `contributes.skills`/`commands` entry
-   * (slash-normalized); `prompt` is optional free-text prose (PHASE 1 does NOT
-   * render the prose — only an auto-generated get-started line from entrypoint).
-   */
-  initialization?: { entrypoint: string; prompt?: string };
-}

package/src/utils/__fixtures__/scan-packages.generated-block.sh

@@ -1,23 +0,0 @@
-# >>> BEGIN GENERATED contribution table (US-003) — do not edit by hand
-# Generated from hq-cli/src/utils/contribution-table.ts by
-# hq-cli/scripts/generate-scan-packages-table.mjs. Regenerate with:
-#   node scripts/generate-scan-packages-table.mjs --write core/scripts/scan-packages.sh
-# Each row is "payload|host|wire" (payload uses {item} for the name).
-# bash 3.2-compatible (macOS default bash has no associative arrays):
-# a plain indexed key list + a generated case-lookup function.
-CONTRIB_KEYS=(workers knowledge skills commands hooks policies scripts mcp)
-# contrib_row <key> -> echoes "payload|host|wire", empty if unknown.
-contrib_row() {
-  case "$1" in
-    workers) printf '%s' 'workers/{item}|core/workers/public|symlink' ;;
-    knowledge) printf '%s' 'knowledge/{item}|core/knowledge/public|symlink' ;;
-    skills) printf '%s' 'skills/{item}|.claude/skills|symlink' ;;
-    commands) printf '%s' 'commands/{item}.md|.claude/commands|symlink' ;;
-    hooks) printf '%s' 'hooks/{item}.sh|.claude/hooks|symlink' ;;
-    policies) printf '%s' 'policies/{item}.md|core/policies|symlink' ;;
-    scripts) printf '%s' 'scripts/{item}|core/scripts|symlink' ;;
-    mcp) printf '%s' 'mcp/{item}.json|merge:claude+codex|merge' ;;
-    *) return 0 ;;
-  esac
-}
-# <<< END GENERATED contribution table

package/src/utils/auth-error.test.ts

@@ -1,40 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { AuthError, isAuthError } from "./auth-error.js";
-
-describe("isAuthError", () => {
-  // HQ-CLI-8: an expired HQ session surfaced as a vault 401 during company
-  // slug resolution. The user fixes it with `hq login`; it should skip Sentry.
-  it("classifies an AuthError as an expected auth state (skip Sentry)", () => {
-    expect(isAuthError(new AuthError())).toBe(true);
-  });
-
-  it("uses an actionable default message", () => {
-    expect(new AuthError().message).toMatch(/hq login/);
-  });
-
-  it("preserves a custom user-facing message verbatim", () => {
-    const msg = "Sign in again before continuing.";
-    expect(new AuthError(msg).message).toBe(msg);
-  });
-
-  it("keeps instanceof across the transpile target", () => {
-    const err = new AuthError();
-    expect(err).toBeInstanceOf(AuthError);
-    expect(err).toBeInstanceOf(Error);
-    expect(err.name).toBe("AuthError");
-  });
-
-  // A genuine defect must still reach Sentry — only the typed auth class is
-  // diverted, so real bugs are never silently swallowed.
-  it("does NOT match a plain Error (so real faults still report)", () => {
-    expect(isAuthError(new Error("Unauthorized"))).toBe(false);
-    expect(isAuthError(new Error("Your HQ session has expired. Run `hq login`."))).toBe(false);
-  });
-
-  it("does NOT match non-error values", () => {
-    expect(isAuthError(null)).toBe(false);
-    expect(isAuthError(undefined)).toBe(false);
-    expect(isAuthError("Unauthorized")).toBe(false);
-    expect(isAuthError({ message: "Unauthorized" })).toBe(false);
-  });
-});

package/src/utils/auth-error.ts

@@ -1,42 +0,0 @@
-// src/utils/auth-error.ts
-//
-// Classify expired or missing HQ session conditions surfaced by the vault API
-// (HQ-CLI-8). These are expected, user-actionable auth states — NOT hq-cli
-// defects — so the top-level catch prints the message and exits non-zero but
-// SKIPS Sentry capture, mirroring the company-selection (HQ-CLI-7),
-// expected-user-error (HQ-CLI-6), and environmental-FS (HQ-CLI-2) carve-outs.
-//
-// HQ-CLI-8: a user ran `hq integrations list --company liverecover --json`
-// with an expired HQ session. Company-slug resolution tried the caller-scoped
-// `/entity/check-slug/me` lookup and the global `/entity/by-slug/company/...`
-// fallback; both returned 401 Unauthorized. The plain Error that bubbled up
-// looked like a company-resolution defect and was shipped to Sentry as a fatal.
-// A 401 from vault resolution means the caller needs to run `hq login`; the
-// code cannot repair an expired token, so this is normal auth state, not a
-// crash to triage.
-
-/**
- * Thrown when the vault API reports the caller's HQ session is expired or
- * missing. The `message` is user-facing and actionable; the top-level handler
- * prints it verbatim and skips Sentry capture.
- */
-export class AuthError extends Error {
-  constructor(
-    message = "Your HQ session has expired or you're not signed in. Run `hq login` and try again.",
-  ) {
-    super(message);
-    this.name = "AuthError";
-    // Preserve `instanceof` across the TS→ES5/ES2015 transpile target.
-    Object.setPrototypeOf(this, AuthError.prototype);
-  }
-}
-
-/**
- * True when `err` is an expected auth-state failure the user must resolve with
- * `hq login`. Callers should print `err.message` and SKIP Sentry capture while
- * preserving a non-zero exit. Genuine faults are plain `Error`s and return
- * `false`, so real bugs still report.
- */
-export function isAuthError(err: unknown): boolean {
-  return err instanceof AuthError;
-}

package/src/utils/billing-gate.test.ts

@@ -1,95 +0,0 @@
-/**
- * Unit tests for the billing-gate helpers (pure parsers + price formatting).
- * The command-level flows are covered in commands/{agents,outposts,billing}.test.ts;
- * this pins the trust-boundary parsing and the cost string.
- */
-
-import { describe, expect, it } from "vitest";
-import {
-  AGENT_PRICE_CENTS,
-  OUTPOST_PRICE_CENTS,
-  formatUsd,
-  isBillingSetupAction,
-  parseBillingPayload,
-} from "./billing-gate.js";
-
-describe("prices", () => {
-  it("match the console's authoritative constants", () => {
-    expect(AGENT_PRICE_CENTS).toBe(10_000);
-    expect(OUTPOST_PRICE_CENTS).toBe(8_000);
-  });
-});
-
-describe("formatUsd", () => {
-  it("renders cents as $X.YZ", () => {
-    expect(formatUsd(10_000)).toBe("$100.00");
-    expect(formatUsd(8_000)).toBe("$80.00");
-    expect(formatUsd(0)).toBe("$0.00");
-  });
-  it("clamps negatives to zero", () => {
-    expect(formatUsd(-500)).toBe("$0.00");
-  });
-});
-
-describe("isBillingSetupAction", () => {
-  it("accepts a valid org setup", () => {
-    expect(
-      isBillingSetupAction({
-        payerType: "company",
-        path: "/v1/billing/checkout/org",
-        method: "POST",
-        body: { companyUid: "cmp_x" },
-      }),
-    ).toBe(true);
-  });
-  it("accepts a valid person setup with no body", () => {
-    expect(
-      isBillingSetupAction({
-        payerType: "person",
-        path: "/v1/billing/checkout/person",
-        method: "POST",
-      }),
-    ).toBe(true);
-  });
-  it("rejects unknown paths / shapes", () => {
-    expect(
-      isBillingSetupAction({
-        payerType: "company",
-        path: "/v1/billing/checkout/evil",
-        method: "POST",
-      }),
-    ).toBe(false);
-    expect(isBillingSetupAction(null)).toBe(false);
-    expect(isBillingSetupAction({ payerType: "company" })).toBe(false);
-  });
-});
-
-describe("parseBillingPayload", () => {
-  it("extracts status + setup from a 402 body", () => {
-    const parsed = parseBillingPayload({
-      error: "payment required",
-      billing: {
-        status: "billing_required",
-        setup: {
-          payerType: "company",
-          path: "/v1/billing/checkout/org",
-          method: "POST",
-          body: { companyUid: "cmp_x" },
-        },
-      },
-    });
-    expect(parsed?.status).toBe("billing_required");
-    expect(parsed?.setup?.path).toBe("/v1/billing/checkout/org");
-  });
-  it("returns status with no setup when the setup is malformed", () => {
-    const parsed = parseBillingPayload({
-      billing: { status: "billing_required", setup: { bogus: true } },
-    });
-    expect(parsed?.status).toBe("billing_required");
-    expect(parsed?.setup).toBeUndefined();
-  });
-  it("returns undefined for a non-billing error body", () => {
-    expect(parseBillingPayload({ error: "forbidden" })).toBeUndefined();
-    expect(parseBillingPayload(null)).toBeUndefined();
-  });
-});

package/src/utils/billing-gate.ts

@@ -1,228 +0,0 @@
-/**
- * Billing gate for paid provisioning (agents & Outposts).
- *
- * hq-pro enforces billing server-side: a provision call for a resource whose
- * payer has no card on file returns `402` with a `billing` payload carrying a
- * `setup` action that names EXACTLY which checkout endpoint to hit. That
- * endpoint returns `{ url }` — a Stripe-hosted card-capture link.
- *
- * This module wires the client-side experience around that contract:
- *   1. `confirmChargeOrExit` — print the monthly cost and require `--yes`
- *      BEFORE any paid provisioning call is made.
- *   2. `surfaceBillingRequired` — when the backend answers `402 billing_required`,
- *      mint the card-capture link and print a plain, shareable message instead
- *      of an opaque failure.
- *   3. `hq billing checkout` (see commands/billing.ts) reuses `mintPaymentLink`
- *      to hand out the same link proactively.
- *
- * Prices mirror the console's authoritative constants
- * (hq-console `src/lib/billing-pricing.ts`): amounts are in the smallest
- * currency unit (US cents) to match Stripe's wire shape.
- */
-
-import chalk from "chalk";
-import { vaultApiFetch } from "./vault-api.js";
-
-/** Per-Agent monthly list price, in cents ($100.00 / agent / month). */
-export const AGENT_PRICE_CENTS = 10_000;
-/** Per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
-export const OUTPOST_PRICE_CENTS = 8_000;
-
-/** Render a cents amount as a `$X.YZ` USD string. */
-export function formatUsd(cents: number): string {
-  return `$${(Math.max(0, Math.round(cents)) / 100).toFixed(2)}`;
-}
-
-/**
- * The server-supplied "how to add a card" action on a `402 billing_required`.
- * Mirrors hq-pro `src/billing/activation-billing.ts` `BillingSetupAction` and
- * the console's `src/lib/billing-setup.ts`.
- */
-export interface BillingSetupAction {
-  payerType: "company" | "person";
-  path: "/v1/billing/checkout/org" | "/v1/billing/checkout/person";
-  method: "POST";
-  body?: { companyUid?: string };
-}
-
-/** The `billing` envelope hq-pro attaches to a billing-blocked provision. */
-export interface BillingErrorPayload {
-  status: string;
-  setup?: BillingSetupAction;
-}
-
-/** Narrow an unknown value to a usable `BillingSetupAction`. */
-export function isBillingSetupAction(value: unknown): value is BillingSetupAction {
-  if (!value || typeof value !== "object") return false;
-  const setup = value as Partial<BillingSetupAction>;
-  const body = setup.body;
-  return (
-    (setup.payerType === "company" || setup.payerType === "person") &&
-    (setup.path === "/v1/billing/checkout/org" ||
-      setup.path === "/v1/billing/checkout/person") &&
-    setup.method === "POST" &&
-    (body === undefined || (typeof body === "object" && body !== null))
-  );
-}
-
-/** Pull a `BillingErrorPayload` out of a decoded hq-pro error body, if present. */
-export function parseBillingPayload(body: unknown): BillingErrorPayload | undefined {
-  if (!body || typeof body !== "object") return undefined;
-  const raw = (body as { billing?: unknown }).billing;
-  if (!raw || typeof raw !== "object") return undefined;
-  const status = (raw as { status?: unknown }).status;
-  if (typeof status !== "string") return undefined;
-  const setup = (raw as { setup?: unknown }).setup;
-  return {
-    status,
-    ...(isBillingSetupAction(setup) ? { setup } : {}),
-  };
-}
-
-export type PaidResource = "agent" | "Outpost";
-
-/**
- * Gate a paid provisioning call behind an explicit, informed `--yes`. Prints the
- * monthly charge in full prose (this is a paid, outward action — Auto-Clarity)
- * and exits non-zero when the caller has not passed `--yes`. Returns normally
- * once approved so the caller proceeds to provision.
- */
-export function confirmChargeOrExit(opts: {
-  resource: PaidResource;
-  unitCents: number;
-  quantity?: number;
-  yes?: boolean;
-}): void {
-  const quantity = opts.quantity ?? 1;
-  const total = opts.unitCents * quantity;
-  const each =
-    quantity > 1 ? ` (${formatUsd(opts.unitCents)} each × ${quantity})` : "";
-  const noun = quantity > 1 ? `${opts.resource}s` : opts.resource;
-  const article = /^[aeiou]/i.test(opts.resource) ? "an" : "a";
-  const subject = quantity > 1 ? `${quantity} ${noun}` : `${article} ${noun}`;
-  if (!opts.yes) {
-    console.error(
-      chalk.yellow(
-        `Provisioning ${subject} adds a recurring charge of ` +
-          `${formatUsd(total)}/month${each} to the payer on file. This is a ` +
-          `paid resource.\n` +
-          `Re-run with --yes to confirm you want to incur this charge.`,
-      ),
-    );
-    process.exit(1);
-  }
-  console.log(
-    chalk.dim(
-      `Confirmed: ${formatUsd(total)}/month for ${quantity} ${noun}. Provisioning…`,
-    ),
-  );
-}
-
-/**
- * Mint a Stripe-hosted card-capture link for a `BillingSetupAction`. Returns the
- * hosted URL the payer opens to add a card. Throws on a non-2xx (the caller
- * decides how to surface it) — never swallows.
- */
-export async function mintPaymentLink(
-  token: string,
-  setup: BillingSetupAction,
-): Promise<string> {
-  const res = await vaultApiFetch({
-    token,
-    path: setup.path,
-    method: "POST",
-    body: setup.body?.companyUid ? { companyUid: setup.body.companyUid } : {},
-  });
-  if (!res.ok) {
-    const body = (await res.json().catch(() => ({}))) as {
-      error?: string;
-      message?: string;
-    };
-    throw new Error(
-      `Failed to mint a payment link: ${body.error ?? body.message ?? res.statusText}`,
-    );
-  }
-  const data = (await res.json()) as { url?: string };
-  if (!data.url) {
-    throw new Error("Payment link response did not include a checkout URL.");
-  }
-  return data.url;
-}
-
-/**
- * The provision was blocked because the payer has no card on file. Mint the
- * card-capture link the backend pointed us at and print a plain, shareable
- * message so the user can add a card (or hand the link to whoever owns billing)
- * and re-run. Returns the URL, or `null` when the server gave no `setup` action
- * to act on. Never prints tokens or secrets.
- */
-export async function surfaceBillingRequired(
-  token: string,
-  billing: BillingErrorPayload,
-): Promise<string | null> {
-  if (!billing.setup) {
-    console.error(
-      chalk.yellow(
-        "Provisioning is blocked on billing, but the server didn't return a " +
-          "payment link. Add a card in the console billing page, then re-run.",
-      ),
-    );
-    return null;
-  }
-  const url = await mintPaymentLink(token, billing.setup);
-  console.log(
-    chalk.yellow("No card on file — provisioning is blocked until one is added."),
-  );
-  console.log(
-    "Add a card here (safe to share with whoever owns billing):\n  " +
-      chalk.cyan(url),
-  );
-  console.log(chalk.dim("Once a card is added, re-run the same command."));
-  return url;
-}
-
-/**
- * Status-aware surface for a 402 billing block. hq-pro's envelope carries two
- * distinct remediations that must never be conflated (mirroring the server's
- * own P1-C classification):
- *   - `payment_failed`   — a card EXISTS and the charge was DECLINED. The
- *     server's `message` already carries the friendly decline copy ("Your
- *     card was declined…", "insufficient funds", …). Telling this user
- *     "No card on file" sends them down the wrong remediation path entirely
- *     (observed live 2026-07-20: a declined $80 Outpost proration surfaced
- *     as "no card", triggering a hunt for a missing card that existed).
- *     The capture link still surfaces — as the way to UPDATE the card.
- *   - anything else (`billing_required`) — genuinely no usable card on
- *     file; the existing add-a-card copy is correct.
- */
-export async function surfaceBillingBlocked(
-  token: string,
-  billing: BillingErrorPayload,
-  serverMessage?: string,
-): Promise<string | null> {
-  if (billing.status !== "payment_failed") {
-    return surfaceBillingRequired(token, billing);
-  }
-  console.error(
-    chalk.yellow(
-      serverMessage?.trim() ||
-        "Your payment failed. Try a different card or contact your bank.",
-    ),
-  );
-  if (!billing.setup) return null;
-  try {
-    const url = await mintPaymentLink(token, billing.setup);
-    console.log(
-      "Update or replace the card here (safe to share with whoever owns billing):\n  " +
-        chalk.cyan(url),
-    );
-    console.log(
-      chalk.dim("Once the payment method is sorted, re-run the same command."),
-    );
-    return url;
-  } catch {
-    // Link minting is best-effort on the decline path — the decline reason
-    // above is the essential part; the console billing page also works.
-    return null;
-  }
-}

package/src/utils/breadcrumb-buffer.ts

@@ -1,18 +0,0 @@
-import type { Breadcrumb } from "@sentry/node";
-
-const BUFFER_SIZE = 20;
-const _buffer: Breadcrumb[] = [];
-
-// Sentry beforeBreadcrumb hook: records every breadcrumb in a ring buffer
-// and returns it unchanged so Sentry still processes it normally.
-export function beforeBreadcrumb(breadcrumb: Breadcrumb): Breadcrumb | null {
-  _buffer.push(breadcrumb);
-  if (_buffer.length > BUFFER_SIZE) {
-    _buffer.shift();
-  }
-  return breadcrumb;
-}
-
-export function getRecentBreadcrumbs(): Breadcrumb[] {
-  return [..._buffer];
-}