@proletariat/cli 0.1.4 → 0.3.0

package/dist/lib/pmo/types.d.ts

@@ -0,0 +1,710 @@
+/**
+ * PMO Interface Types
+ *
+ * Canonical interface for the Project Management Orchestration system.
+ * All storage backends must implement the PMOStorage interface.
+ *
+ * Hierarchy:
+ * - Initiative (optional) - OKR-level grouping
+ * - Project - Discrete effort with its own board + specs
+ * - Epic (optional) - Large body of work within a project
+ * - Ticket - Individual work item
+ * - Subtask - Smallest actionable piece
+ */
+export interface Initiative {
+    id: string;
+    name: string;
+    objective?: string;
+    keyResults?: string[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Project {
+    id: string;
+    name: string;
+    template?: string;
+    description?: string;
+    status: ProjectStatus;
+    phaseId?: string;
+    workflowId?: string;
+    isArchived: boolean;
+    targetDate?: Date;
+    initiativeId?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Epic status lifecycle
+ */
+export type EpicStatus = 'active' | 'draft' | 'complete' | 'dropped' | 'future';
+/**
+ * Epic represents a work container that groups related tickets
+ * and tracks progress through lifecycle statuses.
+ */
+export interface Epic {
+    id: string;
+    projectId: string;
+    title: string;
+    description?: string;
+    status: EpicStatus;
+    position: number;
+    filePath?: string;
+    specId?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * @deprecated TicketStatus enum removed. Use statusId reference to WorkflowStatus instead.
+ * Kept as type alias for backward compatibility during transition.
+ */
+export type TicketStatus = string;
+/**
+ * Standardized priority values: P0 (critical) through P3 (low).
+ */
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+/**
+ * Valid priority values as a const array for validation and CLI options.
+ */
+export declare const PRIORITIES: readonly Priority[];
+/**
+ * Priority display names for UI presentation.
+ */
+export declare const PRIORITY_LABELS: Record<Priority, string>;
+/**
+ * Legacy priority values for backwards compatibility.
+ */
+export type LegacyPriority = 'URGENT' | 'HIGH' | 'MEDIUM' | 'LOW';
+/**
+ * Mapping from legacy priority values to new P0-P3 format.
+ */
+export declare const LEGACY_PRIORITY_MAP: Record<LegacyPriority, Priority>;
+/**
+ * Ticket categories for classification.
+ */
+export declare const TICKET_CATEGORIES: readonly ["feature", "bug", "refactor", "docs", "test", "chore", "performance", "ci", "build", "security", "database", "release"];
+export type TicketCategory = typeof TICKET_CATEGORIES[number];
+/**
+ * Check if a string is a valid Priority value.
+ */
+export declare function isValidPriority(value: string | undefined | null): value is Priority;
+/**
+ * Check if a string is a legacy priority value.
+ */
+export declare function isLegacyPriority(value: string | undefined | null): value is LegacyPriority;
+/**
+ * Normalize a priority value to the new P0-P3 format.
+ * Converts legacy values (URGENT/HIGH/MEDIUM/LOW) to P0-P3.
+ * Returns undefined for invalid values.
+ */
+export declare function normalizePriority(value: string | undefined | null): Priority | undefined;
+/**
+ * Fixed state categories - the semantic buckets that statuses belong to.
+ * These cannot be added, removed, or reordered.
+ *
+ * Order: triage < backlog < unstarted < started < completed < canceled
+ */
+export type StateCategory = 'triage' | 'backlog' | 'unstarted' | 'started' | 'completed' | 'canceled';
+/**
+ * State category order for sorting columns/statuses
+ */
+export declare const STATE_CATEGORY_ORDER: readonly StateCategory[];
+/**
+ * Shared workflow definition.
+ * Projects reference workflows via workflowId.
+ * Updating a workflow affects all projects using it.
+ */
+export interface Workflow {
+    id: string;
+    name: string;
+    description?: string;
+    isBuiltin: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Status within a shared workflow.
+ * Each status belongs to exactly one StateCategory.
+ * Status names must be unique within a workflow.
+ * These are the board columns - workflows define the columns for all projects using them.
+ */
+export interface WorkflowStatus {
+    id: string;
+    workflowId: string;
+    name: string;
+    category: StateCategory;
+    position: number;
+    color?: string;
+    description?: string;
+    isDefault?: boolean;
+    createdAt: Date;
+}
+/**
+ * @deprecated Legacy per-project status - use WorkflowStatus instead.
+ * Kept for backward compatibility during migration.
+ */
+export interface LegacyWorkflowStatus {
+    id: string;
+    projectId: string;
+    name: string;
+    category: StateCategory;
+    position: number;
+    color?: string;
+    description?: string;
+    isDefault?: boolean;
+    createdAt: Date;
+}
+/**
+ * Workflow template - a preset status configuration.
+ * Templates are copied when applied, not referenced.
+ */
+export interface WorkflowTemplate {
+    id: string;
+    name: string;
+    description?: string;
+    isBuiltin: boolean;
+    statuses: WorkflowTemplateStatus[];
+    createdAt: Date;
+}
+/**
+ * Status definition within a template (no projectId since templates are reusable)
+ */
+export interface WorkflowTemplateStatus {
+    name: string;
+    category: StateCategory;
+    position: number;
+    color?: string;
+}
+/**
+ * Project lifecycle status (fixed, not customizable)
+ * @deprecated Use phaseId reference to workspace's phase configuration instead.
+ */
+export type ProjectStatus = 'draft' | 'active' | 'completed' | 'archived';
+/**
+ * Project lifecycle phase (workspace-scoped, customizable)
+ * Each phase belongs to exactly one StateCategory.
+ * Phase names must be unique within a workspace.
+ */
+export interface ProjectPhase {
+    id: string;
+    name: string;
+    category: StateCategory;
+    position: number;
+    color?: string;
+    description?: string;
+    isDefault?: boolean;
+    createdAt: Date;
+}
+/**
+ * Phase template - a preset phase configuration.
+ * Templates are copied when applied, not referenced.
+ */
+export interface PhaseTemplate {
+    id: string;
+    name: string;
+    description?: string;
+    isBuiltin: boolean;
+    phases: PhaseTemplatePhase[];
+    createdAt: Date;
+}
+/**
+ * Phase definition within a template (reusable across workspaces)
+ */
+export interface PhaseTemplatePhase {
+    name: string;
+    category: StateCategory;
+    position: number;
+    color?: string;
+    description?: string;
+    isDefault?: boolean;
+}
+/**
+ * Work action - defines what an agent should do with a ticket.
+ * Actions are reusable prompts that can be applied to any ticket.
+ */
+export interface WorkAction {
+    id: string;
+    name: string;
+    description?: string;
+    prompt: string;
+    endPrompt?: string;
+    suggestedForCategories?: StateCategory[];
+    defaultMoveToCategory?: StateCategory;
+    modifiesCode: boolean;
+    isBuiltin: boolean;
+    createdAt: Date;
+}
+/**
+ * Board represents a project's kanban board view.
+ * This is what gets rendered to board.md and displayed in the UI.
+ */
+export interface Board {
+    id: string;
+    name: string;
+    columns: Column[];
+    updatedAt: Date;
+}
+/**
+ * BoardView represents a saved, filtered view of a project's board.
+ * Allows users to save common filter configurations like "My Tasks" or "High Priority".
+ */
+export interface BoardView {
+    id: string;
+    projectId: string;
+    name: string;
+    description?: string;
+    isDefault?: boolean;
+    filters: BoardViewFilters;
+    groupBy?: BoardViewGroupBy;
+    sortBy?: BoardViewSortBy;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Filter configuration for a board view.
+ * All filters are optional - unset filters show all items.
+ */
+export interface BoardViewFilters {
+    assignee?: string;
+    owner?: string;
+    priority?: string;
+    statusCategory?: StateCategory;
+    statusId?: string;
+    columnIds?: string[];
+    epicId?: string;
+    search?: string;
+}
+/**
+ * Grouping options for board view
+ */
+export type BoardViewGroupBy = 'assignee' | 'priority' | 'epic' | 'status' | 'category';
+/**
+ * Sorting options for board view
+ */
+export type BoardViewSortBy = 'priority' | 'created' | 'updated' | 'title' | 'assignee';
+export interface Column {
+    id: string;
+    name: string;
+    position: number;
+    status?: string;
+    tickets: Ticket[];
+}
+/**
+ * Ticket represents a work item (core entity - no board position here)
+ */
+export interface Ticket {
+    id: string;
+    title: string;
+    description?: string;
+    priority?: string;
+    category?: string;
+    projectId?: string;
+    projectName?: string;
+    statusId: string;
+    statusName?: string;
+    statusCategory?: StateCategory;
+    /**
+     * @deprecated Use statusCategory for logic, statusName for display
+     * This is a temporary alias that maps old status values to categories
+     */
+    status?: TicketStatus;
+    owner?: string;
+    assignee?: string;
+    branch?: string;
+    specId?: string;
+    epicId?: string;
+    subtasks: Subtask[];
+    labels: string[];
+    metadata: Record<string, string>;
+    blockedBy?: string[];
+    affectedPaths?: TicketAffectedPath[];
+    acceptanceCriteria?: AcceptanceCriterion[];
+    createdAt: Date;
+    updatedAt: Date;
+    lastSyncedFromSpec?: Date;
+    lastSyncedFromBoard?: Date;
+    position?: number;
+}
+/**
+ * BoardTicket represents where a ticket appears on the board (view state)
+ */
+export interface BoardTicket {
+    projectId: string;
+    ticketId: string;
+    columnId: string;
+    position: number;
+}
+export interface Subtask {
+    id: string;
+    title: string;
+    done: boolean;
+}
+/**
+ * Input for creating a new ticket.
+ * statusName is the status/column name to place the ticket in.
+ */
+export interface CreateTicketInput {
+    id?: string;
+    title: string;
+    statusName?: string;
+    description?: string;
+    priority?: string;
+    category?: string;
+    statusId?: string;
+    owner?: string;
+    assignee?: string;
+    specId?: string;
+    epicId?: string;
+    labels?: string[];
+    subtasks?: Subtask[];
+    metadata?: Record<string, string>;
+    lastSyncedFromSpec?: Date;
+    lastSyncedFromBoard?: Date;
+}
+/**
+ * Subtask definition within a ticket template
+ */
+export interface TicketTemplateSubtask {
+    title: string;
+}
+/**
+ * Ticket template - a reusable configuration for creating tickets.
+ * Templates can be built-in (system-provided) or custom (user-created).
+ */
+export interface TicketTemplate {
+    id: string;
+    name: string;
+    description?: string;
+    isBuiltin: boolean;
+    titlePattern?: string;
+    descriptionTemplate?: string;
+    defaultPriority?: string;
+    defaultCategory?: string;
+    defaultStatusId?: string;
+    defaultAssignee?: string;
+    defaultOwner?: string;
+    defaultLabels: string[];
+    suggestedSubtasks: TicketTemplateSubtask[];
+    createdAt: Date;
+}
+/**
+ * Filter options for listing ticket templates
+ */
+export interface TicketTemplateFilter {
+    isBuiltin?: boolean;
+    search?: string;
+}
+/**
+ * Affected path hint for agent context scoping.
+ * Tells agents which files/directories are relevant to a ticket.
+ */
+export interface TicketAffectedPath {
+    id?: number;
+    ticketId: string;
+    pathPattern: string;
+    pathType: 'file' | 'directory' | 'glob';
+    createdAt?: Date;
+}
+/**
+ * Structured acceptance criterion for verifiable completion.
+ * Allows programmatic verification rather than markdown parsing.
+ */
+export interface AcceptanceCriterion {
+    id: string;
+    ticketId: string;
+    criterion: string;
+    verifiable: boolean;
+    verified: boolean;
+    verifiedAt?: Date;
+    verifiedBy?: string;
+    position: number;
+}
+/**
+ * Ticket dependency types for same-entity relationships
+ */
+export type TicketDependencyType = 'blocks' | 'relates_to' | 'duplicates';
+/**
+ * Ticket dependency for scheduling.
+ * Represents a dependency relationship between tickets.
+ */
+export interface TicketDependency {
+    ticketId: string;
+    dependsOnTicketId: string;
+    dependencyType: TicketDependencyType;
+    createdAt?: Date;
+}
+/**
+ * Spec dependency types
+ */
+export type SpecDependencyType = 'depends_on' | 'relates_to' | 'duplicates';
+/**
+ * Spec dependency for design ordering.
+ */
+export interface SpecDependency {
+    specId: string;
+    dependsOnSpecId: string;
+    dependencyType: SpecDependencyType;
+    createdAt?: Date;
+}
+/**
+ * Epic dependency types
+ */
+export type EpicDependencyType = 'blocks' | 'relates_to' | 'duplicates';
+/**
+ * Epic dependency for phased work.
+ */
+export interface EpicDependency {
+    epicId: string;
+    dependsOnEpicId: string;
+    dependencyType: EpicDependencyType;
+    createdAt?: Date;
+}
+/**
+ * Spec type - determines directory location and format
+ */
+export type SpecType = 'product' | 'platform' | 'infra' | 'integration';
+/**
+ * Spec status - lifecycle state
+ */
+export type SpecStatus = 'draft' | 'active' | 'implemented';
+/**
+ * Spec - a living document describing ideal state
+ */
+export interface Spec {
+    id: string;
+    title: string;
+    status: SpecStatus;
+    type?: SpecType;
+    tags?: string[];
+    dependsOn?: string[];
+    problem?: string;
+    solution?: string;
+    decisions?: string;
+    notNow?: string;
+    uiUx?: string;
+    acceptanceCriteria?: string;
+    openQuestions?: string;
+    requirementsFunctional?: string;
+    requirementsTechnical?: string;
+    context?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface BoardConfig {
+    name?: string;
+    columns?: string[];
+    mode?: 'in-repo' | 'separate-repo';
+    repo?: string;
+    branch?: string;
+    path?: string;
+}
+export interface SyncConfig {
+    autoPull: boolean;
+    autoPush: boolean;
+    conflictStrategy: 'manual' | 'theirs' | 'ours';
+}
+export interface PMOConfig {
+    version: number;
+    storage: {
+        type: 'sqlite' | 'git' | 'cloud' | 'adapter';
+        mode?: 'in-repo' | 'separate-repo';
+        repo?: string;
+        branch?: string;
+        path?: string;
+        connection?: string;
+    };
+    board: BoardConfig;
+    sync: SyncConfig;
+}
+export interface TicketFilter {
+    statusId?: string;
+    statusCategory?: StateCategory;
+    priority?: string;
+    category?: string;
+    owner?: string;
+    assignee?: string;
+    search?: string;
+    spec?: string;
+    epic?: string;
+    column?: string;
+    projectId?: string;
+    allProjects?: boolean;
+}
+export interface SpecFilter {
+    status?: SpecStatus;
+    type?: SpecType;
+    tags?: string[];
+    search?: string;
+}
+export interface EpicFilter {
+    status?: EpicStatus;
+    search?: string;
+}
+export interface StatusFilter {
+    workflowId?: string;
+    projectId?: string;
+    category?: StateCategory;
+    search?: string;
+}
+export interface WorkflowFilter {
+    isBuiltin?: boolean;
+    search?: string;
+}
+export interface TemplateFilter {
+    isBuiltin?: boolean;
+    search?: string;
+}
+export interface PhaseFilter {
+    category?: StateCategory;
+    search?: string;
+}
+export interface PhaseTemplateFilter {
+    isBuiltin?: boolean;
+    search?: string;
+}
+export interface WorkActionFilter {
+    isBuiltin?: boolean;
+    suggestedFor?: StateCategory;
+    search?: string;
+}
+export interface ProjectFilter {
+    phaseId?: string;
+    isArchived?: boolean;
+    search?: string;
+}
+export interface BoardViewFilter {
+    projectId?: string;
+    isDefault?: boolean;
+    search?: string;
+}
+export interface SyncResult {
+    success: boolean;
+    changes: number;
+    conflicts?: Conflict[];
+}
+export interface SyncStatus {
+    ahead: number;
+    behind: number;
+    conflicts: boolean;
+}
+export interface Conflict {
+    type: string;
+    ticketId?: string;
+    description?: string;
+    message?: string;
+}
+export type PMOErrorCode = 'NOT_FOUND' | 'CONFLICT' | 'INVALID' | 'SYNC_FAILED' | 'NO_PROJECT';
+export declare class PMOError extends Error {
+    code: PMOErrorCode;
+    ticketId?: string | undefined;
+    constructor(code: PMOErrorCode, message: string, ticketId?: string | undefined);
+}
+export interface PMOStorage {
+    readonly type: 'sqlite' | 'git' | 'cloud' | 'adapter';
+    init(projectId: string, config: BoardConfig): Promise<Board>;
+    getBoard(projectId: string): Promise<Board>;
+    getBoardMarkdown(projectId: string): Promise<string>;
+    getColumnNames(projectId: string): string[];
+    createColumn(projectId: string, name: string, position?: number): Promise<Column>;
+    renameColumn(projectId: string, id: string, name: string): Promise<Column>;
+    moveColumn(projectId: string, id: string, position: number): Promise<Column>;
+    deleteColumn(projectId: string, id: string, cascade?: boolean): Promise<void>;
+    createTicket(projectId: string, ticket: CreateTicketInput): Promise<Ticket>;
+    getTicket(id: string): Promise<Ticket | null>;
+    updateTicket(id: string, changes: Partial<Ticket>): Promise<Ticket>;
+    moveTicket(projectId: string, id: string, column: string, position?: number): Promise<Ticket>;
+    moveTicketToProject(ticketId: string, newProjectId: string): Promise<Ticket>;
+    deleteTicket(id: string): Promise<void>;
+    listTickets(projectId: string | undefined, filter?: TicketFilter): Promise<Ticket[]>;
+    addSubtask(ticketId: string, title: string): Promise<Subtask>;
+    toggleSubtask(ticketId: string, subtaskId: string): Promise<Subtask>;
+    removeSubtask(ticketId: string, subtaskId: string): Promise<void>;
+    createSpec(spec: Partial<Spec>): Promise<Spec>;
+    getSpec(id: string): Promise<Spec | null>;
+    listSpecs(filter?: SpecFilter): Promise<Spec[]>;
+    updateSpec(id: string, changes: Partial<Spec>): Promise<Spec>;
+    deleteSpec(id: string): Promise<void>;
+    linkTicketToSpec(ticketId: string, specId: string): Promise<void>;
+    unlinkTicketFromSpec(ticketId: string, specId: string): Promise<void>;
+    getTicketsForSpec(projectId: string, specId: string): Promise<Ticket[]>;
+    getSpecsForTicket(ticketId: string): Promise<Spec[]>;
+    addSpecDependency(specId: string, dependsOnId: string): Promise<void>;
+    removeSpecDependency(specId: string, dependsOnId: string): Promise<void>;
+    getSpecDependencies(specId: string): Promise<Spec[]>;
+    getSpecDependents(specId: string): Promise<Spec[]>;
+    linkProjectToSpec(projectId: string, specId: string): Promise<void>;
+    unlinkProjectFromSpec(projectId: string, specId: string): Promise<void>;
+    getSpecsForProject(projectId: string): Promise<Spec[]>;
+    getProjectsForSpec(specId: string): Promise<Project[]>;
+    createEpic(projectId: string, epic: Partial<Epic>): Promise<Epic>;
+    getEpic(id: string): Promise<Epic | null>;
+    listEpics(projectId: string, filter?: EpicFilter): Promise<Epic[]>;
+    reorderEpic(projectId: string, epicId: string, newPosition: number): Promise<Epic>;
+    updateEpic(id: string, changes: Partial<Epic>): Promise<Epic>;
+    deleteEpic(id: string): Promise<void>;
+    getTicketsForEpic(projectId: string, epicId: string): Promise<Ticket[]>;
+    linkTicketToEpic(ticketId: string, epicId: string): Promise<void>;
+    unlinkTicketFromEpic(ticketId: string): Promise<void>;
+    listWorkflows(filter?: WorkflowFilter): Promise<Workflow[]>;
+    getWorkflow(id: string): Promise<Workflow | null>;
+    createWorkflow(workflow: Partial<Workflow>): Promise<Workflow>;
+    updateWorkflow(id: string, changes: Partial<Workflow>): Promise<Workflow>;
+    deleteWorkflow(id: string): Promise<void>;
+    getProjectWorkflow(projectId: string): Promise<Workflow | null>;
+    listStatuses(workflowId: string): Promise<WorkflowStatus[]>;
+    getStatus(id: string): Promise<WorkflowStatus | null>;
+    createStatus(workflowId: string, status: Partial<WorkflowStatus>): Promise<WorkflowStatus>;
+    updateStatus(id: string, changes: Partial<WorkflowStatus>): Promise<WorkflowStatus>;
+    deleteStatus(id: string): Promise<void>;
+    reorderStatus(id: string, newPosition: number): Promise<WorkflowStatus>;
+    getDefaultStatus(workflowId: string): Promise<WorkflowStatus | null>;
+    listTicketTemplates(filter?: TicketTemplateFilter): Promise<TicketTemplate[]>;
+    getTicketTemplate(id: string): Promise<TicketTemplate | null>;
+    createTicketTemplate(template: Partial<TicketTemplate> & {
+        name: string;
+    }): Promise<TicketTemplate>;
+    createTicketTemplateFromTicket(ticketId: string, name: string, description?: string): Promise<TicketTemplate>;
+    updateTicketTemplate(id: string, changes: Partial<TicketTemplate>): Promise<TicketTemplate>;
+    deleteTicketTemplate(id: string): Promise<void>;
+    listPhases(filter?: PhaseFilter): Promise<ProjectPhase[]>;
+    getPhase(id: string): Promise<ProjectPhase | null>;
+    createPhase(phase: Partial<ProjectPhase>): Promise<ProjectPhase>;
+    updatePhase(id: string, changes: Partial<ProjectPhase>): Promise<ProjectPhase>;
+    deletePhase(id: string): Promise<void>;
+    reorderPhase(id: string, newPosition: number): Promise<ProjectPhase>;
+    getDefaultPhase(): Promise<ProjectPhase | null>;
+    listPhaseTemplates(filter?: PhaseTemplateFilter): Promise<PhaseTemplate[]>;
+    getPhaseTemplate(id: string): Promise<PhaseTemplate | null>;
+    applyPhaseTemplate(templateId: string): Promise<ProjectPhase[]>;
+    savePhaseTemplate(name: string, description?: string): Promise<PhaseTemplate>;
+    updatePhaseTemplate(id: string, changes: {
+        name?: string;
+        description?: string;
+    }): Promise<PhaseTemplate>;
+    deletePhaseTemplate(id: string): Promise<void>;
+    listActions(filter?: WorkActionFilter): Promise<WorkAction[]>;
+    getAction(id: string): Promise<WorkAction | null>;
+    createAction(action: Partial<WorkAction>): Promise<WorkAction>;
+    updateAction(id: string, changes: Partial<WorkAction>): Promise<WorkAction>;
+    deleteAction(id: string): Promise<void>;
+    getSuggestedAction(category: StateCategory): Promise<WorkAction | null>;
+    getProject(id: string): Promise<Project | null>;
+    createProject(project: Partial<Project> & {
+        template?: string;
+    }): Promise<Board>;
+    updateProject(id: string, changes: Partial<Project>): Promise<Project>;
+    listProjects(filter?: ProjectFilter): Promise<Project[]>;
+    archiveProject(id: string): Promise<Project>;
+    unarchiveProject(id: string): Promise<Project>;
+    listBoardViews(filter?: BoardViewFilter): Promise<BoardView[]>;
+    getBoardView(id: string): Promise<BoardView | null>;
+    createBoardView(view: Partial<BoardView>): Promise<BoardView>;
+    updateBoardView(id: string, changes: Partial<BoardView>): Promise<BoardView>;
+    deleteBoardView(id: string): Promise<void>;
+    getDefaultBoardView(projectId: string): Promise<BoardView | null>;
+    getBoardWithView(projectId: string, viewId?: string, filters?: BoardViewFilters): Promise<Board>;
+    pull(): Promise<SyncResult>;
+    push(): Promise<SyncResult>;
+    status(): Promise<SyncStatus>;
+    close(): Promise<void>;
+}
+export type UpdateTicketInput = Omit<Partial<Ticket>, 'id' | 'createdAt' | 'updatedAt'>;