@vertesia/create-worker 0.81.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2024 Composable
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,243 @@
+# @vertesia/create-worker
+
+This package scaffolds a Vertesia custom Temporal worker project.
+Custom workers allow you to deploy your own Temporal workflows and activities to the Vertesia cloud platform.
+
+Visit https://vertesiahq.com for more information about Vertesia.
+
+## Requirements
+
+1. Docker (with buildx support) installed locally.
+2. Vertesia CLI application. The CLI will be automatically installed when initializing the worker project if you didn't install it previously.
+
+## Initialize a Vertesia worker project
+
+Run the following command:
+
+```bash
+npm init @vertesia/worker
+```
+
+Follow the instructions on screen. You need to define an organization and a name for your worker. The organization must be unique inside Vertesia and is usually the name of your Vertesia organization account. The worker name identifies the project within your organization.
+
+The generated project is a TypeScript project using [Temporal](https://temporal.io/) as the workflow system.
+
+## Project Structure
+
+The generated project includes:
+
+```
+├── src/
+│   ├── activities.ts      # Activity implementations (API calls, I/O operations)
+│   ├── workflows.ts       # Workflow definitions (orchestration logic)
+│   ├── main.ts            # Worker entry point
+│   ├── debug-replayer.ts  # Debugging tool for workflow replay
+│   ├── activities.test.ts # Unit tests for activities
+│   └── test/
+│       └── utils.ts       # Test utilities
+├── bin/
+│   └── bundle-workflows.mjs # Workflow bundler script
+├── vitest.config.ts       # Test configuration
+├── tsconfig.json          # TypeScript configuration
+├── tsconfig.test.json     # TypeScript configuration for tests
+├── Dockerfile             # Container build configuration
+└── package.json           # Project configuration
+```
+
+## Development
+
+### Building
+
+```bash
+pnpm install
+pnpm run build
+```
+
+The build process:
+
+1. Compiles TypeScript to JavaScript
+2. Bundles workflows into a single file (required by Temporal)
+
+### Testing
+
+The project uses Vitest with Temporal's `MockActivityEnvironment` for testing activities.
+
+```bash
+pnpm test
+```
+
+Tests are located in `*.test.ts` files alongside the source code.
+
+### Developing workflows and activities
+
+**Activities** (`src/activities.ts`):
+
+- Activities are functions that perform I/O operations (API calls, file access, etc.)
+- They run outside the Temporal workflow sandbox
+- Use `getVertesiaClient(payload)` to get an authenticated Vertesia client
+- Activities can be retried automatically on failure
+
+**Workflows** (`src/workflows.ts`):
+
+- Workflows orchestrate activities and define the business logic
+- They must be deterministic (no direct I/O, random, or time operations)
+- Use `proxyActivities` to call activities from workflows
+- Workflows receive `WorkflowExecutionPayload` with `objectIds` and `vars`
+
+Export your workflows and activities from these files to make them available to the worker.
+
+## Run with a local Temporal server
+
+Running with a local Temporal server is useful for integration testing before deployment.
+
+### 1. Install and start Temporal
+
+Install the [Temporal CLI](https://docs.temporal.io/cli), then start the dev server:
+
+```bash
+temporal server start-dev
+```
+
+### 2. Start the worker
+
+In another terminal:
+
+```bash
+pnpm run start
+```
+
+### 3. Execute a workflow
+
+Using the Temporal CLI:
+
+```bash
+temporal workflow start --name exampleWorkflow -t agents/your-org/your-worker --input-file INPUT.json
+```
+
+Where `INPUT.json` contains the workflow parameters:
+
+```json
+{
+  "objectIds": ["content-object-id"],
+  "event": "workflow_execution_request",
+  "auth_token": "your-auth-token",
+  "account_id": "your-account-id",
+  "project_id": "your-project-id",
+  "config": {
+    "store_url": "https://zeno-server.api.vertesia.io",
+    "studio_url": "https://studio-server.api.vertesia.io"
+  },
+  "vars": {
+    "dryRun": true
+  }
+}
+```
+
+## Debugging workflows
+
+You can debug workflows by replaying them locally using the Temporal replayer in `src/debug-replayer.ts`.
+
+See https://docs.temporal.io/develop/typescript/debugging for more information.
+
+## Configuration
+
+Worker configuration is defined in `package.json` under the `vertesia` section:
+
+```json
+{
+  "vertesia": {
+    "pm": "pnpm",
+    "image": {
+      "repository": "us-docker.pkg.dev/dengenlabs/us.gcr.io",
+      "organization": "your-org",
+      "name": "your-worker"
+    }
+  }
+}
+```
+
+The worker domain (task queue) is automatically constructed as: `agents/{organization}/{name}`
+
+## Deployment
+
+### Build the Docker image
+
+```bash
+vertesia worker build
+```
+
+This builds a Docker image tagged as `your-organization/your-worker:latest`.
+This image is only for local testing.
+
+### Create a release version
+
+```bash
+vertesia worker release <version>
+```
+
+The version must be in `major.minor.patch[-modifier]` format (e.g., `1.0.0`, `1.0.0-rc1`).
+
+This creates a new Docker tag `your-organization/your-worker:version` from the `latest` image.
+
+### Publish to Vertesia
+
+```bash
+vertesia worker publish <version>
+```
+
+This pushes the image to Vertesia and deploys the worker.
+
+Options:
+
+- `--push-only`: Only push the image without deploying
+- `--deploy-only`: Deploy a previously uploaded version
+
+### View versions
+
+```bash
+vertesia worker versions
+```
+
+## Running deployed workflows
+
+Once deployed, workflows can be triggered via:
+
+**SDK:**
+
+```javascript
+const run = await client.workflows.execute("exampleWorkflow", {
+  task_queue: "agents/your-org/your-worker",
+  objectIds: ["content-object-id"],
+  vars: {
+    dryRun: false,
+  },
+});
+```
+
+**CLI:**
+
+```bash
+vertesia workflows execute exampleWorkflow -o <OBJECT_ID> --queue "agents/your-org/your-worker" -f vars.json
+```
+
+**API:**
+
+```bash
+curl --location 'https://api.vertesia.io/api/v1/workflows/execute/exampleWorkflow' \
+--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
+--header 'Content-Type: application/json' \
+--data '{
+  "vars": { "dryRun": false },
+  "task_queue": "agents/your-org/your-worker",
+  "objectIds": ["content-object-id"]
+}'
+```
+
+## Dependencies
+
+Built with:
+
+- **Temporal**: Workflow orchestration
+- **Vertesia SDK**: Platform integration
+- **TypeScript**: Type-safe development
+- **Vitest**: Testing framework

package/bin/create-worker.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../lib/main.js"

package/lib/main.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * @vertesia/create-worker
+ *
+ * This package has been deprecated in favor of @vertesia/create-plugin.
+ * It now acts as a thin wrapper that redirects to create-plugin with the worker template pre-selected.
+ */
+export {};
+//# sourceMappingURL=main.d.ts.map

package/lib/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}

package/lib/main.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * @vertesia/create-worker
+ *
+ * This package has been deprecated in favor of @vertesia/create-plugin.
+ * It now acts as a thin wrapper that redirects to create-plugin with the worker template pre-selected.
+ */
+import { spawn } from 'child_process';
+const DEPRECATION_MESSAGE = `
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                                                             │
+│  ⚠️  @vertesia/create-worker is deprecated                                  │
+│                                                                             │
+│  Please use @vertesia/create-plugin instead:                                │
+│                                                                             │
+│    pnpm create @vertesia/plugin my-worker                                   │
+│    npm create @vertesia/plugin my-worker                                    │
+│                                                                             │
+│  Then select "Vertesia Workflow Worker" from the template list.             │
+│                                                                             │
+│  Continuing with legacy behavior for backwards compatibility...             │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+`;
+async function main(argv) {
+    console.log(DEPRECATION_MESSAGE);
+    const projectName = argv[2];
+    if (!projectName) {
+        console.error('Please specify a project name:');
+        console.error('  npx @vertesia/create-worker my-worker');
+        process.exit(1);
+    }
+    // Forward to create-plugin - user will need to select the worker template
+    console.log('Launching @vertesia/create-plugin...\n');
+    const child = spawn('npx', ['@vertesia/create-plugin', projectName], {
+        stdio: 'inherit',
+        shell: true
+    });
+    child.on('close', (code) => {
+        process.exit(code || 0);
+    });
+    child.on('error', (err) => {
+        console.error('Failed to launch create-plugin:', err.message);
+        console.error('\nPlease install and run create-plugin directly:');
+        console.error(`  npx @vertesia/create-plugin ${projectName}`);
+        process.exit(1);
+    });
+}
+main(process.argv).catch(err => {
+    console.error("Error: ", err);
+    process.exit(1);
+});
+//# sourceMappingURL=main.js.map

package/lib/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;CAe3B,CAAC;AAEF,KAAK,UAAU,IAAI,CAAC,IAAc;IAC9B,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAEjC,MAAM,WAAW,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAE5B,IAAI,CAAC,WAAW,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,0EAA0E;IAC1E,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,yBAAyB,EAAE,WAAW,CAAC,EAAE;QACjE,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,IAAI;KACd,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAmB,EAAE,EAAE;QACtC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;QAC7B,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9D,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,KAAK,CAAC,iCAAiC,WAAW,EAAE,CAAC,CAAC;QAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IAC3B,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vertesia/create-worker",
+  "version": "0.81.0",
+  "description": "Initialize workflow worker package (deprecated - use @vertesia/create-plugin instead)",
+  "type": "module",
+  "bin": {
+    "create-worker": "./bin/create-worker.mjs"
+  },
+  "main": "./lib/main.js",
+  "types": "./lib/main.d.ts",
+  "files": [
+    "lib",
+    "bin"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://docs.vertesiahq.com",
+  "keywords": [
+    "workflow",
+    "temporal",
+    "agent",
+    "llm",
+    "composable",
+    "deprecated"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.7.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertesia/composableai.git",
+    "directory": "packages/create-worker"
+  },
+  "scripts": {
+    "eslint": "eslint './src/**/*.{jsx,js,tsx,ts}'",
+    "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && tsc --build",
+    "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
+  }
+}