@neuralnomads/codenomad 0.4.0 → 0.5.1

package/dist/opencode-config/plugin/lib/background-process.ts

@@ -0,0 +1,309 @@
+import path from "path"
+import { tool } from "@opencode-ai/plugin/tool"
+
+type BackgroundProcess = {
+  id: string
+  title: string
+  command: string
+  status: "running" | "stopped" | "error"
+  startedAt: string
+  stoppedAt?: string
+  exitCode?: number
+  outputSizeBytes?: number
+}
+
+type CodeNomadConfig = {
+  instanceId: string
+  baseUrl: string
+}
+
+type BackgroundProcessOptions = {
+  baseDir: string
+}
+
+type ParsedCommand = {
+  head: string
+  args: string[]
+}
+
+export function createBackgroundProcessTools(config: CodeNomadConfig, options: BackgroundProcessOptions) {
+  const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
+
+    const base = config.baseUrl.replace(/\/+$/, "")
+    const url = `${base}/workspaces/${config.instanceId}/plugin/background-processes${path}`
+    const headers = normalizeHeaders(init?.headers)
+    if (init?.body !== undefined) {
+      headers["Content-Type"] = "application/json"
+    }
+
+    const response = await fetch(url, {
+      ...init,
+      headers,
+    })
+
+    if (!response.ok) {
+      const message = await response.text()
+      throw new Error(message || `Request failed with ${response.status}`)
+    }
+
+    if (response.status === 204) {
+      return undefined as T
+    }
+
+    return (await response.json()) as T
+  }
+
+  return {
+    run_background_process: tool({
+      description:
+        "Run a long-lived background process (dev servers, DBs, watchers) so it keeps running while you do other tasks. Use it for running processes that timeout otherwise or produce a lot of output.",
+      args: {
+        title: tool.schema.string().describe("Short label for the process (e.g. Dev server, DB server)"),
+        command: tool.schema.string().describe("Shell command to run in the workspace"),
+      },
+      async execute(args) {
+        assertCommandWithinBase(args.command, options.baseDir)
+        const process = await request<BackgroundProcess>("", {
+          method: "POST",
+          body: JSON.stringify({ title: args.title, command: args.command }),
+        })
+
+        return `Started background process ${process.id} (${process.title})\nStatus: ${process.status}\nCommand: ${process.command}`
+      },
+    }),
+    list_background_processes: tool({
+      description: "List background processes running for this workspace.",
+      args: {},
+      async execute() {
+        const response = await request<{ processes: BackgroundProcess[] }>("")
+        if (response.processes.length === 0) {
+          return "No background processes running."
+        }
+
+        return response.processes
+          .map((process) => {
+            const status = process.status === "running" ? "running" : process.status
+            const exit = process.exitCode !== undefined ? ` (exit ${process.exitCode})` : ""
+            const size =
+              typeof process.outputSizeBytes === "number" ? ` | ${Math.round(process.outputSizeBytes / 1024)}KB` : ""
+            return `- ${process.id} | ${process.title} | ${status}${exit}${size}\n  ${process.command}`
+          })
+          .join("\n")
+      },
+    }),
+    read_background_process_output: tool({
+      description: "Read output from a background process. Use full, grep, head, or tail.",
+      args: {
+        id: tool.schema.string().describe("Background process ID"),
+        method: tool.schema
+          .enum(["full", "grep", "head", "tail"])
+          .default("full")
+          .describe("Method to read output"),
+        pattern: tool.schema.string().optional().describe("Pattern for grep method"),
+        lines: tool.schema.number().optional().describe("Number of lines for head/tail methods"),
+      },
+      async execute(args) {
+        if (args.method === "grep" && !args.pattern) {
+          return "Pattern is required for grep method."
+        }
+
+        const params = new URLSearchParams({ method: args.method })
+        if (args.pattern) {
+          params.set("pattern", args.pattern)
+        }
+        if (args.lines) {
+          params.set("lines", String(args.lines))
+        }
+
+        const response = await request<{ id: string; content: string; truncated: boolean; sizeBytes: number }>(
+          `/${args.id}/output?${params.toString()}`,
+        )
+
+        const header = response.truncated
+          ? `Output (truncated, ${Math.round(response.sizeBytes / 1024)}KB):`
+          : `Output (${Math.round(response.sizeBytes / 1024)}KB):`
+
+        return `${header}\n\n${response.content}`
+      },
+    }),
+    stop_background_process: tool({
+      description: "Stop a background process (SIGTERM) but keep its output and entry.",
+      args: {
+        id: tool.schema.string().describe("Background process ID"),
+      },
+      async execute(args) {
+        const process = await request<BackgroundProcess>(`/${args.id}/stop`, { method: "POST" })
+        return `Stopped background process ${process.id} (${process.title}). Status: ${process.status}`
+      },
+    }),
+    terminate_background_process: tool({
+      description: "Terminate a background process and delete its output + entry.",
+      args: {
+        id: tool.schema.string().describe("Background process ID"),
+      },
+      async execute(args) {
+        await request<void>(`/${args.id}/terminate`, { method: "POST" })
+        return `Terminated background process ${args.id} and removed its output.`
+      },
+    }),
+  }
+}
+
+const FILE_COMMANDS = new Set(["cd", "rm", "cp", "mv", "mkdir", "touch", "chmod", "chown"])
+const EXPANSION_CHARS = /[~*$?\[\]`$]/
+
+function assertCommandWithinBase(command: string, baseDir: string) {
+  const normalizedBase = path.resolve(baseDir)
+  const commands = splitCommands(command)
+
+  for (const item of commands) {
+    if (!FILE_COMMANDS.has(item.head)) {
+      continue
+    }
+
+    for (const arg of item.args) {
+      if (!arg) continue
+      if (arg.startsWith("-") || (item.head === "chmod" && arg.startsWith("+"))) continue
+
+      const literalArg = unquote(arg)
+      if (EXPANSION_CHARS.test(literalArg)) {
+        throw new Error(`Background process commands may only reference paths within ${normalizedBase}.`)
+      }
+
+      const resolved = path.isAbsolute(literalArg) ? path.normalize(literalArg) : path.resolve(normalizedBase, literalArg)
+      if (!isWithinBase(normalizedBase, resolved)) {
+        throw new Error(`Background process commands may only reference paths within ${normalizedBase}.`)
+      }
+    }
+  }
+}
+
+function splitCommands(command: string): ParsedCommand[] {
+  const tokens = tokenize(command)
+  const commands: ParsedCommand[] = []
+  let current: string[] = []
+
+  for (const token of tokens) {
+    if (isSeparator(token)) {
+      if (current.length > 0) {
+        commands.push({ head: current[0], args: current.slice(1) })
+        current = []
+      }
+      continue
+    }
+    current.push(token)
+  }
+
+  if (current.length > 0) {
+    commands.push({ head: current[0], args: current.slice(1) })
+  }
+
+  return commands
+}
+
+function tokenize(input: string): string[] {
+  const tokens: string[] = []
+  let current = ""
+  let quote: "'" | '"' | null = null
+  let escape = false
+
+  const flush = () => {
+    if (current.length > 0) {
+      tokens.push(current)
+      current = ""
+    }
+  }
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index]
+
+    if (escape) {
+      current += char
+      escape = false
+      continue
+    }
+
+    if (char === "\\" && quote !== "'") {
+      escape = true
+      continue
+    }
+
+    if (quote) {
+      current += char
+      if (char === quote) {
+        quote = null
+      }
+      continue
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char
+      current += char
+      continue
+    }
+
+    if (char === " " || char === "\n" || char === "\t") {
+      flush()
+      continue
+    }
+
+    if (char === "|" || char === "&" || char === ";") {
+      flush()
+      const next = input[index + 1]
+      if ((char === "|" || char === "&") && next === char) {
+        tokens.push(char + next)
+        index += 1
+      } else {
+        tokens.push(char)
+      }
+      continue
+    }
+
+    current += char
+  }
+
+  flush()
+  return tokens
+}
+
+function isSeparator(token: string) {
+  return token === "|" || token === "||" || token === "&&" || token === ";" || token === "&"
+}
+
+function unquote(value: string) {
+  if (value.length >= 2) {
+    const first = value[0]
+    const last = value[value.length - 1]
+    if ((first === "'" && last === "'") || (first === '"' && last === '"')) {
+      return value.slice(1, -1)
+    }
+  }
+  return value
+}
+
+function isWithinBase(baseDir: string, target: string) {
+  const relative = path.relative(baseDir, target)
+  if (!relative) return true
+  return !relative.startsWith("..") && !path.isAbsolute(relative)
+}
+
+function normalizeHeaders(headers: HeadersInit | undefined): Record<string, string> {
+  const output: Record<string, string> = {}
+  if (!headers) return output
+
+  if (headers instanceof Headers) {
+    headers.forEach((value, key) => {
+      output[key] = value
+    })
+    return output
+  }
+
+  if (Array.isArray(headers)) {
+    for (const [key, value] of headers) {
+      output[key] = value
+    }
+    return output
+  }
+
+  return { ...headers }
+}

package/dist/opencode-config/plugin/lib/client.ts

@@ -0,0 +1,165 @@
+export type PluginEvent = {
+  type: string
+  properties?: Record<string, unknown>
+}
+
+export type CodeNomadConfig = {
+  instanceId: string
+  baseUrl: string
+}
+
+export function getCodeNomadConfig(): CodeNomadConfig {
+  return {
+    instanceId: requireEnv("CODENOMAD_INSTANCE_ID"),
+    baseUrl: requireEnv("CODENOMAD_BASE_URL"),
+  }
+}
+
+export function createCodeNomadClient(config: CodeNomadConfig) {
+  return {
+    postEvent: (event: PluginEvent) => postPluginEvent(config.baseUrl, config.instanceId, event),
+    startEvents: (onEvent: (event: PluginEvent) => void) => startPluginEvents(config.baseUrl, config.instanceId, onEvent),
+  }
+}
+
+function requireEnv(key: string): string {
+  const value = process.env[key]
+  if (!value || !value.trim()) {
+    throw new Error(`[CodeNomadPlugin] Missing required env var ${key}`)
+  }
+  return value
+}
+
+function delay(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms))
+}
+
+async function postPluginEvent(baseUrl: string, instanceId: string, event: PluginEvent) {
+  const url = `${baseUrl.replace(/\/+$/, "")}/workspaces/${instanceId}/plugin/event`
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(event),
+  })
+
+  if (!response.ok) {
+    throw new Error(`[CodeNomadPlugin] POST ${url} failed (${response.status})`)
+  }
+}
+
+async function startPluginEvents(baseUrl: string, instanceId: string, onEvent: (event: PluginEvent) => void) {
+  const url = `${baseUrl.replace(/\/+$/, "")}/workspaces/${instanceId}/plugin/events`
+
+  // Fail plugin startup if we cannot establish the initial connection.
+  const initialBody = await connectWithRetries(url, 3)
+
+  // After startup, keep reconnecting; throw after 3 consecutive failures.
+  void consumeWithReconnect(url, onEvent, initialBody)
+}
+
+async function connectWithRetries(url: string, maxAttempts: number) {
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const response = await fetch(url, { headers: { Accept: "text/event-stream" } })
+      if (!response.ok || !response.body) {
+        throw new Error(`[CodeNomadPlugin] SSE unavailable (${response.status})`)
+      }
+      return response.body
+    } catch (error) {
+      lastError = error
+      await delay(500 * attempt)
+    }
+  }
+
+  const reason = lastError instanceof Error ? lastError.message : String(lastError)
+  throw new Error(`[CodeNomadPlugin] Failed to connect to CodeNomad after ${maxAttempts} retries: ${reason}`)
+}
+
+async function consumeWithReconnect(
+  url: string,
+  onEvent: (event: PluginEvent) => void,
+  initialBody: ReadableStream<Uint8Array>,
+) {
+  let consecutiveFailures = 0
+  let body: ReadableStream<Uint8Array> | null = initialBody
+
+  while (true) {
+    try {
+      if (!body) {
+        body = await connectWithRetries(url, 3)
+      }
+
+      await consumeSseBody(body, onEvent)
+      body = null
+      consecutiveFailures = 0
+    } catch (error) {
+      body = null
+      consecutiveFailures += 1
+      if (consecutiveFailures >= 3) {
+        const reason = error instanceof Error ? error.message : String(error)
+        throw new Error(`[CodeNomadPlugin] Plugin event stream failed after 3 retries: ${reason}`)
+      }
+      await delay(500 * consecutiveFailures)
+    }
+  }
+}
+
+async function consumeSseBody(body: ReadableStream<Uint8Array>, onEvent: (event: PluginEvent) => void) {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ""
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done || !value) {
+      break
+    }
+
+    buffer += decoder.decode(value, { stream: true })
+
+    let separatorIndex = buffer.indexOf("\n\n")
+    while (separatorIndex >= 0) {
+      const chunk = buffer.slice(0, separatorIndex)
+      buffer = buffer.slice(separatorIndex + 2)
+      separatorIndex = buffer.indexOf("\n\n")
+
+      const event = parseSseChunk(chunk)
+      if (event) {
+        onEvent(event)
+      }
+    }
+  }
+
+  throw new Error("SSE stream ended")
+}
+
+function parseSseChunk(chunk: string): PluginEvent | null {
+  const lines = chunk.split(/\r?\n/)
+  const dataLines: string[] = []
+
+  for (const line of lines) {
+    if (line.startsWith(":")) continue
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart())
+    }
+  }
+
+  if (dataLines.length === 0) return null
+
+  const payload = dataLines.join("\n").trim()
+  if (!payload) return null
+
+  try {
+    const parsed = JSON.parse(payload)
+    if (!parsed || typeof parsed !== "object" || typeof (parsed as any).type !== "string") {
+      return null
+    }
+    return parsed as PluginEvent
+  } catch {
+    return null
+  }
+}

package/dist/opencode-config.js

@@ -0,0 +1,26 @@
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createLogger } from "./logger";
+const log = createLogger({ component: "opencode-config" });
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const devTemplateDir = path.resolve(__dirname, "../../opencode-config");
+const resourcesPath = process.resourcesPath;
+const prodTemplateDirs = [
+    resourcesPath ? path.resolve(resourcesPath, "opencode-config") : undefined,
+    path.resolve(__dirname, "opencode-config"),
+].filter((dir) => Boolean(dir));
+const isDevBuild = Boolean(process.env.CODENOMAD_DEV ?? process.env.CLI_UI_DEV_SERVER) || existsSync(devTemplateDir);
+const templateDir = isDevBuild
+    ? devTemplateDir
+    : prodTemplateDirs.find((dir) => existsSync(dir)) ?? prodTemplateDirs[0];
+export function getOpencodeConfigDir() {
+    if (!existsSync(templateDir)) {
+        throw new Error(`CodeNomad Opencode config template missing at ${templateDir}`);
+    }
+    if (isDevBuild) {
+        log.debug({ templateDir }, "Using Opencode config template directly (dev mode)");
+    }
+    return templateDir;
+}

package/dist/plugins/channel.js

@@ -0,0 +1,40 @@
+export class PluginChannelManager {
+    constructor(logger) {
+        this.logger = logger;
+        this.clients = new Set();
+    }
+    register(workspaceId, reply) {
+        const connection = { workspaceId, reply };
+        this.clients.add(connection);
+        this.logger.debug({ workspaceId }, "Plugin SSE client connected");
+        let closed = false;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            this.clients.delete(connection);
+            this.logger.debug({ workspaceId }, "Plugin SSE client disconnected");
+        };
+        return { close };
+    }
+    send(workspaceId, event) {
+        for (const client of this.clients) {
+            if (client.workspaceId !== workspaceId)
+                continue;
+            this.write(client.reply, event);
+        }
+    }
+    broadcast(event) {
+        for (const client of this.clients) {
+            this.write(client.reply, event);
+        }
+    }
+    write(reply, event) {
+        try {
+            reply.raw.write(`data: ${JSON.stringify(event)}\n\n`);
+        }
+        catch (error) {
+            this.logger.warn({ err: error }, "Failed to write plugin SSE event");
+        }
+    }
+}

package/dist/plugins/handlers.js

@@ -0,0 +1,17 @@
+export function handlePluginEvent(workspaceId, event, deps) {
+    switch (event.type) {
+        case "codenomad.pong":
+            deps.logger.debug({ workspaceId, properties: event.properties }, "Plugin pong received");
+            return;
+        default:
+            deps.logger.debug({ workspaceId, eventType: event.type }, "Unhandled plugin event");
+    }
+}
+export function buildPingEvent() {
+    return {
+        type: "codenomad.ping",
+        properties: {
+            ts: Date.now(),
+        },
+    };
+}

package/dist/server/http-server.js

@@ -11,6 +11,9 @@ import { registerFilesystemRoutes } from "./routes/filesystem";
 import { registerMetaRoutes } from "./routes/meta";
 import { registerEventRoutes } from "./routes/events";
 import { registerStorageRoutes } from "./routes/storage";
+import { registerPluginRoutes } from "./routes/plugin";
+import { registerBackgroundProcessRoutes } from "./routes/background-processes";
+import { BackgroundProcessManager } from "../background-processes/manager";
 const DEFAULT_HTTP_PORT = 9898;
 export function createHttpServer(deps) {
     const app = Fastify({ logger: false });
@@ -63,6 +66,11 @@ export function createHttpServer(deps) {
             headersTimeout: 0,
         },
     });
+    const backgroundProcessManager = new BackgroundProcessManager({
+        workspaceManager: deps.workspaceManager,
+        eventBus: deps.eventBus,
+        logger: deps.logger.child({ component: "background-processes" }),
+    });
     registerWorkspaceRoutes(app, { workspaceManager: deps.workspaceManager });
     registerConfigRoutes(app, { configStore: deps.configStore, binaryRegistry: deps.binaryRegistry });
     registerFilesystemRoutes(app, { fileSystemBrowser: deps.fileSystemBrowser });
@@ -73,6 +81,8 @@ export function createHttpServer(deps) {
         eventBus: deps.eventBus,
         workspaceManager: deps.workspaceManager,
     });
+    registerPluginRoutes(app, { workspaceManager: deps.workspaceManager, eventBus: deps.eventBus, logger: proxyLogger });
+    registerBackgroundProcessRoutes(app, { backgroundProcessManager });
     registerInstanceProxyRoutes(app, { workspaceManager: deps.workspaceManager, logger: proxyLogger });
     if (deps.uiDevServerUrl) {
         setupDevProxy(app, deps.uiDevServerUrl);

package/dist/server/routes/background-processes.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+const StartSchema = z.object({
+    title: z.string().trim().min(1),
+    command: z.string().trim().min(1),
+});
+const OutputQuerySchema = z.object({
+    method: z.enum(["full", "tail", "head", "grep"]).optional(),
+    mode: z.enum(["full", "tail", "head", "grep"]).optional(),
+    pattern: z.string().optional(),
+    lines: z.coerce.number().int().positive().max(2000).optional(),
+    maxBytes: z.coerce.number().int().positive().optional(),
+});
+export function registerBackgroundProcessRoutes(app, deps) {
+    app.get("/workspaces/:id/plugin/background-processes", async (request) => {
+        const processes = await deps.backgroundProcessManager.list(request.params.id);
+        return { processes };
+    });
+    app.post("/workspaces/:id/plugin/background-processes", async (request, reply) => {
+        const payload = StartSchema.parse(request.body ?? {});
+        const process = await deps.backgroundProcessManager.start(request.params.id, payload.title, payload.command);
+        reply.code(201);
+        return process;
+    });
+    app.post("/workspaces/:id/plugin/background-processes/:processId/stop", async (request, reply) => {
+        const process = await deps.backgroundProcessManager.stop(request.params.id, request.params.processId);
+        if (!process) {
+            reply.code(404);
+            return { error: "Process not found" };
+        }
+        return process;
+    });
+    app.post("/workspaces/:id/plugin/background-processes/:processId/terminate", async (request, reply) => {
+        await deps.backgroundProcessManager.terminate(request.params.id, request.params.processId);
+        reply.code(204);
+        return undefined;
+    });
+    app.get("/workspaces/:id/plugin/background-processes/:processId/output", async (request, reply) => {
+        const query = OutputQuerySchema.parse(request.query ?? {});
+        const method = query.method ?? query.mode;
+        if (method === "grep" && !query.pattern) {
+            reply.code(400);
+            return { error: "Pattern is required for grep output" };
+        }
+        try {
+            return await deps.backgroundProcessManager.readOutput(request.params.id, request.params.processId, {
+                method,
+                pattern: query.pattern,
+                lines: query.lines,
+                maxBytes: query.maxBytes,
+            });
+        }
+        catch (error) {
+            reply.code(400);
+            return { error: error instanceof Error ? error.message : "Invalid output request" };
+        }
+    });
+    app.get("/workspaces/:id/plugin/background-processes/:processId/stream", async (request, reply) => {
+        await deps.backgroundProcessManager.streamOutput(request.params.id, request.params.processId, reply);
+    });
+}