@kky42/pievo-server 1.0.0

package/drizzle/meta/_journal.json

@@ -0,0 +1,69 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1783393995571,
+      "tag": "0000_round_marauders",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1783417162251,
+      "tag": "0001_naive_silver_fox",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1783502268448,
+      "tag": "0002_funny_sage",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1784459031460,
+      "tag": "0003_optimal_slapstick",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1784466600000,
+      "tag": "0004_remove_grok_agent",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1784480337337,
+      "tag": "0005_heavy_gauntlet",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1784482476327,
+      "tag": "0006_tranquil_sharon_carter",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1784529980417,
+      "tag": "0007_faulty_starbolt",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1784530000000,
+      "tag": "0008_durable_lifecycle_evidence",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@kky42/pievo-server",
+  "version": "1.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kky42/pievo.git",
+    "directory": "packages/server"
+  },
+  "type": "module",
+  "description": "Pievo server — a self-hostable zero-exec control plane for scheduled agent loops.",
+  "bin": {
+    "pievo-server": "scripts/pievo-server.mjs"
+  },
+  "files": [
+    ".output",
+    "drizzle",
+    "scripts/pievo-server.mjs",
+    "scripts/server-cli-lib.mjs",
+    "scripts/prestart.mjs",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && node scripts/copy-pglite-assets.mjs",
+    "build:publish": "vite build && node scripts/copy-pglite-assets.mjs --strict",
+    "start": "node scripts/prestart.mjs && node .output/server/index.mjs",
+    "routes:generate": "tsr generate",
+    "typecheck": "tsr generate && tsc --noEmit",
+    "test": "vitest run",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "verify:package": "node scripts/verify-package.mjs",
+    "prepublishOnly": "pnpm build:publish"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1075.0",
+    "@base-ui/react": "^1.6.0",
+    "@electric-sql/pglite": "^0.5.4",
+    "@codemirror/lang-html": "^6.4.11",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@lezer/highlight": "^1.2.3",
+    "@tanstack/react-router": "^1.170.16",
+    "@tanstack/react-start": "^1.168.26",
+    "@uiw/codemirror-themes": "^4.25.10",
+    "@uiw/react-codemirror": "^4.25.10",
+    "better-auth": "^1.6.19",
+    "croner": "^10.0.1",
+    "diff": "^9.0.0",
+    "dompurify": "^3.4.11",
+    "drizzle-orm": "^0.45.2",
+    "html-react-parser": "^6.1.3",
+    "marked": "^18.0.5",
+    "postgres": "^3.4.9",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "recharts": "^3.9.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.1",
+    "@tanstack/react-router-devtools": "^1.167.0",
+    "@tanstack/router-cli": "1.167.17",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "drizzle-kit": "^0.31.10",
+    "jsdom": "^29.1.1",
+    "nitro": "3.0.260610-beta",
+    "tailwindcss": "^4.3.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  }
+}

package/scripts/pievo-server.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  acquireStartLock,
+  acquireStartLockEventually,
+  buildEnvPlan,
+  buildRestartPlan,
+  clearPidRecord,
+  parseArgs,
+  pidStatus,
+  processStartTime,
+  readinessReady,
+  readPidRecord,
+  recordedProcessState,
+  terminateRecordedProcess,
+  updatePidRecordState,
+  usage,
+  waitFor,
+  withLaunchNonce,
+  writePidRecord,
+} from "./server-cli-lib.mjs";
+
+const scriptFile = fileURLToPath(import.meta.url);
+const packageRoot = path.resolve(path.dirname(scriptFile), "..");
+const READY_TIMEOUT_MS = 60_000;
+const DETACHED_LAUNCH_TIMEOUT_MS = 120_000;
+const STOP_TIMEOUT_MS = 10_000;
+const FORCE_STOP_TIMEOUT_MS = 2_000;
+const LOCK_HANDOFF_TIMEOUT_MS = 5_000;
+
+function installShutdown(plan, expected) {
+  let stopping = false;
+  let stopSignal;
+  let prestartChild;
+  let nitroLoaded = false;
+  let replayedForNitro = false;
+
+  const shutdownApplication = () => {
+    const booted = globalThis.__pievoBooted;
+    if (!booted) return;
+    void Promise.resolve(booted)
+      .then((value) => value.shutdown())
+      .catch((error) => console.error(`[pievo-server] application shutdown failed: ${error instanceof Error ? error.message : error}`));
+  };
+
+  const onSignal = (signal) => {
+    if (!stopping) {
+      stopping = true;
+      stopSignal = signal;
+      console.log(`[pievo-server] received ${signal}; shutting down`);
+      shutdownApplication();
+      if (prestartChild?.exitCode === null && prestartChild?.signalCode === null) {
+        try { prestartChild.kill(signal); } catch {}
+      }
+    }
+  };
+
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  // This process is authoritative for its own clean exit. SIGKILL cannot run this
+  // hook, so an external stopper still has to prove death before clearing.
+  process.on("exit", () => clearPidRecord(plan.pidFile, expected));
+
+  return {
+    get stopping() { return stopping; },
+    trackPrestart(child) { prestartChild = child; },
+    clearPrestart(child) { if (prestartChild === child) prestartChild = undefined; },
+    nitroLoaded() {
+      nitroLoaded = true;
+      // If the first signal arrived while Nitro was importing, its graceful HTTP
+      // handler did not see it. Replay once after srvx has installed that handler.
+      if (stopping && !replayedForNitro) {
+        replayedForNitro = true;
+        setImmediate(() => {
+          try { process.kill(process.pid, stopSignal ?? "SIGTERM"); } catch {}
+        });
+      }
+    },
+    requestShutdown(signal = "SIGTERM") {
+      onSignal(signal);
+      if (nitroLoaded && !replayedForNitro) {
+        replayedForNitro = true;
+        setImmediate(() => {
+          try { process.kill(process.pid, signal); } catch {}
+        });
+      }
+    },
+  };
+}
+
+async function runPrestart(plan, shutdown) {
+  const child = spawn(process.execPath, [path.join(packageRoot, "scripts", "prestart.mjs")], {
+    cwd: packageRoot,
+    env: plan.env,
+    stdio: "inherit",
+  });
+  shutdown.trackPrestart(child);
+  try {
+    const result = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+    });
+    if (shutdown.stopping) throw new Error("startup interrupted by shutdown signal");
+    if (result.code !== 0) {
+      throw new Error(`migration prestart failed (${result.signal ? `signal ${result.signal}` : `exit ${result.code ?? "unknown"}`})`);
+    }
+  } finally {
+    shutdown.clearPrestart(child);
+  }
+}
+
+async function waitForPidAuthority(plan, expected, shutdown) {
+  return waitFor(() => {
+    if (shutdown.stopping) return true;
+    const current = readPidRecord(plan.pidFile);
+    return current?.pid === expected.pid
+      && current.startTime === expected.startTime
+      && current.launchNonce === expected.launchNonce;
+  }, 5_000);
+}
+
+async function serve(plan, expected) {
+  // Signal handling comes first: startup remains controllable while waiting for
+  // the parent record and while the async migration child is running.
+  const shutdown = installShutdown(plan, expected);
+  if (!(await waitForPidAuthority(plan, expected, shutdown))) {
+    throw new Error("launcher did not establish pid authority before startup");
+  }
+  if (shutdown.stopping) return;
+
+  const current = pidStatus(plan.pidFile);
+  if (current.state !== "running" || current.record.pid !== process.pid || current.record.startTime !== expected.startTime) {
+    throw new Error("pid authority changed before startup");
+  }
+
+  await runPrestart(plan, shutdown);
+  if (shutdown.stopping) return;
+  const afterPrestart = readPidRecord(plan.pidFile);
+  if (afterPrestart?.pid !== expected.pid
+    || afterPrestart.startTime !== expected.startTime
+    || afterPrestart.launchNonce !== expected.launchNonce) {
+    throw new Error("pid authority changed during migration prestart");
+  }
+
+  try {
+    await import(pathToFileURL(path.join(packageRoot, ".output", "server", "index.mjs")).href);
+    shutdown.nitroLoaded();
+    if (shutdown.stopping) return;
+
+    const ready = await waitFor(
+      () => shutdown.stopping || readinessReady(plan.readyUrl, expected.launchNonce),
+      READY_TIMEOUT_MS,
+    );
+    if (shutdown.stopping) return;
+    if (!ready) throw new Error(`server did not become ready at ${plan.readyUrl}`);
+    updatePidRecordState(plan, expected, "running");
+    console.log(`[pievo-server] ready at http://${plan.host}:${plan.port} (pid ${process.pid})`);
+  } catch (error) {
+    // Once Nitro may own a listening socket, ask its srvx signal handler to drain
+    // HTTP rather than forcing process.exit from our application handler.
+    shutdown.requestShutdown("SIGTERM");
+    throw error;
+  }
+}
+
+async function waitForProcessStart(pid, timeoutMs = 2_000) {
+  let value;
+  await waitFor(() => {
+    value = processStartTime(pid);
+    return Boolean(value);
+  }, timeoutMs, 25);
+  return value;
+}
+
+async function waitForDetachedReady(plan, expected) {
+  const deadline = Date.now() + DETACHED_LAUNCH_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const identity = recordedProcessState(expected);
+    if (identity.state === "gone") throw new Error(`server process ${expected.pid} exited during startup`);
+    if (identity.state === "unsafe") throw new Error(identity.error);
+    const current = readPidRecord(plan.pidFile);
+    if (current?.state === "running"
+      && current.pid === expected.pid
+      && current.startTime === expected.startTime
+      && current.launchNonce === expected.launchNonce
+      && await readinessReady(plan.readyUrl, expected.launchNonce)) return;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`server failed to become ready; see ${plan.logFile}`);
+}
+
+async function cleanFailedLaunch(plan, expected) {
+  const state = recordedProcessState(expected);
+  if (state.state === "gone") {
+    clearPidRecord(plan.pidFile, expected);
+    return;
+  }
+  if (state.state === "unsafe") throw new Error(`${state.error}; retaining ${plan.pidFile}`);
+  await terminateRecordedProcess(expected, {
+    gracefulTimeoutMs: STOP_TIMEOUT_MS,
+    forceTimeoutMs: FORCE_STOP_TIMEOUT_MS,
+  });
+  clearPidRecord(plan.pidFile, expected);
+}
+
+async function start(basePlan, foreground) {
+  const existing = pidStatus(basePlan.pidFile);
+  if (existing.state === "running") {
+    console.log(`pievo-server is already ${existing.record.state === "starting" ? "starting" : "running"} (pid ${existing.record.pid}, http://${existing.record.host}:${existing.record.port})`);
+    return;
+  }
+  if (existing.state === "unsafe") throw new Error(`${existing.error}; refusing to start over the existing pid record`);
+
+  const release = acquireStartLock(basePlan);
+  try {
+    const raced = pidStatus(basePlan.pidFile);
+    if (raced.state === "running") {
+      console.log(`pievo-server is already ${raced.record.state === "starting" ? "starting" : "running"} (pid ${raced.record.pid})`);
+      return;
+    }
+    if (raced.state === "unsafe") throw new Error(`${raced.error}; refusing to start over the existing pid record`);
+
+    const plan = withLaunchNonce(basePlan);
+    if (foreground) {
+      const record = writePidRecord(plan, {
+        launchNonce: plan.launchNonce,
+        managedGroup: false,
+        state: "starting",
+      });
+      await serve(plan, record);
+      return;
+    }
+
+    fs.mkdirSync(plan.dataDir, { recursive: true });
+    const logFd = fs.openSync(plan.logFile, "a", 0o600);
+    let child;
+    try {
+      child = spawn(process.execPath, [scriptFile, "_serve"], {
+        cwd: packageRoot,
+        env: plan.env,
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+      });
+    } finally {
+      fs.closeSync(logFd);
+    }
+    if (!child.pid) throw new Error("failed to spawn server process");
+    child.unref();
+
+    const childStart = await waitForProcessStart(child.pid);
+    if (!childStart) throw new Error(`cannot verify spawned server process ${child.pid}`);
+    const record = writePidRecord(plan, {
+      pid: child.pid,
+      startTime: childStart,
+      launchNonce: plan.launchNonce,
+      managedGroup: true,
+      state: "starting",
+    });
+
+    try {
+      await waitForDetachedReady(plan, record);
+    } catch (error) {
+      try {
+        await cleanFailedLaunch(plan, record);
+      } catch (cleanupError) {
+        throw new Error(`${error instanceof Error ? error.message : error}; cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : cleanupError}`);
+      }
+      throw error;
+    }
+    console.log(`pievo-server started (pid ${child.pid}, http://${plan.host}:${plan.port})`);
+    console.log(`log: ${plan.logFile}`);
+  } finally {
+    release();
+  }
+}
+
+async function stop(plan) {
+  let release;
+  let stoppedRecord;
+  try {
+    try {
+      release = acquireStartLock(plan);
+    } catch (error) {
+      if (error?.code !== "START_LOCKED") throw error;
+      // A detached launcher owns the lock until readiness/failure. Its child pid
+      // record is written before migrations, so stop can still terminate exactly
+      // that starting process, then wait for the launcher to relinquish the lock.
+      const launching = pidStatus(plan.pidFile);
+      if (launching.state !== "running") {
+        if (launching.state === "unsafe") throw new Error(`${launching.error}; refusing to stop during launch`);
+        throw new Error("a launch is in progress but no server process can be safely identified");
+      }
+      stoppedRecord = launching.record;
+      const result = await terminateRecordedProcess(stoppedRecord, {
+        gracefulTimeoutMs: STOP_TIMEOUT_MS,
+        forceTimeoutMs: FORCE_STOP_TIMEOUT_MS,
+      });
+      if (result.forced) console.warn(`[pievo-server] graceful stop timed out; killed pid ${stoppedRecord.pid}`);
+      clearPidRecord(plan.pidFile, stoppedRecord);
+      release = await acquireStartLockEventually(plan, LOCK_HANDOFF_TIMEOUT_MS);
+    }
+
+    const status = pidStatus(plan.pidFile);
+    if (status.state === "unsafe") throw new Error(`${status.error}; refusing to signal the existing pid record`);
+    if (status.state === "running") {
+      stoppedRecord = status.record;
+      const result = await terminateRecordedProcess(stoppedRecord, {
+        gracefulTimeoutMs: STOP_TIMEOUT_MS,
+        forceTimeoutMs: FORCE_STOP_TIMEOUT_MS,
+      });
+      if (result.forced) console.warn(`[pievo-server] graceful stop timed out; killed pid ${stoppedRecord.pid}`);
+      clearPidRecord(plan.pidFile, stoppedRecord);
+    }
+
+    if (stoppedRecord) console.log(`pievo-server stopped (pid ${stoppedRecord.pid})`);
+    else console.log("pievo-server is not running");
+  } finally {
+    release?.();
+  }
+}
+
+function status(plan) {
+  const current = pidStatus(plan.pidFile);
+  if (current.state === "running") {
+    console.log(`pievo-server is ${current.record.state === "starting" ? "starting" : "running"} (pid ${current.record.pid})`);
+    console.log(`url: http://${current.record.host}:${current.record.port}`);
+    console.log(`data: ${plan.dataDir}`);
+    return 0;
+  }
+  if (current.state === "unsafe") {
+    const pid = current.record?.pid ? ` (pid ${current.record.pid})` : "";
+    console.error(`pievo-server status is unsafe: ${current.error}${pid}`);
+    return 1;
+  }
+  console.log(`pievo-server is stopped${current.stale ? " (cleared stale pid file)" : ""}`);
+  return 1;
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`pievo-server: ${error.message}\n\n${usage()}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (options.command === "help") {
+    console.log(usage());
+    return;
+  }
+
+  const inheritedNonce = process.env.PIEVO_SERVER_LAUNCH_NONCE;
+  const instancePlan = buildEnvPlan(options);
+  if (options.command === "_serve") {
+    if (!inheritedNonce) throw new Error("internal serve command requires a launch nonce");
+    const plan = { ...instancePlan, launchNonce: inheritedNonce, env: { ...instancePlan.env, PIEVO_SERVER_LAUNCH_NONCE: inheritedNonce } };
+    const startTime = processStartTime(process.pid);
+    if (!startTime) throw new Error("cannot verify server process identity");
+    const expected = {
+      pid: process.pid,
+      startTime,
+      launchNonce: inheritedNonce,
+      managedGroup: true,
+    };
+    return serve(plan, expected);
+  }
+  if (options.command === "start") return start(instancePlan, options.foreground);
+  if (options.command === "stop") return stop(instancePlan);
+  if (options.command === "status") {
+    process.exitCode = status(instancePlan);
+    return;
+  }
+  if (options.command === "restart") {
+    const before = pidStatus(instancePlan.pidFile);
+    if (before.state === "unsafe") throw new Error(`${before.error}; refusing to restart the existing pid record`);
+    const restartPlan = buildRestartPlan(options, process.env, before.record);
+    await stop(instancePlan);
+    await start(restartPlan, options.foreground);
+  }
+}
+
+main().catch((error) => {
+  console.error(`pievo-server: ${error instanceof Error ? error.message : error}`);
+  process.exitCode = 1;
+});

package/scripts/prestart.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Pre-start migration gate + the BUILT server's boot-time config guard.
+//
+// HOSTED Postgres tier (DATABASE_URL set): apply pending migrations over the
+// DIRECT/session URL using the SAME postgres-js migrator the app uses at boot
+// (db/index.ts `runMigrations`). We deliberately do NOT shell out to
+// `drizzle-kit migrate` — its bundled driver hangs/fails against the Supabase
+// Supavisor pooler, whereas postgres-js connects cleanly. Running it here (a
+// separate pre-serve step) makes a bad migration fail the deploy LOUDLY.
+//
+// Embedded pglite tier (no DATABASE_URL - light self-host): the database
+// migrates IN-PROCESS at boot, so no migration here - but the tier must be
+// OPTED INTO with PIEVO_DB=pglite. The built artifact carries production
+// semantics (vite bakes NODE_ENV=production into the bundle), so a missing
+// DATABASE_URL secret must fail the container HERE, at startup, loudly -
+// db/index.ts has the same refusal, but it sits in a lazily-imported chunk,
+// so on its own the container would boot green and only 500 on the first DB
+// request. `pnpm start` and the Docker CMD both run this script first, which
+// turns that late 500 into a nonzero exit before the server ever serves.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (!process.env.DATABASE_URL) {
+  if (process.env.PIEVO_DB !== "pglite") {
+    console.error(
+      "[prestart] refusing to start on the ephemeral embedded database - " +
+        "set DATABASE_URL (hosted Postgres), or PIEVO_DB=pglite to opt into " +
+        "the embedded pglite tier (and point PIEVO_DATA_DIR at persistent storage)",
+    );
+    process.exit(1);
+  }
+  console.log("[prestart] no DATABASE_URL - embedded pglite (PIEVO_DB=pglite) migrates in-process at boot; skipping");
+  process.exit(0);
+}
+
+const { default: postgres } = await import("postgres");
+const { drizzle } = await import("drizzle-orm/postgres-js");
+const { migrate } = await import("drizzle-orm/postgres-js/migrator");
+
+// DDL + the migrator advisory lock run over the DIRECT (session-mode) URL —
+// never the transaction pooler. Falls back to DATABASE_URL for a plain Postgres,
+// but FAILS LOUD when that fallback would route DDL over the Supabase transaction
+// pooler (it multiplexes connections and cannot hold the migrator's session-scoped
+// advisory lock) - mirrors env.ts `directDatabaseUrl()`, which this script can't
+// import (it runs unbundled, without the TS build).
+const url = process.env.DIRECT_DATABASE_URL || process.env.DATABASE_URL;
+if (!process.env.DIRECT_DATABASE_URL && (url.includes(":6543") || url.includes("pooler.supabase.com"))) {
+  console.error(
+    "[prestart] DIRECT_DATABASE_URL is unset but DATABASE_URL points at the Supabase transaction pooler " +
+      "(:6543 / pooler.supabase.com) - set DIRECT_DATABASE_URL to the direct (:5432, session-mode) " +
+      "connection so migrations run off the pooler",
+  );
+  process.exit(1);
+}
+const migrationsFolder = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "drizzle");
+
+const client = postgres(url, { max: 1 });
+try {
+  await migrate(drizzle(client), { migrationsFolder });
+  console.log("[prestart] migrations applied");
+} catch (e) {
+  console.error("[prestart] migration failed:", e?.message ?? e);
+  process.exitCode = 1;
+} finally {
+  await client.end();
+}