Merge branch 'main' into worktree-wa4-loader-consolidation

Author: dmealing

docs/superpowers/specs/2026-05-25-fr-actionable-loader-error-messages-design.md

@@ -0,0 +1,139 @@
+# FR: Actionable JSON-shape loader errors (path + did-you-mean + fixture link)
+
+**Status:** Design proposal — needs brainstorm before implementation
+**Date:** 2026-05-25
+**Scope:** Cross-language — every port's metadata loader raises JSON-shape validation
+errors using the same `ERR_*` codes from the conformance corpus. This FR proposes a
+cross-port UX improvement.
+**Origin:** A downstream consumer onboarding to 0.6.0 reported that the "first hour with
+MO" was dominated by entity-JSON-shape iteration: typos like `enum` instead of
+`field.enum`, or forgotten `@` prefixes on attributes, produced generic
+"unknown field key X" errors with no line number, no suggestion, and no link to a
+working example.
+
+## Goal
+
+Make loader errors **actionable**: when an authored `metaobjects/*.json` doesn't validate,
+the error should tell the user:
+
+1. **Where in the JSON the problem is** — the JSON path (`metadata.root.children[2].object.entity.children[1]`).
+2. **A "did you mean" suggestion** — Levenshtein-nearest known key (`enum` → `field.enum`).
+3. **A link to a working example** — the most-relevant conformance fixture.
+
+All three are existing knowledge in the loader pipeline; surfacing them on the raised
+error reduces "time to fix" from minutes-of-grepping to seconds-of-reading.
+
+## Why this is cross-language
+
+The conformance corpus defines a fixed set of `ERR_*` codes (`ERR_UNKNOWN_TYPE`,
+`ERR_UNKNOWN_SUBTYPE`, `ERR_BAD_ATTR_VALUE`, `ERR_MISSING_REQUIRED_ATTR`,
+`ERR_RESERVED_ATTR`, etc.) that **every port emits identically**. The error code itself
+is cross-language. The *message text* attached to each error is currently per-port and
+varies in quality. This FR proposes:
+
+1. A cross-language **schema** for the error payload (path, suggestion, fixture link).
+2. Per-port **implementation** of populating that payload — Tier 3 (idiomatic) freedom
+   on the exact rendering, Tier 1 (invariant) commitment to the fields.
+
+This needs a brainstorm because the error-payload schema decision will affect Java,
+C#, Python, and TypeScript loaders simultaneously.
+
+## Current state by port (rough)
+
+| Port | Path info? | Did-you-mean? | Fixture link? |
+|---|---|---|---|
+| TypeScript (`@metaobjectsdev/metadata`) | Partial (some errors include node names) | No | No |
+| C# (`MetaObjects.Metadata`) | Partial (similar) | No | No |
+| Java (`server/java/metadata`) | Partial | No | No |
+| Python (`server/python/src/metaobjects`) | Partial | No | No |
+
+None of the four ports raises errors with the full information today, but all four
+have the information available inside the loader pipeline at the point of failure.
+
+## Brainstorm topics (open)
+
+### 1. Error payload schema — cross-language fields
+
+Strawman:
+
+```jsonc
+{
+  "code": "ERR_BAD_ATTR_VALUE",
+  "message": "Attribute '@values' on 'field.enum[ColorEnum]' must be a non-empty string array; got string",
+  "path": "metadata.root.children[0].object.entity.children[1].field.enum.@values",
+  "suggestions": [
+    "Did you mean to use the inline form '[...]' instead of a single string?",
+    "See fixtures/conformance/enum-inline/input/meta.enums.json for the canonical shape."
+  ],
+  "fixture": "enum-inline",
+  "node": { "type": "field", "subtype": "enum", "name": "ColorEnum" }
+}
+```
+
+Decisions to brainstorm:
+- What's the minimum set of fields every port must populate? (`code`, `message`, `path`
+  probably; `suggestions`, `fixture`, `node` optional?)
+- How is the payload surfaced — exception object, error response, log line, all three?
+  Per-port idiomatic.
+- How does the conformance harness verify the payload? Today it only checks
+  the `code`. Adding payload checks raises corpus expectations.
+
+### 2. "Did you mean" — distance threshold + key sources
+
+Levenshtein distance is the obvious metric. Open questions:
+- Threshold (≤ 2? ≤ 3? proportional to key length?).
+- Key universe per error type:
+  - `ERR_UNKNOWN_TYPE` → list of registered type names.
+  - `ERR_UNKNOWN_SUBTYPE` → list of registered subtypes for the type.
+  - `ERR_RESERVED_ATTR` → the reserved-keyword set.
+  - `ERR_BAD_ATTR_VALUE` for missing `@` prefix → look in the registered attr names.
+- Single best suggestion vs. ranked list of up to N?
+
+### 3. Fixture link — how does the loader know which fixture is canonical?
+
+Two approaches:
+
+**(a) Lookup table.** A registry mapping `(error_code, type, subtype)` → fixture name.
+Lives at `fixtures/conformance/ERROR_TO_FIXTURE.json`, regenerated by tooling. Each
+port loads it.
+
+**(b) Heuristic.** "Look for a fixture whose name contains the type + subtype." Fragile;
+not all fixtures follow that convention.
+
+Recommendation hypothesis: **(a)** — explicit, deterministic, regeneratable.
+
+### 4. Cross-port rollout
+
+This is a per-port implementation effort once the schema is fixed. Suggested order:
+1. Schema design + an ADR in `spec/decisions/`.
+2. TypeScript impl first (largest active consumer base).
+3. C# next (active port, full surface).
+4. Python + Java in parallel as those ports' conformance ledgers close.
+
+## Out of scope (until brainstorm)
+
+- Rewriting the loader pipeline. The payload-surfacing change should slot into existing
+  error-raising sites with minimal pipeline disturbance.
+- Localization of error message text. Strings stay English.
+- IDE / LSP integration that consumes the payload to render diagnostics inline. That's
+  a follow-up consumer — getting the payload right comes first.
+
+## Open questions
+
+1. Does the conformance harness gain payload checks, or do those stay per-port?
+2. Should the error payload field names match TypeScript convention (camelCase) across
+   all ports, or each port uses its own (`snake_case` for Python, `PascalCase` for C#)?
+   The JSON-on-the-wire form is identical regardless.
+3. Is there a desire for a `--strict-author` mode that raises *every* deviation rather
+   than the first one? Today's loader is fail-fast; multi-error reporting is a separate
+   shape.
+
+## Related work
+
+- The Documentation Provider (FR-004 family) already produces structured XML-doc and
+  COMMENT-ON output from metadata `description` / `notes` attrs. That's downstream
+  (output), not upstream (input authoring); the schemas are unrelated, but the cross-
+  port discipline is the same.
+- ADR-0006 (AI-first YAML authoring) lowers the discoverability bar somewhat by accepting
+  sigil-free attrs, but `meta.json` authoring is the canonical interchange and still
+  needs first-class error UX.

docs/superpowers/specs/2026-05-25-fr-cloudflare-workers-deploy-recipe.md

@@ -0,0 +1,118 @@
+# FR: Cloudflare Workers + Vite deploy recipe (TS docs)
+
+**Status:** Design — implementation-ready
+**Date:** 2026-05-25
+**Scope:** TypeScript / documentation only (`README.md` + a new
+`docs/recipes/cloudflare-workers.md`)
+**Origin:** Friction observed in a downstream consumer assembling Cloudflare Workers +
+Vite + MO codegen on their own — multiple sessions spent figuring out which packages run
+in V8 isolates, how to wire `meta gen` into `vite build` + `wrangler deploy`, and how to
+integrate Vite output with Workers Static Assets without wiping hand-curated files.
+
+## Goal
+
+Document MO's Cloudflare Workers story explicitly so adopters don't have to derive it.
+Cover the four constraints that took multiple sessions of trial-and-error to learn:
+
+1. Which `@metaobjectsdev/*` packages are V8-isolate compatible.
+2. How to integrate Vite output with Workers Static Assets (the `emptyOutDir: false`
+   discipline).
+3. How `meta gen` slots into the dev/build chain alongside `vite build` and `wrangler deploy`.
+4. The dev-only / build-time nature of codegen (run locally, commit output, never invoke
+   from a request handler).
+
+## Why TS-only
+
+Cloudflare Workers run V8 isolates with a Node.js compatibility flag. The constraints
+described here are JavaScript-runtime-specific. Java / C# / Python ports do not run in
+Workers and need separate deploy recipes for their respective runtimes (already-existing
+JVM containers, .NET Lambdas, FastAPI on Cloud Run, etc.) when those ports ship runtime
+surfaces.
+
+## Design
+
+### Section 1 — Which packages run in Workers
+
+| Package | Workers-compatible? | Notes |
+|---|---|---|
+| `@metaobjectsdev/cli` | Build-time only | Run on the developer's machine; never bundled. |
+| `@metaobjectsdev/metadata` | Build-time only | Same. |
+| `@metaobjectsdev/codegen-ts` | Build-time only | Same. |
+| `@metaobjectsdev/migrate-ts` | Build-time only | Migrations emit SQL, then `wrangler d1 migrations apply` runs them. |
+| `@metaobjectsdev/render` | ✅ Runtime-safe | Pure JS, no Node-only deps. |
+| `@metaobjectsdev/runtime-ts` | ❌ Node-only | Fastify + Kysely drivers. Not for Workers. |
+| `@metaobjectsdev/runtime-web` | ✅ Runtime-safe | Pure browser/edge JS. |
+| `@metaobjectsdev/react` | ✅ Runtime-safe | Browser; works in Workers if you render React on the edge. |
+| `@metaobjectsdev/tanstack` | ✅ Runtime-safe | Browser-side. |
+| Generated `<Entity>.entity.ts` / `<Entity>.queries.ts` | ✅ Runtime-safe | The generated code is the runtime; uses `drizzle-orm/d1`. |
+| Generated `<Entity>.routes.ts` | ⚠️ Mostly | The route handlers themselves are Workers-safe, but the Fastify adapter from `runtime-ts` is not. Worker adopters skip the routes generator and write their own minimal-API mounting. |
+
+### Section 2 — Vite + Workers Static Assets integration
+
+The minimum-friction shape for a Workers + Vite + MO project:
+
+```
+project-root/
+├── metaobjects/                       # MO metadata (source of truth)
+├── metaobjects.config.ts
+├── src/
+│   ├── worker.ts                      # Worker entrypoint (the SPA's API)
+│   └── ui/                            # React SPA source
+│       ├── index.html
+│       └── main.tsx
+├── public/                            # Hand-curated static (favicons, robots.txt, etc.)
+├── dist/                              # Vite output (gitignored)
+└── wrangler.toml                      # Workers config
+```
+
+`vite.config.ts` must set `build.emptyOutDir: false` if you want hand-curated files in
+`dist/` to survive a `vite build`. With Vite 5+'s default of `emptyOutDir: true`, the
+build wipes anything Vite didn't produce itself — destroying any pre-staged assets.
+
+`wrangler.toml` points `assets.directory = "./dist"` and `main = "./src/worker.ts"`.
+
+### Section 3 — Build chain
+
+The dev-time loop:
+
+```
+$ meta gen        # codegen runs locally; output is committed
+$ vite dev        # SPA dev server
+$ wrangler dev    # worker dev server (proxied for /api)
+```
+
+The deploy loop:
+
+```
+$ meta gen        # in case metadata changed; commit any drift
+$ vite build      # bundles the SPA into ./dist/
+$ wrangler deploy # uploads worker + assets
+```
+
+**`meta gen` runs once per metadata change, not per build.** The output is committed.
+A CI gate can run `meta gen` then `git diff --exit-code` to enforce that committed
+generated code matches the metadata — drift fails the build.
+
+### Section 4 — D1 migration loop
+
+```
+$ meta migrate --dialect d1 --slug my-change   # emits migrations/<seq>_my-change.sql
+$ wrangler d1 migrations apply <BINDING>       # local
+$ wrangler d1 migrations apply <BINDING> --remote   # production
+```
+
+`migrations_dir` in `wrangler.toml` and `--out-dir` in `meta migrate` should agree
+(default `migrations/` matches Wrangler's expectation).
+
+## Out of scope
+
+- A starter / template repo. Worth doing eventually; not part of this FR.
+- Edge-side cron, queue, or workflow integrations.
+- React SPA on the edge (SSR / streaming). The recipe assumes client-side render.
+
+## Open questions
+
+1. Should `routesFile()` get an optional `target: "fastify" | "workers" | "hono"` flag so
+   Workers adopters can opt into a generated minimal-API handler instead of skipping
+   route generation entirely? Useful, but a separate FR — file as follow-up if appetite
+   materializes.