@openfairygui/backend 0.2.0-alpha.0 → 0.2.0-alpha.1

package/dist/runtime-C5JY_kRI.d.cts

@@ -0,0 +1,424 @@
+import { UamProject, UamTransactionOperation } from "@openfairygui/core";
+import { ApplyUamTransactionAppError } from "@openfairygui/functions";
+
+//#region src/contracts.d.ts
+declare const BACKEND_CONTRACT_VERSION: "1.1.0-p2";
+declare const BACKEND_CAPABILITY_SCHEMA_VERSION: 2;
+declare const BACKEND_COMPATIBILITY_POLICY: {
+  readonly incompatibleChange: "requires contractVersion bump";
+  readonly capabilitySchemaChange: "requires capabilitySchemaVersion bump";
+  readonly additiveChange: "allowed without breaking existing consumers";
+};
+type BackendStage = 'read' | 'authoring' | 'runtime';
+interface BackendMessage {
+  code: string;
+  message: string;
+}
+interface BackendDiagnostic {
+  code: string;
+  message: string;
+  severity: 'info' | 'warning' | 'error';
+}
+interface BackendResponseMeta {
+  requestId: string;
+  sessionId?: string;
+  revision?: number;
+  durationMs: number;
+  warnings: BackendMessage[];
+  diagnostics: BackendDiagnostic[];
+  stage: BackendStage;
+  contractVersion: typeof BACKEND_CONTRACT_VERSION;
+  capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
+}
+//#endregion
+//#region src/path-policy.d.ts
+interface PathPolicyViolationError {
+  code: 'path_policy_violation';
+  message: string;
+  policy: 'save_target';
+  attemptedPath: string;
+  allowedPath: string;
+}
+//#endregion
+//#region src/runtime.d.ts
+interface BackendFileHandle {
+  writeFile(content: string): Promise<void>;
+  close(): Promise<void>;
+}
+interface BackendFileStat {
+  isFile(): boolean;
+  isDirectory(): boolean;
+}
+interface BackendFileSystem {
+  stat(filePath: string): Promise<BackendFileStat>;
+  readdir(dirPath: string): Promise<string[]>;
+  readFile(filePath: string): Promise<string>;
+  readFileRaw(filePath: string): Promise<Uint8Array>;
+  writeFile(filePath: string, content: string): Promise<void>;
+  writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+  mkdir(dirPath: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  resolvePath(filePath: string): Promise<string>;
+  openExclusive(filePath: string): Promise<BackendFileHandle>;
+  unlink(filePath: string): Promise<void>;
+  join(...paths: string[]): string;
+  dirname(filePath: string): string;
+  resolve(...paths: string[]): string;
+}
+interface BackendHostAdapter {
+  lockMetadata?(input: {
+    canonicalPathKey: string;
+    canonicalProjectPath: string;
+    lockFilePath: string;
+  }): unknown;
+}
+interface BackendArtifactBridgeCapability {
+  available: false;
+  requiredHost: 'node';
+  executionBoundary: 'external-bridge';
+  bridgeEntrypoint: '@openfairygui/backend/node';
+  reason: string;
+}
+interface BackendCapabilityManifest {
+  browserSafe: true;
+  rootEntrypoint: '@openfairygui/backend';
+  nodeEntrypoint: '@openfairygui/backend/node';
+  adapters: {
+    fileSystem: {
+      injected: true;
+      requiredFor: readonly ['openSession', 'saveSession'];
+    };
+    host: {
+      injected: true;
+      requiredFor: readonly ['advisoryLockMetadata'];
+    };
+  };
+  executionBoundaries: {
+    projectSession: 'in-process-browser-safe';
+    fileBackedSession: 'adapter-backed';
+    artifactPublish: BackendArtifactBridgeCapability;
+    artifactRestore: BackendArtifactBridgeCapability;
+  };
+  diagnostics: {
+    stableCodes: true;
+    errorDiagnosticMirror: true;
+  };
+}
+interface BackendCapabilities {
+  contractVersion: typeof BACKEND_CONTRACT_VERSION;
+  capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
+  transactionKernelOwner: '@openfairygui/core';
+  appSeamOwner: '@openfairygui/functions';
+  runtimeOwner: '@openfairygui/backend';
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  read: {
+    capabilitySnapshot: true;
+    sessionSnapshot: true;
+  };
+  authoring: {
+    applyTransaction: true;
+    saveSession: true;
+    resourceKinds: readonly string[];
+    nodeKinds: readonly string[];
+    gearKinds: readonly string[];
+    unsupported: readonly ['artifact.publish', 'artifact.restore'];
+  };
+  artifact: {
+    publish: false;
+    restore: false;
+    status: 'bridge-required';
+    publishBridge: BackendArtifactBridgeCapability;
+    restoreBridge: BackendArtifactBridgeCapability;
+  };
+  manifest: BackendCapabilityManifest;
+  compatibilityPolicy: typeof BACKEND_COMPATIBILITY_POLICY;
+  runtime: {
+    sessionRuntime: true;
+    advisoryLocking: true;
+    coordinatedSave: true;
+    atomicSave: false;
+    staleRevisionProtection: true;
+    pathPolicy: {
+      canonicalization: 'realpath+normalized-casefold';
+      sessionIdentity: 'project-root';
+      saveTarget: 'opened-project-only';
+      outputTargets: 'deferred';
+      workspaceBoundary: 'project-root-only';
+    };
+    events: {
+      polling: true;
+      subscriptions: false;
+      retentionLimit: 1000;
+      sequenceScope: 'runtime';
+    };
+    jobs: {
+      inMemory: true;
+      cooperativeCancel: true;
+      persistent: false;
+      supportedKinds: readonly ['cache.refresh'];
+      artifactJobs: false;
+      completedRetentionLimit: 100;
+    };
+    cache: {
+      derivedReadOnly: true;
+      keyedBy: 'canonicalPathKey';
+      sourceOfTruth: false;
+      refreshMethod: 'refreshCache';
+    };
+  };
+}
+interface BackendSessionSnapshot {
+  sessionId: string;
+  canonicalProjectPath: string;
+  revision: number;
+  lastSavedRevision: number;
+  dirty: boolean;
+  lockHeld: boolean;
+  capabilities: BackendCapabilities;
+}
+interface BackendSuccess<T> {
+  ok: true;
+  meta: BackendResponseMeta;
+  data: T;
+}
+interface BackendFailure<E extends BackendError = BackendError> {
+  ok: false;
+  meta: BackendResponseMeta;
+  error: E;
+  session?: BackendSessionSnapshot;
+}
+type BackendResult<T, E extends BackendError = BackendError> = BackendSuccess<T> | BackendFailure<E>;
+interface SessionNotFoundError {
+  code: 'session_not_found';
+  message: string;
+  sessionId: string;
+}
+interface SessionStaleWriteError {
+  code: 'stale_write';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  expectedRevision: number;
+  actualRevision: number;
+}
+interface InProcessLockConflictError {
+  code: 'lock_conflict';
+  kind: 'in_process_session_exists';
+  message: string;
+  canonicalPathKey: string;
+  holderSessionId: string;
+  lockFilePath?: string;
+}
+interface AdvisoryLockConflictError {
+  code: 'lock_conflict';
+  kind: 'advisory_lock_conflict';
+  message: string;
+  canonicalPathKey: string;
+  holderSessionId?: string;
+  lockFilePath: string;
+}
+interface SavePartialFailureError {
+  code: 'save_partial_failure';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  attemptedRevision: number;
+  lastSavedRevision: number;
+  committedPaths: string[];
+  failedPaths: string[];
+  diskMayBePartiallyUpdated: true;
+}
+type BackendEventKind = 'session.opened' | 'transaction.applied' | 'transaction.rejected' | 'save.started' | 'save.completed' | 'save.failed' | 'session.closeRequested' | 'session.closed' | 'cache.invalidated' | 'cache.updated' | 'job.created' | 'job.started' | 'job.progress' | 'job.cancelRequested' | 'job.cancelled' | 'job.completed' | 'job.failed';
+interface BackendEvent {
+  sequence: number;
+  kind: BackendEventKind;
+  timestamp: string;
+  sessionId?: string;
+  canonicalPathKey?: string;
+  revision?: number;
+  cacheRevision?: number;
+  jobId?: string;
+  diagnostics: BackendDiagnostic[];
+  payload?: unknown;
+}
+interface GetEventsInput {
+  sessionId: string;
+  after?: string;
+  limit?: number;
+}
+interface GetEventsSnapshot {
+  events: BackendEvent[];
+  oldestSequence: number;
+  currentSequence: number;
+  cursorExpired: boolean;
+}
+interface EventCursorInvalidError {
+  code: 'event_cursor_invalid';
+  message: string;
+  sessionId: string;
+  after: string;
+}
+type BackendJobStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+type BackendJobKind = 'cache.refresh';
+type BackendJobListStatusFilter = BackendJobStatus | 'active' | 'terminal';
+interface BackendJobProgress {
+  completed: number;
+  total?: number;
+  message?: string;
+}
+interface BackendJobSnapshot {
+  jobId: string;
+  kind: BackendJobKind;
+  status: BackendJobStatus;
+  createdAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  sessionId?: string;
+  canonicalPathKey?: string;
+  revision?: number;
+  cacheRevision?: number;
+  diagnostics: BackendDiagnostic[];
+  progress?: BackendJobProgress;
+  result?: unknown;
+  error?: BackendError;
+}
+interface BackendJobListSnapshot {
+  jobs: BackendJobSnapshot[];
+}
+interface GetJobInput {
+  sessionId: string;
+  jobId: string;
+}
+interface ListJobsInput {
+  sessionId: string;
+  status?: BackendJobListStatusFilter;
+  kind?: BackendJobKind;
+  limit?: number;
+}
+interface CancelJobInput {
+  sessionId: string;
+  jobId: string;
+}
+interface BackendJobNotFoundError {
+  code: 'job_not_found';
+  message: string;
+  sessionId: string;
+  jobId: string;
+}
+interface BackendJobNotCancellableError {
+  code: 'job_not_cancellable';
+  message: string;
+  sessionId: string;
+  jobId: string;
+  status: 'completed' | 'failed' | 'cancelled';
+}
+interface BackendJobCancelledError {
+  code: 'job_cancelled';
+  message: string;
+  sessionId: string;
+  jobId: string;
+}
+interface CacheRefreshFailedError {
+  code: 'cache_refresh_failed';
+  message: string;
+  sessionId: string;
+  jobId: string;
+  causeCode?: string;
+}
+interface BackendCapabilityUnavailableError {
+  code: 'capability_unavailable';
+  message: string;
+  capability: 'fileSystem' | 'artifact.publish' | 'artifact.restore';
+  requiredAdapter?: 'BackendFileSystem';
+  requiredHost?: 'node';
+  bridgeBoundary?: 'external-bridge';
+}
+type BackendJobErrors = BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError;
+interface BackendCacheSnapshot {
+  cacheRevision: number;
+  entries: BackendCacheEntry[];
+}
+interface BackendCacheEntry {
+  canonicalPathKey: string;
+  sessionId?: string;
+  revision: number;
+  lastSavedRevision: number;
+  dirty: boolean;
+  valid: boolean;
+  indexedAt: string;
+  summary: {
+    resourceCount: number;
+    packageCount?: number;
+    diagnostics: BackendDiagnostic[];
+  };
+}
+interface GetCacheSnapshotInput {
+  sessionId: string;
+}
+interface RefreshCacheInput {
+  sessionId: string;
+  reason?: 'manual' | 'session_open' | 'after_save';
+}
+type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
+interface ApplySessionTransactionInput {
+  sessionId: string;
+  expectedRevision: number;
+  operations: UamTransactionOperation[];
+}
+interface OpenProjectSessionInput {
+  project: UamProject;
+  sessionId?: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+}
+interface BackendRuntimeOptions {
+  fileSystem?: BackendFileSystem;
+  host?: BackendHostAdapter;
+}
+declare class BackendRuntime {
+  private readonly fileSystem?;
+  private readonly capabilities;
+  private readonly sessions;
+  private readonly sessionsByPath;
+  private readonly eventsBySession;
+  private readonly jobsBySession;
+  private readonly cacheBySession;
+  private eventSequence;
+  private readonly context;
+  private readonly readService;
+  private readonly runtimeService;
+  private readonly authoringService;
+  private readonly cacheService;
+  private readonly eventService;
+  private readonly jobService;
+  constructor(options?: BackendRuntimeOptions);
+  getCapabilities(): BackendSuccess<BackendCapabilities>;
+  openSession(input: {
+    projectPath: string;
+  }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError>>;
+  openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot>;
+  getSession(input: {
+    sessionId: string;
+  }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
+  applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
+  saveSession(input: {
+    sessionId: string;
+    expectedRevision?: number;
+    targetPath?: string;
+  }): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>>;
+  closeSession(input: {
+    sessionId: string;
+  }): Promise<BackendResult<{
+    sessionId: string;
+    closed: true;
+  }, SessionNotFoundError>>;
+  getEvents(input: GetEventsInput): BackendResult<GetEventsSnapshot, SessionNotFoundError | EventCursorInvalidError>;
+  getJob(input: GetJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError>;
+  listJobs(input: ListJobsInput): BackendResult<BackendJobListSnapshot, SessionNotFoundError>;
+  cancelJob(input: CancelJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError | BackendJobNotCancellableError>;
+  getCacheSnapshot(input: GetCacheSnapshotInput): BackendResult<BackendCacheSnapshot, SessionNotFoundError>;
+  refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
+}
+//#endregion
+export { BackendSuccess as A, OpenProjectSessionInput as B, BackendJobProgress as C, BackendRuntime as D, BackendResult as E, GetEventsInput as F, BACKEND_CAPABILITY_SCHEMA_VERSION as G, SavePartialFailureError as H, GetEventsSnapshot as I, BackendDiagnostic as J, BACKEND_COMPATIBILITY_POLICY as K, GetJobInput as L, CancelJobInput as M, EventCursorInvalidError as N, BackendRuntimeOptions as O, GetCacheSnapshotInput as P, InProcessLockConflictError as R, BackendJobNotFoundError as S, BackendJobStatus as T, SessionNotFoundError as U, RefreshCacheInput as V, SessionStaleWriteError as W, BackendResponseMeta as X, BackendMessage as Y, BackendStage as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, CacheRefreshFailedError as j, BackendSessionSnapshot as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendCapabilities as o, BackendFileHandle as p, BACKEND_CONTRACT_VERSION as q, BackendArtifactBridgeCapability as r, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, ListJobsInput as z };