From cc887fb1f6a396990a296053733e8585f6d3d646 Mon Sep 17 00:00:00 2001 From: Ryth Azhur Date: Sun, 10 May 2026 00:16:11 -0400 Subject: [PATCH] Move codegen out of mizan-django: protocol/mizan-generate/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The codegen consumes a schema from any backend and emits typed client code for any frontend — it doesn't belong inside a backend adapter. That placement was historical sediment from when there was only a Django backend; it predates the AFI generalization. New top-level slot: `protocol/` for protocol-level tooling. Tree is now: backends/ server protocol adapters frontends/ client kernel + per-framework adapters cores/ shared language-level primitives protocol/ protocol-level tooling workers/ runtime workers / bridges Codegen moves to `protocol/mizan-generate/`. Same file layout under `generator/` (cli.mjs, lib/), preserved via git mv. Package metadata cleaned up: - name: "generate" (placeholder) → "mizan-generate" - description filled in - type: module (cli.mjs is .mjs ESM, was previously declared "commonjs") - bin entry added so `npx mizan-generate --config ` works once the package is published, instead of `node path/to/cli.mjs`. Path-reference fixups: - backends/mizan-django/README.md: `node path/to/...` → `npx mizan-generate` - backends/mizan-fastapi/README.md: same - ISSUES.md: file paths in three issue entries - CLAUDE.md: codegen description + Package Layout section refreshed (added protocol/, mizan-fastapi entry, mizan-python entry) - docs/AFI_ARCHITECTURE.md: Package Layout refreshed identically Verified codegen runs from new location: regenerated the FastAPI example harness's api/ output, identical to pre-move. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 8 ++++++-- ISSUES.md | 6 +++--- backends/mizan-django/README.md | 6 +++--- backends/mizan-django/generate/package.json | 16 ---------------- backends/mizan-fastapi/README.md | 7 +++---- docs/AFI_ARCHITECTURE.md | 6 +++++- .../mizan-generate}/generator/cli.mjs | 0 .../generator/lib/adapters/react.mjs | 0 .../generator/lib/adapters/svelte.mjs | 0 .../generator/lib/adapters/vue.mjs | 0 .../mizan-generate}/generator/lib/channels.mjs | 0 .../mizan-generate}/generator/lib/fetch.mjs | 0 .../mizan-generate}/generator/lib/index.mjs | 0 .../mizan-generate}/generator/lib/mizan.mjs | 0 .../mizan-generate}/generator/lib/stage1.mjs | 0 protocol/mizan-generate/package.json | 14 ++++++++++++++ 16 files changed, 34 insertions(+), 29 deletions(-) delete mode 100644 backends/mizan-django/generate/package.json rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/cli.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/adapters/react.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/adapters/svelte.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/adapters/vue.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/channels.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/fetch.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/index.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/mizan.mjs (100%) rename {backends/mizan-django/generate => protocol/mizan-generate}/generator/lib/stage1.mjs (100%) create mode 100644 protocol/mizan-generate/package.json diff --git a/CLAUDE.md b/CLAUDE.md index 34f21c2..a66f072 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,13 +15,17 @@ Tree organized by role. Per-framework adapters wrap a single shared kernel; code ``` backends/ server protocol adapters mizan-django/ Django adapter + mizan-fastapi/ FastAPI adapter (RPC + context + invalidation; AFI-common scope) mizan-ts/ TypeScript adapter (proves the protocol is language-agnostic) frontends/ client kernel + per-framework adapters mizan-base/ framework-agnostic kernel; owns data, status, error; adapters subscribe mizan-react/ React contexts + hooks over the kernel mizan-vue/ Vue composables over the kernel mizan-svelte/ Svelte stores/runes over the kernel -cores/ shared language-level primitives (currently empty; mizan-python forthcoming) +cores/ shared language-level primitives + mizan-python/ @client decorator, registry, MWT, HMAC cache keys; consumed by both Python backends +protocol/ protocol-level tooling + mizan-generate/ codegen — fetches schema from any backend, emits typed React/Vue/Svelte client workers/ runtime workers / bridges mizan-ssr/ Bun subprocess used by the Django template backend ``` @@ -442,7 +446,7 @@ urlpatterns = [ ## Codegen — Current State -The codegen is two-stage and per-framework. Stage 1 (in `mizan-django/generate/`) emits the framework-agnostic protocol layer (`callXxx` for mutations, `fetchXxx` for context bundles, types). Stage 2 emits per-framework hooks/composables/stores that subscribe to the `mizan-base` kernel. +The codegen is `protocol/mizan-generate/` — framework-agnostic, two-stage. Stage 1 emits the protocol layer (`callXxx` for mutations, `fetchXxx` for context bundles, types). Stage 2 emits per-framework hooks/composables/stores that subscribe to the `mizan-base` kernel. **What's in place:** diff --git a/ISSUES.md b/ISSUES.md index 2eecce9..dc8625b 100644 --- a/ISSUES.md +++ b/ISSUES.md @@ -30,7 +30,7 @@ The kernel stores only `{params, refetch}`. No `data`, `status`, `error`. Every ## Remaining High ### H5. Mutation hooks expose no loading/error state -**File:** `mizan-django/generate/generator/lib/adapters/react.mjs` +**File:** `protocol/mizan-generate/generator/lib/adapters/react.mjs` Returns bare `useCallback`. No `isPending`, `error`, `isSuccess`. ### H7. Redis SCAN blocks request path at scale @@ -38,11 +38,11 @@ Returns bare `useCallback`. No `isPending`, `error`, `isSuccess`. Synchronous SCAN at 1M keys: multi-second blocking. ### H8. Svelte codegen uses Svelte 4 stores -**File:** `mizan-django/generate/generator/lib/adapters/svelte.mjs` +**File:** `protocol/mizan-generate/generator/lib/adapters/svelte.mjs` Should use Svelte 5 `$state`/`$derived` runes. ### H9. Svelte destroy() not auto-called -**File:** `mizan-django/generate/generator/lib/adapters/svelte.mjs` +**File:** `protocol/mizan-generate/generator/lib/adapters/svelte.mjs` Memory leak if user forgets `onDestroy`. ### H12. Forms triggerValidation captures stale data diff --git a/backends/mizan-django/README.md b/backends/mizan-django/README.md index 4dd7d4b..266f23e 100644 --- a/backends/mizan-django/README.md +++ b/backends/mizan-django/README.md @@ -144,8 +144,8 @@ Frontend gets `useChatChannel({ room })`. ## Generate the frontend -The codegen lives in `backends/mizan-django/generate/`. From your frontend -project, point a config at the Django backend and run the CLI: +The codegen is `mizan-generate` (in `protocol/mizan-generate/`). From your +frontend project, point a config at the Django backend and run the CLI: ```js // frontend/django.config.mjs @@ -171,7 +171,7 @@ export default { ``` ```bash -node path/to/mizan-django/generate/generator/cli.mjs --config django.config.mjs +npx mizan-generate --config django.config.mjs ``` The codegen drives Django's management command (`export_mizan_schema`) under diff --git a/backends/mizan-django/generate/package.json b/backends/mizan-django/generate/package.json deleted file mode 100644 index 53545a8..0000000 --- a/backends/mizan-django/generate/package.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "generate", - "version": "1.0.0", - "description": "", - "main": "index.js", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "keywords": [], - "author": "", - "license": "ISC", - "type": "commonjs", - "dependencies": { - "openapi-typescript": "^7.13.0" - } -} diff --git a/backends/mizan-fastapi/README.md b/backends/mizan-fastapi/README.md index 751d07a..c27b5d1 100644 --- a/backends/mizan-fastapi/README.md +++ b/backends/mizan-fastapi/README.md @@ -108,9 +108,8 @@ anonymous request. The executor branches on those for `auth=True`, ## Generate the frontend -The codegen lives in `backends/mizan-django/generate/` (the codegen package -is framework-agnostic; the directory name is historical). Point a config at -your FastAPI app and run the CLI: +The codegen is `mizan-generate` (in `protocol/mizan-generate/`). Point a +config at your FastAPI app and run the CLI: ```js // frontend/fastapi.config.mjs @@ -133,7 +132,7 @@ export default { ``` ```bash -node path/to/mizan-django/generate/generator/cli.mjs --config fastapi.config.mjs +npx mizan-generate --config fastapi.config.mjs ``` The codegen drives `python -m mizan_fastapi.cli ` under the hood, diff --git a/docs/AFI_ARCHITECTURE.md b/docs/AFI_ARCHITECTURE.md index a9ffee9..7b25477 100644 --- a/docs/AFI_ARCHITECTURE.md +++ b/docs/AFI_ARCHITECTURE.md @@ -10,13 +10,17 @@ Tree organized by role. ``` backends/ server protocol adapters mizan-django/ Django adapter + mizan-fastapi/ FastAPI adapter (AFI-common scope) mizan-ts/ TypeScript adapter (proves the protocol is language-agnostic) frontends/ client kernel + per-framework adapters mizan-base/ framework-agnostic kernel; owns data, status, error; adapters subscribe mizan-react/ React contexts + hooks over the kernel mizan-vue/ Vue composables over the kernel mizan-svelte/ Svelte stores/runes over the kernel -cores/ shared language-level primitives (mizan-python forthcoming) +cores/ shared language-level primitives + mizan-python/ @client decorator, registry, MWT, HMAC cache keys +protocol/ protocol-level tooling + mizan-generate/ codegen — schema in, typed client out workers/ runtime workers / bridges mizan-ssr/ Bun subprocess used by the Django template backend ``` diff --git a/backends/mizan-django/generate/generator/cli.mjs b/protocol/mizan-generate/generator/cli.mjs similarity index 100% rename from backends/mizan-django/generate/generator/cli.mjs rename to protocol/mizan-generate/generator/cli.mjs diff --git a/backends/mizan-django/generate/generator/lib/adapters/react.mjs b/protocol/mizan-generate/generator/lib/adapters/react.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/adapters/react.mjs rename to protocol/mizan-generate/generator/lib/adapters/react.mjs diff --git a/backends/mizan-django/generate/generator/lib/adapters/svelte.mjs b/protocol/mizan-generate/generator/lib/adapters/svelte.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/adapters/svelte.mjs rename to protocol/mizan-generate/generator/lib/adapters/svelte.mjs diff --git a/backends/mizan-django/generate/generator/lib/adapters/vue.mjs b/protocol/mizan-generate/generator/lib/adapters/vue.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/adapters/vue.mjs rename to protocol/mizan-generate/generator/lib/adapters/vue.mjs diff --git a/backends/mizan-django/generate/generator/lib/channels.mjs b/protocol/mizan-generate/generator/lib/channels.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/channels.mjs rename to protocol/mizan-generate/generator/lib/channels.mjs diff --git a/backends/mizan-django/generate/generator/lib/fetch.mjs b/protocol/mizan-generate/generator/lib/fetch.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/fetch.mjs rename to protocol/mizan-generate/generator/lib/fetch.mjs diff --git a/backends/mizan-django/generate/generator/lib/index.mjs b/protocol/mizan-generate/generator/lib/index.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/index.mjs rename to protocol/mizan-generate/generator/lib/index.mjs diff --git a/backends/mizan-django/generate/generator/lib/mizan.mjs b/protocol/mizan-generate/generator/lib/mizan.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/mizan.mjs rename to protocol/mizan-generate/generator/lib/mizan.mjs diff --git a/backends/mizan-django/generate/generator/lib/stage1.mjs b/protocol/mizan-generate/generator/lib/stage1.mjs similarity index 100% rename from backends/mizan-django/generate/generator/lib/stage1.mjs rename to protocol/mizan-generate/generator/lib/stage1.mjs diff --git a/protocol/mizan-generate/package.json b/protocol/mizan-generate/package.json new file mode 100644 index 0000000..9a050b3 --- /dev/null +++ b/protocol/mizan-generate/package.json @@ -0,0 +1,14 @@ +{ + "name": "mizan-generate", + "version": "1.0.0", + "description": "Mizan codegen — fetches the schema from any backend adapter and emits typed React/Vue/Svelte client code on top of the runtime kernel.", + "type": "module", + "bin": { + "mizan-generate": "./generator/cli.mjs" + }, + "main": "./generator/cli.mjs", + "license": "MIT", + "dependencies": { + "openapi-typescript": "^7.13.0" + } +}