@indigoai-us/hq-cli 5.49.0 → 5.50.1

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="60f911e0-ddd5-5a2d-91c7-18ba47457b57")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="34e9e978-4c0a-5113-82af-9a33e30686c6")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -44,7 +44,9 @@ 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 { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
@@ -158,6 +160,10 @@ registerReindexCommand(program);
 // the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
 // 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({
@@ -176,7 +182,18 @@ registerRescueCommand(program);
         await program.parseAsync();
     }
     catch (err) {
-        Sentry.captureException(err);
+        // A full disk / exhausted quota / read-only filesystem is the user's
+        // machine, not an HQ code defect. Surface a clear, actionable message and
+        // skip Sentry capture so one full disk doesn't flood the tracker with
+        // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+        // to Sentry and still exit 1.
+        const envMsg = environmentalFsErrorMessage(err);
+        if (envMsg) {
+            process.stderr.write(`hq: ${envMsg}\n`);
+        }
+        else {
+            Sentry.captureException(err);
+        }
         process.exitCode = 1;
     }
     finally {
@@ -186,4 +203,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=60f911e0-ddd5-5a2d-91c7-18ba47457b57
+//# debugId=34e9e978-4c0a-5113-82af-9a33e30686c6

package/dist/types.d.ts

@@ -7,6 +7,7 @@
  *                            (new in hq-core v12.0.0; see
  *                            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}`;
@@ -56,7 +57,13 @@ export interface SyncResult {
     message?: string;
     filesChanged?: number;
 }
-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 —
  * packs published before this field still validate. When present, install can

package/dist/utils/contribution-table.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 declare const CONTRIBUTION_TABLE: {
+    readonly workers: {
+        readonly payload: "workers/{item}";
+        readonly host: "core/workers/public";
+        readonly wire: "symlink";
+    };
+    readonly knowledge: {
+        readonly payload: "knowledge/{item}";
+        readonly host: "core/knowledge/public";
+        readonly wire: "symlink";
+    };
+    readonly skills: {
+        readonly payload: "skills/{item}";
+        readonly host: ".claude/skills";
+        readonly wire: "symlink";
+    };
+    readonly commands: {
+        readonly payload: "commands/{item}.md";
+        readonly host: ".claude/commands";
+        readonly wire: "symlink";
+    };
+    readonly hooks: {
+        readonly payload: "hooks/{item}.sh";
+        readonly host: ".claude/hooks";
+        readonly wire: "symlink";
+    };
+    readonly policies: {
+        readonly payload: "policies/{item}.md";
+        readonly host: "core/policies";
+        readonly wire: "symlink";
+    };
+    readonly scripts: {
+        readonly payload: "scripts/{item}";
+        readonly host: "core/scripts";
+        readonly wire: "symlink";
+    };
+    readonly mcp: {
+        readonly payload: "mcp/{item}.json";
+        readonly host: "merge:claude+codex";
+        readonly wire: "merge";
+    };
+};
+/** The declared contribution keys, derived once from the table. */
+export type ContributionKey = keyof typeof CONTRIBUTION_TABLE;
+/** All contribution keys, in declaration order. */
+export declare const CONTRIBUTION_KEYS: 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 declare function payloadFor(key: ContributionKey, item: string): string;
+/** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
+export declare const SYMLINK_KEYS: ("workers" | "knowledge" | "skills" | "commands" | "hooks" | "policies" | "scripts" | "mcp")[];
+//# sourceMappingURL=contribution-table.d.ts.map

package/dist/utils/contribution-table.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+/**
+ * The 8-key contribution registry. `as const` so `keyof typeof` yields the
+ * exact literal key union consumed by `PackContributeKey`.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="154fb78d-60ba-508f-b6e7-6889858f1841")}catch(e){}}();
+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' },
+};
+/** All contribution keys, in declaration order. */
+export const CONTRIBUTION_KEYS = Object.keys(CONTRIBUTION_TABLE);
+/**
+ * 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, item) {
+    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');
+//# sourceMappingURL=contribution-table.js.map
+//# debugId=154fb78d-60ba-508f-b6e7-6889858f1841

package/dist/utils/environmental-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * If `err` is an environmental disk/quota/read-only filesystem error, return a
+ * short, user-facing message explaining it; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — the condition is the user's machine, not a bug HQ can fix. A null
+ * result means "this is a normal error; handle it as usual (capture to Sentry)".
+ */
+export declare function environmentalFsErrorMessage(err: unknown): string | null;
+//# sourceMappingURL=environmental-error.d.ts.map

package/dist/utils/environmental-error.js

@@ -0,0 +1,40 @@
+// src/utils/environmental-error.ts
+//
+// Classify errors that stem from the user's machine/filesystem state rather
+// than an HQ code defect. These are unactionable from our side: a full disk, an
+// exhausted quota, or a read-only filesystem. The CLI surfaces a clear,
+// actionable message and does NOT report them to Sentry — otherwise a single
+// full disk floods the issue tracker with identical, unfixable crash reports.
+//
+// HQ-CLI-2: `hq reindex` hit ENOSPC in the operation-lock temp-file write
+// (`fs.openSync` → "ENOSPC: no space left on device, open") and the raw error
+// propagated uncaught to the CLI's top-level handler, which captured it to
+// Sentry and exited silently — 5 stack-trace crashes in 6 seconds, with no
+// message telling the user their disk was full.
+/**
+ * Node errno codes for "the filesystem cannot accept this write" — purely
+ * environmental, never a code bug. Mapped to the message shown to the user.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="03976a9c-d4c3-57dc-bd1d-40c9d025193d")}catch(e){}}();
+const ENVIRONMENTAL_FS_CODES = {
+    ENOSPC: "No space left on device. Free up disk space and try again.",
+    EDQUOT: "Disk quota exceeded. Free up space (or raise your quota) and try again.",
+    EROFS: "The filesystem is read-only, so HQ can't write here. Check the mount/permissions and try again.",
+};
+/**
+ * If `err` is an environmental disk/quota/read-only filesystem error, return a
+ * short, user-facing message explaining it; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — the condition is the user's machine, not a bug HQ can fix. A null
+ * result means "this is a normal error; handle it as usual (capture to Sentry)".
+ */
+export function environmentalFsErrorMessage(err) {
+    const code = err?.code;
+    if (typeof code !== "string")
+        return null;
+    return ENVIRONMENTAL_FS_CODES[code] ?? null;
+}
+//# sourceMappingURL=environmental-error.js.map
+//# debugId=03976a9c-d4c3-57dc-bd1d-40c9d025193d

package/dist/utils/pack-contributions.d.ts

@@ -1,22 +1,65 @@
 /**
- * Content-pack contribution helpers -- the single source of truth (in TS) for
- * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * Content-pack contribution helpers -- the SINGLE SOURCE OF TRUTH (US-003) for
+ * the `contributes.* -> host` 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:
+ * leaving dangling symlinks.
  *
- *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
- *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ * Historically that mapping was RESTATED in five places (the scan-packages.sh
+ * bash `case`, pack-install.ts:validateManifest's `subpaths` record,
+ * `linkFor`'s switch, `contributionLinks`, and the `PackContributeKey` union),
+ * drift-guarded only by a substring check. US-003 collapses it to ONE
+ * declarative table -- `CONTRIBUTION_TABLE` below -- with a row per key
+ * `{ payload, host, wire }`:
  *
- * 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.
+ *   - `PackContributeKey` is DERIVED from the table keys (see types.ts).
+ *   - `linkFor` / `contributionLinks` / the `subpaths` validator READ the table.
+ *   - `core/scripts/scan-packages.sh` reads a generated data block emitted from
+ *     this same table (regenerate via `scripts/generate-scan-packages-table.mjs`).
+ *
+ * A parity test (`pack-contributions.test.ts`) asserts FULL key-set +
+ * payload-suffix + wire-mode equivalence across every surface, so the copies
+ * cannot drift.
+ *
+ * `wire` discriminates HOW a contribution reaches the host:
+ *   - `symlink`: a single `ln -s` into a well-known host directory (every
+ *     contribution type that shipped before MCP).
+ *   - `merge`: the contribution is MERGED into a shared host config rather than
+ *     symlinked (the `mcp` row -- registered into the Claude + Codex agent
+ *     configs). The merge WIRING is delivered in US-004/US-005; US-003 only
+ *     DECLARES the row as data so the table is the single source and the parity
+ *     test guards the real invariant. `symlink`-only readers (linkFor,
+ *     contributionLinks, the symlink validator, scan-packages) must SKIP
+ *     `merge` rows -- they never produce a symlink.
  */
 import type { PackManifest, PackContributeKey } from '../types.js';
+import { CONTRIBUTION_TABLE, type WireMode } from './contribution-table.js';
+import { type UnregisterServerResult, type SafeWriteEnv, type AcquireLockOptions } from '../commands/mcp-registration.js';
+export { CONTRIBUTION_TABLE };
+export type { WireMode };
+/**
+ * Where a contributes key is ROUTED (US-005). Reads the single-source table's
+ * `wire` field — `'symlink'` keys go through `linkFor`/`contributionLinks` (a
+ * host `ln -s`); `'merge'` keys (e.g. `mcp`) go through the `registerMcpServers`
+ * seam in `commands/mcp-registration.ts` and are NEVER symlinked.
+ *
+ * This is the explicit, code-enforced discriminator behind the invariant that
+ * merge keys never reach the symlink path: callers fan out on the return value
+ * rather than relying on `linkFor` happening to return `null`.
+ */
+export declare function routeContribution(key: PackContributeKey): WireMode;
+/**
+ * The subset of a pack's declared `contributes` keys that are `wire: 'merge'`
+ * (e.g. `mcp`) — the keys that MUST be routed to `registerMcpServers` (US-006)
+ * and MUST NOT be symlinked. Unknown keys and non-array/empty values are
+ * ignored, mirroring `contributionLinks`. Returned in `contributes` iteration
+ * order, de-duplicated.
+ */
+export declare function mergeKeys(contributes: Partial<Record<PackContributeKey, string[]>>): PackContributeKey[];
 /** A single symlink a pack contributes: dst (host path) -> src (inside pack). */
 export interface WiredLink {
     key: PackContributeKey;
@@ -26,8 +69,10 @@ export interface WiredLink {
 }
 export type LinkStatus = 'live' | 'broken' | 'missing' | 'foreign';
 /**
- * Every symlink a pack's `contributes` block declares. Empty subfields and
- * non-array values are ignored, mirroring scan-packages.sh.
+ * Every SYMLINK a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh. `wire: 'merge'`
+ * keys (e.g. `mcp`) produce no symlink and are skipped here -- their host
+ * effect (a config merge) is handled separately (US-004/US-005).
  */
 export declare function contributionLinks(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): WiredLink[];
 /** Classify a host path against the link that should own it. */
@@ -75,6 +120,37 @@ export interface UnwireResult {
  * uninstall from leaving dangling symlinks behind.
  */
 export declare function unwirePack(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): UnwireResult;
+/** The result of {@link unwirePackMcp}: the per-server un-registration outcomes (empty when no `mcp` keys). */
+export interface UnwireMcpResult {
+    /** One {@link UnregisterServerResult} per declared `contributes.mcp` server, in declaration order. */
+    servers: UnregisterServerResult[];
+}
+/** Tuning passthrough for {@link unwirePackMcp} (tests inject a tmpdir `env.home` + tiny lock timeouts). */
+export interface UnwirePackMcpOptions {
+    /** Injectable env — tests MUST pass a tmpdir `home` so the real ~/.claude.json / ~/.codex are untouched. */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning (tests use tiny timeouts). */
+    lock?: AcquireLockOptions;
+    /** Backup timestamp override (deterministic tests). */
+    stamp?: string;
+}
+/**
+ * Un-register the `wire: 'merge'` (MCP) servers a pack declares — the parallel to
+ * {@link unwirePack}'s symlink removal. For each name in `mergeKeys(contributes)` →
+ * `contributes.<mergeKey>` (today only `mcp`), this delegates to
+ * {@link unregisterMcpServers}, which removes ONLY entries stamped with THIS pack's
+ * `_hqPack` provenance and SKIPS-AND-WARNS on a foreign/unstamped same-named entry.
+ *
+ * No-ops cleanly when the pack declares no merge keys (returns `{ servers: [] }`),
+ * when the runtime config is absent (Codex-less host → first-class skip; missing
+ * ~/.claude.json → `absent`), and on a re-run (already-removed → `absent`). It does
+ * NOT throw on a foreign entry — uninstall of one pack must not abort on a server
+ * another pack (or the user) owns.
+ *
+ * @param packName    the pack being uninstalled — the provenance to match
+ * @param contributes the pack's `contributes` block (its `mcp` list drives removal)
+ */
+export declare function unwirePackMcp(packName: string, contributes: Partial<Record<PackContributeKey, string[]>>, options?: UnwirePackMcpOptions): UnwireMcpResult;
 export declare function readHqVersion(hqRoot: string): string | null;
 export interface CatalogEntry {
     source: string;