wiki-viewer 1.1.2 → 1.3.0

package/README.md

@@ -47,7 +47,11 @@ Single-user, no-auth mode still works. Auth turns on automatically once anyone s
 ## Quick start
 
 ```bash
-# Point it at a directory
+# Guided setup: directory, host/port, HTTPS, app settings, and optional
+# install as a reboot-persistent service. Recommended for first run.
+npx wiki-viewer init
+
+# Or run directly. Point it at a directory
 npx wiki-viewer ~/notes
 
 # No directory? Pick one in the browser
@@ -57,6 +61,8 @@ npx wiki-viewer
 npx wiki-viewer ~/notes --https
 ```
 
+The wizard walks you through every option and writes `~/.wiki-viewer/config.json`, so you do not have to remember flags. You can re-run it any time, or edit the config with `wiki-viewer config set`.
+
 Open **http://localhost:3000** (or **https://localhost:3000** with `--https`).
 
 To switch the served directory later, click **Change** at the bottom of the sidebar and pick a new folder. No restart needed.
@@ -119,7 +125,42 @@ The run config is saved to `~/.wiki-viewer/config.json`. Edit that file and run
 
 On Linux, install enables lingering (`loginctl enable-linger`) so the service runs without an active login session and survives reboot. If that step needs privileges, the installer prints the command to run manually.
 
-> Ad-hoc runs like `wiki-viewer ~/docs` ignore the saved config. Only the service (and `wiki-viewer service run`) reads `config.json`.
+> Ad-hoc runs like `wiki-viewer ~/docs` ignore the saved bind (dir/host/port), but still read app env from `config.json`. Only the service (and `wiki-viewer service run`) reads the full config.
+
+### App configuration (env)
+
+App settings (OAuth keys, allowlists, rate limits) are env vars. You can keep them in the config file instead of exporting them, and the service will load them on every start.
+
+```bash
+# Set at install time
+wiki-viewer service install ~/notes --env GOOGLE_CLIENT_ID=... --env GOOGLE_CLIENT_SECRET=...
+
+# Or manage them later
+wiki-viewer config set AUTH_ALLOWED_DOMAIN=example.com
+wiki-viewer config set AGENT_RATE_LIMIT=120
+wiki-viewer config unset AGENT_RATE_LIMIT
+wiki-viewer config show
+wiki-viewer service restart   # apply changes
+```
+
+These land in the `env` block of `config.json`:
+
+```json
+{
+  "rootDir": "/home/you/notes",
+  "host": "0.0.0.0",
+  "port": "3003",
+  "https": true,
+  "env": {
+    "GOOGLE_CLIENT_ID": "...",
+    "AUTH_ALLOWED_DOMAIN": "example.com"
+  }
+}
+```
+
+**Precedence:** a variable exported in your shell always wins, then the `env` block in `config.json`, then values the CLI derives for you. So you can still override anything per run with `KEY=VALUE wiki-viewer ...` or `--env KEY=VALUE`.
+
+**`BETTER_AUTH_URL` is derived automatically** from the host, port, and scheme you run with, so the common case needs no config. On `localhost` over HTTP the CLI also sets `WIKI_ALLOW_INSECURE=1` for you (browsers treat localhost as a secure context). If you serve plain HTTP on a non-local host the CLI prints a warning, because login cookies and service workers will not work there. Use `--https`, or terminate TLS in a proxy and set `BETTER_AUTH_URL` to its public `https://` URL via `config set` or your shell.
 
 ### Update
 

package/bin/wiki-viewer.js

@@ -7,6 +7,8 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from "node
 import path from "node:path";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import { stdin, stdout } from "node:process";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const appRoot = path.resolve(__dirname, "..");
@@ -31,19 +33,29 @@ function printUsage() {
   console.error("  -H, --host <host>   Host to bind to (default: localhost)");
   console.error("  --https             Enable HTTPS (self-signed cert, enables service workers)");
   console.error("");
+  console.error("  -e, --env <KEY=VALUE>  Set an app env var (repeatable; persisted with service install)");
+  console.error("");
   console.error("Commands:");
+  console.error("  init                              Interactive setup wizard (dir, host/port, https, env, service)");
   console.error("  service install [dir] [options]   Install as a user service (persists across reboot)");
   console.error("  service uninstall                 Remove the user service");
   console.error("  service status                    Show service status");
   console.error("  service logs                      Tail service logs");
+  console.error("  service restart                   Restart the service");
   console.error("  service run                       Run from saved config (used internally by the service)");
+  console.error("  config show                       Print the saved config");
+  console.error("  config set KEY=VALUE              Set an app env var in the config");
+  console.error("  config unset KEY                  Remove an app env var from the config");
   console.error("  update                            Update wiki-viewer to the latest version and restart");
   console.error("");
   console.error("Examples:");
+  console.error("  wiki-viewer init");
   console.error("  wiki-viewer ~/notes");
   console.error("  wiki-viewer ~/notes --https");
   console.error("  wiki-viewer ~/notes -p 8080 -H 0.0.0.0");
   console.error("  wiki-viewer service install ~/notes -H 0.0.0.0 -p 3003 --https");
+  console.error("  wiki-viewer service install ~/notes --env GOOGLE_CLIENT_ID=... --env GOOGLE_CLIENT_SECRET=...");
+  console.error("  wiki-viewer config set AUTH_ALLOWED_DOMAIN=example.com");
   console.error("  wiki-viewer update");
 }
 
@@ -60,6 +72,7 @@ function parseServeArgs(args) {
     const a = args[i];
     if (a === "-p" || a === "--port") { port = args[++i] ?? port; userSpecifiedPort = true; }
     else if (a === "-H" || a === "--host") host = args[++i] ?? host;
+    else if (a === "-e" || a === "--env") { i++; } // consumed by parseEnvFlags
     else if (a === "--https") useHttps = true;
     else if (!a.startsWith("-") && rootDir === undefined) rootDir = a;
   }
@@ -84,16 +97,21 @@ function saveConfig(cfg) {
   writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n");
 }
 
-// Ad-hoc serve: pure CLI flags + built-in defaults. Does NOT read the config
-// file, so an installed service never silently alters a one-off invocation.
+// Ad-hoc serve: CLI flags + built-in defaults. The run *shape* (dir/host/port)
+// does NOT read the config file, so an installed service never silently alters
+// a one-off invocation. App-level env (config.env) is still read, because those
+// are settings about the app itself (allowlists, OAuth) rather than the bind.
 function resolveServeOptions(args) {
   const cli = parseServeArgs(args);
+  const cfg = loadConfig();
   return {
     rootDir: cli.rootDir ? path.resolve(cli.rootDir) : null,
     port: String(cli.port ?? "3000"),
     host: cli.host ?? "localhost",
     useHttps: Boolean(cli.useHttps),
     userSpecifiedPort: cli.userSpecifiedPort,
+    // App env: config.env as base, ad-hoc --env flags override per run.
+    configEnv: { ...(cfg.env ?? {}), ...parseEnvFlags(args) },
   };
 }
 
@@ -117,9 +135,77 @@ function resolveRunOptions(args) {
     host,
     useHttps: Boolean(useHttps),
     userSpecifiedPort,
+    configEnv: { ...(cfg.env ?? {}), ...parseEnvFlags(args) },
   };
 }
 
+// ── environment resolution ───────────────────────────────────────────────────
+
+// Env vars the app reads that the bin can derive or manage on the user's behalf.
+// Everything else in config.env is passed through verbatim.
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", ""]);
+
+function isLocalHost(h) {
+  return LOCAL_HOSTS.has(h);
+}
+
+// Build the env for the spawned server.
+// Precedence (highest first):
+//   1. the shell environment the user launched us with (explicit override)
+//   2. config.env from ~/.wiki-viewer/config.json
+//   3. values derived by the bin from the run options (e.g. BETTER_AUTH_URL)
+//
+// Returns { env, warnings } where warnings are human-readable strings to print
+// before the server starts.
+function computeServerEnv({ host, port, useHttps, configEnv }) {
+  const warnings = [];
+  const derived = {};
+
+  const scheme = useHttps ? "https" : "http";
+  const urlHost = isLocalHost(host) || host === "0.0.0.0" ? "localhost" : host;
+  const isSecureContext = useHttps || isLocalHost(host);
+
+  // BETTER_AUTH_URL: the app requires this in production so cookies and OAuth
+  // callbacks resolve. Derive it from the bind so the common case needs no
+  // config at all.
+  derived.BETTER_AUTH_URL = `${scheme}://${urlHost}:${port}`;
+
+  // The app refuses to boot in production over an insecure context unless
+  // WIKI_ALLOW_INSECURE=1. localhost http is fine (browsers treat it as secure).
+  // Remote http is not: auth cookies and service workers will silently break.
+  if (!isSecureContext) {
+    derived.WIKI_ALLOW_INSECURE = "1";
+    warnings.push(
+      `Serving plain HTTP on a non-local host (${host}). Browsers treat this as\n` +
+      `   an insecure context: login cookies, service workers and PDF.js will not\n` +
+      `   work reliably, and OAuth callbacks will fail.\n` +
+      `   Fix: re-run with --https, or put a TLS-terminating proxy in front and set\n` +
+      `   BETTER_AUTH_URL to its public https:// URL (see "env" in ${configPath}).`,
+    );
+  } else if (isLocalHost(host) && !useHttps) {
+    // localhost http is a secure context for the browser, but the app's prod
+    // guard still wants the bypass flag set explicitly. Do it for the user.
+    derived.WIKI_ALLOW_INSECURE = "1";
+  }
+
+  // Layer: derived < config.env < shell env.
+  const env = { ...derived, ...configEnv };
+
+  // Note when the shell or config overrode a derived value so the user isn't
+  // surprised that --host/--port didn't change the auth URL.
+  if (configEnv.BETTER_AUTH_URL && configEnv.BETTER_AUTH_URL !== derived.BETTER_AUTH_URL) {
+    // config wins over derived; that's intentional, no warning needed.
+  }
+  if (process.env.BETTER_AUTH_URL && process.env.BETTER_AUTH_URL !== env.BETTER_AUTH_URL) {
+    warnings.push(
+      `BETTER_AUTH_URL is set in your shell (${process.env.BETTER_AUTH_URL}) and\n` +
+      `   overrides the derived/config value.`,
+    );
+  }
+
+  return { env, warnings };
+}
+
 // ── HTTPS cert generation ──────────────────────────────────────────────────
 
 function ensureCerts(host) {
@@ -189,7 +275,7 @@ function getNetworkAddress() {
 // ── start ──────────────────────────────────────────────────────────────────
 
 async function start(opts) {
-  const { rootDir: resolvedRoot, useHttps } = opts;
+  const { rootDir: resolvedRoot, useHttps, configEnv = {} } = opts;
   let { port, host, userSpecifiedPort } = opts;
 
   if (!existsSync(serverJs)) {
@@ -221,11 +307,18 @@ async function start(opts) {
   // Otherwise it must bind to the user-requested host directly.
   const internalHost = useHttps ? "127.0.0.1" : host;
 
+  // Resolve the app environment (config.env + shell overrides + derived
+  // BETTER_AUTH_URL etc.) against the user-facing host/port, then print any
+  // guidance before the server boots.
+  const { env: appEnv, warnings } = computeServerEnv({ host, port, useHttps, configEnv });
+  for (const w of warnings) console.log(`\n⚠️   ${w}`);
+
   const child = spawn(process.execPath, [serverJs], {
     cwd: path.join(appRoot, ".next", "standalone"),
     stdio: "inherit",
     env: {
-      ...process.env,
+      ...appEnv,         // derived defaults + config.env
+      ...process.env,    // shell env always wins over derived/config
       ...(resolvedRoot ? { ROOT_DIR: resolvedRoot } : {}),
       PORT: internalPort,
       HOSTNAME: internalHost,
@@ -310,17 +403,38 @@ function runQuiet(cmd, args) {
 
 // ── service: install ──────────────────────────────────────────────────────────
 
+// Pull repeatable `--env KEY=VALUE` (or `-e KEY=VALUE`) pairs out of an argv
+// list. Returns the collected map; the caller has already parsed the rest.
+function parseEnvFlags(args) {
+  const env = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--env" || args[i] === "-e") {
+      const pair = args[++i];
+      if (!pair || !pair.includes("=")) {
+        console.error(`Error: --env expects KEY=VALUE (got: ${pair ?? "(nothing)"})`);
+        process.exit(1);
+      }
+      const idx = pair.indexOf("=");
+      env[pair.slice(0, idx)] = pair.slice(idx + 1);
+    }
+  }
+  return env;
+}
+
 function serviceInstall(args) {
   const p = requireSupportedPlatform();
 
   // Capture the run config from flags (falling back to existing config), persist it.
   const cli = parseServeArgs(args);
+  const envFlags = parseEnvFlags(args);
   const existing = loadConfig();
+  const mergedEnv = { ...(existing.env ?? {}), ...envFlags };
   const cfg = {
     rootDir: cli.rootDir != null ? path.resolve(cli.rootDir) : existing.rootDir ?? null,
     host: cli.host ?? existing.host ?? "localhost",
     port: cli.port ?? existing.port ?? "3000",
     https: cli.useHttps ?? existing.https ?? false,
+    ...(Object.keys(mergedEnv).length ? { env: mergedEnv } : {}),
   };
   saveConfig(cfg);
   console.log(`Saved config to ${configPath}`);
@@ -328,12 +442,72 @@ function serviceInstall(args) {
   console.log(`  host:  ${cfg.host}`);
   console.log(`  port:  ${cfg.port}`);
   console.log(`  https: ${cfg.https}`);
+  if (cfg.env) {
+    console.log(`  env:   ${Object.keys(cfg.env).join(", ")}`);
+  }
   console.log("");
 
+  // Surface the same secure-context guidance the server would, at install time.
+  const { warnings } = computeServerEnv({
+    host: cfg.host, port: String(cfg.port), useHttps: Boolean(cfg.https), configEnv: cfg.env ?? {},
+  });
+  for (const w of warnings) console.log(`⚠️   ${w}\n`);
+
   if (p === "linux") installSystemd();
   else installLaunchd();
 }
 
+// `wiki-viewer config` — show or edit the saved config (incl. env).
+function configCommand(args) {
+  const cfg = loadConfig();
+
+  if (args.length === 0 || args[0] === "show" || args[0] === "list") {
+    if (!existsSync(configPath)) {
+      console.log(`No config yet at ${configPath}`);
+      console.log(`Create one with: wiki-viewer service install [dir] [options] [--env KEY=VALUE]`);
+      return;
+    }
+    console.log(configPath);
+    console.log(JSON.stringify(cfg, null, 2));
+    return;
+  }
+
+  if (args[0] === "set") {
+    const pairs = args.slice(1);
+    if (pairs.length === 0) {
+      console.error("Usage: wiki-viewer config set KEY=VALUE [KEY=VALUE ...]");
+      process.exit(1);
+    }
+    cfg.env = cfg.env ?? {};
+    for (const pair of pairs) {
+      const idx = pair.indexOf("=");
+      if (idx < 0) { console.error(`Error: expected KEY=VALUE (got: ${pair})`); process.exit(1); }
+      cfg.env[pair.slice(0, idx)] = pair.slice(idx + 1);
+    }
+    saveConfig(cfg);
+    console.log(`Updated env in ${configPath}: ${pairs.map((p) => p.split("=")[0]).join(", ")}`);
+    if (serviceIsInstalled()) console.log("Run `wiki-viewer service restart` to apply.");
+    return;
+  }
+
+  if (args[0] === "unset") {
+    const keys = args.slice(1);
+    if (keys.length === 0) { console.error("Usage: wiki-viewer config unset KEY [KEY ...]"); process.exit(1); }
+    cfg.env = cfg.env ?? {};
+    for (const k of keys) delete cfg.env[k];
+    saveConfig(cfg);
+    console.log(`Removed from env: ${keys.join(", ")}`);
+    if (serviceIsInstalled()) console.log("Run `wiki-viewer service restart` to apply.");
+    return;
+  }
+
+  if (args[0] === "path") { console.log(configPath); return; }
+
+  console.error(`Unknown config command: ${args[0]}`);
+  console.error("Try: show | set KEY=VALUE | unset KEY | path");
+  process.exit(1);
+}
+
 function installSystemd() {
   const unitDir = path.join(os.homedir(), ".config", "systemd", "user");
   mkdirSync(unitDir, { recursive: true });
@@ -519,6 +693,170 @@ function update() {
   console.log("Update complete.");
 }
 
+// ── interactive setup wizard ──────────────────────────────────────────────
+
+// Common app env vars worth offering during setup. Anything not listed can
+// still be added later with `wiki-viewer config set KEY=VALUE`.
+const WIZARD_ENV_VARS = [
+  { key: "AUTH_ALLOWED_DOMAIN", hint: "Restrict signup to an email domain, e.g. example.com" },
+  { key: "AUTH_ALLOWED_EMAILS", hint: "Restrict signup to specific emails (comma-separated)" },
+  { key: "GOOGLE_CLIENT_ID", hint: "Google OAuth client ID (enables Google sign-in)" },
+  { key: "GOOGLE_CLIENT_SECRET", hint: "Google OAuth client secret" },
+  { key: "WIKI_OWNER_HOSTS", hint: "Extra hostnames trusted for the AI panel owner cookie" },
+  { key: "AGENT_RATE_LIMIT", hint: "Per-minute agent API rate limit (default 60)" },
+];
+
+// A prompt helper that survives piped (non-TTY) stdin. node:readline/promises
+// closes the stream between awaited questions when input is piped, so we buffer
+// every line via the 'line' event and hand them out one at a time instead.
+function makePrompter() {
+  const rl = createInterface({ input: stdin, output: stdout });
+  const queue = [];
+  const waiters = [];
+  let closed = false;
+
+  rl.on("line", (line) => {
+    if (waiters.length) waiters.shift()(line);
+    else queue.push(line);
+  });
+  rl.on("close", () => {
+    closed = true;
+    while (waiters.length) waiters.shift()(null);
+  });
+
+  const nextLine = () =>
+    new Promise((resolve) => {
+      if (queue.length) resolve(queue.shift());
+      else if (closed) resolve(null);
+      else waiters.push(resolve);
+    });
+
+  const prompt = async (text) => {
+    stdout.write(text);
+    const line = await nextLine();
+    return line == null ? "" : line;
+  };
+
+  return { prompt, close: () => rl.close() };
+}
+
+async function runWizard() {
+  const io = makePrompter();
+  const existing = loadConfig();
+
+  const ask = async (label, def) => {
+    const suffix = def ? ` [${def}]` : "";
+    const answer = (await io.prompt(`${label}${suffix}: `)).trim();
+    return answer || def || "";
+  };
+  const askYesNo = async (label, defYes) => {
+    const def = defYes ? "Y/n" : "y/N";
+    const answer = (await io.prompt(`${label} [${def}]: `)).trim().toLowerCase();
+    if (!answer) return defYes;
+    return answer === "y" || answer === "yes";
+  };
+
+  try {
+    console.log("\nwiki-viewer setup\n");
+    console.log("Answer a few questions. Press Enter to accept the [default].\n");
+
+    // 1. directory
+    const dirInput = await ask(
+      "Directory to serve (blank = choose later in the browser)",
+      existing.rootDir ?? process.cwd(),
+    );
+    const rootDir = dirInput ? path.resolve(dirInput) : null;
+    if (rootDir && !existsSync(rootDir)) {
+      console.log(`  Note: ${rootDir} does not exist yet; it will be served once created.`);
+    }
+
+    // 2. host
+    const host = await ask(
+      "Host to bind (localhost for this machine only, 0.0.0.0 for the network)",
+      existing.host ?? "localhost",
+    );
+
+    // 3. port
+    const port = await ask("Port", String(existing.port ?? "3000"));
+
+    // 4. https
+    const httpsDefault = existing.https ?? (!isLocalHost(host) && host !== "0.0.0.0");
+    const useHttps = await askYesNo(
+      "Enable HTTPS? (recommended for any non-localhost access)",
+      Boolean(httpsDefault),
+    );
+
+    // 5. app env vars
+    const env = { ...(existing.env ?? {}) };
+    const wantEnv = await askYesNo(
+      "\nConfigure app settings now? (OAuth, signup allowlist, rate limit)",
+      false,
+    );
+    if (wantEnv) {
+      console.log("Leave blank to skip a setting.\n");
+      for (const { key, hint } of WIZARD_ENV_VARS) {
+        const cur = env[key];
+        const val = await ask(`  ${key} — ${hint}`, cur);
+        if (val) env[key] = val;
+        else delete env[key];
+      }
+    }
+
+    // Build and preview the config.
+    const cfg = {
+      rootDir,
+      host,
+      port,
+      https: useHttps,
+      ...(Object.keys(env).length ? { env } : {}),
+    };
+
+    console.log("\nConfiguration:");
+    console.log(`  directory : ${rootDir ?? "(choose in browser)"}`);
+    console.log(`  host      : ${host}`);
+    console.log(`  port      : ${port}`);
+    console.log(`  https     : ${useHttps}`);
+    if (cfg.env) console.log(`  app env   : ${Object.keys(cfg.env).join(", ")}`);
+
+    // Secure-context guidance before committing.
+    const { warnings } = computeServerEnv({ host, port: String(port), useHttps, configEnv: cfg.env ?? {} });
+    for (const w of warnings) console.log(`\n⚠️   ${w}`);
+
+    // 6. what to do now
+    console.log("");
+    console.log("What next?");
+    console.log("  1) Install as a service (starts now and on every reboot)");
+    console.log("  2) Run once now (foreground)");
+    console.log("  3) Save config only");
+    const choice = (await io.prompt("Choose [1/2/3]: ")).trim() || "1";
+
+    saveConfig(cfg);
+    console.log(`\nSaved ${configPath}`);
+
+    io.close();
+
+    if (choice === "1") {
+      const p = platform();
+      if (!p) {
+        console.log("Service install is only supported on Linux and macOS.");
+        console.log("Run it yourself with: wiki-viewer service run");
+        return;
+      }
+      if (p === "linux") installSystemd();
+      else installLaunchd();
+    } else if (choice === "2") {
+      start(resolveRunOptions([]));
+    } else {
+      console.log("\nStart it any time with:");
+      console.log("  wiki-viewer service install   # persistent service");
+      console.log("  wiki-viewer service run       # run from this config");
+    }
+  } finally {
+    // io may already be closed; closing twice is a no-op.
+    io.close();
+  }
+}
+
 // ── dispatch ──────────────────────────────────────────────────────────────
 
 const argv = process.argv.slice(2);
@@ -547,10 +885,26 @@ switch (cmd) {
     }
     break;
   }
+  case "config":
+    configCommand(rest);
+    break;
+  case "init":
+  case "setup":
+    runWizard();
+    break;
   case "update":
     update();
     break;
   default:
+    if (argv.includes("--setup") || argv.includes("--init")) {
+      runWizard();
+      break;
+    }
     // No recognized command → ad-hoc serve (directory + flags only).
+    // On a bare interactive run, point users at the guided setup first.
+    if (argv.length === 0 && stdin.isTTY) {
+      console.log("Tip: run `wiki-viewer init` for guided setup (directory, host/port, HTTPS,");
+      console.log("     app settings, and optional install as a reboot-persistent service).\n");
+    }
     start(resolveServeOptions(argv));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-viewer",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Local file viewer and wiki — view markdown, HTML, PDFs, notebooks, office docs, and more from any directory",
   "license": "MIT",
   "type": "module",