sidecar-cli 0.1.1-beta.1 → 0.1.1-beta.3

package/README.md

@@ -103,6 +103,7 @@ Global:
 
 - `sidecar init [--force] [--name <project-name>] [--json]`
 - `sidecar status [--json]`
+- `sidecar ui [--no-open] [--port <port>] [--install-only] [--project <path>] [--reinstall]`
 - `sidecar capabilities --json`
 - `sidecar help`
 
@@ -216,6 +217,50 @@ 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
+
 ## JSON output
 
 Most commands support `--json` and return structured output:

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';
@@ -166,6 +167,14 @@ function renderContextMarkdown(data) {
     }
     return lines.join('\n');
 }
+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 +192,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')

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

@@ -20,6 +20,13 @@ export function getCapabilitiesManifest(version) {
                 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',

package/package.json

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