deepspace 0.6.0 → 0.6.2

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli/cli.ts
-import { defineCommand as defineCommand22, runMain } from "citty";
+import { defineCommand as defineCommand23, runMain } from "citty";
 import { spawnSync as spawnSync6 } from "child_process";
-import { readFileSync as readFileSync17, existsSync as existsSync14 } from "fs";
-import { dirname as dirname5, join as join15 } from "path";
+import { readFileSync as readFileSync17, existsSync as existsSync15 } from "fs";
+import { dirname as dirname5, join as join16 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/cli/lib/cli-errors.ts
@@ -1342,7 +1342,7 @@ var logout_default = defineCommand2({
 
 // src/cli/commands/dev.ts
 import { defineCommand as defineCommand3 } from "citty";
-import { resolve as resolve4, basename as basename2, join as join9 } from "path";
+import { resolve as resolve4, basename as basename2, join as join10 } from "path";
 import spawn from "cross-spawn";
 
 // src/cli/auth.ts
@@ -1788,6 +1788,112 @@ function removeMacosJunk(dir) {
   return removed;
 }
 
+// src/cli/lib/schema-lint.ts
+import { existsSync as existsSync9 } from "fs";
+import { join as join9 } from "path";
+import { pathToFileURL } from "url";
+
+// src/server/schemas/registry.ts
+var USERS_COLUMNS = [
+  { name: "email", storage: "text", interpretation: "plain" },
+  { name: "name", storage: "text", interpretation: "plain" },
+  { name: "imageUrl", storage: "text", interpretation: "plain" },
+  { name: "role", storage: "text", interpretation: "plain" },
+  { name: "createdAt", storage: "text", interpretation: { kind: "datetime" } },
+  { name: "lastSeenAt", storage: "text", interpretation: { kind: "datetime" } }
+];
+var BASE_USERS_SCHEMA = {
+  name: "users",
+  columns: [...USERS_COLUMNS],
+  permissions: {
+    "*": { read: "own", create: false, update: false, delete: false },
+    admin: { read: true, create: false, update: true, delete: true }
+  }
+};
+function lintSchema(schema) {
+  const warnings = [];
+  const VISIBILITY_AWARE = ["published", "shared"];
+  if (schema.visibilityField) {
+    const offendingRoles = Object.entries(schema.permissions).filter(([, perms]) => perms.read === true).map(([role]) => role);
+    if (offendingRoles.length > 0) {
+      const usesAware = Object.values(schema.permissions).some(
+        (p10) => typeof p10.read === "string" && VISIBILITY_AWARE.includes(p10.read)
+      );
+      if (!usesAware) {
+        warnings.push(
+          `[${schema.name}] visibilityField is declared but no role uses read: 'published' or 'shared'. Roles with read: true (${offendingRoles.join(", ")}) will see every row regardless of visibility. Change those to read: 'published' (owner OR public) or 'shared' (owner OR collaborator OR public) to actually enforce the filter, or remove visibilityField if you don't intend to gate reads by it.`
+        );
+      }
+    }
+  }
+  if (schema.ownerField) {
+    const col = schema.columns.find((c) => c.name === schema.ownerField);
+    if (col && !col.userBound) {
+      warnings.push(
+        `[${schema.name}] ownerField is '${schema.ownerField}' but that column is not marked userBound: true. A client can create a row with someone else's id in this field, bypassing 'own' permission checks. Add userBound: true (and ideally immutable: true) to the column.`
+      );
+    }
+  }
+  for (const col of schema.columns) {
+    if (col.userBound && col.storage !== "text") {
+      warnings.push(
+        `[${schema.name}] column '${col.name}' is userBound but storage is '${col.storage}'. userBound stamps the user id (a string); use storage: 'text'.`
+      );
+    }
+  }
+  return warnings;
+}
+
+// src/cli/lib/schema-lint.ts
+async function lintProjectSchemas(appDir) {
+  const schemasPath = join9(appDir, "src", "schemas.ts");
+  if (!existsSync9(schemasPath)) return null;
+  let schemas;
+  try {
+    const esbuild = await import("esbuild");
+    const outFile = join9(appDir, ".wrangler", "deploy", "schemas.lint.bundle.mjs");
+    await esbuild.build({
+      entryPoints: [schemasPath],
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node18",
+      outfile: outFile,
+      logLevel: "silent",
+      write: true
+    });
+    const mod = await import(`${pathToFileURL(outFile).href}?t=${Date.now()}`);
+    schemas = mod.schemas;
+  } catch {
+    console.warn(
+      "Schema lint skipped: could not bundle src/schemas.ts (the worker still lints at runtime)."
+    );
+    return null;
+  }
+  if (!Array.isArray(schemas)) return null;
+  const findings = [];
+  for (const schema of schemas) {
+    if (!schema || typeof schema !== "object") continue;
+    try {
+      findings.push(...lintSchema(schema));
+    } catch {
+    }
+  }
+  return findings;
+}
+var MAX_PRINTED_FINDINGS = 5;
+function formatSchemaLintFindings(findings) {
+  if (findings.length === 0) return [];
+  const n = findings.length;
+  const shown = findings.slice(0, MAX_PRINTED_FINDINGS);
+  const hidden = n - shown.length;
+  return [
+    `Schema lint: ${n} warning${n === 1 ? "" : "s"} in src/schemas.ts \u2014 ${n === 1 ? "this ships" : "these ship"} as permission/privacy bugs:`,
+    ...shown.map((f) => `  \u2022 ${f}`),
+    ...hidden > 0 ? [`  \u2026and ${hidden} more \u2014 fix the above and re-run to see the rest.`] : []
+  ];
+}
+
 // src/cli/lib/port.ts
 import { createServer } from "net";
 var DEFAULT_PORT = 5173;
@@ -1874,7 +1980,7 @@ var dev_default = defineCommand3({
         );
       } else {
         console.warn(
-          `Warning: could not update ${join9(worktree.mainRepoRoot, ".claude", "launch.json")} (malformed or unwritable) \u2014 the Claude preview tool may serve the main repo's code instead of this worktree.`
+          `Warning: could not update ${join10(worktree.mainRepoRoot, ".claude", "launch.json")} (malformed or unwritable) \u2014 the Claude preview tool may serve the main repo's code instead of this worktree.`
         );
       }
       if (!explicitPort && process.env.DEEPSPACE_PORT) {
@@ -1887,6 +1993,10 @@ var dev_default = defineCommand3({
       updatePort: explicitPort
     });
     ensureInstallReady(appDir);
+    const lintFindings = await lintProjectSchemas(appDir);
+    if (lintFindings && lintFindings.length > 0) {
+      for (const line of formatSchemaLintFindings(lintFindings)) console.warn(line);
+    }
     let token;
     try {
       token = await ensureToken();
@@ -2474,15 +2584,15 @@ var screenshot_default = defineCommand6({
 // src/cli/commands/test-accounts.ts
 import { defineCommand as defineCommand7 } from "citty";
 import * as p3 from "@clack/prompts";
-import { readFileSync as readFileSync10, writeFileSync as writeFileSync8, existsSync as existsSync9, mkdirSync as mkdirSync4 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync10, writeFileSync as writeFileSync8, existsSync as existsSync10, mkdirSync as mkdirSync4 } from "fs";
+import { join as join11 } from "path";
 import { homedir as homedir4 } from "os";
 var SESSION_COOKIE2 = "__Secure-better-auth.session_token";
 var AUTH_URL4 = process.env.DEEPSPACE_AUTH_URL ?? PLATFORM_URLS.auth;
-var DIR3 = join10(homedir4(), ".deepspace");
-var ACCOUNTS_PATH = join10(DIR3, "test-accounts.json");
+var DIR3 = join11(homedir4(), ".deepspace");
+var ACCOUNTS_PATH = join11(DIR3, "test-accounts.json");
 function loadAccounts() {
-  if (!existsSync9(ACCOUNTS_PATH)) return [];
+  if (!existsSync10(ACCOUNTS_PATH)) return [];
   try {
     return JSON.parse(readFileSync10(ACCOUNTS_PATH, "utf-8"));
   } catch {
@@ -2764,9 +2874,9 @@ var test_accounts_default = defineCommand7({
 import { defineCommand as defineCommand8 } from "citty";
 import { execSync as execSync2 } from "child_process";
 import { randomUUID } from "crypto";
-import { readFileSync as readFileSync11, readdirSync as readdirSync4, existsSync as existsSync10 } from "fs";
-import { join as join11, resolve as resolve7, dirname as dirname2 } from "path";
-import { pathToFileURL } from "url";
+import { readFileSync as readFileSync11, readdirSync as readdirSync4, existsSync as existsSync11 } from "fs";
+import { join as join12, resolve as resolve7, dirname as dirname2 } from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
 import * as p4 from "@clack/prompts";
 var DEPLOY_URL3 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
 var API_URL2 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
@@ -2978,7 +3088,7 @@ var deploy_default = defineCommand8({
     }
     p4.log.info(`Id: ${appId}`);
     const readCustomDevVarsAt = (path) => {
-      if (!existsSync10(path)) return {};
+      if (!existsSync11(path)) return {};
       const section = extractCustomDevVars(stripGeneratedSecretsCache(readFileSync11(path, "utf-8")));
       if (!section) return {};
       try {
@@ -3017,6 +3127,10 @@ var deploy_default = defineCommand8({
     }
     const junk = removeMacosJunk(appDir);
     if (junk > 0) p4.log.info(`Removed ${junk} macOS metadata file(s) (._*, .DS_Store)`);
+    const lintFindings = await lintProjectSchemas(appDir);
+    if (lintFindings && lintFindings.length > 0) {
+      p4.log.warn(formatSchemaLintFindings(lintFindings).join("\n"));
+    }
     const s = createSpinner();
     s.start("Building...");
     let preparedWranglerConfig;
@@ -3039,14 +3153,14 @@ var deploy_default = defineCommand8({
       preparedWranglerConfig?.cleanup();
     }
     s.stop("Built");
-    const deployConfigPath = join11(appDir, ".wrangler", "deploy", "config.json");
-    if (!existsSync10(deployConfigPath)) {
+    const deployConfigPath = join12(appDir, ".wrangler", "deploy", "config.json");
+    if (!existsSync11(deployConfigPath)) {
       p4.cancel("Build output config not found at .wrangler/deploy/config.json");
       process.exit(1);
     }
     const deployConfig = JSON.parse(readFileSync11(deployConfigPath, "utf-8"));
     const outputWranglerPath = resolve7(dirname2(deployConfigPath), deployConfig.configPath);
-    if (!existsSync10(outputWranglerPath)) {
+    if (!existsSync11(outputWranglerPath)) {
       p4.cancel(`Output wrangler.json not found at ${outputWranglerPath}`);
       process.exit(1);
     }
@@ -3059,13 +3173,13 @@ var deploy_default = defineCommand8({
       process.exit(1);
     }
     const workerDir = dirname2(outputWranglerPath);
-    const workerBundlePath = join11(workerDir, outputConfig.main);
+    const workerBundlePath = join12(workerDir, outputConfig.main);
     const clientDir = outputConfig.assets?.directory ? resolve7(workerDir, outputConfig.assets.directory) : null;
-    if (!existsSync10(workerBundlePath)) {
+    if (!existsSync11(workerBundlePath)) {
       p4.cancel(`Worker bundle not found at ${workerBundlePath}`);
       process.exit(1);
     }
-    if (!clientDir || !existsSync10(clientDir)) {
+    if (!clientDir || !existsSync11(clientDir)) {
       p4.cancel(`Client assets not found at ${clientDir}`);
       process.exit(1);
     }
@@ -3300,13 +3414,13 @@ then redeploy. (Pass --allow-missing-secrets to deploy without them.)`
   }
 });
 async function syncSubscriptionPlans(appDir, appName, token) {
-  const subsPath = join11(appDir, "src", "subscriptions.ts");
-  if (!existsSync10(subsPath)) return;
+  const subsPath = join12(appDir, "src", "subscriptions.ts");
+  if (!existsSync11(subsPath)) return;
   let plans;
   try {
     const esbuild = await import("esbuild");
-    const outDir = join11(appDir, ".wrangler", "deploy");
-    const outFile = join11(outDir, "subscriptions.bundle.mjs");
+    const outDir = join12(appDir, ".wrangler", "deploy");
+    const outFile = join12(outDir, "subscriptions.bundle.mjs");
     await esbuild.build({
       entryPoints: [subsPath],
       bundle: true,
@@ -3317,7 +3431,7 @@ async function syncSubscriptionPlans(appDir, appName, token) {
       logLevel: "silent",
       write: true
     });
-    const mod = await import(`${pathToFileURL(outFile).href}?t=${Date.now()}`);
+    const mod = await import(`${pathToFileURL2(outFile).href}?t=${Date.now()}`);
     plans = mod.subscriptionPlans;
   } catch (err) {
     p4.log.warn(`Could not load src/subscriptions.ts: ${errMessage(err)}`);
@@ -3448,13 +3562,13 @@ current billing period? (Skip to leave them grandfathered.)`
   }
 }
 async function syncOneTimeProducts(appDir, appName, token) {
-  const productsPath = join11(appDir, "src", "products.ts");
-  if (!existsSync10(productsPath)) return;
+  const productsPath = join12(appDir, "src", "products.ts");
+  if (!existsSync11(productsPath)) return;
   let products;
   try {
     const esbuild = await import("esbuild");
-    const outDir = join11(appDir, ".wrangler", "deploy");
-    const outFile = join11(outDir, "products.bundle.mjs");
+    const outDir = join12(appDir, ".wrangler", "deploy");
+    const outFile = join12(outDir, "products.bundle.mjs");
     await esbuild.build({
       entryPoints: [productsPath],
       bundle: true,
@@ -3465,7 +3579,7 @@ async function syncOneTimeProducts(appDir, appName, token) {
       logLevel: "silent",
       write: true
     });
-    const mod = await import(`${pathToFileURL(outFile).href}?t=${Date.now()}`);
+    const mod = await import(`${pathToFileURL2(outFile).href}?t=${Date.now()}`);
     products = mod.oneTimeProducts;
   } catch (err) {
     p4.log.warn(`Could not load src/products.ts: ${errMessage(err)}`);
@@ -3529,7 +3643,7 @@ function collectAssets(dir) {
   function walk(d, prefix) {
     for (const entry of readdirSync4(d, { withFileTypes: true })) {
       if (entry.name === ".assetsignore") continue;
-      const full = join11(d, entry.name);
+      const full = join12(d, entry.name);
       const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
       if (entry.isDirectory()) {
         walk(full, rel);
@@ -3708,28 +3822,108 @@ var apps_default = defineCommand11({
   }
 });
 
-// src/cli/commands/add.ts
+// src/cli/commands/usage.ts
 import { defineCommand as defineCommand12 } from "citty";
-import { existsSync as existsSync11, readFileSync as readFileSync12 } from "fs";
-import { resolve as resolve8, join as join12, dirname as dirname3 } from "path";
+var API_URL3 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
+function formatCredits(value) {
+  if (value > 0 && value < 1) return "<1";
+  if (value < 10) return value.toFixed(1).replace(/\.0$/, "");
+  return Math.round(value).toLocaleString("en-US");
+}
+function formatUsd(value) {
+  return `$${Math.abs(value) >= 0.01 || value === 0 ? value.toFixed(2) : value.toFixed(4)}`;
+}
+function formatDate(iso) {
+  return new Date(iso).toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    timeZone: "UTC"
+  });
+}
+function renderSummary(summary) {
+  const { credits, usageByIntegration } = summary;
+  const lines = [];
+  const renews = credits.subscription.renewsAt ? ` \xB7 renews ${formatDate(credits.subscription.renewsAt)}` : "";
+  lines.push(`Plan:     ${credits.subscription.tier}${renews}`);
+  lines.push(
+    `Credits:  ${formatCredits(credits.credits)} of ${formatCredits(credits.totalAllocation)} remaining (100 credits = $1)`
+  );
+  const bonusActive = credits.bonus.allocation > 0 || credits.bonus.expired;
+  const purchasedActive = credits.purchased.allocation > 0 || credits.purchased.used > 0;
+  if (bonusActive || purchasedActive) {
+    const bucket = (b) => `${formatCredits(b.remaining)} of ${formatCredits(b.allocation)} remaining`;
+    lines.push(`  Subscription:  ${bucket(credits.subscription)}`);
+    if (bonusActive) {
+      const expires = credits.bonus.expiresAt ? ` \xB7 expires ${formatDate(credits.bonus.expiresAt)}` : "";
+      lines.push(
+        `  Bonus:         ${credits.bonus.expired ? "expired" : bucket(credits.bonus) + expires}`
+      );
+    }
+    if (purchasedActive) {
+      lines.push(`  Purchased:     ${bucket(credits.purchased)}`);
+    }
+  }
+  lines.push("");
+  if (!usageByIntegration.length) {
+    lines.push("No integration usage in the last 30 days.");
+  } else {
+    lines.push("Usage by integration (last 30 days):");
+    const nameWidth = Math.max(11, ...usageByIntegration.map((u) => u.name.length));
+    lines.push(`${"INTEGRATION".padEnd(nameWidth)}  CALLS  COST`);
+    for (const u of usageByIntegration) {
+      lines.push(`${u.name.padEnd(nameWidth)}  ${String(u.count).padEnd(5)}  ${formatUsd(u.totalCost)}`);
+    }
+  }
+  lines.push("");
+  lines.push(`Dashboard: ${DASHBOARD_URL}`);
+  return lines.join("\n");
+}
+var usage_default = defineCommand12({
+  meta: {
+    name: "usage",
+    description: "Show credit balance, quota headroom, and per-integration spend"
+  },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Emit the raw usage summary as JSON instead of human output",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const token = await ensureToken();
+    const summary = await apiFetch(API_URL3, token, "/api/usage/summary");
+    if (args.json) {
+      process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+      return;
+    }
+    console.log(renderSummary(summary));
+  }
+});
+
+// src/cli/commands/add.ts
+import { defineCommand as defineCommand13 } from "citty";
+import { existsSync as existsSync12, readFileSync as readFileSync12 } from "fs";
+import { resolve as resolve8, join as join13, dirname as dirname3 } from "path";
 import { fileURLToPath } from "url";
 import { spawnSync as spawnSync5 } from "child_process";
 function findScript(from) {
-  const inNodeModules = join12(from, "node_modules", "deepspace", "scripts", "add-feature.cjs");
-  if (existsSync11(inNodeModules)) return inNodeModules;
-  const inDotDeepspace = join12(from, ".deepspace", "scripts", "add-feature.cjs");
-  if (existsSync11(inDotDeepspace)) return inDotDeepspace;
+  const inNodeModules = join13(from, "node_modules", "deepspace", "scripts", "add-feature.cjs");
+  if (existsSync12(inNodeModules)) return inNodeModules;
+  const inDotDeepspace = join13(from, ".deepspace", "scripts", "add-feature.cjs");
+  if (existsSync12(inDotDeepspace)) return inDotDeepspace;
   return null;
 }
 function runningScript() {
   const here = dirname3(fileURLToPath(import.meta.url));
-  const script = join12(here, "..", "scripts", "add-feature.cjs");
-  return existsSync11(script) ? script : null;
+  const script = join13(here, "..", "scripts", "add-feature.cjs");
+  return existsSync12(script) ? script : null;
 }
 function isDeepSpaceApp(dir) {
-  if (existsSync11(join12(dir, "wrangler.toml"))) return true;
-  const pkgPath = join12(dir, "package.json");
-  if (!existsSync11(pkgPath)) return false;
+  if (existsSync12(join13(dir, "wrangler.toml"))) return true;
+  const pkgPath = join13(dir, "package.json");
+  if (!existsSync12(pkgPath)) return false;
   try {
     const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
     return Boolean(pkg2.dependencies?.deepspace || pkg2.devDependencies?.deepspace);
@@ -3745,7 +3939,7 @@ function runInstaller(script, passArgs, cwd) {
   }
   process.exit(res.status ?? 1);
 }
-var add_default = defineCommand12({
+var add_default = defineCommand13({
   meta: {
     name: "add",
     description: "Add a feature to your DeepSpace app"
@@ -3790,7 +3984,7 @@ var add_default = defineCommand12({
       const passArgs2 = args.list ? ["--list"] : args.info ? ["--info", String(args.info)] : ["--help"];
       runInstaller(script2, passArgs2, process.cwd());
     }
-    if (!existsSync11(appDir)) {
+    if (!existsSync12(appDir)) {
       console.error(`Target directory not found: ${appDir}`);
       console.error("Create a new app first: deepspace create <name>");
       process.exit(1);
@@ -3806,8 +4000,8 @@ var add_default = defineCommand12({
     if (!script) {
       console.error("Could not find the deepspace feature installer.");
       console.error("Looked in:");
-      console.error(`  ${join12(appDir, "node_modules", "deepspace", "scripts", "add-feature.cjs")}`);
-      console.error(`  ${join12(appDir, ".deepspace", "scripts", "add-feature.cjs")}`);
+      console.error(`  ${join13(appDir, "node_modules", "deepspace", "scripts", "add-feature.cjs")}`);
+      console.error(`  ${join13(appDir, ".deepspace", "scripts", "add-feature.cjs")}`);
       console.error("Are you in a DeepSpace app directory? Try `npm install` first.");
       process.exit(1);
     }
@@ -3818,9 +4012,9 @@ var add_default = defineCommand12({
 });
 
 // src/cli/commands/domain.ts
-import { defineCommand as defineCommand13 } from "citty";
-var API_URL3 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
-var api = (token, path, init) => apiFetch(API_URL3, token, path, init);
+import { defineCommand as defineCommand14 } from "citty";
+var API_URL4 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
+var api = (token, path, init) => apiFetch(API_URL4, token, path, init);
 function scrubInternal(value) {
   if (Array.isArray(value)) return value.map(scrubInternal);
   if (value && typeof value === "object") {
@@ -3854,7 +4048,7 @@ async function confirm3(message) {
     });
   });
 }
-var search = defineCommand13({
+var search = defineCommand14({
   meta: { name: "search", description: "Search for available domains" },
   args: {
     query: { type: "positional", description: "Domain or keyword", required: true },
@@ -3884,7 +4078,7 @@ var search = defineCommand13({
     }
   }
 });
-var buy = defineCommand13({
+var buy = defineCommand14({
   meta: { name: "buy", description: "Buy a domain and attach it to an app" },
   args: {
     domain: { type: "positional", description: "Domain to buy", required: true },
@@ -3994,7 +4188,7 @@ var buy = defineCommand13({
     process.exit(1);
   }
 });
-var list2 = defineCommand13({
+var list2 = defineCommand14({
   meta: { name: "list", description: "List your domains" },
   args: {
     json: { type: "boolean", description: "Emit JSON" }
@@ -4020,7 +4214,7 @@ var list2 = defineCommand13({
     }
   }
 });
-var status = defineCommand13({
+var status = defineCommand14({
   meta: { name: "status", description: "Show details for one domain" },
   args: {
     domain: { type: "positional", description: "Domain", required: true },
@@ -4050,7 +4244,7 @@ var status = defineCommand13({
     console.log(`Charged:       ${fmtCents(found.chargedCents)}/yr`);
   }
 });
-var attach = defineCommand13({
+var attach = defineCommand14({
   meta: { name: "attach", description: "Re-point a domain at a different app" },
   args: {
     domain: { type: "positional", description: "Domain to re-point", required: true },
@@ -4081,7 +4275,7 @@ var attach = defineCommand13({
     console.log(`\u2713 ${args.domain} now points at ${targetApp}`);
   }
 });
-var detach = defineCommand13({
+var detach = defineCommand14({
   meta: {
     name: "detach",
     description: "Stop routing the domain (keeps the registration; auto-renew unchanged)"
@@ -4113,7 +4307,7 @@ var detach = defineCommand13({
     );
   }
 });
-var renew = defineCommand13({
+var renew = defineCommand14({
   meta: { name: "renew", description: "Toggle auto-renewal at the registrar" },
   args: {
     domain: { type: "positional", description: "Domain", required: true },
@@ -4139,13 +4333,13 @@ var renew = defineCommand13({
     console.log(`\u2713 ${args.domain} auto-renew ${enabled ? "enabled" : "disabled"}`);
   }
 });
-var domain_default = defineCommand13({
+var domain_default = defineCommand14({
   meta: { name: "domain", description: "Buy and manage custom domains" },
   subCommands: { search, buy, list: list2, status, attach, detach, renew }
 });
 
 // src/cli/commands/collaborators.ts
-import { defineCommand as defineCommand14 } from "citty";
+import { defineCommand as defineCommand15 } from "citty";
 
 // src/server/auth/testAccounts.ts
 var TEST_ACCOUNT_EMAIL_SUFFIX = "@deepspace.test";
@@ -4154,12 +4348,12 @@ function isTestAccountEmail(email) {
 }
 
 // src/cli/commands/collaborators.ts
-var API_URL4 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
+var API_URL5 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
 var DEPLOY_URL6 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
 function api2(token, path, init) {
-  return apiFetch(API_URL4, token, path, init);
+  return apiFetch(API_URL5, token, path, init);
 }
-var list3 = defineCommand14({
+var list3 = defineCommand15({
   meta: { name: "list", description: "List collaborators on your app" },
   args: {
     app: { type: "string", alias: "a", description: "App id or name (defaults to ./wrangler.toml)" },
@@ -4191,7 +4385,7 @@ var list3 = defineCommand14({
     }
   }
 });
-var add = defineCommand14({
+var add = defineCommand15({
   meta: { name: "add", description: "Authorize someone to deploy your app" },
   args: {
     email: {
@@ -4236,7 +4430,7 @@ var add = defineCommand14({
     console.log(`\u2713 ${res.collaborator.emailDisplay} can now deploy ${app}`);
   }
 });
-var remove = defineCommand14({
+var remove = defineCommand15({
   meta: { name: "remove", description: "Remove a collaborator from your app" },
   args: {
     email: { type: "positional", description: "Collaborator email", required: true },
@@ -4268,7 +4462,7 @@ var remove = defineCommand14({
     console.log(`\u2713 ${found.emailDisplay} can no longer deploy ${app}`);
   }
 });
-var cancel4 = defineCommand14({
+var cancel4 = defineCommand15({
   meta: { name: "cancel", description: "Cancel a pending (un-accepted) email invite" },
   args: {
     email: { type: "positional", description: "Invited email", required: true },
@@ -4300,17 +4494,17 @@ var cancel4 = defineCommand14({
     console.log(`\u2713 Cancelled the pending invite to ${found.email} on ${app}`);
   }
 });
-var collaborators_default = defineCommand14({
+var collaborators_default = defineCommand15({
   meta: { name: "collaborators", description: "Manage who can deploy your app" },
   subCommands: { list: list3, add, remove, cancel: cancel4 }
 });
 
 // src/cli/commands/transfer.ts
-import { defineCommand as defineCommand15 } from "citty";
+import { defineCommand as defineCommand16 } from "citty";
 import * as p6 from "@clack/prompts";
-var API_URL5 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
+var API_URL6 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
 var DEPLOY_URL7 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
-var offer = defineCommand15({
+var offer = defineCommand16({
   meta: { name: "offer", description: "Offer this app to another DeepSpace user" },
   args: {
     email: { type: "positional", description: "Recipient email", required: true },
@@ -4324,7 +4518,7 @@ var offer = defineCommand15({
     const token = await ensureToken();
     const app = await resolveAppTarget(DEPLOY_URL7, token, args.app);
     const pending = await apiFetch(
-      API_URL5,
+      API_URL6,
       token,
       `/api/app-transfers/${encodeURIComponent(app)}`
     );
@@ -4345,7 +4539,7 @@ var offer = defineCommand15({
       }
     }
     const { expiresAt } = await apiFetch(
-      API_URL5,
+      API_URL6,
       token,
       `/api/app-transfers/${encodeURIComponent(app)}`,
       { method: "POST", body: JSON.stringify({ email: args.email }) }
@@ -4359,7 +4553,7 @@ var offer = defineCommand15({
     );
   }
 });
-var status2 = defineCommand15({
+var status2 = defineCommand16({
   meta: { name: "status", description: "Show the pending transfer offer, if any" },
   args: {
     app: { type: "string", alias: "a", description: "App id or name (defaults to ./wrangler.toml)" }
@@ -4367,7 +4561,7 @@ var status2 = defineCommand15({
   async run({ args }) {
     const token = await ensureToken();
     const app = await resolveAppTarget(DEPLOY_URL7, token, args.app);
-    const { transfer } = await apiFetch(API_URL5, token, `/api/app-transfers/${encodeURIComponent(app)}`);
+    const { transfer } = await apiFetch(API_URL6, token, `/api/app-transfers/${encodeURIComponent(app)}`);
     if (!transfer) {
       console.log(`No pending transfer for ${app}.`);
       return;
@@ -4375,7 +4569,7 @@ var status2 = defineCommand15({
     console.log(`Pending: ${app} \u2192 ${transfer.toEmailDisplay} (expires ${transfer.expiresAt}).`);
   }
 });
-var accept = defineCommand15({
+var accept = defineCommand16({
   meta: { name: "accept", description: "Accept a transfer offered to you" },
   args: {
     app: { type: "string", alias: "a", description: "App id of the offered app", required: true }
@@ -4391,7 +4585,7 @@ var accept = defineCommand15({
     );
   }
 });
-var cancel5 = defineCommand15({
+var cancel5 = defineCommand16({
   meta: { name: "cancel", description: "Cancel/decline the pending offer (either party)" },
   args: {
     app: { type: "string", alias: "a", description: "App id or name (defaults to ./wrangler.toml)" }
@@ -4399,22 +4593,22 @@ var cancel5 = defineCommand15({
   async run({ args }) {
     const token = await ensureToken();
     const app = await resolveAppTarget(DEPLOY_URL7, token, args.app);
-    await apiFetch(API_URL5, token, `/api/app-transfers/${encodeURIComponent(app)}`, { method: "DELETE" });
+    await apiFetch(API_URL6, token, `/api/app-transfers/${encodeURIComponent(app)}`, { method: "DELETE" });
     console.log(`\u2713 Transfer offer for ${app} cancelled.`);
   }
 });
-var transfer_default = defineCommand15({
+var transfer_default = defineCommand16({
   meta: { name: "transfer", description: "Transfer app ownership to another user" },
   subCommands: { offer, status: status2, accept, cancel: cancel5 }
 });
 
 // src/cli/commands/integrations.ts
-import { defineCommand as defineCommand16 } from "citty";
+import { defineCommand as defineCommand17 } from "citty";
 
 // src/cli/commands/_invoke-impl.ts
 import { readFileSync as readFileSync13 } from "fs";
 import * as p7 from "@clack/prompts";
-var API_URL6 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
+var API_URL7 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
 var DEFAULT_TIMEOUT_MS = 12e4;
 function parseTarget(target) {
   if (!target || typeof target !== "string") {
@@ -4456,7 +4650,7 @@ function flushAndExit(code) {
   });
 }
 async function fetchCatalog(opts = {}) {
-  const url = opts.summary ? `${API_URL6}/api/integrations?summary=1` : `${API_URL6}/api/integrations`;
+  const url = opts.summary ? `${API_URL7}/api/integrations?summary=1` : `${API_URL7}/api/integrations`;
   const res = await fetch(url);
   if (!res.ok) {
     throw new Error(`Failed to fetch integration catalog (${res.status})`);
@@ -4580,7 +4774,7 @@ async function runInvoke(args) {
   const startedAt = Date.now();
   let res;
   try {
-    res = await fetch(`${API_URL6}/api/integrations/${integration}/${endpoint}`, {
+    res = await fetch(`${API_URL7}/api/integrations/${integration}/${endpoint}`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -4631,7 +4825,7 @@ async function runInvoke(args) {
 }
 
 // src/cli/commands/integrations.ts
-var list4 = defineCommand16({
+var list4 = defineCommand17({
   meta: {
     name: "list",
     description: "List all available integrations"
@@ -4652,7 +4846,7 @@ var list4 = defineCommand16({
     }
   }
 });
-var info = defineCommand16({
+var info = defineCommand17({
   meta: {
     name: "info",
     description: "Print schema + example body for an integration endpoint"
@@ -4678,7 +4872,7 @@ var info = defineCommand16({
     }
   }
 });
-var invoke = defineCommand16({
+var invoke = defineCommand17({
   meta: {
     name: "invoke",
     description: "Invoke a platform integration as the logged-in user"
@@ -4738,7 +4932,7 @@ var invoke = defineCommand16({
     }
   }
 });
-var integrations_default = defineCommand16({
+var integrations_default = defineCommand17({
   meta: {
     name: "integrations",
     description: "List, inspect, and invoke platform integrations"
@@ -4751,8 +4945,8 @@ var integrations_default = defineCommand16({
 });
 
 // src/cli/commands/invoke.ts
-import { defineCommand as defineCommand17 } from "citty";
-var invoke_default = defineCommand17({
+import { defineCommand as defineCommand18 } from "citty";
+var invoke_default = defineCommand18({
   meta: {
     name: "invoke",
     description: "Invoke a platform integration as the logged-in user"
@@ -4832,13 +5026,13 @@ var invoke_default = defineCommand17({
 });
 
 // src/cli/commands/library.ts
-import { defineCommand as defineCommand18 } from "citty";
-import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
-import { join as join13, resolve as resolve9 } from "path";
+import { defineCommand as defineCommand19 } from "citty";
+import { existsSync as existsSync13, readFileSync as readFileSync14 } from "fs";
+import { join as join14, resolve as resolve9 } from "path";
 import { parse as parseToml4 } from "smol-toml";
 import * as p8 from "@clack/prompts";
 var DEFAULT_LIBRARY_APP = "deepdotspace-site";
-var publish = defineCommand18({
+var publish = defineCommand19({
   meta: {
     name: "publish",
     description: "Publish the current app to the DeepSpace library"
@@ -4912,8 +5106,8 @@ var publish = defineCommand18({
     let appName = typeof args.app === "string" && args.app.trim() ? args.app.trim() : void 0;
     if (!appName) {
       const appDir = resolve9(typeof args.dir === "string" && args.dir ? args.dir : ".");
-      const wranglerPath = join13(appDir, "wrangler.toml");
-      if (!existsSync12(wranglerPath)) {
+      const wranglerPath = join14(appDir, "wrangler.toml");
+      if (!existsSync13(wranglerPath)) {
         return die("No --app provided and no wrangler.toml found. Either pass --app <name> or run from your app's directory.");
       }
       const cfg = parseToml4(readFileSync14(wranglerPath, "utf-8"));
@@ -4977,7 +5171,7 @@ var publish = defineCommand18({
     p8.outro("Done");
   }
 });
-var unpublish = defineCommand18({
+var unpublish = defineCommand19({
   meta: {
     name: "unpublish",
     description: "Remove a library entry (owner or admin only)"
@@ -5036,7 +5230,7 @@ var unpublish = defineCommand18({
     p8.outro("Done");
   }
 });
-var library_default = defineCommand18({
+var library_default = defineCommand19({
   meta: {
     name: "library",
     description: "Manage your DeepSpace library entries"
@@ -5048,13 +5242,13 @@ var library_default = defineCommand18({
 });
 
 // src/cli/commands/feedback.ts
-import { defineCommand as defineCommand19 } from "citty";
+import { defineCommand as defineCommand20 } from "citty";
 import * as p9 from "@clack/prompts";
-import { existsSync as existsSync13, readFileSync as readFileSync15 } from "fs";
-import { dirname as dirname4, join as join14 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync15 } from "fs";
+import { dirname as dirname4, join as join15 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { release } from "os";
-var API_URL7 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
+var API_URL8 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
 var TYPES = ["bug", "feature", "other"];
 var TYPE_LABELS = {
   bug: "Bug report",
@@ -5064,7 +5258,7 @@ var TYPE_LABELS = {
 var MAX_TITLE_LEN = 200;
 var MAX_BODY_LEN = 1e4;
 var MAX_CONTEXT_LEN = 200;
-var api3 = (token, path, init) => apiFetch(API_URL7, token, path, init);
+var api3 = (token, path, init) => apiFetch(API_URL8, token, path, init);
 function normalizeType(raw) {
   const value = (raw ?? "bug").toLowerCase();
   if (TYPES.includes(value)) return value;
@@ -5074,11 +5268,11 @@ function readCliVersion() {
   try {
     const here = dirname4(fileURLToPath2(import.meta.url));
     const candidates = [
-      join14(here, "..", "package.json"),
-      join14(here, "..", "..", "..", "package.json")
+      join15(here, "..", "package.json"),
+      join15(here, "..", "..", "..", "package.json")
     ];
     for (const path of candidates) {
-      if (!existsSync13(path)) continue;
+      if (!existsSync14(path)) continue;
       const pkg2 = JSON.parse(readFileSync15(path, "utf-8"));
       if (pkg2.name === "deepspace" && pkg2.version) return pkg2.version;
     }
@@ -5126,7 +5320,7 @@ function buildFeedbackPayload(input) {
     ...input.context
   };
 }
-var feedback_default = defineCommand19({
+var feedback_default = defineCommand20({
   meta: {
     name: "feedback",
     description: "Submit a bug report, feature request, or feedback to DeepSpace"
@@ -5288,7 +5482,7 @@ Context: deepspace ${payload.cliVersion} \xB7 ${payload.nodeVersion} \xB7 ${payl
 });
 
 // src/cli/commands/secrets.ts
-import { defineCommand as defineCommand20 } from "citty";
+import { defineCommand as defineCommand21 } from "citty";
 import { readFileSync as readFileSync16 } from "fs";
 
 // src/cli/lib/citty-args.ts
@@ -5358,7 +5552,7 @@ function warnIfDebugRoutesEnabled(secrets) {
 }
 var APPLY_HINT = "Run `deepspace deploy` to apply \u2014 secrets take effect at deploy time.";
 var LOCAL_DEV_HINT = "Running `deepspace dev`? Restart it to load the change locally.";
-var list5 = defineCommand20({
+var list5 = defineCommand21({
   meta: { name: "list", description: "List masked secrets in a config" },
   args: {
     ...COMMON_ARGS,
@@ -5389,7 +5583,7 @@ var list5 = defineCommand20({
     }
   }
 });
-var set = defineCommand20({
+var set = defineCommand21({
   meta: { name: "set", description: "Set secrets from KEY=value pairs" },
   args: {
     ...COMMON_ARGS,
@@ -5431,7 +5625,7 @@ var set = defineCommand20({
     }
   }
 });
-var get = defineCommand20({
+var get = defineCommand21({
   meta: { name: "get", description: "Get a secret; pass --plain to print the value" },
   args: {
     ...COMMON_ARGS,
@@ -5456,7 +5650,7 @@ var get = defineCommand20({
     }
   }
 });
-var del2 = defineCommand20({
+var del2 = defineCommand21({
   meta: { name: "delete", description: "Delete one or more secrets" },
   args: {
     ...COMMON_ARGS,
@@ -5486,7 +5680,7 @@ var del2 = defineCommand20({
     }
   }
 });
-var upload = defineCommand20({
+var upload = defineCommand21({
   meta: { name: "upload", description: "Upload secrets from a dotenv or JSON file" },
   args: {
     ...COMMON_ARGS,
@@ -5511,7 +5705,7 @@ var upload = defineCommand20({
     }
   }
 });
-var download = defineCommand20({
+var download = defineCommand21({
   meta: { name: "download", description: "Download a config\u2019s secrets (dotenv/json/shell)" },
   args: {
     ...COMMON_ARGS,
@@ -5535,7 +5729,7 @@ var download = defineCommand20({
     }
   }
 });
-var pull = defineCommand20({
+var pull = defineCommand21({
   meta: { name: "pull", description: "Refresh the .dev.vars cache from the app store" },
   args: { ...COMMON_ARGS },
   async run({ args }) {
@@ -5563,7 +5757,7 @@ var pull = defineCommand20({
     }
   }
 });
-var configsList = defineCommand20({
+var configsList = defineCommand21({
   meta: { name: "list", description: "List the app\u2019s configs" },
   args: { ...COMMON_ARGS },
   async run({ args }) {
@@ -5582,7 +5776,7 @@ var configsList = defineCommand20({
     }
   }
 });
-var configsCreate = defineCommand20({
+var configsCreate = defineCommand21({
   meta: { name: "create", description: "Create a config (optionally copying another)" },
   args: {
     ...COMMON_ARGS,
@@ -5613,7 +5807,7 @@ var configsCreate = defineCommand20({
     }
   }
 });
-var configsDelete = defineCommand20({
+var configsDelete = defineCommand21({
   meta: { name: "delete", description: "Delete a config and all of its secrets" },
   args: {
     ...COMMON_ARGS,
@@ -5630,11 +5824,11 @@ var configsDelete = defineCommand20({
     }
   }
 });
-var configs = defineCommand20({
+var configs = defineCommand21({
   meta: { name: "configs", description: "Manage the app\u2019s secrets configs" },
   subCommands: { list: configsList, create: configsCreate, delete: configsDelete }
 });
-var secrets_default = defineCommand20({
+var secrets_default = defineCommand21({
   meta: { name: "secrets", description: "Manage the app\u2019s secrets store" },
   subCommands: {
     list: list5,
@@ -5649,8 +5843,8 @@ var secrets_default = defineCommand20({
 });
 
 // src/cli/commands/init.ts
-import { defineCommand as defineCommand21 } from "citty";
-var init_default = defineCommand21({
+import { defineCommand as defineCommand22 } from "citty";
+var init_default = defineCommand22({
   meta: {
     name: "init",
     description: "Mint this app\u2019s immutable DEEPSPACE_APP_ID into wrangler.toml"
@@ -5696,11 +5890,11 @@ var init_default = defineCommand21({
 
 // src/cli/cli.ts
 var __dirname = dirname5(fileURLToPath3(import.meta.url));
-var pkg = JSON.parse(readFileSync17(join15(__dirname, "..", "package.json"), "utf-8"));
-if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync14("/etc/ssl/certs/ca-certificates.crt")) {
+var pkg = JSON.parse(readFileSync17(join16(__dirname, "..", "package.json"), "utf-8"));
+if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync15("/etc/ssl/certs/ca-certificates.crt")) {
   process.env.SSL_CERT_FILE = "/etc/ssl/certs/ca-certificates.crt";
 }
-var create2 = defineCommand22({
+var create2 = defineCommand23({
   meta: {
     name: "create",
     description: "Create a new DeepSpace app (runs create-deepspace; all flags are forwarded)"
@@ -5727,7 +5921,7 @@ var create2 = defineCommand22({
     process.exit(res.status ?? 1);
   }
 });
-var main = defineCommand22({
+var main = defineCommand23({
   meta: {
     name: "deepspace",
     version: pkg.version,
@@ -5740,6 +5934,7 @@ var main = defineCommand22({
     logout: logout_default,
     whoami: whoami_default,
     apps: apps_default,
+    usage: usage_default,
     dev: dev_default,
     kill: kill_default,
     test: test_default,