@lotics/cli 0.190.0 → 0.191.1

package/AGENTS.md

@@ -7,7 +7,7 @@ conventions are, and where the traps are.
 |---|---|
 | `lotics --help` | The verb inventory (§ COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |
 | `lotics tools` · `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |
-| `lotics docs` · `lotics docs <area>` | Every reference the packages installed beside the project actually ship — `@lotics/app-sdk`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. |
+| `lotics docs` · `lotics docs <area>[/<section>]` | Every reference the packages installed beside the project actually ship — `@lotics/app-sdk`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. |
 | `lotics scaffold docs` | How to write a `model.json` — the file a workspace is built from. Two forms: `{"from": "<preset-slug>", "variants", "rename", "entities", "rows", "apply"}`, which names a preset by slug and carries only what this business differs by, and the full one, spelled out, for when no preset is the trade: every top-level key, every field type with the config it needs, the row format, the rules, and a worked example. Offline, and not part of `lotics docs`. It also covers the `apply` list — published packages copied in after the model's own tables, each with an optional `bind` onto them — and the `preset` block a published model carries. `lotics scaffold check` then proves the file — offline, except for the one read a `from` file's preset needs — including every branch of a preset merged onto its base; `lotics setup` applies it and refuses a table name the workspace already has, `lotics scaffold apply` adopts that table and adds what is missing. `lotics scaffold export` goes the other way — a workspace printed as one of these files, to edit into another business's model; a starting point, never a source of truth. |
 | [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — scaffold, model, types, queries, workflows, screens, ship — and the deploy-free inner loop. The other references describe contracts; this one is the order they go in and why. Read it once before starting an app. |
 | [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas — the detail `--help` compresses. Read it before hand-building a `set_app_*` payload: several tools REPLACE rather than patch, and a CLI verb already owns the safe assembly. |

package/README.md

@@ -15,6 +15,8 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
 **`lotics docs`** lists every reference the packages installed beside your project ship — each
 `@lotics/*` package carries its own, so a doc always describes the version you actually have.
 `lotics docs <area>` prints one (`lotics docs ai`); `lotics docs ui` prints a package's index.
+Every answer is capped at a page, so a long doc hands back its section list and
+`lotics docs <area>/<section>` — or, for a doc that is one table, `lotics docs ui/catalog/Button`.
 Nothing is copied here — the packages, the areas, the titles and the versions are all read at run
 time, so a doc or a whole package added upstream shows up without upgrading this CLI.
 

package/dist/probe_page.js

@@ -0,0 +1,421 @@
+"use strict";
+var __loticsProbe = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/probe_page.ts
+  var probe_page_exports = {};
+  __export(probe_page_exports, {
+    pressTab: () => pressTab,
+    run: () => run,
+    tabs: () => tabs,
+    textLeafCount: () => textLeafCount
+  });
+
+  // src/probe_collectors.ts
+  function moneyColumns() {
+    const money = /^[-+−]?\s?(?:(?:[$€]|USD|EUR|VND)\s?[\d.,]+\s?(?:[KMB]|tr|tỷ)?|[\d.,]+\s?(?:tr|tỷ)?\s?(?:₫|đ|VND|USD|EUR|[$€]))$/i;
+    const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
+    const bandGap = 48;
+    const leaves = [];
+    const walk = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const text = (node.textContent || "").trim();
+        const parent = node.parentElement;
+        if (!text || !parent || skipTag.test(parent.tagName)) return;
+        if (typeof parent.checkVisibility === "function" && !parent.checkVisibility()) return;
+        if (!money.test(text)) return;
+        const range = document.createRange();
+        range.selectNodeContents(node);
+        let rect = range.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) rect = parent.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return;
+        leaves.push({
+          text,
+          left: Math.round(rect.left),
+          right: Math.round(rect.right),
+          top: Math.round(rect.top),
+          bottom: Math.round(rect.bottom)
+        });
+        return;
+      }
+      node.childNodes.forEach(walk);
+    };
+    walk(document.body);
+    const bands = [];
+    for (const leaf of [...leaves].sort((a, b) => a.top - b.top)) {
+      const band = bands[bands.length - 1];
+      if (band !== void 0 && leaf.top - band.bottom <= bandGap) {
+        band.items.push(leaf);
+        band.bottom = Math.max(band.bottom, leaf.bottom);
+      } else {
+        bands.push({ bottom: leaf.bottom, items: [leaf] });
+      }
+    }
+    const columns = [];
+    for (const band of bands) {
+      const clusters = [];
+      for (const leaf of [...band.items].sort((a, b) => a.left - b.left)) {
+        const cluster = clusters[clusters.length - 1];
+        if (cluster !== void 0 && leaf.left < cluster.right) {
+          cluster.items.push(leaf);
+          cluster.right = Math.max(cluster.right, leaf.right);
+        } else {
+          clusters.push({ left: leaf.left, right: leaf.right, items: [leaf] });
+        }
+      }
+      for (const cluster of clusters) {
+        const firstByEdge = /* @__PURE__ */ new Map();
+        for (const item of cluster.items) if (!firstByEdge.has(item.right)) firstByEdge.set(item.right, item.text);
+        const edges = [...firstByEdge.entries()].sort((a, b) => a[0] - b[0]);
+        columns.push({
+          x: cluster.left,
+          size: cluster.items.length,
+          edges: edges.map(([edge]) => edge),
+          samples: edges.map(([, text]) => text)
+        });
+      }
+    }
+    return { total: leaves.length, columns };
+  }
+  function reportedValues() {
+    const numeric = /^[-+−]?\d[\d.,]*\s?(?:%|[A-Za-z₫đ$€]{1,4})?$/;
+    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';
+    const pictureMin = 32;
+    const samples = [];
+    let bare = 0;
+    const walk = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const text = (node.textContent || "").trim();
+        const parent = node.parentElement;
+        if (!text || !parent || skipTag.test(parent.tagName)) return;
+        if (typeof parent.checkVisibility === "function" && !parent.checkVisibility()) return;
+        if (!numeric.test(text) || dateLike.test(text)) return;
+        if (parent.closest(notAValue)) return;
+        bare += 1;
+        if (samples.length < 6) samples.push(text);
+        return;
+      }
+      node.childNodes.forEach(walk);
+    };
+    walk(document.body);
+    const drawn = Array.from(document.querySelectorAll('[role="meter"], [role="progressbar"], canvas')).filter((el) => {
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    });
+    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, samples };
+  }
+  function internalIds() {
+    const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
+    const id = /\b(?:opt|fld|tbl|rec|wfl|mbr|app|wsp)_[A-Za-z0-9]{6,}\b/g;
+    const ids = /* @__PURE__ */ new Set();
+    let total = 0;
+    const walk = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const parent = node.parentElement;
+        if (!parent || skipTag.test(parent.tagName)) return;
+        const text = node.textContent || "";
+        if (!text.trim()) return;
+        total += 1;
+        for (const match of text.match(id) ?? []) ids.add(match);
+        return;
+      }
+      node.childNodes.forEach(walk);
+    };
+    walk(document.body);
+    return { total, ids: [...ids] };
+  }
+  function tabStrips() {
+    const strips = Array.from(document.querySelectorAll('[role="tablist"]')).filter((el) => {
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    }).map((el) => Array.from(el.querySelectorAll('[role="tab"]')).map((tab) => (tab.textContent || "").trim()));
+    return { total: strips.length, strips };
+  }
+  function truncatedLeaves() {
+    const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
+    const cut = [];
+    let total = 0;
+    for (const el of Array.from(document.querySelectorAll("*"))) {
+      if (skipTag.test(el.tagName) || el.children.length > 0) continue;
+      const text = (el.textContent || "").trim();
+      if (!text) continue;
+      if (typeof el.checkVisibility === "function" && !el.checkVisibility()) continue;
+      total += 1;
+      if (getComputedStyle(el).overflow === "visible") 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) {
+        cut.push({ text: text.slice(0, 40), axis: "height", has: el.clientHeight, needs: el.scrollHeight });
+      }
+    }
+    return { total, cut };
+  }
+  function bannedGlyphs() {
+    const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
+    const found = [];
+    let total = 0;
+    const walk = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const parent = node.parentElement;
+        if (!parent || skipTag.test(parent.tagName)) return;
+        const text = node.textContent || "";
+        if (!text.trim()) return;
+        total += 1;
+        if (text.includes(" \xB7 ")) found.push(text.trim().slice(0, 40));
+        return;
+      }
+      node.childNodes.forEach(walk);
+    };
+    walk(document.body);
+    return { total, found };
+  }
+  function compactMoneyWords() {
+    const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
+    const any = /\d[\d.,]*\s?(?:[KMB](?![a-z])|tr(?![a-z])|tỷ)/i;
+    const dongInEnglishWords = /\d[\d.,]*\s?[KMB]\s?(?:₫|đ|VND)|(?:₫|VND)\s?\d[\d.,]*\s?[KMB](?![a-z])/i;
+    const dollarInVietnameseWords = /[$€]\s?\d[\d.,]*\s?(?:tr(?![a-z])|tỷ)|\d[\d.,]*\s?(?:tr|tỷ)\s?(?:[$€]|USD|EUR)(?![a-z])/i;
+    const foreign = [];
+    let total = 0;
+    const walk = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const parent = node.parentElement;
+        if (!parent || skipTag.test(parent.tagName)) return;
+        const text = (node.textContent || "").trim();
+        if (!text) return;
+        if (any.test(text)) total += 1;
+        if (dongInEnglishWords.test(text) || dollarInVietnameseWords.test(text)) foreign.push(text.slice(0, 40));
+        return;
+      }
+      node.childNodes.forEach(walk);
+    };
+    walk(document.body);
+    return { total, foreign };
+  }
+  function scanStackedPairs() {
+    const px = (el) => parseFloat(getComputedStyle(el).fontSize);
+    const weight = (el) => parseInt(getComputedStyle(el).fontWeight, 10) || 400;
+    const isLeaf = (el) => el.children.length === 0 && (el.textContent || "").trim().length > 0;
+    const leafOf = (el, depth = 3) => {
+      if (isLeaf(el)) return el;
+      if (depth === 0 || el.children.length === 0) return null;
+      return leafOf(el.children[0], depth - 1);
+    };
+    let total = 0;
+    const overDemoted = [];
+    for (const el of Array.from(document.querySelectorAll("div"))) {
+      const kids = Array.from(el.children);
+      if (kids.length !== 2) continue;
+      const [first, second] = kids;
+      const subject = leafOf(first);
+      const supporting = leafOf(second);
+      if (!subject || !supporting) continue;
+      if (first.closest('[role="banner"]')) continue;
+      const a = first.getBoundingClientRect();
+      const b = second.getBoundingClientRect();
+      if (b.top < a.bottom - 2) continue;
+      if (a.height === 0 || b.height === 0) continue;
+      total += 1;
+      if (px(supporting) < px(subject) && weight(subject) > weight(supporting)) {
+        overDemoted.push({
+          subject: (subject.textContent || "").trim().slice(0, 60),
+          supporting: (supporting.textContent || "").trim().slice(0, 60),
+          sizes: [px(subject), px(supporting)],
+          weights: [weight(subject), weight(supporting)]
+        });
+      }
+    }
+    return { total, overDemoted };
+  }
+  function scanRowMarks() {
+    const marks = [];
+    const seen = [];
+    const record = (el, text) => {
+      if (seen.some((other) => other.contains(el) || el.contains(other))) return;
+      seen.push(el);
+      const r = el.getBoundingClientRect();
+      marks.push({ text, w: Math.round(r.width), y: Math.round(r.y), x: Math.round(r.x) });
+    };
+    const inContent = (el) => el.closest('[role="banner"]') === null;
+    for (const el of Array.from(document.querySelectorAll('[data-mark="identity"]'))) {
+      const r = el.getBoundingClientRect();
+      if (r.height === 0 || !inContent(el)) continue;
+      record(el, (el.textContent || "").trim() || "\u25A3");
+    }
+    const initials = /^\p{L}{1,2}$/u;
+    const grounded = (el, depth = 2) => {
+      const cs = getComputedStyle(el);
+      if (cs.backgroundColor !== "rgba(0, 0, 0, 0)" || cs.backgroundImage !== "none") return true;
+      if (depth === 0) return false;
+      return Array.from(el.children).some((child) => grounded(child, depth - 1));
+    };
+    for (const el of Array.from(document.querySelectorAll("*"))) {
+      const r = el.getBoundingClientRect();
+      if (r.width < 12 || r.width > 56) continue;
+      if (Math.abs(r.width - r.height) > 1) continue;
+      const cs = getComputedStyle(el);
+      if ((parseFloat(cs.borderTopLeftRadius) || 0) < 3) continue;
+      const text = (el.textContent || "").trim();
+      if (!initials.test(text)) continue;
+      if (!inContent(el)) continue;
+      if (!grounded(el)) continue;
+      record(el, text);
+    }
+    const byRow = /* @__PURE__ */ new Map();
+    for (const m of marks) {
+      const band = Math.round(m.y / 20) * 20;
+      const list = byRow.get(band);
+      if (list) list.push(m);
+      else byRow.set(band, [m]);
+    }
+    const mismatches = [];
+    for (const [band, row] of byRow) {
+      const widths = new Set(row.map((m) => m.w));
+      if (widths.size <= 1) continue;
+      mismatches.push({ y: band, marks: row.sort((a, b) => a.x - b.x).map((m) => `${m.text}:${m.w}px`) });
+    }
+    return { total: marks.length, mismatches };
+  }
+
+  // src/probe_page.ts
+  var MONEY_EDGES_ALLOWED = 2;
+  var MONEY_COLUMN_MIN = 3;
+  var BARE_VALUES_FLOOR = 8;
+  function run(options) {
+    const findings = [];
+    const money = moneyColumns();
+    const ragged = money.columns.filter((column) => column.size >= MONEY_COLUMN_MIN && column.edges.length > MONEY_EDGES_ALLOWED);
+    if (ragged.length > 0) {
+      findings.push({
+        probe: "money_edges",
+        total: money.total,
+        count: ragged.length,
+        detail: ragged.slice(0, 5).map((column) => `x=${column.x}: ${column.edges.length} right edges over ${column.size} figures \u2014 ${column.samples.join(" | ")}`)
+      });
+    }
+    const values = reportedValues();
+    if (values.bare >= BARE_VALUES_FLOOR && values.encoded === 0) {
+      findings.push({
+        probe: "reported_values",
+        total: values.total,
+        count: values.bare,
+        detail: [`${values.bare} values as bare text, 0 as a mark, meter, chart or picture \u2014 e.g. ${values.samples.join(", ")}`]
+      });
+    }
+    const ids = internalIds();
+    if (ids.ids.length > 0) {
+      findings.push({ probe: "internal_ids", total: ids.total, count: ids.ids.length, detail: ids.ids.slice(0, 5) });
+    }
+    const strips = tabStrips();
+    if (strips.total > 1) {
+      findings.push({
+        probe: "tab_strips",
+        total: strips.total,
+        count: strips.total,
+        detail: strips.strips.map((strip) => strip.join(" / "))
+      });
+    }
+    if (options.truncation) {
+      const cut = truncatedLeaves();
+      if (cut.cut.length > 0) {
+        findings.push({
+          probe: "truncation",
+          total: cut.total,
+          count: cut.cut.length,
+          detail: cut.cut.slice(0, 5).map((leaf) => `"${leaf.text}" needs ${leaf.needs}px of ${leaf.axis} in ${leaf.has}px`)
+        });
+      }
+    }
+    const glyphs = bannedGlyphs();
+    if (glyphs.found.length > 0) {
+      findings.push({ probe: "banned_glyph", total: glyphs.total, count: glyphs.found.length, detail: glyphs.found.slice(0, 5) });
+    }
+    const compact = compactMoneyWords();
+    if (compact.foreign.length > 0) {
+      findings.push({
+        probe: "compact_money_words",
+        total: compact.total,
+        count: compact.foreign.length,
+        detail: compact.foreign.slice(0, 5).map((text) => `"${text}" abbreviates in the other currency's words`)
+      });
+    }
+    const pairs = scanStackedPairs();
+    if (pairs.overDemoted.length > 0) {
+      findings.push({
+        probe: "stacked_pairs",
+        total: pairs.total,
+        count: pairs.overDemoted.length,
+        detail: pairs.overDemoted.slice(0, 5).map((pair) => `"${pair.subject}" ${pair.sizes[0]}px/${pair.weights[0]} over "${pair.supporting}" ${pair.sizes[1]}px/${pair.weights[1]}`)
+      });
+    }
+    const marks = scanRowMarks();
+    if (marks.mismatches.length > 0) {
+      findings.push({
+        probe: "row_marks",
+        total: marks.total,
+        count: marks.mismatches.length,
+        detail: marks.mismatches.slice(0, 5).map((row) => `y=${row.y}: ${row.marks.join(", ")}`)
+      });
+    }
+    return {
+      findings,
+      census: {
+        leaves: textLeafCount(),
+        money: money.total,
+        bare: values.bare,
+        encoded: values.encoded,
+        strips: strips.total
+      }
+    };
+  }
+  function textLeafCount() {
+    const skipTag = /^(SCRIPT|STYLE|TITLE|META|LINK|NOSCRIPT|TEMPLATE)$/;
+    let count = 0;
+    const walk = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const parent = node.parentElement;
+        if (parent && !skipTag.test(parent.tagName) && (node.textContent || "").trim()) count += 1;
+        return;
+      }
+      node.childNodes.forEach(walk);
+    };
+    walk(document.body);
+    return count;
+  }
+  function tabs() {
+    const strip = document.querySelector('[role="tablist"]');
+    if (strip === null) return [];
+    return Array.from(strip.querySelectorAll('[role="tab"]')).map((tab) => (tab.textContent || "").trim());
+  }
+  function pressTab(index) {
+    const strip = document.querySelector('[role="tablist"]');
+    const tab = strip?.querySelectorAll('[role="tab"]')[index];
+    if (!(tab instanceof HTMLElement)) return false;
+    tab.click();
+    return true;
+  }
+  return __toCommonJS(probe_page_exports);
+})();