@datarails-ai/dr-appspace-cli 0.10.15 → 0.10.16

package/dist/cli.js

@@ -13,7 +13,7 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-appspace-cli",
-  version: "0.10.15",
+  version: "0.10.16",
   description: "Datarails App Space CLI \u2014 build, try, push and publish App Space apps",
   type: "module",
   engines: {
@@ -57,7 +57,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-01T09:50:31.199Z";
+var BUILD_TIME = "2026-10-01T09:59:27.370Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -10131,6 +10131,9 @@ var contract_schema_default = {
               where: { type: "object" },
               order_by: { type: "string" },
               limit: { type: "integer" },
+              order: { enum: ["source", "declared"], description: "OPTIONAL, shape breakdown only (this schema has no conditional keyword, so the shape rule is the compiler's: source_shape refuses order on a breakdown source outside this enum). The order the items are answered in: declared is the labels listed in items, over any read; source keeps the rows' own order, which holds only where something promises one: a transform, or an app-table read that states order_by. Absent, the items are sorted by size. A waterfall card over a breakdown source needs one, with top: null." },
+              items: { type: "array", items: { type: "string", minLength: 1 }, minItems: 1, description: `OPTIONAL, shape breakdown with order: declared only; on any other shape the compiler refuses it (source_shape). The breakdown's labels, each once, in the order they are drawn (a bridge's steps: ["Opening ARR", "New", ...]). A label the rows do not carry is left out; one they carry and the list does not name follows, in row order.` },
+              top: { type: ["integer", "null"], minimum: 1, description: "OPTIONAL. On a breakdown source (the only shape whose top the compiler holds), how many items are drawn (default 5; the rest is one Other figure, other_value), or null to draw every one; a waterfall card over a breakdown source needs null. An app-table read is also capped by limit (default 200 rows), so a total over a bigger table needs limit set above its row count." },
               requiresRole: { type: "array", items: { type: "string" }, description: "OPTIONAL. The app roles that may read this source, any of them: written as its handler's requiresRole, so the server refuses anyone else with 403. Absent means the roles of the pages whose components read it (pages[].roles), and every role as soon as one of those pages is open to every role." }
             }
           }
@@ -12493,6 +12496,7 @@ function sourceProblems(sources, app, handlers, extra) {
         message: `source "${name}" states shape ${JSON.stringify(row.shape)}; a source answers ${either3(SOURCE_SHAPES2)}`
       });
     }
+    problems.push(...orderProblems(name, row, at));
     if (row.transform !== void 0 && row.transform !== null) {
       const path3 = String(row.transform);
       if (!TRANSFORM_RE.test(path3)) {
@@ -12512,6 +12516,62 @@ function sourceProblems(sources, app, handlers, extra) {
   }
   return problems;
 }
+var SOURCE_ORDERS = ["source", "declared"];
+function orderProblems(name, row, at) {
+  const problems = [];
+  const say = (key, message) => problems.push({ code: "source_shape", pointer: at(name, key), message: `source "${name}" ${message}` });
+  const has = (key) => Object.prototype.hasOwnProperty.call(row, key);
+  if (row.shape !== "breakdown") {
+    if (has("items")) say("items", 'states items, which only a source shaped breakdown reads (with order "declared"); give it shape breakdown, or drop items');
+    return problems;
+  }
+  if (has("order") && !SOURCE_ORDERS.includes(row.order)) {
+    say("order", `states order ${JSON.stringify(row.order)}; a breakdown source keeps ${either3(SOURCE_ORDERS.map((one) => JSON.stringify(one)))} order (the rows' own, or the labels listed in items), and is otherwise sorted by size`);
+  }
+  if (has("items")) {
+    const labels = Array.isArray(row.items) ? row.items : null;
+    if (labels === null || labels.length === 0 || !labels.every(named4) || new Set(labels).size !== labels.length) {
+      say("items", `states items as ${JSON.stringify(row.items)}; items is the breakdown's labels, each once, in the order they are drawn (["Opening ARR", "New", "Churn"])`);
+    } else if (row.order !== "declared") {
+      say("items", 'lists items, which are read only with order "declared"; add "order": "declared", or drop items');
+    }
+  } else if (row.order === "declared") {
+    say("order", `states order "declared" and lists no items; add "items": [the labels, in the order they are drawn], or use "order": "source" to keep the rows' own order`);
+  }
+  if (has("top") && row.top !== null && !(Number.isInteger(row.top) && row.top > 0)) {
+    say("top", `states top ${JSON.stringify(row.top)}; top is how many of the breakdown's items are drawn (a whole number, default 5; the rest is one "Other" figure), or null to draw every one`);
+  }
+  return problems;
+}
+function bridgeFixes(row) {
+  const declare = '"order": "declared" with "items": [the step labels, in order]';
+  const transformed = row.transform !== void 0 && row.transform !== null;
+  const origin = originOf(row);
+  const unordered = origin === "financeos" ? "a FinanceOS aggregate" : origin === "call" ? "a call" : "an app-table read with no order_by";
+  const fixes = [];
+  let order2 = null;
+  if (row.order === "declared") {
+    if (!(Array.isArray(row.items) && row.items.length > 0)) {
+      order2 = "unstated";
+      fixes.push('add "items": [the step labels, in order] beside "order": "declared"');
+    }
+  } else if (row.order === "source") {
+    if (!transformed && !(origin === "table" && named4(row.order_by))) {
+      order2 = "unpromised";
+      fixes.push(
+        origin === "table" ? `add "order_by" naming the column the steps sort by (${unordered} comes back in no promised order), or replace "order": "source" with ${declare}` : `replace "order": "source" with ${declare} \u2014 ${unordered} comes back in no promised order, so its steps could be drawn shuffled`
+      );
+    }
+  } else {
+    order2 = "unstated";
+    fixes.push(
+      transformed ? `add ${declare}, or "order": "source" to keep the order your transform returns` : origin === "table" ? `add ${declare}, or "order": "source" with an "order_by" naming the column the steps sort by` : `add ${declare} (${unordered} comes back in no promised order, so "order": "source" would not hold)`
+    );
+  }
+  const cut3 = !(Object.prototype.hasOwnProperty.call(row, "top") && row.top === null);
+  if (cut3) fixes.push('add "top": null (nothing cut, no "Other")');
+  return { fixes, order: order2, cut: cut3 };
+}
 function carriedFields(row, model) {
   if (row.transform !== void 0 && row.transform !== null) return null;
   const origin = originOf(row);
@@ -14091,9 +14151,12 @@ function widgetProblems(elements, tree, handlers, sources, widgetsPin = WIDGETS)
       shaped(`draws ${props.kind}, and source "${props.source}" answers ${shape} (its shape); give the source the shape ${reads.join(" or ")}`);
       continue;
     }
-    if (ORDERED_KINDS.includes(props.kind) && shape === "breakdown") {
+    const bridge = ORDERED_KINDS.includes(props.kind) && shape === "breakdown" ? bridgeFixes(source) : null;
+    if (bridge !== null && bridge.fixes.length > 0) {
+      const otherFigure = 'cuts to its top 5 (the rest is one "Other" figure a waterfall does not draw)';
+      const why = bridge.order === "unpromised" ? `that keeps the order its rows arrive in, which nothing promises${bridge.cut ? `, and the platform ${otherFigure}` : ""}` : bridge.order === "unstated" ? `which the platform sorts by size${bridge.cut ? ` and ${otherFigure}` : ""}` : `which the platform ${otherFigure}`;
       shaped(
-        `draws ${props.kind}, and source "${props.source}" is a breakdown, which the platform sorts by size and cuts to its top 5 (the rest is one "Other" figure a waterfall does not draw) \u2014 so the bridge would draw the wrong steps and the wrong total. Give the source the shape series (the periods are the steps, in order), or answer the bridge from a custom handler (data.app.handlers, role custom) that returns {"kind": "breakdown", "items": [...]} in the order the steps go`
+        `draws ${props.kind}, and source "${props.source}" is a breakdown ${why} \u2014 so the bridge would draw the wrong steps${bridge.cut ? " and the wrong total" : ""}. In data.sources.${props.source}: ${bridge.fixes.join("; and ")}; or give the source the shape series (the periods are the steps, in order)`
       );
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-appspace-cli",
-  "version": "0.10.15",
+  "version": "0.10.16",
   "description": "Datarails App Space CLI — build, try, push and publish App Space apps",
   "type": "module",
   "engines": {