@datarails-ai/dr-appspace-cli 0.12.1 → 0.12.3

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.1",
+  version: "0.12.3",
   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-07T21:55:46.945Z";
+var BUILD_TIME = "2026-10-08T11:11:55.601Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -208,7 +208,17 @@ function decodeShape(value) {
 
 // src/auth/keyring/types.ts
 function isCookielessSession(s) {
-  return s.impersonatorEmail !== void 0 && s.impersonatorEmail !== "" || s.cookieless === true;
+  return s.impersonatorEmail !== void 0 && s.impersonatorEmail !== "" || s.cookieless === true || hasApiKey(s) || hasApiKeyEnvVar(s);
+}
+function hasApiKey(s) {
+  return s.apiKey !== void 0 && s.apiKey !== "";
+}
+function hasApiKeyEnvVar(s) {
+  return s.apiKeyEnvVar !== void 0 && s.apiKeyEnvVar !== "";
+}
+function usesApiKey(s) {
+  const impersonated = s.impersonatorEmail !== void 0 && s.impersonatorEmail !== "";
+  return (hasApiKey(s) || hasApiKeyEnvVar(s)) && !impersonated;
 }
 var KeychainError = class extends Error {
   constructor(message, options) {
@@ -428,7 +438,9 @@ var KeyringStore = class _KeyringStore {
     try {
       parsed = JSON.parse(raw);
     } catch (err) {
-      throw new KeychainError(`decode session for ${serverKey}:${email}`, { cause: err });
+      throw new KeychainError(`decode session for ${serverKey}:${email}`, {
+        cause: err
+      });
     }
     const sessionId = typeof parsed.sessionId === "string" ? parsed.sessionId : "";
     const csrfToken = typeof parsed.csrfToken === "string" ? parsed.csrfToken : "";
@@ -436,7 +448,10 @@ var KeyringStore = class _KeyringStore {
     const impersonatorEmail = typeof parsed.impersonatorEmail === "string" ? parsed.impersonatorEmail : "";
     const impersonated = impersonatorEmail !== "";
     const cookielessFlag = parsed.cookieless === true;
-    const cookieless = impersonated || cookielessFlag;
+    const apiKey = typeof parsed.apiKey === "string" && parsed.apiKey !== "" ? parsed.apiKey : "";
+    const apiKeyEnvVar = typeof parsed.apiKeyEnvVar === "string" && parsed.apiKeyEnvVar !== "" ? parsed.apiKeyEnvVar : "";
+    const keyed = apiKey !== "" || apiKeyEnvVar !== "";
+    const cookieless = impersonated || cookielessFlag || keyed;
     if (savedAtStr === "" || !cookieless && (sessionId === "" || csrfToken === "")) {
       throw new KeychainError(`session for ${serverKey}:${email} is malformed`);
     }
@@ -458,6 +473,18 @@ var KeyringStore = class _KeyringStore {
     if (cookielessFlag) {
       session.cookieless = true;
     }
+    if (apiKey !== "") {
+      session.apiKey = apiKey;
+    }
+    if (apiKeyEnvVar !== "") {
+      session.apiKeyEnvVar = apiKeyEnvVar;
+    }
+    if (typeof parsed.apiKeyExpiresAt === "string" && parsed.apiKeyExpiresAt !== "") {
+      session.apiKeyExpiresAt = new Date(parsed.apiKeyExpiresAt);
+    }
+    if (typeof parsed.jwtApiKeyFingerprint === "string" && parsed.jwtApiKeyFingerprint !== "") {
+      session.jwtApiKeyFingerprint = parsed.jwtApiKeyFingerprint;
+    }
     if (typeof parsed.jwtExpiresAt === "string" && parsed.jwtExpiresAt !== "") {
       session.jwtExpiresAt = new Date(parsed.jwtExpiresAt);
     }
@@ -499,7 +526,7 @@ var KeyringStore = class _KeyringStore {
     const impersonated = session.impersonatorEmail !== void 0 && session.impersonatorEmail !== "";
     const cookieless = session.cookieless === true;
     if (isCookielessSession(session)) {
-      if (session.jwtAccess === void 0 || session.jwtAccess === "") {
+      if (!usesApiKey(session) && (session.jwtAccess === void 0 || session.jwtAccess === "")) {
         throw new Error("saveSession: cookie-less session must have a jwtAccess token");
       }
     } else {
@@ -533,6 +560,18 @@ var KeyringStore = class _KeyringStore {
     if (cookieless) {
       metaBlob.cookieless = true;
     }
+    if (session.apiKey !== void 0 && session.apiKey !== "") {
+      metaBlob.apiKey = session.apiKey;
+    }
+    if (session.apiKeyEnvVar !== void 0 && session.apiKeyEnvVar !== "") {
+      metaBlob.apiKeyEnvVar = session.apiKeyEnvVar;
+    }
+    if (session.apiKeyExpiresAt !== void 0) {
+      metaBlob.apiKeyExpiresAt = session.apiKeyExpiresAt.toISOString();
+    }
+    if (session.jwtApiKeyFingerprint !== void 0 && session.jwtApiKeyFingerprint !== "") {
+      metaBlob.jwtApiKeyFingerprint = session.jwtApiKeyFingerprint;
+    }
     await this.backend.set(SERVICE, sessionAccount, JSON.stringify(metaBlob));
     if (session.jwtAccess !== void 0 && session.jwtAccess !== "") {
       await this.backend.set(SERVICE, `${sessionAccount}:access`, session.jwtAccess);
@@ -564,7 +603,11 @@ var KeyringStore = class _KeyringStore {
     blob.lastUsedAt = now.toISOString();
     await this.backend.set(SERVICE, sessionAccount, JSON.stringify(blob));
     const savedAt = parseDate(blob.savedAt) ?? now;
-    await this.tryUpsertLegacyIndex(serverKey, { email, savedAt, lastUsedAt: now });
+    await this.tryUpsertLegacyIndex(serverKey, {
+      email,
+      savedAt,
+      lastUsedAt: now
+    });
   }
   /**
    * Upserts one account into the legacy `__index__:<server>` entry via a
@@ -826,6 +869,9 @@ async function pollForToken(host, deviceCode, options = {}) {
   }
 }
 
+// src/auth/jwt.ts
+import { createHash } from "crypto";
+
 // src/auth/types.ts
 function jwtExpiringSoon(e, bufferMs) {
   if (!e.jwtExpiresAt) return true;
@@ -1040,7 +1086,11 @@ async function loginAs(host, operatorAccessToken, userId, options) {
       if (typeof parsed["detail"] === "string") detail = parsed["detail"];
     } catch {
     }
-    throw new LoginAsError(res.status, { code, detail, body: truncate(text3, TRUNCATE) });
+    throw new LoginAsError(res.status, {
+      code,
+      detail,
+      body: truncate(text3, TRUNCATE)
+    });
   }
   let raw;
   try {
@@ -1065,6 +1115,93 @@ async function loginAs(host, operatorAccessToken, userId, options) {
   }
   return { access, refresh, expiresAt, user: obj4["user"] };
 }
+async function exchangeApiKey(host, apiKey, options) {
+  const key = apiKey.trim();
+  if (key === "") {
+    throw new Error("api-key exchange: the stored API key is empty");
+  }
+  if (options?.opaque === true) {
+    if (/[\r\n\0]/.test(key) || !/^[\x00-\xff]+$/.test(key)) {
+      throw new Error(
+        "api-key exchange: the environment variable named by apiKeyEnvVar holds a value that cannot travel in an HTTP header (a line break, NUL, or a character above U+00FF)"
+      );
+    }
+  } else if (!/^[\x21-\x7e]+$/.test(key)) {
+    throw new Error(
+      "api-key exchange: only a printable-ASCII API key with no spaces is accepted; the stored one contains whitespace, control characters, or non-ASCII characters"
+    );
+  }
+  const base = trimTrailingSlash(host);
+  const res = await fetch(`${base}/jwt/api/apikey/token/`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${key}`, Accept: "application/json" },
+    signal: options?.signal
+  });
+  const text3 = await res.text();
+  if (!res.ok) {
+    let code;
+    try {
+      const value = JSON.parse(text3)["error"];
+      if (value === "invalid_key" || value === "exchange_unavailable") code = value;
+    } catch {
+    }
+    throw new Error(
+      `api-key exchange: HTTP ${res.status}${code !== void 0 ? ` (${code})` : ""}`
+    );
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text3);
+  } catch {
+    throw new Error("api-key exchange parse: the response is not JSON");
+  }
+  if (raw === null || typeof raw !== "object") {
+    throw new Error("api-key exchange parse: expected object");
+  }
+  const access = raw["access_token"];
+  if (typeof access !== "string" || access === "") {
+    throw new Error("api-key exchange: empty access token");
+  }
+  let expiresAt;
+  try {
+    expiresAt = decodeJwtExpiration(access);
+  } catch (err) {
+    throw new Error(`api-key exchange: ${msgOf3(err)}`);
+  }
+  return { access, expiresAt };
+}
+function apiKeyFingerprint(apiKey) {
+  return createHash("sha256").update(apiKey.trim()).digest("hex").slice(0, 32);
+}
+function resolveApiKeyMaterial(session) {
+  if (session.apiKey !== void 0 && session.apiKey !== "") {
+    return { key: session.apiKey, fromEnv: false };
+  }
+  const name = session.apiKeyEnvVar;
+  if (name === void 0 || name === "") {
+    throw new Error("api-key exchange: the session carries no API key");
+  }
+  const value = process.env[name];
+  if (value === void 0 || value === "") {
+    throw new Error(
+      `api-key exchange: the credential file names environment variable ${name} as the API-key carrier, but it is unset or empty in this environment`
+    );
+  }
+  return { key: value, fromEnv: true };
+}
+function mintedByStoredApiKey(session) {
+  if (session.jwtAccess === void 0 || session.jwtAccess === "") return false;
+  if (session.jwtApiKeyFingerprint === void 0 || session.jwtApiKeyFingerprint === "") {
+    return false;
+  }
+  let material;
+  try {
+    material = resolveApiKeyMaterial(session);
+  } catch {
+    return false;
+  }
+  return session.jwtApiKeyFingerprint === apiKeyFingerprint(material.key);
+}
 async function ensureValidJwt(store, serverKey, email, options) {
   return ensureJwt(store, serverKey, email, {
     buffer: options?.buffer ?? 0,
@@ -1086,6 +1223,10 @@ async function ensureJwt(store, serverKey, email, opts) {
   if (session === void 0) {
     throw new NotLoggedInError(`not logged in: ${serverKey}:${email}`);
   }
+  if (usesApiKey(session)) {
+    const host2 = opts.host ?? resolve(serverKey).host;
+    return exchangeKeyedSession(store, serverKey, email, session, host2, opts);
+  }
   if (!opts.force && session.jwtAccess !== void 0 && session.jwtAccess !== "" && !jwtExpiringSoon(session, opts.buffer)) {
     return session;
   }
@@ -1099,7 +1240,9 @@ async function ensureJwt(store, serverKey, email, opts) {
   if (session.jwtRefresh !== void 0 && session.jwtRefresh !== "" && host !== "") {
     try {
       const refresh = session.cookieless === true ? refreshExternalJwt : refreshJwt;
-      const tok = await refresh(host, session.jwtRefresh, { signal: opts.signal });
+      const tok = await refresh(host, session.jwtRefresh, {
+        signal: opts.signal
+      });
       refreshNext = {
         ...session,
         jwtAccess: tok.access,
@@ -1157,10 +1300,47 @@ async function ensureJwt(store, serverKey, email, opts) {
   const detail = reasons.length > 0 ? reasons.join("; ") : "no recovery path available";
   throw new SessionExpiredError(`${serverKey}:${email} (${detail})`);
 }
+async function exchangeKeyedSession(store, serverKey, email, session, host, opts) {
+  if (!opts.force && mintedByStoredApiKey(session) && !jwtExpiringSoon(session, opts.buffer)) {
+    return session;
+  }
+  if (host === "") {
+    throw new SessionExpiredError(
+      `${serverKey}:${email} (no host to exchange the API key against)`
+    );
+  }
+  const material = resolveApiKeyMaterial(session);
+  let tok;
+  try {
+    tok = await exchangeApiKey(host, material.key, {
+      signal: opts.signal,
+      opaque: material.fromEnv
+    });
+  } catch (err) {
+    throw new SessionExpiredError(`${serverKey}:${email} (${msgOf3(err)})`);
+  }
+  const next = {
+    ...session,
+    jwtAccess: tok.access,
+    jwtExpiresAt: tok.expiresAt,
+    jwtApiKeyFingerprint: apiKeyFingerprint(material.key),
+    // An API-key identity has no refresh token; clear any stale one so the
+    // refresh ladder is never tempted by it on a later non-keyed read.
+    jwtRefresh: void 0
+  };
+  try {
+    await store.saveSession(serverKey, next);
+  } catch (err) {
+    throw new Error(`save credentials: ${msgOf3(err)}`, { cause: err });
+  }
+  return next;
+}
 async function recoverImpersonatedJwt(store, serverKey, email, session, host, opts) {
   if (session.jwtRefresh !== void 0 && session.jwtRefresh !== "" && host !== "") {
     try {
-      const tok = await refreshExternalJwt(host, session.jwtRefresh, { signal: opts.signal });
+      const tok = await refreshExternalJwt(host, session.jwtRefresh, {
+        signal: opts.signal
+      });
       const next2 = {
         ...session,
         jwtAccess: tok.access,
@@ -1341,7 +1521,7 @@ var AuthorizedClient = class _AuthorizedClient {
     }
     const cookieless = session.cookieless === true;
     if (isCookielessSession(session)) {
-      if (session.jwtAccess === void 0 || session.jwtAccess === "") {
+      if (!usesApiKey(session) && (session.jwtAccess === void 0 || session.jwtAccess === "")) {
         throw new NotLoggedInError(
           cookieless ? `not logged in: ${serverKey}:${email} (cookie-less session has no JWT)` : `not logged in: ${serverKey}:${email} (impersonated session has no JWT; re-run dr-appspace login-as)`
         );
@@ -1845,7 +2025,7 @@ var AuthorizedClient = class _AuthorizedClient {
   async ensureFreshAuth(bufferMs, signal) {
     const access = this._session.jwtAccess ?? "";
     const refresh = this._session.jwtRefresh ?? "";
-    if (access === "" && refresh === "") {
+    if (access === "" && refresh === "" && !usesApiKey(this._session)) {
       return;
     }
     try {
@@ -1894,8 +2074,27 @@ import { z } from "zod";
 var CREDENTIALS_FILE_ENV = "DR_CREDENTIALS_FILE";
 var DEFAULT_CREDENTIALS_FILE = join3(homedir3(), ".dr", "session.json");
 var credentialsFileSchema = z.object({
-  access: z.string().min(1),
-  refresh: z.string().min(1),
+  access: z.string().min(1).optional(),
+  refresh: z.string().min(1).optional(),
+  // A user-bound API key, exchanged for `access` on demand. A file may hold
+  // only this; `access` then appears after the first exchange.
+  apiKey: z.string().min(1).optional(),
+  // DR-52657: the NAME of an environment variable holding the API key, for
+  // provisioners that must not put the key on disk — an agent sandbox, where
+  // the variable's in-sandbox value is an opaque vault placeholder, or a CI
+  // runner keeping the key in its secret env. Resolved at exchange time and
+  // passed verbatim. Mutually exclusive with `apiKey` (refinement below).
+  apiKeyEnvVar: z.string().min(1).optional(),
+  // Carried verbatim, judged where it is read. `z.string()` (not validated or
+  // `.catch`): a rotation rewrites the whole file from the parsed object, so a
+  // value this schema dropped would be deleted silently, and a top-level
+  // rejection would fail the WHOLE file and lock the operator out of logout.
+  apiKeyExpiresAt: z.string().optional(),
+  // Which key minted `access`, as a non-secret fingerprint. Written by the
+  // CLI, not a provisioner: a rotation replaces `apiKey` and leaves this
+  // naming the old one, which is how the next command knows `access` is not
+  // the new key's. `z.string()` for the same lock-out reason as above.
+  accessApiKeyFingerprint: z.string().optional(),
   server: z.string().min(1),
   email: z.string().min(1),
   // min(1): an empty string is how a hand-rolled producer spells "no cookie",
@@ -1911,7 +2110,19 @@ var credentialsFileSchema = z.object({
 }).loose().refine((c) => c.sessionId === void 0 === (c.csrfToken === void 0), {
   message: "sessionId and csrfToken must be provided together",
   path: ["sessionId"]
-});
+}).refine((c) => !(c.apiKey !== void 0 && c.apiKeyEnvVar !== void 0), {
+  message: "apiKey and apiKeyEnvVar are mutually exclusive",
+  path: ["apiKeyEnvVar"]
+}).refine((c) => c.access !== void 0 || c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0, {
+  message: "one of access, apiKey or apiKeyEnvVar is required",
+  path: ["access"]
+}).refine(
+  (c) => c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0 || c.refresh !== void 0 || c.sessionId !== void 0,
+  {
+    message: "refresh is required unless an apiKey, apiKeyEnvVar or a session cookie is present",
+    path: ["refresh"]
+  }
+);
 function credentialsFilePath() {
   const override = process.env[CREDENTIALS_FILE_ENV];
   return override !== void 0 && override !== "" ? override : DEFAULT_CREDENTIALS_FILE;
@@ -1924,8 +2135,14 @@ async function readCredentialsFile(path3) {
     if (err.code === "ENOENT") return void 0;
     throw err;
   }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`credential file ${path3} is not valid JSON`);
+  }
   try {
-    return credentialsFileSchema.parse(JSON.parse(raw));
+    return credentialsFileSchema.parse(parsed);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     throw new Error(`credential file ${path3} is malformed: ${reason}`, { cause: err });
@@ -1933,11 +2150,19 @@ async function readCredentialsFile(path3) {
 }
 async function writeCredentialsFile(path3, creds) {
   await mkdir(dirname2(path3), { recursive: true, mode: 448 });
-  const body = JSON.stringify(
-    { ...creds, savedAt: creds.savedAt ?? (/* @__PURE__ */ new Date()).toISOString() },
-    null,
-    2
-  );
+  let next;
+  try {
+    next = credentialsFileSchema.parse({
+      ...creds,
+      savedAt: creds.savedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`refusing to write an unreadable credential file ${path3}: ${reason}`, {
+      cause: err
+    });
+  }
+  const body = JSON.stringify(next, null, 2);
   const tmp = `${path3}.${process.pid}.tmp`;
   await writeFile(tmp, body, { mode: 384 });
   await chmod(tmp, 384);
@@ -1966,9 +2191,11 @@ var FileKeyringBackend = class _FileKeyringBackend {
     const savedAt = creds.savedAt ?? (/* @__PURE__ */ new Date()).toISOString();
     const sessionId = creds.sessionId ?? "";
     let jwtExpiresAt;
-    try {
-      jwtExpiresAt = decodeJwtExpiration(creds.access).toISOString();
-    } catch {
+    if (creds.access !== void 0 && creds.access !== "") {
+      try {
+        jwtExpiresAt = decodeJwtExpiration(creds.access).toISOString();
+      } catch {
+      }
     }
     return JSON.stringify({
       sessionId,
@@ -1976,7 +2203,19 @@ var FileKeyringBackend = class _FileKeyringBackend {
       savedAt,
       lastUsedAt: savedAt,
       ...sessionId === "" && { cookieless: true },
-      ...jwtExpiresAt !== void 0 && { jwtExpiresAt }
+      ...jwtExpiresAt !== void 0 && { jwtExpiresAt },
+      // Carry the API-key carrier through so `KeyringStore.getSession` sees a
+      // keyed identity and routes it to the exchange, plus the fingerprint of the
+      // key that minted the stored `access` so a reload can tell the cached JWT
+      // is still the current key's. Without it a file store would re-exchange on
+      // EVERY request — `ensureFreshAuth` reloads the session each time, and
+      // `mintedByStoredApiKey` can never match a fingerprint that was never
+      // written. `set('meta')` persists it back below.
+      ...creds.apiKey !== void 0 && creds.apiKey !== "" && { apiKey: creds.apiKey },
+      ...creds.apiKeyEnvVar !== void 0 && creds.apiKeyEnvVar !== "" && { apiKeyEnvVar: creds.apiKeyEnvVar },
+      ...creds.accessApiKeyFingerprint !== void 0 && creds.accessApiKeyFingerprint !== "" && {
+        jwtApiKeyFingerprint: creds.accessApiKeyFingerprint
+      }
     });
   }
   static slotOf(creds, account) {
@@ -2001,6 +2240,20 @@ var FileKeyringBackend = class _FileKeyringBackend {
       ...csrfToken !== "" && { csrfToken }
     };
   }
+  /**
+   * The key fingerprint out of a metadata blob (`KeyringStore` emits it as
+   * `jwtApiKeyFingerprint`), empty when absent. Unlike the cookie it is NOT
+   * derived, so it has to be persisted back to the file or every request
+   * re-exchanges.
+   */
+  static fingerprintOf(blob) {
+    try {
+      const parsed = JSON.parse(blob);
+      return typeof parsed.jwtApiKeyFingerprint === "string" ? parsed.jwtApiKeyFingerprint : "";
+    } catch {
+      return "";
+    }
+  }
   async get(_service, account) {
     const creds = await this.load();
     if (creds === void 0) return void 0;
@@ -2026,10 +2279,14 @@ var FileKeyringBackend = class _FileKeyringBackend {
     switch (_FileKeyringBackend.slotOf(creds, account)) {
       case "meta": {
         const cookie = _FileKeyringBackend.cookieOf(value);
-        if (cookie.sessionId === creds.sessionId && cookie.csrfToken === creds.csrfToken) {
+        const fingerprint = _FileKeyringBackend.fingerprintOf(value);
+        if (cookie.sessionId === creds.sessionId && cookie.csrfToken === creds.csrfToken && fingerprint === (creds.accessApiKeyFingerprint ?? "")) {
           return;
         }
-        await writeCredentialsFile(this.path, { ...creds, ...cookie });
+        const next = { ...creds, ...cookie };
+        if (fingerprint !== "") next.accessApiKeyFingerprint = fingerprint;
+        else delete next.accessApiKeyFingerprint;
+        await writeCredentialsFile(this.path, next);
         return;
       }
       case "access":
@@ -6605,6 +6862,10 @@ function partCalls(element) {
   for (const action of Array.isArray(typed.row_actions) ? typed.row_actions : []) {
     if (action && typeof action === "object" && named(action.call)) out.push(action.call);
   }
+  const bulk = typed.selection && typeof typed.selection === "object" ? typed.selection.bulk_actions : void 0;
+  for (const action of Array.isArray(bulk) ? bulk : []) {
+    if (action && typeof action === "object" && named(action.call)) out.push(action.call);
+  }
   for (const column of Array.isArray(typed.columns) ? typed.columns : []) {
     if (column && typeof column === "object" && column.cell === "toggle" && named(column.call)) out.push(column.call);
   }
@@ -7313,9 +7574,7 @@ function backendSection(app, manifest, pages, elements) {
       signature_ok: signatureOk(source),
       reads_ctx_role: CTX_ROLE.test(source),
       tables_touched: [...new Set([...source.matchAll(TABLE_CALL)].map((match) => match[2]))].sort(),
-      verbs: DATA_VERBS.filter(
-        (verb) => TABLE_ONLY_VERBS.has(verb) ? callsOnTable(source, verb) : new RegExp(`\\.\\s*${verb}\\s*\\(`).test(source)
-      ),
+      verbs: handlerVerbs(source),
       referenced_by_page: isReferenced(handler.name, scriptText) || attributed.has(handler.name)
     };
   }
@@ -7334,6 +7593,10 @@ function backendSection(app, manifest, pages, elements) {
     invariants: invariants(model, roles, handlers)
   };
 }
+function handlerVerbs(source) {
+  const text3 = typeof source === "string" ? source : "";
+  return DATA_VERBS.filter((verb) => TABLE_ONLY_VERBS.has(verb) ? callsOnTable(text3, verb) : new RegExp(`\\.\\s*${verb}\\s*\\(`).test(text3));
+}
 function callsOnTable(source, verb) {
   const holders = [TABLE_INLINE];
   for (const match of source.matchAll(TABLE_LOCAL)) holders.push(match[1]);
@@ -8810,7 +9073,7 @@ import { tmpdir as tmpdir2 } from "os";
 import { dirname as dirname3, join as join10 } from "path";
 
 // src/commands/appspace/generate/report.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { mkdir as mkdir3, readFile as readFile7, writeFile as writeFile4 } from "fs/promises";
 import { join as join9 } from "path";
 function reportPath(dir) {
@@ -8858,7 +9121,7 @@ async function ownedFiles(dir) {
   }
 }
 function digestOf(text3) {
-  return createHash("sha256").update(text3, "utf8").digest("hex");
+  return createHash2("sha256").update(text3, "utf8").digest("hex");
 }
 async function recordedDigests(dir) {
   try {
@@ -9124,7 +9387,7 @@ function registerGetCommand(parent) {
 
 // src/commands/appspace/generate/catalog.ts
 import { readFile as readFile9 } from "fs/promises";
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 var NO_CATALOG = {
   source: "none",
   metrics: [],
@@ -11041,6 +11304,9 @@ function payloadProducers(contract, { moduleSource = () => void 0, pageSource =
         for (const action of Array.isArray(typed.row_actions) ? typed.row_actions : []) {
           if (isPlainObject3(action) && named2(action.call)) add(action.call, { page, uid, what: "data_grid", keys: ["id", "row"] });
         }
+        for (const action of isPlainObject3(typed.selection) && Array.isArray(typed.selection.bulk_actions) ? typed.selection.bulk_actions : []) {
+          if (isPlainObject3(action) && named2(action.call)) add(action.call, { page, uid, what: "data_grid", keys: ["ids"] });
+        }
         for (const column of Array.isArray(typed.columns) ? typed.columns : []) {
           if (isPlainObject3(column) && column.cell === "toggle" && named2(column.call)) add(column.call, { page, uid, what: "data_grid", keys: ["id", "row", "field", "value"] });
         }
@@ -11835,6 +12101,11 @@ function stateCallers(contract, { moduleSource = () => void 0, handlerSource = (
           const asks = action.confirm === true || named3(action.confirm);
           add(action.call, { page, uid, id, what: `row action "${action.label ?? action.call}"`, asks });
         }
+        for (const action of isPlainObject4(typed.selection) && Array.isArray(typed.selection.bulk_actions) ? typed.selection.bulk_actions : []) {
+          if (!isPlainObject4(action) || !named3(action.call)) continue;
+          const asks = action.confirm === true || named3(action.confirm);
+          add(action.call, { page, uid, id, what: `bulk action "${action.label ?? action.call}"`, asks });
+        }
         break;
       case "action":
       case "detail": {
@@ -12164,13 +12435,18 @@ function isPlatformChartColour(n, value) {
 var look_exports = {};
 __export(look_exports, {
   HEADER_ACTION_TYPES: () => HEADER_ACTION_TYPES,
+  STATE_NAMES: () => STATE_NAMES,
+  folderParams: () => folderParams,
   headerActionProblems: () => headerActionProblems,
   humanise: () => humanise,
+  isAppContract: () => isAppContract,
+  kpiStripWorkflowProblems: () => kpiStripWorkflowProblems,
   layoutProblems: () => layoutProblems,
   lookPages: () => lookPages,
   navCountProblems: () => navCountProblems,
   railReachProblems: () => railReachProblems,
   rootsOf: () => rootsOf,
+  shellExpectedProblems: () => shellExpectedProblems,
   untitledCards: () => untitledCards
 });
 var isPlainObject5 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -12478,6 +12754,181 @@ function railReachProblems(contract) {
   }
   return out;
 }
+var STATE_NAMES = ["folder", "status", "stage", "state", "queue"];
+var CATCH_ALL = /* @__PURE__ */ new Set(["", "all", "any", "*", "everything"]);
+var PICK_KINDS = /* @__PURE__ */ new Set(["select", "multi"]);
+var ROW_TYPES = /* @__PURE__ */ new Set(["data_grid", "list", "queue"]);
+var NOT_COUNTS = ["sum", "avg", "avg_days", "count_events"];
+var VALUES_FIX = "state `app.shell` with `nav: rail` and one entry per value, counts from a `summary` handler; look.md rule 1";
+var PAGES_FIX = "state `app.shell` with `nav: rail`; with no `rail.entries` the rail lists the pages; look.md rule 1";
+var COUNTS_FIX = "state `app.shell` with `nav: rail` and one entry per state, each counting a measure of that summary (`pages[].nav.counts.source`); look.md rule 1";
+function isAppContract(contract) {
+  const kind = contract?.app?.kind;
+  return kind !== "dashboard" && (kind === "app" || isPlainObject5(contract?.data?.app));
+}
+function tablesOf(contract) {
+  const tables = contract?.app?.data_model?.tables;
+  return isPlainObject5(tables) ? tables : {};
+}
+function enumOf(column) {
+  return Array.isArray(column?.enum) ? column.enum.filter((one) => typeof one === "string") : [];
+}
+function stateColumn(contract, table) {
+  const columns = isPlainObject5(tablesOf(contract)[table]?.columns) ? tablesOf(contract)[table].columns : {};
+  return Object.keys(columns).find((name) => STATE_NAMES.includes(name) && enumOf(columns[name]).length >= 3) ?? null;
+}
+function realValues(param) {
+  return Array.isArray(param?.values) ? param.values.map(String).filter((value) => !CATCH_ALL.has(value.toLowerCase())) : [];
+}
+function ownPages(contract) {
+  return (Array.isArray(contract?.pages) ? contract.pages : []).filter((page) => page?.owned !== true && named4(page?.path));
+}
+function folderParams(contract) {
+  const enums = [];
+  for (const [table, spec] of Object.entries(tablesOf(contract))) {
+    const columns = isPlainObject5(spec?.columns) ? spec.columns : {};
+    for (const name of STATE_NAMES) if (enumOf(columns[name]).length >= 3) enums.push({ where: `${table}.${name}`, values: new Set(enumOf(columns[name])) });
+  }
+  const out = [];
+  for (const page of ownPages(contract)) {
+    for (const param of Array.isArray(page.params) ? page.params : []) {
+      if (!PICK_KINDS.has(param?.kind) || !named4(param?.name)) continue;
+      const values = realValues(param);
+      if (STATE_NAMES.includes(param.name) && (values.length >= 3 || !Array.isArray(param.values))) {
+        out.push({ page, param, values, why: `named "${param.name}"` });
+        continue;
+      }
+      if (values.length < 3) continue;
+      const match = enums.find((one) => values.every((value) => one.values.has(value)));
+      if (match !== void 0) out.push({ page, param, values, why: `its values are the enum of ${match.where}` });
+    }
+  }
+  return out;
+}
+function tableOf2(contract, element) {
+  const props = isPlainObject5(element?.props) ? element.props : {};
+  if (named4(props.entity)) return props.entity;
+  const source = props.source;
+  if (!named4(source)) return null;
+  const handler = contract?.data?.app?.handlers?.[source];
+  if (isPlainObject5(handler) && named4(handler.table)) return handler.table;
+  const read = contract?.data?.sources?.[source];
+  if (isPlainObject5(read?.from) && named4(read.from.table)) return read.from.table;
+  return null;
+}
+function listingOn(contract, page, test) {
+  const elements = isPlainObject5(contract?.elements) ? contract.elements : {};
+  for (const [uid, element] of Object.entries(elements)) {
+    if (element?.page !== page.path || !ROW_TYPES.has(element.type)) continue;
+    const table = tableOf2(contract, element);
+    if (table !== null && test(table)) return [uid, element, table];
+  }
+  return null;
+}
+function stateCountColumn(spec) {
+  if (!isPlainObject5(spec) || NOT_COUNTS.some((key) => spec[key] !== void 0)) return null;
+  const where2 = spec.count === true ? isPlainObject5(spec.where) ? spec.where : {} : spec.count === void 0 ? spec : null;
+  if (where2 === null) return null;
+  return Object.keys(where2).map((key) => key.split("__")[0]).find((column) => STATE_NAMES.includes(column)) ?? null;
+}
+function stateCounts(handler) {
+  const out = {};
+  for (const [measure, spec] of Object.entries(isPlainObject5(handler?.measures) ? handler.measures : {})) {
+    const column = stateCountColumn(spec);
+    if (column !== null) out[measure] = column;
+  }
+  return out;
+}
+function pageReads(contract, page, name) {
+  const elements = isPlainObject5(contract?.elements) ? contract.elements : {};
+  if (page?.nav?.counts?.source === name) return true;
+  return Object.values(elements).some((element) => element?.page === page.path && element.props?.source === name);
+}
+function shellExpectedProblems(contract) {
+  if (!isAppContract(contract)) return [];
+  const shell = isPlainObject5(contract?.app?.shell) ? contract.app.shell : {};
+  if (shell.nav === "rail") return [];
+  const out = [];
+  const say = (page, param, where2, message, fix) => out.push({ rule: "L8", code: "shell-expected", page, param, where: where2, message, fix });
+  const has = shell.nav === void 0 || shell.nav === null ? "states no app.shell" : `states app.shell.nav ${JSON.stringify(shell.nav)}`;
+  const pages = ownPages(contract);
+  if (pages.length > 4) say(null, null, "pages", `the app has ${pages.length} pages and ${has}, so its screens are a row of tabs too long to scan; an app this size is a rail`, PAGES_FIX);
+  const named_ = /* @__PURE__ */ new Set();
+  for (const { page, param, values, why } of folderParams(contract)) {
+    named_.add(page.path);
+    const listed = values.length > 0 ? ` with ${values.length} values (${values.map((one) => JSON.stringify(one)).join(", ")})` : " (its values from elsewhere)";
+    say(page.path, param.name, `${page.path} params.${param.name}`, `${page.path} declares ${param.kind} param "${param.name}" (${why})${listed} and the app ${has}, so its folders are a dropdown with no counts; they are the rail's entries`, VALUES_FIX);
+  }
+  const handlers = isPlainObject5(contract?.data?.app?.handlers) ? contract.data.app.handlers : {};
+  for (const [name, handler] of Object.entries(handlers)) {
+    if (handler?.role !== "summary" || !named4(handler.table)) continue;
+    const column = stateColumn(contract, handler.table);
+    const counts = Object.fromEntries(Object.entries(stateCounts(handler)).filter(([, by]) => by === column));
+    if (column === null || Object.keys(counts).length < 3) continue;
+    for (const page of pages) {
+      if (named_.has(page.path) || !pageReads(contract, page, name)) continue;
+      const listing = listingOn(contract, page, (table) => table === handler.table);
+      if (listing === null) continue;
+      const columns = [column];
+      say(
+        page.path,
+        null,
+        `${page.path} ${name}`,
+        `${page.path} reads the summary "${name}", whose measures count ${handler.table} by ${columns.join(", ")} (${Object.keys(counts).map((one) => JSON.stringify(one)).join(", ")}), beside ${nameOf3(listing[0], listing[1])} listing ${handler.table}, and the app ${has}: those counts are folders, and folders are the rail's entries`,
+        COUNTS_FIX
+      );
+    }
+  }
+  return out;
+}
+function kpiStripWorkflowProblems(contract) {
+  if (!isAppContract(contract)) return [];
+  const elements = isPlainObject5(contract?.elements) ? contract.elements : {};
+  const handlers = isPlainObject5(contract?.data?.app?.handlers) ? contract.data.app.handlers : {};
+  const folderPages = /* @__PURE__ */ new Map();
+  for (const { page, param } of folderParams(contract)) if (!folderPages.has(page.path)) folderPages.set(page.path, param.name);
+  const out = [];
+  for (const page of ownPages(contract)) {
+    const listing = listingOn(contract, page, (table) => stateColumn(contract, table) !== null);
+    const workflow = listing !== null ? `${nameOf3(listing[0], listing[1])} lists ${listing[2]}, whose ${stateColumn(contract, listing[2])} column is a set of states` : folderPages.has(page.path) ? `the page declares the folder-like param "${folderPages.get(page.path)}"` : null;
+    if (workflow === null) continue;
+    const banded = bandsOf(contract, page);
+    const inBand = new Set(banded.flatMap((band) => band.roots));
+    const loose = rootsOf(contract, page).filter((uid) => !inBand.has(uid));
+    for (const { section, roots } of [...banded, { section: null, roots: loose }]) {
+      const stats = roots.filter((uid) => elements[uid]?.type === "stat");
+      if (stats.length < 2) continue;
+      const bySource = /* @__PURE__ */ new Map();
+      for (const uid of stats) {
+        const source = elements[uid]?.props?.source;
+        if (!named4(source) || handlers[source]?.role !== "summary") continue;
+        if (!bySource.has(source)) bySource.set(source, []);
+        bySource.get(source).push(uid);
+      }
+      for (const [source, group] of bySource) {
+        if (group.length < 2) continue;
+        const measures = handlers[source].measures;
+        const known = isPlainObject5(measures) && group.every((uid) => Object.prototype.hasOwnProperty.call(measures, elements[uid]?.props?.measure));
+        const counts = stateCounts(handlers[source]);
+        if (known ? !group.every((uid) => counts[elements[uid].props.measure] !== void 0) : group.length !== stats.length) continue;
+        const where2 = section === null ? page.path : `band "${section.id}" on ${page.path}`;
+        const shape = section?.layout === "kpi_strip" ? "is a kpi_strip of" : "holds a row of";
+        const what = known ? `${group.length} counts of rows by ${[...new Set(group.map((uid) => counts[elements[uid].props.measure]))].join(", ")}` : `${group.length} counts`;
+        out.push({
+          rule: "L9",
+          code: "kpi-strip-on-workflow",
+          page: page.path,
+          section: section?.id ?? null,
+          where: where2,
+          message: `${where2} ${shape} ${what} from the summary "${source}", and ${workflow}: folder or state counts belong on the rail, not in a KPI strip (workflow.md \xA78)`,
+          fix: VALUES_FIX
+        });
+        break;
+      }
+    }
+  }
+  return out;
+}
 
 // ../flows/insights-builder/kit/contract/platformBadges.mjs
 var PLATFORM_BADGE_COLOURS = Object.freeze([
@@ -13629,8 +14080,9 @@ function compileApp(contract, { kit = null, runtime = RUNTIME, extra = {} } = {}
   const warnings = [...sourceFindings, ...widgetFindings].filter((one) => one.advisory).map(({ advisory: _advisory, ...one }) => one);
   problems.push(...widgetFindings.filter((one) => !one.advisory));
   if (tree.problems.length === 0) problems.push(...partProblems(declared, tree, handlers, sources, contract?.pages, model, { "dr-components": appComponents }));
-  if (tree.problems.length === 0) problems.push(...workflowProblems(declared, tree, handlers, sources, contract?.backend?.handlers, model));
-  const selectedFindings = tree.problems.length === 0 ? selectedProblems(declared, tree, handlers, sources, contract?.backend?.handlers, contract?.pages) : [];
+  const backendFacts = inferredBackendHandlers(contract?.backend?.handlers, handlers, extra);
+  if (tree.problems.length === 0) problems.push(...workflowProblems(declared, tree, handlers, sources, backendFacts, model));
+  const selectedFindings = tree.problems.length === 0 ? selectedProblems(declared, tree, handlers, sources, backendFacts, contract?.pages) : [];
   problems.push(...selectedFindings.filter((one) => !one.advisory));
   warnings.push(...selectedFindings.filter((one) => one.advisory).map(({ advisory: _advisory, ...one }) => one));
   if (problems.length > 0) return { files: {}, problems, contract, warnings };
@@ -14684,7 +15136,7 @@ function workflowProblems(elements, tree, handlers = {}, sources = {}, backendHa
     const say = (code, pointer2, message) => problems.push({ code, pointer: pointer2, message: `${type} "${props.id ?? uid}" ${message}` });
     const readsFrom = (source, pointer2, what) => {
       if (!stated(source)) say("part_source_shape", pointer2, `names no source; a ${type} reads ${what} from a reader \u2014 a ${either3(WORKFLOW_READERS)} handler, or a data.sources entry`);
-      else if (!reader(source)) say("part_source_shape", pointer2, `reads "${source}", which ${roleOf(source) === "custom" || roleOf(source) === void 0 ? `is no reader (a custom handler is one only when its backend.handlers verbs are all query, get or aggregate${Array.isArray(verbsOf(source)) ? `; it states ${JSON.stringify(verbsOf(source))}` : ""})` : `has role ${roleOf(source)}`}; a ${type} reads ${what} from a list, inbox, history or summary handler, a data.sources entry, or such a custom handler, and never calls a writer`);
+      else if (!reader(source)) say("part_source_shape", pointer2, `reads "${source}", which ${roleOf(source) === "custom" || roleOf(source) === void 0 ? `is no reader (a custom handler is one only when its verbs \u2014 stated in backend.handlers, else read off handlers/${source}.py, a guess you settle by stating them \u2014 are all query, get or aggregate${Array.isArray(verbsOf(source)) ? `; ${backendHandlers?.[source]?.inferred === true ? "its file reads as" : "it states"} ${JSON.stringify(verbsOf(source))}` : ""})` : `has role ${roleOf(source)}`}; a ${type} reads ${what} from a list, inbox, history or summary handler, a data.sources entry, or such a custom handler, and never calls a writer`);
     };
     if (type !== "split_pane" && typed.bind === "selected" && !bindReaches(uid)) {
       say("part_bind", `${at}/props/props/bind`, `binds the selected row where no row is ever picked for it: put it at the page root, in a root split_pane or panel, or inside a form or detail with bind: "selected"`);
@@ -14767,6 +15219,21 @@ function workflowProblems(elements, tree, handlers = {}, sources = {}, backendHa
   return problems;
 }
 var ROW_READERS = ["list", "inbox", "history", "summary"];
+function inferredBackendHandlers(stated2, handlers = {}, extra = {}) {
+  const out = isPlainObject6(stated2) ? { ...stated2 } : {};
+  for (const [name, row] of Object.entries(isPlainObject6(handlers) ? handlers : {})) {
+    if (row?.role !== "custom") continue;
+    if (isPlainObject6(out[name]) && Array.isArray(out[name].verbs)) continue;
+    const source = extra?.[`handlers/${name}.py`];
+    if (typeof source !== "string") continue;
+    const verbs = handlerVerbs(source);
+    const hidden = !verbs.some((verb) => INFER_WRITES.includes(verb)) && WRITE_ANYWHERE.test(source);
+    out[name] = { ...isPlainObject6(out[name]) ? out[name] : {}, verbs: hidden ? [...verbs, "update"] : verbs, inferred: true };
+  }
+  return out;
+}
+var INFER_WRITES = ["insert", "update", "delete"];
+var WRITE_ANYWHERE = /\.\s*(?:insert|update|delete)\s*\(/;
 var READ_VERBS = ["query", "get", "aggregate"];
 var ROOT_HOLDERS = ["panel", "split_pane"];
 var BOUND_TYPES = ["form", "detail"];
@@ -14858,7 +15325,7 @@ function selectedProblems(elements, tree, handlers = {}, sources = {}, backendHa
             "bind_source",
             uid,
             "/props/source",
-            `${element.type} "${nameOf5(uid)}" binds the selected row and reads it from "${source}", ${role !== void 0 && role !== "custom" ? `a ${role} handler` : "a custom handler whose backend.handlers verbs are not all reads"}; a pick would call a writer, so the runtime never calls it and draws an error \u2014 read through a list, inbox, history or summary handler, a data.sources entry, or a custom handler whose verbs are all query, get or aggregate`
+            `${element.type} "${nameOf5(uid)}" binds the selected row and reads it from "${source}", ${role !== void 0 && role !== "custom" ? `a ${role} handler` : `a custom handler whose verbs (${backendHandlers?.[source]?.inferred === true ? `read off handlers/${source}.py \u2014 state them in backend.handlers if that guess is wrong` : "stated in backend.handlers"}) are not all reads`}; a pick would call a writer, so the runtime never calls it and draws an error \u2014 read through a list, inbox, history or summary handler, a data.sources entry, or a custom handler whose verbs are all query, get or aggregate`
           );
         } else if (named5(props.entity) && named5(tableOfSource(source, handlers, sources)) && tableOfSource(source, handlers, sources) !== props.entity) {
           say("bind_source", uid, "/props/source", `${element.type} "${nameOf5(uid)}" is over "${props.entity}" and reads the selected row from "${source}", whose rows are "${tableOfSource(source, handlers, sources)}"; it would show (and a Save would post) another table's row \u2014 read the row from a reader over "${props.entity}"`);
@@ -19145,7 +19612,7 @@ function interpret(status, body, path3, contract) {
 }
 function fromRefusal(status, detail, contract) {
   const refused = `the push would be refused (${String(status)})`;
-  const tables = tablesOf(contract);
+  const tables = tablesOf2(contract);
   const conflicts = conflictTables(detail);
   if (conflicts !== void 0) {
     return conflicts.map(([table, owners]) => {
@@ -19229,7 +19696,7 @@ async function stage(dir, scratch, files) {
   }
   return null;
 }
-function tablesOf(contract) {
+function tablesOf2(contract) {
   const out = /* @__PURE__ */ new Map();
   const app = isObj3(contract) && isObj3(contract["app"]) ? contract["app"] : {};
   const model = isObj3(app["data_model"]) ? app["data_model"] : {};
@@ -22619,6 +23086,10 @@ function partCalls2(element) {
   for (const action of Array.isArray(typed.row_actions) ? typed.row_actions : []) {
     if (action && typeof action === "object" && named6(action.call)) out.push(action.call);
   }
+  const bulk = typed.selection && typeof typed.selection === "object" ? typed.selection.bulk_actions : void 0;
+  for (const action of Array.isArray(bulk) ? bulk : []) {
+    if (action && typeof action === "object" && named6(action.call)) out.push(action.call);
+  }
   for (const column of Array.isArray(typed.columns) ? typed.columns : []) {
     if (column && typeof column === "object" && column.cell === "toggle" && named6(column.call)) out.push(column.call);
   }
@@ -23327,9 +23798,7 @@ function backendSection2(app, manifest, pages, elements) {
       signature_ok: signatureOk2(source),
       reads_ctx_role: CTX_ROLE2.test(source),
       tables_touched: [...new Set([...source.matchAll(TABLE_CALL2)].map((match) => match[2]))].sort(),
-      verbs: DATA_VERBS2.filter(
-        (verb) => TABLE_ONLY_VERBS2.has(verb) ? callsOnTable2(source, verb) : new RegExp(`\\.\\s*${verb}\\s*\\(`).test(source)
-      ),
+      verbs: handlerVerbs2(source),
       referenced_by_page: isReferenced3(handler.name, scriptText) || attributed.has(handler.name)
     };
   }
@@ -23348,6 +23817,10 @@ function backendSection2(app, manifest, pages, elements) {
     invariants: invariants2(model, roles, handlers)
   };
 }
+function handlerVerbs2(source) {
+  const text3 = typeof source === "string" ? source : "";
+  return DATA_VERBS2.filter((verb) => TABLE_ONLY_VERBS2.has(verb) ? callsOnTable2(text3, verb) : new RegExp(`\\.\\s*${verb}\\s*\\(`).test(text3));
+}
 function callsOnTable2(source, verb) {
   const holders = [TABLE_INLINE2];
   for (const match of source.matchAll(TABLE_LOCAL2)) holders.push(match[1]);
@@ -24099,6 +24572,9 @@ function payloadProducers2(contract, { moduleSource = () => void 0, pageSource =
         for (const action of Array.isArray(typed.row_actions) ? typed.row_actions : []) {
           if (isPlainObject11(action) && named7(action.call)) add(action.call, { page, uid, what: "data_grid", keys: ["id", "row"] });
         }
+        for (const action of isPlainObject11(typed.selection) && Array.isArray(typed.selection.bulk_actions) ? typed.selection.bulk_actions : []) {
+          if (isPlainObject11(action) && named7(action.call)) add(action.call, { page, uid, what: "data_grid", keys: ["ids"] });
+        }
         for (const column of Array.isArray(typed.columns) ? typed.columns : []) {
           if (isPlainObject11(column) && column.cell === "toggle" && named7(column.call)) add(column.call, { page, uid, what: "data_grid", keys: ["id", "row", "field", "value"] });
         }
@@ -25194,6 +25670,181 @@ function railReachProblems2(contract) {
   }
   return out;
 }
+var STATE_NAMES2 = ["folder", "status", "stage", "state", "queue"];
+var CATCH_ALL2 = /* @__PURE__ */ new Set(["", "all", "any", "*", "everything"]);
+var PICK_KINDS2 = /* @__PURE__ */ new Set(["select", "multi"]);
+var ROW_TYPES2 = /* @__PURE__ */ new Set(["data_grid", "list", "queue"]);
+var NOT_COUNTS2 = ["sum", "avg", "avg_days", "count_events"];
+var VALUES_FIX2 = "state `app.shell` with `nav: rail` and one entry per value, counts from a `summary` handler; look.md rule 1";
+var PAGES_FIX2 = "state `app.shell` with `nav: rail`; with no `rail.entries` the rail lists the pages; look.md rule 1";
+var COUNTS_FIX2 = "state `app.shell` with `nav: rail` and one entry per state, each counting a measure of that summary (`pages[].nav.counts.source`); look.md rule 1";
+function isAppContract2(contract) {
+  const kind = contract?.app?.kind;
+  return kind !== "dashboard" && (kind === "app" || isPlainObject13(contract?.data?.app));
+}
+function tablesOf3(contract) {
+  const tables = contract?.app?.data_model?.tables;
+  return isPlainObject13(tables) ? tables : {};
+}
+function enumOf2(column) {
+  return Array.isArray(column?.enum) ? column.enum.filter((one) => typeof one === "string") : [];
+}
+function stateColumn2(contract, table) {
+  const columns = isPlainObject13(tablesOf3(contract)[table]?.columns) ? tablesOf3(contract)[table].columns : {};
+  return Object.keys(columns).find((name) => STATE_NAMES2.includes(name) && enumOf2(columns[name]).length >= 3) ?? null;
+}
+function realValues2(param) {
+  return Array.isArray(param?.values) ? param.values.map(String).filter((value) => !CATCH_ALL2.has(value.toLowerCase())) : [];
+}
+function ownPages2(contract) {
+  return (Array.isArray(contract?.pages) ? contract.pages : []).filter((page) => page?.owned !== true && named9(page?.path));
+}
+function folderParams2(contract) {
+  const enums = [];
+  for (const [table, spec] of Object.entries(tablesOf3(contract))) {
+    const columns = isPlainObject13(spec?.columns) ? spec.columns : {};
+    for (const name of STATE_NAMES2) if (enumOf2(columns[name]).length >= 3) enums.push({ where: `${table}.${name}`, values: new Set(enumOf2(columns[name])) });
+  }
+  const out = [];
+  for (const page of ownPages2(contract)) {
+    for (const param of Array.isArray(page.params) ? page.params : []) {
+      if (!PICK_KINDS2.has(param?.kind) || !named9(param?.name)) continue;
+      const values = realValues2(param);
+      if (STATE_NAMES2.includes(param.name) && (values.length >= 3 || !Array.isArray(param.values))) {
+        out.push({ page, param, values, why: `named "${param.name}"` });
+        continue;
+      }
+      if (values.length < 3) continue;
+      const match = enums.find((one) => values.every((value) => one.values.has(value)));
+      if (match !== void 0) out.push({ page, param, values, why: `its values are the enum of ${match.where}` });
+    }
+  }
+  return out;
+}
+function tableOf3(contract, element) {
+  const props = isPlainObject13(element?.props) ? element.props : {};
+  if (named9(props.entity)) return props.entity;
+  const source = props.source;
+  if (!named9(source)) return null;
+  const handler = contract?.data?.app?.handlers?.[source];
+  if (isPlainObject13(handler) && named9(handler.table)) return handler.table;
+  const read = contract?.data?.sources?.[source];
+  if (isPlainObject13(read?.from) && named9(read.from.table)) return read.from.table;
+  return null;
+}
+function listingOn2(contract, page, test) {
+  const elements = isPlainObject13(contract?.elements) ? contract.elements : {};
+  for (const [uid, element] of Object.entries(elements)) {
+    if (element?.page !== page.path || !ROW_TYPES2.has(element.type)) continue;
+    const table = tableOf3(contract, element);
+    if (table !== null && test(table)) return [uid, element, table];
+  }
+  return null;
+}
+function stateCountColumn2(spec) {
+  if (!isPlainObject13(spec) || NOT_COUNTS2.some((key) => spec[key] !== void 0)) return null;
+  const where2 = spec.count === true ? isPlainObject13(spec.where) ? spec.where : {} : spec.count === void 0 ? spec : null;
+  if (where2 === null) return null;
+  return Object.keys(where2).map((key) => key.split("__")[0]).find((column) => STATE_NAMES2.includes(column)) ?? null;
+}
+function stateCounts2(handler) {
+  const out = {};
+  for (const [measure, spec] of Object.entries(isPlainObject13(handler?.measures) ? handler.measures : {})) {
+    const column = stateCountColumn2(spec);
+    if (column !== null) out[measure] = column;
+  }
+  return out;
+}
+function pageReads2(contract, page, name) {
+  const elements = isPlainObject13(contract?.elements) ? contract.elements : {};
+  if (page?.nav?.counts?.source === name) return true;
+  return Object.values(elements).some((element) => element?.page === page.path && element.props?.source === name);
+}
+function shellExpectedProblems2(contract) {
+  if (!isAppContract2(contract)) return [];
+  const shell = isPlainObject13(contract?.app?.shell) ? contract.app.shell : {};
+  if (shell.nav === "rail") return [];
+  const out = [];
+  const say = (page, param, where2, message, fix) => out.push({ rule: "L8", code: "shell-expected", page, param, where: where2, message, fix });
+  const has = shell.nav === void 0 || shell.nav === null ? "states no app.shell" : `states app.shell.nav ${JSON.stringify(shell.nav)}`;
+  const pages = ownPages2(contract);
+  if (pages.length > 4) say(null, null, "pages", `the app has ${pages.length} pages and ${has}, so its screens are a row of tabs too long to scan; an app this size is a rail`, PAGES_FIX2);
+  const named_ = /* @__PURE__ */ new Set();
+  for (const { page, param, values, why } of folderParams2(contract)) {
+    named_.add(page.path);
+    const listed = values.length > 0 ? ` with ${values.length} values (${values.map((one) => JSON.stringify(one)).join(", ")})` : " (its values from elsewhere)";
+    say(page.path, param.name, `${page.path} params.${param.name}`, `${page.path} declares ${param.kind} param "${param.name}" (${why})${listed} and the app ${has}, so its folders are a dropdown with no counts; they are the rail's entries`, VALUES_FIX2);
+  }
+  const handlers = isPlainObject13(contract?.data?.app?.handlers) ? contract.data.app.handlers : {};
+  for (const [name, handler] of Object.entries(handlers)) {
+    if (handler?.role !== "summary" || !named9(handler.table)) continue;
+    const column = stateColumn2(contract, handler.table);
+    const counts = Object.fromEntries(Object.entries(stateCounts2(handler)).filter(([, by]) => by === column));
+    if (column === null || Object.keys(counts).length < 3) continue;
+    for (const page of pages) {
+      if (named_.has(page.path) || !pageReads2(contract, page, name)) continue;
+      const listing = listingOn2(contract, page, (table) => table === handler.table);
+      if (listing === null) continue;
+      const columns = [column];
+      say(
+        page.path,
+        null,
+        `${page.path} ${name}`,
+        `${page.path} reads the summary "${name}", whose measures count ${handler.table} by ${columns.join(", ")} (${Object.keys(counts).map((one) => JSON.stringify(one)).join(", ")}), beside ${nameOf4(listing[0], listing[1])} listing ${handler.table}, and the app ${has}: those counts are folders, and folders are the rail's entries`,
+        COUNTS_FIX2
+      );
+    }
+  }
+  return out;
+}
+function kpiStripWorkflowProblems2(contract) {
+  if (!isAppContract2(contract)) return [];
+  const elements = isPlainObject13(contract?.elements) ? contract.elements : {};
+  const handlers = isPlainObject13(contract?.data?.app?.handlers) ? contract.data.app.handlers : {};
+  const folderPages = /* @__PURE__ */ new Map();
+  for (const { page, param } of folderParams2(contract)) if (!folderPages.has(page.path)) folderPages.set(page.path, param.name);
+  const out = [];
+  for (const page of ownPages2(contract)) {
+    const listing = listingOn2(contract, page, (table) => stateColumn2(contract, table) !== null);
+    const workflow = listing !== null ? `${nameOf4(listing[0], listing[1])} lists ${listing[2]}, whose ${stateColumn2(contract, listing[2])} column is a set of states` : folderPages.has(page.path) ? `the page declares the folder-like param "${folderPages.get(page.path)}"` : null;
+    if (workflow === null) continue;
+    const banded = bandsOf3(contract, page);
+    const inBand = new Set(banded.flatMap((band) => band.roots));
+    const loose = rootsOf3(contract, page).filter((uid) => !inBand.has(uid));
+    for (const { section, roots } of [...banded, { section: null, roots: loose }]) {
+      const stats = roots.filter((uid) => elements[uid]?.type === "stat");
+      if (stats.length < 2) continue;
+      const bySource = /* @__PURE__ */ new Map();
+      for (const uid of stats) {
+        const source = elements[uid]?.props?.source;
+        if (!named9(source) || handlers[source]?.role !== "summary") continue;
+        if (!bySource.has(source)) bySource.set(source, []);
+        bySource.get(source).push(uid);
+      }
+      for (const [source, group] of bySource) {
+        if (group.length < 2) continue;
+        const measures = handlers[source].measures;
+        const known = isPlainObject13(measures) && group.every((uid) => Object.prototype.hasOwnProperty.call(measures, elements[uid]?.props?.measure));
+        const counts = stateCounts2(handlers[source]);
+        if (known ? !group.every((uid) => counts[elements[uid].props.measure] !== void 0) : group.length !== stats.length) continue;
+        const where2 = section === null ? page.path : `band "${section.id}" on ${page.path}`;
+        const shape = section?.layout === "kpi_strip" ? "is a kpi_strip of" : "holds a row of";
+        const what = known ? `${group.length} counts of rows by ${[...new Set(group.map((uid) => counts[elements[uid].props.measure]))].join(", ")}` : `${group.length} counts`;
+        out.push({
+          rule: "L9",
+          code: "kpi-strip-on-workflow",
+          page: page.path,
+          section: section?.id ?? null,
+          where: where2,
+          message: `${where2} ${shape} ${what} from the summary "${source}", and ${workflow}: folder or state counts belong on the rail, not in a KPI strip (workflow.md \xA78)`,
+          fix: VALUES_FIX2
+        });
+        break;
+      }
+    }
+  }
+  return out;
+}
 
 // ../flows/appspace-builder/kit/contract/platformPalette.mjs
 var PLATFORM_CHART2 = Object.freeze([
@@ -25415,7 +26066,7 @@ function rgbText2(parts) {
 
 // ../flows/appspace-builder/kit/checks/rules/look.mjs
 var THEME_FILE8 = "ui/theme.css";
-var RULES3 = ["L1", "L2", "L3", "L4", "L5", "L6", "L7"];
+var RULES3 = ["L1", "L2", "L3", "L4", "L5", "L6", "L7", "L8", "L9"];
 function checkLook(app, contract, contractError) {
   const view = {
     ...app,
@@ -25444,6 +26095,9 @@ function checkLook(app, contract, contractError) {
   for (const found of railReachProblems2(contract)) {
     violations.push({ rule: "L7", where: found.where, message: found.message });
   }
+  for (const found of [...shellExpectedProblems2(contract), ...kpiStripWorkflowProblems2(contract)]) {
+    violations.push({ rule: found.rule, where: found.where, message: `${found.code}: ${found.message}; ${found.fix}` });
+  }
   return { violations, skipped: [] };
 }
 
@@ -25628,7 +26282,7 @@ function checkUx(app, contract, contractError) {
     return out;
   };
   const nameOf5 = (uid) => said(elements[uid]?.props?.id) ?? said(elements[uid]?.id) ?? uid;
-  const tableOf2 = (el) => said(el?.props?.entity) ?? said(handlers[el?.props?.source]?.table);
+  const tableOf4 = (el) => said(el?.props?.entity) ?? said(handlers[el?.props?.source]?.table);
   const violations = [];
   for (const uid of uids) {
     const el = elements[uid];
@@ -25638,7 +26292,7 @@ function checkUx(app, contract, contractError) {
     if (!table || handlers[el.props?.action]?.role === "save") continue;
     const listing = uids.find((other) => {
       const o = elements[other];
-      return o?.page === el.page && ROWS.has(o.type) && tableOf2(o) === table && !ancestors(other).some((up) => up.type === "detail");
+      return o?.page === el.page && ROWS.has(o.type) && tableOf4(o) === table && !ancestors(other).some((up) => up.type === "detail");
     });
     if (!listing) continue;
     const label = said(el.props?.label) ?? "New";
@@ -25655,7 +26309,7 @@ function checkUx(app, contract, contractError) {
     const el = elements[uid];
     if (!ROWS.has(el?.type)) continue;
     if (ancestors(uid).some((up) => up.type === "detail")) continue;
-    const table = tableOf2(el);
+    const table = tableOf4(el);
     if (!table || table.startsWith("_") || !isPlainObject14(tables[table]?.columns) || tables[table].singleton === true) continue;
     const columns = tables[table].columns;
     const pk = Object.keys(columns).find((c) => isPlainObject14(columns[c]) && columns[c].pk === true) ?? "id";
@@ -25696,7 +26350,7 @@ function checkUx(app, contract, contractError) {
   for (const uid of uids) {
     const el = elements[uid];
     if (!ROWS.has(el?.type) || el.type === "data_grid") continue;
-    const table = tableOf2(el);
+    const table = tableOf4(el);
     const columns = isPlainObject14(tables[table]?.columns) ? tables[table].columns : {};
     const state = STATE_COLUMNS.find((c) => isPlainObject14(columns[c]) && Array.isArray(columns[c].enum));
     const seen = /* @__PURE__ */ new Map();
@@ -26012,6 +26666,11 @@ function stateCallers2(contract, { moduleSource = () => void 0, handlerSource =
           const asks = action.confirm === true || named10(action.confirm);
           add(action.call, { page, uid, id, what: `row action "${action.label ?? action.call}"`, asks });
         }
+        for (const action of isPlainObject15(typed.selection) && Array.isArray(typed.selection.bulk_actions) ? typed.selection.bulk_actions : []) {
+          if (!isPlainObject15(action) || !named10(action.call)) continue;
+          const asks = action.confirm === true || named10(action.confirm);
+          add(action.call, { page, uid, id, what: `bulk action "${action.label ?? action.call}"`, asks });
+        }
         break;
       case "action":
       case "detail": {
@@ -26305,7 +26964,7 @@ function kitFromDisk2() {
   }
   return kitOnDisk2;
 }
-var ADVISORY = /* @__PURE__ */ new Set(["L6", "L7", "A1.5", "A1.6", "A2.5", "A2.6", "A3.15", "A3.17", "A3.19", "A3.20", "A3.21", "A3.22", "A3.23", "A3.24", "A3.25", "A3.26", "A3.27", "A3.28", "A3.29"]);
+var ADVISORY = /* @__PURE__ */ new Set(["L6", "L7", "L8", "L9", "A1.5", "A1.6", "A2.5", "A2.6", "A3.15", "A3.17", "A3.19", "A3.20", "A3.21", "A3.22", "A3.23", "A3.24", "A3.25", "A3.26", "A3.27", "A3.28", "A3.29"]);
 function verify2({ app: appRef }, { extractContract: extractContract2 = extract2, kit } = {}) {
   const KIT = kit ?? kitFromDisk2();
   const app = loadApp2(resolve12(appRef.dir));
@@ -30634,7 +31293,7 @@ function auditedOf(model) {
   if (typeof tables !== "object" || tables === null) return [];
   return Object.keys(tables).filter((name) => tables[name]?.audit === true);
 }
-function tablesOf2(model) {
+function tablesOf4(model) {
   const tables = model?.tables;
   if (typeof tables !== "object" || tables === null) return {};
   const out = {};
@@ -30672,7 +31331,7 @@ function toRemove(rows2, { stage: stage2, cleanUp, keep, wrote = true }) {
   return rows2.filter((row) => row.recent);
 }
 async function sweepTestRows(client, appId, opts) {
-  const tables = tablesOf2(opts.model);
+  const tables = tablesOf4(opts.model);
   if (Object.keys(tables).length === 0) {
     return { checked: false, why: "the app has no tables", left: [], removed: [], errors: [], truncated: [] };
   }
@@ -30930,7 +31589,7 @@ function pushedContract(bundle, pages) {
   }
   return null;
 }
-function isAppContract(contract) {
+function isAppContract3(contract) {
   return contract.app?.kind !== "dashboard" && typeof contract.data?.app === "object";
 }
 var COMPONENTS2 = /* @__PURE__ */ new Set(["form", "list", "detail", "queue", "action", "filter", "stat", "chart", "custom", "widget"]);
@@ -30959,7 +31618,7 @@ function sectionOf3(element) {
   return typeof raw === "string" && raw !== "" ? raw : void 0;
 }
 function contractFindings(contract) {
-  if (!isAppContract(contract)) return [];
+  if (!isAppContract3(contract)) return [];
   const pages = contract.pages ?? [];
   const elements = contract.elements ?? {};
   const out = [];
@@ -31024,7 +31683,7 @@ function contractFindings(contract) {
   return out;
 }
 function auditFindings(contract) {
-  if (!isAppContract(contract)) return [];
+  if (!isAppContract3(contract)) return [];
   const tables = contract.app?.data_model?.tables ?? {};
   const handlers = contract.data?.app?.handlers ?? {};
   const elements = contract.elements ?? {};
@@ -31153,7 +31812,7 @@ function renderFindings(runs, contract, seed) {
   return out;
 }
 function chartFindings(runs, contract, seed) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const handlers = contract.data?.app?.handlers ?? {};
   const out = [];
   const said2 = /* @__PURE__ */ new Set();
@@ -31249,7 +31908,7 @@ function mapDecisions(handler) {
   return Object.keys(decision).sort();
 }
 function refusalFindings(runs, contract) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const handlers = contract.data?.app?.handlers ?? {};
   const byButton = /* @__PURE__ */ new Map();
   for (const run of runs) {
@@ -31645,7 +32304,7 @@ function partsSummary(contract, bundle, handlerCode) {
     custom_handler_lines: customHandlerLines,
     custom_share: components === 0 ? 0 : Math.round(customUi / components * 100)
   };
-  if (isAppContract(contract)) {
+  if (isAppContract3(contract)) {
     const files = transformFiles2(contract, handlerCode);
     let lines = 0;
     for (const text3 of files.values()) if (text3 !== void 0) lines += nonBlankLinesOf(text3);
@@ -31671,7 +32330,7 @@ function pushedFiles(bundle, handlerCode) {
   };
 }
 function payloadFindings(contract, bundle, handlerCode) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   return DECLARES.unproducedPayloadKeys(contract, pushedFiles(bundle, handlerCode)).map((found) => ({
     code: "payload-key-unproduced",
     where: `${found.pages.join(", ")} \u2192 ${found.handler}`,
@@ -31681,7 +32340,7 @@ function payloadFindings(contract, bundle, handlerCode) {
   }));
 }
 function leverFindings(contract, bundle, handlerCode) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const files = pushedFiles(bundle, handlerCode);
   const finding = (code) => (found) => ({
     code,
@@ -31696,7 +32355,7 @@ function leverFindings(contract, bundle, handlerCode) {
   ];
 }
 function workflowFindings(contract, bundle, handlerCode) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const files = pushedFiles(bundle, handlerCode);
   return [
     // A role that opens the app on a 404: counted, like the unreachable page
@@ -31755,7 +32414,7 @@ function shown(value) {
   return typeof value === "number" || typeof value === "boolean" || typeof value === "string" ? String(value) : JSON.stringify(value);
 }
 function leverStaticFindings(runs, contract, unread = /* @__PURE__ */ new Set()) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const sources = contract.data?.sources ?? {};
   const out = [];
   const seen = /* @__PURE__ */ new Set();
@@ -31853,7 +32512,7 @@ function declaresOf(element) {
   return { calls, shows };
 }
 function customDeclaresFindings(contract, bundle, runs) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const out = [];
   const said2 = /* @__PURE__ */ new Set();
   const undeclared = (uid, page, module, handler, problem5, fix) => {
@@ -31906,7 +32565,7 @@ function customDeclaresFindings(contract, bundle, runs) {
   return out;
 }
 function roleFindings(contract, held) {
-  if (held.own === null || !isAppContract(contract)) return [];
+  if (held.own === null || !isAppContract3(contract)) return [];
   const elements = contract.elements ?? {};
   const parentOf2 = /* @__PURE__ */ new Map();
   for (const [uid, element] of Object.entries(elements)) {
@@ -31951,7 +32610,7 @@ function roleFindings(contract, held) {
   ];
 }
 function cardTitleFindings(contract) {
-  if (!isAppContract(contract)) return [];
+  if (!isAppContract3(contract)) return [];
   return LOOK.untitledCards(contract).map((found) => ({
     code: "card-untitled",
     where: `${found.page} \u2192 ${found.uid}`,
@@ -31960,8 +32619,19 @@ function cardTitleFindings(contract) {
     see: SEE.labels
   }));
 }
+function shellFindings(contract) {
+  if (contract === null) return [];
+  return [...LOOK.shellExpectedProblems(contract), ...LOOK.kpiStripWorkflowProblems(contract)].map((found) => ({
+    code: found.code,
+    where: found.where,
+    message: found.message,
+    fix: `${found.fix.charAt(0).toUpperCase()}${found.fix.slice(1)}.`,
+    see: `App kit ${found.rule} (contract/look.mjs)`,
+    severity: "warning"
+  }));
+}
 function uxFindings(contract) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const codes = {
     "A3.23": "create-form-inline",
     "A3.24": "row-no-detail",
@@ -32006,7 +32676,8 @@ function collectFindings(input) {
     ...input.declared === null ? [] : unreachedFindings(input.declared, input.cases, input.contract, input.runs),
     // Last: said and never counted, so they never push a counted finding down the list.
     ...workflow.filter((one) => one.severity === "warning"),
-    ...uxFindings(input.contract)
+    ...uxFindings(input.contract),
+    ...shellFindings(input.contract)
   ];
 }
 function formatFindings(findings) {
@@ -32426,7 +33097,7 @@ function shownValue(value) {
   return typeof value === "number" || typeof value === "boolean" || typeof value === "string" ? String(value) : JSON.stringify(value);
 }
 function paramsOf3(contract, page) {
-  if (contract === null || !isAppContract(contract)) return [];
+  if (contract === null || !isAppContract3(contract)) return [];
   const found = (contract?.pages ?? []).find((one) => one.path === page && one.owned !== true);
   return Array.isArray(found?.params) ? found.params : [];
 }
@@ -32478,7 +33149,7 @@ function leversNotChecked(skipUi, runs, contract) {
     }
   }
   const loaded = new Set(runs.map((run) => `ui/${run.entry}`));
-  if (contract === null || !isAppContract(contract)) return out;
+  if (contract === null || !isAppContract3(contract)) return out;
   for (const page of contract.pages ?? []) {
     if (page.owned === true || !Array.isArray(page.params) || page.params.length === 0) continue;
     if (judged.has(page.path) || !loaded.has(page.path)) continue;

package/package.json

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