ework-aio 0.1.16 → 0.2.0

package/src/cli.ts

@@ -0,0 +1,467 @@
+// CLI entry point. Manual arg parser (no commander.js — the constraint is
+// no new external deps). Dispatches to command handlers under src/commands/.
+//
+// Parsing rules:
+//   - First positional = subcommand (install/uninstall/status/logs/env/
+//     config/start/stop/restart/ps/migrate/backfill-timestamps).
+//   - `install systemd` = install with --useSystemd. The literal "systemd"
+//     positional after install is the only special case.
+//   - Global flags (--data-dir, --port, --user, --system, --yes, etc.) can
+//     appear anywhere after the subcommand. `config` consumes its own
+//     subcommand position too (list/get/set/restart).
+//   - Unknown flags → error. We never silently swallow typos.
+
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { Logger, InstallError, log as defaultLogger } from "./log.ts";
+import {
+  DEFAULTS,
+  type GlobalOptions,
+  type ServiceTarget,
+} from "./types.ts";
+import { runInstall } from "./commands/install.ts";
+import { runUninstall } from "./commands/uninstall.ts";
+import {
+  runStart,
+  runStop,
+  runRestart,
+  runStatus,
+} from "./commands/lifecycle.ts";
+import { runLogs } from "./commands/logs.ts";
+import { runEnv } from "./commands/env.ts";
+import {
+  runConfig,
+  printConfigHelp,
+  type ConfigArgs,
+} from "./commands/config.ts";
+
+const VERSION = "0.2.0-dev";
+
+const USAGE = `ework-aio <command> [options]
+
+Commands:
+  install [systemd] [options]     Install or upgrade the ework stack (default).
+                                  Add 'systemd' to also write+enable systemd
+                                  units. Without 'systemd', runs in pure
+                                  PID-file mode (no systemctl calls).
+  uninstall                       Stop services and remove units (data preserved)
+  status                          Show service status (PID-file mode)
+  logs [web|daemon]               Tail logs (Ctrl+C to stop)
+  env                             Print key paths (no secrets)
+  config <subcommand>             Read / change runtime config (.env keys)
+    config list                   List all settable keys + current values
+    config get <KEY>              Print current value of one key
+    config set <KEY> <VALUE>      Set a key, then restart affected service
+                                  (unless --no-restart is given)
+    config restart <web|daemon|both>
+                                  Restart one or both services
+
+  start [web|daemon|both]         Start services in PID-file mode (default both)
+  stop [web|daemon|both]          Stop services (SIGTERM, 5s grace, then SIGKILL)
+  restart [web|daemon|both]       Stop + start
+  ps                              Show PID-file mode status (alias for 'status')
+
+  migrate [options]               Migrate issues from a Gitea instance
+  backfill-timestamps             Fix timestamps on already-migrated data
+
+Install options:
+  systemd                         Also install systemd units + enable them
+  --user                          (with systemd) user-level units (default)
+  --system                        (with systemd) system-level units (needs sudo)
+  --data-dir <path>               Override data directory
+                                  (default ~/.local/share/ework-aio)
+  --port <n>                      ework-web port (default ${DEFAULTS.workPort})
+  --daemon-port <n>               ework-daemon port (default ${DEFAULTS.daemonPort})
+  --bot-name <login>              Bot username (default ${DEFAULTS.botName})
+  --no-start                      Install but don't start services
+  --yes (-y)                      Skip all prompts (use generated defaults)
+  --as-user <login>               (sudo only) drop privileges: re-exec install
+                                  as <login> after enabling linger
+  --allow-root                    (sudo only) override refuse-on-root default
+
+Global options:
+  --no-restart                    With 'config set': edit .env but skip restart
+  -h, --help                      Show this help
+  -v, --version                   Print version
+`;
+
+export interface ParsedArgs {
+  subcommand: string;
+  opts: GlobalOptions;
+  positionals: string[];
+  configArgs: ConfigArgs;
+}
+
+function defaultOpts(): GlobalOptions {
+  return {
+    workPort: DEFAULTS.workPort,
+    daemonPort: DEFAULTS.daemonPort,
+    botName: DEFAULTS.botName,
+    scope: DEFAULTS.scope,
+    useSystemd: false,
+    assumeYes: false,
+    allowRoot: false,
+    noRestart: false,
+    noStart: false,
+  };
+}
+
+// parseArgs: manual argv walk. Returns typed result. Throws InstallError
+// on unknown flags / missing values. The shape is stable so tests can
+// exercise it without touching process.argv.
+export function parseArgs(argv: string[]): ParsedArgs {
+  const opts = defaultOpts();
+  const positionals: string[] = [];
+  const configArgs: ConfigArgs = { subcommand: "list" };
+  let inConfig = false;
+  let useSystemdFromPositional = false;
+  // S-1: track if scope was explicitly chosen. Under EUID=0 we used to
+  // silently flip default "user" → "system"; that hid the fact that root
+  // can't run user-scope systemd (XDG_RUNTIME_DIR unset). Now: defaulted
+  // scope still flips (back-compat), explicit --user under root throws.
+  let scopeExplicit = false;
+
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === undefined) break;
+
+    // `config` consumes its own positional subcommand.
+    if (!inConfig && a === "config" && positionals.length === 0) {
+      inConfig = true;
+      positionals.push("config");
+      i++;
+      const peek = (k: number): string | undefined => {
+        const v = argv[k];
+        return typeof v === "string" && !v.startsWith("-") ? v : undefined;
+      };
+      // First positional after `config` is its subcommand. If absent or
+      // not a recognized subcommand name, fall through to "list" (default)
+      // or "help" (if user typed something unknown).
+      const sub = peek(i);
+      if (sub === undefined) {
+        // `config` alone — default to list.
+      } else if (sub === "list" || sub === "get" || sub === "set" || sub === "restart" || sub === "help") {
+        configArgs.subcommand = sub;
+        i++;
+        if (sub === "get") {
+          const key = peek(i);
+          if (key !== undefined) { configArgs.key = key; i++; }
+        } else if (sub === "set") {
+          const key = peek(i);
+          if (key !== undefined) { configArgs.key = key; i++; }
+          const value = peek(i);
+          if (value !== undefined) { configArgs.value = value; i++; }
+        } else if (sub === "restart") {
+          // Distinguish "no target given" (default to both) from "typo
+          // target given" (reject). Without this, `config restart bogus`
+          // silently restarts both services — a real foot-gun in production.
+          const next = argv[i];
+          if (next === "web" || next === "daemon" || next === "both") {
+            configArgs.target = next;
+            i++;
+          } else if (next !== undefined && !next.startsWith("-")) {
+            throw new InstallError(
+              `config restart: invalid target '${next}'. Expected: web | daemon | both`,
+            );
+          }
+        }
+      } else {
+        // Unknown config subcommand — fall through to help.
+        configArgs.subcommand = "help";
+        i++;
+      }
+      continue;
+    }
+
+    if (a === "-h" || a === "--help") {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    if (a === "-v" || a === "--version") {
+      process.stdout.write(`${VERSION}\n`);
+      process.exit(0);
+    }
+
+    // Boolean flags
+    if (a === "systemd") {
+      useSystemdFromPositional = true;
+      i++;
+      continue;
+    }
+    if (a === "--user") { opts.scope = "user"; scopeExplicit = true; i++; continue; }
+    if (a === "--system") { opts.scope = "system"; scopeExplicit = true; i++; continue; }
+    if (a === "--yes" || a === "-y") { opts.assumeYes = true; i++; continue; }
+    if (a === "--allow-root") { opts.allowRoot = true; i++; continue; }
+    if (a === "--no-start") { opts.noStart = true; i++; continue; }
+    if (a === "--no-restart") { opts.noRestart = true; i++; continue; }
+
+    // Value flags (--flag <value>)
+    if (a === "--data-dir") {
+      const v = argv[++i];
+      if (v === undefined) throw new InstallError("--data-dir requires a value");
+      opts.dataDir = v;
+      i++;
+      continue;
+    }
+    if (a === "--port") {
+      const v = argv[++i];
+      if (v === undefined) throw new InstallError("--port requires a value");
+      const n = Number.parseInt(v, 10);
+      if (!Number.isFinite(n) || n <= 0 || n > 65535) {
+        throw new InstallError(`--port: invalid value '${v}' (must be 1-65535)`);
+      }
+      opts.workPort = n;
+      i++;
+      continue;
+    }
+    if (a === "--daemon-port") {
+      const v = argv[++i];
+      if (v === undefined) throw new InstallError("--daemon-port requires a value");
+      const n = Number.parseInt(v, 10);
+      if (!Number.isFinite(n) || n <= 0 || n > 65535) {
+        throw new InstallError(`--daemon-port: invalid value '${v}' (must be 1-65535)`);
+      }
+      opts.daemonPort = n;
+      i++;
+      continue;
+    }
+    if (a === "--bot-name") {
+      const v = argv[++i];
+      if (v === undefined) throw new InstallError("--bot-name requires a value");
+      opts.botName = v;
+      i++;
+      continue;
+    }
+    if (a === "--as-user") {
+      const v = argv[++i];
+      if (v === undefined) throw new InstallError("--as-user requires a value");
+      opts.asUser = v;
+      i++;
+      continue;
+    }
+
+    if (a.startsWith("--")) {
+      throw new InstallError(`Unknown option: ${a} (try --help)`);
+    }
+
+    // Positional (e.g. "install", "web", "daemon", "both")
+    positionals.push(a);
+    i++;
+  }
+
+  if (useSystemdFromPositional) opts.useSystemd = true;
+
+  // S-1: explicit --user under root would silently fail later (systemd
+  // user-scope needs XDG_RUNTIME_DIR which root doesn't have). Default
+  // scope (no flag) still flips to "system" under root for back-compat.
+  if (process.getuid && process.getuid() === 0 && opts.scope === "user") {
+    if (scopeExplicit) {
+      throw new InstallError(
+        "--user cannot be used when running as root: user-scope systemd needs XDG_RUNTIME_DIR which root does not have. " +
+        "Either drop privileges (run as a regular user) or use --system.",
+      );
+    }
+    opts.scope = "system";
+  }
+
+  // S-10: --port and --daemon-port must differ (otherwise both services
+  // fight for the same port and neither binds).
+  if (opts.workPort === opts.daemonPort) {
+    throw new InstallError(
+      `--port and --daemon-port must differ (both are ${opts.workPort})`,
+    );
+  }
+
+  const subcommand = positionals[0] ?? "install";
+
+  return { subcommand, opts, positionals, configArgs };
+}
+
+function parseServiceTarget(arg: string | undefined): ServiceTarget {
+  if (arg === undefined || arg === "") return "both";
+  if (arg === "web" || arg === "daemon" || arg === "both") return arg;
+  throw new InstallError(
+    `Invalid service target '${arg}'. Expected: web | daemon | both`,
+  );
+}
+
+// handleAsUser: when invoked with --as-user (typically via sudo), re-exec
+// the install as the named user after enabling linger. Skipped if not root
+// or no --as-user flag.
+function handleAsUser(opts: GlobalOptions, argv: string[]): void {
+  if (!opts.asUser) return;
+  if (process.getuid && process.getuid() !== 0) {
+    throw new InstallError("--as-user requires running as root (use sudo)");
+  }
+  const target = opts.asUser;
+
+  // Resolve target user's home + uid via getpwnam equivalent (os.userInfo
+  // doesn't take a name arg, so we shell out to `id`).
+  const idRes = spawnSync("id", ["-u", target], { encoding: "utf8" });
+  if (idRes.status !== 0 || !idRes.stdout.trim()) {
+    throw new InstallError(`--as-user: user '${target}' not found`);
+  }
+  const targetUid = Number.parseInt(idRes.stdout.trim(), 10);
+  if (!Number.isFinite(targetUid)) {
+    throw new InstallError(`--as-user: could not parse uid for '${target}'`);
+  }
+  if (targetUid === 0) {
+    throw new InstallError(`--as-user: target '${target}' is root — use --allow-root instead`);
+  }
+
+  // Enable linger so user-level systemd services survive logout.
+  const linger = spawnSync("loginctl", ["enable-linger", target], { encoding: "utf8" });
+  if (linger.status !== 0) {
+    throw new InstallError(
+      `Failed to enable linger for '${target}': ${linger.stderr?.trim() ?? ""}. ` +
+      `Try: sudo loginctl enable-linger ${target}`,
+    );
+  }
+
+  // Re-exec as target user with --as-user stripped from argv.
+  const self = process.argv[1]!;
+  const newArgs = argv.filter((a) => a !== "--as-user" && a !== opts.asUser!);
+  const result = spawnSync("sudo", ["-u", target, "--login", self, ...newArgs], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.status !== null) process.exit(result.status);
+  process.exit(1);
+}
+
+// enforceRootGuard: refuse install as root unless --allow-root or --as-user.
+// Matches install.sh's root guard. Install is the only command that needs
+// this — other commands are read-only or scoped to user data.
+function enforceRootGuard(opts: GlobalOptions, logger: Logger): void {
+  if (!process.getuid || process.getuid() !== 0) return;
+  if (opts.asUser) return; // handled above
+  if (opts.allowRoot) {
+    logger.warn("running install as root with --allow-root — data will live under /root");
+    return;
+  }
+  process.stderr.write(
+    `ework-aio install refuses to run as root by default.\n\n` +
+    `Why this matters:\n` +
+    `  - Data goes under /root/.local/share/ework-aio (unreadable by other users)\n` +
+    `  - opencode is searched in root's PATH (usually not installed there)\n` +
+    `  - npm packages install to system-wide prefix owned by root\n\n` +
+    `Option A (recommended): run as a regular user.\n` +
+    `  npm config set prefix '~/.local'\n` +
+    `  npm install -g ework-aio\n` +
+    `  ework-aio install\n\n` +
+    `Option B: install with sudo but target a regular user.\n` +
+    `  sudo ework-aio install --as-user ${os.userInfo().username}\n\n` +
+    `Option C: really install as root.\n` +
+    `  sudo ework-aio install --allow-root\n`,
+  );
+  process.exit(1);
+}
+
+// main: parse + dispatch. Returns exit code.
+export async function main(
+  argv: string[],
+  logger: Logger = defaultLogger,
+): Promise<number> {
+  let parsed: ParsedArgs;
+  try {
+    parsed = parseArgs(argv);
+  } catch (err) {
+    if (err instanceof InstallError) {
+      logger.error(err.message);
+      return err.code;
+    }
+    throw err;
+  }
+
+  const { subcommand, opts, positionals, configArgs } = parsed;
+
+  // --as-user triggers a re-exec; this never returns.
+  if (opts.asUser && (subcommand === "install" || subcommand === undefined)) {
+    handleAsUser(opts, argv);
+    return 1;
+  }
+
+  try {
+    switch (subcommand) {
+      case "install": {
+        enforceRootGuard(opts, logger);
+        await runInstall(opts, logger);
+        return 0;
+      }
+      case "uninstall": {
+        await runUninstall(opts, logger);
+        return 0;
+      }
+      case "status":
+      case "ps": {
+        await runStatus(opts, logger);
+        return 0;
+      }
+      case "logs": {
+        const svc = positionals[1] === "daemon" ? "daemon" : "web";
+        await runLogs(opts, logger, svc);
+        return 0;
+      }
+      case "env": {
+        await runEnv(opts, logger);
+        return 0;
+      }
+      case "config": {
+        if (configArgs.subcommand === "help") {
+          printConfigHelp(logger);
+          return 0;
+        }
+        await runConfig(opts, logger, configArgs);
+        return 0;
+      }
+      case "start": {
+        const target = parseServiceTarget(positionals[1]);
+        await runStart(opts, logger, target);
+        return 0;
+      }
+      case "stop": {
+        const target = parseServiceTarget(positionals[1]);
+        await runStop(opts, logger, target);
+        return 0;
+      }
+      case "restart": {
+        const target = parseServiceTarget(positionals[1]);
+        await runRestart(opts, logger, target);
+        return 0;
+      }
+      case "migrate": {
+        return runDelegateScript("migrate-from-gitea.ts", argv.slice(1));
+      }
+      case "backfill-timestamps": {
+        return runDelegateScript("backfill-timestamps.ts", argv.slice(1));
+      }
+      default:
+        logger.error(`Unknown command: ${subcommand} (try --help)`);
+        return 1;
+    }
+  } catch (err) {
+    if (err instanceof InstallError) {
+      logger.error(err.message);
+      return err.code;
+    }
+    logger.error(`unexpected error: ${(err as Error).message}`);
+    logger.error((err as Error).stack ?? "");
+    return 1;
+  }
+}
+
+// runDelegateScript: hand off to a sibling TS script via bun. Used for
+// migrate + backfill-timestamps which live in scripts/ and have their own
+// arg surfaces we don't want to absorb into cli.ts.
+function runDelegateScript(scriptName: string, args: string[]): number {
+  const scriptPath = new URL(`../scripts/${scriptName}`, import.meta.url).pathname;
+  const result = spawnSync("bun", [scriptPath, ...args], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
+  if (result.status !== null) return result.status;
+  return 1;
+}
+
+// Entry-point is bin/ework-aio only. Tests import main() directly.

package/src/commands/config.ts

@@ -0,0 +1,208 @@
+// `ework-aio config <subcommand>` — read/change runtime .env keys.
+//
+// Subcommands:
+//   list                          Show all settable keys + current values
+//   get <KEY>                     Print one key's value
+//   set <KEY> <VALUE>             Write to .env, then restart affected service
+//                                 (use --no-restart to skip)
+//   restart <web|daemon|both>     Restart one or both services
+//
+// Allow-list: only keys in SETTABLE_KEYS (src/types.ts) are exposed.
+// Secrets, DB paths, and the web<->daemon contract keys are deliberately
+// excluded — those need `rm .env && ework-aio install` to regenerate.
+//
+// Cross-link propagation: when WORK_PORT changes, the daemon .env's
+// GITEA_URL is rewritten; when DAEMON_PORT changes, the web .env's
+// WORK_DAEMON_WEBHOOK_URL is rewritten. Both services then restart.
+
+import fs from "node:fs";
+import path from "node:path";
+import { Logger, InstallError } from "../log.ts";
+import { resolvePaths } from "../paths.ts";
+import { parseEnvFile, patchEnvKey } from "../env.ts";
+import { SECRET_ENV_VARS } from "../config.ts";
+import {
+  SETTABLE_KEYS,
+  findSettableKey,
+  serviceForKey,
+  type GlobalOptions,
+  type ServiceTarget,
+} from "../types.ts";
+import { runRestart } from "./lifecycle.ts";
+
+function envFileForService(
+  svc: "web" | "daemon",
+  paths: ReturnType<typeof resolvePaths>,
+): string {
+  return svc === "web" ? paths.webEnvFile : paths.daemonEnvFile;
+}
+
+async function readEnvKey(envFile: string, key: string): Promise<string | null> {
+  try {
+    const content = await Bun.file(envFile).text();
+    const v = parseEnvFile(content).entries.get(key);
+    return v !== undefined ? v : null;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export async function configList(opts: GlobalOptions, logger: Logger): Promise<void> {
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: opts.useSystemd });
+  logger.hr();
+  logger.log("Settable config keys");
+  logger.hr();
+  logger.log(`  ${"KEY".padEnd(28)} ${"SERVICE".padEnd(8)} VALUE`);
+  for (const entry of SETTABLE_KEYS) {
+    const envFile = envFileForService(entry.service, paths);
+    let val = await readEnvKey(envFile, entry.key);
+    if (val === null) val = "(unset)";
+    logger.log(`  ${entry.key.padEnd(28)} ${entry.service.padEnd(8)} ${val}`);
+  }
+  logger.hr();
+  logger.log(`Use ${logger.bold("config set <KEY> <VALUE>")} to change a key.`);
+}
+
+export async function configGet(
+  opts: GlobalOptions,
+  logger: Logger,
+  key: string,
+): Promise<void> {
+  const entry = findSettableKey(key);
+  if (!entry) {
+    throw new InstallError(
+      `Key '${key}' is not settable. Run 'ework-aio config list' for the allow-list.`,
+    );
+  }
+  if (SECRET_ENV_VARS.has(key)) {
+    throw new InstallError(
+      `Key '${key}' is a secret — use 'rm .env && ework-aio install' to regenerate.`,
+    );
+  }
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: opts.useSystemd });
+  const envFile = envFileForService(entry.service, paths);
+  const val = await readEnvKey(envFile, key);
+  if (val === null) {
+    logger.warn(`${key} is not currently set in ${envFile}`);
+    return;
+  }
+  process.stdout.write(`${val}\n`);
+}
+
+export async function configSet(
+  opts: GlobalOptions,
+  logger: Logger,
+  key: string,
+  value: string,
+): Promise<void> {
+  const entry = findSettableKey(key);
+  if (!entry) {
+    throw new InstallError(
+      `Key '${key}' is not settable. Run 'ework-aio config list' for the allow-list.`,
+    );
+  }
+  if (SECRET_ENV_VARS.has(key)) {
+    throw new InstallError(
+      `Key '${key}' is a secret — use 'rm .env && ework-aio install' to regenerate.`,
+    );
+  }
+  // .env is a line-oriented format; a value containing a newline would be
+  // parsed as two entries by parseEnvFile. Reject it outright so a stray
+  // shell expansion (e.g. $'alice\nWORK_TOKEN=evil') can't inject keys.
+  if (/[\r\n]/.test(value)) {
+    throw new InstallError(
+      `Value for ${key} contains a newline — multi-line values are not allowed in .env (got ${value.length} chars)`,
+    );
+  }
+
+  const paths = resolvePaths({ dataDir: opts.dataDir, scope: opts.scope, useSystemd: opts.useSystemd });
+  const envFile = envFileForService(entry.service, paths);
+
+  logger.log(`setting ${key}=${value} in ${envFile}`);
+  await patchEnvKey(envFile, key, value);
+  logger.ok(`${key} updated`);
+
+  if (entry.propagate) {
+    const targetFile = envFileForService(entry.propagate.targetService, paths);
+    const newVal = entry.propagate.template(value);
+    logger.log(`propagating to ${entry.propagate.targetService} (${entry.propagate.targetKey})`);
+    await patchEnvKey(targetFile, entry.propagate.targetKey, newVal);
+    logger.ok(`${entry.propagate.targetService} .env updated`);
+  }
+
+  if (opts.noRestart) {
+    const target = serviceForKey(key) ?? "both";
+    logger.warn(`--no-restart: changes saved but service not reloaded. Run 'ework-aio config restart ${target}' to apply.`);
+    return;
+  }
+
+  const target: ServiceTarget = serviceForKey(key) ?? "both";
+  logger.log(`restarting ${target}...`);
+  await runRestart(opts, logger, target);
+}
+
+export async function configRestart(
+  opts: GlobalOptions,
+  logger: Logger,
+  target: ServiceTarget,
+): Promise<void> {
+  await runRestart(opts, logger, target);
+}
+
+export interface ConfigArgs {
+  subcommand: "list" | "get" | "set" | "restart" | "help";
+  key?: string;
+  value?: string;
+  target?: ServiceTarget;
+}
+
+export async function runConfig(
+  opts: GlobalOptions,
+  logger: Logger,
+  args: ConfigArgs,
+): Promise<void> {
+  switch (args.subcommand) {
+    case "list":
+      await configList(opts, logger);
+      return;
+    case "get":
+      if (!args.key) throw new InstallError("Usage: ework-aio config get <KEY>");
+      await configGet(opts, logger, args.key);
+      return;
+    case "set":
+      if (!args.key || args.value === undefined) {
+        throw new InstallError("Usage: ework-aio config set <KEY> <VALUE>");
+      }
+      await configSet(opts, logger, args.key, args.value);
+      return;
+    case "restart":
+      await configRestart(opts, logger, args.target ?? "both");
+      return;
+    case "help":
+      printConfigHelp(logger);
+      return;
+  }
+}
+
+export function printConfigHelp(logger: Logger): void {
+  logger.log(`ework-aio config <subcommand>`);
+  logger.log(``);
+  logger.log(`Subcommands:`);
+  logger.log(`  list                          List all settable keys + current values`);
+  logger.log(`  get <KEY>                     Print current value of one key`);
+  logger.log(`  set <KEY> <VALUE>             Set a key in .env, then restart the affected`);
+  logger.log(`                                service (unless --no-restart is given)`);
+  logger.log(`  restart <web|daemon|both>     Restart one or both services`);
+  logger.log(``);
+  logger.log(`Examples:`);
+  logger.log(`  ework-aio config list`);
+  logger.log(`  ework-aio config get WORK_PORT`);
+  logger.log(`  ework-aio config set WORK_PORT 8080`);
+  logger.log(`  ework-aio config set WORK_TRANSLATE_URL http://127.0.0.1:8000/v1 --no-restart`);
+  logger.log(`  ework-aio config restart both`);
+  logger.log(``);
+  logger.log(`Note: changing WORK_PORT or DAEMON_PORT also rewrites the cross-link the other`);
+  logger.log(`service uses, and restarts both. Secrets and DB paths are not settable here —`);
+  logger.log(`rerun \`ework-aio install\` (with \`rm .env\` first if you need new tokens).`);
+}

package/src/commands/env.ts

@@ -0,0 +1,27 @@
+// `ework-aio env` — print resolved paths (no secrets). Useful for users
+// to find where data, .env files, and the bot token live without grepping.
+
+import { Logger } from "../log.ts";
+import { resolvePaths } from "../paths.ts";
+import type { GlobalOptions } from "../types.ts";
+
+export async function runEnv(opts: GlobalOptions, logger: Logger): Promise<void> {
+  const paths = resolvePaths({
+    dataDir: opts.dataDir,
+    scope: opts.scope,
+    useSystemd: opts.useSystemd,
+  });
+
+  logger.hr();
+  logger.log("ework-aio paths");
+  logger.hr();
+  logger.log(`  data dir      : ${paths.dataDir}`);
+  logger.log(`  web env       : ${paths.webEnvFile}`);
+  logger.log(`  daemon env    : ${paths.daemonEnvFile}`);
+  logger.log(`  bot token     : ${paths.botTokenFile}`);
+  logger.log(`  opencode cfg  : ${paths.opencodeConfigFile}`);
+  logger.log(`  scope         : ${opts.scope}`);
+  logger.log(`  mode          : ${opts.useSystemd ? "systemd" : "PID-file"}`);
+  logger.log(`  web unit      : ${paths.webUnitFile ?? "(not used)"}`);
+  logger.log(`  daemon unit   : ${paths.daemonUnitFile ?? "(not used)"}`);
+}