@seip/blue-bird 1.1.2 → 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,9 +283,79 @@ 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.
 
+## 16. VPS Permissions & Security Hardening
+
+When deploying Blue Bird to Linux VPS servers using Docker Compose orchestration:
+
+### 1. FHS Deployment Standard
+- **Avoid deploying inside `/home/user/`**: User home directories often enforce restrictive traversal permissions (`700`/`750`) or risk cross-user privilege escalation in multi-tenant environments.
+- **Production Standard**: Always deploy in standard Filesystem Hierarchy Standard (FHS) locations:
+  - `/var/www/<project-name>` (Recommended for web applications)
+  - `/srv/<project-name>` (Alternative for site-specific service payloads)
+
+### 2. Permissions & Ownership Matrix
+
+| Path / Target | Recommended Mode | Ownership | Description & Rationale |
+|---|---|---|---|
+| `/var/www/<project-name>` | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Allows unprivileged Nginx container (`UID 101`) path traversal. |
+| `frontend/` (directories) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Directory traversal for static web workers. |
+| `frontend/` (files) | `644` (`-rw-r--r--`) | `$(whoami):$(whoami)` | Public read access for Nginx static serving. |
+| `node_modules/` | Dirs `755`, Files `644` | `$(whoami):$(whoami)` | Strict security. Avoid blanket `chmod -R 755`. |
+| `node_modules/.bin/` | `+x` (`chmod -R +x`) | `$(whoami):$(whoami)` | Preserves execution bits for CLI binaries and symlinks. |
+| `.env` | `600` (`-rw-------`) | `$(whoami):$(whoami)` | Strict isolation for database credentials and JWT keys. Never `777`. |
+| `database/` (SQLite) | Dir `755`, Files `644` | `$(whoami):$(whoami)` | Allows Node.js application process to read/write WAL journals. |
+
+### 3. Container-Level Hardening (Docker)
+- Mount static assets as **read-only (`:ro`)** in `docker-compose.yml` for the Nginx service (e.g. `./frontend:/app/frontend:ro` or `/var/www/<project-name>/frontend:/app/frontend:ro`).
+- Enforces the principle of least privilege: the web server worker cannot write or overwrite host assets even if compromised.
+
+### 4. Production Hardening Commands
+
+```bash
+# 1. Set project ownership to current deploy user
+sudo chown -R $(whoami):$(whoami) /var/www/<project-name>
+cd /var/www/<project-name>
+
+# 2. Ensure parent directory traversal permissions
+chmod 755 /var /var/www /var/www/<project-name>
+
+# 3. Set directory (755) and file (644) permissions for static frontend assets
+find frontend -type d -exec chmod 755 {} +
+find frontend -type f -exec chmod 644 {} +
+
+# 4. Secure node_modules while preserving executable bits in .bin
+find node_modules -type d -exec chmod 755 {} +
+find node_modules -type f -exec chmod 644 {} +
+chmod -R +x node_modules/.bin 2>/dev/null || true
+
+# 5. Restrict environment credentials strictly to owner
+chmod 600 .env
+
+# 6. Set database permissions (for SQLite)
+chmod 755 database 2>/dev/null || true
+chmod 644 database/*.db 2>/dev/null || true
+```
+
+### 5. Failure Modes & Remediation Playbook
+* **Error 13: Permission Denied on static assets (`stat() failed (13: Permission denied)`):**
+  - Cause: Nginx worker (`UID 101`) lacks path traversal (`+x`) or read (`+r`) permissions.
+  - Fix: `chmod 755 /var/www/<project-name> && find frontend -type d -exec chmod 755 {} + && find frontend -type f -exec chmod 644 {} +`
+* **`sh: 1: blue-bird: Permission denied` on CLI:**
+  - Cause: Blanket `chmod 644` stripped execution permissions from binary links in `node_modules/.bin/`.
+  - Fix: `chmod -R +x node_modules/.bin` (or `npm rebuild`)
+* **Docker Inode Desync (404 after `mv` / `rm -rf` directory):**
+  - Cause: Docker volume bind mounts bind to Linux filesystem inodes. Recreating the folder desynchronizes active mounts.
+  - Fix: `npx blue-bird docker stop && npx blue-bird docker start prod` (or `docker compose down && docker compose up -d`)
+* **Real-time Diagnostics:**
+  - Nginx log stream: `docker compose logs -f nginx`
+  - Container visibility check: `docker exec -it <container_name>-nginx su -s /bin/sh nginx -c "ls -la /app/frontend"`
+  - Host path traversal audit: `namei -l /var/www/<project-name>/frontend/css/bluebird.css`
+
+---
+
 _This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

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).
@@ -504,6 +558,135 @@ To deploy via Docker:
    npx blue-bird docker start prod
    ```
 
+---
+
+### 🛡️ Production VPS Security & Permissions Hardening Guide
+
+When deploying Blue Bird to a Linux VPS (Ubuntu, Debian, AlmaLinux, Rocky Linux), file permissions must strictly balance **least-privilege security** (preventing unauthorized read/write access to sensitive files) with **container accessibility** (allowing unprivileged container users like `nginx` to read static assets).
+
+> [!CAUTION]
+> **Never use `chmod -R 777` in production!** Giving full write permissions to all users creates severe security vulnerabilities, allowing compromised processes or unauthorized local users to modify application code, inject backdoors, or tamper with `.env` secrets.
+
+#### 1. Deployment Directory (Filesystem Hierarchy Standard)
+
+* ❌ **Avoid deploying inside `/home/user/`**: Deploying in home directories introduces security risks in multi-user environments and frequently causes `403 Forbidden` / `stat() failed (13: Permission denied)` errors due to restrictive default parent directory permissions (`700`/`750`). Recklessly loosening `/home/user/` exposes user SSH keys and profile data.
+* ✅ **Recommended Production Standard**: Deploy in dedicated Filesystem Hierarchy Standard (FHS) system directories:
+  * `/var/www/<project-name>` (Standard for web applications and static content)
+  * `/srv/<project-name>` (Alternative standard for site-specific payloads)
+
+#### 2. Recommended Permissions & Ownership Matrix
+
+| Target Directory / File | Mode | Ownership | Description & Security Rationale |
+|---|---|---|---|
+| **Project Root** (`/var/www/<project-name>`) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Allows unprivileged container processes (`nginx` UID 101) to traverse down to the project tree. |
+| **Static Frontend Dirs** (`frontend/`) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Grants traversal and read access for Nginx static serving. |
+| **Static Frontend Files** (`frontend/**/*`) | `644` (`-rw-r--r--`) | `$(whoami):$(whoami)` | Read-only access for web server worker processes. |
+| **Node Module Dirs** (`node_modules/`) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Standard directory access. Avoid blanket `chmod -R 755`. |
+| **Node Module Files** (`node_modules/**/*`) | `644` (`-rw-r--r--`) | `$(whoami):$(whoami)` | Standard read-only permissions for non-binary dependencies. |
+| **Executable Binaries** (`node_modules/.bin/`) | `+x` (`chmod -R +x`) | `$(whoami):$(whoami)` | Grants execution bit exclusively to CLI wrapper symlinks (`npx blue-bird`). |
+| **Environment File** (`.env`) | `600` (`-rw-------`) | `$(whoami):$(whoami)` | Restricts database passwords, JWT secrets, and API keys exclusively to the owning user. Never `644` or `777`. |
+| **Database Directory** (`database/` for SQLite) | `755` (dir) / `644` (file) | `$(whoami):$(whoami)` | Allows the Node.js application process inside the container to read and write WAL journal files. |
+
+#### 3. Container-Level Hardening (Docker)
+
+To enforce the principle of least privilege at the container boundary, explicitly mount static frontend assets in **read-only mode (`:ro`)** inside `docker-compose.yml` for the Nginx service:
+
+```yaml
+services:
+  nginx:
+    image: nginx:alpine
+    volumes:
+      - ./frontend:/app/frontend:ro
+      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
+```
+
+This guarantees that even in the event of an Nginx worker compromise, static web assets cannot be overwritten or modified from within the container.
+
+#### 4. Applying Secure Permissions on VPS
+
+Run the following chained commands inside your VPS project directory:
+
+```bash
+# 1. Set project ownership to current deploy user
+sudo chown -R $(whoami):$(whoami) /var/www/<project-name>
+cd /var/www/<project-name>
+
+# 2. Ensure parent directory traversal permissions
+chmod 755 /var /var/www /var/www/<project-name>
+
+# 3. Apply safe permissions for static frontend assets
+find frontend -type d -exec chmod 755 {} +
+find frontend -type f -exec chmod 644 {} +
+
+# 4. Secure node_modules while preserving executable bits in .bin
+find node_modules -type d -exec chmod 755 {} +
+find node_modules -type f -exec chmod 644 {} +
+chmod -R +x node_modules/.bin 2>/dev/null || true
+
+# 5. Lock down environment credentials
+chmod 600 .env
+
+# 6. Set database directory permissions (for SQLite)
+chmod 755 database 2>/dev/null || true
+chmod 644 database/*.db 2>/dev/null || true
+```
+
+---
+
+### 🔧 VPS Production Troubleshooting (Problems & Solutions)
+
+#### 1. Static Assets Return 404 / 403 (`Permission denied`)
+* **Symptom:** Opening pages returns 404 or missing CSS/JS (e.g. `/css/bluebird.css`, `/favicon.ico`), and `docker compose logs -f nginx` reports:
+  ```text
+  [crit] stat() "/app/frontend/css/bluebird.css" failed (13: Permission denied)
+  ```
+* **Cause:** The Nginx container runs as an unprivileged user (`nginx`, UID 101 on Alpine). If parent directories lack traversal (`+x`) permissions, or files lack read (`+r`) permissions, Nginx is blocked from reading `/app/frontend`.
+* **Solution:**
+  ```bash
+  # Grant traversal and read permissions:
+  chmod 755 /var/www/<project-name>
+  find frontend -type d -exec chmod 755 {} +
+  find frontend -type f -exec chmod 644 {} +
+  ```
+
+#### 2. `npx blue-bird` fails with `sh: 1: blue-bird: Permission denied`
+* **Symptom:** Running CLI commands like `npx blue-bird docker stop` or `npx blue-bird docker start prod` fails with permission errors.
+* **Cause:** An overly aggressive global `find . -type f -exec chmod 644` stripped execution permissions from binary wrappers and symlinks in `node_modules/.bin/`.
+* **Solution:**
+  ```bash
+  chmod -R +x node_modules/.bin
+  # Or rebuild native binaries:
+  npm rebuild
+  ```
+
+#### 3. 404 Not Found after Folder Renaming or Moving (Docker Inode Desync)
+* **Symptom:** Moving, replacing, or recreating the project folder (e.g. `mv project_old project` or `git clone` / `rm -rf`) while Docker containers were running leads to persistent 404 errors even though files exist on disk.
+* **Cause:** Linux file descriptors and Docker volume mounts bind to disk **inodes**. When a directory is deleted and recreated, Docker mounts remain attached to the stale/dead inode until the container stack is restarted.
+* **Solution:**
+  ```bash
+  docker compose down
+  docker compose up -d
+  # Or with Blue Bird CLI:
+  npx blue-bird docker stop
+  npx blue-bird docker start prod
+  ```
+
+#### 4. Real-time Container Diagnostics
+* **Inspect Nginx logs in real time:**
+  ```bash
+  docker compose logs -f nginx
+  ```
+* **Test file visibility directly as the Nginx container user:**
+  ```bash
+  docker exec -it <container_name>-nginx su -s /bin/sh nginx -c "ls -la /app/frontend/css/bluebird.css"
+  ```
+* **Inspect path traversal permissions on host:**
+  ```bash
+  namei -l /var/www/<project-name>/frontend/css/bluebird.css
+  ```
+
+---
+
 ### B. Standard Standalone PM2 / Node.js Runtime
 
 If you choose to run outside of Docker, you must set up the reverse proxy and databases manually. To deploy in a standard Linux environment using PM2:

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();
+}