openwork-server 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# OpenWork Server
+
+Filesystem-backed API for OpenWork remote clients. This package provides the OpenWork server layer described in `packages/app/pr/openwork-server.md` and is intentionally independent from the desktop app.
+
+## Quick start
+
+```bash
+npm install -g openwork-server
+openwork-server --workspace /path/to/workspace --approval auto
+```
+
+Or from source:
+
+```bash
+pnpm --filter openwork-server dev -- \
+  --workspace /path/to/workspace \
+  --approval auto
+```
+
+The server logs the client token and host token on boot when they are auto-generated.
+
+## Config file
+
+Defaults to `~/.config/openwork/server.json` (override with `OPENWORK_SERVER_CONFIG` or `--config`).
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 8787,
+  "approval": { "mode": "manual", "timeoutMs": 30000 },
+  "workspaces": [
+    {
+      "path": "/Users/susan/Finance",
+      "name": "Finance",
+      "workspaceType": "local",
+      "baseUrl": "http://127.0.0.1:4096",
+      "directory": "/Users/susan/Finance"
+    }
+  ],
+  "corsOrigins": ["http://localhost:5173"]
+}
+```
+
+## Environment variables
+
+- `OPENWORK_SERVER_CONFIG` path to config JSON
+- `OPENWORK_HOST` / `OPENWORK_PORT`
+- `OPENWORK_TOKEN` client bearer token
+- `OPENWORK_HOST_TOKEN` host approval token
+- `OPENWORK_APPROVAL_MODE` (`manual` | `auto`)
+- `OPENWORK_APPROVAL_TIMEOUT_MS`
+- `OPENWORK_WORKSPACES` (JSON array or comma-separated list of paths)
+- `OPENWORK_CORS_ORIGINS` (comma-separated list or `*`)
+- `OPENWORK_OPENCODE_BASE_URL`
+- `OPENWORK_OPENCODE_DIRECTORY`
+- `OPENWORK_OPENCODE_USERNAME`
+- `OPENWORK_OPENCODE_PASSWORD`
+
+## Endpoints (initial)
+
+- `GET /health`
+- `GET /capabilities`
+- `GET /workspaces`
+- `GET /workspace/:id/config`
+- `PATCH /workspace/:id/config`
+- `GET /workspace/:id/plugins`
+- `POST /workspace/:id/plugins`
+- `DELETE /workspace/:id/plugins/:name`
+- `GET /workspace/:id/skills`
+- `POST /workspace/:id/skills`
+- `GET /workspace/:id/mcp`
+- `POST /workspace/:id/mcp`
+- `DELETE /workspace/:id/mcp/:name`
+- `GET /workspace/:id/commands`
+- `POST /workspace/:id/commands`
+- `DELETE /workspace/:id/commands/:name`
+- `GET /workspace/:id/audit`
+- `GET /workspace/:id/export`
+- `POST /workspace/:id/import`
+
+## Approvals
+
+All writes are gated by host approval. Host APIs require `X-OpenWork-Host-Token`:
+
+- `GET /approvals`
+- `POST /approvals/:id` with `{ "reply": "allow" | "deny" }`
+
+Set `OPENWORK_APPROVAL_MODE=auto` to auto-approve during local development.

package/dist/approvals.js

@@ -0,0 +1,45 @@
+import { shortId } from "./utils.js";
+export class ApprovalService {
+    config;
+    pending = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    list() {
+        return Array.from(this.pending.values()).map((entry) => entry.request);
+    }
+    async requestApproval(input) {
+        if (this.config.mode === "auto") {
+            return { id: "auto", allowed: true };
+        }
+        const id = shortId();
+        const request = {
+            ...input,
+            id,
+            createdAt: Date.now(),
+        };
+        const result = await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                resolve({ id, allowed: false, reason: "timeout" });
+            }, this.config.timeoutMs);
+            this.pending.set(id, { request, resolve, timeout });
+        });
+        return result;
+    }
+    respond(id, reply) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return null;
+        if (pending.timeout)
+            clearTimeout(pending.timeout);
+        this.pending.delete(id);
+        const result = {
+            id,
+            allowed: reply === "allow",
+            reason: reply === "allow" ? undefined : "denied",
+        };
+        pending.resolve(result);
+        return result;
+    }
+}

package/dist/audit.js

@@ -0,0 +1,47 @@
+import { dirname, join } from "node:path";
+import { appendFile, readFile } from "node:fs/promises";
+import { ensureDir, exists } from "./utils.js";
+export function auditLogPath(workspaceRoot) {
+    return join(workspaceRoot, ".opencode", "openwork", "audit.jsonl");
+}
+export async function recordAudit(workspaceRoot, entry) {
+    const path = auditLogPath(workspaceRoot);
+    await ensureDir(dirname(path));
+    await appendFile(path, JSON.stringify(entry) + "\n", "utf8");
+}
+export async function readLastAudit(workspaceRoot) {
+    const path = auditLogPath(workspaceRoot);
+    if (!(await exists(path)))
+        return null;
+    const content = await readFile(path, "utf8");
+    const lines = content.trim().split("\n");
+    const last = lines[lines.length - 1];
+    if (!last)
+        return null;
+    try {
+        return JSON.parse(last);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readAuditEntries(workspaceRoot, limit = 50) {
+    const path = auditLogPath(workspaceRoot);
+    if (!(await exists(path)))
+        return [];
+    const content = await readFile(path, "utf8");
+    const rawLines = content.trim().split("\n").filter(Boolean);
+    if (!rawLines.length)
+        return [];
+    const slice = rawLines.slice(-Math.max(1, limit));
+    const entries = [];
+    for (let i = slice.length - 1; i >= 0; i -= 1) {
+        try {
+            entries.push(JSON.parse(slice[i]));
+        }
+        catch {
+            // ignore malformed entry
+        }
+    }
+    return entries;
+}

package/dist/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+import { parseCliArgs, printHelp, resolveServerConfig } from "./config.js";
+import { startServer } from "./server.js";
+const args = parseCliArgs(process.argv.slice(2));
+if (args.help) {
+    printHelp();
+    process.exit(0);
+}
+const config = await resolveServerConfig(args);
+const server = startServer(config);
+const url = `http://${config.host}:${server.port}`;
+console.log(`OpenWork server listening on ${url}`);
+if (config.tokenSource === "generated") {
+    console.log(`Client token: ${config.token}`);
+}
+if (config.hostTokenSource === "generated") {
+    console.log(`Host token: ${config.hostToken}`);
+}
+if (config.workspaces.length === 0) {
+    console.log("No workspaces configured. Add --workspace or update server.json.");
+}
+else {
+    console.log(`Workspaces: ${config.workspaces.length}`);
+}

package/dist/commands.js

@@ -0,0 +1,73 @@
+import { readdir, readFile, writeFile, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseFrontmatter, buildFrontmatter } from "./frontmatter.js";
+import { exists } from "./utils.js";
+import { projectCommandsDir } from "./workspace-files.js";
+import { validateCommandName, sanitizeCommandName } from "./validators.js";
+import { ApiError } from "./errors.js";
+async function listCommandsInDir(dir, scope) {
+    if (!(await exists(dir)))
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    const items = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith(".md"))
+            continue;
+        const filePath = join(dir, entry.name);
+        const content = await readFile(filePath, "utf8");
+        const { data, body } = parseFrontmatter(content);
+        const name = typeof data.name === "string" ? data.name : entry.name.replace(/\.md$/, "");
+        try {
+            validateCommandName(name);
+        }
+        catch {
+            continue;
+        }
+        items.push({
+            name,
+            description: typeof data.description === "string" ? data.description : undefined,
+            template: body.trim(),
+            agent: typeof data.agent === "string" ? data.agent : undefined,
+            model: typeof data.model === "string" ? data.model : null,
+            subtask: typeof data.subtask === "boolean" ? data.subtask : undefined,
+            scope,
+        });
+    }
+    return items;
+}
+export async function listCommands(workspaceRoot, scope) {
+    if (scope === "global") {
+        const dir = join(homedir(), ".config", "opencode", "commands");
+        return listCommandsInDir(dir, "global");
+    }
+    return listCommandsInDir(projectCommandsDir(workspaceRoot), "workspace");
+}
+export async function upsertCommand(workspaceRoot, payload) {
+    if (!payload.template || payload.template.trim().length === 0) {
+        throw new ApiError(400, "invalid_command_template", "Command template is required");
+    }
+    const sanitized = sanitizeCommandName(payload.name);
+    validateCommandName(sanitized);
+    const frontmatter = buildFrontmatter({
+        name: sanitized,
+        description: payload.description,
+        agent: payload.agent,
+        model: payload.model ?? null,
+        subtask: payload.subtask ?? false,
+    });
+    const content = frontmatter + "\n" + payload.template.trim() + "\n";
+    const dir = projectCommandsDir(workspaceRoot);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `${sanitized}.md`);
+    await writeFile(path, content, "utf8");
+    return path;
+}
+export async function deleteCommand(workspaceRoot, name) {
+    const sanitized = sanitizeCommandName(name);
+    validateCommandName(sanitized);
+    const path = join(projectCommandsDir(workspaceRoot), `${sanitized}.md`);
+    await rm(path, { force: true });
+}

package/dist/config.js

@@ -0,0 +1,210 @@
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { buildWorkspaceInfos } from "./workspaces.js";
+import { parseList, readJsonFile, shortId } from "./utils.js";
+const DEFAULT_PORT = 8787;
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_TIMEOUT_MS = 30000;
+export function parseCliArgs(argv) {
+    const args = { workspaces: [] };
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (!value)
+            continue;
+        if (value === "--help" || value === "-h") {
+            args.help = true;
+            continue;
+        }
+        if (value === "--config") {
+            args.configPath = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--host") {
+            args.host = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--port") {
+            const port = Number(argv[index + 1]);
+            if (!Number.isNaN(port))
+                args.port = port;
+            index += 1;
+            continue;
+        }
+        if (value === "--token") {
+            args.token = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--host-token") {
+            args.hostToken = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--approval") {
+            const mode = argv[index + 1];
+            if (mode === "manual" || mode === "auto")
+                args.approvalMode = mode;
+            index += 1;
+            continue;
+        }
+        if (value === "--approval-timeout") {
+            const timeout = Number(argv[index + 1]);
+            if (!Number.isNaN(timeout))
+                args.approvalTimeoutMs = timeout;
+            index += 1;
+            continue;
+        }
+        if (value === "--opencode-base-url") {
+            args.opencodeBaseUrl = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--opencode-directory") {
+            args.opencodeDirectory = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--opencode-username") {
+            args.opencodeUsername = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--opencode-password") {
+            args.opencodePassword = argv[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--workspace") {
+            const path = argv[index + 1];
+            if (path)
+                args.workspaces.push(path);
+            index += 1;
+            continue;
+        }
+        if (value === "--cors") {
+            args.corsOrigins = parseList(argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (value === "--read-only") {
+            args.readOnly = true;
+            continue;
+        }
+    }
+    return args;
+}
+export function printHelp() {
+    const message = [
+        "openwork-server",
+        "",
+        "Options:",
+        "  --config <path>          Path to server.json",
+        "  --host <host>            Hostname (default 127.0.0.1)",
+        "  --port <port>            Port (default 8787)",
+        "  --token <token>          Client bearer token",
+        "  --host-token <token>     Host approval token",
+        "  --approval <mode>        manual | auto",
+        "  --approval-timeout <ms>  Approval timeout",
+        "  --opencode-base-url <url> OpenCode base URL to share",
+        "  --opencode-directory <path> OpenCode workspace directory to share",
+        "  --opencode-username <user> OpenCode server username",
+        "  --opencode-password <pass> OpenCode server password",
+        "  --workspace <path>       Workspace root (repeatable)",
+        "  --cors <origins>          Comma-separated origins or *",
+        "  --read-only              Disable writes",
+    ].join("\n");
+    console.log(message);
+}
+async function loadFileConfig(configPath) {
+    const parsed = await readJsonFile(configPath);
+    return parsed ?? {};
+}
+export async function resolveServerConfig(cli) {
+    const envConfigPath = process.env.OPENWORK_SERVER_CONFIG;
+    const configPath = cli.configPath ?? envConfigPath ?? resolve(homedir(), ".config", "openwork", "server.json");
+    const fileConfig = await loadFileConfig(configPath);
+    const configDir = dirname(configPath);
+    const envWorkspaces = parseList(process.env.OPENWORK_WORKSPACES);
+    const workspaceConfigs = cli.workspaces.length > 0
+        ? cli.workspaces.map((path) => ({ path }))
+        : envWorkspaces.length > 0
+            ? envWorkspaces.map((path) => ({ path }))
+            : fileConfig.workspaces ?? [];
+    const envOpencodeBaseUrl = process.env.OPENWORK_OPENCODE_BASE_URL;
+    const envOpencodeDirectory = process.env.OPENWORK_OPENCODE_DIRECTORY;
+    const envOpencodeUsername = process.env.OPENWORK_OPENCODE_USERNAME;
+    const envOpencodePassword = process.env.OPENWORK_OPENCODE_PASSWORD;
+    const opencodeBaseUrl = cli.opencodeBaseUrl ?? envOpencodeBaseUrl;
+    const opencodeDirectory = cli.opencodeDirectory ?? envOpencodeDirectory;
+    const opencodeUsername = cli.opencodeUsername ?? envOpencodeUsername ?? fileConfig.opencodeUsername;
+    const opencodePassword = cli.opencodePassword ?? envOpencodePassword ?? fileConfig.opencodePassword;
+    if (workspaceConfigs.length > 0 && (opencodeBaseUrl || opencodeDirectory || opencodeUsername || opencodePassword)) {
+        workspaceConfigs[0] = {
+            ...workspaceConfigs[0],
+            baseUrl: opencodeBaseUrl ?? workspaceConfigs[0].baseUrl,
+            directory: opencodeDirectory ?? workspaceConfigs[0].directory,
+            opencodeUsername: opencodeUsername ?? workspaceConfigs[0].opencodeUsername,
+            opencodePassword: opencodePassword ?? workspaceConfigs[0].opencodePassword,
+        };
+    }
+    const workspaces = buildWorkspaceInfos(workspaceConfigs, configDir);
+    const tokenFromEnv = process.env.OPENWORK_TOKEN;
+    const hostTokenFromEnv = process.env.OPENWORK_HOST_TOKEN;
+    const token = cli.token ?? tokenFromEnv ?? fileConfig.token ?? shortId();
+    const hostToken = cli.hostToken ?? hostTokenFromEnv ?? fileConfig.hostToken ?? shortId();
+    const tokenSource = cli.token
+        ? "cli"
+        : tokenFromEnv
+            ? "env"
+            : fileConfig.token
+                ? "file"
+                : "generated";
+    const hostTokenSource = cli.hostToken
+        ? "cli"
+        : hostTokenFromEnv
+            ? "env"
+            : fileConfig.hostToken
+                ? "file"
+                : "generated";
+    const approvalMode = cli.approvalMode ??
+        process.env.OPENWORK_APPROVAL_MODE ??
+        fileConfig.approval?.mode ??
+        "manual";
+    const approvalTimeoutMs = cli.approvalTimeoutMs ??
+        (process.env.OPENWORK_APPROVAL_TIMEOUT_MS ? Number(process.env.OPENWORK_APPROVAL_TIMEOUT_MS) : undefined) ??
+        fileConfig.approval?.timeoutMs ??
+        DEFAULT_TIMEOUT_MS;
+    const approval = {
+        mode: approvalMode === "auto" ? "auto" : "manual",
+        timeoutMs: Number.isNaN(approvalTimeoutMs) ? DEFAULT_TIMEOUT_MS : approvalTimeoutMs,
+    };
+    const envCorsOrigins = process.env.OPENWORK_CORS_ORIGINS;
+    const parsedEnvCors = envCorsOrigins ? parseList(envCorsOrigins) : null;
+    const corsOrigins = cli.corsOrigins ?? parsedEnvCors ?? fileConfig.corsOrigins ?? ["*"];
+    const envReadOnly = process.env.OPENWORK_READONLY;
+    const parsedReadOnly = envReadOnly
+        ? ["true", "1", "yes"].includes(envReadOnly.toLowerCase())
+        : undefined;
+    const readOnly = cli.readOnly ?? parsedReadOnly ?? fileConfig.readOnly ?? false;
+    const authorizedRoots = fileConfig.authorizedRoots?.length
+        ? fileConfig.authorizedRoots.map((root) => resolve(configDir, root))
+        : workspaces.map((workspace) => workspace.path);
+    const host = cli.host ?? process.env.OPENWORK_HOST ?? fileConfig.host ?? DEFAULT_HOST;
+    const port = cli.port ?? (process.env.OPENWORK_PORT ? Number(process.env.OPENWORK_PORT) : undefined) ?? fileConfig.port ?? DEFAULT_PORT;
+    return {
+        host,
+        port: Number.isNaN(port) ? DEFAULT_PORT : port,
+        token,
+        hostToken,
+        approval,
+        corsOrigins,
+        workspaces,
+        authorizedRoots,
+        readOnly,
+        startedAt: Date.now(),
+        tokenSource,
+        hostTokenSource,
+    };
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+export function formatError(err) {
+    return {
+        code: err.code,
+        message: err.message,
+        details: err.details,
+    };
+}

package/dist/frontmatter.js

@@ -0,0 +1,15 @@
+import { parse, stringify } from "yaml";
+export function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match) {
+        return { data: {}, body: content };
+    }
+    const raw = match[1] ?? "";
+    const data = parse(raw) ?? {};
+    const body = content.slice(match[0].length);
+    return { data, body };
+}
+export function buildFrontmatter(data) {
+    const yaml = stringify(data).trimEnd();
+    return `---\n${yaml}\n---\n`;
+}

package/dist/jsonc.js

@@ -0,0 +1,43 @@
+import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+import { dirname } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { ApiError } from "./errors.js";
+import { ensureDir, exists } from "./utils.js";
+export async function readJsoncFile(path, fallback) {
+    if (!(await exists(path))) {
+        return { data: fallback, raw: "" };
+    }
+    const raw = await readFile(path, "utf8");
+    const errors = [];
+    const data = parse(raw, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+        const details = errors.map((error) => ({
+            code: printParseErrorCode(error.error),
+            offset: error.offset,
+            length: error.length,
+        }));
+        throw new ApiError(422, "invalid_jsonc", "Failed to parse JSONC", details);
+    }
+    return { data, raw };
+}
+export async function updateJsoncTopLevel(path, updates) {
+    const hasFile = await exists(path);
+    if (!hasFile) {
+        await ensureDir(dirname(path));
+        const content = JSON.stringify(updates, null, 2) + "\n";
+        await writeFile(path, content, "utf8");
+        return;
+    }
+    let content = await readFile(path, "utf8");
+    const formattingOptions = { insertSpaces: true, tabSize: 2, eol: "\n" };
+    for (const [key, value] of Object.entries(updates)) {
+        const edits = modify(content, [key], value, { formattingOptions });
+        content = applyEdits(content, edits);
+    }
+    await writeFile(path, content.endsWith("\n") ? content : content + "\n", "utf8");
+}
+export async function writeJsoncFile(path, value) {
+    await ensureDir(dirname(path));
+    const content = JSON.stringify(value, null, 2) + "\n";
+    await writeFile(path, content, "utf8");
+}

package/dist/mcp.js

@@ -0,0 +1,50 @@
+import { minimatch } from "minimatch";
+import { readJsoncFile, updateJsoncTopLevel } from "./jsonc.js";
+import { opencodeConfigPath } from "./workspace-files.js";
+import { validateMcpConfig, validateMcpName } from "./validators.js";
+function getMcpConfig(config) {
+    const mcp = config.mcp;
+    if (!mcp || typeof mcp !== "object")
+        return {};
+    return mcp;
+}
+function getDeniedToolPatterns(config) {
+    const tools = config.tools;
+    if (!tools || typeof tools !== "object")
+        return [];
+    const deny = tools.deny;
+    if (!Array.isArray(deny))
+        return [];
+    return deny.filter((item) => typeof item === "string");
+}
+function isMcpDisabledByTools(config, name) {
+    const patterns = getDeniedToolPatterns(config);
+    if (patterns.length === 0)
+        return false;
+    const candidates = [`mcp.${name}`, `mcp.${name}.*`, `mcp:${name}`, `mcp:${name}:*`, "mcp.*", "mcp:*"];
+    return patterns.some((pattern) => candidates.some((candidate) => minimatch(candidate, pattern)));
+}
+export async function listMcp(workspaceRoot) {
+    const { data: config } = await readJsoncFile(opencodeConfigPath(workspaceRoot), {});
+    const mcpMap = getMcpConfig(config);
+    return Object.entries(mcpMap).map(([name, entry]) => ({
+        name,
+        config: entry,
+        source: "config.project",
+        disabledByTools: isMcpDisabledByTools(config, name) || undefined,
+    }));
+}
+export async function addMcp(workspaceRoot, name, config) {
+    validateMcpName(name);
+    validateMcpConfig(config);
+    const { data } = await readJsoncFile(opencodeConfigPath(workspaceRoot), {});
+    const mcpMap = getMcpConfig(data);
+    mcpMap[name] = config;
+    await updateJsoncTopLevel(opencodeConfigPath(workspaceRoot), { mcp: mcpMap });
+}
+export async function removeMcp(workspaceRoot, name) {
+    const { data } = await readJsoncFile(opencodeConfigPath(workspaceRoot), {});
+    const mcpMap = getMcpConfig(data);
+    delete mcpMap[name];
+    await updateJsoncTopLevel(opencodeConfigPath(workspaceRoot), { mcp: mcpMap });
+}

package/dist/paths.js

@@ -0,0 +1,19 @@
+import { realpath } from "node:fs/promises";
+import { isAbsolute, resolve, sep } from "node:path";
+import { ApiError } from "./errors.js";
+export function assertAbsolute(path) {
+    if (!isAbsolute(path)) {
+        throw new ApiError(400, "invalid_path", "Path must be absolute");
+    }
+}
+export async function resolveWithinRoot(root, ...segments) {
+    const resolvedRoot = await realpath(root);
+    const candidate = resolve(resolvedRoot, ...segments);
+    const resolvedCandidate = await realpath(candidate).catch(() => candidate);
+    if (resolvedCandidate === resolvedRoot)
+        return candidate;
+    if (!resolvedCandidate.startsWith(resolvedRoot + sep)) {
+        throw new ApiError(400, "path_escape", "Path escapes workspace root");
+    }
+    return candidate;
+}