sidecar-cli 0.1.1 → 0.1.2

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,7 +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:
@@ -168,7 +178,18 @@ Optional local enforcement:
 npm run install:hooks
 ```
 
-This installs a non-blocking pre-commit reminder that runs `npm run sidecar:reminder`.
+This is optional and per-repository clone. `sidecar init` does not install git hooks automatically.
+
+This installs a pre-commit guard that checks staged non-doc code changes.
+If staged code changes are present, commit is blocked unless both are recorded since the last commit:
+
+- a `worklog` event
+- a `summary refresh` event
+
+The guard command is:
+
+- `npm run sidecar:reminder -- --staged --enforce`
+
 If a pre-commit hook already exists, Sidecar will not overwrite it unless you run:
 
 ```bash
@@ -205,6 +226,54 @@ Primary tables:
 
 No network dependency is required for normal operation.
 
+## Optional local UI
+
+`sidecar ui` launches a local browser UI for the selected Sidecar project.
+
+Lazy-install behavior:
+
+1. `sidecar ui` resolves the nearest `.sidecar` project root (or uses `--project`).
+2. Sidecar checks for `@sidecar/ui` in `~/.sidecar/ui`.
+3. If missing/incompatible, Sidecar installs or updates it automatically.
+4. Sidecar starts a local UI server and opens the browser (unless `--no-open`).
+
+UI runtime location:
+
+- `~/.sidecar/ui`
+- the CLI installs `@sidecar/ui` here (not in your project repo)
+
+Version compatibility rule:
+
+- CLI and UI must share the same major version.
+- If majors differ, `sidecar ui` auto-reinstalls/updates UI.
+
+Common examples:
+
+```bash
+sidecar ui
+sidecar ui --no-open --port 4311
+sidecar ui --install-only
+sidecar ui --project ../other-repo
+sidecar ui --reinstall
+```
+
+Initial UI screens:
+
+- Overview: project info, active session, recent decisions/worklogs, open tasks, recent notes
+- Timeline: recent events in chronological order
+- Tasks: open and completed tasks
+- 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:
@@ -216,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

@@ -5,12 +5,13 @@ import { Command } from 'commander';
 import Database from 'better-sqlite3';
 import { z } from 'zod';
 import { initializeSchema } from './db/schema.js';
-import { getSidecarPaths } from './lib/paths.js';
+import { findSidecarRoot, getSidecarPaths } from './lib/paths.js';
 import { nowIso, humanTime, stringifyJson } from './lib/format.js';
 import { SidecarError } from './lib/errors.js';
 import { jsonFailure, jsonSuccess, printJsonEnvelope } from './lib/output.js';
 import { bannerDisabled, renderBanner } from './lib/banner.js';
 import { getUpdateNotice } from './lib/update-check.js';
+import { ensureUiInstalled, launchUiServer } from './lib/ui.js';
 import { requireInitialized } from './db/client.js';
 import { renderAgentsMarkdown, renderClaudeMarkdown } from './templates/agents.js';
 import { refreshSummaryFile } from './services/summary-service.js';
@@ -20,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);
@@ -166,6 +170,21 @@ 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);
+    if (!root) {
+        throw new SidecarError(NOT_INITIALIZED_MSG);
+    }
+    return root;
+}
 const program = new Command();
 program.name('sidecar').description('Local-first project memory and recording CLI').version(pkg.version);
 program.option('--no-banner', 'Disable Sidecar banner output');
@@ -183,6 +202,53 @@ function maybePrintUpdateNotice() {
     console.log(`Update available: ${pkg.version} -> ${notice.latestVersion}`);
     console.log(`Run: npm install -g sidecar-cli@${installTag}`);
 }
+program
+    .command('ui')
+    .description('Launch the optional local Sidecar UI')
+    .option('--no-open', 'Do not open the browser automatically')
+    .option('--port <port>', 'Port to run the UI on', (v) => Number.parseInt(v, 10), 4310)
+    .option('--install-only', 'Install/update UI package but do not launch')
+    .option('--project <path>', 'Project path (defaults to nearest Sidecar root)')
+    .option('--reinstall', 'Force reinstall UI package')
+    .addHelpText('after', '\nExamples:\n  $ sidecar ui\n  $ sidecar ui --no-open --port 4311\n  $ sidecar ui --project ../my-repo --install-only')
+    .action((opts) => {
+    const command = 'ui';
+    try {
+        const projectRoot = resolveProjectRoot(opts.project);
+        const port = Number(opts.port);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            fail('Port must be an integer between 1 and 65535');
+        }
+        if (!bannerDisabled()) {
+            console.log(renderBanner());
+            console.log('');
+        }
+        console.log('Launching Sidecar UI');
+        console.log(`Project: ${projectRoot}`);
+        const { installedVersion } = ensureUiInstalled({
+            cliVersion: pkg.version,
+            reinstall: Boolean(opts.reinstall),
+            onStatus: (line) => console.log(line),
+        });
+        console.log(`UI version: ${installedVersion}`);
+        if (opts.installOnly) {
+            console.log('Install-only mode complete.');
+            return;
+        }
+        const { url } = launchUiServer({
+            projectPath: projectRoot,
+            port,
+            openBrowser: opts.open !== false,
+        });
+        console.log(`URL: ${url}`);
+        if (opts.open === false) {
+            console.log('Browser auto-open disabled.');
+        }
+    }
+    catch (err) {
+        handleCommandError(command, false, err);
+    }
+});
 program
     .command('init')
     .description('Initialize Sidecar in the current directory')
@@ -307,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}`,
@@ -323,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')
@@ -336,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')
@@ -380,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);
@@ -400,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.');
@@ -432,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);
@@ -457,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);
@@ -496,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}`,
         ]);
@@ -522,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);
@@ -546,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);
@@ -568,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;
@@ -610,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);
@@ -630,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);
@@ -648,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.');
         }
@@ -712,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);
@@ -730,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/lib/ui.js

@@ -0,0 +1,106 @@
+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 },
+    });
+    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/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,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 +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",
+  "version": "0.1.2",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",