@atlashub/smartstack-cli 3.53.0 → 4.0.0

package/package.json

@@ -1,115 +1,115 @@
-{
-  "name": "@atlashub/smartstack-cli",
-  "version": "3.53.0",
-  "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
-  "author": {
-    "name": "SmartStack",
-    "email": "contact@smartstack.app",
-    "url": "https://smartstack.app"
-  },
-  "license": "MIT",
-  "private": false,
-  "type": "commonjs",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "smartstack": "./dist/index.js",
-    "ss": "./dist/index.js",
-    "smartstack-mcp": "./dist/mcp-entry.mjs"
-  },
-  "files": [
-    "dist",
-    "templates",
-    "config",
-    "scripts",
-    ".documentation"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://dev.azure.com/AtlasHub/SmartStack/_git/SmartStack.cli"
-  },
-  "homepage": "https://smartstack.app",
-  "keywords": [
-    "smartstack",
-    "claude",
-    "claude-code",
-    "gitflow",
-    "efcore",
-    "entity-framework",
-    "migrations",
-    "cli",
-    "automation",
-    "anthropic",
-    "dotnet",
-    "prompts",
-    "ai-tools"
-  ],
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js || exit 0",
-    "dev": "tsup --watch",
-    "build:html": "node templates/skills/business-analyse/html/build-html.js",
-    "build": "npm run build:html && npx tsup",
-    "lint": "eslint src --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "prepublishOnly": "npm run build",
-    "test": "node --test",
-    "link": "npm run build && npm link",
-    "install:local": "npm run build && node dist/index.js install --local --force",
-    "install:global": "npm run build && node dist/index.js install --force",
-    "status:local": "node dist/index.js status --local --verbose",
-    "status:global": "node dist/index.js status --verbose",
-    "doctor": "node dist/index.js doctor",
-    "check-mcp": "node dist/index.js check-mcp",
-    "ralph:start": "node dist/index.js ralph start",
-    "ralph:status": "node dist/index.js ralph status",
-    "ralph:logs": "node dist/index.js ralph logs",
-    "health": "node dist/index.js doctor --json",
-    "test:mcp": "vitest run --config vitest.mcp.config.ts",
-    "test:mcp:watch": "vitest --config vitest.mcp.config.ts",
-    "test:mcp:coverage": "vitest run --config vitest.mcp.config.ts --coverage",
-    "test:ba": "vitest run --config vitest.ba.config.ts",
-    "test:ba:watch": "vitest --config vitest.ba.config.ts",
-    "test:ba:coverage": "vitest run --config vitest.ba.config.ts --coverage",
-    "test:all": "npm run test:mcp && npm run test:ba"
-  },
-  "dependencies": {
-    "@atlashub/smartstack-cli": "file:",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "axios": "^1.7.0",
-    "bcryptjs": "^2.4.3",
-    "chalk": "^5.3.0",
-    "cli-table3": "^0.6.3",
-    "commander": "^12.0.0",
-    "fs-extra": "^11.2.0",
-    "glob": "^13.0.1",
-    "handlebars": "^4.7.8",
-    "inquirer": "^9.2.12",
-    "jsonwebtoken": "^9.0.3",
-    "mssql": "^11.0.1",
-    "ora": "^8.0.1",
-    "zod": "^3.25.0"
-  },
-  "devDependencies": {
-    "@types/bcryptjs": "^2.4.6",
-    "@types/fs-extra": "^11.0.4",
-    "@types/inquirer": "^9.0.7",
-    "@types/jsonwebtoken": "^9.0.10",
-    "@types/mssql": "^9.1.5",
-    "@types/node": "^20.10.6",
-    "@typescript-eslint/eslint-plugin": "^6.18.0",
-    "@typescript-eslint/parser": "^6.18.0",
-    "@vitest/coverage-v8": "^2.1.0",
-    "eslint": "^8.56.0",
-    "prettier": "^3.2.4",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
-    "vitest": "^2.1.0"
-  }
-}
+{
+  "name": "@atlashub/smartstack-cli",
+  "version": "4.0.0",
+  "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
+  "author": {
+    "name": "SmartStack",
+    "email": "contact@smartstack.app",
+    "url": "https://smartstack.app"
+  },
+  "license": "MIT",
+  "private": false,
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "smartstack": "./dist/index.js",
+    "ss": "./dist/index.js",
+    "smartstack-mcp": "./dist/mcp-entry.mjs"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "config",
+    "scripts",
+    ".documentation"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://dev.azure.com/AtlasHub/SmartStack/_git/SmartStack.cli"
+  },
+  "homepage": "https://smartstack.app",
+  "keywords": [
+    "smartstack",
+    "claude",
+    "claude-code",
+    "gitflow",
+    "efcore",
+    "entity-framework",
+    "migrations",
+    "cli",
+    "automation",
+    "anthropic",
+    "dotnet",
+    "prompts",
+    "ai-tools"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js || exit 0",
+    "dev": "tsup --watch",
+    "build:html": "node templates/skills/business-analyse/html/build-html.js",
+    "build": "npm run build:html && npx tsup",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build",
+    "test": "node --test",
+    "link": "npm run build && npm link",
+    "install:local": "npm run build && node dist/index.js install --local --force",
+    "install:global": "npm run build && node dist/index.js install --force",
+    "status:local": "node dist/index.js status --local --verbose",
+    "status:global": "node dist/index.js status --verbose",
+    "doctor": "node dist/index.js doctor",
+    "check-mcp": "node dist/index.js check-mcp",
+    "ralph:start": "node dist/index.js ralph start",
+    "ralph:status": "node dist/index.js ralph status",
+    "ralph:logs": "node dist/index.js ralph logs",
+    "health": "node dist/index.js doctor --json",
+    "test:mcp": "vitest run --config vitest.mcp.config.ts",
+    "test:mcp:watch": "vitest --config vitest.mcp.config.ts",
+    "test:mcp:coverage": "vitest run --config vitest.mcp.config.ts --coverage",
+    "test:ba": "vitest run --config vitest.ba.config.ts",
+    "test:ba:watch": "vitest --config vitest.ba.config.ts",
+    "test:ba:coverage": "vitest run --config vitest.ba.config.ts --coverage",
+    "test:all": "npm run test:mcp && npm run test:ba"
+  },
+  "dependencies": {
+    "@atlashub/smartstack-cli": "file:",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.7.0",
+    "bcryptjs": "^2.4.3",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "glob": "^13.0.1",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.12",
+    "jsonwebtoken": "^9.0.3",
+    "mssql": "^11.0.1",
+    "ora": "^8.0.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^9.0.7",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/mssql": "^9.1.5",
+    "@types/node": "^20.10.6",
+    "@typescript-eslint/eslint-plugin": "^6.18.0",
+    "@typescript-eslint/parser": "^6.18.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "eslint": "^8.56.0",
+    "prettier": "^3.2.4",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^2.1.0"
+  }
+}

package/templates/skills/apex/SKILL.md

@@ -91,8 +91,8 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 44 POST-CHECKs, acceptance criteria |
 | 05 | `steps/step-05-deep-review.md` | Opus | Deep Review: adversarial code review (if -x) |
 | 06 | `steps/step-06-resolve.md` | Opus | Fix BLOCKING findings (if any) |
-| 07 | `steps/step-07-tests.md` | Opus | Scaffold tests via MCP |
-| 08 | `steps/step-08-run-tests.md` | Opus | Run tests until 100% pass |
+| 07 | `steps/step-07-tests.md` | Opus | Final Test Sweep: security tests, coverage, remaining failures |
+| 08 | `steps/step-08-run-tests.md` | Opus | Run Final Test Sweep until 100% pass |
 </step_files>
 
 <apex_phases>
@@ -103,11 +103,11 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | *Init* | 00 | Yes | Setup, hierarchy, challenge the need, **scope guard** (skipped in `-d` delegate mode) |
 | **A** — Analyze | 01 | Yes | Explore existing code |
 | **P** — Plan | 02 | Yes | File-by-file plan with skill/MCP mapping |
-| **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP |
+| **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP (5 layers: domain, seed, backend, frontend, devdata) |
 | **X** — eXamine | 04 | Yes | 3 MCP tools + 50 POST-CHECKs (6 security + 44 convention), build, acceptance criteria |
 | *Deep Review* | 05 (if -x) | No | Adversarial code review beyond automated checks |
 | *Resolve* | 06 (if BLOCKING) | No | Fix BLOCKING findings |
-| *Tests* | 07-08 | **Yes** | Scaffold and run tests |
+| *Final Test Sweep* | 07-08 | **Yes** | Security tests, coverage sweep, remaining failures |
 </apex_phases>
 
 <reference_files>
@@ -119,7 +119,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `references/smartstack-layers.md` | Layer rules, skill/MCP mapping, planning templates, delegate fast path | step-02 | step-03 (do NOT re-read) |
 | `references/smartstack-frontend.md` | Frontend patterns, EntityLookup, i18n, compliance gates (sections 1-9) | step-03 | step-04 |
 | `references/challenge-questions.md` | Hierarchy rules, challenge questions, delegate mode skip | step-00 | — |
-| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03 (delegate mode + seedData tasks) | — |
+| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03 (ALWAYS for Layer 1) | — |
 | `references/error-classification.md` | Build error diagnosis categories A-F | step-03 (build failure), step-04 | — |
 | `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 (if NOT economy_mode) | — |
 | `references/post-checks.md` | 6 security + 44 convention bash checks (MCP tools run first) | step-04 | — |
@@ -133,8 +133,9 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - **ORCHESTRATE, never generate** - All SmartStack code via skills (/controller, /application, etc.) or MCP tools
 - **MCP-first** - Use MCP scaffold/validate tools before manual approaches
 - **Verify MCP at startup** - step-00 checks MCP availability
-- **Layer order** - domain -> infra -> migration(BLOCKING) -> app -> api -> frontend -> i18n -> tests
-- **Agent Teams** - Parallel execution for scan (step-01) and Layer 1 (step-03), unless economy_mode
+- **Layer order** - Layer 0 (domain+infra+migration) → Layer 1 (seed data) → Layer 2 (backend+tests) → Layer 3 (frontend+tests) → Layer 4 (devdata)
+- **Agent Teams** - Parallel execution for scan (step-01) and within Layer 2/3 (step-03) for multi-entity, unless economy_mode
+- **Tests inline** - Backend tests run after Layer 2, frontend tests run after Layer 3 (max 3 fix iterations each). Step-07 = final sweep (security + coverage).
 - **Save outputs** if `{save_mode}` = true
 - **Commits per layer** - Atomic commits after each execution layer
 - **Delegate mode** (`-d`): Read PRD context, skip challenge questions, auto+economy mode implied. Used when `/ralph-loop` delegates code generation to `/apex`.
@@ -168,7 +169,8 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - Code created/corrected via existing skills and MCP (no direct generation)
 - MCP validate_conventions: 0 errors
 - Build: dotnet build PASS + npm run typecheck PASS (if frontend)
-- Seed data complete (navigation, permissions, roles, provider) if required
-- Tests: 100% pass, >= 80% coverage
+- Seed data complete as dedicated Layer 1 (navigation, permissions, roles, provider) — impossible to skip
+- Tests inline: backend tests after Layer 2, frontend tests after Layer 3
+- Final test sweep: security tests + coverage >= 80% + 100% pass rate
 - Commits atomic per layer
 </success_criteria>

package/templates/skills/apex/references/agent-teams-protocol.md

@@ -10,7 +10,7 @@
 
 ```yaml
 TeamCreate:
-  team_name: "apex-{phase}"          # e.g., "apex-analyze", "apex-exec"
+  team_name: "apex-{phase}"          # e.g., "apex-analyze", "apex-layer2", "apex-layer3"
   description: "{phase purpose}"      # e.g., "Scan SmartStack project for existing code"
 ```
 
@@ -24,7 +24,7 @@ Always provide both `team_name` and `description`.
 Task:
   subagent_type: "Explore" | "general-purpose"  # See assignment table below
   team_name: "apex-{phase}"          # Must match TeamCreate
-  name: "{teammate-name}"            # e.g., "scan-backend", "exec-frontend"
+  name: "{teammate-name}"            # e.g., "scan-backend", "entity-employee"
   model: "sonnet" | "opus"           # sonnet for scan, opus for dev (T02/T06)
   mode: "bypassPermissions"
   prompt: "{detailed task prompt}"
@@ -87,14 +87,24 @@ scan-frontend : src/pages/ + src/components/ + src/locales/
 scan-context  : .ralph/ + docs/business/
 ```
 
-### Step-03 Execute: Split by execution layer
+### Step-03 Execute: Split by entity WITHIN a layer
+
+> **Cross-layer parallelism is FORBIDDEN.** Layers execute sequentially: 0 → 1 → 2 → 3 → 4.
+> Agent teams parallelize **multi-entity work within a single layer.**
 
 ```
-exec-backend  : Application services + API controllers + Seed data
-exec-frontend : Pages + Components + Routes + I18n
+Layer 2 (Backend) — if multiple entities:
+  entity-{name1} : Service + DTO + Controller for Entity1
+  entity-{name2} : Service + DTO + Controller for Entity2
+  ...
+
+Layer 3 (Frontend) — if multiple entities:
+  entity-{name1} : Pages + i18n + routes for Entity1
+  entity-{name2} : Pages + i18n + routes for Entity2
+  ...
 ```
 
-Each teammate has an **isolated scope** (C02): backend never touches frontend.
+Each teammate has an **isolated scope** (C02): handles one entity end-to-end within the layer.
 
 ---
 
@@ -108,15 +118,20 @@ Each teammate has an **isolated scope** (C02): backend never touches frontend.
 3. Lead merges into unified analysis
 ```
 
-### Step-03: Lead verifies between layers
+### Step-03: Lead verifies between ALL 5 layers
 
 ```
 1. Layer 0: lead executes (domain + infra + migration)
-2. Build gate: dotnet build --no-restore → MUST PASS
-3. Layer 1: spawn exec-backend + exec-frontend
-4. Wait for both to complete
-5. Build gate: dotnet build + npm typecheck → MUST PASS
-6. Layer 2: lead executes final validation
+2. Build gate: dotnet build → MUST PASS
+3. Layer 1: lead executes (seed data — sequential, no teams)
+4. Build gate: dotnet build → MUST PASS
+5. Layer 2: spawn entity teammates (if multi-entity) OR lead executes (if single entity)
+6. Build gate: dotnet build → MUST PASS
+7. Backend tests inline (scaffold + run + fix max 3)
+8. Layer 3: spawn entity teammates (if multi-entity) OR lead executes (if single entity)
+9. Compliance gate: 5 frontend checks → MUST PASS
+10. Frontend tests inline (scaffold + run + fix max 3)
+11. Layer 4 (optional): lead executes DevData
 ```
 
 ---
@@ -158,7 +173,8 @@ TeamDelete
 | Condition | Action |
 |-----------|--------|
 | economy_mode = true | NO teams, all sequential |
-| Only backend work | NO teams, agent principal |
-| Only frontend work | NO teams, agent principal |
-| Backend + Frontend | Teams: exec-backend + exec-frontend |
-| Analysis phase | Teams: scan-backend + scan-frontend + scan-context |
+| Single entity (any layer) | NO teams, agent principal handles all |
+| Multiple entities, Layer 2 | Teams: one teammate per entity (service + controller) |
+| Multiple entities, Layer 3 | Teams: one teammate per entity (pages + i18n) |
+| Layer 0, Layer 1, Layer 4 | NO teams (sequential by nature) |
+| Analysis phase (step-01) | Teams: scan-backend + scan-frontend + scan-context |

package/templates/skills/apex/references/core-seed-data.md

@@ -1,6 +1,6 @@
 # Core Seed Data - Execution Reference
 
-> **Loaded by:** apex step-03-execute (delegate mode + seedData tasks) and step-04-examine
+> **Loaded by:** apex step-03-execute (ALWAYS for Layer 1) and step-04-examine
 > **Condition:** Seed data generation — infrastructure or seedData category tasks
 > **Applies to:** Client projects only (seeding_strategy = "provider", ExtensionsDbContext)
 >
@@ -1390,3 +1390,29 @@ public class {Module}DevDataSeeder : IDevDataSeeder
 > **Pipeline validation:**
 > - ralph-loop POST-CHECK warns if GUID not found in project config
 > - validate-feature step-05 verifies FK exists in real database via SQL query
+
+---
+
+## DataExportEndpoint Seed Data Pattern
+
+When adding a new export endpoint, add seed data in `DataExportEndpointConfiguration.cs`:
+
+```csharp
+builder.HasData(new {
+    Id = new Guid("{random-guid}"),
+    NavigationApplicationId = NavigationApplicationSeedData.{App}AppId,
+    NavigationModuleId = NavigationModuleSeedData.{Module}ModuleId,
+    Code = "{entity-code}",
+    Name = "{Entity} Export",
+    Description = "Export {entity} data with metadata",
+    RouteTemplate = "/api/v1/export/{entity-code}",
+    RequiredPermission = "{app}.{module}.export",
+    EntityType = "{Entity}",
+    IsActive = true,
+    DefaultRateLimitPerMinute = 60,
+    DefaultMaxPageSize = 1000,
+    CreatedAt = seedDate
+});
+```
+
+Requires matching controller in `Controllers/DataExport/v1/Export{Entity}Controller.cs`.

package/templates/skills/apex/references/smartstack-api.md

@@ -810,6 +810,46 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 
 ---
 
+## External Application & Data Export Pattern
+
+### Entities
+
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `ExternalApplication` | `auth_ExternalApplications` | Machine-to-machine API account (ClientId, ClientSecret, IsActive, IP whitelist) |
+| `ExternalApplicationRole` | `auth_ExternalApplicationRoles` | Role assignment per app (AppId, RoleId, optional TenantId) |
+| `ExternalApplicationExportAccess` | `auth_ExternalApplicationExportAccesses` | Per-app access to specific export endpoint (IsEnabled, RateLimitPerMinute, MaxPageSize) |
+| `DataExportEndpoint` | `auth_DataExportEndpoints` | Registry of available export APIs (Code, RouteTemplate, RequiredPermission, EntityType) |
+| `ExternalAppAuditLog` | `auth_ExternalAppAuditLogs` | Audit trail for all API calls (Authentication, DataExport actions) |
+
+### Architecture (3-layer security)
+
+1. **Authentication** — JWT assertion signed with ClientSecret → ExternalApplicationAuthService validates → generates SmartStack JWT with permissions resolved via ExternalApplicationRole → Role → RolePermission chain
+2. **Authorization** — RequirePermissionFilter checks JWT claims (e.g., `administration.users.export`)
+3. **Access Control** — DataExportAccessMiddleware verifies per-app endpoint access in ExternalApplicationExportAccess table
+
+### Rate Limiting
+
+ExternalAppRateLimitPolicy resolves limits: app override → endpoint default → 60/min fallback.
+Partition key: `{clientId}:{endpointCode}`.
+
+### Seed Data
+
+DataExportEndpoints are seeded in DataExportEndpointConfiguration.cs with FK to NavigationApplication and NavigationModule. Each endpoint maps to a controller in `Controllers/DataExport/v1/`.
+
+### Controller Pattern
+
+Export controllers: `[Route("api/v1/export")]` + `[RequirePermission]` + `[EnableRateLimiting]`
+
+**Query Parameters (all export endpoints except Navigation):**
+- `tenantId` (UUID, required) — Scopes the export to the specified tenant's data
+
+Example: `GET /api/v1/export/users?tenantId=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=50`
+
+Management controllers: `[NavRoute("api.accounts")]` with CustomSegment
+
+---
+
 ## PaginatedResult Pattern
 
 > **Canonical type for ALL paginated responses.** One name, one contract, everywhere.