sidecar-cli 0.1.2 → 0.1.3-beta.1

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;
+}

package/dist/tasks/task-packet.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+export const TASK_PACKET_VERSION = '1.0';
+const taskIdSchema = z.string().regex(/^T-\d{3,}$/, 'Task id must look like T-001');
+export const taskPacketStatusSchema = z.enum(['draft', 'ready', 'queued', 'running', 'review', 'blocked', 'done']);
+export const taskPacketPrioritySchema = z.enum(['low', 'medium', 'high']);
+export const taskPacketTypeSchema = z.enum(['feature', 'bug', 'chore', 'research']);
+export const taskAgentRoleSchema = z.enum(['planner', 'builder-ui', 'builder-app', 'reviewer', 'tester']);
+export const taskRunnerSchema = z.enum(['codex', 'claude']);
+export const taskPacketSchema = z
+    .object({
+    version: z.string().default(TASK_PACKET_VERSION),
+    task_id: taskIdSchema,
+    title: z.string().min(1, 'title is required'),
+    type: taskPacketTypeSchema.default('chore'),
+    status: z
+        .preprocess((value) => {
+        if (value === 'open')
+            return 'draft';
+        if (value === 'in_progress')
+            return 'running';
+        return value;
+    }, taskPacketStatusSchema)
+        .default('draft'),
+    priority: taskPacketPrioritySchema.default('medium'),
+    summary: z.string().min(1, 'summary is required'),
+    goal: z.string().min(1, 'goal is required'),
+    scope: z.object({
+        in_scope: z.array(z.string()).default([]),
+        out_of_scope: z.array(z.string()).default([]),
+    }),
+    context: z.object({
+        related_decisions: z.array(z.string()).default([]),
+        related_notes: z.array(z.string()).default([]),
+    }),
+    implementation: z.object({
+        files_to_read: z.array(z.string()).default([]),
+        files_to_avoid: z.array(z.string()).default([]),
+    }),
+    constraints: z.object({
+        technical: z.array(z.string()).default([]),
+        design: z.array(z.string()).default([]),
+    }),
+    execution: z.object({
+        commands: z.object({
+            validation: z.array(z.string()).default([]),
+        }),
+    }),
+    dependencies: z.array(taskIdSchema).default([]),
+    tags: z.array(z.string()).default([]),
+    target_areas: z.array(z.string()).default([]),
+    definition_of_done: z.array(z.string()).default([]),
+    tracking: z.object({
+        branch: z.string().default(''),
+        worktree: z.string().default(''),
+        assigned_agent_role: taskAgentRoleSchema.nullable().default(null),
+        assigned_runner: taskRunnerSchema.nullable().default(null),
+        assignment_reason: z.string().default(''),
+        assigned_at: z.string().datetime({ offset: true }).nullable().default(null),
+    }),
+    result: z.object({
+        summary: z.string().default(''),
+        changed_files: z.array(z.string()).default([]),
+        validation_results: z.array(z.string()).default([]),
+    }),
+})
+    .strict();
+export const taskPacketInputSchema = taskPacketSchema.omit({ task_id: true }).partial({
+    version: true,
+    type: true,
+    status: true,
+    priority: true,
+    scope: true,
+    context: true,
+    implementation: true,
+    constraints: true,
+    execution: true,
+    dependencies: true,
+    tags: true,
+    target_areas: true,
+    definition_of_done: true,
+    tracking: true,
+    result: true,
+});
+export function createTaskPacket(taskId, input) {
+    const normalized = {
+        ...input,
+        version: input.version ?? TASK_PACKET_VERSION,
+        task_id: taskId,
+        type: input.type ?? 'chore',
+        status: input.status ?? 'draft',
+        priority: input.priority ?? 'medium',
+        scope: {
+            in_scope: input.scope?.in_scope ?? [],
+            out_of_scope: input.scope?.out_of_scope ?? [],
+        },
+        context: {
+            related_decisions: input.context?.related_decisions ?? [],
+            related_notes: input.context?.related_notes ?? [],
+        },
+        implementation: {
+            files_to_read: input.implementation?.files_to_read ?? [],
+            files_to_avoid: input.implementation?.files_to_avoid ?? [],
+        },
+        constraints: {
+            technical: input.constraints?.technical ?? [],
+            design: input.constraints?.design ?? [],
+        },
+        execution: {
+            commands: {
+                validation: input.execution?.commands?.validation ?? [],
+            },
+        },
+        dependencies: input.dependencies ?? [],
+        tags: input.tags ?? [],
+        target_areas: input.target_areas ?? [],
+        definition_of_done: input.definition_of_done ?? [],
+        tracking: {
+            branch: input.tracking?.branch ?? '',
+            worktree: input.tracking?.worktree ?? '',
+            assigned_agent_role: input.tracking?.assigned_agent_role ?? null,
+            assigned_runner: input.tracking?.assigned_runner ?? null,
+            assignment_reason: input.tracking?.assignment_reason ?? '',
+            assigned_at: input.tracking?.assigned_at ?? null,
+        },
+        result: {
+            summary: input.result?.summary ?? '',
+            changed_files: input.result?.changed_files ?? [],
+            validation_results: input.result?.validation_results ?? [],
+        },
+    };
+    return taskPacketSchema.parse(normalized);
+}

package/dist/tasks/task-repository.js

@@ -0,0 +1,78 @@
+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 { taskPacketSchema } from './task-packet.js';
+function taskFilePath(tasksPath, taskId) {
+    return path.join(tasksPath, `${taskId}.json`);
+}
+function parseTaskIdOrdinal(taskId) {
+    const match = /^T-(\d+)$/.exec(taskId);
+    return match ? Number.parseInt(match[1], 10) : 0;
+}
+export class TaskPacketRepository {
+    rootPath;
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+    }
+    get tasksPath() {
+        return getSidecarPaths(this.rootPath).tasksPath;
+    }
+    ensureStorage() {
+        fs.mkdirSync(this.tasksPath, { recursive: true });
+    }
+    generateNextTaskId() {
+        this.ensureStorage();
+        const files = fs.readdirSync(this.tasksPath, { 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, parseTaskIdOrdinal(id));
+        }
+        return `T-${String(max + 1).padStart(3, '0')}`;
+    }
+    save(packet) {
+        this.ensureStorage();
+        const validated = taskPacketSchema.parse(packet);
+        const filePath = taskFilePath(this.tasksPath, validated.task_id);
+        fs.writeFileSync(filePath, `${stringifyJson(validated)}\n`, 'utf8');
+        return filePath;
+    }
+    get(taskId) {
+        const filePath = taskFilePath(this.tasksPath, taskId);
+        if (!fs.existsSync(filePath)) {
+            throw new SidecarError(`Task not found: ${taskId}`);
+        }
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            return taskPacketSchema.parse(raw);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new SidecarError(`Invalid task packet at ${filePath}: ${message}`);
+        }
+    }
+    list() {
+        this.ensureStorage();
+        const files = fs
+            .readdirSync(this.tasksPath, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map((entry) => path.join(this.tasksPath, entry.name))
+            .sort();
+        const packets = [];
+        for (const filePath of files) {
+            try {
+                const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+                packets.push(taskPacketSchema.parse(raw));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new SidecarError(`Invalid task packet at ${filePath}: ${message}`);
+            }
+        }
+        return packets;
+    }
+}

package/dist/tasks/task-service.js

@@ -0,0 +1,79 @@
+import { TaskPacketRepository } from './task-repository.js';
+import { createTaskPacket, } from './task-packet.js';
+export function createTaskPacketRecord(rootPath, input) {
+    const repo = new TaskPacketRepository(rootPath);
+    const taskId = repo.generateNextTaskId();
+    const packetInput = {
+        title: input.title,
+        summary: input.summary,
+        goal: input.goal,
+        type: input.type,
+        status: input.status,
+        priority: input.priority,
+        scope: {
+            in_scope: input.scope_in_scope ?? [],
+            out_of_scope: input.scope_out_of_scope ?? [],
+        },
+        context: {
+            related_decisions: input.related_decisions ?? [],
+            related_notes: input.related_notes ?? [],
+        },
+        implementation: {
+            files_to_read: input.files_to_read ?? [],
+            files_to_avoid: input.files_to_avoid ?? [],
+        },
+        constraints: {
+            technical: input.technical_constraints ?? [],
+            design: input.design_constraints ?? [],
+        },
+        execution: {
+            commands: {
+                validation: input.validation_commands ?? [],
+            },
+        },
+        dependencies: input.dependencies ?? [],
+        tags: input.tags ?? [],
+        target_areas: input.target_areas ?? [],
+        definition_of_done: input.definition_of_done ?? [],
+        tracking: {
+            branch: input.branch ?? '',
+            worktree: input.worktree ?? '',
+            assigned_agent_role: null,
+            assigned_runner: null,
+            assignment_reason: '',
+            assigned_at: null,
+        },
+    };
+    const packet = createTaskPacket(taskId, packetInput);
+    const filePath = repo.save(packet);
+    return { task: packet, path: filePath };
+}
+export function listTaskPackets(rootPath) {
+    const repo = new TaskPacketRepository(rootPath);
+    const order = {
+        draft: 0,
+        ready: 1,
+        queued: 2,
+        running: 3,
+        review: 4,
+        blocked: 5,
+        done: 6,
+    };
+    return repo
+        .list()
+        .slice()
+        .sort((a, b) => {
+        const byStatus = order[a.status] - order[b.status];
+        if (byStatus !== 0)
+            return byStatus;
+        return a.task_id.localeCompare(b.task_id, undefined, { numeric: true });
+    });
+}
+export function getTaskPacket(rootPath, taskId) {
+    const repo = new TaskPacketRepository(rootPath);
+    return repo.get(taskId);
+}
+export function saveTaskPacket(rootPath, task) {
+    const repo = new TaskPacketRepository(rootPath);
+    return repo.save(task);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecar-cli",
-  "version": "0.1.2",
+  "version": "0.1.3-beta.1",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",