Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

8.7 KB
Raw Blame
// Every knob the code reads must be documented where someone would look for it.
//
// CLAUDE.md carries this as a chore ("still grep process.env before adding a new
// one"), and the chore had already slipped: `OS_CODEX_BUILTIN_TOOLS` — which turns
// on provider-run tools that BILL to the owner's account — was readable by the code
// and absent from `.env.example`. A var nobody can find is a var nobody can turn
// off. This is that grep, run by the suite instead of by memory.
//
// The allowlist below is the other half of the contract: vars that are deliberately
// NOT in .env.example because you never set them by hand. Each one carries the
// reason, so adding to this list is a decision rather than a way to silence a test.
import { existsSync, readFileSync } from "node:fs";
import { execSync } from "node:child_process";
import path from "node:path";
import { describe, expect, it } from "vitest";

const ROOT = path.join(__dirname, "..", "..");

/** Not documented in .env.example, on purpose. */
const NOT_A_KNOB: Record<string, string> = {
  // Injected by the framework or the runtime.
  NEXT_RUNTIME: "set by Next itself",
  NODE_ENV: "standard Node/Next process mode; artifact maintenance starts only in production",
  NEXT_PUBLIC_BUILD_ID: "injected by next.config.mjs at build time",
  MSO_RUNTIME_INSTANCE_ID: "injected by the installer-managed service to prove restart readiness",
  // Set by scripts/verify-build.sh in the out-of-tree archive it just built, so the
  // bundle budget knows those bytes describe that source rather than a stale .next.
  MSO_BUNDLE_BUILD_IS_CURRENT: "set by scripts/verify-build.sh for its own out-of-tree build; never user configuration",
  // Private launcher-to-agent handoff. scripts/mso-cli-agent.sh owns these; users
  // should configure the public CLI knobs instead of persisting these in .env.local.
  MSO_AGENT_BASE: "internal mso-cli-agent launcher handoff for the selected loopback API base",
  MSO_AGENT_CLI: "internal mso-cli-agent launcher handoff for the canonical CLI path",
  MSO_AGENT_JAR: "internal mso-cli-agent launcher handoff for the authenticated cookie jar",
  MSO_AGENT_ORIGIN: "internal mso-cli-agent launcher handoff for the request Origin header",
  MSO_MAINTENANCE_LOCKED: "internal maintenance-lock.sh child handoff; never persist or set this as user configuration",
  MSO_AGENT_VERSION: "internal mso-cli-agent launcher handoff for banner metadata",
  // Read by bin/orca-mcp.mjs, an MCP stdio bridge a client spawns locally. It
  // points at the Orca CLI binary; the app itself never reads it.
  ORCA_BIN: "override for the Orca CLI path used by the bin/orca-mcp.mjs stdio bridge, not by the MSO app",
  // Standard terminal convention inherited from the invoking shell, not MSO config.
  NO_COLOR: "standard terminal color convention inherited from the caller",
  VITEST: "set by the test runner",
  // Read by scripts/integrations-ui-evidence.mjs, the browser evidence harness.
  MSO_EVIDENCE_DIR: "output directory for the integrations UI evidence harness; local diagnostics only",
  // The OS gives these to every process.
  SHELL: "the OS's",
  PATH: "standard executable search path inherited by the lifecycle test harness",
  HOME: "the OS's",
  XDG_RUNTIME_DIR: "set by logind, or by the unit — see lib/managed-apps/user-bus.ts",
  // Standard XDG base directory. Read only as the default parent of the update timer
  // units; MSO_SYSTEMD_USER_DIR is the documented override.
  XDG_CONFIG_HOME: "standard XDG base-directory convention; MSO_SYSTEMD_USER_DIR overrides its use",
  // scripts/audit.mjs seams, not app configuration: the audit contract tests shorten
  // the bounded registry probe and relocate its receipt so they never touch the cache.
  MSO_AUDIT_TIMEOUT_MS: "scripts/audit.mjs registry probe ceiling; test seam",
  MSO_AUDIT_ATTEMPTS: "scripts/audit.mjs registry probe retry count; test seam",
  MSO_AUDIT_BACKOFF_MS: "scripts/audit.mjs registry probe backoff; test seam",
  MSO_AUDIT_BUDGET_MS: "scripts/audit.mjs registry probe total budget; test seam",
  MSO_AUDIT_RECEIPT: "scripts/audit.mjs receipt path; test seam, not user configuration",
  // systemd's, read by instrumentation for the watchdog handshake.
  NOTIFY_SOCKET: "systemd's",
  WATCHDOG_USEC: "systemd's",
  // Orca lifecycle test fixtures. scripts/orca/fixtures/*.mjs are disposable
  // stand-ins for the real server, daemon, and CLI; these select fake behavior.
  FAKE_ADVERTISED: "Orca test fixture only: fake server's advertised pairing endpoint",
  FAKE_CLI_LOG: "Orca test fixture only: fixture CLI invocation log path",
  FAKE_CLI_MODE: "Orca test fixture only: fixture CLI behavior selector",
  FAKE_CLI_TOKEN: "Orca test fixture only: fixture CLI echo token",
  FAKE_CRASH_DELAY_MS: "Orca test fixture only: fake server's delayed-crash timing",
  FAKE_DAEMON_DELAY_MS: "Orca test fixture only: fake daemon's pid-record delay",
  FAKE_DAEMON_ENTRY: "Orca test fixture only: fake server's daemon entry path",
  FAKE_MODE: "Orca test fixture only: fake server scenario selector",
  FAKE_READY_DELAY_MS: "Orca test fixture only: fake server's delay before readiness output",
  // Private installer handoff. lib/managed-apps/install.ts derives these from
  // operator-facing install options and passes them to the install scripts.
  MSO_INSTALL_APP_ORIGIN: "private MSO installer-to-app handoff for the configured split app origin; not an operator knob",
  MSO_INSTALL_GATEWAY_BIND: "private MSO installer-to-app handoff for the validated gateway bind mode; not an operator knob",
  // Private Orca runtime environment. scripts/orca/env.mjs writes this into the
  // isolated child env so the runtime uses the scratch user-data directory.
  ORCA_USER_DATA: "private isolated Orca runtime env set by scripts/orca/env.mjs; not a deployment knob",
  // Test + tooling only, never part of a deployment.
  E2E_BASE_URL: "test harness",
  MSO_SCREENSHOT_DIR: "injected per-session artifact staging path for browser tooling; never persistent app configuration",
  E2E_DEMO: "desktop browser harness only: preview has no authentication; never production configuration",
  E2E_CAPTURE_ONLY: "desktop browser harness only: capture baseline before native behavior assertions",
  CHROME_PATH: "MCP Page browser contract harness executable override, not production configuration",
  MSO_SOCKET_POLICY_SECRET: "generated fresh by the production process; never an operator knob",
  E2E_PASSWORD: "test harness",
  E2E_DEVICE: "test harness",
  E2E_HEADED: "test harness",
  MSO_RUNTIME_PROC_ROOT: "test-only fake /proc root for live-runtime ownership tests",
  OS_MEDIA_BASE: "scripts/gen-readme-media.mjs only",
  OS_MEDIA_DEVICE: "scripts/gen-readme-media.mjs only",
};

function usedEnvNames(): string[] {
  const files = execSync("git ls-files --cached --others --exclude-standard '*.ts' '*.tsx' '*.mjs'", { cwd: ROOT, encoding: "utf8" })
    .split("\n")
    .filter(Boolean)
    // A test may stub anything, so .test files do not count as "the app reads it".
    // The e2e HARNESSES do count — they are committed code, and the vars they read
    // are exactly the ones that belong in NOT_A_KNOB rather than in .env.example.
    .filter((f) => !f.includes(".test."))
    // `git ls-files --cached` still reports tracked paths deleted in the working tree.
    // Ignore those so pre-commit verification can validate intentional file retirement.
    .filter((f) => existsSync(path.join(ROOT, f)));
  const names = new Set<string>();
  for (const file of files) {
    const src = readFileSync(path.join(ROOT, file), "utf8");
    for (const m of src.matchAll(/process\.env\.([A-Z][A-Z_0-9]{2,})/g)) names.add(m[1]);
    // `process.env["X"]` and destructuring are not used here; if they appear, this
    // regex stops seeing them — which is why the reconciliation lives in a test that
    // someone will read, not in a silent script.
  }
  return [...names].sort();
}

describe(".env.example documents every knob", () => {
  const example = readFileSync(path.join(ROOT, ".env.example"), "utf8");
  const documented = new Set(
    [...example.matchAll(/^#?\s*([A-Z][A-Z_0-9]+)=/gm)].map((m) => m[1]),
  );

  it("has a line for each env var the app reads", () => {
    const missing = usedEnvNames().filter((n) => !documented.has(n) && !(n in NOT_A_KNOB));
    expect(missing, "add these to .env.example, or to NOT_A_KNOB with a reason").toEqual([]);
  });

  it("keeps the exemption list honest — every entry is still read somewhere", () => {
    const used = new Set(usedEnvNames());
    // An exemption for a var the code no longer reads is stale lore that outlives
    // the reason it was written.
    const stale = Object.keys(NOT_A_KNOB).filter((n) => !used.has(n));
    expect(stale, "these are exempted but no longer read — drop them").toEqual([]);
  });
});