business-stack 0.1.0 → 0.1.3

package/README.md

@@ -0,0 +1,118 @@
+# business-stack
+
+Single npm package bundling a **Next.js** app, **Hono** gateway (Better Auth, integrations, authenticated proxy to FastAPI), and **FastAPI** backend. Turborepo runs web, gateway, and backend together.
+
+## Prerequisites
+
+Install these on your machine and ensure they are on your `PATH`:
+
+| Tool | Purpose |
+|------|---------|
+| [Node.js](https://nodejs.org/) 20+ | Runs the `business-stack` CLI (`setup`, `start`, `doctor`) |
+| [Bun](https://bun.sh) | Installs JS workspaces and runs the gateway |
+| [uv](https://docs.astral.sh/uv/) | Installs and runs the Python backend |
+| Python **3.12** | Required by the backend (managed via `uv`) |
+
+Check your environment:
+
+```bash
+npx business-stack doctor
+```
+
+### Using `npx` (no install, or one-off runs)
+
+`npx` runs the same `business-stack` binary as a global or local install. Use a version tag so npm does not cache an old release:
+
+```bash
+npx --yes business-stack@latest doctor
+npx --yes business-stack@latest setup --yes
+npx --yes business-stack@latest start
+```
+
+On **Windows Command Prompt**, use the same commands; if `npx` is slow the first time, it is downloading the package.
+
+## Installation (recommended: project-level)
+
+**Prefer a local (project) install** so the stack, generated `.env` files, and SQLite database live under your project’s `node_modules/business-stack/`, match npm’s default `npm i business-stack`, and avoid permission or PATH issues from global installs.
+
+### 1. Create or use a project directory
+
+```bash
+mkdir my-stack && cd my-stack
+npm init -y
+```
+
+### 2. Install the package locally
+
+```bash
+npm install business-stack
+```
+
+This installs the full app tree at `node_modules/business-stack/` (Next app, gateway, backend sources).
+
+### 3. Run the CLI via `npx` (or package scripts)
+
+From the **same directory** as your `package.json` (so npm resolves the local install):
+
+```bash
+npx business-stack doctor
+npx business-stack setup --yes
+npx business-stack start
+```
+
+- **`setup`** generates secrets, stores them in SQLite (`node_modules/business-stack/gateway/auth.sqlite`, table `stack_secrets`), and writes `gateway/.env`, `frontend/web/.env.local`, and `backend/.env` under that package path. You do not need to create `.env` files by hand.
+- **`start`** runs `bun install`, `uv sync`, production build, Alembic migrations, then starts Next (`next start`), the gateway, and uvicorn. First run can take several minutes.
+
+Optional flags for `start`: `--skip-install`, `--skip-build`, `--skip-migrate`.
+
+Development servers (hot reload) instead of production:
+
+```bash
+npx business-stack dev
+```
+
+### 4. Optional: npm scripts in your `package.json`
+
+```json
+{
+  "scripts": {
+    "stack:doctor": "business-stack doctor",
+    "stack:setup": "business-stack setup --yes",
+    "stack:start": "business-stack start",
+    "stack:dev": "business-stack dev"
+  }
+}
+```
+
+After a local install, npm adds `node_modules/.bin/business-stack`, so these scripts work without `npx`.
+
+## Global install (optional)
+
+If you want the `business-stack` command on your PATH for every shell:
+
+```bash
+npm install -g business-stack
+business-stack doctor
+business-stack setup --yes
+business-stack start
+```
+
+Files and secrets are then under your global npm prefix (for example `%AppData%\npm\node_modules\business-stack` on Windows). Use global install only if you are comfortable with that layout and upgrades overwriting the same tree.
+
+## Default URLs
+
+| Service | URL |
+|---------|-----|
+| Web (Next) | `http://127.0.0.1:3000` |
+| Gateway | `http://127.0.0.1:3001` |
+| FastAPI | `http://127.0.0.1:8000` |
+
+`setup` uses these by default; interactive `business-stack setup` (without `--yes`) prompts for URLs.
+
+## Security note
+
+Secrets in `stack_secrets` and generated `.env` files are **plaintext at rest**, like a normal `.env`. Protect the install directory and do not commit `gateway/.env`, `frontend/web/.env.local`, `backend/.env`, or `*.sqlite`.
+
+## License
+
+See `package.json` (`license` field).

package/bin/business-stack.cjs

@@ -111,10 +111,29 @@ function writeEnvFile(filePath, content) {
   fs.writeFileSync(filePath, `${content.trim()}\n`, "utf8");
 }
 
+/** Resolve `bun` / `uv` to a concrete path on Windows (`where`); avoids spawn ENOENT for .cmd shims. */
+function resolveExecutable(cmd) {
+  if (process.platform !== "win32") {
+    return cmd;
+  }
+  const r = spawnSync("where.exe", [cmd], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (r.status !== 0 || !r.stdout) {
+    return cmd;
+  }
+  const first = r.stdout
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .find(Boolean);
+  return first || cmd;
+}
+
 function cmdExists(cmd) {
   const isWin = process.platform === "win32";
   const which = isWin ? "where" : "which";
-  const r = spawnSync(which, [cmd], { encoding: "utf8" });
+  const r = spawnSync(which, [cmd], { encoding: "utf8", windowsHide: isWin });
   return r.status === 0;
 }
 
@@ -274,19 +293,62 @@ function envFileLooksConfigured(stackRoot) {
   return hasExistingSecrets(stackRoot);
 }
 
-function runCmd(cmd, args, cwd, extraEnv) {
-  const r = spawnSync(cmd, args, {
+function runCmd(label, cmd, args, cwd, extraEnv) {
+  console.error(`business-stack: ${label}…`);
+  const exe = resolveExecutable(cmd);
+  const r = spawnSync(exe, args, {
     cwd,
     stdio: "inherit",
     env: { ...process.env, ...extraEnv },
     shell: false,
+    windowsHide: process.platform === "win32",
   });
+  if (r.error) {
+    console.error(`business-stack: ${label} failed:`, r.error.message);
+    console.error(`  Command: ${exe} ${args.join(" ")}`);
+    console.error(`  cwd: ${cwd}`);
+    process.exit(1);
+  }
+  if (r.signal) {
+    console.error(`business-stack: ${label} killed (${r.signal})`);
+    process.exit(1);
+  }
   if (r.status !== 0) {
     process.exit(r.status ?? 1);
   }
 }
 
-function runStart(opts) {
+/**
+ * Wait for turbo + servers. Async so Commander keeps the Node event loop alive on Windows
+ * until the child exits (avoids exiting immediately with no output).
+ */
+function waitForChild(child, label) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      resolve(code ?? 0);
+    };
+
+    child.on("error", (err) => {
+      console.error(`business-stack: ${label} — failed to spawn process:`, err.message);
+      console.error("  Is Bun installed and on PATH? Run: business-stack doctor");
+      finish(1);
+    });
+
+    child.on("exit", (code, sig) => {
+      if (sig) {
+        console.error(`business-stack: ${label} — child exited with signal ${sig}`);
+        finish(1);
+        return;
+      }
+      finish(code ?? 0);
+    });
+  });
+}
+
+async function runStart(opts) {
   const stackRoot = getStackRoot();
   if (!envFileLooksConfigured(stackRoot)) {
     console.error(
@@ -295,6 +357,9 @@ function runStart(opts) {
     process.exit(1);
   }
 
+  console.error("business-stack: starting (install → sync → build → migrate → servers)…");
+  console.error(`business-stack: stack root ${stackRoot}`);
+
   const fromDb = readStackSecretsEnv(stackRoot);
   const childEnv = { ...process.env };
   for (const [k, v] of Object.entries(fromDb)) {
@@ -304,43 +369,53 @@ function runStart(opts) {
   }
 
   if (!opts.skipInstall) {
-    runCmd("bun", ["install"], stackRoot, childEnv);
+    runCmd("bun install (workspaces)", "bun", ["install"], stackRoot, childEnv);
   }
-  runCmd("uv", ["sync"], path.join(stackRoot, "backend"), childEnv);
+  runCmd("uv sync (backend)", "uv", ["sync"], path.join(stackRoot, "backend"), childEnv);
   if (!opts.skipBuild) {
-    runCmd("bun", ["run", "build"], stackRoot, childEnv);
+    runCmd("bun run build", "bun", ["run", "build"], stackRoot, childEnv);
   }
   if (!opts.skipMigrate) {
-    runCmd("uv", ["run", "alembic", "upgrade", "head"], path.join(stackRoot, "backend"), childEnv);
+    runCmd(
+      "alembic upgrade head",
+      "uv",
+      ["run", "alembic", "upgrade", "head"],
+      path.join(stackRoot, "backend"),
+      childEnv,
+    );
   }
 
-  const child = spawn("bun", ["run", "start"], {
+  console.error("business-stack: launching production servers (turbo start)…");
+
+  const bunExe = resolveExecutable("bun");
+  const child = spawn(bunExe, ["run", "start"], {
     cwd: stackRoot,
     stdio: "inherit",
     env: childEnv,
     shell: false,
+    windowsHide: process.platform === "win32",
   });
 
-  function shutdown(signal) {
+  const shutdown = () => {
     try {
-      if (process.platform === "win32") {
+      if (process.platform === "win32" && child.pid) {
         spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], {
           stdio: "ignore",
+          windowsHide: true,
         });
-      } else {
-        child.kill(signal);
+      } else if (child.pid) {
+        child.kill("SIGINT");
       }
     } catch {
       /* ignore */
     }
-  }
+  };
 
-  process.on("SIGINT", () => shutdown("SIGINT"));
-  process.on("SIGTERM", () => shutdown("SIGTERM"));
-  child.on("exit", (code, sig) => {
-    if (sig) process.exit(1);
-    process.exit(code ?? 0);
-  });
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+
+  const code = await waitForChild(child, "turbo start");
+  process.exit(code);
 }
 
 function runDev() {
@@ -352,13 +427,13 @@ function runDev() {
       childEnv[k] = String(v);
     }
   }
-  runCmd("bun", ["run", "dev"], stackRoot, childEnv);
+  runCmd("bun run dev", "bun", ["run", "dev"], stackRoot, childEnv);
 }
 
 program
   .name("business-stack")
   .description("Run the business-stack monorepo (Next + Hono gateway + FastAPI)")
-  .version("0.1.0");
+  .version("0.1.3");
 
 program
   .command("doctor")
@@ -385,9 +460,9 @@ program
   .option("--skip-install", "Skip bun install")
   .option("--skip-build", "Skip turbo build")
   .option("--skip-migrate", "Skip alembic upgrade")
-  .action((o) => {
+  .action(async (o) => {
     try {
-      runStart(o);
+      await runStart(o);
     } catch (e) {
       console.error(e instanceof Error ? e.message : e);
       process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "business-stack",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Next.js + Hono gateway + FastAPI monorepo",
   "license": "UNLICENSED",
   "packageManager": "bun@1.3.1",
@@ -15,6 +15,7 @@
     "business-stack": "bin/business-stack.cjs"
   },
   "files": [
+    "README.md",
     "bin",
     "turbo.json",
     ".python-version",