@cellajs/create-cella 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CellaJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import './src/index.js';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cellajs/create-cella",
+  "version": "0.0.2",
+  "private": false,
+  "license": "MIT",
+  "description": "Intuivive TypeScript template to build local-first web apps. Implementation-ready. MIT license.",
+  "keywords": [
+    "template",
+    "monorepo",
+    "fullstack",
+    "typescript",
+    "hono",
+    "drizzle",
+    "shadcn",
+    "postgres",
+    "react",
+    "vite",
+    "pwa",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cellajs/cella",
+    "directory": "cli/create-cella"
+  },
+  "homepage": "https://cellajs.com",
+  "author": "CellaJS <info@cellajs.com>",
+  "engines": {
+    "node": ">=20.14.0"
+  },
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "create-cella": "index.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^6.0.1",
+    "commander": "^12.1.0",
+    "cross-spawn": "^7.0.3",
+    "giget": "^1.2.3",
+    "picocolors": "^1.1.0",
+    "validate-npm-package-name": "^5.0.1",
+    "yocto-spinner": "^0.1.0"
+  },
+  "scripts": {
+    "create": "node index.js"
+  }
+}

package/src/cli.js

@@ -0,0 +1,88 @@
+import { basename, resolve } from 'node:path'
+import { Command, InvalidArgumentError } from 'commander'
+
+import { NAME } from './constants.js'
+
+import { packageJson } from './utils/package-json.js'
+import { validateProjectName } from './utils/validate-project-name.js'
+
+// Initialize CLI variables
+let directory = null;
+let newBranchName = null;
+let createNewBranch = null;
+const packageManager = 'pnpm';
+
+// Set up the CLI command using Commander
+export const command = new Command(NAME)
+  .version(packageJson.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(
+    '--skip-new-branch',
+    'Skip creating a new branch during initialization.',
+    false,
+  )
+  .option(
+    '--skip-install',
+    'Skip the installation of packages.',
+    false,
+  )
+  .option(
+    '--skip-clean',
+    'Skip cleaning the `cella` template.',
+    false,
+  )
+  .option(
+    '--skip-git',
+    'Skip initializing a git repository.',
+    false,
+  )
+  .option(
+      '--new-branch-name <name>',
+      'Specify a new branch name to create and use.',
+      (name) => {
+        if (typeof name === 'string') {
+          name = name.trim();
+        }
+
+        if (name) {
+          const validation = validateProjectName(basename(resolve(name)))
+          if (!validation.valid) throw new InvalidArgumentError(`Invalid branch name: ${validation.problems[0]}`);
+
+          createNewBranch = true;
+          newBranchName = name;
+        }
+      },
+  )
+  .action((name) => {
+      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]}`);
+
+        directory = name;
+      }
+    })
+  .parse();
+
+// Gather the CLI options and arguments
+const options = command.opts({ 
+  skipNewBranch: false, 
+  skipClean: false,
+  skipGit: false, 
+  skipInstall: false,
+ });
+
+ // Export the CLI configuration for use in other modules
+export const cli = { 
+  options, 
+  args: command.args, 
+  directory, 
+  newBranchName, 
+  createNewBranch, 
+  packageManager,
+};

package/src/constants.js

@@ -0,0 +1,31 @@
+export const NAME = 'create-cella'
+
+// URL of the template repository
+export const TEMPLATE_URL = 'github:cellajs/cella';
+
+// Files or folders to be removed from the template after downloading
+export const TO_REMOVE = [
+    'info',
+    './cli/create-cella'
+];
+
+// Specific folder contents to be cleaned out from the template
+export const TO_CLEAN = [
+    './backend/drizzle'
+];
+
+// Files to copy/paste after downloading
+export const TO_COPY = {
+    './backend/.env.example': './backend/.env',
+    './tus/.env.example': './tus/.env',
+    './info/QUICKSTART.md': 'README.md',
+};
+
+// ASCII title for the CLI output
+export const CELLA_TITLE = `
+                         _ _            
+    ▒▓█████▓▒     ___ ___| | | __ _
+    ▒▓█   █▓▒    / __/ _ \\ | |/ _\` |
+    ▒▓█   █▓▒   | (_|  __/ | | (_| |
+    ▒▓█████▓▒    \\___\\___|_|_|\\__,_|
+`;

package/src/create.js

@@ -0,0 +1,148 @@
+import { mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs'
+import { join, relative } from 'node:path';
+import colors from 'picocolors';
+import { downloadTemplate } from "giget";
+import yoctoSpinner from 'yocto-spinner';
+
+import { TEMPLATE_URL} from './constants.js';
+
+import { install } from './utils/run-package-manager-command.js';
+import { cleanTemplate } from './utils/clean-template.js';
+import { runGitCommand } from './utils/run-git-command.js';
+
+export async function create({
+    projectName,
+    targetFolder,
+    newBranchName,
+    skipInstall,
+    skipGit,
+    skipClean,
+    packageManager,
+  }) {
+    // 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();
+
+      try {
+        await cleanTemplate({ 
+          targetFolder,
+          projectName,
+        })
+        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`)
+    }
+
+    // Initialize Git repository if skipGit flag is not set
+    if (!skipGit) {
+      const gitSpinner = yoctoSpinner({
+        text: 'initializing git repository',
+      }).start();
+
+      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);
+        }
+      } else {
+        gitSpinner.warning('Git repository already initialized > Skip git init')
+      }
+    } else {
+      console.info(`${colors.yellow('⚠')} --skip-git > Skip git init`)
+    }
+    
+    // Final success message indicating project creation
+    console.info()
+    console.info(`${colors.green('Success')} Created ${projectName} at ${targetFolder}`)
+    console.info()
+
+    // Check if the working directory needs to be changed
+    const needsCd = originalCwd !== targetFolder;
+    if (needsCd) {
+      // Calculate the relative path between the original working directory and the target folder
+      const relativePath = relative(originalCwd, targetFolder);
+
+      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 with:`)
+    console.info(colors.cyan(`  ${packageManager} quick`))
+    console.info()
+
+    console.info('Read the readme in project root for more info on how to get started!')
+    console.info(`Enjoy building ${projectName} using cella! 🎉`)
+  }

package/src/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import { basename, resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+
+import { input, confirm, select } from '@inquirer/prompts';
+
+import { cli } from './cli.js'
+import { validateProjectName } from './utils/validate-project-name.js'
+import { isEmptyDirectory } from './utils/is-empty-directory.js'
+import { create } from './create.js'
+import { CELLA_TITLE } from './constants.js'
+
+async function main() {
+  console.info(CELLA_TITLE);
+
+  // Skip creating a new branch if --skipNewBranch flag is provided or git is skipped
+  if (cli.options.skipNewBranch || cli.options.skipGit) {
+    cli.createNewBranch = false;
+    cli.newBranchName = null;
+  }
+
+  // Skip installing packages if --skipInstall flag is provided
+  if (cli.options.skipInstall === true) {
+    cli.options.skipInstall = true;
+  }
+
+  // Skip cleaning the template if --skipClean flag is provided
+  if (cli.options.skipClean === true) {
+    cli.options.skipClean = true;
+  }
+
+  // Skip initializing git if --skipGit flag is provided
+  if (cli.options.skipGit === true) {
+    cli.options.skipGit = true;
+  }
+
+  // Prompt for project name if not provided
+  if (!cli.directory) {
+    cli.directory = await input({
+      message: 'Enter your project name',
+      default: 'my-cella-app',
+      validate: (name) => {
+        const validation = validateProjectName(basename(resolve(name)));
+        return validation.valid ? true : `Invalid project name: ${validation.problems[0]}`;
+      },
+    });
+  }
+
+  // Prompt to create a new branch besides the main branch (if not skipped)
+  if (cli.createNewBranch === null) {
+    cli.createNewBranch = await confirm({
+      message: 'Would you like to create a new branch (besides "main")?',
+      default: true,
+    });
+  }
+
+  // Prompt for new branch name, only if user opted to create a new branch
+  if (!cli.newBranchName && cli.createNewBranch) {
+    cli.newBranchName = await input({
+      message: 'Enter the new branch name',
+      default: 'development',
+      validate: (name) => {
+        const validation = validateProjectName(basename(resolve(name)))
+        return validation.valid ? true : `Invalid branch name: ${validation.problems[0]}`;
+      },
+    });
+  }
+
+  const targetFolder = resolve(cli.directory)
+  const projectName = basename(targetFolder)
+
+  // Check if the target folder exists and is not empty
+  if (existsSync(targetFolder) && !(await isEmptyDirectory(targetFolder))) {
+    const dirName = cli.directory === '.' ? 'Current directory' : `Target directory "${targetFolder}"`;
+    const message = `${dirName} is not empty. Please choose how you would like to proceed:`;
+
+    const action = await select({
+      message,
+      choices: [
+        { name: 'Cancel and exit', value: 'cancel' },
+        { name: 'Ignore existing files and continue', value: 'ignore' },
+      ],
+    });
+    if (action === 'cancel') {
+      process.exit(1);
+    }
+  }
+  
+  // Proceed with the project creation
+  await create({
+    projectName,
+    targetFolder,
+    newBranchName: cli.newBranchName,
+    skipInstall: cli.options.skipInstall,
+    skipGit: cli.options.skipGit,
+    skipClean: cli.options.skipClean,
+    packageManager: cli.packageManager,
+  });
+}
+
+main().catch(console.error)

package/src/utils/clean-template.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import colors from 'picocolors';
+
+import { TO_CLEAN, TO_REMOVE, TO_COPY } from '../constants.js';
+
+/**
+ * Cleans the specified template by removing designated folders and files.
+ * @param {Object} params - Parameters containing targetFolder.
+ * @param {string} params.targetFolder - The folder to clean.
+ */
+export async function cleanTemplate({
+  targetFolder,
+  projectName,
+}) {
+  // Change the current working directory to targetFolder if not already set
+  if (process.cwd() !== targetFolder) {
+    process.chdir(targetFolder);
+  }
+
+  return new Promise(async (resolve, reject) => {
+    try {
+      // Copy specified files
+      for (const [src, dest] of Object.entries(TO_COPY)) {
+        const srcAbsolutePath = path.resolve(targetFolder, src);
+        const destAbsolutePath = path.resolve(targetFolder, dest);
+        await copyFile(srcAbsolutePath, destAbsolutePath);
+      }
+
+      // Clean specified folder contents
+      await Promise.all(TO_CLEAN.map(folderPath => {
+        const absolutePath = path.resolve(targetFolder, folderPath);
+        return removeFolderContents(absolutePath);
+      }));
+
+      // Remove specified files and folders
+      await Promise.all(TO_REMOVE.map(filePath => {
+        const absolutePath = path.resolve(targetFolder, filePath);
+        return removeFileOrFolder(absolutePath);
+      }));
+
+      resolve();
+    } catch (err) {
+      reject(`Error during the cleaning process: ${err}`);
+    }
+  });
+}
+
+/**
+ * Removes all contents within a specified folder.
+ * @param {string} folderPath - The path of the folder to clean.
+ */
+export async function removeFolderContents(folderPath) {
+  // List all files in the folder
+  const files = await fs.readdir(folderPath); 
+
+  await Promise.all(files.map(async (file) => {
+    const filePath = path.join(folderPath, file);
+
+    // Get the file or folder statistics
+    const stat = await fs.lstat(filePath);
+
+    // If it's a directory, remove it and all its contents
+    if (stat.isDirectory()) {
+      await fs.rm(filePath, { recursive: true, force: true });
+    } else {
+      // If it's a file, remove it
+      await fs.rm(filePath);
+    }
+  }));
+}
+
+/**
+ * Removes a specified file or folder.
+ * @param {string} pathToRemove - The path to the file or folder to remove.
+ */
+export async function removeFileOrFolder(pathToRemove) {
+  await fs.rm(pathToRemove, { recursive: true, force: true });
+}
+
+// Helper function to copy files if the source exists
+export async function copyFile(src, dest) {
+  try {
+    // Check if the source file exists
+    await fs.access(src);
+
+    // Ensure the destination directory exists
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    
+    // Copy the file
+    await fs.copyFile(src, dest);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.info(`\n${colors.yellow('⚠')} Source file "${src}" does not exist > Skip copy`);
+    } else {
+      throw err;
+    }
+  }
+}

package/src/utils/is-empty-directory.js

@@ -0,0 +1,15 @@
+import { readdir } from 'node:fs/promises'
+
+/**
+ * Checks if a directory is empty or only contains a .git directory.
+ * 
+ * @param {string} path - The path of the directory to check.
+ * @returns {Promise<boolean>} - Resolves to true if the directory is empty or contains only a .git folder, false otherwise.
+ * @throws {Error} - Throws an error if the path is not a directory or if there's an issue reading the directory.
+ */
+export async function isEmptyDirectory(path) {
+  const files = await readdir(path);
+
+  // Check if directory is empty or contains only the .git directory
+  return files.length === 0 || (files.length === 1 && files[0] === '.git');
+}

package/src/utils/package-json.js

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Reads and parses the package.json file located in the root directory.
+ * 
+ * @returns {Promise<object>} - A promise that resolves to the parsed package.json object.
+ * @throws {Error} - Throws an error if the package.json file cannot be found or read, or if the JSON is invalid.
+ */
+async function readPackageJson() {
+  const PACKAGE_JSON_FILE = resolve(
+    fileURLToPath(import.meta.url),
+    '../../../package.json',
+  );
+
+  const packageJson = await readFile(PACKAGE_JSON_FILE, 'utf-8')
+  return JSON.parse(packageJson)
+}
+
+// Load the package.json at module initialization
+export const packageJson = await readPackageJson()

package/src/utils/run-git-command.js

@@ -0,0 +1,39 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Executes a Git command in the specified target folder.
+ * 
+ * @param {Object} options - Options for running the Git command.
+ * @param {string} options.targetFolder - The folder in which to run the command.
+ * @param {string} options.command - The Git command to execute (e.g., 'init', 'commit -m "message"', etc.).
+ * @returns {Promise<void>} - A promise that resolves if the command executes successfully; otherwise, it rejects with an error message.
+ * @throws {Error} - Throws an error if the Git command fails or if there is an error starting the process.
+ */
+export async function runGitCommand({ targetFolder, command }) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(`git ${command}`, [], { 
+        cwd: targetFolder, 
+        shell: true, 
+        timeout: 60000,
+      });
+  
+      // Handle process errors
+      child.on("error", (error) => {
+        reject(error);
+      });
+  
+      // Handle command exit
+      child.on("exit", (code) => {
+        if (code === 0) {
+          resolve();
+        } else {
+          reject(`Git command failed with exit code ${code}`);
+        }
+      });
+  
+      // Swallow stdout and stderr
+      child.stdout.on("data", () => {});
+      child.stderr.on("data", () => {});
+    });
+  }
+  

package/src/utils/run-package-manager-command.js

@@ -0,0 +1,56 @@
+import spawn from 'cross-spawn'
+
+/**
+ * Executes a command using the specified package manager (e.g., pnpm).
+ * 
+ * @param {string} packageManager - The package manager to use (e.g., 'pnpm').
+ * @param {Array<string>} args - The arguments to pass to the package manager command.
+ * @param {Object} [env={}] - Additional environment variables to set during command execution.
+ * @returns {Promise<void>} - A promise that resolves if the command executes successfully; otherwise, it rejects with an error message.
+ */
+export async function runPackageManagerCommand(packageManager, args, env = {} ) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(packageManager, args, {
+      env: {
+        ...process.env,
+        ...env,
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+     // Buffer for capturing stderr and stdout output
+    let stderrBuffer = ''
+    let stdoutBuffer = ''
+
+    // Capture stderr output
+    child.stderr?.on('data', (data) => {
+      stderrBuffer += data
+    });
+
+    // Capture stdout output
+    child.stdout?.on('data', (data) => {
+      stdoutBuffer += data
+    });
+
+    // Handle process exit
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(`"${packageManager} ${args.join(' ')}" failed ${stdoutBuffer} ${stderrBuffer}` );
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+/**
+ * Installs dependencies using the specified package manager.
+ * 
+ * @param {string} packageManager - The package manager to use for installation (e.g., ''pnpm').
+ * @returns {Promise<void>} - A promise that resolves if the installation completes successfully; otherwise, it rejects with an error.
+ */
+export async function install(packageManager) {
+  return runPackageManagerCommand(packageManager, ['install'], {
+    NODE_ENV: 'development',
+  });
+}

package/src/utils/validate-project-name.js

@@ -0,0 +1,28 @@
+import validate from 'validate-npm-package-name'
+
+/**
+ * Validates a project name according to npm package naming conventions.
+ * 
+ * @param {string} name - The name of the project to validate.
+ * @returns {Object} - An object containing the validation result and any associated problems.
+ * @returns {boolean} return.valid - Indicates if the project name is valid.
+ * @returns {Array<string>} return.problems - A list of errors and warnings associated with the project name.
+ */
+export function validateProjectName(name) {
+  // Validate the project name
+  const nameValidation = validate(name);
+
+  // If the name is valid for new packages, return valid status
+  if (nameValidation.validForNewPackages) {
+    return { valid: true, problems: [] };
+  }
+
+  // Return validation result with errors and warnings
+  return {
+    valid: false,
+    problems: [
+      ...(nameValidation.errors || []),
+      ...(nameValidation.warnings || []),
+    ],
+  }
+}