create-alistt69-kit 0.1.9 → 0.1.12

package/src/core/parse-cli-args.js

@@ -1,123 +1,123 @@
-import { allowedPackageManagers } from '../utils/package-manager.js';
-
-function readOptionValue(args, currentIndex, optionName) {
-    const currentArg = args[currentIndex];
-
-    if (currentArg.includes('=')) {
-        return {
-            value: currentArg.slice(currentArg.indexOf('=') + 1),
-            nextIndex: currentIndex,
-        };
-    }
-
-    const nextArg = args[currentIndex + 1];
-
-    if (!nextArg || nextArg.startsWith('-')) {
-        throw new Error(`Option ${optionName} requires a value`);
-    }
-
-    return {
-        value: nextArg,
-        nextIndex: currentIndex + 1,
-    };
-}
-
-export function formatHelpMessage() {
-    return [
-        'Usage:',
-        '  create-alistt69-kit <project-name> [options]',
-        '',
-        'Options:',
-        '  -def, --defaults                    Skip prompts and use defaults',
-        '  --overwrite                  Overwrite target directory if it exists',
-        '  --no-install                 Do not install dependencies',
-        '  --features <comma-list>      Example: eslint,stylelint,react-router',
-        '  --features all               Enable all features',
-        '  --pm <npm|pnpm|yarn>         Package manager',
-        '  -h, --help                   Show help',
-        '',
-        'Defaults:',
-        '  All features are enabled by default',
-        '  Package manager: npm',
-        '  Install dependencies: yes',
-        '',
-        'Examples:',
-        '  create-alistt69-kit my-app',
-        '  create-alistt69-kit my-app --features=all',
-        '  create-alistt69-kit my-app --pm pnpm --no-install',
-        '  create-alistt69-kit my-app --defaults',
-        '  create-alistt69-kit my-app --defaults --overwrite',
-    ].join('\n');
-}
-
-export function parseCliArgs(argv) {
-    const result = {
-        projectName: undefined,
-        selectedFeatureIds: undefined,
-        shouldInstallDependencies: undefined,
-        packageManager: undefined,
-        defaults: false,
-        overwrite: false,
-        showHelp: false,
-    };
-
-    for (let index = 0; index < argv.length; index += 1) {
-        const arg = argv[index];
-
-        if (arg === '-h' || arg === '--help') {
-            result.showHelp = true;
-            continue;
-        }
-
-        if (arg === '-def' || arg === '--defaults') {
-            result.defaults = true;
-            continue;
-        }
-
-        if (arg === '--overwrite') {
-            result.overwrite = true;
-            continue;
-        }
-
-        if (arg === '--no-install') {
-            result.shouldInstallDependencies = false;
-            continue;
-        }
-
-        if (arg.startsWith('--features')) {
-            const { value, nextIndex } = readOptionValue(argv, index, '--features');
-            index = nextIndex;
-
-            result.selectedFeatureIds = value
-                ? value.split(',').map((item) => item.trim()).filter(Boolean)
-                : [];
-
-            continue;
-        }
-
-        if (arg.startsWith('--pm')) {
-            const { value, nextIndex } = readOptionValue(argv, index, '--pm');
-            index = nextIndex;
-
-            if (!allowedPackageManagers.includes(value)) {
-                throw new Error(`Unknown package manager: ${value}`);
-            }
-
-            result.packageManager = value;
-            continue;
-        }
-
-        if (arg.startsWith('-')) {
-            throw new Error(`Unknown option: ${arg}`);
-        }
-
-        if (!result.projectName) {
-            result.projectName = arg;
-            continue;
-        }
-
-        throw new Error(`Unexpected argument: ${arg}`);
-    }
-
-    return result;
+import { allowedPackageManagers } from '../utils/package-manager.js';
+
+function readOptionValue(args, currentIndex, optionName) {
+    const currentArg = args[currentIndex];
+
+    if (currentArg.includes('=')) {
+        return {
+            value: currentArg.slice(currentArg.indexOf('=') + 1),
+            nextIndex: currentIndex,
+        };
+    }
+
+    const nextArg = args[currentIndex + 1];
+
+    if (!nextArg || nextArg.startsWith('-')) {
+        throw new Error(`Option ${optionName} requires a value`);
+    }
+
+    return {
+        value: nextArg,
+        nextIndex: currentIndex + 1,
+    };
+}
+
+export function formatHelpMessage() {
+    return [
+        'Usage:',
+        '  create-alistt69-kit <project-name> [options]',
+        '',
+        'Options:',
+        '  -def, --defaults                    Skip prompts and use defaults',
+        '  --overwrite                  Overwrite target directory if it exists',
+        '  --no-install                 Do not install dependencies',
+        '  --features <comma-list>      Example: eslint,stylelint,react-router',
+        '  --features all               Enable all features',
+        '  --pm <npm|pnpm|yarn>         Package manager',
+        '  -h, --help                   Show help',
+        '',
+        'Defaults:',
+        '  All features are enabled by default',
+        '  Package manager: npm',
+        '  Install dependencies: yes',
+        '',
+        'Examples:',
+        '  create-alistt69-kit my-app',
+        '  create-alistt69-kit my-app --features=all',
+        '  create-alistt69-kit my-app --pm pnpm --no-install',
+        '  create-alistt69-kit my-app --defaults',
+        '  create-alistt69-kit my-app --defaults --overwrite',
+    ].join('\n');
+}
+
+export function parseCliArgs(argv) {
+    const result = {
+        projectName: undefined,
+        selectedFeatureIds: undefined,
+        shouldInstallDependencies: undefined,
+        packageManager: undefined,
+        defaults: false,
+        overwrite: false,
+        showHelp: false,
+    };
+
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+
+        if (arg === '-h' || arg === '--help') {
+            result.showHelp = true;
+            continue;
+        }
+
+        if (arg === '-def' || arg === '--defaults') {
+            result.defaults = true;
+            continue;
+        }
+
+        if (arg === '--overwrite') {
+            result.overwrite = true;
+            continue;
+        }
+
+        if (arg === '--no-install') {
+            result.shouldInstallDependencies = false;
+            continue;
+        }
+
+        if (arg.startsWith('--features')) {
+            const { value, nextIndex } = readOptionValue(argv, index, '--features');
+            index = nextIndex;
+
+            result.selectedFeatureIds = value
+                ? value.split(',').map((item) => item.trim()).filter(Boolean)
+                : [];
+
+            continue;
+        }
+
+        if (arg.startsWith('--pm')) {
+            const { value, nextIndex } = readOptionValue(argv, index, '--pm');
+            index = nextIndex;
+
+            if (!allowedPackageManagers.includes(value)) {
+                throw new Error(`Unknown package manager: ${value}`);
+            }
+
+            result.packageManager = value;
+            continue;
+        }
+
+        if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+
+        if (!result.projectName) {
+            result.projectName = arg;
+            continue;
+        }
+
+        throw new Error(`Unexpected argument: ${arg}`);
+    }
+
+    return result;
 }

package/src/core/prepare-target-directory.js

@@ -1,70 +1,70 @@
-import { confirm, isCancel } from '@clack/prompts';
-import { access, readdir, rm } from 'node:fs/promises';
-import process from 'node:process';
-import { resolve } from 'node:path';
-
-async function pathExists(targetDirPath) {
-    try {
-        await access(targetDirPath);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
-export async function prepareTargetDirectory({
-    projectName,
-    overwrite = false,
-    defaults = false,
-}) {
-    const targetDirPath = resolve(process.cwd(), projectName);
-    const exists = await pathExists(targetDirPath);
-
-    if (!exists) {
-        return {
-            targetDirPath,
-            wasOverwritten: false,
-        };
-    }
-
-    const directoryEntries = await readdir(targetDirPath);
-    const isEmpty = directoryEntries.length === 0;
-
-    if (isEmpty) {
-        return {
-            targetDirPath,
-            wasOverwritten: false,
-        };
-    }
-
-    if (overwrite) {
-        await rm(targetDirPath, { recursive: true, overwrite: true });
-
-        return {
-            targetDirPath,
-            wasOverwritten: true,
-        };
-    }
-
-    if (defaults) {
-        throw new Error(
-            `Directory already exists and is not empty: ${targetDirPath}. Use --overwrite to overwrite it.`,
-        );
-    }
-
-    const overwriteAnswer = await confirm({
-        message: `Directory "${projectName}" already exists and will be overwritten. Continue?`,
-        initialValue: false,
-    });
-
-    if (isCancel(overwriteAnswer) || !overwriteAnswer) {
-        process.exit(0);
-    }
-
-    await rm(targetDirPath, { recursive: true, overwrite: true });
-
-    return {
-        targetDirPath,
-        wasOverwritten: true,
-    };
+import { confirm, isCancel } from '@clack/prompts';
+import { access, readdir, rm } from 'node:fs/promises';
+import process from 'node:process';
+import { resolve } from 'node:path';
+
+async function pathExists(targetDirPath) {
+    try {
+        await access(targetDirPath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export async function prepareTargetDirectory({
+    projectName,
+    overwrite = false,
+    defaults = false,
+}) {
+    const targetDirPath = resolve(process.cwd(), projectName);
+    const exists = await pathExists(targetDirPath);
+
+    if (!exists) {
+        return {
+            targetDirPath,
+            wasOverwritten: false,
+        };
+    }
+
+    const directoryEntries = await readdir(targetDirPath);
+    const isEmpty = directoryEntries.length === 0;
+
+    if (isEmpty) {
+        return {
+            targetDirPath,
+            wasOverwritten: false,
+        };
+    }
+
+    if (overwrite) {
+        await rm(targetDirPath, { recursive: true, overwrite: true });
+
+        return {
+            targetDirPath,
+            wasOverwritten: true,
+        };
+    }
+
+    if (defaults) {
+        throw new Error(
+            `Directory already exists and is not empty: ${targetDirPath}. Use --overwrite to overwrite it.`,
+        );
+    }
+
+    const overwriteAnswer = await confirm({
+        message: `Directory "${projectName}" already exists and will be overwritten. Continue?`,
+        initialValue: false,
+    });
+
+    if (isCancel(overwriteAnswer) || !overwriteAnswer) {
+        process.exit(0);
+    }
+
+    await rm(targetDirPath, { recursive: true, overwrite: true });
+
+    return {
+        targetDirPath,
+        wasOverwritten: true,
+    };
 }

package/src/core/render-project-readme.js

@@ -1,76 +1,189 @@
-import { writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { featuresById } from '../features/index.js';
-import { readPackageJson } from '../utils/package-json.js';
-import { getRunScriptCommand } from '../utils/package-manager.js';
-
-const scriptDescriptions = {
-    dev: 'Start development server',
-    start: 'Start development server',
-    build: 'Build for production',
-    'build:dev': 'Build in development mode',
-    'build:prod': 'Build in production mode',
-    typecheck: 'Run TypeScript type check',
-    lint: 'Run ESLint',
-    'lint:fix': 'Run ESLint with autofix',
-    'lint:styles': 'Run Stylelint',
-    'lint:styles:fix': 'Run Stylelint with autofix',
-};
-
-function formatFeatureList(selectedFeatureIds) {
-    if (selectedFeatureIds.length === 0) {
-        return '- None';
-    }
-
-    return selectedFeatureIds
-        .map((featureId) => {
-            const feature = featuresById.get(featureId);
-
-            return `- ${feature?.title ?? featureId}`;
-        })
-        .join('\n');
-}
-
-function formatScripts(packageManager, scripts) {
-    const entries = Object.entries(scripts);
-
-    if (entries.length === 0) {
-        return '_No scripts available._';
-    }
-
-    return entries.map(([scriptName]) => {
-        const command = getRunScriptCommand(packageManager, scriptName);
-        const description = scriptDescriptions[scriptName] ?? 'Project script';
-
-        return `- \`${command}\` — ${description}`;
-    }).join('\n');
-}
-
-export async function renderProjectReadme({
-    projectPath,
-    projectName,
-    selectedFeatureIds,
-    packageManager,
-}) {
-    const packageJson = await readPackageJson(projectPath);
-
-    const readmeContent = [
-        `# ${projectName}`,
-        '',
-        'Created with `create-alistt69-kit`.',
-        '',
-        '## Enabled features',
-        '',
-        formatFeatureList(selectedFeatureIds),
-        '',
-        '## Available scripts',
-        '',
-        formatScripts(packageManager, packageJson.scripts ?? {}),
-    ].join('\n');
-
-    await writeFile(
-        resolve(projectPath, 'README.md'),
-        `${readmeContent}\n`,
-        'utf8',
-    );
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { featuresById } from '../features/index.js';
+import { readPackageJson } from '../utils/package-json.js';
+import { getRunScriptCommand } from '../utils/package-manager.js';
+
+const defaultTooling = [
+    {
+        title: 'React',
+        docs: 'https://react.dev/',
+        description: 'UI library',
+    },
+    {
+        title: 'TypeScript',
+        docs: 'https://www.typescriptlang.org/',
+        description: 'Static typing',
+    },
+    {
+        title: 'Webpack',
+        docs: 'https://webpack.js.org/',
+        description: 'Bundling and build pipeline',
+    },
+    {
+        title: 'SCSS Modules',
+        docs: 'https://github.com/css-modules/css-modules',
+        description: 'Scoped styling',
+    },
+    {
+        title: 'SVGR',
+        docs: 'https://react-svgr.com/',
+        description: 'SVGs as React components',
+    },
+    {
+        title: 'Webpack Bundle Analyzer',
+        docs: 'https://github.com/webpack-contrib/webpack-bundle-analyzer',
+        description: 'Bundle size inspection',
+    },
+];
+
+const scriptDescriptions = {
+    dev: 'Start development server',
+    start: 'Start development server',
+    build: 'Build for production',
+    'build:dev': 'Build in development mode',
+    'build:prod': 'Build in production mode',
+    typecheck: 'Run TypeScript type check',
+    lint: 'Run ESLint',
+    'lint:fix': 'Run ESLint with autofix',
+    'lint:styles': 'Run Stylelint',
+    'lint:styles:fix': 'Run Stylelint with autofix',
+};
+
+function formatMarkdownList(items, fallback = '- None') {
+    if (items.length === 0) {
+        return fallback;
+    }
+
+    return items.join('\n');
+}
+
+function formatDefaultTooling() {
+    return formatMarkdownList(
+        defaultTooling.map(({ title, docs, description }) => (
+            `- [${title}](${docs}) — ${description}`
+        )),
+    );
+}
+
+function formatFeatureList(selectedFeatureIds) {
+    if (selectedFeatureIds.length === 0) {
+        return '- None';
+    }
+
+    return selectedFeatureIds
+        .map((featureId) => {
+            const feature = featuresById.get(featureId);
+
+            if (!feature) {
+                return `- ${featureId}`;
+            }
+
+            return feature.hint
+                ? `- ${feature.title} — ${feature.hint}`
+                : `- ${feature.title}`;
+        })
+        .join('\n');
+}
+
+function formatScripts(packageManager, scripts) {
+    const entries = Object.entries(scripts);
+
+    if (entries.length === 0) {
+        return '_No scripts available._';
+    }
+
+    return entries
+        .map(([scriptName]) => {
+            const command = getRunScriptCommand(packageManager, scriptName);
+            const description = scriptDescriptions[scriptName] ?? 'Project script';
+
+            return `- \`${command}\` — ${description}`;
+        })
+        .join('\n');
+}
+
+function formatQuickStart({
+                              projectName,
+                              packageManager,
+                              shouldInstallDependencies,
+                          }) {
+    const steps = [`cd ${projectName}`];
+
+    if (!shouldInstallDependencies) {
+        steps.push(packageManager === 'yarn' ? 'yarn' : `${packageManager} install`);
+    }
+
+    steps.push(getRunScriptCommand(packageManager, 'start'));
+
+    return [
+        shouldInstallDependencies
+            ? 'Dependencies are already installed.'
+            : 'Install dependencies first, then start the development server.',
+        '',
+        '```bash',
+        ...steps,
+        '```',
+    ].join('\n');
+}
+
+function formatProjectStructure() {
+    return [
+        '- `public/` — static assets and HTML template',
+        '- `src/` — application source code',
+        '- `src/app/` — app bootstrap, providers, entry-level setup',
+        '- `src/styles/` — global styles and shared styling layer',
+        '- `config/build/` — split webpack configuration',
+    ].join('\n');
+}
+
+export async function renderProjectReadme({
+                                              projectPath,
+                                              projectName,
+                                              selectedFeatureIds,
+                                              packageManager,
+                                              shouldInstallDependencies,
+                                          }) {
+    const packageJson = await readPackageJson(projectPath);
+
+    const readmeContent = [
+        `# ${projectName}`,
+        '',
+        'Created with `create-alistt69-kit`.',
+        '',
+        '## Overview',
+        '',
+        'Starter project based on React + TypeScript + Webpack with optional tooling selected during scaffolding.',
+        '',
+        '## Included by default',
+        '',
+        formatDefaultTooling(),
+        '',
+        '## Selected optional features',
+        '',
+        formatFeatureList(selectedFeatureIds),
+        '',
+        '## Quick start',
+        '',
+        formatQuickStart({
+            projectName,
+            packageManager,
+            shouldInstallDependencies,
+        }),
+        '',
+        '## Project structure',
+        '',
+        formatProjectStructure(),
+        '',
+        '## Available scripts',
+        '',
+        formatScripts(packageManager, packageJson.scripts ?? {}),
+    ].join('\n');
+
+    await writeFile(
+        resolve(projectPath, 'README.md'),
+        `${readmeContent}\n`,
+        'utf8',
+    );
 }