@indigoai-us/hq-cli 5.31.0 → 5.32.0

package/src/commands/packs.ts

@@ -0,0 +1,524 @@
+/**
+ * `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).
+ *
+ * Distinct from `hq packages ...` (the entitlement-gated REGISTRY system tracked
+ * in packages/registry.yaml). Content packs have no registry file -- the
+ * filesystem under core/packages/ is the source of truth. Today `hq install`
+ * is the only clean content-pack op; this adds the rest.
+ *
+ * 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,
+  runScanPackages,
+  installPack,
+  type LatestResult,
+} from './pack-install.js';
+import {
+  contributionLinks,
+  linkStatus,
+  listInstalledPacks,
+  readPackManifest,
+  unwirePack,
+  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;
+  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[];
+}
+
+function buildInstalledView(
+  hqRoot: string,
+  hqVersion: string | null,
+  pack: InstalledPack,
+  installedSources: Set<string>,
+  checkUpdates: boolean,
+): 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 = resolveLatest(m.source, m.version).updateAvailable;
+  }
+
+  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,
+  };
+}
+
+function buildListView(hqRoot: string, checkUpdates: boolean, evalConditionals: boolean): 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 installed = packs.map((p) =>
+    buildInstalledView(hqRoot, hqVersion, p, catalogSources, checkUpdates),
+  );
+  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;
+  yes?: boolean;
+  allowHooks?: 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;
+    }
+    const probe: LatestResult = resolveLatest(source, m.version);
+    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,
+          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
+}
+
+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.');
+  }
+
+  // 1. Un-wire only our symlinks.
+  const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
+
+  // 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 registerPacksCommand(parent: Command): void {
+  const packs = parent.command('packs').description('Content-pack lifecycle (install via `hq install`)');
+
+  packs
+    .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('--eval-conditionals', 'Evaluate catalog conditional predicates (runs bash)')
+    .action(
+      async (opts: CommonOpts & { checkUpdates?: boolean; evalConditionals?: boolean }) => {
+        try {
+          const view = buildListView(resolveRoot(opts), !!opts.checkUpdates, !!opts.evalConditionals);
+          if (wantsJson(opts)) emitJson(view);
+          else printListHuman(view);
+        } catch (e) {
+          console.error(chalk.red('packs list failed:'), (e as Error).message);
+          process.exit(1);
+        }
+      },
+    );
+
+  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('-y, --yes', 'Non-interactive (implies --allow-hooks)')
+    .option('--allow-hooks', 'Install pack hooks 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')
+    .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);
+      }
+    });
+}

package/src/commands/pkg-list.ts

@@ -20,9 +20,10 @@ export function registerPackageListCommand(parent: Command): void {
     .command('list')
     .alias('ls')
     .description('List installed and available packages')
-    .action(async () => {
+    .option('--json', 'Machine-readable JSON output')
+    .action(async (opts: { json?: boolean }) => {
       try {
-        await listPackages();
+        await listPackages(opts.json === true || !process.stdout.isTTY);
       } catch (error) {
         console.error(
           chalk.red('List failed:'),
@@ -33,7 +34,37 @@ export function registerPackageListCommand(parent: Command): void {
     });
 }
 
-async function listPackages(): Promise<void> {
+async function gatherRegistryPackages(): Promise<{
+  installed: ReturnType<typeof readRegistry>;
+  available: EntitlementEntry[];
+  offline: boolean;
+}> {
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
+  const installed = readRegistry(hqRoot);
+  let entitlements: EntitlementEntry[] = [];
+  let offline = false;
+  try {
+    const cached = loadCachedTokens();
+    if (cached && !isExpiring(cached, 120)) {
+      const client = new RegistryClient(getRegistryUrl(), cached.accessToken);
+      const result = await client.getMyEntitlements();
+      entitlements = result.entitlements;
+    }
+  } catch {
+    offline = true;
+  }
+  const installedSlugs = new Set(installed.map((p) => p.slug));
+  const available = entitlements.filter((e) => !installedSlugs.has(e.slug));
+  return { installed, available, offline };
+}
+
+async function listPackages(json: boolean): Promise<void> {
+  if (json) {
+    const { installed, available, offline } = await gatherRegistryPackages();
+    process.stdout.write(JSON.stringify({ installed, available, offline }, null, 2) + '\n');
+    return;
+  }
+
   const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const installed = readRegistry(hqRoot);
 

package/src/index.ts

@@ -23,11 +23,13 @@ import { registerPackageInstallCommand } from "./commands/pkg-install.js";
 import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
 import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
 import { registerPackageListCommand } from "./commands/pkg-list.js";
+import { registerPacksCommand } from "./commands/packs.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
+import { registerGroupGrantsCommand } from "./commands/group-grants.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
@@ -87,6 +89,12 @@ registerPackageRemoveCommand(packagesCmd);
 registerPackageUpdateCommand(packagesCmd);
 registerPackageListCommand(packagesCmd);
 
+// Content-pack lifecycle (core/packages/hq-pack-*). Distinct from the registry
+// `packages` system above. Available as both `hq packages packs …` (grouped)
+// and `hq packs …` (top-level convenience).
+registerPacksCommand(packagesCmd);
+registerPacksCommand(program);
+
 // Top-level shortcuts for package commands
 // "hq install <slug>" = "hq packages install <slug>"
 // "hq remove <slug>"  = "hq packages remove <slug>"
@@ -131,6 +139,10 @@ registerRunCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
 registerGroupsCommand(program);
 
+// Cross-company group grants (subcommand group —
+// hq group-grants grant|revoke|outbound|inbound)
+registerGroupGrantsCommand(program);
+
 // Files ACL management (subcommand group — hq files share|unshare|acl)
 // `registerFilesCommand` returns the `files` group so we can attach the
 // browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.