sidecar-cli 0.1.2 → 0.1.3-beta.1

package/dist/prompts/prompt-compiler.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { nowIso } from '../lib/format.js';
+import { getSidecarPaths } from '../lib/paths.js';
+function section(title, lines) {
+    return [`## ${title}`, ...lines, ''].join('\n');
+}
+function bullets(items, empty = '- none') {
+    if (items.length === 0)
+        return [empty];
+    return items.map((item) => `- ${item}`);
+}
+function finalResponseFormat(runner) {
+    if (runner === 'codex') {
+        return [
+            '- Start with a one-line outcome summary.',
+            '- List files changed with concise reasons.',
+            '- Include validation commands run and their results.',
+            '- Note risks, blockers, or follow-up tasks.',
+        ];
+    }
+    return [
+        '- Use a brief plan -> implementation -> summary structure.',
+        '- Call out assumptions and tradeoffs explicitly.',
+        '- List changed files and validation results.',
+        '- End with remaining risks and next steps if any.',
+    ];
+}
+function runnerGuidance(runner) {
+    if (runner === 'codex') {
+        return [
+            'Work directly in this repository and keep changes tightly scoped to the task.',
+            'Prefer existing project helpers and patterns over introducing new abstractions.',
+            'Keep final reporting concise and implementation-focused.',
+        ];
+    }
+    return [
+        'Begin with a short plan, then execute changes in small coherent steps.',
+        'Explain implementation choices and tradeoffs briefly as you go.',
+        'Provide a clear summary with validation and follow-up notes at the end.',
+    ];
+}
+export function compilePromptMarkdown(input) {
+    const { task, run, runner, agentRole, linkedContext } = input;
+    const lines = [];
+    lines.push('# Sidecar Execution Brief');
+    lines.push('');
+    lines.push(`Runner: ${runner}`);
+    lines.push(`Agent role: ${agentRole}`);
+    lines.push(`Run id: ${run.run_id}`);
+    lines.push(`Task id: ${task.task_id}`);
+    lines.push(`Compiled at: ${nowIso()}`);
+    lines.push('');
+    lines.push(section('Task', [
+        `- ${task.title}`,
+        `- Type: ${task.type}`,
+        `- Priority: ${task.priority}`,
+        `- Status: ${task.status}`,
+    ]));
+    lines.push(section('Objective', [task.goal]));
+    lines.push(section('Why this matters', [task.summary]));
+    lines.push(section('In scope', bullets(task.scope.in_scope)));
+    lines.push(section('Out of scope', bullets(task.scope.out_of_scope)));
+    lines.push(section('Read these first', bullets(task.implementation.files_to_read)));
+    lines.push(section('Avoid changing', bullets(task.implementation.files_to_avoid)));
+    const relatedDecisions = linkedContext?.related_decisions ?? task.context.related_decisions;
+    const relatedNotes = linkedContext?.related_notes ?? task.context.related_notes;
+    lines.push(section('Linked context', [
+        ...bullets(relatedDecisions, '- no related decisions'),
+        ...bullets(relatedNotes, '- no related notes'),
+    ]));
+    lines.push(section('Constraints', [
+        ...bullets(task.constraints.technical, '- no technical constraints'),
+        ...bullets(task.constraints.design, '- no design constraints'),
+    ]));
+    lines.push(section('Validation', bullets(task.execution.commands.validation)));
+    lines.push(section('Definition of done', bullets(task.definition_of_done)));
+    lines.push(section('Runner guidance', runnerGuidance(runner)));
+    lines.push(section('Final response format', finalResponseFormat(runner)));
+    return `${lines.join('\n').trim()}\n`;
+}
+export function saveCompiledPrompt(rootPath, runId, markdown) {
+    const promptsPath = getSidecarPaths(rootPath).promptsPath;
+    fs.mkdirSync(promptsPath, { recursive: true });
+    const promptPath = path.join(promptsPath, `${runId}.md`);
+    fs.writeFileSync(promptPath, markdown, 'utf8');
+    return promptPath;
+}

package/dist/prompts/prompt-service.js

@@ -0,0 +1,35 @@
+import { createRunRecordEntry, updateRunRecordEntry } from '../runs/run-service.js';
+import { getTaskPacket } from '../tasks/task-service.js';
+import { compilePromptMarkdown, saveCompiledPrompt } from './prompt-compiler.js';
+export function compileTaskPrompt(input) {
+    const task = getTaskPacket(input.rootPath, input.taskId);
+    const created = createRunRecordEntry(input.rootPath, {
+        task_id: task.task_id,
+        runner_type: input.runner,
+        agent_role: input.agentRole,
+        status: 'preparing',
+        branch: task.tracking.branch,
+        worktree: task.tracking.worktree,
+    });
+    const promptMarkdown = compilePromptMarkdown({
+        task,
+        run: created.run,
+        runner: input.runner,
+        agentRole: input.agentRole,
+        linkedContext: input.linkedContext,
+    });
+    const promptPath = saveCompiledPrompt(input.rootPath, created.run.run_id, promptMarkdown);
+    updateRunRecordEntry(input.rootPath, created.run.run_id, {
+        status: 'queued',
+        prompt_path: promptPath,
+        summary: `Compiled prompt for task ${task.task_id}`,
+    });
+    return {
+        run_id: created.run.run_id,
+        task_id: task.task_id,
+        runner_type: input.runner,
+        agent_role: input.agentRole,
+        prompt_path: promptPath,
+        prompt_markdown: promptMarkdown,
+    };
+}

package/dist/runners/claude-runner.js

@@ -0,0 +1,38 @@
+export class ClaudeRunnerAdapter {
+    runner = 'claude';
+    prepare(input) {
+        const args = ['run', '--prompt-file', input.promptPath, '--role', input.agentRole];
+        return {
+            command: 'claude',
+            args,
+            shellLine: `claude ${args.join(' ')}`,
+        };
+    }
+    execute(input) {
+        if (input.dryRun) {
+            return {
+                ok: true,
+                executed: false,
+                exitCode: 0,
+                summary: 'Dry run: prepared Claude command only.',
+                commandsRun: [input.prepared.shellLine],
+                validationResults: ['dry-run'],
+                blockers: [],
+                followUps: [],
+            };
+        }
+        return {
+            ok: true,
+            executed: false,
+            exitCode: 0,
+            summary: 'Prepared Claude command. Live execution is placeholder behavior in v1.',
+            commandsRun: [input.prepared.shellLine],
+            validationResults: ['runner execute placeholder'],
+            blockers: [],
+            followUps: ['Integrate real Claude command execution in runner adapter.'],
+        };
+    }
+    collectResult(result) {
+        return result;
+    }
+}

package/dist/runners/codex-runner.js

@@ -0,0 +1,38 @@
+export class CodexRunnerAdapter {
+    runner = 'codex';
+    prepare(input) {
+        const args = ['run', '--prompt-file', input.promptPath, '--role', input.agentRole];
+        return {
+            command: 'codex',
+            args,
+            shellLine: `codex ${args.join(' ')}`,
+        };
+    }
+    execute(input) {
+        if (input.dryRun) {
+            return {
+                ok: true,
+                executed: false,
+                exitCode: 0,
+                summary: 'Dry run: prepared Codex command only.',
+                commandsRun: [input.prepared.shellLine],
+                validationResults: ['dry-run'],
+                blockers: [],
+                followUps: [],
+            };
+        }
+        return {
+            ok: true,
+            executed: false,
+            exitCode: 0,
+            summary: 'Prepared Codex command. Live execution is placeholder behavior in v1.',
+            commandsRun: [input.prepared.shellLine],
+            validationResults: ['runner execute placeholder'],
+            blockers: [],
+            followUps: ['Integrate real Codex command execution in runner adapter.'],
+        };
+    }
+    collectResult(result) {
+        return result;
+    }
+}

package/dist/runners/config.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import { getSidecarPaths } from '../lib/paths.js';
+const DEFAULTS = {
+    default_runner: 'codex',
+    preferred_runners: ['codex', 'claude'],
+    default_agent_role: 'builder-app',
+};
+export function loadRunnerPreferences(rootPath) {
+    const prefsPath = getSidecarPaths(rootPath).preferencesPath;
+    if (!fs.existsSync(prefsPath))
+        return DEFAULTS;
+    try {
+        const raw = JSON.parse(fs.readFileSync(prefsPath, 'utf8'));
+        const defaultRunner = raw.runner?.defaultRunner;
+        const preferredRunners = raw.runner?.preferredRunners;
+        const defaultAgentRole = raw.runner?.defaultAgentRole;
+        return {
+            default_runner: defaultRunner === 'codex' || defaultRunner === 'claude' ? defaultRunner : DEFAULTS.default_runner,
+            preferred_runners: Array.isArray(preferredRunners) && preferredRunners.every((r) => r === 'codex' || r === 'claude')
+                ? preferredRunners
+                : DEFAULTS.preferred_runners,
+            default_agent_role: (() => {
+                if (defaultAgentRole === 'builder')
+                    return 'builder-app';
+                if (defaultAgentRole === 'planner' ||
+                    defaultAgentRole === 'builder-ui' ||
+                    defaultAgentRole === 'builder-app' ||
+                    defaultAgentRole === 'reviewer' ||
+                    defaultAgentRole === 'tester') {
+                    return defaultAgentRole;
+                }
+                return DEFAULTS.default_agent_role;
+            })(),
+        };
+    }
+    catch {
+        return DEFAULTS;
+    }
+}

package/dist/runners/factory.js

@@ -0,0 +1,10 @@
+import { SidecarError } from '../lib/errors.js';
+import { CodexRunnerAdapter } from './codex-runner.js';
+import { ClaudeRunnerAdapter } from './claude-runner.js';
+export function getRunnerAdapter(runner) {
+    if (runner === 'codex')
+        return new CodexRunnerAdapter();
+    if (runner === 'claude')
+        return new ClaudeRunnerAdapter();
+    throw new SidecarError(`Unsupported runner: ${runner}`);
+}

package/dist/runners/runner-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/runs/run-record.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { nowIso } from '../lib/format.js';
+export const RUN_RECORD_VERSION = '1.0';
+export const runIdSchema = z.string().regex(/^R-\d{3,}$/, 'Run id must look like R-001');
+export const runStatusSchema = z.enum(['queued', 'preparing', 'running', 'review', 'blocked', 'completed', 'failed']);
+export const runnerTypeSchema = z.enum(['codex', 'claude']);
+export const runReviewStateSchema = z.enum(['pending', 'approved', 'needs_changes', 'blocked', 'merged']);
+export const runRecordSchema = z
+    .object({
+    version: z.string().default(RUN_RECORD_VERSION),
+    run_id: runIdSchema,
+    task_id: z.string().regex(/^T-\d{3,}$/, 'task_id must look like T-001'),
+    runner_type: runnerTypeSchema,
+    agent_role: z.string().min(1, 'agent_role is required'),
+    status: runStatusSchema,
+    branch: z.string().default(''),
+    worktree: z.string().default(''),
+    prompt_path: z.string().default(''),
+    started_at: z.string().datetime({ offset: true }),
+    completed_at: z.string().datetime({ offset: true }).nullable().default(null),
+    summary: z.string().default(''),
+    changed_files: z.array(z.string()).default([]),
+    commands_run: z.array(z.string()).default([]),
+    validation_results: z.array(z.string()).default([]),
+    blockers: z.array(z.string()).default([]),
+    follow_ups: z.array(z.string()).default([]),
+    review_state: runReviewStateSchema.default('pending'),
+    reviewed_at: z.string().datetime({ offset: true }).nullable().default(null),
+    reviewed_by: z.string().default(''),
+    review_note: z.string().default(''),
+})
+    .strict();
+export const runRecordCreateInputSchema = runRecordSchema
+    .omit({ run_id: true, version: true })
+    .partial({
+    status: true,
+    branch: true,
+    worktree: true,
+    prompt_path: true,
+    started_at: true,
+    completed_at: true,
+    summary: true,
+    changed_files: true,
+    commands_run: true,
+    validation_results: true,
+    blockers: true,
+    follow_ups: true,
+    review_state: true,
+    reviewed_at: true,
+    reviewed_by: true,
+    review_note: true,
+});
+export const runRecordUpdateInputSchema = z
+    .object({
+    status: runStatusSchema.optional(),
+    branch: z.string().optional(),
+    worktree: z.string().optional(),
+    prompt_path: z.string().optional(),
+    completed_at: z.string().datetime({ offset: true }).nullable().optional(),
+    summary: z.string().optional(),
+    changed_files: z.array(z.string()).optional(),
+    commands_run: z.array(z.string()).optional(),
+    validation_results: z.array(z.string()).optional(),
+    blockers: z.array(z.string()).optional(),
+    follow_ups: z.array(z.string()).optional(),
+    review_state: runReviewStateSchema.optional(),
+    reviewed_at: z.string().datetime({ offset: true }).nullable().optional(),
+    reviewed_by: z.string().optional(),
+    review_note: z.string().optional(),
+})
+    .strict();
+export function createRunRecord(runId, input) {
+    const normalized = {
+        version: RUN_RECORD_VERSION,
+        run_id: runId,
+        task_id: input.task_id,
+        runner_type: input.runner_type,
+        agent_role: input.agent_role,
+        status: input.status ?? 'queued',
+        branch: input.branch ?? '',
+        worktree: input.worktree ?? '',
+        prompt_path: input.prompt_path ?? '',
+        started_at: input.started_at ?? nowIso(),
+        completed_at: input.completed_at ?? null,
+        summary: input.summary ?? '',
+        changed_files: input.changed_files ?? [],
+        commands_run: input.commands_run ?? [],
+        validation_results: input.validation_results ?? [],
+        blockers: input.blockers ?? [],
+        follow_ups: input.follow_ups ?? [],
+        review_state: input.review_state ?? 'pending',
+        reviewed_at: input.reviewed_at ?? null,
+        reviewed_by: input.reviewed_by ?? '',
+        review_note: input.review_note ?? '',
+    };
+    return runRecordSchema.parse(normalized);
+}

package/dist/runs/run-repository.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSidecarPaths } from '../lib/paths.js';
+import { SidecarError } from '../lib/errors.js';
+import { stringifyJson } from '../lib/format.js';
+import { createRunRecord, runRecordCreateInputSchema, runRecordSchema, runRecordUpdateInputSchema, } from './run-record.js';
+function runFilePath(runsPath, runId) {
+    return path.join(runsPath, `${runId}.json`);
+}
+function parseRunOrdinal(runId) {
+    const match = /^R-(\d+)$/.exec(runId);
+    return match ? Number.parseInt(match[1], 10) : 0;
+}
+export class RunRecordRepository {
+    rootPath;
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+    }
+    get runsPath() {
+        return getSidecarPaths(this.rootPath).runsPath;
+    }
+    ensureStorage() {
+        fs.mkdirSync(this.runsPath, { recursive: true });
+    }
+    generateNextRunId() {
+        this.ensureStorage();
+        const files = fs.readdirSync(this.runsPath, { withFileTypes: true });
+        let max = 0;
+        for (const file of files) {
+            if (!file.isFile() || !file.name.endsWith('.json'))
+                continue;
+            const id = file.name.slice(0, -'.json'.length);
+            max = Math.max(max, parseRunOrdinal(id));
+        }
+        return `R-${String(max + 1).padStart(3, '0')}`;
+    }
+    create(input) {
+        const parsed = runRecordCreateInputSchema.parse(input);
+        const runId = this.generateNextRunId();
+        const run = createRunRecord(runId, parsed);
+        const filePath = runFilePath(this.runsPath, runId);
+        fs.writeFileSync(filePath, `${stringifyJson(run)}\n`, 'utf8');
+        return { run, path: filePath };
+    }
+    update(runId, patch) {
+        const existing = this.get(runId);
+        const parsedPatch = runRecordUpdateInputSchema.parse(patch);
+        const merged = {
+            ...existing,
+            ...parsedPatch,
+            changed_files: parsedPatch.changed_files ?? existing.changed_files,
+            commands_run: parsedPatch.commands_run ?? existing.commands_run,
+            validation_results: parsedPatch.validation_results ?? existing.validation_results,
+            blockers: parsedPatch.blockers ?? existing.blockers,
+            follow_ups: parsedPatch.follow_ups ?? existing.follow_ups,
+        };
+        const validated = runRecordSchema.parse(merged);
+        const filePath = runFilePath(this.runsPath, runId);
+        fs.writeFileSync(filePath, `${stringifyJson(validated)}\n`, 'utf8');
+        return validated;
+    }
+    get(runId) {
+        const filePath = runFilePath(this.runsPath, runId);
+        if (!fs.existsSync(filePath)) {
+            throw new SidecarError(`Run not found: ${runId}`);
+        }
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            return runRecordSchema.parse(raw);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new SidecarError(`Invalid run record at ${filePath}: ${message}`);
+        }
+    }
+    list() {
+        this.ensureStorage();
+        const files = fs
+            .readdirSync(this.runsPath, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map((entry) => path.join(this.runsPath, entry.name))
+            .sort();
+        const runs = [];
+        for (const filePath of files) {
+            try {
+                const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+                runs.push(runRecordSchema.parse(raw));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new SidecarError(`Invalid run record at ${filePath}: ${message}`);
+            }
+        }
+        return runs;
+    }
+    listForTask(taskId) {
+        return this.list().filter((run) => run.task_id === taskId);
+    }
+}

package/dist/runs/run-service.js

@@ -0,0 +1,27 @@
+import { RunRecordRepository } from './run-repository.js';
+export function createRunRecordEntry(rootPath, input) {
+    const repo = new RunRecordRepository(rootPath);
+    return repo.create(input);
+}
+export function updateRunRecordEntry(rootPath, runId, patch) {
+    const repo = new RunRecordRepository(rootPath);
+    return repo.update(runId, patch);
+}
+export function getRunRecord(rootPath, runId) {
+    const repo = new RunRecordRepository(rootPath);
+    return repo.get(runId);
+}
+export function listRunRecords(rootPath) {
+    const repo = new RunRecordRepository(rootPath);
+    return repo
+        .list()
+        .slice()
+        .sort((a, b) => b.started_at.localeCompare(a.started_at));
+}
+export function listRunRecordsForTask(rootPath, taskId) {
+    const repo = new RunRecordRepository(rootPath);
+    return repo
+        .listForTask(taskId)
+        .slice()
+        .sort((a, b) => b.started_at.localeCompare(a.started_at));
+}

package/dist/services/capabilities-service.js

@@ -10,6 +10,10 @@ export function getCapabilitiesManifest(version) {
             'event_ingest',
             'export_json',
             'export_jsonl_events',
+            'run_records_v1',
+            'prompt_compiler_v1',
+            'task_orchestration_v1',
+            'run_review_workflow_v1',
             'optional_local_ui',
         ],
         commands: [
@@ -168,25 +172,136 @@ export function getCapabilitiesManifest(version) {
                 options: [],
                 subcommands: [
                     {
-                        name: 'add',
-                        description: 'Create an open task',
+                        name: 'create',
+                        description: 'Create a structured task packet',
                         json_output: true,
-                        arguments: ['<title>'],
-                        options: ['--description <text>', '--priority low|medium|high', '--by human|agent', '--json'],
+                        arguments: [],
+                        options: [
+                            '--title <title>',
+                            '--summary <summary>',
+                            '--goal <goal>',
+                            '--type feature|bug|chore|research',
+                            '--status draft|ready|queued|running|review|blocked|done',
+                            '--priority low|medium|high',
+                            '--dependencies <task-ids>',
+                            '--tags <tags>',
+                            '--target-areas <areas>',
+                            '--scope-in <items>',
+                            '--scope-out <items>',
+                            '--related-decisions <items>',
+                            '--related-notes <items>',
+                            '--files-read <paths>',
+                            '--files-avoid <paths>',
+                            '--constraint-tech <items>',
+                            '--constraint-design <items>',
+                            '--validate-cmds <commands>',
+                            '--dod <items>',
+                            '--branch <name>',
+                            '--worktree <path>',
+                            '--json',
+                        ],
                     },
                     {
-                        name: 'done',
-                        description: 'Mark a task as done',
+                        name: 'show',
+                        description: 'Show a task packet',
                         json_output: true,
                         arguments: ['<task-id>'],
-                        options: ['--by human|agent', '--json'],
+                        options: ['--json'],
                     },
                     {
                         name: 'list',
-                        description: 'List tasks',
+                        description: 'List task packets',
                         json_output: true,
                         arguments: [],
-                        options: ['--status open|done|all', '--format table|json', '--json'],
+                        options: ['--status draft|ready|queued|running|review|blocked|done|all', '--json'],
+                    },
+                    {
+                        name: 'assign',
+                        description: 'Assign task to an agent role and runner',
+                        json_output: true,
+                        arguments: ['<task-id>'],
+                        options: ['--agent-role planner|builder-ui|builder-app|reviewer|tester', '--runner codex|claude', '--json'],
+                    },
+                    {
+                        name: 'create-followup',
+                        description: 'Create follow-up task from run report',
+                        json_output: true,
+                        arguments: ['<run-id>'],
+                        options: ['--json'],
+                    },
+                ],
+            },
+            {
+                name: 'prompt',
+                description: 'Prompt compilation operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'compile',
+                        description: 'Compile an execution brief prompt from a task packet',
+                        json_output: true,
+                        arguments: ['<task-id>'],
+                        options: ['--runner codex|claude', '--agent-role <role>', '--preview', '--json'],
+                    },
+                ],
+            },
+            {
+                name: 'run',
+                description: 'Execute a task run or inspect run records',
+                json_output: true,
+                arguments: ['[task-id]'],
+                options: ['--runner codex|claude', '--agent-role planner|builder-ui|builder-app|reviewer|tester', '--dry-run', '--json'],
+                subcommands: [
+                    {
+                        name: 'queue',
+                        description: 'Queue ready tasks with satisfied dependencies',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--json'],
+                    },
+                    {
+                        name: 'start-ready',
+                        description: 'Queue and start all runnable ready tasks',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--dry-run', '--json'],
+                    },
+                    {
+                        name: 'approve',
+                        description: 'Review run as approved, needs changes, or merged',
+                        json_output: true,
+                        arguments: ['<run-id>'],
+                        options: ['--state approved|needs_changes|merged', '--note <text>', '--by <name>', '--json'],
+                    },
+                    {
+                        name: 'block',
+                        description: 'Mark run blocked',
+                        json_output: true,
+                        arguments: ['<run-id>'],
+                        options: ['--note <text>', '--by <name>', '--json'],
+                    },
+                    {
+                        name: 'list',
+                        description: 'List run records',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--task <task-id>', '--status queued|preparing|running|review|blocked|completed|failed|all', '--json'],
+                    },
+                    {
+                        name: 'show',
+                        description: 'Show a run record',
+                        json_output: true,
+                        arguments: ['<run-id>'],
+                        options: ['--json'],
+                    },
+                    {
+                        name: 'summary',
+                        description: 'Show project-level run review summary',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--json'],
                     },
                 ],
             },