@stacksjs/buddy 0.70.113 → 0.70.115

package/dist/cli.js

@@ -2,6 +2,13 @@
 import process from "node:process";
 import { cli, log } from "@stacksjs/cli";
 import { path as p } from "@stacksjs/path";
+try {
+  const { isSupportedBunVersion, minimumBunVersion } = await import("@stacksjs/utils"), currentBunVersion = typeof Bun < "u" ? Bun.version : process.versions.bun;
+  if (currentBunVersion && !isSupportedBunVersion(currentBunVersion)) {
+    console.error(`[buddy] Bun v${minimumBunVersion} or later is required (current: v${currentBunVersion}). Run: bun upgrade`);
+    process.exit(1);
+  }
+} catch {}
 const args = process.argv.slice(2), requestedCommand = args[0] || "help", isHelpFlag = args.includes("--help") || args.includes("-h"), isVersionOnly = ["--version", "-v", "version"].includes(requestedCommand), isHelpMode = requestedCommand === "help" || isHelpFlag && args.length <= 2, skipAppKeyCheck = [
   "build",
   "lint",
@@ -79,7 +86,7 @@ async function main() {
   if (args.length === 0 && process.stdin.isTTY && !buddy.isNoInteraction)
     await showInteractiveMenu(buddy);
   else
-    buddy.parse();
+    await parseOrExit(buddy);
 }
 async function showInteractiveMenu(buddy) {
   const { bold, green, intro } = await import("@stacksjs/cli"), { select } = await import("@stacksjs/cli");
@@ -107,7 +114,21 @@ async function showInteractiveMenu(buddy) {
     buddy.outputHelp();
   else {
     process.argv = ["bun", "buddy", choice];
-    buddy.parse();
+    await parseOrExit(buddy);
+  }
+}
+async function parseOrExit(buddy) {
+  try {
+    await buddy.parse();
+  } catch (error) {
+    if (!(error?.name === "ClappError" || error?.isUsageError === !0))
+      throw error;
+    process.stderr.write(`${error.message}
+`);
+    if (error.usage)
+      process.stderr.write(`${error.usage}
+`);
+    process.exit(typeof error.exitCode === "number" ? error.exitCode : 2);
   }
 }
 await main();

package/dist/commands/add.js

@@ -5,7 +5,7 @@ import { ExitCode } from "@stacksjs/types";
 import { onUnknownSubcommand } from "@stacksjs/cli";
 export function add(buddy) {
   const descriptions = {
-    add: "Add a stack to your project (coming soon)",
+    add: "Add a stack to your project (table and calendar available, more coming soon)",
     table: "Add the Table Stack to your project",
     calendar: "Add the Calendar Stack to your project",
     all: "Add all stacks",

package/dist/commands/build.js

@@ -1,6 +1,7 @@
 import process from "node:process";
-import { intro, log, onUnknownSubcommand, outro } from "@stacksjs/cli";
+import { intro, log, multiselect, onUnknownSubcommand, outro } from "@stacksjs/cli";
 import { Action } from "@stacksjs/enums";
+import { hasTTY, isCI } from "@stacksjs/env";
 import { ExitCode } from "@stacksjs/types";
 let _runAction;
 async function runAction(...args) {
@@ -60,24 +61,62 @@ export function build(buddy) {
       default:
         break;
     }
-    if (hasNoOptions(options))
-      options.stacks = !0;
+    if (hasNoOptions(options)) {
+      if (!isCI && hasTTY && process.stdin.isTTY) {
+        const answers = await multiselect({
+          message: descriptions.select,
+          choices: [
+            { label: "Frontend (views)", value: "views" },
+            { label: "Components", value: "components" },
+            { label: "Web Components", value: "webComponents" },
+            { label: "Functions", value: "functions" },
+            { label: "Documentation", value: "docs" },
+            { label: "Stacks framework", value: "stacks" },
+            { label: "Buddy CLI", value: "buddy" },
+            { label: "Server (Docker image)", value: "server" }
+          ]
+        }), selected = new Set(answers);
+        if (selected.has("views"))
+          options.views = !0;
+        if (selected.has("components"))
+          options.components = !0;
+        if (selected.has("webComponents"))
+          options.webComponents = !0;
+        if (selected.has("functions"))
+          options.functions = !0;
+        if (selected.has("docs"))
+          options.docs = !0;
+        if (selected.has("stacks"))
+          options.stacks = !0;
+        if (selected.has("buddy"))
+          options.buddy = !0;
+        if (selected.has("server"))
+          options.server = !0;
+      }
+      if (hasNoOptions(options)) {
+        options.views = !0;
+        log.info("No build target specified, defaulting to the frontend (views). See `buddy build --help` for all targets.");
+      }
+    }
+    let succeeded = !0;
     if (options.docs)
-      await runAction(Action.BuildDocs);
+      succeeded = await runBuildAction(Action.BuildDocs, "documentation") && succeeded;
     if (options.components)
-      await runAction(Action.BuildComponentLibs);
+      succeeded = await runBuildAction(Action.BuildComponentLibs, "component libraries") && succeeded;
     if (options.webComponents)
-      await runAction(Action.BuildWebComponentLib);
+      succeeded = await runBuildAction(Action.BuildWebComponentLib, "web component library") && succeeded;
     if (options.functions)
-      await runAction(Action.BuildFunctionLib);
+      succeeded = await runBuildAction(Action.BuildFunctionLib, "function library") && succeeded;
     if (options.views)
-      await runAction(Action.BuildViews);
+      succeeded = await runBuildAction(Action.BuildViews, "frontend") && succeeded;
     if (options.stacks)
-      await runAction(Action.BuildStacks);
+      succeeded = await runBuildAction(Action.BuildStacks, "Stacks framework") && succeeded;
     if (options.buddy)
-      await runAction(Action.BuildCli);
+      succeeded = await runBuildAction(Action.BuildCli, "Buddy CLI") && succeeded;
     if (options.server)
-      await runAction(Action.BuildServer);
+      succeeded = await runBuildAction(Action.BuildServer, "server") && succeeded;
+    if (!succeeded)
+      process.exit(ExitCode.FatalError);
     process.exit(ExitCode.Success);
   });
   buddy.command("build:components", "Automagically build component libraries for production use & npm/CDN distribution").alias("prod:components").option("-c, --components", descriptions.components, { default: !0 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
@@ -151,3 +190,11 @@ export function build(buddy) {
 function hasNoOptions(options) {
   return !options.components && !options.webComponents && !options.elements && !options.functions && !options.views && !options.docs && !options.stacks && !options.buddy && !options.server;
 }
+async function runBuildAction(action, target) {
+  const result = await runAction(action);
+  if (result.isErr) {
+    log.error(`Failed to build ${target}.`, result.error);
+    return !1;
+  }
+  return !0;
+}

package/dist/commands/clean.js

@@ -1,17 +1,24 @@
 import process from "node:process";
 import { runAction } from "@stacksjs/actions";
 import { intro, log, onUnknownSubcommand, outro } from "@stacksjs/cli";
+import { hasTTY, isCI } from "@stacksjs/env";
 import { Action } from "@stacksjs/enums";
 import { ExitCode } from "@stacksjs/types";
 export function clean(buddy) {
   const descriptions = {
     clean: "Removes all node_modules & lock files",
     project: "Target a specific project",
+    force: "Skip the confirmation prompt (required in CI/non-interactive shells)",
     verbose: "Enable verbose output"
   };
-  buddy.command("clean", descriptions.clean).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+  buddy.command("clean", descriptions.clean).option("-p, --project [project]", descriptions.project, { default: !1 }).option("-f, --force", descriptions.force, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
     log.debug("Running `buddy clean` ...", options);
-    if (!buddy.isForce && !buddy.isNoInteraction) {
+    const skipConfirm = options.force === !0 || Boolean(buddy.isForce) || Boolean(buddy.isNoInteraction);
+    if (!skipConfirm && (isCI || !hasTTY || !process.stdin.isTTY)) {
+      log.syncError("Refusing to run `buddy clean` from a non-interactive shell without confirmation.");
+      log.fatal("   \u27A1\uFE0F  Re-run with `--force` to proceed: `buddy clean --force`");
+    }
+    if (!skipConfirm) {
       const { confirm } = await import("@stacksjs/cli");
       if (!await confirm({
         message: "This will remove all node_modules and lock files. Continue?",

package/dist/commands/cloud.js

@@ -1,5 +1,5 @@
 import process from "node:process";
-import { intro, italic, log, onUnknownSubcommand, outro, prompts, runCommand, underline } from "@stacksjs/cli";
+import { intro, italic, log, onUnknownSubcommand, outro, prompts, runCommand, text, underline } from "@stacksjs/cli";
 import {
   addJumpBox,
   deleteCdkRemnants,
@@ -14,6 +14,7 @@ import {
   getCloudFrontDistributionId,
   getJumpBoxInstanceId
 } from "@stacksjs/cloud";
+import { hasTTY, isCI } from "@stacksjs/env";
 import { path as p } from "@stacksjs/path";
 import { ExitCode } from "@stacksjs/types";
 async function createTemporaryCdkRole(roleName) {
@@ -260,16 +261,25 @@ export function cloud(buddy) {
   });
   buddy.command("cloud:remove", descriptions.remove).alias("cloud:destroy").alias("cloud:rm").alias("undeploy").option("--jump-box", "Remove the jump-box", { default: !1 }).option("--force", "Force deletion of stack in bad state", { default: !1 }).option("--yes", "Skip confirmation prompts", { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
     log.debug("Running `buddy cloud:remove` ...", options);
-    const startTime = await intro("buddy cloud:remove");
+    const startTime = await intro("buddy cloud:remove"), environment = process.env.APP_ENV || process.env.NODE_ENV || "production";
+    if (!options.yes && (isCI || !hasTTY || !process.stdin.isTTY)) {
+      log.syncError(`Refusing to remove the "${environment}" cloud infrastructure from a non-interactive shell without confirmation.`);
+      log.syncError("   \u27A1\uFE0F  Re-run with `--yes` to confirm (e.g. in CI): `buddy cloud:remove --yes`");
+      await outro("cloud:remove cancelled.", { startTime, useSeconds: !0 });
+      await log.flush();
+      process.exit(ExitCode.FatalError);
+    }
     if (options.jumpBox) {
-      const { confirm } = await prompts({
-        name: "confirm",
-        type: "confirm",
-        message: "Would you like to remove your jump-box for now?"
-      });
-      if (!confirm) {
-        await outro("Exited", { startTime, useSeconds: !0 });
-        process.exit(ExitCode.Success);
+      if (!options.yes) {
+        const { confirm } = await prompts({
+          name: "confirm",
+          type: "confirm",
+          message: "Would you like to remove your jump-box for now?"
+        });
+        if (!confirm) {
+          await outro("Exited", { startTime, useSeconds: !0 });
+          process.exit(ExitCode.Success);
+        }
       }
       const result = await deleteJumpBox();
       if (isResultError(result)) {
@@ -282,11 +292,17 @@ export function cloud(buddy) {
       });
       process.exit(ExitCode.Success);
     }
+    if (!options.yes) {
+      log.warning(`This will permanently delete the "${environment}" cloud infrastructure (compute, storage, CDN, and DNS managed by Stacks). This cannot be undone.`);
+      if ((await text({ message: `Type the environment name "${environment}" to confirm (blank to cancel):` })).trim() !== environment) {
+        await outro("cloud:remove cancelled - confirmation did not match.", { startTime, useSeconds: !0 });
+        process.exit(ExitCode.Success);
+      }
+    }
     console.log("");
     console.log("Removing cloud infrastructure...");
     console.log(`   ${italic("This typically takes 2-5 minutes.")}`);
     console.log("");
-    const environment = process.env.APP_ENV || process.env.NODE_ENV || "production";
     if (!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY) {
       const { existsSync, readFileSync } = await import("node:fs"), { projectPath } = await import("@stacksjs/path"), envFiles = [
         projectPath(`.env.${environment}`),

package/dist/commands/commit.js

@@ -4,7 +4,7 @@ import { log } from "@stacksjs/logging";
 import { onUnknownSubcommand } from "@stacksjs/cli";
 export function commit(buddy) {
   const descriptions = {
-    commit: "Commit your stashed changes",
+    commit: "Commit your staged changes",
     project: "Target a specific project",
     verbose: "Enable verbose output"
   };

package/dist/commands/create.js

@@ -6,7 +6,6 @@ import { Action } from "@stacksjs/enums";
 import { resolve } from "@stacksjs/path";
 import { isFolder } from "@stacksjs/storage";
 import { ExitCode } from "@stacksjs/types";
-import { useOnline } from "@stacksjs/utils";
 import { uninstallAllFeatures } from "./features";
 import { ensurePantryDependencies, ensurePantryInstalled } from "./setup";
 export function create(buddy) {
@@ -28,13 +27,13 @@ export function create(buddy) {
     minimal: "Skip optional feature bundles (cms, commerce, dashboard, marketing, monitoring, realtime, queue) \u2014 bare-bones API/SPA starter that can re-add them later via `./buddy <feature>:install`.",
     verbose: "Enable verbose output"
   };
-  buddy.command("new [name]", descriptions.command).alias("create [name]").option("-n, --name [name]", descriptions.name, { default: !1 }).option("-u, --ui", descriptions.ui, { default: !0 }).option("-c, --components", descriptions.components, { default: !0 }).option("-w, --web-components", descriptions.webComponents, { default: !0 }).option("-v, --vue", descriptions.vue, { default: !0 }).option("-p, --views", descriptions.views, { default: !0 }).option("-f, --functions", descriptions.functions, { default: !0 }).option("-a, --api", descriptions.api, { default: !0 }).option("-d, --database", descriptions.database, { default: !0 }).option("-ca, --cache", descriptions.cache, { default: !1 }).option("-e, --email", descriptions.email, { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("-m, --minimal", descriptions.minimal, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (name, options) => {
+  buddy.command("new [name]", descriptions.command).alias("create [name]").option("-n, --name [name]", descriptions.name, { default: !1 }).option("-u, --ui", descriptions.ui, { default: !0 }).option("-c, --components", descriptions.components, { default: !0 }).option("-w, --web-components", descriptions.webComponents, { default: !0 }).option("-v, --vue", descriptions.vue, { default: !0 }).option("-p, --views", descriptions.views, { default: !0 }).option("-f, --functions", descriptions.functions, { default: !0 }).option("-a, --api", descriptions.api, { default: !0 }).option("-d, --database", descriptions.database, { default: !0 }).option("-ca, --cache", descriptions.cache, { default: !1 }).option("-e, --email", descriptions.email, { default: !1 }).option("-P, --project [project]", descriptions.project, { default: !1 }).option("-m, --minimal", descriptions.minimal, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (name, options) => {
     log.debug("Running `buddy new <name>` ...", options);
     const startTime = await intro("buddy new");
     name = name ?? options.name;
     const path = resolve(process.cwd(), name);
     isFolderCheck(path);
-    onlineCheck();
+    await onlineCheck();
     const result = await download(name, path, options);
     if (result.isErr) {
       log.error(result.error);
@@ -50,6 +49,8 @@ export function create(buddy) {
       log.success(dim(`[${time.toFixed(2)}ms] Completed`));
     }
     log.info(bold("Welcome to the Stacks Framework! \u269B\uFE0F"));
+    log.info(`Get started: ${cyan(`cd ${name}`)} and then ${cyan("./buddy dev")}`);
+    log.info(`Run ${cyan("./buddy doctor")} anytime to check your setup`);
     log.info("To learn more, visit https://stacksjs.com");
     process.exit(ExitCode.Success);
   });
@@ -61,19 +62,28 @@ function isFolderCheck(path) {
     process.exit(ExitCode.FatalError);
   }
 }
-function onlineCheck() {
-  if (!useOnline()) {
-    log.info("It appears you are disconnected from the internet.");
-    log.info("The Stacks setup requires a brief internet connection for setup.");
-    log.info("For instance, it installs your dependencies from.");
-    process.exit(ExitCode.FatalError);
+async function onlineCheck() {
+  if (await isOnline())
+    return;
+  log.info("It appears you are disconnected from the internet.");
+  log.info("Creating a new project requires a brief internet connection to download the template and install dependencies.");
+  process.exit(ExitCode.FatalError);
+}
+async function isOnline() {
+  try {
+    return (await fetch("https://github.com", {
+      method: "HEAD",
+      signal: AbortSignal.timeout(3000)
+    })).ok;
+  } catch {
+    return !1;
   }
 }
 async function download(name, path, _options) {
   log.info("Setting up your stack.");
   try {
     const { downloadTemplate } = await import("@stacksjs/gitit");
-    await downloadTemplate("stacks", { dir: name });
+    await downloadTemplate("gh:stacksjs/stacks", { dir: name });
     log.success(`Successfully scaffolded your project at ${cyan(path)}`);
     return { isErr: !1 };
   } catch (error) {

package/dist/commands/deploy.js

@@ -738,8 +738,11 @@ async function runHetznerDeploy(args) {
     "temp",
     ".DS_Store",
     "*.log",
+    ".env",
     ".env.local",
-    ".env.production.bak"
+    ".env.keys",
+    ".env.production.bak",
+    ".env.production.plain"
   ].flatMap((p) => [`--exclude='${p}'`, `--exclude='*/${p}'`]);
   if (onlySite && !sites[onlySite]) {
     log.error(`--site '${onlySite}' is not a configured site. Available: ${Object.keys(sites).join(", ")}`);
@@ -861,7 +864,10 @@ async function resolveAttachTargetBox(owner, environment) {
   return { serverId: chosen.id, serverName: chosen.name, publicIp: chosen.public_net?.ipv4?.ip };
 }
 export async function provisionMailTenant(ip, logger) {
-  const cfg = emailConfig || {}, domain = cfg.domain || (typeof cfg.from?.address === "string" && cfg.from.address.includes("@") ? cfg.from.address.split("@")[1] : void 0), forwards = cfg.forwards && typeof cfg.forwards === "object" ? cfg.forwards : {}, hasForwards = Object.keys(forwards).length > 0, boxes = domain ? resolveMailboxes(cfg.mailboxes, domain) : [];
+  const cfg = emailConfig || {};
+  if (cfg.server?.enabled === !1)
+    return null;
+  const domain = cfg.domain || (typeof cfg.from?.address === "string" && cfg.from.address.includes("@") ? cfg.from.address.split("@")[1] : void 0), forwards = cfg.forwards && typeof cfg.forwards === "object" ? cfg.forwards : {}, hasForwards = Object.keys(forwards).length > 0, boxes = domain ? resolveMailboxes(cfg.mailboxes, domain) : [];
   if (!domain && !hasForwards)
     return null;
   const { execSync } = await import("node:child_process"), sshArgs = ["-o", "StrictHostKeyChecking=accept-new", "-o", "BatchMode=yes", "-o", "ConnectTimeout=20", `root@${ip}`], forwardsB64 = hasForwards ? Buffer.from(JSON.stringify(forwards)).toString("base64") : "", readme = "Auto-forwarding rules, re-read on every message (edits take effect immediately, no restart). KEY = the delivered mailbox: the FULL address for per-domain isolated mailboxes (e.g. no-reply@app.com), or a bare local-part for legacy role mailboxes. VALUE = list of destination addresses; targets on a local domain are written straight to that mailbox Maildir, external targets are relayed. Managed by buddy deploy " + "from config/email.ts (merge-based \u2014 hand edits to other keys are preserved).", readmeB64 = Buffer.from(readme).toString("base64"), boxesB64 = boxes.length ? Buffer.from(boxes.map((b) => `${b.address}	${b.password}`).join(`
@@ -1083,6 +1089,21 @@ async function reconcileConfigDns(sites, logger) {
       logger.warn(`DNS (config/dns.ts) reconcile for ${domain} failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+async function verifyDnsRecord(provider, domain, fqdn, ip) {
+  try {
+    if (typeof provider?.listRecords !== "function")
+      return !0;
+    const res = await provider.listRecords(domain);
+    if (!res?.success || !Array.isArray(res.records))
+      return !0;
+    return res.records.some((r) => {
+      const name = typeof r?.name === "string" ? r.name.replace(/\.$/, "") : "";
+      return r?.type === "A" && name === fqdn && r?.content === ip;
+    });
+  } catch {
+    return !0;
+  }
+}
 async function reconcileHetznerDns(sites, ip, logger) {
   const domains = new Set;
   for (const site of Object.values(sites))
@@ -1129,11 +1150,15 @@ async function reconcileHetznerDns(sites, ip, logger) {
         continue;
       }
       for (const sub of ["", "www"]) {
-        const fqdn = sub ? `${sub}.${domain}` : domain, res = await provider.upsertRecord(domain, { name: sub, type: "A", content: ip, ttl: 600 });
-        if (res?.success === !1)
-          logger.warn(`  DNS: ${fqdn} \u2192 ${ip} failed: ${res.error || "unknown error"}`);
-        else
+        const fqdn = sub ? `${sub}.${domain}` : domain, res = await provider.upsertRecord(domain, { name: fqdn, type: "A", content: ip, ttl: 600 });
+        if (res?.success === !1) {
+          logger.warn(`  DNS: ${fqdn} \u2192 ${ip} failed: ${res.error || res.message || "unknown error"}`);
+          continue;
+        }
+        if (await verifyDnsRecord(provider, domain, fqdn, ip))
           logger.success(`  DNS: ${fqdn} \u2192 ${ip} (${provider.name})`);
+        else
+          logger.warn(`  DNS: ${fqdn} \u2192 ${ip} reported success at ${provider.name} but no matching A record exists \u2014 create it manually: A ${fqdn} \u2192 ${ip}`);
       }
     } catch (err) {
       logger.warn(`  DNS: ${domain} reconciliation failed: ${err?.message || err}`);

package/dist/commands/dev.js

@@ -6,7 +6,6 @@ import { bold, cyan, dim, green, intro, log, onUnknownSubcommand, outro, prompts
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { promises as dns } from "node:dns";
 import { Action } from "@stacksjs/enums";
 import { libsPath, projectPath } from "@stacksjs/path";
 import { ExitCode } from "@stacksjs/types";
@@ -187,7 +186,7 @@ export function dev(buddy) {
   onUnknownSubcommand(buddy, "dev");
 }
 export async function startDevelopmentServer(_options, _startTime) {
-  const options = _options, startedAt = _startTime, appUrl = process.env.APP_URL, nativeMode = options.native === !0, proxyManagedExternally = process.env.STACKS_PROXY_MANAGED === "1", frontendPort = Number(process.env.PORT) || 3000, apiPort = Number(process.env.PORT_API) || 3008, docsPort = Number(process.env.PORT_DOCS) || 3006, dashboardPort = Number(process.env.PORT_ADMIN) || 3002, includeDashboard = process.env.STACKS_DEV_DASHBOARD === "1", appLooksCustom = !nativeMode && appUrl && appUrl !== "localhost" && !appUrl.includes("localhost:"), domain = appLooksCustom ? appUrl.replace(/^https?:\/\//, "") : null, isLocalDevTld = (host) => host === "localhost" || host.endsWith(".localhost") || host.endsWith(".test") || host.endsWith(".invalid"), domainIsPublic = Boolean(domain) && process.env.STACKS_DEV_ALLOW_PUBLIC_DOMAIN !== "1" && !isLocalDevTld(domain) && (await dns.resolve4(domain).catch(() => [])).some((address) => !address.startsWith("127.")), hasCustomDomain = appLooksCustom && !proxyManagedExternally && !domainIsPublic, dashboardDomain = domain ? `dashboard.${domain}` : null, frontendUrl = domain ? `https://${domain}` : `http://localhost:${frontendPort}`, apiUrl = domain ? `https://${domain}/api` : `http://localhost:${apiPort}`, docsUrl = domain ? `https://${domain}/docs` : `http://localhost:${docsPort}`, dashboardUrl = dashboardDomain ? `https://${dashboardDomain}` : `http://localhost:${dashboardPort}`, managedPorts = [
+  const options = _options, startedAt = _startTime, appUrl = process.env.APP_URL, nativeMode = options.native === !0, proxyManagedExternally = process.env.STACKS_PROXY_MANAGED === "1", frontendPort = Number(process.env.PORT) || 3000, apiPort = Number(process.env.PORT_API) || 3008, docsPort = Number(process.env.PORT_DOCS) || 3006, dashboardPort = Number(process.env.PORT_ADMIN) || 3002, includeDashboard = process.env.STACKS_DEV_DASHBOARD === "1", appLooksCustom = !nativeMode && appUrl && appUrl !== "localhost" && !appUrl.includes("localhost:"), domain = appLooksCustom ? appUrl.replace(/^https?:\/\//, "") : null, localhostOnly = process.env.STACKS_DEV_LOCALHOST === "1", hasCustomDomain = appLooksCustom && !proxyManagedExternally && !localhostOnly, dashboardDomain = domain ? `dashboard.${domain}` : null, frontendUrl = domain ? `https://${domain}` : `http://localhost:${frontendPort}`, apiUrl = domain ? `https://${domain}/api` : `http://localhost:${apiPort}`, docsUrl = domain ? `https://${domain}/docs` : `http://localhost:${docsPort}`, dashboardUrl = dashboardDomain ? `https://${dashboardDomain}` : `http://localhost:${dashboardPort}`, managedPorts = [
     frontendPort,
     apiPort,
     docsPort,
@@ -201,6 +200,8 @@ export async function startDevelopmentServer(_options, _startTime) {
   if (process.env.STACKS_DEV_NO_KILL !== "1")
     await cleanupStaleDevProcesses(managedPorts);
   const rpxTlsPreflight = hasCustomDomain && domain ? prepareRpxTlsForDev({ domain, includeDashboard, options }) : Promise.resolve();
+  if (localhostOnly && domain && !proxyManagedExternally)
+    removeStalePublicDomainOverrides(domain, includeDashboard, options.verbose ?? !1).catch(() => {});
   rpxTlsPreflight.catch(() => {});
   let isExiting = !1, closeNativeApp;
   const SHUTDOWN_GRACE_MS = 1500, cleanup = () => {
@@ -281,7 +282,7 @@ export async function startDevelopmentServer(_options, _startTime) {
     printDevReadyBanner({
       options,
       nativeMode,
-      hasCustomDomain: !!appLooksCustom,
+      hasCustomDomain: !!appLooksCustom && !localhostOnly,
       proxyReachable: proxyManagedExternally ? !0 : proxyReachable,
       frontendUrl,
       apiUrl,
@@ -363,21 +364,22 @@ function printDevReadyBanner(input) {
     domain,
     dashboardPort,
     dashboardDomain
-  } = input, verbose = options.verbose ?? !1, useProxy = hasCustomDomain && proxyReachable, feUrl = `http://localhost:${frontendPort}`, apUrl = `http://localhost:${apiPort}`, dcUrl = `http://localhost:${docsPort}`, dbUrl = `http://localhost:${dashboardPort}`, blogUrl = `${feUrl}/blog`;
+  } = input, verbose = options.verbose ?? !1, useProxy = hasCustomDomain && proxyReachable, feUrl = useProxy ? frontendUrl : `http://localhost:${frontendPort}`, apUrl = useProxy ? apiUrl : `http://localhost:${apiPort}`, dcUrl = useProxy ? docsUrl : `http://localhost:${docsPort}`, dbUrl = useProxy ? dashboardUrl : `http://localhost:${dashboardPort}`, blogUrl = `${feUrl}/blog`;
   console.log();
   console.log(`  ${green("\u279C")}  ${bold("Frontend")}:    ${cyan(feUrl)}`);
   if (nativeMode)
-    console.log(`  ${green("\u279C")}  ${bold("Native")}:      ${cyan(`Craft \u2192 http://localhost:${frontendPort}`)}`);
+    console.log(`  ${green("\u279C")}  ${bold("Native")}:      ${cyan(`Craft \u2192 ${feUrl}`)}`);
   console.log(`  ${green("\u279C")}  ${bold("API")}:         ${cyan(apUrl)}`);
   console.log(`  ${green("\u279C")}  ${bold("Docs")}:        ${cyan(dcUrl)}`);
   if (blogIsConfigured())
     console.log(`  ${green("\u279C")}  ${bold("Blog")}:        ${cyan(blogUrl)}`);
   if (includeDashboard)
     console.log(`  ${green("\u279C")}  ${bold("Dashboard")}:   ${cyan(dbUrl)}`);
-  if (useProxy && domain)
-    console.log(`  ${dim("\u279C")}  ${dim("Proxy")}:       ${dim(`${frontendUrl} (local HTTPS via rpx)`)}`);
-  if (useProxy && includeDashboard && dashboardDomain)
-    console.log(`  ${dim("\u279C")}  ${dim("Proxy")}:       ${dim(`${dashboardUrl} (local HTTPS via rpx)`)}`);
+  if (useProxy) {
+    console.log(`  ${dim("\u279C")}  ${dim("Direct")}:      ${dim(`http://localhost:${frontendPort} (bypasses the proxy)`)}`);
+    if (includeDashboard && dashboardDomain)
+      console.log(`  ${dim("\u279C")}  ${dim("Direct")}:      ${dim(`http://localhost:${dashboardPort} (dashboard, bypasses the proxy)`)}`);
+  }
   if (isComingSoonMode()) {
     console.log();
     console.log(`  ${yellow("\u25CF")}  ${bold(yellow("Coming soon mode"))} ${dim("\u2014 visitors see the holding page; bypass with the coming-soon secret.")}`);
@@ -849,15 +851,7 @@ async function removeStalePublicDomainOverrides(domain, includeDashboard, verbos
   }
 }
 async function prepareRpxTlsForDev(input) {
-  const { domain, includeDashboard, options } = input, verbose = options.verbose ?? !1;
-  if (process.env.STACKS_DEV_ALLOW_PUBLIC_DOMAIN !== "1") {
-    if ((await dns.resolve4(domain).catch(() => [])).some((address) => !address.startsWith("127."))) {
-      log.warn(`Skipping local DNS override for public domain ${domain}; use a .localhost/.test domain for development`);
-      await removeStalePublicDomainOverrides(domain, includeDashboard, verbose);
-      return;
-    }
-  }
-  const hosts = [
+  const { domain, includeDashboard, options } = input, verbose = options.verbose ?? !1, hosts = [
     domain,
     ...includeDashboard ? [`dashboard.${domain}`] : []
   ], hostsNeedingFile = hosts.filter((host) => {
@@ -877,8 +871,11 @@ async function prepareRpxTlsForDev(input) {
 }
 async function startRpxDaemonIfNeeded(input) {
   const { ensureDaemonRunning, isDaemonRunning: isRpxUp } = await importDevelopmentRpx();
-  if (await isRpxUp())
-    return;
+  if (await isRpxUp()) {
+    if (await waitForHttpsProxy(443, 1500))
+      return;
+    await input.stopRpx({ timeoutMs: 5000 }).catch(() => {});
+  }
   const spawnOpts = {
     spawnCommand: input.spawnCommand,
     spawnCwd: resolveRpxDaemonSpawnCwd(),

package/dist/commands/doctor.d.ts

@@ -1,2 +1,11 @@
 import type { CLI } from '@stacksjs/types';
 export declare function doctor(buddy: CLI): void;
+/**
+ * Throw inside a probe fn to record a warning instead of a failure.
+ * Used when a check cannot run to completion (e.g. the driver exposes
+ * no raw query method, so there is nothing to probe with) or when the
+ * finding is advisory rather than fatal (e.g. a busy dev port).
+ */
+declare class ProbeWarning extends Error {
+
+}

package/dist/commands/doctor.js

@@ -2,22 +2,28 @@ import process from "node:process";
 import { bold, dim, green, intro, log, onUnknownSubcommand, red, yellow } from "@stacksjs/cli";
 import { feature } from "@stacksjs/config";
 import { storage } from "@stacksjs/storage";
+import { isSupportedBunVersion, isVersionGreaterThanOrEqual, minimumBunVersion } from "@stacksjs/utils";
 import { FEATURE_NAMES, featurePathsPresent } from "./features";
+const minimumSqliteVersion = "3.47.2";
+
+class ProbeWarning extends Error {
+}
 async function probe(checks, name, fn, timeoutMs = 2000) {
-  const start = Date.now();
+  const start = Date.now(), ac = new AbortController, timer = setTimeout(() => ac.abort(), timeoutMs);
   try {
-    const ac = new AbortController, timer = setTimeout(() => ac.abort(), timeoutMs), message = await Promise.race([
+    const message = await Promise.race([
       fn(),
       new Promise((_, rej) => ac.signal.addEventListener("abort", () => rej(Error(`timed out (>${Math.round(timeoutMs / 1000)}s)`))))
     ]);
-    clearTimeout(timer);
     checks.push({ name, status: "pass", message: `${message} (${Date.now() - start}ms)` });
   } catch (err) {
     checks.push({
       name,
-      status: "fail",
+      status: err instanceof ProbeWarning ? "warn" : "fail",
       message: err instanceof Error ? err.message : String(err)
     });
+  } finally {
+    clearTimeout(timer);
   }
 }
 export function doctor(buddy) {
@@ -25,19 +31,18 @@ export function doctor(buddy) {
     log.debug("Running `buddy doctor` ...");
     await intro("buddy doctor");
     const checks = [], bunVersion = process.versions.bun;
-    if (bunVersion)
-      if (Number.parseInt(bunVersion.split(".")[0] || "0", 10) >= 1)
-        checks.push({
-          name: "Bun Runtime",
-          status: "pass",
-          message: `v${bunVersion}`
-        });
-      else
-        checks.push({
-          name: "Bun Runtime",
-          status: "warn",
-          message: `v${bunVersion} (v1.0+ recommended)`
-        });
+    if (bunVersion && isSupportedBunVersion(bunVersion))
+      checks.push({
+        name: "Bun Runtime",
+        status: "pass",
+        message: `v${bunVersion}`
+      });
+    else if (bunVersion)
+      checks.push({
+        name: "Bun Runtime",
+        status: "fail",
+        message: `v${bunVersion} (requires v${minimumBunVersion} or later, run: bun upgrade)`
+      });
     else
       checks.push({
         name: "Bun Runtime",
@@ -100,9 +105,34 @@ export function doctor(buddy) {
         status: "fail",
         message: "Not set \u2014 features that depend on it (encrypted columns, signed URLs, env decryption) will refuse to run. Run `buddy key:generate`."
       });
+    await probe(checks, "SQLite Engine", async () => {
+      const { Database } = await import("bun:sqlite"), memory = new Database(":memory:");
+      let version;
+      try {
+        const row = memory.query("SELECT sqlite_version() AS version").get();
+        if (typeof row?.version === "string")
+          version = row.version;
+      } finally {
+        memory.close();
+      }
+      if (!version)
+        throw new ProbeWarning("could not read sqlite_version() (skipped)");
+      if (!isVersionGreaterThanOrEqual(version, minimumSqliteVersion))
+        throw Error(`v${version} is below the required v${minimumSqliteVersion} (system.sqlite in package.json); upgrade Bun for a newer bundled SQLite`);
+      return `v${version}`;
+    });
     await probe(checks, "Database", async () => {
-      const { db } = await import("@stacksjs/database");
-      await db.unsafe?.("SELECT 1");
+      const { db } = await import("@stacksjs/database"), unsafe = db.unsafe;
+      if (typeof unsafe !== "function")
+        throw new ProbeWarning("driver exposes no raw query method (skipped)");
+      const statement = unsafe("SELECT 1");
+      if (!statement || typeof statement.then !== "function" && typeof statement.execute !== "function")
+        throw new ProbeWarning("driver returned a non-executable statement (skipped)");
+      const result = typeof statement.execute === "function" ? await statement.execute() : await statement;
+      if (result === void 0 || result === null)
+        throw Error("probe query returned no result");
+      if (Array.isArray(result) && result.length === 0)
+        throw Error("probe query returned no rows");
       return "Reachable";
     });
     await probe(checks, "Database FKs", async () => {
@@ -303,6 +333,34 @@ export function doctor(buddy) {
         message: `Could not audit dev-domain overrides: ${err instanceof Error ? err.message : String(err)}`
       });
     }
+    await probe(checks, "Dev ports", async () => {
+      const net = await import("node:net"), { config } = await import("@stacksjs/config"), configured = config.ports ?? {}, targets = [
+        { name: "frontend", key: "frontend", envVar: "PORT", fallback: 3000 },
+        { name: "api", key: "api", envVar: "PORT_API", fallback: 3008 },
+        { name: "docs", key: "docs", envVar: "PORT_DOCS", fallback: 3006 },
+        { name: "dashboard", key: "admin", envVar: "PORT_ADMIN", fallback: 3002 }
+      ].map((t) => ({ ...t, port: Number(configured[t.key]) || t.fallback })), canConnect = (port, host) => new Promise((resolve) => {
+        const socket = net.createConnection({ port, host });
+        socket.setTimeout(400);
+        const done = (occupied) => {
+          socket.destroy();
+          resolve(occupied);
+        };
+        socket.once("connect", () => done(!0));
+        socket.once("timeout", () => done(!1));
+        socket.once("error", () => done(!1));
+      }), occupied = new Set;
+      await Promise.all([...new Set(targets.map((t) => t.port))].map(async (port) => {
+        if (await canConnect(port, "127.0.0.1") || await canConnect(port, "::1"))
+          occupied.add(port);
+      }));
+      const busy = targets.filter((t) => occupied.has(t.port));
+      if (busy.length > 0) {
+        const list = busy.map((t) => `${t.name} :${t.port} (${t.envVar})`).join(", ");
+        throw new ProbeWarning(`in use: ${list}. buddy dev will fail to bind; stop the process holding the port or set the override env var`);
+      }
+      return `All free: ${targets.map((t) => `${t.name} :${t.port}`).join(", ")}`;
+    });
     try {
       const orphans = [];
       for (const name of FEATURE_NAMES) {