sidecar-cli 0.1.0-beta.4

package/dist/db/client.js

@@ -0,0 +1,16 @@
+import Database from 'better-sqlite3';
+import { findSidecarRoot, getSidecarPaths } from '../lib/paths.js';
+import { SidecarError } from '../lib/errors.js';
+export function requireInitialized() {
+    const rootPath = findSidecarRoot();
+    if (!rootPath) {
+        throw new SidecarError('Sidecar is not initialized in this directory or any parent directory', 'NOT_INITIALIZED', 2);
+    }
+    const db = new Database(getSidecarPaths(rootPath).dbPath);
+    const row = db.prepare('SELECT id FROM projects ORDER BY id LIMIT 1').get();
+    if (!row) {
+        db.close();
+        throw new SidecarError('Sidecar database exists but project row is missing. Re-run `sidecar init --force`.', 'PROJECT_MISSING', 2);
+    }
+    return { rootPath, db, projectId: row.id };
+}

package/dist/db/schema.js

@@ -0,0 +1,69 @@
+export function initializeSchema(db) {
+    db.pragma('journal_mode = WAL');
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS projects (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      root_path TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      details_json TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      created_by TEXT NOT NULL,
+      source TEXT NOT NULL,
+      session_id INTEGER,
+      FOREIGN KEY (project_id) REFERENCES projects(id),
+      FOREIGN KEY (session_id) REFERENCES sessions(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER NOT NULL,
+      title TEXT NOT NULL,
+      description TEXT,
+      status TEXT NOT NULL,
+      priority TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      closed_at TEXT,
+      origin_event_id INTEGER,
+      FOREIGN KEY (project_id) REFERENCES projects(id),
+      FOREIGN KEY (origin_event_id) REFERENCES events(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER NOT NULL,
+      started_at TEXT NOT NULL,
+      ended_at TEXT,
+      actor_type TEXT NOT NULL,
+      actor_name TEXT,
+      summary TEXT,
+      FOREIGN KEY (project_id) REFERENCES projects(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS artifacts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER NOT NULL,
+      path TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      note TEXT,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_events_project_time ON events(project_id, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+    CREATE INDEX IF NOT EXISTS idx_tasks_project_status ON tasks(project_id, status);
+    CREATE INDEX IF NOT EXISTS idx_sessions_project_active ON sessions(project_id, ended_at);
+    CREATE INDEX IF NOT EXISTS idx_artifacts_project_time ON artifacts(project_id, created_at DESC);
+  `);
+}

package/dist/lib/banner.js

@@ -0,0 +1,12 @@
+export const SIDECAR_MARK = '[■]─[▪]  sidecar';
+export const SIDECAR_TAGLINE = 'project memory for your work';
+export function bannerDisabled(argv = process.argv) {
+    return process.env.SIDECAR_NO_BANNER === '1' || argv.includes('--no-banner');
+}
+export function renderBanner(includeTagline = true) {
+    const lines = [SIDECAR_MARK, ''];
+    if (includeTagline) {
+        lines.push(SIDECAR_TAGLINE);
+    }
+    return lines.join('\n');
+}

package/dist/lib/db.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import Database from 'better-sqlite3';
+export function openDb(dbPath) {
+    return new Database(dbPath);
+}
+export function migrate(db) {
+    db.pragma('journal_mode = WAL');
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts TEXT NOT NULL,
+      type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      tags_json TEXT NOT NULL DEFAULT '[]'
+    );
+
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'open',
+      priority TEXT NOT NULL DEFAULT 'medium',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts DESC);
+    CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+    CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+  `);
+}
+export function ensureSidecarDir(sidecarDir) {
+    if (!fs.existsSync(sidecarDir)) {
+        fs.mkdirSync(sidecarDir, { recursive: true });
+    }
+}

package/dist/lib/errors.js

@@ -0,0 +1,10 @@
+export class SidecarError extends Error {
+    code;
+    exitCode;
+    constructor(message, code = 'SIDE_CAR_ERROR', exitCode = 1) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.name = 'SidecarError';
+    }
+}

package/dist/lib/format.js

@@ -0,0 +1,14 @@
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function humanTime(iso) {
+    return new Date(iso).toLocaleString();
+}
+export function splitCsv(input) {
+    if (!input)
+        return [];
+    return input.split(',').map((x) => x.trim()).filter(Boolean);
+}
+export function stringifyJson(value) {
+    return JSON.stringify(value, null, 2);
+}

package/dist/lib/output.js

@@ -0,0 +1,20 @@
+import { stringifyJson } from './format.js';
+export function jsonSuccess(command, data) {
+    return {
+        ok: true,
+        command,
+        data,
+        errors: [],
+    };
+}
+export function jsonFailure(command, message) {
+    return {
+        ok: false,
+        command,
+        data: null,
+        errors: [message],
+    };
+}
+export function printJsonEnvelope(payload) {
+    console.log(stringifyJson(payload));
+}

package/dist/lib/paths.js

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const SIDECAR_DIR = '.sidecar';
+export function getSidecarPaths(rootPath) {
+    const sidecarPath = path.join(rootPath, SIDECAR_DIR);
+    return {
+        rootPath,
+        sidecarPath,
+        dbPath: path.join(sidecarPath, 'sidecar.db'),
+        configPath: path.join(sidecarPath, 'config.json'),
+        preferencesPath: path.join(sidecarPath, 'preferences.json'),
+        agentsPath: path.join(sidecarPath, 'AGENTS.md'),
+        summaryPath: path.join(sidecarPath, 'summary.md'),
+    };
+}
+export function findSidecarRoot(startDir = process.cwd()) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (fs.existsSync(path.join(current, SIDECAR_DIR))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}

package/dist/lib/validation.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export const eventTypeSchema = z.enum([
+    'note',
+    'worklog',
+    'decision',
+    'task_update',
+    'summary',
+    'context',
+]);
+export const taskPrioritySchema = z.enum(['low', 'medium', 'high']);
+export const addEventSchema = z.object({
+    type: eventTypeSchema,
+    title: z.string().trim().min(1).max(140),
+    body: z.string().trim().min(1),
+    tags: z.array(z.string().trim().min(1)).default([]),
+});
+export const addTaskSchema = z.object({
+    title: z.string().trim().min(1).max(240),
+    priority: taskPrioritySchema.default('medium'),
+});
+export const completeTaskSchema = z.object({
+    id: z.number().int().positive(),
+});
+export function parseTags(input) {
+    if (!input)
+        return [];
+    return input
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+}

package/dist/services/artifact-service.js

@@ -0,0 +1,12 @@
+import { nowIso } from '../lib/format.js';
+export function addArtifact(db, input) {
+    const info = db
+        .prepare(`INSERT INTO artifacts (project_id, path, kind, note, created_at) VALUES (?, ?, ?, ?, ?)`)
+        .run(input.projectId, input.path, input.kind, input.note ?? null, nowIso());
+    return Number(info.lastInsertRowid);
+}
+export function listArtifacts(db, projectId) {
+    return db
+        .prepare(`SELECT id, path, kind, note, created_at FROM artifacts WHERE project_id = ? ORDER BY created_at DESC LIMIT 50`)
+        .all(projectId);
+}

package/dist/services/capabilities-service.js

@@ -0,0 +1,198 @@
+export function getCapabilitiesManifest(version) {
+    return {
+        schema_version: 1,
+        cli: {
+            name: 'sidecar',
+            version,
+        },
+        commands: [
+            {
+                name: 'init',
+                description: 'Initialize Sidecar in the current directory',
+                json_output: true,
+                arguments: [],
+                options: ['--force', '--name <project-name>', '--json'],
+            },
+            {
+                name: 'status',
+                description: 'Show Sidecar initialization status and activity counts',
+                json_output: true,
+                arguments: [],
+                options: ['--json'],
+            },
+            {
+                name: 'capabilities',
+                description: 'Show machine-readable CLI manifest',
+                json_output: true,
+                arguments: [],
+                options: ['--json'],
+            },
+            {
+                name: 'context',
+                description: 'Generate project context snapshot',
+                json_output: true,
+                arguments: [],
+                options: ['--limit <n>', '--format text|markdown|json', '--json'],
+            },
+            {
+                name: 'summary',
+                description: 'Summary operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'refresh',
+                        description: 'Regenerate .sidecar/summary.md',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--limit <n>', '--json'],
+                    },
+                ],
+            },
+            {
+                name: 'recent',
+                description: 'Show recent event timeline',
+                json_output: true,
+                arguments: [],
+                options: ['--type <event-type>', '--limit <n>', '--json'],
+            },
+            {
+                name: 'note',
+                description: 'Record a note event',
+                json_output: true,
+                arguments: ['<text>'],
+                options: ['--title <title>', '--by human|agent', '--session <id>', '--json'],
+            },
+            {
+                name: 'decision',
+                description: 'Decision operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'record',
+                        description: 'Record a decision',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--title <title>', '--summary <summary>', '--details <details>', '--by human|agent', '--session <id>', '--json'],
+                    },
+                ],
+            },
+            {
+                name: 'worklog',
+                description: 'Worklog operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'record',
+                        description: 'Record a worklog',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--goal <goal>', '--done <summary>', '--files <paths>', '--risks <text>', '--next <text>', '--by human|agent', '--session <id>', '--json'],
+                    },
+                ],
+            },
+            {
+                name: 'task',
+                description: 'Task operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'add',
+                        description: 'Create an open task',
+                        json_output: true,
+                        arguments: ['<title>'],
+                        options: ['--description <text>', '--priority low|medium|high', '--by human|agent', '--json'],
+                    },
+                    {
+                        name: 'done',
+                        description: 'Mark a task as done',
+                        json_output: true,
+                        arguments: ['<task-id>'],
+                        options: ['--by human|agent', '--json'],
+                    },
+                    {
+                        name: 'list',
+                        description: 'List tasks',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--status open|done|all', '--format table|json', '--json'],
+                    },
+                ],
+            },
+            {
+                name: 'session',
+                description: 'Session operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'start',
+                        description: 'Start a session',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--actor human|agent', '--name <actor-name>', '--json'],
+                    },
+                    {
+                        name: 'end',
+                        description: 'End the active session',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--summary <text>', '--json'],
+                    },
+                    {
+                        name: 'current',
+                        description: 'Show active session',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--json'],
+                    },
+                    {
+                        name: 'verify',
+                        description: 'Run lightweight session hygiene checks',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--json'],
+                    },
+                ],
+            },
+            {
+                name: 'doctor',
+                description: 'Alias for session verify',
+                json_output: true,
+                arguments: [],
+                options: ['--json'],
+            },
+            {
+                name: 'artifact',
+                description: 'Artifact operations',
+                json_output: true,
+                arguments: [],
+                options: [],
+                subcommands: [
+                    {
+                        name: 'add',
+                        description: 'Add an artifact reference',
+                        json_output: true,
+                        arguments: ['<path>'],
+                        options: ['--kind file|doc|screenshot|other', '--note <text>', '--json'],
+                    },
+                    {
+                        name: 'list',
+                        description: 'List recent artifacts',
+                        json_output: true,
+                        arguments: [],
+                        options: ['--json'],
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/services/context-service.js

@@ -0,0 +1,33 @@
+import { nowIso } from '../lib/format.js';
+export function buildContext(db, input) {
+    const project = db.prepare(`SELECT name, root_path FROM projects WHERE id = ?`).get(input.projectId);
+    const activeSession = db
+        .prepare(`SELECT id, started_at, actor_type, actor_name FROM sessions WHERE project_id = ? AND ended_at IS NULL ORDER BY started_at DESC LIMIT 1`)
+        .get(input.projectId);
+    const decisions = db
+        .prepare(`SELECT created_at, title, summary FROM events WHERE project_id = ? AND type = 'decision' ORDER BY created_at DESC LIMIT ?`)
+        .all(input.projectId, input.limit);
+    const worklogs = db
+        .prepare(`SELECT created_at, title, summary FROM events WHERE project_id = ? AND type = 'worklog' ORDER BY created_at DESC LIMIT ?`)
+        .all(input.projectId, input.limit);
+    const notes = db
+        .prepare(`SELECT created_at, title, summary FROM events WHERE project_id = ? AND type = 'note' ORDER BY created_at DESC LIMIT ?`)
+        .all(input.projectId, input.limit);
+    const openTasks = db
+        .prepare(`SELECT id, title, priority, updated_at FROM tasks WHERE project_id = ? AND status = 'open' ORDER BY updated_at DESC LIMIT ?`)
+        .all(input.projectId, input.limit);
+    const artifacts = db
+        .prepare(`SELECT path, kind, note, created_at FROM artifacts WHERE project_id = ? ORDER BY created_at DESC LIMIT ?`)
+        .all(input.projectId, input.limit);
+    return {
+        generatedAt: nowIso(),
+        projectName: project.name,
+        projectPath: project.root_path,
+        activeSession: activeSession ?? null,
+        recentDecisions: decisions,
+        recentWorklogs: worklogs,
+        notableNotes: notes,
+        openTasks,
+        recentArtifacts: artifacts,
+    };
+}

package/dist/services/event-service.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { nowIso, splitCsv } from '../lib/format.js';
+const createdBySchema = z.enum(['human', 'agent', 'system']);
+function normalizeArtifactPath(inputPath) {
+    const normalized = path.normalize(inputPath.trim()).replaceAll('\\', '/');
+    return normalized.startsWith('./') ? normalized.slice(2) : normalized;
+}
+export function getActiveSessionId(db, projectId) {
+    const row = db
+        .prepare(`SELECT id FROM sessions WHERE project_id = ? AND ended_at IS NULL ORDER BY started_at DESC LIMIT 1`)
+        .get(projectId);
+    return row?.id ?? null;
+}
+export function createEvent(db, input) {
+    const createdBy = createdBySchema.parse(input.createdBy ?? 'human');
+    const source = input.source ?? 'cli';
+    const info = db
+        .prepare(`
+      INSERT INTO events (project_id, type, title, summary, details_json, created_at, created_by, source, session_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+        .run(input.projectId, input.type, input.title, input.summary, JSON.stringify(input.details ?? {}), nowIso(), createdBy, source, input.sessionId ?? null);
+    return Number(info.lastInsertRowid);
+}
+export function addNote(db, input) {
+    const title = input.title?.trim() || 'Note';
+    return createEvent(db, {
+        projectId: input.projectId,
+        type: 'note',
+        title,
+        summary: input.text,
+        details: { text: input.text },
+        createdBy: input.by,
+        sessionId: input.sessionId,
+    });
+}
+export function addDecision(db, input) {
+    return createEvent(db, {
+        projectId: input.projectId,
+        type: 'decision',
+        title: input.title,
+        summary: input.summary,
+        details: { details: input.details ?? null },
+        createdBy: input.by,
+        sessionId: input.sessionId,
+    });
+}
+export function addWorklog(db, input) {
+    const files = Array.from(new Set(splitCsv(input.files).map(normalizeArtifactPath).filter(Boolean)));
+    const goal = input.goal?.trim();
+    const done = input.done.trim();
+    const risks = input.risks?.trim() || null;
+    const next = input.next?.trim() || null;
+    const title = goal ? `Worklog: ${goal}` : 'Worklog entry';
+    const eventId = createEvent(db, {
+        projectId: input.projectId,
+        type: 'worklog',
+        title,
+        summary: done,
+        details: {
+            goal: goal ?? null,
+            done,
+            files,
+            risks,
+            next,
+        },
+        createdBy: input.by,
+        sessionId: input.sessionId,
+    });
+    return { eventId, files };
+}
+export function listRecentEvents(db, input) {
+    if (input.type) {
+        return db
+            .prepare(`SELECT id, type, title, summary, created_by, created_at FROM events WHERE project_id = ? AND type = ? ORDER BY created_at DESC LIMIT ?`)
+            .all(input.projectId, input.type, input.limit);
+    }
+    return db
+        .prepare(`SELECT id, type, title, summary, created_by, created_at FROM events WHERE project_id = ? ORDER BY created_at DESC LIMIT ?`)
+        .all(input.projectId, input.limit);
+}

package/dist/services/session-service.js

@@ -0,0 +1,47 @@
+import { nowIso } from '../lib/format.js';
+export function currentSession(db, projectId) {
+    return db
+        .prepare(`SELECT * FROM sessions WHERE project_id = ? AND ended_at IS NULL ORDER BY started_at DESC LIMIT 1`)
+        .get(projectId);
+}
+export function startSession(db, input) {
+    const active = currentSession(db, input.projectId);
+    if (active)
+        return { ok: false, reason: 'A session is already active' };
+    const info = db
+        .prepare(`INSERT INTO sessions (project_id, started_at, ended_at, actor_type, actor_name, summary) VALUES (?, ?, NULL, ?, ?, NULL)`)
+        .run(input.projectId, nowIso(), input.actor, input.name ?? null);
+    return { ok: true, sessionId: Number(info.lastInsertRowid) };
+}
+export function endSession(db, input) {
+    const active = currentSession(db, input.projectId);
+    if (!active)
+        return { ok: false, reason: 'No active session found' };
+    db.prepare(`UPDATE sessions SET ended_at = ?, summary = ? WHERE id = ?`).run(nowIso(), input.summary ?? null, active.id);
+    return { ok: true, sessionId: active.id };
+}
+export function verifySessionHygiene(db, projectId, summaryRecentlyRefreshed) {
+    const warnings = [];
+    const active = currentSession(db, projectId);
+    if (active) {
+        const worklog = db
+            .prepare(`SELECT id FROM events WHERE project_id = ? AND type = 'worklog' AND session_id = ? LIMIT 1`)
+            .get(projectId, active.id);
+        if (!worklog)
+            warnings.push('Active session has no worklog yet.');
+    }
+    const openTasks = db.prepare(`SELECT COUNT(*) as count FROM tasks WHERE project_id = ? AND status = 'open'`).get(projectId);
+    if (openTasks.count > 0 && !summaryRecentlyRefreshed) {
+        warnings.push('Open tasks exist and summary was not refreshed recently.');
+    }
+    const recentWork = db
+        .prepare(`SELECT COUNT(*) as count FROM events WHERE project_id = ? AND type = 'worklog' AND created_at >= datetime('now', '-3 day')`)
+        .get(projectId);
+    const recentDecisions = db
+        .prepare(`SELECT COUNT(*) as count FROM events WHERE project_id = ? AND type = 'decision' AND created_at >= datetime('now', '-7 day')`)
+        .get(projectId);
+    if (recentWork.count > 0 && recentDecisions.count === 0) {
+        warnings.push('Recent worklogs exist but no recent decision was recorded.');
+    }
+    return warnings;
+}