@shrkcrft/cli 0.1.0-alpha.2

package/dist/surface/spine-extractor.js

@@ -0,0 +1,100 @@
+/**
+ * IDs of pipelines treated as the "spine" — pipelines whose
+ * referenced commands are tier=Core regardless of any other catalog
+ * derivation rule.
+ *
+ * Today only `engine.feature-dev` exists in the engine repo.
+ * `engine.safe-generation` is a planned second spine pipeline; if a
+ * project ships it, it's automatically picked up here.
+ */
+export const SPINE_PIPELINE_IDS = Object.freeze([
+    'engine.feature-dev',
+    'engine.safe-generation',
+]);
+/**
+ * Verbs the spine derivation is allowed to promote to core. The
+ * spine pipelines reference write verbs (`apply`, `gen`, `plan
+ * review`) too, but those are power-user surfaces; letting them
+ * drift into core inflates the "brutally small" promise. Anything
+ * outside this allowlist stays tier=extended even when the spine
+ * references it.
+ */
+const CORE_SPINE_VERB_ALLOWLIST = new Set([
+    'context',
+    'check boundaries',
+]);
+/**
+ * Extract the catalog command names referenced from spine
+ * pipelines AND in the core verb allowlist. The function does NOT
+ * execute any pipeline — it walks `steps[].cliCommands[]` and parses
+ * out the verb path.
+ *
+ * Parsing rule: each `cliCommands` entry is a shell-style string like
+ * `bun run shrk plan review /tmp/plan.json`. The parser strips a
+ * leading `bun run shrk` or `shrk` and returns the first 1-2 tokens
+ * as a command path. Multi-token paths are joined with a space so
+ * they match {@link ICommandCatalogEntry.command} entries that already
+ * use this form (`pack author status`, `plan review`).
+ */
+export function extractSpineCommands(pipelines) {
+    const out = new Set();
+    const spineIds = new Set(SPINE_PIPELINE_IDS);
+    for (const pipeline of pipelines) {
+        if (!spineIds.has(pipeline.id))
+            continue;
+        for (const step of pipeline.steps ?? []) {
+            for (const raw of step.cliCommands ?? []) {
+                const verb = parseCommandVerb(raw);
+                if (verb && CORE_SPINE_VERB_ALLOWLIST.has(verb))
+                    out.add(verb);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Parse a single CLI command string into its catalog `command`
+ * path. Returns `undefined` if the string doesn't reference shrk.
+ *
+ * Examples:
+ *   `bun run shrk doctor`                      → `doctor`
+ *   `bun run shrk plan review /tmp/plan.json`  → `plan review`
+ *   `bun run shrk pack author status`          → `pack author status`
+ *   `bun run shrk context --task "<task>"`     → `context`
+ *   `bun x tsc`                                → undefined
+ */
+export function parseCommandVerb(raw) {
+    let tokens = raw.trim().split(/\s+/);
+    if (tokens.length === 0)
+        return undefined;
+    // Drop leading `bun run` / `npx` / `pnpm exec` wrappers.
+    const wrappers = new Set(['bun', 'npx', 'pnpm', 'yarn']);
+    if (wrappers.has(tokens[0])) {
+        tokens = tokens.slice(1);
+        if (tokens[0] === 'run' || tokens[0] === 'exec' || tokens[0] === 'x') {
+            tokens = tokens.slice(1);
+        }
+    }
+    // Drop the `shrk` binary name.
+    if (tokens[0] !== 'shrk')
+        return undefined;
+    tokens = tokens.slice(1);
+    // Stop at the first flag, placeholder (`<...>`), path-looking arg
+    // (`/tmp/...`, `./...`), or quoted-string arg. Placeholders +
+    // positional args inflate the verb path so we exclude them.
+    const verbTokens = [];
+    for (const t of tokens) {
+        if (t.startsWith('-'))
+            break;
+        if (t.startsWith('<') || t.endsWith('>'))
+            break;
+        if (t.startsWith('/') || t.startsWith('./') || t.startsWith('../'))
+            break;
+        if (t.startsWith('"') || t.startsWith("'"))
+            break;
+        verbTokens.push(t);
+    }
+    if (verbTokens.length === 0)
+        return undefined;
+    return verbTokens.join(' ');
+}

package/dist/surface/surface-config-writer.d.ts

@@ -0,0 +1,59 @@
+import type { ISurfaceConfig } from '@shrkcrft/config';
+export interface ISurfaceConfigEdit {
+    /** What changed. */
+    field: 'enabled' | 'hidden';
+    /** Command name that was added/removed. */
+    command: string;
+    /** Operation. */
+    operation: 'add' | 'remove';
+}
+export interface ISurfaceConfigDiff {
+    configFile: string;
+    before: ISurfaceConfig;
+    after: ISurfaceConfig;
+    edits: readonly ISurfaceConfigEdit[];
+    /** Suggested next-command if the user wants to apply. */
+    nextCommand: string;
+}
+export interface ISurfaceConfigWriteResult {
+    configFile: string;
+    edits: readonly ISurfaceConfigEdit[];
+    /** Whether the file existed before the write. */
+    fileExisted: boolean;
+}
+/**
+ * Mutate the `surface.enabled[]` array in
+ * `sharkcraft.config.ts`. Preview-first: the caller computes the diff
+ * via {@link planSurfaceEdit} and only applies it via
+ * {@link applySurfaceEdit} when `--write` is passed.
+ */
+export declare function planSurfaceEdit(configFile: string, before: ISurfaceConfig | undefined, edits: readonly ISurfaceConfigEdit[]): ISurfaceConfigDiff;
+/**
+ * Apply a previously-planned surface edit to the config file.
+ *
+ * Strategy:
+ *   1. Read the config file as text.
+ *   2. If a `surface:` block exists, replace it.
+ *   3. Otherwise, append it before the final `})` / `});` of the
+ *      default-exported config object.
+ *
+ * The mutator is intentionally text-based (not AST). The config shape
+ * is small and the surface block is well-defined; an AST pass would
+ * add complexity for no extra correctness. Unit tests lock the behavior.
+ */
+export declare function applySurfaceEdit(diff: ISurfaceConfigDiff): ISurfaceConfigWriteResult;
+/**
+ * Render the surface block as a TS object literal.
+ */
+export declare function renderSurfaceBlock(surface: ISurfaceConfig, indent?: string): string;
+/**
+ * Compute the new file body given the desired surface block.
+ *
+ * If the file already has a `surface: { ... }` block, replace it.
+ * Otherwise, insert before the closing `})` / `});` of the config
+ * literal.
+ */
+export declare function applySurfaceTextEdit(original: string, surface: ISurfaceConfig): string;
+/** Default config file path for a project. */
+export declare function defaultConfigFile(sharkcraftDir: string): string;
+//# sourceMappingURL=surface-config-writer.d.ts.map

package/dist/surface/surface-config-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-config-writer.d.ts","sourceRoot":"","sources":["../../src/surface/surface-config-writer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,SAAS,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrC,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrC,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GACnC,kBAAkB,CA0BpB;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,kBAAkB,GACvB,yBAAyB,CAe3B;AAmBD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,SAAO,GAAG,MAAM,CAsBjF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAgBtF;AAED,8CAA8C;AAC9C,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/surface/surface-config-writer.js

@@ -0,0 +1,135 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+/**
+ * Mutate the `surface.enabled[]` array in
+ * `sharkcraft.config.ts`. Preview-first: the caller computes the diff
+ * via {@link planSurfaceEdit} and only applies it via
+ * {@link applySurfaceEdit} when `--write` is passed.
+ */
+export function planSurfaceEdit(configFile, before, edits) {
+    const beforeNormalised = {
+        enabled: [...(before?.enabled ?? [])],
+        hidden: [...(before?.hidden ?? [])],
+    };
+    const afterEnabled = new Set(beforeNormalised.enabled ?? []);
+    const afterHidden = new Set(beforeNormalised.hidden ?? []);
+    for (const edit of edits) {
+        const target = edit.field === 'enabled' ? afterEnabled : afterHidden;
+        if (edit.operation === 'add')
+            target.add(edit.command);
+        else
+            target.delete(edit.command);
+    }
+    const after = {
+        enabled: [...afterEnabled].sort(),
+        hidden: [...afterHidden].sort(),
+    };
+    return {
+        configFile,
+        before: beforeNormalised,
+        after,
+        edits,
+        nextCommand: edits.length > 0 ? edits.map((e) => describeEdit(e)).join(', ') : '(no-op)',
+    };
+}
+function describeEdit(edit) {
+    const verb = edit.operation === 'add' ? '+' : '-';
+    return `${verb} surface.${edit.field}: ${edit.command}`;
+}
+/**
+ * Apply a previously-planned surface edit to the config file.
+ *
+ * Strategy:
+ *   1. Read the config file as text.
+ *   2. If a `surface:` block exists, replace it.
+ *   3. Otherwise, append it before the final `})` / `});` of the
+ *      default-exported config object.
+ *
+ * The mutator is intentionally text-based (not AST). The config shape
+ * is small and the surface block is well-defined; an AST pass would
+ * add complexity for no extra correctness. Unit tests lock the behavior.
+ */
+export function applySurfaceEdit(diff) {
+    if (diff.edits.length === 0) {
+        return { configFile: diff.configFile, edits: [], fileExisted: true };
+    }
+    const fileExisted = fileExists(diff.configFile);
+    const original = fileExisted ? readFileSync(diff.configFile, 'utf8') : DEFAULT_CONFIG_BODY;
+    const updated = applySurfaceTextEdit(original, diff.after);
+    writeFileSync(diff.configFile, updated, 'utf8');
+    return {
+        configFile: diff.configFile,
+        edits: diff.edits,
+        fileExisted,
+    };
+}
+function fileExists(p) {
+    try {
+        readFileSync(p, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const DEFAULT_CONFIG_BODY = `import { defineSharkCraftConfig } from '@shrkcrft/config';
+
+export default defineSharkCraftConfig({
+});
+`;
+const SURFACE_BLOCK_REGEX = /(^\s*surface\s*:\s*\{[\s\S]*?\}\s*,?\s*\n)/m;
+/**
+ * Render the surface block as a TS object literal.
+ */
+export function renderSurfaceBlock(surface, indent = '  ') {
+    const lines = [];
+    lines.push(`${indent}surface: {`);
+    if (surface.profile) {
+        lines.push(`${indent}  profile: ${JSON.stringify(surface.profile)},`);
+    }
+    if (surface.enabled && surface.enabled.length > 0) {
+        lines.push(`${indent}  enabled: [`);
+        for (const name of surface.enabled)
+            lines.push(`${indent}    ${JSON.stringify(name)},`);
+        lines.push(`${indent}  ],`);
+    }
+    else {
+        lines.push(`${indent}  enabled: [],`);
+    }
+    if (surface.hidden && surface.hidden.length > 0) {
+        lines.push(`${indent}  hidden: [`);
+        for (const name of surface.hidden)
+            lines.push(`${indent}    ${JSON.stringify(name)},`);
+        lines.push(`${indent}  ],`);
+    }
+    else {
+        lines.push(`${indent}  hidden: [],`);
+    }
+    lines.push(`${indent}},`);
+    return lines.join('\n') + '\n';
+}
+/**
+ * Compute the new file body given the desired surface block.
+ *
+ * If the file already has a `surface: { ... }` block, replace it.
+ * Otherwise, insert before the closing `})` / `});` of the config
+ * literal.
+ */
+export function applySurfaceTextEdit(original, surface) {
+    const block = renderSurfaceBlock(surface);
+    if (SURFACE_BLOCK_REGEX.test(original)) {
+        return original.replace(SURFACE_BLOCK_REGEX, block);
+    }
+    // Insert before the closing `})` / `});` of the config object.
+    // Prefer the last `})` so nested objects don't trip us up.
+    const closeRegex = /(\n)(\}\)\s*;?\s*)$/m;
+    if (closeRegex.test(original)) {
+        return original.replace(closeRegex, `\n${block}$2`);
+    }
+    // Fallback: append at end with a defineSharkCraftConfig wrapper.
+    return `${original}\n${DEFAULT_CONFIG_BODY.replace('})', `${block}})`)}`;
+}
+/** Default config file path for a project. */
+export function defaultConfigFile(sharkcraftDir) {
+    return nodePath.join(sharkcraftDir, 'sharkcraft.config.ts');
+}

package/dist/surface/surface-summary.d.ts

@@ -0,0 +1,66 @@
+import { CommandTier, type ICommandCatalogEntry } from '../commands/command-catalog.js';
+import { TierSource, type ITierResolution, type ITierResolverContext } from './tier.js';
+export declare const SURFACE_SUMMARY_SCHEMA = "sharkcraft.surface.v1";
+/** Per-command snapshot used in {@link ISurfaceSummary}. */
+export interface ISurfaceCommandView {
+    command: string;
+    tier: CommandTier;
+    source: TierSource;
+    detail?: string;
+    /** Whether the command is callable in this project's surface configuration. */
+    callable: boolean;
+    /** Whether the command shows in default `--help` output. */
+    visibleInHelp: boolean;
+    /** True if `surface.hidden[]` contains the command. */
+    hidden: boolean;
+    /** True if `surface.enabled[]` contains the command. */
+    enabled: boolean;
+    /** Pack contribution source, if any. */
+    pack?: string;
+}
+export interface ISurfaceTotals {
+    core: number;
+    extended: number;
+    experimental: number;
+    /** Sum of (core + extended visibleInHelp). */
+    visible: number;
+    /** Sum of all callable commands (core + extended). */
+    callable: number;
+}
+export interface ISurfaceSummary {
+    schema: typeof SURFACE_SUMMARY_SCHEMA;
+    tiers: {
+        core: readonly ISurfaceCommandView[];
+        extended: readonly ISurfaceCommandView[];
+        experimental: readonly ISurfaceCommandView[];
+    };
+    totals: ISurfaceTotals;
+    /**
+     * Warnings — e.g. a `surface.enabled` entry that doesn't match any
+     * catalog command, or an attempt to hide a core command.
+     */
+    warnings: readonly ISurfaceWarning[];
+    /** Stable hash of (catalog + context). Used in test snapshots. */
+    hash: string;
+}
+export interface ISurfaceWarning {
+    command: string;
+    code: 'unknown-command' | 'cannot-hide-core' | 'cannot-disable-core' | 'enable-noop' | 'tier-override-conflict';
+    message: string;
+}
+/**
+ * Build the canonical surface summary used by `shrk surface list`
+ * (text + JSON), the `--about` landing, the help renderer's hidden-set,
+ * and the MCP gating layer.
+ *
+ * Implementation note: deterministic. Same context + catalog → same
+ * summary, byte-for-byte. The `hash` field is the SHA-256 prefix of
+ * the canonical JSON form (sans the hash itself) — useful for cache
+ * keys and snapshot tests.
+ */
+export declare function buildSurfaceSummary(context: ITierResolverContext): ISurfaceSummary;
+/** Look up a single command's tier resolution from a summary. */
+export declare function findCommandInSummary(summary: ISurfaceSummary, command: string): ISurfaceCommandView | undefined;
+/** Resolve a single tier given a context (no summary needed). */
+export declare function resolveTierForCommand(entry: ICommandCatalogEntry, context: ITierResolverContext): ITierResolution;
+//# sourceMappingURL=surface-summary.d.ts.map

package/dist/surface/surface-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-summary.d.ts","sourceRoot":"","sources":["../../src/surface/surface-summary.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EAGX,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAKL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,KAAK,EAAE;QACL,IAAI,EAAE,SAAS,mBAAmB,EAAE,CAAC;QACrC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;QACzC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;KAC9C,CAAC;IACF,MAAM,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,qBAAqB,GAAG,aAAa,GAAG,wBAAwB,CAAC;IAChH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAoFjB;AAkFD,iEAAiE;AACjE,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,GACd,mBAAmB,GAAG,SAAS,CAMjC;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAEjB"}

package/dist/surface/surface-summary.js

@@ -0,0 +1,162 @@
+import { createHash } from 'node:crypto';
+import { CommandTier, COMMAND_CATALOG, defaultShowInHelp, } from "../commands/command-catalog.js";
+import { BOOTSTRAP_COMMANDS, isCallable, isVisibleInDefaultHelp, resolveTier, TierSource, } from "./tier.js";
+export const SURFACE_SUMMARY_SCHEMA = 'sharkcraft.surface.v1';
+/**
+ * Build the canonical surface summary used by `shrk surface list`
+ * (text + JSON), the `--about` landing, the help renderer's hidden-set,
+ * and the MCP gating layer.
+ *
+ * Implementation note: deterministic. Same context + catalog → same
+ * summary, byte-for-byte. The `hash` field is the SHA-256 prefix of
+ * the canonical JSON form (sans the hash itself) — useful for cache
+ * keys and snapshot tests.
+ */
+export function buildSurfaceSummary(context) {
+    const core = [];
+    const extended = [];
+    const experimental = [];
+    const warnings = [];
+    const hiddenSet = new Set(context.surfaceConfig?.hidden ?? []);
+    const enabledSet = new Set(context.surfaceConfig?.enabled ?? []);
+    const knownCommands = new Set();
+    for (const entry of COMMAND_CATALOG) {
+        knownCommands.add(entry.command);
+        const view = makeCommandView(entry, context, hiddenSet, enabledSet, warnings);
+        pushIntoBucket(view, core, extended, experimental);
+    }
+    // Surface bootstrap meta-flags (e.g. `--about`) that aren't
+    // ordinary catalog entries. They sit in core for visibility but have
+    // no catalog row.
+    for (const bootstrap of BOOTSTRAP_COMMANDS) {
+        if (knownCommands.has(bootstrap))
+            continue;
+        core.push({
+            command: bootstrap,
+            tier: CommandTier.Core,
+            source: TierSource.Bootstrap,
+            detail: 'bootstrap meta-flag',
+            callable: true,
+            visibleInHelp: true,
+            hidden: false,
+            enabled: false,
+        });
+    }
+    // Sort each bucket alphabetically for stable output.
+    const sortByName = (a, b) => a.command.localeCompare(b.command);
+    core.sort(sortByName);
+    extended.sort(sortByName);
+    experimental.sort(sortByName);
+    // Audit warnings for config keys that don't correspond to anything.
+    for (const name of enabledSet) {
+        if (!knownCommands.has(name) && !BOOTSTRAP_COMMANDS.includes(name)) {
+            warnings.push({
+                command: name,
+                code: 'unknown-command',
+                message: `surface.enabled[] references unknown command: ${name}`,
+            });
+        }
+    }
+    for (const name of hiddenSet) {
+        if (!knownCommands.has(name) && !BOOTSTRAP_COMMANDS.includes(name)) {
+            warnings.push({
+                command: name,
+                code: 'unknown-command',
+                message: `surface.hidden[] references unknown command: ${name}`,
+            });
+        }
+    }
+    const totals = {
+        core: core.length,
+        extended: extended.length,
+        experimental: experimental.length,
+        visible: core.length + extended.filter((c) => c.visibleInHelp).length,
+        callable: core.length +
+            extended.length +
+            experimental.filter((c) => c.callable).length,
+    };
+    const summaryWithoutHash = {
+        schema: SURFACE_SUMMARY_SCHEMA,
+        tiers: { core, extended, experimental },
+        totals,
+        warnings,
+    };
+    const hash = createHash('sha256')
+        .update(JSON.stringify(summaryWithoutHash))
+        .digest('hex')
+        .slice(0, 16);
+    return { ...summaryWithoutHash, hash };
+}
+function makeCommandView(entry, context, hiddenSet, enabledSet, warnings) {
+    const resolution = resolveTier(entry, context);
+    const isHidden = hiddenSet.has(entry.command);
+    const isEnabled = enabledSet.has(entry.command);
+    // Cross-check the config against the derived tier.
+    if (resolution.tier === CommandTier.Core) {
+        if (isHidden) {
+            warnings.push({
+                command: entry.command,
+                code: 'cannot-hide-core',
+                message: `Cannot hide core command: ${entry.command}. Remove from surface.hidden.`,
+            });
+        }
+        if (isEnabled) {
+            // Enabling a core command is harmless but pointless.
+            warnings.push({
+                command: entry.command,
+                code: 'enable-noop',
+                message: `Enabling a core command is a no-op: ${entry.command}`,
+            });
+        }
+    }
+    // Cross-check explicit override against the resolver. If the catalog
+    // says Experimental but the resolver promoted to Core (spine /
+    // bootstrap), surface a warning so the override is corrected.
+    if (entry.tier !== undefined &&
+        entry.tier !== resolution.tier &&
+        resolution.source !== TierSource.Override) {
+        warnings.push({
+            command: entry.command,
+            code: 'tier-override-conflict',
+            message: `Catalog declares tier=${entry.tier} but mechanical derivation resolved to ${resolution.tier} (${resolution.source}). Remove the override.`,
+        });
+    }
+    const view = {
+        command: entry.command,
+        tier: resolution.tier,
+        source: resolution.source,
+        callable: isCallable(resolution),
+        visibleInHelp: isVisibleInDefaultHelp(resolution, isHidden) && defaultShowInHelp(entry),
+        hidden: isHidden,
+        enabled: isEnabled,
+    };
+    if (resolution.detail)
+        view.detail = resolution.detail;
+    const pack = context.packContributions.get(entry.command);
+    if (pack)
+        view.pack = pack;
+    return view;
+}
+function pushIntoBucket(view, core, extended, experimental) {
+    switch (view.tier) {
+        case CommandTier.Core:
+            core.push(view);
+            break;
+        case CommandTier.Extended:
+            extended.push(view);
+            break;
+        case CommandTier.Experimental:
+            experimental.push(view);
+            break;
+    }
+}
+/** Look up a single command's tier resolution from a summary. */
+export function findCommandInSummary(summary, command) {
+    return (summary.tiers.core.find((c) => c.command === command) ??
+        summary.tiers.extended.find((c) => c.command === command) ??
+        summary.tiers.experimental.find((c) => c.command === command));
+}
+/** Resolve a single tier given a context (no summary needed). */
+export function resolveTierForCommand(entry, context) {
+    return resolveTier(entry, context);
+}

package/dist/surface/tier.d.ts

@@ -0,0 +1,100 @@
+import type { ISurfaceConfig } from '@shrkcrft/config';
+import { CommandTier, type ICommandCatalogEntry } from '../commands/command-catalog.js';
+/**
+ * Bootstrap commands. Always tier=Core regardless of any other
+ * derivation rule. Listed here (and only here) so the rule is mechanical:
+ * a fresh repo with NO `sharkcraft.config.ts` can always reach these.
+ *
+ * Tokens are catalog `command` strings (the same form as
+ * {@link ICommandCatalogEntry.command}). Multi-token entries (e.g.
+ * `pack author status`) are matched exactly.
+ *
+ * Brutally small set. Discovery verbs (`commands`, `start-here`) live
+ * in extended tier; users find them via `shrk surface list` or `shrk
+ * recommend`.
+ */
+export declare const BOOTSTRAP_COMMANDS: readonly string[];
+/**
+ * Source explanations for tier classification. Returned by the
+ * resolver so `shrk surface explain <name>` can describe why a
+ * command's tier is what it is.
+ */
+export declare enum TierSource {
+    Bootstrap = "bootstrap",
+    Spine = "spine",
+    PackContribution = "pack-contribution",
+    Override = "override",
+    Hidden = "hidden-flag",
+    Default = "default"
+}
+export interface ITierResolution {
+    /** Resolved tier (post-derivation, post-config). */
+    tier: CommandTier;
+    /** Why the tier resolved that way. */
+    source: TierSource;
+    /** Human-readable detail (e.g. "in engine.feature-dev spine pipeline"). */
+    detail?: string;
+    /** True if the user's surface config flipped the default. */
+    configApplied?: boolean;
+}
+export interface ITierResolverContext {
+    /** Catalog command names ({@link ICommandCatalogEntry.command}) referenced by spine pipelines. */
+    spineCommands: ReadonlySet<string>;
+    /** Catalog command names contributed by loaded packs (pack-contributed commands). */
+    packContributions: ReadonlyMap<string, string>;
+    /** User's `sharkcraft.config.ts surface{}` block (may be undefined for a fresh repo). */
+    surfaceConfig: ISurfaceConfig | undefined;
+}
+/**
+ * Mechanically derive a command's tier.
+ *
+ * Resolution order (HIGHEST wins, never demotes Core):
+ *
+ *   1. Bootstrap set → Core.
+ *   2. Spine pipeline reference → Core.
+ *   3. Pack contribution → Experimental (unless in surface.enabled).
+ *   4. Explicit catalog `tier` override → that value (cannot demote Core).
+ *   5. Catalog overlay `hidden` verdict → Experimental.
+ *   6. Otherwise → Extended.
+ *
+ * After derivation, the user's `surface.enabled` / `surface.hidden`
+ * config can flip a single dimension:
+ *
+ *   - `surface.enabled` contains the command → promote Experimental
+ *     to Extended (callable, visible in `surface list` only — `--help`
+ *     visibility is governed by the catalog's own defaultShowInHelp).
+ *   - `surface.hidden` contains the command AND tier is Extended →
+ *     remains Extended-tier but hidden from `--help`. The visibility
+ *     flip is read by the help renderer, not by the tier resolver
+ *     directly.
+ *
+ * Core commands cannot be hidden or disabled. Attempts to do so are
+ * surfaced as warnings by `shrk doctor` and `shrk surface list --json`.
+ */
+export declare function resolveTier(entry: ICommandCatalogEntry, context: ITierResolverContext): ITierResolution;
+/**
+ * Is the command callable from the CLI / MCP in the current
+ * surface configuration?
+ *
+ *   - Core: always callable.
+ *   - Extended: always callable.
+ *   - Experimental: callable only if in `surface.enabled`.
+ *
+ * The resolver's promotion of Experimental → Extended already accounts
+ * for `enabled[]`, so this is a simple tier check.
+ */
+export declare function isCallable(resolution: ITierResolution): boolean;
+/**
+ * Should the command be visible in `--help` output?
+ *
+ *   - Core: always visible.
+ *   - Extended: visible unless in `surface.hidden` (the help renderer
+ *     checks the config and consults `defaultShowInHelp(entry)`).
+ *   - Experimental: never visible in `--help`; only in `surface list`.
+ *
+ * The caller still consults `defaultShowInHelp(entry)` for the
+ * underlying surface/lifecycle gating; this function answers "does
+ * the tier permit visibility at all?".
+ */
+export declare function isVisibleInDefaultHelp(resolution: ITierResolution, hiddenByConfig: boolean): boolean;
+//# sourceMappingURL=tier.d.ts.map

package/dist/surface/tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier.d.ts","sourceRoot":"","sources":["../../src/surface/tier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,WAAW,EACX,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAW9C,CAAC;AAEH;;;;GAIG;AACH,oBAAY,UAAU;IACpB,SAAS,cAAc;IACvB,KAAK,UAAU;IACf,gBAAgB,sBAAsB;IACtC,QAAQ,aAAa;IACrB,MAAM,gBAAgB;IACtB,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,sCAAsC;IACtC,MAAM,EAAE,UAAU,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,qFAAqF;IACrF,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,yFAAyF;IACzF,aAAa,EAAE,cAAc,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CA4EjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAK/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAC3B,cAAc,EAAE,OAAO,GACtB,OAAO,CAKT"}