@bhooai/nexus-cli 0.1.4 → 2.0.0

package/src/commands/maintenance-commands.ts

@@ -0,0 +1,40 @@
+/**
+ * nexus down — enable maintenance mode for the current project.
+ * nexus up  — disable maintenance mode.
+ */
+import type { CommandContext } from '../dispatcher.js';
+import { setMaintenance, isMaintenance, maintenanceMessage } from '@bhooai/nexus-core';
+
+export async function runDown(ctx: CommandContext): Promise<void> {
+  const projectRoot = process.cwd();
+  const msg = ctx.args.flags.message as string | undefined;
+  await setMaintenance(projectRoot, true, msg);
+  console.log(`✓ Maintenance mode enabled${msg ? ` — "${msg}"` : ''}`);
+  console.log(`  All requests will receive HTTP 503 (except /health).`);
+  console.log(`  Use \`nexus up\` to restore.`);
+}
+
+export async function runUp(_ctx: CommandContext): Promise<void> {
+  const projectRoot = process.cwd();
+  if (!isMaintenance(projectRoot)) {
+    console.log('Maintenance mode is not enabled.');
+    return;
+  }
+  const msg = await maintenanceMessage(projectRoot);
+  await setMaintenance(projectRoot, false);
+  console.log(`✓ Maintenance mode disabled${msg ? ` (was: "${msg}")` : ''}`);
+}
+
+export const downCommand = {
+  name: 'down',
+  description: 'Enable maintenance mode (503 + Retry-After)',
+  usage: 'nexus down [--message "..."]',
+  run: runDown,
+};
+
+export const upCommand = {
+  name: 'up',
+  description: 'Disable maintenance mode',
+  usage: 'nexus up',
+  run: runUp,
+};

package/src/commands/plugin.ts

@@ -0,0 +1,233 @@
+/**
+ * nexus plugin — manage project plugins (new / install / remove / list).
+ *
+ *   nexus plugin new <name>             — scaffold plugins/<name>/ with a manifest
+ *   nexus plugin install <pkg-or-path>  — install a plugin (npm package or local path)
+ *   nexus plugin remove <name>          — remove a plugin entry
+ *   nexus plugin list                   — list registered plugins
+ *
+ * Plugin entry lives in nexus.config.ts under `plugins.entries[]`.
+ */
+import { mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+import type { CommandContext } from '../dispatcher.js';
+import { slugify } from '../util.js';
+import { confirm, isInteractive } from '../prompts.js';
+
+const PLUGIN_MANIFEST = `{
+  "name": "<%= name %>",
+  "version": "0.1.0",
+  "description": "",
+  "main": "index.ts"
+}
+`;
+
+const PLUGIN_INDEX = `/**
+ * <name> plugin — auto-loaded by createNexusApp().
+ *
+ * Export hooks:
+ *   register(container)   — wire singletons before routes mount
+ *   routes                — additional RoutesFile[] to merge
+ *   boot(app)             — post-init hook
+ */
+import type { Container } from '@bhooai/nexus-core';
+
+export function register(container: Container): void {
+  // Register DI singletons here.
+}
+
+export async function boot(): Promise<void> {
+  // Async init.
+}
+
+// export const routes = [...];   // opt-in: additional HTTP routes
+`;
+
+interface PluginEntry {
+  path: string;
+  enabled: boolean;
+  config?: Record<string, unknown>;
+}
+
+export async function run(ctx: CommandContext): Promise<void> {
+  const sub = ctx.args._[0];
+  switch (sub) {
+    case 'new':     return pluginNew(ctx);
+    case 'install': return pluginInstall(ctx);
+    case 'remove':  return pluginRemove(ctx);
+    case 'list':    return pluginList(ctx);
+    default:
+      console.error('Usage: nexus plugin <new|install|remove|list> [...]');
+      process.exitCode = 1;
+  }
+}
+
+async function pluginNew(ctx: CommandContext): Promise<void> {
+  const name = ctx.args._[1];
+  if (!name) {
+    console.error('Usage: nexus plugin new <name>');
+    process.exitCode = 1;
+    return;
+  }
+  const slug = slugify(name);
+  const projectRoot = process.cwd();
+  const pluginsDir = resolve(projectRoot, getPluginsDir(projectRoot));
+  const pluginDir = join(pluginsDir, slug);
+  if (existsSync(pluginDir)) {
+    console.error(`✗ Plugin "${slug}" already exists at ${pluginDir}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await mkdir(pluginDir, { recursive: true });
+  await writeFile(join(pluginDir, 'package.json'), PLUGIN_MANIFEST.replace(/<%= name %>/g, slug));
+  await writeFile(join(pluginDir, 'index.ts'), PLUGIN_INDEX.replace(/<name>/g, slug));
+  await registerPluginInConfig(projectRoot, { path: join('./', getPluginsDir(projectRoot), slug), enabled: true });
+
+  console.log(`✓ Created ${pluginDir}`);
+}
+
+async function pluginInstall(ctx: CommandContext): Promise<void> {
+  const pkg = ctx.args._[1];
+  if (!pkg) {
+    console.error('Usage: nexus plugin install <pkg-or-path>');
+    process.exitCode = 1;
+    return;
+  }
+  const projectRoot = process.cwd();
+  const isPath = pkg.startsWith('./') || pkg.startsWith('../') || pkg.includes(':\\') || pkg.startsWith('/');
+  const path = isPath ? pkg : pkg;   // for npm packages, just record the name; resolution happens at require time
+  await registerPluginInConfig(projectRoot, { path, enabled: true });
+  console.log(`✓ Registered plugin: ${path}`);
+  if (!isPath) {
+    console.log(`  Run \`npm install ${pkg}\` if not already installed.`);
+  }
+}
+
+async function pluginRemove(ctx: CommandContext): Promise<void> {
+  const name = ctx.args._[1];
+  if (!name) {
+    console.error('Usage: nexus plugin remove <name>');
+    process.exitCode = 1;
+    return;
+  }
+  const projectRoot = process.cwd();
+  const removed = await unregisterPluginInConfig(projectRoot, name);
+  if (!removed) {
+    console.error(`✗ Plugin "${name}" not registered in nexus.config.ts`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`✓ Removed plugin entry: ${name}`);
+
+  // If it's a local folder under plugins/, offer to delete the files.
+  const pluginsDir = resolve(projectRoot, getPluginsDir(projectRoot));
+  const localDir = join(pluginsDir, slugify(name));
+  if (existsSync(localDir) && isInteractive()) {
+    const yes = await confirm(`Also delete ${localDir}?`, false);
+    if (yes) {
+      await rm(localDir, { recursive: true, force: true });
+      console.log(`✓ Deleted ${localDir}`);
+    }
+  }
+}
+
+async function pluginList(_ctx: CommandContext): Promise<void> {
+  const projectRoot = process.cwd();
+  const entries = await readPluginEntries(projectRoot);
+  if (entries.length === 0) {
+    console.log('(no plugins registered — entries array is empty)');
+    return;
+  }
+  console.log(`Plugins in nexus.config.ts (${entries.length}):\n`);
+  for (const e of entries) {
+    console.log(`  ${e.enabled ? '✓' : '○'} ${e.path}`);
+  }
+}
+
+// ----------------------------------------------------------------------
+// Config read/write helpers
+// ----------------------------------------------------------------------
+
+function getPluginsDir(projectRoot: string): string {
+  const pluginsDir = readPluginsDirFromConfig(projectRoot);
+  return pluginsDir ?? 'plugins';
+}
+
+function readPluginsDirFromConfig(projectRoot: string): string | null {
+  const cfgPath = resolve(projectRoot, 'nexus.config.ts');
+  if (!existsSync(cfgPath)) return null;
+  try {
+    const raw = require('node:fs').readFileSync(cfgPath, 'utf-8');
+    const m = raw.match(/plugins\s*:\s*\{[^}]*dir\s*:\s*['"]([^'"]+)['"]/);
+    return m ? m[1]! : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readPluginEntries(projectRoot: string): Promise<PluginEntry[]> {
+  const cfgPath = resolve(projectRoot, 'nexus.config.ts');
+  if (!existsSync(cfgPath)) return [];
+  try {
+    const raw = await readFile(cfgPath, 'utf-8');
+    // Naive but reliable-ish parse: find entries: [...] block
+    const m = raw.match(/entries\s*:\s*\[([\s\S]*?)\]/);
+    if (!m) return [];
+    const block = m[1]!;
+    const entries: PluginEntry[] = [];
+    const re = /\{\s*path\s*:\s*['"]([^'"]+)['"]\s*,\s*enabled\s*:\s*(true|false)/g;
+    let match;
+    while ((match = re.exec(block)) !== null) {
+      entries.push({ path: match[1]!, enabled: match[2] === 'true' });
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+async function registerPluginInConfig(projectRoot: string, entry: PluginEntry): Promise<void> {
+  const cfgPath = resolve(projectRoot, 'nexus.config.ts');
+  if (!existsSync(cfgPath)) {
+    throw new Error('nexus.config.ts not found in project root');
+  }
+  const raw = await readFile(cfgPath, 'utf-8');
+  const jsonEntry = `{ path: '${entry.path}', enabled: ${entry.enabled} }`;
+
+  // If entries: [] is empty, replace with [entry]
+  if (/entries\s*:\s*\[\s*\]/.test(raw)) {
+    const updated = raw.replace(/entries\s*:\s*\[\s*\]/, `entries: [${jsonEntry}]`);
+    await writeFile(cfgPath, updated, 'utf-8');
+    return;
+  }
+  // If entries: [...existing...], append
+  if (/entries\s*:\s*\[/.test(raw)) {
+    const updated = raw.replace(/entries\s*:\s*\[/, `entries: [${jsonEntry}, `);
+    await writeFile(cfgPath, updated, 'utf-8');
+    return;
+  }
+  throw new Error('Cannot locate plugins.entries[] in nexus.config.ts');
+}
+
+async function unregisterPluginInConfig(projectRoot: string, name: string): Promise<boolean> {
+  const cfgPath = resolve(projectRoot, 'nexus.config.ts');
+  if (!existsSync(cfgPath)) return false;
+  const raw = await readFile(cfgPath, 'utf-8');
+  const slug = slugify(name);
+  // Remove any entry whose path ends with /<slug> or is the package name
+  const pattern = new RegExp(`\\{[^}]*path\\s*:\\s*['"][^'"]*${slug.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}[^'"]*['"][^}]*\\},?\\s*`, 'g');
+  const updated = raw.replace(pattern, '');
+  if (updated === raw) return false;
+  // Cleanup: "[, " → "[", ", ]" → "]"
+  const cleaned = updated
+    .replace(/\[\s*,\s*/g, '[')
+    .replace(/,\s*\]/g, ']')
+    .replace(/,\s*,/g, ',');
+  await writeFile(cfgPath, cleaned, 'utf-8');
+  return true;
+}
+
+export const description = 'Manage project plugins (new / install / remove / list)';
+export const usage = 'nexus plugin <subcommand> [...]';

package/src/commands/queue.ts

@@ -0,0 +1,145 @@
+/**
+ * nexus queue — process background jobs.
+ *
+ *   nexus queue:work [--queue <name>]   — start a worker that polls + runs jobs
+ *   nexus queue:retry <jobId>           — move a failed job back onto its queue
+ *
+ * Jobs live in apps/<backend>/src/jobs/*Job.ts. Workers poll the queue
+ * adapter from nexus-core's Job subsystem.
+ */
+import { resolve, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import type { CommandContext } from '../dispatcher.js';
+import type { Job, JobQueueAdapter, JobPayload } from '@bhooai/nexus-core';
+
+interface RegisteredJobClass {
+  name: string;
+  klass: new () => Job<never[]>;
+}
+
+const JOBS_SUBDIR = 'src/jobs';
+
+export async function runWork(ctx: CommandContext): Promise<void> {
+  const appName = (ctx.args.flags.app as string) ?? 'backend';
+  const queueFilter = ctx.args.flags.queue as string | undefined;
+  const projectRoot = process.cwd();
+  const jobsDir = join(projectRoot, 'apps', appName, JOBS_SUBDIR);
+
+  if (!existsSync(jobsDir)) {
+    console.error(`✗ No jobs directory: ${jobsDir}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const jobClasses = await loadJobs(jobsDir);
+  if (jobClasses.length === 0) {
+    console.log('(no jobs found)');
+    return;
+  }
+
+  // Build queue name -> jobs mapping
+  const byQueue = new Map<string, RegisteredJobClass[]>();
+  for (const j of jobClasses) {
+    const instance = new j.klass();
+    const q = (instance as Job).queue ?? 'default';
+    if (queueFilter && queueFilter !== q) continue;
+    if (!byQueue.has(q)) byQueue.set(q, []);
+    byQueue.get(q)!.push(j);
+  }
+
+  if (byQueue.size === 0) {
+    console.log(`(no jobs registered${queueFilter ? ` for queue "${queueFilter}"` : ''})`);
+    return;
+  }
+
+  console.log(`nexus queue:work — listening on queues: ${[...byQueue.keys()].join(', ')}`);
+  console.log(`Loaded ${jobClasses.length} job class(es). Ctrl+C to stop.\n`);
+
+  // The queue adapter lives in nexus-core; we need a shared instance.
+  // For now: instantiate a fresh InMemoryQueueAdapter (means the queue is
+  // process-local — production deployments should plug a Redis adapter and
+  // call this worker with the same adapter wired).
+  const { InMemoryQueueAdapter, configureQueue } = await import('@bhooai/nexus-core');
+  const adapter = new InMemoryQueueAdapter();
+  configureQueue(adapter);
+
+  let stopping = false;
+  process.on('SIGINT', () => { stopping = true; console.log('\nStopping...'); });
+  process.on('SIGTERM', () => { stopping = true; });
+
+  // Poll loop per queue
+  const workers = [...byQueue.entries()].map(([queue, jobs]) =>
+    workQueue(queue, jobs, adapter, () => stopping),
+  );
+  await Promise.all(workers);
+
+  console.log('Worker exited.');
+}
+
+async function loadJobs(jobsDir: string): Promise<RegisteredJobClass[]> {
+  const files = (await readdir(jobsDir)).filter((f) => f.endsWith('Job.ts') || f.endsWith('Job.js'));
+  const out: RegisteredJobClass[] = [];
+  for (const file of files) {
+    try {
+      const mod = await import(pathToFileURL(join(jobsDir, file)).href);
+      const klass = (mod as any).default ?? (mod as any)[Object.keys(mod)[0]!];
+      if (typeof klass === 'function') {
+        out.push({ name: file.replace(/\.(ts|js)$/, ''), klass });
+      }
+    } catch (err) {
+      console.warn(`! failed to load ${file}:`, err);
+    }
+  }
+  return out;
+}
+
+async function workQueue(
+  queue: string,
+  jobs: RegisteredJobClass[],
+  adapter: JobQueueAdapter,
+  isStopping: () => boolean,
+): Promise<void> {
+  while (!isStopping()) {
+    const payload = await adapter.dequeue(queue);
+    if (!payload) {
+      await sleep(500);
+      continue;
+    }
+
+    const target = jobs.find((j) => j.name === payload.args[0]);
+    if (!target) {
+      // Unknown job — put it back so another worker might handle it
+      await adapter.retry(payload as JobPayload, new Error('no handler'));
+      continue;
+    }
+
+    const instance = new target.klass();
+    try {
+      const args = payload.args.slice(1);
+      await (instance.handle as (...args: unknown[]) => Promise<void>)(...args);
+      console.log(`✓ ${target.name} (${payload.id})`);
+    } catch (err) {
+      if (payload.attempts < (instance.retries ?? 3)) {
+        console.warn(`↻ ${target.name} (${payload.id}) retry ${payload.attempts + 1}`);
+        await adapter.retry(payload, err);
+      } else {
+        console.error(`✗ ${target.name} (${payload.id}) failed permanently:`, err);
+        await adapter.fail(payload, err);
+      }
+    }
+  }
+}
+
+export async function runRetry(ctx: CommandContext): Promise<void> {
+  const jobId = ctx.args._[1];
+  console.log(`queue:retry ${jobId ?? '<missing>'} — requires a persistent adapter (Redis). Stub for now.`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export const description = 'Process background jobs';
+export const usage = 'nexus queue:<work|retry> [--queue <name>] [--app <backend>]';

package/src/commands/test.ts

@@ -0,0 +1,34 @@
+/**
+ * nexus test — run vitest (unit/integration) or playwright (e2e).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { CommandContext } from '../dispatcher.js';
+
+export async function run(ctx: CommandContext): Promise<void> {
+  const isE2e = !!ctx.args.flags.e2e;
+  const isWatch = !!ctx.args.flags.watch;
+  const projectRoot = process.cwd();
+
+  const cmd = isE2e
+    ? { bin: 'npx', args: ['playwright', 'test', ...(isWatch ? ['--ui'] : [])] }
+    : { bin: 'npx', args: ['vitest', ...(isWatch ? [] : ['run'])] };
+
+  // Sanity: make sure the test config exists
+  const configFile = isE2e ? 'playwright.config.ts' : 'vitest.workspace.ts';
+  if (!existsSync(resolve(projectRoot, configFile))) {
+    console.log(`No ${configFile} in ${projectRoot} — nothing to run.`);
+    console.log(`Generate one with \`nexus make:test-config\` (coming in P7).`);
+    return;
+  }
+
+  const code = await new Promise<number>((res) => {
+    const child = spawn(cmd.bin, cmd.args, { cwd: projectRoot, stdio: 'inherit', shell: true });
+    child.on('exit', (c) => res(c ?? 1));
+  });
+  process.exitCode = code;
+}
+
+export const description = 'Run tests (vitest by default, playwright with --e2e)';
+export const usage = 'nexus test [--watch] [--e2e]';

package/src/dispatcher.ts

@@ -0,0 +1,98 @@
+/**
+ * nexus CLI entry. Dispatches to per-command modules in ./commands/.
+ *
+ * Command modules export `run(argv: string[]): Promise<void>` and a static
+ * `description` for help output.
+ */
+import { parseArgs } from './util.js';
+import { closePrompts } from './prompts.js';
+
+export interface CommandContext {
+  argv: string[];
+  args: ReturnType<typeof parseArgs>;
+}
+
+export interface Command {
+  name: string;
+  description: string;
+  usage?: string;
+  run(ctx: CommandContext): Promise<void>;
+}
+
+const COMMANDS: Command[] = [];
+
+export function registerCommand(cmd: Command): void {
+  COMMANDS.push(cmd);
+}
+
+export async function run(cmd: string, argv: string[]): Promise<void> {
+  try {
+    if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+      printHelp();
+      return;
+    }
+    if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+      console.log('nexus v2.0.0');
+      return;
+    }
+    const found = COMMANDS.find((c) => c.name === cmd);
+    if (!found) {
+      console.error(`Unknown command: ${cmd}`);
+      printHelp();
+      process.exitCode = 1;
+      return;
+    }
+    await found.run({ argv, args: parseArgs(argv) });
+  } finally {
+    closePrompts();
+  }
+}
+
+function printHelp(): void {
+  console.log(`nexus — BhooAI Nexus CLI (v2)
+
+Usage: nexus <command> [options]
+
+Project lifecycle:
+  init [dir] [--example <name>] [--interactive]   Scaffold a new project
+  dev [--only a,b]                                 Start dev services
+  build [--target <app>|all]                       Build for production
+  test [--watch|--e2e]                             Run tests
+  doctor                                          Environment health check
+  sync [--check|--dry-run]                        Rewrite derived files
+  uninstall [--purge|--dry-run|--keep-db]         Remove project
+
+Maintenance:
+  down [--message "..."]                          Enable maintenance mode
+  up                                              Disable maintenance mode
+
+Queue + database:
+  db:seed [--class <name>]
+  db:migrate [--step N]
+  db:rollback [--step N]
+  queue:work [--queue <name>]
+  queue:retry <jobId>
+
+Multi-app scaffolding:
+  add backend <name>
+  add frontend <name> [--for <backend>]
+  add route <name> --app <backend>
+
+Generators (make:*):
+  make:route · make:controller · make:model · make:service · make:repository ·
+  make:middleware · make:validator · make:job · make:event · make:listener ·
+  make:policy · make:resource · make:request · make:mail · make:room ·
+  make:subgraph · make:seeder · make:migration · make:provider · make:plugin
+
+Plugins:
+  plugin new <name>
+  plugin install <pkg>
+  plugin remove <name>
+  plugin list
+
+Python AI:
+  pysetup [pkgs...]
+
+Run \`nexus <command> --help\` for command-specific flags (where implemented).
+`);
+}

package/src/generators.ts

@@ -0,0 +1,102 @@
+/**
+ * Generic make:* generators. Each generator knows:
+ *   - which folder it targets (under apps/<backend>/src/)
+ *   - the file suffix (e.g. Job.ts, Policy.ts, .room.ts)
+ *   - the content template to render
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import type { CommandContext } from './dispatcher.js';
+
+export interface GeneratorSpec {
+  /** Folder under apps/<backend>/src/. */
+  folder: string;
+  /** Filename suffix appended to the slug, e.g. "Job.ts" for jobs, ".room.ts" for ws. */
+  suffix: string;
+  /** Render the file content given the slug + class name. */
+  render(input: { slug: string; className: string; name: string }): string;
+  /** Create companion file(s) — e.g. a mailable also wants a template. */
+  companions?: CompanionSpec[];
+}
+
+export interface CompanionSpec {
+  relativePath: (input: { slug: string; className: string }) => string;
+  content: (input: { slug: string; className: string }) => string;
+}
+
+export function classNameFor(slug: string): string {
+  return slug
+    .split(/[-_]/)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('');
+}
+
+/** Convert a user-provided name (kebab, snake, CamelCase, spaces) to kebab slug. */
+export function slugFromName(name: string): string {
+  return name
+    .replace(/([a-z])([A-Z])/g, '$1-$2')      // split camelCase
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '')
+    .replace(/^-+|-+$/g, '');
+}
+
+/** Class-name (PascalCase) from any input. */
+export function pascalFromName(name: string): string {
+  return slugFromName(name)
+    .split(/-/)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('');
+}
+
+export function fileNameFor(slug: string, suffix: string): string {
+  // Slug starts with a dot, the slug gets appended before it:  slug + .room.ts
+  // Otherwise the slug is title-cased + suffix:                slugJob.ts
+  if (suffix.startsWith('.')) return `${slug}${suffix}`;
+  return `${slug}${suffix}`;
+}
+
+export async function runGenerator(ctx: CommandContext, spec: GeneratorSpec): Promise<void> {
+  const rawName = ctx.args._[0];
+  if (!rawName) {
+    console.error(`Usage: nexus make:<thing> <name> [--app <backend>]`);
+    process.exitCode = 1;
+    return;
+  }
+  const name = rawName;
+  const slug = slugFromName(name);
+  const className = pascalFromName(name);
+  const app = (ctx.args.flags.app as string) ?? 'backend';
+
+  const projectRoot = process.cwd();
+  const backendDir = join(projectRoot, 'apps', app);
+  if (!existsSync(backendDir)) {
+    console.error(`✗ Backend "${app}" not found. Run \`nexus add backend ${app}\` first, or pass --app.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const targetDir = resolve(backendDir, 'src', spec.folder);
+  await mkdir(targetDir, { recursive: true });
+  const targetPath = join(targetDir, fileNameFor(slug, spec.suffix));
+
+  if (existsSync(targetPath)) {
+    console.error(`✗ File already exists: ${targetPath}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await writeFile(targetPath, spec.render({ slug, className, name }), 'utf-8');
+  console.log(`✓ Created ${targetPath.replace(projectRoot + '\\', '')}`);
+
+  for (const c of spec.companions ?? []) {
+    const relPath = c.relativePath({ slug, className });
+    const compPath = join(backendDir, 'src', relPath);
+    await mkdir(resolve(compPath, '..'), { recursive: true });
+    if (!existsSync(compPath)) {
+      await writeFile(compPath, c.content({ slug, className }), 'utf-8');
+      console.log(`✓ Created ${compPath.replace(projectRoot + '\\', '')}`);
+    }
+  }
+}