import { DoomMcpProjection } from "./mcpProjection.mjs";
//#region src/schemas/packageApi.d.ts
/** The host-owned sync view a repository-scoped package API may inspect. */
export interface DoomRepositorySyncView {
  fresh: boolean;
  reasons: string[];
  mcpProjection?: DoomMcpProjection;
}
/** Where an API runs: inside one session's server, or in the machine-wide hub. */
export type DoomApiScope = 'session' | 'hub';
export declare const DOOM_API_SCOPES: readonly DoomApiScope[];
/** The segment an API is mounted under, below this prefix. */
export declare const DOOM_API_ROUTE_PREFIX = "/api/plugin";
/** Selects the hub API bundle that owns the named cockpit session. */
export declare const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
/** Absolute unix socket path exposed to processes inside a session server. */
export declare const DOOM_API_SOCKET_ENV = "DOOMPI_SESSION_API_SOCKET";
/** Bearer token for agent-only routes on a session API socket. */
export declare const DOOM_API_INTERNAL_TOKEN_ENV = "DOOMPI_SESSION_API_INTERNAL_TOKEN";
/** Trusted caller headers written only by the cockpit-to-session proxy. */
export declare const DOOM_API_CALLER_LOCALITY_HEADER = "x-doompi-api-caller-locality";
export declare const DOOM_API_CALLER_DEVICE_ID_HEADER = "x-doompi-api-caller-device-id";
export declare const DOOM_API_CALLER_STEP_UP_HEADER = "x-doompi-api-caller-step-up";
export declare const DOOM_API_CALLER_HEADERS: readonly ["x-doompi-api-caller-locality", "x-doompi-api-caller-device-id", "x-doompi-api-caller-step-up"];
export type DoomApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';
export type DoomApiCaller = {
  locality: 'local';
  stepUp: 'not-required';
} | {
  locality: 'remote';
  deviceId: string;
  stepUp: DoomApiCallerStepUp;
};
/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
export declare function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined;
/**
 * A browser-reachable OAuth redirect the host serves on its own listener.
 *
 * A package brokering third-party OAuth cannot use a loopback redirect when the
 * operator's browser is on another machine: `127.0.0.1` resolves to whichever
 * machine the browser runs on. The host owns a listener that is reachable from
 * wherever the cockpit is being used, so it lends that instead of the package
 * opening a port of its own.
 */
export interface DoomOAuthRedirect {
  /** Absolute URL to register as the redirect target, already origin-correct. */
  readonly redirectUri: string;
  /**
   * Accept redirects carrying this state. Must complete before the
   * authorization URL is surfaced, or the redirect races its own reservation.
   */
  reserve(state: string, timeoutMs?: number): Promise<void>;
  /** Resolves once the redirect carrying this state arrives. */
  wait(state: string, timeoutMs?: number): Promise<{
    code: string;
    state: string;
  }>;
  /** Drops a reservation whose flow ended without a redirect. */
  cancel(state: string): void;
}
/** What the host tells an API about itself when it starts. */
export interface DoomApiContext {
  scope: DoomApiScope;
  /** The session this host serves; absent for a hub-scoped API. */
  sessionId?: string;
  /** The session's working directory; absent for a hub-scoped API. */
  cwd?: string;
  /** Shared only with child processes in this session, never with remote API clients. */
  internalToken?: string;
  /** Shared only with the cockpit hub for privileged cross-session coordination. */
  hubToken?: string;
  /**
   * Resolves a hub-issued opaque repository id to an admitted canonical root.
   * Hub APIs must never accept a browser-supplied filesystem path instead.
   */
  resolveRepository?(repositoryId: string): string | undefined;
  /** Reads the admitted repository's sync projection without exposing its state path. */
  readRepositorySync?(repositoryId: string): DoomRepositorySyncView | undefined;
  /**
   * Borrows the hub's OAuth redirect surface. Undefined when the hub cannot
   * currently serve one, in which case the package keeps its own behaviour.
   */
  oauthRedirect?(): DoomOAuthRedirect | undefined;
  onNotice(message: string): void;
}
/**
 * One running surface. The host strips the mount prefix before calling, so
 * routes are declared relative ('/runners/:id/log') and a package never
 * repeats where it was mounted.
 */
export interface DoomApiHandler {
  fetch(request: Request): Response | Promise<Response>;
  close(): void;
}
export interface DoomApi {
  /** Segment under /api/plugin/; globally unique across loaded packages. */
  basePath: string;
  start(context: DoomApiContext): DoomApiHandler;
}
/** The named export a declared entry must provide, so a host can find it. */
export declare const DOOM_API_EXPORT = "api";
/** Narrows a module's export to an API, so a broken package is a notice rather than a crash. */
export declare function isDoomApi(value: unknown): value is DoomApi;
/** The package.json field a package declares its API under. */
export declare const DOOM_API_MANIFEST_FIELD = "doompiApi";
export interface DoomApiEntryDeclaration {
  /** Package-relative ./path to the source entry. */
  entry: string;
  /** Package-relative ./path to the built entry, which is what a host imports. */
  dist?: string;
}
/** One package's declaration, validated, with an entry per scope it offers. */
export interface DeclaredPackageApi {
  basePath: string;
  packageDir: string;
  packageName: string;
  session?: DoomApiEntryDeclaration;
  hub?: DoomApiEntryDeclaration;
}
export declare class DoomApiManifestError extends Error {
  constructor(packageDir: string, message: string);
}
/**
 * Validates one package.json's `doompiApi` block. A block naming neither scope
 * is an error rather than an empty result: declaring an API that no host can
 * ever mount is a mistake worth reporting where it was made.
 */
export declare function declaredApisOf(packageDir: string, manifest: Record<string, unknown>): DeclaredPackageApi[];
/**
 * The deterministic order hosts mount in, with cross-package collisions settled
 * the way every other shared name is: the first package keeps the base path and
 * the later one is dropped with a notice.
 */
export declare function orderDeclaredApis(apis: readonly DeclaredPackageApi[], onNotice?: (message: string) => void): DeclaredPackageApi[];
//#endregion
//# sourceMappingURL=packageApi.d.mts.map