@evref-bl/dev-nexus 0.1.0-alpha.0

package/dist/nexusCoordination.d.ts

@@ -0,0 +1,198 @@
+import { type GitRunner } from "./gitWorktreeService.js";
+import type { WorkComment, WorkItem } from "./workTrackingTypes.js";
+export declare const coordinationHandoffCommentMarker = "DevNexus coordination handoff";
+export declare const coordinationHandoffKind = "dev-nexus.coordination.handoff";
+export declare const defaultCoordinationHandoffStaleAfterMs: number;
+export type NexusCoordinationHandoffStatus = "working" | "ready" | "blocked" | "merged";
+export interface NexusCoordinationGitStatus {
+    repositoryPath: string | null;
+    branch: string | null;
+    upstream: string | null;
+    baseRef: string | null;
+    headCommit: string | null;
+    dirty: boolean | null;
+    stagedCount: number;
+    unstagedCount: number;
+    untrackedCount: number;
+    ahead: number | null;
+    behind: number | null;
+    pushed: boolean | null;
+    warnings: string[];
+}
+export interface NexusCoordinationHandoffRecord {
+    kind: typeof coordinationHandoffKind;
+    version: 1;
+    createdAt: string;
+    projectId: string;
+    projectRoot: string;
+    componentId: string;
+    componentName: string;
+    workItemId: string;
+    hostId: string;
+    agentId: string | null;
+    status: NexusCoordinationHandoffStatus;
+    repositoryPath: string | null;
+    branch: string | null;
+    upstream: string | null;
+    baseRef: string | null;
+    headCommit: string | null;
+    dirty: boolean | null;
+    ahead: number | null;
+    behind: number | null;
+    pushed: boolean | null;
+    changedAreas: string[];
+    decisions: string[];
+    verificationSummary: string | null;
+    integrationPreference: string | null;
+    note: string | null;
+}
+export interface NexusCoordinationHandoffSummary extends NexusCoordinationHandoffRecord {
+    commentId: string | null;
+    commentCreatedAt: string | null;
+    stale: boolean;
+    ageMs: number | null;
+}
+export interface NexusCoordinationHandoffCollection {
+    available: boolean;
+    provider: string | null;
+    records: NexusCoordinationHandoffSummary[];
+    warnings: string[];
+}
+export type NexusCoordinationIntegrationScope = "work_item" | "component" | "target_branch";
+export type NexusCoordinationMergeStatus = "clean" | "conflict" | "skipped" | "unknown";
+export interface NexusCoordinationIntegrationFetchPlan {
+    requested: boolean;
+    allowed: boolean;
+    remote: string | null;
+    targetBranch: string | null;
+    ran: boolean;
+    exitCode: number | null;
+    warning: string | null;
+}
+export interface NexusCoordinationIntegrationBranchMerge {
+    status: NexusCoordinationMergeStatus;
+    mergeBase: string | null;
+    targetCommit: string | null;
+    branchCommit: string | null;
+    changedFiles: string[];
+    conflictFiles: string[];
+    messages: string[];
+    summary: string;
+    rangeDiff: string[];
+}
+export interface NexusCoordinationIntegrationBranchPlan {
+    workItemId: string;
+    branch: string;
+    status: NexusCoordinationHandoffStatus;
+    stale: boolean;
+    headCommit: string | null;
+    handoff: {
+        hostId: string;
+        agentId: string | null;
+        status: NexusCoordinationHandoffStatus;
+        createdAt: string;
+        stale: boolean;
+        changedAreas: string[];
+        decisions: string[];
+        verificationSummary: string | null;
+        integrationPreference: string | null;
+        note: string | null;
+    };
+    merge: NexusCoordinationIntegrationBranchMerge;
+}
+export interface NexusCoordinationDecisionConflict {
+    kind: "changed_area" | "integration_preference";
+    branches: string[];
+    changedArea: string | null;
+    decisions: string[];
+    summary: string;
+}
+export interface NexusCoordinationSuggestedMergeStep {
+    branch: string;
+    workItemId: string;
+    direction: string;
+    reason: string;
+}
+export interface NexusCoordinationIntegrationPlan {
+    project: NexusCoordinationStatus["project"];
+    component: NexusCoordinationStatus["component"];
+    scope: NexusCoordinationIntegrationScope;
+    target: {
+        branch: string | null;
+        ref: string;
+        commit: string | null;
+    };
+    fetch: NexusCoordinationIntegrationFetchPlan;
+    handoffs: {
+        available: boolean;
+        provider: string | null;
+        totalCount: number;
+        activeCount: number;
+        staleCount: number;
+        records: NexusCoordinationHandoffSummary[];
+        warnings: string[];
+    };
+    branches: NexusCoordinationIntegrationBranchPlan[];
+    decisionConflicts: NexusCoordinationDecisionConflict[];
+    suggestedOrder: NexusCoordinationSuggestedMergeStep[];
+    nextAction: string;
+    warnings: string[];
+    mutatesSource: false;
+}
+export interface NexusCoordinationStatus {
+    project: {
+        id: string;
+        name: string;
+        projectRoot: string;
+    };
+    component: {
+        id: string;
+        name: string;
+        role: string;
+        sourceRoot: string;
+        worktreesRoot: string;
+        workTrackingProvider: string | null;
+    };
+    workItem: WorkItem | null;
+    git: NexusCoordinationGitStatus;
+    handoffs: NexusCoordinationHandoffCollection;
+    nextAction: string;
+    blocking: boolean;
+    warnings: string[];
+}
+export interface NexusCoordinationStatusOptions {
+    projectRoot: string;
+    componentId?: string;
+    workItemId?: string;
+    currentPath?: string;
+    gitRunner?: GitRunner;
+    now?: () => Date | string;
+    maxHandoffAgeMs?: number;
+}
+export interface NexusCoordinationHandoffOptions extends NexusCoordinationStatusOptions {
+    workItemId: string;
+    status: NexusCoordinationHandoffStatus;
+    hostId?: string;
+    agentId?: string;
+    changedAreas?: string[];
+    decisions?: string[];
+    verificationSummary?: string | null;
+    integrationPreference?: string | null;
+    note?: string | null;
+}
+export interface NexusCoordinationIntegrationOptions extends NexusCoordinationStatusOptions {
+    targetBranch?: string;
+    fetch?: boolean;
+}
+export interface NexusCoordinationHandoffResult {
+    project: NexusCoordinationStatus["project"];
+    component: NexusCoordinationStatus["component"];
+    record: NexusCoordinationHandoffRecord;
+    comment: WorkComment;
+    git: NexusCoordinationGitStatus;
+}
+export declare function getNexusCoordinationStatus(options: NexusCoordinationStatusOptions): Promise<NexusCoordinationStatus>;
+export declare function createNexusCoordinationHandoff(options: NexusCoordinationHandoffOptions): Promise<NexusCoordinationHandoffResult>;
+export declare function getNexusCoordinationIntegrationPlan(options: NexusCoordinationIntegrationOptions): Promise<NexusCoordinationIntegrationPlan>;
+export declare function parseNexusCoordinationHandoffStatus(value: string, pathName: string): NexusCoordinationHandoffStatus;
+export declare function formatCoordinationHandoffComment(record: NexusCoordinationHandoffRecord): string;