SourceAdapter API Reference

AI Primitives Hub normalizes collection sources through the SourceAdapter port in packages/core/src/ports/source-adapter.ts. Concrete implementations live in packages/infra/src/adapters/ and are constructed by packages/app/src/registry/create-source-adapter.ts.

The repository does not currently expose runtime registration of arbitrary third-party adapter classes. Supporting another source type requires a code change to the shared packages.

Interface

interface SourceAdapter {
  readonly type: string;
  readonly source: RegistrySource;

  fetchBundles(): Promise<Bundle[]>;
  downloadBundle(bundle: Bundle): Promise<Buffer>;
  fetchMetadata(): Promise<SourceMetadata>;
  validate(): Promise<ValidationResult>;
  requiresAuthentication(): boolean;
  getManifestUrl(bundleId: string, version?: string): string;
  getDownloadUrl(bundleId: string, version?: string): string;
  downloadReadme(bundle: Bundle): Promise<string | null>;
  forceAuthentication?(): Promise<void>;
}

Method Semantics

Member	Current contract
`type`	Source-type identifier handled by the adapter
`source`	Normalized source configuration used to construct the adapter
`fetchBundles`	Return normalized bundle metadata available from the source
`downloadBundle`	Return the installable archive as a `Buffer`
`fetchMetadata`	Return source-level display and diagnostic metadata
`validate`	Return user-facing source validation details
`requiresAuthentication`	Indicate whether the configured source normally requires credentials
`getManifestUrl`	Return a URL/path for display or diagnostics
`getDownloadUrl`	Return a URL/path for display or diagnostics
`downloadReadme`	Return bundle README text, or `null` when unavailable
`forceAuthentication`	Optionally trigger delivery-supported reauthentication

downloadBundle is the installation boundary for every adapter. Even when a remote source exposes a ready-made ZIP URL, the adapter downloads it and returns a buffer. The URL methods do not create a separate URL-based install pipeline.

Built-in Implementations

Source type	Implementation
`github`	`GitHubAdapter`
`local`	`LocalAdapter`
`awesome-copilot`	`AwesomeCopilotAdapter`
`local-awesome-copilot`	`LocalAwesomeCopilotAdapter`
`apm`	`ApmAdapter`
`local-apm`	`LocalApmAdapter`
`skills`	`SkillsAdapter`
`local-skills`	`LocalSkillsAdapter`
`azure-devops`	`AzureDevOpsAdapter`

The registry source union is broader than the Hub configuration schema. See Hub Schema before using a source type in hub-config.yml.

Factory Dependencies

createSourceAdapter requires delivery-provided implementations of:

interface SourceAdapterFactoryDeps {
  fs: FileSystem;
  clock: Clock;
  httpClient: HttpClient;
  processRunner: ProcessRunner;
  fallbackTokenProviders: readonly TokenProvider[];
}

This keeps VS Code and Node/CLI details outside the domain and infrastructure implementations.

For sources with credentials, an explicit source.token is placed before the delivery fallbacks in a CompositeTokenProvider. GitHub-hosted adapters receive a GitHubApiClient; Azure DevOps receives an AzureDevOpsApiClient.

HTTP Redirect Policy

HttpClient.fetch follows redirects by default. Set HttpRequest.followRedirects to false when an adapter needs to inspect a redirect response before sending another request. HTTP implementations must return that response, its Location header, and the requested finalUrl without following the redirect. maxRedirects continues to limit automatic redirect handling when following is enabled.

ArtifactoryHttpClient uses this mode to check every redirect destination against the configured origin and source path before forwarding credentials. Its redirect chains are limited to 10 hops, and path-confinement failures are not retried.

Adding an Adapter in This Repository

Extend the source type and configuration in packages/core.
Implement SourceAdapter in packages/infra/src/adapters/.
Export it from the infra adapter index.
Add the construction case to createSourceAdapter in packages/app.
Add tests for the adapter and factory case.
Update source configuration documentation.
Update the Hub schema separately if Hubs should accept the new type.

Do not register the adapter in an extension-only factory. Both delivery layers use the shared application factory.

Interface​

Method Semantics​

Built-in Implementations​

Factory Dependencies​

HTTP Redirect Policy​

Adding an Adapter in This Repository​

See Also​