@atlashub/smartstack-cli 4.38.0 → 4.40.0

package/templates/skills/efcore/SKILL.md

@@ -24,6 +24,7 @@ Parse `$ARGUMENTS` to determine the command:
 | `migration` | **Agent** `efcore-migration` | sonnet |
 | `squash` | **Agent** `efcore-squash` | sonnet |
 | `rebase-snapshot` | **Agent** `efcore-rebase-snapshot` | sonnet |
+| (none) | **Inline** `<command-help>` | — |
 
 **Inline commands:** Execute directly following the matching `<command-*>` section below.
 **Agent commands:** Delegate via Agent tool:
@@ -31,11 +32,19 @@ Parse `$ARGUMENTS` to determine the command:
 Agent(
   subagent_type: "{agent_name}",
   model: "sonnet",
-  prompt: "Execute /efcore {command} in {cwd}. Branch: {branch}. Flags: {flags}. Description: {description}"
+  prompt: "Execute /efcore {command}.
+    Working directory: {cwd}
+    Branch: {branch}
+    Context: {--context value if provided, else 'auto-detect'}
+    Force: {true if --force flag, else false}
+    Description: {user description if provided}
+  "
 )
 ```
 
-**Flags:** `--context <name>` (CoreDbContext/ExtensionsDbContext), `--force` (skip confirmations)
+**Flags:**
+- `--context <name>` — Force DbContext (`CoreDbContext` or `ExtensionsDbContext`), skip auto-detection
+- `--force` — Skip all confirmations (backup still created)
 
 </routing>
 
@@ -91,6 +100,8 @@ Pattern: `{context}_v{version}_{sequence}_{Description}`
 
 **READ-ONLY: Never modify database or migrations.**
 
+> **Troubleshooting:** See `references/troubleshooting.md` for common errors.
+
 1. Call MCP `mcp__smartstack__check_migrations` with `branch: {current_branch}`
 2. If MCP unavailable, fallback: `dotnet ef migrations list --no-build --context {Context}` per context
 3. Display compact summary
@@ -117,11 +128,14 @@ BRANCH: {branch}
 
 **ONLY runs `dotnet ef database update`. Never creates/deletes migrations.**
 
-1. Verify `appsettings.Local.json` exists in the API project
-2. Apply Core: `dotnet ef database update --context CoreDbContext --verbose`
-3. Apply Extensions: `dotnet ef database update --context ExtensionsDbContext --verbose`
+> **Reference:** See `references/database-operations.md` for connection test and migration count utilities.
+
+1. Detect projects: `INFRA_PROJECT=$(find src -name "*Infrastructure.csproj" | head -1)` and `STARTUP_PROJECT=$(find src -name "*.Api.csproj" | head -1)`
+2. Verify `appsettings.Local.json` exists in the API project
+3. Apply Core: `dotnet ef database update --context CoreDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT" --verbose`
+4. Apply Extensions: `dotnet ef database update --context ExtensionsDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT" --verbose`
 
-If connection fails: suggest verifying SQL Server, appsettings.Local.json, or `/efcore db-reset`.
+If connection fails: suggest verifying SQL Server, appsettings.Local.json, or `/efcore db-reset`. See `references/troubleshooting.md`.
 
 ```
 DB DEPLOY
@@ -138,15 +152,18 @@ DB DEPLOY
 
 **ONLY operates on database. Never creates/deletes migration files.**
 
-1. **Confirm** (MANDATORY unless `--force`):
+> **Reference:** See `references/reset-operations.md` for drop/recreate commands.
+
+1. Detect projects: `INFRA_PROJECT=$(find src -name "*Infrastructure.csproj" | head -1)` and `STARTUP_PROJECT=$(find src -name "*.Api.csproj" | head -1)`
+2. **Confirm** (MANDATORY unless `--force`):
    ```
    AskUserQuestion({ question: "DELETE the database? All data will be lost.", options: ["Yes, delete", "No, cancel"] })
    ```
-2. **Backup** (optional): `sqlcmd -S "$SERVER" -E -Q "BACKUP DATABASE [$DB] TO DISK='$FILE' WITH FORMAT, INIT, COMPRESSION"`
-3. **Drop**: `dotnet ef database drop --force`
-4. **Recreate Core**: `dotnet ef database update --context CoreDbContext`
-5. **Recreate Extensions**: `dotnet ef database update --context ExtensionsDbContext`
-6. **Ask** if user wants `/efcore db-seed`
+3. **Backup** (optional): `sqlcmd -S "$SERVER" -E -Q "BACKUP DATABASE [$DB] TO DISK='$FILE' WITH FORMAT, INIT, COMPRESSION"`
+4. **Drop**: `dotnet ef database drop --force --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
+5. **Recreate Core**: `dotnet ef database update --context CoreDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
+6. **Recreate Extensions**: `dotnet ef database update --context ExtensionsDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
+7. **Ask** if user wants `/efcore db-seed`
 
 Block if ASPNETCORE_ENVIRONMENT=Production.
 
@@ -167,6 +184,8 @@ Next: /efcore db-status, /efcore db-seed
 
 **Never drop or recreate database.**
 
+> **Reference:** See `references/seed-methods.md` for detection and execution details.
+
 1. **Detect** seeding method:
    - `HasData()` in EF configs → apply via `dotnet ef database update --context {Context}`
    - `IDataSeeder` / `--seed` CLI arg → `dotnet run --project {startup} -- --seed`
@@ -250,3 +269,27 @@ If conflict:
 ```
 
 </command-conflicts>
+
+<command-help>
+
+## (no command) — Show available commands
+
+Display the list of available `/efcore` commands:
+
+```
+EF CORE COMMANDS
+────────────────
+  db-status         Migration state check
+  db-deploy         Apply pending migrations
+  db-reset          Drop + recreate database
+  db-seed           Populate test data
+  scan              Cross-branch migration scanner
+  conflicts         Migration conflict analyzer
+  migration         Create/recreate migration
+  squash            Consolidate migrations
+  rebase-snapshot   Resync ModelSnapshot with parent
+
+Usage: /efcore <command> [--context <name>] [--force]
+```
+
+</command-help>

package/templates/skills/efcore/references/database-operations.md

@@ -7,8 +7,7 @@
 ```bash
 # Validate required variables from step-00-init
 for VAR_NAME in DBCONTEXT DBCONTEXT_TYPE INFRA_PROJECT STARTUP_PROJECT SELECTED_ENV; do
-  eval VAR_VALUE=\$$VAR_NAME
-  if [ -z "$VAR_VALUE" ]; then
+  if [ -z "${!VAR_NAME}" ]; then
     echo "ERROR: Required variable $VAR_NAME is not set"
     echo "Run step-00-init first"
     exit 1
@@ -38,7 +37,7 @@ fi
 ## Connection Test
 
 ```bash
-CONNECTION_TEST=$(dotnet ef database list \
+CONNECTION_TEST=$(dotnet ef migrations list \
   --context "$DBCONTEXT" \
   --project "$INFRA_PROJECT" \
   --startup-project "$STARTUP_PROJECT" 2>&1)

package/templates/skills/efcore/references/seed-methods.md

@@ -27,7 +27,7 @@ if grep -q "\-\-seed" ./src/*/Program.cs 2>/dev/null; then
 fi
 
 # WARNING: SQL scripts detected
-if [ -f "./scripts/seed.sql" ] || find . -name "seed*.sql" 2>/dev/null | grep -q .; then
+if [ -f "./scripts/seed.sql" ] || find src -name "seed*.sql" -not -path "*/bin/*" -not -path "*/obj/*" 2>/dev/null | grep -q .; then
   echo ""
   echo "WARNING: SQL seed scripts detected - FORBIDDEN by conventions"
   echo "Migrate to HasData() or IDataSeeder"

package/templates/skills/efcore/references/shared-init-functions.md

@@ -58,7 +58,7 @@ the .NET SDK may not be found even if `dotnet-ef` is. Use `$USERPROFILE` first o
 ```bash
 detect_efcore_project() {
   # Find project with EF Core reference
-  CSPROJ=$(find . -name "*.csproj" -exec grep -l "Microsoft.EntityFrameworkCore" {} \; | head -1)
+  CSPROJ=$(find src-name "*.csproj" -exec grep -l "Microsoft.EntityFrameworkCore" {} \; | head -1)
 
   if [ -z "$CSPROJ" ]; then
     echo "ERROR: No EF Core project found"
@@ -70,8 +70,8 @@ detect_efcore_project() {
   MIGRATIONS_DIR="$PROJECT_DIR/Persistence/Migrations"
 
   # Find startup and infrastructure projects
-  STARTUP_PROJECT=$(find . -name "*.Api.csproj" -o -name "*Web.csproj" | head -1)
-  INFRA_PROJECT=$(find . -name "*Infrastructure.csproj" | head -1)
+  STARTUP_PROJECT=$(find src-name "*.Api.csproj" -o -name "*Web.csproj" | head -1)
+  INFRA_PROJECT=$(find src-name "*Infrastructure.csproj" | head -1)
   [ -z "$INFRA_PROJECT" ] && INFRA_PROJECT="$CSPROJ"
 
   echo "Project: $PROJECT_NAME"
@@ -84,7 +84,7 @@ detect_efcore_project() {
 ```bash
 detect_dbcontext() {
   # Priority 1: SmartStack.Domain exists → SmartStack source project (Core only)
-  if find . -type d -name "SmartStack.Domain" | grep -q .; then
+  if find src-type d -name "SmartStack.Domain" | grep -q .; then
     DBCONTEXT="CoreDbContext"
     DBCONTEXT_TYPE="core"
     SCHEMA="core"
@@ -94,7 +94,7 @@ detect_dbcontext() {
   fi
 
   # Priority 2: Client project with SmartStack NuGet → BOTH contexts
-  if find . -name "*.csproj" -exec grep -ql "PackageReference.*SmartStack" {} \; 2>/dev/null; then
+  if find src-name "*.csproj" -exec grep -ql "PackageReference.*SmartStack" {} \; 2>/dev/null; then
     DBCONTEXT="CoreDbContext"
     DBCONTEXT_TYPE="both"
     SCHEMA="core"
@@ -105,8 +105,8 @@ detect_dbcontext() {
   fi
 
   # Priority 3: Scan for DbContext in code
-  CORE_CTX=$(find . -name "*.cs" -exec grep -l "CoreDbContext" {} \; 2>/dev/null | head -1)
-  EXT_CTX=$(find . -name "*.cs" -exec grep -l "ExtensionsDbContext" {} \; 2>/dev/null | head -1)
+  CORE_CTX=$(find src-name "*.cs" -exec grep -l "CoreDbContext" {} \; 2>/dev/null | head -1)
+  EXT_CTX=$(find src-name "*.cs" -exec grep -l "ExtensionsDbContext" {} \; 2>/dev/null | head -1)
 
   if [ -n "$CORE_CTX" ] && [ -n "$EXT_CTX" ]; then
     DBCONTEXT="CoreDbContext"
@@ -137,7 +137,7 @@ detect_dbcontext() {
 
 ```bash
 detect_environment() {
-  API_DIR=$(find . -type d -name "*.Api" | head -1)
+  API_DIR=$(find src-type d -name "*.Api" | head -1)
   [ -z "$API_DIR" ] && API_DIR="src/SmartStack.Api"
 
   # Priority: --env flag > appsettings.Local.json > error

package/templates/skills/efcore/references/zero-downtime-patterns.md

@@ -2,6 +2,8 @@
 Zero-downtime migration patterns for EF Core. Use when a migration contains destructive operations (column rename, type change, column drop) that could cause downtime during deployment.
 
 These patterns apply to production deployments where the application runs continuously. For development environments, standard migrations are sufficient.
+
+> **Exception to "no raw SQL" rule:** `migrationBuilder.Sql(...)` is authorized ONLY for data backfill operations within zero-downtime migration patterns (e.g., `UPDATE ... SET NewCol = OldCol`). Never use it for DDL (CREATE/ALTER/DROP) — those must go through EF Core Fluent API or `SqlObjects/`.
 </overview>
 
 <when_to_use>

package/templates/skills/gitflow/phases/cleanup.md

@@ -60,9 +60,21 @@ while read -r line; do
     continue
   fi
 
+  # Skip permanent branches
+  [[ "$WT_BRANCH" == "$GF_MAIN_BRANCH" ]] || [[ "$WT_BRANCH" == "$GF_DEVELOP_BRANCH" ]] && {
+    VALID+=("$WT_PATH:$WT_BRANCH")
+    continue
+  }
+
   # Check if branch still exists on remote
   REMOTE_EXISTS=$(git branch -r --list "origin/$WT_BRANCH" | wc -l)
-  if [ "$REMOTE_EXISTS" -eq 0 ] && [[ "$WT_BRANCH" != "$GF_MAIN_BRANCH" ]] && [[ "$WT_BRANCH" != "$GF_DEVELOP_BRANCH" ]]; then
+
+  # Check if branch is merged into develop or main
+  MERGED_INTO_DEVELOP=$(git branch --merged "$GF_DEVELOP_BRANCH" | grep -c "$WT_BRANCH" 2>/dev/null || echo 0)
+  MERGED_INTO_MAIN=$(git branch --merged "$GF_MAIN_BRANCH" | grep -c "$WT_BRANCH" 2>/dev/null || echo 0)
+
+  # Stale if: no remote OR already merged
+  if [ "$REMOTE_EXISTS" -eq 0 ] || [ "$MERGED_INTO_DEVELOP" -gt 0 ] || [ "$MERGED_INTO_MAIN" -gt 0 ]; then
     STALE+=("$WT_PATH:$WT_BRANCH")
     continue
   fi
@@ -166,10 +178,14 @@ AskUserQuestion:
 # Remove orphaned
 for item in "${ORPHANED[@]}"; do
   WT_PATH=$(echo "$item" | cut -d':' -f1)
+  WT_BRANCH=$(echo "$item" | cut -d':' -f2)
   git worktree remove "$WT_PATH" --force 2>/dev/null || rm -rf "$WT_PATH"
+  # Delete remote branch if exists
+  git push origin --delete "$WT_BRANCH" 2>/dev/null
+  git branch -D "$WT_BRANCH" 2>/dev/null
 done
 
-# Prune
+# Prune stale worktree references
 git worktree prune
 
 # Remove stale
@@ -178,15 +194,29 @@ for item in "${STALE[@]}"; do
   WT_BRANCH=$(echo "$item" | cut -d':' -f2)
 
   git worktree remove "$WT_PATH" --force 2>/dev/null || rm -rf "$WT_PATH"
+  # Delete remote branch if exists
+  git push origin --delete "$WT_BRANCH" 2>/dev/null
   git branch -D "$WT_BRANCH" 2>/dev/null
 done
+
+# Final prune after all removals
+git worktree prune
 ```
 
 **Branches:**
 ```bash
-# Delete merged branches
+# Delete merged branches (local + remote)
 for branch in "${MERGED_BRANCHES[@]}"; do
   git branch -d "$branch"
+  git push origin --delete "$branch" 2>/dev/null
+done
+```
+
+**Empty parent directories:**
+```bash
+# Clean up empty worktree parent directories
+for dir in "$GF_FEATURES_DIR" "$GF_RELEASES_DIR" "$GF_HOTFIXES_DIR"; do
+  [ -d "$dir" ] && [ -z "$(ls -A "$dir" 2>/dev/null)" ] && rm -rf "$dir"
 done
 ```