@openserv-labs/deploy 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# serv
+
+CLI to deploy agents to the [OpenServ](https://openserv.ai) platform.
+
+## Installation
+
+```bash
+npm install -g serv
+```
+
+Or run directly with `npx`:
+
+```bash
+npx serv deploy
+```
+
+## Usage
+
+```
+serv <command> [path]
+
+Commands:
+  deploy [path]   Deploy an agent to OpenServ (default path: .)
+
+Options:
+  --help, -h      Show this help message
+```
+
+### Deploy an agent
+
+From the agent project directory:
+
+```bash
+serv deploy
+```
+
+Or specify a path:
+
+```bash
+serv deploy ./my-agent
+```
+
+The deploy command will:
+
+1. Read configuration from `.env` and `.openserv.json` in the target directory.
+2. Resolve or create a container on the OpenServ platform.
+3. Archive the project files (respecting `.gitignore`), upload them, and run `npm install`.
+4. Start (or restart) the agent process and make it publicly available.
+5. If an agent API key is configured, update the agent's endpoint URL on the platform.
+
+## Configuration
+
+### Environment variables
+
+Set these in a `.env` file in your project directory or as shell environment variables:
+
+| Variable | Required | Description |
+|---|---|---|
+| `OPENSERV_USER_API_KEY` | Yes | Your OpenServ API key |
+| `OPENSERV_CONTAINER_ID` | No | Container ID for redeployment (auto-set after first deploy) |
+| `OPENSERV_ORCHESTRATOR_URL` | No | Custom orchestrator URL (defaults to `https://agent-orchestrator.openserv.ai`) |
+| `OPENSERV_API_URL` | No | Custom platform API URL (defaults to `https://api.openserv.ai`) |
+
+### `.openserv.json`
+
+Place this file in your project root to link deploys to a registered agent. The CLI reads the first agent entry:
+
+```json
+{
+  "agents": {
+    "My Agent": {
+      "id": 42,
+      "apiKey": "your-agent-api-key"
+    }
+  }
+}
+```
+
+When both `id` and `apiKey` are present, the CLI will automatically update the agent's endpoint URL after going live.
+
+### Files included in the deploy archive
+
+The CLI creates a tar.gz archive of your project, applying these rules:
+
+- **Always excluded:** `node_modules`, `.git`, `dist`, `.next`, `.turbo`, `.env`, `.env.example`, `.env.local`, `.env.*.local`, `*.tsbuildinfo`
+- **`.gitignore` rules** are respected if a `.gitignore` file exists.
+
+## Publishing to npm
+
+### Prerequisites
+
+- An [npm](https://www.npmjs.com/) account with publish access.
+- Node.js 20+.
+
+### Steps
+
+1. **Build the package:**
+
+```bash
+npm run build
+```
+
+2. **Update the version** (follow [semver](https://semver.org/)):
+
+```bash
+npm version patch   # or minor / major
+```
+
+3. **Publish:**
+
+```bash
+npm publish
+```
+
+The `"files"` field in `package.json` ensures only the `dist/` directory is included in the published package. The `"bin"` field registers the `serv` command globally when installed with `-g`.
+
+## Development
+
+```bash
+# Run locally without building
+npm run dev -- deploy ./my-agent
+
+# Build
+npm run build
+```

package/dist/index.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+
+// src/deploy.ts
+import path4 from "path";
+
+// src/api-client.ts
+import axios from "axios";
+var DEFAULT_ORCHESTRATOR_URL = "https://agent-orchestrator.openserv.ai";
+var ApiError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "ApiError";
+  }
+};
+var ApiClient = class {
+  client;
+  constructor(opts) {
+    const headers = {
+      "x-openserv-key": opts.apiKey
+    };
+    if (opts.agentId != null) {
+      headers["x-openserv-agent-id"] = String(opts.agentId);
+    }
+    this.client = axios.create({
+      baseURL: opts.orchestratorUrl || DEFAULT_ORCHESTRATOR_URL,
+      headers,
+      maxBodyLength: 100 * 1024 * 1024,
+      maxContentLength: 100 * 1024 * 1024
+    });
+  }
+  async createContainer() {
+    const res = await this.request("POST", "/container/create");
+    return res;
+  }
+  async getStatus(id) {
+    return this.request("GET", `/container/${id}/status`);
+  }
+  async findContainerByAgent(agentId) {
+    try {
+      const status = await this.getStatus(String(agentId));
+      return {
+        id: status.id,
+        appName: status.appName,
+        machineId: status.machineId,
+        status: status.status
+      };
+    } catch (err) {
+      if (err instanceof ApiError && err.statusCode === 404) return null;
+      throw err;
+    }
+  }
+  async upload(id, tarBuffer) {
+    await this.client.post(`/container/${id}/upload`, tarBuffer, {
+      headers: { "Content-Type": "application/gzip" }
+    });
+  }
+  async exec(id, command, timeout) {
+    return this.request("POST", `/container/${id}/exec`, {
+      command,
+      timeout
+    });
+  }
+  async start(id, entrypoint) {
+    await this.request("POST", `/container/${id}/start`, {
+      entrypoint: entrypoint || "npx tsx src/agent.ts"
+    });
+  }
+  async restart(id) {
+    await this.request("POST", `/container/${id}/restart`);
+  }
+  async goLive(id, mode = "on-demand") {
+    return this.request("POST", `/container/${id}/go-live`, {
+      mode
+    });
+  }
+  async updateEndpointUrl(agentId, agentApiKey, endpointUrl) {
+    const platformUrl = process.env.OPENSERV_API_URL || "https://api.openserv.ai";
+    await axios.put(
+      `${platformUrl}/agents/${agentId}/endpoint-url`,
+      { endpoint_url: endpointUrl },
+      { headers: { "x-openserv-key": agentApiKey } }
+    );
+  }
+  async request(method, path5, body) {
+    try {
+      const res = await this.client.request({
+        method,
+        url: path5,
+        data: body
+      });
+      return res.data;
+    } catch (err) {
+      const axiosErr = err;
+      const statusCode = axiosErr.response?.status;
+      const data = axiosErr.response?.data ?? axiosErr.message;
+      const detail = typeof data === "string" ? data : JSON.stringify(data);
+      throw new ApiError(
+        `${method} ${path5} failed (${statusCode ?? "unknown"}): ${detail}`,
+        statusCode
+      );
+    }
+  }
+};
+
+// src/env.ts
+import fs from "fs";
+import path from "path";
+import { config as loadDotenv } from "dotenv";
+function readEnv(dir) {
+  const envPath = path.join(dir, ".env");
+  const parsed = loadDotenv({ path: envPath, override: false });
+  const env = parsed.parsed ?? {};
+  return {
+    apiKey: env.OPENSERV_USER_API_KEY || process.env.OPENSERV_USER_API_KEY,
+    containerId: env.OPENSERV_CONTAINER_ID || process.env.OPENSERV_CONTAINER_ID,
+    orchestratorUrl: env.OPENSERV_ORCHESTRATOR_URL || process.env.OPENSERV_ORCHESTRATOR_URL
+  };
+}
+function writeContainerId(dir, containerId) {
+  const envPath = path.join(dir, ".env");
+  let content = "";
+  if (fs.existsSync(envPath)) {
+    content = fs.readFileSync(envPath, "utf8");
+  }
+  const key = "OPENSERV_CONTAINER_ID";
+  const line = `${key}=${containerId}`;
+  const regex = new RegExp(`^${key}=.*$`, "m");
+  if (regex.test(content)) {
+    content = content.replace(regex, line);
+  } else {
+    const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+    content = `${content}${separator}${line}
+`;
+  }
+  fs.writeFileSync(envPath, content, "utf8");
+}
+
+// src/openserv-json.ts
+import fs2 from "fs";
+import path2 from "path";
+function readAgentConfig(dir) {
+  const filePath = path2.join(dir, ".openserv.json");
+  if (!fs2.existsSync(filePath)) {
+    return void 0;
+  }
+  try {
+    const raw = fs2.readFileSync(filePath, "utf8");
+    const data = JSON.parse(raw);
+    if (!data.agents) return void 0;
+    const firstAgent = Object.values(data.agents)[0];
+    if (!firstAgent) return void 0;
+    return { id: firstAgent.id, apiKey: firstAgent.apiKey };
+  } catch {
+    return void 0;
+  }
+}
+
+// src/tar.ts
+import fs3 from "fs";
+import os from "os";
+import path3 from "path";
+import ignore from "ignore";
+import * as tar from "tar";
+var ALWAYS_EXCLUDE = [
+  "node_modules",
+  ".git",
+  "dist",
+  ".next",
+  ".turbo",
+  ".env",
+  ".env.example",
+  ".env.local",
+  ".env.*.local"
+];
+var ALWAYS_EXCLUDE_EXTENSIONS = [".tsbuildinfo"];
+async function createTarBuffer(dir) {
+  const ig = ignore();
+  ig.add(ALWAYS_EXCLUDE);
+  const gitignorePath = path3.join(dir, ".gitignore");
+  if (fs3.existsSync(gitignorePath)) {
+    const content = fs3.readFileSync(gitignorePath, "utf8");
+    ig.add(content);
+  }
+  const entries = collectEntries(dir, dir, ig);
+  const tmpFile = path3.join(os.tmpdir(), `serv-deploy-${Date.now()}.tar.gz`);
+  try {
+    await tar.create(
+      {
+        gzip: true,
+        cwd: dir,
+        portable: true,
+        file: tmpFile
+      },
+      entries
+    );
+    return { buffer: fs3.readFileSync(tmpFile), files: entries };
+  } finally {
+    try {
+      fs3.unlinkSync(tmpFile);
+    } catch {
+    }
+  }
+}
+function collectEntries(baseDir, currentDir, ig) {
+  const entries = [];
+  const items = fs3.readdirSync(currentDir, { withFileTypes: true });
+  for (const item of items) {
+    const fullPath = path3.join(currentDir, item.name);
+    const relativePath = path3.relative(baseDir, fullPath);
+    if (ALWAYS_EXCLUDE_EXTENSIONS.some((ext) => item.name.endsWith(ext))) {
+      continue;
+    }
+    const testPath = item.isDirectory() ? `${relativePath}/` : relativePath;
+    if (ig.ignores(testPath)) {
+      continue;
+    }
+    if (item.isDirectory()) {
+      entries.push(...collectEntries(baseDir, fullPath, ig));
+    } else {
+      entries.push(relativePath);
+    }
+  }
+  return entries;
+}
+
+// src/deploy.ts
+async function resolveContainer(client, dir, containerId, agentId) {
+  if (containerId) {
+    console.log(`Using existing container: ${containerId}`);
+    return { id: containerId, isFirstDeploy: false };
+  }
+  if (agentId) {
+    console.log(
+      `Agent ID found: ${agentId}. Checking for existing container...`
+    );
+    const existing = await client.findContainerByAgent(agentId);
+    if (existing) {
+      writeContainerId(dir, existing.id);
+      console.log(`  Found container: ${existing.id}`);
+      console.log("  Saved to .env\n");
+      return { id: existing.id, isFirstDeploy: false };
+    }
+    console.log("  No container found. Creating new container...");
+  } else {
+    console.log("Creating new container...");
+  }
+  const container = await client.createContainer();
+  writeContainerId(dir, container.id);
+  console.log(`  Container ID: ${container.id}`);
+  console.log("  Written to .env\n");
+  return { id: container.id, isFirstDeploy: true };
+}
+async function deploy(targetPath) {
+  const dir = path4.resolve(targetPath);
+  console.log(`Deploying from ${dir}
+`);
+  const env = readEnv(dir);
+  const agentConfig = readAgentConfig(dir);
+  const agentId = agentConfig?.id;
+  if (!env.apiKey) {
+    throw new Error(
+      "OPENSERV_USER_API_KEY not found. Set it in your .env file or as an environment variable."
+    );
+  }
+  const client = new ApiClient({
+    apiKey: env.apiKey,
+    agentId,
+    orchestratorUrl: env.orchestratorUrl
+  });
+  const { id: targetId, isFirstDeploy } = await resolveContainer(
+    client,
+    dir,
+    env.containerId,
+    agentId
+  );
+  let currentStatus;
+  let appName;
+  if (!isFirstDeploy) {
+    try {
+      const status = await client.getStatus(targetId);
+      currentStatus = status.status;
+      appName = status.appName;
+      console.log(`  Current status: ${currentStatus}`);
+    } catch {
+    }
+  }
+  console.log("\nCreating archive...");
+  const { buffer: tarBuffer, files } = await createTarBuffer(dir);
+  for (const file of files) {
+    console.log(`  ${file}`);
+  }
+  console.log(
+    `  ${files.length} files, ${(tarBuffer.length / 1024).toFixed(1)} KB`
+  );
+  console.log("\nUploading files...");
+  await client.upload(targetId, tarBuffer);
+  console.log("  Done.");
+  const verify = await client.exec(targetId, ["ls", "-la", "/app"], 30);
+  if (verify.exitCode === 0) {
+    console.log("  Verified /app contents:");
+    for (const line of verify.stdout.split("\n").filter(Boolean)) {
+      console.log(`    ${line}`);
+    }
+  } else {
+    console.error("  Warning: could not verify upload");
+    if (verify.stderr) console.error(`    ${verify.stderr}`);
+  }
+  console.log("\nInstalling dependencies...");
+  const installResult = await client.exec(targetId, ["npm", "install"], 600);
+  if (installResult.exitCode !== 0) {
+    const parts = [`npm install failed (exit code ${installResult.exitCode})`];
+    if (installResult.stdout)
+      parts.push(`stdout: ${installResult.stdout.slice(0, 500)}`);
+    if (installResult.stderr)
+      parts.push(`stderr: ${installResult.stderr.slice(0, 500)}`);
+    throw new Error(parts.join("\n"));
+  }
+  console.log("  Done.");
+  const needsStart = isFirstDeploy || !currentStatus || currentStatus === "ready";
+  if (needsStart) {
+    console.log("\nStarting agent...");
+    await client.start(targetId);
+    console.log("  Agent started.");
+  } else {
+    console.log("\nRestarting container...");
+    await client.restart(targetId);
+    console.log("  Container restarted.");
+  }
+  let publicUrl;
+  if (currentStatus !== "live") {
+    console.log("\nGoing live...");
+    const result = await client.goLive(targetId, "continuous");
+    publicUrl = result.publicUrl;
+    console.log(`  Public URL: ${publicUrl}`);
+  } else {
+    if (appName) {
+      publicUrl = `https://${appName}.fly.dev`;
+    }
+    console.log("\nAlready live.");
+  }
+  if (agentConfig?.apiKey && agentConfig.id && publicUrl) {
+    console.log("\nUpdating agent endpoint URL...");
+    await client.updateEndpointUrl(
+      agentConfig.id,
+      agentConfig.apiKey,
+      publicUrl
+    );
+    console.log(`  Agent endpoint set to ${publicUrl}`);
+  }
+  console.log("\nDeploy complete!");
+}
+
+// src/index.ts
+var HELP = `
+Usage: serv <command> [path]
+
+Commands:
+  deploy [path]   Deploy an agent to OpenServ (default path: .)
+
+Options:
+  --help, -h      Show this help message
+
+Environment variables (set in .env or shell):
+  OPENSERV_USER_API_KEY       Your OpenServ API key (required)
+  OPENSERV_CONTAINER_ID       Container ID for redeployment (auto-set after first deploy)
+  OPENSERV_ORCHESTRATOR_URL   Custom orchestrator URL (optional)
+`.trim();
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const command = args[0];
+  switch (command) {
+    case "deploy": {
+      const targetPath = args[1] || ".";
+      await deploy(targetPath);
+      break;
+    }
+    default:
+      console.error(`Unknown command: ${command}
+`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error("\nFailed:", err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@openserv-labs/deploy",
+	"version": "0.1.0",
+	"description": "CLI to deploy agents to the OpenServ platform",
+	"license": "MIT",
+	"keywords": [
+		"openserv",
+		"agent",
+		"deploy",
+		"cli"
+	],
+	"type": "module",
+	"bin": {
+		"serv": "./dist/index.js"
+	},
+	"main": "./dist/index.js",
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsx src/index.ts"
+	},
+	"dependencies": {
+		"axios": "^1.7.2",
+		"dotenv": "^16.4.7",
+		"ignore": "^7.0.3",
+		"tar": "^7.4.3"
+	},
+	"devDependencies": {
+		"@types/node": "^20.14.0",
+		"tsup": "^8.5.0",
+		"tsx": "^4.19.4",
+		"typescript": "^5.9.3"
+	}
+}