codebrief 1.3.0 → 1.4.0

package/README.md

@@ -279,7 +279,8 @@ npx codebrief [directory] [options]
 | `--dry-run` | Preview what would be generated |
 | `--refresh-snapshot` | Re-scan source files and update just the code snapshot |
 | `--reconfigure` | Re-prompt even if `.codebrief.json` exists |
-| `--check` | Check if the snapshot is stale (exit 0 = fresh, 1 = stale) |
+| `--check` | Check if the snapshot is stale via hash comparison (exit 0 = fresh, 1 = stale) |
+| `--check=timestamp` | Timestamp-only staleness check — instant, no file hashing (for shell hooks) |
 | `--max-tokens=N` | Set the token budget for the code snapshot |
 | `--generate-skills` | Generate Claude Code skill files |
 | `-v, --verbose` | Show detailed progress output |
@@ -296,7 +297,7 @@ This finds the `<!-- CODE SNAPSHOT -->` markers in your context file, re-scans s
 
 ## Shell Integration
 
-Automatically detect stale snapshots when you `cd` into a project:
+Automatically detect stale snapshots when you `cd` into a project. These hooks run in pure shell (no Node.js boot), so they add zero latency to your prompt:
 
 <details>
 <summary><strong>zsh</strong></summary>
@@ -305,7 +306,13 @@ Automatically detect stale snapshots when you `cd` into a project:
 # Add to ~/.zshrc
 chpwd() {
   if [[ -f .codebrief.json ]]; then
-    npx --yes codebrief --check 2>/dev/null
+    local ts days stale_days
+    ts=$(command grep -o '"snapshotGeneratedAt":[0-9]*' .codebrief.json 2>/dev/null | command grep -o '[0-9]*$')
+    [[ -z "$ts" ]] && return
+    stale_days=$(command grep -o '"staleDays":[0-9]*' .codebrief.json 2>/dev/null | command grep -o '[0-9]*$')
+    : "${stale_days:=7}"
+    days=$(( ($(date +%s) - ts / 1000) / 86400 ))
+    (( days > stale_days )) && echo "codebrief: snapshot is ${days}d old. Run: npx codebrief --refresh-snapshot"
   fi
 }
 ```
@@ -320,7 +327,13 @@ chpwd() {
 cd() {
   builtin cd "$@" || return
   if [[ -f .codebrief.json ]]; then
-    npx --yes codebrief --check 2>/dev/null
+    local ts days stale_days
+    ts=$(command grep -o '"snapshotGeneratedAt":[0-9]*' .codebrief.json 2>/dev/null | command grep -o '[0-9]*$')
+    [[ -z "$ts" ]] && return
+    stale_days=$(command grep -o '"staleDays":[0-9]*' .codebrief.json 2>/dev/null | command grep -o '[0-9]*$')
+    : "${stale_days:=7}"
+    days=$(( ($(date +%s) - ts / 1000) / 86400 ))
+    (( days > stale_days )) && echo "codebrief: snapshot is ${days}d old. Run: npx codebrief --refresh-snapshot"
   fi
 }
 ```
@@ -334,13 +347,20 @@ cd() {
 # Add to ~/.config/fish/conf.d/codebrief.fish
 function __codebrief_check --on-variable PWD
   if test -f .codebrief.json
-    npx --yes codebrief --check 2>/dev/null
+    set -l ts (command grep -o '"snapshotGeneratedAt":[0-9]*' .codebrief.json 2>/dev/null | command grep -o '[0-9]*\$')
+    test -z "$ts"; and return
+    set -l stale_days (command grep -o '"staleDays":[0-9]*' .codebrief.json 2>/dev/null | command grep -o '[0-9]*\$')
+    test -z "$stale_days"; and set stale_days 7
+    set -l days (math "( "(date +%s)" - $ts / 1000) / 86400")
+    test $days -gt $stale_days; and echo "codebrief: snapshot is "$days"d old. Run: npx codebrief --refresh-snapshot"
   end
 end
 ```
 
 </details>
 
+> **Tip:** Set `"staleDays": 14` in `.codebrief.json` to customize the threshold. For CI/pre-commit use the hash-based `--check` instead.
+
 ## Config File
 
 On first run, codebrief saves your answers to `.codebrief.json`:

package/dist/index.js

@@ -3411,11 +3411,13 @@ async function loadConfig(rootDir) {
     generatePerPackage: cfg.generatePerPackage ?? false,
     snapshotHash: cfg.snapshotHash,
     snapshotGeneratedAt: cfg.snapshotGeneratedAt,
-    language: cfg.language
+    language: cfg.language,
+    staleDays: cfg.staleDays
   };
 }
 async function saveConfig(rootDir, answers, snapshotHash, language) {
   const configPath = path6.join(rootDir, CONFIG_FILENAME);
+  const existing = await readJsonFile(configPath);
   const cfg = {
     _version: CONFIG_VERSION,
     ides: answers.ides,
@@ -3427,7 +3429,8 @@ async function saveConfig(rootDir, answers, snapshotHash, language) {
     stackCorrections: answers.stackCorrections,
     generatePerPackage: answers.generatePerPackage,
     ...snapshotHash ? { snapshotHash, snapshotGeneratedAt: Date.now() } : {},
-    ...language ? { language } : {}
+    ...language ? { language } : {},
+    ...existing?.staleDays != null ? { staleDays: existing.staleDays } : {}
   };
   await writeFileSafe(configPath, JSON.stringify(cfg, null, 2) + "\n");
 }
@@ -3585,6 +3588,11 @@ async function refreshSnapshot(rootDir) {
     updated = content.slice(0, startIdx) + newBlock + content.slice(endIdx);
   }
   await writeFileSafe(absPath, updated);
+  if (config) {
+    const answers = configToAnswers(config);
+    const newHash = await computeSnapshotHash(rootDir, config.language ?? detected.language);
+    await saveConfig(rootDir, answers, newHash, config.language ?? detected.language);
+  }
   p3.log.success(`Updated snapshot in ${theme.accent(found.path)}`);
 }
 
@@ -3773,7 +3781,7 @@ async function animateCommunities(communityCount) {
 }
 
 // src/index.ts
-var VERSION = true ? "1.3.0" : "0.0.0-dev";
+var VERSION = true ? "1.4.0" : "0.0.0-dev";
 var NAME = true ? "codebrief" : "codebrief";
 var DESCRIPTION = true ? "Bootstrap optimized AI context files for any project. Auto-detect stack, generate code snapshots, produce config for Claude Code, Cursor, Copilot, Windsurf, Cline, Continue, Aider, and more." : "";
 function printHelp() {
@@ -3790,7 +3798,8 @@ function printHelp() {
   console.log(`    ${theme.accent("--dry-run")}               Preview what would be generated`);
   console.log(`    ${theme.accent("--reconfigure")}           Re-prompt even if .codebrief.json exists`);
   console.log(`    ${theme.accent("--refresh-snapshot")}      Re-scan source files, update code snapshot only`);
-  console.log(`    ${theme.accent("--check")}                 Exit 0 if snapshot is fresh, 1 if stale`);
+  console.log(`    ${theme.accent("--check")}                 Exit 0 if snapshot is fresh, 1 if stale (hash-based)`);
+  console.log(`    ${theme.accent("--check=timestamp")}       Exit 0/1 based on age only (no Node.js needed in shell hooks)`);
   console.log(`    ${theme.accent("--max-tokens=N")}          Set the token budget for the code snapshot`);
   console.log(`    ${theme.accent("--generate-skills")}       Generate Claude Code skill files`);
   console.log(`    ${theme.accent("-v, --verbose")}           Show detailed progress output`);
@@ -3817,7 +3826,9 @@ async function main() {
   const dryRun = args.includes("--dry-run");
   const refresh = args.includes("--refresh-snapshot");
   const reconfigure = args.includes("--reconfigure");
-  const check = args.includes("--check");
+  const checkArg = args.find((a) => a === "--check" || a.startsWith("--check="));
+  const check = !!checkArg;
+  const checkTimestamp = checkArg === "--check=timestamp";
   const verbose = args.includes("--verbose") || args.includes("-v");
   const generateSkills = args.includes("--generate-skills");
   const maxTokensArg = args.find((a) => a.startsWith("--max-tokens="));
@@ -3842,6 +3853,20 @@ async function main() {
   };
   if (check) {
     const config = await loadConfig(rootDir);
+    if (checkTimestamp) {
+      if (!config?.snapshotGeneratedAt) {
+        process.exit(0);
+      }
+      const staleDays = config.staleDays ?? 7;
+      const daysSince = Math.floor(
+        (Date.now() - config.snapshotGeneratedAt) / (1e3 * 60 * 60 * 24)
+      );
+      if (daysSince > staleDays) {
+        console.log(`codebrief: snapshot is ${daysSince}d old. Run: npx codebrief --refresh-snapshot`);
+        process.exit(1);
+      }
+      process.exit(0);
+    }
     if (!config?.snapshotHash) {
       process.exit(0);
     }