From f2f93d122bf0607c35eaba84adccb2fab65da578 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Wed, 22 Jul 2026 10:39:11 -0500
Subject: [PATCH 1/2] fix: resolve @cardstack/runtime-common in npm-installed
 parse
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Card code that imports `@cardstack/runtime-common`, and any card whose
`@model.<field>` value type is derived through the `primitive` unique
symbol, failed to type-check in a published install: runtime-common is a
devDependency npm doesn't install, so the bare specifier was unresolvable
and the field-value mapping collapsed to the field class.

Generate runtime-common's `.d.ts` into `bundled-types/` (plain emission —
no content-tag or `: any` annotation, so the `primitive`/`realmURL`
`unique symbol` identities survive) and alias `@cardstack/runtime-common`
+ `/*` to it in the parse tsconfig. Promotes the plain-glimmer and
runtime-common fixtures to the must-pass set; the decorator and positional
-helper gaps remain deferred.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/boxel-cli/scripts/build-types.ts     | 125 +++++++++++++++++-
 packages/boxel-cli/src/commands/parse.ts      |  10 ++
 .../boxel-cli/tests/integration/parse.test.ts |  77 ++++++-----
 3 files changed, 177 insertions(+), 35 deletions(-)

diff --git a/packages/boxel-cli/scripts/build-types.ts b/packages/boxel-cli/scripts/build-types.ts
index fef307fb3a5..c5fabc1124d 100644
--- a/packages/boxel-cli/scripts/build-types.ts
+++ b/packages/boxel-cli/scripts/build-types.ts
@@ -14,6 +14,14 @@
  *                                   --declaration --emitDeclarationOnly`).
  *                                   Source `.d.ts` files in `base/types`
  *                                   are passed through as-is.
+ * - `bundled-types/runtime-common/` — auto-generated `.d.ts` for
+ *                                   `packages/runtime-common`. See
+ *                                   `buildRuntimeCommonDts()`. Backs the
+ *                                   `@cardstack/runtime-common` path
+ *                                   alias; base's `.d.ts` import its
+ *                                   `primitive`/`realmURL` symbols and
+ *                                   field/query types, on which card
+ *                                   field-value typing depends.
  * - `bundled-types/host-types/`  — `packages/host/types/*` ambient
  *                                   `.d.ts` files, referenced via the
  *                                   `'*': ['<host>/types/*']` fallback
@@ -303,8 +311,108 @@ function annotateInferredTypes(code: string): string {
     );
 }
 
+/**
+ * Generate `.d.ts` for every module in `packages/runtime-common` and
+ * copy them into the destination. Runtime-common is plain `.ts` (no
+ * `<template>`), so unlike `base/` there's no content-tag preprocess and
+ * no `: any` annotation — the declarations emit faithfully.
+ *
+ * That fidelity is the point: `base/`'s bundled `.d.ts` imports the
+ * `primitive` / `realmURL` `unique symbol`s and the field / query types
+ * from `@cardstack/runtime-common`, and card-api's field-value mapping
+ * (`@model.someNumberField` → `number`, via `T extends { [primitive]:
+ * infer P }`) only resolves when those symbol identities are present.
+ * Card code reaches these through the `@cardstack/runtime-common` path
+ * alias in parse.ts's tsconfig.
+ */
+function buildRuntimeCommonDts(rcSrc: string, rcDst: string): void {
+  let tmpDir = mkdtempSync(join(tmpdir(), 'boxel-cli-rc-dts-'));
+  try {
+    // Copy `.ts` source into tmpDir (skip node_modules/dist/tests).
+    // Pre-existing `.d.ts` are passed through; tsc emits the rest.
+    let preexistingDts: string[] = [];
+    let walk = (dir: string): void => {
+      for (let entry of readdirSync(dir, { withFileTypes: true })) {
+        if (
+          entry.name === 'node_modules' ||
+          entry.name === 'dist' ||
+          entry.name.startsWith('.cache')
+        ) {
+          continue;
+        }
+        let full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        let rel = relative(rcSrc, full);
+        if (!rel.endsWith('.ts')) continue;
+        // Tests aren't part of the type surface and drag in test deps.
+        if (rel.endsWith('.test.ts') || rel.startsWith('tests/')) continue;
+        let dst = join(tmpDir, rel);
+        mkdirSync(dirname(dst), { recursive: true });
+        writeFileSync(dst, readFileSync(full, 'utf8'), 'utf8');
+        if (rel.endsWith('.d.ts')) preexistingDts.push(rel);
+      }
+    };
+    walk(rcSrc);
+
+    // Link host's node_modules so runtime-common's imports resolve.
+    let nodeModulesLink = join(tmpDir, 'node_modules');
+    if (!existsSync(nodeModulesLink)) {
+      execFileSync(
+        'ln',
+        [
+          '-sf',
+          join(MONOREPO_PACKAGES, 'host', 'node_modules'),
+          'node_modules',
+        ],
+        { cwd: tmpDir },
+      );
+    }
+
+    let outDir = join(tmpDir, '.dts-out');
+    let tsconfig = {
+      extends: join(MONOREPO_PACKAGES, 'host', 'tsconfig.json'),
+      compilerOptions: {
+        noEmit: false,
+        declaration: true,
+        emitDeclarationOnly: true,
+        outDir,
+        inlineSourceMap: false,
+        inlineSources: false,
+        noUnusedLocals: false,
+        noUnusedParameters: false,
+        skipLibCheck: true,
+        rootDir: tmpDir,
+      },
+      include: ['**/*.ts'],
+    };
+    let tsconfigPath = join(tmpDir, 'tsconfig.json');
+    writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2), 'utf8');
+
+    // Same sandboxed emit as base/: declarations for imports that reach
+    // outside rootDir (host, base) are dropped rather than written to
+    // their source locations.
+    runTscEmitOnly(tsconfigPath, outDir);
+
+    rmSync(rcDst, { recursive: true, force: true });
+    mkdirSync(rcDst, { recursive: true });
+    if (existsSync(outDir)) {
+      cpSync(outDir, rcDst, { recursive: true });
+    }
+    for (let rel of preexistingDts) {
+      let to = join(rcDst, rel);
+      mkdirSync(dirname(to), { recursive: true });
+      cpSync(join(tmpDir, rel), to);
+    }
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
 // ---------------------------------------------------------------------------
-// Simple-copy vendors (everything except `base/`)
+// Simple-copy vendors (everything except `base/` and `runtime-common/`)
 // ---------------------------------------------------------------------------
 
 interface Vendor {
@@ -483,6 +591,21 @@ function main(): void {
   total += baseSize;
   console.log(`${(baseSize / 1024 / 1024).toFixed(2)} MB`);
 
+  // runtime-common runs through the .d.ts pipeline too: base's bundled
+  // declarations import its symbols and types, and card field-value
+  // typing depends on them.
+  let rcSrc = join(MONOREPO_PACKAGES, 'runtime-common');
+  let rcDst = join(outRoot, 'runtime-common');
+  if (!safeIsDirectory(rcSrc)) {
+    console.error(`Missing packages/runtime-common at ${rcSrc}`);
+    process.exit(1);
+  }
+  process.stdout.write('  runtime-common … (running tsc --declaration) ');
+  buildRuntimeCommonDts(rcSrc, rcDst);
+  let rcSize = dirSize(rcDst);
+  total += rcSize;
+  console.log(`${(rcSize / 1024 / 1024).toFixed(2)} MB`);
+
   // Other vendors are simple copies with filters.
   for (let vendor of VENDORS) {
     if (!safeIsDirectory(vendor.from)) {
diff --git a/packages/boxel-cli/src/commands/parse.ts b/packages/boxel-cli/src/commands/parse.ts
index a28968419bb..4aec5bd1a3f 100644
--- a/packages/boxel-cli/src/commands/parse.ts
+++ b/packages/boxel-cli/src/commands/parse.ts
@@ -99,6 +99,14 @@ const BOXEL_UI_PATH = BUNDLED_TYPES_DIR
 const LOCAL_TYPES_PATH = BUNDLED_TYPES_DIR
   ? join(BUNDLED_TYPES_DIR, 'local-types')
   : join(PACKAGES_PATH, 'local-types');
+// `@cardstack/runtime-common` is a devDependency, so `npm install` of a
+// published CLI never installs it. Bundle its generated `.d.ts` and
+// alias the bare + subpath specifiers to it; base's bundled `.d.ts`
+// import its `primitive` symbol and field/query types, which card
+// field-value typing depends on.
+const RUNTIME_COMMON_PATH = BUNDLED_TYPES_DIR
+  ? join(BUNDLED_TYPES_DIR, 'runtime-common')
+  : join(PACKAGES_PATH, 'runtime-common');
 // Ambient module decls for paths boxel-cli doesn't ship full types
 // for (e.g. `@cardstack/boxel-icons/*` — 130MB if shipped). Generated
 // by `scripts/build-types.ts`. Only present in published / built
@@ -592,6 +600,8 @@ async function runGlintCheck(
           paths: {
             '@cardstack/base/*': [`${BASE_PKG_PATH}/*`],
             'https://cardstack.com/base/*': [`${BASE_PKG_PATH}/*`],
+            '@cardstack/runtime-common': [`${RUNTIME_COMMON_PATH}/index`],
+            '@cardstack/runtime-common/*': [`${RUNTIME_COMMON_PATH}/*`],
             '@cardstack/host/tests/*': [`${HOST_TESTS_PATH}/*`],
             '@cardstack/host/*': [`${HOST_APP_PATH}/*`],
             '@cardstack/boxel-host/commands/*': [`${HOST_APP_PATH}/commands/*`],
diff --git a/packages/boxel-cli/tests/integration/parse.test.ts b/packages/boxel-cli/tests/integration/parse.test.ts
index f3305d8c28e..5f534e40011 100644
--- a/packages/boxel-cli/tests/integration/parse.test.ts
+++ b/packages/boxel-cli/tests/integration/parse.test.ts
@@ -33,22 +33,39 @@ async function parseFixture(name: string): Promise<ParseRealmResult> {
 
 // ---------------------------------------------------------------------------
 // Primary behavior: glint runs against an npm install and the CLI's
-// tsconfig aliases resolve, so real cards type-check clean.
+// tsconfig aliases + bundled types resolve, so real cards type-check
+// clean. Each fixture pins a distinct resolution surface:
+//   - plain-glimmer: field value types (`@model.someNumberField` →
+//     `number`), which resolve through the `primitive` symbol bundled
+//     from @cardstack/runtime-common.
+//   - runtime-common: the bare `@cardstack/runtime-common` import
+//     (the `realmURL` symbol, the `Query` type).
+//   - boxel-host-tools: the `@cardstack/boxel-host/tools/*` alias + the
+//     bundled `tools/` source.
 // ---------------------------------------------------------------------------
+const CLEAN_FIXTURES: { name: string; covers: string }[] = [
+  {
+    name: 'plain-glimmer',
+    covers: 'field value types via the primitive symbol',
+  },
+  { name: 'runtime-common', covers: 'bare @cardstack/runtime-common import' },
+  { name: 'boxel-host-tools', covers: '@cardstack/boxel-host/tools/* import' },
+];
+
 describe('boxel parse (against the installed CLI)', () => {
-  it(
-    'type-checks a card importing @cardstack/boxel-host/tools/* clean',
-    async () => {
-      // Exercises the host-tools path alias + the bundled `tools/`
-      // source. Also proves glint ran end-to-end on a real card in the
-      // installed layout.
-      let result = await parseFixture('boxel-host-tools');
-      expect(result.errors).toEqual([]);
-      expect(result.status).toBe('passed');
-      expect(result.filesChecked).toBeGreaterThanOrEqual(1);
-    },
-    { timeout: 180_000 },
-  );
+  describe.each(CLEAN_FIXTURES)('$name — $covers', ({ name }) => {
+    it(
+      'type-checks clean',
+      async () => {
+        let result = await parseFixture(name);
+        // Surface the actual diagnostics on failure, not a bare count.
+        expect(result.errors).toEqual([]);
+        expect(result.status).toBe('passed');
+        expect(result.filesChecked).toBeGreaterThanOrEqual(1);
+      },
+      { timeout: 180_000 },
+    );
+  });
 
   it(
     'type-checks a .test.gts using assert.dom clean (qunit-dom augmentation)',
@@ -83,23 +100,20 @@ describe('boxel parse (against the installed CLI)', () => {
 });
 
 // ---------------------------------------------------------------------------
-// Known typing gaps, deferred to follow-up work. These are card patterns
-// that type-check clean in the monorepo (against host's real types) but
-// not yet in a published install, because the bundled types / glint
-// config don't cover them:
+// Known typing gaps, deferred to follow-up work. Two card patterns don't
+// type-check clean yet:
 //
-//   - runtime-common / field values: card-api resolves field value types
-//     (`@model.someNumberField` → `number`) through the `primitive`
-//     unique symbol imported from `@cardstack/runtime-common`. That
-//     package is a devDependency, which `npm install` of the published
-//     CLI does not install, so the mapping collapses to the field class
-//     (`NumberField`). Fix: bundle runtime-common's generated types.
-//   - decorators: `@tracked` alongside a `<template>` inside a
+//   - tracked-format-class — `@tracked` alongside a `<template>` inside a
 //     `static isolated = class … {}` expression trips glint's
 //     "Decorators are not valid here". A glint/ember-tsc transform
-//     limitation for decorators in class expressions.
-//   - helper arg shapes: the bundled `formatDateTime` typing rejects the
-//     common positional call `(formatDateTime @model.when 'MMM D')`.
+//     limitation for decorators in class expressions; it reproduces in
+//     both the monorepo and the published layout, so it isn't a
+//     bundled-types gap.
+//   - helpers-and-fields — the bundled `@cardstack/boxel-ui/helpers`
+//     `formatDateTime` typing rejects the common positional call
+//     `(formatDateTime @model.when 'MMM D')`. (Its field interpolations
+//     type-check now; the positional helper is the remaining error, and
+//     only in the published layout.)
 //
 // Marked `it.fails`: each is an expected failure while the published CLI
 // lacks support for the pattern, so it runs without failing CI. An
@@ -107,12 +121,7 @@ describe('boxel parse (against the installed CLI)', () => {
 // marker and move the case into the block above.
 // ---------------------------------------------------------------------------
 describe('boxel parse — known typing gaps (deferred)', () => {
-  const DEFERRED = [
-    'plain-glimmer',
-    'runtime-common',
-    'helpers-and-fields',
-    'tracked-format-class',
-  ];
+  const DEFERRED = ['helpers-and-fields', 'tracked-format-class'];
 
   describe.each(DEFERRED)('%s', (name) => {
     it.fails(

From 5add34c1fe5fbf224713b627446bb7d9fee40bb2 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Wed, 22 Jul 2026 12:07:01 -0500
Subject: [PATCH 2/2] test: call formatDateTime with its named format arg in
 the parse fixture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The helpers-and-fields fixture called `(formatDateTime @model.when 'MMM
D')` — a positional format the helper does not accept: its signature
takes the date positionally and options (including `format`) as named
args, matching the documented usage and the runtime, which takes an
options object. The npm-installed glint correctly rejected the positional
shape (the monorepo's leniently allowed it). Use `format='MMM D'` and
promote helpers-and-fields to the must-pass set; only the decorator gap
remains deferred.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../parse/helpers-and-fields/event.gts        |  6 ++---
 .../boxel-cli/tests/integration/parse.test.ts | 26 ++++++++++---------
 2 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/packages/boxel-cli/tests/fixtures/parse/helpers-and-fields/event.gts b/packages/boxel-cli/tests/fixtures/parse/helpers-and-fields/event.gts
index e2c2913022f..deb7dc6c706 100644
--- a/packages/boxel-cli/tests/fixtures/parse/helpers-and-fields/event.gts
+++ b/packages/boxel-cli/tests/fixtures/parse/helpers-and-fields/event.gts
@@ -9,8 +9,8 @@ import NumberField from 'https://cardstack.com/base/number';
 import TextAreaField from 'https://cardstack.com/base/text-area';
 import { formatDateTime } from '@cardstack/boxel-ui/helpers';
 
-// Exercises the common template shapes: the positional
-// `formatDateTime` helper call, and direct interpolation of
+// Exercises the common template shapes: a `formatDateTime` helper call
+// with its `format` named arg, and direct interpolation of
 // `contains(NumberField)` / `contains(TextAreaField)` values.
 export class Event extends CardDef {
   static displayName = 'Event';
@@ -19,7 +19,7 @@ export class Event extends CardDef {
   @field notes = contains(TextAreaField);
   static isolated = class extends Component<typeof Event> {
     <template>
-      <time>{{formatDateTime @model.when 'MMM D'}}</time>
+      <time>{{formatDateTime @model.when format='MMM D'}}</time>
       <span>{{@model.capacity}}</span>
       <p>{{@model.notes}}</p>
     </template>
diff --git a/packages/boxel-cli/tests/integration/parse.test.ts b/packages/boxel-cli/tests/integration/parse.test.ts
index 5f534e40011..11a506e2872 100644
--- a/packages/boxel-cli/tests/integration/parse.test.ts
+++ b/packages/boxel-cli/tests/integration/parse.test.ts
@@ -42,6 +42,10 @@ async function parseFixture(name: string): Promise<ParseRealmResult> {
 //     (the `realmURL` symbol, the `Query` type).
 //   - boxel-host-tools: the `@cardstack/boxel-host/tools/*` alias + the
 //     bundled `tools/` source.
+//   - helpers-and-fields: a `@cardstack/boxel-ui/helpers` call
+//     (`formatDateTime` with its `format` named arg) plus direct
+//     interpolation of `contains(NumberField)` / `contains(TextAreaField)`
+//     field values.
 // ---------------------------------------------------------------------------
 const CLEAN_FIXTURES: { name: string; covers: string }[] = [
   {
@@ -50,6 +54,10 @@ const CLEAN_FIXTURES: { name: string; covers: string }[] = [
   },
   { name: 'runtime-common', covers: 'bare @cardstack/runtime-common import' },
   { name: 'boxel-host-tools', covers: '@cardstack/boxel-host/tools/* import' },
+  {
+    name: 'helpers-and-fields',
+    covers: 'boxel-ui helper call + field interpolation',
+  },
 ];
 
 describe('boxel parse (against the installed CLI)', () => {
@@ -100,8 +108,7 @@ describe('boxel parse (against the installed CLI)', () => {
 });
 
 // ---------------------------------------------------------------------------
-// Known typing gaps, deferred to follow-up work. Two card patterns don't
-// type-check clean yet:
+// Known typing gap, deferred to follow-up work:
 //
 //   - tracked-format-class — `@tracked` alongside a `<template>` inside a
 //     `static isolated = class … {}` expression trips glint's
@@ -109,19 +116,14 @@ describe('boxel parse (against the installed CLI)', () => {
 //     limitation for decorators in class expressions; it reproduces in
 //     both the monorepo and the published layout, so it isn't a
 //     bundled-types gap.
-//   - helpers-and-fields — the bundled `@cardstack/boxel-ui/helpers`
-//     `formatDateTime` typing rejects the common positional call
-//     `(formatDateTime @model.when 'MMM D')`. (Its field interpolations
-//     type-check now; the positional helper is the remaining error, and
-//     only in the published layout.)
 //
-// Marked `it.fails`: each is an expected failure while the published CLI
-// lacks support for the pattern, so it runs without failing CI. An
-// unexpected pass makes `it.fails` itself fail — the signal to remove the
-// marker and move the case into the block above.
+// Marked `it.fails`: an expected failure while the CLI lacks support for
+// the pattern, so it runs without failing CI. An unexpected pass makes
+// `it.fails` itself fail — the signal to remove the marker and move the
+// case into the block above.
 // ---------------------------------------------------------------------------
 describe('boxel parse — known typing gaps (deferred)', () => {
-  const DEFERRED = ['helpers-and-fields', 'tracked-format-class'];
+  const DEFERRED = ['tracked-format-class'];
 
   describe.each(DEFERRED)('%s', (name) => {
     it.fails(