ework-aio 0.1.16 → 0.2.0

package/src/commands/lifecycle.ts

@@ -0,0 +1,206 @@
+// PID-file mode lifecycle: start / stop / restart / status.
+//
+// Each command targets a service ("web" | "daemon") or "both". Services
+// are detached (startProcess uses spawn+unref) so they survive the CLI's
+// exit. PIDs land in <dataDir>/run/<svc>.pid, logs in <dataDir>/run/<svc>.log.
+//
+// `status` reports per-service: PID, alive?, port (if listed in .env),
+// and a one-line fetch probe (so users see "✓ listening" vs "✗ not
+// responding" without having to curl themselves).
+
+import { Logger, InstallError } from "../log.ts";
+import { resolvePaths, type PathConfig } from "../paths.ts";
+import {
+  startProcess,
+  stopProcess,
+  readPidFile,
+  isProcessRunning,
+} from "../pidfile.ts";
+import { parseEnvFile } from "../env.ts";
+import { resolveCommand } from "../preflight.ts";
+import type { GlobalOptions, ServiceTarget } from "../types.ts";
+
+interface ServicePaths {
+  bin: string;
+  dataDir: string;
+  envFile: string;
+  pidFile: string;
+  logFile: string;
+  portKey: string | null;
+}
+
+function servicePaths(paths: PathConfig, svc: "web" | "daemon"): ServicePaths {
+  if (svc === "web") {
+    return {
+      bin: "ework-web",
+      dataDir: paths.webDataDir,
+      envFile: paths.webEnvFile,
+      pidFile: paths.webPidFile,
+      logFile: paths.webLogFile,
+      portKey: "WORK_PORT",
+    };
+  }
+  return {
+    bin: "ework-daemon",
+    dataDir: paths.daemonDataDir,
+    envFile: paths.daemonEnvFile,
+    pidFile: paths.daemonPidFile,
+    logFile: paths.daemonLogFile,
+    portKey: "DAEMON_PORT",
+  };
+}
+
+async function loadEnv(envFile: string): Promise<NodeJS.ProcessEnv> {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  try {
+    const content = await Bun.file(envFile).text();
+    const parsed = parseEnvFile(content);
+    for (const [k, v] of parsed.entries) env[k] = v;
+  } catch {
+    // missing .env → fall back to process.env only
+  }
+  return env;
+}
+
+async function startOne(
+  svc: "web" | "daemon",
+  paths: PathConfig,
+  logger: Logger,
+): Promise<boolean> {
+  const sp = servicePaths(paths, svc);
+  const binPath = resolveCommand(sp.bin);
+  if (!binPath) {
+    throw new InstallError(`${sp.bin} not found on PATH — install with: npm install -g ${sp.bin}`);
+  }
+  const existingPid = await readPidFile(sp.pidFile);
+  if (existingPid !== null && isProcessRunning(existingPid)) {
+    logger.log(`ework-${svc} already running (pid ${existingPid})`);
+    return false;
+  }
+  const env = await loadEnv(sp.envFile);
+  const { pid } = await startProcess({
+    cmd: binPath,
+    args: [],
+    cwd: sp.dataDir,
+    env,
+    logFile: sp.logFile,
+    pidFile: sp.pidFile,
+  });
+  logger.ok(`ework-${svc} started (pid ${pid}, log ${sp.logFile})`);
+  return true;
+}
+
+async function stopOne(svc: "web" | "daemon", paths: PathConfig, logger: Logger): Promise<boolean> {
+  const sp = servicePaths(paths, svc);
+  try {
+    const result = await stopProcess(sp.pidFile, { graceMs: 5000, sigkillAfter: true });
+    if (result.killed) {
+      logger.ok(`ework-${svc} stopped (pid ${result.pid}${result.timedOut ? ", SIGKILL after timeout" : ""})`);
+    } else {
+      logger.log(`ework-${svc} was not running (stale pidfile cleaned)`);
+    }
+    return result.killed;
+  } catch (err) {
+    if (err instanceof Error && /not found or empty/.test(err.message)) {
+      logger.log(`ework-${svc} not running (no pidfile at ${sp.pidFile})`);
+      return false;
+    }
+    throw err;
+  }
+}
+
+function targets(target: ServiceTarget): Array<"web" | "daemon"> {
+  return target === "both" ? ["web", "daemon"] : [target];
+}
+
+export async function runStart(
+  opts: GlobalOptions,
+  logger: Logger,
+  target: ServiceTarget,
+): Promise<void> {
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: false });
+  for (const svc of targets(target)) {
+    await startOne(svc, paths, logger);
+  }
+}
+
+export async function runStop(
+  opts: GlobalOptions,
+  logger: Logger,
+  target: ServiceTarget,
+): Promise<void> {
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: false });
+  for (const svc of targets(target)) {
+    await stopOne(svc, paths, logger);
+  }
+}
+
+export async function runRestart(
+  opts: GlobalOptions,
+  logger: Logger,
+  target: ServiceTarget,
+): Promise<void> {
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: false });
+  for (const svc of targets(target)) {
+    await stopOne(svc, paths, logger);
+    await startOne(svc, paths, logger);
+  }
+}
+
+export interface StatusEntry {
+  svc: "web" | "daemon";
+  pid: number | null;
+  alive: boolean;
+  port: number | null;
+  listening: boolean | null;
+}
+
+export async function runStatus(opts: GlobalOptions, logger: Logger): Promise<StatusEntry[]> {
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: false });
+
+  logger.hr();
+  logger.log("ework-aio status (PID-file mode)");
+  logger.hr();
+
+  const entries: StatusEntry[] = [];
+  for (const svc of ["web", "daemon"] as const) {
+    const sp = servicePaths(paths, svc);
+    const pid = await readPidFile(sp.pidFile);
+    const alive = pid !== null && isProcessRunning(pid);
+
+    let port: number | null = null;
+    try {
+      const content = await Bun.file(sp.envFile).text();
+      const portStr = parseEnvFile(content).entries.get(sp.portKey ?? "");
+      if (portStr) port = Number.parseInt(portStr, 10) || null;
+    } catch {
+      // missing .env → no port
+    }
+
+    let listening: boolean | null = null;
+    if (port !== null) {
+      // web exposes /login; daemon doesn't. Probe a per-service URL so the
+      // status line doesn't lie about the daemon being "not responding"
+      // when it's actually healthy.
+      const probeUrl = svc === "web"
+        ? `http://127.0.0.1:${port}/login`
+        : `http://127.0.0.1:${port}/`;
+      try {
+        const r = await fetch(probeUrl, { method: "GET" });
+        listening = r.status < 500;
+      } catch {
+        listening = false;
+      }
+    }
+
+    entries.push({ svc, pid, alive, port, listening });
+
+    const pidStr = pid === null ? "—" : `pid ${pid}`;
+    const aliveStr = alive ? "✓ running" : "✗ not running";
+    const portStr = port === null ? "(no port in .env)" : `:${port}`;
+    const listenStr = listening === null ? "" : listening ? " ✓ listening" : " ✗ not responding";
+    logger.log(`  ework-${svc.padEnd(8)} ${pidStr.padEnd(10)} ${aliveStr}  ${portStr}${listenStr}`);
+  }
+  logger.hr();
+  return entries;
+}

package/src/commands/logs.ts

@@ -0,0 +1,71 @@
+// `ework-aio logs [web|daemon]` — tail -f the PID-file log file.
+//
+// Pure-TS implementation (no `tail -f` shell-out — the constraint is JS
+// handles 99% of cases, only bun/npm/opencode/sudo/systemctl are
+// whitelisted). Uses fs.watchFile to poll for size changes; appends new
+// bytes to stdout. Polling is portable across Linux/macOS/WSL without
+// inotify quirks.
+
+import fs from "node:fs";
+import { Logger, InstallError } from "../log.ts";
+import { resolvePaths } from "../paths.ts";
+import type { GlobalOptions } from "../types.ts";
+
+export async function runLogs(
+  opts: GlobalOptions,
+  logger: Logger,
+  svc: "web" | "daemon",
+): Promise<void> {
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: false });
+  const logFile = svc === "web" ? paths.webLogFile : paths.daemonLogFile;
+
+  if (!fs.existsSync(logFile)) {
+    throw new InstallError(
+      `log file not found at ${logFile}. Start the service first: ework-aio start ${svc}`,
+    );
+  }
+
+  logger.log(`tailing ${logFile} (Ctrl+C to stop)`);
+
+  const fd = fs.openSync(logFile, "r");
+  let size = fs.fstatSync(fd).size;
+
+  // Print the last 200 lines on attach.
+  const headBytes = Math.min(size, 8192);
+  const headBuf = Buffer.alloc(headBytes);
+  fs.readSync(fd, headBuf, 0, headBytes, size - headBytes);
+  const headText = headBuf.toString("utf8");
+  const headLines = headText.split("\n");
+  const recent = headLines.slice(Math.max(0, headLines.length - 201)).join("\n");
+  process.stdout.write(recent);
+
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    fs.unwatchFile(logFile);
+    fs.closeSync(fd);
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+
+  // Poll every 500ms — fs.watchFile default is 5007ms which feels laggy.
+  fs.watchFile(logFile, { interval: 500 }, (curr) => {
+    if (curr.size > size) {
+      const len = curr.size - size;
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, size);
+      process.stdout.write(buf.toString("utf8"));
+      size = curr.size;
+    } else if (curr.size < size) {
+      // File was truncated (log rotation). Reset to end.
+      size = curr.size;
+    }
+  });
+
+  // Hold the process open until signal.
+  await new Promise<void>(() => {
+    // never resolves; signal handler exits
+  });
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,64 @@
+// Uninstall: stop services, remove systemd units (if installed), preserve
+// all user data. Idempotent — missing units or stale PID files are not
+// errors. Data dir is never touched; user removes it manually if desired.
+
+import { Logger } from "../log.ts";
+import { resolvePaths } from "../paths.ts";
+import { stopProcess } from "../pidfile.ts";
+import { removeUnit, getUnitState, type SystemctlOptions } from "../systemd.ts";
+import type { GlobalOptions } from "../types.ts";
+
+export async function runUninstall(opts: GlobalOptions, logger: Logger): Promise<void> {
+  const paths = resolvePaths({
+    dataDir: opts.dataDir,
+    scope: opts.scope,
+    useSystemd: opts.useSystemd,
+  });
+
+  logger.hr();
+  logger.log("uninstalling ework-aio services (keeping data)");
+  logger.hr();
+
+  // 1. Stop PID-file mode services (best-effort).
+  for (const svc of ["web", "daemon"] as const) {
+    const pidFile = svc === "web" ? paths.webPidFile : paths.daemonPidFile;
+    try {
+      const result = await stopProcess(pidFile, { graceMs: 5000, sigkillAfter: true });
+      if (result.killed) {
+        logger.ok(`stopped ework-${svc} (pid ${result.pid})`);
+      }
+    } catch (err) {
+      if (err instanceof Error && /not found or empty/.test(err.message)) {
+        // No PID file — service wasn't running in PID-file mode. Fine.
+      } else {
+        logger.warn(`stop ework-${svc} failed: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  // 2. Remove systemd units (only if installed with --useSystemd).
+  if (opts.useSystemd && paths.webUnitFile && paths.daemonUnitFile) {
+    const unitOpts: SystemctlOptions = { scope: opts.scope };
+    for (const svc of ["ework-web", "ework-daemon"] as const) {
+      const state = getUnitState(svc, unitOpts);
+      if (state === "unknown") {
+        // Unit not loaded — nothing to remove.
+        continue;
+      }
+      try {
+        const unitFile = svc === "ework-web" ? paths.webUnitFile : paths.daemonUnitFile;
+        await removeUnit(svc, unitFile, unitOpts);
+        logger.ok(`removed ${svc}.service`);
+      } catch (err) {
+        logger.warn(`remove ${svc}.service failed: ${(err as Error).message}`);
+      }
+    }
+  } else {
+    logger.log("(PID-file mode — no systemd units to remove)");
+  }
+
+  // 3. Print recovery hint.
+  logger.hr();
+  logger.ok(`services removed. data preserved at ${paths.dataDir}`);
+  logger.warn(`to fully remove: rm -rf ${paths.dataDir} && npm uninstall -g ework-aio ework-web ework-daemon opencode-ework`);
+}

package/src/config.ts

@@ -0,0 +1,88 @@
+// Single source of truth for ework-web + ework-daemon .env keys.
+//
+// Each key has:
+//   - envVar:     the literal env var name written to .env
+//   - generate(): returns the value to use when forward-filling a missing key
+//   - secret?:    true if the value is sensitive (token, secret, password)
+//                 — used to redact in `config list` output
+//
+// The forward-fill principle: when a user re-runs install and we preserve
+// their existing .env, we walk this list and append any missing keys with
+// freshly generated values. User-set values are NEVER overwritten.
+//
+// This schema MUST stay in sync with ework-web's src/config.ts (the runtime
+// Zod parser). Any new required field added there must be added here too,
+// otherwise stale .env files will crash the next start (the v0.1.17 bug).
+
+import { randomBytes } from "node:crypto";
+import type { PathConfig } from "./paths.ts";
+
+export type EnvFile = "web" | "daemon";
+
+export interface InstallContext {
+  paths: PathConfig;
+  workPort: number;
+  daemonPort: number;
+  botName: string;
+  operatorLogin: string;
+  // opencode binary path (looked up via preflight)
+  opencodeBin: string;
+}
+
+export interface EnvKeySpec {
+  envVar: string;
+  file: EnvFile;
+  secret?: boolean;
+  generate: (ctx: InstallContext) => string;
+}
+
+const hex = (bytes: number): string => randomBytes(bytes).toString("hex");
+
+export const WEB_ENV_KEYS: readonly EnvKeySpec[] = [
+  { envVar: "WORK_PORT",                   file: "web", generate: (c) => String(c.workPort) },
+  { envVar: "WORK_HOST",                   file: "web", generate: () => "127.0.0.1" },
+  { envVar: "WORK_TOKEN",                  file: "web", secret: true, generate: () => hex(20) },
+  { envVar: "WORK_COOKIE_SECRET",          file: "web", secret: true, generate: () => hex(24) },
+  { envVar: "WORK_OPERATOR_LOGIN",         file: "web", generate: (c) => c.operatorLogin },
+  { envVar: "WORK_WRITES_ENABLED",         file: "web", generate: () => "true" },
+  { envVar: "WORK_DB_PATH",                file: "web", generate: (c) => c.paths.webDbPath },
+  { envVar: "WORK_ATTACHMENT_ROOT",        file: "web", generate: (c) => c.paths.webAttachmentRoot },
+  { envVar: "WORK_FILE_ROOTS",             file: "web", generate: (c) => `/tmp,${c.paths.dataDir}` },
+  { envVar: "WORK_DAEMON_BOT_LOGIN",       file: "web", generate: (c) => c.botName },
+  { envVar: "WORK_DAEMON_WEBHOOK_URL",     file: "web", generate: (c) => `http://127.0.0.1:${c.daemonPort}` },
+  { envVar: "WORK_DAEMON_WEBHOOK_SECRET",  file: "web", secret: true, generate: () => hex(20) },
+] as const;
+
+export const DAEMON_ENV_KEYS: readonly EnvKeySpec[] = [
+  { envVar: "DAEMON_ENV",             file: "daemon", generate: () => "production" },
+  { envVar: "DAEMON_PORT",            file: "daemon", generate: (c) => String(c.daemonPort) },
+  { envVar: "DAEMON_HOST",            file: "daemon", generate: () => "127.0.0.1" },
+  { envVar: "DAEMON_DB_PATH",         file: "daemon", generate: (c) => c.paths.daemonDbPath },
+  { envVar: "GITEA_URL",              file: "daemon", generate: (c) => `http://127.0.0.1:${c.workPort}` },
+  // These tokens come from the bot bootstrap flow — empty placeholder here,
+  // filled in by write_daemon_env after PAT is minted.
+  { envVar: "GITEA_TOKEN",            file: "daemon", secret: true, generate: () => "" },
+  { envVar: "GITEA_WEBHOOK_SECRET",   file: "daemon", secret: true, generate: (c) => hex(20) },
+  { envVar: "BOT_USERNAME",           file: "daemon", generate: (c) => c.botName },
+  { envVar: "BOT_TOKEN",              file: "daemon", secret: true, generate: () => "" },
+  { envVar: "OPENCODE_BINARY",        file: "daemon", generate: (c) => c.opencodeBin },
+  { envVar: "OPENCODE_BASE_WORKDIR",  file: "daemon", generate: (c) => c.paths.opencodeWorkdir },
+] as const;
+
+export function keysForFile(file: EnvFile): readonly EnvKeySpec[] {
+  return file === "web" ? WEB_ENV_KEYS : DAEMON_ENV_KEYS;
+}
+
+// Set of env vars that, if missing, would crash ework-web or ework-daemon
+// at startup (Zod schema rejects). Used by env.ts forward-fill to log
+// which keys were injected.
+export const REQUIRED_KEYS: ReadonlySet<string> = new Set([
+  ...WEB_ENV_KEYS.map((k) => k.envVar),
+  ...DAEMON_ENV_KEYS.map((k) => k.envVar),
+]);
+
+// Keys whose value should be redacted in `config list` output.
+export const SECRET_ENV_VARS: ReadonlySet<string> = new Set([
+  ...WEB_ENV_KEYS.filter((k) => k.secret).map((k) => k.envVar),
+  ...DAEMON_ENV_KEYS.filter((k) => k.secret).map((k) => k.envVar),
+]);

package/src/env.ts

@@ -0,0 +1,219 @@
+// .env file read / write / preserve / forward-fill.
+//
+// The v0.1.17 bug we're regressing against: install.sh preserved existing
+// .env files verbatim, never injecting schema-required keys that were
+// missing. When ework-web's Zod schema grew new required fields, old .env
+// files crashed on next startup. fix(install): forward-fill missing
+// schema-required keys (bc6b065) was the bash patch; this is the TS port.
+
+import fs from "node:fs";
+import path from "node:path";
+import { keysForFile, type EnvFile, type InstallContext } from "./config.ts";
+
+export interface EnvMap {
+  // Preserves insertion order, matching how .env is read + written.
+  readonly entries: ReadonlyMap<string, string>;
+}
+
+export interface ForwardFillResult {
+  // Keys that were added (envVar names).
+  added: string[];
+  // Final map after merge.
+  merged: Map<string, string>;
+}
+
+// parseEnvFile: read a .env file into an ordered map. Format:
+//   KEY=value        → entry
+//   KEY="value"      → entry, quotes stripped
+//   # comment        → skipped (preserved on write via rawLines)
+//   <blank>          → skipped (preserved on write via rawLines)
+// Malformed lines are skipped with a warning (caller decides whether to fail).
+export interface ParsedEnvFile {
+  entries: Map<string, string>;
+  // Raw lines preserved in original order, for writeback that doesn't
+  // disturb user comments / formatting. New keys are appended after the
+  // last non-blank non-comment line.
+  rawLines: string[];
+}
+
+export function parseEnvFile(content: string): ParsedEnvFile {
+  const entries = new Map<string, string>();
+  const rawLines = content.split(/\r?\n/);
+  for (const line of rawLines) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = line.slice(0, eqIdx).trim();
+    let value = line.slice(eqIdx + 1);
+    // Strip matching surrounding quotes if present.
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) entries.set(key, value);
+  }
+  return { entries, rawLines };
+}
+
+// forwardFill: given a parsed .env and an InstallContext, ensure every
+// required key for the given file (web or daemon) is present. Missing
+// keys are appended to rawLines + merged. Existing keys are NEVER touched.
+export function forwardFill(
+  parsed: ParsedEnvFile,
+  file: EnvFile,
+  ctx: InstallContext,
+): ForwardFillResult {
+  const added: string[] = [];
+  const merged = new Map(parsed.entries);
+
+  for (const spec of keysForFile(file)) {
+    if (merged.has(spec.envVar)) continue;
+    const value = spec.generate(ctx);
+    merged.set(spec.envVar, value);
+    added.push(spec.envVar);
+  }
+
+  return { added, merged };
+}
+
+// serializeEnvFile: write a map back to .env format, preserving raw lines
+// for keys that already existed and appending new keys at the end.
+export function serializeEnvFile(parsed: ParsedEnvFile, added: Array<{ key: string; value: string }>): string {
+  const out: string[] = [...parsed.rawLines];
+  while (out.length > 0) {
+    const last = out[out.length - 1];
+    if (last === undefined || last.trim() !== "") break;
+    out.pop();
+  }
+
+  if (added.length > 0) {
+    if (out.length > 0) {
+      const last = out[out.length - 1];
+      if (last !== undefined && last !== "") out.push("");
+    }
+    const now = new Date().toISOString();
+    out.push(`# ework-aio forward-fill at ${now}`);
+    for (const { key, value } of added) {
+      out.push(`${key}=${value}`);
+    }
+  }
+  return out.join("\n") + "\n";
+}
+
+// readEnvFile: read + parse, return null if file doesn't exist.
+export async function readEnvFile(filePath: string): Promise<ParsedEnvFile | null> {
+  try {
+    const content = await Bun.file(filePath).text();
+    return parseEnvFile(content);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+// writeEnvFileAtomic: write .env via temp file + rename, mode 0600.
+// Atomic so a crash mid-write doesn't leave a corrupt .env.
+export async function writeEnvFileAtomic(filePath: string, content: string): Promise<void> {
+  const dir = path.dirname(filePath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const tmp = path.join(dir, `.env.tmp.${process.pid}.${Date.now()}`);
+  await fs.promises.writeFile(tmp, content, { mode: 0o600 });
+  try {
+    await fs.promises.rename(tmp, filePath);
+  } catch (err) {
+    await fs.promises.unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+// ensureEnvFile: top-level entry for write_web_env / write_daemon_env.
+// Reads existing .env (if any), forward-fills missing keys, writes back
+// atomically. Returns the list of keys that were added.
+export interface EnsureEnvOptions {
+  file: EnvFile;
+  filePath: string;
+  ctx: InstallContext;
+  // If true and file doesn't exist, generate fresh values for ALL keys
+  // (not just required ones). Default true.
+  freshIfMissing?: boolean;
+}
+
+export async function ensureEnvFile(opts: EnsureEnvOptions): Promise<{ added: string[]; created: boolean }> {
+  const existing = await readEnvFile(opts.filePath);
+  if (existing === null) {
+    // Fresh file: synthesize an empty ParsedEnvFile so forwardFill adds all keys.
+    const fresh: ParsedEnvFile = { entries: new Map(), rawLines: [] };
+    const result = forwardFill(fresh, opts.file, opts.ctx);
+    const now = new Date().toISOString();
+    const header = `# Generated by ework-aio at ${now}\n`;
+    const body = serializeEnvFile(fresh, result.added.map((key) => ({
+      key,
+      value: result.merged.get(key) ?? "",
+    })));
+    await writeEnvFileAtomic(opts.filePath, header + body);
+    return { added: result.added, created: true };
+  }
+
+  const result = forwardFill(existing, opts.file, opts.ctx);
+  if (result.added.length === 0) {
+    // Nothing to do — preserve the file untouched.
+    return { added: [], created: false };
+  }
+
+  const body = serializeEnvFile(existing, result.added.map((key) => ({
+    key,
+    value: result.merged.get(key) ?? "",
+  })));
+  await writeEnvFileAtomic(opts.filePath, body);
+  return { added: result.added, created: false };
+}
+
+// patchEnvKey: rewrite a single key in .env, preserving all other lines,
+// then write atomically (temp + rename, mode 0600). Used by config set
+// and install.ts (BOT_TOKEN injection after forward-fill).
+//
+// If the file doesn't exist, it's created with just this key. If the key
+// already exists, its value is replaced in-place. Otherwise the key is
+// appended after the last non-blank line.
+//
+// Key matching uses the same tolerance as parseEnvFile: leading/trailing
+// whitespace around `=` is accepted (`KEY = value` matches key `KEY`).
+// Without this alignment, patch would append a duplicate line instead of
+// replacing, and downstream parseEnvFile would silently pick one of the
+// two values depending on iteration order.
+export async function patchEnvKey(envFile: string, key: string, value: string): Promise<void> {
+  let content = "";
+  try {
+    content = await Bun.file(envFile).text();
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+  const lines = content.split(/\r?\n/);
+  let found = false;
+  for (const [i, line] of lines.entries()) {
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) continue;
+    // Skip comment lines (parseEnvFile ignores leading '#' too).
+    if (line.slice(0, eqIdx).trim().startsWith("#")) continue;
+    if (line.slice(0, eqIdx).trim() === key) {
+      lines[i] = `${key}=${value}`;
+      found = true;
+      break;
+    }
+  }
+  if (!found) {
+    // Trim trailing blank lines, then append.
+    while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+    if (lines.length > 0) lines.push("");
+    lines.push(`${key}=${value}`);
+  } else {
+    // On in-place replace, `content.split(/\r?\n/)` keeps a trailing "" if
+    // the file ended with `\n` (the common case). Joining back with "\n"
+    // reproduces the trailing "\n", so we'd otherwise double it below.
+    while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  }
+  await writeEnvFileAtomic(envFile, lines.join("\n") + "\n");
+}