sidecar-cli 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -144,14 +144,28 @@ sidecar session end --summary "Initialization and recording flow implemented"
 ## AI agent usage
 
 Sidecar generates `.sidecar/AGENTS.md` during `init`.
+This repo also includes a root `AGENTS.md` so the policy is visible before any `.sidecar` lookup.
 
-That file explains:
+Required minimum for any code change:
 
-- this repo uses Sidecar
-- required workflow for agents
-- when to record notes, decisions, worklogs, and tasks
-- recommended commands
-- a practical session checklist and example
+1. `sidecar context --format markdown`
+2. `sidecar worklog record --done "<what changed>" --files <paths> --by agent`
+3. if behavior/design changed: `sidecar decision record ...`
+4. if follow-up exists: `sidecar task add ...`
+5. `sidecar summary refresh`
+
+Optional local enforcement:
+
+```bash
+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:
 
@@ -214,6 +228,7 @@ Required configuration:
 - `HOMEBREW_TAP_GITHUB_TOKEN` (secret, optional)
 
 See [RELEASE.md](./RELEASE.md) for full release steps and examples.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for code structure and contribution guidelines.
 
 Quick preflight:
 

package/dist/cli.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,9 @@ program
             sidecar.agentsPath,
             sidecar.summaryPath,
         ];
+        const shouldWriteRootAgents = Boolean(opts.force) || !fs.existsSync(sidecar.rootAgentsPath);
+        if (shouldWriteRootAgents)
+            files.push(sidecar.rootAgentsPath);
         fs.mkdirSync(sidecar.sidecarPath, { recursive: true });
         if (opts.force) {
             for (const file of [
@@ -220,6 +251,9 @@ program
             output: { humanTime: true },
         }));
         fs.writeFileSync(sidecar.agentsPath, renderAgentsMarkdown(projectName));
+        if (shouldWriteRootAgents) {
+            fs.writeFileSync(sidecar.rootAgentsPath, renderAgentsMarkdown(projectName));
+        }
         const db2 = new Database(sidecar.dbPath);
         const refreshed = refreshSummaryFile(db2, rootPath, 1, 10);
         db2.close();
@@ -632,22 +666,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 +683,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,7 @@ export function getSidecarPaths(rootPath) {
     return {
         rootPath,
         sidecarPath,
+        rootAgentsPath: path.join(rootPath, 'AGENTS.md'),
         dbPath: path.join(sidecarPath, 'sidecar.db'),
         configPath: path.join(sidecarPath, 'config.json'),
         preferencesPath: path.join(sidecarPath, 'preferences.json'),
@@ -16,8 +17,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

@@ -3,6 +3,16 @@ export function renderAgentsMarkdown(projectName) {
 
 Sidecar is the local project memory tool for this repository.
 
+## MUST before final response
+
+If you changed code, you MUST run these commands in order:
+
+1. \`sidecar context --format markdown\`
+2. \`sidecar worklog record --done "<what changed>" --files <paths> --by agent\`
+3. if behavior/design/architecture changed: \`sidecar decision record --title "<decision>" --summary "<why>" --by agent\`
+4. if follow-up exists: \`sidecar task add "<follow-up>" --priority medium --by agent\`
+5. \`sidecar summary refresh\`
+
 ## Required workflow
 
 For any code change, run these in order before final response:
@@ -18,6 +28,7 @@ For any code change, run these in order before final response:
 - If files changed: always record a worklog.
 - If behavior/design choice changed: record a decision.
 - If follow-up work exists: add a task.
+- Never skip summary refresh after recording work.
 
 ## Definition of Done
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecar-cli",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.7",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",
@@ -14,7 +14,8 @@
     "release:stable": "node scripts/cut-release.mjs --channel stable",
     "release:beta": "node scripts/cut-release.mjs --channel beta",
     "release:rc": "node scripts/cut-release.mjs --channel rc",
-    "sidecar:reminder": "node scripts/sidecar-reminder.mjs"
+    "sidecar:reminder": "node scripts/sidecar-reminder.mjs",
+    "install:hooks": "node scripts/install-git-hooks.mjs"
   },
   "keywords": [],
   "author": "",

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);
-}