@hellcoder/companion 0.96.0

package/server/cron-store.ts

@@ -0,0 +1,148 @@
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  existsSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { CronJob, CronJobCreateInput } from "./cron-types.js";
+import { COMPANION_HOME } from "./paths.js";
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const CRON_DIR = join(COMPANION_HOME, "cron");
+
+function ensureDir(): void {
+  mkdirSync(CRON_DIR, { recursive: true });
+}
+
+function filePath(id: string): string {
+  return join(CRON_DIR, `${id}.json`);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+// ─── CRUD ───────────────────────────────────────────────────────────────────
+
+export function listJobs(): CronJob[] {
+  ensureDir();
+  try {
+    const files = readdirSync(CRON_DIR).filter((f) => f.endsWith(".json"));
+    const jobs: CronJob[] = [];
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(CRON_DIR, file), "utf-8");
+        jobs.push(JSON.parse(raw));
+      } catch {
+        // Skip corrupt files
+      }
+    }
+    jobs.sort((a, b) => a.name.localeCompare(b.name));
+    return jobs;
+  } catch {
+    return [];
+  }
+}
+
+export function getJob(id: string): CronJob | null {
+  ensureDir();
+  try {
+    const raw = readFileSync(filePath(id), "utf-8");
+    return JSON.parse(raw) as CronJob;
+  } catch {
+    return null;
+  }
+}
+
+export function createJob(data: CronJobCreateInput): CronJob {
+  if (!data.name || !data.name.trim()) throw new Error("Job name is required");
+  if (!data.prompt || !data.prompt.trim()) throw new Error("Job prompt is required");
+  if (!data.schedule || !data.schedule.trim()) throw new Error("Job schedule is required");
+  if (!data.cwd || !data.cwd.trim()) throw new Error("Job working directory is required");
+
+  const id = slugify(data.name.trim());
+  if (!id) throw new Error("Job name must contain alphanumeric characters");
+
+  ensureDir();
+  if (existsSync(filePath(id))) {
+    throw new Error(`A job with a similar name already exists ("${id}")`);
+  }
+
+  const now = Date.now();
+  const job: CronJob = {
+    ...data,
+    id,
+    name: data.name.trim(),
+    prompt: data.prompt.trim(),
+    schedule: data.schedule.trim(),
+    cwd: data.cwd.trim(),
+    createdAt: now,
+    updatedAt: now,
+    consecutiveFailures: 0,
+    totalRuns: 0,
+  };
+  writeFileSync(filePath(id), JSON.stringify(job, null, 2), "utf-8");
+  return job;
+}
+
+export function updateJob(
+  id: string,
+  updates: Partial<CronJob>,
+): CronJob | null {
+  ensureDir();
+  const existing = getJob(id);
+  if (!existing) return null;
+
+  const newName = updates.name?.trim() || existing.name;
+  const newId = slugify(newName);
+  if (!newId) throw new Error("Job name must contain alphanumeric characters");
+
+  // If name changed, check for slug collision with a different job
+  if (newId !== id && existsSync(filePath(newId))) {
+    throw new Error(`A job with a similar name already exists ("${newId}")`);
+  }
+
+  const job: CronJob = {
+    ...existing,
+    ...updates,
+    id: newId,
+    name: newName,
+    updatedAt: Date.now(),
+    // Preserve immutable fields
+    createdAt: existing.createdAt,
+  };
+
+  // If id changed, delete old file
+  if (newId !== id) {
+    try {
+      unlinkSync(filePath(id));
+    } catch {
+      /* ok */
+    }
+  }
+
+  writeFileSync(filePath(newId), JSON.stringify(job, null, 2), "utf-8");
+  return job;
+}
+
+export function deleteJob(id: string): boolean {
+  ensureDir();
+  if (!existsSync(filePath(id))) return false;
+  try {
+    unlinkSync(filePath(id));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/server/cron-types.ts

@@ -0,0 +1,63 @@
+// ─── Cron Job Types ────────────────────────────────────────────────────────
+
+export interface CronJob {
+  /** Unique slug-based ID (derived from name) */
+  id: string;
+  /** Human-readable job name */
+  name: string;
+  /** The prompt to send when the job fires */
+  prompt: string;
+  /** Cron expression (e.g. "0 8 * * *") or ISO datetime string for one-shot */
+  schedule: string;
+  /** true = recurring cron, false = one-shot at a specific time */
+  recurring: boolean;
+  /** Backend to use */
+  backendType: "claude" | "codex";
+  /** Model to use (e.g. "claude-sonnet-4-6") */
+  model: string;
+  /** Working directory for the session */
+  cwd: string;
+  /** Optional environment slug (references ~/.companion/envs/) */
+  envSlug?: string;
+  /** Whether the job is currently enabled */
+  enabled: boolean;
+  /** Permission mode — defaults to "bypassPermissions" for autonomy */
+  permissionMode: string;
+  /** Codex-only: enable internet access */
+  codexInternetAccess?: boolean;
+
+  // ── Tracking ──
+  createdAt: number;
+  updatedAt: number;
+  /** Last time this job was triggered */
+  lastRunAt?: number;
+  /** Session ID of the last execution */
+  lastSessionId?: string;
+  /** Number of consecutive failures */
+  consecutiveFailures: number;
+  /** Total number of runs */
+  totalRuns: number;
+}
+
+export interface CronJobExecution {
+  /** The session ID created for this execution */
+  sessionId: string;
+  /** The job ID that triggered this */
+  jobId: string;
+  /** When the execution started */
+  startedAt: number;
+  /** When the execution completed (result received) */
+  completedAt?: number;
+  /** Whether the execution succeeded */
+  success?: boolean;
+  /** Error message if it failed */
+  error?: string;
+  /** Cost in USD */
+  costUsd?: number;
+}
+
+/** Input for creating a cron job (without auto-generated fields) */
+export type CronJobCreateInput = Omit<
+  CronJob,
+  "id" | "createdAt" | "updatedAt" | "consecutiveFailures" | "totalRuns" | "lastRunAt" | "lastSessionId"
+>;

package/server/env-manager.test.ts

@@ -0,0 +1,268 @@
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let tempDir: string;
+let envManager: typeof import("./env-manager.js");
+
+const mockHomedir = vi.hoisted(() => {
+  let dir = "";
+  return {
+    get: () => dir,
+    set: (d: string) => {
+      dir = d;
+    },
+  };
+});
+
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return {
+    ...actual,
+    homedir: () => mockHomedir.get(),
+  };
+});
+
+beforeEach(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), "env-test-"));
+  mockHomedir.set(tempDir);
+  vi.resetModules();
+  envManager = await import("./env-manager.js");
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Helper to get the envs directory path used by the module
+// ---------------------------------------------------------------------------
+function envsDir(): string {
+  return join(tempDir, ".companion", "envs");
+}
+
+// ===========================================================================
+// Slugification (tested indirectly via createEnv)
+// ===========================================================================
+describe("slugification via createEnv", () => {
+  it("converts spaces to hyphens and lowercases", async () => {
+    const env = envManager.createEnv("My App");
+    expect(env.slug).toBe("my-app");
+  });
+
+  it("strips special characters", async () => {
+    const env = envManager.createEnv("Hello World! @#$%");
+    expect(env.slug).toBe("hello-world");
+  });
+
+  it("collapses consecutive hyphens", async () => {
+    const env = envManager.createEnv("a   ---  b");
+    expect(env.slug).toBe("a-b");
+  });
+
+  it("trims leading and trailing hyphens", async () => {
+    const env = envManager.createEnv(" -cool env- ");
+    expect(env.slug).toBe("cool-env");
+  });
+
+  it("throws when name is empty string", () => {
+    expect(() => envManager.createEnv("")).toThrow("Environment name is required");
+  });
+
+  it("throws when name is only whitespace", () => {
+    expect(() => envManager.createEnv("   ")).toThrow("Environment name is required");
+  });
+
+  it("throws when name contains no alphanumeric characters", () => {
+    expect(() => envManager.createEnv("@#$%^&")).toThrow(
+      "Environment name must contain alphanumeric characters",
+    );
+  });
+});
+
+// ===========================================================================
+// listEnvs
+// ===========================================================================
+describe("listEnvs", () => {
+  it("returns empty array when no envs exist", () => {
+    const result = envManager.listEnvs();
+    expect(result).toEqual([]);
+  });
+
+  it("returns envs sorted alphabetically by name", () => {
+    envManager.createEnv("Zebra");
+    envManager.createEnv("Alpha");
+    envManager.createEnv("Mango");
+
+    const result = envManager.listEnvs();
+    expect(result.map((e) => e.name)).toEqual(["Alpha", "Mango", "Zebra"]);
+  });
+
+  it("skips corrupt JSON files", () => {
+    // Create a valid env first
+    envManager.createEnv("Valid");
+
+    // Write a corrupt file directly into the envs directory
+    writeFileSync(join(envsDir(), "corrupt.json"), "NOT VALID JSON{{{", "utf-8");
+
+    const result = envManager.listEnvs();
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe("Valid");
+  });
+});
+
+// ===========================================================================
+// getEnv
+// ===========================================================================
+describe("getEnv", () => {
+  it("returns the env when it exists", () => {
+    envManager.createEnv("My Service", { PORT: "3000" });
+
+    const result = envManager.getEnv("my-service");
+    expect(result).not.toBeNull();
+    expect(result!.name).toBe("My Service");
+    expect(result!.slug).toBe("my-service");
+    expect(result!.variables).toEqual({ PORT: "3000" });
+  });
+
+  it("returns null when the env does not exist", () => {
+    const result = envManager.getEnv("nonexistent");
+    expect(result).toBeNull();
+  });
+});
+
+// ===========================================================================
+// createEnv
+// ===========================================================================
+describe("createEnv", () => {
+  it("returns an env with correct structure and timestamps", () => {
+    const before = Date.now();
+    const env = envManager.createEnv("Production", { NODE_ENV: "production" });
+    const after = Date.now();
+
+    expect(env.name).toBe("Production");
+    expect(env.slug).toBe("production");
+    expect(env.variables).toEqual({ NODE_ENV: "production" });
+    expect(env.createdAt).toBeGreaterThanOrEqual(before);
+    expect(env.createdAt).toBeLessThanOrEqual(after);
+    expect(env.updatedAt).toBe(env.createdAt);
+  });
+
+  it("persists the env to disk as JSON", () => {
+    envManager.createEnv("Disk Check");
+
+    const raw = readFileSync(join(envsDir(), "disk-check.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    expect(parsed.name).toBe("Disk Check");
+    expect(parsed.slug).toBe("disk-check");
+  });
+
+  it("defaults variables to empty object", () => {
+    const env = envManager.createEnv("No Vars");
+    expect(env.variables).toEqual({});
+  });
+
+  it("throws when creating a duplicate slug", () => {
+    envManager.createEnv("My App");
+    expect(() => envManager.createEnv("My App")).toThrow(
+      'An environment with a similar name already exists ("my-app")',
+    );
+  });
+
+  it("trims the name before saving", () => {
+    const env = envManager.createEnv("  Spaced Out  ");
+    expect(env.name).toBe("Spaced Out");
+    expect(env.slug).toBe("spaced-out");
+  });
+});
+
+// ===========================================================================
+// updateEnv
+// ===========================================================================
+describe("updateEnv", () => {
+  it("updates name and variables", () => {
+    envManager.createEnv("Original", { KEY: "old" });
+
+    const updated = envManager.updateEnv("original", {
+      name: "Renamed",
+      variables: { KEY: "new" },
+    });
+
+    expect(updated).not.toBeNull();
+    expect(updated!.name).toBe("Renamed");
+    expect(updated!.slug).toBe("renamed");
+    expect(updated!.variables).toEqual({ KEY: "new" });
+  });
+
+  it("renames the file on disk when slug changes", () => {
+    envManager.createEnv("Old Name");
+
+    envManager.updateEnv("old-name", { name: "New Name" });
+
+    // Old file should be gone, new file should exist
+    const oldPath = join(envsDir(), "old-name.json");
+    const newPath = join(envsDir(), "new-name.json");
+
+    expect(() => readFileSync(oldPath, "utf-8")).toThrow();
+    const parsed = JSON.parse(readFileSync(newPath, "utf-8"));
+    expect(parsed.name).toBe("New Name");
+    expect(parsed.slug).toBe("new-name");
+  });
+
+  it("throws on slug collision during rename", () => {
+    envManager.createEnv("Alpha");
+    envManager.createEnv("Beta");
+
+    expect(() => envManager.updateEnv("alpha", { name: "Beta" })).toThrow(
+      'An environment with a similar name already exists ("beta")',
+    );
+  });
+
+  it("returns null for a non-existent slug", () => {
+    const result = envManager.updateEnv("ghost", { name: "New" });
+    expect(result).toBeNull();
+  });
+
+  it("preserves createdAt and advances updatedAt", async () => {
+    const env = envManager.createEnv("Timestamps");
+    const originalCreatedAt = env.createdAt;
+
+    // Small delay to ensure Date.now() advances
+    await new Promise((r) => setTimeout(r, 10));
+
+    const updated = envManager.updateEnv("timestamps", { variables: { A: "1" } });
+
+    expect(updated).not.toBeNull();
+    expect(updated!.createdAt).toBe(originalCreatedAt);
+    expect(updated!.updatedAt).toBeGreaterThan(originalCreatedAt);
+  });
+
+  it("keeps existing variables when only name is updated", () => {
+    envManager.createEnv("Keep Vars", { SECRET: "abc" });
+
+    const updated = envManager.updateEnv("keep-vars", { name: "Kept Vars" });
+    expect(updated!.variables).toEqual({ SECRET: "abc" });
+  });
+});
+
+// Docker-related tests (getEffectiveImage, updateBuildStatus, createEnv with docker options)
+// have been moved to sandbox-manager.test.ts as part of the sandbox/environment separation.
+
+// ===========================================================================
+// deleteEnv
+// ===========================================================================
+describe("deleteEnv", () => {
+  it("deletes an existing env and returns true", () => {
+    envManager.createEnv("To Delete");
+    const result = envManager.deleteEnv("to-delete");
+    expect(result).toBe(true);
+
+    // Confirm it is gone
+    expect(envManager.getEnv("to-delete")).toBeNull();
+  });
+
+  it("returns false when the env does not exist", () => {
+    const result = envManager.deleteEnv("missing");
+    expect(result).toBe(false);
+  });
+});

package/server/env-manager.ts

@@ -0,0 +1,161 @@
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  existsSync,
+} from "node:fs";
+import { join } from "node:path";
+import { COMPANION_HOME } from "./paths.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface CompanionEnv {
+  name: string;
+  slug: string;
+  variables: Record<string, string>;
+
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Fields that can be updated via the update API */
+export interface EnvUpdateFields {
+  name?: string;
+  variables?: Record<string, string>;
+}
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const ENVS_DIR = join(COMPANION_HOME, "envs");
+
+function ensureDir(): void {
+  mkdirSync(ENVS_DIR, { recursive: true });
+}
+
+/** Validate that a slug contains only safe characters (prevents path traversal) */
+function validateSlug(slug: string): void {
+  if (!/^[a-z0-9-]+$/.test(slug)) {
+    throw new Error("Invalid slug: must contain only lowercase alphanumeric characters and hyphens");
+  }
+}
+
+function filePath(slug: string): string {
+  validateSlug(slug);
+  return join(ENVS_DIR, `${slug}.json`);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+// ─── CRUD ───────────────────────────────────────────────────────────────────
+
+export function listEnvs(): CompanionEnv[] {
+  ensureDir();
+  try {
+    const files = readdirSync(ENVS_DIR).filter((f) => f.endsWith(".json"));
+    const envs: CompanionEnv[] = [];
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(ENVS_DIR, file), "utf-8");
+        envs.push(JSON.parse(raw));
+      } catch {
+        // Skip corrupt files
+      }
+    }
+    envs.sort((a, b) => a.name.localeCompare(b.name));
+    return envs;
+  } catch {
+    return [];
+  }
+}
+
+export function getEnv(slug: string): CompanionEnv | null {
+  ensureDir();
+  try {
+    const raw = readFileSync(filePath(slug), "utf-8");
+    return JSON.parse(raw) as CompanionEnv;
+  } catch {
+    return null;
+  }
+}
+
+export function createEnv(
+  name: string,
+  variables: Record<string, string> = {},
+): CompanionEnv {
+  if (!name || !name.trim()) throw new Error("Environment name is required");
+  const slug = slugify(name.trim());
+  if (!slug) throw new Error("Environment name must contain alphanumeric characters");
+
+  ensureDir();
+  if (existsSync(filePath(slug))) {
+    throw new Error(`An environment with a similar name already exists ("${slug}")`);
+  }
+
+  const now = Date.now();
+  const env: CompanionEnv = {
+    name: name.trim(),
+    slug,
+    variables,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  writeFileSync(filePath(slug), JSON.stringify(env, null, 2), "utf-8");
+  return env;
+}
+
+export function updateEnv(
+  slug: string,
+  updates: EnvUpdateFields,
+): CompanionEnv | null {
+  ensureDir();
+  const existing = getEnv(slug);
+  if (!existing) return null;
+
+  const newName = updates.name?.trim() || existing.name;
+  const newSlug = slugify(newName);
+  if (!newSlug) throw new Error("Environment name must contain alphanumeric characters");
+
+  // If name changed, check for slug collision with a different env
+  if (newSlug !== slug && existsSync(filePath(newSlug))) {
+    throw new Error(`An environment with a similar name already exists ("${newSlug}")`);
+  }
+
+  const env: CompanionEnv = {
+    ...existing,
+    name: newName,
+    slug: newSlug,
+    variables: updates.variables ?? existing.variables,
+    updatedAt: Date.now(),
+  };
+
+  // If slug changed, delete old file
+  if (newSlug !== slug) {
+    try { unlinkSync(filePath(slug)); } catch { /* ok */ }
+  }
+
+  writeFileSync(filePath(newSlug), JSON.stringify(env, null, 2), "utf-8");
+  return env;
+}
+
+export function deleteEnv(slug: string): boolean {
+  ensureDir();
+  if (!existsSync(filePath(slug))) return false;
+  try {
+    unlinkSync(filePath(slug));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/server/event-bus-types.ts

@@ -0,0 +1,64 @@
+// Typed event map for the Companion internal event bus.
+// Each key is a namespaced event name; values are the payload passed to handlers.
+
+import type { BrowserIncomingMessage } from "./session-types.js";
+import type { CodexAdapter } from "./codex-adapter.js";
+import type { SessionPhase } from "./session-state-machine.js";
+
+export interface CompanionEventMap {
+  // ── Session lifecycle ──────────────────────────────────────────────
+
+  /** CLI reported its internal session ID (used for --resume). */
+  "session:cli-id-received": { sessionId: string; cliSessionId: string };
+
+  /** CLI/Codex process exited. */
+  "session:exited": { sessionId: string; exitCode: number | null };
+
+  /** CLI WebSocket disconnected and a browser needs a relaunch. */
+  "session:relaunch-needed": { sessionId: string };
+
+  /** Idle-kill threshold reached with no connected browsers. */
+  "session:idle-kill": { sessionId: string };
+
+  /** First non-error turn completed (triggers auto-naming). */
+  "session:first-turn-completed": {
+    sessionId: string;
+    firstUserMessage: string;
+  };
+
+  /** Git info resolved for a session (branch and cwd known). */
+  "session:git-info-ready": { sessionId: string; cwd: string; branch: string };
+
+  /** Session phase changed (formal state machine transition). */
+  "session:phase-changed": {
+    sessionId: string;
+    from: SessionPhase;
+    to: SessionPhase;
+    trigger: string;
+  };
+
+  // ── Backend integration ────────────────────────────────────────────
+
+  /** Codex adapter created and ready to be attached to WsBridge. */
+  "backend:codex-adapter-created": {
+    sessionId: string;
+    adapter: CodexAdapter;
+  };
+
+  // ── Per-session messages (high volume) ─────────────────────────────
+
+  /** An assistant message was processed and broadcast to browsers. */
+  "message:assistant": {
+    sessionId: string;
+    message: BrowserIncomingMessage;
+  };
+
+  /** A stream event was processed and broadcast to browsers. */
+  "message:stream_event": {
+    sessionId: string;
+    message: BrowserIncomingMessage;
+  };
+
+  /** A result (turn completion) was processed and broadcast to browsers. */
+  "message:result": { sessionId: string; message: BrowserIncomingMessage };
+}