@shrkcrft/cli 0.1.0-alpha.2

package/dist/commands/help.command.js

@@ -0,0 +1,127 @@
+import { header } from "../output/format-output.js";
+/**
+ * Short product start screen for bare `shrk` / `shrk --help`. Pruned
+ * to the core tier set; extended verbs live one link away via
+ * `shrk surface list`.
+ *
+ * Returns the lines (without trailing newline). Pulled into a function
+ * so tests can assert on the structure without grepping stdout.
+ */
+export function renderStartScreen() {
+    const lines = [];
+    lines.push('SharkCraft CLI — deterministic, local-first project intelligence for AI coding agents.');
+    lines.push('Usage: shrk [--cwd <dir>] <command> [...args]');
+    lines.push('');
+    lines.push('Core (always on):');
+    lines.push('  $ shrk recommend "<task>"        — what should I do?');
+    lines.push('  $ shrk doctor                    — is the workspace healthy?');
+    lines.push('  $ shrk context --task "<task>"   — focused context for a task');
+    lines.push('  $ shrk init                      — create sharkcraft/ + config skeleton');
+    lines.push('  $ shrk check boundaries          — boundary enforcement');
+    lines.push('  $ shrk surface list              — every command grouped by tier');
+    lines.push('');
+    lines.push('Discover the rest (extended tier — always callable):');
+    lines.push('  $ shrk surface list              — full surface, grouped by tier and profile');
+    lines.push('  $ shrk surface profiles          — named profiles (small-app / monorepo / ci / agent / pack-author)');
+    lines.push('  $ shrk surface explain <cmd>     — why a command has its current tier');
+    lines.push('  $ shrk help <command>            — usage for a specific command');
+    lines.push('  $ shrk --full-help               — the long, exhaustive help');
+    lines.push('  $ shrk --about                   — what shrk is and is not');
+    lines.push('');
+    lines.push('Free-form input is fine — `shrk "<task>"` routes to `shrk recommend`.');
+    return lines.join('\n') + '\n';
+}
+export function makeHelpCommand(registry) {
+    return {
+        name: 'help',
+        description: 'Show CLI help. Bare `shrk help` prints a short start screen — pass `--full` for the long catalog.',
+        usage: 'shrk help [<command>] [--full]',
+        run(args) {
+            const requested = args.positional[0];
+            const wantsFull = args.flags.get('full') === true ||
+                args.flags.get('verbose') === true ||
+                args.flags.get('full-help') === true;
+            if (requested) {
+                // Multi-segment help. `shrk help "pack author"` or
+                // positional args ["pack", "author"] resolve through the trie.
+                const tokens = args.positional[0]?.includes(' ')
+                    ? args.positional[0].split(/\s+/).filter(Boolean)
+                    : args.positional.filter(Boolean);
+                const { handler, matchedPath, node } = registry.resolve(tokens);
+                if (handler && matchedPath.join(' ') === tokens.join(' ')) {
+                    // Exact match on a callable command.
+                    const canonical = registry.listCommandAliases().get(tokens[0]);
+                    process.stdout.write(`${matchedPath.join(' ')} — ${handler.description}\n${handler.usage}\n`);
+                    if (canonical && tokens.length === 1) {
+                        process.stdout.write(`(alias for: ${canonical})\n`);
+                    }
+                    return 0;
+                }
+                if (node.children.size > 0) {
+                    // It's a group (with or without its own handler). List children.
+                    const aliasNote = matchedPath.length === 1 && registry.listGroupAliases().get(tokens[0]) !== undefined
+                        ? ` (alias for: ${registry.listGroupAliases().get(tokens[0])})`
+                        : '';
+                    const groupLabel = matchedPath.length > 0 ? matchedPath.join(' ') : tokens.join(' ');
+                    process.stdout.write(header(`shrk ${groupLabel}${aliasNote}`));
+                    if (handler) {
+                        process.stdout.write(`  (this group is itself callable)\n`);
+                        process.stdout.write(`  ${groupLabel.padEnd(20)} — ${handler.description}\n`);
+                        process.stdout.write(`      ${handler.usage}\n\n`);
+                    }
+                    for (const [name, child] of node.children) {
+                        if (child.handler) {
+                            process.stdout.write(`  ${groupLabel} ${name.padEnd(12)} — ${child.handler.description}\n`);
+                            process.stdout.write(`      ${child.handler.usage}\n`);
+                        }
+                        else if (child.children.size > 0) {
+                            // Nested subgroup — show one-line summary.
+                            const verbList = [...child.children.keys()].slice(0, 4).join(', ');
+                            process.stdout.write(`  ${groupLabel} ${name.padEnd(12)} — subgroup: ${verbList}…\n`);
+                        }
+                    }
+                    return 0;
+                }
+                process.stderr.write(`Unknown command: ${tokens.join(' ')}\n`);
+                return 1;
+            }
+            if (!wantsFull) {
+                process.stdout.write(renderStartScreen());
+                return 0;
+            }
+            process.stdout.write(`SharkCraft CLI — structured project intelligence for AI coding agents\n`);
+            process.stdout.write(`Usage: shrk [--cwd <dir>] <command> [...args]\n`);
+            process.stdout.write(header('Top-level commands'));
+            for (const c of registry.list()) {
+                process.stdout.write(`  ${c.name.padEnd(10)} — ${c.description}\n`);
+            }
+            // Show each canonical group once.
+            const canonicalGroups = [];
+            const aliasMap = registry.listGroupAliases();
+            const seen = new Set();
+            for (const g of registry.listGroups()) {
+                const canonical = aliasMap.get(g) ?? g;
+                if (!seen.has(canonical)) {
+                    seen.add(canonical);
+                    canonicalGroups.push(canonical);
+                }
+            }
+            const aliasesByCanonical = new Map();
+            for (const [alias, canonical] of aliasMap.entries()) {
+                const list = aliasesByCanonical.get(canonical) ?? [];
+                list.push(alias);
+                aliasesByCanonical.set(canonical, list);
+            }
+            for (const group of canonicalGroups) {
+                const aliases = aliasesByCanonical.get(group) ?? [];
+                const aliasNote = aliases.length ? ` (also: ${aliases.join(', ')})` : '';
+                process.stdout.write(header(`shrk ${group} <sub>${aliasNote}`));
+                for (const s of registry.listGroup(group)) {
+                    process.stdout.write(`  ${group} ${s.name.padEnd(10)} — ${s.description}\n`);
+                }
+            }
+            process.stdout.write('\nRun `shrk help <command>` for detailed usage.\n');
+            return 0;
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const helperListCommand: ICommandHandler;
+export declare const helperGetCommand: ICommandHandler;
+export declare const helperPlanCommand: ICommandHandler;
+export declare const helperCommand: ICommandHandler;
+//# sourceMappingURL=helper.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helper.command.d.ts","sourceRoot":"","sources":["../../src/commands/helper.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,iBAAiB,EAAE,eAgB/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eA6B9B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAiF/B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,eAqB3B,CAAC"}

package/dist/commands/helper.command.js

@@ -0,0 +1,170 @@
+/**
+ * `shrk helper` commands.
+ *
+ * shrk helper list
+ * shrk helper get <id>
+ * shrk helper plan <id> --var k=v [--dry-run] [--output <plan.json>]
+ *
+ * Dry-run by default; never writes source.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildHelperPlan, HELPERS, HELPER_SYNTHETIC_TEMPLATE, helperPlanToSavedPlan, renderHelperPlanText, } from '@shrkcrft/inspector';
+import { savePlanToFile, signPlan } from '@shrkcrft/generator';
+import { flagBool, flagString, flagVars, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+function writePlanFile(content, outputArg, cwd) {
+    const abs = nodePath.isAbsolute(outputArg) ? outputArg : nodePath.resolve(cwd, outputArg);
+    mkdirSync(nodePath.dirname(abs), { recursive: true });
+    writeFileSync(abs, content + '\n', 'utf8');
+    return abs;
+}
+export const helperListCommand = {
+    name: 'list',
+    description: 'List available helpers (one-shot plan generators).',
+    usage: 'shrk helper list [--json]',
+    async run(args) {
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(HELPERS) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Helpers (${HELPERS.length})`));
+        for (const h of HELPERS) {
+            const marker = h.destructive ? '[destructive] ' : '              ';
+            process.stdout.write(`  ${marker}${h.id.padEnd(34)} ${h.description}\n`);
+        }
+        return 0;
+    },
+};
+export const helperGetCommand = {
+    name: 'get',
+    description: 'Show a helper definition (variables, safety flags).',
+    usage: 'shrk helper get <id> [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk helper get <id>\n');
+            return 2;
+        }
+        const def = HELPERS.find((h) => h.id === id);
+        if (!def) {
+            process.stderr.write(`Unknown helper: ${id}\n`);
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(def) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Helper: ${def.id}`));
+        process.stdout.write(`  description     ${def.description}\n`);
+        process.stdout.write(`  destructive     ${def.destructive ? 'yes' : 'no'}\n`);
+        process.stdout.write(`  review          ${def.requiresHumanReview ? 'human review required' : 'auto'}\n`);
+        process.stdout.write(`  variables       ${def.variables.length}\n`);
+        for (const v of def.variables) {
+            process.stdout.write(`    • ${v.name}${v.required ? ' (required)' : ''} — ${v.description}\n`);
+        }
+        return 0;
+    },
+};
+export const helperPlanCommand = {
+    name: 'plan',
+    description: 'Generate a plan-only helper plan (dry-run by default). Pass --save-plan <file> to emit a saved plan that flows through `shrk apply`.',
+    usage: 'shrk helper plan <id> --var k=v [--output <plan.json>] [--save-plan <file>] [--sign] [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk helper plan <id> --var k=v\n');
+            return 2;
+        }
+        const def = HELPERS.find((h) => h.id === id);
+        if (!def) {
+            process.stderr.write(`Unknown helper: ${id}\n`);
+            return 1;
+        }
+        // Helpers with requiresProfile must error explicitly when no
+        // profile is available. Today the helper-registry detects this inside
+        // buildHelperPlan via requireProfile(); we surface a friendly message.
+        if ('requiresProfile' in def && def.requiresProfile) {
+            process.stderr.write(`Helper "${id}" requires a plugin-lifecycle profile. Available:\n  $ shrk plugin lifecycle profiles\n`);
+            // Still try to build the plan; the registry throws with the same idea.
+        }
+        const cwd = resolveCwd(args);
+        const vars = flagVars(args);
+        try {
+            const plan = buildHelperPlan({ helperId: id, projectRoot: cwd, vars });
+            const savePlanPath = flagString(args, 'save-plan');
+            if (savePlanPath) {
+                const saved = helperPlanToSavedPlan(plan, cwd);
+                let toWrite = saved;
+                if (flagBool(args, 'sign')) {
+                    const signed = signPlan(toWrite);
+                    if (signed.ok)
+                        toWrite = signed.value;
+                }
+                const abs = nodePath.isAbsolute(savePlanPath)
+                    ? savePlanPath
+                    : nodePath.resolve(cwd, savePlanPath);
+                const writeResult = savePlanToFile(toWrite, abs);
+                if (!writeResult.ok) {
+                    process.stderr.write(`Failed to save plan: ${writeResult.error.message}\n`);
+                    return 1;
+                }
+                if (!flagBool(args, 'json')) {
+                    process.stdout.write(renderHelperPlanText(plan));
+                    process.stdout.write(`\nSaved plan to ${abs}\nApply: shrk apply ${abs} --verify-signature\n`);
+                }
+                else {
+                    process.stdout.write(asJson({ saved: abs, plan, synthetic: HELPER_SYNTHETIC_TEMPLATE }) + '\n');
+                }
+                return 0;
+            }
+            const output = flagString(args, 'output');
+            if (flagBool(args, 'json')) {
+                const body = asJson(plan);
+                if (output) {
+                    const abs = writePlanFile(body, output, cwd);
+                    process.stdout.write(`Wrote ${abs}\n`);
+                }
+                else {
+                    process.stdout.write(body + '\n');
+                }
+                return 0;
+            }
+            process.stdout.write(renderHelperPlanText(plan));
+            if (plan.destructive) {
+                process.stdout.write('\n⚠ DESTRUCTIVE — human approval required.\n');
+            }
+            if (output) {
+                const abs = writePlanFile(asJson(plan), output, cwd);
+                process.stdout.write(`\nSaved plan to ${abs}\n`);
+            }
+            return 0;
+        }
+        catch (e) {
+            process.stderr.write(`${e.message}\n`);
+            return 2;
+        }
+    },
+};
+export const helperCommand = {
+    name: 'helper',
+    description: 'Helper plan generators (list / get / plan). Plan-only, dry-run default.',
+    usage: 'shrk helper list|get <id>|plan <id> --var k=v',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'list') {
+            args.positional = args.positional.slice(1);
+            return helperListCommand.run(args);
+        }
+        if (sub === 'get') {
+            args.positional = args.positional.slice(1);
+            return helperGetCommand.run(args);
+        }
+        if (sub === 'plan') {
+            args.positional = args.positional.slice(1);
+            return helperPlanCommand.run(args);
+        }
+        process.stderr.write('Usage: shrk helper list|get <id>|plan <id>\n');
+        return 2;
+    },
+};

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

@@ -0,0 +1,6 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const ideFileCommand: ICommandHandler;
+export declare const ideProjectCommand: ICommandHandler;
+export declare const ideSymbolCommand: ICommandHandler;
+export declare const ideCommand: ICommandHandler;
+//# sourceMappingURL=ide.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ide.command.d.ts","sourceRoot":"","sources":["../../src/commands/ide.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0ChC,eAAO,MAAM,cAAc,EAAE,eAiI5B,CAAC;AAwCF,eAAO,MAAM,iBAAiB,EAAE,eAuF/B,CAAC;AAsBF,eAAO,MAAM,gBAAgB,EAAE,eAuG9B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,eA+BxB,CAAC"}

package/dist/commands/ide.command.js

@@ -0,0 +1,340 @@
+import { existsSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildAiReadinessReport, buildPackSignatureStatusReport, inspectSharkcraft, runDoctor, } from '@shrkcrft/inspector';
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+function relativise(cwd, file) {
+    const abs = nodePath.isAbsolute(file) ? file : nodePath.resolve(cwd, file);
+    return nodePath.relative(cwd, abs);
+}
+export const ideFileCommand = {
+    name: 'file',
+    description: 'Emit per-file SharkCraft signals as one JSON record (applicable rules + relevant knowledge + suggested commands). Read-only. Designed for IDE extensions.',
+    usage: 'shrk ide file <path> [--json]',
+    async run(args) {
+        const target = args.positional[0];
+        if (!target) {
+            process.stderr.write('Usage: shrk ide file <path> [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const abs = nodePath.isAbsolute(target) ? target : nodePath.resolve(cwd, target);
+        const exists = existsSync(abs);
+        const isDirectory = exists ? safeIsDir(abs) : false;
+        let report;
+        try {
+            const inspection = await inspectSharkcraft({ cwd });
+            const rules = inspection.ruleService.list();
+            const knowledge = inspection.knowledgeEntries;
+            // We don't have a per-file query in the engine; the deterministic
+            // approach is: surface rules whose `pathPatterns` or content
+            // mention this file's path segments, then suggest the smallest set
+            // of next commands.
+            const relPath = relativise(cwd, abs);
+            const fileTokens = relPath.split(/[\\/.]/).filter((t) => t.length >= 3);
+            const applicableRules = rules
+                .filter((r) => fileTokens.some((tok) => {
+                const hay = (r.content + ' ' + (r.title ?? '') + ' ' + (r.tags ?? []).join(' ')).toLowerCase();
+                return hay.includes(tok.toLowerCase());
+            }))
+                .slice(0, 25)
+                .map((r) => ({
+                id: r.id,
+                title: r.title,
+                priority: r.priority,
+                advisory: Boolean(r.advisory),
+                appliesWhen: r.appliesWhen,
+            }));
+            const relevantKnowledge = knowledge
+                .filter((k) => fileTokens.some((tok) => {
+                const hay = (k.content + ' ' + (k.title ?? '') + ' ' + (k.tags ?? []).join(' ')).toLowerCase();
+                return hay.includes(tok.toLowerCase());
+            }))
+                .slice(0, 25)
+                .map((k) => ({ id: k.id, title: k.title, type: k.type, priority: k.priority }));
+            const suggestedCommands = [];
+            suggestedCommands.push(`shrk why "${relPath}"`);
+            if (applicableRules.length > 0) {
+                suggestedCommands.push(`shrk rules relevant --task "edit ${relPath}"`);
+            }
+            if (relevantKnowledge.length > 0) {
+                suggestedCommands.push(`shrk knowledge search "${nodePath.basename(relPath)}"`);
+            }
+            suggestedCommands.push('shrk impact');
+            suggestedCommands.push('shrk check boundaries --changed-only');
+            const notes = [];
+            if (!exists)
+                notes.push('file does not exist on disk');
+            if (isDirectory)
+                notes.push('path is a directory; results are heuristic');
+            report = {
+                schema: 'sharkcraft.ide.file/v1',
+                generatedAt: new Date().toISOString(),
+                cwd,
+                file: {
+                    path: abs,
+                    relativePath: relPath,
+                    exists,
+                    isDirectory,
+                },
+                applicableRules,
+                relevantKnowledge,
+                suggestedCommands,
+                notes,
+            };
+        }
+        catch (e) {
+            // If sharkcraft/ is absent or broken, still produce a useful skeleton.
+            const relPath = relativise(cwd, abs);
+            report = {
+                schema: 'sharkcraft.ide.file/v1',
+                generatedAt: new Date().toISOString(),
+                cwd,
+                file: { path: abs, relativePath: relPath, exists, isDirectory },
+                applicableRules: [],
+                relevantKnowledge: [],
+                suggestedCommands: [
+                    'shrk init --zero-config',
+                    'shrk doctor',
+                ],
+                notes: [
+                    `inspectSharkcraft failed: ${e.message}`,
+                    'run `shrk init --zero-config` to set up the workspace',
+                ],
+            };
+        }
+        if (flagBool(args, 'json') || !process.stdout.isTTY) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`IDE file report: ${report.file.relativePath}`));
+        process.stdout.write(`exists:    ${report.file.exists}\n`);
+        process.stdout.write(`directory: ${report.file.isDirectory}\n\n`);
+        process.stdout.write(`applicable rules (${report.applicableRules.length}):\n`);
+        for (const r of report.applicableRules.slice(0, 10)) {
+            process.stdout.write(`  • ${r.id}${r.priority ? ` [${r.priority}]` : ''} — ${r.title ?? ''}\n`);
+        }
+        process.stdout.write(`\nrelevant knowledge (${report.relevantKnowledge.length}):\n`);
+        for (const k of report.relevantKnowledge.slice(0, 10)) {
+            process.stdout.write(`  • ${k.id}${k.priority ? ` [${k.priority}]` : ''} — ${k.title ?? ''}\n`);
+        }
+        process.stdout.write(`\nsuggested commands:\n`);
+        for (const c of report.suggestedCommands)
+            process.stdout.write(`  $ ${c}\n`);
+        if (report.notes.length > 0) {
+            process.stdout.write('\nnotes:\n');
+            for (const n of report.notes)
+                process.stdout.write(`  • ${n}\n`);
+        }
+        process.stdout.write(`\n(pass --json for the machine surface — schema ${report.schema})\n`);
+        return 0;
+    },
+};
+function safeIsDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export const ideProjectCommand = {
+    name: 'project',
+    description: 'Emit workspace-wide SharkCraft signals as one JSON record (active packs, presets, framework, doctor summary, CI status, signature status). Read-only.',
+    usage: 'shrk ide project [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const doctor = runDoctor(inspection);
+        const ai = buildAiReadinessReport(inspection);
+        const sig = buildPackSignatureStatusReport(inspection);
+        const cfg = inspection.config;
+        const verificationIds = (cfg?.verificationCommands ?? [])
+            .map((v) => v.id)
+            .filter((id) => typeof id === 'string');
+        // Active presets — every preset in the registry that recommends with
+        // confidence ≥ 'medium' against the detected profiles.
+        const activePresets = inspection.presetRegistry
+            .list()
+            .filter((p) => {
+            const appliesTo = p.appliesTo;
+            if (!appliesTo)
+                return false;
+            return inspection.workspace.profiles.some((prof) => appliesTo.includes(prof));
+        })
+            .slice(0, 25)
+            .map((p) => ({ id: p.id }));
+        const report = {
+            schema: 'sharkcraft.ide.project/v1',
+            generatedAt: new Date().toISOString(),
+            cwd,
+            workspace: {
+                framework: inspection.workspace.framework ?? null,
+                profiles: inspection.workspace.profiles,
+                hasSharkcraftFolder: inspection.hasSharkcraftFolder,
+            },
+            activePacks: (inspection.packs.validPacks ?? []).map((p) => ({
+                name: p.packageName,
+                version: p.packageVersion,
+            })),
+            activePresets,
+            configuredVerificationCommandIds: verificationIds,
+            doctor: {
+                passed: doctor.passed,
+                errors: doctor.summary.errors,
+                warnings: doctor.summary.warnings,
+                info: doctor.summary.info,
+                ok: doctor.summary.ok,
+            },
+            aiReadiness: { score: ai.score, grade: ai.grade },
+            signatureStatus: {
+                total: sig.summary.total,
+                present: sig.summary.present,
+                stale: sig.summary.stale,
+                missing: sig.summary.missing,
+                dev: sig.summary.dev,
+            },
+            suggestedCommands: [
+                'shrk doctor',
+                'shrk check boundaries --changed-only',
+                'shrk packs signature-status',
+                'shrk drift rules',
+            ],
+        };
+        if (flagBool(args, 'json') || !process.stdout.isTTY) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`IDE project report`));
+        process.stdout.write(`framework:  ${report.workspace.framework ?? '(unknown)'}\n`);
+        process.stdout.write(`profiles:   ${report.workspace.profiles.join(', ') || '(none)'}\n`);
+        process.stdout.write(`packs:      ${report.activePacks.length}\n`);
+        process.stdout.write(`presets:    ${report.activePresets.length}\n`);
+        process.stdout.write(`doctor:     ${report.doctor.errors} err / ${report.doctor.warnings} warn / ${report.doctor.ok} ok\n`);
+        process.stdout.write(`ai-ready:   ${report.aiReadiness.score}/100 (${report.aiReadiness.grade})\n`);
+        process.stdout.write(`signatures: ${report.signatureStatus.present} present / ${report.signatureStatus.stale} stale / ${report.signatureStatus.missing} missing / ${report.signatureStatus.dev} dev\n`);
+        process.stdout.write(`\n(pass --json for the machine surface — schema ${report.schema})\n`);
+        return 0;
+    },
+};
+export const ideSymbolCommand = {
+    name: 'symbol',
+    description: 'Emit per-symbol SharkCraft signals (knowledge anchors / rule references / suggested commands) as one JSON record. Read-only.',
+    usage: 'shrk ide symbol <name> [--json]',
+    async run(args) {
+        const symbol = args.positional[0];
+        if (!symbol) {
+            process.stderr.write('Usage: shrk ide symbol <name> [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const references = [];
+        const symbolLower = symbol.toLowerCase();
+        const matchInString = (s) => typeof s === 'string' && s.toLowerCase().includes(symbolLower);
+        for (const entry of inspection.knowledgeEntries) {
+            const kind = entry.type === 'rule' ? 'rule' : 'knowledge';
+            const anchors = entry.anchors;
+            if (anchors) {
+                for (const a of anchors) {
+                    if (a.kind === 'symbol' && a.symbol === symbol) {
+                        references.push({
+                            sourceKind: kind,
+                            sourceId: entry.id,
+                            sourceTitle: entry.title,
+                            matchedField: 'anchors',
+                        });
+                        break;
+                    }
+                }
+            }
+            const refs = entry.references;
+            if (refs) {
+                for (const r of refs) {
+                    if (r.kind === 'symbol' && r.symbol === symbol) {
+                        references.push({
+                            sourceKind: kind,
+                            sourceId: entry.id,
+                            sourceTitle: entry.title,
+                            matchedField: 'references',
+                        });
+                        break;
+                    }
+                }
+            }
+            if (matchInString(entry.title) && !references.some((x) => x.sourceId === entry.id)) {
+                references.push({
+                    sourceKind: kind,
+                    sourceId: entry.id,
+                    sourceTitle: entry.title,
+                    matchedField: 'title',
+                });
+            }
+            else if (matchInString(entry.content) &&
+                !references.some((x) => x.sourceId === entry.id)) {
+                references.push({
+                    sourceKind: kind,
+                    sourceId: entry.id,
+                    sourceTitle: entry.title,
+                    matchedField: 'content',
+                });
+            }
+        }
+        const report = {
+            schema: 'sharkcraft.ide.symbol/v1',
+            generatedAt: new Date().toISOString(),
+            cwd,
+            symbol,
+            references: references.slice(0, 50),
+            suggestedCommands: [
+                `shrk impact --symbol ${symbol}`,
+                `shrk trace --symbol ${symbol}`,
+                `shrk knowledge search "${symbol}"`,
+            ],
+            notes: references.length === 0
+                ? ['no anchors / rules reference this symbol']
+                : [],
+        };
+        if (flagBool(args, 'json') || !process.stdout.isTTY) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`IDE symbol report: ${symbol}`));
+        process.stdout.write(`references (${report.references.length}):\n`);
+        for (const r of report.references.slice(0, 10)) {
+            process.stdout.write(`  • ${r.sourceKind}:${r.sourceId} (matched in ${r.matchedField})\n`);
+        }
+        process.stdout.write(`\nsuggested commands:\n`);
+        for (const c of report.suggestedCommands)
+            process.stdout.write(`  $ ${c}\n`);
+        return 0;
+    },
+};
+export const ideCommand = {
+    name: 'ide',
+    description: 'IDE data surface — read-only JSON reports per file / project / symbol. Designed for IDE extensions to consume.',
+    usage: 'shrk ide file <path> [--json] | shrk ide project [--json] | shrk ide symbol <name> [--json]',
+    async run(args) {
+        const verb = args.positional[0];
+        if (verb === 'file') {
+            return ideFileCommand.run({
+                ...args,
+                positional: args.positional.slice(1),
+            });
+        }
+        if (verb === 'project') {
+            return ideProjectCommand.run({
+                ...args,
+                positional: args.positional.slice(1),
+            });
+        }
+        if (verb === 'symbol') {
+            return ideSymbolCommand.run({
+                ...args,
+                positional: args.positional.slice(1),
+            });
+        }
+        process.stderr.write('Usage: shrk ide <file|project|symbol> [...args] [--json]\n');
+        return 2;
+    },
+};

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

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const impactCommand: ICommandHandler;
+//# sourceMappingURL=impact.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0QhC,eAAO,MAAM,aAAa,EAAE,eAoV3B,CAAC"}