@atlashub/smartstack-cli 3.37.0 → 3.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (216) hide show
  1. package/dist/index.js +16 -24
  2. package/dist/index.js.map +1 -1
  3. package/dist/mcp-entry.mjs +201 -256
  4. package/dist/mcp-entry.mjs.map +1 -1
  5. package/package.json +1 -1
  6. package/scripts/extract-api-endpoints.ts +5 -5
  7. package/scripts/generate-doc-with-mock-ui.ts +10 -17
  8. package/templates/agents/ba-reader.md +9 -9
  9. package/templates/agents/ba-writer.md +12 -15
  10. package/templates/agents/code-reviewer.md +1 -1
  11. package/templates/agents/docs-context-reader.md +1 -1
  12. package/templates/agents/gitflow/merge.md +0 -4
  13. package/templates/agents/gitflow/pr.md +0 -4
  14. package/templates/agents/gitflow/start.md +30 -5
  15. package/templates/mcp-scaffolding/frontend/nav-routes.ts.hbs +20 -20
  16. package/templates/mcp-scaffolding/frontend/routes.tsx.hbs +16 -24
  17. package/templates/mcp-scaffolding/migrations/seed-roles.cs.hbs +2 -2
  18. package/templates/skills/_resources/mcp-validate-documentation-spec.md +3 -3
  19. package/templates/skills/_shared.md +15 -17
  20. package/templates/skills/ai-prompt/SKILL.md +1 -1
  21. package/templates/skills/ai-prompt/steps/step-00-init.md +47 -0
  22. package/templates/skills/apex/SKILL.md +3 -4
  23. package/templates/skills/apex/_shared.md +10 -20
  24. package/templates/skills/apex/references/analysis-methods.md +141 -0
  25. package/templates/skills/apex/references/challenge-questions.md +1 -21
  26. package/templates/skills/apex/references/core-seed-data.md +35 -57
  27. package/templates/skills/apex/references/examine-build-validation.md +87 -0
  28. package/templates/skills/apex/references/execution-frontend-gates.md +177 -0
  29. package/templates/skills/apex/references/execution-frontend-patterns.md +105 -0
  30. package/templates/skills/apex/references/execution-layer1-rules.md +96 -0
  31. package/templates/skills/apex/references/initialization-challenge-flow.md +110 -0
  32. package/templates/skills/apex/references/planning-layer-mapping.md +151 -0
  33. package/templates/skills/apex/references/post-checks.md +145 -40
  34. package/templates/skills/apex/references/smartstack-api.md +35 -51
  35. package/templates/skills/apex/references/smartstack-frontend.md +17 -17
  36. package/templates/skills/apex/references/smartstack-layers.md +38 -62
  37. package/templates/skills/apex/steps/step-00-init.md +14 -26
  38. package/templates/skills/apex/steps/step-01-analyze.md +10 -143
  39. package/templates/skills/apex/steps/step-02-plan.md +10 -92
  40. package/templates/skills/apex/steps/step-03-execute.md +47 -249
  41. package/templates/skills/apex/steps/step-04-examine.md +14 -78
  42. package/templates/skills/apex/steps/step-05-deep-review.md +2 -2
  43. package/templates/skills/apex/steps/step-08-run-tests.md +2 -0
  44. package/templates/skills/application/SKILL.md +6 -7
  45. package/templates/skills/application/references/backend-controller-hierarchy.md +16 -16
  46. package/templates/skills/application/references/backend-seeding-and-dto-output.md +83 -0
  47. package/templates/skills/application/references/backend-table-prefix-mapping.md +79 -0
  48. package/templates/skills/application/references/backend-verification.md +1 -1
  49. package/templates/skills/application/references/frontend-i18n-and-output.md +67 -0
  50. package/templates/skills/application/references/frontend-route-naming.md +117 -0
  51. package/templates/skills/application/references/frontend-route-wiring-app-tsx.md +107 -0
  52. package/templates/skills/application/references/frontend-verification.md +12 -12
  53. package/templates/skills/application/references/init-parameter-detection.md +120 -0
  54. package/templates/skills/application/references/migration-checklist-troubleshooting.md +100 -0
  55. package/templates/skills/application/references/nav-fallback-procedure.md +5 -6
  56. package/templates/skills/application/references/provider-template.md +2 -6
  57. package/templates/skills/application/references/roles-client-project-handling.md +55 -0
  58. package/templates/skills/application/references/roles-fallback-procedure.md +149 -0
  59. package/templates/skills/application/references/test-coverage-requirements.md +213 -0
  60. package/templates/skills/application/references/test-frontend.md +3 -3
  61. package/templates/skills/application/steps/step-00-init.md +11 -141
  62. package/templates/skills/application/steps/step-01-navigation.md +3 -3
  63. package/templates/skills/application/steps/step-02-permissions.md +4 -4
  64. package/templates/skills/application/steps/step-03-roles.md +18 -175
  65. package/templates/skills/application/steps/step-03b-provider.md +1 -2
  66. package/templates/skills/application/steps/step-04-backend.md +19 -110
  67. package/templates/skills/application/steps/step-05-frontend.md +17 -143
  68. package/templates/skills/application/steps/step-06-migration.md +12 -60
  69. package/templates/skills/application/steps/step-07-tests.md +9 -76
  70. package/templates/skills/application/templates-backend.md +29 -27
  71. package/templates/skills/application/templates-frontend.md +48 -48
  72. package/templates/skills/application/templates-seed.md +57 -131
  73. package/templates/skills/business-analyse/SKILL.md +27 -30
  74. package/templates/skills/business-analyse/_architecture.md +6 -6
  75. package/templates/skills/business-analyse/_shared.md +60 -88
  76. package/templates/skills/business-analyse/questionnaire/04-data.md +3 -3
  77. package/templates/skills/business-analyse/questionnaire/06-security.md +1 -1
  78. package/templates/skills/business-analyse/questionnaire/13-cross-module.md +1 -1
  79. package/templates/skills/business-analyse/react/application-viewer.md +12 -12
  80. package/templates/skills/business-analyse/react/components.md +8 -12
  81. package/templates/skills/business-analyse/react/schema.md +11 -11
  82. package/templates/skills/business-analyse/references/agent-module-prompt.md +2 -3
  83. package/templates/skills/business-analyse/references/analysis-semantic-checks.md +190 -0
  84. package/templates/skills/business-analyse/references/cache-warming-strategy.md +2 -2
  85. package/templates/skills/business-analyse/references/cadrage-challenge-patterns.md +41 -0
  86. package/templates/skills/business-analyse/references/cadrage-coverage-matrix.md +74 -0
  87. package/templates/skills/business-analyse/references/cadrage-shared-modules.md +69 -0
  88. package/templates/skills/business-analyse/references/cadrage-structure-cards.md +1 -1
  89. package/templates/skills/business-analyse/references/compilation-structure-cards.md +297 -0
  90. package/templates/skills/business-analyse/references/consolidation-structural-checks.md +2 -2
  91. package/templates/skills/business-analyse/references/deploy-modes.md +5 -5
  92. package/templates/skills/business-analyse/references/detection-strategies.md +7 -7
  93. package/templates/skills/business-analyse/references/handoff-file-templates.md +14 -22
  94. package/templates/skills/business-analyse/references/handoff-mappings.md +4 -4
  95. package/templates/skills/business-analyse/references/handoff-seeddata-generation.md +312 -0
  96. package/templates/skills/business-analyse/references/init-schema-deployment.md +3 -3
  97. package/templates/skills/business-analyse/references/naming-conventions.md +22 -24
  98. package/templates/skills/business-analyse/references/prd-generation.md +2 -2
  99. package/templates/skills/business-analyse/references/review-data-mapping.md +2 -2
  100. package/templates/skills/business-analyse/references/robustness-checks.md +1 -1
  101. package/templates/skills/business-analyse/references/spec-auto-inference.md +3 -3
  102. package/templates/skills/business-analyse/references/team-orchestration.md +49 -6
  103. package/templates/skills/business-analyse/references/ui-dashboard-spec.md +1 -1
  104. package/templates/skills/business-analyse/references/ui-resource-cards.md +18 -18
  105. package/templates/skills/business-analyse/references/validate-incremental-html.md +2 -2
  106. package/templates/skills/business-analyse/references/validation-checklist.md +2 -2
  107. package/templates/skills/business-analyse/schemas/application-schema.json +4 -5
  108. package/templates/skills/business-analyse/schemas/project-schema.json +1 -6
  109. package/templates/skills/business-analyse/schemas/sections/metadata-schema.json +2 -3
  110. package/templates/skills/business-analyse/schemas/sections/specification-schema.json +4 -4
  111. package/templates/skills/business-analyse/steps/step-00-init.md +8 -17
  112. package/templates/skills/business-analyse/steps/step-01-cadrage.md +35 -198
  113. package/templates/skills/business-analyse/steps/step-01b-applications.md +16 -20
  114. package/templates/skills/business-analyse/steps/step-02-decomposition.md +1 -1
  115. package/templates/skills/business-analyse/steps/step-03a1-setup.md +4 -4
  116. package/templates/skills/business-analyse/steps/step-03a2-analysis.md +1 -1
  117. package/templates/skills/business-analyse/steps/step-03b-ui.md +4 -4
  118. package/templates/skills/business-analyse/steps/step-03c-compile.md +66 -140
  119. package/templates/skills/business-analyse/steps/step-03d-validate.md +2 -2
  120. package/templates/skills/business-analyse/steps/step-04a-collect.md +2 -2
  121. package/templates/skills/business-analyse/steps/step-04b-analyze.md +42 -160
  122. package/templates/skills/business-analyse/steps/step-04c-decide.md +1 -1
  123. package/templates/skills/business-analyse/steps/step-05a-handoff.md +74 -104
  124. package/templates/skills/business-analyse/steps/step-05b-deploy.md +13 -11
  125. package/templates/skills/business-analyse/steps/step-06-review.md +3 -3
  126. package/templates/skills/business-analyse/templates/tpl-frd.md +13 -13
  127. package/templates/skills/business-analyse/templates/tpl-handoff.md +12 -12
  128. package/templates/skills/business-analyse/templates-frd.md +25 -25
  129. package/templates/skills/business-analyse/templates-react.md +15 -21
  130. package/templates/skills/controller/SKILL.md +1 -1
  131. package/templates/skills/controller/postman-templates.md +1 -1
  132. package/templates/skills/controller/references/controller-code-templates.md +2 -2
  133. package/templates/skills/controller/references/mcp-scaffold-workflow.md +209 -0
  134. package/templates/skills/controller/references/permission-sync-templates.md +13 -16
  135. package/templates/skills/controller/steps/step-00-init.md +11 -11
  136. package/templates/skills/controller/steps/step-03-generate.md +64 -103
  137. package/templates/skills/controller/templates.md +67 -71
  138. package/templates/skills/debug/SKILL.md +13 -218
  139. package/templates/skills/debug/steps/step-00-init.md +57 -0
  140. package/templates/skills/debug/steps/step-01-analyze.md +219 -0
  141. package/templates/skills/debug/steps/step-02-resolve.md +85 -0
  142. package/templates/skills/documentation/SKILL.md +49 -345
  143. package/templates/skills/documentation/data-schema.md +11 -8
  144. package/templates/skills/documentation/steps/step-00-init.md +70 -0
  145. package/templates/skills/documentation/steps/step-01-scan.md +113 -0
  146. package/templates/skills/documentation/steps/step-02-generate.md +231 -0
  147. package/templates/skills/documentation/steps/step-03-validate.md +238 -0
  148. package/templates/skills/documentation/templates.md +480 -322
  149. package/templates/skills/efcore/references/both-contexts.md +32 -0
  150. package/templates/skills/efcore/references/database-operations.md +67 -0
  151. package/templates/skills/efcore/references/destructive-operations.md +38 -0
  152. package/templates/skills/efcore/references/reset-operations.md +81 -0
  153. package/templates/skills/efcore/references/seed-methods.md +86 -0
  154. package/templates/skills/efcore/references/shared-init-functions.md +250 -0
  155. package/templates/skills/efcore/references/sql-objects-injection.md +61 -0
  156. package/templates/skills/efcore/references/troubleshooting.md +81 -0
  157. package/templates/skills/efcore/steps/db/step-deploy.md +1 -32
  158. package/templates/skills/efcore/steps/db/step-reset.md +7 -103
  159. package/templates/skills/efcore/steps/db/step-seed.md +10 -132
  160. package/templates/skills/efcore/steps/db/step-status.md +5 -44
  161. package/templates/skills/efcore/steps/migration/step-03-validate.md +8 -62
  162. package/templates/skills/efcore/steps/rebase-snapshot/step-03-create.md +1 -57
  163. package/templates/skills/efcore/steps/shared/step-00-init.md +11 -254
  164. package/templates/skills/efcore/steps/squash/step-03-create.md +1 -58
  165. package/templates/skills/feature-full/SKILL.md +1 -1
  166. package/templates/skills/feature-full/steps/step-00-init.md +57 -0
  167. package/templates/skills/feature-full/steps/step-01-implementation.md +1 -1
  168. package/templates/skills/gitflow/SKILL.md +1 -1
  169. package/templates/skills/gitflow/_shared.md +23 -0
  170. package/templates/skills/gitflow/references/commit-message-generation.md +58 -0
  171. package/templates/skills/gitflow/references/commit-migration-validation.md +49 -0
  172. package/templates/skills/gitflow/references/finish-cleanup.md +51 -0
  173. package/templates/skills/gitflow/references/finish-version-bumping.md +45 -0
  174. package/templates/skills/gitflow/references/init-environment-detection.md +41 -0
  175. package/templates/skills/gitflow/references/init-questions.md +185 -0
  176. package/templates/skills/gitflow/references/init-structure-creation.md +71 -0
  177. package/templates/skills/gitflow/references/init-version-detection.md +21 -0
  178. package/templates/skills/gitflow/references/init-workspace-detection.md +43 -0
  179. package/templates/skills/gitflow/references/merge-ci-status.md +36 -0
  180. package/templates/skills/gitflow/references/merge-execution.md +62 -0
  181. package/templates/skills/gitflow/references/merge-pr-context.md +76 -0
  182. package/templates/skills/gitflow/references/pr-build-checks.md +60 -0
  183. package/templates/skills/gitflow/references/pr-generation.md +58 -0
  184. package/templates/skills/gitflow/references/start-branch-normalization.md +28 -0
  185. package/templates/skills/gitflow/references/start-worktree-creation.md +50 -0
  186. package/templates/skills/gitflow/references/sync-push-verify.md +44 -0
  187. package/templates/skills/gitflow/references/sync-rebase-conflicts.md +38 -0
  188. package/templates/skills/gitflow/steps/step-commit.md +12 -91
  189. package/templates/skills/gitflow/steps/step-finish.md +15 -159
  190. package/templates/skills/gitflow/steps/step-init.md +24 -326
  191. package/templates/skills/gitflow/steps/step-merge.md +17 -176
  192. package/templates/skills/gitflow/steps/step-pr.md +10 -116
  193. package/templates/skills/gitflow/steps/step-start.md +16 -109
  194. package/templates/skills/gitflow/steps/step-sync.md +6 -69
  195. package/templates/skills/ralph-loop/SKILL.md +6 -0
  196. package/templates/skills/ralph-loop/references/category-completeness.md +185 -0
  197. package/templates/skills/ralph-loop/references/compact-loop.md +1 -1
  198. package/templates/skills/ralph-loop/references/init-resume-recovery.md +127 -0
  199. package/templates/skills/ralph-loop/references/module-transition.md +151 -0
  200. package/templates/skills/ralph-loop/references/multi-module-queue.md +171 -0
  201. package/templates/skills/ralph-loop/references/parallel-execution.md +246 -0
  202. package/templates/skills/ralph-loop/references/task-transform-legacy.md +6 -9
  203. package/templates/skills/ralph-loop/references/team-orchestration.md +45 -3
  204. package/templates/skills/ralph-loop/steps/step-00-init.md +36 -109
  205. package/templates/skills/ralph-loop/steps/step-01-task.md +15 -163
  206. package/templates/skills/ralph-loop/steps/step-02-execute.md +8 -154
  207. package/templates/skills/ralph-loop/steps/step-04-check.md +21 -73
  208. package/templates/skills/review-code/references/owasp-api-top10.md +5 -5
  209. package/templates/skills/review-code/references/smartstack-conventions.md +11 -11
  210. package/templates/skills/validate-feature/references/api-smoke-tests.md +140 -0
  211. package/templates/skills/validate-feature/references/db-validation-checks.md +180 -0
  212. package/templates/skills/validate-feature/steps/step-01-compile.md +5 -2
  213. package/templates/skills/validate-feature/steps/step-04-api-smoke.md +34 -145
  214. package/templates/skills/validate-feature/steps/step-05-db-validation.md +74 -260
  215. package/templates/skills/workflow/SKILL.md +1 -1
  216. package/templates/skills/workflow/steps/step-00-init.md +57 -0
@@ -22,156 +22,26 @@ Initialize the application/module creation by parsing parameters, detecting leve
22
22
 
23
23
  ## EXECUTION SEQUENCE
24
24
 
25
- ### 1. Detect Navigation Level
25
+ ### 1-4. Parameter Detection & Project Analysis
26
26
 
27
- From user request, identify the level:
28
-
29
- | Hint in Request | Level | Parent Required |
30
- |-----------------|---------|-----------------|
31
- | "context", "workspace", "nouveau contexte" | context | No |
32
- | "application", "app", "nouvelle application" | application | Yes (context) |
33
- | "module", "feature", "nouveau module" | module | Yes (context.application) |
34
- | "section", "tab", "nouvelle section" | section | Yes (context.app.module) |
35
-
36
- ### 2. Extract Parameters
37
-
38
- ```yaml
39
- # Required
40
- level: context | application | module | section
41
- code: kebab-case (e.g., "products", "order-management")
42
- labels:
43
- fr: "Label français"
44
- en: "English label"
45
- it: "Etichetta italiana"
46
- de: "Deutsche Bezeichnung"
47
- icon: Lucide icon name (e.g., "Package", "ShoppingCart")
48
- displayOrder: number
49
-
50
- # Conditional (required for non-context levels)
51
- parentPath: "context.application.module" (dot-separated)
52
- ```
53
-
54
- ### 3. MCP Prerequisite Check (BLOCKING)
55
-
56
- **CRITICAL:** This check is **BLOCKING** - the skill cannot proceed without MCP.
57
-
58
- > See `_shared.md` → "MCP Prerequisite Guard (BLOCKING)" for the full pattern.
59
-
60
- ```
61
- Call: mcp__smartstack__validate_conventions
62
- Args: { checks: ["tables"] }
63
- ```
64
-
65
- **On success:** Set `mcp_available = true`, continue to Step 4.
66
-
67
- **On failure (STOP):**
68
-
69
- ```
70
- ═══════════════════════════════════════════════════════════════
71
- MCP SMARTSTACK NOT AVAILABLE - SKILL BLOCKED
72
- ═══════════════════════════════════════════════════════════════
73
-
74
- The SmartStack MCP server is required for the application
75
- skill but could not be reached.
76
-
77
- To install:
78
- claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
79
-
80
- To verify:
81
- /mcp:healthcheck
82
-
83
- After installation, restart Claude Code and retry.
84
-
85
- ═══════════════════════════════════════════════════════════════
86
- ```
87
-
88
- **DO NOT** offer manual instructions or degraded execution.
89
- **DO NOT** proceed with step files.
90
- **STOP the skill immediately.**
91
-
92
- ### 4. Detect Project Type
93
-
94
- Read `.smartstack/config.json` at the project root to determine the seeding strategy:
95
-
96
- ```
97
- Read: .smartstack/config.json
98
- Extract: projectType, dbContext
99
- ```
100
-
101
- | projectType | dbContext | Seeding Strategy |
102
- |-------------|----------|-----------------|
103
- | `core` | `core` | HasData() in Configuration files (existing pattern) |
104
- | `client` | `extensions` | IClientSeedDataProvider (runtime seeding) |
105
-
106
- **If file not found or projectType missing:** Default to `core` / `hasdata`.
107
-
108
- Store:
109
- ```
110
- {project_type} = "core" or "client"
111
- {db_context} = "core" or "extensions"
112
- {seeding_strategy} = "hasdata" or "provider"
113
- ```
114
-
115
- ### 4b. Detect Feature.json Context (Optional Enrichment)
116
-
117
- Search for a Business Analysis feature.json for the target module:
118
-
119
- ```
120
- Glob: docs/business/*/{code}/business-analyse/v*/feature.json
121
- .business-analyse/business/*/modules/{code}/features/*/feature.json
122
- ```
123
-
124
- **If found (status = "handed-off" or "consolidated"):**
125
-
126
- Read the feature.json and extract context for subsequent steps:
127
-
128
- | feature.json Section | Used In Step | Extracted Data |
129
- |----------------------|-------------|----------------|
130
- | `analysis.entities[]` | step-04 (backend) | Entity names, attributes, relationships, validations |
131
- | `specification.useCases[]` | step-04 (backend) | API endpoint definitions beyond basic CRUD |
132
- | `specification.permissionMatrix` | step-02 (permissions) | Custom permission paths and role assignments |
133
- | `specification.apiEndpoints[]` | step-04 (backend) | Exact HTTP methods, routes, DTOs |
134
- | `specification.navigation` | step-01 (navigation) | Navigation hierarchy with labels and icons |
135
- | `specification.i18nKeys` | step-05 (frontend) | Pre-defined translation keys |
136
- | `specification.validations[]` | step-04 (backend) | Field-level validation rules |
137
- | `specification.uiWireframes[]` | step-05 (frontend) | UI layout guidance |
138
- | `specification.seedDataCore` | step-01, step-02, step-03 | Pre-computed seeds |
139
- | `analysis.businessRules[]` | step-04, step-07 | Business rules for service logic and tests |
140
- | `specification.lifeCycles[]` | step-04 (backend) | Entity state machines |
141
- | `specification.dashboards` | step-05 (frontend) | Dashboard KPIs and chart specs |
142
- | `documentation` | step-08 | userDocRequired / techDocRequired flags |
143
-
144
- Store:
145
- ```
146
- {feature_json_path} = "path/to/feature.json" or null
147
- {has_feature_context} = true or false
148
- {feature_data} = parsed feature.json object (if found)
149
- ```
150
-
151
- **If NOT found or status not in ["handed-off", "consolidated"]:**
152
-
153
- ```
154
- {has_feature_context} = false
155
- ```
156
-
157
- Continue normally. All subsequent steps use their standard generation logic (generic CRUD).
158
-
159
- > **When `{has_feature_context} = true`**, subsequent steps SHOULD use the feature.json data
160
- > to generate more accurate code: entities with correct attributes and relationships, custom
161
- > permissions beyond basic CRUD, specific API routes, validation rules, and business logic
162
- > in services. This reduces post-generation manual corrections significantly.
27
+ See [references/init-parameter-detection.md](../references/init-parameter-detection.md) for:
28
+ - Navigation level detection (application/module/section)
29
+ - Parameter extraction (code, labels, icon, displayOrder)
30
+ - Project type & seeding strategy detection
31
+ - Feature.json context enrichment (optional)
32
+ - MCP prerequisite validation (BLOCKING)
163
33
 
164
34
  ### 5. Build Full Path
165
35
 
166
36
  ```
167
37
  {full_path} = {parentPath}.{code} (if parentPath exists)
168
- {full_path} = {code} (if context level)
38
+ {full_path} = {code} (if application level)
169
39
 
170
40
  Example:
171
41
  level: module
172
- parentPath: erp.sales
42
+ parentPath: sales
173
43
  code: products
174
- → full_path: erp.sales.products
44
+ → full_path: sales.products
175
45
  ```
176
46
 
177
47
  ### 6. Infer Descriptions (if not provided)
@@ -218,7 +88,7 @@ descriptions:
218
88
 
219
89
  | Variable | Description |
220
90
  |----------|-------------|
221
- | `{level}` | context, application, module, or section |
91
+ | `{level}` | application, module, or section |
222
92
  | `{code}` | kebab-case identifier |
223
93
  | `{full_path}` | Complete navigation path |
224
94
  | `{parent_path}` | Parent path (null for context) |
@@ -29,7 +29,7 @@ From step-00-init:
29
29
 
30
30
  | Variable | Description |
31
31
  |----------|-------------|
32
- | `{level}` | context, application, module, or section |
32
+ | `{level}` | application, module, or section |
33
33
  | `{code}` | kebab-case identifier |
34
34
  | `{full_path}` | Complete navigation path |
35
35
  | `{parent_path}` | Parent path (null for context) |
@@ -55,7 +55,7 @@ Tool: mcp__smartstack__scaffold_navigation
55
55
  Args:
56
56
  level: "{level}"
57
57
  code: "{code}"
58
- parentPath: "{parent_path}" # Omit if level is "context"
58
+ parentPath: "{parent_path}" # Omit if level is "application" (top-level)
59
59
  labels:
60
60
  fr: "{labels.fr}"
61
61
  en: "{labels.en}"
@@ -158,7 +158,7 @@ See [references/nav-fallback-procedure.md](../references/nav-fallback-procedure.
158
158
 
159
159
  ## FAILURE MODES
160
160
 
161
- - Missing parent path for non-context level (return to step-00)
161
+ - Missing parent path for non-application level (return to step-00)
162
162
  - Invalid level (return to step-00)
163
163
  - Parent entity not found in existing seeds (ask user for parent GUID)
164
164
 
@@ -28,7 +28,7 @@ From previous steps:
28
28
 
29
29
  | Variable | Description |
30
30
  |----------|-------------|
31
- | `{level}` | context, application, module, or section |
31
+ | `{level}` | application, module, or section |
32
32
  | `{full_path}` | Complete navigation path (navRoute) |
33
33
  | `{navigation_guid}` | GUID of the navigation entity |
34
34
  | `{labels}` | Object with fr, en, it, de |
@@ -45,7 +45,7 @@ For permissions, the navRoute is the `{full_path}`:
45
45
 
46
46
  ```
47
47
  navRoute = "{full_path}"
48
- Example: "erp.sales.products"
48
+ Example: "sales.products"
49
49
  ```
50
50
 
51
51
  ### 2. Call MCP generate_permissions
@@ -76,7 +76,7 @@ Add to `Application/Common/Authorization/Permissions.cs`:
76
76
 
77
77
  **Usage in Controller:**
78
78
  ```csharp
79
- [RequirePermission(Permissions.{Context}.{Application}.{Module}.Read)]
79
+ [RequirePermission(Permissions.{Application}.{Module}.Read)]
80
80
  public async Task<ActionResult> GetAll() { ... }
81
81
  ```
82
82
  ```
@@ -186,7 +186,7 @@ If MCP call fails:
186
186
  ## FAILURE MODES
187
187
 
188
188
  - MCP call failed (display error, stop)
189
- - Invalid navRoute format (must be context.application.module)
189
+ - Invalid navRoute format (must be application.module)
190
190
  - Missing navigation entity (return to step-01)
191
191
 
192
192
  ---
@@ -37,7 +37,7 @@ From previous steps:
37
37
  | Variable | Description |
38
38
  |----------|-------------|
39
39
  | `{full_path}` | Complete navigation path (navRoute) |
40
- | `{level}` | context, application, module, or section |
40
+ | `{level}` | application, module, or section |
41
41
  | `{permission_guids}` | GUIDs for generated permissions |
42
42
  | `{mcp_available}` | Boolean - MCP connectivity status |
43
43
  | `{project_type}` | "core" or "client" |
@@ -49,13 +49,10 @@ From previous steps:
49
49
 
50
50
  ### 1. Determine Default Role Assignments
51
51
 
52
- Based on navigation context, apply default role mappings:
53
-
54
- | Context | PlatformAdmin | TenantAdmin | StandardUser |
55
- |---------|---------------|-------------|--------------|
56
- | `platform.*` | Full CRUD | Read only | None |
57
- | `business.*` | Full CRUD | Full CRUD | Read only |
58
- | `personal.*` | None | Full CRUD | Full CRUD |
52
+ See [references/roles-client-project-handling.md](../references/roles-client-project-handling.md) for:
53
+ - Default role mapping table by application prefix
54
+ - ApplicationRolesSeedData.cs requirements (once per application)
55
+ - {Module}RolePermissionSeedData.cs requirements (per module)
59
56
 
60
57
  ### 2. Call MCP scaffold_role_permissions
61
58
 
@@ -134,178 +131,24 @@ If MCP call fails or `{mcp_available}` = false:
134
131
 
135
132
  > **Condition:** `{seeding_strategy}` = "provider"
136
133
 
137
- **For core (`{seeding_strategy}` = "hasdata"):** Write in RolePermissionConfiguration.cs (existing pattern)
138
-
139
- **For client (`{seeding_strategy}` = "provider"):** DO NOT write in RolePermissionConfiguration.cs (does not exist in client projects).
140
-
141
- Instead, create TWO files:
142
-
143
- ### 1. ApplicationRolesSeedData.cs (ONCE per application)
144
-
145
- **File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
146
-
147
- **Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
148
-
149
- **CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
150
-
151
- See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
152
-
153
- **Key requirements:**
154
- - Deterministic GUIDs based on `role-{applicationId}-{roleType}`
155
- - 4 roles: Admin, Manager, Contributor, Viewer
156
- - Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
157
- - `ApplicationId` references the navigation application GUID
158
- - `IsSystem = false` (application-scoped, not system roles)
159
-
160
- **Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
161
-
162
- ### 2. {Module}RolePermissionSeedData.cs (PER module)
163
-
164
- **File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
165
-
166
- **Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
167
-
168
- Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
169
- These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
170
-
171
- **After creating both files:** Proceed to step-03b-provider.md (which will skip for core projects).
134
+ See [references/roles-client-project-handling.md](../references/roles-client-project-handling.md) for:
135
+ - ApplicationRolesSeedData.cs creation (once per application)
136
+ - {Module}RolePermissionSeedData.cs creation (per module)
137
+ - Role code naming and GUID generation rules
138
+ - Detection of existing ApplicationRolesSeedData.cs
172
139
 
173
140
  ---
174
141
 
175
142
  ## FALLBACK PROCEDURE (When MCP Unavailable)
176
143
 
177
- > This procedure generates role-permission HasData entries following SmartStack.app patterns.
178
-
179
- ### F1. Read Existing RolePermissionConfiguration.cs
180
-
181
- ```
182
- Glob: **/Persistence/Configurations/Authorization/RolePermissionConfiguration.cs
183
- ```
184
-
185
- Read the file to determine:
186
- - Existing role-permission mappings
187
- - The GetSeedData() method structure
188
- - Which roles already have which permissions
189
- - The GUID generation method used (deterministic or hardcoded)
190
-
191
- ### F2. Read Role GUIDs
192
-
193
- **System-level roles** (well-known GUIDs):
194
-
195
- | Role | GUID |
196
- |------|------|
197
- | SuperAdmin | `11111111-1111-1111-1111-111111111111` |
198
- | PlatformAdmin | `22222222-2222-2222-2222-222222222222` |
199
- | TenantAdmin | `33333333-3333-3333-3333-333333333333` |
200
- | StandardUser | `44444444-4444-4444-4444-444444444444` |
201
-
202
- **IMPORTANT:** Read the actual `RoleSeedData.cs` or `RoleConfiguration.cs` in the target project to confirm the actual role GUIDs. The above are defaults; the project may use different values.
203
-
204
- **Application-scoped roles** (deterministic GUIDs based on application):
205
-
206
- ```csharp
207
- // Read the existing GenerateDeterministicGuid method in RolePermissionConfiguration.cs
208
- // Typically uses MD5 hash:
209
- private static Guid GenerateDeterministicGuid(Guid applicationId, string roleType)
210
- {
211
- using var md5 = System.Security.Cryptography.MD5.Create();
212
- var input = $"{applicationId}-{roleType}";
213
- var hash = md5.ComputeHash(System.Text.Encoding.UTF8.GetBytes(input));
214
- return new Guid(hash);
215
- }
216
- // roleType values: "admin", "manager", "contributor", "viewer"
217
- ```
218
-
219
- Find the `applicationId` from `NavigationApplicationSeedData.cs` matching `{full_path}`.
220
-
221
- ### F3. Determine Context-Based Default Mappings
222
-
223
- Based on `{full_path}` prefix:
224
-
225
- | Context Prefix | SuperAdmin | PlatformAdmin | App Admin | App Manager | App Contributor | App Viewer |
226
- |----------------|------------|---------------|-----------|-------------|-----------------|------------|
227
- | `platform.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
228
- | `business.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
229
- | `personal.*` | wildcard | None | Full CRUD | CRU | CR | R |
230
-
231
- ### F4. Generate RolePermission HasData Entries
232
-
233
- Using `{permission_guids}` from step-02:
234
-
235
- ```csharp
236
- // In RolePermissionConfiguration.cs - GetSeedData() method
237
- var seedDate = SeedConstants.SeedDate;
238
-
239
- // ============================================================
240
- // {MODULE_NAME} PERMISSIONS
241
- // ============================================================
242
-
243
- // SuperAdmin: already has *.* wildcard - no individual entries needed
244
-
245
- // PlatformAdmin (for platform.* context)
246
- rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
247
- rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
248
- rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
249
- rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.delete}, AssignedAt = seedDate });
250
-
251
- // Application-scoped: Admin → wildcard
252
- rolePermissions.Add(new { RoleId = appAdminRoleId, PermissionId = {permission_guids.wildcard}, AssignedAt = seedDate });
253
-
254
- // Application-scoped: Manager → CRU (read + create + update — no delete)
255
- rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
256
- rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
257
- rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
258
-
259
- // Application-scoped: Contributor → CR
260
- rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
261
- rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
262
-
263
- // Application-scoped: Viewer → R
264
- rolePermissions.Add(new { RoleId = appViewerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
265
- ```
266
-
267
- ### F5. Write Code to RolePermissionConfiguration.cs
268
-
269
- **CRITICAL:** Do NOT just display code. WRITE it to the actual file.
270
-
271
- 1. Open `RolePermissionConfiguration.cs`
272
- 2. Find the `GetSeedData()` method
273
- 3. Add the new role-permission entries to the list
274
- 4. Add necessary permission GUID references (import from PermissionConfiguration or use inline)
275
- 5. Add comments grouping the new entries: `// {MODULE_NAME} PERMISSIONS`
276
-
277
- ### F6. Present Summary
278
-
279
- ```markdown
280
- ## Role-Permission Mappings Generated (Fallback)
281
-
282
- | Role | Permissions |
283
- |------|-------------|
284
- | SuperAdmin | Already has wildcard access |
285
- | PlatformAdmin | {full_path}.read, .create, .update, .delete |
286
- | App Admin | {full_path}.* (wildcard) |
287
- | App Manager | {full_path}.read, .create, .update |
288
- | App Contributor | {full_path}.read, .create |
289
- | App Viewer | {full_path}.read |
290
-
291
- Written to: RolePermissionConfiguration.cs
292
- ```
293
-
294
- ### F7. Offer User Adjustment
295
-
296
- ```yaml
297
- questions:
298
- - header: "Role Access"
299
- question: "Default role-permission mappings have been applied. Adjust?"
300
- options:
301
- - label: "Keep defaults (Recommended)"
302
- description: "Standard role hierarchy applied"
303
- - label: "Custom adjustments"
304
- description: "I want to change specific role permissions"
305
- multiSelect: false
306
- ```
307
-
308
- If user selects "Custom adjustments", ask which roles/permissions to change and update the file accordingly.
144
+ See [references/roles-fallback-procedure.md](../references/roles-fallback-procedure.md) for the complete 7-step fallback:
145
+ - **F1:** Read existing RolePermissionConfiguration.cs to determine state
146
+ - **F2:** Read role GUIDs (system-level and application-scoped)
147
+ - **F3:** Determine default mappings based on application prefix
148
+ - **F4:** Generate RolePermission HasData entries using permission GUIDs
149
+ - **F5:** Write code to RolePermissionConfiguration.cs (CRITICAL: WRITE not display)
150
+ - **F6:** Present summary
151
+ - **F7:** Offer user adjustment option
309
152
 
310
153
  ---
311
154
 
@@ -33,7 +33,7 @@ From previous steps:
33
33
 
34
34
  | Variable | Description |
35
35
  |----------|-------------|
36
- | `{level}` | context, application, module, or section |
36
+ | `{level}` | application, module, or section |
37
37
  | `{code}` | kebab-case identifier |
38
38
  | `{full_path}` | Complete navigation path |
39
39
  | `{labels}` | Object with fr, en, it, de |
@@ -82,7 +82,6 @@ Using the SeedData files as data sources, generate the `{AppPascalName}SeedDataP
82
82
  Adapt the template:
83
83
  - Replace `{AppPascalName}` with the PascalCase application name
84
84
  - Replace `{app_code}` with the kebab-case application code
85
- - Replace `{context_code}` with the parent context code
86
85
  - Fill in the actual navigation, permission, and role-permission creation logic
87
86
  using the helper methods from the SeedData classes
88
87
 
@@ -32,7 +32,7 @@ From previous steps:
32
32
 
33
33
  | Variable | Description |
34
34
  |----------|-------------|
35
- | `{level}` | context, application, module, or section |
35
+ | `{level}` | application, module, or section |
36
36
  | `{code}` | kebab-case identifier |
37
37
  | `{full_path}` | Complete navigation path (navRoute) |
38
38
  | `{labels}` | Object with fr, en, it, de |
@@ -53,32 +53,12 @@ code: "user-profiles" → entityName: "UserProfile"
53
53
 
54
54
  ### 2. Determine Table Prefix and Controller Folder
55
55
 
56
- **Table Prefix priority:**
57
- 1. **If a `feature.json` exists** with `metadata.tablePrefix` → use that prefix (e.g., `rh_`, `fi_`)
58
- 2. **Otherwise**, derive from navigation context using the fallback table below
59
-
60
- **Fallback table (when no feature.json tablePrefix is available):**
61
-
62
- | Context | Table Prefix | Controller Folder |
63
- |---------|--------|-------------------|
64
- | platform.administration | `auth_` or `cfg_` | `Admin` |
65
- | platform.support | `support_` | `Support` |
66
- | business.* | `ref_` or domain-specific | `Business` |
67
- | personal.* | `usr_` | `User` |
68
-
69
- ```
70
- # Check for feature.json tablePrefix
71
- Search for feature.json in:
72
- - docs/business/{application}/business-analyse/*/feature.json
73
- - Read metadata.tablePrefix if exists
74
-
75
- IF metadata.tablePrefix exists:
76
- {prefix} = metadata.tablePrefix # e.g., "rh_"
77
- ELSE:
78
- {prefix} = derived from context table above
79
- ```
80
-
81
- Store: `{controller_folder}` = the Controller Folder from the table above.
56
+ See [references/backend-table-prefix-mapping.md](../references/backend-table-prefix-mapping.md) for:
57
+ - Table prefix priority (feature.json vs. fallback)
58
+ - Application-to-prefix mapping table
59
+ - Feature.json detection and extraction
60
+ - Controller folder organization
61
+ - Store `{controller_folder}` from the mapping
82
62
 
83
63
  ### 3. Call MCP scaffold_extension
84
64
 
@@ -100,93 +80,22 @@ Args:
100
80
 
101
81
  ### 4. Parse MCP Response
102
82
 
103
- The tool generates (paths organized by navRoute hierarchy `{context}.{application}.{module}`):
104
- - `Domain/{Context}/{Application}/{Module}/{EntityName}.cs` - Entity with BaseEntity
105
- - `Infrastructure/Persistence/Configurations/{Context}/{Application}/{Module}/{EntityName}Configuration.cs` - EF Config
83
+ The tool generates (paths organized by navRoute hierarchy `{application}.{module}`):
84
+ - `Domain/{Application}/{Module}/{EntityName}.cs` - Entity with BaseEntity
85
+ - `Infrastructure/Persistence/Configurations/{Application}/{Module}/{EntityName}Configuration.cs` - EF Config
106
86
  - `Application/Common/Interfaces/I{EntityName}Service.cs` - Service Interface
107
- - `Infrastructure/Services/{Context}/{Application}/{Module}/{EntityName}Service.cs` - Service Implementation
87
+ - `Infrastructure/Services/{Application}/{Module}/{EntityName}Service.cs` - Service Implementation
108
88
  - `Api/Controllers/{controller_folder}/{Application}/{EntityName}Controller.cs` - REST Controller
109
- - `Application/{Context}/{Application}/{Module}/DTOs/{EntityName}ResponseDto.cs` - Response DTO
110
- - `Application/{Context}/{Application}/{Module}/DTOs/Create{EntityName}Dto.cs` - Create request
111
- - `Application/{Context}/{Application}/{Module}/DTOs/Update{EntityName}Dto.cs` - Update request
112
-
113
- ### 5. Present Output to User
114
-
115
- ```markdown
116
- ## Backend Code Generated
117
-
118
- ### Domain Layer
119
- - `Domain/{Context}/{Application}/{Module}/{EntityName}.cs`
120
-
121
- ### Infrastructure Layer
122
- - `Persistence/Configurations/{Context}/{Application}/{Module}/{EntityName}Configuration.cs`
123
- - `Services/{Context}/{Application}/{Module}/{EntityName}Service.cs`
124
-
125
- ### Application Layer
126
- - `Common/Interfaces/I{EntityName}Service.cs`
127
- - `{Context}/{Application}/{Module}/DTOs/{EntityName}ResponseDto.cs`
128
- - `{Context}/{Application}/{Module}/DTOs/Create{EntityName}Dto.cs`
129
- - `{Context}/{Application}/{Module}/DTOs/Update{EntityName}Dto.cs`
130
-
131
- ### API Layer
132
- - `Controllers/{controller_folder}/{Application}/{EntityName}Controller.cs`
133
- - NavRoute: `{full_path}`
134
- - Endpoints:
135
- - GET /api/{code} - List all
136
- - GET /api/{code}/{id} - Get by ID
137
- - POST /api/{code} - Create
138
- - PUT /api/{code}/{id} - Update
139
- - DELETE /api/{code}/{id} - Delete
140
-
141
- ### Next Steps
142
- 1. Add DbSet to ICoreDbContext: `public DbSet<{EntityName}> {EntityName}s => Set<{EntityName}>();`
143
- 2. Register service in DI: `services.AddScoped<I{EntityName}Service, {EntityName}Service>();`
144
- 3. Run: `dotnet ef migrations add core_vX.X.X_XXX_Add{EntityName}`
145
- ```
146
-
147
- ### 6. Entity Seeding (Optional)
148
-
149
- > Ask the user if they want to seed initial data for the entity.
150
- > This creates runtime seed data (applied at startup via DevDataSeeder), following the same
151
- > architecture as core (SeedData provider pattern).
152
-
153
- ```yaml
154
- questions:
155
- - header: "Seed Data"
156
- question: "Would you like to generate initial seed data for {EntityName}?"
157
- options:
158
- - label: "Yes - Generate SeedData provider"
159
- description: "Creates {EntityName}SeedData.cs + registers in DevDataSeeder (same pattern as core)"
160
- - label: "No - Skip seeding"
161
- description: "Entity starts empty (can add seed data later)"
162
- multiSelect: false
163
- ```
89
+ - `Application/{Application}/{Module}/DTOs/{EntityName}ResponseDto.cs` - Response DTO
90
+ - `Application/{Application}/{Module}/DTOs/Create{EntityName}Dto.cs` - Create request
91
+ - `Application/{Application}/{Module}/DTOs/Update{EntityName}Dto.cs` - Update request
164
92
 
165
- #### If User Selects YES:
93
+ ### 5-7. Present Output, Entity Seeding & Store Info
166
94
 
167
- See [references/backend-entity-seeding.md](../references/backend-entity-seeding.md) for the full seeding pattern:
168
- 1. **SeedData file** (`{EntityName}SeedData.cs`) static class with deterministic GUIDs, 3-5 samples
169
- 2. **DevDataSeeder update** add `Seed{EntityName}sAsync()` method with idempotent check
170
-
171
- #### If User Selects NO:
172
-
173
- Skip this section and proceed to storing entity info.
174
-
175
- ```markdown
176
- > Skipping entity seed data. You can generate it later using the SeedData provider pattern
177
- > documented in templates-seed.md.
178
- ```
179
-
180
- ### 7. Store Entity Info
181
-
182
- Store entity information for frontend generation:
183
-
184
- ```
185
- {entity_name} = "{EntityName}"
186
- {entity_code} = "{code}"
187
- {api_route} = "/api/{code}"
188
- {has_seed_data} = true/false // Whether SeedData provider was generated
189
- ```
95
+ See [references/backend-seeding-and-dto-output.md](../references/backend-seeding-and-dto-output.md) for:
96
+ - Output formatting by layer (Domain, Infrastructure, Application, API)
97
+ - Entity seeding questions and responses
98
+ - Entity info storage for frontend generation
190
99
 
191
100
  ---
192
101