Merge pull request #289 from metaobjectsdev/fix/decouple-ui-and-raw-exec

fix: raw-exec 500 on Postgres, UI/storage decoupling, and Drizzle out of browser bundles

Author: dmealing

server/typescript/packages/codegen-ts-react/src/form-file.ts

@@ -1,6 +1,6 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import { OBJECT_ATTR_DISCRIMINATOR } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, entityOutputPath, emitsWriteArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_FORM } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, entityOutputPath, servesWriteApi, isProjection, isTphSubtype, CODEGEN_ATTR_EMIT_FORM } from "@metaobjectsdev/codegen-ts";
 import { renderFormFile } from "./templates/form-file.js";
 
 export interface FormFileOpts {
@@ -33,7 +33,11 @@ export const formFile = function formFile(opts?: FormFileOpts): Generator {
       // ADR-0039: own — @discriminator identifies a TPH base level (read own so a
       // subtype isn't mistaken for a base); e is already known not to be a subtype.
       if (typeof e.ownAttr(OBJECT_ATTR_DISCRIMINATOR) === "string") return false;
-      return emitsWriteArtifacts(e);
+      // A form is a client of a WRITE endpoint. Ask whether one exists, not where the
+      // data is stored — see api-surface.ts. `!isProjection` stays explicit here: a
+      // read-only view is a UI-tier exclusion (nothing to submit), distinct from
+      // whether write endpoints exist at all.
+      return servesWriteApi(e) && !isProjection(e);
     },
     generate: perEntity((entity, ctx) => {
       if (!ctx.renderContext) {

server/typescript/packages/codegen-ts-tanstack/src/tanstack-grid-hook.ts

@@ -1,5 +1,5 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
 import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderGridHookFile } from "./templates/grid-hook-file.js";
 
@@ -31,7 +31,7 @@ export const tanstackGridHook = function tanstackGridHook(opts?: TanstackGridHoo
   // TS2307 when the inherited layout carries an `@filter` preset (the hook then imports
   // `<sub>DefaultFilter` from the missing columns module).
   const passesOtherGates = (e: MetaObject): boolean =>
-    emitsInstanceArtifacts(e)
+    servesReadApi(e)
     // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
     && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
     && userFilter(e)
@@ -40,14 +40,23 @@ export const tanstackGridHook = function tanstackGridHook(opts?: TanstackGridHoo
     if (!ctx.renderContext) {
       throw new Error("tanstack-grid-hook: renderContext is required (provided by runGen)");
     }
-    return {
+    // Also emit the DB-free descriptor module this file imports from. Each UI
+    // generator emits it rather than relying on the consumer wiring an extra one:
+    // the entity generator is scaffold-and-own (ADR-0034), so it cannot be changed
+    // from the package. Emissions are byte-identical between generators, which the
+    // runner collapses (#266).
+    return [{
+      path: entityOutputPath(ctx.renderContext.outputLayout, entity.package,
+        entityMetaFileName(entity.name)),
+      content: await formatTs(renderEntityMetaFile(entity, ctx.renderContext.apiPrefix)),
+    }, {
       path: entityOutputPath(
         ctx.renderContext.outputLayout,
         entity.package,
         `${entity.name}.grid.ts`,
       ),
       content: await formatTs(renderGridHookFile(entity, ctx.renderContext)),
-    };
+    }];
   });
   const generator: Generator = {
     name: "tanstack-grid-hook",

server/typescript/packages/codegen-ts-tanstack/src/tanstack-grid.ts

@@ -1,5 +1,5 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
 import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderColumnsFile } from "./templates/columns-file.js";
 
@@ -24,7 +24,7 @@ export const tanstackGrid = function tanstackGrid(opts?: TanstackGridOpts): Gene
   // Split out so the discoverability note can name exactly the entities the LAYOUT
   // gate alone held back (#287) — an opted-out or abstract type is not a surprise.
   const passesOtherGates = (e: MetaObject): boolean =>
-    emitsInstanceArtifacts(e)
+    servesReadApi(e)
     // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
     && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
     && userFilter(e)

server/typescript/packages/codegen-ts-tanstack/src/tanstack-query.ts

@@ -1,5 +1,5 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK } from "@metaobjectsdev/codegen-ts";
 import { renderHooksFile } from "./templates/hooks-file.js";
 
 export interface TanstackQueryOpts {
@@ -25,17 +25,26 @@ export const tanstackQuery = function tanstackQuery(opts?: TanstackQueryOpts): G
     // FR-017 Tier 3: TPH subtypes get no standalone hooks file — their per-subtype
     // hooks live in the discriminator base's hooks file (polymorphic + per-subtype).
     // ADR-0039: resolving — a concrete entity may inherit @emitTanstack via extends.
-    filter: (e: MetaObject) => emitsInstanceArtifacts(e) && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false && !isTphSubtype(e) && userFilter(e),
+    filter: (e: MetaObject) => servesReadApi(e) && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error(
           "tanstack-query: renderContext is required (provided by runGen)",
         );
-      }
-      return {
+      }      // Also emit the DB-free descriptor module this file imports from. Each UI
+      // generator emits it rather than relying on the consumer wiring an extra
+      // generator: the entity generator is scaffold-and-own (ADR-0034), so it cannot
+      // be changed from the package. Emissions are byte-identical between generators,
+      // which the runner collapses (#266).
+      const metaFile = {
+        path: entityOutputPath(ctx.renderContext.outputLayout, entity.package,
+          entityMetaFileName(entity.name)),
+        content: await formatTs(renderEntityMetaFile(entity, ctx.renderContext.apiPrefix)),
+      };
+      return [metaFile, {
         path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.hooks.ts`),
         content: await formatTs(renderHooksFile(entity, ctx.renderContext)),
-      };
+      }];
     }),
   };
   if (opts?.target) {

server/typescript/packages/codegen-ts-tanstack/src/templates/grid-hook-file.ts

@@ -12,6 +12,17 @@ import { code, imp, joinCode, type Code } from "ts-poet";
 import type { MetaObject, MetaLayout } from "@metaobjectsdev/metadata";
 import { LAYOUT_SUBTYPE_DATA_GRID } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "@metaobjectsdev/codegen-ts";
+
+/** The DB-free descriptor sibling of an entity module: `./Author` → `./Author.meta`,
+ *  `./Author.js` → `./Author.meta.js`. The UI files take the `<Entity>` descriptor
+ *  from there so a browser bundle never pulls the Drizzle table in — it is the ONLY
+ *  value they import from the entity module; everything else is `import type`. */
+function metaModuleOf(entityModule: string): string {
+  return entityModule.endsWith(".js")
+    ? `${entityModule.slice(0, -3)}.meta.js`
+    : `${entityModule}.meta`;
+}
+
 import { GENERATED_HEADER, entityModuleSpecifier, siblingSpecifier } from "@metaobjectsdev/codegen-ts";
 
 interface GridSpec {
@@ -69,7 +80,7 @@ export function renderGridHookFile(entity: MetaObject, ctx: RenderContext): stri
   const buildFilterQsSym    = imp("buildFilterQs@@metaobjectsdev/runtime-web");
 
   const entityImports: Code = code`
-import { ${entityName} } from ${JSON.stringify(entityModule)};
+import { ${entityName} } from ${JSON.stringify(metaModuleOf(entityModule))};
 import type { ${entityName} as ${entityName}Row } from ${JSON.stringify(entityModule)};
 `;
 

server/typescript/packages/codegen-ts-tanstack/src/templates/hooks-file.ts

@@ -1,6 +1,17 @@
 import { code, imp, joinCode, Import, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import type { RenderContext, RelationEntry } from "@metaobjectsdev/codegen-ts";
+
+/** The DB-free descriptor sibling of an entity module: `./Author` → `./Author.meta`,
+ *  `./Author.js` → `./Author.meta.js`. The UI files take the `<Entity>` descriptor
+ *  from there so a browser bundle never pulls the Drizzle table in — it is the ONLY
+ *  value they import from the entity module; everything else is `import type`. */
+function metaModuleOf(entityModule: string): string {
+  return entityModule.endsWith(".js")
+    ? `${entityModule.slice(0, -3)}.meta.js`
+    : `${entityModule}.meta`;
+}
+
 import {
   GENERATED_HEADER,
   isProjection,
@@ -170,8 +181,8 @@ function renderReadOnlyHooksFile(entity: MetaObject, entityModule: string, ctx:
   const buildFilterQsSym = imp("buildFilterQs@@metaobjectsdev/runtime-web");
 
   const entityImports: Code = code`
+import { ${entityName} } from ${JSON.stringify(metaModuleOf(entityModule))};
 import {
-  ${entityName},
   type ${entityName} as ${entityName}Row,
   type ${entityName}Filter,
 } from ${JSON.stringify(entityModule)};
@@ -249,8 +260,8 @@ function renderFullHooksFile(entity: MetaObject, entityModule: string, ctx: Rend
   const buildFilterQsSym = imp("buildFilterQs@@metaobjectsdev/runtime-web");
 
   const entityImports: Code = code`
+import { ${entityName} } from ${JSON.stringify(metaModuleOf(entityModule))};
 import {
-  ${entityName},
   type ${entityName} as ${entityName}Row,
   type ${entityName}Insert,
   type ${entityName}Update,

server/typescript/packages/codegen-ts-tanstack/test/golden/__snapshots__/grid-filter/Subscriber.grid.ts

@@ -1,7 +1,7 @@
 // @generated by @metaobjectsdev/codegen-ts-tanstack — DO NOT EDIT.
 // Source metadata: Subscriber (Subscriber)
-import { Subscriber } from "./Subscriber";
 import type { Subscriber as SubscriberRow } from "./Subscriber";
+import { Subscriber } from "./Subscriber.meta";
 import { subscriberActiveFilter } from "./Subscriber.columns";
 import { buildFilterQs } from "@metaobjectsdev/runtime-web";
 import { useEntityFetcher } from "@metaobjectsdev/tanstack";

server/typescript/packages/codegen-ts-tanstack/test/golden/__snapshots__/multi-grid/Program.grid.ts

@@ -1,7 +1,7 @@
 // @generated by @metaobjectsdev/codegen-ts-tanstack — DO NOT EDIT.
 // Source metadata: Program (Program)
-import { Program } from "./Program";
 import type { Program as ProgramRow } from "./Program";
+import { Program } from "./Program.meta";
 import { buildFilterQs } from "@metaobjectsdev/runtime-web";
 import { useEntityFetcher } from "@metaobjectsdev/tanstack";
 import { useQuery } from "@tanstack/react-query";

server/typescript/packages/codegen-ts-tanstack/test/golden/__snapshots__/single-entity/Subscriber.grid.ts

@@ -1,7 +1,7 @@
 // @generated by @metaobjectsdev/codegen-ts-tanstack — DO NOT EDIT.
 // Source metadata: Subscriber (Subscriber)
-import { Subscriber } from "./Subscriber";
 import type { Subscriber as SubscriberRow } from "./Subscriber";
+import { Subscriber } from "./Subscriber.meta";
 import { buildFilterQs } from "@metaobjectsdev/runtime-web";
 import { useEntityFetcher } from "@metaobjectsdev/tanstack";
 import { useQuery } from "@tanstack/react-query";

server/typescript/packages/codegen-ts-tanstack/test/tanstack-query.test.ts

@@ -28,6 +28,12 @@ async function buildCtx(genFilter?: (e: { name: string }) => boolean): Promise<G
   };
 }
 
+const pick = (files: { path: string; content: string }[], suffix: string) => {
+  const f = files.find((x) => x.path.endsWith(suffix));
+  if (!f) throw new Error(`no emitted file ending in ${suffix} — got ${files.map((x) => x.path).join(", ")}`);
+  return f;
+};
+
 describe("tanstackQuery() factory", () => {
   test("returns a Generator named 'tanstack-query'", () => {
     const gen = tanstackQuery();
@@ -38,8 +44,7 @@ describe("tanstackQuery() factory", () => {
   test("emits Subscriber.hooks.ts with the query-key factory and 5 hooks", async () => {
     const ctx = await buildCtx();
     const files = await tanstackQuery().generate(ctx);
-    expect(files.length).toBe(1);
-    const file = files[0]!;
+        const file = pick(files, ".hooks.ts");
     expect(file.path).toBe("Subscriber.hooks.ts");
     expect(file.content).toContain("@generated by @metaobjectsdev/codegen-ts");
     // Query-key factory:
@@ -57,28 +62,28 @@ describe("tanstackQuery() factory", () => {
 
   test("mutation hooks invalidate via subscriberKeys.all()", async () => {
     const ctx = await buildCtx();
-    const file = (await tanstackQuery().generate(ctx))[0]!;
+    const file = pick(await tanstackQuery().generate(ctx), ".hooks.ts");
     // Each mutation should call invalidateQueries with subscriberKeys.all().
     const matches = file.content.match(/invalidateQueries\(\{\s*queryKey:\s*subscriberKeys\.all\(\)/g);
     expect(matches?.length).toBe(3); // create, update, delete
   });
 
   test("each hook accepts an opts override parameter", async () => {
     const ctx = await buildCtx();
-    const file = (await tanstackQuery().generate(ctx))[0]!;
+    const file = pick(await tanstackQuery().generate(ctx), ".hooks.ts");
     expect(file.content).toContain("opts?: Omit<UseQueryOptions");
     expect(file.content).toContain("opts?: Omit<UseMutationOptions");
   });
 
   test("uses Subscriber.$path from entity constants for URLs", async () => {
     const ctx = await buildCtx();
-    const file = (await tanstackQuery().generate(ctx))[0]!;
+    const file = pick(await tanstackQuery().generate(ctx), ".hooks.ts");
     expect(file.content).toContain("Subscriber.$path");
   });
 
   test("prefixes fetch URLs with Subscriber.$apiPrefix", async () => {
     const ctx = await buildCtx();
-    const file = (await tanstackQuery().generate(ctx))[0]!;
+    const file = pick(await tanstackQuery().generate(ctx), ".hooks.ts");
     // Every fetch URL should have $apiPrefix before $path so users can set apiPrefix once.
     expect(file.content).toContain("Subscriber.$apiPrefix");
     // Specifically the get-one pattern: