@atlashub/smartstack-cli 1.6.1 → 1.8.0

package/README.md

@@ -16,127 +16,570 @@
 
 **By [AtlasHub](https://www.atlashub.ch)** | [support@atlashub.ch](mailto:support@atlashub.ch)
 
+## What's New in v1.5.2
+
+- **Azure DevOps Support** - Full GitFlow integration with Azure DevOps PRs and pipelines
+- **npm Auto-Publish** - Automated publishing via Azure Pipelines (@next and @latest tags)
+- **Ralph Loop Integration** - Fully automated BA orchestration with Ralph Loop framework
+- **Prompts System** - Expert prompt creation and optimization tools
+- **Quick Search** - Lightning-fast codebase exploration
+
+---
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Update](#update)
+- [Project Creation](#project-creation)
+- [CLI Commands](#cli-commands)
+- [Claude Code Commands](#claude-code-commands)
+- [VS Code Configuration](#vs-code-configuration)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+### 1. Node.js (v18 or higher)
+
+**Download:** https://nodejs.org/
+
+Verify installation:
+```powershell
+node --version   # Should display v18.x.x or higher
+npm --version    # Should display 9.x.x or higher
+```
+
+### 2. .NET SDK (v10.0 or higher)
+
+**Download:** https://dotnet.microsoft.com/download
+
+Verify installation:
+```powershell
+dotnet --version   # Should display 10.x.x or higher
+```
+
+### 3. Visual Studio Code
+
+**Download:** https://code.visualstudio.com/
+
+### 4. Claude Code Extension for VS Code
+
+1. Open VS Code
+2. Open Extensions panel (`Ctrl+Shift+X`)
+3. Search for "Claude Code"
+4. Click **Install**
+
+Or via terminal:
+```powershell
+code --install-extension anthropic.claude-code
+```
+
+### 5. MCP Servers (Recommended)
+
+MCP servers enhance the development experience:
+
+```powershell
+# SmartStack MCP - Convention validation, scaffolding, API docs
+claude mcp add smartstack
+
+# Context7 MCP - Library documentation, code examples
+claude mcp add context7
+```
+
 ---
 
 ## Installation
 
-```bash
-# Install globally
+### Step 1: Install the npm package
+
+```powershell
 npm install -g @atlashub/smartstack-cli
+```
 
-# Install commands to Claude Code
+### Step 2: Install commands into Claude Code
+
+```powershell
 smartstack install
+```
 
-# Or use the short alias
+Or with the short alias:
+```powershell
 ss install
 ```
 
-## Usage
+### Step 3: Verify installation
+
+```powershell
+smartstack status --verbose
+```
+
+### Local Installation (project only)
+
+If you prefer a project-scoped installation:
+
+```powershell
+cd C:\path\to\your\project
+smartstack install --local
+```
+
+---
+
+## Update
+
+### Update SmartStack CLI
+
+```powershell
+# Automatic update (package + commands)
+smartstack update
+```
+
+### Manual Update
+
+```powershell
+# 1. Update npm package
+npm update -g @atlashub/smartstack-cli
+
+# 2. Reinstall commands
+smartstack install --force
+```
+
+### Check for available updates
+
+```powershell
+npm outdated -g @atlashub/smartstack-cli
+```
+
+---
+
+## Project Creation
+
+### Method 1: `smartstack init` command (Recommended)
+
+The `smartstack init` command creates a complete SmartStack project with an interactive wizard.
 
-After installation, the following commands are available in Claude Code:
+#### Interactive creation
+
+```powershell
+smartstack init MyProject
+```
+
+The wizard will ask for:
+1. **Project type**: Full Stack, Backend Only, or Frontend Only
+2. **Database**: SQL Server, PostgreSQL, or SQLite
+3. **Modules**: Auth, Navigation, AI, Notifications
+
+#### Quick creation (default values)
+
+```powershell
+smartstack init MyProject -y
+```
+
+#### Available options
+
+| Option | Description |
+|--------|-------------|
+| `--full-stack` | Backend .NET + Frontend React (default) |
+| `--backend` | Backend .NET only |
+| `--frontend` | Frontend React only |
+| `--db <type>` | Database: `sqlserver`, `postgresql`, `sqlite` |
+| `--dry-run` | Simulation without creating files |
+| `--skip-mcp-check` | Skip MCP servers verification |
+| `-y, --yes` | Use default values |
+
+#### Examples
+
+```powershell
+# Full-stack project with SQL Server (default)
+smartstack init MyApp
+
+# Backend only with PostgreSQL
+smartstack init MyApi --backend --db postgresql
+
+# Frontend only
+smartstack init MyFrontend --frontend
+
+# Simulation (see what would be created)
+smartstack init MyProject --dry-run
+```
+
+#### Created structure
+
+```
+MyProject/
+├── src/
+│   ├── MyProject.Domain/           # Entities and interfaces
+│   ├── MyProject.Application/      # Services and DTOs
+│   ├── MyProject.Infrastructure/   # EF Core, repositories
+│   └── MyProject.Api/              # Controllers and configuration
+├── web/
+│   └── myproject-web/              # Frontend React + Vite
+├── tests/
+├── MyProject.sln
+├── Directory.Build.props
+├── .gitignore
+└── README.md
+```
+
+#### After creation
+
+```powershell
+cd MyProject
+
+# 1. Configure connection string in appsettings.json
+
+# 2. Create initial migration
+dotnet ef migrations add InitialCreate -p src/MyProject.Infrastructure -s src/MyProject.Api
+
+# 3. Apply migration
+dotnet ef database update -p src/MyProject.Infrastructure -s src/MyProject.Api
+
+# 4. Run backend
+dotnet run --project src/MyProject.Api
+
+# 5. Run frontend (another terminal)
+cd web/myproject-web
+npm run dev
+```
+
+### Method 2: Initialize existing project with GitFlow
+
+If you already have a project and want to add GitFlow:
+
+```powershell
+cd C:\Projects\MyExistingProject
+code .
+```
+
+In VS Code with Claude Code active:
+```
+/gitflow:1-init
+```
+
+---
+
+## CLI Commands
+
+All commands support the short alias `ss` (e.g., `ss install`, `ss status`).
+
+### install
+
+Install SmartStack commands, agents, and hooks.
+
+```powershell
+smartstack install [options]
+```
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--force` | `-f` | Overwrite existing files |
+| `--global` | `-g` | Install to ~/.claude (default) |
+| `--local` | `-l` | Install to ./.claude (project) |
+| `--commands-only` | | Install only commands |
+| `--agents-only` | | Install only agents |
+| `--hooks-only` | | Install only hooks |
+| `--no-config` | | Skip config file creation |
+| `--no-plugins` | | Skip Claude Code plugin installation |
+
+### uninstall
+
+Remove SmartStack commands, agents, and hooks.
+
+```powershell
+smartstack uninstall [options]
+```
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--global` | `-g` | Uninstall from ~/.claude (default) |
+| `--local` | `-l` | Uninstall from ./.claude |
+| `--commands-only` | | Remove only commands |
+| `--agents-only` | | Remove only agents |
+| `--hooks-only` | | Remove only hooks |
+| `--keep-config` | | Keep configuration file |
+| `--yes` | `-y` | Skip confirmation prompt |
+
+### status
+
+Show installation status.
+
+```powershell
+smartstack status [options]
+```
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--global` | `-g` | Check ~/.claude (default) |
+| `--local` | `-l` | Check ./.claude |
+| `--verbose` | `-v` | Show detailed command list |
+
+### update
+
+Update commands to the latest version.
+
+```powershell
+smartstack update [options]
+```
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--global` | `-g` | Update ~/.claude (default) |
+| `--local` | `-l` | Update ./.claude |
+
+### init
+
+Initialize a new SmartStack project.
+
+```powershell
+smartstack init <name> [options]
+```
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--full-stack` | | Backend + Frontend (default) |
+| `--backend` | | Backend .NET only |
+| `--frontend` | | Frontend React only |
+| `--db <type>` | | Database: sqlserver, postgresql, sqlite |
+| `--dry-run` | | Show what would be created |
+| `--yes` | `-y` | Skip prompts, use defaults |
+| `--skip-mcp-check` | | Skip MCP servers check |
+
+### docs
+
+Open SmartStack documentation in browser.
+
+```powershell
+smartstack docs [page] [options]
+```
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--list` | `-l` | List available documentation pages |
+
+**Available pages:**
+- `index` - Home page
+- `installation` - Installation guide
+- `commands` - Commands reference
+- `agents` - Agents documentation
+- `apex` - APEX methodology
+- `business-analyse` - Business Analysis workflow
+- `gitflow` - GitFlow workflow
+- `efcore` - EF Core migrations
+- `hooks` - Hooks configuration
+- `test-web` - Web testing
+
+**Examples:**
+```powershell
+smartstack docs                    # Open home page
+smartstack docs gitflow            # Open GitFlow documentation
+smartstack docs --list             # List all available pages
+```
+
+### license
+
+Manage SmartStack CLI license.
+
+```powershell
+smartstack license <command> [options]
+```
+
+| Command | Description |
+|---------|-------------|
+| `activate <key>` | Activate a license key |
+| `status` | Show current license status |
+| `deactivate` | Remove the current license |
+| `verify <key>` | Verify a license key without activating |
+
+**Examples:**
+```powershell
+smartstack license activate ABC123-DEF456    # Activate license
+smartstack license status                     # Check license status
+smartstack license deactivate                 # Remove license
+smartstack license verify ABC123-DEF456       # Verify without activating
+```
+
+---
+
+## Claude Code Commands
 
 ### GitFlow Workflow
 
-- `/gitflow` - Full GitFlow workflow
-- `/gitflow:1-init` - Initialize GitFlow structure
-- `/gitflow:2-status` - Show repository status
-- `/gitflow:3-commit` - Smart commit with validation
-- `/gitflow:4-plan` - Create integration plan
-- `/gitflow:5-exec` - Execute integration plan
-- `/gitflow:6-abort` - Rollback operations
-- `/gitflow:7-pull-request` - Create PR
-- `/gitflow:8-review` - Review PR
-- `/gitflow:9-merge` - Merge PR
-- `/gitflow:10-start` - Start feature/release/hotfix
-- `/gitflow:11-finish` - Finish and tag
-- `/gitflow:12-cleanup` - Cleanup worktrees
+| Command | Description |
+|---------|-------------|
+| `/gitflow` | Full GitFlow workflow |
+| `/gitflow:1-init` | Initialize GitFlow structure |
+| `/gitflow:2-status` | Show repository status |
+| `/gitflow:3-commit` | Smart commit with validation |
+| `/gitflow:4-plan` | Create integration plan |
+| `/gitflow:5-exec` | Execute integration plan |
+| `/gitflow:6-abort` | Rollback operations |
+| `/gitflow:10-start` | Start feature/release/hotfix |
+| `/gitflow:11-finish` | Finish and tag |
+| `/gitflow:12-cleanup` | Cleanup worktrees |
+| `/gitflow:13-sync` | Sync with remote |
+| `/gitflow:14-rebase` | Rebase on develop |
+| `/gitflow:7-pull-request` | Create a Pull Request |
+| `/gitflow:8-review` | Review a PR |
+| `/gitflow:9-merge` | Merge a PR |
 
 ### Development Methodologies
 
-- `/apex` - APEX methodology (Analyze-Plan-Execute-eXamine)
-- `/epct` - Explore-Plan-Code-Test methodology
-- `/oneshot` - Ultra-fast implementation
-- `/debug` - Systematic bug debugging
-- `/explore` - Deep codebase exploration
-- `/explain` - Code explanation with diagrams
-- `/review` - Quick code review
-- `/implement` - Implementation from BA handoff
+| Command | Description |
+|---------|-------------|
+| `/apex` | APEX methodology (Analyze-Plan-Execute-eXamine) |
+| `/epct` | Explore-Plan-Code-Test methodology |
+| `/oneshot` | Ultra-fast implementation |
+| `/debug` | Systematic debugging |
+| `/explore` | Deep codebase exploration |
+| `/explain` | Code explanation with diagrams |
+| `/review` | Quick code review |
+| `/implement` | Implementation from BA handoff |
 
 ### Business Analysis
 
-- `/business-analyse` - Full BA workflow with automatic orchestration
-- `/business-analyse:1-init` - Initialize BA structure
-- `/business-analyse:2-discover` - Requirements elicitation + similarity detection
-- `/business-analyse:3-analyse` - Business analysis (BRD)
-- `/business-analyse:4-specify` - Functional specification (FRD)
-- `/business-analyse:5-validate` - User validation gate
-- `/business-analyse:6-handoff` - Implementation brief (English)
-- `/business-analyse:7-doc-html` - Auto-generated HTML documentation
-- `/business-analyse:bug` - Bug resolution documentation
-- `/business-analyse:change-request` - Change request during development
+| Command | Description |
+|---------|-------------|
+| `/business-analyse` | Full BA workflow with orchestration |
+| `/business-analyse:1-init` | Initialize BA structure |
+| `/business-analyse:2-discover` | Requirements elicitation |
+| `/business-analyse:3-analyse` | Business analysis (BRD) |
+| `/business-analyse:4-specify` | Functional specification (FRD) |
+| `/business-analyse:5-validate` | User validation gate |
+| `/business-analyse:6-handoff` | Implementation brief |
+| `/business-analyse:7-doc-html` | Auto-generated HTML documentation |
+| `/business-analyse:bug` | Bug resolution documentation |
+| `/business-analyse:change-request` | Change request during development |
 
 ### EF Core Migrations
 
-- `/efcore` - EF Core orchestrator
-- `/efcore:migration` - Create/recreate migration
-- `/efcore:db-status` - Show migration status
-- `/efcore:db-deploy` - Apply migrations
-- `/efcore:db-seed` - Seed database
-- `/efcore:db-reset` - Reset database
-- `/efcore:scan` - Scan migrations across branches
-- `/efcore:conflicts` - Detect conflicts
-- `/efcore:rebase-snapshot` - Rebase ModelSnapshot
-- `/efcore:squash` - Squash multiple migrations
+| Command | Description |
+|---------|-------------|
+| `/efcore` | EF Core orchestrator |
+| `/efcore:migration` | Create/recreate migration |
+| `/efcore:db-status` | Show migration status |
+| `/efcore:db-deploy` | Apply migrations |
+| `/efcore:db-seed` | Seed database |
+| `/efcore:db-reset` | Reset database |
+| `/efcore:scan` | Scan migrations across branches |
+| `/efcore:conflicts` | Detect conflicts |
+| `/efcore:rebase-snapshot` | Rebase ModelSnapshot |
+| `/efcore:squash` | Squash multiple migrations |
 
 ### Prompts & Tools
 
-- `/prompts:create` - Expert prompt creation
-- `/prompts:agent` - Agent prompt optimization
-- `/prompts:command` - Command prompt patterns
-- `/prompts:claude-memory` - CLAUDE.md file management
+| Command | Description |
+|---------|-------------|
+| `/prompts:create` | Expert prompt creation |
+| `/prompts:agent` | Agent prompt optimization |
+| `/prompts:command` | Command prompt patterns |
+| `/prompts:claude-memory` | CLAUDE.md file management |
 
-### Ralph Loop (v1.4.0)
+### Ralph Loop
 
-- `/ralph-loop` - Start autonomous Ralph Loop session
-- `/ralph-loop:cancel-ralph` - Cancel active Ralph Loop
-- `/ralph-loop:help` - Ralph Loop documentation
+| Command | Description |
+|---------|-------------|
+| `/ralph-loop` | Start autonomous Ralph Loop session |
+| `/ralph-loop:cancel-ralph` | Cancel active Ralph Loop |
+| `/ralph-loop:help` | Ralph Loop documentation |
 
 ### Quick Search
 
-- `/quick-search` - Lightning-fast codebase search
+| Command | Description |
+|---------|-------------|
+| `/quick-search` | Lightning-fast codebase search |
 
-## CLI Commands
+---
 
-```bash
-# Install commands globally
-smartstack install
-ss install              # Short alias
+## VS Code Configuration
 
-# Install to current project only
-smartstack install --local
+### Recommended settings
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "claude-code.enableSmartStack": true,
+  "files.associations": {
+    "*.md": "markdown"
+  },
+  "editor.formatOnSave": true
+}
+```
+
+### Useful keyboard shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Shift+P` | Command palette |
+| `Ctrl+Shift+C` | Open Claude Code |
+| `Ctrl+ù` | Integrated terminal |
+
+---
+
+## Troubleshooting
+
+### "smartstack" is not recognized
+
+**Cause:** npm global is not in PATH.
+
+**Solution:**
+```powershell
+# Find npm global path
+npm config get prefix
+
+# Add to PATH (replace with your path)
+$env:Path += ";C:\Users\YourName\AppData\Roaming\npm"
+```
+
+### Permission error
+
+**Solution:** Run PowerShell as administrator, then:
+```powershell
+npm install -g @atlashub/smartstack-cli
+```
 
-# Show installation status
-smartstack status
+### Commands don't appear in Claude Code
+
+```powershell
+# Reinstall with force
+smartstack install --force
+
+# Check status
 smartstack status --verbose
+```
 
-# Update to latest version
-smartstack update
+### "MCP servers missing" error during `smartstack init`
+
+**Solution:** Install required MCP servers:
+```powershell
+claude mcp add smartstack
+claude mcp add context7
+```
 
+Or skip verification:
+```powershell
+smartstack init MyProject --skip-mcp-check
+```
+
+### Complete reinstallation
+
+```powershell
 # Uninstall
 smartstack uninstall
-```
+npm uninstall -g @atlashub/smartstack-cli
 
-## What's New in v1.5.2
+# Reinstall
+npm install -g @atlashub/smartstack-cli
+smartstack install
+```
 
-- **Azure DevOps Support** - Full GitFlow integration with Azure DevOps PRs and pipelines
-- **npm Auto-Publish** - Automated publishing via Azure Pipelines (@next and @latest tags)
-- **Ralph Loop Integration** - Fully automated BA orchestration with Ralph Loop framework
-- **Prompts System** - Expert prompt creation and optimization tools
-- **Quick Search** - Lightning-fast codebase exploration
+---
 
-## Documentation
+## Resources
 
-Full documentation available at:
+- [Official Website](https://smartstack.app)
+- [SmartStack Documentation](https://docs.smartstack.app)
 - [GitFlow Documentation](.documentation/gitflow.html)
 - [Business Analysis Documentation](.documentation/business-analyse.html)
 
@@ -148,6 +591,20 @@ Full documentation available at:
 
 **Need help?** Contact us at [support@atlashub.ch](mailto:support@atlashub.ch)
 
+## Development
+
+### Publishing
+
+> **INTERDICTION DE PUBLIER MANUELLEMENT SUR NPM**
+>
+> La publication sur npm est **automatique** via Azure Pipelines.
+> Ne jamais exécuter `npm publish` manuellement.
+>
+> **Workflow:**
+> 1. Créer une release avec `/gitflow:10-start release`
+> 2. Finaliser avec `/gitflow:11-finish`
+> 3. Le tag déclenche automatiquement le pipeline de publication
+
 ## License
 
 MIT - Free for personal and commercial use.