ework-aio 0.1.17 → 0.2.1

package/src/log.ts

@@ -0,0 +1,102 @@
+// Pretty-printer for install / CLI output. Mirrors the bash aesthetic from
+// bin/install.sh (• for log, ✓ for ok, ! for warn, ✗ for die, ── for hr)
+// but with TS types and injectable stream so tests can capture output.
+
+const isTTY = process.stdout.isTTY ?? false;
+
+// Minimal stream interface — narrower than the full WriteStream type so
+// stdout (fd 1) and stderr (fd 2) are both assignable without friction.
+interface WritableStreamLike {
+  write(chunk: string | Uint8Array): boolean;
+  isTTY?: boolean;
+}
+
+function colorEnabled(stream: WritableStreamLike): boolean {
+  // Per no-color.org spec: ANY presence of NO_COLOR in the environment
+  // (including empty string) disables color. The truthy check
+  // `if (process.env.NO_COLOR)` treats `NO_COLOR=` as "not set", which
+  // violates the spec and surprises users who export the empty value
+  // explicitly (e.g. shell rc files).
+  if ("NO_COLOR" in process.env) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return stream.isTTY ?? false;
+}
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+} as const;
+
+export interface LoggerOptions {
+  stdout?: WritableStreamLike;
+  stderr?: WritableStreamLike;
+}
+
+export class Logger {
+  private readonly stdout: WritableStreamLike;
+  private readonly stderr: WritableStreamLike;
+  private readonly stdoutColor: boolean;
+  private readonly stderrColor: boolean;
+
+  constructor(opts: LoggerOptions = {}) {
+    this.stdout = opts.stdout ?? process.stdout;
+    this.stderr = opts.stderr ?? process.stderr;
+    this.stdoutColor = colorEnabled(this.stdout);
+    this.stderrColor = colorEnabled(this.stderr);
+  }
+
+  private paint(stream: WritableStreamLike, enabled: boolean, ...parts: Array<string>): string {
+    return parts.map((p) => (enabled ? p : p.replace(/\x1b\[[0-9;]*m/g, ""))).join("");
+  }
+
+  log(msg: string): void {
+    const line = this.paint(this.stdout, this.stdoutColor, `${C.blue}•${C.reset} `, msg, "\n");
+    this.stdout.write(line);
+  }
+
+  ok(msg: string): void {
+    const line = this.paint(this.stdout, this.stdoutColor, `${C.green}✓${C.reset} `, msg, "\n");
+    this.stdout.write(line);
+  }
+
+  warn(msg: string): void {
+    const line = this.paint(this.stderr, this.stderrColor, `${C.yellow}!${C.reset} `, msg, "\n");
+    this.stderr.write(line);
+  }
+
+  error(msg: string): void {
+    const line = this.paint(this.stderr, this.stderrColor, `${C.red}✗${C.reset} `, msg, "\n");
+    this.stderr.write(line);
+  }
+
+  hr(): void {
+    const line = this.paint(this.stdout, this.stdoutColor, `${C.dim}──${C.reset}`, "\n");
+    this.stdout.write(line);
+  }
+
+  bold(msg: string): string {
+    return this.paint(this.stdout, this.stdoutColor, `${C.bold}${msg}${C.reset}`);
+  }
+
+  dim(msg: string): string {
+    return this.paint(this.stdout, this.stdoutColor, `${C.dim}${msg}${C.reset}`);
+  }
+}
+
+export const log = new Logger();
+
+// InstallError: typed fatal for install flow. Distinct from generic Error so
+// catch sites can tell "expected install failure" from "unexpected crash".
+export class InstallError extends Error {
+  readonly code: number;
+  constructor(message: string, code: number = 1) {
+    super(message);
+    this.name = "InstallError";
+    this.code = code;
+  }
+}

package/src/opencode-config.ts

@@ -0,0 +1,104 @@
+// opencode.json read/write + plugin registration. Replaces jq with
+// JSON.parse/stringify. Treats the file as untrusted input — malformed
+// JSON throws a typed error, not a raw SyntaxError.
+
+import fs from "node:fs";
+import path from "node:path";
+import { InstallError } from "./log.ts";
+
+export interface OpencodeConfig {
+  // Unknown-key passthrough — preserves fields we don't know about.
+  [key: string]: unknown;
+  plugins?: Array<string | { name: string; [k: string]: unknown }>;
+}
+
+export interface ReadConfigResult {
+  config: OpencodeConfig;
+  existed: boolean;
+}
+
+export async function readConfig(configPath: string): Promise<ReadConfigResult> {
+  let content: string;
+  try {
+    content = await Bun.file(configPath).text();
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { config: {}, existed: false };
+    }
+    throw err;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    throw new InstallError(
+      `${configPath} contains malformed JSON: ${(err as Error).message}`,
+    );
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new InstallError(
+      `${configPath} must be a JSON object at the top level (got ${Array.isArray(parsed) ? "array" : typeof parsed})`,
+    );
+  }
+
+  return { config: parsed as OpencodeConfig, existed: true };
+}
+
+export async function writeConfig(configPath: string, config: OpencodeConfig): Promise<void> {
+  const dir = path.dirname(configPath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const tmp = path.join(dir, `.opencode.json.tmp.${process.pid}.${Date.now()}`);
+  const content = JSON.stringify(config, null, 2) + "\n";
+  await fs.promises.writeFile(tmp, content, { mode: 0o644 });
+  try {
+    await fs.promises.rename(tmp, configPath);
+  } catch (err) {
+    await fs.promises.unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+function normalizePluginEntry(entry: unknown): string | null {
+  // Plugin entries can be either "name" (string) or { name: "...", ...opts }.
+  if (typeof entry === "string") return entry;
+  if (entry !== null && typeof entry === "object") {
+    const name = (entry as { name?: unknown }).name;
+    if (typeof name === "string") return name;
+  }
+  return null;
+}
+
+export function hasPlugin(config: OpencodeConfig, pluginName: string): boolean {
+  const plugins = config.plugins;
+  if (!Array.isArray(plugins)) return false;
+  return plugins.some((p) => normalizePluginEntry(p) === pluginName);
+}
+
+export function ensurePlugin(config: OpencodeConfig, pluginName: string): { config: OpencodeConfig; added: boolean } {
+  if (hasPlugin(config, pluginName)) {
+    return { config, added: false };
+  }
+  const next: OpencodeConfig = { ...config };
+  next.plugins = [...(Array.isArray(config.plugins) ? config.plugins : []), pluginName];
+  return { config: next, added: true };
+}
+
+export function removePlugin(config: OpencodeConfig, pluginName: string): { config: OpencodeConfig; removed: boolean } {
+  if (!hasPlugin(config, pluginName)) {
+    return { config, removed: false };
+  }
+  const next: OpencodeConfig = { ...config };
+  const plugins = Array.isArray(config.plugins) ? config.plugins : [];
+  next.plugins = plugins.filter((p) => normalizePluginEntry(p) !== pluginName);
+  return { config: next, removed: true };
+}
+
+export async function ensurePluginInFile(configPath: string, pluginName: string): Promise<{ added: boolean }> {
+  const { config } = await readConfig(configPath);
+  const result = ensurePlugin(config, pluginName);
+  if (!result.added) return { added: false };
+  await writeConfig(configPath, result.config);
+  return { added: true };
+}

package/src/paths.ts

@@ -0,0 +1,95 @@
+// Path resolution for ework-aio. All file system paths used by install
+// flow through here so tests can override via env vars.
+//
+// Hierarchy:
+//   DATA_DIR (default: $XDG_DATA_HOME/ework-aio or ~/.local/share/ework-aio)
+//   ├── ework-web/                  (web service data)
+//   │   ├── .env                    (web env file)
+//   │   ├── ework.db                (web SQLite DB)
+//   │   └── attachments/            (uploaded files)
+//   ├── ework-daemon/               (daemon service data)
+//   │   ├── .env                    (daemon env file)
+//   │   └── ework-daemon.db         (daemon SQLite DB)
+//   ├── run/                        (PID files + logs for PID-file mode)
+//   │   ├── web.{pid,log}
+//   │   └── daemon.{pid,log}
+//   ├── bot-token                   (persisted bot PAT)
+//   └── opencode-workdir/           (opencode working directory base)
+
+import path from "node:path";
+import os from "node:os";
+
+export interface PathConfig {
+  dataDir: string;
+  webDataDir: string;
+  daemonDataDir: string;
+  webEnvFile: string;
+  daemonEnvFile: string;
+  runDir: string;
+  botTokenFile: string;
+  opencodeWorkdir: string;
+  opencodeConfigFile: string;
+  webDbPath: string;
+  daemonDbPath: string;
+  webAttachmentRoot: string;
+  webPidFile: string;
+  daemonPidFile: string;
+  webLogFile: string;
+  daemonLogFile: string;
+  webUnitFile: string | null;    // null when not using systemd
+  daemonUnitFile: string | null;
+}
+
+export interface ResolvePathsOptions {
+  dataDir?: string;            // override via --data-dir
+  configHome?: string;         // override XDG_CONFIG_HOME for tests
+  scope: "user" | "system";    // systemd scope (affects unit file location)
+  useSystemd: boolean;         // if false, webUnitFile/daemonUnitFile are null
+}
+
+export function resolvePaths(opts: ResolvePathsOptions): PathConfig {
+  const home = os.homedir();
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  // opts.configHome takes precedence over XDG_CONFIG_HOME so tests can
+  // pin a config dir without polluting or reading the user's real
+  // ~/.config. The previous precedence (env || opts || default) meant
+  // a developer with XDG_CONFIG_HOME set couldn't override it from tests,
+  // and test runs would leak into the real config dir.
+  const xdgConfigHome = opts.configHome
+    || process.env.XDG_CONFIG_HOME
+    || path.join(home, ".config");
+
+  const dataDir = opts.dataDir || path.join(xdgDataHome, "ework-aio");
+  const webDataDir = path.join(dataDir, "ework-web");
+  const daemonDataDir = path.join(dataDir, "ework-daemon");
+  const runDir = path.join(dataDir, "run");
+
+  // Unit file location depends on scope and whether systemd is opted-in
+  let unitDir: string | null = null;
+  if (opts.useSystemd) {
+    unitDir = opts.scope === "system"
+      ? "/etc/systemd/system"
+      : path.join(xdgConfigHome, "systemd", "user");
+  }
+
+  return {
+    dataDir,
+    webDataDir,
+    daemonDataDir,
+    webEnvFile: path.join(webDataDir, ".env"),
+    daemonEnvFile: path.join(daemonDataDir, ".env"),
+    runDir,
+    botTokenFile: path.join(dataDir, "bot-token"),
+    opencodeWorkdir: path.join(dataDir, "opencode-workdir"),
+    opencodeConfigFile: path.join(xdgConfigHome, "opencode", "opencode.json"),
+    webDbPath: path.join(webDataDir, "ework.db"),
+    daemonDbPath: path.join(daemonDataDir, "ework-daemon.db"),
+    webAttachmentRoot: path.join(webDataDir, "attachments"),
+    webPidFile: path.join(runDir, "web.pid"),
+    daemonPidFile: path.join(runDir, "daemon.pid"),
+    webLogFile: path.join(runDir, "web.log"),
+    daemonLogFile: path.join(runDir, "daemon.log"),
+    webUnitFile: unitDir ? path.join(unitDir, "ework-web.service") : null,
+    daemonUnitFile: unitDir ? path.join(unitDir, "ework-daemon.service") : null,
+  };
+}

package/src/pidfile.ts

@@ -0,0 +1,166 @@
+// Detached process management (PID-file mode).
+//
+// Replaces bash `setsid nohup <cmd> & echo $! > pidfile; disown`.
+// Uses node:child_process.spawn with detached:true + child.unref() so the
+// parent can exit without taking the child down. stdio is redirected to a
+// log file so we don't lose stdout/stderr after parent exit.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface StartProcessOptions {
+  cmd: string;
+  args: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  logFile: string;
+  pidFile: string;
+}
+
+export interface StartProcessResult {
+  pid: number;
+}
+
+export class PidFileError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PidFileError";
+  }
+}
+
+export async function startProcess(opts: StartProcessOptions): Promise<StartProcessResult> {
+  await fs.promises.mkdir(path.dirname(opts.logFile), { recursive: true });
+  await fs.promises.mkdir(path.dirname(opts.pidFile), { recursive: true });
+
+  // sync open — Bun's async FileHandle has a finalizer that closes the fd
+  // when GC'd, which can race with the child inheriting it via stdio.
+  // openSync returns a raw fd we own; spawn() dups it for the child.
+  const logFd = fs.openSync(opts.logFile, "a", 0o644);
+
+  let child: ChildProcess;
+  try {
+    child = spawn(opts.cmd, opts.args, {
+      cwd: opts.cwd,
+      env: opts.env,
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+    });
+  } catch (err) {
+    fs.closeSync(logFd);
+    throw new PidFileError(`Failed to spawn ${opts.cmd}: ${(err as Error).message}`);
+  }
+
+  // Bun/node:spawn returns a ChildProcess even when the binary doesn't
+  // exist (ENOENT) — child.pid stays undefined and an 'error' event is
+  // emitted on next tick. Without a handler the event becomes an
+  // uncaughtException that takes down the test runner (and on long-running
+  // ework-aio, the install). The no-pid check below catches this case
+  // synchronously; this handler suppresses the redundant async 'error'.
+  child.on("error", () => { /* handled via pid check below */ });
+
+  if (typeof child.pid !== "number") {
+    // S-2: logFd was opened above; we own it until spawn() inherits it
+    // via stdio. On the no-pid failure path the child didn't actually
+    // take over the fd, so we must close it before throwing — otherwise
+    // the fd leaks until process exit (and on long-running installs
+    // holding the log file open blocks log rotation).
+    fs.closeSync(logFd);
+    throw new PidFileError(`Spawned ${opts.cmd} but no pid was assigned`);
+  }
+
+  const pid = child.pid;
+
+  child.unref();
+
+  fs.closeSync(logFd);
+
+  await writePidFileAtomic(opts.pidFile, pid);
+
+  return { pid };
+}
+
+export async function writePidFileAtomic(pidFile: string, pid: number): Promise<void> {
+  const dir = path.dirname(pidFile);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const suffix = `${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}`;
+  const tmp = path.join(dir, `.pid.tmp.${suffix}`);
+  await fs.promises.writeFile(tmp, `${pid}\n`, { mode: 0o644 });
+  try {
+    await fs.promises.rename(tmp, pidFile);
+  } catch (err) {
+    await fs.promises.unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+export async function readPidFile(pidFile: string): Promise<number | null> {
+  try {
+    const content = await fs.promises.readFile(pidFile, "utf8");
+    const pid = parseInt(content.trim(), 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export function isProcessRunning(pid: number): boolean {
+  try {
+    // signal 0 = existence check, no actual signal sent
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ESRCH") return false;   // No such process
+    if ((err as NodeJS.ErrnoException).code === "EPERM") return true;    // Exists but not ours
+    throw err;
+  }
+}
+
+export async function stopProcess(
+  pidFile: string,
+  opts: { graceMs?: number; sigkillAfter?: boolean } = {},
+): Promise<{ pid: number; killed: boolean; timedOut: boolean }> {
+  const graceMs = opts.graceMs ?? 5000;
+  const pid = await readPidFile(pidFile);
+  if (pid === null) {
+    throw new PidFileError(`PID file ${pidFile} not found or empty`);
+  }
+  if (!isProcessRunning(pid)) {
+    // Stale pidfile; clean up.
+    await fs.promises.unlink(pidFile).catch(() => {});
+    return { pid, killed: false, timedOut: false };
+  }
+
+  process.kill(pid, "SIGTERM");
+
+  const deadline = Date.now() + graceMs;
+  while (Date.now() < deadline) {
+    if (!isProcessRunning(pid)) {
+      await fs.promises.unlink(pidFile).catch(() => {});
+      return { pid, killed: true, timedOut: false };
+    }
+    await sleep(100);
+  }
+
+  if (opts.sigkillAfter === false) {
+    return { pid, killed: false, timedOut: true };
+  }
+
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ESRCH") {
+      await fs.promises.unlink(pidFile).catch(() => {});
+      return { pid, killed: true, timedOut: true };
+    }
+    throw err;
+  }
+  await fs.promises.unlink(pidFile).catch(() => {});
+  return { pid, killed: true, timedOut: true };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/preflight.ts

@@ -0,0 +1,48 @@
+import { spawnSync } from "node:child_process";
+
+export interface PreflightResult {
+  missing: string[];
+  found: Map<string, string>;
+  optional: Map<string, string | null>;
+}
+
+export interface PreflightOptions {
+  optionalCommands?: string[];
+}
+
+export function resolveCommand(cmd: string): string | null {
+  const result = spawnSync("sh", ["-c", `command -v ${JSON.stringify(cmd)}`], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    // Pass env explicitly — Bun's spawnSync doesn't pick up process.env
+    // mutations if env is omitted (unlike Node which inherits at spawn).
+    env: process.env,
+  });
+  if (result.status !== 0) return null;
+  const path = result.stdout.trim();
+  return path === "" ? null : path;
+}
+
+export function checkPreflight(
+  required: string[],
+  opts: PreflightOptions = {},
+): PreflightResult {
+  const missing: string[] = [];
+  const found = new Map<string, string>();
+  const optional = new Map<string, string | null>();
+
+  for (const cmd of required) {
+    const path = resolveCommand(cmd);
+    if (path === null) missing.push(cmd);
+    else found.set(cmd, path);
+  }
+
+  for (const cmd of opts.optionalCommands ?? []) {
+    optional.set(cmd, resolveCommand(cmd));
+  }
+
+  return { missing, found, optional };
+}
+
+export const REQUIRED_COMMANDS: readonly string[] = ["bun", "npm", "opencode"];
+export const OPTIONAL_COMMANDS: readonly string[] = ["systemctl", "sudo"];