Skip to content

Commit 975d5b3

Browse files
fix(create-objectstack, cli): scaffolded projects pin every @objectstack/* dependency to the exact scaffolder version (#25539)
<!-- claude-projects-attribution: {"github_login":"os-sales"} --> _Requested by **Sales** · [project thread](https://claude.ai/code/project/chan_01D5bWFY3rFzgJcytD5gD4Uu?thread=cmsg_01D5bWFY3rFzgJcytD5gD4UuDWJsBGQpadCH8JR2xZQ5re)_ Part of #25510 (the producer half). The card stays open for two halves this PR does not carry, named under "What is left" below. Clause-②: no Metadata-protocol: none ## What changed Every project scaffolded by `npm create objectstack`, `os init` or `os create` (default standalone placement) now lists each `@objectstack/*` dependency at the EXACT version of the tool that wrote it. Before, it got `^VERSION`. A prerelease is written verbatim (`18.1.0-rc.2`). The v18 docs say a `^18.0.0` range "can therefore move you to a release that breaks you. Pin exact versions" (`content/docs/releases/v18/index.mdx:129-130`). | Producer | Before | After | |---|---|---| | `packages/create-objectstack/src/pkg-utils.ts` `syncObjectStackDeps` | `^VERSION` | `VERSION` | | `packages/cli/src/commands/init.ts` `pkgVersion()` | `^VERSION` | `VERSION` | | `packages/cli/src/commands/create.ts` `objectstackDependencySpec('standalone')` | `^VERSION` | `VERSION` | | `os create --in-repo` | `workspace:*` | `workspace:*` (unchanged) | Third-party ranges (`typescript`, `vitest`, `zod`, `@types/node`) are not touched. Every scaffolded `@objectstack/*` name is in `.changeset/config.json`'s `fixed` group, so the scaffolder's own version is published for each one. The changeset is `patch` on `create-objectstack` and `@objectstack/cli`, and it carries the hand fix for existing projects. ## What is left on #25510 1. **The committed blank baseline (`packages/create-objectstack/src/templates/blank/package.json`) stays `^18.0.0` on purpose.** The release rewrite that stamps it is `scripts/sync-template-versions.mjs`, which is outside this card's file surface. It runs in the root `version` script, after `changeset version`, and in `cut-rc.yml`. It sets every `@objectstack/*` entry of every template's `package.json` to `range` = `` `^${major}.0.0` `` (`loadScaffolderVersion()`, about line 270). The same `range` also feeds the manifest's `specVersion`. If this PR wrote an exact baseline, the next version pass would put `^MAJOR.0.0` back, and an exact-form ratchet in `template-consistency.test.ts` would then fail on the post-version tree. So the baseline, its ratchet (`template-consistency.test.ts:122-139`, "must be ^MAJOR.x") and the rewriter have to move together, in a change whose surface includes `scripts/sync-template-versions.mjs` and its `--self-test` fixtures. That change has to split the deps value (the exact `version`, prerelease included) from `specVersion`, which is a protocol range and should stay one. Users are not exposed in the meantime: `syncObjectStackDeps` overwrites the baseline at scaffold time whenever the scaffolder's version is readable. The test `leaves no @objectstack/* range in the scaffolded blank template` pins that. 2. **Docs (devx lane):** `content/docs/protocol/kernel/plugin-spec.mdx:719,723` (a plugin `package.json` example with `^17.0.0`) and `:741-746` ("the scaffolders caret-pin each dependency"), plus `content/docs/upgrading.mdx:81-82` ("a project on the scaffold's default ranges (`^17.0.0`)"). ## Tests Measured on this branch (head `3a678c53a7` for the final union; package runs cited per commit): - `pnpm --filter create-objectstack test`: Test Files 18 passed (18), Tests 268 passed (268) (at `95c59d7dbe`; the create-objectstack tree is unchanged since). - `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2`: Test Files 327 passed (327), Tests 4811 passed (4811) (at `4f417d70e9`). - `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 test/scaffold-exact-objectstack-pin.test.ts test/init.test.ts test/create.test.ts`: 3 passed (3), 73 passed (73) (final test content). - `pnpm --filter create-objectstack typecheck` exit 0; `pnpm --filter @objectstack/cli typecheck` exit 0 (`tsc --noEmit && pnpm check:test-typecheck`). What is pinned: - create-objectstack: exact form, a prerelease (`18.1.0-rc.2`), and the real blank template through the rewrite (`template-consistency.test.ts`). `runtime-image.test.ts` now uses EQUALITY between the Dockerfile tag and the emitted pin, plus a prerelease scaffold. `satisfiesCaret` and its battery are gone, because no producer writes a caret any more. `scaffold-skills-single-copy.test.ts` reads the exact form. - `os init` and `os create` (standalone): exact form at this checkout's version (`init.test.ts`, `create.test.ts`). The new `test/scaffold-exact-objectstack-pin.test.ts` imports the commands under a planted `18.1.0-rc.2` manifest and checks every template of both commands, with `--in-repo` `workspace:*` as the control. **Ablation**, one per producer, through `scripts/ablation-replace.mjs` in wrap mode. Each mutation put the caret back. Each restore was proven by blob == HEAD and an empty `git diff HEAD`. These tests import `src/`, so no build or dist leg applies. - `init.ts` `pkgVersion()`: 4 failed / 53 passed (`init.test.ts` ×3 templates and the prerelease file). - `create.ts` standalone: 2 failed / 18 passed. - `pkg-utils.ts`: 6 failed / 53 passed (`template-consistency.test.ts` ×3, `runtime-image.test.ts` ×3). ## Gates `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derives 70 commands. The same 70 were re-derived at `3a678c53a7` and run there, together with `pnpm lint`. Results are in the report comment on #25510. CI owns every other family. ## Acceptance notes - Prose now stale and outside the file surface (comments only, no behaviour): `packages/create-objectstack/src/index.ts:37` and `:586` ("the template carries a caret range"), and `packages/create-objectstack/src/runtime-image.ts:20-27` (the generated `package.json` "carries a caret RANGE"). The resolve-after-install logic is still correct with exact pins: the resolved version now equals the pin. --- _Generated by [Claude Code](https://claude.ai/code/session_01CxBKycaiUpA1yGx1XyoGqX)_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01CxBKycaiUpA1yGx1XyoGqX --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 93a6ba4 commit 975d5b3

10 files changed

Lines changed: 229 additions & 155 deletions
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'create-objectstack': patch
3+
'@objectstack/cli': patch
4+
---
5+
6+
fix(create-objectstack, cli): a scaffolded project pins every `@objectstack/*` dependency to the exact version of the tool that wrote it, not a `^` range
7+
8+
Clause-②: no
9+
Metadata-protocol: none
10+
11+
On the v18 line a breaking change may ship in a minor or a patch, and the release notes say "Pin exact versions". The scaffolders wrote `^<version>` instead, so the next re-resolve (`npm update`, a deleted lockfile, an install without the lock) could move a new project onto a release that breaks it without anyone deciding to upgrade.
12+
13+
- **`npm create objectstack`** (`create-objectstack`), **`os init`** and **`os create`** (the default standalone placement) now write the scaffolder's own version, exactly, for every `@objectstack/*` entry in the emitted `package.json`: `18.0.0`, not `^18.0.0`. A prerelease is written verbatim (`18.1.0-rc.2`).
14+
- **Unchanged.** `os create --in-repo` still writes `workspace:*`. Third-party ranges (`typescript`, `vitest`, `zod`, `@types/node`) are not touched. Every `@objectstack/*` package is released on one version, so the exact version is published for each of them.
15+
- **An existing project** keeps whatever its `package.json` says. To follow the docs, replace each `^18.x.y` on an `@objectstack/*` entry with the exact version you run (for example `"@objectstack/runtime": "18.0.0"`), then reinstall.

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

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -93,12 +93,12 @@
9393
* ## The version the standalone shape pins
9494
*
9595
* Every `@objectstack/*` package in this monorepo is released together on one
96-
* version, so the range that is guaranteed to exist and to be mutually
97-
* compatible is the CLI's own. `getCliVersion()` (owned by `init.ts`, which
98-
* has pinned scaffolded deps this way since long before this command did) reads
99-
* it from the CLI package's own manifest; the range is imported rather than
100-
* re-derived so the two scaffolders cannot drift on the one value that decides
101-
* whether a scaffold resolves at all.
96+
* version, so the version that is guaranteed to exist and to be mutually
97+
* compatible is the CLI's own, pinned exactly. `getCliVersion()` (owned by
98+
* `init.ts`, which has pinned scaffolded deps this way since long before this
99+
* command did) reads it from the CLI package's own manifest; the version is
100+
* imported rather than re-derived so the two scaffolders cannot drift on the
101+
* one value that decides whether a scaffold resolves at all.
102102
*
103103
* ## Why the standalone shape reuses `init`'s renderers
104104
*
@@ -157,12 +157,14 @@ export const DEFAULT_PLACEMENT: ScaffoldPlacement = 'standalone';
157157
/**
158158
* The dependency spec every `@objectstack/*` entry in an emitted manifest gets.
159159
*
160-
* `standalone` is caret-pinned to the CLI's own version — a published range
161-
* that npm, pnpm, yarn and bun all resolve. `workspace:*` is emitted ONLY for
162-
* the in-repo placement, where a workspace really does supply those names.
160+
* `standalone` is the CLI's own version, EXACT (no `^`/`~`, a prerelease kept
161+
* verbatim) — a published version that npm, pnpm, yarn and bun all resolve,
162+
* and the pin the docs prescribe, because a breaking change may ship in a
163+
* minor or a patch on the v18 line. `workspace:*` is emitted ONLY for the
164+
* in-repo placement, where a workspace really does supply those names.
163165
*/
164166
export function objectstackDependencySpec(placement: ScaffoldPlacement): string {
165-
return placement === 'in-repo' ? 'workspace:*' : `^${getCliVersion()}`;
167+
return placement === 'in-repo' ? 'workspace:*' : getCliVersion();
166168
}
167169

168170
/**

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,13 @@ export function getCliVersion(): string {
4949
return cachedCliVersion;
5050
}
5151

52-
/** Caret-pinned to the CLI's own version (e.g. `^6.5.0`). */
52+
/**
53+
* The CLI's own version, EXACT (e.g. `18.0.0`, or `18.1.0-rc.2` in an RC
54+
* window) — never a `^`/`~` range. A breaking change may ship in a minor or a
55+
* patch on the v18 line, and the docs tell a project to pin exact versions.
56+
*/
5357
function pkgVersion(): string {
54-
return `^${getCliVersion()}`;
58+
return getCliVersion();
5559
}
5660

5761
/**

‎packages/cli/test/create.test.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,13 +120,14 @@ describe('os create: the sweep covers every shipped template', () => {
120120
});
121121

122122
describe.each(TEMPLATE_KEYS)('os create %s — the standalone (default) emission', (key) => {
123-
it('declares every @objectstack dependency as a published range pinned to this CLI', () => {
123+
it('declares every @objectstack dependency at the exact version of this CLI', () => {
124124
const deps = objectstackDeps(pkgJson(key, 'standalone'));
125125
expect(Object.keys(deps).length).toBeGreaterThan(0);
126126
for (const [name, spec] of Object.entries(deps)) {
127-
expect(spec, `${key}: ${name}`).toBe(`^${getCliVersion()}`);
128-
// A published range, spelled the way npm/pnpm/yarn/bun all resolve it.
129-
expect(spec, `${key}: ${name}`).toMatch(/^\^\d+\.\d+\.\d+/);
127+
expect(spec, `${key}: ${name}`).toBe(getCliVersion());
128+
// A published version with no range operator: a breaking change may ship
129+
// in a minor or a patch on the v18 line, so the docs prescribe exact pins.
130+
expect(spec, `${key}: ${name}`).toMatch(/^\d+\.\d+\.\d+/);
130131
}
131132
});
132133

‎packages/cli/test/init.test.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,10 @@ describe('init command — published scaffold', () => {
2828
}
2929
});
3030

31-
it('pins every @objectstack/* dep to the CLI version', () => {
32-
const expected = `^${pkg.version}`;
31+
// EXACT, no `^`/`~`: a breaking change may ship in a minor or a patch on
32+
// the v18 line, and the docs tell a project to pin exact versions.
33+
it('pins every @objectstack/* dep to the exact CLI version', () => {
34+
const expected = pkg.version;
3335
for (const [name, range] of Object.entries(allDeps)) {
3436
if (name.startsWith('@objectstack/')) {
3537
expect(range, name).toBe(expected);
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* `os init` and `os create` (standalone) pin every `@objectstack/*` dependency
5+
* of the project they emit to the CLI's own version, EXACTLY — no `^`, no `~`.
6+
* On the v18 line a breaking change may ship in a minor or a patch, and the
7+
* docs tell a project to pin exact versions; a caret would let the next
8+
* re-resolve move a fresh project across such a release unasked.
9+
*
10+
* `init.test.ts` and `create.test.ts` pin that against the version this
11+
* checkout carries. This file pins the shape the NEXT version pass produces
12+
* and no other test sees until it lands: a `cut-rc` pass in pre mode makes
13+
* the CLI `X.Y.Z-rc.N`, and that whole string — prerelease tail included — is
14+
* the pin. The CLI reads its version from its own `package.json` once and
15+
* caches it, so this file first imports the commands under a planted manifest read.
16+
* The in-repo placement is the control: it keeps `workspace:*`.
17+
*/
18+
19+
import { describe, it, expect, vi } from 'vitest';
20+
import fs from 'fs';
21+
import path from 'path';
22+
import { fileURLToPath } from 'url';
23+
24+
const HERE = path.dirname(fileURLToPath(import.meta.url));
25+
const CLI_MANIFEST = path.resolve(HERE, '..', 'package.json');
26+
const PRERELEASE = '18.1.0-rc.2';
27+
28+
/** Every `@objectstack/*` entry of a manifest, both dependency sections. */
29+
function objectstackDeps(pkg: {
30+
dependencies?: Record<string, string>;
31+
devDependencies?: Record<string, string>;
32+
}): [string, string][] {
33+
return Object.entries({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }).filter(
34+
([name]) => name.startsWith('@objectstack/'),
35+
);
36+
}
37+
38+
// The first import of the command modules happens HERE, under the planted
39+
// manifest read, at collection time: each test file gets its own module
40+
// registry, so no reset is needed, and module evaluation is not charged to a
41+
// hook's timeout.
42+
const realRead = fs.readFileSync;
43+
const spy = vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) =>
44+
typeof file === 'string' && path.resolve(file) === CLI_MANIFEST
45+
? JSON.stringify({ name: '@objectstack/cli', version: PRERELEASE })
46+
: (realRead as (...args: unknown[]) => unknown)(file, ...rest)) as typeof fs.readFileSync);
47+
let init: typeof import('../src/commands/init.js');
48+
let create: typeof import('../src/commands/create.js');
49+
let plantedVersion: string;
50+
try {
51+
init = await import('../src/commands/init.js');
52+
create = await import('../src/commands/create.js');
53+
// Read while the planted manifest is in place; the value is cached after.
54+
plantedVersion = init.getCliVersion();
55+
} finally {
56+
spy.mockRestore();
57+
}
58+
59+
describe('a prerelease CLI pins scaffolded @objectstack/* deps exactly', () => {
60+
// Harness guard: without it, a manifest read that escaped the spy would
61+
// measure the checkout's own release version and prove nothing about tails.
62+
it('reads the planted prerelease as the CLI version', () => {
63+
expect(plantedVersion).toBe(PRERELEASE);
64+
});
65+
66+
it('os init: every template, every @objectstack/* dep', () => {
67+
const keys = Object.keys(init.TEMPLATES);
68+
expect(keys.length).toBeGreaterThan(0);
69+
for (const key of keys) {
70+
const deps = objectstackDeps(init.TEMPLATES[key]);
71+
expect(deps.length, key).toBeGreaterThan(0);
72+
for (const [name, spec] of deps) expect(spec, `${key}: ${name}`).toBe(PRERELEASE);
73+
}
74+
});
75+
76+
it('os create (standalone): every template, every @objectstack/* dep', () => {
77+
expect(create.objectstackDependencySpec('standalone')).toBe(PRERELEASE);
78+
const keys = Object.keys(create.templates);
79+
expect(keys.length).toBeGreaterThan(0);
80+
for (const key of keys) {
81+
const pkg = create.templates[key].filesFor('standalone')['package.json']('my-thing') as {
82+
dependencies?: Record<string, string>;
83+
devDependencies?: Record<string, string>;
84+
};
85+
const deps = objectstackDeps(pkg);
86+
expect(deps.length, key).toBeGreaterThan(0);
87+
for (const [name, spec] of deps) expect(spec, `${key}: ${name}`).toBe(PRERELEASE);
88+
}
89+
});
90+
91+
it('os create --in-repo keeps workspace:* (the control)', () => {
92+
expect(create.objectstackDependencySpec('in-repo')).toBe('workspace:*');
93+
for (const key of Object.keys(create.templates)) {
94+
const pkg = create.templates[key].filesFor('in-repo')['package.json']('my-thing') as {
95+
dependencies?: Record<string, string>;
96+
devDependencies?: Record<string, string>;
97+
};
98+
for (const [name, spec] of objectstackDeps(pkg)) {
99+
expect(spec, `${key}: ${name}`).toBe('workspace:*');
100+
}
101+
}
102+
});
103+
});

‎packages/create-objectstack/src/pkg-utils.ts‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,16 @@
55
// test needs must be importable without running the CLI.
66

77
/**
8-
* Rewrite every `@objectstack/*` range in dependencies/devDependencies to
9-
* `^<version>`. All @objectstack packages version in lockstep, so the
10-
* scaffolder's own version always resolves and always matches the framework
11-
* the docs describe. No-op when the version is unknown (`0.0.0` fallback) so
12-
* a broken version read never corrupts the template's committed baseline.
8+
* Rewrite every `@objectstack/*` range in dependencies/devDependencies to the
9+
* EXACT `<version>` — no `^`, no `~`, prereleases kept verbatim. On the v18
10+
* line a breaking change may ship in a minor or a patch, so the docs tell a
11+
* project to pin exact versions; a caret here would let the next re-resolve
12+
* (`npm update`, a deleted lockfile, an install without the lock) move a new
13+
* project across such a release without anyone deciding to upgrade. All
14+
* @objectstack packages version in lockstep (the changesets `fixed` group),
15+
* so the scaffolder's own version is published for every one of them. No-op
16+
* when the version is unknown (`0.0.0` fallback) so a broken version read
17+
* never corrupts the template's committed baseline.
1318
*/
1419
export function syncObjectStackDeps(
1520
pkg: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> },
@@ -20,7 +25,7 @@ export function syncObjectStackDeps(
2025
if (!deps) continue;
2126
for (const dep of Object.keys(deps)) {
2227
if (dep.startsWith('@objectstack/')) {
23-
deps[dep] = `^${version}`;
28+
deps[dep] = version;
2429
}
2530
}
2631
}

0 commit comments

Comments
 (0)