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

package/dist/nexusAutomationTargetReport.js

@@ -0,0 +1,504 @@
+import path from "node:path";
+import { readNexusAutomationRunLedger, } from "./nexusAutomation.js";
+import { loadProjectConfig, } from "./nexusProjectConfig.js";
+import { resolveProjectComponents, } from "./nexusProjectLifecycle.js";
+import { readNexusAutomationTargetContext, } from "./nexusAutomationTarget.js";
+import { readNexusAutomationTargetCycleLedger, summarizeNexusAutomationTargetCycles, } from "./nexusAutomationTargetCycle.js";
+import { loadLocalWorkTrackingStore, resolveLocalWorkTrackingStorePath, } from "./workTrackingLocalProvider.js";
+export class NexusAutomationTargetReportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationTargetReportError";
+    }
+}
+export function buildNexusAutomationTargetReport(options) {
+    const projectRoot = path.resolve(requiredNonEmptyString(options.projectRoot, "projectRoot"));
+    const projectConfig = loadProjectConfig(projectRoot);
+    const automationConfig = projectConfig.automation ?? null;
+    const generatedAt = isoString(options.now ?? new Date());
+    const components = resolveProjectComponents(projectRoot, projectConfig);
+    if (!automationConfig) {
+        return {
+            version: 1,
+            generatedAt,
+            projectRoot,
+            project: projectSummary(projectConfig, components),
+            target: null,
+            status: "not_started",
+            statusReason: "Project automation is not configured",
+            cycleSummary: null,
+            runSummary: null,
+            workItemSummary: null,
+            executionSummary: null,
+            componentProgress: [],
+            relaunchDecision: {
+                type: "not_ready",
+                reason: "Project automation is not configured",
+                eligibleWorkItemCount: null,
+                latestCycleId: null,
+                latestRunId: null,
+            },
+            activeBlockers: [],
+            blockers: [],
+            notes: [],
+        };
+    }
+    const target = readNexusAutomationTargetContext({
+        projectRoot,
+        config: automationConfig,
+    });
+    const cycleLedger = readNexusAutomationTargetCycleLedger(projectRoot, automationConfig);
+    const cycleSummary = summarizeNexusAutomationTargetCycles({
+        projectRoot,
+        config: automationConfig,
+    });
+    const runLedger = readNexusAutomationRunLedger(projectRoot, automationConfig);
+    const runSummary = summarizeRuns(runLedger);
+    const status = reportStatus(cycleLedger, runLedger);
+    const workItemResolver = localWorkItemResolver(projectRoot, components);
+    const workItemSummary = summarizeCycleWorkItems(cycleLedger, workItemResolver);
+    const executionSummary = summarizeExecution(runLedger, workItemResolver);
+    const activeBlockers = summarizeActiveBlockers({
+        lastCycle: cycleSummary.lastCycle,
+        lastRun: runSummary.lastRun,
+        workItemResolver,
+    });
+    return {
+        version: 1,
+        generatedAt,
+        projectRoot,
+        project: projectSummary(projectConfig, components),
+        target,
+        status,
+        statusReason: reportStatusReason(status, cycleSummary.lastCycle, runSummary.lastRun),
+        cycleSummary,
+        runSummary,
+        workItemSummary,
+        executionSummary,
+        componentProgress: summarizeComponentProgress({
+            components,
+            workItemSummary,
+            executionSummary,
+            activeBlockers,
+        }),
+        relaunchDecision: relaunchDecision({
+            automationConfig,
+            lastCycle: cycleSummary.lastCycle,
+            lastRun: runSummary.lastRun,
+        }),
+        activeBlockers,
+        blockers: uniqueStrings(cycleLedger.cycles.flatMap((cycle) => cycle.blockers)),
+        notes: uniqueStrings(cycleLedger.cycles.flatMap((cycle) => cycle.notes)),
+    };
+}
+function relaunchDecision(options) {
+    const { automationConfig, lastCycle, lastRun } = options;
+    if (!lastCycle) {
+        if (lastRun?.status === "blocked") {
+            return decision("report_blocked", `Latest automation run ${lastRun.id} is blocked and no target cycle is recorded`, null, null, lastRun.id);
+        }
+        if (lastRun?.status === "failed") {
+            return decision("report_failed", `Latest automation run ${lastRun.id} failed and no target cycle is recorded`, null, null, lastRun.id);
+        }
+        return decision("not_ready", "No target cycle is recorded", null, null, lastRun?.id ?? null);
+    }
+    const latestRunId = lastCycle.runId ?? lastRun?.id ?? null;
+    if (lastCycle.status === "started" || lastCycle.status === "dispatched") {
+        return decision("wait", `Latest target cycle ${lastCycle.id} is still ${lastCycle.status}`, lastCycle.eligibleWorkItemCount, lastCycle.id, latestRunId);
+    }
+    if (lastCycle.status === "blocked") {
+        return decision("report_blocked", `Latest target cycle ${lastCycle.id} is blocked`, lastCycle.eligibleWorkItemCount, lastCycle.id, latestRunId);
+    }
+    if (lastCycle.status === "failed") {
+        return decision("report_failed", `Latest target cycle ${lastCycle.id} failed`, lastCycle.eligibleWorkItemCount, lastCycle.id, latestRunId);
+    }
+    const eligibleWorkItemCount = lastCycle.eligibleWorkItemCount;
+    if (eligibleWorkItemCount === null) {
+        return decision("not_ready", `Latest target cycle ${lastCycle.id} did not record eligible work item count`, null, lastCycle.id, latestRunId);
+    }
+    if (eligibleWorkItemCount > 0) {
+        if (automationConfig.agent.relaunch.whileEligible) {
+            return decision("relaunch", `Latest target cycle ${lastCycle.id} recorded ${eligibleWorkItemCount} eligible work item(s) and relaunch while eligible is enabled`, eligibleWorkItemCount, lastCycle.id, latestRunId);
+        }
+        return decision("wait", `Latest target cycle ${lastCycle.id} recorded ${eligibleWorkItemCount} eligible work item(s), but relaunch while eligible is disabled`, eligibleWorkItemCount, lastCycle.id, latestRunId);
+    }
+    if (automationConfig.target.stopWhenNoEligibleWork) {
+        return decision("stop", `Latest target cycle ${lastCycle.id} recorded no eligible work item(s)`, eligibleWorkItemCount, lastCycle.id, latestRunId);
+    }
+    return decision("wait", `Latest target cycle ${lastCycle.id} recorded no eligible work item(s), but stopWhenNoEligibleWork is disabled`, eligibleWorkItemCount, lastCycle.id, latestRunId);
+}
+function decision(type, reason, eligibleWorkItemCount, latestCycleId, latestRunId) {
+    return {
+        type,
+        reason,
+        eligibleWorkItemCount,
+        latestCycleId,
+        latestRunId,
+    };
+}
+function projectSummary(projectConfig, components) {
+    return {
+        id: projectConfig.id,
+        name: projectConfig.name,
+        componentCount: components.length,
+    };
+}
+function summarizeRuns(ledger) {
+    return {
+        runCount: ledger.runs.length,
+        completedRunCount: ledger.runs.filter((run) => run.status === "completed")
+            .length,
+        blockedRunCount: ledger.runs.filter((run) => run.status === "blocked")
+            .length,
+        failedRunCount: ledger.runs.filter((run) => run.status === "failed").length,
+        skippedRunCount: ledger.runs.filter((run) => run.status === "skipped")
+            .length,
+        lastRun: ledger.runs.at(-1) ?? null,
+    };
+}
+function summarizeCycleWorkItems(ledger, workItemResolver) {
+    const all = ledger.cycles.flatMap((cycle) => cycle.workItems.map((item) => ({ cycle, item })));
+    const unique = new Map();
+    const componentCounts = new Map();
+    const byCycleStatus = {
+        eligible: 0,
+        selected: 0,
+        dispatched: 0,
+        in_progress: 0,
+        completed: 0,
+        blocked: 0,
+        skipped: 0,
+    };
+    for (const { cycle, item } of all) {
+        const key = workItemKey(item);
+        const resolved = workItemResolver(item.componentId, item.id);
+        unique.set(key, {
+            componentId: item.componentId,
+            id: item.id,
+            title: item.title ?? resolved?.title ?? null,
+            status: item.status ?? resolved?.status ?? null,
+            latestCycleStatus: item.cycleStatus,
+            latestCycleId: cycle.id,
+            agentProfileId: item.agentProfileId,
+            notes: item.notes,
+        });
+        const componentKey = item.componentId ?? "";
+        const component = componentCounts.get(componentKey) ?? {
+            componentId: item.componentId,
+            totalReferences: 0,
+            uniqueIds: new Set(),
+        };
+        component.totalReferences += 1;
+        component.uniqueIds.add(item.id);
+        componentCounts.set(componentKey, component);
+        if (item.cycleStatus) {
+            byCycleStatus[item.cycleStatus] += 1;
+        }
+    }
+    const uniqueReferences = [...unique.values()];
+    return {
+        totalReferences: all.length,
+        uniqueReferences,
+        byComponent: [...componentCounts.values()].map((component) => ({
+            componentId: component.componentId,
+            totalReferences: component.totalReferences,
+            uniqueWorkItemCount: component.uniqueIds.size,
+        })),
+        byCycleStatus,
+        progress: summarizeWorkItemProgress(uniqueReferences),
+    };
+}
+function summarizeExecution(ledger, workItemResolver) {
+    const runs = ledger.runs.map((run) => {
+        const resolved = run.workItemId
+            ? workItemResolver(run.componentId, run.workItemId)
+            : null;
+        return {
+            runId: run.id,
+            componentId: run.componentId,
+            status: run.status,
+            workItemId: run.workItemId,
+            workItemTitle: run.workItemTitle ?? resolved?.title ?? null,
+            workItemStatus: resolved?.status ?? null,
+            commitIds: run.commitIds,
+            summary: run.summary,
+            error: run.error,
+        };
+    });
+    const runById = new Map(runs.map((run) => [run.runId, run]));
+    const verification = ledger.runs.flatMap((run) => {
+        const summary = runById.get(run.id);
+        return run.verification.map((record) => ({
+            runId: run.id,
+            componentId: run.componentId,
+            workItemId: run.workItemId,
+            workItemTitle: summary?.workItemTitle ?? null,
+            ...record,
+        }));
+    });
+    const publicationDecisions = ledger.runs.flatMap((run) => {
+        if (!run.publicationDecision) {
+            return [];
+        }
+        const summary = runById.get(run.id);
+        return [
+            {
+                runId: run.id,
+                componentId: run.componentId,
+                workItemId: run.workItemId,
+                workItemTitle: summary?.workItemTitle ?? null,
+                ...run.publicationDecision,
+            },
+        ];
+    });
+    return {
+        runCount: ledger.runs.length,
+        commitIds: uniqueStrings(ledger.runs.flatMap((run) => run.commitIds)),
+        verification,
+        publicationDecisions,
+        runs,
+    };
+}
+function summarizeActiveBlockers(options) {
+    const { lastCycle, lastRun, workItemResolver } = options;
+    const active = [];
+    if (lastCycle &&
+        (lastCycle.status === "completed" || lastCycle.status === "skipped")) {
+        return active;
+    }
+    if (lastCycle) {
+        for (const blocker of lastCycle.blockers) {
+            active.push({
+                source: "cycle",
+                componentId: null,
+                cycleId: lastCycle.id,
+                runId: lastCycle.runId,
+                workItemId: null,
+                workItemTitle: null,
+                message: blocker,
+            });
+        }
+        for (const item of lastCycle.workItems) {
+            const resolved = workItemResolver(item.componentId, item.id);
+            const status = item.status ?? resolved?.status ?? null;
+            if (item.cycleStatus !== "blocked" && status !== "blocked") {
+                continue;
+            }
+            active.push({
+                source: "work_item",
+                componentId: item.componentId,
+                cycleId: lastCycle.id,
+                runId: lastCycle.runId,
+                workItemId: item.id,
+                workItemTitle: item.title ?? resolved?.title ?? null,
+                message: item.notes,
+            });
+        }
+    }
+    if (lastRun &&
+        (lastRun.status === "blocked" || lastRun.status === "failed") &&
+        (!lastCycle || lastCycle.runId === lastRun.id)) {
+        const resolved = lastRun.workItemId
+            ? workItemResolver(lastRun.componentId, lastRun.workItemId)
+            : null;
+        active.push({
+            source: "run",
+            componentId: lastRun.componentId,
+            cycleId: lastCycle?.id ?? null,
+            runId: lastRun.id,
+            workItemId: lastRun.workItemId,
+            workItemTitle: lastRun.workItemTitle ?? resolved?.title ?? null,
+            message: lastRun.error,
+        });
+    }
+    return active;
+}
+function summarizeComponentProgress(options) {
+    const drafts = new Map();
+    const ensureDraft = (componentId, component = null) => {
+        const key = componentId ?? "";
+        const existing = drafts.get(key);
+        if (existing) {
+            if (!existing.component && component) {
+                existing.component = component;
+            }
+            return existing;
+        }
+        const draft = {
+            component,
+            componentId,
+            workItems: [],
+            activeBlockers: [],
+            runs: [],
+        };
+        drafts.set(key, draft);
+        return draft;
+    };
+    for (const component of options.components) {
+        ensureDraft(component.id, component);
+    }
+    for (const item of options.workItemSummary.uniqueReferences) {
+        ensureDraft(item.componentId).workItems.push(item);
+    }
+    for (const blocker of options.activeBlockers) {
+        if (blocker.componentId !== null) {
+            ensureDraft(blocker.componentId).activeBlockers.push(blocker);
+        }
+    }
+    for (const run of options.executionSummary.runs) {
+        ensureDraft(run.componentId).runs.push(run);
+    }
+    return [...drafts.values()].map((draft) => {
+        const componentId = draft.component?.id ?? draft.componentId;
+        const verification = options.executionSummary.verification.filter((record) => record.componentId === componentId);
+        const publicationDecisions = options.executionSummary.publicationDecisions.filter((decisionRecord) => decisionRecord.componentId === componentId);
+        return {
+            componentId,
+            componentName: draft.component?.name ?? componentId,
+            role: draft.component?.role ?? null,
+            sourceRoot: draft.component?.sourceRoot ?? null,
+            workTrackingProvider: draft.component?.workTracking?.provider ?? null,
+            workItemCount: draft.workItems.length,
+            workItems: summarizeWorkItemProgress(draft.workItems),
+            activeBlockers: draft.activeBlockers,
+            commitIds: uniqueStrings(draft.runs.flatMap((run) => run.commitIds)),
+            verification,
+            publicationDecisions,
+            runs: draft.runs,
+        };
+    });
+}
+function summarizeWorkItemProgress(references) {
+    const progress = emptyWorkItemProgress();
+    for (const reference of references) {
+        const bucket = workItemProgressBucket(reference);
+        if (bucket) {
+            progress[bucket].push(reference);
+        }
+    }
+    return progress;
+}
+function emptyWorkItemProgress() {
+    return {
+        readyEligibleWork: [],
+        selectedWork: [],
+        blockedHitlWork: [],
+        completedWork: [],
+        skippedWork: [],
+    };
+}
+function workItemProgressBucket(reference) {
+    switch (reference.latestCycleStatus) {
+        case "eligible":
+            return "readyEligibleWork";
+        case "selected":
+        case "dispatched":
+        case "in_progress":
+            return "selectedWork";
+        case "blocked":
+            return "blockedHitlWork";
+        case "completed":
+            return "completedWork";
+        case "skipped":
+            return "skippedWork";
+        default:
+            break;
+    }
+    switch (reference.status) {
+        case "ready":
+            return "readyEligibleWork";
+        case "in_progress":
+            return "selectedWork";
+        case "blocked":
+            return "blockedHitlWork";
+        case "done":
+            return "completedWork";
+        case "wont_do":
+            return "skippedWork";
+        default:
+            return null;
+    }
+}
+function localWorkItemResolver(projectRoot, components) {
+    const primaryComponentId = components.find((component) => component.role === "primary")?.id ??
+        components[0]?.id ??
+        null;
+    const itemsByComponent = new Map();
+    for (const component of components) {
+        const workTracking = component.workTracking;
+        if (workTracking?.provider !== "local") {
+            continue;
+        }
+        try {
+            const store = loadLocalWorkTrackingStore(resolveLocalWorkTrackingStorePath(projectRoot, workTracking));
+            itemsByComponent.set(component.id, new Map(store.items.map((item) => [
+                item.id,
+                {
+                    title: item.title,
+                    status: item.status,
+                },
+            ])));
+        }
+        catch {
+            continue;
+        }
+    }
+    return (componentId, id) => {
+        const resolvedComponentId = componentId ?? primaryComponentId;
+        if (!resolvedComponentId) {
+            return null;
+        }
+        return itemsByComponent.get(resolvedComponentId)?.get(id) ?? null;
+    };
+}
+function reportStatus(cycleLedger, runLedger) {
+    const lastCycle = cycleLedger.cycles.at(-1);
+    if (lastCycle) {
+        return cycleStatusToReportStatus(lastCycle.status);
+    }
+    const lastRun = runLedger.runs.at(-1);
+    if (!lastRun) {
+        return "not_started";
+    }
+    return "not_started";
+}
+function cycleStatusToReportStatus(status) {
+    if (status === "started" || status === "dispatched") {
+        return "active";
+    }
+    return status;
+}
+function reportStatusReason(status, lastCycle, lastRun) {
+    if (lastCycle) {
+        return `Latest target cycle ${lastCycle.id} is ${lastCycle.status}`;
+    }
+    if (lastRun) {
+        return `No target cycle is recorded; latest automation run ${lastRun.id} is ${lastRun.status}`;
+    }
+    if (status === "not_started") {
+        return "No target cycles or automation runs are recorded";
+    }
+    return `Target report status is ${status}`;
+}
+function workItemKey(item) {
+    return `${item.componentId ?? ""}:${item.id}`;
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function isoString(value) {
+    return dateFrom(value, "date").toISOString();
+}
+function dateFrom(value, name) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new NexusAutomationTargetReportError(`${name} must be a valid date`);
+    }
+    return date;
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationTargetReportError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/nexusAutomationWorktreeSetup.d.ts

@@ -0,0 +1,89 @@
+import { type GitRunner } from "./gitWorktreeService.js";
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+import { type MaterializeNexusWorkerContextBundleResult, type NexusWorkerContextDependencyProjection, type NexusWorkerContextDependencyProjectionSourceControl, type NexusWorkerContextDependencyProjectionSourceMetadata, type NexusWorkerContextDependencyProjectionStatus, type NexusWorkerContextBundleWorktree } from "./nexusWorkerContextBundle.js";
+import { type NexusProjectSkillsConfig, type NexusSkillMaterializationMode, type NexusSkillSourceControl } from "./nexusSkills.js";
+import type { NexusPluginWorkerFragmentsProjection } from "./nexusPluginCapabilities.js";
+export type NexusAutomationWorktreeSetupLinkStatus = "linked" | "present" | "skipped";
+export interface NexusAutomationWorktreeSetupPreflightCheck {
+    name: string;
+    status: "passed" | "failed";
+    message: string;
+}
+export interface NexusAutomationWorktreeSetupLinkResult {
+    source: string;
+    target: string;
+    sourcePath: string;
+    targetPath: string;
+    required: boolean;
+    status: NexusAutomationWorktreeSetupLinkStatus;
+    message: string;
+}
+export interface NexusAutomationPluginDependencyProjection {
+    id: string;
+    source: string;
+    target: string;
+    required: boolean;
+    sourceControl: NexusWorkerContextDependencyProjectionSourceControl;
+    reason: string | null;
+    sourceMetadata: NexusWorkerContextDependencyProjectionSourceMetadata;
+}
+export interface NexusAutomationWorktreeDependencyProjectionResult extends NexusWorkerContextDependencyProjection {
+    status: NexusWorkerContextDependencyProjectionStatus;
+}
+export type NexusAutomationWorktreeSkillProjectionStatus = "missing" | "stale" | "present";
+export interface NexusAutomationWorktreeSkillProjectionSkillResult {
+    id: string;
+    name: string;
+    version: string;
+    materialization: NexusSkillMaterializationMode;
+    sourceSkillRoot: string;
+    projectedSkillRoot: string;
+    skillPath: string | null;
+    beforeStatus: NexusAutomationWorktreeSkillProjectionStatus;
+    afterStatus: NexusAutomationWorktreeSkillProjectionStatus;
+    refreshed: boolean;
+    reasons: string[];
+}
+export interface NexusAutomationWorktreeSkillProjectionResult {
+    agent: string;
+    projectManagedSkillsRoot: string;
+    skillsDirectory: string;
+    sourceControl: NexusSkillSourceControl;
+    skills: NexusAutomationWorktreeSkillProjectionSkillResult[];
+}
+export interface NexusAutomationWorktreeSetupResult {
+    links: NexusAutomationWorktreeSetupLinkResult[];
+    dependencyProjections: NexusAutomationWorktreeDependencyProjectionResult[];
+    skillProjections: NexusAutomationWorktreeSkillProjectionResult[];
+    context?: MaterializeNexusWorkerContextBundleResult;
+}
+export interface NexusAutomationWorktreeSetupContextInput {
+    project: {
+        id?: string | null;
+        name?: string | null;
+        root: string;
+    };
+    ownership: NexusWorkerContextBundleWorktree;
+    targetStatePath?: string | null;
+    pluginFragments?: NexusPluginWorkerFragmentsProjection;
+}
+export interface NexusAutomationWorktreeSetupOptions {
+    sourceRoot: string;
+    worktreesRoot?: string;
+    worktreePath: string;
+    automationConfig: NexusAutomationConfig;
+    pluginDependencyProjections?: NexusAutomationPluginDependencyProjection[];
+    skillsConfig?: NexusProjectSkillsConfig;
+    context?: NexusAutomationWorktreeSetupContextInput;
+    gitRunner?: GitRunner;
+    platform?: NodeJS.Platform;
+}
+export declare class NexusAutomationWorktreeSetupError extends Error {
+    constructor(message: string);
+}
+export declare function preflightNexusAutomationWorktreeSetup(options: {
+    sourceRoot: string;
+    automationConfig: NexusAutomationConfig;
+    pluginDependencyProjections?: NexusAutomationPluginDependencyProjection[];
+}): NexusAutomationWorktreeSetupPreflightCheck[];
+export declare function materializeNexusAutomationWorktreeSetup(options: NexusAutomationWorktreeSetupOptions): NexusAutomationWorktreeSetupResult;