The best way to control Claude Code, Codex and more from any computer or phone

main
ts 142 lines 6.08 KB
Raw
1 import * as NodeNet from "node:net";
2 import * as Data from "effect/Data";
3 import * as Effect from "effect/Effect";
4 import * as Result from "effect/Result";
5 import * as SemVer from "effect/SemVer";
6 import * as SemVerRange from "effect/SemVerRange";
7
8 export class NodeOperationFailed extends Data.TaggedError("NodeOperationFailed")<{
9 readonly message: string;
10 readonly cause?: unknown;
11 }> {}
12
13 /**
14 * The process's working directory, captured ONCE at module load.
15 *
16 * Relative user paths (Vite roots, asset directories) must resolve against
17 * this instead of a live `process.cwd()` read: third-party code sharing the
18 * process can change the working directory transiently — most notably
19 * cross-spawn, which `process.chdir`s into a spawn's `cwd` to resolve its
20 * binary on PATH and then chdirs back. A live read racing that window
21 * resolves against an unrelated directory. (`State/LocalState.ts` anchors
22 * the state tree the same way, for the same reason.)
23 */
24 export const initialCwd: string = process.cwd();
25
26 /**
27 * The extension of alchemy's own modules next to `importMetaUrl`: `.ts`
28 * when running from `src/` (Bun, or Node under the dev loader), `.js`
29 * from the compiled `lib/`. The dev loader namespaces file URLs with a
30 * query, so only the pathname is consulted.
31 */
32 export const moduleExtension = (importMetaUrl: string) =>
33 new URL(importMetaUrl).pathname.endsWith(".ts") ? ".ts" : ".js";
34
35 /**
36 * Opt out of cross-spawn's temporary `process.chdir` dance.
37 *
38 * cross-spawn (bundled inside vite, wrangler, next, tinyexec, playwright,
39 * tsx, prisma, …) resolves a spawn's binary by `process.chdir`ing the
40 * WHOLE parent process into the spawn's `cwd`, calling `which.sync`, and
41 * chdiring back. In an alchemy process — which runs many resource builds
42 * and hashers concurrently on one event loop — every fiber that touches a
43 * relative path can race that window and resolve against an unrelated
44 * directory.
45 *
46 * `process.chdir.disabled = true` is NODE'S OWN convention: Node sets it
47 * on `process.chdir` inside worker threads (where chdir is forbidden),
48 * and cross-spawn checks it to skip the dance. Setting it on the main
49 * thread opts us into the exact mode every cross-spawn copy already runs
50 * in inside jest/vitest/playwright workers daily — not an untested path.
51 * The flag is purely advisory: `process.chdir` itself keeps working, and
52 * an audit of the dependency tree shows the only readers are bundled
53 * cross-spawn copies; nothing else writes or consults it.
54 *
55 * Behavior delta: a spawn combining a custom `cwd` with a command that is
56 * neither absolute nor on PATH (e.g. `./scripts/build.sh`). POSIX still
57 * works (cross-spawn falls back to the raw command; the OS resolves it in
58 * the child's cwd). On Windows that shape can fail to resolve — the same
59 * limitation those tools already have inside worker threads. Everything
60 * alchemy and its toolchains spawn is absolute or on PATH, and `Command`
61 * resources use effect's ChildProcess (plain spawn, no cross-spawn).
62 */
63 export const disableCrossSpawnChdir = (): void => {
64 (process.chdir as { disabled?: boolean }).disabled = true;
65 };
66
67 /**
68 * Node arguments that install alchemy's Oxc loader in a child process, the
69 * same way `bin/cli.js` installs it for the CLI itself. Every `.ts`/`.tsx`
70 * a Node process loads — alchemy's own source in a checkout, the user's
71 * stack everywhere — goes through it; nothing relies on Node's built-in
72 * TypeScript support (strip-only, and Node 26 removed the transform flag).
73 *
74 * A `.ts` entry means a checkout: `bin/register-dev-mode.js` adds the
75 * src-condition resolution for workspace packages on top of the loader.
76 * A `.js` entry means a published install: `bin/register-oxc.js` is the
77 * loader alone.
78 */
79 export const nodeLoaderArgs = (entry: string): string[] => [
80 "--import",
81 import.meta.resolve(
82 /\.[cm]?tsx?$/.test(entry) ? "../../bin/register-dev-mode.js" : "../../bin/register-oxc.js",
83 ),
84 ];
85
86 /**
87 * Whether this Node supports the synchronous in-thread loader hooks
88 * (`module.registerHooks`) the way `bin/register-dev-mode.js` needs them.
89 * Before 24.5 (nodejs/node#59011) a resolve hook's `conditions` were
90 * ignored, so the `bun` condition never reached Node's resolver; before
91 * 24.11.1 and 25.1 (nodejs/node#59929) an imported CommonJS module could
92 * not `require()` TypeScript (see `importedCommonJsNeedsNodeLoader` in
93 * node-utils' loader/hooks.ts).
94 *
95 * This is THE capability gate for running the CLI from source under
96 * node: with the hooks installed, the Oxc loader handles every `.ts`/`.tsx`
97 * file regardless of Node's own TypeScript support.
98 *
99 * `bin/cli.js` mirrors this predicate inline — it must run under plain node
100 * before any `.ts` can load. Keep the two in sync.
101 */
102 export const isRegisterHooksSupported = (version = process.versions.node): boolean => {
103 const parsed = Result.getOrUndefined(SemVer.parse(version));
104 return (
105 parsed !== undefined && SemVerRange.matches(REGISTER_HOOKS, parsed, { includePrerelease: true })
106 );
107 };
108
109 const REGISTER_HOOKS = SemVerRange.parseUnsafe(
110 ">=22.22.3 <23.0.0-0 || >=24.11.1 <25.0.0-0 || >=25.1.0",
111 );
112
113 /**
114 * Ask the OS for an unused TCP port, release it, and return its number.
115 *
116 * The port is only available, not reserved: another process can claim it
117 * before the caller binds. Callers should keep the gap short and still handle
118 * `EADDRINUSE`.
119 */
120 export const findAvailablePort = (host = "127.0.0.1") =>
121 Effect.callback<number, Error>((resume) => {
122 const server = NodeNet.createServer();
123 server.unref();
124 server.once("error", (error) => resume(Effect.fail(error)));
125 server.listen(0, host, () => {
126 const address = server.address();
127 const port = typeof address === "object" && address !== null ? address.port : undefined;
128 server.close((error) => {
129 if (error) {
130 resume(Effect.fail(error));
131 } else if (port !== undefined) {
132 resume(Effect.succeed(port));
133 } else {
134 resume(
135 Effect.fail(
136 new NodeOperationFailed({ message: "Failed to allocate an available port" }),
137 ),
138 );
139 }
140 });
141 });
142 });