@atlashub/smartstack-cli 3.37.0 → 3.39.0

package/templates/skills/efcore/references/troubleshooting.md

@@ -0,0 +1,81 @@
+# EF Core Troubleshooting
+
+## Database Status
+
+### Troubleshooting (if connection fails)
+
+```
+TROUBLESHOOTING
+├── SQL Server running?
+├── appsettings.Local.json configured?
+├── Database exists?
+└── Commands: /efcore db-reset, /efcore db-deploy
+```
+
+## Deploy Errors
+
+| Error | Resolution |
+|-------|------------|
+| Connection failed | Check SQL Server, credentials |
+| Migration error | Review migration, consider reset |
+| Constraint violation | Check data, may need seed |
+
+## Reset Protections
+
+| Protection | Description |
+|------------|-------------|
+| Env Display | Shows database BEFORE confirmation |
+| Confirmation | Explicit request with database NAME |
+| Production Block | Blocks if Production detected |
+| EF Core Only | No raw SQL |
+
+## Seed Setup Guide
+
+If no seed methods detected, display guide:
+
+```
+SEED SETUP GUIDE
+================
+
+Option 1: HasData() in Configuration (RECOMMENDED)
+--------------------------------------------------
+// In UserConfiguration.cs
+builder.HasData(new User {
+    Id = Guid.Parse("7f3c9a2e-8d1b-4e5f-a6c8-9b4d2f7e1a3c"),
+    Name = "Admin",
+    Email = "admin@example.com"
+});
+
+// Then run:
+dotnet ef migrations add SeedData
+
+Option 2: IDataSeeder Class
+---------------------------
+public class UserSeeder : IDataSeeder
+{
+    public async Task SeedAsync(DbContext context)
+    {
+        if (!await context.Users.AnyAsync())
+        {
+            context.Users.Add(new User { ... });
+            await context.SaveChangesAsync();
+        }
+    }
+}
+
+// Register in Program.cs and call via --seed argument
+```
+
+## Migration from SQL
+
+```csharp
+// BEFORE (FORBIDDEN): scripts/seed.sql
+INSERT INTO Users (Id, Name) VALUES (1, 'Admin');
+
+// AFTER (CORRECT): UserConfiguration.cs
+builder.HasData(new User {
+    Id = Guid.Parse("7f3c9a2e-8d1b-4e5f-a6c8-9b4d2f7e1a3c"),
+    Name = "Admin"
+});
+// Then: dotnet ef migrations add SeedData
+```

package/templates/skills/efcore/steps/db/step-deploy.md

@@ -208,38 +208,7 @@ Next: /efcore db-status, /efcore db-seed
 
 ## BOTH CONTEXTS:
 
-**If `RUN_BOTH=true` (auto-detected for client projects with SmartStack NuGet):**
-
-Run the full deploy sequence (steps 2-6) TWICE, in order:
-
-```bash
-# 1. Deploy CoreDbContext first (system tables: Users, Roles, Tenants...)
-echo "=== Deploying CoreDbContext (core schema) ==="
-DBCONTEXT="CoreDbContext"
-SCHEMA="core"
-# Run steps 2-6 with CoreDbContext...
-
-dotnet ef database update \
-  --context "CoreDbContext" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT" \
-  --verbose
-
-# 2. Then ExtensionsDbContext (client tables)
-echo ""
-echo "=== Deploying ExtensionsDbContext (extensions schema) ==="
-DBCONTEXT="ExtensionsDbContext"
-SCHEMA="extensions"
-# Run steps 2-6 with ExtensionsDbContext...
-
-dotnet ef database update \
-  --context "ExtensionsDbContext" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT" \
-  --verbose
-```
-
-**Order matters:** Core MUST be deployed first (Extensions may have foreign keys to Core tables).
+Load: `references/both-contexts.md`
 
 ---
 

package/templates/skills/efcore/steps/db/step-reset.md

@@ -32,17 +32,9 @@ Completely reset the database: drop, recreate, and apply all migrations.
 
 ### 1. Environment Check
 
-```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
-    echo "ERROR: Required variable $VAR_NAME is not set"
-    echo "Run step-00-init first"
-    exit 1
-  fi
-done
+Load validation: `references/database-operations.md#check-required-variables`
 
+```bash
 echo "Reset Configuration"
 echo "==================="
 echo ""
@@ -93,66 +85,15 @@ AskUserQuestion:
 
 **If backup requested:**
 
-```bash
-BACKUP_DIR=".claude/gitflow/backup/database"
-mkdir -p "$BACKUP_DIR"
-
-BACKUP_FILE="$BACKUP_DIR/${DATABASE_NAME}_$(date +%Y%m%d_%H%M%S).bak"
-
-echo "Creating backup: $BACKUP_FILE"
-
-sqlcmd -S "$SERVER_NAME" -E -Q "BACKUP DATABASE [$DATABASE_NAME] TO DISK='$BACKUP_FILE'"
-
-if [ $? -eq 0 ]; then
-  echo "Backup created: $BACKUP_FILE"
-else
-  echo "WARNING: Backup failed. Continue anyway?"
-fi
-```
+Load: `references/database-operations.md#backup-command`
 
 ### 4. Drop Database
 
-```bash
-echo ""
-echo "Dropping database..."
-
-dotnet ef database drop \
-  --context "$DBCONTEXT" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT" \
-  --force
-EXIT_CODE=$?
-
-if [ $EXIT_CODE -ne 0 ]; then
-  echo "ERROR: Drop failed (exit code: $EXIT_CODE)"
-  echo "Database may be in use. Close connections and retry."
-  exit 1
-fi
-
-echo "Database dropped."
-```
+Load: `references/reset-operations.md#drop-database`
 
 ### 5. Recreate + Apply Migrations
 
-```bash
-echo ""
-echo "Recreating database with migrations..."
-
-dotnet ef database update \
-  --context "$DBCONTEXT" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT" \
-  --verbose
-EXIT_CODE=$?
-
-if [ $EXIT_CODE -ne 0 ]; then
-  echo ""
-  echo "ERROR: Recreation failed (exit code: $EXIT_CODE)"
-  exit 1
-fi
-
-echo "Database recreated."
-```
+Load: `references/reset-operations.md#recreate--apply-migrations`
 
 ### 6. Optional Seed
 
@@ -181,39 +122,7 @@ dotnet run --project "$STARTUP_PROJECT" -- --seed 2>/dev/null || echo "No --seed
 
 ### 7. Summary
 
-```bash
-MIGRATION_COUNT=$(dotnet ef migrations list \
-  --context "$DBCONTEXT" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT" 2>/dev/null | \
-  grep -c "^[0-9]" || echo "0")
-
-echo ""
-echo "==========================================="
-echo "RESET COMPLETE"
-echo "==========================================="
-echo ""
-echo "Database:    $DATABASE_NAME"
-echo "Environment: $SELECTED_ENV"
-echo "DbContext:   $DBCONTEXT"
-echo ""
-echo "Operations:"
-echo "  - Drop: OK"
-echo "  - Create: OK"
-echo "  - Migrations: $MIGRATION_COUNT applied"
-if [ -n "$BACKUP_FILE" ]; then
-echo "  - Backup: $BACKUP_FILE"
-fi
-echo ""
-echo "Compliance:  EF Core CLI only"
-echo ""
-echo "==========================================="
-echo ""
-echo "Next steps:"
-echo "  /efcore db-status    # Verify status"
-echo "  /efcore db-seed      # Add test data"
-echo ""
-```
+Load: `references/reset-operations.md#summary-after-reset`
 
 ---
 
@@ -241,12 +150,7 @@ Next: /efcore db-status, /efcore db-seed
 
 ## PROTECTIONS:
 
-| Protection | Description |
-|------------|-------------|
-| Env Display | Shows database BEFORE confirmation |
-| Confirmation | Explicit request with database NAME |
-| Production Block | Blocks if Production detected |
-| EF Core Only | No raw SQL |
+Load: `references/troubleshooting.md#reset-protections`
 
 ---
 

package/templates/skills/efcore/steps/db/step-seed.md

@@ -28,17 +28,9 @@ Populate the database with test or initial data using EF Core conventions.
 
 ### 1. Environment Check
 
-```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
-    echo "ERROR: Required variable $VAR_NAME is not set"
-    echo "Run step-00-init first"
-    exit 1
-  fi
-done
+Load validation: `references/database-operations.md#check-required-variables`
 
+```bash
 echo "Seed Configuration"
 echo "=================="
 echo ""
@@ -52,41 +44,7 @@ block_production
 
 ### 2. Detect Available Seed Methods
 
-```bash
-echo ""
-echo "Detecting seed methods..."
-
-SEED_METHODS=""
-
-# HasData() in configurations (RECOMMENDED)
-if grep -rq "\.HasData(" . --include="*.cs" 2>/dev/null; then
-  SEED_METHODS+=" hasdata"
-  echo "  - HasData(): Found"
-fi
-
-# IDataSeeder classes
-if grep -rq "IDataSeeder\|class.*Seeder" . --include="*.cs" 2>/dev/null; then
-  SEED_METHODS+=" seeder-class"
-  echo "  - Seeder classes: Found"
-fi
-
-# --seed CLI argument
-if grep -q "\-\-seed" ./src/*/Program.cs 2>/dev/null; then
-  SEED_METHODS+=" cli-argument"
-  echo "  - CLI --seed: Found"
-fi
-
-# WARNING: SQL scripts detected
-if [ -f "./scripts/seed.sql" ] || find . -name "seed*.sql" 2>/dev/null | grep -q .; then
-  echo ""
-  echo "WARNING: SQL seed scripts detected - FORBIDDEN by conventions"
-  echo "Migrate to HasData() or IDataSeeder"
-fi
-
-if [ -z "$SEED_METHODS" ]; then
-  echo "  No seed methods found"
-fi
-```
+Load: `references/seed-methods.md#detect-available-seed-methods`
 
 ### 3. Select Method
 
@@ -108,52 +66,15 @@ AskUserQuestion:
 
 ### 4. Execute Seed
 
-**HasData method:**
-
-```bash
-echo ""
-echo "HasData is applied via migrations."
-echo "Running database update to ensure all HasData is applied..."
-
-dotnet ef database update \
-  --context "$DBCONTEXT" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT"
-```
-
-**Seeder Class method:**
-
-```bash
-echo ""
-echo "Running seeder class..."
+Load execution methods from: `references/seed-methods.md#execute-seed-*`
 
-dotnet run --project "$STARTUP_PROJECT" -- --seed
-EXIT_CODE=$?
-
-if [ $EXIT_CODE -ne 0 ]; then
-  echo "Seed command failed or not supported (exit code: $EXIT_CODE)"
-  echo "Check if --seed argument is implemented in Program.cs"
-fi
-```
-
-**CLI argument method:**
-
-```bash
-echo ""
-echo "Running application with --seed..."
-
-dotnet run --project "$STARTUP_PROJECT" -- --seed
-```
+- HasData: `references/seed-methods.md#execute-seed---hasdata`
+- Seeder Class: `references/seed-methods.md#execute-seed---seeder-class`
+- CLI Argument: `references/seed-methods.md#execute-seed---cli-argument`
 
 ### 5. Verify (Optional)
 
-```bash
-echo ""
-echo "Verifying seed data..."
-
-# Quick check - count records in key tables
-# This is application-specific
-```
+Load: `references/seed-methods.md#verify-seed-data`
 
 ### 6. Summary
 
@@ -197,56 +118,13 @@ Next: /efcore db-status, dotnet run
 
 ## NO SEED METHODS FOUND:
 
-If no seed methods detected, display guide:
-
-```
-SEED SETUP GUIDE
-================
-
-Option 1: HasData() in Configuration (RECOMMENDED)
---------------------------------------------------
-// In UserConfiguration.cs
-builder.HasData(new User {
-    Id = Guid.Parse("7f3c9a2e-8d1b-4e5f-a6c8-9b4d2f7e1a3c"),
-    Name = "Admin",
-    Email = "admin@example.com"
-});
-
-// Then run:
-dotnet ef migrations add SeedData
-
-Option 2: IDataSeeder Class
----------------------------
-public class UserSeeder : IDataSeeder
-{
-    public async Task SeedAsync(DbContext context)
-    {
-        if (!await context.Users.AnyAsync())
-        {
-            context.Users.Add(new User { ... });
-            await context.SaveChangesAsync();
-        }
-    }
-}
-
-// Register in Program.cs and call via --seed argument
-```
+Load: `references/troubleshooting.md#seed-setup-guide`
 
 ---
 
 ## MIGRATION FROM SQL:
 
-```csharp
-// BEFORE (FORBIDDEN): scripts/seed.sql
-INSERT INTO Users (Id, Name) VALUES (1, 'Admin');
-
-// AFTER (CORRECT): UserConfiguration.cs
-builder.HasData(new User {
-    Id = Guid.Parse("7f3c9a2e-8d1b-4e5f-a6c8-9b4d2f7e1a3c"),
-    Name = "Admin"
-});
-// Then: dotnet ef migrations add SeedData
-```
+Load: `references/troubleshooting.md#migration-from-sql`
 
 ---
 

package/templates/skills/efcore/steps/db/step-status.md

@@ -20,17 +20,7 @@ Display comprehensive status of EF Core migrations and database connection.
 
 ### 0. Validate Required Variables
 
-```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
-    echo "ERROR: Required variable $VAR_NAME is not set"
-    echo "Run step-00-init first"
-    exit 1
-  fi
-done
-```
+Load: `references/database-operations.md#check-required-variables`
 
 ### 1. Display Configuration
 
@@ -48,23 +38,7 @@ echo "Config:      $CONFIG_FILE"
 
 ### 2. Test Database Connection
 
-```bash
-echo ""
-echo "Testing connection..."
-
-CONNECTION_TEST=$(dotnet ef database list \
-  --context "$DBCONTEXT" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT" 2>&1)
-
-if [ $? -eq 0 ]; then
-  echo "Connection:  OK"
-else
-  echo "Connection:  FAILED"
-  echo ""
-  echo "$CONNECTION_TEST"
-fi
-```
+Load: `references/database-operations.md#connection-test`
 
 ### 3. List Migrations
 
@@ -80,16 +54,9 @@ dotnet ef migrations list \
 
 ### 4. Count Applied vs Pending
 
-```bash
-MIGRATION_OUTPUT=$(dotnet ef migrations list \
-  --context "$DBCONTEXT" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$STARTUP_PROJECT" 2>/dev/null)
-
-APPLIED=$(echo "$MIGRATION_OUTPUT" | grep -v "(Pending)" | grep -c "^[0-9]" || echo "0")
-PENDING=$(echo "$MIGRATION_OUTPUT" | grep -c "(Pending)" || echo "0")
-TOTAL=$((APPLIED + PENDING))
+Load: `references/database-operations.md#migration-count-utilities`
 
+```bash
 echo ""
 echo "Summary:"
 echo "  Total:    $TOTAL migrations"
@@ -187,13 +154,7 @@ Next: /efcore db-deploy
 
 ## TROUBLESHOOTING (if connection fails):
 
-```
-TROUBLESHOOTING
-├── SQL Server running?
-├── appsettings.Local.json configured?
-├── Database exists?
-└── Commands: /efcore db-reset, /efcore db-deploy
-```
+Load: `references/troubleshooting.md#database-status`
 
 ---
 

package/templates/skills/efcore/steps/migration/step-02-create.md

@@ -107,20 +107,7 @@ dotnet ef migrations add "$MIGRATION_NAME" \
   --verbose
 ```
 
-### 6. Cleanup EF Core Design-Time Artifacts
-
-```bash
-# EF Core's Roslyn BuildHost creates corrupted bin folders on Windows (U+F05C instead of backslash)
-# Clean up any bin*Debug folders that are NOT the normal bin/Debug path
-for d in src/*/bin?Debug; do
-  if [ -d "$d" ]; then
-    echo "Removing corrupted EF Core artifact: $d"
-    rm -rf "$d"
-  fi
-done
-```
-
-### 7. Verify Creation
+### 6. Verify Creation
 
 ```bash
 # Check files were created

package/templates/skills/efcore/steps/migration/step-03-validate.md

@@ -90,6 +90,8 @@ AskUserQuestion:
   multiSelect: false
 ```
 
+See: `references/destructive-operations.md` for zero-downtime patterns.
+
 ### 4. Handle Response
 
 ```javascript
@@ -146,68 +148,12 @@ exit 0
 
 ### 6. Final Summary
 
-```bash
-echo ""
-echo "==========================================="
-echo "MIGRATION COMPLETE"
-echo "==========================================="
-echo ""
-echo "Branch:      $CURRENT_BRANCH"
-echo "DbContext:   $DBCONTEXT ($DBCONTEXT_TYPE)"
-echo ""
-echo "Migration:   $MIGRATION_NAME"
-echo "Files:"
-echo "  - ${MIGRATION_NAME}.cs"
-echo "  - ${MIGRATION_NAME}.Designer.cs"
-echo "  - ${DBCONTEXT}ModelSnapshot.cs (updated)"
-echo ""
-echo "Content:"
-echo "  Tables:      $UP_TABLES"
-echo "  Columns:     $UP_COLUMNS"
-echo "  Indexes:     $UP_INDEXES"
-echo "  Foreign Keys:$UP_FOREIGN"
-echo ""
-if [ "$ACTION" = "deploy" ]; then
-  echo "Status:      Applied to local database"
-else
-  echo "Status:      Created (not applied)"
-  echo "             Run /efcore db-deploy to apply"
-fi
-echo ""
-echo "==========================================="
-echo ""
-echo "Next steps:"
-echo "  /gitflow commit       # Commit changes"
-echo "  /efcore db-status     # Check database status"
-echo ""
-```
-
----
-
-## OUTPUT FORMAT:
-
-```
-MIGRATION COMPLETE
-==================
-Branch:      {current_branch}
-DbContext:   {dbcontext} ({dbcontext_type})
-
-Migration:   {migration_name}
-Files:
-  - {migration_name}.cs
-  - {migration_name}.Designer.cs
-  - {dbcontext}ModelSnapshot.cs (updated)
-
-Content:
-  Tables:      {count}
-  Columns:     {count}
-  Indexes:     {count}
-  Foreign Keys:{count}
-
-Status:      {Applied | Created (not applied)}
-
-Next: /gitflow commit, /efcore db-status
-```
+Create summary output showing:
+- Branch, DbContext, DbContext Type
+- Migration name and files
+- Content statistics (tables, columns, indexes, foreign keys)
+- Status (Applied or Created)
+- Next steps
 
 ---
 

package/templates/skills/efcore/steps/rebase-snapshot/step-03-create.md

@@ -89,63 +89,7 @@ echo "  $DESIGNER_FILE"
 
 ### 5. Inject SQL Objects (Functions, Views, SP)
 
-EF Core does NOT generate DDL for TVF, views, and stored procedures.
-SQL source scripts are in `Persistence/SqlObjects/` (Embedded Resources).
-After a rebase-snapshot, they must be re-injected into the consolidated migration.
-
-```bash
-# Check if SqlObjects folder exists with .sql files
-SQL_OBJECTS_DIR="$INFRA_PROJECT_DIR/Persistence/SqlObjects"
-SQL_FILES=$(find "$SQL_OBJECTS_DIR" -name "*.sql" 2>/dev/null | wc -l)
-
-if [ "$SQL_FILES" -gt 0 ]; then
-  echo ""
-  echo "Found $SQL_FILES SQL object(s) in SqlObjects/"
-  echo "Injecting SqlObjectHelper.ApplyAll(migrationBuilder) into migration..."
-
-  # Validate migration file path before sed operations
-  if [ ! -f "$MIGRATION_FILE" ]; then
-    echo "ERROR: Migration file not found: $MIGRATION_FILE"
-    exit 1
-  fi
-  if ! echo "$MIGRATION_FILE" | grep -qE '\.cs$'; then
-    echo "ERROR: Invalid migration file path (not .cs): $MIGRATION_FILE"
-    exit 1
-  fi
-
-  # Add using directive if not present
-  if ! grep -q "using SmartStack.Infrastructure.Persistence.SqlObjects;" "$MIGRATION_FILE"; then
-    sed -i '1s/^/using SmartStack.Infrastructure.Persistence.SqlObjects;\n/' "$MIGRATION_FILE"
-  fi
-
-  # Add SqlObjectHelper.ApplyAll at the end of Up() method
-  sed -i '/protected override void Up/,/^        }/ {
-    /^        }/ i\
-\            // Apply SQL objects (TVF, Views, SP) from embedded resources\
-\            SqlObjectHelper.ApplyAll(migrationBuilder);
-  }' "$MIGRATION_FILE"
-
-  # Verify injection succeeded (fallback to manual step if sed pattern didn't match)
-  if ! grep -q "SqlObjectHelper.ApplyAll" "$MIGRATION_FILE"; then
-    echo "WARNING: Automatic injection failed (indentation pattern may differ)"
-    echo ""
-    echo "MANUAL STEP REQUIRED: Add these lines inside the Up() method before the closing brace:"
-    echo '    using SmartStack.Infrastructure.Persistence.SqlObjects;'
-    echo '    ...'
-    echo '    SqlObjectHelper.ApplyAll(migrationBuilder);'
-    echo ""
-    echo "File: $MIGRATION_FILE"
-  else
-    echo "  SqlObjectHelper.ApplyAll(migrationBuilder) injected"
-  fi
-  find "$SQL_OBJECTS_DIR" -name "*.sql" -exec basename {} \; | while read f; do
-    echo "  - $f"
-  done
-else
-  echo ""
-  echo "No SQL objects found in SqlObjects/ - skipping injection"
-fi
-```
+Load: `references/sql-objects-injection.md`
 
 ---