@cellajs/create-cella 0.1.5 → 0.2.0

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/README.md

@@ -0,0 +1,57 @@
+# @cellajs/create-cella
+
+CLI tool to scaffold a new Cella project from the template.
+
+## Overview
+
+This CLI creates a new Cella project by downloading the latest template, setting up your development environment, and configuring git with upstream tracking for future syncs.
+
+## Usage
+
+```bash
+pnpm create @cellajs/cella my-app
+```
+
+Running without arguments starts interactive mode, prompting for:
+
+1. **Project name** – Directory name and package name
+2. **New branch** – Optionally create a dev branch alongside `main`
+3. **Directory conflict** – If target exists, choose to cancel or continue
+
+## CLI Options
+
+```bash
+pnpm create @cellajs/cella [directory] [options]
+```
+
+## What It Does
+
+1. Downloads latest Cella template via [giget](https://github.com/unjs/giget)
+2. Cleans template files (removes cella-specific docs, configs)
+3. Installs dependencies with `pnpm install`
+4. Generates initial database migrations
+5. Initializes git repository with initial commit
+6. Creates optional working branch
+7. Adds Cella as upstream remote for future syncs
+
+## Development
+
+```bash
+cd cli/create-cella
+
+# Type check
+pnpm ts
+
+# Lint
+pnpm lint:fix
+
+# Run tests
+pnpm test
+
+# Run locally
+pnpm start
+
+# Build for npm publish
+pnpm build
+```
+

package/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cellajs/create-cella",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "private": false,
   "license": "MIT",
   "description": "Cella is a TypeScript template to create web apps with sync and offline capabilities.",
@@ -15,32 +15,44 @@
   "homepage": "https://cellajs.com",
   "author": "CellaJS <info@cellajs.com>",
   "engines": {
-    "node": ">=20.14.0"
+    "node": "24.x"
   },
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./src/create-cella-cli.ts",
+  "imports": {
+    "#/*": "./src/*"
+  },
   "bin": {
     "create-cella": "index.js"
   },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "axios": "^1.13.6",
+    "commander": "^14.0.3",
+    "giget": "^3.1.2",
+    "nano-spawn": "^2.0.0",
+    "ora": "^9.3.0",
+    "picocolors": "^1.1.1",
+    "validate-npm-package-name": "^7.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.13",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0"
+  },
   "scripts": {
-    "start": "tsx ./src/index.ts",
+    "start": "tsx ./src/create-cella-cli.ts",
     "clean": "rimraf ./dist",
     "build": "tsup",
     "test-build": "pnpm run build && node index.js",
-    "prepublishOnly": "pnpm run build"
-  },
-  "packageManager": "pnpm@9.11.0",
-  "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"
-  },
-  "devDependencies": {
-    "tsup": "^8.3.5",
-    "tsx": "^4.19.2"
+    "check": "pnpm ts && pnpm biome check --write .",
+    "check:old": "pnpm ts:old && pnpm biome check --write .",
+    "ts": "tsgo --pretty",
+    "ts:old": "tsc --pretty",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}

package/src/add-remote.ts

@@ -1,50 +1,40 @@
-import yoctoSpinner from 'yocto-spinner';
-import { runGitCommand } from './utils/run-git-command.ts';
-import { CELLA_REMOTE_URL } from './constants.ts';
-
-interface AddRemoteOptions {
-  targetFolder: string;
-  remoteUrl?: string; // Optional, defaults to CELLA_REMOTE_URL
-  remoteName?: string; // Optional, defaults to 'upstream'
-}
+import { CELLA_REMOTE_URL } from '#/constants';
+import type { AddRemoteOptions } from '#/modules/cli';
+import { gitRemoteAdd, gitRemoteGetUrl, gitRemoteRemove } from '#/utils/git';
 
+/**
+ * Adds or updates the upstream remote for the Cella template.
+ * @param options - Configuration options
+ * @param options.silent - If true, don't throw on failure (used when called from progress tracker)
+ */
 export async function addRemote({
   targetFolder,
   remoteUrl = CELLA_REMOTE_URL,
   remoteName = 'upstream',
+  silent = false,
 }: AddRemoteOptions): Promise<void> {
-
-  // Spinner for adding remote
-  const remoteSpinner = yoctoSpinner({
-    text: 'Adding remote',
-  }).start();
-
   try {
     // Check if the remote exists
     let remote: string | null = null;
 
     try {
-      remote = await runGitCommand({ targetFolder, command: `remote get-url ${remoteName}` });
-    } catch (error: any) {
+      remote = await gitRemoteGetUrl(targetFolder, remoteName);
+    } catch {
       // If the remote doesn't exist, it throws a fatal error
       remote = null;
     }
 
     // Add or update the remote if it doesn't exist or differs from `remoteUrl`
     if (!remote) {
-      await runGitCommand({ targetFolder, command: `remote add ${remoteName} ${remoteUrl}` });
-      remoteSpinner.success('Remote added successfully.');
+      await gitRemoteAdd(targetFolder, remoteName, remoteUrl);
     } else if (remote !== remoteUrl) {
       // Remove existing remote and set the new URL
-      await runGitCommand({ targetFolder, command: `remote remove ${remoteName}` });
-      await runGitCommand({ targetFolder, command: `remote add ${remoteName} ${remoteUrl}` });
-      remoteSpinner.success('Remote updated successfully.');
-    } else {
-      remoteSpinner.success('Remote is already configured correctly.');
+      await gitRemoteRemove(targetFolder, remoteName);
+      await gitRemoteAdd(targetFolder, remoteName, remoteUrl);
     }
   } catch (error) {
-    console.error(error);
-    remoteSpinner.error('Failed to add remote.');
-    process.exit(1);
+    if (!silent) {
+      throw error;
+    }
   }
 }

package/src/constants.ts

@@ -1,62 +1,106 @@
-export const NAME = 'create-cella';
+import pc from 'picocolors';
+import packageJson from '../package.json' with { type: 'json' };
 
-// URL of the template repository
-export const TEMPLATE_URL = 'github:cellajs/cella';
+/** Name of this CLI tool */
+export const NAME = 'create cella';
+
+/** Thin line divider for console output (60 chars wide) */
+export const DIVIDER = '─'.repeat(60);
 
-// URL to the repository
-export const CELLA_REMOTE_URL: string = 'git@github.com:cellajs/cella.git';
+/** URL of the template repository */
+export const TEMPLATE_URL = 'github:cellajs/cella';
 
-// Import package.json dynamically for version and website information
-import packageJson from '../package.json' assert { type: 'json' };
+/** URL to the repository */
+export const CELLA_REMOTE_URL = 'git@github.com:cellajs/cella.git';
 
-// Export details from package.json
+/** Export details from package.json */
 export const DESCRIPTION: string = packageJson.description;
 export const VERSION: string = packageJson.version;
 export const AUTHOR: string = packageJson.author;
 export const WEBSITE: string = packageJson.homepage;
 export const GITHUB: string = packageJson.repository.url;
 
+export function getHeaderLine(templateVersion?: string): string {
+  const leftText = `⧈ ${NAME} · v${VERSION} · cella v${templateVersion}`;
+  const rightText = packageJson.homepage.replace('https://', '');
+  const left = `${pc.cyan(`⧈ ${NAME}`)} ${pc.dim(`· v${VERSION} · cella v${templateVersion}`)}`;
+  const right = pc.cyan(rightText);
+  const padding = Math.max(1, 60 - leftText.length - rightText.length);
+  return `${left}${' '.repeat(padding)}${right}`;
+}
+
 // Files or folders to be removed from the template after downloading
-export const TO_REMOVE: string[] = [
-  'info',
-  './cli/create-cella',
-];
+export const TO_REMOVE: string[] = ['./cli/create', './info/QUICKSTART.md'];
 
 // Specific folder contents to be cleaned out from the template
-export const TO_CLEAN: string[] = [
-  './backend/drizzle',
-];
+export const TO_CLEAN: string[] = ['./backend/drizzle'];
 
 // Files to copy/paste after downloading
 export const TO_COPY: Record<string, string> = {
   './backend/.env.example': './backend/.env',
   './frontend/.env.example': './frontend/.env',
-  './tus/.env.example': './tus/.env',
   './info/QUICKSTART.md': 'README.md',
 };
 
-// Files to be editted after downloading
-export const TO_EDIT: Record<string, { regexMatch: RegExp; replaceWith: string }[]> = {
-  './config/default.ts': [
+/** Type for file edit operations */
+export type FileEdit = { regexMatch: RegExp; replaceWith: string };
+
+// Files to be edited after downloading
+export const TO_EDIT: Record<string, FileEdit[]> = {
+  './shared/default-config.ts': [
     {
-      regexMatch: /enabledAuthenticationStrategies:\s*\[[^\]]+\]\s*as\s*const,/g,
-      replaceWith: "enabledAuthenticationStrategies: ['password', 'passkey'] as const,",
+      regexMatch: /enabledAuthStrategies:\s*\[[^\]]+\]\s*as\s*const,/g,
+      replaceWith: "enabledAuthStrategies: ['password', 'passkey', 'totp'] as const,",
     },
     {
-      regexMatch: /imado\:\s*(true|false),/g,
-      replaceWith: "imado: false,",
+      regexMatch: /uploadEnabled:\s*(true|false),/g,
+      replaceWith: 'uploadEnabled: false,',
     },
     {
-      regexMatch: /enabledOauthProviders:\s*\[[^\]]+\]\s*as\s*const,/g,
-      replaceWith: "enabledOauthProviders: [] as const,",
+      regexMatch: /enabledOAuthProviders:\s*\[[^\]]+\]\s*as\s*const,/g,
+      replaceWith: 'enabledOAuthProviders: [] as const,',
     },
   ],
 };
-// ASCII logo for the CLI output
-export const LOGO = `
-                         _ _            
-    ▒▓█████▓▒     ___ ___| | | __ _
-    ▒▓█   █▓▒    / __/ _ \\ | |/ _\` |
-    ▒▓█   █▓▒   | (_|  __/ | | (_| |
-    ▒▓█████▓▒    \\___\\___|_|_|\\__,_|
-`;
+
+/**
+ * Generate file edits to apply a port offset to a new fork.
+ * All dev ports are shifted by the given offset to avoid collisions with sibling forks.
+ *
+ * Only 3 files need editing — all other services derive ports from these:
+ * - development-config.ts → frontend/backend URLs (read by Vite, backend, CDC, studio, tests)
+ * - .env → backend PORT + database connection strings
+ * - compose.yaml → Docker container names + host port mappings
+ *
+ * Default ports: frontend=3000, backend=4000, db=5432, dbTest=5434
+ */
+export function getPortEdits(projectName: string, offset: number): Record<string, FileEdit[]> {
+  if (offset === 0) return {};
+
+  const fe = 3000 + offset;
+  const be = 4000 + offset;
+  const db = 5432 + offset;
+  const dbTest = 5434 + offset;
+
+  return {
+    './shared/development-config.ts': [
+      { regexMatch: /frontendUrl:\s*'http:\/\/localhost:\d+'/g, replaceWith: `frontendUrl: 'http://localhost:${fe}'` },
+      { regexMatch: /backendUrl:\s*'http:\/\/localhost:\d+'/g, replaceWith: `backendUrl: 'http://localhost:${be}'` },
+      {
+        regexMatch: /backendAuthUrl:\s*'http:\/\/localhost:\d+\/auth'/g,
+        replaceWith: `backendAuthUrl: 'http://localhost:${be}/auth'`,
+      },
+    ],
+    './backend/.env': [
+      { regexMatch: /PORT=\d+/g, replaceWith: `PORT=${be}` },
+      { regexMatch: /@0\.0\.0\.0:5432\//g, replaceWith: `@0.0.0.0:${db}/` },
+    ],
+    './compose.yaml': [
+      { regexMatch: /name: cella/g, replaceWith: `name: ${projectName}` },
+      { regexMatch: /container_name: cella_db\b/g, replaceWith: `container_name: ${projectName}_db` },
+      { regexMatch: /container_name: cella_db_test/g, replaceWith: `container_name: ${projectName}_db_test` },
+      { regexMatch: /- 5432:5432/g, replaceWith: `- ${db}:5432` },
+      { regexMatch: /- 5434:5432/g, replaceWith: `- ${dbTest}:5432` },
+    ],
+  };
+}

package/src/create-cella-cli.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env tsx
+
+import { existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { input, select } from '@inquirer/prompts';
+import pc from 'picocolors';
+
+import { TEMPLATE_URL } from '#/constants';
+import { create } from '#/create';
+import { type CreateOptions, cli, showWelcome } from '#/modules/cli';
+import { detectUsedPorts, findNextOffset } from '#/utils/detect-used-ports';
+import { extractPackageJsonVersionFromUri } from '#/utils/extract-package-json-version-from-uri';
+import { isEmptyDirectory } from '#/utils/is-empty-directory';
+import { validateProjectName } from '#/utils/validate-project-name';
+
+async function main(): Promise<void> {
+  // Get the latest version of the template
+  const templateVersion = await extractPackageJsonVersionFromUri(TEMPLATE_URL);
+
+  // Display CLI welcome banner
+  showWelcome(templateVersion);
+
+  // Shared theme to clear prompts after answering
+  const promptTheme = { prefix: '', style: { answer: (text: string) => text } };
+  const promptContext = { clearPromptOnDone: true };
+
+  // Prompt for project name if not provided
+  if (!cli.directory) {
+    cli.directory = await input(
+      {
+        message: 'Enter your project name',
+        default: 'my-cella-app',
+        theme: promptTheme,
+        validate: (name) => {
+          const validation = validateProjectName(basename(resolve(name)));
+          return validation.valid ? true : `Invalid project name: ${validation.problems?.[0] ?? 'unknown error'}`;
+        },
+      },
+      promptContext,
+    );
+  }
+
+  // Default to creating a 'development' working branch
+  if (!cli.newBranchName) {
+    cli.newBranchName = 'development';
+  }
+
+  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,
+        theme: promptTheme,
+        choices: [
+          { name: 'Cancel and exit', value: 'cancel' },
+          { name: 'Ignore existing files and continue', value: 'ignore' },
+        ],
+      },
+      promptContext,
+    );
+
+    if (action === 'cancel') {
+      process.exit(1);
+    }
+  }
+
+  // Scan sibling directories and prompt for port offset
+  const portOffset = await promptPortOffset(targetFolder, promptTheme, promptContext);
+
+  // Proceed with the project creation
+  const createOptions: CreateOptions = {
+    projectName,
+    targetFolder,
+    newBranchName: cli.newBranchName,
+    packageManager: cli.packageManager,
+    templateUrl: cli.options.template,
+    portOffset,
+  };
+
+  await create(createOptions);
+}
+
+main().catch(console.error);
+
+/** Format an offset as a port overview string, e.g. "10 → :3010 / :4010 / :5442" */
+function formatOffset(o: number, suffix = ''): string {
+  return `${o} → :${3000 + o} / :${4000 + o} / :${5432 + o}${suffix}`;
+}
+
+/** Scan sibling forks and prompt the user to pick a port offset */
+async function promptPortOffset(targetFolder: string, theme: object, context: object): Promise<number> {
+  const usedPorts = await detectUsedPorts(targetFolder);
+  const suggested = findNextOffset(usedPorts);
+
+  if (usedPorts.length > 0) {
+    console.info(pc.dim('\nDetected cella forks in sibling directories:'));
+    for (const p of usedPorts) {
+      console.info(pc.dim(`  ${p.project}: frontend :${p.frontend}, backend :${p.backend} (offset ${p.offset})`));
+    }
+    console.info();
+  }
+
+  const presets = [0, 10, 20, 30].filter((o) => o !== suggested);
+  const choice = await select(
+    {
+      message: 'Port offset (avoids conflicts with sibling forks)',
+      theme,
+      choices: [
+        ...(suggested > 0 ? [{ name: formatOffset(suggested, ' (suggested)'), value: suggested }] : []),
+        { name: formatOffset(0, ' (default)'), value: 0 },
+        ...presets.map((o) => ({ name: formatOffset(o), value: o })),
+        { name: 'Custom offset', value: -1 },
+      ],
+    },
+    context,
+  );
+
+  if (choice !== -1) return choice;
+
+  const custom = await input(
+    {
+      message: 'Enter custom offset (0-490, multiples of 10)',
+      default: String(suggested),
+      theme,
+      validate: (val) => {
+        const n = Number(val);
+        if (Number.isNaN(n) || n < 0 || n > 490) return 'Must be between 0 and 490';
+        if (n % 10 !== 0) return 'Must be a multiple of 10';
+        return true;
+      },
+    },
+    context,
+  );
+  return Number(custom);
+}