@openfairygui/backend 0.2.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,364 @@
+import { UamTransactionOperation } from "@openfairygui/core";
+import { ApplyUamTransactionAppError } from "@openfairygui/functions";
+import { Stats } from "node:fs";
+
+//#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 BackendFileSystem {
+  stat(filePath: string): Promise<Stats>;
+  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 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', '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: 'deferred';
+  };
+  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;
+}
+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 | ApplyUamTransactionAppError;
+interface ApplySessionTransactionInput {
+  sessionId: string;
+  expectedRevision: number;
+  operations: UamTransactionOperation[];
+}
+interface BackendRuntimeOptions {
+  fileSystem?: BackendFileSystem;
+}
+declare function createNodeBackendFileSystem(): BackendFileSystem;
+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>>;
+  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>>;
+  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 { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileSystem, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type RefreshCacheInput, type SavePartialFailureError, type SessionNotFoundError, type SessionStaleWriteError, createNodeBackendFileSystem };