@antelopejs/dms-ai 0.0.1

package/skills/dms-builder-safe/REFERENCE.md

@@ -0,0 +1,111 @@
+# dms-builder-safe reference
+
+## Data resources (Table + DataAPI)
+
+A **resource** is the data layer a table/form displays: a Database `Table`+`Model`
+and a matching `DataAPI` controller at `/api/<name>`, generated as decorator classes
+kept in sync — never hand-write them. The resource ops (and the `controller` binding
+they feed) require a dms-builder engine version that implements them: if one returns
+`request_failed` (the host answered `unknown_op`) or `builder_unavailable`, the
+installed engine doesn't support it — explain the limitation instead of retrying.
+
+1. **Read first.** `BuilderListResources`; `BuilderResourceStructure <ref>` for
+   fields + `version` hash. Hand-edited or relation fields come back `opaque` —
+   safe mode can't reconfigure those.
+2. **Create** with `BuilderCreateResource` (`name`, `fields`, optional `seeds` — each
+   seed row supplies its own `_id`; never declare `_id`, it is auto-managed). It
+   scaffolds a `<name>/{database,data-api,index}.ts` folder and wires the nearest barrel.
+   - `location` — where the folder goes (omit for `src/<name>/`): a dir string
+     relative to the src root, `{ category: <CategoryRef> }` (mirrors that category's
+     page placement; prefer for a resource shared by one section), or
+     `{ page: <PageRef> }` (nests beside that page; prefer for a one-page resource).
+     Pass exact refs from `BuilderListPages`, never guess.
+   - `routes` — which DataAPI endpoints to expose (omit for the full set): `list`,
+     `get`, `create`, `edit`, `delete`, `select` (relation-picker options), `archive`
+     (soft delete + undo), `export`. Pass a subset whenever a resource is not a full
+     CRUD table — a singleton edit form wants `["get","edit"]`, a read-only listing
+     `["list","get"]` — and keep the view in sync: drop the `TableView` `rowActions`
+     whose routes you left out, or bind a `Form` instead for a singleton.
+3. **Edit fields** with `BuilderAddField` / `BuilderConfigureField <ref>#<field>` /
+   `BuilderRemoveField`; field name is immutable (rename = remove + add). **Delete**
+   with `BuilderDeleteResource`: removes the files, unwires the barrel, and by default
+   clears the resource's database table so a name reuse re-seeds cleanly rather than
+   showing stale rows (`keepData: true` to keep them).
+4. **Fields are semantic aspects, not decorators:** `dataType`, `label`, `listable`
+   (default true), `searchable`, `sortable`, `filterable`, `access`
+   (`read`|`readwrite`, default `readwrite`), `required`, `indexed`, `order`. Names
+   colliding with a DataController route or model property (`_id`, `model`, `get`,
+   `list`, `select`, `count`, `new`, `edit`, `delete`, `archive`, `restore`,
+   `exportStart`, `exportStatus`, `exportDownload`) are rejected with `invalid_config`.
+
+**Displaying a resource on a page is a safe-mode step**: create and populate the
+resource, then `BuilderAddBlock` a `TableView` with `controller` = the resource `ref`
+and display options in `config`. Relation columns work via `$ref` (see
+"DataType, component, and reference values" in SKILL.md).
+
+## Queries (computed numbers a DataAPI can't serve)
+
+A **query** is a derived-data endpoint on a *page*: a GET route returning one computed
+number — a count, a sum, an average — backed by a generated method on the resource's
+model. The DataAPI serves rows; a query serves an aggregate over them. Reach for one
+whenever a block needs a number rather than a list — a **KpiCard** is the usual consumer.
+
+1. **Read the templates.** `BuilderQueryTemplates` returns each template's `id`, what it
+   computes, its `output` kind, and its `params` schema. Never guess an id or a param key —
+   an unrecognised key is rejected. v1 has `count` and `aggregate`, both `output: "scalar"`.
+2. **Add the query** with `BuilderAddQuery` on the page that will display it (not the
+   resource's page). It compiles the template into a model method and a page route in one
+   atomic op and returns `{ query, route }`.
+3. **Wire the block to it.** `route` is the full URL — pass it as the card's `fetchUrl`.
+   There is no reference sentinel for queries yet, so wire the returned string; if you later
+   move the endpoint, update the card in the same turn.
+4. **Read back** with `BuilderPageStructure` — a page's `queries` array reports each one's
+   `name`, `endpoint`, `resource`, `modelMethod`, `template` and `params`.
+5. **Reconfigure / remove** with `BuilderConfigureQuery` (only the keys you patch change)
+   and `BuilderRemoveQuery` (drops the route, and the model method once nothing calls it).
+
+**Params** are documented by each template's own `params` schema from
+`BuilderQueryTemplates` — every key, every value shape, down to the enums. Read it rather
+than guessing; an unrecognised key is rejected.
+
+The one idea worth stating here, because it is what makes a query reusable: a filter value
+can be **bound to a request parameter** instead of baked into the chain
+(`{ "$param": { "name": "min" } }`), so one query answers `?min=25` and `?min=100`
+rather than needing a query per threshold. Bake the value in when it is part of what the
+query *means* (in-stock rows), bind it when the caller chooses (a price threshold). The
+`name`/`in` you give a `$param` shape the route, not the model: the route reads the value
+from that source and hands it to the model method, whose own parameter is named for you.
+
+```json
+{
+  "page": "/catalog/books", "name": "inStockValue", "resource": "book",
+  "template": "aggregate",
+  "params": { "op": "sum", "field": "price",
+              "where": [ { "field": "inStock", "op": "eq", "value": true } ] }
+}
+```
+→ `{ "query": "/catalog/books@inStockValue", "route": "/catalog/books/stats/in-stock-value" }`,
+serving `{ "value": 110.48 }`.
+
+**What you don't have to manage.** The route is auth-gated by the page, automatically —
+a query is never public. Queries wanting the identical chain share one model method, and a
+query whose chain diverges from a method others still use gets its own rather than editing
+theirs — which is why a `modelMethod` may not match its query's name (`inStockCount2`). All
+of that is handled for you: reconfiguring or removing one query never changes what another
+page's query returns.
+
+**Endpoints are a default, not a namespace.** `/stats/<kebab-name>` unless you pass
+`endpoint`; any path is fine as long as it starts with `/` and the page doesn't already
+serve it. One coupling: a `$param` with `in: "param"` reads a path segment, so its
+`endpoint` must declare a matching `:name` (`in: "query"`, the default, needs nothing).
+
+**Opaque queries.** Read-back is purely structural: the builder recognizes a query by its
+shape, so anything it can parse it can edit. A query is opaque **only when it no longer
+parses** — not merely because a human touched it. An in-grammar edit (a changed threshold, an
+added filter) is simply re-read and stays editable. `opaqueReason` is `unparseable_route` (the
+GET wrapper isn't the `return { value: await model.m(...) }` shape) or `unparseable_chain` (the
+model method isn't a chain any template accepts — hand-written differently, edited out of the
+grammar, or emitted by a newer builder). `BuilderConfigureQuery` refuses an opaque query with
+`opaque_target`, but it stays visible and `BuilderRemoveQuery` still works: the builder can
+always remove what it cannot edit. To reshape an opaque query, edit it in vibe mode — or bring
+its body back within the chain grammar and the builder picks it up again.

package/skills/dms-builder-safe/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: dms-builder-safe
+description: Builds or modifies AntelopeJS DMS admin pages through the Builder MCP tools instead of raw code edits. Use when the generation mode is "safe", or when the user wants predictable, typechecked page edits (add/configure/move/remove blocks, create pages and categories).
+icon: i-ph-shield-check
+category: Builder
+tags: [Pages, Builder, SafeMode, DMS]
+---
+
+# Building DMS pages through the Builder (safe mode)
+
+In safe mode you act **only through the `Builder*` MCP tools** — raw file edits
+(`Write`/`Edit`/`Bash`) are blocked. Every op is **atomic and typecheck-gated**: on
+success it returns the file changes; on `typecheck_failed` **nothing is written**.
+
+## Addressing
+
+- **PageRef** = the page's route, e.g. `/charts/revenue`.
+- **BlockPath** = `<pageRef>#<name>[/<childId>...]`: `#<name>` is a top-level block;
+  each `/<childId>` descends into a container's child.
+- **CategoryRef** = a dotted id, e.g. `pages.charts` (top-level pages under `pages.*`;
+  module pages under `modules.<id>.*`). Get exact refs from `BuilderListPages`, never guess.
+- **ResourceRef** = a data resource's id — its `/api/<name>` route segment.
+  **FieldPath** = `<resourceRef>#<fieldName>` (flat). Get refs from `BuilderListResources`.
+- **QueryRef** = `<pageRef>@<queryName>`, e.g. `/catalog/books@inStockCount`. The page is
+  where the route lives; the resource it reads is recorded in the query. Get refs from
+  `BuilderPageStructure`'s `queries`.
+
+## DataType, component, and reference values
+
+- Wherever the catalog marks a config field `x-dataType` (a Form field's `type`, a
+  TableView `Column` `type`, a resource field's `dataType`), pass a **DataType value**
+  `{ $dataType: "<id>", config: {…} }` — an id from `BuilderCatalog`'s `dataTypes`.
+  Never pass a raw `$expr`; safe mode refuses it.
+- Config fields the catalog marks `x-component` hold a nested component (e.g. a
+  ChartCard's `chart`), which safe mode cannot construct — there is no `$expr` escape
+  hatch. Treat them like `opaque_target`: explain and ask to switch to Vibe mode.
+- To name a builder-generated resource class inside config — e.g. a relation column's
+  `dataApiController` — pass a **reference value**
+  `{ $ref: { resource: "<ref>", as?: "dataApi" | "table" | "model" } }` (default `as`
+  = `dataApi`). The resource must already exist. Unlike `$expr`, `$ref` is validated
+  and **allowed in safe mode**, so relation columns work in safe mode.
+
+## Workflow
+
+1. **Discover the catalog first.** `BuilderCatalog` lists the valid block `type`s
+   (Grid, GridRow, KpiCard, Form, Tab, Tree, ChartCard, TableView, …), their config
+   schemas, and the DataTypes. Only use types it lists.
+2. **Read before you write.** `BuilderListPages` to find a page/category;
+   `BuilderPageStructure <pageRef>` for the block tree, `editable` flags, and
+   `version` hash. Model new blocks on an existing page.
+3. **Create a page** with `BuilderCreatePage` (pass a real `CategoryRef`); it returns
+   `{ ref, filepath }`. Immediately `NavigateToPage` to the new (empty) page — before
+   adding any blocks — so the user watches it fill in block by block.
+4. **Add blocks** with `BuilderAddBlock`: omit `parent` for a top-level block or pass
+   a container's BlockPath to nest; `name` unique among siblings; `type` + `config`
+   from the catalog. **Controller-leading blocks** (catalog `controllerArg: true`,
+   e.g. `TableView`) bind to a data resource: pass `controller` = the resource `ref`
+   (its DataAPI class becomes the leading argument) and display options in `config`.
+   Required for those types; rejected for others.
+5. **Configure / rearrange**: `BuilderConfigureBlock` merges options (`replace: true`
+   to overwrite). Children are managed only via `BuilderAddBlock` /
+   `BuilderMoveBlock` / `BuilderRemoveBlock` (removes the whole subtree).
+6. **Pages & categories**: `BuilderConfigurePage` edits page metadata (displayName,
+   icon, order, description); `BuilderDeletePage` removes a page and its barrel
+   import; `BuilderCreateCategory` / `BuilderConfigureCategory` /
+   `BuilderDeleteCategory` manage categories. Category delete is refused with
+   `referential_integrity` while any page still references it — `BuilderDeletePage`
+   those pages first.
+7. **Verify at runtime.** A typecheck-clean edit can still be wrong at runtime (a
+   bad `fetchUrl` 404s): `NavigateToPage` to load the page and `QueryLogs` to check
+   the host's actual reload/runtime output.
+
+## Data resources (Table + DataAPI)
+
+A **resource** is the data layer a table/form displays: a Database `Table`+`Model`
+and a matching `DataAPI` controller at `/api/<name>`, generated as decorator classes
+kept in sync — never hand-write them. Displaying one on a page is a safe-mode step:
+create and populate the resource, then `BuilderAddBlock` a `TableView` with
+`controller` = the resource `ref`. See [REFERENCE.md](REFERENCE.md) for the full
+resource workflow (`BuilderListResources` / `BuilderCreateResource` with `location`
+and `routes` / field ops / `BuilderDeleteResource`), field semantics and reserved
+names, and the engine-support caveat for resource ops.
+
+## Queries (computed numbers a DataAPI can't serve)
+
+A **query** is a derived-data endpoint on a *page*: a GET route returning one computed
+number — a count, a sum, an average — backed by a generated method on a resource's model.
+The DataAPI serves rows; a query serves an aggregate over them, and a **KpiCard** is the
+usual consumer. Add one with `BuilderAddQuery` on the page that will display it (not the
+resource's page), wire the returned `route` as the card's `fetchUrl`, and read it back
+through `BuilderPageStructure`'s `queries`. See [REFERENCE.md](REFERENCE.md) for the
+template catalog, route-bound params, opaque read-back, and the full query workflow.
+
+## Errors & escalation
+
+- `typecheck_failed` → the emitted code didn't compile; read `diagnostics`, fix the
+  `config`/`type`, retry. Nothing was written.
+- `invalid_config` / `duplicate_name` / `not_found` → fix the input.
+- `builder_unavailable` / `request_failed` → the host's builder engine is unreachable
+  or doesn't implement the op (`request_failed` with `HTTP 400` = the host answered
+  `unknown_op`). Explain the limitation; don't retry.
+- `opaque_target` / `unsupported` → **safe mode cannot do this**. Explain the
+  limitation and ask permission to switch to **Vibe mode** for that one step; do not
+  force it. After any vibe-mode excursion, call `BuilderRefresh` (optionally scoped
+  to the page) so the builder's source index reconciles with disk before further
+  safe-mode ops.
+- `stale` → the page changed under you; re-read with `BuilderPageStructure`, retry.
+
+## Guardrails
+
+- Always `BuilderCatalog` before adding blocks; use only listed types + config keys.
+  Likewise `BuilderQueryTemplates` before adding a query.
+- Block/child names are mandatory and unique among siblings.
+- A card showing an aggregate needs a query behind it — don't point a `fetchUrl` at a
+  DataAPI route and hope it returns a number.
+- After a structural change, navigate to the page and check logs before declaring done.
+  A query is the case where this matters most: it typechecks against the field names but
+  the number it returns is only visible at runtime.