Skip to content

Commit 6294157

Browse files
fix(cli): a direct os serve --dev compiles the config before its dev artifact door serves it (#26289)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XVivP8oT7gawhLRoP3Mv7si)_ Fixes #26242 Clause-②: no Metadata-protocol: none ## What was wrong A host config's dev boot holds two copies of one stack. The config module, evaluated in the serving process, feeds the AppPlugin wrap, and provider-bound connectors are materialized from that copy, so it is what dispatch calls. The compiled `dist/objectstack.json` feeds the dev artifact door, and its copy is what `/api/v1/meta/connector/NAME` serves. #26130 (PR #26240) made `os dev` compile before it boots. A direct `os serve --dev` still composed the door over whatever artifact was on disk, so an env-derived value differed between the two copies. Red first on `main` at `81bba6c3` (before #26240) and re-read on this branch's base `3d50a43b`: `examples/app-showcase`, artifact compiled with `OS_PORT`/`PORT` unset (all three `baseUrl` values `http://127.0.0.1:3000`), `OS_PORT=41302`, nothing listening on 3000. "dispatch" is `POST /api/v1/automation/showcase_declarative_connector_ping/trigger`. | boot | `/meta/connector/showcase_status_api` → `providerConfig.baseUrl` before | after | dispatch | |---|---|---|---| | `os serve objectstack.config.ts --dev -p 41302` | `http://127.0.0.1:3000` | `http://127.0.0.1:41302` | 200, `status: ok` (reached 41302) both | | `os serve objectstack.config.ts -p 41302` (production) | `http://127.0.0.1:41302` | `http://127.0.0.1:41302`, artifact md5 unchanged | 200 both | | `os dev --no-compile --no-watch -p 41302` | `http://127.0.0.1:3000` | `http://127.0.0.1:3000` (unchanged, the operator's shortcut) | 200 | | `os dev --no-watch -p 41302` | (`:41302` since #26240) | `http://127.0.0.1:41302` | 200 | | `os serve --dev` with `OS_ARTIFACT_URL=file://…` (pinned) | boots the pinned artifact | same, no compile line, pinned file md5 unchanged | | ## The fix Route (b), the one #26240 took: the dev boot compiles the config into the artifact it is about to serve, in its own environment, so both copies are one evaluation's answer. Nothing restates which variables a config reads or in what order. - `packages/cli/src/utils/dev-compile-at-boot.ts` (new): `devCompilesAtBoot`, moved verbatim from `commands/dev.ts` so both doors read the one decision (`dev.ts` imports `serve.ts`, so `serve.ts` cannot import `dev.ts`). `dev.ts` now imports it; the decision and its `os dev` behaviour are unchanged. The `#26130` pin's import moves with it. - `packages/cli/src/commands/serve.ts`: in the dev artifact door's existing-artifact branch, before the door is constructed, a boot with no supervising `os dev` (its channel `OS_INTERNAL_ARTIFACT_PATH` unset) asks `devCompilesAtBoot` and compiles. Under `os dev` the child keeps its parent's decision, so `os dev --no-compile` still serves the artifact as built and a default `os dev` does not compile twice. A boot with no artifact on disk never reaches this branch: no door composes, the wrap is the one copy, and nothing is compiled (so test fixtures and fresh checkouts without `dist/` are untouched). A failed compile refuses the boot with the compile's own output, as under `os dev`. Production boots never reach the branch (it is inside the `isDev` door block). - `compileForDevBoot` (same util) spawns `os compile CONFIG --output ARTIFACT` with the serving process's environment, including the `.env` files serve loaded, but with `NODE_ENV` put back to its launch value. `serve --dev` sets `NODE_ENV=development` on itself; if the child inherited that, it would run under oclif's source loader, which `child-env-source-loader.pin.test.ts` forbids. The child therefore sees what `os dev`'s compile child sees. - Cost: one compile per direct dev boot over an existing artifact. On the showcase, ready went from 5 s to 8 s. ## Tests - New `packages/cli/test/serve-dev-connector-env-parity.integration.test.ts` (integration tier, built entry, `-p 0`). It uses the #26130 fixture, copied so neither file's legs move the other's (#26268 is reworking that file for the port flag). The fixture has one provider-bound connector whose `baseUrl` is built from `OS_PORT`, a provider factory that records the materialized `providerConfig`, and a `:3000` artifact rewritten before each boot. Three legs: - `os serve --dev`: the served `baseUrl` equals the materialized one and is not the build-time one. - `os dev --no-compile`: the served one is still `:3000` and the artifact's bytes are untouched. - Production `os serve`: the materialized one is not `:3000` and the artifact's bytes are untouched. The verdicts compare the two copies, never a port number, so the file holds whether or not #26268 has landed. Three runs: `Tests 3 passed (3)` at 13.6 s, 13.9 s and 13.2 s. The header declares `test-budget: 20`, from the slowest run x 1.25. - `dev-connector-env-parity.integration.test.ts` (#26130's file) is unchanged and green at head. Together with the new file: `Test Files 2 passed (2)`, `Tests 5 passed (5)`. - Ablation, run once per behaviour through `scripts/ablation-replace.mjs`. Each leg rebuilt the CLI, and `ablation-dist-preflight` found the marker in `packages/cli/dist/commands/serve.js` before the run: - A: the compile condition was short-circuited to false. Only the `serve --dev` leg went red, with `expected 'http://127.0.0.1:3000' to be 'http://127.0.0.1:41302'`. - B: the supervised guard was dropped. Only the `--no-compile` leg went red, with `expected 'http://127.0.0.1:41302' to be 'http://127.0.0.1:3000'`. - Both restored with the blob equal to HEAD and `git diff HEAD` empty. After a rebuild, `preflight --absent` passed for both markers. - `pnpm --filter @objectstack/cli exec vitest run --project unit` at `ca2e4216`: `Test Files 334 passed (334)`, `Tests 4878 passed (4878)`. The later commits change one refusal string and one test header. - `pnpm --filter @objectstack/cli exec vitest run --project integration` at `378de620` (the first head; the later diff moves the compile spawn into the util and splits the pin out): `Test Files 173 passed | 1 skipped (174)`, `Tests 1477 passed | 9 skipped`. This tier was run because the diff touches the serve boot path, and every direct-dev fixture that has a `dist/` now compiles at boot. - `pnpm --filter @objectstack/cli typecheck`: exit 0 at head. ## Gates Local subset at head `6f7edd28c`: `node scripts/pm/dispatch-gates.mjs --commands` derived 91 families, and each was run with its exit code captured before any pipe. `--ran` reconciliation: `91 run, 0 NOT-MEASURED`, all exit 0. - First sweep, at `ca2e4216`: - `pnpm check:doc-authoring` went red on a real finding: the compile refusal's runtime text carried the tracker id. It was stripped (`751f30aa`) and the gate is green. - `check-plugin-teardown-shape --self-test` exited 3 on the shallow clone. After `git fetch origin 621a487` it exited 0 (48 cases). - `check:dual-build-cjs-loads` exited 3 there, with its prerequisite not met. It exited 0 on the final sweep. - `pnpm check:cli-test-child-env`: green with the new census entry, and its self-test passed 152 cases. The first attempt was refused because the leg env's spread came after `NODE_ENV`; `NODE_ENV: undefined` now comes last. - `eslint --no-inline-config` on the six touched source and test files: exit 0. `node scripts/check-nul-bytes.mjs`: exit 0. - CI check-runs: in progress at PR open. The seat reads convergence. ## Acceptance notes - Open overlap re-measured before opening: #26268 (the `-p` port flag; it touches `dev.ts`, `serve.ts` and #26130's test file), #26244 and #26215 (`serve.ts`, other regions). A trial merge of #26268 into this head is clean. On the merged tree with the CLI rebuilt, both parity files answer `Tests 6 passed (6)`; there `-p 0` makes the config read `:0`, and the relative verdicts still hold. Whichever of the two lands second merges `main`. - Outside the claim's file surface: none. Docs untouched: no flag or default changed. The `os serve --dev` bullet in `content/docs/deployment/cli.mdx` says nothing about the artifact, so it is not false. - A non-host config (no plugin instances) on `os serve --dev` never reaches this door: its standalone stack serves metadata and dispatch from the same artifact bundle, so the two copies already agree, both at the build-time value. That is the same posture as `os start --artifact`. It was observed only, not measured on a fixture, and is not this card. - `NODE_ENV=development os serve` (no `--dev`) is a dev boot too (`isDevelopmentBoot`), composes the same door, and so compiles the same way. `os start` with `NODE_ENV=development` is supervised and does not. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_019rDzaJmEJAYLUNJ4kwG2vN --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 6ea429d commit 6294157

7 files changed

Lines changed: 536 additions & 44 deletions

File tree

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
'@objectstack/cli': patch
3+
---
4+
5+
fix(cli): a direct `os serve --dev` compiles the config before its dev artifact door serves it, so the served connector `baseUrl` is the one dispatch calls
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
- **Before.** `os serve --dev` over an existing `dist/objectstack.json` served that file through the dev artifact door as found, while dispatch read the config module it evaluated. A config value read from the environment, such as `examples/app-showcase`'s self URL built from `OS_PORT`, then differed between them. With `OS_PORT=41302` over an artifact built without it, `GET /api/v1/meta/connector/showcase_status_api` served `http://127.0.0.1:3000` while the connector called port 41302. `os dev` had the same split until it began compiling at boot.
11+
- **Now.** Before it composes that door, a direct dev boot compiles the config into the artifact in its own environment, using the same decision `os dev` uses (`devCompilesAtBoot`), so both copies come from one evaluation. A failed compile refuses the boot, as under `os dev`. This costs about 3 s per boot on the showcase.
12+
- Under `os dev`, the `serve` child keeps its parent's decision and never compiles again, so `os dev --no-compile` still boots the artifact as built. A dev boot with no artifact on disk composes no door and compiles nothing, as before. A pinned artifact (`OS_ARTIFACT_URL`) is never rebuilt.
13+
- Production `os serve` (no `--dev`, `NODE_ENV` not `development`) and `os start` are unchanged.

‎packages/cli/src/commands/dev.ts‎

Lines changed: 1 addition & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import {
2222
type DevelopmentUpgradeResult,
2323
} from '../utils/dev-organization-ownership-upgrade.js';
2424
import { childEnvWithResolvedArtifact } from '../utils/internal-artifact-channel.js';
25+
import { devCompilesAtBoot } from '../utils/dev-compile-at-boot.js';
2526
import { makeDirectorySync } from '../utils/make-directory.js';
2627
// THE artifact precedence, written once (#21501) — shared with `start`, and
2728
// with the `serve` child this command spawns. ⛔ No rung of it is restated here.
@@ -246,48 +247,6 @@ export function forwardSeedSettledToParent(msg: unknown): boolean {
246247
return true;
247248
}
248249

249-
/**
250-
* Whether this `os dev` boot compiles the cwd config into the artifact it is
251-
* about to serve, before the server starts (#26130).
252-
*
253-
* Yes by default whenever the boot serves an artifact this command builds and
254-
* there is a config to build it from. The reason is the dev boot's two copies
255-
* of one stack. A host config's `os dev` boot serves the stack from TWO places:
256-
* the config MODULE, evaluated in the `serve` child (the AppPlugin wrap, whose
257-
* registry copy is what a provider-bound connector is materialized from, so
258-
* what dispatch calls), and the compiled artifact (the dev artifact door, whose
259-
* copy is what `/api/v1/meta/<type>` serves). A config that reads the
260-
* environment at module evaluation, as `examples/app-showcase`'s self URL reads
261-
* `OS_PORT`, gives the module copy THIS boot's value and the artifact copy the
262-
* value of whichever environment last compiled it. Measured on the showcase
263-
* with `OS_PORT=41302` over an artifact built without it:
264-
* `GET /api/v1/meta/connector/showcase_status_api` served
265-
* `http://127.0.0.1:3000` while the materialized connector called 41302.
266-
*
267-
* Compiling here, in this process's environment (the `serve` child inherits
268-
* the same one), makes both copies one evaluation's answer, so nothing has to
269-
* restate which variables a config reads or in what order. The watch loop's
270-
* recompiles already run in that environment, so the two stay one answer for
271-
* the whole session.
272-
*
273-
* `--no-compile` keeps the old shortcut, booting the artifact as built (and
274-
* the startup staleness warning says when it is older than the sources); a
275-
* missing artifact is still compiled, since there is nothing else to serve. A
276-
* pinned artifact (`--artifact`, `OS_ARTIFACT_URL`, a remote
277-
* `OS_ARTIFACT_PATH`) is never rebuilt. With no config and a missing artifact
278-
* the answer is yes, so the caller refuses there with the one remedy line.
279-
*/
280-
export function devCompilesAtBoot(opts: {
281-
compile: boolean;
282-
pinned: boolean;
283-
configExists: boolean;
284-
artifactExists: boolean;
285-
}): boolean {
286-
if (opts.pinned) return false;
287-
if (!opts.artifactExists) return true;
288-
return opts.compile && opts.configExists;
289-
}
290-
291250
/**
292251
* Whether this `os dev` boot runs the watch-recompile loop (#20681).
293252
*

‎packages/cli/src/commands/serve.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import { mergeBootConfig } from '../utils/merge-boot-config.js';
1111
import { provisionTelemetryDatasource, standaloneTelemetryPrimary } from '../utils/telemetry-datasource.js';
1212
import { isHostConfig, shouldBootWithLibrary } from '../utils/plugin-detection.js';
1313
import { readInternalArtifactPath, readInternalConfigOutputPath } from '../utils/internal-artifact-channel.js';
14+
import { compileForDevBoot, devCompilesAtBoot } from '../utils/dev-compile-at-boot.js';
1415
import { makeDirectorySync } from '../utils/make-directory.js';
1516
// The precedence's last rung — whether the cwd config takes part — decided by
1617
// the SAME predicate the supervisors print their `Config:` row by (#21501).
@@ -2174,6 +2175,9 @@ export default class Serve extends Command {
21742175
// An operator who never exported NODE_ENV is booting a real deployment,
21752176
// not asking to be treated as development — this is `os serve` agreeing
21762177
// with `os start` on that, one line, for the whole gate family at once.
2178+
// #26242 — the value before this command sets its own, for the one child a
2179+
// dev boot may start (`compileForDevBoot`), which must not inherit the write.
2180+
const launchNodeEnv = process.env.NODE_ENV;
21772181
if (flags.dev) {
21782182
if (!process.env.NODE_ENV) process.env.NODE_ENV = 'development';
21792183
} else if (!process.env.NODE_ENV) {
@@ -3512,6 +3516,41 @@ export default class Serve extends Command {
35123516
+ '\n boot without a door.',
35133517
));
35143518
} else {
3519+
// #26242 — the door is about to serve THIS file's copy of the
3520+
// stack while the wrap below serves the config module's, so a
3521+
// config that reads the environment at module evaluation (the
3522+
// showcase's `OS_PORT` self URL) gives `/meta` the value of
3523+
// whichever environment last compiled the file. `os dev` closed
3524+
// that by compiling before it boots (#26130); a direct dev boot
3525+
// reads the same decision, `devCompilesAtBoot`. Under a
3526+
// supervising `os dev` (its channel answered) the parent already
3527+
// made it, `--no-compile` included, so the child never compiles
3528+
// again. Only an artifact on disk reaches this branch: with none,
3529+
// no door composes and the wrap is the one copy.
3530+
//
3531+
// The compile runs in THIS process's environment, the one the
3532+
// module above was evaluated in, with the launch `NODE_ENV` put
3533+
// back (`compileForDevBoot` says why), so both copies are one
3534+
// evaluation's answer exactly as under `os dev`. A failed compile
3535+
// refuses the boot, as it does there.
3536+
if (!supervisorArtifact && devCompilesAtBoot({
3537+
compile: true,
3538+
pinned: Boolean(pinnedArtifact),
3539+
configExists,
3540+
artifactExists: true,
3541+
})) {
3542+
printDiagnostic(chalk.dim(` Compiling ${relativeConfig} → ${path.relative(process.cwd(), hmrArtifactPath) || hmrArtifactPath}...`));
3543+
const compiled = compileForDevBoot({ configPath: absolutePath, outputPath: hmrArtifactPath, launchNodeEnv });
3544+
if (compiled.status !== 0) {
3545+
console.error(
3546+
`${compiled.stdout ?? ''}${compiled.stderr ?? ''}\n`
3547+
+ chalk.red(` ✗ Compile failed — fix errors above before starting the dev server.\n`)
3548+
+ chalk.dim(` A dev boot over ${hmrArtifactPath} compiles ${relativeConfig} into it first, so the`)
3549+
+ chalk.dim('\n metadata it serves is the config this boot evaluates.'),
3550+
);
3551+
process.exit(1);
3552+
}
3553+
}
35153554
const { MetadataPlugin } = await import('@objectstack/metadata');
35163555
// Mirror the standalone stack's dev config exactly
35173556
// (packages/runtime/src/standalone-stack.ts): declarative
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { spawnSync, type SpawnSyncReturns } from 'child_process';
4+
5+
/**
6+
* Whether a development boot compiles the config into the artifact it is about
7+
* to serve, before the server starts (#26130). Both dev doors read this one
8+
* decision: `os dev` before it spawns its `serve` child, and a direct
9+
* `os serve --dev` before it composes the dev artifact door (#26242). Lifted
10+
* here from `commands/dev.ts` so the second door reads it instead of restating
11+
* it (`dev.ts` imports `serve.ts`, so `serve.ts` cannot import `dev.ts`).
12+
*
13+
* Yes by default whenever the boot serves an artifact it builds and there is a
14+
* config to build it from. The reason is the dev boot's two copies of one
15+
* stack. A host config's dev boot serves the stack from TWO places: the config
16+
* MODULE, evaluated in the serving process (the AppPlugin wrap, whose registry
17+
* copy is what a provider-bound connector is materialized from, so what
18+
* dispatch calls), and the compiled artifact (the dev artifact door, whose copy
19+
* is what `/api/v1/meta/<type>` serves). A config that reads the environment at
20+
* module evaluation, as `examples/app-showcase`'s self URL reads `OS_PORT`,
21+
* gives the module copy THIS boot's value and the artifact copy the value of
22+
* whichever environment last compiled it. Measured on the showcase with
23+
* `OS_PORT=41302` over an artifact built without it, on `os dev` and on
24+
* `os serve --dev` alike: `GET /api/v1/meta/connector/showcase_status_api`
25+
* served `http://127.0.0.1:3000` while the materialized connector called 41302.
26+
*
27+
* Compiling in the boot's own environment (`os dev`'s `serve` child inherits
28+
* the same one) makes both copies one evaluation's answer, so nothing has to
29+
* restate which variables a config reads or in what order. `os dev`'s watch
30+
* loop recompiles in that environment too, so the two stay one answer for the
31+
* whole session.
32+
*
33+
* `os dev --no-compile` keeps the old shortcut, booting the artifact as built
34+
* (and the startup staleness warning says when it is older than the sources);
35+
* a missing artifact is still compiled, since there is nothing else to serve.
36+
* A pinned artifact (`--artifact`, `OS_ARTIFACT_URL`, a remote
37+
* `OS_ARTIFACT_PATH`) is never rebuilt. With no config and a missing artifact
38+
* the answer is yes, so the caller refuses there with the one remedy line.
39+
*/
40+
export function devCompilesAtBoot(opts: {
41+
compile: boolean;
42+
pinned: boolean;
43+
configExists: boolean;
44+
artifactExists: boolean;
45+
}): boolean {
46+
if (opts.pinned) return false;
47+
if (!opts.artifactExists) return true;
48+
return opts.compile && opts.configExists;
49+
}
50+
51+
/**
52+
* Compile `configPath` into `outputPath` in a child `os compile`, for a direct
53+
* dev boot about to serve that artifact (#26242). The output is captured and
54+
* returned, so a boot whose banner is still being assembled stays quiet unless
55+
* the compile fails.
56+
*
57+
* The child gets the serving process's environment (the project `.env` files
58+
* it loaded included) with ONE value put back: `NODE_ENV` as the process was
59+
* launched with it. `serve --dev` sets `NODE_ENV=development` on ITSELF after
60+
* its own modules have loaded; inherited, that write would put the child under
61+
* oclif's TypeScript source loader, the failure
62+
* `commands/child-env-source-loader.pin.test.ts` holds every command to (and
63+
* the reason `os dev`'s own compile spawn writes no `NODE_ENV`). So the child
64+
* sees what `os dev`'s compile child sees: the operator's `NODE_ENV`, or none.
65+
*/
66+
export function compileForDevBoot(opts: {
67+
configPath: string;
68+
outputPath: string;
69+
launchNodeEnv: string | undefined;
70+
}): SpawnSyncReturns<string> {
71+
return spawnSync(
72+
process.execPath,
73+
[process.argv[1], 'compile', opts.configPath, '--output', opts.outputPath],
74+
{
75+
// `spawn` drops an `undefined` entry, so an unset launch value stays unset.
76+
env: { ...process.env, NODE_ENV: opts.launchNodeEnv },
77+
encoding: 'utf8',
78+
stdio: ['ignore', 'pipe', 'pipe'],
79+
},
80+
);
81+
}

‎packages/cli/test/dev-compile-at-boot.pin.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@
1515

1616
import { describe, it, expect } from 'vitest';
1717
import { Parser } from '@oclif/core';
18-
import Dev, { devCompilesAtBoot } from '../src/commands/dev.js';
18+
import Dev from '../src/commands/dev.js';
19+
import { devCompilesAtBoot } from '../src/utils/dev-compile-at-boot.js';
1920

2021
const parseDev = (argv: string[]) =>
2122
Parser.parse(argv, { flags: Dev.flags, args: Dev.args, strict: true });

0 commit comments

Comments
 (0)