create-arktos 1.5.0 → 2.0.0

package/cli/generator.js

@@ -0,0 +1,184 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'node:child_process';
+
+const GITIGNORE_CONTENT = `# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.database
+
+# Production build
+dist/
+build/
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Testing & Coverage
+coverage/
+.nyc_output/
+*.lcov
+
+# TypeScript cache
+*.tsbuildinfo
+
+# OS & Editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Prisma
+# Keep prisma schema and migrations in version control
+
+# Temporary files
+tmp/
+temp/
+*.tgz
+`;
+
+/**
+ * Filter out development, lock, and cache files from template copying.
+ */
+function shouldCopyFile(src, sourceDir) {
+  const relativePath = path.relative(sourceDir, src);
+  const fileName = path.basename(src);
+  const segments = relativePath.split(path.sep);
+
+  if (
+    segments.includes('node_modules') ||
+    segments.includes('dist') ||
+    segments.includes('build') ||
+    segments.includes('.turbo') ||
+    segments.includes('coverage')
+  ) {
+    return false;
+  }
+
+  const excludedFiles = [
+    '.DS_Store',
+    'Thumbs.db',
+    'ehthumbs.db',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'bun.lockb',
+    'bun.lock',
+  ];
+
+  if (excludedFiles.includes(fileName)) {
+    return false;
+  }
+
+  if (relativePath.endsWith('.tgz') || relativePath.endsWith('.tsbuildinfo')) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Copies the backend template into the target directory.
+ */
+export async function copyTemplateFiles(templatesDir, targetDir) {
+  const templateSourceDir = path.join(templatesDir, 'backend');
+
+  if (!(await fs.pathExists(templateSourceDir))) {
+    throw new Error(`Template not found at: ${templateSourceDir}`);
+  }
+
+  // Copy template files with filtering
+  await fs.copy(templateSourceDir, targetDir, {
+    filter: src => shouldCopyFile(src, templateSourceDir),
+  });
+
+  // Ensure clean .gitignore
+  await fs.writeFile(path.join(targetDir, '.gitignore'), GITIGNORE_CONTENT);
+
+  return true;
+}
+
+/**
+ * Normalizes and configures the generated project's package.json.
+ */
+export async function customizePackageJson(targetDir, projectName) {
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  if (!(await fs.pathExists(packageJsonPath))) {
+    throw new Error(`package.json not found in target directory: ${targetDir}`);
+  }
+
+  const packageJson = await fs.readJson(packageJsonPath);
+
+  packageJson.name = projectName;
+  packageJson.version = '0.1.0';
+  packageJson.private = true;
+  packageJson.description = `${projectName} - Production backend API built with Arktos`;
+
+  // Remove monorepo/cli internal fields if present
+  delete packageJson.bin;
+  delete packageJson.files;
+  delete packageJson.publishConfig;
+  delete packageJson.bugs;
+
+  await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+  return true;
+}
+
+/**
+ * Initializes a clean git repository with initial commit.
+ */
+export function initializeGit(targetDir) {
+  try {
+    execSync('git init', { cwd: targetDir, stdio: 'ignore', timeout: 8000 });
+    execSync('git add -A', { cwd: targetDir, stdio: 'ignore', timeout: 8000 });
+    execSync('git commit -m "feat: initial commit with Arktos"', {
+      cwd: targetDir,
+      stdio: 'ignore',
+      timeout: 8000,
+    });
+    return true;
+  } catch {
+    // Git might not be installed or configured, non-critical
+    return false;
+  }
+}
+
+/**
+ * Checks for updates on npm registry using native fetch with strict timeout.
+ */
+export async function checkForUpdates(currentVersion) {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 1500);
+
+    const response = await fetch('https://registry.npmjs.org/create-arktos/latest', {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      const data = await response.json();
+      if (data.version && data.version !== currentVersion) {
+        return data.version;
+      }
+    }
+  } catch {
+    // Offline or slow network, silently ignore
+  }
+
+  return null;
+}

package/cli/package-manager.js

@@ -0,0 +1,66 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * Modern package manager detection with pnpm-first priority,
+ * environment user-agent detection, and bun support.
+ */
+export async function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent;
+  if (userAgent) {
+    if (userAgent.startsWith('pnpm')) return 'pnpm';
+    if (userAgent.startsWith('bun')) return 'bun';
+    if (userAgent.startsWith('yarn')) return 'yarn';
+    if (userAgent.startsWith('npm')) return 'npm';
+  }
+
+  const managers = ['pnpm', 'bun', 'yarn', 'npm'];
+  for (const pm of managers) {
+    try {
+      execSync(`${pm} --version`, { stdio: 'ignore' });
+      return pm;
+    } catch {
+      // Not installed, try next
+    }
+  }
+
+  return 'pnpm';
+}
+
+export function getPackageManagerCommands(packageManager = 'pnpm') {
+  const commands = {
+    pnpm: {
+      install: 'pnpm install',
+      dev: 'pnpm dev',
+      build: 'pnpm build',
+      start: 'pnpm start',
+      migrate: 'pnpm dlx prisma migrate dev',
+      seed: 'pnpm db:seed',
+    },
+    bun: {
+      install: 'bun install',
+      dev: 'bun dev',
+      build: 'bun build',
+      start: 'bun start',
+      migrate: 'bunx prisma migrate dev',
+      seed: 'bun db:seed',
+    },
+    yarn: {
+      install: 'yarn',
+      dev: 'yarn dev',
+      build: 'yarn build',
+      start: 'yarn start',
+      migrate: 'yarn prisma migrate dev',
+      seed: 'yarn db:seed',
+    },
+    npm: {
+      install: 'npm install',
+      dev: 'npm run dev',
+      build: 'npm run build',
+      start: 'npm start',
+      migrate: 'npx prisma migrate dev',
+      seed: 'npm run db:seed',
+    },
+  };
+
+  return commands[packageManager] || commands.pnpm;
+}

package/cli/project-name.js

@@ -0,0 +1,179 @@
+export function normalizeProjectName(name) {
+  if (!name || typeof name !== 'string') {
+    return name
+  }
+
+  try {
+    let normalized = name.normalize('NFD')
+
+    const characterMap = {
+      ç: 'c',
+      Ç: 'C',
+      ğ: 'g',
+      Ğ: 'G',
+      ı: 'i',
+      İ: 'I',
+      ö: 'o',
+      Ö: 'O',
+      ş: 's',
+      Ş: 'S',
+      ü: 'u',
+      Ü: 'U',
+      á: 'a',
+      Á: 'A',
+      à: 'a',
+      À: 'A',
+      â: 'a',
+      Â: 'A',
+      é: 'e',
+      É: 'E',
+      è: 'e',
+      È: 'E',
+      ê: 'e',
+      Ê: 'E',
+      í: 'i',
+      Í: 'I',
+      ì: 'i',
+      Ì: 'I',
+      î: 'i',
+      Î: 'I',
+      ó: 'o',
+      Ó: 'O',
+      ò: 'o',
+      Ò: 'O',
+      ô: 'o',
+      Ô: 'O',
+      ú: 'u',
+      Ú: 'U',
+      ù: 'u',
+      Ù: 'U',
+      û: 'u',
+      Û: 'U',
+      ñ: 'n',
+      Ñ: 'N',
+    }
+
+    normalized = normalized.replace(/./g, (char) => characterMap[char] || char)
+    normalized = normalized.replace(/\p{Diacritic}/gu, '')
+
+    return normalized.normalize('NFC')
+  } catch {
+    const fallbackMap = {
+      ç: 'c',
+      Ç: 'C',
+      ğ: 'g',
+      Ğ: 'G',
+      ı: 'i',
+      İ: 'I',
+      ö: 'o',
+      Ö: 'O',
+      ş: 's',
+      Ş: 'S',
+      ü: 'u',
+      Ü: 'U',
+    }
+
+    return name.replace(/[çÇğĞıİöÖşŞüÜ]/g, (char) => fallbackMap[char] || char)
+  }
+}
+
+export function validateProjectName(name) {
+  const checks = [
+    {
+      test: name && name.trim() !== '',
+      message: 'Project name cannot be empty',
+      code: 'EMPTY_NAME',
+    },
+    {
+      test: name.length <= 50,
+      message: 'Project name cannot exceed 50 characters',
+      code: 'NAME_TOO_LONG',
+    },
+    {
+      test: name.length >= 1,
+      message: 'Project name must be at least 1 character long',
+      code: 'NAME_TOO_SHORT',
+    },
+    {
+      test: !/^\d/.test(name),
+      message: 'Project name cannot start with a number',
+      code: 'STARTS_WITH_NUMBER',
+    },
+    {
+      test: !name.includes(' '),
+      message: 'Project name cannot contain spaces',
+      code: 'CONTAINS_SPACE',
+    },
+    {
+      test: !/^[.-]/.test(name),
+      message: 'Project name cannot start with a dot or hyphen',
+      code: 'STARTS_WITH_SPECIAL',
+    },
+    {
+      test: !/[.-]$/.test(name),
+      message: 'Project name cannot end with a dot or hyphen',
+      code: 'ENDS_WITH_SPECIAL',
+    },
+  ]
+
+  for (const check of checks) {
+    if (!check.test) {
+      return {
+        isValid: false,
+        message: check.message,
+        code: check.code,
+      }
+    }
+  }
+
+  const normalizedName = normalizeProjectName(name)
+  const validationRegex = /^[a-zA-Z0-9._-]+$/
+  if (!validationRegex.test(normalizedName)) {
+    return {
+      isValid: false,
+      message: 'Project name can only contain letters, numbers, dots, hyphens, and underscores',
+      code: 'INVALID_CHARACTERS',
+    }
+  }
+
+  const reservedNames = [
+    'test',
+    'express',
+    'node_modules',
+    '.git',
+    'src',
+    'public',
+    'build',
+    'dist',
+    'coverage',
+    'prisma',
+    'api',
+    'root',
+    'admin',
+    'config',
+    'lib',
+    'bin',
+  ]
+
+  if (reservedNames.includes(normalizedName.toLowerCase())) {
+    return {
+      isValid: false,
+      message: `"${name}" is a reserved name, please choose another name`,
+      code: 'RESERVED_NAME',
+    }
+  }
+
+  const npmInvalidPatterns = [/^_/, /\s/, /[A-Z]/, /[@/]/]
+
+  for (const pattern of npmInvalidPatterns) {
+    if (pattern.test(normalizedName)) {
+      return {
+        isValid: false,
+        message: 'Project name must follow npm package naming conventions (lowercase, no spaces, no leading underscore)',
+        code: 'INVALID_NPM_NAME',
+      }
+    }
+  }
+
+  return { isValid: true, normalizedName }
+}

package/cli/ui.js

@@ -0,0 +1,54 @@
+import chalk from 'chalk'
+import prompts from 'prompts'
+import { validateProjectName } from './project-name.js'
+
+export function printBanner(version) {
+  console.log(`
+  ${chalk.blue.bold('❄️  ARKTOS')} ${chalk.dim(`v${version}`)}
+  ${chalk.gray('Production-ready Node.js & TypeScript Backend Generator')}
+  ${chalk.dim('Express • JWT • Prisma ORM • PostgreSQL • Resend')}
+`)
+}
+
+export async function promptProjectName(defaultName = 'my-arktos-api') {
+  const response = await prompts({
+    type: 'text',
+    name: 'projectName',
+    message: 'What is your backend project named?',
+    initial: defaultName,
+    validate: (val) => {
+      const res = validateProjectName(val)
+      return res.isValid ? true : res.message
+    },
+  })
+
+  return response.projectName
+}
+
+export async function promptOverwrite(targetDir) {
+  const response = await prompts({
+    type: 'confirm',
+    name: 'overwrite',
+    message: `Directory "${chalk.yellow(targetDir)}" already exists. Overwrite?`,
+    initial: false,
+  })
+
+  return Boolean(response.overwrite)
+}
+
+export function printSuccess({ projectName, targetDir, packageManager, commands }) {
+  console.log(`
+  ${chalk.green.bold('✔ Success!')} Created ${chalk.cyan.bold(projectName)} at ${chalk.dim(targetDir)}
+
+  ${chalk.bold('Next steps to get started:')}
+
+    ${chalk.cyan(`1. cd ${projectName}`)}
+    ${chalk.cyan(`2. cp .env.example .env`)}   ${chalk.dim('# Configure DATABASE_URL, JWT_SECRET, etc.')}
+    ${chalk.cyan(`3. ${commands.install}`)}
+    ${chalk.cyan(`4. ${commands.migrate}`)}  ${chalk.dim('# Run database migrations')}
+    ${chalk.cyan(`5. ${commands.seed}`)}     ${chalk.dim('# (Optional) Seed demo data')}
+    ${chalk.cyan(`6. ${commands.dev}`)}      ${chalk.dim('# Start dev server at http://localhost:3001')}
+
+  ${chalk.dim('Repository & issues:')} ${chalk.blue('https://github.com/zzafergok/arktos')}
+`)
+}

package/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import fs from 'fs-extra';
+import { program } from 'commander';
+import ora from 'ora';
+import chalk from 'chalk';
+
+import { normalizeProjectName, validateProjectName } from './cli/project-name.js';
+import { detectPackageManager, getPackageManagerCommands } from './cli/package-manager.js';
+import {
+  copyTemplateFiles,
+  customizePackageJson,
+  initializeGit,
+  checkForUpdates,
+} from './cli/generator.js';
+import { printBanner, promptProjectName, promptOverwrite, printSuccess } from './cli/ui.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+const { version: PACKAGE_VERSION } = require('./package.json');
+const templatesDir = path.join(__dirname, 'templates');
+
+program
+  .name('create-arktos')
+  .description('❄️  Arktos: Production-ready Node.js & TypeScript Backend Boilerplate Generator')
+  .version(PACKAGE_VERSION, '-v, --version')
+  .argument('[project-directory]', 'Target directory for the generated backend project')
+  .option('--skip-git', 'Skip git repository initialization')
+  .option('--skip-update-check', 'Skip checking for a newer version')
+  .option('--package-manager <pm>', 'Specify package manager (pnpm, bun, yarn, npm)')
+  .option('--verbose', 'Show detailed debug output')
+  .action(async (projectDirArg, options) => {
+    let updatePromise = null;
+    if (!options.skipUpdateCheck) {
+      updatePromise = checkForUpdates(PACKAGE_VERSION).catch(() => null);
+    }
+
+    try {
+      // 1. Resolve Project Name and Destination Directory
+      let projectName = null;
+      let targetDir = null;
+
+      if (projectDirArg) {
+        targetDir = path.resolve(process.cwd(), projectDirArg);
+        projectName = path.basename(targetDir);
+
+        const validation = validateProjectName(projectName);
+        if (!validation.isValid) {
+          console.error(
+            chalk.red(`\n✖ Invalid project name "${projectName}": ${validation.message}\n`)
+          );
+          process.exit(1);
+        }
+        if (validation.normalizedName && validation.normalizedName !== projectName) {
+          projectName = validation.normalizedName;
+          targetDir = path.join(path.dirname(targetDir), projectName);
+        }
+      } else {
+        printBanner(PACKAGE_VERSION);
+        const promptedName = await promptProjectName();
+        if (!promptedName) {
+          console.log(chalk.gray('\nOperation cancelled.\n'));
+          process.exit(0);
+        }
+        projectName = normalizeProjectName(promptedName);
+        targetDir = path.resolve(process.cwd(), projectName);
+      }
+
+      // 2. Check Directory Overwrite
+      if (await fs.pathExists(targetDir)) {
+        const existingFiles = await fs.readdir(targetDir);
+        if (existingFiles.length > 0) {
+          const shouldOverwrite = await promptOverwrite(projectName);
+          if (!shouldOverwrite) {
+            console.log(chalk.gray('\nOperation cancelled.\n'));
+            process.exit(0);
+          }
+          await fs.emptyDir(targetDir);
+        }
+      } else {
+        await fs.ensureDir(targetDir);
+      }
+
+      // 3. Scaffolding Pipeline
+      const spinner = ora({
+        text: `Creating ${chalk.cyan(projectName)}...`,
+      }).start();
+
+      // Copy template files
+      spinner.text = 'Scaffolding Arktos backend template...';
+      await copyTemplateFiles(templatesDir, targetDir);
+
+      // Normalize package.json
+      spinner.text = 'Configuring backend package.json...';
+      await customizePackageJson(targetDir, projectName);
+
+      // Initialize git repository
+      if (!options.skipGit) {
+        spinner.text = 'Initializing git repository...';
+        initializeGit(targetDir);
+      }
+
+      spinner.succeed(
+        chalk.green(`Arktos backend project "${chalk.bold(projectName)}" successfully created!`)
+      );
+
+      // 4. Detect Package Manager & Command Guidance
+      const packageManager = options.packageManager || (await detectPackageManager());
+      const commands = getPackageManagerCommands(packageManager);
+
+      printSuccess({
+        projectName,
+        targetDir,
+        packageManager,
+        commands,
+      });
+
+      // 5. Print Update Notification (if available)
+      if (updatePromise) {
+        const latestVersion = await updatePromise;
+        if (latestVersion) {
+          console.log(
+            chalk.yellow(
+              `  💡 A new version (v${latestVersion}) is available! Upgrade with: npm install -g create-arktos@latest\n`
+            )
+          );
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red(`\n✖ Project creation failed: ${error.message}\n`));
+      if (options.verbose && error.stack) {
+        console.error(chalk.dim(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+// Custom help layout
+program.on('--help', () => {
+  console.log(`
+${chalk.bold('Examples:')}
+  $ npx create-arktos my-api
+  $ pnpm create arktos my-api
+  $ npm create arktos my-api --skip-git
+  $ npx create-arktos my-api --package-manager bun
+`);
+});
+
+program.parse(process.argv);