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

package/dist/nexusAutomationStatus.js

@@ -0,0 +1,462 @@
+import fs from "node:fs";
+import path from "node:path";
+import { buildNexusAutomationWorkItemQuery, eligibleNexusAutomationWorkItems, evaluateNexusAutomationLedgerBackoff, nexusAutomationLockPath, readNexusAutomationRunLedger, selectNexusAutomationWorkItem, } from "./nexusAutomation.js";
+import { preflightNexusAutomationAgentLaunch, } from "./nexusAutomationAgentLaunch.js";
+import { normalizeNexusAutomationAgentPolicy, } from "./nexusAutomationAgentProfile.js";
+import { loadProjectConfig, } from "./nexusProjectConfig.js";
+import { readNexusAutomationTargetContext, } from "./nexusAutomationTarget.js";
+import { summarizeNexusAutomationTargetCycles, } from "./nexusAutomationTargetCycle.js";
+import { resolvePrimaryProjectComponent, resolveProjectComponents, } from "./nexusProjectLifecycle.js";
+import { preflightNexusAutomationRunOnce, } from "./nexusAutomationRunOnce.js";
+import { createWorkTrackerProvider, } from "./workTrackingProviderService.js";
+export class NexusAutomationStatusError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationStatusError";
+    }
+}
+export async function getNexusAutomationStatus(options) {
+    const projectRoot = path.resolve(requiredNonEmptyString(options.projectRoot, "projectRoot"));
+    const projectConfig = loadProjectConfig(projectRoot);
+    const automationConfig = projectConfig.automation ?? null;
+    const components = resolveProjectComponents(projectRoot, projectConfig);
+    const primaryComponent = resolvePrimaryProjectComponent(projectRoot, projectConfig);
+    const sourceRoot = primaryComponent.sourceRoot;
+    if (!automationConfig?.enabled) {
+        return statusResult({
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            status: "disabled",
+            summary: "Automation is not enabled for this project",
+            lock: null,
+            ledger: null,
+            backoff: null,
+            preflight: [],
+            selectorQuery: null,
+            candidateCount: null,
+            eligibleWorkItems: null,
+            selectedWorkItem: null,
+        });
+    }
+    const now = currentIso(options.now);
+    const ledger = readNexusAutomationRunLedger(projectRoot, automationConfig);
+    const lock = readNexusAutomationStatusLock(projectRoot, automationConfig, now);
+    if (lock.status === "active") {
+        return statusResult({
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            status: "locked",
+            summary: lock.message,
+            lock,
+            ledger,
+            backoff: null,
+            preflight: [],
+            selectorQuery: null,
+            candidateCount: null,
+            eligibleWorkItems: null,
+            selectedWorkItem: null,
+        });
+    }
+    if (lock.status === "invalid") {
+        return statusResult({
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            status: "blocked",
+            summary: lock.message,
+            lock,
+            ledger,
+            backoff: null,
+            preflight: [],
+            selectorQuery: null,
+            candidateCount: null,
+            eligibleWorkItems: null,
+            selectedWorkItem: null,
+        });
+    }
+    const backoff = evaluateNexusAutomationLedgerBackoff(automationConfig, ledger, now);
+    if (!backoff.shouldRun) {
+        return statusResult({
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            status: "backoff",
+            summary: backoff.reason ?? "Automation retry backoff is active",
+            lock,
+            ledger,
+            backoff,
+            preflight: [],
+            selectorQuery: null,
+            candidateCount: null,
+            eligibleWorkItems: null,
+            selectedWorkItem: null,
+        });
+    }
+    if (automationConfig.mode === "agent_launch") {
+        const componentProviders = createStatusComponentProviders({
+            options,
+            projectRoot,
+            projectConfig,
+            components,
+        });
+        if (componentProviders.length === 0) {
+            const summary = "No project component has work tracking configured";
+            return statusResult({
+                projectRoot,
+                sourceRoot,
+                components,
+                projectConfig,
+                automationConfig,
+                status: "blocked",
+                summary,
+                lock,
+                ledger,
+                backoff,
+                preflight: [
+                    {
+                        name: "workTracking",
+                        status: "failed",
+                        message: summary,
+                    },
+                ],
+                selectorQuery: null,
+                candidateCount: null,
+                eligibleWorkItems: null,
+                selectedWorkItem: null,
+            });
+        }
+        const preflight = preflightNexusAutomationAgentLaunch({
+            components,
+            componentProviders,
+            automationConfig,
+        });
+        const failedChecks = preflight.filter((check) => check.status === "failed");
+        if (failedChecks.length > 0) {
+            return statusResult({
+                projectRoot,
+                sourceRoot,
+                components,
+                projectConfig,
+                automationConfig,
+                status: "blocked",
+                summary: failedChecks.map((check) => check.message).join("; "),
+                lock,
+                ledger,
+                backoff,
+                preflight,
+                selectorQuery: null,
+                candidateCount: null,
+                eligibleWorkItems: null,
+                selectedWorkItem: null,
+            });
+        }
+        const selectorQuery = buildNexusAutomationWorkItemQuery(automationConfig);
+        const componentEligibleWorkItems = await listStatusEligibleWorkItemsByComponent(componentProviders, selectorQuery, automationConfig, projectRoot);
+        const eligibleWorkItems = componentEligibleWorkItems.flatMap((component) => component.workItems);
+        const status = eligibleWorkItems.length > 0 ? "ready" : "idle";
+        const summary = eligibleWorkItems.length > 0
+            ? `Agent launch ready with ${eligibleWorkItems.length} eligible work item(s)`
+            : "No eligible work item matched the automation selector";
+        return statusResult({
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            status,
+            summary,
+            lock,
+            ledger,
+            backoff,
+            preflight,
+            selectorQuery,
+            candidateCount: eligibleWorkItems.length,
+            eligibleWorkItems,
+            componentEligibleWorkItems,
+            selectedWorkItem: null,
+        });
+    }
+    if (!primaryComponent.workTracking) {
+        const summary = "Primary component work tracking is not configured";
+        return statusResult({
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            status: "blocked",
+            summary,
+            lock,
+            ledger,
+            backoff,
+            preflight: [
+                {
+                    name: "workTracking",
+                    status: "failed",
+                    message: summary,
+                },
+            ],
+            selectorQuery: null,
+            candidateCount: null,
+            eligibleWorkItems: null,
+            selectedWorkItem: null,
+        });
+    }
+    const provider = createStatusProvider({
+        options,
+        projectRoot,
+        sourceRoot,
+        projectConfig,
+        component: primaryComponent,
+    });
+    const preflight = preflightNexusAutomationRunOnce({
+        projectRoot,
+        sourceRoot,
+        projectConfig,
+        component: primaryComponent,
+        automationConfig,
+        provider,
+    });
+    const failedChecks = preflight.filter((check) => check.status === "failed");
+    if (failedChecks.length > 0) {
+        return statusResult({
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            status: "blocked",
+            summary: failedChecks.map((check) => check.message).join("; "),
+            lock,
+            ledger,
+            backoff,
+            preflight,
+            selectorQuery: null,
+            candidateCount: null,
+            eligibleWorkItems: null,
+            selectedWorkItem: null,
+        });
+    }
+    const selectorQuery = buildNexusAutomationWorkItemQuery(automationConfig);
+    const candidates = await provider.listWorkItems({
+        ...selectorQuery,
+        projectRoot,
+    });
+    const selectedWorkItem = selectNexusAutomationWorkItem(candidates, automationConfig) ?? null;
+    const status = selectedWorkItem ? "ready" : "idle";
+    const summary = selectedWorkItem
+        ? `Selected work item ${selectedWorkItem.id}: ${selectedWorkItem.title}`
+        : "No eligible work item matched the automation selector";
+    return statusResult({
+        projectRoot,
+        sourceRoot,
+        components,
+        projectConfig,
+        automationConfig,
+        status,
+        summary,
+        lock,
+        ledger,
+        backoff,
+        preflight,
+        selectorQuery,
+        candidateCount: candidates.length,
+        eligibleWorkItems: null,
+        selectedWorkItem,
+    });
+}
+export function readNexusAutomationStatusLock(projectRoot, config, now = new Date()) {
+    const lockPath = nexusAutomationLockPath(projectRoot, config);
+    if (!fs.existsSync(lockPath)) {
+        return {
+            path: lockPath,
+            status: "none",
+            runId: null,
+            owner: null,
+            acquiredAt: null,
+            expiresAt: null,
+            message: "No automation run lock is present",
+        };
+    }
+    try {
+        const record = JSON.parse(fs.readFileSync(lockPath, "utf8").replace(/^\uFEFF/, ""));
+        const runId = requiredLockString(record.runId, "automation lock.runId");
+        const acquiredAt = requiredLockIsoString(record.acquiredAt, "automation lock.acquiredAt");
+        const expiresAt = requiredLockIsoString(record.expiresAt, "automation lock.expiresAt");
+        const owner = optionalLockString(record.owner);
+        const expiresAtDate = dateFrom(expiresAt, "automation lock.expiresAt");
+        const status = expiresAtDate.getTime() > dateFrom(now, "now").getTime()
+            ? "active"
+            : "stale";
+        const message = status === "active"
+            ? `Automation run lock is held by ${runId} until ${expiresAt}`
+            : `Automation run lock is stale and can be replaced: ${runId}`;
+        return {
+            path: lockPath,
+            status,
+            runId,
+            owner,
+            acquiredAt,
+            expiresAt,
+            message,
+        };
+    }
+    catch (error) {
+        return {
+            path: lockPath,
+            status: "invalid",
+            runId: null,
+            owner: null,
+            acquiredAt: null,
+            expiresAt: null,
+            message: `Automation run lock is invalid: ${errorMessage(error)}`,
+        };
+    }
+}
+function createStatusProvider(options) {
+    const workTracking = options.component.workTracking;
+    if (!workTracking) {
+        throw new NexusAutomationStatusError("Primary component work tracking is not configured");
+    }
+    if (options.options.provider) {
+        return options.options.provider;
+    }
+    if (options.options.providerFactory) {
+        return options.options.providerFactory({
+            projectRoot: options.projectRoot,
+            sourceRoot: options.sourceRoot,
+            projectConfig: options.projectConfig,
+            component: options.component,
+            workTracking,
+        });
+    }
+    return createWorkTrackerProvider(workTracking, {
+        ...options.options.providerOptions,
+        projectRoot: options.projectRoot,
+        now: options.options.now,
+    });
+}
+function createStatusComponentProviders(options) {
+    return options.components
+        .filter((component) => component.workTracking)
+        .map((component) => ({
+        component,
+        provider: createStatusComponentProvider({
+            options: options.options,
+            projectRoot: options.projectRoot,
+            projectConfig: options.projectConfig,
+            component,
+        }),
+    }));
+}
+function createStatusComponentProvider(options) {
+    const workTracking = options.component.workTracking;
+    if (!workTracking) {
+        throw new NexusAutomationStatusError(`Component ${options.component.id} work tracking is not configured`);
+    }
+    if (options.options.provider) {
+        return options.options.provider;
+    }
+    if (options.options.providerFactory) {
+        return options.options.providerFactory({
+            projectRoot: options.projectRoot,
+            sourceRoot: options.component.sourceRoot,
+            projectConfig: options.projectConfig,
+            component: options.component,
+            workTracking,
+        });
+    }
+    return createWorkTrackerProvider(workTracking, {
+        ...options.options.providerOptions,
+        projectRoot: options.projectRoot,
+        now: options.options.now,
+    });
+}
+async function listStatusEligibleWorkItemsByComponent(componentProviders, selectorQuery, automationConfig, projectRoot) {
+    const grouped = [];
+    for (const { component, provider } of componentProviders) {
+        grouped.push({
+            componentId: component.id,
+            workItems: eligibleNexusAutomationWorkItems(await provider.listWorkItems({
+                ...selectorQuery,
+                projectRoot,
+            }), automationConfig),
+        });
+    }
+    return grouped;
+}
+function statusResult(result) {
+    const target = result.target ??
+        (result.automationConfig
+            ? readNexusAutomationTargetContext({
+                projectRoot: result.projectRoot,
+                config: result.automationConfig,
+            })
+            : null);
+    const agent = result.agent ??
+        (result.automationConfig
+            ? normalizeNexusAutomationAgentPolicy(result.automationConfig)
+            : null);
+    const targetCycles = result.targetCycles ??
+        (result.automationConfig
+            ? summarizeNexusAutomationTargetCycles({
+                projectRoot: result.projectRoot,
+                config: result.automationConfig,
+            })
+            : null);
+    return {
+        ...result,
+        target,
+        targetCycles,
+        agent,
+        components: result.components ?? [],
+        componentEligibleWorkItems: result.componentEligibleWorkItems ?? null,
+    };
+}
+function currentIso(now) {
+    const value = now ? now() : new Date();
+    return dateFrom(value, "now").toISOString();
+}
+function dateFrom(value, name) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new NexusAutomationStatusError(`${name} must be a valid date`);
+    }
+    return date;
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationStatusError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function requiredLockString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationStatusError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function requiredLockIsoString(value, name) {
+    const stringValue = requiredLockString(value, name);
+    dateFrom(stringValue, name);
+    return stringValue;
+}
+function optionalLockString(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return requiredLockString(value, "automation lock.owner");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/nexusAutomationTarget.d.ts

@@ -0,0 +1,19 @@
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+export interface NexusAutomationTargetContext {
+    id: string | null;
+    objective: string | null;
+    statePath: string;
+    cycleLedgerPath: string;
+    stateExists: boolean;
+    stateMarkdown: string | null;
+    stopWhenNoEligibleWork: boolean;
+    maxCycles: number | null;
+    maxWorkItems: number | null;
+}
+export declare class NexusAutomationTargetError extends Error {
+    constructor(message: string);
+}
+export declare function readNexusAutomationTargetContext(options: {
+    projectRoot: string;
+    config: NexusAutomationConfig;
+}): NexusAutomationTargetContext;

package/dist/nexusAutomationTarget.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+export class NexusAutomationTargetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationTargetError";
+    }
+}
+export function readNexusAutomationTargetContext(options) {
+    const statePath = resolveProjectRelativePath(options.projectRoot, options.config.target.statePath, "automation.target.statePath");
+    const cycleLedgerPath = resolveProjectRelativePath(options.projectRoot, options.config.target.cycleLedgerPath, "automation.target.cycleLedgerPath");
+    const stateExists = fs.existsSync(statePath);
+    return {
+        id: options.config.target.id,
+        objective: options.config.target.objective,
+        statePath,
+        cycleLedgerPath,
+        stateExists,
+        stateMarkdown: stateExists ? fs.readFileSync(statePath, "utf8") : null,
+        stopWhenNoEligibleWork: options.config.target.stopWhenNoEligibleWork,
+        maxCycles: options.config.target.maxCycles,
+        maxWorkItems: options.config.target.maxWorkItems,
+    };
+}
+function resolveProjectRelativePath(projectRoot, configuredPath, fieldName) {
+    const root = path.resolve(projectRoot);
+    const target = path.resolve(root, configuredPath);
+    const relative = path.relative(root, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new NexusAutomationTargetError(`${fieldName} must resolve inside the project root: ${target}`);
+    }
+    return target;
+}

package/dist/nexusAutomationTargetCycle.d.ts

@@ -0,0 +1,90 @@
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+import type { WorkStatus } from "./workTrackingTypes.js";
+export declare const maxNexusAutomationTargetCycleNoteLength = 1000;
+export type NexusAutomationTargetCycleStatus = "started" | "dispatched" | "completed" | "blocked" | "failed" | "skipped";
+export type NexusAutomationTargetCycleWorkItemStatus = "eligible" | "selected" | "dispatched" | "in_progress" | "completed" | "blocked" | "skipped";
+export interface NexusAutomationTargetCycleWorkItem {
+    componentId: string | null;
+    id: string;
+    title: string | null;
+    status: WorkStatus | null;
+    cycleStatus: NexusAutomationTargetCycleWorkItemStatus | null;
+    agentProfileId: string | null;
+    notes: string | null;
+}
+export interface NexusAutomationTargetCycleRecord {
+    id: string;
+    projectId: string;
+    targetId: string | null;
+    runId: string | null;
+    status: NexusAutomationTargetCycleStatus;
+    startedAt: string;
+    finishedAt: string | null;
+    objective: string | null;
+    summary: string | null;
+    eligibleWorkItemCount: number | null;
+    workItems: NexusAutomationTargetCycleWorkItem[];
+    blockers: string[];
+    notes: string[];
+    nextCycleNotBefore: string | null;
+}
+export interface NexusAutomationTargetCycleRecordInput {
+    id?: string;
+    projectId: string;
+    targetId?: string | null;
+    runId?: string | null;
+    status: NexusAutomationTargetCycleStatus;
+    startedAt?: string;
+    finishedAt?: string | null;
+    objective?: string | null;
+    summary?: string | null;
+    eligibleWorkItemCount?: number | null;
+    workItems?: NexusAutomationTargetCycleWorkItemInput[];
+    blockers?: string[];
+    notes?: string[];
+    nextCycleNotBefore?: string | null;
+}
+export interface NexusAutomationTargetCycleWorkItemInput {
+    componentId?: string | null;
+    id: string;
+    title?: string | null;
+    status?: WorkStatus | null;
+    cycleStatus?: NexusAutomationTargetCycleWorkItemStatus | null;
+    agentProfileId?: string | null;
+    notes?: string | null;
+}
+export interface NexusAutomationTargetCycleLedger {
+    version: 1;
+    cycles: NexusAutomationTargetCycleRecord[];
+    updatedAt: string | null;
+}
+export interface AppendNexusAutomationTargetCycleRecordOptions {
+    projectRoot: string;
+    config: NexusAutomationConfig;
+    record: NexusAutomationTargetCycleRecordInput;
+    now?: Date | string;
+}
+export interface NexusAutomationTargetCycleSummary {
+    ledgerPath: string;
+    cycleCount: number;
+    activeCycleCount: number;
+    completedCycleCount: number;
+    blockedCycleCount: number;
+    failedCycleCount: number;
+    skippedCycleCount: number;
+    lastCycle: NexusAutomationTargetCycleRecord | null;
+}
+export declare class NexusAutomationTargetCycleError extends Error {
+    constructor(message: string);
+}
+export declare function nexusAutomationTargetCycleLedgerPath(projectRoot: string, config: NexusAutomationConfig): string;
+export declare function emptyNexusAutomationTargetCycleLedger(): NexusAutomationTargetCycleLedger;
+export declare function readNexusAutomationTargetCycleLedger(projectRoot: string, config: NexusAutomationConfig): NexusAutomationTargetCycleLedger;
+export declare function writeNexusAutomationTargetCycleLedger(projectRoot: string, config: NexusAutomationConfig, ledger: NexusAutomationTargetCycleLedger): string;
+export declare function appendNexusAutomationTargetCycleRecord(options: AppendNexusAutomationTargetCycleRecordOptions): NexusAutomationTargetCycleLedger;
+export declare function summarizeNexusAutomationTargetCycles(options: {
+    projectRoot: string;
+    config: NexusAutomationConfig;
+}): NexusAutomationTargetCycleSummary;
+export declare function normalizeNexusAutomationTargetCycleLedger(value: unknown): NexusAutomationTargetCycleLedger;
+export declare function generateNexusAutomationTargetCycleId(now?: Date | string): string;