@bhooai/nexus-cli 0.1.0 → 0.1.4

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@bhooai/nexus-cli",
-  "version": "0.1.0",
-  "publishConfig": { "access": "public" },
+  "version": "0.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/commands/dev.ts

@@ -1,12 +1,14 @@
 import { ServiceSpec, Supervisor } from '../supervisor.js';
 import { loadConfigAuto } from '../../../nexus-core/src/index.js';
 import { configChangedSinceSync, syncConfig } from '../config-sync.js';
+import { isPortFree } from '../util.js';
 
 const COLORS = {
   backend: '\x1b[32m',
   frontend: '\x1b[36m',
   'ai-server': '\x1b[33m',
   admin: '\x1b[35m',
+  'node-agent': '\x1b[34m',
 };
 
 const BOLD = '\x1b[1m';
@@ -20,9 +22,20 @@ export async function dev(args: string[] = []): Promise<number> {  const cfg = a
   const cpIdx = args.indexOf('--control-port');
   const controlPort = cpIdx >= 0 && Number.isFinite(Number(args[cpIdx + 1])) ? Number(args[cpIdx + 1]) : 7474;
 
-  // If nexus.config.* changed since the last sync, rewrite every derived
-  // artifact (Dockerfile, docker.*, serve-all.mjs, admin pkg, project DB)
-  // before booting so the whole stack runs on the new values.
+  // Runtime port auto-allocation: a second project (master + slave) can run on
+  // the same machine side-by-side. Any configured port that is already taken is
+  // bumped to the next free one and threaded through NEXUS_* env, which both
+  // the backend loader and the Vite dev servers honour (config < env).
+  const serverPort = await nextFreePort(cfg.server.host, cfg.server.port);
+  const frontendPort = await nextFreePort('127.0.0.1', cfg.frontend.port);
+  const adminPort = await nextFreePort('127.0.0.1', cfg.admin.port);
+  const aiServerPort = await nextFreePort('127.0.0.1', Number(aiPort(cfg.ai.serverUrl)));
+  const lbPort = await nextFreePort('127.0.0.1', cfg.cluster.lbPort);
+  const agentPort = await nextFreePort('127.0.0.1', cfg.cluster.nodeAgentPort);
+
+  // If the config changed since the last sync, rewrite every derived artifact
+  // (Dockerfile, docker.*, serve-all.mjs, admin pkg, project DB) before booting
+  // so the whole stack runs on the new values.
   if (!args.includes('--no-sync')) {
     if (configChangedSinceSync(process.cwd(), cfg)) {
       process.stdout.write(`\n  ${BOLD}Config changed - re-syncing derived artifacts...${RESET}\n`);
@@ -34,19 +47,33 @@ export async function dev(args: string[] = []): Promise<number> {  const cfg = a
     }
   }
 
+  // Env override for a port that was bumped away from the configured value.
+  // Only set when different, so the configured port is used verbatim otherwise.
+  const portEnv = (actual: number, configured: number, key: string): Record<string, string> =>
+    actual !== configured ? { [key]: String(actual) } : {};
+
   const all: ServiceSpec[] = [
     {
       name: 'backend',
       command: ['tsx', 'watch', 'apps/backend/src/main.ts'],
       cwd: '',
       color: COLORS.backend,
+      env: {
+        ...portEnv(serverPort, cfg.server.port, 'NEXUS_SERVER_PORT'),
+        ...portEnv(lbPort, cfg.cluster.lbPort, 'NEXUS_CLUSTER_LBPORT'),
+        ...portEnv(agentPort, cfg.cluster.nodeAgentPort, 'NEXUS_CLUSTER_NODEAGENTPORT'),
+      },
     },
     {
       name: 'frontend',
-      command: ['vite', '--port', String(cfg.frontend.port), '--host', cfg.frontend.host],
+      command: ['vite', '--port', String(frontendPort), '--host', cfg.frontend.host],
       cwd: 'apps/frontend',
       color: COLORS.frontend,
       optional: true,
+      env: {
+        ...portEnv(serverPort, cfg.server.port, 'NEXUS_SERVER_PORT'),
+        ...portEnv(frontendPort, cfg.frontend.port, 'NEXUS_FRONTEND_PORT'),
+      },
     },
     {
       name: 'ai-server',
@@ -54,17 +81,39 @@ export async function dev(args: string[] = []): Promise<number> {  const cfg = a
       cwd: 'apps/ai-server',
       color: COLORS['ai-server'],
       optional: true,
-      env: { AI_PORT: aiPort(cfg.ai.serverUrl) },
+      env: { AI_PORT: String(aiServerPort) },
     },
     {
       name: 'admin',
-      command: ['vite', '--port', String(cfg.admin.port), '--host', cfg.admin.host],
+      command: ['vite', '--port', String(adminPort), '--host', cfg.admin.host],
       cwd: 'apps/admin',
       color: COLORS.admin,
       optional: true,
+      env: {
+        ...portEnv(serverPort, cfg.server.port, 'NEXUS_SERVER_PORT'),
+        ...portEnv(adminPort, cfg.admin.port, 'NEXUS_ADMIN_PORT'),
+      },
     },
   ];
 
+  // Slave/node mode: auto-start a node agent (agent-only — it advertises the dev
+  // supervisor's backend as its role service instead of spawning a second one).
+  // The master can then link this node via its agent URL right after `npm run dev`.
+  // Invoked through `node node_modules/bhooai-nexus/bin/nexus.js` so it resolves
+  // even when the `nexus` bin shim isn't linked into the project's .bin.
+  if (cfg.cluster.role) {
+    all.push({
+      name: 'node-agent',
+      command: ['node', 'node_modules/bhooai-nexus/bin/nexus.js', 'node', 'serve', `--role=${cfg.cluster.role}`, `--port=${agentPort}`, '--no-service'],
+      cwd: '',
+      color: COLORS['node-agent'],
+      env: {
+        ...portEnv(serverPort, cfg.server.port, 'NEXUS_SERVER_PORT'),
+        ...portEnv(agentPort, cfg.cluster.nodeAgentPort, 'NEXUS_CLUSTER_NODEAGENTPORT'),
+      },
+    });
+  }
+
   // Drop services the config disables (unless an explicit --only pins them).
   const enabled = all.filter((s) => {
     if (only) return only.includes(s.name);
@@ -85,19 +134,23 @@ export async function dev(args: string[] = []): Promise<number> {  const cfg = a
     switch (s.name) {
       case 'backend':
         host = cfg.server.host;
-        port = String(cfg.server.port);
+        port = String(serverPort);
         break;
       case 'frontend':
         host = cfg.frontend.host;
-        port = String(cfg.frontend.port);
+        port = String(frontendPort);
         break;
       case 'admin':
         host = cfg.admin.host;
-        port = String(cfg.admin.port);
+        port = String(adminPort);
         break;
       case 'ai-server':
         host = '0.0.0.0';
-        port = aiPort(cfg.ai.serverUrl);
+        port = String(aiServerPort);
+        break;
+      case 'node-agent':
+        host = cfg.cluster.nodeAgentHost;
+        port = String(agentPort);
         break;
     }
     const padName = s.name.padEnd(15);
@@ -112,9 +165,13 @@ export async function dev(args: string[] = []): Promise<number> {  const cfg = a
   // After services spawn, print quick-start URLs.
   setTimeout(() => {
     process.stdout.write(`\n  ${BOLD}Visit:${RESET}\n`);
-    process.stdout.write(`  http://localhost:${cfg.frontend.port}  (frontend)\n`);
-    process.stdout.write(`  http://localhost:${cfg.admin.port}  (admin)\n`);
-    process.stdout.write(`  http://localhost:${cfg.server.port}/health  (backend)\n`);
+    process.stdout.write(`  http://localhost:${frontendPort}  (frontend)\n`);
+    process.stdout.write(`  http://localhost:${adminPort}  (admin)\n`);
+    process.stdout.write(`  http://localhost:${serverPort}/health  (backend)\n`);
+    if (cfg.cluster.role) {
+      process.stdout.write(`\n  ${BOLD}Node agent${RESET} — link this from the master:\n`);
+      process.stdout.write(`  http://${cfg.cluster.nodeAgentHost}:${agentPort}  (agent)  ·  role: ${cfg.cluster.role}\n`);
+    }
     process.stdout.write(`\n`);
   }, 2000);
 
@@ -122,6 +179,16 @@ export async function dev(args: string[] = []): Promise<number> {  const cfg = a
   return 0;
 }
 
+/** First free port at or above `port` on `host` (fails fast, caps at +100). */
+async function nextFreePort(host: string, port: number): Promise<number> {
+  const base = Number(port);
+  if (await isPortFree(host, base)) return base;
+  for (let i = 1; i <= 100; i++) {
+    if (await isPortFree(host, base + i)) return base + i;
+  }
+  return base;
+}
+
 /** Port parsed from the configured AI server URL (defaults 8000). */
 function aiPort(serverUrl: string): string {
   try {

package/src/commands/init.ts

@@ -234,7 +234,7 @@ export async function init(opts: InitOptions = {}, args: string[] = []): Promise
       ai: { serverUrl: 'http://localhost:8000' },
       server: { host: '0.0.0.0', port: 4000 },
       frontend: { port: 3000 },
-      admin: { port: 3001 },
+      admin: { port: 3300 },
     });
     const mongoDown = services.find((s) => s.name === 'mongodb' && !s.ok);
     const redisDown = services.find((s) => s.name === 'redis' && !s.ok);
@@ -261,7 +261,7 @@ export async function init(opts: InitOptions = {}, args: string[] = []): Promise
               ai: { serverUrl: 'http://localhost:8000' },
               server: { host: '0.0.0.0', port: 4000 },
               frontend: { port: 3000 },
-              admin: { port: 3001 },
+              admin: { port: 3300 },
             });
             const md = services.find((s) => s.name === 'mongodb' && !s.ok);
             const rd = services.find((s) => s.name === 'redis' && !s.ok);
@@ -430,7 +430,7 @@ export async function init(opts: InitOptions = {}, args: string[] = []): Promise
   // (detected from a sibling root, prompted, or passed via --cluster-token)
   // so the central can authenticate this node's agent.
   const token = choices.clusterToken || randomBytes(16).toString('hex');
-  applyClusterConfig(target, choices.kind, token);
+  applyClusterConfig(target, choices.kind, choices.role, token, choices.agentPort);
   patchConfig(target, {
     mongoUri: choices.mongoUri,
     redisUrl: choices.redisUrl,
@@ -660,7 +660,7 @@ async function registerProject(target: string, choices: WizardChoices, clusterTo
       payments: { currency: 'INR', providersConfigured: [] },
       cluster: { enabled: choices.kind === 'root', token: clusterToken },
       paths: { uploads: 'uploads', plugins: 'plugins', certs: 'certs', logs: 'logs' },
-      ports: { backend: 4000, frontend: 3000, admin: 3001, ai: 8000 },
+      ports: { backend: 4000, frontend: 3000, admin: 3300, ai: 8000 },
     };
     const record: ProjectInfo = {
       ...base,
@@ -706,8 +706,9 @@ async function verifyProject(target: string): Promise<void> {
 /** Write the `cluster` section into the scaffolded nexus.config.ts.
  *  The template ships with `cluster: { enabled: false, token: '' }`, so this
  *  always patches the existing line - setting `enabled` (true for root, false
- *  for node) and stamping a fresh pairing `token`. Idempotent on re-runs. */
-function applyClusterConfig(target: string, kind: 'root' | 'node', token: string): void {
+ *  for node), stamping a fresh pairing `token`, and (for nodes) the `role` so
+ *  `nexus dev` knows to auto-start a node agent. Idempotent on re-runs. */
+function applyClusterConfig(target: string, kind: 'root' | 'node', role: string, token: string, agentPort: number): void {
   const configPath = join(target, 'nexus.config.ts');
   if (!existsSync(configPath)) return;
   let src = readFileSync(configPath, 'utf8');
@@ -716,7 +717,8 @@ function applyClusterConfig(target: string, kind: 'root' | 'node', token: string
 
   if (!/cluster\s*:/.test(src)) {
     // No cluster block at all - insert one after the opening brace.
-    const clusterLine = `  cluster: { enabled: ${enabled}, token: '${desiredToken}' },`;
+    const roleLine = kind === 'node' ? `, role: '${role}'` : '';
+    const clusterLine = `  cluster: { enabled: ${enabled}, token: '${desiredToken}'${roleLine}, nodeAgentPort: ${agentPort} },`;
     writeFileSync(configPath, src.replace(
       /(const config: Partial<NexusConfig> = \{\r?\n)/,
       `$1${clusterLine}\n`,
@@ -725,7 +727,7 @@ function applyClusterConfig(target: string, kind: 'root' | 'node', token: string
     return;
   }
 
-  // Patch the existing cluster line's `enabled` + `token` in place.
+  // Patch the existing cluster line's `enabled` + `token` (+ `role`/`nodeAgentPort`) in place.
   let changed = false;
 
   // enabled: <bool>
@@ -745,9 +747,44 @@ function applyClusterConfig(target: string, kind: 'root' | 'node', token: string
     changed = true;
   }
 
+  // role: '<role>' — set for nodes, remove for root. Only patch if present and different.
+  if (kind === 'node') {
+    const roleRe = /(cluster\s*:\s*\{[^}]*\brole\s*:\s*')([^']*)(')/;
+    const roleMatch = roleRe.exec(src);
+    if (roleMatch) {
+      if (roleMatch[2] !== role) {
+        src = src.replace(roleRe, `$1${role}$3`);
+        changed = true;
+      }
+    } else {
+      // No role key yet — insert it right after `enabled: <bool>,`.
+      src = src.replace(
+        /(cluster\s*:\s*\{[^}]*\benabled\s*:\s*(?:false|true)\s*,)/,
+        `$1 role: '${role}',`,
+      );
+      changed = true;
+    }
+  }
+
+  // nodeAgentPort: <number> — persist the port chosen at init so the admin
+  // node-agent panel + `nexus dev` reflect it instead of the 7575 default.
+  const portRe = /(cluster\s*:\s*\{[^}]*\bnodeAgentPort\s*:\s*)(\d+)/;
+  const portMatch = portRe.exec(src);
+  if (portMatch && portMatch[2] !== String(agentPort)) {
+    src = src.replace(portRe, `$1${agentPort}`);
+    changed = true;
+  } else if (!portMatch) {
+    // No nodeAgentPort key yet — insert it after `token: '...',`.
+    src = src.replace(
+      /(cluster\s*:\s*\{[^}]*\btoken\s*:\s*'[^']*'\s*,)/,
+      `$1 nodeAgentPort: ${agentPort},`,
+    );
+    changed = true;
+  }
+
   if (changed) {
     writeFileSync(configPath, src);
-    console.log(`  ${GREEN}update${RESET} nexus.config.ts (cluster: ${kind}, enabled: ${enabled})`);
+    console.log(`  ${GREEN}update${RESET} nexus.config.ts (cluster: ${kind}, enabled: ${enabled}${kind === 'node' ? `, role: ${role}` : ''}, nodeAgentPort: ${agentPort})`);
   } else {
     console.log(`  ${DIM}keep${RESET}  nexus.config.ts (cluster: ${kind} already set)`);
   }
@@ -812,7 +849,7 @@ function wireFrameworkDependency(target: string): void {
 
 /** Auto-allocate free ports for a freshly scaffolded project and patch its
  *  nexus.config.ts. All projects ship with the same defaults (server 4000,
- *  frontend 3000, admin 3001, AI 8000, cluster LB 8080, agent 7575), so a
+ *  frontend 3000, admin 3300, AI 8000, cluster LB 8080, agent 7575), so a
  *  second project running on the same machine collides - its admin Vite fails
  *  to bind and the browser hits another project's admin (wrong project name). */
 async function allocateProjectPorts(target: string): Promise<void> {
@@ -823,7 +860,7 @@ async function allocateProjectPorts(target: string): Promise<void> {
   const defaults: Array<{ key: string; port: number }> = [
     { key: 'server', port: 4000 },
     { key: 'frontend', port: 3000 },
-    { key: 'admin', port: 3001 },
+    { key: 'admin', port: 3300 },
     { key: 'ai', port: 8000 },
     { key: 'lb', port: 8080 },
     { key: 'agent', port: 7575 },
@@ -869,13 +906,14 @@ async function allocateProjectPorts(target: string): Promise<void> {
 
 function installDependencies(target: string): number {
   console.log('\n  Installing project dependencies (React, Vite, admin, and framework packages)...');
-  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const result = spawnSync(npm, ['install', '--no-audit', '--no-fund'], {
-    cwd: target,
-    stdio: 'inherit',
-    // Windows npm is a .cmd shim and requires shell execution.
-    shell: process.platform === 'win32',
-  });
+  // Windows npm is a .cmd shim and requires shell execution. Passing the full
+  // command line (no separate args array) avoids Node's DEP0190 warning, which
+  // fires when args are combined with shell: true.
+  const win = process.platform === 'win32';
+  const npmArgs = ['install', '--no-audit', '--no-fund'];
+  const result = win
+    ? spawnSync(`npm.cmd ${npmArgs.join(' ')}`, { cwd: target, stdio: 'inherit', shell: true })
+    : spawnSync('npm', npmArgs, { cwd: target, stdio: 'inherit' });
   if (result.error) {
     console.error(`init: npm install failed: ${result.error.message}`);
     return 1;
@@ -884,6 +922,17 @@ function installDependencies(target: string): number {
     console.error(`init: npm install exited with code ${result.status ?? 'unknown'}`);
     return result.status ?? 1;
   }
+  // npm 11.7+ gates dependency install scripts behind an `allowScripts` policy
+  // and prints an advisory warning for unreviewed scripts (e.g. esbuild's
+  // postinstall). Record approvals in the scaffolded project so its own future
+  // installs stay quiet. Older npm has no such command - the failure is
+  // harmless, and `--no-allow-scripts-pin` keeps entries version-agnostic.
+  const approve = win
+    ? spawnSync('npm.cmd approve-scripts --all --no-allow-scripts-pin', { cwd: target, stdio: 'ignore', shell: true })
+    : spawnSync('npm', ['approve-scripts', '--all', '--no-allow-scripts-pin'], { cwd: target, stdio: 'ignore' });
+  if (approve.error || (approve.status !== null && approve.status !== 0)) {
+    // Old npm - the advisory warning is cosmetic.
+  }
   console.log('  Dependencies installed.');
   return 0;
 }

package/src/commands/node.ts

@@ -36,6 +36,7 @@ export async function node(args: string[]): Promise<number> {
   if (sub === 'serve') {
     const description = roleDescription(role);
     const command = serviceCommand(role, cfg);
+    const noService = args.includes('--no-service');
     const agent = new NodeAgent({
       projectRoot: process.cwd(),
       role: role as never,
@@ -44,7 +45,8 @@ export async function node(args: string[]): Promise<number> {
       token,
       version: '0.1.0',
       services: serviceUrls(role, cfg),
-      serviceCommand: command,
+      serviceCommand: noService ? [] : command,
+      serviceEnv: { NEXUS_SERVER_PORT: String(cfg.server.port) },
       advertisedUrl: process.env.NEXUS_NODE_ADVERTISED_URL,
     });
     await agent.listen(agentHost);
@@ -52,7 +54,10 @@ export async function node(args: string[]): Promise<number> {
     console.log(`  ${GREEN}agent url:  http://${agentHost}:${effectivePort}${RESET}`);
     console.log(`  ${GREEN}token:      ${token ? `${token}` : '<empty - set cluster.token>'}`)
     console.log(`  ${DIM}link it from the central:  nexus cluster link http://${agentHost}:${effectivePort}${RESET}`);
-    if (command.length) {
+    if (noService) {
+      console.log(`  ${DIM}agent-only mode (--no-service): not spawning a role service;${RESET}`);
+      console.log(`  ${DIM}advertising ${serviceUrls(role, cfg)[role as 'backend'] ?? '—'} as the role service.${RESET}`);
+    } else if (command.length) {
       agent.startService();
       console.log(`  started role service: ${command.join(' ')}`);
     }

package/src/commands/pysetup.ts

@@ -126,7 +126,13 @@ async function resolvePython(explicit: string): Promise<string> {
 
 function run(cmd: string, args: string[]): Promise<number> {
   return new Promise((resolveRun) => {
-    const child = spawn(cmd, args, { stdio: 'inherit', shell: process.platform === 'win32' });
+    // Windows: python may be a .cmd shim and needs a shell. Pass the full command
+    // line to avoid Node's DEP0190 warning (args + shell: true are concatenated
+    // unescaped anyway).
+    const win = process.platform === 'win32';
+    const child = win
+      ? spawn([cmd, ...args].map((t) => (/\s/.test(t) ? `"${t}"` : t)).join(' '), { stdio: 'inherit', shell: true })
+      : spawn(cmd, args, { stdio: 'inherit' });
     child.on('error', (err) => {
       console.error(`\x1b[31m[pysetup]\x1b[0m failed to run ${cmd}: ${err.message}`);
       resolveRun(1);

package/src/supervisor.ts

@@ -121,12 +121,22 @@ export class Supervisor {
     for (const k of ['PATH', 'Path', 'path']) delete childEnv[k];
     childEnv.PATH = [...binDirs, origPath].filter(Boolean).join(PATH_SEP);
 
-    const proc = spawn(cmd, args, {
-      cwd: cwdAbs,
-      env: childEnv,
-      shell: process.platform === 'win32',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    // Windows: service commands are often .cmd shims (tsx/vite/npm) that need a
+    // shell. Pass the full command line instead of a separate args array to avoid
+    // Node's DEP0190 warning (args + shell: true are only concatenated anyway).
+    const win = process.platform === 'win32';
+    const proc = win
+      ? spawn([cmd, ...args].map((t) => (/\s/.test(t) ? `"${t}"` : t)).join(' '), {
+          cwd: cwdAbs,
+          env: childEnv,
+          shell: true,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        })
+      : spawn(cmd, args, {
+          cwd: cwdAbs,
+          env: childEnv,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
     this.procs.set(spec.name, proc);
     state.status = 'running';
     state.pid = proc.pid;
@@ -304,7 +314,7 @@ export class Supervisor {
 
   private handleControl(req: IncomingMessage, res: ServerResponse): void {
     const url = new URL(req.url ?? '/', `http://127.0.0.1:${this.controlPort}`);
-    // Permissive CORS so the browser-based admin (localhost:3001) can call us.
+    // Permissive CORS so the browser-based admin (localhost:3300) can call us.
     res.setHeader('access-control-allow-origin', '*');
     res.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
     res.setHeader('access-control-allow-headers', 'content-type, authorization');

package/src/util.ts

@@ -45,7 +45,16 @@ export function parseHostPort(url: string, defaultPort: number): { host: string;
 
 export async function versionOf(cmd: string, args: string[] = ['--version']): Promise<string> {
   try {
-    const { stdout } = await execFileAsync(cmd, args, { shell: process.platform === 'win32' });
+    // Windows: runtimes like `npm` are .cmd shims requiring a shell. Passing the
+    // full command line (no separate args array) avoids Node's DEP0190 warning.
+    const win = process.platform === 'win32';
+    const { stdout } = win
+      ? await execFileAsync(
+          [cmd, ...args].map((t) => (/\s/.test(t) ? `"${t}"` : t)).join(' '),
+          [],
+          { shell: true },
+        )
+      : await execFileAsync(cmd, args, {});
     return stdout.trim();
   } catch {
     return '';

package/templates/Dockerfile

@@ -3,13 +3,13 @@
 # Build:
 #   docker build -t node-1 .
 # Run (pass project secrets; real env vars always win over .env):
-#   docker run --rm -p 4000:4000 -p 3000:3000 -p 3001:3001 --env-file .env node-1
+#   docker run --rm -p 4000:4000 -p 3000:3000 -p 3300:3300 --env-file .env node-1
 #   # or override the server port / cluster node agent port:
-#   docker run --rm -p 4000:4000 -p 3000:3000 -p 3001:3001 -e NEXUS_SERVER_PORT=4000 -e NEXUS_NODE_PORT=7575 node-1
+#   docker run --rm -p 4000:4000 -p 3000:3000 -p 3300:3300 -e NEXUS_SERVER_PORT=4000 -e NEXUS_NODE_PORT=7575 node-1
 #
 # Access:
 #   frontend  http://localhost:3000   (SPA; /health /graphql /auth /ai /ws proxied to the backend)
-#   admin     http://localhost:3001   (SPA; /admin /auth proxied to the backend)
+#   admin     http://localhost:3300   (SPA; /admin /auth proxied to the backend)
 #   backend   http://localhost:4000   (API + /health)
 #   node      http://localhost:7575   (cluster node agent — link it from a root: `nexus cluster link http://<host>:7575`)
 #
@@ -42,7 +42,7 @@ RUN mkdir -p uploads && chown -R node:node /app
 
 # Default ports are informational; the real values come from nexus.config.* /
 # NEXUS_* env overrides at runtime.
-EXPOSE 3000 3001 4000 7575
+EXPOSE 3000 3300 4000 7575
 
 ENV NODE_ENV=production
 
@@ -53,7 +53,7 @@ USER node
 
 # Runs the stack: cluster node agent (:7575) + backend role service via
 # `nexus node serve --role=backend --port=7575`, plus frontend (:3000) and
-# admin (:3001) previews.
+# admin (:3300) previews.
 COPY --chown=node:node bin/serve-all.mjs bin/serve-all.mjs
 COPY --chown=node:node package.json package.json
 

package/templates/README.md

@@ -18,7 +18,7 @@ Then visit:
 
 - Backend: http://localhost:4000/health
 - Frontend: http://localhost:3000
-- Admin: http://localhost:3001
+- Admin: http://localhost:3300
 - AI server: http://localhost:8000
 
 ## What you got

package/templates/apps/admin/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite --port 3001",
+    "dev": "vite --port 3300",
     "build": "tsc -b && vite build",
     "preview": "vite preview"
   },
@@ -12,12 +12,10 @@
     "react-dom": "^18.3.0"
   },
   "devDependencies": {
+    "@bhooai/nexus-postcss": "*",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.0",
-    "autoprefixer": "^10.4.20",
-    "postcss": "^8.4.47",
-    "tailwindcss": "^3.4.13",
     "typescript": "^5.6.0",
     "vite": "^5.4.0"
   }

package/templates/apps/admin/postcss.config.js

@@ -1,6 +1,3 @@
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-};
+import { createPreset } from '@bhooai/nexus-postcss';
+
+export default createPreset();

package/templates/apps/admin/vite.config.ts

@@ -31,7 +31,7 @@ async function loadConfig() {
     },
     admin: {
       host: str(process.env.NEXUS_ADMIN_HOST, user.admin?.host ?? 'localhost'),
-      port: num(process.env.NEXUS_ADMIN_PORT, user.admin?.port ?? 3001),
+      port: num(process.env.NEXUS_ADMIN_PORT, user.admin?.port ?? 3300),
       enabled: user.admin?.enabled ?? true,
     },
     frontend: {

package/templates/apps/backend/package.json

@@ -22,7 +22,8 @@
     "@bhooai/nexus-crypto": "*",
     "@bhooai/nexus-ads": "*",
     "@bhooai/nexus-plugins": "*",
-    "@bhooai/nexus-ai-client": "*"
+    "@bhooai/nexus-ai-client": "*",
+    "@bhooai/nexus-cluster": "*"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",

package/templates/apps/backend/src/main.ts

@@ -312,7 +312,7 @@ async function main(): Promise<void> {
   });
 
   // Cluster manager — auto-starts the LB + autoscaler when config says enabled.
-  const cluster = new ClusterManager({ config: config.cluster, root: PROJECT_ROOT, aiServerUrl: config.ai.serverUrl });
+  const cluster = new ClusterManager({ config: config.cluster, root: PROJECT_ROOT, aiServerUrl: config.ai.serverUrl, self: { id: 'master', baseUrl: `http://127.0.0.1:${config.server.port}` } });
   if (config.cluster.enabled) {
     try {
       await cluster.listenLb(config.cluster.lbHost);

package/templates/apps/backend/src/modules/admin/clusterRoutes.ts

@@ -38,7 +38,7 @@ export function registerClusterRoutes(
   deps: { root: string; config: import('@bhooai/nexus-core').NexusConfig; manager?: ClusterManager },
 ): void {
   const manager = deps.manager ?? (() => {
-    const m = new ClusterManager({ config: deps.config.cluster, root: deps.root, aiServerUrl: deps.config.ai.serverUrl });
+    const m = new ClusterManager({ config: deps.config.cluster, root: deps.root, aiServerUrl: deps.config.ai.serverUrl, self: { id: 'master', baseUrl: `http://127.0.0.1:${deps.config.server.port}` } });
     deps.manager = m;
     return m;
   })();
@@ -214,10 +214,10 @@ export function registerClusterRoutes(
   }, guard);
 
   router.post('/admin/cluster/link', async (ctx) => {
-    const { nodeUrl } = (ctx.body ?? {}) as { nodeUrl?: string };
+    const { nodeUrl, token } = (ctx.body ?? {}) as { nodeUrl?: string; token?: string };
     if (!nodeUrl) { ctx.json({ error: 'nodeUrl is required' }, 400); return; }
     try {
-      const node = await manager.link(nodeUrl);
+      const node = await manager.link(nodeUrl, token);
       upsertClusterNode(toClusterNodeRecord({
         id: node.identity.id, role: node.identity.role, tier: node.identity.tier, version: node.identity.version,
         baseUrl: node.identity.baseUrl, services: node.identity.services, status: node.status, enabled: node.enabled,

package/templates/apps/frontend/package.json

@@ -12,6 +12,7 @@
     "react-dom": "^18.3.0"
   },
   "devDependencies": {
+    "@bhooai/nexus-postcss": "*",
     "@vitejs/plugin-react": "^4.3.0",
     "typescript": "^5.6.0",
     "vite": "^5.4.0"

package/templates/apps/frontend/postcss.config.js

@@ -0,0 +1,3 @@
+import { createPreset } from '@bhooai/nexus-postcss';
+
+export default createPreset();

package/templates/apps/frontend/src/index.css

@@ -0,0 +1,44 @@
+@import '@bhooai/nexus-postcss/theme.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/*
+ * Example: using Nexus design tokens + Tailwind utilities together.
+ *
+ * The theme.css @import above defines CSS custom properties on :root:
+ *   --nexus-bg, --nexus-ink, --nexus-muted, --nexus-surface,
+ *   --nexus-border, --nexus-accent, --nexus-radius, --nexus-mesh, …
+ *
+ * Override any token in your own :root to retheme the whole app:
+ */
+
+:root {
+  /* --nexus-accent: #ff6b6b;  /* uncomment to retheme the accent */
+}
+
+/* Example: a glass-surface card built from Nexus tokens. */
+.nexus-card {
+  background: var(--nexus-surface);
+  border: 1px solid var(--nexus-border);
+  border-radius: var(--nexus-radius);
+  color: var(--nexus-ink);
+  padding: 1.5rem;
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+}
+
+/* Example: ambient mesh background (gradient field behind your app). */
+.nexus-mesh-bg {
+  background: var(--nexus-mesh), var(--nexus-bg);
+  background-attachment: fixed;
+  min-height: 100vh;
+}
+
+/* Example: accent-colored link / button using a token. */
+.nexus-link {
+  color: var(--nexus-accent);
+  text-decoration: none;
+}
+.nexus-link:hover { text-decoration: underline; }

package/templates/apps/frontend/src/main.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import { createRoot } from 'react-dom/client';
+import './index.css';
 
 // Generated placeholder frontend. The framework's own apps/frontend has the full
 // auth / GraphQL / streaming / checkout UI — copy what you need from there.

package/templates/apps/frontend/tailwind.config.js

@@ -0,0 +1,9 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './index.html',
+    './src/**/*.{ts,tsx}',
+  ],
+  theme: { extend: {} },
+  plugins: [],
+};

package/templates/apps/frontend/vite.config.ts

@@ -34,6 +34,10 @@ async function loadConfig() {
       port: num(process.env.NEXUS_FRONTEND_PORT, user.frontend?.port ?? 3000),
       enabled: user.frontend?.enabled ?? true,
     },
+    cluster: {
+      enabled: user.cluster?.enabled ?? false,
+      lbPort: num(process.env.NEXUS_CLUSTER_LBPORT, user.cluster?.lbPort ?? 8080),
+    },
   };
 }
 
@@ -42,6 +46,11 @@ export default defineConfig(async () => {
   const backendHost = cfg.server.host === '0.0.0.0' || cfg.server.host === '::' ? '127.0.0.1' : cfg.server.host;
   const backend = `http://${backendHost}:${cfg.server.port}`;
   const backendWs = `ws://${backendHost}:${cfg.server.port}`;
+  // When the cluster is enabled, route /uploads through the load balancer so
+  // path-pin routing (/uploads/images -> slave-1, /uploads/files -> slave-2)
+  // actually applies. Otherwise fall back to the local backend directly.
+  const lbTarget = `http://${backendHost}:${cfg.cluster.lbPort}`;
+  const uploadsTarget = cfg.cluster.enabled ? lbTarget : backend;
 
   return {
     plugins: [react()],
@@ -55,7 +64,7 @@ export default defineConfig(async () => {
         '/graphql': { target: backend, changeOrigin: true, ws: true },
         '/ai': { target: backend, changeOrigin: true },
         '/payments': { target: backend, changeOrigin: true },
-        '/uploads': { target: backend, changeOrigin: true },
+        '/uploads': { target: uploadsTarget, changeOrigin: true },
         '/ws': { target: backendWs, ws: true, changeOrigin: true },
       },
     },

package/templates/bin/serve-all.mjs

@@ -2,7 +2,7 @@
 //   backend  -> nexus node serve --role=backend --port=<NEXUS_NODE_PORT|7575>
 //               (cluster node agent on :7575 + backend role service)
 //   frontend -> vite preview on :3000          (built SPA, proxies API)
-//   admin    -> vite preview on :3001          (built admin SPA, proxies API)
+//   admin    -> vite preview on :3300          (built admin SPA, proxies API)
 // Forwards signals / reaps children so `docker stop` shuts down cleanly.
 import { spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
@@ -42,4 +42,4 @@ process.on('SIGTERM', () => shutdown(0));
 
 run('backend', root, node, ['bin/nexus.js', 'node', 'serve', '--role=backend', `--port=${nodePort}`]);
 run('frontend', join(root, 'apps', 'frontend'), npm, ['run', 'preview', '--', '--host', '0.0.0.0', '--port', '3000']);
-run('admin', join(root, 'apps', 'admin'), npm, ['run', 'preview', '--', '--host', '0.0.0.0', '--port', '3001']);
+run('admin', join(root, 'apps', 'admin'), npm, ['run', 'preview', '--', '--host', '0.0.0.0', '--port', '3300']);

package/templates/nexus.config.ts

@@ -22,7 +22,7 @@ const config: Partial<NexusConfig> = {
   // Python AI server (first /ai/* proxy hops to this).
   ai: { serverUrl: 'http://localhost:8000', timeoutMs: 60_000, defaultProvider: 'auto', schemaModel: 'llama3:latest' },
   // Vite dev server for the admin app.
-  admin: { port: 3001, host: 'localhost', enabled: true },
+  admin: { port: 3300, host: 'localhost', enabled: true },
   // Node mesh: set kind via —as=root|node at init (this file stays minimal).
   cluster: { enabled: false, failOpenSingleNode: true, lbHost: '0.0.0.0', lbPort: 8080, nodeAgentHost: '0.0.0.0', nodeAgentPort: 7575, registryFile: 'cluster.runtime.json', token: '' },
   

package/tests/cli.test.ts

@@ -31,6 +31,13 @@ describe('CLI init', () => {
     expect(existsSync(join(dir, 'nexus.config.ts'))).toBe(true);
     expect(existsSync(join(dir, 'apps/backend/src/main.ts'))).toBe(true);
     expect(existsSync(join(dir, 'apps/frontend/src/main.tsx'))).toBe(true);
+    expect(existsSync(join(dir, 'apps/frontend/tailwind.config.js'))).toBe(true);
+    expect(existsSync(join(dir, 'apps/frontend/postcss.config.js'))).toBe(true);
+    expect(existsSync(join(dir, 'apps/frontend/src/index.css'))).toBe(true);
+    const fePkg = JSON.parse(readFileSync(join(dir, 'apps/frontend/package.json'), 'utf8')) as Record<string, any>;
+    expect(fePkg.devDependencies?.['@bhooai/nexus-postcss']).toBeDefined();
+    const fePostcss = readFileSync(join(dir, 'apps/frontend/postcss.config.js'), 'utf8');
+    expect(fePostcss).toContain('createPreset');
     expect(existsSync(join(dir, 'apps/ai-server/main.py'))).toBe(true);
     expect(existsSync(join(dir, 'apps/admin/src/main.tsx'))).toBe(true);
   });