@kitsy/coop-core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,670 @@
+declare const ITEM_TYPES: readonly ["epic", "story", "task", "bug", "spike"];
+type ItemType = (typeof ITEM_TYPES)[number];
+declare const ITEM_STATUSES: readonly ["todo", "in_progress", "blocked", "done"];
+type ItemStatus = (typeof ITEM_STATUSES)[number];
+interface ItemLinks {
+    github_issue?: string;
+    github_pr?: string;
+}
+interface AgentSpec {
+    goal?: string;
+    context_paths?: string[];
+    commands?: {
+        build?: string;
+        test?: string;
+        lint?: string;
+        [key: string]: string | undefined;
+    };
+    constraints?: string[];
+    risks?: string[];
+    prompt_hints?: string[];
+}
+interface BacklogItemData {
+    id: string;
+    type: ItemType;
+    title: string;
+    status: ItemStatus;
+    created: string;
+    updated: string;
+    priority?: string;
+    points?: number;
+    owner?: string;
+    labels?: string[];
+    links?: ItemLinks;
+    depends_on?: string[];
+    acceptance?: string[];
+    agent?: AgentSpec;
+    parent_id?: string;
+}
+interface BacklogItem extends BacklogItemData {
+    body: string;
+    filePath: string;
+}
+interface RepoConfig {
+    spec_version: number;
+    id_prefix: string;
+    id_strategy?: "text" | "counter";
+    next_id?: number;
+}
+interface RepoState {
+    rootDir: string;
+    workspaceDir: ".coop";
+    config: RepoConfig;
+    items: BacklogItem[];
+    itemsById: Map<string, BacklogItem>;
+}
+interface CreateItemParams {
+    id?: string;
+    type: ItemType;
+    title: string;
+    status?: ItemStatus;
+    priority?: string;
+    points?: number;
+    owner?: string;
+    labels?: string[];
+    links?: ItemLinks;
+    depends_on?: string[];
+    acceptance?: string[];
+    agent?: AgentSpec;
+    parent_id?: string;
+    body?: string;
+}
+interface UpdateItemParams {
+    title?: string;
+    status?: ItemStatus;
+    type?: ItemType;
+    priority?: string;
+    points?: number;
+    owner?: string;
+    labels?: string[];
+    links?: ItemLinks;
+    depends_on?: string[];
+    acceptance?: string[];
+    agent?: AgentSpec;
+    body?: string;
+}
+interface FilterSpec {
+    status?: string;
+    owner?: string;
+    label?: string;
+    type?: ItemType | ItemType[] | string;
+    search?: string;
+}
+
+type ValueOf<T> = T[keyof T];
+declare const TaskType: {
+    readonly feature: "feature";
+    readonly bug: "bug";
+    readonly chore: "chore";
+    readonly spike: "spike";
+    readonly epic: "epic";
+};
+type TaskType = ValueOf<typeof TaskType>;
+declare const TaskStatus: {
+    readonly todo: "todo";
+    readonly blocked: "blocked";
+    readonly in_progress: "in_progress";
+    readonly in_review: "in_review";
+    readonly done: "done";
+    readonly canceled: "canceled";
+};
+type TaskStatus = ValueOf<typeof TaskStatus>;
+declare const TaskPriority: {
+    readonly p0: "p0";
+    readonly p1: "p1";
+    readonly p2: "p2";
+    readonly p3: "p3";
+};
+type TaskPriority = ValueOf<typeof TaskPriority>;
+declare const TaskComplexity: {
+    readonly trivial: "trivial";
+    readonly small: "small";
+    readonly medium: "medium";
+    readonly large: "large";
+    readonly unknown: "unknown";
+};
+type TaskComplexity = ValueOf<typeof TaskComplexity>;
+declare const TaskDeterminism: {
+    readonly high: "high";
+    readonly medium: "medium";
+    readonly low: "low";
+    readonly experimental: "experimental";
+};
+type TaskDeterminism = ValueOf<typeof TaskDeterminism>;
+declare const IdeaStatus: {
+    readonly captured: "captured";
+    readonly exploring: "exploring";
+    readonly promoted: "promoted";
+    readonly parked: "parked";
+    readonly rejected: "rejected";
+};
+type IdeaStatus = ValueOf<typeof IdeaStatus>;
+declare const DeliveryStatus: {
+    readonly planning: "planning";
+    readonly committed: "committed";
+    readonly in_progress: "in_progress";
+    readonly delivered: "delivered";
+    readonly canceled: "canceled";
+};
+type DeliveryStatus = ValueOf<typeof DeliveryStatus>;
+declare const ExecutorType: {
+    readonly human: "human";
+    readonly ai: "ai";
+    readonly ci: "ci";
+    readonly hybrid: "hybrid";
+};
+type ExecutorType = ValueOf<typeof ExecutorType>;
+declare const RunbookAction: {
+    readonly generate: "generate";
+    readonly run: "run";
+    readonly review: "review";
+    readonly test: "test";
+    readonly deploy: "deploy";
+};
+type RunbookAction = ValueOf<typeof RunbookAction>;
+declare const ArtifactType: {
+    readonly pr: "pr";
+    readonly migration: "migration";
+    readonly deployment: "deployment";
+    readonly document: "document";
+    readonly config: "config";
+};
+type ArtifactType = ValueOf<typeof ArtifactType>;
+declare const RiskLevel: {
+    readonly low: "low";
+    readonly medium: "medium";
+    readonly high: "high";
+    readonly critical: "critical";
+};
+type RiskLevel = ValueOf<typeof RiskLevel>;
+
+interface DeliveryBudget {
+    engineering_hours?: number;
+    cost_usd?: number;
+}
+interface DeliveryScope {
+    include: string[];
+    exclude: string[];
+}
+interface DeliveryRisk {
+    id: string;
+    description: string;
+    probability: RiskLevel;
+    impact: RiskLevel;
+    mitigation?: string;
+}
+interface DeliveryGovernance {
+    owner?: string;
+    stakeholders?: string[];
+    review_cadence?: string;
+}
+interface Delivery {
+    id: string;
+    name: string;
+    status: DeliveryStatus;
+    target_date: string | null;
+    started_date: string | null;
+    delivered_date: string | null;
+    budget: DeliveryBudget;
+    capacity_profiles: string[];
+    scope: DeliveryScope;
+    risks?: DeliveryRisk[];
+    governance?: DeliveryGovernance;
+}
+
+interface AvailabilityWindow {
+    from: string;
+    to: string;
+    hours_per_day: number;
+}
+interface EffectiveCapacity {
+    method: "computed" | "manual";
+    hours_per_week?: number;
+    tokens_per_day?: number;
+    compute_hours_per_week?: number;
+}
+interface HumanMember {
+    id: string;
+    role?: string;
+    hours_per_week?: number;
+    skills?: string[];
+    availability?: AvailabilityWindow[];
+}
+interface HumanResource {
+    id: string;
+    type: "human";
+    members: HumanMember[];
+    defaults?: {
+        hours_per_week?: number;
+    };
+    overhead?: {
+        meetings_percent?: number;
+        context_switch_percent?: number;
+    };
+    effective_capacity?: EffectiveCapacity;
+}
+interface AIAgent {
+    id: string;
+    provider?: string;
+    model?: string;
+    token_limit_per_day?: number;
+    concurrency?: number;
+    capabilities?: string[];
+}
+interface AIResource {
+    id: string;
+    type: "ai";
+    agents: AIAgent[];
+    routing?: {
+        default?: string;
+        complexity_large?: string;
+        spike?: string;
+    };
+    effective_capacity?: EffectiveCapacity;
+}
+interface ComputeNode {
+    id: string;
+    provider?: string;
+    gpu_hours_per_week?: number;
+    cpu_hours_per_week?: number;
+    availability_percent?: number;
+}
+interface ComputeResource {
+    id: string;
+    type: "compute";
+    nodes: ComputeNode[];
+    effective_capacity?: EffectiveCapacity;
+}
+type ResourceProfile = HumanResource | AIResource | ComputeResource;
+
+interface TaskCore {
+    id: string;
+    title: string;
+    type: TaskType;
+    status: TaskStatus;
+    created: string;
+    updated: string;
+}
+interface TaskPlanning {
+    priority?: TaskPriority;
+    track?: string;
+    assignee?: string | null;
+    depends_on?: string[];
+    tags?: string[];
+    delivery?: string | null;
+}
+interface TaskEstimate {
+    optimistic_hours: number;
+    expected_hours: number;
+    pessimistic_hours: number;
+}
+interface TaskResources {
+    human_hours?: number;
+    ai_tokens?: number;
+    compute_gpu_hours?: number;
+    cost_usd?: number;
+}
+interface TaskEstimation {
+    complexity?: TaskComplexity;
+    determinism?: TaskDeterminism;
+    estimate?: TaskEstimate;
+    resources?: TaskResources;
+}
+interface RunbookStep {
+    step: string;
+    action: RunbookAction;
+    command?: string;
+    description?: string;
+    output?: string;
+    success_criteria?: string;
+    reviewer?: string;
+}
+interface ExecutionPermissions {
+    read_paths?: string[];
+    write_paths?: string[];
+    allowed_commands?: string[];
+    forbidden_commands?: string[];
+}
+interface ExecutionConstraints {
+    max_tokens?: number;
+    max_duration_minutes?: number;
+    max_file_changes?: number;
+    require_tests?: boolean;
+}
+interface TaskExecution {
+    execution?: {
+        executor: ExecutorType;
+        agent?: string;
+        context?: {
+            paths?: string[];
+            files?: string[];
+            tasks?: string[];
+        };
+        runbook?: RunbookStep[];
+        permissions?: ExecutionPermissions;
+        constraints?: ExecutionConstraints;
+    };
+    artifacts?: {
+        produces?: Array<{
+            type: ArtifactType;
+            target?: string;
+            path?: string;
+        }>;
+    };
+}
+interface TaskGovernance {
+    governance?: {
+        owner?: string;
+        reviewer?: string;
+        approval_required?: boolean;
+        compliance_tags?: string[];
+    };
+    risk?: {
+        level?: RiskLevel;
+        probability?: number;
+        impact_hours?: number;
+        mitigation?: string;
+        contingency?: string;
+    };
+    metrics?: {
+        target_cycle_time_days?: number;
+    };
+    enterprise?: Record<string, unknown>;
+}
+type Task = TaskCore & TaskPlanning & TaskEstimation & TaskExecution & TaskGovernance;
+interface TaskComputed {
+    blocks: string[];
+    pert_hours: number | null;
+    pert_stddev: number | null;
+    readiness: "ready" | "blocked" | "waiting_review" | "done";
+    scheduling_score: number;
+    critical_path_member: boolean;
+    slack_hours: number;
+    depth: number;
+}
+
+interface Track {
+    id: string;
+    name: string;
+    capacity_profiles: string[];
+    constraints?: {
+        max_concurrent_tasks?: number;
+        allowed_types?: TaskType[];
+    };
+    dependencies?: {
+        upstream?: string[];
+        downstream?: string[];
+    };
+}
+
+interface TaskGraph {
+    nodes: Map<string, Task>;
+    forward: Map<string, Set<string>>;
+    reverse: Map<string, Set<string>>;
+    topological_order: string[];
+    tracks: Map<string, Track>;
+    resources: Map<string, ResourceProfile>;
+    deliveries: Map<string, Delivery>;
+}
+interface GraphValidationResult {
+    level: "error" | "warning";
+    invariant: "acyclicity" | "referential_integrity" | "terminal_convergence" | "status_consistency";
+    message: string;
+    task_ids?: string[];
+}
+
+interface BuildGraphContext {
+    tracks?: Map<string, Track>;
+    resources?: Map<string, ResourceProfile>;
+    deliveries?: Map<string, Delivery>;
+}
+declare function detect_cycle(graph: TaskGraph): string[] | null;
+declare function topological_sort(graph: TaskGraph): string[];
+declare function transitive_dependencies(graph: TaskGraph, taskId: string): Set<string>;
+declare function transitive_dependents(graph: TaskGraph, taskId: string): Set<string>;
+declare function build_graph(tasks: Task[], context?: BuildGraphContext): TaskGraph;
+
+declare function load_graph(coopDir: string): TaskGraph;
+
+declare function extract_subgraph(graph: TaskGraph, taskIds: string[]): TaskGraph;
+declare function find_external_dependencies(subgraph: TaskGraph, fullGraph: TaskGraph): string[];
+
+declare function validate_graph(graph: TaskGraph): GraphValidationResult[];
+
+interface CoopConfig {
+    version: number;
+    project: {
+        name: string;
+        id: string;
+    };
+    id_prefixes?: {
+        idea?: string;
+        task?: string;
+        delivery?: string;
+        run?: string;
+    };
+    defaults?: {
+        task?: {
+            type?: TaskType;
+            priority?: TaskPriority;
+            complexity?: TaskComplexity;
+            determinism?: TaskDeterminism;
+        };
+        track?: string;
+    };
+    scheduling?: {
+        algorithm?: "critical-path" | "priority-first" | "manual";
+        velocity_window_weeks?: number;
+        overhead_factor?: number;
+        weights?: Record<string, number>;
+    };
+    ai?: {
+        default_executor?: string;
+        sandbox?: boolean;
+        max_concurrent_agents?: number;
+        token_budget_per_task?: number;
+    };
+    plugins?: {
+        enabled?: string[];
+    };
+    hooks?: {
+        on_task_transition?: string;
+        on_delivery_complete?: string;
+    };
+}
+
+interface Idea {
+    id: string;
+    title: string;
+    created: string;
+    author: string;
+    status: IdeaStatus;
+    tags: string[];
+    source: string;
+    linked_tasks: string[];
+}
+
+interface ParsedDelivery {
+    delivery: Delivery;
+    body: string;
+    raw: Record<string, unknown>;
+}
+declare function parseDeliveryContent(content: string, source?: string): ParsedDelivery;
+declare function parseDeliveryFile(filePath: string): ParsedDelivery;
+
+interface FrontmatterParseResult {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+declare function parseFrontmatterContent(content: string, source?: string): FrontmatterParseResult;
+declare function parseFrontmatterFile(filePath: string): FrontmatterParseResult;
+declare function stringifyFrontmatter(frontmatter: Record<string, unknown>, body?: string): string;
+
+interface ParsedIdea {
+    idea: Idea;
+    body: string;
+    raw: Record<string, unknown>;
+}
+declare function parseIdeaContent(content: string, source?: string): ParsedIdea;
+declare function parseIdeaFile(filePath: string): ParsedIdea;
+
+interface ParsedTask {
+    task: Task;
+    body: string;
+    raw: Record<string, unknown>;
+}
+declare function parseTaskContent(content: string, source?: string): ParsedTask;
+declare function parseTaskFile(filePath: string): ParsedTask;
+
+interface WriteTaskOptions {
+    body?: string;
+    raw?: Record<string, unknown>;
+    filePath?: string;
+}
+declare function writeTask(task: Task, options?: WriteTaskOptions): string;
+
+declare function parseYamlContent<T extends object = Record<string, unknown>>(content: string, source?: string): T;
+declare function parseYamlFile<T extends object = Record<string, unknown>>(filePath: string): T;
+
+type ReadinessState = "ready" | "blocked" | "in_progress" | "waiting_review" | "done";
+interface ReadinessPartitions {
+    ready: Task[];
+    blocked: Task[];
+    in_progress: Task[];
+    waiting_review: Task[];
+    done: Task[];
+}
+interface ReadinessTransitionEvent {
+    type: "task.transitioned";
+    task_id: string;
+    from: "blocked";
+    to: "todo";
+    reason: string;
+}
+interface ReadinessWarning {
+    code: "todo_with_unresolved_dependencies";
+    task_id: string;
+    message: string;
+}
+interface ReadinessComputation {
+    readiness: Map<string, ReadinessState>;
+    partitions: ReadinessPartitions;
+    corrections: ReadinessTransitionEvent[];
+    warnings: ReadinessWarning[];
+}
+declare function compute_readiness(task: Task, graph: TaskGraph): ReadinessState;
+declare function compute_all_readiness(graph: TaskGraph): Map<string, ReadinessState>;
+declare function partition_by_readiness(graph: TaskGraph): ReadinessPartitions;
+declare function compute_readiness_with_corrections(graph: TaskGraph): ReadinessComputation;
+
+declare const CURRENT_SCHEMA_VERSION = 2;
+declare function read_schema_version(coopDir: string): number;
+declare function write_schema_version(coopDir: string, version: number): void;
+
+type TaskTransitionedEvent = {
+    type: "task.transitioned";
+    automated: true;
+    task_id: string;
+    from: TaskStatus;
+    to: TaskStatus;
+    reason: string;
+};
+type AutoTransitionResult = {
+    should_transition: boolean;
+    target_status?: TaskStatus;
+    event?: TaskTransitionedEvent;
+};
+type DependencyStatuses = Map<string, TaskStatus> | Record<string, TaskStatus>;
+declare function check_blocked(task: Task, dependencyStatuses?: DependencyStatuses): AutoTransitionResult;
+declare function check_unblocked(task: Task, dependencyStatuses?: DependencyStatuses): AutoTransitionResult;
+
+type TransitionContext = {
+    actor?: string;
+    dependencyStatuses?: Map<string, TaskStatus> | Record<string, TaskStatus>;
+    now?: string | Date;
+};
+type TransitionResult = {
+    success: boolean;
+    task: Task;
+    error?: string;
+};
+declare const VALID_TASK_TRANSITIONS: Map<TaskStatus, Set<TaskStatus>>;
+declare function transition(task: Task, targetStatus: TaskStatus, context?: TransitionContext): TransitionResult;
+
+type ValidationLevel = "error" | "warning";
+interface ValidationError {
+    level: ValidationLevel;
+    field: string;
+    message: string;
+    rule: string;
+}
+
+interface ReferentialValidationContext {
+    existingIds?: Set<string>;
+    currentTaskId?: string;
+    dependencyMap?: Map<string, string[]> | Record<string, string[]>;
+    tracks?: Set<string>;
+    deliveries?: Set<string>;
+    assignees?: Set<string>;
+    agents?: Set<string>;
+}
+declare function validateReferential(task: Task, context?: ReferentialValidationContext): ValidationError[];
+
+interface TrackWip {
+    inProgress: number;
+    limit: number;
+}
+interface SemanticValidationContext {
+    taskStatuses?: Map<string, Task["status"]> | Record<string, Task["status"]>;
+    trackWip?: Map<string, TrackWip> | Record<string, TrackWip>;
+    deliveryByTaskId?: Map<string, string> | Record<string, string>;
+    linkedSpikeTaskIds?: Set<string>;
+}
+declare function validateSemantic(task: Task, context?: SemanticValidationContext): ValidationError[];
+
+interface StructuralValidationContext {
+    filePath?: string;
+}
+declare function validateStructural(task: Task, context?: StructuralValidationContext): ValidationError[];
+
+declare const VALID_TRANSITIONS: Map<TaskStatus, Set<TaskStatus>>;
+interface TransitionValidationContext {
+    actor?: string;
+    dependencyStatuses?: Map<string, TaskStatus> | Record<string, TaskStatus>;
+}
+declare function validate_transition(fromStatus: TaskStatus, toStatus: TaskStatus): boolean;
+declare function validateTransition(task: Task, toStatus: TaskStatus, context?: TransitionValidationContext): ValidationError[];
+
+interface ValidationContext extends StructuralValidationContext, ReferentialValidationContext, SemanticValidationContext {
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    issues: ValidationError[];
+}
+declare function validate(task: Task, context?: ValidationContext): ValidationResult;
+
+declare function findRepoRoot(cwd?: string): string | null;
+interface CompletionResult {
+    item: BacklogItem;
+    previousStatus: ItemStatus;
+    releaseFile?: string;
+    alreadyComplete: boolean;
+}
+declare function completeItem(rootDir: string, id: string): CompletionResult;
+declare function ensureCoopLayout(rootDir: string): void;
+declare function loadState(rootDir: string): RepoState;
+declare function queryItems(state: RepoState, filter: FilterSpec): BacklogItem[];
+declare function getItemById(state: RepoState, id: string): BacklogItem | null;
+declare function createItem(rootDir: string, params: CreateItemParams): BacklogItem;
+declare function updateItem(rootDir: string, id: string, patch: UpdateItemParams): BacklogItem;
+declare function deleteItem(rootDir: string, id: string): BacklogItem;
+declare function renderAgentPrompt(item: BacklogItem): string;
+declare function validateRepo(rootDir: string): {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+};
+
+export { type AIAgent, type AIResource, type AgentSpec, ArtifactType, type AutoTransitionResult, type AvailabilityWindow, type BacklogItem, type BacklogItemData, CURRENT_SCHEMA_VERSION, type ComputeNode, type ComputeResource, type CoopConfig, type CreateItemParams, type Delivery, type DeliveryBudget, type DeliveryGovernance, type DeliveryRisk, type DeliveryScope, DeliveryStatus, type EffectiveCapacity, type ExecutionConstraints, type ExecutionPermissions, ExecutorType, type FilterSpec, type FrontmatterParseResult, type GraphValidationResult, type HumanMember, type HumanResource, ITEM_STATUSES, ITEM_TYPES, type Idea, IdeaStatus, type ItemLinks, type ItemStatus, type ItemType, type ParsedDelivery, type ParsedIdea, type ParsedTask, type ReadinessComputation, type ReadinessPartitions, type ReadinessState, type ReadinessTransitionEvent, type ReadinessWarning, type ReferentialValidationContext, type RepoConfig, type RepoState, type ResourceProfile, RiskLevel, RunbookAction, type RunbookStep, type SemanticValidationContext, type StructuralValidationContext, type Task, TaskComplexity, type TaskComputed, type TaskCore, TaskDeterminism, type TaskEstimate, type TaskEstimation, type TaskExecution, type TaskGovernance, type TaskGraph, type TaskPlanning, TaskPriority, type TaskResources, TaskStatus, type TaskTransitionedEvent, TaskType, type Track, type TrackWip, type TransitionContext, type TransitionResult, type TransitionValidationContext, type UpdateItemParams, VALID_TASK_TRANSITIONS, VALID_TRANSITIONS, type ValidationContext, type ValidationError, type ValidationLevel, type ValidationResult, type WriteTaskOptions, build_graph, check_blocked, check_unblocked, completeItem, compute_all_readiness, compute_readiness, compute_readiness_with_corrections, createItem, deleteItem, detect_cycle, ensureCoopLayout, extract_subgraph, findRepoRoot, find_external_dependencies, getItemById, loadState, load_graph, parseDeliveryContent, parseDeliveryFile, parseFrontmatterContent, parseFrontmatterFile, parseIdeaContent, parseIdeaFile, parseTaskContent, parseTaskFile, parseYamlContent, parseYamlFile, partition_by_readiness, queryItems, read_schema_version, renderAgentPrompt, stringifyFrontmatter, topological_sort, transition, transitive_dependencies, transitive_dependents, updateItem, validate, validateReferential, validateRepo, validateSemantic, validateStructural, validateTransition, validate_graph, validate_transition, writeTask, write_schema_version };