@navels/neal 0.1.0

package/dist/neal/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import process from 'node:process';
+import { buildUsageLines, } from './cli.js';
+import { runCheckCommand } from './commands/check.js';
+import { runCompatCommand } from './commands/compat.js';
+import { runNewRunCommand } from './commands/new-run.js';
+import { runPlanAndExecuteCommand } from './commands/plan-and-execute.js';
+import { runResumeRunCommand } from './commands/resume-run.js';
+import { getCurrentRunLogger } from './commands/runtime.js';
+import { runReviewCommand } from './commands/review.js';
+import { runSetupCommand } from './commands/setup.js';
+import { runSquashCommand } from './commands/squash.js';
+import { runStatusCommand } from './commands/status.js';
+import { formatWriterProviderSetupRequiredLines, isWriterProvidersNotConfiguredError, } from './config.js';
+import { clearDiagnosticFooter, writeErrorDetail, writeNarrative } from './diagnostic.js';
+import { CoderRoundError, ReviewerRoundError } from './agents.js';
+import { getAppVersion } from './version.js';
+function printUsage(lines) {
+    for (const line of lines) {
+        console.error(line);
+    }
+}
+function usage() {
+    printUsage(buildUsageLines(getAppVersion()));
+    process.exit(1);
+}
+function help(lines) {
+    for (const line of lines) {
+        console.log(line);
+    }
+}
+function getProcessArgs() {
+    const args = process.argv.slice(2);
+    if (args[0] === '--' && process.env.npm_lifecycle_event === 'start') {
+        return args.slice(1);
+    }
+    return args;
+}
+async function main() {
+    const args = getProcessArgs();
+    const version = getAppVersion();
+    if (args.length === 0) {
+        usage();
+    }
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+        if (args.length === 1) {
+            help(buildUsageLines(version));
+            return;
+        }
+        throw new Error('Usage: neal help');
+    }
+    if (args[0] === 'version' || args[0] === '--version' || args[0] === '-V') {
+        if (args.length !== 1) {
+            throw new Error('Usage: neal version');
+        }
+        process.stdout.write(`${version}\n`);
+        return;
+    }
+    if (args[0] === 'status') {
+        await runStatusCommand(args);
+        return;
+    }
+    if (args[0] === 'review') {
+        await runReviewCommand(args);
+        return;
+    }
+    if (args[0] === 'setup') {
+        await runSetupCommand(args);
+        return;
+    }
+    if (args[0] === 'plan') {
+        await runNewRunCommand(args);
+        return;
+    }
+    if (args[0] === 'execute') {
+        await runNewRunCommand(args);
+        return;
+    }
+    if (args[0] === 'run') {
+        await runPlanAndExecuteCommand(args);
+        return;
+    }
+    if (args[0] === 'resume') {
+        await runResumeRunCommand(args);
+        return;
+    }
+    if (args[0] === 'squash') {
+        await runSquashCommand(args);
+        return;
+    }
+    if (args[0] === 'check') {
+        await runCheckCommand(args);
+        return;
+    }
+    if (args[0] === 'compat') {
+        await runCompatCommand(args);
+        return;
+    }
+    throw new Error(`Unknown command: ${args[0]}. Run \`neal help\` for supported commands.`);
+}
+void main().catch((error) => {
+    clearDiagnosticFooter();
+    const runLogger = getCurrentRunLogger();
+    const message = error instanceof Error ? error.message : String(error);
+    const coderSessionHandle = error instanceof CoderRoundError ? error.sessionHandle : null;
+    const reviewerSessionHandle = error instanceof ReviewerRoundError ? error.sessionHandle : null;
+    void runLogger?.event('run.failed', {
+        message,
+        coderSessionHandle,
+        reviewerSessionHandle,
+        reviewerSubtype: error instanceof ReviewerRoundError ? error.subtype : null,
+    });
+    if (error instanceof Error && error.stack) {
+        void runLogger?.stderr(`[fatal] ${error.stack}\n`);
+    }
+    else {
+        void runLogger?.stderr(`[fatal] ${message}\n`);
+    }
+    if (coderSessionHandle) {
+        writeErrorDetail(`[neal:detail] coder session: ${coderSessionHandle}\n`, runLogger, { role: 'coder' });
+    }
+    else if (reviewerSessionHandle) {
+        writeErrorDetail(`[neal:detail] reviewer session: ${reviewerSessionHandle}\n`, runLogger, { role: 'reviewer' });
+    }
+    if (isWriterProvidersNotConfiguredError(error)) {
+        writeNarrative(`${formatWriterProviderSetupRequiredLines(error, '[neal]').join('\n')}\n`);
+    }
+    else {
+        // Some thrown messages already carry the prefix (e.g. run-lock guidance);
+        // only prepend it when absent so every failure reports it exactly once.
+        writeNarrative(message.startsWith('[neal] ') ? `${message}\n` : `[neal] ${message}\n`);
+    }
+    process.exit(1);
+});

package/dist/neal/interactive-controls.js

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+import readline from 'node:readline';
+import { clearDiagnosticFooter, getBufferedDetailSnapshot, isDiagnosticDetailVisible, showDiagnosticDetailView, showDiagnosticNarrativeView, writeNarrative, } from './diagnostic.js';
+export function createInteractiveKeyController(options = {}) {
+    let stopRequested = false;
+    let cleanedUp = false;
+    const input = options.input ?? process.stdin;
+    const stopRequestFile = options.stopRequestFile ?? process.env.NEAL_STOP_AFTER_CURRENT_SCOPE_FILE;
+    const allowStopRequest = options.allowStopRequest ?? true;
+    if (!input.isTTY) {
+        return {
+            cleanup() { },
+            isStopRequested() {
+                return allowStopRequest && (stopRequested || hasStopRequestFile(stopRequestFile));
+            },
+        };
+    }
+    const emitKeypressEvents = options.emitKeypressEvents ?? readline.emitKeypressEvents;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    emitKeypressEvents(input);
+    input.setRawMode?.(true);
+    input.resume();
+    const onKeypress = (_input, key) => {
+        if (key.ctrl && key.name === 'c') {
+            cleanup();
+            clearDiagnosticFooter();
+            exit(130);
+            return;
+        }
+        if (key.name === 'q' && allowStopRequest) {
+            stopRequested = !stopRequested;
+            writeNarrative(stopRequested
+                ? '\n[neal] stop requested after the current scope\n'
+                : '\n[neal] stop request cleared; continuing after the current scope\n');
+            return;
+        }
+        if (key.name === 'v') {
+            toggleDetailVisibility(options.getDetailFilter?.() ?? {});
+        }
+    };
+    input.on('keypress', onKeypress);
+    function cleanup() {
+        if (cleanedUp) {
+            return;
+        }
+        cleanedUp = true;
+        input.off('keypress', onKeypress);
+        if (input.isTTY) {
+            input.setRawMode?.(false);
+        }
+        input.pause();
+    }
+    return {
+        cleanup,
+        isStopRequested() {
+            return allowStopRequest && (stopRequested || hasStopRequestFile(stopRequestFile));
+        },
+    };
+}
+function hasStopRequestFile(stopRequestFile) {
+    return stopRequestFile ? existsSync(stopRequestFile) : false;
+}
+function toggleDetailVisibility(filter) {
+    if (isDiagnosticDetailVisible()) {
+        showDiagnosticNarrativeView();
+        return;
+    }
+    showDiagnosticDetailView(selectDetailReplayFilter(filter));
+}
+function selectDetailReplayFilter(filter) {
+    if (!filter.runId) {
+        return filter;
+    }
+    const preferredFilter = {
+        runId: filter.runId,
+        phase: filter.phase,
+        scopeLabel: filter.scopeLabel,
+        scopeNumber: filter.scopeNumber,
+    };
+    const preferredSnapshot = getBufferedDetailSnapshot(preferredFilter);
+    if (preferredSnapshot.entries.length > 0) {
+        return preferredFilter;
+    }
+    return { runId: filter.runId };
+}

package/dist/neal/logger.js

@@ -0,0 +1,102 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { writeJsonAtomic } from './atomic-write.js';
+import { RUNS_DIR_NAME } from './storage-paths.js';
+import { getNealBuildMetadata } from './version.js';
+export function createRunId() {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `${timestamp}-${randomUUID().slice(0, 8)}`;
+}
+async function safeWrite(action) {
+    try {
+        await action();
+    }
+    catch {
+        // Best-effort diagnostics only.
+    }
+}
+async function readExistingMeta(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function appendResumeMeta(meta, resume) {
+    const resumes = Array.isArray(meta.resumes) ? meta.resumes : [];
+    return {
+        ...meta,
+        resumes: [
+            ...resumes,
+            resume,
+        ],
+    };
+}
+export class RunLogger {
+    runDir;
+    eventsPath;
+    stderrPath;
+    metaPath;
+    constructor(runDir) {
+        this.runDir = runDir;
+        this.eventsPath = join(runDir, 'events.ndjson');
+        this.stderrPath = join(runDir, 'stderr.log');
+        this.metaPath = join(runDir, 'meta.json');
+    }
+    async init(init) {
+        await safeWrite(async () => {
+            await mkdir(this.runDir, { recursive: true });
+            const now = new Date().toISOString();
+            const build = await getNealBuildMetadata();
+            const resumeRecord = init.resumedFromStatePath
+                ? {
+                    resumedAt: now,
+                    resumedFromStatePath: init.resumedFromStatePath,
+                    build,
+                }
+                : null;
+            if (resumeRecord) {
+                const existing = await readExistingMeta(this.metaPath);
+                if (existing) {
+                    await writeJsonAtomic(this.metaPath, appendResumeMeta(existing, resumeRecord));
+                    return;
+                }
+            }
+            await writeJsonAtomic(this.metaPath, {
+                version: 1,
+                createdAt: now,
+                cwd: init.cwd,
+                planDoc: init.planDoc,
+                planName: basename(init.planDoc),
+                topLevelMode: init.topLevelMode,
+                resumedFromStatePath: init.resumedFromStatePath ?? null,
+                runDir: this.runDir,
+                ...(resumeRecord ? { resumes: [resumeRecord] } : { build }),
+            });
+        });
+    }
+    async event(type, data) {
+        const payload = {
+            ts: new Date().toISOString(),
+            type,
+            data,
+        };
+        await safeWrite(async () => {
+            await appendFile(this.eventsPath, JSON.stringify(payload) + '\n', 'utf8');
+        });
+    }
+    async stderr(message) {
+        await safeWrite(async () => {
+            await appendFile(this.stderrPath, message, 'utf8');
+        });
+    }
+}
+export async function createRunLogger(init) {
+    const runDir = init.runDir ?? join(init.stateDir, RUNS_DIR_NAME, createRunId());
+    const logger = new RunLogger(runDir);
+    await logger.init(init);
+    return logger;
+}

package/dist/neal/manual-gates.js

@@ -0,0 +1,121 @@
+import { spawn } from 'node:child_process';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const OUTPUT_TAIL_LIMIT = 4_000;
+const REDACTED = '[redacted]';
+export async function runManualGateResumeChecks(state) {
+    const gate = state.manualGate;
+    if (state.phase !== 'manual_gate' || gate === null) {
+        throw new Error('Cannot run manual gate resume checks without an active manual gate.');
+    }
+    const results = [];
+    for (const check of gate.resumeChecks) {
+        const result = await runManualGateResumeCheck(state, check);
+        results.push(result);
+        if (!result.ok) {
+            return {
+                ok: false,
+                failure: result,
+                results,
+            };
+        }
+    }
+    return {
+        ok: true,
+        results: results,
+    };
+}
+export function redactManualGateOutput(value, env = process.env) {
+    let redacted = value;
+    for (const [key, secret] of Object.entries(env)) {
+        if (!secret || !isSensitiveEnvKey(key)) {
+            continue;
+        }
+        redacted = redacted.split(secret).join(REDACTED);
+    }
+    return redacted;
+}
+function isSensitiveEnvKey(key) {
+    return /TOKEN|SECRET|PASSWORD|KEY/i.test(key);
+}
+async function runManualGateResumeCheck(state, check) {
+    const [command, ...args] = check.command;
+    if (!command) {
+        throw new Error(`Manual gate check ${check.name} has an empty command.`);
+    }
+    const timeoutMs = check.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const cwd = check.cwd === 'run_dir' ? state.runDir : state.cwd;
+    const raw = await runCommand({
+        command,
+        args,
+        cwd,
+        timeoutMs,
+    });
+    const stdoutTail = boundedTail(redactManualGateOutput(raw.stdout));
+    const stderrTail = boundedTail(redactManualGateOutput(raw.stderr));
+    if (raw.exitCode === 0 && raw.signal === null) {
+        return {
+            ok: true,
+            checkName: check.name,
+            exitCode: 0,
+            signal: null,
+            stdoutTail,
+            stderrTail,
+        };
+    }
+    return {
+        ok: false,
+        checkName: check.name,
+        exitCode: raw.exitCode,
+        signal: raw.signal,
+        stdoutTail,
+        stderrTail,
+    };
+}
+function runCommand(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(args.command, args.args, {
+            cwd: args.cwd,
+            shell: false,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        let settled = false;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, args.timeoutMs);
+        child.stdout?.on('data', (chunk) => {
+            stdout.push(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr.push(chunk);
+        });
+        child.once('error', (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.once('close', (exitCode, signal) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                exitCode,
+                signal: signal ?? (timedOut ? 'SIGTERM' : null),
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+            });
+        });
+    });
+}
+function boundedTail(value) {
+    return value.length <= OUTPUT_TAIL_LIMIT ? value : value.slice(value.length - OUTPUT_TAIL_LIMIT);
+}

package/dist/neal/orchestrator/artifacts.js

@@ -0,0 +1,70 @@
+import { writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { writeRecoveryMarkdown } from '../support.js';
+import { getFinalCompletionReviewArtifactPath, writeFinalCompletionReviewMarkdown } from '../final-completion-review.js';
+import { writePlanProgressArtifacts } from '../progress.js';
+import { writeReviewMarkdown } from '../review.js';
+import { writeRunNarrativeArtifacts } from '../run-narrative.js';
+import { hasFinalCompletionReviewState } from '../state-views.js';
+export async function writeExecutionArtifacts(state) {
+    await writeReviewMarkdown(state.reviewMarkdownPath, state);
+    await writeRecoveryMarkdown(state.recoveryMarkdownPath, state);
+    await writePlanProgressArtifacts(state);
+    if (hasFinalCompletionReviewState(state)) {
+        await writeFinalCompletionReviewMarkdown(getFinalCompletionReviewArtifactPath(state.runDir), state);
+    }
+    await writeRunNarrativeArtifacts(state);
+}
+export function validateManualGateId(id) {
+    const trimmed = id.trim();
+    if (!trimmed) {
+        throw new Error('Manual gate id must be non-empty.');
+    }
+    if (trimmed.includes('..') ||
+        trimmed.includes('/') ||
+        trimmed.includes('\\') ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed)) {
+        throw new Error(`Manual gate id ${JSON.stringify(id)} cannot safely form a gate artifact filename.`);
+    }
+    return trimmed;
+}
+export function getManualGateArtifactPath(runDir, gateId) {
+    return join(runDir, `GATE-${validateManualGateId(gateId)}.md`);
+}
+export async function writeManualGateArtifact(args) {
+    const id = validateManualGateId(args.id);
+    const artifactPath = getManualGateArtifactPath(args.state.runDir, id);
+    const runId = basename(args.state.runDir);
+    const lines = [
+        `# ${args.title.trim()}`,
+        '',
+        '## Reason',
+        '',
+        args.reason.trim(),
+        '',
+        '## Instructions',
+        '',
+        args.instructionsMarkdown.trim(),
+        '',
+        '## Resume Checks',
+        '',
+        ...args.resumeChecks.flatMap((check) => renderResumeCheck(check)),
+        '## Resume',
+        '',
+        `Run \`neal resume --run ${runId}\` after the manual work is complete.`,
+        '',
+        'Neal will resume the same `coder_scope` after these checks pass.',
+        '',
+    ];
+    await writeFile(artifactPath, `${lines.join('\n').trimEnd()}\n`, 'utf8');
+    return artifactPath;
+}
+function renderResumeCheck(check) {
+    return [
+        `- ${check.name}`,
+        `  - argv: \`${JSON.stringify(check.command)}\``,
+        `  - cwd: \`${check.cwd ?? 'repo'}\``,
+        ...(check.timeoutMs === undefined ? [] : [`  - timeoutMs: \`${check.timeoutMs}\``]),
+        '',
+    ];
+}