@shrkcrft/cli 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/export/claude-commands-export.js

@@ -0,0 +1,276 @@
+/**
+ * `.claude/commands/` generator — emits per-project slash commands
+ * for Claude Code. Companion to `claude-skill` export, but with a
+ * different inversion semantics:
+ *
+ *   - **claude-skill** loads rules into Claude's prompt automatically
+ *     based on description match. Passive — Claude reads the rules.
+ *   - **claude-commands** registers slash commands the USER invokes
+ *     (`/new-service`, `/check-changes`). Active — the command IS the
+ *     recipe; Claude follows it step-by-step.
+ *
+ * Generated commands fall into two buckets:
+ *
+ * **Static commands** (always present, project-agnostic recipes):
+ *   - `/follow-shrk` — short reminder of the apply-gate flow.
+ *   - `/check-changes` — runs `shrk check boundaries --changed-only`
+ *     scoped to the current diff and reports back.
+ *   - `/shrk-brief` — runs `shrk brief` and uses the output for the
+ *     current task.
+ *   - `/explain-file <path>` — per-file rules / paths / boundary
+ *     lookup (pairs with `shrk advise <path>` from Phase 3).
+ *
+ * **Per-template commands** (one per id in `sharkcraft/templates.ts`):
+ *   - `/new-<template-id>` — Claude runs `shrk gen <template-id>
+ *     <name> --dry-run --save-plan ...`, reviews the plan, and
+ *     applies via `shrk apply ... --verify-signature --validate`.
+ *
+ * Generated files are self-contained markdown — no `@shrkcrft/*`
+ * imports, no shell expansions. Each one is a complete "recipe in a
+ * file" that Claude Code reads when the user types the slash command.
+ */
+// ─── Static commands (always emitted) ────────────────────────────────────────
+const STATIC_FOLLOW_SHRK = `---
+description: Reminder of the shrk apply-gate flow for this project. Use when generating or modifying code so the change passes the same boundary / validation gates the project CI uses.
+---
+
+# Follow the shrk apply-gate flow
+
+This repo uses [SharkCraft](https://github.com/shrkcrft/sharkcraft) as the
+gate for AI-written code. Skip the gate and CI will fail with the same
+errors anyway — save the round-trip.
+
+## The loop
+
+1. **Get focused context first.**
+   - Run: \`shrk task "<one-sentence task>"\` for a task packet (relevant rules + templates + verification commands).
+   - Or: \`shrk brief\` for the single-page project brief.
+
+2. **Scaffold via a template (not freehand).**
+   - List options: \`shrk templates list\`.
+   - Dry-run + save plan: \`shrk gen <template-id> <name> --dry-run --save-plan /tmp/plan.json\`.
+
+3. **Apply the plan through the CLI.**
+   - \`shrk apply /tmp/plan.json --verify-signature --validate\`.
+   - Never write files directly through MCP — MCP is read-only in this repo.
+
+4. **Verify before declaring done.**
+   - \`shrk check boundaries --changed-only\` — fails if the diff broke any layer rule.
+   - \`shrk check imports\` — fails on lazy requires / cross-package deep imports.
+   - Project verification commands (from \`shrk task\`'s \`actionHints.verificationCommands\`).
+
+## When this loop doesn't apply
+
+- Tiny changes that don't touch source files (docs, comments).
+- Read-only investigations.
+- Anything where shrk would clearly be in the way.
+
+In all other cases: **follow the loop**. The gates are short; the rework if you skip them is long.
+`;
+const STATIC_CHECK_CHANGES = `---
+description: Run shrk's boundary + import-hygiene checks on the current git diff. Use after making any file change to confirm the change didn't violate the project's architecture rules before declaring the task done.
+---
+
+# Check the current diff for boundary violations
+
+Run the diff-scoped boundary check:
+
+\`\`\`bash
+shrk check boundaries --changed-only
+\`\`\`
+
+Run the import-hygiene check on the changed files:
+
+\`\`\`bash
+shrk check imports
+\`\`\`
+
+## Interpreting the output
+
+- **Exit 0, "0 violations":** safe to declare done.
+- **Exit non-zero with violations listed:** fix each violation before continuing. Each violation has a \`suggestedFix\` line — apply it.
+- **A violation on a file you didn't change:** that's a pre-existing violation in the repo. Ignore it; the \`--changed-only\` filter only fails on violations your diff introduced.
+
+If the violations look like false positives, consult \`sharkcraft/boundaries.ts\` (the rule definitions) — don't disable them ad-hoc.
+`;
+const STATIC_SHRK_BRIEF = `---
+description: Pull shrk's single-page project brief — focused rules, paths, verification commands. Use when starting work in this codebase so you have the project's actual conventions in context before writing any code.
+---
+
+# Pull the shrk brief for this project
+
+Run the project brief:
+
+\`\`\`bash
+shrk brief
+\`\`\`
+
+This returns a compact markdown brief covering:
+- Project overview (name, frameworks, package manager).
+- Top rules that apply to code generation in this repo.
+- Path conventions (where different file types belong).
+- Action hints (commands, MCP tools, verification commands).
+- Forbidden actions (what NOT to do).
+
+For a per-task version (only the rules + paths + templates relevant to one task):
+
+\`\`\`bash
+shrk task "<one-sentence task description>"
+\`\`\`
+
+Both are read-only — no files are touched. Use the output to shape your plan before making any changes.
+`;
+const STATIC_EXPLAIN_FILE = `---
+description: Look up the rules, path conventions, and boundary rules that apply to a specific file in this codebase. Use before editing an unfamiliar file so you follow the project's per-area conventions instead of generic patterns.
+---
+
+# Explain what applies to a file in this codebase
+
+For a given file path (e.g. \`apps/users/src/profile.service.ts\`):
+
+\`\`\`bash
+shrk why <file-path>
+\`\`\`
+
+Returns:
+- Which package / layer the file belongs to.
+- Which path conventions apply (e.g. "services live in \`apps/<x>/src/services/\`").
+- Which rules are scoped to this file's path.
+- Which boundary rules constrain this file's imports.
+- Cross-references to related knowledge entries.
+
+Use this *before* editing. The output is the project's actual conventions for that area, not your guess based on the file's content.
+`;
+// ─── Per-template command generator ──────────────────────────────────────────
+/**
+ * Slugify a template id into a slash-command name. Template ids
+ * conventionally look like `typescript.service`; the slash command is
+ * `new-typescript-service` (or `new-service` if the segment after the
+ * dot is unique and shorter).
+ */
+function templateSlash(templateId) {
+    // Use the LAST dot-separated segment as the primary name —
+    // `typescript.service` → `new-service`. Falls back to the full id
+    // when there's no dot or the segment is too generic (single char).
+    const parts = templateId.split('.');
+    const tail = parts[parts.length - 1] ?? templateId;
+    const safeName = tail.length >= 3 ? tail : templateId.replace(/\./g, '-');
+    return `new-${safeName}`
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function templateCommandBody(template) {
+    const displayName = template.name ?? template.id;
+    const description = template.description
+        ? template.description.replace(/\s+/g, ' ').trim()
+        : `Scaffold a new ${displayName} using the project's actual template (\`${template.id}\`). Follows the shrk plan → apply → validate flow.`;
+    return `---
+description: ${JSON.stringify(description)}
+---
+
+# /${templateSlash(template.id)} — scaffold ${displayName}
+
+This command scaffolds a new ${displayName} using the project's actual template
+defined in \`sharkcraft/templates.ts\`. The template encodes this repo's
+conventions for path, naming, and structure — the result will match how
+the rest of the codebase is organized, not generic patterns.
+
+## The flow
+
+When the user invokes \`/${templateSlash(template.id)} <name>\`:
+
+1. **Generate a plan (no writes yet):**
+   \`\`\`bash
+   shrk gen ${template.id} <name> --dry-run --save-plan /tmp/${templateSlash(template.id)}.plan.json
+   \`\`\`
+
+2. **Read the plan back** from \`/tmp/${templateSlash(template.id)}.plan.json\` and show the user which files will be created.
+
+3. **Confirm.** Wait for the user to approve. If they want changes, adjust the plan or re-run \`shrk gen\` with different flags.
+
+4. **Apply through the validated CLI path:**
+   \`\`\`bash
+   shrk apply /tmp/${templateSlash(template.id)}.plan.json --verify-signature --validate
+   \`\`\`
+
+5. **Verify** the diff didn't break any boundary rules:
+   \`\`\`bash
+   shrk check boundaries --changed-only
+   \`\`\`
+
+## If the template doesn't fit
+
+If the user's request doesn't match the \`${template.id}\` template
+shape, fall back to:
+
+- \`shrk templates list\` — see all available templates.
+- \`shrk gen <other-template> <name> --dry-run\` — try a different template.
+- Hand-author only as last resort, and run \`/check-changes\` after.
+
+The whole point of using the template is consistency with the rest of
+this codebase. Skipping it means the new code will look different from
+what's already there.
+`;
+}
+/**
+ * Build the full set of `.claude/commands/*.md` files for a project.
+ *
+ * Pure — caller writes the bytes. Same shape as the `synthesize-*`
+ * functions in this codebase: input inspection → output file list.
+ */
+export function buildClaudeCommands(inspection, options = {}) {
+    const files = [];
+    files.push({
+        path: '.claude/commands/follow-shrk.md',
+        slash: 'follow-shrk',
+        source: 'static',
+        content: STATIC_FOLLOW_SHRK,
+    });
+    files.push({
+        path: '.claude/commands/check-changes.md',
+        slash: 'check-changes',
+        source: 'static',
+        content: STATIC_CHECK_CHANGES,
+    });
+    files.push({
+        path: '.claude/commands/shrk-brief.md',
+        slash: 'shrk-brief',
+        source: 'static',
+        content: STATIC_SHRK_BRIEF,
+    });
+    files.push({
+        path: '.claude/commands/explain-file.md',
+        slash: 'explain-file',
+        source: 'static',
+        content: STATIC_EXPLAIN_FILE,
+    });
+    // Per-template commands — bounded so a pack with 50 templates
+    // doesn't dump 50 slash commands into the user's palette. Sorted
+    // by id for deterministic emit order.
+    const cap = options.maxTemplateCommands ?? 20;
+    const templates = [...inspection.templates].sort((a, b) => a.id.localeCompare(b.id));
+    const seenSlash = new Set(files.map((f) => f.slash));
+    for (const t of templates) {
+        if (files.filter((f) => f.source === 'template').length >= cap)
+            break;
+        let slash = templateSlash(t.id);
+        if (seenSlash.has(slash)) {
+            // Two templates with the same tail (e.g. `ts.service` and
+            // `py.service` both → `new-service`) — fall back to the full id
+            // to disambiguate the second one.
+            slash = `new-${t.id.replace(/\./g, '-').toLowerCase()}`;
+            if (seenSlash.has(slash))
+                continue;
+        }
+        seenSlash.add(slash);
+        files.push({
+            path: `.claude/commands/${slash}.md`,
+            slash,
+            source: 'template',
+            content: templateCommandBody(t),
+        });
+    }
+    return { files };
+}

package/dist/export/export-formats.d.ts

@@ -1,5 +1,5 @@
 import type { ISharkcraftInspection } from '@shrkcrft/inspector';
-export type ExportFormat = 'agents-md' | 'claude-md' | 'cursor-rules' | 'copilot-instructions';
+export type ExportFormat = 'agents-md' | 'claude-md' | 'claude-skill' | 'cursor-rules' | 'copilot-instructions';
 export interface ExportOptions {
     format: ExportFormat;
     /** Optional task to scope the export. */

package/dist/export/export-formats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export-formats.d.ts","sourceRoot":"","sources":["../../src/export/export-formats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,cAAc,GACd,sBAAsB,CAAC;AAE3B,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAqHD,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,aAAa,GACrB,YAAY,CAsBd;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAOnE;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,YAAY,EAKpD,CAAC"}
+{"version":3,"file":"export-formats.d.ts","sourceRoot":"","sources":["../../src/export/export-formats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,cAAc,GACd,cAAc,GACd,sBAAsB,CAAC;AAE3B,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAqPD,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,aAAa,GACrB,YAAY,CAmCd;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAQnE;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,YAAY,EAMpD,CAAC"}

package/dist/export/export-formats.js

@@ -1,11 +1,28 @@
 import { aggregateActionHints, KnowledgeType } from '@shrkcrft/knowledge';
 import { priorityWeight } from '@shrkcrft/knowledge';
-const DEFAULT_OUTPUT_PATH = {
-    'agents-md': 'AGENTS.md',
-    'claude-md': 'CLAUDE.md',
-    'cursor-rules': '.cursor/rules/sharkcraft.mdc',
-    'copilot-instructions': '.github/copilot-instructions.md',
-};
+function projectSlug(name) {
+    if (!name)
+        return 'project';
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48) || 'project');
+}
+function defaultOutputFor(format, inspection) {
+    switch (format) {
+        case 'agents-md':
+            return 'AGENTS.md';
+        case 'claude-md':
+            return 'CLAUDE.md';
+        case 'claude-skill':
+            return `.claude/skills/${projectSlug(inspection.config?.projectName)}/SKILL.md`;
+        case 'cursor-rules':
+            return '.cursor/rules/sharkcraft.mdc';
+        case 'copilot-instructions':
+            return '.github/copilot-instructions.md';
+    }
+}
 function selectTopByPriority(entries, limit) {
     return [...entries]
         .sort((a, b) => priorityWeight(b.priority) - priorityWeight(a.priority))
@@ -100,23 +117,131 @@ function renderBody(inspection, options) {
     }
     return sections.join('\n\n');
 }
+/**
+ * Filter rules / paths to the high-signal subset for an inlined skill.
+ *
+ * Every rule the skill carries pays in Claude's context every time the
+ * skill is loaded. Low-priority items dilute the signal of the
+ * load-bearing ones (`Critical` safety + `High` architecture). We keep
+ * only Critical + High by default, falling back to "all" only if the
+ * filtered list is empty (e.g. a repo with no high-priority entries
+ * yet shouldn't ship an empty skill).
+ */
+function filterHighSignal(entries) {
+    const filtered = entries.filter((e) => {
+        const p = String(e.priority).toLowerCase();
+        return p === 'critical' || p === 'high';
+    });
+    return filtered.length > 0 ? filtered : [...entries];
+}
+/**
+ * Render the body in tight, decision-driving form for the Claude Code
+ * Skill format. Skills get loaded into Claude's prompt when the skill's
+ * `description` matches the current task, so the body must be short and
+ * directly actionable — no preamble, no metadata about generation, no
+ * pipelines (Claude can run `shrk task` for those when needed).
+ *
+ * Sections:
+ *   1. Where files belong (path conventions, top N) — most-leveraged signal.
+ *   2. Rules to follow (Critical + High only) — pads context otherwise.
+ *   3. Do / Don't — forbidden actions and verification commands.
+ *   4. How to write code in this repo — the gen → review → apply loop
+ *      verbatim, since Claude needs to know shrk is the write path.
+ */
+function renderSkillBody(inspection, options) {
+    const { rules: allRules, paths: allPaths } = gatherRulesAndPaths(inspection, {
+        ...options,
+        // Pull more upfront, then filter down to high-signal — keeps the
+        // softcap-at-15 default but the inlined skill stays terse.
+        maxRules: options.maxRules ?? 24,
+        maxPaths: options.maxPaths ?? 18,
+    });
+    // Skills are inlined into the prompt — every entry costs Claude
+    // context. Only ship the items the user said are load-bearing.
+    const rules = filterHighSignal(allRules).slice(0, options.maxRules ?? 12);
+    const paths = filterHighSignal(allPaths).slice(0, options.maxPaths ?? 10);
+    const sections = [];
+    if (inspection.config?.description) {
+        sections.push(`## About this codebase\n\n${inspection.config.description}`);
+    }
+    const pathsBody = renderPathsSection(paths);
+    if (pathsBody) {
+        sections.push(`## Where files belong\n\nWhen creating or moving a file, place it according to these conventions:\n\n${pathsBody}`);
+    }
+    const rulesBody = renderRulesSection(rules);
+    if (rulesBody) {
+        sections.push(`## Rules this codebase follows\n\nApply these whenever you generate, modify, or review code:\n\n${rulesBody}`);
+    }
+    const agg = aggregateActionHints(inspection.knowledgeEntries);
+    const doDont = [];
+    if (agg.forbiddenActions.length) {
+        doDont.push('**Do not:**');
+        for (const f of agg.forbiddenActions.slice(0, 8))
+            doDont.push(`- ${f}`);
+        doDont.push('');
+    }
+    if (agg.verificationCommands.length) {
+        doDont.push('**Verify changes with:**');
+        for (const c of agg.verificationCommands.slice(0, 6))
+            doDont.push(`- \`${c}\``);
+    }
+    if (doDont.length) {
+        sections.push(`## Do / Don't\n\n${doDont.join('\n').trim()}`);
+    }
+    sections.push(`## How to write code in this repo\n\n` +
+        `This repository uses [SharkCraft](https://github.com/shrkcrft/sharkcraft) to gate writes — the CLI is the only write path, and writes go through a plan → review → apply loop.\n\n` +
+        `1. **Get a task packet** before non-trivial work: \`shrk task "<one-sentence task>"\` returns the focused rules, paths, templates, and verification commands for that task.\n` +
+        `2. **Scaffold via templates** instead of writing files freehand: \`shrk gen <template-id> <name> --dry-run --save-plan plan.json\` produces a signed plan.\n` +
+        `3. **Apply the plan** through the CLI: \`shrk apply plan.json --verify-signature\` — never write through MCP.\n` +
+        `4. **Check the result**: \`shrk check boundaries\` + the verification commands listed above.\n\n` +
+        `For ad-hoc questions about the codebase, query the MCP server (\`shrk mcp serve\`) or run \`shrk context --task "<query>"\` for token-budgeted context.`);
+    return sections.join('\n\n');
+}
+/**
+ * Build the YAML frontmatter for a Claude Code Skill. The `description`
+ * field is what Claude uses to decide whether to load this skill — keep
+ * it specific (project name + what's covered) so it doesn't trigger on
+ * unrelated tasks.
+ */
+function renderSkillFrontmatter(inspection) {
+    const slug = projectSlug(inspection.config?.projectName);
+    const projectName = inspection.config?.projectName ?? slug;
+    const description = `Codebase rules, path conventions, and review gates for ${projectName}. ` +
+        `Use this skill whenever generating, modifying, or reviewing code in this repository — ` +
+        `it tells you the per-file path conventions, the architecture boundaries, the verification commands, ` +
+        `and the safe write path (CLI plan → review → apply).`;
+    return `---\nname: ${slug}\ndescription: ${JSON.stringify(description)}\n---`;
+}
 export function renderExport(inspection, options) {
-    const body = renderBody(inspection, options);
-    const suggestedPath = DEFAULT_OUTPUT_PATH[options.format];
+    const suggestedPath = defaultOutputFor(options.format, inspection);
     let content = '';
     switch (options.format) {
-        case 'agents-md':
+        case 'agents-md': {
+            const body = renderBody(inspection, options);
             content = `# Agents Guide\n\n${PREAMBLE}\n\n${body}\n`;
             break;
-        case 'claude-md':
+        }
+        case 'claude-md': {
+            const body = renderBody(inspection, options);
             content = `# CLAUDE.md\n\n${PREAMBLE}\n\nThis file is read by Claude Code (claude.ai/code) at session start. Treat it as a compatibility view of the project's SharkCraft knowledge — use the MCP server (\`shrk mcp serve\`) for the live, queryable source of truth.\n\n${body}\n`;
             break;
+        }
+        case 'claude-skill': {
+            // Claude Code Skill: YAML frontmatter declares when to load this,
+            // body is tight decision-driving content. No preamble, no boilerplate
+            // — every token in here costs Claude context when loaded.
+            const frontmatter = renderSkillFrontmatter(inspection);
+            const projectName = inspection.config?.projectName ?? 'this codebase';
+            const body = renderSkillBody(inspection, options);
+            content = `${frontmatter}\n\n# ${projectName} — codebase guide\n\n${body}\n`;
+            break;
+        }
         case 'cursor-rules':
             // Cursor MDC frontmatter: leave alwaysApply off so the user can tune.
-            content = `---\ndescription: SharkCraft project rules (auto-generated)\nalwaysApply: false\n---\n\n${PREAMBLE}\n\n${body}\n`;
+            content = `---\ndescription: SharkCraft project rules (auto-generated)\nalwaysApply: false\n---\n\n${PREAMBLE}\n\n${renderBody(inspection, options)}\n`;
             break;
         case 'copilot-instructions':
-            content = `# Copilot instructions\n\n${PREAMBLE}\n\n${body}\n`;
+            content = `# Copilot instructions\n\n${PREAMBLE}\n\n${renderBody(inspection, options)}\n`;
             break;
     }
     return { format: options.format, suggestedPath, content };
@@ -124,12 +249,14 @@ export function renderExport(inspection, options) {
 export function isExportFormat(value) {
     return (value === 'agents-md' ||
         value === 'claude-md' ||
+        value === 'claude-skill' ||
         value === 'cursor-rules' ||
         value === 'copilot-instructions');
 }
 export const ALL_EXPORT_FORMATS = Object.freeze([
     'agents-md',
     'claude-md',
+    'claude-skill',
     'cursor-rules',
     'copilot-instructions',
 ]);

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EACL,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAyV/B,wBAAgB,aAAa,IAAI,eAAe,CA2V/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AA6FD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EACL,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAyV/B,wBAAgB,aAAa,IAAI,eAAe,CA2V/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAkGD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}

package/dist/main.js

@@ -20,6 +20,7 @@ import { presetsListCommand, presetsGetCommand, presetsExplainCommand, presetsRe
 import { taskCommand } from "./commands/task.command.js";
 import { preflightCommand } from "./commands/preflight.command.js";
 import { checkCommand } from "./commands/check.command.js";
+import { diffCheckCommand } from "./commands/diff-check.command.js";
 import { driftCommand } from "./commands/drift.command.js";
 import { graphCommand } from "./commands/graph.command.js";
 import { coverageCommand } from "./commands/coverage.command.js";
@@ -56,7 +57,6 @@ import { biomeCommand } from "./commands/biome.command.js";
 import { ideCommand } from "./commands/ide.command.js";
 import { makeCommandsCommand } from "./commands/commands.command.js";
 import { safetyCommand } from "./commands/safety.command.js";
-import { pluginCommand } from "./commands/plugin.command.js";
 import { profilesCommand } from "./commands/profiles.command.js";
 import { auditProjectCouplingCommand } from "./commands/audit.command.js";
 import { conventionsCommand } from "./commands/conventions.command.js";
@@ -162,6 +162,7 @@ export function buildRegistry() {
     registry.register(taskCommand);
     registry.register(explainCommand);
     registry.register(checkCommand);
+    registry.register(diffCheckCommand);
     // changed-only preflight orchestrator.
     registry.register(preflightCommand);
     registry.register(driftCommand);
@@ -192,7 +193,6 @@ export function buildRegistry() {
     registry.register(eslintCommand);
     registry.register(biomeCommand);
     registry.register(ideCommand);
-    registry.register(pluginCommand);
     registry.register(profilesCommand);
     registry.registerSubcommand('audit', auditProjectCouplingCommand);
     registry.register(conventionsCommand);
@@ -506,7 +506,14 @@ async function runCliInner(argv) {
         return registry.get('help').run(parseArgs([], { globalCwd }));
     }
     if (first === '--full-help') {
-        return registry.get('help').run(parseArgs(['--full'], { globalCwd }));
+        // Pass through `--all` (catalog dump) and `--verbose` if the user
+        // included them after `--full-help`.
+        const extra = [];
+        if (argv.includes('--all'))
+            extra.push('--all');
+        if (argv.includes('--verbose') || argv.includes('-v'))
+            extra.push('--verbose');
+        return registry.get('help').run(parseArgs(['--full', ...extra], { globalCwd }));
     }
     if (first === '--version' || first === '-v') {
         return registry.get('version').run(parseArgs([], { globalCwd }));
@@ -550,7 +557,7 @@ async function runCliInner(argv) {
         return 2;
     }
     const attempted = probe.slice(0, 2).join(' ');
-    process.stderr.write(`Unknown command: ${attempted}\n`);
+    process.stderr.write(`shrk doesn't have a \`${attempted}\` command.\n`);
     printDidYouMean(attempted);
     return 2;
 }
@@ -658,21 +665,107 @@ async function checkSurfaceGate(matchedPath, cwd) {
         return null;
     }
 }
+// Score thresholds for did-you-mean output. Picked from observed
+// scoring: 1-char-off typos score 8+ on plain commands; 3-4-char-off
+// near-misses score ~5; loose / token-overlap matches score 1-3.
+// Junk matches (frobnicate → bundle diff) can score 8 too because of
+// token overlap, so we sharpen by also requiring the suggestion's
+// command name to be reasonably close in length to the attempt.
+const SUGGEST_CONFIDENT_SCORE = 7;
+const SUGGEST_VISIBLE_SCORE = 3;
+function reorderCandidates(attempted, candidates) {
+    // Stable sort: higher score first, then shorter command (more likely
+    // canonical), then lexicographic. The base suggester returns ties in
+    // arbitrary order — this makes the top suggestion more predictable.
+    const ranked = [...candidates];
+    ranked.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (a.command.length !== b.command.length) {
+            return a.command.length - b.command.length;
+        }
+        return a.command < b.command ? -1 : a.command > b.command ? 1 : 0;
+    });
+    return ranked;
+}
+/** Edit distance (Levenshtein). Used to gate did-you-mean confidence. */
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = new Array(n + 1);
+    for (let j = 0; j <= n; j += 1)
+        dp[j] = j;
+    for (let i = 1; i <= m; i += 1) {
+        let prev = dp[0];
+        dp[0] = i;
+        for (let j = 1; j <= n; j += 1) {
+            const tmp = dp[j];
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + cost);
+            prev = tmp;
+        }
+    }
+    return dp[n];
+}
+/**
+ * Suggestion is "confident" when the candidate's top token is close
+ * to the attempt in edit-distance terms — `doctorz`→`doctor` (1 edit)
+ * or `inspct`→`inspect` (1 edit) qualify; `frobnicate`→`bundle` (10
+ * edits) does not, even when the suggester scores them similarly
+ * because of incidental token overlap in descriptions.
+ *
+ * Threshold: edit distance ≤ max(1, attempt.length / 4) AND raw score
+ * meets `SUGGEST_VISIBLE_SCORE`. This catches typical fingers-on-keys
+ * typos while rejecting "you typed something totally different."
+ */
+function isConfidentMatch(attempted, suggestion) {
+    if (suggestion.score < SUGGEST_VISIBLE_SCORE)
+        return false;
+    const lower = attempted.toLowerCase();
+    const head = (suggestion.command.split(/\s+/)[0] ?? suggestion.command).toLowerCase();
+    const dist = editDistance(lower, head);
+    const tolerance = Math.max(1, Math.floor(lower.length / 4));
+    return dist <= tolerance;
+}
 function printDidYouMean(attempted) {
-    const candidates = suggestDidYouMean(COMMAND_CATALOG, [attempted], 3);
-    if (candidates.length === 0) {
-        process.stderr.write("Tip: run `shrk commands suggest \"<partial>\"` or `shrk help` to discover commands.\n");
+    const rawCandidates = suggestDidYouMean(COMMAND_CATALOG, [attempted], 5);
+    const reordered = reorderCandidates(attempted, rawCandidates).filter((c) => c.score >= SUGGEST_VISIBLE_SCORE);
+    if (reordered.length === 0) {
+        process.stderr.write('Run `shrk help` to see the curated commands, or `shrk --full-help` for the full catalog.\n');
+        const footer = errorFooterFor('unknown-command', { task: attempted });
+        if (footer)
+            process.stderr.write(renderErrorFooter(footer));
+        return;
+    }
+    // Confident single-match path: surface ONE suggestion clearly.
+    const top = reordered[0];
+    if (isConfidentMatch(attempted, top)) {
+        process.stderr.write(`Did you mean \`shrk ${top.command}\`?\n`);
+        process.stderr.write(`  ${top.description}\n`);
+        // Second-tier suggestions only if they're also strong.
+        const others = reordered.slice(1, 3).filter((c) => isConfidentMatch(attempted, c));
+        if (others.length > 0) {
+            process.stderr.write('Other close matches:\n');
+            for (const c of others) {
+                process.stderr.write(`  shrk ${c.command} — ${c.description}\n`);
+            }
+        }
         const footer = errorFooterFor('unknown-command', { task: attempted });
         if (footer)
             process.stderr.write(renderErrorFooter(footer));
         return;
     }
-    process.stderr.write('Did you mean:\n');
-    for (const c of candidates) {
+    // Low-confidence: show up to 3 as "closest matches", honest about
+    // not knowing which is right.
+    process.stderr.write('Closest matches in the catalog:\n');
+    for (const c of reordered.slice(0, 3)) {
         process.stderr.write(`  shrk ${c.command} — ${c.description}\n`);
     }
-    // append the standardised next-command footer so the user
-    // always has a deterministic exit route.
+    process.stderr.write("If none of those look right, run `shrk help` or `shrk \"<task>\"` to route as a free-form task.\n");
     const footer = errorFooterFor('unknown-command', { task: attempted });
     if (footer)
         process.stderr.write(renderErrorFooter(footer));