{"id":45523558,"url":"https://github.com/stacklok/toolhive-core","last_synced_at":"2026-02-22T23:28:50.844Z","repository":{"id":336045691,"uuid":"1147957313","full_name":"stacklok/toolhive-core","owner":"stacklok","description":"The ToolHive Platform common libraries and specs","archived":false,"fork":false,"pushed_at":"2026-02-17T14:59:28.000Z","size":144,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-17T15:49:03.130Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacklok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T12:08:32.000Z","updated_at":"2026-02-17T13:08:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stacklok/toolhive-core","commit_stats":null,"previous_names":["stacklok/toolhive-core"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/stacklok/toolhive-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacklok","download_url":"https://codeload.github.com/stacklok/toolhive-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29730668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T20:09:16.275Z","status":"ssl_error","status_checked_at":"2026-02-22T20:09:13.750Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-22T23:28:46.278Z","updated_at":"2026-02-22T23:28:50.834Z","avatar_url":"https://github.com/stacklok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# toolhive-core\n\nThe ToolHive Platform common libraries and specifications.\n\n`toolhive-core` provides stable, well-tested Go utilities with explicit API guarantees for the ToolHive ecosystem. Projects like [toolhive](https://github.com/stacklok/toolhive), [dockyard](https://github.com/stacklok/dockyard), [toolhive-registry](https://github.com/stacklok/toolhive-registry), and [toolhive-registry-server](https://github.com/stacklok/toolhive-registry-server) depend on this library for shared functionality.\n\n## Why toolhive-core?\n\nThe ToolHive ecosystem spans multiple Go repositories, and several of these projects need to share common utilities. Rather than having projects import internal packages from `toolhive` (which have no stability guarantees), `toolhive-core` provides:\n\n- **Stability guarantees**: Packages follow semantic versioning with explicit API commitments\n- **Clear maturity levels**: Each package is marked as Stable, Beta, or Alpha\n- **Tested and documented**: All packages meet minimum quality standards before inclusion\n- **Independent versioning**: Evolves on its own release cadence, decoupled from `toolhive` releases\n\n## Available Packages\n\n| Package | Stability | Description |\n|---------|-----------|-------------|\n| `cel` | Alpha | Generic CEL expression compilation and evaluation |\n| `env` | Stable | Environment variable abstraction with `Reader` interface |\n| `httperr` | Stable | Wrap errors with HTTP status codes |\n| `logging` | Alpha | Pre-configured `*slog.Logger` factory with consistent ToolHive defaults |\n| `oci/skills` | Alpha | OCI artifact types, media types, and registry operations for skills |\n| `recovery` | Beta | HTTP panic recovery middleware |\n| `validation/http` | Stable | RFC 7230/8707 compliant HTTP header and URI validation |\n| `validation/group` | Stable | Group name validation |\n\n## Package Stability Levels\n\nEach package is marked with a stability level:\n\n| Level | Meaning | API Guarantees |\n|-------|---------|----------------|\n| **Stable** | Production-ready, fully supported | No breaking changes without major version bump |\n| **Beta** | Feature-complete, may have minor changes | Breaking changes possible with deprecation notice |\n| **Alpha** | Experimental, subject to significant changes | No stability guarantees |\n\n## Graduation Criteria\n\nPackages in `toolhive-core` must meet formal criteria before inclusion. This ensures that shared packages are genuinely reusable, well-tested, and not tied to the internal workings of any specific project.\n\n### Guiding Principle\n\nPackages must provide genuinely reusable value and be designed as reusable from the start. A package that requires knowledge of toolhive internals to use correctly is not a good candidate for graduation.\n\n### Fast Track (Simple Packages)\n\nFor small, focused packages with minimal dependencies (e.g., `env`, `errors`, `validation`):\n\n| Criterion | Requirement |\n|-----------|-------------|\n| **Production usage** | Deployed in production for ≥1 month |\n| **No internal dependencies** | Cannot depend on non-graduated internal packages |\n| **No global state** | No singletons, global variables for state, or `init()` side effects |\n| **Test coverage** | ≥70% line coverage |\n| **Documentation** | Package-level godoc |\n| **Approval** | GitHub issue approved by one maintainer |\n\n### Standard Track (Complex Packages)\n\nFor packages with external dependencies, multiple types, or broader API surface:\n\n| Criterion | Requirement |\n|-----------|-------------|\n| **Production usage** | Deployed in production for ≥2 months without breaking changes |\n| **API stability** | No breaking changes in the last 2 minor releases |\n| **Interface design** | Uses Go interfaces for dependency injection and testability |\n| **Error handling** | Returns typed errors; no panics except for programming bugs |\n| **No global state** | No singletons, global variables for state, or `init()` side effects |\n| **Test coverage** | ≥70% line coverage with meaningful assertions |\n| **Documentation** | Package-level godoc with usage examples |\n| **Linting** | Passes `golangci-lint` with project configuration |\n| **Minimal dependencies** | Only essential external dependencies |\n| **No circular imports** | Must not create import cycles when extracted |\n| **No internal dependencies** | Cannot depend on non-graduated internal packages |\n| **Stable external deps** | External dependencies must be v1.0+ or widely adopted |\n| **Sponsorship** | At least one maintainer sponsors the graduation |\n| **Approval** | RFC or detailed GitHub issue reviewed and approved |\n\n### Graduation Process\n\n1. **Proposal**: Open a GitHub issue identifying the graduation candidate and proposed track (fast/standard)\n2. **Track determination**: Maintainers confirm which track applies based on package complexity\n3. **Evaluation**: Assess against the relevant track's criteria\n4. **Approval**: Fast track requires one maintainer approval; standard track requires RFC or detailed issue review\n5. **Extraction**: Move package to `toolhive-core` with necessary adaptations\n6. **Release**: Tag a new semver release of `toolhive-core`\n7. **Migration**: Update consuming projects to import from `toolhive-core`\n\n## Versioning\n\n`toolhive-core` follows [Semantic Versioning 2.0.0](https://semver.org/):\n\n- **Major (vX.0.0)**: Breaking API changes\n- **Minor (v0.X.0)**: New features, backward-compatible\n- **Patch (v0.0.X)**: Bug fixes, backward-compatible\n\n## License\n\nApache-2.0 - See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacklok%2Ftoolhive-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-core/lists"}