@shrkcrft/inspector 0.1.0-alpha.1

package/dist/task-packet.d.ts

@@ -0,0 +1,104 @@
+import { type IContextResult } from '@shrkcrft/context';
+import { type IAggregatedActionHints, type IKnowledgeEntry } from '@shrkcrft/knowledge';
+import type { IRule } from '@shrkcrft/rules';
+import type { ITemplateDefinition } from '@shrkcrft/templates';
+import type { IPresetRecommendation } from '@shrkcrft/presets';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export interface ITaskPacketRecommendedPipeline {
+    pipelineId: string;
+    reason: string;
+}
+export interface ITaskPacketSuggestedGen {
+    templateId: string;
+    templateName: string;
+    /** Concrete `shrk gen` command with placeholders for missing vars. */
+    dryRunCommand: string;
+    /** Concrete `shrk apply` command suggestion. */
+    applyCommand: string;
+    /** Variables this template requires. */
+    requiredVariables: readonly string[];
+}
+export interface ITaskPacket {
+    task: string;
+    /** Compact project overview text (same shape as `shrk inspect`). */
+    projectOverview: string;
+    /** Detected profile tags. */
+    detectedProfiles: readonly string[];
+    /** Top preset recommendations (informational). */
+    presetRecommendations: IPresetRecommendation[];
+    /** Selected pipelines (max 3). */
+    recommendedPipelines: ITaskPacketRecommendedPipeline[];
+    /** Token-budgeted context (rules / paths / templates relevant to the task). */
+    context: IContextResult;
+    /** Rules that match the task (uncapped list, separate from the context body). */
+    relevantRules: readonly IRule[];
+    /** Paths that match (as knowledge entries with type "path"). */
+    relevantPaths: readonly IKnowledgeEntry[];
+    /** Templates that match. */
+    relevantTemplates: readonly ITemplateDefinition[];
+    /** Aggregated action hints across the relevant entries. */
+    actionHints: IAggregatedActionHints;
+    /** MCP tools recommended for this task. */
+    recommendedMcpTools: readonly string[];
+    /** CLI commands recommended for this task. */
+    recommendedCliCommands: readonly string[];
+    /** Things the agent must not do. */
+    forbiddenActions: readonly string[];
+    /** Commands that should be run after the change. */
+    verificationCommands: readonly string[];
+    /** Step ids that require human review (sourced from recommended pipelines). */
+    humanReviewPoints: readonly string[];
+    /** Rough token estimate for the packet body. */
+    tokenEstimate: number;
+    /**
+     * Ranking explanations per kind (only filled when buildTaskPacket is called
+     * with `explainRanking: true`).
+     */
+    rankingReasons?: {
+        rules?: readonly {
+            id: string;
+            score: number;
+            reasons: readonly string[];
+        }[];
+        paths?: readonly {
+            id: string;
+            score: number;
+            reasons: readonly string[];
+        }[];
+        templates?: readonly {
+            id: string;
+            score: number;
+            reasons: readonly string[];
+        }[];
+        pipelines?: readonly {
+            id: string;
+            score: number;
+            reasons: readonly string[];
+        }[];
+        presets?: readonly {
+            id: string;
+            score: number;
+            reasons: readonly string[];
+        }[];
+    };
+    /**
+     * If a template is an obvious fit, concrete `shrk gen` + `shrk apply`
+     * commands. Variables that aren't extractable from the task stay as
+     * placeholders so the agent doesn't hallucinate values.
+     */
+    suggestedGen?: ITaskPacketSuggestedGen;
+}
+export interface IBuildTaskPacketOptions {
+    /** Optional max tokens for the embedded context. Default: 3500. */
+    maxTokens?: number;
+    /** Optional scope override forwarded to buildContext. */
+    scope?: readonly string[];
+    /** When true, include per-kind ranking reasons in the packet. */
+    explainRanking?: boolean;
+}
+/**
+ * Build a deterministic, AI-ready bundle for a single task. Pure orchestration
+ * over the existing inspector services — no AI calls, no writes.
+ */
+export declare function buildTaskPacket(inspection: ISharkcraftInspection, task: string, options?: IBuildTaskPacketOptions): ITaskPacket;
+//# sourceMappingURL=task-packet.d.ts.map

package/dist/task-packet.d.ts.map

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

package/dist/task-packet.js

@@ -0,0 +1,156 @@
+import { buildContext } from '@shrkcrft/context';
+import { aggregateActionHints, } from '@shrkcrft/knowledge';
+import { rankAll } from "./task-ranker.js";
+import { buildProjectOverview, renderOverviewText } from "./project-overview.js";
+function findPipelinesByTags(pipelines, ...tags) {
+    return pipelines.filter((p) => p.tags?.some((t) => tags.includes(t.toLowerCase())));
+}
+function pickPipelines(pipelines, task) {
+    const lower = task.toLowerCase();
+    const out = [];
+    const featureLike = /\b(create|add|implement|generate|new|build)\b/.test(lower);
+    const refactorLike = /\b(refactor|rewrite|migrate|extract)\b/.test(lower);
+    const testLike = /\b(test|spec|coverage)\b/.test(lower);
+    if (featureLike) {
+        for (const p of findPipelinesByTags(pipelines, 'feature', 'generation')) {
+            if (!out.some((o) => o.pipelineId === p.id)) {
+                out.push({ pipelineId: p.id, reason: 'task looks like new feature work' });
+            }
+        }
+    }
+    if (refactorLike) {
+        for (const p of findPipelinesByTags(pipelines, 'refactor', 'safe', 'generation')) {
+            if (!out.some((o) => o.pipelineId === p.id)) {
+                out.push({ pipelineId: p.id, reason: 'task looks like refactor work' });
+            }
+        }
+    }
+    if (testLike) {
+        for (const p of findPipelinesByTags(pipelines, 'test')) {
+            if (!out.some((o) => o.pipelineId === p.id)) {
+                out.push({ pipelineId: p.id, reason: 'task mentions testing' });
+            }
+        }
+    }
+    // Fallback: context-only when nothing matched.
+    if (out.length === 0) {
+        for (const p of findPipelinesByTags(pipelines, 'context', 'safe')) {
+            out.push({ pipelineId: p.id, reason: 'no obvious work type — start with context-only' });
+        }
+    }
+    return out.slice(0, 3);
+}
+/**
+ * Build a deterministic, AI-ready bundle for a single task. Pure orchestration
+ * over the existing inspector services — no AI calls, no writes.
+ */
+export function buildTaskPacket(inspection, task, options = {}) {
+    const maxTokens = options.maxTokens ?? 3500;
+    const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+    const overviewText = renderOverviewText(overview);
+    const contextResult = buildContext(inspection.knowledgeEntries, {
+        task,
+        maxTokens,
+        ...(options.scope ? { scope: options.scope } : {}),
+        projectOverview: overviewText,
+    });
+    // ── Deterministic ranker — replaces the old substring search ─────────
+    const ranking = rankAll(inspection, task, 10);
+    const relevantRules = ranking.rules.map((r) => r.item);
+    const relevantPaths = ranking.paths.map((r) => r.item);
+    const relevantTemplates = ranking.templates.map((r) => r.item);
+    // Aggregate hints from the *ranked* knowledge so unrelated entries don't
+    // leak into the action-hints surface.
+    const hintCorpus = [
+        ...ranking.rules.slice(0, 8).map((r) => r.item),
+        ...inspection.knowledgeEntries.filter((e) => e.priority === 'critical' || e.priority === 'high'),
+    ];
+    const actionHints = aggregateActionHints(hintCorpus);
+    // Pipelines: prefer ranker output, then verb fallback for context-only.
+    const rankedPipelines = ranking.pipelines.slice(0, 3).map((p) => ({
+        pipelineId: p.item.id,
+        reason: p.reasons.join('; ') || 'ranked match',
+    }));
+    const fallback = rankedPipelines.length > 0 ? rankedPipelines : pickPipelines(inspection.pipelineRegistry.list(), task);
+    const recommendedPipelines = fallback;
+    const humanReviewPoints = [];
+    for (const r of recommendedPipelines) {
+        const p = inspection.pipelineRegistry.get(r.pipelineId);
+        if (!p)
+            continue;
+        for (const step of p.steps) {
+            if (step.humanReview)
+                humanReviewPoints.push(`${p.id}.${step.id}`);
+        }
+    }
+    const presetRecommendations = ranking.presets.slice(0, 3).map((r) => ({
+        preset: r.item,
+        score: r.score,
+        confidence: (r.score >= 15 ? 'high' : r.score >= 9 ? 'medium' : 'low'),
+        reasons: r.reasons,
+    }));
+    const tokenEstimate = contextResult.totalTokens +
+        Math.ceil((actionHints.commands.length + actionHints.mcpTools.length + actionHints.verificationCommands.length) *
+            4);
+    // Suggested generation command — only emitted when one template clearly
+    // dominates the field AND the user's wording suggests creation work.
+    let suggestedGen;
+    const top = ranking.templates[0];
+    const runnerUp = ranking.templates[1];
+    if (top &&
+        /\b(create|add|implement|generate|new|build)\b/i.test(task) &&
+        (!runnerUp || top.score - runnerUp.score >= 4)) {
+        const tpl = top.item;
+        const required = (tpl.variables ?? [])
+            .filter((v) => v.required)
+            .map((v) => v.name);
+        const varStr = required.map((n) => `--var ${n}=<${n}>`).join(' ');
+        const namePlaceholder = '<name>';
+        suggestedGen = {
+            templateId: tpl.id,
+            templateName: tpl.name,
+            dryRunCommand: `shrk gen ${tpl.id} ${namePlaceholder}${varStr ? ' ' + varStr : ''} --dry-run --save-plan ./.sharkcraft/plans/${tpl.id}.json`,
+            applyCommand: `shrk apply ./.sharkcraft/plans/${tpl.id}.json --verify-signature  # human-approved only`,
+            requiredVariables: required,
+        };
+    }
+    function makeReasons(items) {
+        return items.slice(0, 5).map((r) => ({
+            id: r.item.id,
+            score: r.score,
+            reasons: r.reasons,
+        }));
+    }
+    const rankingReasons = options.explainRanking
+        ? {
+            rules: makeReasons(ranking.rules),
+            paths: makeReasons(ranking.paths),
+            templates: makeReasons(ranking.templates),
+            pipelines: makeReasons(ranking.pipelines),
+            presets: makeReasons(ranking.presets),
+        }
+        : undefined;
+    const packet = {
+        task,
+        projectOverview: overviewText,
+        detectedProfiles: inspection.workspace.profiles,
+        presetRecommendations,
+        recommendedPipelines,
+        context: contextResult,
+        relevantRules,
+        relevantPaths,
+        relevantTemplates,
+        actionHints,
+        recommendedMcpTools: actionHints.mcpTools.map((t) => t.tool),
+        recommendedCliCommands: actionHints.commands.map((c) => typeof c === 'string' ? c : c.command),
+        forbiddenActions: actionHints.forbiddenActions,
+        verificationCommands: actionHints.verificationCommands,
+        humanReviewPoints,
+        tokenEstimate,
+    };
+    if (rankingReasons)
+        packet.rankingReasons = rankingReasons;
+    if (suggestedGen)
+        packet.suggestedGen = suggestedGen;
+    return packet;
+}

package/dist/task-ranker.d.ts

@@ -0,0 +1,51 @@
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+import type { ITemplateDefinition } from '@shrkcrft/templates';
+import type { IPipelineDefinition } from '@shrkcrft/pipelines';
+import type { IPreset, IResolvedPreset } from '@shrkcrft/presets';
+/**
+ * Deterministic relevance ranker.
+ *
+ * Inputs: a free-text task + structured signals (tags, scope, priority,
+ * appliesWhen, title, description, actionHints.relatedTemplates /
+ * relatedPathConventions, pipeline steps/templates, preset appliesTo).
+ *
+ * No AI. No embeddings. Pure scoring + reasons.
+ */
+export interface IRankedItem<T> {
+    item: T;
+    score: number;
+    reasons: string[];
+}
+export declare function rankKnowledgeEntries(entries: readonly IKnowledgeEntry[], task: string): IRankedItem<IKnowledgeEntry>[];
+export declare function rankTemplates(templates: readonly ITemplateDefinition[], task: string): IRankedItem<ITemplateDefinition>[];
+export declare function rankPathConventions(paths: readonly IKnowledgeEntry[], task: string): IRankedItem<IKnowledgeEntry>[];
+export declare function rankPipelines(pipelines: readonly IPipelineDefinition[], task: string): IRankedItem<IPipelineDefinition>[];
+export declare function rankPresets(presets: readonly IPreset[], task: string, detectedProfiles: readonly string[]): IRankedItem<IPreset>[];
+export interface IRankAllResult {
+    rules: IRankedItem<IKnowledgeEntry>[];
+    paths: IRankedItem<IKnowledgeEntry>[];
+    templates: IRankedItem<ITemplateDefinition>[];
+    pipelines: IRankedItem<IPipelineDefinition>[];
+    presets: IRankedItem<IPreset>[];
+}
+export declare function rankAll(inspection: {
+    knowledgeEntries: readonly IKnowledgeEntry[];
+    templates: readonly ITemplateDefinition[];
+    pipelines: readonly IPipelineDefinition[];
+    presetRegistry: {
+        list: () => readonly IPreset[];
+    };
+    workspace: {
+        profiles: readonly string[];
+    };
+    ruleService: {
+        list: () => readonly IKnowledgeEntry[];
+    };
+    pathService: {
+        list: () => readonly IKnowledgeEntry[];
+    };
+}, task: string, limit?: number): IRankAllResult;
+export declare function explainRanked<T>(items: readonly IRankedItem<T>[], describe: (item: T) => string, limit?: number): string;
+/** Re-export resolved-preset for callers that want to combine ranker + composition. */
+export type { IResolvedPreset };
+//# sourceMappingURL=task-ranker.d.ts.map

package/dist/task-ranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-ranker.d.ts","sourceRoot":"","sources":["../src/task-ranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAiQD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,IAAI,EAAE,MAAM,GACX,WAAW,CAAC,eAAe,CAAC,EAAE,CAqBhC;AAGD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,mBAAmB,EAAE,EACzC,IAAI,EAAE,MAAM,GACX,WAAW,CAAC,mBAAmB,CAAC,EAAE,CAiBpC;AAGD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,IAAI,EAAE,MAAM,GACX,WAAW,CAAC,eAAe,CAAC,EAAE,CAEhC;AAGD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,mBAAmB,EAAE,EACzC,IAAI,EAAE,MAAM,GACX,WAAW,CAAC,mBAAmB,CAAC,EAAE,CAkCpC;AAGD,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,WAAW,CAAC,OAAO,CAAC,EAAE,CAgCxB;AAGD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC,eAAe,CAAC,EAAE,CAAC;IACtC,KAAK,EAAE,WAAW,CAAC,eAAe,CAAC,EAAE,CAAC;IACtC,SAAS,EAAE,WAAW,CAAC,mBAAmB,CAAC,EAAE,CAAC;IAC9C,SAAS,EAAE,WAAW,CAAC,mBAAmB,CAAC,EAAE,CAAC;IAC9C,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;CACjC;AAED,wBAAgB,OAAO,CACrB,UAAU,EAAE;IACV,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,cAAc,EAAE;QAAE,IAAI,EAAE,MAAM,SAAS,OAAO,EAAE,CAAA;KAAE,CAAC;IACnD,SAAS,EAAE;QAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IAC3C,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,SAAS,eAAe,EAAE,CAAA;KAAE,CAAC;IACxD,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,SAAS,eAAe,EAAE,CAAA;KAAE,CAAC;CACzD,EACD,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAW,GACjB,cAAc,CAiEhB;AAGD,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,EAChC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAC7B,KAAK,GAAE,MAAU,GAChB,MAAM,CAKR;AAED,uFAAuF;AACvF,YAAY,EAAE,eAAe,EAAE,CAAC"}