@shrkcrft/pipelines 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/pipelines
+
+SharkCraft AI development pipelines: typed flow definitions, registry, loader, formatter.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/pipelines
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/define/define-pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { IPipelineDefinition, PipelineDefinitionInput } from '../model/pipeline-definition.js';
+export declare function definePipeline(input: PipelineDefinitionInput): IPipelineDefinition;
+//# sourceMappingURL=define-pipeline.d.ts.map

package/dist/define/define-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-pipeline.d.ts","sourceRoot":"","sources":["../../src/define/define-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,iCAAiC,CAAC;AAEzC,wBAAgB,cAAc,CAAC,KAAK,EAAE,uBAAuB,GAAG,mBAAmB,CAyBlF"}

package/dist/define/define-pipeline.js

@@ -0,0 +1,28 @@
+export function definePipeline(input) {
+    if (!input.id)
+        throw new Error("definePipeline: 'id' is required");
+    if (!input.title)
+        throw new Error(`definePipeline: 'title' is required for ${input.id}`);
+    if (!Array.isArray(input.steps) || input.steps.length === 0) {
+        throw new Error(`definePipeline: ${input.id} must have at least one step`);
+    }
+    const ids = new Set();
+    for (const step of input.steps) {
+        if (!step.id) {
+            throw new Error(`definePipeline: ${input.id}: every step needs an id`);
+        }
+        if (ids.has(step.id)) {
+            throw new Error(`definePipeline: ${input.id}: duplicate step id "${step.id}"`);
+        }
+        ids.add(step.id);
+    }
+    return {
+        ...input,
+        tags: input.tags ? Object.freeze([...input.tags]) : undefined,
+        scope: input.scope ? Object.freeze([...input.scope]) : undefined,
+        appliesWhen: input.appliesWhen ? Object.freeze([...input.appliesWhen]) : undefined,
+        inputs: input.inputs ? Object.freeze([...input.inputs]) : undefined,
+        steps: Object.freeze([...input.steps]),
+        notes: input.notes ? Object.freeze([...input.notes]) : undefined,
+    };
+}

package/dist/format/pipeline-formatter.d.ts

@@ -0,0 +1,4 @@
+import type { IPipelineDefinition } from '../model/pipeline-definition.js';
+export declare function formatPipelineCompact(p: IPipelineDefinition): string;
+export declare function formatPipelineFull(p: IPipelineDefinition): string;
+//# sourceMappingURL=pipeline-formatter.d.ts.map

package/dist/format/pipeline-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-formatter.d.ts","sourceRoot":"","sources":["../../src/format/pipeline-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAIpE;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CA0CjE"}

package/dist/format/pipeline-formatter.js

@@ -0,0 +1,57 @@
+export function formatPipelineCompact(p) {
+    const tags = (p.tags ?? []).length ? ` tags=[${(p.tags ?? []).join(', ')}]` : '';
+    const stepWord = p.steps.length === 1 ? 'step' : 'steps';
+    return `${p.id.padEnd(28)} ${p.steps.length} ${stepWord} — ${p.title}${tags}`;
+}
+export function formatPipelineFull(p) {
+    const lines = [];
+    lines.push(`# Pipeline: ${p.title}`);
+    lines.push(`id: ${p.id}`);
+    if (p.tags?.length)
+        lines.push(`tags: ${p.tags.join(', ')}`);
+    if (p.scope?.length)
+        lines.push(`scope: ${p.scope.join(', ')}`);
+    if (p.appliesWhen?.length)
+        lines.push(`appliesWhen: ${p.appliesWhen.join(', ')}`);
+    lines.push('');
+    lines.push(p.description);
+    if (p.inputs?.length) {
+        lines.push('');
+        lines.push('## Inputs');
+        for (const i of p.inputs) {
+            const req = i.required ? ' (required)' : '';
+            const def = i.default !== undefined ? ` = ${i.default}` : '';
+            const choices = i.choices?.length ? ` choices=[${i.choices.join(', ')}]` : '';
+            const desc = i.description ? ` — ${i.description}` : '';
+            lines.push(`- ${i.name}${req}${def}${choices}${desc}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Steps');
+    for (let idx = 0; idx < p.steps.length; idx += 1) {
+        const step = p.steps[idx];
+        const req = step.required === false ? ' (optional)' : '';
+        const review = step.humanReview ? ' — human review' : '';
+        const when = step.enabledWhen ? ` — enabledWhen ${step.enabledWhen}` : '';
+        lines.push(`${idx + 1}. [${step.type}] ${step.id}${req}${review}${when}`);
+        if (step.description)
+            lines.push(`     ${step.description}`);
+        if (step.instruction)
+            lines.push(`     instruction: ${step.instruction}`);
+        if (step.mcpTools?.length)
+            lines.push(`     mcpTools: ${step.mcpTools.join(', ')}`);
+        if (step.cliCommands?.length) {
+            for (const c of step.cliCommands)
+                lines.push(`     $ ${c}`);
+        }
+        if (step.references?.length)
+            lines.push(`     references: ${step.references.join(', ')}`);
+    }
+    if (p.notes?.length) {
+        lines.push('');
+        lines.push('## Notes');
+        for (const n of p.notes)
+            lines.push(`- ${n}`);
+    }
+    return lines.join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './model/pipeline-step.js';
+export * from './model/pipeline-input.js';
+export * from './model/pipeline-definition.js';
+export * from './define/define-pipeline.js';
+export * from './registry/pipeline-registry.js';
+export * from './load/pipeline-loader.js';
+export * from './format/pipeline-formatter.js';
+export * from './runtime/interpolate.js';
+export * from './runtime/render-script.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./model/pipeline-step.js";
+export * from "./model/pipeline-input.js";
+export * from "./model/pipeline-definition.js";
+export * from "./define/define-pipeline.js";
+export * from "./registry/pipeline-registry.js";
+export * from "./load/pipeline-loader.js";
+export * from "./format/pipeline-formatter.js";
+export * from "./runtime/interpolate.js";
+export * from "./runtime/render-script.js";

package/dist/load/pipeline-loader.d.ts

@@ -0,0 +1,12 @@
+import { type IImportContext } from '@shrkcrft/core';
+import type { IPipelineDefinition } from '../model/pipeline-definition.js';
+export interface ILoadedPipelines {
+    pipelines: IPipelineDefinition[];
+    warnings: string[];
+    sourceFiles: string[];
+}
+export interface ILoadPipelinesOptions {
+    importContext?: IImportContext;
+}
+export declare function loadPipelinesFromFile(filePath: string, options?: ILoadPipelinesOptions): Promise<ILoadedPipelines>;
+//# sourceMappingURL=pipeline-loader.d.ts.map

package/dist/load/pipeline-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-loader.d.ts","sourceRoot":"","sources":["../../src/load/pipeline-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAa3E,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAwC3B"}

package/dist/load/pipeline-loader.js

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs';
+import { safeImport } from '@shrkcrft/core';
+function isPipeline(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.id === 'string' &&
+        typeof v.title === 'string' &&
+        typeof v.description === 'string' &&
+        Array.isArray(v.steps));
+}
+export async function loadPipelinesFromFile(filePath, options = {}) {
+    const warnings = [];
+    const pipelines = [];
+    const sourceFiles = [];
+    if (!existsSync(filePath)) {
+        warnings.push(`Pipeline file not found: ${filePath}`);
+        return { pipelines, warnings, sourceFiles };
+    }
+    sourceFiles.push(filePath);
+    const result = options.importContext
+        ? await options.importContext.load(filePath)
+        : await safeImport(filePath, { skipExistsCheck: true });
+    if (!result.ok) {
+        const label = result.timedOut ? 'timed out importing' : 'Failed to import';
+        warnings.push(`${label} ${filePath}: ${result.error.message}`);
+        return { pipelines, warnings, sourceFiles };
+    }
+    const seen = new Set();
+    const tryPush = (v) => {
+        if (!isPipeline(v))
+            return;
+        if (seen.has(v.id))
+            return;
+        seen.add(v.id);
+        const p = { ...v, source: v.source ?? { origin: filePath } };
+        pipelines.push(p);
+    };
+    for (const key of Object.keys(result.module)) {
+        const v = result.module[key];
+        if (isPipeline(v)) {
+            tryPush(v);
+        }
+        else if (Array.isArray(v)) {
+            for (const item of v)
+                tryPush(item);
+        }
+    }
+    if (pipelines.length === 0)
+        warnings.push(`No pipelines exported by ${filePath}`);
+    return { pipelines, warnings, sourceFiles };
+}

package/dist/model/pipeline-definition.d.ts

@@ -0,0 +1,21 @@
+import type { IPipelineInput } from './pipeline-input.js';
+import type { IPipelineStep } from './pipeline-step.js';
+export interface IPipelineDefinition {
+    id: string;
+    title: string;
+    description: string;
+    tags?: readonly string[];
+    scope?: readonly string[];
+    /** Free-form task hints (e.g. "create-plugin"). Used for relevance lookup. */
+    appliesWhen?: readonly string[];
+    inputs?: readonly IPipelineInput[];
+    steps: readonly IPipelineStep[];
+    /** Free-form notes shown after the steps. */
+    notes?: readonly string[];
+    /** Originating file path. */
+    source?: {
+        origin?: string;
+    };
+}
+export type PipelineDefinitionInput = Omit<IPipelineDefinition, 'source'>;
+//# sourceMappingURL=pipeline-definition.d.ts.map

package/dist/model/pipeline-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-definition.d.ts","sourceRoot":"","sources":["../../src/model/pipeline-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,6BAA6B;IAC7B,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9B;AAED,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC"}

package/dist/model/pipeline-definition.js

@@ -0,0 +1 @@
+export {};

package/dist/model/pipeline-input.d.ts

@@ -0,0 +1,10 @@
+export interface IPipelineInput {
+    name: string;
+    description?: string;
+    required?: boolean;
+    /** Optional default value (string). */
+    default?: string;
+    /** Restricted set of allowed values. */
+    choices?: readonly string[];
+}
+//# sourceMappingURL=pipeline-input.d.ts.map

package/dist/model/pipeline-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-input.d.ts","sourceRoot":"","sources":["../../src/model/pipeline-input.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B"}

package/dist/model/pipeline-input.js

@@ -0,0 +1 @@
+export {};

package/dist/model/pipeline-step.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Step type taxonomy. Steps are declarative; SharkCraft does not run them.
+ * Pipelines are retrieval-shaped so an agent can read the plan and follow it.
+ */
+export declare enum PipelineStepType {
+    /** Build / load context (no side effects). */
+    Context = "context",
+    /** Agent-driven thinking step (instruction-only). */
+    Agent = "agent",
+    /** Produce a generation plan (dry-run only via MCP / CLI gen --dry-run). */
+    GenerationPlan = "generation-plan",
+    /** Apply a saved plan (CLI-only). */
+    ApplyPlan = "apply-plan",
+    /** Run a shell command. */
+    Command = "command",
+    /** Call an MCP tool. */
+    McpTool = "mcp-tool"
+}
+export interface IPipelineStep {
+    id: string;
+    /** Step type — gives the agent a clear class of action. */
+    type: PipelineStepType | string;
+    /** Short description shown alongside the step. */
+    description?: string;
+    /** MCP tool names referenced by this step. */
+    mcpTools?: readonly string[];
+    /** CLI command strings (with <placeholder> tokens). */
+    cliCommands?: readonly string[];
+    /** Agent instruction text (for type=agent). */
+    instruction?: string;
+    /** Default true: this step must run for the pipeline to succeed. */
+    required?: boolean;
+    /** True if a human must review the result before continuing. */
+    humanReview?: boolean;
+    /**
+     * Optional input name that gates this step. The CLI / MCP context builders
+     * pass it through as informational metadata; v1 does not evaluate it.
+     */
+    enabledWhen?: string;
+    /** Optional reference to a knowledge entry / template / path convention. */
+    references?: readonly string[];
+}
+//# sourceMappingURL=pipeline-step.d.ts.map

package/dist/model/pipeline-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-step.d.ts","sourceRoot":"","sources":["../../src/model/pipeline-step.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,gBAAgB;IAC1B,8CAA8C;IAC9C,OAAO,YAAY;IACnB,qDAAqD;IACrD,KAAK,UAAU;IACf,4EAA4E;IAC5E,cAAc,oBAAoB;IAClC,qCAAqC;IACrC,SAAS,eAAe;IACxB,2BAA2B;IAC3B,OAAO,YAAY;IACnB,wBAAwB;IACxB,OAAO,aAAa;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC;IAChC,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC"}

package/dist/model/pipeline-step.js

@@ -0,0 +1,19 @@
+/**
+ * Step type taxonomy. Steps are declarative; SharkCraft does not run them.
+ * Pipelines are retrieval-shaped so an agent can read the plan and follow it.
+ */
+export var PipelineStepType;
+(function (PipelineStepType) {
+    /** Build / load context (no side effects). */
+    PipelineStepType["Context"] = "context";
+    /** Agent-driven thinking step (instruction-only). */
+    PipelineStepType["Agent"] = "agent";
+    /** Produce a generation plan (dry-run only via MCP / CLI gen --dry-run). */
+    PipelineStepType["GenerationPlan"] = "generation-plan";
+    /** Apply a saved plan (CLI-only). */
+    PipelineStepType["ApplyPlan"] = "apply-plan";
+    /** Run a shell command. */
+    PipelineStepType["Command"] = "command";
+    /** Call an MCP tool. */
+    PipelineStepType["McpTool"] = "mcp-tool";
+})(PipelineStepType || (PipelineStepType = {}));

package/dist/registry/pipeline-registry.d.ts

@@ -0,0 +1,16 @@
+import type { IPipelineDefinition } from '../model/pipeline-definition.js';
+export declare class PipelineRegistry {
+    private readonly byId;
+    constructor(pipelines?: readonly IPipelineDefinition[]);
+    register(pipeline: IPipelineDefinition): void;
+    has(id: string): boolean;
+    get(id: string): IPipelineDefinition | null;
+    list(): IPipelineDefinition[];
+    search(query: string): IPipelineDefinition[];
+    /**
+     * Crude relevance: bias by overlap of task words with appliesWhen / tags /
+     * title. Returns the top `limit` pipelines (default 5).
+     */
+    relevantFor(task: string, limit?: number): IPipelineDefinition[];
+}
+//# sourceMappingURL=pipeline-registry.d.ts.map

package/dist/registry/pipeline-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-registry.d.ts","sourceRoot":"","sources":["../../src/registry/pipeline-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0C;gBAEnD,SAAS,GAAE,SAAS,mBAAmB,EAAO;IAI1D,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAI7C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAI3C,IAAI,IAAI,mBAAmB,EAAE;IAI7B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAc5C;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,mBAAmB,EAAE;CAwB5D"}

package/dist/registry/pipeline-registry.js

@@ -0,0 +1,64 @@
+export class PipelineRegistry {
+    byId = new Map();
+    constructor(pipelines = []) {
+        for (const p of pipelines)
+            this.register(p);
+    }
+    register(pipeline) {
+        this.byId.set(pipeline.id, pipeline);
+    }
+    has(id) {
+        return this.byId.has(id);
+    }
+    get(id) {
+        return this.byId.get(id) ?? null;
+    }
+    list() {
+        return [...this.byId.values()];
+    }
+    search(query) {
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return this.list();
+        return this.list().filter((p) => {
+            return (p.id.toLowerCase().includes(q) ||
+                p.title.toLowerCase().includes(q) ||
+                p.description.toLowerCase().includes(q) ||
+                (p.tags ?? []).some((t) => t.toLowerCase().includes(q)) ||
+                (p.appliesWhen ?? []).some((a) => a.toLowerCase().includes(q)));
+        });
+    }
+    /**
+     * Crude relevance: bias by overlap of task words with appliesWhen / tags /
+     * title. Returns the top `limit` pipelines (default 5).
+     */
+    relevantFor(task, limit = 5) {
+        const taskLower = task.toLowerCase();
+        const words = taskLower.split(/\W+/).filter((w) => w.length >= 3);
+        const scored = this.list().map((p) => {
+            let score = 0;
+            for (const tag of p.tags ?? []) {
+                if (taskLower.includes(tag.toLowerCase()))
+                    score += 5;
+            }
+            for (const a of p.appliesWhen ?? []) {
+                if (taskLower.includes(a.toLowerCase()))
+                    score += 6;
+            }
+            if (p.title.toLowerCase().includes(taskLower))
+                score += 4;
+            for (const w of words) {
+                if (p.id.toLowerCase().includes(w))
+                    score += 2;
+                if (p.description.toLowerCase().includes(w))
+                    score += 1;
+            }
+            return { p, score };
+        });
+        return scored
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map((s) => s.p);
+    }
+}

package/dist/runtime/interpolate.d.ts

@@ -0,0 +1,48 @@
+import type { IPipelineDefinition } from '../model/pipeline-definition.js';
+export interface IInterpolatedStep {
+    id: string;
+    type: string;
+    description?: string;
+    instruction?: string;
+    mcpTools: readonly string[];
+    cliCommands: readonly string[];
+    references: readonly string[];
+    required: boolean;
+    humanReview: boolean;
+    enabledWhen?: string;
+    /** True if this step was skipped because of enabledWhen and the user did not opt in. */
+    skipped: boolean;
+}
+export interface IInterpolatedPipeline {
+    id: string;
+    title: string;
+    description: string;
+    task: string;
+    inputs: Record<string, string>;
+    steps: IInterpolatedStep[];
+}
+export interface InterpolatePipelineOptions {
+    task: string;
+    projectRoot?: string;
+    /** Named inputs passed by the agent / user. */
+    inputs?: Record<string, string>;
+    /** Set of optional step ids to include. Pass '*' to include all optional steps. */
+    includeOptional?: readonly string[];
+}
+/**
+ * Interpolate placeholders in the pipeline's CLI commands / instructions /
+ * descriptions. Returns the resolved step list and a record of every value
+ * used (for traceability).
+ *
+ * Placeholders supported:
+ *  - <task>          → options.task
+ *  - <repo>          → options.projectRoot
+ *  - <pipelineId>    → the pipeline id
+ *  - <name>          → options.inputs.name etc.
+ *
+ * Optional steps (`required: false`) are dropped unless their id is listed in
+ * `includeOptional` (or `*`). Steps with `enabledWhen` are dropped unless
+ * `enabledWhen` is included in `includeOptional`.
+ */
+export declare function interpolatePipeline(pipeline: IPipelineDefinition, options: InterpolatePipelineOptions): IInterpolatedPipeline;
+//# sourceMappingURL=interpolate.d.ts.map

package/dist/runtime/interpolate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../../src/runtime/interpolate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAG3E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mFAAmF;IACnF,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,0BAA0B,GAClC,qBAAqB,CA2CvB"}

package/dist/runtime/interpolate.js

@@ -0,0 +1,67 @@
+function applyPlaceholders(input, values) {
+    return input.replace(/<([a-zA-Z][a-zA-Z0-9_-]*)>/g, (whole, key) => {
+        if (Object.prototype.hasOwnProperty.call(values, key))
+            return values[key];
+        return whole;
+    });
+}
+/**
+ * Interpolate placeholders in the pipeline's CLI commands / instructions /
+ * descriptions. Returns the resolved step list and a record of every value
+ * used (for traceability).
+ *
+ * Placeholders supported:
+ *  - <task>          → options.task
+ *  - <repo>          → options.projectRoot
+ *  - <pipelineId>    → the pipeline id
+ *  - <name>          → options.inputs.name etc.
+ *
+ * Optional steps (`required: false`) are dropped unless their id is listed in
+ * `includeOptional` (or `*`). Steps with `enabledWhen` are dropped unless
+ * `enabledWhen` is included in `includeOptional`.
+ */
+export function interpolatePipeline(pipeline, options) {
+    const values = {
+        task: options.task,
+        repo: options.projectRoot ?? '<repo>',
+        pipelineId: pipeline.id,
+        ...(options.inputs),
+    };
+    const includeAll = options.includeOptional?.includes('*') === true;
+    const includeSet = new Set(options.includeOptional ?? []);
+    function resolveStep(step) {
+        const requiredDefault = step.required !== false;
+        let skipped = false;
+        if (!requiredDefault && !includeAll && !includeSet.has(step.id)) {
+            skipped = true;
+        }
+        if (step.enabledWhen && !includeAll && !includeSet.has(step.enabledWhen) && !includeSet.has(step.id)) {
+            skipped = true;
+        }
+        const out = {
+            id: step.id,
+            type: step.type,
+            required: requiredDefault,
+            humanReview: step.humanReview === true,
+            mcpTools: step.mcpTools ?? [],
+            cliCommands: (step.cliCommands ?? []).map((c) => applyPlaceholders(c, values)),
+            references: step.references ?? [],
+            skipped,
+        };
+        if (step.description !== undefined)
+            out.description = applyPlaceholders(step.description, values);
+        if (step.instruction !== undefined)
+            out.instruction = applyPlaceholders(step.instruction, values);
+        if (step.enabledWhen !== undefined)
+            out.enabledWhen = step.enabledWhen;
+        return out;
+    }
+    return {
+        id: pipeline.id,
+        title: pipeline.title,
+        description: pipeline.description,
+        task: options.task,
+        inputs: values,
+        steps: pipeline.steps.map(resolveStep),
+    };
+}

package/dist/runtime/render-script.d.ts

@@ -0,0 +1,19 @@
+import type { IInterpolatedPipeline } from './interpolate.js';
+/**
+ * Render a copy-pasteable shell script from an interpolated pipeline. The
+ * script:
+ *  - sets `set -euo pipefail` at the top so failures stop the chain
+ *  - prefixes each step with a `# === N. step-id ===` header
+ *  - emits CLI commands verbatim (already interpolated)
+ *  - skips steps marked `skipped`
+ *  - inserts an "echo + manual confirm" stanza in front of write/apply steps
+ *  - leaves agent / mcp-tool steps as no-op `echo` lines (those are agent
+ *    actions, not shell commands)
+ */
+export declare function renderPipelineScript(pipeline: IInterpolatedPipeline): string;
+/**
+ * Find the next required, not-yet-marked-done step. Useful for an agent or
+ * the CLI that wants to ask "what should I do now?".
+ */
+export declare function findNextStep(pipeline: IInterpolatedPipeline): IInterpolatedPipeline['steps'][number] | null;
+//# sourceMappingURL=render-script.d.ts.map

package/dist/runtime/render-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-script.d.ts","sourceRoot":"","sources":["../../src/runtime/render-script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAI9D;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CA0C5E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,qBAAqB,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAM3G"}

package/dist/runtime/render-script.js

@@ -0,0 +1,68 @@
+const WRITE_STEP_TYPES = new Set(['apply-plan']);
+/**
+ * Render a copy-pasteable shell script from an interpolated pipeline. The
+ * script:
+ *  - sets `set -euo pipefail` at the top so failures stop the chain
+ *  - prefixes each step with a `# === N. step-id ===` header
+ *  - emits CLI commands verbatim (already interpolated)
+ *  - skips steps marked `skipped`
+ *  - inserts an "echo + manual confirm" stanza in front of write/apply steps
+ *  - leaves agent / mcp-tool steps as no-op `echo` lines (those are agent
+ *    actions, not shell commands)
+ */
+export function renderPipelineScript(pipeline) {
+    const lines = [];
+    lines.push('#!/usr/bin/env bash');
+    lines.push('# Generated by `shrk pipelines script`.');
+    lines.push(`# Pipeline: ${pipeline.id} — ${pipeline.title}`);
+    lines.push(`# Task: ${pipeline.task}`);
+    lines.push('set -euo pipefail');
+    lines.push('');
+    let stepIndex = 0;
+    for (const step of pipeline.steps) {
+        stepIndex += 1;
+        if (step.skipped) {
+            lines.push(`# === ${stepIndex}. ${step.id} (skipped — optional, not included) ===`);
+            lines.push('');
+            continue;
+        }
+        const reviewTag = step.humanReview ? ' [HUMAN REVIEW]' : '';
+        const optionalTag = step.required ? '' : ' (optional)';
+        lines.push(`# === ${stepIndex}. [${step.type}] ${step.id}${optionalTag}${reviewTag} ===`);
+        if (step.description)
+            lines.push(`# ${step.description.replace(/\n/g, '\n# ')}`);
+        if (step.instruction)
+            lines.push(`# instruction: ${step.instruction.replace(/\n/g, '\n# ')}`);
+        if (step.references.length) {
+            lines.push(`# references: ${step.references.join(', ')}`);
+        }
+        if (step.mcpTools.length) {
+            lines.push(`# mcpTools: ${step.mcpTools.join(', ')}`);
+        }
+        if (WRITE_STEP_TYPES.has(step.type)) {
+            lines.push('echo "About to write files. Confirm by pressing Enter, or Ctrl-C to abort."');
+            lines.push('read -r _');
+        }
+        if (step.cliCommands.length === 0 && step.type !== 'command' && step.type !== 'apply-plan') {
+            // Agent-only step: emit an echo so the script remains valid but no-op.
+            lines.push(`echo "→ ${step.id}: agent/mcp action — no shell command"`);
+        }
+        for (const cmd of step.cliCommands) {
+            lines.push(cmd);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Find the next required, not-yet-marked-done step. Useful for an agent or
+ * the CLI that wants to ask "what should I do now?".
+ */
+export function findNextStep(pipeline) {
+    for (const step of pipeline.steps) {
+        if (step.skipped)
+            continue;
+        return step;
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shrkcrft/pipelines",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft AI development pipelines: typed flow definitions, registry, loader, formatter.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/pipelines"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "pipelines",
+    "workflows",
+    "ai-agent"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}