fix(create-objectstack): pin the scaffolded Dockerfile's runtime image to the CLI that builds the artifact (#9115)

* fix(create-objectstack): pin the scaffolded Dockerfile's runtime image to the CLI that builds the artifact (#9017)

The blank template shipped `FROM ghcr.io/objectstack-ai/objectstack:latest`
directly beneath a comment telling the reader to pin the tag to the
`@objectstack/cli` version in their package.json — an instruction the scaffold
itself did not follow, baked into every `npx create-objectstack` app.

The tag is resolved AFTER install, from the installed CLI, not from the
generated package.json: that file carries a caret range, and npm resolves
`^17.0.0` to the newest 17.x, so pinning the range's floor would ship a runtime
image older than the CLI that built the artifact. This is the rule
scaffold-e2e.yml already applies for the same reason.

Both halves move together — the comment above the FROM line is rewritten in the
same pass, so the scaffold no longer instructs a step it just performed. With
--skip-install there is no resolved version: the tag stays `latest` and the
imperative comment stays, which is true on that path.

scaffold-e2e.yml now reads the tag it builds its local runtime image under out
of the generated Dockerfile instead of hardcoding `:latest`. Those were two
hand-matched literals; a skew would have made Docker pull the last published
image instead of the one built from this checkout, leaving the job's stated
hermeticity false while it stayed green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y26DJEHSBhhAQ6wwfsHNza

* test(create-objectstack): pin the scaffolder wiring too, not just the pin helper (#9017)

The behavioural tests call pinRuntimeImage directly, so removing the call from
index.ts would have left them green while every scaffolded app kept `latest`.
index.ts cannot be imported (program.parse() at module scope), so its text is
asserted — the same compromise template-consistency.test.ts already makes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y26DJEHSBhhAQ6wwfsHNza

---------

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

Author: os-project-manager

.changeset/scaffold-runtime-image-pinned.md

@@ -0,0 +1,49 @@
+---
+"create-objectstack": patch
+---
+
+fix(create-objectstack): the scaffolded Dockerfile pins the runtime image to the CLI that builds the artifact, instead of `latest` under a comment saying to pin (#9017)
+
+`src/templates/blank/Dockerfile` shipped `FROM ghcr.io/objectstack-ai/objectstack:latest`
+directly beneath a comment instructing the reader to "pin the tag to the
+`@objectstack/cli` version in your package.json so the runtime matches the CLI that built
+the artifact" — an instruction the scaffold itself did not follow. Every app made with
+`npx create-objectstack` shipped that contradiction from day one, and `docker/README.md`'s
+tag table already scopes `latest` to quick starts while documenting `X.Y.Z` as the
+production pin.
+
+Measured on scaffolded output rather than the template's bytes, before the fix:
+
+```
+emitted package.json cli range : ^17.0.0
+emitted Dockerfile FROM        : FROM ghcr.io/objectstack-ai/objectstack:latest
+agreement (tag vs cli range)   : DISAGREE
+```
+
+**The tag is resolved after `install`, from the installed CLI — not from the generated
+`package.json`.** That file carries a caret RANGE, and the two are not interchangeable:
+npm resolves `^17.0.0` to the newest 17.x, so pinning the range's floor would ship a
+runtime image *older* than the CLI that built the artifact — breaking the same promise in
+a new way. The rolling `:17` tag does match the range's float window but is exactly what
+the tag table tells production not to use. The resolved version is the only value that
+makes the sentence true, and it is the rule the repo already applies for this purpose in
+`.github/workflows/scaffold-e2e.yml` ("Pin the runtime's CLI to the SAME version the
+generated project actually resolved to — NOT a hardcoded `latest`").
+
+**Both halves move together.** Pinning the line while leaving an imperative to pin by hand
+would relocate the contradiction rather than remove it, so the comment above the `FROM`
+line is replaced in the same rewrite. With `--skip-install` there is no resolved version:
+the tag stays `latest` and the comment keeps telling the reader to pin — which is true on
+that path, because there the user really must do it by hand.
+
+The regression proof asserts on **scaffolded output**, never on the template: it scaffolds
+with the real copy/sync/pin path, plants an installed CLI whose version is deliberately
+*not* the range's floor (the normal case, and the one that a package.json-derived tag
+would get wrong), and checks the emitted `FROM` tag against the emitted `package.json`
+range with a satisfies-check rather than equality.
+
+`.github/workflows/scaffold-e2e.yml` now reads the tag it builds its local runtime image
+under **out of the generated Dockerfile** instead of hardcoding `:latest`. Those were two
+hand-matched literals; had they skewed, Docker would have quietly pulled the last
+published image instead of the one built from this checkout, and the job's own stated
+hermeticity would have been false while it stayed green.

.github/workflows/scaffold-e2e.yml

@@ -215,10 +215,29 @@ jobs:
         # resolved version keeps the image in lockstep whether the project got
         # the repo RC, the `latest` fallback (see the install step), or a
         # published stable.
+        #
+        # The TAG this image is built under is READ OUT OF the generated
+        # Dockerfile rather than hardcoded (#9017). The two used to be
+        # hand-matched literals — `:latest` here and `:latest` in the template —
+        # and the scaffolder now pins that tag to the CLI a project resolved, so
+        # a hardcoded tag here would stop naming the image the scaffolded
+        # `FROM` asks for. Docker would then silently pull the last PUBLISHED
+        # image instead of the one built from this checkout, and (b) above would
+        # be quietly false while the job stayed green. Deriving both from one
+        # source is what makes that skew impossible rather than merely fixed.
+        # (This job scaffolds with --skip-install, so today that tag reads
+        # `latest`; it follows the file if that ever changes.)
         run: |
           CLI_VERSION=$(node -p "require('$RUNNER_TEMP/e2e-app/node_modules/@objectstack/cli/package.json').version")
+          RUNTIME_TAG=$(sed -n 's|^FROM ghcr\.io/objectstack-ai/objectstack:||p' \
+            "$RUNNER_TEMP/e2e-app/Dockerfile")
+          if [ -z "$RUNTIME_TAG" ]; then
+            echo "::error::no FROM ghcr.io/objectstack-ai/objectstack:<tag> line in the scaffolded Dockerfile — the base image the next step builds against cannot be named, so this job would silently test a pulled image instead of this checkout"
+            exit 1
+          fi
           echo "Runtime image will bundle @objectstack/cli@$CLI_VERSION (matches the scaffolded artifact's protocol)"
-          docker build -t ghcr.io/objectstack-ai/objectstack:latest \
+          echo "Tagging it ghcr.io/objectstack-ai/objectstack:$RUNTIME_TAG (read from the scaffolded Dockerfile)"
+          docker build -t "ghcr.io/objectstack-ai/objectstack:$RUNTIME_TAG" \
             --build-arg OS_CLI_VERSION="$CLI_VERSION" \
             "$GITHUB_WORKSPACE/docker"
 

packages/create-objectstack/src/index.ts

@@ -24,8 +24,14 @@
  *   - objectstack.config.ts     manifest.id and manifest.name string literals
  *   - README.md                 first H1
  *
- * Finally we run `<pm> install` and (best-effort) install the ObjectStack
- * skills bundle via `npx skills add objectstack-ai/objectstack/skills --all`.
+ * Then we run `<pm> install` — and only afterwards can the Dockerfile's runtime
+ * image tag be pinned, because the template carries a caret range and the tag
+ * has to name the @objectstack/cli version npm actually resolved (#9017). With
+ * `--skip-install` there is no resolved version, so the template keeps `latest`
+ * and its comment keeps telling the reader to pin by hand — true in that path.
+ *
+ * Finally we (best-effort) install the ObjectStack skills bundle via
+ * `npx skills add objectstack-ai/objectstack/skills --all`.
  * The `/skills` subpath scopes discovery to the curated, customer-published
  * catalog — repo-internal skills (e.g. under `.claude/skills/`) must never
  * reach scaffolded projects.
@@ -46,6 +52,7 @@ import {
   findStaleNamespacePrefixes,
 } from './rewrite-identity.js';
 import { lookupTemplate, templateNames } from './template-registry.js';
+import { readResolvedCliVersion, pinRuntimeImage } from './runtime-image.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -348,14 +355,39 @@ const program = new Command()
 
       if (!options.skipInstall) {
         printStep('Installing dependencies...');
+        let installed = false;
         try {
           const pm = detectPackageManager();
           execSync(`${pm} install`, { stdio: 'inherit', cwd: targetDir });
+          installed = true;
           console.log('');
         } catch {
           printWarning('Dependency installation failed. Run `npm install` manually.');
           console.log('');
         }
+
+        // Pin the Dockerfile's runtime image to the CLI that will build this
+        // project's artifact — knowable only now, because the template pins a
+        // caret RANGE and npm has just resolved it (#9017). Skipped without an
+        // install: with no node_modules there is no resolved version, and the
+        // template's own comment then correctly tells the user to pin by hand.
+        if (installed) {
+          const resolved = readResolvedCliVersion(targetDir);
+          if (resolved) {
+            const result = pinRuntimeImage(targetDir, resolved);
+            if (result.pinned) {
+              printSuccess(`Dockerfile runtime image pinned to ${result.tag}`);
+            } else {
+              // Not fatal: the project is complete, the tag is just less
+              // precise than it could be. runtime-image.test.ts is the guard.
+              printWarning(
+                `Could not pin the Dockerfile runtime image (${result.reason}); ` +
+                  `it still reads \`latest\` — pin it to ${resolved} before deploying.`,
+              );
+            }
+            console.log('');
+          }
+        }
       }
 
       if (!options.skipInstall && !options.skipSkills) {