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

package/dist/gitWorktreeService.d.ts

@@ -0,0 +1,57 @@
+export interface GitCommandResult {
+    args: string[];
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}
+export type GitRunner = (args: readonly string[], cwd?: string) => GitCommandResult;
+export interface PrepareGitWorktreeOptions {
+    componentId: string;
+    sourceRoot: string;
+    worktreesRoot: string;
+    branchName: string;
+    worktreeName?: string;
+    baseRef?: string | null;
+    workItemId?: string | null;
+    workItemTitle?: string | null;
+    gitRunner?: GitRunner;
+}
+export interface PreparedGitWorktreeWorkItem {
+    id: string;
+    title: string | null;
+}
+export interface PrepareGitWorktreeResult {
+    componentId: string;
+    sourceRoot: string;
+    worktreesRoot: string;
+    worktreePath: string;
+    branchName: string;
+    baseRef: string | null;
+    workItem: PreparedGitWorktreeWorkItem | null;
+    git: {
+        commands: GitCommandResult[];
+    };
+}
+export interface RemoveGitWorktreeOptions {
+    sourceRoot: string;
+    worktreePath: string;
+    gitRunner?: GitRunner;
+}
+export interface RemoveGitWorktreeResult {
+    sourceRoot: string;
+    worktreePath: string;
+    git: {
+        commands: GitCommandResult[];
+    };
+}
+export declare class GitWorktreeServiceError extends Error {
+    constructor(message: string);
+}
+export declare function prepareGitWorktree(options: PrepareGitWorktreeOptions): PrepareGitWorktreeResult;
+export declare function removeGitWorktree(options: RemoveGitWorktreeOptions): RemoveGitWorktreeResult;
+export declare function normalizeBranchName(value: string): string;
+export declare function safeDirectoryName(value: string): string;
+export declare function normalizeWorktreeName(value: string): string;
+export declare function assertSafeWorktreePath(worktreesRoot: string, worktreePath: string): void;
+export declare function defaultGitRunner(args: readonly string[], cwd?: string): GitCommandResult;
+export declare function runGitCommand(gitRunner: GitRunner, commands: GitCommandResult[], args: readonly string[], cwd?: string): GitCommandResult;

package/dist/gitWorktreeService.js

@@ -0,0 +1,157 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+export class GitWorktreeServiceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitWorktreeServiceError";
+    }
+}
+export function prepareGitWorktree(options) {
+    const componentId = requiredNonEmptyString(options.componentId, "componentId");
+    const sourceRoot = path.resolve(options.sourceRoot);
+    const worktreesRoot = path.resolve(options.worktreesRoot);
+    const branchName = normalizeBranchName(options.branchName);
+    const baseRef = optionalNullableString(options.baseRef, "baseRef");
+    const worktreeName = options.worktreeName
+        ? normalizeWorktreeName(options.worktreeName)
+        : safeDirectoryName(branchName);
+    const workItem = normalizePreparedWorktreeWorkItem(options.workItemId, options.workItemTitle);
+    const worktreePath = path.join(worktreesRoot, worktreeName);
+    assertSafeWorktreePath(worktreesRoot, worktreePath);
+    if (fs.existsSync(worktreePath)) {
+        throw new GitWorktreeServiceError(`Worktree path already exists: ${worktreePath}`);
+    }
+    const gitRunner = options.gitRunner ?? defaultGitRunner;
+    const commands = [];
+    fs.mkdirSync(worktreesRoot, { recursive: true });
+    runGitCommand(gitRunner, commands, [
+        "worktree",
+        "add",
+        "-b",
+        branchName,
+        worktreePath,
+        ...(baseRef ? [baseRef] : []),
+    ], sourceRoot);
+    return {
+        componentId,
+        sourceRoot,
+        worktreesRoot,
+        worktreePath,
+        branchName,
+        baseRef,
+        workItem,
+        git: {
+            commands,
+        },
+    };
+}
+export function removeGitWorktree(options) {
+    const sourceRoot = path.resolve(options.sourceRoot);
+    const worktreePath = path.resolve(options.worktreePath);
+    const gitRunner = options.gitRunner ?? defaultGitRunner;
+    const commands = [];
+    runGitCommand(gitRunner, commands, ["worktree", "remove", worktreePath], sourceRoot);
+    return {
+        sourceRoot,
+        worktreePath,
+        git: {
+            commands,
+        },
+    };
+}
+export function normalizeBranchName(value) {
+    const trimmed = value.trim().replaceAll("\\", "/");
+    if (trimmed.length === 0) {
+        throw new GitWorktreeServiceError("branchName must be non-empty");
+    }
+    if (trimmed.startsWith("/") ||
+        trimmed.endsWith("/") ||
+        trimmed.includes("..") ||
+        trimmed.includes("//") ||
+        /[\u0000-\u001F ~^:?*[\\]/u.test(trimmed)) {
+        throw new GitWorktreeServiceError(`Invalid branchName: ${value}`);
+    }
+    return trimmed;
+}
+export function safeDirectoryName(value) {
+    const sanitized = value
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+    if (!sanitized) {
+        throw new GitWorktreeServiceError("Worktree name must contain at least one filesystem-safe character");
+    }
+    if (sanitized === "." || sanitized === ".." || sanitized.includes("..")) {
+        throw new GitWorktreeServiceError(`Invalid worktreeName: ${value}`);
+    }
+    return sanitized;
+}
+export function normalizeWorktreeName(value) {
+    const trimmed = requiredNonEmptyString(value, "worktreeName");
+    if (path.isAbsolute(trimmed) ||
+        trimmed === "." ||
+        trimmed === ".." ||
+        trimmed.includes("..") ||
+        /[\\/]/u.test(trimmed) ||
+        !/^[A-Za-z0-9._-]+$/u.test(trimmed)) {
+        throw new GitWorktreeServiceError(`Invalid worktreeName: ${value}`);
+    }
+    return trimmed;
+}
+export function assertSafeWorktreePath(worktreesRoot, worktreePath) {
+    const resolvedRoot = path.resolve(worktreesRoot);
+    const resolvedTarget = path.resolve(worktreePath);
+    const relative = path.relative(resolvedRoot, resolvedTarget);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new GitWorktreeServiceError(`Worktree path must be inside worktrees root: ${resolvedTarget}`);
+    }
+}
+export function defaultGitRunner(args, cwd) {
+    const result = spawnSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+        shell: false,
+        windowsHide: true,
+    });
+    if (result.error) {
+        throw new GitWorktreeServiceError(`Failed to run git ${args.join(" ")}: ${result.error.message}`);
+    }
+    return {
+        args: [...args],
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        exitCode: result.status,
+    };
+}
+export function runGitCommand(gitRunner, commands, args, cwd) {
+    const result = gitRunner(args, cwd);
+    commands.push(result);
+    if (result.exitCode !== 0) {
+        throw new GitWorktreeServiceError(`git ${args.join(" ")} failed with exit code ${result.exitCode}: ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+    return result;
+}
+function normalizePreparedWorktreeWorkItem(workItemId, workItemTitle) {
+    if (workItemId === undefined || workItemId === null) {
+        return null;
+    }
+    return {
+        id: requiredNonEmptyString(workItemId, "workItemId"),
+        title: optionalNullableString(workItemTitle, "workItemTitle"),
+    };
+}
+function optionalNullableString(value, name) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return requiredNonEmptyString(value, name);
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new GitWorktreeServiceError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+export * from "./browserOpener.js";
+export * from "./gitWorktreeService.js";
+export * from "./nexusAutomation.js";
+export * from "./nexusAutomationAgentLaunch.js";
+export * from "./nexusAutomationAgentProfile.js";
+export * from "./nexusAutomationAgentSurface.js";
+export * from "./nexusAutomationCommandExecutor.js";
+export * from "./nexusAutomationConfig.js";
+export * from "./nexusAutomationEnqueue.js";
+export * from "./nexusAutomationRunOnce.js";
+export * from "./nexusAutomationScheduler.js";
+export * from "./nexusAutomationStatus.js";
+export * from "./nexusAutomationTarget.js";
+export * from "./nexusAutomationTargetCycle.js";
+export * from "./nexusAutomationTargetReport.js";
+export * from "./nexusCoordination.js";
+export * from "./nexusWorkerContextBundle.js";
+export * from "./nexusAgentMcpConfig.js";
+export * from "./nexusAutomationWorktreeSetup.js";
+export * from "./nexusMcpServer.js";
+export * from "./nexusPluginCapabilities.js";
+export * from "./nexusProjectScaffold.js";
+export * from "./nexusProjectTemplate.js";
+export * from "./processSupervisor.js";
+export * from "./workTrackingGitHubProvider.js";
+export * from "./workTrackingGitLabProvider.js";
+export * from "./workTrackingJiraProvider.js";
+export * from "./workItemService.js";
+export * from "./worktreeExecutionMetadata.js";
+export * from "./nexusExtension.js";
+export * from "./nexusHomeConfig.js";
+export * from "./nexusProjectConfig.js";
+export * from "./nexusProjectHomeService.js";
+export * from "./nexusProjectLifecycle.js";
+export * from "./nexusProjectOperations.js";
+export * from "./nexusProjectRegistry.js";
+export * from "./nexusSkills.js";
+export * from "./workTrackingLocalProvider.js";
+export * from "./workTrackingProviderService.js";
+export * from "./workTrackingTypes.js";
+export * from "./vibeKanbanApi.js";
+export * from "./vibeKanbanAuth.js";
+export * from "./vibeKanbanBoardAdapter.js";
+export * from "./vibeKanbanMcpConfig.js";
+export * from "./vibeKanbanProjectAdapter.js";
+export * from "./vibeKanbanWorkspaceSetup.js";
+export * from "./workTrackingVibeProvider.js";

package/dist/index.js

@@ -0,0 +1,47 @@
+export * from "./browserOpener.js";
+export * from "./gitWorktreeService.js";
+export * from "./nexusAutomation.js";
+export * from "./nexusAutomationAgentLaunch.js";
+export * from "./nexusAutomationAgentProfile.js";
+export * from "./nexusAutomationAgentSurface.js";
+export * from "./nexusAutomationCommandExecutor.js";
+export * from "./nexusAutomationConfig.js";
+export * from "./nexusAutomationEnqueue.js";
+export * from "./nexusAutomationRunOnce.js";
+export * from "./nexusAutomationScheduler.js";
+export * from "./nexusAutomationStatus.js";
+export * from "./nexusAutomationTarget.js";
+export * from "./nexusAutomationTargetCycle.js";
+export * from "./nexusAutomationTargetReport.js";
+export * from "./nexusCoordination.js";
+export * from "./nexusWorkerContextBundle.js";
+export * from "./nexusAgentMcpConfig.js";
+export * from "./nexusAutomationWorktreeSetup.js";
+export * from "./nexusMcpServer.js";
+export * from "./nexusPluginCapabilities.js";
+export * from "./nexusProjectScaffold.js";
+export * from "./nexusProjectTemplate.js";
+export * from "./processSupervisor.js";
+export * from "./workTrackingGitHubProvider.js";
+export * from "./workTrackingGitLabProvider.js";
+export * from "./workTrackingJiraProvider.js";
+export * from "./workItemService.js";
+export * from "./worktreeExecutionMetadata.js";
+export * from "./nexusExtension.js";
+export * from "./nexusHomeConfig.js";
+export * from "./nexusProjectConfig.js";
+export * from "./nexusProjectHomeService.js";
+export * from "./nexusProjectLifecycle.js";
+export * from "./nexusProjectOperations.js";
+export * from "./nexusProjectRegistry.js";
+export * from "./nexusSkills.js";
+export * from "./workTrackingLocalProvider.js";
+export * from "./workTrackingProviderService.js";
+export * from "./workTrackingTypes.js";
+export * from "./vibeKanbanApi.js";
+export * from "./vibeKanbanAuth.js";
+export * from "./vibeKanbanBoardAdapter.js";
+export * from "./vibeKanbanMcpConfig.js";
+export * from "./vibeKanbanProjectAdapter.js";
+export * from "./vibeKanbanWorkspaceSetup.js";
+export * from "./workTrackingVibeProvider.js";

package/dist/nexusAgentMcpConfig.d.ts

@@ -0,0 +1,30 @@
+import type { NexusProjectAgentMcpTarget, NexusProjectMcpConfig } from "./nexusProjectConfig.js";
+import type { NexusSkillSourceControl } from "./nexusSkills.js";
+export declare const defaultNexusMcpServerName = "dev_nexus";
+export declare const defaultNexusMcpCommand = "dev-nexus";
+export declare const defaultNexusMcpArgs: readonly ["mcp-stdio"];
+export interface MaterializeNexusProjectAgentMcpConfigOptions {
+    projectRoot: string;
+    mcpConfig?: NexusProjectMcpConfig;
+    agentTargets?: NexusProjectAgentMcpTarget[];
+    excludeFromGit?: boolean;
+}
+export interface MaterializedNexusAgentMcpTarget {
+    agent: string;
+    serverName: string;
+    command: string;
+    args: string[];
+    sourceControl: NexusSkillSourceControl;
+    configPath: string;
+    configFormat: "toml" | "json";
+}
+export interface MaterializeNexusProjectAgentMcpConfigResult {
+    agentTargets: MaterializedNexusAgentMcpTarget[];
+    gitExcludePath: string | null;
+    gitExcludeEntries: string[];
+}
+export declare class NexusAgentMcpConfigError extends Error {
+    constructor(message: string);
+}
+export declare function emptyNexusProjectAgentMcpConfigResult(): MaterializeNexusProjectAgentMcpConfigResult;
+export declare function materializeNexusProjectAgentMcpConfig(options: MaterializeNexusProjectAgentMcpConfigOptions): MaterializeNexusProjectAgentMcpConfigResult;

package/dist/nexusAgentMcpConfig.js

@@ -0,0 +1,228 @@
+import fs from "node:fs";
+import path from "node:path";
+export const defaultNexusMcpServerName = "dev_nexus";
+export const defaultNexusMcpCommand = "dev-nexus";
+export const defaultNexusMcpArgs = ["mcp-stdio"];
+export class NexusAgentMcpConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAgentMcpConfigError";
+    }
+}
+export function emptyNexusProjectAgentMcpConfigResult() {
+    return {
+        agentTargets: [],
+        gitExcludePath: null,
+        gitExcludeEntries: [],
+    };
+}
+export function materializeNexusProjectAgentMcpConfig(options) {
+    if (options.mcpConfig?.enabled === false) {
+        return emptyNexusProjectAgentMcpConfigResult();
+    }
+    const projectRoot = path.resolve(options.projectRoot);
+    const targets = resolveAgentMcpTargets(projectRoot, options);
+    for (const target of targets) {
+        if (target.configFormat === "toml") {
+            writeCodexMcpConfig(target);
+        }
+        else {
+            writeClaudeMcpConfig(target);
+        }
+    }
+    const supportEntries = targets
+        .filter((target) => target.sourceControl === "support")
+        .map((target) => gitExcludeEntryForPath(projectRoot, target.configPath));
+    const gitExclude = options.excludeFromGit === false
+        ? { gitExcludePath: null, gitExcludeEntries: [] }
+        : addGitExcludeEntries(projectRoot, supportEntries);
+    return {
+        agentTargets: targets,
+        gitExcludePath: gitExclude.gitExcludePath,
+        gitExcludeEntries: gitExclude.gitExcludeEntries,
+    };
+}
+function resolveAgentMcpTargets(projectRoot, options) {
+    const configuredTargets = options.agentTargets ?? options.mcpConfig?.agentTargets ?? [{ agent: "codex" }];
+    return configuredTargets
+        .filter((target) => target.enabled !== false)
+        .map((target) => {
+        const serverName = target.serverName ??
+            options.mcpConfig?.serverName ??
+            defaultNexusMcpServerName;
+        assertTomlBareKey(serverName, `mcp agent target ${target.agent}.serverName`);
+        const command = target.command ?? options.mcpConfig?.command ?? defaultNexusMcpCommand;
+        const args = [
+            ...(target.args ?? options.mcpConfig?.args ?? defaultNexusMcpArgs),
+        ];
+        const sourceControl = target.sourceControl ?? options.mcpConfig?.sourceControl ?? "support";
+        const configFormat = configFormatForAgent(target.agent);
+        const configPath = path.join(projectRoot, assertProjectRelativeFilePath(target.configPath ?? defaultConfigPathForAgent(target.agent), `mcp agent target ${target.agent}.configPath`));
+        return {
+            agent: target.agent,
+            serverName,
+            command,
+            args,
+            sourceControl,
+            configPath,
+            configFormat,
+        };
+    });
+}
+function configFormatForAgent(agent) {
+    if (agent === "codex") {
+        return "toml";
+    }
+    if (agent === "claude") {
+        return "json";
+    }
+    throw new NexusAgentMcpConfigError(`Agent MCP target is not supported: ${agent}`);
+}
+function defaultConfigPathForAgent(agent) {
+    if (agent === "codex") {
+        return path.join(".codex", "config.toml");
+    }
+    if (agent === "claude") {
+        return ".mcp.json";
+    }
+    throw new NexusAgentMcpConfigError(`Agent MCP target is not supported: ${agent}`);
+}
+function assertProjectRelativeFilePath(filePath, pathName) {
+    if (!filePath ||
+        path.isAbsolute(filePath) ||
+        filePath
+            .split(/[\\/]/u)
+            .some((part) => part === ".." || part === "." || part === "")) {
+        throw new NexusAgentMcpConfigError(`${pathName} must be a project-relative file path`);
+    }
+    return filePath;
+}
+function assertTomlBareKey(value, pathName) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value)) {
+        throw new NexusAgentMcpConfigError(`${pathName} must contain only letters, digits, underscores, and hyphens`);
+    }
+}
+function writeCodexMcpConfig(target) {
+    const existing = fs.existsSync(target.configPath)
+        ? fs.readFileSync(target.configPath, "utf8")
+        : "";
+    const nextContent = upsertCodexMcpServerBlock(existing, target);
+    fs.mkdirSync(path.dirname(target.configPath), { recursive: true });
+    fs.writeFileSync(target.configPath, nextContent, "utf8");
+}
+function upsertCodexMcpServerBlock(existing, target) {
+    const retainedLines = removeTomlServerTable(existing, target.serverName);
+    const retained = trimTrailingBlankLines(retainedLines).join("\n");
+    const serverBlock = [
+        `[mcp_servers.${target.serverName}]`,
+        `command = ${tomlString(target.command)}`,
+        `args = ${tomlStringArray(target.args)}`,
+    ].join("\n");
+    return retained.length > 0
+        ? `${retained}\n\n${serverBlock}\n`
+        : `${serverBlock}\n`;
+}
+function removeTomlServerTable(existing, serverName) {
+    const lines = existing.replace(/\r\n/gu, "\n").split("\n");
+    const retained = [];
+    let skipping = false;
+    for (const line of lines) {
+        const tableName = tomlTableName(line);
+        if (tableName) {
+            skipping = isMcpServerTable(tableName, serverName);
+            if (skipping) {
+                continue;
+            }
+        }
+        if (!skipping) {
+            retained.push(line);
+        }
+    }
+    return retained;
+}
+function tomlTableName(line) {
+    const match = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/u);
+    return match?.[1]?.trim() ?? null;
+}
+function isMcpServerTable(tableName, serverName) {
+    return (tableName === `mcp_servers.${serverName}` ||
+        tableName.startsWith(`mcp_servers.${serverName}.`));
+}
+function trimTrailingBlankLines(lines) {
+    const trimmed = [...lines];
+    while (trimmed.length > 0 && trimmed.at(-1)?.trim() === "") {
+        trimmed.pop();
+    }
+    return trimmed;
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlStringArray(values) {
+    return `[${values.map((value) => tomlString(value)).join(", ")}]`;
+}
+function writeClaudeMcpConfig(target) {
+    const existing = readJsonObject(target.configPath);
+    const existingServers = existing.mcpServers;
+    if (existingServers !== undefined &&
+        (!existingServers ||
+            typeof existingServers !== "object" ||
+            Array.isArray(existingServers))) {
+        throw new NexusAgentMcpConfigError(`Claude MCP config mcpServers must be an object: ${target.configPath}`);
+    }
+    const mcpServers = {
+        ...(existingServers ?? {}),
+        [target.serverName]: {
+            command: target.command,
+            args: target.args,
+        },
+    };
+    fs.mkdirSync(path.dirname(target.configPath), { recursive: true });
+    fs.writeFileSync(target.configPath, `${JSON.stringify({ ...existing, mcpServers }, null, 2)}\n`, "utf8");
+}
+function readJsonObject(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new NexusAgentMcpConfigError(`MCP config must be a JSON object: ${filePath}`);
+    }
+    return parsed;
+}
+function addGitExcludeEntries(projectRoot, entries) {
+    const gitInfoDir = path.join(projectRoot, ".git", "info");
+    if (!fs.existsSync(gitInfoDir) || !fs.statSync(gitInfoDir).isDirectory()) {
+        return {
+            gitExcludePath: null,
+            gitExcludeEntries: [],
+        };
+    }
+    const excludePath = path.join(gitInfoDir, "exclude");
+    const existing = fs.existsSync(excludePath)
+        ? fs.readFileSync(excludePath, "utf8")
+        : "";
+    const existingLines = new Set(existing
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean));
+    const appended = [];
+    for (const entry of entries) {
+        if (!existingLines.has(entry)) {
+            appended.push(entry);
+            existingLines.add(entry);
+        }
+    }
+    if (appended.length > 0) {
+        fs.mkdirSync(gitInfoDir, { recursive: true });
+        const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+        fs.appendFileSync(excludePath, `${prefix}${appended.join("\n")}\n`, "utf8");
+    }
+    return {
+        gitExcludePath: excludePath,
+        gitExcludeEntries: appended,
+    };
+}
+function gitExcludeEntryForPath(projectRoot, filePath) {
+    return path.relative(projectRoot, filePath).replace(/\\/gu, "/");
+}

package/dist/nexusAutomation.d.ts

@@ -0,0 +1,103 @@
+import type { NexusAutomationConfig } from "./nexusAutomationConfig.js";
+import type { WorkItem, WorkItemQuery } from "./workTrackingTypes.js";
+import { type WorktreePublicationDecision, type WorktreeVerificationRecord } from "./worktreeExecutionMetadata.js";
+export type NexusAutomationRunStatus = "started" | "completed" | "failed" | "blocked" | "skipped";
+export interface NexusAutomationRunRecord {
+    id: string;
+    projectId: string;
+    componentId: string | null;
+    status: NexusAutomationRunStatus;
+    startedAt: string;
+    finishedAt: string | null;
+    workItemId: string | null;
+    workItemTitle: string | null;
+    sourceRoot: string | null;
+    worktreePath: string | null;
+    branchName: string | null;
+    baseRef: string | null;
+    commitIds: string[];
+    summary: string | null;
+    verification: WorktreeVerificationRecord[];
+    publicationDecision: WorktreePublicationDecision | null;
+    error: string | null;
+    nextRunNotBefore: string | null;
+}
+export interface NexusAutomationRunRecordInput {
+    id: string;
+    projectId: string;
+    componentId?: string | null;
+    status: NexusAutomationRunStatus;
+    startedAt?: string;
+    finishedAt?: string | null;
+    workItemId?: string | null;
+    workItemTitle?: string | null;
+    sourceRoot?: string | null;
+    worktreePath?: string | null;
+    branchName?: string | null;
+    baseRef?: string | null;
+    commitIds?: string[];
+    summary?: string | null;
+    verification?: WorktreeVerificationRecord[];
+    publicationDecision?: WorktreePublicationDecision | null;
+    error?: string | null;
+    nextRunNotBefore?: string | null;
+}
+export interface NexusAutomationRunLedger {
+    version: 1;
+    runs: NexusAutomationRunRecord[];
+    updatedAt: string | null;
+}
+export interface NexusAutomationRunLock {
+    runId: string;
+    owner: string | null;
+    acquiredAt: string;
+    expiresAt: string;
+}
+export interface AcquireNexusAutomationRunLockOptions {
+    projectRoot: string;
+    config: NexusAutomationConfig;
+    runId: string;
+    owner?: string | null;
+    now?: Date | string;
+}
+export interface AcquireNexusAutomationRunLockResult {
+    lockPath: string;
+    lock: NexusAutomationRunLock;
+    replacedStaleLock: boolean;
+}
+export interface ReleaseNexusAutomationRunLockOptions {
+    projectRoot: string;
+    config: NexusAutomationConfig;
+    runId?: string;
+}
+export interface AppendNexusAutomationRunRecordOptions {
+    projectRoot: string;
+    config: NexusAutomationConfig;
+    record: NexusAutomationRunRecordInput;
+    now?: Date | string;
+}
+export interface NexusAutomationBackoffDecision {
+    consecutiveFailures: number;
+    shouldRun: boolean;
+    retryAfter: string | null;
+    delayMs: number | null;
+    reason: string | null;
+}
+export declare class NexusAutomationError extends Error {
+    constructor(message: string);
+}
+export declare function nexusAutomationLedgerPath(projectRoot: string, config: NexusAutomationConfig): string;
+export declare function nexusAutomationLockPath(projectRoot: string, config: NexusAutomationConfig): string;
+export declare function emptyNexusAutomationRunLedger(): NexusAutomationRunLedger;
+export declare function readNexusAutomationRunLedger(projectRoot: string, config: NexusAutomationConfig): NexusAutomationRunLedger;
+export declare function writeNexusAutomationRunLedger(projectRoot: string, config: NexusAutomationConfig, ledger: NexusAutomationRunLedger): string;
+export declare function appendNexusAutomationRunRecord(options: AppendNexusAutomationRunRecordOptions): NexusAutomationRunLedger;
+export declare function normalizeNexusAutomationRunLedger(value: unknown): NexusAutomationRunLedger;
+export declare function acquireNexusAutomationRunLock(options: AcquireNexusAutomationRunLockOptions): AcquireNexusAutomationRunLockResult;
+export declare function releaseNexusAutomationRunLock(options: ReleaseNexusAutomationRunLockOptions): boolean;
+export declare function buildNexusAutomationWorkItemQuery(config: NexusAutomationConfig): WorkItemQuery;
+export declare function selectNexusAutomationWorkItem(items: readonly WorkItem[], config: NexusAutomationConfig): WorkItem | undefined;
+export declare function eligibleNexusAutomationWorkItems(items: readonly WorkItem[], config: NexusAutomationConfig): WorkItem[];
+export declare function evaluateNexusAutomationBackoff(config: NexusAutomationConfig, consecutiveFailures: number, lastFailureAt: Date | string): NexusAutomationBackoffDecision;
+export declare function countConsecutiveNexusAutomationFailures(ledger: NexusAutomationRunLedger): number;
+export declare function evaluateNexusAutomationLedgerBackoff(config: NexusAutomationConfig, ledger: NexusAutomationRunLedger, now?: Date | string): NexusAutomationBackoffDecision;