@shrkcrft/inspector 0.1.0-alpha.1

package/dist/task-routing-hint-registry.d.ts

@@ -0,0 +1,36 @@
+import { type ITaskRoutingHint } from '@shrkcrft/plugin-api';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const TASK_ROUTING_HINT_REGISTRY_SCHEMA = "sharkcraft.task-routing-hint-registry/v1";
+export declare enum TaskRoutingHintSource {
+    Local = "local",
+    Pack = "pack",
+    Fixture = "fixture"
+}
+export interface ITaskRoutingHintEntry {
+    readonly hint: ITaskRoutingHint;
+    readonly source: TaskRoutingHintSource;
+    readonly packageName?: string;
+    readonly sourceFile: string;
+}
+export interface ITaskRoutingHintDoctorIssue {
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly hintId?: string;
+    readonly source?: string;
+}
+export declare function loadTaskRoutingHints(inspection: ISharkcraftInspection): Promise<{
+    entries: readonly ITaskRoutingHintEntry[];
+    issues: readonly ITaskRoutingHintDoctorIssue[];
+}>;
+export declare function listTaskRoutingHints(inspection: ISharkcraftInspection): Promise<readonly ITaskRoutingHintEntry[]>;
+export declare function listTaskRoutingHintIssues(inspection: ISharkcraftInspection): Promise<readonly ITaskRoutingHintDoctorIssue[]>;
+export interface ITaskRoutingMatchResult {
+    readonly hint: ITaskRoutingHint;
+    readonly source: TaskRoutingHintSource;
+    readonly packageName?: string;
+    readonly score: number;
+    readonly reasons: readonly string[];
+}
+export declare function explainTaskRouting(inspection: ISharkcraftInspection, task: string): Promise<readonly ITaskRoutingMatchResult[]>;
+//# sourceMappingURL=task-routing-hint-registry.d.ts.map

package/dist/task-routing-hint-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-routing-hint-registry.d.ts","sourceRoot":"","sources":["../src/task-routing-hint-registry.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,iCAAiC,6CAA6C,CAAC;AAE5F,oBAAY,qBAAqB;IAC/B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IAC1C,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,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AA4BD,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAAC,MAAM,EAAE,SAAS,2BAA2B,EAAE,CAAA;CAAE,CAAC,CAoFxG;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,qBAAqB,EAAE,CAAC,CAG3C;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,2BAA2B,EAAE,CAAC,CAGjD;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CA0C7C"}

package/dist/task-routing-hint-registry.js

@@ -0,0 +1,186 @@
+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;
+};
+/**
+ * Task routing hint registry. Pack- and local-contributed task
+ * routing hints bias the recommender output toward project-specific
+ * playbooks / templates / helpers / profiles / conventions / knowledge.
+ *
+ * Engine ships zero hints; everything comes from contributions.
+ */
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { validateTaskRoutingHint, } from '@shrkcrft/plugin-api';
+export const TASK_ROUTING_HINT_REGISTRY_SCHEMA = 'sharkcraft.task-routing-hint-registry/v1';
+export var TaskRoutingHintSource;
+(function (TaskRoutingHintSource) {
+    TaskRoutingHintSource["Local"] = "local";
+    TaskRoutingHintSource["Pack"] = "pack";
+    TaskRoutingHintSource["Fixture"] = "fixture";
+})(TaskRoutingHintSource || (TaskRoutingHintSource = {}));
+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.taskRoutingHints))
+        return mod.taskRoutingHints;
+    return [];
+}
+function localFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    for (const name of ['task-routing-hints.ts', 'task-routing-hints/index.ts']) {
+        const abs = nodePath.join(dir, name);
+        if (existsSync(abs))
+            out.push(abs);
+    }
+    const cfg = inspection.config;
+    for (const rel of cfg?.taskRoutingHintFiles ?? []) {
+        out.push(nodePath.isAbsolute(rel) ? rel : nodePath.join(dir, rel));
+    }
+    return out;
+}
+export async function loadTaskRoutingHints(inspection) {
+    const entries = [];
+    const issues = [];
+    const seen = new Set();
+    const ingest = (raw, source, packageName, sourceFile) => {
+        const v = validateTaskRoutingHint(raw);
+        if (!v.valid) {
+            for (const i of v.issues) {
+                issues.push({
+                    severity: 'error',
+                    code: 'invalid-hint',
+                    message: `${i.field}: ${i.message}`,
+                    hintId: typeof raw.id === 'string' ? raw.id : undefined,
+                    source: sourceFile,
+                });
+            }
+            return;
+        }
+        if (seen.has(raw.id)) {
+            issues.push({
+                severity: 'error',
+                code: 'duplicate-id',
+                message: `Task routing hint "${raw.id}" already loaded; skipping ${sourceFile}.`,
+                hintId: raw.id,
+                source: sourceFile,
+            });
+            return;
+        }
+        seen.add(raw.id);
+        entries.push({
+            hint: 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, TaskRoutingHintSource.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.taskRoutingHintFiles ?? []) {
+            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, TaskRoutingHintSource.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 listTaskRoutingHints(inspection) {
+    const { entries } = await loadTaskRoutingHints(inspection);
+    return entries;
+}
+export async function listTaskRoutingHintIssues(inspection) {
+    const { issues } = await loadTaskRoutingHints(inspection);
+    return issues;
+}
+export async function explainTaskRouting(inspection, task) {
+    const entries = await listTaskRoutingHints(inspection);
+    const lower = task.toLowerCase();
+    const out = [];
+    for (const e of entries) {
+        let score = 0;
+        const reasons = [];
+        for (const kw of e.hint.match.keywords ?? []) {
+            if (lower.includes(kw.toLowerCase())) {
+                score += 2;
+                reasons.push(`keyword: ${kw}`);
+            }
+        }
+        for (const p of e.hint.match.phrases ?? []) {
+            if (lower.includes(p.toLowerCase())) {
+                score += 3;
+                reasons.push(`phrase: ${p}`);
+            }
+        }
+        for (const r of e.hint.match.regexes ?? []) {
+            try {
+                if (new RegExp(r, 'i').test(task)) {
+                    score += 2;
+                    reasons.push(`regex: ${r}`);
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (score > 0) {
+            const result = {
+                hint: e.hint,
+                source: e.source,
+                ...(e.packageName ? { packageName: e.packageName } : {}),
+                score: score + (e.hint.confidenceBoost ?? 0),
+                reasons,
+            };
+            out.push(result);
+        }
+    }
+    out.sort((a, b) => b.score - a.score);
+    return out;
+}

package/dist/template-authoring.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Template authoring previews.
+ *
+ * Mirror of `knowledge-authoring.ts` for templates. Templates are TS-shaped
+ * objects (not knowledge entries), so the draft body is a TS const literal
+ * rather than a JSON-style entry. The CLI adapter writes drafts under
+ * `.sharkcraft/authoring/templates/` and records provenance with
+ * `AssetKind.Template`.
+ *
+ * Hard rules (same as knowledge-authoring):
+ *   - Never mutates `sharkcraft/templates.ts` or any pack's
+ *     `assets/templates.ts`.
+ *   - Update preserves all unspecified fields verbatim.
+ *   - Remove always reports reverse references and refuses by default
+ *     when any remain (unless `forcePreview`).
+ *
+ * Scope: update + remove only. `scaffold` / `add` already ship at
+ * `packages/cli/src/commands/templates.command.ts`.
+ */
+import type { ITemplateDefinition } from '@shrkcrft/templates';
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+import type { IPipelineDefinition } from '@shrkcrft/pipelines';
+import type { IPreset } from '@shrkcrft/presets';
+export declare const TEMPLATE_AUTHORING_SCHEMA = "sharkcraft.template-authoring/v1";
+export declare enum TemplateAuthoringOperation {
+    Update = "update",
+    Remove = "remove"
+}
+export interface ITemplateUpdateOps {
+    setName?: string;
+    setDescription?: string;
+    addTags?: readonly string[];
+    removeTags?: readonly string[];
+    addScope?: readonly string[];
+    removeScope?: readonly string[];
+    addAppliesWhen?: readonly string[];
+    removeAppliesWhen?: readonly string[];
+    /** Add to metadata.requiredProfileIds. */
+    addRequiredProfileIds?: readonly string[];
+    removeRequiredProfileIds?: readonly string[];
+    /** Add to metadata.forbiddenPathFragments. */
+    addForbiddenPathFragments?: readonly string[];
+    removeForbiddenPathFragments?: readonly string[];
+    /** Add to related (knowledge entry ids). */
+    addRelated?: readonly string[];
+    removeRelated?: readonly string[];
+    /** Append a postGenerationNote (preview only — the resolver still runs). */
+    addPostGenerationNote?: string;
+}
+export interface ITemplateAuthoringInput {
+    operation: TemplateAuthoringOperation;
+    id: string;
+    updateOps?: ITemplateUpdateOps;
+    reason?: string;
+    /** Override the default refusal when reverse references exist (remove). */
+    forcePreview?: boolean;
+}
+export interface ITemplateAuthoringDraftFile {
+    path: string;
+    body: string;
+    language: 'typescript' | 'markdown';
+}
+export interface ITemplateReverseReference {
+    fromKind: 'knowledge' | 'pipeline' | 'preset' | 'pack';
+    fromId: string;
+    field: string;
+    note?: string;
+}
+export interface ITemplateAuthoringPatchChange {
+    op: 'add' | 'remove' | 'replace';
+    field: string;
+    before?: unknown;
+    after?: unknown;
+}
+export interface ITemplateAuthoringPatch {
+    schema: 'sharkcraft.template-authoring-patch/v1';
+    operation: TemplateAuthoringOperation;
+    templateId: string;
+    changes: readonly ITemplateAuthoringPatchChange[];
+}
+export interface ITemplateAuthoringResult {
+    schema: typeof TEMPLATE_AUTHORING_SCHEMA;
+    generatedAt: string;
+    operation: TemplateAuthoringOperation;
+    templateId: string;
+    ok: boolean;
+    refusal?: string;
+    /** TS draft (update only — for `remove` it is a comment notice). */
+    tsDraft: ITemplateAuthoringDraftFile;
+    /** Markdown explainer + next commands. */
+    explainer: ITemplateAuthoringDraftFile;
+    /** Optional semantic patch (update only). */
+    patch?: ITemplateAuthoringPatch;
+    warnings: readonly string[];
+    nextCommands: readonly string[];
+    /** Resolved current definition (before change). */
+    current?: ITemplateDefinition;
+    /** Projected definition shape (update only). */
+    next?: ITemplateDefinition;
+    /** Reverse references blocking removal (remove only). */
+    reverseReferences?: readonly ITemplateReverseReference[];
+}
+export interface ITemplateAuthoringContext {
+    templates: readonly ITemplateDefinition[];
+    /** Used to detect reverse references for `remove`. */
+    knowledgeEntries?: readonly IKnowledgeEntry[];
+    pipelines?: readonly IPipelineDefinition[];
+    presets?: readonly IPreset[];
+    /** Pack-contributed template ids by pack — used to flag if the target id is owned by a pack. */
+    packTemplateIds?: ReadonlyMap<string, string>;
+}
+export declare function buildTemplateAuthoringPreview(input: ITemplateAuthoringInput, context: ITemplateAuthoringContext): ITemplateAuthoringResult;
+//# sourceMappingURL=template-authoring.d.ts.map

package/dist/template-authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-authoring.d.ts","sourceRoot":"","sources":["../src/template-authoring.ts"],"names":[],"mappings":"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"}