@ratio-app/cli 0.1.1

package/dist/lib/orchestrator/child-runner.js

@@ -0,0 +1,471 @@
+// src/lib/orchestrator/child-runner.ts
+import { spawn } from "child_process";
+
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+var OrchestratorSpawnError = class extends RatioCLIError {
+  constructor(message, hint = "Could not start your app's dev command \u2014 check that the command in ratio.config.jsonc runs from this directory.") {
+    super({ code: "ORCHESTRATOR_SPAWN", exitCode: 10, message, hint });
+  }
+};
+var OrchestratorDrainTimeoutError = class extends RatioCLIError {
+  constructor(message, hint = "Your dev command did not exit cleanly within 5 seconds \u2014 it was forcibly terminated.") {
+    super({ code: "ORCHESTRATOR_DRAIN", exitCode: 11, message, hint });
+  }
+};
+
+// src/lib/manifest/read-manifest.ts
+import fs2 from "fs";
+import path2 from "path";
+
+// src/lib/manifest/write-client-id.ts
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+
+// src/lib/manifest/read-manifest.ts
+var DEV_COMMAND_HINT = 'Add a "devCommand" entry to ratio.config.jsonc (e.g. "npm run dev") and re-run.';
+
+// src/lib/orchestrator/child-runner.ts
+var DRAIN_MS = 5e3;
+var RACE_WINDOW_MS = 200;
+var SIGNAL_FORCE_EXIT_WINDOW_MS = 2e3;
+var CHILD_BUFFER_MAX_BYTES = 64 * 1024;
+var DEV_COMMAND_TOKENIZE_HINT = "devCommand must be a simple whitespace-separated command; complex shell pipelines are not supported.";
+var DEFAULT_FORWARD_PORT = 3001;
+function tokenizeDevCommand(raw) {
+  const tokens = [];
+  let current = "";
+  let quote;
+  let hasToken = false;
+  for (let i = 0; i < raw.length; i += 1) {
+    const ch = raw.charAt(i);
+    if (quote !== void 0) {
+      if (ch === quote) {
+        quote = void 0;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      hasToken = true;
+      continue;
+    }
+    if (ch === " " || ch === "	" || ch === "\n" || ch === "\r") {
+      if (hasToken) {
+        tokens.push(current);
+        current = "";
+        hasToken = false;
+      }
+      continue;
+    }
+    if (ch === "|" || ch === "&" || ch === ";" || ch === "<" || ch === ">" || ch === "`") {
+      throw new ValidationError(
+        `devCommand contains an unsupported shell operator: ${ch}`,
+        DEV_COMMAND_TOKENIZE_HINT
+      );
+    }
+    if (ch === "$" && raw.charAt(i + 1) === "(") {
+      throw new ValidationError(
+        "devCommand contains an unsupported shell substitution.",
+        DEV_COMMAND_TOKENIZE_HINT
+      );
+    }
+    current += ch;
+    hasToken = true;
+  }
+  if (quote !== void 0) {
+    throw new ValidationError(
+      "devCommand has an unterminated quote.",
+      DEV_COMMAND_TOKENIZE_HINT
+    );
+  }
+  if (hasToken) {
+    tokens.push(current);
+  }
+  if (tokens.length === 0 || tokens[0] === "") {
+    throw new ValidationError("devCommand is empty.", DEV_COMMAND_HINT);
+  }
+  return tokens;
+}
+var LinePrefixer = class {
+  constructor(prefix, write) {
+    this.prefix = prefix;
+    this.write = write;
+  }
+  prefix;
+  write;
+  buffer = Buffer.alloc(0);
+  push(chunk) {
+    const incoming = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+    if (incoming.length === 0) {
+      return;
+    }
+    this.buffer = this.buffer.length === 0 ? incoming : Buffer.concat([this.buffer, incoming]);
+    this.drainCompleteLines();
+    if (this.buffer.length > CHILD_BUFFER_MAX_BYTES) {
+      this.flush();
+    }
+  }
+  /** Emit any buffered partial line (with prefix + newline), then reset. */
+  flush() {
+    if (this.buffer.length > 0) {
+      this.write(`${this.prefix}${this.buffer.toString("utf8")}
+`);
+      this.buffer = Buffer.alloc(0);
+    }
+  }
+  drainCompleteLines() {
+    let newlineAt = this.buffer.indexOf(10);
+    while (newlineAt !== -1) {
+      const line = this.buffer.subarray(0, newlineAt).toString("utf8");
+      this.buffer = this.buffer.subarray(newlineAt + 1);
+      this.write(`${this.prefix}${line}
+`);
+      newlineAt = this.buffer.indexOf(10);
+    }
+  }
+};
+var SIGNAL_EXIT_CODES = {
+  SIGHUP: 129,
+  SIGINT: 130,
+  SIGQUIT: 131,
+  SIGKILL: 137,
+  SIGTERM: 143
+};
+function exitCodeFrom(code, signal) {
+  if (code !== null) {
+    return code;
+  }
+  if (signal !== null) {
+    return SIGNAL_EXIT_CODES[signal] ?? 1;
+  }
+  return 1;
+}
+var ExitArbiter = class {
+  decidingChildCode;
+  signalCode;
+  get shutdownInitiated() {
+    return this.decidingChildCode !== void 0 || this.signalCode !== void 0;
+  }
+  observeChildExit(code, signal) {
+    if (this.shutdownInitiated) {
+      return;
+    }
+    this.decidingChildCode = exitCodeFrom(code, signal);
+  }
+  observeSignal(sig) {
+    if (this.shutdownInitiated) {
+      return;
+    }
+    this.signalCode = sig === "SIGINT" ? 130 : 143;
+  }
+  finalCode() {
+    return this.signalCode ?? this.decidingChildCode ?? 0;
+  }
+};
+var defaultSpawn = (command, args, options) => spawn(command, [...args], {
+  cwd: options.cwd,
+  env: options.env,
+  stdio: options.stdio,
+  shell: options.shell
+});
+function buildListenInvocation(env, devServerPort, argv1) {
+  const override = env.RATIO_DEV_LISTEN_BIN;
+  const listenBin = override ?? argv1;
+  if (listenBin === void 0 || listenBin === "") {
+    throw new OrchestratorSpawnError(
+      "Could not locate the CLI binary to start the webhook listener.",
+      "Re-install the CLI, or invoke it through its bin entry point."
+    );
+  }
+  const listenArgs = override ? [] : [
+    "dev",
+    "listen",
+    "--forward-to",
+    `localhost:${devServerPort ?? DEFAULT_FORWARD_PORT}/webhooks`
+  ];
+  return { command: process.execPath, args: [listenBin, ...listenArgs] };
+}
+function describeCause(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+async function orchestrate(options) {
+  const { io } = options;
+  const drainMs = options.drainMs ?? DRAIN_MS;
+  const spawnApp = options.spawnApp ?? defaultSpawn;
+  const spawnListen = options.spawnListen ?? defaultSpawn;
+  const trace = (line) => {
+    if (options.verbose) {
+      io.writeErr(`[verbose] ${line}
+`);
+    }
+  };
+  const appCommand = options.appArgv[0];
+  if (appCommand === void 0 || appCommand === "") {
+    throw new ValidationError("devCommand is empty.", DEV_COMMAND_HINT);
+  }
+  const appEnv = {
+    ...options.env,
+    ...options.devServerPort !== void 0 ? { PORT: String(options.devServerPort) } : {},
+    RATIO_ORCHESTRATED: "1"
+  };
+  let app;
+  try {
+    app = spawnApp(appCommand, options.appArgv.slice(1), {
+      cwd: options.cwd,
+      env: appEnv,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false
+    });
+  } catch (cause) {
+    throw new OrchestratorSpawnError(
+      `Could not start the dev command (${appCommand}): ${describeCause(cause)}`
+    );
+  }
+  trace(`spawn app: ${appCommand} (${app.pid ?? "-"})`);
+  const invocation = buildListenInvocation(
+    options.env,
+    options.devServerPort,
+    options.argv1 ?? process.argv[1]
+  );
+  const listenEnv = { ...options.env, RATIO_ORCHESTRATED: "1" };
+  let listen;
+  try {
+    listen = spawnListen(invocation.command, invocation.args, {
+      cwd: options.cwd,
+      env: listenEnv,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false
+    });
+  } catch (cause) {
+    app.kill("SIGTERM");
+    throw new OrchestratorSpawnError(
+      `Could not start the webhook listener: ${describeCause(cause)}`,
+      "The bundled webhook listener could not be started; re-install the CLI if this persists."
+    );
+  }
+  trace(`spawn listen: (${listen.pid ?? "-"})`);
+  const appOut = new LinePrefixer("[app] ", (chunk) => io.writeOut(chunk));
+  const appErrOut = new LinePrefixer("[app] ", (chunk) => io.writeOut(chunk));
+  const listenOut = new LinePrefixer("[listen] ", (chunk) => io.writeOut(chunk));
+  const listenErrOut = new LinePrefixer("[listen] ", (chunk) => io.writeOut(chunk));
+  const pipe = (stream, prefixer) => {
+    if (stream !== null) {
+      stream.on("data", (chunk) => prefixer.push(chunk));
+    }
+  };
+  pipe(app.stdout, appOut);
+  pipe(app.stderr, appErrOut);
+  pipe(listen.stdout, listenOut);
+  pipe(listen.stderr, listenErrOut);
+  const arbiter = new ExitArbiter();
+  let appExited = false;
+  let listenExited = false;
+  let spawnFailure;
+  let drainEscalated = false;
+  let drainTimer;
+  let drainStartedAt = 0;
+  let firstSignalAt = 0;
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      options.signalSource.removeListener("SIGINT", onSigint);
+      options.signalSource.removeListener("SIGTERM", onSigterm);
+      if (drainTimer !== void 0) {
+        clearTimeout(drainTimer);
+        drainTimer = void 0;
+      }
+      appOut.flush();
+      appErrOut.flush();
+      listenOut.flush();
+      listenErrOut.flush();
+    };
+    const settle = (code) => {
+      if (!settled) {
+        settled = true;
+        cleanup();
+        resolve(code);
+      }
+    };
+    const fail = (err) => {
+      if (!settled) {
+        settled = true;
+        cleanup();
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+    const startDrain = () => {
+      if (drainTimer !== void 0) {
+        return;
+      }
+      drainStartedAt = Date.now();
+      drainTimer = setTimeout(() => {
+        if (!appExited) {
+          app.kill("SIGKILL");
+          drainEscalated = true;
+        }
+        if (!listenExited) {
+          listen.kill("SIGKILL");
+          drainEscalated = true;
+        }
+      }, drainMs);
+    };
+    const finishIfDone = () => {
+      if (!appExited || !listenExited) {
+        return;
+      }
+      if (drainStartedAt > 0) {
+        trace(`drain elapsed: ${Date.now() - drainStartedAt}ms`);
+      }
+      const code = arbiter.finalCode();
+      void options.preview.onShutdown().then(
+        () => {
+          if (spawnFailure !== void 0) {
+            fail(spawnFailure);
+            return;
+          }
+          if (drainEscalated && code === 0) {
+            fail(
+              new OrchestratorDrainTimeoutError(
+                "A child process had to be forcibly terminated during shutdown."
+              )
+            );
+            return;
+          }
+          settle(code);
+        },
+        (err) => fail(err)
+      );
+    };
+    const onAppExit = (code, signal) => {
+      appExited = true;
+      appOut.flush();
+      appErrOut.flush();
+      trace(`app exited: code=${code} signal=${signal}`);
+      const alreadyShuttingDown = arbiter.shutdownInitiated;
+      arbiter.observeChildExit(code, signal);
+      if (!alreadyShuttingDown && !listenExited) {
+        listen.kill("SIGTERM");
+        startDrain();
+      }
+      finishIfDone();
+    };
+    const onListenExit = (code, signal) => {
+      listenExited = true;
+      listenOut.flush();
+      listenErrOut.flush();
+      trace(`listen exited: code=${code} signal=${signal}`);
+      const alreadyShuttingDown = arbiter.shutdownInitiated;
+      arbiter.observeChildExit(code, signal);
+      if (!alreadyShuttingDown && !appExited) {
+        app.kill("SIGTERM");
+        startDrain();
+      }
+      finishIfDone();
+    };
+    const onAppError = (err) => {
+      appExited = true;
+      if (spawnFailure === void 0) {
+        spawnFailure = new OrchestratorSpawnError(
+          `Could not start the dev command (${appCommand}): ${err.message}`
+        );
+      }
+      arbiter.observeChildExit(1, null);
+      if (!listenExited) {
+        listen.kill("SIGTERM");
+        startDrain();
+      }
+      finishIfDone();
+    };
+    const onListenError = (err) => {
+      listenExited = true;
+      if (spawnFailure === void 0) {
+        spawnFailure = new OrchestratorSpawnError(
+          `Could not start the webhook listener: ${err.message}`,
+          "The bundled webhook listener could not be started; re-install the CLI if this persists."
+        );
+      }
+      arbiter.observeChildExit(1, null);
+      if (!appExited) {
+        app.kill("SIGTERM");
+        startDrain();
+      }
+      finishIfDone();
+    };
+    const onSignal = (sig) => {
+      trace(`signal received: ${sig}`);
+      if (arbiter.shutdownInitiated) {
+        if (firstSignalAt === 0) {
+          firstSignalAt = Date.now();
+          return;
+        }
+        if (Date.now() - firstSignalAt <= SIGNAL_FORCE_EXIT_WINDOW_MS) {
+          options.hardExit(130);
+        }
+        return;
+      }
+      firstSignalAt = Date.now();
+      arbiter.observeSignal(sig);
+      io.writeErr("shutting down: stopping the dev command and the webhook listener\n");
+      if (!appExited) {
+        app.kill("SIGTERM");
+      }
+      if (!listenExited) {
+        listen.kill("SIGTERM");
+      }
+      startDrain();
+    };
+    const onSigint = () => onSignal("SIGINT");
+    const onSigterm = () => onSignal("SIGTERM");
+    options.signalSource.on("SIGINT", onSigint);
+    options.signalSource.on("SIGTERM", onSigterm);
+    app.once("exit", onAppExit);
+    app.once("error", onAppError);
+    listen.once("exit", onListenExit);
+    listen.once("error", onListenError);
+    trace(`preview: onDevServerReady(${options.devServerPort ?? 0})`);
+    void options.preview.onDevServerReady(options.devServerPort ?? 0).catch((err) => fail(err));
+  });
+}
+export {
+  CHILD_BUFFER_MAX_BYTES,
+  DEFAULT_FORWARD_PORT,
+  DEV_COMMAND_TOKENIZE_HINT,
+  DRAIN_MS,
+  ExitArbiter,
+  LinePrefixer,
+  RACE_WINDOW_MS,
+  SIGNAL_FORCE_EXIT_WINDOW_MS,
+  buildListenInvocation,
+  exitCodeFrom,
+  orchestrate,
+  tokenizeDevCommand
+};
+//# sourceMappingURL=child-runner.js.map

package/dist/lib/orchestrator/child-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/orchestrator/child-runner.ts","../../../src/lib/errors.ts","../../../src/lib/manifest/read-manifest.ts","../../../src/lib/manifest/write-client-id.ts"],"sourcesContent":["/**\n * Child-process runner for `ratio app dev`.\n *\n * Spawns two children — the app's own dev command and the webhook\n * listener — multiplexes their output onto stdout with per-child line\n * prefixes, and arbitrates a single deterministic exit code out of child\n * crashes and delivery of SIGINT/SIGTERM to the orchestrator.\n *\n * Everything process-shaped is injectable (spawn functions, signal\n * source, output sinks, hard-exit) so the full lifecycle is testable\n * without real dev servers or real signals.\n */\n\nimport { spawn } from 'node:child_process';\nimport {\n  OrchestratorDrainTimeoutError,\n  OrchestratorSpawnError,\n  ValidationError,\n} from '../errors.js';\nimport { DEV_COMMAND_HINT } from '../manifest/read-manifest.js';\nimport type { PreviewController } from '../preview/index.js';\n\n/** SIGTERM → SIGKILL grace window during shutdown. */\nexport const DRAIN_MS = 5_000;\n\n/**\n * Window within which \"both children crashed\" is arbitrated to the\n * first-observed exit. The arbiter is deterministic for every ordering\n * (first observed terminating cause always wins), which satisfies the\n * race rule for this window and beyond.\n */\nexport const RACE_WINDOW_MS = 200;\n\n/** A second interrupt inside this window forces an immediate exit (130). */\nexport const SIGNAL_FORCE_EXIT_WINDOW_MS = 2_000;\n\n/** Per-child line-buffer bound; overflow flushes a partial line. */\nexport const CHILD_BUFFER_MAX_BYTES = 64 * 1024;\n\n/** Hint shown when the dev command cannot be tokenized safely. */\nexport const DEV_COMMAND_TOKENIZE_HINT =\n  'devCommand must be a simple whitespace-separated command; complex shell pipelines are not supported.';\n\n/** Default forwarded-to port for the listener when the manifest has none. */\nexport const DEFAULT_FORWARD_PORT = 3001;\n\n// ── Tokenizer ──────────────────────────────────────────────────────────────\n\n/**\n * Split a dev command string into an argv array: whitespace-separated,\n * with single- or double-quoted segments kept together. Shell operators\n * (pipes, redirects, substitutions) are rejected outright — the command\n * is spawned without a shell, so they could never mean what the author\n * intended.\n */\nexport function tokenizeDevCommand(raw: string): string[] {\n  const tokens: string[] = [];\n  let current = '';\n  let quote: '\"' | \"'\" | undefined;\n  let hasToken = false;\n\n  for (let i = 0; i < raw.length; i += 1) {\n    const ch = raw.charAt(i);\n    if (quote !== undefined) {\n      if (ch === quote) {\n        quote = undefined;\n      } else {\n        current += ch;\n      }\n      continue;\n    }\n    if (ch === '\"' || ch === \"'\") {\n      quote = ch;\n      hasToken = true;\n      continue;\n    }\n    if (ch === ' ' || ch === '\\t' || ch === '\\n' || ch === '\\r') {\n      if (hasToken) {\n        tokens.push(current);\n        current = '';\n        hasToken = false;\n      }\n      continue;\n    }\n    if (ch === '|' || ch === '&' || ch === ';' || ch === '<' || ch === '>' || ch === '`') {\n      throw new ValidationError(\n        `devCommand contains an unsupported shell operator: ${ch}`,\n        DEV_COMMAND_TOKENIZE_HINT,\n      );\n    }\n    if (ch === '$' && raw.charAt(i + 1) === '(') {\n      throw new ValidationError(\n        'devCommand contains an unsupported shell substitution.',\n        DEV_COMMAND_TOKENIZE_HINT,\n      );\n    }\n    current += ch;\n    hasToken = true;\n  }\n\n  if (quote !== undefined) {\n    throw new ValidationError(\n      'devCommand has an unterminated quote.',\n      DEV_COMMAND_TOKENIZE_HINT,\n    );\n  }\n  if (hasToken) {\n    tokens.push(current);\n  }\n  if (tokens.length === 0 || tokens[0] === '') {\n    throw new ValidationError('devCommand is empty.', DEV_COMMAND_HINT);\n  }\n  return tokens;\n}\n\n// ── Log multiplexer ────────────────────────────────────────────────────────\n\n/**\n * Per-stream line buffer that emits `<prefix><line>\\n` only on newline\n * boundaries, so chunks split mid-line (or mid-UTF-8-character) never\n * corrupt the prefixed output. Bounded to CHILD_BUFFER_MAX_BYTES: on\n * overflow, the partial line is flushed with the prefix and a newline.\n */\nexport class LinePrefixer {\n  private buffer: Buffer = Buffer.alloc(0);\n\n  constructor(\n    private readonly prefix: string,\n    private readonly write: (chunk: string) => void,\n  ) {}\n\n  push(chunk: Buffer | string): void {\n    const incoming = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;\n    if (incoming.length === 0) {\n      return;\n    }\n    this.buffer = this.buffer.length === 0 ? incoming : Buffer.concat([this.buffer, incoming]);\n    this.drainCompleteLines();\n    if (this.buffer.length > CHILD_BUFFER_MAX_BYTES) {\n      this.flush();\n    }\n  }\n\n  /** Emit any buffered partial line (with prefix + newline), then reset. */\n  flush(): void {\n    if (this.buffer.length > 0) {\n      this.write(`${this.prefix}${this.buffer.toString('utf8')}\\n`);\n      this.buffer = Buffer.alloc(0);\n    }\n  }\n\n  private drainCompleteLines(): void {\n    let newlineAt = this.buffer.indexOf(0x0a);\n    while (newlineAt !== -1) {\n      const line = this.buffer.subarray(0, newlineAt).toString('utf8');\n      this.buffer = this.buffer.subarray(newlineAt + 1);\n      this.write(`${this.prefix}${line}\\n`);\n      newlineAt = this.buffer.indexOf(0x0a);\n    }\n  }\n}\n\n// ── Exit-code arbitration ──────────────────────────────────────────────────\n\n/** POSIX-conventional exit codes for signal-terminated children. */\nconst SIGNAL_EXIT_CODES: Readonly<Partial<Record<NodeJS.Signals, number>>> = {\n  SIGHUP: 129,\n  SIGINT: 130,\n  SIGQUIT: 131,\n  SIGKILL: 137,\n  SIGTERM: 143,\n};\n\n/** Map a child's (code, signal) exit pair to a single numeric exit code. */\nexport function exitCodeFrom(\n  code: number | null,\n  signal: NodeJS.Signals | null,\n): number {\n  if (code !== null) {\n    return code;\n  }\n  if (signal !== null) {\n    return SIGNAL_EXIT_CODES[signal] ?? 1;\n  }\n  return 1;\n}\n\n/**\n * Deterministic exit-code arbiter: the FIRST observed terminating cause\n * (a child exit, or a signal delivered to the orchestrator) decides the\n * final code. Exits observed after shutdown started are the expected\n * result of our own SIGTERM and never change the outcome.\n */\nexport class ExitArbiter {\n  private decidingChildCode: number | undefined;\n  private signalCode: number | undefined;\n\n  get shutdownInitiated(): boolean {\n    return this.decidingChildCode !== undefined || this.signalCode !== undefined;\n  }\n\n  observeChildExit(code: number | null, signal: NodeJS.Signals | null): void {\n    if (this.shutdownInitiated) {\n      return;\n    }\n    this.decidingChildCode = exitCodeFrom(code, signal);\n  }\n\n  observeSignal(sig: 'SIGINT' | 'SIGTERM'): void {\n    if (this.shutdownInitiated) {\n      return;\n    }\n    this.signalCode = sig === 'SIGINT' ? 130 : 143;\n  }\n\n  finalCode(): number {\n    return this.signalCode ?? this.decidingChildCode ?? 0;\n  }\n}\n\n// ── Child spawning ─────────────────────────────────────────────────────────\n\n/** The exact spawn options the orchestrator uses for both children. */\nexport interface SpawnChildOptions {\n  cwd: string;\n  env: NodeJS.ProcessEnv;\n  stdio: ['ignore', 'pipe', 'pipe'];\n  shell: false;\n}\n\n/** Structural subset of ChildProcess the orchestrator relies on. */\nexport interface ChildLike {\n  readonly pid?: number | undefined;\n  readonly stdout: NodeJS.ReadableStream | null;\n  readonly stderr: NodeJS.ReadableStream | null;\n  kill(signal?: NodeJS.Signals): boolean;\n  once(\n    event: 'exit',\n    listener: (code: number | null, signal: NodeJS.Signals | null) => void,\n  ): unknown;\n  once(event: 'error', listener: (err: Error) => void): unknown;\n}\n\nexport type SpawnFn = (\n  command: string,\n  args: readonly string[],\n  options: SpawnChildOptions,\n) => ChildLike;\n\nconst defaultSpawn: SpawnFn = (command, args, options) =>\n  spawn(command, [...args], {\n    cwd: options.cwd,\n    env: options.env,\n    stdio: options.stdio,\n    shell: options.shell,\n  });\n\n/** Minimal process-signal surface, injectable so tests never send real signals. */\nexport interface SignalSource {\n  on(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;\n  removeListener(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;\n}\n\n/** How the listener child is invoked: always the current node executable. */\nexport interface ListenInvocation {\n  command: string;\n  args: string[];\n}\n\n/**\n * Build the listener child's invocation. By default the listener runs as\n * a sub-command of this same binary. The RATIO_DEV_LISTEN_BIN environment\n * variable substitutes a different script for the listener (a test seam;\n * unset in normal use, in which case the default binary path is used).\n */\nexport function buildListenInvocation(\n  env: NodeJS.ProcessEnv,\n  devServerPort: number | undefined,\n  argv1: string | undefined,\n): ListenInvocation {\n  const override = env.RATIO_DEV_LISTEN_BIN;\n  const listenBin = override ?? argv1;\n  if (listenBin === undefined || listenBin === '') {\n    throw new OrchestratorSpawnError(\n      'Could not locate the CLI binary to start the webhook listener.',\n      'Re-install the CLI, or invoke it through its bin entry point.',\n    );\n  }\n  const listenArgs = override\n    ? []\n    : [\n        'dev',\n        'listen',\n        '--forward-to',\n        `localhost:${devServerPort ?? DEFAULT_FORWARD_PORT}/webhooks`,\n      ];\n  return { command: process.execPath, args: [listenBin, ...listenArgs] };\n}\n\n// ── Orchestration ──────────────────────────────────────────────────────────\n\nexport interface OrchestratorIo {\n  writeOut(chunk: string): void;\n  writeErr(chunk: string): void;\n}\n\nexport interface OrchestrateOptions {\n  /** Tokenized dev command; index 0 is the executable. */\n  appArgv: string[];\n  /** Optional port hint exposed to the app child as PORT. */\n  devServerPort: number | undefined;\n  cwd: string;\n  env: NodeJS.ProcessEnv;\n  preview: PreviewController;\n  verbose: boolean;\n  io: OrchestratorIo;\n  signalSource: SignalSource;\n  /** Immediate process exit for the second-interrupt fast path. */\n  hardExit: (code: number) => void;\n  /** Test seam: spawner for the app child. */\n  spawnApp?: SpawnFn;\n  /** Test seam: spawner for the listener child. */\n  spawnListen?: SpawnFn;\n  /** Test seam: shrink the SIGTERM → SIGKILL grace window. */\n  drainMs?: number;\n  /** Test seam: stand-in for the CLI's own script path. */\n  argv1?: string;\n}\n\nfunction describeCause(cause: unknown): string {\n  return cause instanceof Error ? cause.message : String(cause);\n}\n\n/**\n * Run both children to completion and resolve the final exit code.\n * Rejects with a typed error when a child cannot be spawned (exit 10) or\n * when an otherwise-clean shutdown needed a SIGKILL escalation (exit 11).\n */\nexport async function orchestrate(options: OrchestrateOptions): Promise<number> {\n  const { io } = options;\n  const drainMs = options.drainMs ?? DRAIN_MS;\n  const spawnApp = options.spawnApp ?? defaultSpawn;\n  const spawnListen = options.spawnListen ?? defaultSpawn;\n  const trace = (line: string): void => {\n    if (options.verbose) {\n      io.writeErr(`[verbose] ${line}\\n`);\n    }\n  };\n\n  const appCommand = options.appArgv[0];\n  if (appCommand === undefined || appCommand === '') {\n    throw new ValidationError('devCommand is empty.', DEV_COMMAND_HINT);\n  }\n\n  // Child A: the app's own dev command. PORT is set only when the\n  // manifest declares a devServerPort.\n  const appEnv: NodeJS.ProcessEnv = {\n    ...options.env,\n    ...(options.devServerPort !== undefined\n      ? { PORT: String(options.devServerPort) }\n      : {}),\n    RATIO_ORCHESTRATED: '1',\n  };\n  let app: ChildLike;\n  try {\n    app = spawnApp(appCommand, options.appArgv.slice(1), {\n      cwd: options.cwd,\n      env: appEnv,\n      stdio: ['ignore', 'pipe', 'pipe'],\n      shell: false,\n    });\n  } catch (cause) {\n    throw new OrchestratorSpawnError(\n      `Could not start the dev command (${appCommand}): ${describeCause(cause)}`,\n    );\n  }\n  trace(`spawn app: ${appCommand} (${app.pid ?? '-'})`);\n\n  // Child B: the webhook listener, run as a sub-command of this binary.\n  const invocation = buildListenInvocation(\n    options.env,\n    options.devServerPort,\n    options.argv1 ?? process.argv[1],\n  );\n  const listenEnv: NodeJS.ProcessEnv = { ...options.env, RATIO_ORCHESTRATED: '1' };\n  let listen: ChildLike;\n  try {\n    listen = spawnListen(invocation.command, invocation.args, {\n      cwd: options.cwd,\n      env: listenEnv,\n      stdio: ['ignore', 'pipe', 'pipe'],\n      shell: false,\n    });\n  } catch (cause) {\n    app.kill('SIGTERM');\n    throw new OrchestratorSpawnError(\n      `Could not start the webhook listener: ${describeCause(cause)}`,\n      'The bundled webhook listener could not be started; re-install the CLI if this persists.',\n    );\n  }\n  trace(`spawn listen: (${listen.pid ?? '-'})`);\n\n  // Log multiplexer: per-stream line buffers, one prefix per child.\n  const appOut = new LinePrefixer('[app] ', (chunk) => io.writeOut(chunk));\n  const appErrOut = new LinePrefixer('[app] ', (chunk) => io.writeOut(chunk));\n  const listenOut = new LinePrefixer('[listen] ', (chunk) => io.writeOut(chunk));\n  const listenErrOut = new LinePrefixer('[listen] ', (chunk) => io.writeOut(chunk));\n  const pipe = (stream: NodeJS.ReadableStream | null, prefixer: LinePrefixer): void => {\n    if (stream !== null) {\n      stream.on('data', (chunk: Buffer | string) => prefixer.push(chunk));\n    }\n  };\n  pipe(app.stdout, appOut);\n  pipe(app.stderr, appErrOut);\n  pipe(listen.stdout, listenOut);\n  pipe(listen.stderr, listenErrOut);\n\n  const arbiter = new ExitArbiter();\n  let appExited = false;\n  let listenExited = false;\n  let spawnFailure: OrchestratorSpawnError | undefined;\n  let drainEscalated = false;\n  let drainTimer: NodeJS.Timeout | undefined;\n  let drainStartedAt = 0;\n  let firstSignalAt = 0;\n\n  return await new Promise<number>((resolve, reject) => {\n    let settled = false;\n\n    const cleanup = (): void => {\n      options.signalSource.removeListener('SIGINT', onSigint);\n      options.signalSource.removeListener('SIGTERM', onSigterm);\n      if (drainTimer !== undefined) {\n        clearTimeout(drainTimer);\n        drainTimer = undefined;\n      }\n      appOut.flush();\n      appErrOut.flush();\n      listenOut.flush();\n      listenErrOut.flush();\n    };\n\n    const settle = (code: number): void => {\n      if (!settled) {\n        settled = true;\n        cleanup();\n        resolve(code);\n      }\n    };\n    const fail = (err: unknown): void => {\n      if (!settled) {\n        settled = true;\n        cleanup();\n        reject(err instanceof Error ? err : new Error(String(err)));\n      }\n    };\n\n    const startDrain = (): void => {\n      if (drainTimer !== undefined) {\n        return;\n      }\n      drainStartedAt = Date.now();\n      drainTimer = setTimeout(() => {\n        if (!appExited) {\n          app.kill('SIGKILL');\n          drainEscalated = true;\n        }\n        if (!listenExited) {\n          listen.kill('SIGKILL');\n          drainEscalated = true;\n        }\n      }, drainMs);\n    };\n\n    const finishIfDone = (): void => {\n      if (!appExited || !listenExited) {\n        return;\n      }\n      if (drainStartedAt > 0) {\n        trace(`drain elapsed: ${Date.now() - drainStartedAt}ms`);\n      }\n      const code = arbiter.finalCode();\n      void options.preview.onShutdown().then(\n        () => {\n          if (spawnFailure !== undefined) {\n            fail(spawnFailure);\n            return;\n          }\n          if (drainEscalated && code === 0) {\n            fail(\n              new OrchestratorDrainTimeoutError(\n                'A child process had to be forcibly terminated during shutdown.',\n              ),\n            );\n            return;\n          }\n          settle(code);\n        },\n        (err: unknown) => fail(err),\n      );\n    };\n\n    const onAppExit = (code: number | null, signal: NodeJS.Signals | null): void => {\n      appExited = true;\n      appOut.flush();\n      appErrOut.flush();\n      trace(`app exited: code=${code} signal=${signal}`);\n      const alreadyShuttingDown = arbiter.shutdownInitiated;\n      arbiter.observeChildExit(code, signal);\n      if (!alreadyShuttingDown && !listenExited) {\n        listen.kill('SIGTERM');\n        startDrain();\n      }\n      finishIfDone();\n    };\n\n    const onListenExit = (code: number | null, signal: NodeJS.Signals | null): void => {\n      listenExited = true;\n      listenOut.flush();\n      listenErrOut.flush();\n      trace(`listen exited: code=${code} signal=${signal}`);\n      const alreadyShuttingDown = arbiter.shutdownInitiated;\n      arbiter.observeChildExit(code, signal);\n      if (!alreadyShuttingDown && !appExited) {\n        app.kill('SIGTERM');\n        startDrain();\n      }\n      finishIfDone();\n    };\n\n    const onAppError = (err: Error): void => {\n      appExited = true;\n      if (spawnFailure === undefined) {\n        spawnFailure = new OrchestratorSpawnError(\n          `Could not start the dev command (${appCommand}): ${err.message}`,\n        );\n      }\n      arbiter.observeChildExit(1, null);\n      if (!listenExited) {\n        listen.kill('SIGTERM');\n        startDrain();\n      }\n      finishIfDone();\n    };\n\n    const onListenError = (err: Error): void => {\n      listenExited = true;\n      if (spawnFailure === undefined) {\n        spawnFailure = new OrchestratorSpawnError(\n          `Could not start the webhook listener: ${err.message}`,\n          'The bundled webhook listener could not be started; re-install the CLI if this persists.',\n        );\n      }\n      arbiter.observeChildExit(1, null);\n      if (!appExited) {\n        app.kill('SIGTERM');\n        startDrain();\n      }\n      finishIfDone();\n    };\n\n    const onSignal = (sig: 'SIGINT' | 'SIGTERM'): void => {\n      trace(`signal received: ${sig}`);\n      if (arbiter.shutdownInitiated) {\n        if (firstSignalAt === 0) {\n          // Shutdown was child-initiated; arm the force-exit window so a\n          // follow-up interrupt can still cut the drain short.\n          firstSignalAt = Date.now();\n          return;\n        }\n        if (Date.now() - firstSignalAt <= SIGNAL_FORCE_EXIT_WINDOW_MS) {\n          options.hardExit(130);\n        }\n        return;\n      }\n      firstSignalAt = Date.now();\n      arbiter.observeSignal(sig);\n      io.writeErr('shutting down: stopping the dev command and the webhook listener\\n');\n      if (!appExited) {\n        app.kill('SIGTERM');\n      }\n      if (!listenExited) {\n        listen.kill('SIGTERM');\n      }\n      startDrain();\n    };\n    const onSigint = (): void => onSignal('SIGINT');\n    const onSigterm = (): void => onSignal('SIGTERM');\n    options.signalSource.on('SIGINT', onSigint);\n    options.signalSource.on('SIGTERM', onSigterm);\n\n    app.once('exit', onAppExit);\n    app.once('error', onAppError);\n    listen.once('exit', onListenExit);\n    listen.once('error', onListenError);\n\n    // Both children are up: notify the preview seam (a no-op in v1).\n    trace(`preview: onDevServerReady(${options.devServerPort ?? 0})`);\n    void options.preview\n      .onDevServerReady(options.devServerPort ?? 0)\n      .catch((err: unknown) => fail(err));\n  });\n}\n","/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n","/**\n * Read-only view over the app manifest (ratio.config.jsonc).\n *\n * The file is treated as an opaque UTF-8 string: no JSON/JSONC parser is\n * involved, so comments and unknown keys are irrelevant to the read and\n * survive untouched on disk. Each field is extracted with one targeted\n * regex, mirroring the write-side idiom in write-client-id.ts. This module\n * never writes the file.\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { ValidationError } from '../errors.js';\nimport { MANIFEST_FILE_NAME } from './write-client-id.js';\n\n/** Read-only extraction regex for the dev command line. */\nconst DEV_COMMAND_ROW = /^\\s*\"devCommand\"\\s*:\\s*\"([^\"]*)\"/m;\n\n/** Read-only extraction regex for the dev-server port (integer, unquoted). */\nconst DEV_SERVER_PORT_ROW = /^\\s*\"devServerPort\"\\s*:\\s*(\\d+)/m;\n\n/** Key-presence probe: distinguishes \"absent\" from \"present but malformed\". */\nconst DEV_SERVER_PORT_KEY = /^\\s*\"devServerPort\"\\s*:/m;\n\n/** Read-only extraction regex for the appName echo. Never used to write. */\nconst APP_NAME_ROW = /^\\s*\"appName\"\\s*:\\s*\"([^\"]*)\"/m;\n\n/** Read-only extraction regex for the clientId echo. Never used to write. */\nconst CLIENT_ID_READ_ROW = /^\\s*\"clientId\"\\s*:\\s*\"([^\"]*)\"/m;\n\n/** Hint shown whenever the dev command entry is missing or unusable. */\nexport const DEV_COMMAND_HINT =\n  'Add a \"devCommand\" entry to ratio.config.jsonc (e.g. \"npm run dev\") and re-run.';\n\nexport interface ManifestView {\n  /** Absolute path to the manifest file that was read. */\n  path: string;\n  /** The command used to start the app's own dev server. Always present. */\n  devCommand: string;\n  /** Optional local dev-server port (1-65535); undefined when absent. */\n  devServerPort: number | undefined;\n  /** Parsed from the manifest's appName row, when present. */\n  appName: string | undefined;\n  /** Parsed from the manifest's clientId row, when present. */\n  clientId: string | undefined;\n}\n\n/**\n * Locate `ratio.config.jsonc` under `cwd` and extract the fields the dev\n * orchestrator needs. Fails fast with a typed error when the file is\n * missing, when `devCommand` is absent/empty, or when `devServerPort` is\n * present but not an integer in 1-65535.\n */\nexport function readManifest(cwd: string): ManifestView {\n  const filePath = path.join(cwd, MANIFEST_FILE_NAME);\n\n  let content: string;\n  try {\n    content = fs.readFileSync(filePath, 'utf8');\n  } catch {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n    );\n  }\n\n  const devCommand = DEV_COMMAND_ROW.exec(content)?.[1];\n  if (devCommand === undefined || devCommand.trim() === '') {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} has no usable \"devCommand\" entry.`,\n      DEV_COMMAND_HINT,\n    );\n  }\n\n  let devServerPort: number | undefined;\n  if (DEV_SERVER_PORT_KEY.test(content)) {\n    const rawPort = DEV_SERVER_PORT_ROW.exec(content)?.[1];\n    const port = rawPort === undefined ? Number.NaN : Number.parseInt(rawPort, 10);\n    if (!Number.isInteger(port) || port < 1 || port > 65535) {\n      throw new ValidationError(\n        `${MANIFEST_FILE_NAME} has an invalid \"devServerPort\" value.`,\n        '\"devServerPort\" must be an unquoted integer between 1 and 65535 (e.g. \"devServerPort\": 3001).',\n      );\n    }\n    devServerPort = port;\n  }\n\n  return {\n    path: filePath,\n    devCommand,\n    devServerPort,\n    appName: APP_NAME_ROW.exec(content)?.[1],\n    clientId: CLIENT_ID_READ_ROW.exec(content)?.[1],\n  };\n}\n","/**\n * Atomically rewrite the top-level \"clientId\" value in a ratio.config.jsonc\n * file. Preserves every comment, whitespace token, and unknown key.\n *\n * The file is treated as an opaque UTF-8 string: no JSON/JSONC parser is\n * involved, so comments survive verbatim. Exactly one targeted regex is\n * applied to the `\"clientId\": \"<value>\"` line; everything else is copied\n * byte-for-byte.\n *\n * Throws ValidationError if the file is not shaped like a canonical\n * ratio.config.jsonc (no top-level \"clientId\" key on its own line).\n */\n\nimport crypto from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { ValidationError } from '../errors.js';\n\n/** Manifest file name expected in the app repo root. */\nexport const MANIFEST_FILE_NAME = 'ratio.config.jsonc';\n\n/** Targeted single-key rewrite regex for the clientId value. */\nconst CLIENT_ID_ROW = /^(\\s*\"clientId\"\\s*:\\s*\")([^\"]*)(\"\\s*,?)/m;\n\n/** Read-only extraction regex for the appName echo. Never used to write. */\nconst APP_NAME_ROW = /^\\s*\"appName\"\\s*:\\s*\"([^\"]*)\"/m;\n\nexport interface WriteClientIdResult {\n  /** false when the file already had the same clientId. */\n  written: boolean;\n  /** Absolute path to the manifest file. */\n  path: string;\n  /** Parsed from the manifest's appName row, when present. */\n  appName?: string;\n  /** The value that was replaced, when it was non-empty and different. */\n  previousClientId?: string;\n}\n\n/**\n * Locate `ratio.config.jsonc` under `cwd`, rewrite ONLY the top-level\n * clientId value, and persist via atomic tmp+rename with 0600 discipline\n * (mirrors the credential store's write contract). Same-value re-runs are\n * a no-op (`written: false`, file untouched).\n */\nexport async function writeClientId(\n  cwd: string,\n  clientId: string,\n): Promise<WriteClientIdResult> {\n  const filePath = path.join(cwd, MANIFEST_FILE_NAME);\n\n  let content: string;\n  try {\n    content = fs.readFileSync(filePath, 'utf8');\n  } catch {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n    );\n  }\n\n  const appNameMatch = APP_NAME_ROW.exec(content);\n  const appName = appNameMatch?.[1];\n\n  const rowMatch = CLIENT_ID_ROW.exec(content);\n  if (rowMatch === null) {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} has no top-level \"clientId\" entry.`,\n      'Restore the \"clientId\" line from the app template, then re-run.',\n    );\n  }\n\n  const existing = rowMatch[2] ?? '';\n\n  const base: WriteClientIdResult = {\n    written: false,\n    path: filePath,\n    ...(appName !== undefined ? { appName } : {}),\n  };\n\n  if (existing === clientId) {\n    return base;\n  }\n\n  // Function replacer: the new value is inserted verbatim, immune to `$`\n  // pattern expansion in String.replace replacement strings.\n  const updated = content.replace(\n    CLIENT_ID_ROW,\n    (_row, open: string, _old: string, close: string) =>\n      `${open}${clientId}${close}`,\n  );\n\n  const tmpPath = `${filePath}.${process.pid}.${crypto\n    .randomBytes(8)\n    .toString('hex')}.tmp`;\n  try {\n    // mode at open time closes the create-then-chmod race window.\n    fs.writeFileSync(tmpPath, updated, { mode: 0o600 });\n    fs.renameSync(tmpPath, filePath);\n  } catch (err) {\n    try {\n      fs.unlinkSync(tmpPath);\n    } catch {\n      // Best-effort cleanup: the tmp file may never have been created.\n    }\n    throw err;\n  }\n  if (process.platform !== 'win32') {\n    // Belt-and-braces: rename may preserve a prior destination mode.\n    fs.chmodSync(filePath, 0o600);\n  }\n\n  return {\n    ...base,\n    written: true,\n    ...(existing !== '' ? { previousClientId: existing } : {}),\n  };\n}\n"],"mappings":";AAaA,SAAS,aAAa;;;ACHf,IAAM,gBAAN,cAA4B,MAAM;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAMT;AACD,UAAM,KAAK,OAAO;AAClB,SAAK,OAAO,WAAW;AACvB,SAAK,OAAO,KAAK;AACjB,SAAK,WAAW,KAAK;AACrB,QAAI,KAAK,SAAS,OAAW,MAAK,OAAO,KAAK;AAC9C,QAAI,KAAK,YAAY,OAAW,MAAK,UAAU,KAAK;AAAA,EACtD;AACF;AAgEO,IAAM,kBAAN,cAA8B,cAAc;AAAA,EACjD,YAAY,SAAiB,MAAe;AAC1C,UAAM,OAA2E;AAAA,MAC/E,MAAM;AAAA,MACN,UAAU;AAAA,MACV;AAAA,IACF;AACA,QAAI,SAAS,OAAW,MAAK,OAAO;AACpC,UAAM,IAAI;AAAA,EACZ;AACF;AAWO,IAAM,yBAAN,cAAqC,cAAc;AAAA,EACxD,YACE,SACA,OAAe,wHACf;AACA,UAAM,EAAE,MAAM,sBAAsB,UAAU,IAAI,SAAS,KAAK,CAAC;AAAA,EACnE;AACF;AAEO,IAAM,gCAAN,cAA4C,cAAc;AAAA,EAC/D,YACE,SACA,OAAe,6FACf;AACA,UAAM,EAAE,MAAM,sBAAsB,UAAU,IAAI,SAAS,KAAK,CAAC;AAAA,EACnE;AACF;;;ACzHA,OAAOA,SAAQ;AACf,OAAOC,WAAU;;;ACEjB,OAAO,YAAY;AACnB,OAAO,QAAQ;AACf,OAAO,UAAU;;;ADgBV,IAAM,mBACX;;;AFTK,IAAM,WAAW;AAQjB,IAAM,iBAAiB;AAGvB,IAAM,8BAA8B;AAGpC,IAAM,yBAAyB,KAAK;AAGpC,IAAM,4BACX;AAGK,IAAM,uBAAuB;AAW7B,SAAS,mBAAmB,KAAuB;AACxD,QAAM,SAAmB,CAAC;AAC1B,MAAI,UAAU;AACd,MAAI;AACJ,MAAI,WAAW;AAEf,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK,GAAG;AACtC,UAAM,KAAK,IAAI,OAAO,CAAC;AACvB,QAAI,UAAU,QAAW;AACvB,UAAI,OAAO,OAAO;AAChB,gBAAQ;AAAA,MACV,OAAO;AACL,mBAAW;AAAA,MACb;AACA;AAAA,IACF;AACA,QAAI,OAAO,OAAO,OAAO,KAAK;AAC5B,cAAQ;AACR,iBAAW;AACX;AAAA,IACF;AACA,QAAI,OAAO,OAAO,OAAO,OAAQ,OAAO,QAAQ,OAAO,MAAM;AAC3D,UAAI,UAAU;AACZ,eAAO,KAAK,OAAO;AACnB,kBAAU;AACV,mBAAW;AAAA,MACb;AACA;AAAA,IACF;AACA,QAAI,OAAO,OAAO,OAAO,OAAO,OAAO,OAAO,OAAO,OAAO,OAAO,OAAO,OAAO,KAAK;AACpF,YAAM,IAAI;AAAA,QACR,sDAAsD,EAAE;AAAA,QACxD;AAAA,MACF;AAAA,IACF;AACA,QAAI,OAAO,OAAO,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK;AAC3C,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AACA,eAAW;AACX,eAAW;AAAA,EACb;AAEA,MAAI,UAAU,QAAW;AACvB,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,MAAI,UAAU;AACZ,WAAO,KAAK,OAAO;AAAA,EACrB;AACA,MAAI,OAAO,WAAW,KAAK,OAAO,CAAC,MAAM,IAAI;AAC3C,UAAM,IAAI,gBAAgB,wBAAwB,gBAAgB;AAAA,EACpE;AACA,SAAO;AACT;AAUO,IAAM,eAAN,MAAmB;AAAA,EAGxB,YACmB,QACA,OACjB;AAFiB;AACA;AAAA,EAChB;AAAA,EAFgB;AAAA,EACA;AAAA,EAJX,SAAiB,OAAO,MAAM,CAAC;AAAA,EAOvC,KAAK,OAA8B;AACjC,UAAM,WAAW,OAAO,UAAU,WAAW,OAAO,KAAK,OAAO,MAAM,IAAI;AAC1E,QAAI,SAAS,WAAW,GAAG;AACzB;AAAA,IACF;AACA,SAAK,SAAS,KAAK,OAAO,WAAW,IAAI,WAAW,OAAO,OAAO,CAAC,KAAK,QAAQ,QAAQ,CAAC;AACzF,SAAK,mBAAmB;AACxB,QAAI,KAAK,OAAO,SAAS,wBAAwB;AAC/C,WAAK,MAAM;AAAA,IACb;AAAA,EACF;AAAA;AAAA,EAGA,QAAc;AACZ,QAAI,KAAK,OAAO,SAAS,GAAG;AAC1B,WAAK,MAAM,GAAG,KAAK,MAAM,GAAG,KAAK,OAAO,SAAS,MAAM,CAAC;AAAA,CAAI;AAC5D,WAAK,SAAS,OAAO,MAAM,CAAC;AAAA,IAC9B;AAAA,EACF;AAAA,EAEQ,qBAA2B;AACjC,QAAI,YAAY,KAAK,OAAO,QAAQ,EAAI;AACxC,WAAO,cAAc,IAAI;AACvB,YAAM,OAAO,KAAK,OAAO,SAAS,GAAG,SAAS,EAAE,SAAS,MAAM;AAC/D,WAAK,SAAS,KAAK,OAAO,SAAS,YAAY,CAAC;AAChD,WAAK,MAAM,GAAG,KAAK,MAAM,GAAG,IAAI;AAAA,CAAI;AACpC,kBAAY,KAAK,OAAO,QAAQ,EAAI;AAAA,IACtC;AAAA,EACF;AACF;AAKA,IAAM,oBAAuE;AAAA,EAC3E,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,SAAS;AAAA,EACT,SAAS;AACX;AAGO,SAAS,aACd,MACA,QACQ;AACR,MAAI,SAAS,MAAM;AACjB,WAAO;AAAA,EACT;AACA,MAAI,WAAW,MAAM;AACnB,WAAO,kBAAkB,MAAM,KAAK;AAAA,EACtC;AACA,SAAO;AACT;AAQO,IAAM,cAAN,MAAkB;AAAA,EACf;AAAA,EACA;AAAA,EAER,IAAI,oBAA6B;AAC/B,WAAO,KAAK,sBAAsB,UAAa,KAAK,eAAe;AAAA,EACrE;AAAA,EAEA,iBAAiB,MAAqB,QAAqC;AACzE,QAAI,KAAK,mBAAmB;AAC1B;AAAA,IACF;AACA,SAAK,oBAAoB,aAAa,MAAM,MAAM;AAAA,EACpD;AAAA,EAEA,cAAc,KAAiC;AAC7C,QAAI,KAAK,mBAAmB;AAC1B;AAAA,IACF;AACA,SAAK,aAAa,QAAQ,WAAW,MAAM;AAAA,EAC7C;AAAA,EAEA,YAAoB;AAClB,WAAO,KAAK,cAAc,KAAK,qBAAqB;AAAA,EACtD;AACF;AA+BA,IAAM,eAAwB,CAAC,SAAS,MAAM,YAC5C,MAAM,SAAS,CAAC,GAAG,IAAI,GAAG;AAAA,EACxB,KAAK,QAAQ;AAAA,EACb,KAAK,QAAQ;AAAA,EACb,OAAO,QAAQ;AAAA,EACf,OAAO,QAAQ;AACjB,CAAC;AAoBI,SAAS,sBACd,KACA,eACA,OACkB;AAClB,QAAM,WAAW,IAAI;AACrB,QAAM,YAAY,YAAY;AAC9B,MAAI,cAAc,UAAa,cAAc,IAAI;AAC/C,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,QAAM,aAAa,WACf,CAAC,IACD;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA,aAAa,iBAAiB,oBAAoB;AAAA,EACpD;AACJ,SAAO,EAAE,SAAS,QAAQ,UAAU,MAAM,CAAC,WAAW,GAAG,UAAU,EAAE;AACvE;AAgCA,SAAS,cAAc,OAAwB;AAC7C,SAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D;AAOA,eAAsB,YAAY,SAA8C;AAC9E,QAAM,EAAE,GAAG,IAAI;AACf,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,QAAQ,CAAC,SAAuB;AACpC,QAAI,QAAQ,SAAS;AACnB,SAAG,SAAS,aAAa,IAAI;AAAA,CAAI;AAAA,IACnC;AAAA,EACF;AAEA,QAAM,aAAa,QAAQ,QAAQ,CAAC;AACpC,MAAI,eAAe,UAAa,eAAe,IAAI;AACjD,UAAM,IAAI,gBAAgB,wBAAwB,gBAAgB;AAAA,EACpE;AAIA,QAAM,SAA4B;AAAA,IAChC,GAAG,QAAQ;AAAA,IACX,GAAI,QAAQ,kBAAkB,SAC1B,EAAE,MAAM,OAAO,QAAQ,aAAa,EAAE,IACtC,CAAC;AAAA,IACL,oBAAoB;AAAA,EACtB;AACA,MAAI;AACJ,MAAI;AACF,UAAM,SAAS,YAAY,QAAQ,QAAQ,MAAM,CAAC,GAAG;AAAA,MACnD,KAAK,QAAQ;AAAA,MACb,KAAK;AAAA,MACL,OAAO,CAAC,UAAU,QAAQ,MAAM;AAAA,MAChC,OAAO;AAAA,IACT,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,oCAAoC,UAAU,MAAM,cAAc,KAAK,CAAC;AAAA,IAC1E;AAAA,EACF;AACA,QAAM,cAAc,UAAU,KAAK,IAAI,OAAO,GAAG,GAAG;AAGpD,QAAM,aAAa;AAAA,IACjB,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,QAAQ,SAAS,QAAQ,KAAK,CAAC;AAAA,EACjC;AACA,QAAM,YAA+B,EAAE,GAAG,QAAQ,KAAK,oBAAoB,IAAI;AAC/E,MAAI;AACJ,MAAI;AACF,aAAS,YAAY,WAAW,SAAS,WAAW,MAAM;AAAA,MACxD,KAAK,QAAQ;AAAA,MACb,KAAK;AAAA,MACL,OAAO,CAAC,UAAU,QAAQ,MAAM;AAAA,MAChC,OAAO;AAAA,IACT,CAAC;AAAA,EACH,SAAS,OAAO;AACd,QAAI,KAAK,SAAS;AAClB,UAAM,IAAI;AAAA,MACR,yCAAyC,cAAc,KAAK,CAAC;AAAA,MAC7D;AAAA,IACF;AAAA,EACF;AACA,QAAM,kBAAkB,OAAO,OAAO,GAAG,GAAG;AAG5C,QAAM,SAAS,IAAI,aAAa,UAAU,CAAC,UAAU,GAAG,SAAS,KAAK,CAAC;AACvE,QAAM,YAAY,IAAI,aAAa,UAAU,CAAC,UAAU,GAAG,SAAS,KAAK,CAAC;AAC1E,QAAM,YAAY,IAAI,aAAa,aAAa,CAAC,UAAU,GAAG,SAAS,KAAK,CAAC;AAC7E,QAAM,eAAe,IAAI,aAAa,aAAa,CAAC,UAAU,GAAG,SAAS,KAAK,CAAC;AAChF,QAAM,OAAO,CAAC,QAAsC,aAAiC;AACnF,QAAI,WAAW,MAAM;AACnB,aAAO,GAAG,QAAQ,CAAC,UAA2B,SAAS,KAAK,KAAK,CAAC;AAAA,IACpE;AAAA,EACF;AACA,OAAK,IAAI,QAAQ,MAAM;AACvB,OAAK,IAAI,QAAQ,SAAS;AAC1B,OAAK,OAAO,QAAQ,SAAS;AAC7B,OAAK,OAAO,QAAQ,YAAY;AAEhC,QAAM,UAAU,IAAI,YAAY;AAChC,MAAI,YAAY;AAChB,MAAI,eAAe;AACnB,MAAI;AACJ,MAAI,iBAAiB;AACrB,MAAI;AACJ,MAAI,iBAAiB;AACrB,MAAI,gBAAgB;AAEpB,SAAO,MAAM,IAAI,QAAgB,CAAC,SAAS,WAAW;AACpD,QAAI,UAAU;AAEd,UAAM,UAAU,MAAY;AAC1B,cAAQ,aAAa,eAAe,UAAU,QAAQ;AACtD,cAAQ,aAAa,eAAe,WAAW,SAAS;AACxD,UAAI,eAAe,QAAW;AAC5B,qBAAa,UAAU;AACvB,qBAAa;AAAA,MACf;AACA,aAAO,MAAM;AACb,gBAAU,MAAM;AAChB,gBAAU,MAAM;AAChB,mBAAa,MAAM;AAAA,IACrB;AAEA,UAAM,SAAS,CAAC,SAAuB;AACrC,UAAI,CAAC,SAAS;AACZ,kBAAU;AACV,gBAAQ;AACR,gBAAQ,IAAI;AAAA,MACd;AAAA,IACF;AACA,UAAM,OAAO,CAAC,QAAuB;AACnC,UAAI,CAAC,SAAS;AACZ,kBAAU;AACV,gBAAQ;AACR,eAAO,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,MAC5D;AAAA,IACF;AAEA,UAAM,aAAa,MAAY;AAC7B,UAAI,eAAe,QAAW;AAC5B;AAAA,MACF;AACA,uBAAiB,KAAK,IAAI;AAC1B,mBAAa,WAAW,MAAM;AAC5B,YAAI,CAAC,WAAW;AACd,cAAI,KAAK,SAAS;AAClB,2BAAiB;AAAA,QACnB;AACA,YAAI,CAAC,cAAc;AACjB,iBAAO,KAAK,SAAS;AACrB,2BAAiB;AAAA,QACnB;AAAA,MACF,GAAG,OAAO;AAAA,IACZ;AAEA,UAAM,eAAe,MAAY;AAC/B,UAAI,CAAC,aAAa,CAAC,cAAc;AAC/B;AAAA,MACF;AACA,UAAI,iBAAiB,GAAG;AACtB,cAAM,kBAAkB,KAAK,IAAI,IAAI,cAAc,IAAI;AAAA,MACzD;AACA,YAAM,OAAO,QAAQ,UAAU;AAC/B,WAAK,QAAQ,QAAQ,WAAW,EAAE;AAAA,QAChC,MAAM;AACJ,cAAI,iBAAiB,QAAW;AAC9B,iBAAK,YAAY;AACjB;AAAA,UACF;AACA,cAAI,kBAAkB,SAAS,GAAG;AAChC;AAAA,cACE,IAAI;AAAA,gBACF;AAAA,cACF;AAAA,YACF;AACA;AAAA,UACF;AACA,iBAAO,IAAI;AAAA,QACb;AAAA,QACA,CAAC,QAAiB,KAAK,GAAG;AAAA,MAC5B;AAAA,IACF;AAEA,UAAM,YAAY,CAAC,MAAqB,WAAwC;AAC9E,kBAAY;AACZ,aAAO,MAAM;AACb,gBAAU,MAAM;AAChB,YAAM,oBAAoB,IAAI,WAAW,MAAM,EAAE;AACjD,YAAM,sBAAsB,QAAQ;AACpC,cAAQ,iBAAiB,MAAM,MAAM;AACrC,UAAI,CAAC,uBAAuB,CAAC,cAAc;AACzC,eAAO,KAAK,SAAS;AACrB,mBAAW;AAAA,MACb;AACA,mBAAa;AAAA,IACf;AAEA,UAAM,eAAe,CAAC,MAAqB,WAAwC;AACjF,qBAAe;AACf,gBAAU,MAAM;AAChB,mBAAa,MAAM;AACnB,YAAM,uBAAuB,IAAI,WAAW,MAAM,EAAE;AACpD,YAAM,sBAAsB,QAAQ;AACpC,cAAQ,iBAAiB,MAAM,MAAM;AACrC,UAAI,CAAC,uBAAuB,CAAC,WAAW;AACtC,YAAI,KAAK,SAAS;AAClB,mBAAW;AAAA,MACb;AACA,mBAAa;AAAA,IACf;AAEA,UAAM,aAAa,CAAC,QAAqB;AACvC,kBAAY;AACZ,UAAI,iBAAiB,QAAW;AAC9B,uBAAe,IAAI;AAAA,UACjB,oCAAoC,UAAU,MAAM,IAAI,OAAO;AAAA,QACjE;AAAA,MACF;AACA,cAAQ,iBAAiB,GAAG,IAAI;AAChC,UAAI,CAAC,cAAc;AACjB,eAAO,KAAK,SAAS;AACrB,mBAAW;AAAA,MACb;AACA,mBAAa;AAAA,IACf;AAEA,UAAM,gBAAgB,CAAC,QAAqB;AAC1C,qBAAe;AACf,UAAI,iBAAiB,QAAW;AAC9B,uBAAe,IAAI;AAAA,UACjB,yCAAyC,IAAI,OAAO;AAAA,UACpD;AAAA,QACF;AAAA,MACF;AACA,cAAQ,iBAAiB,GAAG,IAAI;AAChC,UAAI,CAAC,WAAW;AACd,YAAI,KAAK,SAAS;AAClB,mBAAW;AAAA,MACb;AACA,mBAAa;AAAA,IACf;AAEA,UAAM,WAAW,CAAC,QAAoC;AACpD,YAAM,oBAAoB,GAAG,EAAE;AAC/B,UAAI,QAAQ,mBAAmB;AAC7B,YAAI,kBAAkB,GAAG;AAGvB,0BAAgB,KAAK,IAAI;AACzB;AAAA,QACF;AACA,YAAI,KAAK,IAAI,IAAI,iBAAiB,6BAA6B;AAC7D,kBAAQ,SAAS,GAAG;AAAA,QACtB;AACA;AAAA,MACF;AACA,sBAAgB,KAAK,IAAI;AACzB,cAAQ,cAAc,GAAG;AACzB,SAAG,SAAS,oEAAoE;AAChF,UAAI,CAAC,WAAW;AACd,YAAI,KAAK,SAAS;AAAA,MACpB;AACA,UAAI,CAAC,cAAc;AACjB,eAAO,KAAK,SAAS;AAAA,MACvB;AACA,iBAAW;AAAA,IACb;AACA,UAAM,WAAW,MAAY,SAAS,QAAQ;AAC9C,UAAM,YAAY,MAAY,SAAS,SAAS;AAChD,YAAQ,aAAa,GAAG,UAAU,QAAQ;AAC1C,YAAQ,aAAa,GAAG,WAAW,SAAS;AAE5C,QAAI,KAAK,QAAQ,SAAS;AAC1B,QAAI,KAAK,SAAS,UAAU;AAC5B,WAAO,KAAK,QAAQ,YAAY;AAChC,WAAO,KAAK,SAAS,aAAa;AAGlC,UAAM,6BAA6B,QAAQ,iBAAiB,CAAC,GAAG;AAChE,SAAK,QAAQ,QACV,iBAAiB,QAAQ,iBAAiB,CAAC,EAC3C,MAAM,CAAC,QAAiB,KAAK,GAAG,CAAC;AAAA,EACtC,CAAC;AACH;","names":["fs","path"]}

package/dist/lib/preview/index.d.ts

@@ -0,0 +1,11 @@
+import { PreviewController } from './types.js';
+export { NullPreviewController } from './types.js';
+
+/**
+ * v1: always returns NullPreviewController. The active-preview binding
+ * is introduced by a future change; the orchestrator does not need to
+ * change when that happens.
+ */
+declare function createPreviewController(): PreviewController;
+
+export { PreviewController, createPreviewController };

package/dist/lib/preview/index.js

@@ -0,0 +1,17 @@
+// src/lib/preview/types.ts
+var NullPreviewController = class {
+  async onDevServerReady(_port) {
+  }
+  async onShutdown() {
+  }
+};
+
+// src/lib/preview/index.ts
+function createPreviewController() {
+  return new NullPreviewController();
+}
+export {
+  NullPreviewController,
+  createPreviewController
+};
+//# sourceMappingURL=index.js.map

package/dist/lib/preview/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/preview/types.ts","../../../src/lib/preview/index.ts"],"sourcesContent":["/**\n * Reserved seam for a future active-preview implementation. In v1 the\n * only implementation is a no-op; the interface exists so a future\n * change can bind an active implementation without editing the\n * orchestrator.\n */\nexport interface PreviewController {\n  onDevServerReady(port: number): Promise<void>;\n  onShutdown(): Promise<void>;\n}\n\nexport class NullPreviewController implements PreviewController {\n  async onDevServerReady(_port: number): Promise<void> {}\n  async onShutdown(): Promise<void> {}\n}\n","export { NullPreviewController } from './types.js';\nexport type { PreviewController } from './types.js';\n\n/**\n * v1: always returns NullPreviewController. The active-preview binding\n * is introduced by a future change; the orchestrator does not need to\n * change when that happens.\n */\nexport function createPreviewController(): PreviewController {\n  return new NullPreviewController();\n}\n\nimport { NullPreviewController } from './types.js';\nimport type { PreviewController } from './types.js';\n"],"mappings":";AAWO,IAAM,wBAAN,MAAyD;AAAA,EAC9D,MAAM,iBAAiB,OAA8B;AAAA,EAAC;AAAA,EACtD,MAAM,aAA4B;AAAA,EAAC;AACrC;;;ACNO,SAAS,0BAA6C;AAC3D,SAAO,IAAI,sBAAsB;AACnC;","names":[]}

package/dist/lib/preview/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reserved seam for a future active-preview implementation. In v1 the
+ * only implementation is a no-op; the interface exists so a future
+ * change can bind an active implementation without editing the
+ * orchestrator.
+ */
+interface PreviewController {
+    onDevServerReady(port: number): Promise<void>;
+    onShutdown(): Promise<void>;
+}
+declare class NullPreviewController implements PreviewController {
+    onDevServerReady(_port: number): Promise<void>;
+    onShutdown(): Promise<void>;
+}
+
+export { NullPreviewController, type PreviewController };

package/dist/lib/preview/types.js

@@ -0,0 +1,11 @@
+// src/lib/preview/types.ts
+var NullPreviewController = class {
+  async onDevServerReady(_port) {
+  }
+  async onShutdown() {
+  }
+};
+export {
+  NullPreviewController
+};
+//# sourceMappingURL=types.js.map

package/dist/lib/preview/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/preview/types.ts"],"sourcesContent":["/**\n * Reserved seam for a future active-preview implementation. In v1 the\n * only implementation is a no-op; the interface exists so a future\n * change can bind an active implementation without editing the\n * orchestrator.\n */\nexport interface PreviewController {\n  onDevServerReady(port: number): Promise<void>;\n  onShutdown(): Promise<void>;\n}\n\nexport class NullPreviewController implements PreviewController {\n  async onDevServerReady(_port: number): Promise<void> {}\n  async onShutdown(): Promise<void> {}\n}\n"],"mappings":";AAWO,IAAM,wBAAN,MAAyD;AAAA,EAC9D,MAAM,iBAAiB,OAA8B;AAAA,EAAC;AAAA,EACtD,MAAM,aAA4B;AAAA,EAAC;AACrC;","names":[]}