@cellajs/create-cella 0.1.7 → 0.2.0

package/src/create.ts

@@ -1,193 +1,114 @@
-import { mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import colors from 'picocolors';
+import { cp, mkdir } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
 import { downloadTemplate } from 'giget';
-import yoctoSpinner from 'yocto-spinner';
-
-import { TEMPLATE_URL } from './constants.ts';
-
-import { install, generate } from './utils/run-package-manager-command.ts';
-import { cleanTemplate } from './utils/clean-template.ts';
-import { runGitCommand } from './utils/run-git-command.ts';
-import { addRemote } from './add-remote.ts';
-
-interface CreateOptions {
-  projectName: string;
-  targetFolder: string;
-  newBranchName?: string | null;
-  skipInstall: boolean;
-  skipGit: boolean;
-  skipClean: boolean;
-  skipGenerate: boolean;
-  packageManager: string;
+import { addRemote } from '#/add-remote';
+import { getPortEdits, TEMPLATE_URL } from '#/constants';
+import { type CreateOptions, showSuccess } from '#/modules/cli';
+import { cleanTemplate } from '#/utils/clean-template';
+import { gitAddAll, gitBranch, gitCheckout, gitCommit, gitInit } from '#/utils/git';
+import { createProgress } from '#/utils/progress';
+import { generate, install } from '#/utils/run-package-manager-command';
+
+/** Check if a path is a local directory */
+function isLocalPath(path: string): boolean {
+  return path.startsWith('/') || path.startsWith('./') || path.startsWith('../');
 }
 
 export async function create({
   projectName,
   targetFolder,
   newBranchName,
-  skipInstall,
-  skipGit,
-  skipClean,
-  skipGenerate,
   packageManager,
+  templateUrl,
+  portOffset = 0,
+  silent = false,
 }: CreateOptions): Promise<void> {
   // Save the original working directory
   const originalCwd = process.cwd();
 
-  console.info();
-
-  // Create the target folder if it doesn't exist
-  const createFolderSpinner = yoctoSpinner({
-    text: 'Creating project folder',
-  }).start();
-
-  await mkdir(targetFolder, { recursive: true });
-  process.chdir(targetFolder);
-
-  createFolderSpinner.success('Project folder created');
-
-  // Download the template from the specified URL
-  const downloadSpinner = yoctoSpinner({
-    text: 'Downloading `cella` template',
-  }).start();
-
-  await downloadTemplate(TEMPLATE_URL, {
-    cwd: process.cwd(),
-    dir: targetFolder,
-    force: true,
-    provider: 'github',
-  });
-
-  downloadSpinner.success('`cella` template downloaded');
-
-  // Clean the template if the skipClean flag is not set
-  if (!skipClean) {
-    const cleanSpinner = yoctoSpinner({
-      text: 'cleaning `cella` template',
-    }).start();
+  // Use custom template or default
+  const template = templateUrl || TEMPLATE_URL;
+  const isLocalTemplate = templateUrl && isLocalPath(templateUrl);
+
+  const progress = createProgress('creating project', silent);
+
+  try {
+    // Create the target folder
+    progress.step('creating project folder');
+    await mkdir(targetFolder, { recursive: true });
+    process.chdir(targetFolder);
+
+    // Download or copy the template
+    if (isLocalTemplate) {
+      progress.step('copying local template');
+      const sourcePath = resolve(originalCwd, templateUrl);
+
+      // Check if target is inside source (would cause EINVAL)
+      if (targetFolder.startsWith(sourcePath)) {
+        throw new Error(
+          `Cannot create project inside the template directory.\n` +
+            `  Run from outside: cd ~ && pnpm create @cellajs/cella ${projectName} --template ${templateUrl}`,
+        );
+      }
 
-    try {
-      await cleanTemplate({
-        targetFolder,
-        projectName,
+      await cp(sourcePath, targetFolder, {
+        recursive: true,
+        filter: (src) => !src.includes('node_modules') && !src.includes('.git'),
+      });
+    } else {
+      progress.step('downloading cella template');
+      await downloadTemplate(template, {
+        cwd: process.cwd(),
+        dir: targetFolder,
+        force: true,
+        provider: 'github',
       });
-      cleanSpinner.success('`cella` template cleaned');
-    } catch (e) {
-      console.error(e);
-      cleanSpinner.error('Failed to clean `cella` template');
-      process.exit(1);
     }
-  } else {
-    console.info(`${colors.yellow('⚠')} --skip-clean > Skip cleaning \`cella\` template`);
-  }
 
-  // Install dependencies if the skipInstall flag is not set
-  if (!skipInstall) {
-    const installSpinner = yoctoSpinner({
-      text: 'installing dependencies',
-    }).start();
-
-    try {
-      await install(packageManager);
-      installSpinner.success('Dependencies installed');
-    } catch (e) {
-      console.error(e);
-      installSpinner.error('Failed to install dependencies');
-      process.exit(1);
-    }
-  } else {
-    console.info(`${colors.yellow('⚠')} --skip-install > Skip installing dependencies`);
-  }
+    // Clean the template and apply port offsets
+    progress.step('cleaning template');
+    const extraEdits = getPortEdits(projectName, portOffset);
+    await cleanTemplate({ targetFolder, extraEdits });
 
-  // Generate SQL files if the skipGenerate flag is not set
-  if (!skipGenerate) {
-    const generateSpinner = yoctoSpinner({
-      text: 'generating SQL files',
-    }).start();
-
-    try {
-      await generate(packageManager);
-      generateSpinner.success('SQL files generated');
-    } catch (e) {
-      console.error(e);
-      generateSpinner.error('Failed to generate SQL files');
-      process.exit(1);
-    }
-  } else {
-    console.info(`${colors.yellow('⚠')} --skip-generate > Skip generating SQL files`);
-  }
+    // Install dependencies
+    progress.step('installing dependencies');
+    await install(packageManager);
 
-  // Initialize Git repository if skipGit flag is not set
-  if (!skipGit) {
-    const gitSpinner = yoctoSpinner({
-      text: 'initializing git repository',
-    }).start();
+    // Generate SQL files
+    progress.step('generating migrations');
+    await generate(packageManager);
 
+    // Initialize git repository
     const gitFolderPath = join(targetFolder, '.git');
-
     if (!existsSync(gitFolderPath)) {
-      try {
-        // Run Git commands to initialize the repository and make the first commit
-        await runGitCommand({ targetFolder, command: 'init' });
-        await runGitCommand({ targetFolder, command: 'add .' });
-        await runGitCommand({ targetFolder, command: 'commit -m "Initial commit"' });
-
-        // If a new branch name is specified, create and checkout the branch
-        if (newBranchName) {
-          await runGitCommand({ targetFolder, command: `branch ${newBranchName}` });
-          await runGitCommand({ targetFolder, command: `checkout ${newBranchName}` });
-          gitSpinner.success(`Git repository initialized, initial commit created, and new branch ${newBranchName} created`);
-        } else {
-          gitSpinner.success('Git repository initialized and initial commit created');
-        }
-      } catch (e) {
-        console.error(e);
-        gitSpinner.error('Failed to initialize Git repository or create branch');
-        process.exit(1);
+      progress.step('initializing git');
+      await gitInit(targetFolder);
+      await gitAddAll(targetFolder);
+      await gitCommit(targetFolder, 'Initial commit');
+
+      if (newBranchName) {
+        progress.step(`creating branch '${newBranchName}'`);
+        await gitBranch(targetFolder, newBranchName);
+        await gitCheckout(targetFolder, newBranchName);
       }
-    } else {
-      gitSpinner.warning('Git repository already initialized > Skip git init');
     }
-  } else {
-    console.info(`${colors.yellow('⚠')} --skip-git > Skip git init`);
-  }
 
-  // Add Cella as upstream remote
-  await addRemote({ targetFolder });
+    // Add upstream remote
+    progress.step('adding upstream remote');
+    await addRemote({ targetFolder, silent: true });
 
-  // Final success message indicating project creation
-  console.info();
-  console.info(`${colors.green('Success')} Created ${projectName} at ${targetFolder}`);
-  console.info();
+    // Done
+    progress.done(`created ${projectName}`);
+  } catch (error) {
+    progress.fail(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
 
   // Check if the working directory needs to be changed
   const needsCd = originalCwd !== targetFolder;
   const relativePath = relative(originalCwd, targetFolder);
 
-  if (needsCd) {
-    // Calculate the relative path between the original working directory and the target folder
-    console.info('now go to your project using:');
-    console.info(colors.cyan(`  cd ${relativePath}`)); // Adding './' to make it clear it's a relative path
-    console.info();
-  }
-
-  console.info(`${needsCd ? 'then ' : ''}quick start using pglite with:`);
-  console.info(colors.cyan(`  ${packageManager} quick`));
-  console.info();
-
-  console.info('Already have docker installed? Then you can run a full setup:');
-  console.info(colors.cyan(`  ${packageManager} docker`));
-  console.info(colors.cyan(`  ${packageManager} dev`));
-  console.info(colors.cyan(`  ${packageManager} seed`));
-  console.info();
-
-  console.info(`Once running, you can sign in using:`);
-  console.info(`email: ${colors.greenBright('admin-test@cellajs.com')}`);
-  console.info(`password: ${colors.greenBright('12345678')}`);
-  console.info();
-  console.info(`For more info, check out: ${relativePath}/README.md`);
-  console.info(`Enjoy building ${projectName} using cella! 🎉`);
-  console.info();
+  // Display final success message
+  showSuccess(projectName, targetFolder, relativePath, needsCd, packageManager);
 }

package/src/modules/cli/commands.ts

@@ -0,0 +1,58 @@
+import { basename, resolve } from 'node:path';
+import { Command, InvalidArgumentError } from 'commander';
+
+import { NAME, VERSION } from '#/constants';
+import { validateProjectName } from '#/utils/validate-project-name';
+import type { CLIConfig, CLIOptions } from './types';
+
+// Initialize CLI variables
+let directory: string | null = null;
+let newBranchName: string | null = null;
+const packageManager = 'pnpm';
+
+/**
+ * Defines the root CLI command using Commander.
+ * This command accepts CLI options and validates user input.
+ */
+export const command = new Command(NAME)
+  .version(VERSION, '-v, --version', `output the current version of ${NAME}`)
+  .argument('[directory]', 'the directory name for the new project')
+  .usage('[directory] [options]')
+  .helpOption('-h, --help', 'display this help message')
+  .option('--template <path>', 'use a custom template (local path or github:user/repo)')
+  .action((name: string) => {
+    if (typeof name === 'string') {
+      name = name.trim();
+    }
+
+    if (name) {
+      const validation = validateProjectName(basename(resolve(name)));
+
+      if (!validation.valid) {
+        throw new InvalidArgumentError(`Invalid project name: ${validation.problems?.[0] ?? 'unknown error'}`);
+      }
+
+      directory = name;
+    }
+  })
+  .parse();
+
+// Gather the CLI options and arguments
+const options: CLIOptions = command.opts<CLIOptions>();
+
+/**
+ * Runs the CLI and returns the parsed configuration.
+ * This function parses command line arguments and returns the CLI config.
+ */
+export function runCli(): CLIConfig {
+  return {
+    options,
+    args: command.args,
+    directory,
+    newBranchName,
+    packageManager,
+  };
+}
+
+// Export CLI configuration for direct import
+export const cli: CLIConfig = runCli();

package/src/modules/cli/display.ts

@@ -0,0 +1,62 @@
+import pc from 'picocolors';
+
+import { DESCRIPTION, DIVIDER, getHeaderLine } from '#/constants';
+
+/** ASCII art logo for the CLI welcome screen. */
+function showAscii(): void {
+  console.info(pc.cyan('                      _ _            '));
+  console.info(pc.cyan('▒▓█████▓▒     ___ ___| | | __ _      '));
+  console.info(pc.cyan('▒▓█   █▓▒    / __/ _ \\ | |/ _` |    '));
+  console.info(pc.cyan('▒▓█   █▓▒   | (_|  __/ | | (_| |     '));
+  console.info(pc.cyan('▒▓█████▓▒    \\___\\___|_|_|\\__,_|  '));
+}
+
+/**
+ * Displays the compact CLI welcome header.
+ * @param templateVersion - The version of the cella template being used
+ */
+export function showWelcome(templateVersion: string): void {
+  console.info();
+  showAscii();
+  console.info();
+  console.info(pc.dim(DESCRIPTION));
+  console.info();
+  console.info(getHeaderLine(templateVersion));
+  console.info(DIVIDER);
+}
+
+/**
+ * Displays the final success message after project creation.
+ */
+export function showSuccess(
+  projectName: string,
+  _targetFolder: string,
+  relativePath: string,
+  needsCd: boolean,
+  packageManager: string,
+): void {
+  console.info(DIVIDER);
+  console.info();
+
+  // Navigation instruction
+  if (needsCd) {
+    console.info(`${pc.green('→')} cd ${pc.cyan(relativePath)}`);
+    console.info();
+  }
+
+  // Quick start options
+  console.info(`${pc.green('→')} ${pc.cyan(`${packageManager} quick`)}       ${pc.gray('(pglite, no docker)')}`);
+  console.info();
+  console.info(pc.gray('or, for full setup:'));
+  console.info();
+  console.info(
+    `${pc.green('→')} ${pc.cyan(`${packageManager} docker`)} ${pc.dim('&&')} ${pc.cyan(`${packageManager} seed`)} ${pc.dim('&&')} ${pc.cyan(`${packageManager} dev`)}`,
+  );
+  console.info();
+
+  // Credentials
+  console.info(`sign in: ${pc.gray('admin-test@cellajs.com / 12345678')}`);
+  console.info();
+  console.info(`enjoy building ${pc.green(projectName)} with cella!`);
+  console.info();
+}

package/src/modules/cli/index.ts

@@ -0,0 +1,3 @@
+export { cli, command, runCli } from './commands';
+export { showSuccess, showWelcome } from './display';
+export type { AddRemoteOptions, CLIConfig, CLIOptions, CreateOptions } from './types';

package/src/modules/cli/types.ts

@@ -0,0 +1,35 @@
+/** CLI options parsed from command line arguments */
+export interface CLIOptions {
+  template?: string;
+}
+
+/** CLI configuration state */
+export interface CLIConfig {
+  options: CLIOptions;
+  args: string[];
+  directory: string | null;
+  newBranchName: string | null;
+  packageManager: string;
+}
+
+/** Options for creating a new project */
+export interface CreateOptions {
+  projectName: string;
+  targetFolder: string;
+  newBranchName?: string | null;
+  packageManager: string;
+  templateUrl?: string;
+  /** Port offset to avoid collisions with sibling forks (0 = default ports) */
+  portOffset?: number;
+  /** Suppress all output (for testing) */
+  silent?: boolean;
+}
+
+/** Options for adding a remote to the repository */
+export interface AddRemoteOptions {
+  targetFolder: string;
+  remoteUrl?: string;
+  remoteName?: string;
+  /** If true, don't throw on failure */
+  silent?: boolean;
+}

package/src/utils/clean-template.ts

@@ -1,19 +1,19 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import colors from 'picocolors';
+import pc from 'picocolors';
 
-import { TO_CLEAN, TO_REMOVE, TO_COPY, TO_EDIT } from '../constants.ts';
+import { type FileEdit, TO_CLEAN, TO_COPY, TO_EDIT, TO_REMOVE } from '#/constants';
 
 /**
  * Cleans the specified template by removing designated folders and files.
- * @param params - Parameters containing the target folder and project name.
+ * @param params - Parameters containing the target folder and optional extra edits.
  */
 export async function cleanTemplate({
   targetFolder,
-  projectName,
+  extraEdits = {},
 }: {
   targetFolder: string;
-  projectName: string;
+  extraEdits?: Record<string, FileEdit[]>;
 }): Promise<void> {
   // Change the current working directory to targetFolder if not already set
   if (process.cwd() !== targetFolder) {
@@ -34,7 +34,7 @@ export async function cleanTemplate({
         TO_CLEAN.map((folderPath) => {
           const absolutePath = path.resolve(targetFolder, folderPath);
           return removeFolderContents(absolutePath);
-        })
+        }),
       );
 
       // Remove specified files and folders
@@ -42,14 +42,21 @@ export async function cleanTemplate({
         TO_REMOVE.map((filePath) => {
           const absolutePath = path.resolve(targetFolder, filePath);
           return removeFileOrFolder(absolutePath);
-        })
+        }),
       );
 
+      // Merge static edits with extra edits (e.g., port offsets)
+      const allEdits = { ...TO_EDIT };
+      for (const [filePath, edits] of Object.entries(extraEdits)) {
+        allEdits[filePath] = [...(allEdits[filePath] || []), ...edits];
+      }
+
       // Edit specific files
-      await Promise.all(Object.entries(TO_EDIT).map(async ([filePath, edits]) => {
+      await Promise.all(
+        Object.entries(allEdits).map(async ([filePath, edits]) => {
           const absolutePath = path.resolve(targetFolder, filePath);
           await editFile(absolutePath, edits);
-        })
+        }),
       );
 
       resolve();
@@ -81,7 +88,7 @@ export async function removeFolderContents(folderPath: string): Promise<void> {
         // If it's a file, remove it
         await fs.rm(filePath);
       }
-    })
+    }),
   );
 }
 
@@ -110,7 +117,7 @@ export async function copyFile(src: string, dest: string): Promise<void> {
     await fs.copyFile(src, dest);
   } catch (err: any) {
     if (err.code === 'ENOENT') {
-      console.info(`\n${colors.yellow('⚠')} Source file "${src}" does not exist > Skip copy`);
+      console.info(`\n${pc.yellow('⚠')} Source file "${src}" does not exist > Skip copy`);
     } else {
       throw err;
     }
@@ -122,7 +129,10 @@ export async function copyFile(src: string, dest: string): Promise<void> {
  * @param filePath - The path of the file to edit.
  * @param edits - The list of edits to apply.
  */
-export async function editFile(filePath: string, edits: Array<{regexMatch: RegExp; replaceWith: string }>): Promise<void> {
+export async function editFile(
+  filePath: string,
+  edits: Array<{ regexMatch: RegExp; replaceWith: string }>,
+): Promise<void> {
   try {
     await fs.access(filePath);
 
@@ -139,12 +149,11 @@ export async function editFile(filePath: string, edits: Array<{regexMatch: RegEx
     if (fileContent !== updatedContent) {
       await fs.writeFile(filePath, updatedContent, 'utf8');
     }
-
   } catch (err: any) {
     if (err.code === 'ENOENT') {
-      console.info(`\n${colors.yellow('⚠')} Source file "${filePath}" does not exist > Skip edit`);
+      console.info(`\n${pc.yellow('⚠')} Source file "${filePath}" does not exist > Skip edit`);
     } else {
       throw err;
     }
   }
-}
+}

package/src/utils/detect-used-ports.ts

@@ -0,0 +1,57 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+interface UsedPorts {
+  project: string;
+  frontend: number;
+  backend: number;
+  offset: number;
+}
+
+/**
+ * Scan sibling directories for existing cella forks and extract their dev ports.
+ * Looks for `shared/development-config.ts` to identify cella-based projects.
+ */
+export async function detectUsedPorts(targetFolder: string): Promise<UsedPorts[]> {
+  const parentDir = dirname(targetFolder);
+  const used: UsedPorts[] = [];
+
+  let siblings: string[];
+  try {
+    siblings = await readdir(parentDir);
+  } catch {
+    return used;
+  }
+
+  for (const name of siblings) {
+    const configPath = join(parentDir, name, 'shared/development-config.ts');
+    try {
+      const content = await readFile(configPath, 'utf8');
+      const feMatch = content.match(/frontendUrl:\s*'http:\/\/localhost:(\d+)'/);
+      const beMatch = content.match(/backendUrl:\s*'http:\/\/localhost:(\d+)'/);
+      if (feMatch && beMatch) {
+        const frontend = Number(feMatch[1]);
+        const backend = Number(beMatch[1]);
+        used.push({
+          project: name,
+          frontend,
+          backend,
+          offset: frontend - 3000,
+        });
+      }
+    } catch {
+      // Not a cella fork, skip
+    }
+  }
+
+  return used;
+}
+
+/** Find the next available offset (in steps of 10) that doesn't collide with existing forks. */
+export function findNextOffset(usedPorts: UsedPorts[]): number {
+  const usedOffsets = new Set(usedPorts.map((p) => p.offset));
+  for (let offset = 0; offset <= 490; offset += 10) {
+    if (!usedOffsets.has(offset)) return offset;
+  }
+  return 0;
+}

package/src/utils/extract-package-json-version-from-uri.ts

@@ -3,15 +3,15 @@ import axios from 'axios';
 /**
  * Retrieves the version from the package.json file of a GitHub repository.
  * If the package.json file is not found or an error occurs, it returns 'unknown'.
- * 
+ *
  * @param repositoryUrl {string} - The GitHub repository URL in the format 'github:user/repo'.
  * @param branch {string} - The branch name (defaults to 'main').
  * @returns {Promise<string>} - The version from the package.json file.
  */
-export async function extractPackageJsonVersionFromUri(repositoryUrl: string, branch: string = 'main'): Promise<string> {
+export async function extractPackageJsonVersionFromUri(repositoryUrl: string, branch = 'main'): Promise<string> {
   // Extract owner and repo from the URL
   const [owner, repo] = repositoryUrl.replace('github:', '').split('/');
-  
+
   // Construct the URL for the package.json file in the provided branch
   const packageJsonUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/package.json`;
 
@@ -19,11 +19,11 @@ export async function extractPackageJsonVersionFromUri(repositoryUrl: string, br
     // Fetch the package.json file
     const response = await axios.get(packageJsonUrl);
     const packageJson = response.data;
-    
+
     // Return the version from the package.json, or 'unknown' if not found
     return packageJson.version || 'unknown';
   } catch (error) {
     // If there's an error (file not found, etc.), return 'unknown'
     return 'unknown';
   }
-}
+}