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

main
ts 360 lines 13.4 KB
Raw
1 // Shared build plumbing for the workspace packages under packages/.
2 //
3 // Each package's `scripts/build.ts` (its `build:package` script) declares its
4 // options and compile steps and hands them to `build`, which:
5 //
6 // 1. Generates `publishConfig.exports` from the package's source `exports`.
7 // In the workspace, `exports` points straight at `src/*.ts` so every
8 // consumer runs from source without a build. Published tarballs swap in
9 // `publishConfig.exports`, which resolves to the compiled output and keeps
10 // the `bun` (and, where enabled, `worker`) conditions on source.
11 // 2. Copies the repository's LICENSE, NOTICE and, where needed,
12 // THIRD_PARTY_LICENSES.md and README.md into the package.
13 // 3. Runs the compile steps in order.
14 // 4. For packages consumed from their build output, writes
15 // `<outDir>/.build-stamp`, which `ensure-built.ts` compares against the
16 // sources to decide whether a rebuild is needed.
17 //
18 // Every phase is timed. Each timing is printed as it finishes, prefixed with
19 // the package name, and the build's timings are appended to the package's
20 // `.cache/build-timings.jsonl`.
21 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
22 import * as NodeServices from "@effect/platform-node/NodeServices";
23 import * as Console from "effect/Console";
24 import * as Effect from "effect/Effect";
25 import * as FileSystem from "effect/FileSystem";
26 import * as Path from "effect/Path";
27 import { ChildProcess, CommandLine } from "effect/process";
28 import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
29
30 type Services = FileSystem.FileSystem | Path.Path | ChildProcessSpawner;
31
32 /** A named compile step, run with the package directory as cwd. */
33 export interface Step {
34 readonly name: string;
35 readonly run: (packageDirectory: string) => Effect.Effect<void, unknown, Services>;
36 }
37
38 export interface BuildOptions {
39 /** Generate `publishConfig.exports` from `exports`. */
40 readonly exports?: {
41 /**
42 * Also generate the workspace `exports` from `src/`: the root, one entry
43 * per directory index (`./S3` → `./src/S3/index.ts`), the `sourceOnly`
44 * subpaths, and `./*` for every other file. Published packages block
45 * every `internal/` directory.
46 */
47 readonly generate?: boolean;
48 /** Add a `worker` condition on source for Worker bundlers. */
49 readonly worker?: boolean;
50 /** Subpaths that resolve to source in every condition. */
51 readonly sourceOnly?: ReadonlyArray<string>;
52 };
53 /** Copy THIRD_PARTY_LICENSES.md into the package. */
54 readonly thirdPartyLicenses?: boolean;
55 /** Copy README.md into the package. */
56 readonly readme?: boolean;
57 /**
58 * Output directory consumed from its build output in the workspace. A
59 * successful build writes its `.build-stamp` (see ensure-built.ts).
60 */
61 readonly stamp?: string;
62 readonly steps: ReadonlyArray<Step>;
63 }
64
65 /** File recording a successful build inside a stamped output directory. */
66 export const stampFile = ".build-stamp";
67
68 const workspaceRoot = Effect.gen(function* () {
69 const path = yield* Path.Path;
70 return path.resolve(import.meta.dirname, "..");
71 });
72
73 /** Give a step a readable name for the timing logs. */
74 export const named = (name: string, step: Step): Step => ({ ...step, name });
75
76 /**
77 * Build a command that runs on every platform. node_modules/.bin entries and
78 * pnpm are `.cmd` shims on Windows, which only a shell can run, and a shell
79 * takes one script, so the arguments are joined into it there.
80 */
81 export const command = Effect.fn(function* (
82 bin: string,
83 args: ReadonlyArray<string>,
84 options: ChildProcess.CommandOptions,
85 ) {
86 if (process.platform !== "win32") return ChildProcess.make(bin, args, options);
87 const script = yield* Effect.fromResult(CommandLine.join([bin, ...args], { format: "windows" }));
88 return ChildProcess.make(script, [], { ...options, shell: true });
89 });
90
91 /** Run a command; fails when it exits non-zero. */
92 export const exec = (bin: string, ...args: Array<string>): Step => ({
93 name: [bin, ...args].join(" "),
94 run: Effect.fn(function* (packageDirectory) {
95 const spawner = yield* ChildProcessSpawner;
96 const exitCode = yield* spawner.exitCode(
97 yield* command(bin, args, {
98 cwd: packageDirectory,
99 stdin: "inherit",
100 stdout: "inherit",
101 stderr: "inherit",
102 }),
103 );
104 if (exitCode !== 0) {
105 return yield* Effect.fail(new Error(`${bin} exited with code ${exitCode}`));
106 }
107 }),
108 });
109
110 /**
111 * Run the TypeScript compiler: tsrs where it ships a native binary, `tsc`
112 * elsewhere (Windows, Intel macOS).
113 */
114 export const typescript = (...args: Array<string>): Step =>
115 exec(
116 ["darwin-arm64", "linux-x64", "linux-arm64"].includes(`${process.platform}-${process.arch}`)
117 ? "tsrs"
118 : "tsc",
119 ...args,
120 );
121
122 /** Copy a file, paths relative to the package directory. */
123 export const copy = (from: string, to: string): Step => ({
124 name: `copy ${from} → ${to}`,
125 run: Effect.fn(function* (packageDirectory) {
126 const fs = yield* FileSystem.FileSystem;
127 const path = yield* Path.Path;
128 yield* fs.copyFile(path.join(packageDirectory, from), path.join(packageDirectory, to));
129 }),
130 });
131
132 /** Directories under `src/`, relative to it, skipping `internal/` trees. */
133 const sourceDirectories = Effect.fn(function* (sourceDirectory: string) {
134 const fs = yield* FileSystem.FileSystem;
135 const path = yield* Path.Path;
136 const entries = yield* fs.readDirectory(sourceDirectory, { recursive: true });
137 const directories: Array<string> = [];
138 for (const entry of entries.sort()) {
139 const info = yield* fs.stat(path.join(sourceDirectory, entry));
140 if (info.type === "Directory") directories.push(entry.split(path.sep).join("/"));
141 }
142 return directories;
143 });
144
145 const isInternal = (directory: string) => directory.split("/").includes("internal");
146
147 const generateExports = Effect.fn(function* (
148 packageDirectory: string,
149 options: NonNullable<BuildOptions["exports"]>,
150 ) {
151 const fs = yield* FileSystem.FileSystem;
152 const path = yield* Path.Path;
153 const sourceDirectory = path.join(packageDirectory, "src");
154 const directories = yield* sourceDirectories(sourceDirectory);
155
156 const indexes: Array<string> = [];
157 for (const directory of directories) {
158 if (isInternal(directory)) continue;
159 if (yield* fs.exists(path.join(sourceDirectory, directory, "index.ts"))) {
160 indexes.push(directory);
161 }
162 }
163
164 return {
165 ...((yield* fs.exists(path.join(sourceDirectory, "index.ts")))
166 ? { ".": "./src/index.ts" }
167 : {}),
168 ...Object.fromEntries(
169 (options.sourceOnly ?? []).map((subpath) => [subpath, `./src/${subpath.slice(2)}.ts`]),
170 ),
171 ...Object.fromEntries(
172 indexes
173 .sort((a, b) => a.localeCompare(b))
174 .map((directory) => [`./${directory}`, `./src/${directory}/index.ts`]),
175 ),
176 "./*": "./src/*.ts",
177 "./package.json": "./package.json",
178 } as Record<string, string | null>;
179 });
180
181 /**
182 * `null` entries blocking everything named `internal` from the published
183 * package: each `internal/` directory, a root `internal.ts` (`./internal`),
184 * and `internal.ts` at any depth below it (one pattern key ending in
185 * `/internal`, which outranks `./*`).
186 */
187 const internalBlocks = Effect.fn(function* (packageDirectory: string) {
188 const fs = yield* FileSystem.FileSystem;
189 const path = yield* Path.Path;
190 const sourceDirectory = path.join(packageDirectory, "src");
191 const directories = yield* sourceDirectories(sourceDirectory);
192 const files = (yield* fs.readDirectory(sourceDirectory, { recursive: true })).map((file) =>
193 file.split(path.sep).join("/"),
194 );
195 return {
196 ...Object.fromEntries(
197 directories
198 .filter((directory) => directory.split("/").at(-1) === "internal")
199 .filter((directory) => !isInternal(directory.split("/").slice(0, -1).join("/")))
200 .map((directory) => [`./${directory}/*`, null]),
201 ),
202 ...(files.includes("internal.ts") ? { "./internal": null } : {}),
203 ...(files.some(
204 (file) => file.endsWith("/internal.ts") && !isInternal(file.slice(0, file.lastIndexOf("/"))),
205 )
206 ? { "./*/internal": null }
207 : {}),
208 };
209 });
210
211 const syncPublishExports = Effect.fn(function* (
212 packageDirectory: string,
213 options: NonNullable<BuildOptions["exports"]>,
214 ) {
215 const fs = yield* FileSystem.FileSystem;
216 const path = yield* Path.Path;
217
218 const packageJsonPath = path.join(packageDirectory, "package.json");
219 const packageJson = JSON.parse(yield* fs.readFileString(packageJsonPath)) as {
220 exports: Record<string, string | null>;
221 publishConfig?: Record<string, unknown>;
222 };
223 if (options.generate) {
224 packageJson.exports = yield* generateExports(packageDirectory, options);
225 }
226 const tsconfig = JSON.parse(
227 yield* fs.readFileString(path.join(packageDirectory, "tsconfig.json")),
228 ) as { compilerOptions: { outDir: string } };
229 const outDir = `./${path.normalize(tsconfig.compilerOptions.outDir)}/`;
230
231 const exports = Object.fromEntries(
232 Object.entries(packageJson.exports).map(([subpath, source]) => {
233 // Non-source entries (bin scripts, package.json) publish as-is.
234 if (source === null || !source.startsWith("./src/")) {
235 return [subpath, source];
236 }
237 if (options.sourceOnly?.includes(subpath)) {
238 return [subpath, { types: source, bun: source, default: source }];
239 }
240
241 const output = source.replace(/^\.\/src\//, outDir);
242 return [
243 subpath,
244 {
245 types: output.replace(/\.tsx?$/, ".d.ts"),
246 bun: source,
247 ...(options.worker ? { worker: source } : {}),
248 default: output.replace(/\.tsx?$/, ".js"),
249 },
250 ];
251 }),
252 );
253
254 // Blocks go just before `./*` so the published map reads top to bottom.
255 const blocks = options.generate ? yield* internalBlocks(packageDirectory) : {};
256 const published = Object.fromEntries(
257 Object.entries(exports).flatMap((entry) =>
258 entry[0] === "./*" ? [...Object.entries(blocks), entry] : [entry],
259 ),
260 );
261
262 yield* fs.writeFileString(
263 packageJsonPath,
264 JSON.stringify(
265 { ...packageJson, publishConfig: { ...packageJson.publishConfig, exports: published } },
266 null,
267 2,
268 ) + "\n",
269 );
270 });
271
272 const copyRepositoryFiles = Effect.fn(function* (packageDirectory: string, options: BuildOptions) {
273 const fs = yield* FileSystem.FileSystem;
274 const path = yield* Path.Path;
275 const root = yield* workspaceRoot;
276
277 const files = [
278 "LICENSE",
279 "NOTICE",
280 ...(options.thirdPartyLicenses ? ["THIRD_PARTY_LICENSES.md"] : []),
281 ...(options.readme ? ["README.md"] : []),
282 ];
283 yield* Effect.forEach(files, (file) =>
284 fs.copyFile(path.join(root, file), path.join(packageDirectory, file)),
285 );
286 });
287
288 const writeStamp = Effect.fn(function* (packageDirectory: string, outDir: string) {
289 const fs = yield* FileSystem.FileSystem;
290 const path = yield* Path.Path;
291 const directory = path.join(packageDirectory, outDir);
292 yield* fs.makeDirectory(directory, { recursive: true });
293 const at = yield* Effect.sync(() => new Date().toISOString());
294 yield* fs.writeFileString(path.join(directory, stampFile), `${at}\n`);
295 });
296
297 const now = Effect.sync(() => Date.now());
298 const formatSeconds = (ms: number) => `${(ms / 1000).toFixed(2)}s`;
299
300 /** Build the package whose `scripts/` directory is `scriptsDirectory` (pass `import.meta.dirname`). */
301 export const build = (scriptsDirectory: string, options: BuildOptions) =>
302 Effect.gen(function* () {
303 const fs = yield* FileSystem.FileSystem;
304 const path = yield* Path.Path;
305 const packageDirectory = path.resolve(scriptsDirectory, "..");
306 const { name, version } = JSON.parse(
307 yield* fs.readFileString(path.join(packageDirectory, "package.json")),
308 ) as { name: string; version: string };
309
310 // `scripts/sync-exports.ts` regenerates the export maps without building.
311 if (process.env.PACKAGE_BUILD_EXPORTS_ONLY === "1") {
312 if (options.exports) yield* syncPublishExports(packageDirectory, options.exports);
313 return;
314 }
315
316 const phases: Array<Step> = [
317 {
318 name: "sync package files",
319 run: Effect.fn(function* (directory) {
320 if (options.exports) yield* syncPublishExports(directory, options.exports);
321 yield* copyRepositoryFiles(directory, options);
322 }),
323 },
324 ...options.steps,
325 ...(options.stamp
326 ? [
327 {
328 name: "write build stamp",
329 run: (directory: string) => writeStamp(directory, options.stamp!),
330 },
331 ]
332 : []),
333 ];
334
335 // Each line names its package: several packages build in parallel and
336 // their output interleaves.
337 const log = (message: string) => Console.log(`[build ${name}] ${message}`);
338
339 yield* log(`start (v${version})`);
340 const startedAt = yield* now;
341 const timings: Array<{ name: string; ms: number }> = [];
342 for (const phase of phases) {
343 const phaseStartedAt = yield* now;
344 yield* phase.run(packageDirectory);
345 const ms = (yield* now) - phaseStartedAt;
346 timings.push({ name: phase.name, ms });
347 yield* log(`${phase.name}: ${formatSeconds(ms)}`);
348 }
349 const total = (yield* now) - startedAt;
350 yield* log(`done in ${formatSeconds(total)}`);
351
352 const cacheDirectory = path.join(packageDirectory, ".cache");
353 yield* fs.makeDirectory(cacheDirectory, { recursive: true });
354 yield* fs.writeFileString(
355 path.join(cacheDirectory, "build-timings.jsonl"),
356 JSON.stringify({ at: new Date(startedAt).toISOString(), version, total, steps: timings }) +
357 "\n",
358 { flag: "a" },
359 );
360 }).pipe(Effect.provide(NodeServices.layer), NodeRuntime.runMain);