@datarails-ai/dr-appspace-cli 0.10.4 → 0.10.5

package/README.md

@@ -85,6 +85,8 @@ A dashboard can be **assembled** rather than typed. `compile --draft
 (`--skeleton <file>`, or the draft's own `skeleton` key) and one SPEC draft
 per page — each card's `props` and SPEC `row`, plus its `page`, `reads`,
 `datasets` and `capabilities` — and then compiles it like any other. The
+app's `name` and `description` (the line under the name on its card, which
+kit rule R1.5 requires) are the skeleton's `app`, as written. The rest of the
 frame is the CLI's: the first page is `ui/index.html` at `/`, every other
 `ui/<name>.html` at `/<name>.html`, the skeleton's sections and card order,
 a page not built yet carries one card saying it comes next, and — only

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.4",
+  version: "0.10.5",
   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-09-30T14:25:42.306Z";
+var BUILD_TIME = "2026-09-30T14:45:52.678Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -3531,9 +3531,10 @@ function canonical(value) {
   return JSON.stringify(value) ?? "null";
 }
 function frame(skeleton, pages, appId) {
+  const described = skeleton.app.description === void 0 ? {} : { description: skeleton.app.description };
   return {
     v: 1,
-    app: { id: appId, name: skeleton.app.name, kind: "dashboard", routes: pages.map((plan) => plan.address) },
+    app: { id: appId, name: skeleton.app.name, ...described, kind: "dashboard", routes: pages.map((plan) => plan.address) },
     pages: pages.map(pageFrom),
     elements: {},
     data: { source: "static", widgets: {} }
@@ -4936,6 +4937,9 @@ function appSection(app, manifest) {
   return {
     id: manifest.id ?? null,
     name: manifest.name ?? null,
+    // What the app does, in the line under its name on the card Studio lists
+    // it on. Read as written: the verifier, not the reader, judges the words.
+    description: typeof manifest.description === "string" ? manifest.description : null,
     kind: manifest.kind ?? null,
     // What the app is called in the nav, which is not always what it is
     // called: `name` is the title of the page and `nav.label` is the word
@@ -7853,6 +7857,7 @@ var contract_schema_default = {
       properties: {
         id: { type: ["string", "null"] },
         name: { type: ["string", "null"] },
+        description: { type: ["string", "null"], description: "manifest.description - what the app does, in one sentence: the line under its name on the card Studio lists it on. OPTIONAL: a contract written before this key existed omits it." },
         kind: { type: ["string", "null"], description: "dashboard, app, or absent" },
         nav_label: { type: ["string", "null"], description: "manifest.nav.label - what the app is called in the nav, which is not always manifest.name. OPTIONAL: a contract written before this key existed omits it." },
         version: { type: ["string", "null"] },
@@ -11663,6 +11668,8 @@ function manifestFile(contract, handlerName) {
     apiVersion: app.api_version ?? "appspace/v1",
     id: app.id ?? null,
     name: app.name ?? null,
+    // The line under the name on the dashboard's card, as `compileApp` writes an app's.
+    ...typeof app.description === "string" ? { description: app.description } : {},
     version: app.version ?? "0.1.0",
     kind: "dashboard",
     ...app.nav_label ? { nav: { label: app.nav_label } } : {},
@@ -15734,6 +15741,10 @@ function manifestOf(contract, app, handlers, names, model, served = []) {
     apiVersion: app.api_version ?? DEFAULT_API_VERSION,
     id: app.id ?? null,
     name: app.name ?? app.id ?? null,
+    // The line under the name on the app's card. Any string is written, an
+    // empty one too, so the verifier says "blank" and the round trip holds;
+    // a contract that states none writes the manifest it always did.
+    ...typeof app.description === "string" ? { description: app.description } : {},
     version: app.version ?? DEFAULT_VERSION
   };
   if (named4(app.nav_label)) manifest.nav = { label: app.nav_label };
@@ -17405,6 +17416,27 @@ function isReferenced2(name, frontendText) {
   return new RegExp(`(['"\`])${escaped}\\1|/${escaped}\\b`).test(frontendText);
 }
 
+// ../flows/insights-builder/kit/checks/lib/description.mjs
+var DESCRIPTION_MAX = 120;
+var SAYS_NOTHING = "so the app's card in Studio says nothing under its name";
+var WRITE = `Write app.description in the contract: one sentence on what the app does, for the card; no newline, and at most ${DESCRIPTION_MAX} characters`;
+var LINE_BREAK = /[\n\r\u2028\u2029]/;
+function descriptionProblems(description) {
+  if (description === void 0 || description === null) return [`manifest.description is missing, ${SAYS_NOTHING}. ${WRITE}`];
+  if (typeof description !== "string") return [`manifest.description is ${JSON.stringify(description)}, not text, ${SAYS_NOTHING}. ${WRITE}`];
+  const shown2 = description.trim().split(/\s+/).join(" ");
+  if (shown2 === "") return [`manifest.description is blank, ${SAYS_NOTHING}. ${WRITE}`];
+  const problems = [];
+  if (LINE_BREAK.test(description)) {
+    problems.push(`manifest.description breaks onto a second line, and the card in Studio shows one paragraph. ${WRITE}`);
+  }
+  const characters = [...shown2].length;
+  if (characters > DESCRIPTION_MAX) {
+    problems.push(`manifest.description is ${characters} characters, and the card in Studio has room for ${DESCRIPTION_MAX} (three lines). ${WRITE}`);
+  }
+  return problems;
+}
+
 // ../flows/insights-builder/kit/checks/rules/manifest.mjs
 var DASHBOARD_CAPABILITIES = /* @__PURE__ */ new Set(["financeos", "state"]);
 var FINANCEOS_READ_SCOPE = /^(metrics|semantic|tables|status|filebox|raw):read$/;
@@ -17418,6 +17450,7 @@ function checkManifest(app) {
   if (dataModel !== null || manifest.dataModel !== void 0 || manifest.data_model !== void 0) {
     violations.push({ rule: "R1.1", where: where2, message: "a dashboard declares no data_model: every number is read live from FinanceOS" });
   }
+  for (const message of descriptionProblems(manifest.description)) violations.push({ rule: "R1.5", where: where2, message });
   const capabilities = manifest.capabilities ?? {};
   if (typeof capabilities !== "object" || Array.isArray(capabilities)) {
     violations.push({ rule: "R1.1", where: where2, message: "capabilities must be an object" });
@@ -18883,6 +18916,9 @@ function appSection2(app, manifest) {
   return {
     id: manifest.id ?? null,
     name: manifest.name ?? null,
+    // What the app does, in the line under its name on the card Studio lists
+    // it on. Read as written: the verifier, not the reader, judges the words.
+    description: typeof manifest.description === "string" ? manifest.description : null,
     kind: manifest.kind ?? null,
     // What the app is called in the nav, which is not always what it is
     // called: `name` is the title of the page and `nav.label` is the word
@@ -21595,6 +21631,27 @@ function checkLook(app, contract, contractError) {
   return { violations, skipped: [] };
 }
 
+// ../flows/appspace-builder/kit/checks/lib/description.mjs
+var DESCRIPTION_MAX2 = 120;
+var SAYS_NOTHING2 = "so the app's card in Studio says nothing under its name";
+var WRITE2 = `Write app.description in the contract: one sentence on what the app does, for the card; no newline, and at most ${DESCRIPTION_MAX2} characters`;
+var LINE_BREAK2 = /[\n\r\u2028\u2029]/;
+function descriptionProblems2(description) {
+  if (description === void 0 || description === null) return [`manifest.description is missing, ${SAYS_NOTHING2}. ${WRITE2}`];
+  if (typeof description !== "string") return [`manifest.description is ${JSON.stringify(description)}, not text, ${SAYS_NOTHING2}. ${WRITE2}`];
+  const shown2 = description.trim().split(/\s+/).join(" ");
+  if (shown2 === "") return [`manifest.description is blank, ${SAYS_NOTHING2}. ${WRITE2}`];
+  const problems = [];
+  if (LINE_BREAK2.test(description)) {
+    problems.push(`manifest.description breaks onto a second line, and the card in Studio shows one paragraph. ${WRITE2}`);
+  }
+  const characters = [...shown2].length;
+  if (characters > DESCRIPTION_MAX2) {
+    problems.push(`manifest.description is ${characters} characters, and the card in Studio has room for ${DESCRIPTION_MAX2} (three lines). ${WRITE2}`);
+  }
+  return problems;
+}
+
 // ../flows/appspace-builder/kit/checks/rules/manifest.mjs
 function checkManifest2(app) {
   const violations = [];
@@ -21603,6 +21660,7 @@ function checkManifest2(app) {
   if (typeof manifest.name !== "string" || !manifest.name.trim()) {
     violations.push({ rule: "A1.1", where: where2, message: "manifest.name is empty; the app is listed under its id" });
   }
+  for (const message of descriptionProblems2(manifest.description)) violations.push({ rule: "A1.7", where: where2, message });
   if (manifest.kind === "dashboard") {
     violations.push({ rule: "A1.2", where: where2, message: 'manifest.kind is "dashboard"; dashboards are built by the Insights Builder and its kit, not here' });
   }
@@ -22537,7 +22595,7 @@ var kit_default = {
 // ../flows/appspace-builder/kit/kit.json
 var kit_default2 = {
   name: "appspace-app-kit",
-  description: "The checks the App Builder runs on every pushed version of a regular App Space app: a manifest that names the app, handlers that exist and take (ctx, payload), a page that calls only handlers that exist, no handler nothing reaches, roles declared wherever a handler reads ctx.role, and the component vocabulary held to the data model \u2014 every data-dr-action a declared handler, every data-dr-entity a table, every data-dr-field one of its columns.",
+  description: "The checks the App Builder runs on every pushed version of a regular App Space app: a manifest that names the app and says in a line what it does, handlers that exist and take (ctx, payload), a page that calls only handlers that exist, no handler nothing reaches, roles declared wherever a handler reads ctx.role, and the component vocabulary held to the data model \u2014 every data-dr-action a declared handler, every data-dr-entity a table, every data-dr-field one of its columns.",
   checks: "checks/run.mjs",
   contract: "contract/extract.mjs",
   charts: "echarts@5.6.0",
@@ -29511,6 +29569,8 @@ function dashboardStarter(values) {
     app: {
       id: values.id,
       name: values.name,
+      // What the card Studio lists the dashboard on says under its name.
+      description: "What this dashboard answers, in one sentence its reader would use.",
       kind: "dashboard",
       nav_label: values.name,
       routes: ["/"],
@@ -29597,6 +29657,8 @@ function appStarter(values) {
     app: {
       id: values.id,
       name: values.name,
+      // What the card Studio lists the app on says under its name.
+      description: `Raise a ${record2} and follow it until it is done.`,
       nav_label: values.name,
       routes: ["/"],
       capabilities: { data: ["rw"] },

package/package.json

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