The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 03:37 UTC
| 1 | import * as NodeNet from "node:net"; |
| 2 | import { stripVTControlCharacters } from "node:util"; |
| 3 | import * as Deferred from "effect/Deferred"; |
| 4 | import * as Effect from "effect/Effect"; |
| 5 | import { SystemError } from "effect/PlatformError"; |
| 6 | import * as Schedule from "effect/Schedule"; |
| 7 | import * as Stream from "effect/Stream"; |
| 8 | import * as LocalProvider from "../Local/LocalProvider.ts"; |
| 9 | import * as ProviderLayer from "../Local/ProviderLayer.ts"; |
| 10 | import * as Provider from "../Provider.ts"; |
| 11 | import { Resource } from "../Resource.ts"; |
| 12 | import { moduleExtension } from "../Util/Node.ts"; |
| 13 | import { makeResourceOutput } from "../Util/ResourceOutput.ts"; |
| 14 | import { CommandExecutor, UnexpectedExit, makeCommandError, type CommandProps } from "./Command.ts"; |
| 15 | import { makeCommandRedactor } from "./Redaction.ts"; |
| 16 | |
| 17 | export interface DevProps extends CommandProps { |
| 18 | /** |
| 19 | * Make the URL required: the resource is ready only once the command |
| 20 | * prints a URL, however long that takes, and fails if the command exits |
| 21 | * first. Without it, the resource waits 5 seconds and settles with |
| 22 | * `url: undefined` when no URL appears. |
| 23 | * |
| 24 | * A localhost/IP URL is still preferred: when the first URL printed is |
| 25 | * another one, the resource waits up to 5 seconds more for a local one |
| 26 | * before settling with it. |
| 27 | * |
| 28 | * @default false |
| 29 | */ |
| 30 | waitForUrl?: boolean; |
| 31 | /** |
| 32 | * The port the command listens on. Alchemy sets `PORT` to it, over any |
| 33 | * `env.PORT`, and the resource is ready once the port accepts a |
| 34 | * connection, however long that takes. Output isn't scanned for a URL, |
| 35 | * so `waitForUrl` has no effect: `url` is `http://localhost:<port>`. |
| 36 | * |
| 37 | * The resource fails if the command exits before the port opens, or if |
| 38 | * another process already listens on the port when the command starts. |
| 39 | */ |
| 40 | port?: number; |
| 41 | } |
| 42 | |
| 43 | export interface Dev extends Resource< |
| 44 | "Command.Dev", |
| 45 | DevProps, |
| 46 | { |
| 47 | /** |
| 48 | * URL extracted from stdout/stderr. A `localhost`/IP URL (the dev |
| 49 | * server's own address) is preferred over any other URL the command |
| 50 | * prints; a non-local URL is only used as a fallback if no local one |
| 51 | * appears. Best-effort: `undefined` if no URL appears within 5 seconds, |
| 52 | * unless `waitForUrl` is set, which waits until one does. With `port`, |
| 53 | * it is `http://localhost:<port>`. |
| 54 | */ |
| 55 | url: string | undefined; |
| 56 | } |
| 57 | > {} |
| 58 | |
| 59 | /** |
| 60 | * A long-lived shell process scoped to a stack instance, started during |
| 61 | * `alchemy dev` and restarted when its inputs change. During `alchemy deploy` |
| 62 | * this is a no-op — `Dev` resources only run in dev mode. |
| 63 | * |
| 64 | * The child process runs inside the dev sidecar (see `Command/Local.ts`) so it |
| 65 | * survives user-code HMR — Alchemy's user process can restart without killing |
| 66 | * your `npm run dev` server. Its stdout/stderr are mirrored to the terminal |
| 67 | * (preserving colored output) and scanned for an `http(s)://…` URL, favoring |
| 68 | * a `localhost`/IP URL (the dev server's own address) over any unrelated URL |
| 69 | * the command prints first. The result is exposed as the `url` output |
| 70 | * attribute — useful for surfacing a dev server's local URL back out to |
| 71 | * whatever resource declared this `Dev`. |
| 72 | * |
| 73 | * |
| 74 | * ### Basic Usage |
| 75 | * Pass a shell command that starts a long-lived dev server. Alchemy |
| 76 | * runs it in the background and extracts the first URL it prints. |
| 77 | * |
| 78 | * **Example:** Start a Vite dev server |
| 79 | * ```typescript |
| 80 | * const dev = yield* Dev("Frontend", { |
| 81 | * command: "npm run dev", |
| 82 | * }); |
| 83 | * yield* Console.log(dev.url); // e.g. "http://localhost:5173" |
| 84 | * ``` |
| 85 | * |
| 86 | * ### Requiring a URL |
| 87 | * By default the resource waits 5 seconds for a URL and settles with |
| 88 | * `url: undefined` if none appears. Set `waitForUrl` when downstream |
| 89 | * resources depend on the URL: the resource is ready only once the |
| 90 | * command prints one, however long the server takes to start, and fails |
| 91 | * if the command exits first. |
| 92 | * |
| 93 | * **Example:** Wait for a slow server's URL |
| 94 | * ```typescript |
| 95 | * const engine = yield* Dev("Engine", { |
| 96 | * command: "rivet-engine start", |
| 97 | * waitForUrl: true, |
| 98 | * }); |
| 99 | * ``` |
| 100 | * |
| 101 | * ### Known Port |
| 102 | * When you choose the port, pass it as `port`: Alchemy sets `PORT` to it |
| 103 | * and the resource is ready once the port accepts a connection, with no |
| 104 | * output scanning. This suits servers that print no URL, and wrappers |
| 105 | * that route the port elsewhere. |
| 106 | * |
| 107 | * **Example:** Serve on port 4000 |
| 108 | * ```typescript |
| 109 | * const api = yield* Dev("Api", { |
| 110 | * command: "node server.ts", |
| 111 | * port: 4000, |
| 112 | * }); |
| 113 | * yield* Console.log(api.url); // "http://localhost:4000" |
| 114 | * ``` |
| 115 | * |
| 116 | * ### Working Directory |
| 117 | * Use `cwd` to run the command in a subdirectory — useful in |
| 118 | * monorepos where each package has its own dev server. |
| 119 | * |
| 120 | * **Example:** Monorepo package |
| 121 | * ```typescript |
| 122 | * const dev = yield* Dev("Web", { |
| 123 | * command: "npm run dev", |
| 124 | * cwd: "apps/web", |
| 125 | * }); |
| 126 | * ``` |
| 127 | * |
| 128 | * ### Environment Variables |
| 129 | * Extra environment variables are merged on top of `process.env`. |
| 130 | * Sensitive values can be wrapped in `Redacted` to keep them out |
| 131 | * of logs and state files. |
| 132 | * |
| 133 | * **Example:** Custom port and env |
| 134 | * ```typescript |
| 135 | * const dev = yield* Dev("Api", { |
| 136 | * command: "npm run dev", |
| 137 | * env: { |
| 138 | * PORT: "4000", |
| 139 | * DATABASE_URL: Redacted.make("postgres://..."), |
| 140 | * }, |
| 141 | * }); |
| 142 | * ``` |
| 143 | * |
| 144 | * @resource |
| 145 | */ |
| 146 | export const Dev = Resource<Dev>("Command.Dev"); |
| 147 | |
| 148 | export const DevProvider = () => |
| 149 | ProviderLayer.dual(Dev, { |
| 150 | live: DevProviderLive, |
| 151 | local: DevProviderLocal, |
| 152 | }); |
| 153 | |
| 154 | export const DevProviderLive = () => |
| 155 | Provider.succeed(Dev, { |
| 156 | list: () => Effect.succeed([]), |
| 157 | diff: () => Effect.succeed({ action: "noop" }), |
| 158 | reconcile: () => Effect.succeed({ url: undefined }), |
| 159 | delete: () => Effect.void, |
| 160 | }); |
| 161 | |
| 162 | export const DevProviderLocal = () => |
| 163 | LocalProvider.make( |
| 164 | Dev, |
| 165 | import.meta.resolve(`./Local${moduleExtension(import.meta.url)}`, import.meta.url), |
| 166 | Effect.gen(function* () { |
| 167 | const { spawn } = yield* CommandExecutor; |
| 168 | |
| 169 | return { |
| 170 | // The dev process is spawned into the instance scope the helper |
| 171 | // provides: it keeps running after `start` returns (readiness) and |
| 172 | // is killed when the helper closes the scope on restart/delete. |
| 173 | start: Effect.fn(function* ({ fqn, news: props, invalidate }) { |
| 174 | const { port } = props; |
| 175 | // A restart has already killed the previous process group, so a |
| 176 | // listener now is someone else's (an orphaned server, say), and |
| 177 | // the readiness probe below would mistake it for this command. |
| 178 | if (port !== undefined && (yield* isListening(port))) { |
| 179 | return yield* makeCommandError( |
| 180 | props, |
| 181 | new SystemError({ |
| 182 | _tag: "Busy", |
| 183 | module: "Command", |
| 184 | method: "Dev", |
| 185 | pathOrDescriptor: port, |
| 186 | description: "another process already listens on this port", |
| 187 | }), |
| 188 | ); |
| 189 | } |
| 190 | const child = yield* spawn( |
| 191 | port === undefined ? props : { ...props, env: { ...props.env, PORT: `${port}` } }, |
| 192 | ); |
| 193 | const redactor = makeCommandRedactor(props.env); |
| 194 | // Through the logger, never a raw fd write: the process that owns |
| 195 | // the terminal renders the records and writes them to the run log |
| 196 | // (and a bare write to its stdout would tear the animated region). |
| 197 | const prefixed = yield* makeResourceOutput(fqn); |
| 198 | yield* Effect.addFinalizer(() => |
| 199 | Effect.sync(() => { |
| 200 | prefixed.stdout.flush(); |
| 201 | prefixed.stderr.flush(); |
| 202 | }), |
| 203 | ); |
| 204 | |
| 205 | let buffer = ""; |
| 206 | // A non-local URL seen so far (docs link, error page, update notice, |
| 207 | // …). Held as a fallback so that if the dev server never prints a |
| 208 | // localhost/IP URL we still surface something, but a localhost URL |
| 209 | // always wins if one shows up. See issue #695. |
| 210 | let fallbackUrl: string | undefined; |
| 211 | const deferred = yield* Deferred.make<string>(); |
| 212 | // Done when the first URL of any kind appears. |
| 213 | const anyUrl = yield* Deferred.make<void>(); |
| 214 | |
| 215 | const mirror = (sink: "stdout" | "stderr") => |
| 216 | child[sink].pipe( |
| 217 | Stream.decodeText, |
| 218 | redactor.stream, |
| 219 | Stream.tap((text) => Effect.sync(() => prefixed[sink].push(text))), |
| 220 | Stream.tap((text) => |
| 221 | Effect.sync(() => { |
| 222 | if (Deferred.isDoneUnsafe(deferred)) return; |
| 223 | buffer += text; |
| 224 | const url = extractUrl(buffer); |
| 225 | if (!url) return; |
| 226 | Deferred.doneUnsafe(anyUrl, Effect.void); |
| 227 | if (isLocalUrl(url)) { |
| 228 | // The dev server's own address — resolve immediately. |
| 229 | Deferred.doneUnsafe(deferred, Effect.succeed(url)); |
| 230 | } else { |
| 231 | // Keep scanning: a localhost/IP URL may still appear. |
| 232 | fallbackUrl = url; |
| 233 | } |
| 234 | }), |
| 235 | ), |
| 236 | Stream.runDrain, |
| 237 | Effect.forkScoped, |
| 238 | ); |
| 239 | |
| 240 | yield* mirror("stdout"); |
| 241 | yield* mirror("stderr"); |
| 242 | |
| 243 | // Readiness: a localhost/IP URL appears, or 5 seconds pass and we |
| 244 | // settle with any other URL we saw (`undefined` with none). With |
| 245 | // `waitForUrl`, those 5 seconds start only once some URL appears, |
| 246 | // so the URL is required and there is no deadline: the only other |
| 247 | // way out is the process exiting, which is a failure. With `port`, |
| 248 | // readiness is the port opening instead, again with no deadline. |
| 249 | const awaitLocalUrl = Deferred.await(deferred).pipe( |
| 250 | Effect.timeoutOrElse({ |
| 251 | duration: "5 seconds", |
| 252 | orElse: () => Effect.succeed(fallbackUrl), |
| 253 | }), |
| 254 | ); |
| 255 | const url = yield* Effect.raceAllFirst([ |
| 256 | port !== undefined |
| 257 | ? isListening(port).pipe( |
| 258 | Effect.repeat({ |
| 259 | schedule: Schedule.spaced("100 millis"), |
| 260 | until: (listening) => listening, |
| 261 | }), |
| 262 | Effect.as(`http://localhost:${port}`), |
| 263 | ) |
| 264 | : props.waitForUrl |
| 265 | ? Deferred.await(anyUrl).pipe(Effect.andThen(awaitLocalUrl)) |
| 266 | : awaitLocalUrl, |
| 267 | child.exitCode.pipe( |
| 268 | Effect.mapError((error) => makeCommandError(props, error.reason)), |
| 269 | Effect.flatMap((exitCode) => |
| 270 | makeCommandError(props, new UnexpectedExit({ exitCode, stderr: buffer })), |
| 271 | ), |
| 272 | ), |
| 273 | ]); |
| 274 | |
| 275 | // The process may die on its own after readiness (crash, manual |
| 276 | // kill). Drop it from the running registry so the next plan |
| 277 | // reports `update` and restarts it. |
| 278 | yield* child.exitCode.pipe( |
| 279 | Effect.exit, |
| 280 | Effect.flatMap(() => invalidate), |
| 281 | Effect.forkScoped, |
| 282 | ); |
| 283 | |
| 284 | return { url }; |
| 285 | }), |
| 286 | } satisfies LocalProvider.LocalProviderSpec<Dev>; |
| 287 | }), |
| 288 | ); |
| 289 | |
| 290 | // Matches an http(s) URL whose host is `localhost`, an IPv4 address, or a |
| 291 | // bracketed IPv6 address — i.e. the shape a dev server prints for its own |
| 292 | // local address. Preferred over any other URL a command might print first |
| 293 | // (docs links, error pages, update notices). See issue #695. |
| 294 | const LOCAL_URL_REGEX = |
| 295 | /https?:\/\/(?:localhost|\[[0-9a-fA-F:]+\]|(?:\d{1,3}\.){3}\d{1,3})(?::\d+)?[^\s)\],"'`]*/; |
| 296 | |
| 297 | // Matches the first plain http(s) URL. Stops at whitespace and at a small |
| 298 | // set of punctuation typically used to wrap URLs in log output. |
| 299 | const URL_REGEX = /https?:\/\/[^\s)\],"'`]+/; |
| 300 | |
| 301 | /** |
| 302 | * Extract a URL from `text`, favoring a localhost/IP URL (the dev server's |
| 303 | * own address) over any other URL. Returns the first localhost/IP URL if one |
| 304 | * is present, otherwise the first plain http(s) URL, otherwise `undefined`. |
| 305 | * `Vite`, `Next`, etc. surround the URL with ANSI color codes that would |
| 306 | * otherwise be eaten by the URL regex, so strip them first. |
| 307 | * @internal |
| 308 | */ |
| 309 | export const extractUrl = (text: string) => { |
| 310 | const clean = stripVTControlCharacters(text); |
| 311 | const url = clean.match(LOCAL_URL_REGEX)?.[0] ?? clean.match(URL_REGEX)?.[0]; |
| 312 | // Some dev servers print their *bind* address (Nuxt: `http://0.0.0.0:3000`), |
| 313 | // which is not a connectable host. Normalize the unspecified address to |
| 314 | // `localhost` so consumers of `url` — browser links, Router dev routing, |
| 315 | // the emulated CloudFront edge dialing the origin — can actually reach it. |
| 316 | return url?.replace( |
| 317 | /^(https?:\/\/)(?:0\.0\.0\.0|\[::\]|\[0+:0+:0+:0+:0+:0+:0+:0+\])(?=[:/]|$)/, |
| 318 | "$1localhost", |
| 319 | ); |
| 320 | }; |
| 321 | |
| 322 | const isLocalUrl = (url: string) => LOCAL_URL_REGEX.test(url); |
| 323 | |
| 324 | // Whether a TCP connection to `port` succeeds on either loopback address: |
| 325 | // a server bound to `localhost` may listen on only one of them. |
| 326 | const isListening = (port: number) => |
| 327 | Effect.all([connects("127.0.0.1", port), connects("::1", port)], { |
| 328 | concurrency: "unbounded", |
| 329 | }).pipe(Effect.map(([ipv4, ipv6]) => ipv4 || ipv6)); |
| 330 | |
| 331 | const connects = (host: string, port: number) => |
| 332 | Effect.callback<boolean>((resume) => { |
| 333 | const socket = NodeNet.connect({ host, port }); |
| 334 | socket.once("connect", () => { |
| 335 | socket.destroy(); |
| 336 | resume(Effect.succeed(true)); |
| 337 | }); |
| 338 | socket.once("error", () => resume(Effect.succeed(false))); |
| 339 | return Effect.sync(() => socket.destroy()); |
| 340 | }); |