@aligent/create-workspace 0.0.1

package/README.md

@@ -0,0 +1,142 @@
+# @aligent/create-workspace
+
+A command-line tool for creating new Nx workspaces with opinionated presets and configurations. This tool wraps `create-nx-workspace` and provides a streamlined experience for initializing Aligent microservice projects.
+
+## Features
+
+- Interactive prompts for workspace configuration
+- Support for custom Nx presets (e.g., `@aligent/nx-cdk`)
+- Automatic workspace cleanup (removes unnecessary files)
+- Built-in validation for workspace names and presets
+
+## Prerequisites
+
+- **Node.js**: v16.9 or higher (LTS recommended)
+- **Corepack**: Must be enabled on your system
+
+### Enable Corepack
+
+Corepack is included with Node.js 16.9+ but needs to be enabled:
+
+```sh
+corepack enable
+```
+
+For more information, visit the [official Corepack documentation](https://nodejs.org/api/corepack.html).
+
+## Usage
+
+### Using npx (Recommended)
+
+Run the tool directly without installation:
+
+```sh
+npx @aligent/create-workspace
+```
+
+### Global Installation
+
+Install globally for repeated use:
+
+```sh
+npm install -g @aligent/create-workspace
+create-workspace
+```
+
+### Interactive Mode
+
+Simply run the command and follow the prompts:
+
+```sh
+npx @aligent/create-workspace
+```
+
+You'll be asked to provide:
+1. **Preset**: The Nx preset to use (e.g., `@aligent/nx-cdk`)
+2. **Workspace name**: Must contain only lowercase letters, numbers, and hyphens
+
+### CLI Arguments
+
+Skip the interactive prompts by providing arguments:
+
+```sh
+npx @aligent/create-workspace --preset @aligent/nx-cdk --name my-workspace
+```
+
+#### Available Options
+
+| Option | Type | Description | Example |
+|--------|------|-------------|---------|
+| `--preset` | string | The Nx preset to use (supports version pinning) | `@aligent/nx-cdk@1.0.0` |
+| `--name` | string | The workspace name (lowercase, alphanumeric, hyphens only) | `my-app` |
+| `--debug` | boolean | Keep failed workspace directory for debugging | `--debug` |
+| `--version` | - | Show version number | - |
+| `--help` | - | Show help | - |
+
+### Examples
+
+Create a workspace with the default CDK preset:
+
+```sh
+npx @aligent/create-workspace --preset @aligent/nx-cdk --name my-cdk-app
+```
+
+Create a workspace with a specific preset version:
+
+```sh
+npx @aligent/create-workspace --preset @aligent/nx-cdk@1.2.3 --name my-app
+```
+
+## What Happens During Creation
+
+1. Validates prerequisites (Corepack availability)
+2. Collects workspace configuration (preset and name)
+3. Creates Nx workspace using the specified preset
+4. Cleans up unnecessary files:
+   - `package-lock.json` (in favor of Yarn)
+   - `.nx` cache directory
+   - `.vscode` settings
+   - `node_modules` (to be reinstalled with Yarn)
+5. Displays next steps for getting started
+
+## Next Steps After Creation
+
+After successful workspace creation, follow these steps:
+
+```sh
+# Navigate to your workspace
+cd your-workspace-name
+
+# Activate the Node.js version
+nvm use
+
+# Install dependencies
+yarn install
+```
+
+## Development
+
+This package is written in TypeScript and built using Nx.
+
+### Build
+
+```sh
+npm install
+npm run build
+```
+
+### Testing & Linting
+
+Run tests, linting, and type-checking:
+
+```sh
+npm run test
+```
+
+## License
+
+MIT
+
+## Repository
+
+[microservice-development-utilities](https://github.com/aligent/microservice-development-utilities)

package/bin/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const devkit_1 = require("@nx/devkit");
+const create_nx_workspace_1 = require("create-nx-workspace");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const prompts_1 = __importDefault(require("prompts"));
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("./lib/helpers");
+const PACKAGE_MANAGER = 'npm';
+const ITEMS_TO_REMOVE = ['package-lock.json', '.nx', '.vscode', 'node_modules'];
+async function main() {
+    // Handle Ctrl+C gracefully
+    process.on('SIGINT', helpers_1.handleCancellation);
+    const corepackAvailable = (0, helpers_1.isCommandAvailable)('corepack');
+    if (!corepackAvailable) {
+        (0, helpers_1.showCorepackInstructions)();
+        (0, helpers_1.logErrorThenExit)('Corepack is not available on your system');
+    }
+    const commandIndex = process.argv.findIndex(text => text.includes('create-workspace'));
+    const args = await (0, yargs_1.default)(process.argv.slice(commandIndex + 1))
+        .options({
+        preset: {
+            type: 'string',
+            demandOption: false,
+            description: 'The preset to use (e.g., @aligent/nx-cdk)',
+        },
+        name: {
+            type: 'string',
+            demandOption: false,
+            description: 'The workspace name',
+        },
+        debug: {
+            type: 'boolean',
+            demandOption: false,
+            default: false,
+        },
+    })
+        .usage('Usage: $0 --preset [preset] --name [name]')
+        .example('$0 --preset @aligent/nx-cdk --name my-app', '')
+        .showHelpOnFail(false, 'Specify --help for available options')
+        .version()
+        .parse();
+    const responses = await (0, prompts_1.default)([
+        {
+            type: args.preset ? null : 'text',
+            name: 'preset',
+            message: 'Which preset would you like to use?',
+            initial: '@aligent/nx-cdk',
+            validate: (value) => value.length > 0 || 'Preset is required (e.g., @aligent/nx-cdk)',
+        },
+        {
+            type: args.name ? null : 'text',
+            name: 'name',
+            message: 'What is your workspace name?',
+            validate: (value) => {
+                if (value.length === 0)
+                    return 'Workspace name is required';
+                if (!/^[a-z0-9-]+$/.test(value))
+                    return 'Workspace name must contain only lowercase letters, numbers, and hyphens';
+                return true;
+            },
+        },
+    ], { onCancel: helpers_1.handleCancellation });
+    const preset = args.preset || responses.preset;
+    const name = args.name || responses.name;
+    if (!preset || !name) {
+        (0, helpers_1.logErrorThenExit)('Missing required information');
+    }
+    const targetDir = path_1.default.join(process.cwd(), name);
+    if (fs_1.default.existsSync(targetDir)) {
+        (0, helpers_1.logErrorThenExit)(`Directory "${name}" already exists in the current location`, 'Please choose a different name or remove the existing directory.');
+    }
+    const { presetName, version } = (0, helpers_1.parsePreset)(preset);
+    if (!version) {
+        (0, helpers_1.logErrorThenExit)('Malfunction required preset');
+    }
+    const presetWithVersion = `${presetName}@${version}`;
+    devkit_1.logger.info('\n📋 Configuration:');
+    devkit_1.logger.info(`   Workspace name:    ${name}`);
+    devkit_1.logger.info(`   Preset:            ${presetWithVersion}`);
+    devkit_1.logger.info(`   Target directory:  ${targetDir}`);
+    devkit_1.logger.info('');
+    const { confirmed } = await (0, prompts_1.default)({
+        type: 'confirm',
+        name: 'confirmed',
+        message: 'Create workspace with these settings?',
+        initial: true,
+    }, { onCancel: helpers_1.handleCancellation });
+    if (!confirmed) {
+        (0, helpers_1.handleCancellation)();
+    }
+    try {
+        const { directory } = await (0, create_nx_workspace_1.createWorkspace)(presetWithVersion, {
+            name,
+            nxCloud: 'skip',
+            packageManager: PACKAGE_MANAGER,
+        });
+        (0, helpers_1.cleanupWorkspace)(directory, ITEMS_TO_REMOVE);
+        // Show summary and next steps
+        devkit_1.logger.info('\n✨ Summary:');
+        devkit_1.logger.info(`   Successfully created workspace "${name}"`);
+        devkit_1.logger.info(`   Using preset: ${presetWithVersion}`);
+        devkit_1.logger.info(`   Location: ${directory}`);
+        devkit_1.logger.info('');
+        devkit_1.logger.info('📝 Next steps:');
+        devkit_1.logger.info(`   1. cd ${name}`);
+        devkit_1.logger.info('      Navigate to your new workspace directory');
+        devkit_1.logger.info('');
+        devkit_1.logger.info('   2. nvm use');
+        devkit_1.logger.info('      Activate the Node.js version specified in .nvmrc');
+        devkit_1.logger.info('');
+        devkit_1.logger.info('   3. yarn install');
+        devkit_1.logger.info('      Install all workspace dependencies');
+        devkit_1.logger.info('');
+    }
+    catch (err) {
+        devkit_1.logger.error('Failed to create workspace');
+        const dirPath = path_1.default.join(process.cwd(), name);
+        await (0, helpers_1.failedWorkspaceCleanup)(dirPath, args.debug);
+        devkit_1.logger.error('Error details:');
+        (0, helpers_1.logErrorThenExit)(err);
+    }
+}
+main();

package/bin/lib/helpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Extracts package name and version from a preset string
+ */
+export declare function parsePreset(preset: string): {
+    presetName: string | undefined;
+    version: string;
+} | {
+    presetName: string;
+    version?: never;
+};
+export declare function isCommandAvailable(command: string): boolean;
+export declare function showCorepackInstructions(): void;
+/**
+ * Handle graceful exit on user cancellation
+ */
+export declare function handleCancellation(): never;
+export declare function logErrorThenExit(error: unknown, suggestion?: string): never;
+export declare function cleanupWorkspace(directory: string, items: string[]): void;
+export declare function failedWorkspaceCleanup(directory: string, debug: boolean): Promise<void>;

package/bin/lib/helpers.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePreset = parsePreset;
+exports.isCommandAvailable = isCommandAvailable;
+exports.showCorepackInstructions = showCorepackInstructions;
+exports.handleCancellation = handleCancellation;
+exports.logErrorThenExit = logErrorThenExit;
+exports.cleanupWorkspace = cleanupWorkspace;
+exports.failedWorkspaceCleanup = failedWorkspaceCleanup;
+const devkit_1 = require("@nx/devkit");
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Extracts package name and version from a preset string
+ */
+function parsePreset(preset) {
+    const defaultVersion = 'latest';
+    // Handle scoped packages: @scope/package@version or @scope/package
+    const scoped = preset.match(/^(@[^/]+\/[^@]+)(?:@(.+))?$/);
+    if (scoped) {
+        return { presetName: scoped[1], version: scoped[2] || defaultVersion };
+    }
+    // Handle regular packages: package@version or package
+    const regular = preset.match(/^([^@]+)(?:@(.+))?$/);
+    if (regular) {
+        return {
+            presetName: regular[1],
+            version: regular[2] || defaultVersion,
+        };
+    }
+    return { presetName: preset };
+}
+function isCommandAvailable(command) {
+    try {
+        (0, child_process_1.execSync)(`${command} --version`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function showCorepackInstructions() {
+    devkit_1.logger.info('\n');
+    devkit_1.logger.info('This tool requires Yarn via Corepack.\n');
+    devkit_1.logger.info('To enable corepack, run: corepack enable');
+    devkit_1.logger.info('\n');
+    devkit_1.logger.info('If corepack is not installed, you need Node.js 16.9+ or higher.');
+    devkit_1.logger.info('Corepack is included with Node.js but may need to be enabled.\n');
+    devkit_1.logger.info('For more information, visit:');
+    devkit_1.logger.info('   https://nodejs.org/api/corepack.html\n');
+}
+/**
+ * Handle graceful exit on user cancellation
+ */
+function handleCancellation() {
+    devkit_1.logger.warn('\nWorkspace creation cancelled\n');
+    process.exit(0);
+}
+function logErrorThenExit(error, suggestion) {
+    devkit_1.logger.info('\n');
+    devkit_1.logger.error(error);
+    if (suggestion)
+        devkit_1.logger.info(suggestion);
+    devkit_1.logger.info('\n');
+    process.exit(1);
+}
+function cleanupWorkspace(directory, items) {
+    for (const item of items) {
+        const itemPath = path_1.default.join(directory, item);
+        if (fs_1.default.existsSync(itemPath)) {
+            try {
+                fs_1.default.rmSync(itemPath, { recursive: true, force: true });
+            }
+            catch {
+                devkit_1.logger.warn(`Failed to remove ${item}`);
+            }
+        }
+    }
+}
+async function failedWorkspaceCleanup(directory, debug) {
+    if (!debug && fs_1.default.existsSync(directory)) {
+        try {
+            fs_1.default.rmSync(directory, { recursive: true, force: true });
+            devkit_1.logger.info('Cleaned up incomplete workspace');
+        }
+        catch {
+            devkit_1.logger.warn('Failed to clean up directory. You may need to remove it manually.');
+        }
+    }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@aligent/create-workspace",
+  "version": "0.0.1",
+  "description": "A command line tool for creating new workspace",
+  "type": "commonjs",
+  "main": "./bin/index.js",
+  "bin": {
+    "create-workspace": "./bin/index.js"
+  },
+  "typings": "./bin/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aligent/microservice-development-utilities.git",
+    "directory": "packages/create-workspace"
+  },
+  "dependencies": {
+    "@nx/devkit": "22.4.2",
+    "create-nx-workspace": "22.4.2",
+    "prompts": "^2.4.2",
+    "yargs": "^18.0.0"
+  },
+  "author": "Aligent",
+  "license": "MIT",
+  "types": "./bin/index.d.ts"
+}