@stardeck-customer-apps/compose 0.1.0

package/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: compose
+description: Regenerate a Stardeck app's Module-rail artifacts (the *.gen.ts registries and the route/endpoint stubs) from the installed Modules.
+---
+
+# @stardeck-customer-apps/compose
+
+Every Module in `apps/web/src/modules/*` declares its mounts, endpoints,
+enhancements, contributions, i18n layers and data stores in `module.json`.
+Compose turns that declaration into the code Next.js actually builds:
+
+- `apps/web/src/modules.gen.ts` — the Module registry and `isModuleEnabled`
+- `apps/web/src/module-contributions.gen.ts`
+- `apps/web/src/module-i18n.gen.ts`
+- `apps/web/src/module-init.server.gen.ts`
+- `apps/web/src/module-datastores.gen.ts`
+- one `page.tsx` / `route.ts` stub under `apps/web/src/app/**` per declared
+  mount and endpoint
+
+## Running it
+
+```bash
+npx stardeck-compose [--enabled=a,b,c] [--prune] [--cwd=<repo root>]
+```
+
+Run it from the repo root (the directory holding `apps/web`). Today you invoke
+it manually — `npx stardeck-compose` before `next dev` / `next build` / your
+typecheck — after changing any `module.json`. The `predev` / `prebuild` /
+`pretypecheck` / `pretest` wiring that makes this automatic has not landed yet.
+
+**Caveat: compose has no platform database.** It composes from `module.json`
+alone, so Module data-store bindings resolve to none (`module-datastores.gen.ts`
+comes out empty) and every Module's registry version reads `unreleased`. An app
+whose platform-side rail resolved real data-store bindings must not run compose
+until the consumer wiring supplies them — compose would otherwise overwrite the
+bindings with nothing.
+
+- `--enabled` — comma-separated **feature** Module names. Unset composes every
+  installed Module. Library and contract Modules are always composed. A name
+  that is not installed fails with exit 1. Falls back to
+  `NEXT_PUBLIC_STARDECK_ENABLED_MODULES` (how the platform passes the selection
+  at deploy time); the flag wins.
+- `--prune` — after composing, delete the source of every excluded Module, plus
+  any enhancement slice an enabled Module keeps for an excluded peer (the slice
+  imports its peer, so leaving it breaks `next build`). Requires `--enabled`,
+  a git checkout, and a clean one: it refuses when `git status --ignored`
+  reports uncommitted or ignored files under `apps/web/src/modules`, and
+  refuses outside a checkout — it is for throwaway deploy checkouts, not yours.
+
+## Rules
+
+- **Never hand-edit a generated file.** Every `*.gen.ts` and every stub carries
+  a rail marker; the next compose overwrites them, and a file whose marker is
+  missing or wrong makes compose refuse rather than clobber your edit.
+- Change `module.json` (or the Module's own source under `routes/`,
+  `contributions.ts`, `i18n/`, …) and re-run compose.
+- `@stardeck-customer-apps/compose/runtime` exports `isModuleEnabledByList`,
+  the single enablement rule, and imports nothing — it is safe in client
+  components.