@shrkcrft/inspector 0.1.0-alpha.2

package/dist/pack-symbol-compat.js

@@ -0,0 +1,371 @@
+/**
+ * Plugin-api symbol compatibility diff.
+ *
+ * Reads `import { … } from '@shrkcrft/plugin-api'` lines from each pack
+ * contribution file, resolves the consumer's installed plugin-api source,
+ * and reports which symbols the pack uses that the consumer's plugin-api
+ * does not export.
+ *
+ * This is intentionally a regex/structural parser — we do not depend on
+ * the TypeScript compiler. The goal is to catch the dominant failure
+ * mode (`Export named 'X' not found in module '@shrkcrft/plugin-api'`)
+ * before publish, not to be a full module-graph analyser.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const PACK_SYMBOL_COMPAT_SCHEMA = 'sharkcraft.pack-symbol-compat/v1';
+const NAMED_IMPORT_RE = /^\s*import\s*(?:type\s+)?\{([^}]+)\}\s*from\s*['"]@shrkcrft\/plugin-api['"]/;
+const DEFAULT_IMPORT_RE = /^\s*import\s+(\w+)\s*(?:,\s*\{([^}]+)\})?\s*from\s*['"]@shrkcrft\/plugin-api['"]/;
+function listContributionFiles(packPath) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry === 'node_modules' || entry.startsWith('.'))
+                continue;
+            const full = nodePath.join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory())
+                walk(full);
+            else if (/\.(ts|tsx|mts|cts|js|mjs|cjs)$/.test(entry) && !entry.endsWith('.d.ts')) {
+                out.push(full);
+            }
+        }
+    };
+    const srcDir = nodePath.join(packPath, 'src');
+    walk(existsSync(srcDir) ? srcDir : packPath);
+    return out;
+}
+function extractImports(file) {
+    let body;
+    try {
+        body = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const raw of body.split(/\r?\n/)) {
+        const named = raw.match(NAMED_IMPORT_RE);
+        if (named) {
+            for (const symbol of named[1].split(',')) {
+                const clean = symbol.replace(/\s+as\s+\w+/, '').trim();
+                if (clean)
+                    names.push(clean);
+            }
+            continue;
+        }
+        const def = raw.match(DEFAULT_IMPORT_RE);
+        if (def) {
+            // Default import — track as a symbol name. Plugin-api has no default
+            // export today, so this is mostly diagnostic.
+            names.push(def[1]);
+            if (def[2]) {
+                for (const symbol of def[2].split(',')) {
+                    const clean = symbol.replace(/\s+as\s+\w+/, '').trim();
+                    if (clean)
+                        names.push(clean);
+                }
+            }
+        }
+    }
+    return names;
+}
+function inferSourceMode(rel) {
+    if (rel.startsWith('src/'))
+        return 'source';
+    if (rel.endsWith('.d.ts'))
+        return 'declaration';
+    if (rel.endsWith('.js') || rel.endsWith('.cjs') || rel.endsWith('.mjs'))
+        return 'dist-js';
+    return 'fallback';
+}
+function resolvePluginApi(consumerRoot, packPath) {
+    const candidates = [];
+    if (consumerRoot) {
+        candidates.push({
+            dir: nodePath.join(consumerRoot, 'node_modules', '@shrkcrft', 'plugin-api'),
+            resolution: 'consumer-node-modules',
+        });
+    }
+    candidates.push({
+        dir: nodePath.join(packPath, 'node_modules', '@shrkcrft', 'plugin-api'),
+        resolution: 'pack-node-modules',
+    });
+    for (const c of candidates) {
+        if (!existsSync(c.dir))
+            continue;
+        // Prefer the source `src/index.ts` (symlinked monorepo); fall back to
+        // `dist/index.js` / `dist/index.d.ts`.
+        const choices = [
+            'src/index.ts',
+            'dist/index.d.ts',
+            'dist/index.js',
+            'dist/index.mjs',
+            'dist/index.cjs',
+            'index.d.ts',
+            'index.js',
+            'index.cjs',
+        ];
+        for (const rel of choices) {
+            const full = nodePath.join(c.dir, rel);
+            if (existsSync(full)) {
+                const resolution = rel.startsWith('src/') && c.resolution === 'consumer-node-modules'
+                    ? 'consumer-symlink'
+                    : c.resolution;
+                return { source: full, resolution, sourceMode: inferSourceMode(rel) };
+            }
+        }
+    }
+    return { source: '', resolution: 'not-found', sourceMode: 'none' };
+}
+/**
+ * Collect CJS/UMD-style exports from a built JavaScript bundle.
+ * Handles the patterns that bun, tsc, esbuild and rollup emit:
+ *   - `Object.defineProperty(exports, "X", { ... })`
+ *   - `exports.X = ...`
+ *   - `module.exports.X = ...`
+ *   - `module.exports = { X, Y }`
+ *   - ESM bundles: `export const X`, `export { X }`, `export function X`
+ */
+const CJS_DEFINE_PROP_RE = /Object\.defineProperty\(\s*exports\s*,\s*['"]([A-Za-z_$][\w$]*)['"]/g;
+const CJS_EXPORTS_ASSIGN_RE = /\bexports\s*\.\s*([A-Za-z_$][\w$]*)\s*=/g;
+const CJS_MODULE_EXPORTS_PROP_RE = /\bmodule\s*\.\s*exports\s*\.\s*([A-Za-z_$][\w$]*)\s*=/g;
+const CJS_MODULE_EXPORTS_OBJECT_RE = /\bmodule\s*\.\s*exports\s*=\s*\{([^}]+)\}/;
+function collectJsExports(file) {
+    const out = new Set();
+    let body;
+    try {
+        body = readFileSync(file, 'utf8');
+    }
+    catch {
+        return out;
+    }
+    for (const m of body.matchAll(CJS_DEFINE_PROP_RE)) {
+        if (m[1] && m[1] !== '__esModule')
+            out.add(m[1]);
+    }
+    for (const m of body.matchAll(CJS_EXPORTS_ASSIGN_RE)) {
+        if (m[1] && m[1] !== '__esModule')
+            out.add(m[1]);
+    }
+    for (const m of body.matchAll(CJS_MODULE_EXPORTS_PROP_RE)) {
+        if (m[1] && m[1] !== '__esModule')
+            out.add(m[1]);
+    }
+    const objMatch = body.match(CJS_MODULE_EXPORTS_OBJECT_RE);
+    if (objMatch && objMatch[1]) {
+        for (const piece of objMatch[1].split(',')) {
+            const name = piece.split(':')[0]?.trim();
+            if (name && /^[A-Za-z_$][\w$]*$/.test(name))
+                out.add(name);
+        }
+    }
+    // Also pick up ESM-style `export const`/`export function`/`export { X }`
+    for (const raw of body.split(/\r?\n/)) {
+        const named = raw.match(EXPORT_NAMED_RE);
+        if (named && named[1])
+            out.add(named[1]);
+        const block = raw.match(EXPORT_BLOCK_RE);
+        if (block && !/from\s+['"]/.test(raw)) {
+            for (const symbol of block[1].split(',')) {
+                const clean = symbol.replace(/\s+as\s+(\w+)/, '$1').trim();
+                if (clean && /^[A-Za-z_$][\w$]*$/.test(clean))
+                    out.add(clean);
+            }
+        }
+    }
+    return out;
+}
+const EXPORT_NAMED_RE = /^\s*export\s+(?:async\s+)?(?:declare\s+)?(?:function|class|interface|enum|type|const|let|var)\s+(\w+)/;
+const EXPORT_BLOCK_RE = /^\s*export\s*\{([^}]+)\}/;
+const RE_EXPORT_RE = /^\s*export\s*\*\s+from\s*['"]([^'"]+)['"]/;
+const RE_EXPORT_NAMED_RE = /^\s*export\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/;
+function collectExports(file, visited) {
+    if (visited.has(file))
+        return new Set();
+    visited.add(file);
+    const out = new Set();
+    let body;
+    try {
+        body = readFileSync(file, 'utf8');
+    }
+    catch {
+        return out;
+    }
+    for (const raw of body.split(/\r?\n/)) {
+        const named = raw.match(EXPORT_NAMED_RE);
+        if (named) {
+            out.add(named[1]);
+            continue;
+        }
+        const block = raw.match(EXPORT_BLOCK_RE);
+        if (block && !/from\s+['"]/.test(raw)) {
+            for (const symbol of block[1].split(',')) {
+                const clean = symbol.replace(/\s+as\s+(\w+)/, '$1').trim();
+                if (clean)
+                    out.add(clean);
+            }
+            continue;
+        }
+        const reExport = raw.match(RE_EXPORT_RE);
+        if (reExport) {
+            const childRel = reExport[1];
+            const candidate = resolveRelative(file, childRel);
+            if (candidate) {
+                for (const symbol of collectExports(candidate, visited))
+                    out.add(symbol);
+            }
+            continue;
+        }
+        const reExportNamed = raw.match(RE_EXPORT_NAMED_RE);
+        if (reExportNamed) {
+            for (const symbol of reExportNamed[1].split(',')) {
+                const clean = symbol.replace(/\s+as\s+(\w+)/, '$1').trim();
+                if (clean)
+                    out.add(clean);
+            }
+        }
+    }
+    return out;
+}
+function resolveRelative(fromFile, rel) {
+    if (!rel.startsWith('.'))
+        return null;
+    const base = nodePath.resolve(nodePath.dirname(fromFile), rel);
+    const candidates = [
+        base + '.ts',
+        base + '.tsx',
+        base + '.js',
+        base + '.mjs',
+        base + '.cjs',
+        nodePath.join(base, 'index.ts'),
+        nodePath.join(base, 'index.tsx'),
+        nodePath.join(base, 'index.js'),
+    ];
+    for (const c of candidates)
+        if (existsSync(c))
+            return c;
+    return null;
+}
+function confidenceFor(mode, count) {
+    if (mode === 'source' || mode === 'declaration')
+        return 'high';
+    if (mode === 'dist-js' && count >= 3)
+        return 'medium';
+    if (mode === 'dist-js')
+        return 'low';
+    if (mode === 'none')
+        return 'low';
+    return 'low';
+}
+export function checkPackSymbolCompat(input) {
+    const packAbs = nodePath.resolve(input.packPath);
+    const consumerRoot = input.consumerRoot ? nodePath.resolve(input.consumerRoot) : null;
+    const resolved = resolvePluginApi(consumerRoot, packAbs);
+    const filesInspected = [];
+    let availableSet = new Set();
+    let usedMode = resolved.sourceMode;
+    if (resolved.source.length > 0) {
+        if (resolved.sourceMode === 'dist-js') {
+            availableSet = collectJsExports(resolved.source);
+            filesInspected.push(resolved.source);
+        }
+        else {
+            availableSet = collectExports(resolved.source, new Set());
+            filesInspected.push(resolved.source);
+        }
+    }
+    // Dist-aware mode — when explicitly requested, also scan dist/*.js to
+    // pick up exports a declaration file omits.
+    if (input.distAware && consumerRoot) {
+        const distDir = nodePath.join(consumerRoot, 'node_modules', '@shrkcrft', 'plugin-api', 'dist');
+        if (existsSync(distDir)) {
+            for (const entry of safeReaddir(distDir)) {
+                if (!/\.(js|cjs|mjs)$/.test(entry))
+                    continue;
+                const full = nodePath.join(distDir, entry);
+                for (const s of collectJsExports(full))
+                    availableSet.add(s);
+                filesInspected.push(full);
+            }
+            if (resolved.sourceMode === 'declaration')
+                usedMode = 'dist-js';
+        }
+    }
+    const importsByFile = [];
+    const symbolToFiles = new Map();
+    for (const file of listContributionFiles(packAbs)) {
+        const symbols = extractImports(file);
+        if (symbols.length === 0)
+            continue;
+        importsByFile.push({ file, importedSymbols: symbols });
+        for (const s of symbols) {
+            let list = symbolToFiles.get(s);
+            if (!list) {
+                list = new Set();
+                symbolToFiles.set(s, list);
+            }
+            list.add(file);
+        }
+    }
+    const findings = [];
+    for (const [symbol, files] of symbolToFiles) {
+        const status = availableSet.has(symbol) ? 'available' : 'missing';
+        findings.push({ symbol, files: [...files], status });
+    }
+    findings.sort((a, b) => a.symbol.localeCompare(b.symbol));
+    const missingSymbols = findings.filter((f) => f.status === 'missing').map((f) => f.symbol);
+    const suggestions = [];
+    if (missingSymbols.length === 0) {
+        if (resolved.resolution === 'not-found') {
+            suggestions.push('No installed @shrkcrft/plugin-api was found. Pass --consumer-root to point at the consumer workspace if symbols differ across versions.');
+        }
+    }
+    else {
+        suggestions.push(`Pack imports ${missingSymbols.length} symbol(s) that the consumer's @shrkcrft/plugin-api does not export.`);
+        suggestions.push(`1. Bump @shrkcrft/plugin-api in the consumer workspace to a version that exports ${missingSymbols
+            .slice(0, 4)
+            .map((s) => '`' + s + '`')
+            .join(', ')}${missingSymbols.length > 4 ? ', …' : ''}.`);
+        suggestions.push('2. Widen `peerDependencies."@shrkcrft/plugin-api"` only if those symbols are stable across the range.');
+        suggestions.push('3. Replace the helper imports with plain structural object literals (`export default ([...] as const)`).');
+        suggestions.push('4. Drop the import entirely if the helper is no longer needed by your contributions.');
+    }
+    return {
+        schema: PACK_SYMBOL_COMPAT_SCHEMA,
+        packPath: packAbs,
+        consumerRoot,
+        pluginApiSource: resolved.source || null,
+        pluginApiResolution: resolved.resolution,
+        availableSymbols: [...availableSet].sort(),
+        findings,
+        missingSymbols,
+        imports: importsByFile,
+        compatible: missingSymbols.length === 0,
+        suggestions,
+        sourceMode: usedMode,
+        confidence: confidenceFor(usedMode, availableSet.size),
+        filesInspected,
+    };
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/pack-test-runner.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pack test runner.
+ *
+ * Test case model: `definePackTest({ id, task, expect*Ids?, mustNotIncludeIds?, maxTokens? })`.
+ * Test cases live in either:
+ *   <packRoot>/sharkcraft/pack-tests.ts
+ *   <packRoot>/src/assets/pack-tests.ts
+ *
+ * The runner:
+ *   1. Loads the pack tests via dynamic import (Bun handles TS natively).
+ *   2. For each test case, builds a task packet against an isolated inspection.
+ *   3. Validates the packet contains every `expect*Ids` and none of the
+ *      `mustNotIncludeIds`, optionally capping the token budget.
+ *   4. Emits a structured diagnostic report.
+ */
+export interface IPackTestCase {
+    id: string;
+    task: string;
+    description?: string;
+    expectKnowledgeIds?: ReadonlyArray<string>;
+    expectRuleIds?: ReadonlyArray<string>;
+    expectTemplateIds?: ReadonlyArray<string>;
+    expectPipelineIds?: ReadonlyArray<string>;
+    expectPlaybookIds?: ReadonlyArray<string>;
+    expectConstructIds?: ReadonlyArray<string>;
+    mustNotIncludeIds?: ReadonlyArray<string>;
+    maxTokens?: number;
+}
+export declare function definePackTest<T extends IPackTestCase>(t: T): T;
+export interface IPackTestResult {
+    id: string;
+    task: string;
+    passed: boolean;
+    diagnostics: ReadonlyArray<{
+        code: 'missing-id' | 'unexpected-id' | 'token-budget' | 'load-error';
+        field?: string;
+        expected?: string;
+        actual?: string;
+        suggestion?: string;
+        message: string;
+    }>;
+    tokenEstimate?: number;
+}
+export interface IPackTestReport {
+    schema: 'sharkcraft.pack-test-report/v1';
+    packPath: string;
+    testsFile: string | null;
+    ran: number;
+    passed: number;
+    failed: number;
+    cases: ReadonlyArray<IPackTestResult>;
+}
+export declare function runPackTests(input: {
+    packPath: string;
+    caseId?: string;
+    updateSnapshots?: boolean;
+}): Promise<IPackTestReport>;
+export declare function renderPackTestReportText(report: IPackTestReport): string;
+//# sourceMappingURL=pack-test-runner.d.ts.map

package/dist/pack-test-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-test-runner.d.ts","sourceRoot":"","sources":["../src/pack-test-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,kBAAkB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAE/D;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,aAAa,CAAC;QACzB,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,cAAc,GAAG,YAAY,CAAC;QACrE,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gCAAgC,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACvC;AA4HD,wBAAsB,YAAY,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,eAAe,CAAC,CAgE3B;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBxE"}

package/dist/pack-test-runner.js

@@ -0,0 +1,211 @@
+/**
+ * Pack test runner.
+ *
+ * Test case model: `definePackTest({ id, task, expect*Ids?, mustNotIncludeIds?, maxTokens? })`.
+ * Test cases live in either:
+ *   <packRoot>/sharkcraft/pack-tests.ts
+ *   <packRoot>/src/assets/pack-tests.ts
+ *
+ * The runner:
+ *   1. Loads the pack tests via dynamic import (Bun handles TS natively).
+ *   2. For each test case, builds a task packet against an isolated inspection.
+ *   3. Validates the packet contains every `expect*Ids` and none of the
+ *      `mustNotIncludeIds`, optionally capping the token budget.
+ *   4. Emits a structured diagnostic report.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { inspectSharkcraft } from "./sharkcraft-inspector.js";
+import { buildTaskPacket } from "./task-packet.js";
+export function definePackTest(t) {
+    return t;
+}
+const TEST_FILE_CANDIDATES = [
+    'sharkcraft/pack-tests.ts',
+    'src/assets/pack-tests.ts',
+    'pack-tests.ts',
+];
+function findTestsFile(packPath) {
+    for (const rel of TEST_FILE_CANDIDATES) {
+        const abs = join(packPath, rel);
+        if (existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+async function loadTestCases(file) {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    const list = mod.default ?? mod.tests ?? [];
+    return [...list];
+}
+function unique(arr) {
+    return [...new Set(arr)];
+}
+async function summariseTaskPacket(packPath, task) {
+    const inspection = await inspectSharkcraft({ cwd: packPath });
+    const packet = buildTaskPacket(inspection, task);
+    const knowledgeIds = unique(packet.context.sections.flatMap((s) => [...s.entryIds]));
+    const ruleIds = unique(packet.relevantRules.map((r) => r.id));
+    const templateIds = unique(packet.relevantTemplates.map((t) => t.id));
+    const pipelineIds = unique(packet.recommendedPipelines.map((p) => p.pipelineId));
+    return {
+        knowledgeIds,
+        ruleIds,
+        templateIds,
+        pipelineIds,
+        playbookIds: [],
+        constructIds: [],
+        tokenEstimate: packet.tokenEstimate,
+    };
+}
+function evaluateCase(testCase, packet) {
+    const diagnostics = [];
+    const checks = [
+        { field: 'knowledgeIds', expected: testCase.expectKnowledgeIds },
+        { field: 'ruleIds', expected: testCase.expectRuleIds },
+        { field: 'templateIds', expected: testCase.expectTemplateIds },
+        { field: 'pipelineIds', expected: testCase.expectPipelineIds },
+    ];
+    for (const c of checks) {
+        if (!c.expected)
+            continue;
+        const actualList = packet[c.field];
+        for (const id of c.expected) {
+            if (!actualList.includes(id)) {
+                diagnostics.push({
+                    code: 'missing-id',
+                    field: c.field,
+                    expected: id,
+                    suggestion: `Add ${id} to the pack's ${c.field} or to the recommender for "${testCase.task}".`,
+                    message: `Expected ${c.field} to include "${id}" for task "${testCase.task}", but it did not.`,
+                });
+            }
+        }
+    }
+    if (testCase.mustNotIncludeIds && testCase.mustNotIncludeIds.length > 0) {
+        const allIds = unique([
+            ...packet.knowledgeIds,
+            ...packet.ruleIds,
+            ...packet.templateIds,
+            ...packet.pipelineIds,
+        ]);
+        for (const id of testCase.mustNotIncludeIds) {
+            if (allIds.includes(id)) {
+                diagnostics.push({
+                    code: 'unexpected-id',
+                    expected: id,
+                    actual: id,
+                    message: `"${id}" should not have been included in the packet for task "${testCase.task}".`,
+                });
+            }
+        }
+    }
+    if (testCase.maxTokens && packet.tokenEstimate > testCase.maxTokens) {
+        diagnostics.push({
+            code: 'token-budget',
+            message: `Token estimate ${packet.tokenEstimate} exceeds maxTokens=${testCase.maxTokens}.`,
+        });
+    }
+    return {
+        id: testCase.id,
+        task: testCase.task,
+        passed: diagnostics.length === 0,
+        diagnostics,
+        tokenEstimate: packet.tokenEstimate,
+    };
+}
+export async function runPackTests(input) {
+    const { packPath, caseId } = input;
+    const testsFile = findTestsFile(packPath);
+    if (!testsFile) {
+        return {
+            schema: 'sharkcraft.pack-test-report/v1',
+            packPath,
+            testsFile: null,
+            ran: 0,
+            passed: 0,
+            failed: 0,
+            cases: [],
+        };
+    }
+    let cases;
+    try {
+        cases = await loadTestCases(testsFile);
+    }
+    catch (e) {
+        return {
+            schema: 'sharkcraft.pack-test-report/v1',
+            packPath,
+            testsFile,
+            ran: 0,
+            passed: 0,
+            failed: 1,
+            cases: [
+                {
+                    id: '(load)',
+                    task: '(load)',
+                    passed: false,
+                    diagnostics: [
+                        {
+                            code: 'load-error',
+                            message: `Failed to load pack tests from ${testsFile}: ${e.message}`,
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    if (caseId)
+        cases = cases.filter((c) => c.id === caseId);
+    const results = [];
+    for (const tc of cases) {
+        const summary = await summariseTaskPacket(packPath, tc.task);
+        results.push(evaluateCase(tc, summary));
+    }
+    if (input.updateSnapshots) {
+        const snapsDir = join(packPath, 'sharkcraft', 'pack-test-snapshots');
+        mkdirSync(snapsDir, { recursive: true });
+        for (const r of results) {
+            const file = join(snapsDir, `${r.id}.json`);
+            writeFileSync(file, JSON.stringify(r, null, 2) + '\n', 'utf8');
+        }
+    }
+    const passed = results.filter((r) => r.passed).length;
+    return {
+        schema: 'sharkcraft.pack-test-report/v1',
+        packPath,
+        testsFile,
+        ran: results.length,
+        passed,
+        failed: results.length - passed,
+        cases: results,
+    };
+}
+export function renderPackTestReportText(report) {
+    const lines = [];
+    lines.push(`=== Pack tests ===`);
+    lines.push(`  pack         ${report.packPath}`);
+    lines.push(`  tests file   ${report.testsFile ?? '(none)'}`);
+    lines.push(`  ran          ${report.ran}`);
+    lines.push(`  passed       ${report.passed}`);
+    lines.push(`  failed       ${report.failed}`);
+    lines.push('');
+    for (const c of report.cases) {
+        lines.push(`  ${c.passed ? '✓' : '✗'} ${c.id}  ${c.task}`);
+        for (const d of c.diagnostics) {
+            lines.push(`      - [${d.code}] ${d.message}`);
+            if (d.suggestion)
+                lines.push(`        ↳ ${d.suggestion}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/pipeline-command-dictionary.d.ts

@@ -0,0 +1,2 @@
+export declare const COMMAND_DICTIONARY: readonly string[];
+//# sourceMappingURL=pipeline-command-dictionary.d.ts.map

package/dist/pipeline-command-dictionary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-command-dictionary.d.ts","sourceRoot":"","sources":["../src/pipeline-command-dictionary.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAmB9C,CAAC"}

package/dist/pipeline-command-dictionary.js

@@ -0,0 +1,20 @@
+export const COMMAND_DICTIONARY = Object.freeze([
+    'shrk',
+    'bun',
+    'bunx',
+    'npm',
+    'npx',
+    'pnpm',
+    'yarn',
+    'node',
+    'tsc',
+    'eslint',
+    'prettier',
+    'git',
+    'echo',
+    'rm',
+    'mv',
+    'cp',
+    'mkdir',
+    'cat',
+]);