@metaobjectsdev/sdk 0.12.2 → 0.12.3

package/agent-context/skills/metaobjects-authoring/SKILL.md

@@ -351,7 +351,10 @@ child traversal, package only on the root segment) and/or carry `origin.*`
 children (`passthrough` / `aggregate` / `collection`) declaring assembly; its
 identity passes through via `extends` (`identity.primary: { name: id, extends:
 "Author.id" }`); it is read-only by construction and the declared field set IS
-the exposure (fail-closed).
+the exposure (fail-closed). Give it a read-only `source.rdb` `@kind: view`
+child (`source.rdb: { kind: view, table: v_author }`) — codegen keys projection
+detection + view DDL off that read-only source, so without it `meta gen` emits
+nothing for the projection.
 
 ## Abstracts + `extends` (deferred resolution) + `overlay`
 

package/agent-context/skills/metaobjects-codegen/SKILL.md

@@ -61,6 +61,40 @@ entity never emits instance/write artifacts regardless.
 Per-entity opt-outs exist (e.g. skipping client-side artifacts for a given
 entity) and are set as attributes on the entity in metadata, not in code.
 
+## You don't have to generate everything — pick your layers
+
+Codegen is **granular and à la carte, not all-or-nothing.** The most powerful
+pattern when an app's API doesn't match generated CRUD: **generate the data layer,
+hand-write only the API layer** — never abandon codegen wholesale and hand-write
+the data access too.
+
+- **Generate the data layer, skip the routes.** Omit `routesFile()` from the
+  `generators` array (keep `entityFile()` + `queriesFile()` + `barrel()`): you get
+  the typed entity/table, schemas, and query/finder helpers, then write your own
+  routes by hand — *calling the generated queries*. Do this whenever the API shape
+  (custom paths, HTML responses, nested payloads) doesn't fit generated REST CRUD.
+- **Mix generated and hand-written routes.** Even with custom paths, mount the
+  standard verbs with the runtime helpers and hand-write only the custom ones (see
+  the runtime skill's `mountCrudRoutes` / `mount<Verb>Route` / `expose`). You are
+  never forced into all-generated or all-hand-written.
+- **Derived/aggregate data → declare a projection, then USE its generated query.**
+  Don't hand-write a join or an `AVG()`/`COUNT()`. Declare an `object.projection`
+  with `origin.aggregate` / `origin.passthrough` / `origin.collection` children
+  **and a read-only `source.rdb` `@kind: view` child** (codegen detects a
+  projection by that read-only source, not by the subtype alone — omit it and
+  nothing is generated). `meta gen` emits a read-only query for it (and
+  `meta migrate` its DB view), and you **call that generated query from your
+  route**. Declaring the projection is only half the win — *consuming* its
+  generated query is the other half.
+- **Codegen is yours to extend.** A generated file carries the `@generated` header
+  and is a normal source file: copy it and customize the copy (three-way merge
+  preserves your edits on regen), or write your own `Generator` (the plugin
+  interface) and add it to the `generators` array for an artifact the built-ins
+  don't cover.
+
+`meta gen --list` prints every generator by stable name; the `generators` array in
+`metaobjects.config.ts` is where you opt each one in or out.
+
 ## Dialects
 
 Generated DB schema/DDL targets a SQL **dialect**:

package/agent-context/skills/metaobjects-runtime-ui/references/typescript.md

@@ -90,3 +90,33 @@ The routes call `parseFilterParams` (from `@metaobjectsdev/runtime-ts/drizzle-fa
 to validate `?filter[..][..]=..&sort=..&limit=&offset=` against the generated
 `<Entity>FilterAllowlist` / `<Entity>SortAllowlist`, returning HTTP 400 on an
 unknown field or disallowed operator.
+
+### Granular routes — mount some, hand-write the rest (don't read `node_modules`)
+
+When the API doesn't match generated CRUD, you don't have to choose all-generated
+or all-hand-written, and you never need to reverse-engineer the runtime package.
+`@metaobjectsdev/runtime-ts/drizzle-fastify` exports the mount helpers the generated
+routes are built from — call them directly:
+
+```ts
+import {
+  mountCrudRoutes, mountGetRoute, mountListRoute, mountReadOnlyCrudRoutes,
+} from "@metaobjectsdev/runtime-ts/drizzle-fastify";
+import { RecipeInsertSchema, RecipeUpdateSchema } from "./generated/Recipe.js";
+
+// all five verbs:
+mountCrudRoutes({ fastify: app, path: "/recipes", db, table: recipes,
+  insertSchema: RecipeInsertSchema, updateSchema: RecipeUpdateSchema });
+
+mountCrudRoutes({ ...opts, expose: ["list", "get"] }); // only some verbs
+mountReadOnlyCrudRoutes({ ...opts });                  // list + get only
+mountGetRoute({ ...opts });                            // a single verb
+```
+
+`CrudRoutesOptions` = `{ fastify, path, db, table, insertSchema, updateSchema }`
+plus `expose?` (limit verbs), `routeOptions?` (Fastify hooks — e.g.
+`{ preHandler: requireAuthHook }` for auth), and `updateMethod?` (`"patch"` default
+/ `"put"`). So **mount the standard verbs with these helpers and hand-write only the
+custom routes** (HTML pages, nested resources, computed fields) — calling the
+generated query helpers, and a projection's generated query for derived/aggregate
+data. Generate the data layer; hand-write only what's genuinely custom.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.12.2",
+    "@metaobjectsdev/metadata": "0.12.3",
     "zod": "^3.23.0"
   },
   "devDependencies": {