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

package/dist/nexusAutomationScheduler.js

@@ -0,0 +1,196 @@
+import path from "node:path";
+import { runNexusAutomationOnce, } from "./nexusAutomationRunOnce.js";
+import { runNexusAutomationAgentLaunchOnce, } from "./nexusAutomationAgentLaunch.js";
+import { getNexusAutomationStatus, } from "./nexusAutomationStatus.js";
+export class NexusAutomationSchedulerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationSchedulerError";
+    }
+}
+export async function runNexusAutomationScheduler(options) {
+    const projectRoot = path.resolve(requiredNonEmptyString(options.projectRoot, "projectRoot"));
+    const intervalOverride = optionalPositiveInteger(options.intervalMs, "intervalMs");
+    const maxTicks = optionalPositiveInteger(options.maxTicks, "maxTicks");
+    const maxRuns = optionalPositiveInteger(options.maxRuns, "maxRuns");
+    const sleep = options.sleep ?? defaultSleep;
+    const startedAt = currentIso(options.now);
+    const ticks = [];
+    const runs = [];
+    let stoppedReason = "stopped";
+    while (true) {
+        if (options.shouldStop?.()) {
+            stoppedReason = "stopped";
+            break;
+        }
+        const tickStartedAt = currentIso(options.now);
+        const status = await getNexusAutomationStatus({
+            projectRoot,
+            provider: options.provider,
+            providerFactory: options.providerFactory,
+            providerOptions: options.providerOptions,
+            now: options.now,
+        });
+        const intervalMs = intervalOverride ?? status.automationConfig?.schedule.intervalMs;
+        if (!status.automationConfig?.schedule.enabled || !intervalMs) {
+            const tick = schedulerTick({
+                index: ticks.length + 1,
+                startedAt: tickStartedAt,
+                finishedAt: currentIso(options.now),
+                status,
+                action: "stopped",
+                waitMs: null,
+                run: null,
+            });
+            ticks.push(tick);
+            await options.onTick?.(tick);
+            stoppedReason = "disabled";
+            break;
+        }
+        let action = "waited";
+        let waitMs = nextNexusAutomationSchedulerDelayMs(status, intervalMs, tickStartedAt);
+        let run = null;
+        if (status.status === "ready") {
+            const runId = schedulerRunId(options.runIdPrefix, ticks.length + 1, tickStartedAt);
+            if (status.automationConfig?.mode === "agent_launch") {
+                if (!options.agentLauncher) {
+                    throw new NexusAutomationSchedulerError("agentLauncher is required when automation.mode is agent_launch");
+                }
+                run = await runNexusAutomationAgentLaunchOnce({
+                    projectRoot,
+                    provider: options.provider,
+                    providerFactory: options.providerFactory,
+                    providerOptions: options.providerOptions,
+                    now: options.now,
+                    owner: options.owner ?? "scheduler",
+                    runId,
+                    launcher: options.agentLauncher,
+                });
+                waitMs = status.automationConfig.agent.relaunch.whileEligible &&
+                    maxRuns !== undefined
+                    ? 0
+                    : intervalMs;
+            }
+            else {
+                if (!options.executor) {
+                    throw new NexusAutomationSchedulerError("executor is required when automation.mode is run_once");
+                }
+                run = await runNexusAutomationOnce({
+                    projectRoot,
+                    provider: options.provider,
+                    providerFactory: options.providerFactory,
+                    providerOptions: options.providerOptions,
+                    gitRunner: options.gitRunner,
+                    now: options.now,
+                    owner: options.owner ?? "scheduler",
+                    baseRef: options.baseRef,
+                    runId,
+                    executor: options.executor,
+                });
+            }
+            runs.push(run);
+            action = "ran";
+        }
+        const tick = schedulerTick({
+            index: ticks.length + 1,
+            startedAt: tickStartedAt,
+            finishedAt: currentIso(options.now),
+            status,
+            action,
+            waitMs,
+            run,
+        });
+        ticks.push(tick);
+        await options.onTick?.(tick);
+        if (maxRuns !== undefined && runs.length >= maxRuns) {
+            stoppedReason = "max_runs";
+            break;
+        }
+        if (maxTicks !== undefined && ticks.length >= maxTicks) {
+            stoppedReason = "max_ticks";
+            break;
+        }
+        if (options.shouldStop?.()) {
+            stoppedReason = "stopped";
+            break;
+        }
+        await sleep(waitMs);
+    }
+    return {
+        projectRoot,
+        startedAt,
+        finishedAt: currentIso(options.now),
+        ticks,
+        runs,
+        stoppedReason,
+    };
+}
+export function nextNexusAutomationSchedulerDelayMs(status, intervalMs, now = new Date()) {
+    const normalizedInterval = optionalPositiveInteger(intervalMs, "intervalMs");
+    if (normalizedInterval === undefined) {
+        throw new NexusAutomationSchedulerError("intervalMs is required");
+    }
+    if (status.status === "backoff" && status.backoff?.retryAfter) {
+        return delayUntil(status.backoff.retryAfter, now);
+    }
+    if (status.status === "locked" && status.lock?.expiresAt) {
+        return delayUntil(status.lock.expiresAt, now);
+    }
+    return normalizedInterval;
+}
+function schedulerTick(tick) {
+    return tick;
+}
+function schedulerRunId(prefix, tickIndex, timestamp) {
+    return [
+        safeRunIdPrefix(prefix ?? "scheduled"),
+        timestamp.replaceAll("-", "").replaceAll(":", "").replace(".", "-"),
+        tickIndex.toString(),
+    ].join("-");
+}
+function safeRunIdPrefix(value) {
+    const normalized = value
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (!normalized) {
+        throw new NexusAutomationSchedulerError("runIdPrefix must contain at least one safe character");
+    }
+    return normalized;
+}
+function delayUntil(target, now) {
+    const targetDate = dateFrom(target, "target");
+    const nowDate = dateFrom(now, "now");
+    return Math.max(0, targetDate.getTime() - nowDate.getTime());
+}
+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 NexusAutomationSchedulerError(`${name} must be a valid date`);
+    }
+    return date;
+}
+async function defaultSleep(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function optionalPositiveInteger(value, name) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new NexusAutomationSchedulerError(`${name} must be a positive integer`);
+    }
+    return value;
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationSchedulerError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/nexusAutomationStatus.d.ts

@@ -0,0 +1,55 @@
+import { type NexusAutomationBackoffDecision, type NexusAutomationRunLedger } from "./nexusAutomation.js";
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+import { type NexusAutomationComponentEligibleWorkItems } from "./nexusAutomationAgentLaunch.js";
+import { type NexusAutomationAgentPolicy } from "./nexusAutomationAgentProfile.js";
+import { type NexusProjectConfig } from "./nexusProjectConfig.js";
+import { type NexusAutomationTargetContext } from "./nexusAutomationTarget.js";
+import { type NexusAutomationTargetCycleSummary } from "./nexusAutomationTargetCycle.js";
+import { type ResolvedNexusProjectComponent } from "./nexusProjectLifecycle.js";
+import { type NexusAutomationPreflightCheck, type NexusAutomationWorkTrackerProviderFactory } from "./nexusAutomationRunOnce.js";
+import { type CreateWorkTrackerProviderOptions } from "./workTrackingProviderService.js";
+import type { WorkItem, WorkItemQuery, WorkTrackerProvider } from "./workTrackingTypes.js";
+export type NexusAutomationStatusKind = "disabled" | "locked" | "backoff" | "blocked" | "idle" | "ready";
+export type NexusAutomationLockStatusKind = "none" | "active" | "stale" | "invalid";
+export interface NexusAutomationStatusLock {
+    path: string;
+    status: NexusAutomationLockStatusKind;
+    runId: string | null;
+    owner: string | null;
+    acquiredAt: string | null;
+    expiresAt: string | null;
+    message: string;
+}
+export interface GetNexusAutomationStatusOptions {
+    projectRoot: string;
+    provider?: WorkTrackerProvider;
+    providerFactory?: NexusAutomationWorkTrackerProviderFactory;
+    providerOptions?: CreateWorkTrackerProviderOptions;
+    now?: () => Date | string;
+}
+export interface NexusAutomationStatus {
+    projectRoot: string;
+    sourceRoot: string | null;
+    components: ResolvedNexusProjectComponent[];
+    projectConfig: NexusProjectConfig;
+    automationConfig: NexusAutomationConfig | null;
+    status: NexusAutomationStatusKind;
+    summary: string;
+    lock: NexusAutomationStatusLock | null;
+    ledger: NexusAutomationRunLedger | null;
+    backoff: NexusAutomationBackoffDecision | null;
+    preflight: NexusAutomationPreflightCheck[];
+    target: NexusAutomationTargetContext | null;
+    targetCycles: NexusAutomationTargetCycleSummary | null;
+    agent: NexusAutomationAgentPolicy | null;
+    selectorQuery: WorkItemQuery | null;
+    candidateCount: number | null;
+    eligibleWorkItems: WorkItem[] | null;
+    componentEligibleWorkItems: NexusAutomationComponentEligibleWorkItems[] | null;
+    selectedWorkItem: WorkItem | null;
+}
+export declare class NexusAutomationStatusError extends Error {
+    constructor(message: string);
+}
+export declare function getNexusAutomationStatus(options: GetNexusAutomationStatusOptions): Promise<NexusAutomationStatus>;
+export declare function readNexusAutomationStatusLock(projectRoot: string, config: NexusAutomationConfig, now?: Date | string): NexusAutomationStatusLock;