@navels/neal 0.1.0

package/dist/neal/orchestrator.js

@@ -0,0 +1,215 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { getMaxReviewRounds, getPhaseHeartbeatMs } from './config.js';
+import { getHeadCommit, getWorktreeStatus } from './git.js';
+import { createRunLogger } from './logger.js';
+import { writeDetail } from './diagnostic.js';
+import { logUserGuidanceApplied } from './prompts/guidance.js';
+import { writeExecutionArtifacts } from './orchestrator/artifacts.js';
+import { runFinalCompletionReviewPhase as runFinalCompletionReviewPhaseImpl, runExecuteFinalizationPhase as runExecuteFinalizationPhaseImpl, } from './orchestrator/completion.js';
+import { runOnePass as runOnePassLoop, } from './orchestrator/run-loop.js';
+import { runCoderScopePhase, runExecuteResponsePhase, } from './orchestrator/phases/coder.js';
+import { hasPendingInteractiveBlockedRecoveryTurn, runInteractiveBlockedRecoveryPhase, } from './orchestrator/phases/recovery.js';
+import { runAwaitingDerivedPlanExecutionPhase, runCoderPlanPhase, runPlanReviewPhase, runPlanningResponsePhase, } from './orchestrator/phases/planning.js';
+import { runReviewPhase } from './orchestrator/phases/review.js';
+import { writeCheckpointRetrospective } from './retrospective.js';
+import { applyResumeActions, planResumeActions } from './resume-planner.js';
+import { writeCurrentRunPointer } from './run-registry.js';
+import { createInitialState, getRunStatePath, loadState, saveState } from './state.js';
+import { getNealDir, getPlanDocumentBackupPath } from './storage-paths.js';
+import { filterAllowedDirtyPathStatus, filterWrapperOwnedWorktreeStatus, formatDirtyWorktreeDiagnostic, } from './worktree-status.js';
+export const runFinalCompletionReviewPhase = (state, statePath, logger) => runFinalCompletionReviewPhaseImpl(state, statePath, logger, {
+    writeExecutionArtifacts,
+});
+export const runExecuteFinalizationPhase = (state, statePath, logger) => runExecuteFinalizationPhaseImpl(state, statePath, logger, {
+    writeExecutionArtifacts,
+});
+function startPhaseHeartbeat(phase, getState, logger, intervalMs = getPhaseHeartbeatMs(getState().cwd)) {
+    if (!logger || intervalMs <= 0) {
+        return () => { };
+    }
+    const startedAt = Date.now();
+    const timer = setInterval(() => {
+        const state = getState();
+        const elapsedMs = Date.now() - startedAt;
+        const payload = {
+            phase,
+            elapsedMs,
+            coderSessionHandle: state.coderSessionHandle,
+            reviewerSessionHandle: state.reviewerSessionHandle,
+            currentScopeNumber: state.currentScopeNumber,
+            topLevelMode: state.topLevelMode,
+        };
+        void logger.event('phase.heartbeat', payload);
+        writePhaseHeartbeatDetail({ state, phase, elapsedMs, logger });
+    }, intervalMs);
+    return () => clearInterval(timer);
+}
+export function writePhaseHeartbeatDetail(args) {
+    writeDetail(`[neal] heartbeat phase=${args.phase} elapsed=${Math.round(args.elapsedMs / 1000)}s` +
+        `${args.state.coderSessionHandle ? ` coder=${args.state.coderSessionHandle}` : ''}` +
+        `${args.state.reviewerSessionHandle ? ` reviewer=${args.state.reviewerSessionHandle}` : ''}\n`, args.logger, {
+        runId: basename(args.state.runDir),
+        phase: args.phase,
+        scopeNumber: args.state.currentScopeNumber ?? undefined,
+    });
+}
+export async function initializeOrchestration(planDoc, cwd, agentConfig, topLevelMode = 'execute', options) {
+    const absolutePlanDoc = resolve(planDoc);
+    const stateDir = getNealDir(cwd);
+    const logger = await createRunLogger({
+        cwd,
+        stateDir,
+        planDoc: absolutePlanDoc,
+        topLevelMode,
+        runDir: options?.runDir,
+    });
+    const planDocBackupPath = topLevelMode === 'plan' ? await createPlanDocumentBackup(absolutePlanDoc, logger.runDir) : null;
+    const init = {
+        cwd,
+        planDoc: absolutePlanDoc,
+        planDocBackupPath,
+        stateDir,
+        runDir: logger.runDir,
+        topLevelMode,
+        allowedDirtyPaths: options?.allowedDirtyPaths ?? [],
+        agentConfig,
+        unattended: options?.unattended ?? false,
+        autoSquashOnCompletion: options?.autoSquashOnCompletion ?? true,
+        progressJsonPath: join(logger.runDir, 'plan-progress.json'),
+        progressMarkdownPath: join(logger.runDir, 'PLAN_PROGRESS.md'),
+        reviewMarkdownPath: join(logger.runDir, 'REVIEW.md'),
+        recoveryMarkdownPath: join(logger.runDir, 'RECOVERY.md'),
+        maxRounds: getMaxReviewRounds(cwd),
+    };
+    await mkdir(stateDir, { recursive: true });
+    const baseCommit = await getHeadCommit(cwd);
+    const initialState = await createInitialState(init, baseCommit);
+    const statePath = getRunStatePath(logger.runDir);
+    const savedState = await saveState(statePath, initialState);
+    await writeCurrentRunPointer(savedState);
+    await writeExecutionArtifacts(savedState);
+    await logger.event('run.initialized', {
+        statePath,
+        baseCommit,
+        topLevelMode,
+        planDocBackupPath,
+        agentConfig: savedState.agentConfig,
+        reviewMarkdownPath: savedState.reviewMarkdownPath,
+        progressJsonPath: savedState.progressJsonPath,
+        progressMarkdownPath: savedState.progressMarkdownPath,
+    });
+    await logUserGuidanceApplied(logger);
+    return {
+        state: savedState,
+        statePath,
+        logger,
+    };
+}
+async function createPlanDocumentBackup(planDoc, runDir) {
+    const backupPath = getPlanDocumentBackupPath(runDir);
+    await mkdir(dirname(backupPath), { recursive: true });
+    await copyFile(planDoc, backupPath);
+    return backupPath;
+}
+export async function runOnePass(state, statePath, logger, options) {
+    const runPhaseWithCoderSessionHandle = async (runPhase) => {
+        const nextState = await runPhase();
+        options?.onCoderSessionHandle?.(nextState.coderSessionHandle);
+        return nextState;
+    };
+    const handlers = {
+        coder_plan: async (currentState) => runPhaseWithCoderSessionHandle(() => runCoderPlanPhase(currentState, statePath, logger)),
+        reviewer_plan: async (currentState) => runPlanReviewPhase(currentState, statePath, logger),
+        coder_plan_response: async (currentState) => runPhaseWithCoderSessionHandle(() => runPlanningResponsePhase(currentState, statePath, currentState.phase, logger)),
+        awaiting_derived_plan_execution: async (currentState) => runAwaitingDerivedPlanExecutionPhase(currentState, statePath, logger),
+        coder_scope: async (currentState) => runPhaseWithCoderSessionHandle(() => runCoderScopePhase(currentState, statePath, logger)),
+        reviewer_scope: async (currentState) => runReviewPhase(currentState, statePath, logger),
+        coder_response: async (currentState) => runPhaseWithCoderSessionHandle(() => runExecuteResponsePhase(currentState, statePath, currentState.phase, logger)),
+        interactive_blocked_recovery: async (currentState) => runPhaseWithCoderSessionHandle(() => runInteractiveBlockedRecoveryPhase(currentState, statePath, logger)),
+        execute_finalization: async (currentState) => runExecuteFinalizationPhase(currentState, statePath, logger),
+        final_completion_review: async (currentState) => runFinalCompletionReviewPhase(currentState, statePath, logger),
+    };
+    return runOnePassLoop({
+        state,
+        statePath,
+        logger,
+        options,
+        runtime: {
+            hasPendingInteractiveBlockedRecoveryTurn,
+            startPhaseHeartbeat,
+            writeCheckpointRetrospective: async (currentState, reason) => {
+                await writeCheckpointRetrospective(currentState, reason);
+            },
+        },
+        handlers,
+    });
+}
+export async function loadOrInitialize(planDoc, cwd, agentConfig, resumeStatePath, topLevelMode = 'execute', options) {
+    if (resumeStatePath) {
+        return loadRunForResume(resumeStatePath);
+    }
+    return initializeNewRun(planDoc, cwd, agentConfig, topLevelMode, options);
+}
+export async function loadRunForResume(resumeStatePath) {
+    const initialState = await loadState(resumeStatePath);
+    const logger = await createRunLogger({
+        cwd: initialState.cwd,
+        stateDir: dirname(resumeStatePath),
+        planDoc: initialState.planDoc,
+        topLevelMode: initialState.topLevelMode,
+        runDir: initialState.runDir,
+        resumedFromStatePath: resumeStatePath,
+    });
+    await logger.event('run.resumed', {
+        statePath: resumeStatePath,
+        phase: initialState.phase,
+        status: initialState.status,
+        agentConfig: initialState.agentConfig,
+    });
+    await logUserGuidanceApplied(logger);
+    const resumeActions = planResumeActions(initialState);
+    const state = await applyResumeActions(initialState, resumeStatePath, logger, resumeActions);
+    await writeCurrentRunPointer(state);
+    await writeExecutionArtifacts(state);
+    return {
+        state,
+        statePath: resumeStatePath,
+        logger,
+    };
+}
+export async function initializeNewRun(planDoc, cwd, agentConfig, topLevelMode = 'execute', options) {
+    if (!planDoc) {
+        throw new Error('planDoc is required when initializing a new orchestration');
+    }
+    if (topLevelMode === 'execute') {
+        const statusOutput = filterAllowedDirtyPathStatus(cwd, filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(cwd)), getExecuteAdmissionAllowedDirtyPaths(cwd, planDoc, options?.allowedDirtyPaths ?? []));
+        if (statusOutput) {
+            const diagnostic = formatDirtyWorktreeDiagnostic({
+                statusOutput,
+                expectedScratchDirs: ['.neal/runs/<run-id>/scratch/'],
+            });
+            throw new Error([
+                `Cannot start neal execute with a dirty worktree:\n${statusOutput}`,
+                diagnostic,
+                'Use neal resume for in-progress scope work, or start from a clean worktree.',
+            ]
+                .filter(Boolean)
+                .join('\n\n'));
+        }
+    }
+    return initializeOrchestration(planDoc, cwd, agentConfig, topLevelMode, options);
+}
+function getExecuteAdmissionAllowedDirtyPaths(cwd, planDoc, allowedDirtyPaths) {
+    const expandedPaths = [...allowedDirtyPaths];
+    const absoluteCwd = resolve(cwd);
+    const absolutePlanDoc = resolve(planDoc);
+    const relativePlanDoc = relative(absoluteCwd, absolutePlanDoc);
+    if (relativePlanDoc && (relativePlanDoc.startsWith('..') || isAbsolute(relativePlanDoc))) {
+        const localPlanSurrogate = basename(absolutePlanDoc);
+        if (localPlanSurrogate && !expandedPaths.includes(localPlanSurrogate)) {
+            expandedPaths.push(localPlanSurrogate);
+        }
+    }
+    return expandedPaths;
+}

package/dist/neal/phase-display.js

@@ -0,0 +1,27 @@
+import { EXECUTE_FINALIZATION_PHASE, EXECUTE_FINALIZATION_PUBLIC_LABEL, } from './execute-finalization.js';
+const PUBLIC_PHASE_LABELS = {
+    coder_plan: 'refining plan',
+    reviewer_plan: 'reviewing plan',
+    coder_plan_response: 'revising plan',
+    coder_plan_optional_response: 'optional plan revision',
+    awaiting_derived_plan_execution: 'ready to execute derived plan',
+    coder_scope: 'implementing current scope',
+    manual_gate: 'waiting for manual gate',
+    reviewer_scope: 'reviewing current scope',
+    coder_response: 'addressing review findings',
+    coder_optional_response: 'optional review follow-up',
+    interactive_blocked_recovery: 'waiting for recovery guidance',
+    [EXECUTE_FINALIZATION_PHASE]: EXECUTE_FINALIZATION_PUBLIC_LABEL,
+    final_completion_review: 'reviewing final completion',
+    done: 'done',
+    blocked: 'blocked',
+};
+export function formatPublicPhase(phase) {
+    return PUBLIC_PHASE_LABELS[phase];
+}
+export function formatMaybePublicPhase(value) {
+    if (!value) {
+        return null;
+    }
+    return value in PUBLIC_PHASE_LABELS ? PUBLIC_PHASE_LABELS[value] : value;
+}

package/dist/neal/plan-doc.js

@@ -0,0 +1,154 @@
+import { realpath, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { getIgnoredPaths, getRepositoryRoot } from './git.js';
+export async function inspectPlanDocDisposition(cwd, planDoc, options = {}) {
+    const repositoryRoot = await realpath(await getRepositoryRoot(cwd));
+    const absolutePlanDoc = resolve(cwd, planDoc);
+    const comparablePlanDoc = await resolvePathForRepositoryComparison(absolutePlanDoc);
+    const selectedPlanDoc = absolutePlanDoc;
+    if (!isPathInside(repositoryRoot, comparablePlanDoc)) {
+        const fileStatus = await getFileStatus(absolutePlanDoc);
+        return {
+            selectedPlanDoc,
+            absolutePlanDoc,
+            repositoryRoot,
+            repoRelativePath: null,
+            normalizedPlanDoc: absolutePlanDoc,
+            disposition: 'outside_repo',
+            eligibleForCommit: false,
+            exists: fileStatus !== 'missing',
+            isRegularFile: fileStatus === 'regular_file',
+            ignored: false,
+        };
+    }
+    const repoRelativePath = toRepoRelativePath(repositoryRoot, comparablePlanDoc);
+    const normalizedPlanDoc = repoRelativePath;
+    const fileStatus = await getFileStatus(absolutePlanDoc);
+    if (fileStatus === 'missing') {
+        return {
+            selectedPlanDoc,
+            absolutePlanDoc,
+            repositoryRoot,
+            repoRelativePath,
+            normalizedPlanDoc,
+            disposition: 'missing',
+            eligibleForCommit: false,
+            exists: false,
+            isRegularFile: false,
+            ignored: false,
+        };
+    }
+    if (fileStatus !== 'regular_file') {
+        return {
+            selectedPlanDoc,
+            absolutePlanDoc,
+            repositoryRoot,
+            repoRelativePath,
+            normalizedPlanDoc,
+            disposition: 'not_regular_file',
+            eligibleForCommit: false,
+            exists: true,
+            isRegularFile: false,
+            ignored: false,
+        };
+    }
+    const ignoredPaths = await getIgnoredPaths(repositoryRoot, [repoRelativePath]);
+    const ignored = ignoredPaths.includes(repoRelativePath);
+    if (ignored) {
+        return {
+            selectedPlanDoc,
+            absolutePlanDoc,
+            repositoryRoot,
+            repoRelativePath,
+            normalizedPlanDoc,
+            disposition: 'ignored',
+            eligibleForCommit: false,
+            exists: true,
+            isRegularFile: true,
+            ignored: true,
+        };
+    }
+    const changedFiles = new Set((options.changedFiles ?? []).map((changedFile) => normalizeChangedFilePath(repositoryRoot, changedFile)));
+    const disposition = changedFiles.has(repoRelativePath) ? 'included' : 'metadata_only_clean';
+    return {
+        selectedPlanDoc,
+        absolutePlanDoc,
+        repositoryRoot,
+        repoRelativePath,
+        normalizedPlanDoc,
+        disposition,
+        eligibleForCommit: true,
+        exists: true,
+        isRegularFile: true,
+        ignored: false,
+    };
+}
+export function toPlanDocMetadata(inspection) {
+    return {
+        selectedPlanDoc: inspection.selectedPlanDoc,
+        normalizedPlanDoc: inspection.normalizedPlanDoc,
+        planDocDisposition: inspection.disposition,
+        repoRelativePath: inspection.repoRelativePath,
+        eligibleForCommit: inspection.eligibleForCommit,
+    };
+}
+function isPathInside(parent, child) {
+    const relativePath = relative(parent, child);
+    return (relativePath === '' ||
+        (relativePath !== '..' &&
+            !relativePath.startsWith(`..${sep}`) &&
+            !isAbsolute(relativePath)));
+}
+function toRepoRelativePath(repositoryRoot, path) {
+    const relativePath = relative(repositoryRoot, path);
+    return toGitPath(relativePath === '' ? '.' : normalize(relativePath));
+}
+function normalizeChangedFilePath(repositoryRoot, path) {
+    const absolutePath = isAbsolute(path) ? resolve(path) : null;
+    if (absolutePath && isPathInside(repositoryRoot, absolutePath)) {
+        return toRepoRelativePath(repositoryRoot, absolutePath);
+    }
+    return toGitPath(normalize(path));
+}
+function toGitPath(path) {
+    return path.split(sep).join('/');
+}
+async function getFileStatus(path) {
+    try {
+        const fileStat = await stat(path);
+        return fileStat.isFile() ? 'regular_file' : 'not_regular_file';
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, 'ENOENT')) {
+            return 'missing';
+        }
+        throw error;
+    }
+}
+async function resolvePathForRepositoryComparison(path) {
+    const missingSegments = [];
+    let currentPath = path;
+    while (true) {
+        try {
+            const existingPath = await realpath(currentPath);
+            return missingSegments.length === 0 ? existingPath : join(existingPath, ...missingSegments.reverse());
+        }
+        catch (error) {
+            if (!isNodeErrorWithCode(error, 'ENOENT')) {
+                throw error;
+            }
+            const parent = dirname(currentPath);
+            if (parent === currentPath) {
+                return path;
+            }
+            missingSegments.push(basename(currentPath));
+            currentPath = parent;
+        }
+    }
+}
+function isNodeErrorWithCode(error, code) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === code);
+}