@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/packs.ts

@@ -1,622 +0,0 @@
-/**
- * `hq packs` -- lifecycle for CONTENT packs (the ones installed via
- * `hq install <source>` that live in `core/packages/hq-pack-<name>/`).
- *
- *   hq packs list        Installed packs + curated catalog, with link health.
- *   hq packs update       Re-install the latest of an installed pack.
- *   hq packs uninstall    Un-wire + archive a pack (clean, no dangling symlinks).
- *
- * Also exposed through `hq packages list`, because package installs use this
- * content-pack system. Content packs have no registry file -- the filesystem
- * under core/packages/ is the source of truth.
- *
- * Every subcommand supports `--json` for machine consumers (the HQ Sync
- * menubar app). JSON is also the default when stdout is not a TTY, matching
- * the `hq signals` / `hq sources` convention.
- *
- * Spec: knowledge/public/hq-core/package-yaml-spec.md.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import * as readline from 'readline';
-import { spawnSync } from 'child_process';
-import { Command } from 'commander';
-import chalk from 'chalk';
-import semverSatisfies from 'semver/functions/satisfies.js';
-import { findHqRoot } from '../utils/manifest.js';
-import {
-  classify,
-  resolveLatest,
-  resolveLatestMarketplace,
-  runScanPackages,
-  installPack,
-  type LatestResult,
-} from './pack-install.js';
-import {
-  contributionLinks,
-  linkStatus,
-  listInstalledPacks,
-  findDependentPacks,
-  readPackManifest,
-  unwirePack,
-  unwirePackMcp,
-  readHqVersion,
-  readRecommendedPackages,
-  packagesDir,
-  type InstalledPack,
-  type LinkStatus,
-} from '../utils/pack-contributions.js';
-import type { PackContributeKey } from '../types.js';
-
-// ---------------------------------------------------------------------------
-// Shared helpers
-// ---------------------------------------------------------------------------
-
-interface CommonOpts {
-  json?: boolean;
-  hqRoot?: string;
-}
-
-function resolveRoot(opts: CommonOpts): string {
-  return opts.hqRoot ? path.resolve(opts.hqRoot) : findHqRoot();
-}
-
-/** JSON when --json or when piped (non-TTY); human-readable on a terminal. */
-function wantsJson(opts: CommonOpts): boolean {
-  return opts.json === true || !process.stdout.isTTY;
-}
-
-function emitJson(value: unknown): void {
-  process.stdout.write(JSON.stringify(value, null, 2) + '\n');
-}
-
-function safeClassify(source?: string): string | null {
-  if (!source) return null;
-  try {
-    return classify(source);
-  } catch {
-    return null;
-  }
-}
-
-function evalConditional(expr: string): boolean {
-  return spawnSync('bash', ['-c', expr], { stdio: 'ignore' }).status === 0;
-}
-
-async function confirm(question: string): Promise<boolean> {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const answer: string = await new Promise((resolve) => {
-    rl.question(`${question} [y/N] `, (a) => {
-      rl.close();
-      resolve(a);
-    });
-  });
-  return /^(y|yes)$/i.test(answer.trim());
-}
-
-// ---------------------------------------------------------------------------
-// list
-// ---------------------------------------------------------------------------
-
-interface InstalledPackView {
-  name: string;
-  version?: string;
-  publisher?: string;
-  source?: string;
-  transport: string | null;
-  requiresHqCore?: string;
-  hqCoreSatisfied: boolean | null;
-  contributes: Partial<Record<PackContributeKey, number>>;
-  links: Record<LinkStatus, number>;
-  brokenLinks: Array<{ key: PackContributeKey; item: string; dst: string }>;
-  inCatalog: boolean;
-  updateAvailable: boolean | null;
-  /**
-   * Post-install initialization (US-005). Present only when the pack's
-   * package.yaml declares an `initialization` block — drives the HQ Sync
-   * "Installed" panel get-started affordance. Absent → omitted (no null noise).
-   */
-  initialization?: { entrypoint: string; prompt?: string };
-  error?: string;
-}
-
-interface AvailablePackView {
-  source: string;
-  description?: string;
-  installed: false;
-  conditional?: string;
-  conditionalStatus: 'pass' | 'fail' | 'unevaluated' | 'none';
-}
-
-interface PacksListView {
-  hqRoot: string;
-  hqVersion: string | null;
-  installed: InstalledPackView[];
-  available: AvailablePackView[];
-  warnings: string[];
-}
-
-export function buildInstalledView(
-  hqRoot: string,
-  hqVersion: string | null,
-  pack: InstalledPack,
-  installedSources: Set<string>,
-  checkUpdates: boolean,
-  latestProbe?: LatestResult,
-): InstalledPackView {
-  if (!pack.manifest) {
-    return {
-      name: pack.name,
-      transport: null,
-      hqCoreSatisfied: null,
-      contributes: {},
-      links: { live: 0, broken: 0, missing: 0, foreign: 0 },
-      brokenLinks: [],
-      inCatalog: false,
-      updateAvailable: null,
-      error: pack.error ?? 'unreadable manifest',
-    };
-  }
-  const m = pack.manifest;
-  const contributes = m.contributes ?? {};
-  const links = contributionLinks(hqRoot, pack.dir, contributes);
-  const counts: Record<LinkStatus, number> = { live: 0, broken: 0, missing: 0, foreign: 0 };
-  const brokenLinks: InstalledPackView['brokenLinks'] = [];
-  for (const link of links) {
-    const st = linkStatus(link);
-    counts[st]++;
-    if (st === 'broken') brokenLinks.push({ key: link.key, item: link.item, dst: link.dst });
-  }
-  const contributeCounts: Partial<Record<PackContributeKey, number>> = {};
-  for (const [key, items] of Object.entries(contributes) as [PackContributeKey, unknown][]) {
-    if (Array.isArray(items) && items.length > 0) contributeCounts[key] = items.length;
-  }
-  const requiresHqCore = m.requires?.hqCore;
-  const hqCoreSatisfied =
-    hqVersion && requiresHqCore ? semverSatisfies(hqVersion, requiresHqCore) : null;
-
-  let updateAvailable: boolean | null = null;
-  if (checkUpdates && m.source) {
-    updateAvailable = latestProbe?.updateAvailable ?? null;
-  }
-
-  // US-005 — surface the pack's `initialization` block so the HQ Sync
-  // "Installed" panel can render its get-started affordance. `readPackManifest`
-  // already parses the full package.yaml, so `m.initialization` is available;
-  // we still shape it defensively (tolerate a malformed/absent block) and omit
-  // the field entirely when absent so the JSON carries no null noise.
-  let initialization: InstalledPackView['initialization'];
-  const rawInit = m.initialization as unknown;
-  if (rawInit && typeof rawInit === 'object' && !Array.isArray(rawInit)) {
-    const initObj = rawInit as Record<string, unknown>;
-    const entrypoint = initObj.entrypoint;
-    if (typeof entrypoint === 'string' && entrypoint.trim() !== '') {
-      initialization = { entrypoint };
-      if (typeof initObj.prompt === 'string') initialization.prompt = initObj.prompt;
-    }
-  }
-
-  return {
-    name: m.name ?? pack.name,
-    version: m.version,
-    publisher: m.publisher,
-    source: m.source,
-    transport: safeClassify(m.source),
-    requiresHqCore,
-    hqCoreSatisfied,
-    contributes: contributeCounts,
-    links: counts,
-    brokenLinks,
-    inCatalog: m.source ? installedSources.has(m.source) : false,
-    updateAvailable,
-    ...(initialization ? { initialization } : {}),
-  };
-}
-
-async function buildListView(
-  hqRoot: string,
-  checkUpdates: boolean,
-  evalConditionals: boolean,
-  refreshUpdates: boolean,
-): Promise<PacksListView> {
-  const hqVersion = readHqVersion(hqRoot);
-  const packs = listInstalledPacks(hqRoot);
-  const catalog = readRecommendedPackages(hqRoot);
-  const catalogSources = new Set(catalog.map((c) => c.source));
-  const warnings: string[] = [];
-
-  const latestProbes = await Promise.all(
-    packs.map((p) =>
-      checkUpdates && p.manifest?.source
-        ? resolveLatest(p.manifest.source, p.manifest.version, { forceRefresh: refreshUpdates })
-        : Promise.resolve(undefined),
-    ),
-  );
-  const installed = packs.map((p, i) =>
-    buildInstalledView(hqRoot, hqVersion, p, catalogSources, checkUpdates, latestProbes[i]),
-  );
-  for (const p of installed) {
-    if (p.error) warnings.push(`${p.name}: ${p.error}`);
-  }
-
-  const installedSources = new Set(
-    packs.map((p) => p.manifest?.source).filter((s): s is string => !!s),
-  );
-  const available: AvailablePackView[] = catalog
-    .filter((c) => !installedSources.has(c.source))
-    .map((c) => {
-      let conditionalStatus: AvailablePackView['conditionalStatus'] = c.conditional
-        ? 'unevaluated'
-        : 'none';
-      if (c.conditional && evalConditionals) {
-        conditionalStatus = evalConditional(c.conditional) ? 'pass' : 'fail';
-      }
-      return {
-        source: c.source,
-        description: c.description,
-        installed: false,
-        conditional: c.conditional,
-        conditionalStatus,
-      };
-    });
-
-  return { hqRoot, hqVersion, installed, available, warnings };
-}
-
-function printListHuman(view: PacksListView): void {
-  console.log(chalk.bold(`\nHQ packs  (${view.hqRoot}, hqCore ${view.hqVersion ?? '?'})\n`));
-  if (view.installed.length === 0) {
-    console.log(chalk.dim('  No content packs installed.\n'));
-  } else {
-    console.log(chalk.bold('Installed:'));
-    for (const p of view.installed) {
-      if (p.error) {
-        console.log(`  ${chalk.red(p.name)}  ${chalk.dim('(' + p.error + ')')}`);
-        continue;
-      }
-      const broken = p.links.broken > 0 ? chalk.red(`  ! ${p.links.broken} broken link(s)`) : '';
-      const upd = p.updateAvailable ? chalk.yellow('  ^ update available') : '';
-      const hq = p.hqCoreSatisfied === false ? chalk.red('  x hqCore mismatch') : '';
-      console.log(`  ${chalk.green(p.name)}@${p.version ?? '?'}  ${chalk.dim(p.transport ?? '')}${upd}${hq}${broken}`);
-    }
-    console.log();
-  }
-  if (view.available.length > 0) {
-    console.log(chalk.bold('Available (curated):'));
-    for (const a of view.available) {
-      const gate =
-        a.conditionalStatus === 'fail'
-          ? chalk.dim('  (gated off)')
-          : a.conditionalStatus === 'unevaluated' && a.conditional
-            ? chalk.dim('  (conditional)')
-            : '';
-      console.log(`  ${chalk.cyan(a.source)}${gate}`);
-      if (a.description) console.log(chalk.dim(`    ${a.description}`));
-    }
-    console.log(chalk.dim('\n  Install with: hq install <source>\n'));
-  }
-}
-
-// ---------------------------------------------------------------------------
-// update
-// ---------------------------------------------------------------------------
-
-interface UpdateCheck {
-  name: string;
-  transport: string;
-  current?: string;
-  latest?: string;
-  updateAvailable: boolean | null;
-  applied: boolean;
-  reason?: string;
-  error?: string;
-}
-
-interface UpdateOpts extends CommonOpts {
-  checkOnly?: boolean;
-  refresh?: boolean;
-  yes?: boolean;
-  allowHooks?: boolean;
-  allowMcp?: boolean;
-  branch?: boolean;
-}
-
-async function runUpdate(name: string | undefined, opts: UpdateOpts): Promise<UpdateCheck[]> {
-  const hqRoot = resolveRoot(opts);
-  let packs = listInstalledPacks(hqRoot).filter((p) => p.manifest);
-  if (name) {
-    packs = packs.filter((p) => (p.manifest?.name ?? p.name) === name);
-    if (packs.length === 0) {
-      return [{ name, transport: 'unknown', updateAvailable: null, applied: false, error: 'not installed' }];
-    }
-  }
-
-  const results: UpdateCheck[] = [];
-  for (const pack of packs) {
-    const m = pack.manifest!;
-    const source = m.source;
-    const pname = m.name ?? pack.name;
-    if (!source) {
-      results.push({ name: pname, transport: 'unknown', updateAvailable: null, applied: false, error: 'no stamped source -- cannot update' });
-      continue;
-    }
-    // US-006: marketplace sources need the async listings probe (network) —
-    // the sync `resolveLatest` cannot make that call and returns null. Every
-    // other transport keeps the existing synchronous probe unchanged.
-    const probe: LatestResult =
-      safeClassify(source) === 'marketplace'
-        ? await resolveLatestMarketplace(source, m.version)
-        : await resolveLatest(source, m.version, { forceRefresh: true });
-    const base: UpdateCheck = {
-      name: pname,
-      transport: probe.transport,
-      current: probe.current,
-      latest: probe.latest,
-      updateAvailable: probe.updateAvailable,
-      applied: false,
-      error: probe.error,
-    };
-    if (opts.checkOnly) {
-      results.push(base);
-      continue;
-    }
-    // Apply only when there's a known update, or when explicitly named (force re-sync).
-    if (probe.updateAvailable === false && !name) {
-      results.push({ ...base, reason: 'already current' });
-      continue;
-    }
-    try {
-      // Un-wire old contributions first so a contribution dropped by the new
-      // version doesn't leave a dangling host symlink. installPack re-wires.
-      unwirePack(hqRoot, pack.dir, m.contributes ?? {});
-      const prevCwd = process.cwd();
-      if (opts.hqRoot) process.chdir(hqRoot); // installPack resolves via findHqRoot()
-      try {
-        await installPack(source, {
-          allowHooks: opts.yes || opts.allowHooks,
-          allowMcp: opts.yes || opts.allowMcp,
-          followBranch: opts.branch,
-          quiet: wantsJson(opts),
-        });
-      } finally {
-        if (opts.hqRoot) process.chdir(prevCwd);
-      }
-      results.push({ ...base, applied: true });
-    } catch (e) {
-      results.push({ ...base, applied: false, error: (e as Error).message });
-    }
-  }
-  return results;
-}
-
-// ---------------------------------------------------------------------------
-// uninstall
-// ---------------------------------------------------------------------------
-
-interface UninstallResult {
-  name: string;
-  archived: string | null;
-  unlinked: Array<{ key: PackContributeKey; item: string; dst: string }>;
-  skipped: Array<{ key: PackContributeKey; item: string; dst: string; reason: string }>;
-  rescan: 'ok' | 'skipped';
-  workersRegistryRegenerated: boolean;
-  sideEffectsSuggested: string[];
-  warnings: string[];
-}
-
-interface UninstallOpts extends CommonOpts {
-  yes?: boolean;
-  archive?: boolean; // commander sets false for --no-archive
-  force?: boolean; // bypass the dependents guard (M0)
-}
-
-function archiveTimestamp(): string {
-  return new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
-}
-
-async function runUninstall(name: string, opts: UninstallOpts): Promise<UninstallResult> {
-  const hqRoot = resolveRoot(opts);
-  const packDir = path.join(packagesDir(hqRoot), name);
-  if (!fs.existsSync(packDir)) {
-    throw new Error(`Pack "${name}" is not installed (no core/packages/${name}/).`);
-  }
-  const warnings: string[] = [];
-  const { manifest } = readPackManifest(packDir);
-  const contributes = manifest?.contributes ?? {};
-  if (!manifest) {
-    warnings.push('package.yaml unreadable -- host symlinks could not be computed precisely; ran a re-scan to reconcile.');
-  }
-
-  // 0. Dependents guard (M0): refuse to remove a pack that another installed pack
-  // lists in its `requires.packs`, unless --force. Filesystem presence is the
-  // source of truth (listInstalledPacks), consistent with the install-time
-  // assertPackDependencies check. Runs BEFORE any un-wiring so a blocked uninstall
-  // leaves the pack fully intact.
-  if (!opts.force) {
-    const dependents = findDependentPacks(listInstalledPacks(hqRoot), name);
-    if (dependents.length > 0) {
-      const who = dependents.map((p) => p.manifest?.name ?? p.name).join(', ');
-      throw new Error(
-        `Cannot uninstall "${name}": required by ${who}. ` +
-          `Uninstall the dependent pack(s) first, or pass --force to override.`,
-      );
-    }
-  }
-
-  // 1. Un-wire only our symlinks.
-  const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
-
-  // 1b. Un-register the pack's MCP (`wire: 'merge'`) servers — invisible to the
-  // symlink unwire above. Provenance-scoped: removes ONLY entries stamped with this
-  // pack's `_hqPack`, and skip-and-warns on any foreign/unstamped same-named entry.
-  // Tolerant of a Codex-less host / absent config; idempotent on re-run.
-  try {
-    const mcp = unwirePackMcp(name, contributes);
-    for (const server of mcp.servers) {
-      if ('skipped' in server.claude) continue; // (claude is always inspected; never skipped)
-      if (server.claude.outcome === 'skipped-foreign' && server.claude.reason) {
-        warnings.push(server.claude.reason);
-      }
-      if (!('skipped' in server.codex) && server.codex.outcome === 'skipped-foreign' && server.codex.reason) {
-        warnings.push(server.codex.reason);
-      }
-    }
-  } catch (e) {
-    // Never let an MCP un-registration failure abort the rest of the uninstall
-    // (symlink unwire already ran; the pack dir still gets archived). Surface it.
-    warnings.push(`MCP un-registration encountered an error: ${(e as Error).message}`);
-  }
-
-  // 2. Archive (or delete) the pack dir -- BEFORE re-scan so it isn't re-wired.
-  let archived: string | null = null;
-  if (opts.archive === false) {
-    fs.rmSync(packDir, { recursive: true, force: true });
-  } else {
-    const dest = path.join(packagesDir(hqRoot), '.archive', `${name}-${archiveTimestamp()}`);
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.renameSync(packDir, dest);
-    archived = path.relative(hqRoot, dest);
-  }
-
-  // 3. Re-assert remaining packs' links (handles two packs sharing a contribution).
-  let rescan: 'ok' | 'skipped' = 'skipped';
-  try {
-    // Quiet: uninstall emits its own summary / JSON; keep scan stdout off ours.
-    runScanPackages(hqRoot, { quiet: true });
-    rescan = 'ok';
-  } catch {
-    rescan = 'skipped';
-  }
-
-  // 4. Regenerate the workers registry if this pack contributed workers.
-  let workersRegistryRegenerated = false;
-  const contributedWorkers = Array.isArray(contributes.workers) && contributes.workers.length > 0;
-  if (contributedWorkers) {
-    const gen = path.join(hqRoot, 'core', 'scripts', 'generate-workers-registry.sh');
-    if (fs.existsSync(gen)) {
-      const r = spawnSync('bash', [gen], { cwd: hqRoot, env: { ...process.env, HQ_ROOT: hqRoot }, stdio: 'ignore' });
-      workersRegistryRegenerated = r.status === 0;
-      if (!workersRegistryRegenerated) warnings.push('generate-workers-registry.sh exited non-zero');
-    }
-  }
-
-  const sideEffectsSuggested = ['master-sync', 'qmd-reindex'];
-  if (contributedWorkers && !workersRegistryRegenerated) sideEffectsSuggested.push('workers-registry');
-
-  return {
-    name,
-    archived,
-    unlinked,
-    skipped,
-    rescan,
-    workersRegistryRegenerated,
-    sideEffectsSuggested,
-    warnings,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Registration
-// ---------------------------------------------------------------------------
-
-export function registerPacksListCommand(parent: Command): void {
-  parent
-    .command('list')
-    .alias('ls')
-    .description('List installed content packs and the curated catalog')
-    .option('--json', 'Machine-readable JSON output')
-    .option('--hq-root <path>', 'HQ root (default: auto-detect)')
-    .option('--check-updates', 'Probe each pack for available updates (network I/O)')
-    .option('--refresh', 'Bypass cached update probes')
-    .option('--eval-conditionals', 'Evaluate catalog conditional predicates (runs bash)')
-    .action(
-      async (opts: CommonOpts & { checkUpdates?: boolean; evalConditionals?: boolean; refresh?: boolean }) => {
-        try {
-          const view = await buildListView(
-            resolveRoot(opts),
-            !!opts.checkUpdates,
-            !!opts.evalConditionals,
-            !!opts.refresh,
-          );
-          if (wantsJson(opts)) emitJson(view);
-          else printListHuman(view);
-        } catch (e) {
-          console.error(chalk.red('packs list failed:'), (e as Error).message);
-          process.exit(1);
-        }
-      },
-    );
-}
-
-export function registerPacksCommand(parent: Command): void {
-  const packs = parent.command('packs').description('Content-pack lifecycle (install via `hq install`)');
-
-  registerPacksListCommand(packs);
-
-  packs
-    .command('update [name]')
-    .description('Update an installed content pack (re-install latest)')
-    .option('--json', 'Machine-readable JSON output')
-    .option('--hq-root <path>', 'HQ root (default: auto-detect)')
-    .option('--check-only', 'Report availability without installing')
-    .option('--refresh', 'Bypass cached update probes (update refreshes by default)')
-    .option('-y, --yes', 'Non-interactive (implies --allow-hooks and --allow-mcp)')
-    .option('--allow-hooks', 'Install pack hooks without prompting')
-    .option('--allow-mcp', 'Register pack MCP servers without prompting')
-    .option('--branch', 'Follow the source branch instead of SHA-pinning')
-    .action(async (name: string | undefined, opts: UpdateOpts) => {
-      try {
-        const results = await runUpdate(name, opts);
-        if (wantsJson(opts)) {
-          emitJson({ checked: results, updatedCount: results.filter((r) => r.applied).length });
-        } else {
-          for (const r of results) {
-            if (r.error) console.log(`  ${chalk.red(r.name)}: ${r.error}`);
-            else if (r.applied) console.log(`  ${chalk.green(r.name)}: updated`);
-            else if (r.updateAvailable) console.log(`  ${chalk.yellow(r.name)}: ${r.current ?? '?'} -> ${r.latest ?? '?'} available`);
-            else console.log(`  ${chalk.dim(r.name)}: ${r.reason ?? 'current'}`);
-          }
-        }
-      } catch (e) {
-        console.error(chalk.red('packs update failed:'), (e as Error).message);
-        process.exit(1);
-      }
-    });
-
-  packs
-    .command('uninstall <name>')
-    .alias('remove')
-    .description('Un-wire and archive an installed content pack')
-    .option('--json', 'Machine-readable JSON output')
-    .option('--hq-root <path>', 'HQ root (default: auto-detect)')
-    .option('-y, --yes', 'Skip confirmation')
-    .option('--no-archive', 'Delete instead of archiving')
-    .option('--force', 'Uninstall even if other installed packs require this one')
-    .action(async (name: string, opts: UninstallOpts) => {
-      try {
-        if (!opts.yes) {
-          if (!process.stdout.isTTY) {
-            throw new Error('Refusing to uninstall without --yes in non-interactive mode.');
-          }
-          const ok = await confirm(`Uninstall pack "${name}"? This removes its host symlinks.`);
-          if (!ok) {
-            console.log(chalk.dim('Aborted.'));
-            return;
-          }
-        }
-        const result = await runUninstall(name, opts);
-        if (wantsJson(opts)) {
-          emitJson(result);
-        } else {
-          console.log(chalk.green(`\nOK Uninstalled ${name}`));
-          console.log(chalk.dim(`  Unlinked ${result.unlinked.length} symlink(s); archived to ${result.archived ?? '(deleted)'}.`));
-          if (result.skipped.length > 0) console.log(chalk.dim(`  Left ${result.skipped.length} non-owned path(s) in place.`));
-          for (const w of result.warnings) console.log(chalk.yellow(`  ! ${w}`));
-        }
-      } catch (e) {
-        console.error(chalk.red('packs uninstall failed:'), (e as Error).message);
-        process.exit(1);
-      }
-    });
-}