@indigoai-us/hq-cli 5.50.1 → 5.50.2

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/types.ts

@@ -95,12 +95,30 @@ export interface PackAuthor {
   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';
-  requires: { hqCore: string }; // semver range
+  /**
+   * 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;

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

@@ -16,11 +16,13 @@ import {
   contributionLinks,
   linkStatus,
   listInstalledPacks,
+  findDependentPacks,
   unwirePack,
   unwirePackMcp,
   packagesDir,
   readHqVersion,
   type WiredLink,
+  type InstalledPack,
 } from './pack-contributions.js';
 import { parse as parseToml } from 'smol-toml';
 import {
@@ -489,3 +491,54 @@ describe('US-009: unwirePackMcp (mcp un-registration parallel to symlink unwire)
     expect(fs.readFileSync(codexConfigPath(env), 'utf-8')).toBe(original);
   });
 });
+
+// ---------------------------------------------------------------------------
+// findDependentPacks — uninstall dependents guard (M0)
+// ---------------------------------------------------------------------------
+
+describe('findDependentPacks (M0)', () => {
+  function ip(
+    name: string,
+    requiresPacks?: Array<{ name: string; version?: string }>,
+  ): InstalledPack {
+    return {
+      name,
+      dir: `/tmp/nope/${name}`,
+      manifest: {
+        name,
+        version: '1.0.0',
+        publisher: '@indigoai-us',
+        access: 'public',
+        requires: { hqCore: '>=15.0.0', packs: requiresPacks },
+        contributes: { skills: ['x'] },
+      },
+    } as InstalledPack;
+  }
+
+  it('returns the packs that require the named pack', () => {
+    const installed = [
+      ip('hq-pack-crm'),
+      ip('hq-pack-accounting', [{ name: 'hq-pack-crm', version: '>=1.0.0' }]),
+      ip('hq-pack-unrelated'),
+    ];
+    const deps = findDependentPacks(installed, 'hq-pack-crm');
+    expect(deps.map((p) => p.name)).toEqual(['hq-pack-accounting']);
+  });
+
+  it('returns empty when no installed pack requires it', () => {
+    const installed = [ip('hq-pack-crm'), ip('hq-pack-unrelated')];
+    expect(findDependentPacks(installed, 'hq-pack-crm')).toEqual([]);
+  });
+
+  it('never counts a pack that lists itself as its own dependent', () => {
+    // Defensive: a self-referencing manifest (rejected at install) must not make
+    // a pack un-removable.
+    const installed = [ip('hq-pack-weird', [{ name: 'hq-pack-weird' }])];
+    expect(findDependentPacks(installed, 'hq-pack-weird')).toEqual([]);
+  });
+
+  it('tolerates an unreadable manifest (manifest === null)', () => {
+    const broken: InstalledPack = { name: 'hq-pack-broken', dir: '/tmp/nope', manifest: null };
+    expect(findDependentPacks([broken], 'hq-pack-crm')).toEqual([]);
+  });
+});

package/src/utils/pack-contributions.ts

@@ -264,6 +264,23 @@ export function listInstalledPacks(hqRoot: string): InstalledPack[] {
   return out;
 }
 
+/**
+ * Installed packs that declare `name` in their `requires.packs` (M0). Pure over
+ * the supplied list — the uninstall dependents guard calls this with
+ * `listInstalledPacks(hqRoot)`. Excludes the pack named `name` itself, so a
+ * self-reference never counts as its own dependent.
+ */
+export function findDependentPacks(
+  installed: InstalledPack[],
+  name: string,
+): InstalledPack[] {
+  return installed.filter(
+    (p) =>
+      p.name !== name &&
+      (p.manifest?.requires?.packs ?? []).some((d) => d.name === name),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Un-wiring (the uninstall guarantee)
 // ---------------------------------------------------------------------------

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

@@ -49,6 +49,51 @@ describe("shouldSkipGate", () => {
   });
 });
 
+describe("prefix install helpers", () => {
+  it("derives the npm prefix from unix global package layouts", async () => {
+    const { __test__ } = await loadModule();
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global/lib/node_modules/@indigoai-us/hq-cli",
+      ),
+    ).toBe("/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global");
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "/usr/local/lib/node_modules/@indigoai-us/hq-cli",
+      ),
+    ).toBe("/usr/local");
+  });
+
+  it("derives the npm prefix from a windows-style package layout", async () => {
+    const { __test__ } = await loadModule();
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "C:\\Users\\x\\AppData\\Roaming\\npm\\node_modules\\@indigoai-us\\hq-cli",
+      ),
+    ).toBe("C:/Users/x/AppData/Roaming/npm");
+  });
+
+  it("returns null when the package path is not under node_modules", async () => {
+    const { __test__ } = await loadModule();
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "/Users/x/dev/hq/packages/hq-cli",
+      ),
+    ).toBeNull();
+  });
+
+  it("builds the prefixed npm install argv", async () => {
+    const { __test__ } = await loadModule();
+    expect(__test__.buildPrefixedInstallArgv("/tmp/npm-global")).toEqual([
+      "install",
+      "-g",
+      "--prefix",
+      "/tmp/npm-global",
+      "@indigoai-us/hq-cli@latest",
+    ]);
+  });
+});
+
 describe("enforceVersionGate — opt-out + soft paths (no process.exit)", () => {
   it("is silent + no fetch when HQ_NO_UPDATE_CHECK=1", async () => {
     vi.stubEnv("HQ_NO_UPDATE_CHECK", "1");
@@ -242,4 +287,81 @@ describe("enforceVersionGate — hard-update path", () => {
     expect(body.currentVersion).toBe("5.10.0");
     expect(typeof body.platform).toBe("string");
   });
+
+  it("installs with the resolved running prefix instead of the bare server command", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const runner = vi.fn().mockReturnValue({ ok: true });
+    const { __test__ } = await loadModule();
+    const prefix = "/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global";
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
+        },
+        {
+          resolvePrefix: () => prefix,
+          runner,
+        },
+      ),
+    ).toThrow(/__process_exit__:0/);
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(runner).toHaveBeenCalledWith("npm", [
+      "install",
+      "-g",
+      "--prefix",
+      prefix,
+      "@indigoai-us/hq-cli@latest",
+    ]);
+    expect(runner).not.toHaveBeenCalledWith("npm", [
+      "install",
+      "-g",
+      "@indigoai-us/hq-cli@latest",
+    ]);
+  });
+
+  it("falls back to the server updateCommand when no running prefix resolves", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const performUpdateString = vi.fn().mockReturnValue({ ok: true });
+    const { __test__ } = await loadModule();
+    const updateCommand = "npm install -g @indigoai-us/hq-cli@latest";
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand,
+        },
+        {
+          performUpdateString,
+          resolvePrefix: () => null,
+        },
+      ),
+    ).toThrow(/__process_exit__:0/);
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(performUpdateString).toHaveBeenCalledWith(updateCommand);
+  });
 });