@usezombie/zombiectl 0.3.0

package/src/lib/agent-loop.js

@@ -0,0 +1,106 @@
+import { streamFetch, authHeaders } from "./http.js";
+import { executeTool } from "./tool-executors.js";
+
+const MAX_TOOL_CALLS = 10;
+const MAX_WALL_MS = 30000;
+
+const TOOL_DEFINITIONS = [
+  {
+    name: "read_file",
+    description: "Read a file from the user's repo",
+    input_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+  },
+  {
+    name: "list_dir",
+    description: "List directory contents",
+    input_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+  },
+  {
+    name: "glob",
+    description: "Find files matching a glob pattern",
+    input_schema: { type: "object", properties: { pattern: { type: "string" } }, required: ["pattern"] },
+  },
+];
+
+/**
+ * Run the agent tool-call loop.
+ * POST messages + tools → receive SSE → execute tool_use locally → POST again → repeat.
+ *
+ * @param {string} endpoint - API path (e.g., "/v1/workspaces/{id}/spec/template")
+ * @param {string} userMessage - Initial user message
+ * @param {string} repoRoot - Absolute path to repo root
+ * @param {object} ctx - CLI context (apiUrl, token, etc.)
+ * @param {object} callbacks - { onToolCall, onText, onDone, onError }
+ * @returns {Promise<{text: string, usage: object|null, toolCalls: number, wallMs: number}>}
+ */
+export async function agentLoop(endpoint, userMessage, repoRoot, ctx, callbacks = {}) {
+  const baseUrl = ctx.apiUrl;
+  const headers = authHeaders({ token: ctx.token, apiKey: ctx.apiKey });
+  const url = `${baseUrl}${endpoint}`;
+
+  let messages = [{ role: "user", content: userMessage }];
+  let toolCalls = 0;
+  let accumulatedText = "";
+  let lastUsage = null;
+  const startTime = Date.now();
+
+  while (toolCalls < MAX_TOOL_CALLS && (Date.now() - startTime) < MAX_WALL_MS) {
+    const payload = { messages, tools: TOOL_DEFINITIONS };
+    let pendingToolUses = [];
+    let gotDone = false;
+
+    await streamFetch(url, payload, headers, (event) => {
+      switch (event.type) {
+        case "tool_use":
+          pendingToolUses.push(event.data);
+          break;
+        case "text_delta":
+          if (event.data?.text) {
+            accumulatedText += event.data.text;
+            callbacks.onText?.(event.data.text);
+          }
+          break;
+        case "done":
+          lastUsage = event.data?.usage ?? null;
+          gotDone = true;
+          callbacks.onDone?.(event.data);
+          break;
+        case "error":
+          callbacks.onError?.(event.data?.message ?? "unknown error");
+          break;
+      }
+    }, { fetchImpl: ctx.fetchImpl, timeoutMs: MAX_WALL_MS - (Date.now() - startTime) });
+
+    // If no tool calls, we're done
+    if (pendingToolUses.length === 0 || gotDone) break;
+
+    // Execute tool calls locally and build next message batch
+    for (const tc of pendingToolUses) {
+      toolCalls++;
+      callbacks.onToolCall?.(tc);
+      const result = executeTool(tc.name, tc.input, repoRoot);
+
+      // Append assistant tool_use + user tool_result to message history
+      messages.push({
+        role: "assistant",
+        content: JSON.stringify([{ type: "tool_use", id: tc.id, name: tc.name, input: tc.input }]),
+      });
+      messages.push({
+        role: "user",
+        content: JSON.stringify([{ type: "tool_result", tool_use_id: tc.id, content: result }]),
+      });
+    }
+
+    if (toolCalls >= MAX_TOOL_CALLS) {
+      callbacks.onError?.(`max tool calls reached (${MAX_TOOL_CALLS})`);
+      break;
+    }
+  }
+
+  const wallMs = Date.now() - startTime;
+  if (wallMs >= MAX_WALL_MS && !accumulatedText) {
+    callbacks.onError?.("wall time exceeded (30s)");
+  }
+
+  return { text: accumulatedText, usage: lastUsage, toolCalls, wallMs };
+}

package/src/lib/analytics.js

@@ -0,0 +1,114 @@
+const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+const DEFAULT_POSTHOG_KEY = [
+  "phc_XmuRIXBST",
+  "Rfxka7IgfkU0V",
+  "PMD3LDRR3IqIL",
+  "XNg3bXzv",
+].join("");
+
+function boolFromEnv(value, fallback) {
+  if (value == null || value === "") return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  return !(normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no");
+}
+
+function resolveConfig(env = process.env) {
+  const key = env.ZOMBIE_POSTHOG_KEY || DEFAULT_POSTHOG_KEY;
+  const host = env.ZOMBIE_POSTHOG_HOST || DEFAULT_POSTHOG_HOST;
+  const enabled = boolFromEnv(env.ZOMBIE_POSTHOG_ENABLED, key.length > 0);
+  return { key, host, enabled };
+}
+
+function sanitizeProperties(properties = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (value === undefined || value === null) continue;
+    out[key] = String(value);
+  }
+  return out;
+}
+
+export async function createCliAnalytics(env = process.env) {
+  const cfg = resolveConfig(env);
+  if (!cfg.enabled || !cfg.key) return null;
+
+  try {
+    const loaded = await import("posthog-node");
+    const PostHogCtor = loaded.PostHog || loaded.default;
+    const client = new PostHogCtor(cfg.key, {
+      host: cfg.host,
+      flushAt: 1,
+      flushInterval: 0,
+    });
+    return client;
+  } catch {
+    return null;
+  }
+}
+
+export function trackCliEvent(client, distinctId, event, properties = {}) {
+  if (!client) return;
+  try {
+    client.capture({
+      distinctId: distinctId || "anonymous",
+      event,
+      properties: sanitizeProperties(properties),
+    });
+  } catch {
+    // Telemetry must never block or break CLI UX.
+  }
+}
+
+export function setCliAnalyticsContext(ctx, properties = {}) {
+  if (!ctx) return;
+  const current = ctx.analyticsContext || {};
+  ctx.analyticsContext = {
+    ...current,
+    ...sanitizeProperties(properties),
+  };
+}
+
+export function getCliAnalyticsContext(ctx) {
+  return ctx?.analyticsContext ? { ...ctx.analyticsContext } : {};
+}
+
+export function queueCliAnalyticsEvent(ctx, event, properties = {}) {
+  if (!ctx) return;
+  if (!Array.isArray(ctx.analyticsEvents)) ctx.analyticsEvents = [];
+  ctx.analyticsEvents.push({
+    event,
+    properties: sanitizeProperties(properties),
+  });
+}
+
+export function drainCliAnalyticsEvents(ctx) {
+  if (!ctx || !Array.isArray(ctx.analyticsEvents) || ctx.analyticsEvents.length === 0) return [];
+  const events = ctx.analyticsEvents.slice();
+  ctx.analyticsEvents = [];
+  return events;
+}
+
+export async function shutdownCliAnalytics(client) {
+  if (!client) return;
+  try {
+    await client.shutdown();
+  } catch {
+    // ignore shutdown failures
+  }
+}
+
+export const cliAnalyticsInternals = {
+  DEFAULT_POSTHOG_KEY,
+  drainCliAnalyticsEvents,
+  getCliAnalyticsContext,
+  queueCliAnalyticsEvent,
+  resolveConfig,
+  sanitizeProperties,
+  setCliAnalyticsContext,
+};
+
+export const cliAnalytics = {
+  createCliAnalytics,
+  trackCliEvent,
+  shutdownCliAnalytics,
+};

package/src/lib/api-paths.js

@@ -0,0 +1,2 @@
+export const AGENTS_PATH = "/v1/agents/";
+export const WORKSPACES_PATH = "/v1/workspaces/";

package/src/lib/browser.js

@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+
+function browserDisabled(env) {
+  const raw = env.BROWSER;
+  if (raw == null) return false;
+  const normalized = String(raw).trim().toLowerCase();
+  return normalized === "false" || normalized === "0" || normalized === "off" || normalized === "none";
+}
+
+function hasDisplay(env) {
+  return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+
+function isSsh(env) {
+  return Boolean(env.SSH_CLIENT || env.SSH_TTY || env.SSH_CONNECTION);
+}
+
+function looksLikeWsl(env) {
+  const release = `${env.WSL_DISTRO_NAME || ""}${env.WSL_INTEROP || ""}${env.OSTYPE || ""}`.toLowerCase();
+  return release.includes("wsl");
+}
+
+function commandExists(command) {
+  return new Promise((resolve) => {
+    const probe = spawn("sh", ["-lc", `command -v ${command} >/dev/null 2>&1`], {
+      stdio: "ignore",
+    });
+    probe.on("exit", (code) => resolve(code === 0));
+    probe.on("error", () => resolve(false));
+  });
+}
+
+export async function resolveBrowserCommand(env = process.env, platform = process.platform) {
+  if (browserDisabled(env)) {
+    return { argv: null, reason: "browser-disabled" };
+  }
+
+  if (platform === "win32") {
+    return { argv: ["cmd", "/c", "start", ""], quoteUrl: true, command: "cmd" };
+  }
+
+  if (platform === "darwin") {
+    return { argv: ["open"], quoteUrl: false, command: "open" };
+  }
+
+  if (platform === "linux") {
+    const wsl = looksLikeWsl(env);
+    if (wsl) {
+      if (await commandExists("wslview")) {
+        return { argv: ["wslview"], quoteUrl: false, command: "wslview" };
+      }
+      if (!hasDisplay(env)) {
+        return { argv: null, reason: "wsl-no-wslview" };
+      }
+    }
+
+    if (!hasDisplay(env)) {
+      return { argv: null, reason: isSsh(env) ? "ssh-no-display" : "no-display" };
+    }
+
+    if (await commandExists("xdg-open")) {
+      return { argv: ["xdg-open"], quoteUrl: false, command: "xdg-open" };
+    }
+
+    return { argv: null, reason: "missing-xdg-open" };
+  }
+
+  return { argv: null, reason: "unsupported-platform" };
+}
+
+export async function openUrl(url, opts = {}) {
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+
+  const resolved = await resolveBrowserCommand(env, platform);
+  if (!resolved.argv) return false;
+
+  return new Promise((resolve) => {
+    const argv = [...resolved.argv];
+    if (resolved.quoteUrl) {
+      argv.push(`"${url}"`);
+    } else {
+      argv.push(url);
+    }
+
+    const child = spawn(argv[0], argv.slice(1), {
+      detached: true,
+      stdio: "ignore",
+      windowsVerbatimArguments: resolved.quoteUrl === true,
+    });
+
+    child.on("error", () => resolve(false));
+    child.unref();
+    resolve(true);
+  });
+}

package/src/lib/http.js

@@ -0,0 +1,149 @@
+const DEFAULT_TIMEOUT_MS = 15000;
+
+export class ApiError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "ApiError";
+    this.status = details.status;
+    this.code = details.code;
+    this.requestId = details.requestId;
+    this.body = details.body;
+  }
+}
+
+export async function apiRequest(url, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new ApiError("fetch is unavailable", { code: "NO_FETCH" });
+  }
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+
+  try {
+    const res = await fetchImpl(url, {
+      method: options.method || "GET",
+      headers: options.headers || {},
+      body: options.body,
+      signal: ctrl.signal,
+    });
+
+    const text = await res.text();
+    let json = null;
+    if (text.length > 0) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+
+    if (!res.ok) {
+      const errorCode = json?.error?.code || `HTTP_${res.status}`;
+      const requestId = json?.error?.request_id ?? json?.request_id ?? null;
+      const message = json?.error?.message || res.statusText || "request failed";
+      throw new ApiError(message, {
+        status: res.status,
+        code: errorCode,
+        requestId,
+        body: json ?? text,
+      });
+    }
+
+    return json ?? {};
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new ApiError(`request timed out after ${timeoutMs}ms`, {
+        status: 408,
+        code: "TIMEOUT",
+      });
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * POST with SSE streaming response. Calls onEvent for each parsed SSE event.
+ * Returns when the stream ends or an error occurs.
+ */
+export async function streamFetch(url, payload, headers, onEvent, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 30000;
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { ...headers, "Content-Type": "application/json", "Accept": "text/event-stream" },
+      body: JSON.stringify(payload),
+      signal: ctrl.signal,
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      let json = null;
+      try { json = JSON.parse(text); } catch { /* ignore */ }
+      const errorCode = json?.error?.code || `HTTP_${res.status}`;
+      const message = json?.error?.message || res.statusText || "request failed";
+      throw new ApiError(message, { status: res.status, code: errorCode, body: json ?? text });
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+
+      let boundary;
+      while ((boundary = buf.indexOf("\n\n")) !== -1) {
+        const frame = buf.slice(0, boundary);
+        buf = buf.slice(boundary + 2);
+        const event = parseSseFrame(frame);
+        if (event) onEvent(event);
+      }
+    }
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new ApiError(`stream timed out after ${timeoutMs}ms`, { status: 408, code: "TIMEOUT" });
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function parseSseFrame(frame) {
+  let type = "message";
+  let data = "";
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("event: ")) type = line.slice(7);
+    else if (line.startsWith("data: ")) data = line.slice(6);
+    else if (line.startsWith(":")) continue; // comment/heartbeat
+  }
+  if (!data) return null;
+  try { return { type, data: JSON.parse(data) }; } catch { return { type, data }; }
+}
+
+export function authHeaders(auth) {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+
+    if (auth?.token) {
+        headers.Authorization = `Bearer ${auth.token}`;
+        return headers;
+    }
+
+    if (auth?.apiKey) {
+        headers.Authorization = `Bearer ${auth.apiKey}`;
+    }
+
+    return headers;
+}

package/src/lib/sse-parser.js

@@ -0,0 +1,50 @@
+/**
+ * Parse SSE frames from a text buffer.
+ * Returns { events: [...], remainder: string }.
+ * Each event has { type, data }.
+ */
+export function parseSseBuffer(buf) {
+  const events = [];
+  let remainder = buf;
+
+  while (true) {
+    const boundary = remainder.indexOf("\n\n");
+    if (boundary === -1) break;
+
+    const frame = remainder.slice(0, boundary);
+    remainder = remainder.slice(boundary + 2);
+
+    const event = parseSseFrame(frame);
+    if (event) events.push(event);
+  }
+
+  return { events, remainder };
+}
+
+/**
+ * Parse a single SSE frame (text between double newlines).
+ * Returns { type, data } or null if not a valid event.
+ */
+function parseSseFrame(frame) {
+  let type = "message";
+  let data = "";
+
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("event: ")) {
+      type = line.slice(7);
+    } else if (line.startsWith("data: ")) {
+      data = line.slice(6);
+    } else if (line.startsWith(":")) {
+      // Comment line (heartbeat), skip
+      continue;
+    }
+  }
+
+  if (!data) return null;
+
+  try {
+    return { type, data: JSON.parse(data) };
+  } catch {
+    return { type, data };
+  }
+}

package/src/lib/state.js

@@ -0,0 +1,67 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+function resolveStatePaths() {
+  const baseDir = process.env.ZOMBIE_STATE_DIR || path.join(os.homedir(), ".config", "zombiectl");
+  return {
+    baseDir,
+    credentialsPath: path.join(baseDir, "credentials.json"),
+    workspacesPath: path.join(baseDir, "workspaces.json"),
+  };
+}
+
+async function ensureBaseDir() {
+  const { baseDir } = resolveStatePaths();
+  await fs.mkdir(baseDir, { recursive: true });
+}
+
+async function readJson(filePath, fallback) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.name === "SyntaxError")) return fallback;
+    throw err;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await ensureBaseDir();
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  await fs.writeFile(filePath, body, { mode: 0o600 });
+}
+
+export function newIdempotencyKey() {
+  return randomBytes(12).toString("hex");
+}
+
+export async function loadCredentials() {
+  const { credentialsPath } = resolveStatePaths();
+  return readJson(credentialsPath, { token: null, saved_at: null, session_id: null, api_url: null });
+}
+
+export async function saveCredentials(next) {
+  const { credentialsPath } = resolveStatePaths();
+  await writeJson(credentialsPath, next);
+}
+
+export async function clearCredentials() {
+  const { credentialsPath } = resolveStatePaths();
+  await writeJson(credentialsPath, { token: null, saved_at: Date.now(), session_id: null, api_url: null });
+}
+
+export async function loadWorkspaces() {
+  const { workspacesPath } = resolveStatePaths();
+  return readJson(workspacesPath, { current_workspace_id: null, items: [] });
+}
+
+export async function saveWorkspaces(next) {
+  const { workspacesPath } = resolveStatePaths();
+  await writeJson(workspacesPath, next);
+}
+
+export const stateInternals = {
+  resolveStatePaths,
+};

package/src/lib/tool-executors.js

@@ -0,0 +1,110 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve, sep, relative } from "node:path";
+
+const MAX_GLOB_RESULTS = 500;
+const MAX_FILE_SIZE = 256 * 1024; // 256KB
+
+/**
+ * Validate that a resolved path is within the repo root.
+ * Returns { resolved } or { error }.
+ */
+export function validatePath(inputPath, repoRoot) {
+  const resolved = resolve(repoRoot, inputPath);
+  if (resolved !== repoRoot && !resolved.startsWith(repoRoot + sep)) {
+    return { error: "path outside repo root" };
+  }
+  return { resolved };
+}
+
+/**
+ * Execute a tool call locally. Returns the result string.
+ */
+export function executeTool(name, input, repoRoot) {
+  switch (name) {
+    case "read_file":
+      return executeReadFile(input.path, repoRoot);
+    case "list_dir":
+      return executeListDir(input.path, repoRoot);
+    case "glob":
+      return executeGlob(input.pattern, repoRoot);
+    default:
+      return `error: unknown tool "${name}"`;
+  }
+}
+
+function executeReadFile(path, repoRoot) {
+  const v = validatePath(path, repoRoot);
+  if (v.error) return `error: ${v.error}`;
+
+  try {
+    const stat = statSync(v.resolved);
+    if (stat.isDirectory()) return "error: path is a directory, use list_dir instead";
+    if (stat.size > MAX_FILE_SIZE) return `error: file too large (${stat.size} bytes, max ${MAX_FILE_SIZE})`;
+    return readFileSync(v.resolved, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return `error: file not found: ${path}`;
+    return `error: ${err.message}`;
+  }
+}
+
+function executeListDir(path, repoRoot) {
+  const v = validatePath(path || ".", repoRoot);
+  if (v.error) return `error: ${v.error}`;
+
+  try {
+    const entries = readdirSync(v.resolved, { withFileTypes: true });
+    return entries
+      .filter((e) => e.name !== ".git")
+      .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+      .sort()
+      .join("\n");
+  } catch (err) {
+    if (err.code === "ENOENT") return `error: directory not found: ${path}`;
+    return `error: ${err.message}`;
+  }
+}
+
+function micromatch(filePath, pattern) {
+  const regex = pattern
+    .replace(/\*\*\//g, "\x00/")
+    .replace(/\*\*/g, "\x01")
+    .replace(/\./g, "\\.")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, "[^/]")
+    .replace(/\x00\//g, "(?:.*/)?")
+    .replace(/\x01/g, ".*");
+  return new RegExp(`^${regex}$`).test(filePath);
+}
+
+function walkSync(dir, root, results, limit) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    if (results.length >= limit) return;
+    if (entry.name === ".git") continue;
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkSync(full, root, results, limit);
+    } else {
+      results.push(relative(root, full));
+    }
+  }
+}
+
+function executeGlob(pattern, repoRoot) {
+  try {
+    const allFiles = [];
+    walkSync(repoRoot, repoRoot, allFiles, MAX_GLOB_RESULTS * 10);
+    const results = [];
+    for (const f of allFiles) {
+      if (micromatch(f, pattern)) {
+        results.push(f);
+        if (results.length >= MAX_GLOB_RESULTS) break;
+      }
+    }
+    if (results.length === 0) return "(no matches)";
+    return results.sort().join("\n");
+  } catch (err) {
+    return `error: ${err.message}`;
+  }
+}