@ha-bits/cortex 1.1.0 → 1.1.8

package/README.md

@@ -1,6 +1,6 @@
 # @ha-bits/cortex
 
-Cortex - Habits Workflow Executor CLI
+Cortex - Habits Workflow Executor Server and CLI
 
 ## Installation
 
@@ -12,61 +12,98 @@ npx @ha-bits/cortex
 
 ## Usage
 
-Run the CLI:
-
 ```bash
-cortex [command] [options]
+npx cortex <command> [options]
 # or
-npx @ha-bits/cortex [command] [options]
+npx @ha-bits/cortex <command> [options]
 ```
 
-### Local Development
+### Commands
+
+#### Start Server
 
-To run the Cortex server locally during development:
+Start the workflow execution server:
 
 ```bash
-pnpm nx dev @ha-bits/cortex --config ./packages/cortex/server/examples/business-intersect-standalone/config.json
+npx cortex server --config ./stack.yaml
+npx cortex server -c ./config.json -p 8080
 ```
 
-This starts the server with the specified example workflow.
+Options:
+- `--config, -c` - Path to config file (looks for config.json in cwd if not specified)
+- `--port, -p` - Server port (priority: args > config.json > .env > 3000)
+- `--host, -h` - Server host (default: 0.0.0.0)
+
+#### Execute Workflow
+
+Execute a workflow directly without starting a server:
+
+```bash
+# Execute from workflow file
+cortex execute ./workflow.json
+
+# Execute by ID from config
+cortex execute --config ./stack.yaml --id my-workflow
+
+# Execute all workflows
+cortex execute --config ./stack.yaml --all
 
-### Available Commands
+# Execute with input data
+cortex execute --config ./stack.yaml --id my-workflow --input '{"prompt": "Hello"}'
+```
 
-- `server` - Start the Cortex server
-- `--config` - Specify a config file path
+#### Convert Workflow
 
-### Example
+Convert n8n, Activepieces, or Script workflows to Habits format:
 
 ```bash
-# Start server with config
-cortex server --config ./config.json
+cortex convert --input ./n8n-workflow.json --output ./habits.yaml
+cortex convert -i ./workflow.json -o ./habits.yaml --env  # Generate .env template
+```
 
-# Or with npx
-npx @ha-bits/cortex server --config ./config.json
+### Local Development
+
+```bash
+pnpm nx dev @ha-bits/cortex --config examples/mixed/stack.yaml
 ```
 
-## Configuration
+## API Endpoints
 
-The CLI requires a configuration file. See the documentation for configuration options.
+### Workflow Management
+- `GET /misc/workflows` - List all loaded workflows
+- `GET /misc/workflow/:workflowId` - Get workflow details
+
+### Workflow Execution
+- `POST /api/:workflowId` - Execute a workflow
+  - Query params: `?stream=true` for streaming response (NDJSON)
+- `GET /misc/execution/:id` - Get execution status
+- `GET /misc/executions` - List all executions
+- `DELETE /misc/execution/:id` - Cancel execution
+
+### Webhooks
+- `GET /webhook/health` - Webhook subsystem health
+- `GET /webhook/list` - List registered webhook endpoints
+- `ALL /webhook/:workflowId/:nodeId` - Webhook trigger endpoints
+
+### Health
+- `GET /health` - Server health check
+- `GET /misc/health` - Alternative health endpoint
 
 ## Technical Notes
 
 ### Dynamic Module Loading
 
-Cortex uses `createRequire` from Node.js's `module` API instead of the standard `require()` for loading modules at runtime. This is necessary because:
+Cortex uses `createRequire` from Node.js's `module` API instead of standard `require()` for loading modules at runtime. This is necessary because:
 
-1. **Bundler Compatibility**: When the code is bundled with esbuild/webpack then ncc, the bundler transforms `require()` calls and creates a static context that can't resolve paths determined at runtime.
+1. **Bundler Compatibility**: When bundled with esbuild/webpack/ncc, the bundler transforms `require()` calls and creates a static context that can't resolve runtime paths.
 
-2. **Dynamic Path Resolution**: Activepieces modules are downloaded to `/tmp/habits-nodes/` or wherever the env points to at runtime (HABITS_NODES_PATH) and their paths aren't known at build time. Using `createRequire(__filename)` creates a fresh require function that bypasses the bundler's static analysis.
+2. **Dynamic Path Resolution**: Modules are downloaded to `/tmp/habits-nodes/` (or `HABITS_NODES_PATH`) at runtime, and their paths aren't known at build time.
 
-3. **Production Environment**: In production (`/app/dist/pack/index.cjs`), the bundled code would throw "Cannot find module" errors with regular `require()` because webpack's `webpackEmptyContext` can't resolve dynamic paths.
+3. **Production Environment**: In bundled production code, regular `require()` would throw "Cannot find module" errors.
 
 ```typescript
 // Instead of: require(dynamicPath)  // ❌ Fails in bundled code
-// We use:
-customRequire(__filename, dynamicPath)
-
-//OR 
+// Use:
 import { createRequire } from 'module';
 const dynamicRequire = createRequire(__filename);
 const loadedModule = dynamicRequire(dynamicPath);  // ✅ Works in bundled code