@loj-lang/cli 0.5.0

package/README.md

@@ -0,0 +1,87 @@
+# @loj-lang/cli
+
+Repo-level orchestration CLI for `loj.project.yaml`.
+
+Current implemented commands:
+
+- `loj validate`
+- `loj build`
+- `loj dev`
+- `loj status`
+- `loj stop`
+- `loj doctor`
+- `loj rules validate`
+- `loj rules build`
+- `loj flow validate`
+- `loj flow build`
+- `loj agent install <codex|windsurf|generic>`
+- `loj agent add <codex|windsurf|generic> --from <source>`
+- `loj agent export <codex|windsurf|generic> --out-dir <dir>`
+
+This package coordinates sibling frontend and backend targets rather than replacing target-local CLIs.
+Its agent commands only distribute the bundled `loj-authoring` skill; they do not replace the
+canonical syntax docs or the manifest/inspect/trace contract.
+
+Recommended project-shell loop:
+
+```bash
+# inspect dependencies, generated outputs, linked files, and current dev state
+npx @loj-lang/cli doctor ./loj.project.yaml
+
+# start the managed host/backend loop
+npx @loj-lang/cli dev ./loj.project.yaml
+
+# inspect current URLs, services, probes, and debugger endpoints
+npx @loj-lang/cli status ./loj.project.yaml
+
+# stop the active managed session
+npx @loj-lang/cli stop ./loj.project.yaml
+```
+
+Examples:
+
+```bash
+# validate a standalone policy/rules proof file
+npx @loj-lang/cli rules validate ./policies/invoice-access.rules.loj
+
+# emit a target-neutral semantic manifest
+npx @loj-lang/cli rules build ./policies/invoice-access.rules.loj --out-dir ./generated/rules
+
+# validate a standalone workflow/state-machine proof file
+npx @loj-lang/cli flow validate ./workflows/booking-process.flow.loj
+
+# emit a shared workflow manifest
+npx @loj-lang/cli flow build ./workflows/booking-process.flow.loj --out-dir ./generated/flow
+
+# install into CODEX_HOME/skills or ~/.codex/skills
+npx @loj-lang/cli agent install codex
+
+# install into WINDSURF_HOME/skills or ~/.codeium/windsurf/skills
+npx @loj-lang/cli agent install windsurf
+
+# vendor a pinned project copy under ./.loj/agents/codex/skills
+npx @loj-lang/cli agent install codex --scope project
+
+# add a skill bundle from a local or remote source
+npx @loj-lang/cli agent add codex --from ./tooling/skills/loj-authoring
+
+# install into any explicit skills directory
+npx @loj-lang/cli agent install generic --skills-dir ~/.my-agent/skills
+
+# export into any custom directory
+npx @loj-lang/cli agent export codex --out-dir ./tooling/skills
+```
+
+The current `.rules.loj` slice is intentionally narrow: one named rule set per file, grouped
+`allow/deny`, `eligibility`, `validate`, and `derive` entries, standalone manifest emission
+through `loj rules build`, plus narrow backend-family linkage through `resource auth.policy`,
+`resource create.rules`, and `readModel rules`. It is still not orchestrated through
+`loj.project.yaml`. The current `.flow.loj` slice is even narrower: standalone validate/build
+only, with one `workflow <name>:` block compiling to a shared workflow manifest.
+
+Local workspace commands:
+
+```bash
+npm run build --workspace=@loj-lang/cli
+npm run test --workspace=@loj-lang/cli
+```

package/agent-assets/loj-authoring/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: loj-authoring
+description: >
+  Use this skill when creating, editing, reviewing, or debugging `.web.loj` / legacy `.rdsl`
+  files, `.api.loj` / legacy `.sdsl` files, `.style.loj` files, linked `.rules.loj` / `.flow.loj`
+  slices, or `loj.project.yaml` orchestration files for the Loj DSL framework. Covers current
+  web/api/style family syntax, linked rules/workflow/SQL escape hatches, project-shell
+  database/runtime/dev commands, and how those inputs map to generated React, Spring Boot, and
+  FastAPI output.
+---
+
+# Loj Authoring
+
+Use this skill for:
+
+- frontend-family `.web.loj` / legacy `.rdsl`
+- style `.style.loj`
+- backend-family `.api.loj` / legacy `.sdsl`
+- linked `.rules.loj`
+- linked `.flow.loj`
+- `loj.project.yaml`
+
+(For codex) If this skill is missing outside the repo, current install/export commands are:
+
+- `npx @loj-lang/cli agent install codex`
+- `npx @loj-lang/cli agent install codex --scope project`
+- `npx @loj-lang/cli agent export codex --out-dir ./tooling/skills`
+
+All portable technique references required by this skill live in `references/`.
+You may not have knowledge of the Loj DSL framework at this time, so you must read the references to understand the syntax and semantics of the DSL.
+This skill should remain usable even when vendored outside the repo.
+
+| Task involves | Read |
+|---|---|
+| frontend-family syntax, models/resources/pages/read-model pages, style/SEO/assets, workflow-linked surfaces | `references/frontend-family.md` |
+| generated React runtime assumptions, runtime imports, inspect/trace behavior | `references/frontend-runtime-trace.md` |
+| backend-family syntax, models/resources/read-models, linked rules/workflow/SQL, transaction defaults | `references/backend-family.md` |
+| Spring Boot / FastAPI target-specific output and escape-hatch constraints | `references/backend-targets.md` |
+| standalone policy/rules proof syntax and current linkage boundaries | `references/policy-rules-proof.md` |
+| standalone workflow/state-machine syntax and current linked resource behavior | `references/workflow-flow-proof.md` |
+| `loj.project.yaml`, project-shell database/runtime slices, dev/status/doctor flows, frontend↔backend transport alignment | `references/project-and-transport.md` |
+
+## Workflow
+
+1. Identify whether the task is frontend-family, backend-family, linked rules/workflow, or project-shell orchestration.
+2. For new source, prefer canonical suffixes and target names:
+   - `.web.loj`, `.api.loj`
+   - `type: web`, `type: api`
+3. Read only the minimal bundled reference slice from the router above.
+4. Generate only implemented syntax from those references.
+5. If the requested shape is outside the current slice, say so and use the narrowest implemented escape hatch or project/runtime profile.
+
+## Command Shortcuts
+
+Default recommendation: use project-shell commands first whenever a `loj.project.yaml` exists.
+
+- preferred default:
+  - `loj validate loj.project.yaml`
+  - `loj build loj.project.yaml`
+  - `loj dev loj.project.yaml`
+  - `loj rebuild loj.project.yaml --target <alias>`
+  - `loj restart loj.project.yaml --service <host|server|all>`
+  - `loj status loj.project.yaml`
+  - `loj stop loj.project.yaml`
+  - `loj doctor loj.project.yaml`
+- single-target project-shell:
+  - `loj validate loj.project.yaml --target <alias>`
+  - `loj build loj.project.yaml --target <alias>`
+  - `loj dev loj.project.yaml --target <alias>`
+  - `loj status loj.project.yaml --target <alias>`
+  - `loj doctor loj.project.yaml --target <alias>`
+- standalone rules proof:
+  - `loj rules validate <entry.rules.loj>`
+  - `loj rules build <entry.rules.loj> --out-dir <dir>`
+- standalone workflow proof:
+  - `loj flow validate <entry.flow.loj>`
+  - `loj flow build <entry.flow.loj> --out-dir <dir>`
+- family-local fallback:
+  - `rdsl validate <entry.web.loj>`
+  - `rdsl build <entry.web.loj> --out-dir <dir>`
+  - `sdsl validate <entry.api.loj>`
+  - `sdsl build <entry.api.loj> --out-dir <dir>`
+
+Use `rdsl` / `sdsl` mainly for pure single-family work or compiler/debug tasks. Do not treat them as
+the default entrypoint for new multi-file app work when `loj.project.yaml` exists.
+
+Useful debugging commands:
+
+- `rdsl inspect <entry.web.loj|build-dir> [--node <id>]`
+- `rdsl trace <entry.web.loj|build-dir> <generated-file:line[:col]>`
+
+## Hard Rules
+
+### Common
+
+- Files are a strict YAML subset: no anchors, aliases, merge keys, or custom tags.
+- For new files, use canonical suffixes; keep `.rdsl` / `.sdsl` only for legacy edits.
+- Prefer single-file apps for small demos. Use `imports:` only when the app really benefits from splitting by domain.
+- `imports:` entries are relative family-source paths (`.web.loj` / `.rdsl`, `.api.loj` / `.sdsl`) or directories ending with `/`.
+- Nested imports are allowed. Cycles are invalid. Directory imports expand direct children only.
+- One root file owns `app:` and `compiler:`. Module files may not contain them.
+- Model/resource names must stay unique across the merged namespace.
+- Keep primitives target-neutral and business-oriented.
+- Do not leak framework/runtime specifics into the DSL source.
+
+### Frontend-family
+
+- Expression language stays constrained. No loops, statements, closures, or inline JS outside implemented escape hatches.
+- Escape preference: built-in DSL > `@expr` > `@fn` > `@custom`.
+- Treat suffix-bearing escape paths such as `.ts` / `.tsx` as deliberate frontend lock-in, not the default style.
+- `toast` accepts static string or descriptor only.
+- Current UI-copy descriptor support is still narrow:
+  - use plain strings for fixed copy
+  - use `{ key?, defaultMessage?, values? }` when future i18n or scalar-literal interpolation matters
+  - copy descriptors are currently implemented only on the documented title/label/date-navigation/SEO slices
+- `app.style` links `.style.loj`; shell-level `style:` references are currently narrow and do not imply table internals or responsive/mobile variants.
+- `app.seo`, `page.seo`, and `@asset(...)` are web metadata/asset surfaces, not style DSL features.
+- Escape file paths resolve relative to the declaring `.web.loj` file, not the root file.
+
+### Backend-family
+
+- `compiler:` must use an implemented `target + language + profile` triple.
+- `auth:` describes policy intent, not framework internals.
+- `operations:` controls generated CRUD endpoints; all default `true` if omitted.
+- No frontend concepts like pages, navigation, columns, or toast in `.api.loj`.
+- Do not encode Java/Python/SQLAlchemy/JPA into DSL primitives; keep them in target/profile or escape-hatch code.
+- `resource auth.policy` may use either `@fn("./policies/x")` or `@rules("./policies/x")`.
+- `resource create.rules` may use `@rules("./rules/x")` for narrow create eligibility/validation.
+- `readModel rules` may use `@rules("./rules/x")` for narrow eligibility/validation/derivation.
+- `resource workflow` may use `@flow("./workflows/x")`.
+- `readModel handler` may use `@fn("./handlers/x")` or narrow file-backed `@sql("./queries/x")`.
+- `@sql(...)` is read-model-only, read-only, and file-backed; keep procedures and write-oriented SQL in `@fn(...)`.
+- Generated write paths are transactional by default in the implemented targets; do not invent `transactional: true`.
+
+### `.rules.loj`
+
+- Use exactly one top-level `rules <name>:` block per file.
+- Stay within the current slice:
+  - `allow/deny <operation>`
+  - `eligibility <name>`
+  - `validate <name>`
+  - `derive <field>`
+  - shared `when`, optional `or`, optional `message`, and list-only `scopeWhen/scope` on auth entries
+- `.rules.loj` is linked only through the documented frontend/backend slices; do not invent new integration points.
+- Do not put `.rules.loj` under `loj.project.yaml`.
+
+### `.flow.loj`
+
+- Use exactly one top-level `workflow <name>:` block per file.
+- Stay within the current slice:
+  - `model`
+  - `field`
+  - `states`
+  - optional `wizard.steps`
+  - `transitions`
+- `.flow.loj` is linked only through `resource workflow: ...` in `.web.loj` / `.api.loj`.
+- Do not invent project-shell workflow targets, page-level router DSL, or framework-specific state-machine syntax.
+
+### `loj.project.yaml`
+
+- `loj.project.yaml` is orchestration only. Never place `model`, `resource`, `page`, or backend implementation details in it.
+- Prefer `type: web` / `type: api`. Treat `type: rdsl` / `type: sdsl` as deprecated legacy aliases.
+- `entry` should point at canonical suffixes for new examples: `app.web.loj`, `app.api.loj`.
+- Database/runtime/dev orchestration belongs here, not in `.web.loj` / `.api.loj`.
+- Keep `dev:` and `targets.<alias>.runtime` narrow and declarative. Do not turn them into arbitrary scripting or general ops config.
+- For new projects, default to the recommended bundled directory structure from `references/project-and-transport.md` instead of inventing an ad hoc tree.
+
+## Review Before Final Output
+
+- Valid strict-YAML-subset?
+- Canonical suffix/type chosen for new files unless editing legacy input?
+- Read from bundled `references/` rather than guessing from stale memory?
+- Top-level keys allowed for this file type (root vs module)?
+- Model/resource names unique project-wide?
+- Rules/effects within the implemented slice?
+- Escape hatches narrow and intentional?
+- No framework/runtime detail leaking into family DSL source?
+- For `.api.loj`: implemented `target/language/profile` triple and current linkage boundaries respected?
+- For `loj.project.yaml`: orchestration-only, with `web/api` preferred and database/runtime/dev slices kept narrow?

package/agent-assets/loj-authoring/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Loj Authoring"
+  short_description: "Author `.web.loj`, `.api.loj`, and `loj.project.yaml` using canonical Loj patterns"

package/agent-assets/loj-authoring/metadata.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.5.0",
+  "organization": "Loj",
+  "date": "March 2026",
+  "abstract": "Unified AI authoring skill for the Loj DSL framework. Covers frontend-family .web.loj (legacy .rdsl), backend-family .api.loj (legacy .sdsl), style .style.loj, linked .rules.loj and .flow.loj sub-DSL slices, and loj.project.yaml orchestration authoring, review, and debugging. Uses bundled references for current syntax, runtime, transport, project-shell, style, and generated-output guidance."
+}

package/agent-assets/loj-authoring/references/backend-family.md

@@ -0,0 +1,340 @@
+# Backend-Family Authoring (`.api.loj`, legacy `.sdsl`)
+
+Use this reference when authoring or reviewing backend-family source files.
+
+## Defaults
+
+- Prefer `.api.loj` for new files. Use `.sdsl` only for legacy edits.
+- Files are a strict YAML subset:
+  - no anchors
+  - no aliases
+  - no merge keys
+  - no custom tags
+
+Implemented compiler triples today:
+
+- `spring-boot / java / mvc-jpa-security`
+- `fastapi / python / rest-sqlalchemy-auth`
+
+If `compiler:` is omitted, default is the Spring triple above.
+
+## File Shape
+
+Root files may contain:
+
+- `app:`
+- optional `compiler:`
+- optional `imports:`
+- `model <Name>:`
+- `resource <name>:`
+- `readModel <name>:`
+
+Module files may contain:
+
+- optional `imports:`
+- `model <Name>:`
+- `resource <name>:`
+- `readModel <name>:`
+
+Module files may not contain `app:` or `compiler:`.
+
+## Imports
+
+- Use single-file for small demos.
+- Split by domain only when the service grows.
+- `imports:` entries must be relative `.api.loj` / `.sdsl` paths or directories ending in `/`.
+- Nested imports are allowed.
+- Import cycles are invalid.
+- Directory imports expand direct child family files only, sorted lexicographically.
+
+## `app:`
+
+```yaml
+app:
+  name: "Booking Service"
+  package: "com.example.booking"
+```
+
+Rules:
+
+- `name` is required
+- `package` is required
+- `package` must be a valid dotted Java-style package root
+- do not place auth provider, database vendor, shutdown, proxy, or deploy details here
+
+## `compiler:`
+
+```yaml
+compiler:
+  target: spring-boot
+  language: java
+  profile: mvc-jpa-security
+```
+
+Rules:
+
+- `target`, `language`, and `profile` must form an implemented triple
+- do not encode language into `target`
+- `compiler:` is for generation target selection, not business semantics
+
+## `model <Name>:`
+
+Example:
+
+```yaml
+model Booking:
+  reference: string @required @unique
+  baseFare: decimal @required
+  travelDate: date @required
+  status: enum(DRAFT, READY, CONFIRMED, FAILED)
+  memberId: belongsTo(Member)
+  passengers: hasMany(Passenger, by: bookingId)
+  createdAt: datetime @createdAt
+  updatedAt: datetime @updatedAt
+```
+
+Types:
+
+- `string`
+- `text`
+- `integer`
+- `long`
+- `decimal`
+- `boolean`
+- `datetime`
+- `date`
+- `enum(A, B, C)`
+- `belongsTo(Model)`
+- `hasMany(Model, by: field)`
+
+Decorators:
+
+- `@required`
+- `@email`
+- `@unique`
+- `@minLen(n)`
+- `@maxLen(n)`
+- `@createdAt`
+- `@updatedAt`
+
+Implicit persistence identity:
+
+```yaml
+id: long
+```
+
+Do not declare `id` manually in `v0.1`.
+
+Relation rules:
+
+- `belongsTo(Model)` is supported for narrow foreign-key-style relations
+- `hasMany(Model, by: field)` is inverse metadata only
+- `hasMany(..., by: ...)` must point to a target-model field declared as
+  `belongsTo(CurrentModel)`
+- current backend-family relation support is metadata plus generated foreign-key handling; it is not
+  a query DSL
+
+## `readModel <name>:`
+
+Example:
+
+```yaml
+readModel flightAvailability:
+  api: /api/flight-availability
+  auth:
+    mode: public
+  inputs:
+    departureAirport: string @required
+    departureDate: date @required
+  result:
+    flightNo: string
+    quotedFare: decimal
+  handler: '@sql("./queries/flightAvailability")'
+  rules: '@rules("./rules/flight-availability")'
+```
+
+Rules:
+
+- current read-models are narrow named GET list surfaces, not a generic query DSL
+- `api` is required and must start with `/`
+- `inputs:` and `result:` reuse model-style field authoring, but currently support scalar and enum
+  field shapes only
+- current `inputs:` support only `@required`
+- current `inputs:` do not support `datetime`
+- current `result:` fields do not support decorators
+- `auth:` currently supports only `mode` / `roles`
+- `handler:` is required and must use `@fn("./path")` or `@sql("./path")`
+- extensionless logical ids are preferred; target resolution uses `.java` for Spring and `.py` for
+  FastAPI
+- `@sql(...)` is read-model-only and intentionally narrow:
+  - file-backed query only
+  - read-only `SELECT` / `WITH`
+  - no procedures, `CALL`, `EXEC`, or write SQL
+  - alias columns to declared `result:` field names
+- `rules:` is optional and must use `@rules("./rules/x")`
+- current read-model rules support only:
+  - `eligibility`
+  - `validate`
+  - `derive`
+- `allow/deny` entries are rejected on backend read-model linkage
+- read-model rule expressions currently allow:
+  - `currentUser.*`
+  - `input.<field>`
+  - `item.<resultField>` inside derivations
+  - bare uppercase literals like `ADMIN`
+
+## `resource <name>:`
+
+Example:
+
+```yaml
+resource bookings:
+  model: Booking
+  api: /api/bookings
+  auth:
+    mode: authenticated
+    roles: [AGENT, ADMIN]
+  create:
+    rules: '@rules("./rules/booking-create")'
+    includes:
+      - field: passengers
+        fields: [name, seat]
+  update:
+    includes:
+      - field: passengers
+        fields: [id, name, seat]
+  workflow: '@flow("./workflows/booking-lifecycle")'
+  operations:
+    list: true
+    get: true
+    create: true
+    update: true
+    delete: true
+```
+
+Current resource rules:
+
+- `model` and `api` are required
+- `auth.policy` may use `@fn("./policies/x")` or `@rules("./policies/x")`
+- `create.rules` may use `@rules("./rules/x")`
+- `create.rules` currently supports only:
+  - `eligibility`
+  - `validate`
+- `create.rules` rejects:
+  - `allow/deny`
+  - `derive`
+- `create.includes` / `update.includes` are the current one-level aggregate-root nested-write slice
+- they accept only direct `hasMany(Target, by: field)` relations
+- child `fields:` must belong to the target model
+- the inverse `by:` field is seeded automatically and must not be listed again
+- child `fields:` may currently use scalar, enum, or `belongsTo(...)`
+- child `fields:` may not use `hasMany(...)`
+- `update.includes` one-level diff semantics are:
+  - child items with `id` update existing children under the parent
+  - child items without `id` create new children
+  - omitted existing children are deleted
+
+Current `workflow:` rules:
+
+- `workflow:` is optional and must use `@flow("./workflows/x")`
+- extensionless logical ids are preferred for `workflow:`
+- the linked workflow `model` must match the resource model
+- the linked workflow `field` must point to an `enum(...)` field on that model
+- the linked workflow must declare every enum value from that field, and every declared workflow
+  state must exist in that enum
+- generated workflow mutation paths add transition enforcement endpoints and preserve state on normal
+  update payloads
+
+## Transaction Rule
+
+Generated backend write paths are transactional by default in the implemented targets:
+
+- `resource create`
+- `resource update`
+- `resource delete`
+- nested `create.includes` / `update.includes`
+- workflow-linked create/update/transition paths
+
+Current target behavior:
+
+- Spring -> `@Transactional`
+- FastAPI -> one generated `Session` commit/rollback boundary
+
+Authors do not need and should not invent `transactional: true` in source DSL.
+
+Custom escape hatches keep their own transaction boundary:
+
+- `@fn(...)` is responsible for itself
+- `@sql(...)` is read-model-only and read-only today
+
+## Backend Escape Hatches
+
+Use escape hatches only when the current `.api.loj` slice cannot express the behavior directly.
+
+### `readModel handler: '@fn("./handlers/x")'`
+
+Use `@fn(...)` for target-local query logic that is too specific for the shared read-model slice.
+
+Rules:
+
+- the handler file is a target-language function-body snippet, not a full controller/service/module
+- extensionless logical ids are preferred
+- Spring resolves to `.java`
+- FastAPI resolves to `.py`
+
+Current snippet contract:
+
+- Spring executes inside:
+  - `List<ReadModelResult> execute(ReadModelInput input, PolicyPrincipal principal)`
+- FastAPI executes inside:
+  - `def execute(db: Session, input: ReadModelInput, principal: AuthenticatedUser | None) -> list[ReadModelResult]`
+
+Current file-shape rule:
+
+- backend `@fn(...)` read-model handlers are function-body snippets
+- do not include package declarations, imports, class declarations, or outer function declarations
+- write only the body that runs inside the generated adapter function
+
+Keep handler code target-local:
+
+- use repositories / ORM / raw SQL as needed inside the snippet
+- do not try to invent backend-family query-builder syntax around it
+
+### `readModel handler: '@sql("./queries/x")'`
+
+Use `@sql(...)` only for narrow read-only read-model handlers.
+
+Rules:
+
+- file-backed only; do not inline large SQL strings into `.api.loj`
+- read-only `SELECT` / `WITH` only
+- no procedures, `CALL`, `EXEC`, or write SQL
+- alias result columns to the declared `result:` field names
+- Spring gets a generated `NamedParameterJdbcTemplate` adapter
+- FastAPI gets a generated `sqlalchemy.text(...)` adapter
+
+### `auth.policy: '@fn(...)'`
+
+Use `@fn(...)` for target-local auth decisions that cannot be expressed by `mode` / `roles` or the
+current `.rules.loj` slice.
+
+Keep it narrow:
+
+- it is an additional policy check, not a replacement for the whole resource contract
+- it keeps its own local transaction/runtime behavior
+- policy snippets are also function-body snippets in the current backend-family targets
+- do not include package/import/class/function declarations there either
+
+## Commands
+
+- `sdsl validate <entry.api.loj>`
+- `sdsl build <entry.api.loj> --out-dir <dir>`
+
+Use `loj.project.yaml` instead when you need project-shell database/runtime profiles, auto-provision,
+shutdown/probe/cors/base-path handling, or coordinated `dev/status/doctor`.
+
+## Guardrails
+
+- Do not invent generic query composition or generic SQL DSL around `readModel`.
+- Do not move database vendors or server runtime/deploy settings into `.api.loj`.
+- Do not leak Spring/FastAPI framework vocabulary into source DSL.