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

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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.8",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -47,25 +47,25 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.7",
-    "@shrkcrft/config": "^0.1.0-alpha.7",
-    "@shrkcrft/workspace": "^0.1.0-alpha.7",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.7",
-    "@shrkcrft/context": "^0.1.0-alpha.7",
-    "@shrkcrft/rules": "^0.1.0-alpha.7",
-    "@shrkcrft/paths": "^0.1.0-alpha.7",
-    "@shrkcrft/templates": "^0.1.0-alpha.7",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.7",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.7",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.7",
-    "@shrkcrft/presets": "^0.1.0-alpha.7",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.7",
-    "@shrkcrft/generator": "^0.1.0-alpha.7",
-    "@shrkcrft/importer": "^0.1.0-alpha.7",
-    "@shrkcrft/inspector": "^0.1.0-alpha.7",
-    "@shrkcrft/ai": "^0.1.0-alpha.7",
-    "@shrkcrft/shared": "^0.1.0-alpha.7",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.7"
+    "@shrkcrft/core": "^0.1.0-alpha.8",
+    "@shrkcrft/config": "^0.1.0-alpha.8",
+    "@shrkcrft/workspace": "^0.1.0-alpha.8",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.8",
+    "@shrkcrft/context": "^0.1.0-alpha.8",
+    "@shrkcrft/rules": "^0.1.0-alpha.8",
+    "@shrkcrft/paths": "^0.1.0-alpha.8",
+    "@shrkcrft/templates": "^0.1.0-alpha.8",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.8",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.8",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.8",
+    "@shrkcrft/presets": "^0.1.0-alpha.8",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.8",
+    "@shrkcrft/generator": "^0.1.0-alpha.8",
+    "@shrkcrft/importer": "^0.1.0-alpha.8",
+    "@shrkcrft/inspector": "^0.1.0-alpha.8",
+    "@shrkcrft/ai": "^0.1.0-alpha.8",
+    "@shrkcrft/shared": "^0.1.0-alpha.8",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.8"
   },
   "publishConfig": {
     "access": "public"

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

@@ -1,11 +0,0 @@
-import { type ICommandHandler } from '../command-registry.js';
-export declare const pluginRenameCommand: ICommandHandler;
-export declare const pluginRemoveCommand: ICommandHandler;
-export declare const pluginLifecycleListCommand: ICommandHandler;
-export declare const pluginLifecycleInspectCommand: ICommandHandler;
-export declare const pluginLifecycleProfilesCommand: ICommandHandler;
-export declare const pluginLifecycleProfileCommand: ICommandHandler;
-export declare const pluginLifecycleDoctorCommand: ICommandHandler;
-export declare const pluginLifecycleCommand: ICommandHandler;
-export declare const pluginCommand: ICommandHandler;
-//# sourceMappingURL=plugin.command.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"plugin.command.d.ts","sourceRoot":"","sources":["../../src/commands/plugin.command.ts"],"names":[],"mappings":"AA+BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2BhC,eAAO,MAAM,mBAAmB,EAAE,eAmEjC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAkEjC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAwBxC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAsC3C,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,eA4B5C,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAkD3C,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eA0C1C,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAepC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,eAc3B,CAAC"}