@lotics/cli 0.198.0 → 0.205.0

package/dist/src/client.d.ts

@@ -92,10 +92,27 @@ export interface ReportFrame {
     tried?: string;
     wanted?: string;
 }
+/** One promise a refused write would break, as the tool transport states it. */
+export interface ToolBreakingChange {
+    kind: string;
+    alias: string;
+    path: string;
+    rule?: string;
+    message?: string;
+    app_id?: string;
+}
 export interface ToolExecuteResult {
     result: unknown;
     model_output?: string;
     error?: string;
+    /** The refusal's `code` — the same discriminator the HTTP envelope carries,
+     *  and the only part of a failure a caller may branch on. Absent when the
+     *  failure was not a typed error, and from any server older than it. */
+    error_code?: string;
+    /** A refused input addressed per field: one sentence from a typed alias, a
+     *  list from a rejecting table workflow. */
+    field_errors?: Record<string, string> | Record<string, string[]>;
+    breaking_changes?: readonly ToolBreakingChange[];
 }
 /**
  * A settled (or in-flight) app-agent run, the transcript-excluded projection
@@ -352,6 +369,14 @@ 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
@@ -396,6 +421,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
@@ -618,12 +649,28 @@ export declare class LoticsClient {
      */
     private buildHeaders;
     private request;
+    /** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
+    /** `credential_origin` describes the CREDENTIAL this call carried, not the
+     *  member above: `sign_in` for a terminal somebody signed in from, `api_key`
+     *  for one an admin issued. Null for a row minted before it was recorded, and
+     *  absent from an older server — both mean not told. */
     whoami(): Promise<{
         member_id: string;
-        email: string;
+        email: string | null;
         name: string;
+        account_type?: string;
         organization_id: string;
         organization_name: string;
+        credential_origin?: "api_key" | "sign_in" | null;
+    }>;
+    /**
+     * Hand this client's own credential back — what `lotics auth logout` calls
+     * before it forgets the key, so signing out ends the credential instead of
+     * leaving a live one on a server nobody can see it from. Takes no id: the
+     * only thing it can revoke is the key these requests carry.
+     */
+    revokeSelfCredential(): Promise<{
+        id: string;
     }>;
     /**
      * File a hand-written report, or a list of them in one call. Unlike a
@@ -639,6 +686,7 @@ export declare class LoticsClient {
         app_id?: string;
     }): Promise<{
         accepted: number;
+        report_ids?: string[];
     }>;
     setWorkspaceId(id: string): void;
     /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
@@ -937,7 +985,12 @@ export declare class LoticsClient {
      * provenance is a 400, and one already on the latest release a 409 — both
      * refusals, both before any write. Admin-only.
      */
-    upgradeApp(app_id: string): Promise<AppUpgradeResult>;
+    upgradeApp(app_id: string, 
+    /** Apply the new release even though it breaks what this app's published API
+     *  promises, snapshotting the broken contract as a new version. */
+    opts?: {
+        acknowledge_breaking_api_change?: boolean;
+    }): Promise<AppUpgradeResult>;
     /**
      * Capture live records from this workspace as a starter's sample data.
      *
@@ -1063,6 +1116,20 @@ export declare class LoticsClient {
         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`
@@ -1094,6 +1161,40 @@ export declare class LoticsClient {
         public_subdomain: string;
         origin: string;
     }>;
+    /**
+     * Publish the app's API — the owner's promise about what its declared queries
+     * and workflows return to a caller outside the app.
+     *
+     * Snapshots the contract and answers the version it took, plus what the
+     * published surface exposes that the owner may not have intended. A query
+     * that does not name its columns is refused (400) before anything is written:
+     * the app cannot promise field names it never stated.
+     */
+    publishAppApi(app_id: string): Promise<{
+        app_id: string;
+        contract_version: number;
+        published_at: string;
+        warnings: string[];
+    }>;
+    /** End the promise. `unpublished: false` means the app was publishing nothing,
+     *  which this leaves unchanged. The superseded snapshot stays, so a later
+     *  publish continues the numbering rather than reusing a version. */
+    unpublishAppApi(app_id: string): Promise<{
+        app_id: string;
+        unpublished: boolean;
+    }>;
+    /** Whether the app is publishing an API, and which contract version. */
+    getAppApiPublication(app_id: string): Promise<{
+        published: boolean;
+        contract_version: number | null;
+        published_at: string | null;
+    }>;
+    /**
+     * The published API as an OpenAPI 3.1 document — what a consumer's own
+     * generator reads. Rendered from the live SNAPSHOT rather than the manifest,
+     * so it describes what the app has promised; 404 while nothing is published.
+     */
+    getAppOpenApiDocument(app_id: string): Promise<Record<string, unknown>>;
     getAppVersion(app_id: string, version_id: string): Promise<{
         id: string;
         app_id: string;
@@ -1173,6 +1274,9 @@ export declare class LoticsClient {
          *  server refuses it when the live body has moved since, rather than
          *  letting a stale copy overwrite an edit its author never saw. */
         expected_body_sha?: string;
+        /** Carry out this write even though it breaks what the app's published API
+         *  promises, snapshotting the broken contract as a new version. */
+        acknowledge_breaking_api_change?: boolean;
     }): Promise<ToolExecuteResult>;
     /**
      * Bind (create or replace) an app query by alias via the `set_app_query` tool
@@ -1188,7 +1292,10 @@ export declare class LoticsClient {
         description?: string;
     }, 
     /** The fingerprint this edit was based on — makes the write conditional. */
-    expected_sha?: string): Promise<ToolExecuteResult>;
+    expected_sha?: string, 
+    /** Carry out this write even though it breaks what the app's published API
+     *  promises, snapshotting the broken contract as a new version. */
+    acknowledge_breaking_api_change?: boolean): Promise<ToolExecuteResult>;
     /**
      * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
      * — the deploy-free authoring path for `apps.agents`, parallel to
@@ -1366,6 +1473,13 @@ export declare class LoticsClient {
         workflow_aliases?: string[];
         agent_aliases?: string[];
         query_aliases?: string[];
+        /**
+         * Ship this version even though its manifest breaks what the app's published
+         * API promises, snapshotting the broken contract as a new version. A
+         * multipart field is text, so it goes over as the two spellings the server's
+         * own schema admits.
+         */
+        acknowledge_breaking_api_change?: boolean;
     }): Promise<{
         version_id: string;
         version_number: number;

package/dist/src/client.js

@@ -266,10 +266,12 @@ var LoticsClient = class {
       body = {};
     }
     const message = typeof body.message === "string" ? body.message : text;
+    const hint = typeof body.hint === "string" ? `
+  ${body.hint}` : "";
     const trace = requestId === void 0 ? "" : `
 
   Request id: ${requestId} \u2014 quote this to Lotics support.`;
-    throw new LoticsRequestError(`${response.status}: ${message}${trace}`, response.status, body);
+    throw new LoticsRequestError(`${response.status}: ${message}${hint}${trace}`, response.status, body);
   }
   /**
    * The backend's `log()` middleware registers `user-agent`,
@@ -319,9 +321,23 @@ var LoticsClient = class {
     if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
     return response.json();
   }
+  /** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
+  /** `credential_origin` describes the CREDENTIAL this call carried, not the
+   *  member above: `sign_in` for a terminal somebody signed in from, `api_key`
+   *  for one an admin issued. Null for a row minted before it was recorded, and
+   *  absent from an older server — both mean not told. */
   async whoami() {
     return this.request("GET", "/v1/cli/whoami");
   }
+  /**
+   * Hand this client's own credential back — what `lotics auth logout` calls
+   * before it forgets the key, so signing out ends the credential instead of
+   * leaving a live one on a server nobody can see it from. Takes no id: the
+   * only thing it can revoke is the key these requests carry.
+   */
+  async revokeSelfCredential() {
+    return this.request("DELETE", "/v1/api_keys/self");
+  }
   /**
    * 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
@@ -517,8 +533,12 @@ var LoticsClient = class {
    * provenance is a 400, and one already on the latest release a 409 — both
    * refusals, both before any write. Admin-only.
    */
-  async upgradeApp(app_id) {
-    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/upgrade`, {});
+  async upgradeApp(app_id, opts = {}) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/upgrade`,
+      opts.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
+    );
   }
   /**
    * Capture live records from this workspace as a starter's sample data.
@@ -650,6 +670,23 @@ var LoticsClient = class {
     );
     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`
@@ -695,6 +732,36 @@ var LoticsClient = class {
       { public_subdomain }
     );
   }
+  /**
+   * Publish the app's API — the owner's promise about what its declared queries
+   * and workflows return to a caller outside the app.
+   *
+   * Snapshots the contract and answers the version it took, plus what the
+   * published surface exposes that the owner may not have intended. A query
+   * that does not name its columns is refused (400) before anything is written:
+   * the app cannot promise field names it never stated.
+   */
+  async publishAppApi(app_id) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/api/publish`, {});
+  }
+  /** End the promise. `unpublished: false` means the app was publishing nothing,
+   *  which this leaves unchanged. The superseded snapshot stays, so a later
+   *  publish continues the numbering rather than reusing a version. */
+  async unpublishAppApi(app_id) {
+    return this.request("DELETE", `/v1/apps/${encodeURIComponent(app_id)}/api/publish`);
+  }
+  /** Whether the app is publishing an API, and which contract version. */
+  async getAppApiPublication(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/api/publication`);
+  }
+  /**
+   * The published API as an OpenAPI 3.1 document — what a consumer's own
+   * generator reads. Rendered from the live SNAPSHOT rather than the manifest,
+   * so it describes what the app has promised; 404 while nothing is published.
+   */
+  async getAppOpenApiDocument(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/openapi.json`);
+  }
   async getAppVersion(app_id, version_id) {
     return this.request(
       "GET",
@@ -784,7 +851,10 @@ var LoticsClient = class {
       ...body.outputs ? { outputs: body.outputs } : {},
       ...body.name ? { name: body.name } : {},
       ...body.description ? { description: body.description } : {},
-      ...body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {}
+      ...body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {},
+      // Sent only when the caller asked for it: absent means "refuse a break",
+      // which is the answer a caller who said nothing gave.
+      ...body.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
     });
   }
   /**
@@ -795,12 +865,13 @@ var LoticsClient = class {
    * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
    * so the next `lotics app deploy` overwrites this from the manifest.
    */
-  async setAppQuery(app_id, alias, declaration, expected_sha) {
+  async setAppQuery(app_id, alias, declaration, expected_sha, acknowledge_breaking_api_change) {
     return this.execute("set_app_query", {
       app_id,
       alias,
       declaration,
-      ...expected_sha ? { expected_sha } : {}
+      ...expected_sha ? { expected_sha } : {},
+      ...acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
     });
   }
   /**
@@ -1003,16 +1074,12 @@ var LoticsClient = class {
     formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
     formData.append("agent_aliases", JSON.stringify(args.agent_aliases ?? []));
     formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
+    if (args.acknowledge_breaking_api_change) {
+      formData.append("acknowledge_breaking_api_change", "true");
+    }
     const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
     const headers = this.buildHeaders();
     const response = await fetch(url, { method: "POST", headers, body: formData });
-    if (response.status === 409) {
-      const conflict = await response.json();
-      const err = new Error(conflict.message ?? "Deploy conflict \u2014 pull required");
-      err.code = "VERSION_CONFLICT";
-      err.current_version_id = conflict.current_version_id ?? null;
-      throw err;
-    }
     if (!response.ok) {
       await this.throwResponseError(response, headers["x-request-id"]);
     }

package/docs/building_an_app.md

@@ -99,13 +99,16 @@ 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 });
 ```
 
 An alias is slugified from the display name, so a rename on the platform MOVES it: re-run `codegen`
@@ -119,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.
@@ -169,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
@@ -286,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
@@ -336,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