@shrkcrft/cli 0.1.0-alpha.1

package/dist/commands/mcp.command.js

@@ -0,0 +1,203 @@
+import { startMcpServer, } from '@shrkcrft/mcp-server';
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { printError } from "../output/print-error.js";
+import { loadSurfaceContext } from "../surface/load-surface-context.js";
+import { buildSurfaceSummary, findCommandInSummary } from "../surface/surface-summary.js";
+export const mcpCommand = {
+    name: 'mcp',
+    description: 'MCP server operations (subcommand required).',
+    usage: 'shrk [--cwd <dir>] mcp serve [--verbose] [--watch] [--http] [--port <n>] [--host <h>]   |   shrk mcp install [<harness>]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'serve') {
+            try {
+                const cwd = resolveCwd(args);
+                const opts = {
+                    cwd,
+                    verbose: flagBool(args, 'verbose'),
+                    watch: flagBool(args, 'watch'),
+                    gateResolver: await buildMcpGateResolver(cwd),
+                };
+                if (flagBool(args, 'http')) {
+                    opts.transport = 'http';
+                    const host = flagString(args, 'host');
+                    if (host)
+                        opts.host = host;
+                    const port = flagNumber(args, 'port');
+                    if (port !== undefined)
+                        opts.port = port;
+                }
+                await startMcpServer(opts);
+                return 0;
+            }
+            catch (e) {
+                printError(e instanceof Error ? e : new Error(String(e)));
+                return 1;
+            }
+        }
+        if (sub === 'install') {
+            const harness = args.positional[1];
+            const showAll = flagBool(args, 'all-paths');
+            if (harness !== undefined && !HARNESSES.some((h) => h.id === harness)) {
+                process.stderr.write(`Unknown harness: ${harness}\nKnown: ${HARNESSES.map((h) => h.id).join(', ')}\n`);
+                return 2;
+            }
+            process.stdout.write(renderMcpInstallInstructions(harness, showAll));
+            return 0;
+        }
+        process.stderr.write('Usage:\n' +
+            '  shrk mcp serve [--http] [--port N] [--watch]\n' +
+            '  shrk mcp install [claude-code|claude-desktop|cursor|cline]\n');
+        return 2;
+    },
+};
+const HARNESSES = [
+    {
+        id: 'claude-code',
+        label: 'Claude Code (Anthropic CLI)',
+        configPaths: [
+            { os: '*', path: '<repo>/.mcp.json                    # project-scoped (preferred)' },
+            { os: '*', path: '~/.claude.json                      # user-scoped (fallback)' },
+        ],
+        note: 'Claude Code reads both; project-scoped wins when present.',
+    },
+    {
+        id: 'claude-desktop',
+        label: 'Claude Desktop',
+        configPaths: [
+            { os: 'darwin', path: '~/Library/Application Support/Claude/claude_desktop_config.json' },
+            { os: 'win32', path: '%APPDATA%\\Claude\\claude_desktop_config.json' },
+            { os: 'linux', path: '~/.config/Claude/claude_desktop_config.json' },
+        ],
+        note: 'Restart Claude Desktop after editing.',
+    },
+    {
+        id: 'cursor',
+        label: 'Cursor IDE',
+        configPaths: [
+            { os: '*', path: '~/.cursor/mcp.json                  # user-scoped' },
+            { os: '*', path: '<repo>/.cursor/mcp.json             # project-scoped' },
+        ],
+        note: 'Cursor merges both. Reload the IDE after editing.',
+    },
+    {
+        id: 'cline',
+        label: 'Cline (VS Code extension)',
+        configPaths: [
+            {
+                os: 'darwin',
+                path: '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json',
+            },
+            {
+                os: 'win32',
+                path: '%APPDATA%\\Code\\User\\globalStorage\\saoudrizwan.claude-dev\\settings\\cline_mcp_settings.json',
+            },
+            {
+                os: 'linux',
+                path: '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json',
+            },
+        ],
+        note: 'Reload the Cline panel after editing.',
+    },
+];
+function currentOs() {
+    const p = process.platform;
+    if (p === 'darwin' || p === 'win32' || p === 'linux')
+        return p;
+    return 'other';
+}
+function pathsForPlatform(target, showAll) {
+    if (showAll)
+        return target.configPaths.map((p) => p.path);
+    const os = currentOs();
+    const matched = target.configPaths.filter((p) => p.os === '*' || p.os === os);
+    // If the current OS has no specific entry, fall back to all to avoid an
+    // empty list. (`other` platforms like FreeBSD land here.)
+    if (matched.length === 0)
+        return target.configPaths.map((p) => p.path);
+    return matched.map((p) => p.path);
+}
+const SHARKCRAFT_MCP_SNIPPET = `{
+  "mcpServers": {
+    "sharkcraft": {
+      "command": "shrk",
+      "args": ["mcp", "serve"]
+    }
+  }
+}`;
+function renderMcpInstallInstructions(harness, showAll) {
+    const lines = [];
+    if (!harness) {
+        lines.push('SharkCraft MCP server entry (universal, stdio transport):');
+        lines.push('');
+        lines.push(SHARKCRAFT_MCP_SNIPPET);
+        lines.push('');
+        lines.push('Paste it into one of these harnesses (`shrk mcp install <id>` for exact paths):');
+        lines.push('');
+        for (const h of HARNESSES) {
+            lines.push(`  ${h.id.padEnd(16)} ${h.label}`);
+        }
+        lines.push('');
+        lines.push('After pasting, restart/reload the harness. The server is read-only — agents cannot write.');
+        return lines.join('\n') + '\n';
+    }
+    const target = HARNESSES.find((h) => h.id === harness);
+    if (!target) {
+        return (`Unknown harness: ${harness}\n` +
+            `Known: ${HARNESSES.map((h) => h.id).join(', ')}\n`);
+    }
+    const paths = pathsForPlatform(target, showAll);
+    const os = currentOs();
+    lines.push(`${target.label}`);
+    lines.push('');
+    lines.push(showAll || os === 'other'
+        ? 'Config file (all platforms):'
+        : `Config file (${os}; pass --all-paths to see every platform):`);
+    for (const p of paths)
+        lines.push(`  ${p}`);
+    lines.push('');
+    lines.push('Add this entry (merge with any existing `mcpServers` block):');
+    lines.push('');
+    lines.push(SHARKCRAFT_MCP_SNIPPET);
+    if (target.note) {
+        lines.push('');
+        lines.push(target.note);
+    }
+    lines.push('');
+    lines.push('Verify by asking the agent: "List MCP tools available." You should see ~250 sharkcraft tools.');
+    lines.push('The server is read-only — agents cannot write. Use `shrk apply --verify-signature` for writes.');
+    return lines.join('\n') + '\n';
+}
+/**
+ * Build the MCP tier-gate resolver from the surface summary.
+ * Returns a function that, given a tool, decides whether to refuse the
+ * call (when the tool's sibling CLI command is experimental and not
+ * enabled). Tools without `cliCommand` are always callable
+ * (bootstrap MCP-only tools).
+ *
+ * Failure-soft: any error building the summary returns a no-op
+ * resolver — the server stays open rather than failing closed on
+ * unrelated issues.
+ */
+async function buildMcpGateResolver(cwd) {
+    try {
+        const { context } = await loadSurfaceContext({ cwd });
+        const summary = buildSurfaceSummary(context);
+        return (tool) => {
+            if (!tool.cliCommand)
+                return null;
+            const view = findCommandInSummary(summary, tool.cliCommand);
+            if (!view || view.callable)
+                return null;
+            return {
+                command: tool.cliCommand,
+                reason: view.detail
+                    ? `Sibling CLI command \`${tool.cliCommand}\` is experimental: ${view.detail}.`
+                    : `Sibling CLI command \`${tool.cliCommand}\` is experimental and not enabled.`,
+            };
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,11 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const memoryBuildCommand: ICommandHandler;
+export declare const memoryDiffCommand: ICommandHandler;
+export declare const memoryDriftCommand: ICommandHandler;
+export declare const memorySnapshotsCommand: ICommandHandler;
+export declare const memoryReportCommand: ICommandHandler;
+export declare const memoryRiskCommand: ICommandHandler;
+export declare const memoryFilesCommand: ICommandHandler;
+export declare const memoryDiagnosticsCommand: ICommandHandler;
+export declare const memoryResetCommand: ICommandHandler;
+//# sourceMappingURL=memory.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.command.d.ts","sourceRoot":"","sources":["../../src/commands/memory.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,kBAAkB,EAAE,eAyBhC,CAAC;AAWF,eAAO,MAAM,iBAAiB,EAAE,eA0C/B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAgChC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAkBpC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAkBjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAmB/B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAyBhC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAuBtC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAwBhC,CAAC"}

package/dist/commands/memory.command.js

@@ -0,0 +1,264 @@
+import * as nodePath from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { buildRepositoryMemory, diffMemoryIndex, inspectSharkcraft, latestMemorySnapshot, listMemorySnapshots, loadMemorySnapshot, loadRepositoryMemory, memoryRiskForTask, renderMemoryDiffMarkdown, renderMemoryDiffText, renderMemoryReportText, renderMemoryRiskText, resetRepositoryMemory, saveRepositoryMemory, writeMemorySnapshot, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+function writeOutOrJson(args, cwd, body) {
+    const output = flagString(args, 'output');
+    if (output) {
+        const abs = nodePath.isAbsolute(output) ? output : nodePath.resolve(cwd, output);
+        mkdirSync(nodePath.dirname(abs), { recursive: true });
+        writeFileSync(abs, body, 'utf8');
+        process.stdout.write(`Wrote ${abs}\n`);
+        return 0;
+    }
+    process.stdout.write(body);
+    return 0;
+}
+export const memoryBuildCommand = {
+    name: 'build',
+    description: 'Build (or refresh) the local repository memory index from .sharkcraft history. Writes only to .sharkcraft/memory/. With --write-snapshot, also archives the index to .sharkcraft/memory/history/. Local-only.',
+    usage: 'shrk memory build [--write-snapshot] [--json] [--output <file>]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const index = await buildRepositoryMemory(inspection);
+        const file = saveRepositoryMemory(inspection.projectRoot, index);
+        let snapshotFile;
+        if (flagBool(args, 'write-snapshot')) {
+            snapshotFile = writeMemorySnapshot(inspection.projectRoot, index);
+        }
+        if (flagBool(args, 'json')) {
+            return writeOutOrJson(args, cwd, asJson({ index, indexFile: file, snapshotFile }) + '\n');
+        }
+        process.stdout.write(`Memory index written to ${file}\n`);
+        if (snapshotFile)
+            process.stdout.write(`Snapshot archived: ${snapshotFile}\n`);
+        process.stdout.write(`  sources scanned: ${index.sourceCount}\n`);
+        process.stdout.write(`  top files     : ${index.files.length}\n`);
+        process.stdout.write(`  diagnostics   : ${index.diagnostics.length}\n`);
+        process.stdout.write(`  release blockers: ${index.releaseBlockers.length}\n`);
+        return 0;
+    },
+};
+function loadIndexFromPath(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export const memoryDiffCommand = {
+    name: 'diff',
+    description: 'Compare two memory snapshots (or one snapshot + the current index). Read-only.',
+    usage: 'shrk memory diff <old.json> [new.json] [--format text|markdown|json] [--output <file>]',
+    async run(args) {
+        const oldArg = args.positional[0];
+        const newArg = args.positional[1];
+        if (!oldArg) {
+            process.stderr.write('Usage: shrk memory diff <old.json> [new.json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const oldPath = nodePath.isAbsolute(oldArg) ? oldArg : nodePath.resolve(cwd, oldArg);
+        const before = loadIndexFromPath(oldPath);
+        if (!before) {
+            process.stderr.write(`Cannot read ${oldPath}\n`);
+            return 1;
+        }
+        let after;
+        if (newArg) {
+            const newPath = nodePath.isAbsolute(newArg) ? newArg : nodePath.resolve(cwd, newArg);
+            after = loadIndexFromPath(newPath);
+            if (!after) {
+                process.stderr.write(`Cannot read ${newPath}\n`);
+                return 1;
+            }
+        }
+        else {
+            after = loadRepositoryMemory(cwd);
+            if (!after) {
+                process.stderr.write('No current memory index. Run `shrk memory build` first.\n');
+                return 1;
+            }
+        }
+        const diff = diffMemoryIndex(before, after);
+        const format = (flagString(args, 'format') ?? 'text').toLowerCase();
+        let body;
+        if (format === 'json' || flagBool(args, 'json'))
+            body = asJson(diff) + '\n';
+        else if (format === 'markdown' || format === 'md')
+            body = renderMemoryDiffMarkdown(diff);
+        else
+            body = renderMemoryDiffText(diff);
+        return writeOutOrJson(args, cwd, body);
+    },
+};
+export const memoryDriftCommand = {
+    name: 'drift',
+    description: 'Compare the current memory index against the latest snapshot under .sharkcraft/memory/history/. Read-only.',
+    usage: 'shrk memory drift [--previous <snapshot.json>] [--format text|markdown|json] [--output <file>]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const current = loadRepositoryMemory(cwd);
+        if (!current) {
+            process.stderr.write('No current memory index. Run `shrk memory build` first.\n');
+            return 1;
+        }
+        const previousFlag = flagString(args, 'previous');
+        let before;
+        if (previousFlag) {
+            const p = nodePath.isAbsolute(previousFlag) ? previousFlag : nodePath.resolve(cwd, previousFlag);
+            before = loadMemorySnapshot(p);
+            if (!before) {
+                process.stderr.write(`Cannot read ${p}\n`);
+                return 1;
+            }
+        }
+        else {
+            before = latestMemorySnapshot(cwd);
+        }
+        const diff = diffMemoryIndex(before, current);
+        const format = (flagString(args, 'format') ?? 'text').toLowerCase();
+        let body;
+        if (format === 'json' || flagBool(args, 'json'))
+            body = asJson(diff) + '\n';
+        else if (format === 'markdown' || format === 'md')
+            body = renderMemoryDiffMarkdown(diff);
+        else
+            body = renderMemoryDiffText(diff);
+        return writeOutOrJson(args, cwd, body);
+    },
+};
+export const memorySnapshotsCommand = {
+    name: 'snapshots',
+    description: 'List archived memory snapshots under .sharkcraft/memory/history/. Read-only.',
+    usage: 'shrk memory snapshots [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const list = listMemorySnapshots(cwd);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(list) + '\n');
+            return 0;
+        }
+        if (list.length === 0) {
+            process.stdout.write('No snapshots yet. Run `shrk memory build --write-snapshot`.\n');
+            return 0;
+        }
+        for (const f of list)
+            process.stdout.write(`${f}\n`);
+        return 0;
+    },
+};
+export const memoryReportCommand = {
+    name: 'report',
+    description: 'Render a human-readable repository memory report. Read-only.',
+    usage: 'shrk memory report [--json] [--output <file>]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const index = loadRepositoryMemory(cwd);
+        if (!index) {
+            process.stderr.write('No memory index found. Run `shrk memory build` first.\n');
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            return writeOutOrJson(args, cwd, asJson(index) + '\n');
+        }
+        return writeOutOrJson(args, cwd, renderMemoryReportText(index));
+    },
+};
+export const memoryRiskCommand = {
+    name: 'risk',
+    description: 'Combine task risk with historical signals from .sharkcraft/memory/index.json. Read-only.',
+    usage: 'shrk memory risk "<task>" [--json] [--output <file>]',
+    async run(args) {
+        const task = args.positional.join(' ').trim();
+        if (!task) {
+            process.stderr.write('Usage: shrk memory risk "<task>"\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const index = loadRepositoryMemory(cwd);
+        const report = memoryRiskForTask(index, task);
+        if (flagBool(args, 'json')) {
+            return writeOutOrJson(args, cwd, asJson(report) + '\n');
+        }
+        return writeOutOrJson(args, cwd, renderMemoryRiskText(report));
+    },
+};
+export const memoryFilesCommand = {
+    name: 'files',
+    description: 'List historically risky files from the memory index. Read-only.',
+    usage: 'shrk memory files [--json] [--limit <n>]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const index = loadRepositoryMemory(cwd);
+        if (!index) {
+            process.stderr.write('No memory index found. Run `shrk memory build` first.\n');
+            return 1;
+        }
+        const limitRaw = flagString(args, 'limit');
+        const limit = limitRaw ? Number(limitRaw) : 30;
+        const top = index.files.slice(0, Number.isFinite(limit) ? limit : 30);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(top) + '\n');
+            return 0;
+        }
+        for (const f of top) {
+            process.stdout.write(`${String(f.touchCount).padStart(4)}x ${f.path} (conflicts=${f.conflictCount}, warnings=${f.warningCount})\n`);
+        }
+        return 0;
+    },
+};
+export const memoryDiagnosticsCommand = {
+    name: 'diagnostics',
+    description: 'List recurring diagnostics from the memory index. Read-only.',
+    usage: 'shrk memory diagnostics [--json] [--limit <n>]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const index = loadRepositoryMemory(cwd);
+        if (!index) {
+            process.stderr.write('No memory index found. Run `shrk memory build` first.\n');
+            return 1;
+        }
+        const limitRaw = flagString(args, 'limit');
+        const limit = limitRaw ? Number(limitRaw) : 30;
+        const top = index.diagnostics.slice(0, Number.isFinite(limit) ? limit : 30);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(top) + '\n');
+            return 0;
+        }
+        for (const d of top) {
+            process.stdout.write(`${String(d.count).padStart(3)}x ${d.code}\n`);
+        }
+        return 0;
+    },
+};
+export const memoryResetCommand = {
+    name: 'reset',
+    description: 'Reset the local repository memory. Default is --dry-run; pass --write to actually delete .sharkcraft/memory.',
+    usage: 'shrk memory reset [--dry-run|--write]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const writeMode = flagBool(args, 'write');
+        const result = resetRepositoryMemory(cwd, { dryRun: !writeMode });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(result) + '\n');
+            return 0;
+        }
+        if (result.notRemoved.length && !writeMode) {
+            // not removed because dir didn't exist
+        }
+        if (result.dryRun) {
+            process.stdout.write(`(dry-run) Would remove: ${result.removed.join(', ') || '(nothing)'}\n`);
+            process.stdout.write('Pass --write to actually delete.\n');
+        }
+        else {
+            process.stdout.write(`Removed: ${result.removed.join(', ') || '(nothing)'}\n`);
+        }
+        return 0;
+    },
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.command.d.ts","sourceRoot":"","sources":["../../src/commands/onboard.command.ts"],"names":[],"mappings":"AA6CA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,cAAc,EAAE,eA2O5B,CAAC"}