@datarails-ai/dr-appspace-cli 0.12.0 → 0.12.2

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.0",
+  version: "0.12.2",
   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-07T17:05:49.665Z";
+var BUILD_TIME = "2026-10-08T08:05:29.934Z";
 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":
@@ -8810,7 +9067,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 +9115,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 +9381,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: [],
@@ -17549,6 +17806,7 @@ function validateContract(contract, catalog) {
   if (kind === "dashboard") {
     checkPeriodOverride(doc, problems);
     checkKinds(doc, problems);
+    checkDrillTargets(doc, problems);
     checkPairing(doc, problems);
     checkTransforms(doc, problems);
   } else {
@@ -18030,6 +18288,19 @@ function checkSources(doc, catalog, problems, skipped) {
       }
       report(held, ["data", "widgets", id, "source", key]);
     }
+    {
+      const held = source["period_field"];
+      const field = isObject4(held) ? held["field"] : held;
+      const epoch = isObject4(held) && held["format"] === "epoch";
+      if (typeof field === "string" && dated.has(field.toLowerCase()) && source["period_is_date"] !== true && !epoch) {
+        problems.push({
+          code: "period-needs-date",
+          pointer: pointer("data", "widgets", id, "source", "period_field"),
+          message: `${JSON.stringify(field)} is a date column, and this source does not say so \u2014 its window is not sent to FinanceOS, a drill reads rows from every period, and a clicked chart point matches no row.`,
+          fix: `Add "period_is_date": true to the source (next to period_field ${JSON.stringify(field)}); the page's window is then pushed down as Unix epoch seconds, with no "where" range needed.`
+        });
+      }
+    }
     for (const key of ["select", "dimensions", "measures"]) {
       for (const [index, name] of list2(source[key]).entries()) {
         if (isObject4(name)) {
@@ -18361,6 +18632,40 @@ function checkKinds(doc, problems) {
     });
   }
 }
+function checkDrillTargets(doc, problems) {
+  const widgets = obj(obj(doc["data"])["widgets"]);
+  for (const [id, raw] of Object.entries(widgets)) {
+    if (id.startsWith("_") || !isObject4(raw)) continue;
+    const row = raw;
+    if (row["data"] !== void 0 && row["data"] !== null) continue;
+    const drill = list2(row["drill"]).filter((name) => typeof name === "string");
+    if (drill.length === 0) continue;
+    const offered = new Set(drill.map((name) => name.toLowerCase()));
+    const listed = JSON.stringify(drill);
+    if (row["kind"] === "breakdown") {
+      const dimension = row["dimension"];
+      if (typeof dimension !== "string" || dimension === "") continue;
+      if (offered.has(dimension.toLowerCase())) continue;
+      problems.push({
+        code: "drill-needs-dimension",
+        pointer: pointer("data", "widgets", id, "drill"),
+        message: `this breakdown is cut by ${JSON.stringify(dimension)} and its drill list ${listed} does not name it, so no legend row answers a click \u2014 the card looks drillable and is not.`,
+        fix: `Put ${JSON.stringify(dimension)} first in drill \u2014 ${JSON.stringify([dimension, ...drill])}: the clicked slice is a value of the card's own dimension, and the levels after it are where the grid goes next.`
+      });
+      continue;
+    }
+    if (row["kind"] !== "table") continue;
+    const declared = list2(row["columns"]).map((column) => isObject4(column) ? column["key"] : void 0).filter((key) => typeof key === "string" && key !== "");
+    const keys2 = declared.length > 0 ? declared : list2(obj(row["source"])["dimensions"]).filter((key) => typeof key === "string");
+    if (keys2.length === 0 || keys2.some((key) => offered.has(key.toLowerCase()))) continue;
+    problems.push({
+      code: "drill-needs-dimension",
+      pointer: pointer("data", "widgets", id, "drill"),
+      message: `this table's drill list ${listed} names none of its columns (${keys2.map((key) => JSON.stringify(key)).join(", ")}), and a cell drills only when its column key is in drill \u2014 so no cell answers a click.`,
+      fix: `Add the column a reader clicks to drill \u2014 e.g. ${JSON.stringify([keys2[0], ...drill])} \u2014 naming the grid's own dimension column first.`
+    });
+  }
+}
 function checkPairing(doc, problems) {
   const data = doc["data"];
   if (!isObject4(data) || !isObject4(data["widgets"])) return;

package/package.json

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