@shrkcrft/cli 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/dashboard/code-intelligence-data.js

@@ -0,0 +1,307 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { runArchCheck } from '@shrkcrft/architecture-guard';
+import { FrameworkQueryApi } from '@shrkcrft/framework-scanners';
+import { GraphStore } from '@shrkcrft/graph';
+import { findResumePoint, } from '@shrkcrft/migrate';
+import { QualityGateReportStore, runQualityGates } from '@shrkcrft/quality-gates';
+import { BridgeStore } from '@shrkcrft/rule-graph';
+/**
+ * Build the Code Intelligence overview response.
+ *
+ * Reads the three on-disk stores plus runs the architecture-guard
+ * check inline. Every section degrades to `available: false` with a
+ * `hint` when its backing store is missing — the dashboard renders
+ * those as "run `shrk graph index` to enable" cards rather than
+ * blocking the whole panel.
+ *
+ * Pure read — never builds or writes anything.
+ */
+export function buildDashboardCodeIntelligence(projectRoot) {
+    const commandHints = [
+        { label: 'Build code graph', command: 'shrk graph index', purpose: 'Refresh the persistent code-graph store.' },
+        { label: 'Build rule-graph bridge', command: 'shrk rule-graph index', purpose: 'Rebuild bridge edges from files to assets.' },
+        { label: 'Build framework index', command: 'shrk framework index', purpose: 'Detect framework entities (NestJS, React, etc.).' },
+        { label: 'Run architecture checks', command: 'shrk arch check', purpose: 'Surface public-API misuse, cycles, fat barrels.' },
+    ];
+    // Graph.
+    const graphStore = new GraphStore(projectRoot);
+    const graph = graphStore.exists()
+        ? readGraphSection(graphStore)
+        : { available: false, hint: "run 'shrk graph index'" };
+    // Bridge.
+    const bridgeStore = new BridgeStore(projectRoot);
+    const bridge = bridgeStore.exists()
+        ? readBridgeSection(bridgeStore)
+        : { available: false, hint: "run 'shrk rule-graph index'" };
+    // Framework.
+    const framework = FrameworkQueryApi.missingDescription(projectRoot)
+        ? { available: false, hint: "run 'shrk framework index'" }
+        : readFrameworkSection(projectRoot);
+    // Architecture (depends on graph store existing).
+    const architecture = graph.available
+        ? readArchSection(projectRoot)
+        : { available: false, errors: 0, warnings: 0, hint: 'graph index missing' };
+    return {
+        schema: 'sharkcraft.dashboard-code-intelligence/v1',
+        available: graph.available || bridge.available || framework.available,
+        graph,
+        bridge,
+        framework,
+        architecture,
+        commandHints,
+    };
+}
+/**
+ * Build the cross-framework routes panel response.
+ *
+ * Reads the framework store. For each entity with `subtype: 'route'`
+ * (or `api-route`), emits a row with `framework`, `method`, `path`,
+ * `handler`, and `file`. Sorted alphabetically by (framework, method,
+ * path).
+ */
+export function buildDashboardRoutes(projectRoot) {
+    const commandHints = [
+        { label: 'Build framework index', command: 'shrk framework index', purpose: 'Detect routes / components across frameworks.' },
+        { label: 'List a single framework', command: 'shrk framework list --framework <name>', purpose: 'Filter the entity list to one framework.' },
+    ];
+    const missing = FrameworkQueryApi.missingDescription(projectRoot);
+    if (missing) {
+        return {
+            schema: 'sharkcraft.dashboard-routes/v1',
+            available: false,
+            total: 0,
+            byFramework: {},
+            routes: [],
+            commandHints,
+            hint: missing,
+        };
+    }
+    const api = FrameworkQueryApi.fromStore(projectRoot);
+    const rows = [];
+    for (const entity of api.list({ subtype: 'route', limit: 5000 })) {
+        rows.push(toRow(entity));
+    }
+    for (const entity of api.list({ subtype: 'api-route', limit: 5000 })) {
+        rows.push(toRow(entity));
+    }
+    rows.sort((a, b) => a.framework.localeCompare(b.framework) ||
+        a.method.localeCompare(b.method) ||
+        a.path.localeCompare(b.path));
+    const byFramework = {};
+    for (const r of rows)
+        byFramework[r.framework] = (byFramework[r.framework] ?? 0) + 1;
+    return {
+        schema: 'sharkcraft.dashboard-routes/v1',
+        available: true,
+        total: rows.length,
+        byFramework,
+        routes: rows,
+        commandHints,
+    };
+}
+function readGraphSection(store) {
+    const snap = store.loadSnapshot();
+    return {
+        available: true,
+        fileCount: snap.manifest.filesIndexed,
+        nodeCount: snap.nodes.size,
+        edgeCount: snap.edges.size,
+        workspacePackages: snap.manifest.workspacePackages.length,
+        lastIndexedAt: snap.manifest.lastIndexedAt,
+        nodesByKind: snap.manifest.nodesByKind,
+        edgesByKind: snap.manifest.edgesByKind,
+    };
+}
+function readBridgeSection(store) {
+    const snap = store.loadSnapshot();
+    return {
+        available: true,
+        lastBuiltAt: snap.manifest.lastBuiltAt,
+        nodesByKind: snap.manifest.nodesByKind,
+        edgesByKind: snap.manifest.edgesByKind,
+        sourceCounts: snap.manifest.sourceCounts,
+    };
+}
+function readFrameworkSection(projectRoot) {
+    const api = FrameworkQueryApi.fromStore(projectRoot);
+    const manifest = api.manifest();
+    return {
+        available: true,
+        lastBuiltAt: manifest.lastBuiltAt,
+        frameworks: manifest.frameworks,
+        countsByFramework: manifest.countsByFramework,
+        countsBySubtype: manifest.countsBySubtype,
+    };
+}
+function readArchSection(projectRoot) {
+    // Honor an optional `sharkcraft/arch.ts` if present, but never load
+    // it dynamically inside the dashboard request path — keeping HTTP
+    // handlers synchronous and avoiding arbitrary code execution under
+    // the request. Default checks only.
+    const archPath = nodePath.join(projectRoot, 'sharkcraft', 'arch.ts');
+    void archPath;
+    const report = runArchCheck({ projectRoot });
+    return {
+        available: report.diagnostics.length === 0 || !report.diagnostics.some((d) => d.includes('code-graph store missing')),
+        errors: report.countsBySeverity.error,
+        warnings: report.countsBySeverity.warning,
+        violationsByKind: report.countsByKind,
+    };
+}
+function toRow(entity) {
+    const data = entity.data ?? {};
+    return {
+        framework: String(data['framework'] ?? '?'),
+        method: String(data['method'] ?? '?'),
+        path: String(data['path'] ?? data['routePath'] ?? '/'),
+        handler: String(data['handler'] ??
+            (data['className'] && data['handler']
+                ? `${data['className']}.${data['handler']}`
+                : data['name'] ?? '?')),
+        file: entity.path ?? '?',
+    };
+}
+/**
+ * Build the Migrations panel response.
+ *
+ * Reads every `.sharkcraft/migrations/*.state.json` (written by
+ * `@shrkcrft/migrate` after each step), shapes each into a dashboard
+ * row, and stamps `resumePoint` so the UI can highlight where a
+ * partially-failed migration would pick up.
+ */
+export function buildDashboardMigrations(projectRoot) {
+    const commandHints = [
+        {
+            label: 'Plan a migration',
+            command: 'shrk migrate plan <id>',
+            purpose: 'Preview the migration before any disk writes.',
+        },
+        {
+            label: 'Apply a migration',
+            command: 'shrk migrate apply <id>',
+            purpose: 'Execute the migration; checkpoints are written after every step.',
+        },
+        {
+            label: 'Resume a halted migration',
+            command: 'shrk migrate resume <id>',
+            purpose: 'Pick up at the failed step using the saved checkpoint.',
+        },
+    ];
+    const dir = nodePath.join(projectRoot, '.sharkcraft', 'migrations');
+    if (!existsSync(dir)) {
+        return {
+            schema: 'sharkcraft.dashboard-migrations/v1',
+            available: false,
+            total: 0,
+            migrations: [],
+            commandHints,
+            hint: 'no migrations have been run yet',
+        };
+    }
+    const rows = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.state.json'))
+            continue;
+        const abs = nodePath.join(dir, entry);
+        try {
+            const report = JSON.parse(readFileSync(abs, 'utf8'));
+            const resumePoint = findResumePoint(report);
+            rows.push({
+                id: report.migration.id,
+                title: report.migration.title,
+                overall: report.overall,
+                dryRun: report.dryRun,
+                startedAt: report.startedAt,
+                totalDurationMs: report.totalDurationMs,
+                steps: report.steps.map((s) => ({
+                    index: s.index,
+                    id: s.id,
+                    kind: s.kind,
+                    status: s.status,
+                    message: s.message,
+                    durationMs: s.durationMs,
+                })),
+                ...(resumePoint !== undefined ? { resumePoint } : {}),
+            });
+        }
+        catch {
+            /* corrupted state file — skip silently */
+        }
+    }
+    rows.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+    return {
+        schema: 'sharkcraft.dashboard-migrations/v1',
+        available: true,
+        total: rows.length,
+        migrations: rows,
+        commandHints,
+    };
+}
+/**
+ * Build the Quality-Gates panel response.
+ *
+ * Runs `runQualityGates` on request — the gate is cheap enough
+ * (<500 ms on a medium repo) that a fresh run beats stale data. The
+ * graph-fresh gate inside will surface "run `shrk graph index`" as a
+ * `nextCommand` when the store is missing, so the panel degrades
+ * gracefully.
+ */
+const QUALITY_GATE_REPORT_FRESH_MS = 5 * 60 * 1000;
+export function buildDashboardQualityGates(projectRoot) {
+    const commandHints = [
+        {
+            label: 'Run the gate locally',
+            command: 'shrk gate',
+            purpose: 'Same as the panel — writes a fresh .sharkcraft/quality-gates/last.json.',
+        },
+        {
+            label: 'Fail on warnings too',
+            command: 'shrk gate --strict',
+            purpose: 'Make `warn` exit 1 (useful for CI).',
+        },
+    ];
+    // Prefer a recent persisted report (written by `shrk gate`) over
+    // running every gate on every page load — the gate is cheap but the
+    // dashboard's polling loop is not.
+    const store = new QualityGateReportStore(projectRoot);
+    const saved = store.read();
+    const savedAge = store.ageMs();
+    const isFresh = saved !== undefined && savedAge !== undefined && savedAge <= QUALITY_GATE_REPORT_FRESH_MS;
+    const report = isFresh ? saved : runQualityGates({ projectRoot });
+    if (!isFresh) {
+        // Cache the freshly-computed report so subsequent dashboard
+        // requests reuse it.
+        try {
+            store.write(report);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    const gates = report.gates.map((g) => ({
+        id: g.id,
+        label: g.label,
+        status: g.status,
+        message: g.message,
+        durationMs: g.durationMs,
+        ...(g.nextCommands && g.nextCommands.length > 0 ? { nextCommands: g.nextCommands } : {}),
+    }));
+    return {
+        schema: 'sharkcraft.dashboard-quality-gates/v1',
+        overall: report.overall,
+        startedAt: report.startedAt,
+        totalDurationMs: report.totalDurationMs,
+        counts: report.counts,
+        gates,
+        commandHints,
+    };
+}
+void statSync;

package/dist/dashboard/dashboard-api-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-api-server.d.ts","sourceRoot":"","sources":["../../src/dashboard/dashboard-api-server.ts"],"names":[],"mappings":"AAsDA,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAcD,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAiC1F;AA4ZD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"dashboard-api-server.d.ts","sourceRoot":"","sources":["../../src/dashboard/dashboard-api-server.ts"],"names":[],"mappings":"AA4DA,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AA2BD,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqC1F;AA2jBD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}

package/dist/dashboard/dashboard-api-server.js

@@ -17,6 +17,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { buildDashboardAdoption, buildDashboardArchitecture, buildDashboardBoundaries, buildDashboardCapabilities, buildDashboardCommands, buildDashboardCoverage, buildDashboardDoctor, buildDashboardDrift, buildDashboardGraph, buildDashboardGraphNode, buildDashboardGraphPath, buildDashboardHealth, buildDashboardMcpSummary, buildDashboardOnboarding, buildDashboardOverview, buildDashboardPacks, buildDashboardPipelines, buildDashboardPresets, buildDashboardQuality, buildDashboardReports, buildDashboardReview, buildDashboardSafety, buildDashboardScaffolds, buildDashboardSchemas, buildDashboardSessionDetail, buildDashboardSessions, buildDashboardStats, inspectSharkcraft, renderDevSessionHtml, scanDevSession, } from '@shrkcrft/inspector';
 import { COMMAND_CATALOG } from "../commands/command-catalog.js";
+import { buildDashboardCodeIntelligence, buildDashboardMigrations, buildDashboardQualityGates, buildDashboardRoutes, } from "./code-intelligence-data.js";
 const SCHEMA_ID = 'sharkcraft.dashboard-api/v1';
 export async function startDashboardApiServer(opts) {
     const host = opts.host ?? '127.0.0.1';
@@ -26,7 +27,7 @@ export async function startDashboardApiServer(opts) {
     }
     const startedAt = Date.now();
     const sessionHubs = new Map();
-    const ctx = { opts, startedAt, sessionHubs };
+    const ctx = { opts, startedAt, sessionHubs, globalHub: null };
     const server = http.createServer(async (req, res) => {
         try {
             await handle(req, res, ctx);
@@ -47,6 +48,10 @@ export async function startDashboardApiServer(opts) {
             for (const hub of sessionHubs.values())
                 closeHub(hub);
             sessionHubs.clear();
+            if (ctx.globalHub) {
+                closeGlobalHub(ctx.globalHub);
+                ctx.globalHub = null;
+            }
             server.close(() => resolve());
         }),
     };
@@ -115,6 +120,121 @@ function ensureSessionHub(ctx, sessionId) {
     ctx.sessionHubs.set(sessionId, hub);
     return hub;
 }
+/**
+ * Watched subdirectories under `.sharkcraft/` for the global hub.
+ * Order matters only for diagnostics — the event emitted is `change:<name>`.
+ *
+ *   - `graph/`: the code-graph store; fires after `shrk graph index`.
+ *   - `bridge/`: the rule-graph bridge.
+ *   - `framework/`: framework-scanner outputs.
+ *   - `migrations/`: migrate run state (one file per migration).
+ *   - `api-surface/`: api-surface-diff caches.
+ *   - `quality-gates/`: persisted gate reports.
+ */
+const GLOBAL_WATCH_DIRS = [
+    'graph',
+    'bridge',
+    'framework',
+    'migrations',
+    'api-surface',
+    'quality-gates',
+];
+function closeGlobalHub(hub) {
+    if (hub.debounceTimer) {
+        clearTimeout(hub.debounceTimer);
+        hub.debounceTimer = null;
+    }
+    for (const w of hub.watchers) {
+        try {
+            w.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    hub.watchers = [];
+    hub.subscribers.clear();
+}
+function ensureGlobalHub(ctx) {
+    if (ctx.globalHub)
+        return ctx.globalHub;
+    const hub = {
+        subscribers: new Set(),
+        watchers: [],
+        version: 0,
+        debounceTimer: null,
+        lastEvent: null,
+    };
+    const broadcast = (name) => {
+        if (hub.debounceTimer)
+            clearTimeout(hub.debounceTimer);
+        hub.debounceTimer = setTimeout(() => {
+            hub.version += 1;
+            hub.lastEvent = name;
+            const line = `event: change\ndata: ${name}\nid: ${hub.version}\n\n`;
+            for (const send of [...hub.subscribers]) {
+                try {
+                    send(line);
+                }
+                catch {
+                    hub.subscribers.delete(send);
+                }
+            }
+        }, 200);
+    };
+    for (const dir of GLOBAL_WATCH_DIRS) {
+        const target = nodePath.join(ctx.opts.cwd, '.sharkcraft', dir);
+        if (!fs.existsSync(target))
+            continue;
+        try {
+            const w = fs.watch(target, { recursive: true }, () => broadcast(dir));
+            hub.watchers.push(w);
+        }
+        catch {
+            try {
+                const w = fs.watch(target, () => broadcast(dir));
+                hub.watchers.push(w);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    ctx.globalHub = hub;
+    return hub;
+}
+function serveGlobalEvents(req, res, ctx) {
+    const hub = ensureGlobalHub(ctx);
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+        connection: 'keep-alive',
+    });
+    const send = (line) => {
+        res.write(line);
+    };
+    hub.subscribers.add(send);
+    send(`event: hello\ndata: ${hub.lastEvent ?? 'ready'}\nid: ${hub.version}\n\n`);
+    const ping = setInterval(() => {
+        try {
+            res.write(`: ping\n\n`);
+        }
+        catch {
+            /* ignore */
+        }
+    }, 15000);
+    const close = () => {
+        clearInterval(ping);
+        hub.subscribers.delete(send);
+        if (hub.subscribers.size === 0) {
+            closeGlobalHub(hub);
+            ctx.globalHub = null;
+        }
+    };
+    req.on('close', close);
+    req.on('end', close);
+}
 async function handle(req, res, ctx) {
     if (req.method !== 'GET' && req.method !== 'HEAD') {
         res.setHeader('allow', 'GET, HEAD');
@@ -129,11 +249,21 @@ async function handle(req, res, ctx) {
     if (!path.startsWith('/api/') && opts.staticDir) {
         return serveStatic(res, opts.staticDir, path);
     }
+    // Non-API request with no static UI installed. Common when @shrkcrft/cli
+    // is consumed without @shrkcrft/dashboard present. Return a helpful page
+    // instead of falling through to the cryptic "Unknown route: /".
+    if (!path.startsWith('/api/') && !opts.staticDir) {
+        return serveNoUiHint(res, path);
+    }
     // Session live events (SSE). Subscribe via EventSource on the session detail page.
     const sseMatch = path.match(/^\/api\/sessions\/([^/]+)\/events$/);
     if (sseMatch) {
         return serveSessionEvents(req, res, ctx, decodeURIComponent(sseMatch[1]));
     }
+    // Global live events (SSE). Subscribers refetch on every change.
+    if (path === '/api/events') {
+        return serveGlobalEvents(req, res, ctx);
+    }
     // Rendered HTML report for the session (or any report on disk under the
     // session dir). Served with a content-security-policy that disallows
     // anything but inline styles — the report renderer never emits scripts,
@@ -172,6 +302,18 @@ async function handle(req, res, ctx) {
         });
         return respond(res, buildEnvelope(projectRoot, stats));
     }
+    if (path === '/api/code-intelligence') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardCodeIntelligence(projectRoot)));
+    }
+    if (path === '/api/routes') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardRoutes(projectRoot)));
+    }
+    if (path === '/api/migrations') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardMigrations(projectRoot)));
+    }
+    if (path === '/api/quality-gates') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardQualityGates(projectRoot)));
+    }
     // For data routes that need inspection, load once per request.
     const needsInspection = path.startsWith('/api/overview') ||
         path.startsWith('/api/doctor') ||
@@ -369,6 +511,25 @@ function serveSessionReportHtml(res, cwd, sessionId) {
     }
     res.end(html);
 }
+function serveNoUiHint(res, urlPath) {
+    const accept = (res.req?.headers['accept'] ?? '');
+    const wantsHtml = accept.includes('text/html');
+    if (wantsHtml) {
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>SharkCraft dashboard — UI not installed</title><meta name="viewport" content="width=device-width,initial-scale=1"><style>body{font-family:ui-sans-serif,system-ui,-apple-system,sans-serif;max-width:680px;margin:48px auto;padding:0 16px;color:#1f2937;line-height:1.55}code,pre{background:#f3f4f6;padding:2px 6px;border-radius:4px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px}pre{padding:12px;overflow:auto}h1{font-size:20px;margin-top:0}a{color:#2563eb}</style></head><body><h1>SharkCraft dashboard</h1><p>The API is running, but the web UI bundle (<code>@shrkcrft/dashboard</code>) was not found next to <code>@shrkcrft/cli</code>.</p><p>Install or upgrade it alongside the CLI:</p><pre>npm i -D @shrkcrft/dashboard@alpha</pre><p>Or point the server at a local build:</p><pre>shrk dashboard --dev-assets path/to/dashboard/dist</pre><p>The API itself is available — try <a href="/api/health">/api/health</a> or <a href="/api/overview">/api/overview</a>.</p></body></html>`;
+        res.statusCode = 200;
+        res.setHeader('content-type', 'text/html; charset=utf-8');
+        res.setHeader('cache-control', 'no-store');
+        res.setHeader('x-content-type-options', 'nosniff');
+        res.setHeader('referrer-policy', 'no-referrer');
+        if ((res.req?.method ?? 'GET') === 'HEAD') {
+            res.end();
+            return;
+        }
+        res.end(html);
+        return;
+    }
+    respondError(res, 404, 'not-found', `No UI assets installed; ${urlPath} cannot be served. Install @shrkcrft/dashboard or pass --dev-assets.`);
+}
 function serveStatic(res, staticDir, urlPath) {
     // Strip leading / and resolve against staticDir. Reject traversal.
     const rel = urlPath.replace(/^\/+/, '');

package/dist/export/claude-commands-export.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `.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.
+ */
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+export interface IClaudeCommandFile {
+    /** Path relative to project root (e.g. `.claude/commands/new-service.md`). */
+    path: string;
+    /** Full markdown body, including YAML frontmatter. */
+    content: string;
+    /** The slash name users type (e.g. `new-service` → `/new-service`). */
+    slash: string;
+    /** Why this command was generated — surfaces in the dry-run summary. */
+    source: 'static' | 'template';
+}
+export interface IClaudeCommandsResult {
+    files: readonly IClaudeCommandFile[];
+}
+export interface IClaudeCommandsOptions {
+    /**
+     * Cap on the number of per-template commands to emit. Default 20.
+     * Templates are sorted by id; the first N are kept.
+     */
+    maxTemplateCommands?: number;
+}
+/**
+ * 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 declare function buildClaudeCommands(inspection: ISharkcraftInspection, options?: IClaudeCommandsOptions): IClaudeCommandsResult;
+//# sourceMappingURL=claude-commands-export.d.ts.map

package/dist/export/claude-commands-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-commands-export.d.ts","sourceRoot":"","sources":["../../src/export/claude-commands-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACtC;AA0MD,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAsDvB"}