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

package/dist/nexusAutomationConfig.js

@@ -0,0 +1,547 @@
+export const defaultNexusAutomationConfig = {
+    enabled: true,
+    mode: "run_once",
+    selector: {
+        statuses: ["ready", "todo"],
+        labels: [],
+        excludeLabels: [],
+        assignees: [],
+        search: null,
+        limit: 10,
+    },
+    verification: {
+        focusedCommands: [],
+        fullCommands: [],
+        requirePassing: true,
+    },
+    ledger: {
+        path: ".dev-nexus/automation/runs.json",
+        retention: 200,
+    },
+    lock: {
+        path: ".dev-nexus/automation/run.lock",
+        staleAfterMs: 60 * 60 * 1000,
+    },
+    backoff: {
+        failureLimit: 3,
+        baseDelayMs: 5 * 60 * 1000,
+        maxDelayMs: 60 * 60 * 1000,
+    },
+    schedule: {
+        enabled: true,
+        intervalMs: 15 * 60 * 1000,
+    },
+    setup: {
+        dependencyLinks: [],
+    },
+    executor: {
+        command: null,
+        timeoutMs: null,
+        runFullVerification: false,
+    },
+    agent: {
+        command: null,
+        timeoutMs: null,
+        coordinatorProfileId: null,
+        maxConcurrentSubagents: 1,
+        profiles: [],
+        relaunch: {
+            whileEligible: false,
+        },
+    },
+    target: {
+        id: null,
+        objective: null,
+        statePath: ".dev-nexus/automation/target-state.md",
+        cycleLedgerPath: ".dev-nexus/automation/target-cycles.json",
+        stopWhenNoEligibleWork: true,
+        maxCycles: null,
+        maxWorkItems: null,
+    },
+    safety: {
+        profile: "local",
+        allowHostMutation: false,
+        allowDependencyInstall: false,
+        allowLiveServices: false,
+    },
+    publication: {
+        strategy: "review_handoff",
+        remote: "origin",
+        targetBranch: null,
+        push: false,
+    },
+};
+export class NexusAutomationConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationConfigError";
+    }
+}
+export function validateNexusAutomationConfig(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const record = assertRecord(value, "project config.automation");
+    const enabled = optionalBoolean(record, "enabled", "project config.automation");
+    const mode = validateMode(record.mode, "project config.automation.mode");
+    const selector = validateSelectorConfig(record.selector);
+    const verification = validateVerificationConfig(record.verification);
+    const ledger = validateLedgerConfig(record.ledger);
+    const lock = validateLockConfig(record.lock);
+    const backoff = validateBackoffConfig(record.backoff);
+    const schedule = validateScheduleConfig(record.schedule);
+    const setup = validateSetupConfig(record.setup);
+    const executor = validateExecutorConfig(record.executor);
+    const agent = validateAgentConfig(record.agent);
+    const target = validateTargetConfig(record.target);
+    const safety = validateSafetyConfig(record.safety);
+    const publication = validatePublicationConfig(record.publication);
+    return {
+        enabled: enabled ?? defaultNexusAutomationConfig.enabled,
+        mode: mode ?? defaultNexusAutomationConfig.mode,
+        selector: {
+            ...defaultNexusAutomationConfig.selector,
+            ...selector,
+        },
+        verification: {
+            ...defaultNexusAutomationConfig.verification,
+            ...verification,
+        },
+        ledger: {
+            ...defaultNexusAutomationConfig.ledger,
+            ...ledger,
+        },
+        lock: {
+            ...defaultNexusAutomationConfig.lock,
+            ...lock,
+        },
+        backoff: {
+            ...defaultNexusAutomationConfig.backoff,
+            ...backoff,
+        },
+        schedule: {
+            ...defaultNexusAutomationConfig.schedule,
+            ...schedule,
+        },
+        setup: {
+            ...defaultNexusAutomationConfig.setup,
+            ...setup,
+        },
+        executor: {
+            ...defaultNexusAutomationConfig.executor,
+            ...executor,
+        },
+        agent: {
+            ...defaultNexusAutomationConfig.agent,
+            ...agent,
+            relaunch: {
+                ...defaultNexusAutomationConfig.agent.relaunch,
+                ...agent.relaunch,
+            },
+        },
+        target: {
+            ...defaultNexusAutomationConfig.target,
+            ...target,
+        },
+        safety: {
+            ...defaultNexusAutomationConfig.safety,
+            ...safety,
+        },
+        publication: {
+            ...defaultNexusAutomationConfig.publication,
+            ...publication,
+        },
+    };
+}
+function validateMode(value, pathName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "run_once" || value === "agent_launch") {
+        return value;
+    }
+    throw new NexusAutomationConfigError(`${pathName} must be run_once or agent_launch`);
+}
+function validateSelectorConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.selector";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalArrayField(record, "statuses", pathName, validateWorkStatus),
+        ...optionalArrayField(record, "labels", pathName, requiredNonEmptyString),
+        ...optionalArrayField(record, "excludeLabels", pathName, requiredNonEmptyString),
+        ...optionalArrayField(record, "assignees", pathName, requiredNonEmptyString),
+        ...optionalNullableStringField(record, "search", pathName),
+        ...optionalPositiveIntegerField(record, "limit", pathName),
+    };
+}
+function validateVerificationConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.verification";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalArrayField(record, "focusedCommands", pathName, requiredNonEmptyString),
+        ...optionalArrayField(record, "fullCommands", pathName, requiredNonEmptyString),
+        ...optionalBooleanField(record, "requirePassing", pathName),
+    };
+}
+function validateLedgerConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.ledger";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalStringField(record, "path", pathName),
+        ...optionalPositiveIntegerField(record, "retention", pathName),
+    };
+}
+function validateLockConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.lock";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalStringField(record, "path", pathName),
+        ...optionalPositiveIntegerField(record, "staleAfterMs", pathName),
+    };
+}
+function validateBackoffConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.backoff";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalPositiveIntegerField(record, "failureLimit", pathName),
+        ...optionalPositiveIntegerField(record, "baseDelayMs", pathName),
+        ...optionalPositiveIntegerField(record, "maxDelayMs", pathName),
+    };
+}
+function validateScheduleConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.schedule";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalBooleanField(record, "enabled", pathName),
+        ...optionalPositiveIntegerField(record, "intervalMs", pathName),
+    };
+}
+function validateSetupConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.setup";
+    const record = assertRecord(value, pathName);
+    const dependencyLinks = record.dependencyLinks;
+    if (dependencyLinks === undefined) {
+        return {};
+    }
+    if (!Array.isArray(dependencyLinks)) {
+        throw new NexusAutomationConfigError(`${pathName}.dependencyLinks must be an array`);
+    }
+    return {
+        dependencyLinks: dependencyLinks.map((link, index) => validateDependencyLinkConfig(link, `${pathName}.dependencyLinks[${index}]`)),
+    };
+}
+function validateExecutorConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.executor";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalNullableStringField(record, "command", pathName),
+        ...optionalNullablePositiveIntegerField(record, "timeoutMs", pathName),
+        ...optionalBooleanField(record, "runFullVerification", pathName),
+    };
+}
+function validateAgentConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.agent";
+    const record = assertRecord(value, pathName);
+    const coordinatorProfileId = optionalNullableStringField(record, "coordinatorProfileId", pathName);
+    const profiles = optionalArrayField(record, "profiles", pathName, validateAgentProfileConfig);
+    if (profiles.profiles) {
+        assertUniqueAgentProfileIds(profiles.profiles, `${pathName}.profiles`);
+    }
+    if (coordinatorProfileId.coordinatorProfileId) {
+        const profile = profiles.profiles?.find((item) => item.id === coordinatorProfileId.coordinatorProfileId);
+        if (!profile) {
+            throw new NexusAutomationConfigError(`${pathName}.coordinatorProfileId must reference a configured agent profile`);
+        }
+    }
+    return {
+        ...optionalNullableStringField(record, "command", pathName),
+        ...optionalNullablePositiveIntegerField(record, "timeoutMs", pathName),
+        ...coordinatorProfileId,
+        ...optionalPositiveIntegerField(record, "maxConcurrentSubagents", pathName),
+        ...profiles,
+        ...validateAgentRelaunchConfig(record.relaunch),
+    };
+}
+function validateAgentProfileConfig(value, pathName) {
+    const record = assertRecord(value, pathName);
+    return {
+        id: requiredNonEmptyString(record.id, `${pathName}.id`),
+        executor: requiredNonEmptyString(record.executor, `${pathName}.executor`),
+        model: optionalNullableString(record.model, `${pathName}.model`) ?? null,
+        version: optionalNullableString(record.version, `${pathName}.version`) ?? null,
+        variant: optionalNullableString(record.variant, `${pathName}.variant`) ?? null,
+        reasoning: optionalNullableString(record.reasoning, `${pathName}.reasoning`) ?? null,
+        intelligence: optionalNullableString(record.intelligence, `${pathName}.intelligence`) ??
+            null,
+        intendedUse: validateAgentProfileIntendedUse(record.intendedUse, `${pathName}.intendedUse`),
+        safety: validateAgentProfileSafetyConfig(record.safety, `${pathName}.safety`),
+        command: optionalNullableString(record.command, `${pathName}.command`) ?? null,
+        args: optionalStringArray(record.args, `${pathName}.args`) ?? [],
+    };
+}
+function validateAgentProfileIntendedUse(value, pathName) {
+    if (value === undefined) {
+        return "any";
+    }
+    if (value === "any" || value === "coordinator" || value === "subagent") {
+        return value;
+    }
+    throw new NexusAutomationConfigError(`${pathName} must be any, coordinator, or subagent`);
+}
+function validateAgentProfileSafetyConfig(value, pathName) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return {
+        ...defaultNexusAutomationConfig.safety,
+        ...validateSafetyConfigAt(value, pathName),
+    };
+}
+function assertUniqueAgentProfileIds(profiles, pathName) {
+    const ids = new Set();
+    for (const profile of profiles) {
+        if (ids.has(profile.id)) {
+            throw new NexusAutomationConfigError(`${pathName} contains duplicate id: ${profile.id}`);
+        }
+        ids.add(profile.id);
+    }
+}
+function validateAgentRelaunchConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.agent.relaunch";
+    const record = assertRecord(value, pathName);
+    return {
+        relaunch: {
+            ...defaultNexusAutomationConfig.agent.relaunch,
+            ...optionalBooleanField(record, "whileEligible", pathName),
+        },
+    };
+}
+function validateTargetConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.target";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalNullableStringField(record, "id", pathName),
+        ...optionalNullableStringField(record, "objective", pathName),
+        ...optionalRelativePathField(record, "statePath", pathName),
+        ...optionalRelativePathField(record, "cycleLedgerPath", pathName),
+        ...optionalBooleanField(record, "stopWhenNoEligibleWork", pathName),
+        ...optionalNullablePositiveIntegerField(record, "maxCycles", pathName),
+        ...optionalNullablePositiveIntegerField(record, "maxWorkItems", pathName),
+    };
+}
+function validateDependencyLinkConfig(value, pathName) {
+    const record = assertRecord(value, pathName);
+    return {
+        source: requiredNonEmptyString(record.source, `${pathName}.source`),
+        target: requiredNonEmptyString(record.target, `${pathName}.target`),
+        required: optionalBoolean(record, "required", pathName) ?? false,
+    };
+}
+function validateSafetyConfig(value) {
+    return validateSafetyConfigAt(value, "project config.automation.safety");
+}
+function validateSafetyConfigAt(value, pathName) {
+    if (value === undefined) {
+        return {};
+    }
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalSafetyProfileField(record, "profile", pathName),
+        ...optionalBooleanField(record, "allowHostMutation", pathName),
+        ...optionalBooleanField(record, "allowDependencyInstall", pathName),
+        ...optionalBooleanField(record, "allowLiveServices", pathName),
+    };
+}
+function validatePublicationConfig(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const pathName = "project config.automation.publication";
+    const record = assertRecord(value, pathName);
+    return {
+        ...optionalPublicationStrategyField(record, "strategy", pathName),
+        ...optionalNullableStringField(record, "remote", pathName),
+        ...optionalNullableStringField(record, "targetBranch", pathName),
+        ...optionalBooleanField(record, "push", pathName),
+    };
+}
+function assertRecord(value, pathName) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationConfigError(`${pathName} must be an object`);
+    }
+    return value;
+}
+function optionalBoolean(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
+        throw new NexusAutomationConfigError(`${pathName}.${key} must be a boolean`);
+    }
+    return value;
+}
+function optionalBooleanField(record, key, pathName, outputKey = key) {
+    const value = optionalBoolean(record, key, pathName);
+    return value === undefined ? {} : { [outputKey]: value };
+}
+function optionalStringField(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    return {
+        [key]: requiredNonEmptyString(value, `${pathName}.${key}`),
+    };
+}
+function optionalNullableString(value, pathName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return requiredNonEmptyString(value, pathName);
+}
+function optionalNullableStringField(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    if (value === null) {
+        return { [key]: null };
+    }
+    return {
+        [key]: requiredNonEmptyString(value, `${pathName}.${key}`),
+    };
+}
+function optionalRelativePathField(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    const normalized = requiredNonEmptyString(value, `${pathName}.${key}`);
+    if (normalized.split(/[\\/]/u).some((part) => part === "..") ||
+        /^[A-Za-z]:/u.test(normalized) ||
+        normalized.startsWith("/") ||
+        normalized.startsWith("\\")) {
+        throw new NexusAutomationConfigError(`${pathName}.${key} must be a project-relative path`);
+    }
+    return { [key]: normalized };
+}
+function optionalPositiveIntegerField(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new NexusAutomationConfigError(`${pathName}.${key} must be a positive integer`);
+    }
+    return { [key]: value };
+}
+function optionalNullablePositiveIntegerField(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    if (value === null) {
+        return { [key]: null };
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new NexusAutomationConfigError(`${pathName}.${key} must be a positive integer or null`);
+    }
+    return { [key]: value };
+}
+function optionalArrayField(record, key, pathName, normalizeItem) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    if (!Array.isArray(value)) {
+        throw new NexusAutomationConfigError(`${pathName}.${key} must be an array`);
+    }
+    return {
+        [key]: value.map((item, index) => normalizeItem(item, `${pathName}.${key}[${index}]`)),
+    };
+}
+function optionalStringArray(value, pathName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new NexusAutomationConfigError(`${pathName} must be an array`);
+    }
+    return value.map((item, index) => requiredNonEmptyString(item, `${pathName}[${index}]`));
+}
+function optionalSafetyProfileField(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    if (value === "local" || value === "isolated" || value === "host-authorized") {
+        return { [key]: value };
+    }
+    throw new NexusAutomationConfigError(`${pathName}.${key} must be local, isolated, or host-authorized`);
+}
+function optionalPublicationStrategyField(record, key, pathName) {
+    const value = record[key];
+    if (value === undefined) {
+        return {};
+    }
+    if (value === "local_only" ||
+        value === "direct_integration" ||
+        value === "review_handoff") {
+        return { [key]: value };
+    }
+    throw new NexusAutomationConfigError(`${pathName}.${key} must be local_only, direct_integration, or review_handoff`);
+}
+function validateWorkStatus(value, pathName) {
+    if (value === "todo" ||
+        value === "ready" ||
+        value === "in_progress" ||
+        value === "blocked" ||
+        value === "done" ||
+        value === "wont_do") {
+        return value;
+    }
+    throw new NexusAutomationConfigError(`${pathName} must be todo, ready, in_progress, blocked, done, or wont_do`);
+}
+function requiredNonEmptyString(value, pathName) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationConfigError(`${pathName} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/nexusAutomationEnqueue.d.ts

@@ -0,0 +1,37 @@
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+import { type NexusProjectConfig } from "./nexusProjectConfig.js";
+import { type ResolvedNexusProjectComponent } from "./nexusProjectLifecycle.js";
+import { type CreateWorkTrackerProviderOptions } from "./workTrackingProviderService.js";
+import type { WorkItem, WorkStatus, WorkTrackerProvider } from "./workTrackingTypes.js";
+export interface EnqueueNexusAutomationWorkItemProviderContext {
+    projectRoot: string;
+    sourceRoot: string;
+    projectConfig: NexusProjectConfig;
+    component: ResolvedNexusProjectComponent;
+    workTracking: NonNullable<ResolvedNexusProjectComponent["workTracking"]>;
+}
+export type EnqueueNexusAutomationWorkItemProviderFactory = (context: EnqueueNexusAutomationWorkItemProviderContext) => WorkTrackerProvider;
+export interface EnqueueNexusAutomationWorkItemOptions {
+    projectRoot: string;
+    title: string;
+    description?: string | null;
+    status?: WorkStatus;
+    labels?: string[];
+    assignees?: string[];
+    milestone?: string | null;
+    provider?: WorkTrackerProvider;
+    providerFactory?: EnqueueNexusAutomationWorkItemProviderFactory;
+    providerOptions?: Omit<CreateWorkTrackerProviderOptions, "projectRoot" | "now">;
+    now?: () => Date | string;
+}
+export interface EnqueueNexusAutomationWorkItemResult {
+    projectRoot: string;
+    sourceRoot: string;
+    projectConfig: NexusProjectConfig;
+    automationConfig: NexusAutomationConfig;
+    workItem: WorkItem;
+}
+export declare class NexusAutomationEnqueueError extends Error {
+    constructor(message: string);
+}
+export declare function enqueueNexusAutomationWorkItem(options: EnqueueNexusAutomationWorkItemOptions): Promise<EnqueueNexusAutomationWorkItemResult>;