@mudlab/create-workflow 1.0.0

package/template/README.md

@@ -0,0 +1,49 @@
+# My Mudlab Workflows
+
+Automated workflows powered by [Mudlab](https://mudlab.io).
+
+## Setup
+
+1. Copy `.env.example` to `.env` and add your API keys:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` with your Mudlab API key and any integration keys you need.
+
+## Creating Workflows
+
+1. **Add a tool** in `execution/tools/my_tool.js`
+2. **Add a workflow** in `execution/workflows/my_workflow.json`
+3. **Add a directive** in `directives/my_workflow.md`
+
+See `CLAUDE.md` for detailed documentation on the 3-layer architecture.
+
+## Push to Mudlab
+
+```bash
+# Single workflow
+node execution/push_workflow.js execution/workflows/my_workflow.json
+
+# All workflows
+npm run push:all
+```
+
+## Directory Structure
+
+```
+├── CLAUDE.md                    # AI orchestrator instructions
+├── directives/                  # Workflow documentation (SOPs)
+├── execution/
+│   ├── push_workflow.js         # Push script
+│   ├── tools/                   # Node.js tool functions
+│   ├── tools_directives/        # AI usage instructions
+│   └── workflows/               # Workflow packages (JSON)
+├── assets/                      # Static assets
+└── .tmp/                        # Temp files (gitignored)
+```
+
+## Learn More
+
+- [Mudlab Documentation](https://mudlab.io/docs)
+- See `CLAUDE.md` for the complete 3-layer architecture guide

package/template/assets/.gitkeep

@@ -0,0 +1,3 @@
+# Assets
+
+Place static assets here (logos, templates, etc.)

package/template/directives/.gitkeep

@@ -0,0 +1,12 @@
+# Workflow Directives
+
+Place your workflow directive markdown files here.
+
+Each workflow needs a directive file that documents:
+- What the workflow does
+- Workflow scope (what it IS and IS NOT for)
+- Trigger format (webhook URL and payload)
+- Input/output specifications
+- Example usage
+
+See CLAUDE.md for the full directive structure template.

package/template/execution/push_workflow.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+
+/**
+ * Push Workflow to Mudlab
+ *
+ * Takes one or more workflow packages (tools + workflow definition) and pushes
+ * everything to the Mudlab API. Automatically handles create vs update
+ * based on existing IDs, and writes returned IDs back to the JSON files.
+ *
+ * Usage:
+ *   Single:  node execution/push_workflow.js execution/workflows/my_workflow.json
+ *   Bulk:    node execution/push_workflow.js execution/workflows/*.json
+ *
+ * When multiple files are provided, they are pushed in a single bulk API call
+ * for better performance.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Load environment variables from .env
+function loadEnv() {
+  const envPath = path.join(process.cwd(), '.env');
+  if (fs.existsSync(envPath)) {
+    const envContent = fs.readFileSync(envPath, 'utf-8');
+    for (const line of envContent.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#')) {
+        const [key, ...valueParts] = trimmed.split('=');
+        const value = valueParts.join('=').replace(/^["']|["']$/g, '');
+        process.env[key] = value;
+      }
+    }
+  }
+}
+
+loadEnv();
+
+const MUDLAB_API_URL = process.env.MUDLAB_API_URL || 'http://localhost:3000';
+const MUDLAB_API_KEY = process.env.MUDLAB_API_KEY;
+
+function getHeaders() {
+  return {
+    'Content-Type': 'application/json',
+    ...(MUDLAB_API_KEY && { 'X-API-Key': MUDLAB_API_KEY })
+  };
+}
+
+
+/**
+ * Write IDs back to the workflow JSON file
+ */
+function updateWorkflowFile(workflowPath, workflowId, toolIds) {
+  const workflowPackage = JSON.parse(fs.readFileSync(workflowPath, 'utf-8'));
+
+  // Update workflow ID
+  workflowPackage.id = workflowId;
+
+  // Update tool IDs
+  for (const tool of workflowPackage.tools) {
+    if (toolIds[tool.tool_id]) {
+      tool.id = toolIds[tool.tool_id];
+    }
+  }
+
+  fs.writeFileSync(workflowPath, JSON.stringify(workflowPackage, null, 2) + '\n');
+}
+
+function savePushLog(workflowResult, toolResults) {
+  const tmpDir = path.join(process.cwd(), '.tmp');
+  if (!fs.existsSync(tmpDir)) {
+    fs.mkdirSync(tmpDir, { recursive: true });
+  }
+
+  const logPath = path.join(tmpDir, 'pushed_workflows.json');
+  let log = [];
+  if (fs.existsSync(logPath)) {
+    log = JSON.parse(fs.readFileSync(logPath, 'utf-8'));
+  }
+
+  log.push({
+    pushed_at: new Date().toISOString(),
+    workflow: workflowResult,
+    tools: toolResults
+  });
+
+  fs.writeFileSync(logPath, JSON.stringify(log, null, 2));
+}
+
+/**
+ * Prepare a single workflow payload from package and directive
+ */
+function prepareWorkflowPayload(workflowPackage, directivePath) {
+  // Read directive
+  const directive = fs.readFileSync(directivePath, 'utf-8');
+
+  // Prepare tools with code and directives loaded from files
+  const tools = workflowPackage.tools.map(tool => {
+    let code = tool.code;
+    if (tool.code_file) {
+      const codePath = path.join(process.cwd(), tool.code_file);
+      if (!fs.existsSync(codePath)) {
+        throw new Error(`Tool code file not found: ${tool.code_file}`);
+      }
+      code = fs.readFileSync(codePath, 'utf-8');
+    }
+
+    // Read tool directive from file if specified
+    let toolDirective = tool.directive || null;
+    if (tool.directive_file) {
+      const toolDirectivePath = path.join(process.cwd(), tool.directive_file);
+      if (fs.existsSync(toolDirectivePath)) {
+        toolDirective = fs.readFileSync(toolDirectivePath, 'utf-8');
+        console.log(`   📝 Loaded directive for ${tool.tool_id} (${toolDirective.length} chars)`);
+      } else {
+        console.log(`   ⚠️  Directive file not found: ${tool.directive_file}`);
+      }
+    }
+
+    return {
+      id: tool.id || null,
+      tool_id: tool.tool_id,
+      name: tool.name,
+      description: tool.description,
+      directive: toolDirective,
+      running_message: tool.running_message,
+      code: code,
+      inputs: tool.inputs,
+      outputs: tool.outputs
+    };
+  });
+
+  // Debug: show tools with directives
+  for (const tool of tools) {
+    if (tool.directive) {
+      console.log(`   📤 Sending directive for ${tool.tool_id}: "${tool.directive.substring(0, 50)}..."`);
+    }
+  }
+
+  return {
+    id: workflowPackage.id || null,
+    name: workflowPackage.name,
+    description: workflowPackage.description,
+    directive: directive,
+    running_message: workflowPackage.running_message,
+    success_message: workflowPackage.success_message,
+    client_id: workflowPackage.client_id,
+    steps: workflowPackage.steps,
+    tools: tools
+  };
+}
+
+/**
+ * Push workflow(s) to the API
+ * @param {Array|Object} payloads - Single payload or array of payloads
+ * @returns {Object} API response (normalized)
+ *
+ * Bulk response format:
+ * {
+ *   success: boolean,        // true only if ALL succeeded
+ *   results: [...],          // all results (success and failure)
+ *   summary: { total, succeeded, failed },
+ *   workflows: [...],        // convenience: only successes
+ *   errors: [{ workflow_name, error, details }, ...]  // convenience: only failures
+ * }
+ */
+async function pushToApi(payloads) {
+  const isBulk = Array.isArray(payloads) && payloads.length > 1;
+  const body = isBulk ? payloads : (Array.isArray(payloads) ? payloads[0] : payloads);
+
+  const response = await fetch(`${MUDLAB_API_URL}/api/push-workflow`, {
+    method: 'POST',
+    headers: getHeaders(),
+    body: JSON.stringify(body)
+  });
+
+  // Handle different status codes
+  // 200 = all succeeded, 207 = partial success, 400/500 = error
+  if (!response.ok && response.status !== 207) {
+    const error = await response.text();
+    throw new Error(`Push failed (${response.status}): ${error}`);
+  }
+
+  const result = await response.json();
+
+  // Normalize response format
+  // Single: { success, workflow, tools }
+  // Bulk: { success, results, summary, workflows, errors }
+  if (isBulk) {
+    return { isBulk: true, ...result };
+  } else {
+    // Normalize single response to match bulk format
+    return {
+      isBulk: false,
+      results: [result],
+      summary: { total: 1, succeeded: result.success ? 1 : 0, failed: result.success ? 0 : 1 },
+      workflows: result.success ? [result] : [],
+      errors: result.success ? [] : [{ workflow_name: result.workflow?.name || 'Unknown', error: result.error, details: result.details }]
+    };
+  }
+}
+
+/**
+ * Process a single workflow result and update its JSON file
+ */
+function processWorkflowResult(result, workflowPath, workflowPackage) {
+  const workflowData = result.workflow;
+  // Tools are now nested inside workflow object
+  const toolResults = workflowData.tools || [];
+  const toolIdMap = {};
+
+  // Log tool results
+  console.log('🔧 Tools:\n');
+  for (const tool of toolResults) {
+    toolIdMap[tool.tool_id] = tool.id;
+    const action = tool.created ? 'Created' : 'Updated';
+    const toolDef = workflowPackage.tools.find(t => t.tool_id === tool.tool_id);
+    const toolName = tool.name || toolDef?.name || tool.tool_id;
+    const hasDirective = toolDef?.directive_file ? ' [has directive]' : '';
+    console.log(`   ✓ ${toolName} (${action})${hasDirective}`);
+    console.log(`     ID: ${tool.id}`);
+    console.log(`     Version: ${tool.version}\n`);
+  }
+
+  // Log workflow result
+  const workflowAction = workflowData.created ? 'Created' : 'Updated';
+  console.log(`📋 Workflow: ${workflowPackage.name} (${workflowAction})`);
+  console.log(`   ID: ${workflowData.id}`);
+  console.log(`   Status: ${workflowData.status}`);
+  console.log(`   Steps: ${workflowData.steps_count || workflowPackage.steps.length}\n`);
+
+  // Write IDs back to the JSON file
+  console.log('💾 Updating workflow file with IDs...');
+  updateWorkflowFile(workflowPath, workflowData.id, toolIdMap);
+  console.log(`   ✓ ${workflowPath}\n`);
+
+  // Save push log
+  savePushLog(workflowData, toolResults);
+
+  return { workflowData, toolIdMap };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node push_workflow.js <workflow-package.json> [workflow2.json ...]');
+    console.error('       node push_workflow.js execution/workflows/*.json');
+    process.exit(1);
+  }
+
+  // Validate all files exist first
+  const workflowPaths = [];
+  for (const arg of args) {
+    if (!fs.existsSync(arg)) {
+      console.error(`Workflow package not found: ${arg}`);
+      process.exit(1);
+    }
+    workflowPaths.push(arg);
+  }
+
+  if (!MUDLAB_API_KEY) {
+    console.warn('Warning: MUDLAB_API_KEY not set. API calls may fail.');
+  }
+
+  const isBulk = workflowPaths.length > 1;
+
+  if (isBulk) {
+    console.log(`\n📦 Pushing ${workflowPaths.length} workflow packages (bulk mode)`);
+  } else {
+    console.log(`\n📦 Pushing workflow package: ${workflowPaths[0]}`);
+  }
+  console.log(`   API: ${MUDLAB_API_URL}\n`);
+
+  // Prepare all payloads
+  const payloads = [];
+  const workflowPackages = [];
+
+  for (const workflowPath of workflowPaths) {
+    console.log(`📄 Preparing: ${workflowPath}`);
+    const workflowPackage = JSON.parse(fs.readFileSync(workflowPath, 'utf-8'));
+    workflowPackages.push(workflowPackage);
+
+    // Validate directive file exists
+    if (!workflowPackage.directive_file) {
+      console.error(`   Missing required field: directive_file in ${workflowPath}`);
+      process.exit(1);
+    }
+
+    const directivePath = path.join(process.cwd(), workflowPackage.directive_file);
+    if (!fs.existsSync(directivePath)) {
+      console.error(`   Directive file not found: ${workflowPackage.directive_file}`);
+      process.exit(1);
+    }
+
+    console.log(`   Directive: ${workflowPackage.directive_file}`);
+    const payload = prepareWorkflowPayload(workflowPackage, directivePath);
+    payloads.push(payload);
+  }
+
+  console.log('\n🔗 Pushing workflow(s) and tools...\n');
+
+  try {
+    const response = await pushToApi(payloads);
+    const { results, summary, errors } = response;
+
+    // Process each result
+    const allToolIds = {};
+    const allWorkflowIds = [];
+
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      const workflowPath = workflowPaths[i];
+      const workflowPackage = workflowPackages[i];
+
+      if (isBulk) {
+        console.log('─'.repeat(50));
+        console.log(`\n[${i + 1}/${results.length}] ${workflowPackage.name}\n`);
+      }
+
+      if (!result.success) {
+        console.error(`   ✗ Failed: ${result.error || 'Unknown error'}`);
+        if (result.details) {
+          console.error(`     Details: ${result.details}`);
+        }
+        continue;
+      }
+
+      const { workflowData, toolIdMap } = processWorkflowResult(result, workflowPath, workflowPackage);
+      Object.assign(allToolIds, toolIdMap);
+      allWorkflowIds.push({ name: workflowPackage.name, id: workflowData.id });
+    }
+
+    // Summary
+    console.log('─'.repeat(50));
+
+    if (isBulk) {
+      console.log(`\n📊 Bulk Push Summary:`);
+      console.log(`   Total: ${summary.total}`);
+      console.log(`   Succeeded: ${summary.succeeded}`);
+      console.log(`   Failed: ${summary.failed}`);
+
+      if (summary.failed > 0 && errors && errors.length > 0) {
+        console.log(`\n❌ Failed Workflows:\n`);
+        for (const err of errors) {
+          console.log(`   ${err.workflow_name}:`);
+          console.log(`     Error: ${err.error}`);
+          if (err.details) {
+            console.log(`     Details: ${err.details}`);
+          }
+        }
+        console.log('');
+      } else if (summary.failed === 0) {
+        console.log(`\n✅ All workflows pushed successfully!\n`);
+      }
+
+      if (allWorkflowIds.length > 0) {
+        console.log('Workflow UUIDs:');
+        for (const { name, id } of allWorkflowIds) {
+          console.log(`   ${name}: ${id}`);
+        }
+      }
+    } else {
+      if (summary.failed > 0) {
+        console.log('\n❌ Workflow push failed.\n');
+      } else {
+        console.log('\n✅ Workflow pushed successfully!\n');
+        console.log('Tool UUIDs:');
+        for (const [toolId, uuid] of Object.entries(allToolIds)) {
+          console.log(`   ${toolId}: ${uuid}`);
+        }
+        const workflowId = allWorkflowIds[0]?.id;
+        console.log(`\nWorkflow UUID: ${workflowId}`);
+        console.log(`\nTo run this workflow:`);
+        console.log(`   POST ${MUDLAB_API_URL}/api/run`);
+        console.log(`   Body: { "workflow_id": "${workflowId}", "input": { ... } }`);
+      }
+    }
+
+    console.log(`\nPush log saved to: .tmp/pushed_workflows.json\n`);
+
+    // Exit with error if any failed
+    if (summary.failed > 0) {
+      process.exit(1);
+    }
+
+  } catch (error) {
+    console.error(`   ✗ Push failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error('Fatal error:', error.message);
+  process.exit(1);
+});

package/template/execution/tools/.gitkeep

@@ -0,0 +1,18 @@
+# Tools
+
+Place your Node.js tool files here.
+
+Each tool is a module that exports a `run` function:
+
+```javascript
+async function run({ input, env, context }) {
+  // Your logic here
+  return {
+    action: "completed",
+    message: "Human-readable success message",
+    // ... other output fields
+  };
+}
+
+module.exports = { run };
+```

package/template/execution/tools_directives/.gitkeep

@@ -0,0 +1,12 @@
+# Tool Directives
+
+Place your tool directive markdown files here.
+
+Each tool directive provides AI usage instructions:
+- Input constraints and validation rules
+- Output details
+- Formatting requirements
+- Best practices
+- Common mistakes to avoid
+
+These are injected into the AI's context when the tool is used.

package/template/execution/workflows/.gitkeep

@@ -0,0 +1,10 @@
+# Workflow Packages
+
+Place your workflow JSON package files here.
+
+Each workflow package defines:
+- Workflow metadata (name, description, messages)
+- Tools used by the workflow
+- Steps that execute the tools in order
+
+Run `node execution/push_workflow.js execution/workflows/your_workflow.json` to push.

package/template/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "my-mudlab-workflows",
+  "version": "1.0.0",
+  "description": "Mudlab workflow automation project",
+  "scripts": {
+    "push": "node execution/push_workflow.js",
+    "push:all": "node execution/push_workflow.js execution/workflows/*.json"
+  },
+  "keywords": ["mudlab", "workflow", "automation"],
+  "license": "MIT",
+  "dependencies": {}
+}