feat(scripts): gate that kernel-reaching pages are declared in a discoverable shape (#12266)

What makes something a served page is membership in a manifest bundle's `pages:`
array -- verified against the kernel's own read path, not the card's prose: both
seams that admit a page (registerApp at the manifest, the nested-plugin seam in
registerPlugin) funnel into registerMetadataCollections, which reads
`source['pages']` and hands each entry to registerItem('page', ...). There is no
third entry route; definePage() is PageSchema.parse(), an authoring door whose
result still has to land in a `pages:` array.

The canonical-envelope gates (#11255 -> #11480) discover their population by
export shape instead (`export const X: Page =`), an approximation #11480
measured failing on a live page. Measuring the residual across the tree at
f11fc61 found the class still open in exactly one place: CONNECT_AGENT_PAGE
(packages/mcp), a bare `export const ... = { ... }` reaching the kernel through
CONNECT_AGENT_UI_BUNDLE.pages, in a package carrying no page gate.

check:page-declaration-shape makes the approximation exact by construction: every
IDENTIFIER entry in a `pages:` array must resolve to `export const X: Page =` or
`export const X = definePage(...)`. Judging identifier entries catches 100% of
the real population (34 entries) and admits 0% of the noise -- the 62 inline
literals are all migration fixtures in spec/conversions/registry.ts, and the 181
string entries are book/doc page-NAME lists. Comment masking is the shared
js-comment-mask.mjs, never a private stripComments.

CONNECT_AGENT_PAGE is annotated, the same type-level-only repair #11574 applied
to MarketplaceInstalledPage.


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

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

Author: yinlianghui

.changeset/page-declaration-shape-gate.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/mcp': patch
+---
+
+`CONNECT_AGENT_PAGE` is declared `: Page` (type-level only; no runtime change) so export-shape page discovery can see it. It reaches the kernel through `CONNECT_AGENT_UI_BUNDLE.pages`, but was authored as a bare `export const CONNECT_AGENT_PAGE = { … }` with per-field `as const` — the same shape `MarketplaceInstalledPage` shipped in before #11574, and invisible to the export-shape scan the canonical-envelope gates (#11255, #11480) discover their population with. A new repo-wide gate, `check:page-declaration-shape`, now closes the class: every identifier in a bundle's `pages:` array must be declared `export const X: Page =` or through `definePage()` (#11576).

.github/workflows/lint.yml

@@ -1171,6 +1171,17 @@ jobs:
       - name: React pages honour the useAdapter() query and result contracts
         run: pnpm check:react-page-adapter-contract
 
+      # #11576 page discovery vs ground truth: what makes something a SERVED
+      # page is membership in a bundle's `pages:` array (the kernel reads it in
+      # `registerMetadataCollections`), not its type annotation — while the
+      # canonical-envelope gates (#11255, #11480) discover their population by
+      # export shape. #11480 measured that gap on a live page. This gate makes
+      # the approximation exact by construction: every identifier in a `pages:`
+      # array must be declared `export const X: Page =` or via `definePage()`,
+      # so a page can never again be served-but-uncovered.
+      - name: Kernel-reaching pages are declared in a discoverable shape
+        run: pnpm check:page-declaration-shape
+
       # #10830 form-section `name` in docs examples: the docs pages that TEACH
       # the i18n-anchor convention were the one surface where nothing enforced
       # it. `packages/lint`'s `translation-section-name-missing` walks app

package.json

@@ -45,6 +45,7 @@
     "check:docs-image-tag": "node scripts/check-docs-image-tag.mjs --self-test && node scripts/check-docs-image-tag.mjs",
     "check:docs-image-tag-sync": "node scripts/sync-docs-image-tags.mjs --self-test",
     "check:react-page-adapter-contract": "node scripts/check-react-page-adapter-contract.mjs --self-test && node scripts/check-react-page-adapter-contract.mjs",
+    "check:page-declaration-shape": "node scripts/check-page-declaration-shape.mjs --self-test && node scripts/check-page-declaration-shape.mjs",
     "check:template-version-sync": "node scripts/sync-template-versions.mjs --self-test",
     "check:role-word": "node scripts/check-role-word.mjs --self-test && node scripts/check-role-word.mjs",
     "check:quick-reference-counts": "node scripts/check-quick-reference-counts.mjs --self-test && node scripts/check-quick-reference-counts.mjs",

packages/mcp/src/connect-ui.ts

@@ -18,7 +18,9 @@
  * (`OS_MCP_SERVER_ENABLED=false`) gets no page and no nav entry.
  */
 
-export const CONNECT_AGENT_PAGE = {
+import type { Page } from '@objectstack/spec/ui';
+
+export const CONNECT_AGENT_PAGE: Page = {
   name: 'connect_agent',
   label: 'Connect an Agent',
   type: 'app' as const,