Registry

Registry Protocol

Registries are OPTIONAL. They provide package discovery, search, and version resolution. No central authority is required; users MAY configure multiple registries, and registries are additive.

Registry Index Format

A registry is a JSON file hosted at any URL. The file contains a package index:

{
  "registry_version": 1,
  "name": "community-packages",
  "url": "https://registry.example.com/index.json",
  "packages": [
    {
      "name": "api-testing",
      "version": "1.0.0",
      "description": "Skills and tools for API testing workflows.",
      "author": {
        "name": "Example Org"
      },
      "url": "https://registry.example.com/packages/api-testing-1.0.0.ccpkg",
      "checksum": "sha256:a1b2c3d4...",
      "tags": ["api", "testing", "openapi"],
      "published_at": "2026-02-14T12:00:00Z",
      "downloads": 1234,
      "verified": true
    }
  ]
}

Registry index fields:

Field	Required	Type	Description
registry_version	REQUIRED	number	Schema version. Currently 1.
name	REQUIRED	string	Human-readable registry name.
url	REQUIRED	string	Canonical URL of this registry index.
packages	REQUIRED	array	Array of package entries.

Package entry fields:

Field	Required	Type	Description
name	REQUIRED	string	Package name.
version	REQUIRED	string	Package version (semver).
description	REQUIRED	string	Package description.
author	REQUIRED	object	Author object (same schema as manifest).
url	REQUIRED	string	Download URL for the .ccpkg archive.
checksum	REQUIRED	string	SHA-256 checksum of the archive.
tags	OPTIONAL	string[]	Searchable tags.
published_at	OPTIONAL	string	ISO 8601 publication timestamp.
downloads	OPTIONAL	number	Download count.
verified	OPTIONAL	boolean	Whether the registry has verified the package.

Registry Configuration

Users configure registries in their host settings:

{
  "ccpkg": {
    "registries": [
      "https://registry.example.com/index.json",
      "https://my-team.github.io/packages/index.json"
    ]
  }
}

Resolution Behavior

When a user installs a package by name (e.g., ccpkg install api-testing):

1. The installer queries all configured registries.
2. Matching packages are collected across registries.
3. If multiple versions match, the highest semver version is selected.
4. If the same name and version appear in multiple registries, the first registry in the configuration list takes precedence.

Registry URLs MUST use HTTPS (see Transport Security).

Version Discovery

Registries SHOULD provide a version endpoint that enables efficient update checking without downloading the full index.

Version endpoint format:

A registry MAY expose per-package version information at a predictable URL derived from the registry base URL:

{registry-base-url}/packages/{name}/versions.json

Response schema:

{
  "name": "api-testing",
  "latest": "2.1.0",
  "versions": [
    {
      "version": "2.1.0",
      "published_at": "2026-03-01T12:00:00Z",
      "checksum": "sha256:...",
      "url": "https://..."
    },
    {
      "version": "2.0.0",
      "published_at": "2026-02-15T12:00:00Z",
      "checksum": "sha256:...",
      "url": "https://..."
    }
  ]
}

Field	Required	Type	Description
name	REQUIRED	string	Package name
latest	REQUIRED	string	Latest stable version (semver)
versions	REQUIRED	array	All published versions, newest first

Each version entry uses the same fields as a registry package entry.

Registries SHOULD support ETag and If-None-Match headers to enable efficient polling. An installer that checks for updates SHOULD cache responses and use conditional requests to minimize bandwidth.

Security Advisories

Registries MAY publish security advisories for packages. An advisory indicates that one or more versions of a package have a known vulnerability.

Advisory endpoint format:

{registry-base-url}/advisories.json

Response schema:

{
  "advisories": [
    {
      "id": "CCPKG-2026-001",
      "package": "vulnerable-pkg",
      "affected_versions": "<1.2.3",
      "severity": "high",
      "title": "Command injection in hook script",
      "description": "...",
      "fixed_in": "1.2.3",
      "published_at": "2026-03-01T00:00:00Z",
      "url": "https://..."
    }
  ]
}

Field	Required	Type	Description
id	REQUIRED	string	Unique advisory identifier
package	REQUIRED	string	Affected package name
affected_versions	REQUIRED	string	Semver range of affected versions
severity	REQUIRED	string	One of: critical, high, medium, low
title	REQUIRED	string	Short description of the vulnerability
description	OPTIONAL	string	Detailed description
fixed_in	OPTIONAL	string	Version that fixes the vulnerability
published_at	REQUIRED	string	ISO 8601 timestamp
url	OPTIONAL	string	Link to full advisory details

Installers that support update discovery SHOULD check the advisory endpoint and SHOULD surface advisories affecting installed packages. The urgency of notification is an implementation concern.