@lotics/cli 0.196.0 → 0.198.0

package/dist/src/client.d.ts

@@ -19,6 +19,34 @@ export interface AppQueryFilterGroup {
 }
 /** Runtime filter/sort the app query RPC applies AFTER the named query, bounded to its output columns. */
 export type AppQueryFilter = AppQueryFilterCondition | AppQueryFilterGroup;
+/**
+ * Body of the app query RPC — the one wire shape every transport carries, so
+ * the dev bridge forwards it whole rather than naming fields that then drift
+ * from what the deployed SDK sends.
+ */
+export interface AppQueryBody {
+    alias: string;
+    params?: Record<string, unknown>;
+    limit?: number;
+    offset?: number;
+    sort?: AppQuerySortKey[];
+    filter?: AppQueryFilter;
+    /** Return only `total` over the filtered set — no rows. */
+    count?: boolean;
+    /** Opt into keyset (seek) pagination, which answers with `next_cursor`. */
+    keyset?: boolean;
+    /** The previous page's `next_cursor`, in keyset mode. */
+    cursor?: string;
+}
+/** Result of the app query RPC. `total` answers a `count` read; `truncated` and
+ *  `next_cursor` a rows read — `next_cursor` in keyset mode only, null on the
+ *  last page. */
+export interface AppQueryResult {
+    rows: unknown[];
+    total?: number;
+    truncated?: boolean;
+    next_cursor?: string | null;
+}
 /**
  * Where a download's bytes go: the FILE to write, or the DIRECTORY to write the
  * stored name into. Stated by the caller, never inferred from the path's shape —
@@ -52,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;
@@ -313,11 +353,21 @@ export interface ScaffoldWorkspaceResult {
         /** False when a table of that label already existed and was adopted. */
         created: boolean;
     }>;
+    /**
+     * 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;
@@ -576,24 +626,19 @@ 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;
     }>;
     setWorkspaceId(id: string): void;
     /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
@@ -602,6 +647,7 @@ export declare class LoticsClient {
     createWorkspace(body: {
         name: string;
         timezone?: string;
+        default_currency?: string;
     }): Promise<WorkspaceInfo>;
     /**
      * Apply a workspace MODEL to the current workspace — the from-scratch half of
@@ -708,10 +754,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
@@ -748,6 +803,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;
@@ -981,6 +1040,29 @@ 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;
+    }>>;
     /**
      * 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`
@@ -1042,18 +1124,7 @@ export declare class LoticsClient {
      * Run a named query declared in the app's manifest, scoped to the app's IAM
      * principal. Mirrors POST /v1/apps/{app_id}/query.
      */
-    appQuery(app_id: string, body: {
-        alias: string;
-        params?: Record<string, unknown>;
-        limit?: number;
-        offset?: number;
-        sort?: AppQuerySortKey[];
-        filter?: AppQueryFilter;
-        count?: boolean;
-    }): Promise<{
-        rows: unknown[];
-        total?: number;
-    }>;
+    appQuery(app_id: string, body: AppQueryBody): Promise<AppQueryResult>;
     appMembers(app_id: string, group_id?: string): Promise<{
         members: Array<{
             id: string;
@@ -1142,6 +1213,13 @@ export declare class LoticsClient {
      * `lotics app pull`, which writes it to `src/workflows/<alias>.ts`.
      */
     getAppWorkflow(app_id: string, alias: string): Promise<ToolExecuteResult>;
+    /**
+     * The app's capability catalog exactly as a chat or MCP caller reads it —
+     * every query, workflow and agent alias the caller's scope reaches, with the
+     * description each is chosen BY. One read for the whole app, so a check over
+     * what those readers see costs one request rather than one per alias.
+     */
+    getAppCapabilities(app_id: string): Promise<ToolExecuteResult>;
     /**
      * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
      * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
@@ -1294,6 +1372,27 @@ export declare class LoticsClient {
         bundle_size_bytes: number;
     }>;
     downloadFile(url: string, outputPath: string): Promise<string>;
+    /**
+     * One page of this workspace's stored files, newest first — `GET /v1/files`.
+     *
+     * The only enumeration there is: every other file surface takes an id, so
+     * without this "what is in the store" is answerable from Postgres alone, which
+     * is exactly the escape hatch a CLI-first workflow exists to remove. Paged by a
+     * keyset cursor the server mints; a caller walks until `next_cursor` is null.
+     */
+    listFiles(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        files: Array<{
+            id: string;
+            filename: string;
+            mime_type: string;
+            size?: number | null;
+            created_at: string;
+        }>;
+        next_cursor: string | null;
+    }>;
     downloadFileById(fileId: string, destination?: DownloadDestination, options?: {
         reserved?: Set<string>;
     }): Promise<{

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,42 @@ 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);
+  }
   /**
    * 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`
@@ -790,6 +827,15 @@ var LoticsClient = class {
   async getAppWorkflow(app_id, alias) {
     return this.execute("get_app_workflow", { app_id, alias });
   }
+  /**
+   * The app's capability catalog exactly as a chat or MCP caller reads it —
+   * every query, workflow and agent alias the caller's scope reaches, with the
+   * description each is chosen BY. One read for the whole app, so a check over
+   * what those readers see costs one request rather than one per alias.
+   */
+  async getAppCapabilities(app_id) {
+    return this.execute("get_app_capabilities", { app_id });
+  }
   /**
    * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
    * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
@@ -983,6 +1029,21 @@ var LoticsClient = class {
     await fs.promises.writeFile(absolutePath, buffer);
     return absolutePath;
   }
+  /**
+   * One page of this workspace's stored files, newest first — `GET /v1/files`.
+   *
+   * The only enumeration there is: every other file surface takes an id, so
+   * without this "what is in the store" is answerable from Postgres alone, which
+   * is exactly the escape hatch a CLI-first workflow exists to remove. Paged by a
+   * keyset cursor the server mints; a caller walks until `next_cursor` is null.
+   */
+  async listFiles(opts) {
+    const params = new URLSearchParams();
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.cursor !== void 0) params.set("cursor", opts.cursor);
+    const query = params.toString();
+    return this.request("GET", `/v1/files${query ? `?${query}` : ""}`);
+  }
   async downloadFileById(fileId, destination, options) {
     const signedHeaders = this.buildHeaders();
     const signedUrlRes = await fetch(

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
@@ -105,9 +108,10 @@ Address fields by alias, never by a pasted id:
 row.opt(r[F.SHIPMENT.direction]) === OPT.SHIPMENT.direction.export
 ```
 
-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
 
@@ -129,6 +133,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
@@ -232,6 +252,12 @@ Vite plus an RPC-forwarding server, in a sandboxed iframe matching production, w
 auth and HMR. File flows work too — the dev server relays the bytes, so upload, preview and
 download are all exercisable locally.
 
+**Navigate with `waitUntil: "domcontentloaded"`.** A dev app never goes network-quiet — the Vite
+client and the app's own cross-origin frame each keep a connection open — so a driver that opts
+into `networkidle` waits out its timeout on an app that rendered fine, and the timeout reads as the
+app being broken. Any in-app path opens directly (`http://localhost:<port>/lo/rec_…`); the wrapper
+serves every path that is not one of its own `/_…` routes.
+
 **Drive it with a browser, in this order** — each step's failure means something different:
 
 1. **Does it render at all?** A blank iframe is almost always a bundling problem, not your code.