orez 0.0.1

package/dist/s3-local.js

@@ -0,0 +1,131 @@
+/**
+ * minimal local s3-compatible server.
+ * handles GET/PUT/DELETE/HEAD for object storage, replacing minio.
+ */
+import { createServer, } from 'node:http';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, } from 'node:fs';
+import { join, dirname, extname, resolve } from 'node:path';
+const MIME_TYPES = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.json': 'application/json',
+    '.txt': 'text/plain',
+};
+function corsHeaders() {
+    return {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, PUT, DELETE, HEAD, OPTIONS',
+        'Access-Control-Allow-Headers': '*',
+        'Access-Control-Expose-Headers': 'ETag, Content-Length',
+    };
+}
+export function startS3Server(config) {
+    const storageDir = join(config.dataDir, 's3');
+    mkdirSync(storageDir, { recursive: true });
+    const server = createServer((req, res) => {
+        const headers = corsHeaders();
+        if (req.method === 'OPTIONS') {
+            res.writeHead(200, headers);
+            res.end();
+            return;
+        }
+        const url = new URL(req.url || '/', `http://localhost:${config.s3Port}`);
+        const filePath = resolve(join(storageDir, url.pathname));
+        if (!filePath.startsWith(resolve(storageDir))) {
+            res.writeHead(403, headers);
+            res.end();
+            return;
+        }
+        try {
+            switch (req.method) {
+                case 'GET': {
+                    if (!existsSync(filePath) ||
+                        statSync(filePath).isDirectory()) {
+                        res.writeHead(404, {
+                            ...headers,
+                            'Content-Type': 'application/xml',
+                        });
+                        res.end('<Error><Code>NoSuchKey</Code></Error>');
+                        return;
+                    }
+                    const data = readFileSync(filePath);
+                    const ext = extname(filePath);
+                    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+                    res.writeHead(200, {
+                        ...headers,
+                        'Content-Type': contentType,
+                        'Content-Length': data.length.toString(),
+                        ETag: `"${Buffer.from(data).length}"`,
+                    });
+                    res.end(data);
+                    break;
+                }
+                case 'PUT': {
+                    const chunks = [];
+                    req.on('data', (chunk) => chunks.push(chunk));
+                    req.on('end', () => {
+                        mkdirSync(dirname(filePath), {
+                            recursive: true,
+                        });
+                        const body = Buffer.concat(chunks);
+                        writeFileSync(filePath, body);
+                        res.writeHead(200, {
+                            ...headers,
+                            ETag: `"${body.length}"`,
+                        });
+                        res.end();
+                    });
+                    break;
+                }
+                case 'DELETE': {
+                    if (existsSync(filePath)) {
+                        unlinkSync(filePath);
+                    }
+                    res.writeHead(204, headers);
+                    res.end();
+                    break;
+                }
+                case 'HEAD': {
+                    if (!existsSync(filePath) ||
+                        statSync(filePath).isDirectory()) {
+                        res.writeHead(404, headers);
+                        res.end();
+                        return;
+                    }
+                    const stat = statSync(filePath);
+                    const ext = extname(filePath);
+                    res.writeHead(200, {
+                        ...headers,
+                        'Content-Type': MIME_TYPES[ext] ||
+                            'application/octet-stream',
+                        'Content-Length': stat.size.toString(),
+                    });
+                    res.end();
+                    break;
+                }
+                default:
+                    res.writeHead(405, headers);
+                    res.end();
+            }
+        }
+        catch (err) {
+            res.writeHead(500, {
+                ...headers,
+                'Content-Type': 'application/xml',
+            });
+            res.end('<Error><Code>InternalError</Code></Error>');
+        }
+    });
+    return new Promise((resolve, reject) => {
+        server.listen(config.s3Port, '127.0.0.1', () => {
+            console.info(`[orez] local s3 listening on port ${config.s3Port}`);
+            resolve(server);
+        });
+        server.on('error', reject);
+    });
+}
+//# sourceMappingURL=s3-local.js.map

package/dist/s3-local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-local.js","sourceRoot":"","sources":["../src/s3-local.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,YAAY,GAIb,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,QAAQ,GACT,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAI3D,MAAM,UAAU,GAA2B;IACzC,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,eAAe;IACvB,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,YAAY;CACrB,CAAA;AAED,SAAS,WAAW;IAClB,OAAO;QACL,6BAA6B,EAAE,GAAG;QAClC,8BAA8B,EAC5B,iCAAiC;QACnC,8BAA8B,EAAE,GAAG;QACnC,+BAA+B,EAAE,sBAAsB;KACxD,CAAA;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,MAAsB;IAEtB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC7C,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAE1C,MAAM,MAAM,GAAG,YAAY,CACzB,CAAC,GAAoB,EAAE,GAAmB,EAAE,EAAE;QAC5C,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;QAE7B,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC7B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC3B,GAAG,CAAC,GAAG,EAAE,CAAA;YACT,OAAM;QACR,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,GAAG,CACjB,GAAG,CAAC,GAAG,IAAI,GAAG,EACd,oBAAoB,MAAM,CAAC,MAAM,EAAE,CACpC,CAAA;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAA;QAExD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC3B,GAAG,CAAC,GAAG,EAAE,CAAA;YACT,OAAM;QACR,CAAC;QAED,IAAI,CAAC;YACH,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;gBACnB,KAAK,KAAK,CAAC,CAAC,CAAC;oBACX,IACE,CAAC,UAAU,CAAC,QAAQ,CAAC;wBACrB,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAChC,CAAC;wBACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;4BACjB,GAAG,OAAO;4BACV,cAAc,EAAE,iBAAiB;yBAClC,CAAC,CAAA;wBACF,GAAG,CAAC,GAAG,CACL,uCAAuC,CACxC,CAAA;wBACD,OAAM;oBACR,CAAC;oBACD,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;oBACnC,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;oBAC7B,MAAM,WAAW,GACf,UAAU,CAAC,GAAG,CAAC,IAAI,0BAA0B,CAAA;oBAC/C,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;wBACjB,GAAG,OAAO;wBACV,cAAc,EAAE,WAAW;wBAC3B,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;wBACxC,IAAI,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG;qBACtC,CAAC,CAAA;oBACF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;oBACb,MAAK;gBACP,CAAC;gBAED,KAAK,KAAK,CAAC,CAAC,CAAC;oBACX,MAAM,MAAM,GAAa,EAAE,CAAA;oBAC3B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CACnB,CAAA;oBACD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;wBACjB,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;4BAC3B,SAAS,EAAE,IAAI;yBAChB,CAAC,CAAA;wBACF,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;wBAClC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;wBAC7B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;4BACjB,GAAG,OAAO;4BACV,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,GAAG;yBACzB,CAAC,CAAA;wBACF,GAAG,CAAC,GAAG,EAAE,CAAA;oBACX,CAAC,CAAC,CAAA;oBACF,MAAK;gBACP,CAAC;gBAED,KAAK,QAAQ,CAAC,CAAC,CAAC;oBACd,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;wBACzB,UAAU,CAAC,QAAQ,CAAC,CAAA;oBACtB,CAAC;oBACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;oBAC3B,GAAG,CAAC,GAAG,EAAE,CAAA;oBACT,MAAK;gBACP,CAAC;gBAED,KAAK,MAAM,CAAC,CAAC,CAAC;oBACZ,IACE,CAAC,UAAU,CAAC,QAAQ,CAAC;wBACrB,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAChC,CAAC;wBACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;wBAC3B,GAAG,CAAC,GAAG,EAAE,CAAA;wBACT,OAAM;oBACR,CAAC;oBACD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAA;oBAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;oBAC7B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;wBACjB,GAAG,OAAO;wBACV,cAAc,EACZ,UAAU,CAAC,GAAG,CAAC;4BACf,0BAA0B;wBAC5B,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE;qBACvC,CAAC,CAAA;oBACF,GAAG,CAAC,GAAG,EAAE,CAAA;oBACT,MAAK;gBACP,CAAC;gBAED;oBACE,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;oBAC3B,GAAG,CAAC,GAAG,EAAE,CAAA;YACb,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;gBACjB,GAAG,OAAO;gBACV,cAAc,EAAE,iBAAiB;aAClC,CAAC,CAAA;YACF,GAAG,CAAC,GAAG,CACL,2CAA2C,CAC5C,CAAA;QACH,CAAC;IACH,CAAC,CACF,CAAA;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE;YAC7C,OAAO,CAAC,IAAI,CACV,qCAAqC,MAAM,CAAC,MAAM,EAAE,CACrD,CAAA;YACD,OAAO,CAAC,MAAM,CAAC,CAAA;QACjB,CAAC,CAAC,CAAA;QACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IAC5B,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "orez",
+  "version": "0.0.1",
+  "description": "PGlite-powered zero-sync development backend. No Docker required.",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint --import-plugin",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "check": "tsc --noEmit",
+    "demo:test": "bun demo/src/test/run-e2e.ts",
+    "check:all": "bun run lint && bun run format:check && bun run check && bun run test",
+    "release": "bun scripts/release.ts"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "pg-gateway": "^0.3.0-beta.4"
+  },
+  "devDependencies": {
+    "oxlint": "latest",
+    "oxfmt": "latest",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/natew/zero-lite"
+  },
+  "keywords": [
+    "zero",
+    "pglite",
+    "postgres",
+    "replication",
+    "sync",
+    "zero-cache",
+    "development"
+  ]
+}

package/src/config.ts

@@ -0,0 +1,40 @@
+export interface ZeroLiteConfig {
+  dataDir: string
+  pgPort: number
+  zeroPort: number
+  s3Port: number
+  webPort: number
+  pgUser: string
+  pgPassword: string
+  migrationsDir: string
+  seedFile: string
+  skipZeroCache: boolean
+}
+
+export function getConfig(
+  overrides: Partial<ZeroLiteConfig> = {}
+): ZeroLiteConfig {
+  return {
+    dataDir: overrides.dataDir || '.zero-lite',
+    pgPort: overrides.pgPort || 6434,
+    zeroPort: overrides.zeroPort || 5849,
+    s3Port: overrides.s3Port || 10201,
+    webPort:
+      overrides.webPort ||
+      Number(process.env.VITE_PORT_WEB) ||
+      8081,
+    pgUser: overrides.pgUser || 'user',
+    pgPassword: overrides.pgPassword || 'password',
+    migrationsDir:
+      overrides.migrationsDir || 'src/database/migrations',
+    seedFile: overrides.seedFile || 'src/database/seed.sql',
+    skipZeroCache: overrides.skipZeroCache || false,
+  }
+}
+
+export function getConnectionString(
+  config: ZeroLiteConfig,
+  dbName = 'postgres'
+): string {
+  return `postgresql://${config.pgUser}:${config.pgPassword}@127.0.0.1:${config.pgPort}/${dbName}`
+}

package/src/index.ts

@@ -0,0 +1,255 @@
+/**
+ * orez: pglite-powered zero-sync development backend.
+ *
+ * starts a pglite instance, tcp proxy, s3 server, and zero-cache
+ * process. replaces docker-based postgresql, zero-cache, and minio
+ * with a single `bun run` command.
+ */
+
+import { resolve, join } from 'node:path'
+import {
+  existsSync,
+  readFileSync,
+  mkdirSync,
+  writeFileSync,
+  unlinkSync,
+} from 'node:fs'
+import { spawn, type ChildProcess } from 'node:child_process'
+
+import type { PGlite } from '@electric-sql/pglite'
+import type { Server } from 'node:net'
+import type { Server as HttpServer } from 'node:http'
+
+import { getConfig, getConnectionString } from './config'
+import { installChangeTracking } from './replication/change-tracker'
+import { createPGliteInstance, runMigrations } from './pglite-manager'
+import { startPgProxy } from './pg-proxy'
+import { startS3Server } from './s3-local'
+
+import type { ZeroLiteConfig } from './config'
+
+export type { ZeroLiteConfig } from './config'
+export { getConfig, getConnectionString } from './config'
+
+export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
+  const config = getConfig(overrides)
+  console.info('[orez] starting...')
+  console.info(`[orez] data dir: ${resolve(config.dataDir)}`)
+
+  mkdirSync(config.dataDir, { recursive: true })
+
+  // start pglite
+  const db = await createPGliteInstance(config)
+
+  // run migrations
+  await runMigrations(db, config)
+
+  // install change tracking
+  console.info('[orez] installing change tracking')
+  await installChangeTracking(db)
+
+  // start tcp proxy
+  const pgServer = await startPgProxy(db, config)
+
+  // start s3 server
+  const s3Server = await startS3Server(config)
+
+  // seed data if needed
+  await seedIfNeeded(db, config)
+
+  // write .env.local so `bun dev` connects to orez ports
+  writeEnvLocal(config)
+
+  // start zero-cache
+  let zeroCacheProcess: ChildProcess | null = null
+  if (!config.skipZeroCache) {
+    console.info('[orez] starting zero-cache...')
+    zeroCacheProcess = await startZeroCache(config)
+    await waitForZeroCache(config)
+  } else {
+    console.info('[orez] skipping zero-cache (skipZeroCache=true)')
+  }
+
+  const stop = async () => {
+    console.info('[orez] shutting down...')
+    if (zeroCacheProcess) {
+      zeroCacheProcess.kill('SIGTERM')
+    }
+    pgServer.close()
+    s3Server.close()
+    await db.close()
+    cleanupEnvLocal()
+    console.info('[orez] stopped')
+  }
+
+  return { config, stop }
+}
+
+const ENV_LOCAL_PATH = resolve('.env.local')
+const ENV_LOCAL_MARKER = '# auto-generated by orez'
+
+function writeEnvLocal(config: ZeroLiteConfig): void {
+  const upstreamUrl = getConnectionString(config, 'postgres')
+  const cvrUrl = getConnectionString(config, 'zero_cvr')
+  const cdbUrl = getConnectionString(config, 'zero_cdb')
+
+  const content = `${ENV_LOCAL_MARKER}
+VITE_PORT_POSTGRES=${config.pgPort}
+VITE_PORT_ZERO=${config.zeroPort}
+VITE_PORT_MINIO=${config.s3Port}
+VITE_PUBLIC_ZERO_SERVER="http://localhost:${config.zeroPort}"
+ZERO_UPSTREAM_DB="${upstreamUrl}"
+ZERO_CVR_DB="${cvrUrl}"
+ZERO_CHANGE_DB="${cdbUrl}"
+CLOUDFLARE_R2_ENDPOINT="http://localhost:${config.s3Port}"
+CLOUDFLARE_R2_PUBLIC_URL="http://localhost:${config.s3Port}"
+`
+  writeFileSync(ENV_LOCAL_PATH, content)
+  console.info('[orez] wrote .env.local for dev server')
+}
+
+function cleanupEnvLocal(): void {
+  try {
+    if (existsSync(ENV_LOCAL_PATH)) {
+      const content = readFileSync(ENV_LOCAL_PATH, 'utf-8')
+      if (content.startsWith(ENV_LOCAL_MARKER)) {
+        unlinkSync(ENV_LOCAL_PATH)
+        console.info('[orez] cleaned up .env.local')
+      }
+    }
+  } catch {
+    // ignore cleanup errors
+  }
+}
+
+async function seedIfNeeded(
+  db: PGlite,
+  config: ZeroLiteConfig
+): Promise<void> {
+  // check if we already have data
+  try {
+    const result = await db.query<{ count: string }>(
+      'SELECT count(*) as count FROM public."user"'
+    )
+    if (Number(result.rows[0].count) > 0) {
+      return
+    }
+  } catch {
+    // table might not exist yet
+  }
+
+  console.info('[orez] seeding demo data...')
+  const seedFile = resolve(config.seedFile)
+  if (!existsSync(seedFile)) {
+    console.info('[orez] no seed file found, skipping')
+    return
+  }
+
+  const sql = readFileSync(seedFile, 'utf-8')
+  const statements = sql
+    .split('--> statement-breakpoint')
+    .map((s) => s.trim())
+    .filter(Boolean)
+
+  for (const stmt of statements) {
+    await db.exec(stmt)
+  }
+  console.info('[orez] seeded demo data')
+}
+
+async function startZeroCache(
+  config: ZeroLiteConfig
+): Promise<ChildProcess> {
+  // find zero-cache binary
+  const zeroCachePaths = [
+    resolve('node_modules/.bin/zero-cache'),
+    resolve(
+      'node_modules/@rocicorp/zero/out/zero-cache/src/bin/main.js'
+    ),
+  ]
+
+  let zeroCacheBin = ''
+  for (const p of zeroCachePaths) {
+    if (existsSync(p)) {
+      zeroCacheBin = p
+      break
+    }
+  }
+
+  if (!zeroCacheBin) {
+    throw new Error(
+      'zero-cache binary not found. install @rocicorp/zero'
+    )
+  }
+
+  const upstreamUrl = getConnectionString(config, 'postgres')
+  const cvrUrl = getConnectionString(config, 'zero_cvr')
+  const cdbUrl = getConnectionString(config, 'zero_cdb')
+
+  const env: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    NODE_ENV: 'development',
+    ZERO_UPSTREAM_DB: upstreamUrl,
+    ZERO_CVR_DB: cvrUrl,
+    ZERO_CHANGE_DB: cdbUrl,
+    ZERO_REPLICA_FILE: resolve(config.dataDir, 'zero-replica.db'),
+    ZERO_PORT: String(config.zeroPort),
+    ZERO_MUTATE_URL: `http://localhost:${config.webPort}/api/zero/push`,
+    ZERO_QUERY_URL: `http://localhost:${config.webPort}/api/zero/pull`,
+    ZERO_LOG_LEVEL: 'info',
+    ZERO_NUM_SYNC_WORKERS: '1',
+    DO_NOT_TRACK: '1',
+  }
+
+  const child = spawn(zeroCacheBin, [], {
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+
+  child.stdout?.on('data', (data: Buffer) => {
+    const lines = data.toString().trim().split('\n')
+    for (const line of lines) {
+      console.info(`[zero-cache] ${line}`)
+    }
+  })
+
+  child.stderr?.on('data', (data: Buffer) => {
+    const lines = data.toString().trim().split('\n')
+    for (const line of lines) {
+      console.info(`[zero-cache] ${line}`)
+    }
+  })
+
+  child.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      console.info(`[zero-cache] exited with code ${code}`)
+    }
+  })
+
+  return child
+}
+
+async function waitForZeroCache(
+  config: ZeroLiteConfig,
+  timeoutMs = 60000
+): Promise<void> {
+  const start = Date.now()
+  const url = `http://127.0.0.1:${config.zeroPort}/`
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url)
+      if (res.ok) {
+        console.info('[orez] zero-cache is ready')
+        return
+      }
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 500))
+  }
+
+  console.info(
+    '[orez] warning: zero-cache health check timed out, continuing anyway'
+  )
+}