sidecar-cli 0.1.1-beta.2 → 0.1.1-rc.1

package/README.md

@@ -21,6 +21,12 @@ Install globally (stable):
 npm install -g sidecar-cli
 ```
 
+Note on npm deprecation warnings:
+
+- You may see a transitive warning for `prebuild-install@7.1.3` during install.
+- This currently comes from `better-sqlite3` (Sidecar's SQLite dependency), not from Sidecar code directly.
+- Sidecar still installs/works normally; we will update when upstream dependency chain moves off it.
+
 Install beta:
 
 ```bash
@@ -103,8 +109,11 @@ Global:
 
 - `sidecar init [--force] [--name <project-name>] [--json]`
 - `sidecar status [--json]`
+- `sidecar preferences show [--json]`
 - `sidecar ui [--no-open] [--port <port>] [--install-only] [--project <path>] [--reinstall]`
 - `sidecar capabilities --json`
+- `sidecar event add ... [--json]`
+- `sidecar export [--format json|jsonl] [--output <path>]`
 - `sidecar help`
 
 Context and summary:
@@ -256,6 +265,15 @@ Initial UI screens:
 - Decisions: decision records with summary and timestamps
 - Preferences: `.sidecar/preferences.json` and `.sidecar/summary.md`
 
+UI write support (v1):
+
+- Add notes from Overview
+- Add open tasks from Overview
+- Edit `.sidecar/preferences.json` from Preferences
+  - `output.humanTime` controls timestamp style in human-readable CLI output:
+    - `true`: friendly local times (for example `3/18/2026, 11:51 AM`)
+    - `false`: raw ISO-style timestamps
+
 ## JSON output
 
 Most commands support `--json` and return structured output:
@@ -267,6 +285,68 @@ Most commands support `--json` and return structured output:
 
 This makes Sidecar easy to automate from scripts and AI agents.
 
+## Integration API
+
+Sidecar CLI is the first integration API for scripts, agents, and local tooling.
+
+Standard JSON envelope:
+
+```json
+{
+  "ok": true,
+  "version": "1.0",
+  "command": "task add",
+  "data": {},
+  "errors": []
+}
+```
+
+Failure envelope:
+
+```json
+{
+  "ok": false,
+  "version": "1.0",
+  "command": "task add",
+  "data": null,
+  "errors": ["..."]
+}
+```
+
+Generic event ingest:
+
+```bash
+sidecar event add --type decision --title "Use SQLite" --summary "Simple local storage for v1" --created-by agent --source cli --json
+sidecar event add --json-input '{"type":"note","summary":"Captured context","created_by":"agent"}' --json
+cat event.json | sidecar event add --stdin --json
+```
+
+Capabilities metadata:
+
+```bash
+sidecar capabilities --json
+```
+
+Includes:
+
+- `cli_version`
+- `json_contract_version`
+- `features`
+- command and option metadata
+
+Export project memory:
+
+```bash
+sidecar export --format json
+sidecar export --format json --output ./exports/sidecar.json
+sidecar export --format jsonl > sidecar-events.jsonl
+```
+
+JSONL note:
+
+- JSONL export currently emits events only, one JSON object per line.
+- each JSONL line includes `"version": "1.0"` and `"record_type": "event"`.
+
 ## Release and distribution
 
 See [RELEASE.md](./RELEASE.md) for publishing/release details.

package/dist/cli.js

@@ -21,11 +21,14 @@ import { addArtifact, listArtifacts } from './services/artifact-service.js';
 import { addDecision, addNote, addWorklog, getActiveSessionId, listRecentEvents } from './services/event-service.js';
 import { addTask, listTasks, markTaskDone } from './services/task-service.js';
 import { currentSession, endSession, startSession, verifySessionHygiene } from './services/session-service.js';
+import { eventIngestSchema, ingestEvent } from './services/event-ingest-service.js';
+import { buildExportJson, buildExportJsonlEvents, writeOutputFile } from './services/export-service.js';
 const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const actorSchema = z.enum(['human', 'agent']);
 const taskPrioritySchema = z.enum(['low', 'medium', 'high']);
 const artifactKindSchema = z.enum(['file', 'doc', 'screenshot', 'other']);
 const taskStatusSchema = z.enum(['open', 'done', 'all']);
+const exportFormatSchema = z.enum(['json', 'jsonl']);
 const NOT_INITIALIZED_MSG = 'Sidecar is not initialized in this directory or any parent directory';
 function fail(message) {
     throw new SidecarError(message);
@@ -167,6 +170,13 @@ function renderContextMarkdown(data) {
     }
     return lines.join('\n');
 }
+async function readStdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
 function resolveProjectRoot(projectPath) {
     const basePath = projectPath ? path.resolve(projectPath) : process.cwd();
     const root = findSidecarRoot(basePath);
@@ -363,7 +373,7 @@ program
         };
         const recent = db.prepare(`SELECT type, title, created_at FROM events WHERE project_id = ? ORDER BY created_at DESC LIMIT 5`).all(projectId);
         db.close();
-        const data = { initialized: true, project, counts, recent };
+        const data = { project, counts, recent_events: recent };
         respondSuccess(command, Boolean(opts.json), data, [
             `Project: ${project.name}`,
             `Root: ${project.root_path}`,
@@ -379,6 +389,24 @@ program
         handleCommandError(command, Boolean(opts.json), normalized);
     }
 });
+const preferences = program.command('preferences').description('Preferences commands');
+preferences
+    .command('show')
+    .description('Show project preferences')
+    .option('--json', 'Print machine-readable JSON output')
+    .addHelpText('after', '\nExamples:\n  $ sidecar preferences show\n  $ sidecar preferences show --json')
+    .action((opts) => {
+    const command = 'preferences show';
+    try {
+        const { rootPath } = requireInitialized();
+        const prefsPath = getSidecarPaths(rootPath).preferencesPath;
+        const preferencesData = fs.existsSync(prefsPath) ? JSON.parse(fs.readFileSync(prefsPath, 'utf8')) : {};
+        respondSuccess(command, Boolean(opts.json), { project: { root_path: rootPath }, preferences: preferencesData, path: prefsPath }, [`Preferences path: ${prefsPath}`, stringifyJson(preferencesData)]);
+    }
+    catch (err) {
+        handleCommandError(command, Boolean(opts.json), err);
+    }
+});
 program
     .command('capabilities')
     .description('Output a machine-readable manifest of Sidecar commands')
@@ -392,6 +420,120 @@ program
     else
         console.log(stringifyJson(manifest));
 });
+const event = program.command('event').description('Generic event ingest commands');
+event
+    .command('add')
+    .description('Add a validated generic Sidecar event')
+    .option('--type <type>', 'note|decision|worklog|task_created|task_completed|summary_generated')
+    .option('--title <title>', 'Event title')
+    .option('--summary <summary>', 'Event summary')
+    .option('--details-json <json>', 'JSON object for details_json')
+    .option('--created-by <by>', 'human|agent|system')
+    .option('--source <source>', 'cli|imported|generated')
+    .option('--session-id <id>', 'Optional session id', (v) => Number.parseInt(v, 10))
+    .option('--json-input <json>', 'Raw JSON event payload')
+    .option('--stdin', 'Read JSON event payload from stdin')
+    .option('--json', 'Print machine-readable JSON output')
+    .addHelpText('after', '\nExamples:\n  $ sidecar event add --type note --summary "Captured context"\n  $ sidecar event add --json-input \'{"type":"decision","title":"Use SQLite","summary":"Local-first"}\' --json\n  $ cat event.json | sidecar event add --stdin --json')
+    .action(async (opts) => {
+    const command = 'event add';
+    try {
+        const payloadSources = [Boolean(opts.jsonInput), Boolean(opts.stdin), Boolean(opts.type || opts.title || opts.summary || opts.detailsJson || opts.createdBy || opts.source || opts.sessionId)];
+        if (payloadSources.filter(Boolean).length !== 1) {
+            fail('Provide exactly one payload source: structured flags OR --json-input OR --stdin');
+        }
+        let payloadRaw;
+        if (opts.jsonInput) {
+            payloadRaw = JSON.parse(opts.jsonInput);
+        }
+        else if (opts.stdin) {
+            const raw = (await readStdinText()).trim();
+            if (!raw)
+                fail('STDIN payload is empty');
+            payloadRaw = JSON.parse(raw);
+        }
+        else {
+            payloadRaw = {
+                type: opts.type,
+                title: opts.title,
+                summary: opts.summary,
+                details_json: opts.detailsJson ? JSON.parse(opts.detailsJson) : undefined,
+                created_by: opts.createdBy,
+                source: opts.source,
+                session_id: Number.isInteger(opts.sessionId) ? opts.sessionId : undefined,
+            };
+        }
+        const payload = eventIngestSchema.parse(payloadRaw);
+        const { db, projectId } = requireInitialized();
+        const created = ingestEvent(db, { project_id: projectId, payload });
+        db.close();
+        respondSuccess(command, Boolean(opts.json), { event: { ...created, created_at: nowIso() } }, [`Recorded ${created.type} event #${created.id}.`]);
+    }
+    catch (err) {
+        handleCommandError(command, Boolean(opts.json), err);
+    }
+});
+program
+    .command('export')
+    .description('Export project memory in JSON or JSONL')
+    .option('--format <format>', 'json|jsonl', 'json')
+    .option('--limit <n>', 'Limit exported events', (v) => Number.parseInt(v, 10))
+    .option('--type <event-type>', 'Filter exported events by type')
+    .option('--since <iso-date>', 'Filter events created_at >= since')
+    .option('--until <iso-date>', 'Filter events created_at <= until')
+    .option('--output <path>', 'Write export to file path instead of stdout')
+    .option('--json', 'Wrap command metadata in JSON envelope when writing to file')
+    .addHelpText('after', '\nExamples:\n  $ sidecar export --format json\n  $ sidecar export --format jsonl --output sidecar-events.jsonl\n  $ sidecar export --type decision --since 2026-01-01T00:00:00Z')
+    .action((opts) => {
+    const command = 'export';
+    try {
+        const format = exportFormatSchema.parse(opts.format);
+        if (opts.since && Number.isNaN(Date.parse(opts.since)))
+            fail('--since must be a valid ISO date');
+        if (opts.until && Number.isNaN(Date.parse(opts.until)))
+            fail('--until must be a valid ISO date');
+        const { db, projectId, rootPath } = requireInitialized();
+        if (format === 'json') {
+            const payload = buildExportJson(db, {
+                projectId,
+                rootPath,
+                limit: opts.limit,
+                type: opts.type,
+                since: opts.since,
+                until: opts.until,
+            });
+            db.close();
+            const rendered = stringifyJson(payload);
+            if (opts.output) {
+                const filePath = writeOutputFile(opts.output, `${rendered}\n`);
+                respondSuccess(command, Boolean(opts.json), { format, output_path: filePath }, [`Export written: ${filePath}`]);
+            }
+            else {
+                console.log(rendered);
+            }
+            return;
+        }
+        const lines = buildExportJsonlEvents(db, {
+            projectId,
+            limit: opts.limit,
+            type: opts.type,
+            since: opts.since,
+            until: opts.until,
+        });
+        db.close();
+        const rendered = `${lines.join('\n')}${lines.length > 0 ? '\n' : ''}`;
+        if (opts.output) {
+            const filePath = writeOutputFile(opts.output, rendered);
+            respondSuccess(command, Boolean(opts.json), { format, output_path: filePath, records: lines.length }, [`Export written: ${filePath}`]);
+        }
+        else {
+            process.stdout.write(rendered);
+        }
+    }
+    catch (err) {
+        handleCommandError(command, Boolean(opts.json), err);
+    }
+});
 program
     .command('context')
     .description('Generate a compact context snapshot for a work session')
@@ -436,7 +578,7 @@ summary
         const { db, projectId, rootPath } = requireInitialized();
         const out = refreshSummaryFile(db, rootPath, projectId, Math.max(1, opts.limit));
         db.close();
-        respondSuccess(command, Boolean(opts.json), { ...out, timestamp: nowIso() }, ['Summary refreshed.', `Path: ${out.path}`]);
+        respondSuccess(command, Boolean(opts.json), { summary: { path: out.path, generated_at: out.generatedAt } }, ['Summary refreshed.', `Path: ${out.path}`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -456,7 +598,7 @@ program
         const rows = listRecentEvents(db, { projectId, type: opts.type, limit: Math.max(1, opts.limit) });
         db.close();
         if (opts.json)
-            printJsonEnvelope(jsonSuccess(command, rows));
+            printJsonEnvelope(jsonSuccess(command, { events: rows }));
         else {
             if (rows.length === 0) {
                 console.log('No events found.');
@@ -488,7 +630,7 @@ program
         const sessionId = maybeSessionId(db, projectId, opts.session);
         const eventId = addNote(db, { projectId, text, title: opts.title, by, sessionId });
         db.close();
-        respondSuccess(command, Boolean(opts.json), { eventId, timestamp: nowIso() }, [`Recorded note event #${eventId}.`]);
+        respondSuccess(command, Boolean(opts.json), { event: { id: eventId, type: 'note', title: opts.title?.trim() || 'Note', summary: text, created_by: by, session_id: sessionId, created_at: nowIso() } }, [`Recorded note event #${eventId}.`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -513,7 +655,7 @@ decision
         const sessionId = maybeSessionId(db, projectId, opts.session);
         const eventId = addDecision(db, { projectId, title: opts.title, summary: opts.summary, details: opts.details, by, sessionId });
         db.close();
-        respondSuccess(command, Boolean(opts.json), { eventId, timestamp: nowIso() }, [`Recorded decision event #${eventId}.`]);
+        respondSuccess(command, Boolean(opts.json), { event: { id: eventId, type: 'decision', title: opts.title, summary: opts.summary, created_by: by, session_id: sessionId, created_at: nowIso() } }, [`Recorded decision event #${eventId}.`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -552,7 +694,7 @@ worklog
             addArtifact(db, { projectId, path: filePath, kind: 'file' });
         }
         db.close();
-        respondSuccess(command, Boolean(opts.json), { ...result, timestamp: nowIso() }, [
+        respondSuccess(command, Boolean(opts.json), { event: { id: result.eventId, type: 'worklog', summary: opts.done, created_by: by, session_id: sessionId, created_at: nowIso() }, artifacts: result.files.map((p) => ({ path: p, kind: 'file' })) }, [
             `Recorded worklog event #${result.eventId}.`,
             `Artifacts linked: ${result.files.length}`,
         ]);
@@ -578,7 +720,7 @@ task
         const { db, projectId } = requireInitialized();
         const result = addTask(db, { projectId, title, description: opts.description, priority, by });
         db.close();
-        respondSuccess(command, Boolean(opts.json), { ...result, timestamp: nowIso() }, [`Added task #${result.taskId}.`]);
+        respondSuccess(command, Boolean(opts.json), { task: { id: result.taskId, title, description: opts.description ?? null, status: 'open', priority }, event: { id: result.eventId, type: 'task_created' } }, [`Added task #${result.taskId}.`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -602,7 +744,7 @@ task
         db.close();
         if (!result.ok)
             fail(result.reason);
-        respondSuccess(command, Boolean(opts.json), { taskId, eventId: result.eventId, timestamp: nowIso() }, [`Completed task #${taskId}.`]);
+        respondSuccess(command, Boolean(opts.json), { task: { id: taskId, status: 'done' }, event: { id: result.eventId, type: 'task_completed' } }, [`Completed task #${taskId}.`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -624,7 +766,7 @@ task
         db.close();
         if (opts.format === 'json' || opts.json) {
             if (opts.json)
-                printJsonEnvelope(jsonSuccess(command, rows));
+                printJsonEnvelope(jsonSuccess(command, { status, tasks: rows }));
             else
                 console.log(stringifyJson(rows));
             return;
@@ -666,7 +808,7 @@ session
         db.close();
         if (!result.ok)
             fail(result.reason);
-        respondSuccess(command, Boolean(opts.json), { ...result, timestamp: nowIso() }, [`Started session #${result.sessionId}.`]);
+        respondSuccess(command, Boolean(opts.json), { session: { id: result.sessionId, actor_type: actor, actor_name: opts.name ?? null, started_at: nowIso() } }, [`Started session #${result.sessionId}.`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -686,7 +828,7 @@ session
         db.close();
         if (!result.ok)
             fail(result.reason);
-        respondSuccess(command, Boolean(opts.json), { ...result, timestamp: nowIso() }, [`Ended session #${result.sessionId}.`]);
+        respondSuccess(command, Boolean(opts.json), { session: { id: result.sessionId, ended_at: nowIso(), summary: opts.summary ?? null } }, [`Ended session #${result.sessionId}.`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -704,7 +846,7 @@ session
         const current = currentSession(db, projectId);
         db.close();
         if (opts.json)
-            printJsonEnvelope(jsonSuccess(command, { current: current ?? null }));
+            printJsonEnvelope(jsonSuccess(command, { session: current ?? null }));
         else if (!current) {
             console.log('No active session.');
         }
@@ -768,7 +910,7 @@ artifact
         const { db, projectId } = requireInitialized();
         const artifactId = addArtifact(db, { projectId, path: artifactPath, kind, note: opts.note });
         db.close();
-        respondSuccess(command, Boolean(opts.json), { artifactId, timestamp: nowIso() }, [`Added artifact #${artifactId}.`]);
+        respondSuccess(command, Boolean(opts.json), { artifact: { id: artifactId, path: artifactPath, kind, note: opts.note ?? null, created_at: nowIso() } }, [`Added artifact #${artifactId}.`]);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -786,7 +928,7 @@ artifact
         const rows = listArtifacts(db, projectId);
         db.close();
         if (opts.json)
-            printJsonEnvelope(jsonSuccess(command, rows));
+            printJsonEnvelope(jsonSuccess(command, { artifacts: rows }));
         else {
             if (rows.length === 0) {
                 console.log('No artifacts found.');

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/services/capabilities-service.js

@@ -1,10 +1,17 @@
+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',
+            'optional_local_ui',
+        ],
         commands: [
             {
                 name: 'init',
@@ -20,6 +27,22 @@ 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)',
@@ -41,6 +64,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',

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/types/api.js

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

package/package.json

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