@shrkcrft/cli 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/surface/command-index.d.ts

@@ -0,0 +1,77 @@
+import { type ICommandCatalogEntry } from '../commands/command-catalog.js';
+import type { CommandRegistry } from '../command-registry.js';
+import type { ICommandIndexEntry } from './command-index-entry.js';
+import type { ICommandIndex } from './i-command-index.js';
+/**
+ * THE command index — the one answer to "does this command / subverb / meta
+ * flag exist, what does it do, who is it for".
+ *
+ * Before round 11 there were three disagreeing inventories: the dispatch trie
+ * (326 handler paths), COMMAND_CATALOG (442 rows, 55 of them flag variants of
+ * another row) and help's own catalog walk. `surface list` enumerated the
+ * catalog, so 75 registered verbs were absent from "the callable-command
+ * inventory", and a command-string check against it would have deleted correct
+ * commands. The index is built from the registry (what actually dispatches)
+ * and JOINED with the catalog (what documents it):
+ *
+ *   (a) every `registry.listAll()` path                  → `Trie`
+ *   (b) every subverb a handler declares (`subverbs`)    → `Subverb` (declared)
+ *   (c) every catalog path dispatched internally by a
+ *       real handler (`check wiring`, `graph status`)    → `Subverb`
+ *   (d) catalog-documented command groups (`paths`)      → `Trie`
+ *   (e) the bootstrap meta flags                         → `Meta`
+ *
+ * Catalog rows that only add flags or placeholders fold into `variants`.
+ * `surface list`, `help`, `commands doctor`, the surface gate and the
+ * command-string resolver all read this — never COMMAND_CATALOG directly.
+ */
+/** Meta flags `runCliInner` handles before dispatch. Always callable. */
+export declare const META_COMMANDS: readonly {
+    path: string;
+    description: string;
+    usage: string;
+}[];
+/** A token that can be a command-path segment (not a flag, placeholder, quote or path). */
+export declare function isCommandWord(token: string): boolean;
+/**
+ * The command path a catalog `command` string documents: its leading run of
+ * command words, stopping at the first flag, placeholder, quoted argument or
+ * path (`impact graph <impact.json>` → `impact graph`,
+ * `architecture violations --changed-only` → `architecture violations`).
+ */
+export declare function cleanCommandPath(command: string): string;
+/**
+ * Build the command index. With a registry it is the dispatch table joined
+ * with the catalog; without one it degrades to the catalog, relabelled
+ * (`registryBacked: false`, every entry `Catalog`) rather than passed off as
+ * the dispatch table.
+ *
+ * `catalog` defaults to COMMAND_CATALOG; a test passes its own rows to prove a
+ * join (an undeclared internal subverb) against a registry of its own.
+ */
+export declare function buildCommandIndex(registry?: CommandRegistry, catalog?: readonly ICommandCatalogEntry[]): ICommandIndex;
+/** The entry at `path`, or the entry a folded variant / alias spelling belongs to. */
+export declare function findCommandIndexEntry(index: ICommandIndex, command: string): ICommandIndexEntry | undefined;
+/**
+ * The known subverb names directly below `path`: the next token of every index
+ * entry under it, at any depth (`ci scaffold gitlab` makes `scaffold` a known
+ * subverb of `ci` even though `ci scaffold` has no row of its own). Sorted,
+ * distinct.
+ */
+export declare function subverbNamesOf(index: ICommandIndex, path: string): string[];
+/**
+ * The index of `registry` (over COMMAND_CATALOG), built once per registry and
+ * shared — the dispatcher guard, the help intercept, `help` and the active
+ * index all read the same object.
+ */
+export declare function commandIndexFor(registry: CommandRegistry): ICommandIndex;
+/** Called by `runCliInner` with the registry it dispatches from. */
+export declare function setActiveCommandRegistry(registry: CommandRegistry | undefined): void;
+/**
+ * The index of the registry this CLI run dispatches from, or `undefined`
+ * outside `runCli` (a direct engine call) — callers then degrade loudly
+ * (`buildCommandIndex()` relabelled as the catalog, or no command resolver →
+ * NOT VERIFIED), never to a silent guess.
+ */
+export declare function getActiveCommandIndex(): ICommandIndex | undefined;
+//# sourceMappingURL=command-index.d.ts.map

package/dist/surface/command-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-index.d.ts","sourceRoot":"","sources":["../../src/surface/command-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAI/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,yEAAyE;AACzE,eAAO,MAAM,aAAa,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAsBrF,CAAC;AAIL,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxD;AA0FD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,CAAC,EAAE,eAAe,EAC1B,OAAO,GAAE,SAAS,oBAAoB,EAAoB,GACzD,aAAa,CA8Hf;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,SAAS,CAOhC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAW3E;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa,CAOxE;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,GAAG,SAAS,CAEjE"}

package/dist/surface/command-index.js

@@ -0,0 +1,323 @@
+import { COMMAND_CATALOG, CommandAudience, commandAudience, } from "../commands/command-catalog.js";
+import { CommandDispatchKind } from "./command-dispatch-kind.js";
+/**
+ * THE command index — the one answer to "does this command / subverb / meta
+ * flag exist, what does it do, who is it for".
+ *
+ * Before round 11 there were three disagreeing inventories: the dispatch trie
+ * (326 handler paths), COMMAND_CATALOG (442 rows, 55 of them flag variants of
+ * another row) and help's own catalog walk. `surface list` enumerated the
+ * catalog, so 75 registered verbs were absent from "the callable-command
+ * inventory", and a command-string check against it would have deleted correct
+ * commands. The index is built from the registry (what actually dispatches)
+ * and JOINED with the catalog (what documents it):
+ *
+ *   (a) every `registry.listAll()` path                  → `Trie`
+ *   (b) every subverb a handler declares (`subverbs`)    → `Subverb` (declared)
+ *   (c) every catalog path dispatched internally by a
+ *       real handler (`check wiring`, `graph status`)    → `Subverb`
+ *   (d) catalog-documented command groups (`paths`)      → `Trie`
+ *   (e) the bootstrap meta flags                         → `Meta`
+ *
+ * Catalog rows that only add flags or placeholders fold into `variants`.
+ * `surface list`, `help`, `commands doctor`, the surface gate and the
+ * command-string resolver all read this — never COMMAND_CATALOG directly.
+ */
+/** Meta flags `runCliInner` handles before dispatch. Always callable. */
+export const META_COMMANDS = Object.freeze([
+    {
+        path: '--about',
+        description: 'What shrk is and is not — the in-binary philosophy summary.',
+        usage: 'shrk --about',
+    },
+    {
+        path: '--full-help',
+        description: 'Long help: every visible command (add --all for the whole catalog).',
+        usage: 'shrk --full-help [--all]',
+    },
+    {
+        path: '--help',
+        description: 'The short start screen (same as `shrk help`).',
+        usage: 'shrk --help',
+    },
+    {
+        path: '--version',
+        description: 'Print the installed shrk version.',
+        usage: 'shrk --version',
+    },
+]);
+const COMMAND_WORD = /^[a-z0-9][a-z0-9-]*$/i;
+/** A token that can be a command-path segment (not a flag, placeholder, quote or path). */
+export function isCommandWord(token) {
+    return COMMAND_WORD.test(token);
+}
+/**
+ * The command path a catalog `command` string documents: its leading run of
+ * command words, stopping at the first flag, placeholder, quoted argument or
+ * path (`impact graph <impact.json>` → `impact graph`,
+ * `architecture violations --changed-only` → `architecture violations`).
+ */
+export function cleanCommandPath(command) {
+    const out = [];
+    for (const token of command.trim().split(/\s+/)) {
+        if (!isCommandWord(token))
+            break;
+        out.push(token);
+    }
+    return out.join(' ');
+}
+function groupCatalogRows(catalog) {
+    const byPath = new Map();
+    for (const row of catalog) {
+        const path = cleanCommandPath(row.command);
+        if (path.length === 0)
+            continue;
+        const list = byPath.get(path) ?? [];
+        list.push(row);
+        byPath.set(path, list);
+    }
+    return byPath;
+}
+function sortedUnique(values) {
+    return [...new Set(values.filter((v) => v.length > 0))].sort();
+}
+function makeEntry(input) {
+    const rows = input.rows ?? [];
+    const base = rows.find((r) => r.command.trim() === input.path) ?? rows[0];
+    const variants = sortedUnique(rows.map((r) => r.command.trim()).filter((c) => c !== input.path));
+    const description = base?.description ?? input.subverb?.description ?? input.handler?.description ?? '';
+    const usage = input.subverb?.usage ?? input.handler?.usage;
+    const aliasParent = input.aliasParent ?? input.parent;
+    const subverbAliases = (input.subverb?.aliases ?? []).map((a) => aliasParent ? `${aliasParent} ${a}` : a);
+    const aliases = sortedUnique([
+        ...(base?.aliases ?? []),
+        ...(input.aliases ?? []),
+        ...subverbAliases,
+    ]);
+    const positionals = input.subverb?.positionals ?? input.handler?.positionals;
+    return {
+        path: input.path,
+        tokens: input.path.split(' '),
+        dispatch: input.dispatch,
+        description,
+        ...(usage ? { usage } : {}),
+        catalogued: rows.length > 0,
+        ...(base ? { catalogEntry: base } : {}),
+        variants,
+        aliases,
+        audience: base ? commandAudience(base) : [CommandAudience.Human],
+        ...(input.parent !== undefined ? { parent: input.parent } : {}),
+        ...(input.declared !== undefined ? { declared: input.declared } : {}),
+        ...(positionals !== undefined ? { positionals } : {}),
+    };
+}
+/** Top-level alias spellings of `path` (`playbook list` for `playbooks list`). */
+function aliasSpellings(path, topAliases) {
+    const head = path[0];
+    if (head === undefined)
+        return [];
+    return (topAliases.get(head) ?? []).map((alias) => [alias, ...path.slice(1)].join(' '));
+}
+function collectTopAliases(registry) {
+    const out = new Map();
+    const add = (alias, canonical) => {
+        const list = out.get(canonical) ?? [];
+        if (!list.includes(alias))
+            list.push(alias);
+        out.set(canonical, list);
+    };
+    for (const [alias, canonical] of registry.listGroupAliases())
+        add(alias, canonical);
+    for (const [alias, canonical] of registry.listCommandAliases())
+        add(alias, canonical);
+    return out;
+}
+/**
+ * Build the command index. With a registry it is the dispatch table joined
+ * with the catalog; without one it degrades to the catalog, relabelled
+ * (`registryBacked: false`, every entry `Catalog`) rather than passed off as
+ * the dispatch table.
+ *
+ * `catalog` defaults to COMMAND_CATALOG; a test passes its own rows to prove a
+ * join (an undeclared internal subverb) against a registry of its own.
+ */
+export function buildCommandIndex(registry, catalog = COMMAND_CATALOG) {
+    const rowsByPath = groupCatalogRows(catalog);
+    const entries = new Map();
+    if (registry) {
+        const topAliases = collectTopAliases(registry);
+        const all = registry.listAll();
+        // (a) every registered handler path.
+        for (const { path, handler } of all) {
+            const p = path.join(' ');
+            entries.set(p, makeEntry({
+                path: p,
+                dispatch: CommandDispatchKind.Trie,
+                rows: rowsByPath.get(p),
+                handler,
+                aliases: aliasSpellings(path, topAliases),
+            }));
+        }
+        // (b) subverbs a handler declares — nested ones too (`search tuning list`).
+        // A real trie child of the same name wins. `parent` stays the handler that
+        // dispatches the whole chain; aliases are spelled under the direct parent.
+        const addDeclared = (handlerPath, parentPath, specs) => {
+            for (const subverb of specs) {
+                const tokens = [...parentPath, subverb.name];
+                const p = tokens.join(' ');
+                if (!entries.has(p)) {
+                    entries.set(p, makeEntry({
+                        path: p,
+                        dispatch: CommandDispatchKind.Subverb,
+                        rows: rowsByPath.get(p),
+                        subverb,
+                        parent: handlerPath.join(' '),
+                        aliasParent: parentPath.join(' '),
+                        declared: true,
+                        aliases: aliasSpellings(tokens, topAliases),
+                    }));
+                }
+                if (subverb.subverbs)
+                    addDeclared(handlerPath, tokens, subverb.subverbs);
+            }
+        };
+        for (const { path, handler } of all) {
+            addDeclared(path, path, handler.subverbs ?? []);
+        }
+        // (c)/(d) catalog paths the trie does not list verbatim.
+        for (const [p, rows] of rowsByPath) {
+            if (entries.has(p))
+                continue;
+            const res = registry.resolve(p.split(' '));
+            if (res.matchedPath.length === 0)
+                continue; // nothing dispatches it — `commands doctor` reports the row
+            const canonical = [...res.matchedPath, ...res.rest].join(' ');
+            const existing = entries.get(canonical);
+            if (existing) {
+                // An alias spelling of a path already indexed (`playbook list`).
+                entries.set(canonical, {
+                    ...existing,
+                    catalogued: true,
+                    ...(existing.catalogEntry ? {} : rows[0] ? { catalogEntry: rows[0] } : {}),
+                    variants: sortedUnique([...existing.variants, ...rows.map((r) => r.command.trim())]),
+                    aliases: sortedUnique([...existing.aliases, p]),
+                });
+                continue;
+            }
+            if (res.rest.length === 0) {
+                // (d) A documented command group with no handler of its own.
+                if (res.node.children.size > 0) {
+                    entries.set(canonical, makeEntry({ path: canonical, dispatch: CommandDispatchKind.Trie, rows }));
+                }
+                continue;
+            }
+            // (c) Dispatched internally by the deepest matched handler. A pure group
+            // node cannot dispatch a positional, so its "subverb" is not real.
+            if (!res.handler)
+                continue;
+            entries.set(canonical, makeEntry({
+                path: canonical,
+                dispatch: CommandDispatchKind.Subverb,
+                rows,
+                parent: res.matchedPath.join(' '),
+                declared: false,
+            }));
+        }
+    }
+    else {
+        for (const [p, rows] of rowsByPath) {
+            entries.set(p, makeEntry({ path: p, dispatch: CommandDispatchKind.Catalog, rows }));
+        }
+    }
+    // (e) bootstrap meta flags.
+    for (const meta of META_COMMANDS) {
+        if (entries.has(meta.path))
+            continue;
+        const rows = rowsByPath.get(meta.path);
+        entries.set(meta.path, {
+            path: meta.path,
+            tokens: [meta.path],
+            dispatch: CommandDispatchKind.Meta,
+            description: rows?.[0]?.description ?? meta.description,
+            usage: meta.usage,
+            catalogued: (rows?.length ?? 0) > 0,
+            ...(rows?.[0] ? { catalogEntry: rows[0] } : {}),
+            variants: [],
+            aliases: [],
+            audience: [CommandAudience.Human, CommandAudience.Agent],
+        });
+    }
+    const sorted = [...entries.values()].sort((a, b) => a.path.localeCompare(b.path));
+    return {
+        entries: sorted,
+        byPath: new Map(sorted.map((e) => [e.path, e])),
+        registryBacked: registry !== undefined,
+        ...(registry ? { registry } : {}),
+    };
+}
+/** The entry at `path`, or the entry a folded variant / alias spelling belongs to. */
+export function findCommandIndexEntry(index, command) {
+    const exact = index.byPath.get(command.trim());
+    if (exact)
+        return exact;
+    const clean = cleanCommandPath(command);
+    const byClean = index.byPath.get(clean);
+    if (byClean)
+        return byClean;
+    return index.entries.find((e) => e.aliases.includes(clean) || e.variants.includes(command.trim()));
+}
+/**
+ * The known subverb names directly below `path`: the next token of every index
+ * entry under it, at any depth (`ci scaffold gitlab` makes `scaffold` a known
+ * subverb of `ci` even though `ci scaffold` has no row of its own). Sorted,
+ * distinct.
+ */
+export function subverbNamesOf(index, path) {
+    const depth = path.length === 0 ? 0 : path.split(' ').length;
+    const prefix = path.length === 0 ? '' : `${path} `;
+    const out = new Set();
+    for (const e of index.entries) {
+        if (e.tokens.length <= depth)
+            continue;
+        if (prefix.length > 0 && !e.path.startsWith(prefix))
+            continue;
+        const name = e.tokens[depth];
+        if (name !== undefined && !name.startsWith('-'))
+            out.add(name);
+    }
+    return [...out].sort();
+}
+// ── The active index ──────────────────────────────────────────────────────
+//
+// `runCliInner` registers the registry it dispatches from, once per run, so a
+// command (or a warm site feeding the inspector's command resolver) reads the
+// SAME index without importing main.ts — which imports every command and would
+// be circular. Built lazily: most runs never ask.
+let activeRegistry;
+const INDEX_BY_REGISTRY = new WeakMap();
+/**
+ * The index of `registry` (over COMMAND_CATALOG), built once per registry and
+ * shared — the dispatcher guard, the help intercept, `help` and the active
+ * index all read the same object.
+ */
+export function commandIndexFor(registry) {
+    let index = INDEX_BY_REGISTRY.get(registry);
+    if (!index) {
+        index = buildCommandIndex(registry);
+        INDEX_BY_REGISTRY.set(registry, index);
+    }
+    return index;
+}
+/** Called by `runCliInner` with the registry it dispatches from. */
+export function setActiveCommandRegistry(registry) {
+    activeRegistry = registry;
+}
+/**
+ * The index of the registry this CLI run dispatches from, or `undefined`
+ * outside `runCli` (a direct engine call) — callers then degrade loudly
+ * (`buildCommandIndex()` relabelled as the catalog, or no command resolver →
+ * NOT VERIFIED), never to a silent guess.
+ */
+export function getActiveCommandIndex() {
+    return activeRegistry ? commandIndexFor(activeRegistry) : undefined;
+}

package/dist/surface/i-command-index.d.ts

@@ -0,0 +1,22 @@
+import type { CommandRegistry } from '../command-registry.js';
+import type { ICommandIndexEntry } from './command-index-entry.js';
+/**
+ * The complete dispatchable command inventory: every registered handler path,
+ * every declared or catalog-documented subverb, and the bootstrap meta flags —
+ * joined with the catalog by clean path.
+ */
+export interface ICommandIndex {
+    /** Sorted by path. */
+    readonly entries: readonly ICommandIndexEntry[];
+    readonly byPath: ReadonlyMap<string, ICommandIndexEntry>;
+    /**
+     * True when built from a command registry. False only for the registry-less
+     * fallback (a direct engine call outside `runCli`), which lists catalog rows
+     * whose dispatch is unproven — relabelled `catalog`, never passed off as the
+     * dispatch table.
+     */
+    readonly registryBacked: boolean;
+    /** The registry the index was built from, for alias-aware trie descent. */
+    readonly registry?: CommandRegistry;
+}
+//# sourceMappingURL=i-command-index.d.ts.map

package/dist/surface/i-command-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-command-index.d.ts","sourceRoot":"","sources":["../../src/surface/i-command-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;CACrC"}

package/dist/surface/i-command-index.js

@@ -0,0 +1 @@
+export {};

package/dist/surface/i-command-string-context.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What `resolveCommandString` checks NON-shrk commands against.
+ *
+ * Each field is optional: an absent set means "cannot check that family", and
+ * the resolver reports those strings `NotShrk` (skipped, counted) instead of
+ * inventing an answer.
+ */
+export interface ICommandStringContext {
+    /** Root `package.json` script names, for `<pm> run <script>`. */
+    readonly scripts?: ReadonlySet<string>;
+    /** Registered MCP tool names, for bare tool ids (`get_task_packet`). */
+    readonly mcpToolNames?: ReadonlySet<string>;
+    /**
+     * The project root a path-mode argument is looked up under — the
+     * dispatcher's cwd. Absent → no argument names a file (a disk-free reading):
+     * a verb-shaped token under a path-mode command is then a verb it lacks.
+     */
+    readonly root?: string;
+}
+//# sourceMappingURL=i-command-string-context.d.ts.map

package/dist/surface/i-command-string-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-command-string-context.d.ts","sourceRoot":"","sources":["../../src/surface/i-command-string-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/surface/i-command-string-context.js

@@ -0,0 +1 @@
+export {};

package/dist/surface/i-surface-denial.d.ts

@@ -0,0 +1,13 @@
+import type { SurfaceLayer } from './surface-layer.js';
+/**
+ * Why a command is denied by `surface.disabled`: the selector that named it
+ * and the layer that declared that selector. Carried on the tier resolution
+ * and the surface view so the refusal text and `surface explain` name the
+ * remedy that actually works (`surface allow` for a config deny, `surface
+ * enable` over a profile deny).
+ */
+export interface ISurfaceDenial {
+    readonly selector: string;
+    readonly origin: SurfaceLayer;
+}
+//# sourceMappingURL=i-surface-denial.d.ts.map

package/dist/surface/i-surface-denial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-surface-denial.d.ts","sourceRoot":"","sources":["../../src/surface/i-surface-denial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B"}

package/dist/surface/i-surface-denial.js

@@ -0,0 +1 @@
+export {};

package/dist/surface/load-surface-context.d.ts

@@ -1,4 +1,5 @@
 import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { ISurfaceConfig } from '@shrkcrft/config';
 import { type ISurfaceProfile } from './profiles.js';
 import type { ITierResolverContext } from './tier.js';
 export interface LoadSurfaceContextOptions {
@@ -28,7 +29,22 @@ export interface ILoadedSurfaceContext {
  *      engine repo — `ICommandPlugin` exists in the plugin-api but no
  *      pack contributes commands today; future packs will populate
  *      the inspection's pack discovery).
- *   4. Read the user's `surface{}` config block.
+ *   4. Read the user's `surface{}` config block and compose it with the
+ *      active profile ({@link composeSurfaceConfig}).
+ *   5. Detect the host (`detectSharkcraftRepo`, the one authority): outside
+ *      SharkCraft's own repository, tool-maintenance commands are gated.
+ *
+ * The CLI surface gate, the MCP gate, `surface list/explain` and `--help` all
+ * read this ONE context, so they cannot disagree about what is visible or
+ * callable here.
  */
 export declare function loadSurfaceContext(options: LoadSurfaceContextOptions): Promise<ILoadedSurfaceContext>;
+/**
+ * Compose the project's `surface{}` block with the active profile — the one
+ * merge. Each list is the union of the profile's and the config's entries;
+ * `explicitSurface` keeps the config's OWN `enabled` / `disabled` whenever a
+ * profile is active, because the deny rule needs the layer ("an explicit
+ * config `enabled` overrides a profile's deny, never a config deny").
+ */
+export declare function composeSurfaceConfig(rawConfig: ISurfaceConfig | undefined, activeProfile: ISurfaceProfile | undefined): Pick<ITierResolverContext, 'surfaceConfig' | 'explicitSurface'>;
 //# sourceMappingURL=load-surface-context.d.ts.map

package/dist/surface/load-surface-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-surface-context.d.ts","sourceRoot":"","sources":["../../src/surface/load-surface-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAGpF,OAAO,EAAgC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEtD,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,UAAU,EAAE,qBAAqB,CAAC;IAClC;;;;OAIG;IACH,iBAAiB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,0EAA0E;IAC1E,aAAa,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,qBAAqB,CAAC,CAmChC"}
+{"version":3,"file":"load-surface-context.d.ts","sourceRoot":"","sources":["../../src/surface/load-surface-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAgC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEtD,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,UAAU,EAAE,qBAAqB,CAAC;IAClC;;;;OAIG;IACH,iBAAiB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,0EAA0E;IAC1E,aAAa,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,qBAAqB,CAAC,CA+BhC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,cAAc,GAAG,SAAS,EACrC,aAAa,EAAE,eAAe,GAAG,SAAS,GACzC,IAAI,CAAC,oBAAoB,EAAE,eAAe,GAAG,iBAAiB,CAAC,CAsBjE"}

package/dist/surface/load-surface-context.js

@@ -1,4 +1,4 @@
-import { inspectSharkcraft } from '@shrkcrft/inspector';
+import { detectSharkcraftRepo, inspectSharkcraft, } from '@shrkcrft/inspector';
 import { extractSpineCommands } from "./spine-extractor.js";
 import { BUILTIN_PROFILES, getProfile } from "./profiles.js";
 /**
@@ -11,7 +11,14 @@ import { BUILTIN_PROFILES, getProfile } from "./profiles.js";
  *      engine repo — `ICommandPlugin` exists in the plugin-api but no
  *      pack contributes commands today; future packs will populate
  *      the inspection's pack discovery).
- *   4. Read the user's `surface{}` config block.
+ *   4. Read the user's `surface{}` config block and compose it with the
+ *      active profile ({@link composeSurfaceConfig}).
+ *   5. Detect the host (`detectSharkcraftRepo`, the one authority): outside
+ *      SharkCraft's own repository, tool-maintenance commands are gated.
+ *
+ * The CLI surface gate, the MCP gate, `surface list/explain` and `--help` all
+ * read this ONE context, so they cannot disagree about what is visible or
+ * callable here.
  */
 export async function loadSurfaceContext(options) {
     const inspection = options.inspection ?? (await inspectSharkcraft({ cwd: options.cwd }));
@@ -24,22 +31,49 @@ export async function loadSurfaceContext(options) {
     const activeProfile = profileId
         ? getProfile(profileId, packProfiles)
         : undefined;
-    // Compose profile.hidden + config.hidden / profile.enabled + config.enabled.
-    // Config wins on conflicts (explicit user choice over profile default).
+    const composed = composeSurfaceConfig(rawConfig, activeProfile);
+    const isToolRepo = detectSharkcraftRepo(inspection.projectRoot ?? options.cwd);
+    return {
+        inspection,
+        context: {
+            spineCommands,
+            packContributions,
+            surfaceConfig: composed.surfaceConfig,
+            isToolRepo,
+            ...(composed.explicitSurface ? { explicitSurface: composed.explicitSurface } : {}),
+        },
+        availableProfiles: [...BUILTIN_PROFILES, ...packProfiles],
+        ...(activeProfile ? { activeProfile } : {}),
+    };
+}
+/**
+ * Compose the project's `surface{}` block with the active profile — the one
+ * merge. Each list is the union of the profile's and the config's entries;
+ * `explicitSurface` keeps the config's OWN `enabled` / `disabled` whenever a
+ * profile is active, because the deny rule needs the layer ("an explicit
+ * config `enabled` overrides a profile's deny, never a config deny").
+ */
+export function composeSurfaceConfig(rawConfig, activeProfile) {
+    const profileId = rawConfig?.profile;
     const mergedHidden = mergeUnique(activeProfile?.hidden, rawConfig?.hidden);
     const mergedEnabled = mergeUnique(activeProfile?.enabled, rawConfig?.enabled);
+    const mergedDisabled = mergeUnique(activeProfile?.disabled, rawConfig?.disabled);
     const surfaceConfig = rawConfig || activeProfile
         ? {
             ...(profileId ? { profile: profileId } : {}),
             ...(mergedHidden.length > 0 ? { hidden: mergedHidden } : {}),
             ...(mergedEnabled.length > 0 ? { enabled: mergedEnabled } : {}),
+            ...(mergedDisabled.length > 0 ? { disabled: mergedDisabled } : {}),
         }
         : undefined;
+    if (!activeProfile)
+        return { surfaceConfig };
     return {
-        inspection,
-        context: { spineCommands, packContributions, surfaceConfig },
-        availableProfiles: [...BUILTIN_PROFILES, ...packProfiles],
-        ...(activeProfile ? { activeProfile } : {}),
+        surfaceConfig,
+        explicitSurface: {
+            enabled: [...(rawConfig?.enabled ?? [])],
+            disabled: [...(rawConfig?.disabled ?? [])],
+        },
     };
 }
 function mergeUnique(a, b) {
@@ -65,13 +99,17 @@ function collectPackProfiles(inspection) {
                 description: typeof r.description === 'string' ? r.description : `Pack profile (${pack.packageName})`,
                 source: 'pack',
                 pack: pack.packageName,
-                ...(Array.isArray(r.hidden) ? { hidden: r.hidden.filter((s) => typeof s === 'string') } : {}),
-                ...(Array.isArray(r.enabled) ? { enabled: r.enabled.filter((s) => typeof s === 'string') } : {}),
+                ...(Array.isArray(r.hidden) ? { hidden: stringsOf(r.hidden) } : {}),
+                ...(Array.isArray(r.enabled) ? { enabled: stringsOf(r.enabled) } : {}),
+                ...(Array.isArray(r.disabled) ? { disabled: stringsOf(r.disabled) } : {}),
             });
         }
     }
     return out;
 }
+function stringsOf(values) {
+    return values.filter((s) => typeof s === 'string');
+}
 /**
  * Collect pack-contributed CLI command names. Today the pack
  * manifest schema has no `commandFiles[]` contribution slot, so this