Skip to content

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

feat(core,server,cli): 边界面部署变量读侧同时认 ADELIE_* 与旧名(2.2c 前半)

lmliheng83acbdf07424
diff --git a/packages/cli/src/commands/auth.ts b/packages/cli/src/commands/auth.ts
index 8110aa8d..bea8aac5 100644
--- a/packages/cli/src/commands/auth.ts
+++ b/packages/cli/src/commands/auth.ts
@@ -14,6 +14,7 @@
* The session lands in `<root>/cli-session.json` (0600) rather than a shell's history.
* Docs: /docs/cli § "penguin auth".
*/
+import { boundaryEnv } from "@lmliheng/penguin-core";
import { mintApiToken } from "@lmliheng/penguin-server/auth-token";
import { liveServerLock } from "@lmliheng/penguin-server/lock";
import type { Command } from "commander";
@@ -221,11 +222,12 @@ export function registerAuthCommand(program: Command, t: Messages): void {
}
const root = resolveRootOption(opts.root);
// A session row written straight into web.db (auth-token.ts); no server needed, and safe
- // while one runs. PENGUIN_WEB_DB honored as everywhere else, or the token would be
- // minted into a file the live server never reads.
+ // while one runs. ADELIE_WEB_DB (or its pre-rename spelling) honored as everywhere else,
+ // or the token would be minted into a file the live server never reads.
+ const dbPath = boundaryEnv(process.env, "webDb");
const result = mintApiToken(root, {
userId: opts.userId,
- ...(process.env.PENGUIN_WEB_DB ? { dbPath: process.env.PENGUIN_WEB_DB } : {}),
+ ...(dbPath ? { dbPath } : {}),
...(ttl === undefined ? {} : { ttlMs: ttl * 1000 }),
});
if (result.outcome === "no_server") {
diff --git a/packages/cli/src/commands/reset-password.ts b/packages/cli/src/commands/reset-password.ts
index fab2f132..6de34563 100644
--- a/packages/cli/src/commands/reset-password.ts
+++ b/packages/cli/src/commands/reset-password.ts
@@ -4,15 +4,16 @@
*
* The admin resets every other user from the user-management page, but nothing can
* reset the admin itself once its password is forgotten. This subcommand of `penguin
- * server` closes that gap from the machine owning the data root (PENGUIN_HOME or the
- * default root, PENGUIN_WEB_DB honored for the database path): it refuses while a live
+ * server` closes that gap from the machine owning the data root (ADELIE_HOME or the
+ * default root, ADELIE_WEB_DB — or its pre-rename spelling — honored for the database
+ * path): it refuses while a live
* server owns the root (web.db is single-writer), otherwise the built-in admin returns to
* the unclaimed state with its sessions revoked, and the next server start prints a fresh
* first-login link to claim it through (reset-admin-password.ts).
* Docs: /docs/cli § "penguin server / penguin web".
*/
import path from "node:path";
-import { resolveRoot } from "@lmliheng/penguin-core";
+import { boundaryEnv, resolveRoot } from "@lmliheng/penguin-core";
import { resetAdminPassword } from "@lmliheng/penguin-server/reset-admin-password";
import type { Command } from "commander";
import type { Messages } from "../i18n.js";
@@ -24,7 +25,7 @@ export function registerResetPasswordCommand(server: Command, t: Messages): void
.description(t.resetPassword.desc)
.action(async () => {
const root = resolveRoot();
- const dbPath = process.env.PENGUIN_WEB_DB ?? path.join(root, "web.db");
+ const dbPath = boundaryEnv(process.env, "webDb") ?? path.join(root, "web.db");
const result = await resetAdminPassword(root, dbPath);
switch (result.outcome) {
case "server_running":
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
index 05c4f05b..6df956d6 100644
--- a/packages/cli/src/commands/serve.ts
+++ b/packages/cli/src/commands/serve.ts
@@ -119,8 +119,9 @@ export function cliEntryFor(argv1: string | undefined): string | null {
*/
/**
* Pre-start lock check: the App URL of a live server already owning the data root this
- * process would use (same resolution as the server: PENGUIN_HOME or the default root),
- * or null. The server itself re-checks on startup (the in-process backstop); checking
+ * process would use (same resolution as the server: ADELIE_HOME, or the pre-rename
+ * PENGUIN_HOME, or the default root), or null. The server itself re-checks on startup (the
+ * in-process backstop); checking
* here keeps the friendly path — `penguin server` refuses with the URL, `penguin web`
* simply opens the existing instance. Locks live per data root, so a second server on a
* DIFFERENT root is untouched. See @lmliheng/penguin-server/lock.
diff --git a/packages/cli/src/commands/server-status.ts b/packages/cli/src/commands/server-status.ts
index bc5e2953..e417a64a 100644
--- a/packages/cli/src/commands/server-status.ts
+++ b/packages/cli/src/commands/server-status.ts
@@ -9,6 +9,7 @@
* Docs: /docs/cli § "penguin server / penguin web".
*/
import path from "node:path";
+import { boundaryEnv } from "@lmliheng/penguin-core";
import { readMachineStatus } from "@lmliheng/penguin-server/machine-status";
import type { Command } from "commander";
import type { Messages } from "../i18n.js";
@@ -22,9 +23,9 @@ export function registerStatusCommand(server: Command, t: Messages): void {
.option("--root <dir>", t.common.root)
.action(async (opts: { root?: string }) => {
const root = resolveRootOption(opts.root);
- // PENGUIN_WEB_DB honored as everywhere else, or this reads an identity out of a
- // database the live server never writes to.
- const dbPath = process.env.PENGUIN_WEB_DB ?? path.join(root, "web.db");
+ // ADELIE_WEB_DB (or its pre-rename spelling) honored as everywhere else, or this reads an
+ // identity out of a database the live server never writes to.
+ const dbPath = boundaryEnv(process.env, "webDb") ?? path.join(root, "web.db");
process.stdout.write(JSON.stringify(await readMachineStatus(root, dbPath)) + "\n");
});
}
diff --git a/packages/core/src/environment/tools/command/shell.ts b/packages/core/src/environment/tools/command/shell.ts
index a5b3e1ce..e75997c0 100644
--- a/packages/core/src/environment/tools/command/shell.ts
+++ b/packages/core/src/environment/tools/command/shell.ts
@@ -18,7 +18,9 @@
* resolves into the Windows system directory is ignored: that is the WSL launcher, which
* runs commands inside a Linux distro with a different filesystem view (and fails outright
* when no distro is configured).
- * 4. Then `PENGUIN_BUNDLED_SHELL` — the MinGit bash the Windows package ships (see the
+ * 4. Then `ADELIE_BUNDLED_SHELL` (the pre-rename `PENGUIN_BUNDLED_SHELL` is still read — the
+ * launcher shim that sets it ships with the installers, so its writer is outside this
+ * repository) — the MinGit bash the Windows package ships (see the
* release workflow), advertised by the launcher shims as an absolute path. It comes
* *after* the PATH probe on purpose: a user's own Git for Windows carries the full MSYS
* userland (curl, tar, less, perl …), while MinGit carries ~60 core tools, so when both
@@ -45,6 +47,7 @@
import { spawnSync } from "node:child_process";
import { existsSync } from "node:fs";
import path from "node:path";
+import { boundaryEnv } from "../../../state/boundary-env.js";
/** A resolved shell invocation: `spawn(command, [...args, cmd])` runs `cmd` in that shell. */
export interface ShellInvocation {
@@ -213,7 +216,7 @@ export function resolveShell(opts: ResolveShellOptions = {}): ShellInvocation {
// The bundled MinGit bash (installed-package layout only; absent for npm installs). Reported
// to the model as "bash" rather than its filename: MinGit installs GNU bash under the name
// `sh`, and the Skill ecosystem targets bash, so "sh" would understate what it can run.
- const bundled = env.PENGUIN_BUNDLED_SHELL?.trim();
+ const bundled = boundaryEnv(env, "bundledShell")?.trim();
if (bundled && exists(bundled)) {
return { command: bundled, args: ["-lc"], name: "bash" };
}
diff --git a/packages/core/src/state/boundary-env.ts b/packages/core/src/state/boundary-env.ts
new file mode 100644
index 00000000..98d2ce6e
--- /dev/null
+++ b/packages/core/src/state/boundary-env.ts
@@ -0,0 +1,70 @@
+/**
+ * Deployment variables whose *other* end lives outside this repository.
+ *
+ * A setting whose two ends are both this code base was renamed outright (see FORK-PROGRESS.md
+ * § 2.2b, the `ADELIE_*` control-plane batch). This module is the read side of the batch that
+ * cannot be renamed that way: its values are *written* by programs Adelie does not build here —
+ * the desktop shell's launch environment, the systemd unit or shell rc of an existing deployment,
+ * a launcher script from an older install. Those writers cannot move in the same release as this
+ * reader, so each name is accepted in both spellings: `ADELIE_*` first, then the pre-rename
+ * `PENGUIN_*`.
+ *
+ * Keeping the old spelling is not politeness, it is the difference between working and quietly
+ * broken: a `PENGUIN_WEB_DB` that stopped being read points the server at `<root>/web.db` — a
+ * different, empty file than the one the operator has been backing up.
+ *
+ * The rule is the one the data root already follows (`ROOT_ENV` / `LEGACY_ROOT_ENV` in paths.ts):
+ * the new spelling wins when both are set, and a set-but-empty new name counts as set — the
+ * consumers that treat blank as unset (the CLI entry, the port file) trim it themselves.
+ *
+ * Deliberately NOT in this table:
+ * - the installer / release protocol (`PENGUIN_INSTALL_DIR`, `PENGUIN_VERSION`, the
+ * `PENGUIN_DOWNLOAD_*` switches, the `__PENGUIN_*__` build stamps): a running CLI downloads
+ * `install.sh` from a release, so old CLI × new script is a supported pair and both ends have to
+ * move together with the release chain (FORK-PROGRESS.md § 4.x).
+ * - the upstream gateway (`PENGUIN_GO_*`): their service, and not ours to rename.
+ * - the desktop shell's own switches (`PENGUIN_DESKTOP_SMOKE*`, `PENGUIN_NO_LOGIN_SHELL_ENV`,
+ * `PENGUIN_BB_SMOKE_BUNDLE`): read only inside the shell's own scripts and tests.
+ */
+
+/** One boundary setting: the spelling Adelie reads and writes, plus the one it still reads. */
+export interface BoundaryEnvName {
+ /** Adelie's own spelling; preferred when both are set. */
+ readonly name: string;
+ /** The pre-rename spelling, still read because its writer is outside this repository. */
+ readonly legacy: string;
+}
+
+/**
+ * The boundary settings and their two spellings. One entry per variable, so that a reader who is
+ * about to spell one of these names by hand can see why it has two.
+ */
+export const BOUNDARY_ENV = {
+ /** `--profile` of the desktop shell (it forks this server) and of an existing deployment. */
+ profile: { name: "ADELIE_PROFILE", legacy: "PENGUIN_PROFILE" },
+ /** Front-end build directory: the desktop shell, a systemd unit, an operator's `.env`. */
+ webDist: { name: "ADELIE_WEB_DIST", legacy: "PENGUIN_WEB_DIST" },
+ /** SQLite index path — an operator's override, honored by the server and by three CLI reads. */
+ webDb: { name: "ADELIE_WEB_DB", legacy: "PENGUIN_WEB_DB" },
+ /** The CLI entry the server offers: `penguin server|web` exports it, the shell passes one. */
+ cliEntry: { name: "ADELIE_CLI_ENTRY", legacy: "PENGUIN_CLI_ENTRY" },
+ /** Port announcement file the desktop shell polls when it starts the server with PORT=0. */
+ portFile: { name: "ADELIE_PORT_FILE", legacy: "PENGUIN_PORT_FILE" },
+ /** Per-launch desktop-mode token; the shell mints it, and it must never leave the machine. */
+ desktopToken: { name: "ADELIE_DESKTOP_TOKEN", legacy: "PENGUIN_DESKTOP_TOKEN" },
+ /** MinGit bash shipped by the Windows package; the launcher shim advertises its path. */
+ bundledShell: { name: "ADELIE_BUNDLED_SHELL", legacy: "PENGUIN_BUNDLED_SHELL" },
+} as const satisfies Record<string, BoundaryEnvName>;
+
+/** Key of a boundary setting, for {@link boundaryEnv}. */
+export type BoundaryEnvKey = keyof typeof BOUNDARY_ENV;
+
+/**
+ * Reads one boundary setting out of an environment: the Adelie spelling, then the pre-rename one.
+ * Takes the environment as an argument rather than reading `process.env`, so tests can hand it a
+ * fabricated one — the same shape the server's config parser and the shell resolver use.
+ */
+export function boundaryEnv(env: NodeJS.ProcessEnv, key: BoundaryEnvKey): string | undefined {
+ const { name, legacy } = BOUNDARY_ENV[key];
+ return env[name] ?? env[legacy];
+}
diff --git a/packages/core/src/state/index.ts b/packages/core/src/state/index.ts
index 72ec8836..54c281a1 100644
--- a/packages/core/src/state/index.ts
+++ b/packages/core/src/state/index.ts
@@ -4,6 +4,7 @@
* Directory layout, default config, Project config read/write, Agent State load/init.
*/
export * from "./paths.js";
+export * from "./boundary-env.js";
export * from "./default-config.js";
export * from "./kernel-history.js";
export * from "./kernel-update.js";
diff --git a/packages/core/test/boundary-env.test.ts b/packages/core/test/boundary-env.test.ts
new file mode 100644
index 00000000..e1a09027
--- /dev/null
+++ b/packages/core/test/boundary-env.test.ts
@@ -0,0 +1,84 @@
+/**
+ * The boundary-variable table (core/src/state/boundary-env.ts) and its reader.
+ *
+ * These names have two spellings because their *writers* are outside this repository — the
+ * desktop shell's launch environment, an existing deployment's unit file, an older installer's
+ * launcher script. The tests here pin the two properties such a table can silently lose: that a
+ * pair really is one name in two spellings, and that the new spelling wins while the old one
+ * keeps being read.
+ */
+import { describe, expect, it } from "vitest";
+import { BOUNDARY_ENV, boundaryEnv } from "../src/state/boundary-env.js";
+
+describe("BOUNDARY_ENV", () => {
+ it("names exactly the deployment variables whose writer is outside this repository", () => {
+ // A literal list, not a count: a name added here is a decision (whose writer is it? can it
+ // move in the same release?), and a name *removed* here breaks the installs it named.
+ expect(Object.keys(BOUNDARY_ENV).sort()).toEqual([
+ "bundledShell",
+ "cliEntry",
+ "desktopToken",
+ "portFile",
+ "profile",
+ "webDb",
+ "webDist",
+ ]);
+ });
+
+ it("pairs one Adelie name with one pre-rename name, and nothing else", () => {
+ const values = Object.values(BOUNDARY_ENV);
+ const names = values.map((entry) => entry.name);
+ const legacies = values.map((entry) => entry.legacy);
+ expect(new Set([...names, ...legacies]).size).toBe(names.length + legacies.length);
+ for (const { name, legacy } of values) {
+ expect(name).toMatch(/^ADELIE_[A-Z0-9_]+$/);
+ // The legacy spelling is the same setting, not a second knob: same suffix, old prefix.
+ expect(legacy).toBe(`PENGUIN_${name.slice("ADELIE_".length)}`);
+ }
+ });
+});
+
+describe("boundaryEnv", () => {
+ it("reads Adelie's own spelling", () => {
+ expect(boundaryEnv({ ADELIE_WEB_DB: "/srv/adelie/web.db" }, "webDb")).toBe(
+ "/srv/adelie/web.db",
+ );
+ });
+
+ it("still reads the pre-rename spelling, so an existing deployment keeps working", () => {
+ // The one thing this must not do is stop reading it: a PENGUIN_WEB_DB that is no longer
+ // honored points the server at an empty `<root>/web.db` instead of the operator's file.
+ expect(boundaryEnv({ PENGUIN_WEB_DB: "/opt/penguin/data/web.db" }, "webDb")).toBe(
+ "/opt/penguin/data/web.db",
+ );
+ });
+
+ it("prefers the new spelling when both are set", () => {
+ expect(boundaryEnv({ ADELIE_WEB_DB: "/new.db", PENGUIN_WEB_DB: "/old.db" }, "webDb")).toBe(
+ "/new.db",
+ );
+ });
+
+ it("is undefined when neither is set, so the caller's own default takes over", () => {
+ expect(boundaryEnv({}, "webDb")).toBeUndefined();
+ expect(boundaryEnv({ PORT: "7364" }, "webDb")).toBeUndefined();
+ });
+
+ it("treats a set-but-empty new name as set — the rule the data root already follows", () => {
+ // Consumers that care (the CLI entry, the port file) trim and treat blank as unset
+ // themselves; the reader does not quietly fall back to the old name, which would make the
+ // empty value mean the opposite of what it says.
+ expect(boundaryEnv({ ADELIE_WEB_DB: "", PENGUIN_WEB_DB: "/old.db" }, "webDb")).toBe("");
+ });
+
+ it("reads every entry of the table, new spelling and old", () => {
+ for (const [key, { name, legacy }] of Object.entries(BOUNDARY_ENV)) {
+ expect(boundaryEnv({ [name]: `${key}-new` }, key as keyof typeof BOUNDARY_ENV)).toBe(
+ `${key}-new`,
+ );
+ expect(boundaryEnv({ [legacy]: `${key}-old` }, key as keyof typeof BOUNDARY_ENV)).toBe(
+ `${key}-old`,
+ );
+ }
+ });
+});
diff --git a/packages/core/test/shell-resolver.test.ts b/packages/core/test/shell-resolver.test.ts
index aba7d63b..0095d86d 100644
--- a/packages/core/test/shell-resolver.test.ts
+++ b/packages/core/test/shell-resolver.test.ts
@@ -245,7 +245,7 @@ describe("resolveShell — ADELIE_SHELL override", () => {
});
});
-describe("resolveShell — the bundled MinGit bash (PENGUIN_BUNDLED_SHELL)", () => {
+describe("resolveShell — the bundled MinGit bash (ADELIE_BUNDLED_SHELL, pre-rename too)", () => {
const BUNDLED = "C:\\Users\\u\\.penguin\\git\\usr\\bin\\sh.exe";
/** An exists() stub answering true only for the bundled path. */
const bundledExists = (p: string) => p === BUNDLED;
@@ -282,6 +282,19 @@ describe("resolveShell — the bundled MinGit bash (PENGUIN_BUNDLED_SHELL)", ()
expect(shell.command).toBe(BUNDLED);
});
+ it("reads ADELIE_BUNDLED_SHELL too, and prefers it over the pre-rename spelling", () => {
+ // The launcher shim that advertises this path ships inside the installers, so Adelie names
+ // it itself while the installers still export the old spelling (state/boundary-env.ts).
+ const renamed = "C:\\Users\\u\\adelie\\git\\usr\\bin\\sh.exe";
+ const shell = resolveShell({
+ platform: "win32",
+ env: { ADELIE_BUNDLED_SHELL: renamed, PENGUIN_BUNDLED_SHELL: BUNDLED },
+ whichAll: which({ pwsh: ["C:\\pwsh.exe"] }),
+ exists: (p) => p === renamed || p === BUNDLED,
+ });
+ expect(shell).toEqual({ command: renamed, args: ["-lc"], name: "bash" });
+ });
+
it("still loses to an explicit ADELIE_SHELL", () => {
const shell = resolveShell({
platform: "win32",
diff --git a/packages/server/README.md b/packages/server/README.md
index 05e8abbe..b6e4d650 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -5,7 +5,7 @@ The Adelie Web backend — the Web implementation of the SDK's Human boundary. H
## Architecture
- **HTTP**: Hono + `@hono/node-server`; the `http` module (src/http/app.ts) assembles the business surface from every module's `HttpModule.routes` contributions and binds no port (tests drive it via `app.request()`); `index.ts` is the startup entry (dotenv, graceful shutdown).
-- **Storage**: SQLite via Node's built-in `node:sqlite` (WAL) holds only indexes and aggregates (users, auth sessions, Project authorization, Agent/Session indexes, usage, UI prefs, error records). Agent State, Traces and Workspaces stay as files under `~/.penguin/data/<project>/agents/<agent>/`, fully shared with the SDK and CLI.
+- **Storage**: SQLite via Node's built-in `node:sqlite` (WAL) holds only indexes and aggregates (users, auth sessions, Project authorization, Agent/Session indexes, usage, UI prefs, error records). Agent State, Traces and Workspaces stay as files under `~/.adelie/data/<project>/agents/<agent>/`, fully shared with the SDK and CLI.
- **Runtime**: a session manager keeps active Sessions (get-or-resume-or-heal, per-Session mutex, run/compact driving); approvals surface over SSE as `approval_request` and decisions re-read the stored approval mode each time; interrupts converge pending approvals to deny before aborting; a scheduler fires `agent_state/schedule/*.toml` tasks while the service runs.
- **SSE**: per-channel monotonic event ids with a bounded replay buffer (1000 events / 2MB); reconnects replay from `Last-Event-ID` or receive `resync_required`; heartbeat comment every 20s.
- **Usage**: `token_usage` events are persisted row by row; costs are computed at query time from current per-model pricing.
@@ -18,11 +18,16 @@ The full route tables and the SSE protocol are documented in the [Server API ref
| Variable | Meaning | Default |
| --- | --- | --- |
| `PORT` / `HOST` | Listen port / address | `7364` / `127.0.0.1` |
-| `PENGUIN_HOME` | Data root (shared with SDK/CLI) | `~/.penguin/data` |
-| `PENGUIN_WEB_DB` | SQLite file path | `<root>/web.db` |
-| `PENGUIN_WEB_DIST` | Front-end build dir (static hosting + SPA fallback when present) | `../web/dist`, or the bundled `web-dist/` in the npm package |
+| `ADELIE_HOME` (was `PENGUIN_HOME`) | Data root (shared with SDK/CLI) | `~/.adelie/data` |
+| `ADELIE_WEB_DB` (was `PENGUIN_WEB_DB`) | SQLite file path | `<root>/web.db` |
+| `ADELIE_WEB_DIST` (was `PENGUIN_WEB_DIST`) | Front-end build dir (static hosting + SPA fallback when present) | `../web/dist`, or the bundled `web-dist/` in the npm package |
| `ADELIE_TRUST_PROXY` | Trust `x-forwarded-proto` (`1` to enable): it opens the hot-update network gate over proxied HTTPS and marks session cookies `Secure` — only behind a reverse proxy that sets/strips the header itself | unset (untrusted) |
-| `PENGUIN_CLI_ENTRY` | CLI entry script offered to the Agents this server runs: it is written into `<root>/bin/penguin` and put at the front of every command's PATH | `penguin server\|web` and the desktop shell set it; otherwise the entry of the checkout this server was started from, when it has one |
+| `ADELIE_CLI_ENTRY` (was `PENGUIN_CLI_ENTRY`) | CLI entry script offered to the Agents this server runs: it is written into `<root>/bin/penguin` and put at the front of every command's PATH | `penguin server\|web` and the desktop shell set it; otherwise the entry of the checkout this server was started from, when it has one |
+
+Every deployment variable above keeps reading the spelling in parentheses: its writer is outside
+this repository (the desktop shell's launch environment, an existing deployment's unit file, an
+older launcher script), so both names are accepted while those writers move over — see
+`packages/core/src/state/boundary-env.ts`.
`.env` in the process cwd is loaded automatically.
diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.ts
index 100d4220..b6723136 100644
--- a/packages/server/src/api/types.ts
+++ b/packages/server/src/api/types.ts
@@ -122,8 +122,8 @@ export interface MeResponse {
previewIsolated: boolean;
/**
* Whether this server runs in desktop mode (spawned by the desktop shell with
- * PENGUIN_DESKTOP_TOKEN). The web app then hides the logout entry, the
- * initial-password banner and the self-update entry.
+ * ADELIE_DESKTOP_TOKEN, or its pre-rename PENGUIN_DESKTOP_TOKEN). The web app then hides
+ * the logout entry, the initial-password banner and the self-update entry.
*/
desktopMode: boolean;
/**
@@ -4365,8 +4365,9 @@ export interface MachineInfo {
*/
status: MachineServerStatus | null;
/**
- * The data root the server there runs on (`PENGUIN_HOME`). This instance's PROFILE decides
- * it — a dev instance names the machine's dev root and never the release one beside it
+ * The data root the server there runs on (`ADELIE_HOME`, or the pre-rename `PENGUIN_HOME`
+ * the install commands still spell). This instance's PROFILE decides it — a dev instance
+ * names the machine's dev root and never the release one beside it
* (machines/layout.ts) — which is exactly what a reader looking at two instances of this
* page needs to tell them apart. Written in that machine's own spelling once its platform
* is known, and in the POSIX one before that; for `local` it is this process's own root,
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index d7627f31..59946c71 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -3,16 +3,19 @@
*
* 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 PENGUIN_WEB_DB, tests use ":memory:").
+ * `<root>/web.db` (overridable via ADELIE_WEB_DB, tests use ":memory:").
* In production, the SPA is served statically once the frontend build output
- * directory (PENGUIN_WEB_DIST, the bundled web-dist/, or ../web/dist) is
+ * 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,
@@ -71,7 +74,8 @@ export interface ServerConfig {
*/
authSessionRenewMs: number;
/**
- * Desktop mode (PENGUIN_DESKTOP_TOKEN): the per-launch token minted by the desktop
+ * 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.
@@ -88,7 +92,8 @@ export interface ServerConfig {
*/
supervised: boolean;
/**
- * Port announcement file (PENGUIN_PORT_FILE): once the App is up, the actual
+ * 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.
*/
@@ -106,8 +111,10 @@ export interface ServerConfig {
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). `PENGUIN_CLI_ENTRY` when
- * set: `penguin server|web` exports its own entry there, and the desktop shell passes
+ * `<root>/bin/penguin` shim execs (see services/cli-shim.ts). `ADELIE_CLI_ENTRY` when
+ * set (`PENGUIN_CLI_ENTRY` is read too — `penguin server|web` still exports that spelling and
+ * the desktop shell passes it, 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.
@@ -226,7 +233,7 @@ export function normalizeModelScopeBridgeUrl(raw: string | undefined): string {
return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
}
-/** Parses server config from environment variables (PORT / HOST / ADELIE_HOME / PENGUIN_WEB_DIST / PENGUIN_WEB_DB / ADELIE_PREVIEW_ORIGIN / PENGUIN_GO_ORIGIN / MODELSCOPE_BRIDGE_URL / ADELIE_SEED_ADMIN_PASSWORD / PENGUIN_DESKTOP_TOKEN / PENGUIN_PORT_FILE / ADELIE_TRUST_PROXY / PENGUIN_CLI_ENTRY). */
+/** 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; 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
@@ -240,7 +247,7 @@ export function resolveServerConfig(env: NodeJS.ProcessEnv = process.env): Serve
throw new Error(`Invalid port configuration PORT=${env.PORT}`);
}
const host = env.HOST ?? "127.0.0.1";
- const desktopToken = env.PENGUIN_DESKTOP_TOKEN?.trim() || null;
+ 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})`);
@@ -249,8 +256,8 @@ export function resolveServerConfig(env: NodeJS.ProcessEnv = process.env): Serve
root,
host,
port,
- dbPath: env.PENGUIN_WEB_DB ?? path.join(root, "web.db"),
- webDist: env.PENGUIN_WEB_DIST ?? defaultWebDist(),
+ 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),
@@ -259,9 +266,9 @@ export function resolveServerConfig(env: NodeJS.ProcessEnv = process.env): Serve
authSessionTtlMs: 30 * DAY_MS,
authSessionRenewMs: 29 * DAY_MS,
desktopToken,
- portFile: env.PENGUIN_PORT_FILE?.trim() || null,
+ portFile: boundaryEnv(env, "portFile")?.trim() || null,
trustProxy: env.ADELIE_TRUST_PROXY === "1",
supervised: env.ADELIE_SUPERVISED === "1",
- cliEntry: env.PENGUIN_CLI_ENTRY?.trim() || defaultCliEntry(),
+ cliEntry: boundaryEnv(env, "cliEntry")?.trim() || defaultCliEntry(),
};
}
diff --git a/packages/server/src/http/routes/version.ts b/packages/server/src/http/routes/version.ts
index 4de463ca..4bf0b1cd 100644
--- a/packages/server/src/http/routes/version.ts
+++ b/packages/server/src/http/routes/version.ts
@@ -19,6 +19,7 @@
* route says so (`no_supervisor`) instead of stopping a service nobody would bring back,
* and the page shows the manual restart hint.
*/
+import { boundaryEnv } from "@lmliheng/penguin-core";
import { versionReport } from "../../version-report.js";
import { Hono } from "hono";
import type { Context } from "hono";
@@ -127,7 +128,10 @@ export function versionRoutes(deps: VersionRouteDeps): Hono<AppEnv> {
// `penguin update` resolves the release itself.
const check = await deps.updateCheck.check(false);
const target = check.updateAvailable ? check.latestVersion : null;
- const cliEntry = process.env.PENGUIN_CLI_ENTRY ?? null;
+ // The entry is only interesting when the operator (or the desktop shell) pinned one:
+ // this route re-runs it, so the checkout fallback config resolves would be the wrong
+ // answer here. Both spellings of the name are read — see state/boundary-env.ts.
+ const cliEntry = boundaryEnv(process.env, "cliEntry") ?? null;
return c.json(deps.updateJob.start(cliEntry, target) satisfies UpdateJobStatus);
});
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index ea7415d5..6176cc21 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -290,7 +290,8 @@ class PenguinServer {
}
/**
- * Announces the port (PENGUIN_PORT_FILE), the last step of startup. The port is bound
+ * Announces the port (ADELIE_PORT_FILE; PENGUIN_PORT_FILE is read too), the last step of
+ * startup. The port is bound
* long before this — a client that arrives early is answered rather than refused — but
* the announcement means the App is up, because that is what a reader waits for: the
* desktop shell opens its window on it. Between the bind and here every request gets the
@@ -368,12 +369,13 @@ class PenguinServer {
console.log(`SQLite: ${this.config.dbPath}`);
// Named for the same reason the data root is: it is the one path the static tail
// serves from when no pushed web version is restored, and the only trace of a wrong
- // PENGUIN_WEB_DIST or a missing build is otherwise a 404 on every page.
+ // ADELIE_WEB_DIST (the pre-rename PENGUIN_WEB_DIST is read too) or a missing build is
+ // otherwise a 404 on every page.
console.log(`Web dist: ${this.config.webDist}`);
if (!fs.existsSync(path.join(this.config.webDist, "index.html"))) {
console.warn(
`[server] Web dist has no index.html; the Web App answers 404 unless a pushed web ` +
- `version is restored. Build packages/web or point PENGUIN_WEB_DIST at a build.`,
+ `version is restored. Build packages/web or point ADELIE_WEB_DIST at a build.`,
);
}
if (this.config.desktopToken !== null) console.log("Desktop mode: enabled");
@@ -526,7 +528,7 @@ class PenguinServer {
/** Exit code for "another server already owns this data root" (see lock.ts). */
const EXIT_ALREADY_RUNNING = 3;
-/** Port announcement (PENGUIN_PORT_FILE): tmp + rename, so a polling reader never sees a partial write. */
+/** Port announcement (ADELIE_PORT_FILE, or the pre-rename PENGUIN_PORT_FILE): tmp + rename, so a polling reader never sees a partial write. */
function writePortFile(file: string, port: number): void {
fs.mkdirSync(path.dirname(file), { recursive: true });
const tmp = `${file}.${process.pid}.tmp`;
diff --git a/packages/server/src/machine-status.ts b/packages/server/src/machine-status.ts
index 0e977e65..d780003d 100644
--- a/packages/server/src/machine-status.ts
+++ b/packages/server/src/machine-status.ts
@@ -34,7 +34,7 @@ export interface MachineStatus {
machineId: string | null;
}
-/** `dbPath` may be elsewhere (PENGUIN_WEB_DB), as everywhere else that reads this database. */
+/** `dbPath` may be elsewhere (ADELIE_WEB_DB, or its pre-rename PENGUIN_WEB_DB), as everywhere else that reads this database. */
export async function readMachineStatus(
root: string,
dbPath: string = path.join(root, "web.db"),
diff --git a/packages/server/src/machines/layout.ts b/packages/server/src/machines/layout.ts
index 971df5a6..486c973f 100644
--- a/packages/server/src/machines/layout.ts
+++ b/packages/server/src/machines/layout.ts
@@ -3,8 +3,9 @@
*
* The desktop shell runs as one of two profiles — release, or the dev instance that runs
* beside it on its own data root (`packages/desktop/src/app-identity.ts`) — and the shell
- * hands that choice to its server as `PENGUIN_PROFILE`. A profile names a data-root family,
- * and it holds on every machine the instance touches: a dev instance installs to, starts,
+ * hands that choice to its server as `PENGUIN_PROFILE`, the pre-rename spelling of
+ * `ADELIE_PROFILE` (both are read; see core's state/boundary-env.ts). A profile names a data-root
+ * family, and it holds on every machine the instance touches: a dev instance installs to, starts,
* probes and connects to a machine's DEV installation, never the release one there — so a
* connect from the dev instance cannot stop the release server a person is using on that
* machine, and the two keep separate Agents, Sessions and pushed versions on both ends.
@@ -25,7 +26,7 @@
* Pure, and the only place either path is spelled: every command in this directory takes a
* layout rather than naming `~/.penguin` itself.
*/
-import { DEFAULT_DEV_SERVER_PORT, DEFAULT_SERVER_PORT } from "@lmliheng/penguin-core";
+import { DEFAULT_DEV_SERVER_PORT, DEFAULT_SERVER_PORT, boundaryEnv } from "@lmliheng/penguin-core";
export type Profile = "release" | "dev";
@@ -41,9 +42,10 @@ export interface RemoteLayout {
ownsCommand: boolean;
}
-/** `PENGUIN_PROFILE=dev` selects the dev profile; anything else is release. */
+/** `ADELIE_PROFILE=dev` (or the pre-rename `PENGUIN_PROFILE`, still read) selects the dev
+ * profile; anything else is release. */
export function profileFromEnv(env: NodeJS.ProcessEnv): Profile {
- return env.PENGUIN_PROFILE?.trim() === "dev" ? "dev" : "release";
+ return boundaryEnv(env, "profile")?.trim() === "dev" ? "dev" : "release";
}
export function remoteLayoutFor(profile: Profile): RemoteLayout {
diff --git a/packages/server/src/reset-admin-password.ts b/packages/server/src/reset-admin-password.ts
index 367b59b0..225e32d9 100644
--- a/packages/server/src/reset-admin-password.ts
+++ b/packages/server/src/reset-admin-password.ts
@@ -28,7 +28,7 @@ export type ResetAdminPasswordResult =
/** Returned to the unclaimed state: start the server and open the first-login link it prints. */
| { outcome: "reset" };
-/** `dbPath` may be elsewhere (PENGUIN_WEB_DB); `root` stays the root, which the sweep needs. */
+/** `dbPath` may be elsewhere (ADELIE_WEB_DB, or its pre-rename PENGUIN_WEB_DB); `root` stays the root, which the sweep needs. */
export async function resetAdminPassword(
root: string,
dbPath: string = path.join(root, "web.db"),
diff --git a/packages/server/src/services/desktop-service.ts b/packages/server/src/services/desktop-service.ts
index d199b17c..834d90a4 100644
--- a/packages/server/src/services/desktop-service.ts
+++ b/packages/server/src/services/desktop-service.ts
@@ -1,5 +1,6 @@
/**
- * Desktop mode (PENGUIN_DESKTOP_TOKEN): the shell that spawned this server proves itself
+ * Desktop mode (ADELIE_DESKTOP_TOKEN, or the pre-rename PENGUIN_DESKTOP_TOKEN the shell still
+ * exports): the shell that spawned this server proves itself
* with a per-launch random token, which backs two endpoints with different consumption
* rules:
*
diff --git a/packages/server/src/services/update-job.ts b/packages/server/src/services/update-job.ts
index faf71e53..966a867b 100644
--- a/packages/server/src/services/update-job.ts
+++ b/packages/server/src/services/update-job.ts
@@ -6,8 +6,9 @@
* process: a start while one runs joins it, and the finished status stays readable until
* the next start (which is also how a failed run is retried).
*
- * How the self-update works: `penguin server|web` exports PENGUIN_CLI_ENTRY (its own entry
- * script path) before importing this server, and the job re-runs that script as
+ * How the self-update works: `penguin server|web` exports its own entry script path as
+ * PENGUIN_CLI_ENTRY — the pre-rename spelling of ADELIE_CLI_ENTRY, and the config parser
+ * reads both — before importing this server, and the job re-runs that script as
* `node <entry> update --yes` — the CLI's update command owns all install-kind detection,
* download and replacement logic (packages/cli/src/commands/update.ts). A server started
* any other way (tests, a custom embedding) has no CLI to run and reports "unsupported".
diff --git a/packages/server/test/config.test.ts b/packages/server/test/config.test.ts
index 446178fc..0d0bd7a3 100644
--- a/packages/server/test/config.test.ts
+++ b/packages/server/test/config.test.ts
@@ -6,8 +6,10 @@
* non-integer or out-of-range value throws. This matches the CLI's resolvePort.
* - ADELIE_SEED_ADMIN_PASSWORD: unset, empty or blank leaves the seed unpinned (null, so the
* seed generates its own); a value is kept trimmed; desktop mode changes neither.
- * - PENGUIN_CLI_ENTRY: a value is kept trimmed; a blank one falls through to the checkout
- * lookup like an unset one.
+ * - ADELIE_CLI_ENTRY (or the pre-rename PENGUIN_CLI_ENTRY): a value is kept trimmed; a blank one
+ * falls through to the checkout lookup like an unset one.
+ * - The deployment names live in two spellings while their writers are outside this repository
+ * (core's state/boundary-env.ts): ADELIE_* wins, PENGUIN_* still reads.
* - PENGUIN_GO_ORIGIN accepts a loopback HTTP origin for integration work and refuses anything
* that is not a bare origin, or plaintext HTTP to another host.
* - MODELSCOPE_BRIDGE_URL may carry a path prefix but refuses plaintext HTTP, credentials, a
@@ -90,8 +92,13 @@ describe("resolveServerConfig: seed password", () => {
});
});
-describe("resolveServerConfig: PENGUIN_CLI_ENTRY parsing", () => {
+describe("resolveServerConfig: ADELIE_CLI_ENTRY parsing", () => {
it("keeps a value trimmed — it is what the <root>/bin/penguin shim execs", () => {
+ expect(
+ resolveServerConfig({ ...base, ADELIE_CLI_ENTRY: " /opt/adelie/dist/penguin.js " }).cliEntry,
+ ).toBe("/opt/adelie/dist/penguin.js");
+ // The pre-rename name is still what `penguin server|web` exports and the desktop shell
+ // passes, so a deployment that only sets it keeps working.
expect(
resolveServerConfig({ ...base, PENGUIN_CLI_ENTRY: " /opt/penguin/dist/penguin.js " })
.cliEntry,
@@ -102,12 +109,46 @@ describe("resolveServerConfig: PENGUIN_CLI_ENTRY parsing", () => {
// What the lookup finds depends on whether this checkout has built its CLI, so the
// claim here is only that a blank value is not treated as an entry (see cli-shim.test.ts
// for checkoutCliEntry itself).
- const blank = resolveServerConfig({ ...base, PENGUIN_CLI_ENTRY: " " }).cliEntry;
+ const blank = resolveServerConfig({ ...base, ADELIE_CLI_ENTRY: " " }).cliEntry;
expect(blank).toBe(resolveServerConfig({ ...base }).cliEntry);
expect(blank === null || blank?.endsWith(`${path.sep}penguin.js`)).toBe(true);
});
});
+describe("resolveServerConfig: the deployment names read in both spellings", () => {
+ it("prefers the ADELIE_* spelling of every one of them", () => {
+ const config = resolveServerConfig({
+ ...base,
+ ADELIE_WEB_DIST: "/srv/adelie/web",
+ PENGUIN_WEB_DIST: "/opt/penguin/web",
+ ADELIE_WEB_DB: "/srv/adelie/web.db",
+ PENGUIN_WEB_DB: "/opt/penguin/web.db",
+ ADELIE_PORT_FILE: "/run/adelie.port",
+ PENGUIN_PORT_FILE: "/run/penguin.port",
+ ADELIE_DESKTOP_TOKEN: " adelie-token ",
+ PENGUIN_DESKTOP_TOKEN: "penguin-token",
+ });
+ expect(config.webDist).toBe("/srv/adelie/web");
+ expect(config.dbPath).toBe("/srv/adelie/web.db");
+ expect(config.portFile).toBe("/run/adelie.port");
+ expect(config.desktopToken).toBe("adelie-token");
+ });
+
+ it("keeps reading the pre-rename spelling an existing deployment or the shell sets", () => {
+ const config = resolveServerConfig({
+ ...base,
+ PENGUIN_WEB_DIST: "/opt/penguin/web",
+ PENGUIN_WEB_DB: "/opt/penguin/web.db",
+ PENGUIN_PORT_FILE: "/run/penguin.port",
+ PENGUIN_DESKTOP_TOKEN: "penguin-token",
+ });
+ expect(config.webDist).toBe("/opt/penguin/web");
+ expect(config.dbPath).toBe("/opt/penguin/web.db");
+ expect(config.portFile).toBe("/run/penguin.port");
+ expect(config.desktopToken).toBe("penguin-token");
+ });
+});
+
describe("resolveServerConfig: PENGUIN_GO_ORIGIN parsing", () => {
it("accepts a loopback HTTP origin for integration work, trimmed", () => {
expect(
diff --git a/packages/server/test/machines.test.ts b/packages/server/test/machines.test.ts
index 8f5d6bf4..8de65c24 100644
--- a/packages/server/test/machines.test.ts
+++ b/packages/server/test/machines.test.ts
@@ -453,8 +453,10 @@ describe("asking `penguin server status` in the machine's own dialect", () => {
it("carries the profile to the far side, so a server started there reaches on in the same one", () => {
// That server has a machines service of its own, and it reads its layout from
- // PENGUIN_PROFILE. Without the variable a dev-profile server would reach the NEXT
- // machine's release installation — the profile would hold for exactly one hop.
+ // PENGUIN_PROFILE (or ADELIE_PROFILE — both are read; the command spells the pre-rename
+ // one because the far side may be an older install). Without the variable a dev-profile
+ // server would reach the NEXT machine's release installation — the profile would hold for
+ // exactly one hop.
expect(readServerStateCommand("linux", DEV)).toContain(" PENGUIN_PROFILE=dev ");
expect(readServerStateCommand("win32", DEV)).toContain('set "PENGUIN_PROFILE=dev" & ');
// Named for release too: an account exporting the variable cannot flip a release server.
@@ -634,11 +636,16 @@ describe("startRemoteServer", () => {
});
describe("remote layout", () => {
- it("is the release installation unless PENGUIN_PROFILE says dev", () => {
+ it("is the release installation unless PENGUIN_PROFILE (or ADELIE_PROFILE) says dev", () => {
expect(profileFromEnv({})).toBe("release");
expect(profileFromEnv({ PENGUIN_PROFILE: "release" })).toBe("release");
expect(profileFromEnv({ PENGUIN_PROFILE: "dev" })).toBe("dev");
expect(profileFromEnv({ PENGUIN_PROFILE: "anything-else" })).toBe("release");
+ // Adelie's own spelling, which wins: the shell that sets PROFILE is the pre-rename writer
+ // whose other end is outside this repository (core's state/boundary-env.ts).
+ expect(profileFromEnv({ ADELIE_PROFILE: "dev" })).toBe("dev");
+ expect(profileFromEnv({ ADELIE_PROFILE: "dev", PENGUIN_PROFILE: "release" })).toBe("dev");
+ expect(profileFromEnv({ ADELIE_PROFILE: " release " })).toBe("release");
});
it("keeps the two profiles apart on every axis: program, data root, port", () => {
diff --git a/packages/server/test/version.test.ts b/packages/server/test/version.test.ts
index 92cc7722..49c3c716 100644
--- a/packages/server/test/version.test.ts
+++ b/packages/server/test/version.test.ts
@@ -267,14 +267,22 @@ describe("UpdateCheckService", () => {
describe("POST /api/version/update", () => {
let t: TestApp;
let savedEntry: string | undefined;
+ let savedRenamed: string | undefined;
beforeEach(async () => {
+ // Both spellings: the route reads ADELIE_CLI_ENTRY first and PENGUIN_CLI_ENTRY after it
+ // (core's state/boundary-env.ts), so clearing only one of them would leave the other
+ // leaking in from the environment the test was started with.
savedEntry = process.env.PENGUIN_CLI_ENTRY;
+ savedRenamed = process.env.ADELIE_CLI_ENTRY;
delete process.env.PENGUIN_CLI_ENTRY;
+ delete process.env.ADELIE_CLI_ENTRY;
t = await createTestApp();
});
afterEach(async () => {
if (savedEntry === undefined) delete process.env.PENGUIN_CLI_ENTRY;
else process.env.PENGUIN_CLI_ENTRY = savedEntry;
+ if (savedRenamed === undefined) delete process.env.ADELIE_CLI_ENTRY;
+ else process.env.ADELIE_CLI_ENTRY = savedRenamed;
await t.cleanup();
});