@malloydata/malloyyo 0.2.30 → 0.2.32

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { resolve as resolve2 } from "node:path";
+import { resolve as resolve3 } from "node:path";
 
 // src/config.ts
 import { readFileSync, existsSync } from "node:fs";
@@ -51,11 +51,14 @@ The old shape still works for now.`
     targets
   };
 }
+var TARGETS_BLOCK_EXAMPLE = '  "malloyyo": {\n    "targets": { "prod": { "url": "https://<instance>", "dataset": "<dataset>" } }\n  }';
 function readTargetMap(dir) {
   const raw = readMalloyyoBlock(dir);
   if (raw) return parseMalloyyoConfig(raw).targets;
   throw new Error(
-    `No \`malloyyo\` config found in ${dir} (looked for a "malloyyo" block in malloy-config.json, then malloyyo.json).`
+    `No \`malloyyo\` config found in ${dir} (looked for a "malloyyo" block in malloy-config.json, then malloyyo.json).
+Add one to malloy-config.json:
+${TARGETS_BLOCK_EXAMPLE}`
   );
 }
 function readMalloyyoBlock(dir) {
@@ -85,6 +88,25 @@ function readSiteConfig(dir) {
 var normalizeUrl = (u) => u.replace(/\/+$/, "");
 function resolveTarget(dir, name) {
   const targets = readTargetMap(dir);
+  const entries = Object.entries(targets);
+  if (name === void 0) {
+    if (entries.length === 0) {
+      throw new Error(
+        `No publish targets defined. Add one to malloy-config.json:
+${TARGETS_BLOCK_EXAMPLE}`
+      );
+    }
+    if (entries.length > 1) {
+      throw new Error(`Multiple targets \u2014 specify which: ${entries.map(([n]) => n).join(", ")}.`);
+    }
+    const [onlyName, onlyCfg] = entries[0];
+    return {
+      name: onlyName,
+      url: normalizeUrl(onlyCfg.url),
+      dataset: onlyCfg.dataset,
+      tokenEnv: onlyCfg.malloyyo_token?.env
+    };
+  }
   const cfg = targets[name];
   if (!cfg) {
     const available = Object.keys(targets).join(", ") || "(none defined)";
@@ -2608,6 +2630,36 @@ function printLintReport(report) {
   }
 }
 
+// src/shared/env-refs.ts
+function missingEnvRefs(configJson, env = process.env) {
+  if (!configJson) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(configJson);
+  } catch {
+    return [];
+  }
+  const missing = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (Array.isArray(node)) return void node.forEach(walk);
+    if (typeof node !== "object" || node === null) return;
+    const rec = node;
+    if (typeof rec.env === "string" && !env[rec.env]) missing.add(rec.env);
+    for (const v of Object.values(rec)) walk(v);
+  };
+  walk(parsed);
+  return [...missing];
+}
+function missingEnvHint(missing, where) {
+  if (missing.length === 0) return "";
+  const vars = missing.map((v) => `$${v}`).join(", ");
+  const isAre = missing.length > 1 ? "are" : "is";
+  return `
+  malloy-config.json references ${vars}, which ${isAre} NOT set on ${where}.
+  Malloy reads an unset reference as an empty value, which usually shows up as
+  the connection error above.`;
+}
+
 // src/oauth.ts
 import http from "node:http";
 import crypto from "node:crypto";
@@ -2652,10 +2704,30 @@ function clearCreds(url6) {
   return true;
 }
 
+// package.json
+var version = "0.2.32";
+
+// src/http.ts
+var USER_AGENT = `malloyyo/${version}`;
+var UPGRADE_REQUIRED = 426;
+async function upgradeRequiredMessage(res) {
+  const body = await res.json().catch(() => ({}));
+  const needs = body.minimum_version ? ` ${body.minimum_version} or newer` : " a newer version";
+  return `This server requires${needs} of the malloyyo CLI (you have ${version}).
+Run:  npm i -g @malloydata/malloyyo`;
+}
+async function apiFetch(url6, init = {}) {
+  const headers = new Headers(init.headers);
+  headers.set("user-agent", USER_AGENT);
+  const res = await fetch(url6, { ...init, headers });
+  if (res.status === UPGRADE_REQUIRED) throw new Error(await upgradeRequiredMessage(res));
+  return res;
+}
+
 // src/oauth.ts
 var LOGIN_TIMEOUT_MS = 5 * 60 * 1e3;
 async function discover(baseUrl) {
-  const res = await fetch(`${baseUrl}/api/oauth/discovery/authorization-server`);
+  const res = await apiFetch(`${baseUrl}/api/oauth/discovery/authorization-server`);
   if (!res.ok) throw new Error(`OAuth discovery failed at ${baseUrl}: ${res.status} ${res.statusText}`);
   return await res.json();
 }
@@ -2665,7 +2737,7 @@ function pkce() {
   return { verifier, challenge };
 }
 async function registerClient(registrationEndpoint, redirectUri) {
-  const res = await fetch(registrationEndpoint, {
+  const res = await apiFetch(registrationEndpoint, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
@@ -2743,7 +2815,7 @@ async function login(baseUrl) {
 `);
     openBrowser(authUrl.toString());
     const authCode = await code;
-    const res = await fetch(ep.token_endpoint, {
+    const res = await apiFetch(ep.token_endpoint, {
       method: "POST",
       headers: { "content-type": "application/x-www-form-urlencoded" },
       body: new URLSearchParams({
@@ -2770,7 +2842,7 @@ async function login(baseUrl) {
 }
 async function refresh(baseUrl, creds) {
   const ep = await discover(baseUrl);
-  const res = await fetch(ep.token_endpoint, {
+  const res = await apiFetch(ep.token_endpoint, {
     method: "POST",
     headers: { "content-type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams({
@@ -2790,6 +2862,11 @@ async function refresh(baseUrl, creds) {
   saveCreds(baseUrl, updated);
   return updated;
 }
+function tokenSource(target, opts) {
+  if (opts.tokenFlag) return "flag";
+  if (target.tokenEnv && process.env[target.tokenEnv]) return "env";
+  return "login";
+}
 async function getAccessToken(target, opts) {
   if (opts.tokenFlag) return opts.tokenFlag;
   if (target.tokenEnv && process.env[target.tokenEnv]) return process.env[target.tokenEnv];
@@ -3037,6 +3114,11 @@ function urlStateFromSearch(search) {
   return s;
 }
 
+// src/shared/html.ts
+function safeJson(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+
 // src/shared/nav.ts
 var esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 var NAV_CSS = `
@@ -3217,7 +3299,7 @@ function makeInPageBundler() {
     return js;
   };
 }
-var html = (body, title) => `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title><meta name="viewport" content="width=device-width,initial-scale=1"><style>${NAV_CSS}</style></head><body style="margin:0">${body}</body></html>`;
+var html = (body, title) => `<!doctype html><html><head><meta charset="utf-8"><title>${esc2(title)}</title><meta name="viewport" content="width=device-width,initial-scale=1"><style>${NAV_CSS}</style></head><body style="margin:0">${body}</body></html>`;
 function navHtml2(dash, all) {
   return navHtml(dash.name, all, (n) => `/?d=${encodeURIComponent(n)}`);
 }
@@ -3234,14 +3316,14 @@ function inPageShell(dash, all, givenSpecs, initialGivens, initialUrlState, tile
     autorun: dash.autorun
   };
   return html(
-    navHtml2(dash, all) + `<div id="root"></div><script>window.__DASHBOARD__=${JSON.stringify(info)};window.__GIVENS__=${JSON.stringify(givenSpecs)};window.__INITIAL_GIVENS__=${JSON.stringify(initialGivens)};window.__INITIAL_URLSTATE__=${JSON.stringify(initialUrlState)}</script><script>try{new EventSource('/events').onmessage=()=>location.reload();}catch(e){}</script><script src="/inpage.js?d=${encodeURIComponent(dash.name)}"></script>`,
+    navHtml2(dash, all) + `<div id="root"></div><script>window.__DASHBOARD__=${safeJson(info)};window.__GIVENS__=${safeJson(givenSpecs)};window.__INITIAL_GIVENS__=${safeJson(initialGivens)};window.__INITIAL_URLSTATE__=${safeJson(initialUrlState)}</script><script>try{new EventSource('/events').onmessage=()=>location.reload();}catch(e){}</script><script src="/inpage.js?d=${encodeURIComponent(dash.name)}"></script>`,
     dash.title
   );
 }
 function parentShell(dash, frameBase, all, initialGivens, initialUrlState) {
   const givensQs = Object.entries({ ...initialGivens, ...initialUrlState }).map(([k, v]) => `&${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("");
-  const d = JSON.stringify(dash.name);
-  const fb = JSON.stringify(frameBase);
+  const d = safeJson(dash.name);
+  const fb = safeJson(frameBase);
   const nav = navHtml2(dash, all);
   return html(
     `<div style="display:flex;flex-direction:column;height:100vh">` + nav + // allow-popups(+escape-sandbox): let a # link mark open its target in a
@@ -3316,7 +3398,7 @@ function frameDoc(dash, givenSpecs, initialGivens, initialUrlState, tileSpecs) {
     autorun: dash.autorun
   };
   return html(
-    `<div id="root"></div><script>window.__DASHBOARD__=${JSON.stringify(info)};window.__GIVENS__=${JSON.stringify(givenSpecs)};window.__INITIAL_GIVENS__=${JSON.stringify(initialGivens)};window.__INITIAL_URLSTATE__=${JSON.stringify(initialUrlState)}</script><script src="/bundle.js?d=${encodeURIComponent(dash.name)}"></script>`,
+    `<div id="root"></div><script>window.__DASHBOARD__=${safeJson(info)};window.__GIVENS__=${safeJson(givenSpecs)};window.__INITIAL_GIVENS__=${safeJson(initialGivens)};window.__INITIAL_URLSTATE__=${safeJson(initialUrlState)}</script><script src="/bundle.js?d=${encodeURIComponent(dash.name)}"></script>`,
     dash.title
   );
 }
@@ -3515,7 +3597,7 @@ function serveStatic(dir, port) {
     res.writeHead(200, { "Content-Type": type, "Content-Length": st.size, "Accept-Ranges": "bytes" });
     fs6.createReadStream(file).pipe(res);
   });
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     let attempt = 0;
     const tryPort = (p) => {
       server.once("error", (err) => {
@@ -3531,7 +3613,7 @@ function serveStatic(dir, port) {
 (port ${port} busy \u2014 using ${p})`);
         console.log(`
 serving ${path7.basename(dir)}/ on http://localhost:${p}  (ctrl-c to stop)`);
-        resolve3();
+        resolve4();
       });
     };
     tryPort(port);
@@ -3664,12 +3746,12 @@ ${analyticsSnippet(analytics)}
 ${navFor(dash, all, cleanUrls)}
 <div id="root"></div>
 <script>
-window.__DASHBOARD__ = ${JSON.stringify(info)};
+window.__DASHBOARD__ = ${safeJson(info)};
 // Given SPECS (label/type/default/suggest) are introspected from the model's
 // given: declarations at BUILD time \u2014 the runtime reads them from here to draw
 // controls and seed initial values. Without them there are no controls and
 // every given starts empty.
-window.__GIVENS__ = ${JSON.stringify(givenSpecs)};
+window.__GIVENS__ = ${safeJson(givenSpecs)};
 // __INITIAL_GIVENS__ is NOT set here on purpose: the entry bundle sets it from
 // location.search using shared/givens-url, the same encoder the dev server uses.
 // An inline copy is what drifted last time (it stripped the dollar-sign prefix
@@ -3684,7 +3766,7 @@ window.__GIVENS__ = ${JSON.stringify(givenSpecs)};
 function indexPage(dashboards, title, custom, cleanUrls, analytics) {
   const link = (n) => cleanUrls ? `./${encodeURIComponent(n)}` : `./${encodeURIComponent(n)}.html`;
   const body = custom ? `<div id="root"></div>
-<script>window.__DASHBOARDS__ = ${JSON.stringify(
+<script>window.__DASHBOARDS__ = ${safeJson(
     dashboards.map((d) => ({ name: d.name, title: d.title, description: d.description, href: link(d.name) }))
   )};</script>
 <script type="module" src="./assets/index.js"></script>` : `<main class="index"><h1>${esc3(title)}</h1><ul>` + dashboards.map(
@@ -4187,30 +4269,942 @@ async function launchCmd(mode, opts) {
     stdio: "inherit",
     cwd: root
   });
-  await new Promise((resolve3) => {
+  await new Promise((resolve4) => {
     child.on("error", (e) => {
       process.stderr.write(
         `\u2717 could not launch \`claude\`: ${e.message}
   (is Claude Code installed and on PATH?)
 `
       );
-      resolve3();
+      resolve4();
     });
-    child.on("exit", () => resolve3());
+    child.on("exit", () => resolve4());
   });
   fs10.rmSync(tmpDir, { recursive: true, force: true });
 }
 
-// package.json
-var version = "0.2.30";
+// src/cloud/index.ts
+import { resolve as resolve2 } from "node:path";
+
+// src/cloud/infer.ts
+var HOSTED_DOMAIN_SUFFIX = ".malloyyo.com";
+var InstanceInferenceError = class extends Error {
+};
+function inferInstance(dir) {
+  let resolved;
+  try {
+    resolved = resolveInstance(dir);
+  } catch (error) {
+    throw new InstanceInferenceError(
+      `no instance given, and none could be inferred from malloy-config.json: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  let hostname;
+  try {
+    hostname = new URL(resolved.url).hostname;
+  } catch {
+    throw new InstanceInferenceError(
+      `no instance given, and the config target "${resolved.name}" has a URL this command cannot parse`
+    );
+  }
+  if (!hostname.endsWith(HOSTED_DOMAIN_SUFFIX)) {
+    throw new InstanceInferenceError(
+      `no instance given, and the config target "${resolved.name}" points at ${hostname}, which is not a Malloyyo-hosted instance \u2014 name the instance explicitly`
+    );
+  }
+  const slug = hostname.slice(0, hostname.indexOf("."));
+  if (slug === "") {
+    throw new InstanceInferenceError(
+      `no instance given, and the config target "${resolved.name}" points at the bare hosted domain`
+    );
+  }
+  return { slug, targetName: resolved.name };
+}
+
+// src/cloud/api.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+var ControlPlaneError = class extends Error {
+  constructor(status2, code, message2) {
+    super(message2);
+    this.status = status2;
+    this.code = code;
+    this.name = "ControlPlaneError";
+  }
+};
+function isTransientStatus(status2) {
+  return status2 >= 500 || status2 === 429;
+}
+function isNetworkError(error) {
+  return error instanceof TypeError;
+}
+var NON_JSON_DETAIL = "the control plane returned a body that is not JSON; check that MALLOYYO_API_URL points at the control plane and not at something in front of it";
+var DEFAULT_MAX_ATTEMPTS = 3;
+var RETRY_BASE_DELAY_MS = 500;
+var NOT_JSON = Symbol("not-json");
+function parseBody(text) {
+  if (text === "") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return NOT_JSON;
+  }
+}
+function createControlPlaneClient(options) {
+  const doFetch = options.fetch ?? apiFetch;
+  const base = options.apiUrl.replace(/\/+$/, "");
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve4) => setTimeout(resolve4, ms)));
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  async function attempt(method, path12, extra) {
+    const token = await options.getAccessToken();
+    const headers = {
+      authorization: `Bearer ${token}`,
+      accept: "application/json"
+    };
+    if (extra?.idempotencyKey !== void 0) headers["idempotency-key"] = extra.idempotencyKey;
+    if (extra?.body !== void 0) headers["content-type"] = "application/json";
+    const response = await doFetch(`${base}${path12}`, {
+      method,
+      headers,
+      ...extra?.body === void 0 ? {} : { body: JSON.stringify(extra.body) }
+    });
+    const parsed = parseBody(await response.text());
+    if (!response.ok) {
+      const body = parsed === NOT_JSON ? void 0 : parsed;
+      const code = isRecord(body) && typeof body.error === "string" ? body.error : "error";
+      const detail = isRecord(body) && typeof body.message === "string" ? body.message : parsed === NOT_JSON ? NON_JSON_DETAIL : code;
+      throw new ControlPlaneError(response.status, code, detail);
+    }
+    if (parsed === NOT_JSON) {
+      throw new ControlPlaneError(response.status, "invalid_response", NON_JSON_DETAIL);
+    }
+    return parsed;
+  }
+  async function request(method, path12, extra) {
+    for (let attemptNumber = 1; ; attemptNumber += 1) {
+      try {
+        return await attempt(method, path12, extra);
+      } catch (error) {
+        const transient = error instanceof ControlPlaneError ? isTransientStatus(error.status) : isNetworkError(error);
+        if (!transient || attemptNumber >= maxAttempts) throw error;
+      }
+      await sleep(RETRY_BASE_DELAY_MS * attemptNumber);
+    }
+  }
+  function expectRecord(value) {
+    if (!isRecord(value)) {
+      throw new Error("the control plane returned a response that was not a JSON object");
+    }
+    return value;
+  }
+  function expectField(body, field) {
+    const value = body[field];
+    if (!isRecord(value) && !Array.isArray(value)) {
+      throw new Error(`the control plane's response carried no \`${field}\``);
+    }
+    return value;
+  }
+  return {
+    async createInstance({ slug, idempotencyKey }) {
+      const body = expectRecord(
+        await request("POST", "/v1/instances", { idempotencyKey, body: { slug } })
+      );
+      return {
+        instance: expectField(body, "instance"),
+        operation: expectField(body, "operation")
+      };
+    },
+    async getInstance(id) {
+      const body = expectRecord(await request("GET", `/v1/instances/${encodeURIComponent(id)}`));
+      return expectField(body, "instance");
+    },
+    async listInstances() {
+      const body = expectRecord(await request("GET", "/v1/instances"));
+      return expectField(body, "instances");
+    },
+    async deleteInstance({ id, idempotencyKey }) {
+      const body = expectRecord(
+        await request("DELETE", `/v1/instances/${encodeURIComponent(id)}`, { idempotencyKey })
+      );
+      return {
+        instance: expectField(body, "instance"),
+        // Documented as nullable on this endpoint alone; see `ControlPlaneClient`.
+        operation: body.operation === null ? null : expectField(body, "operation")
+      };
+    },
+    async setInstanceSecrets({ id, values, idempotencyKey }) {
+      const body = expectRecord(
+        await request("POST", `/v1/instances/${encodeURIComponent(id)}/secrets`, {
+          idempotencyKey,
+          body: { secrets: values }
+        })
+      );
+      return {
+        instance: expectField(body, "instance"),
+        operation: expectField(body, "operation"),
+        secrets: expectField(body, "secrets")
+      };
+    },
+    async unsetInstanceSecrets({ id, names, idempotencyKey }) {
+      const body = expectRecord(
+        await request("DELETE", `/v1/instances/${encodeURIComponent(id)}/secrets`, {
+          idempotencyKey,
+          body: { names }
+        })
+      );
+      return {
+        instance: expectField(body, "instance"),
+        operation: expectField(body, "operation"),
+        secrets: expectField(body, "secrets")
+      };
+    },
+    async listInstanceSecrets(id) {
+      const body = expectRecord(
+        await request("GET", `/v1/instances/${encodeURIComponent(id)}/secrets`)
+      );
+      return {
+        instance: expectField(body, "instance"),
+        secrets: expectField(body, "secrets")
+      };
+    },
+    async getOperation(id) {
+      const body = expectRecord(await request("GET", `/v1/operations/${encodeURIComponent(id)}`));
+      return expectField(body, "operation");
+    }
+  };
+}
+
+// src/cloud/commands.ts
+import { randomUUID } from "node:crypto";
+var STEP_LABELS = {
+  create_sign_in: "Setting up sign-in",
+  seat_administrator: "Adding you as administrator",
+  register_hostname: "Authorizing your address for sign-in",
+  create_database: "Creating your database",
+  reserve_instance: "Reserving your instance",
+  store_credentials: "Storing credentials",
+  start_instance: "Starting your instance",
+  start_standby: "Preparing standby capacity",
+  wait_for_startup: "Waiting for it to come up",
+  setup_check: "Checking it responds",
+  record_success: "Finishing up",
+  // The secrets roll. The standby first — it is updated while stopped, so it costs
+  // nothing — then the one actually serving, which is the brief interruption.
+  update_standby: "Updating standby capacity",
+  update_instance: "Applying to your instance"
+};
+var COMMAND_SCOPES = {
+  create: ["instances:create", "instances:read"],
+  status: ["instances:read"],
+  list: ["instances:read"],
+  delete: ["instances:delete", "instances:read"],
+  // `secrets:write` is deliberately not an `instances:*` scope: it can replace the
+  // credentials a tenant queries its own warehouse with, which is well outside the blast
+  // radius the instance-management scopes are bounded to. `instances:read` comes along for
+  // the same reason `create` carries it — this command polls the operation it opens and
+  // re-reads the instance, and the control plane gates both GETs on read.
+  "secrets set": ["secrets:write", "instances:read"],
+  // Removal is a write to the same configuration, so it is the same scope — there is
+  // still no read scope, and nothing here for one to read.
+  "secrets unset": ["secrets:write", "instances:read"],
+  // Listing serves names and digests, which the write scope already learns from every
+  // set and unset response — there is no value anywhere on this path to gate. No
+  // `instances:read`: nothing is polled and nothing re-read.
+  "secrets list": ["secrets:write"]
+};
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var DEFAULT_MAX_OPERATION_WAIT_MS = 10 * 60 * 1e3;
+function instanceUrl(instance) {
+  return instance.hostname === null ? null : `https://${instance.hostname}`;
+}
+function printInstance(ctx, instance) {
+  const url6 = instanceUrl(instance);
+  ctx.out(`  ${instance.slug}  (${instance.id})`);
+  ctx.out(`    lifecycle: ${instance.lifecycle}`);
+  if (url6 !== null) ctx.out(`    url:       ${url6}`);
+}
+function formatDuration(ms) {
+  const seconds = Math.max(0, Math.round(ms / 1e3));
+  const minutes = Math.floor(seconds / 60);
+  return minutes === 0 ? `${seconds}s` : `${minutes}m ${seconds % 60}s`;
+}
+async function waitForOperation(ctx, operation) {
+  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve4) => setTimeout(resolve4, ms)));
+  const now = ctx.now ?? Date.now;
+  const interval = ctx.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const maxWait = ctx.maxOperationWaitMs ?? DEFAULT_MAX_OPERATION_WAIT_MS;
+  const startedAt = now();
+  const deadline = startedAt + maxWait;
+  const reported = /* @__PURE__ */ new Set();
+  const report = (current2) => {
+    if (ctx.json) return;
+    for (const step of current2.steps ?? []) {
+      if (reported.has(step.key)) continue;
+      reported.add(step.key);
+      const label = STEP_LABELS[step.key];
+      if (label !== void 0) ctx.out(`  \u2713 ${label}`);
+    }
+  };
+  let current = operation;
+  report(current);
+  while (current.status === "running") {
+    if (now() >= deadline) {
+      current = await ctx.client.getOperation(current.id);
+      report(current);
+      break;
+    }
+    await sleep(interval);
+    current = await ctx.client.getOperation(current.id);
+    report(current);
+  }
+  return { operation: current, waitedMs: now() - startedAt };
+}
+async function reportOperation(ctx, operation, instanceId, verb) {
+  if (operation === null) {
+    const instance = await ctx.client.getInstance(instanceId);
+    if (ctx.json) {
+      ctx.out(JSON.stringify({ operation: null, instance }, null, 2));
+    } else {
+      ctx.out(`${verb} succeeded: the instance was already ${instance.lifecycle}.`);
+      printInstance(ctx, instance);
+    }
+    return 0;
+  }
+  const { operation: final, waitedMs } = await waitForOperation(ctx, operation);
+  if (final.status === "succeeded") {
+    const instance = await ctx.client.getInstance(instanceId);
+    if (ctx.json) {
+      ctx.out(JSON.stringify({ operation: final, instance }, null, 2));
+    } else {
+      ctx.out(`${verb} succeeded:`);
+      printInstance(ctx, instance);
+      const url6 = instanceUrl(instance);
+      if (verb === "create" && url6 !== null) {
+        ctx.out("");
+        ctx.out("Add this to malloy-config.json in your model repo:");
+        ctx.out("");
+        ctx.out(`  "malloyyo": {`);
+        ctx.out(`    "targets": {`);
+        ctx.out(`      "${instance.slug}": { "url": "${url6}", "dataset": "<dataset>" }`);
+        ctx.out(`    }`);
+        ctx.out(`  }`);
+        ctx.out("");
+        ctx.out(`Sign in at ${url6}`);
+        ctx.out(`Then, from that repo:  malloyyo login && malloyyo publish`);
+      }
+    }
+    return 0;
+  }
+  if (final.status === "failed") {
+    if (ctx.json) {
+      ctx.out(JSON.stringify({ operation: final }, null, 2));
+    } else {
+      ctx.out(`${verb} failed: ${final.error ?? "unknown error"}`);
+    }
+    return 1;
+  }
+  if (ctx.json) {
+    ctx.out(JSON.stringify({ operation: final }, null, 2));
+  } else {
+    ctx.out(
+      `Stopped waiting after ${formatDuration(waitedMs)} \u2014 this is the CLI giving up, not the ${verb} failing.`
+    );
+    ctx.out(
+      `The ${verb} is still running server-side (operation ${final.id}). Check it with \`malloyyo cloud instance status\`.`
+    );
+  }
+  return 0;
+}
+async function createCommand(ctx, args) {
+  const idempotencyKey = (ctx.newIdempotencyKey ?? randomUUID)();
+  const { instance, operation } = await ctx.client.createInstance({
+    slug: args.slug,
+    idempotencyKey
+  });
+  if (!ctx.json) ctx.out(`creating instance "${args.slug}" (operation ${operation.id})\u2026`);
+  return reportOperation(ctx, operation, instance.id, "create");
+}
+var DEFAULT_BUSY_POLL_INTERVAL_MS = 5e3;
+var DEFAULT_MAX_BUSY_WAIT_MS = 5 * 60 * 1e3;
+var InvalidSecretArgumentError = class extends Error {
+  constructor(message2) {
+    super(message2);
+    this.name = "InvalidSecretArgumentError";
+  }
+};
+function parseSecretArguments(args) {
+  if (args.length === 0) {
+    throw new InvalidSecretArgumentError("give at least one NAME or NAME=value");
+  }
+  const parsed = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index2, argument] of args.entries()) {
+    const separator = argument.indexOf("=");
+    if (separator === 0) {
+      throw new InvalidSecretArgumentError(`argument ${index2 + 1} has no name before its "="`);
+    }
+    const name = separator === -1 ? argument : argument.slice(0, separator);
+    if (name === "") throw new InvalidSecretArgumentError(`argument ${index2 + 1} is empty`);
+    if (seen.has(name)) throw new InvalidSecretArgumentError(`"${name}" was given more than once`);
+    seen.add(name);
+    parsed.push(separator === -1 ? { name } : { name, value: argument.slice(separator + 1) });
+  }
+  return parsed;
+}
+function parseSecretLines(text) {
+  const values = {};
+  for (const [index2, rawLine] of text.split("\n").entries()) {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    const separator = line.indexOf("=");
+    if (separator <= 0) {
+      throw new InvalidSecretArgumentError(`line ${index2 + 1} is not a NAME=value pair`);
+    }
+    const name = line.slice(0, separator).trim();
+    if (name in values) {
+      throw new InvalidSecretArgumentError(`"${name}" appears on more than one line`);
+    }
+    values[name] = line.slice(separator + 1);
+  }
+  if (Object.keys(values).length === 0) {
+    throw new InvalidSecretArgumentError("stdin carried no NAME=value pairs");
+  }
+  return values;
+}
+function isInstanceBusy(error) {
+  return error instanceof ControlPlaneError && error.code === "instance_busy";
+}
+function rejectInstanceAsSecretName(id, parsed) {
+  const looksLikeTheInstance = parsed.some(
+    (argument) => argument.value === void 0 && argument.name === id
+  );
+  if (looksLikeTheInstance) {
+    throw new InvalidSecretArgumentError(
+      `"${id}" is the instance, not a secret name \u2014 it is no longer a positional argument.
+Run this inside the model repo that publishes to it, or pass it as -i ${id}.`
+    );
+  }
+}
+async function resolveSecretValues(ctx, args) {
+  if (args.stdin === true) {
+    if (args.assignments.length > 0) {
+      throw new InvalidSecretArgumentError("--stdin takes the pairs on stdin, not as arguments");
+    }
+    if (ctx.readStdin === void 0) {
+      throw new InvalidSecretArgumentError("--stdin is not available here");
+    }
+    return parseSecretLines(await ctx.readStdin());
+  }
+  const parsed = parseSecretArguments(args.assignments);
+  rejectInstanceAsSecretName(args.id, parsed);
+  const values = {};
+  for (const argument of parsed) {
+    if (argument.value !== void 0) {
+      values[argument.name] = argument.value;
+      continue;
+    }
+    if (ctx.promptSecret === void 0) {
+      throw new InvalidSecretArgumentError(
+        `no value given for "${argument.name}", and there is no terminal to prompt on; pass it with --stdin instead`
+      );
+    }
+    const value = await ctx.promptSecret(argument.name);
+    if (value === "") {
+      throw new InvalidSecretArgumentError(`no value entered for "${argument.name}"`);
+    }
+    values[argument.name] = value;
+  }
+  return values;
+}
+async function secretsSetCommand(ctx, args) {
+  const values = await resolveSecretValues(ctx, args);
+  const names = Object.keys(values);
+  const idempotencyKey = (ctx.newIdempotencyKey ?? randomUUID)();
+  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve4) => setTimeout(resolve4, ms)));
+  const now = ctx.now ?? Date.now;
+  const deadline = now() + (ctx.maxBusyWaitMs ?? DEFAULT_MAX_BUSY_WAIT_MS);
+  let result;
+  let announcedWait = false;
+  for (; ; ) {
+    try {
+      result = await ctx.client.setInstanceSecrets({ id: args.id, values, idempotencyKey });
+      break;
+    } catch (error) {
+      if (!isInstanceBusy(error) || now() >= deadline) throw error;
+      if (!ctx.json && !announcedWait) {
+        ctx.out("another operation is running on this instance, waiting\u2026");
+        announcedWait = true;
+      }
+    }
+    await sleep(ctx.busyPollIntervalMs ?? DEFAULT_BUSY_POLL_INTERVAL_MS);
+  }
+  if (!ctx.json) {
+    ctx.out(`setting ${names.join(", ")} on "${result.instance.slug}"\u2026`);
+  }
+  return reportOperation(ctx, result.operation, result.instance.id, "secrets set");
+}
+function parseUnsetNames(raw) {
+  if (raw.length === 0) {
+    throw new InvalidSecretArgumentError("give at least one secret name to unset");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of raw) {
+    if (name.includes("=")) {
+      throw new InvalidSecretArgumentError(
+        `unset takes names, not NAME=value pairs (got "${name.slice(0, name.indexOf("="))}=\u2026")`
+      );
+    }
+    if (seen.has(name)) {
+      throw new InvalidSecretArgumentError(`"${name}" appears more than once`);
+    }
+    seen.add(name);
+  }
+  return raw;
+}
+async function secretsUnsetCommand(ctx, args) {
+  const names = parseUnsetNames(args.names);
+  rejectInstanceAsSecretName(
+    args.id,
+    names.map((name) => ({ name }))
+  );
+  const idempotencyKey = (ctx.newIdempotencyKey ?? randomUUID)();
+  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve4) => setTimeout(resolve4, ms)));
+  const now = ctx.now ?? Date.now;
+  const deadline = now() + (ctx.maxBusyWaitMs ?? DEFAULT_MAX_BUSY_WAIT_MS);
+  let result;
+  let announcedWait = false;
+  for (; ; ) {
+    try {
+      result = await ctx.client.unsetInstanceSecrets({ id: args.id, names, idempotencyKey });
+      break;
+    } catch (error) {
+      if (!isInstanceBusy(error) || now() >= deadline) throw error;
+      if (!ctx.json && !announcedWait) {
+        ctx.out("another operation is running on this instance, waiting\u2026");
+        announcedWait = true;
+      }
+    }
+    await sleep(ctx.busyPollIntervalMs ?? DEFAULT_BUSY_POLL_INTERVAL_MS);
+  }
+  if (!ctx.json) {
+    const wasRemoved = result.secrets.filter((secret) => secret.removed).map((s) => s.name);
+    const wasAbsent = result.secrets.filter((secret) => !secret.removed).map((s) => s.name);
+    if (wasRemoved.length > 0) {
+      ctx.out(`removing ${wasRemoved.join(", ")} from "${result.instance.slug}"\u2026`);
+    }
+    for (const name of wasAbsent) {
+      ctx.out(`  ${name} was not set`);
+    }
+  }
+  return reportOperation(ctx, result.operation, result.instance.id, "secrets unset");
+}
+async function secretsListCommand(ctx, args) {
+  const { instance, secrets } = await ctx.client.listInstanceSecrets(args.id);
+  if (ctx.json) {
+    ctx.out(JSON.stringify({ instance, secrets }, null, 2));
+    return 0;
+  }
+  if (secrets.length === 0) {
+    ctx.out(`no secrets set on "${instance.slug}".`);
+    return 0;
+  }
+  const width = Math.max(...secrets.map((secret) => secret.name.length));
+  for (const secret of secrets) {
+    ctx.out(`  ${secret.name.padEnd(width)}  ${secret.digest ?? ""}`.trimEnd());
+  }
+  return 0;
+}
+async function statusCommand(ctx, args) {
+  const instance = await ctx.client.getInstance(args.id);
+  if (ctx.json) {
+    ctx.out(JSON.stringify(instance, null, 2));
+  } else {
+    printInstance(ctx, instance);
+  }
+  return 0;
+}
+async function listCommand(ctx) {
+  const instances = await ctx.client.listInstances();
+  if (ctx.json) {
+    ctx.out(JSON.stringify(instances, null, 2));
+    return 0;
+  }
+  if (instances.length === 0) {
+    ctx.out("no instances.");
+    return 0;
+  }
+  ctx.out(`${instances.length} instance${instances.length === 1 ? "" : "s"}:`);
+  for (const instance of instances) printInstance(ctx, instance);
+  return 0;
+}
+async function deleteCommand(ctx, args) {
+  const idempotencyKey = (ctx.newIdempotencyKey ?? randomUUID)();
+  const { instance, operation } = await ctx.client.deleteInstance({
+    id: args.id,
+    idempotencyKey
+  });
+  if (!ctx.json && operation !== null) {
+    ctx.out(`deleting instance "${instance.slug}" (operation ${operation.id})\u2026`);
+  }
+  return reportOperation(ctx, operation, instance.id, "delete");
+}
+
+// src/cloud/config.ts
+var DEFAULT_API_URL = "https://api.malloyyo.com";
+var MissingCloudConfigError = class extends Error {
+  constructor(names) {
+    super(
+      `missing required configuration: ${names.join(", ")}.
+Set them as environment variables. Your credential comes from Malloyyo when your account is created.`
+    );
+    this.names = names;
+    this.name = "MissingCloudConfigError";
+  }
+};
+var ENV_NAMES = {
+  apiUrl: "MALLOYYO_API_URL",
+  clientId: "MALLOYYO_CLIENT_ID",
+  clientSecret: "MALLOYYO_CLIENT_SECRET"
+};
+function loadCloudConfig(env) {
+  const read = (key) => {
+    const raw = env[ENV_NAMES[key]];
+    return raw === void 0 || raw.trim() === "" ? void 0 : raw.trim();
+  };
+  const values = {
+    apiUrl: read("apiUrl") ?? DEFAULT_API_URL,
+    clientId: read("clientId"),
+    clientSecret: read("clientSecret")
+  };
+  const missing = Object.keys(values).filter((key) => values[key] === void 0).map((key) => ENV_NAMES[key]);
+  if (missing.length > 0) throw new MissingCloudConfigError(missing);
+  return values;
+}
+
+// src/cloud/token-source.ts
+var DEFAULT_REFRESH_SKEW_SECONDS = 60;
+function createCredentialExchange(config) {
+  const base = config.apiUrl.replace(/\/+$/, "");
+  return async (scopes) => {
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: config.clientId,
+      client_secret: config.clientSecret
+    });
+    if (scopes.length > 0) body.set("scope", scopes.join(" "));
+    const response = await apiFetch(`${base}/v1/token`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        accept: "application/json"
+      },
+      body: body.toString()
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = text === "" ? void 0 : JSON.parse(text);
+    } catch {
+      parsed = void 0;
+    }
+    const fields = typeof parsed === "object" && parsed !== null ? parsed : {};
+    if (!response.ok) {
+      const code = typeof fields.error === "string" ? fields.error : "error";
+      throw new ControlPlaneError(
+        response.status,
+        code,
+        // The server deliberately says nothing about *why* a credential was rejected, so
+        // the actionable sentence has to come from here — it is the side that knows which
+        // two environment variables the values came from.
+        code === "invalid_client" ? "your Malloyyo credentials were rejected. Check MALLOYYO_CLIENT_ID and MALLOYYO_CLIENT_SECRET, and that your account is still active." : typeof fields.message === "string" ? fields.message : `could not get an access token (${code})`
+      );
+    }
+    if (typeof fields.access_token !== "string" || typeof fields.expires_in !== "number") {
+      throw new ControlPlaneError(
+        response.status,
+        "invalid_response",
+        "the control plane returned no access token; check that MALLOYYO_API_URL points at it"
+      );
+    }
+    return { accessToken: fields.access_token, expiresIn: fields.expires_in };
+  };
+}
+function createCachedTokenSource(exchange, scopes, options = {}) {
+  const now = options.now ?? Date.now;
+  const skewMs = (options.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
+  let cached = null;
+  let inFlight = null;
+  async function fetchToken() {
+    const grant = await exchange(scopes);
+    cached = {
+      accessToken: grant.accessToken,
+      renewAtMs: now() + grant.expiresIn * 1e3 - skewMs
+    };
+    return grant.accessToken;
+  }
+  return {
+    async getAccessToken() {
+      if (cached !== null && now() < cached.renewAtMs) return cached.accessToken;
+      inFlight ??= fetchToken().finally(() => {
+        inFlight = null;
+      });
+      return inFlight;
+    }
+  };
+}
+function createCloudTokenSource(config, scopes) {
+  return createCachedTokenSource(createCredentialExchange(config), scopes);
+}
+
+// src/cloud/run.ts
+function defaultClientFactory(config, scopes) {
+  const tokenSource2 = createCloudTokenSource(config, scopes);
+  return createControlPlaneClient({
+    apiUrl: config.apiUrl,
+    getAccessToken: () => tokenSource2.getAccessToken()
+  });
+}
+async function runCloud(invocation, deps) {
+  let config;
+  try {
+    config = loadCloudConfig(deps.env);
+  } catch (error) {
+    if (error instanceof MissingCloudConfigError) {
+      deps.err(error.message);
+      return 2;
+    }
+    throw error;
+  }
+  const makeClient = deps.makeClient ?? defaultClientFactory;
+  let ctx;
+  try {
+    ctx = {
+      client: makeClient(config, COMMAND_SCOPES[invocation.command]),
+      out: deps.out,
+      json: deps.json === true,
+      // `promptSecret` is absent when stdin is not a terminal, and that absence is what
+      // turns a bare NAME under a pipe into a clear "use --stdin" error instead of a
+      // command that hangs on input that is never coming.
+      ...deps.readStdin === void 0 ? {} : { readStdin: deps.readStdin },
+      ...deps.promptSecret === void 0 ? {} : { promptSecret: deps.promptSecret }
+    };
+  } catch (error) {
+    deps.err(
+      `could not build a control-plane client from the environment: ${error instanceof Error ? error.message : "unknown error"}`
+    );
+    return 2;
+  }
+  try {
+    switch (invocation.command) {
+      case "create":
+        return await createCommand(ctx, { slug: invocation.slug });
+      case "status":
+        return await statusCommand(ctx, { id: invocation.id });
+      case "list":
+        return await listCommand(ctx);
+      case "delete":
+        return await deleteCommand(ctx, { id: invocation.id });
+      case "secrets set":
+        return await secretsSetCommand(ctx, {
+          id: invocation.id,
+          assignments: invocation.assignments,
+          stdin: invocation.stdin
+        });
+      case "secrets unset":
+        return await secretsUnsetCommand(ctx, { id: invocation.id, names: invocation.names });
+      case "secrets list":
+        return await secretsListCommand(ctx, { id: invocation.id });
+    }
+  } catch (error) {
+    if (error instanceof InvalidSecretArgumentError) {
+      deps.err(error.message);
+      return 2;
+    }
+    if (error instanceof ControlPlaneError) {
+      deps.err(`error (${error.status}): ${error.message}`);
+      return 1;
+    }
+    deps.err(error instanceof Error ? error.message : "an unexpected error occurred");
+    return 1;
+  }
+}
+
+// src/cloud/index.ts
+async function readStdin2() {
+  process.stdin.setEncoding("utf8");
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  return text;
+}
+async function promptSecret(name) {
+  const { default: password } = await import("@inquirer/password");
+  try {
+    return await password({ message: `Value for ${name} (hidden):` }, { output: process.stderr });
+  } catch (error) {
+    if (error instanceof Error && error.name === "ExitPromptError") {
+      throw new Error(`entering ${name} was cancelled`);
+    }
+    throw error;
+  }
+}
+function resolveOrInferInstance(given) {
+  if (given !== void 0) return given;
+  try {
+    const inferred = inferInstance(resolve2("."));
+    process.stderr.write(
+      `using instance ${inferred.slug} (from malloy-config.json target "${inferred.targetName}")
+`
+    );
+    return inferred.slug;
+  } catch (error) {
+    if (error instanceof InstanceInferenceError) {
+      process.stderr.write(`${error.message}
+`);
+      process.exitCode = 2;
+      return null;
+    }
+    throw error;
+  }
+}
+async function dispatch(invocation, json) {
+  process.exitCode = await runCloud(invocation, {
+    env: process.env,
+    out: (line) => process.stdout.write(`${line}
+`),
+    err: (line) => process.stderr.write(`${line}
+`),
+    json,
+    readStdin: readStdin2,
+    // Only when there is a terminal to prompt on. Its absence is what lets a bare `NAME`
+    // under a pipe fail with "use --stdin" instead of hanging forever on input that is never
+    // coming.
+    ...process.stdin.isTTY === true ? { promptSecret } : {}
+  });
+}
+var SECRETS_SET_HELP = `Secrets are the values your Malloy models resolve warehouse connections from, as
+{ "env": "NAME" } in malloy-config.json. Several in one command are applied together.
+The command returns once they are live; your instance restarts briefly. Values are
+stored only by the instance host and are never readable back through this CLI.
+
+Run inside your model repo and the instance is the one its malloy-config.json
+publishes to; -i names a different one explicitly.
+
+A value typed as NAME=value goes into your shell history and is visible to other
+processes while the command runs. Two ways to avoid that:
+
+  malloyyo cloud secrets set PG_HOST=db.example.com PG_USER=app PG_PASSWORD
+      a bare NAME is prompted for, with the input hidden
+
+  op read op://vault/pg/password | malloyyo cloud secrets set --stdin
+      --stdin reads NAME=value lines: a file, a CI variable, a password manager`;
+function registerCloudCommands(program2) {
+  const cloud = program2.command("cloud").description("manage Malloyyo-hosted instances").addHelpText(
+    "after",
+    "\nCredentials come from MALLOYYO_CLIENT_ID and MALLOYYO_CLIENT_SECRET.\n"
+  );
+  const instance = cloud.command("instance").description("create and manage hosted instances");
+  instance.command("create").argument("<slug>", "the name your instance is reached at: <slug>.malloyyo.com").option("--json", "print the result as JSON instead of progress lines").description("provision a new hosted instance and wait for it to come up").action(async (slug, opts) => {
+    await dispatch({ command: "create", slug }, opts.json === true);
+  });
+  instance.command("status").argument("[instance]", "instance name (the one in its URL) or ID; inferred from malloy-config.json when omitted").option("--json", "print the instance as JSON").description("show an instance's lifecycle, URL, and observed state").action(async (instance2, opts) => {
+    const id = resolveOrInferInstance(instance2);
+    if (id === null) return;
+    await dispatch({ command: "status", id }, opts.json === true);
+  });
+  instance.command("list").option("--json", "print the instances as JSON").description("list your hosted instances").action(async (opts) => {
+    await dispatch({ command: "list" }, opts.json === true);
+  });
+  instance.command("delete").argument("<instance>", "instance name (the one in its URL) or ID").option("--json", "print the result as JSON instead of progress lines").description("delete an instance (reversible until it is destroyed)").action(async (instance2, opts) => {
+    await dispatch({ command: "delete", id: instance2 }, opts.json === true);
+  });
+  const secrets = cloud.command("secrets").description("manage an instance's warehouse secrets");
+  const instanceOption = [
+    "-i, --instance <instance>",
+    "instance name (the one in its URL) or ID; otherwise inferred from malloy-config.json"
+  ];
+  secrets.command("set").argument("[assignments...]", "NAME=value pairs, or a bare NAME to be prompted for").option(...instanceOption).option("--stdin", "read NAME=value lines from stdin instead of the command line").option("--json", "print the result as JSON instead of progress lines").description("set warehouse secrets on an instance and wait until they are live").addHelpText("after", `
+${SECRETS_SET_HELP}
+`).action(
+    async (assignments, opts) => {
+      const id = resolveOrInferInstance(opts.instance);
+      if (id === null) return;
+      await dispatch(
+        { command: "secrets set", id, assignments, stdin: opts.stdin === true },
+        opts.json === true
+      );
+    }
+  );
+  secrets.command("unset").argument("<names...>", "secret names to remove \u2014 names only, no values").option(...instanceOption).option("--json", "print the result as JSON instead of progress lines").description("remove warehouse secrets from an instance and wait until the change is live").action(async (names, opts) => {
+    const id = resolveOrInferInstance(opts.instance);
+    if (id === null) return;
+    await dispatch({ command: "secrets unset", id, names }, opts.json === true);
+  });
+  secrets.command("list").option(...instanceOption).option("--json", "print names and digests as JSON").description("list the secrets set on an instance \u2014 names and digests, never values").action(async (opts) => {
+    const id = resolveOrInferInstance(opts.instance);
+    if (id === null) return;
+    await dispatch({ command: "secrets list", id }, opts.json === true);
+  });
+}
 
 // src/index.ts
 function shortSha(sha) {
   return sha ? sha.slice(0, 7) : "";
 }
+function authHint(status2, t, source) {
+  const login2 = `malloyyo login ${t.name}`;
+  if (status2 === 403) {
+    return `
+  The token is valid, but that account isn't an admin on ${t.url} \u2014
+  publishing is admin-only. Ask an admin there to grant access.`;
+  }
+  switch (source) {
+    case "flag":
+      return `
+  That token came from --token. Drop the flag and run:  ${login2}`;
+    case "env":
+      return `
+  That token came from $${t.tokenEnv}. Re-issue it, or unset it and run:  ${login2}`;
+    default:
+      return `
+  Your saved login for ${t.url} is expired or revoked.
+  Run:  ${login2}`;
+  }
+}
+function failureHint(out, t) {
+  switch (out.kind) {
+    case "missing-import":
+      return `
+  A file the model imports wasn't in the upload. Publish from the directory
+  that holds index.malloy, and check the import path's spelling/case.`;
+    case "connection":
+      if (out.missingEnv?.length) {
+        const vars = out.missingEnv.map((v) => `$${v}`).join(", ");
+        return `
+  malloy-config.json references ${vars}, which ${out.missingEnv.length > 1 ? "are" : "is"} NOT set on ${t.url}.
+  Secrets don't travel with the model \u2014 set them in that deployment's environment
+  (Vercel: Settings \u2192 Environment Variables), then publish again.`;
+      }
+      return `
+  The server couldn't open the connection the model uses. Check the
+  \`connections\` block in malloy-config.json, and that ${t.url} can reach it.`;
+    case "persist":
+      return `
+  The model itself is fine \u2014 this failed writing to the server's database.
+  Retry; if it repeats, the message above is the database's own.`;
+    default:
+      return "";
+  }
+}
+function requestFailed(what, res, out, t, source) {
+  const detail = out.error ?? `${res.status} ${res.statusText}`;
+  const hint = res.status === 401 || res.status === 403 ? authHint(res.status, t, source) : failureHint(out, t);
+  return new Error(`${what} failed: ${detail}${hint}`);
+}
 async function publish(target, dir, opts) {
-  const root = resolve2(dir);
+  const root = resolve3(dir);
   const t = resolveTarget(root, target);
+  const source = tokenSource(t, { tokenFlag: opts.token });
   const bearer = await getAccessToken(t, { tokenFlag: opts.token });
   const { files, config } = gatherDirectory(root);
   if (files.length === 0) {
@@ -4223,40 +5217,48 @@ async function publish(target, dir, opts) {
       printLintReport(report);
     }
     if (!report.ok) {
-      throw new Error("dashboard lint failed \u2014 fix the above, or pass --skip-lint");
+      throw new Error(
+        "dashboard lint failed \u2014 fix the above, or pass --skip-lint" + missingEnvHint(missingEnvRefs(config), "this shell")
+      );
     }
   }
   const git = gitInfo(root);
   const dashboards = await gatherDashboards(root);
   const body = { files, config, git, dashboards };
   const provenance = git.sha ? `${git.branch}@${shortSha(git.sha)}${git.dirty ? " (dirty)" : ""}` : "(no git)";
-  console.log(`\u2192 ${t.url}  dataset=${t.dataset}`);
+  console.log(`\u2192 ${t.url}  dataset=${t.dataset}${opts.createDataset ? " (create if missing)" : ""}`);
   console.log(`  ${files.length} file(s)  ${provenance}`);
   if (opts.dryRun) {
     console.log("dry run \u2014 not sending");
     return;
   }
-  const res = await fetch(`${t.url}/api/datasets/${t.dataset}/model/push`, {
+  const push = `${t.url}/api/datasets/${t.dataset}/model/push${opts.createDataset ? "?create=1" : ""}`;
+  const res = await apiFetch(push, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${bearer}` },
     body: JSON.stringify(body)
   });
   const out = await res.json().catch(() => ({}));
   if (!res.ok || !out.ok) {
-    throw new Error(`publish failed: ${out.error ?? `${res.status} ${res.statusText}`}`);
+    throw requestFailed("publish", res, out, t, source);
+  }
+  if (out.created) {
+    console.log(`\u2713 created dataset ${out.dataset ?? t.dataset} (private) \u2014 ${t.url}/datasets/${out.dataset ?? t.dataset}`);
   }
   console.log(
     `\u2713 published version ${out.version} \u2014 ${out.sources?.length ?? 0} source(s)` + (dashboards.length ? `, ${dashboards.length} dashboard(s)` : "")
   );
 }
 async function status(target, opts) {
-  const t = resolveTarget(resolve2("."), target);
+  const t = resolveTarget(resolve3("."), target);
+  const source = tokenSource(t, { tokenFlag: opts.token });
   const bearer = await getAccessToken(t, { tokenFlag: opts.token });
-  const res = await fetch(`${t.url}/api/datasets/${t.dataset}/model/status`, {
+  const res = await apiFetch(`${t.url}/api/datasets/${t.dataset}/model/status`, {
     headers: { authorization: `Bearer ${bearer}` }
   });
   if (!res.ok) {
-    throw new Error(`status failed: ${res.status} ${res.statusText}`);
+    const body = await res.json().catch(() => ({}));
+    throw requestFailed("status", res, body, t, source);
   }
   const s = await res.json();
   const git = s.git;
@@ -4265,29 +5267,40 @@ async function status(target, opts) {
   console.log(`  ${s.compileError ? `\u2717 ${s.compileError}` : `\u2713 compiled ${s.compiledAt ?? ""}`}`);
 }
 async function loginCmd(target) {
-  const inst = resolveInstance(resolve2("."), target);
+  const inst = resolveInstance(resolve3("."), target);
   await login(inst.url);
   console.log(`\u2713 logged in to ${inst.name} (${inst.url})`);
 }
 async function logoutCmd(target) {
-  const inst = resolveInstance(resolve2("."), target);
+  const inst = resolveInstance(resolve3("."), target);
   console.log(clearCreds(inst.url) ? `\u2713 logged out of ${inst.url}` : `not logged in to ${inst.url}`);
 }
 var program = new Command();
 program.name("malloyyo").description("Publish Malloy models to a Malloyyo instance").version(version);
 program.command("login").argument("[target]", "target name or instance URL (optional if the config has one target)").description("sign in to an instance in your browser (stores a token)").action(loginCmd);
 program.command("logout").argument("[target]", "target name or instance URL (optional if the config has one target)").description("forget the stored token for an instance").action(logoutCmd);
-program.command("publish").argument("<target>", "named target from the `malloyyo` config block").argument("[dir]", "directory to publish", ".").option("--token <token>", "bearer token (overrides login/env)").option("--dry-run", "gather and report what would be sent, but don't POST").option("--skip-lint", "skip the pre-publish dashboard lint").description('push the Malloy model in <dir> (default ".") to <target>').action(publish);
+program.command("publish").argument(
+  "[target]",
+  "named target from the `malloyyo` config block; optional when the repo defines one"
+).argument("[dir]", "directory to publish", ".").option("--token <token>", "bearer token (overrides login/env)").option("--dry-run", "gather and report what would be sent, but don't POST").option("--skip-lint", "skip the pre-publish dashboard lint").option("--create-dataset", "create the target dataset if it doesn't exist yet (private)").description('push the Malloy model in <dir> (default ".") to <target>').action(publish);
 program.command("lint").argument("[dir]", "directory to lint", ".").description("validate ./dashboards against the model (manifest, query, givens, Dashboard.tsx)").action(async (dir) => {
-  const report = await lintDashboards(resolve2(dir));
+  const root = resolve3(dir);
+  const report = await lintDashboards(root);
   if (report.dashboards.length === 0) {
     console.log("no dashboards to lint");
     return;
   }
   printLintReport(report);
-  if (!report.ok) process.exit(1);
+  if (!report.ok) {
+    const hint = missingEnvHint(missingEnvRefs(gatherDirectory(root).config), "this shell");
+    if (hint) console.error(hint.replace(/^\n/, ""));
+    process.exit(1);
+  }
 });
-program.command("status").argument("<target>", "named target from the `malloyyo` config block").option("--token <token>", "bearer token (overrides login/env)").description("show what's live on <target>: version, commit, compile state").action(status);
+program.command("status").argument(
+  "[target]",
+  "named target from the `malloyyo` config block; optional when the repo defines one"
+).option("--token <token>", "bearer token (overrides login/env)").description("show what's live on the target: version, commit, compile state").action(status);
 program.command("mcp").option("-C, --root <dir>", "project root (default: current directory)").option("--develop", "author surface: compile/prettify/query any .malloy in the project").option("--explore", "explore surface: the claude.ai web preview (index.malloy only) [default]").description(
   "run a local stdio MCP server over the Malloy model in the current directory. --develop for authoring, --explore (default) to preview the web experience"
 ).action(async (opts) => {
@@ -4351,6 +5364,7 @@ program.command("dashboard").argument("<action>", "action to run (dev | bundle)"
     throw new Error(`unknown dashboard action '${action}' (expected: dev | bundle)`);
   }
 );
+registerCloudCommands(program);
 program.parseAsync().catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);