@lotics/cli 0.318.30 → 0.318.32
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/README.md +1 -1
- package/dist/src/cli.js +30 -23
- package/docs/agent_surface.md +3 -3
- package/docs/app_bindings.md +24 -9
- package/docs/building_an_app.md +2 -2
- package/docs/cli_reference.md +3 -3
- package/docs/knowledge_docs.md +1 -1
- package/docs/migration.md +3 -2
- package/docs/permissions.md +7 -5
- package/docs/workflow_steps.md +3 -3
- package/docs/workflows.md +2 -2
- package/docs/working_in_a_workspace.md +2 -2
- package/package.json +1 -1
package/docs/agent_surface.md
CHANGED
|
@@ -305,9 +305,9 @@ a Reading's `key` take no name the app generates (`reference/app.generated-name`
|
|
|
305
305
|
}
|
|
306
306
|
```
|
|
307
307
|
|
|
308
|
-
`set_workflow` sets its code (`workflows`). A query
|
|
309
|
-
the tree
|
|
310
|
-
node, it is the tree's. A caller sees the description and
|
|
308
|
+
`set_workflow` sets its code (`workflows`). A query the app holds that
|
|
309
|
+
the tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,
|
|
310
|
+
whose answer notes it; declared as a Query node, it is the tree's. A caller sees the description and
|
|
311
311
|
each input's `description` and nothing else, so each says what the value is and what leaving it out means;
|
|
312
312
|
the check notes one that says nothing.
|
|
313
313
|
|
package/docs/app_bindings.md
CHANGED
|
@@ -5,17 +5,29 @@ under an alias — a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):
|
|
|
5
5
|
|
|
6
6
|
| Binding | Declared with | The app calls it with | An agent calls it with |
|
|
7
7
|
|---|---|---|---|
|
|
8
|
-
| Query | `
|
|
8
|
+
| Query | `set_app`, a `Query` node | `useQuery("<alias>", params?)` | `run_app_query` |
|
|
9
9
|
| Workflow | `set_workflow` | `useWorkflow("<alias>")({ ...inputs })` | `run_app_workflow` |
|
|
10
10
|
|
|
11
11
|
Each runs under the app's authority (`{ type: "app", app_id }`), the app owner's reach — never the
|
|
12
12
|
calling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next
|
|
13
13
|
call uses it. `get_app` lists an app's aliases with their params and inputs.
|
|
14
14
|
|
|
15
|
-
Each reader returns a fingerprint of what it read
|
|
16
|
-
`
|
|
17
|
-
`
|
|
18
|
-
|
|
15
|
+
Each reader returns a fingerprint of what it read, and a write built on that read passes it back:
|
|
16
|
+
`get_workflow`'s `version` as `set_workflow`'s `expected_version`, and `get_app`'s version as `set_app`'s
|
|
17
|
+
`base_version_id`. The write is refused, and writes nothing, when it changed since; omit it for an unconditional write.
|
|
18
|
+
|
|
19
|
+
## API apps
|
|
20
|
+
|
|
21
|
+
An API app is one a customer's own server calls. It holds only `Query` and `Workflow` nodes, so no address serves it, and it cannot be shared publicly.
|
|
22
|
+
|
|
23
|
+
1. `set_app` with a tree of those nodes, naming the tables they read in `uses`. The answer carries the link where an admin creates its key, and `get_app` states it again.
|
|
24
|
+
2. `set_workflow` sets each workflow's code.
|
|
25
|
+
3. An admin opens the link and creates an app key (`lak_…`). It reaches this app alone and only calls it; no other route and no tool answers it, and that can never be widened. Its secret is shown once, so it goes straight into the server's secrets, and no tool creates or reads one.
|
|
26
|
+
4. To promise the shape to that server, an admin's `set_app` states `{ "app_id": "…", "api_published": true }`: a numbered contract and an OpenAPI document, and a later write that would break it is refused.
|
|
27
|
+
|
|
28
|
+
The server sends `Authorization: Bearer lak_…` to `POST /v1/apps/{app_id}/queries/{alias}` and `POST /v1/apps/{app_id}/workflows/{alias}/execute`. The answer holds what the app declares, with each row's own id and timestamps: no member's email, no field id, and a failed run a generic message beside its `execution_id`. A browser cannot call them, and a key never goes in a page.
|
|
29
|
+
|
|
30
|
+
A `Query` node reads one table or List with `rows` or `list`. A wider read states the whole query as `ast`, below.
|
|
19
31
|
|
|
20
32
|
## Queries
|
|
21
33
|
|
|
@@ -36,10 +48,13 @@ A save checks what a deploy checks: every table is in this workspace and within
|
|
|
36
48
|
every projected, filtered and sorted field resolves, every param token is declared, and a key a
|
|
37
49
|
node's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.
|
|
38
50
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
51
|
+
`set_app` states one as a `Query` node: `{ "type": "Query", "key": "<alias>", "ast": { … } }`, beside `params`,
|
|
52
|
+
`description` and `templates`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch
|
|
53
|
+
replaces its `ast`, `params` or `templates` whole. On an app that serves
|
|
54
|
+
code, `nodes` takes `{ "<alias>": { … } }` and merges each: send only the fields you change, `null` clears `params`,
|
|
55
|
+
`description` or `templates` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its
|
|
56
|
+
`children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by
|
|
57
|
+
name, and `get_app`'s `body` reads them back by alias.
|
|
43
58
|
|
|
44
59
|
### The query tree
|
|
45
60
|
|
package/docs/building_an_app.md
CHANGED
|
@@ -179,7 +179,7 @@ The contract, and nothing more:
|
|
|
179
179
|
- The app is a static bundle on the app host and reaches data only through the SDK.
|
|
180
180
|
|
|
181
181
|
What the app reads and writes is bound on the app, never in the project: `lotics run
|
|
182
|
-
|
|
182
|
+
set_app` binds named queries (`app_bindings`), `lotics run set_workflow` a workflow body, and each mints a
|
|
183
183
|
version. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy uploads the build
|
|
184
184
|
and carries every binding forward unchanged.
|
|
185
185
|
|
|
@@ -249,4 +249,4 @@ standing process the app expects that agent to carry out belongs there and nowhe
|
|
|
249
249
|
**A caller outside the team gets its own app.** Sharing an app publicly, or giving an API key
|
|
250
250
|
access to it, reaches every alias the app declares; no alias can be held back. So whatever
|
|
251
251
|
outsiders may call is a SECOND app over the same tables: only the queries they may read and the
|
|
252
|
-
workflows they may run. The desk the team works in stays a separate, private app.
|
|
252
|
+
workflows they may run. The desk the team works in stays a separate, private app. One only a server calls is an API app: `lotics docs app_bindings` § API apps.
|
package/docs/cli_reference.md
CHANGED
|
@@ -28,7 +28,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
28
28
|
| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \| lotics run <tool> -`) — both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone — the error names both escapes. |
|
|
29
29
|
| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
|
|
30
30
|
| `lotics run <tool>` — **file cells** | A file in a tool's result carries its `fil_…` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file — this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |
|
|
31
|
-
| — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `
|
|
31
|
+
| — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `set_workflow`. A command exists only for work that touches a local file: `app apply`, `app create --custom`, `app pull`, `app deploy`. |
|
|
32
32
|
| — | **An app's queries and workflows take more than their params and inputs** (`lotics docs agent_surface`). `run_app_query '{"app_id","alias","params"}'` also takes `filters` and `sort` over the query's output columns, `fields` (the columns to return), `count` with `count_by` or `count_where`, `aggregate`, `limit` (200 rows at most; 50 where none is stated) and `cursor`, and `runs` — up to 20 reads in one call, each `{"alias", …}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {"key", …narrowing}` instead of the read arguments makes the file an app's Export makes (`lotics docs agent_surface`). `run_app_workflow '{"app_id","alias","inputs"}'` also takes `dry_run: true` — a rehearsal on the real inputs, nothing written or sent; the answer is what the run would return, with the reads it made under `dry_run.reads`, the calls it would make under `dry_run.writes` and the papers it rendered under `dry_run.papers` and the parts of the answer it could not say under `dry_run.unpredicted`; a workflow no dry run is offered of answers `status: "not_previewed"` — and `runs` — up to 50 runs in order, the first refused, failed or not previewed ending the call, an input `{"from_run": <index>, "path": "data.<key>"}` reading an earlier run's answer. |
|
|
33
33
|
| — | **The exit code reports the WORK, not just the call — for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` — a dry run asked for and not given) exit non-zero and print `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |
|
|
34
34
|
| `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries — an object with a `url`, a `filename` and the `expires_at` its signature ends at, at any depth, such as `screenshot_app`'s images. Each is fetched into `<dir>` (created if missing) under its `filename`, taking a free spelling beside a file of that name already there, and a link's `snapshot` text is written beside it as `<name>.txt`. The written paths follow the answer on **stdout**, one per line (on stderr under `--json`, whose stdout stays the one object). A link is signed for an hour; one the store no longer serves exits non-zero. A workspace file states no `expires_at` and is left to `lotics file download`. |
|
|
@@ -47,8 +47,8 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
47
47
|
| `lotics knowledge rm <id...>` | Delete docs via `set_knowledge` (`{ knowledge_doc_id, delete: true }`), one call per id: each must be a live doc you manage that no app or workflow names, and the command reports which succeeded and which failed. Sharing and history are kept. The REST execute path does not gate `needsApproval`, so this runs unattended. |
|
|
48
48
|
| `lotics knowledge restore <id...>` | Bring deleted docs back via `set_knowledge` (`{ knowledge_doc_id, restore: true }`), one call per id: each must be a deleted doc you manage, and the command reports which succeeded and which failed. Refuses the no-argument form. |
|
|
49
49
|
| `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`) and links `[path]` (default `./<name>`, made when absent) to it by writing `package.json#lotics` (the app and its workspace, which is how `app deploy` in that directory finds both) — into the project's own `package.json` when it has one, every other key kept, otherwise a `package.json` holding the link alone. Nothing else is written and nothing is installed: the project is yours. `app deploy` needs `@lotics/app-sdk` (React 19) and an `npm run build` that writes a static `dist/` with an `index.html`. A directory already linked to an app is refused before the app row exists. The app has no version until the first `lotics app deploy`. `--custom` is required: a JSON app is made by `lotics app apply` (the tool `set_app`). The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` once the project installs it. |
|
|
50
|
-
| `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (
|
|
51
|
-
| `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour)
|
|
50
|
+
| `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (its identity and Query nodes) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ "app_id": "…", "version_id": "…", "digest": "…" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) — a custom-code project records both in `package.json#lotics`, a single file has no such place — so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |
|
|
51
|
+
| `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version — its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) — what would refuse the tree, and what it would grant and remove — and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |
|
|
52
52
|
| `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`GET /v1/apps/{id}/types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent; a type error in the app's own files stops the deploy, one inside an installed package is reported and does not) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged — those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |
|
|
53
53
|
| `lotics docs` \| `lotics docs <area>[/<section>]` \| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** — the model reference, this index, and every doc under `docs/` — so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal — a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`; a literal search that finds nothing while the pattern read as an expression matches (`a|b`) returns those lines under a note saying so, and `--literal` keeps the literal zero; with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` — the dialect the knowledge lines of `get_workspace` with `search` are read in — each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |
|
|
54
54
|
| `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
|
package/docs/knowledge_docs.md
CHANGED
|
@@ -33,7 +33,7 @@ coarse, restate a term the heading was carrying.
|
|
|
33
33
|
|
|
34
34
|
A new doc is **owned by you and private**. `set_access` shares it: `resources[]` with `resource_type` `knowledge_doc`, and `principals[]` (a
|
|
35
35
|
member, a member group, or `organization` for everyone), each with a `role` of `user` or `manager`; a principal without a `role` has
|
|
36
|
-
its access taken away. A doc reaches an agent
|
|
36
|
+
its access taken away. A doc reaches an agent when the member can `use` it. An organization admin can use any doc, and their agent searches what they list unless it passes `all: true`.
|
|
37
37
|
|
|
38
38
|
## How an agent uses a doc
|
|
39
39
|
|
package/docs/migration.md
CHANGED
|
@@ -20,10 +20,11 @@ roles are the workspace's own.
|
|
|
20
20
|
| `lotics scaffold diff` | `lotics app apply <file> --check` — what would refuse the tree, writing nothing |
|
|
21
21
|
| `lotics scaffold export` | `lotics app pull <app_id> [path]` — the app's tree as JSON, one app at a time |
|
|
22
22
|
| `lotics app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |
|
|
23
|
-
| `lotics app workflow set` / `app query set` | `lotics run set_workflow` / `
|
|
23
|
+
| `lotics app workflow set` / `app query set` | `lotics run set_workflow` / `lotics run set_app` with a `Query` node — each mints a version |
|
|
24
|
+
| `lotics run set_app_queries`, `lotics run get_app_query` | `lotics run set_app` with `nodes` (`{ "<alias>": { "type": "Query", "ast": … } }`, `null` unbinds), and `lotics run get_app`, whose `body` lists them |
|
|
24
25
|
| `lotics app versions` + a redeploy of an old tree | apply the earlier tree again (`lotics app apply <file>`), or deploy the earlier source; table changes and data writes stay |
|
|
25
26
|
| `lotics app rename`, `app subdomain`, `package.json#lotics.capabilities` | `lotics run set_app` with the app's id (`public_subdomain`, `capabilities`; its name is the tree's `name`) |
|
|
26
|
-
| `lotics app api publish` / `unpublish` | `lotics run
|
|
27
|
+
| `lotics app api publish` / `unpublish`, `lotics run set_app_api` | `lotics run set_app '{"app_id":"…","api_published":true}'` / `false` |
|
|
27
28
|
| `lotics field rename` | `lotics run set_tables` with a merge patch of the table's document |
|
|
28
29
|
| `lotics app kit` | nothing: a custom-code app depends on `@lotics/app-sdk` (below) |
|
|
29
30
|
| `@lotics/xlsx` / `@lotics/docx` to build a template's file | any `.xlsx` / `.docx` library, then `lotics upload` (`lotics docs document_templates`) |
|
package/docs/permissions.md
CHANGED
|
@@ -16,9 +16,11 @@ owner. Everything starts private, and sharing is the only way to widen it. `set_
|
|
|
16
16
|
whole organization a role on a resource (`working_in_a_workspace`). Several shares add up, the highest role wins, and
|
|
17
17
|
there is no deny.
|
|
18
18
|
|
|
19
|
+
**Lists are shorter than reach.** A listing shows your own work and what is shared with you. An admin's listing says what it left out (`not_listed`), and `all: true` on `get_workspace` lists it: apps, knowledge docs and templates. An admin's agent lists every table, automation and connection without it. A doc search covers what is listed, so a member's private doc enters an admin's answers only with `all: true`. By id, an admin reaches anything. Sharing an item with yourself through `set_access` lists it from then on.
|
|
20
|
+
|
|
19
21
|
| Role | Reaches |
|
|
20
22
|
|---|---|
|
|
21
|
-
| Organization owner, admin | Every resource
|
|
23
|
+
| Organization owner, admin | Every resource |
|
|
22
24
|
| Member | What they own and what is shared with them |
|
|
23
25
|
|
|
24
26
|
## Two doors to data
|
|
@@ -49,15 +51,15 @@ and a person who owns the target or an admin can share it with them as viewer.
|
|
|
49
51
|
|
|
50
52
|
A workflow, app, automation and notification workflow uses its owner's current permissions. Pressing a button, answering
|
|
51
53
|
a card or filling a form only triggers it. If the owner loses access, the run fails. Only the owner or an admin writes a
|
|
52
|
-
body
|
|
54
|
+
body, and that includes a notification workflow and naming it on a card; it still runs as its owner.
|
|
53
55
|
|
|
54
|
-
Saving a body needs
|
|
55
|
-
names. To inspect what a member would get, an admin passes `as_member` with a read or a dry run.
|
|
56
|
+
Saving a body needs its owner to be able to use every connection, template and knowledge doc it names. To inspect what a member would get, an admin passes `as_member` with a read or a dry run.
|
|
56
57
|
|
|
57
58
|
## Connections
|
|
58
59
|
|
|
59
60
|
A connection belongs to the company. Only an admin connects one, in Lotics under Settings → Connections. Admins and
|
|
60
|
-
whoever it is shared with can act through it, and it passes to an admin when its owner leaves.
|
|
61
|
+
whoever it is shared with can act through it, and it passes to an admin when its owner leaves. An app handed from one admin
|
|
62
|
+
to another keeps its shares; any other handover clears them.
|
|
61
63
|
|
|
62
64
|
A workflow step's `connected_account_id` is a literal, a constant bound to one, or a choice among them, so every possible
|
|
63
65
|
value is judged at save; one read from an input, a record or a call is refused at save and at run. A document template
|
package/docs/workflow_steps.md
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
The steps only a workflow body runs: a connection's (an invoice issuer, a mailbox, …) and the platform's own. Each is
|
|
6
6
|
called as `await <step>({ ...inputs })` (see `workflows`); a step's inputs and answer are its entry here. A connection
|
|
7
|
-
step takes the `connected_account_id` that `get_workspace` lists under kind `connection`, and the app's owner
|
|
8
|
-
|
|
7
|
+
step takes the `connected_account_id` that `get_workspace` lists under kind `connection`, and the app's owner must be
|
|
8
|
+
able to use that connection. A step's `connected_account_id` is a literal, a
|
|
9
9
|
constant bound to one, or a choice among them: every possible value is judged at save, and one read from an input, a
|
|
10
10
|
record or a call is refused. A template may come from data; a run refuses one its owner cannot use.
|
|
11
11
|
|
|
@@ -3251,7 +3251,7 @@ above. A provider's refusal carries the provider's own words.
|
|
|
3251
3251
|
- Notify workspace members.
|
|
3252
3252
|
- Lotics shows it to each recipient and emails it to their own address, through no connection; a member who signs in with an identifier an admin issued has no mailbox and sees it in Lotics alone.
|
|
3253
3253
|
- A member is named by the member_id get_workspace kind member lists. (chat, MCP, CLI)
|
|
3254
|
-
- In a workflow body, every member is { type: "organization", id: runtime.organization_id } and the member who started the run { type: "member", id: runtime.triggered_by_member_id }; a run a schedule, a webhook or an email starts was started by no member. blocks draw under the message: text, stat, chart, fields, link, and record (table_id and record_id; the card shows the record's own title, read as the sender can read it). actions are buttons: each runs workflow_id under its owner's access when pressed, and
|
|
3254
|
+
- In a workflow body, every member is { type: "organization", id: runtime.organization_id } and the member who started the run { type: "member", id: runtime.triggered_by_member_id }; a run a schedule, a webhook or an email starts was started by no member. blocks draw under the message: text, stat, chart, fields, link, and record (table_id and record_id; the card shows the record's own title, read as the sender can read it). actions are buttons: each runs workflow_id under its owner's access when pressed, and its owner or an admin may name it.
|
|
3255
3255
|
- A workflow a card can run declares notification inputs. inputs are the values the sender fixes; asks are the values the presser answers, each ask key an input of the workflow that inputs does not fix; every required input of the workflow is fixed or asked as required. decision is "any" (one decision for all recipients: the first press decides it) or "each" (every recipient decides alone); it is required with actions and refused without.
|
|
3256
3256
|
|
|
3257
3257
|
**Inputs**
|
package/docs/workflows.md
CHANGED
|
@@ -42,7 +42,7 @@ not supply is refused, naming the ones it takes. A rehearsal needs write scope:
|
|
|
42
42
|
a step it drops included. `even_if_invoked` and `acknowledge_breaking_api_change` belong to an app workflow and are
|
|
43
43
|
refused for another kind.
|
|
44
44
|
|
|
45
|
-
A notification workflow is run by the action of a notification card under its owner's access; the press only triggers it. It declares `inputs` as an app workflow does, reads them as `inputs.<name>` (or `trigger.notification_action.inputs.<name>`), cannot `wait` or `wait_for_event`, and is bound to no table, automation, button or app. Its owner or an admin reads and deletes it
|
|
45
|
+
A notification workflow is run by the action of a notification card under its owner's access; the press only triggers it. It declares `inputs` as an app workflow does, reads them as `inputs.<name>` (or `trigger.notification_action.inputs.<name>`), cannot `wait` or `wait_for_event`, and is bound to no table, automation, button or app. Its owner or an admin reads, replaces and deletes it and puts it on a card, and it still runs as its owner; it has one owner for life and is archived with them when they leave (its open cards close), never handed on. Its writes are judged and attributed as its owner. Its runs are read by its owner and admins, and are never retried: pressing the card again is the retry. A step that sends a card names each action's `workflow_id` as a literal. Only a workflow sends a card; an `agent` step writes the title and body it sends.
|
|
46
46
|
|
|
47
47
|
An app workflow reads its call as `trigger.app_workflow.inputs.<name>`, or `inputs.<name>`, which is the same read. A Workflow node receives the inputs it declares;
|
|
48
48
|
an Act's `workflow` receives `record_id` (`record_ids` on an act over several rows) and what the Act asks.
|
|
@@ -91,7 +91,7 @@ A delayed run is never cancelled from a workflow: after a `wait`, it reads the r
|
|
|
91
91
|
A tool's inputs and answer are in its own description; the steps only a body runs — a connection's, a mail's — are each
|
|
92
92
|
an entry of `workflow_steps`. An admin connects a service in Lotics under Settings → Connections; a step names that
|
|
93
93
|
connection by its `connected_account_id`, which `get_workspace` with `kind: "connection"` lists for the connections the
|
|
94
|
-
caller can use. The app's owner
|
|
94
|
+
caller can use. The app's owner must be able to use that connection, so a
|
|
95
95
|
`connected_account_id` is a literal, a constant bound to one, or a choice among them: every possible value is judged at
|
|
96
96
|
save, and one read from an input, a record or a call is refused. A template may come from data; a run refuses one its
|
|
97
97
|
owner cannot use.
|
|
@@ -21,11 +21,11 @@ Find the means in this order: `get_workspace` maps the workspace; `search` it by
|
|
|
21
21
|
|
|
22
22
|
## People
|
|
23
23
|
|
|
24
|
-
`get_workspace` with kind `member` lists every member's name and id; an admin also sees each one's email, role, `managed` and `sign_in_name`, and
|
|
24
|
+
`get_workspace` with kind `member` lists every member's name and id; an admin also sees each one's email, role, `managed` and `sign_in_name`, and, on kind `app`, `knowledge` or `template`, `not_listed`: how many more they can reach, which `all: true` lists. Listed docs and templates carry `access`. An admin also reads the credit limits there.
|
|
25
25
|
|
|
26
26
|
`set_members` is an admin's: `members` is a map keyed by an email address, a member id or a managed member's sign-in name, and `groups` a map keyed by a group id or the name of a group to create. In `members`, an email no member holds invites that person (`role` is `member` or `admin`; the invitation email goes out), a current member's entry sets `name` and `role`, a removed member's entry restores them and takes only `name`, and `null` removes a member or cancels the invitation pending to that address. Sign-in names are compared in lowercase. A person adds a managed member and sets its password in Settings → Members. The organization keeps at least one admin: the last one cannot be demoted or removed. In `groups`, an entry sets `name`, `description` and the roster with `member_ids`, or with `add_member_ids` and `remove_member_ids` that leave the rest in place; a roster entry may be a key of `members`, so a person invited in the same call can join; `null` deletes the group. The whole input is checked before anything is written or sent; members are applied before groups, in the order given, and the caller's own step-down last. A member's tool list does not carry `set_members` or `set_workspace`.
|
|
27
27
|
|
|
28
|
-
`set_access` gives members, groups or the whole organization a role on resources. Role `owner`, on one member, hands every resource listed to that member, whom only the resource's owner or an admin may name; a call cannot share an app and hand it over together, an app handed
|
|
28
|
+
`set_access` gives members, groups or the whole organization a role on resources. Role `owner`, on one member, hands every resource listed to that member, whom only the resource's owner or an admin may name; a call cannot share an app and hand it over together, an app handed to or from a member loses its sharing, and an automation is turned off until its new owner turns it on. Handovers are applied one resource at a time, and a failure part-way names what was already applied. `set_workspace` takes `credit_limits` (`workspace`, `apps` by app id, `members` by member id; a number is the daily ceiling in credits, `null` removes it and asks for approval).
|
|
29
29
|
|
|
30
30
|
## Comments
|
|
31
31
|
|