@citruslime/create-boilerplate 3.0.0-beta.2 → 3.0.0-beta.3

package/main.js

@@ -1,25 +1,39 @@
 #!/usr/bin/env node
-import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { exec, execSync, spawn } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath, URL } from 'node:url';
-
-import { green, lightBlue, red } from 'kolorist';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+import {
+    bold,
+    cyan,
+    dim,
+    green,
+    lightBlue,
+    magenta,
+    red
+} from 'kolorist';
 import parseArgs from 'minimist';
 import { default as prompts } from 'prompts';
 
-const argv = parseArgs(process.argv.slice(2));
+const argv = parseArgs(process.argv.slice(2), {
+    alias: { v: 'verbose' },
+    boolean: ['verbose']
+});
 const cwd = process.cwd();
 const codeDir = fileURLToPath(new URL('./', import.meta.url));
+const verbose = Boolean(argv.verbose);
 
 const placeholdersToReplace = {
     /* eslint-disable @typescript-eslint/naming-convention */
     '[[PACKAGE_NAME]]': '',
-    '[[PACKAGE_DIR]]': '',
-    '[[ROOT_DIR]]': '',
-    '[[HUSKY_DIR]]': '',
-    '\'[[PROXY]]\'': '{}',
-    '\'[[FRONTEND_PORT]]\'': 0
+    '[[GIT_ROOT]]': '',
+    '[[DEFAULT_USERNAME]]': '',
+    '\'[[PROXY]]\'': ''
     /* eslint-enable @typescript-eslint/naming-convention */
 };
 
@@ -30,303 +44,248 @@ const filesToRename = {
     '_lintstagedrc.js': '.lintstagedrc.js',
     _stylelintignore: '.stylelintignore',
     '_stylelint.config.js': 'stylelint.config.js',
-    'template.code-workspace': 'citrus-lime.code-workspace',
-    _npmrc: '.npmrc'
+    _husky: '.husky'
 };
 
-const dependenciesToInstall = [
-    {
-        name: '@citruslime/ui'
-    },
-    {
-        name: '@citruslime/utils'
-    },
-    {
-        name: '@vueuse/core'
-    },
-    {
-        name: 'pinia'
-    },
-    {
-        name: 'pinia-plugin-persistedstate'
-    },
-    {
-        name: 'vue'
-    },
-    {
-        name: 'vue-i18n'
-    },
-    {
-        name: 'vue-router'
-    },
-    {
-        name: '@citruslime/config',
-        dev: true
-    },
-    {
-        name: '@citruslime/theme',
-        dev: true
-    },
-    {
-        name: '@tsconfig/node20',
-        dev: true
-    },
-    {
-        name: '@types/jsdom',
-        dev: true
-    },
-    {
-        name: '@types/luxon',
-        dev: true
-    },
-    {
-        name: '@types/node',
-        dev: true
-    },
-    {
-        name: '@vitejs/plugin-vue',
-        dev: true
-    },
-    {
-        name: '@vue/tsconfig',
-        dev: true
-    },
-    {
-        name: 'husky',
-        dev: true
-    },
-    {
-        name: 'lint-staged',
-        dev: true
-    },
-    {
-        name: 'postcss',
-        dev: true
-    },
-    {
-        name: 'npm-run-all',
-        dev: true
-    },
-    {
-        name: 'typescript',
-        dev: true
-    },
-    {
-        name: 'unplugin-auto-import',
-        dev: true
-    },
-    {
-        name: 'unplugin-vue-components',
-        dev: true
-    },
-    {
-        name: 'unplugin-vue-router',
-        dev: true
-    },
-    {
-        name: 'vite',
-        dev: true
-    },
-    {
-        name: 'vite-plugin-mkcert',
-        dev: true
-    },
-    {
-        name: 'vue-tsc',
-        dev: true
-    }
+const spinnerFrames = [
+    '⠋',
+    '⠙',
+    '⠹',
+    '⠸',
+    '⠼',
+    '⠴',
+    '⠦',
+    '⠧',
+    '⠇',
+    '⠏'
 ];
 
 /**
- * Initialise the new package.
+ * Short banner (similar in spirit to create-vite / npm init style CLIs).
+ */
+function printBanner () {
+    console.log();
+    console.log(`  ${bold(cyan('Citrus-Lime Vue Template'))}`);
+
+    if (!verbose) {
+        console.log();
+        console.log(dim('Tip: pass --verbose for further details.'));
+    }
+
+    console.log();
+}
+
+/**
+ * Runs task with a spinner (interactive TTY) or plain lines
+ * (CI, piped stdout, or --verbose so child process output does not garble the spinner).
+ *
+ * @param {string} label Step description.
+ * @param {() => void | Promise<void>} callback Work to run (sync or async).
+ * @throws {Error} An error if the work fails.
+ */
+async function runStep (label, callback) {
+    const plain = !process.stdout.isTTY || verbose;
+
+    if (plain) {
+        console.log(`${lightBlue('›')} ${label}`);
+
+        try {
+            await Promise.resolve(callback());
+        }
+        catch (e) {
+            console.log(`${red('✖')} ${label}`);
+            throw e;
+        }
+
+        console.log(`${green('✓')} ${label}`);
+
+        return;
+    }
+
+    let frame = 0;
+    const interval = setInterval(() => {
+        const f = spinnerFrames[frame++ % spinnerFrames.length];
+
+        process.stdout.write(`\r${dim('◆')} ${magenta(f)} ${label}\x1b[K`);
+    }, 50);
+
+    try {
+        await Promise.resolve(callback());
+    }
+    catch (e) {
+        process.stdout.write('\r\x1b[K');
+        throw e;
+    }
+    finally {
+        clearInterval(interval);
+    }
+
+    process.stdout.write(`\r${dim('◆')} ${green('✓')} ${label}\x1b[K\n`);
+}
+
+/**
+ * Initialise the new project.
+ *
+ * @throws {Error} Operation cancelled error.
  */
 async function init () {
-    let packageDir = argv._[0];
-    const rootDir = execSync('git rev-parse --show-toplevel')
-        .toString()
-        .trim();
+    printBanner();
+
+    const packageDir = argv._[0];
 
     const {
         packageName,
-        empty,
-        backendPort,
-        packageManager
+        backendPort
     } = await prompts([
         {
             type: 'text',
             name: 'packageName',
             message: 'Enter a name for the project:',
-            validate: value => /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(value) || 'Invalid package name'
-        },
-        {
-            type: packageDir ? null : 'text',
-            name: 'packageDir',
-            message: 'Enter a directory for the project:',
-            initial: '.',
-            onState: state => packageDir = state.value
-        },
-        {
-            type: () => directoryValid(packageDir) ? null : 'confirm',
-            name: 'empty',
-            message: () => `${packageDir === '.' ? 'Current directory' : `Target directory "${packageDir}"`} is not empty. Remove existing files and continue?`
+            validate: value => /^[a-z0-9-~][a-z0-9-._~]*$/.test(value) || 'Invalid project name (lowercase, no scope)'
         },
         {
-            type (_, { empty }) {
-                if (empty === false) {
-                    cancel();
-                }
-
-                return null;
-            },
-            name: 'emptyConfirmation'
-        },
-        {
-            type: 'confirm',
-            name: 'hasApi',
-            message: 'Setup backend proxy?',
-            initial: true
-        },
-        {
-            type: prev => prev ? 'text' : null,
+            type: 'number',
             name: 'backendPort',
             message: 'Enter the port that the backend server runs on:',
-            initial: 0
-        },
-        {
-            type: 'select',
-            name: 'packageManager',
-            message: 'Select a package manager:',
-            choices: [
-                {
-                    title: 'pnpm',
-                    value: 'pnpm'
-                },
-                {
-                    title: 'yarn',
-                    value: 'yarn'
-                },
-                {
-                    title: 'npm',
-                    value: 'npm'
-                }
-            ],
-            initial: 0
+            validate: value => (Number.isInteger(value) && value >= 1024 && value <= 65535) || 'Enter a valid port (1024-65535)'
         }
     ], {
-        onCancel: () => cancel()
+        onCancel () {
+            throw new Error('Operation was cancelled.');
+        }
     });
 
-    print(lightBlue('Initialising package...'), true);
+    console.log();
+    console.log(dim('—'.repeat(42)));
+    console.log();
 
-    packageDir = packageDir.toString();
+    const targetDir = (packageDir ?? packageName).toString();
 
-    setReplacements(packageName, packageDir, rootDir, backendPort ?? 0, packageManager);
-    prepareDir(join(cwd, packageDir), empty);
-    copyTemplate(packageDir);
+    const projectDir = resolve(cwd, targetDir);
 
-    process.chdir(packageDir);
-    installDependencies(packageManager);
+    await runStep('Preparing project directory', () => {
+        if (!existsSync(projectDir)) {
+            mkdirSync(projectDir, { recursive: true });
+        }
+    });
 
-    print(lightBlue('Creating hooks...'), true);
-    copyHooks(rootDir);
+    const gitRoot = getGitRoot(projectDir);
+    const gitRootRelative = (relative(projectDir, gitRoot ?? projectDir) || '.').replaceAll('\\', '/');
 
-    print(green(`Package ${packageName} has been successfully initialised in ${packageDir}.`), true);
-}
+    setReplacements(packageName, backendPort, gitRootRelative);
 
-/**
- * Checks if a directory is valid for project creation.
- *
- * @param {string} packageDir The directory of the package being created.
- * @returns True, if the directory is valid; false, otherwise.
- */
-function directoryValid (packageDir) {
-    const directoryExists = existsSync(packageDir);
-    const directorySize = directoryExists ? readdirSync(packageDir).length : 0;
-    const directoryOnlyContainsGit = directorySize === 1 && existsSync(`${packageDir}/.git`);
-
-    return !directoryExists ||
-        directorySize === 0 ||
-        directoryOnlyContainsGit;
+    await runStep('Scaffolding template files', () => {
+        copyTemplate(projectDir, gitRoot ?? projectDir);
+    });
+
+    if (!gitRoot) {
+        await runStep('Initialising Git repository', () => execAsync('git init', {
+            cwd: projectDir,
+            stdio: 'ignore'
+        }));
+    }
+
+    await installDependencies(projectDir, packageName);
+
+    console.log();
+    console.log(bold(green('All set.')));
+    console.log();
+    console.log(dim('Your new project is ready. Next:'));
+    console.log();
+    console.log(`  ${cyan('$')} ${dim('cd')} ${targetDir}`);
+    console.log(`  ${cyan('$')} ${dim('pnpm dev')}`);
+    console.log();
 }
 
 /**
- * Set the dynamic values for the file renaming and placeholder replacements.
+ * Set the dynamic values for the placeholder replacements.
  *
- * @param {string} packageName The name of the package being created.
- * @param {string} packageDir The directory of the package being created.
- * @param {string} rootDir The relative path of the root of the repository.
+ * @param {string} packageName The name of the project.
  * @param {number} backendPort The port that the backend server runs on.
- * @param packageManager The selected package manager to use.
+ * @param {string} gitRoot The relative path from the project directory to the Git root.
  */
-function setReplacements (packageName, packageDir, rootDir, backendPort, packageManager) {
-    const husky = relative(join(cwd, packageDir, '.vscode'), join(rootDir, '.husky'));
-    const repoRoot = relative(join(cwd, packageDir), rootDir);
-    const projDir = relative(rootDir, join(cwd, packageDir));
-
+function setReplacements (packageName, backendPort, gitRoot) {
     filesToRename['template.code-workspace'] = `${packageName}.code-workspace`;
     placeholdersToReplace['[[PACKAGE_NAME]]'] = packageName;
-    placeholdersToReplace['[[PACKAGE_DIR]]'] = projDir;
-    placeholdersToReplace['[[ROOT_DIR]]'] = repoRoot.replaceAll('\\', '/');
-    placeholdersToReplace['[[HUSKY_DIR]]'] = husky.replaceAll('\\', '/');
-    placeholdersToReplace['\'[[FRONTEND_PORT]]\''] = Math.floor(Math.random() * 1001) + 4000;
-    placeholdersToReplace['[[PACKAGE_MANAGER]]'] = packageManager;
-
-    if (backendPort !== 0) {
-        placeholdersToReplace['\'[[PROXY]]\''] = `{
+    placeholdersToReplace['[[GIT_ROOT]]'] = gitRoot;
+    placeholdersToReplace['[[DEFAULT_USERNAME]]'] = getDefaultUsername();
+    placeholdersToReplace['\'[[PROXY]]\''] = `{
+            // eslint-disable-next-line @typescript-eslint/naming-convention
             '/api': {
                 target: 'https://localhost:${backendPort}',
                 secure: false,
-                rewrite: (path) => path.replace('/api', '')
+                rewrite: (path: string): string => path.replace('/api', '')
             }
         }`;
-    }
 }
 
 /**
- * Prepares the directory for the new package to be created in.
+ * Gets username to use as default for the project.
  *
- * @param {string} path The path of the directory to be prepared.
- * @param {boolean} empty If the current contents needs to be emptied.
+ * @returns {string} Git `user.name`, if set; otherwise, the OS username.
  */
-function prepareDir (path, empty) {
-    if (empty) {
-        const options = {
-            recursive: true,
-            force: true
-        };
-
-        print(lightBlue('Emptying directory...'), true);
+function getDefaultUsername () {
+    try {
+        const username = execSync('git config user.name', {
+            cwd: process.cwd(),
+            encoding: 'utf-8',
+            stdio: [
+                'ignore',
+                'pipe',
+                'ignore'
+            ]
+        }).trim();
+
+        if (username) {
+            return username;
+        }
 
-        forEachInDir(path, item => rmSync(join(path, item), options));
+        return userInfo().username;
     }
-    else if (!existsSync(path)) {
-        print(lightBlue('Creating directory...'), true);
-
-        mkdirSync(path);
+    catch {
+        // Git is missing, not on PATH, or config is unreadable.
     }
+
+    return 'Unknown';
 }
 
 /**
- * Copies the template directory into the new package directory.
+ * Returns the root directory of the Git repository containing the given
+ * directory, or null if the directory is not inside a Git repository.
  *
- * @param {string} packageDir The directory of the new package.
+ * @param {string} dir The directory to check.
+ * @returns {string | null} The Git root path, or null.
  */
-function copyTemplate (packageDir) {
-    const templateDir = join(codeDir, 'template');
-
-    forEachInDir(templateDir, item => copy(templateDir, packageDir, item));
+function getGitRoot (dir) {
+    try {
+        return execSync('git rev-parse --show-toplevel', {
+            cwd: dir,
+            stdio: [
+                'ignore',
+                'pipe',
+                'ignore'
+            ],
+            encoding: 'utf-8'
+        }).trim();
+    }
+    catch {
+        return null;
+    }
 }
 
 /**
- * Copies the hooks directory into the husky directory for the repository.
+ * Copies the template directory into the project directory.
+ * The `_husky` directory is copied to the Git root so that hooks are installed into the correct location.
  *
- * @param {string} rootDir The relative path from the package directory to the root of the repository.
+ * @param {string} projectDir The directory of the new project.
+ * @param {string} gitRoot The root of the Git repository.
  */
-function copyHooks (rootDir) {
-    const hooksDir = join(codeDir, 'hooks');
-    const huskyDir = join(rootDir, '.husky');
+function copyTemplate (projectDir, gitRoot) {
+    const templateDir = join(codeDir, 'template');
 
-    forEachInDir(hooksDir, item => copy(hooksDir, huskyDir, item));
+    for (const item of readdirSync(templateDir)) {
+        copy(templateDir, item === '_husky' ? gitRoot : projectDir, item);
+    }
 }
 
 /**
@@ -337,118 +296,198 @@ function copyHooks (rootDir) {
  * @param {string} item The item to copy.
  */
 function copy (source, destination, item) {
+    if (item === '.gitkeep') {
+        return;
+    }
+
     const sourceItem = join(source, item);
     const info = statSync(sourceItem);
 
     if (info.isDirectory()) {
-        const destinationDir = join(destination, item);
+        const renamedItem = filesToRename[item] ?? item;
+        const destinationDir = join(destination, renamedItem);
 
         mkdirSync(destinationDir, { recursive: true });
 
-        forEachInDir(sourceItem, item => copy(sourceItem, destinationDir, item));
+        for (const child of readdirSync(sourceItem)) {
+            copy(sourceItem, destinationDir, child);
+        }
     }
     else {
-        const destinationFile = filesToRename[item] ? join(destination, filesToRename[item]) : join(destination, item);
+        const destinationFile = join(destination, filesToRename[item] ?? item);
 
         if (existsSync(destinationFile)) {
-            print(lightBlue(`Skipping ${item}...`), true);
+            if (verbose) {
+                console.log(`${dim('skip')} ${item}`);
+            }
         }
-        else {
-            const options = {
-                encoding: 'utf-8'
-            };
+        else if (extname(item).toLowerCase() === '.ico') {
+            if (verbose) {
+                console.log(`${dim('copy')} ${item}`);
+            }
 
-            print(lightBlue(`Copying ${item}...`), true);
+            copyFileSync(sourceItem, destinationFile);
+        }
+        else {
+            if (verbose) {
+                console.log(`${dim('copy')} ${item}`);
+            }
 
-            let contents = readFileSync(sourceItem, options);
+            let contents = readFileSync(sourceItem, { encoding: 'utf-8' });
 
             for (const [
                 key,
                 value
             ] of Object.entries(placeholdersToReplace)) {
-                contents = contents.replace(key, value);
+                contents = contents.replaceAll(key, value);
             }
 
-            writeFileSync(destinationFile, contents, options);
+            writeFileSync(destinationFile, contents, { encoding: 'utf-8' });
         }
     }
 }
 
 /**
- * Installs the required dependencies for the template.
- *
- * @param {string} packageManager The package manager to use.
+ * Dependency definitions per workspace.
+ * The major version constraint ensures pnpm resolves to the latest minor/patch
+ * and writes the full ^x.y.z version into package.json.
  */
-function installDependencies (packageManager) {
-    const prefix = `${packageManager} ${packageManager !== 'npm' ? 'add' : 'install'}`;
-
-    print(lightBlue('Installing dev dependencies...'), true);
-
-    let devDependencies = '';
-
-    for (const dependency of dependenciesToInstall.filter(d => d.dev)) {
-        devDependencies += `${dependency.name}${dependency.next ? '@next' : '@latest'} `;
-    }
-
-    execSync(`${prefix} -D ${devDependencies}`);
-
-    print(lightBlue('Installing dependencies...'), true);
-
-    let dependencies = '';
-
-    for (const dependency of dependenciesToInstall.filter(d => !d.dev)) {
-        dependencies += `${dependency.name}${dependency.next ? '@next' : '@latest'} `;
+const dependencies = {
+    root: {
+        dev: [
+            'eslint@9',
+            'husky@9',
+            'lint-staged@16',
+            'stylelint@17',
+            'turbo@2'
+        ]
+    },
+    app: {
+        prod: [
+            '@citruslime/ui@4',
+            '@citruslime/vue-utils@2',
+            '@vueuse/core@14',
+            'luxon@3',
+            'pinia@3',
+            'pinia-plugin-persistedstate@4',
+            'vue@3',
+            'vue-i18n@11',
+            'vue-router@5'
+        ],
+        dev: [
+            '@citruslime/theme@2',
+            '@intlify/unplugin-vue-i18n@11',
+            '@tailwindcss/vite@4',
+            '@types/jsdom@27',
+            '@types/luxon@3',
+            '@types/node@25',
+            '@vitejs/plugin-vue@6',
+            'jsdom@28',
+            'npm-run-all@4',
+            'typescript@5',
+            'unplugin-auto-import@21',
+            'unplugin-vue-components@32',
+            'vite@8',
+            'vite-plugin-mkcert@1',
+            'vite-plugin-vue-devtools@8',
+            'vue-tsc@3'
+        ]
+    },
+    'config-eslint': {
+        prod: ['@citruslime/config@2']
+    },
+    'config-stylelint': {
+        prod: ['@citruslime/config@2']
+    },
+    'config-typescript': {
+        prod: [
+            '@tsconfig/node24@24',
+            '@vue/tsconfig@0'
+        ]
+    },
+    utils: {
+        prod: [
+            '@citruslime/vue-utils@2',
+            'unimport@6'
+        ],
+        dev: [
+            '@types/node@25',
+            'npm-run-all@4',
+            'typescript@5',
+            'unplugin-auto-import@21',
+            'vite@8',
+            'vue-tsc@3'
+        ]
     }
-
-    execSync(`${prefix} ${dependencies}`);
-
-    print(lightBlue('Running final install...'), true);
-
-    execSync(`${packageManager} install`);
-}
+};
 
 /**
- * Calls the callback for each item in a directory.
+ * Runs a shell command. Use this instead of promisified `exec` when `stdio` must be
+ * `'inherit'` — `exec` always buffers child output and does not honour `stdio` for streaming.
  *
- * @param {string} dir The directory to loop-through the contents of.
- * @param {function(string): void} callback The callback to provide with each item.
+ * @param {string} command Full command line (shell parsing).
+ * @param {string} cwd Working directory.
+ * @returns {Promise<void>}
  */
-function forEachInDir (dir, callback) {
-    const items = readdirSync(dir);
-
-    for (const item of items) {
-        callback(item);
-    }
+function runShellCommand (command, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            stdio: verbose ? 'inherit' : 'ignore',
+            windowsHide: true
+        });
+
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Command failed with exit code ${code}${signal ? ` (${signal})` : ''}: ${command}`));
+            }
+        });
+    });
 }
 
 /**
- * Throws an error to indicate that the current operation has been cancelled.
+ * Installs all project dependencies using pnpm add with major version constraints.
+ * Pnpm resolves each to the latest matching version and writes ^x.y.z into package.json.
  *
- * @throws {Error} Operation cancelled error.
+ * @param {string} projectDir The project directory.
+ * @param {string} packageName The name of the project used as the npm scope.
+ * @returns {Promise<void>}
  */
-function cancel () {
-    throw new Error('Operation was cancelled.');
-}
+async function installDependencies (projectDir, packageName) {
+    const runPnpm = cmd => runShellCommand(cmd, projectDir);
 
-/**
- * Prints a message to the console.
- *
- * @param {string} message The message to display.
- * @param {boolean} clearPrevious Whether to clear any existing message.
- */
-function print (message, clearPrevious = false) {
-    if (clearPrevious) {
-        process.stdout.clearLine(0);
-        process.stdout.cursorTo(0);
+    await runStep('pnpm install (workspace)', () => runPnpm('pnpm install --ignore-scripts'));
+
+    await runStep('Adding root DevDependencies', () => runPnpm(`pnpm add -D -w ${dependencies.root.dev.join(' ')}`));
+
+    for (const [
+        workspace,
+        deps
+    ] of Object.entries(dependencies).filter(([k]) => k !== 'root')) {
+        const filter = `--filter @${packageName}/${workspace}`;
+
+        if (deps.prod?.length) {
+            await runStep(`Dependencies · @${packageName}/${workspace}`, () => runPnpm(`pnpm ${filter} add ${deps.prod.join(' ')}`));
+        }
+
+        if (deps.dev?.length) {
+            await runStep(`DevDependencies · @${packageName}/${workspace}`, () => runPnpm(`pnpm ${filter} add -D ${deps.dev.join(' ')}`));
+        }
     }
 
-    process.stdout.write(message);
+    await runStep('pnpm install (final lockfile)', () => runPnpm('pnpm install'));
 }
 
 try {
     await init();
 }
 catch (e) {
-    print(`\n${red(e.message)}`);
+    console.error();
+    console.error(`${red('✖')} ${e.message}`);
     process.exit(1);
 }