@loj-lang/cli 0.5.0

package/agent-assets/loj-authoring/references/frontend-runtime-trace.md

@@ -0,0 +1,204 @@
+# Frontend Runtime And Trace
+
+Use this reference when the task involves generated React code, runtime assumptions, `rdsl inspect`,
+or `rdsl trace`.
+
+## Current Generated Target
+
+- frontend-family currently generates `react + typescript`
+- generated code imports direct subpaths from `@loj-lang/rdsl-runtime`
+- generated code should not assume a barrel-export-only runtime contract
+
+Current direct runtime import families used by generated code include:
+
+- components:
+  - `DataTable`
+  - `GroupedDataTable`
+  - `PivotDataTable`
+  - `FilterBar`
+  - `Pagination`
+  - `FormField`
+  - `ConfirmDialog`
+  - `WorkflowSummary`
+- hooks:
+  - `useResource`
+  - `useReadModel`
+  - `useCollectionView`
+  - `useGroupedCollectionView`
+  - `useToast`
+  - `useAuth`
+  - `useDocumentMetadata`
+  - navigation helpers under `hooks/navigation`
+- policy helper:
+  - `can`
+
+## Runtime Assumptions
+
+### `useResource(api)`
+
+Generated CRUD flows assume `useResource` provides:
+
+- `data`
+- `allData`
+- `loading`
+- `error`
+- `filters`, `setFilters`
+- `sort`, `setSort`
+- `pagination`, `setPagination`
+- `getById`
+- `createItem`
+- `updateItem`
+- `deleteItem`
+- `refresh`
+
+Resource records always have `id: string` at the frontend runtime surface.
+
+Generated relation/page reuse still depends on `allData` for:
+
+- relation-derived projections such as `team.name` / `members.count`
+- record-scoped relation page filtering by inverse foreign key
+- relation-aware create/edit/read back-link reuse
+
+### `useReadModel(api, options)`
+
+Generated read-model pages assume a fixed GET list-style contract and current helper behavior for:
+
+- `data`
+- `loading`
+- `error`
+- URL-backed query inputs
+- required-input gating before fetch
+
+Current read-model pages may also layer:
+
+- shared `queryState`
+- `dateNavigation`
+- `selectionState`
+- grouped/pivoted table presentation over fetched rows
+
+### `useCollectionView(items, options)` / `useGroupedCollectionView(items, options)`
+
+Generated list, related-panel, page-table, grouped-table, and grouped-matrix surfaces assume these
+helpers provide:
+
+- `data`
+- `filters`, `setFilters`
+- `sort`, `setSort`
+- `pagination`, `setPagination`
+
+Current rule:
+
+- filtering, sorting, grouping, pivoting, and pagination are currently client-side after fetch
+- relation-derived filters and sortable relation columns are applied over projected table data, not
+  server-side joins
+
+### `useToast()`
+
+Generated code may call:
+
+- `toast.success("Saved!")`
+- `toast.success({ key, defaultMessage, values })`
+
+Descriptor values stay scalar/deterministic.
+
+### `useDocumentMetadata()`
+
+Generated web metadata surfaces now assume runtime support for:
+
+- `document.title`
+- meta `description`
+- canonical link
+- `og:*` image/title/description-ish fields
+- favicon
+
+That support is driven by `.web.loj` `app.seo`, `page.seo`, and `@asset(...)`, not by ad hoc host code.
+
+### Navigation helpers
+
+Generated code now assumes runtime helpers for:
+
+- app-local href construction
+- sanitized `returnTo`
+- current location/search parsing
+- optional web `runtime.basePath` stripping/prefixing
+
+Do not hand-edit generated code to bypass those helpers.
+
+### `can(rule, context)`
+
+Generated code uses `can()` only for built-in normalized rule ASTs.
+
+It currently gates:
+
+- `visibleIf`
+- `enabledIf`
+- linked grouped-rule eligibility/validation surfaces
+- navigation visibility
+- workflow step visibility
+
+## Runtime Transport Baseline
+
+The current frontend runtime accepts list responses shaped as:
+
+- raw array
+- `{ items: [...] }`
+- `{ data: [...] }`
+
+Single-record responses may be:
+
+- raw object
+- `{ item: {...} }`
+- `{ data: {...} }`
+
+Errors may be:
+
+- non-2xx JSON with string `message`
+
+Important current rule:
+
+- server-driven pagination metadata is not required
+- list pagination is currently derived client-side after fetch
+
+## Browser Events
+
+Generated code may emit:
+
+- `rdsl:refresh`
+- `rdsl:invalidate`
+- `rdsl:open-dialog`
+
+These are still part of generated-code/runtime integration.
+
+## Trace And Inspect
+
+Use:
+
+- `rdsl inspect <entry.web.loj|build-dir> [--node <id>]`
+- `rdsl trace <entry-or-build-dir> <generated-file:line[:col]>`
+
+Current manifest split:
+
+- `semantic-manifest.json`
+- `trace-manifest.json`
+
+Important trace concepts:
+
+- `sourceFiles`
+- `generatedFiles`
+- `nodes`
+- `regions`
+- `hostFiles`
+
+What they mean:
+
+- `nodes`: semantic node catalog
+- `regions`: generated file spans mapped back to semantic nodes
+- `hostFiles`: copied escape-hatch files plus copied dependencies such as CSS and asset closures
+
+## Authoring Guardrails
+
+- When reviewing generated React code, validate it against these runtime contracts, not ad hoc
+  assumptions.
+- If a task is about generated-output bugs, check runtime contract mismatches first.
+- If a task is about trace/inspect behavior, reason in terms of `semantic node -> generated region`,
+  not line comments alone.

package/agent-assets/loj-authoring/references/policy-rules-proof.md

@@ -0,0 +1,178 @@
+# Policy / Rules Proof (`.rules.loj`)
+
+Use this reference only for the current first-slice rules proof.
+
+This is still a narrow surface. It is now wired into backend-family `.api.loj` through:
+
+- `resource auth.policy: '@rules("./policies/x")'`
+- `resource create.rules: '@rules("./rules/x")'`
+- `readModel <name> rules: '@rules("./rules/x")'`
+
+It is now also wired into frontend-family `.web.loj` through:
+
+- `readModel <name> rules: '@rules("./rules/x")'`
+- `resource create.rules: '@rules("./rules/x")'`
+- `resource edit.rules: '@rules("./rules/x")'`
+- `resource create.includes[].rules: '@rules("./rules/x")'`
+- `resource edit.includes[].rules: '@rules("./rules/x")'`
+
+It is still not orchestrated through `loj.project.yaml`.
+
+## Current Scope
+
+Implemented today:
+
+- `.rules.loj` file suffix
+- one named rule set per file
+- parser + validator + target-neutral semantic manifest generation
+- grouped rule entry kinds:
+  - `allow/deny <operation>`
+  - `eligibility <name>`
+  - `validate <name>`
+  - `derive <field>`
+- repo CLI entry:
+  - `loj rules validate <file.rules.loj>`
+  - `loj rules build <file.rules.loj> --out-dir <dir>`
+
+Not implemented yet:
+
+- workflow `.flow.loj`
+- project-shell orchestration for rules targets
+- broader frontend `.rules.loj` consumers beyond the current read-model plus generated create/edit form surfaces
+
+## File Shape
+
+Use one top-level block:
+
+```yaml
+rules invoice-access:
+  allow list:
+    when: currentUser.role in [ADMIN, FINANCE, SALES]
+
+  allow update:
+    when: currentUser.role == ADMIN
+    or:
+      - currentUser.id == record.accountManagerId
+
+  deny delete:
+    when: record.status == COMPLETED
+    message:
+      key: "invoice.delete.completed"
+      defaultMessage: "Completed invoices cannot be deleted."
+```
+
+Rules:
+
+- exactly one top-level `rules <name>:` block per file
+- entry keys may be:
+  - `allow <operation>`
+  - `deny <operation>`
+  - `eligibility <name>`
+  - `validate <name>`
+  - `derive <field>`
+- supported operations:
+  - `list`
+  - `get`
+  - `create`
+  - `update`
+  - `delete`
+
+## Supported Fields
+
+Inside auth `allow ...` / `deny ...` blocks:
+
+- required:
+  - `when`
+- optional:
+  - `or`
+  - `message`
+  - `scopeWhen`
+  - `scope`
+
+Field rules:
+
+- `when` must be a non-empty expression string
+- `or` may be one string or a sequence of strings
+- `message` may be:
+  - one string
+  - one descriptor object with `key`, `defaultMessage`, optional `values`
+- `scopeWhen` and `scope` are allowed only on `list`
+- if one of `scopeWhen` / `scope` is present, both must be present
+
+Inside `eligibility <name>` / `validate <name>` blocks:
+
+- required:
+  - `when`
+- optional:
+  - `or`
+  - `message`
+
+Inside `derive <field>` blocks:
+
+- required:
+  - `value`
+- optional:
+  - `when`
+
+## Expression Language
+
+The current rules proof reuses the same constrained expression language used by core web-family
+rules.
+
+Use:
+
+- comparisons like `==`, `!=`, `>`, `<`, `>=`, `<=`
+- arithmetic like `+`, `-`, `*`, `/`
+- logical `&&`, `||`, `not`
+- dotted paths like `currentUser.role`, `record.status`
+- membership like `currentUser.role in [ADMIN, SALES]`
+- built-ins such as `hasRole(...)`, `isOwner(...)`, `isEmpty(...)`, `count(...)`
+
+Do not use:
+
+- raw JavaScript or Python
+- statements, loops, imports, closures
+- framework/runtime internals
+
+## Current Command Path
+
+Validate:
+
+```bash
+loj rules validate ./policies/invoice-access.rules.loj
+```
+
+Build manifest:
+
+```bash
+loj rules build ./policies/invoice-access.rules.loj --out-dir ./generated/rules
+```
+
+Current build output is a standalone semantic manifest JSON file. Treat it as the first proof
+surface plus a few narrow backend-family linkage points, not as a finished cross-target rules
+system.
+
+## Hard Guardrails
+
+- The only implemented `.api.loj` linkages are:
+  - `resource auth.policy: '@rules("./policies/x")'`
+  - `resource create.rules: '@rules("./rules/x")'`
+  - `readModel <name> rules: '@rules("./rules/x")'`
+- The implemented `.web.loj` linkages are:
+  - `readModel <name> rules: '@rules("./rules/x")'`
+  - `resource create.rules: '@rules("./rules/x")'`
+  - `resource edit.rules: '@rules("./rules/x")'`
+  - `resource create.includes[].rules: '@rules("./rules/x")'`
+  - `resource edit.includes[].rules: '@rules("./rules/x")'`
+- Current linkage boundaries:
+  - `auth.policy` consumes only `allow/deny` auth entries
+  - backend `create.rules` consumes only `eligibility` + `validate`
+  - `readModel rules` consumes only `eligibility` + `validate` + `derive`
+  - frontend `readModel rules` use `eligibility` / `validate` only for local fetch gating and `derive` only for client-side row derivation after fetch
+  - frontend `create.rules` / `edit.rules` use `eligibility` for local generated-form gating, `validate` for local pre-submit checks, and `derive` only for top-level scalar generated fields already listed in the form
+  - frontend `create.includes[].rules` / `edit.includes[].rules` use `eligibility` / `validate` for local repeated-child item gating and validation, and `derive` only for scalar child fields already listed in that include's `fields:`
+  - frontend `readModel rules` reject `allow/deny` entries
+  - frontend generated form consumers (`create.rules`, `edit.rules`, `create.includes[].rules`, `edit.includes[].rules`) all reject `allow/deny` entries
+- Do not invent `type: rules` inside `loj.project.yaml` yet.
+- Do not add workflow/state-machine syntax to `.rules.loj`.
+- Keep rule authoring declarative and target-neutral.