feat: load docs from runtime git cache

Author: cmilesio

.gitignore

@@ -1,3 +1,4 @@
 IMPLEMENTATION.md
 AGENTS.md
-.idea
+.idea
+.atlas/

README.md

@@ -47,6 +47,26 @@ forj marketplace make:job sync-catalog
 
 ## Development
 
+```bash
+make build
+make release-check
+make test
+make vet
+```
+
+At runtime, Atlas reads docs from `GOFORJ_DOCS_PATH` when set. Otherwise it
+clones or refreshes `github.com/goforj/docs` in the user's cache directory,
+loads the Markdown tree into memory, and serves MCP docs tools from memory.
+Atlas uses the `git` executable when it is available and silently falls back to
+native Go git support when it is not.
+
+Atlas is consumed by GoForj as a Go module, not as a prebuilt binary. A release
+should run `make release-check`, tag the module, and then bump GoForj to that
+tag. The normal docs path is a local git cache loaded into memory by the MCP
+server, so Atlas does not need to commit a copied docs tree.
+
+Equivalent direct validation:
+
 ```bash
 GOCACHE=/tmp/gocache GOMODCACHE=/tmp/gomodcache go test ./...
 ```

docs/cache.go

@@ -0,0 +1,59 @@
+package docs
+
+import (
+	"context"
+	"errors"
+	"sync"
+)
+
+// CachingProvider loads docs once and serves them from memory afterward.
+type CachingProvider struct {
+	Provider Provider
+
+	mu        sync.Mutex
+	loaded    bool
+	manifest  Manifest
+	documents []Document
+}
+
+// Manifest returns cached docs metadata.
+func (p *CachingProvider) Manifest(ctx context.Context) (Manifest, error) {
+	if err := p.load(ctx); err != nil {
+		return Manifest{}, err
+	}
+	return p.manifest, nil
+}
+
+// Documents returns cached Markdown documents.
+func (p *CachingProvider) Documents(ctx context.Context) ([]Document, error) {
+	if err := p.load(ctx); err != nil {
+		return nil, err
+	}
+	return append([]Document(nil), p.documents...), nil
+}
+
+// load keeps docs retrieval fast after the first successful provider read.
+func (p *CachingProvider) load(ctx context.Context) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.loaded {
+		return nil
+	}
+
+	if p.Provider == nil {
+		return errors.New("docs provider is not configured")
+	}
+	documents, err := p.Provider.Documents(ctx)
+	if err != nil {
+		return err
+	}
+	manifest, err := p.Provider.Manifest(ctx)
+	if err != nil {
+		return err
+	}
+	p.documents = append([]Document(nil), documents...)
+	p.manifest = manifest
+	p.loaded = true
+	return nil
+}

docs/cache_test.go

@@ -0,0 +1,46 @@
+package docs
+
+import (
+	"context"
+	"testing"
+)
+
+func TestCachingProviderLoadsDocumentsOnce(t *testing.T) {
+	source := &countingProvider{
+		manifest: Manifest{Version: "test", Revision: "rev1"},
+		documents: []Document{
+			{Path: "index.md", Title: "Home", Content: "# Home\n"},
+		},
+	}
+	provider := &CachingProvider{Provider: source}
+
+	for i := 0; i < 3; i++ {
+		documents, err := provider.Documents(context.Background())
+		if err != nil {
+			t.Fatalf("documents: %v", err)
+		}
+		if len(documents) != 1 {
+			t.Fatalf("expected one document, got %d", len(documents))
+		}
+	}
+	if source.documentCalls != 1 {
+		t.Fatalf("expected one source document load, got %d", source.documentCalls)
+	}
+}
+
+type countingProvider struct {
+	manifest      Manifest
+	documents     []Document
+	manifestCalls int
+	documentCalls int
+}
+
+func (p *countingProvider) Manifest(context.Context) (Manifest, error) {
+	p.manifestCalls++
+	return p.manifest, nil
+}
+
+func (p *countingProvider) Documents(context.Context) ([]Document, error) {
+	p.documentCalls++
+	return p.documents, nil
+}

docs/fallback.go

@@ -0,0 +1,61 @@
+package docs
+
+import (
+	"context"
+	"errors"
+)
+
+// DefaultProvider returns Atlas docs using a local override or cached git docs.
+func DefaultProvider(version string) Provider {
+	providers := []Provider{}
+	if provider, ok := ProviderFromEnv(version); ok {
+		providers = append(providers, provider)
+	}
+	providers = append(providers, NewGitProvider(version))
+	return &CachingProvider{Provider: FallbackProvider{Providers: providers}}
+}
+
+// FallbackProvider tries docs providers in order until one returns documents.
+type FallbackProvider struct {
+	Providers []Provider
+}
+
+// Manifest returns metadata for the first provider that can return documents.
+func (p FallbackProvider) Manifest(ctx context.Context) (Manifest, error) {
+	provider, err := p.provider(ctx)
+	if err != nil {
+		return Manifest{}, err
+	}
+	return provider.Manifest(ctx)
+}
+
+// Documents returns documents from the first available provider.
+func (p FallbackProvider) Documents(ctx context.Context) ([]Document, error) {
+	provider, err := p.provider(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return provider.Documents(ctx)
+}
+
+// provider picks the first source with real documents so broken overrides do not hide git docs.
+func (p FallbackProvider) provider(ctx context.Context) (Provider, error) {
+	var lastErr error
+	for _, provider := range p.Providers {
+		if provider == nil {
+			continue
+		}
+		documents, err := provider.Documents(ctx)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		if len(documents) > 0 {
+			return provider, nil
+		}
+	}
+	if lastErr != nil {
+		return nil, lastErr
+	}
+	return nil, errors.New("no docs providers available")
+}

docs/fs.go

@@ -52,7 +52,7 @@ func (p FSProvider) Manifest(ctx context.Context) (Manifest, error) {
 
 // Documents loads Markdown documents from the provider root.
 func (p FSProvider) Documents(ctx context.Context) ([]Document, error) {
-	root, err := filepath.Abs(p.Root)
+	root, err := filepath.Abs(docsRoot(p.Root))
 	if err != nil {
 		return nil, err
 	}
@@ -113,3 +113,15 @@ func firstHeading(content string, fallback string) string {
 	}
 	return fallback
 }
+
+func docsRoot(root string) string {
+	if dirExists(filepath.Join(root, "docs")) {
+		return filepath.Join(root, "docs")
+	}
+	return root
+}
+
+func dirExists(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && info.IsDir()
+}