@jeancodogno/specforce-kit 0.1.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 (153) hide show
  1. package/.geminiignore +15 -0
  2. package/.github/workflows/ci.yml +100 -0
  3. package/.github/workflows/release.yml +51 -0
  4. package/.golangci.yml +21 -0
  5. package/.goreleaser.yaml +43 -0
  6. package/.rgignore +13 -0
  7. package/.specforce/config.yaml +32 -0
  8. package/.specforce/docs/.gitkeep +0 -0
  9. package/.specforce/docs/architecture.md +98 -0
  10. package/.specforce/docs/engineering.md +80 -0
  11. package/.specforce/docs/governance.md +30 -0
  12. package/.specforce/docs/memorial.md +44 -0
  13. package/.specforce/docs/principles.md +31 -0
  14. package/.specforce/docs/security.md +31 -0
  15. package/.specforce/docs/ui-ux.md +129 -0
  16. package/.specforce/specs/.gitkeep +0 -0
  17. package/AGENTS.md +36 -0
  18. package/CONTRIBUTING.md +81 -0
  19. package/LICENSE +21 -0
  20. package/Makefile +49 -0
  21. package/README.md +144 -0
  22. package/assets/logo-header.png +0 -0
  23. package/assets/logo.png +0 -0
  24. package/docs/artifacts.md +41 -0
  25. package/docs/cli.md +73 -0
  26. package/docs/configuration.md +50 -0
  27. package/docs/getting-started.md +110 -0
  28. package/docs/supported-tools.md +14 -0
  29. package/go.mod +35 -0
  30. package/go.sum +61 -0
  31. package/index.js +0 -0
  32. package/package.json +26 -0
  33. package/src/cmd/specforce/main.go +23 -0
  34. package/src/cmd/specforce/main_test.go +7 -0
  35. package/src/internal/agent/artifacts/constitution/architecture.yaml +70 -0
  36. package/src/internal/agent/artifacts/constitution/engineering.yaml +52 -0
  37. package/src/internal/agent/artifacts/constitution/governance.yaml +41 -0
  38. package/src/internal/agent/artifacts/constitution/memorial.yaml +55 -0
  39. package/src/internal/agent/artifacts/constitution/principles.yaml +54 -0
  40. package/src/internal/agent/artifacts/constitution/security.yaml +47 -0
  41. package/src/internal/agent/artifacts/constitution/ui-ux.yaml +158 -0
  42. package/src/internal/agent/artifacts/spec/design.yaml +50 -0
  43. package/src/internal/agent/artifacts/spec/requirements.yaml +48 -0
  44. package/src/internal/agent/artifacts/spec/tasks.yaml +55 -0
  45. package/src/internal/agent/compatibility_test.go +120 -0
  46. package/src/internal/agent/cwd_test.go +9 -0
  47. package/src/internal/agent/embed.go +19 -0
  48. package/src/internal/agent/integration_test.go +138 -0
  49. package/src/internal/agent/kit/agents/product-analyst.yaml +31 -0
  50. package/src/internal/agent/kit/agents/technical-developer.yaml +28 -0
  51. package/src/internal/agent/kit/agents/technical-project-planner.yaml +30 -0
  52. package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +36 -0
  53. package/src/internal/agent/kit/agents/technical-solution-architect.yaml +32 -0
  54. package/src/internal/agent/kit/commands/archive.yaml +25 -0
  55. package/src/internal/agent/kit/commands/constitution.yaml +132 -0
  56. package/src/internal/agent/kit/commands/implement.yaml +96 -0
  57. package/src/internal/agent/kit/commands/spec.yaml +94 -0
  58. package/src/internal/agent/kit/instructions/archive.md +68 -0
  59. package/src/internal/agent/kit/kit.yaml +111 -0
  60. package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +56 -0
  61. package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +58 -0
  62. package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +38 -0
  63. package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +52 -0
  64. package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +137 -0
  65. package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +103 -0
  66. package/src/internal/agent/kit_manifests_test.go +58 -0
  67. package/src/internal/agent/manifest.go +15 -0
  68. package/src/internal/agent/registry.go +69 -0
  69. package/src/internal/agent/registry_test.go +51 -0
  70. package/src/internal/agent/translator.go +334 -0
  71. package/src/internal/agent/translator_test.go +734 -0
  72. package/src/internal/cli/archive.go +91 -0
  73. package/src/internal/cli/archive_test.go +67 -0
  74. package/src/internal/cli/cli.go +259 -0
  75. package/src/internal/cli/cli_test.go +130 -0
  76. package/src/internal/cli/cobra/archive.go +26 -0
  77. package/src/internal/cli/cobra/console.go +21 -0
  78. package/src/internal/cli/cobra/constitution.go +44 -0
  79. package/src/internal/cli/cobra/dummy_test.go +7 -0
  80. package/src/internal/cli/cobra/implementation.go +50 -0
  81. package/src/internal/cli/cobra/init.go +23 -0
  82. package/src/internal/cli/cobra/install.go +21 -0
  83. package/src/internal/cli/cobra/root.go +47 -0
  84. package/src/internal/cli/cobra/spec.go +91 -0
  85. package/src/internal/cli/console.go +48 -0
  86. package/src/internal/cli/constitution.go +190 -0
  87. package/src/internal/cli/constitution_test.go +50 -0
  88. package/src/internal/cli/implementation.go +153 -0
  89. package/src/internal/cli/implementation_test.go +165 -0
  90. package/src/internal/cli/spec.go +369 -0
  91. package/src/internal/cli/spec_test.go +85 -0
  92. package/src/internal/constitution/registry.go +139 -0
  93. package/src/internal/constitution/registry_test.go +97 -0
  94. package/src/internal/constitution/status.go +70 -0
  95. package/src/internal/constitution/status_test.go +160 -0
  96. package/src/internal/core/blueprint.go +49 -0
  97. package/src/internal/core/blueprint_test.go +58 -0
  98. package/src/internal/core/config.go +124 -0
  99. package/src/internal/core/config_test.go +145 -0
  100. package/src/internal/core/constants.go +13 -0
  101. package/src/internal/core/errors.go +31 -0
  102. package/src/internal/core/errors_test.go +48 -0
  103. package/src/internal/core/hooks.go +89 -0
  104. package/src/internal/core/hooks_test.go +51 -0
  105. package/src/internal/core/kit.go +15 -0
  106. package/src/internal/core/kit_test.go +65 -0
  107. package/src/internal/core/path.go +115 -0
  108. package/src/internal/core/path_test.go +101 -0
  109. package/src/internal/core/ui.go +19 -0
  110. package/src/internal/installer/dependencies.go +23 -0
  111. package/src/internal/installer/install.go +89 -0
  112. package/src/internal/installer/installer.go +45 -0
  113. package/src/internal/installer/installer_test.go +96 -0
  114. package/src/internal/project/agents_md.go +108 -0
  115. package/src/internal/project/agents_md_test.go +101 -0
  116. package/src/internal/project/bootstrapper.go +64 -0
  117. package/src/internal/project/bootstrapper_test.go +89 -0
  118. package/src/internal/project/detector.go +35 -0
  119. package/src/internal/project/detector_test.go +96 -0
  120. package/src/internal/project/refresh_integration_test.go +86 -0
  121. package/src/internal/project/service.go +93 -0
  122. package/src/internal/project/service_test.go +135 -0
  123. package/src/internal/spec/archive.go +49 -0
  124. package/src/internal/spec/archive_test.go +55 -0
  125. package/src/internal/spec/discovery.go +53 -0
  126. package/src/internal/spec/discovery_test.go +60 -0
  127. package/src/internal/spec/implementation.go +296 -0
  128. package/src/internal/spec/implementation_test.go +253 -0
  129. package/src/internal/spec/registry.go +142 -0
  130. package/src/internal/spec/registry_test.go +105 -0
  131. package/src/internal/spec/scanner.go +219 -0
  132. package/src/internal/spec/scanner_test.go +243 -0
  133. package/src/internal/spec/service.go +157 -0
  134. package/src/internal/spec/service_test.go +238 -0
  135. package/src/internal/spec/status.go +94 -0
  136. package/src/internal/spec/status_test.go +146 -0
  137. package/src/internal/spec/tasks.go +103 -0
  138. package/src/internal/spec/tasks_test.go +137 -0
  139. package/src/internal/tui/components.go +132 -0
  140. package/src/internal/tui/console.go +247 -0
  141. package/src/internal/tui/console_test.go +19 -0
  142. package/src/internal/tui/constitution.go +36 -0
  143. package/src/internal/tui/constitution_test.go +32 -0
  144. package/src/internal/tui/implementation.go +151 -0
  145. package/src/internal/tui/logo.go +89 -0
  146. package/src/internal/tui/multiselect.go +199 -0
  147. package/src/internal/tui/progressbar.go +37 -0
  148. package/src/internal/tui/progressbar_test.go +30 -0
  149. package/src/internal/tui/spec.go +35 -0
  150. package/src/internal/tui/spinner.go +66 -0
  151. package/src/internal/tui/terminal.go +18 -0
  152. package/src/internal/tui/theme.go +125 -0
  153. package/src/internal/tui/ui.go +52 -0
@@ -0,0 +1,734 @@
1
+ package agent
2
+
3
+ import (
4
+ "context"
5
+ "errors"
6
+ "os"
7
+ "path/filepath"
8
+ "strings"
9
+ "testing"
10
+
11
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
12
+ "github.com/jeancodogno/specforce-kit/src/internal/installer"
13
+ )
14
+
15
+ func getMockKitConfig() *core.KitConfig {
16
+ return &core.KitConfig{
17
+ Tools: map[string]core.ToolRoute{
18
+ "claude": {
19
+ Target: ".claude/",
20
+ Mappings: map[string]core.MappingConfig{
21
+ "agents": {Path: "agents", Ext: ".md"},
22
+ "skills": {Path: "skills", Ext: ".md"},
23
+ "commands": {Path: "commands/spf", Ext: ".md"},
24
+ },
25
+ },
26
+ "gemini-cli": {
27
+ Target: ".gemini/",
28
+ Mappings: map[string]core.MappingConfig{
29
+ "agents": {Path: "agents", Ext: ".toml"},
30
+ },
31
+ },
32
+ "kimi-code": {
33
+ Target: ".kimi/",
34
+ Mappings: map[string]core.MappingConfig{
35
+ "commands": {Path: "skills/spf-*", Name: "SKILL", Ext: ".md"},
36
+ "skills": {Path: "skills", Ext: ".md"},
37
+ },
38
+ },
39
+ "wildcard-tool": {
40
+ Target: ".wildcard/",
41
+ Mappings: map[string]core.MappingConfig{
42
+ "commands": {Path: "tools", Name: "*-kit", Ext: ".md"},
43
+ },
44
+ },
45
+ },
46
+ }
47
+ }
48
+
49
+ func TestResolveMapping_Wildcards(t *testing.T) {
50
+ tmpDir, err := os.MkdirTemp("", "specforce-test-wildcards-*")
51
+ if err != nil {
52
+ t.Fatalf("failed to create temp dir: %v", err)
53
+ }
54
+ defer func() { _ = os.RemoveAll(tmpDir) }()
55
+
56
+ kitDir := filepath.Join(tmpDir, "kit")
57
+ _ = os.MkdirAll(filepath.Join(kitDir, "commands"), 0755)
58
+
59
+ blueprintYAML := "description: Test Command\ncontent: |\n # Hello\n"
60
+ _ = os.WriteFile(filepath.Join(kitDir, "commands/archive.yaml"), []byte(blueprintYAML), 0644)
61
+
62
+ kitFS := os.DirFS(kitDir)
63
+ kitConfig := &core.KitConfig{
64
+ Tools: map[string]core.ToolRoute{
65
+ "generic-tool": {
66
+ Target: ".generic/",
67
+ Mappings: map[string]core.MappingConfig{
68
+ "commands": {Path: "skills/spf-*", Name: "SKILL", Ext: ".md"},
69
+ },
70
+ },
71
+ "wildcard-tool": {
72
+ Target: ".wildcard/",
73
+ Mappings: map[string]core.MappingConfig{
74
+ "commands": {Path: "tools", Name: "*-kit", Ext: ".md"},
75
+ },
76
+ },
77
+ },
78
+ }
79
+ projectRoot := filepath.Join(tmpDir, "project")
80
+
81
+ // Test case 1: Path expansion + fixed name
82
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "commands/archive.yaml", "generic-tool", installer.Options{})
83
+ if err != nil {
84
+ t.Fatalf("processBlueprint failed for generic-tool: %v", err)
85
+ }
86
+ expectedGeneric := filepath.Join(projectRoot, ".generic/skills/spf-archive/SKILL.md")
87
+ if _, err := os.Stat(expectedGeneric); os.IsNotExist(err) {
88
+ t.Errorf("expected expanded path %s to exist", expectedGeneric)
89
+ }
90
+
91
+ // Test case 2: Fixed path + name expansion
92
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "commands/archive.yaml", "wildcard-tool", installer.Options{})
93
+ if err != nil {
94
+ t.Fatalf("processBlueprint failed for wildcard-tool: %v", err)
95
+ }
96
+ expectedWildcard := filepath.Join(projectRoot, ".wildcard/tools/archive-kit.md")
97
+ if _, err := os.Stat(expectedWildcard); os.IsNotExist(err) {
98
+ t.Errorf("expected expanded name %s to exist", expectedWildcard)
99
+ }
100
+ }
101
+
102
+ func TestResolveMapping_Whitelisting(t *testing.T) {
103
+ tmpDir, err := os.MkdirTemp("", "specforce-test-whitelisting-*")
104
+ if err != nil {
105
+ t.Fatalf("failed to create temp dir: %v", err)
106
+ }
107
+ defer func() { _ = os.RemoveAll(tmpDir) }()
108
+
109
+ kitDir := filepath.Join(tmpDir, "kit")
110
+ _ = os.MkdirAll(filepath.Join(kitDir, "agents"), 0755)
111
+ _ = os.WriteFile(filepath.Join(kitDir, "agents/test.yaml"), []byte("description: test"), 0644)
112
+
113
+ kitFS := os.DirFS(kitDir)
114
+ kitConfig := &core.KitConfig{
115
+ Tools: map[string]core.ToolRoute{
116
+ "minimal": {
117
+ Target: ".minimal/",
118
+ Mappings: map[string]core.MappingConfig{
119
+ "skills": {Path: "skills", Ext: ".md"},
120
+ },
121
+ },
122
+ },
123
+ }
124
+ projectRoot := filepath.Join(tmpDir, "project")
125
+
126
+ // Category 'agents' is NOT in 'minimal' mappings
127
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "agents/test.yaml", "minimal", installer.Options{})
128
+ if err != nil {
129
+ t.Fatalf("processBlueprint failed: %v", err)
130
+ }
131
+
132
+ // Should NOT exist
133
+ expectedPath := filepath.Join(projectRoot, ".minimal/agents/test.md")
134
+ if _, err := os.Stat(expectedPath); err == nil {
135
+ t.Errorf("expected file %s to NOT exist (should be whitelisted out)", expectedPath)
136
+ }
137
+ }
138
+
139
+ func TestResolveMapping_Defaulting(t *testing.T) {
140
+ tmpDir, err := os.MkdirTemp("", "specforce-test-defaulting-*")
141
+ if err != nil {
142
+ t.Fatalf("failed to create temp dir: %v", err)
143
+ }
144
+ defer func() { _ = os.RemoveAll(tmpDir) }()
145
+
146
+ kitDir := filepath.Join(tmpDir, "kit")
147
+ _ = os.MkdirAll(filepath.Join(kitDir, "agents"), 0755)
148
+ _ = os.WriteFile(filepath.Join(kitDir, "agents/my-slug.yaml"), []byte("description: test"), 0644)
149
+
150
+ kitFS := os.DirFS(kitDir)
151
+ kitConfig := &core.KitConfig{
152
+ Tools: map[string]core.ToolRoute{
153
+ "test-tool": {
154
+ Target: ".test/",
155
+ Mappings: map[string]core.MappingConfig{
156
+ "agents": {Path: "dir", Name: "", Ext: ".md"}, // Empty Name
157
+ },
158
+ },
159
+ },
160
+ }
161
+ projectRoot := filepath.Join(tmpDir, "project")
162
+
163
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "agents/my-slug.yaml", "test-tool", installer.Options{})
164
+ if err != nil {
165
+ t.Fatalf("processBlueprint failed: %v", err)
166
+ }
167
+
168
+ // Should default to 'my-slug'
169
+ expectedPath := filepath.Join(projectRoot, ".test/dir/my-slug.md")
170
+ if _, err := os.Stat(expectedPath); os.IsNotExist(err) {
171
+ t.Errorf("expected file %s to exist (defaulted to slug)", expectedPath)
172
+ }
173
+ }
174
+
175
+ func TestKimiExclusion(t *testing.T) {
176
+ tmpDir, err := os.MkdirTemp("", "specforce-test-kimi-exclusion-*")
177
+ if err != nil {
178
+ t.Fatalf("failed to create temp dir: %v", err)
179
+ }
180
+ defer func() { _ = os.RemoveAll(tmpDir) }()
181
+
182
+ kitDir := filepath.Join(tmpDir, "kit")
183
+ agentsDir := filepath.Join(kitDir, "agents")
184
+ _ = os.MkdirAll(agentsDir, 0755)
185
+
186
+ blueprintYAML := "description: Test Agent\ncontent: |\n # Hello\n"
187
+ _ = os.WriteFile(filepath.Join(agentsDir, "test-agent.yaml"), []byte(blueprintYAML), 0644)
188
+
189
+ kitFS := os.DirFS(kitDir)
190
+ kitConfig := getMockKitConfig()
191
+ projectRoot := filepath.Join(tmpDir, "project")
192
+
193
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "agents/test-agent.yaml", "kimi-code", installer.Options{})
194
+ if err != nil {
195
+ t.Fatalf("processBlueprint failed: %v", err)
196
+ }
197
+
198
+ // Should NOT exist
199
+ expectedPath := filepath.Join(projectRoot, ".kimi/agents/test-agent.md")
200
+ if _, err := os.Stat(expectedPath); err == nil {
201
+ t.Errorf("expected file %s to NOT exist for kimi-code", expectedPath)
202
+ }
203
+ }
204
+
205
+ func TestKimiCommandToSkill(t *testing.T) {
206
+ runTranslatorTest(t, translatorTestParams{
207
+ blueprintPath: "commands/archive.yaml",
208
+ blueprintYAML: "description: Test Command\ncontent: |\n # Command Content\n",
209
+ targetTool: "kimi-code",
210
+ expectedPath: ".kimi/skills/spf-archive/SKILL.md",
211
+ checkContent: func(t *testing.T, content string) {
212
+ if !strings.Contains(content, "description: Test Command") {
213
+ t.Error("Command-to-Skill transformation missing header")
214
+ }
215
+ },
216
+ })
217
+ }
218
+
219
+ func TestAdaptArtifacts_Success(t *testing.T) {
220
+ runTranslatorTest(t, translatorTestParams{
221
+ blueprintPath: "agents/test-agent.yaml",
222
+ blueprintYAML: "description: Test Agent\ncontent: |\n # Hello\n",
223
+ targetTool: "claude",
224
+ expectedPath: ".claude/agents/test-agent.md",
225
+ checkContent: func(t *testing.T, content string) {
226
+ if !strings.HasPrefix(content, "---") {
227
+ t.Errorf("expected YAML frontmatter header, got: %q", content)
228
+ }
229
+ if !strings.Contains(content, "name: test-agent") {
230
+ t.Error("header missing name")
231
+ }
232
+ },
233
+ })
234
+ }
235
+
236
+ func TestUnmappedAgent(t *testing.T) {
237
+ tmpDir, err := os.MkdirTemp("", "specforce-test-unmapped-*")
238
+ if err != nil {
239
+ t.Fatalf("failed to create temp dir: %v", err)
240
+ }
241
+ defer func() { _ = os.RemoveAll(tmpDir) }()
242
+
243
+ kitDir := filepath.Join(tmpDir, "kit")
244
+ agentsDir := filepath.Join(kitDir, "agents")
245
+ _ = os.MkdirAll(agentsDir, 0755)
246
+
247
+ blueprintYAML := "description: Test Agent\ncontent: |\n # Hello\n"
248
+ _ = os.WriteFile(filepath.Join(agentsDir, "test-agent.yaml"), []byte(blueprintYAML), 0644)
249
+
250
+ kitFS := os.DirFS(kitDir)
251
+ kitConfig := getMockKitConfig()
252
+ projectRoot := filepath.Join(tmpDir, "project")
253
+
254
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "agents/test-agent.yaml", "unknown-agent", installer.Options{})
255
+ if !errors.Is(err, core.ErrToolMappingNotFound) {
256
+ t.Errorf("expected ErrToolMappingNotFound, got %v", err)
257
+ }
258
+ }
259
+
260
+ func TestLegacyMappingIgnored(t *testing.T) {
261
+ tmpDir, err := os.MkdirTemp("", "specforce-test-legacy-*")
262
+ if err != nil {
263
+ t.Fatalf("failed to create temp dir: %v", err)
264
+ }
265
+ defer func() { _ = os.RemoveAll(tmpDir) }()
266
+
267
+ kitDir := filepath.Join(tmpDir, "kit")
268
+ agentsDir := filepath.Join(kitDir, "agents")
269
+ _ = os.MkdirAll(agentsDir, 0755)
270
+
271
+ // Write a legacy mapping.yaml with completely different settings
272
+ legacyMapping := "claude:\n path: .legacy/path\n ext: .legacy\n"
273
+ _ = os.WriteFile(filepath.Join(agentsDir, "mapping.yaml"), []byte(legacyMapping), 0644)
274
+
275
+ blueprintYAML := "description: Test Agent\ncontent: |\n # Hello\n"
276
+ _ = os.WriteFile(filepath.Join(agentsDir, "test-agent.yaml"), []byte(blueprintYAML), 0644)
277
+
278
+ kitFS := os.DirFS(kitDir)
279
+ kitConfig := getMockKitConfig()
280
+ projectRoot := filepath.Join(tmpDir, "project")
281
+
282
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "agents/test-agent.yaml", "claude", installer.Options{})
283
+ if err != nil {
284
+ t.Fatalf("processBlueprint failed: %v", err)
285
+ }
286
+
287
+ // Should ignore legacy mapping and use kitConfig
288
+ expectedPath := filepath.Join(projectRoot, ".claude/agents/test-agent.md")
289
+ if _, err := os.Stat(expectedPath); os.IsNotExist(err) {
290
+ t.Errorf("expected file %s to exist (legacy mapping was not ignored)", expectedPath)
291
+ }
292
+ }
293
+
294
+ func TestMappingRegistry_Subdirectories(t *testing.T) {
295
+ tmpDir, err := os.MkdirTemp("", "specforce-test-mapping-sub-*")
296
+ if err != nil {
297
+ t.Fatalf("failed to create temp dir: %v", err)
298
+ }
299
+ defer func() { _ = os.RemoveAll(tmpDir) }()
300
+
301
+ kitDir := filepath.Join(tmpDir, "kit")
302
+ agentsDir := filepath.Join(kitDir, "agents")
303
+ subDir := filepath.Join(agentsDir, "special")
304
+ _ = os.MkdirAll(subDir, 0755)
305
+
306
+ blueprintYAML := "description: Test Agent\ncontent: |\n # Hello\n"
307
+ _ = os.WriteFile(filepath.Join(subDir, "sub-agent.yaml"), []byte(blueprintYAML), 0644)
308
+
309
+ kitFS := os.DirFS(kitDir)
310
+ kitConfig := getMockKitConfig()
311
+ projectRoot := filepath.Join(tmpDir, "project-rel")
312
+
313
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "agents/special/sub-agent.yaml", "claude", installer.Options{})
314
+ if err != nil {
315
+ t.Fatalf("processBlueprint failed: %v", err)
316
+ }
317
+
318
+ // Expected: .claude/agents/special/sub-agent.md
319
+ expectedPath := filepath.Join(projectRoot, ".claude/agents/special/sub-agent.md")
320
+ if _, err := os.Stat(expectedPath); os.IsNotExist(err) {
321
+ t.Errorf("expected file %s to exist", expectedPath)
322
+ }
323
+ }
324
+
325
+ func TestMappingGemini(t *testing.T) {
326
+ runTranslatorTest(t, translatorTestParams{
327
+ blueprintPath: "agents/test-agent.yaml",
328
+ blueprintYAML: "description: Test Agent\ncontent: |\n # Hello\n",
329
+ targetTool: "gemini-cli",
330
+ expectedPath: ".gemini/agents/test-agent.toml",
331
+ checkContent: func(t *testing.T, content string) {
332
+ if !strings.Contains(content, `description = "Test Agent"`) {
333
+ t.Error("missing description in TOML")
334
+ }
335
+ },
336
+ })
337
+ }
338
+
339
+ type translatorTestParams struct {
340
+ blueprintPath string
341
+ blueprintYAML string
342
+ targetTool string
343
+ expectedPath string
344
+ checkContent func(t *testing.T, content string)
345
+ }
346
+
347
+ func runTranslatorTest(t *testing.T, params translatorTestParams) {
348
+ tmpDir, err := os.MkdirTemp("", "specforce-test-translator-*")
349
+ if err != nil {
350
+ t.Fatalf("failed to create temp dir: %v", err)
351
+ }
352
+ defer func() { _ = os.RemoveAll(tmpDir) }()
353
+
354
+ kitDir := filepath.Join(tmpDir, "kit")
355
+ blueprintFile := filepath.Join(kitDir, params.blueprintPath)
356
+ _ = os.MkdirAll(filepath.Dir(blueprintFile), 0755)
357
+ _ = os.WriteFile(blueprintFile, []byte(params.blueprintYAML), 0644)
358
+
359
+ kitFS := os.DirFS(kitDir)
360
+ kitConfig := getMockKitConfig()
361
+ projectRoot := filepath.Join(tmpDir, "project")
362
+
363
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, params.blueprintPath, params.targetTool, installer.Options{})
364
+ if err != nil {
365
+ t.Fatalf("processBlueprint failed: %v", err)
366
+ }
367
+
368
+ fullExpectedPath := filepath.Join(projectRoot, params.expectedPath)
369
+ if _, err := os.Stat(fullExpectedPath); os.IsNotExist(err) {
370
+ t.Errorf("expected file %s to exist", fullExpectedPath)
371
+ }
372
+
373
+ if params.checkContent != nil {
374
+ data, _ := os.ReadFile(fullExpectedPath)
375
+ params.checkContent(t, string(data))
376
+ }
377
+ }
378
+
379
+ func TestMappingOverrides(t *testing.T) {
380
+ tmpDir, err := os.MkdirTemp("", "specforce-test-overrides-*")
381
+ if err != nil {
382
+ t.Fatalf("failed to create temp dir: %v", err)
383
+ }
384
+ defer func() { _ = os.RemoveAll(tmpDir) }()
385
+
386
+ kitDir := filepath.Join(tmpDir, "kit")
387
+ agentsDir := filepath.Join(kitDir, "agents")
388
+ if err := os.MkdirAll(agentsDir, 0755); err != nil {
389
+ t.Fatalf("failed to create agents dir: %v", err)
390
+ }
391
+
392
+ // Blueprint with explicit override
393
+ blueprintYAML := "description: Override Agent\nmapping:\n claude:\n path: custom/path\n name: overridden-name\ncontent: |\n # Hello\n"
394
+ if err := os.WriteFile(filepath.Join(agentsDir, "override-agent.yaml"), []byte(blueprintYAML), 0644); err != nil {
395
+ t.Fatalf("failed to write blueprint: %v", err)
396
+ }
397
+
398
+ kitFS := os.DirFS(kitDir)
399
+ kitConfig := getMockKitConfig()
400
+ projectRoot := filepath.Join(tmpDir, "project")
401
+
402
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "agents/override-agent.yaml", "claude", installer.Options{})
403
+ if err != nil {
404
+ t.Fatalf("processBlueprint failed: %v", err)
405
+ }
406
+
407
+ // Overrides should be relative to the target directory of the tool
408
+ // Expected: .claude/custom/path/overridden-name.md
409
+ expectedPath := filepath.Join(projectRoot, ".claude/custom/path/overridden-name.md")
410
+ if _, err := os.Stat(expectedPath); os.IsNotExist(err) {
411
+ t.Errorf("expected file %s to exist", expectedPath)
412
+ }
413
+ }
414
+
415
+ func TestSkillHeader(t *testing.T) {
416
+ tmpDir, err := os.MkdirTemp("", "specforce-test-skills-*")
417
+ if err != nil {
418
+ t.Fatalf("failed to create temp dir: %v", err)
419
+ }
420
+ defer func() { _ = os.RemoveAll(tmpDir) }()
421
+
422
+ kitDir := filepath.Join(tmpDir, "kit")
423
+ skillsDir := filepath.Join(kitDir, "skills/test-skill")
424
+ if err := os.MkdirAll(skillsDir, 0755); err != nil {
425
+ t.Fatalf("failed to create skills dir: %v", err)
426
+ }
427
+
428
+ skillYAML := "name: test-skill\ndescription: Test Skill Description\nversion: \"2.1\"\npriority: HIGH\ncontent: |\n # Skill Content\n"
429
+ skillYAMLPath := filepath.Join(skillsDir, "SKILL.yaml")
430
+ if err := os.WriteFile(skillYAMLPath, []byte(skillYAML), 0644); err != nil {
431
+ t.Fatalf("failed to write skill: %v", err)
432
+ }
433
+
434
+ kitFS := os.DirFS(kitDir)
435
+ kitConfig := getMockKitConfig()
436
+ projectRoot := filepath.Join(tmpDir, "project")
437
+
438
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "skills/test-skill/SKILL.yaml", "claude", installer.Options{})
439
+ if err != nil {
440
+ t.Fatalf("processBlueprint failed for SKILL.yaml: %v", err)
441
+ }
442
+
443
+ skillMD := filepath.Join(projectRoot, ".claude/skills/test-skill/SKILL.md")
444
+ data, err := os.ReadFile(skillMD)
445
+ if err != nil {
446
+ t.Fatalf("failed to read expected skill file %s: %v", skillMD, err)
447
+ }
448
+ content := string(data)
449
+ if !strings.Contains(content, "name: test-skill") {
450
+ t.Errorf("SKILL.md header missing name from metadata. Content: %q", content)
451
+ }
452
+ if !strings.Contains(content, "version: 2.1") || !strings.Contains(content, "priority: HIGH") {
453
+ t.Errorf("SKILL.md missing version or priority. Content: %q", content)
454
+ }
455
+ }
456
+
457
+ func TestCommandHeader(t *testing.T) {
458
+ tmpDir, err := os.MkdirTemp("", "specforce-test-commands-*")
459
+ if err != nil {
460
+ t.Fatalf("failed to create temp dir: %v", err)
461
+ }
462
+ defer func() { _ = os.RemoveAll(tmpDir) }()
463
+
464
+ kitDir := filepath.Join(tmpDir, "kit")
465
+ commandsDir := filepath.Join(kitDir, "commands")
466
+ if err := os.MkdirAll(commandsDir, 0755); err != nil {
467
+ t.Fatalf("failed to create commands dir: %v", err)
468
+ }
469
+
470
+ commandYAML := "description: Test Command Description\ncontent: |\n # Command Content\n"
471
+ if err := os.WriteFile(filepath.Join(commandsDir, "test-cmd.yaml"), []byte(commandYAML), 0644); err != nil {
472
+ t.Fatalf("failed to write command: %v", err)
473
+ }
474
+
475
+ kitFS := os.DirFS(kitDir)
476
+ kitConfig := getMockKitConfig()
477
+ projectRoot := filepath.Join(tmpDir, "project")
478
+
479
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "commands/test-cmd.yaml", "claude", installer.Options{})
480
+ if err != nil {
481
+ t.Fatalf("processBlueprint failed: %v", err)
482
+ }
483
+
484
+ cmdMD := filepath.Join(projectRoot, ".claude/commands/spf/test-cmd.md")
485
+ data, _ := os.ReadFile(cmdMD)
486
+ content := string(data)
487
+ if !strings.HasPrefix(content, "---") || !strings.Contains(content, "description: Test Command Description") {
488
+ t.Errorf("Command missing description in header. Content: %q", content)
489
+ }
490
+ }
491
+
492
+ func TestStandardizedNaming(t *testing.T) {
493
+ tmpDir, err := os.MkdirTemp("", "specforce-test-naming-*")
494
+ if err != nil {
495
+ t.Fatalf("failed to create temp dir: %v", err)
496
+ }
497
+ defer func() { _ = os.RemoveAll(tmpDir) }()
498
+
499
+ kitDir := filepath.Join(tmpDir, "kit")
500
+ commandsDir := filepath.Join(kitDir, "commands")
501
+ _ = os.MkdirAll(commandsDir, 0755)
502
+
503
+ blueprintYAML := "description: Test Command\ncontent: |\n # Hello\n"
504
+ _ = os.WriteFile(filepath.Join(commandsDir, "archive.yaml"), []byte(blueprintYAML), 0644)
505
+
506
+ kitFS := os.DirFS(kitDir)
507
+ kitConfig := &core.KitConfig{
508
+ Tools: map[string]core.ToolRoute{
509
+ "codex": {
510
+ Target: ".codex/",
511
+ Mappings: map[string]core.MappingConfig{
512
+ "commands": {Path: "commands/spf", Name: "spf-*", Ext: ".md"},
513
+ },
514
+ },
515
+ },
516
+ }
517
+ projectRoot := filepath.Join(tmpDir, "project")
518
+
519
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfig, "commands/archive.yaml", "codex", installer.Options{})
520
+ if err != nil {
521
+ t.Fatalf("processBlueprint failed: %v", err)
522
+ }
523
+
524
+ expectedPath := filepath.Join(projectRoot, ".codex/commands/spf/spf-archive.md")
525
+ if _, err := os.Stat(expectedPath); os.IsNotExist(err) {
526
+ t.Errorf("expected file %s to exist", expectedPath)
527
+ }
528
+
529
+ // Test case 3: Absolute path for global-enabled agent
530
+ globalTmp, _ := os.MkdirTemp("", "specforce-global-*")
531
+ defer func() { _ = os.RemoveAll(globalTmp) }()
532
+
533
+ kitConfigGlobal := &core.KitConfig{
534
+ Tools: map[string]core.ToolRoute{
535
+ "codex": {
536
+ Target: globalTmp,
537
+ Mappings: map[string]core.MappingConfig{
538
+ "commands": {Path: "spf", Name: "spf-*", Ext: ".md"},
539
+ },
540
+ },
541
+ },
542
+ }
543
+
544
+ err = processBlueprint(context.Background(), projectRoot, kitFS, kitConfigGlobal, "commands/archive.yaml", "codex", installer.Options{})
545
+ if err != nil {
546
+ t.Fatalf("processBlueprint failed for global absolute path: %v", err)
547
+ }
548
+
549
+ expectedGlobalPath := filepath.Join(globalTmp, "spf/spf-archive.md")
550
+ if _, err := os.Stat(expectedGlobalPath); os.IsNotExist(err) {
551
+ t.Errorf("expected file %s to exist in global path", expectedGlobalPath)
552
+ }
553
+ }
554
+
555
+
556
+
557
+
558
+ func TestResolveMapping_TargetOverride(t *testing.T) {
559
+ tmpDir, err := os.MkdirTemp("", "specforce-test-target-override-*")
560
+ if err != nil {
561
+ t.Fatalf("failed to create temp dir: %v", err)
562
+ }
563
+ defer func() { _ = os.RemoveAll(tmpDir) }()
564
+
565
+ globalDir := filepath.Join(tmpDir, "global")
566
+ _ = os.MkdirAll(globalDir, 0755)
567
+
568
+ kitConfig := &core.KitConfig{
569
+ Tools: map[string]core.ToolRoute{
570
+ "test-agent": {
571
+ Target: ".local/",
572
+ Mappings: map[string]core.MappingConfig{
573
+ "commands": {
574
+ Target: globalDir,
575
+ Path: "global-cmds",
576
+ Ext: ".md",
577
+ },
578
+ "skills": {
579
+ Path: "local-skills",
580
+ Ext: ".md",
581
+ },
582
+ },
583
+ },
584
+ },
585
+ }
586
+
587
+ bp := &core.Blueprint{ID: "test"}
588
+
589
+ // Test case 1: Command uses override target
590
+ mapping, err := resolveMapping(kitConfig, "commands/test.yaml", bp, "test-agent")
591
+ if err != nil {
592
+ t.Fatalf("resolveMapping failed: %v", err)
593
+ }
594
+ expectedPath := filepath.Clean(filepath.Join(globalDir, "global-cmds"))
595
+ if mapping.Path != expectedPath {
596
+ t.Errorf("expected path %s, got %s", expectedPath, mapping.Path)
597
+ }
598
+
599
+ // Test case 2: Skill uses default tool target
600
+ mapping, err = resolveMapping(kitConfig, "skills/test.yaml", bp, "test-agent")
601
+ if err != nil {
602
+ t.Fatalf("resolveMapping failed: %v", err)
603
+ }
604
+ expectedPath = filepath.Clean(filepath.Join(".local/", "local-skills"))
605
+ if mapping.Path != expectedPath {
606
+ t.Errorf("expected path %s, got %s", expectedPath, mapping.Path)
607
+ }
608
+ }
609
+
610
+ func TestResolveMapping_TildeExpansionFailure(t *testing.T) {
611
+ kitConfig := &core.KitConfig{
612
+ Tools: map[string]core.ToolRoute{
613
+ "test-agent": {
614
+ Target: "~/hidden-path",
615
+ Mappings: map[string]core.MappingConfig{
616
+ "commands": {Path: "cmds", Ext: ".md"},
617
+ },
618
+ },
619
+ },
620
+ }
621
+
622
+ oldHome := os.Getenv("HOME")
623
+ _ = os.Unsetenv("HOME")
624
+ _ = os.Unsetenv("USERPROFILE") // For windows compatibility in tests if ever run there
625
+ defer func() { _ = os.Setenv("HOME", oldHome) }()
626
+
627
+ bp := &core.Blueprint{ID: "test"}
628
+ _, err := resolveMapping(kitConfig, "commands/test.yaml", bp, "test-agent")
629
+ if err == nil {
630
+ t.Fatal("expected error for failed tilde expansion, got nil")
631
+ }
632
+ if !strings.Contains(err.Error(), "failed to resolve home directory") {
633
+ t.Errorf("expected home directory resolution error, got: %v", err)
634
+ }
635
+ }
636
+
637
+ func TestCodexExpansionHierarchy(t *testing.T) {
638
+ kitConfig := &core.KitConfig{
639
+ Tools: map[string]core.ToolRoute{
640
+ "codex": {
641
+ Mappings: map[string]core.MappingConfig{
642
+ "commands": {
643
+ Target: "${CODEX_PROMPTS_DIR:-${CODEX_HOME:-~/.codex}/prompts}",
644
+ Path: ".",
645
+ Ext: ".md",
646
+ },
647
+ },
648
+ },
649
+ },
650
+ }
651
+ bp := &core.Blueprint{ID: "test"}
652
+
653
+ // Cleanup env after test
654
+ defer func() {
655
+ _ = os.Unsetenv("CODEX_PROMPTS_DIR")
656
+ _ = os.Unsetenv("CODEX_HOME")
657
+ }()
658
+
659
+ // Case 1: CODEX_PROMPTS_DIR
660
+ _ = os.Setenv("CODEX_PROMPTS_DIR", "/path/to/prompts")
661
+ mapping, err := resolveMapping(kitConfig, "commands/test.yaml", bp, "codex")
662
+ if err != nil {
663
+ t.Fatalf("resolveMapping failed: %v", err)
664
+ }
665
+ if mapping.Path != "/path/to/prompts" {
666
+ t.Errorf("Priority 1 failed: expected /path/to/prompts, got %s", mapping.Path)
667
+ }
668
+
669
+ // Case 2: CODEX_HOME
670
+ _ = os.Unsetenv("CODEX_PROMPTS_DIR")
671
+ _ = os.Setenv("CODEX_HOME", "/home/user/.codex")
672
+ mapping, err = resolveMapping(kitConfig, "commands/test.yaml", bp, "codex")
673
+ if err != nil {
674
+ t.Fatalf("resolveMapping failed: %v", err)
675
+ }
676
+ if mapping.Path != "/home/user/.codex/prompts" {
677
+ t.Errorf("Priority 2 failed: expected /home/user/.codex/prompts, got %s", mapping.Path)
678
+ }
679
+
680
+ // Case 3: Default ~/.codex/prompts
681
+ _ = os.Unsetenv("CODEX_HOME")
682
+ home, _ := os.UserHomeDir()
683
+ mapping, err = resolveMapping(kitConfig, "commands/test.yaml", bp, "codex")
684
+ if err != nil {
685
+ t.Fatalf("resolveMapping failed: %v", err)
686
+ }
687
+ expected := filepath.Clean(filepath.Join(home, ".codex/prompts"))
688
+ if mapping.Path != expected {
689
+ t.Errorf("Priority 3 failed: expected %s, got %s", expected, mapping.Path)
690
+ }
691
+ }
692
+
693
+ func TestCodexGlobalLocalIsolation(t *testing.T) {
694
+ globalDir := "/tmp/global-codex"
695
+
696
+ kitConfig := &core.KitConfig{
697
+ Tools: map[string]core.ToolRoute{
698
+ "codex": {
699
+ Target: ".codex/", // Local target
700
+ Mappings: map[string]core.MappingConfig{
701
+ "commands": {
702
+ Target: globalDir, // Global override
703
+ Path: ".",
704
+ Ext: ".md",
705
+ },
706
+ "skills": {
707
+ Path: "skills",
708
+ Ext: ".md",
709
+ },
710
+ },
711
+ },
712
+ },
713
+ }
714
+ bp := &core.Blueprint{ID: "test"}
715
+
716
+ // 1. Verify Command is Global (Absolute)
717
+ mapping, err := resolveMapping(kitConfig, "commands/test.yaml", bp, "codex")
718
+ if err != nil {
719
+ t.Fatalf("resolveMapping failed: %v", err)
720
+ }
721
+ if mapping.Path != globalDir {
722
+ t.Errorf("expected global path %s, got %s", globalDir, mapping.Path)
723
+ }
724
+
725
+ // 2. Verify Skill is Local (Relative)
726
+ mapping, err = resolveMapping(kitConfig, "skills/test.yaml", bp, "codex")
727
+ if err != nil {
728
+ t.Fatalf("resolveMapping failed: %v", err)
729
+ }
730
+ expectedLocal := filepath.Clean(filepath.Join(".codex/", "skills"))
731
+ if mapping.Path != expectedLocal {
732
+ t.Errorf("expected local path %s, got %s", expectedLocal, mapping.Path)
733
+ }
734
+ }