sidecar-cli 0.1.0-beta.6 → 0.1.0-beta.8

package/README.md

@@ -11,15 +11,7 @@ Sidecar is a local-first, CLI-first project memory and recording tool for human
 - Keep project memory structured and local.
 - Make session handoffs easier for humans and agents.
 - Record decisions, work logs, tasks, notes, sessions, and artifacts in one stable CLI.
-- Generate deterministic context and summary outputs without any cloud or LLM dependency.
-
-## v1 scope
-
-- No cloud sync
-- No remote server
-- No GUI
-- No MCP server
-- No passive prompt capture
+- Generate deterministic context and summary outputs from local project data.
 
 ## Install
 
@@ -76,7 +68,7 @@ npm run dev -- --help
 Initialize in a project directory:
 
 ```bash
-npm run dev -- init
+sidecar init
 ```
 
 This creates:
@@ -86,6 +78,8 @@ This creates:
 - `.sidecar/preferences.json`
 - `.sidecar/AGENTS.md`
 - `.sidecar/summary.md`
+- `AGENTS.md` (repo root)
+- `CLAUDE.md` (repo root)
 
 Use `--force` to overwrite Sidecar-managed files.
 
@@ -161,6 +155,11 @@ npm run install:hooks
 ```
 
 This installs a non-blocking pre-commit reminder that runs `npm run sidecar:reminder`.
+If a pre-commit hook already exists, Sidecar will not overwrite it unless you run:
+
+```bash
+npm run install:hooks -- --force
+```
 
 Agents can discover the CLI surface programmatically with:
 
@@ -195,48 +194,5 @@ This makes Sidecar easy to automate from scripts and AI agents.
 
 ## Release and distribution
 
-Sidecar uses tag-based GitHub Actions releases.
-
-Tag formats:
-
-- stable: `v1.2.3`
-- beta: `v1.2.3-beta.1`
-- rc: `v1.2.3-rc.1`
-
-Behavior:
-
-- stable tags publish npm `latest`
-- beta tags publish npm `beta`
-- rc tags publish npm `rc`
-- all release tags create GitHub Releases and upload tarball assets
-- Homebrew tap updates are stable-only (beta/rc intentionally skipped)
-
-Workflows:
-
-- CI: `.github/workflows/ci.yml`
-- Release: `.github/workflows/release.yml`
-
-Required configuration:
-
-- `NPM_TOKEN` (secret)
-- `HOMEBREW_TAP_REPO` (variable, optional)
-- `HOMEBREW_TAP_GITHUB_TOKEN` (secret, optional)
-
-See [RELEASE.md](./RELEASE.md) for full release steps and examples.
-
-Quick preflight:
-
-```bash
-npm run release_check -- --tag v1.2.3
-```
-
-One-command release:
-
-```bash
-npm run release:stable -- --version 1.2.3
-npm run release:beta -- --version 1.2.3 --pre 1
-npm run release:rc -- --version 1.2.3 --pre 1
-
-# preview only (no commit/tag/push)
-npm run release:beta -- --version 1.2.3 --pre 1 --dry-run
-```
+See [RELEASE.md](./RELEASE.md) for publishing/release details.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for code structure and contribution guidelines.

package/dist/cli.js

@@ -12,7 +12,7 @@ import { jsonFailure, jsonSuccess, printJsonEnvelope } from './lib/output.js';
 import { bannerDisabled, renderBanner } from './lib/banner.js';
 import { getUpdateNotice } from './lib/update-check.js';
 import { requireInitialized } from './db/client.js';
-import { renderAgentsMarkdown } from './templates/agents.js';
+import { renderAgentsMarkdown, renderClaudeMarkdown } from './templates/agents.js';
 import { refreshSummaryFile } from './services/summary-service.js';
 import { buildContext } from './services/context-service.js';
 import { getCapabilitiesManifest } from './services/capabilities-service.js';
@@ -58,6 +58,25 @@ function respondSuccess(command, asJson, data, lines = []) {
         console.log(line);
     }
 }
+function summaryWasRefreshedRecently(db, projectId) {
+    return Boolean(db
+        .prepare(`SELECT id FROM events WHERE project_id = ? AND type = 'summary_generated' AND created_at >= datetime('now', '-3 day') LIMIT 1`)
+        .get(projectId));
+}
+function renderSessionHygiene(command, asJson, warnings) {
+    if (asJson) {
+        printJsonEnvelope(jsonSuccess(command, { warnings, healthy: warnings.length === 0 }));
+        return;
+    }
+    if (warnings.length === 0) {
+        console.log('Session hygiene looks good.');
+        return;
+    }
+    console.log('Session hygiene warnings:');
+    for (const warning of warnings) {
+        console.log(`- ${warning}`);
+    }
+}
 function renderContextText(data) {
     const lines = [];
     lines.push(`Project: ${data.projectName}`);
@@ -177,6 +196,15 @@ program
         const rootPath = process.cwd();
         const sidecar = getSidecarPaths(rootPath);
         const projectName = opts.name?.trim() || path.basename(rootPath);
+        if (fs.existsSync(sidecar.sidecarPath)) {
+            const stat = fs.lstatSync(sidecar.sidecarPath);
+            if (stat.isSymbolicLink()) {
+                fail('Refusing to initialize: .sidecar is a symbolic link. Remove it and run init again.');
+            }
+            if (!stat.isDirectory()) {
+                fail('Refusing to initialize: .sidecar exists but is not a directory.');
+            }
+        }
         if (fs.existsSync(sidecar.sidecarPath) && !opts.force) {
             fail('Sidecar is already initialized in this project. Re-run with --force to recreate .sidecar files.');
         }
@@ -187,6 +215,12 @@ program
             sidecar.agentsPath,
             sidecar.summaryPath,
         ];
+        const shouldWriteRootAgents = Boolean(opts.force) || !fs.existsSync(sidecar.rootAgentsPath);
+        const shouldWriteRootClaude = Boolean(opts.force) || !fs.existsSync(sidecar.rootClaudePath);
+        if (shouldWriteRootAgents)
+            files.push(sidecar.rootAgentsPath);
+        if (shouldWriteRootClaude)
+            files.push(sidecar.rootClaudePath);
         fs.mkdirSync(sidecar.sidecarPath, { recursive: true });
         if (opts.force) {
             for (const file of [
@@ -220,6 +254,12 @@ program
             output: { humanTime: true },
         }));
         fs.writeFileSync(sidecar.agentsPath, renderAgentsMarkdown(projectName));
+        if (shouldWriteRootAgents) {
+            fs.writeFileSync(sidecar.rootAgentsPath, renderAgentsMarkdown(projectName));
+        }
+        if (shouldWriteRootClaude) {
+            fs.writeFileSync(sidecar.rootClaudePath, renderClaudeMarkdown(projectName));
+        }
         const db2 = new Database(sidecar.dbPath);
         const refreshed = refreshSummaryFile(db2, rootPath, 1, 10);
         db2.close();
@@ -632,22 +672,9 @@ session
     const command = 'session verify';
     try {
         const { db, projectId } = requireInitialized();
-        const summaryRecent = Boolean(db
-            .prepare(`SELECT id FROM events WHERE project_id = ? AND type = 'summary_generated' AND created_at >= datetime('now', '-3 day') LIMIT 1`)
-            .get(projectId));
-        const warnings = verifySessionHygiene(db, projectId, summaryRecent);
+        const warnings = verifySessionHygiene(db, projectId, summaryWasRefreshedRecently(db, projectId));
         db.close();
-        if (opts.json)
-            printJsonEnvelope(jsonSuccess(command, { warnings, healthy: warnings.length === 0 }));
-        else {
-            if (warnings.length === 0) {
-                console.log('Session hygiene looks good.');
-                return;
-            }
-            console.log('Session hygiene warnings:');
-            for (const w of warnings)
-                console.log(`- ${w}`);
-        }
+        renderSessionHygiene(command, Boolean(opts.json), warnings);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);
@@ -662,22 +689,9 @@ program
     const command = 'doctor';
     try {
         const { db, projectId } = requireInitialized();
-        const summaryRecent = Boolean(db
-            .prepare(`SELECT id FROM events WHERE project_id = ? AND type = 'summary_generated' AND created_at >= datetime('now', '-3 day') LIMIT 1`)
-            .get(projectId));
-        const warnings = verifySessionHygiene(db, projectId, summaryRecent);
+        const warnings = verifySessionHygiene(db, projectId, summaryWasRefreshedRecently(db, projectId));
         db.close();
-        if (opts.json)
-            printJsonEnvelope(jsonSuccess(command, { warnings, healthy: warnings.length === 0 }));
-        else {
-            if (warnings.length === 0) {
-                console.log('Session hygiene looks good.');
-                return;
-            }
-            console.log('Session hygiene warnings:');
-            for (const w of warnings)
-                console.log(`- ${w}`);
-        }
+        renderSessionHygiene(command, Boolean(opts.json), warnings);
     }
     catch (err) {
         handleCommandError(command, Boolean(opts.json), err);

package/dist/lib/paths.js

@@ -6,6 +6,8 @@ export function getSidecarPaths(rootPath) {
     return {
         rootPath,
         sidecarPath,
+        rootAgentsPath: path.join(rootPath, 'AGENTS.md'),
+        rootClaudePath: path.join(rootPath, 'CLAUDE.md'),
         dbPath: path.join(sidecarPath, 'sidecar.db'),
         configPath: path.join(sidecarPath, 'config.json'),
         preferencesPath: path.join(sidecarPath, 'preferences.json'),
@@ -16,8 +18,11 @@ export function getSidecarPaths(rootPath) {
 export function findSidecarRoot(startDir = process.cwd()) {
     let current = path.resolve(startDir);
     while (true) {
-        if (fs.existsSync(path.join(current, SIDECAR_DIR))) {
-            return current;
+        const candidate = path.join(current, SIDECAR_DIR);
+        if (fs.existsSync(candidate)) {
+            const stat = fs.lstatSync(candidate);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                return current;
         }
         const parent = path.dirname(current);
         if (parent === current)

package/dist/templates/agents.js

@@ -1,6 +1,8 @@
-export function renderAgentsMarkdown(projectName) {
+function renderSharedGuide(projectName, heading) {
     return `# Sidecar Agent Guide
 
+${heading}
+
 Sidecar is the local project memory tool for this repository.
 
 ## MUST before final response
@@ -71,3 +73,9 @@ Run this before final response to catch missed Sidecar logging:
 Project: ${projectName}.
 `;
 }
+export function renderAgentsMarkdown(projectName) {
+    return renderSharedGuide(projectName, 'Use this guide for AI coding agents in this repository.');
+}
+export function renderClaudeMarkdown(projectName) {
+    return renderSharedGuide(projectName, 'Claude-specific note: treat this as required workflow, not advisory context.');
+}

package/package.json

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

package/dist/lib/validation.js

@@ -1,31 +0,0 @@
-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);
-}