@indigoai-us/hq-cli 5.50.1 → 5.51.0

package/src/commands/pack-install.test.ts

@@ -26,6 +26,7 @@ import {
   runScanPackages,
   stampInstallSource,
   validateManifest,
+  assertPackDependencies,
   getStartedLine,
   toMarketplaceListing,
   fetchMarketplace,
@@ -1319,3 +1320,146 @@ describe('pack-install: fetchMarketplace honors the envelope-mapped contentHash'
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// requires.packs — pack-to-pack dependencies (M0)
+// ---------------------------------------------------------------------------
+
+describe('requires.packs validation (M0)', () => {
+  // Mirrors the author/capabilities helper: a minimal otherwise-valid payload
+  // whose only variable is the `requires.packs` block under test.
+  function writePackWithRequires(extraYaml: string): string {
+    const dir = mkFakePackPayload({ 'knowledge/demo/README.md': '# demo' });
+    fs.writeFileSync(
+      path.join(dir, 'package.yaml'),
+      [
+        'name: hq-pack-accounting',
+        'version: 1.0.0',
+        "publisher: '@indigoai-us'",
+        'access: public',
+        'requires:',
+        "  hqCore: '>=15.1.0'",
+        extraYaml,
+        'contributes:',
+        '  knowledge:',
+        '    - demo',
+        '',
+      ].join('\n'),
+    );
+    return dir;
+  }
+
+  it('a manifest WITHOUT requires.packs validates (backwards-compatible)', () => {
+    const dir = writePackWithRequires('');
+    const m = validateManifest(dir, '15.1.0');
+    expect(m.requires.packs).toBeUndefined();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('a well-formed requires.packs (with and without version) is accepted', () => {
+    const dir = writePackWithRequires(
+      [
+        '  packs:',
+        '    - name: hq-pack-crm',
+        "      version: '>=1.0.0'",
+        '    - name: hq-pack-other',
+      ].join('\n'),
+    );
+    const m = validateManifest(dir, '15.1.0');
+    expect(m.requires.packs).toEqual([
+      { name: 'hq-pack-crm', version: '>=1.0.0' },
+      { name: 'hq-pack-other' },
+    ]);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects requires.packs that is not a list', () => {
+    const dir = writePackWithRequires('  packs: hq-pack-crm');
+    expect(() => validateManifest(dir, '15.1.0')).toThrow(/requires\.packs must be a list/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an entry with an invalid pack name', () => {
+    const dir = writePackWithRequires(['  packs:', '    - name: not-an-hq-pack'].join('\n'));
+    expect(() => validateManifest(dir, '15.1.0')).toThrow(/requires\.packs\[\]\.name/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an entry with an invalid version range', () => {
+    const dir = writePackWithRequires(
+      ['  packs:', '    - name: hq-pack-crm', '      version: not-a-range'].join('\n'),
+    );
+    expect(() => validateManifest(dir, '15.1.0')).toThrow(/invalid version range/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe('assertPackDependencies (M0)', () => {
+  let hqRoot: string;
+  beforeEach(() => {
+    hqRoot = mkFakeHq();
+  });
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  // Seed an installed pack by writing core/packages/<name>/package.yaml — the
+  // filesystem-presence source of truth listInstalledPacks reads (NOT modules.yaml).
+  function seedInstalledPack(name: string, version?: string): void {
+    const dir = path.join(hqRoot, 'core', 'packages', name);
+    fs.mkdirSync(dir, { recursive: true });
+    const lines = [`name: ${name}`];
+    if (version) lines.push(`version: ${version}`);
+    fs.writeFileSync(path.join(dir, 'package.yaml'), lines.join('\n') + '\n');
+  }
+
+  it('is a no-op when the pack declares no requires.packs', () => {
+    const pkg = fakeManifest({ requires: { hqCore: '>=15.1.0' } });
+    expect(() => assertPackDependencies(hqRoot, pkg)).not.toThrow();
+  });
+
+  it('passes when every required pack is installed (no version constraint)', () => {
+    seedInstalledPack('hq-pack-crm', '1.2.0');
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).not.toThrow();
+  });
+
+  it('throws a clear, actionable error when a required pack is missing', () => {
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).toThrow(
+      /requires hq-pack-crm, which is not installed/,
+    );
+  });
+
+  it('passes when the installed version satisfies the required range', () => {
+    seedInstalledPack('hq-pack-crm', '1.2.0');
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm', version: '>=1.0.0' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).not.toThrow();
+  });
+
+  it('throws when the installed version does NOT satisfy the required range', () => {
+    seedInstalledPack('hq-pack-crm', '0.9.0');
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm', version: '>=1.0.0' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).toThrow(/requires hq-pack-crm >=1\.0\.0/);
+  });
+
+  it('rejects a pack that lists itself as a dependency', () => {
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-accounting' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).toThrow(/cannot list itself/);
+  });
+});

package/src/commands/pack-install.ts

@@ -53,7 +53,7 @@ import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
 import semverGt from 'semver/functions/gt.js';
 import { findHqRoot } from '../utils/manifest.js';
-import { readHqVersion, routeContribution } from '../utils/pack-contributions.js';
+import { readHqVersion, routeContribution, listInstalledPacks } from '../utils/pack-contributions.js';
 import { CONTRIBUTION_TABLE, payloadFor } from '../utils/contribution-table.js';
 import { safeExtractTarball } from './safe-extract.js';
 import { vaultApiFetchPublic } from '../utils/vault-api.js';
@@ -1201,6 +1201,40 @@ export function validateManifest(
       `Host hqCore ${hqVersion} does not satisfy pack requirement ${range}`
     );
   }
+  // 6b. requires.packs (M0) — OPTIONAL pack-to-pack dependencies. Absent → legacy
+  // behavior (hqCore is the only prerequisite). Present → a list of
+  // { name, version? } where `name` is a valid hq-pack name and `version` (if
+  // given) is a valid semver RANGE. SHAPE validation only (no filesystem) so a
+  // malformed dependency can't masquerade as valid; whether the named packs are
+  // actually INSTALLED is enforced at install time by assertPackDependencies
+  // (which needs hqRoot — a pure manifest validator doesn't have it).
+  const reqPacks = m.requires?.packs;
+  if (reqPacks !== undefined) {
+    if (!Array.isArray(reqPacks)) {
+      throw new Error('requires.packs must be a list of { name, version? } entries');
+    }
+    for (const dep of reqPacks) {
+      if (!dep || typeof dep !== 'object' || Array.isArray(dep)) {
+        throw new Error(
+          'requires.packs entries must be mappings with a name (and optional version)'
+        );
+      }
+      const d = dep as unknown as Record<string, unknown>;
+      if (typeof d.name !== 'string' || !/^hq-pack-[a-z0-9][a-z0-9-]*$/.test(d.name)) {
+        throw new Error(
+          `requires.packs[].name "${d.name}" must match ^hq-pack-[a-z0-9][a-z0-9-]*$`
+        );
+      }
+      if (
+        d.version !== undefined &&
+        (typeof d.version !== 'string' || !semverValidRange(d.version))
+      ) {
+        throw new Error(
+          `requires.packs entry for "${d.name}" has an invalid version range "${d.version}"`
+        );
+      }
+    }
+  }
   // 7. contributes has at least one non-empty subfield
   const contributes = (m.contributes ?? {}) as PackManifest['contributes'];
   const nonEmpty = Object.values(contributes).some(
@@ -1312,6 +1346,51 @@ export function validateManifest(
   return m as PackManifest;
 }
 
+// ---------------------------------------------------------------------------
+// Pack-to-pack dependency pre-flight (M0)
+// ---------------------------------------------------------------------------
+
+/**
+ * Enforce a pack's `requires.packs`: every named dependency MUST already be
+ * installed (and satisfy its optional semver RANGE) before we write anything.
+ *
+ * Installed packs are discovered by FILESYSTEM PRESENCE via `listInstalledPacks`
+ * — deliberately NOT `modules.yaml`, which `installPack` no longer writes under
+ * the v12+ layout (a modules.yaml-based check would silently ignore every modern
+ * pack). Throws on the first unmet dependency so the install aborts with NO
+ * partial state (it is called before installToPackages). No-op when
+ * `requires.packs` is absent/empty, keeping legacy packs unaffected.
+ */
+export function assertPackDependencies(hqRoot: string, pkg: PackManifest): void {
+  const deps = pkg.requires?.packs ?? [];
+  if (deps.length === 0) return;
+  const installed = new Map<string, string | undefined>();
+  for (const p of listInstalledPacks(hqRoot)) {
+    // Key on the manifest name when readable, else the directory name.
+    installed.set(p.manifest?.name ?? p.name, p.manifest?.version);
+  }
+  for (const dep of deps) {
+    if (dep.name === pkg.name) {
+      throw new Error(`Pack ${pkg.name} cannot list itself in requires.packs.`);
+    }
+    if (!installed.has(dep.name)) {
+      throw new Error(
+        `Pack ${pkg.name} requires ${dep.name}, which is not installed. ` +
+          `Install it first, e.g.: hq install marketplace:${dep.name}`
+      );
+    }
+    if (dep.version) {
+      const have = installed.get(dep.name);
+      if (!have || !semverSatisfies(have, dep.version, { includePrerelease: true })) {
+        throw new Error(
+          `Pack ${pkg.name} requires ${dep.name} ${dep.version}, but ` +
+            `${dep.name}${have ? ` ${have}` : ' (version unknown)'} is installed.`
+        );
+      }
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Post-install get-started line (US-005)
 // ---------------------------------------------------------------------------
@@ -1919,6 +1998,12 @@ export async function installPack(
 
     const pkg = validateManifest(fetched.payloadDir, hqVersion);
 
+    // M0 — pack-to-pack dependency pre-flight. Runs BEFORE any prompts or writes
+    // so a missing/unsatisfied `requires.packs` aborts with no partial state, and
+    // before we bother the operator with hook/MCP trust prompts for a pack that
+    // can't install anyway.
+    assertPackDependencies(hqRoot, pkg);
+
     if (pkg.conditional) {
       const allowed = await confirmConditional(pkg, opts.allowHooks ?? false);
       if (!allowed) {

package/src/commands/packs.ts

@@ -38,6 +38,7 @@ import {
   contributionLinks,
   linkStatus,
   listInstalledPacks,
+  findDependentPacks,
   readPackManifest,
   unwirePack,
   unwirePackMcp,
@@ -394,6 +395,7 @@ interface UninstallResult {
 interface UninstallOpts extends CommonOpts {
   yes?: boolean;
   archive?: boolean; // commander sets false for --no-archive
+  force?: boolean; // bypass the dependents guard (M0)
 }
 
 function archiveTimestamp(): string {
@@ -413,6 +415,22 @@ async function runUninstall(name: string, opts: UninstallOpts): Promise<Uninstal
     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);
 
@@ -550,6 +568,7 @@ export function registerPacksCommand(parent: Command): void {
     .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) {

package/src/commands/people.test.ts

@@ -19,7 +19,11 @@ import {
   resolveNameToEmail,
   type PersonRecord,
 } from "../utils/people.js";
-import { registerPeopleCommand, resolveCompanySlug } from "./people.js";
+import {
+  registerPeopleCommand,
+  resolveCompanySlug,
+  type RefreshPeopleRoster,
+} from "./people.js";
 
 // ---------------------------------------------------------------------------
 // Filesystem fixture helpers
@@ -335,15 +339,20 @@ describe("companyPeopleDir", () => {
 // Wired CLI surface (list / search / resolve)
 // ---------------------------------------------------------------------------
 
-function buildProgram(): Command {
+function buildProgram(deps?: { refreshRoster?: RefreshPeopleRoster }): Command {
   const program = new Command();
   program.exitOverride(); // throw instead of process.exit on commander errors
-  registerPeopleCommand(program);
+  registerPeopleCommand(program, deps);
   return program;
 }
 
-async function run(args: string[]): Promise<void> {
-  await buildProgram().parseAsync(["node", "hq", ...args]);
+async function run(
+  args: string[],
+  deps: { refreshRoster?: RefreshPeopleRoster } = {
+    refreshRoster: async () => {},
+  },
+): Promise<void> {
+  await buildProgram(deps).parseAsync(["node", "hq", ...args]);
 }
 
 describe("hq people (wired)", () => {
@@ -396,6 +405,104 @@ describe("hq people (wired)", () => {
     expect(out[0].email).toBe("jane@acme.com");
   });
 
+  it("search local hit does not refresh the roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await run(
+      [
+        "people",
+        "search",
+        "jane",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+      ],
+      { refreshRoster },
+    );
+    expect(refreshRoster).not.toHaveBeenCalled();
+  });
+
+  it("search local miss refreshes once and retries from the refreshed roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      makePerson("acme", "ada-lovelace", {
+        name: "Ada Lovelace",
+        email: "ada@acme.com",
+        type: "internal",
+      });
+    });
+
+    await run(
+      [
+        "people",
+        "search",
+        "ada",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(refreshRoster).toHaveBeenCalledWith(tmpRoot, "acme");
+    const out = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatchObject({
+      name: "Ada Lovelace",
+      email: "ada@acme.com",
+    });
+  });
+
+  it("search local miss with refresh failure reports the original empty JSON and logs a note", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      throw new Error("offline");
+    });
+
+    await run(
+      [
+        "people",
+        "search",
+        "ada",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual([]);
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Could not refresh people roster"),
+    );
+  });
+
+  it("search --local-only skips refresh on a miss", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await run(
+      [
+        "people",
+        "search",
+        "ada",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+        "--local-only",
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual([]);
+  });
+
   it("resolve prints the bare email on stdout", async () => {
     await run([
       "people",
@@ -409,6 +516,106 @@ describe("hq people (wired)", () => {
     expect(logSpy).toHaveBeenCalledWith("jane@acme.com");
   });
 
+  it("resolve local hit does not refresh the roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await run(
+      [
+        "people",
+        "resolve",
+        "Jane Smith",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+      ],
+      { refreshRoster },
+    );
+    expect(refreshRoster).not.toHaveBeenCalled();
+  });
+
+  it("resolve local miss refreshes once and retries from the refreshed roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      makePerson("acme", "ada-lovelace", {
+        name: "Ada Lovelace",
+        email: "ada@acme.com",
+        type: "internal",
+      });
+    });
+
+    await run(
+      [
+        "people",
+        "resolve",
+        "Ada Lovelace",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(refreshRoster).toHaveBeenCalledWith(tmpRoot, "acme");
+    expect(logSpy).toHaveBeenCalledWith("ada@acme.com");
+  });
+
+  it("resolve local miss with refresh failure reports unchanged not_found JSON and logs a note", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      throw new Error("not signed in");
+    });
+
+    await expect(
+      run(
+        [
+          "people",
+          "resolve",
+          "Ada Lovelace",
+          "--company",
+          "acme",
+          "--hq-root",
+          tmpRoot,
+          "--json",
+        ],
+        { refreshRoster },
+      ),
+    ).rejects.toThrow("__exit__");
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual({
+      status: "not_found",
+    });
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Could not refresh people roster"),
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("resolve --local-only skips refresh on a miss", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await expect(
+      run(
+        [
+          "people",
+          "resolve",
+          "Ada Lovelace",
+          "--company",
+          "acme",
+          "--hq-root",
+          tmpRoot,
+          "--json",
+          "--local-only",
+        ],
+        { refreshRoster },
+      ),
+    ).rejects.toThrow("__exit__");
+
+    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual({
+      status: "not_found",
+    });
+  });
+
   it("resolve exits non-zero when not found", async () => {
     await expect(
       run([