@lotics/cli 0.321.95 → 0.321.97

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.
@@ -223,6 +223,15 @@ export declare class NoAnswerError extends Error {
223
223
  * because the clock covers the body too.
224
224
  */
225
225
  export declare function fetchStorage<T>(url: string, timeoutMs: number | undefined, read: (response: Response) => Promise<T>): Promise<T>;
226
+ /**
227
+ * Saves the body of an object-storage signed URL to a file as it arrives, never holding it whole: the one way a link
228
+ * becomes a file. `fileFor` reads the response's status and headers and names the absolute `file` to write (with
229
+ * whatever else its caller answers), creating nothing; its directory is created here. Held to `timeoutMs` as
230
+ * `fetchStorage` holds a read, body included.
231
+ */
232
+ export declare function saveStorageLink<T extends {
233
+ file: string;
234
+ }>(url: string, timeoutMs: number | undefined, fileFor: (response: Response) => Promise<T>): Promise<T>;
226
235
  /**
227
236
  * The website: where a person goes when the CLI cannot finish the job. Held
228
237
  * beside the API base and overridable for the same reason — a run against a
@@ -78,7 +78,7 @@ function telemetryErrorMessage(status, parsed) {
78
78
 
79
79
  // ../shared/src/cli_capabilities.ts
80
80
  var CLI_CAPABILITIES_HEADER = "x-lotics-cli-capabilities";
81
- var CLI_CAPABILITIES = ["docs-fallback", "answer-file"];
81
+ var CLI_CAPABILITIES = ["docs-fallback", "answer-file", "answer-link"];
82
82
 
83
83
  // ../shared/src/proxy_upload_limit.ts
84
84
  var PROXY_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
@@ -87,6 +87,8 @@ var PROXY_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
87
87
  import crypto from "node:crypto";
88
88
  import fs from "node:fs";
89
89
  import path from "node:path";
90
+ import { Readable } from "node:stream";
91
+ import { pipeline } from "node:stream/promises";
90
92
 
91
93
  // src/invocation.ts
92
94
  var invocation = null;
@@ -193,6 +195,22 @@ async function fetchStorage(url, timeoutMs, read) {
193
195
  throw error;
194
196
  }
195
197
  }
198
+ async function saveStorageLink(url, timeoutMs, fileFor) {
199
+ return fetchStorage(url, timeoutMs, async (response) => {
200
+ const target = await fileFor(response);
201
+ await fs.promises.mkdir(path.dirname(target.file), { recursive: true });
202
+ const body = response.body === null ? Readable.from([]) : Readable.fromWeb(response.body);
203
+ const partial = `${target.file}.${crypto.randomUUID()}.part`;
204
+ try {
205
+ await pipeline(body, fs.createWriteStream(partial));
206
+ } catch (error) {
207
+ await fs.promises.rm(partial, { force: true });
208
+ throw error;
209
+ }
210
+ await fs.promises.rename(partial, target.file);
211
+ return target;
212
+ });
213
+ }
196
214
  var NEVER_SENT_CODES = /* @__PURE__ */ new Set([
197
215
  "ENOTFOUND",
198
216
  "ECONNREFUSED",
@@ -551,14 +569,11 @@ var LoticsClient = class {
551
569
  return this.requestForm("POST", `/v1/apps/${encodeURIComponent(args.app_id)}/versions`, formData);
552
570
  }
553
571
  async downloadFile(url, outputPath) {
554
- const buffer = await fetchStorage(url, this.timeoutMs, async (response) => {
572
+ const { file } = await saveStorageLink(url, this.timeoutMs, async (response) => {
555
573
  if (!response.ok) throw new Error(`${response.status}: Failed to download file`);
556
- return Buffer.from(await response.arrayBuffer());
574
+ return { file: path.resolve(outputPath) };
557
575
  });
558
- const absolutePath = path.resolve(outputPath);
559
- await fs.promises.mkdir(path.dirname(absolutePath), { recursive: true });
560
- await fs.promises.writeFile(absolutePath, buffer);
561
- return absolutePath;
576
+ return file;
562
577
  }
563
578
  /**
564
579
  * One page of this workspace's stored files, newest first — `GET /v1/files`.
@@ -577,20 +592,17 @@ var LoticsClient = class {
577
592
  }
578
593
  async downloadFileById(fileId, destination, options) {
579
594
  const { url } = await this.request("GET", `/v1/files/${encodeURIComponent(fileId)}/signed_url`);
580
- const { disposition, buffer } = await fetchStorage(url, this.timeoutMs, async (response) => {
595
+ const saved = await saveStorageLink(url, this.timeoutMs, async (response) => {
581
596
  if (!response.ok) await this.throwResponseError(response);
582
- return { disposition: response.headers.get("content-disposition") ?? "", buffer: Buffer.from(await response.arrayBuffer()) };
597
+ const originalFilename = parseContentDispositionFilename(response.headers.get("content-disposition") ?? "") ?? fileId;
598
+ const { dir, named } = destination === void 0 ? { dir: process.cwd() } : "file" in destination ? {
599
+ dir: path.dirname(path.resolve(destination.file)),
600
+ named: path.basename(destination.file)
601
+ } : { dir: path.resolve(destination.dir) };
602
+ const filename = named ?? findAvailableFilename(dir, originalFilename, options?.reserved);
603
+ return { file: path.join(dir, filename), filename, stored_filename: originalFilename };
583
604
  });
584
- const originalFilename = parseContentDispositionFilename(disposition) ?? fileId;
585
- const { dir, named } = destination === void 0 ? { dir: process.cwd() } : "file" in destination ? {
586
- dir: path.dirname(path.resolve(destination.file)),
587
- named: path.basename(destination.file)
588
- } : { dir: path.resolve(destination.dir) };
589
- await fs.promises.mkdir(dir, { recursive: true });
590
- const filename = named ?? findAvailableFilename(dir, originalFilename, options?.reserved);
591
- const absolutePath = path.join(dir, filename);
592
- await fs.promises.writeFile(absolutePath, buffer);
593
- return { path: absolutePath, filename, stored_filename: originalFilename };
605
+ return { path: saved.file, filename: saved.filename, stored_filename: saved.stored_filename };
594
606
  }
595
607
  async downloadRecordFiles(recordId, fieldAlias, outputDir) {
596
608
  const result = await this.execute("query_records", { record_ids: [recordId] }, { format: "text" });
@@ -767,5 +779,6 @@ export {
767
779
  fetchStorage,
768
780
  findAvailableFilename,
769
781
  pollCliLogin,
782
+ saveStorageLink,
770
783
  startCliLogin
771
784
  };
@@ -46,8 +46,6 @@ app has.
46
46
  | `<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a List stating `same`; `record_<field>` per `where` bound to a field of the record | each Reading of a Record page, each List that only reads on it (its `key`, else its entity's alias) and each funnel, called by its `key` |
47
47
  | `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading's | a Reading whose value `records.limits` bounds: the bound's sum, beside the Reading's own |
48
48
  | `<reading>_on_hand` | <label> / <on-hand entity>: how many <on-hand entity> rows there are, per "<field>". Each row carries `<field>`, `__count`. | none: every row of its entity its `where` keeps, whatever the place | a Reading with `on_hand` (a shortfall): the on-hand rows' groups, beside the Reading's own |
49
- | `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | an Export of the register that fills a template |
50
- | `<entity>_export_rows_of_<source>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | an Export over some of a List's sources: their rows alone, each source named in turn |
51
49
  | `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |
52
50
  | `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads — the rows with no <place> counted apart. | | a register laid out as a `plan`: its places' counts of present rows |
53
51
 
@@ -140,19 +138,16 @@ read over; a tab's totals take the folder's id too, in an app that works inside
140
138
  ## Exporting a file
141
139
 
142
140
  ```
143
- run_app_query {"app_id":"app_…","export":{"key":"by_carrier","per":"…","tab":"in_yard","status":["…"]}}
141
+ run_app_query {"app_id":"app_…","export":{"list":"by_carrier","tab":"in_yard","status":["…"]}}
144
142
  ```
145
143
 
146
- `export` makes the file the register's Export button makes, from what the caller reads, and answers it under `files` as a workspace
147
- file like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `key` is the
148
- key of an Export of a List in `get_app`'s tree, at the root or below a row's page; it is sent without `alias` or any other argument of a
149
- read. An option is named by its name or its id, as a read's filters name it; a member by its id or its name, for a member
150
- of the app's organization; a row, by its id. The other keys
144
+ `export` makes a List that states `export: true` as a workbook, as the register's Export button does, from what the caller reads, and answers it under `files` as a workspace
145
+ file like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `list` is the View id of that List: its `key` at the root, `<page entity>.<key>` below a row's page (the row page's table, a dot, the List's `key`); it is sent without `alias` or any other argument of a
146
+ read. An option is named by its name or its id, as a read's filters name it; a member by its id; a row, by its id. The other keys
151
147
  narrow the file as the register's own controls do, each absent one leaving the register's opening view:
152
148
 
153
149
  | Key | Takes |
154
150
  |---|---|
155
- | `per` | The option, row id or member id the report is made for — required by an Export that states `per`, refused by one that does not; a member, here and in a member chip, is an id or a name, found as a filter on a member column finds one |
156
151
  | `tab`, `period`, `window` | A Tab's key (the first when absent); `{ "from", "to" }` days `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` on a date-and-time field) the tabs read over; a calendar's or board's days |
157
152
  | `status` | Options of the register's status that are kept |
158
153
  | `filters` | `{ "<field>": <value> }` by the field's alias, a value `null` clearing the register's opening chip; a value is one of the shapes below |
@@ -31,7 +31,7 @@ A `Query` node reads one table or List with `rows` or `list`. A wider read state
31
31
 
32
32
  ## Queries
33
33
 
34
- A query declaration is `{ ast, params?, description?, templates? }`:
34
+ A query declaration is `{ ast, params?, description? }`:
35
35
 
36
36
  - `ast` — a query template (a QueryNode, below). It fixes the tables, filters and columns the alias
37
37
  reads, so a caller cannot widen it.
@@ -41,18 +41,16 @@ A query declaration is `{ ast, params?, description?, templates? }`:
41
41
  param left unset drops the conditions that read it; a required param that arrives empty is
42
42
  refused where a filter reads it.
43
43
  - `description` — one line saying what the query returns, for an agent choosing between aliases.
44
- - `templates` — the document templates an export of its rows may fill, by name:
45
- `{ <name>: { template_id: "dtl_…", rows: "<key the template lists the rows under>" } }`.
46
44
 
47
45
  A save checks what a deploy checks: every table is in this workspace and within the owner's reach,
48
46
  every projected, filtered and sorted field resolves, every param token is declared, and a key a
49
47
  node's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.
50
48
 
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
49
+ `set_app` states one as a `Query` node: `{ "type": "Query", "key": "<alias>", "ast": { … } }`, beside `params`
50
+ and `description`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch
51
+ replaces its `ast` or `params` whole. On an app that serves
52
+ code, `nodes` takes `{ "<alias>": { … } }` and merges each: send only the fields you change, `null` clears `params`
53
+ or `description` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its
56
54
  `children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by
57
55
  name, and `get_app`'s `body` reads them back by alias.
58
56
 
@@ -29,9 +29,9 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
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
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
- | — | **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. |
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: {"list", …narrowing}` instead of the read arguments makes the workbook of a List that states `export: true`, `list` its View id (`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
- | `lotics run <tool> '<json>'` with `as_file: true` | An answer that names its own file (`_file`) is saved as that file, whole JSON, where the command runs, or in `-o <dir>`; the path prints after the answer (on stderr under `--json`). The same call names the same file, so running it again replaces it. |
34
+ | `lotics run <tool> '<json>'` with `as_file: true` | An answer that names its own file (`_file`) is saved as that file where the command runs, or in `-o <dir>`: a page's as the whole JSON answer, a whole set's (`query_records` with no page, or `all: true`) downloaded from `_file.url` as it arrives, JSON Lines. The path prints after the answer (on stderr under `--json`). The same call names the same file, so running it again replaces it. |
35
35
  | `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`. |
36
36
  | `lotics run set_members '{"members": {"<email or member id>": {"role": "member", "name": "…"}}}'` | Invite to this workspace (`name` is the name the invitation carries) or set a person's role in it (`role`: `member` or `admin`; `null` takes the person, or the invitation pending to that address, out of it); `groups` keeps the member groups in the same call. An admin of this workspace or an organization owner. Renaming or removing a person, restoring one, co-ownership and a member who signs in by a name are a person's in Settings → Members, and no tool takes them. The whole input is checked before an email is sent. A member's `lotics tools` lists neither `set_members` nor `set_workspace`. View-as is the web app's preview alone; the CLI acts as the signed-in member. |
37
37
  | `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |
package/docs/design.md CHANGED
@@ -129,7 +129,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
129
129
  - `columns` (list of (alias | Edit column)): Fields read after the row's title, each drawn though no row holds it
130
130
  - `label` (text): The register's name in the app's lists and tab strip
131
131
  - `filters` (list of (alias | Tiered filter | Listed filter) (at most 3)): Fields the reader narrows by every day, beside the stage chips, at most 3
132
- - `children` (list of (Tab | Reading | Export | Act | List) (at least one)): Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view
132
+ - `children` (list of (Tab | Reading | Act | List) (at least one)): Its Tabs, band Readings and Acts over ticked rows or every row in view
133
133
  - `key` (alias): Names the List among its siblings and in a Query's `list`
134
134
  - `sort` (Sort key | list of Sort key (at least one)): The rows' order
135
135
  - `layout` (layout): A word, or an object stating one layout with its data
@@ -260,7 +260,7 @@ Whether the build does the owner's work, answered by a call each, never from wha
260
260
  3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.
261
261
  4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?
262
262
  5. Is anything cramped at desk or phone width?
263
- 6. Is every paper and every Export made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove an Export with `run_app_query` and `export`.
263
+ 6. Is every paper and every exporting List's workbook made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove a List's `export: true` with `run_app_query` and `export`.
264
264
  7. Is each thing that must never happen in this business (a step taken before its approval, stock below zero, a double booking) refused on every write? Prove each with a write sent `dry_run: true` that is refused (`workflows/table-checks`).
265
265
 
266
266
  A failed answer is a change to the tree, or a gap named to the owner.
@@ -284,7 +284,7 @@ Each kind of row's view is chosen before its List is written:
284
284
  | Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes, and every row's ⋯ offers Duplicate; a List with `same` where read-only | |
285
285
  | A related row's value on the list (the newest contract's end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |
286
286
  | Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | |
287
- | Counted over a period | the register's Tabs over one `period`; a Tab's `totals` for a child's sums before, during and through it; an open Tab's `where` reads only what was true at the period's end, never a status the row moves on from | |
287
+ | Counted over a period | the register's Tabs over one `period`; a Tab's `totals` for a child's sums before, during and through it; an open Tab reads only what was true at the period's end, never a status the row moves on from | |
288
288
  | Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | |
289
289
  | A plan of spans | List `layout: {"gantt": {"start": …}}` | `reference/gantt` |
290
290
  | Stood at a place on a plan, flat or in 3D — pallets, bins | List `layout: {"plan": …}`; places state `plan_place` | `reference/plan` |
@@ -377,7 +377,7 @@ register's outline is. A child List on a record with this layout draws the bars
377
377
  `layout: "roster"` with a List inside it over the child whose rows fill the days — one link back to the
378
378
  register's table and a date on its line: what each row did on each day (shifts, runs, attendance). With
379
379
  `expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.
380
- An `Export` with an html or Excel `template` prints the grid as the screen reads it (`document_templates/a-template`). Worked: `examples/roster`.
380
+ Worked: `examples/roster`.
381
381
 
382
382
  #### Weekly pattern
383
383
 
@@ -87,6 +87,9 @@ this host, give the person the file and a `person` drop link.
87
87
  (skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass
88
88
  raw numbers, ISO dates and booleans at generate time; the cell's number format shows them. A cell's format also decides
89
89
  what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).
90
+ A date cell reads a day or a moment written with no zone (`2026-09-30T08:15`) as that clock, and a moment written with
91
+ one (a workflow's `now()`, `2026-09-30T08:15:00+07:00`) on the workspace's clock; `format`, `add_days` and a
92
+ comparison read it the same way.
90
93
  - **`word`** — a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,
91
94
  `{{FOR … IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added
92
95
  (`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run
@@ -103,7 +106,7 @@ Every type supports three shapes of substitution. The exact syntax differs per e
103
106
  the `set_template` description for the reference; here is the capability:
104
107
 
105
108
  - **Scalar** — a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in
106
- Excel preserve their type via the cell's number format.
109
+ Excel preserve their type via the cell's number format, and an Excel cell whose template prints nothing (empty text, only spaces, or no value) is left blank.
107
110
  - **Repeating rows / line items** — one template row rendered once per item in a list, for
108
111
  invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style
109
112
  `{{#each items}}…{{/each}}`; Word uses `{{FOR item IN items}}…{{$item.field}}…{{END-FOR item}}`. The HTML and email types
@@ -210,7 +213,7 @@ siblings in the List's order, with its depth as `level` (1 for the rows filed un
210
213
  A paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the
211
214
  titles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is
212
215
  refused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no
213
- column — a grid of rows by days is a roster's Export (below). A Word template is read for this when it is next saved.
216
+ column. A Word template is read for this when it is next saved.
214
217
 
215
218
  A paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one file of them all: the rows arrive under the entity's alias. An html paper hands each row the child rows the record's paper would be handed, under the same names, with their `_totals`; an Excel or Word paper is handed the rows alone. The page the rows open draws those Lists:
216
219
 
@@ -218,26 +221,9 @@ A paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one
218
221
  {{#each supplier_order}}<h2>{{code}}</h2>{{#each sources}}<p>{{description}} × {{quantity}}</p>{{/each}}{{/each}}
219
222
  ```
220
223
 
221
- A paper over many rows (a client's month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act's `template`; or a List `Export` with `template` and `per` (`reference/export-node`).
224
+ A paper over many rows (a client's month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act's `template`. A report that reads rows of its own choosing and fills a template is an Act that runs a Workflow calling `generate_document` (`reference/act-node`, `reference/workflow-node`, `workflows/steps`); the Workflow hands the file back to whoever pressed the Act.
222
225
  `reference/groups-and-templates` has the rest.
223
226
 
224
- A roster's `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days
225
- holding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List's entity alias, `student` here)
226
- `cells`, a word per column — each of its rows' mark, the option's `short` else its label (a row with no state, its title), joined by `, ` —
227
- `counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row's figure, else the count of the cells it holds):
228
-
229
- ```html
230
- <tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>
231
- {{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}
232
- ```
233
-
234
- | | A | B | C | D | E |
235
- |---|---|---|---|---|---|
236
- | 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |
237
- | 2 | `{{#each student}}` | | | | |
238
- | 3 | `{{name}}` | | `{{cells \| lookup:@index}}` | | `{{counts.absent}}` |
239
- | 4 | `{{/each}}` | | | | |
240
-
241
227
  ## Discovering and managing templates
242
228
 
243
229
  These tools work across all five types:
package/docs/examples.md CHANGED
@@ -567,14 +567,9 @@ each section says which its record takes under **Its stages**, so the form is co
567
567
  "create": ["ho_ten", "chuyen_mon", "dien_thoai"],
568
568
  "children": [
569
569
  {"type": "List", "entity": "lich_truc", "create": true, "remove": true},
570
- {"type": "Act", "key": "tao_ca_truc_ds", "label": "Tạo ca trực", "on": "view", "makes": "lich_truc"},
571
- {
572
- "type": "Export",
573
- "key": "lich_truc_thang",
574
- "label": "Lịch trực tháng",
575
- "template": "lich_truc_thang"
576
- }
577
- ]
570
+ {"type": "Act", "key": "tao_ca_truc_ds", "label": "Tạo ca trực", "on": "view", "makes": "lich_truc"}
571
+ ],
572
+ "export": true
578
573
  }
579
574
  ],
580
575
  "pages": [
@@ -688,10 +683,8 @@ each section says which its record takes under **Its stages**, so the form is co
688
683
  "filters": ["on_hand"],
689
684
  "search": ["name", "sku"],
690
685
  "layout": "cards",
691
- "children": [
692
- {"type": "Reading", "key": "register_reading_0", "value": "on_hand", "by": "category"},
693
- {"type": "Export", "key": "export"}
694
- ]
686
+ "children": [{"type": "Reading", "key": "register_reading_0", "value": "on_hand", "by": "category"}],
687
+ "export": true
695
688
  }
696
689
  ],
697
690
  "pages": [
@@ -1290,7 +1283,6 @@ each section says which its record takes under **Its stages**, so the form is co
1290
1283
  "over": "ngay_nhan_giay_to"
1291
1284
  },
1292
1285
  {"type": "Reading", "key": "register_reading_2", "by": "doi_tuong"},
1293
- {"type": "Export", "key": "export"},
1294
1286
  {
1295
1287
  "type": "Act",
1296
1288
  "key": "in_danh_sach",
@@ -1298,7 +1290,8 @@ each section says which its record takes under **Its stages**, so the form is co
1298
1290
  "on": "view",
1299
1291
  "template": "danh_sach_nop"
1300
1292
  }
1301
- ]
1293
+ ],
1294
+ "export": true
1302
1295
  },
1303
1296
  {
1304
1297
  "type": "List",
package/docs/workflows.md CHANGED
@@ -123,6 +123,10 @@ id; any other `//` comment there becomes the step's description.
123
123
 
124
124
  A run reads a repeated identical record read once, until the run writes; a loop that waits for a row to change needs a `wait` step, or each pass sees the same rows.
125
125
 
126
+ A `query_records` with no `limit` returns the first 50 rows, and `has_more` says whether there are more. `all: true` returns every row the call matches, up to 32 MiB of them; a call past that is refused, with no rows. `all` does not combine with `limit`, `offset`, `page_size`, `pagination`, `record_ids`, `aggregate`, `tables` or `comments`, and a workflow's read takes no `as_file`.
127
+
128
+ `sort` of a records read also takes `__created_at` and `__updated_at`, a row's creation and last-update time (`{ field_key: "__created_at", order: "desc" }` is newest-created first); with `include_timestamps: true` each row carries `created_at` and `updated_at`, read as `r.created_at`.
129
+
126
130
  **`await` inside a statement** runs the call as its own step first, then reads its output where it is
127
131
  written: `size((await query_records({...})).records)`, an `if` test, a `return` value, a `for-of`
128
132
  iterable, a tool input. `const x = c ? await t({...}) : null;` is stored as the `if` it means. An
@@ -192,12 +196,20 @@ A body names a table or document template by its alias (`query_records({ table_i
192
196
  6. **`option("<field>", "<option>")` names an option where no select is beside it** (a name set once and compared later,
193
197
  a list of options, a value handed to a tool). It reads as the option, typed as that select's, and is stored as its alias. The field is a select or a formula that states `options`.
194
198
  The field is looked up among the tables the body reaches; a field or option that does not exist is refused naming both, and
195
- a field alias that two tables state with different keys for that option is refused naming each table. An option
196
- key written out reads as its alias, but write `option()`: a key is a value no one can read.
197
- 7. **Text renders labels.** Inside a template or a text tool input, a select, member or link value renders its display
199
+ a field alias that two tables state with different keys for that option is refused naming each table, as is one printed
200
+ (rule 7) where the tables label that option differently. An option
201
+ key written out reads as its alias, but write `option()`: a key is a value no one can read. `options("<field>")` lists
202
+ the field's options in its order, each `{ alias, label }`, found and refused as `option()`'s field is
203
+ (`options("status").map((o) => o.label)`); it is read when the run reads it, so a reorder or a relabel shows at once.
204
+ 7. **Text renders labels.** Inside a template, `text(...)` or a text tool input, a select, member or link value renders its display
198
205
  text: `` `${record["status"]}` `` writes "Done", not `done`, and `` `${record["status"] ?? ""}` `` writes it too. A
199
- formula stating `options` (a computed category) is read as the single select it is drawn as: compared by option,
200
- rendered by label.
206
+ card's action inputs and the option keys its ask offer take the alias, a field's value included. `option("status", "done")`
207
+ and a select input read as `inputs.stage` print a label only in a template, `text(...)` or a document's data: the label
208
+ its field, or the workflow's declared input, states when the run prints it; a multi-select's labels print as a field's
209
+ do. Handed to any other tool input, compared, written or filtered on, each is the option's alias: `title: inputs.stage`
210
+ is the alias, `` title: `Stage ${inputs.stage}` `` prints the label. A name bound to the value (`const s = inputs.stage`,
211
+ `const o = option("status", "done")`, `const v = record.status`) prints the value. A formula stating `options` (a computed category) is read as the single select it is drawn as:
212
+ compared by option, rendered by label.
201
213
 
202
214
  ## What an expression reads
203
215
 
@@ -359,6 +371,7 @@ The same work can be written with the helpers below, which are additions to Java
359
371
  `addMonths` (a day past the target month's end lands on its last day), `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,
360
372
  `isSameDay`, `isToday`, `isWithinRange`, `datesOn(from, until, days)` (the days from `from` to `until`, both included, falling on weekdays named `mon` to `sun`), `meetsBounds`. A date beside a moment compares by day, so `<=` means
361
373
  through that day; `startOfMonth` and `endOfMonth` of a date answer a day
374
+ - **Options**: `option(field, option)` and `options(field)` (see **Fields and options**)
362
375
  - **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,
363
376
  `randomAlphaNumeric(len)`, `sample(items)` (a random item)
364
377
 
@@ -378,8 +391,8 @@ expression — `(x) => <expr>` — or a block of `const` declarations, `if`/`els
378
391
  ending in `return <expr>;` (`(x) => { … }` or `function (x) { … }`):
379
392
 
380
393
  ```js
381
- const orders = await query_records({ table_id: "orders" });
382
- const customers = await query_records({ table_id: "customers" });
394
+ const orders = await query_records({ table_id: "orders", all: true });
395
+ const customers = await query_records({ table_id: "customers", all: true });
383
396
  const rows = orders.records.map((o) => {
384
397
  const c = find(customers.records, (x) => x.id == o.data.customer[0]);
385
398
  if (c == null) { return null; }
@@ -399,8 +412,8 @@ rows once, then read each group by its key. `groupBy` answers an object of lists
399
412
  is the group a code names, or an empty list:
400
413
 
401
414
  ```
402
- const parties = await query_records({ table_id: "parties" });
403
- const lines = await query_records({ table_id: "sheet_lines" });
415
+ const parties = await query_records({ table_id: "parties", all: true });
416
+ const lines = await query_records({ table_id: "sheet_lines", all: true });
404
417
  const byCode = groupBy(parties.records, (p) => p.data["code"] ?? "");
405
418
  const holders = lines.records.map((line) => ({
406
419
  line: line.id,
@@ -60,7 +60,7 @@ A stored text is changed by `edits`, never sent whole again: `set_workflow` (wit
60
60
 
61
61
  A long text not stored yet rides a file. `set_workflow` takes `source_file_id` in place of `source`, `set_knowledge` takes `content_file_id` in place of `content`, and `set_template` takes `template_file_id` in place of an html or email `template`: write the text where you work, upload it with `upload_file` (`files`), and pass the `file_id` the upload answers.
62
62
 
63
- Many rows come as a file. `query_records` with `as_file: true` sends the page as a JSON file and lists no rows: over MCP an embedded file, on the CLI a file `lotics run` saves where it runs (or in `-o <dir>`) and names. The file is the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias, so code reads every row. Without a `limit` it takes the page maximum of 1,000 rows; `has_more` and `offset` page past it.
63
+ Many rows come as a file. `query_records` with `as_file: true` lists no rows and sends them as a file: over MCP an embedded file (a whole set up to 12 MiB, a link past that), on the CLI a file `lotics run` saves where it runs (or in `-o <dir>`) and names. With `limit`, `offset`, `page_size`, `pagination` or `comments: true`, the file is that page as JSON, the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias. Without them it is every row the call matches, in its order, as JSON Lines: one row a line, each as `records` lists it. That file is also at `_file.url` for an hour, `_file.rows` counts its rows, and `all: true` sends the same file. A call matching no row answers `total: 0` and no file. One organization writes one such file at a time. A set too large to write within about 80 seconds is refused with how many rows were written; narrow it with `filters`, or name fewer fields with `field_keys`.
64
64
 
65
65
  Many rows go back as a file too. `create_records` and `update_records` take `rows_file_id`: a JSON file holding the call's per-row keys, in place of stating them. Everything else stays in the call: `table_id`, `dry_run`, `row_op`, `return_fields`.
66
66
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.321.95",
3
+ "version": "0.321.97",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {