fix(scripts): export sync-template-versions' declaration surface and guard its entry point (#9648)

The script models its targets well — a TEXT_STAMPS table and a findTemplateDirs()
walk that is deliberately not a curated list — but exported none of it and ran the
sync at module scope, so a consumer that imported it to ask which paths the version
pass writes rewrote every template instead of getting an answer.

Export stampedPaths() plus the raw declarations, and add the entry-point guard
#9064 added to check-docs-image-tag.mjs. The version read moved out of module
scope into loadScaffolderVersion(), which throws instead of exiting: an import
that can kill its host process is a worse hazard than the sync, not a smaller one.


Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-steve

packages/create-objectstack/src/template-version-stamps.test.ts

@@ -0,0 +1,304 @@
+// Copyright (c) 2026 ObjectStack contributors. Apache-2.0 license.
+//
+// The declaration surface of `scripts/sync-template-versions.mjs` (#9554).
+//
+// That script stamps three version surfaces per bundled template and discovers
+// the template set by WALKING `src/templates/` — "deliberately not a curated
+// list", because a hand-kept list is what let `specVersion` drift eleven majors
+// (#9264). But for one release it declared that set where nobody could read it:
+// nothing was exported and the sync ran at module scope, so a consumer that
+// imported the file to ask "which paths does the version pass write?" rewrote
+// every template instead of getting an answer. `cut-rc.yml`'s release-file
+// allowlist therefore RESTATED two of the paths, both hard-coding the template
+// name `blank`.
+//
+// ## Why a fixture with a SECOND template, and why that is the whole point
+//
+// The repo ships exactly one template today, so on the live tree the walk and a
+// literal `blank` pair agree and nothing is red — which is precisely why this
+// finding could only be found by reading rather than by a failing test. Every
+// assertion below that ran only against the live tree would pass just as
+// happily against a `stampedPaths()` that returned two hard-coded `blank`
+// strings. So the load-bearing cases run against a temp checkout carrying TWO
+// templates: `blank` and `second`. An implementation that restated `blank`
+// fails there, and that is the assertion that keeps this fixed rather than
+// re-found the day a second template ships.
+//
+// The same fixture is deliberately built STALE (pinning ^17 while its
+// scaffolder reads 42.0.0). That makes the import-safety assertion non-vacuous
+// in the one way that matters: an unguarded module imported against a stale
+// tree REWRITES it, so "the files are byte-identical after import" is evidence
+// only when there was something for a rewrite to do. Byte-identity over an
+// already-in-lockstep tree would prove nothing at all.
+//
+// Scope note: this file asserts the DECLARATION surface and the entry-point
+// guard. #9348 (the script has no `--self-test` and runs nowhere in CI) is a
+// separate change to the same file and is not implemented here.
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const repoRoot = path.resolve(pkgRoot, '..', '..');
+const SYNC_SCRIPT = path.join(repoRoot, 'scripts', 'sync-template-versions.mjs');
+
+/**
+ * The script is loaded the way its real consumer loads it — by URL, at run
+ * time — rather than by a static import. `cut-rc.yml` reaches it as
+ * `node -e 'import { … } from "./scripts/sync-template-versions.mjs"'`, and a
+ * `.mjs` outside this package's `rootDir` is not statically importable from
+ * `src/` anyway.
+ */
+type SyncModule = {
+  TEMPLATE_DIR: string;
+  TEMPLATE_ROOT: string;
+  TEMPLATE_PKG_FILE: string;
+  VERSION_SOURCE: string;
+  TEXT_STAMPS: { file: string; key: string; pattern: RegExp }[];
+  findTemplateDirs: (templateRoot?: string) => string[];
+  stampedPaths: (options?: { root?: string }) => string[];
+  loadScaffolderVersion: (file?: string) => { version: string; major: string; range: string };
+};
+
+const loadSync = async (file = SYNC_SCRIPT): Promise<SyncModule> =>
+  (await import(pathToFileURL(file).href)) as SyncModule;
+
+// ── the two-template fixture ────────────────────────────────────────────────
+
+/** A throwaway checkout shaped like this repo: `scripts/` + the template tree. */
+let fixture: string;
+let fixtureScript: string;
+
+/** Deliberately not the live version, so a stamp that ran is unmistakable. */
+const FIXTURE_VERSION = '42.0.0';
+/** Deliberately stale: every fixture surface pins this and must move to 42. */
+const STALE_MAJOR = '17';
+
+const FIXTURE_TEMPLATES = ['blank', 'second'] as const;
+
+const fixtureTemplateDir = (template: string) =>
+  path.join(fixture, 'packages', 'create-objectstack', 'src', 'templates', template);
+
+const writeFixtureFile = (file: string, content: string) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+};
+
+beforeAll(() => {
+  fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'sync-template-versions-9554-'));
+
+  // The script resolves its repo root from its OWN location
+  // (`dirname(dirname(import.meta.url))`), so a copy two levels above the
+  // template tree makes the fixture a complete, self-consistent checkout.
+  fixtureScript = path.join(fixture, 'scripts', 'sync-template-versions.mjs');
+  writeFixtureFile(fixtureScript, fs.readFileSync(SYNC_SCRIPT, 'utf8'));
+
+  writeFixtureFile(
+    path.join(fixture, 'packages', 'create-objectstack', 'package.json'),
+    JSON.stringify({ name: 'create-objectstack', version: FIXTURE_VERSION }, null, 2) + '\n',
+  );
+
+  for (const template of FIXTURE_TEMPLATES) {
+    const dir = fixtureTemplateDir(template);
+    writeFixtureFile(
+      path.join(dir, 'package.json'),
+      JSON.stringify(
+        {
+          name: `template-${template}`,
+          dependencies: { '@objectstack/spec': `^${STALE_MAJOR}.0.0`, chalk: '^6.0.0' },
+          devDependencies: { '@objectstack/cli': `^${STALE_MAJOR}.0.0` },
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+    writeFixtureFile(
+      path.join(dir, 'objectstack.config.ts'),
+      `export default defineStack({ manifest: { engines: { protocol: '^${STALE_MAJOR}' } } });\n`,
+    );
+    writeFixtureFile(
+      path.join(dir, 'objectstack.manifest.json'),
+      `{\n  "specVersion": "^${STALE_MAJOR}.0.0",\n  "scaffold": { "variables": [] }\n}\n`,
+    );
+  }
+
+  // A file, not a directory, beside the templates: the walk must ignore it the
+  // way the live tree's `templates/AGENTS.md` is ignored.
+  writeFixtureFile(
+    path.join(fixture, 'packages', 'create-objectstack', 'src', 'templates', 'AGENTS.md'),
+    '# not a template\n',
+  );
+});
+
+afterAll(() => {
+  if (fixture) fs.rmSync(fixture, { recursive: true, force: true });
+});
+
+/** Every fixture surface, as absolute paths. */
+const allFixtureSurfaces = () =>
+  FIXTURE_TEMPLATES.flatMap((template) =>
+    ['package.json', 'objectstack.config.ts', 'objectstack.manifest.json'].map((file) =>
+      path.join(fixtureTemplateDir(template), file),
+    ),
+  );
+
+const snapshotFixture = () =>
+  Object.fromEntries(allFixtureSurfaces().map((file) => [file, fs.readFileSync(file, 'utf8')]));
+
+// ── import safety (#9554) ───────────────────────────────────────────────────
+
+describe('sync-template-versions.mjs is import-safe', () => {
+  it('importing it against a STALE two-template checkout rewrites nothing', async () => {
+    const before = snapshotFixture();
+
+    // Anti-vacuity: the fixture must genuinely need stamping, or byte-identity
+    // below is a statement about a tree no correct implementation would touch.
+    expect(
+      Object.values(before).every((text) => text.includes(`^${STALE_MAJOR}`)),
+      'the fixture starts STALE on every surface, so an unguarded import would have work to do',
+    ).toBe(true);
+
+    await loadSync(fixtureScript);
+
+    expect(
+      snapshotFixture(),
+      'importing the module must not run the sync — the entry-point guard is what lets a ' +
+        'consumer read the declarations instead of restating them (#9554)',
+    ).toEqual(before);
+  });
+
+  it('exports the declaration surface a consumer needs', async () => {
+    const sync = await loadSync();
+    expect(typeof sync.stampedPaths).toBe('function');
+    expect(typeof sync.findTemplateDirs).toBe('function');
+    expect(typeof sync.loadScaffolderVersion).toBe('function');
+    expect(Array.isArray(sync.TEXT_STAMPS)).toBe(true);
+    expect(sync.TEXT_STAMPS.length).toBeGreaterThan(0);
+    expect(sync.TEMPLATE_DIR).toBe('packages/create-objectstack/src/templates');
+  });
+
+  it('reading the version THROWS rather than exiting the host process', async () => {
+    const sync = await loadSync();
+    const bad = path.join(fixture, 'unparseable.json');
+    fs.writeFileSync(bad, JSON.stringify({ version: 'workspace:*' }));
+    // A module-scope `process.exit(1)` on an unparseable version is a worse
+    // import hazard than the sync, not a smaller one: it kills the consumer.
+    expect(() => sync.loadScaffolderVersion(bad)).toThrow(/cannot parse/i);
+  });
+});
+
+// ── the entry point still stamps (#9554 must not break the release path) ────
+
+describe('the entry-point guard leaves the CLI path working', () => {
+  it('running the script stamps EVERY template, including the second one', () => {
+    const stdout = execFileSync(process.execPath, [fixtureScript], { encoding: 'utf8' });
+
+    for (const template of FIXTURE_TEMPLATES) {
+      const dir = fixtureTemplateDir(template);
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      expect(
+        pkg.dependencies['@objectstack/spec'],
+        `${template}/package.json @objectstack/* ranges move to the scaffolder's major`,
+      ).toBe('^42.0.0');
+      expect(pkg.devDependencies['@objectstack/cli']).toBe('^42.0.0');
+      expect(
+        pkg.dependencies.chalk,
+        'a non-@objectstack dependency is never touched',
+      ).toBe('^6.0.0');
+
+      expect(fs.readFileSync(path.join(dir, 'objectstack.config.ts'), 'utf8')).toContain(
+        "engines: { protocol: '^42' }",
+      );
+
+      const manifest = fs.readFileSync(path.join(dir, 'objectstack.manifest.json'), 'utf8');
+      expect(manifest).toContain('"specVersion": "^42.0.0"');
+      expect(
+        manifest,
+        'the manifest is rewritten as TEXT, so unrelated compact structure survives',
+      ).toContain('"scaffold": { "variables": [] }');
+    }
+
+    // A guard that made the version pass silently stop stamping would be far
+    // worse than the finding it fixes, so the run is observed to REPORT both.
+    expect(stdout).toContain('2 template(s) in lockstep with create-objectstack@42.0.0');
+    expect(stdout).toContain('second/objectstack.manifest.json');
+  });
+});
+
+// ── stampedPaths() is derived from the walk, never a restated list ──────────
+
+describe('stampedPaths()', () => {
+  it('covers every discovered template — the case a literal list fails', async () => {
+    const sync = await loadSync(fixtureScript);
+    const paths = sync.stampedPaths({ root: fixture });
+    const prefix = 'packages/create-objectstack/src/templates';
+
+    expect(paths).toEqual([
+      `${prefix}/blank/objectstack.config.ts`,
+      `${prefix}/blank/objectstack.manifest.json`,
+      `${prefix}/blank/package.json`,
+      `${prefix}/second/objectstack.config.ts`,
+      `${prefix}/second/objectstack.manifest.json`,
+      `${prefix}/second/package.json`,
+    ]);
+
+    // The finding, stated as an assertion: the pair `cut-rc.yml` spells
+    // literally is a STRICT SUBSET of what the version pass actually writes as
+    // soon as a second template exists. An implementation that restated
+    // `blank` would satisfy every other assertion in this file.
+    const literals = [
+      `${prefix}/blank/objectstack.config.ts`,
+      `${prefix}/blank/objectstack.manifest.json`,
+    ];
+    const uncovered = paths.filter((p) => !literals.includes(p));
+    expect(
+      uncovered.some((p) => p.includes('/second/')),
+      'the second template is covered by the declaration and by no literal `blank` pair',
+    ).toBe(true);
+  });
+
+  it('names only paths that exist — consumers build git pathspecs out of them', async () => {
+    const sync = await loadSync();
+    const paths = sync.stampedPaths();
+    expect(paths.length).toBeGreaterThan(0);
+    for (const p of paths) {
+      expect(p, 'repo-relative, never absolute').not.toMatch(/^([/]|[A-Za-z]:)/);
+      expect(p, 'POSIX separators — these are git pathspecs downstream').not.toContain('\\');
+      expect(fs.existsSync(path.join(repoRoot, p)), `${p} exists in this checkout`).toBe(true);
+    }
+    expect(new Set(paths).size, 'no duplicates').toBe(paths.length);
+    expect([...paths].sort(), 'stable order').toEqual(paths);
+  });
+
+  it('agrees with the live walk rather than with a remembered template set', async () => {
+    const sync = await loadSync();
+    const templates = sync.findTemplateDirs();
+    expect(templates.length).toBeGreaterThan(0);
+
+    const files = [sync.TEMPLATE_PKG_FILE, ...sync.TEXT_STAMPS.map((s) => s.file)];
+    const expected = templates
+      .flatMap((t) => files.map((f) => `${sync.TEMPLATE_DIR}/${t}/${f}`))
+      .sort();
+    expect(sync.stampedPaths()).toEqual(expected);
+  });
+
+  it('REFUSES an empty template set instead of returning an empty allowlist', async () => {
+    const sync = await loadSync();
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'sync-template-versions-empty-'));
+    fs.mkdirSync(path.join(empty, 'packages', 'create-objectstack', 'src', 'templates'), {
+      recursive: true,
+    });
+    try {
+      // An empty list reads exactly like "no template paths need staging" and
+      // means "the directory moved" — the vacuous-green shape the script's own
+      // run refuses, and the one `cut-rc.yml` already guards for the doc half.
+      expect(() => sync.stampedPaths({ root: empty })).toThrow(/no template directories/i);
+    } finally {
+      fs.rmSync(empty, { recursive: true, force: true });
+    }
+  });
+});