@atlashub/smartstack-cli 3.8.0 → 3.9.0

package/templates/skills/gitflow/references/start-efcore-preflight.md

@@ -0,0 +1,70 @@
+# Start: EF Core Migration Pre-flight
+
+> Reference for step-start.md — BLOCKING check for release/hotfix branches.
+
+## Migration Naming Validation
+
+```bash
+if [ "$branch_type" = "release" ] || [ "$branch_type" = "hotfix" ]; then
+  echo "EF CORE MIGRATION PRE-FLIGHT"
+  echo "─────────────────────────────"
+
+  MIGRATION_DIRS=$(find . -type d -name "Migrations" -path "*/src/*" 2>/dev/null)
+
+  if [ -n "$MIGRATION_DIRS" ]; then
+    BAD_MIGRATIONS=""
+    GOOD_COUNT=0
+    BAD_COUNT=0
+
+    for dir in $MIGRATION_DIRS; do
+      for file in $(find "$dir" -name "*.cs" ! -name "*Designer*" ! -name "*ModelSnapshot*" | sort); do
+        FILENAME=$(basename "$file" .cs)
+        # Strip EF Core 14-digit timestamp prefix (e.g., 20260128220215_)
+        NAME_PART=$(echo "$FILENAME" | sed 's/^[0-9]\{14\}_//')
+
+        # Validate: {context}_v{version}_{sequence}_{Description}
+        # Accepts both dot (v2.0.0) and underscore (v2_0_0) version separators
+        if echo "$NAME_PART" | grep -qE '^[a-zA-Z]+_v[0-9]+[._][0-9]+[._][0-9]+_[0-9]{3}_[A-Z]'; then
+          echo "  ✅ $FILENAME"
+          GOOD_COUNT=$((GOOD_COUNT + 1))
+        else
+          echo "  ❌ $FILENAME"
+          BAD_COUNT=$((BAD_COUNT + 1))
+          BAD_MIGRATIONS="$BAD_MIGRATIONS  - $FILENAME\n"
+        fi
+      done
+    done
+
+    echo ""
+    echo "Result: $GOOD_COUNT OK, $BAD_COUNT non-compliant"
+
+    if [ "$BAD_COUNT" -gt 0 ]; then
+      echo ""
+      echo "⛔ RELEASE BLOCKED - Non-compliant migration names detected"
+      echo "Expected format: {context}_v{version}_{sequence}_{Description}"
+      echo "  Example OK:  core_v2.0.0_001_InitialSchema"
+      echo "  Example NOK: AddApplicationAccessRequests"
+    fi
+  fi
+fi
+```
+
+## If Non-Compliant Migrations Found
+
+```yaml
+AskUserQuestion:
+  header: "Migrations"
+  question: "Non-compliant migration names block this release. How to proceed?"
+  options:
+    - label: "Run /efcore squash (Recommended)"
+      description: "Squash migrations on develop to fix naming via MCP, then retry release"
+    - label: "Abort release"
+      description: "Cancel release, fix manually on develop"
+    - label: "Continue anyway"
+      description: "Proceed despite naming issues (NOT recommended for production)"
+```
+
+**Actions:**
+- **"/efcore squash"** → Delegate to `efcore-squash` agent on develop, then re-run `/gitflow start release`
+- **"Abort release"** → STOP immediately
+- **"Continue anyway"** → Log warning to `.claude/gitflow/logs/audit.log` and proceed

package/templates/skills/gitflow/references/start-local-config.md

@@ -0,0 +1,110 @@
+# Start: Local Environment Configuration
+
+> Reference for step-start.md — auto-generated local config for each worktree.
+
+## Port Generation
+
+```bash
+# Generate unique ports based on branch name hash (to avoid conflicts between worktrees)
+HASH=$(echo "$BRANCH_NAME" | shasum 2>/dev/null || echo "$BRANCH_NAME" | md5sum 2>/dev/null || echo "$BRANCH_NAME" | cksum)
+HASH=$(echo "$HASH" | cut -c1-4)
+HASH_NUM=$((16#$HASH % 100))
+API_PORT=$((5200 + HASH_NUM))
+WEB_PORT=$((5300 + HASH_NUM))
+
+PROJECT_NAME=$(echo "$GF_PROJECT_NAME" | tr '[:upper:]' '[:lower:]')
+DB_NAME=$(echo "${PROJECT_NAME}_${branch_type}_${BRANCH_NAME}" | cut -c1-63)
+```
+
+## 7a. Backend: appsettings.Local.json
+
+```bash
+[ -n "$API_DIR" ] && [ -f "$API_DIR/appsettings.json" ] && {
+  cat > "$API_DIR/appsettings.Local.json" << EOF
+{
+  "ConnectionStrings": {
+    "DefaultConnection": "Server=localhost;Database=${DB_NAME};Trusted_Connection=true;TrustServerCertificate=true"
+  },
+  "SmartStack": {
+    "AutoMigrate": true,
+    "FailOnMigrationError": true,
+    "EnableDevSeeding": true
+  },
+  "Authentication": {
+    "FrontendUrl": "http://localhost:${WEB_PORT}"
+  },
+  "Kestrel": {
+    "Endpoints": {
+      "Http": {
+        "Url": "http://localhost:${API_PORT}"
+      }
+    }
+  },
+  "Serilog": {
+    "MinimumLevel": {
+      "Default": "Debug"
+    }
+  }
+}
+EOF
+}
+```
+
+## 7b. Frontend: .env.local + npm script
+
+```bash
+[ -n "$WEB_DIR" ] && [ -f "$WEB_DIR/package.json" ] && {
+  cat > "$WEB_DIR/.env.local" << EOF
+VITE_API_URL=http://localhost:${API_PORT}
+VITE_APP_ENV=local
+VITE_DEBUG=true
+EOF
+
+  # Add "local" script to package.json if not exists
+  if ! grep -q '"local"' "$WEB_DIR/package.json"; then
+    node -e "
+      const fs = require('fs');
+      const pkg = JSON.parse(fs.readFileSync('$WEB_DIR/package.json', 'utf8'));
+      if (!pkg.scripts.local) {
+        pkg.scripts.local = 'vite --mode local --port ${WEB_PORT}';
+        fs.writeFileSync('$WEB_DIR/package.json', JSON.stringify(pkg, null, 2) + '\n');
+      }
+    "
+  fi
+}
+```
+
+## 7c. Backend: launchSettings.json Local Profile
+
+```bash
+LAUNCH_SETTINGS="$API_DIR/Properties/launchSettings.json"
+[ -n "$API_DIR" ] && [ -f "$LAUNCH_SETTINGS" ] && {
+  node -e "
+    const fs = require('fs');
+    const ls = JSON.parse(fs.readFileSync('$LAUNCH_SETTINGS', 'utf8'));
+    ls.profiles = ls.profiles || {};
+    ls.profiles.Local = {
+      commandName: 'Project',
+      dotnetRunMessages: true,
+      launchBrowser: false,
+      applicationUrl: 'http://localhost:${API_PORT}',
+      environmentVariables: {
+        ASPNETCORE_ENVIRONMENT: 'Local'
+      }
+    };
+    fs.writeFileSync('$LAUNCH_SETTINGS', JSON.stringify(ls, null, 2) + '\n');
+  "
+}
+```
+
+## 7d. Summary Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  LOCAL ENVIRONMENT CONFIGURED                               │
+├─────────────────────────────────────────────────────────────┤
+│  Database:  ${DB_NAME}                                      │
+│  API Port:  ${API_PORT}  →  dotnet run --launch-profile Local│
+│  Web Port:  ${WEB_PORT}  →  npm run local                   │
+└─────────────────────────────────────────────────────────────┘
+```

package/templates/skills/gitflow/steps/step-init.md

@@ -287,121 +287,12 @@ The user will type the actual name via "Other". Use this raw input for step 6b.
 
 **⛔ ALWAYS normalize, even if user chose the detected name.**
 
-**Step 1: Parse input into words**
-
-Split the raw input on any separator: spaces, hyphens, underscores, dots, camelCase boundaries.
-
-| Raw input | Parsed words |
-|-----------|-------------|
-| `mon super projet` | `["mon", "super", "projet"]` |
-| `gestion-des-stocks` | `["gestion", "des", "stocks"]` |
-| `my_awesome_app` | `["my", "awesome", "app"]` |
-| `SmartStack.App` | `["Smart", "Stack", "App"]` |
-| `userManagement` | `["user", "Management"]` |
-
-**Step 2: Language detection and spell check**
-
-For EACH word, you MUST:
-1. **Detect the language** (French, English, or technical/proper noun)
-2. **Check spelling** - flag obvious typos
-3. **Suggest corrections** if misspelled
-
-| Word | Language | Spelling | Suggestion |
-|------|----------|----------|------------|
-| `gestion` | FR | ✅ | - |
-| `gestoin` | FR | ❌ typo | → `gestion` |
-| `managment` | EN | ❌ typo | → `management` |
-| `SmartStack` | Proper noun | ✅ | - |
-| `auth` | EN (abbreviation) | ✅ | - |
-
-**If typos detected**, ask the user BEFORE generating variants:
-
-```yaml
-AskUserQuestion:
-  - header: "Spelling"
-    question: "Corrections detected. Accept?"
-    options:
-      - label: "Accept corrections (Recommended)"
-        description: "'gestoin' → 'gestion', 'managment' → 'management'"
-      - label: "Keep original"
-        description: "Use the name as typed"
-    multiSelect: false
-```
-
-**Step 3: Generate all name variants**
-
-From the cleaned words, generate ALL variants:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  PROJECT NAME VARIANTS                                       │
-│  Input: "gestion des stocks"                                 │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  A) PascalCase.Dot    →  Gestion.Des.Stocks                 │
-│     Best for: .NET namespace, C# project, folder name        │
-│                                                              │
-│  B) PascalCase        →  GestionDesStocks                    │
-│     Best for: Class name, assembly name                      │
-│                                                              │
-│  C) kebab-case        →  gestion-des-stocks                  │
-│     Best for: Git repo, npm package, URL slug                │
-│                                                              │
-│  D) snake_case        →  gestion_des_stocks                  │
-│     Best for: Database, Python, file system                  │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Step 4: Ask user to choose the PRIMARY format**
-
-```yaml
-AskUserQuestion:
-  - header: "Format"
-    question: "Which format for the project name?"
-    options:
-      - label: "PascalCase.Dot (Recommended)"
-        description: "{PascalCase.Dot variant} - .NET convention"
-      - label: "PascalCase"
-        description: "{PascalCase variant} - single word"
-      - label: "kebab-case"
-        description: "{kebab-case variant} - git/npm convention"
-      - label: "snake_case"
-        description: "{snake_case variant} - database/python convention"
-    multiSelect: false
-```
-
-**Step 5: Store all derived names**
-
-Regardless of the chosen primary format, ALL variants are generated and stored:
-
-```json
-{
-  "PROJECT_NAME": "{chosen format}",
-  "PROJECT_VARIANTS": {
-    "pascalCaseDot": "Gestion.Des.Stocks",
-    "pascalCase": "GestionDesStocks",
-    "kebabCase": "gestion-des-stocks",
-    "snakeCase": "gestion_des_stocks",
-    "displayName": "Gestion Des Stocks",
-    "words": ["gestion", "des", "stocks"],
-    "language": "fr"
-  }
-}
-```
-
-These variants are available for subsequent steps (repo name, namespace, folder, etc.).
-
-**Real-world examples:**
-
-| User types | PascalCase.Dot | kebab-case | PascalCase |
-|-----------|---------------|------------|------------|
-| `smart stack app` | `SmartStack.App` | `smart-stack-app` | `SmartStackApp` |
-| `gestion-des-stocks` | `Gestion.Des.Stocks` | `gestion-des-stocks` | `GestionDesStocks` |
-| `Mon Projet V2` | `Mon.Projet.V2` | `mon-projet-v2` | `MonProjetV2` |
-| `user auth module` | `User.Auth.Module` | `user-auth-module` | `UserAuthModule` |
-| `PROJET TEST` | `Projet.Test` | `projet-test` | `ProjetTest` |
-| `e-commerce platform` | `ECommerce.Platform` | `e-commerce-platform` | `ECommercePlatform` |
+See [references/init-name-normalization.md](../references/init-name-normalization.md) for the full 5-step process:
+1. Parse input into words (split on separators + camelCase)
+2. Language detection and spell check (ask user if typos found)
+3. Generate all name variants (PascalCase.Dot, PascalCase, kebab-case, snake_case)
+4. Ask user to choose PRIMARY format
+5. Store all derived names in `PROJECT_VARIANTS`
 
 ### 7. Ask Worktree Mode
 
@@ -482,88 +373,11 @@ mkdir -p "$PROJECT_BASE/$DEVELOP_DIR/.claude/gitflow/backup"
 
 **Write `.claude/gitflow/config.json` in develop worktree.**
 
-**⛔ IMPORTANT: Store paths using `normalize_path_for_storage()` format (Windows-style: `D:/path/to/folder`).** The `read_gitflow_config()` in `_shared.md` translates them to platform format at read time. This ensures WSL and Windows can share the same config.
-
-```json
-{
-  "version": "2.1.0",
-  "platform": {
-    "detected": "{GF_PLATFORM}",
-    "shell": "{GF_SHELL}",
-    "detectedAt": "{ISO_DATE}"
-  },
-  "workspace": {
-    "path": "{WORKSPACE_DIR_STORAGE_FORMAT}",
-    "name": ""
-  },
-  "repository": {
-    "name": "{PROJECT_NAME}",
-    "rootFolder": "{ROOT_FOLDER_STORAGE_FORMAT}",
-    "nameVariants": {
-      "pascalCaseDot": "{PascalCase.Dot}",
-      "pascalCase": "{PascalCase}",
-      "kebabCase": "{kebab-case}",
-      "snakeCase": "{snake_case}",
-      "displayName": "{Display Name}"
-    },
-    "defaultBranch": "main",
-    "remoteUrl": "{REPO_URL}"
-  },
-  "git": {
-    "provider": "{GIT_PROVIDER}",
-    "branches": {
-      "main": "main",
-      "develop": "develop"
-    },
-    "prefixes": {
-      "feature": "feature/",
-      "release": "release/",
-      "hotfix": "hotfix/"
-    }
-  },
-  "worktrees": {
-    "enabled": true,
-    "mode": "{WORKTREE_MODE}",
-    "structure": {
-      "main": "{ROOT_FOLDER_STORAGE_FORMAT}/01-Main",
-      "develop": "{ROOT_FOLDER_STORAGE_FORMAT}/02-Develop",
-      "features": "{ROOT_FOLDER_STORAGE_FORMAT}/features",
-      "releases": "{ROOT_FOLDER_STORAGE_FORMAT}/releases",
-      "hotfixes": "{ROOT_FOLDER_STORAGE_FORMAT}/hotfixes"
-    }
-  },
-  "versioning": {
-    "strategy": "semver",
-    "current": "{VERSION}",
-    "tagPrefix": "v",
-    "sources": ["csproj", "package.json", "VERSION"]
-  },
-  "efcore": {
-    "enabled": true,
-    "validateOnCommit": true,
-    "blockDestructive": true,
-    "migrationNaming": "{context}_v{version}_{sequence}_{Description}"
-  },
-  "workflow": {
-    "push": {
-      "afterCommit": "worktree"
-    },
-    "pr": {
-      "autoLabels": true,
-      "requireReview": true
-    }
-  },
-  "language": {
-    "code": "{GF_LANG}"
-  }
-}
-```
+See [references/init-config-template.md](../references/init-config-template.md) for:
+- Full config.json v2.1.0 template (platform, workspace, repository, git, worktrees, versioning, efcore, workflow, language)
+- Path storage convention (`normalize_path_for_storage()` format)
 
-**Path storage convention:**
-- `{ROOT_FOLDER_STORAGE_FORMAT}` = result of `normalize_path_for_storage("{ROOT_FOLDER}")`
-- On WSL: `/mnt/d/projects/MyApp` → stored as `D:/projects/MyApp`
-- On Windows: `D:\projects\MyApp` → stored as `D:/projects/MyApp`
-- On Linux/macOS: `/home/user/projects/MyApp` → stored as-is
+**⛔ IMPORTANT:** Store paths using Windows-style format (`D:/path/to/folder`). The `read_gitflow_config()` in `_shared.md` translates to platform format at read time.
 
 ### 10. Detect Version
 
@@ -585,33 +399,9 @@ VERSION=$(grep -oP '<Version>\K[^<]+' "$DEVELOP_FULL_PATH"/*.csproj 2>/dev/null
 
 **⛔ MANDATORY: Verify the structure was created correctly.**
 
-```bash
-PROJECT_BASE="{ROOT_FOLDER}"
-MAIN_DIR=$([ "$WORKTREE_MODE" = "organized" ] && echo "01-Main" || echo "main")
-DEVELOP_DIR=$([ "$WORKTREE_MODE" = "organized" ] && echo "02-Develop" || echo "develop")
-ERRORS=0
-
-# Verify bare repo
-[ -f "$PROJECT_BASE/.bare/HEAD" ] && echo "✓ .bare/HEAD OK" || { echo "❌ .bare/HEAD missing"; ERRORS=$((ERRORS+1)); }
-
-# Verify worktrees on correct branches
-MAIN_BRANCH=$(git -C "$PROJECT_BASE/$MAIN_DIR" branch --show-current 2>/dev/null)
-[ "$MAIN_BRANCH" = "main" ] && echo "✓ $MAIN_DIR on main" || { echo "❌ $MAIN_DIR on '$MAIN_BRANCH', expected 'main'"; ERRORS=$((ERRORS+1)); }
-
-DEVELOP_BRANCH=$(git -C "$PROJECT_BASE/$DEVELOP_DIR" branch --show-current 2>/dev/null)
-[ "$DEVELOP_BRANCH" = "develop" ] && echo "✓ $DEVELOP_DIR on develop" || { echo "❌ $DEVELOP_DIR on '$DEVELOP_BRANCH', expected 'develop'"; ERRORS=$((ERRORS+1)); }
-
-# Verify directories
-for subdir in features releases hotfixes; do
-  [ -d "$PROJECT_BASE/$subdir" ] && echo "✓ $subdir/ OK" || { echo "❌ $subdir/ missing"; ERRORS=$((ERRORS+1)); }
-done
+See [references/init-config-template.md](../references/init-config-template.md) — Section "Post-Init Validation" for the full bash validation script.
 
-# Verify config directory
-[ -d "$PROJECT_BASE/$DEVELOP_DIR/.claude/gitflow" ] && echo "✓ .claude/gitflow/ OK" || { echo "❌ .claude/gitflow/ missing"; ERRORS=$((ERRORS+1)); }
-
-echo ""
-[ "$ERRORS" -eq 0 ] && echo "VALIDATION: ALL CHECKS PASSED" || echo "VALIDATION: $ERRORS error(s) detected - check output above"
-```
+Checks: .bare/HEAD, worktree branches (main/develop), features/releases/hotfixes dirs, .claude/gitflow/ dir.
 
 ### 11. Summary
 
@@ -694,70 +484,9 @@ Init is standalone. User should `cd 02-Develop` then run `/gitflow -f <feature-n
 
 When called with `init --workspace`, batch-initialize all repos in a workspace.
 
-### Workspace Execution Sequence:
-
-1. **Ask workspace directory:**
-```yaml
-AskUserQuestion:
-  - header: "Workspace"
-    question: "Where is the workspace root? (parent directory containing all repos)"
-    options:
-      - label: "Use parent folder (Recommended)"
-        description: "{DETECTED_FOLDER}/"
-      - label: "Custom path"
-        description: "Specify a different location"
-    multiSelect: false
-```
-
-2. **Detect or ask for repos:**
-```yaml
-AskUserQuestion:
-  - header: "Repos"
-    question: "How to identify repositories to initialize?"
-    options:
-      - label: "Detect from folders (Recommended)"
-        description: "Scan workspace for git repositories"
-      - label: "Enter URLs"
-        description: "Provide a list of repository URLs"
-    multiSelect: false
-```
-
-3. **Create `.smartstack-workspace.json`:**
-```json
-{
-  "version": "1.0.0",
-  "name": "{WORKSPACE_NAME}",
-  "createdAt": "{ISO_DATE}",
-  "updatedAt": "{ISO_DATE}",
-  "platform": {
-    "detected": "{GF_PLATFORM}",
-    "shell": "{GF_SHELL}"
-  },
-  "repositories": [],
-  "defaults": {
-    "provider": "{GIT_PROVIDER}",
-    "worktreeMode": "organized",
-    "language": "en"
-  }
-}
-```
-
-4. **Loop: For each repo, run Steps 1-10b with workspace defaults pre-populated.**
-   - Skip questions where workspace defaults apply (provider, worktree mode)
-   - Add each repo to `workspace.json` after successful init
-
-5. **Display global summary:**
-```
-╔══════════════════════════════════════════════════════════════════╗
-║                 WORKSPACE INITIALIZED                            ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Workspace: {WORKSPACE_DIR}                                      ║
-║  Platform:  {GF_PLATFORM} ({GF_SHELL})                           ║
-║  Repos:     {REPO_COUNT} initialized                             ║
-╠══════════════════════════════════════════════════════════════════╣
-{for each REPO}
-║  ✅ {REPO_NAME}                                                  ║
-║     01-Main/ ✓  02-Develop/ ✓  config.json ✓                     ║
-{end for}
-╚══════════════════════════════════════════════════════════════════╝
-```
+See [references/init-config-template.md](../references/init-config-template.md) — Section "Workspace Mode" for the full execution sequence:
+1. Ask workspace directory
+2. Detect or ask for repos
+3. Create `.smartstack-workspace.json`
+4. Loop Steps 1-10b per repo with workspace defaults
+5. Display global summary

package/templates/skills/gitflow/steps/step-plan.md

@@ -96,69 +96,12 @@ CODE_CONFLICTS=$(grep -c "<<<<<<" /tmp/merge-tree || echo "0")
 
 ### 5. Generate Plan Document
 
-**Write to `.claude/gitflow/plans/{branch-name}_{date}.md`:**
-
-```markdown
-# Integration Plan: {CURRENT} → {BASE_BRANCH}
-
-**Generated:** {timestamp}
-**Status:** PENDING
-
-## Summary
-
-| Field | Value |
-|-------|-------|
-| Source | {CURRENT} |
-| Target | {BASE_BRANCH} |
-| Commits | {COMMITS} |
-| Strategy | {MERGE_STRATEGY} |
-| Merge Back | {MERGE_BACK or "N/A"} |
-
-## Commits to Integrate
-
-{COMMIT_LIST}
-
-## EF Core Analysis
-
-| Check | Status |
-|-------|--------|
-| Branch migrations | {count} |
-| Base migrations | {count} |
-| Snapshot diverged | {yes/no} |
-| Conflict type | {none/migration/code/both} |
-
-## Pre-Integration Steps
-
-{if migration conflict}
-1. [ ] Run `/efcore:rebase-snapshot`
-2. [ ] Verify migration generates same schema
-3. [ ] Run `/gitflow sync`
-{endif}
-
-{if code conflict}
-1. [ ] Run `/gitflow sync` (includes rebase)
-2. [ ] Resolve conflicts manually
-3. [ ] Verify build passes
-{endif}
-
-## Integration Steps
-
-1. [ ] Create PR: `/gitflow pr`
-2. [ ] Review and approve
-3. [ ] Merge: `/gitflow merge`
-{if release or hotfix}
-4. [ ] Merge back to develop
-5. [ ] Create tag: v{VERSION}
-{endif}
-6. [ ] Cleanup: `/gitflow finish`
-
-## Post-Integration
-
-- [ ] Verify CI/CD passes
-- [ ] Verify migrations applied
-- [ ] Delete source branch
-- [ ] Remove worktree
-```
+See [references/plan-template.md](../references/plan-template.md) for the complete plan document template written to `.claude/gitflow/plans/{branch-name}_{date}.md`:
+- Summary table (source, target, commits, strategy, merge-back)
+- Commits list, EF Core analysis table
+- Pre-integration steps (conditional on migration/code conflicts)
+- Integration steps (conditional on release/hotfix)
+- Post-integration checklist
 
 ### 6. Display Plan Summary