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

package/dist/nexusAutomationTargetCycle.js

@@ -0,0 +1,282 @@
+import fs from "node:fs";
+import path from "node:path";
+export const maxNexusAutomationTargetCycleNoteLength = 1000;
+export class NexusAutomationTargetCycleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationTargetCycleError";
+    }
+}
+export function nexusAutomationTargetCycleLedgerPath(projectRoot, config) {
+    return resolveProjectRelativePath(projectRoot, config.target.cycleLedgerPath, "automation.target.cycleLedgerPath");
+}
+export function emptyNexusAutomationTargetCycleLedger() {
+    return {
+        version: 1,
+        cycles: [],
+        updatedAt: null,
+    };
+}
+export function readNexusAutomationTargetCycleLedger(projectRoot, config) {
+    const ledgerPath = nexusAutomationTargetCycleLedgerPath(projectRoot, config);
+    if (!fs.existsSync(ledgerPath)) {
+        return emptyNexusAutomationTargetCycleLedger();
+    }
+    return normalizeNexusAutomationTargetCycleLedger(JSON.parse(fs.readFileSync(ledgerPath, "utf8").replace(/^\uFEFF/, "")));
+}
+export function writeNexusAutomationTargetCycleLedger(projectRoot, config, ledger) {
+    const ledgerPath = nexusAutomationTargetCycleLedgerPath(projectRoot, config);
+    const normalized = normalizeNexusAutomationTargetCycleLedger(ledger);
+    fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+    fs.writeFileSync(ledgerPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+    return ledgerPath;
+}
+export function appendNexusAutomationTargetCycleRecord(options) {
+    const recordedAt = isoString(options.now ?? new Date());
+    const record = normalizeTargetCycleRecordInput(options.record, recordedAt);
+    const existing = readNexusAutomationTargetCycleLedger(options.projectRoot, options.config);
+    const cycles = [...existing.cycles, record].slice(-options.config.ledger.retention);
+    const ledger = {
+        version: 1,
+        cycles,
+        updatedAt: recordedAt,
+    };
+    writeNexusAutomationTargetCycleLedger(options.projectRoot, options.config, ledger);
+    return ledger;
+}
+export function summarizeNexusAutomationTargetCycles(options) {
+    const ledgerPath = nexusAutomationTargetCycleLedgerPath(options.projectRoot, options.config);
+    const ledger = readNexusAutomationTargetCycleLedger(options.projectRoot, options.config);
+    return {
+        ledgerPath,
+        cycleCount: ledger.cycles.length,
+        activeCycleCount: ledger.cycles.filter(isActiveCycle).length,
+        completedCycleCount: ledger.cycles.filter((cycle) => cycle.status === "completed").length,
+        blockedCycleCount: ledger.cycles.filter((cycle) => cycle.status === "blocked").length,
+        failedCycleCount: ledger.cycles.filter((cycle) => cycle.status === "failed")
+            .length,
+        skippedCycleCount: ledger.cycles.filter((cycle) => cycle.status === "skipped").length,
+        lastCycle: ledger.cycles.at(-1) ?? null,
+    };
+}
+export function normalizeNexusAutomationTargetCycleLedger(value) {
+    if (value === undefined || value === null) {
+        return emptyNexusAutomationTargetCycleLedger();
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationTargetCycleError("target cycle ledger must be an object");
+    }
+    const record = value;
+    if (record.version !== 1) {
+        throw new NexusAutomationTargetCycleError("target cycle ledger.version must be 1");
+    }
+    if (!Array.isArray(record.cycles)) {
+        throw new NexusAutomationTargetCycleError("target cycle ledger.cycles must be an array");
+    }
+    return {
+        version: 1,
+        cycles: record.cycles.map(normalizeTargetCycleRecord),
+        updatedAt: optionalIsoString(record.updatedAt, "target cycle ledger.updatedAt"),
+    };
+}
+export function generateNexusAutomationTargetCycleId(now = new Date()) {
+    const timestamp = isoString(now)
+        .replaceAll("-", "")
+        .replaceAll(":", "")
+        .replace(".", "-");
+    const suffix = Math.random().toString(36).slice(2, 8);
+    return `target-cycle-${timestamp}-${suffix}`;
+}
+function normalizeTargetCycleRecordInput(input, recordedAt) {
+    const status = normalizeCycleStatus(input.status, "target cycle.status");
+    return normalizeTargetCycleRecord({
+        ...input,
+        id: input.id ?? generateNexusAutomationTargetCycleId(recordedAt),
+        targetId: input.targetId ?? null,
+        runId: input.runId ?? null,
+        startedAt: input.startedAt ?? recordedAt,
+        finishedAt: input.finishedAt === undefined
+            ? defaultFinishedAt(status, recordedAt)
+            : input.finishedAt,
+        objective: input.objective ?? null,
+        summary: input.summary ?? null,
+        eligibleWorkItemCount: input.eligibleWorkItemCount ?? null,
+        workItems: input.workItems ?? [],
+        blockers: input.blockers ?? [],
+        notes: input.notes ?? [],
+        nextCycleNotBefore: input.nextCycleNotBefore ?? null,
+    });
+}
+function normalizeTargetCycleRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationTargetCycleError("target cycle record must be an object");
+    }
+    const record = value;
+    return {
+        id: requiredNonEmptyString(record.id, "target cycle.id"),
+        projectId: requiredNonEmptyString(record.projectId, "target cycle.projectId"),
+        targetId: optionalNullableString(record.targetId) ?? null,
+        runId: optionalNullableString(record.runId) ?? null,
+        status: normalizeCycleStatus(record.status, "target cycle.status"),
+        startedAt: requiredIsoString(record.startedAt, "target cycle.startedAt"),
+        finishedAt: optionalIsoString(record.finishedAt, "target cycle.finishedAt"),
+        objective: optionalNullableString(record.objective) ?? null,
+        summary: optionalNullableString(record.summary) ?? null,
+        eligibleWorkItemCount: optionalNullableNonNegativeInteger(record.eligibleWorkItemCount, "target cycle.eligibleWorkItemCount"),
+        workItems: normalizeWorkItems(record.workItems),
+        blockers: normalizeStringArray(record.blockers, "target cycle.blockers"),
+        notes: normalizeStringArray(record.notes, "target cycle.notes", maxNexusAutomationTargetCycleNoteLength),
+        nextCycleNotBefore: optionalIsoString(record.nextCycleNotBefore, "target cycle.nextCycleNotBefore"),
+    };
+}
+function normalizeWorkItems(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new NexusAutomationTargetCycleError("target cycle.workItems must be an array");
+    }
+    return value.map((item, index) => normalizeWorkItem(item, index));
+}
+function normalizeWorkItem(value, index) {
+    const pathName = `target cycle.workItems[${index}]`;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationTargetCycleError(`${pathName} must be an object`);
+    }
+    const record = value;
+    return {
+        componentId: optionalNullableString(record.componentId) ?? null,
+        id: requiredNonEmptyString(record.id, `${pathName}.id`),
+        title: optionalNullableString(record.title) ?? null,
+        status: optionalWorkStatus(record.status, `${pathName}.status`),
+        cycleStatus: optionalCycleWorkItemStatus(record.cycleStatus, `${pathName}.cycleStatus`),
+        agentProfileId: optionalNullableString(record.agentProfileId) ?? null,
+        notes: boundedOptionalNullableString(record.notes, `${pathName}.notes`, maxNexusAutomationTargetCycleNoteLength) ?? null,
+    };
+}
+function isActiveCycle(cycle) {
+    return cycle.status === "started" || cycle.status === "dispatched";
+}
+function defaultFinishedAt(status, recordedAt) {
+    return status === "started" || status === "dispatched" ? null : recordedAt;
+}
+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 NexusAutomationTargetCycleError(`${fieldName} must resolve inside the project root: ${target}`);
+    }
+    return target;
+}
+function normalizeCycleStatus(value, name) {
+    if (value === "started" ||
+        value === "dispatched" ||
+        value === "completed" ||
+        value === "blocked" ||
+        value === "failed" ||
+        value === "skipped") {
+        return value;
+    }
+    throw new NexusAutomationTargetCycleError(`${name} must be started, dispatched, completed, blocked, failed, or skipped`);
+}
+function optionalCycleWorkItemStatus(value, name) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (value === "eligible" ||
+        value === "selected" ||
+        value === "dispatched" ||
+        value === "in_progress" ||
+        value === "completed" ||
+        value === "blocked" ||
+        value === "skipped") {
+        return value;
+    }
+    throw new NexusAutomationTargetCycleError(`${name} must be eligible, selected, dispatched, in_progress, completed, blocked, or skipped`);
+}
+function optionalWorkStatus(value, name) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (value === "todo" ||
+        value === "ready" ||
+        value === "in_progress" ||
+        value === "blocked" ||
+        value === "done" ||
+        value === "wont_do") {
+        return value;
+    }
+    throw new NexusAutomationTargetCycleError(`${name} must be todo, ready, in_progress, blocked, done, or wont_do`);
+}
+function normalizeStringArray(value, name, maxLength) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new NexusAutomationTargetCycleError(`${name} must be an array`);
+    }
+    return value.map((item, index) => {
+        const stringValue = requiredNonEmptyString(item, `${name}[${index}]`);
+        if (maxLength !== undefined && stringValue.length > maxLength) {
+            throw new NexusAutomationTargetCycleError(`${name}[${index}] must be at most ${maxLength} characters`);
+        }
+        return stringValue;
+    });
+}
+function optionalNullableNonNegativeInteger(value, name) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new NexusAutomationTargetCycleError(`${name} must be a non-negative integer or null`);
+    }
+    return value;
+}
+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 NexusAutomationTargetCycleError(`${name} must be a valid date`);
+    }
+    return date;
+}
+function boundedOptionalNullableString(value, name, maxLength) {
+    const stringValue = optionalNullableString(value, name);
+    if (stringValue === undefined || stringValue === null) {
+        return stringValue;
+    }
+    if (stringValue.length > maxLength) {
+        throw new NexusAutomationTargetCycleError(`${name} must be at most ${maxLength} characters`);
+    }
+    return stringValue;
+}
+function optionalNullableString(value, name = "value") {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return requiredNonEmptyString(value, name);
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationTargetCycleError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/nexusAutomationTargetReport.d.ts

@@ -0,0 +1,136 @@
+import { type NexusAutomationRunRecord, type NexusAutomationRunStatus } from "./nexusAutomation.js";
+import { type ResolvedNexusProjectComponent } from "./nexusProjectLifecycle.js";
+import { type NexusAutomationTargetContext } from "./nexusAutomationTarget.js";
+import { type NexusAutomationTargetCycleSummary, type NexusAutomationTargetCycleWorkItemStatus } from "./nexusAutomationTargetCycle.js";
+import type { WorkStatus } from "./workTrackingTypes.js";
+import type { WorktreePublicationDecision, WorktreeVerificationRecord } from "./worktreeExecutionMetadata.js";
+export type NexusAutomationTargetReportStatus = "not_started" | "active" | "completed" | "blocked" | "failed" | "skipped";
+export type NexusAutomationTargetReportRelaunchDecisionType = "relaunch" | "stop" | "wait" | "report_blocked" | "report_failed" | "not_ready";
+export interface BuildNexusAutomationTargetReportOptions {
+    projectRoot: string;
+    now?: Date | string;
+}
+export interface NexusAutomationTargetReportRunSummary {
+    runCount: number;
+    completedRunCount: number;
+    blockedRunCount: number;
+    failedRunCount: number;
+    skippedRunCount: number;
+    lastRun: NexusAutomationRunRecord | null;
+}
+export interface NexusAutomationTargetReportWorkItemSummary {
+    totalReferences: number;
+    uniqueReferences: NexusAutomationTargetReportWorkItemReference[];
+    byComponent: NexusAutomationTargetReportComponentWorkItemSummary[];
+    byCycleStatus: Record<NexusAutomationTargetCycleWorkItemStatus, number>;
+    progress: NexusAutomationTargetReportWorkItemProgressSummary;
+}
+export interface NexusAutomationTargetReportWorkItemReference {
+    componentId: string | null;
+    id: string;
+    title: string | null;
+    status: WorkStatus | null;
+    latestCycleStatus: NexusAutomationTargetCycleWorkItemStatus | null;
+    latestCycleId: string;
+    agentProfileId: string | null;
+    notes: string | null;
+}
+export interface NexusAutomationTargetReportComponentWorkItemSummary {
+    componentId: string | null;
+    totalReferences: number;
+    uniqueWorkItemCount: number;
+}
+export interface NexusAutomationTargetReportWorkItemProgressSummary {
+    readyEligibleWork: NexusAutomationTargetReportWorkItemReference[];
+    selectedWork: NexusAutomationTargetReportWorkItemReference[];
+    blockedHitlWork: NexusAutomationTargetReportWorkItemReference[];
+    completedWork: NexusAutomationTargetReportWorkItemReference[];
+    skippedWork: NexusAutomationTargetReportWorkItemReference[];
+}
+export type NexusAutomationTargetReportActiveBlockerSource = "cycle" | "work_item" | "run";
+export interface NexusAutomationTargetReportActiveBlocker {
+    source: NexusAutomationTargetReportActiveBlockerSource;
+    componentId: string | null;
+    cycleId: string | null;
+    runId: string | null;
+    workItemId: string | null;
+    workItemTitle: string | null;
+    message: string | null;
+}
+export interface NexusAutomationTargetReportExecutionRunSummary {
+    runId: string;
+    componentId: string | null;
+    status: NexusAutomationRunStatus;
+    workItemId: string | null;
+    workItemTitle: string | null;
+    workItemStatus: WorkStatus | null;
+    commitIds: string[];
+    summary: string | null;
+    error: string | null;
+}
+export interface NexusAutomationTargetReportVerificationSummary extends WorktreeVerificationRecord {
+    runId: string;
+    componentId: string | null;
+    workItemId: string | null;
+    workItemTitle: string | null;
+}
+export interface NexusAutomationTargetReportPublicationDecisionSummary extends WorktreePublicationDecision {
+    runId: string;
+    componentId: string | null;
+    workItemId: string | null;
+    workItemTitle: string | null;
+}
+export interface NexusAutomationTargetReportExecutionSummary {
+    runCount: number;
+    commitIds: string[];
+    verification: NexusAutomationTargetReportVerificationSummary[];
+    publicationDecisions: NexusAutomationTargetReportPublicationDecisionSummary[];
+    runs: NexusAutomationTargetReportExecutionRunSummary[];
+}
+export interface NexusAutomationTargetReportComponentProgressSummary {
+    componentId: string | null;
+    componentName: string | null;
+    role: ResolvedNexusProjectComponent["role"] | null;
+    sourceRoot: string | null;
+    workTrackingProvider: string | null;
+    workItemCount: number;
+    workItems: NexusAutomationTargetReportWorkItemProgressSummary;
+    activeBlockers: NexusAutomationTargetReportActiveBlocker[];
+    commitIds: string[];
+    verification: NexusAutomationTargetReportVerificationSummary[];
+    publicationDecisions: NexusAutomationTargetReportPublicationDecisionSummary[];
+    runs: NexusAutomationTargetReportExecutionRunSummary[];
+}
+export interface NexusAutomationTargetReportRelaunchDecision {
+    type: NexusAutomationTargetReportRelaunchDecisionType;
+    reason: string;
+    eligibleWorkItemCount: number | null;
+    latestCycleId: string | null;
+    latestRunId: string | null;
+}
+export interface NexusAutomationTargetReport {
+    version: 1;
+    generatedAt: string;
+    projectRoot: string;
+    project: {
+        id: string;
+        name: string;
+        componentCount: number;
+    };
+    target: NexusAutomationTargetContext | null;
+    status: NexusAutomationTargetReportStatus;
+    statusReason: string;
+    cycleSummary: NexusAutomationTargetCycleSummary | null;
+    runSummary: NexusAutomationTargetReportRunSummary | null;
+    workItemSummary: NexusAutomationTargetReportWorkItemSummary | null;
+    executionSummary: NexusAutomationTargetReportExecutionSummary | null;
+    componentProgress: NexusAutomationTargetReportComponentProgressSummary[];
+    relaunchDecision: NexusAutomationTargetReportRelaunchDecision;
+    activeBlockers: NexusAutomationTargetReportActiveBlocker[];
+    blockers: string[];
+    notes: string[];
+}
+export declare class NexusAutomationTargetReportError extends Error {
+    constructor(message: string);
+}
+export declare function buildNexusAutomationTargetReport(options: BuildNexusAutomationTargetReportOptions): NexusAutomationTargetReport;