@seip/blue-bird 1.1.3 → 1.1.4

package/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "Zignd.html-css-class-completion",
+    "pranaygp.vscode-css-peek"
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "html-css-class-completion.includeGlobPattern": "frontend/css/**/*.css",
+  "html-css-class-completion.enableEmmetSupport": true,
+  "css.validate": true,
+  "editor.quickSuggestions": {
+    "other": true,
+    "comments": false,
+    "strings": true
+  }
+}

package/AGENTS.md

@@ -206,14 +206,51 @@ npx blue-bird docker prune          # Cleans unused volumes, dangling images, an
 
 The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts. Alternatively, PM2 and other services can be run manually in standalone server environments by configuring `DATABASE_URL` inside `.env`.
 
-## 11. AI Development Guidelines
+## 11. Productivity & Developer Tooling CLI
+
+```bash
+# System Diagnostics & Smoke Test
+npx blue-bird doctor                # Audits .env, ports, permissions, and runs live HTTP smoke test
+
+# Route Scaffolding
+npx blue-bird make:route <name>     # Generates full CRUD route with Validation & Cache invalidation
+npx blue-bird make:route <name> -a  # Generates route with Auth.protect() middleware
+
+# Database Migrations & Seeds
+npx blue-bird make:migration <name> # Creates timestamped SQL migration in database/migrations/
+npx blue-bird migrate               # Executes pending migrations across SQLite, MySQL, or Postgres
+npx blue-bird migrate:status        # Displays applied and pending migration batches
+npx blue-bird make:seed <name>      # Creates SQL seed file in database/seeds/
+npx blue-bird seed                  # Executes seed files in database/seeds/
+
+# VPS Host Nginx & SSL Automation (Auto-resolves APP_URL & PORT from .env if omitted)
+npx blue-bird nginx:conf [domain] [port]
+```
+
+## 12. Background Jobs & Queue (Queue)
+
+Blue Bird includes a lightweight queue worker (`core/queue.js`) backed by Redis with an automatic in-memory fallback for local development or non-redis architectures.
+
+```javascript
+import Queue from "@seip/blue-bird/core/queue.js";
+
+// 1. Register job processor
+Queue.process("sendWelcomeEmail", async (payload) => {
+  console.log(`Sending email to ${payload.email}...`);
+});
+
+// 2. Dispatch job from route or service
+await Queue.dispatch("sendWelcomeEmail", { email: "user@example.com" });
+```
+
+## 13. AI Development Guidelines
 
 1. **Frontend**: Static files are stored in `frontend/` (e.g. `frontend/css`, `frontend/js`). HTML files will be served without the `.html` extension (e.g. `login.html` is accessible as `/login`).
 2. **JSON Responses**: API endpoints should return standardized responses formatted as `{ message: "..." }` or `{ data: ... }`.
 3. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
 4. **No inline comments**: Only use JSDoc for documentation.
 
-## 12. Database Module (database.js)
+## 14. Database Module (database.js)
 
 Blue Bird provides a unified wrapper class (`core/database.js`) supporting **SQLite (`better-sqlite3`)**, **MySQL (`mysql2/promise`)**, and **PostgreSQL (`pg`)**. It features connection pooling/reconnection, automatic retries on startup, query formatting, and built-in Redis query caching:
 
@@ -246,12 +283,12 @@ await connection.transaction(async (tx) => {
 });
 ```
 
-## 11. Nginx Static Asset Caching
+## 15. Nginx Static Asset Caching
 
 In production, Nginx is configured to explicitly cache static assets (`.js`, `.css`, `.jpg`, `.png`, etc.) in the user's browser with the `Cache-Control` header (valid for 1 month). 
 HTML and API endpoints (`/api/*`) are not cached by Nginx to ensure they serve dynamic and up-to-date content, relying instead on the Node.js application and Redis for data-layer caching.
 
-## 13. VPS Permissions & Security Hardening
+## 16. VPS Permissions & Security Hardening
 
 When deploying Blue Bird to Linux VPS servers using Docker Compose orchestration:
 

package/README.md

@@ -444,6 +444,60 @@ Nginx is configured to explicitly cache static assets (`.js`, `.css`, `.jpg`, `.
 
 ---
 
+## 🛠️ Developer Tooling & CLI Suite
+
+Blue Bird includes built-in developer productivity commands:
+
+```bash
+# System Diagnostics & Smoke Testing
+npx blue-bird doctor                 # Audits .env, ports, permissions, and runs live HTTP smoke test
+
+# Route Scaffolding
+npx blue-bird make:route <name>      # Generates full CRUD route with Validation & Cache invalidation
+npx blue-bird make:route <name> -a   # Generates route with Auth.protect() middleware
+
+# Database Migrations & Seeds
+npx blue-bird make:migration <name>  # Creates timestamped SQL migration in database/migrations/
+npx blue-bird migrate                # Executes pending migrations across SQLite, MySQL, or Postgres
+npx blue-bird migrate:status         # Displays applied and pending migration batches
+npx blue-bird make:seed <name>       # Creates SQL seed file in database/seeds/
+npx blue-bird seed                   # Executes seed files in database/seeds/
+
+# VPS Host Nginx & SSL Automation (Auto-resolves APP_URL & PORT from .env if omitted)
+npx blue-bird nginx:conf [domain] [port]
+```
+
+---
+
+## ✨ IDE Autocompletion & Developer Experience (CSS & JS)
+
+When initializing a project with `npx blue-bird`, the CLI generates `jsconfig.json`, `.vscode/settings.json`, `.vscode/extensions.json`, and `frontend/js/bluebird.d.ts` for zero-configuration IntelliSense:
+
+- **HTML & CSS Class IntelliSense:** Autocompletes all `bluebird.css` utilities and component classes in HTML attributes (`class="..."`). Recommended extensions:
+  - [HTML CSS Class Completion (Open VSX)](https://open-vsx.org/vscode/item?itemName=Zignd.html-css-class-completion) / [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Zignd.html-css-class-completion)
+  - [CSS Peek (Open VSX)](https://open-vsx.org/vscode/item?itemName=pranaygp.vscode-css-peek) / [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pranaygp.vscode-css-peek)
+- **JavaScript Tooltips & Autocomplete:** Built-in typed definitions (`bluebird.d.ts`) provide hover tooltips, options autocomplete, and inline code examples for `bluebird('toast', {...})`, `bluebird('snackbar', {...})`, `bluebird('drawer', {...})`, and other UI helpers.
+
+---
+
+## 📬 Background Jobs & Queue (Queue)
+
+Blue Bird includes a lightweight queue worker (`core/queue.js`) backed by Redis with an automatic in-memory fallback for local development or non-redis architectures:
+
+```javascript
+import Queue from "@seip/blue-bird/core/queue.js";
+
+// 1. Register job processor
+Queue.process("sendWelcomeEmail", async (payload) => {
+  console.log(`Sending email to ${payload.email}...`);
+});
+
+// 2. Dispatch job from route or service
+await Queue.dispatch("sendWelcomeEmail", { email: "user@example.com" });
+```
+
+---
+
 ## Docker CLI Workflow
 
 Blue Bird comes with a built-in Docker CLI wrapper that handles both local development database bootstrapping and full-stack VPS production deployments across MySQL, PostgreSQL, or no-database architectures.
@@ -457,7 +511,7 @@ npx blue-bird docker <command> [options]
 ### Supported Actions:
 
 - **`npx blue-bird docker dev`**: Boots the development database and Redis containers. Run `npm run dev` locally on your host machine.
-- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + Nginx + Database + Redis).
+- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + Nginx + Database + Redis) and runs the automatic health smoke test.
 - **`npx blue-bird docker start db`** (or `postgres` / `mysql`): Boots the configured database container only (great for local development outside Docker).
 - **`npx blue-bird docker start redis`**: Boots the Redis container only.
 - **`npx blue-bird docker start dbs`**: Boots both database containers (configured DB + Redis).

package/core/cli/docker.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
@@ -148,7 +150,14 @@ async function startCommand(service) {
     console.log(chalk.cyan("Starting production stack (DB + Redis + App + Nginx)..."));
     const code = await runCmd("docker", ["compose", "--profile", "prod", "up", "-d"]);
     if (code === 0) {
-      console.log(chalk.green("Production stack started."));
+      console.log(chalk.green("Production stack started successfully."));
+      console.log(chalk.cyan("\nRunning post-start health check (Doctor)...\n"));
+      try {
+        const { runDoctor } = await import("./doctor.js");
+        await runDoctor();
+      } catch (err) {
+        console.log(chalk.gray(`Health check skipped: ${err.message}`));
+      }
     } else {
       console.error(chalk.red("Error starting production stack."));
       process.exit(1);

package/core/cli/doctor.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import net from "node:net";
+import chalk from "chalk";
+
+/**
+ * Parses .env file into key-value map.
+ * @returns {Record<string, string>}
+ */
+function parseEnv() {
+  const envPath = path.resolve(process.cwd(), ".env");
+  const env = {};
+  if (fs.existsSync(envPath)) {
+    const lines = fs.readFileSync(envPath, "utf-8").split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#") && trimmed.includes("=")) {
+        const idx = trimmed.indexOf("=");
+        const key = trimmed.substring(0, idx).trim();
+        let val = trimmed.substring(idx + 1).trim();
+        if (
+          (val.startsWith('"') && val.endsWith('"')) ||
+          (val.startsWith("'") && val.endsWith("'"))
+        ) {
+          val = val.slice(1, -1);
+        }
+        env[key] = val;
+      }
+    }
+  }
+  return env;
+}
+
+/**
+ * Checks if a TCP port is currently open for binding on localhost.
+ * @param {number} port
+ * @returns {Promise<boolean>} Resolves to true if available, false if in use.
+ */
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+/**
+ * Finds a representative static file in frontend/ directory.
+ * @returns {string|null} Relative path like 'css/bluebird.css' or 'index.html'
+ */
+function findSampleStaticAsset() {
+  const frontendDir = path.resolve(process.cwd(), "frontend");
+  if (!fs.existsSync(frontendDir)) return null;
+
+  const candidates = [
+    "css/bluebird.css",
+    "css/style.css",
+    "js/bluebird.js",
+    "js/index.js",
+    "index.html",
+    "favicon.ico",
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(frontendDir, candidate))) {
+      return candidate;
+    }
+  }
+
+  try {
+    const files = fs.readdirSync(frontendDir, { recursive: true });
+    for (const f of files) {
+      const full = path.join(frontendDir, f);
+      if (fs.statSync(full).isFile()) {
+        return f.replace(/\\/g, "/");
+      }
+    }
+  } catch {
+    // fallback
+  }
+
+  return null;
+}
+
+/**
+ * Formats file permissions mode (e.g. 0600, 0755).
+ * @param {string} filePath
+ * @returns {string}
+ */
+function getOctalPermissions(filePath) {
+  try {
+    const stats = fs.statSync(filePath);
+    return "0" + (stats.mode & 0o777).toString(8);
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Runs the Blue Bird Doctor diagnostic suite.
+ */
+export async function runDoctor() {
+  console.log(chalk.bold.cyan("============================================================="));
+  console.log(chalk.bold.cyan(" Blue Bird System & Security Health Diagnostic (Doctor)"));
+  console.log(chalk.bold.cyan("============================================================="));
+  console.log("");
+
+  const env = parseEnv();
+  const envPath = path.resolve(process.cwd(), ".env");
+  const projectDir = process.cwd();
+  const isLinux = process.platform === "linux";
+  const port = parseInt(env.PORT || "3000", 10);
+  let appUrl = (env.APP_URL || `http://localhost:${port}`).replace(/\/$/, "");
+  if (
+    (appUrl === "http://localhost" || appUrl === "http://127.0.0.1") &&
+    port !== 80
+  ) {
+    appUrl = `http://localhost:${port}`;
+  }
+
+  let issuesFound = 0;
+  let warningsFound = 0;
+
+  // -------------------------------------------------------------
+  // 1. Environment & Secrets Check (.env)
+  // -------------------------------------------------------------
+  console.log(chalk.bold("[1/5] Environment & Configuration (.env):"));
+  if (!fs.existsSync(envPath)) {
+    console.log(chalk.red("  [FAIL] .env file is missing in project root."));
+    console.log(chalk.gray("         Run 'npx blue-bird' or copy .env_example to .env."));
+    issuesFound++;
+  } else {
+    console.log(chalk.green("  [PASS] .env file exists."));
+
+    if (isLinux) {
+      const envMode = getOctalPermissions(envPath);
+      if (envMode !== "0600" && envMode !== "0400") {
+        console.log(chalk.yellow(`  [WARN] .env permissions are '${envMode}'. Recommended mode is '0600' (chmod 600 .env).`));
+        warningsFound++;
+      } else {
+        console.log(chalk.green(`  [PASS] .env file permissions are strictly isolated (${envMode}).`));
+      }
+    }
+
+    if (!env.JWT_SECRET || env.JWT_SECRET.length < 16) {
+      console.log(chalk.yellow("  [WARN] JWT_SECRET is missing or shorter than 16 characters."));
+      warningsFound++;
+    } else {
+      console.log(chalk.green("  [PASS] JWT_SECRET is configured."));
+    }
+  }
+  console.log("");
+
+  // -------------------------------------------------------------
+  // 2. Filesystem Hierarchy & Permissions (FHS)
+  // -------------------------------------------------------------
+  console.log(chalk.bold("[2/5] Filesystem Hierarchy Standard & Static Asset Structure:"));
+  if (isLinux) {
+    if (projectDir.startsWith("/home/")) {
+      console.log(chalk.yellow("  [WARN] Project is deployed inside '/home/user/'."));
+      console.log(chalk.gray("         Recommended FHS production standard is '/var/www/<project>' or '/srv/<project>'"));
+      console.log(chalk.gray("         to prevent path traversal restrictions for unprivileged containers (nginx UID 101)."));
+      warningsFound++;
+    } else {
+      console.log(chalk.green("  [PASS] Project directory follows recommended FHS location."));
+    }
+  }
+
+  const frontendDir = path.resolve(process.cwd(), "frontend");
+  if (!fs.existsSync(frontendDir)) {
+    console.log(chalk.red("  [FAIL] 'frontend/' directory is missing."));
+    issuesFound++;
+  } else {
+    console.log(chalk.green("  [PASS] 'frontend/' directory exists."));
+    const sampleAsset = findSampleStaticAsset();
+    if (sampleAsset) {
+      console.log(chalk.green(`  [PASS] Detected sample static asset: 'frontend/${sampleAsset}'`));
+    } else {
+      console.log(chalk.yellow("  [WARN] No static files found inside 'frontend/'."));
+      warningsFound++;
+    }
+  }
+  console.log("");
+
+  // -------------------------------------------------------------
+  // 3. Port & Local Network Binding Check
+  // -------------------------------------------------------------
+  console.log(chalk.bold("[3/5] Port Availability & Binding:"));
+  const portFree = await isPortAvailable(port);
+  if (portFree) {
+    console.log(chalk.green(`  [INFO] Port ${port} is currently free and available for binding.`));
+  } else {
+    console.log(chalk.cyan(`  [INFO] Port ${port} is currently in use (application server or container is active).`));
+  }
+  console.log("");
+
+  // -------------------------------------------------------------
+  // 4. Live Smoke Test (API & Nginx Static Asset Delivery)
+  // -------------------------------------------------------------
+  console.log(chalk.bold("[4/5] Live HTTP Smoke Test (Health & Static Delivery):"));
+  const sampleAsset = findSampleStaticAsset();
+  const testUrls = [
+    { name: "API Health Endpoint", url: `${appUrl}/api/health`, isApi: true },
+  ];
+  if (sampleAsset) {
+    testUrls.push({
+      name: `Static Asset (/${sampleAsset})`,
+      url: `${appUrl}/${sampleAsset}`,
+      isApi: false,
+    });
+  }
+
+  let serverReachable = false;
+
+  for (const item of testUrls) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 3000);
+      const res = await fetch(item.url, { signal: controller.signal });
+      clearTimeout(timeoutId);
+
+      serverReachable = true;
+
+      if (res.status === 200) {
+        console.log(chalk.green(`  [PASS] ${item.name} returned HTTP 200 OK.`));
+      } else if (res.status === 403) {
+        console.log(chalk.red(`  [FAIL] ${item.name} returned HTTP 403 Forbidden.`));
+        console.log(chalk.yellow("         Cause: Unprivileged Nginx worker (UID 101) lacks path traversal (+x) or read (+r) permissions."));
+        console.log(chalk.yellow("         Remediation: Run the following commands on your host:"));
+        console.log(chalk.white(`           chmod 755 ${projectDir}`));
+        console.log(chalk.white("           find frontend -type d -exec chmod 755 {} +"));
+        console.log(chalk.white("           find frontend -type f -exec chmod 644 {} +"));
+        issuesFound++;
+      } else if (res.status === 404) {
+        console.log(chalk.red(`  [FAIL] ${item.name} returned HTTP 404 Not Found.`));
+        console.log(chalk.yellow("         Cause: File not found or Docker volume mount inode desynchronization."));
+        console.log(chalk.yellow("         Remediation: Recreate container volume mounts:"));
+        console.log(chalk.white("           npx blue-bird docker stop && npx blue-bird docker start prod"));
+        issuesFound++;
+      } else {
+        console.log(chalk.yellow(`  [WARN] ${item.name} returned HTTP ${res.status}.`));
+        warningsFound++;
+      }
+    } catch (err) {
+      if (err.name === "AbortError") {
+        console.log(chalk.yellow(`  [WARN] Request to ${item.name} (${item.url}) timed out after 3s.`));
+      } else {
+        console.log(chalk.gray(`  [INFO] Cannot connect to ${item.name} at ${item.url} (${err.code || err.message}).`));
+      }
+    }
+  }
+
+  if (!serverReachable) {
+    console.log(chalk.gray("  [INFO] Application server is not running locally. Start it with:"));
+    console.log(chalk.gray("         Development: npm run dev"));
+    console.log(chalk.gray("         Production:  npx blue-bird docker start prod"));
+  }
+  console.log("");
+
+  // -------------------------------------------------------------
+  // 5. Database & Cache Driver Status
+  // -------------------------------------------------------------
+  console.log(chalk.bold("[5/5] Database & Cache Architecture:"));
+  const dbType = (env.DB_TYPE || "sqlite").toLowerCase();
+  console.log(chalk.green(`  [INFO] Database Type: ${dbType.toUpperCase()}`));
+  const cacheMode = (env.CACHE_MODE || "memory").toLowerCase();
+  console.log(chalk.green(`  [INFO] Cache Mode:    ${cacheMode.toUpperCase()}`));
+  console.log("");
+
+  // -------------------------------------------------------------
+  // Summary
+  // -------------------------------------------------------------
+  console.log(chalk.bold.cyan("============================================================="));
+  if (issuesFound === 0 && warningsFound === 0) {
+    console.log(chalk.bold.green(" Diagnostic Summary: All checks passed with zero issues!"));
+  } else if (issuesFound === 0) {
+    console.log(chalk.bold.yellow(` Diagnostic Summary: System is operational with ${warningsFound} warning(s).`));
+  } else {
+    console.log(chalk.bold.red(` Diagnostic Summary: Found ${issuesFound} error(s) and ${warningsFound} warning(s).`));
+  }
+  console.log(chalk.bold.cyan("============================================================="));
+}
+
+// If executed directly from CLI
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("doctor.js") || process.argv[2] === "doctor") {
+  runDoctor();
+}

package/core/cli/init.js

@@ -118,6 +118,8 @@ class ProjectInit {
       "docker",
       ".env_example",
       "AGENTS.md",
+      "jsconfig.json",
+      ".vscode",
     ];
 
     try {
@@ -333,7 +335,10 @@ class ProjectInit {
         dev: "node --watch --env-file=.env backend/index.js",
         start: "node --env-file=.env backend/index.js",
         init: "blue-bird",
+        doctor: "blue-bird doctor",
         route: "blue-bird route",
+        migrate: "blue-bird migrate",
+        seed: "blue-bird seed",
         "swagger-install": "blue-bird swagger-install",
         docker: "blue-bird docker",
       };
@@ -452,9 +457,33 @@ const initializer = new ProjectInit();
 const args = process.argv.slice(2);
 const command = args[0];
 
-if (command === "route") import("./route.js");
-else if (command === "swagger-install") import("./swagger.js");
-else if (command === "docker") import("./docker.js");
-else if (command === "add") addCommand(args[1]);
-else initializer.run();
+if (command === "route" || command === "make:route") {
+  import("./route.js");
+} else if (command === "doctor") {
+  import("./doctor.js");
+} else if (
+  command === "nginx:conf" ||
+  command === "nginx:host" ||
+  command === "nginx"
+) {
+  import("./nginx.js");
+} else if (
+  command === "migrate" ||
+  command === "migrate:status" ||
+  command === "migrate:rollback" ||
+  command === "seed" ||
+  command === "make:migration" ||
+  command === "make:seed"
+) {
+  import("./migrate.js");
+} else if (command === "swagger-install") {
+  import("./swagger.js");
+} else if (command === "docker") {
+  import("./docker.js");
+} else if (command === "add") {
+  addCommand(args[1]);
+} else {
+  initializer.run();
+}
+