cli_tool_implementation.md

CLI Tool Implementation — Future Version

Status: Deferred to future version
Goal: Implement a complete CLI tool that enables npx emberdocs init my-docs and other commands, preparing the package for npm publishing.

---

Overview

Implement a complete CLI tool that allows users to initialize, develop, build, and deploy EmberDocs projects via npx emberdocs. The CLI will scaffold new projects, proxy development commands, and provide deployment helpers.

Architecture

graph TD
    A[npx emberdocs] --> B[bin/emberdocs.js]
    B --> C[Commander.js CLI]
    C --> D[init command]
    C --> E[dev command]
    C --> F[build command]
    C --> G[deploy command]
    
    D --> H[Scaffold Project]
    H --> I[Copy Templates]
    H --> J[Install Dependencies]
    
    E --> K[Proxy to Next.js dev]
    F --> L[Proxy to Next.js build]
    G --> M[Platform-specific deploy]

Loading

File Structure

New Files to Create

1. bin/emberdocs.js - CLI entry point (executable)
2. src/cli/index.ts - Main CLI logic and command registration
3. src/cli/commands/init.ts - Init command implementation
4. src/cli/commands/dev.ts - Dev command implementation
5. src/cli/commands/build.ts - Build command implementation
6. src/cli/commands/deploy.ts - Deploy command implementation
7. src/cli/utils/scaffold.ts - Project scaffolding utilities
8. src/cli/utils/templates.ts - Template file management
9. templates/minimal/ - Minimal project template files
10. templates/full/ - Full project template with examples
11. templates/integrate/ - Integration template for existing Next.js projects

Files to Modify

1. package.json - Add bin field, CLI dependencies, remove private: true
2. tsconfig.json - Include CLI source files
3. .gitignore - Ensure CLI build output is handled

Implementation Details

1. Package Configuration (package.json)

Add bin field:

"bin": {
  "emberdocs": "./bin/emberdocs.js"
}

Add CLI dependencies:

• commander - Command parsing
• inquirer - Interactive prompts
• chalk - Terminal colors
• ora - Progress spinners
• fs-extra - Enhanced file operations
• execa - Process execution

Remove or make conditional:

• "private": true - Remove to allow publishing

2. CLI Entry Point (bin/emberdocs.js)

Simple Node.js wrapper that:

• Checks Node.js version (>=18)
• Loads and executes the compiled CLI from dist/cli/index.js
• Handles errors gracefully

3. Main CLI (src/cli/index.ts)

• Sets up Commander.js with program name, version, description
• Registers all commands (init, dev, build, deploy)
• Handles global error handling
• Provides help text

4. Init Command (src/cli/commands/init.ts)

Options:

• --minimal - Minimal setup (no examples)
• --integrate - Add to existing Next.js project
• --template <name> - Use specific template

Flow:

1. Validate target directory (check if exists, prompt if needed)
2. Choose template type (minimal/full/integrate) via prompt if not specified
3. Copy template files to target directory
4. Generate package.json with correct dependencies
5. Create .env.example and .env.local
6. Install dependencies via npm/yarn/pnpm (detect package manager)
7. Build search index
8. Display success message with next steps

Template Structure:

• Copy essential Next.js config files
• Copy EmberDocs source code (or reference as dependency)
• Create minimal docs/ directory with example
• Set up TypeScript config
• Include Tailwind config
• Add necessary scripts to package.json

5. Dev Command (src/cli/commands/dev.ts)

Options:

• --port <number> - Port number (default: 3000)
• --host <string> - Host address

Flow:

1. Check if in EmberDocs project (look for next.config.mjs or emberdocs.config.js)
2. Run npm run dev with port/host options
3. Proxy Next.js dev server

6. Build Command (src/cli/commands/build.ts)

Options:

• --output <dir> - Output directory (default: .next)
• --static - Static export only

Flow:

1. Build search index first
2. Run Next.js build
3. Optionally run static export if --static flag

7. Deploy Command (src/cli/commands/deploy.ts)

Platforms:

• vercel - Deploy to Vercel
• netlify - Deploy to Netlify
• github-pages - Deploy to GitHub Pages

Flow:

1. Build project first
2. Run platform-specific deployment commands
3. Provide deployment URLs

8. Scaffolding Utilities (src/cli/utils/scaffold.ts)

Functions:

• createDirectory(path) - Create directory with error handling
• copyTemplate(templateName, targetDir) - Copy template files
• generatePackageJson(options) - Generate package.json
• installDependencies(targetDir, packageManager) - Install deps
• detectPackageManager() - Detect npm/yarn/pnpm
• createEnvFiles(targetDir) - Create .env.example and .env.local

9. Template Files

Minimal Template:

• Basic Next.js setup
• EmberDocs integration
• Single example doc
• Minimal config

Full Template:

• Complete Next.js setup
• Multiple example docs (getting-started, guides, api-reference)
• All features enabled
• Example configuration

Integration Template:

• Files to add to existing Next.js project
• Instructions for manual integration
• Minimal file changes

Build Configuration

TypeScript Compilation

• CLI code needs to be compiled to dist/cli/
• Add build script: "build:cli": "tsc -p tsconfig.cli.json"
• Create tsconfig.cli.json for CLI-specific compilation

Executable Permissions

• Ensure bin/emberdocs.js has executable permissions
• Add to .gitattributes: bin/emberdocs.js linguist-generated=false

Testing Strategy

1. Unit Tests - Test individual command functions
2. Integration Tests - Test full init flow in temp directory
3. E2E Tests - Test actual npx usage (manual for now)

Publishing Preparation

1. Version Management - Set initial version (0.1.0)
2. README Updates - Add CLI usage documentation
3. npmignore - Exclude unnecessary files from package
4. Pre-publish Checklist - Document steps for future publishing

Dependencies to Add

{
  "commander": "^11.0.0",
  "inquirer": "^9.2.0",
  "chalk": "^5.3.0",
  "ora": "^7.0.0",
  "fs-extra": "^11.2.0",
  "execa": "^8.0.0"
}

Implementation Order

1. Set up package.json (bin, dependencies)
2. Create CLI entry point (bin/emberdocs.js)
3. Set up TypeScript config for CLI
4. Implement main CLI structure (src/cli/index.ts)
5. Implement init command (most complex)
6. Create template files
7. Implement dev, build, deploy commands
8. Add error handling and user feedback
9. Test locally with npm link
10. Update documentation

Success Criteria

• npx emberdocs init my-docs creates working project in < 30 seconds
• All commands work as expected
• Clear error messages and progress indicators
• Cross-platform compatibility (macOS, Linux, Windows)
• Package is ready for npm publishing (but not published yet)

Implementation Tasks

Setup & Configuration

• Update package.json: add bin field, CLI dependencies, remove private flag
• Create bin/emberdocs.js executable entry point
• Create tsconfig.cli.json for CLI compilation and update main tsconfig

Core CLI Implementation

• Create src/cli/index.ts with Commander.js setup and command registration
• Implement src/cli/utils/scaffold.ts with directory creation, template copying, and dependency installation
• Create template directories (minimal, full, integrate) with necessary files

Commands

• Implement src/cli/commands/init.ts with options (--minimal, --integrate, --template) and interactive prompts
• Implement src/cli/commands/dev.ts to proxy Next.js dev server with port/host options
• Implement src/cli/commands/build.ts with search index building and Next.js build
• Implement src/cli/commands/deploy.ts with platform support (vercel, netlify, github-pages)

Polish & Testing

• Add comprehensive error handling, progress indicators (ora), and user-friendly messages (chalk)
• Test CLI locally using npm link and verify all commands work
• Update README.md and create CLI usage documentation
• Create .npmignore, update version, add pre-publish checklist documentation