ework-aio 0.1.7 → 0.1.9

package/README.md

@@ -100,7 +100,7 @@ Keeping these in a separate, explicitly-invoked step is intentional:
 ```
 ework-aio install [options]    Install or upgrade the stack
 ework-aio uninstall            Stop services and remove units (data preserved)
-ework-aio status               Show service status
+ework-aio status               Show service status (systemd mode)
 ework-aio logs [web|daemon]    Tail logs
 ework-aio env                  Print key paths (no secrets)
 ework-aio config <subcommand>  Read / change runtime .env keys
@@ -109,6 +109,12 @@ ework-aio config <subcommand>  Read / change runtime .env keys
   config set <KEY> <VALUE>    Set a key, then restart affected service
                               (use --no-restart to defer)
   config restart <web|daemon|both>  Restart one or both services
+
+# PID-file mode (no systemd required — see below)
+ework-aio start [web|daemon|both] [--foreground]  Start services in background
+ework-aio stop [web|daemon|both]                  Stop services (SIGTERM, 5s, SIGKILL)
+ework-aio restart [web|daemon|both]               Stop + start
+ework-aio ps                                       Show PID-file mode status
 ```
 
 ### Install options
@@ -212,6 +218,45 @@ npm uninstall -g ework-aio ework-web ework-daemon opencode-ework
 # Remove the plugin entry from ~/.config/opencode/opencode.json manually
 ```
 
+## PID-file mode (no systemd)
+
+`install` / `status` / `config` / `uninstall` go through `systemctl`, which assumes systemd. If you're on a system without systemd — **macOS, WSL1, Alpine without systemd, Docker containers, dev laptops** — use the parallel PID-file mode instead:
+
+| Mode        | Start                         | Stop                          | Status              | Restart                          |
+| ----------- | ----------------------------- | ----------------------------- | ------------------- | -------------------------------- |
+| systemd     | `ework-aio install`           | `ework-aio uninstall`         | `ework-aio status`  | `ework-aio config restart both`  |
+| **PID-file**| `ework-aio start`             | `ework-aio stop`              | `ework-aio ps`      | `ework-aio restart`              |
+
+PID-file mode writes per-service PID + log under `~/.local/share/ework-aio/run/`:
+
+```
+~/.local/share/ework-aio/run/
+  ├── web.pid          # ework-web PID
+  ├── web.log          # nohup stdout+stderr
+  ├── daemon.pid
+  └── daemon.log
+```
+
+```bash
+# One-time setup: scaffold .env + data dir (no systemd required if you skip the unit install)
+ework-aio install --no-start
+
+# Then control with PID-file mode:
+ework-aio start                # start web + daemon in background
+ework-aio start web            # just web
+ework-aio start daemon --foreground   # run in current terminal
+ework-aio stop                 # SIGTERM, 5s grace, SIGKILL if needed
+ework-aio restart web          # stop + start
+ework-aio ps                   # show PID + log path for each service
+```
+
+Override the data dir with `EWORK_AIO_DATA_DIR=/path ework-aio start`.
+
+**Notes**:
+- `install` (with `--no-start`) is still required once to scaffold `.env` and the data directory. The systemd units it writes are inert when nothing manages them.
+- PID-file mode does NOT auto-restart on crash. Consider a process supervisor (`pm2`, `supervisord`, `runit`, `launchd`) if you need that.
+- Both modes can coexist (systemd-managed services ignore PID files, and vice versa) but you should pick one to avoid port conflicts.
+
 ## Alternatives
 
 - **Docker AIO**: the `ework-web` repo ships `docker/build.sh` + `docker/run.sh` for a single-container deployment. Useful when you don't want to manage host systemd.

package/bin/ework-aio

@@ -1,7 +1,14 @@
 #!/usr/bin/env bun
 import { spawn, spawnSync } from "bun";
-import { existsSync, readFileSync } from "fs";
-import { resolve, dirname, join } from "path";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "fs";
+import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -14,8 +21,9 @@ function usage() {
 
 Usage:
   ework-aio install [options]    Install and start ework-web + ework-daemon
+                                  (uses systemd; see start/stop for non-systemd)
   ework-aio uninstall            Stop services and remove units (keeps data)
-  ework-aio status               Show service status
+  ework-aio status               Show service status (systemd mode)
   ework-aio logs [svc]           Tail logs (svc: web | daemon)
   ework-aio env                  Print the .env path and key names (no values)
   ework-aio config <subcommand>  Read / change runtime .env keys
@@ -24,6 +32,19 @@ Usage:
     config set <KEY> <VALUE>     Set a key, then restart affected service
                                  (use --no-restart to defer)
     config restart <web|daemon|both>
+  ework-aio start [svc]          Start services in background WITHOUT systemd
+                                  (PID-file mode, works on WSL/macOS/Alpine).
+                                  svc: web | daemon | both (default both).
+                                  --foreground runs in current terminal.
+  ework-aio stop [svc]           Stop services started via 'start'
+                                  (SIGTERM, 5s grace, then SIGKILL)
+  ework-aio restart [svc]        Stop + start
+  ework-aio ps                   Show PID-file mode status (web+daemon)
+  ework-aio migrate [options]    Migrate issues from a Gitea instance into
+                                  ework-web via the Gitea REST API. Idempotent.
+                                  Run \`ework-aio migrate --help\` for details.
+  ework-aio backfill-timestamps  Fix created_at/updated_at on already-migrated
+                                  data. Use after migrate when ework.db is local.
   ework-aio --version            Print version
 
 Install options:
@@ -35,6 +56,9 @@ Install options:
   --bot-name <login>             Bot username (default: ework-daemon)
   --no-start                     Install units but don't start services
   --yes                          Skip all prompts (use generated defaults)
+
+PID-file mode (--foreground works with start):
+  --data-dir <path>              Same as install option
 `);
 }
 
@@ -56,6 +80,356 @@ if (!existsSync(installSh)) {
 }
 
 const knownSubs = ["install", "uninstall", "status", "logs", "env", "config"];
+
+// ─── PID-file mode (no systemd required) ───────────────────────────────────
+//
+// start/stop/restart/ps bypass install.sh and the systemd dependency entirely.
+// Each service writes its PID + log under $DATA_DIR/run/, managed via the
+// standard node:child_process detached-spawn pattern (sets the child free of
+// the parent's process group so the parent can exit while the service keeps
+// running). This is the path for systems without systemd: macOS, WSL1, Alpine,
+// containers, dev laptops.
+
+const SVC_CONFIG = {
+  web: {
+    binName: "ework-web",
+    binFallback: "ework-web/bin/ework-web.js",
+    dataSubdir: "ework-web",
+    label: "ework-web",
+  },
+  daemon: {
+    binName: "ework-daemon-server",
+    binFallback: "ework-daemon/bin/ework-daemon-server.js",
+    dataSubdir: "ework-daemon",
+    label: "ework-daemon",
+  },
+} as const;
+
+type SvcName = keyof typeof SVC_CONFIG;
+
+function resolveDataDir(): string {
+  const xdg = process.env.XDG_DATA_HOME || `${process.env.HOME}/.local/share`;
+  return process.env.EWORK_AIO_DATA_DIR || `${xdg}/ework-aio`;
+}
+
+function runDir(): string {
+  const d = join(resolveDataDir(), "run");
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+  return d;
+}
+
+function svcEnvPath(svc: SvcName): string {
+  return join(resolveDataDir(), SVC_CONFIG[svc].dataSubdir, ".env");
+}
+
+function svcPidPath(svc: SvcName): string {
+  return join(runDir(), `${svc}.pid`);
+}
+
+function svcLogPath(svc: SvcName): string {
+  return join(runDir(), `${svc}.log`);
+}
+
+// KEY=VALUE parser, ignores comments + blanks, never throws.
+function parseEnvFile(path: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!existsSync(path)) return out;
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq < 0) continue;
+    const k = trimmed.slice(0, eq).trim();
+    let v = trimmed.slice(eq + 1).trim();
+    if (
+      (v.startsWith('"') && v.endsWith('"')) ||
+      (v.startsWith("'") && v.endsWith("'"))
+    ) {
+      v = v.slice(1, -1);
+    }
+    if (k) out[k] = v;
+  }
+  return out;
+}
+
+function resolveSvcBin(svc: SvcName): string | null {
+  const cfg = SVC_CONFIG[svc];
+  // PATH lookup first (covers PATH-installed global bins). `command -v` is a
+  // shell builtin so we have to invoke via sh -c.
+  const lookup = spawnSync(["sh", "-c", `command -v ${cfg.binName}`], {
+    env: process.env,
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (lookup.success) {
+    const p = lookup.stdout.toString().trim();
+    if (p && existsSync(p)) return p;
+  }
+  // npm global root fallback — covers npm-installed packages whose bin dir
+  // isn't on PATH (common with nvm-style installs).
+  const npmRoot = spawnSync(["npm", "root", "-g"], {
+    env: process.env,
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (npmRoot.success) {
+    const fallback = join(npmRoot.stdout.toString().trim(), cfg.binFallback);
+    if (existsSync(fallback)) return fallback;
+  }
+  return null;
+}
+
+function pidAlive(pid: number): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readPid(svc: SvcName): number | null {
+  const p = svcPidPath(svc);
+  if (!existsSync(p)) return null;
+  const raw = readFileSync(p, "utf8").trim();
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+function writePid(svc: SvcName, pid: number): void {
+  writeFileSync(svcPidPath(svc), `${pid}\n`, { encoding: "utf8" });
+}
+
+function clearPid(svc: SvcName): void {
+  const p = svcPidPath(svc);
+  if (existsSync(p)) rmSync(p);
+
+  const staleSocket = join(runDir(), `${svc}.port`);
+  if (existsSync(staleSocket)) rmSync(staleSocket);
+}
+
+function waitForExit(pid: number, timeoutMs: number): boolean {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!pidAlive(pid)) return true;
+    const slept = Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    void slept;
+  }
+  return !pidAlive(pid);
+}
+
+function parseSvcArg(argv: string[]): { svc: "both" | SvcName; foreground: boolean } {
+  let svc: "both" | SvcName = "both";
+  let foreground = false;
+  for (const a of argv.slice(1)) {
+    if (a === "--foreground" || a === "-f") foreground = true;
+    else if (a === "web" || a === "daemon") svc = a;
+    else if (a === "both") svc = "both";
+    else {
+      console.error(`Unknown argument: ${a}`);
+      console.error("Usage: ework-aio <start|stop|restart> [web|daemon|both] [--foreground]");
+      process.exit(2);
+    }
+  }
+  return { svc, foreground };
+}
+
+function startOne(svc: SvcName, foreground: boolean): boolean {
+  const existing = readPid(svc);
+  if (existing && pidAlive(existing)) {
+    console.log(`${SVC_CONFIG[svc].label} already running (pid ${existing})`);
+    return true;
+  }
+  if (existing) clearPid(svc);
+
+  const bin = resolveSvcBin(svc);
+  if (!bin) {
+    console.error(
+      `${SVC_CONFIG[svc].label}: cannot find bin '${SVC_CONFIG[svc].binName}' in PATH or npm global root.`
+    );
+    console.error(`  Install with: npm i -g ${SVC_CONFIG[svc].binName.split("-")[0]}`);
+    return false;
+  }
+  const envPath = svcEnvPath(svc);
+  if (!existsSync(envPath)) {
+    console.error(
+      `${SVC_CONFIG[svc].label}: missing .env at ${envPath}.`
+    );
+    console.error("  Run `ework-aio install --no-start` first to scaffold config + data dir.");
+    return false;
+  }
+
+  // Sane perms on the bin (npm sometimes ships without +x).
+  try {
+    chmodSync(bin, 0o755);
+  } catch {
+    // best-effort
+  }
+
+  const mergedEnv = { ...process.env, ...parseEnvFile(envPath) };
+  const logPath = svcLogPath(svc);
+
+  if (foreground) {
+    console.log(`Starting ${SVC_CONFIG[svc].label} in foreground (Ctrl+C to stop)`);
+    const r = spawnSync([bin], {
+      stdio: ["inherit", "inherit", "inherit"],
+      env: mergedEnv,
+    });
+    return r.status === 0;
+  }
+
+  // Background: detached spawn via node:child_process so the parent can exit
+  // cleanly while the service keeps running. stdout+stderr append to logPath.
+  const { spawn: nodeSpawn } = require("node:child_process");
+  const { openSync } = require("node:fs");
+  const logFd = openSync(logPath, "a");
+  const child = nodeSpawn(bin, [], {
+    env: mergedEnv,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+  });
+  child.unref();
+  if (!child.pid) {
+    console.error(`${SVC_CONFIG[svc].label}: spawn failed`);
+    return false;
+  }
+  writePid(svc, child.pid);
+  console.log(`${SVC_CONFIG[svc].label} started (pid ${child.pid}, log ${logPath})`);
+
+  // Grace window: if the process dies within 800ms it almost certainly failed
+  // to start (bad env, port in use, missing dep). Surface the last log lines.
+  const start = Date.now();
+  while (Date.now() - start < 800) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 80);
+  }
+  if (!pidAlive(child.pid)) {
+    console.error(`${SVC_CONFIG[svc].label}: exited within 800ms — likely a startup error.`);
+    console.error(`  Tail of ${logPath}:`);
+    const tail = spawnSync(["tail", "-n", "20", logPath], { stdout: "pipe" });
+    if (tail.status === 0) console.error(tail.stdout.toString());
+    clearPid(svc);
+    return false;
+  }
+  return true;
+}
+
+function stopOne(svc: SvcName): boolean {
+  const pid = readPid(svc);
+  if (!pid) {
+    console.log(`${SVC_CONFIG[svc].label} not running (no PID file)`);
+    return true;
+  }
+  if (!pidAlive(pid)) {
+    console.log(`${SVC_CONFIG[svc].label} not running (stale PID file, removing)`);
+    clearPid(svc);
+    return true;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (e) {
+    console.error(`${SVC_CONFIG[svc].label}: SIGTERM failed: ${(e as Error).message}`);
+    return false;
+  }
+  console.log(`${SVC_CONFIG[svc].label}: SIGTERM sent (pid ${pid})`);
+  if (waitForExit(pid, 5000)) {
+    clearPid(svc);
+    console.log(`${SVC_CONFIG[svc].label} stopped`);
+    return true;
+  }
+  console.warn(`${SVC_CONFIG[svc].label}: did not exit in 5s, sending SIGKILL`);
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+    // best-effort
+  }
+  if (waitForExit(pid, 2000)) {
+    clearPid(svc);
+    console.log(`${SVC_CONFIG[svc].label} killed`);
+    return true;
+  }
+  console.error(`${SVC_CONFIG[svc].label}: failed to kill pid ${pid}`);
+  return false;
+}
+
+function psAll(): void {
+  console.log("ework-aio PID-file mode status:");
+  for (const svc of Object.keys(SVC_CONFIG) as SvcName[]) {
+    const pid = readPid(svc);
+    const alive = pid !== null && pidAlive(pid);
+    const cfg = SVC_CONFIG[svc];
+    if (alive) {
+      console.log(`  ${cfg.label.padEnd(18)} running   pid ${pid}   log ${svcLogPath(svc)}`);
+    } else if (pid !== null) {
+      console.log(`  ${cfg.label.padEnd(18)} dead      stale pid ${pid} (run: ework-aio stop ${svc})`);
+    } else {
+      console.log(`  ${cfg.label.padEnd(18)} stopped`);
+    }
+  }
+}
+
+function runPidMode(command: "start" | "stop" | "restart", argv: string[]): number {
+  const { svc, foreground } = parseSvcArg(argv);
+  if (command === "ps") {
+    psAll();
+    return 0;
+  }
+  const targets: SvcName[] = svc === "both" ? ["web", "daemon"] : [svc];
+  let rc = 0;
+  if (command === "stop") {
+    for (const s of targets) if (!stopOne(s)) rc = 1;
+    return rc;
+  }
+  if (command === "start") {
+    for (const s of targets) if (!startOne(s, foreground)) rc = 1;
+    return rc;
+  }
+  // restart
+  for (const s of targets) stopOne(s);
+  for (const s of targets) if (!startOne(s, foreground)) rc = 1;
+  return rc;
+}
+
+if (
+  subcommand === "start" ||
+  subcommand === "stop" ||
+  subcommand === "restart" ||
+  subcommand === "ps"
+) {
+  process.exit(runPidMode(subcommand as "start" | "stop" | "restart", args));
+}
+
+if (subcommand === "migrate") {
+  const migrateScript = resolve(__dirname, "..", "scripts", "migrate-from-gitea.ts");
+  if (!existsSync(migrateScript)) {
+    console.error(`Cannot find migrate script (looked at ${migrateScript}).`);
+    console.error("This usually means the package was installed incorrectly.");
+    process.exit(1);
+  }
+  const rest = args.slice(1);
+  const result = spawnSync(["bun", migrateScript, ...rest], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
+  if (result.status !== null) process.exit(result.status);
+  process.exit(1);
+}
+
+if (subcommand === "backfill-timestamps") {
+  const script = resolve(__dirname, "..", "scripts", "backfill-timestamps.ts");
+  if (!existsSync(script)) {
+    console.error(`Cannot find backfill-timestamps script (looked at ${script}).`);
+    process.exit(1);
+  }
+  const rest = args.slice(1);
+  const result = spawnSync(["bun", script, ...rest], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
+  if (result.status !== null) process.exit(result.status);
+  process.exit(1);
+}
+
 const finalArgs = knownSubs.includes(subcommand) ? args : ["install", ...args];
 
 const result = spawnSync(["bash", installSh, ...finalArgs], {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ework-aio",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "All-in-one installer for ework (issue tracker) + ework-daemon (AI bridge) + opencode-ework (plugin). One command: npm i -g ework-aio && ework-aio install.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
   },
   "files": [
     "bin",
+    "scripts",
     "src",
     "README.md",
     "LICENSE"