@sweny-ai/core 0.1.0

package/dist/testing.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Test Helpers
+ *
+ * MockClaude for running workflows without an API key.
+ * File-based skill for local testing.
+ *
+ * @example
+ * ```ts
+ * import { MockClaude, fileSkill } from '@sweny-ai/core/testing'
+ *
+ * const claude = new MockClaude({
+ *   gather: {
+ *     toolCalls: [{ tool: 'fs_read_json', input: { path: 'logs.json' } }],
+ *     data: { logs: [...] },
+ *   },
+ *   investigate: {
+ *     data: { root_cause: 'NPE in handler', severity: 'high' },
+ *   },
+ * })
+ * ```
+ */
+import type { Claude, NodeResult, Tool, JSONSchema, Workflow } from "./types.js";
+export interface MockNodeResponse {
+    /** Tool calls to execute (optional — handlers will be called) */
+    toolCalls?: {
+        tool: string;
+        input: Record<string, unknown>;
+    }[];
+    /** Data to return as the node result */
+    data?: Record<string, unknown>;
+    /** Status (default: "success") */
+    status?: "success" | "skipped" | "failed";
+}
+export interface MockClaudeOptions {
+    /** Node ID → scripted response */
+    responses: Record<string, MockNodeResponse>;
+    /** Route decisions: "fromNode" → chosen target node ID */
+    routes?: Record<string, string>;
+    /** Workflow definition — enables instruction-based node matching (required for branching workflows) */
+    workflow?: Workflow;
+}
+/**
+ * A mock Claude client that follows a script.
+ *
+ * For each node, it executes scripted tool calls and returns
+ * scripted results. For routing decisions, it follows the
+ * routes map or defaults to the first choice.
+ */
+export declare class MockClaude implements Claude {
+    private callOrder;
+    private responses;
+    private routes;
+    private instructionMap;
+    constructor(opts: MockClaudeOptions);
+    /** Returns the order in which nodes were executed */
+    get executedNodes(): string[];
+    run(opts: {
+        instruction: string;
+        context: Record<string, unknown>;
+        tools: Tool[];
+        outputSchema?: JSONSchema;
+    }): Promise<NodeResult>;
+    evaluate(opts: {
+        question: string;
+        context: Record<string, unknown>;
+        choices: {
+            id: string;
+            description: string;
+        }[];
+    }): Promise<string>;
+    /**
+     * Identify which node is being executed.
+     *
+     * Strategy:
+     * 1. If a workflow was provided, match by instruction text (accurate for branching)
+     * 2. Otherwise, fall back to sequential key matching (works for linear DAGs)
+     */
+    private identifyNode;
+}
+import type { Skill } from "./types.js";
+/**
+ * Create a file-based skill for local testing.
+ *
+ * Replaces ALL four file providers (observability, issue-tracking,
+ * source-control, notification) with a single skill that reads/writes
+ * local JSON/markdown files.
+ */
+export declare function createFileSkill(outputDir: string): Skill;

package/dist/testing.js

@@ -0,0 +1,253 @@
+/**
+ * Test Helpers
+ *
+ * MockClaude for running workflows without an API key.
+ * File-based skill for local testing.
+ *
+ * @example
+ * ```ts
+ * import { MockClaude, fileSkill } from '@sweny-ai/core/testing'
+ *
+ * const claude = new MockClaude({
+ *   gather: {
+ *     toolCalls: [{ tool: 'fs_read_json', input: { path: 'logs.json' } }],
+ *     data: { logs: [...] },
+ *   },
+ *   investigate: {
+ *     data: { root_cause: 'NPE in handler', severity: 'high' },
+ *   },
+ * })
+ * ```
+ */
+import { consoleLogger } from "./types.js";
+/**
+ * A mock Claude client that follows a script.
+ *
+ * For each node, it executes scripted tool calls and returns
+ * scripted results. For routing decisions, it follows the
+ * routes map or defaults to the first choice.
+ */
+export class MockClaude {
+    callOrder = [];
+    responses;
+    routes;
+    instructionMap; // instruction text → node ID
+    constructor(opts) {
+        this.responses = opts.responses;
+        this.routes = opts.routes ?? {};
+        // Build reverse map: instruction → node ID (for accurate matching in branching workflows)
+        this.instructionMap = new Map();
+        if (opts.workflow) {
+            for (const [id, node] of Object.entries(opts.workflow.nodes)) {
+                this.instructionMap.set(node.instruction, id);
+            }
+        }
+    }
+    /** Returns the order in which nodes were executed */
+    get executedNodes() {
+        return [...this.callOrder];
+    }
+    async run(opts) {
+        // Identify which node this is by matching instruction text against responses
+        // The executor wraps tools with event tracking, so we can find the node
+        // by checking which response key's instruction appears
+        const nodeId = this.identifyNode(opts.instruction);
+        this.callOrder.push(nodeId);
+        const response = this.responses[nodeId];
+        if (!response) {
+            return {
+                status: "success",
+                data: { summary: `Mock: no scripted response for "${nodeId}"` },
+                toolCalls: [],
+            };
+        }
+        // Execute scripted tool calls
+        const toolCalls = [];
+        if (response.toolCalls) {
+            for (const tc of response.toolCalls) {
+                const tool = opts.tools.find((t) => t.name === tc.tool);
+                if (tool) {
+                    const defaultCtx = { config: {}, logger: consoleLogger };
+                    const output = await tool.handler(tc.input, defaultCtx);
+                    toolCalls.push({ tool: tc.tool, input: tc.input, output });
+                }
+                else {
+                    toolCalls.push({ tool: tc.tool, input: tc.input, output: { error: "tool not found" } });
+                }
+            }
+        }
+        return {
+            status: response.status ?? "success",
+            data: response.data ?? {},
+            toolCalls,
+        };
+    }
+    async evaluate(opts) {
+        // Check if we have a scripted route from the last executed node
+        const lastNode = this.callOrder[this.callOrder.length - 1];
+        if (lastNode && this.routes[lastNode]) {
+            const route = this.routes[lastNode];
+            // Validate route is a valid choice
+            if (opts.choices.some((c) => c.id === route)) {
+                return route;
+            }
+        }
+        // Default: first choice
+        return opts.choices[0].id;
+    }
+    /**
+     * Identify which node is being executed.
+     *
+     * Strategy:
+     * 1. If a workflow was provided, match by instruction text (accurate for branching)
+     * 2. Otherwise, fall back to sequential key matching (works for linear DAGs)
+     */
+    identifyNode(instruction) {
+        // 1. Instruction-based matching (accurate for branching workflows)
+        if (this.instructionMap.size > 0) {
+            const nodeId = this.instructionMap.get(instruction);
+            if (nodeId && nodeId in this.responses)
+                return nodeId;
+        }
+        // 2. Check if any response key appears literally in the instruction
+        const keys = Object.keys(this.responses);
+        for (const key of keys) {
+            if (instruction.toLowerCase().includes(key.toLowerCase()) && !this.callOrder.includes(key)) {
+                return key;
+            }
+        }
+        // 3. Sequential fallback: return the next unused key
+        const unused = keys.filter((k) => !this.callOrder.includes(k));
+        return unused[0] ?? `unknown-${this.callOrder.length}`;
+    }
+}
+/**
+ * Create a file-based skill for local testing.
+ *
+ * Replaces ALL four file providers (observability, issue-tracking,
+ * source-control, notification) with a single skill that reads/writes
+ * local JSON/markdown files.
+ */
+export function createFileSkill(outputDir) {
+    // Lazy-loaded — only resolved when a handler actually runs (Node-only)
+    let _fs = null;
+    let _path = null;
+    let _resolved = null;
+    async function getFs() {
+        if (!_fs)
+            _fs = await import("node:fs");
+        return _fs;
+    }
+    async function getResolved() {
+        if (!_path)
+            _path = await import("node:path");
+        if (!_resolved)
+            _resolved = _path.resolve(outputDir);
+        return { path: _path, resolved: _resolved };
+    }
+    return {
+        id: "filesystem",
+        name: "Local Filesystem",
+        category: "general",
+        description: "Read logs and write issues/PRs/notifications to local files (for testing)",
+        config: {},
+        tools: [
+            {
+                name: "fs_read_json",
+                description: "Read and parse a JSON file",
+                input_schema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "File path (absolute or relative to output dir)" },
+                    },
+                    required: ["path"],
+                },
+                handler: async (input) => {
+                    const fs = await getFs();
+                    const { path: p, resolved } = await getResolved();
+                    const filePath = p.isAbsolute(input.path) ? input.path : p.join(resolved, input.path);
+                    const raw = fs.readFileSync(filePath, "utf-8");
+                    return JSON.parse(raw);
+                },
+            },
+            {
+                name: "fs_read_text",
+                description: "Read a text file",
+                input_schema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string" },
+                    },
+                    required: ["path"],
+                },
+                handler: async (input) => {
+                    const fs = await getFs();
+                    const { path: p, resolved } = await getResolved();
+                    const filePath = p.isAbsolute(input.path) ? input.path : p.join(resolved, input.path);
+                    return fs.readFileSync(filePath, "utf-8");
+                },
+            },
+            {
+                name: "fs_write_json",
+                description: "Write a JSON object to a file",
+                input_schema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "File path relative to output dir" },
+                        data: { type: "object", description: "JSON data to write" },
+                    },
+                    required: ["path", "data"],
+                },
+                handler: async (input) => {
+                    const fs = await getFs();
+                    const { path: p, resolved } = await getResolved();
+                    const filePath = p.join(resolved, input.path);
+                    fs.mkdirSync(p.dirname(filePath), { recursive: true });
+                    fs.writeFileSync(filePath, JSON.stringify(input.data, null, 2), "utf-8");
+                    return { written: filePath };
+                },
+            },
+            {
+                name: "fs_write_markdown",
+                description: "Write a markdown file (for issues, PRs, notifications)",
+                input_schema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "File path relative to output dir" },
+                        content: { type: "string", description: "Markdown content" },
+                    },
+                    required: ["path", "content"],
+                },
+                handler: async (input) => {
+                    const fs = await getFs();
+                    const { path: p, resolved } = await getResolved();
+                    const filePath = p.join(resolved, input.path);
+                    fs.mkdirSync(p.dirname(filePath), { recursive: true });
+                    fs.writeFileSync(filePath, input.content, "utf-8");
+                    return { written: filePath };
+                },
+            },
+            {
+                name: "fs_list_dir",
+                description: "List files in a directory",
+                input_schema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Directory path relative to output dir" },
+                    },
+                },
+                handler: async (input) => {
+                    const fs = await getFs();
+                    const { path: p, resolved } = await getResolved();
+                    const dirPath = input.path ? p.join(resolved, input.path) : resolved;
+                    try {
+                        return fs.readdirSync(dirPath);
+                    }
+                    catch (err) {
+                        return { error: `Failed to list directory: ${err.message}`, files: [] };
+                    }
+                },
+            },
+        ],
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+export type JSONSchema = Record<string, unknown>;
+/** Context passed to tool handlers at execution time */
+export interface ToolContext {
+    /** Resolved config values (env vars + explicit overrides) */
+    config: Record<string, string>;
+    /** Structured logger */
+    logger: Logger;
+}
+/** A single tool Claude can invoke */
+export interface Tool {
+    name: string;
+    description: string;
+    input_schema: JSONSchema;
+    handler: (input: any, ctx: ToolContext) => Promise<unknown>;
+}
+/** Config field declaration — skills say what they need */
+export interface ConfigField {
+    description: string;
+    required?: boolean;
+    /** Default environment variable to read from */
+    env?: string;
+}
+/** Skill categories — used for validation and grouping */
+export type SkillCategory = "git" | "observability" | "tasks" | "notification" | "general";
+/** A skill groups related tools with shared config requirements */
+export interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    category: SkillCategory;
+    config: Record<string, ConfigField>;
+    tools: Tool[];
+}
+/** A node in the workflow DAG */
+export interface Node {
+    /** Human-readable name */
+    name: string;
+    /** What Claude should accomplish at this step */
+    instruction: string;
+    /** Skill IDs available at this node */
+    skills: string[];
+    /** Optional structured output schema */
+    output?: JSONSchema;
+}
+/** An edge connecting two nodes */
+export interface Edge {
+    from: string;
+    to: string;
+    /** Natural language condition — Claude evaluates at runtime */
+    when?: string;
+}
+/** A complete workflow definition — pure data, fully serializable */
+export interface Workflow {
+    id: string;
+    name: string;
+    description: string;
+    nodes: Record<string, Node>;
+    edges: Edge[];
+    entry: string;
+}
+export interface NodeResult {
+    status: "success" | "skipped" | "failed";
+    /** Arbitrary data produced by this node */
+    data: Record<string, unknown>;
+    /** Tool calls made during this node's execution */
+    toolCalls: ToolCall[];
+}
+export interface ToolCall {
+    tool: string;
+    input: unknown;
+    output: unknown;
+}
+export type ExecutionEvent = {
+    type: "workflow:start";
+    workflow: string;
+} | {
+    type: "node:enter";
+    node: string;
+    instruction: string;
+} | {
+    type: "tool:call";
+    node: string;
+    tool: string;
+    input: unknown;
+} | {
+    type: "tool:result";
+    node: string;
+    tool: string;
+    output: unknown;
+} | {
+    type: "node:exit";
+    node: string;
+    result: NodeResult;
+} | {
+    type: "route";
+    from: string;
+    to: string;
+    reason: string;
+} | {
+    type: "workflow:end";
+    results: Record<string, NodeResult>;
+};
+export type Observer = (event: ExecutionEvent) => void;
+export interface Claude {
+    /** Run a node: give Claude an instruction, context, and tools */
+    run(opts: {
+        instruction: string;
+        context: Record<string, unknown>;
+        tools: Tool[];
+        outputSchema?: JSONSchema;
+    }): Promise<NodeResult>;
+    /** Evaluate a routing condition — pick one of N choices */
+    evaluate(opts: {
+        question: string;
+        context: Record<string, unknown>;
+        choices: {
+            id: string;
+            description: string;
+        }[];
+    }): Promise<string>;
+}
+export interface McpServerConfig {
+    type: "stdio" | "http";
+    command?: string;
+    args?: string[];
+    url?: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+}
+export interface McpAutoConfig {
+    sourceControlProvider?: string;
+    issueTrackerProvider?: string;
+    observabilityProvider?: string;
+    credentials: Record<string, string>;
+    workspaceTools?: string[];
+    userMcpServers?: Record<string, McpServerConfig>;
+}
+export interface Logger {
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+}
+export declare const consoleLogger: Logger;

package/dist/types.js

@@ -0,0 +1,11 @@
+// ─── Skill System ────────────────────────────────────────────────
+//
+// A Skill is a logical group of tools that share configuration.
+// Skills replace "providers" — instead of typed interfaces that
+// step code calls, skills expose tools that Claude calls directly.
+export const consoleLogger = {
+    info: (msg, data) => console.log(`[info] ${msg}`, data ?? ""),
+    warn: (msg, data) => console.warn(`[warn] ${msg}`, data ?? ""),
+    error: (msg, data) => console.error(`[error] ${msg}`, data ?? ""),
+    debug: (msg, data) => console.debug(`[debug] ${msg}`, data ?? ""),
+};

package/dist/workflow-builder.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Workflow Builder
+ *
+ * Generates and refines SWEny workflow definitions using the Claude
+ * interface (headless Claude Code). Accepts a natural language
+ * description and available skills, and returns a validated Workflow.
+ */
+import type { Workflow, Skill, Claude, Logger } from "./types.js";
+export interface BuildWorkflowOptions {
+    /** Claude client (headless Claude Code) */
+    claude: Claude;
+    /** Skills available for use in the workflow */
+    skills: Skill[];
+    /** Optional logger */
+    logger?: Logger;
+}
+/**
+ * Build the system prompt sent to Claude as the instruction.
+ * Includes the JSON schema, available skills, instruction quality
+ * guidance, rules, and optionally an existing workflow to refine.
+ */
+export declare function buildSystemPrompt(skills: Skill[], existingWorkflow?: Workflow): string;
+/**
+ * Extract and validate a Workflow from the raw data returned by
+ * claude.run(). The ClaudeClient spreads parsed JSON into data and
+ * adds a `summary` key from the text response. We strip `summary`
+ * and any other non-workflow keys before parsing.
+ */
+export declare function extractWorkflow(data: Record<string, unknown>): Workflow;
+/**
+ * Generate a complete workflow from a natural language description.
+ *
+ * Builds a system prompt with the workflow JSON schema, available
+ * skills, instruction quality guidance, and rules. Calls claude.run()
+ * with no tools (pure generation task). Parses and validates the
+ * returned JSON as a Workflow.
+ */
+export declare function buildWorkflow(description: string, options: BuildWorkflowOptions): Promise<Workflow>;
+/**
+ * Refine an existing workflow based on a natural language instruction.
+ *
+ * Same as buildWorkflow but includes the current workflow in the
+ * prompt as context so Claude can modify it.
+ */
+export declare function refineWorkflow(workflow: Workflow, instruction: string, options: BuildWorkflowOptions): Promise<Workflow>;

package/dist/workflow-builder.js

@@ -0,0 +1,120 @@
+/**
+ * Workflow Builder
+ *
+ * Generates and refines SWEny workflow definitions using the Claude
+ * interface (headless Claude Code). Accepts a natural language
+ * description and available skills, and returns a validated Workflow.
+ */
+import { workflowZ, validateWorkflow, workflowJsonSchema } from "./schema.js";
+// ─── Instruction quality guidance ────────────────────────────────
+const INSTRUCTION_GUIDANCE = `Each node's \`instruction\` field is a detailed prompt that Claude will execute autonomously.
+Write instructions as if briefing a skilled engineer who has access to the node's tools
+but no other context. Be specific about:
+
+- WHAT to query/search/create (not just "check for errors" — specify filters, time ranges, grouping)
+- HOW to interpret results (what counts as actionable? what thresholds matter?)
+- WHAT output to produce (structured findings, not just "summarize")
+- HOW to handle edge cases (no results found, too many results, ambiguous data)
+
+Bad:  "Query Sentry for errors"
+Good: "Query Sentry for unresolved errors from the last 24 hours. Group by issue
+       fingerprint. For each group, note: error count, affected services, first/last
+       seen timestamps, and stack trace summary. Prioritize by frequency × recency.
+       If no errors found, report that explicitly so downstream nodes can skip."`;
+// ─── Helpers ─────────────────────────────────────────────────────
+/**
+ * Build the system prompt sent to Claude as the instruction.
+ * Includes the JSON schema, available skills, instruction quality
+ * guidance, rules, and optionally an existing workflow to refine.
+ */
+export function buildSystemPrompt(skills, existingWorkflow) {
+    const skillList = skills.map((s) => `- ${s.id}: ${s.description}`).join("\n");
+    const parts = [
+        "You generate SWEny workflow definitions as JSON.",
+        "",
+        "## Workflow JSON Schema",
+        "```json",
+        JSON.stringify(workflowJsonSchema, null, 2),
+        "```",
+        "",
+        "## Available Skills",
+        skillList || "(none)",
+        "",
+        "## Instruction Quality",
+        INSTRUCTION_GUIDANCE,
+        "",
+        "## Rules",
+        "- Use snake_case for node IDs (e.g. gather_errors, create_ticket)",
+        "- Set `entry` to the first node in the flow",
+        "- Only reference skill IDs from the list above in node `skills` arrays",
+        "- Use natural language for edge `when` conditions",
+        "- Every node must be reachable from the entry node",
+        "- Return ONLY the workflow JSON object — no markdown fences, no explanation",
+    ];
+    if (existingWorkflow) {
+        parts.push("", "## Current Workflow (modify this)", "```json", JSON.stringify(existingWorkflow, null, 2), "```");
+    }
+    return parts.join("\n");
+}
+/**
+ * Extract and validate a Workflow from the raw data returned by
+ * claude.run(). The ClaudeClient spreads parsed JSON into data and
+ * adds a `summary` key from the text response. We strip `summary`
+ * and any other non-workflow keys before parsing.
+ */
+export function extractWorkflow(data) {
+    // Remove keys added by ClaudeClient that aren't part of the workflow schema
+    const { summary: _summary, ...rest } = data;
+    // workflowZ.parse throws a ZodError on invalid input
+    const parsed = workflowZ.parse(rest);
+    const errors = validateWorkflow(parsed);
+    if (errors.length > 0) {
+        throw new Error(`Generated workflow has validation errors: ${errors.map((e) => e.message).join("; ")}`);
+    }
+    return parsed;
+}
+// ─── Public API ───────────────────────────────────────────────────
+/**
+ * Generate a complete workflow from a natural language description.
+ *
+ * Builds a system prompt with the workflow JSON schema, available
+ * skills, instruction quality guidance, and rules. Calls claude.run()
+ * with no tools (pure generation task). Parses and validates the
+ * returned JSON as a Workflow.
+ */
+export async function buildWorkflow(description, options) {
+    const { claude, skills, logger } = options;
+    const instruction = buildSystemPrompt(skills);
+    logger?.debug("buildWorkflow: calling claude.run", { description });
+    const result = await claude.run({
+        instruction,
+        context: { description },
+        tools: [],
+        outputSchema: workflowJsonSchema,
+    });
+    if (result.status === "failed") {
+        throw new Error(`Claude failed to generate workflow: ${result.data.error ?? "unknown error"}`);
+    }
+    return extractWorkflow(result.data);
+}
+/**
+ * Refine an existing workflow based on a natural language instruction.
+ *
+ * Same as buildWorkflow but includes the current workflow in the
+ * prompt as context so Claude can modify it.
+ */
+export async function refineWorkflow(workflow, instruction, options) {
+    const { claude, skills, logger } = options;
+    const systemPrompt = buildSystemPrompt(skills, workflow);
+    logger?.debug("refineWorkflow: calling claude.run", { instruction });
+    const result = await claude.run({
+        instruction: systemPrompt,
+        context: { instruction },
+        tools: [],
+        outputSchema: workflowJsonSchema,
+    });
+    if (result.status === "failed") {
+        throw new Error(`Claude failed to refine workflow: ${result.data.error ?? "unknown error"}`);
+    }
+    return extractWorkflow(result.data);
+}

package/dist/workflow-builder.test.d.ts

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