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

package/dist/nexusAutomationEnqueue.js

@@ -0,0 +1,128 @@
+import path from "node:path";
+import { selectNexusAutomationWorkItem } from "./nexusAutomation.js";
+import { loadProjectConfig, } from "./nexusProjectConfig.js";
+import { resolvePrimaryProjectComponent, } from "./nexusProjectLifecycle.js";
+import { createWorkTrackerProvider, } from "./workTrackingProviderService.js";
+export class NexusAutomationEnqueueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationEnqueueError";
+    }
+}
+export async function enqueueNexusAutomationWorkItem(options) {
+    const projectRoot = path.resolve(requiredNonEmptyString(options.projectRoot, "projectRoot"));
+    const projectConfig = loadProjectConfig(projectRoot);
+    const automationConfig = projectConfig.automation;
+    if (!automationConfig?.enabled) {
+        throw new NexusAutomationEnqueueError("Project automation is not enabled");
+    }
+    const primaryComponent = resolvePrimaryProjectComponent(projectRoot, projectConfig);
+    if (!primaryComponent.workTracking) {
+        throw new NexusAutomationEnqueueError("Primary component work tracking is not configured");
+    }
+    const sourceRoot = primaryComponent.sourceRoot;
+    const status = resolveEnqueueStatus(automationConfig, options.status);
+    const labels = resolveSelectorStrings("labels", automationConfig.selector.labels, options.labels);
+    const assignees = resolveSelectorStrings("assignees", automationConfig.selector.assignees, options.assignees);
+    assertNoExcludedLabels(labels, automationConfig.selector.excludeLabels);
+    assertSearchMatches(automationConfig, options.title, options.description ?? null);
+    const provider = resolveProvider({
+        options,
+        projectRoot,
+        sourceRoot,
+        projectConfig,
+        component: primaryComponent,
+    });
+    const workItem = await provider.createWorkItem({
+        projectRoot,
+        title: requiredNonEmptyString(options.title, "title"),
+        description: options.description,
+        status,
+        labels,
+        assignees,
+        milestone: options.milestone,
+    });
+    if (!selectNexusAutomationWorkItem([workItem], automationConfig)) {
+        throw new NexusAutomationEnqueueError(`Created work item ${workItem.id} did not match the automation selector`);
+    }
+    return {
+        projectRoot,
+        sourceRoot,
+        projectConfig,
+        automationConfig,
+        workItem,
+    };
+}
+function resolveProvider(options) {
+    const workTracking = options.component.workTracking;
+    if (!workTracking) {
+        throw new NexusAutomationEnqueueError("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 resolveEnqueueStatus(config, requested) {
+    if (requested) {
+        if (!config.selector.statuses.includes(requested)) {
+            throw new NexusAutomationEnqueueError(`--status must match automation selector statuses: ${config.selector.statuses.join(", ")}`);
+        }
+        return requested;
+    }
+    const status = config.selector.statuses[0];
+    if (!status) {
+        throw new NexusAutomationEnqueueError("Automation selector must include at least one status");
+    }
+    return status;
+}
+function resolveSelectorStrings(name, selectorValues, requestedValues) {
+    const values = [...selectorValues, ...(requestedValues ?? [])];
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const normalized = requiredNonEmptyString(value, name);
+        const key = normalized.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(normalized);
+        }
+    }
+    return result;
+}
+function assertNoExcludedLabels(labels, excludedLabels) {
+    const labelSet = new Set(labels.map((label) => label.toLowerCase()));
+    const conflicts = excludedLabels.filter((label) => labelSet.has(label.toLowerCase()));
+    if (conflicts.length > 0) {
+        throw new NexusAutomationEnqueueError(`labels conflict with automation selector exclusions: ${conflicts.join(", ")}`);
+    }
+}
+function assertSearchMatches(config, title, description) {
+    const search = config.selector.search?.trim().toLowerCase();
+    if (!search) {
+        return;
+    }
+    const haystack = [title, description ?? ""].join("\n").toLowerCase();
+    if (!haystack.includes(search)) {
+        throw new NexusAutomationEnqueueError("title or description must match automation selector search");
+    }
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationEnqueueError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/nexusAutomationRunOnce.d.ts

@@ -0,0 +1,91 @@
+import { type GitRunner, type PrepareGitWorktreeResult } from "./gitWorktreeService.js";
+import { type AcquireNexusAutomationRunLockResult, type NexusAutomationRunLedger, type NexusAutomationRunStatus } from "./nexusAutomation.js";
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+import { type NexusAutomationPluginDependencyProjection, type NexusAutomationWorktreeSetupResult } from "./nexusAutomationWorktreeSetup.js";
+import { type NexusProjectConfig } from "./nexusProjectConfig.js";
+import { type ResolvedNexusProjectComponent } from "./nexusProjectLifecycle.js";
+import { type WorktreeExecutionMetadata, type WorktreePublicationDecisionInput, type WorktreeVerificationInput } from "./worktreeExecutionMetadata.js";
+import { type CreateWorkTrackerProviderOptions } from "./workTrackingProviderService.js";
+import type { WorkComment, WorkItem, WorkTrackerProvider, WorkTrackingConfig } from "./workTrackingTypes.js";
+export type NexusAutomationExecutorStatus = "completed" | "failed" | "blocked";
+export interface NexusAutomationExecutorInput {
+    runId: string;
+    startedAt: string;
+    projectRoot: string;
+    sourceRoot: string;
+    projectConfig: NexusProjectConfig;
+    automationConfig: NexusAutomationConfig;
+    workItem: WorkItem;
+    worktree: PrepareGitWorktreeResult;
+    setup: NexusAutomationWorktreeSetupResult;
+}
+export interface NexusAutomationExecutorResult {
+    status?: NexusAutomationExecutorStatus;
+    summary?: string | null;
+    commitIds?: string[];
+    verification?: WorktreeVerificationInput[];
+    publicationDecision?: WorktreePublicationDecisionInput;
+    error?: string | null;
+}
+export type NexusAutomationExecutor = (input: NexusAutomationExecutorInput) => NexusAutomationExecutorResult | Promise<NexusAutomationExecutorResult>;
+export interface NexusAutomationProviderContext {
+    projectRoot: string;
+    sourceRoot: string;
+    projectConfig: NexusProjectConfig;
+    component?: ResolvedNexusProjectComponent;
+    workTracking: WorkTrackingConfig;
+}
+export type NexusAutomationWorkTrackerProviderFactory = (context: NexusAutomationProviderContext) => WorkTrackerProvider;
+export type NexusAutomationPreflightStatus = "passed" | "failed";
+export interface NexusAutomationPreflightCheck {
+    name: string;
+    status: NexusAutomationPreflightStatus;
+    message: string;
+}
+export interface RunNexusAutomationOnceOptions {
+    projectRoot: string;
+    homePath?: string;
+    runId?: string;
+    owner?: string | null;
+    branchName?: string;
+    worktreeName?: string;
+    baseRef?: string | null;
+    provider?: WorkTrackerProvider;
+    providerFactory?: NexusAutomationWorkTrackerProviderFactory;
+    providerOptions?: CreateWorkTrackerProviderOptions;
+    gitRunner?: GitRunner;
+    now?: () => Date | string;
+    executor: NexusAutomationExecutor;
+}
+export interface RunNexusAutomationOnceResult {
+    runId: string;
+    projectRoot: string;
+    sourceRoot: string | null;
+    projectConfig: NexusProjectConfig;
+    automationConfig: NexusAutomationConfig | null;
+    status: NexusAutomationRunStatus;
+    summary: string;
+    ledger: NexusAutomationRunLedger | null;
+    lock: AcquireNexusAutomationRunLockResult | null;
+    preflight: NexusAutomationPreflightCheck[];
+    workItem: WorkItem | null;
+    worktree: PrepareGitWorktreeResult | null;
+    setup: NexusAutomationWorktreeSetupResult | null;
+    execution: WorktreeExecutionMetadata | null;
+    comments: WorkComment[];
+    updatedWorkItem: WorkItem | null;
+}
+export declare class NexusAutomationRunOnceError extends Error {
+    constructor(message: string);
+}
+export declare function runNexusAutomationOnce(options: RunNexusAutomationOnceOptions): Promise<RunNexusAutomationOnceResult>;
+export declare function preflightNexusAutomationRunOnce(options: {
+    projectRoot: string;
+    sourceRoot: string;
+    projectConfig: NexusProjectConfig;
+    component: ResolvedNexusProjectComponent;
+    automationConfig: NexusAutomationConfig;
+    provider: WorkTrackerProvider;
+    pluginDependencyProjections?: NexusAutomationPluginDependencyProjection[];
+}): NexusAutomationPreflightCheck[];
+export declare function generateNexusAutomationRunId(now?: () => Date | string): string;