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

package/README.md

@@ -23,16 +23,29 @@ Sidecar is a local-first, CLI-first project memory and recording tool for human
 
 ## Install
 
-Install globally:
+Install globally (stable):
 
 ```bash
 npm install -g sidecar-cli
 ```
 
+Install beta:
+
+```bash
+npm install -g sidecar-cli@beta
+```
+
+Install rc:
+
+```bash
+npm install -g sidecar-cli@rc
+```
+
 Or run without install:
 
 ```bash
 npx sidecar-cli --help
+npx sidecar-cli@beta --help
 ```
 
 Requirements:
@@ -70,6 +83,7 @@ This creates:
 
 - `.sidecar/sidecar.db`
 - `.sidecar/config.json`
+- `.sidecar/preferences.json`
 - `.sidecar/AGENTS.md`
 - `.sidecar/summary.md`
 
@@ -130,14 +144,23 @@ 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.
+
+Required minimum for any code change:
+
+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`
 
-That file explains:
+Optional local enforcement:
+
+```bash
+npm run install:hooks
+```
 
-- this repo uses Sidecar
-- required workflow for agents
-- when to record notes, decisions, worklogs, and tasks
-- recommended commands
-- a practical session checklist and example
+This installs a non-blocking pre-commit reminder that runs `npm run sidecar:reminder`.
 
 Agents can discover the CLI surface programmatically with:
 

package/dist/cli.js

@@ -10,6 +10,7 @@ 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 { requireInitialized } from './db/client.js';
 import { renderAgentsMarkdown } from './templates/agents.js';
 import { refreshSummaryFile } from './services/summary-service.js';
@@ -149,6 +150,20 @@ function renderContextMarkdown(data) {
 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');
+function maybePrintUpdateNotice() {
+    const jsonRequested = process.argv.includes('--json');
+    const notice = getUpdateNotice({
+        packageName: 'sidecar-cli',
+        currentVersion: pkg.version,
+        skip: jsonRequested,
+    });
+    if (!notice)
+        return;
+    const installTag = notice.channel === 'latest' ? 'latest' : notice.channel;
+    console.log('');
+    console.log(`Update available: ${pkg.version} -> ${notice.latestVersion}`);
+    console.log(`Run: npm install -g sidecar-cli@${installTag}`);
+}
 program
     .command('init')
     .description('Initialize Sidecar in the current directory')
@@ -722,6 +737,8 @@ if (process.argv.length === 2) {
         console.log('');
     }
     program.outputHelp();
+    maybePrintUpdateNotice();
     process.exit(0);
 }
 program.parse(process.argv);
+maybePrintUpdateNotice();

package/dist/lib/update-check.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { gt as semverGt } from 'semver';
+const CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
+function getCacheFilePath() {
+    return path.join(os.homedir(), '.sidecar-cli', 'update-check.json');
+}
+function loadCache() {
+    const file = getCacheFilePath();
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveCache(cache) {
+    const file = getCacheFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache));
+}
+export function detectReleaseChannel(version) {
+    if (version.includes('-beta.'))
+        return 'beta';
+    if (version.includes('-rc.'))
+        return 'rc';
+    return 'latest';
+}
+function shouldCheckNow(cache) {
+    if (!cache?.lastCheckedAt)
+        return true;
+    const last = Date.parse(cache.lastCheckedAt);
+    if (Number.isNaN(last))
+        return true;
+    return Date.now() - last >= CHECK_INTERVAL_MS;
+}
+function fetchDistTags(pkgName) {
+    try {
+        const raw = execFileSync('npm', ['view', pkgName, 'dist-tags', '--json'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        }).trim();
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getUpdateNotice(options) {
+    if (options.skip || process.env.SIDECAR_NO_UPDATE_CHECK === '1')
+        return null;
+    const channel = detectReleaseChannel(options.currentVersion);
+    const cache = loadCache();
+    if (!shouldCheckNow(cache)) {
+        const cachedVersion = cache?.byChannel?.[channel];
+        if (!cachedVersion)
+            return null;
+        return semverGt(cachedVersion, options.currentVersion) ? { latestVersion: cachedVersion, channel } : null;
+    }
+    const tags = fetchDistTags(options.packageName);
+    if (!tags)
+        return null;
+    const latestVersion = tags[channel];
+    if (!latestVersion)
+        return null;
+    saveCache({
+        lastCheckedAt: new Date().toISOString(),
+        byChannel: {
+            ...(cache?.byChannel ?? {}),
+            [channel]: latestVersion,
+        },
+    });
+    return semverGt(latestVersion, options.currentVersion) ? { latestVersion, channel } : null;
+}

package/dist/templates/agents.js

@@ -3,36 +3,71 @@ 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
 
-1. Run \`sidecar context --format markdown\`.
-2. Do the work.
-3. Record updates:
-   - decision: \`sidecar decision record ...\`
-   - worklog: \`sidecar worklog record ...\`
-   - follow-up task: \`sidecar task add ...\`
-4. Run \`sidecar summary refresh\`.
+For any code change, run these in order before final response:
+
+1. \`sidecar context --format markdown\`
+2. implement changes
+3. \`sidecar worklog record ...\`
+4. if behavior/design/architecture changed: \`sidecar decision record ...\`
+5. \`sidecar summary refresh\`
+
+## Scope rules
+
+- 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
 
-## Commands to use
+- [ ] Context reviewed
+  - \`sidecar context --format markdown\`
+- [ ] Work recorded
+  - \`sidecar worklog record --done "<what changed>" --files <paths> --by agent\`
+- [ ] Decision recorded when needed
+  - \`sidecar decision record --title "<decision>" --summary "<why>" --by agent\`
+- [ ] Follow-up task created when needed
+  - \`sidecar task add "<follow-up>" --priority medium --by agent\`
+- [ ] Summary refreshed
+  - \`sidecar summary refresh\`
+
+## Command patterns
 
 - Context: \`sidecar context --format markdown\`
-- Decision: \`sidecar decision record --title "<title>" --summary "<summary>" --by agent\`
 - Worklog: \`sidecar worklog record --done "<what changed>" --files src/a.ts,src/b.ts --by agent\`
+- Decision: \`sidecar decision record --title "<title>" --summary "<summary>" --by agent\`
 - Task: \`sidecar task add "<follow-up>" --priority medium --by agent\`
 - Summary: \`sidecar summary refresh\`
 
-## Example workflow
+## Example: small feature build
 
 \`\`\`bash
 sidecar context --format markdown
-sidecar session start --actor agent --name codex
-sidecar decision record --title "Choose SQLite" --summary "Local, deterministic storage" --by agent
-sidecar worklog record --goal "Refactor context output" --done "Improved markdown and json context payload" --files src/cli.ts,src/services/context-service.ts --by agent
-sidecar task add "Add integration test for context output" --priority medium --by agent
+# implement small todo app feature in src/app.ts and src/todo.ts
+sidecar worklog record --goal "todo feature" --done "Added todo CRUD handlers and wired routes" --files src/app.ts,src/todo.ts --by agent
+sidecar decision record --title "Use in-memory store for v1" --summary "Keeps implementation simple for initial feature" --by agent
+sidecar task add "Persist todos to sqlite" --priority medium --by agent
 sidecar summary refresh
-sidecar session end --summary "Context and summary updates complete"
 \`\`\`
 
+## Optional hygiene reminder
+
+Run this before final response to catch missed Sidecar logging:
+
+- \`npm run sidecar:reminder\`
+
 Project: ${projectName}.
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecar-cli",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",
@@ -13,7 +13,9 @@
     "release:cut": "node scripts/cut-release.mjs",
     "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"
+    "release:rc": "node scripts/cut-release.mjs --channel rc",
+    "sidecar:reminder": "node scripts/sidecar-reminder.mjs",
+    "install:hooks": "node scripts/install-git-hooks.mjs"
   },
   "keywords": [],
   "author": "",
@@ -27,11 +29,13 @@
     "better-sqlite3": "^12.8.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
+    "semver": "^7.7.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.5.0",
+    "@types/semver": "^7.7.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },