@shrkcrft/inspector 0.1.0-alpha.1

package/dist/pack-docs.d.ts

@@ -0,0 +1,11 @@
+export declare const PACK_DOCS_SCHEMA = "sharkcraft.pack-docs/v1";
+export interface IPackDocsPreview {
+    schema: typeof PACK_DOCS_SCHEMA;
+    packPath: string;
+    packName: string;
+    packVersion: string;
+    body: string;
+    files: readonly string[];
+}
+export declare function generatePackDocs(packPath: string): IPackDocsPreview;
+//# sourceMappingURL=pack-docs.d.ts.map

package/dist/pack-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-docs.d.ts","sourceRoot":"","sources":["../src/pack-docs.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,gBAAgB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAkCD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAiFnE"}

package/dist/pack-docs.js

@@ -0,0 +1,101 @@
+/**
+ * Pack docs generator.
+ *
+ * Generates a self-contained README-style markdown for a pack: manifest
+ * summary, contributions table, install/verify commands, safety notes,
+ * compatibility notes, release-check result.
+ *
+ * Read-only — produces a body string (the caller decides where to write).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const PACK_DOCS_SCHEMA = 'sharkcraft.pack-docs/v1';
+function loadManifest(packPath) {
+    const pkgJsonPath = nodePath.join(packPath, 'package.json');
+    if (!existsSync(pkgJsonPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function generatePackDocs(packPath) {
+    const m = loadManifest(packPath) ?? {};
+    const sk = m.sharkcraft ?? {};
+    const name = m.name ?? nodePath.basename(packPath);
+    const version = m.version ?? '0.0.0';
+    const lines = [];
+    lines.push(`# ${name}`);
+    lines.push('');
+    if (m.description) {
+        lines.push(m.description);
+        lines.push('');
+    }
+    lines.push(`> Pack manifest: \`sharkcraft.pack/${sk.manifestVersion ?? 'v1'}\` · version **${version}**`);
+    lines.push('');
+    lines.push('## Contributions');
+    lines.push('');
+    lines.push('| kind | files |');
+    lines.push('|---|---|');
+    const rows = [
+        { kind: 'knowledge', files: sk.knowledgeFiles },
+        { kind: 'rules', files: sk.ruleFiles },
+        { kind: 'paths', files: sk.pathFiles },
+        { kind: 'templates', files: sk.templateFiles },
+        { kind: 'pipelines', files: sk.pipelineFiles },
+        { kind: 'docs', files: sk.docsFiles },
+        { kind: 'presets', files: sk.presetFiles },
+        { kind: 'scaffold patterns', files: sk.scaffoldPatternFiles },
+        { kind: 'policy checks', files: sk.policyCheckFiles },
+        { kind: 'constructs', files: sk.constructFiles },
+        { kind: 'construct facets', files: sk.constructFacetFiles },
+        { kind: 'playbooks', files: sk.playbookFiles },
+    ];
+    let totalFiles = 0;
+    const allFiles = [];
+    for (const r of rows) {
+        const count = r.files?.length ?? 0;
+        if (count === 0)
+            continue;
+        totalFiles += count;
+        lines.push(`| ${r.kind} | ${count} |`);
+        if (r.files)
+            allFiles.push(...r.files);
+    }
+    if (totalFiles === 0)
+        lines.push('| (none) | 0 |');
+    lines.push('');
+    lines.push('## Install + verify');
+    lines.push('');
+    lines.push('```bash');
+    lines.push(`bun add ${name}`);
+    lines.push('shrk packs doctor --require-signatures');
+    lines.push(`shrk packs release-check ${name}`);
+    lines.push('```');
+    lines.push('');
+    lines.push('## Safety notes');
+    lines.push('');
+    lines.push('- SharkCraft never auto-runs pack-contributed verification commands. Only commands listed in your local `sharkcraft.config.ts verificationCommands[]` are eligible for `shrk apply --validate`.');
+    lines.push(`- The pack manifest can be HMAC-signed; verify with \`shrk packs verify ${name}\` after install.`);
+    if (sk.signature) {
+        lines.push('- This pack ships a signed manifest.');
+    }
+    else {
+        lines.push('- This pack does **not** ship a signed manifest. Sign it before publishing: `shrk packs sign <path> --verify-after-sign`.');
+    }
+    lines.push('');
+    lines.push('## Compatibility');
+    lines.push('');
+    lines.push('- Run `shrk packs compat <pack-path> --consumer-root <repo> --dist-aware` to detect helper-missing or symbol-missing issues against your installed `@shrkcrft/plugin-api`.');
+    lines.push('');
+    return {
+        schema: PACK_DOCS_SCHEMA,
+        packPath,
+        packName: name,
+        packVersion: version,
+        body: lines.join('\n') + '\n',
+        files: allFiles,
+    };
+}

package/dist/pack-doctor.d.ts

@@ -0,0 +1,50 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { type IPackReleaseCheck } from './pack-release-check.js';
+export interface IPackDoctorIssue {
+    severity: 'error' | 'warning' | 'info';
+    packageName: string;
+    code: 'invalid-manifest' | 'missing-contribution-file' | 'empty-resolved-contributions' | 'duplicate-id-local' | 'duplicate-id-pack-internal' | 'template-no-description' | 'pipeline-no-steps' | 'critical-rule-no-hints' | 'docs-file-missing' | 'unsigned-pack' | 'tampered-pack' | 'preset-composition-cycle' | 'preset-composed-not-found' | 'preset-missing-ref' | 'preset-no-includes' | 'release-manifest-issue' | 'release-contribution-issue' | 'release-signature-issue' | 'release-files-issue' | 'release-readiness-issue';
+    message: string;
+    /** Free-form suggestion. */
+    suggestion?: string;
+    /** Optional copy-pasteable shell command for the human reviewer. */
+    suggestedCommand?: string;
+}
+export interface IPackDoctorReport {
+    passed: boolean;
+    packsChecked: number;
+    issues: IPackDoctorIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+    /** Optional release-check payload per pack (populated when --release was passed). */
+    releaseChecks?: readonly IPackReleaseCheck[];
+}
+export interface IPackDoctorOptions {
+    /** When true, unsigned packs surface as `unsigned-pack` warnings. */
+    requireSignatures?: boolean;
+    /** When true, also run pack-release-check per pack and fold findings into issues. */
+    release?: boolean;
+    /** When true, release-check warnings escalate to errors. */
+    strict?: boolean;
+}
+/**
+ * Full structural + quality audit of every discovered pack. Returns a list of
+ * issues (error / warning / info) plus an aggregated pass flag.
+ *
+ * "Errors" mean the pack should not be trusted: invalid manifest, tampered
+ * signature, missing contribution files, fully empty contributions. Everything
+ * else is a warning — useful for pack authors, not fatal.
+ */
+export declare function buildPackDoctorReport(inspection: ISharkcraftInspection, options?: IPackDoctorOptions): IPackDoctorReport;
+/** Run pack-release-check for every valid discovered pack and return the
+ *  results. Async because contribution loading uses dynamic imports. */
+export declare function runPackReleaseChecksForReport(inspection: ISharkcraftInspection): Promise<IPackReleaseCheck[]>;
+/** Fold a list of release-check results into a doctor report. Mutates and
+ *  returns the same report for ergonomics. */
+export declare function mergePackReleaseChecks(inspection: ISharkcraftInspection, report: IPackDoctorReport, releaseChecks: readonly IPackReleaseCheck[], options?: {
+    strict?: boolean;
+}): IPackDoctorReport;
+//# sourceMappingURL=pack-doctor.d.ts.map

package/dist/pack-doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-doctor.d.ts","sourceRoot":"","sources":["../src/pack-doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EACA,kBAAkB,GAClB,2BAA2B,GAC3B,8BAA8B,GAC9B,oBAAoB,GACpB,4BAA4B,GAC5B,yBAAyB,GACzB,mBAAmB,GACnB,wBAAwB,GACxB,mBAAmB,GACnB,eAAe,GACf,eAAe,GACf,0BAA0B,GAC1B,2BAA2B,GAC3B,oBAAoB,GACpB,oBAAoB,GACpB,wBAAwB,GACxB,4BAA4B,GAC5B,yBAAyB,GACzB,qBAAqB,GACrB,yBAAyB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,qFAAqF;IACrF,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAeD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAqNnB;AAgBD;wEACwE;AACxE,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAa9B;AAED;8CAC8C;AAC9C,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,iBAAiB,CAoCnB"}

package/dist/pack-doctor.js

@@ -0,0 +1,302 @@
+import { hasActionHints } from '@shrkcrft/knowledge';
+import { resolvePreset, resolvePresetReferences } from '@shrkcrft/presets';
+import { inspectionReferenceLookup } from "./reference-lookup.js";
+import { runPackReleaseCheck } from "./pack-release-check.js";
+const GEN_KEYWORDS = ['generate', 'create', 'add', 'refactor', 'test', 'review'];
+function appliesToGeneration(e) {
+    for (const a of e.appliesWhen ?? []) {
+        const lower = a.toLowerCase();
+        if (GEN_KEYWORDS.some((k) => lower.includes(k)))
+            return true;
+    }
+    return false;
+}
+function isCriticalOrHigh(e) {
+    const p = String(e.priority);
+    return p === 'critical' || p === 'high';
+}
+/**
+ * Full structural + quality audit of every discovered pack. Returns a list of
+ * issues (error / warning / info) plus an aggregated pass flag.
+ *
+ * "Errors" mean the pack should not be trusted: invalid manifest, tampered
+ * signature, missing contribution files, fully empty contributions. Everything
+ * else is a warning — useful for pack authors, not fatal.
+ */
+export function buildPackDoctorReport(inspection, options = {}) {
+    const issues = [];
+    const localKnowledgeIds = new Set(inspection.knowledgeEntries
+        .filter((e) => inspection.entrySources.get(e.id)?.type === 'local')
+        .map((e) => e.id));
+    for (const pack of inspection.packs.invalidPacks) {
+        issues.push({
+            severity: 'error',
+            packageName: pack.packageName,
+            code: 'invalid-manifest',
+            message: pack.loadError ??
+                `Manifest validation failed: ${pack.validationIssues.map((i) => i.field).join(', ')}`,
+            suggestion: 'Verify the manifest exports a definePackManifest({...}) default export.',
+        });
+    }
+    for (const pack of inspection.packs.discoveredPacks) {
+        if (!pack.valid)
+            continue; // already covered by invalid-manifest above
+        const manifest = pack.manifest;
+        const resolved = pack.resolvedCounts;
+        const declaredAny = manifest.contributions.knowledgeFiles?.length ||
+            manifest.contributions.ruleFiles?.length ||
+            manifest.contributions.pathFiles?.length ||
+            manifest.contributions.templateFiles?.length ||
+            manifest.contributions.pipelineFiles?.length ||
+            manifest.contributions.docsFiles?.length;
+        const resolvedAny = !!resolved &&
+            (resolved.knowledgeEntries +
+                resolved.rules +
+                resolved.pathConventions +
+                resolved.templates +
+                resolved.pipelines +
+                resolved.docs >
+                0);
+        if (declaredAny && !resolvedAny) {
+            issues.push({
+                severity: 'error',
+                packageName: pack.packageName,
+                code: 'empty-resolved-contributions',
+                message: 'Pack declared contribution files but nothing loaded — every file is missing, empty, or duplicates local entries.',
+                suggestion: 'Run `shrk packs get <pack>` and check the listed contribution files.',
+            });
+        }
+        // Templates contributed by this pack — require a non-trivial description.
+        for (const t of inspection.templates) {
+            const src = inspection.templateSources.get(t.id);
+            if (src?.type !== 'pack' || src.packageName !== pack.packageName)
+                continue;
+            const description = t.description;
+            if (typeof description !== 'string' || description.trim().length < 5) {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'template-no-description',
+                    message: `Template "${t.id}" lacks a meaningful description.`,
+                    suggestion: 'Add a description so agents can pick the right generator for a task.',
+                });
+            }
+        }
+        // Pipelines contributed by this pack — require at least one step.
+        for (const p of inspection.pipelines) {
+            const src = inspection.pipelineSources.get(p.id);
+            if (src?.type !== 'pack' || src.packageName !== pack.packageName)
+                continue;
+            if (!Array.isArray(p.steps) || p.steps.length === 0) {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'pipeline-no-steps',
+                    message: `Pipeline "${p.id}" has no steps.`,
+                });
+            }
+        }
+        // Critical/high workflow rules contributed by this pack should carry hints.
+        for (const entry of inspection.knowledgeEntries) {
+            const src = inspection.entrySources.get(entry.id);
+            if (src?.type !== 'pack' || src.packageName !== pack.packageName)
+                continue;
+            if (!isCriticalOrHigh(entry))
+                continue;
+            if (!appliesToGeneration(entry))
+                continue;
+            if (String(entry.type) === 'path')
+                continue;
+            if (!hasActionHints(entry)) {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'critical-rule-no-hints',
+                    message: `Rule "${entry.id}" is high/critical and applies to generation but ships no actionHints.`,
+                });
+            }
+        }
+        // Local-vs-pack duplicate ids.
+        for (const entry of inspection.knowledgeEntries) {
+            const src = inspection.entrySources.get(entry.id);
+            if (src?.type !== 'pack' || src.packageName !== pack.packageName)
+                continue;
+            if (localKnowledgeIds.has(entry.id)) {
+                issues.push({
+                    severity: 'info',
+                    packageName: pack.packageName,
+                    code: 'duplicate-id-local',
+                    message: `Pack entry "${entry.id}" duplicates a local id — local wins.`,
+                });
+            }
+        }
+        // Signature gating.
+        if (options.requireSignatures) {
+            const status = pack.signatureStatus;
+            if (!status || status === 'missing-signature' || status === 'not-checked') {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'unsigned-pack',
+                    message: 'Pack has no signature; --require-signatures was set.',
+                    suggestion: 'Run `shrk packs sign <pack-dir>` and ship the signed manifest.',
+                });
+            }
+        }
+        if (pack.signatureStatus === 'invalid-signature') {
+            issues.push({
+                severity: 'error',
+                packageName: pack.packageName,
+                code: 'tampered-pack',
+                message: pack.signatureMessage ?? 'Pack signature does not match.',
+                suggestion: 'Do not trust this pack — re-fetch from a known-good source.',
+            });
+        }
+        // Docs files: surface inspector-side "missing contribution file" warnings.
+        // Those already land in inspection.warnings; we re-surface them here so the
+        // doctor view is self-contained.
+        // Preset composition / references for presets contributed by this pack.
+        const refLookup = inspectionReferenceLookup(inspection);
+        for (const preset of inspection.presetRegistry.list()) {
+            const src = inspection.presetSources.get(preset.id);
+            if (src?.type !== 'pack' || src.packageName !== pack.packageName)
+                continue;
+            const resolved = resolvePreset(inspection.presetRegistry, preset.id);
+            for (const i of resolved.issues) {
+                issues.push({
+                    severity: 'error',
+                    packageName: pack.packageName,
+                    code: i.code === 'composition-cycle'
+                        ? 'preset-composition-cycle'
+                        : 'preset-composed-not-found',
+                    message: `Preset "${preset.id}": ${i.message}`,
+                });
+            }
+            const refs = resolvePresetReferences(resolved, refLookup);
+            for (const m of refs.missing) {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'preset-missing-ref',
+                    message: `Preset "${preset.id}" references missing ${m.kind} id "${m.id}".`,
+                    suggestion: 'Install the pack that provides the referenced asset, or add it locally.',
+                });
+            }
+            const includesAny = (resolved.includes.knowledge?.length ?? 0) +
+                (resolved.includes.rules?.length ?? 0) +
+                (resolved.includes.paths?.length ?? 0) +
+                (resolved.includes.templates?.length ?? 0) +
+                (resolved.includes.pipelines?.length ?? 0) +
+                (resolved.includes.knowledgeIds?.length ?? 0) +
+                (resolved.includes.ruleIds?.length ?? 0) +
+                (resolved.includes.pathConventionIds?.length ?? 0) +
+                (resolved.includes.templateIds?.length ?? 0) +
+                (resolved.includes.pipelineIds?.length ?? 0) >
+                0;
+            if (!includesAny) {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'preset-no-includes',
+                    message: `Preset "${preset.id}" contributes no includes (no embedded entries and no reference ids).`,
+                });
+            }
+        }
+        const prefix = `pack ${pack.packageName}: missing contribution file `;
+        for (const w of inspection.warnings) {
+            if (!w.startsWith(prefix))
+                continue;
+            const rel = w.slice(prefix.length);
+            issues.push({
+                severity: 'error',
+                packageName: pack.packageName,
+                code: 'missing-contribution-file',
+                message: `Contribution file is missing on disk: ${rel}`,
+                suggestion: 'Update the manifest paths or restore the file under the package root.',
+            });
+        }
+    }
+    const summary = {
+        errors: issues.filter((i) => i.severity === 'error').length,
+        warnings: issues.filter((i) => i.severity === 'warning').length,
+        info: issues.filter((i) => i.severity === 'info').length,
+    };
+    return {
+        passed: summary.errors === 0,
+        packsChecked: inspection.packs.discoveredPacks.length,
+        issues,
+        summary,
+    };
+}
+/** Map a single release-check finding code to one of the four IPackDoctorIssue
+ *  release-* bucket codes. */
+function releaseFindingBucket(code) {
+    if (code.startsWith('manifest-'))
+        return 'release-manifest-issue';
+    if (code === 'no-manifest' || code === 'no-package-json')
+        return 'release-manifest-issue';
+    if (code === 'contribution-missing' || code === 'contribution-load-failed' || code === 'contribution-helper-missing')
+        return 'release-contribution-issue';
+    if (code === 'unsigned-manifest')
+        return 'release-signature-issue';
+    if (code === 'no-files-whitelist' || code === 'manifest-not-in-files')
+        return 'release-files-issue';
+    return 'release-readiness-issue';
+}
+/** Run pack-release-check for every valid discovered pack and return the
+ *  results. Async because contribution loading uses dynamic imports. */
+export async function runPackReleaseChecksForReport(inspection) {
+    const results = [];
+    for (const pack of inspection.packs.discoveredPacks) {
+        if (!pack.valid)
+            continue;
+        try {
+            const check = await runPackReleaseCheck(pack.packageRoot);
+            results.push(check);
+        }
+        catch (e) {
+            // Swallow per-pack errors so the doctor report stays best-effort.
+            void e;
+        }
+    }
+    return results;
+}
+/** Fold a list of release-check results into a doctor report. Mutates and
+ *  returns the same report for ergonomics. */
+export function mergePackReleaseChecks(inspection, report, releaseChecks, options = {}) {
+    // Build a path -> packageName index so we can map check paths back to packs.
+    const pathToName = new Map();
+    for (const pack of inspection.packs.discoveredPacks) {
+        if (pack.valid)
+            pathToName.set(pack.packageRoot, pack.packageName);
+    }
+    for (const check of releaseChecks) {
+        const packageName = pathToName.get(check.packPath) ?? check.packPath;
+        for (const f of check.findings) {
+            const code = releaseFindingBucket(f.code);
+            const severity = f.severity === 'error'
+                ? 'error'
+                : f.severity === 'warning' && options.strict
+                    ? 'error'
+                    : f.severity === 'warning'
+                        ? 'warning'
+                        : 'info';
+            report.issues.push({
+                packageName,
+                severity,
+                code,
+                message: `[release/${f.code}] ${f.message}`,
+                ...(f.suggestedFix ? { suggestion: f.suggestedFix } : {}),
+                ...(f.suggestedCommand ? { suggestedCommand: f.suggestedCommand } : {}),
+            });
+        }
+    }
+    report.summary = {
+        errors: report.issues.filter((i) => i.severity === 'error').length,
+        warnings: report.issues.filter((i) => i.severity === 'warning').length,
+        info: report.issues.filter((i) => i.severity === 'info').length,
+    };
+    report.passed = report.summary.errors === 0;
+    report.releaseChecks = releaseChecks;
+    return report;
+}

package/dist/pack-helper-registry.d.ts

@@ -0,0 +1,29 @@
+import { type IPackHelper } from '@shrkcrft/plugin-api';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const PACK_HELPER_REGISTRY_SCHEMA = "sharkcraft.pack-helper-registry/v1";
+export declare enum PackHelperSource {
+    Local = "local",
+    Pack = "pack",
+    Fixture = "fixture"
+}
+export interface IPackHelperEntry {
+    readonly helper: IPackHelper;
+    readonly source: PackHelperSource;
+    readonly packageName?: string;
+    readonly sourceFile: string;
+}
+export interface IPackHelperDoctorIssue {
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly helperId?: string;
+    readonly source?: string;
+}
+export declare function loadPackHelpers(inspection: ISharkcraftInspection): Promise<{
+    entries: readonly IPackHelperEntry[];
+    issues: readonly IPackHelperDoctorIssue[];
+}>;
+export declare function listPackHelpers(inspection: ISharkcraftInspection): Promise<readonly IPackHelperEntry[]>;
+export declare function findPackHelper(inspection: ISharkcraftInspection, id: string): Promise<IPackHelperEntry | null>;
+export declare function listPackHelperIssues(inspection: ISharkcraftInspection): Promise<readonly IPackHelperDoctorIssue[]>;
+//# sourceMappingURL=pack-helper-registry.d.ts.map

package/dist/pack-helper-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-helper-registry.d.ts","sourceRoot":"","sources":["../src/pack-helper-registry.ts"],"names":[],"mappings":"AAQA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,2BAA2B,uCAAuC,CAAC;AAEhF,oBAAY,gBAAgB;IAC1B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AA4BD,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAA;CAAE,CAAC,CAoF9F;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAGtC;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,qBAAqB,EACjC,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAGlC;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAG5C"}

package/dist/pack-helper-registry.js

@@ -0,0 +1,144 @@
+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;
+};
+/**
+ * Pack helper registry. Loads pack-contributed and locally-configured
+ * helpers via `helperFiles[]`. Engine still ships its profile-driven generic
+ * helpers (HelperId/core.*) — this registry is purely additive.
+ */
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { validatePackHelper } from '@shrkcrft/plugin-api';
+export const PACK_HELPER_REGISTRY_SCHEMA = 'sharkcraft.pack-helper-registry/v1';
+export var PackHelperSource;
+(function (PackHelperSource) {
+    PackHelperSource["Local"] = "local";
+    PackHelperSource["Pack"] = "pack";
+    PackHelperSource["Fixture"] = "fixture";
+})(PackHelperSource || (PackHelperSource = {}));
+async function importDefault(file) {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    if (Array.isArray(mod.default))
+        return mod.default;
+    if (mod.default && typeof mod.default === 'object')
+        return [mod.default];
+    if (Array.isArray(mod.helpers))
+        return mod.helpers;
+    return [];
+}
+function localFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    for (const name of ['helpers.ts', 'helpers/index.ts']) {
+        const abs = nodePath.join(dir, name);
+        if (existsSync(abs))
+            out.push(abs);
+    }
+    const cfg = inspection.config;
+    for (const rel of cfg?.helperFiles ?? []) {
+        out.push(nodePath.isAbsolute(rel) ? rel : nodePath.join(dir, rel));
+    }
+    return out;
+}
+export async function loadPackHelpers(inspection) {
+    const entries = [];
+    const issues = [];
+    const seen = new Set();
+    const ingest = (raw, source, packageName, sourceFile) => {
+        const v = validatePackHelper(raw);
+        if (!v.valid) {
+            for (const i of v.issues) {
+                issues.push({
+                    severity: 'error',
+                    code: 'invalid-helper',
+                    message: `${i.field}: ${i.message}`,
+                    helperId: typeof raw.id === 'string' ? raw.id : undefined,
+                    source: sourceFile,
+                });
+            }
+            return;
+        }
+        if (seen.has(raw.id)) {
+            issues.push({
+                severity: 'error',
+                code: 'duplicate-id',
+                message: `Helper "${raw.id}" already loaded; skipping ${sourceFile}.`,
+                helperId: raw.id,
+                source: sourceFile,
+            });
+            return;
+        }
+        seen.add(raw.id);
+        entries.push({
+            helper: raw,
+            source,
+            ...(packageName ? { packageName } : {}),
+            sourceFile,
+        });
+    };
+    for (const file of localFiles(inspection)) {
+        try {
+            const list = await importDefault(file);
+            const rel = nodePath.relative(inspection.projectRoot, file) || file;
+            for (const h of list)
+                ingest(h, PackHelperSource.Local, undefined, rel);
+        }
+        catch (e) {
+            issues.push({
+                severity: 'warning',
+                code: 'load-failed',
+                message: `Failed to load ${file}: ${e.message}`,
+                source: file,
+            });
+        }
+    }
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const rel of contributions.helperFiles ?? []) {
+            const file = nodePath.resolve(pack.packageRoot, rel);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'missing-file',
+                    message: `Pack ${pack.packageName} declares ${rel} but file is missing.`,
+                    source: file,
+                });
+                continue;
+            }
+            try {
+                const list = await importDefault(file);
+                for (const h of list)
+                    ingest(h, PackHelperSource.Pack, pack.packageName, rel);
+            }
+            catch (e) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'load-failed',
+                    message: `Pack ${pack.packageName} (${rel}): ${e.message}`,
+                    source: file,
+                });
+            }
+        }
+    }
+    return { entries, issues };
+}
+export async function listPackHelpers(inspection) {
+    const { entries } = await loadPackHelpers(inspection);
+    return entries;
+}
+export async function findPackHelper(inspection, id) {
+    const entries = await listPackHelpers(inspection);
+    return entries.find((e) => e.helper.id === id) ?? null;
+}
+export async function listPackHelperIssues(inspection) {
+    const { issues } = await loadPackHelpers(inspection);
+    return issues;
+}