@rely-ai/caliber 1.25.0 → 1.25.1-dev.1773933794

package/dist/bin.js

@@ -27,6 +27,8 @@ __export(constants_exports, {
   BACKUPS_DIR: () => BACKUPS_DIR,
   CALIBER_DIR: () => CALIBER_DIR,
   LEARNING_DIR: () => LEARNING_DIR,
+  LEARNING_FINALIZE_LOG: () => LEARNING_FINALIZE_LOG,
+  LEARNING_LAST_ERROR_FILE: () => LEARNING_LAST_ERROR_FILE,
   LEARNING_MAX_EVENTS: () => LEARNING_MAX_EVENTS,
   LEARNING_ROI_FILE: () => LEARNING_ROI_FILE,
   LEARNING_SESSION_FILE: () => LEARNING_SESSION_FILE,
@@ -37,7 +39,7 @@ __export(constants_exports, {
 });
 import path2 from "path";
 import os from "os";
-var AUTH_DIR, CALIBER_DIR, MANIFEST_FILE, BACKUPS_DIR, LEARNING_DIR, LEARNING_SESSION_FILE, LEARNING_STATE_FILE, LEARNING_MAX_EVENTS, LEARNING_ROI_FILE, PERSONAL_LEARNINGS_FILE, MIN_SESSIONS_FOR_COMPARISON;
+var AUTH_DIR, CALIBER_DIR, MANIFEST_FILE, BACKUPS_DIR, LEARNING_DIR, LEARNING_SESSION_FILE, LEARNING_STATE_FILE, LEARNING_MAX_EVENTS, LEARNING_ROI_FILE, PERSONAL_LEARNINGS_FILE, LEARNING_FINALIZE_LOG, LEARNING_LAST_ERROR_FILE, MIN_SESSIONS_FOR_COMPARISON;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -51,6 +53,8 @@ var init_constants = __esm({
     LEARNING_MAX_EVENTS = 500;
     LEARNING_ROI_FILE = "roi-stats.json";
     PERSONAL_LEARNINGS_FILE = path2.join(AUTH_DIR, "personal-learnings.md");
+    LEARNING_FINALIZE_LOG = "finalize.log";
+    LEARNING_LAST_ERROR_FILE = "last-error.json";
     MIN_SESSIONS_FOR_COMPARISON = 3;
   }
 });
@@ -586,7 +590,7 @@ var init_lock = __esm({
 // src/cli.ts
 import { Command } from "commander";
 import fs45 from "fs";
-import path35 from "path";
+import path36 from "path";
 import { fileURLToPath } from "url";
 
 // src/commands/init.ts
@@ -2648,6 +2652,11 @@ DO NOT extract:
 - General programming best practices everyone already knows
 - Summaries of successful routine operations that need no special handling
 - Anything already covered in the existing CLAUDE.md
+- **One-time debugging artifacts** \u2014 fixes for a specific bug that was resolved in this session and won't recur (e.g. "fixed the stream parser by adding a null check at line 42"). Only extract if the pattern will help future sessions avoid the same trap.
+- **Session-specific file paths, worktree locations, or branch names** \u2014 these are ephemeral and won't apply to future sessions
+- **Implementation details of a feature being built** \u2014 the learning should be about HOW to work in this project, not WHAT was built
+
+The litmus test for every learning: "Would a different developer, working on a DIFFERENT task in this same repo next week, benefit from knowing this?" If the answer is no \u2014 if it only matters for the exact problem being debugged today \u2014 do NOT include it.
 
 From these observations, produce:
 
@@ -2681,6 +2690,9 @@ Bad examples (do NOT produce these):
 - "The codebase uses TypeScript with strict mode" (describes code, not actionable)
 - "Components follow a pattern of X" (describes architecture, not operational)
 - "The project has a scoring module" (summarizes code structure)
+- "Cursor provider with \`--print --output-format stream-json\` outputs multiple events" (implementation detail of a specific feature, not a reusable pattern)
+- "When merging to \`next\`, use the worktree at \`/path/to/worktree\`" (session-specific path, won't apply next week)
+- "Fixed the lock bug by adding \`process.kill(pid, 0)\`" (one-time bug fix, not a reusable lesson)
 - Any bullet without a **[type]** prefix
 
 Rules for the learned section:
@@ -3412,15 +3424,15 @@ init_config();
 // src/utils/dependencies.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
-function readFileOrNull2(path37) {
+function readFileOrNull2(path38) {
   try {
-    return readFileSync2(path37, "utf-8");
+    return readFileSync2(path38, "utf-8");
   } catch {
     return null;
   }
 }
-function readJsonOrNull(path37) {
-  const content = readFileOrNull2(path37);
+function readJsonOrNull(path38) {
+  const content = readFileOrNull2(path38);
   if (!content) return null;
   try {
     return JSON.parse(content);
@@ -4046,11 +4058,38 @@ function appendPreCommitBlock(content) {
 function getCursorPreCommitRule() {
   return { filename: CURSOR_RULE_FILENAME, content: CURSOR_RULE_CONTENT };
 }
+var LEARNINGS_BLOCK_START = "<!-- caliber:managed:learnings -->";
+var LEARNINGS_BLOCK_END = "<!-- /caliber:managed:learnings -->";
+var LEARNINGS_BLOCK = `${LEARNINGS_BLOCK_START}
+## Session Learnings
+
+Read \`CALIBER_LEARNINGS.md\` for patterns and anti-patterns learned from previous sessions.
+These are auto-extracted from real tool usage \u2014 treat them as project-specific rules.
+${LEARNINGS_BLOCK_END}`;
+var CURSOR_LEARNINGS_FILENAME = "caliber-learnings.mdc";
+var CURSOR_LEARNINGS_CONTENT = `---
+description: Reference session-learned patterns from CALIBER_LEARNINGS.md
+alwaysApply: true
+---
+Read \`CALIBER_LEARNINGS.md\` for patterns and anti-patterns learned from previous sessions.
+These are auto-extracted from real tool usage \u2014 treat them as project-specific rules.
+`;
+function hasLearningsBlock(content) {
+  return content.includes(LEARNINGS_BLOCK_START);
+}
+function appendLearningsBlock(content) {
+  if (hasLearningsBlock(content)) return content;
+  const trimmed = content.trimEnd();
+  return trimmed + "\n\n" + LEARNINGS_BLOCK + "\n";
+}
+function getCursorLearningsRule() {
+  return { filename: CURSOR_LEARNINGS_FILENAME, content: CURSOR_LEARNINGS_CONTENT };
+}
 
 // src/writers/claude/index.ts
 function writeClaudeConfig(config) {
   const written = [];
-  fs9.writeFileSync("CLAUDE.md", appendPreCommitBlock(config.claudeMd));
+  fs9.writeFileSync("CLAUDE.md", appendLearningsBlock(appendPreCommitBlock(config.claudeMd)));
   written.push("CLAUDE.md");
   if (config.skills?.length) {
     for (const skill of config.skills) {
@@ -4094,7 +4133,8 @@ function writeCursorConfig(config) {
     written.push(".cursorrules");
   }
   const preCommitRule = getCursorPreCommitRule();
-  const allRules = [...config.rules || [], preCommitRule];
+  const learningsRule = getCursorLearningsRule();
+  const allRules = [...config.rules || [], preCommitRule, learningsRule];
   const rulesDir = path10.join(".cursor", "rules");
   if (!fs10.existsSync(rulesDir)) fs10.mkdirSync(rulesDir, { recursive: true });
   for (const rule of allRules) {
@@ -4142,7 +4182,7 @@ import fs11 from "fs";
 import path11 from "path";
 function writeCodexConfig(config) {
   const written = [];
-  fs11.writeFileSync("AGENTS.md", appendPreCommitBlock(config.agentsMd));
+  fs11.writeFileSync("AGENTS.md", appendLearningsBlock(appendPreCommitBlock(config.agentsMd)));
   written.push("AGENTS.md");
   if (config.skills?.length) {
     for (const skill of config.skills) {
@@ -4170,7 +4210,7 @@ function writeGithubCopilotConfig(config) {
   const written = [];
   if (config.instructions) {
     fs12.mkdirSync(".github", { recursive: true });
-    fs12.writeFileSync(path12.join(".github", "copilot-instructions.md"), appendPreCommitBlock(config.instructions));
+    fs12.writeFileSync(path12.join(".github", "copilot-instructions.md"), appendLearningsBlock(appendPreCommitBlock(config.instructions)));
     written.push(".github/copilot-instructions.md");
   }
   if (config.instructionFiles?.length) {
@@ -7105,11 +7145,11 @@ function countIssuePoints(issues) {
 }
 async function scoreAndRefine(setup, dir, sessionHistory, callbacks) {
   const existsCache = /* @__PURE__ */ new Map();
-  const cachedExists = (path37) => {
-    const cached = existsCache.get(path37);
+  const cachedExists = (path38) => {
+    const cached = existsCache.get(path38);
     if (cached !== void 0) return cached;
-    const result = existsSync9(path37);
-    existsCache.set(path37, result);
+    const result = existsSync9(path38);
+    existsCache.set(path38, result);
     return result;
   };
   const projectStructure = collectProjectStructure(dir);
@@ -9222,7 +9262,7 @@ import path25 from "path";
 function writeRefreshDocs(docs) {
   const written = [];
   if (docs.claudeMd) {
-    fs33.writeFileSync("CLAUDE.md", appendPreCommitBlock(docs.claudeMd));
+    fs33.writeFileSync("CLAUDE.md", appendLearningsBlock(appendPreCommitBlock(docs.claudeMd)));
     written.push("CLAUDE.md");
   }
   if (docs.readmeMd) {
@@ -9251,7 +9291,7 @@ function writeRefreshDocs(docs) {
   }
   if (docs.copilotInstructions) {
     fs33.mkdirSync(".github", { recursive: true });
-    fs33.writeFileSync(path25.join(".github", "copilot-instructions.md"), appendPreCommitBlock(docs.copilotInstructions));
+    fs33.writeFileSync(path25.join(".github", "copilot-instructions.md"), appendLearningsBlock(appendPreCommitBlock(docs.copilotInstructions)));
     written.push(".github/copilot-instructions.md");
   }
   if (docs.copilotInstructionFiles) {
@@ -10020,6 +10060,7 @@ async function configCommand() {
 
 // src/commands/learn.ts
 import fs42 from "fs";
+import path33 from "path";
 import chalk23 from "chalk";
 
 // src/learner/stdin.ts
@@ -10150,10 +10191,17 @@ function acquireFinalizeLock() {
     try {
       const stat = fs39.statSync(lockPath);
       if (Date.now() - stat.mtimeMs < LOCK_STALE_MS) {
-        return false;
+        const pid = parseInt(fs39.readFileSync(lockPath, "utf-8").trim(), 10);
+        if (!isNaN(pid) && isProcessAlive(pid)) {
+          return false;
+        }
       }
     } catch {
     }
+    try {
+      fs39.unlinkSync(lockPath);
+    } catch {
+    }
   }
   try {
     fs39.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
@@ -10162,6 +10210,14 @@ function acquireFinalizeLock() {
     return false;
   }
 }
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function releaseFinalizeLock() {
   const lockPath = lockFilePath();
   try {
@@ -10621,6 +10677,27 @@ var MIN_EVENTS_FOR_ANALYSIS = 25;
 var MIN_EVENTS_AUTO = 10;
 var AUTO_SETTLE_MS = 200;
 var INCREMENTAL_INTERVAL = 50;
+function writeFinalizeError(message) {
+  try {
+    const errorPath = path33.join(LEARNING_DIR, LEARNING_LAST_ERROR_FILE);
+    if (!fs42.existsSync(LEARNING_DIR)) fs42.mkdirSync(LEARNING_DIR, { recursive: true });
+    fs42.writeFileSync(errorPath, JSON.stringify({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      error: message,
+      pid: process.pid
+    }, null, 2));
+  } catch {
+  }
+}
+function readFinalizeError() {
+  try {
+    const errorPath = path33.join(LEARNING_DIR, LEARNING_LAST_ERROR_FILE);
+    if (!fs42.existsSync(errorPath)) return null;
+    return JSON.parse(fs42.readFileSync(errorPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
 async function learnObserveCommand(options) {
   try {
     const raw = await readStdin();
@@ -10663,10 +10740,14 @@ async function learnObserveCommand(options) {
         const { resolveCaliber: resolveCaliber2 } = await Promise.resolve().then(() => (init_resolve_caliber(), resolve_caliber_exports));
         const bin = resolveCaliber2();
         const { spawn: spawn4 } = await import("child_process");
+        const logPath = path33.join(LEARNING_DIR, LEARNING_FINALIZE_LOG);
+        if (!fs42.existsSync(LEARNING_DIR)) fs42.mkdirSync(LEARNING_DIR, { recursive: true });
+        const logFd = fs42.openSync(logPath, "a");
         spawn4(bin, ["learn", "finalize", "--auto", "--incremental"], {
           detached: true,
-          stdio: "ignore"
+          stdio: ["ignore", logFd, logFd]
         }).unref();
+        fs42.closeSync(logFd);
       } catch {
       }
     }
@@ -10851,9 +10932,11 @@ async function learnFinalizeCommand(options) {
       console.log(chalk23.dim(`caliber: ${totalLearnings} learnings active \u2014 est. ~${t.estimatedSavingsTokens.toLocaleString()} tokens saved across ${t.totalSessionsWithLearnings} sessions`));
     }
   } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
     if (options?.force && !isAuto) {
-      console.error(chalk23.red("caliber: finalize failed \u2014"), err instanceof Error ? err.message : err);
+      console.error(chalk23.red("caliber: finalize failed \u2014"), errorMsg);
     }
+    writeFinalizeError(errorMsg);
   } finally {
     if (analyzed) {
       if (isIncremental) {
@@ -10943,6 +11026,15 @@ async function learnStatusCommand() {
   } else {
     console.log(`Last analysis: ${chalk23.dim("none")}`);
   }
+  const lastError = readFinalizeError();
+  if (lastError) {
+    console.log(`Last error: ${chalk23.red(lastError.error)}`);
+    console.log(chalk23.dim(`  at ${lastError.timestamp}`));
+    const logPath = path33.join(LEARNING_DIR, LEARNING_FINALIZE_LOG);
+    if (fs42.existsSync(logPath)) {
+      console.log(chalk23.dim(`  Full log: ${logPath}`));
+    }
+  }
   const learnedSection = readLearnedSection();
   if (learnedSection) {
     const lineCount = learnedSection.split("\n").filter(Boolean).length;
@@ -11194,7 +11286,7 @@ async function insightsCommand(options) {
 
 // src/commands/sources.ts
 import fs43 from "fs";
-import path33 from "path";
+import path34 from "path";
 import chalk25 from "chalk";
 async function sourcesListCommand() {
   const dir = process.cwd();
@@ -11210,9 +11302,9 @@ async function sourcesListCommand() {
   if (configSources.length > 0) {
     for (const source of configSources) {
       const sourcePath = source.path || source.url || "";
-      const exists = source.path ? fs43.existsSync(path33.resolve(dir, source.path)) : false;
+      const exists = source.path ? fs43.existsSync(path34.resolve(dir, source.path)) : false;
       const status = exists ? chalk25.green("reachable") : chalk25.red("not found");
-      const hasSummary = source.path && fs43.existsSync(path33.join(path33.resolve(dir, source.path), ".caliber", "summary.json"));
+      const hasSummary = source.path && fs43.existsSync(path34.join(path34.resolve(dir, source.path), ".caliber", "summary.json"));
       console.log(`  ${chalk25.bold(source.role || source.type)}  ${chalk25.dim(sourcePath)}`);
       console.log(`    Type: ${source.type}  Status: ${status}${hasSummary ? "  " + chalk25.cyan("has summary.json") : ""}`);
       if (source.description) console.log(`    ${chalk25.dim(source.description)}`);
@@ -11222,7 +11314,7 @@ async function sourcesListCommand() {
   if (workspaces.length > 0) {
     console.log(chalk25.dim("  Auto-detected workspaces:"));
     for (const ws of workspaces) {
-      const exists = fs43.existsSync(path33.resolve(dir, ws));
+      const exists = fs43.existsSync(path34.resolve(dir, ws));
       console.log(`    ${exists ? chalk25.green("\u25CF") : chalk25.red("\u25CF")} ${ws}`);
     }
     console.log("");
@@ -11230,7 +11322,7 @@ async function sourcesListCommand() {
 }
 async function sourcesAddCommand(sourcePath) {
   const dir = process.cwd();
-  const absPath = path33.resolve(dir, sourcePath);
+  const absPath = path34.resolve(dir, sourcePath);
   if (!fs43.existsSync(absPath)) {
     console.log(chalk25.red(`
   Path not found: ${sourcePath}
@@ -11246,7 +11338,7 @@ async function sourcesAddCommand(sourcePath) {
   }
   const existing = loadSourcesConfig(dir);
   const alreadyConfigured = existing.some(
-    (s) => s.path && path33.resolve(dir, s.path) === absPath
+    (s) => s.path && path34.resolve(dir, s.path) === absPath
   );
   if (alreadyConfigured) {
     console.log(chalk25.yellow(`
@@ -11295,7 +11387,7 @@ async function sourcesRemoveCommand(name) {
 
 // src/commands/publish.ts
 import fs44 from "fs";
-import path34 from "path";
+import path35 from "path";
 import chalk26 from "chalk";
 import ora7 from "ora";
 init_config();
@@ -11309,10 +11401,10 @@ async function publishCommand() {
   const spinner = ora7("Generating project summary...").start();
   try {
     const fingerprint = await collectFingerprint(dir);
-    const claudeMd = readFileOrNull(path34.join(dir, "CLAUDE.md"));
+    const claudeMd = readFileOrNull(path35.join(dir, "CLAUDE.md"));
     const topLevelDirs = fingerprint.fileTree.filter((f) => f.endsWith("/") && !f.includes("/")).map((f) => f.replace(/\/$/, ""));
     const summary = {
-      name: fingerprint.packageName || path34.basename(dir),
+      name: fingerprint.packageName || path35.basename(dir),
       version: "1.0.0",
       description: fingerprint.description || "",
       languages: fingerprint.languages,
@@ -11324,7 +11416,7 @@ async function publishCommand() {
       summary.conventions = claudeMd.slice(0, 2e3);
     }
     try {
-      const pkgContent = readFileOrNull(path34.join(dir, "package.json"));
+      const pkgContent = readFileOrNull(path35.join(dir, "package.json"));
       if (pkgContent) {
         const pkg3 = JSON.parse(pkgContent);
         if (pkg3.scripts) {
@@ -11337,14 +11429,14 @@ async function publishCommand() {
       }
     } catch {
     }
-    const outputDir = path34.join(dir, ".caliber");
+    const outputDir = path35.join(dir, ".caliber");
     if (!fs44.existsSync(outputDir)) {
       fs44.mkdirSync(outputDir, { recursive: true });
     }
-    const outputPath = path34.join(outputDir, "summary.json");
+    const outputPath = path35.join(outputDir, "summary.json");
     fs44.writeFileSync(outputPath, JSON.stringify(summary, null, 2) + "\n", "utf-8");
     spinner.succeed("Project summary published");
-    console.log(`  ${chalk26.green("\u2713")} ${path34.relative(dir, outputPath)}`);
+    console.log(`  ${chalk26.green("\u2713")} ${path35.relative(dir, outputPath)}`);
     console.log(chalk26.dim("\n  Other projects can now reference this repo as a source."));
     console.log(chalk26.dim("  When they run `caliber init`, they'll read this summary automatically.\n"));
   } catch (err) {
@@ -11356,9 +11448,9 @@ async function publishCommand() {
 }
 
 // src/cli.ts
-var __dirname = path35.dirname(fileURLToPath(import.meta.url));
+var __dirname = path36.dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(
-  fs45.readFileSync(path35.resolve(__dirname, "..", "package.json"), "utf-8")
+  fs45.readFileSync(path36.resolve(__dirname, "..", "package.json"), "utf-8")
 );
 var program = new Command();
 var displayVersion = process.env.CALIBER_LOCAL ? `${pkg.version}-local` : pkg.version;
@@ -11445,15 +11537,15 @@ learn.command("delete <index>").description("Delete a learning by its index numb
 
 // src/utils/version-check.ts
 import fs46 from "fs";
-import path36 from "path";
+import path37 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { execSync as execSync15 } from "child_process";
 import chalk27 from "chalk";
 import ora8 from "ora";
 import confirm2 from "@inquirer/confirm";
-var __dirname_vc = path36.dirname(fileURLToPath2(import.meta.url));
+var __dirname_vc = path37.dirname(fileURLToPath2(import.meta.url));
 var pkg2 = JSON.parse(
-  fs46.readFileSync(path36.resolve(__dirname_vc, "..", "package.json"), "utf-8")
+  fs46.readFileSync(path37.resolve(__dirname_vc, "..", "package.json"), "utf-8")
 );
 function getChannel(version) {
   const match = version.match(/-(dev|next)\./);
@@ -11478,7 +11570,7 @@ function isNewer(registry, current) {
 function getInstalledVersion() {
   try {
     const globalRoot = execSync15("npm root -g", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-    const pkgPath = path36.join(globalRoot, "@rely-ai", "caliber", "package.json");
+    const pkgPath = path37.join(globalRoot, "@rely-ai", "caliber", "package.json");
     return JSON.parse(fs46.readFileSync(pkgPath, "utf-8")).version;
   } catch {
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rely-ai/caliber",
-  "version": "1.25.0",
+  "version": "1.25.1-dev.1773933794",
   "description": "Analyze your codebase and generate optimized AI agent configs (CLAUDE.md, .cursorrules, skills) — no API key needed",
   "type": "module",
   "bin": {