@lotics/cli 0.197.0 → 0.204.0

package/dist/src/client.d.ts

@@ -80,6 +80,18 @@ export interface WorkspaceInfo {
     organization_id: string;
     created_at: string;
 }
+/**
+ * One hand-written report. Declared here rather than imported: this entry's
+ * published `.d.ts` must resolve for a consumer who has none of this package's
+ * other modules.
+ */
+export interface ReportFrame {
+    goal: string;
+    actual: string;
+    expected?: string;
+    tried?: string;
+    wanted?: string;
+}
 export interface ToolExecuteResult {
     result: unknown;
     model_output?: string;
@@ -340,12 +352,30 @@ export interface ScaffoldWorkspaceResult {
         table_id: string;
         /** False when a table of that label already existed and was adopted. */
         created: boolean;
+        /**
+         * What this run put ON that table — the delta a schema write is confirmed by.
+         * Absent from an instance too old to state it, so the line omits the counts
+         * rather than reporting a run that added nothing.
+         */
+        created_fields?: number;
+        created_options?: number;
+        created_views?: number;
     }>;
+    /**
+     * Every role the model declares. `created` is false when a GROUP of that name
+     * was already here and the role bound to it — which is how a role silently
+     * inherits another workspace's membership, and why the line prints it the way
+     * an entity's does.
+     */
     roles: Array<{
         alias: string;
         group_id: string;
+        created: boolean;
     }>;
-    /** Ids of the rows written, per entity alias — the handle for deleting them again. */
+    /**
+     * Ids of the rows written, per entity alias — the handle for deleting them
+     * again, and what `scaffold apply --documents` joins its rows to.
+     */
     record_ids: Record<string, string[]>;
     /** Rows were sent and none were written, because the run adopted a table. */
     rows_skipped: boolean;
@@ -374,6 +404,12 @@ export interface WorkspaceModelExport {
         area: string;
         message: string;
     }>;
+    /**
+     * Labels of the entities the link closure added — the tables the caller did not
+     * name and a link pulled in. Absent from an instance too old to state it, which
+     * is why the printout says nothing rather than "0 pulled in".
+     */
+    pulled_in?: string[];
 }
 /**
  * A request the API refused. The message carries the status and the server's
@@ -604,24 +640,20 @@ export declare class LoticsClient {
         organization_name: string;
     }>;
     /**
-     * File a hand-written report. Unlike a telemetry flush, the headers this
-     * stamps are CORRECT: the invocation making the request is the one the report
-     * is about, so the courier and the cargo are the same session.
+     * File a hand-written report, or a list of them in one call. Unlike a
+     * telemetry flush, the headers this stamps are CORRECT: the invocation making
+     * the request is the one the report is about, so the courier and the cargo are
+     * the same session.
      */
     sendReport(body: {
-        report: {
-            goal: string;
-            actual: string;
-            expected?: string;
-            tried?: string;
-            wanted?: string;
-        };
+        report: ReportFrame | ReportFrame[];
         cli_session_id: string | null;
         cli_version: string;
         workspace_id?: string;
         app_id?: string;
     }): Promise<{
-        accepted: true;
+        accepted: number;
+        report_ids?: string[];
     }>;
     setWorkspaceId(id: string): void;
     /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
@@ -737,10 +769,19 @@ export declare class LoticsClient {
          * source archive so agent-authored bindings (via `set_app_workflow`)
          * survive the pull/edit/deploy loop. Null/undefined on apps that have
          * never had a workflow declared.
+         *
+         * `table_ids` is the set of tables the bound BODY touches, recorded when the
+         * body was verified. It is what makes a table an app only ever WRITES to
+         * addressable: codegen covers every table a query reads, and a workflow
+         * writing a table no screen reads had no `F`/`OPT` entry, so its body
+         * carried pasted `fld_`/`opt_` literals that a rename breaks silently
+         * instead of failing `tsc`. Absent on a binding written before the server
+         * recorded it — the set widens what codegen covers, it does not define it.
          */
         workflows?: Record<string, {
             workflow_id: string;
             inputs?: Record<string, unknown>;
+            table_ids?: string[];
         }> | null;
         /**
          * Live alias → query declaration map from `apps.queries`. Source of truth
@@ -777,6 +818,10 @@ export declare class LoticsClient {
         name: string;
         description?: string;
         icon?: string;
+        /** The launcher tile's colour — the app's own, carried from whatever declared it. */
+        theme?: {
+            color?: string;
+        };
     }): Promise<{
         id: string;
         name: string;
@@ -1010,6 +1055,43 @@ export declare class LoticsClient {
     }): Promise<StarterPublish>;
     /** The state of a publish: which app is building, and the version once every dist is in. */
     getStarterPublish(publish_id: string): Promise<StarterPublish>;
+    /**
+     * The ROW RULE each of these tables declares — `private_filters` as stored, or
+     * `null` where the table has none.
+     *
+     * `GET /v1/tables/{id}` rather than the `get_table` tool beside it: the rule is
+     * an IAM fact about who may read a row, and the tool's output is the schema an
+     * agent writes records against, which is why it carries fields and not this.
+     * One call per id. A table this credential may not read — 403, or 404 for one
+     * that is gone — is DROPPED: the only caller warns about rules it can see, and
+     * a table it cannot read is not evidence of one. EVERY other failure throws.
+     * An expired key, a 500, a timeout and an offline host all mean the scan has
+     * no answer, and swallowing them would render as "this table declares no
+     * rule" — the guard at its quietest exactly where it knows least.
+     *
+     * The filter is carried untyped: a published `.d.ts` cannot name
+     * `@lotics/shared`'s filter schema, and the one reader asks a single question
+     * of the tree rather than interpreting it.
+     */
+    getTableRowRules(tableIds: string[]): Promise<Array<{
+        id: string;
+        name: string;
+        private_filters: unknown;
+    }>>;
+    /**
+     * The organization's member groups — the directory `lotics app codegen` turns
+     * into the `GRP` alias map.
+     *
+     * Over the HTTP route rather than `query_member_groups`, because the tool is
+     * admin-only and the route is member-visible by design (`docs/iam.md` § Groups:
+     * reading the directory is not administration). Codegen runs for every author,
+     * so an admin-only read here would leave a non-admin's `GRP` empty and their
+     * app unbuildable.
+     */
+    getMemberGroups(): Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
     /**
      * Resolve the display name + fields (incl. select options) of the given tables
      * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`

package/dist/src/client.js

@@ -323,9 +323,10 @@ var LoticsClient = class {
     return this.request("GET", "/v1/cli/whoami");
   }
   /**
-   * File a hand-written report. Unlike a telemetry flush, the headers this
-   * stamps are CORRECT: the invocation making the request is the one the report
-   * is about, so the courier and the cargo are the same session.
+   * File a hand-written report, or a list of them in one call. Unlike a
+   * telemetry flush, the headers this stamps are CORRECT: the invocation making
+   * the request is the one the report is about, so the courier and the cargo are
+   * the same session.
    */
   async sendReport(body) {
     return this.request("POST", "/v1/cli/report", body);
@@ -613,6 +614,59 @@ var LoticsClient = class {
   async getStarterPublish(publish_id) {
     return this.request("GET", `/v1/starters/publishes/${encodeURIComponent(publish_id)}`);
   }
+  /**
+   * The ROW RULE each of these tables declares — `private_filters` as stored, or
+   * `null` where the table has none.
+   *
+   * `GET /v1/tables/{id}` rather than the `get_table` tool beside it: the rule is
+   * an IAM fact about who may read a row, and the tool's output is the schema an
+   * agent writes records against, which is why it carries fields and not this.
+   * One call per id. A table this credential may not read — 403, or 404 for one
+   * that is gone — is DROPPED: the only caller warns about rules it can see, and
+   * a table it cannot read is not evidence of one. EVERY other failure throws.
+   * An expired key, a 500, a timeout and an offline host all mean the scan has
+   * no answer, and swallowing them would render as "this table declares no
+   * rule" — the guard at its quietest exactly where it knows least.
+   *
+   * The filter is carried untyped: a published `.d.ts` cannot name
+   * `@lotics/shared`'s filter schema, and the one reader asks a single question
+   * of the tree rather than interpreting it.
+   */
+  async getTableRowRules(tableIds) {
+    const tables = await Promise.all(
+      tableIds.map(async (table_id) => {
+        try {
+          const table = await this.request(
+            "GET",
+            `/v1/tables/${encodeURIComponent(table_id)}`
+          );
+          return { id: table.id, name: table.name, private_filters: table.private_filters ?? null };
+        } catch (error) {
+          const notVisible = error instanceof LoticsRequestError && (error.status === 403 || error.status === 404);
+          if (!notVisible) throw error;
+          return null;
+        }
+      })
+    );
+    return tables.filter((table) => table !== null);
+  }
+  /**
+   * The organization's member groups — the directory `lotics app codegen` turns
+   * into the `GRP` alias map.
+   *
+   * Over the HTTP route rather than `query_member_groups`, because the tool is
+   * admin-only and the route is member-visible by design (`docs/iam.md` § Groups:
+   * reading the directory is not administration). Codegen runs for every author,
+   * so an admin-only read here would leave a non-admin's `GRP` empty and their
+   * app unbuildable.
+   */
+  async getMemberGroups() {
+    const { groups } = await this.request(
+      "GET",
+      "/v1/iam/member_groups"
+    );
+    return groups.map((group) => ({ id: group.id, name: group.name }));
+  }
   /**
    * Resolve the display name + fields (incl. select options) of the given tables
    * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`

package/docs/building_an_app.md

@@ -22,7 +22,10 @@ cd <dir> && lotics app pull <app_id>   # existing: refresh to the latest first,
 each screen as the registry shape over the live table its entity became — a `LifecycleDesk`, a
 `PartyRegister`, … from `@lotics/ui`, its slots reading the fields the plan bound. The tables
 have to exist (`lotics scaffold apply` first); a table or field the workspace lacks is refused by
-name. A `custom` screen arrives as its rows and the slot list, for you to compose.
+name. A `custom` screen arrives as a register of the cells its roles name, cut to what still reads
+at a phone's width — its slot list is a checklist of what the rows know, never a layout. The
+project's `README.md` is the plan in prose: the app, its screens with their routes and shapes, and
+the tables behind them.
 
 A pull writes more than source: one `src/workflows/<alias>.ts` per bound workflow, one
 `src/agents/<alias>.md` per bound agent, and the `.lotics/` type companions — so an existing app
@@ -96,18 +99,22 @@ lotics app codegen        # no deploy, no version bump
 ```
 
 Regenerates `.lotics/`: the three `.d.ts` companions that type `useQuery` / `useWorkflow` /
-`useAgentRun`, and — when credentials resolve — `app_fields.ts`, exporting `F` (table → field →
-`"fld_…"`) and `OPT` (table → select field → option → `"opt_…"`) keyed by display-name aliases.
+`useAgentRun`, and — when credentials resolve — `app_fields.ts`, exporting four maps keyed by
+display-name aliases: `F` (table → field → `"fld_…"`), `OPT` (table → select field → option →
+`"opt_…"`), `TBL` (table → `"tbl_…"`) and `GRP` (member group → `"grp_…"`).
 
-Address fields by alias, never by a pasted id:
+Address every id by alias, never by a pasted one — a table id and a member group included:
 
 ```tsx
 row.opt(r[F.SHIPMENT.direction]) === OPT.SHIPMENT.direction.export
+useCommentCounts({ table_id: TBL.SHIPMENT });
+useMembers({ group: GRP.sale });
 ```
 
-A rename in the platform then moves your call sites when you re-run `codegen`, and a stale alias
-fails `tsc` instead of failing at runtime. **Re-run after any schema change** — local typecheck is
-only honest if the generated ids are current, and you never deploy to refresh types.
+An alias is slugified from the display name, so a rename on the platform MOVES it: re-run `codegen`
+and every call site on the old alias fails `tsc` until it names the new one. **Re-run after any
+schema change** — local typecheck is only honest if the generated ids are current, and you never
+deploy to refresh types.
 
 ## 5 — Named queries
 
@@ -115,6 +122,11 @@ Author them as `kind: "project"` with a `filter`. A bare `from_table` over-expos
 degrades at scale. Scope per-user reads with `is_current_member` **inside the template** — a
 `member_id` passed from the client is an IDOR, since the caller chooses it.
 
+Name each projected column — `{ "source": "fld_…", "output": "total" }` — and the row is then read
+as `r.total`, with no field map on the read path; `lotics app create --from` emits exactly that.
+Write one `description` per alias too: it is the line a chat or MCP caller chooses between them by,
+and `lotics app check` exits 1 naming any alias that has none.
+
 Decode cells with the `row.*` helpers (`row.text`, `row.opt`, `readSelect`, `readLinks`), never by
 reaching into the raw shape: a select cell is `[{key,label}]`, and a hand-rolled reader silently
 returns the wrong half.
@@ -129,6 +141,22 @@ Details: `lotics docs queries`.
 
 ## 6 — Workflows, the only way an app writes
 
+**A workflow binding is SOURCE, and it deploys with the app.** Its two halves are
+`package.json#lotics.workflows.<alias>` and `src/workflows/<alias>.ts`; `lotics app pull` writes
+both, and `lotics app deploy` pushes whatever differs from what it last saw live — through
+`set_app_workflow`, before the bundle ships, so a version that shipped always reproduces what runs.
+Nothing is bound by hand after a deploy, and nothing needs to be: an alias whose body and
+declaration are in the repo is an alias the next clone can build. Three consequences worth knowing
+before you write one:
+
+- **A push refuses when the live body moved past the copy you edited.** The baseline rides as a
+  precondition, so two people editing one alias is a refusal naming it, never a silent clobber.
+- **An unchanged alias is not pushed.** An update is a diff, so a deploy that changes one screen
+  does not re-push nine workflows.
+- **Deleting the declaration and the file does not unbind it.** The binding keeps serving, and
+  keeps being published to chat and to MCP. `lotics app deploy --prune` unbinds what the project no
+  longer names, and it is opt-in because an alias can be invoked from outside the bundle.
+
 A workflow body is a file you open and edit. The new-alias path is typed from the first line:
 
 1. Declare it in `package.json#lotics.workflows.<alias>` — its `inputs`, and `outputs` only to
@@ -149,7 +177,9 @@ writes the schema back into the manifest and refreshes that alias's types in pla
 The alias's `description` rides along from the manifest. It is the one line an agent reads when
 choosing between your workflows, so write it rather than leaving the generated placeholder — and
 keep it inside 300 characters, the cap a push holds both a workflow's and a query's `description`
-to, because both ride the capability catalog into the agent's prompt on every run.
+to, because both ride the capability catalog into the agent's prompt on every run. `app check`
+names every alias over it and exits 1, and `workflow set` / `query set` refuse before sending
+anything, so a long line costs one edit rather than a failed push per alias.
 
 **Every workflow you declare is also the chat agent's write surface.** So the alias's *shape* is an
 agent-facing decision, not only a screen-facing one — take a list where one job covers many
@@ -266,17 +296,21 @@ actually carries, not what the source says it should.
 
 ```
 npm run typecheck && npm run lint && npm test
-lotics app check --screens           # every pre-flight a deploy runs, without building or shipping,
+lotics app check --screens --shots shots/
+                                     # every pre-flight a deploy runs, without building or shipping,
                                      # plus the portability gate a library publish applies, plus
-                                     # every screen rendered at 1280 and 375 and measured
+                                     # every screen rendered at 1280 and 375, measured, and written
+                                     # to shots/ as a PNG per screen and per record it opened
 lotics app deploy -m "<what changed + why>"
 ```
 
 **A green suite says nothing about how the screen LOOKS**, and that half starts with
 `--screens`: it renders the app over its real data (Chrome needed), walks every tab at both
 widths, and refuses what a review would; what it measures is in `lotics docs cli_reference`. What
-it cannot measure is in `lotics docs reviewing` — render it, look at it, then measure what the look
-is telling you. Both before the deploy, not as an audit someone schedules after a complaint.
+it cannot measure is in `lotics docs reviewing` — which is why `--shots <dir>` is on the same
+line: it photographs the frame each probe read, so LOOKING at the app is the same run rather than
+a dev server and a browser pass per screen. Open the 375 shots first. Both before the deploy, not
+as an audit someone schedules after a complaint.
 
 Every check above reads the SOURCE; none of them renders it. So the entire class of defect that
 lives in the pixels — wrong form for the subject, a treatment that contradicts what an element
@@ -316,7 +350,7 @@ lotics app codegen                   # after any schema change
 npm run typecheck                    # honest, because codegen is current
 lotics run run_app_workflow '{"app_id":…,"alias":…}'   # prove the mutation path
 lotics app dev                       # prove the screen
-lotics app check --screens           # measure it, before anyone looks
+lotics app check --screens --shots shots/   # measure it AND photograph it, before anyone looks
 …
 lotics app workflow set <alias>      # push the body; the server verifies
 lotics app deploy -m "…"             # pushes pending bindings, then ships