@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,23 @@
1
+ package installer
2
+
3
+ import (
4
+ "fmt"
5
+ "os/exec"
6
+
7
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
8
+ )
9
+
10
+ // VerifyDependencies checks for git and ripgrep in PATH.
11
+ func VerifyDependencies(ui core.UI) {
12
+ dependencies := []string{"git", "rg"}
13
+ for _, dep := range dependencies {
14
+ _, err := exec.LookPath(dep)
15
+ if err != nil {
16
+ if ui != nil {
17
+ ui.Warn(fmt.Sprintf("Dependency '%s' not found in PATH. Some features may not work correctly.", dep))
18
+ } else {
19
+ fmt.Printf("[WARN] Dependency '%s' not found in PATH. Some features may not work correctly.\n", dep)
20
+ }
21
+ }
22
+ }
23
+ }
@@ -0,0 +1,89 @@
1
+ package installer
2
+
3
+ import (
4
+ "context"
5
+ "errors"
6
+ "fmt"
7
+ "os"
8
+ "path/filepath"
9
+
10
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
11
+ )
12
+
13
+ // Install handles the global installation of the specforce binary.
14
+ func Install(ctx context.Context, ui core.UI) error {
15
+ if err := ctx.Err(); err != nil {
16
+ return err
17
+ }
18
+
19
+ exePath, err := os.Executable()
20
+ if err != nil {
21
+ return fmt.Errorf("failed to get executable path: %w", err)
22
+ }
23
+
24
+ targetDir := "/usr/local/bin"
25
+ targetPath := filepath.Join(targetDir, "specforce")
26
+
27
+ if ui != nil {
28
+ ui.SubTask(fmt.Sprintf("Attempting to install specforce to %s...", targetPath))
29
+ }
30
+
31
+ if err := checkPermissions(ui, targetDir); err != nil {
32
+ handlePermissionError(ui, targetDir, exePath, targetPath)
33
+ return err
34
+ }
35
+
36
+ if err := createSymlink(exePath, targetPath); err != nil {
37
+ return err
38
+ }
39
+
40
+ if ui != nil {
41
+ ui.SubTask(fmt.Sprintf("specforce installed successfully to %s", targetPath))
42
+ }
43
+ return nil
44
+ }
45
+
46
+ func checkPermissions(ui core.UI, dir string) error {
47
+ tmpFile := filepath.Join(filepath.Clean(dir), ".specforce_write_test")
48
+ // #nosec G304 - This is a write test for the installer in a known system directory
49
+ f, err := os.Create(tmpFile)
50
+ if err != nil {
51
+ return fmt.Errorf("failed to check write permissions in %s: %w", dir, errors.Join(core.ErrInstallerPermissionDenied, err))
52
+ }
53
+ if err := f.Close(); err != nil {
54
+ return fmt.Errorf("failed to close temporary file: %w", err)
55
+ }
56
+ if err := os.Remove(tmpFile); err != nil && ui != nil {
57
+ ui.Warn(fmt.Sprintf("Failed to remove temporary file: %s", tmpFile))
58
+ }
59
+ return nil
60
+ }
61
+
62
+ func handlePermissionError(ui core.UI, targetDir, exePath, targetPath string) {
63
+ msg := fmt.Sprintf("%s is not writable without elevated permissions.", targetDir)
64
+ sudoCmd := "Please run: sudo ln -sf " + exePath + " " + targetPath
65
+
66
+ if ui != nil {
67
+ ui.Warn(msg)
68
+ fmt.Println(sudoCmd)
69
+ } else {
70
+ fmt.Printf("[WARN] %s\n", msg)
71
+ fmt.Println(sudoCmd)
72
+ }
73
+ }
74
+
75
+ func createSymlink(exePath, targetPath string) error {
76
+ if err := os.Symlink(exePath, targetPath); err != nil {
77
+ if os.IsExist(err) {
78
+ if err := os.Remove(targetPath); err != nil {
79
+ return fmt.Errorf("failed to remove existing symlink: %w", err)
80
+ }
81
+ if err := os.Symlink(exePath, targetPath); err != nil {
82
+ return fmt.Errorf("failed to create symlink: %w", err)
83
+ }
84
+ } else {
85
+ return fmt.Errorf("failed to create symlink: %w", err)
86
+ }
87
+ }
88
+ return nil
89
+ }
@@ -0,0 +1,45 @@
1
+ package installer
2
+
3
+ import (
4
+ "path/filepath"
5
+ "strings"
6
+
7
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
8
+ )
9
+
10
+ // Options defines configuration for the installation/extraction process.
11
+ type Options struct {
12
+ // ToolsOnly, when true, restricts installation to tool-specific directories
13
+ // and explicitly excludes the .specforce directory.
14
+ ToolsOnly bool
15
+ }
16
+
17
+ // ShouldInstall determines if a given relative path should be installed based on the provided options.
18
+ func ShouldInstall(path string, opts Options) bool {
19
+ if !opts.ToolsOnly {
20
+ return true
21
+ }
22
+
23
+ // Always allow absolute paths in ToolsOnly mode, as they represent global tool exports
24
+ if filepath.IsAbs(path) {
25
+ return true
26
+ }
27
+
28
+ // Ensure the path is normalized for prefix checking
29
+ normalized := strings.TrimPrefix(path, "./")
30
+
31
+ // Explicitly exclude .specforce/ directory in ToolsOnly mode
32
+ if strings.HasPrefix(normalized, ".specforce/") {
33
+ return false
34
+ }
35
+
36
+ // Whitelist tool-specific directories
37
+ for _, prefix := range core.ToolPrefixes {
38
+ if strings.HasPrefix(normalized, prefix) {
39
+ return true
40
+ }
41
+ }
42
+
43
+ // Default to false in ToolsOnly mode if not matched by whitelist
44
+ return false
45
+ }
@@ -0,0 +1,96 @@
1
+ package installer
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
+ )
13
+
14
+ func TestInstall_CancelledContext_ReturnsError(t *testing.T) {
15
+ ctx, cancel := context.WithCancel(context.Background())
16
+ cancel() // cancel immediately
17
+
18
+ err := Install(ctx, nil)
19
+ if err == nil {
20
+ t.Fatal("expected error for cancelled context, got nil")
21
+ }
22
+ if !errors.Is(err, context.Canceled) {
23
+ t.Errorf("expected context.Canceled error, got: %v", err)
24
+ }
25
+ }
26
+
27
+ func TestCheckPermissions_WrapsWithDomainError(t *testing.T) {
28
+ tmpDir, err := os.MkdirTemp("", "specforce-installer-test-*")
29
+ if err != nil {
30
+ t.Fatalf("failed to create temp dir: %v", err)
31
+ }
32
+ defer func() { _ = os.RemoveAll(tmpDir) }()
33
+
34
+ readOnlyDir := filepath.Join(tmpDir, "readonly")
35
+ if err := os.MkdirAll(readOnlyDir, 0444); err != nil {
36
+ t.Fatalf("failed to create read-only dir: %v", err)
37
+ }
38
+
39
+ permErr := checkPermissions(nil, readOnlyDir)
40
+ if permErr == nil {
41
+ t.Skip("no permission error in this environment (possibly running as root)")
42
+ }
43
+
44
+ if !errors.Is(permErr, core.ErrInstallerPermissionDenied) {
45
+ t.Errorf("expected error to wrap ErrInstallerPermissionDenied, got: %v", permErr)
46
+ }
47
+
48
+ if !strings.Contains(permErr.Error(), "failed to check") {
49
+ t.Errorf("expected error message to contain wrapping context, got: %v", permErr)
50
+ }
51
+ }
52
+
53
+ func TestShouldInstall_ToolsOnly(t *testing.T) {
54
+ opts := Options{ToolsOnly: true}
55
+
56
+ tests := []struct {
57
+ path string
58
+ expected bool
59
+ }{
60
+ {".gemini/agents/spf.toml", true},
61
+ {".claude/commands/spf.md", true},
62
+ {".opencode/skills/tdd.md", true},
63
+ {".specforce/config.yaml", false},
64
+ {".specforce/docs/architecture.md", false},
65
+ {"README.md", false},
66
+ {"go.mod", false},
67
+ {".agent/workflows/spf.md", true},
68
+ }
69
+
70
+ for _, tt := range tests {
71
+ got := ShouldInstall(tt.path, opts)
72
+ if got != tt.expected {
73
+ t.Errorf("ShouldInstall(%q, ToolsOnly: true) = %v; want %v", tt.path, got, tt.expected)
74
+ }
75
+ }
76
+ }
77
+
78
+ func TestShouldInstall_All(t *testing.T) {
79
+ opts := Options{ToolsOnly: false}
80
+
81
+ tests := []struct {
82
+ path string
83
+ expected bool
84
+ }{
85
+ {".gemini/agents/spf.toml", true},
86
+ {".specforce/config.yaml", true},
87
+ {"README.md", true},
88
+ }
89
+
90
+ for _, tt := range tests {
91
+ got := ShouldInstall(tt.path, opts)
92
+ if got != tt.expected {
93
+ t.Errorf("ShouldInstall(%q, ToolsOnly: false) = %v; want %v", tt.path, got, tt.expected)
94
+ }
95
+ }
96
+ }
@@ -0,0 +1,108 @@
1
+ package project
2
+
3
+ import (
4
+ "fmt"
5
+ "os"
6
+ "path/filepath"
7
+ "strings"
8
+
9
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
10
+ )
11
+
12
+ const agentsMDTemplate = `<!-- SPECFORCE_AGENTS_START -->
13
+ # AI Agent Collaboration Guide
14
+
15
+ This project uses **Specforce** for Spec-Driven Development (SDD). As an AI agent, you MUST adhere to the following rules:
16
+
17
+ ## 1. Spec-Driven Development (SDD) Protocol
18
+ - **Specs First:** Never write implementation code until a corresponding Specification (requirements.md, design.md, tasks.md) exists and is approved. You MUST consult spec artifacts using the Specforce CLI (e.g., specforce spec list, specforce spec status <slug> --json, and specforce spec artifact <name> --json) rather than reading the raw markdown files directly.
19
+ - **Atomic Tasks:** Follow the exact sequence of the tasks.md roadmap. Mark tasks as [DONE] or [FINISHED] sequentially.
20
+ - **Verification:** Execute the exact verification/TDD steps defined in the tasks.md file before marking a task as complete.
21
+
22
+ ## 2. Project Constitution
23
+ Before proposing architectural changes or adding new patterns, you MUST review the relevant Constitution documents located in .specforce/docs/:
24
+ - principles.md: Core values, philosophy, and cultural/technical axioms.
25
+ - architecture.md: System boundaries, dependency direction, and persistence topology.
26
+ - ui-ux.md: Visual direction, interaction patterns, and aesthetic DNA.
27
+ - security.md: AuthZ, roles, permissions, and data protection rules.
28
+ - engineering.md: Coding standards, testing strategy, and refactoring guidelines.
29
+ - governance.md: Project lifecycle rules, ownership, and AI boundaries.
30
+ - memorial.md: Durable lessons learned and cross-session memory.
31
+
32
+ ## 3. Custom Hooks Configuration
33
+ Specforce allows developers to gate state transitions (e.g., finishing a task) using custom hooks. You can configure these in the project root's config.yaml:
34
+
35
+ ` + "```" + `yaml
36
+ # config.yaml example
37
+ hooks:
38
+ on_task_finish:
39
+ command: "make lint && make test"
40
+ on_spec_finish:
41
+ command: "make build"
42
+ ` + "```" + `
43
+ If a hook fails, the state transition will be blocked.
44
+
45
+ *Note: The content above is managed by Specforce. Do not edit inside these markers.*
46
+ <!-- SPECFORCE_AGENTS_END -->
47
+ `
48
+
49
+ // EnsureAgentsMD creates or updates the AGENTS.md file in the project root.
50
+ func EnsureAgentsMD(root string, ui core.UI) error {
51
+ root = filepath.Clean(root)
52
+ path := filepath.Join(root, "AGENTS.md")
53
+ replacement := generateAgentsContent()
54
+
55
+ var existing string
56
+ if _, err := os.Stat(path); err == nil {
57
+ // #nosec G304
58
+ data, err := os.ReadFile(path)
59
+ if err != nil {
60
+ return fmt.Errorf("failed to read existing AGENTS.md: %w", err)
61
+ }
62
+ existing = string(data)
63
+ }
64
+
65
+ merged := mergeAgentsContent(existing, replacement)
66
+
67
+ if existing == merged {
68
+ return nil
69
+ }
70
+
71
+ if ui != nil {
72
+ ui.SubTask("Updating AGENTS.md...")
73
+ }
74
+
75
+ // #nosec G306 G304
76
+ if err := os.WriteFile(path, []byte(merged), 0600); err != nil {
77
+ return fmt.Errorf("failed to write AGENTS.md: %w", err)
78
+ }
79
+
80
+ return nil
81
+ }
82
+
83
+ func generateAgentsContent() string {
84
+ return agentsMDTemplate
85
+ }
86
+
87
+ func mergeAgentsContent(existing, replacement string) string {
88
+ startMarker := "<!-- SPECFORCE_AGENTS_START -->"
89
+ endMarker := "<!-- SPECFORCE_AGENTS_END -->"
90
+
91
+ startIdx := strings.Index(existing, startMarker)
92
+ endIdx := strings.Index(existing, endMarker)
93
+
94
+ if startIdx != -1 && endIdx != -1 && endIdx > startIdx {
95
+ // Replace content between markers (including markers)
96
+ return existing[:startIdx] + replacement + existing[endIdx+len(endMarker):]
97
+ }
98
+
99
+ if existing == "" {
100
+ return replacement
101
+ }
102
+
103
+ // Append to end if markers not found
104
+ if !strings.HasSuffix(existing, "\n") {
105
+ existing += "\n"
106
+ }
107
+ return existing + replacement
108
+ }
@@ -0,0 +1,101 @@
1
+ package project
2
+
3
+ import (
4
+ "os"
5
+ "path/filepath"
6
+ "strings"
7
+ "testing"
8
+ )
9
+
10
+ func TestEnsureAgentsMD(t *testing.T) {
11
+ tempDir, err := os.MkdirTemp("", "specforce-test-*")
12
+ if err != nil {
13
+ t.Fatalf("failed to create temp dir: %v", err)
14
+ }
15
+ defer func() { _ = os.RemoveAll(tempDir) }()
16
+
17
+ t.Run("Create new file", func(t *testing.T) {
18
+ err := EnsureAgentsMD(tempDir, nil)
19
+ if err != nil {
20
+ t.Errorf("expected no error, got %v", err)
21
+ }
22
+
23
+ path := filepath.Join(tempDir, "AGENTS.md")
24
+ if _, err := os.Stat(path); os.IsNotExist(err) {
25
+ t.Errorf("AGENTS.md was not created")
26
+ }
27
+
28
+ content, _ := os.ReadFile(path)
29
+ if !strings.Contains(string(content), "<!-- SPECFORCE_AGENTS_START -->") {
30
+ t.Errorf("created file missing markers")
31
+ }
32
+ })
33
+
34
+ t.Run("Update existing file", func(t *testing.T) {
35
+ path := filepath.Join(tempDir, "AGENTS.md")
36
+ customContent := "CUSTOM START\n<!-- SPECFORCE_AGENTS_START -->\nOLD\n<!-- SPECFORCE_AGENTS_END -->\nCUSTOM END"
37
+ err := os.WriteFile(path, []byte(customContent), 0644)
38
+ if err != nil {
39
+ t.Fatalf("failed to write existing file: %v", err)
40
+ }
41
+
42
+ err = EnsureAgentsMD(tempDir, nil)
43
+ if err != nil {
44
+ t.Errorf("expected no error, got %v", err)
45
+ }
46
+
47
+ content, _ := os.ReadFile(path)
48
+ if !strings.HasPrefix(string(content), "CUSTOM START") {
49
+ t.Errorf("custom content not preserved")
50
+ }
51
+ if !strings.Contains(string(content), "# AI Agent Collaboration Guide") {
52
+ t.Errorf("managed content not updated")
53
+ }
54
+ })
55
+ }
56
+
57
+ func TestGenerateAgentsContent(t *testing.T) {
58
+ content := generateAgentsContent()
59
+
60
+ if !strings.Contains(content, "<!-- SPECFORCE_AGENTS_START -->") {
61
+ t.Errorf("content does not contain start marker")
62
+ }
63
+ if !strings.Contains(content, "<!-- SPECFORCE_AGENTS_END -->") {
64
+ t.Errorf("content does not contain end marker")
65
+ }
66
+ if !strings.Contains(content, "# AI Agent Collaboration Guide") {
67
+ t.Errorf("content does not contain title")
68
+ }
69
+ }
70
+
71
+ func TestMergeAgentsContent(t *testing.T) {
72
+ replacement := "NEW CONTENT"
73
+
74
+ t.Run("Empty existing", func(t *testing.T) {
75
+ existing := ""
76
+ result := mergeAgentsContent(existing, replacement)
77
+ if result != replacement {
78
+ t.Errorf("expected %q, got %q", replacement, result)
79
+ }
80
+ })
81
+
82
+ t.Run("Existing without markers", func(t *testing.T) {
83
+ existing := "CUSTOM CONTENT"
84
+ result := mergeAgentsContent(existing, replacement)
85
+ if !strings.HasPrefix(result, "CUSTOM CONTENT") {
86
+ t.Errorf("custom content not preserved at start")
87
+ }
88
+ if !strings.Contains(result, replacement) {
89
+ t.Errorf("replacement not found")
90
+ }
91
+ })
92
+
93
+ t.Run("Existing with markers", func(t *testing.T) {
94
+ existing := "CUSTOM START\n<!-- SPECFORCE_AGENTS_START -->\nOLD CONTENT\n<!-- SPECFORCE_AGENTS_END -->\nCUSTOM END"
95
+ result := mergeAgentsContent(existing, replacement)
96
+ expected := "CUSTOM START\n" + replacement + "\nCUSTOM END"
97
+ if result != expected {
98
+ t.Errorf("expected %q, got %q", expected, result)
99
+ }
100
+ })
101
+ }
@@ -0,0 +1,64 @@
1
+ package project
2
+
3
+ import (
4
+ "context"
5
+ "fmt"
6
+ "io/fs"
7
+ "os"
8
+ "path/filepath"
9
+
10
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
11
+ )
12
+
13
+ // BootstrapProject creates the basic Specforce directory structure and initializes standard templates.
14
+ func BootstrapProject(ctx context.Context, root string, kitFS fs.FS, artifactsFS fs.FS, ui core.UI) error {
15
+ if err := ctx.Err(); err != nil {
16
+ return err
17
+ }
18
+
19
+ if _, err := os.Stat(filepath.Join(root, ".specforce")); err == nil {
20
+ return fmt.Errorf("cannot initialize project: %w", core.ErrProjectAlreadyInitialized)
21
+ }
22
+
23
+ dirs := []string{
24
+ ".specforce/docs",
25
+ ".specforce/specs",
26
+ ".specforce/archive",
27
+ }
28
+
29
+ if ui != nil {
30
+ ui.StartSpinner("Creating directories...")
31
+ }
32
+ if err := createDirectories(root, dirs); err != nil {
33
+ return err
34
+ }
35
+
36
+ if ui != nil {
37
+ ui.StopSpinner()
38
+ ui.Success("Specforce directory structure initialized successfully.")
39
+ }
40
+
41
+ if err := EnsureAgentsMD(root, ui); err != nil {
42
+ return fmt.Errorf("failed to ensure AGENTS.md: %w", err)
43
+ }
44
+
45
+ return nil
46
+ }
47
+
48
+ func createDirectories(root string, dirs []string) error {
49
+ for _, dir := range dirs {
50
+ path := filepath.Join(root, dir)
51
+ if err := os.MkdirAll(path, 0750); err != nil {
52
+ return fmt.Errorf("failed to create directory %s: %w", path, err)
53
+ }
54
+
55
+ // Add .gitkeep to ensure directories are tracked if empty
56
+ gitkeep := filepath.Join(path, ".gitkeep")
57
+ if _, err := os.Stat(gitkeep); os.IsNotExist(err) {
58
+ if err := os.WriteFile(gitkeep, []byte(""), 0600); err != nil {
59
+ return fmt.Errorf("failed to create .gitkeep in %s: %w", path, err)
60
+ }
61
+ }
62
+ }
63
+ return nil
64
+ }
@@ -0,0 +1,89 @@
1
+ package project
2
+
3
+ import (
4
+ "context"
5
+ "os"
6
+ "path/filepath"
7
+ "testing"
8
+ "testing/fstest"
9
+ )
10
+
11
+ type mockUI struct {
12
+ warnCalled bool
13
+ }
14
+
15
+ func (m *mockUI) Log(msg string) {}
16
+ func (m *mockUI) Success(msg string) {}
17
+ func (m *mockUI) Warn(msg string) { m.warnCalled = true }
18
+ func (m *mockUI) Error(msg string) {}
19
+ func (m *mockUI) SubTask(msg string) {}
20
+ func (m *mockUI) StartSpinner(msg string) {}
21
+ func (m *mockUI) StopSpinner() {}
22
+ func (m *mockUI) Confirm(msg string) bool { return true }
23
+
24
+ func TestBootstrapProject_Success(t *testing.T) {
25
+ tmpDir := t.TempDir()
26
+ ctx := context.Background()
27
+
28
+ // Mock artifacts filesystem
29
+ artifactsFS := fstest.MapFS{}
30
+
31
+ err := BootstrapProject(ctx, tmpDir, nil, artifactsFS, &mockUI{})
32
+ if err != nil {
33
+ t.Fatalf("expected no error, got %v", err)
34
+ }
35
+
36
+ dirs := []string{
37
+ ".specforce/docs",
38
+ ".specforce/specs",
39
+ ".specforce/archive",
40
+ }
41
+
42
+ for _, dir := range dirs {
43
+ path := filepath.Join(tmpDir, dir)
44
+ if info, err := os.Stat(path); err != nil || !info.IsDir() {
45
+ t.Errorf("expected directory %s to exist", path)
46
+ }
47
+ if _, err := os.Stat(filepath.Join(path, ".gitkeep")); os.IsNotExist(err) {
48
+ t.Errorf("expected .gitkeep in %s", path)
49
+ }
50
+ }
51
+
52
+ // Verify .specforce/templates does NOT exist
53
+ templatesPath := filepath.Join(tmpDir, ".specforce/templates")
54
+ if _, err := os.Stat(templatesPath); !os.IsNotExist(err) {
55
+ t.Errorf("expected directory %s NOT to exist", templatesPath)
56
+ }
57
+ }
58
+
59
+ func TestBootstrapProject_Errors(t *testing.T) {
60
+ tmpDir := t.TempDir()
61
+ ctx := context.Background()
62
+ artifactsFS := fstest.MapFS{}
63
+
64
+ t.Run("already initialized", func(t *testing.T) {
65
+ if err := os.Mkdir(filepath.Join(tmpDir, ".specforce"), 0755); err != nil {
66
+ t.Fatal(err)
67
+ }
68
+ err := BootstrapProject(ctx, tmpDir, nil, artifactsFS, nil)
69
+ if err == nil {
70
+ t.Fatal("expected error when already initialized")
71
+ }
72
+ })
73
+
74
+ t.Run("cancelled context", func(t *testing.T) {
75
+ cancelCtx, cancel := context.WithCancel(ctx)
76
+ cancel()
77
+ err := BootstrapProject(cancelCtx, t.TempDir(), nil, artifactsFS, nil)
78
+ if err == nil {
79
+ t.Fatal("expected error for cancelled context")
80
+ }
81
+ })
82
+
83
+ t.Run("nil ui success", func(t *testing.T) {
84
+ err := BootstrapProject(ctx, t.TempDir(), nil, artifactsFS, nil)
85
+ if err != nil {
86
+ t.Fatalf("BootstrapProject failed with nil UI: %v", err)
87
+ }
88
+ })
89
+ }
@@ -0,0 +1,35 @@
1
+ package project
2
+
3
+ import (
4
+ "context"
5
+ "os"
6
+ "path/filepath"
7
+
8
+ "github.com/jeancodogno/specforce-kit/src/internal/agent"
9
+ )
10
+
11
+ // DetectExistingAgents checks for existing agent directories in the current project using the registry.
12
+ func DetectExistingAgents(ctx context.Context, root string, reg *agent.Registry) []string {
13
+ var existing []string
14
+ if reg == nil {
15
+ return existing
16
+ }
17
+
18
+ for _, agent := range reg.GetAgents() {
19
+ if err := ctx.Err(); err != nil {
20
+ return existing
21
+ }
22
+ path := filepath.Join(root, agent.DirName)
23
+ if info, err := os.Stat(path); err == nil && info.IsDir() {
24
+ existing = append(existing, agent.ID)
25
+ }
26
+ }
27
+
28
+ return existing
29
+ }
30
+
31
+ // IsInitialized checks if the project has been initialized by looking for the .specforce directory.
32
+ func IsInitialized(root string) bool {
33
+ info, err := os.Stat(filepath.Join(root, ".specforce"))
34
+ return err == nil && info.IsDir()
35
+ }