@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,145 @@
1
+ package core
2
+
3
+ import (
4
+ "os"
5
+ "path/filepath"
6
+ "testing"
7
+ )
8
+
9
+ func TestEnsureConfigExists(t *testing.T) {
10
+ tmpDir := t.TempDir()
11
+
12
+ t.Run("creates new config", func(t *testing.T) {
13
+ err := EnsureConfigExists(tmpDir)
14
+ if err != nil {
15
+ t.Fatalf("expected no error, got %v", err)
16
+ }
17
+
18
+ configPath := filepath.Join(tmpDir, ".specforce", "config.yaml")
19
+ if _, err := os.Stat(configPath); os.IsNotExist(err) {
20
+ t.Fatal("expected config file to be created")
21
+ }
22
+
23
+ data, err := os.ReadFile(configPath)
24
+ if err != nil {
25
+ t.Fatal(err)
26
+ }
27
+ if string(data) != DefaultConfigContent {
28
+ t.Errorf("expected default config content, got %s", string(data))
29
+ }
30
+ })
31
+
32
+ t.Run("does not overwrite existing config", func(t *testing.T) {
33
+ configPath := filepath.Join(tmpDir, ".specforce", "config.yaml")
34
+ existingContent := "instructions: {}"
35
+ if err := os.WriteFile(configPath, []byte(existingContent), 0644); err != nil {
36
+ t.Fatal(err)
37
+ }
38
+
39
+ err := EnsureConfigExists(tmpDir)
40
+ if err != nil {
41
+ t.Fatalf("expected no error, got %v", err)
42
+ }
43
+
44
+ data, err := os.ReadFile(configPath)
45
+ if err != nil {
46
+ t.Fatal(err)
47
+ }
48
+ if string(data) != existingContent {
49
+ t.Errorf("expected existing config content to be preserved, got %s", string(data))
50
+ }
51
+ })
52
+
53
+ t.Run("returns error on security failure", func(t *testing.T) {
54
+ err := EnsureConfigExists("/nonexistent/root")
55
+ if err == nil {
56
+ t.Fatal("expected error for nonexistent root")
57
+ }
58
+ })
59
+ }
60
+
61
+ func TestLoadConfig_Success(t *testing.T) {
62
+ tmpDir := t.TempDir()
63
+ specforceDir := filepath.Join(tmpDir, ".specforce")
64
+ if err := os.MkdirAll(specforceDir, 0755); err != nil {
65
+ t.Fatal(err)
66
+ }
67
+
68
+ t.Run("load hooks from config", func(t *testing.T) {
69
+ configContent := `
70
+ hooks:
71
+ on_task_finished:
72
+ - "echo task"
73
+ on_phase_finished:
74
+ - "echo phase"
75
+ on_all_tasks_finished:
76
+ - "echo all"
77
+ `
78
+ configPath := filepath.Join(specforceDir, "config.yaml")
79
+ if err := os.WriteFile(configPath, []byte(configContent), 0644); err != nil {
80
+ t.Fatal(err)
81
+ }
82
+
83
+ config := LoadConfig(tmpDir)
84
+ if len(config.Hooks.OnTaskFinished) == 0 || config.Hooks.OnTaskFinished[0] != "echo task" {
85
+ t.Errorf("expected 'echo task', got %v", config.Hooks.OnTaskFinished)
86
+ }
87
+ if len(config.Hooks.OnPhaseFinished) == 0 || config.Hooks.OnPhaseFinished[0] != "echo phase" {
88
+ t.Errorf("expected 'echo phase', got %v", config.Hooks.OnPhaseFinished)
89
+ }
90
+ if len(config.Hooks.OnAllTasksFinished) == 0 || config.Hooks.OnAllTasksFinished[0] != "echo all" {
91
+ t.Errorf("expected 'echo all', got %v", config.Hooks.OnAllTasksFinished)
92
+ }
93
+ })
94
+
95
+ t.Run("load instructions from config", func(t *testing.T) {
96
+ configContent := `
97
+ instructions:
98
+ requirements:
99
+ - "Instruction 1"
100
+ `
101
+ configPath := filepath.Join(specforceDir, "config.yaml")
102
+ if err := os.WriteFile(configPath, []byte(configContent), 0644); err != nil {
103
+ t.Fatal(err)
104
+ }
105
+
106
+ config := LoadConfig(tmpDir)
107
+ if len(config.Instructions["requirements"]) == 0 || config.Instructions["requirements"][0] != "Instruction 1" {
108
+ t.Errorf("expected 'Instruction 1', got %v", config.Instructions["requirements"])
109
+ }
110
+ })
111
+ }
112
+
113
+ func TestLoadConfig_Errors(t *testing.T) {
114
+ tmpDir := t.TempDir()
115
+ specforceDir := filepath.Join(tmpDir, ".specforce")
116
+ if err := os.MkdirAll(specforceDir, 0755); err != nil {
117
+ t.Fatal(err)
118
+ }
119
+
120
+ t.Run("returns empty config if file missing", func(t *testing.T) {
121
+ emptyDir := t.TempDir()
122
+ config := LoadConfig(emptyDir)
123
+ if config == nil {
124
+ t.Fatal("expected non-nil config")
125
+ }
126
+ if len(config.Instructions) != 0 {
127
+ t.Errorf("expected empty instructions, got %v", config.Instructions)
128
+ }
129
+ })
130
+
131
+ t.Run("returns empty config if malformed", func(t *testing.T) {
132
+ configPath := filepath.Join(specforceDir, "config.yaml")
133
+ if err := os.WriteFile(configPath, []byte("invalid: yaml: :"), 0644); err != nil {
134
+ t.Fatal(err)
135
+ }
136
+
137
+ config := LoadConfig(tmpDir)
138
+ if config == nil {
139
+ t.Fatal("expected non-nil config")
140
+ }
141
+ if len(config.Instructions) != 0 {
142
+ t.Errorf("expected empty instructions, got %v", config.Instructions)
143
+ }
144
+ })
145
+ }
@@ -0,0 +1,13 @@
1
+ package core
2
+
3
+ // Tool directory prefixes that are considered "agent tools" and can be updated independently of the project constitution.
4
+ var ToolPrefixes = []string{
5
+ ".gemini/",
6
+ ".claude/",
7
+ ".opencode/",
8
+ ".kilocode/",
9
+ ".agent/",
10
+ ".qwen/",
11
+ ".codex/",
12
+ ".kimi/",
13
+ }
@@ -0,0 +1,31 @@
1
+ package core
2
+
3
+ import "errors"
4
+
5
+ // Domain sentinel errors for Specforce subsystems.
6
+ // Use errors.Is to identify these through error chains.
7
+ var (
8
+ // ErrProjectAlreadyInitialized is returned when init is called on an existing project.
9
+ ErrProjectAlreadyInitialized = errors.New("project already initialized")
10
+
11
+ // ErrAgentNotFound is returned when the agent registry cannot locate a requested agent.
12
+ ErrAgentNotFound = errors.New("agent not found")
13
+
14
+ // ErrInvalidSpecFile is returned when a spec markdown file fails parsing or has an invalid format.
15
+ ErrInvalidSpecFile = errors.New("invalid spec file")
16
+
17
+ // ErrInstallerPermissionDenied is returned when file system permissions are insufficient for installation.
18
+ ErrInstallerPermissionDenied = errors.New("installer permission denied")
19
+
20
+ // ErrMissingKitConfig is returned when the kit.yaml configuration file is missing.
21
+ ErrMissingKitConfig = errors.New("kit.yaml configuration is missing")
22
+
23
+ // ErrToolMappingNotFound is returned when a tool mapping is not found in kit.yaml.
24
+ ErrToolMappingNotFound = errors.New("tool mapping not found in kit.yaml")
25
+
26
+ // ErrSpecAlreadyActive is returned when a spec slug is already in use in the active specs directory.
27
+ ErrSpecAlreadyActive = errors.New("feature specification is already active")
28
+
29
+ // ErrSpecAlreadyArchived is returned when a spec slug is already in use in the archive directory.
30
+ ErrSpecAlreadyArchived = errors.New("feature specification already exists in the archive")
31
+ )
@@ -0,0 +1,48 @@
1
+ package core_test
2
+
3
+ import (
4
+ "errors"
5
+ "fmt"
6
+ "testing"
7
+
8
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
9
+ )
10
+
11
+ func TestDomainErrors_Is(t *testing.T) {
12
+ t.Run("ErrProjectAlreadyInitialized wraps correctly", func(t *testing.T) {
13
+ wrapped := fmt.Errorf("init failed: %w", core.ErrProjectAlreadyInitialized)
14
+ if !errors.Is(wrapped, core.ErrProjectAlreadyInitialized) {
15
+ t.Errorf("expected errors.Is to identify ErrProjectAlreadyInitialized through wrapping")
16
+ }
17
+ })
18
+
19
+ t.Run("ErrAgentNotFound wraps correctly", func(t *testing.T) {
20
+ wrapped := fmt.Errorf("registry lookup: %w", core.ErrAgentNotFound)
21
+ if !errors.Is(wrapped, core.ErrAgentNotFound) {
22
+ t.Errorf("expected errors.Is to identify ErrAgentNotFound through wrapping")
23
+ }
24
+ })
25
+
26
+ t.Run("ErrInvalidSpecFile wraps correctly", func(t *testing.T) {
27
+ wrapped := fmt.Errorf("scanner: %w", core.ErrInvalidSpecFile)
28
+ if !errors.Is(wrapped, core.ErrInvalidSpecFile) {
29
+ t.Errorf("expected errors.Is to identify ErrInvalidSpecFile through wrapping")
30
+ }
31
+ })
32
+
33
+ t.Run("ErrInstallerPermissionDenied wraps correctly", func(t *testing.T) {
34
+ wrapped := fmt.Errorf("install: %w", core.ErrInstallerPermissionDenied)
35
+ if !errors.Is(wrapped, core.ErrInstallerPermissionDenied) {
36
+ t.Errorf("expected errors.Is to identify ErrInstallerPermissionDenied through wrapping")
37
+ }
38
+ })
39
+
40
+ t.Run("domain errors do not match each other", func(t *testing.T) {
41
+ if errors.Is(core.ErrAgentNotFound, core.ErrProjectAlreadyInitialized) {
42
+ t.Errorf("distinct domain errors should not match each other")
43
+ }
44
+ if errors.Is(core.ErrInvalidSpecFile, core.ErrInstallerPermissionDenied) {
45
+ t.Errorf("distinct domain errors should not match each other")
46
+ }
47
+ })
48
+ }
@@ -0,0 +1,89 @@
1
+ package core
2
+
3
+ import (
4
+ "bytes"
5
+ "context"
6
+ "os/exec"
7
+ "strings"
8
+ "sync"
9
+ )
10
+
11
+ // HookResult contains the result of an external command execution.
12
+ type HookResult struct {
13
+ Command string
14
+ Stdout string
15
+ Stderr string
16
+ ExitCode int
17
+ Success bool
18
+ }
19
+
20
+ // HookError is returned when one or more hooks fail.
21
+ type HookError struct {
22
+ Results []HookResult
23
+ }
24
+
25
+ func (e *HookError) Error() string {
26
+ return "one or more hooks failed"
27
+ }
28
+
29
+ // ExecuteHooks runs multiple commands in parallel and returns their results.
30
+ // It returns a *HookError if any of the commands fail (non-zero exit code).
31
+ func ExecuteHooks(ctx context.Context, commands []string) ([]HookResult, error) {
32
+ if len(commands) == 0 {
33
+ return nil, nil
34
+ }
35
+
36
+ results := make([]HookResult, len(commands))
37
+ var wg sync.WaitGroup
38
+ var mu sync.Mutex
39
+ var hasFailure bool
40
+
41
+ for i, cmdStr := range commands {
42
+ wg.Add(1)
43
+ go func(i int, cmdStr string) {
44
+ defer wg.Done()
45
+
46
+ parts := strings.Fields(cmdStr)
47
+ if len(parts) == 0 {
48
+ return
49
+ }
50
+
51
+ var stdout, stderr bytes.Buffer
52
+ // #nosec G204 - User-defined hooks require variable command execution
53
+ cmd := exec.CommandContext(ctx, parts[0], parts[1:]...)
54
+ cmd.Stdout = &stdout
55
+ cmd.Stderr = &stderr
56
+
57
+ err := cmd.Run()
58
+
59
+ res := HookResult{
60
+ Command: cmdStr,
61
+ Stdout: stdout.String(),
62
+ Stderr: stderr.String(),
63
+ Success: true,
64
+ }
65
+
66
+ if err != nil {
67
+ res.Success = false
68
+ if exitErr, ok := err.(*exec.ExitError); ok {
69
+ res.ExitCode = exitErr.ExitCode()
70
+ } else {
71
+ res.ExitCode = -1
72
+ }
73
+ mu.Lock()
74
+ hasFailure = true
75
+ mu.Unlock()
76
+ }
77
+
78
+ results[i] = res
79
+ }(i, cmdStr)
80
+ }
81
+
82
+ wg.Wait()
83
+
84
+ if hasFailure {
85
+ return results, &HookError{Results: results}
86
+ }
87
+
88
+ return results, nil
89
+ }
@@ -0,0 +1,51 @@
1
+ package core
2
+
3
+ import (
4
+ "context"
5
+ "testing"
6
+ )
7
+
8
+ func TestExecuteHooks(t *testing.T) {
9
+ ctx := context.Background()
10
+
11
+ tests := []struct {
12
+ name string
13
+ commands []string
14
+ wantErr bool
15
+ }{
16
+ {
17
+ name: "Simple echo",
18
+ commands: []string{"echo hello"},
19
+ wantErr: false,
20
+ },
21
+ {
22
+ name: "Command with arguments",
23
+ commands: []string{"ls -l"},
24
+ wantErr: false,
25
+ },
26
+ {
27
+ name: "Failed command",
28
+ commands: []string{"false"},
29
+ wantErr: true,
30
+ },
31
+ {
32
+ name: "Empty command string",
33
+ commands: []string{""},
34
+ wantErr: false,
35
+ },
36
+ }
37
+
38
+ for _, tt := range tests {
39
+ t.Run(tt.name, func(t *testing.T) {
40
+ _, err := ExecuteHooks(ctx, tt.commands)
41
+ if (err != nil) != tt.wantErr {
42
+ t.Errorf("ExecuteHooks() error = %v, wantErr %v", err, tt.wantErr)
43
+ }
44
+ if tt.wantErr && err != nil {
45
+ if err.Error() != "one or more hooks failed" {
46
+ t.Errorf("expected 'one or more hooks failed', got %v", err.Error())
47
+ }
48
+ }
49
+ })
50
+ }
51
+ }
@@ -0,0 +1,15 @@
1
+ package core
2
+
3
+ // ToolRoute represents the target routing path and specific directory mappings for an agent tool.
4
+ type ToolRoute struct {
5
+ Name string `yaml:"name"`
6
+ Description string `yaml:"description"`
7
+ Target string `yaml:"target"`
8
+ Mappings map[string]MappingConfig `yaml:"mappings"`
9
+ }
10
+
11
+ // KitConfig represents the root configuration structure for kit.yaml,
12
+ // defining mapping rules for all supported AI agents.
13
+ type KitConfig struct {
14
+ Tools map[string]ToolRoute `yaml:"tools"`
15
+ }
@@ -0,0 +1,65 @@
1
+ package core_test
2
+
3
+ import (
4
+ "testing"
5
+
6
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
7
+ "gopkg.in/yaml.v3"
8
+ )
9
+
10
+ func TestKitConfigUnmarshal(t *testing.T) {
11
+ yamlData := []byte(`
12
+ tools:
13
+ gemini-cli:
14
+ target: ".gemini/"
15
+ mappings:
16
+ skills:
17
+ path: "skills"
18
+ ext: ".md"
19
+ agents:
20
+ path: "prompts"
21
+ ext: ".md"
22
+ claude-code:
23
+ target: ".claude/"
24
+ mappings:
25
+ skills:
26
+ path: "instructions"
27
+ ext: ".md"
28
+ `)
29
+
30
+ var config core.KitConfig
31
+ if err := yaml.Unmarshal(yamlData, &config); err != nil {
32
+ t.Fatalf("failed to unmarshal yaml: %v", err)
33
+ }
34
+
35
+ if len(config.Tools) != 2 {
36
+ t.Fatalf("expected 2 tools, got %d", len(config.Tools))
37
+ }
38
+
39
+ gemini, ok := config.Tools["gemini-cli"]
40
+ if !ok {
41
+ t.Fatal("expected 'gemini-cli' tool")
42
+ }
43
+
44
+ if gemini.Target != ".gemini/" {
45
+ t.Errorf("expected target '.gemini/', got %q", gemini.Target)
46
+ }
47
+
48
+ if len(gemini.Mappings) != 2 {
49
+ t.Fatalf("expected 2 mappings for gemini-cli, got %d", len(gemini.Mappings))
50
+ }
51
+
52
+ skillsMap := gemini.Mappings["skills"]
53
+ if skillsMap.Path != "skills" || skillsMap.Ext != ".md" {
54
+ t.Errorf("unexpected skills mapping: %+v", skillsMap)
55
+ }
56
+
57
+ claude, ok := config.Tools["claude-code"]
58
+ if !ok {
59
+ t.Fatal("expected 'claude-code' tool")
60
+ }
61
+
62
+ if claude.Target != ".claude/" {
63
+ t.Errorf("expected target '.claude/', got %q", claude.Target)
64
+ }
65
+ }
@@ -0,0 +1,115 @@
1
+ package core
2
+
3
+ import (
4
+ "fmt"
5
+ "os"
6
+ "path/filepath"
7
+ "strings"
8
+ )
9
+
10
+ // ExpandPath expands leading ~ to user home directory and environment variables in the form ${VAR:-DEFAULT}.
11
+ func ExpandPath(path string) string {
12
+ // 1. Expand environment variables first: ${VAR:-DEFAULT}
13
+ path = expandEnv(path)
14
+
15
+ // 2. Expand tilde if it's now at the beginning
16
+ if strings.HasPrefix(path, "~") {
17
+ home, err := os.UserHomeDir()
18
+ if err == nil {
19
+ if path == "~" {
20
+ path = home
21
+ } else if len(path) > 1 && (path[1] == '/' || path[1] == filepath.Separator || path[1] == '.') {
22
+ path = filepath.Join(home, path[1:])
23
+ }
24
+ }
25
+ }
26
+
27
+ return path
28
+ }
29
+
30
+ func expandEnv(path string) string {
31
+ for {
32
+ start := strings.Index(path, "${")
33
+ if start == -1 {
34
+ break
35
+ }
36
+
37
+ // Find the matching closing brace, handling nested ${}
38
+ balance := 0
39
+ end := -1
40
+ for i := start; i < len(path); i++ {
41
+ if strings.HasPrefix(path[i:], "${") {
42
+ balance++
43
+ i++ // skip '{'
44
+ } else if path[i] == '}' {
45
+ balance--
46
+ if balance == 0 {
47
+ end = i
48
+ break
49
+ }
50
+ }
51
+ }
52
+
53
+ if end == -1 {
54
+ break // Malformed
55
+ }
56
+
57
+ content := path[start+2 : end]
58
+ replacement := ""
59
+
60
+ if idx := strings.Index(content, ":-"); idx != -1 {
61
+ varName := content[:idx]
62
+ fallback := content[idx+2:]
63
+ val := os.Getenv(varName)
64
+ if val != "" {
65
+ replacement = val
66
+ } else {
67
+ replacement = expandEnv(fallback) // Recursive fallback expansion
68
+ }
69
+ } else {
70
+ replacement = os.Getenv(content)
71
+ }
72
+
73
+ path = path[:start] + replacement + path[end+1:]
74
+ }
75
+ return path
76
+ }
77
+
78
+ // SecurePath takes a root and a target path, cleans it, and ensures it's within the root.
79
+ // In Go 1.24+, we use os.OpenRoot to validate that the path is within boundaries if the root exists.
80
+ func SecurePath(root, target string) (string, error) {
81
+ absRoot, err := filepath.Abs(root)
82
+ if err != nil {
83
+ return "", fmt.Errorf("failed to get absolute path for root %s: %w", root, err)
84
+ }
85
+
86
+ // Clean the target path first to handle relative segments
87
+ cleanTarget := filepath.Clean(target)
88
+ if filepath.IsAbs(cleanTarget) {
89
+ rel, err := filepath.Rel(absRoot, cleanTarget)
90
+ if err != nil || strings.HasPrefix(rel, "..") {
91
+ return "", fmt.Errorf("security: absolute path %s is outside root %s", target, absRoot)
92
+ }
93
+ cleanTarget = rel
94
+ }
95
+
96
+ r, err := os.OpenRoot(absRoot)
97
+ if err == nil {
98
+ defer func() { _ = r.Close() }()
99
+ // os.OpenRoot.Stat will fail if path escapes root.
100
+ _, err = r.Stat(cleanTarget)
101
+ if err != nil && !os.IsNotExist(err) {
102
+ return "", fmt.Errorf("security: path traversal attempt or invalid path: %w", err)
103
+ }
104
+ } else if !os.IsNotExist(err) {
105
+ return "", fmt.Errorf("failed to open root %s: %w", absRoot, err)
106
+ }
107
+
108
+ // Fallback/Double check: Ensure the final path still has the absRoot prefix
109
+ finalPath := filepath.Join(absRoot, cleanTarget)
110
+ if !strings.HasPrefix(finalPath, absRoot) {
111
+ return "", fmt.Errorf("security: path traversal attempt detected for %s", target)
112
+ }
113
+
114
+ return finalPath, nil
115
+ }
@@ -0,0 +1,101 @@
1
+ package core
2
+
3
+ import (
4
+ "os"
5
+ "path/filepath"
6
+ "testing"
7
+ )
8
+
9
+ func TestExpandPath_Tilde(t *testing.T) {
10
+ home, err := os.UserHomeDir()
11
+ if err != nil {
12
+ t.Fatalf("failed to get user home dir: %v", err)
13
+ }
14
+
15
+ tests := []struct {
16
+ name string
17
+ input string
18
+ expected string
19
+ }{
20
+ {"tilde expansion", "~/test", filepath.Join(home, "test")},
21
+ {"tilde dot expansion", "~/.codex", filepath.Join(home, ".codex")},
22
+ {"no tilde", "/absolute/path", "/absolute/path"},
23
+ {"relative path", "relative/path", "relative/path"},
24
+ }
25
+
26
+ for _, tt := range tests {
27
+ t.Run(tt.name, func(t *testing.T) {
28
+ got := ExpandPath(tt.input)
29
+ if got != tt.expected {
30
+ t.Errorf("ExpandPath(%q) = %q, want %q", tt.input, got, tt.expected)
31
+ }
32
+ })
33
+ }
34
+ }
35
+
36
+ func TestExpandPath_EnvVars(t *testing.T) {
37
+ if err := os.Setenv("SET_VAR", "value"); err != nil {
38
+ t.Fatalf("failed to set env var: %v", err)
39
+ }
40
+ defer func() { _ = os.Unsetenv("SET_VAR") }()
41
+
42
+ tests := []struct {
43
+ name string
44
+ input string
45
+ expected string
46
+ }{
47
+ {"env var expansion (set)", "${SET_VAR:-default}", "value"},
48
+ {"env var expansion (unset)", "${UNSET_VAR:-default}", "default"},
49
+ {"env var expansion (no fallback, set)", "${SET_VAR}", "value"},
50
+ {"env var expansion (no fallback, unset)", "${UNSET_VAR}", ""},
51
+ {"nested env var expansion", "${UNSET_VAR:-${SET_VAR:-fallback}}", "value"},
52
+ }
53
+
54
+ for _, tt := range tests {
55
+ t.Run(tt.name, func(t *testing.T) {
56
+ got := ExpandPath(tt.input)
57
+ if got != tt.expected {
58
+ t.Errorf("ExpandPath(%q) = %q, want %q", tt.input, got, tt.expected)
59
+ }
60
+ })
61
+ }
62
+ }
63
+
64
+ func TestExpandPath_Complex(t *testing.T) {
65
+ home, err := os.UserHomeDir()
66
+ if err != nil {
67
+ t.Fatalf("failed to get user home dir: %v", err)
68
+ }
69
+
70
+ if err := os.Setenv("PROJECT_NAME", "my-project"); err != nil {
71
+ t.Fatalf("failed to set env var: %v", err)
72
+ }
73
+ defer func() { _ = os.Unsetenv("PROJECT_NAME") }()
74
+
75
+ input := "~/prompts/${PROJECT_NAME:-default}/spf"
76
+ expected := filepath.Join(home, "prompts/my-project/spf")
77
+ got := ExpandPath(input)
78
+ if got != expected {
79
+ t.Errorf("ExpandPath(%q) = %q, want %q", input, got, expected)
80
+ }
81
+ }
82
+
83
+ func TestExpandPath_Malformed(t *testing.T) {
84
+ tests := []struct {
85
+ name string
86
+ input string
87
+ expected string
88
+ }{
89
+ {"missing closing brace", "${VAR", "${VAR"},
90
+ {"unbalanced nested", "${VAR:-${NESTED", "${VAR:-${NESTED"},
91
+ }
92
+
93
+ for _, tt := range tests {
94
+ t.Run(tt.name, func(t *testing.T) {
95
+ got := ExpandPath(tt.input)
96
+ if got != tt.expected {
97
+ t.Errorf("ExpandPath(%q) = %q, want %q", tt.input, got, tt.expected)
98
+ }
99
+ })
100
+ }
101
+ }
@@ -0,0 +1,19 @@
1
+ package core
2
+
3
+ // UI defines the interface for interacting with the user and logging progress.
4
+ type UI interface {
5
+ Log(message string)
6
+ Warn(message string)
7
+ Error(message string)
8
+ Success(message string)
9
+
10
+ // SubTask logs a smaller unit of work.
11
+ SubTask(message string)
12
+
13
+ // Spinner management
14
+ StartSpinner(message string)
15
+ StopSpinner()
16
+
17
+ // Interactivity
18
+ Confirm(question string) bool
19
+ }