create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/research/06-cli-strategy.md

@@ -0,0 +1,615 @@
+# CLI Strategy: Project Scaffolding
+
+**Project:** Lego-One (Modern.js SaaS OS)
+**Document:** 06 - CLI Strategy
+**Status:** Research Phase
+
+## Executive Summary
+
+This document explains how to implement the `pnpm create lego-one` command that allows developers to scaffold a new Lego-One project. Since we're using the **Git Template** approach, the CLI will be a lightweight wrapper around git operations and project configuration.
+
+---
+
+## 1. CLI Overview
+
+### 1.1 Command Structure
+
+```bash
+# Create new project from template
+pnpm create lego-one my-saas-app
+
+# With interactive prompts
+pnpm create lego-one my-saas-app --interactive
+
+# Skip git initialization
+pnpm create lego-one my-saas-app --no-git
+
+# Use specific branch
+pnpm create lego-one my-saas-app --branch v2.0.0
+```
+
+### 1.2 What the CLI Does
+
+1. **Clone Template:** Fetches lego-one from GitHub
+2. **Configure:** Updates package.json, env vars
+3. **Install:** Runs `pnpm install`
+4. **Initialize Git:** Creates initial commit
+5. **Configure Plugins:** Prompts for which plugins to enable
+
+---
+
+## 2. Implementation Options
+
+### 2.1 Option A: npm create (Recommended)
+
+Uses npm's built-in `create-*` command pattern.
+
+**Entry Point:** `packages/create-lego-one/package.json`
+
+```json
+{
+  "name": "create-lego-one",
+  "version": "1.0.0",
+  "bin": "./dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --clean",
+    "dev": "tsup src/index.ts --format cjs --watch"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "fs-extra": "^11.2.0",
+    "execa": "^8.0.1"
+  }
+}
+```
+
+### 2.2 Option B: Global CLI
+
+Install globally and run as a command:
+
+```bash
+pnpm add -g @lego/cli
+lego-one create my-saas-app
+```
+
+### 2.3 Option C: npx (Simplest)
+
+No package needed - uses a template repo directly:
+
+```bash
+npx create-lego-one@latest my-saas-app
+```
+
+**Our Choice:** Option A (npm create) - standard pattern, good DX.
+
+---
+
+## 3. CLI Implementation
+
+### 3.1 Main Entry Point
+
+**File:** `packages/create-lego-one/src/index.ts`
+
+```typescript
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createProject } from './commands/create';
+import { addPlugin } from './commands/add-plugin';
+
+const program = new Command();
+
+program
+  .name('create-lego-one')
+  .description('Create a new Lego-One SaaS application')
+  .version('1.0.0');
+
+program
+  .argument('[project-name]', 'Name of the project')
+  .option('-i, --interactive', 'Use interactive mode')
+  .option('--no-git', 'Skip git initialization')
+  .option('--branch <branch>', 'Template branch to use', 'main')
+  .action(async (projectName, options) => {
+    try {
+      await createProject(projectName, options);
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('add-plugin <plugin-name>')
+  .description('Add a plugin to the current project')
+  .action(addPlugin);
+
+program.parse();
+```
+
+### 3.2 Create Project Command
+
+**File:** `packages/create-lego-one/src/commands/create.ts`
+
+```typescript
+import path from 'path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import ora from 'ora';
+import prompts from 'prompts';
+import { execaCommand } from 'execa';
+
+interface CreateOptions {
+  interactive?: boolean;
+  git?: boolean;
+  branch?: string;
+}
+
+export async function createProject(
+  projectName: string | undefined,
+  options: CreateOptions
+) {
+  const spinner = ora();
+
+  // Interactive mode or get project name
+  let name = projectName;
+  let targetDir = process.cwd();
+
+  if (options.interactive || !name) {
+    const response = await prompts([
+      {
+        type: 'text',
+        name: 'name',
+        message: 'Project name:',
+        initial: 'my-saas-app',
+        validate: (n) => /^[a-z0-9-]+$/.test(n) || 'Only lowercase, numbers, and hyphens allowed',
+      },
+      {
+        type: 'select',
+        name: 'location',
+        message: 'Where to create the project?',
+        choices: [
+          { title: 'Current directory', value: 'current' },
+          { title: 'New subdirectory', value: 'subdirectory' },
+        ],
+        initial: 0,
+      },
+    ]);
+
+    name = response.name;
+    if (response.location === 'subdirectory') {
+      targetDir = path.join(targetDir, name);
+    }
+  }
+
+  if (!name) {
+    throw new Error('Project name is required');
+  }
+
+  const templateRepo = 'https://github.com/lego-one/lego-one.git';
+  const tempDir = path.join(targetDir, '.template-temp');
+
+  // Step 1: Clone template
+  spinner.start('Cloning Lego-One template...');
+  try {
+    await execaCommand(
+      `git clone --depth 1 --branch ${options.branch} ${templateRepo} ${tempDir}`
+    );
+    spinner.succeed('Template cloned');
+  } catch (error) {
+    spinner.fail('Failed to clone template');
+    throw error;
+  }
+
+  // Step 2: Copy files to target
+  spinner.start('Setting up project files...');
+  try {
+    // Copy all files except .git
+    const files = await fs.readdir(tempDir);
+    for (const file of files) {
+      if (file !== '.git') {
+        await fs.copy(
+          path.join(tempDir, file),
+          path.join(targetDir, file),
+          { overwrite: true }
+        );
+      }
+    }
+
+    // Remove temp directory
+    await fs.remove(tempDir);
+    spinner.succeed('Project files created');
+  } catch (error) {
+    spinner.fail('Failed to copy files');
+    throw error;
+  }
+
+  // Step 3: Configure package.json
+  spinner.start('Configuring project...');
+  try {
+    const packageJsonPath = path.join(targetDir, 'package.json');
+    const packageJson = await fs.readJson(packageJsonPath);
+
+    // Update project name
+    packageJson.name = name;
+
+    // Remove private flag (user may want to publish)
+    delete packageJson.private;
+
+    await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+    spinner.succeed('Project configured');
+  } catch (error) {
+    spinner.fail('Failed to configure project');
+    throw error;
+  }
+
+  // Step 4: Interactive plugin selection
+  if (options.interactive) {
+    const { plugins } = await prompts({
+      type: 'multiselect',
+      name: 'plugins',
+      message: 'Select plugins to enable:',
+      choices: [
+        { title: 'Dashboard', value: '@lego/plugin-dashboard', selected: true },
+        { title: 'Auth', value: '@lego/plugin-auth', selected: true },
+        { title: 'Billing (Stripe)', value: '@lego/plugin-billing' },
+        { title: 'Inventory', value: '@lego/plugin-inventory' },
+        { title: 'Loan Calculator', value: '@lego/plugin-loan-calculator' },
+      ],
+    });
+
+    // Update saas.config.ts
+    await updateSaaSConfig(targetDir, plugins);
+  }
+
+  // Step 5: Install dependencies
+  spinner.start('Installing dependencies...');
+  try {
+    await execaCommand('pnpm install', { cwd: targetDir });
+    spinner.succeed('Dependencies installed');
+  } catch (error) {
+    spinner.warn('Failed to install dependencies. Run `pnpm install` manually.');
+  }
+
+  // Step 6: Git initialization
+  if (options.git !== false) {
+    spinner.start('Initializing git...');
+    try {
+      await execaCommand('git init', { cwd: targetDir });
+      await execaCommand('git add .', { cwd: targetDir });
+      await execaCommand('git commit -m "Initial commit from Lego-One"', {
+        cwd: targetDir,
+      });
+      spinner.succeed('Git initialized');
+    } catch (error) {
+      spinner.warn('Git initialization failed');
+    }
+  }
+
+  // Success message
+  console.log('\n' + chalk.green('✓ Project created successfully!\n'));
+  console.log(chalk.cyan('Next steps:\n'));
+  console.log(`  cd ${name}`);
+  console.log('  pnpm run dev');
+  console.log('\n' + chalk.gray('Happy building!'));
+}
+
+async function updateSaaSConfig(targetDir: string, enabledPlugins: string[]) {
+  const configPath = path.join(targetDir, 'saas.config.ts');
+
+  let configContent = await fs.readFile(configPath, 'utf-8');
+
+  // Update enabled plugins
+  const pluginsSection = enabledPlugins
+    .map((p) => `    { name: '${p}', enabled: true }`)
+    .join(',\n');
+
+  configContent = configContent.replace(
+    /plugins: \[[\s\S]*?\]/,
+    `plugins: [\n${pluginsSection}\n  ]`
+  );
+
+  await fs.writeFile(configPath, configContent);
+}
+```
+
+### 3.3 Add Plugin Command
+
+**File:** `packages/create-lego-one/src/commands/add-plugin.ts`
+
+```typescript
+import path from 'path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import ora from 'ora';
+
+export async function addPlugin(pluginName: string) {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+
+  // Check if we're in a Lego-One project
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error('Not in a valid project directory');
+  }
+
+  const packageJson = await fs.readJson(packageJsonPath);
+  if (!packageJson.name?.startsWith('lego-one')) {
+    throw new Error('Not a Lego-One project');
+  }
+
+  spinner.start(`Adding plugin: ${pluginName}...`);
+
+  try {
+    // Update saas.config.ts
+    const configPath = path.join(projectRoot, 'saas.config.ts');
+    let configContent = await fs.readFile(configPath, 'utf-8');
+
+    // Add plugin to the list
+    const pluginEntry = `    { name: '${pluginName}', enabled: true }`;
+
+    if (configContent.includes('plugins: [')) {
+      configContent = configContent.replace(
+        'plugins: [',
+        `plugins: [\n${pluginEntry},`
+      );
+    }
+
+    await fs.writeFile(configPath, configContent);
+
+    spinner.succeed(`Plugin ${pluginName} added`);
+    console.log('\n' + chalk.gray('Update modern.runtime.ts to add the sub-app entry.'));
+  } catch (error) {
+    spinner.fail(`Failed to add plugin: ${error.message}`);
+    throw error;
+  }
+}
+```
+
+---
+
+## 4. Template Repository Structure
+
+### 4.1 GitHub Template Setup
+
+**Repository:** `github.com/lego-one/lego-one`
+
+```
+lego-one/                          # Template repository
+├── .github/
+│   └── workflows/
+│       └── template-sync.yml      # Sync upstream changes
+├── host/
+│   ├── src/
+│   ├── modern.config.ts
+│   └── package.json
+├── packages/
+│   └── plugins/
+│       └── @lego/
+│           ├── plugin-dashboard/
+│           ├── plugin-auth/
+│           └── plugin-billing/
+├── saas.config.ts                 # User-editable config
+├── pnpm-workspace.yaml
+├── package.json                   # Root package.json
+├── README.md
+└── .gitignore
+```
+
+### 4.2 Template Configuration
+
+**File:** `lego-one/.github/template-config.yml`
+
+```yaml
+# Template repository configuration
+name: Lego-One SaaS OS
+description: Microkernel SaaS boilerplate with Modern.js
+
+# Files to exclude when using as template
+exclude:
+  - .git/
+  - node_modules/
+  - dist/
+  - .env.local
+  - pnpm-lock.yaml
+
+# Prompts for users
+prompts:
+  - id: project_name
+    name: Project Name
+    default: my-saas-app
+  - id: pocketbase_url
+    name: PocketBase URL
+    default: http://localhost:8090
+  - id: enable_dashboard
+    name: Enable Dashboard Plugin
+    type: boolean
+    default: true
+  - id: enable_auth
+    name: Enable Auth Plugin
+    type: boolean
+    default: true
+```
+
+---
+
+## 5. Publishing the CLI
+
+### 5.1 Package.json
+
+**File:** `packages/create-lego-one/package.json`
+
+```json
+{
+  "name": "create-lego-one",
+  "version": "1.0.0",
+  "description": "Create a new Lego-One SaaS application",
+  "bin": "./dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --clean",
+    "dev": "tsup src/index.ts --format cjs --watch",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "create-app",
+    "lego-one",
+    "saas",
+    "micro-frontend",
+    "modernjs"
+  ],
+  "exports": "./dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lego-one/create-lego-one.git"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "prompts": "^2.4.2",
+    "execa": "^8.0.1",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/prompts": "^2.4.9",
+    "@types/fs-extra": "^11.0.4",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=8.0.0"
+  }
+}
+```
+
+### 5.2 Build Configuration
+
+**File:** `packages/create-lego-one/tsup.config.ts`
+
+```typescript
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs'],
+  target: 'node18',
+  clean: true,
+  shims: true,
+  banner: {
+    js: '#!/usr/bin/env node',
+  },
+});
+```
+
+### 5.3 Publish to npm
+
+```bash
+# Build the CLI
+cd packages/create-lego-one
+pnpm run build
+
+# Publish to npm
+pnpm publish --access public
+```
+
+---
+
+## 6. User Experience
+
+### 6.1 Creating a New Project
+
+```bash
+# User runs:
+pnpm create lego-one my-saas-app
+
+# Output:
+✓ Cloning Lego-One template...
+✓ Setting up project files...
+✓ Configuring project...
+✓ Installing dependencies...
+✓ Git initialized
+
+✓ Project created successfully!
+
+Next steps:
+  cd my-saas-app
+  pnpm run dev
+
+Happy building!
+```
+
+### 6.2 Interactive Mode
+
+```bash
+pnpm create lego-one --interactive
+
+# Prompts:
+? Project name: my-saas-app
+? Where to create the project? Current directory
+? Select plugins to enable:
+  ✓ Dashboard
+  ✓ Auth
+  ○ Billing (Stripe)
+  ○ Inventory
+  ○ Loan Calculator
+
+# ... creates project with selected plugins enabled
+```
+
+---
+
+## 7. Update Workflow
+
+### 7.1 User Updates from Template
+
+Since we're using Git Template approach:
+
+```bash
+# In user's project
+git remote add upstream https://github.com/lego-one/lego-one.git
+git fetch upstream
+git merge upstream/main
+
+# Resolve conflicts as needed
+# The user keeps their custom plugins in separate branch or subtree
+```
+
+### 7.2 Plugin Updates
+
+Official plugins are managed via git subtree/submodule:
+
+```bash
+# Add official plugin as subtree
+git subtree add \
+  --prefix=packages/plugins/@lego/plugin-dashboard \
+  https://github.com/lego-one/plugin-dashboard.git \
+  main
+
+# Update plugin later
+git subtree pull \
+  --prefix=packages/plugins/@lego/plugin-dashboard \
+  https://github.com/lego-one/plugin-dashboard.git \
+  main
+```
+
+---
+
+## 8. Next Steps
+
+1. **`07-deployment.md`**: Deploy host and plugins to production
+
+---
+
+## References
+
+- [npm create Documentation](https://docs.npmjs.com/cli/v9/commands/npm-create)
+- [Commander.js](https://commander.js.org/)
+- [GitHub Template Repositories](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
+- [pnpm Workspace](https://pnpm.io/workspaces)