Skip to content

Commit ab3c776

Browse files
fix(cli): two builds of an unchanged app ship one legacy runtime module, so its hashed name and runtimeModule ref stop changing (#26547)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1X7csHsNjL2aQgnCaNu1p3hu)_ Fixes #26478 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么:** `os build` 打包旧版运行时模块时,临时入口不再以「进程号+时间戳」命名写到配置旁边,而是以固定名经 esbuild stdin 传入;模块里的路径一律相对配置所在目录。 - **为什么改:** 同一个应用每次重建都会产出新的 `objectstack-runtime.HASH.mjs` 文件名和新的 `runtimeModule` 引用,缓存与部署 diff 永远不收敛(#7651 当年缺的复现就是这个)。 - **风险与回滚:** 风险低,只改一个函数的 esbuild 入参,模块导出与行为不变;回滚即 revert 本 PR。 - **先看:** `packages/cli/src/utils/build-runtime.ts`(`buildRuntimeBundle` 里 `esbuild.build` 的 `stdin` 与 `absWorkingDir` 两处);`packages/cli/test/build-runtime-reproducible.test.ts`。 - **两分钟验证:** `pnpm --filter @objectstack/cli exec vitest run --project unit test/build-runtime-reproducible.test.ts`,预期 3 个用例全绿;在 main 上同一命令红 2 个(文件名不同、sourcemap 带临时目录与进程号)。 - **需要你做的:** 无,席位落地。 ## What changes `buildRuntimeBundle` (`packages/cli/src/utils/build-runtime.ts`) used to write its generated esbuild entry beside the config as `.objectstack-runtime.entry.PID.TIMESTAMP.mjs`. esbuild prints every input's path into the output, once as a path comment above that input's code and once in the inline sourcemap's `sources`, and the module's file name is `sha256` over that output. So `process.pid` and `Date.now()` reached the shipped bytes and the name, and no two builds could share a name. Now: - The entry is handed to esbuild as `stdin` (`contents` = the same generated source, `resolveDir` = the config's directory, `sourcefile` = the fixed `.objectstack-runtime.entry.mjs`). Nothing is written next to the config, so concurrent builds share no file, and the `unlinkSync` cleanup paths are gone. - `absWorkingDir` is the config's directory. The audit the order asked for (any other per-run value reaching the bundle) found one more of the same mechanism: every path esbuild prints was relative to the process cwd, so the same app built from another directory (`os build path/to/objectstack.config.ts`) or another checkout location shipped different bytes and a different name. Paths are now relative to the config, so they read `objectstack.config.ts`, `slug.ts`, `.objectstack-runtime.entry.mjs`. Nothing else per-run reaches the module. Read on a real bundle: the banner is a constant; `meta.builtAt` is emitted as the source text `new Date().toISOString()`, evaluated when the module is imported, not a build-time value; `LOCATORS` and `refCount` derive from the config; `sourcesContent` carries file contents only; packages are external, so no `node_modules` path is printed. The suggested route's example (a fixed name inside a per-build temp directory) was not taken: a `mkdtemp` directory name is itself random and esbuild would print it into the same comment and sourcemap, so the bytes would still differ. `stdin` gives a stable name with no directory at all. ## Why Two builds of an unchanged app must give a byte-identical bundle, the same file name and the same `runtimeModule` ref in `dist/objectstack.json` (triage ruling on #26478). Otherwise any cache or CDN keyed on the name is busted every build and every deploy diff shows the artifact as changed. ## Tests New `packages/cli/test/build-runtime-reproducible.test.ts`, `unit` tier: it calls `buildRuntimeBundle` in-process (no CLI spawn) on a fixture whose hook calls a helper imported from another module, so the handler is bundled. 1. Two builds into one `dist/` give the same `outputFileName`, the same `hash`, byte-identical files, and only one file in `dist/`. 2. The inline sourcemap's `sources` are exactly the three config-relative names, and the module text does not contain the fixture's `mkdtemp` directory name. 3. Nothing is left beside the config, and the module imported back serves the hook and runs it (`' Hello World '` becomes `'hello world'`), which shows the `stdin` entry still resolves the config and its transitive import. Red first on the base (`c7d6ca8e`, test committed alone as `c1c07c89`): cases 1 and 2 fail, case 3 passes. <details><summary>Red on the base, green on the fix, and the ablation</summary> Base, `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 test/build-runtime-reproducible.test.ts` under the verify lock: ```text × two builds of an unchanged app give byte-identical modules under one name AssertionError: expected 'objectstack-runtime.0d8a62ba362af40a.…' to be 'objectstack-runtime.0509e52d02fdce77.…' × the module names its inputs relative to the config, never a per-run or machine-local path + "../../../../../tmp/os-build-runtime-reproducible-fADw6M/app/.objectstack-runtime.entry.1505.1793084124288.mjs", + "../../../../../tmp/os-build-runtime-reproducible-fADw6M/app/objectstack.config.ts", + "../../../../../tmp/os-build-runtime-reproducible-fADw6M/app/slug.ts", Tests 2 failed | 1 passed (3) os-verify-lock: VERDICT command-exit 1 ``` Fix (`37a263c1`): `Tests 3 passed (3)`, `VERDICT command-exit 0`. Ablation of the `absWorkingDir` line through `scripts/ablation-replace.mjs` (anchor 1 → 0, blob `36fb893d` → `d6c7a478`): case 2 red with the cwd-relative `sources` above (now with the fixed entry name), cases 1 and 3 green; restored to blob `36fb893d` = HEAD, `git diff HEAD` empty. The test imports `../src/`, so no `dist/` rebuild sits between the edit and the run. Outside the test, the same app built from two different cwds through `tsx` produced `objectstack-runtime.29956dd5d3b128f6.mjs` both times. </details> ## Acceptance notes - The test is in-process, so it does not spawn `os build` at all; `compile.ts` hands `outputFileName` to `runtimeModule` unchanged (`finalBundle.runtimeModule = ./FILE`), so the artifact ref follows the name. - Open PRs on this file: a search of open PRs for `build-runtime` returned 13 hits, none of which is a CLI build change. ## Verification All local readings at head `c914e2e6`. - `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2` (whole `unit` tier): 336 files passed, 2 failed only because `packages/cli` itself was not yet built (`packages/cli is not built (./dist/index.js is absent)`). After `pnpm --filter @objectstack/cli build`, those two (`published-subpath-console.pin`, `published-subpath-hook-body.pin`) pass: 29/29. - `pnpm --filter @objectstack/cli typecheck` (`tsc --noEmit && pnpm check:test-typecheck`): exit 0. - `eslint --no-inline-config` on the two touched source files: exit 0. - The `integration` tier is declared to CI: the diff touches no spawn entry and no integration-tier file. - Gates: `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 61 families; 60 ran green, and `--ran` reconciles `61 derived, 60 run, 1 NOT-MEASURED, 0 UNRUN`. <details><summary>Gate readings</summary> - `pnpm check:dual-build-cjs-loads`: NOT MEASURED, exit 3 `PREREQUISITE NOT MET` (it reads every package's `dist/`, and only the CLI's closure was built). CI's Lint and Repo Gates runs it. - Four gates first exited 3 because they ran before the CLI build or on a shallow clone, then went green on a re-run after `pnpm --filter @objectstack/cli build` and `git fetch --unshallow`: `check-plugin-teardown-shape.mjs --self-test`, `check:i18n`, `check:i18n-coverage`, `check:i18n-walk-parity`. - Every other derived family: exit 0. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (No `packages/spec` change.) - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes (eslint on the touched files). - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset (`@objectstack/cli` patch). - [x] 6. `packages/spec` touched: n/a. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01FEkQ5ozQ2e4NBxHuYv9Wph --- _Generated by [Claude Code](https://claude.ai/code/session_01FEkQ5ozQ2e4NBxHuYv9Wph)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2f21b48 commit ab3c776

3 files changed

Lines changed: 159 additions & 26 deletions

File tree

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/cli': patch
3+
---
4+
5+
fix(cli): `os build` writes the same legacy runtime module for an unchanged app, so its content-hashed name and the artifact's `runtimeModule` ref stop changing on every rebuild
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The legacy runtime module (`dist/objectstack-runtime.HASH.mjs`) is named by a hash of its bytes, but those bytes used to differ on every build. The build wrote a temporary esbuild entry beside the config under a name made of the process id and the current time, and esbuild prints each input's path into the module, as a comment above its code and in the inline sourcemap. Those paths were also relative to the directory `os build` ran from. So every rebuild of an unchanged app shipped a new file name and a new `runtimeModule` ref in `dist/objectstack.json`, and building the same app from another directory or another checkout did too.
11+
12+
The entry is now handed to esbuild in memory under one fixed name, and every path in the module is relative to the config's own directory. Two builds of an unchanged app now ship byte-identical modules under one name, wherever they run. No temporary file is written next to the config any more. The module's exports and behaviour are unchanged.

‎packages/cli/src/utils/build-runtime.ts‎

Lines changed: 28 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -198,43 +198,45 @@ export async function buildRuntimeBundle(opts: BuildRuntimeOptions): Promise<Bui
198198
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
199199

200200
const entryDir = dirname(sourceConfigPath);
201-
const entryPath = resolvePath(
202-
entryDir,
203-
`.${baseName}.entry.${process.pid}.${Date.now()}.mjs`,
204-
);
205-
writeFileSync(entryPath, generateEntrySource(sourceConfigPath, locators, entryDir));
206201

207202
let esbuild: typeof import('esbuild');
208203
try {
209204
esbuild = await import('esbuild');
210205
} catch (err) {
211-
try { unlinkSync(entryPath); } catch { /* noop */ }
212206
throw new Error(
213207
`[build-runtime] esbuild is required to bundle declarative handlers but is not installed: ${(err as Error).message}`,
214208
);
215209
}
216210

217211
// Bundle to an in-memory buffer first so we can hash, then rename.
218-
let result;
219-
try {
220-
result = await esbuild.build({
221-
entryPoints: [entryPath],
222-
bundle: true,
223-
format: 'esm',
224-
platform: 'node',
225-
target: 'node18',
226-
write: false,
227-
sourcemap: 'inline',
228-
packages: 'external',
229-
logLevel: 'silent',
230-
legalComments: 'none',
231-
resolveExtensions: ['.ts', '.tsx', '.mjs', '.js', '.cjs', '.json'],
232-
loader: { '.ts': 'ts', '.tsx': 'tsx' },
233-
banner: { js: '// @generated by @objectstack/cli — do not edit.' },
234-
});
235-
} finally {
236-
try { unlinkSync(entryPath); } catch { /* noop */ }
237-
}
212+
//
213+
// The name is a hash of these bytes, so nothing that varies between two
214+
// builds of the same app may reach them. esbuild prints every input's path
215+
// into the output, as a `// path` comment and in the inline sourcemap's
216+
// `sources`. So the entry goes in as `stdin` under one fixed name (no file on
217+
// disk, so concurrent builds share nothing), and paths are relative to the
218+
// config's directory rather than to the process's cwd.
219+
const result = await esbuild.build({
220+
stdin: {
221+
contents: generateEntrySource(sourceConfigPath, locators, entryDir),
222+
resolveDir: entryDir,
223+
sourcefile: `.${baseName}.entry.mjs`,
224+
loader: 'js',
225+
},
226+
absWorkingDir: entryDir,
227+
bundle: true,
228+
format: 'esm',
229+
platform: 'node',
230+
target: 'node18',
231+
write: false,
232+
sourcemap: 'inline',
233+
packages: 'external',
234+
logLevel: 'silent',
235+
legalComments: 'none',
236+
resolveExtensions: ['.ts', '.tsx', '.mjs', '.js', '.cjs', '.json'],
237+
loader: { '.ts': 'ts', '.tsx': 'tsx' },
238+
banner: { js: '// @generated by @objectstack/cli — do not edit.' },
239+
});
238240

239241
const out = result.outputFiles?.[0];
240242
if (!out) throw new Error('[build-runtime] esbuild produced no output');
Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* Two builds of an unchanged app give the same legacy runtime module: the same
5+
* bytes, so the same content-hashed name (`objectstack-runtime.HASH.mjs`) and
6+
* the same `runtimeModule` ref in `dist/objectstack.json`.
7+
*
8+
* ## The defect, measured before the fix
9+
*
10+
* `buildRuntimeBundle` wrote its generated esbuild entry beside the config as
11+
* `.objectstack-runtime.entry.PID.TIMESTAMP.mjs`. esbuild prints every input's
12+
* path into the bundle, as a `// path` comment above its code and in the inline
13+
* sourcemap's `sources`, so the pid and `Date.now()` reached the shipped bytes
14+
* and the name hashed from them: every rebuild named a new file. Those paths
15+
* were also relative to the process's cwd, so the same app built from another
16+
* directory or another checkout shipped different bytes too.
17+
*
18+
* The entry is now handed to esbuild as `stdin` under one fixed name, and paths
19+
* are made relative to the config's own directory. This file pins the result
20+
* in-process (no CLI spawn): `compile.ts` hands the module's file name to the
21+
* artifact unchanged.
22+
*/
23+
24+
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
25+
import { mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
26+
import { tmpdir } from 'node:os';
27+
import { basename, join } from 'node:path';
28+
import { pathToFileURL } from 'node:url';
29+
import { buildRuntimeBundle, type BuildRuntimeResult } from '../src/utils/build-runtime.js';
30+
31+
let root = '';
32+
let appDir = '';
33+
let configPath = '';
34+
35+
/**
36+
* The hook handler calls `slugOf` from another module, so it cannot be lowered
37+
* to a metadata body and `os build` bundles it. `loadedConfig` below stands in
38+
* for what `loadConfig` answers: the module is generated from WHERE each
39+
* callable sits in it, and re-reads that path from the bundled config.
40+
*/
41+
const handler = async (): Promise<void> => {};
42+
const loadedConfig = { hooks: [{ name: 'rb_slug', object: 'rb_doc', events: ['beforeInsert'], handler }] };
43+
const callables = { rb_slug: handler };
44+
45+
const APP_FILES = ['objectstack.config.ts', 'slug.ts'];
46+
47+
function build(outputDir: string): Promise<BuildRuntimeResult> {
48+
return buildRuntimeBundle({ sourceConfigPath: configPath, callables, loadedConfig, outputDir });
49+
}
50+
51+
/** The `sources` of the module's inline sourcemap. */
52+
function sourcemapSources(code: string): string[] {
53+
const m = /^\/\/# sourceMappingURL=data:application\/json;base64,(.+)$/m.exec(code);
54+
expect(m, 'the module carries no inline sourcemap').not.toBeNull();
55+
return (JSON.parse(Buffer.from(m![1], 'base64').toString('utf8')) as { sources: string[] }).sources;
56+
}
57+
58+
beforeAll(() => {
59+
root = mkdtempSync(join(tmpdir(), 'os-build-runtime-reproducible-'));
60+
appDir = join(root, 'app');
61+
mkdirSync(appDir);
62+
writeFileSync(
63+
join(appDir, 'slug.ts'),
64+
`export const slugOf = (s: unknown): string => String(s).trim().toLowerCase();\n`,
65+
);
66+
configPath = join(appDir, 'objectstack.config.ts');
67+
writeFileSync(
68+
configPath,
69+
`import { slugOf } from './slug';
70+
71+
const slugTidy = async (ctx: { input: { title: unknown } }) => { ctx.input.title = slugOf(ctx.input.title); };
72+
73+
export default {
74+
hooks: [{ name: 'rb_slug', object: 'rb_doc', events: ['beforeInsert'], handler: slugTidy }],
75+
};
76+
`,
77+
);
78+
});
79+
80+
afterAll(() => {
81+
if (root) rmSync(root, { recursive: true, force: true });
82+
});
83+
84+
describe('the legacy runtime module is reproducible', () => {
85+
it('two builds of an unchanged app give byte-identical modules under one name', async () => {
86+
const outputDir = join(root, 'dist');
87+
const first = await build(outputDir);
88+
const firstBytes = readFileSync(first.outputPath);
89+
const second = await build(outputDir);
90+
const secondBytes = readFileSync(second.outputPath);
91+
92+
expect(second.outputFileName).toBe(first.outputFileName);
93+
expect(second.hash).toBe(first.hash);
94+
expect(secondBytes.equals(firstBytes), 'the two builds shipped different bytes').toBe(true);
95+
expect(readdirSync(outputDir)).toEqual([first.outputFileName]);
96+
});
97+
98+
it('the module names its inputs relative to the config, never a per-run or machine-local path', async () => {
99+
const result = await build(join(root, 'dist-paths'));
100+
const code = readFileSync(result.outputPath, 'utf8');
101+
102+
expect([...sourcemapSources(code)].sort()).toEqual(['.objectstack-runtime.entry.mjs', 'objectstack.config.ts', 'slug.ts']);
103+
// The fixture's mkdtemp directory is the machine-local part of every input path.
104+
expect(code).not.toContain(basename(root));
105+
});
106+
107+
it('writes nothing beside the config, and the module still serves the bundled hook', async () => {
108+
const result = await build(join(root, 'dist-serve'));
109+
expect(readdirSync(appDir).sort()).toEqual(APP_FILES);
110+
111+
const mod = (await import(pathToFileURL(result.outputPath).href)) as {
112+
functions: Record<string, (ctx: { input: { title: unknown } }) => Promise<void>>;
113+
};
114+
expect(Object.keys(mod.functions)).toEqual(['rb_slug']);
115+
const ctx = { input: { title: ' Hello World ' } };
116+
await mod.functions.rb_slug(ctx);
117+
expect(ctx.input.title).toBe('hello world');
118+
});
119+
});

0 commit comments

Comments
 (0)