sidecar-cli 0.1.1 → 0.1.2-beta.1

package/dist/lib/output.js

@@ -1,7 +1,9 @@
 import { stringifyJson } from './format.js';
+export const JSON_CONTRACT_VERSION = '1.0';
 export function jsonSuccess(command, data) {
     return {
         ok: true,
+        version: JSON_CONTRACT_VERSION,
         command,
         data,
         errors: [],
@@ -10,6 +12,7 @@ export function jsonSuccess(command, data) {
 export function jsonFailure(command, message) {
     return {
         ok: false,
+        version: JSON_CONTRACT_VERSION,
         command,
         data: null,
         errors: [message],

package/dist/lib/paths.js

@@ -6,6 +6,9 @@ export function getSidecarPaths(rootPath) {
     return {
         rootPath,
         sidecarPath,
+        tasksPath: path.join(sidecarPath, 'tasks'),
+        runsPath: path.join(sidecarPath, 'runs'),
+        promptsPath: path.join(sidecarPath, 'prompts'),
         rootAgentsPath: path.join(rootPath, 'AGENTS.md'),
         rootClaudePath: path.join(rootPath, 'CLAUDE.md'),
         dbPath: path.join(sidecarPath, 'sidecar.db'),

package/dist/lib/ui.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { detectReleaseChannel } from './update-check.js';
+import { SidecarError } from './errors.js';
+const UI_PACKAGE = '@sidecar/ui';
+const UI_RUNTIME_DIR = path.join(os.homedir(), '.sidecar', 'ui');
+function ensureRuntimeDir() {
+    fs.mkdirSync(UI_RUNTIME_DIR, { recursive: true });
+    const runtimePkgPath = path.join(UI_RUNTIME_DIR, 'package.json');
+    if (!fs.existsSync(runtimePkgPath)) {
+        fs.writeFileSync(runtimePkgPath, JSON.stringify({ name: 'sidecar-ui-runtime', private: true, version: '0.0.0' }, null, 2));
+    }
+}
+function readInstalledUiVersion() {
+    const p = path.join(UI_RUNTIME_DIR, 'node_modules', '@sidecar', 'ui', 'package.json');
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function major(version) {
+    const m = version.match(/^(\d+)\./);
+    if (!m)
+        return null;
+    return Number.parseInt(m[1], 10);
+}
+function isCompatible(cliVersion, uiVersion) {
+    if (!uiVersion)
+        return false;
+    const cliMajor = major(cliVersion);
+    const uiMajor = major(uiVersion);
+    return cliMajor !== null && uiMajor !== null && cliMajor === uiMajor;
+}
+function npmInstall(spec) {
+    execFileSync('npm', ['install', '--no-audit', '--no-fund', spec], {
+        cwd: UI_RUNTIME_DIR,
+        stdio: 'inherit',
+    });
+}
+function getDesiredTag(cliVersion) {
+    return detectReleaseChannel(cliVersion);
+}
+export function ensureUiInstalled(options) {
+    ensureRuntimeDir();
+    const tag = getDesiredTag(options.cliVersion);
+    const installed = readInstalledUiVersion();
+    const shouldInstall = Boolean(options.reinstall) || !isCompatible(options.cliVersion, installed);
+    if (shouldInstall) {
+        options.onStatus?.(installed
+            ? `Updating Sidecar UI (${installed}) for CLI compatibility...`
+            : 'Installing Sidecar UI for first use...');
+        const spec = `${UI_PACKAGE}@${tag}`;
+        try {
+            npmInstall(spec);
+        }
+        catch {
+            const localUiPkg = path.resolve(process.cwd(), 'packages', 'ui');
+            if (fs.existsSync(path.join(localUiPkg, 'package.json'))) {
+                options.onStatus?.('Falling back to local workspace UI package...');
+                npmInstall(localUiPkg);
+            }
+            else {
+                throw new SidecarError('Failed to install Sidecar UI package. Check npm access/network and retry `sidecar ui --reinstall`.');
+            }
+        }
+    }
+    const finalVersion = readInstalledUiVersion();
+    if (!finalVersion) {
+        throw new SidecarError('Sidecar UI appears missing after install. Retry with `sidecar ui --reinstall`.');
+    }
+    return { installedVersion: finalVersion };
+}
+export function launchUiServer(options) {
+    const serverPath = path.join(UI_RUNTIME_DIR, 'node_modules', '@sidecar', 'ui', 'server.js');
+    if (!fs.existsSync(serverPath)) {
+        throw new SidecarError('Sidecar UI server entry was not found after install.');
+    }
+    const child = spawn(process.execPath, [serverPath, '--project', options.projectPath, '--port', String(options.port)], {
+        stdio: 'inherit',
+        env: {
+            ...process.env,
+            SIDECAR_CLI_JS: process.argv[1] || '',
+        },
+    });
+    const url = `http://localhost:${options.port}`;
+    if (options.openBrowser) {
+        openBrowser(url);
+    }
+    return { url, child };
+}
+export function openBrowser(url) {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+        return;
+    }
+    if (platform === 'win32') {
+        spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+        return;
+    }
+    spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+}

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