feat: language plugin architecture for multi-language support

Replace hardcoded per-language logic scattered across ~10 files with
a source-level plugin system. Each language (Go, Python, Java,
TypeScript) registers itself via init() and implements the
LanguagePlugin interface. The core framework iterates plugins for
derivation, display, unlink hints, scaffolding, and link operations.

Key changes:
- New internal/language/ package with plugin registry and interfaces
- Optional interfaces via type assertion: Scaffolder, PostGenHook,
  Linker, DocContributor
- Manifest/record schema: flat per-language fields replaced with
  Languages map[string]config.LanguageCoords
- Commands (unlink, gen, link, inspect, show, release) now iterate
  plugins instead of hardcoding per-language if-blocks
- Doc contribution system: plugins embed markdown fragments assembled
  by cmd/docgen into docs/_generated/ includes
- Developer guide (internal/language/CONTRIBUTING.md) for adding
  new language plugins

Author: daniel-garcia

.github/agents/copilot-instructions.md

@@ -37,4 +37,19 @@ Go 1.24: Follow standard conventions
 
 
 <!-- MANUAL ADDITIONS START -->
+
+## Language Plugin Architecture
+- Multi-language support uses a plugin system in `internal/language/`
+- Each language (Go, Python, Java, TypeScript) is a registered plugin implementing `LanguagePlugin` interface
+- Plugins self-register via `init()` — no central wiring needed
+- Optional interfaces: `Scaffolder`, `PostGenHook`, `Linker`, `DocContributor`
+- Plugins co-locate documentation fragments in `<lang>_doc/` directories
+- To add a new language, follow the step-by-step guide: `internal/language/CONTRIBUTING.md`
+- Generated doc includes live in `docs/_generated/` (never edit manually)
+- Build: `GOTOOLCHAIN=go1.26.1 go generate ./internal/language/...` regenerates doc includes
+- Manifest/record schema uses `Languages map[string]config.LanguageCoords` instead of flat per-language fields
+- Core derivation functions live in `internal/config/identity.go`; plugins wrap them
+- `language.DeriveAllCoords()` replaces the old `config.DeriveLanguageCoordsWithRoot()`
+- `language.FormatIdentityReport()` replaces the old `config.FormatIdentityReport()`
+
 <!-- MANUAL ADDITIONS END -->

.gitignore

@@ -20,6 +20,9 @@ go.work
 # APX binary in root directory only (not subdirectories)
 /apx
 
+# docgen binary (built by go generate)
+/docgen
+
 # Bin directory
 bin/*
 
@@ -65,6 +68,9 @@ env/
 # Sphinx build output
 docs/_build/
 
+# Generated doc includes (built by go generate / cmd/docgen)
+docs/_generated/
+
 # GoReleaser dist output
 dist/
 

CLAUDE.md

@@ -65,6 +65,12 @@ branchName := "release/" + normalizedPath
 - Business logic: `internal/` packages (independently testable)
 - User output: `internal/ui` package only
 - Error handling: always wrap with `fmt.Errorf("context: %w", err)`
+- Language plugins: `internal/language/` — plugin-based multi-language support
+  - Each language (Go, Python, Java, TypeScript) is a registered plugin implementing `LanguagePlugin`
+  - Adding a new language: see `internal/language/CONTRIBUTING.md`
+  - Doc fragments co-located with plugins in `<lang>_doc/` dirs, assembled by `cmd/docgen`
+  - Generated doc includes live in `docs/_generated/` (never edit manually)
+  - Build: `go generate ./internal/language/...` regenerates doc includes
 
 ## Vocabulary
 - `apx release` is the release pipeline (NOT `apx publish` — that was removed)

cmd/apx/commands/gen.go

@@ -2,8 +2,10 @@ package commands
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/infobloxopen/apx/internal/config"
+	"github.com/infobloxopen/apx/internal/language"
 	"github.com/infobloxopen/apx/internal/overlay"
 	"github.com/infobloxopen/apx/internal/ui"
 	"github.com/spf13/cobra"
@@ -22,9 +24,10 @@ func newGenCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "gen <lang> [path]",
 		Short: "Generate code",
-		Long:  "Generate code for the specified language.\nSupported languages: go, python, java",
-		Args:  cobra.RangeArgs(1, 2),
-		RunE:  genAction,
+		Long: fmt.Sprintf("Generate code for the specified language.\nSupported languages: %s",
+			strings.Join(language.Names(), ", ")),
+		Args: cobra.RangeArgs(1, 2),
+		RunE: genAction,
 	}
 	cmd.Flags().String("out", "", "output directory")
 	cmd.Flags().Bool("clean", false, "clean output directory before generation")
@@ -57,6 +60,9 @@ func genAction(cmd *cobra.Command, args []string) error {
 func generateCode(opts GenerateOptions) error {
 	ui.Info("Generating %s code from dependencies...", opts.Language)
 
+	// Look up the plugin for scaffolding / post-gen hooks.
+	plugin := language.Get(opts.Language)
+
 	dm := config.NewDependencyManager("apx.yaml", "apx.lock", "")
 	deps, err := dm.List()
 	if err != nil {
@@ -78,26 +84,47 @@ func generateCode(opts GenerateOptions) error {
 			return fmt.Errorf("failed to create overlay: %w", err)
 		}
 
-		// Scaffold Python packages when org is configured.
-		if opts.Language == "python" && cfg != nil && cfg.Org != "" {
+		// Run Scaffolder if the plugin implements it.
+		if scaffolder, ok := plugin.(language.Scaffolder); ok {
 			api, parseErr := config.ParseAPIID(dep.ModulePath)
 			if parseErr != nil {
 				return fmt.Errorf("parsing API ID %s: %w", dep.ModulePath, parseErr)
 			}
-			distName := config.DerivePythonDistName(cfg.Org, api)
-			importRoot := config.DerivePythonImport(cfg.Org, api)
-			if err := overlay.ScaffoldPythonPackage(ov.Path, distName, importRoot); err != nil {
-				return fmt.Errorf("scaffolding Python package for %s: %w", dep.ModulePath, err)
+			org := ""
+			importRoot := ""
+			if cfg != nil {
+				org = cfg.Org
+				importRoot = cfg.ImportRoot
+			}
+			ctx := language.DerivationContext{
+				SourceRepo: resolveSourceRepoFromConfig(cfg),
+				ImportRoot: importRoot,
+				Org:        org,
+				API:        api,
+			}
+			if ctx.Org != "" {
+				if err := scaffolder.Scaffold(ov.Path, ctx); err != nil {
+					return fmt.Errorf("scaffolding %s for %s: %w", opts.Language, dep.ModulePath, err)
+				}
 			}
 		}
 	}
 
-	if opts.Language == "go" {
-		if err := mgr.Sync(); err != nil {
-			return fmt.Errorf("failed to sync go.work: %w", err)
+	// Run PostGenHook if the plugin implements it.
+	if hook, ok := plugin.(language.PostGenHook); ok {
+		if err := hook.PostGen("."); err != nil {
+			return fmt.Errorf("post-generation hook for %s: %w", opts.Language, err)
 		}
 	}
 
 	ui.Success("Code generation completed successfully")
 	return nil
 }
+
+// resolveSourceRepoFromConfig builds the source repo string from a loaded config.
+func resolveSourceRepoFromConfig(cfg *config.Config) string {
+	if cfg != nil && cfg.Org != "" && cfg.Repo != "" {
+		return fmt.Sprintf("github.com/%s/%s", cfg.Org, cfg.Repo)
+	}
+	return "github.com/<org>/<repo>"
+}

cmd/apx/commands/inspect.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/infobloxopen/apx/internal/catalog"
 	"github.com/infobloxopen/apx/internal/config"
+	"github.com/infobloxopen/apx/internal/language"
 	"github.com/infobloxopen/apx/internal/ui"
 	"github.com/spf13/cobra"
 )
@@ -81,7 +82,17 @@ func inspectIdentityAction(cmd *cobra.Command, args []string) error {
 	importRoot := resolveImportRoot(cmd)
 	org := resolveOrg(cmd)
 
-	api, source, release, langs, err := config.BuildIdentityBlockWithRoot(apiID, sourceRepo, importRoot, org, lifecycle, "")
+	api, source, release, err := config.BuildIdentityBlock(apiID, sourceRepo, lifecycle, "")
+	if err != nil {
+		return err
+	}
+
+	langs, err := language.DeriveAllCoords(language.DerivationContext{
+		SourceRepo: sourceRepo,
+		ImportRoot: importRoot,
+		Org:        org,
+		API:        api,
+	})
 	if err != nil {
 		return err
 	}
@@ -113,7 +124,7 @@ func inspectIdentityAction(cmd *cobra.Command, args []string) error {
 		return printIdentityJSON(api, source, release, langs)
 	}
 
-	report := config.FormatIdentityReport(api, source, release, langs)
+	report := language.FormatIdentityReport(api, source, release, langs)
 	fmt.Print(report)
 
 	// Print catalog-enriched data
@@ -173,7 +184,17 @@ func inspectReleaseAction(cmd *cobra.Command, args []string) error {
 		lifecycle = "beta"
 	}
 
-	api, source, release, langs, err := config.BuildIdentityBlockWithRoot(apiID, sourceRepo, importRoot, org2, lifecycle, version)
+	api, source, release, err := config.BuildIdentityBlock(apiID, sourceRepo, lifecycle, version)
+	if err != nil {
+		return err
+	}
+
+	langs, err := language.DeriveAllCoords(language.DerivationContext{
+		SourceRepo: sourceRepo,
+		ImportRoot: importRoot,
+		Org:        org2,
+		API:        api,
+	})
 	if err != nil {
 		return err
 	}
@@ -183,7 +204,7 @@ func inspectReleaseAction(cmd *cobra.Command, args []string) error {
 		return printIdentityJSON(api, source, release, langs)
 	}
 
-	report := config.FormatIdentityReport(api, source, release, langs)
+	report := language.FormatIdentityReport(api, source, release, langs)
 	fmt.Print(report)
 	return nil
 }

cmd/apx/commands/link.go

@@ -2,119 +2,72 @@ package commands
 
 import (
 	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
+	"strings"
 
-	"github.com/infobloxopen/apx/internal/config"
-	"github.com/infobloxopen/apx/internal/overlay"
+	"github.com/infobloxopen/apx/internal/language"
 	"github.com/infobloxopen/apx/internal/ui"
 	"github.com/spf13/cobra"
 )
 
 func newLinkCmd() *cobra.Command {
+	// Build supported languages dynamically from plugins that implement Linker.
+	var linkable []string
+	for _, p := range language.All() {
+		if _, ok := p.(language.Linker); ok {
+			linkable = append(linkable, p.Name())
+		}
+	}
+	supported := strings.Join(linkable, ", ")
+
 	cmd := &cobra.Command{
 		Use:   "link <language> [module-path]",
 		Short: "Link overlays for local development",
-		Long: `Link generated overlays for local development.
+		Long: fmt.Sprintf(`Link generated overlays for local development.
 
 For Python: runs 'pip install -e' for each overlay in the active virtualenv.
 For Go: use 'apx sync' instead (Go uses go.work overlays).
 
+Supported languages: %s
+
 Examples:
   apx link python                              # link all Python overlays
-  apx link python proto/payments/ledger/v1     # link a specific overlay`,
+  apx link python proto/payments/ledger/v1     # link a specific overlay`, supported),
 		Args: cobra.RangeArgs(1, 2),
 		RunE: linkAction,
 	}
 	return cmd
 }
 
+func linkableNames() []string {
+	var names []string
+	for _, p := range language.All() {
+		if _, ok := p.(language.Linker); ok {
+			names = append(names, p.Name())
+		}
+	}
+	return names
+}
+
 func linkAction(cmd *cobra.Command, args []string) error {
 	lang := args[0]
 	var filterPath string
 	if len(args) > 1 {
 		filterPath = args[1]
 	}
 
-	switch lang {
-	case "go":
-		ui.Info("Go uses go.work overlays — run 'apx sync' instead.")
-		return nil
-	case "python":
-		return linkPython(filterPath)
-	default:
-		return fmt.Errorf("unsupported language for link: %s (supported: python)", lang)
-	}
-}
-
-func linkPython(filterPath string) error {
-	venv := os.Getenv("VIRTUAL_ENV")
-	if venv == "" {
-		return fmt.Errorf("no active virtualenv detected (VIRTUAL_ENV is not set)\nActivate a virtualenv first: source .venv/bin/activate")
-	}
-
-	pip := pipPath(venv)
-	if _, err := os.Stat(pip); os.IsNotExist(err) {
-		return fmt.Errorf("pip not found at %s — is the virtualenv valid?", pip)
-	}
-
-	mgr := overlay.NewManager(".")
-	overlays, err := mgr.List()
-	if err != nil {
-		return fmt.Errorf("listing overlays: %w", err)
-	}
-
-	linked := 0
-	for _, ov := range overlays {
-		if ov.Language != "python" {
-			continue
-		}
-		if filterPath != "" && ov.ModulePath != filterPath {
-			continue
-		}
-
-		// Only link overlays that have a pyproject.toml (scaffolded).
-		pyproject := filepath.Join(ov.Path, "pyproject.toml")
-		if _, err := os.Stat(pyproject); os.IsNotExist(err) {
-			ui.Warning("Skipping %s — no pyproject.toml (run 'apx gen python' first)", ov.ModulePath)
-			continue
-		}
-
-		ui.Info("Linking %s ...", ov.ModulePath)
-		installCmd := exec.Command(pip, "install", "-e", ov.Path)
-		installCmd.Env = os.Environ()
-		installCmd.Stdout = os.Stdout
-		installCmd.Stderr = os.Stderr
-		if err := installCmd.Run(); err != nil {
-			return fmt.Errorf("pip install -e failed for %s: %w", ov.ModulePath, err)
-		}
-		linked++
+	plugin := language.Get(lang)
+	if plugin == nil {
+		return fmt.Errorf("unknown language %q (supported: %s)", lang, strings.Join(language.Names(), ", "))
 	}
 
-	if filterPath != "" && linked == 0 {
-		// Check if the user needs to run gen first.
-		cfg, _ := config.Load("")
-		if cfg != nil && cfg.Org != "" {
-			return fmt.Errorf("no Python overlay found for %s — run 'apx gen python' first", filterPath)
+	linker, ok := plugin.(language.Linker)
+	if !ok {
+		if lang == "go" {
+			ui.Info("%s does not support 'link'. Use 'apx sync' for Go overlays.", lang)
+			return nil
 		}
-		return fmt.Errorf("no Python overlay found for %s — ensure org is configured in apx.yaml and run 'apx gen python'", filterPath)
-	}
-
-	if linked == 0 {
-		ui.Info("No Python overlays to link. Run 'apx gen python' first.")
-		return nil
+		return fmt.Errorf("unsupported language %q for link (supported: %s)", lang, strings.Join(linkableNames(), ", "))
 	}
 
-	ui.Success("Linked %d Python overlay(s) in editable mode", linked)
-	return nil
-}
-
-// pipPath returns the platform-appropriate path to pip inside a virtualenv.
-func pipPath(venvDir string) string {
-	if runtime.GOOS == "windows" {
-		return filepath.Join(venvDir, "Scripts", "pip.exe")
-	}
-	return filepath.Join(venvDir, "bin", "pip")
+	return linker.Link(".", filterPath)
 }