/**
 * The wire contract between this package's hub API and its cockpit client:
 * one run's terminal, and the files its run directory holds.
 *
 * Both halves of the cockpit import these names, so the route strings and the
 * event names live here rather than being spelled twice.
 */

/**
 * Segment this package's API is mounted under, below /api/plugins/.
 *
 * The same word names `src/extensions/(backend)/api/workflow/`, which is where
 * the build reads the mount for the browser's client, so the two cannot drift.
 * The routes themselves are declared in `apiRoutes.ts`.
 */
export const WORKFLOW_API_BASE_PATH = 'workflow';

/** The SSE event name the screen stream writes. */
export const WORKFLOW_SCREEN_EVENT = 'screen';

/** What a surface may do with one run's terminal, and why anything is missing. */
export interface WorkflowTerminalCapabilitiesView {
  readable: boolean;
  writable: boolean;
  resizable: boolean;
  reason?: string;
}

/** One frame of a run's terminal, as the stream pushes it. */
export interface WorkflowScreenEvent {
  /** The visible screen, newest line last, carrying the colour the run printed. */
  lines: string[];
  capabilities: WorkflowTerminalCapabilitiesView;
  /** True once the run has settled, after which the stream ends. */
  ended?: boolean;
}

/** Answer to taking or releasing the keyboard for one run. */
export interface WorkflowControlResponse {
  /** True when this caller now holds the keyboard. */
  held: boolean;
  /** The token later writes must carry; absent when control was refused or released. */
  token?: string;
  /** Why control was refused, worded for a reader. */
  reason?: string;
}

/** Answer after a settled run and its directory have been permanently removed. */
export interface WorkflowDeleteResponse {
  deleted: true;
}

/** How a declared run-directory entry compares with what is on disk. */
export type WorkflowArtifactState = 'written' | 'empty' | 'pending' | 'unreadable';

/** One file or directory in a run's own folder. */
export interface WorkflowArtifactView {
  /** Path relative to the run directory, which is also the read route's parameter. */
  path: string;
  kind: 'file' | 'directory';
  /** What the workflow says this file is for; empty for a file it never declared. */
  description: string;
  /** The jobs the workflow says write it. */
  producedBy: string[];
  /** True when the workflow's run-directory block names this entry. */
  declared: boolean;
  state: WorkflowArtifactState;
  /** Bytes on disk, absent until the file exists. */
  size?: number;
  /** ISO 8601 of the last write, absent until the file exists. */
  modifiedAt?: string;
}

export interface WorkflowArtifactsResponse {
  /** Absolute path of the run's own directory, which the reader may want to open. */
  runDir: string;
  /** What the workflow says the directory is for. */
  description: string;
  artifacts: WorkflowArtifactView[];
}

/** One artifact's metadata and optional text, as the viewer tab reads it. */
export interface WorkflowArtifactContentResponse {
  path: string;
  size: number;
  modifiedAt: string;
  /** Media type inferred from the file extension by the trusted hub. Absent on older hubs. */
  mimeType?: string;
  /** Present for text formats; binary files are streamed from the raw route instead. */
  text?: string;
  /** True when textual content was longer than the reader's byte budget. */
  truncated: boolean;
}