@atlashub/smartstack-cli 3.52.0 → 3.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.52.0",
+  "version": "3.54.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/agents/gitflow/init.md

@@ -10,12 +10,17 @@ tools: Bash, Read, Write, Glob, AskUserQuestion
 
 You initialize a GitFlow project by orchestrating 3 specialized sub-agents.
 
+**IMPORTANT: User questions (root folder, project name, worktree mode) are normally
+handled by the main conversation BEFORE this agent is spawned. If you receive
+pre-confirmed values in your prompt, use them directly. If values are NOT provided,
+you MUST call AskUserQuestion for each missing value before proceeding.**
+
 ## ARCHITECTURE
 
 ```
 gitflow-init (you - orchestrator)
   ├── Task(gitflow-init-detect)   → Environment report
-  ├── AskUserQuestion             → User confirms URL, path, name, worktree mode
+  ├── AskUserQuestion             → ONLY if values not pre-confirmed by caller
   ├── Task(gitflow-init-clone)    → Create structure (skip if disabled)
   ├── Write config.json           → v2.1.0 with platform & workspace
   └── Task(gitflow-init-validate) → Verify & repair (skip if disabled)

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

@@ -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,40 @@ 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]`
+Management controllers: `[NavRoute("api.accounts")]` with CustomSegment
+
+---
+
 ## PaginatedResult Pattern
 
 > **Canonical type for ALL paginated responses.** One name, one contract, everywhere.

package/templates/skills/application/references/backend-table-prefix-mapping.md

@@ -19,6 +19,7 @@
 | `support.*` | `support_` | `Support` | Table: `support_Tickets`, Controller: `Controllers/Support/TicketsController.cs` |
 | `*` (business apps) | `ref_` or domain-specific | `{ApplicationPascal}` | Table: `ref_Products`, Controller: `Controllers/Sales/ProductsController.cs` |
 | `myspace.*` | `usr_` | `MySpace` | Table: `usr_Preferences`, Controller: `Controllers/MySpace/PreferencesController.cs` |
+| `api.*` | `auth_` or `ext_` | `Api` | Table: `auth_ExternalApplications`, Controller: `Controllers/Platform/Api/ExternalApplications/` |
 
 ---
 

package/templates/skills/business-analyse/patterns/suggestion-catalog.md

@@ -26,6 +26,7 @@ Suggests companion modules based on primary module type:
 | **Permissions/Security** | permission, role, access, authority, rbac | UserRoles, Groups, Policies, Audit, Delegation | Permission systems need fine-grained control, group policies, and audit trails |
 | **Notifications** | notification, alert, email, message, broadcast | Templates, Channels, Scheduling, Preferences | Notification systems need template management, multi-channel support, scheduling |
 | **Reporting** | report, dashboard, analytics, BI, metrics | Dashboards, Exports, Scheduling, AlertRules | Reporting needs visualization, scheduled distribution, and data export |
+| **API Management / Integrations** | api, external, integration, webhook, export, data-export, machine-to-machine | ExternalApps, DataExportEndpoints, ExportAccess, AuditLogs, ApiKeys | API platforms need app registration, key management, granular endpoint access, rate limiting, and audit logging |
 
 ---
 
@@ -66,6 +67,7 @@ Suggests system integrations based on requirements:
 | **Geographical features** | Maps/Location Service | Spatial data handling | Add section with provider selection, geocoding, distance calculation |
 | **Data synchronization** | Event Bus/Messaging | Async data consistency | Add section with message types, subscription strategy, retry logic |
 | **File storage** | Cloud Storage Integration | Large file handling | Add section with provider selection, access control, cleanup policy |
+| **Machine-to-machine API** | External app, M2M, JWT assertion, API key | Data Export API | Add section with app registration, key generation, endpoint-level access grants, per-app rate limits, and audit log |
 
 ---
 

package/templates/skills/gitflow/SKILL.md

@@ -185,7 +185,7 @@ start ──► commit* ──► sync ──► pr ──► merge ──► fi
 
 | Input Pattern | Step File | Task Agent (`subagent_type`) |
 |---------------|-----------|----------------------------|
-| `init` | `steps/step-init.md` | `gitflow-init` |
+| `init` | `steps/step-init.md` | **ALWAYS INLINE** (see below) |
 | `start`, `-f`, `-r`, `-h` | `steps/step-start.md` | `gitflow-start` |
 | `commit [msg]` | `steps/step-commit.md` | `gitflow-commit` |
 | `sync` | `steps/step-sync.md` | — |
@@ -206,6 +206,16 @@ start ──► commit* ──► sync ──► pr ──► merge ──► fi
 | **Auto mode** (`-a`) | Use `Task` tool with the matching `subagent_type` for each step sequentially |
 | **Standalone phases** | Always delegate to Task agent (fast, isolated) |
 
+**⚠️ SPECIAL RULE FOR `init`:**
+`init` is **ALWAYS executed inline** — NEVER delegate to a Task agent.
+Read `steps/step-init.md` and execute it directly in the main conversation.
+This is mandatory because `init` requires AskUserQuestion calls that MUST
+happen in the main conversation (sub-agents skip questions).
+After the user answers all questions, delegate heavy work to:
+- `Task(gitflow-init-detect)` for environment detection
+- `Task(gitflow-init-clone)` for structure creation
+- `Task(gitflow-init-validate)` for post-init verification
+
 </entry_point>
 
 <step_files>

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

@@ -10,134 +10,106 @@ next_step: null
 
 Set up GitFlow configuration with bare repository, worktrees, and branches.
 
-**ULTRA THINK before creating configuration.**
-
----
-
-## MANDATORY INTERACTIVE QUESTIONS
-
-╔══════════════════════════════════════════════════════════════════════════╗
-║  You MUST call AskUserQuestion for EACH question below.                 ║
-║  Auto-detected values are SUGGESTIONS for option labels, NOT answers.  ║
-║  NEVER use a detected value as the final value without user confirm.   ║
-║  Minimum AskUserQuestion calls: 3 (if URL provided) or 4 (if not).    ║
-╚══════════════════════════════════════════════════════════════════════════╝
-
-| Question | Variable | Suggested from | MUST ASK? |
-|----------|----------|----------------|-----------|
-| Repository URL | `{REPO_URL}` | `git remote get-url origin` | YES (skip only if URL in command args) |
-| Root folder | `{ROOT_FOLDER}` | Parent of current directory | **ALWAYS YES** |
-| Project name | `{PROJECT_NAME}` | Repo name from URL or folder | **ALWAYS YES** |
-| Worktree mode | `{WORKTREE_MODE}` | None — no default | **ALWAYS YES** |
-
-**Multi-project principle:** Each repository has its OWN independent GitFlow config. Step 2 scans for sibling projects to provide context, not to share configuration.
-
-**⛔ FOLLOW-UP RULE:** When a user selects a "Custom..." option (custom name, custom path, custom URL), that selection is just a CHOICE, not the actual value. You MUST immediately ask a follow-up question to capture the actual value. Never proceed with a blank or default value.
+**This step runs INLINE in the main conversation. All AskUserQuestion calls
+happen here (NOT in a sub-agent). Only clone/validate are delegated.**
 
 ---
 
 ## EXECUTION SEQUENCE:
 
-### 1. Detect Environment (for defaults only)
-
-See [references/init-environment-detection.md](../references/init-environment-detection.md) for:
-- Platform detection (WSL/Windows/macOS/Linux)
-- Git provider detection
-- Auto-detect defaults (URL, folder, project name)
-
-### 2. Detect Workspace (multi-project context)
-
-See [references/init-workspace-detection.md](../references/init-workspace-detection.md) for:
-- Sibling project scanning
-- Workspace context display
-- Per-repository GitFlow principle
+### 1. Detect Environment (delegate to sub-agent)
 
-### 3. Question: Existing Configuration
+Spawn `Task(gitflow-init-detect)` (haiku) to detect platform, git state, workspace siblings, provider.
+Parse the report to extract: PLATFORM, SHELL_TYPE, DETECTED_URL, DETECTED_NAME, GIT_PROVIDER, SIBLING_COUNT.
 
-**⛔ Only if `ALREADY_INITIALIZED` = true.** Otherwise skip to step 4.
+### 2. Check Existing Configuration
 
-See [references/init-questions.md](../references/init-questions.md) → **Question 4** for options (Reconfigure / Repair / View only / Cancel).
+If `.claude/gitflow/config.json` exists, ask user: Reconfigure / Repair / View / Cancel.
+If Cancel or View → EXIT. If Repair → delegate to `Task(gitflow-init-validate)` → EXIT.
 
-### 4. Question: Repository URL
+### 3. Question: Repository URL
 
-**⛔ MUST ASK — even if URL was auto-detected.**
+If URL was provided in command args (starts with `https://` or `git@`), use it directly → skip to step 4.
 
-See [references/init-questions.md](../references/init-questions.md) → **Question 1** for format and follow-up rules.
+Otherwise, call AskUserQuestion:
+- header: "Repository"
+- question: "Repository URL? (detected: {DETECTED_URL})"
+- options: Use detected URL (Recommended) / Enter GitHub URL / Enter Azure DevOps URL / Local only
+- If user selects custom option → ask follow-up for actual URL
 
-### 5. Question: Root Folder — CALL AskUserQuestion
+Store as `{REPO_URL}`.
 
-**CALL AskUserQuestion NOW. Do NOT auto-derive from the URL or environment.**
+### 4. Question: Root Folder
 
-See [references/init-questions.md](../references/init-questions.md) → **Question 2** for format and follow-up rules.
+Call AskUserQuestion:
+- header: "Location"
+- question: "Root folder for this project? (worktrees will be created here)"
+- options:
+  - "Use parent folder (Recommended)" — "{PARENT_DIR}/ - consistent with {SIBLING_COUNT} sibling project(s)"
+  - "Use current folder" — "{CURRENT_DIR}/"
+  - "Custom path" — "Specify a different location"
+- If user selects "Custom path" → ask follow-up for actual path
 
-### 6. Question: Project Name — CALL AskUserQuestion
+Store as `{PROJECT_BASE}`. Normalize for platform (WSL: /mnt/ format, Windows: forward slashes).
 
-**CALL AskUserQuestion NOW. Do NOT auto-derive from the URL or environment.**
+### 5. Question: Project Name
 
-See [references/init-questions.md](../references/init-questions.md) → **Question 3** for format and follow-up rules.
+Call AskUserQuestion:
+- header: "Project"
+- question: "Project name? (detected: {DETECTED_NAME})"
+- options:
+  - "Use detected name (Recommended)" — "{DETECTED_NAME}"
+  - "Custom name" — "Specify a different project name"
+- If user selects "Custom name" → ask follow-up for actual name
 
-### 6b. Normalize Project Name (INTELLIGENT)
+Store as `{PROJECT_NAME}`.
 
-**⛔ ALWAYS normalize, even if user chose the detected name.**
+Then normalize into variants: PascalCase.Dot, PascalCase, kebab-case, snake_case, Display Name.
+See [references/init-name-normalization.md](../references/init-name-normalization.md).
 
-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`
+### 6. Question: Worktree Mode
 
-### 7. Question: Worktree Mode — CALL AskUserQuestion
+Call AskUserQuestion:
+- header: "Worktrees"
+- question: "How should worktrees be organized?"
+- options:
+  - "Organized (Recommended)" — "Numbered folders: 01-Main/, 02-Develop/, features/, releases/, hotfixes/"
+  - "Simple" — "Plain folders: main/, develop/, features/, releases/, hotfixes/"
+  - "Disabled" — "No worktrees, use git checkout (not recommended)"
 
-**CALL AskUserQuestion NOW. This question is the MOST FREQUENTLY SKIPPED.**
+Store as `{WORKTREE_MODE}` ("organized", "simple", or "disabled").
 
-⛔ BLOCKING: If you reach step 8 without having called AskUserQuestion for
-worktree mode and received an explicit user answer, STOP and ask it NOW.
-Do NOT default to "organized". The user MUST choose.
+### 7. Confirm all values
 
-See [references/init-questions.md](../references/init-questions.md) → **Question 5** for options:
-- **Organized** (recommended): `01-Main/`, `02-Develop/`, `features/`, `releases/`, `hotfixes/`
-- **Simple**: `main/`, `develop/`, `features/`, `releases/`, `hotfixes/`
-- **Disabled**: No worktrees, use `git checkout`
-
-
-### 8. Create Directory Structure
-
-See [references/init-structure-creation.md](../references/init-structure-creation.md) for:
-- Path normalization for WSL
-- Complete directory structure creation with absolute paths
-- Bare repository setup
-- Worktree creation (organized and simple modes)
-- GitFlow config directory creation
-
-### 9. Detect Version
-
-**⛔ MUST run BEFORE creating config.json (step 10) — the detected `{VERSION}` is needed in the config template.**
-
-See [references/init-version-detection.md](../references/init-version-detection.md) for:
-- Version detection with priority (csproj, package.json, tags, etc.)
-- Platform-agnostic path handling
-- Fallback: `0.0.0` if no version source found
-
-**⛔ WARNING:** Do NOT confuse the config schema version (`"version": "2.1.0"` at line 1 of config.json) with the project version (`"versioning.current": "{VERSION}"`). They are completely different values.
+Display a summary to the user before proceeding:
+```
+Ready to initialize:
+  URL:      {REPO_URL}
+  Folder:   {PROJECT_BASE}
+  Name:     {PROJECT_NAME}
+  Mode:     {WORKTREE_MODE}
+```
 
-### 10. Create Configuration
+### 8. Create Directory Structure (delegate to sub-agent)
 
-**Write `.claude/gitflow/config.json` in develop worktree using the `{VERSION}` detected in step 9.**
+**Skip if `{WORKTREE_MODE}` is "disabled".**
 
-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)
+Spawn `Task(gitflow-init-clone)` (sonnet) with the user-confirmed values:
+- REPO_URL, PROJECT_BASE, PROJECT_NAME, WORKTREE_MODE, PLATFORM
 
-**⛔ 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.
+See [references/init-structure-creation.md](../references/init-structure-creation.md) for details.
 
-### 10b. Post-Init Validation
+### 9. Detect Version + Create Configuration
 
-**⛔ MANDATORY: Verify the structure was created correctly.**
+Detect version (csproj > package.json > tags > fallback `0.0.0`).
+Write `.claude/gitflow/config.json` in develop worktree.
+See [references/init-config-template.md](../references/init-config-template.md) for template.
+Store paths as `D:/path/to/folder` format.
 
-See [references/init-config-template.md](../references/init-config-template.md) — Section "Post-Init Validation" for the full bash validation script.
+### 10. Post-Init Validation (delegate to sub-agent)
 
-Checks: .bare/HEAD, worktree branches (main/develop), features/releases/hotfixes dirs, .claude/gitflow/ dir.
+Spawn `Task(gitflow-init-validate)` (haiku) to verify structure.
+Checks: .bare/HEAD, worktree branches, directories, config file.
 
 ### 11. Summary
 
@@ -205,7 +177,7 @@ Before completing init, verify:
 
 ## SUCCESS CRITERIA:
 
-- ✅ AskUserQuestion tool called at least 3 times (4 if URL not in command args)
+- ✅ AskUserQuestion called for root folder, project name, AND worktree mode
 - ✅ Complete folder structure created
 - ✅ Both main and develop worktrees functional
 - ✅ Configuration file created