@bhooai/nexus-cli 0.1.5 → 2.0.1

package/src/index.ts

@@ -1,94 +1,36 @@
-import { doctor } from './commands/doctor.js';
-import { init } from './commands/init.js';
-import { dev } from './commands/dev.js';
-import { pysetup } from './commands/pysetup.js';
-import { cluster } from './commands/cluster.js';
-import { node } from './commands/node.js';
-import { syncCommand } from './commands/sync.js';
-import { uninstall } from './commands/uninstall.js';
-import { loadDotEnv } from './dotenv.js';
+/**
+ * nexus CLI entry — registers all commands and dispatches.
+ */
+import { registerCommand, run as dispatch } from './dispatcher.js';
+import * as initCmd from './commands/init.js';
+import * as devCmd from './commands/dev.js';
+import * as doctorCmd from './commands/doctor.js';
+import * as buildCmd from './commands/build.js';
+import * as testCmd from './commands/test.js';
+import * as addCmd from './commands/add.js';
+import * as pluginCmd from './commands/plugin.js';
+import * as dbCmd from './commands/db.js';
+import * as queueCmd from './commands/queue.js';
+import { downCommand, upCommand } from './commands/maintenance-commands.js';
+import { registerMakeCommands } from './make/generators.js';
 
-/** Dispatch a CLI command. Returns the exit code. */
-export async function run(cmd: string, args: string[]): Promise<number> {
-  // Load the project .env once so NEXUS_* keys reach the config loader AND the
-  // supervised child processes (they inherit process.env).
-  loadDotEnv(process.cwd());
+registerCommand({ name: 'init', description: initCmd.description, usage: initCmd.usage, run: initCmd.run });
+registerCommand({ name: 'dev', description: devCmd.description, usage: devCmd.usage, run: devCmd.run });
+registerCommand({ name: 'doctor', description: doctorCmd.description, usage: doctorCmd.usage, run: doctorCmd.run });
+registerCommand({ name: 'build', description: buildCmd.description, usage: buildCmd.usage, run: buildCmd.run });
+registerCommand({ name: 'test', description: testCmd.description, usage: testCmd.usage, run: testCmd.run });
+registerCommand({ name: 'add', description: addCmd.description, usage: addCmd.usage, run: addCmd.run });
+registerCommand({ name: 'plugin', description: pluginCmd.description, usage: pluginCmd.usage, run: pluginCmd.run });
+registerCommand({ name: 'db:seed', description: dbCmd.description, usage: dbCmd.usage, run: dbCmd.runSeed });
+registerCommand({ name: 'db:migrate', description: dbCmd.description, usage: dbCmd.usage, run: dbCmd.runMigrate });
+registerCommand({ name: 'db:rollback', description: dbCmd.description, usage: dbCmd.usage, run: dbCmd.runRollback });
+registerCommand({ name: 'queue:work', description: queueCmd.description, usage: queueCmd.usage, run: queueCmd.runWork });
+registerCommand({ name: 'queue:retry', description: queueCmd.description, usage: queueCmd.usage, run: queueCmd.runRetry });
+registerCommand(downCommand);
+registerCommand(upCommand);
 
-  switch (cmd) {
-    case 'doctor':
-      return doctor();
-    case 'init':
-      return init({}, args);
-    case 'dev':
-      return dev(args);
-    case 'build':
-      console.log('nexus build - implemented in a later phase (tsc across workspaces).');
-      return 0;
-    case 'test':
-      console.log('nexus test - run `npm test` (vitest + pytest) for now.');
-      return 0;
-    case 'plugin':
-      console.log('nexus plugin <new|install> - implemented in Phase 8.');
-      return 0;
-    case 'add':
-      console.log('nexus add <subgraph|module> - implemented in Phase 5/6.');
-      return 0;
-    case 'pysetup':
-      return pysetup(args);
-    case 'uninstall':
-      return uninstall(args);
-    case 'cluster':
-      return cluster(args);
-    case 'node':
-      return node(args);
-    case 'sync':
-      return syncCommand(args);
-    case 'help':
-    case '--help':
-    case '-h':
-      printHelp();
-      return 0;
-    default:
-      console.error(`Unknown command: ${cmd}`);
-      printHelp();
-      return 1;
-  }
-}
-
-function printHelp(): void {
-  console.log(`
-BhooAI Nexus CLI
-
-Usage: nexus <command> [args]
+registerMakeCommands(registerCommand);
 
-Commands:
-  init [target] [--as=root|node] [--role=R] [--name=N] [--mongo-uri=URI]
-       [--redis-url=URL] [--ai-providers=a,b] [--ai-key id=val]
-       [--cluster-token=T] [--venv|--no-venv] [--no-interactive] [--no-install] [--skip-mongo-check]
-                                   Scaffold a project; one-command wizard sets up
-                                   Node + frontend + admin + Python AI + Mongo/Redis
-  dev [--only a,b]          Start the four terminals under the supervisor
-  build                     Build all TypeScript workspaces
-  test                      Run all test suites
-  doctor                    Verify the environment (node, python, mongo, redis)
-  plugin <new|install>      Manage plugins
-  add <subgraph|module>     Scaffold a new subgraph or module
-  pysetup [pkgs...] [--venv] [--interactive]
-                             Install the AI-server Python deps (requirements.txt) + extras
-  uninstall [--target <path>] [--purge] [--force] [--dry-run]
-                             Drop the project DB, delete its nexus_projects record,
-                             optionally remove the project directory (--purge)
-  node <id|serve>           Run this machine as a cluster node (agent + role service)
-  cluster <sub>             Root-side mesh: status, link, scale, serve, etc.
-  sync [--check] [--no-db]  Rewrite Dockerfiles, docker.*, serve-all.mjs & DB from nexus.config.ts
-
-Options:
-  -h, --help                Show this help
-`);
+export async function run(cmd: string, argv: string[]): Promise<void> {
+  await dispatch(cmd, argv);
 }
-
-// Re-exports for programmatic use.
-export { doctor, init, dev, pysetup, cluster, node, syncCommand };
-export { syncConfig, configChangedSinceSync, deriveValues, fingerprintOf } from './config-sync.js';
-export { Supervisor } from './supervisor.js';
-export type { LogEntry } from './supervisor.js';

package/src/make/generators.ts

@@ -0,0 +1,431 @@
+/**
+ * All make:* generators — registered as commands under the `make:` prefix.
+ */
+import type { Command } from '../dispatcher.js';
+import { runGenerator, type GeneratorSpec } from '../generators.js';
+
+// ---------------------------------------------------------------------------
+// Templates for each artifact
+// ---------------------------------------------------------------------------
+
+const GENERATORS: Record<string, GeneratorSpec> = {
+  route: {
+    folder: 'routes',
+    suffix: '.ts',
+    render: ({ slug }) => `import { defineRoutes } from '@bhooai/nexus-core';
+import type { RequestContext } from '@bhooai/nexus-core';
+
+export default defineRoutes([
+  { method: 'GET',    path: '/${slug}',      handler: list   },
+  { method: 'POST',   path: '/${slug}',      handler: create },
+  { method: 'GET',    path: '/${slug}/:id',  handler: getOne },
+  { method: 'PATCH',  path: '/${slug}/:id',  handler: update },
+  { method: 'DELETE', path: '/${slug}/:id',  handler: remove },
+]);
+
+function list(_ctx: RequestContext)     { _ctx.json([]); }
+function create(ctx: RequestContext)    { ctx.json({ created: true }, 201); }
+function getOne(ctx: RequestContext)    { ctx.json({ id: ctx.params.id }); }
+function update(ctx: RequestContext)    { ctx.json({ id: ctx.params.id, updated: true }); }
+function remove(ctx: RequestContext)    { ctx.status(204); }
+`,
+  },
+
+  controller: {
+    folder: 'controllers',
+    suffix: 'Controller.ts',
+    render: ({ className, slug }) => `/**
+ * ${className}Controller — actions for the ${slug} resource.
+ * Routes reference these from ../routes/${slug}.ts.
+ */
+export class ${className}Controller {
+  async list()    { return []; }
+  async create(body: unknown) { return { created: true, body }; }
+  async getOne(id: string)    { return { id }; }
+  async update(id: string, body: unknown) { return { id, body }; }
+  async remove(_id: string)   { /* no-op */ }
+}
+`,
+  },
+
+  model: {
+    folder: 'models',
+    suffix: '.ts',
+    render: ({ className, slug }) => `import { model, Schema } from '@bhooai/nexus-data';
+
+const ${slug}Schema = new Schema({
+  name:      { type: String, required: true },
+  createdAt: { type: Date,   default: () => new Date() },
+  updatedAt: { type: Date,   default: () => new Date() },
+});
+
+export const ${className} = model('${slug}s', ${slug}Schema);
+export type ${className}Doc = typeof ${className} extends ((...args: never[]) => infer R) ? R : never;
+`,
+  },
+
+  service: {
+    folder: 'services',
+    suffix: 'Service.ts',
+    render: ({ className }) => `/**
+ * ${className}Service — business logic for the resource.
+ * Callers: routes/*, graphql/*.graph.ts, ws/*.room.ts.
+ */
+export class ${className}Service {
+  async list() { return []; }
+  async findById(id: string) { return { id }; }
+}
+`,
+  },
+
+  repository: {
+    folder: 'repositories',
+    suffix: 'Repository.ts',
+    render: ({ className, slug }) => `/**
+ * ${className}Repository — query layer over the ${slug} collection.
+ * Keeps Mongo concerns out of services.
+ */
+import type { Db } from 'mongodb';
+
+export class ${className}Repository {
+  constructor(private db: Db) {}
+
+  async findAll() {
+    return this.db.collection('${slug}s').find({}).toArray();
+  }
+
+  async findById(id: string) {
+    return this.db.collection('${slug}s').findOne({ _id: id as never });
+  }
+}
+`,
+  },
+
+  middleware: {
+    folder: 'middleware',
+    suffix: '.ts',
+    render: ({ slug, className }) => `import type { Middleware } from '@bhooai/nexus-core';
+
+/**
+ * ${className} — route middleware. Attach via routes/*.ts middleware: [...].
+ */
+export const ${className}: Middleware = async (ctx, next) => {
+  // pre-handler work
+  await next();
+  // post-handler work
+};
+`,
+  },
+
+  validator: {
+    folder: 'validators',
+    suffix: '.schema.ts',
+    render: ({ slug, className }) => `import { z } from 'zod';
+
+export const ${className}Schema = z.object({
+  name: z.string().min(2),
+});
+
+export type ${className}Input = z.infer<typeof ${className}Schema>;
+`,
+  },
+
+  job: {
+    folder: 'jobs',
+    suffix: 'Job.ts',
+    render: ({ className }) => `import { Job } from '@bhooai/nexus-core';
+
+export default class ${className}Job extends Job {
+  queue = 'default';
+  retries = 3;
+  backoff = 'exponential' as const;
+
+  async handle(...args: unknown[]): Promise<void> {
+    // Job logic here. Throw to trigger retry.
+    void args;
+  }
+}
+`,
+  },
+
+  event: {
+    folder: 'events',
+    suffix: '.ts',
+    render: ({ className }) => `import { DomainEvent } from '@bhooai/nexus-core';
+
+export class ${className} extends DomainEvent {
+  // Payload fields as constructor args.
+  // constructor(public readonly userId: string) { super(); }
+}
+`,
+  },
+
+  listener: {
+    folder: 'listeners',
+    suffix: '.ts',
+    render: ({ className }) => `import { Listener } from '@bhooai/nexus-core';
+
+// Convention: file name "On<Foo>.ts" auto-wires to event "<Foo>".
+// Adjust imports / class target if your event lives elsewhere.
+export default class ${className} extends Listener {
+  async handle(event: unknown): Promise<void> {
+    // event is the dispatched DomainEvent instance
+    void event;
+  }
+}
+`,
+  },
+
+  policy: {
+    folder: 'policies',
+    suffix: 'Policy.ts',
+    render: ({ className, slug }) => `import { Policy } from '@bhooai/nexus-core';
+
+/**
+ * ${className}Policy — authorization rules for ${slug}.
+ *
+ * Methods on this class correspond to abilities: view, create, update, delete, ...
+ * Return true to allow, false to deny. Async allowed.
+ */
+export default class ${className}Policy extends Policy {
+  viewAny(_actor: unknown) { return true; }
+  view(_actor: unknown, _resource: unknown) { return true; }
+  create(_actor: unknown) { return true; }
+  update(_actor: unknown, _resource: unknown) { return true; }
+  delete(_actor: unknown, _resource: unknown) { return true; }
+}
+`,
+  },
+
+  resource: {
+    folder: 'resources',
+    suffix: 'Resource.ts',
+    render: ({ className }) => `import { Resource } from '@bhooai/nexus-core';
+
+interface ${className}Shape {
+  id: string;
+  name: string;
+  // ...
+}
+
+export class ${className}Resource extends Resource<${className}Shape> {
+  toJSON(value: ${className}Shape) {
+    return {
+      id: value.id,
+      name: value.name,
+    };
+  }
+}
+`,
+  },
+
+  request: {
+    folder: 'requests',
+    suffix: 'Request.ts',
+    render: ({ className }) => `import { FormRequest } from '@bhooai/nexus-core';
+import { z } from 'zod';
+
+export class ${className}Request extends FormRequest {
+  schema = z.object({
+    // define body schema
+  });
+
+  // authorize(ctx) { return !!ctx.state.user; }
+}
+`,
+  },
+
+  mail: {
+    folder: 'mail/mailables',
+    suffix: 'Mail.ts',
+    render: ({ className, slug }) => `import { Mailable } from '@bhooai/nexus-core';
+
+export default class ${className}Mail extends Mailable {
+  subject = '${className}';
+  template = '${slug}';
+
+  data() {
+    return {};
+  }
+}
+`,
+    companions: [{
+      relativePath: ({ slug }) => `mail/templates/${slug}.ejs`,
+      content: () => `<!doctype html>
+<html>
+<body>
+  <p>Hello,</p>
+  <p>This is the auto-generated template. Edit me.</p>
+</body>
+</html>
+`,
+    }],
+  },
+
+  room: {
+    folder: 'ws',
+    suffix: '.room.ts',
+    render: ({ slug }) => `import type { RequestContext } from '@bhooai/nexus-core';
+
+/**
+ * WebSocket room "${slug}". Auto-mounted on /ws.
+ *
+ * Real wiring awaits the realtime integration in createNexusApp (P2.5).
+ * For now this file simply exports a manifest.
+ */
+export default {
+  name: '${slug}',
+  onJoin: async (_socket: unknown, _ctx: RequestContext) => {},
+  onLeave: async (_socket: unknown, _ctx: RequestContext) => {},
+  onMessage: {
+    // 'msg:send': async (socket, payload) => { ... },
+  },
+};
+`,
+  },
+
+  subgraph: {
+    folder: 'graphql',
+    suffix: '.graph.ts',
+    render: ({ slug, className }) => `/**
+ * ${className} GraphQL subgraph — picked up by the federation composer.
+ * typeDefs use federation directives (@key, @extends).
+ */
+export const typeDefs = /* GraphQL */ \`
+  type ${className} @key(fields: "id") {
+    id: ID!
+    name: String!
+  }
+
+  extend type Query {
+    ${slug}: [${className}!]!
+  }
+\`;
+
+export const resolvers = {
+  Query: {
+    ${slug}: () => [],
+  },
+};
+`,
+  },
+
+  seeder: {
+    folder: 'database/seeds',
+    suffix: 'Seeder.ts',
+    render: ({ className }) => `import { Seeder } from '@bhooai/nexus-core';
+import type { Db } from 'mongodb';
+
+export default class ${className}Seeder extends Seeder {
+  async run(db?: Db): Promise<void> {
+    void db;
+    // Example: await db?.collection('users').insertMany([...]);
+  }
+}
+`,
+  },
+
+  migration: {
+    folder: 'database/migrations',
+    // Migrations get a timestamped filename — handled specially below (make:migration below).
+    // This entry is here only as a template holder; registration skips it.
+    suffix: '.ts',
+    render: ({ slug }) => `import type { Db } from 'mongodb';
+
+export async function up(db: Db): Promise<void> {
+  // await db.createCollection('${slug}s');
+}
+
+export async function down(db: Db): Promise<void> {
+  // await db.dropCollection('${slug}s');
+}
+`,
+  },
+
+  provider: {
+    folder: 'providers',
+    suffix: 'ServiceProvider.ts',
+    render: ({ className }) => `import { ServiceProvider } from '@bhooai/nexus-core';
+import type { Container } from '@bhooai/nexus-core';
+
+export default class ${className}ServiceProvider extends ServiceProvider {
+  register(container: Container): void {
+    // container.singleton('name', () => new Thing());
+    void container;
+  }
+
+  async boot(_container: Container): Promise<void> {
+    // post-registration boot
+  }
+}
+`,
+  },
+
+  plugin: {
+    folder: 'plugins',
+    suffix: '/index.ts',
+    render: ({ slug, className }) => `/**
+ * ${className} plugin entry.
+ */
+import type { Container } from '@bhooai/nexus-core';
+
+export function register(_container: Container): void {}
+
+export async function boot(): Promise<void> {}
+`,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export function registerMakeCommands(register: (cmd: Command) => void): void {
+  for (const [name, spec] of Object.entries(GENERATORS)) {
+    if (name === 'migration') continue;   // handled below with timestamp logic
+    register({
+      name: `make:${name}`,
+      description: `Generate a new ${name} under apps/<backend>/src/${spec.folder}`,
+      usage: `nexus make:${name} <name> [--app <backend>]`,
+      run: async (ctx) => {
+        await runGenerator(ctx, spec);
+      },
+    });
+  }
+
+  // migrations need a separate code-path (timestamped filename).
+  register({
+    name: 'make:migration',
+    description: 'Generate a new timestamped migration',
+    usage: 'nexus make:migration <name> [--app <backend>]',
+    run: async (ctx) => {
+      const rawName = ctx.args._[0];
+      if (!rawName) {
+        console.error('Usage: nexus make:migration <name> [--app <backend>]');
+        process.exitCode = 1;
+        return;
+      }
+      const { resolve, join } = await import('node:path');
+      const { mkdir, writeFile } = await import('node:fs/promises');
+      const { existsSync } = await import('node:fs');
+      const { slugFromName } = await import('../generators.js');
+
+      const slug = slugFromName(rawName);
+      const app = (ctx.args.flags.app as string) ?? 'backend';
+      const projectRoot = process.cwd();
+      const ts = new Date();
+      const stamp = `${ts.getUTCFullYear()}_${String(ts.getUTCMonth() + 1).padStart(2, '0')}_${String(ts.getUTCDate()).padStart(2, '0')}_${String(ts.getUTCHours()).padStart(2, '0')}${String(ts.getUTCMinutes()).padStart(2, '0')}${String(ts.getUTCSeconds()).padStart(2, '0')}`;
+      const fileName = `${stamp}_${slug}.ts`;
+      const dir = resolve(projectRoot, 'apps', app, 'src', 'database', 'migrations');
+      await mkdir(dir, { recursive: true });
+      const target = join(dir, fileName);
+      if (existsSync(target)) {
+        console.error(`✗ already exists: ${target}`);
+        process.exitCode = 1;
+        return;
+      }
+      await writeFile(target, GENERATORS.migration!.render({ slug, className: '', name: rawName }));
+      console.log(`✓ Created ${target.replace(projectRoot + '\\', '')}`);
+    },
+  });
+}

package/src/ports.ts

@@ -0,0 +1,85 @@
+/**
+ * Per-app port registry.
+ *
+ * Maintains `.nexus-ports.json` at the project root so each backend /
+ * frontend / admin has a stable port across runs. Both `nexus add` and
+ * `nexus dev` consult + update this file. `createNexusApp()` reads via the
+ * NEXUS_PORT env var (set by `nexus dev`) or by looking up its app name.
+ *
+ * Format:
+ *   { "backend": 4000, "backend-shop": 4001, "frontend": 3000, ... }
+ */
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { nextFreePort } from './util.js';
+
+const REGISTRY_FILENAME = '.nexus-ports.json';
+
+export interface PortRegistry {
+  [appName: string]: number;
+}
+
+const DEFAULTS: Record<string, number> = {
+  backend:   4000,
+  frontend:  3000,
+  admin:     3300,
+  'ai-server': 8000,
+};
+
+export function registryPath(projectRoot: string): string {
+  return join(resolve(projectRoot), REGISTRY_FILENAME);
+}
+
+export async function readRegistry(projectRoot: string): Promise<PortRegistry> {
+  const p = registryPath(projectRoot);
+  if (!existsSync(p)) return {};
+  try {
+    const raw = await readFile(p, 'utf-8');
+    return JSON.parse(raw) as PortRegistry;
+  } catch {
+    return {};
+  }
+}
+
+export async function writeRegistry(projectRoot: string, registry: PortRegistry): Promise<void> {
+  await writeFile(registryPath(projectRoot), JSON.stringify(registry, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Get the port assigned to an app, allocating + persisting one if missing.
+ *
+ * Default port logic:
+ *   - If app is a known type (backend / frontend / admin / ai-server), use its canonical default
+ *   - Otherwise, derive from the type prefix: backend-* → 4000+, frontend-* → 3000+, admin-* → 3300+
+ *   - Bump until free + not already in registry
+ */
+export async function ensurePort(projectRoot: string, appName: string): Promise<number> {
+  const reg = await readRegistry(projectRoot);
+  if (reg[appName]) return reg[appName]!;
+
+  const defaultPort = defaultPortFor(appName);
+  const used = new Set(Object.values(reg));
+  let candidate = defaultPort;
+  while (used.has(candidate)) candidate++;
+  // Verify the candidate is actually free on the box right now
+  candidate = await nextFreePort(candidate);
+
+  reg[appName] = candidate;
+  await writeRegistry(projectRoot, reg);
+  return candidate;
+}
+
+export function defaultPortFor(appName: string): number {
+  if (DEFAULTS[appName]) return DEFAULTS[appName]!;
+  if (appName.startsWith('backend-')) return 4000;
+  if (appName.startsWith('frontend-')) return 3000;
+  if (appName.startsWith('admin-')) return 3300;
+  return 5000;
+}
+
+/** Look up the port for an app without allocating one (returns null if unset). */
+export async function lookupPort(projectRoot: string, appName: string): Promise<number | null> {
+  const reg = await readRegistry(projectRoot);
+  return reg[appName] ?? null;
+}