@zibby/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zibby
+
+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,147 @@
+# @zibby/test-automation-core
+
+Core test automation engine with multi-agent support, DAG-based workflow execution, and extensible skill system.
+
+## Features
+
+- **Multi-Agent Support** — Cursor (via cursor-agent CLI) and Claude (via Anthropic API)
+- **Workflow Engine** — DAG-based graph compiler with typed state, conditional branching, and lifecycle hooks
+- **Skill System** — Extensible registry that maps capabilities to MCP servers
+- **Node Registry** — Register custom workflow nodes with Zod schemas and prompts
+- **Code Generator** — Compile workflow graphs into standalone executable scripts
+
+## Installation
+
+```bash
+npm install @zibby/test-automation-core
+```
+
+## Usage
+
+### Functional Style (recommended)
+
+```javascript
+import { workflow, z } from '@zibby/test-automation-core';
+import '@zibby/skills';
+
+const agent = workflow((graph) => {
+  graph.addNode('plan', {
+    name: 'plan',
+    prompt: (state) => `Analyze: "${state.input}". Return JSON.`,
+    outputSchema: z.object({ action: z.string() }),
+  });
+  graph.addNode('execute', {
+    name: 'execute',
+    skills: ['browser'],
+    prompt: (state) => `Execute: ${state.plan.action}`,
+    outputSchema: z.object({ result: z.string() }),
+  });
+  graph.setEntryPoint('plan');
+  graph.addEdge('plan', 'execute');
+  graph.addEdge('execute', 'END');
+});
+
+await agent.run('Navigate to example.com and verify the title');
+```
+
+### Class-Based Style
+
+```javascript
+import { WorkflowAgent, WorkflowGraph, z } from '@zibby/test-automation-core';
+
+class MyAgent extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('plan', { /* ... */ });
+    graph.addNode('execute', { /* ... */ });
+    graph.setEntryPoint('plan');
+    graph.addEdge('plan', 'execute');
+    graph.addEdge('execute', 'END');
+    return graph;
+  }
+}
+
+const agent = new MyAgent();
+await agent.run('Do something');
+```
+
+### Custom Nodes
+
+Define workflow nodes with Zod output schemas:
+
+```javascript
+import { z } from '@zibby/test-automation-core';
+
+export const myNode = {
+  name: 'analyze',
+  skills: ['browser'],
+  prompt: (state) => `Analyze ${state.input} and extract key information`,
+  outputSchema: z.object({
+    title: z.string(),
+    links: z.array(z.string()),
+  }),
+};
+```
+
+### Skill Registry
+
+```javascript
+import { registerSkill, getSkill, listSkillIds } from '@zibby/test-automation-core';
+
+// Register a custom MCP skill
+registerSkill({
+  id: 'my-tool',
+  serverName: 'my-mcp-server',
+  command: 'npx',
+  args: ['my-mcp-package'],
+  allowedTools: ['do_thing'],
+  resolve: () => ({ command: 'npx', args: ['my-mcp-package'] }),
+});
+
+// Query the registry
+const skill = getSkill('browser');
+const allIds = listSkillIds();
+```
+
+## Architecture
+
+```
+@zibby/test-automation-core
+├── src/
+│   ├── framework/           # Workflow engine
+│   │   ├── graph.js         # WorkflowGraph (DAG builder)
+│   │   ├── graph-compiler.js # Compiles graphs to execution plans
+│   │   ├── node.js          # Node execution with agent invocation
+│   │   ├── node-registry.js # Register/lookup custom nodes
+│   │   ├── skill-registry.js # Skill → MCP server mapping
+│   │   ├── tool-resolver.js # Resolves skills to MCP configs
+│   │   ├── code-generator.js # Generate standalone scripts
+│   │   ├── state.js         # Typed workflow state
+│   │   └── agents/          # Agent strategies
+│   │       ├── cursor-strategy.js
+│   │       └── claude-strategy.js
+│   ├── runtime/             # Browser runtime utilities
+│   ├── utils/               # Helpers (logger, selectors, parsers)
+│   └── index.js             # Public API
+├── templates/               # Built-in workflow templates
+│   ├── browser-test-automation/
+│   └── code-analysis/
+└── scripts/                 # Setup scripts (Playwright MCP, CI)
+```
+
+## Environment Variables
+
+```bash
+# Cursor agent (CI/CD only — local uses stored credentials)
+CURSOR_API_KEY=your-cursor-token
+
+# Claude agent
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Cloud sync (optional)
+ZIBBY_API_KEY=zby_xxx
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@zibby/core",
+  "version": "0.1.0",
+  "description": "Core test automation engine with multi-agent and multi-MCP support",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./sync": "./src/sync/index.js",
+    "./framework/graph.js": "./src/framework/graph.js",
+    "./framework/state.js": "./src/framework/state.js",
+    "./framework/node.js": "./src/framework/node.js",
+    "./framework/graph-compiler.js": "./src/framework/graph-compiler.js",
+    "./framework/node-registry.js": "./src/framework/node-registry.js",
+    "./framework/skill-registry.js": "./src/framework/skill-registry.js",
+    "./framework/tool-resolver.js": "./src/framework/tool-resolver.js",
+    "./framework/function-bridge.js": "./src/framework/function-bridge.js",
+    "./framework/function-skill-registry.js": "./src/framework/function-skill-registry.js",
+    "./framework/code-generator.js": "./src/framework/code-generator.js",
+    "./utils/ast-utils.js": "./src/utils/ast-utils.js",
+    "./utils/mcp-config-writer.js": "./src/utils/mcp-config-writer.js",
+    "./utils/node-schema-parser.js": "./src/utils/node-schema-parser.js",
+    "./templates/register-nodes.js": "./templates/register-nodes.js",
+    "./templates": "./templates/index.js",
+    "./templates/*": "./templates/*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:state-schema": "vitest run src/framework/__tests__/state-schema.test.js",
+    "test:state-schema:e2e": "node src/framework/__tests__/state-schema.e2e.test.js",
+    "export:workflows": "node scripts/export-default-workflows.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "testing",
+    "automation",
+    "playwright",
+    "ai",
+    "mcp"
+  ],
+  "author": "Zibby",
+  "license": "MIT",
+  "homepage": "https://zibby.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ZibbyHQ/zibby-agent"
+  },
+  "bugs": {
+    "url": "https://github.com/ZibbyHQ/zibby-agent/issues"
+  },
+  "files": [
+    "src/",
+    "!src/**/__tests__/",
+    "!src/**/*.test.js",
+    "!src/**/*.spec.js",
+    "templates/",
+    "!templates/**/__tests__/",
+    "!templates/**/*.test.js",
+    "!templates/**/*.spec.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.50",
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@playwright/mcp": "^0.0.54",
+    "acorn": "^8.15.0",
+    "acorn-walk": "^8.3.4",
+    "axios": "^1.13.3",
+    "chalk": "^5.3.0",
+    "dotenv": "^16.4.0",
+    "handlebars": "^4.7.8",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "optionalDependencies": {
+    "@zibby/mcp-browser": "*"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.49.0",
+    "playwright": ">=1.49.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "vitest": "^4.0.18"
+  }
+}

package/src/agents/base.js

@@ -0,0 +1,361 @@
+import { spawn } from 'child_process';
+import { mkdirSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { ContextLoader } from '../framework/context-loader.js';
+import { StreamingParser } from '../utils/streaming-parser.js';
+import { findCursorAgentPath } from '../utils/cursor-utils.js';
+import { DEFAULT_OUTPUT_BASE, SESSIONS_DIR, SESSION_INFO_FILE } from '../framework/constants.js';
+import { WorkflowGraph } from '../framework/graph.js';
+
+export class WorkflowAgent {
+  constructor(config = {}) {
+    this.config = config;
+    this.adapter = null;
+    this.paths = config.paths || { specs: 'test-specs', generated: 'tests' };
+    this.agentCommand = config.agentCommand || 'cursor-agent';
+    this.buildArgs = config.buildArgs || ((prompt, useStreaming = true) => {
+      const args = [
+        '-p', 
+        prompt, 
+        '--approve-mcps', 
+        '--force'
+      ];
+      
+      // Only use streaming for non-structured output
+      if (useStreaming) {
+        args.push('--output-format', 'stream-json');
+        args.push('--stream-partial-output');
+      }
+      
+      return args;
+    });
+  }
+
+  /**
+   * Extract JSON result from NDJSON streaming output
+   * Uses StreamingParser for clean, reliable extraction
+   */
+  static extractJsonFromStream(rawOutput) {
+    return StreamingParser.extractResult(rawOutput);
+  }
+
+  async initialize(adapter) {
+    this.adapter = adapter;
+    if (adapter && !adapter.isConnected()) {
+      await adapter.connect();
+    }
+  }
+
+  buildGraph() {
+    throw new Error('buildGraph() must be implemented by subclass');
+  }
+
+  async onComplete(_result) {
+    // Override in subclass for post-execution processing
+    // (e.g., save artifacts, enrich events, rename videos)
+  }
+
+  async run(input, options = {}) {
+    const graph = this.buildGraph();
+    const initialState = typeof input === 'object' && !Array.isArray(input)
+      ? { input, ...input, ...options }
+      : { input, ...options };
+    const result = await graph.run(this, initialState);
+    return result;
+  }
+
+  async executeNode(nodeConfig, state) {
+    const { prompt, outputSchema, model } = nodeConfig;
+    const promptText = typeof prompt === 'function' ? prompt(state) : prompt;
+    
+    console.log(`\n📝 Prompt:\n${promptText}\n`);
+    
+    const output = await this.executePrompt(promptText, state.cwd, 300000, model);
+    
+    console.log(`\n📤 Raw Output:\n${output}\n`);
+    
+    let parsedOutput = null;
+    if (outputSchema) {
+      try {
+        // Use the static helper to extract JSON from streaming output
+        parsedOutput = WorkflowAgent.extractJsonFromStream(output);
+        
+        if (!parsedOutput) {
+          throw new Error('No valid result JSON found in output');
+        }
+        
+        console.log(`\n✅ Parsed Output:\n${JSON.stringify(parsedOutput, null, 2)}\n`);
+      } catch (err) {
+        console.warn(`⚠️  Failed to parse output as JSON: ${err.message}`);
+      }
+    }
+    
+    return { success: true, output: parsedOutput, raw: output };
+  }
+
+  async cleanup() {
+    if (this.adapter && this.adapter.isConnected()) {
+      await this.adapter.disconnect();
+    }
+  }
+
+  async executePrompt(prompt, cwd = process.cwd(), timeoutMs = 300000, model = null, useStreaming = true) {
+    // Resolve cursor-agent path if needed (handles cases where PATH isn't set)
+    let agentCommand = this.agentCommand;
+    if (agentCommand === 'cursor-agent') {
+      const resolvedPath = await findCursorAgentPath();
+      if (resolvedPath) {
+        agentCommand = resolvedPath;
+      }
+      // If not found, keep original command - error will be clearer from spawn
+    }
+    
+    return new Promise((resolve, reject) => {
+      let output = '';
+      const args = this.buildArgs(prompt, useStreaming);
+      
+      if (model) {
+        args.push('--model', model);
+      }
+
+      const env = { ...process.env };
+      
+      const agent = spawn(agentCommand, args, {
+        cwd,
+        env,
+        stdio: ['inherit', 'pipe', 'inherit'], // Let stderr pass through for typewriter effect
+        shell: false,
+        detached: false,
+      });
+
+      const timeout = setTimeout(() => {
+        console.log(`\n⏱️  Timeout reached (${timeoutMs / 1000}s) - killing agent...`);
+        agent.kill('SIGTERM');
+        // Force kill if still running after 2 seconds
+        setTimeout(() => {
+          if (!agent.killed) {
+            console.log('⚠️  Forcing kill (SIGKILL)...');
+            agent.kill('SIGKILL');
+          }
+        }, 2000);
+        reject(new Error(`Agent timed out after ${timeoutMs / 1000}s. The agent may be stuck or waiting for user input.`));
+      }, timeoutMs);
+
+      let lastOutputLength = 0;
+      let lastOutputTime = Date.now();
+      const heartbeat = setInterval(() => {
+        if (output.length > lastOutputLength) {
+          // Output is coming in, no need to show heartbeat
+          lastOutputLength = output.length;
+          lastOutputTime = Date.now();
+        } else {
+          // Only show "thinking" message if no output for 10 seconds
+          const timeSinceLastOutput = Date.now() - lastOutputTime;
+          if (timeSinceLastOutput > 10000) {
+            console.log(`⏳ AI agent is thinking... (${Math.floor(timeSinceLastOutput / 1000)}s, ${output.length} bytes so far)`);
+          }
+        }
+      }, 10000);
+
+      // Handle Ctrl+C gracefully
+      const cleanup = () => {
+        clearTimeout(timeout);
+        clearInterval(heartbeat);
+        if (agent && !agent.killed) {
+          agent.kill('SIGTERM');
+          // Force kill if not dead after 2 seconds
+          setTimeout(() => {
+            if (!agent.killed) {
+              agent.kill('SIGKILL');
+            }
+          }, 2000);
+        }
+      };
+
+      const sigintHandler = () => {
+        console.log('\n\n🛑 Interrupted by user (Ctrl+C)');
+        cleanup();
+        // Don't reset terminal - it's too aggressive
+        reject(new Error('Interrupted by user'));
+      };
+
+      process.on('SIGINT', sigintHandler);
+
+      // Use StreamingParser for clean, reliable parsing
+      const parser = new StreamingParser();
+      
+      // Handle stdout - cursor-agent outputs NDJSON protocol messages
+      agent.stdout.on('data', (data) => {
+        const chunk = data.toString();
+        output += chunk; // Accumulate raw output
+        
+        const displayText = parser.processChunk(chunk);
+        
+        if (displayText) {
+          // Write the extracted text immediately (no buffering)
+          // This creates the typewriter effect as cursor-agent streams
+          process.stdout.write(displayText, 'utf8', () => {
+            // Flush immediately after write
+            if (process.stdout.isTTY) {
+              process.stdout._flush && process.stdout._flush();
+            }
+          });
+          lastOutputTime = Date.now();
+          lastOutputLength += displayText.length;
+        }
+      });
+      
+      agent.on('close', (code) => {
+        process.off('SIGINT', sigintHandler);
+        clearTimeout(timeout);
+        clearInterval(heartbeat);
+        
+        // Flush any remaining buffer
+        const remainingText = parser.flush();
+        if (remainingText) {
+          process.stdout.write(remainingText);
+        }
+        
+        // Get the complete output (for JSON extraction, includes protocol)
+        output = parser.getRawText();
+        
+        // Also store the extracted result for direct access
+        const extractedResult = parser.getResult();
+        
+        if (code === 0) {
+          // Return both raw output and extracted result
+          resolve({ raw: output, extracted: extractedResult });
+        } else {
+          reject(new Error(`Agent exited with code ${code}`));
+        }
+      });
+      
+      agent.on('error', (error) => {
+        process.off('SIGINT', sigintHandler);
+        clearTimeout(timeout);
+        clearInterval(heartbeat);
+        reject(new Error(`Failed to spawn agent: ${error.message}`));
+      });
+    });
+  }
+
+  /**
+   * Run a single node (for testing/debugging)
+   * This is a framework feature, not part of workflow definition
+   */
+  async runSingleNode(nodeName, nodeMap, initialState) {
+    const nodeConfig = nodeMap[nodeName];
+    if (!nodeConfig) {
+      throw new Error(`Unknown node: ${nodeName}. Available nodes: ${Object.keys(nodeMap).join(', ')}`);
+    }
+
+    const { cwd } = initialState;
+    if (!cwd) {
+      throw new Error('cwd is required for single node execution');
+    }
+    
+    // Reuse existing session if provided (--session flag), otherwise create new
+    let sessionPath = initialState.sessionPath;
+    let sessionTimestamp = initialState.sessionTimestamp;
+    const config = initialState.config || {};
+    
+    if (!sessionPath) {
+      // Generate CI-aware session ID
+      const ciSessionId = process.env.CI_JOB_ID || 
+                         process.env.GITHUB_RUN_ID || 
+                         process.env.CIRCLE_WORKFLOW_ID ||
+                         process.env.BUILD_ID;
+      
+      const baseId = ciSessionId || Date.now().toString();
+      const prefix = config.paths?.sessionPrefix;
+      const sessionId = prefix ? `${prefix}_${baseId}` : baseId;
+      
+      sessionTimestamp = sessionTimestamp || Date.now();
+      
+      // Use configurable output path
+      const outputBase = config.paths?.output || DEFAULT_OUTPUT_BASE;
+      sessionPath = join(cwd, outputBase, SESSIONS_DIR, sessionId);
+      
+      if (!existsSync(sessionPath)) {
+        mkdirSync(sessionPath, { recursive: true });
+      }
+    }
+    
+    // Write session info to output directory
+    const outputBase = config.paths?.output || DEFAULT_OUTPUT_BASE;
+    const sessionInfoPath = join(cwd, outputBase, SESSION_INFO_FILE);
+    mkdirSync(join(cwd, outputBase), { recursive: true });
+    writeFileSync(sessionInfoPath, JSON.stringify({ 
+      sessionPath, 
+      sessionTimestamp: sessionTimestamp || sessionPath.split('/').pop(), 
+      currentNode: nodeName,
+      createdAt: new Date().toISOString() 
+    }), 'utf-8');
+
+    console.log(`\n${'='.repeat(80)}`);
+    console.log(`🎯 SINGLE NODE EXECUTION: ${nodeName}`);
+    console.log(`📁 Session: ${sessionPath.split('/').pop()}${initialState.sessionPath ? ' (reusing)' : ''}`);
+    console.log(`${'='.repeat(80)}\n`);
+
+    const context = await ContextLoader.loadContext(
+      initialState.specPath || '',
+      cwd,
+      initialState.contextConfig || {}
+    );
+
+    // Use Node class for consistent behavior with workflow execution
+    const { Node } = await import('../framework/node.js');
+    const { WorkflowState } = await import('../framework/state.js');
+    
+    const state = new WorkflowState({
+      ...initialState,
+      sessionPath,
+      sessionTimestamp,
+      context
+    });
+    
+    const node = new Node(nodeConfig);
+    const result = await node.execute(this, state);
+    
+    console.log(`\n${'='.repeat(80)}`);
+    console.log(`✅ Node ${nodeName} completed`);
+    console.log(`${'='.repeat(80)}\n`);
+
+    return { success: true, output: result.output, outputPath: initialState.outputPath, state: result };
+  }
+
+  calculateOutputPath(specPath) {
+    const { specs, generated } = this.paths;
+    if (!specPath) return `${generated}/generated-test.spec.js`;
+    
+    const relativePath = specPath.replace(new RegExp(`^${specs}/`), '').replace(/\.[^.]+$/, '.spec.js');
+    return `${generated}/${relativePath}`.replace(/\/+/g, '/');
+  }
+}
+
+/**
+ * Functional workflow factory — no class boilerplate needed.
+ *
+ *   const agent = workflow((graph) => {
+ *     graph.addNode('plan',    { prompt: ..., outputSchema: ... });
+ *     graph.addNode('execute', { skills: ['calculator'], prompt: ... });
+ *     graph.setEntryPoint('plan');
+ *     graph.addEdge('plan', 'execute');
+ *     graph.addEdge('execute', 'END');
+ *   });
+ *
+ *   await agent.run("What is 15 plus 27?");
+ */
+export function workflow(builder, options = {}) {
+  const agent = new WorkflowAgent(options);
+  agent.buildGraph = function () {
+    const graph = new WorkflowGraph();
+    builder(graph);
+    return graph;
+  };
+  if (options.onComplete) {
+    agent.onComplete = options.onComplete;
+  }
+  return agent;
+}
+

package/src/constants.js

@@ -0,0 +1,47 @@
+/**
+ * Zibby Framework Constants
+ * Single source of truth for all configuration values
+ */
+
+export const DEFAULT_MODELS = {
+  CLAUDE: 'claude-sonnet-4-6',
+  CURSOR: 'auto',
+  OPENAI_POSTPROCESSING: 'gpt-4o-mini'
+};
+
+export const AGENT_TYPES = {
+  CLAUDE: 'claude',
+  CURSOR: 'cursor'
+};
+
+export const LOG_LEVELS = {
+  DEBUG: 'debug',
+  INFO: 'info',
+  WARN: 'warn',
+  ERROR: 'error',
+  SILENT: 'silent'
+};
+
+export const CLAUDE_MODEL_MAP = {
+  'auto': 'claude-sonnet-4-6',
+  // 4.6 aliases
+  'sonnet-4.6': 'claude-sonnet-4-6',
+  'sonnet-4-6': 'claude-sonnet-4-6',
+  'opus-4.6': 'claude-opus-4-6',
+  'opus-4-6': 'claude-opus-4-6',
+  // 4.5 aliases
+  'sonnet-4.5': 'claude-sonnet-4-5-20250929',
+  'sonnet-4-5': 'claude-sonnet-4-5-20250929',
+  'opus-4.5': 'claude-opus-4-20250514',
+  'opus-4-5': 'claude-opus-4-20250514',
+  // Direct API IDs (pass-through)
+  'claude-sonnet-4-6': 'claude-sonnet-4-6',
+  'claude-opus-4-6': 'claude-opus-4-6',
+  'claude-sonnet-4-5-20250929': 'claude-sonnet-4-5-20250929',
+  'claude-opus-4-20250514': 'claude-opus-4-20250514',
+};
+
+export const TIMEOUTS = {
+  CURSOR_AGENT_DEFAULT: 20 * 60 * 1000,
+  OPENAI_REQUEST: 30000
+};