/**
 * Shared domain types for the Kanban API.
 *
 * These describe the shape of data exchanged with the docs frontend. The
 * frontend re-declares a compatible set in `kanbanApi.ts` (it cannot import
 * across packages without a build step); keep them in sync.
 */

/** Kanban columns, in left-to-right board order. */
export type Column = 'done' | 'in-progress' | 'todo' | 'backlog';

export const COLUMNS: Column[] = ['done', 'in-progress', 'todo', 'backlog'];

export function isColumn(value: unknown): value is Column {
  return typeof value === 'string' && (COLUMNS as string[]).includes(value);
}

export type ReferenceType = 'doc' | 'code' | 'demo' | 'external' | 'custom';

/** A cross-reference shown on a card — usually a link to a design doc page. */
export interface Reference {
  label: string;
  type: ReferenceType;
  href: string;
  /** Canonical references are protected and cannot be removed by users. */
  removable: boolean;
}

export interface Comment {
  id: string;
  cardId: string;
  text: string;
  author: string;
  /** Epoch milliseconds. */
  createdAt: number;
}

export interface Card {
  id: string;
  title: string;
  description: string;
  details: string;
  category: string;
  files: string | null;
  notes: string | null;
  status: Column;
  sortOrder: number;
  comments: Comment[];
  tags: string[];
  references: Reference[];
}

export interface Board {
  cards: Card[];
  lastUpdated: string;
}

export interface DocPage {
  path: string;
  title: string;
  icon: string;
  blurb: string;
}

/** A user-created documentation page. Before beautification, `content` is raw
 * markdown-ish source and `html` is its rendered form; after beautification,
 * `content` is overwritten with the AI-authored HTML (which also equals
 * `html`). `beautified` records which state the page is in. */
export interface CustomPage {
  id: string;
  slug: string;
  title: string;
  icon: string;
  blurb: string;
  content: string;
  html: string;
  beautified: boolean;
  createdAt: string;
  updatedAt: string;
}

// --- Agentic orchestrator --------------------------------------------------

/** Lifecycle state of an agent run. */
export type RunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'stopped';

/** A single agent run working one kanban card inside a git worktree. */
export interface AgentRun {
  id: string;
  cardId: string;
  status: RunStatus;
  useWorktree: boolean;
  /** Whether this run created (and therefore owns/cleans up) its worktree.
   * Refinement runs inherit a prior run's worktree and set this to false. */
  ownsWorktree: boolean;
  branch: string | null;
  worktreePath: string | null;
  /** pi session JSONL path persisted for this run (resumable by refinements). */
  sessionFile: string | null;
  prompt: string;
  summary: string | null;
  commitSha: string | null;
  error: string | null;
  createdAt: string;
  startedAt: string | null;
  finishedAt: string | null;
}

/** A slim, replayable event emitted during a run (persisted + streamed). */
export interface AgentRunEvent {
  id: number;
  runId: string;
  seq: number;
  type: string;
  data: Record<string, unknown>;
  createdAt: string;
}
