fix(cli): stamp engines.protocol into scaffolds and example apps (#4097) (#4239)

* fix(cli): stamp engines.protocol into scaffolds and example apps (#4097)

Booting any example app printed the ADR-0087 grandfathering warning:
the templates users copy declared no engines.protocol range, so every
derived app silently opted out of the load-time protocol handshake.

- os init (app/plugin/empty templates): generated objectstack.config.ts
  now stamps engines: { protocol: '^<PROTOCOL_MAJOR>' } — the literal
  major the scaffold was generated under, i.e. what the package was
  authored against.
- examples/app-todo, app-crm, app-showcase: declare '^17' explicitly.
  On a future protocol major bump the handshake turns these into loud
  OS_PROTOCOL_INCOMPATIBLE boot failures instead of silent admits,
  forcing a conscious example migration — which is the feature.
- init.test.ts: every template must stamp a range admitting the current
  major (guards the scaffold against regressing to no-range).

Verified: ^17 → checkProtocolCompat status 'ok' under runtime 17.0.0;
all three examples pass 'os validate'; the compiled app-todo artifact
carries engines through to the boot manifest; cli suite 89 files /
917 tests green.

The warn-vs-lint-failure policy question from #4097 is deliberately
left unchanged: absent ranges still warn at boot ('objectstack lint'
already nudges), and escalation to a compile failure can be its own
decision.

Closes #4097

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

* docs: stamp engines.protocol into the canonical config examples

The two most-copied objectstack.config.ts blocks (your-first-project,
deployment/cli configuration section) now model the same ADR-0087
engines.protocol declaration the scaffolds stamp, so hand-copied
configs don't regress to the no-range grandfathering path.

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

---------

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

Author: os-zhuang

.changeset/tender-hats-brush.md

@@ -0,0 +1,9 @@
+---
+"@objectstack/cli": patch
+---
+
+`os init` scaffolds now stamp `engines: { protocol: '^<current major>' }` into the
+generated `objectstack.config.ts` (all three templates), so newly authored packages
+participate in the ADR-0087 load-time protocol handshake instead of being admitted
+under the "no-range" grandfathering warning. The bundled example apps (`app-todo`,
+`app-crm`, `app-showcase`) now declare the same range. (#4097)

content/docs/deployment/cli.mdx

@@ -897,6 +897,8 @@ export default defineStack({
     type: 'app',
     name: 'My App',
     description: 'My ObjectStack application',
+    // Protocol major this app is authored against (ADR-0087 load-time check).
+    engines: { protocol: '^17' },
   },
 
   objects: Object.values(objects),

content/docs/getting-started/your-first-project.mdx

@@ -113,6 +113,8 @@ export default defineStack({
     version: '0.1.0',
     type: 'app',
     name: 'My App',
+    // Protocol major this app is authored against (ADR-0087 load-time check).
+    engines: { protocol: '^17' },
   },
   // `automation` runs flows and, per ADR-0097, materializes declarative
   // `connectors:` entries at boot. The three generic executors below register

examples/app-crm/objectstack.config.ts

@@ -44,6 +44,10 @@ export default defineStack({
     type: 'app',
     name: 'CRM (minimal example)',
     description: 'Minimal CRM workspace used by the framework to validate the metadata loading pipeline end-to-end.',
+    // Protocol major this package is authored against (ADR-0087). The kernel
+    // checks the range at load time and refuses a major-incompatible runtime
+    // with a structured diagnostic instead of failing deep in a schema parse.
+    engines: { protocol: '^17' },
   },
 
   // Auto-resolved by the CLI; `ui` enables the Studio shell, `automation`

examples/app-showcase/objectstack.config.ts

@@ -83,6 +83,10 @@ export default defineStack({
     type: 'app',
     name: 'ObjectStack Showcase',
     description: 'Kitchen-sink workspace covering all metadata types, all view types, and the major capability chains.',
+    // Protocol major this package is authored against (ADR-0087). The kernel
+    // checks the range at load time and refuses a major-incompatible runtime
+    // with a structured diagnostic instead of failing deep in a schema parse.
+    engines: { protocol: '^17' },
   },
 
   // Capability tokens the CLI resolves to platform plugins:

examples/app-todo/objectstack.config.ts

@@ -36,6 +36,10 @@ export default defineStack({
     type: 'app',
     name: 'Todo Manager',
     description: 'A comprehensive Todo app demonstrating ObjectStack Protocol features including automation, dashboards, and reports',
+    // Protocol major this package is authored against (ADR-0087). The kernel
+    // checks the range at load time and refuses a major-incompatible runtime
+    // with a structured diagnostic instead of failing deep in a schema parse.
+    engines: { protocol: '^17' },
   },
 
   // Seed Data (top-level, registered as metadata)

packages/cli/src/commands/init.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { Args, Command, Flags } from '@oclif/core';
+import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
 import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
@@ -143,6 +144,8 @@ export default defineStack({
     type: 'app',
     name: '${toTitleCase(name)}',
     description: '${toTitleCase(name)} application built with ObjectStack',
+    // Protocol major this app is authored against (ADR-0087 load-time check).
+    engines: { protocol: '^${PROTOCOL_MAJOR}' },
   },
 
   objects: Object.values(objects),
@@ -215,6 +218,8 @@ export default defineStack({
     type: 'plugin',
     name: '${toTitleCase(name)} Plugin',
     description: 'ObjectStack Plugin: ${toTitleCase(name)}',
+    // Protocol major this plugin is authored against (ADR-0087 load-time check).
+    engines: { protocol: '^${PROTOCOL_MAJOR}' },
   },
 
   objects: Object.values(objects),
@@ -270,6 +275,8 @@ export default defineStack({
     type: 'app',
     name: '${toTitleCase(name)}',
     description: '',
+    // Protocol major this app is authored against (ADR-0087 load-time check).
+    engines: { protocol: '^${PROTOCOL_MAJOR}' },
   },
 });
 `,

packages/cli/test/init.test.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
+import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -172,6 +173,20 @@ describe('scaffold rendering — round-trip', () => {
       fs.rmSync(tmpRoot, { recursive: true, force: true });
     }
   });
+
+  // #4097 — every scaffold stamps an `engines.protocol` range admitting the
+  // protocol major it was generated under, so new projects never boot with
+  // the ADR-0087 handshake silently skipped ("no-range" grandfathering).
+  it('stamps engines.protocol with the current protocol major in every template', () => {
+    for (const key of Object.keys(TEMPLATES)) {
+      const { tmpRoot } = renderTemplate(key as keyof typeof TEMPLATES, 'my-app');
+      const cfg = fs.readFileSync(path.join(tmpRoot, 'objectstack.config.ts'), 'utf8');
+      expect(cfg, `template "${key}" must declare engines.protocol`).toContain(
+        `engines: { protocol: '^${PROTOCOL_MAJOR}' }`,
+      );
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('detectPackageManager', () => {