@noego/app 0.0.1

package/AGENTS.md

@@ -0,0 +1,457 @@
+Objective
+
+  - Implement a production-ready build pipeline driven by a simple CLI:
+      - app build --server index.ts --page ui/index.html
+  - Preserve the current runtime model:
+      - Single Node process serves API + SSR UI
+      - Browser loads a page that hydrates a client bundle
+  - Eliminate runtime compilation of Svelte; precompile SSR/CSR
+  - Keep server-side dynamic discovery/loading (controllers, middleware, OpenAPI, SQL) working without rewriting application code or public
+    framework interfaces
+  - Make paths predictable and configurable; handle relative/absolute dirs correctly
+
+  Entry Points
+
+  - Server entry: `noblelaw/index.ts` (spawns/hosts Express + @noego/dinner API + @noego/forge SSR UI)
+  - Page entry: `noblelaw/ui/index.html` (loads `noblelaw/ui/client.ts` to hydrate in browser)
+
+Repository Roots and Path Referencing
+
+- Unless explicitly prefixed, relative paths in this document refer to the application project root (`--root`), which in our environment is `noblelaw` at `/Users/shavauhngabay/dev/noblelaw`.
+- Source checkouts for frameworks/tools:
+  - Forge: `/Users/shavauhngabay/dev/ego/forge`
+  - Dinner: `/Users/shavauhngabay/dev/noego/dinner`
+  - Sqlstack: `/Users/shavauhngabay/dev/ego/sqlstack`
+  - App (this CLI): `/Users/shavauhngabay/dev/app`
+- Example dist outputs in this doc are under the application project: `noblelaw/dist/...`.
+
+  Current Architecture
+
+  - API
+      - @noego/dinner (source: `/Users/shavauhngabay/dev/noego/dinner`) loads OpenAPI (default noblelaw uses `noblelaw/server/stitch.yaml`), dynamically wires controllers (`noblelaw/server/controller/**`) and middleware (`noblelaw/middleware/**`) based on configured base dirs
+      - Paths are resolved with process.cwd() and are runtime file-based; both controllers base and middleware base are configurable
+  - UI SSR
+      - @noego/forge/server (source: `/Users/shavauhngabay/dev/ego/forge`) uses options from `noblelaw/ui/options.ts`
+      - In dev, Vite middleware compiles .svelte on demand
+      - In prod, must be precompiled (no loaders)
+  - Client
+      - Hydration bootstrap at `noblelaw/ui/client.ts`, page template `noblelaw/ui/index.html`
+  - DB
+      - Repositories (server/repo/**) use sqlstack decorators (source: `/Users/shavauhngabay/dev/ego/sqlstack`)
+      - sqlstack reads .sql from filesystem at runtime, adjacent to transpiled repo JS
+  - Tests/CI
+      - Jest + Python runner; not directly relevant to build targets, but artifacts must be runnable in CI
+  - Config files
+      - `noblelaw/tsconfig.json`, `noblelaw/vite.config.js`, `noblelaw/proper.json`, `noblelaw/server/stitch.yaml`, `noblelaw/ui/stitch.yaml`
+
+  Constraints and Implications
+
+  - sqlstack requires .sql files living next to the repository implementation at runtime; bundling server code breaks this unless the layout and
+    files are preserved
+  - Dinner and Forge rely on runtime files and directories (OpenAPI YAML, controller paths, middleware paths). If paths are relative to
+    process.cwd(), starting from a different CWD breaks them; if they use __dirname, relocating without mirroring structure breaks them
+  - The exact locations of controllers, middleware, and UI components are user-configurable in the app’s own options; the build must not assume fixed paths
+  - Therefore:
+      - Prefer transpile-only for server-side code (no bundling), preserving directory layout
+      - Copy all server-side assets needed at runtime: .sql, .yaml, and any file paths referenced by code
+      - Fully bundle client (CSR) and precompile SSR
+      - Replace only the dev-only Svelte/Vite compilation-on-request with precompiled SSR modules + manifests
+
+  CLI Contract
+
+  - Command: app build --server index.ts --page ui/index.html
+  - Options (all optional; default values assume noblelaw layout)
+      - --root . project root
+      - --out dist output directory root
+      - --server-root . where to resolve server entry from (default --root)
+      - --ui-root ui where to resolve the page and client entry (default dirname of --page)
+      - --controllers server/controller runtime path for controllers (copied, layout preserved) — can be any path
+      - --middleware middleware runtime middleware path (copied, layout preserved) — can be any path
+      - --openapi server/stitch.yaml server OpenAPI entry (copied)
+      - --ui-openapi ui/stitch.yaml UI OpenAPI entry for Forge (copied into UI build context or resolved via manifest)
+      - --sql-glob 'server/repo/**/*.sql' glob(s) to copy alongside transpiled server code
+      - --assets 'ui/resources/**' static assets to copy/public
+      - --client-exclude 'server/**' glob(s) to exclude from the client bundle (can be repeated)
+      - --mode production
+      - Relative paths resolve from --root unless starting with / (absolute)
+  - App must normalize all paths, make them absolute internally, and record these in manifests used at runtime
+
+  Build Requirements
+
+  - Client (CSR)
+      - Bundle/minify ui/client.ts via Vite/Rollup
+      - Output hashed assets and a client manifest (for preload and hydration tags)
+      - Honor client exclusions: replace imports matching `--client-exclude` patterns with stub modules that throw on access (ensures server-only code never ships)
+  - UI SSR
+      - Compile Svelte views/layouts to SSR modules ahead-of-time
+      - Produce an SSR bundle or set of modules and an SSR manifest mapping routes/views/layouts to module file paths
+      - No Node loader or compile-on-request in prod
+      - Allow user-supplied Vite config to extend/override defaults (see Configuration Overrides)
+  - Server
+      - Transpile-only (TS → ESM) for:
+          - index.ts, server/**, middleware/**
+      - Preserve folder structure under dist so runtime discovery continues to work
+      - Copy assets required at runtime:
+          - All .sql adjacent to repos
+          - OpenAPI YAML (server/stitch.yaml, referenced server/openapi/**)
+          - Optional UI OpenAPI YAML (ui/stitch.yaml) if Forge SSR reads it at runtime
+      - Do not inline or bundle away filesystem references expected by dinner/sqlstack/forge
+      - The resulting server entry must be able to:
+          - Serve static client assets from dist/client
+          - Import/call the precompiled SSR handler using the SSR manifest
+          - Initialize dinner with OpenAPI YAML in dist/server/...
+  - HTML template
+      - Use ui/index.html as the SSR template in prod
+      - Inject correct script/style tags and preload links using the client manifest
+
+Configuration Overrides
+
+- Principle
+  - Provide sane defaults; allow projects to extend or replace them. The application retains ultimate control over build configuration.
+
+- Vite (Client CSR)
+  - Default: App loads the project’s own `vite.config.{js,ts}` (`configFile: true`) and applies minimal, required overrides:
+    - `build.outDir = dist/client`, `build.manifest = true`, `rollupOptions.input = <resolved --page>`.
+    - Injects the client-exclude plugin when `--client-exclude` is provided.
+  - Extensibility:
+    - `--client-vite-config <path>`: use an alternate Vite config file for the client build.
+    - `--client-vite-override <json>`: deep-merge object applied after loading the config file but before enforcing invariants; last‑write wins except for required invariants.
+    - Required invariants always win: App will always set `outDir`, `manifest`, and `input` unless `--allow-override-required` is passed (not recommended).
+
+- Vite (SSR precompile)
+  - Default: reuse project Vite config with `build.ssr = true`, `outDir = dist/ui/ssr`, and `preserveModules` to keep module paths predictable.
+  - Extensibility:
+    - `--ssr-vite-config <path>`: alternate config file for SSR build.
+    - `--ssr-vite-override <json>`: deep-merge overrides (e.g., additional plugins, resolve.alias). Required invariants are enforced similarly (ssr, outDir, preserveModules input set derived from OpenAPI routes).
+
+- Forge Options Wrapper
+  - App generates `dist/server/ui/options.js` by importing compiled options and deep‑merging minimal production overrides:
+    - `development=false`, `viteOptions.root=<dist root>`, `component_dir='ui/ssr'`, `build_dir='client'`, updated `renderer` and `open_api_path`.
+  - User retains control: all original options (including custom renderer or assets) are preserved unless they conflict with production invariants. Projects may opt out (future flag) to supply their own production options module.
+
+- TypeScript/tsc
+  - App uses the project’s local TypeScript with the project’s `tsconfig.json`. Projects may customize compiler settings freely. App only changes `outDir` via CLI and performs a post‑emit ESM import extension fixup.
+
+YAML Configuration (Preferred)
+
+- Principle
+  - While every option is available via CLI, the preferred way to configure App is a YAML config file committed to the repo. This provides a single, reviewable source of truth. CLI flags remain available for ad‑hoc overrides.
+
+- Location and discovery
+  - Default filenames searched at the application root (`noblelaw`): `app.yaml`, `app.yml`, `app.config.yaml`, `app.config.yml`, or `app.config.json`.
+  - A future `--config <path>` CLI flag may explicitly point to a YAML file. Paths inside the YAML resolve relative to the YAML file itself unless absolute.
+
+- Schema (high‑level)
+  - Server
+    - `entry`: e.g., `noblelaw/index.ts`
+    - `rootDir`: e.g., `noblelaw`
+    - `controllers`: e.g., `noblelaw/server/controller`
+    - `middleware`: e.g., `noblelaw/middleware`
+    - `openapi`: e.g., `noblelaw/server/stitch.yaml`
+    - `sqlGlobs`: list of globs, e.g., `['noblelaw/server/repo/**/*.sql']`
+  - UI
+    - `page`: e.g., `noblelaw/ui/index.html`
+    - `options`: e.g., `noblelaw/ui/options.ts` (Forge server options entry)
+    - `rootDir`: e.g., `noblelaw/ui`
+    - `openapi`: e.g., `noblelaw/ui/stitch.yaml`
+    - `assets`: list of globs, e.g., `['noblelaw/ui/resources/**']`
+    - `clientExclude`: list of globs for CSR exclusions, e.g., `['noblelaw/server/**', 'noblelaw/middleware/**']`
+  - Dev
+    - `watch`: boolean
+    - `watchPaths`: list of globs (preferred)
+    - `splitServe`: boolean
+    - `frontendCmd`: e.g., `vite`
+  - Vite (extensible)
+    - `client`:
+      - `configFile`: path to a Vite config for CSR (JSON or JS)
+      - `override`: object or path to a JSON file with deep‑merge overrides
+    - `ssr`:
+      - `configFile`: path to a Vite config for SSR build
+      - `override`: object or path to a JSON file with deep‑merge overrides
+  - Output
+    - `outDir`: e.g., `noblelaw/dist`
+
+- Referencing JSON files
+  - Any `override` field under `vite.client` or `vite.ssr` may be either an inline object or a string path to a JSON file. App will load JSON and deep‑merge it into the Vite config (after the file’s own `configFile` is applied, before enforcing invariants like `outDir`).
+  - This pattern can be extended to other future sections where JSON is a convenient format.
+
+- Example: `noblelaw/app.yaml`
+  - server:
+      entry: noblelaw/index.ts
+      rootDir: noblelaw
+      controllers: noblelaw/server/controller
+      middleware: noblelaw/middleware
+      openapi: noblelaw/server/stitch.yaml
+      sqlGlobs:
+        - noblelaw/server/repo/**/*.sql
+  - ui:
+      page: noblelaw/ui/index.html
+      options: noblelaw/ui/options.ts
+      rootDir: noblelaw/ui
+      openapi: noblelaw/ui/stitch.yaml
+      assets:
+        - noblelaw/ui/resources/**
+        - noblelaw/ui/styles/**
+      clientExclude:
+        - noblelaw/server/**
+        - noblelaw/middleware/**
+  - dev:
+      watch: true
+      watchPaths:
+        - noblelaw/server/**/*.ts
+        - noblelaw/ui/openapi/**/*.yaml
+      splitServe: true
+      frontendCmd: vite
+  - vite:
+      client:
+        configFile: noblelaw/vite.config.js
+        override: noblelaw/vite.client.override.json
+      ssr:
+        configFile: noblelaw/vite.config.js
+        override:
+          build:
+            ssr: true
+            rollupOptions:
+              preserveModules: true
+  - outDir: noblelaw/dist
+
+- Precedence and merging
+  - Defaults → YAML → CLI: App starts from sane defaults, applies YAML config, then applies CLI flags as the final layer. Required invariants for production builds still apply (e.g., outDir, manifest, SSR flags), unless explicitly documented otherwise.
+
+OpenAPI‑Driven Discovery (Build/Serve Optimization)
+
+- Rationale
+  - The OpenAPI specs (server and UI stitch YAML) already declare every API route, controller reference, middleware reference, and UI view/layout. App can parse these ahead of time to optimize build and reduce required options.
+
+- What App derives
+  - Server OpenAPI (`noblelaw/server/stitch.yaml`):
+    - All controller identifiers from `x-controller` across routes.
+    - All middleware identifiers from `x-middleware`.
+  - UI OpenAPI (`noblelaw/ui/stitch.yaml`):
+    - All pages, layouts, and component paths that need SSR precompilation.
+
+- How we use it
+  - SSR entry set: feed the exact list of Svelte components (views/layouts) into the SSR Vite build, avoiding filesystem globs.
+  - Validation: after transpile/copy, verify all referenced controllers/middleware resolve under `noblelaw/dist` and fail fast with actionable errors.
+  - Manifest: emit a debug manifest including discovered controllers, middleware, and SSR components for troubleshooting.
+
+- Option minimization (sane defaults with override)
+  - If `--controllers` or `--middleware` are omitted, App attempts to infer base directories by computing the longest common directory prefix from discovered identifiers. Example: if `x-controller` uses `controllers/*.controller`, infer `noblelaw/server/controller`.
+  - If inference fails or is ambiguous, App falls back to NobleLaw defaults and warns. Users retain full control by setting flags explicitly.
+  - `--ui-openapi` remains required for SSR discovery unless the project embeds its location in code; App defaults to `noblelaw/ui/stitch.yaml`.
+
+- Serve improvements
+  - During `app serve`, App may parse OpenAPI once at startup to log missing controllers/middleware early, while still delegating runtime wiring to Dinner/Forge.
+  - Optional strict mode (future): `--strict-openapi` to fail serve/build when unresolved references are detected.
+
+  Directory and Path Semantics
+
+  - Input resolution
+      - Treat CLI values as relative to --root unless absolute
+      - --page determines --ui-root when not provided (dirname of --page)
+  - Output layout (example)
+      - `noblelaw/dist/server/**` transpiled JS, mirrored structure of `noblelaw/server/**` and `noblelaw/middleware/**`, plus copied `.sql` and `noblelaw/server/openapi/**`, `noblelaw/server/stitch.yaml`
+      - `noblelaw/dist/client/**` bundled CSR assets + `manifest.json`
+      - `noblelaw/dist/ssr/**` SSR bundle/modules + `ssr-manifest.json` (or embed SSR output under `noblelaw/dist/server/ssr/**`)
+  - Runtime path resolution
+      - All server code that used process.cwd() should continue to work if server is launched with cwd at dist root OR the dist structure mirrors
+        source-tree paths
+      - App must ensure:
+          - Dinner’s `openapi_path` points to a real YAML under `noblelaw/dist/server/...`
+          - Forge’s `open_api_path` resolves correctly under `noblelaw/dist` (either copy UI YAML or generate a stitched snapshot consumed by SSR)
+          - sqlstack finds `.sql` files next to the transpiled repo JS under `noblelaw/dist/server/repo/**`
+      - If any path cannot be made to resolve from cwd reliably, App provides a tiny generated bootstrap wrapper that rewrites those path
+        strings to __dirname-based equivalents at build time (no change to public interfaces)
+
+Path Customization and Framework Mapping
+
+- Dinner (API)
+  - controllers_base_path: absolute base directory for resolving x-controller identifiers. The identifiers in OpenAPI (e.g., controllers/user.controller) are paths relative to this base, without extensions.
+  - middleware_path: absolute base directory for resolving x-middleware identifiers. If omitted, Dinner falls back to controllers_base_path, then process.cwd().
+  - Resolution behavior: Dinner computes module paths with path.resolve(process.cwd(), path.join(base, id)). This is why setting process.cwd() correctly at runtime matters.
+  - Implication: You can place controllers and middleware anywhere; keep x-controller and x-middleware stable, and change only the base paths.
+
+- Forge (SSR/UI)
+  - component_dir: directory containing Svelte components (layouts, views), resolved relative to viteOptions.root.
+  - build_dir: directory for client build output served statically in production.
+  - renderer: HTML template path for SSR; in production, Forge reads the file contents at startup.
+  - open_api_path: path to the UI OpenAPI (stitch) YAML used to build the manifest; resolved relative to viteOptions.root.
+  - middleware_path: optional base for UI middleware; resolved similar to Dinner.
+  - Assets: a map of mountPath -> [directories], served from viteOptions.root in production.
+  - Dev vs prod: in dev Vite compiles on demand; in prod, ProdComponentLoader loads precompiled SSR modules from component_dir.
+
+- Sqlstack (DB)
+  - Decorators load .sql files from the filesystem at runtime next to the compiled repo JS. Dialect variants are supported (e.g., find.sql, find.sqlite.sql).
+  - Root directory for SQL resolution is inferred from decorator location or explicitly passed via @Query(). No bundling or inlining — files must exist at runtime.
+
+- App CLI flags → runtime mapping
+  - --controllers: the source directory to mirror into dist for runtime controller discovery. Must correspond to the app’s controllers_base_path at runtime. Defaults to server/controller for NobleLaw, but any path is valid.
+  - --middleware: the source directory to mirror into dist for runtime middleware discovery. Must correspond to the app’s middleware_path (or controllers_base_path fallback). Defaults to middleware for NobleLaw.
+  - --openapi / --ui-openapi: OpenAPI stitch YAML locations for API and UI. App copies these into dist/server and dist/ui respectively.
+  - --sql-glob: one or more glob patterns for SQL files to copy next to compiled JS outputs. Use this to support custom repo locations.
+  - --page / --ui-root: determines client entry and build root used by Vite; paths are normalized relative to --root unless absolute.
+  - All paths accept non-default, project-specific layouts — App normalizes to absolute and preserves structure under dist.
+
+How App Preserves Flexibility
+
+- CWD bootstrap: The generated dist/server/index.js sets process.chdir(distRoot) before importing the compiled entry. This makes Dinner and Forge path resolution (which are CWD-relative) behave identically to dev.
+- Layout mirroring: App transpiles without bundling and copies the resulting JS tree so relative relationships are preserved (e.g., server/controller/**, server/repo/**). Middleware is mirrored under dist/middleware or as configured.
+- Options wrapper (Forge): App wraps ui/options.js in dist to set viteOptions.root to the dist root and points component_dir to precompiled SSR (ui/ssr), build_dir to client, and updates renderer/open_api_path to dist paths. This preserves Forge’s public API while switching from dev loaders to precompiled modules.
+- Asset copying: OpenAPI YAML trees and SQL globs are copied verbatim so runtime file-based discovery continues to work.
+
+ESM Import Extensions (Server JS)
+
+- Problem
+  - Node’s native ESM loader requires explicit file extensions for relative imports (e.g., `import x from './foo.js'`).
+  - TypeScript source commonly uses extensionless relative imports (preferred) and directory imports (e.g., `import './repo'`). These compile verbatim and will fail at runtime without a loader.
+
+- Policy
+  - Source TS: extensionless relative imports are allowed and preferred by default. Projects may opt to include `.js` in TS if they want; App supports both styles.
+  - No dev loaders in production: we will not rely on ts-node/tsx or custom Node loaders to fix extensions at runtime.
+
+- Build-time Fixup
+  - After TSC emits ESM, App rewrites import specifiers in emitted `.js` files to be Node‑compatible:
+    - Relative specifiers without extensions: `./foo` → `./foo.js` when `foo.js` exists in dist.
+    - Directory specifiers: `./repo` → `./repo/index.js` when `repo/index.js` exists in dist.
+    - Explicit TS extensions: `./foo.ts` → `./foo.js`.
+    - Already‑extended (`.js`, `.mjs`, `.cjs`, `.json`) are left unchanged.
+    - Non‑relative (bare) specifiers and built‑ins are never modified.
+  - Dynamic imports: simple string literals (e.g., `import('./foo')`) are fixed the same as static. Template or computed specifiers are not rewritten; authors should ensure those resolve to valid `.js` at runtime.
+
+- Opt‑out / Control
+  - If a project prefers writing `.js` extensions in TS or already manages extensions, App’s fixup is conservative and will not double‑append.
+  - Future flag (planned): allow disabling or customizing rewrite rules if a repository has bespoke needs.
+
+- Why this approach
+  - Keeps server build transpile‑only (no bundling) while producing ESM that runs under Node without loaders.
+  - Preserves directory layout so Dinner/Forge/Sqlstack file discovery still works.
+
+Client Bundle Exclusions
+
+- Goal
+  - Prevent accidental inclusion of server-only code in the browser bundle while allowing projects to keep shared TypeScript without extensions.
+
+- CLI
+  - `--client-exclude <glob>`: may be specified multiple times. Paths are resolved relative to `--root` unless absolute. Example defaults for NobleLaw: `server/**`, `middleware/**`.
+
+- Behavior
+  - During the Vite/Rollup client build, App installs a plugin that intercepts resolved module IDs. If the absolute file path matches any exclusion pattern, the loader returns a virtual stub module instead of the real source.
+  - The stub exports proxies that throw when accessed at runtime. This avoids leaking server implementation into the client and makes violations visible during testing.
+
+- Stub semantics
+  - Static import: `import x from 'excluded'` → the module evaluates, but any property access throws a clear error: “Excluded from client bundle: <path>”.
+  - Named imports: accessing any named export throws the same error.
+  - Dynamic import with a literal path is also stubbed; computed/templated specifiers are not guaranteed to be caught and should be avoided for server-only modules.
+
+- Notes
+  - The stub design preserves tree-shaking; unused excluded imports can be eliminated.
+  - This mechanism complements, not replaces, SSR/Prod separation in Forge. It specifically guards the CSR client build.
+
+Non‑Default Layout Examples
+
+- Controllers under src/api/controllers and middleware under app/mw:
+  - app build --controllers src/api/controllers --middleware app/mw
+  - Dinner options should set controllers_base_path and middleware_path accordingly; App will mirror these into dist preserving structure.
+- Repositories under backend/data/repos with SQL under backend/data/sql:
+  - app build --sql-glob 'backend/data/**/*.sql'
+  - Sqlstack will find .sql files next to compiled JS in dist as long as the relative adjacency is preserved.
+- OpenAPI files under config/api/stitch.yaml and config/ui/stitch.yaml:
+  - app build --openapi config/api/stitch.yaml --ui-openapi config/ui/stitch.yaml
+  - App copies them into dist/server and dist/ui respectively; runtime code reads the copies via CWD-relative paths.
+
+  Development vs Production
+
+  - Dev
+      - Keep current dev flow (Vite HMR, dynamic load) unchanged
+      - app serve runs the uncompiled project:
+        - Uses the project’s TypeScript directly via `tsx` (preferred) or `ts-node` if available
+        - Injects Forge dev loader automatically when present (`--loader @noego/forge/loader`) so SSR behaves like today
+        - Runs with `NODE_ENV=development` and cwd at `--root`
+        - Optional file watching and auto‑restart:
+          - `--watch` enables restart on server‑side changes
+          - `--watch-path <glob>` adds additional watch patterns (repeatable). Preferred: use globs to cover directories rather than listing many files.
+          - Defaults watch: controllers, middleware, server OpenAPI (and openapi/**), UI OpenAPI (and openapi/**), and SQL globs
+          - UI Svelte/TS/CSS/HTML under `noblelaw/ui/**` are excluded from restart and continue to reload via Vite HMR
+        - Optional split processes in watch mode:
+          - `--split-serve` starts the frontend dev server (vite) as a separate process so API restarts don’t disrupt HMR
+          - `--frontend-cmd vite` selects the frontend runner (currently only vite supported)
+          - Note: projects integrating Forge’s dev Vite server inside Express may need to disable that integration to avoid duplicate Vite instances when using split-serve
+  - Prod
+      - No tsx loaders or custom Node loaders
+      - No Svelte compilation on request
+      - No OpenAPI generation on request beyond reading YAML
+      - No sqlstack SQL inlining; actual .sql files must exist at runtime
+
+  Allowed Framework Changes (non-breaking)
+
+  - Forge
+      - Add a production SSR build target that emits SSR modules and an SSR manifest
+      - Add an option to read UI OpenAPI from a pre-stitched JSON artifact (optional optimization) but keep YAML support by default
+      - Ensure serverOnlyStub plugin is dev-only
+  - Dinner
+      - Allow openapi_path to be YAML or a pre-stitched JSON; retain current API
+      - No change to controller/middleware builder/caller interfaces
+  - Sqlstack
+      - No API changes; optionally expose a pluggable resolver to support alternate asset locations (not required if we copy files)
+      - Document environment variable to set default dialect if needed (e.g., SQLITE)
+
+  Functional Behavior Required After Build
+
+  - Server starts from dist/server/index.js (or equivalent)
+      - Serves API routes per OpenAPI; controllers/middleware load dynamically from dist paths
+      - Serves UI routes SSR using precompiled SSR modules and SSR manifest
+      - Serves static client assets from dist/client
+  - Browser navigation
+      - Initial request returns SSR HTML, includes preload links from client manifest, hydrates successfully
+      - Client-side navigation fetches prebuilt code-split chunks; no server-side Svelte compilation
+  - SQL execution
+      - sqlstack reads .sql from dist/server/repo/** with expected naming (findUser.sql, findUser.sqlite.sql, etc.)
+  - OpenAPI
+      - YAML files are present under dist/server/openapi/** and are correctly referenced
+
+  Acceptance Criteria
+
+  - Running app build --server index.ts --page ui/index.html produces:
+      - `noblelaw/dist/server` transpiled ESM with mirrored structure and copied `.sql`, OpenAPI YAML
+      - `noblelaw/dist/client` minified assets + client manifest
+      - `noblelaw/dist/ssr` precompiled SSR output + SSR manifest (or nested under `noblelaw/dist/server/ssr`)
+  - Starting node dist/server/index.js:
+      - API endpoints function unchanged
+      - GET / returns SSR HTML; hydration works
+      - Navigating CSR-only routes loads hashed chunks without 500s or on-demand compilation
+  - No dependency on tsx, custom Node loaders, or dev-only Vite middlewares in production
+  - No changes to public interfaces of Forge, Dinner, or Sqlstack; only configuration/tooling/paths adjusted
+  - CI can run npm ci && npm run build && node dist/server/index.js and tests target the running server successfully
+
+  Implementation Notes
+
+  - Prefer multi-build with Vite/Rollup:
+      - CSR client: entry ui/client.ts (page ui/index.html), emits client manifest
+      - SSR: static SSR entry generated by Forge from OpenAPI UI routes; emits SSR manifest
+      - Server: transpile-only with esbuild/tsc; copy assets (.sql, .yaml)
+  - Path handling policy
+      - Record both source and output absolute paths inside a build manifest for troubleshooting
+      - If the app is started from outside dist, require cwd to be dist (documented), or generate a wrapper that sets process.chdir(__dirname +
+        '/../') at startup
+  - Defaults for noblelaw
+      - --root .
+      - --server index.ts
+      - --page ui/index.html
+      - --controllers server/controller (customizable)
+      - --middleware middleware (customizable)
+      - --openapi server/stitch.yaml
+      - --ui-openapi ui/stitch.yaml
+      - --sql-glob 'server/repo/**/*.sql'
+      - --client-exclude 'server/**,middleware/**'
+      - --out dist
+
+
+
+Framework Reference
+`/Users/shavauhngabay/dev/ego/forge`
+`/Users/shavauhngabay/dev/noego/dinner`
+`/Users/shavauhngabay/dev/ego/sqlstack`
+
+
+Project Reference
+`/Users/shavauhngabay/dev/noblelaw`

package/bin/app.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../src/cli.js').catch((error) => {
+  console.error('[app] failed to start CLI:', error);
+  process.exitCode = 1;
+});

package/docs/design.md

@@ -0,0 +1,107 @@
+# App Build CLI – Design Notes
+
+## Goals
+- Provide reproducible `app build` and `app serve` commands for NobleLaw-style projects.
+- Preserve the runtime contract of Dinner/Forge/Sqlstack by keeping file-based discovery working after build.
+- Precompile Svelte (SSR + CSR) so production servers no longer rely on loader-based compilation.
+- Ensure all runtime paths remain predictable by normalising to `--root`, copying required assets, and generating bootstrap/manifests.
+- Prefer declarative configuration (`app.yaml`) with CLI overrides for ad-hoc tweaks.
+
+## Configuration Resolution
+1. **Defaults** — baked into App, biased toward NobleLaw layout.
+2. **YAML config** — auto-discovered (`app.yaml`, `app.yml`, or `app.config.yaml` inside `--root`). Future: explicit `--config`.
+3. **CLI flags** — highest precedence.
+
+All relative paths resolve against the config file’s directory (for YAML) or `--root` (for CLI). The merged configuration is normalised into absolute paths and fan-out structures (`BuildConfig`) used downstream.
+
+Key fields:
+- `server`: entry, rootDir, controllers, middleware, openapi, sqlGlobs.
+- `ui`: page, rootDir, openapi, assets, clientExclude globs.
+- `vite`: optional overrides for CSR/SSR builds (config file + JSON override).
+- `dev`: serve-mode toggles (watch, watchPaths, splitServe, frontendCmd).
+- `outDir`: build destination.
+
+App records the merged config and important paths in a build manifest for auditing.
+
+## High-Level Pipeline
+1. **Path Resolution**
+   - Parse CLI options, defaulting to the NobleLaw layout.
+   - Resolve every user-supplied path relative to `--root` unless already absolute.
+   - Produce an internal `BuildConfig` with absolute `root`, `out`, `serverEntry`, `uiRoot`, `openApi`, `sqlGlobs`, etc.
+   - Record both source and output paths in a build manifest for troubleshooting.
+
+2. **Workspace Prep**
+   - Clean the target `--out` directory.
+   - Create a deterministic staging area (`.app/tmp`) for compiler outputs before reshaping into the final layout.
+
+3. **OpenAPI Discovery**
+   - Read stitched OpenAPI specs (server + UI) ahead of time.
+   - Extract controller + middleware identifiers (server) and view/layout component paths (UI).
+   - Use results to:
+     - Validate that expected files are emitted into `dist`.
+     - Derive SSR input set and infer controller/middleware base dirs when options omitted.
+     - Populate debug manifest (list of routes/components).
+
+4. **Server Build (TS ➜ JS)**
+   - Invoke the project’s own TypeScript compiler (`tsc`) with `outDir={tmp}/server` so compiler options (decorators, metadata) stay consistent.
+   - Copy the resulting JS tree into `dist/server`, flattening `tmp/server/**/*` so controllers end up at `dist/server/controller`, repos at `dist/server/repo`, etc.
+   - Copy TS outputs for `ui/**/*` into `dist/server/ui` to satisfy imports like `./ui/frontend`.
+   - Copy middleware outputs into `dist/middleware` (Dinner & Forge middleware lookup).
+   - Move the compiled entry `index.js` aside and generate a bootstrap `dist/server/index.js` that:
+     - Resolves `__dirname`, calls `process.chdir(<dist root>)` so `process.cwd()`-relative paths continue to work.
+     - `await import('./index.build.js')` (or similar) to execute the compiled entry module.
+   - Rename the original entry to `index.build.js` (keeps sourcemaps intact).
+   - Generate `dist/server/ui/options.js` wrapper that imports the compiled options and deep-merges production overrides:
+     - `development=false`, `viteOptions.root=<dist root>`
+     - `component_dir='ui/ssr'`, `build_dir='client'`
+     - `open_api_path` & `renderer` rewritten to dist copies
+     - Preserve custom user fields unless they conflict with production invariants.
+
+5. **Asset Copy**
+   - Copy OpenAPI YAML (`server/stitch.yaml`, `server/openapi/**`, UI stitch) into mirrored dist paths.
+   - Copy SQL files specified by `--sql-glob` so each repo’s `.sql` sits next to its compiled JS sibling.
+   - Copy arbitrary asset globs (`--assets`) – defaults include `ui/resources/**`, `database/**`, etc.
+   - Verify all controller/middleware identifiers discovered from OpenAPI resolve to files under `dist`.
+
+6. **Client Build (CSR)**
+   - Use the project’s Vite config via `vite.build({ configFile, root: uiRoot, build: { outDir: dist/client, manifest: true } })`.
+   - Force `build.rollupOptions.input` to the resolved client entry module so Vite emits hashed assets and a manifest without relying on HTML transforms.
+   - Collect the generated manifest (supports both `manifest.json` and `.vite/manifest.json`) to drive preload/script injection.
+   - Install the client-exclusion plugin that stubs modules matching `clientExclude` globs, preventing server-only sources from landing in the browser bundle.
+
+7. **SSR Compilation**
+   - Reuse Vite in SSR mode with:
+     - `build: { ssr: true, outDir: dist/ui/ssr, rollupOptions: { preserveModules: true, preserveModulesRoot: uiRoot, input: <set of layout/view components> } }`.
+   - Component list comes from OpenAPI-derived routes (layouts + views).
+   - Resulting files mirror the original `.svelte` tree but with `.js` extensions, allowing Forge’s `ProdComponentLoader` (`replace('.svelte', '.js')`) to work unchanged.
+   - Emit `dist/ssr/manifest.json` describing every route → layout/view module path (relative to dist root) for debugging and possible runtime use.
+
+8. **HTML Template Rewriting**
+   - Read `ui/index.html`, strip dev-only tags (`/@vite/client`, direct `ui/client.ts` script).
+   - Inject preload + `<script type="module">` tags based on the CSR manifest.
+   - Persist the transformed template to `dist/ui/index.html`, which Forge’s `BaseHTMLRender` will load.
+
+9. **Runtime Bootstrap & Manifests**
+   - Generate `dist/server/runtime-manifest.json` capturing:
+     - Absolute → relative path mapping for key assets (openapi, sql roots, middleware root, client manifest, ssr manifest, template).
+     - Build metadata (timestamps, CLI version, input options).
+   - Ensure the bootstrap wrapper keeps CWD pinned to the dist root so legacy `process.cwd()` resolution in Dinner/Forge/sqlstack continues to work.
+
+10. **Verification & Dev Mode Hooks**
+   - Optionally run a lightweight post-build check (`node --check dist/server/index.build.js`) and ensure expected artifacts exist.
+   - Provide `app build --inspect` (future) to print manifest contents.
+    - `app serve` launches `tsx` (or `ts-node`) against the original entry with Forge loader, optional watch, and split frontend process per config.
+
+## External Dependencies
+- **TypeScript**: use the project-local compiler via `root/node_modules/typescript`.
+- **Vite** / **@sveltejs/vite-plugin-svelte**: loaded from the target project for both CSR and SSR builds.
+- **@noego/stitch**: consumed through Forge’s parser to discover routes/layouts when creating the SSR entry set.
+- **yaml** / **deepmerge**: parse `app.yaml` and merge overrides.
+- **glob** (project-local) for file discovery.
+- No additional runtime deps for App itself; CLI implemented in ESM JS.
+
+## Open Questions / Follow-ups
+- Whether Forge should load a precomputed SSR manifest vs building on start. Current plan keeps runtime unchanged (Forge still builds at start) but provides manifest for inspection; can revisit once CLI is functional.
+- Potential production mode differences (NODE_ENV). App sets `mode=production` for Vite by default but allows overrides via `--mode`.
+- How to expose build summaries (JSON vs console). Initial version will log human-readable summary and emit `runtime-manifest.json`.
+- Improve developer ergonomics around TypeScript diagnostics (currently streamed verbatim when `tsc` reports errors but emit proceeds).

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@noego/app",
+  "version": "0.0.1",
+  "description": "Production build tool for Dinner/Forge apps.",
+  "type": "module",
+  "bin": {
+    "app": "./bin/app.js",
+    "noego":"./bin/app.js"
+  },
+  "scripts": {
+    "build": "node ./bin/app.js build"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "license": "MIT",
+  "author": "App Build CLI",
+  "dependencies": {
+    "deepmerge": "^4.3.1",
+    "picomatch": "^2.3.1",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {}
+}