@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,139 @@
1
+ package constitution
2
+
3
+ import (
4
+ "fmt"
5
+ "io/fs"
6
+ "path/filepath"
7
+ "strings"
8
+
9
+ "gopkg.in/yaml.v3"
10
+ )
11
+
12
+ // Artifact represents a constitution document specification.
13
+ type Artifact struct {
14
+ Slug string `json:"slug" yaml:"-"`
15
+ Name string `json:"name" yaml:"-"`
16
+ Description string `json:"description" yaml:"description"`
17
+ Instruction string `json:"instruction" yaml:"instruction"`
18
+ Template string `json:"template" yaml:"template"`
19
+ Path string `json:"path" yaml:"-"`
20
+ }
21
+
22
+ // Registry manages the collection of constitution artifacts.
23
+ type Registry struct {
24
+ artifacts map[string]Artifact
25
+ }
26
+
27
+ // NewRegistry initializes a new registry by loading YAML files from the provided filesystem.
28
+ func NewRegistry(artifactsFS fs.FS) (*Registry, error) {
29
+ r := &Registry{
30
+ artifacts: make(map[string]Artifact),
31
+ }
32
+
33
+ // The artifacts are located at the root of the provided filesystem
34
+ // (usually sub-filesystem of internal/agent/artifacts/constitution)
35
+ artifactRoot := "."
36
+
37
+ err := fs.WalkDir(artifactsFS, artifactRoot, func(path string, d fs.DirEntry, err error) error {
38
+ if err != nil {
39
+ return err
40
+ }
41
+ if d.IsDir() || !strings.HasSuffix(d.Name(), ".yaml") || d.Name() == "mapping.yaml" {
42
+ return nil
43
+ }
44
+
45
+ art, err := loadArtifact(artifactsFS, path, d.Name())
46
+ if err != nil {
47
+ return err
48
+ }
49
+
50
+ r.artifacts[art.Slug] = art
51
+ return nil
52
+ })
53
+
54
+ if err != nil {
55
+ return nil, fmt.Errorf("failed to load constitution artifacts: %w", err)
56
+ }
57
+
58
+ return r, nil
59
+ }
60
+
61
+ func loadArtifact(artifactsFS fs.FS, path, fileName string) (Artifact, error) {
62
+ data, err := fs.ReadFile(artifactsFS, path)
63
+ if err != nil {
64
+ return Artifact{}, fmt.Errorf("failed to read artifact %s: %w", path, err)
65
+ }
66
+
67
+ var art Artifact
68
+ if err := yaml.Unmarshal(data, &art); err != nil {
69
+ return Artifact{}, fmt.Errorf("failed to parse artifact %s: %w", path, err)
70
+ }
71
+
72
+ // Validation: Check required fields
73
+ if art.Description == "" {
74
+ return Artifact{}, fmt.Errorf("artifact %s is missing 'description'", path)
75
+ }
76
+ if art.Instruction == "" {
77
+ return Artifact{}, fmt.Errorf("artifact %s is missing 'instruction'", path)
78
+ }
79
+ if art.Template == "" {
80
+ return Artifact{}, fmt.Errorf("artifact %s is missing 'template'", path)
81
+ }
82
+
83
+ // Slug is the filename without extension
84
+ art.Slug = strings.TrimSuffix(fileName, ".yaml")
85
+
86
+ // Handle "index" special case (remove leading underscore for Slug/Name)
87
+ if art.Slug == "_index" {
88
+ art.Slug = "index"
89
+ }
90
+
91
+ // Name is the clean artifact name (slug)
92
+ art.Name = art.Slug
93
+
94
+ // Path is the expected project-relative path (with extension)
95
+ mdFileName := art.Slug + ".md"
96
+ if art.Slug == "index" {
97
+ mdFileName = "_index.md"
98
+ }
99
+
100
+ art.Path = filepath.Join(".specforce", "docs", mdFileName)
101
+
102
+ return art, nil
103
+ }
104
+
105
+ // Get returns an artifact by its slug.
106
+ func (r *Registry) Get(slug string) (Artifact, bool) {
107
+ art, ok := r.artifacts[slug]
108
+ return art, ok
109
+ }
110
+
111
+ // List returns all loaded artifacts.
112
+ func (r *Registry) List() []Artifact {
113
+ list := make([]Artifact, 0, len(r.artifacts))
114
+ // We want a stable order, but for now simple slice is fine.
115
+ // Common order: principles, architecture, ui-ux, security, engineering, governance, memorial
116
+ order := []string{"principles", "architecture", "ui-ux", "security", "engineering", "governance", "memorial"}
117
+
118
+ for _, slug := range order {
119
+ if art, ok := r.artifacts[slug]; ok {
120
+ list = append(list, art)
121
+ }
122
+ }
123
+
124
+ // Catch any artifacts not in the explicit order
125
+ for slug, art := range r.artifacts {
126
+ found := false
127
+ for _, orderedSlug := range order {
128
+ if slug == orderedSlug {
129
+ found = true
130
+ break
131
+ }
132
+ }
133
+ if !found {
134
+ list = append(list, art)
135
+ }
136
+ }
137
+
138
+ return list
139
+ }
@@ -0,0 +1,97 @@
1
+ package constitution
2
+
3
+ import (
4
+ "os"
5
+ "testing"
6
+ "testing/fstest"
7
+ )
8
+
9
+ func TestNewRegistry(t *testing.T) {
10
+ // The artifacts are in src/internal/agent/artifacts/constitution/
11
+ // We are in src/internal/constitution/
12
+ artifactsRoot := "../../internal/agent/artifacts/constitution"
13
+ artifactsFS := os.DirFS(artifactsRoot)
14
+
15
+ registry, err := NewRegistry(artifactsFS)
16
+ if err != nil {
17
+ t.Fatalf("Failed to create registry: %v", err)
18
+ }
19
+
20
+ artifacts := registry.List()
21
+ if len(artifacts) < 7 {
22
+ t.Errorf("Expected at least 7 artifacts, got %d", len(artifacts))
23
+ }
24
+
25
+ // Verify Architecture artifact
26
+ arch, ok := registry.Get("architecture")
27
+ if !ok {
28
+ t.Fatal("Architecture artifact not found")
29
+ }
30
+
31
+ if arch.Description == "" {
32
+ t.Error("Architecture description should not be empty")
33
+ }
34
+ if arch.Instruction == "" {
35
+ t.Error("Architecture instruction should not be empty")
36
+ }
37
+ if arch.Template == "" {
38
+ t.Error("Architecture template should not be empty")
39
+ }
40
+ if arch.Name != "architecture" {
41
+ t.Errorf("Expected architecture, got %s", arch.Name)
42
+ }
43
+ if arch.Path != ".specforce/docs/architecture.md" {
44
+ t.Errorf("Expected .specforce/docs/architecture.md, got %s", arch.Path)
45
+ }
46
+ }
47
+
48
+ func TestNewRegistry_IndexSpecialCase(t *testing.T) {
49
+ mockFS := fstest.MapFS{
50
+ "index.yaml": &fstest.MapFile{
51
+ Data: []byte("description: Index Description\ninstruction: Index Instruction\ntemplate: Index Template"),
52
+ },
53
+ }
54
+
55
+ reg, err := NewRegistry(mockFS)
56
+ if err != nil {
57
+ t.Fatalf("Failed to create registry with mock FS: %v", err)
58
+ }
59
+
60
+ idx, ok := reg.Get("index")
61
+ if !ok {
62
+ t.Fatal("Index artifact not found")
63
+ }
64
+
65
+ if idx.Name != "index" {
66
+ t.Errorf("Expected index, got %s", idx.Name)
67
+ }
68
+ if idx.Path != ".specforce/docs/_index.md" {
69
+ t.Errorf("Expected .specforce/docs/_index.md, got %s", idx.Path)
70
+ }
71
+ }
72
+
73
+ func TestNewRegistry_LeadingUnderscoreSpecialCase(t *testing.T) {
74
+ mockFS := fstest.MapFS{
75
+ "_index.yaml": &fstest.MapFile{
76
+ Data: []byte("description: Index Description\ninstruction: Index Instruction\ntemplate: Index Template"),
77
+ },
78
+ }
79
+
80
+ reg, err := NewRegistry(mockFS)
81
+ if err != nil {
82
+ t.Fatalf("Failed to create registry with mock FS: %v", err)
83
+ }
84
+
85
+ idx, ok := reg.Get("index")
86
+ if !ok {
87
+ // If it's stored as _index, this will fail
88
+ t.Fatal("Index artifact not found by 'index' slug")
89
+ }
90
+
91
+ if idx.Name != "index" {
92
+ t.Errorf("Expected name 'index', got %s", idx.Name)
93
+ }
94
+ if idx.Path != ".specforce/docs/_index.md" {
95
+ t.Errorf("Expected path .specforce/docs/_index.md, got %s", idx.Path)
96
+ }
97
+ }
@@ -0,0 +1,70 @@
1
+ package constitution
2
+
3
+ import (
4
+ "context"
5
+ "os"
6
+ "path/filepath"
7
+ )
8
+
9
+ // ArtifactStatus represents the presence and description of a single constitution document.
10
+ type ArtifactStatus struct {
11
+ Name string `json:"name"`
12
+ Description string `json:"description"`
13
+ Path string `json:"path"`
14
+ Exists bool `json:"exists"`
15
+ }
16
+
17
+ // ConstitutionStatus represents the overall completion state of the project's documentation.
18
+ type ConstitutionStatus struct {
19
+ Artifacts []ArtifactStatus `json:"artifacts"`
20
+ Progress int `json:"progress"`
21
+ Total int `json:"total"`
22
+ Found int `json:"found"`
23
+ }
24
+
25
+ // GetStatus checks the filesystem for the required artifacts from the registry and returns a progress summary.
26
+ func GetStatus(ctx context.Context, projectRoot string, registry *Registry) (ConstitutionStatus, error) {
27
+ artifacts := registry.List()
28
+
29
+ // Filter for standard core artifacts (exclude index and module as they are meta/dynamic)
30
+ // Actually, index IS core. memorial and current-state are also core.
31
+ // Only 'module' is a generic template.
32
+
33
+ coreArtifacts := make([]Artifact, 0)
34
+ for _, art := range artifacts {
35
+ if art.Slug == "module" {
36
+ continue
37
+ }
38
+ coreArtifacts = append(coreArtifacts, art)
39
+ }
40
+
41
+ status := ConstitutionStatus{
42
+ Artifacts: make([]ArtifactStatus, len(coreArtifacts)),
43
+ Total: len(coreArtifacts),
44
+ }
45
+
46
+ for i, art := range coreArtifacts {
47
+ if err := ctx.Err(); err != nil {
48
+ return status, err
49
+ }
50
+ fullPath := filepath.Join(projectRoot, art.Path)
51
+ exists := false
52
+ if _, err := os.Stat(fullPath); err == nil {
53
+ exists = true
54
+ status.Found++
55
+ }
56
+
57
+ status.Artifacts[i] = ArtifactStatus{
58
+ Name: art.Name,
59
+ Description: art.Description,
60
+ Path: art.Path,
61
+ Exists: exists,
62
+ }
63
+ }
64
+
65
+ if status.Total > 0 {
66
+ status.Progress = (status.Found * 100) / status.Total
67
+ }
68
+
69
+ return status, nil
70
+ }
@@ -0,0 +1,160 @@
1
+ package constitution
2
+
3
+ import (
4
+ "context"
5
+ "os"
6
+ "path/filepath"
7
+ "testing"
8
+ )
9
+
10
+ func getTestRegistry(t *testing.T) *Registry {
11
+ // The artifacts are in src/internal/agent/artifacts/constitution/
12
+ // We are in src/internal/constitution/
13
+ artifactsRoot := "../../internal/agent/artifacts/constitution"
14
+ artifactsFS := os.DirFS(artifactsRoot)
15
+
16
+ registry, err := NewRegistry(artifactsFS)
17
+ if err != nil {
18
+ t.Fatalf("Failed to create registry for testing: %v", err)
19
+ }
20
+ return registry
21
+ }
22
+
23
+ func TestGetStatus(t *testing.T) {
24
+ registry := getTestRegistry(t)
25
+
26
+ // Create a temporary directory for tests
27
+ tmpDir, err := os.MkdirTemp("", "specforce-test-*")
28
+ if err != nil {
29
+ t.Fatalf("failed to create temp dir: %v", err)
30
+ }
31
+ defer func() {
32
+ _ = os.RemoveAll(tmpDir)
33
+ }()
34
+
35
+ t.Run("Empty directory", func(t *testing.T) {
36
+ runEmptyDirTest(t, tmpDir, registry)
37
+ })
38
+
39
+ t.Run("All core files present", func(t *testing.T) {
40
+ runAllFilesPresentTest(t, tmpDir, registry)
41
+ })
42
+
43
+ t.Run("Partially present", func(t *testing.T) {
44
+ runPartiallyPresentTest(t, registry)
45
+ })
46
+
47
+ t.Run("Missing docs directory", func(t *testing.T) {
48
+ runMissingDocsDirTest(t, registry)
49
+ })
50
+ }
51
+
52
+ func runEmptyDirTest(t *testing.T, tmpDir string, registry *Registry) {
53
+ status, err := GetStatus(context.Background(), tmpDir, registry)
54
+ if err != nil {
55
+ t.Fatalf("GetStatus failed: %v", err)
56
+ }
57
+
58
+ // We removed current-state and index, so it should be 7 artifacts
59
+ // (principles, architecture, ui-ux, security, engineering, governance, memorial)
60
+ expectedTotal := 7
61
+ if status.Total != expectedTotal {
62
+ t.Errorf("expected %d artifacts, got %d", expectedTotal, status.Total)
63
+ }
64
+ if status.Found != 0 {
65
+ t.Errorf("expected 0 found, got %d", status.Found)
66
+ }
67
+ if status.Progress != 0 {
68
+ t.Errorf("expected 0%% progress, got %d%%", status.Progress)
69
+ }
70
+ for _, a := range status.Artifacts {
71
+ if a.Exists {
72
+ t.Errorf("artifact %s should not exist", a.Name)
73
+ }
74
+ }
75
+ }
76
+
77
+ func runAllFilesPresentTest(t *testing.T, tmpDir string, registry *Registry) {
78
+ docsDir := filepath.Join(tmpDir, ".specforce", "docs")
79
+ if err := os.MkdirAll(docsDir, 0755); err != nil {
80
+ t.Fatalf("failed to create docs dir: %v", err)
81
+ }
82
+
83
+ artifacts := registry.List()
84
+ coreCount := 0
85
+ for _, art := range artifacts {
86
+ if art.Slug == "module" {
87
+ continue
88
+ }
89
+ coreCount++
90
+ if err := os.WriteFile(filepath.Join(tmpDir, art.Path), []byte("test"), 0644); err != nil {
91
+ t.Fatalf("failed to write test file %s: %v", art.Name, err)
92
+ }
93
+ }
94
+
95
+ status, err := GetStatus(context.Background(), tmpDir, registry)
96
+ if err != nil {
97
+ t.Fatalf("GetStatus failed: %v", err)
98
+ }
99
+
100
+ if status.Found != coreCount {
101
+ t.Errorf("expected %d found, got %d", coreCount, status.Found)
102
+ }
103
+ if status.Progress != 100 {
104
+ t.Errorf("expected 100%% progress, got %d%%", status.Progress)
105
+ }
106
+ }
107
+
108
+ func runPartiallyPresentTest(t *testing.T, registry *Registry) {
109
+ partialTmpDir, err := os.MkdirTemp("", "specforce-test-partial-*")
110
+ if err != nil {
111
+ t.Fatalf("failed to create partial temp dir: %v", err)
112
+ }
113
+ defer func() {
114
+ _ = os.RemoveAll(partialTmpDir)
115
+ }()
116
+
117
+ docsDir := filepath.Join(partialTmpDir, ".specforce", "docs")
118
+ if err := os.MkdirAll(docsDir, 0755); err != nil {
119
+ t.Fatalf("failed to create docs dir: %v", err)
120
+ }
121
+
122
+ artifacts := registry.List()
123
+ coreArtifacts := make([]Artifact, 0)
124
+ for _, art := range artifacts {
125
+ if art.Slug != "module" {
126
+ coreArtifacts = append(coreArtifacts, art)
127
+ }
128
+ }
129
+
130
+ // Create only the first 2 core artifacts
131
+ for i := 0; i < 2; i++ {
132
+ if err := os.WriteFile(filepath.Join(partialTmpDir, coreArtifacts[i].Path), []byte("test"), 0644); err != nil {
133
+ t.Fatalf("failed to write partial test file: %v", err)
134
+ }
135
+ }
136
+
137
+ status, err := GetStatus(context.Background(), partialTmpDir, registry)
138
+ if err != nil {
139
+ t.Fatalf("GetStatus failed: %v", err)
140
+ }
141
+
142
+ if status.Found != 2 {
143
+ t.Errorf("expected 2 found, got %d", status.Found)
144
+ }
145
+ // (2/7) * 100 = 28.57... -> 28
146
+ expectedProgress := (2 * 100) / len(coreArtifacts)
147
+ if status.Progress != expectedProgress {
148
+ t.Errorf("expected %d%% progress, got %d%%", expectedProgress, status.Progress)
149
+ }
150
+ }
151
+
152
+ func runMissingDocsDirTest(t *testing.T, registry *Registry) {
153
+ status, err := GetStatus(context.Background(), "/non-existent-dir-12345", registry)
154
+ if err != nil {
155
+ t.Fatalf("GetStatus failed: %v", err)
156
+ }
157
+ if status.Found != 0 {
158
+ t.Errorf("expected 0 found, got %d", status.Found)
159
+ }
160
+ }
@@ -0,0 +1,49 @@
1
+ package core
2
+
3
+ import (
4
+ "fmt"
5
+ "strings"
6
+
7
+ "gopkg.in/yaml.v3"
8
+ )
9
+
10
+ // MappingConfig defines where and how a blueprint should be adapted for an agent.
11
+ type MappingConfig struct {
12
+ Target string `yaml:"target,omitempty"`
13
+ Path string `yaml:"path"`
14
+ Name string `yaml:"name"`
15
+ Ext string `yaml:"ext"`
16
+ }
17
+
18
+ // BlueprintMetadata contains the structured metadata of a framework asset.
19
+ type BlueprintMetadata struct {
20
+ Name string `yaml:"name"`
21
+ Description string `yaml:"description"`
22
+ Version string `yaml:"version,omitempty"`
23
+ Priority string `yaml:"priority,omitempty"`
24
+ Triggers []string `yaml:"triggers,omitempty"`
25
+ Mapping map[string]MappingConfig `yaml:"mapping"`
26
+ Content string `yaml:"content,omitempty"`
27
+ }
28
+
29
+ // Blueprint represents a framework asset with metadata and content.
30
+ type Blueprint struct {
31
+ ID string
32
+ Metadata BlueprintMetadata
33
+ Content string
34
+ }
35
+
36
+ // ParseBlueprint parses a file content (pure YAML) into a Blueprint struct.
37
+ func ParseBlueprint(id string, data []byte) (*Blueprint, error) {
38
+ var metadata BlueprintMetadata
39
+ if err := yaml.Unmarshal(data, &metadata); err != nil {
40
+ return nil, fmt.Errorf("failed to parse blueprint metadata (ID: %s): %w", id, err)
41
+ }
42
+
43
+ // For YAML blueprints, we expect both metadata and content to be in the same file structure.
44
+ return &Blueprint{
45
+ ID: id,
46
+ Metadata: metadata,
47
+ Content: strings.TrimSpace(metadata.Content),
48
+ }, nil
49
+ }
@@ -0,0 +1,58 @@
1
+ package core
2
+
3
+ import (
4
+ "testing"
5
+ )
6
+
7
+ func TestParseBlueprint(t *testing.T) {
8
+ tests := []struct {
9
+ name string
10
+ id string
11
+ data string
12
+ wantErr bool
13
+ }{
14
+ {
15
+ name: "Valid blueprint",
16
+ id: "test-bp",
17
+ data: `
18
+ name: Test Blueprint
19
+ description: A test blueprint
20
+ mapping:
21
+ agent1:
22
+ path: path/to/agent1
23
+ name: name1
24
+ ext: .md
25
+ content: |
26
+ This is the content.
27
+ `,
28
+ wantErr: false,
29
+ },
30
+ {
31
+ name: "Invalid YAML",
32
+ id: "invalid-yaml",
33
+ data: `name: : invalid`,
34
+ wantErr: true,
35
+ },
36
+ }
37
+
38
+ for _, tt := range tests {
39
+ t.Run(tt.name, func(t *testing.T) {
40
+ got, err := ParseBlueprint(tt.id, []byte(tt.data))
41
+ if (err != nil) != tt.wantErr {
42
+ t.Errorf("ParseBlueprint() error = %v, wantErr %v", err, tt.wantErr)
43
+ return
44
+ }
45
+ if !tt.wantErr {
46
+ if got.ID != tt.id {
47
+ t.Errorf("ParseBlueprint() ID = %v, want %v", got.ID, tt.id)
48
+ }
49
+ if got.Metadata.Name != "Test Blueprint" {
50
+ t.Errorf("ParseBlueprint() Name = %v, want %v", got.Metadata.Name, "Test Blueprint")
51
+ }
52
+ if got.Content != "This is the content." {
53
+ t.Errorf("ParseBlueprint() Content = %v, want %v", got.Content, "This is the content.")
54
+ }
55
+ }
56
+ })
57
+ }
58
+ }
@@ -0,0 +1,124 @@
1
+ package core
2
+
3
+ import (
4
+ "fmt"
5
+ "os"
6
+ "path/filepath"
7
+
8
+ "gopkg.in/yaml.v3"
9
+ )
10
+
11
+ // HooksConfig contains the commands to run for specific implementation events.
12
+ type HooksConfig struct {
13
+ OnTaskFinished []string `yaml:"on_task_finished"`
14
+ OnPhaseFinished []string `yaml:"on_phase_finished"`
15
+ OnAllTasksFinished []string `yaml:"on_all_tasks_finished"`
16
+ }
17
+
18
+ // ProjectConfig contains the project-specific configuration.
19
+ type ProjectConfig struct {
20
+ Instructions map[string][]string `yaml:"instructions"`
21
+ Hooks HooksConfig `yaml:"hooks"`
22
+ }
23
+
24
+ // DefaultConfigContent is the default content for the .specforce/config.yaml file.
25
+ const DefaultConfigContent = `instructions:
26
+ # Example: Project-wide instructions for all requirements artifacts
27
+ # requirements:
28
+ # - "Always use BDD GIVEN/WHEN/THEN syntax"
29
+ # - "Ensure accessibility is mentioned for UI components"
30
+
31
+ # Example: Project-wide instructions for all design artifacts
32
+ # design:
33
+ # - "Use Mermaid.js for architecture diagrams"
34
+ # - "Include a detailed component inventory"
35
+
36
+ # Example: Project-wide instructions for all tasks artifacts
37
+ # tasks:
38
+ # - "Each task must have a clear verification step"
39
+ # - "Group tasks by implementation phases"
40
+
41
+ # Example: Project-wide instructions for the implementation phase
42
+ # implementation:
43
+ # - "Always run 'go fmt' before finishing a task"
44
+ # - "Use explicit type casts instead of interfaces when possible"
45
+
46
+ # Example: Project-wide instructions for the archive phase
47
+ # archive:
48
+ # - "Always update the project memorial with lessons learned"
49
+ # - "Ensure all temporary artifacts are cleaned up"
50
+
51
+ hooks:
52
+ # Example: Run linting and tests automatically when finishing tasks
53
+ # on_task_finished:
54
+ # - "golangci-lint run"
55
+ # on_phase_finished:
56
+ # - "go test ./src/internal/..."
57
+ # on_all_tasks_finished:
58
+ # - "go test ./..."
59
+ `
60
+
61
+ // EnsureConfigExists checks if the configuration file exists, and creates it with default content if it doesn't.
62
+ func EnsureConfigExists(root string) error {
63
+ specforceDir, err := SecurePath(root, ".specforce")
64
+ if err != nil {
65
+ return fmt.Errorf("security: %w", err)
66
+ }
67
+ configPath, err := SecurePath(root, filepath.Join(".specforce", "config.yaml"))
68
+ if err != nil {
69
+ return fmt.Errorf("security: %w", err)
70
+ }
71
+
72
+ // Check if file already exists
73
+ if _, err := os.Stat(configPath); err == nil {
74
+ return nil // Already exists, do nothing
75
+ }
76
+
77
+ // Create .specforce directory if it doesn't exist
78
+ if err := os.MkdirAll(specforceDir, 0750); err != nil {
79
+ return fmt.Errorf("failed to create .specforce directory: %w", err)
80
+ }
81
+
82
+ // Write default content
83
+ // #nosec G306 - Config path is secured by SecurePath
84
+ if err := os.WriteFile(configPath, []byte(DefaultConfigContent), 0600); err != nil {
85
+ return fmt.Errorf("failed to write default config file: %w", err)
86
+ }
87
+
88
+ return nil
89
+ }
90
+
91
+ // LoadConfig reads the .specforce/config.yaml file from the project root.
92
+ func LoadConfig(root string) *ProjectConfig {
93
+ config := &ProjectConfig{
94
+ Instructions: make(map[string][]string),
95
+ }
96
+
97
+ configPath, err := SecurePath(root, filepath.Join(".specforce", "config.yaml"))
98
+ if err != nil {
99
+ fmt.Fprintf(os.Stderr, "Warning: Security: %v\n", err)
100
+ return config
101
+ }
102
+
103
+ // #nosec G304 - Path is secured by SecurePath
104
+ data, err := os.ReadFile(configPath)
105
+ if err != nil {
106
+ if !os.IsNotExist(err) {
107
+ fmt.Fprintf(os.Stderr, "Warning: Failed to read config file at %s: %v\n", configPath, err)
108
+ }
109
+ return config
110
+ }
111
+
112
+ if err := yaml.Unmarshal(data, config); err != nil {
113
+ fmt.Fprintf(os.Stderr, "Warning: Malformed config file at %s: %v\n", configPath, err)
114
+ // Ensure we return an empty but non-nil Instructions map
115
+ config.Instructions = make(map[string][]string)
116
+ return config
117
+ }
118
+
119
+ if config.Instructions == nil {
120
+ config.Instructions = make(map[string][]string)
121
+ }
122
+
123
+ return config
124
+ }