Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

15.8 KB
Raw Blame
/**
 * Server runtime config (ServerConfig) — parsed from environment variables.
 *
 * The data root directory is shared with the SDK / CLI (`resolveRoot()`:
 * ADELIE_HOME or ~/.adelie/data); the SQLite index database defaults to
 * `<root>/web.db` (overridable via ADELIE_WEB_DB, tests use ":memory:").
 * In production, the SPA is served statically once the frontend build output
 * directory (ADELIE_WEB_DIST, the bundled web-dist/, or ../web/dist) is
 * detected to exist.
 * The five deployment variables below are read in both spellings — see
 * core's state/boundary-env.ts for why their writers are outside this repository.
 * Docs: /docs/configuration § "Environment variables".
 */
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import {
  boundaryEnv,
  DEFAULT_SERVER_PORT,
  LEGACY_ROOT_ENV,
  resolveRoot,
  ROOT_ENV,
} from "@adelie/core";
import { checkoutCliEntry } from "./services/cli-shim.js";

export interface ServerConfig {
  /** Local data root directory (shared with the SDK/CLI). */
  root: string;
  /** HTTP listen address and port (defaults to 127.0.0.1:4000, Adelie's own Web port — upstream serves on 7364). */
  host: string;
  /**
   * Listen port. `0` asks the OS for an ephemeral port (the desktop shell always does),
   * in which case the value is only a request: index.ts writes the ACTUAL bound port back
   * here once listening, because preview URLs are built from the server's own port rather
   * than the browser's (dev serves the SPA on a different port; see resolvePreviewTarget).
   */
  port: number;
  /** SQLite database path; ":memory:" for test injection. */
  dbPath: string;
  /** Frontend static assets directory; whether it's enabled is decided by checking existence when the app is assembled. */
  webDist: string;
  /**
   * Origin that serves Workspace HTML previews (ADELIE_PREVIEW_ORIGIN), e.g.
   * `https://preview.example.com`. It must differ from the App origin by **hostname** —
   * cookies ignore ports, so a second port would still share the session cookie. Unset
   * is the norm locally: the loopback counterpart (`127.0.0.1` <-> `localhost`) is
   * derived per request instead.
   */
  previewOrigin: string | null;
  /**
   * Trusted Penguin Go origin, never supplied by a browser request.
   *
   * OPTIONAL like `cliEntry`: a runtime older than this field publishes none, and a pushed
   * platform must still boot there — its consumer (PlatformAuthProvider) then falls back to
   * the default `normalizePenguinGoOrigin(undefined)` returns.
   */
  penguinGoOrigin?: string;
  /**
   * Base URL of the ModelScope authorization bridge (MODELSCOPE_BRIDGE_URL), without a
   * trailing slash — e.g. `https://go.penguin.ooo/modelscope`. The harness sends the
   * start/poll exchange here and never to ModelScope itself: the bridge holds the OAuth
   * client secret. Unlike `penguinGoOrigin` this value carries a path prefix in production,
   * because the bridge is mounted under one and strips it from the incoming request.
   *
   * OPTIONAL for the same reason as `penguinGoOrigin`; ModelScopeAuthProvider defaults it.
   */
  modelscopeBridgeUrl?: string;
  /**
   * Fixed initial password for the seeded built-in admin (ADELIE_SEED_ADMIN_PASSWORD),
   * used by automated tests and e2e. Null is the norm: the seed then generates a random
   * password that is hashed and discarded unseen, and the account is claimed through the
   * first-login link instead.
   */
  seedAdminPassword: string | null;
  /** Login session validity period (30 days). */
  authSessionTtlMs: number;
  /**
   * Sliding renewal threshold: a session validated with less than this much left is renewed to
   * the full TTL. Set one day below the TTL, so any session used at least a day after it was
   * issued renews — in practice a session in regular use never expires, and the TTL is the
   * idle timeout.
   */
  authSessionRenewMs: number;
  /**
   * Desktop mode (ADELIE_DESKTOP_TOKEN; the pre-rename PENGUIN_DESKTOP_TOKEN is read too): the
   * per-launch token minted by the desktop
   * shell. Non-null enables the one-shot claim link and the Bearer-token shutdown
   * endpoints and requires a loopback HOST — desktop mode passes the token through a
   * URL, which must never leave the machine.
   */
  desktopToken: string | null;
  /**
   * Whether `penguin server|web` supervises this process (ADELIE_SUPERVISED=1) and relaunches
   * it when it exits with core's SERVER_RESTART_EXIT_CODE — what makes the web UI's "restart
   * to update" possible. False under a direct server start, a dev run, or the desktop shell.
   *
   * Required, unlike cliEntry below: the hot-update seam names it in the
   * config interface it claims (hmr/capabilities.ts's HMR_INTERFACES), and a runtime that
   * publishes a lifecycle capability publishes this field with it — the two arrived together.
   */
  supervised: boolean;
  /**
   * Port announcement file (ADELIE_PORT_FILE; PENGUIN_PORT_FILE is read too): once the App is up,
   * the actual
   * bound port is written here — the supervising process's way to learn the port when
   * it starts the server with PORT=0.
   */
  portFile: string | null;
  /**
   * Trust `x-forwarded-proto` from the request (ADELIE_TRUST_PROXY=1). Off by default:
   * the header is caller-supplied, so on a non-loopback bind an untrusted caller could
   * set it to `https` to walk through the hot-update network gate (hmr/routes.ts) while
   * actually speaking plaintext — or get session cookies stamped `Secure` over plain HTTP,
   * which the browser then never sends back (a sign-in that never takes). Enable this only
   * behind a reverse proxy that terminates TLS and either sets or strips the header itself
   * before it reaches this process; an HTTPS deployment that leaves it off issues session
   * cookies WITHOUT the `Secure` flag (auth/middleware.ts cookieOptions).
   */
  trustProxy: boolean;
  /**
   * The CLI entry script this harness offers to the Agents it runs — the file the
   * `<root>/bin/penguin` shim execs (see services/cli-shim.ts). `ADELIE_CLI_ENTRY` when
   * set (`PENGUIN_CLI_ENTRY` is read too — the desktop shell passes that spelling, and its
   * launch environment is not built in this repository, see state/boundary-env.ts):
   * `penguin server|web` exports its own
   * entry there, and the desktop shell passes
   * the bundled one to the server it forks. Otherwise the entry of the checkout this
   * server was started from, when it has a built one. Null = no CLI to offer, and no shim
   * is written.
   *
   * Related to but wider than the self-update endpoint's use of the same variable
   * (http/routes/version.ts), which accepts only an INSTALLED entry it can re-run as
   * `penguin update`: a checkout has no release to update to, but its CLI is exactly the
   * one an Agent working on that checkout should be running.
   *
   * OPTIONAL for the same reason: absent — a runtime older than this field — reads as null,
   * no CLI to offer and no shim written.
   */
  cliEntry?: string | null;
  /**
   * Feedback endpoint (ADELIE_FEEDBACK_URL): the absolute http(s) URL the Web UI's feedback
   * entry posts to, with ADELIE_FEEDBACK_KEY sent as its `x-adelie-key` header when set. Null
   * — the default — turns the entry off: an install with no feedback backend has nothing to
   * send its users' words to, and a button that can only fail is worse than no button.
   *
   * The contract is the Adelie requirements box's (`POST /api/requirements`, `{title, detail}`
   * in, `{ok, item}` out) — the same box the patrol rounds read their work from, so feedback
   * filed from the UI lands in the queue an Agent already works through.
   */
  feedbackUrl: string | null;
  /** The feedback endpoint's credential (ADELIE_FEEDBACK_KEY), sent as `x-adelie-key`; null when the endpoint takes none. */
  feedbackKey: string | null;
}

const DAY_MS = 24 * 60 * 60 * 1000;

/**
 * Default frontend build output directory, first match wins:
 * - `<this package>/web-dist`: npm package layout — the release workflow copies the built
 *   web assets into the published package, so an `npm install` gets the Web UI too;
 * - `<this package>/../web/dist`: monorepo layout (resolves the same whether running
 *   from src or dist), also the fallback when neither exists.
 */
function defaultWebDist(): string {
  const here = path.dirname(fileURLToPath(import.meta.url));
  const bundled = path.resolve(here, "..", "web-dist");
  if (fs.existsSync(bundled)) return bundled;
  return path.resolve(here, "..", "..", "web", "dist");
}

/**
 * The CLI entry of the checkout this server module lives in, resolved from the module's
 * own location (`packages/server/src/…` under tsx, `packages/server/dist/…` when built,
 * the desktop shell's bundle in a source desktop run — all reached by the same walk to the
 * workspace root). Null outside a checkout, and null when its CLI has not been built.
 */
function defaultCliEntry(): string | null {
  return checkoutCliEntry(path.dirname(fileURLToPath(import.meta.url)));
}

/**
 * Validates ADELIE_PREVIEW_ORIGIN into a bare origin, or throws. An unparseable value
 * is a hard failure rather than a silent fallback: falling back would quietly serve
 * previews same-origin, which is the configuration this variable exists to avoid.
 */
function normalizePreviewOrigin(raw: string | undefined): string | null {
  if (!raw || raw.trim() === "") return null;
  let url: URL;
  try {
    url = new URL(raw.trim());
  } catch {
    throw new Error(`Invalid ADELIE_PREVIEW_ORIGIN=${raw} (expected an absolute origin)`);
  }
  if (url.protocol !== "http:" && url.protocol !== "https:") {
    throw new Error(`Invalid ADELIE_PREVIEW_ORIGIN=${raw} (only http/https are supported)`);
  }
  return url.origin;
}

/** HTTPS in production; plain HTTP is accepted only for an explicit loopback integration. */
export function normalizePenguinGoOrigin(raw: string | undefined): string {
  const value = raw?.trim() || "https://token.penguin.ooo";
  let url: URL;
  try {
    url = new URL(value);
  } catch {
    throw new Error(`Invalid PENGUIN_GO_ORIGIN=${value} (expected an absolute HTTP(S) origin)`);
  }
  if (
    url.username !== "" ||
    url.password !== "" ||
    url.pathname !== "/" ||
    url.search !== "" ||
    url.hash !== ""
  ) {
    throw new Error(
      `Invalid PENGUIN_GO_ORIGIN=${value} (paths, credentials, query and fragment are not allowed)`,
    );
  }
  const loopback =
    url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
    throw new Error(`Invalid PENGUIN_GO_ORIGIN=${value} (HTTPS required except for loopback HTTP)`);
  }
  return url.origin;
}

/**
 * Validates MODELSCOPE_BRIDGE_URL into a base URL with no trailing slash, or throws.
 *
 * Deliberately looser than normalizePenguinGoOrigin in exactly one place: a PATH PREFIX is
 * allowed, because the bridge is mounted under one in production
 * (`https://go.penguin.ooo/modelscope`) and strips it from the request itself — so the
 * prefix is part of the address the client must call. Credentials, query, fragment and
 * plaintext HTTP stay rejected.
 */
export function normalizeModelScopeBridgeUrl(raw: string | undefined): string {
  const value = raw?.trim() || "https://go.penguin.ooo/modelscope";
  let url: URL;
  try {
    url = new URL(value);
  } catch {
    throw new Error(`Invalid MODELSCOPE_BRIDGE_URL=${value} (expected an absolute HTTP(S) URL)`);
  }
  if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") {
    throw new Error(
      `Invalid MODELSCOPE_BRIDGE_URL=${value} (credentials, query and fragment are not allowed)`,
    );
  }
  if (url.protocol !== "https:") {
    throw new Error(`Invalid MODELSCOPE_BRIDGE_URL=${value} (HTTPS required)`);
  }
  // A bare origin parses as pathname "/", which must become "" rather than stay a slash, or
  // every appended route would read `//oauth/start`.
  return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
}

/**
 * Validates ADELIE_FEEDBACK_URL into an absolute http(s) URL, or null when unset. A blank
 * value counts as unset (the common `.env` case of `ADELIE_FEEDBACK_URL=`), and a malformed
 * one throws here rather than at the first submission: the alternative is a feedback entry
 * that looks live and answers with a network error the operator cannot connect to a typo.
 * Credentials in the URL stay rejected — the key has its own variable, and putting it in the
 * URL would leak it into the journal through the logged request line.
 */
export function normalizeFeedbackUrl(raw: string | undefined): string | null {
  const value = raw?.trim();
  if (!value) return null;
  let url: URL;
  try {
    url = new URL(value);
  } catch {
    throw new Error(`Invalid ADELIE_FEEDBACK_URL=${value} (expected an absolute HTTP(S) URL)`);
  }
  if (url.protocol !== "http:" && url.protocol !== "https:") {
    throw new Error(`Invalid ADELIE_FEEDBACK_URL=${value} (only http/https are supported)`);
  }
  if (url.username !== "" || url.password !== "") {
    throw new Error(`Invalid ADELIE_FEEDBACK_URL=${value} (put the key in ADELIE_FEEDBACK_KEY)`);
  }
  return url.toString();
}

/** Parses server config from environment variables (PORT / HOST / ADELIE_HOME / ADELIE_WEB_DIST / ADELIE_WEB_DB / ADELIE_PREVIEW_ORIGIN / PENGUIN_GO_ORIGIN / MODELSCOPE_BRIDGE_URL / ADELIE_SEED_ADMIN_PASSWORD / ADELIE_DESKTOP_TOKEN / ADELIE_PORT_FILE / ADELIE_TRUST_PROXY / ADELIE_CLI_ENTRY / ADELIE_FEEDBACK_URL / ADELIE_FEEDBACK_KEY; each of the deployment names is also read in its pre-rename `PENGUIN_*` spelling, see state/boundary-env.ts). */
export function resolveServerConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
  // The root is read off the passed environment rather than `process.env` (this function takes
  // one so tests can hand it a fabricated environment), so the two names are spelled here as
  // well as in `resolveRoot()` — imported constants, not literals, so they cannot drift.
  const root = env[ROOT_ENV] ?? env[LEGACY_ROOT_ENV] ?? resolveRoot();
  // An empty PORT string is treated as unset (the common `.env` case of an empty
  // `PORT=`): Number("") === 0 would pass the range check and bind to a random
  // port; this matches the CLI's resolvePort convention.
  const port = Number(env.PORT || DEFAULT_SERVER_PORT);
  if (!Number.isInteger(port) || port < 0 || port > 65535) {
    throw new Error(`Invalid port configuration PORT=${env.PORT}`);
  }
  const host = env.HOST ?? "127.0.0.1";
  const desktopToken = boundaryEnv(env, "desktopToken")?.trim() || null;
  // Desktop mode redeems its token through a URL: never allow it off loopback.
  if (desktopToken !== null && host !== "127.0.0.1" && host !== "localhost") {
    throw new Error(`Desktop mode requires a loopback HOST (got HOST=${host})`);
  }
  return {
    root,
    host,
    port,
    dbPath: boundaryEnv(env, "webDb") ?? path.join(root, "web.db"),
    webDist: boundaryEnv(env, "webDist") ?? defaultWebDist(),
    previewOrigin: normalizePreviewOrigin(env.ADELIE_PREVIEW_ORIGIN),
    penguinGoOrigin: normalizePenguinGoOrigin(env.PENGUIN_GO_ORIGIN),
    modelscopeBridgeUrl: normalizeModelScopeBridgeUrl(env.MODELSCOPE_BRIDGE_URL),
    // An empty/whitespace value is treated as unset, which leaves the seed to generate one.
    seedAdminPassword: env.ADELIE_SEED_ADMIN_PASSWORD?.trim() || null,
    authSessionTtlMs: 30 * DAY_MS,
    authSessionRenewMs: 29 * DAY_MS,
    desktopToken,
    portFile: boundaryEnv(env, "portFile")?.trim() || null,
    trustProxy: env.ADELIE_TRUST_PROXY === "1",
    supervised: env.ADELIE_SUPERVISED === "1",
    cliEntry: boundaryEnv(env, "cliEntry")?.trim() || defaultCliEntry(),
    feedbackUrl: normalizeFeedbackUrl(env.ADELIE_FEEDBACK_URL),
    // An empty value counts as unset: an endpoint that wants no credential gets no header,
    // rather than an empty one it would have to treat as a wrong key.
    feedbackKey: env.ADELIE_FEEDBACK_KEY?.trim() || null,
  };
}