@mars-stack/cli 0.2.0 → 1.0.2

package/template/scripts/ensure-db.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+
+/**
+ * Ensures a local database is available before starting development.
+ *
+ * Strategy (in order):
+ * 1. If DATABASE_URL connects to a reachable database, use it and sync schema.
+ * 2. Otherwise, start an embedded PostgreSQL via `prisma dev` (PGlite-powered).
+ *    No Docker. No installation. No external processes.
+ * 3. Sync the Prisma schema automatically.
+ */
+
+import { execSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+
+function log(icon, msg) {
+  console.log(`  ${icon}  ${msg}`);
+}
+
+function loadEnvFile() {
+  const envFiles = ['.env.development.local', '.env.development', '.env'];
+  for (const file of envFiles) {
+    const filePath = resolve(ROOT, file);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, 'utf-8');
+      for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1) continue;
+        const key = trimmed.slice(0, eqIdx);
+        let value = trimmed.slice(eqIdx + 1);
+        if (
+          (value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))
+        ) {
+          value = value.slice(1, -1);
+        }
+        if (!process.env[key]) {
+          process.env[key] = value;
+        }
+      }
+    }
+  }
+}
+
+function canConnectToDb() {
+  try {
+    execSync('npx prisma db execute --stdin <<< "SELECT 1"', {
+      cwd: ROOT,
+      stdio: 'ignore',
+      timeout: 8000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function pushSchema() {
+  try {
+    execSync('npx prisma db push --skip-generate --accept-data-loss', {
+      cwd: ROOT,
+      stdio: 'inherit',
+      timeout: 30000,
+      env: { ...process.env },
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getProjectName() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(resolve(ROOT, 'package.json'), 'utf-8'),
+    );
+    return (pkg.name || 'mars')
+      .replace(/^@[^/]+\//, '')
+      .replace(/[^a-z0-9-]/g, '-');
+  } catch {
+    return 'mars';
+  }
+}
+
+function stripAnsi(str) {
+  return str.replace(
+    /[\x1b\x9b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
+    '',
+  ).replace(/\]8;;[^\x1b]*/g, '');
+}
+
+function getPrismaDevTcpUrl(name) {
+  try {
+    const rawOutput = execSync('npx prisma dev ls 2>/dev/null', {
+      cwd: ROOT,
+      encoding: 'utf-8',
+      timeout: 15000,
+    });
+
+    const output = stripAnsi(rawOutput);
+    const isRunning = output.includes(name) && output.toLowerCase().includes('running');
+
+    // Extract the TCP postgres:// URL (not prisma+postgres://)
+    // Match postgres://...localhost:NNNNN/... with port in the 50000+ range (prisma dev default)
+    const tcpMatch = output.match(
+      /(?<![+])postgres:\/\/[^\s"]+localhost:\d+\/[^\s"]*/,
+    );
+    if (tcpMatch) {
+      // Clean up any trailing characters
+      const url = tcpMatch[0].replace(/[)\]}>]+$/, '');
+      return { running: isRunning, url };
+    }
+
+    return { running: isRunning, url: null };
+  } catch {
+    return { running: false, url: null };
+  }
+}
+
+function startPrismaDev(name) {
+  try {
+    const rawOutput = execSync(
+      `npx prisma dev --detach --name="${name}" 2>&1`,
+      { cwd: ROOT, encoding: 'utf-8', timeout: 30000 },
+    );
+
+    const output = stripAnsi(rawOutput);
+    const tcpMatch = output.match(
+      /(?<![+])postgres:\/\/[^\s"]+localhost:\d+\/[^\s"]*/,
+    );
+    return tcpMatch ? tcpMatch[0].replace(/[)\]}>]+$/, '') : null;
+  } catch {
+    return null;
+  }
+}
+
+function generateJwtSecret() {
+  try {
+    return execSync('openssl rand -hex 32', { encoding: 'utf-8' }).trim();
+  } catch {
+    return crypto.randomBytes(32).toString('hex');
+  }
+}
+
+function ensureJwtSecret() {
+  if (process.env.JWT_SECRET && process.env.JWT_SECRET.length >= 32) {
+    return;
+  }
+  const envLocalPath = resolve(ROOT, '.env.development.local');
+  let content = existsSync(envLocalPath) ? readFileSync(envLocalPath, 'utf-8') : '';
+  const secret = generateJwtSecret();
+  if (content.includes('JWT_SECRET=')) {
+    content = content.replace(/^JWT_SECRET=.*$/m, `JWT_SECRET="${secret}"`);
+  } else {
+    content += (content && !content.endsWith('\n') ? '\n' : '') + `# Required for auth (ensure-db)\nJWT_SECRET="${secret}"\n`;
+  }
+  writeFileSync(envLocalPath, content);
+  process.env.JWT_SECRET = secret;
+  log(`${GREEN}✓${RESET}`, `JWT_SECRET written to .env.development.local`);
+}
+
+function writeLocalDbUrl(url) {
+  const envLocalPath = resolve(ROOT, '.env.development.local');
+  let content = '';
+
+  if (existsSync(envLocalPath)) {
+    content = readFileSync(envLocalPath, 'utf-8');
+    if (content.includes('DATABASE_URL=')) {
+      content = content.replace(
+        /^DATABASE_URL=.*$/m,
+        `DATABASE_URL="${url}"`,
+      );
+      writeFileSync(envLocalPath, content);
+      return;
+    }
+  }
+
+  const addition = `${content ? '\n' : ''}# Auto-generated by ensure-db (prisma dev)\nDATABASE_URL="${url}"\n`;
+  writeFileSync(envLocalPath, content + addition);
+}
+
+async function main() {
+  console.log();
+  console.log(
+    `${BOLD}${CYAN}MARS${RESET} ${DIM}Ensuring database...${RESET}`,
+  );
+  console.log();
+
+  loadEnvFile();
+  ensureJwtSecret();
+
+  // 1. Check if existing DATABASE_URL works (skip if it's a prisma dev auto-URL)
+  const dbUrl = process.env.DATABASE_URL || '';
+  const isAutoUrl = dbUrl.includes('localhost:512') || dbUrl.includes('ensure-db');
+  if (dbUrl && !isAutoUrl) {
+    const connected = canConnectToDb();
+    if (connected) {
+      log(`${GREEN}✓${RESET}`, 'Database is reachable.');
+      log(`${CYAN}↓${RESET}`, 'Syncing schema...');
+      pushSchema();
+      log(`${GREEN}✓${RESET}`, 'Ready.');
+      console.log();
+      return;
+    }
+    log(
+      `${YELLOW}!${RESET}`,
+      `DATABASE_URL is set but not reachable. Starting embedded database.`,
+    );
+  }
+
+  // 2. Start or connect to embedded Postgres via prisma dev
+  const projectName = getProjectName();
+  const existing = getPrismaDevTcpUrl(projectName);
+
+  let tcpUrl = existing.url;
+
+  if (existing.running && tcpUrl) {
+    log(
+      `${GREEN}✓${RESET}`,
+      `Embedded Postgres "${projectName}" already running.`,
+    );
+  } else {
+    log(
+      `${CYAN}↓${RESET}`,
+      `Starting embedded Postgres via ${BOLD}prisma dev${RESET}...`,
+    );
+    const startUrl = startPrismaDev(projectName);
+
+    if (!startUrl) {
+      // Try to get the URL from ls (server may have started despite no URL in stdout)
+      const retry = getPrismaDevTcpUrl(projectName);
+      tcpUrl = retry.url;
+    } else {
+      tcpUrl = startUrl;
+    }
+
+    if (!tcpUrl) {
+      log(`${YELLOW}!${RESET}`, 'Could not start embedded database.');
+      log(
+        ' ',
+        `${DIM}The app will start anyway — UI preview works without a database.${RESET}`,
+      );
+      log(
+        ' ',
+        `${DIM}Set DATABASE_URL in .env to a cloud database (Neon, Supabase) to connect.${RESET}`,
+      );
+      console.log();
+      return;
+    }
+
+    log(`${GREEN}✓${RESET}`, `Embedded Postgres running.`);
+  }
+
+  // 3. Write the TCP connection URL to .env.development.local
+  writeLocalDbUrl(tcpUrl);
+  process.env.DATABASE_URL = tcpUrl;
+  log(`${GREEN}✓${RESET}`, `DATABASE_URL written to .env.development.local`);
+
+  // 4. Sync schema
+  log(`${CYAN}↓${RESET}`, 'Syncing schema...');
+  const pushed = pushSchema();
+  if (pushed) {
+    log(`${GREEN}✓${RESET}`, 'Database schema is up to date.');
+  } else {
+    log(
+      `${YELLOW}!${RESET}`,
+      `Schema push failed — run ${BOLD}yarn db:push${RESET} manually after startup.`,
+    );
+  }
+
+  console.log();
+}
+
+main().catch((err) => {
+  console.error('ensure-db failed:', err.message);
+});

package/template/scripts/generate-docs.ts

@@ -0,0 +1,143 @@
+/**
+ * Auto-generates documentation from the codebase.
+ * Outputs to docs/generated/ for snapshot comparison in CI.
+ *
+ * Usage: npx tsx scripts/generate-docs.ts
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ROOT = path.resolve(__dirname, '..');
+const OUTPUT_DIR = path.join(ROOT, 'docs', 'generated');
+
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function generateDbSchema(): string {
+  const schemaDir = path.join(ROOT, 'prisma', 'schema');
+  if (!fs.existsSync(schemaDir)) {
+    return '# Database Schema\n\nNo Prisma schema files found.\n';
+  }
+
+  const lines: string[] = [
+    '# Database Schema',
+    '',
+    'Auto-generated from `prisma/schema/` files.',
+    '',
+  ];
+
+  const schemaFiles = fs.readdirSync(schemaDir).filter((f) => f.endsWith('.prisma'));
+
+  for (const file of schemaFiles) {
+    const content = fs.readFileSync(path.join(schemaDir, file), 'utf-8');
+    const models = content.match(/model\s+(\w+)\s*\{[^}]*\}/g) || [];
+
+    if (models.length > 0) {
+      lines.push(`## ${file}`);
+      lines.push('');
+
+      for (const model of models) {
+        const nameMatch = model.match(/model\s+(\w+)/);
+        if (!nameMatch) continue;
+
+        lines.push(`### ${nameMatch[1]}`);
+        lines.push('');
+        lines.push('```prisma');
+        lines.push(model.trim());
+        lines.push('```');
+        lines.push('');
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function generateApiRoutes(): string {
+  const apiDir = path.join(ROOT, 'src', 'app', 'api');
+  if (!fs.existsSync(apiDir)) {
+    return '# API Routes\n\nNo API route directory found.\n';
+  }
+
+  const lines: string[] = [
+    '# API Routes',
+    '',
+    'Auto-generated from `src/app/api/` directory.',
+    '',
+    '| Endpoint | Methods | Auth Required |',
+    '|----------|---------|---------------|',
+  ];
+
+  function scanRoutes(dir: string, prefix: string): void {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        scanRoutes(path.join(dir, entry.name), `${prefix}/${entry.name}`);
+      } else if (entry.name === 'route.ts' || entry.name === 'route.tsx') {
+        const content = fs.readFileSync(path.join(dir, entry.name), 'utf-8');
+        const methods: string[] = [];
+        if (content.includes('export const GET') || content.includes('export async function GET')) methods.push('GET');
+        if (content.includes('export const POST') || content.includes('export async function POST')) methods.push('POST');
+        if (content.includes('export const PUT') || content.includes('export async function PUT')) methods.push('PUT');
+        if (content.includes('export const DELETE') || content.includes('export async function DELETE')) methods.push('DELETE');
+        if (content.includes('export const PATCH') || content.includes('export async function PATCH')) methods.push('PATCH');
+
+        const isProtected = prefix.includes('/protected') || content.includes('withAuth') || content.includes('withRole') || content.includes('withOwnership');
+
+        lines.push(`| \`/api${prefix}\` | ${methods.join(', ') || 'unknown'} | ${isProtected ? 'Yes' : 'No'} |`);
+      }
+    }
+  }
+
+  scanRoutes(apiDir, '');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function generateComponentMap(): string {
+  const lines: string[] = [
+    '# Component Map',
+    '',
+    'Auto-generated from `@mars-stack/ui` component exports.',
+    '',
+  ];
+
+  const categories = [
+    { name: 'Primitives', description: 'Atomic UI components with no business logic' },
+    { name: 'Patterns', description: 'Compositions of primitives, still no business logic' },
+  ];
+
+  for (const category of categories) {
+    lines.push(`## ${category.name}`);
+    lines.push('');
+    lines.push(category.description);
+    lines.push('');
+    lines.push('> Component list is populated from @mars-stack/ui exports. Run this script after installing dependencies.');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function main(): void {
+  ensureDir(OUTPUT_DIR);
+
+  const dbSchema = generateDbSchema();
+  fs.writeFileSync(path.join(OUTPUT_DIR, 'db-schema.md'), dbSchema);
+  console.log('Generated docs/generated/db-schema.md');
+
+  const apiRoutes = generateApiRoutes();
+  fs.writeFileSync(path.join(OUTPUT_DIR, 'api-routes.md'), apiRoutes);
+  console.log('Generated docs/generated/api-routes.md');
+
+  const componentMap = generateComponentMap();
+  fs.writeFileSync(path.join(OUTPUT_DIR, 'component-map.md'), componentMap);
+  console.log('Generated docs/generated/component-map.md');
+}
+
+main();

package/template/scripts/generate-env-example.ts

@@ -0,0 +1,89 @@
+/**
+ * Generates .env.example dynamically based on enabled features and services
+ * in app.config.ts. Only includes env vars that the current configuration needs.
+ *
+ * Run: `yarn generate:env` or `tsx scripts/generate-env-example.ts`
+ */
+import { writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+// Inline the config reading to avoid TSX path alias issues in scripts
+// In practice, this reads from the compiled config
+const featureEnvMap: Record<string, { vars: string[]; comment: string }> = {
+  // Core (always required)
+  _core: {
+    vars: ['DATABASE_URL', 'JWT_SECRET', 'NEXTAUTH_URL', 'NEXT_PUBLIC_APP_URL'],
+    comment: 'Core (always required)',
+  },
+  // Feature-specific
+  googleOAuth: {
+    vars: ['GOOGLE_CLIENT_ID', 'GOOGLE_CLIENT_SECRET'],
+    comment: 'Google OAuth',
+  },
+  billing: {
+    vars: ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET', 'NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY'],
+    comment: 'Stripe Billing',
+  },
+  analytics: {
+    vars: ['NEXT_PUBLIC_ANALYTICS_ID'],
+    comment: 'Analytics',
+  },
+  sentry: {
+    vars: ['SENTRY_DSN', 'SENTRY_AUTH_TOKEN'],
+    comment: 'Sentry Monitoring',
+  },
+  ai: {
+    vars: ['OPENAI_API_KEY'],
+    comment: 'AI Provider',
+  },
+};
+
+const _serviceEnvMap: Record<string, { vars: string[]; comment: string }> = {
+  sendgrid: {
+    vars: ['SENDGRID_API_KEY', 'EMAIL_FROM'],
+    comment: 'SendGrid Email',
+  },
+  resend: {
+    vars: ['RESEND_API_KEY', 'EMAIL_FROM'],
+    comment: 'Resend Email',
+  },
+  s3: {
+    vars: ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_S3_BUCKET', 'AWS_REGION'],
+    comment: 'AWS S3 Storage',
+  },
+  vercel_storage: {
+    vars: ['BLOB_READ_WRITE_TOKEN'],
+    comment: 'Vercel Blob Storage',
+  },
+};
+
+function generateEnvExample(): string {
+  const lines: string[] = [
+    '# MARS Environment Variables',
+    '# Generated from app.config.ts -- only includes vars for enabled features',
+    `# Generated at: ${new Date().toISOString()}`,
+    '',
+  ];
+
+  // Always include core vars
+  const core = featureEnvMap._core;
+  lines.push(`# ${core.comment}`);
+  core.vars.forEach((v) => lines.push(`${v}=`));
+  lines.push('');
+
+  // Redis (always included for rate limiting)
+  lines.push('# Redis (rate limiting + caching)');
+  lines.push('UPSTASH_REDIS_REST_URL=');
+  lines.push('UPSTASH_REDIS_REST_TOKEN=');
+  lines.push('');
+
+  lines.push('# Add feature-specific env vars by enabling features in app.config.ts');
+  lines.push('# Then run: yarn generate:env');
+
+  return lines.join('\n') + '\n';
+}
+
+const output = generateEnvExample();
+const outputPath = resolve(process.cwd(), '.env.example');
+writeFileSync(outputPath, output);
+console.log(`Generated .env.example with core vars`);

package/template/scripts/seed.ts

@@ -0,0 +1,56 @@
+import { PrismaClient } from '../prisma/generated/prisma/client.js';
+import { PrismaPg } from '@prisma/adapter-pg';
+import { hashPassword } from '@mars-stack/core/auth/password';
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL!,
+});
+const prisma = new PrismaClient({ adapter });
+
+const DEFAULT_PASSWORD = 'Password123!';
+
+interface SeedUser {
+  email: string;
+  name: string;
+  role: string;
+}
+
+const seedUsers: SeedUser[] = [
+  { email: 'admin@example.com', name: 'Admin', role: 'admin' },
+  { email: 'user@example.com', name: 'Test User', role: 'user' },
+];
+
+async function seed() {
+  console.log('🌱 Seeding database...\n');
+
+  const hashedPassword = await hashPassword(DEFAULT_PASSWORD);
+  const now = new Date();
+
+  for (const { email, name, role } of seedUsers) {
+    const user = await prisma.user.upsert({
+      where: { email },
+      update: { name, role },
+      create: {
+        email,
+        name,
+        password: hashedPassword,
+        role,
+        emailVerified: now,
+      },
+    });
+
+    console.log(`  ✔ ${role} user: ${user.email} (id: ${user.id})`);
+  }
+
+  console.log('\n✅ Seed complete.');
+  console.log(`   Default password for all users: ${DEFAULT_PASSWORD}`);
+}
+
+seed()
+  .catch((error: unknown) => {
+    console.error('❌ Seed failed:', error);
+    process.exit(1);
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });