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

package/dist/nexusAutomationRunOnce.js

@@ -0,0 +1,586 @@
+import fs from "node:fs";
+import path from "node:path";
+import { prepareGitWorktree, safeDirectoryName, } from "./gitWorktreeService.js";
+import { acquireNexusAutomationRunLock, appendNexusAutomationRunRecord, buildNexusAutomationWorkItemQuery, evaluateNexusAutomationLedgerBackoff, readNexusAutomationRunLedger, releaseNexusAutomationRunLock, selectNexusAutomationWorkItem, } from "./nexusAutomation.js";
+import { materializeNexusAutomationWorktreeSetup, preflightNexusAutomationWorktreeSetup, } from "./nexusAutomationWorktreeSetup.js";
+import { loadProjectConfig, } from "./nexusProjectConfig.js";
+import { projectPluginDependencyProjections, projectPluginWorkerFragments, } from "./nexusPluginCapabilities.js";
+import { resolvePrimaryProjectComponent, } from "./nexusProjectLifecycle.js";
+import { applyWorktreeExecutionUpdate, emptyWorktreeExecutionMetadata, writeWorktreeExecutionMetadata, worktreeOwnershipMetadataFromPreparedWorktree, } from "./worktreeExecutionMetadata.js";
+import { createWorkTrackerProvider, } from "./workTrackingProviderService.js";
+export class NexusAutomationRunOnceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationRunOnceError";
+    }
+}
+export async function runNexusAutomationOnce(options) {
+    const projectRoot = path.resolve(requiredNonEmptyString(options.projectRoot, "projectRoot"));
+    const projectConfig = loadProjectConfig(projectRoot);
+    const automationConfig = projectConfig.automation ?? null;
+    const runId = options.runId ?? generateNexusAutomationRunId(options.now);
+    const comments = [];
+    let sourceRoot = null;
+    let lock = null;
+    let workItem = null;
+    let updatedWorkItem = null;
+    let worktree = null;
+    let setup = null;
+    let ledger = null;
+    let provider = null;
+    let primaryComponent = null;
+    let preflight = [];
+    let pluginDependencyProjections = [];
+    if (!automationConfig?.enabled) {
+        return {
+            runId,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            status: "skipped",
+            summary: "Automation is not enabled for this project",
+            ledger,
+            lock,
+            preflight: [],
+            workItem,
+            worktree,
+            setup,
+            execution: null,
+            comments,
+            updatedWorkItem,
+        };
+    }
+    const startedAt = currentIso(options.now);
+    lock = acquireNexusAutomationRunLock({
+        projectRoot,
+        config: automationConfig,
+        runId,
+        owner: options.owner ?? null,
+        now: startedAt,
+    });
+    try {
+        ledger = readNexusAutomationRunLedger(projectRoot, automationConfig);
+        const backoff = evaluateNexusAutomationLedgerBackoff(automationConfig, ledger, startedAt);
+        if (!backoff.shouldRun) {
+            const summary = backoff.reason ?? "Automation retry backoff is active";
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: startedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    status: "skipped",
+                    startedAt,
+                    finishedAt: startedAt,
+                    summary,
+                    nextRunNotBefore: backoff.retryAfter,
+                },
+            });
+            return runResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "skipped",
+                summary,
+                ledger,
+                lock,
+                preflight: [],
+                workItem,
+                worktree,
+                setup,
+                execution: null,
+                comments,
+                updatedWorkItem,
+            });
+        }
+        primaryComponent = resolvePrimaryProjectComponent(projectRoot, projectConfig);
+        sourceRoot = primaryComponent.sourceRoot;
+        if (!primaryComponent.workTracking) {
+            const summary = "Primary component work tracking is not configured";
+            preflight = [
+                check("workTracking", false, "Primary component has work tracking configured", summary),
+            ];
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: startedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    componentId: primaryComponent.id,
+                    status: "blocked",
+                    startedAt,
+                    finishedAt: startedAt,
+                    sourceRoot,
+                    summary,
+                    error: summary,
+                },
+            });
+            return runResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "blocked",
+                summary,
+                ledger,
+                lock,
+                preflight,
+                workItem,
+                worktree,
+                setup,
+                execution: null,
+                comments,
+                updatedWorkItem,
+            });
+        }
+        pluginDependencyProjections = automationPluginDependencyProjections(projectConfig, primaryComponent.id);
+        provider = createAutomationProvider({
+            options,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            component: primaryComponent,
+        });
+        preflight = preflightNexusAutomationRunOnce({
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            component: primaryComponent,
+            automationConfig,
+            provider,
+            pluginDependencyProjections,
+        });
+        const failedChecks = preflight.filter((check) => check.status === "failed");
+        if (failedChecks.length > 0) {
+            const summary = failedChecks.map((check) => check.message).join("; ");
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: startedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    componentId: primaryComponent.id,
+                    status: "blocked",
+                    startedAt,
+                    finishedAt: startedAt,
+                    sourceRoot,
+                    summary,
+                    error: summary,
+                },
+            });
+            return runResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "blocked",
+                summary,
+                ledger,
+                lock,
+                preflight,
+                workItem,
+                worktree,
+                setup,
+                execution: null,
+                comments,
+                updatedWorkItem,
+            });
+        }
+        const candidates = await provider.listWorkItems({
+            ...buildNexusAutomationWorkItemQuery(automationConfig),
+            projectRoot,
+        });
+        workItem = selectNexusAutomationWorkItem(candidates, automationConfig) ?? null;
+        if (!workItem) {
+            const summary = "No eligible work item matched the automation selector";
+            const finishedAt = currentIso(options.now);
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: finishedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    componentId: primaryComponent.id,
+                    status: "skipped",
+                    startedAt,
+                    finishedAt,
+                    sourceRoot,
+                    summary,
+                },
+            });
+            return runResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "skipped",
+                summary,
+                ledger,
+                lock,
+                preflight,
+                workItem,
+                worktree,
+                setup,
+                execution: null,
+                comments,
+                updatedWorkItem,
+            });
+        }
+        const baseRef = options.baseRef ??
+            primaryComponent.defaultBranch ??
+            projectConfig.repo.defaultBranch ??
+            null;
+        const branchName = options.branchName ?? defaultAutomationBranchName(projectConfig.id, workItem.id, runId);
+        worktree = prepareGitWorktree({
+            componentId: primaryComponent.id,
+            sourceRoot,
+            worktreesRoot: primaryComponent.worktreesRoot,
+            branchName,
+            ...(options.worktreeName ? { worktreeName: options.worktreeName } : {}),
+            ...(baseRef ? { baseRef } : {}),
+            workItemId: workItem.id,
+            workItemTitle: workItem.title,
+            ...(options.gitRunner ? { gitRunner: options.gitRunner } : {}),
+        });
+        setup = materializeNexusAutomationWorktreeSetup({
+            sourceRoot,
+            worktreesRoot: primaryComponent.worktreesRoot,
+            worktreePath: worktree.worktreePath,
+            automationConfig,
+            pluginDependencyProjections,
+            skillsConfig: projectConfig.skills,
+            context: {
+                project: {
+                    id: projectConfig.id,
+                    name: projectConfig.name,
+                    root: projectRoot,
+                },
+                ownership: {
+                    componentId: worktree.componentId,
+                    sourceRoot: worktree.sourceRoot,
+                    worktreesRoot: worktree.worktreesRoot,
+                    worktreePath: worktree.worktreePath,
+                    branchName: worktree.branchName,
+                    baseRef: worktree.baseRef,
+                    workItem: worktree.workItem,
+                },
+                pluginFragments: projectPluginWorkerFragments(projectConfig, {
+                    componentId: primaryComponent.id,
+                }),
+            },
+            ...(options.gitRunner ? { gitRunner: options.gitRunner } : {}),
+        });
+        updatedWorkItem = await setTrackerStatus(provider, workItem, "in_progress");
+        comments.push(await provider.addComment(workItemRef(workItem), startedTrackerComment(runId, worktree)));
+        const executorResult = await options.executor({
+            runId,
+            startedAt,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            workItem,
+            worktree,
+            setup,
+        });
+        const finishedAt = currentIso(options.now);
+        const execution = executionMetadataFromExecutorResult(executorResult, finishedAt, worktree);
+        writeWorktreeExecutionMetadata(worktree.worktreePath, execution);
+        const status = normalizeExecutorStatus(executorResult.status);
+        if (status === "completed") {
+            updatedWorkItem = await setTrackerStatus(provider, workItem, "done");
+        }
+        else if (status === "blocked") {
+            updatedWorkItem = await setTrackerStatus(provider, workItem, "blocked");
+        }
+        const summary = executorResult.summary ?? defaultRunSummary(status);
+        comments.push(await provider.addComment(workItemRef(workItem), finishedTrackerComment(runId, status, summary)));
+        ledger = appendNexusAutomationRunRecord({
+            projectRoot,
+            config: automationConfig,
+            now: finishedAt,
+            record: {
+                id: runId,
+                projectId: projectConfig.id,
+                componentId: primaryComponent.id,
+                status,
+                startedAt,
+                finishedAt,
+                workItemId: workItem.id,
+                workItemTitle: workItem.title,
+                sourceRoot,
+                worktreePath: worktree.worktreePath,
+                branchName: worktree.branchName,
+                baseRef: worktree.baseRef,
+                commitIds: execution.commitIds,
+                summary,
+                verification: execution.verification,
+                publicationDecision: execution.publicationDecision,
+                error: executorResult.error ?? null,
+            },
+        });
+        return runResult({
+            runId,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            status,
+            summary,
+            ledger,
+            lock,
+            preflight,
+            workItem,
+            worktree,
+            setup,
+            execution,
+            comments,
+            updatedWorkItem,
+        });
+    }
+    catch (error) {
+        if (!automationConfig) {
+            throw error;
+        }
+        const finishedAt = currentIso(options.now);
+        const summary = errorMessage(error);
+        await tryAddFailureComment(provider ?? undefined, workItem, runId, summary);
+        ledger = appendNexusAutomationRunRecord({
+            projectRoot,
+            config: automationConfig,
+            now: finishedAt,
+            record: {
+                id: runId,
+                projectId: projectConfig.id,
+                componentId: primaryComponent?.id ?? null,
+                status: "failed",
+                startedAt,
+                finishedAt,
+                workItemId: workItem?.id ?? null,
+                workItemTitle: workItem?.title ?? null,
+                sourceRoot,
+                worktreePath: worktree?.worktreePath ?? null,
+                branchName: worktree?.branchName ?? null,
+                baseRef: worktree?.baseRef ?? null,
+                summary,
+                error: summary,
+            },
+        });
+        return runResult({
+            runId,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            status: "failed",
+            summary,
+            ledger,
+            lock,
+            preflight,
+            workItem,
+            worktree,
+            setup,
+            execution: null,
+            comments,
+            updatedWorkItem,
+        });
+    }
+    finally {
+        if (automationConfig) {
+            releaseNexusAutomationRunLock({
+                projectRoot,
+                config: automationConfig,
+                runId,
+            });
+        }
+    }
+}
+export function preflightNexusAutomationRunOnce(options) {
+    const worktreesRoot = options.component.worktreesRoot;
+    return [
+        check("workTracking", Boolean(options.component.workTracking), "Primary component has work tracking configured", "Primary component work tracking is not configured"),
+        check("trackerListItems", options.provider.capabilities.listItems, "Tracker can list work items", `Tracker provider ${options.provider.provider} cannot list work items`),
+        check("trackerUpdateItems", options.provider.capabilities.updateItem, "Tracker can update work items", `Tracker provider ${options.provider.provider} cannot update work items`),
+        check("trackerComments", options.provider.capabilities.comment, "Tracker can record run comments", `Tracker provider ${options.provider.provider} cannot record comments`),
+        check("gitRepository", options.component.kind === "git", "Primary component source is Git-backed", "Automation worktree preparation requires the primary component to be Git-backed"),
+        check("sourceRoot", fs.existsSync(options.sourceRoot) && fs.statSync(options.sourceRoot).isDirectory(), "Primary component source root exists", `Primary component source root does not exist: ${options.sourceRoot}`),
+        check("worktreesRoot", pathIsInside(options.projectRoot, worktreesRoot), "Project worktrees root stays inside the project root", `Automation worktreesRoot must resolve inside the project root: ${worktreesRoot}`),
+        ...preflightNexusAutomationWorktreeSetup({
+            sourceRoot: options.sourceRoot,
+            automationConfig: options.automationConfig,
+            pluginDependencyProjections: options.pluginDependencyProjections,
+        }),
+    ];
+}
+function automationPluginDependencyProjections(projectConfig, componentId) {
+    return projectPluginDependencyProjections(projectConfig, {
+        componentId,
+    }).map((projection) => ({
+        id: projection.id,
+        source: projection.source,
+        target: projection.target,
+        required: projection.required,
+        sourceControl: projection.sourceControl,
+        reason: projection.reason,
+        sourceMetadata: {
+            pluginId: projection.pluginSource.pluginId,
+            pluginName: projection.pluginSource.pluginName,
+            version: projection.pluginSource.version,
+            capabilityId: projection.pluginSource.capabilityId,
+        },
+    }));
+}
+export function generateNexusAutomationRunId(now) {
+    const timestamp = currentIso(now)
+        .replaceAll("-", "")
+        .replaceAll(":", "")
+        .replace(".", "-");
+    const suffix = Math.random().toString(36).slice(2, 8);
+    return `run-${timestamp}-${suffix}`;
+}
+function createAutomationProvider(options) {
+    const workTracking = options.component.workTracking;
+    if (!workTracking) {
+        throw new NexusAutomationRunOnceError("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 executionMetadataFromExecutorResult(result, finishedAt, worktree) {
+    let metadata = emptyWorktreeExecutionMetadata();
+    const verification = result.verification ?? [];
+    const initialUpdate = {
+        worktree: worktreeOwnershipMetadataFromPreparedWorktree(worktree),
+        ...(result.commitIds?.length ? { commitIds: result.commitIds } : {}),
+        ...(result.publicationDecision
+            ? { publicationDecision: result.publicationDecision }
+            : {}),
+        ...(verification[0] ? { verification: verification[0] } : {}),
+    };
+    if (hasExecutionUpdate(initialUpdate)) {
+        metadata = applyWorktreeExecutionUpdate(metadata, initialUpdate, finishedAt);
+    }
+    for (const verificationRecord of verification.slice(1)) {
+        metadata = applyWorktreeExecutionUpdate(metadata, { verification: verificationRecord }, finishedAt);
+    }
+    return metadata;
+}
+function hasExecutionUpdate(update) {
+    return Boolean(Object.prototype.hasOwnProperty.call(update, "worktree") ||
+        update.commitIds?.length ||
+        update.verification ||
+        update.publicationDecision);
+}
+async function setTrackerStatus(provider, item, status) {
+    if (provider.setStatus) {
+        return provider.setStatus(workItemRef(item), status);
+    }
+    return provider.updateWorkItem(workItemRef(item), { status });
+}
+async function tryAddFailureComment(provider, item, runId, summary) {
+    if (!provider || !item || !provider.capabilities.comment) {
+        return;
+    }
+    try {
+        await provider.addComment(workItemRef(item), finishedTrackerComment(runId, "failed", summary));
+    }
+    catch {
+        // Failure recording must not be masked by a best-effort tracker comment.
+    }
+}
+function workItemRef(item) {
+    return {
+        id: item.id,
+        provider: item.provider,
+        ...(item.externalRef ? { externalRef: item.externalRef } : {}),
+    };
+}
+function startedTrackerComment(runId, worktree) {
+    return [
+        `DevNexus automation run ${runId} started.`,
+        `Worktree: ${worktree.worktreePath}`,
+        `Branch: ${worktree.branchName}`,
+    ].join("\n");
+}
+function finishedTrackerComment(runId, status, summary) {
+    return [
+        `DevNexus automation run ${runId} ${status}.`,
+        `Summary: ${summary}`,
+    ].join("\n");
+}
+function normalizeExecutorStatus(status) {
+    return status ?? "completed";
+}
+function defaultRunSummary(status) {
+    if (status === "completed") {
+        return "Automation executor completed";
+    }
+    if (status === "blocked") {
+        return "Automation executor reported a blocker";
+    }
+    return "Automation executor failed";
+}
+function defaultAutomationBranchName(projectId, workItemId, runId) {
+    return [
+        "codex",
+        safeDirectoryName(projectId),
+        safeDirectoryName(workItemId),
+        safeDirectoryName(runId),
+    ].join("/");
+}
+function check(name, passed, passedMessage, failedMessage) {
+    return {
+        name,
+        status: passed ? "passed" : "failed",
+        message: passed ? passedMessage : failedMessage,
+    };
+}
+function pathIsInside(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function runResult(result) {
+    return result;
+}
+function currentIso(now) {
+    const value = now ? now() : new Date();
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new NexusAutomationRunOnceError("now must return a valid date");
+    }
+    return date.toISOString();
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationRunOnceError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/nexusAutomationScheduler.d.ts

@@ -0,0 +1,50 @@
+import type { GitRunner } from "./gitWorktreeService.js";
+import { type NexusAutomationExecutor, type RunNexusAutomationOnceResult, type NexusAutomationWorkTrackerProviderFactory } from "./nexusAutomationRunOnce.js";
+import { type NexusAutomationAgentLauncher, type RunNexusAutomationAgentLaunchOnceResult } from "./nexusAutomationAgentLaunch.js";
+import { type NexusAutomationStatus } from "./nexusAutomationStatus.js";
+import type { CreateWorkTrackerProviderOptions } from "./workTrackingProviderService.js";
+import type { WorkTrackerProvider } from "./workTrackingTypes.js";
+export type NexusAutomationSchedulerAction = "ran" | "waited" | "stopped";
+export type NexusAutomationSchedulerStopReason = "disabled" | "max_runs" | "max_ticks" | "stopped";
+export type NexusAutomationSchedulerRunResult = RunNexusAutomationOnceResult | RunNexusAutomationAgentLaunchOnceResult;
+export interface NexusAutomationSchedulerTick {
+    index: number;
+    startedAt: string;
+    finishedAt: string;
+    status: NexusAutomationStatus;
+    action: NexusAutomationSchedulerAction;
+    waitMs: number | null;
+    run: NexusAutomationSchedulerRunResult | null;
+}
+export interface RunNexusAutomationSchedulerOptions {
+    projectRoot: string;
+    executor?: NexusAutomationExecutor;
+    agentLauncher?: NexusAutomationAgentLauncher;
+    owner?: string | null;
+    baseRef?: string | null;
+    provider?: WorkTrackerProvider;
+    providerFactory?: NexusAutomationWorkTrackerProviderFactory;
+    providerOptions?: CreateWorkTrackerProviderOptions;
+    gitRunner?: GitRunner;
+    now?: () => Date | string;
+    sleep?: (ms: number) => Promise<void>;
+    onTick?: (tick: NexusAutomationSchedulerTick) => void | Promise<void>;
+    intervalMs?: number;
+    maxTicks?: number;
+    maxRuns?: number;
+    runIdPrefix?: string;
+    shouldStop?: () => boolean;
+}
+export interface RunNexusAutomationSchedulerResult {
+    projectRoot: string;
+    startedAt: string;
+    finishedAt: string;
+    ticks: NexusAutomationSchedulerTick[];
+    runs: NexusAutomationSchedulerRunResult[];
+    stoppedReason: NexusAutomationSchedulerStopReason;
+}
+export declare class NexusAutomationSchedulerError extends Error {
+    constructor(message: string);
+}
+export declare function runNexusAutomationScheduler(options: RunNexusAutomationSchedulerOptions): Promise<RunNexusAutomationSchedulerResult>;
+export declare function nextNexusAutomationSchedulerDelayMs(status: NexusAutomationStatus, intervalMs: number, now?: Date | string): number;