🏗️ Dual SDK architecture

Composer Skills isn't one SDK — it's two packaged in the same module. They solve different problems, take different underlying paths, and have different runtime requirements. Understanding their boundaries is essential to using this project well.

🌐 vs 🛠️ Two SDKs at a glance

	🌐 Packagist API SDK	🛠️ Composer CLI SDK
Package path	pkg/client, pkg/repository	pkg/composer
Underlying mechanism	HTTP calls to Packagist REST API	Executes local composer binary (os/exec)
Needs PHP?	❌ No (pure Go)	✅ Yes (PHP 7.4+)
Needs Composer?	❌ No	✅ Yes (Composer 2.0+, can auto-install)
Data source	Packagist server (remote)	Local PHP project (composer.json/composer.lock)
Methods	20	234
Typical use	Search packages, view statistics, pull advisories	Install/update dependencies, local audits, manage projects

🌐 Packagist API SDK

Package path: github.com/scagogogo/composer-skills/pkg/client

It's a set of typed HTTP clients that communicate directly with Packagist servers. Return values are Go structs; it doesn't touch the local PHP environment.

c := client.NewComposerClient(30 * time.Second)

// Remote search
results, _ := c.SearchPackages("logging", 10, 1)

// Remote package details
pkg, _ := c.GetPackage("monolog/monolog")

// Remote security advisories (repository-wide)
advisories, _ := c.GetSecurityAdvisories()

// Site-wide statistics
stats, _ := c.GetStatistics()

pkg/repository provides higher-level repository operation wrappers on top of client, suited for building package mirrors, index downloads, and similar use cases.

When to pick it

• Your program runs in an environment without PHP (pure Go services, CI runners, Lambda).
• You need global Packagist data, not a specific local project's state.
• You're only querying, not modifying (search, statistics, advisories).

🛠️ Composer CLI SDK

Package path: github.com/scagogogo/composer-skills/pkg/composer

It uses os/exec to invoke the local composer executable, wrapping all standard Composer subcommands (234 methods across 20 categories). All operations target a specific local PHP project (set via SetWorkingDir).

comp, _ := composer.New(composer.DefaultOptions())
comp.SetWorkingDir("/path/to/php/project")

// Local dependency management
comp.Install(false, true)
comp.RequirePackage("monolog/monolog", "^3.0", false)

// Local security audit (against the project's installed dependencies)
result, _ := comp.AuditWithJSON()

// Local package inspection
tree, _ := comp.ShowDependencyTree("symfony/console")

When to pick it

• You're operating on a real PHP project (install, update, audit, scripts).
• You need structured info from the local composer.json / composer.lock.
• You're doing DevOps automation: detect environment, install Composer, run install, validate schema.

🤔 Which one to use?

A simple rule of thumb: Where does the data come from?

• Data comes from Packagist server ("what logging packages exist in the world?", "are there new advisories for monolog?") → use 🌐 Packagist API SDK.
• Data comes from local project ("what dependencies does this project have?", "does this project have vulnerabilities?", "install dependencies") → use 🛠️ Composer CLI SDK.

They are often used together. For example, a security scanner might:

1. Use 🌐 client.GetSecurityAdvisories() to pull all remote advisories.
2. Use 🛠️ comp.GetDirectDependencyNames() to get the local project's dependency list.
3. Cross-reference them in Go and output "specific vulnerabilities affecting this project".

📊 Capability comparison cheat sheet

Capability	🌐 Packagist API	🛠️ Composer CLI
Search packages	✅ SearchPackages	✅ Search
Package details	✅ GetPackage	✅ ShowPackage
Security advisories	✅ GetSecurityAdvisories (repo-wide)	✅ AuditWithJSON (this project only)
Statistics	✅ GetStatistics	❌
Install/update dependencies	❌	✅ Install/Update
Dependency tree / why	❌	✅ ShowDependencyTree/WhyPackage
Outdated packages	❌	✅ OutdatedPackages
Create project / scripts	❌	✅ CreateProject/RunScript
composer.json read/write	❌	✅ ReadComposerJSON/WriteComposerJSON

Difference in security advisories

GetSecurityAdvisories (Packagist API) returns a repository-wide advisory feed; AuditWithJSON (Composer CLI) audits only the currently installed dependencies in this project. They complement each other and are not interchangeable.

🧭 Next steps

• 🌐 Packagist API SDK overview — detailed documentation for 20 API methods.
• 🛠️ Composer CLI SDK overview — 234 methods indexed by category.
• 🔧 Auto-install mechanism — how the Composer CLI SDK auto-provisions Composer when missing.
• 🧪 Typed return values — shared structured return design across both SDKs.