@lotics/cli 0.263.0 → 0.266.0

package/docs/migration.md

@@ -1,99 +1,72 @@
 # @lotics/cli — migration notes
 
-What an app author has to DO when a release changes the shape of a project the CLI owns. Every
-other contract is `docs/cli_reference.md`; this file is the one a reader opens once, because
-something already on disk no longer matches what the CLI writes.
-
-## Opt-in history and starts, `app.json` version 4
-
-A record's status history and an add's starting values are stated, never inferred. The history is still
-written on every move; it is drawn only where the app asks.
-
-1. **`record.history: true`** on each app whose record should show its status history beside it (a
-   shipment, a gate in and out, an order and its logistics). Without it the history is drawn nowhere. A
-   block of the history entity in a section is refused: `record.history` draws it.
-2. **`records.<e>.starts: { <field>: "today" | "me" }`** where an add should start a date at today (a
-   moment at now) or a member at the reader. Without it such a field starts empty.
-3. **`lotics app regenerate`** writes `app.json` version 4; a version 3 spec stops at its first render with
-   `app.json is version 3; this runtime reads version 4`.
-
-## A record's `sections`, `app.json` version 3
-
-A record is its `sections`, stacked in the order the work reaches them, replacing `record.facts` and
-`record.blocks`: each section a `title`, its `fields`, the `acts` under them and its `blocks`, and `at`
-naming the status options it is the work of. The comment thread is `record.comments: true`, never a
-block. `lotics scaffold check` refuses `facts`, `blocks` and a comments block by name.
-
-1. **Restate each record.** Each fact group becomes a section with its title and fields; move each
-   block into the section it belongs to (a leg's fees into that leg's section, narrowed by `where`);
-   name in `acts` the acts whose inputs live there — an act no section names is a button in the header.
-   A staged section's acts are offered during its stage alone: an act offered at other stages stands
-   in their section, in a section with no `at`, or in the header.
-2. **`lotics app regenerate`** in the app directory writes `app.json` version 3. `@lotics/app-runtime`
-   reads version 3 alone: a version 2 spec stops at its first render with `app.json is version 2; this
-   runtime reads version 3`.
-
-## Apps built from a model: `records` and `apps`
-
-A model states an app in one vocabulary: `records` says how a row of each entity is recognised (its
-title, the line under it, its picture, its status, its figure, its deadlines), and each entry of
-`apps` is one register over one entity and the record its rows open — its columns and filters, its
-sections, its acts and its checks (`lotics docs model/apps`). How each piece looks is the runtime's;
-no key changes it. `lotics app create --from` compiles that into `app.json`, and an older spec stops
-at its first render naming the version this runtime reads.
-
-What a model no longer holds, each refused by name by `lotics scaffold check`:
-
-- **`field_roles`, screen shapes and their clauses** — `records` and `apps` state what they stated.
-- **`table_workflows`** — a model keeps no table automation. A status `history` is appended by the
-  app's own generated write that moves the status.
-- **`connections`** — nothing in a model pushes through an account any more.
-
-### Moving an app generated from an earlier model
-
-1. **Restate the model.** Replace `field_roles` with a `records` entry per entity the app lists,
-   opens or picks, and each app with its register, record, acts and checks. `lotics scaffold check`
-   prints every app as its reader will see it; `lotics app preview <model.json>#<app>` draws it.
-2. **`lotics app regenerate`** in the app directory. It rewrites `app.json`, `src/main.tsx` and the
-   generated workflow bodies. The generated aliases are new (`<entity>_list`, `create_<entity>`,
-   `act_<alias>`, …), so the old ones are retired: their bodies are deleted and the next
-   `lotics app deploy` unbinds them.
-3. **A component the app took over keeps its file, and loses what it wrapped.** The runtime exports
-   no screen, section or act renderer, and `lotics app eject` is gone. A part the vocabulary now
-   states goes back into the model; a record part it cannot state is a `component` block (the
-   component is handed `{ record, spec, refresh }` — `lotics docs components`); an act whose write
-   `set` cannot say names its own `workflow`, which runs after the generated guards.
-4. **Remove the history automations an earlier `scaffold apply` installed.** They are not deleted
-   by anything, and beside the app's own history append every move would write two rows.
-   `lotics run remove_table_workflow` takes each one off its table.
-5. `lotics app check`, then `lotics app deploy`.
-
-### What `app regenerate` owns
-
-- **No three-way merge, and no conflict markers.** The generator owns every file it emits:
-  `app.json` is compiled whole; a generated workflow body is rewritten and what it replaced is parked
-  in `.lotics/regenerate-dropped.patch`, file by file.
-- **Two things are yours**: `src/components/` (seeded where it is absent, named back where you have
-  changed it, never rewritten), and an act's own `workflow`, of which only the guard region between
-  its `<lotics:guards>` markers is rewritten.
-- A TSX app with no `app.json` is untouched by all of this. Delete `package.json#lotics.plan` and it
-  is a hand-written project like any other; `app regenerate` then refuses, which is the correct
-  answer for a tree nothing generates.
-
-## The SDK is part of the runtime
-
-`@lotics/app-sdk` moved into `@lotics/app-runtime`. One package carries the hooks, the router and
-the renderer, so an app lists one range and a kit correction cannot reach the renderer without
-reaching the hooks it reads through. An app changes two things:
-
-- **The dependency.** `@lotics/app-runtime` replaces `@lotics/app-sdk`. `@lotics/ui` stays beside it
-  only where the app's own code imports the kit, at the range the runtime depends on: two ranges
-  are two copies of the kit, neither seeing the other's context.
-- **The import specifiers.** `@lotics/app-sdk` becomes `@lotics/app-runtime/sdk`, and
-  `@lotics/app-sdk/router` becomes `@lotics/app-runtime/router` — in `src/`, and in `vite.config.ts`,
-  whose test optimizer names the SDK in a scaffolded app.
-
-`lotics app kit --published` makes the first two: it rewrites every quoted specifier, drops the
-dependency, installs the runtime and names each file it rewrote. `lotics app regenerate` does the
-same, and so does `lotics workspace build` for every app it regenerates; `lotics app check` names
-every app still listing `@lotics/app-sdk`. A deployed app keeps running on the bundle it shipped until it is rebuilt.
+What to DO when a release changes the shape of something the CLI once wrote to disk. Every other
+contract is `docs/cli_reference.md`; this file is the one a reader opens once, because something
+already on disk no longer matches what the CLI does.
+
+## Local app projects are gone
+
+An app built from a model no longer lives in a directory. The live app is the only edit surface:
+each change mints a new version of it, and rolling back to an earlier version is the undo. What
+the app is — its screens (`app.json`), its queries, workflows, agents and capabilities, and the
+model body it was compiled from — is held by that version, and the model's tables, fields, options,
+templates and roles are the workspace's own.
+
+| What you ran | What replaces it |
+|---|---|
+| `lotics scaffold check` + `scaffold apply` | `lotics model apply <model.json>` — checks the file, applies the tables and rows, then mints a version of every app it declares |
+| `lotics workspace build <model.json>` | `lotics model apply <model.json>` |
+| `lotics app create --from <model.json>#<app>` | `lotics model apply <model.json> --app <app>` |
+| `lotics app regenerate` | change the model file, then `lotics model apply` |
+| `lotics scaffold diff` | `lotics model apply <model.json> --plan` — what the apply would change, writing nothing |
+| `lotics scaffold export` | `lotics model pull [-o <model.json>]` — the workspace's model, rebuilt from what owns each part |
+| `lotics app pull`, `app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |
+| `lotics app workflow set` / `app query set` / `app agent set` | `lotics run set_app_workflow` / `set_app_query` / `set_app_agent` — each mints a version |
+| `lotics app versions` + a redeploy of an old tree | `lotics run query_app_versions`, then `lotics run rollback_app` — restores the app's earlier version; table changes and data writes stay |
+| `lotics app rename`, `app subdomain`, `package.json#lotics.capabilities` | `lotics run update_app` (`name`, `public_subdomain`, `capabilities`) |
+| `lotics app api publish` / `unpublish` | `lotics run publish_app_api` / `unpublish_app_api` |
+| `lotics field rename` | `lotics run update_table`, then the same label in the model file |
+| `lotics app kit` | nothing: a custom-code app depends on `@lotics/app-sdk` (below) |
+| `@lotics/xlsx` / `@lotics/docx` to build a template's file | any `.xlsx` / `.docx` library, then `lotics upload` (`lotics docs document_templates`) |
+| `lotics file preview` | `lotics file download <fil_id>`, then open it |
+| `model.json#apply` (`[{package, bind}]`) | state the tables under `entities` — a model carrying `apply` is refused |
+| `lotics library list` / `library show <slug>`, `lotics preset list` / `preset show <slug>` | the example models at `https://lotics.ai/presets/index.json`, each a complete `model.json` to adapt |
+| `model.json#from` (with `variants`, `rename`) | state every table under `entities` — a model carrying `from` is refused |
+| `lotics library init <apg_id>`, `lotics setup <apg_id>`, `lotics app upgrade`, `lotics library fixtures` | nothing copies a package any more: write a `model.json` (`lotics docs model`), then `lotics setup model.json` or `lotics model apply model.json` |
+
+`lotics tools` lists every tool, and `lotics tools <name>` prints its input.
+
+**An existing JSON app moves on the first `lotics model apply`** of the model it came from: that
+apply binds each app alias to the app it already became and mints its next version from the file.
+A directory an earlier CLI wrote (`app.json`, `src/workflows/`, `.lotics/`, `package.json#lotics`
+with `plan`, `queries` or `workflows`) is no longer read by anything; keep the model file, delete the
+rest.
+
+**Authored workflow bodies** an act names (`workflow` on an act) are the live workflow's own body:
+the apply keeps it, and `lotics run set_app_workflow` changes it.
+
+**A model written before `party`** draws its people and organisations as things — a row with no
+picture shows no initials: state `party` (`person` or `organization`) on those entities' `records`.
+
+## Custom-code apps use `@lotics/app-sdk`
+
+A hand-written app depends on `@lotics/app-sdk` alone — the hooks (`useQuery`, `useWorkflow`, …),
+`mount`, and `AppRouter` from `@lotics/app-sdk/router` — and draws with its own React.
+`@lotics/app-runtime` and `@lotics/ui` are no longer published: the runtime is what the platform
+draws a model's app with, and it ships with the platform.
+
+An app that listed `@lotics/app-runtime`:
+
+1. **The dependency.** `@lotics/app-sdk` replaces `@lotics/app-runtime` in `package.json`.
+2. **The import specifiers.** `@lotics/app-runtime/sdk` becomes `@lotics/app-sdk`, and
+   `@lotics/app-runtime/router` becomes `@lotics/app-sdk/router` — in `src/` and in
+   `vite.config.ts`.
+3. **The kit.** An app that imports `@lotics/ui` keeps the version it already installed; no newer one
+   is published. Its screens can stay on it, or move to plain React (or any library) one screen at a
+   time.
+4. **`package.json#lotics`** needs only `app_id`, `workspace_id` and `current_version_id`. The live
+   app owns its `queries`, `workflows`, `agents` and `capabilities`, and `lotics app deploy` refuses
+   a directory that still declares any of them; delete them, and the unread `synced` block.
+5. `lotics app deploy` builds the directory and uploads it as a new version.
+
+A deployed app keeps running on the bundle it shipped until it is deployed again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.263.0",
+  "version": "0.266.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {