Skip to main content

Adapter Architecture

Adapters provide a unified interface for fetching bundles from different source types.

IRepositoryAdapter Interface​

interface IRepositoryAdapter {
    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;
    forceAuthentication?(): Promise<void>;
}

Adapter Types​

AdapterSource TypeInstallation MethodStatus
GitHubAdaptergithubURL-based (getDownloadUrl)Active
LocalAdapterlocalBuffer-based (downloadBundle)Active
AwesomeCopilotAdapterawesome-copilotBuffer-based (builds zip on-the-fly)Active
LocalAwesomeCopilotAdapterlocal-awesome-copilotBuffer-basedActive
ApmAdapterapmURL-basedActive
LocalApmAdapterlocal-apmBuffer-basedActive

Source types are defined in src/types/registry.ts:

export type SourceType = 'github' | 'local' | 
    'awesome-copilot' | 'local-awesome-copilot' | 'apm' | 'local-apm';

Two Installation Paths​

URL-Based (install()):

  • Pre-packaged zip bundles on remote servers
  • Direct download from URL
  • Used by: GitHub, AwesomeCopilot

Buffer-Based (installFromBuffer()):

  • Dynamically created bundles
  • Builds zip in memory
  • Used by: AwesomeCopilot, Local

Adding a New Adapter​

// 1. Extend RepositoryAdapter base class
export class MyAdapter extends RepositoryAdapter {
    readonly type = 'my-type';
    
    async fetchBundles(): Promise<Bundle[]> { /* ... */ }
    async downloadBundle(bundle: Bundle): Promise<Buffer> { /* ... */ }
    async fetchMetadata(): Promise<SourceMetadata> { /* ... */ }
    async validate(): Promise<ValidationResult> { /* ... */ }
    getManifestUrl(bundleId: string, version?: string): string { /* ... */ }
    getDownloadUrl(bundleId: string, version?: string): string { /* ... */ }
}

// 2. Register in factory
RepositoryAdapterFactory.register('my-type', MyAdapter);

// 3. Add to SourceType union in src/types/registry.ts
export type SourceType = 'github' | 'local' | 
    'awesome-copilot' | 'local-awesome-copilot' | 'apm' | 'local-apm' | 'my-type';

See Also​