nukebase 2.2.0 → 2.2.2

package/bin/nukebase.js

@@ -33,7 +33,9 @@ function usage() {
 
 Usage: nukebase <command>        (or: npx nukebase <command>)
 
-New here? Run: npx nukebase start
+New here? Run: npx nukebase guide
+  what NukeBase can do and how to plan your app with Claude; creates nothing
+Ready to set up? Run: npx nukebase start
   signs you in, creates a project and downloads it, ready to build
 
 Accounts
@@ -80,7 +82,7 @@ In a project folder (runs as the account that owns the project)
   domain <name> [--email e]  connect in one go (DNS already set)
   domain remove              disconnect the custom domain
   domain email               send the app's emails from the custom domain
-                             (--root | --sub, --reply-to you@gmail.com, --wait)
+                             (--root | --sub, --wait)
   domain email remove        go back to sending from nukebase.com
   logs [--follow]            recent log output; --follow streams
   download [--out f.zip]     the project ZIP, exactly as the server has it
@@ -122,6 +124,8 @@ if (command === 'start') {
 
 if (args.has('version') && !command) {
   console.log(version);
+} else if (command === 'guide') {
+  require('../lib/guide').guideCommand();
 } else if (!command || command === 'help' || (args.has('help') && !command)) {
   usage();
 } else if (ACCOUNT_COMMANDS.includes(command) || command === 'setup') {

package/lib/account-commands.js

@@ -296,10 +296,69 @@ function namePackage(dir, name) {
   } catch { return false; }
 }
 
-// Create `name` on the server and unpack it into `dest`. Returns
-// { exists: true } when the account already has a project by that name, so
-// `start` can try the next one; any other failure stops the command.
-async function createProject({ acct, api, name, tier, dest, install }) {
+// Read a download to the end, showing how much has arrived: one line that
+// updates in a terminal, or a line every 10 MB when the output goes to a file
+// or an AI agent (where \r updates would pile up). The archives are streamed
+// without a length, so it shows MB so far, not a percentage.
+async function readWithProgress(res, label) {
+  const tty = process.stdout.isTTY;
+  const mb = (n) => (n / 1048576).toFixed(1);
+  const chunks = [];
+  let got = 0, lastShown = 0, lastLine = 0;
+  const show = (final) => {
+    if (tty) process.stdout.write(`\r  ${label}… ${mb(got)} MB${final ? '\n' : ''}`);
+    else if (final || got - lastLine >= 10 * 1048576) { console.log(`  ${label}… ${mb(got)} MB`); lastLine = got; }
+  };
+  if (!res.body || typeof res.body.getReader !== 'function') {
+    const buf = Buffer.from(await res.arrayBuffer());
+    got = buf.length; show(true);
+    return buf;
+  }
+  const reader = res.body.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(Buffer.from(value));
+      got += value.length;
+      if (Date.now() - lastShown > 250) { lastShown = Date.now(); show(false); }
+    }
+  } catch (e) {
+    // End the half-drawn progress line, so whatever is printed next starts clean.
+    if (tty && got) process.stdout.write('\n');
+    throw e;
+  }
+  show(true);
+  return Buffer.concat(chunks);
+}
+
+// The project's files as the server has them, without node_modules (an
+// `npm install` follows; servers too old for ?skip send them anyway). One
+// retry, since this runs right after a dropped connection.
+async function downloadExisting({ acct, api, name }) {
+  const headers = { 'X-Project': name, Cookie: cookieFor(acct) };
+  const url = `${api}/download-project?project=${encodeURIComponent(name)}&skip=node_modules`;
+  let lastErr = null;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      const dl = await fetch(url, { headers });
+      if (!dl.ok) { lastErr = new Error(`the server answered ${dl.status}`); continue; }
+      return await readWithProgress(dl, `Downloading ${name}`);
+    } catch (e) {
+      lastErr = e;
+      if (attempt === 1) console.log('  (download interrupted, trying again)');
+    }
+  }
+  fail(`${name} exists but could not be downloaded (${lastErr.cause?.message || lastErr.message}).\n` +
+    `   In an empty folder, run: nukebase link ${name}   then: nukebase pull --yes   then: npm install`);
+}
+
+// Create `name` on the server and unpack it into `dest`. When the account
+// already has a project by that name: with `reuse`, that project is
+// downloaded into `dest` instead (`start`: running it again finishes the
+// job rather than making name-2); without, returns { exists: true }. Any
+// other failure stops the command.
+async function createProject({ acct, api, name, tier, dest, install, reuse = false }) {
   console.log(`\n🚀 Creating ${name}...`);
   const headers = (extra = {}) => ({ ...extra, 'X-Project': name, Cookie: cookieFor(acct) });
 
@@ -325,14 +384,7 @@ async function createProject({ acct, api, name, tier, dest, install }) {
     }
     if (!probe.ok) fail(`Create failed: ${why} (and the server answered ${probe.status} when asked whether ${name} exists).`);
     console.log(`  (the connection dropped while the server finished setting up ${name} — it exists, downloading it)`);
-    let dl;
-    try {
-      dl = await fetch(`${api}/download-project?project=${encodeURIComponent(name)}`, { headers: headers() });
-    } catch (e) {
-      fail(`${name} was created but could not be downloaded (${e.cause?.message || e.message}). Link to it: nukebase link ${name}`);
-    }
-    if (!dl.ok) fail(`${name} was created but could not be downloaded (${dl.status}). Link to it: nukebase link ${name}`);
-    return Buffer.from(await dl.arrayBuffer());
+    return downloadExisting({ acct, api, name });
   }
 
   let res = null, zip = null;
@@ -348,19 +400,25 @@ async function createProject({ acct, api, name, tier, dest, install }) {
   if (res && !res.ok) {
     let msg = '';
     try { msg = (await res.json()).error; } catch {}
-    if (res.status === 400 && /already exists/i.test(msg || '')) return { exists: true };
-    if (res.status === 401) fail(`The sign-in for ${acct.label} is no longer valid. Run: nukebase login --email ${acct.label}`);
-    // No plan or no credit: fixed on the dashboard.
-    if (res.status === 403 && /plan|funds|credit|wallet|balance|upgrade/i.test(msg)) {
-      fail(`${msg}\n   Manage your plan at ${api}/`);
+    const taken = res.status === 400 && /already exists/i.test(msg || '');
+    if (taken && !reuse) return { exists: true };
+    if (taken) {
+      console.log(`  ${name} already exists in your account, so downloading it here instead of making a new one.`);
+      zip = await downloadExisting({ acct, api, name });
+    } else {
+      if (res.status === 401) fail(`The sign-in for ${acct.label} is no longer valid. Run: nukebase login --email ${acct.label}`);
+      // No plan or no credit: fixed on the dashboard.
+      if (res.status === 403 && /plan|funds|credit|wallet|balance|upgrade/i.test(msg)) {
+        fail(`${msg}\n   Manage your plan at ${api}/`);
+      }
+      fail(`Create failed (${res.status}): ${msg || res.statusText}`);
     }
-    fail(`Create failed (${res.status}): ${msg || res.statusText}`);
   }
 
   // The server finishes setup as the ZIP finishes streaming, so read it all.
   // A drop here is the same case as above.
   if (!zip) {
-    try { zip = Buffer.from(await res.arrayBuffer()); }
+    try { zip = await readWithProgress(res, `Downloading ${name}`); }
     catch (e) { zip = await recover(e); }
   }
   fs.mkdirSync(dest, { recursive: true });
@@ -373,7 +431,7 @@ async function createProject({ acct, api, name, tier, dest, install }) {
   console.log(`✓ Downloaded ${count} files into ${path.relative(process.cwd(), dest) || 'this folder'}`);
 
   if (install && fs.existsSync(path.join(dest, 'package.json'))) {
-    console.log('\n📦 npm install\n');
+    console.log('\n📦 Installing packages (npm install)…\n');
     // One command string under a shell: npm is npm.cmd on Windows, which
     // needs a shell, and Node 26 deprecates passing separate args with one.
     const r = spawnSync('npm install', [], { cwd: dest, stdio: 'inherit', shell: true });
@@ -496,19 +554,17 @@ async function startCommand(args) {
   const intoHere = isEmptyFolder(here);
   const given = args.positional.find(a => !a.includes('@') && PROJECT_NAME_RE.test(a) && !resolveTier(a, catalog));
   const base = given || (intoHere && nameFromFolder(here)) || 'myapp';
-  const candidates = given ? [given] : [base, ...Array.from({ length: 8 }, (_, i) => `${base}-${i + 2}`.slice(0, 31))];
+  // One name. If the account already has a project by it, that project is
+  // downloaded here rather than a name-2 being created: running start again
+  // after a hiccup finishes the job.
+  const name = base;
+  const dest = intoHere ? here : path.resolve(here, name);
+  if (!intoHere && fs.existsSync(dest) && fs.readdirSync(dest).length) {
+    fail(`There is already a folder named ${name} here with files in it. Run this in an empty folder, or choose another name: npx nukebase start <name>`);
+  }
 
   console.log(`  Size: ${tierLabel(catalog, tier)}${isFree ? ' (paid from your $10 monthly credit)' : ''}`);
-  let created = null, name = null, dest = null;
-  for (const candidate of candidates) {
-    dest = intoHere ? here : path.resolve(here, candidate);
-    if (!intoHere && fs.existsSync(dest) && fs.readdirSync(dest).length) continue;
-    const out = await createProject({ acct, api, name: candidate, tier, dest, install: !args.has('no-install') });
-    if (out.exists) { console.log(`  (${candidate} is taken, trying another name)`); continue; }
-    created = out; name = candidate;
-    break;
-  }
-  if (!created) fail(given ? `You already have a project named ${given}. Pick another name: npx nukebase start <name>` : 'Could not find a free project name. Run: npx nukebase start <name>');
+  const created = await createProject({ acct, api, name, tier, dest, install: !args.has('no-install'), reuse: true });
 
   // Written for whoever runs this next, person or AI agent.
   console.log(`\n✅ Your app "${name}" is live at ${created.url}`);

package/lib/args.js

@@ -6,7 +6,7 @@
 // `--name=value` works too.
 
 const VALUE_FLAGS = new Set([
-  'region', 'api', 'as', 'tier', 'streams', 'out', 'email', 'to', 'include', 'name', 'reply-to'
+  'region', 'api', 'as', 'tier', 'streams', 'out', 'email', 'to', 'include', 'name', 'reply-to', 'from'
 ]);
 
 const SHORT = { y: 'yes', f: 'follow', h: 'help', v: 'version' };

package/lib/guide.js

@@ -0,0 +1,116 @@
+// `nukebase guide`: the front door for someone who is not a coder.
+//
+// It creates nothing and signs nothing in. It prints a briefing written for
+// the AI assistant the person is talking to (usually Claude Code), so the
+// assistant knows what NukeBase can do and holds a conversation about the
+// app before `nukebase start` creates anything. The person's own words on the
+// landing page are just: "Run npx nukebase@latest guide, then help me build
+// my app."
+//
+// No prices here on purpose: they change, and the dashboard shows them.
+
+const GUIDE = `
+NUKEBASE GUIDE
+==============
+
+For the AI assistant reading this
+---------------------------------
+The person you are helping may not be a coder. They want to build an app
+with NukeBase. Nothing has been created yet, and nothing should be until they
+agree to a plan.
+
+  1. Have a short, friendly conversation to understand what they want
+     (questions below). Ask one or two at a time, in plain words. No jargon:
+     never ask them about databases, frameworks or APIs.
+  2. Play the plan back in a few plain sentences, including the project name,
+     and ask: "Shall I set it up?"
+  3. Only after they say yes, run the setup command (Commands, below), then
+     read the CLAUDE.md file in the new project folder before writing any
+     code. It explains how NukeBase apps are built.
+  4. Save the agreed plan as PLAN.md in the project folder, so the next
+     session knows what was agreed.
+  5. Build it, put it live, and show them the link. Then offer the extras
+     they would want: their own domain, emails from that domain.
+
+What NukeBase is
+----------------
+One place to build and run a web app: the website, its data, user sign-in,
+email and hosting all come together, with nothing else to sign up for or
+set up. Apps work on phones and computers and can be added to a phone's home
+screen like an app from the store.
+
+What it can do (features)
+-------------------------
+  Website hosting        Live at its own web address the moment it is set up.
+  Live data              A built-in database. When one person changes
+                         something, everyone else's screen updates instantly
+                         (no refreshing): bookings, chats, sign-up lists.
+  User sign-in           People sign in with a link sent to their email. No
+                         passwords. One browser can stay signed in to several
+                         accounts and switch between them.
+  Who can see what       Rules for which users can read or change which data
+                         (each user sees only their own orders, say).
+  File uploads           Photos, documents and other files, stored with the app.
+  Emails                 Sign-in emails out of the box. With the person's own
+                         domain: any email (reminders, receipts, notifications)
+                         from addresses like support@theirdomain.com, and a
+                         log of what was delivered or bounced.
+  Phone notifications    Push notifications to phones and computers.
+  Works offline          Pages open without signal; changes made offline are
+                         sent when the connection comes back.
+  Own domain             Their domain (theirbusiness.com) with SSL included.
+  Server code            Logic that runs on the server: scheduled jobs,
+                         actions triggered when data changes, calls to other
+                         services (Stripe for payments, for example; payments
+                         are not built in, but can be added).
+  Safety net             Every deploy can be undone, and the data can be
+                         backed up to their computer at any time.
+  Secrets                API keys for other services, kept out of the code.
+  Sizes                  128 MB, 256 MB, 512 MB or 1 GB. The default is fine to
+                         start; it can be changed at any time from the
+                         dashboard.
+
+Good fits: booking and scheduling, member or client portals, sign-up lists
+and waitlists, small shops and catalogs, dashboards and tools for a business,
+chat and anything live, community and club sites, simple games.
+Not the right tool: video processing, training AI models, or very large data
+warehouses.
+
+Questions to ask (adapt them; skip what is already clear)
+----------------------------------------------------------
+  - What do you want to build, and who is it for?
+  - What should people be able to do in it? (book a time, post, order, ...)
+  - Do people need to sign in? Is there an admin (you) with extra powers?
+  - Should it send emails, like confirmations or reminders?
+  - Phone notifications? Uploading photos or files?
+  - Do you have a domain name you want to use, or one in mind?
+  - What do you want your project to be named?
+    (lowercase letters, numbers and dashes, 3 to 31 characters, starting
+    with a letter, e.g. "bloom-bookings". It becomes part of the web address.)
+
+Commands
+--------
+Setup (run in an empty folder; it signs them in first if needed: a browser
+window opens to confirm, or a short code to type on any device):
+  npx nukebase@latest start <project-name> --yes
+
+Then, inside the project folder:
+  npx nukebase push --yes          put the latest version live
+  npx nukebase logs                see what the app printed (errors too)
+  npx nukebase domain              connect their own domain, step by step
+  npx nukebase domain email        send the app's emails from that domain
+  npx nukebase rollback            undo the last push (their data is kept)
+  npx nukebase backup              copy the app's data to this computer
+  npx nukebase env push            send secrets from .env to the server
+  npx nukebase pause / restart     stop the app, or start it again
+  npx nukebase help                every command
+
+The dashboard at https://nukebase.com shows all their apps, usage and
+billing, and does most of the above with buttons too.
+`;
+
+function guideCommand() {
+  console.log(GUIDE.trimEnd() + '\n');
+}
+
+module.exports = { guideCommand, GUIDE };

package/lib/project-commands.js

@@ -945,11 +945,12 @@ async function domainCommand() {
   }
 }
 
-// nukebase domain email [--root | --sub] [--reply-to you@gmail.com] [--wait]
+// nukebase domain email [--root | --sub] [--wait]
 // nukebase domain email remove
 //
-// Send the app's emails (sign-in links today) from its custom domain:
-// login@theirapp.com, replies to --reply-to. The sending domain is either the
+// Send the app's emails from its custom domain. The setup is only the
+// domain and its DNS: the address, sender name and Reply-To are chosen per
+// email in code (sendEmail's `from` / `replyTo`). The sending domain is either the
 // custom domain itself (--root) or mail.<domain> (--sub; safest when the
 // domain already has email). Prints the two DNS records to add, then waits
 // for the mail provider to verify them (Enter to check now, Ctrl+C to leave
@@ -970,18 +971,22 @@ async function emailDomainCommand(action) {
   const current = check.current;
   const wantRoot = args.has('root') ? true : args.has('sub') ? false : null;
   const replyTo = args.get('reply-to');
+  const fromArg = args.get('from');
   const changing = wantRoot !== null && (!current || current.root !== wantRoot);
 
   let rec = current;
-  if (!current || changing || replyTo !== undefined) {
+  if (!current || changing || replyTo !== undefined || fromArg !== undefined) {
+    // --from / --reply-to are only carried by a region transfer, for setups
+    // made when those were part of it.
+    const from = fromArg;
     let root = wantRoot;
     if (root === null) root = current ? current.root : null;
     if (root === null) {
       const suggestRoot = check.suggested === 'root';
       console.log(`\n✉️  Send ${project}'s emails from ${domain}\n`);
-      console.log(`   1) login@${domain}`);
+      console.log(`   1) anything@${domain}`);
       console.log(`      ${check.hasEmail ? 'This domain already has email set up' + (check.spf ? ' (you will update its SPF record)' : '') + '.' : 'Recommended: this domain has no email set up yet.'}`);
-      console.log(`   2) login@${domain}, sent via mail.${domain}`);
+      console.log(`   2) anything@${domain}, sent via mail.${domain}`);
       console.log('      Safest if you already use email on this domain: its records are not touched.\n');
       if (process.stdin.isTTY && !AUTO_YES) {
         const a = (await askLine(`   Choose 1 or 2 [${suggestRoot ? 1 : 2}]: `)).trim();
@@ -990,11 +995,9 @@ async function emailDomainCommand(action) {
         root = suggestRoot;
       }
     }
-    let reply = replyTo;
-    if (reply === undefined && !current && process.stdin.isTTY && !AUTO_YES) {
-      reply = (await askLine('   Where should replies go? (e.g. you@gmail.com, Enter to skip): ')).trim();
-    }
+    const reply = replyTo;
     const body = { root };
+    if (typeof from === 'string' && from) body.from = from;
     if (typeof reply === 'string') body.replyTo = reply;
     rec = (await projectPost('/email-domain', body, { label: 'email' })).emailDomain;
   }
@@ -1010,8 +1013,9 @@ async function emailDomainCommand(action) {
 
 function printEmailRecords(rec) {
   const ok = rec.status === 'verified';
-  console.log(`\n   Sending domain: ${rec.name}   ${ok ? `✓ verified — emails go out as login@${rec.fromDomain || rec.name}` : '… waiting for DNS'}`);
-  if (rec.replyTo) console.log(`   Replies go to:  ${rec.replyTo}`);
+  const fromDomain = rec.fromDomain || (rec.root ? rec.name : rec.name.replace(/^mail\./, ''));
+  console.log(`\n   Sending domain: ${rec.name}   ${ok ? '✓ verified' : '… waiting for DNS'}`);
+  console.log(`   Sends from:     any address @${fromDomain} — your code picks it: sendEmail({ from: "Your Name <support>" })`);
   if (ok) { console.log(''); return; }
   console.log('\n   At your registrar, add these DNS records:\n');
   for (const r of rec.records || []) {
@@ -1035,7 +1039,7 @@ async function waitForEmailDomain() {
       const marks = (rec.records || []).map(x => `${x.valid ? '✓' : '…'} ${x.kind.toUpperCase()}`).join('   ');
       process.stdout.write(`\r   ${marks}      `);
       if (rec.status === 'verified') {
-        console.log(`\n\n✓ Verified. ${project}'s emails now go out as login@${rec.fromDomain || rec.name}.`);
+        console.log(`\n\n✓ Verified. ${project}'s emails now go out from @${rec.fromDomain || rec.name}.`);
         return;
       }
       await wait(20000);
@@ -1409,6 +1413,7 @@ async function regionTransfer() {
       const em = node.emailDomain;
       const emArgs = ['domain', 'email', em.root ? '--root' : '--sub', '--region', target, '--yes', ...asArgs];
       if (em.replyTo) emArgs.push('--reply-to', em.replyTo);
+      if (em.fromLocal) emArgs.push('--from', em.fromLocal);
       const e = spawnSync(process.execPath, [BIN, ...emArgs], { stdio: 'inherit', cwd: root });
       if (e.status !== 0) console.error(`   Email sending: finish later with: nukebase domain email --region ${target}${asArgs.length ? ' ' + asArgs.join(' ') : ''}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nukebase",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "NukeBase CLI: create, deploy and manage NukeBase projects",
   "bin": {
     "nukebase": "bin/nukebase.js"