dev-runner.ts

#!/usr/bin/env node

import * as NodeOS from "node:os";

import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
import * as NodeServices from "@effect/platform-node/NodeServices";
import * as NetService from "@t3tools/shared/Net";
import { resolveGitWorktreePath, resolveWorktreeT3Home } from "@t3tools/shared/devHome";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { resolveSpawnCommand } from "@t3tools/shared/shell";
import * as Config from "effect/Config";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Hash from "effect/Hash";
import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Schema from "effect/Schema";
import { Argument, Command, Flag } from "effect/cli";
import { ChildProcess } from "effect/process";

import { defaultDevMemoryLimitBytes, enforceDevMemoryLimit } from "./lib/dev-memory-limit.ts";
import { type DevShareError, shareDevServer, unshareDevServer } from "./lib/dev-share.ts";
import { loadRepoEnv } from "./lib/public-config.ts";

Object.assign(process.env, loadRepoEnv());

const BASE_SERVER_PORT = 13773;
const BASE_WEB_PORT = 5733;
const MAX_HASH_OFFSET = 3000;
const MAX_PORT = 65535;
const DESKTOP_DEV_LOOPBACK_HOST = "127.0.0.1";
// Browsers block these ports before networking even when curl accepts them.
// https://fetch.spec.whatwg.org/#port-blocking
const FETCH_BAD_PORTS = new Set([
  0, 1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102,
  103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465,
  512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993,
  995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668,
  6669, 6679, 6697, 10080,
]);
// Dev binds loopback; other interfaces cannot establish port availability.
const DEV_PORT_PROBE_HOSTS = ["127.0.0.1", "::1"] as const;
// Migration prunes after copying, so large sources also need an automatic-seeding limit.
const LARGE_DEV_DATABASE_BYTES = 500 * 1024 * 1024;

/** Only loopback and wildcard binds keep the loopback proxy target reachable. */
export function isProxiableBindHost(host: string): boolean {
  const normalized = host.trim();
  return (
    normalized === "" ||
    normalized === "localhost" ||
    normalized === "127.0.0.1" ||
    normalized === "::1" ||
    normalized === "[::1]" ||
    normalized === "0.0.0.0" ||
    normalized === "::" ||
    normalized === "[::]"
  );
}

function sharedBackendTargetHost(host: string | undefined): string {
  const normalized = host?.trim() ?? "";
  if (normalized === "::1" || normalized === "[::1]") return "[::1]";
  if (normalized === "localhost") return "localhost";
  return "127.0.0.1";
}

export const DEFAULT_T3_HOME = Effect.map(Effect.service(Path.Path), (path) =>
  path.join(NodeOS.homedir(), ".t3"),
);

const MODE_ARGS = {
  dev: [
    "run",
    "--filter=@t3tools/contracts",
    "--filter=@t3tools/web",
    "--filter=t3",
    "--parallel",
    "dev",
  ],
  "dev:server": ["run", "--filter=t3", "dev"],
  "dev:web": ["run", "--filter=@t3tools/web", "dev"],
  "dev:desktop": ["run", "--filter=@t3tools/desktop", "--filter=@t3tools/web", "dev"],
} as const satisfies Record<string, ReadonlyArray<string>>;

// `--built`: the web package rebuilds into apps/web/dist and the backend serves
// it, so no Vite dev server runs.
const BUILT_DEV_ARGS = [
  "run",
  "--filter=@t3tools/web",
  "--filter=t3",
  "--parallel",
  "dev:built",
] as const;

type DevMode = keyof typeof MODE_ARGS;
// Only backend ports honor --host/T3CODE_HOST; web ports stay loopback.
type PortAvailabilityCheck<R = never> = (
  port: number,
  role?: "server" | "web",
) => Effect.Effect<boolean, never, R>;

const DEV_RUNNER_MODES = Object.keys(MODE_ARGS) as Array<DevMode>;

export function isBrowserAllowedPort(port: number): boolean {
  return !FETCH_BAD_PORTS.has(port);
}

export class DevRunnerConfigurationError extends Schema.TaggedError<DevRunnerConfigurationError>()(
  "DevRunnerConfigurationError",
  {
    configKeys: Schema.Array(Schema.String),
    cause: Schema.Defect(),
  },
) {
  override get message(): string {
    return `Failed to read dev-runner configuration: ${this.configKeys.join(", ")}.`;
  }
}

export class DevRunnerInvalidPortOffsetError extends Schema.TaggedError<DevRunnerInvalidPortOffsetError>()(
  "DevRunnerInvalidPortOffsetError",
  {
    configKey: Schema.Literal("T3CODE_PORT_OFFSET"),
    portOffset: Schema.Number,
    minimum: Schema.Number,
  },
) {
  override get message(): string {
    return `${this.configKey} must be at least ${this.minimum}; received ${this.portOffset}.`;
  }
}

export class DevRunnerPortExhaustedError extends Schema.TaggedError<DevRunnerPortExhaustedError>()(
  "DevRunnerPortExhaustedError",
  {
    startOffset: Schema.Number,
    requireServerPort: Schema.Boolean,
    requireWebPort: Schema.Boolean,
    baseServerPort: Schema.Number,
    baseWebPort: Schema.Number,
    maximumPort: Schema.Number,
  },
) {
  override get message(): string {
    return `No required dev ports were available from offset ${this.startOffset} through maximum port ${this.maximumPort}.`;
  }
}

export class DevRunnerProcessError extends Schema.TaggedError<DevRunnerProcessError>()(
  "DevRunnerProcessError",
  {
    operation: Schema.Literals(["spawn", "wait-for-exit"]),
    mode: Schema.Literals(["dev", "dev:server", "dev:web", "dev:desktop"]),
    executable: Schema.Literal("vp"),
    argumentCount: Schema.Number,
    shell: Schema.Boolean,
    cause: Schema.Defect(),
  },
) {
  override get message(): string {
    return `Dev-runner process operation "${this.operation}" failed for mode "${this.mode}".`;
  }
}

export class DevRunnerProcessExitError extends Schema.TaggedError<DevRunnerProcessExitError>()(
  "DevRunnerProcessExitError",
  {
    mode: Schema.Literals(["dev", "dev:server", "dev:web", "dev:desktop"]),
    executable: Schema.Literal("vp"),
    argumentCount: Schema.Number,
    shell: Schema.Boolean,
    exitCode: Schema.Number,
  },
) {
  override get message(): string {
    return `Dev-runner process exited with code ${this.exitCode} in mode "${this.mode}".`;
  }
}

export class DevRunnerHostNotProxiableError extends Schema.TaggedError<DevRunnerHostNotProxiableError>()(
  "DevRunnerHostNotProxiableError",
  {
    mode: Schema.Literals(["dev", "dev:web"]),
    host: Schema.String,
  },
) {
  override get message(): string {
    return `--host ${this.host} cannot be combined with ${this.mode}: single-origin browser dev proxies the backend at localhost, and a backend bound only to ${this.host} leaves localhost unanswered, so every proxied request fails. Use a wildcard (0.0.0.0 or ::) to serve that interface and loopback together, or --share for remote access.`;
  }
}

export class DevRunnerBuiltNeedsShareError extends Schema.TaggedError<DevRunnerBuiltNeedsShareError>()(
  "DevRunnerBuiltNeedsShareError",
  {
    mode: Schema.Literals(["dev", "dev:server", "dev:web", "dev:desktop"]),
  },
) {
  override get message(): string {
    return `--built only works with \`dev --share\` (got ${this.mode}${this.mode === "dev" ? " without --share" : ""}): the backend serves the built client on the tailnet URL.`;
  }
}

const optionalStringConfig = (name: string): Config.Config<string | undefined> =>
  Config.String(name).pipe(
    Config.option,
    Config.map((value) => Option.getOrUndefined(value)),
  );
const optionalBooleanConfig = (name: string): Config.Config<boolean | undefined> =>
  Config.Boolean(name).pipe(
    Config.option,
    Config.map((value) => Option.getOrUndefined(value)),
  );
const optionalPortConfig = (name: string): Config.Config<number | undefined> =>
  Config.Port(name).pipe(
    Config.option,
    Config.map((value) => Option.getOrUndefined(value)),
  );
const optionalIntegerConfig = (name: string): Config.Config<number | undefined> =>
  Config.Int(name).pipe(
    Config.option,
    Config.map((value) => Option.getOrUndefined(value)),
  );
const OffsetConfig = Config.all({
  portOffset: optionalIntegerConfig("T3CODE_PORT_OFFSET"),
  devInstance: optionalStringConfig("T3CODE_DEV_INSTANCE"),
});

export function resolveOffset(config: {
  readonly portOffset: number | undefined;
  readonly devInstance: string | undefined;
  readonly worktreePath?: string | undefined;
}): Effect.Effect<
  { readonly offset: number; readonly source: string },
  DevRunnerInvalidPortOffsetError
> {
  if (config.portOffset !== undefined) {
    if (config.portOffset < 0) {
      return Effect.fail(
        new DevRunnerInvalidPortOffsetError({
          configKey: "T3CODE_PORT_OFFSET",
          portOffset: config.portOffset,
          minimum: 0,
        }),
      );
    }
    return Effect.succeed({
      offset: config.portOffset,
      source: `T3CODE_PORT_OFFSET=${config.portOffset}`,
    });
  }

  const seed = config.devInstance?.trim();
  if (seed) {
    if (/^\d+$/.test(seed)) {
      return Effect.succeed({
        offset: Number(seed),
        source: `numeric T3CODE_DEV_INSTANCE=${seed}`,
      });
    }

    const offset = ((Hash.string(seed) >>> 0) % MAX_HASH_OFFSET) + 1;
    return Effect.succeed({ offset, source: `hashed T3CODE_DEV_INSTANCE=${seed}` });
  }

  const worktreePath = config.worktreePath?.trim();
  if (worktreePath) {
    const offset = ((Hash.string(worktreePath) >>> 0) % MAX_HASH_OFFSET) + 1;
    return Effect.succeed({ offset, source: `worktree ${worktreePath}` });
  }

  return Effect.succeed({ offset: 0, source: "default ports" });
}

const resolveBaseDir = Effect.fn("dev-runner.resolveBaseDir")(function* (
  baseDir: string | undefined,
): Effect.fn.Return<string, never, Path.Path> {
  const path = yield* Path.Path;
  const configured = baseDir?.trim();

  if (configured === "~") {
    return yield* HostProcess.HomeDirectory;
  }
  if (configured?.startsWith("~/") || configured?.startsWith("~\\")) {
    return path.join(yield* HostProcess.HomeDirectory, configured.slice(2));
  }
  if (configured) {
    return path.resolve(configured);
  }

  return yield* DEFAULT_T3_HOME;
});

interface CreateDevRunnerEnvInput {
  readonly mode: DevMode;
  readonly baseEnv: NodeJS.ProcessEnv;
  readonly serverOffset: number;
  readonly webOffset: number;
  readonly t3Home: string | undefined;
  readonly browser: boolean | undefined;
  readonly autoBootstrapProjectFromCwd: boolean | undefined;
  readonly logWebSocketEvents: boolean | undefined;
  readonly host: string | undefined;
  readonly port: number | undefined;
  readonly devUrl: URL | undefined;
}

export const createDevRunnerEnv = Effect.fn("dev-runner.createDevRunnerEnv")(function* ({
  mode,
  baseEnv,
  serverOffset,
  webOffset,
  t3Home,
  browser,
  autoBootstrapProjectFromCwd,
  logWebSocketEvents,
  host,
  port,
  devUrl,
}: CreateDevRunnerEnvInput): Effect.fn.Return<NodeJS.ProcessEnv, never, Path.Path> {
  const serverPort = port ?? BASE_SERVER_PORT + serverOffset;
  const webPort = BASE_WEB_PORT + webOffset;
  const configuredBaseDir = t3Home?.trim() || undefined;
  const resolvedBaseDir = yield* resolveBaseDir(configuredBaseDir);
  const isDesktopMode = mode === "dev:desktop";

  const output: NodeJS.ProcessEnv = {
    ...baseEnv,
    PORT: String(webPort),
    VITE_DEV_SERVER_URL:
      devUrl?.toString() ??
      `http://${isDesktopMode ? DESKTOP_DEV_LOOPBACK_HOST : "localhost"}:${webPort}`,
  };

  if (configuredBaseDir !== undefined) {
    output.T3CODE_HOME = resolvedBaseDir;
  } else {
    delete output.T3CODE_HOME;
  }

  // Managed T3 service shells leak launcher variables that make dev servers fail version checks.
  // Dev-runner servers are never launcher-managed (serviceLauncherClient.ts resolveStartup).
  delete output.T3_SERVICE_LAUNCHER_CONTEXT;
  delete output.T3_BOOT_SERVICE_UNIT;

  // Each worktree has its own state, so a dev server would count as a new
  // install of the developer's real accounts. Set it explicitly to opt in.
  output.T3CODE_TELEMETRY_ENABLED = baseEnv.T3CODE_TELEMETRY_ENABLED ?? "false";

  if (!isDesktopMode) {
    output.T3CODE_PORT = String(serverPort);
    // An inherited HOST pins Vite's HMR socket via explicitHost in apps/web/vite.config.ts.
    // Only desktop mode should set it.
    delete output.HOST;
    if (mode === "dev" || mode === "dev:web") {
      // Browser dev is single-origin: everything (including /ws) is proxied
      // through Vite, so the client must resolve its backend from
      // window.location.origin rather than a baked-in localhost URL.
      delete output.VITE_HTTP_URL;
      delete output.VITE_WS_URL;
      // Deleting is not enough on its own: vite.config.ts calls loadRepoEnv,
      // which merges `.env`/`.env.local` *under* this env, so a developer
      // with either URL in their `.env` would get it back and silently lose
      // single-origin mode.
      output.T3CODE_SINGLE_ORIGIN_DEV = "1";
    } else {
      output.VITE_HTTP_URL = `http://localhost:${serverPort}`;
      output.VITE_WS_URL = `ws://localhost:${serverPort}`;
      delete output.T3CODE_SINGLE_ORIGIN_DEV;
    }
  } else {
    output.T3CODE_PORT = String(serverPort);
    output.VITE_HTTP_URL = `http://${DESKTOP_DEV_LOOPBACK_HOST}:${serverPort}`;
    output.VITE_WS_URL = `ws://${DESKTOP_DEV_LOOPBACK_HOST}:${serverPort}`;
    // Desktop pins the renderer to loopback on purpose; an ambient marker
    // must not make Vite drop those URLs.
    delete output.T3CODE_SINGLE_ORIGIN_DEV;
    delete output.T3CODE_MODE;
    delete output.T3CODE_NO_BROWSER;
    delete output.T3CODE_HOST;
    delete output.T3CODE_DEV_AUTH_TOKEN;
  }

  if (!isDesktopMode && host !== undefined) {
    output.T3CODE_HOST = host;
  }

  if (!isDesktopMode) {
    output.T3CODE_NO_BROWSER = browser === true ? "0" : "1";
  }

  if (autoBootstrapProjectFromCwd !== undefined) {
    output.T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD = autoBootstrapProjectFromCwd ? "1" : "0";
  } else {
    delete output.T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD;
  }

  if (logWebSocketEvents !== undefined) {
    output.T3CODE_LOG_WS_EVENTS = logWebSocketEvents ? "1" : "0";
  } else {
    delete output.T3CODE_LOG_WS_EVENTS;
  }

  if (mode === "dev") {
    output.T3CODE_MODE = "web";
    delete output.T3CODE_DESKTOP_WS_URL;
  }

  if (mode === "dev:server" || mode === "dev:web") {
    output.T3CODE_MODE = "web";
    delete output.T3CODE_DESKTOP_WS_URL;
  }

  if (isDesktopMode) {
    output.HOST = DESKTOP_DEV_LOOPBACK_HOST;
    delete output.T3CODE_DESKTOP_WS_URL;
  }

  return output;
});

function portPairForOffset(offset: number): {
  readonly serverPort: number;
  readonly webPort: number;
} {
  return {
    serverPort: BASE_SERVER_PORT + offset,
    webPort: BASE_WEB_PORT + offset,
  };
}

export const checkPortAvailabilityOnHosts = Effect.fn("dev-runner.checkPortAvailabilityOnHosts")(
  function* <R>(
    port: number,
    hosts: ReadonlyArray<string>,
    canListenOnHost: (port: number, host: string) => Effect.Effect<boolean, never, R>,
  ): Effect.fn.Return<boolean, never, R> {
    for (const host of hosts) {
      if (!(yield* canListenOnHost(port, host))) {
        return false;
      }
    }

    return true;
  },
);

export function devPortProbeHosts(configuredHost: string | undefined): ReadonlyArray<string> {
  const host = configuredHost?.trim();
  if (!host || DEV_PORT_PROBE_HOSTS.includes(host as (typeof DEV_PORT_PROBE_HOSTS)[number])) {
    return DEV_PORT_PROBE_HOSTS;
  }
  return [...DEV_PORT_PROBE_HOSTS, host];
}

const makeDefaultCheckPortAvailability =
  (configuredHost: string | undefined): PortAvailabilityCheck<NetService.NetService> =>
  (port, role) =>
    Effect.gen(function* () {
      const net = yield* NetService.NetService;
      const hosts = role === "web" ? DEV_PORT_PROBE_HOSTS : devPortProbeHosts(configuredHost);
      return yield* checkPortAvailabilityOnHosts(port, hosts, (candidatePort, host) =>
        net.canListenOnHost(candidatePort, host),
      );
    });

const defaultCheckPortAvailability = makeDefaultCheckPortAvailability(undefined);

interface FindFirstAvailableOffsetInput<R = NetService.NetService> {
  readonly startOffset: number;
  readonly requireServerPort: boolean;
  readonly requireWebPort: boolean;
  readonly checkPortAvailability?: PortAvailabilityCheck<R>;
}

export const findFirstAvailableOffset = Effect.fn("dev-runner.findFirstAvailableOffset")(function* <
  R = NetService.NetService,
>({
  startOffset,
  requireServerPort,
  requireWebPort,
  checkPortAvailability,
}: FindFirstAvailableOffsetInput<R>): Effect.fn.Return<number, DevRunnerPortExhaustedError, R> {
  const checkPort = (checkPortAvailability ??
    defaultCheckPortAvailability) as PortAvailabilityCheck<R>;

  for (let candidate = startOffset; ; candidate += 1) {
    const { serverPort, webPort } = portPairForOffset(candidate);
    const serverPortOutOfRange = serverPort > MAX_PORT;
    const webPortOutOfRange = webPort > MAX_PORT;

    if (
      (requireServerPort && serverPortOutOfRange) ||
      (requireWebPort && webPortOutOfRange) ||
      (!requireServerPort && !requireWebPort && (serverPortOutOfRange || webPortOutOfRange))
    ) {
      break;
    }

    if (requireWebPort && !isBrowserAllowedPort(webPort)) {
      continue;
    }

    const checks: Array<Effect.Effect<boolean, never, R>> = [];
    if (requireServerPort) {
      checks.push(checkPort(serverPort, "server"));
    }
    if (requireWebPort) {
      checks.push(checkPort(webPort, "web"));
    }

    if (checks.length === 0) {
      return candidate;
    }

    const availability = yield* Effect.all(checks);
    if (availability.every(Boolean)) {
      return candidate;
    }
  }

  return yield* new DevRunnerPortExhaustedError({
    startOffset,
    requireServerPort,
    requireWebPort,
    baseServerPort: BASE_SERVER_PORT,
    baseWebPort: BASE_WEB_PORT,
    maximumPort: MAX_PORT,
  });
});

interface ResolveModePortOffsetsInput<R = NetService.NetService> {
  readonly mode: DevMode;
  readonly startOffset: number;
  readonly hasExplicitServerPort: boolean;
  readonly hasExplicitDevUrl: boolean;
  readonly checkPortAvailability?: PortAvailabilityCheck<R>;
}

export const resolveModePortOffsets = Effect.fn("dev-runner.resolveModePortOffsets")(function* <
  R = NetService.NetService,
>({
  mode,
  startOffset,
  hasExplicitServerPort,
  hasExplicitDevUrl,
  checkPortAvailability,
}: ResolveModePortOffsetsInput<R>): Effect.fn.Return<
  { readonly serverOffset: number; readonly webOffset: number },
  DevRunnerPortExhaustedError,
  R
> {
  const checkPort = (checkPortAvailability ??
    defaultCheckPortAvailability) as PortAvailabilityCheck<R>;

  if (mode === "dev:web") {
    if (hasExplicitDevUrl) {
      return { serverOffset: startOffset, webOffset: startOffset };
    }

    const webOffset = yield* findFirstAvailableOffset({
      startOffset,
      requireServerPort: false,
      requireWebPort: true,
      checkPortAvailability: checkPort,
    });
    return { serverOffset: startOffset, webOffset };
  }

  if (mode === "dev:server") {
    if (hasExplicitServerPort) {
      return { serverOffset: startOffset, webOffset: startOffset };
    }

    const serverOffset = yield* findFirstAvailableOffset({
      startOffset,
      requireServerPort: true,
      requireWebPort: false,
      checkPortAvailability: checkPort,
    });
    return { serverOffset, webOffset: serverOffset };
  }

  const sharedOffset = yield* findFirstAvailableOffset({
    startOffset,
    requireServerPort: !hasExplicitServerPort,
    requireWebPort: !hasExplicitDevUrl,
    checkPortAvailability: checkPort,
  });

  return { serverOffset: sharedOffset, webOffset: sharedOffset };
});

/** Best effort: a failed first-start step warns, and dev still starts. */
const runRepoScript = Effect.fn("dev-runner.runRepoScript")(function* (
  script: string,
  args: ReadonlyArray<string>,
  env: NodeJS.ProcessEnv,
) {
  const path = yield* Path.Path;
  const repoRoot = path.dirname(import.meta.dirname);
  const exitCode = yield* ChildProcess.make(
    yield* HostProcess.ExecutablePath,
    [path.join(repoRoot, script), ...args],
    { cwd: repoRoot, stdin: "ignore", stdout: "inherit", stderr: "inherit", env, extendEnv: false },
  ).pipe(
    Effect.flatMap((child) => child.exitCode),
    Effect.scoped,
    Effect.orElseSucceed(() => -1),
  );
  if (exitCode !== 0) {
    yield* Effect.logWarning(`[dev-runner] ${script} failed; starting anyway.`);
  }
});

/**
 * The first start in a worktree seeds its empty database from a small live database
 * and warms the web dependency cache. Each step checks for its own output, so
 * later starts skip it.
 */
const prepareFirstStart = Effect.fn("dev-runner.prepareFirstStart")(function* (input: {
  readonly mode: DevMode;
  readonly seed: boolean;
  readonly worktreeHome: string | undefined;
  readonly env: NodeJS.ProcessEnv;
}) {
  const fs = yield* FileSystem.FileSystem;
  const path = yield* Path.Path;
  const exists = (file: string) => fs.exists(file).pipe(Effect.orElseSucceed(() => false));

  if (input.worktreeHome !== undefined && input.mode !== "dev:web") {
    const stateDir = path.join(input.worktreeHome, "userdata");
    for (const name of ["statev2.sqlite", "state.sqlite"]) {
      const file = path.join(stateDir, name);
      const info = yield* fs.stat(file).pipe(Effect.option);
      if (Option.isSome(info) && Number(info.value.size) > LARGE_DEV_DATABASE_BYTES) {
        yield* Effect.logWarning(
          `[dev-runner] ${file} is ${Math.round(Number(info.value.size) / 1024 / 1024)} MB. With the dev server stopped, \`vp run migrate-dev-db\` rebuilds statev2.sqlite as a small copy of recent data.`,
        );
      }
    }
    const source = path.join(yield* HostProcess.HomeDirectory, ".t3", "userdata", "statev2.sqlite");
    // A V1 state.sqlite counts as data too: the server imports it only while
    // statev2.sqlite is missing, so seeding would hide it.
    if (
      input.seed &&
      !(yield* exists(path.join(stateDir, "statev2.sqlite"))) &&
      !(yield* exists(path.join(stateDir, "state.sqlite")))
    ) {
      const info = yield* fs.stat(source).pipe(Effect.option);
      if (Option.isSome(info)) {
        if (Number(info.value.size) > LARGE_DEV_DATABASE_BYTES) {
          yield* Effect.logWarning(
            `[dev-runner] ${source} exceeds 500 MiB; skipping automatic database seeding and starting with an empty database. Run \`vp run migrate-dev-db\` manually with dev stopped if needed; it may use substantial disk space before pruning.`,
          );
        } else {
          yield* Effect.logInfo(
            `[dev-runner] seeding ${input.worktreeHome} from ${source} (read-only). --no-seed or T3CODE_DEV_SEED=0 skips this.`,
          );
          yield* runRepoScript(
            "apps/server/scripts/migrate-dev-db.ts",
            ["--base-dir", input.worktreeHome, "--source", source],
            input.env,
          );
        }
      }
    }
  }

  const repoRoot = path.dirname(import.meta.dirname);
  if (
    input.mode !== "dev:server" &&
    !(yield* exists(path.join(repoRoot, "apps/web/node_modules/.vite/deps/_metadata.json")))
  ) {
    yield* runRepoScript("apps/web/scripts/warm-dep-cache.ts", [], input.env);
  }
});

interface DevRunnerCliInput {
  readonly mode: DevMode;
  readonly t3Home: string | undefined;
  readonly browser: boolean | undefined;
  readonly autoBootstrapProjectFromCwd: boolean | undefined;
  readonly logWebSocketEvents: boolean | undefined;
  readonly host: string | undefined;
  readonly port: number | undefined;
  readonly devUrl: URL | undefined;
  readonly dryRun: boolean;
  readonly share: boolean;
  readonly seed?: boolean | undefined;
  readonly built: boolean;
  readonly memoryLimitGb?: number | undefined;
  readonly runArgs: ReadonlyArray<string>;
}

export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput")(function* (
  input: DevRunnerCliInput,
) {
  const { portOffset, devInstance } = yield* OffsetConfig.pipe(
    Effect.mapError(
      (cause) =>
        new DevRunnerConfigurationError({
          configKeys: ["T3CODE_PORT_OFFSET", "T3CODE_DEV_INSTANCE"],
          cause,
        }),
    ),
  );

  if (
    (input.mode === "dev" || input.mode === "dev:web") &&
    input.host !== undefined &&
    !isProxiableBindHost(input.host)
  ) {
    return yield* new DevRunnerHostNotProxiableError({ mode: input.mode, host: input.host });
  }

  if (input.built && (input.mode !== "dev" || !input.share)) {
    return yield* new DevRunnerBuiltNeedsShareError({ mode: input.mode });
  }

  const worktreePath = yield* resolveGitWorktreePath(yield* HostProcess.WorkingDirectory);

  const { offset, source } = yield* resolveOffset({
    portOffset,
    devInstance,
    worktreePath,
  });

  const { serverOffset, webOffset } = yield* resolveModePortOffsets({
    mode: input.mode,
    startOffset: offset,
    hasExplicitServerPort: input.port !== undefined,
    hasExplicitDevUrl: input.devUrl !== undefined,
    checkPortAvailability: makeDefaultCheckPortAvailability(input.host),
  });

  const hostEnvironment = yield* HostProcess.Environment;
  // A dev server started inside a worktree defaults to that worktree's own
  // (gitignored) `.t3` — see @t3tools/shared/devHome for why this must
  // outrank an ambient T3CODE_HOME. `--home-dir` still wins.
  const worktreeHome = yield* resolveWorktreeT3Home(yield* HostProcess.WorkingDirectory);
  // Trim before choosing: `--home-dir ""` is not a selection, and treating it
  // as one would skip the worktree default and land on the shared home —
  // exactly the outcome this precedence exists to prevent.
  const resolvedT3Home =
    (input.t3Home?.trim() || undefined) ??
    worktreeHome ??
    (hostEnvironment.T3CODE_HOME?.trim() || undefined);
  const env = yield* createDevRunnerEnv({
    mode: input.mode,
    baseEnv: hostEnvironment,
    serverOffset,
    webOffset,
    t3Home: resolvedT3Home,
    browser: input.browser,
    autoBootstrapProjectFromCwd: input.autoBootstrapProjectFromCwd,
    logWebSocketEvents: input.logWebSocketEvents,
    host: input.host,
    port: input.port,
    devUrl: input.devUrl,
  });

  const selectionSuffix =
    serverOffset !== offset || webOffset !== offset
      ? ` selectedOffset(server=${serverOffset},web=${webOffset})`
      : "";
  const baseDir = env.T3CODE_HOME ?? (yield* DEFAULT_T3_HOME);

  yield* Effect.logInfo(
    `[dev-runner] mode=${input.mode} source=${source}${selectionSuffix} serverPort=${String(env.T3CODE_PORT)} webPort=${String(env.PORT)} baseDir=${baseDir}`,
  );

  // Before the share block: --dry-run only resolves and prints. Sharing would
  // replace, then tear down, whatever mapping the port already had — a
  // surprising side effect from a command documented as inert.
  if (input.dryRun) {
    return;
  }

  const sharedWebPort = BASE_WEB_PORT + webOffset;
  let built = false;
  if (input.share) {
    if (input.mode === "dev:server") {
      yield* Effect.logInfo("[dev-runner] --share has no effect for dev:server (no web server).");
    } else if (input.mode === "dev:desktop") {
      yield* Effect.logWarning(
        "[dev-runner] --share is not supported for dev:desktop (the renderer is pinned to loopback). Use `dev`, which runs the whole browser stack.",
      );
    } else {
      // acquireRelease, not share-then-addFinalizer: the mapping outlives this
      // process (and reboots), so the cleanup has to be registered atomically
      // with creating it. An interrupt landing in between would otherwise
      // leave a mapping pointing at a port nothing is listening on.
      const shared = yield* Effect.acquireRelease(
        shareDevServer({
          webPort: sharedWebPort,
          // The backend binds 127.0.0.1 unless --host changes it. A wildcard
          // still answers there; `--host ::1` binds only the IPv6 loopback, and
          // `localhost` binds whichever loopback Node resolves first.
          ...(input.built
            ? {
                localTarget: {
                  port: Number(env.T3CODE_PORT),
                  host: sharedBackendTargetHost(input.host),
                },
              }
            : {}),
        }),
        () =>
          unshareDevServer(sharedWebPort).pipe(
            Effect.flatMap((result) =>
              result.cleared
                ? Effect.void
                : Effect.logWarning(
                    `[dev-runner] could not remove the tailnet mapping for port ${String(sharedWebPort)}${
                      result.explanation ? `: ${result.explanation}` : ""
                    }. Remove it with \`tailscale serve --https=${String(sharedWebPort)} --set-path=/ off\`.`,
                  ),
            ),
          ),
      ).pipe(
        Effect.tapError((error: DevShareError) =>
          Effect.logWarning(
            `[dev-runner] could not share on the tailnet: ${error.message}${
              error.hint ? ` — ${error.hint}` : ""
            }`,
          ),
        ),
        Effect.option,
        Effect.map(Option.getOrUndefined),
      );

      if (shared) {
        // The app is reached from the tailnet origin. Vite already allows
        // *.ts.net hosts; the backend needs the origin for credentialed
        // requests that bypass the proxy (desktop renderer, direct calls).
        env.T3CODE_DEV_ALLOWED_ORIGINS = [
          env.T3CODE_DEV_ALLOWED_ORIGINS,
          new URL(shared.url).origin,
        ]
          .filter((entry) => entry && entry.length > 0)
          .join(",");
        if (input.devUrl === undefined) {
          env.VITE_DEV_SERVER_URL = shared.url;
        }
        if (input.built) {
          built = true;
          env.T3CODE_BUILT_DEV = "1";
        } else if (env.T3CODE_BUNDLED_DEV === undefined) {
          // A shared origin serves a remote browser, where unbundled dev's
          // per-module requests each pay a tailnet round trip — a cold module
          // graph takes minutes to first paint. Bundled dev collapses that to a
          // few chunk requests.
          env.T3CODE_BUNDLED_DEV = "1";
        }
        yield* Effect.logInfo(`[dev-runner] shared on tailnet: ${shared.url}`);
      } else if (input.built) {
        yield* Effect.logWarning(
          "[dev-runner] --built needs the tailnet share; running the Vite dev server instead.",
        );
      }
    }
  }

  // After sharing, so the warm step sees the same bundled-dev env as Vite.
  yield* prepareFirstStart({
    mode: input.mode,
    seed: input.seed !== false,
    worktreeHome: baseDir === worktreeHome ? worktreeHome : undefined,
    env,
  });

  const args = [...(built ? BUILT_DEV_ARGS : MODE_ARGS[input.mode]), ...input.runArgs];
  const spawnCommand = yield* resolveSpawnCommand("vp", args, { env });
  const processContext = {
    mode: input.mode,
    executable: "vp" as const,
    argumentCount: args.length,
    shell: spawnCommand.shell,
  } as const;
  const child = yield* ChildProcess.make(spawnCommand.command, spawnCommand.args, {
    stdin: "inherit",
    stdout: "inherit",
    stderr: "inherit",
    env,
    extendEnv: false,
    shell: spawnCommand.shell,
    // Its own process group: teardown signals the whole group, because vp
    // does not pass SIGTERM on to Vite and the server.
    detached: true,
    forceKillAfter: "1500 millis",
  }).pipe(
    Effect.mapError(
      (cause) =>
        new DevRunnerProcessError({
          ...processContext,
          operation: "spawn",
          cause,
        }),
    ),
  );

  const memoryLimitBytes =
    input.memoryLimitGb === undefined
      ? defaultDevMemoryLimitBytes()
      : input.memoryLimitGb * 1024 ** 3;
  const exitCode = yield* child.exitCode.pipe(
    Effect.mapError(
      (cause) =>
        new DevRunnerProcessError({
          ...processContext,
          operation: "wait-for-exit",
          cause,
        }),
    ),
    Effect.raceFirst(enforceDevMemoryLimit(memoryLimitBytes)),
  );
  if (exitCode !== 0) {
    return yield* new DevRunnerProcessExitError({
      ...processContext,
      exitCode,
    });
  }
});

const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));

const devRunnerCli = Command.make("dev-runner", {
  mode: Argument.Literals("mode", DEV_RUNNER_MODES).pipe(
    Argument.withDescription("Development mode to run."),
  ),
  t3Home: Flag.String("home-dir").pipe(
    Flag.withDescription(
      "Explicit T3 Code data directory; runtime state is stored under userdata (equivalent to T3CODE_HOME). Inside a git worktree this defaults to that worktree's own .t3 so dev state stays off the shared home.",
    ),
    Flag.optional,
    Flag.map(Option.getOrUndefined),
  ),
  browser: Flag.Boolean("browser").pipe(
    Flag.withDescription("Open a browser automatically (disabled by default for web dev)."),
    Flag.withDefault(false),
  ),
  autoBootstrapProjectFromCwd: Flag.Boolean("auto-bootstrap-project-from-cwd").pipe(
    Flag.withDescription(
      "Auto-bootstrap toggle (equivalent to T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD).",
    ),
    Flag.withFallbackConfig(optionalBooleanConfig("T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD")),
  ),
  logWebSocketEvents: Flag.Boolean("log-websocket-events").pipe(
    Flag.withDescription("WebSocket event logging toggle (equivalent to T3CODE_LOG_WS_EVENTS)."),
    Flag.withAlias("log-ws-events"),
    Flag.withFallbackConfig(optionalBooleanConfig("T3CODE_LOG_WS_EVENTS")),
  ),
  host: Flag.String("host").pipe(
    Flag.withDescription("Server host/interface override (forwards to T3CODE_HOST)."),
    Flag.withFallbackConfig(optionalStringConfig("T3CODE_HOST")),
  ),
  port: Flag.Int("port").pipe(
    Flag.withSchema(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }))),
    Flag.withDescription("Server port override (forwards to T3CODE_PORT)."),
    Flag.withFallbackConfig(optionalPortConfig("T3CODE_PORT")),
  ),
  devUrl: Flag.String("dev-url").pipe(
    Flag.withSchema(Schema.URLFromString),
    Flag.withDescription(
      "Explicit web dev URL override (forwards to VITE_DEV_SERVER_URL). Ambient VITE_DEV_SERVER_URL values are ignored so a parent dev app cannot redirect the child runner.",
    ),
    Flag.optional,
    Flag.map(Option.getOrUndefined),
  ),
  dryRun: Flag.Boolean("dry-run").pipe(
    Flag.withDescription("Resolve mode/ports/env and print, but do not spawn Vite+."),
    Flag.withDefault(false),
  ),
  share: Flag.Boolean("share").pipe(
    Flag.withDescription(
      "Publish the web dev server on this machine's tailnet over HTTPS (via `tailscale serve`) and print the pairing URL for it. Removed again on exit.",
    ),
    Flag.withDefault(false),
  ),
  seed: Flag.Boolean("seed").pipe(
    Flag.withDescription(
      "Seed an empty worktree database from ~/.t3 on first start (read-only, via migrate-dev-db) if the source is at most 500 MiB. On by default; --no-seed or T3CODE_DEV_SEED=0 skips it.",
    ),
    Flag.withFallbackConfig(optionalBooleanConfig("T3CODE_DEV_SEED")),
  ),
  built: Flag.Boolean("built").pipe(
    Flag.withDescription(
      "With --share: serve a production web build from the backend instead of the Vite dev server. Rebuilds on change, no HMR, much smaller remote loads.",
    ),
    Flag.withDefault(false),
  ),
  memoryLimitGb: Flag.Int("memory-limit-gb").pipe(
    Flag.withSchema(NonNegativeInt),
    Flag.withDescription(
      "Stop the dev server when it and its child processes use more than this many GiB of RAM plus swap (equivalent to T3CODE_DEV_MEMORY_LIMIT_GB). Defaults to half of RAM, at most 16. 0 turns it off. Linux only.",
    ),
    Flag.withFallbackConfig(
      Config.schema(NonNegativeInt, "T3CODE_DEV_MEMORY_LIMIT_GB").pipe(
        Config.option,
        Config.map(Option.getOrUndefined),
      ),
    ),
  ),
  runArgs: Argument.String("run-arg").pipe(
    Argument.withDescription("Additional Vite+ run args (pass after `--`)."),
    Argument.variadic(),
  ),
}).pipe(
  Command.withDescription("Run monorepo development modes with deterministic port/env wiring."),
  Command.withHandler((input) => runDevRunnerWithInput(input)),
);

const cliRuntimeLayer = Layer.mergeAll(
  Logger.layer([Logger.consolePretty()]),
  NodeServices.layer,
  NetService.layer,
);

if (import.meta.main) {
  // runMain interrupts (running finalizers such as the --share unmapping) only
  // on SIGINT/SIGTERM; a closed terminal or dropped SSH session sends SIGHUP.
  process.on("SIGHUP", () => process.kill(process.pid, "SIGTERM"));
  Command.run(devRunnerCli, { version: "0.0.0" }).pipe(
    Effect.scoped,
    Effect.provide(cliRuntimeLayer),
    NodeRuntime.runMain,
  );
}