@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/src/commands/packs.ts

@@ -38,8 +38,10 @@ import {
   contributionLinks,
   linkStatus,
   listInstalledPacks,
+  findDependentPacks,
   readPackManifest,
   unwirePack,
+  unwirePackMcp,
   readHqVersion,
   readRecommendedPackages,
   packagesDir,
@@ -303,6 +305,7 @@ interface UpdateOpts extends CommonOpts {
   checkOnly?: boolean;
   yes?: boolean;
   allowHooks?: boolean;
+  allowMcp?: boolean;
   branch?: boolean;
 }
 
@@ -359,6 +362,7 @@ async function runUpdate(name: string | undefined, opts: UpdateOpts): Promise<Up
       try {
         await installPack(source, {
           allowHooks: opts.yes || opts.allowHooks,
+          allowMcp: opts.yes || opts.allowMcp,
           followBranch: opts.branch,
           quiet: wantsJson(opts),
         });
@@ -391,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 {
@@ -410,9 +415,46 @@ 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);
 
+  // 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) {
@@ -495,8 +537,9 @@ export function registerPacksCommand(parent: Command): void {
     .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('-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 {
@@ -525,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/pkg-install.ts

@@ -43,16 +43,18 @@ export function registerPackageInstallCommand(parent: Command): void {
     )
     .option('--company <co>', 'Scope the package to a specific company (registry flow only)')
     .option('--allow-hooks', 'Skip the hooks confirmation prompt (content-pack flow)')
+    .option('--allow-mcp', 'Skip the MCP server confirmation prompt (content-pack flow)')
     .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
     .action(
       async (
         source: string,
-        opts: { company?: string; allowHooks?: boolean; branch?: boolean }
+        opts: { company?: string; allowHooks?: boolean; allowMcp?: boolean; branch?: boolean }
       ) => {
         try {
           if (sourceMatchesPackPattern(source)) {
             await installPack(source, {
               allowHooks: opts.allowHooks,
+              allowMcp: opts.allowMcp,
               followBranch: opts.branch,
             });
           } else {
@@ -62,6 +64,7 @@ export function registerPackageInstallCommand(parent: Command): void {
             // listings transport — the live install path — instead.
             await installPack(`${MARKETPLACE_PREFIX}${source}`, {
               allowHooks: opts.allowHooks,
+              allowMcp: opts.allowMcp,
               followBranch: opts.branch,
             });
           }

package/src/index.ts

@@ -44,6 +44,7 @@ import { registerSourcesCommand } from "./commands/sources.js";
 import { registerSignalsCommand } from "./commands/signals.js";
 import { registerReindexCommand } from "./commands/reindex.js";
 import { registerRescueCommand } from "./commands/rescue.js";
+import { registerMcpCommand } from "./commands/mcp-status.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import {
@@ -199,6 +200,11 @@ registerReindexCommand(program);
 // shipped from @indigoai-us/hq-cloud.
 registerRescueCommand(program);
 
+// MCP pack observability (subcommand group — `hq mcp status`). Read-only
+// provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
+// off the configs, NOT linkStatus), with secret-redacted output + `--json`.
+registerMcpCommand(program);
+
 (async () => {
   try {
     Sentry.addBreadcrumb({

package/src/types.ts

@@ -8,6 +8,8 @@
  *                            knowledge/public/hq-core/package-yaml-spec.md)
  */
 
+import type { ContributionKey } from './utils/contribution-table.js';
+
 export type LegacyStrategy = 'link' | 'merge' | 'copy';
 export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
@@ -73,14 +75,13 @@ export interface SyncResult {
 // covers the entitlement-gated registry flow (`hq packages install <slug>`).
 // ---------------------------------------------------------------------------
 
-export type PackContributeKey =
-  | 'workers'
-  | 'knowledge'
-  | 'skills'
-  | 'commands'
-  | 'hooks'
-  | 'policies'
-  | 'scripts';
+/**
+ * The `contributes.*` keys a pack may declare. DERIVED (US-003) from the single
+ * declarative contribution registry in `utils/contribution-table.ts` -- adding
+ * a contribution type is one row there, and this union updates automatically.
+ * Do NOT restate the keys here.
+ */
+export type PackContributeKey = ContributionKey;
 
 /**
  * Pack authorship attribution (US-001). OPTIONAL and backwards-compatible —
@@ -94,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/contribution-table.ts

@@ -0,0 +1,83 @@
+/**
+ * The contribution registry -- the SINGLE declarative source of truth (US-003)
+ * for the `contributes.* -> host` mapping. Every other surface DERIVES from
+ * this table:
+ *
+ *   - `PackContributeKey` (types.ts)              = `keyof typeof CONTRIBUTION_TABLE`
+ *   - `linkFor` / `contributionLinks`             read `payload` + `host`
+ *   - `validateManifest`'s payload check          reads `payload`
+ *   - `core/scripts/scan-packages.sh`             reads a data block GENERATED
+ *                                                 from this table
+ *                                                 (scripts/generate-scan-packages-table.mjs)
+ *
+ * Adding a contribution type is ONE row here, not a five-site edit. The parity
+ * test (`pack-contributions.test.ts`) asserts every surface agrees on the full
+ * key-set, the payload suffix, and the wire mode.
+ *
+ * Row fields:
+ *   - `payload`: path INSIDE the pack, with the literal token `{item}` for the
+ *     declared name. The suffix after `{item}` (e.g. `.md`, `.json`, or none)
+ *     IS the load-bearing per-key shape.
+ *   - `host`: for `wire: 'symlink'`, the host DIRECTORY (relative to the HQ
+ *     root) the symlink is created under -- the symlink dst is
+ *     `<host>/<expanded-item-basename>`. For `wire: 'merge'`, a non-path
+ *     SENTINEL describing the merge target (e.g. `merge:claude+codex`); it is
+ *     NEVER used as a filesystem path.
+ *   - `wire`: `symlink` (a single `ln -s` into `host`) or `merge` (merged into
+ *     a shared host config; see US-004/US-005). Symlink-only readers MUST skip
+ *     `merge` rows.
+ *
+ * NOTE: the `mcp` row is DECLARED here as data only. US-003 does NOT wire any
+ * MCP behavior -- the merge engine lands in US-004/US-005. Declaring it now
+ * makes the table the single source so adding the merge wiring is a code change
+ * against an already-present row, and the parity test guards it from day one.
+ */
+
+export type WireMode = 'symlink' | 'merge';
+
+export interface ContributionRow {
+  /** Path inside the pack, with `{item}` substituted for the declared name. */
+  payload: string;
+  /**
+   * `wire: 'symlink'` -> host directory the symlink lives under (HQ-root
+   * relative). `wire: 'merge'` -> a non-path sentinel for the merge target.
+   */
+  host: string;
+  wire: WireMode;
+}
+
+/**
+ * The 8-key contribution registry. `as const` so `keyof typeof` yields the
+ * exact literal key union consumed by `PackContributeKey`.
+ */
+export const CONTRIBUTION_TABLE = {
+  workers: { payload: 'workers/{item}', host: 'core/workers/public', wire: 'symlink' },
+  knowledge: { payload: 'knowledge/{item}', host: 'core/knowledge/public', wire: 'symlink' },
+  skills: { payload: 'skills/{item}', host: '.claude/skills', wire: 'symlink' },
+  commands: { payload: 'commands/{item}.md', host: '.claude/commands', wire: 'symlink' },
+  hooks: { payload: 'hooks/{item}.sh', host: '.claude/hooks', wire: 'symlink' },
+  policies: { payload: 'policies/{item}.md', host: 'core/policies', wire: 'symlink' },
+  scripts: { payload: 'scripts/{item}', host: 'core/scripts', wire: 'symlink' },
+  // wire:merge -- DECLARED as data (US-003); the merge engine ships in
+  // US-004/US-005. Symlink readers skip this row.
+  mcp: { payload: 'mcp/{item}.json', host: 'merge:claude+codex', wire: 'merge' },
+} as const satisfies Record<string, ContributionRow>;
+
+/** The declared contribution keys, derived once from the table. */
+export type ContributionKey = keyof typeof CONTRIBUTION_TABLE;
+
+/** All contribution keys, in declaration order. */
+export const CONTRIBUTION_KEYS = Object.keys(CONTRIBUTION_TABLE) as ContributionKey[];
+
+/**
+ * Expand a row's `payload` template for a concrete item name. Returns the
+ * pack-relative path of the contribution's payload (e.g. `commands/foo.md`).
+ */
+export function payloadFor(key: ContributionKey, item: string): string {
+  return CONTRIBUTION_TABLE[key].payload.replace('{item}', item);
+}
+
+/** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
+export const SYMLINK_KEYS = CONTRIBUTION_KEYS.filter(
+  (k) => CONTRIBUTION_TABLE[k].wire === 'symlink',
+);