@shrkcrft/cli 0.1.0-alpha.2

package/dist/commands/commands.command.js

@@ -0,0 +1,1208 @@
+import { flagBool, flagString, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+import { COMMAND_CATALOG, CommandLifecycle, CommandSurface, R46_OVERLAY, SafetyLevel, buildCommandSafetyMatrix, commandLifecycle, commandSurface, commandTaskRole, defaultShowInHelp, renderCommandSafetyMatrixMarkdown, } 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]',
+        async run(args) {
+            const sub = args.positional[0];
+            if (sub === 'doctor') {
+                return runCommandsDoctor(args, registry);
+            }
+            if (sub === 'ux-check') {
+                return runCommandsUxCheck(args);
+            }
+            if (sub === 'primary') {
+                const report = buildPrimaryCommandsReport();
+                if (flagBool(args, 'json')) {
+                    process.stdout.write(asJson(report) + '\n');
+                    return 0;
+                }
+                process.stdout.write(renderPrimaryCommandsText(report));
+                return 0;
+            }
+            if (sub === 'tree') {
+                return printTree(args);
+            }
+            if (sub === 'taxonomy') {
+                const report = buildCommandTaxonomy({ catalog: COMMAND_CATALOG });
+                const explicitOutput = flagString(args, 'output');
+                const writeDocs = flagBool(args, 'write-docs');
+                const format = flagString(args, 'format') ?? (flagBool(args, 'json') ? 'json' : 'text');
+                if (writeDocs || explicitOutput) {
+                    const { mkdirSync, writeFileSync } = await import('node:fs');
+                    const { dirname, isAbsolute, resolve } = await import('node:path');
+                    const cwd = process.cwd();
+                    const target = explicitOutput
+                        ? isAbsolute(explicitOutput)
+                            ? explicitOutput
+                            : resolve(cwd, explicitOutput)
+                        : resolve(cwd, 'docs/commands-taxonomy.md');
+                    mkdirSync(dirname(target), { recursive: true });
+                    const header = '<!-- generated by `shrk commands taxonomy --write-docs` — do not edit by hand -->\n\n';
+                    const body = renderCommandTaxonomyMarkdown(report);
+                    writeFileSync(target, header + body, 'utf8');
+                    process.stdout.write(`Wrote ${target}\n`);
+                    return 0;
+                }
+                if (format === 'json') {
+                    process.stdout.write(asJson(report) + '\n');
+                }
+                else if (format === 'markdown') {
+                    process.stdout.write(renderCommandTaxonomyMarkdown(report));
+                }
+                else {
+                    process.stdout.write(renderCommandTaxonomyText(report));
+                }
+                return 0;
+            }
+            if (sub === 'matrix') {
+                const rows = buildCommandSafetyMatrix();
+                const fmt = flagString(args, 'format') ?? (flagBool(args, 'json') ? 'json' : 'markdown');
+                if (fmt === 'json') {
+                    process.stdout.write(asJson(rows) + '\n');
+                }
+                else {
+                    process.stdout.write(renderCommandSafetyMatrixMarkdown(rows));
+                }
+                return 0;
+            }
+            // `shrk commands entrypoints` / `shrk commands workflows` renders
+            // the entrypoint matrix that classifies entrypoints by class
+            // (human-interactive / agent-mcp / machine-json / debug-explainability).
+            if (sub === 'entrypoints' || sub === 'workflows') {
+                const { buildEntrypointMatrix, renderEntrypointMatrixText } = await import('@shrkcrft/inspector');
+                const report = buildEntrypointMatrix();
+                if (flagBool(args, 'json')) {
+                    process.stdout.write(asJson(report) + '\n');
+                    return 0;
+                }
+                process.stdout.write(renderEntrypointMatrixText(report));
+                return 0;
+            }
+            if (sub === 'search') {
+                const query = args.positional.slice(1).join(' ').toLowerCase().trim();
+                const filtered = COMMAND_CATALOG.filter((c) => !query ||
+                    c.command.toLowerCase().includes(query) ||
+                    c.description.toLowerCase().includes(query) ||
+                    c.aliases.some((a) => a.toLowerCase().includes(query)));
+                return printCatalog(args, filtered);
+            }
+            // Surface / machine / legacy / overlaps views.
+            if (sub === 'surface') {
+                return runCommandsSurface(args);
+            }
+            if (sub === 'machine') {
+                return runCommandsMachine(args);
+            }
+            if (sub === 'legacy') {
+                return runCommandsLegacy(args);
+            }
+            if (sub === 'overlaps') {
+                return runCommandsOverlaps(args);
+            }
+            // Advanced / deprecated / hidden / retirement-plan / docs-check.
+            if (sub === 'advanced') {
+                return runCommandsAdvanced(args);
+            }
+            if (sub === 'deprecated') {
+                return runCommandsDeprecated(args);
+            }
+            if (sub === 'hidden') {
+                return runCommandsHidden(args);
+            }
+            if (sub === 'retirement-plan') {
+                return runCommandsRetirementPlan(args);
+            }
+            if (sub === 'docs-check') {
+                return runCommandsDocsCheck(args);
+            }
+            const safetyFilter = flagString(args, 'safety');
+            const categoryFilter = flagString(args, 'category');
+            const wantsAll = flagBool(args, 'all');
+            let entries = COMMAND_CATALOG;
+            if (safetyFilter) {
+                entries = entries.filter((e) => e.safetyLevel === safetyFilter);
+            }
+            if (categoryFilter) {
+                entries = entries.filter((e) => e.category === categoryFilter);
+            }
+            // Default view shrinks to "what new users should see first":
+            // primary + common (visible per `defaultShowInHelp`). `--all` brings
+            // back the full catalog. `--safety` / `--category` filters force the
+            // entire catalog through (operators using them know what they're
+            // doing).
+            if (!wantsAll && !safetyFilter && !categoryFilter) {
+                return printCompactCatalog(args, entries);
+            }
+            return printCatalog(args, entries);
+        },
+    };
+}
+/**
+ * `shrk commands surface <surface>` filters by the new surface
+ * classification. With no argument, prints a one-line summary per surface.
+ */
+function runCommandsSurface(args) {
+    const wanted = args.positional[1];
+    if (!wanted) {
+        const counts = new Map();
+        for (const e of COMMAND_CATALOG) {
+            const s = commandSurface(e);
+            counts.set(s, (counts.get(s) ?? 0) + 1);
+        }
+        if (flagBool(args, 'json')) {
+            const out = {};
+            for (const [k, v] of counts)
+                out[k] = v;
+            process.stdout.write(asJson({ surfaces: out, total: COMMAND_CATALOG.length }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Command surfaces'));
+        for (const s of Object.values(CommandSurface)) {
+            const n = counts.get(s) ?? 0;
+            process.stdout.write(`  ${s.padEnd(10)} ${n}\n`);
+        }
+        process.stdout.write(`\nUsage: shrk commands surface <${Object.values(CommandSurface).join('|')}> [--json]\n`);
+        return 0;
+    }
+    const surface = wanted;
+    if (!Object.values(CommandSurface).includes(surface)) {
+        process.stderr.write(`Unknown surface "${wanted}". Valid: ${Object.values(CommandSurface).join(', ')}\n`);
+        return 2;
+    }
+    const matches = COMMAND_CATALOG.filter((e) => commandSurface(e) === surface);
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ surface, total: matches.length, entries: matches }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Commands — surface=${surface} (${matches.length})`));
+    for (const e of matches) {
+        const tag = safetyTag(e.safetyLevel);
+        process.stdout.write(`  ${tag}  ${e.command.padEnd(34)} ${e.description}\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);
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: matches.length, entries: matches }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Machine-oriented commands (${matches.length})`));
+    if (matches.length === 0) {
+        process.stdout.write('  (none)\n');
+        return 0;
+    }
+    for (const e of matches) {
+        const tag = safetyTag(e.safetyLevel);
+        const prefer = e.preferredCommand ? `  → prefer: ${e.preferredCommand}` : '';
+        process.stdout.write(`  ${tag}  ${e.command.padEnd(28)} ${e.description}${prefer}\n`);
+    }
+    return 0;
+}
+/**
+ * `shrk commands advanced` lists every advanced surface (typically
+ * maintainer / pack-author / one-off diagnostic commands).
+ */
+function runCommandsAdvanced(args) {
+    const matches = COMMAND_CATALOG.filter((e) => commandSurface(e) === CommandSurface.Advanced);
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: matches.length, entries: matches }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Advanced commands (${matches.length})`));
+    if (matches.length === 0) {
+        process.stdout.write('  (none)\n');
+        return 0;
+    }
+    for (const e of matches) {
+        const tag = safetyTag(e.safetyLevel);
+        process.stdout.write(`  ${tag}  ${e.command.padEnd(34)} ${e.description}\n`);
+    }
+    return 0;
+}
+/**
+ * `shrk commands deprecated` lists every command with `lifecycle =
+ * Deprecated` / `Retired` (also picks up entries that have `replacedBy` but
+ * inherited the default lifecycle).
+ */
+function runCommandsDeprecated(args) {
+    const matches = COMMAND_CATALOG.filter((e) => {
+        const lc = commandLifecycle(e);
+        return lc === CommandLifecycle.Deprecated || lc === CommandLifecycle.Retired;
+    });
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: matches.length, entries: matches }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Deprecated / retired commands (${matches.length})`));
+    if (matches.length === 0) {
+        process.stdout.write('  (none)\n');
+        return 0;
+    }
+    for (const e of matches) {
+        const lc = commandLifecycle(e);
+        const dest = e.replacedBy ?? e.preferredCommand ?? '(no replacement)';
+        const since = e.deprecatedSince ? `  since=${e.deprecatedSince}` : '';
+        const removeAfter = e.removeAfter ? `  removeAfter=${e.removeAfter}` : '';
+        process.stdout.write(`  [${lc}]  shrk ${e.command.padEnd(28)} → ${dest}${since}${removeAfter}\n`);
+        if (e.reason) {
+            process.stdout.write(`        reason: ${e.reason}\n`);
+        }
+    }
+    return 0;
+}
+/**
+ * `shrk commands hidden` lists every catalog entry that is hidden
+ * from default help (advanced / machine / internal / legacy / deprecated /
+ * retired / alias / explicit `showInDefaultHelp=false`).
+ */
+function runCommandsHidden(args) {
+    const matches = COMMAND_CATALOG.filter((e) => !defaultShowInHelp(e));
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: matches.length, entries: matches }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Hidden-from-default-help commands (${matches.length})`));
+    if (matches.length === 0) {
+        process.stdout.write('  (none)\n');
+        return 0;
+    }
+    const byReason = new Map();
+    for (const e of matches) {
+        const reason = hiddenReason(e);
+        const arr = byReason.get(reason) ?? [];
+        arr.push(e);
+        byReason.set(reason, arr);
+    }
+    for (const [reason, list] of byReason) {
+        process.stdout.write(`\n${reason} (${list.length}):\n`);
+        for (const e of list) {
+            process.stdout.write(`  shrk ${e.command.padEnd(32)} ${e.description}\n`);
+        }
+    }
+    return 0;
+}
+function hiddenReason(e) {
+    if (e.showInDefaultHelp === false)
+        return 'explicit showInDefaultHelp=false';
+    const lc = commandLifecycle(e);
+    if (lc === CommandLifecycle.Retired)
+        return 'retired';
+    if (lc === CommandLifecycle.Deprecated)
+        return 'deprecated';
+    if (lc === CommandLifecycle.Alias)
+        return 'alias';
+    const surface = commandSurface(e);
+    if (surface === CommandSurface.Advanced)
+        return 'surface=advanced';
+    if (surface === CommandSurface.Machine)
+        return 'surface=machine';
+    if (surface === CommandSurface.Internal)
+        return 'surface=internal';
+    if (surface === CommandSurface.Legacy)
+        return 'surface=legacy';
+    return 'other';
+}
+/**
+ * Build the retirement plan: groups every entry that needs lifecycle
+ * attention. Pure for testing.
+ */
+export function buildRetirementPlanReport() {
+    const deprecated = [];
+    const aliases = [];
+    const machineInHelp = [];
+    const overlapping = [];
+    const missingReplacedBy = [];
+    const legacyNoRemoveAfter = [];
+    for (const e of COMMAND_CATALOG) {
+        const lc = commandLifecycle(e);
+        if (lc === CommandLifecycle.Deprecated || lc === CommandLifecycle.Retired) {
+            const row = { command: e.command };
+            if (e.replacedBy)
+                row.replacedBy = e.replacedBy;
+            if (e.preferredCommand)
+                row.preferredCommand = e.preferredCommand;
+            if (e.reason)
+                row.reason = e.reason;
+            if (e.deprecatedSince)
+                row.deprecatedSince = e.deprecatedSince;
+            deprecated.push(row);
+            if (!e.replacedBy && !e.preferredCommand) {
+                missingReplacedBy.push({ command: e.command });
+            }
+            if (commandSurface(e) === CommandSurface.Legacy && !e.removeAfter) {
+                legacyNoRemoveAfter.push({ command: e.command });
+            }
+        }
+        if (lc === CommandLifecycle.Alias) {
+            const row = { command: e.command };
+            if (e.replacedBy)
+                row.replacedBy = e.replacedBy;
+            if (e.preferredCommand)
+                row.preferredCommand = e.preferredCommand;
+            aliases.push(row);
+        }
+        if ((commandSurface(e) === CommandSurface.Machine || e.machineOnly === true) &&
+            defaultShowInHelp(e)) {
+            machineInHelp.push({ command: e.command });
+        }
+        if (e.overlapsWith && e.overlapsWith.length > 0) {
+            overlapping.push({ command: e.command, overlapsWith: e.overlapsWith });
+        }
+    }
+    const groups = [];
+    if (deprecated.length)
+        groups.push({ reason: 'deprecated', entries: deprecated });
+    if (aliases.length)
+        groups.push({ reason: 'aliases', entries: aliases });
+    if (machineInHelp.length)
+        groups.push({ reason: 'machine-in-help', entries: machineInHelp });
+    if (overlapping.length)
+        groups.push({ reason: 'overlapping', entries: overlapping });
+    if (missingReplacedBy.length)
+        groups.push({ reason: 'missing-replacedBy', entries: missingReplacedBy });
+    if (legacyNoRemoveAfter.length)
+        groups.push({ reason: 'legacy-no-removeAfter', entries: legacyNoRemoveAfter });
+    return {
+        schema: 'sharkcraft.commands-retirement-plan/v1',
+        total: groups.reduce((sum, g) => sum + g.entries.length, 0),
+        groups,
+    };
+}
+function runCommandsRetirementPlan(args) {
+    const report = buildRetirementPlanReport();
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson(report) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Retirement plan (${report.total} entries)`));
+    if (report.groups.length === 0) {
+        process.stdout.write('  No lifecycle attention needed. ✓\n');
+        return 0;
+    }
+    for (const g of report.groups) {
+        process.stdout.write(`\n${g.reason} (${g.entries.length}):\n`);
+        for (const e of g.entries) {
+            const dest = e.replacedBy ?? e.preferredCommand;
+            const arrow = dest ? `  → ${dest}` : '';
+            const overlaps = e.overlapsWith ? `  overlaps: ${e.overlapsWith.join(', ')}` : '';
+            const since = e.deprecatedSince ? `  since=${e.deprecatedSince}` : '';
+            process.stdout.write(`  shrk ${e.command}${arrow}${overlaps}${since}\n`);
+            if (e.reason)
+                process.stdout.write(`        reason: ${e.reason}\n`);
+        }
+    }
+    process.stdout.write('\nThis report prepares pruning — no commands are removed yet.\n');
+    return 0;
+}
+/** `shrk commands legacy` lists deprecated / replaced commands. */
+function runCommandsLegacy(args) {
+    const matches = COMMAND_CATALOG.filter((e) => commandSurface(e) === CommandSurface.Legacy || e.replacedBy);
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: matches.length, entries: matches }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Legacy / replaced commands (${matches.length})`));
+    if (matches.length === 0) {
+        process.stdout.write('  (none)\n');
+        return 0;
+    }
+    for (const e of matches) {
+        const replacedBy = e.replacedBy ? `  → ${e.replacedBy}` : '';
+        process.stdout.write(`  shrk ${e.command.padEnd(32)} ${e.description}${replacedBy}\n`);
+    }
+    return 0;
+}
+/**
+ * `shrk commands overlaps` lists commands that declare overlap with
+ * others, plus their preferredCommand pointer (or `(none)` for unresolved).
+ */
+function runCommandsOverlaps(args) {
+    const rows = [];
+    for (const e of COMMAND_CATALOG) {
+        if (e.overlapsWith && e.overlapsWith.length > 0) {
+            rows.push({
+                command: e.command,
+                overlapsWith: e.overlapsWith,
+                preferredCommand: e.preferredCommand ?? null,
+            });
+        }
+    }
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: rows.length, entries: rows }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Overlapping commands (${rows.length})`));
+    if (rows.length === 0) {
+        process.stdout.write('  (none)\n');
+        return 0;
+    }
+    for (const r of rows) {
+        process.stdout.write(`  shrk ${r.command}\n`);
+        process.stdout.write(`    overlaps with: ${r.overlapsWith.join(', ')}\n`);
+        process.stdout.write(`    prefer:        ${r.preferredCommand ?? '(none — add preferredCommand)'}\n`);
+    }
+    return 0;
+}
+/** Back-compat: the simple top-level entry kept so existing tests still work. */
+export const commandsCommand = {
+    name: 'commands',
+    description: 'List every `shrk` command with its safety level, side effects, and MCP availability. Use `shrk commands search <query>` to filter.',
+    usage: 'shrk commands [search <query>|tree|doctor] [--safety <level>] [--category <name>] [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'doctor') {
+            return runCommandsDoctor(args, null);
+        }
+        if (sub === 'tree') {
+            return printTree(args);
+        }
+        // `shrk commands entrypoints` renders the entrypoint matrix
+        // (which entrypoint should I use for X?). The pre-existing
+        // `shrk commands matrix` continues to print the command safety matrix.
+        if (sub === 'entrypoints' || sub === 'workflows') {
+            const { buildEntrypointMatrix, renderEntrypointMatrixText } = await import('@shrkcrft/inspector');
+            const report = buildEntrypointMatrix();
+            if (flagBool(args, 'json')) {
+                process.stdout.write(asJson(report) + '\n');
+                return 0;
+            }
+            process.stdout.write(renderEntrypointMatrixText(report));
+            return 0;
+        }
+        if (sub === 'search') {
+            const query = args.positional.slice(1).join(' ').toLowerCase().trim();
+            const filtered = COMMAND_CATALOG.filter((c) => !query ||
+                c.command.toLowerCase().includes(query) ||
+                c.description.toLowerCase().includes(query) ||
+                c.aliases.some((a) => a.toLowerCase().includes(query)));
+            return printCatalog(args, filtered);
+        }
+        // Keep the new views available even via the back-compat entry.
+        if (sub === 'surface')
+            return runCommandsSurface(args);
+        if (sub === 'machine')
+            return runCommandsMachine(args);
+        if (sub === 'legacy')
+            return runCommandsLegacy(args);
+        if (sub === 'overlaps')
+            return runCommandsOverlaps(args);
+        if (sub === 'advanced')
+            return runCommandsAdvanced(args);
+        if (sub === 'deprecated')
+            return runCommandsDeprecated(args);
+        if (sub === 'hidden')
+            return runCommandsHidden(args);
+        if (sub === 'retirement-plan')
+            return runCommandsRetirementPlan(args);
+        if (sub === 'docs-check')
+            return await runCommandsDocsCheck(args);
+        const safetyFilter = flagString(args, 'safety');
+        const categoryFilter = flagString(args, 'category');
+        let entries = COMMAND_CATALOG;
+        if (safetyFilter) {
+            entries = entries.filter((e) => e.safetyLevel === safetyFilter);
+        }
+        if (categoryFilter) {
+            entries = entries.filter((e) => e.category === categoryFilter);
+        }
+        return printCatalog(args, entries);
+    },
+};
+const PRIMARY_COMMAND_HINTS = [
+    'doctor',
+    'context',
+    'task',
+    'search',
+    'impact',
+    'brief',
+    'dev start',
+    'quality',
+    'review packet',
+    'report site',
+    'release readiness',
+    'commands',
+    'start-here',
+    'onboard',
+    // `map` and `handoff` were folded into `architecture map` and `brief`.
+];
+export function buildCommandsUxReport() {
+    const issues = [];
+    const seenAliases = new Map();
+    let primaryReferenced = 0;
+    for (const e of COMMAND_CATALOG) {
+        if (!e.description || e.description.trim().length < 5) {
+            issues.push({
+                code: e.description ? 'short-description' : 'missing-description',
+                severity: e.description ? 'warning' : 'error',
+                message: e.description
+                    ? `description for "${e.command}" is < 5 chars — would not help a reader picking the command`
+                    : `catalog entry "${e.command}" has no description`,
+                command: e.command,
+            });
+        }
+        if (!e.safetyLevel) {
+            issues.push({
+                code: 'missing-safety-metadata',
+                severity: 'error',
+                message: `catalog entry "${e.command}" missing safetyLevel`,
+                command: e.command,
+            });
+        }
+        if (e.aliases && e.aliases.length > 0) {
+            for (const a of e.aliases) {
+                const prior = seenAliases.get(a);
+                if (prior && prior !== e.command) {
+                    issues.push({
+                        code: 'duplicate-alias',
+                        severity: 'warning',
+                        message: `alias "${a}" used by both "${prior}" and "${e.command}"`,
+                        command: e.command,
+                    });
+                }
+                seenAliases.set(a, e.command);
+            }
+        }
+        if (PRIMARY_COMMAND_HINTS.some((p) => e.command === p || e.command.startsWith(p + ' '))) {
+            primaryReferenced += 1;
+        }
+    }
+    // Each primary hint should map to at least one catalog entry.
+    for (const hint of PRIMARY_COMMAND_HINTS) {
+        const found = COMMAND_CATALOG.some((e) => e.command === hint || e.command.startsWith(hint + ' '));
+        if (!found) {
+            issues.push({
+                code: 'unreferenced-primary',
+                severity: 'warning',
+                message: `primary command "${hint}" has no catalog entry`,
+                command: hint,
+            });
+        }
+    }
+    // Metadata-driven UX checks. Warnings, not errors, unless the
+    // issue is clearly structural (none of these currently rise to error).
+    for (const e of COMMAND_CATALOG) {
+        const surface = commandSurface(e);
+        // (a) primary commands should declare an audience (so adopters can see
+        // who the command is for at a glance).
+        if (surface === CommandSurface.Primary && (!e.intendedAudience || e.intendedAudience.length === 0)) {
+            issues.push({
+                code: 'primary-without-audience',
+                severity: 'warning',
+                message: `primary command "${e.command}" has no explicit intendedAudience — readers can't tell who it's for`,
+                command: e.command,
+            });
+        }
+        // (b) primary commands should declare a taskRole.
+        if (surface === CommandSurface.Primary && !e.taskRole) {
+            issues.push({
+                code: 'primary-without-role',
+                severity: 'warning',
+                message: `primary command "${e.command}" has no taskRole — readers can't slot it into the start/context/search/... map`,
+                command: e.command,
+            });
+        }
+        // (c) machine-only commands should not be marked primary. If they're
+        // primary they end up promoted to humans on `shrk commands primary`,
+        // which is the problem we're trying to fix.
+        if (surface === CommandSurface.Primary && e.machineOnly === true) {
+            issues.push({
+                code: 'machine-marked-primary',
+                severity: 'warning',
+                message: `command "${e.command}" is marked machineOnly but surface=primary — set surface=machine or remove machineOnly`,
+                command: e.command,
+            });
+        }
+        // (d) legacy entries need a replacement pointer.
+        if (surface === CommandSurface.Legacy && !e.replacedBy && !e.preferredCommand) {
+            issues.push({
+                code: 'legacy-without-replacement',
+                severity: 'warning',
+                message: `legacy command "${e.command}" has no replacedBy / preferredCommand — readers won't know where to go`,
+                command: e.command,
+            });
+        }
+        // (e) commands that declare an overlap must point to a preferred path
+        // (or be the canonical entry — surface=Primary + role=Start). Otherwise
+        // the operator doesn't know which of the overlapping ones to pick.
+        if (e.overlapsWith && e.overlapsWith.length > 0 && !e.preferredCommand) {
+            const isCanonical = surface === CommandSurface.Primary && e.taskRole === 'start';
+            if (!isCanonical) {
+                issues.push({
+                    code: 'overlap-without-preferred',
+                    severity: 'warning',
+                    message: `command "${e.command}" declares overlapsWith=[${e.overlapsWith.join(', ')}] but no preferredCommand — operator can't tell which one to pick`,
+                    command: e.command,
+                });
+            }
+        }
+        // (f) description "explains purpose" heuristic: descriptions ≤ 30 chars
+        // typically describe what without saying when. We flag this for primary
+        // commands only — advanced/internal commands can afford to be terse.
+        if (surface === CommandSurface.Primary && e.description.trim().length < 30) {
+            issues.push({
+                code: 'description-without-purpose',
+                severity: 'info',
+                message: `primary command "${e.command}" has a short description (${e.description.trim().length} chars) — consider explaining when to use it`,
+                command: e.command,
+            });
+        }
+    }
+    // (h) deprecated lifecycle requires replacedBy or reason.
+    // Overlay-supplied `replacedBy`/`reason` count as well, so the audit
+    // can mark batches deprecated without re-shuffling 40+ catalog literals.
+    for (const e of COMMAND_CATALOG) {
+        const lc = commandLifecycle(e);
+        const r46 = R46_OVERLAY[e.command];
+        if (lc === CommandLifecycle.Deprecated &&
+            !e.replacedBy &&
+            !e.preferredCommand &&
+            !e.reason &&
+            !r46?.replacedBy &&
+            !r46?.reason) {
+            issues.push({
+                code: 'deprecated-without-replacement',
+                severity: 'warning',
+                message: `deprecated command "${e.command}" has no replacedBy / preferredCommand / reason`,
+                command: e.command,
+            });
+        }
+        if (lc === CommandLifecycle.Alias && !e.replacedBy && !e.preferredCommand) {
+            issues.push({
+                code: 'alias-without-target',
+                severity: 'warning',
+                message: `alias command "${e.command}" has no replacedBy / preferredCommand — readers can't find the canonical command`,
+                command: e.command,
+            });
+        }
+        // (i) Non-standard verbosity flags surfaced via description.
+        const descLower = e.description.toLowerCase();
+        const nonStandard = ['--detailed', '--long', '--more', '--with-detail', '--expand'];
+        for (const flag of nonStandard) {
+            if (descLower.includes(flag)) {
+                issues.push({
+                    code: 'nonstandard-verbosity-flag',
+                    severity: 'warning',
+                    message: `command "${e.command}" advertises non-standard verbosity flag ${flag} — prefer --verbose / --full / --json (see docs/verbosity-vocabulary.md)`,
+                    command: e.command,
+                });
+            }
+        }
+    }
+    // (g) too many primary commands for the same taskRole. The agent / new
+    // user shouldn't see 5 "start" primary commands; one canonical wins.
+    const primaryByRole = new Map();
+    for (const e of COMMAND_CATALOG) {
+        if (commandSurface(e) === CommandSurface.Primary && e.taskRole) {
+            const arr = primaryByRole.get(e.taskRole) ?? [];
+            arr.push(e.command);
+            primaryByRole.set(e.taskRole, arr);
+        }
+    }
+    for (const [role, cmds] of primaryByRole) {
+        if (cmds.length > 4) {
+            issues.push({
+                code: 'too-many-primary-for-role',
+                severity: 'info',
+                message: `${cmds.length} primary commands share taskRole="${role}" (${cmds.join(', ')}) — consider promoting one canonical and demoting the rest to common`,
+                command: cmds.join(','),
+            });
+        }
+    }
+    const errors = issues.filter((i) => i.severity === 'error').length;
+    const warnings = issues.filter((i) => i.severity === 'warning').length;
+    return {
+        schema: 'sharkcraft.commands-ux-check/v1',
+        passed: errors === 0,
+        issues,
+        summary: {
+            catalogEntries: COMMAND_CATALOG.length,
+            primaryReferenced,
+            errors,
+            warnings,
+        },
+    };
+}
+async function runCommandsUxCheck(args) {
+    const report = buildCommandsUxReport();
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson(report) + '\n');
+        return report.passed ? 0 : 1;
+    }
+    process.stdout.write(header('Commands UX check'));
+    process.stdout.write(`  catalog ${report.summary.catalogEntries}  primary referenced ${report.summary.primaryReferenced}  errors ${report.summary.errors}  warnings ${report.summary.warnings}\n\n`);
+    if (report.issues.length === 0) {
+        process.stdout.write('No UX issues found.\n');
+    }
+    else {
+        for (const i of report.issues) {
+            process.stdout.write(`  [${i.severity.padEnd(8)}] ${i.code.padEnd(24)} ${i.command} — ${i.message}\n`);
+        }
+    }
+    return report.passed ? 0 : 1;
+}
+/** Pure: build the doctor report. Exported for tests. */
+export function buildCommandsDoctorReport(registry) {
+    const issues = [];
+    // 1. No duplicate commands.
+    const seen = new Set();
+    for (const e of COMMAND_CATALOG) {
+        if (seen.has(e.command)) {
+            issues.push({
+                code: 'duplicate-command',
+                message: `duplicate catalog entry for "${e.command}"`,
+                severity: 'error',
+            });
+        }
+        seen.add(e.command);
+    }
+    // 2. Every entry has a safety level + description + category.
+    const validLevels = new Set(Object.values(SafetyLevel));
+    for (const e of COMMAND_CATALOG) {
+        if (!e.description || e.description.trim().length === 0) {
+            issues.push({
+                code: 'missing-description',
+                message: `catalog entry "${e.command}" has empty description`,
+                severity: 'error',
+            });
+        }
+        if (!validLevels.has(e.safetyLevel)) {
+            issues.push({
+                code: 'invalid-safety-level',
+                message: `catalog entry "${e.command}" has invalid safetyLevel "${e.safetyLevel}"`,
+                severity: 'error',
+            });
+        }
+        if (!e.category || e.category.trim().length === 0) {
+            issues.push({
+                code: 'missing-category',
+                message: `catalog entry "${e.command}" has empty category`,
+                severity: 'warning',
+            });
+        }
+    }
+    // 3. writes-source ⇒ not MCP-available.
+    for (const e of COMMAND_CATALOG) {
+        if (e.writesSource && e.mcpAvailable) {
+            issues.push({
+                code: 'writes-source-via-mcp',
+                message: `catalog entry "${e.command}" writes source but is marked mcpAvailable`,
+                severity: 'error',
+            });
+        }
+    }
+    // 4. writesSource ⇒ writesFiles.
+    for (const e of COMMAND_CATALOG) {
+        if (e.writesSource && !e.writesFiles) {
+            issues.push({
+                code: 'writes-source-without-writes-files',
+                message: `catalog entry "${e.command}" sets writesSource but not writesFiles`,
+                severity: 'warning',
+            });
+        }
+    }
+    // 5. runs-shell safety level ⇒ runsShell flag (and vice versa).
+    for (const e of COMMAND_CATALOG) {
+        if (e.safetyLevel === SafetyLevel.RunsShell && !e.runsShell) {
+            issues.push({
+                code: 'shell-level-without-flag',
+                message: `catalog entry "${e.command}" is labeled runs-shell but runsShell=false`,
+                severity: 'warning',
+            });
+        }
+    }
+    // 6. Registry coverage: every catalog top-level verb resolves in the registry.
+    let registered = 0;
+    let registeredSub = 0;
+    if (registry) {
+        for (const cmd of registry.list())
+            registered += 1;
+        for (const g of registry.listGroups()) {
+            const sub = registry.listGroup(g);
+            registeredSub += sub.length;
+        }
+        for (const e of COMMAND_CATALOG) {
+            const parts = e.command.split(' ');
+            const top = parts[0];
+            const second = parts[1];
+            if (!registry.get(top) && !registry.listGroups().includes(top)) {
+                issues.push({
+                    code: 'unregistered-command',
+                    message: `catalog mentions "${e.command}" but "${top}" is not registered`,
+                    severity: 'error',
+                });
+                continue;
+            }
+            if (second && registry.listGroups().includes(top)) {
+                // Sub-verbs may be options/flags (e.g. "onboard --write-drafts");
+                // only treat the registered subcommand groups as ground truth.
+                const knownSub = registry.getSub(top, second);
+                // 3-level commands (e.g. `pack author status`) almost always
+                // go through an internal dispatcher in the parent command handler;
+                // the second level is a verb name, not a registered subcommand.
+                // Don't flag those as drift — the parent's existence is enough.
+                const isInternalDispatch = parts.length >= 3;
+                if (!knownSub && !second.startsWith('--') && !isInternalDispatch) {
+                    // Promoted from info to error: the catalog must tell the
+                    // truth about what's wired up. If the catalog claims a verb the
+                    // registry can't dispatch, that's drift the user shouldn't
+                    // discover by trying to run the command.
+                    issues.push({
+                        code: 'unregistered-subcommand',
+                        message: `catalog mentions "${e.command}" but no handler for "${top} ${second}"`,
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+        // 7. Registered commands without a catalog entry.
+        for (const c of registry.list()) {
+            const inCatalog = COMMAND_CATALOG.some((e) => e.command === c.name || e.command.startsWith(c.name + ' '));
+            if (!inCatalog) {
+                // Promoted to error for primary verbs: if a user types
+                // `shrk help <cmd>` we should be able to print catalog metadata
+                // for it.
+                issues.push({
+                    code: 'missing-catalog-entry',
+                    message: `command "${c.name}" is registered but has no catalog entry`,
+                    severity: 'error',
+                });
+            }
+            if (!c.usage || c.usage.trim().length === 0) {
+                issues.push({
+                    code: 'missing-usage',
+                    message: `command "${c.name}" has empty usage`,
+                    severity: 'warning',
+                });
+            }
+        }
+    }
+    const errors = issues.filter((i) => i.severity === 'error').length;
+    const warnings = issues.filter((i) => i.severity === 'warning').length;
+    return {
+        passed: errors === 0,
+        issues,
+        summary: {
+            catalogEntries: COMMAND_CATALOG.length,
+            registeredCommands: registered,
+            registeredSubcommands: registeredSub,
+            errors,
+            warnings,
+        },
+    };
+}
+function runCommandsDoctor(args, registry) {
+    const report = buildCommandsDoctorReport(registry);
+    const strict = flagBool(args, 'strict');
+    // `--strict` promotes any catalog drift (warnings AND info) to a
+    // failing verdict. Without --strict, only errors fail the verdict.
+    const failed = report.summary.errors > 0 || (strict && report.summary.warnings > 0);
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({
+            ...report,
+            strict,
+            verdict: failed ? 'drift' : 'clean',
+        }) + '\n');
+        return failed ? 1 : 0;
+    }
+    process.stdout.write(header('Command catalog doctor'));
+    process.stdout.write(`  catalogEntries: ${report.summary.catalogEntries}\n` +
+        `  registered:     ${report.summary.registeredCommands}\n` +
+        `  subcommands:    ${report.summary.registeredSubcommands}\n` +
+        `  errors:         ${report.summary.errors}\n` +
+        `  warnings:       ${report.summary.warnings}\n` +
+        (strict ? `  strict:         on\n` : '') +
+        '\n');
+    if (report.issues.length === 0) {
+        process.stdout.write('No issues.\n');
+        return 0;
+    }
+    for (const i of report.issues) {
+        process.stdout.write(`  ${i.severity.toUpperCase().padEnd(8)} ${i.code.padEnd(34)} ${i.message}\n`);
+    }
+    process.stdout.write(`\nVerdict: ${failed ? 'CATALOG DRIFT' : 'OK ✓'}\n`);
+    return failed ? 1 : 0;
+}
+function printCatalog(args, entries) {
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson(entries) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`SharkCraft commands (${entries.length})`));
+    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))) {
+            const safety = safetyTag(e.safetyLevel);
+            process.stdout.write(`  ${safety}  ${e.command.padEnd(34)} ${e.description}\n`);
+        }
+    }
+    return 0;
+}
+/**
+ * Compact default-view renderer. Only entries that pass
+ * {@link defaultShowInHelp} are listed, and they are grouped into three
+ * fixed sections (start / common-validation / common-generation+review+apply).
+ * Advanced / machine / deprecated / hidden are reachable via dedicated
+ * subcommands, surfaced in the trailing "See more" block.
+ */
+function printCompactCatalog(args, entries) {
+    if (flagBool(args, 'json')) {
+        // JSON keeps the legacy unfiltered shape so downstream tools don't break;
+        // the compaction is human-output-only.
+        process.stdout.write(asJson(entries) + '\n');
+        return 0;
+    }
+    const visible = entries.filter((e) => defaultShowInHelp(e));
+    const primary = visible.filter((e) => commandSurface(e) === CommandSurface.Primary);
+    const common = visible.filter((e) => commandSurface(e) === CommandSurface.Common);
+    process.stdout.write(header(`SharkCraft commands (default view — ${visible.length} of ${entries.length})`));
+    process.stdout.write('Primary commands (start here — canonical answers for common questions):\n');
+    for (const e of sortByCommand(primary)) {
+        const safety = safetyTag(e.safetyLevel);
+        process.stdout.write(`  ${safety}  ${e.command.padEnd(34)} ${e.description}\n`);
+    }
+    if (common.length > 0) {
+        // Surface only the common verbs that pair with one of the
+        // canonical task-roles users reach for from the start screen
+        // (generate / review / apply / validate / inspect / diagnose / config).
+        // Everything else stays one flag away (`--all`).
+        const allowedRoles = new Set(['generate', 'review', 'apply', 'validate', 'inspect', 'diagnose', 'config', 'release']);
+        const featured = sortByCommand(common).filter((e) => {
+            const role = commandTaskRole(e);
+            if (role && allowedRoles.has(role))
+                return true;
+            // Top-level verbs without subcommand suffix are still featured even
+            // without a role — they're the "front door" surfaces.
+            return !e.command.includes(' ');
+        });
+        const featuredLimit = 12;
+        process.stdout.write('\nCommon commands (frequent / well-documented surfaces):\n');
+        for (const e of featured.slice(0, featuredLimit)) {
+            const safety = safetyTag(e.safetyLevel);
+            process.stdout.write(`  ${safety}  ${e.command.padEnd(34)} ${e.description}\n`);
+        }
+        const remaining = common.length - Math.min(featured.length, featuredLimit);
+        if (remaining > 0) {
+            process.stdout.write(`  … (${remaining} more — pass --all to see every common command)\n`);
+        }
+    }
+    process.stdout.write('\nSee more:\n');
+    process.stdout.write('  $ shrk commands --all                   — full catalog\n');
+    process.stdout.write('  $ shrk commands advanced                — advanced surfaces\n');
+    process.stdout.write('  $ shrk commands machine                 — machine / JSON-pipe surfaces\n');
+    process.stdout.write('  $ shrk commands deprecated              — deprecated / replaced commands\n');
+    process.stdout.write('  $ shrk commands hidden                  — every hidden-from-default command\n');
+    process.stdout.write('  $ shrk commands overlaps                — overlapping surfaces + preferred entrypoint\n');
+    process.stdout.write('  $ shrk commands retirement-plan         — lifecycle backlog\n');
+    process.stdout.write('  $ shrk commands taxonomy                — domain grouping\n');
+    process.stdout.write('  $ shrk commands explain <cmd>           — detail for one command\n');
+    return 0;
+}
+function sortByCommand(entries) {
+    return [...entries].sort((a, b) => a.command.localeCompare(b.command));
+}
+const DOCS_TO_CHECK = [
+    'docs/command-entrypoints.md',
+    'docs/start-here.md',
+    'docs/overview.md',
+];
+export async function buildDocsCheckReport(cwd) {
+    const { readFileSync, existsSync } = await import('node:fs');
+    const { resolve } = await import('node:path');
+    const root = cwd ?? process.cwd();
+    const issues = [];
+    const catalogByCommand = new Map();
+    for (const e of COMMAND_CATALOG)
+        catalogByCommand.set(e.command, e);
+    // (a) replacedBy / preferredCommand pointers must resolve to a real
+    // catalog command — these are structural and rise to error.
+    for (const e of COMMAND_CATALOG) {
+        if (e.replacedBy) {
+            const target = stripShrkPrefix(e.replacedBy);
+            if (!targetMatchesCatalog(target, catalogByCommand)) {
+                issues.push({
+                    code: 'replaced-by-missing',
+                    severity: 'error',
+                    command: e.command,
+                    message: `replacedBy "${e.replacedBy}" does not resolve to a catalog command`,
+                });
+            }
+        }
+        if (e.preferredCommand) {
+            const target = stripShrkPrefix(e.preferredCommand);
+            if (!targetMatchesCatalog(target, catalogByCommand)) {
+                issues.push({
+                    code: 'preferred-command-missing',
+                    severity: 'warning',
+                    command: e.command,
+                    message: `preferredCommand "${e.preferredCommand}" does not resolve to a catalog command`,
+                });
+            }
+        }
+    }
+    // (b) walk DOCS_TO_CHECK, extract `shrk <verb>` references, warn on stale
+    // or deprecated targets.
+    let filesChecked = 0;
+    for (const rel of DOCS_TO_CHECK) {
+        const abs = resolve(root, rel);
+        if (!existsSync(abs))
+            continue;
+        filesChecked += 1;
+        const content = readFileSync(abs, 'utf8');
+        const refs = extractShrkRefs(content);
+        for (const ref of refs) {
+            const stripped = stripShrkPrefix(ref);
+            const match = matchCatalogEntry(stripped, catalogByCommand);
+            if (!match) {
+                issues.push({
+                    code: 'stale-doc-reference',
+                    severity: 'info',
+                    file: rel,
+                    command: ref,
+                    message: `${rel} references \`shrk ${stripped}\` but no catalog command matches`,
+                });
+                continue;
+            }
+            const lc = commandLifecycle(match);
+            if (lc === CommandLifecycle.Deprecated || lc === CommandLifecycle.Retired) {
+                const r46 = R46_OVERLAY[match.command];
+                const replacement = match.replacedBy ?? match.preferredCommand ?? r46?.replacedBy ?? '(no replacement)';
+                issues.push({
+                    code: 'doc-promotes-deprecated',
+                    severity: 'warning',
+                    file: rel,
+                    command: match.command,
+                    message: `${rel} promotes deprecated command \`shrk ${match.command}\` — prefer \`${replacement}\``,
+                });
+            }
+        }
+    }
+    const errors = issues.filter((i) => i.severity === 'error').length;
+    const warnings = issues.filter((i) => i.severity === 'warning').length;
+    const info = issues.filter((i) => i.severity === 'info').length;
+    return {
+        schema: 'sharkcraft.commands-docs-check/v1',
+        passed: errors === 0,
+        filesChecked,
+        issues,
+        summary: { errors, warnings, info },
+    };
+}
+function stripShrkPrefix(s) {
+    return s.replace(/^shrk\s+/, '').replace(/[`"<]+/g, '').replace(/[`">]+$/, '').trim();
+}
+function targetMatchesCatalog(target, byCommand) {
+    return matchCatalogEntry(target, byCommand) !== undefined;
+}
+function matchCatalogEntry(target, byCommand) {
+    const head = target.split(/\s+/).filter((t) => !t.startsWith('<')).join(' ').trim();
+    if (!head)
+        return undefined;
+    const direct = byCommand.get(head);
+    if (direct)
+        return direct;
+    const parts = head.split(/\s+/);
+    while (parts.length > 0) {
+        const joined = parts.join(' ');
+        const m = byCommand.get(joined);
+        if (m)
+            return m;
+        // Group prefix match (e.g. `report site` → any `report …` catalog entry).
+        const groupHit = [...byCommand.values()].find((e) => e.command.startsWith(joined + ' '));
+        if (groupHit)
+            return groupHit;
+        parts.pop();
+    }
+    return undefined;
+}
+const SHRK_REF_RE = /shrk\s+([a-z][a-z0-9_\-]*(?:\s+[a-z][a-z0-9_\-]*)*)/gi;
+function extractShrkRefs(content) {
+    const out = new Set();
+    let match;
+    SHRK_REF_RE.lastIndex = 0;
+    while ((match = SHRK_REF_RE.exec(content)) !== null) {
+        const candidate = match[1].trim();
+        if (!candidate)
+            continue;
+        // Skip references to flags / quoted tokens — they're not real commands.
+        if (candidate.startsWith('-'))
+            continue;
+        out.add(candidate);
+    }
+    return [...out];
+}
+async function runCommandsDocsCheck(args) {
+    const report = await buildDocsCheckReport();
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson(report) + '\n');
+        return report.passed ? 0 : 1;
+    }
+    process.stdout.write(header('Commands docs-check'));
+    process.stdout.write(`  files ${report.filesChecked}  errors ${report.summary.errors}  warnings ${report.summary.warnings}  info ${report.summary.info}\n\n`);
+    if (report.issues.length === 0) {
+        process.stdout.write('No docs drift detected. ✓\n');
+        return 0;
+    }
+    for (const i of report.issues) {
+        const tag = `[${i.severity.padEnd(8)}] ${i.code.padEnd(28)}`;
+        const file = i.file ? ` ${i.file}:` : '';
+        process.stdout.write(`  ${tag}${file} ${i.message}\n`);
+    }
+    return report.passed ? 0 : 1;
+}
+function printTree(args) {
+    if (flagBool(args, 'json')) {
+        const tree = {};
+        for (const e of COMMAND_CATALOG) {
+            const top = e.command.split(' ')[0];
+            tree[top] = tree[top] ?? [];
+            tree[top].push(e);
+        }
+        process.stdout.write(asJson(tree) + '\n');
+        return 0;
+    }
+    const seen = new Set();
+    process.stdout.write(header('Command tree'));
+    for (const e of COMMAND_CATALOG) {
+        const top = e.command.split(' ')[0];
+        if (!seen.has(top)) {
+            process.stdout.write(`\n${top}\n`);
+            seen.add(top);
+        }
+        if (e.command !== top) {
+            process.stdout.write(`  • ${e.command}\n`);
+        }
+        else {
+            process.stdout.write(`  • (top-level)  ${e.description}\n`);
+        }
+    }
+    return 0;
+}
+function safetyTag(level) {
+    switch (level) {
+        case SafetyLevel.ReadOnly:
+            return 'READ ';
+        case SafetyLevel.WritesSessionOnly:
+            return 'SESS ';
+        case SafetyLevel.WritesDraftsOnly:
+            return 'DRAFT';
+        case SafetyLevel.WritesSource:
+            return 'WRITE';
+        case SafetyLevel.RunsShell:
+            return 'SHELL';
+        case SafetyLevel.RequiresReview:
+            return 'REVW ';
+    }
+}