opencode-ext-connector 0.3.0

package/dist/core/errors.d.ts

@@ -0,0 +1,57 @@
+import type { ProviderId } from "./ids";
+export type ConnectorErrorCode = "invalid-argument" | "operation-cancelled" | "deadline-exceeded" | "resource-disposed" | "adapter-error" | "http-transport-error" | "process-supervisor-error";
+type ConnectorErrorOptions = {
+    readonly code: ConnectorErrorCode;
+    readonly retryable: boolean;
+    readonly cause: unknown | null;
+};
+export declare abstract class ConnectorError extends Error {
+    readonly code: ConnectorErrorCode;
+    readonly retryable: boolean;
+    readonly cause: unknown | null;
+    protected constructor(message: string, options: ConnectorErrorOptions);
+}
+export declare class InvalidArgumentError extends ConnectorError {
+    readonly argument: string;
+    readonly name = "InvalidArgumentError";
+    constructor(argument: string, cause?: unknown | null);
+}
+export declare class OperationCancelledError extends ConnectorError {
+    readonly operation: string;
+    readonly name = "OperationCancelledError";
+    constructor(operation: string);
+}
+export declare class DeadlineExceededError extends ConnectorError {
+    readonly timeoutMs: number;
+    readonly name = "DeadlineExceededError";
+    constructor(timeoutMs: number);
+}
+export declare class ResourceDisposedError extends ConnectorError {
+    readonly resource: string;
+    readonly name = "ResourceDisposedError";
+    constructor(resource: string);
+}
+type InfrastructureErrorOptions = {
+    readonly operation: string;
+    readonly retryable: boolean;
+    readonly cause: unknown | null;
+};
+export declare class AdapterError extends ConnectorError {
+    readonly name = "AdapterError";
+    readonly operation: string;
+    readonly providerId: ProviderId | null;
+    constructor(options: InfrastructureErrorOptions & {
+        readonly providerId: ProviderId | null;
+    });
+}
+export declare class HttpTransportError extends ConnectorError {
+    readonly name = "HttpTransportError";
+    readonly operation: string;
+    constructor(options: InfrastructureErrorOptions);
+}
+export declare class ProcessSupervisorError extends ConnectorError {
+    readonly name = "ProcessSupervisorError";
+    readonly operation: string;
+    constructor(options: InfrastructureErrorOptions);
+}
+export {};

package/dist/core/errors.js

@@ -0,0 +1,81 @@
+export class ConnectorError extends Error {
+    code;
+    retryable;
+    cause;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.code = options.code;
+        this.retryable = options.retryable;
+        this.cause = options.cause;
+    }
+}
+export class InvalidArgumentError extends ConnectorError {
+    argument;
+    name = "InvalidArgumentError";
+    constructor(argument, cause = null) {
+        super("invalid connector argument", { code: "invalid-argument", retryable: false, cause });
+        this.argument = argument;
+    }
+}
+export class OperationCancelledError extends ConnectorError {
+    operation;
+    name = "OperationCancelledError";
+    constructor(operation) {
+        super("connector operation cancelled", {
+            code: "operation-cancelled",
+            retryable: false,
+            cause: null,
+        });
+        this.operation = operation;
+    }
+}
+export class DeadlineExceededError extends ConnectorError {
+    timeoutMs;
+    name = "DeadlineExceededError";
+    constructor(timeoutMs) {
+        super("connector deadline exceeded", {
+            code: "deadline-exceeded",
+            retryable: true,
+            cause: null,
+        });
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class ResourceDisposedError extends ConnectorError {
+    resource;
+    name = "ResourceDisposedError";
+    constructor(resource) {
+        super("connector resource disposed", {
+            code: "resource-disposed",
+            retryable: false,
+            cause: null,
+        });
+        this.resource = resource;
+    }
+}
+export class AdapterError extends ConnectorError {
+    name = "AdapterError";
+    operation;
+    providerId;
+    constructor(options) {
+        super("provider adapter failed", { code: "adapter-error", ...options });
+        this.operation = options.operation;
+        this.providerId = options.providerId;
+    }
+}
+export class HttpTransportError extends ConnectorError {
+    name = "HttpTransportError";
+    operation;
+    constructor(options) {
+        super("HTTP transport failed", { code: "http-transport-error", ...options });
+        this.operation = options.operation;
+    }
+}
+export class ProcessSupervisorError extends ConnectorError {
+    name = "ProcessSupervisorError";
+    operation;
+    constructor(options) {
+        super("process supervisor failed", { code: "process-supervisor-error", ...options });
+        this.operation = options.operation;
+    }
+}

package/dist/core/health.d.ts

@@ -0,0 +1,22 @@
+export type HealthPolicy = {
+    readonly initialBackoffMs: number;
+    readonly maximumBackoffMs: number;
+};
+export type HealthState = {
+    readonly status: "unknown" | "ready" | "stale" | "unavailable";
+    readonly consecutiveFailures: number;
+    readonly retryAtMs: number | null;
+};
+export type HealthEvent = {
+    readonly status: "ready";
+    readonly atMs: number;
+} | {
+    readonly status: "stale";
+    readonly atMs: number;
+} | {
+    readonly status: "unavailable";
+    readonly atMs: number;
+};
+export declare function createInitialHealthState(): HealthState;
+export declare function calculateBackoffMs(failures: number, policy: HealthPolicy): number;
+export declare function reduceHealth(state: HealthState, event: HealthEvent, policy: HealthPolicy): HealthState;

package/dist/core/health.js

@@ -0,0 +1,30 @@
+export function createInitialHealthState() {
+    return { status: "unknown", consecutiveFailures: 0, retryAtMs: null };
+}
+export function calculateBackoffMs(failures, policy) {
+    if (failures <= 0) {
+        return 0;
+    }
+    let delay = Math.min(policy.initialBackoffMs, policy.maximumBackoffMs);
+    let remainingFailures = failures - 1;
+    while (remainingFailures > 0 && delay < policy.maximumBackoffMs) {
+        delay = Math.min(delay * 2, policy.maximumBackoffMs);
+        remainingFailures -= 1;
+    }
+    return delay;
+}
+export function reduceHealth(state, event, policy) {
+    switch (event.status) {
+        case "ready":
+            return { status: "ready", consecutiveFailures: 0, retryAtMs: null };
+        case "stale":
+        case "unavailable": {
+            const consecutiveFailures = state.consecutiveFailures + 1;
+            return {
+                status: event.status,
+                consecutiveFailures,
+                retryAtMs: event.atMs + calculateBackoffMs(consecutiveFailures, policy),
+            };
+        }
+    }
+}

package/dist/core/http.d.ts

@@ -0,0 +1,28 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type HttpHeaders = {
+    readonly [name: string]: string;
+};
+export type HttpRequest = {
+    readonly method: HttpMethod;
+    readonly url: string;
+    readonly headers: HttpHeaders;
+    readonly body: Uint8Array | null;
+};
+export type HttpResponse = {
+    readonly status: number;
+    readonly statusText?: string;
+    readonly headers: HttpHeaders;
+    readonly body: Uint8Array;
+    readonly bodyPresent?: boolean;
+};
+export type HttpStreamResponse = {
+    readonly status: number;
+    readonly statusText?: string;
+    readonly headers: HttpHeaders;
+    readonly body: AsyncIterable<Uint8Array>;
+    readonly bodyPresent?: boolean;
+};
+export interface HttpTransport {
+    request(request: HttpRequest, signal: AbortSignal): Promise<HttpResponse>;
+    stream?(request: HttpRequest, signal: AbortSignal): Promise<HttpStreamResponse>;
+}

package/dist/core/http.js

@@ -0,0 +1 @@
+export {};

package/dist/core/ids.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const ProviderIdSchema: z.core.$ZodBranded<z.ZodString, "ProviderId">;
+export type ProviderId = z.output<typeof ProviderIdSchema>;
+export declare const ModelIdSchema: z.core.$ZodBranded<z.ZodString, "ModelId">;
+export type ModelId = z.output<typeof ModelIdSchema>;
+export declare function parseProviderId(input: unknown): ProviderId;
+export declare function parseModelId(input: unknown): ModelId;

package/dist/core/ids.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export const ProviderIdSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+    .brand();
+export const ModelIdSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .refine((value) => [...value].every((character) => {
+    const codePoint = character.codePointAt(0);
+    return codePoint !== undefined && codePoint >= 32 && codePoint !== 127;
+}))
+    .refine((value) => value.trim() === value)
+    .brand();
+export function parseProviderId(input) {
+    return ProviderIdSchema.parse(input);
+}
+export function parseModelId(input) {
+    return ModelIdSchema.parse(input);
+}

package/dist/core/lifecycle.d.ts

@@ -0,0 +1,4 @@
+export interface AsyncDisposableHandle extends AsyncDisposable {
+    dispose(): Promise<void>;
+}
+export declare function createAsyncDisposable(cleanup: () => void | Promise<void>): AsyncDisposableHandle;

package/dist/core/lifecycle.js

@@ -0,0 +1,16 @@
+export function createAsyncDisposable(cleanup) {
+    let disposal;
+    const dispose = () => {
+        if (disposal !== undefined) {
+            return disposal;
+        }
+        const deferred = Promise.withResolvers();
+        disposal = deferred.promise;
+        Promise.resolve().then(cleanup).then(deferred.resolve, deferred.reject);
+        return disposal;
+    };
+    return {
+        dispose,
+        [Symbol.asyncDispose]: dispose,
+    };
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,21 @@
+import type { Clock } from "./clock";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogValue = null | boolean | number | string | readonly LogValue[] | {
+    readonly [key: string]: LogValue;
+};
+export type LogFields = {
+    readonly [key: string]: LogValue;
+};
+export type LogRecord = {
+    readonly timestampMs: number;
+    readonly level: LogLevel;
+    readonly event: string;
+    readonly fields: LogFields;
+};
+export interface LogSink {
+    write(record: LogRecord): void;
+}
+export interface ConnectorLogger {
+    log(level: LogLevel, event: string, fields: LogFields): void;
+}
+export declare function createConnectorLogger(clock: Clock, sink: LogSink): ConnectorLogger;

package/dist/core/logger.js

@@ -0,0 +1,61 @@
+const REDACTED = "[REDACTED]";
+const SENSITIVE_KEYS = new Set([
+    "authorization",
+    "cookie",
+    "setcookie",
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "access",
+    "refresh",
+    "expires",
+    "apikey",
+    "password",
+    "secret",
+]);
+function isLogArray(value) {
+    return Array.isArray(value);
+}
+function sanitizeUrl(value) {
+    if (!URL.canParse(value)) {
+        return value;
+    }
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        return value;
+    }
+    if (url.username.length > 0)
+        url.username = REDACTED;
+    if (url.password.length > 0)
+        url.password = REDACTED;
+    const queryNames = [...url.searchParams.keys()];
+    if (queryNames.length > 0) {
+        url.search = "";
+        for (const name of queryNames)
+            url.searchParams.append(name, REDACTED);
+    }
+    return url.toString();
+}
+function sanitizeValue(value) {
+    if (typeof value === "string") {
+        return sanitizeUrl(value);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (isLogArray(value)) {
+        return value.map(sanitizeValue);
+    }
+    return sanitizeFields(value);
+}
+function sanitizeFields(fields) {
+    return Object.fromEntries(Object.entries(fields).map(([key, value]) => {
+        const normalizedKey = key.toLowerCase().replaceAll("-", "").replaceAll("_", "");
+        return [key, SENSITIVE_KEYS.has(normalizedKey) ? REDACTED : sanitizeValue(value)];
+    }));
+}
+export function createConnectorLogger(clock, sink) {
+    return {
+        log: (level, event, fields) => sink.write({ timestampMs: clock.nowMs(), level, event, fields: sanitizeFields(fields) }),
+    };
+}

package/dist/core/models.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { ModelId, ProviderId } from "./ids";
+export type AdapterModelInput = {
+    readonly id: string;
+};
+export type AdapterModel = {
+    readonly id: ModelId;
+};
+export type ProviderFailureReason = "adapter-error" | "transport-error" | "process-error" | "invalid-data";
+export type ProviderSnapshotInput = {
+    readonly status: "ready";
+    readonly providerId: string;
+    readonly models: readonly AdapterModelInput[];
+} | {
+    readonly status: "stale";
+    readonly providerId: string;
+    readonly models: readonly AdapterModelInput[];
+    readonly reason: ProviderFailureReason;
+} | {
+    readonly status: "unavailable";
+    readonly providerId: string;
+    readonly reason: ProviderFailureReason;
+};
+export type ProviderSnapshot = {
+    readonly status: "ready";
+    readonly providerId: ProviderId;
+    readonly models: readonly AdapterModel[];
+} | {
+    readonly status: "stale";
+    readonly providerId: ProviderId;
+    readonly models: readonly AdapterModel[];
+    readonly reason: ProviderFailureReason;
+} | {
+    readonly status: "unavailable";
+    readonly providerId: ProviderId;
+    readonly reason: ProviderFailureReason;
+};
+export declare const AdapterModelSchema: z.ZodType<AdapterModel, AdapterModelInput>;
+export declare const ProviderSnapshotSchema: z.ZodType<ProviderSnapshot, ProviderSnapshotInput>;
+export declare function parseAdapterModel(input: unknown): AdapterModel;
+export declare function parseProviderSnapshot(input: unknown): ProviderSnapshot;

package/dist/core/models.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { ModelIdSchema, ProviderIdSchema } from "./ids";
+export const AdapterModelSchema = z
+    .object({ id: ModelIdSchema })
+    .strict()
+    .readonly();
+const ProviderFailureReasonSchema = z.union([
+    z.literal("adapter-error"),
+    z.literal("transport-error"),
+    z.literal("process-error"),
+    z.literal("invalid-data"),
+]);
+const AdapterModelsSchema = z
+    .array(AdapterModelSchema)
+    .superRefine((models, context) => {
+    const ids = new Set();
+    for (const model of models) {
+        if (ids.has(model.id)) {
+            context.addIssue({ code: "custom", message: "duplicate model ID" });
+        }
+        ids.add(model.id);
+    }
+})
+    .readonly();
+export const ProviderSnapshotSchema = z
+    .discriminatedUnion("status", [
+    z
+        .object({
+        status: z.literal("ready"),
+        providerId: ProviderIdSchema,
+        models: AdapterModelsSchema,
+    })
+        .strict()
+        .readonly(),
+    z
+        .object({
+        status: z.literal("stale"),
+        providerId: ProviderIdSchema,
+        models: AdapterModelsSchema,
+        reason: ProviderFailureReasonSchema,
+    })
+        .strict()
+        .readonly(),
+    z
+        .object({
+        status: z.literal("unavailable"),
+        providerId: ProviderIdSchema,
+        reason: ProviderFailureReasonSchema,
+    })
+        .strict()
+        .readonly(),
+])
+    .readonly();
+export function parseAdapterModel(input) {
+    return AdapterModelSchema.parse(input);
+}
+export function parseProviderSnapshot(input) {
+    return ProviderSnapshotSchema.parse(input);
+}

package/dist/core/options.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { HealthPolicy } from "./health";
+export type CredentialRefreshMode = "auto" | "never";
+export type CredentialRefreshPolicy = {
+    readonly mode: CredentialRefreshMode;
+    readonly leadMs: number;
+};
+export type ConnectorOptionsInput = {
+    readonly providers?: readonly ("claude" | "cursor" | "command-code" | "ollama")[] | undefined;
+    readonly snapshotTimeoutMs?: number | undefined;
+    readonly writeBackCredentials?: boolean | undefined;
+    readonly credentialRefresh?: {
+        readonly mode?: CredentialRefreshMode | undefined;
+        readonly leadMs?: number | undefined;
+    } | undefined;
+    readonly catalogReloadMs?: number | undefined;
+    readonly health?: {
+        readonly initialBackoffMs?: number | undefined;
+        readonly maximumBackoffMs?: number | undefined;
+    } | undefined;
+};
+export type ConnectorOptions = {
+    readonly providers: readonly ("claude" | "cursor" | "command-code" | "ollama")[];
+    readonly snapshotTimeoutMs: number;
+    readonly writeBackCredentials: boolean;
+    readonly credentialRefresh: CredentialRefreshPolicy;
+    readonly catalogReloadMs: number;
+    readonly health: HealthPolicy;
+};
+export declare const ConnectorOptionsSchema: z.ZodType<ConnectorOptions, ConnectorOptionsInput>;
+export declare function parseConnectorOptions(input: unknown): ConnectorOptions;

package/dist/core/options.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+const MaximumTimerMs = 2_147_483_647;
+const PositiveSafeIntegerSchema = z.number().int().positive().max(MaximumTimerMs);
+const NonNegativeSafeIntegerSchema = z.number().int().nonnegative().max(MaximumTimerMs);
+const ProviderSchema = z.enum(["claude", "cursor", "command-code", "ollama"]);
+const CredentialRefreshModeSchema = z.enum(["auto", "never"]);
+const DefaultProviders = [
+    "claude",
+    "cursor",
+    "command-code",
+    "ollama",
+];
+const ConnectorOptionsInputSchema = z
+    .object({
+    providers: z.array(ProviderSchema).optional(),
+    snapshotTimeoutMs: PositiveSafeIntegerSchema.optional(),
+    writeBackCredentials: z.boolean().optional(),
+    credentialRefresh: z
+        .object({
+        mode: CredentialRefreshModeSchema.optional(),
+        leadMs: NonNegativeSafeIntegerSchema.optional(),
+    })
+        .strict()
+        .optional(),
+    catalogReloadMs: NonNegativeSafeIntegerSchema.optional(),
+    health: z
+        .object({
+        initialBackoffMs: PositiveSafeIntegerSchema.optional(),
+        maximumBackoffMs: PositiveSafeIntegerSchema.optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((input, context) => {
+    const initialBackoffMs = input.health?.initialBackoffMs ?? 1_000;
+    const maximumBackoffMs = input.health?.maximumBackoffMs ?? 60_000;
+    if (initialBackoffMs > maximumBackoffMs) {
+        context.addIssue({ code: "custom", message: "initial backoff exceeds maximum" });
+    }
+});
+export const ConnectorOptionsSchema = ConnectorOptionsInputSchema.transform((input) => {
+    const health = Object.freeze({
+        initialBackoffMs: input.health?.initialBackoffMs ?? 1_000,
+        maximumBackoffMs: input.health?.maximumBackoffMs ?? 60_000,
+    });
+    const credentialRefresh = Object.freeze({
+        mode: input.credentialRefresh?.mode ?? "auto",
+        leadMs: input.credentialRefresh?.leadMs ?? 60_000,
+    });
+    return Object.freeze({
+        providers: Object.freeze(input.providers ?? DefaultProviders),
+        snapshotTimeoutMs: input.snapshotTimeoutMs ?? 30_000,
+        writeBackCredentials: input.writeBackCredentials ?? false,
+        credentialRefresh,
+        catalogReloadMs: input.catalogReloadMs ?? 300_000,
+        health,
+    });
+});
+export function parseConnectorOptions(input) {
+    return ConnectorOptionsSchema.parse(input);
+}

package/dist/core/process.d.ts

@@ -0,0 +1,20 @@
+import type { AsyncDisposableHandle } from "./lifecycle";
+export type ProcessCommand = {
+    readonly executable: string;
+    readonly arguments: readonly string[];
+    readonly cwd: string | null;
+};
+export type ProcessExit = {
+    readonly kind: "code";
+    readonly code: number;
+} | {
+    readonly kind: "signal";
+    readonly signal: string;
+};
+export interface SupervisedProcess extends AsyncDisposableHandle {
+    wait(signal: AbortSignal): Promise<ProcessExit>;
+    terminate(): Promise<void>;
+}
+export interface ProcessSupervisor extends AsyncDisposableHandle {
+    start(command: ProcessCommand, signal: AbortSignal): Promise<SupervisedProcess>;
+}

package/dist/core/process.js

@@ -0,0 +1 @@
+export {};

package/dist/http/fetch-transport.d.ts

@@ -0,0 +1,2 @@
+import type { HttpTransport } from "../core/http";
+export declare function createFetchHttpTransport(): HttpTransport;

package/dist/http/fetch-transport.js

@@ -0,0 +1,75 @@
+export function createFetchHttpTransport() {
+    return {
+        request: async (request, signal) => {
+            const response = await fetch(request.url, {
+                method: request.method,
+                headers: request.headers,
+                body: request.body,
+                signal,
+            });
+            const headers = {};
+            response.headers.forEach((value, name) => {
+                headers[name] = value;
+            });
+            return {
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+                body: new Uint8Array(await response.arrayBuffer()),
+                bodyPresent: response.body !== null,
+            };
+        },
+        stream: async (request, signal) => {
+            const response = await fetch(request.url, {
+                method: request.method,
+                headers: request.headers,
+                body: request.body,
+                signal,
+            });
+            const headers = {};
+            response.headers.forEach((value, name) => {
+                headers[name] = value;
+            });
+            const body = response.body;
+            if (body === null) {
+                return {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers,
+                    body: (async function* () { })(),
+                    bodyPresent: false,
+                };
+            }
+            const reader = body.getReader();
+            const streamBody = (async function* () {
+                let completed = false;
+                try {
+                    while (true) {
+                        if (signal.aborted) {
+                            throw new DOMException("Aborted", "AbortError");
+                        }
+                        const { done, value } = await reader.read();
+                        if (done) {
+                            completed = true;
+                            break;
+                        }
+                        yield value;
+                    }
+                }
+                finally {
+                    if (!completed) {
+                        await reader.cancel();
+                    }
+                    reader.releaseLock();
+                }
+            })();
+            return {
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+                body: streamBody,
+                bodyPresent: true,
+            };
+        },
+    };
+}

package/dist/http/package-version.d.ts

@@ -0,0 +1,7 @@
+import type { HttpTransport } from "../core/http";
+export type PackageVersionResolver = (signal: AbortSignal) => Promise<string | null>;
+export type PackageVersionResolverOptions = {
+    readonly transport: HttpTransport;
+    readonly packageName: string;
+};
+export declare function createPackageVersionResolver(options: PackageVersionResolverOptions): PackageVersionResolver;