@legionworks/facet 1.9.0

package/src/cli/service-metadata.ts

@@ -0,0 +1,134 @@
+/**
+ * Service metadata helpers shared by the lazy spawn path and any
+ * future CLI surface that needs to peek at the live loopback service.
+ *
+ * Three responsibilities:
+ *
+ *   1. Read the install token from disk (the CLI never auto-generates
+ *      tokens; the service does on its first start).
+ *   2. Read the validated metadata record and classify it as live,
+ *      stale, cross-version, or missing. The classification drives
+ *      every spawn decision.
+ *   3. Wait for the metadata record to become ready (port > 0, live
+ *      pid, matching contract version) under a bounded deadline.
+ *      Never a fixed sleep.
+ *
+ * Extracted from `spawn-service.ts` so the orchestrator stays under
+ * the 300-line hard cap; the helpers here are the kind that grow as
+ * new edge cases get defended.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { FacetError } from "../shared/errors/facet-error";
+import { FACET_SCHEMA_VERSION } from "../shared/contracts/envelope";
+import {
+  isLockStale,
+  readLockMetadata,
+  type LockMetadata,
+} from "../service/lifecycle/process-lock";
+import { isPidAlive } from "../service/lifecycle/process-lock";
+import type { FacetRuntimePaths } from "../shared/config/paths";
+
+/**
+ * Build the typed contract-mismatch error used by every code path
+ * that observes a cross-version lock. Lives in one place so the
+ * error body shape cannot drift between the fast-path and the
+ * wait-for-ready path.
+ */
+export function contractMismatchError(meta: {
+  pid: number;
+  port: number;
+  contractVersion: string;
+}): FacetError {
+  return new FacetError(
+    "internal",
+    `Service contract version mismatch: service=${meta.contractVersion}, cli=${FACET_SCHEMA_VERSION}`,
+    {
+      retryable: false,
+      details: {
+        reason: "contract_version_mismatch",
+        service: meta.contractVersion,
+        cli: FACET_SCHEMA_VERSION,
+        pid: meta.pid,
+        port: meta.port,
+      },
+    },
+  );
+}
+
+/**
+ * Read the install token from disk. The token is created by the
+ * service during its first start; if the lock is missing the token
+ * is too. The CLI never auto-generates tokens — that is a
+ * service-side responsibility.
+ */
+export function readInstallToken(paths: FacetRuntimePaths): string {
+  const tokenPath = paths.token.replace(/promote\.token$/, "install.token");
+  if (!existsSync(tokenPath)) {
+    throw new FacetError(
+      "internal",
+      `Install token not found at ${tokenPath}; the service must start before the CLI can talk to it`,
+      { retryable: true, details: { tokenPath } },
+    );
+  }
+  const value = readFileSync(tokenPath, "utf8").trim();
+  if (value.length === 0) {
+    throw new FacetError("internal", `Install token at ${tokenPath} is empty`, {
+      retryable: false,
+      details: { tokenPath },
+    });
+  }
+  return value;
+}
+
+/**
+ * Read a usable metadata record from disk. Returns the record only
+ * when it points at a live, contract-version-matching service.
+ * Returns null in every other case (missing, stale, dead pid) so the
+ * caller can decide whether to spawn or surface a typed error.
+ *
+ * Cross-version live records are reported as `null` here — the caller
+ * uses `readLiveMetadata` only for the same-version fast path and
+ * branches on contract version separately to surface the typed
+ * mismatch error.
+ */
+export function readLiveMetadata(paths: FacetRuntimePaths): LockMetadata | null {
+  const meta = readLockMetadata(paths.lock);
+  if (meta === null) return null;
+  if (meta.contractVersion !== FACET_SCHEMA_VERSION) return null;
+  if (!isPidAlive(meta.pid)) return null;
+  if (isLockStale(meta)) return null;
+  return meta;
+}
+
+/**
+ * Wait for the metadata record to appear with a non-zero port —
+ * `startFacetService` writes the port AFTER the kernel-assigned
+ * bind succeeds, so a port>0 record means a serving loopback.
+ * Poll-with-deadline — never a fixed sleep. Throws a typed
+ * `contract_version_mismatch` if the record appears with a future
+ * schema version (a build upgrade) and a typed `internal` on
+ * deadline.
+ */
+export async function waitForReady(
+  paths: FacetRuntimePaths,
+  timeoutMs: number,
+  intervalMs: number,
+): Promise<LockMetadata> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const meta = readLockMetadata(paths.lock);
+    if (meta !== null && meta.port > 0) {
+      if (meta.contractVersion !== FACET_SCHEMA_VERSION) {
+        throw contractMismatchError(meta);
+      }
+      if (isPidAlive(meta.pid)) return meta;
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new FacetError("internal", "Service did not become ready before deadline", {
+    retryable: true,
+    details: { timeoutMs, lockPath: paths.lock },
+  });
+}

package/src/cli/spawn-service.ts

@@ -0,0 +1,326 @@
+/**
+ * Lazy service spawn.
+ *
+ * First cold CLI call reads the validated service metadata record
+ * written by `startFacetService` (see
+ * `src/service/lifecycle/process-lock.ts`). If the record is absent
+ * or stale, the spawner reaps the stale lock and forks a DETACHED
+ * `bun run src/service/main.ts` child carrying the same `FACET_HOME`
+ * so the child sees the same paths the parent did.
+ *
+ * Concurrency: a single in-process `inflight` Promise is shared
+ * across every cold caller. The Promise resolves only when the
+ * metadata record reports a live, contract-version-matching service
+ * (poll-with-deadline — never a fixed sleep). A second caller that
+ * arrives while the first is waiting joins the SAME Promise, so
+ * 20 concurrent cold calls result in exactly ONE spawn and ONE
+ * metadata record on disk.
+ *
+ * The child is started with `child_process.spawn` detached + `unref`,
+ * so the parent can exit without leaving the service as a zombie;
+ * the service owns its own lifecycle via the idle controller.
+ */
+
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { unlinkSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+
+import { FACET_SCHEMA_VERSION } from "../shared/contracts/envelope";
+import { isCompiledRuntime, type ServiceLaunch } from "../shared/build-mode";
+import { isLockStale, readLockMetadata } from "../service/lifecycle/process-lock";
+import { computeFacetPaths, type FacetRuntimePaths } from "../shared/config/paths";
+import { isPidAlive } from "../service/lifecycle/process-lock";
+import type { LockMetadata } from "../service/lifecycle/process-lock";
+
+import {
+  contractMismatchError,
+  readInstallToken,
+  readLiveMetadata,
+  waitForReady,
+} from "./service-metadata";
+
+export interface SpawnServiceOptions {
+  readonly env: NodeJS.ProcessEnv;
+  /** Override the runtime paths; defaults to `computeFacetPaths(env)`. */
+  readonly paths?: FacetRuntimePaths;
+  /** Override the service entrypoint (default: `src/service/main.ts`). */
+  readonly entrypoint?: string;
+  /** Override the bun binary (default: `process.execPath`). */
+  readonly bunPath?: string;
+  /** Polling deadline in ms (default: 15000). */
+  readonly readyTimeoutMs?: number;
+  /** Poll interval in ms (default: 25). */
+  readonly pollIntervalMs?: number;
+  /** Override the service idle window; used by lifecycle probes and tests. */
+  readonly idleTimeoutMs?: number;
+  /**
+   * Override the Tier 0 runner module path. Defaults to
+   * `src/validation/tier0/runner.ts` resolved relative to this file.
+   * The CLI owns this path because only the CLI may import the
+   * validation module directly; the service child dynamic-imports
+   * the path passed here.
+   */
+  readonly tier0RunnerPath?: string;
+  /** Override the Tier 1 runner module path for insecure boots. */
+  readonly tier1RunnerPath?: string;
+  /** Explicit process launch mode; defaults to the current Bun build mode. */
+  readonly launch?: ServiceLaunch;
+}
+
+/**
+ * Test-side hooks. The `onServiceSpawn` callback fires once per
+ * REAL `child_process.spawn` call in the cold-start path; the
+ * concurrency test counts these to assert that 20 concurrent
+ * cold callers result in exactly ONE spawn (not 20). The
+ * `bypassInflight` flag skips the in-process inflight wait map
+ * so the test can prove the "exactly one" assertion is meaningful
+ * (with bypass on, the same 20 callers produce 20 spawns).
+ */
+export interface ServiceHooks {
+  readonly onServiceSpawn?: (argv?: readonly string[], stderr?: "ignore" | "inherit") => void;
+  readonly bypassInflight?: boolean;
+}
+
+export interface ResolvedService {
+  readonly metadata: LockMetadata;
+  readonly installToken: string;
+  readonly baseUrl: string;
+}
+
+const DEFAULT_READY_TIMEOUT_MS = 15_000;
+const DEFAULT_POLL_INTERVAL_MS = 25;
+
+/**
+ * One-process registry of in-flight spawn waits. The CLI is
+ * short-lived (one invocation per process), so the table holds at
+ * most ONE entry at a time in practice. The map exists so the
+ * test that races 20 cold callers can observe the join path:
+ * callers 2..N must NOT acquire the lock or fork a new process.
+ */
+const inflight = new Map<string, Promise<ResolvedService>>();
+
+/**
+ * Build the service child's argv. Extracted from `spawnChild` so the
+ * parent/child path-agreement contract is unit-testable without a real
+ * spawn: every per-path override the parent passes on the command line
+ * (db, tokens, lock, evidence) must be present and equal the parent's
+ * `paths` so a future change to `computeFacetPaths` cannot desync them.
+ */
+export function buildServiceSpawnArgs(
+  paths: FacetRuntimePaths,
+  options: ServiceLaunch & { readonly idleTimeoutMs?: number },
+): string[] {
+  const args = [
+    ...(options.mode === "compiled" ? ["--facet-internal-service"] : [options.entrypoint]),
+    "--db-path",
+    paths.database,
+    "--install-token-path",
+    paths.token.replace(/promote\.token$/, "install.token"),
+    "--promote-token-path",
+    paths.token,
+    "--lock-path",
+    paths.lock,
+    "--evidence-path",
+    paths.evidence,
+    ...(options.mode === "source"
+      ? [
+          "--tier0-runner-path",
+          options.tier0RunnerPath,
+          "--tier1-runner-path",
+          options.tier1RunnerPath,
+        ]
+      : []),
+  ];
+  if (options.idleTimeoutMs !== undefined) {
+    args.push("--idle-timeout-ms", String(options.idleTimeoutMs));
+  }
+  return args;
+}
+
+/**
+ * Spawn the service as a detached child. The child inherits
+ * `FACET_HOME` so its paths match the parent's; the parent passes
+ * the same paths on the command line so a future change to
+ * `computeFacetPaths` cannot desync parent and child.
+ */
+function spawnChild(
+  paths: FacetRuntimePaths,
+  options: SpawnServiceOptions,
+  onSpawn?: (argv?: readonly string[], stderr?: "ignore" | "inherit") => void,
+): ChildProcess {
+  const bunPath = options.bunPath ?? process.execPath;
+  const facetHome = paths.database
+    ? resolvePath(dirname(dirname(paths.database)))
+    : (options.env.FACET_HOME ?? "");
+  const childEnv: NodeJS.ProcessEnv = {
+    ...options.env,
+    FACET_HOME: facetHome,
+  };
+  // Pass per-path overrides as flags so the child does not have to
+  // recompute paths from FACET_HOME; this keeps parent + child
+  // identical even when an operator sets XDG_* vars.
+  const launch = options.launch ?? resolveServiceLaunch(options);
+  const args = buildServiceSpawnArgs(paths, {
+    ...launch,
+    ...(options.idleTimeoutMs !== undefined ? { idleTimeoutMs: options.idleTimeoutMs } : {}),
+  });
+  const insecureBoot =
+    ["1", "2", "3"].includes(options.env.FACET_INSECURE ?? "") ||
+    options.env.FACET_INSECURE_AUTO === "1";
+  const stderr = insecureBoot ? "inherit" : "ignore";
+  onSpawn?.(args, stderr);
+  return spawn(bunPath, args, {
+    env: childEnv,
+    stdio: ["ignore", "ignore", stderr],
+    detached: true,
+  });
+}
+
+function resolveServiceLaunch(options: SpawnServiceOptions): ServiceLaunch {
+  if (isCompiledRuntime()) return { mode: "compiled" };
+  return {
+    mode: "source",
+    entrypoint: options.entrypoint ?? resolvePath(import.meta.dir, "..", "service", "main.ts"),
+    tier0RunnerPath: options.tier0RunnerPath ?? resolveDefaultTier0RunnerPath(),
+    tier1RunnerPath: options.tier1RunnerPath ?? resolveDefaultTier1RunnerPath(),
+  };
+}
+
+/**
+ * Default Tier 0 runner module path. Resolved relative to this file
+ * (which lives in `src/cli/`) so the import is `../validation/tier0/runner`.
+ * Callers can override via `SpawnServiceOptions.tier0RunnerPath` for
+ * tests or for custom builds.
+ */
+function resolveDefaultTier0RunnerPath(): string {
+  return resolvePath(import.meta.dir, "..", "validation", "tier0", "runner.ts");
+}
+
+function resolveDefaultTier1RunnerPath(): string {
+  return resolvePath(import.meta.dir, "..", "validation", "tier1", "runner.ts");
+}
+
+/**
+ * Reap a stale lock whose owner is dead, so the spawn path can
+ * fork a fresh service. Best-effort: a parallel cold start may
+ * race and either win the lock or retry; both outcomes are safe.
+ */
+function reapStaleLock(lockPath: string): void {
+  const existing = readLockMetadata(lockPath);
+  if (existing === null) return;
+  if (isPidAlive(existing.pid) && !isLockStale(existing)) return;
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    // ignore — a parallel cold start will retry.
+  }
+}
+
+/**
+ * Cold-start: fork the child + wait for ready. Throws typed
+ * `FacetError` on contract-mismatch and on ready-timeout.
+ *
+ * The CLI does NOT call `acquireLock` under its own pid — that
+ * would be a foreign-pid lock the child could never reclaim without
+ * killing the parent. Instead the CLI reaps a stale lock and forks
+ * the child, which acquires the lock on its own startup path via
+ * `startFacetService`.
+ *
+ * The `onServiceSpawn` hook fires once before each real
+ * `child_process.spawn` call; the concurrency test uses it to
+ * assert that 20 concurrent cold callers produce exactly ONE
+ * spawn (not 20).
+ */
+async function coldStart(
+  options: SpawnServiceOptions,
+  hooks: ServiceHooks = {},
+): Promise<ResolvedService> {
+  const env = options.env.FACET_HOME !== undefined ? { facetHome: options.env.FACET_HOME } : {};
+  const paths = options.paths ?? computeFacetPaths(env);
+  reapStaleLock(paths.lock);
+  // Pre-spawn guard: a live same-version foreign-pid owner means a
+  // peer service is already running. The CLI joins that peer via
+  // the metadata record instead of forking a second instance.
+  const precheck = readLockMetadata(paths.lock);
+  if (precheck !== null && isPidAlive(precheck.pid) && !isLockStale(precheck)) {
+    if (precheck.contractVersion !== FACET_SCHEMA_VERSION) {
+      throw contractMismatchError(precheck);
+    }
+    return {
+      metadata: precheck,
+      installToken: readInstallToken(paths),
+      baseUrl: `http://127.0.0.1:${precheck.port}`,
+    };
+  }
+  const child = spawnChild(paths, options, hooks.onServiceSpawn);
+  // Detach the child from the parent's lifecycle — when the CLI
+  // exits, the service keeps running until its idle window closes.
+  child.unref();
+  void child;
+  const meta = await waitForReady(
+    paths,
+    options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+    options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+  );
+  return {
+    metadata: meta,
+    installToken: readInstallToken(paths),
+    baseUrl: `http://127.0.0.1:${meta.port}`,
+  };
+}
+
+/**
+ * Ensure a live, contract-version-matching service is running. If
+ * one is already running, return its info; if not, lazily start one
+ * and share the wait across concurrent callers.
+ *
+ * Returns the resolved service's baseUrl, metadata, and install
+ * token. Throws typed `FacetError` on contract-version mismatch
+ * and on the ready deadline.
+ */
+export async function ensureService(
+  options: SpawnServiceOptions,
+  hooks: ServiceHooks = {},
+): Promise<ResolvedService> {
+  const env = options.env.FACET_HOME !== undefined ? { facetHome: options.env.FACET_HOME } : {};
+  const paths = options.paths ?? computeFacetPaths(env);
+  const key = paths.lock;
+
+  // Fast path: a usable same-version record already exists.
+  const live = readLiveMetadata(paths);
+  if (live !== null) {
+    return {
+      metadata: live,
+      installToken: readInstallToken(paths),
+      baseUrl: `http://127.0.0.1:${live.port}`,
+    };
+  }
+
+  // A live foreign owner cannot be used or reclaimed. A dead owner falls
+  // through so coldStart can reap its stale lock before spawning.
+  const raw = readLockMetadata(paths.lock);
+  if (raw !== null) {
+    if (raw.contractVersion !== FACET_SCHEMA_VERSION && isPidAlive(raw.pid)) {
+      throw contractMismatchError(raw);
+    }
+    // Same-version but stale (dead pid): fall through to the cold
+    // path so a fresh service replaces it.
+  }
+
+  // Concurrent-caller fast path: another caller in this process is
+  // already spawning. Join the same wait. `bypassInflight` is a
+  // test-only flag that disables this join so the concurrency
+  // test can prove the join path is doing real work.
+  if (!hooks.bypassInflight) {
+    const pending = inflight.get(key);
+    if (pending !== undefined) return pending;
+  }
+
+  // Cold path: become the spawner.
+  const promise = coldStart(options, hooks).finally(() => {
+    inflight.delete(key);
+  });
+  inflight.set(key, promise);
+  return promise;
+}

package/src/css.d.ts

@@ -0,0 +1,4 @@
+declare module "*.css" {
+  const css: string;
+  export default css;
+}