@dhananjay_kaushik/claude-orchestrator 0.1.1

package/dist/config/schema.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export const verificationCommandSchema = z.object({
+    command: z.string().min(1, 'Command must be a non-empty string'),
+    args: z.array(z.string()),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive('Timeout must be a positive integer')
+        .max(3600000, 'Verification command timeout cannot exceed 1 hour'),
+    name: z.string().optional(),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    allowFailure: z.boolean().optional(),
+});
+export const configSchema = z.object({
+    version: z.string(),
+    planDir: z.string(),
+    baseBranch: z.string(),
+    branchPrefix: z.string(),
+    models: z.object({
+        planning: z.string(),
+        execution: z.string().optional(),
+    }),
+    claude: z.object({
+        binary: z.string(),
+        permissionMode: z.string().optional(),
+        allowedTools: z.array(z.string()).optional(),
+        extraSafeArgs: z.array(z.string()).optional(),
+    }),
+    taskTimeoutMs: z.number().int().positive().max(7200000, 'Task timeout cannot exceed 2 hours'),
+    verificationCommands: z.array(verificationCommandSchema),
+    maxRetries: z.number().int().min(0).max(10, 'Max retries cannot exceed 10'),
+    logsDir: z.string(),
+    stateDir: z.string(),
+    worktreeDir: z.string(),
+    commitMessageTemplate: z.string(),
+    sessionLimits: z
+        .object({
+        showBeforeRun: z.boolean(),
+        pauseOnLimit: z.boolean(),
+    })
+        .strict(),
+    security: z.object({
+        allowedCommands: z.array(z.string()).optional(),
+        deniedCommands: z.array(z.string()),
+        protectedPaths: z.array(z.string()),
+        allowNetwork: z.boolean(),
+    }),
+    notifications: z.unknown().optional(),
+});

package/dist/executor/command.js

@@ -0,0 +1,18 @@
+export function buildClaudeCommand(config, prompt) {
+    const command = config.claude?.binary || 'claude';
+    const args = ['-p', prompt, '--output-format', 'json'];
+    if (config.models?.execution) {
+        args.push('--model', config.models.execution);
+    }
+    if (config.claude?.permissionMode) {
+        args.push('--permission-mode', config.claude.permissionMode);
+    }
+    if (config.claude?.allowedTools && config.claude.allowedTools.length > 0) {
+        args.push('--allowedTools', config.claude.allowedTools.join(','));
+    }
+    if (config.claude?.extraSafeArgs && config.claude.extraSafeArgs.length > 0) {
+        const safeArgs = config.claude.extraSafeArgs.filter((arg) => arg !== '--dangerously-skip-permissions');
+        args.push(...safeArgs);
+    }
+    return { command, args };
+}

package/dist/executor/execution.js

@@ -0,0 +1,191 @@
+import { execa } from 'execa';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { buildClaudeCommand } from './command.js';
+import { extractOrchestratorResult } from './parser.js';
+import { redactSecrets } from '../logging/redact.js';
+export async function checkClaudeSessionLimits(config) {
+    // Attempt to read from Claude status.
+    // Claude Code does not yet provide a structured 'status' CLI command,
+    // so this is a best-effort preflight that fails gracefully.
+    try {
+        const result = await execa(config.claude.binary, ['-p', 'status', '--output-format', 'json'], {
+            shell: false,
+            timeout: 5000,
+            stdin: 'ignore',
+            stdout: 'pipe',
+            stderr: 'pipe',
+        });
+        try {
+            const parsed = JSON.parse(result.stdout);
+            let limitReached = false;
+            let resetTime;
+            const msg = parsed.result || '';
+            if (msg.match(/limit reached|usage limit/i)) {
+                limitReached = true;
+                const resetMatch = msg.match(/resets? in ([a-zA-Z0-9 ]+)/i);
+                if (resetMatch) {
+                    resetTime = resetMatch[1].trim();
+                }
+            }
+            return {
+                limitReached,
+                usage: parsed.usage,
+                resetTime,
+                message: limitReached ? msg : undefined,
+            };
+        }
+        catch {
+            return { limitReached: false };
+        }
+    }
+    catch (error) {
+        let limitReached = false;
+        let resetTime;
+        const errorMsg = [
+            error?.message,
+            String(error?.stdout || ''),
+            String(error?.stderr || ''),
+        ].join(' ');
+        if (errorMsg.match(/limit reached|usage limit/i)) {
+            limitReached = true;
+            const resetMatch = errorMsg.match(/resets? in ([a-zA-Z0-9 ]+)/i);
+            if (resetMatch) {
+                resetTime = resetMatch[1].trim();
+            }
+        }
+        return {
+            limitReached,
+            resetTime,
+            message: limitReached ? errorMsg : undefined,
+        };
+    }
+}
+export async function executeClaudeHeadless(config, prompt, logDir, taskId, signal) {
+    const { command, args } = buildClaudeCommand(config, prompt);
+    await fs.mkdir(logDir, { recursive: true });
+    const rawLogPath = path.join(logDir, `${taskId}-claude-response.json`);
+    try {
+        const result = await execa(command, args, {
+            shell: false,
+            timeout: config.taskTimeoutMs,
+            stdin: 'ignore',
+            stdout: 'pipe',
+            stderr: 'pipe',
+            cancelSignal: signal,
+        });
+        const timestamp = new Date().toISOString();
+        const header = `\n\n--- Claude Execution at ${timestamp} ---\n`;
+        const stdoutRedacted = redactSecrets(result.stdout);
+        await fs.appendFile(rawLogPath, header + stdoutRedacted + '\n', 'utf-8');
+        if (result.stderr) {
+            const stderrLogPath = path.join(logDir, `${taskId}-claude-stderr.log`);
+            await fs.appendFile(stderrLogPath, header + redactSecrets(result.stderr) + '\n', 'utf-8');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: 'Malformed JSON response from Claude',
+                exitCode: result.exitCode,
+            };
+        }
+        if (parsed.is_error) {
+            let sessionLimitReached = false;
+            let limitResetTime;
+            const errorMsg = parsed.result || '';
+            if (errorMsg.match(/limit reached|usage limit/i)) {
+                sessionLimitReached = true;
+                const resetMatch = errorMsg.match(/resets? in ([a-zA-Z0-9 ]+)/i);
+                if (resetMatch) {
+                    limitResetTime = resetMatch[1].trim();
+                }
+            }
+            return {
+                success: false,
+                response: parsed,
+                error: 'Claude execution returned is_error: true',
+                exitCode: result.exitCode,
+                sessionLimitReached,
+                limitResetTime,
+            };
+        }
+        if (!parsed.result) {
+            return {
+                success: false,
+                response: parsed,
+                error: 'Claude execution missing required result field',
+                exitCode: result.exitCode,
+            };
+        }
+        const sentinel = extractOrchestratorResult(parsed.result);
+        if (!sentinel) {
+            return {
+                success: false,
+                response: parsed,
+                error: 'Missing required ORCHESTRATOR_RESULT sentinel',
+                exitCode: result.exitCode,
+                sentinel: null,
+            };
+        }
+        return {
+            success: true,
+            response: parsed,
+            exitCode: result.exitCode,
+            sentinel,
+        };
+    }
+    catch (error) {
+        const timestamp = new Date().toISOString();
+        const header = `\n\n--- Claude Execution at ${timestamp} ---\n`;
+        if (error.stdout) {
+            await fs.appendFile(rawLogPath, header + redactSecrets(String(error.stdout)) + '\n', 'utf-8');
+        }
+        if (error.stderr) {
+            const stderrLogPath = path.join(logDir, `${taskId}-claude-stderr.log`);
+            await fs.appendFile(stderrLogPath, header + redactSecrets(String(error.stderr)) + '\n', 'utf-8');
+        }
+        if (error.isCanceled || error.signal === 'SIGINT') {
+            return {
+                success: false,
+                error: 'Execution interrupted by user',
+                exitCode: error.exitCode ?? null,
+                interrupted: true,
+            };
+        }
+        let parsed;
+        if (error.stdout) {
+            try {
+                parsed = JSON.parse(String(error.stdout));
+            }
+            catch (e) {
+                // ignore
+            }
+        }
+        let sessionLimitReached = false;
+        let limitResetTime;
+        const errorMsg = [
+            error?.message,
+            String(error?.stdout || ''),
+            String(error?.stderr || ''),
+        ].join(' ');
+        if (errorMsg.match(/limit reached|usage limit/i)) {
+            sessionLimitReached = true;
+            const resetMatch = errorMsg.match(/resets? in ([a-zA-Z0-9 ]+)/i);
+            if (resetMatch) {
+                limitResetTime = resetMatch[1].trim();
+            }
+        }
+        return {
+            success: false,
+            response: parsed,
+            error: error.message || 'Claude execution failed',
+            exitCode: error.exitCode ?? null,
+            sessionLimitReached,
+            limitResetTime,
+        };
+    }
+}

package/dist/executor/parser.js

@@ -0,0 +1,33 @@
+export function parseClaudeJSON(output) {
+    try {
+        const parsed = JSON.parse(output);
+        if (!parsed || typeof parsed !== 'object') {
+            throw new Error('Claude JSON output must be an object');
+        }
+        // We expect some basic fields, mainly `result`.
+        if (typeof parsed.result !== 'string') {
+            throw new Error('Claude JSON output must contain a string "result" field');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`Failed to parse Claude JSON response: ${error.message}`);
+    }
+}
+export function extractOrchestratorResult(resultString) {
+    const match = resultString.match(/ORCHESTRATOR_RESULT:\s*(SUCCESS|BLOCKED|NEEDS_RETRY_CONTEXT)/);
+    if (!match) {
+        return null;
+    }
+    const type = match[1];
+    const handoffNotes = resultString.substring(0, match.index).trim() || undefined;
+    if (type === 'BLOCKED') {
+        const reasonMatch = resultString.match(/BLOCKED_REASON:\s*(.+)$/m);
+        return {
+            type: 'BLOCKED',
+            reason: reasonMatch ? reasonMatch[1].trim() : 'Unknown block reason',
+            handoffNotes,
+        };
+    }
+    return { type, handoffNotes };
+}

package/dist/executor/policy.js

@@ -0,0 +1,64 @@
+export class PolicyViolationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PolicyViolationError';
+    }
+}
+/**
+ * Validates a verification command against the security policy.
+ * Throws PolicyViolationError if the command is unsafe.
+ */
+export function validateVerificationCommand(config, cmd) {
+    const DENIED_COMMANDS = ['rm', 'rmdir', 'chmod', 'chown', 'kill', 'pkill', 'killall'];
+    const deniedList = new Set([...DENIED_COMMANDS, ...(config.security?.deniedCommands || [])]);
+    // Strip potential paths to get the base executable name
+    const commandParts = cmd.command.split('/');
+    const baseCommand = commandParts[commandParts.length - 1];
+    if (deniedList.has(baseCommand)) {
+        throw new PolicyViolationError(`Command '${baseCommand}' is in the denylist.`);
+    }
+    // Block destructive Git commands regardless of config
+    if (baseCommand === 'git') {
+        const destructiveGitArgs = [
+            'reset',
+            'clean',
+            'push',
+            'rebase',
+            'commit',
+            'checkout',
+            'branch',
+            'rm',
+            'amend',
+        ];
+        // Check if any argument is a destructive command
+        // (A naive check, but sufficient for MVP safety given we don't expect git to be used as a verification command anyway)
+        if (cmd.args.some((arg) => destructiveGitArgs.includes(arg))) {
+            throw new PolicyViolationError(`Destructive git operations are blocked.`);
+        }
+    }
+    // Block shell fragments, inline command chains, redirection, command substitution, and environment interpolation
+    const SHELL_CHARACTERS = /[&|<>;$()`\n]/;
+    if (SHELL_CHARACTERS.test(cmd.command)) {
+        throw new PolicyViolationError(`Shell fragments and operators are not allowed in command executables.`);
+    }
+    for (const arg of cmd.args) {
+        if (SHELL_CHARACTERS.test(arg)) {
+            throw new PolicyViolationError(`Shell fragments and operators are not allowed in command arguments.`);
+        }
+    }
+    // Require explicit user confirmation for any command outside the allowlist
+    if (config.security?.allowedCommands && config.security.allowedCommands.length > 0) {
+        if (!config.security.allowedCommands.includes(baseCommand)) {
+            throw new PolicyViolationError(`Command '${baseCommand}' is not in the allowedCommands list. Explicit user confirmation is required.`);
+        }
+    }
+}
+/**
+ * Validates Claude permission mode and allowed tools before execution.
+ * Throws PolicyViolationError if settings are unsafe.
+ */
+export function validateClaudePermissions(config) {
+    if (config.claude?.extraSafeArgs?.includes('--dangerously-skip-permissions')) {
+        throw new PolicyViolationError(`'--dangerously-skip-permissions' is not allowed for normal execution.`);
+    }
+}

package/dist/executor/state.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function loadPlanState(planId, config) {
+    const stateDir = path.resolve(process.cwd(), config.stateDir);
+    const stateFile = path.join(stateDir, `${planId}.json`);
+    try {
+        const existing = await fs.readFile(stateFile, 'utf-8');
+        return JSON.parse(existing);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT') {
+            console.warn(`Warning: Failed to parse state file for plan ${planId}: ${e.message}`);
+        }
+        return { planId, tasks: {} };
+    }
+}
+export async function savePlanState(state, config) {
+    const stateDir = path.resolve(process.cwd(), config.stateDir);
+    await fs.mkdir(stateDir, { recursive: true });
+    const stateFile = path.join(stateDir, `${state.planId}.json`);
+    await fs.writeFile(stateFile, JSON.stringify(state, null, 2), 'utf-8');
+}
+export function getTaskState(state, taskId) {
+    if (!state.tasks[taskId]) {
+        state.tasks[taskId] = {
+            id: taskId,
+            attempts: 0,
+            lastStatus: 'NOT_DONE',
+            logFilePaths: [],
+            claudeExitCodes: [],
+            jsonResponsePaths: [],
+            verificationResults: [],
+        };
+    }
+    return state.tasks[taskId];
+}

package/dist/executor/verification.js

@@ -0,0 +1,101 @@
+import { execa } from 'execa';
+import { resolve, isAbsolute } from 'path';
+import * as fs from 'fs/promises';
+import { validateVerificationCommand } from './policy.js';
+export async function runVerification(config, taskWorktreePath, logDir) {
+    if (!config.verificationCommands || config.verificationCommands.length === 0) {
+        return null;
+    }
+    try {
+        await fs.mkdir(logDir, { recursive: true });
+    }
+    catch {
+        // ignore
+    }
+    let totalDurationMs = 0;
+    let lastStdoutPath = '';
+    let lastStderrPath = '';
+    for (let i = 0; i < config.verificationCommands.length; i++) {
+        const cmd = config.verificationCommands[i];
+        validateVerificationCommand(config, cmd);
+        let cwd = taskWorktreePath;
+        if (cmd.cwd) {
+            cwd = isAbsolute(cmd.cwd) ? cmd.cwd : resolve(taskWorktreePath, cmd.cwd);
+            if (!cwd.startsWith(resolve(taskWorktreePath))) {
+                return {
+                    success: false,
+                    durationMs: 0,
+                    errorOutput: `Command cwd ${cwd} escapes task worktree ${taskWorktreePath}`,
+                    exitCode: 1,
+                    stdoutPath: '',
+                    stderrPath: '',
+                };
+            }
+        }
+        const stdoutPath = resolve(logDir, `verification_${i}_stdout.log`);
+        const stderrPath = resolve(logDir, `verification_${i}_stderr.log`);
+        lastStdoutPath = stdoutPath;
+        lastStderrPath = stderrPath;
+        const timestamp = new Date().toISOString();
+        const header = `\n\n--- Verification Command: ${cmd.command} ${cmd.args.join(' ')} at ${timestamp} ---\n`;
+        await fs.appendFile(stdoutPath, header);
+        await fs.appendFile(stderrPath, header);
+        const startTime = Date.now();
+        let exitCode = null;
+        let success = false;
+        let errorOutput = '';
+        try {
+            const subprocess = execa(cmd.command, cmd.args, {
+                cwd,
+                env: { ...process.env, ...cmd.env },
+                shell: false,
+                timeout: cmd.timeoutMs,
+            });
+            subprocess.stdout?.on('data', (chunk) => {
+                const text = redactSecrets(chunk.toString());
+                fs.appendFile(stdoutPath, text).catch(() => { });
+            });
+            subprocess.stderr?.on('data', (chunk) => {
+                const text = redactSecrets(chunk.toString());
+                fs.appendFile(stderrPath, text).catch(() => { });
+            });
+            const result = await subprocess;
+            exitCode = result.exitCode ?? null;
+            success = true;
+        }
+        catch (error) {
+            exitCode = error.exitCode ?? null;
+            success = !!cmd.allowFailure;
+            errorOutput = redactSecrets(error.stderr || error.message || String(error));
+        }
+        const durationMs = Date.now() - startTime;
+        const footer = `\n--- Exit Code: ${exitCode}, Duration: ${durationMs}ms ---\n`;
+        await fs.appendFile(stdoutPath, footer).catch(() => { });
+        await fs.appendFile(stderrPath, footer).catch(() => { });
+        totalDurationMs += durationMs;
+        if (!success) {
+            return {
+                success: false,
+                durationMs: totalDurationMs,
+                errorOutput,
+                exitCode,
+                stdoutPath,
+                stderrPath,
+                command: `${cmd.command} ${cmd.args.join(' ')}`.trim(),
+            };
+        }
+    }
+    return {
+        success: true,
+        durationMs: totalDurationMs,
+        stdoutPath: lastStdoutPath,
+        stderrPath: lastStderrPath,
+    };
+}
+export function redactSecrets(text) {
+    // Redact potential secrets.
+    let redacted = text;
+    redacted = redacted.replace(/((?:password|secret|token|key|api_key|auth)[=:]\s*['"]?)[^\s'"]+(['"]?)/gi, '$1***$2');
+    redacted = redacted.replace(/((?:bearer)\s+)[^\s"']+/gi, '$1***');
+    return redacted;
+}

package/dist/git/branch.js

@@ -0,0 +1,82 @@
+import { execa } from 'execa';
+import { isCancel, text, select, confirm } from '@clack/prompts';
+/**
+ * Sanitizes a string to be a valid git branch name.
+ * Replaces invalid characters with hyphens and removes consecutive hyphens.
+ */
+export function sanitizeBranchName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9/]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Checks if the current git repository has uncommitted changes.
+ */
+export async function hasUncommittedChanges(cwd = process.cwd()) {
+    try {
+        const { stdout } = await execa('git', ['status', '--porcelain'], { cwd });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Prompts the user for a branch name with a default derived from the plan name.
+ */
+export async function promptForBranchName(defaultName) {
+    const sanitizedDefault = sanitizeBranchName(defaultName);
+    const branchName = await text({
+        message: 'What should we name the branch for this plan?',
+        initialValue: sanitizedDefault,
+        validate: (value) => {
+            if (!value)
+                return 'Branch name is required';
+            const sanitized = sanitizeBranchName(value);
+            if (value !== sanitized)
+                return `Invalid characters. Try: ${sanitized}`;
+        }
+    });
+    if (isCancel(branchName)) {
+        throw new Error('Operation cancelled');
+    }
+    return branchName;
+}
+/**
+ * Prompts the user on how to handle a dirty working tree.
+ */
+export async function promptForDirtyWorktree() {
+    const action = await select({
+        message: 'The working tree has uncommitted changes. How would you like to proceed?',
+        options: [
+            { value: 'continue', label: 'Continue on current branch (keep changes)' },
+            { value: 'branch', label: 'Create a new branch with these changes' },
+            { value: 'halt', label: 'Halt execution' },
+        ]
+    });
+    if (isCancel(action)) {
+        return 'halt';
+    }
+    return action;
+}
+/**
+ * Prompts to confirm the base branch.
+ */
+export async function confirmBaseBranch(baseBranch) {
+    const isConfirmed = await confirm({
+        message: `Use '${baseBranch}' as the base branch?`,
+        initialValue: true,
+    });
+    if (isCancel(isConfirmed)) {
+        throw new Error('Operation cancelled');
+    }
+    return isConfirmed;
+}
+/**
+ * Creates and checks out a new branch.
+ */
+export async function createAndCheckoutBranch(branchName, cwd = process.cwd()) {
+    await execa('git', ['checkout', '-b', branchName], { cwd });
+}

package/dist/git/commit.js

@@ -0,0 +1,47 @@
+import { execa } from 'execa';
+/**
+ * Stages all changes in the given directory using `git add -A`.
+ */
+export async function stageAllChanges(cwd = process.cwd()) {
+    await execa('git', ['add', '-A'], { cwd });
+}
+/**
+ * Checks if there are any staged changes ready to be committed.
+ */
+export async function hasStagedChanges(cwd = process.cwd()) {
+    try {
+        const { exitCode } = await execa('git', ['diff', '--cached', '--quiet'], { cwd, reject: false });
+        return exitCode === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Creates a commit with the specified message.
+ * Returns the commit hash.
+ */
+export async function createCommit(message, cwd = process.cwd()) {
+    await execa('git', ['commit', '-m', message], { cwd });
+    return getLatestCommitHash(cwd);
+}
+/**
+ * Returns the hash of the latest commit.
+ */
+export async function getLatestCommitHash(cwd = process.cwd()) {
+    const { stdout } = await execa('git', ['rev-parse', 'HEAD'], { cwd });
+    return stdout.trim();
+}
+/**
+ * Formats a commit message using the template and variables.
+ */
+export function formatCommitMessage(template, vars = {}) {
+    let msg = template;
+    if (vars.planName)
+        msg = msg.replace(/\{planName\}/g, vars.planName);
+    if (vars.taskId)
+        msg = msg.replace(/\{taskId\}/g, vars.taskId);
+    if (vars.taskText)
+        msg = msg.replace(/\{taskText\}/g, vars.taskText);
+    return msg;
+}

package/dist/git/repo.js

@@ -0,0 +1,55 @@
+import { execa } from 'execa';
+/**
+ * Checks whether the specified directory is within a Git repository.
+ */
+export async function isGitRepository(cwd = process.cwd()) {
+    try {
+        const { exitCode } = await execa('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd,
+            reject: false,
+        });
+        return exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Initializes a new Git repository in the specified directory.
+ */
+export async function initializeGitRepository(cwd = process.cwd()) {
+    await execa('git', ['init'], { cwd });
+}
+/**
+ * Gets all local branches in the Git repository.
+ */
+export async function getAvailableBranches(cwd = process.cwd()) {
+    try {
+        const { stdout } = await execa('git', ['branch', '--format=%(refname:short)'], { cwd });
+        return stdout
+            .split('\n')
+            .map((b) => b.trim())
+            .filter((b) => b.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolves the default branch. If the configured default branch exists, returns it.
+ * Otherwise, falls back to common branch names or the first available branch.
+ * If no branches exist, returns the configured default.
+ */
+export async function resolveDefaultBranch(configDefaultBranch, cwd = process.cwd()) {
+    const branches = await getAvailableBranches(cwd);
+    if (branches.includes(configDefaultBranch)) {
+        return configDefaultBranch;
+    }
+    if (branches.includes('main'))
+        return 'main';
+    if (branches.includes('master'))
+        return 'master';
+    if (branches.length > 0)
+        return branches[0];
+    return configDefaultBranch;
+}