@lotics/cli 0.198.0 → 0.205.0

package/AGENTS.md

@@ -52,6 +52,23 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   code again; once the 15 minutes are up it says to ask again. `lotics setup` falls into the same
   flow by itself when the email it was given already has an account: it stops having created
   nothing, and the SAME command run again carries on.
+- **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile
+  from `auth login` / `auth signup` acts as the person who confirmed it and is theirs — `lotics auth
+  logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that
+  out). A profile from `auth api-key` holds a key an ADMIN issued, which is routinely also on a
+  server and on other machines, so logout only forgets it locally and says so; only an admin revokes
+  it. A profile that states no kind (saved before the field existed) is resolved against the SERVER
+  and revoked only if the answer is a sign-in; a bare `--api-key` / `LOTICS_API_KEY` names no
+  profile to remove at all. Nothing is ever revoked on a guess — between two, the destructive one is
+  wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.
+- **A 401 names its remedy — act on the hint, do not retry.** "This credential expired / was
+  revoked / belongs to a member who is no longer active" carries the one remedy that ends this
+  credential: run `lotics auth login <email>` for a sign-in, or ask the admin who issued it for a
+  new key. A credential minted before that was recorded carries BOTH, because nothing on the row
+  tells them apart — so on a box with no browser, take the second. Only an UNRECOGNIZED key gets
+  the generic "Invalid or disabled API key", and that one is generic on purpose, so re-sending it
+  teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays
+  `unauthorized` for every 401.
 - **Large payloads bypass `ARG_MAX`** — `lotics run <tool> @args.json` or piped stdin. A leading `@` is
   unambiguously a file path (JSON args start with `{`).
 - **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to
@@ -66,6 +83,13 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   so `lotics run … && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on
   findings. An unrecognized status exits 0 — the list is an allowlist of failure, so a status added
   later never turns a working script red — and a parked run (`awaiting_input`) is not a failure.
+- **An app that PUBLISHES an API turns every later manifest write into a release.** `lotics app api
+  publish` snapshots what the app's queries and workflows promise to callers outside it — a
+  customer's own site or server, which nobody here can redeploy. From then on an additive change
+  re-snapshots silently and a breaking one is REFUSED, naming each change;
+  `--acknowledge-breaking-api` (on `app deploy`, `app query set`, `app workflow set`, `app upgrade`)
+  is the answer that carries it out and snapshots the break as a new contract version. An app that
+  publishes nothing is untouched by any of it.
 - **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the
   records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs
   those deletes (records only — never files, integrations or notifications). Neither is a rollback.

package/README.md

@@ -124,6 +124,10 @@ The CLI checks for updates once per day and prints a note on stderr, naming the
 
 ## Authentication
 
+**Two kinds of credential, and which you hold decides what `logout` does.** `auth signup` / `auth login` give this machine a **sign-in** — it acts as you, carries whatever role you have, and is yours to see and revoke at Settings → Security → *Keys and terminals*; it lapses after 90 days of disuse, and each use pushes that out. `auth api-key` saves an **API key** an admin issued: it acts as the member it was created for, often lives on a server and on other people's machines too, and only an admin revokes it. `lotics auth whoami` prints which kind this machine holds — from the saved profile, or from the server when the profile does not say.
+
+When a credential stops working the refusal says which of the three ways it is dead — "This credential was revoked." / "expired." / "belongs to a member who is no longer active in this organization." — and names both remedies, because a credential acts as a person whether it is their own sign-in or a key an admin issued under their membership, and nothing on the row tells the two apart: sign in again with `lotics auth login <email>`, or ask the admin who issued it for a new key. A key the server does not recognize at all gets one generic answer, deliberately: an unrecognized key learns nothing from being refused.
+
 **`lotics auth signup`** — Creates a new Lotics account, organization, workspace, and API key in one step. Sends a magic link email so you can access the web app.
 
 ```bash
@@ -157,7 +161,7 @@ lotics auth api-key                  # interactive prompt
 lotics auth api-key ltk_...          # registers the key's org as a profile (now active)
 ```
 
-Run `lotics auth logout [<name|id>]` to remove a profile (default: the active org), or `lotics auth logout --all` to wipe the store. Inside a pinned directory the bare form removes the **pin**, not a profile — name the org to remove its credential.
+Run `lotics auth logout [<name|id>]` to remove a profile (default: the active org), or `lotics auth logout --all` to wipe the store. Inside a pinned directory the bare form removes the **pin**, not a profile — name the org to remove its credential. A profile saved by `auth login` / `auth signup` is a **sign-in**, and logging out revokes it server-side too. One saved by `auth api-key` is an admin-issued key that other machines may also hold, so it is only removed from this machine and stays active until an admin revokes it under Settings → API keys. A profile saved before the kind was recorded states nothing, so the server is asked and the credential is revoked only if the answer is a sign-in.
 
 ## Organizations
 
@@ -169,7 +173,7 @@ lotics org use acme                 # switch active org by name (or org id)
 lotics org use "Acme Corp"          # names are case-insensitive
 ```
 
-The org **id** is the identity; the name is a label cached when the key was saved. Rename an org in the app and the cached label goes stale — the old name still works, the new one matches nothing — until `lotics auth whoami` refreshes it. A name matching two saved orgs is refused rather than guessed; use the id.
+The org **id** is the identity; the name is the label the key was saved under, and it is yours — renaming the org in the app never moves it, so the scripts scoping by it keep running. `lotics auth whoami` learns the new name and records it beside the label; both resolve, and `lotics org` prints `label (server: name)` while they differ. A name matching two saved orgs is refused rather than guessed; use the id.
 
 ### Working in parallel (worktrees)
 
@@ -195,7 +199,7 @@ Every command that resolves a workspace names its target before it acts — `lot
 
 `LOTICS_WORKSPACE` (or `--workspace <id>` / `-w`) overrides the workspace at any level. For ephemeral or CI use, set `LOTICS_API_KEY` instead of saving anything.
 
-**`LOTICS_ORG` is resolved once, before any command runs.** A value matching no saved credential refuses every verb with one sentence — a read, a write, and a check that needs no credential alike — and the refusal lists the orgs this machine does hold, so it is answerable without another command. It refuses even when a key arrives another way: a variable that scopes the command must not go unread while `LOTICS_API_KEY` sends the write somewhere else. When the variable resolves AND a key is supplied, the key decides the org and the command says so. A server-side rename leaves the cached org name stale, so name an org by its `org_` id when a concurrent session may rename it.
+**`LOTICS_ORG` is resolved once, before any command runs.** A value matching no saved credential refuses every verb with one sentence — a read, a write, and a check that needs no credential alike — and the refusal lists the orgs this machine does hold, so it is answerable without another command. It refuses even when a key arrives another way: a variable that scopes the command must not go unread while `LOTICS_API_KEY` sends the write somewhere else. When the variable resolves AND a key is supplied, the key decides the org and the command says so. An org keeps the name it was saved under: a server-side rename never moves it, the new name resolves as well, and `lotics org` prints both when they differ.
 
 ### Diagnostics
 
@@ -349,6 +353,18 @@ lotics app versions app_...                # ...for any app, without pulling it
 lotics app upgrade                         # the app this directory's manifest names
 lotics app upgrade app_...                 # ...for any app, without pulling it first
 
+# The app's API: what its declared queries and workflows promise to a caller
+# OUTSIDE the app — a customer's own site or server. Publishing snapshots that
+# promise as a numbered contract; from then on a manifest write that would break
+# it is refused and every breaking change is named, unless the write carries
+# --acknowledge-breaking-api (app deploy / app query set / app workflow set /
+# app upgrade). A query that does not name the columns it returns is refused at
+# publish: those field names are the table's, not the app's to promise.
+lotics app api publish                     # snapshot the contract; prints the version + warnings
+lotics app api status                      # is one published, and which version callers hold
+lotics app api spec -o api.openapi.json    # the OpenAPI 3.1 document, for the consumer's generator
+lotics app api unpublish                   # end the promise
+
 # Regenerate .lotics/* WITHOUT a deploy: the .d.ts type companions (always) +
 # the runtime app_fields.ts (when authenticated) — F/OPT maps that address
 # fields + select options by stable display-name aliases instead of opaque ids.

package/dist/probe_page.js

@@ -98,6 +98,8 @@ var __loticsProbe = (() => {
   }
   function reportedValues() {
     const numeric = /^[-+−]?\d[\d.,]*\s?(?:%|[A-Za-z₫đ$€]{1,4})?$/;
+    const counted = /(?:%|[A-Za-z₫đ$€]{1,4})$/;
+    const delta = /^[↑↓→▲▼]\s*[-+−]?\d[\d.,]*\s?%$/;
     const dateLike = /\d[/:-]\d/;
     const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
     const notAValue = 'a, button, [role="tab"], [role="button"], input, th, [role="columnheader"], nav';
@@ -105,6 +107,7 @@ var __loticsProbe = (() => {
     const nameReach = 360;
     const values = [];
     const labels = [];
+    let deltas = 0;
     const walk = (node) => {
       if (node.nodeType === Node.TEXT_NODE) {
         const text = (node.textContent || "").trim();
@@ -113,6 +116,10 @@ var __loticsProbe = (() => {
         if (typeof parent.checkVisibility === "function" && !parent.checkVisibility()) return;
         const rect = parent.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0) return;
+        if (delta.test(text)) {
+          deltas += 1;
+          return;
+        }
         const leaf = { text, left: Math.round(rect.left), right: Math.round(rect.right), top: Math.round(rect.top) };
         if (!numeric.test(text) || dateLike.test(text)) {
           labels.push(leaf);
@@ -138,6 +145,7 @@ var __loticsProbe = (() => {
     }
     const columns = [];
     let bare = 0;
+    let quantities = 0;
     for (const cluster of clusters) {
       const items = [...cluster.items].sort((a, b) => a.top - b.top);
       const ordinal = items.length >= 3 && items.every((item, index) => item.text === String(index + 1));
@@ -145,10 +153,13 @@ var __loticsProbe = (() => {
       const top = items[0];
       const above = labels.filter((label) => label.top < top.top && top.top - label.top <= nameReach && label.left < cluster.right && label.right > cluster.left).sort((a, b) => b.top - a.top)[0];
       const beside = labels.filter((label) => Math.abs(label.top - top.top) <= 8 && label.right <= top.left).sort((a, b) => b.right - a.right)[0];
+      const scaled = items.filter((item) => counted.test(item.text)).length;
       bare += items.length;
+      quantities += scaled;
       columns.push({
         slot: (above ?? beside)?.text.slice(0, 40) ?? "",
         size: items.length,
+        quantities: scaled,
         samples: items.slice(0, 4).map((item) => item.text)
       });
     }
@@ -157,13 +168,37 @@ var __loticsProbe = (() => {
       const r = el.getBoundingClientRect();
       return r.width > 0 && r.height > 0;
     });
+    const reads = (el) => {
+      const role = el.getAttribute("role");
+      if (role !== "meter" && role !== "progressbar") return true;
+      const stated = (name) => {
+        const raw = el.getAttribute(name);
+        return raw === null || raw.trim() === "" ? Number.NaN : Number(raw);
+      };
+      const bound = (name, fallback) => {
+        const value = stated(name);
+        return Number.isFinite(value) ? value : fallback;
+      };
+      const now = stated("aria-valuenow");
+      if (!Number.isFinite(now)) return false;
+      const floor = bound("aria-valuemin", 0);
+      const top = bound("aria-valuemax", 100);
+      return top > floor && now < top;
+    };
     const pictures = Array.from(document.querySelectorAll('[role="img"], svg, img')).filter((el) => {
       if (el.getAttribute("aria-hidden") === "true") return false;
       const r = el.getBoundingClientRect();
       return r.width >= pictureMin && r.height >= pictureMin;
     });
-    const encoded = drawn.length + pictures.length;
-    return { total: bare + encoded, bare, encoded, columns };
+    const encoded = drawn.filter(reads).length + pictures.length + deltas;
+    return {
+      total: bare + encoded,
+      bare,
+      quantities,
+      encoded,
+      devices: drawn.length + pictures.length + deltas,
+      columns
+    };
   }
   function internalIds() {
     const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
@@ -199,6 +234,8 @@ var __loticsProbe = (() => {
   }
   function truncatedLeaves() {
     const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
+    const clippedAway = /^inset\(\s*50%/;
+    const breakable = /[\t\n\v\f\r \u200b\u3000]/;
     const cut = [];
     let total = 0;
     for (const el of Array.from(document.querySelectorAll("*"))) {
@@ -206,8 +243,17 @@ var __loticsProbe = (() => {
       const text = (el.textContent || "").trim();
       if (!text) continue;
       if (typeof el.checkVisibility === "function" && !el.checkVisibility()) continue;
+      const style = getComputedStyle(el);
+      const box = el.getBoundingClientRect();
+      if (box.width <= 1 && box.height <= 1) continue;
+      if (clippedAway.test(style.getPropertyValue("clip-path"))) continue;
       total += 1;
-      if (getComputedStyle(el).overflow === "visible") continue;
+      if (style.overflow === "visible") continue;
+      const states = (property) => {
+        const value = style.getPropertyValue(property);
+        return value !== "" && value !== "none";
+      };
+      if ((states("-webkit-line-clamp") || states("line-clamp")) && breakable.test(text)) continue;
       if (el.scrollWidth > el.clientWidth + 1) {
         cut.push({ text: text.slice(0, 40), axis: "width", has: el.clientWidth, needs: el.scrollWidth });
       } else if (el.scrollHeight > el.clientHeight + 1) {
@@ -266,6 +312,7 @@ var __loticsProbe = (() => {
       if (depth === 0 || el.children.length === 0) return null;
       return leafOf(el.children[0], depth - 1);
     };
+    const sameColumn = 8;
     let total = 0;
     const overDemoted = [];
     for (const el of Array.from(document.querySelectorAll("div"))) {
@@ -279,6 +326,7 @@ var __loticsProbe = (() => {
       const a = first.getBoundingClientRect();
       const b = second.getBoundingClientRect();
       if (b.top < a.bottom - 2) continue;
+      if (Math.abs(b.left - a.left) > sameColumn) continue;
       if (a.height === 0 || b.height === 0) continue;
       total += 1;
       if (px(supporting) < px(subject) && weight(subject) > weight(supporting)) {
@@ -350,7 +398,7 @@ var __loticsProbe = (() => {
     },
     reported_values: {
       section: "9",
-      fix: "Encode the column the screen is ABOUT \u2014 a mark, a meter, a chart or a picture \u2014 and leave the rest as text."
+      fix: "Encode the column the screen is ABOUT \u2014 a mark, a meter, a chart or a picture \u2014 and leave the rest as text; a meter whose maximum is the bound it alarms at reads the same on every row, so it encodes nothing."
     },
     internal_ids: {
       section: "8",
@@ -362,7 +410,7 @@ var __loticsProbe = (() => {
     },
     truncation: {
       section: "8g",
-      fix: "Shed a trailing column or let the subject take two lines, so the distinguishing half of the name survives."
+      fix: "Shed a trailing column, or widen this one until the value fits \u2014 a date, a code or a figure cut inside itself reads as a different one."
     },
     banned_glyph: {
       section: "10",
@@ -395,6 +443,7 @@ var __loticsProbe = (() => {
   var MONEY_EDGES_ALLOWED = 2;
   var MONEY_COLUMN_MIN = 3;
   var BARE_VALUES_FLOOR = 8;
+  var QUANTITY_COLUMN_MIN = 2;
   function run(options) {
     const findings = [];
     const money = moneyColumns();
@@ -409,14 +458,15 @@ var __loticsProbe = (() => {
       });
     }
     const values = reportedValues();
-    if (values.bare >= BARE_VALUES_FLOOR && values.encoded === 0) {
+    const measurable = values.columns.some((column) => column.quantities >= QUANTITY_COLUMN_MIN) || values.devices > 0;
+    if (values.bare >= BARE_VALUES_FLOOR && values.encoded === 0 && measurable) {
       findings.push({
         probe: "reported_values",
         ...signature("reported_values"),
         total: values.total,
         count: values.bare,
         detail: [
-          `${values.bare} values as bare text, 0 as a mark, meter, chart or picture`,
+          values.devices === 0 ? `${values.bare} values as bare text, nothing drawn as a mark, meter, chart or picture` : `${values.bare} values as bare text; ${values.devices} drawn, none of them reading a value`,
           ...values.columns.slice(0, 5).map((column) => `  ${column.slot === "" ? "(unnamed)" : column.slot}: ${column.size} \u2014 ${column.samples.join(", ")}`)
         ]
       });
@@ -487,7 +537,9 @@ var __loticsProbe = (() => {
         leaves: textLeafCount(),
         money: money.total,
         bare: values.bare,
+        quantities: values.quantities,
         encoded: values.encoded,
+        devices: values.devices,
         strips: strips.counted
       }
     };