@indigoai-us/hq-cli 5.31.0 → 5.32.0

package/src/utils/pack-contributions.test.ts

@@ -0,0 +1,208 @@
+/**
+ * pack-contributions tests — pins the content-pack lifecycle helpers that
+ * commands/packs.ts (list / update / uninstall) depends on.
+ *
+ * The load-bearing invariant is the contributes->host-path mapping: it MUST
+ * agree byte-for-byte with core/scripts/scan-packages.sh (the wiring
+ * authority) and pack-install.ts:validateManifest. A drift there means
+ * uninstall would miss symlinks (dangling links) or delete the wrong path.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  contributionLinks,
+  linkStatus,
+  listInstalledPacks,
+  unwirePack,
+  packagesDir,
+  type WiredLink,
+} from './pack-contributions.js';
+import type { PackContributeKey } from '../types.js';
+
+// The canonical mapping, encoded once here as the test oracle. Host paths are
+// relative to hqRoot; src paths relative to the pack dir.
+const EXPECTED: Record<PackContributeKey, { src: string; dst: string }> = {
+  workers: { src: 'workers/X', dst: 'core/workers/public/X' },
+  knowledge: { src: 'knowledge/X', dst: 'core/knowledge/public/X' },
+  skills: { src: 'skills/X', dst: '.claude/skills/X' },
+  commands: { src: 'commands/X.md', dst: '.claude/commands/X.md' },
+  hooks: { src: 'hooks/X.sh', dst: '.claude/hooks/X.sh' },
+  policies: { src: 'policies/X.md', dst: 'core/policies/X.md' },
+  scripts: { src: 'scripts/X', dst: 'core/scripts/X' },
+};
+
+function mkTmp(prefix: string): string {
+  // realpathSync so macOS /tmp -> /private/tmp doesn't break path equality.
+  return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+}
+
+describe('contributionLinks: mapping', () => {
+  it('maps every contributes key to the canonical src/dst', () => {
+    const hqRoot = '/hq';
+    const packDir = '/hq/core/packages/hq-pack-x';
+    for (const key of Object.keys(EXPECTED) as PackContributeKey[]) {
+      const [link] = contributionLinks(hqRoot, packDir, { [key]: ['X'] });
+      expect(link.key).toBe(key);
+      expect(link.src).toBe(path.join(packDir, EXPECTED[key].src));
+      expect(link.dst).toBe(path.join(hqRoot, EXPECTED[key].dst));
+    }
+  });
+
+  it('ignores empty / non-array contributes subfields', () => {
+    const links = contributionLinks('/hq', '/p', {
+      skills: [],
+      workers: ['a', 'b'],
+      // @ts-expect-error — defensive: non-array should be skipped
+      hooks: 'nope',
+    });
+    expect(links.map((l) => l.item)).toEqual(['a', 'b']);
+  });
+});
+
+describe('contributionLinks: parity with scan-packages.sh', () => {
+  // Best-effort drift guard: if the bash wirer is reachable, confirm each
+  // case arm's dst suffix matches our TS mapping. Skips cleanly off-tree.
+  const candidates = [
+    path.resolve(process.cwd(), '../../../core/scripts/scan-packages.sh'),
+    path.resolve(process.cwd(), '../../../../core/scripts/scan-packages.sh'),
+  ];
+  const scanPath = candidates.find((p) => fs.existsSync(p));
+
+  (scanPath ? it : it.skip)('dst suffixes match the bash case arms', () => {
+    const bash = fs.readFileSync(scanPath as string, 'utf-8');
+    for (const key of Object.keys(EXPECTED) as PackContributeKey[]) {
+      // dst host-path suffix, with the trailing /$item or /$item.md stripped.
+      const suffix = EXPECTED[key].dst.replace(/\/X(\.\w+)?$/, '');
+      expect(bash).toContain(suffix); // e.g. core/workers/public, .claude/skills
+    }
+  });
+});
+
+describe('linkStatus + unwirePack', () => {
+  let hqRoot: string;
+  let packDir: string;
+
+  beforeEach(() => {
+    hqRoot = mkTmp('hq-pc-root-');
+    packDir = path.join(packagesDir(hqRoot), 'hq-pack-demo');
+    // A pack that contributes one skill and one command.
+    fs.mkdirSync(path.join(packDir, 'skills', 'demo-skill'), { recursive: true });
+    fs.writeFileSync(path.join(packDir, 'skills', 'demo-skill', 'SKILL.md'), '# demo');
+    fs.mkdirSync(path.join(packDir, 'commands'), { recursive: true });
+    fs.writeFileSync(path.join(packDir, 'commands', 'demo-cmd.md'), '# cmd');
+  });
+
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  const contributes = { skills: ['demo-skill'], commands: ['demo-cmd'] };
+
+  function wire(link: WiredLink): void {
+    fs.mkdirSync(path.dirname(link.dst), { recursive: true });
+    fs.symlinkSync(link.src, link.dst);
+  }
+
+  it('reports missing before wiring, live after wiring', () => {
+    const links = contributionLinks(hqRoot, packDir, contributes);
+    for (const l of links) expect(linkStatus(l)).toBe('missing');
+    for (const l of links) wire(l);
+    for (const l of links) expect(linkStatus(l)).toBe('live');
+  });
+
+  it('reports broken when the pack payload is gone', () => {
+    const links = contributionLinks(hqRoot, packDir, contributes);
+    links.forEach(wire);
+    fs.rmSync(packDir, { recursive: true, force: true });
+    for (const l of links) expect(linkStatus(l)).toBe('broken');
+  });
+
+  it('reports foreign when the dst points elsewhere or is a real file', () => {
+    const [skillLink, cmdLink] = contributionLinks(hqRoot, packDir, contributes);
+    // foreign symlink: points at some other path
+    fs.mkdirSync(path.dirname(skillLink.dst), { recursive: true });
+    const other = path.join(hqRoot, 'somewhere-else');
+    fs.mkdirSync(other, { recursive: true });
+    fs.symlinkSync(other, skillLink.dst);
+    expect(linkStatus(skillLink)).toBe('foreign');
+    // foreign real file
+    fs.mkdirSync(path.dirname(cmdLink.dst), { recursive: true });
+    fs.writeFileSync(cmdLink.dst, 'host-owned content');
+    expect(linkStatus(cmdLink)).toBe('foreign');
+  });
+
+  it('unwirePack removes ONLY our symlinks, leaving foreign ones', () => {
+    const [skillLink, cmdLink] = contributionLinks(hqRoot, packDir, contributes);
+    wire(skillLink); // our link
+    // cmd slot occupied by a foreign symlink (another pack / host content)
+    fs.mkdirSync(path.dirname(cmdLink.dst), { recursive: true });
+    const other = path.join(hqRoot, 'foreign-target.md');
+    fs.writeFileSync(other, 'x');
+    fs.symlinkSync(other, cmdLink.dst);
+
+    const result = unwirePack(hqRoot, packDir, contributes);
+
+    expect(fs.existsSync(skillLink.dst)).toBe(false); // ours removed
+    expect(fs.lstatSync(cmdLink.dst).isSymbolicLink()).toBe(true); // foreign kept
+    expect(result.unlinked.map((u) => u.item)).toEqual(['demo-skill']);
+    expect(result.skipped.map((s) => s.item)).toEqual(['demo-cmd']);
+  });
+
+  it('unwirePack removes broken (dangling) links that point into our pack', () => {
+    const links = contributionLinks(hqRoot, packDir, contributes);
+    links.forEach(wire);
+    fs.rmSync(packDir, { recursive: true, force: true }); // now all broken
+    const result = unwirePack(hqRoot, packDir, contributes);
+    expect(result.unlinked).toHaveLength(2);
+    for (const l of links) expect(fs.existsSync(l.dst)).toBe(false);
+    for (const l of links) expect(() => fs.lstatSync(l.dst)).toThrow(); // gone
+  });
+});
+
+describe('listInstalledPacks', () => {
+  let hqRoot: string;
+
+  beforeEach(() => {
+    hqRoot = mkTmp('hq-pc-list-');
+  });
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  it('returns [] when core/packages is absent', () => {
+    expect(listInstalledPacks(hqRoot)).toEqual([]);
+  });
+
+  it('walks packs, skips README + .archive, and parses the stamped source', () => {
+    const dir = packagesDir(hqRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'README.md'), '# packages');
+    fs.mkdirSync(path.join(dir, '.archive', 'old-pack-2026'), { recursive: true });
+
+    const p = path.join(dir, 'hq-pack-one');
+    fs.mkdirSync(p, { recursive: true });
+    fs.writeFileSync(
+      path.join(p, 'package.yaml'),
+      'source: "github:acme/repo#packages/hq-pack-one"\nname: hq-pack-one\nversion: 2.1.0\ncontributes:\n  skills:\n    - foo\n',
+    );
+
+    const packs = listInstalledPacks(hqRoot);
+    expect(packs.map((x) => x.name)).toEqual(['hq-pack-one']);
+    expect(packs[0].manifest?.version).toBe('2.1.0');
+    expect(packs[0].manifest?.source).toBe('github:acme/repo#packages/hq-pack-one');
+  });
+
+  it('surfaces an unreadable manifest as error, not a throw', () => {
+    const dir = packagesDir(hqRoot);
+    const p = path.join(dir, 'hq-pack-bad');
+    fs.mkdirSync(p, { recursive: true });
+    fs.writeFileSync(path.join(p, 'package.yaml'), 'name: [unclosed\n');
+    const packs = listInstalledPacks(hqRoot);
+    expect(packs).toHaveLength(1);
+    expect(packs[0].manifest).toBeNull();
+    expect(packs[0].error).toMatch(/invalid/i);
+  });
+});

package/src/utils/pack-contributions.ts

@@ -0,0 +1,303 @@
+/**
+ * Content-pack contribution helpers -- the single source of truth (in TS) for
+ * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * `core/scripts/scan-packages.sh`.
+ *
+ * `pack-install.ts` only INSTALLS content packs (into `core/packages/<name>/`,
+ * tracked by filesystem presence -- there is no registry file). The list /
+ * update / uninstall lifecycle in `commands/packs.ts` needs to reason about the
+ * SAME mapping so it can report link health and cleanly un-wire a pack without
+ * leaving dangling symlinks. That mapping is duplicated today in two places:
+ *
+ *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
+ *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ *
+ * This module re-encodes it once for TS callers. A parity test
+ * (`pack-contributions.test.ts`) asserts it matches scan-packages.sh's `case`
+ * arms so the three copies cannot drift.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import type { PackManifest, PackContributeKey } from '../types.js';
+
+/** A single symlink a pack contributes: dst (host path) -> src (inside pack). */
+export interface WiredLink {
+  key: PackContributeKey;
+  item: string;
+  src: string; // absolute path inside core/packages/<pack>/
+  dst: string; // absolute host path the symlink lives at
+}
+
+export type LinkStatus =
+  | 'live' // dst is a symlink -> this pack's src, and src exists
+  | 'broken' // dst is a symlink -> this pack's src, but src is gone
+  | 'missing' // dst does not exist (declared but never wired / already removed)
+  | 'foreign'; // dst exists but points elsewhere or is a real file (collision)
+
+/**
+ * Map one contributes entry to its source/host paths. MUST stay in lockstep
+ * with scan-packages.sh:wire_one_package and pack-install.ts:validateManifest.
+ */
+function linkFor(
+  hqRoot: string,
+  packDir: string,
+  key: PackContributeKey,
+  item: string,
+): WiredLink {
+  let srcRel: string;
+  let dstRel: string;
+  switch (key) {
+    case 'workers':
+      srcRel = path.join('workers', item);
+      dstRel = path.join('core', 'workers', 'public', item);
+      break;
+    case 'knowledge':
+      srcRel = path.join('knowledge', item);
+      dstRel = path.join('core', 'knowledge', 'public', item);
+      break;
+    case 'skills':
+      srcRel = path.join('skills', item);
+      dstRel = path.join('.claude', 'skills', item);
+      break;
+    case 'commands':
+      srcRel = path.join('commands', `${item}.md`);
+      dstRel = path.join('.claude', 'commands', `${item}.md`);
+      break;
+    case 'hooks':
+      srcRel = path.join('hooks', `${item}.sh`);
+      dstRel = path.join('.claude', 'hooks', `${item}.sh`);
+      break;
+    case 'policies':
+      srcRel = path.join('policies', `${item}.md`);
+      dstRel = path.join('core', 'policies', `${item}.md`);
+      break;
+    case 'scripts':
+      srcRel = path.join('scripts', item);
+      dstRel = path.join('core', 'scripts', item);
+      break;
+  }
+  return {
+    key,
+    item,
+    src: path.join(packDir, srcRel),
+    dst: path.join(hqRoot, dstRel),
+  };
+}
+
+/**
+ * Every symlink a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh.
+ */
+export function contributionLinks(
+  hqRoot: string,
+  packDir: string,
+  contributes: Partial<Record<PackContributeKey, string[]>>,
+): WiredLink[] {
+  const links: WiredLink[] = [];
+  for (const [key, items] of Object.entries(contributes) as [
+    PackContributeKey,
+    unknown,
+  ][]) {
+    if (!Array.isArray(items)) continue;
+    for (const item of items) {
+      if (typeof item !== 'string' || item.length === 0) continue;
+      links.push(linkFor(hqRoot, packDir, key, item));
+    }
+  }
+  return links;
+}
+
+/** Classify a host path against the link that should own it. */
+export function linkStatus(link: WiredLink): LinkStatus {
+  let st: fs.Stats | undefined;
+  try {
+    st = fs.lstatSync(link.dst);
+  } catch {
+    return 'missing';
+  }
+  if (!st.isSymbolicLink()) {
+    return 'foreign'; // a real file/dir occupies the slot -- not ours
+  }
+  let target: string;
+  try {
+    target = fs.readlinkSync(link.dst);
+  } catch {
+    return 'foreign';
+  }
+  // scan-packages.sh writes the symlink target as the absolute `src` path, so a
+  // direct compare is correct. Resolve both to be robust to trailing slashes.
+  const resolvedTarget = path.resolve(path.dirname(link.dst), target);
+  if (path.resolve(link.src) !== resolvedTarget) {
+    return 'foreign'; // points at another pack / somewhere else
+  }
+  return fs.existsSync(link.src) ? 'live' : 'broken';
+}
+
+// ---------------------------------------------------------------------------
+// Installed-pack discovery
+// ---------------------------------------------------------------------------
+
+/** A content pack's manifest plus the install-time stamped source. */
+export interface InstalledPackManifest extends PackManifest {
+  source?: string; // stamped by pack-install.ts:stampInstallSource
+}
+
+export interface InstalledPack {
+  name: string; // directory name (== manifest.name when well-formed)
+  dir: string; // absolute path to core/packages/<name>/
+  manifest: InstalledPackManifest | null; // null when package.yaml is unreadable
+  error?: string; // parse/validation error message when manifest is null
+}
+
+/** Absolute path to `<hqRoot>/core/packages`. */
+export function packagesDir(hqRoot: string): string {
+  return path.join(hqRoot, 'core', 'packages');
+}
+
+/** Read and shallowly validate a pack's package.yaml. */
+export function readPackManifest(packDir: string): {
+  manifest: InstalledPackManifest | null;
+  error?: string;
+} {
+  const manifestPath = path.join(packDir, 'package.yaml');
+  if (!fs.existsSync(manifestPath)) {
+    return { manifest: null, error: 'package.yaml missing' };
+  }
+  try {
+    const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object') {
+      return { manifest: null, error: 'package.yaml is not a mapping' };
+    }
+    return { manifest: parsed as InstalledPackManifest };
+  } catch (e) {
+    return { manifest: null, error: `package.yaml invalid: ${(e as Error).message}` };
+  }
+}
+
+/**
+ * Walk `core/packages/<name>/package.yaml`. Skips the `.archive` dir, the bundled
+ * `README.md`, and any non-directory entry. Filesystem presence is the source
+ * of truth for installed content packs.
+ */
+export function listInstalledPacks(hqRoot: string): InstalledPack[] {
+  const dir = packagesDir(hqRoot);
+  if (!fs.existsSync(dir)) return [];
+  const out: InstalledPack[] = [];
+  for (const name of fs.readdirSync(dir).sort()) {
+    if (name.startsWith('.')) continue; // .archive, .DS_Store, etc.
+    const packDir = path.join(dir, name);
+    let st: fs.Stats;
+    try {
+      st = fs.statSync(packDir);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue; // README.md and friends
+    const { manifest, error } = readPackManifest(packDir);
+    if (!manifest && !fs.existsSync(path.join(packDir, 'package.yaml'))) {
+      continue; // a plain dir that isn't a pack -- ignore silently
+    }
+    out.push({ name, dir: packDir, manifest, error });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Un-wiring (the uninstall guarantee)
+// ---------------------------------------------------------------------------
+
+export interface UnwireResult {
+  unlinked: Array<{ key: PackContributeKey; item: string; dst: string }>;
+  skipped: Array<{
+    key: PackContributeKey;
+    item: string;
+    dst: string;
+    reason: 'foreign' | 'missing';
+  }>;
+}
+
+/**
+ * Remove only the host symlinks that resolve into THIS pack's directory
+ * (status `live` or `broken`). Foreign links and real files are left in place
+ * -- same collision philosophy as scan-packages.sh. This is what prevents an
+ * uninstall from leaving dangling symlinks behind.
+ */
+export function unwirePack(
+  hqRoot: string,
+  packDir: string,
+  contributes: Partial<Record<PackContributeKey, string[]>>,
+): UnwireResult {
+  const result: UnwireResult = { unlinked: [], skipped: [] };
+  for (const link of contributionLinks(hqRoot, packDir, contributes)) {
+    const status = linkStatus(link);
+    if (status === 'live' || status === 'broken') {
+      try {
+        fs.unlinkSync(link.dst);
+        result.unlinked.push({ key: link.key, item: link.item, dst: link.dst });
+      } catch {
+        result.skipped.push({
+          key: link.key,
+          item: link.item,
+          dst: link.dst,
+          reason: 'foreign',
+        });
+      }
+    } else {
+      result.skipped.push({
+        key: link.key,
+        item: link.item,
+        dst: link.dst,
+        reason: status === 'missing' ? 'missing' : 'foreign',
+      });
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Host introspection: hqVersion + recommended_packages catalog
+// ---------------------------------------------------------------------------
+
+/** Locate core.yaml -- v14+ nests it under `core/`, older layouts at the root. */
+function coreYamlPath(hqRoot: string): string | null {
+  const nested = path.join(hqRoot, 'core', 'core.yaml');
+  if (fs.existsSync(nested)) return nested;
+  const flat = path.join(hqRoot, 'core.yaml');
+  if (fs.existsSync(flat)) return flat;
+  return null;
+}
+
+export function readHqVersion(hqRoot: string): string | null {
+  const p = coreYamlPath(hqRoot);
+  if (!p) return null;
+  try {
+    const c = yaml.load(fs.readFileSync(p, 'utf-8')) as { hqVersion?: string };
+    return c?.hqVersion ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export interface CatalogEntry {
+  source: string;
+  description?: string;
+  conditional?: string;
+  auto_install?: boolean;
+}
+
+/** Read `recommended_packages` from core.yaml (the curated content-pack catalog). */
+export function readRecommendedPackages(hqRoot: string): CatalogEntry[] {
+  const p = coreYamlPath(hqRoot);
+  if (!p) return [];
+  try {
+    const c = yaml.load(fs.readFileSync(p, 'utf-8')) as {
+      recommended_packages?: CatalogEntry[];
+    };
+    const list = c?.recommended_packages;
+    return Array.isArray(list) ? list : [];
+  } catch {
+    return [];
+  }
+}