@shrkcrft/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/commands/command-catalog.js

@@ -390,6 +390,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'check orphans',
+        description: 'Write-safety guard: after deleting file(s)/export(s), finds surviving files that still import them or reference a symbol they declared — alias-resolved, incl. barrel re-exports the type checker misses. Reverse-closure over the diff vs --since (or --staged) against the code-graph snapshot; each survivor reported with file:line. [--since <ref>] [--staged] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
     entry({
         command: 'policy-lint',
         description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against config-defined policyRules[] — sees `.html` files AND inline `template:` strings that tsc/AOT cannot. Deterministic; no AI. [--surface template|style|ts] [--changed-only] [--only <ids>] [--json]',
@@ -398,6 +406,46 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'wiring explain',
+        description: 'Dry-run ONE configured wiringRule and print the declared set + registered set it extracts (token + file:line), the alias-resolved set-difference, and the verdict — the author-loop view of what `check wiring` sees, without re-running the gate. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'wiring test',
+        description: 'Dry-run an EPHEMERAL candidate wiring rule (a .json file or inline JSON) against the live tree — see the declared/registered sets + diff it would produce before committing it to sharkcraft.config.ts. Never writes config. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'wiring chain',
+        description: 'Registration/DI graph query: the declared → provided → consumed chain of a token across files/layers, alias-resolved, with file:line at each hop + a verdict (wired / unprovided / orphan). Models runtime wiring imports can\'t see. Idioms from sharkcraft.config.ts registrationGraph[]. [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'wiring unprovided',
+        description: 'Registration/DI graph query: tokens DECLARED or INJECTED but never PROVIDED — the silent-at-runtime class (typecheck/AOT-green, resolves to undefined at runtime). The write-safety check imports/grep structurally can\'t do. [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'wiring orphans',
+        description: 'Registration/DI graph query: tokens PROVIDED/registered that nothing CONSUMES — a build-clean dead registration (or a sign the consumer was renamed/removed). [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
     entry({
         command: 'reuse',
         description: 'Intent → the canonical primitive to reuse: matches your intent against config reusePrimitives[] then resolves the symbol through the code graph (transitive star-barrels) to its import path, sibling exports, and real consumer files to copy. Read-only; no AI.',
@@ -415,6 +463,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'finish',
+        description: 'Composite "is this changeset safe to finish?" gate: EXECUTES boundaries + import-hygiene + wiring + policy + deleted-orphans changed-only inline, plus an impact summary, and returns ONE pass/fail. The trustworthy "done?" call after editing — superset of diff-check; honors 0-rules→skipped. Read-only. [files… | --staged | --since <ref>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
     entry({
         command: 'review',
         description: 'PR-review packet — changed files, affected rules, missing tests heuristic.',
@@ -1658,6 +1714,14 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
     }),
+    entry({
+        command: 'trace literal',
+        description: 'Trace an EXACT string literal across the codebase, classified by direction: declare → register → consume sites of a cross-fence contract (kind slug, permission id, route key) the type system can\'t link and grep can\'t classify. Resolves `const X = "lit"` aliases. Generalizes `registry … where` to any literal — no pre-declared registry. [--glob <g>] [--no-aliases] [--limit N] [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
     entry({
         command: 'feedback',
         description: 'Feedback ingestion (ingest|summarize|actions|convert-to-backlog). Read-only.',
@@ -3206,6 +3270,206 @@ export const COMMAND_CATALOG = Object.freeze([
         intendedAudience: [CommandAudience.Human, CommandAudience.Maintainer],
         taskRole: CommandTaskRole.Inspect,
     }),
+    // ── D3-2: registered command groups that resolved live but had ZERO
+    // catalog entries, so `shrk commands doctor` was blind to them and
+    // `shrk help <group>` had no metadata. One canonical row per registered
+    // sub-verb. Everything is ReadOnly except `checks run --execute`
+    // (RunsShell) and `audit project-coupling` (RunsShell, advanced).
+    // `mcpAvailable` mirrors a real read-only MCP tool where one exists.
+    //
+    // paths — path-convention registry
+    // (MCP: list_path_conventions / get_path_convention / search_path_conventions).
+    entry({
+        command: 'paths list',
+        description: 'List path conventions.',
+        category: 'paths',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'paths get',
+        description: 'Get one path convention by id.',
+        category: 'paths',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'paths search',
+        description: 'Search path conventions by scope / query.',
+        category: 'paths',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Search,
+    }),
+    entry({
+        command: 'paths best',
+        description: 'Pick the best path convention for a task.',
+        category: 'paths',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    // pipelines — pipeline registry
+    // (MCP: list_pipelines / get_pipeline / get_pipeline_context / create_pipeline_plan).
+    entry({
+        command: 'pipelines list',
+        description: 'List available pipelines.',
+        category: 'pipelines',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'pipelines get',
+        description: 'Show one pipeline by id.',
+        category: 'pipelines',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'pipelines context',
+        description: 'Token-budgeted context for a pipeline + task.',
+        category: 'pipelines',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Context,
+    }),
+    entry({
+        command: 'pipelines plan',
+        description: 'Render a pipeline as an ordered step plan for a task.',
+        category: 'pipelines',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Context,
+    }),
+    entry({
+        command: 'pipelines script',
+        description: 'Render a pipeline as a runnable bash-style preview script (no execution).',
+        category: 'pipelines',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Context,
+    }),
+    entry({
+        command: 'pipelines next',
+        description: 'Show the next recommended step in a pipeline for a task.',
+        category: 'pipelines',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'pipelines vars',
+        description: 'List the variables a pipeline consumes.',
+        category: 'pipelines',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    // checks — custom-check registry declared by rules (metadata.checks[]).
+    entry({
+        command: 'checks list',
+        description: 'List custom checks declared by rules (metadata.checks[]). Read-only.',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'checks doctor',
+        description: 'Validate custom-check descriptors (missing fields, duplicate ids).',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Diagnose,
+    }),
+    entry({
+        command: 'checks run',
+        description: 'Preview a custom check. Read-only by default — pass --execute to run it.',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'checks run --execute',
+        description: 'Actually invoke the custom check command (runs the configured shell command).',
+        category: 'checks',
+        safetyLevel: SafetyLevel.RunsShell,
+        runsShell: true,
+        requiresReview: true,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'checks parse-report',
+        description: 'Parse a check report file into the canonical finding shape. Read-only.',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'checks import',
+        description: 'Import an external tool report into the universal check-result protocol. Read-only.',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'checks aggregate',
+        description: 'Aggregate multiple check reports into one verdict. Read-only.',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'checks report',
+        description: 'Render aggregated check results in the chosen format. Read-only.',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'checks convert',
+        description: 'Convert a check report between supported formats. Read-only.',
+        category: 'checks',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    // audit — project-specific coupling audit (MCP: get_project_coupling_report).
+    // RunsShell/advanced per the brief: the report/plan modes materialise
+    // artifacts and the audit is a heavyweight, opt-in surface.
+    entry({
+        command: 'audit project-coupling',
+        description: 'Audit / plan / report project-specific coupling. Pass --token to scan for identifiers; the engine ships zero built-in tokens.',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.RunsShell,
+        runsShell: true,
+        mcpAvailable: true,
+        surface: CommandSurface.Advanced,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent],
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    // ownership — CODEOWNERS / sharkcraft ownership registry
+    // (MCP: get_ownership / match_owners).
+    entry({
+        command: 'ownership list',
+        description: 'List ownership rules from CODEOWNERS / sharkcraft/ownership.ts.',
+        category: 'ownership',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'ownership for',
+        description: 'Show the ownership match for a single file.',
+        category: 'ownership',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'ownership affected',
+        description: 'Show owners affected by --since <ref>, --bundle <id>, or --files a,b.',
+        category: 'ownership',
+        safetyLevel: SafetyLevel.ReadOnly,
+        taskRole: CommandTaskRole.Inspect,
+    }),
 ]);
 /** Return every canonical command string in the catalog. */
 export function listCatalogCommandStrings() {
@@ -3464,6 +3728,7 @@ const PRIMARY_VERBS_ALLOWLIST = new Set([
     'gen',
     'apply',
     'check',
+    'finish',
     'quality',
     'plan',
     'fix',
@@ -3534,6 +3799,32 @@ export function defaultShowInHelp(e) {
     const surface = commandSurface(e);
     return surface === CommandSurface.Primary || surface === CommandSurface.Common;
 }
+/**
+ * The "explain / dry-run" command family: entries that show you what a gate,
+ * ranker, or graph *sees* before you act (`search tuning explain`, `wiring
+ * explain`/`wiring test`, `boundaries explain`, `surface explain`, …). Several
+ * carry an Advanced surface, so {@link defaultShowInHelp} hides them despite
+ * being high-value — which is exactly why an agent finds them only by guessing.
+ * `shrk --full-help` lists this family in a dedicated section so they stop
+ * being hidden. Returns callable entries only (retired/deprecated/alias and
+ * R46-pruned are excluded), sorted by command.
+ */
+export function listExplainFamily() {
+    return COMMAND_CATALOG.filter((e) => {
+        const lc = commandLifecycle(e);
+        if (lc === CommandLifecycle.Deprecated ||
+            lc === CommandLifecycle.Retired ||
+            lc === CommandLifecycle.Alias) {
+            return false;
+        }
+        if (R46_OVERLAY[e.command])
+            return false;
+        const role = commandTaskRole(e);
+        return role === CommandTaskRole.Explain || /(^|\s)explain$/.test(e.command);
+    })
+        .slice()
+        .sort((a, b) => a.command.localeCompare(b.command));
+}
 /**
  * Short "Use this when…" line derived from `surface`, `taskRole`,
  * `preferredCommand`, `replacedBy`, and `machineOnly`. Empty string when

package/dist/commands/commands.command.d.ts

@@ -1,5 +1,20 @@
 import { type CommandRegistry, type ICommandHandler } from '../command-registry.js';
+import { type ISurfaceProfile } from '../surface/profiles.js';
+import { type ICommandCatalogEntry } from './command-catalog.js';
 export declare function makeCommandsCommand(registry: CommandRegistry): ICommandHandler;
+export interface ICommandsProfileView {
+    profile: ISurfaceProfile;
+    entries: readonly ICommandCatalogEntry[];
+    hidden: readonly string[];
+    catalogTotal: number;
+}
+/**
+ * Pure: render the catalog as a surface profile sees it. Every command the
+ * profile lists in `hidden` is filtered out of `entries` (commands stay
+ * callable — this is a listing filter, not a disable). Returns undefined when
+ * the profile id is unknown. Exported for tests.
+ */
+export declare function buildCommandsProfileView(profileId: string, packProfiles?: readonly ISurfaceProfile[]): ICommandsProfileView | undefined;
 export interface IRetirementPlanGroup {
     reason: 'deprecated' | 'aliases' | 'machine-in-help' | 'overlapping' | 'missing-replacedBy' | 'legacy-no-removeAfter';
     entries: readonly {

package/dist/commands/commands.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.command.d.ts","sourceRoot":"","sources":["../../src/commands/commands.command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.command.d.ts","sourceRoot":"","sources":["../../src/commands/commands.command.ts"],"names":[],"mappings":"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"}

package/dist/commands/commands.command.js

@@ -1,12 +1,13 @@
-import { flagBool, flagString } from "../command-registry.js";
+import { flagBool, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { BUILTIN_PROFILES, getProfile } from "../surface/profiles.js";
 import { buildCommandSafetyMatrix, COMMAND_CATALOG, CommandLifecycle, commandLifecycle, CommandSurface, commandSurface, commandTaskRole, defaultShowInHelp, R46_OVERLAY, renderCommandSafetyMatrixMarkdown, SafetyLevel } from "./command-catalog.js";
 import { buildCommandTaxonomy, buildPrimaryCommandsReport, renderCommandTaxonomyMarkdown, renderCommandTaxonomyText, renderPrimaryCommandsText } from '@shrkcrft/inspector';
 export function makeCommandsCommand(registry) {
     return {
         name: 'commands',
-        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | machine | legacy | overlaps | taxonomy | matrix | tree | search | suggest | explain | entrypoints | doctor | ux-check.',
-        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|suggest <p>|explain <cmd>|entrypoints|doctor|ux-check] [--all] [--safety <level>] [--category <name>] [--json]',
+        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog, or --profile <id> (e.g. agent) for the surface a profile sees. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | profile | machine | legacy | overlaps | taxonomy | matrix | tree | search | suggest | explain | entrypoints | doctor | ux-check.',
+        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|profile [<id>]|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|suggest <p>|explain <cmd>|entrypoints|doctor|ux-check] [--all] [--profile <id>] [--safety <level>] [--category <name>] [--json]',
         async run(args) {
             const sub = args.positional[0];
             if (sub === 'doctor') {
@@ -95,6 +96,12 @@ export function makeCommandsCommand(registry) {
             if (sub === 'surface') {
                 return runCommandsSurface(args);
             }
+            // `shrk commands profile [<id>]` — list surface profiles, or render the
+            // catalog as one profile sees it (the curated view, e.g. `agent`).
+            if (sub === 'profile') {
+                const id = args.positional[1];
+                return id ? runCommandsProfile(args, id) : runCommandsProfileList(args);
+            }
             if (sub === 'machine') {
                 return runCommandsMachine(args);
             }
@@ -120,8 +127,34 @@ export function makeCommandsCommand(registry) {
             if (sub === 'docs-check') {
                 return runCommandsDocsCheck(args);
             }
+            // `--profile <id>` renders the catalog curated for a surface profile
+            // (e.g. `--profile agent` hides CI/release/pack-maintenance machinery an
+            // inline agent doesn't need). Commands stay callable; this is a listing
+            // filter, not a disable.
+            const profileFilter = flagString(args, 'profile');
+            if (profileFilter) {
+                return runCommandsProfile(args, profileFilter);
+            }
             const safetyFilter = flagString(args, 'safety');
             const categoryFilter = flagString(args, 'category');
+            // Validate the filter values against real allowlists — a typo (e.g.
+            // `--safety read` or `--category typo`) previously matched nothing and
+            // returned "commands (0)" with exit 0, which reads like an empty result
+            // rather than a mistake. Reject with the valid set + exit 2 instead.
+            if (safetyFilter !== undefined) {
+                const validSafety = new Set(Object.values(SafetyLevel));
+                if (!validSafety.has(safetyFilter)) {
+                    process.stderr.write(`Unknown --safety "${safetyFilter}". Valid: ${[...validSafety].sort().join(', ')}\n`);
+                    return 2;
+                }
+            }
+            if (categoryFilter !== undefined) {
+                const validCategories = new Set(COMMAND_CATALOG.map((e) => e.category));
+                if (!validCategories.has(categoryFilter)) {
+                    process.stderr.write(`Unknown --category "${categoryFilter}". Valid: ${[...validCategories].sort().join(', ')}\n`);
+                    return 2;
+                }
+            }
             const wantsAll = flagBool(args, 'all');
             let entries = COMMAND_CATALOG;
             if (safetyFilter) {
@@ -186,6 +219,97 @@ function runCommandsSurface(args) {
     }
     return 0;
 }
+/**
+ * Pure: render the catalog as a surface profile sees it. Every command the
+ * profile lists in `hidden` is filtered out of `entries` (commands stay
+ * callable — this is a listing filter, not a disable). Returns undefined when
+ * the profile id is unknown. Exported for tests.
+ */
+export function buildCommandsProfileView(profileId, packProfiles = []) {
+    const profile = getProfile(profileId, packProfiles);
+    if (!profile)
+        return undefined;
+    const hidden = new Set(profile.hidden ?? []);
+    const entries = COMMAND_CATALOG.filter((e) => !hidden.has(e.command));
+    return { profile, entries, hidden: [...hidden].sort(), catalogTotal: COMMAND_CATALOG.length };
+}
+/**
+ * `shrk commands --profile <id>` / `shrk commands profile <id>` renders the
+ * catalog curated for a surface profile (e.g. `agent` hides
+ * CI/release/pack-maintenance machinery an inline agent doesn't need) without
+ * editing `sharkcraft.config.ts`. Builtin profiles resolve instantly; an
+ * unknown id falls back to discovering pack-contributed profiles via the
+ * surface context (best-effort — needs a workspace).
+ */
+async function runCommandsProfile(args, profileId) {
+    let view = buildCommandsProfileView(profileId);
+    let validIds = BUILTIN_PROFILES.map((p) => p.id);
+    if (!view) {
+        try {
+            const { loadSurfaceContext } = await import("../surface/load-surface-context.js");
+            const ctx = await loadSurfaceContext({ cwd: resolveCwd(args) });
+            validIds = ctx.availableProfiles.map((p) => p.id);
+            view = buildCommandsProfileView(profileId, ctx.availableProfiles);
+        }
+        catch {
+            // Pack discovery failed (e.g. outside a project) — builtin-only.
+        }
+    }
+    if (!view) {
+        process.stderr.write(`Unknown profile "${profileId}". Valid: ${[...validIds].sort().join(', ')}\n`);
+        return 2;
+    }
+    const { profile, entries, hidden, catalogTotal } = view;
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({
+            profile: profile.id,
+            description: profile.description,
+            source: profile.source,
+            total: entries.length,
+            catalogTotal,
+            hiddenCount: hidden.length,
+            hidden,
+            entries,
+        }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Commands — profile=${profile.id} (${entries.length} of ${catalogTotal} visible)`));
+    process.stdout.write(`  ${profile.description}\n`);
+    if (hidden.length > 0) {
+        process.stdout.write(`  (${hidden.length} command(s) hidden by this profile — still callable)\n`);
+    }
+    const grouped = new Map();
+    for (const e of entries) {
+        const arr = grouped.get(e.category) ?? [];
+        arr.push(e);
+        grouped.set(e.category, arr);
+    }
+    for (const [cat, items] of [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        process.stdout.write(`\n## ${cat}\n`);
+        for (const e of items.sort((a, b) => a.command.localeCompare(b.command))) {
+            process.stdout.write(`  ${safetyTag(e.safetyLevel)}  ${e.command.padEnd(34)} ${e.description}\n`);
+        }
+    }
+    return 0;
+}
+/** `shrk commands profile` (no id) lists the available surface profiles. */
+function runCommandsProfileList(args) {
+    const rows = BUILTIN_PROFILES.map((p) => ({
+        id: p.id,
+        description: p.description,
+        hides: (p.hidden ?? []).length,
+    }));
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: rows.length, profiles: rows }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Surface profiles (${rows.length})`));
+    for (const r of rows) {
+        process.stdout.write(`  ${r.id.padEnd(12)} hides=${String(r.hides).padEnd(4)} ${r.description}\n`);
+    }
+    process.stdout.write(`\nUsage: shrk commands profile <id>   |   shrk commands --profile <id>   (render the curated view)\n`);
+    return 0;
+}
 /** `shrk commands machine` lists machine-oriented commands. */
 function runCommandsMachine(args) {
     const matches = COMMAND_CATALOG.filter((e) => commandSurface(e) === CommandSurface.Machine || e.machineOnly === true);
@@ -487,6 +611,10 @@ export const commandsCommand = {
         // Keep the new views available even via the back-compat entry.
         if (sub === 'surface')
             return runCommandsSurface(args);
+        if (sub === 'profile') {
+            const id = args.positional[1];
+            return id ? runCommandsProfile(args, id) : runCommandsProfileList(args);
+        }
         if (sub === 'machine')
             return runCommandsMachine(args);
         if (sub === 'legacy')
@@ -503,6 +631,10 @@ export const commandsCommand = {
             return runCommandsRetirementPlan(args);
         if (sub === 'docs-check')
             return await runCommandsDocsCheck(args);
+        const profileFilter = flagString(args, 'profile');
+        if (profileFilter) {
+            return runCommandsProfile(args, profileFilter);
+        }
         const safetyFilter = flagString(args, 'safety');
         const categoryFilter = flagString(args, 'category');
         let entries = COMMAND_CATALOG;
@@ -882,6 +1014,33 @@ export function buildCommandsDoctorReport(registry) {
                 });
             }
         }
+        // 8. registerSubcommand-only GROUPS without a catalog entry.
+        // Check #7 above only sees depth-1 nodes that carry a handler
+        // (registry.list()). Groups registered purely via registerSubcommand
+        // (e.g. paths / pipelines / checks / audit / ownership) are handler-less
+        // group nodes — they resolve live yet never appear in list(), so the
+        // doctor reported "No issues" while those groups had zero catalog
+        // coverage. Walk listGroups() and flag any group no catalog entry
+        // covers. Pure alias groups (listGroupAliases) are skipped — their
+        // canonical target carries the entry.
+        const aliasGroups = new Set(registry.listGroupAliases().keys());
+        const catalogTopWords = new Set();
+        for (const e of COMMAND_CATALOG) {
+            const top = e.command.split(/\s+/)[0];
+            if (top)
+                catalogTopWords.add(top);
+        }
+        for (const g of registry.listGroups()) {
+            if (aliasGroups.has(g))
+                continue;
+            if (!catalogTopWords.has(g)) {
+                issues.push({
+                    code: 'missing-catalog-entry',
+                    message: `command group "${g}" is registered (registerSubcommand) but no catalog entry covers it`,
+                    severity: 'error',
+                });
+            }
+        }
     }
     const errors = issues.filter((i) => i.severity === 'error').length;
     const warnings = issues.filter((i) => i.severity === 'warning').length;

package/dist/commands/compress.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,eAAe,EAAE,eA8F7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqEhC,eAAO,MAAM,eAAe,EAAE,eAoG7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -5,6 +5,35 @@ import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-regist
 import { asJson } from "../output/format-output.js";
 import { ccrDir, openCcrStore } from "../output/ccr-store-config.js";
 const CONTENT_TYPES = new Set(Object.values(EContentType));
+// `--type` accepts the EContentType wire strings plus ergonomic aliases. `code`
+// is an alias for `source-code`: it routes to the structure-preserving code
+// outline (ECompressionStrategy.Code), NOT the markdown line-omission a bare
+// `code` used to silently fall through to under auto-detect.
+const TYPE_ALIASES = {
+    code: EContentType.SourceCode,
+};
+// The full set of accepted `--type` tokens (content-type wire strings +
+// aliases), sorted and rendered once so the rejection message and the
+// passthrough hint advertise exactly what `resolveContentType` accepts.
+const VALID_TYPE_TOKENS = [...CONTENT_TYPES, ...Object.keys(TYPE_ALIASES)].sort().join(', ');
+/**
+ * Resolve a raw `--type` value into a forced {@link EContentType}. Unlike the
+ * old `CONTENT_TYPES.has` check — which silently dropped unknown values and let
+ * the phantom `code` fall through to auto-detect (markdown line-omission) — an
+ * unrecognized non-empty value yields an `error` so the caller can reject with a
+ * non-zero exit, and `code` is mapped to the real source-code strategy. A
+ * missing/empty value is a no-op (auto-detect).
+ */
+function resolveContentType(raw) {
+    if (raw === undefined || raw === '')
+        return {};
+    const aliased = TYPE_ALIASES[raw];
+    if (aliased)
+        return { type: aliased };
+    if (CONTENT_TYPES.has(raw))
+        return { type: raw };
+    return { error: `compress: unknown --type "${raw}". Valid types: ${VALID_TYPE_TOKENS}.` };
+}
 // Below this size a passthrough no-op isn't worth a warning (tiny snippets
 // legitimately have nothing to compress). Above it, a silent `−0%` re-emit is
 // the opposite of the tool's purpose — nudge the user toward `--type`.
@@ -36,6 +65,13 @@ export const compressCommand = {
     booleanFlags: COMPRESS_BOOLEAN_FLAGS,
     run(args) {
         const cwd = resolveCwd(args);
+        // Validate `--type` up front: an unknown value is a user error, not a
+        // silent fall-through to auto-detect — fail fast before reading input.
+        const resolvedType = resolveContentType(flagString(args, 'type'));
+        if (resolvedType.error) {
+            process.stderr.write(resolvedType.error + '\n');
+            return 1;
+        }
         let content;
         try {
             content = readInput(args);
@@ -59,9 +95,8 @@ export const compressCommand = {
             opts.maxItems = Math.floor(max);
         if (flagBool(args, 'lossless'))
             opts.lossless = true;
-        const type = flagString(args, 'type');
-        if (type && CONTENT_TYPES.has(type))
-            opts.contentType = type;
+        if (resolvedType.type)
+            opts.contentType = resolvedType.type;
         const result = compressContent(content, opts);
         const pct = Math.round(result.savings.ratio * 100);
         // A lossy result with no cached original (i.e. --no-cache) can't be undone
@@ -109,7 +144,7 @@ export const compressCommand = {
             inputBytes >= PASSTHROUGH_HINT_MIN_BYTES &&
             !flagBool(args, 'lossless')) {
             process.stderr.write(`hint: nothing was compressed — auto-detect classified this as ${result.contentType} and found no win. ` +
-                'Try `--type <content-type>` to force a strategy (json, git-diff, search-results, build-log, source-code, markdown).\n');
+                `Try \`--type <content-type>\` to force a strategy (${VALID_TYPE_TOKENS}).\n`);
         }
         return 0;
     },