@loj-lang/cli 0.5.0

package/agent-assets/loj-authoring/references/project-and-transport.md

@@ -0,0 +1,454 @@
+# Project File And Transport
+
+Use this reference for `loj.project.yaml`, full-stack orchestration, target-level database/runtime
+profiles, and the shared frontend↔backend HTTP/JSON baseline.
+
+## `loj.project.yaml` Purpose
+
+`loj.project.yaml` is orchestration only.
+
+It answers:
+
+- what targets belong to the app
+- where each target entry file lives
+- where generated output should go
+- which dev host/server topology should run together
+- which project-shell database/runtime profile should be prepared for generated targets
+
+It must not contain business semantics such as:
+
+- `model`
+- `resource`
+- `page`
+- controllers/entities/services
+- frontend layout details
+
+## Recommended Directory Structure
+
+For new projects, default to this shape unless the task explicitly needs something else:
+
+```text
+my-app/
+  loj.project.yaml
+
+  frontend/
+    app.web.loj
+    models/
+    resources/
+    read-models/
+    pages/
+    rules/
+    workflows/
+    styles/
+    components/
+    logic/
+    assets/
+
+  backend/
+    app.api.loj
+    models/
+    resources/
+    read-models/
+    rules/
+    workflows/
+    handlers/
+    policies/
+    queries/
+```
+
+Use this as a recommendation, not a parser requirement.
+
+Intent:
+
+- `frontend/` keeps `.web.loj`, `.style.loj`, frontend rules/workflows, host components, and assets together
+- `backend/` keeps `.api.loj`, backend rules/workflows, `@fn(...)` handlers/policies, and `@sql(...)` queries together
+- `loj.project.yaml` stays at the app root
+
+## Minimal Shape
+
+```yaml
+app:
+  name: user-admin
+
+targets:
+  frontend:
+    type: web
+    entry: frontend/app.web.loj
+  backend:
+    type: api
+    entry: backend/app.api.loj
+```
+
+Rules:
+
+- `app.name` is required
+- `targets` is required
+- each target has:
+  - logical alias key
+  - `type`
+  - `entry`
+- `entry` is relative to the project file
+
+## Target Types
+
+Preferred:
+
+- `web`
+- `api`
+
+Legacy aliases still accepted during the beta window:
+
+- `rdsl`
+- `sdsl`
+
+Use `web/api` for new project files.
+
+## Current Expanded Shape
+
+```yaml
+app:
+  name: flight-booking-proof
+
+targets:
+  frontend:
+    type: web
+    entry: frontend/app.web.loj
+    outDir: generated/frontend
+    runtime:
+      basePath: /console
+  backend:
+    type: api
+    entry: backend/app.api.loj
+    outDir: generated/backend
+    database:
+      vendor: postgres
+      mode: docker-compose
+      name: booking_app
+      username: loj
+      password: loj
+      autoProvision: true
+      migrations: native-sql
+    runtime:
+      basePath: /internal-api
+      shutdown:
+        mode: graceful
+        timeout: 30s
+      health:
+        path: /health
+      readiness:
+        path: /ready
+      drain:
+        path: /drain
+      cors:
+        origins: ["http://127.0.0.1:5173"]
+      forwardedHeaders:
+        mode: standard
+      trustedProxy:
+        mode: local
+      requestSizeLimit: 10mb
+
+dev:
+  host:
+    type: react-vite
+    target: frontend
+    dir: ./generated/frontend
+    apiBase: /api
+    proxyTarget: backend
+  server:
+    target: backend
+```
+
+Rules:
+
+- the project file stays declarative
+- do not put shell commands in it
+- do not turn it into a generic env bag
+- database/runtime slices live here, not in `.web.loj` / `.api.loj`
+
+Complete Spring-style example:
+
+```yaml
+app:
+  name: flight-booking-proof
+
+targets:
+  frontend:
+    type: web
+    entry: frontend/app.web.loj
+    outDir: generated/frontend
+    runtime:
+      basePath: /console
+  backend:
+    type: api
+    entry: backend/app.api.loj
+    outDir: generated/backend-postgres
+    database:
+      vendor: postgres
+      mode: docker-compose
+      name: flight_booking_proof
+      username: loj
+      password: loj
+      autoProvision: true
+      migrations: flyway
+    runtime:
+      basePath: /internal-api
+      shutdown:
+        mode: graceful
+        timeout: 30s
+      cors:
+        origins: [http://127.0.0.1:5173]
+        methods: [GET, POST, PUT, PATCH, DELETE, OPTIONS]
+        headers: [Authorization, Content-Type]
+        credentials: true
+      forwardedHeaders:
+        mode: standard
+      trustedProxy:
+        mode: local
+      health:
+        path: /healthz
+      readiness:
+        path: /readyz
+      drain:
+        path: /drainz
+      requestSizeLimit: 10mb
+
+dev:
+  host:
+    type: react-vite
+    target: frontend
+    dir: ../../subprojects/rdsl/examples/user-admin/host
+    apiBase: /api
+    proxyTarget: backend
+  server:
+    target: backend
+```
+
+## Current CLI Mapping
+
+Project-shell commands are the preferred default when `loj.project.yaml` exists:
+
+- `loj validate loj.project.yaml`
+- `loj build loj.project.yaml`
+- `loj dev loj.project.yaml`
+- `loj dev loj.project.yaml --debug`
+- `loj rebuild loj.project.yaml --target frontend`
+- `loj restart loj.project.yaml --service host`
+- `loj status loj.project.yaml`
+- `loj stop loj.project.yaml`
+- `loj doctor loj.project.yaml`
+
+Single-target project-shell flows keep database/runtime profiles active:
+
+- `loj validate loj.project.yaml --target backend`
+- `loj build loj.project.yaml --target backend`
+- `loj dev loj.project.yaml --target backend`
+- `loj status loj.project.yaml --target backend`
+- `loj doctor loj.project.yaml --target backend`
+
+Target-local CLIs remain available as secondary tools:
+
+- `rdsl validate/build`
+- `sdsl validate/build/dev`
+
+Use `loj.project.yaml` whenever you need project-shell database/runtime/dev orchestration, even if
+you are only generating one target.
+
+Command stance:
+
+- default: `loj ...`
+- secondary/high-signal local tooling: `rdsl ...` / `sdsl ...`
+- do not recommend `rdsl build` / `sdsl build` as the default path for new user-facing full-stack
+  examples
+
+## Required, Optional, Defaults
+
+Core field status:
+
+| Path | Status | Current default / note |
+| --- | --- | --- |
+| `app.name` | required | non-empty string |
+| `targets` | required | must contain at least one target |
+| `targets.<alias>.type` | required | `web | api` preferred; `rdsl | sdsl` still accepted as legacy aliases |
+| `targets.<alias>.entry` | required | non-empty relative path |
+| `targets.<alias>.outDir` | optional | build falls back to target-local defaults when omitted |
+| `targets.<alias>.database` | optional | `api` targets only |
+| `targets.<alias>.runtime` | optional | `api` targets may use the narrow runtime slice; `web` currently only uses `runtime.basePath` |
+| `dev` | optional | no managed dev processes when omitted |
+| `dev.server` | optional | starts no backend process when omitted |
+| `dev.server.target` | required when `dev.server` exists | must reference an `api` target |
+| `dev.server.host` | optional | `127.0.0.1` |
+| `dev.server.port` | optional | `3001` |
+| `dev.host` | optional | starts no frontend host when omitted |
+| `dev.host.type` | optional | `react-vite` |
+| `dev.host.target` | required when `dev.host` exists | must reference a `web` target |
+| `dev.host.dir` | required when `dev.host` exists | non-empty relative path |
+| `dev.host.host` | optional | `127.0.0.1` |
+| `dev.host.port` | optional | `5173` |
+| `dev.host.previewPort` | optional | `4173` |
+| `dev.host.apiBase` | optional | `/api` |
+| `dev.host.proxyTarget` | optional | defaults to `dev.server.target` when a local backend is also configured |
+| `dev.host.proxyAuth` | optional | no default |
+
+Database defaults:
+
+| Path | Status | Current default / note |
+| --- | --- | --- |
+| `database.vendor` | required when `database` exists | `h2 | sqlite | postgres | mysql | mariadb | sqlserver | oracle` |
+| `database.mode` | optional | `embedded` for `h2/sqlite`, otherwise `external` |
+| `database.name` | optional | derived from `app.name`; `sqlite` becomes `<app>.db`, `oracle` becomes `FREEPDB1` |
+| `database.host` | optional | external vendors default to `127.0.0.1` |
+| `database.port` | optional | vendor default where applicable |
+| `database.username` | optional | vendor default |
+| `database.password` | optional | vendor default |
+| `database.autoProvision` | optional | `false` |
+| `database.migrations` | optional | `none` |
+
+Runtime defaults:
+
+| Path | Status | Current default / note |
+| --- | --- | --- |
+| `runtime.basePath` | optional | no default; supported on `api` and `web` targets |
+| `runtime.shutdown` | optional | `api` targets only |
+| `runtime.shutdown.mode` | optional inside `shutdown` | `graceful` |
+| `runtime.shutdown.timeout` | optional inside `shutdown` | `30s` |
+| `runtime.health.path` | optional | no default helper emitted unless declared |
+| `runtime.readiness.path` | optional | no default helper emitted unless declared |
+| `runtime.drain.path` | optional | no default helper emitted unless declared |
+| `runtime.cors` | optional | `api` targets only |
+| `runtime.cors.origins` | required when `cors` exists | non-empty string array |
+| `runtime.cors.methods` | optional | target defaults when omitted |
+| `runtime.cors.headers` | optional | target defaults when omitted |
+| `runtime.cors.credentials` | optional | `false` |
+| `runtime.forwardedHeaders` | optional | `api` targets only |
+| `runtime.forwardedHeaders.mode` | optional inside `forwardedHeaders` | `standard` |
+| `runtime.trustedProxy` | optional | `api` targets only |
+| `runtime.trustedProxy.mode` | optional inside `trustedProxy` | `local` |
+| `runtime.trustedProxy.cidrs` | optional | required only when `mode: cidrs` |
+| `runtime.requestSizeLimit` | optional | no default |
+
+Current auto-fill behavior:
+
+- if `runtime.trustedProxy` is declared without `runtime.forwardedHeaders`, the project shell
+  currently auto-enables `forwardedHeaders.mode: standard`
+
+## Env Story
+
+Current conventional env files:
+
+- `.env`
+- `.env.local`
+- `.env.<target-alias>`
+- `.env.<target-alias>.local`
+
+`loj validate`, `loj build`, and `loj dev` load these conventionally.
+
+`loj dev` also watches them and reloads managed target sessions when they change.
+
+## Database Slice
+
+`targets.<alias>.database` is currently supported on `api` targets.
+
+Supported fields:
+
+- `vendor`: `h2 | sqlite | postgres | mysql | mariadb | sqlserver | oracle`
+- `mode`: `embedded | external | docker-compose`
+- `name`
+- `host`
+- `port`
+- `username`
+- `password`
+- `autoProvision`
+- `migrations`: `none | native-sql | flyway`
+
+Current intent:
+
+- database choice stays in project/runtime orchestration
+- generated targets may emit runtime-specific config plus native `db/schema.sql`
+- `loj dev` may auto-start/stop generated `docker-compose.database.yaml` when
+  `mode: docker-compose` and `autoProvision: true`
+
+## Runtime Slice
+
+`targets.<alias>.runtime` currently supports:
+
+- on `api` targets:
+  - `basePath`
+  - `shutdown.mode`
+  - `shutdown.timeout`
+  - `health.path`
+  - `readiness.path`
+  - `drain.path`
+  - `cors.origins`
+  - `cors.methods`
+  - `cors.headers`
+  - `cors.credentials`
+  - `forwardedHeaders.mode`
+  - `trustedProxy.mode`
+  - `trustedProxy.cidrs`
+  - `requestSizeLimit`
+- on `web` targets:
+  - `basePath`
+
+Keep this narrow. It expresses generated runtime/deploy intent, not business semantics.
+
+## Dev Story
+
+Current `loj dev` scope:
+
+- starts target-local rebuild loops
+- can run a React/Vite host for the configured web target
+- can run the configured backend server
+- can auto-provision supported Docker Compose databases
+- persists dev-session state for `status`, `stop`, and editor reuse
+- accepts `loj rebuild` to queue a manual rebuild for all or selected active targets
+- accepts `loj restart` to restart managed `host` and/or `server` processes without restarting the whole loop
+- may expose attachable debugger endpoints through `loj dev --debug`
+
+Keep this conventional. Do not invent arbitrary process orchestration syntax.
+
+## Neutral Transport Contract
+
+Frontend and backend targets align to a shared HTTP/JSON contract, not directly to each other's
+frameworks.
+
+### Lists
+
+Accepted list responses:
+
+- raw JSON array
+- `{ items: [...] }`
+- `{ data: [...] }`
+
+### Single records
+
+Accepted single-record responses:
+
+- raw JSON object
+- `{ item: {...} }`
+- `{ data: {...} }`
+
+### Errors
+
+Errors should be non-2xx JSON objects with string `message`.
+
+Current message rule:
+
+- backend targets should return a stable human-readable `message`
+- do not invent target-private message templating in source DSL
+
+### IDs
+
+- every resource record includes `id`
+- frontend may coerce it to string
+
+### Pagination
+
+- server pagination metadata is still optional
+- generated list pagination remains client-side unless the shared transport contract widens later
+
+## Full-Stack Authoring Guardrails
+
+- Keep frontend-family and backend-family semantics in their own files.
+- Use `loj.project.yaml` only to compose them.
+- If frontend and backend need a richer shared transport shape, evolve the transport contract first.
+- Do not hide target mismatches inside project orchestration.

package/agent-assets/loj-authoring/references/workflow-flow-proof.md

@@ -0,0 +1,263 @@
+# Workflow / Flow (`.flow.loj`)
+
+Use this reference for the current first-slice workflow/state-machine surface.
+
+It still has standalone CLI entry points, but it is no longer standalone-only:
+
+- `.api.loj` may link it through `resource workflow: '@flow("./workflows/x")'`
+- `.web.loj` may link it through either:
+  - `resource workflow: '@flow("./workflows/x")'`
+  - `resource workflow: { source: '@flow("./workflows/x")', style: workflowShell }`
+- `loj.project.yaml` still does not orchestrate `.flow.loj` directly
+
+## Current Scope
+
+Implemented today:
+
+- `.flow.loj` file suffix
+- one named workflow per file
+- parser + validator + shared workflow-manifest generation
+- repo CLI entry:
+  - `loj flow validate <file.flow.loj>`
+  - `loj flow build <file.flow.loj> --out-dir <dir>`
+- narrow `.api.loj` linkage through `resource workflow: '@flow("./workflows/x")'`
+- narrow `.web.loj` linkage through scalar or mapping `resource workflow`
+- generated backend transition-enforcement surface for Spring Boot + FastAPI
+- generated frontend create/edit/read workflow summaries, step-aware create/edit submit CTA labels, and next-step-prioritized read-surface transition actions
+- fixed generated frontend workflow route/page at `/:id/workflow` for workflow-linked resources
+
+Not implemented yet:
+
+- project-shell orchestration for flow targets
+- broader custom page-level wizard routing or long-transaction semantics beyond the fixed generated workflow page
+- non-resource workflow consumers
+
+## File Shape
+
+Use one top-level block:
+
+```yaml
+workflow booking-process:
+  model: Booking
+  field: status
+
+  states:
+    DRAFT:
+      label: "Draft"
+      color: gray
+    READY:
+      label: "Ready"
+      color: blue
+    CONFIRMED:
+      label: "Confirmed"
+      color: green
+
+  wizard:
+    steps:
+      - name: select-flight
+        completesWith: DRAFT
+        surface: form
+      - name: enter-passengers
+        completesWith: READY
+        surface: read
+        allow: currentUser.role in [ADMIN, AGENT]
+
+  transitions:
+    confirm:
+      from: READY
+      to: CONFIRMED
+      allow: currentUser.role == ADMIN
+```
+
+Rules:
+
+- exactly one top-level `workflow <name>:` block per file
+- `model` is required
+- `field` is required
+- `states` is required
+- `transitions` is required
+- `wizard` is optional
+
+Richer booking-style example:
+
+```yaml
+workflow booking-process:
+  model: Booking
+  field: status
+
+  states:
+    DRAFT:
+      label: "Draft"
+      color: gray
+    READY:
+      label: "Ready"
+      color: blue
+    CONFIRMED:
+      label: "Confirmed"
+      color: green
+    FAILED:
+      label: "Failed"
+      color: red
+
+  wizard:
+    steps:
+      - name: select-itinerary
+        completesWith: DRAFT
+        surface: form
+      - name: review-booking
+        completesWith: READY
+        surface: read
+      - name: complete-ticketing
+        completesWith: CONFIRMED
+        surface: workflow
+
+  transitions:
+    confirm:
+      from: READY
+      to: CONFIRMED
+      allow: currentUser.role in [ADMIN, AGENT]
+    fail_ticketing:
+      from: READY
+      to: FAILED
+      allow: currentUser.role in [ADMIN, AGENT]
+    reopen:
+      from: FAILED
+      to: READY
+      allow: currentUser.role == ADMIN
+```
+
+Use this kind of thicker example when the task is booking/approval/recovery oriented. It is still
+within the current first-slice workflow surface.
+
+## Supported Keys
+
+Top-level workflow keys:
+
+- `model`
+- `field`
+- `states`
+- `wizard`
+- `transitions`
+
+Inside each `states:` entry:
+
+- optional `label`
+- optional `color`
+
+Inside each `wizard.steps:` item:
+
+- required `name`
+- required `completesWith`
+- optional `surface`
+- optional `allow`
+
+Current `surface` values:
+
+- `form`
+- `read`
+- `workflow`
+
+Current defaulting:
+
+- first wizard step defaults to `form`
+- later wizard steps default to `workflow`
+
+Inside each `transitions:` entry:
+
+- required `from`
+- required `to`
+- optional `allow`
+
+## Expression Language
+
+The current flow proof reuses the same constrained expression language used by `.web.loj`,
+`.api.loj`, and `.rules.loj`.
+
+Use:
+
+- comparisons like `==`, `!=`, `>`, `<`, `>=`, `<=`
+- logical `&&`, `||`, `not`
+- arithmetic like `+`, `-`, `*`, `/`
+- dotted paths like `currentUser.role`, `record.status`
+- membership like `currentUser.role in [ADMIN, AGENT]`
+
+Do not use:
+
+- raw JavaScript, Java, or Python
+- statements, loops, imports, closures
+- router/state-machine/transaction-framework internals
+
+## Current Command Path
+
+Validate:
+
+```bash
+loj flow validate ./workflows/booking-process.flow.loj
+```
+
+Build manifest:
+
+```bash
+loj flow build ./workflows/booking-process.flow.loj --out-dir ./generated/flow
+```
+
+Current build output is a standalone workflow manifest JSON file. Treat it as the first proof
+surface, even though that same manifest is now also consumed by narrow `.api.loj` / `.web.loj`
+resource linkage.
+
+## Current Linked Resource Surfaces
+
+Backend:
+
+```yaml
+resource bookings:
+  model: Booking
+  api: /api/bookings
+  workflow: '@flow("./workflows/booking-process")'
+```
+
+- Spring Boot + FastAPI generate workflow-aware create/update wrappers
+- create seeds the initial workflow state from the first wizard step's `completesWith` when present, otherwise the first declared workflow state
+- update preserves the current workflow state rather than accepting direct state mutation through the normal update payload
+- workflow-linked resources also gain `POST /.../{id}/transitions/{transition}` for transition enforcement
+
+Frontend:
+
+```yaml
+resource bookings:
+  model: Booking
+  api: /api/bookings
+  workflow:
+    source: '@flow("./workflows/booking-process")'
+    style: workflowShell
+  read:
+    fields: [reference, status]
+```
+
+- generated create/edit/read surfaces reuse the linked workflow manifest
+- on `.web.loj`, `workflow:` may be a scalar `@flow("./workflows/x")` or a mapping with
+  `source:` plus optional shell-level `style:`
+- `wizard.steps[].surface` now controls narrow generated handoff across existing surfaces: `form` reuses generated edit after record creation, `read` reuses the generated read surface, and `workflow` reuses the fixed generated workflow page
+- create shows workflow state plus visible wizard steps, derives narrow current/next-step summaries, upgrades the primary submit CTA to `Create and continue to <next step>` when a visible next step exists, and defaults successful submit into the next step's declared surface when no explicit redirect or app-local `returnTo` exists
+- edit shows workflow state plus visible wizard steps, derives the same narrow current/next-step summaries, upgrades the primary submit CTA to `Save and continue to <next step>` when a visible next step exists, surfaces a narrow `Workflow` link into the fixed workflow page, and defaults successful submit into that same next-step surface resolution when no explicit redirect or app-local `returnTo` exists
+- read also shows next-step-prioritized allowed transitions, narrow current/next-step summaries, a generated `workflowStep` handoff when later-step review is requested, and a narrow `Redo <previous step>` link when a previous visible step exists; it posts to the generated backend transition route, and successful transitions now also hand off into the next visible wizard step's declared surface when that surface changes
+- generated routing also adds a fixed `/:id/workflow` page that reuses the same manifest for current-state summary, narrow current/next-step summaries, wizard-step progress, next-step-prioritized transition actions, narrow `workflowStep` review handoff, `Redo <previous step>` navigation, post-transition next-step handoff, a narrow related-surface summary derived from existing `read.related` anchors when a read view exists, generated `read.fields` record-context details plus generated `read.related` panel context when a read view exists, preserves workflow links and workflow state labels across label-list related fallbacks when the target resource has no generated read/edit surface, and narrow `View` / `Edit` / `Back` links with sanitized app-local `returnTo`
+- record-scoped relation pages that already exist for the same parent resource also pass a narrow `parentWorkflow` summary into adjacent generated custom blocks when that parent resource is workflow-linked
+- the workflow-controlled enum state field may not be listed as a plain generated `create.fields` or `edit.fields` entry
+
+Current expression boundary for linked workflow usage:
+
+- wizard step `allow` stays inside the shared expression language
+- web wizard-step visibility currently supports `currentUser`, `record`, `formData`, and bare enum-like literals
+- backend transition enforcement currently supports `currentUser`, `record`, and bare enum-like literals
+
+## Hard Guardrails
+
+- Do not invent any `.flow.loj` linkage beyond:
+  - `resource workflow: '@flow("./workflows/x")'` in `.api.loj`
+  - `resource workflow: '@flow("./workflows/x")'` in `.web.loj`
+  - `resource workflow: { source: '@flow("./workflows/x")', style: workflowShell }` in `.web.loj`
+- Do not add policy/rules syntax to `.flow.loj`.
+- Do not add target-specific router or transaction vocabulary to `.flow.loj`.
+- Do not invent `loj.project.yaml` workflow target types yet.
+- Keep workflow authoring declarative and target-neutral.