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

package/dist/nexusAutomation.js

@@ -0,0 +1,390 @@
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeWorktreeExecutionMetadata, } from "./worktreeExecutionMetadata.js";
+export class NexusAutomationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationError";
+    }
+}
+export function nexusAutomationLedgerPath(projectRoot, config) {
+    return resolveAutomationStatePath(projectRoot, config.ledger.path, "automation.ledger.path");
+}
+export function nexusAutomationLockPath(projectRoot, config) {
+    return resolveAutomationStatePath(projectRoot, config.lock.path, "automation.lock.path");
+}
+export function emptyNexusAutomationRunLedger() {
+    return {
+        version: 1,
+        runs: [],
+        updatedAt: null,
+    };
+}
+export function readNexusAutomationRunLedger(projectRoot, config) {
+    const ledgerPath = nexusAutomationLedgerPath(projectRoot, config);
+    if (!fs.existsSync(ledgerPath)) {
+        return emptyNexusAutomationRunLedger();
+    }
+    return normalizeNexusAutomationRunLedger(JSON.parse(fs.readFileSync(ledgerPath, "utf8").replace(/^\uFEFF/, "")));
+}
+export function writeNexusAutomationRunLedger(projectRoot, config, ledger) {
+    const ledgerPath = nexusAutomationLedgerPath(projectRoot, config);
+    const normalized = normalizeNexusAutomationRunLedger(ledger);
+    fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+    fs.writeFileSync(ledgerPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+    return ledgerPath;
+}
+export function appendNexusAutomationRunRecord(options) {
+    const recordedAt = isoString(options.now ?? new Date());
+    const record = normalizeRunRecordInput(options.record, recordedAt);
+    const existing = readNexusAutomationRunLedger(options.projectRoot, options.config);
+    const runs = [...existing.runs, record].slice(-options.config.ledger.retention);
+    const ledger = {
+        version: 1,
+        runs,
+        updatedAt: recordedAt,
+    };
+    writeNexusAutomationRunLedger(options.projectRoot, options.config, ledger);
+    return ledger;
+}
+export function normalizeNexusAutomationRunLedger(value) {
+    if (value === undefined || value === null) {
+        return emptyNexusAutomationRunLedger();
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationError("automation run ledger must be an object");
+    }
+    const record = value;
+    if (record.version !== 1) {
+        throw new NexusAutomationError("automation run ledger.version must be 1");
+    }
+    if (!Array.isArray(record.runs)) {
+        throw new NexusAutomationError("automation run ledger.runs must be an array");
+    }
+    return {
+        version: 1,
+        runs: record.runs.map(normalizeRunRecord),
+        updatedAt: optionalNullableString(record.updatedAt) ?? null,
+    };
+}
+export function acquireNexusAutomationRunLock(options) {
+    const lockPath = nexusAutomationLockPath(options.projectRoot, options.config);
+    const runId = requiredNonEmptyString(options.runId, "runId");
+    const now = dateFrom(options.now ?? new Date(), "now");
+    const lock = {
+        runId,
+        owner: optionalNullableString(options.owner) ?? null,
+        acquiredAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + options.config.lock.staleAfterMs)
+            .toISOString(),
+    };
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const initial = tryWriteLock(lockPath, lock);
+    if (initial) {
+        return { lockPath, lock, replacedStaleLock: false };
+    }
+    const existing = readExistingLock(lockPath);
+    if (dateFrom(existing.expiresAt, "automation lock.expiresAt").getTime() > now.getTime()) {
+        throw new NexusAutomationError(`Automation run lock is already held by ${existing.runId} until ${existing.expiresAt}`);
+    }
+    fs.rmSync(lockPath, { force: true });
+    if (!tryWriteLock(lockPath, lock)) {
+        throw new NexusAutomationError(`Automation run lock could not be acquired: ${lockPath}`);
+    }
+    return { lockPath, lock, replacedStaleLock: true };
+}
+export function releaseNexusAutomationRunLock(options) {
+    const lockPath = nexusAutomationLockPath(options.projectRoot, options.config);
+    if (!fs.existsSync(lockPath)) {
+        return false;
+    }
+    if (options.runId) {
+        const existing = readExistingLock(lockPath);
+        if (existing.runId !== options.runId) {
+            return false;
+        }
+    }
+    fs.rmSync(lockPath, { force: true });
+    return true;
+}
+export function buildNexusAutomationWorkItemQuery(config) {
+    const selector = config.selector;
+    return {
+        status: selector.statuses,
+        ...(selector.labels.length ? { labels: selector.labels } : {}),
+        ...(selector.assignees.length ? { assignees: selector.assignees } : {}),
+        ...(selector.search ? { search: selector.search } : {}),
+        limit: selector.limit,
+    };
+}
+export function selectNexusAutomationWorkItem(items, config) {
+    return items.find((item) => matchesSelector(item, config.selector));
+}
+export function eligibleNexusAutomationWorkItems(items, config) {
+    return items.filter((item) => matchesSelector(item, config.selector));
+}
+export function evaluateNexusAutomationBackoff(config, consecutiveFailures, lastFailureAt) {
+    if (!Number.isInteger(consecutiveFailures) || consecutiveFailures < 0) {
+        throw new NexusAutomationError("consecutiveFailures must be a non-negative integer");
+    }
+    if (consecutiveFailures === 0) {
+        return {
+            consecutiveFailures,
+            shouldRun: true,
+            retryAfter: null,
+            delayMs: null,
+            reason: null,
+        };
+    }
+    if (consecutiveFailures >= config.backoff.failureLimit) {
+        return {
+            consecutiveFailures,
+            shouldRun: false,
+            retryAfter: null,
+            delayMs: null,
+            reason: `automation failure limit reached: ${consecutiveFailures}`,
+        };
+    }
+    const failedAt = dateFrom(lastFailureAt, "lastFailureAt");
+    const delayMs = Math.min(config.backoff.maxDelayMs, config.backoff.baseDelayMs * 2 ** (consecutiveFailures - 1));
+    return {
+        consecutiveFailures,
+        shouldRun: false,
+        retryAfter: new Date(failedAt.getTime() + delayMs).toISOString(),
+        delayMs,
+        reason: "automation retry backoff is active",
+    };
+}
+export function countConsecutiveNexusAutomationFailures(ledger) {
+    let failures = 0;
+    for (let index = ledger.runs.length - 1; index >= 0; index -= 1) {
+        const run = ledger.runs[index];
+        if (run.status === "skipped") {
+            continue;
+        }
+        if (run.status === "failed" || run.status === "blocked") {
+            failures += 1;
+            continue;
+        }
+        break;
+    }
+    return failures;
+}
+export function evaluateNexusAutomationLedgerBackoff(config, ledger, now = new Date()) {
+    const consecutiveFailures = countConsecutiveNexusAutomationFailures(ledger);
+    if (consecutiveFailures === 0) {
+        return {
+            consecutiveFailures,
+            shouldRun: true,
+            retryAfter: null,
+            delayMs: null,
+            reason: null,
+        };
+    }
+    const lastFailure = [...ledger.runs]
+        .reverse()
+        .find((run) => run.status === "failed" || run.status === "blocked");
+    if (!lastFailure) {
+        return {
+            consecutiveFailures: 0,
+            shouldRun: true,
+            retryAfter: null,
+            delayMs: null,
+            reason: null,
+        };
+    }
+    const decision = evaluateNexusAutomationBackoff(config, consecutiveFailures, lastFailure.finishedAt ?? lastFailure.startedAt);
+    if (!decision.retryAfter) {
+        return decision;
+    }
+    const retryAt = dateFrom(decision.retryAfter, "retryAfter");
+    if (dateFrom(now, "now").getTime() >= retryAt.getTime()) {
+        return {
+            ...decision,
+            shouldRun: true,
+            reason: null,
+        };
+    }
+    return decision;
+}
+function resolveAutomationStatePath(projectRoot, configuredPath, fieldName) {
+    const root = path.resolve(projectRoot);
+    const target = path.resolve(root, configuredPath);
+    const relative = path.relative(root, target);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new NexusAutomationError(`${fieldName} must resolve inside the project root: ${target}`);
+    }
+    return target;
+}
+function matchesSelector(item, selector) {
+    return (selector.statuses.includes(item.status) &&
+        includesAll(normalizeStringList(item.labels), selector.labels) &&
+        includesNone(normalizeStringList(item.labels), selector.excludeLabels) &&
+        includesAll(normalizeStringList(item.assignees), selector.assignees) &&
+        matchesSearch(item, selector.search));
+}
+function includesAll(values, expected) {
+    return expected.every((value) => values.has(value.toLowerCase()));
+}
+function includesNone(values, blocked) {
+    return blocked.every((value) => !values.has(value.toLowerCase()));
+}
+function normalizeStringList(values) {
+    return new Set((values ?? []).map((value) => value.toLowerCase()));
+}
+function matchesSearch(item, search) {
+    if (!search) {
+        return true;
+    }
+    const needle = search.toLowerCase();
+    return [item.id, item.title, item.description ?? ""].some((value) => value.toLowerCase().includes(needle));
+}
+function tryWriteLock(lockPath, lock) {
+    try {
+        const handle = fs.openSync(lockPath, "wx");
+        try {
+            fs.writeFileSync(handle, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+        }
+        finally {
+            fs.closeSync(handle);
+        }
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EEXIST") {
+            return false;
+        }
+        throw error;
+    }
+}
+function readExistingLock(lockPath) {
+    return normalizeRunLock(JSON.parse(fs.readFileSync(lockPath, "utf8").replace(/^\uFEFF/, "")));
+}
+function normalizeRunLock(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationError("automation run lock must be an object");
+    }
+    const record = value;
+    return {
+        runId: requiredNonEmptyString(record.runId, "automation lock.runId"),
+        owner: optionalNullableString(record.owner) ?? null,
+        acquiredAt: requiredIsoString(record.acquiredAt, "automation lock.acquiredAt"),
+        expiresAt: requiredIsoString(record.expiresAt, "automation lock.expiresAt"),
+    };
+}
+function normalizeRunRecordInput(input, recordedAt) {
+    return normalizeRunRecord({
+        ...input,
+        startedAt: input.startedAt ?? recordedAt,
+        finishedAt: input.finishedAt ?? null,
+        componentId: input.componentId ?? null,
+        workItemId: input.workItemId ?? null,
+        workItemTitle: input.workItemTitle ?? null,
+        sourceRoot: input.sourceRoot ?? null,
+        worktreePath: input.worktreePath ?? null,
+        branchName: input.branchName ?? null,
+        baseRef: input.baseRef ?? null,
+        commitIds: input.commitIds ?? [],
+        summary: input.summary ?? null,
+        verification: input.verification ?? [],
+        publicationDecision: input.publicationDecision ?? null,
+        error: input.error ?? null,
+        nextRunNotBefore: input.nextRunNotBefore ?? null,
+    });
+}
+function normalizeRunRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationError("automation run record must be an object");
+    }
+    const record = value;
+    return {
+        id: requiredNonEmptyString(record.id, "automation run.id"),
+        projectId: requiredNonEmptyString(record.projectId, "automation run.projectId"),
+        componentId: optionalNullableString(record.componentId) ?? null,
+        status: normalizeRunStatus(record.status, "automation run.status"),
+        startedAt: requiredIsoString(record.startedAt, "automation run.startedAt"),
+        finishedAt: optionalIsoString(record.finishedAt, "automation run.finishedAt"),
+        workItemId: optionalNullableString(record.workItemId) ?? null,
+        workItemTitle: optionalNullableString(record.workItemTitle) ?? null,
+        sourceRoot: optionalNullableString(record.sourceRoot) ?? null,
+        worktreePath: optionalNullableString(record.worktreePath) ?? null,
+        branchName: optionalNullableString(record.branchName) ?? null,
+        baseRef: optionalNullableString(record.baseRef) ?? null,
+        commitIds: normalizeStringArray(record.commitIds, "automation run.commitIds"),
+        summary: optionalNullableString(record.summary) ?? null,
+        verification: normalizeVerificationRecords(record.verification),
+        publicationDecision: normalizePublicationDecision(record.publicationDecision),
+        error: optionalNullableString(record.error) ?? null,
+        nextRunNotBefore: optionalIsoString(record.nextRunNotBefore, "automation run.nextRunNotBefore"),
+    };
+}
+function normalizeVerificationRecords(value) {
+    return normalizeWorktreeExecutionMetadata({
+        verification: value,
+    }).verification;
+}
+function normalizeStringArray(value, name) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new NexusAutomationError(`${name} must be an array`);
+    }
+    return value.map((item, index) => requiredNonEmptyString(item, `${name}[${index}]`));
+}
+function normalizePublicationDecision(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return normalizeWorktreeExecutionMetadata({
+        publicationDecision: value,
+    }).publicationDecision;
+}
+function normalizeRunStatus(value, name) {
+    if (value === "started" ||
+        value === "completed" ||
+        value === "failed" ||
+        value === "blocked" ||
+        value === "skipped") {
+        return value;
+    }
+    throw new NexusAutomationError(`${name} must be started, completed, failed, blocked, or skipped`);
+}
+function optionalIsoString(value, name) {
+    const stringValue = optionalNullableString(value);
+    if (stringValue === undefined || stringValue === null) {
+        return null;
+    }
+    return requiredIsoString(stringValue, name);
+}
+function requiredIsoString(value, name) {
+    const stringValue = requiredNonEmptyString(value, name);
+    dateFrom(stringValue, name);
+    return stringValue;
+}
+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 NexusAutomationError(`${name} must be a valid date`);
+    }
+    return date;
+}
+function optionalNullableString(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return requiredNonEmptyString(value, "value");
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/nexusAutomationAgentLaunch.d.ts

@@ -0,0 +1,148 @@
+import { type AcquireNexusAutomationRunLockResult, type NexusAutomationRunLedger, type NexusAutomationRunStatus } from "./nexusAutomation.js";
+import { type NexusAutomationCommandRunner } from "./nexusAutomationCommandExecutor.js";
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+import { type NexusAutomationAgentPolicy } from "./nexusAutomationAgentProfile.js";
+import { type NexusPluginCapabilityProjection } from "./nexusPluginCapabilities.js";
+import { type NexusProjectConfig } from "./nexusProjectConfig.js";
+import { type NexusAutomationTargetContext } from "./nexusAutomationTarget.js";
+import { type ResolvedNexusProjectComponent } from "./nexusProjectLifecycle.js";
+import type { NexusAutomationPreflightCheck, NexusAutomationWorkTrackerProviderFactory } from "./nexusAutomationRunOnce.js";
+import { type CreateWorkTrackerProviderOptions } from "./workTrackingProviderService.js";
+import type { WorkItem, WorkItemQuery, WorkTrackerProvider } from "./workTrackingTypes.js";
+import type { WorktreePublicationDecisionInput, WorktreeVerificationInput, WorktreeVerificationStatus } from "./worktreeExecutionMetadata.js";
+export type NexusAutomationAgentLaunchStatus = "completed" | "failed" | "blocked";
+export interface NexusAutomationAgentLaunchComponentContext {
+    id: string;
+    name: string;
+    role: ResolvedNexusProjectComponent["role"];
+    kind: ResolvedNexusProjectComponent["kind"];
+    sourceRoot: string;
+    sourceRootExists: boolean;
+    worktreesRoot: string;
+    worktreesRootExists: boolean;
+    remoteUrl: string | null;
+    defaultBranch: string | null;
+    workTracker: {
+        provider: string | null;
+        configured: boolean;
+    };
+    relationships: ResolvedNexusProjectComponent["relationships"];
+}
+export interface NexusAutomationComponentEligibleWorkItems {
+    componentId: string;
+    workItems: WorkItem[];
+}
+export interface NexusAutomationAgentLaunchContext {
+    version: 1;
+    runId: string;
+    startedAt: string;
+    projectRoot: string;
+    sourceRoot: string;
+    project: {
+        id: string;
+        name: string;
+        componentCount: number;
+    };
+    components: NexusAutomationAgentLaunchComponentContext[];
+    automation: {
+        mode: "agent_launch";
+        selectorQuery: WorkItemQuery;
+        eligibleWorkItemCount: number;
+    };
+    target: NexusAutomationTargetContext;
+    agent: {
+        coordinatorProfileId: string | null;
+        maxConcurrentSubagents: number;
+        safety: NexusAutomationAgentPolicy["safety"];
+        coordinatorProfile: NexusAutomationAgentPolicy["coordinatorProfile"];
+        profiles: NexusAutomationAgentPolicy["profiles"];
+    };
+    pluginCapabilities: NexusPluginCapabilityProjection[];
+    result: NexusAutomationAgentResultContract;
+    eligibleWorkItems: WorkItem[];
+    componentEligibleWorkItems: NexusAutomationComponentEligibleWorkItems[];
+    safety: NexusAutomationConfig["safety"];
+    publication: NexusAutomationConfig["publication"];
+}
+export interface NexusAutomationAgentResultContract {
+    file: string;
+    requiredFields: string[];
+    optionalFields: string[];
+    statuses: NexusAutomationAgentLaunchStatus[];
+    verificationStatuses: WorktreeVerificationStatus[];
+    publicationDecisionTypes: WorktreePublicationDecisionInput["type"][];
+}
+export interface NexusAutomationAgentLaunchInput {
+    runId: string;
+    startedAt: string;
+    projectRoot: string;
+    sourceRoot: string;
+    components: ResolvedNexusProjectComponent[];
+    projectConfig: NexusProjectConfig;
+    automationConfig: NexusAutomationConfig;
+    selectorQuery: WorkItemQuery;
+    eligibleWorkItems: WorkItem[];
+    componentEligibleWorkItems: NexusAutomationComponentEligibleWorkItems[];
+    contextFile: string;
+    resultFile: string;
+}
+export interface NexusAutomationAgentLaunchResult {
+    status?: NexusAutomationAgentLaunchStatus;
+    summary?: string | null;
+    commitIds?: string[];
+    verification?: WorktreeVerificationInput[];
+    publicationDecision?: WorktreePublicationDecisionInput;
+    error?: string | null;
+}
+export type NexusAutomationAgentLauncher = (input: NexusAutomationAgentLaunchInput) => NexusAutomationAgentLaunchResult | Promise<NexusAutomationAgentLaunchResult>;
+export interface CreateNexusAutomationAgentCommandLauncherOptions {
+    command: string;
+    commandRunner?: NexusAutomationCommandRunner;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+export interface RunNexusAutomationAgentLaunchOnceOptions {
+    projectRoot: string;
+    homePath?: string;
+    runId?: string;
+    owner?: string | null;
+    provider?: WorkTrackerProvider;
+    providerFactory?: NexusAutomationWorkTrackerProviderFactory;
+    providerOptions?: CreateWorkTrackerProviderOptions;
+    now?: () => Date | string;
+    launcher: NexusAutomationAgentLauncher;
+}
+export interface RunNexusAutomationAgentLaunchOnceResult {
+    runId: string;
+    projectRoot: string;
+    sourceRoot: string | null;
+    projectConfig: NexusProjectConfig;
+    automationConfig: NexusAutomationConfig | null;
+    status: NexusAutomationRunStatus;
+    summary: string;
+    ledger: NexusAutomationRunLedger | null;
+    lock: AcquireNexusAutomationRunLockResult | null;
+    preflight: NexusAutomationPreflightCheck[];
+    selectorQuery: WorkItemQuery | null;
+    eligibleWorkItems: WorkItem[];
+    componentEligibleWorkItems: NexusAutomationComponentEligibleWorkItems[];
+    components: ResolvedNexusProjectComponent[];
+    contextFile: string | null;
+    resultFile: string | null;
+    launch: NexusAutomationAgentLaunchResult | null;
+}
+export interface NexusAutomationAgentLaunchComponentProvider {
+    component: ResolvedNexusProjectComponent;
+    provider: WorkTrackerProvider;
+}
+export declare class NexusAutomationAgentLaunchError extends Error {
+    constructor(message: string);
+}
+export declare function runNexusAutomationAgentLaunchOnce(options: RunNexusAutomationAgentLaunchOnceOptions): Promise<RunNexusAutomationAgentLaunchOnceResult>;
+export declare function createNexusAutomationAgentCommandLauncher(options: CreateNexusAutomationAgentCommandLauncherOptions): NexusAutomationAgentLauncher;
+export declare function preflightNexusAutomationAgentLaunch(options: {
+    components: ResolvedNexusProjectComponent[];
+    componentProviders: NexusAutomationAgentLaunchComponentProvider[];
+    automationConfig: NexusAutomationConfig;
+}): NexusAutomationPreflightCheck[];
+export declare function generateNexusAutomationAgentRunId(now?: () => Date | string): string;