@dashai/cli 0.25.0 → 0.26.0

package/dist/bin.js

@@ -828,6 +828,74 @@ var init_connect_status = __esm({
     SETUP_SETTINGS_PATH = "Modules \u2192 Installed modules \u2192 Technical \u2192 Data connections";
   }
 });
+function declaredSecretNames(manifest) {
+  const names = [];
+  for (const s of manifest?.runtime?.secrets ?? []) {
+    if (typeof s?.key === "string" && SECRET_KEY.test(s.key) && !names.includes(s.key)) {
+      names.push(s.key);
+    }
+  }
+  return names;
+}
+function envLocalSetNames(projectRoot) {
+  const set = /* @__PURE__ */ new Set();
+  const path = join(projectRoot, ".env.local");
+  if (!existsSync(path)) return set;
+  for (const line of readFileSync(path, "utf-8").split(/\r?\n/)) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const value = m[2].trim().replace(/^(['"])(.*)\1$/, "$2");
+    if (value.length > 0) set.add(m[1]);
+  }
+  return set;
+}
+function missingSecretNames(declared, env, envLocal2) {
+  return declared.filter((k) => !(env[k] !== void 0 && env[k] !== "") && !envLocal2.has(k));
+}
+function secretsBannerLine(declared, missing) {
+  if (declared.length === 0) return null;
+  if (missing.length === 0) return `${declared.length} declared, all set`;
+  return `${declared.length} declared, ${missing.length} missing: ${missing.join(", ")} (add ${missing.length === 1 ? "it" : "them"} to .env.local)`;
+}
+function withSecretLines(content, names) {
+  const mentioned = (k) => new RegExp(`^\\s*#?\\s*(?:export\\s+)?${k}\\s*=`, "m").test(content);
+  const add = names.filter((k) => !mentioned(k));
+  if (add.length === 0) return content;
+  const hasHeader = content.includes(ENV_LOCAL_SECRETS_HEADER[0]);
+  const block = [...hasHeader ? [] : ENV_LOCAL_SECRETS_HEADER, ...add.map((k) => `# ${k}=`)].join("\n");
+  const base = content.length === 0 || content.endsWith("\n") ? content : `${content}
+`;
+  return `${base}${base.length > 0 && !hasHeader ? "\n" : ""}${block}
+`;
+}
+function syncEnvLocalSecretLines(projectRoot, names) {
+  if (names.length === 0) return [];
+  const path = join(projectRoot, ".env.local");
+  const before = existsSync(path) ? readFileSync(path, "utf-8") : "";
+  const after = withSecretLines(before, names);
+  if (after === before) return [];
+  writeFileSync(path, after, "utf-8");
+  return names.filter((k) => !new RegExp(`^\\s*#?\\s*(?:export\\s+)?${k}\\s*=`, "m").test(before));
+}
+function reportSecretLines(added) {
+  if (added.length === 0) return;
+  info(
+    `Added ${added.map((k) => code(`# ${k}=`)).join(", ")} to ${code(".env.local")}: set dev values there. Hosted modules do not receive declared secrets yet.`
+  );
+}
+var SECRET_KEY, ENV_LOCAL_SECRETS_HEADER;
+var init_declared_secrets = __esm({
+  "src/lib/declared-secrets.ts"() {
+    init_output();
+    SECRET_KEY = /^[A-Z][A-Z0-9_]*$/;
+    ENV_LOCAL_SECRETS_HEADER = [
+      "# Declared runtime secrets (module.json runtime.secrets[]). Set a dev value",
+      "# after the `=` and remove the `#`; `dashwise dev` names any that are missing.",
+      "# Hosted modules do not receive declared secrets yet (platform item U1);",
+      "# locally `dashwise dev` runs `next dev`, which reads them from this file."
+    ];
+  }
+});
 function manifestPath(dir) {
   return join(resolve(dir ?? process.cwd()), "module.json");
 }
@@ -1172,6 +1240,12 @@ async function devCommand(options) {
   (Ensure you're logged into the right backend: ${code(`dashwise login --api-url ${apiUrl}`)}.)`
     );
   }
+  {
+    const declared = declaredSecretNames(readManifest(projectRoot));
+    const missing = missingSecretNames(declared, childEnv, envLocalSetNames(projectRoot));
+    const line = secretsBannerLine(declared, missing);
+    if (line !== null) (missing.length > 0 ? warn : info)(`  ${dim("secrets")}     ${line}`);
+  }
   info("");
   if (moduleEntry !== null && manifestSlug !== void 0) {
     await reportConnectStatus({
@@ -1412,13 +1486,13 @@ async function resolveDevPort(requested) {
 }
 async function isPortFree(port) {
   const { createServer } = await import('net');
-  return new Promise((resolve15) => {
+  return new Promise((resolve16) => {
     const server = createServer();
     server.once("error", () => {
-      resolve15(false);
+      resolve16(false);
     });
     server.once("listening", () => {
-      server.close(() => resolve15(true));
+      server.close(() => resolve16(true));
     });
     server.listen(port, "0.0.0.0");
   });
@@ -1486,6 +1560,7 @@ var init_dev = __esm({
     init_api_client();
     init_connect_status();
     init_config();
+    init_declared_secrets();
     init_manifest_io();
     init_manifest_poll();
     init_output();
@@ -12595,9 +12670,14 @@ dashwise module destroy-dev-install  # tear down when done (cleans backend + aut
 - **No untyped \`any\`.** The generated SDK gives you types \u2014 use
   them. If you need an escape hatch, add a \`@ts-expect-error\` with
   a comment explaining why.
-- **No secrets in code or env files.** Use \`runtime.secrets[]\` in
-  \`module.json\`; values are encrypted at rest and resolved at
-  runtime.
+- **No secrets in code or committed env files.** Declare each one in
+  \`runtime.secrets[]\` in \`module.json\` (by name; values never go in the
+  repo). Hosted modules do not receive declared secrets yet (platform item
+  U1): until that lands, a hosted module cannot read them. Locally, put dev
+  values in the gitignored \`.env.local\` (\`dashwise init\` and
+  \`dashwise module generate\` add a commented \`# KEY=\` line per declared
+  secret); \`dashwise dev\` runs \`next dev\`, which loads them, and names
+  any that are missing.
 
 ## Pointers
 
@@ -13468,6 +13548,9 @@ async function moduleInitCommand(slugArg, options) {
       writeFileSync(absPath, content, "utf-8");
       written++;
     }
+    reportSecretLines(
+      syncEnvLocalSecretLines(dir, declaredSecretNames(readManifest(dir)))
+    );
   }
   if (writeMode !== "none" && !cloudReady) {
     process.stdout.write(
@@ -13710,10 +13793,297 @@ var init_init = __esm({
     init_output();
     init_api_client();
     init_config();
+    init_declared_secrets();
     init_manifest_io();
     init_workspaces();
   }
 });
+
+// src/lib/manifest-evolution.ts
+function compareManifests(base, head, history = []) {
+  const violations = [];
+  const additions = [];
+  const warnings = [];
+  const v = (rule, where, detail) => violations.push({ rule, where, detail });
+  const baseTables = tablesOf(base);
+  const headTables = tablesOf(head);
+  const everTables = /* @__PURE__ */ new Set();
+  const everFields = /* @__PURE__ */ new Set();
+  for (const m of history) {
+    for (const [slug, t] of tablesOf(m)) {
+      everTables.add(slug);
+      for (const f of t.fields ?? []) everFields.add(`${slug}.${f.slug}`);
+    }
+  }
+  for (const [slug, bt] of baseTables) {
+    const ht = headTables.get(slug);
+    if (!ht) {
+      v("removed_table", slug, "tables are never removed; deprecate instead");
+      continue;
+    }
+    const bf = fieldsOf(bt);
+    const hf = fieldsOf(ht);
+    for (const [fs, f] of bf) {
+      const g = hf.get(fs);
+      const where = `${slug}.${fs}`;
+      if (!g) {
+        v("removed_field", where, "fields are never removed; stop writing it and set human_edit: open");
+        continue;
+      }
+      if (f.type !== g.type) v("retyped_field", where, `${f.type} \u2192 ${g.type}`);
+      if ((f.decimal_places ?? null) !== (g.decimal_places ?? null)) {
+        v("retyped_field", where, `decimal_places ${f.decimal_places ?? "none"} \u2192 ${g.decimal_places ?? "none"}`);
+      }
+      if ((f.target ?? null) !== (g.target ?? null)) v("retyped_field", where, `link target ${f.target} \u2192 ${g.target}`);
+      if (f.required !== true && g.required === true) {
+        v("required_tightened", where, "old rows are empty; enforce it in the tool layer instead");
+      }
+      const bo = f.options ?? [];
+      const ho = g.options ?? [];
+      for (const [i, o] of bo.entries()) {
+        if (!ho.includes(o)) v("removed_option", where, `option "${String(o)}" removed`);
+        else if (ho[i] !== o) {
+          v("reordered_option", where, `option "${String(o)}" moved from ${i} to ${ho.indexOf(o)}; options are append-only`);
+        }
+      }
+      for (const o of ho.slice(bo.length)) if (!bo.includes(o)) additions.push(`option ${where} "${String(o)}"`);
+    }
+    for (const [fs] of hf) {
+      if (bf.has(fs)) continue;
+      if (everFields.has(`${slug}.${fs}`)) {
+        v("slug_reused", `${slug}.${fs}`, "this slug was removed in an earlier version and may not come back");
+      } else additions.push(`field ${slug}.${fs}`);
+    }
+    const hu = new Set(uniqueIndexes(ht));
+    for (const idx of uniqueIndexes(bt)) {
+      if (!hu.has(idx)) v("dropped_unique_index", `${slug}(${idx})`, "a unique index is a protocol lock; it may not be dropped or changed");
+    }
+    const bu = new Set(uniqueIndexes(bt));
+    for (const idx of hu) {
+      if (bu.has(idx)) continue;
+      const overExisting = idx.split(",").some((f) => f.length > 0 && bf.has(f));
+      if (overExisting) {
+        v("unique_on_populated", `${slug}(${idx})`, "a new unique index (indexes[].unique) over existing fields fails on duplicates already stored; add a new field instead");
+      } else additions.push(`unique index ${slug}(${idx})`);
+    }
+  }
+  for (const [slug] of headTables) {
+    if (baseTables.has(slug)) continue;
+    if (everTables.has(slug)) v("slug_reused", slug, "this table slug was removed in an earlier version and may not come back");
+    else additions.push(`table ${slug}`);
+  }
+  const baseViews = new Set((base?.owns?.views ?? []).map((x) => x.slug));
+  const headViews = new Set((head?.owns?.views ?? []).map((x) => x.slug));
+  for (const s of baseViews) if (!headViews.has(s)) warnings.push(`view ${s} removed (callers of qbViews.${s} break)`);
+  for (const s of headViews) if (!baseViews.has(s)) additions.push(`view ${s}`);
+  return { violations, additions, warnings };
+}
+var tablesOf, fieldsOf, uniqueIndexes;
+var init_manifest_evolution = __esm({
+  "src/lib/manifest-evolution.ts"() {
+    tablesOf = (m) => new Map((m?.owns?.tables ?? []).map((t) => [t.slug, t]));
+    fieldsOf = (t) => new Map((t?.fields ?? []).map((f) => [f.slug, f]));
+    uniqueIndexes = (t) => (t?.indexes ?? []).filter((i) => i.unique === true).map((i) => (i.fields ?? []).join(","));
+  }
+});
+
+// src/commands/module/diff-check.ts
+var diff_check_exports = {};
+__export(diff_check_exports, {
+  EvolutionCheckError: () => EvolutionCheckError,
+  moduleDiffCheckCommand: () => moduleDiffCheckCommand,
+  printEvolutionReport: () => printEvolutionReport,
+  publishEvolutionGate: () => publishEvolutionGate,
+  runEvolutionCheck: () => runEvolutionCheck
+});
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new EvolutionCheckError(`could not read ${path}: ${err.message}`);
+  }
+}
+function git(cwd, args) {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 64 * 1024 * 1024
+    });
+  } catch (err) {
+    const stderr = err.stderr?.trim();
+    throw new EvolutionCheckError(`git ${args.join(" ")} failed${stderr ? `: ${stderr}` : ""}`);
+  }
+}
+async function runEvolutionCheck(options) {
+  const projectRoot = resolve(options.dir ?? process.cwd());
+  const headPath = options.head ? resolve(options.head) : join(projectRoot, "module.json");
+  if (!existsSync(headPath)) throw new EvolutionCheckError(`no manifest at ${headPath}`);
+  const head = readJson(headPath);
+  const baseFile = options.baseFile ?? (options.base && existsSync(options.base) ? options.base : void 0);
+  if (baseFile) {
+    const base = readJson(baseFile);
+    return { ...compareManifests(base, head), base: baseFile, head: headPath, history: 0, nothingReleased: false };
+  }
+  if (options.base) {
+    const ref = options.base;
+    const base = JSON.parse(git(projectRoot, ["show", `${ref}:./module.json`]));
+    let history2 = [];
+    if (!options.noHistory) {
+      const shas = git(projectRoot, ["log", "--format=%H", "--reverse", ref, "--", "module.json"]).split("\n").filter(Boolean);
+      history2 = shas.slice(0, -1).map((sha) => JSON.parse(git(projectRoot, ["show", `${sha}:./module.json`])));
+    }
+    return {
+      ...compareManifests(base, head, history2),
+      base: `${ref}:module.json`,
+      head: headPath,
+      history: history2.length,
+      nothingReleased: false
+    };
+  }
+  const slug = head.module?.slug;
+  if (!slug) throw new EvolutionCheckError(`${headPath} has no module.slug`);
+  let mod;
+  let versions;
+  try {
+    mod = await apiRequest(
+      "GET",
+      `/api/modules/by-slug/${encodeURIComponent(slug)}`
+    );
+    if (!mod.current_version) {
+      return {
+        violations: [],
+        additions: [],
+        warnings: [],
+        base: "(nothing released)",
+        head: headPath,
+        history: 0,
+        nothingReleased: true
+      };
+    }
+    versions = await apiRequest("GET", `/api/modules/${mod.id}/versions`);
+  } catch (err) {
+    const why = err instanceof ApiError ? `${err.code || err.status} ${err.message}` : err.message;
+    throw new EvolutionCheckError(
+      `could not read the released manifest of ${slug} (${why}); pass --base <ref|file> to check offline`
+    );
+  }
+  const released = versions.find((v) => v.version === mod.current_version);
+  if (!released?.manifest_jsonb) {
+    throw new EvolutionCheckError(
+      `the platform returned no manifest for ${slug} v${mod.current_version}; pass --base <ref|file> to check offline`
+    );
+  }
+  const releasedAt = released.created_on ? Date.parse(released.created_on) : Number.POSITIVE_INFINITY;
+  const history = options.noHistory ? [] : versions.filter((v) => v !== released && v.manifest_jsonb && v.created_on && Date.parse(v.created_on) < releasedAt).sort((a, b) => Date.parse(a.created_on) - Date.parse(b.created_on)).map((v) => v.manifest_jsonb);
+  return {
+    ...compareManifests(released.manifest_jsonb, head, history),
+    base: `${slug} v${mod.current_version} (released)`,
+    head: headPath,
+    history: history.length,
+    nothingReleased: false
+  };
+}
+function printEvolutionReport(r, print = out) {
+  print(`module diff --check: ${r.head} against ${r.base} (${r.history} older version${r.history === 1 ? "" : "s"} scanned)`);
+  for (const a of r.additions) print(`  + ${a}`);
+  for (const w of r.warnings) print(`  ! ${w}`);
+  for (const x of r.violations) print(`  \u2717 ${x.rule}: ${x.where}: ${x.detail}`);
+}
+async function moduleDiffCheckCommand(options) {
+  let r;
+  try {
+    r = await runEvolutionCheck(options);
+  } catch (err) {
+    if (err instanceof EvolutionCheckError) {
+      if (options.json) out(JSON.stringify({ ok: false, error: { code: "CHECK_FAILED", message: err.message } }));
+      else fail(`module diff --check: ${err.message}`);
+      return 2;
+    }
+    throw err;
+  }
+  if (options.json) {
+    out(JSON.stringify({ ok: r.violations.length === 0, ...r }, null, 2));
+    return r.violations.length === 0 ? 0 : 1;
+  }
+  if (r.nothingReleased) {
+    success("Nothing released yet: every change is additive.");
+    return 0;
+  }
+  printEvolutionReport(r);
+  if (r.violations.length === 0) {
+    success("additive");
+    return 0;
+  }
+  fail(`${r.violations.length} violation(s): not additive. Released copies would lose data or fail to upgrade.`);
+  info(`Add a new field or table instead, and stop writing the old one (${code('human_edit: "open"')}).`);
+  return 1;
+}
+async function publishEvolutionGate(projectRoot, strict) {
+  let r;
+  try {
+    r = await runEvolutionCheck({ dir: projectRoot });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (strict) {
+      fail(`Evolution check could not run (${msg}). Refusing with --strict. Nothing was published.`);
+      return 1;
+    }
+    warn(`Evolution check skipped: ${msg}.`);
+    return 0;
+  }
+  if (r.nothingReleased || r.violations.length === 0) return 0;
+  printEvolutionReport(r, (s) => (strict ? fail : warn)(s));
+  if (strict) {
+    fail(
+      `module.json is not an additive evolution of the released version (${r.violations.length} violation(s)). Refusing with --strict. Nothing was published.`
+    );
+    return 1;
+  }
+  warn(
+    `module.json is not an additive evolution of the released version: installs that upgrade lose the data above. ${code("--strict")} turns this into a refusal; ${code("dashwise module diff --check")} shows it on its own.`
+  );
+  return 0;
+}
+var EvolutionCheckError;
+var init_diff_check = __esm({
+  "src/commands/module/diff-check.ts"() {
+    init_api_client();
+    init_manifest_evolution();
+    init_output();
+    EvolutionCheckError = class extends Error {
+    };
+  }
+});
+
+// src/lib/manifest-reference-lint.ts
+function referenceFieldWarnings(manifest) {
+  const tables = manifest?.owns?.tables;
+  if (!Array.isArray(tables)) return [];
+  const warnings = [];
+  for (const table of tables) {
+    if (typeof table?.slug !== "string" || !Array.isArray(table.fields)) continue;
+    for (const field of table.fields) {
+      if (typeof field?.slug !== "string" || typeof field.type !== "string") continue;
+      if (field.slug === "id" || !REFERENCE_NAME.test(field.slug)) continue;
+      if (!PLAIN_TYPES.has(field.type)) continue;
+      warnings.push({
+        table: table.slug,
+        field: field.slug,
+        type: field.type,
+        message: `${table.slug}.${field.slug} is a ${field.type} field named like a reference. If it points at a row in Dashwise, use a link_row field: plain ids break silently when data is copied to another installation. Ignore this for ids from outside systems.`
+      });
+    }
+  }
+  return warnings;
+}
+var REFERENCE_NAME, PLAIN_TYPES;
+var init_manifest_reference_lint = __esm({
+  "src/lib/manifest-reference-lint.ts"() {
+    REFERENCE_NAME = /(?:_id|_ref|Id|Ref)$/;
+    PLAIN_TYPES = /* @__PURE__ */ new Set(["number", "text", "autonumber"]);
+  }
+});
 function loadSchemaCommandContext(opts) {
   const projectRoot = resolve(opts.dir ?? process.cwd());
   const manifestPath2 = join(projectRoot, "module.json");
@@ -13786,6 +14156,89 @@ var init_dotenv_local = __esm({
   }
 });
 
+// src/lib/install-target.ts
+function keyDisplayPrefix(apiKey) {
+  if (!apiKey.startsWith(KEY_SCHEME)) return null;
+  const prefix = apiKey.slice(KEY_SCHEME.length, KEY_SCHEME.length + KEY_PREFIX_CHARS);
+  return prefix.length === KEY_PREFIX_CHARS ? prefix : null;
+}
+async function keyBelongsToInstall(apiKey, installationId, options, now = /* @__PURE__ */ new Date()) {
+  const prefix = keyDisplayPrefix(apiKey);
+  if (prefix === null) return false;
+  const { api_keys } = await listApiKeys(installationId, options);
+  return api_keys.some(
+    (k) => k.installation_id === installationId && k.key_prefix === prefix && (k.status === void 0 || k.status === "active") && k.revoked_at === null && (k.expires_at === null || new Date(k.expires_at) > now)
+  );
+}
+function formatInstallTarget(id, detail) {
+  return detail ? `\u2192 install #${id} (${detail})` : `\u2192 install #${id}`;
+}
+async function nameKeyTarget(args) {
+  const { apiKey, keySource, entry, cfg, apiUrl, install } = args;
+  const request = cfg ? { baseUrl: apiUrl, auth: { token: cfg.token }, signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS) } : null;
+  if (install === void 0) {
+    if (keySource !== "cached" || !entry) {
+      info(
+        `\u2192 install not checked: ${code("DASHWISE_API_KEY")} comes from ${keySource === "environment" ? "the environment" : code(".env.local")}. Pass ${code("--install <id>")} to name its target and refuse a mismatch.`
+      );
+      return 0;
+    }
+    if (!request || entry.workspaceId === void 0) {
+      info(formatInstallTarget(entry.installationId, "the cached dev install"));
+      return 0;
+    }
+    try {
+      const workspaces = await apiRequest("GET", "/api/workspaces", void 0, request);
+      const ws = workspaces.find((w) => w.id === entry.workspaceId);
+      info(formatInstallTarget(entry.installationId, `${ws ? ws.slug : `workspace #${entry.workspaceId}`}, local`));
+    } catch {
+      info(formatInstallTarget(entry.installationId));
+    }
+    return 0;
+  }
+  const source = keySource === "cached" ? "the cached key" : `${code("DASHWISE_API_KEY")} (from ${keySource === "environment" ? "the environment" : code(".env.local")})`;
+  if (!request) {
+    fail(
+      `${code("--install")} looks the install up with your CLI login, and there is none. Run ${code("dashwise login")} first. Nothing was run.`
+    );
+    return 1;
+  }
+  let belongs;
+  try {
+    belongs = await keyBelongsToInstall(apiKey, install, request);
+  } catch (err) {
+    fail(
+      `Could not read the keys of install #${install} to confirm ${source} (${describe(err)}). Refusing to run against an unconfirmed install. Nothing was run.`
+    );
+    return 1;
+  }
+  const cachedDev = entry?.installationId === install ? "the cached dev install, " : "";
+  if (!belongs) {
+    const other = entry && entry.installationId !== install && entry.apiKey === apiKey ? ` It is the cached key of install #${entry.installationId}.` : "";
+    fail(`${source} is not a live key of install #${install}.${other} Nothing was run.`);
+    info(
+      `Use a key of install #${install} (mint one with ${code(`dashwise api-keys create <name> --install ${install}`)}), or drop ${code("--install")} to run against the key's own install.`
+    );
+    return 1;
+  }
+  info(formatInstallTarget(install, `${cachedDev}key checked`));
+  return 0;
+}
+function describe(err) {
+  if (err instanceof ApiError) return `${err.code || err.status} ${err.message}`;
+  return err.message;
+}
+var KEY_PREFIX_CHARS, KEY_SCHEME, LOOKUP_TIMEOUT_MS;
+var init_install_target = __esm({
+  "src/lib/install-target.ts"() {
+    init_api_client();
+    init_output();
+    KEY_PREFIX_CHARS = 8;
+    KEY_SCHEME = "dwk_";
+    LOOKUP_TIMEOUT_MS = 1500;
+  }
+});
+
 // src/commands/run.ts
 var run_exports = {};
 __export(run_exports, {
@@ -13798,6 +14251,10 @@ async function runCommand(cmdArgs, options) {
     );
     return 1;
   }
+  if (options.install !== void 0 && (!Number.isInteger(options.install) || options.install <= 0)) {
+    fail(`--install expects a positive integer installation id (got "${options.install}").`);
+    return 1;
+  }
   const projectRoot = resolve(options.dir ?? process.cwd());
   let manifestSlug;
   try {
@@ -13810,6 +14267,7 @@ async function runCommand(cmdArgs, options) {
     fail(`module.json has no ${code("module.slug")} \u2014 the manifest is malformed.`);
     return 1;
   }
+  const keyInShell = process.env.DASHWISE_API_KEY !== void 0;
   hydrateEnvFromDotenvLocal(projectRoot);
   const cfg = (() => {
     try {
@@ -13820,8 +14278,19 @@ async function runCommand(cmdArgs, options) {
   })();
   const apiUrl = process.env.DASHWISE_API_URL ?? cfg?.apiUrl ?? "http://localhost:3000";
   let apiKey = process.env.DASHWISE_API_KEY;
+  let keySource = keyInShell ? "environment" : ".env.local";
+  let entry = null;
   if (!apiKey) {
-    let entry = readModuleEntry(manifestSlug);
+    entry = readModuleEntry(manifestSlug);
+    if (entry && options.install !== void 0 && entry.installationId !== options.install) {
+      fail(
+        `No key for install #${options.install}: the cached ${code("dwk_")} key of ${code(manifestSlug)} belongs to install #${entry.installationId}. Nothing was run.`
+      );
+      info(
+        `Set ${code("DASHWISE_API_KEY")} to a key of install #${options.install} (mint one with ${code(`dashwise api-keys create <name> --install ${options.install}`)}).`
+      );
+      return 1;
+    }
     if (cfg) {
       const healed = await resolveModuleApiKey(
         manifestSlug,
@@ -13832,6 +14301,7 @@ async function runCommand(cmdArgs, options) {
       if (healed) entry = healed;
     }
     apiKey = entry?.apiKey;
+    keySource = "cached";
   }
   if (!apiKey) {
     fail(
@@ -13842,6 +14312,15 @@ async function runCommand(cmdArgs, options) {
     );
     return 1;
   }
+  const target = await nameKeyTarget({
+    apiKey,
+    keySource,
+    entry: entry ?? readModuleEntry(manifestSlug),
+    cfg,
+    apiUrl,
+    ...options.install !== void 0 ? { install: options.install } : {}
+  });
+  if (target !== 0) return target;
   const [cmd, ...rest] = cmdArgs;
   info(
     `${dim("run")} ${cmd} ${rest.join(" ")} ${dim(`(DASHWISE_API_URL=${apiUrl}, DASHWISE_API_KEY injected)`)}`
@@ -13871,6 +14350,7 @@ var init_run = __esm({
   "src/commands/run.ts"() {
     init_config();
     init_dotenv_local();
+    init_install_target();
     init_manifest_io();
     init_output();
     init_dev();
@@ -14161,6 +14641,7 @@ async function schemaPushCommand(options) {
     return surfaceSchemaPushError(err, slug);
   }
   printApplySummary(applied);
+  for (const w of referenceFieldWarnings(manifest)) warn(w.message);
   if (dwkAuth) {
     try {
       const { manifest: canonical } = await getInstallationSchema(dwkAuth);
@@ -14309,6 +14790,7 @@ var init_push = __esm({
     init_manifest_io();
     init_manifest_merge();
     init_output();
+    init_manifest_reference_lint();
   }
 });
 
@@ -15866,8 +16348,8 @@ function startMcpProxy(opts) {
   let streamUnavailable = false;
   let streamStarted = false;
   let resolveDone;
-  const done = new Promise((resolve15) => {
-    resolveDone = resolve15;
+  const done = new Promise((resolve16) => {
+    resolveDone = resolve16;
   });
   const trace = (line) => {
     if (verbose) log2(line);
@@ -16353,7 +16835,7 @@ async function revokeSession(endpointId) {
     () => false
   );
   const timeout = new Promise(
-    (resolve15) => setTimeout(() => resolve15(false), REVOKE_TIMEOUT_MS).unref()
+    (resolve16) => setTimeout(() => resolve16(false), REVOKE_TIMEOUT_MS).unref()
   );
   await Promise.race([attempt, timeout]);
 }
@@ -16531,7 +17013,7 @@ async function mcpAddCommand(options = {}) {
     fail(`Could not run \`claude\`: ${target.refused} Run the command above yourself.`);
     return 1;
   }
-  return await new Promise((resolve15) => {
+  return await new Promise((resolve16) => {
     const child = spawn(target.command, target.args, { shell: target.shell, stdio: "inherit" });
     let settled = false;
     child.on("error", (err) => {
@@ -16541,16 +17023,16 @@ async function mcpAddCommand(options = {}) {
         fail(
           `Claude Code is not on your PATH, so nothing was registered. Run the command above once ${code("claude")} is installed.`
         );
-        resolve15(1);
+        resolve16(1);
         return;
       }
       fail(`Could not run \`claude\`: ${err.message}`);
-      resolve15(1);
+      resolve16(1);
     });
     child.on("close", (codeOut) => {
       if (settled) return;
       settled = true;
-      resolve15(codeOut ?? 1);
+      resolve16(codeOut ?? 1);
     });
   });
 }
@@ -16669,10 +17151,10 @@ function upgradeCommand(plugin, marketplace) {
 var PLUGIN_NAME = "dashwise";
 var MARKETPLACE_NAME = "dashwise";
 var DEFAULT_MARKETPLACE_SOURCE = "Intuize/dashwise-cli";
-var defaultRunner = (cmd, args, opts) => new Promise((resolve15) => {
+var defaultRunner = (cmd, args, opts) => new Promise((resolve16) => {
   const target = spawnTarget(cmd, args);
   if ("refused" in target) {
-    resolve15({ code: null, stdout: "", stderr: target.refused, missing: false });
+    resolve16({ code: null, stdout: "", stderr: target.refused, missing: false });
     return;
   }
   const child = spawn(target.command, target.args, {
@@ -16687,7 +17169,7 @@ var defaultRunner = (cmd, args, opts) => new Promise((resolve15) => {
   child.on("error", (err) => {
     if (settled) return;
     settled = true;
-    resolve15({
+    resolve16({
       code: null,
       stdout,
       stderr: stderr || err.message,
@@ -16697,7 +17179,7 @@ var defaultRunner = (cmd, args, opts) => new Promise((resolve15) => {
   child.on("close", (exitCode) => {
     if (settled) return;
     settled = true;
-    resolve15({ code: exitCode, stdout, stderr, missing: false });
+    resolve16({ code: exitCode, stdout, stderr, missing: false });
   });
 });
 function readSkillsOnDisk() {
@@ -17938,6 +18420,7 @@ function judgeGeneratorStamp(stamp, opts = {}) {
 // src/commands/module/generate.ts
 init_sdk_version();
 init_output();
+init_declared_secrets();
 function outputDir(projectRoot) {
   return join(projectRoot, "node_modules", "@dashai", "generated");
 }
@@ -18014,6 +18497,9 @@ async function moduleGenerateCommand(options) {
   info(`Hash: ${dim(res.contentHash)}`);
   if (verdict.note !== null && declaresUses(manifest)) info(verdict.note);
   warnIfSdkBelowUsesFloor(projectRoot, manifest);
+  reportSecretLines(
+    syncEnvLocalSecretLines(projectRoot, declaredSecretNames(manifest))
+  );
   return 0;
 }
 function declaresUses(manifest) {
@@ -18272,6 +18758,101 @@ init_init();
 // src/commands/module/install.ts
 init_api_client();
 init_config();
+
+// src/lib/agent-session.ts
+var MARKERS = [
+  ["CLAUDECODE", (v) => v === "1"],
+  ["CLAUDE_CODE_REMOTE", (v) => v === "true"],
+  ["CODEX_SANDBOX", (v) => v.length > 0],
+  ["CODEX_SANDBOX_NETWORK_DISABLED", (v) => v.length > 0],
+  ["CURSOR_AGENT", (v) => v.length > 0],
+  ["DW_AGENT", (v) => v.length > 0],
+  ["DASHWISE_AGENT_SESSION", (v) => v === "1" || v === "true"]
+];
+function agentSessionMarker(env = process.env) {
+  for (const [name, test] of MARKERS) {
+    const value = env[name];
+    if (value !== void 0 && test(value)) return name;
+  }
+  return null;
+}
+
+// src/lib/drift-preview.ts
+init_api_client();
+function redactedConsumer(redacted) {
+  switch (redacted) {
+    case "private_copy":
+      return "someone's private copy";
+    case "other_team_copy":
+      return "another team's copy";
+    case "development_copy":
+      return "a development copy you cannot see";
+    default:
+      return "a copy you cannot see";
+  }
+}
+var WIDEN_WORDS = {
+  uses_need_added: "a new table it reads from another module",
+  uses_ops_widened: "more operations on a table it reads",
+  uses_fields_added: "more fields of a table it reads",
+  dependency_added: "a new or wider dependency",
+  exposes_widened: "more of what it exposes to other modules",
+  permissions_added: "more permissions",
+  roles_widened: "more roles or permission keys",
+  outbound_added: "new outbound APIs (data can leave)",
+  secrets_added: "new secrets",
+  public_access_enabled: "public access"
+};
+function describeWidening(widening) {
+  return widening.map((w) => WIDEN_WORDS[w] ?? w).join(", ");
+}
+async function getUpgradePreview(installationId, version, options = {}) {
+  return apiRequest(
+    "GET",
+    `/api/installations/${installationId}/upgrade-preview?version=${encodeURIComponent(version)}`,
+    void 0,
+    options
+  );
+}
+function count(n, unit) {
+  if (n === null) return `${unit}s not counted`;
+  return `${n.toLocaleString("en-US")} ${unit}${n === 1 ? "" : "s"}`;
+}
+function describeDrift(drift) {
+  const lines = [];
+  const d = drift.details;
+  const removedTables = d?.tables_to_remove ?? drift.tables_to_remove.map((t) => ({ table: t, name: t, rows: null }));
+  for (const t of removedTables) {
+    lines.push({
+      loses: t.rows !== 0,
+      text: `Moves table ${t.table} (${count(t.rows, "row")}) to the Trash`
+    });
+  }
+  const removedFields = d?.fields_to_remove ?? drift.fields_to_remove.map((f) => ({ ...f, name: f.field, values: null }));
+  for (const f of removedFields) {
+    lines.push({
+      loses: f.values !== 0,
+      text: `Moves field ${f.table}.${f.field} (${count(f.values, "value")}) to the Trash`
+    });
+  }
+  const retyped = d?.fields_to_retype ?? (drift.fields_to_retype ?? []).map((f) => ({ ...f, name: f.field, values: null }));
+  for (const f of retyped) {
+    lines.push({
+      loses: f.values !== 0,
+      text: `Converts field ${f.table}.${f.field} from ${f.from} to ${f.to} (${count(f.values, "value")}; a value that does not convert is lost)`
+    });
+  }
+  lines.sort((a, b) => Number(b.loses) - Number(a.loses));
+  for (const t of drift.tables_to_create) {
+    lines.push({ loses: false, text: `Adds table ${t}` });
+  }
+  for (const f of drift.fields_to_create) {
+    lines.push({ loses: false, text: `Adds field ${f.table}.${f.field}` });
+  }
+  return lines;
+}
+
+// src/commands/module/install.ts
 init_manifest_io();
 
 // src/lib/module-lifecycle.ts
@@ -18450,18 +19031,31 @@ async function moduleInstallCommand(slugArg, options) {
       );
     }
   }
-  if (!options.yes && process.stdout.isTTY && !confirmedViaPicker) {
-    const message = devInstallToReplace ? isUpgrade ? `Destroy the dev install (revokes local-dev credentials) and upgrade ${code(mod.slug)} to ${code(`v${targetVersion}`)} in ${code(workspace2.slug)}?` : `Replace the dev install (revokes local-dev credentials) and install ${code(mod.slug)} ${code(`v${targetVersion}`)} into ${code(workspace2.slug)} as production?` : `${isUpgrade ? "Upgrade" : "Install"} ${code(mod.slug)} ${code(`v${targetVersion}`)} into workspace ${code(workspace2.slug)}?`;
+  let preview;
+  let lossy = false;
+  let lossAccepted = false;
+  if (existing) {
+    const rerun = rerunLine(mod.slug, workspace2.slug, targetVersion, options, devInstallToReplace !== void 0);
+    const previewed = await previewUpgrade(existing.id, targetVersion, options, auth, rerun, devInstallToReplace?.id);
+    if (typeof previewed === "number") return previewed;
+    preview = previewed.preview;
+    lossy = previewed.lossy;
+    lossAccepted = previewed.accepted;
+  }
+  const askForLoss = lossy && !lossAccepted;
+  if (askForLoss || !options.yes && process.stdout.isTTY && !confirmedViaPicker) {
+    const lossClause = lossy ? " It moves the data listed above to the Trash or converts it." : "";
+    const message = devInstallToReplace ? isUpgrade ? `Destroy the dev install (revokes local-dev credentials) and upgrade ${code(mod.slug)} to ${code(`v${targetVersion}`)} in ${code(workspace2.slug)}?${lossClause}` : `Replace the dev install (revokes local-dev credentials) and install ${code(mod.slug)} ${code(`v${targetVersion}`)} into ${code(workspace2.slug)} as production?` : `${isUpgrade ? "Upgrade" : "Install"} ${code(mod.slug)} ${code(`v${targetVersion}`)} into workspace ${code(workspace2.slug)}?${lossClause}`;
     const answer = await select({
       message,
       options: [
         {
           value: "go",
-          label: devInstallToReplace ? isUpgrade ? "Yes, destroy the dev install + upgrade" : "Yes, replace the dev install + production-install" : isUpgrade ? "Yes, upgrade now" : "Yes, install now"
+          label: devInstallToReplace ? isUpgrade ? lossy ? "Yes, destroy the dev install + upgrade and lose the data listed above" : "Yes, destroy the dev install + upgrade" : "Yes, replace the dev install + production-install" : isUpgrade ? lossy ? "Yes, upgrade and lose the data listed above" : "Yes, upgrade now" : "Yes, install now"
         },
         { value: "cancel", label: "No, abort" }
       ],
-      initialValue: devInstallToReplace ? "cancel" : "go"
+      initialValue: devInstallToReplace || lossy ? "cancel" : "go"
     });
     if (isCancel(answer) || answer === "cancel") {
       fail("Aborted. Nothing was changed.");
@@ -18483,7 +19077,9 @@ async function moduleInstallCommand(slugArg, options) {
         workspaceId: workspace2.id,
         version: targetVersion,
         ...existing ? { installation_id: existing.id } : {},
-        ...options.force !== void 0 ? { force: options.force } : {}
+        ...options.force !== void 0 ? { force: options.force } : {},
+        // P5-08: confirms exactly the delta that was shown (409 DRIFT_CHANGED otherwise).
+        ...preview ? { drift_hash: preview.drift_hash } : {}
       },
       auth
     );
@@ -18535,6 +19131,9 @@ async function moduleInstallCommand(slugArg, options) {
         was_upgrade: result.was_upgrade,
         public_url: publicUrl,
         verified,
+        // P5-08: the confirmed preview; `null` for a fresh install (nothing to preview).
+        drift_hash: preview?.drift_hash ?? null,
+        data_loss: preview ? lossy : null,
         // `null` when the binding surface was unreachable; `[]` when the
         // module declares no slots. The two are not the same thing.
         uses: readiness === null ? null : usesInstallJson(readiness),
@@ -18703,6 +19302,19 @@ function surfaceInstallError(err, slug, workspaceSlug, devInstallReplaced) {
   Ask the module's author to invite this workspace (or open the install gate), then retry.`
         );
         break;
+      case "DRIFT_CHANGED":
+        fail(
+          `Install ${code(slug)} changed since its upgrade preview, so the confirmed change no longer matches. Nothing was changed.
+  Re-run ${code("dashwise module install")} to see the new preview.`
+        );
+        break;
+      case "DATA_LOSS_CONFIRM_REQUIRED":
+      case "UPGRADE_CONFIRM_REQUIRED":
+        fail(
+          `The platform asks for a confirmed preview before this upgrade (${err.code}). Nothing was changed.
+  Re-run ${code("dashwise module install")}: it previews the upgrade and sends the confirmation.`
+        );
+        break;
       case "UPGRADE_BREAKS_CONSUMERS":
         fail(
           `Upgrading ${code(slug)} would break modules that consume its current schema.
@@ -18752,6 +19364,75 @@ function usesInstallJson(readiness) {
     }))
   };
 }
+async function previewUpgrade(installationId, targetVersion, options, auth, rerun, devInstallToReplaceId) {
+  let preview;
+  try {
+    preview = await getUpgradePreview(installationId, targetVersion, auth);
+  } catch (err) {
+    const why = err instanceof ApiError ? `${err.code || err.status} ${err.message}` : err.message;
+    const checkNote = options.acceptDataLoss !== void 0 ? `, so ${code("--accept-data-loss")} cannot be checked` : "";
+    fail(
+      `Could not preview what upgrading install #${installationId} to ${code(`v${targetVersion}`)} does to its data (${why})${checkNote}. Nothing was changed.`
+    );
+    info(`An upgrade is never applied without its preview; retry when the platform answers.`);
+    return 1;
+  }
+  const lines = describeDrift(preview.drift);
+  const lossy = lines.some((l) => l.loses);
+  const from = preview.from_version ? `v${preview.from_version}` : "its current version";
+  if (lines.length === 0) {
+    info(`Upgrading install #${installationId} from ${from} to v${preview.to_version} changes no table or field.`);
+  } else {
+    info(`What upgrading install #${installationId} from ${from} to v${preview.to_version} does to its data:`);
+    for (const line of lines) {
+      (line.loses ? warn : info)(`  ${line.text}`);
+    }
+  }
+  const broken = preview.breaks_consumers ?? [];
+  if (broken.length > 0) {
+    const names = broken.map(
+      (c2) => c2.module_slug ? `${c2.module_slug}${c2.installation_id ? ` #${c2.installation_id}` : ""}` : redactedConsumer(c2.redacted)
+    );
+    warn(`  Breaks ${broken.length} module${broken.length === 1 ? "" : "s"} that read${broken.length === 1 ? "s" : ""} this one: ${names.join(", ")}`);
+  }
+  if (preview.approval_required) {
+    const asks = preview.widening && preview.widening.length > 0 ? `: it asks for ${describeWidening(preview.widening)}` : "";
+    warn(`  This update waits for the module author's approval${asks}.`);
+  }
+  if (options.acceptDataLoss !== void 0 && options.acceptDataLoss !== preview.drift_hash) {
+    fail(
+      `${code("--accept-data-loss")} does not match this upgrade's preview: the copy or the release changed since that hash was printed. Nothing was changed.`
+    );
+    info(`To accept the change listed above, a person re-runs:
+  ${rerun(preview.drift_hash)}`);
+    return 1;
+  }
+  const accepted = lossy && options.acceptDataLoss === preview.drift_hash;
+  if (lossy && !accepted) {
+    const yesNote = options.yes ? ` ${code("--yes")} does not accept data loss.` : "";
+    const marker = agentSessionMarker();
+    const why = marker ? `this is an agent session (${code(marker)} is set): a person decides` : !process.stdout.isTTY ? "there is no terminal to ask in" : null;
+    if (why) {
+      const alsoDev = devInstallToReplaceId !== void 0 ? ` and destroys dev install #${devInstallToReplaceId} first` : "";
+      fail(`This upgrade loses the data listed above${alsoDev}, and ${why}.${yesNote} Refused. Nothing was changed.`);
+      info(`To accept exactly that loss, a person re-runs:
+  ${rerun(preview.drift_hash)}`);
+      return 1;
+    }
+  }
+  return { preview, lossy, accepted };
+}
+function rerunLine(slug, workspaceSlug, targetVersion, options, replacingDevInstall) {
+  return (hash) => [
+    "dashwise module install",
+    slug,
+    `--workspace ${workspaceSlug}`,
+    `--version ${targetVersion}`,
+    ...options.force ? ["--force"] : [],
+    ...replacingDevInstall ? ["--replace-dev-install"] : [],
+    `--accept-data-loss ${hash}`
+  ].join(" ");
+}
 
 // src/commands/module/list.ts
 init_api_client();
@@ -19121,6 +19802,7 @@ function formatBytes(n) {
 }
 
 // src/commands/module/publish.ts
+init_diff_check();
 var VALID_BUMP = /* @__PURE__ */ new Set(["patch", "minor", "major"]);
 var PACKED_FILE_LIST_CAP = 20;
 function packedFileLines(files, cap = PACKED_FILE_LIST_CAP) {
@@ -19207,6 +19889,10 @@ async function modulePublishCommand(options) {
   info(
     `Module: ${code(mod.slug)} (id ${mod.id})${mod.current_version ? `, current ${code(`v${mod.current_version}`)}` : dim(", no published version yet")}`
   );
+  if (mod.current_version) {
+    const gate = await publishEvolutionGate(projectRoot, options.strict === true);
+    if (gate !== 0) return gate;
+  }
   let tarball;
   try {
     tarball = await packTarball({
@@ -19798,7 +20484,7 @@ async function moduleReleaseCommand(slugArg, options) {
   }
   async function wait() {
     const remaining = Math.max(0, deadline - Date.now());
-    await new Promise((resolve15) => setTimeout(resolve15, Math.min(options.pollIntervalMs ?? 4e3, remaining)));
+    await new Promise((resolve16) => setTimeout(resolve16, Math.min(options.pollIntervalMs ?? 4e3, remaining)));
   }
 }
 
@@ -20220,6 +20906,7 @@ async function modulePullDataCommand(options) {
 // src/commands/module/validate.ts
 init_api_client();
 init_output();
+init_manifest_reference_lint();
 async function moduleValidateCommand(options) {
   const projectRoot = resolve(options.dir ?? process.cwd());
   const manifestPath2 = join(projectRoot, "module.json");
@@ -20244,6 +20931,7 @@ async function moduleValidateCommand(options) {
     );
     if (res.ok) {
       success("Manifest is valid.");
+      for (const w of referenceFieldWarnings(manifest)) warn(w.message);
       return 0;
     }
     fail(`Unexpected response shape: ${JSON.stringify(res)}`);
@@ -22646,6 +23334,23 @@ init_api_client();
 init_config();
 init_manifest_io();
 init_output();
+init_declared_secrets();
+var SECRETS_NOTE = "# Declared secrets (runtime.secrets[]): set each value on your host; Dashwise never exports a secret value.";
+function secretNameLines(names, format) {
+  const lines = names.map((name) => {
+    switch (format) {
+      case "env":
+        return `# ${name}=`;
+      case "railway":
+        return `# ${name}: railway variables set ${name}='<value>'`;
+      case "vercel":
+        return `# ${name}: vercel env add ${name} production`;
+      case "fly":
+        return `# ${name}: fly secrets set ${name}='<value>'`;
+    }
+  });
+  return [SECRETS_NOTE, ...lines].join("\n");
+}
 var PLACEHOLDER = "<run-`dashwise-api-keys-create-<name>`-and-paste-here>";
 async function envExportCommand(options) {
   const format = options.format ?? "env";
@@ -22736,7 +23441,19 @@ async function envExportCommand(options) {
       ...apiKeyComment !== null ? { comment: apiKeyComment } : {}
     }
   ];
+  const secretNames = options.withSecretNames ? declaredSecretNames(manifest) : [];
   process.stdout.write(render(entries, format));
+  if (secretNames.length > 0) {
+    if (format === "json") {
+      info(
+        `Declared secrets to set on your host (Dashwise never exports a secret value): ${secretNames.join(", ")}`
+      );
+    } else {
+      process.stdout.write(`
+
+${secretNameLines(secretNames, format)}`);
+    }
+  }
   if (format !== "json") process.stdout.write("\n");
   if (apiKey === PLACEHOLDER) {
     info("");
@@ -22792,6 +23509,7 @@ init_config();
 init_dotenv_local();
 init_manifest_io();
 init_output();
+init_install_target();
 init_dev();
 async function queryCommand(options) {
   const projectRoot = resolve(options.dir ?? process.cwd());
@@ -22814,17 +23532,25 @@ async function queryCommand(options) {
     );
     return 1;
   }
+  const keyInShell = process.env.DASHWISE_API_KEY !== void 0;
   hydrateEnvFromDotenvLocal(projectRoot);
+  const cfg = (() => {
+    try {
+      return readConfig();
+    } catch {
+      return null;
+    }
+  })();
+  const apiUrl = process.env.DASHWISE_API_URL ?? cfg?.apiUrl ?? "http://localhost:3000";
+  let keySource = keyInShell ? "environment" : ".env.local";
+  let entry = manifestSlug ? readModuleEntry(manifestSlug) : null;
   if (!process.env.DASHWISE_API_KEY && manifestSlug) {
-    const cfg = (() => {
-      try {
-        return readConfig();
-      } catch {
-        return null;
-      }
-    })();
-    const apiUrl = process.env.DASHWISE_API_URL ?? cfg?.apiUrl ?? "http://localhost:3000";
-    let entry = readModuleEntry(manifestSlug);
+    if (entry && options.install !== void 0 && entry.installationId !== options.install) {
+      fail(
+        `No key for install #${options.install}: the cached ${code("dwk_")} key of ${code(manifestSlug)} belongs to install #${entry.installationId}. Nothing was run.`
+      );
+      return 1;
+    }
     if (cfg) {
       const healed = await resolveModuleApiKey(
         manifestSlug,
@@ -22836,11 +23562,26 @@ async function queryCommand(options) {
     }
     if (entry?.apiKey) {
       process.env.DASHWISE_API_KEY = entry.apiKey;
+      keySource = "cached";
       if (!process.env.DASHWISE_API_URL) {
         process.env.DASHWISE_API_URL = apiUrl;
       }
     }
   }
+  if (process.env.DASHWISE_API_KEY) {
+    const target = await nameKeyTarget({
+      apiKey: process.env.DASHWISE_API_KEY,
+      keySource,
+      entry,
+      cfg,
+      apiUrl: process.env.DASHWISE_API_URL ?? apiUrl,
+      ...options.install !== void 0 ? { install: options.install } : {}
+    });
+    if (target !== 0) return target;
+  } else if (options.install !== void 0) {
+    fail(`No ${code("dwk_")} key to check against install #${options.install}. Set ${code("DASHWISE_API_KEY")}. Nothing was run.`);
+    return 1;
+  }
   const modes = [
     options.inline !== void 0 ? "inline" : null,
     options.file !== void 0 ? "file" : null,
@@ -23206,7 +23947,7 @@ function formatTimestamp(iso) {
   return iso.slice(0, 19).replace("T", " ");
 }
 function sleep2(ms) {
-  return new Promise((resolve15) => setTimeout(resolve15, ms));
+  return new Promise((resolve16) => setTimeout(resolve16, ms));
 }
 
 // src/commands/module/action-log.ts
@@ -23308,7 +24049,7 @@ async function runTail2(installationId, options) {
       }
       dim(`(tail: transient error \u2014 ${err.message})`);
     }
-    await new Promise((resolve15) => setTimeout(resolve15, POLL_INTERVAL_MS2));
+    await new Promise((resolve16) => setTimeout(resolve16, POLL_INTERVAL_MS2));
   }
 }
 function printTable(rows) {
@@ -23693,7 +24434,7 @@ async function sleep3(ms, aborted) {
   const slice = 100;
   let waited = 0;
   while (waited < ms && !aborted()) {
-    await new Promise((resolve15) => setTimeout(resolve15, Math.min(slice, ms - waited)));
+    await new Promise((resolve16) => setTimeout(resolve16, Math.min(slice, ms - waited)));
     waited += slice;
   }
 }
@@ -24524,12 +25265,29 @@ moduleCmd.command("list").description("List modules you own (or `--all` for owne
     ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
   });
 });
-moduleCmd.command("diff").description("Show what would change at the next publish vs the currently-published version.").option("--dir <path>", "Project root (default: current directory).").option("--json", "Emit the structured diff as JSON instead of the human-readable summary.").action(async (cmdOpts) => {
-  process.exitCode = await moduleDiffCommand({
-    ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
-    ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
-  });
-});
+moduleCmd.command("diff").description(
+  "Show what would change at the next publish vs the currently-published version. With --check: exit 1 when module.json is not an additive evolution of the released manifest (a removed table or field, a retype, a removed or reordered option, a new unique index (`indexes[].unique`) over an existing field, a dropped unique index, required tightened, or a slug reused after an earlier removal), 2 on a usage or read error. Offline with --base."
+).option("--dir <path>", "Project root (default: current directory).").option("--json", "Emit the structured diff as JSON instead of the human-readable summary.").option("--check", "Check additive evolution against the released manifest (exit 0 additive, 1 not additive, 2 error).").option("--base <ref|path>", "With --check: the base manifest from a git ref (its module.json, history from its log) or, when the path exists, a file. Default: the released version on the platform.").option("--base-file <path>", "With --check: the base manifest from a file.").option("--head <path>", "With --check: the manifest to check (default: <dir>/module.json).").option("--no-history", "With --check: skip the slug-reuse scan of older versions.").option("--dry-run", "Accepted for uniformity; --check never writes anything.").action(
+  async (cmdOpts) => {
+    if (cmdOpts.check) {
+      const { moduleDiffCheckCommand: moduleDiffCheckCommand2 } = await Promise.resolve().then(() => (init_diff_check(), diff_check_exports));
+      process.exitCode = await moduleDiffCheckCommand2({
+        ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
+        ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {},
+        ...cmdOpts.base !== void 0 ? { base: cmdOpts.base } : {},
+        ...cmdOpts.baseFile !== void 0 ? { baseFile: cmdOpts.baseFile } : {},
+        ...cmdOpts.head !== void 0 ? { head: cmdOpts.head } : {},
+        // commander maps `--no-history` to `history === false`.
+        ...cmdOpts.history === false ? { noHistory: true } : {}
+      });
+      return;
+    }
+    process.exitCode = await moduleDiffCommand({
+      ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
+      ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
+    });
+  }
+);
 moduleCmd.command("pull-data").description("Export the module's own-table rows to a local JSON file (for fixtures, local dev seeding).").option("--dir <path>", "Project root (default: current directory).").option("--limit <n>", "Max rows per table (1-1000, default 100).", parseIntOption).option("--out <path>", "Output file path (default: ./dashwise-data.json).").action(async (cmdOpts) => {
   process.exitCode = await modulePullDataCommand({
     ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
@@ -24681,6 +25439,10 @@ program.command("query").description(
 ).option(
   "--stream",
   "Call .stream() instead of .execute() \u2014 prints rows incrementally as JSON-lines (one row per line). Lets you see progress on big queries + Ctrl-C cleanly midway. Mutually exclusive with --explain and --repl."
+).option(
+  "--install <id>",
+  "The install the key must belong to: reads that install's key list with your CLI login (one request, 1.5 s), prints `\u2192 install #<id> (key checked)` and refuses (exit 1) when DASHWISE_API_KEY is not an active key of that install or the list cannot be read.",
+  parseIntOption
 ).action(
   async (cmdOpts) => {
     process.exitCode = await queryCommand({
@@ -24690,16 +25452,22 @@ program.command("query").description(
       ...cmdOpts.repl !== void 0 ? { repl: cmdOpts.repl } : {},
       ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {},
       ...cmdOpts.explain !== void 0 ? { explain: cmdOpts.explain } : {},
-      ...cmdOpts.stream !== void 0 ? { stream: cmdOpts.stream } : {}
+      ...cmdOpts.stream !== void 0 ? { stream: cmdOpts.stream } : {},
+      ...cmdOpts.install !== void 0 ? { install: cmdOpts.install } : {}
     });
   }
 );
 program.command("run [cmd...]").description(
-  "Run a command with the module's Dashwise env injected \u2014 resolves DASHWISE_API_URL + DASHWISE_API_KEY through the same chain as `dashwise query` (explicit env \u2192 .env.local \u2192 the cached dwk_ key) and spawns the command with them overlaid, inheriting stdio and propagating the exit code. Example: `dashwise run -- node seed.mjs`."
-).option("--dir <path>", "Project root containing `module.json` (default: current directory).").action(async (cmdArgs, cmdOpts) => {
+  "Run a command with the module's Dashwise env injected \u2014 resolves DASHWISE_API_URL + DASHWISE_API_KEY through the same chain as `dashwise query` (explicit env \u2192 .env.local \u2192 the cached dwk_ key) and spawns the command with them overlaid, inheriting stdio and propagating the exit code. Names its target first (`\u2192 install #<id> (\u2026)`, at most one lookup request); `--install <id>` refuses a key of any other install. Example: `dashwise run --install 42 -- node seed.mjs`."
+).option("--dir <path>", "Project root containing `module.json` (default: current directory).").option(
+  "--install <id>",
+  "The install the key must belong to. Reads that install's key list with your CLI login (one request, 1.5 s), prints `\u2192 install #<id> (key checked)` and refuses (exit 1, nothing run) when DASHWISE_API_KEY is not an active key of that install or the list cannot be read.",
+  parseIntOption
+).action(async (cmdArgs, cmdOpts) => {
   const { runCommand: runCommand2 } = await Promise.resolve().then(() => (init_run(), run_exports));
   process.exitCode = await runCommand2(cmdArgs ?? [], {
-    ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {}
+    ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
+    ...cmdOpts.install !== void 0 ? { install: cmdOpts.install } : {}
   });
 });
 program.command("pull").description(
@@ -24826,13 +25594,17 @@ envCmd.command("export").description(
 ).option(
   "--key <dwk_value>",
   "Use a previously-minted API key (paste plaintext). (Mutually exclusive with --new-key.)"
+).option(
+  "--with-secret-names",
+  "Also name each secret declared in module.json runtime.secrets[] as a commented `# KEY=` line (a comment naming the command for railway/vercel/fly; stderr for json). Never a value: values never leave Dashwise; set them on your host."
 ).action(
   async (cmdOpts) => {
     process.exitCode = await envExportCommand({
       ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
       ...cmdOpts.format !== void 0 ? { format: cmdOpts.format } : {},
       ...cmdOpts.newKey !== void 0 ? { newKey: cmdOpts.newKey } : {},
-      ...cmdOpts.key !== void 0 ? { key: cmdOpts.key } : {}
+      ...cmdOpts.key !== void 0 ? { key: cmdOpts.key } : {},
+      ...cmdOpts.withSecretNames ? { withSecretNames: true } : {}
     });
   }
 );
@@ -24858,7 +25630,10 @@ moduleCmd.command("publish").description("Pack the current directory + upload it
 ).option(
   "--timeout <seconds>",
   "Max seconds to wait for an async build before giving up polling (default 360)."
-).option("--json", "Emit the final build result as machine-readable JSON.").action(
+).option("--json", "Emit the final build result as machine-readable JSON.").option(
+  "--strict",
+  "Refuse to publish when module.json is not an additive evolution of the released version (the `module diff --check` rules), or when that check cannot run. Without it the check only warns."
+).action(
   async (cmdOpts) => {
     const timeoutSec = cmdOpts.timeout !== void 0 ? Number(cmdOpts.timeout) : void 0;
     process.exitCode = await modulePublishCommand({
@@ -24874,19 +25649,23 @@ moduleCmd.command("publish").description("Pack the current directory + upload it
       // commander maps `--no-wait` to `wait === false`.
       ...cmdOpts.wait === false ? { noWait: true } : {},
       ...timeoutSec !== void 0 && Number.isFinite(timeoutSec) ? { timeoutSec } : {},
-      ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
+      ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {},
+      ...cmdOpts.strict !== void 0 ? { strict: cmdOpts.strict } : {}
     });
   }
 );
-moduleCmd.command("install [slug]").alias("deploy").description(
-  'Install (deploy) a published module into a workspace \u2014 provisions the runtime and prints the public URL. Upgrades/repairs an existing production install idempotently. When only a dev install exists it asks whether to install alongside it (--keep-dev-install) or replace it (--replace-dev-install), rather than silently landing on the dev row. Exits 3 \u2014 "deployed, setup pending" \u2014 when a required `uses` slot is still unbound: the deploy succeeded but the module throws on its first data call until an admin binds it.'
+moduleCmd.command("install [slug]").alias("deploy").alias("upgrade").description(
+  "Install (deploy) a published module into a workspace \u2014 provisions the runtime and prints the public URL. Upgrades/repairs an existing production install idempotently: an upgrade first prints what it does to the copy's data (tables and fields it moves to the Trash or converts, with their counts), asks once, and sends the preview's drift_hash. A move that loses data is accepted only by a person: the one question in a terminal, or --accept-data-loss <drift_hash> with the hash the preview printed. --yes never accepts data loss; with no terminal, or inside an AI agent session, a lossy move is refused and the refusal prints the re-run line. When only a dev install exists it asks whether to install alongside it (--keep-dev-install) or replace it (--replace-dev-install), rather than silently landing on the dev row. Exits 3 \u2014 \"deployed, setup pending\" \u2014 when a required `uses` slot is still unbound: the deploy succeeded but the module throws on its first data call until an admin binds it."
 ).option("--workspace <slug-or-id>", "Target workspace (default: cached module workspace, config default, or interactive picker).").option("--version <semver>", "Install a specific published version (default: latest).").option("--force", "Proceed even when the upgrade breaks consumer modules (UPGRADE_BREAKS_CONSUMERS).").option(
   "--keep-dev-install",
   "Install production ALONGSIDE the workspace's kind=local dev install, leaving local dev working. Non-destructive. Backends >= 2026-07-15 keep a separate live-install slot per kind group, so the two coexist."
 ).option(
   "--replace-dev-install",
   "Destroy the workspace's kind=local dev install first, then fresh production install. Revokes the cached local-dev credentials; on backends >= 2026-07-15 local dev can be re-provisioned afterwards (dashwise module reset-dev-install, or dashwise init <slug> --workspace <ws>) and will coexist with the production install. On OLDER backends this is one-way \u2014 prefer --keep-dev-install."
-).option("--dir <path>", "Project root for the module.json slug lookup (default: current directory).").option("-y, --yes", "Skip the confirmation prompt (for CI / scripted use).").option("--json", "Emit the final result as machine-readable JSON.").action(
+).option("--dir <path>", "Project root for the module.json slug lookup (default: current directory).").option("-y, --yes", "Skip the confirmation prompt (for CI / scripted use). Never accepts data loss: see --accept-data-loss.").option(
+  "--accept-data-loss <drift_hash>",
+  "Accept the data loss of this upgrade: the drift_hash its preview printed. Only that exact hash accepts it (a person decides; an agent stops and reports the hash)."
+).option("--json", "Emit the final result as machine-readable JSON.").action(
   async (slug, cmdOpts) => {
     process.exitCode = await moduleInstallCommand(slug, {
       ...cmdOpts.workspace !== void 0 ? { workspace: cmdOpts.workspace } : {},
@@ -24896,6 +25675,7 @@ moduleCmd.command("install [slug]").alias("deploy").description(
       ...cmdOpts.replaceDevInstall !== void 0 ? { replaceDevInstall: cmdOpts.replaceDevInstall } : {},
       ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
       ...cmdOpts.yes !== void 0 ? { yes: cmdOpts.yes } : {},
+      ...cmdOpts.acceptDataLoss !== void 0 ? { acceptDataLoss: cmdOpts.acceptDataLoss } : {},
       ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
     });
   }
@@ -25192,7 +25972,7 @@ fieldCmd.command("set-type <table-slug> <field-slug> <new-type>").description(
   }
 );
 function getVersion() {
-  return "0.25.0";
+  return "0.26.0";
 }
 function parseIntOption(value) {
   const n = Number.parseInt(value, 10);