@shrkcrft/inspector 0.1.0-alpha.2

package/dist/self-audit.js

@@ -0,0 +1,192 @@
+/**
+ * `shrk self audit` — meaningful only inside the SharkCraft repo itself.
+ *
+ * Aggregates several existing read-only audits:
+ *  - shrk commands doctor (catalog completeness)
+ *  - mcp audit (no writable tools)
+ *  - docs check
+ *  - examples check
+ *  - release readiness
+ *  - runtime doctor
+ *  - compat:node static report
+ *  - packs doctor on example packs
+ *
+ * The aggregation is intentionally lightweight — every component is its own
+ * command. `self audit` just wires the verdicts into one pass/fail and
+ * suggests the next CLI step.
+ *
+ * When run outside the SharkCraft repo, the command returns a single
+ * "not-applicable" finding instead of running anything.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const SELF_AUDIT_SCHEMA = 'sharkcraft.self-audit/v1';
+export function detectSharkcraftRepo(projectRoot) {
+    const pkgFile = nodePath.join(projectRoot, 'package.json');
+    if (!existsSync(pkgFile))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+        if (pkg.name === 'sharkcraft')
+            return true;
+        // Heuristic: monorepo with packages/cli + packages/inspector + packages/mcp-server.
+        const markers = ['packages/cli', 'packages/inspector', 'packages/mcp-server'];
+        if (markers.every((m) => existsSync(nodePath.join(projectRoot, m))))
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function buildSelfAudit(projectRoot, input = {}) {
+    const isRepo = detectSharkcraftRepo(projectRoot);
+    if (!isRepo) {
+        return {
+            schema: SELF_AUDIT_SCHEMA,
+            generatedAt: new Date().toISOString(),
+            projectRoot,
+            isSharkcraftRepo: false,
+            findings: [
+                {
+                    id: 'not-sharkcraft-repo',
+                    title: 'Self audit applies only to the SharkCraft monorepo',
+                    status: 'skipped',
+                    message: 'Run `shrk release readiness` instead for a generic readiness verdict.',
+                    nextCommand: 'shrk release readiness',
+                },
+            ],
+            ok: true,
+        };
+    }
+    const findings = [];
+    // Release readiness
+    if (input.releaseReadinessReady === undefined) {
+        findings.push({
+            id: 'release-readiness',
+            title: 'Release readiness',
+            status: 'skipped',
+            message: 'No release readiness verdict was supplied — pass --include-readiness or run `shrk release readiness` directly.',
+            nextCommand: 'shrk release readiness',
+        });
+    }
+    else if (input.releaseReadinessReady) {
+        findings.push({
+            id: 'release-readiness',
+            title: 'Release readiness',
+            status: (input.releaseReadinessWarnings ?? 0) > 0 ? 'warn' : 'pass',
+            message: `Blockers: ${input.releaseReadinessBlockers ?? 0}, warnings: ${input.releaseReadinessWarnings ?? 0}.`,
+        });
+    }
+    else {
+        findings.push({
+            id: 'release-readiness',
+            title: 'Release readiness',
+            status: 'fail',
+            message: `Blockers: ${input.releaseReadinessBlockers ?? '?'}.`,
+            nextCommand: 'shrk release readiness --strict',
+        });
+    }
+    // Commands doctor
+    if (input.commandsDoctorErrors === undefined && input.commandsDoctorWarnings === undefined) {
+        findings.push({
+            id: 'commands-doctor',
+            title: 'Commands catalog doctor',
+            status: 'skipped',
+            message: 'No verdict supplied — run `shrk commands doctor`.',
+            nextCommand: 'shrk commands doctor',
+        });
+    }
+    else if ((input.commandsDoctorErrors ?? 0) === 0 && (input.commandsDoctorWarnings ?? 0) === 0) {
+        findings.push({
+            id: 'commands-doctor',
+            title: 'Commands catalog doctor',
+            status: 'pass',
+            message: 'Catalog is consistent.',
+        });
+    }
+    else if ((input.commandsDoctorErrors ?? 0) > 0) {
+        findings.push({
+            id: 'commands-doctor',
+            title: 'Commands catalog doctor',
+            status: 'fail',
+            message: `${input.commandsDoctorErrors} catalog error(s).`,
+            nextCommand: 'shrk commands doctor',
+        });
+    }
+    else {
+        findings.push({
+            id: 'commands-doctor',
+            title: 'Commands catalog doctor',
+            status: 'warn',
+            message: `${input.commandsDoctorWarnings} catalog warning(s).`,
+            nextCommand: 'shrk commands doctor',
+        });
+    }
+    // MCP audit
+    if (input.mcpAuditWriteToolCount === undefined) {
+        findings.push({
+            id: 'mcp-audit',
+            title: 'MCP audit — no write tools',
+            status: 'skipped',
+            message: 'No verdict supplied — run `shrk mcp audit`.',
+            nextCommand: 'shrk mcp audit',
+        });
+    }
+    else if (input.mcpAuditWriteToolCount === 0) {
+        findings.push({
+            id: 'mcp-audit',
+            title: 'MCP audit — no write tools',
+            status: 'pass',
+            message: 'Every registered tool is read-only.',
+        });
+    }
+    else {
+        findings.push({
+            id: 'mcp-audit',
+            title: 'MCP audit — no write tools',
+            status: 'fail',
+            message: `${input.mcpAuditWriteToolCount} MCP tool(s) report write capability — this breaks the safety contract.`,
+            nextCommand: 'shrk mcp audit',
+        });
+    }
+    const flag = (id, title, ok, nextCommand) => {
+        if (ok === null || ok === undefined) {
+            findings.push({ id, title, status: 'skipped', message: 'Not run.', nextCommand });
+        }
+        else if (ok) {
+            findings.push({ id, title, status: 'pass', message: 'Clean.' });
+        }
+        else {
+            findings.push({ id, title, status: 'fail', message: 'Reports errors.', nextCommand });
+        }
+    };
+    flag('docs-check', 'Docs check', input.docsCheckOk, 'shrk docs check');
+    flag('examples-check', 'Examples check', input.examplesCheckOk, 'shrk examples check');
+    flag('runtime-doctor', 'Runtime doctor', input.runtimeDoctorOk ?? null, 'shrk runtime doctor');
+    flag('compat-node', 'compat:node', input.compatNodeOk ?? null, 'bun run compat:node');
+    flag('packs-doctor', 'Packs doctor', input.packsDoctorOk ?? null, 'shrk packs doctor --release');
+    flag('demo-package-validate', 'Demo package validate', input.demoPackageValidateOk ?? null, 'shrk demo package --validate');
+    const ok = findings.filter((f) => f.status === 'fail').length === 0;
+    return {
+        schema: SELF_AUDIT_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        projectRoot,
+        isSharkcraftRepo: true,
+        findings,
+        ok,
+    };
+}
+export function renderSelfAuditText(report) {
+    const lines = [];
+    lines.push(`# Self audit — ${report.ok ? 'OK' : 'NOT OK'}`);
+    lines.push(`Project: ${report.projectRoot}`);
+    lines.push(`Is SharkCraft repo: ${report.isSharkcraftRepo}`);
+    lines.push('');
+    for (const f of report.findings) {
+        lines.push(`  [${f.status.padEnd(8)}] ${f.title}: ${f.message}`);
+        if (f.nextCommand)
+            lines.push(`     → ${f.nextCommand}`);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/self-config-doctor-v2.d.ts

@@ -0,0 +1,57 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const SELF_CONFIG_DOCTOR_V2_SCHEMA = "sharkcraft.self-config-doctor/v2";
+export declare enum SelfConfigSeverityV2 {
+    Info = "info",
+    Warning = "warning",
+    Error = "error"
+}
+/**
+ * Source / target kind taxonomy. Open string for forward-compat with
+ * pack-contributed kinds, but the engine emits one of these values.
+ */
+export type SelfConfigKind = 'knowledge' | 'command' | 'helper' | 'template' | 'playbook' | 'pipeline' | 'policy' | 'rule' | 'path' | 'convention' | 'registration-hint' | 'routing-hint' | 'agent-test' | 'decision' | 'profile' | 'migration-profile' | 'plugin-lifecycle-profile' | 'contract-template' | 'pack' | 'schema' | 'file' | 'unknown';
+/**
+ * Edge relation taxonomy. Open string to allow future relations.
+ */
+export type SelfConfigRelation = 'references' | 'expects' | 'validates' | 'requires' | 'produces' | 'routes-to' | 'tunes' | 'documents' | 'supersedes' | 'related';
+export interface ISelfConfigFindingV2 {
+    readonly id: string;
+    readonly severity: SelfConfigSeverityV2;
+    readonly code: string;
+    readonly sourceKind: SelfConfigKind;
+    readonly sourceId: string;
+    readonly targetKind: SelfConfigKind;
+    readonly targetId: string;
+    readonly relation: SelfConfigRelation;
+    readonly file?: string;
+    readonly message: string;
+    readonly suggestedFix?: string;
+    readonly nextCommand?: string;
+    /**
+     * Reporter confidence in this finding.
+     *   - high   — extracted from authoritative loader output
+     *   - medium — extracted from authoritative loader but relation is weak
+     *   - low    — derived from regex / fallback parsing
+     */
+    readonly confidence: 'high' | 'medium' | 'low';
+}
+export interface ISelfConfigDoctorReportV2 {
+    readonly schema: typeof SELF_CONFIG_DOCTOR_V2_SCHEMA;
+    readonly generatedAt: string;
+    readonly projectRoot: string;
+    readonly findings: readonly ISelfConfigFindingV2[];
+    readonly totals: Readonly<{
+        error: number;
+        warning: number;
+        info: number;
+        byRelation: Readonly<Record<string, number>>;
+        bySourceKind: Readonly<Record<string, number>>;
+        byTargetKind: Readonly<Record<string, number>>;
+    }>;
+    readonly verdict: 'ok' | 'warnings' | 'errors';
+    readonly nextCommands: readonly string[];
+}
+export declare function buildSelfConfigDoctorReportV2(inspection: ISharkcraftInspection): Promise<ISelfConfigDoctorReportV2>;
+export declare function renderSelfConfigDoctorV2Text(report: ISelfConfigDoctorReportV2): string;
+export declare function renderSelfConfigDoctorV2Markdown(report: ISelfConfigDoctorReportV2): string;
+//# sourceMappingURL=self-config-doctor-v2.d.ts.map

package/dist/self-config-doctor-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-config-doctor-v2.d.ts","sourceRoot":"","sources":["../src/self-config-doctor-v2.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,4BAA4B,qCAAqC,CAAC;AAE/E,oBAAY,oBAAoB;IAC9B,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,SAAS,GACT,QAAQ,GACR,UAAU,GACV,UAAU,GACV,UAAU,GACV,QAAQ,GACR,MAAM,GACN,MAAM,GACN,YAAY,GACZ,mBAAmB,GACnB,cAAc,GACd,YAAY,GACZ,UAAU,GACV,SAAS,GACT,mBAAmB,GACnB,0BAA0B,GAC1B,mBAAmB,GACnB,MAAM,GACN,QAAQ,GACR,MAAM,GACN,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,YAAY,GACZ,SAAS,GACT,WAAW,GACX,UAAU,GACV,UAAU,GACV,WAAW,GACX,OAAO,GACP,WAAW,GACX,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CAChD;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7C,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KAChD,CAAC,CAAC;IACH,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AA8qBD,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,yBAAyB,CAAC,CAyCpC;AAsBD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CA+BtF;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,yBAAyB,GAChC,MAAM,CAqBR"}