sidecar-cli 0.1.1 → 0.1.2-beta.1

package/dist/services/capabilities-service.js

@@ -1,10 +1,21 @@
+import { JSON_CONTRACT_VERSION } from '../lib/output.js';
 export function getCapabilitiesManifest(version) {
     return {
-        schema_version: 1,
-        cli: {
-            name: 'sidecar',
-            version,
-        },
+        cli_name: 'sidecar',
+        cli_version: version,
+        json_contract_version: JSON_CONTRACT_VERSION,
+        features: [
+            'json_envelope_v1',
+            'capabilities_manifest',
+            'event_ingest',
+            'export_json',
+            'export_jsonl_events',
+            'run_records_v1',
+            'prompt_compiler_v1',
+            'task_orchestration_v1',
+            'run_review_workflow_v1',
+            'optional_local_ui',
+        ],
         commands: [
             {
                 name: 'init',
@@ -20,6 +31,29 @@ export function getCapabilitiesManifest(version) {
                 arguments: [],
                 options: ['--json'],
             },
+            {
+                name: 'preferences',
+                description: 'Preferences operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'show',
+                        description: 'Show project preferences',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--json'],
+                    },
+                ],
+            },
+            {
+                name: 'ui',
+                description: 'Launch optional local Sidecar UI (lazy-installed on first run)',
+                json_output: false,
+                arguments: [],
+                options: ['--no-open', '--port <port>', '--install-only', '--project <path>', '--reinstall'],
+            },
             {
                 name: 'capabilities',
                 description: 'Show machine-readable CLI manifest',
@@ -34,6 +68,40 @@ export function getCapabilitiesManifest(version) {
                 arguments: [],
                 options: ['--limit <n>', '--format text|markdown|json', '--json'],
             },
+            {
+                name: 'event',
+                description: 'Generic event ingest operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'add',
+                        description: 'Add a validated generic event payload',
+                        json_output: true,
+                        arguments: [],
+                        options: [
+                            '--type <type>',
+                            '--title <title>',
+                            '--summary <summary>',
+                            '--details-json <json>',
+                            '--created-by <by>',
+                            '--source <source>',
+                            '--session-id <id>',
+                            '--json-input <json>',
+                            '--stdin',
+                            '--json',
+                        ],
+                    },
+                ],
+            },
+            {
+                name: 'export',
+                description: 'Export project memory in JSON or JSONL',
+                json_output: true,
+                arguments: [],
+                options: ['--format json|jsonl', '--limit <n>', '--type <event-type>', '--since <iso-date>', '--until <iso-date>', '--output <path>', '--json'],
+            },
             {
                 name: 'summary',
                 description: 'Summary operations',
@@ -104,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: [],
+                        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: 'show',
+                        description: 'Show a task packet',
+                        json_output: true,
+                        arguments: ['<task-id>'],
+                        options: ['--json'],
+                    },
+                    {
+                        name: 'list',
+                        description: 'List task packets',
+                        json_output: true,
+                        arguments: [],
+                        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: ['<title>'],
-                        options: ['--description <text>', '--priority low|medium|high', '--by human|agent', '--json'],
+                        arguments: ['<task-id>'],
+                        options: ['--agent-role planner|builder-ui|builder-app|reviewer|tester', '--runner codex|claude', '--json'],
                     },
                     {
-                        name: 'done',
-                        description: 'Mark a task as done',
+                        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: ['--by human|agent', '--json'],
+                        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 tasks',
+                        description: 'List run records',
                         json_output: true,
                         arguments: [],
-                        options: ['--status open|done|all', '--format table|json', '--json'],
+                        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'],
                     },
                 ],
             },

package/dist/services/event-ingest-service.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { createEvent } from './event-service.js';
+const eventTypeSchema = z.enum([
+    'note',
+    'decision',
+    'worklog',
+    'task_created',
+    'task_completed',
+    'summary_generated',
+]);
+const createdBySchema = z.enum(['human', 'agent', 'system']).default('system');
+const sourceSchema = z.enum(['cli', 'imported', 'generated']).default('cli');
+export const eventIngestSchema = z
+    .object({
+    type: eventTypeSchema,
+    title: z.string().trim().min(1).optional(),
+    summary: z.string().trim().min(1).optional(),
+    details_json: z.record(z.string(), z.unknown()).optional(),
+    created_by: createdBySchema.optional(),
+    source: sourceSchema.optional(),
+    session_id: z.number().int().positive().nullable().optional(),
+})
+    .superRefine((payload, ctx) => {
+    if (payload.type === 'decision') {
+        if (!payload.title)
+            ctx.addIssue({ code: 'custom', path: ['title'], message: 'title is required for decision events' });
+        if (!payload.summary)
+            ctx.addIssue({ code: 'custom', path: ['summary'], message: 'summary is required for decision events' });
+        return;
+    }
+    if (payload.type === 'summary_generated')
+        return;
+    if (!payload.summary) {
+        ctx.addIssue({ code: 'custom', path: ['summary'], message: `summary is required for ${payload.type} events` });
+    }
+});
+export function ingestEvent(db, input) {
+    const payload = eventIngestSchema.parse(input.payload);
+    const title = payload.title ??
+        (payload.type === 'note'
+            ? 'Note'
+            : payload.type === 'worklog'
+                ? 'Worklog entry'
+                : payload.type === 'task_created'
+                    ? 'Task created'
+                    : payload.type === 'task_completed'
+                        ? 'Task completed'
+                        : payload.type === 'summary_generated'
+                            ? 'Summary refreshed'
+                            : 'Event');
+    const summary = payload.summary ?? '';
+    const eventId = createEvent(db, {
+        projectId: input.project_id,
+        type: payload.type,
+        title,
+        summary,
+        details: payload.details_json ?? {},
+        createdBy: payload.created_by ?? 'system',
+        source: payload.source ?? 'cli',
+        sessionId: payload.session_id ?? null,
+    });
+    return {
+        id: eventId,
+        type: payload.type,
+        title,
+        summary,
+        details_json: payload.details_json ?? {},
+        created_by: payload.created_by ?? 'system',
+        source: payload.source ?? 'cli',
+        session_id: payload.session_id ?? null,
+    };
+}

package/dist/services/export-service.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { JSON_CONTRACT_VERSION } from '../lib/output.js';
+export function buildExportJson(db, input) {
+    const project = db.prepare('SELECT id, name, root_path, created_at, updated_at FROM projects WHERE id = ?').get(input.projectId);
+    const preferencesPath = path.join(input.rootPath, '.sidecar', 'preferences.json');
+    const preferences = fs.existsSync(preferencesPath)
+        ? JSON.parse(fs.readFileSync(preferencesPath, 'utf8'))
+        : null;
+    const sessions = db
+        .prepare('SELECT id, project_id, started_at, ended_at, actor_type, actor_name, summary FROM sessions WHERE project_id = ? ORDER BY started_at DESC')
+        .all(input.projectId);
+    const tasks = db
+        .prepare(`SELECT id, project_id, title, description, status, priority, created_at, updated_at, closed_at, origin_event_id FROM tasks WHERE project_id = ? ORDER BY CASE WHEN status = 'open' THEN 0 ELSE 1 END, updated_at DESC`)
+        .all(input.projectId);
+    const artifacts = db
+        .prepare('SELECT id, project_id, path, kind, note, created_at FROM artifacts WHERE project_id = ? ORDER BY created_at DESC')
+        .all(input.projectId);
+    const eventWhere = ['project_id = ?'];
+    const eventArgs = [input.projectId];
+    if (input.type) {
+        eventWhere.push('type = ?');
+        eventArgs.push(input.type);
+    }
+    if (input.since) {
+        eventWhere.push('created_at >= ?');
+        eventArgs.push(input.since);
+    }
+    if (input.until) {
+        eventWhere.push('created_at <= ?');
+        eventArgs.push(input.until);
+    }
+    const limitClause = input.limit && input.limit > 0 ? ` LIMIT ${Math.floor(input.limit)}` : '';
+    const events = db
+        .prepare(`SELECT id, project_id, type, title, summary, details_json, created_at, created_by, source, session_id
+       FROM events
+       WHERE ${eventWhere.join(' AND ')}
+       ORDER BY created_at DESC${limitClause}`)
+        .all(...eventArgs);
+    return {
+        version: JSON_CONTRACT_VERSION,
+        project,
+        preferences: preferences,
+        sessions: sessions,
+        tasks: tasks,
+        artifacts: artifacts,
+        events,
+    };
+}
+export function buildExportJsonlEvents(db, input) {
+    const where = ['project_id = ?'];
+    const args = [input.projectId];
+    if (input.type) {
+        where.push('type = ?');
+        args.push(input.type);
+    }
+    if (input.since) {
+        where.push('created_at >= ?');
+        args.push(input.since);
+    }
+    if (input.until) {
+        where.push('created_at <= ?');
+        args.push(input.until);
+    }
+    const limitClause = input.limit && input.limit > 0 ? ` LIMIT ${Math.floor(input.limit)}` : '';
+    const rows = db
+        .prepare(`SELECT id, project_id, type, title, summary, details_json, created_at, created_by, source, session_id
+       FROM events
+       WHERE ${where.join(' AND ')}
+       ORDER BY created_at DESC${limitClause}`)
+        .all(...args);
+    return rows.map((row) => JSON.stringify({ version: JSON_CONTRACT_VERSION, record_type: 'event', project_id: row.project_id, data: row }));
+}
+export function writeOutputFile(outputPath, content) {
+    const abs = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    return abs;
+}

package/dist/services/run-orchestrator-service.js

@@ -0,0 +1,59 @@
+import { nowIso } from '../lib/format.js';
+import { compileTaskPrompt } from '../prompts/prompt-service.js';
+import { getTaskPacket } from '../tasks/task-service.js';
+import { getRunnerAdapter } from '../runners/factory.js';
+import { loadRunnerPreferences } from '../runners/config.js';
+import { updateRunRecordEntry } from '../runs/run-service.js';
+import { saveTaskPacket } from '../tasks/task-service.js';
+export function runTaskExecution(input) {
+    const prefs = loadRunnerPreferences(input.rootPath);
+    const dryRun = Boolean(input.dryRun);
+    const task = getTaskPacket(input.rootPath, input.taskId);
+    const runner = input.runner ?? task.tracking.assigned_runner ?? prefs.default_runner;
+    const agentRole = input.agentRole ?? task.tracking.assigned_agent_role ?? prefs.default_agent_role;
+    const compiled = compileTaskPrompt({
+        rootPath: input.rootPath,
+        taskId: task.task_id,
+        runner,
+        agentRole,
+    });
+    const adapter = getRunnerAdapter(runner);
+    saveTaskPacket(input.rootPath, { ...task, status: 'running' });
+    updateRunRecordEntry(input.rootPath, compiled.run_id, {
+        status: 'running',
+        branch: task.tracking.branch,
+        worktree: task.tracking.worktree || input.rootPath,
+    });
+    const prepared = adapter.prepare({
+        runId: compiled.run_id,
+        taskId: task.task_id,
+        agentRole,
+        promptPath: compiled.prompt_path,
+        projectRoot: input.rootPath,
+    });
+    const executed = adapter.execute({ prepared, dryRun });
+    const collected = adapter.collectResult(executed);
+    const finishedStatus = collected.ok ? 'completed' : 'failed';
+    const nextTaskStatus = collected.ok ? 'review' : 'blocked';
+    saveTaskPacket(input.rootPath, { ...getTaskPacket(input.rootPath, task.task_id), status: nextTaskStatus });
+    updateRunRecordEntry(input.rootPath, compiled.run_id, {
+        status: finishedStatus,
+        completed_at: nowIso(),
+        summary: collected.summary,
+        commands_run: collected.commandsRun,
+        validation_results: collected.validationResults,
+        blockers: collected.blockers,
+        follow_ups: collected.followUps,
+    });
+    return {
+        task_id: task.task_id,
+        run_id: compiled.run_id,
+        runner_type: runner,
+        agent_role: agentRole,
+        prompt_path: compiled.prompt_path,
+        status: finishedStatus,
+        dry_run: dryRun,
+        shell_command: prepared.shellLine,
+        summary: collected.summary,
+    };
+}

package/dist/services/run-review-service.js

@@ -0,0 +1,76 @@
+import { SidecarError } from '../lib/errors.js';
+import { nowIso } from '../lib/format.js';
+import { getRunRecord, listRunRecords, updateRunRecordEntry } from '../runs/run-service.js';
+import { createTaskPacketRecord, getTaskPacket, saveTaskPacket } from '../tasks/task-service.js';
+function taskStatusForReview(state) {
+    if (state === 'approved')
+        return 'review';
+    if (state === 'needs_changes')
+        return 'ready';
+    if (state === 'blocked')
+        return 'blocked';
+    if (state === 'merged')
+        return 'done';
+    return 'review';
+}
+export function reviewRun(rootPath, runId, state, options) {
+    const run = getRunRecord(rootPath, runId);
+    if (run.status !== 'completed' && run.status !== 'failed' && run.status !== 'blocked') {
+        throw new SidecarError('Run must be completed, failed, or blocked before review actions');
+    }
+    updateRunRecordEntry(rootPath, run.run_id, {
+        review_state: state,
+        reviewed_at: nowIso(),
+        reviewed_by: options?.by ?? 'human',
+        review_note: options?.note ?? '',
+    });
+    const task = getTaskPacket(rootPath, run.task_id);
+    const nextTaskStatus = taskStatusForReview(state);
+    saveTaskPacket(rootPath, { ...task, status: nextTaskStatus });
+    return {
+        run_id: run.run_id,
+        task_id: run.task_id,
+        review_state: state,
+        task_status: nextTaskStatus,
+    };
+}
+export function createFollowupTaskFromRun(rootPath, runId) {
+    const run = getRunRecord(rootPath, runId);
+    const sourceTask = getTaskPacket(rootPath, run.task_id);
+    const suggestions = run.follow_ups.length > 0 ? run.follow_ups : ['Investigate run issues and apply required changes'];
+    const created = createTaskPacketRecord(rootPath, {
+        title: `Follow-up: ${sourceTask.title}`,
+        summary: run.review_note || run.summary || 'Follow-up work from reviewed run',
+        goal: suggestions.join('; '),
+        type: sourceTask.type,
+        status: 'draft',
+        priority: sourceTask.priority,
+        dependencies: [sourceTask.task_id],
+        tags: Array.from(new Set([...sourceTask.tags, 'follow-up'])),
+        target_areas: sourceTask.target_areas,
+        files_to_read: sourceTask.implementation.files_to_read,
+        files_to_avoid: sourceTask.implementation.files_to_avoid,
+        technical_constraints: sourceTask.constraints.technical,
+        design_constraints: sourceTask.constraints.design,
+        validation_commands: sourceTask.execution.commands.validation,
+        definition_of_done: [...sourceTask.definition_of_done, ...suggestions],
+    });
+    return {
+        source_run_id: run.run_id,
+        task_id: created.task.task_id,
+        title: created.task.title,
+    };
+}
+export function buildReviewSummary(rootPath) {
+    const runs = listRunRecords(rootPath);
+    return {
+        completed_runs: runs.filter((r) => r.status === 'completed').length,
+        blocked_runs: runs.filter((r) => r.status === 'blocked' || r.review_state === 'blocked').length,
+        suggested_follow_ups: runs.reduce((acc, r) => acc + r.follow_ups.length, 0),
+        recently_merged: runs
+            .filter((r) => r.review_state === 'merged' && r.reviewed_at)
+            .sort((a, b) => String(b.reviewed_at).localeCompare(String(a.reviewed_at)))
+            .slice(0, 10)
+            .map((r) => ({ run_id: r.run_id, task_id: r.task_id, reviewed_at: r.reviewed_at || '' })),
+    };
+}

package/dist/services/task-orchestration-service.js

@@ -0,0 +1,94 @@
+import { nowIso } from '../lib/format.js';
+import { getTaskPacket, listTaskPackets, saveTaskPacket } from '../tasks/task-service.js';
+function hasUiSignal(task) {
+    const joined = [
+        ...task.tags,
+        ...task.target_areas,
+        ...task.implementation.files_to_read,
+        ...task.implementation.files_to_avoid,
+    ]
+        .join(' ')
+        .toLowerCase();
+    return /(ui|frontend|css|html|react|view|component)/.test(joined);
+}
+function pickRole(task) {
+    if (task.type === 'research')
+        return { role: 'planner', reason: 'task type is research' };
+    if (task.tags.some((t) => t.toLowerCase() === 'test') || task.target_areas.some((a) => /test/i.test(a))) {
+        return { role: 'tester', reason: 'tags/target_areas indicate testing' };
+    }
+    if (task.tags.some((t) => /review/i.test(t)) || task.type === 'bug') {
+        return { role: 'reviewer', reason: 'bug/review signal present' };
+    }
+    if (hasUiSignal(task))
+        return { role: 'builder-ui', reason: 'ui/frontend signal detected' };
+    return { role: 'builder-app', reason: 'default app implementation path' };
+}
+function defaultRunnerForRole(role) {
+    if (role === 'reviewer' || role === 'planner')
+        return 'claude';
+    return 'codex';
+}
+export function dependenciesMet(task, tasksById) {
+    const missing = task.dependencies.filter((depId) => tasksById.get(depId)?.status !== 'done');
+    return { ok: missing.length === 0, missing };
+}
+export function assignTask(rootPath, taskId, override) {
+    const task = getTaskPacket(rootPath, taskId);
+    const auto = pickRole(task);
+    const role = override?.role ?? auto.role;
+    const runner = override?.runner ?? defaultRunnerForRole(role);
+    const reason = override?.role || override?.runner ? 'manual override' : auto.reason;
+    const updated = {
+        ...task,
+        tracking: {
+            ...task.tracking,
+            assigned_agent_role: role,
+            assigned_runner: runner,
+            assignment_reason: reason,
+            assigned_at: nowIso(),
+        },
+    };
+    saveTaskPacket(rootPath, updated);
+    return { task_id: task.task_id, agent_role: role, runner, reason };
+}
+export function queueReadyTasks(rootPath) {
+    const tasks = listTaskPackets(rootPath);
+    const byId = new Map(tasks.map((t) => [t.task_id, t]));
+    const decisions = [];
+    for (const task of tasks) {
+        if (task.status !== 'ready')
+            continue;
+        const dep = dependenciesMet(task, byId);
+        if (!dep.ok) {
+            saveTaskPacket(rootPath, { ...task, status: 'blocked' });
+            decisions.push({ task_id: task.task_id, queued: false, reason: `blocked by dependencies: ${dep.missing.join(', ')}` });
+            continue;
+        }
+        const assignment = task.tracking.assigned_agent_role && task.tracking.assigned_runner
+            ? {
+                role: task.tracking.assigned_agent_role,
+                runner: task.tracking.assigned_runner,
+            }
+            : (() => {
+                const decided = assignTask(rootPath, task.task_id);
+                return { role: decided.agent_role, runner: decided.runner };
+            })();
+        const latest = getTaskPacket(rootPath, task.task_id);
+        saveTaskPacket(rootPath, {
+            ...latest,
+            status: 'queued',
+            tracking: {
+                ...latest.tracking,
+                assigned_agent_role: assignment.role,
+                assigned_runner: assignment.runner,
+            },
+        });
+        decisions.push({
+            task_id: task.task_id,
+            queued: true,
+            reason: `queued for ${assignment.role} via ${assignment.runner}`,
+        });
+    }
+    return decisions;
+}