@datarails-ai/dr-appspace-cli 0.12.11 → 0.12.13

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.12.11",
+  version: "0.12.13",
   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-14T19:55:58.887Z";
+var BUILD_TIME = "2026-10-15T06:27:08.313Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -6435,7 +6435,7 @@ function endOfRegex(text3, start) {
 // ../flows/insights-builder/kit/contract/extract.mjs
 var CONTRACT_V = 1;
 var GENERATED_BY = "dashboard-kit/contract@1";
-var KIT_REGIONS = /* @__PURE__ */ new Set(["header", "asof", "refresh", "nav", "filters", "controls", "band"]);
+var KIT_REGIONS = /* @__PURE__ */ new Set(["header", "asof", "refresh", "theme", "nav", "filters", "controls", "band"]);
 var DASHBOARD_KIND = "dashboard";
 var BAND_ROLE = "band";
 var GRID_CLASSES = /* @__PURE__ */ new Set(["dr-dash", "dr-grid"]);
@@ -16373,18 +16373,31 @@ async function writePackage(dir, appId, pkg) {
     ) + "\n"
   );
 }
-async function writeStoredContract(client, appId, dir) {
+async function readStoredContract(client, appId, codeVersion) {
+  const app = `/apps/${encodeURIComponent(appId)}`;
+  const path3 = typeof codeVersion === "number" ? `${app}/versions/${String(codeVersion)}/contract` : `${app}/contract`;
   let stored;
   try {
-    stored = await client.request(`/apps/${encodeURIComponent(appId)}/contract`);
-  } catch {
-    return false;
+    stored = await client.request(path3);
+  } catch (err) {
+    if (err instanceof AppSpaceHttpError) {
+      const detail = err.body?.detail;
+      return { missing: `${String(err.status)}${typeof detail === "string" ? ` ${detail}` : ""}` };
+    }
+    return { missing: err instanceof Error ? err.message.split("\n")[0] ?? "" : String(err) };
+  }
+  if (typeof stored !== "object" || stored === null || Array.isArray(stored)) {
+    return { missing: "the contract read answered no document" };
   }
-  if (typeof stored !== "object" || stored === null || Array.isArray(stored)) return false;
   const held = stored["contract"];
   const document = typeof held === "object" && held !== null && !Array.isArray(held) ? held : stored;
-  if (!("v" in document)) return false;
-  await writeFile5(join10(dir, "contract.json"), JSON.stringify(document, null, 2) + "\n");
+  if (!("v" in document)) return { missing: "the contract read answered no document" };
+  return { document };
+}
+async function writeStoredContract(client, appId, dir, codeVersion) {
+  const read = await readStoredContract(client, appId, codeVersion);
+  if (!("document" in read)) return false;
+  await writeFile5(join10(dir, "contract.json"), JSON.stringify(read.document, null, 2) + "\n");
   return true;
 }
 async function writeOwnedFiles(dir, document, { force = false } = {}) {
@@ -16443,20 +16456,52 @@ async function restoreOwnedFiles(dir, contractWritten, { force }) {
   ];
   return writeOwnedFiles(dir, { owned }, { force });
 }
-async function pullInto(client, appId, dir) {
-  let pkg;
-  try {
-    pkg = await client.request(`/apps/${encodeURIComponent(appId)}/package`);
-  } catch (err) {
-    if (err instanceof AppSpaceHttpError && err.status === 404) return null;
-    throw err;
+var contractWait = { pulls: 7, baseMs: 250, capMs: 4e3 };
+function contractWaitMs(pull) {
+  return Math.min(contractWait.capMs, contractWait.baseMs * 2 ** (pull - 1));
+}
+var LiveContractMissing = class extends Error {
+  constructor(appId, revision, pulls, last) {
+    super(
+      `${appId} is live at revision ${String(revision)}, and its contract could not be read in ${String(pulls)} pulls (the last answered: ${last}). Without it this landing cannot see the cards already live: it would build the app again from the skeleton and replace every one of them. Nothing was landed. Run the same command again. If it fails the same way, the live version has no contract on record: \`app-space get ${appId} --dir <a new folder>\` and then \`app-space push <that folder>\` push the same package back with one, and the next landing builds on it.`
+    );
+    this.appId = appId;
+    this.revision = revision;
+    this.pulls = pulls;
+    this.last = last;
+    this.name = "LiveContractMissing";
+  }
+  appId;
+  revision;
+  pulls;
+  last;
+};
+async function pullInto(client, appId, dir, {
+  onWait,
+  sleep: sleep2 = (ms) => new Promise((done) => setTimeout(done, ms))
+} = {}) {
+  for (let pull = 1; ; pull += 1) {
+    let pkg;
+    try {
+      pkg = await client.request(`/apps/${encodeURIComponent(appId)}/package`);
+    } catch (err) {
+      if (err instanceof AppSpaceHttpError && err.status === 404) return null;
+      throw err;
+    }
+    await rm2(join10(dir, "contract.json"), { force: true });
+    await writePackage(dir, appId, pkg);
+    const read = await readStoredContract(client, appId, pkg.code_version);
+    if ("document" in read) {
+      await writeFile5(join10(dir, "contract.json"), JSON.stringify(read.document, null, 2) + "\n");
+      await restoreOwnedFiles(dir, true, { force: true });
+      await recordPulled(dir, true);
+      return { revision: pkg.revision, stage: pkg.stage };
+    }
+    if (pull >= contractWait.pulls) throw new LiveContractMissing(appId, pkg.revision, pull, read.missing);
+    const ms = contractWaitMs(pull);
+    onWait?.(pull, ms, read.missing);
+    await sleep2(ms);
   }
-  await rm2(join10(dir, "contract.json"), { force: true });
-  await writePackage(dir, appId, pkg);
-  const contract = await writeStoredContract(client, appId, dir);
-  await restoreOwnedFiles(dir, contract, { force: true });
-  await recordPulled(dir, contract);
-  return { revision: pkg.revision, stage: pkg.stage };
 }
 async function runGet(appId, opts) {
   const client = await connect(opts);
@@ -16473,7 +16518,7 @@ async function runGet(appId, opts) {
       return 1;
     }
     await writePackage(dir, appId, pkg);
-    const contract = await writeStoredContract(client, appId, dir);
+    const contract = await writeStoredContract(client, appId, dir, pkg.code_version);
     const restored = await restoreOwnedFiles(dir, contract, { force: opts.force === true });
     await recordPulled(dir, contract);
     if (opts.json === true) {
@@ -17261,7 +17306,7 @@ var contract_schema_default = {
               properties: {
                 file: { type: "string" },
                 tokens: { type: "object", additionalProperties: { type: "string" } },
-                preset: { type: "string", enum: ["default", "slate", "warm", "contrast", "presentation"], description: "OPTIONAL. A named look from the pinned ui-kit (presentation is refused: ui-kit/v4 shipped without it); absent means default. The compiler fills pages[].theme/density where a page states none from this and app.theme.density, and drops both keys from the filled contract it compares (mirrors fillHeaders)." },
+                preset: { type: "string", enum: ["default", "slate", "warm", "contrast", "presentation"], description: "OPTIONAL. A named look from the pinned ui-kit (presentation is refused: ui-kit/v4 shipped without it); absent means default. A dashboard is built light: slate composes as default, because dark is the viewer's Dark mode switch (the theme region). The compiler fills pages[].theme/density where a page states none from this and app.theme.density, and drops both keys from the filled contract it compares (mirrors fillHeaders)." },
                 density: { type: "string", enum: ["comfortable", "compact"], description: "OPTIONAL. app.theme.density; absent means comfortable. Distinct from pages[].density, which is the compiled data-dr-density string." }
               }
             }
@@ -17277,7 +17322,7 @@ var contract_schema_default = {
         module: { type: "string", description: "dr-widgets, dr-insights, dr-fmt, echarts, ui-kit" },
         version: { type: "string", description: "1.1.1 for a vendor module, v3 for the ui-kit" },
         file: { type: "string" },
-        path: { type: "string", description: "the platform-root path, e.g. vendor/dr-widgets@1.2.1/widgets.js" },
+        path: { type: "string", description: "the platform-root path, e.g. vendor/dr-widgets@1.2.3/widgets.js" },
         rel: { enum: ["script", "stylesheet"] },
         pages: { type: "array", items: { type: "string" } },
         order: { type: "integer", minimum: 0, description: "load order: where this module is first reached across the bundle" }
@@ -17326,7 +17371,7 @@ var contract_schema_default = {
           }
         },
         scripts: { type: "array", items: { type: "string" }, description: "the bundle scripts this page loads" },
-        theme: { type: ["string", "null"], description: "data-dr-theme: default, slate, warm, contrast" },
+        theme: { type: ["string", "null"], description: "data-dr-theme: default, warm, contrast. A dashboard is built light, so slate composes as default (dark is the viewer's Dark mode switch); a page read back from a dashboard built before that may still say slate." },
         density: { type: ["string", "null"], description: "data-dr-density" },
         mount: {
           oneOf: [
@@ -17446,7 +17491,7 @@ var contract_schema_default = {
           enum: ["region", "grid", "widget", "control", "nav", "tab", "slot", "form", "list", "detail", "queue", "action", "filter", "stat", "chart", "custom", "field", "number_input", "tabs", "tab_panel", "select", "date_picker", "data_grid", "dialog", "variance_table", "toggle", "control_group", "callout", "scenario_columns", "slider", "button", "status", "badge", "tag", "empty_state", "stepper", "alert", "checkbox", "radio_group", "file_upload", "skeleton", "progress", "accordion", "tooltip_info", "filter_bar", "filter_chip", "date_range", "fiscal_month", "search_input", "split_pane", "file_viewer", "line_grid", "document", "panel"],
           description: "the dashboard vocabulary (region, grid, widget, control, nav, tab, slot) and the App Builder's component vocabulary (form, list, detail, queue, action, filter, the stat tile that reads one measure out of a summary handler, the chart that draws the rows one list, inbox or custom handler answers, the custom component a module under ui/components draws, and the field that sits inside one). widget is shared: on an app page it is a dashboard card too, drawn by dr-app-widgets in the kind data-dr-kind names, over the one widget payload the handler data-dr-source names answers"
         },
-        role: { type: ["string", "null"], description: "a region's data-dr-kit (header, asof, refresh, nav, filters, controls), a widget's kind, a control's kind, a slot's name. Null for a component: its kind IS its type, and the role it is meant for is props.role." },
+        role: { type: ["string", "null"], description: "a region's data-dr-kit (header, asof, refresh, theme, nav, filters, controls), a widget's kind, a control's kind, a slot's name. Null for a component: its kind IS its type, and the role it is meant for is props.role." },
         id: { type: ["string", "null"] },
         tag: { type: ["string", "null"], description: "null for an element read out of a built bundle, which no longer says what it renders" },
         classes: { type: "array", items: { type: "string" } },
@@ -19808,6 +19853,9 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 var THEME_FILE3 = "ui/theme.css";
 var PRESETS2 = ["default", "slate", "warm", "contrast"];
 var DEFAULT_PRESET = "default";
+var DARK_PRESET = "slate";
+var CANVAS_TOKENS = /* @__PURE__ */ new Set(["--dr-surface", "--dr-page", "--dr-border"]);
+var DARK_SURFACE_BELOW = 0.18;
 var SPAN_BY_KIND = {
   kpi: 3,
   line: 6,
@@ -19890,13 +19938,21 @@ function composeLayout(contract) {
   const app = isPlainObject7(out.app) ? out.app : out.app = {};
   const pages = Array.isArray(out.pages) ? out.pages : out.pages = [];
   const elements = isPlainObject7(out.elements) ? out.elements : out.elements = {};
-  const preset = presetOf(app, pages);
+  const asked = presetOf(app, pages);
+  const preset = asked === DARK_PRESET ? DEFAULT_PRESET : asked;
   if (isPlainObject7(app.theme) && "preset" in app.theme) delete app.theme.preset;
   for (const page of pages) {
     const path3 = page.path ?? "ui/index.html";
     if (page.theme === void 0 || page.theme === null) {
       page.theme = preset;
       record2("page.theme", path3, `${path3} opens on the "${preset}" theme`);
+    } else if (page.theme === DARK_PRESET) {
+      page.theme = DEFAULT_PRESET;
+      record2(
+        "page.theme",
+        path3,
+        `${path3} opens on the "${DEFAULT_PRESET}" theme: "${DARK_PRESET}" is the viewer's Dark mode switch, not a look a dashboard is built on`
+      );
     }
     if (page.density === void 0) page.density = null;
     if (page.title === void 0 || page.title === null) {
@@ -19971,6 +20027,21 @@ function composeTheme(app, preset, record2) {
   const table = THEME_TOKENS[preset] ?? THEME_TOKENS[DEFAULT_PRESET];
   const theme = isPlainObject7(app.theme) ? app.theme : {};
   const tokens = isPlainObject7(theme.tokens) ? { ...theme.tokens } : {};
+  const dark = THEME_TOKENS[DARK_PRESET];
+  if (isDarkSurface(tokens["--dr-surface"], dark["--dr-surface"], tokens)) {
+    let lightened = 0;
+    for (const [token, value] of Object.entries(dark)) {
+      if (table[token] === void 0 || tokens[token] === table[token]) continue;
+      if (tokens[token] !== value && !CANVAS_TOKENS.has(token)) continue;
+      tokens[token] = table[token];
+      lightened += 1;
+    }
+    record2(
+      "theme.tokens",
+      THEME_FILE3,
+      `${lightened} palette token(s) moved from the "${DARK_PRESET}" preset to "${preset}": a dashboard is built light, and dark is the viewer's Dark mode switch`
+    );
+  }
   let filled = 0;
   for (const [token, value] of Object.entries(table)) {
     if (token in tokens) continue;
@@ -19986,6 +20057,21 @@ function composeTheme(app, preset, record2) {
     );
   }
 }
+function isDarkSurface(value, darkSurface, tokens, seen = /* @__PURE__ */ new Set()) {
+  if (typeof value !== "string") return false;
+  const alias = /^var\(\s*(--[a-z0-9-]+)\s*(?:,[^)]*)?\)$/i.exec(value.trim());
+  if (alias) {
+    if (seen.has(alias[1])) return false;
+    seen.add(alias[1]);
+    return isDarkSurface(tokens[alias[1]], darkSurface, tokens, seen);
+  }
+  if (value === darkSurface) return true;
+  try {
+    return luminance(value) < DARK_SURFACE_BELOW;
+  } catch {
+    return false;
+  }
+}
 function presetOf(app, pages) {
   const asked = isPlainObject7(app.theme) ? app.theme.preset : null;
   if (typeof asked === "string" && PRESETS2.includes(asked)) return asked;
@@ -20371,6 +20457,9 @@ function appbar(page, elements) {
     "  </div>",
     '  <div class="dr-appbar__actions">',
     `    <button type="button" class="${classesOf2(elements, "region", "refresh", ["dr-btn", "dr-btn--secondary", "dr-btn--sm"])}" data-dr-kit="refresh">Refresh</button>`,
+    // The viewer's light/dark switch: dr-widgets flips the body between this
+    // page's own preset and slate, and remembers the choice per app.
+    `    <button type="button" class="${classesOf2(elements, "region", "theme", ["dr-btn", "dr-btn--secondary", "dr-btn--sm"])}" data-dr-kit="theme" aria-pressed="false">Dark mode</button>`,
     "  </div>",
     "</header>"
   ];
@@ -27131,7 +27220,7 @@ var kit_default = {
   fmt: "dr-fmt@2.0.1",
   markdown: "dr-md@1.0.0",
   uiKit: "ui-kit/v4",
-  widgets: "dr-widgets@1.2.1"
+  widgets: "dr-widgets@1.2.3"
 };
 
 // ../flows/appspace-builder/kit/kit.json
@@ -27348,7 +27437,7 @@ async function runCompile(dir, opts) {
   if (plan.intruders.length > 0 || plan.strays.length > 0 || plan.edited.length > 0) {
     report.failure = "would-overwrite";
     await writeReport(dir, report);
-    process.stderr.write(refusalOf(dir, plan));
+    process.stderr.write(refusalOf(dir, plan, opts.ontoLive === true));
     return 1;
   }
   const check5 = opts.check === true;
@@ -27687,12 +27776,13 @@ function customHandlerPaths(contract) {
   }
   return out;
 }
-function refusalOf(dir, plan) {
+function refusalOf(dir, plan, ontoLive) {
   const list3 = (paths) => `${paths.slice(0, 3).join(", ")}${paths.length > 3 ? "\u2026" : ""}`;
   let out = "";
   if (plan.intruders.length > 0) {
-    out += `${dir} already holds ${list3(plan.intruders)}, which this compiler did not write. Move them aside, or pass --force to write over them.
-`;
+    out += `${dir} already holds ${list3(plan.intruders)}, ` + // `ship --onto-live` pulled these: they are the live app, and writing
+    // over them is replacing other landings' cards. Never the way past it.
+    (ontoLive ? "which this compiler did not write: they are the live app as pulled, and this landing could not build on them. Nothing was pushed. Run the same command again.\n" : "which this compiler did not write. Move them aside, or pass --force to write over them.\n");
   }
   const handlers = plan.strays.filter((path3) => path3.startsWith("handlers/"));
   const modules = plan.strays.filter((path3) => !path3.startsWith("handlers/"));
@@ -27721,7 +27811,7 @@ function roundTripDiffs(input, extracted, compilerProblems = [], { order: order2
   const stated2 = order2 === void 0 ? {} : { order: order2 };
   const read = order2 === void 0 ? {} : { order: "keys" };
   const left = stripPositional(normaliseApp(input), stated2);
-  const right = stripPositional(normaliseApp(extracted), read);
+  const right = stripPositional(normaliseApp(withoutUnstatedChrome(input, extracted)), read);
   const declared = compilerProblems.some((problem5) => problem5.code === DECLARED_LOSS);
   const diffs = [];
   for (const section of ["app", "pages", "elements", "data"]) {
@@ -27746,6 +27836,40 @@ function roundTripDiffs(input, extracted, compilerProblems = [], { order: order2
   }
   return diffs.slice(0, 40);
 }
+var ADDED_CHROME = /* @__PURE__ */ new Set(["theme"]);
+function withoutUnstatedChrome(input, extracted) {
+  if (!isPlain(input) || !isPlain(extracted)) return extracted;
+  const want = input["elements"];
+  const got = extracted["elements"];
+  if (!isPlain(want) || !isPlain(got)) return extracted;
+  const regionOf = (element) => `${String(element["page"] ?? "")}|${String(element["role"] ?? "")}`;
+  const statedRegions = new Set(
+    Object.values(want).filter((element) => isPlain(element) && element["type"] === "region").map(regionOf)
+  );
+  const unstated = new Set(
+    Object.entries(got).filter(([, element]) => {
+      if (!isPlain(element) || element["type"] !== "region") return false;
+      if (!ADDED_CHROME.has(String(element["role"] ?? ""))) return false;
+      const children = element["children"];
+      return !statedRegions.has(regionOf(element)) && (!Array.isArray(children) || children.length === 0);
+    }).map(([uid]) => uid)
+  );
+  if (unstated.size === 0) return extracted;
+  const out = JSON.parse(JSON.stringify(extracted));
+  const elements = out["elements"];
+  for (const uid of unstated) delete elements[uid];
+  for (const element of Object.values(elements)) {
+    if (isPlain(element) && Array.isArray(element["children"])) {
+      element["children"] = element["children"].filter((uid) => !unstated.has(String(uid)));
+    }
+  }
+  for (const page of Array.isArray(out["pages"]) ? out["pages"] : []) {
+    if (isPlain(page) && Array.isArray(page["tree"])) {
+      page["tree"] = page["tree"].filter((uid) => !unstated.has(String(uid)));
+    }
+  }
+  return out;
+}
 function normaliseApp(contract) {
   if (typeof contract !== "object" || contract === null) return contract;
   const out = JSON.parse(JSON.stringify(contract));
@@ -27971,6 +28095,12 @@ async function loadContract(dir, opts) {
     return { contract, assemble: null, headline: resolveExpectations(opts.expect, contract, {}), overlay: {} };
   }
   const baseRaw = await readIfPresent(join15(dir, "contract.json"));
+  if (opts.ontoLive === true && baseRaw === void 0 && await readIfPresent(join15(dir, "manifest.json")) !== void 0) {
+    process.stderr.write(
+      "ship --onto-live: the folder holds the live package but not its contract.json, so this landing cannot see the cards already live, and would replace them. Nothing was written. Run the same command again.\n"
+    );
+    return { exit: 1 };
+  }
   const assembled = assemble({
     drafts: (await Promise.all(drafts.map(readNamed))).flatMap(pageDrafts),
     ...opts.skeleton === void 0 ? {} : { skeleton: await readNamed(opts.skeleton) },
@@ -28338,7 +28468,7 @@ function registerShipCommand(parent) {
   withJsonOption(
     withServerOptions(
       withAssemblyOptions(
-        parent.command("ship [dir]").description("Assemble, compile, push and prove a dashboard pass; print the update block the reply ends with.").option("--seed <file>", "Seed rows, as JSON. Forwarded to the push.").option("--force", "Write over files this compiler did not write (never a custom handler).").option(
+        parent.command("ship [dir]").description("Assemble, compile, push and prove a dashboard pass; print the update block the reply ends with.").option("--seed <file>", "Seed rows, as JSON. Forwarded to the push.").option("--force", "Write over files this compiler did not write (never a custom handler). Refused with --onto-live.").option(
           "--onto-live",
           "Land this pass's cards on the app as it is live now, keeping every card already there: pull it, add them, push against its revision, and start over when another push lands first. Needs --app-id and --skeleton, and a folder of its own."
         )
@@ -28373,6 +28503,11 @@ async function runShipOntoLive(dir, opts) {
   if ((opts.expect ?? []).length > 0) {
     return refuse("--expect holds the headline, which is the build's to confirm; a landing proves its own cards only.");
   }
+  if (opts.force === true) {
+    return refuse(
+      "does not take --force: every landing builds on the cards already live, and --force would let this one replace them. Run the same command without it. If it refuses over files it did not write, the live app could not be read whole: run it again, and report the refusal if it repeats."
+    );
+  }
   const owned = await claimFolder(dir);
   if (owned !== null) return refuse(owned);
   await defaultServerFromSession(opts);
@@ -28384,7 +28519,20 @@ async function runShipOntoLive(dir, opts) {
     const client = await connect(opts);
     let pulled;
     try {
-      pulled = await pullInto(client, appId, dir);
+      pulled = await pullInto(client, appId, dir, {
+        onWait: (pull, ms, missing) => {
+          if (opts.json === true) return;
+          process.stdout.write(
+            `onto ${appId}: the live version's contract is not readable yet (${missing}) \u2014 pulling again in ${String(ms)} ms (pull ${String(pull + 1)})
+`
+          );
+        }
+      });
+    } catch (err) {
+      if (!(err instanceof LiveContractMissing)) throw err;
+      process.stderr.write(`ship --onto-live: ${err.message}
+`);
+      return { code: 1, lost: null, creating: false };
     } finally {
       client.cleanup();
     }

package/package.json

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