#!/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 { 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 === "[::]" ); } 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>; // `--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 = ( port: number, role?: "server" | "web", ) => Effect.Effect; const DEV_RUNNER_MODES = Object.keys(MODE_ARGS) as Array; export function isBrowserAllowedPort(port: number): boolean { return !FETCH_BAD_PORTS.has(port); } export class DevRunnerConfigurationError extends Schema.TaggedError()( "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", { 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", { 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", { 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", { 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", { 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", { 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 => Config.String(name).pipe( Config.option, Config.map((value) => Option.getOrUndefined(value)), ); const optionalBooleanConfig = (name: string): Config.Config => Config.Boolean(name).pipe( Config.option, Config.map((value) => Option.getOrUndefined(value)), ); const optionalPortConfig = (name: string): Config.Config => Config.Port(name).pipe( Config.option, Config.map((value) => Option.getOrUndefined(value)), ); const optionalIntegerConfig = (name: string): Config.Config => 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 { 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 { 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* ( port: number, hosts: ReadonlyArray, canListenOnHost: (port: number, host: string) => Effect.Effect, ): Effect.fn.Return { for (const host of hosts) { if (!(yield* canListenOnHost(port, host))) { return false; } } return true; }, ); export function devPortProbeHosts(configuredHost: string | undefined): ReadonlyArray { 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 => (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 { readonly startOffset: number; readonly requireServerPort: boolean; readonly requireWebPort: boolean; readonly checkPortAvailability?: PortAvailabilityCheck; } export const findFirstAvailableOffset = Effect.fn("dev-runner.findFirstAvailableOffset")(function* < R = NetService.NetService, >({ startOffset, requireServerPort, requireWebPort, checkPortAvailability, }: FindFirstAvailableOffsetInput): Effect.fn.Return { const checkPort = (checkPortAvailability ?? defaultCheckPortAvailability) as PortAvailabilityCheck; 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> = []; 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 { readonly mode: DevMode; readonly startOffset: number; readonly hasExplicitServerPort: boolean; readonly hasExplicitDevUrl: boolean; readonly checkPortAvailability?: PortAvailabilityCheck; } export const resolveModePortOffsets = Effect.fn("dev-runner.resolveModePortOffsets")(function* < R = NetService.NetService, >({ mode, startOffset, hasExplicitServerPort, hasExplicitDevUrl, checkPortAvailability, }: ResolveModePortOffsetsInput): Effect.fn.Return< { readonly serverOffset: number; readonly webOffset: number }, DevRunnerPortExhaustedError, R > { const checkPort = (checkPortAvailability ?? defaultCheckPortAvailability) as PortAvailabilityCheck; 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, 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, * builds the native resource monitor, 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); // Dev backends load the monitor from its Cargo output, which a fresh // checkout or worktree does not have yet. if (input.mode !== "dev:web") { const crate = path.join(repoRoot, "native/resource-monitor"); const binary = (yield* HostProcess.Platform) === "win32" ? "t3-resource-monitor.exe" : "t3-resource-monitor"; if ( !(yield* exists(path.join(crate, "target/release", binary))) && !(yield* exists(path.join(crate, "target/debug", binary))) ) { yield* Effect.logInfo("[dev-runner] building the resource monitor (first start only)."); const exitCode = yield* ChildProcess.make( "cargo", ["build", "--locked", "--release", "--manifest-path", path.join(crate, "Cargo.toml")], { cwd: repoRoot, stdin: "ignore", stdout: "inherit", stderr: "inherit", env: input.env, extendEnv: false, }, ).pipe( Effect.flatMap((child) => child.exitCode), Effect.scoped, Effect.orElseSucceed(() => -1), ); if (exitCode !== 0) { yield* Effect.logWarning( "[dev-runner] could not build the resource monitor; starting without process telemetry. Install Rust and run `vp run build:resource-monitor`.", ); } } } 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 runArgs: ReadonlyArray; } 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. ...(input.built ? { localTarget: { port: Number(env.T3CODE_PORT), host: ["::1", "[::1]"].includes(input.host?.trim() ?? "") ? "[::1]" : "127.0.0.1", }, } : {}), }), () => 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, // Keep Vite+ in the same process group so terminal signals (Ctrl+C) // reach it directly. Effect defaults to detached: true on non-Windows, // which would put the runner in a new group and require manual forwarding. detached: false, forceKillAfter: "1500 millis", }).pipe( Effect.mapError( (cause) => new DevRunnerProcessError({ ...processContext, operation: "spawn", cause, }), ), ); const exitCode = yield* child.exitCode.pipe( Effect.mapError( (cause) => new DevRunnerProcessError({ ...processContext, operation: "wait-for-exit", cause, }), ), ); if (exitCode !== 0) { return yield* new DevRunnerProcessExitError({ ...processContext, exitCode, }); } }); 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), ), 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) { Command.run(devRunnerCli, { version: "0.0.0" }).pipe( Effect.scoped, Effect.provide(cliRuntimeLayer), NodeRuntime.runMain, ); }