import type { SpawnOptions } from 'node:child_process';
import type { PygmalionRevisionCatalog } from './dist-lib/types/editor/revisionCatalog.js';

export interface WorkspaceDraftProcessOptions extends Omit<SpawnOptions, 'signal' | 'detached' | 'stdio' | 'timeout' | 'killSignal'> {
  signal?: AbortSignal;
  /** Milliseconds before cancellation. Zero disables the deadline. Default: 240,000. */
  timeout?: number;
  /** Milliseconds between SIGTERM and SIGKILL. Default: 1,000. */
  terminationGraceMs?: number;
  /** Maximum bytes per output stream. Default: 8 MiB. */
  maxBuffer?: number;
}

/** macOS/Linux: waits for process-group cleanup on success, failure, cancellation, and timeout. */
export declare function executeWorkspaceDraftProcess(
  command: string, args: readonly string[], options?: WorkspaceDraftProcessOptions,
): Promise<{ stdout: string; stderr: string }>;

export interface RevisionCatalogResolver {
  /** Only complete SHA-1 or SHA-256 commits are accepted; returned catalogs are frozen copies. */
  resolve(sourceRevision: string, signal?: AbortSignal): Promise<PygmalionRevisionCatalog>;
  currentRevision(signal?: AbortSignal): Promise<string>;
  /** Least recently used first; expired and current-build entries are omitted. */
  retained(): string[];
  /** Cancels owned generation, discards cached results, and rejects subsequent requests. */
  dispose(): void;
}

export interface RevisionCatalogResolverOptions {
  projectRoot?: string;
  /** Repository-relative application directory. Default: the repository root. */
  appDirectory?: string;
  currentCatalog(signal?: AbortSignal): unknown | Promise<unknown>;
  generate(context: { archiveRoot: string; sourceRevision: string; signal: AbortSignal }): unknown | Promise<unknown>;
  /** Defaults to commits reachable from HEAD or repository branches, remotes, and tags. */
  reachable?(sourceRevision: string, signal: AbortSignal): boolean | Promise<boolean>;
  /** Custom extraction must await its callback and stop workers before removing source files. */
  archive?<T>(sourceRevision: string, signal: AbortSignal,
    operation: (context: Readonly<{ appRoot: string; sourceRevision: string; signal: AbortSignal }>) => Promise<T>): Promise<T>;
  /** Defaults to 4 archived catalogs; zero disables retention. */
  maxEntries?: number;
  /** Absolute lifetime since generation, in milliseconds. Default: 30 minutes. */
  maxAgeMs?: number;
}

/** Shares requests for each revision and serializes archive/build work across revisions. */
export declare function createRevisionCatalogResolver(options: RevisionCatalogResolverOptions): RevisionCatalogResolver;

/** Returns dependency search paths from the first byte-identical lockfile, or [] for an archive-local install. */
export declare function resolveSourceArchiveDependencies(options: {
  archiveRoot: string; dependencyRoots: readonly string[]; lockfile?: string;
}): Promise<string[]>;

/** Rejects host worktrees, Git metadata, and missing or linked required directories. */
export declare function assertIsolatedSourceRoot(options: {
  archiveRoot: string; hostRoot: string; requiredDirectories?: readonly string[];
}): Promise<string>;

/** Converts SIGTERM/SIGINT into cancellation and exit status; dispose removes its process listeners. */
export declare function createWorkspaceDraftLifecycle(): Readonly<{
  signal: AbortSignal;
  dispose(): void;
}>;

/** Requires canonical source/output directories belonging to one SDK draft-preview temporary root. */
export declare function assertWorkspaceDraftDirectories(options: {
  appRoot: string; outputDirectory: string; appDirectory?: string;
}): Promise<Readonly<{ appRoot: string; outputDirectory: string; temporaryRoot: string }>>;

/** Imports the installed package's explicit exports['.'].import entry; no parent-install fallback. */
export declare function importIsolatedPackage<T = Record<string, unknown>>(options: {
  appRoot: string; name: string;
}): Promise<T>;