@cjhyy/code-shell-server 0.9.44 → 0.9.46

package/dist/links/providers/index.d.ts

@@ -0,0 +1,7 @@
+import { type AgentModule, type LocalLinkProviderSpec } from "@cjhyy/code-shell-core/extension";
+export { createDefaultLinkProviders } from "./defaults.js";
+type Registrar = (providers: readonly LocalLinkProviderSpec[]) => void;
+/** Explicit product composition; custom SDK callers may supply their own registrar. */
+export declare function installDefaultLinkProviders(register?: Registrar): void;
+/** Loaded by the existing trusted worker module factory mechanism. */
+export declare function createLinkProviderModule(): AgentModule;

package/dist/links/providers/index.js

@@ -0,0 +1,22 @@
+import { registerLocalLinkProviders, getLocalLinkProvider, } from "@cjhyy/code-shell-core/extension";
+import { createDefaultLinkProviders } from "./defaults.js";
+export { createDefaultLinkProviders } from "./defaults.js";
+const installed = new WeakSet();
+/** Explicit product composition; custom SDK callers may supply their own registrar. */
+export function installDefaultLinkProviders(register = registerLocalLinkProviders) {
+    if (installed.has(register))
+        return;
+    const providers = createDefaultLinkProviders();
+    // Two product module copies may share one Core registry (e.g. a host/plugin
+    // composition). Preserve explicitly installed implementations instead of
+    // overwriting them or treating the second default composition as an error.
+    register(register === registerLocalLinkProviders
+        ? providers.filter((provider) => !getLocalLinkProvider(provider.id))
+        : providers);
+    installed.add(register);
+}
+/** Loaded by the existing trusted worker module factory mechanism. */
+export function createLinkProviderModule() {
+    installDefaultLinkProviders();
+    return { id: "codeshell-link-providers" };
+}

package/dist/links/remote-catalog.d.ts

@@ -1,5 +1,13 @@
 import { type RemoteLinkConfiguration } from "@cjhyy/code-shell-core";
 import { type RemoteLinkProviderId } from "@cjhyy/code-shell-core";
+export type RemoteLinkCatalogFailureReason = "network" | "timeout" | "http_status" | "invalid_json" | "invalid_schema" | "unreviewed_capability" | "unsupported_auth" | "response_limit";
+/** Fixed diagnostics distinguish unavailable discovery from a valid empty catalog. */
+export declare class RemoteLinkCatalogError extends Error {
+    readonly reason: RemoteLinkCatalogFailureReason;
+    readonly httpStatus?: number | undefined;
+    readonly code: "network_error" | "http_error" | "invalid_response" | "response_too_large";
+    constructor(reason: RemoteLinkCatalogFailureReason, httpStatus?: number | undefined);
+}
 /** The Host's compiled executors own authority, never remotely supplied presentation metadata. */
 export declare const REMOTE_LINK_ADAPTERS: ({
     methodId: string;
@@ -80,7 +88,7 @@ export declare const REMOTE_LINK_ADAPTERS: ({
     id: "figma";
     name: "Figma";
     group: "files";
-    actions: readonly ["get_file", "get_comments", "get_nodes", "get_images", "get_image_fills"];
+    actions: readonly ["get_file", "read_design_content", "get_comments", "get_nodes", "get_images", "get_image_fills"];
 })[];
 export type RemoteProviderId = RemoteLinkProviderId;
 export interface RemoteProviderCapabilities {
@@ -88,7 +96,6 @@ export interface RemoteProviderCapabilities {
     actions: string[];
     scopes: string[];
 }
-export declare const LEGACY_REMOTE_PROVIDERS: RemoteProviderCapabilities[];
 export declare function readRemoteProviderCatalog(configuration: RemoteLinkConfiguration): Promise<RemoteProviderId[]>;
-/** A legacy v1 service has no catalog. Its one already-reviewed adapter remains compatible. */
+/** Discovery never grants authority or turns a failed response into an empty catalog. */
 export declare function readRemoteProviderCapabilities(configuration: RemoteLinkConfiguration): Promise<RemoteProviderCapabilities[]>;

package/dist/links/remote-catalog.js

@@ -1,5 +1,34 @@
 import { beginRemoteLinkAuthorization } from "@cjhyy/code-shell-core";
-import { REMOTE_LINK_PROVIDER_ADAPTERS, LEGACY_GITHUB_ACTIONS, } from "@cjhyy/code-shell-core";
+import { REMOTE_LINK_PROVIDER_ADAPTERS } from "@cjhyy/code-shell-core";
+/** Fixed diagnostics distinguish unavailable discovery from a valid empty catalog. */
+export class RemoteLinkCatalogError extends Error {
+    reason;
+    httpStatus;
+    code;
+    constructor(reason, httpStatus) {
+        super({
+            network: "Could not reach the Link provider catalog. Retry the request.",
+            timeout: "The Link provider catalog request timed out. Retry the request.",
+            http_status: "The Link provider catalog returned an unsuccessful HTTP status.",
+            invalid_json: "The Link provider catalog response is not valid JSON.",
+            invalid_schema: "The Link provider catalog response does not match the supported protocol.",
+            unreviewed_capability: "The Link provider catalog advertised an unreviewed capability.",
+            unsupported_auth: "The Link provider catalog uses an unsupported authorization mechanism.",
+            response_limit: "The Link provider catalog exceeded the 32 KiB response limit.",
+        }[reason]);
+        this.reason = reason;
+        this.httpStatus = httpStatus;
+        this.name = "RemoteLinkCatalogError";
+        this.code =
+            reason === "network" || reason === "timeout"
+                ? "network_error"
+                : reason === "http_status"
+                    ? "http_error"
+                    : reason === "response_limit"
+                        ? "response_too_large"
+                        : "invalid_response";
+    }
+}
 /** The Host's compiled executors own authority, never remotely supplied presentation metadata. */
 export const REMOTE_LINK_ADAPTERS = REMOTE_LINK_PROVIDER_ADAPTERS.map((adapter) => ({
     ...adapter,
@@ -7,36 +36,36 @@ export const REMOTE_LINK_ADAPTERS = REMOTE_LINK_PROVIDER_ADAPTERS.map((adapter)
     authModeId: "remote-link",
     scopes: adapter.actions.map((action) => `${adapter.id}:${action}`),
 }));
-export const LEGACY_REMOTE_PROVIDERS = [
-    {
-        id: "github",
-        actions: [...LEGACY_GITHUB_ACTIONS],
-        scopes: LEGACY_GITHUB_ACTIONS.map((action) => `github:${action}`),
-    },
-];
 export async function readRemoteProviderCatalog(configuration) {
     return (await readRemoteProviderCapabilities(configuration)).map((provider) => provider.id);
 }
-/** A legacy v1 service has no catalog. Its one already-reviewed adapter remains compatible. */
+/** Discovery never grants authority or turns a failed response into an empty catalog. */
 export async function readRemoteProviderCapabilities(configuration) {
     const issuer = beginRemoteLinkAuthorization(configuration).configuration.issuer;
     const scopes = REMOTE_LINK_ADAPTERS.flatMap((adapter) => adapter.scopes);
     const capabilities = JSON.stringify({ version: 1, scopes });
     if (scopes.length > 128 || Buffer.byteLength(capabilities) > 4_096)
         throw new Error("Host Link capabilities exceed catalog negotiation limits");
-    const response = await fetch(new URL("/api/v1/links/providers", issuer), {
-        redirect: "error",
-        signal: AbortSignal.timeout(5_000),
-        headers: { Accept: "application/json", "X-CodeShell-Link-Capabilities": capabilities },
-    });
-    if ([404, 501].includes(response.status)) {
-        await response.body?.cancel();
-        return structuredClone(LEGACY_REMOTE_PROVIDERS);
+    const signal = AbortSignal.timeout(5_000);
+    let response;
+    try {
+        response = await fetch(new URL("/api/v1/links/providers", issuer), {
+            redirect: "error",
+            signal,
+            headers: { Accept: "application/json", "X-CodeShell-Link-Capabilities": capabilities },
+        });
     }
-    if (!response.ok || !response.body) {
-        await response.body?.cancel();
-        throw new Error("Link catalog unavailable");
+    catch (error) {
+        throw new RemoteLinkCatalogError(signal.aborted || (error instanceof Error && error.name === "TimeoutError")
+            ? "timeout"
+            : "network");
     }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new RemoteLinkCatalogError("http_status", response.status);
+    }
+    if (!response.body)
+        throw new RemoteLinkCatalogError("invalid_schema");
     const reader = response.body.getReader();
     const chunks = [];
     let size = 0;
@@ -47,12 +76,17 @@ export async function readRemoteProviderCapabilities(configuration) {
                 break;
             size += value.byteLength;
             if (size > 32_768) {
-                await reader.cancel();
-                return [];
+                throw new RemoteLinkCatalogError("response_limit");
             }
             chunks.push(value);
         }
     }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        if (error instanceof RemoteLinkCatalogError)
+            throw error;
+        throw new RemoteLinkCatalogError(signal.aborted ? "timeout" : "network");
+    }
     finally {
         reader.releaseLock();
     }
@@ -61,13 +95,22 @@ export async function readRemoteProviderCapabilities(configuration) {
         catalog = JSON.parse(Buffer.concat(chunks).toString("utf8"));
     }
     catch {
-        return [];
+        throw new RemoteLinkCatalogError("invalid_json");
     }
     if (catalog?.version !== 1 || !Array.isArray(catalog.providers) || catalog.providers.length > 32)
-        return [];
+        throw new RemoteLinkCatalogError("invalid_schema");
+    if (catalog.providers.some((item) => !item ||
+        typeof item !== "object" ||
+        Array.isArray(item) ||
+        typeof item.id !== "string" ||
+        !/^[a-z][a-z0-9_-]{0,63}$/.test(item.id)))
+        throw new RemoteLinkCatalogError("invalid_schema");
+    const ids = catalog.providers.map((item) => item.id);
+    if (new Set(ids).size !== ids.length)
+        throw new RemoteLinkCatalogError("invalid_schema");
     return REMOTE_LINK_ADAPTERS.flatMap((adapter) => {
         const matches = catalog.providers.filter((item) => item?.id === adapter.id);
-        if (matches.length !== 1)
+        if (!matches.length)
             return [];
         const provider = matches[0];
         const actions = provider.actions;
@@ -81,14 +124,18 @@ export async function readRemoteProviderCapabilities(configuration) {
             scopes.length !== actions.length ||
             new Set(scopes).size !== scopes.length ||
             actions.some((action) => !scopes.includes(`${adapter.id}:${action}`)))
-            return [];
-        if (!Array.isArray(provider.methods) ||
-            !provider.methods.some((method) => method?.id === adapter.methodId &&
+            throw new RemoteLinkCatalogError("unreviewed_capability");
+        const methods = Array.isArray(provider.methods)
+            ? provider.methods.filter((method) => method?.id === adapter.methodId)
+            : [];
+        if (methods.length !== 1 ||
+            !methods.some((method) => method?.id === adapter.methodId &&
                 method.authKind === "oauth" &&
                 method.defaultAuthModeId === "browser" &&
                 Array.isArray(method.authModes) &&
+                method.authModes.filter((mode) => mode?.id === "browser").length === 1 &&
                 method.authModes.some((mode) => mode?.id === "browser" && mode.kind === "redirect")))
-            return [];
+            throw new RemoteLinkCatalogError("unsupported_auth");
         return [{ id: adapter.id, actions: [...actions], scopes: [...scopes] }];
     });
 }

package/dist/links/runtime/operation.d.ts

@@ -0,0 +1,9 @@
+/** One adapter invocation. Write approval, durable intent and verification belong to the owning controller. */
+export declare function executeLinkOperation(options: {
+    providerId: string;
+    action: string;
+    params: Record<string, unknown>;
+    execute(params: Record<string, unknown>): Promise<unknown>;
+    assertAuthorized?(): void;
+    signal?: AbortSignal;
+}): Promise<unknown>;

package/dist/links/runtime/operation.js

@@ -0,0 +1,16 @@
+import { LinkOperationError, assertLinkOperationResult, getLinkOperationContract, snapshotLinkOperationInput, } from "@cjhyy/code-shell-link";
+/** One adapter invocation. Write approval, durable intent and verification belong to the owning controller. */
+export async function executeLinkOperation(options) {
+    const contract = getLinkOperationContract(options.providerId, options.action);
+    if (!contract)
+        throw new LinkOperationError("unsupported_contract", "This Host does not support the requested operation contract.");
+    // Detach input before asynchronous code can observe caller changes.
+    const params = snapshotLinkOperationInput(contract, options.params);
+    options.signal?.throwIfAborted();
+    options.assertAuthorized?.();
+    const result = await options.execute(params);
+    options.assertAuthorized?.();
+    options.signal?.throwIfAborted();
+    assertLinkOperationResult(contract, result);
+    return result;
+}

package/dist/links/service.d.ts

@@ -1,12 +1,18 @@
 import { CredentialStore, type RemoteLinkConfiguration, connectCliLink, getCliLinkStatus, validateLocalLinkToken, type LocalLinkValidationResult } from "@cjhyy/code-shell-core";
+import { type LinkAuthorizationDiagnosticSink } from "./diagnostics.js";
 import { readRemoteProviderCatalog } from "./remote-catalog.js";
 import { LinkDeviceOAuthBroker, type LocalBrowserAuthToken } from "./device-oauth.js";
-import type { LinkAuthorization, LinkAuthorizationResponse, LinkConnectionInput, LinkErrorCode, LinkOperationContext, LinkSnapshot, MaskedLinkConnection, TokenConnectionInput } from "./types.js";
+import type { LinkAuthorization, LinkAuthorizationFailure, LinkAuthorizationResponse, LinkConnectionInput, LinkErrorCode, LinkOperationContext, LinkSnapshot, MaskedLinkConnection, TokenConnectionInput, HostLinkOAuthAdapter } from "./types.js";
 export declare class LinkServiceError extends Error {
     readonly status: number;
     readonly code: LinkErrorCode;
     constructor(status: number, code: LinkErrorCode);
 }
+/** Trusted Host adapters use this to expose reviewed failure stages, never raw provider text. */
+export declare class HostLinkOAuthError extends LinkServiceError {
+    readonly failure: LinkAuthorizationFailure;
+    constructor(failure: LinkAuthorizationFailure);
+}
 export declare function publicLinkError(error: unknown): LinkServiceError;
 export interface LinkServiceOptions {
     cwd?: string;
@@ -16,6 +22,11 @@ export interface LinkServiceOptions {
     now?: () => number;
     /** Trusted Host configuration; never accepted from a browser request. */
     remoteLink?: () => RemoteLinkConfiguration | undefined;
+    /** Optional Host authority for a remote authorization's complete lifetime. */
+    captureRemoteAuthority?: () => {
+        current(): void;
+        signal: AbortSignal;
+    };
     /** Trusted Host opt-in: reuse a uniquely identified user connection after remote OAuth. */
     reuseRemoteConnection?: boolean;
     /** Test seams. Production delegates to Core's fixed provider and CLI executors. */
@@ -26,6 +37,9 @@ export interface LinkServiceOptions {
     readRemoteCatalog?: typeof readRemoteProviderCatalog;
     /** Native Host only; remote browser callers may bind existing Host sessions but cannot start login. */
     allowCliLogin?: boolean;
+    hostOAuthAdapters?: readonly HostLinkOAuthAdapter[];
+    /** Defaults to redacted single-line JSON on stderr for HTTP and native authorization starts. */
+    onAuthorizationDiagnostic?: LinkAuthorizationDiagnosticSink;
 }
 /** Trusted host adapter input; deliberately absent from the HTTP API. */
 export type ValidatedLinkAuthentication = {
@@ -45,6 +59,7 @@ export declare function createLinkService(options?: LinkServiceOptions): {
     connectToken: (context: LinkOperationContext, input: TokenConnectionInput) => Promise<MaskedLinkConnection>;
     connectCli: (context: LinkOperationContext, input: LinkConnectionInput) => Promise<MaskedLinkConnection>;
     cliStatus: (context: LinkOperationContext, rawProviderId: unknown) => Promise<{
+        accountId?: string | undefined;
         account?: string | undefined;
         providerId: import("@cjhyy/code-shell-core").CliLinkProviderId;
         command: string;
@@ -55,8 +70,9 @@ export declare function createLinkService(options?: LinkServiceOptions): {
     disconnect: (context: LinkOperationContext, id: string, expectedRevision: string) => Promise<void>;
     startDeviceAuth: (context: LinkOperationContext, input: LinkConnectionInput) => Promise<LinkAuthorization>;
     startAuthorization: (context: LinkOperationContext, input: LinkConnectionInput, rawAuthModeId: unknown) => Promise<LinkAuthorization>;
+    openHostAuthorization: (context: LinkOperationContext, id: string) => Promise<boolean>;
     respondAuthorization: (context: LinkOperationContext, id: string, response: LinkAuthorizationResponse) => Promise<LinkAuthorization>;
-    refreshRemoteCatalog: (context: LinkOperationContext) => Promise<void>;
+    refreshRemoteCatalog: (context: LinkOperationContext, force?: boolean) => Promise<void>;
     startRemoteAuth: (context: LinkOperationContext, input: LinkConnectionInput) => Promise<LinkAuthorization>;
     completeRemoteAuth: (context: LinkOperationContext, id: string, callbackUrl: string) => Promise<LinkAuthorization>;
     retryRemoteCleanup: () => Promise<void>;