fix(cli): os start / os dev stop injecting OS_ARTIFACT_PATH into the child serve environment

.changeset/artifact-path-child-env-internal-channel.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): `os start` / `os dev` stop writing `OS_ARTIFACT_PATH` into the child `serve` environment — the CLI's own plumbing moves to an internal channel (#8985)
+
+`os start` and `os dev` are supervisors: each resolves an artifact, then spawns
+`os serve` to boot it. Both handed the resolved path down by writing
+**`OS_ARTIFACT_PATH`** into the child environment — the same variable an operator
+sets to name an artifact. `dev` wrote it unconditionally; `start` wrote it
+whenever it had resolved anything and no `OS_ARTIFACT_URL` was in play. Both
+writes happen **before** the downstream `objectstack.config.ts` is evaluated.
+
+So inside any config, that variable was set on **every** boot, including boots
+where no operator had ever mentioned it — measured from the shipped EE image
+with its own `ENV` deliberately deleted: `os start` still printed
+`Artifact: dist/objectstack.json` and handed that path down. A config could not
+answer *"did a human ask for this, or did the CLI put it here?"*
+
+The resolved path now travels on **`OS_INTERNAL_ARTIFACT_PATH`**, a channel the
+CLI owns both ends of (`packages/cli/src/utils/internal-artifact-channel.ts`),
+and the property downstream consumers need is restored:
+
+> **the presence of `OS_ARTIFACT_PATH` in a config's environment means an
+> operator set it.**
+
+**Nothing about resolution changed.** Each command's ladder resolves in the
+parent exactly as before, and `serve` reads the new channel strictly between the
+reference and the operator knob:
+
+```
+--artifact > OS_ARTIFACT_URL > OS_INTERNAL_ARTIFACT_PATH > OS_ARTIFACT_PATH > <cwd>/dist/objectstack.json
+```
+
+That position is what preserves today's answers in both directions. It beats
+`OS_ARTIFACT_PATH` because `os start --artifact X` run with an operator's
+`OS_ARTIFACT_PATH=Y` exported boots **X** today — the parent used to overwrite
+the variable on the way down, and now inherits it untouched. It loses to
+`OS_ARTIFACT_URL` because `os dev` writes the channel unconditionally, as it
+wrote the old variable unconditionally, and the reference has always outranked
+the path.
+
+Two further behaviours are unchanged and now pinned rather than incidental:
+`start` still refuses to set `OS_BOOT_EMPTY` when a reference is driving the
+boot (an unreachable artifact host stays a loud refusal instead of a silently
+empty platform), and a resolved-but-missing artifact is still "named" to
+`resolveDefaultArtifactPath`, so it fails loudly rather than booting empty.
+
+**If you depended on the old side effect** — a config reading
+`process.env.OS_ARTIFACT_PATH` and expecting the CLI to have populated it — set
+the variable yourself, or read the artifact from the config's own inputs.
+`OS_ARTIFACT_PATH` remains a fully supported operator knob on the exact rung it
+has always occupied; the CLI simply no longer manufactures it on your behalf.
+`OS_INTERNAL_ARTIFACT_PATH` is not a supported knob and is deliberately absent
+from the environment-variable reference.

packages/cli/src/commands/artifact-child-env.pin.test.ts

@@ -0,0 +1,313 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Pin: **the presence of `OS_ARTIFACT_PATH` in a config's environment means an
+ * operator set it.**
+ *
+ * `os start` and `os dev` spawn `os serve`, and the downstream
+ * `objectstack.config.ts` is evaluated inside that child. While the supervisors
+ * wrote their own resolved artifact path into the child's `OS_ARTIFACT_PATH`,
+ * the variable was set on **every** boot — so a config could not tell an
+ * operator's instruction from the CLI's own plumbing, and a consumer wanting to
+ * refuse the retired knob could only do so by inspecting its *value*.
+ *
+ * The plumbing now travels on `OS_INTERNAL_ARTIFACT_PATH`
+ * (`utils/internal-artifact-channel.ts`). This file pins both halves of the
+ * property, plus the two behaviours that had to survive the move: the
+ * resolution ladder, and `start`'s deliberate refusal to declare an empty boot
+ * acceptable when a reference is driving the boot.
+ *
+ * Two kinds of assertion here, and both are needed:
+ *
+ * - **Behavioural** — over `childEnvWithResolvedArtifact`, which is the whole
+ * of what each command contributes to its child's artifact environment.
+ * - **Structural** — a source assertion that neither command writes
+ * `OS_ARTIFACT_PATH` into an env object at all. The behavioural pins describe
+ * the helper; only this one refuses a future edit that re-adds the write
+ * beside it. Both files compose their child env as
+ * `{ ...childEnvWithResolvedArtifact(process.env, …), …other keys }`, so
+ * "the helper is correct" plus "nothing else writes the key" is what makes
+ * the composed env correct.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'path';
+import ts from 'typescript';
+import {
+ INTERNAL_ARTIFACT_PATH_ENV,
+ childEnvWithResolvedArtifact,
+ readInternalArtifactPath,
+} from '../utils/internal-artifact-channel.js';
+import { resolveArtifactSource } from './start.js';
+
+const ARTIFACT = '/srv/app/objectstack.json';
+
+describe('the child `serve` env — OS_ARTIFACT_PATH means an operator set it', () => {
+ it('carries NO OS_ARTIFACT_PATH when the operator did not set one', () => {
+ const parentEnv = { PATH: '/usr/bin', NODE_ENV: 'production' };
+
+ for (const decision of [
+ { kind: 'resolved', path: ARTIFACT },
+ { kind: 'reference' },
+ { kind: 'empty' },
+ ] as const) {
+ const childEnv = childEnvWithResolvedArtifact(parentEnv, decision);
+ expect(
+ Object.prototype.hasOwnProperty.call(childEnv, 'OS_ARTIFACT_PATH'),
+ `decision ${decision.kind} must not introduce OS_ARTIFACT_PATH`,
+ ).toBe(false);
+ expect(childEnv.OS_ARTIFACT_PATH).toBeUndefined();
+ }
+ });
+
+ it('still carries OS_ARTIFACT_PATH — verbatim — when the operator DID set one', () => {
+ const parentEnv = { OS_ARTIFACT_PATH: './dist/from-operator.json' };
+
+ for (const decision of [
+ { kind: 'resolved', path: '/abs/dist/from-operator.json' },
+ { kind: 'reference' },
+ { kind: 'empty' },
+ ] as const) {
+ const childEnv = childEnvWithResolvedArtifact(parentEnv, decision);
+ // Inherited untouched: the child sees exactly what the operator wrote,
+ // not an absolutised rewrite of it.
+ expect(childEnv.OS_ARTIFACT_PATH).toBe('./dist/from-operator.json');
+ }
+ });
+
+ it('hands the resolved artifact down on the internal channel instead', () => {
+ const childEnv = childEnvWithResolvedArtifact({}, { kind: 'resolved', path: ARTIFACT });
+ expect(childEnv[INTERNAL_ARTIFACT_PATH_ENV]).toBe(ARTIFACT);
+ expect(readInternalArtifactPath(childEnv)).toBe(ARTIFACT);
+ });
+
+ it('lets the parent OWN the internal channel — an inherited value never speaks for it', () => {
+ const parentEnv = { [INTERNAL_ARTIFACT_PATH_ENV]: '/stale/inherited.json' };
+
+ expect(childEnvWithResolvedArtifact(parentEnv, { kind: 'resolved', path: ARTIFACT }))
+ .toMatchObject({ [INTERNAL_ARTIFACT_PATH_ENV]: ARTIFACT });
+
+ for (const decision of [{ kind: 'reference' }, { kind: 'empty' }] as const) {
+ const childEnv = childEnvWithResolvedArtifact(parentEnv, decision);
+ expect(
+ readInternalArtifactPath(childEnv),
+ `decision ${decision.kind} resolved nothing, so the channel must be empty`,
+ ).toBeUndefined();
+ expect(Object.prototype.hasOwnProperty.call(childEnv, INTERNAL_ARTIFACT_PATH_ENV)).toBe(false);
+ }
+ });
+
+ it('reads a blank channel value as no decision at all', () => {
+ expect(readInternalArtifactPath({})).toBeUndefined();
+ expect(readInternalArtifactPath({ [INTERNAL_ARTIFACT_PATH_ENV]: '' })).toBeUndefined();
+ expect(readInternalArtifactPath({ [INTERNAL_ARTIFACT_PATH_ENV]: ' ' })).toBeUndefined();
+ });
+});
+
+describe('OS_BOOT_EMPTY — the artifact-reference refusal survives the move', () => {
+ it('is NOT set when a reference (OS_ARTIFACT_URL) is driving the boot', () => {
+ // Load-bearing: setting it here would tell `serve` that booting an app-less
+ // kernel is an acceptable outcome, turning an unreachable artifact host
+ // into a silently empty platform instead of a loud refusal.
+ const childEnv = childEnvWithResolvedArtifact({}, { kind: 'reference' });
+ expect(childEnv.OS_BOOT_EMPTY).toBeUndefined();
+ expect(readInternalArtifactPath(childEnv)).toBeUndefined();
+ });
+
+ it('is NOT set when an artifact was resolved', () => {
+ expect(childEnvWithResolvedArtifact({}, { kind: 'resolved', path: ARTIFACT }).OS_BOOT_EMPTY)
+ .toBeUndefined();
+ });
+
+ it('is set only when nothing resolved and an empty boot IS the intent', () => {
+ expect(childEnvWithResolvedArtifact({}, { kind: 'empty' }).OS_BOOT_EMPTY).toBe('1');
+ });
+
+ it('never CLEARS an operator-exported OS_BOOT_EMPTY (add-only, as before)', () => {
+ const parentEnv = { OS_BOOT_EMPTY: '1' };
+ for (const decision of [
+ { kind: 'resolved', path: ARTIFACT },
+ { kind: 'reference' },
+ { kind: 'empty' },
+ ] as const) {
+ expect(
+ childEnvWithResolvedArtifact(parentEnv, decision).OS_BOOT_EMPTY,
+ `decision ${decision.kind} must not start clearing an inherited OS_BOOT_EMPTY`,
+ ).toBe('1');
+ }
+ });
+});
+
+describe('resolveArtifactSource — the resolution ladder is unchanged', () => {
+ let cwd: string;
+ let home: string;
+
+ const write = (dir: string, rel: string) => {
+ const abs = path.join(dir, rel);
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, '{}');
+ return abs;
+ };
+
+ beforeEach(() => {
+ cwd = mkdtempSync(path.join(tmpdir(), 'os-artifact-cwd-'));
+ home = mkdtempSync(path.join(tmpdir(), 'os-artifact-home-'));
+ });
+ afterEach(() => {
+ for (const d of [cwd, home]) {
+ try { rmSync(d, { recursive: true, force: true }); } catch { /* noop */ }
+ }
+ });
+
+ it('rung 1: --artifact wins over everything, including an operator OS_ARTIFACT_PATH', () => {
+ const flagFile = write(cwd, 'build/pinned.json');
+ write(cwd, 'dist/objectstack.json');
+ write(home, 'dist/objectstack.json');
+
+ const r = resolveArtifactSource('build/pinned.json', home, {
+ cwd,
+ env: { OS_ARTIFACT_PATH: '/from/env.json' },
+ });
+ expect(r?.path).toBe(flagFile);
+ });
+
+ it('rung 1: --artifact passes an http(s) URL through untouched', () => {
+ const url = 'https://cdn.example.com/app.json';
+ expect(resolveArtifactSource(url, home, { cwd, env: {} })?.path).toBe(url);
+ });
+
+ it('rung 2: $OS_ARTIFACT_PATH wins over both auto-detected locations', () => {
+ write(cwd, 'dist/objectstack.json');
+ write(home, 'dist/objectstack.json');
+
+ const r = resolveArtifactSource(undefined, home, {
+ cwd,
+ env: { OS_ARTIFACT_PATH: 'custom/app.json' },
+ });
+ // Anchored on the cwd, exactly as before — the ladder resolves it; the
+ // variable itself is inherited by the child untouched.
+ expect(r?.path).toBe(path.join(cwd, 'custom/app.json'));
+ });
+
+ it('rung 2: $OS_ARTIFACT_PATH may itself be an http(s) URL', () => {
+ const url = 'https://cdn.example.com/env.json';
+ expect(resolveArtifactSource(undefined, home, { cwd, env: { OS_ARTIFACT_PATH: url } })?.path)
+ .toBe(url);
+ });
+
+ it('rung 3: <cwd>/dist/objectstack.json wins over <home>/dist', () => {
+ const cwdArtifact = write(cwd, 'dist/objectstack.json');
+ write(home, 'dist/objectstack.json');
+ expect(resolveArtifactSource(undefined, home, { cwd, env: {} })?.path).toBe(cwdArtifact);
+ });
+
+ it('rung 4: <home>/dist/objectstack.json is the last resort', () => {
+ const homeArtifact = write(home, 'dist/objectstack.json');
+ expect(resolveArtifactSource(undefined, home, { cwd, env: {} })?.path).toBe(homeArtifact);
+ });
+
+ it('rung 5: nothing reachable resolves to undefined', () => {
+ expect(resolveArtifactSource(undefined, home, { cwd, env: {} })).toBeUndefined();
+ });
+});
+
+describe('structural: the supervisors never write the operator knob', () => {
+ /**
+ * Read WRITES of `OS_ARTIFACT_PATH` off the TypeScript AST.
+ *
+ * Deliberately not a text scan. The first version of this pin stripped
+ * comments with a regex and reported `start.ts` clean while the file really
+ * did carry the write: the `--auth-secret` flag description contains the
+ * literal `/api/v1/auth/*`, whose `/*` opened a phantom block comment that
+ * swallowed 250 lines of real code, the injection among them. A detector that
+ * under-reports silently is worse than none — so the parser decides what is
+ * code and what is prose, and strings and comments cannot lie to it.
+ *
+ * Only writes are collected. Reading `process.env.OS_ARTIFACT_PATH` — the
+ * operator's own value, which both commands' ladders still honour — is
+ * correct and must stay possible.
+ */
+ const artifactPathWrites = (file: string): string[] => {
+ const src = readFileSync(new URL(`./${file}`, import.meta.url), 'utf8');
+ const sourceFile = ts.createSourceFile(file, src, ts.ScriptTarget.Latest, true);
+ const hits: string[] = [];
+
+ const at = (node: ts.Node) =>
+ `${file}:${sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1}`;
+ const staticName = (node: ts.Node): string | undefined =>
+ ts.isIdentifier(node) || ts.isStringLiteral(node) ? node.text : undefined;
+
+ const visit = (node: ts.Node): void => {
+ // `{ OS_ARTIFACT_PATH: value }` and `{ OS_ARTIFACT_PATH }`
+ if (
+ (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node))
+ && staticName(node.name) === 'OS_ARTIFACT_PATH'
+ ) {
+ hits.push(`${at(node)} object property`);
+ }
+ // `env.OS_ARTIFACT_PATH = value` / `env['OS_ARTIFACT_PATH'] = value`
+ if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+ const lhs = node.left;
+ if (ts.isPropertyAccessExpression(lhs) && lhs.name.text === 'OS_ARTIFACT_PATH') {
+ hits.push(`${at(node)} property assignment`);
+ }
+ if (
+ ts.isElementAccessExpression(lhs)
+ && staticName(lhs.argumentExpression) === 'OS_ARTIFACT_PATH'
+ ) {
+ hits.push(`${at(node)} indexed assignment`);
+ }
+ }
+ ts.forEachChild(node, visit);
+ };
+
+ visit(sourceFile);
+ return hits;
+ };
+
+ for (const file of ['start.ts', 'dev.ts']) {
+ it(`${file} writes OS_ARTIFACT_PATH nowhere`, () => {
+ expect(
+ artifactPathWrites(file),
+ `${file} must not write OS_ARTIFACT_PATH into a child environment — the CLI's own `
+ + `resolved artifact travels on ${INTERNAL_ARTIFACT_PATH_ENV}, so that a downstream `
+ + `objectstack.config.ts seeing OS_ARTIFACT_PATH knows an operator set it. `
+ + `Reading process.env.OS_ARTIFACT_PATH (the operator's value) stays correct.`,
+ ).toEqual([]);
+ });
+ }
+
+ it('the detector itself sees a write that a comment-stripping text scan missed', () => {
+ // The specimen is `start.ts`'s own shape, with the `/*`-bearing string that
+ // defeated the text scan sitting above it. Without this, the pin above
+ // could go permanently green by failing to look.
+ // The trailing docblock matters: the `/*` inside the string only swallows
+ // code up to the next `*/`, and in the real file that closer is an ordinary
+ // docblock a few hundred lines further down.
+ const specimen = [
+ "const flag = { description: 'mount /api/v1/auth/* (overrides $AUTH_SECRET)' };",
+ 'const childEnv = {',
+ ' ...process.env,',
+ ' OS_ARTIFACT_PATH: resolved.path,',
+ '};',
+ '/** An ordinary docblock, whose closer ends the phantom comment. */',
+ 'export const done = true;',
+ ].join('\n');
+
+ const sourceFile = ts.createSourceFile('specimen.ts', specimen, ts.ScriptTarget.Latest, true);
+ let found = 0;
+ const visit = (node: ts.Node): void => {
+ if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)
+ && node.name.text === 'OS_ARTIFACT_PATH') found += 1;
+ ts.forEachChild(node, visit);
+ };
+ visit(sourceFile);
+ expect(found).toBe(1);
+
+ // ...and the text scan this replaced reports the same specimen clean.
+ const textScanned = specimen.replace(/\/\*[\s\S]*?\*\//g, '');
+ expect(/OS_ARTIFACT_PATH\s*:/.test(textScanned)).toBe(false);
+ });
+});

packages/cli/src/commands/dev.ts

@@ -16,6 +16,7 @@ import {
  assessArtifactStaleness,
  formatMtimeGap,
 } from '../utils/dev-restart.js';
+import { childEnvWithResolvedArtifact } from '../utils/internal-artifact-channel.js';
 import { readEnvWithDeprecation, isMcpServerEnabled } from '@objectstack/types';
 import type { ResolvedProjectDatabaseUrl } from '@objectstack/runtime';
 
@@ -327,10 +328,18 @@ export default class Dev extends Command {
  fs.mkdirSync(path.dirname(resolvedDb.url.replace(/^file:/, '')), { recursive: true });
  }
  const effectiveDb = resolvedDb.url;
+ // `dev` always has a resolved artifact by this point (it compiled one, or
+ // was handed one with `--artifact`, or is pointing at the canonical
+ // `<cwd>/dist/objectstack.json`), so the decision is unconditionally
+ // `resolved` — exactly as unconditional as the `OS_ARTIFACT_PATH` write
+ // it replaces. What changed is the channel: the resolved path travels on
+ // the CLI's own `OS_INTERNAL_ARTIFACT_PATH`, so an `OS_ARTIFACT_PATH`
+ // seen by a downstream `objectstack.config.ts` means an operator set it.
+ // The operator's own value is inherited verbatim, and `dev`'s ladder
+ // above still honours it on the rung it has always occupied.
  const localEnv: NodeJS.ProcessEnv = {
- ...process.env,
+ ...childEnvWithResolvedArtifact(process.env, { kind: 'resolved', path: artifactPath }),
  OS_ENVIRONMENT_ID: environmentId,
- OS_ARTIFACT_PATH: artifactPath,
  OS_SEED_ADMIN: seedAdmin ? '1' : '0',
  ...(seedAdmin && flags['admin-email'] ? { OS_SEED_ADMIN_EMAIL: flags['admin-email'] } : {}),
  ...(seedAdmin && flags['admin-password'] ? { OS_SEED_ADMIN_PASSWORD: flags['admin-password'] } : {}),