runbrief 0.1.4 → 0.1.5

package/README.md

@@ -13,13 +13,13 @@ name used in the install command.
 Claude Code:
 
 ```sh
-claude mcp add --transport stdio --scope user brief -- npx -y runbrief@^0.1.4
+claude mcp add --transport stdio --scope user brief -- npx -y runbrief@^0.1.5
 ```
 
 Codex:
 
 ```sh
-codex mcp add brief -- npx -y runbrief@^0.1.4
+codex mcp add brief -- npx -y runbrief@^0.1.5
 ```
 
 Generic MCP configuration:
@@ -29,7 +29,7 @@ Generic MCP configuration:
   "mcpServers": {
     "brief": {
       "command": "npx",
-      "args": ["-y", "runbrief@^0.1.4"],
+      "args": ["-y", "runbrief@^0.1.5"],
       "env": {
         "BRIEF_CONNECTOR_DISTRIBUTION": "package"
       }
@@ -42,7 +42,7 @@ Brief works locally without an account. Connect a Brief workspace only when
 you want approved team context, derived scan sync, shared learnings, and hosted
 proof history.
 
-The published setup uses the compatible patch range (`^0.1.4`). Each fresh MCP
+The published setup uses the compatible patch range (`^0.1.5`). Each fresh MCP
 start resolves the latest compatible connector patch, so routine fixes do not
 require a reinstall. A new setup is needed only when a future release changes
 the supported minor or major version.
@@ -94,7 +94,7 @@ to another machine after redemption.
 To remove the local credential and pair again:
 
 ```bash
-npx -y runbrief@^0.1.4 cloud-logout
+npx -y runbrief@^0.1.5 cloud-logout
 ```
 
 The explicit `BRIEF_API_URL` + `BRIEF_API_KEY` environment path remains as an

package/dist/cli.js

@@ -27065,7 +27065,7 @@ var init_agentSetup = __esm({
       "ide",
       "generic"
     ];
-    briefPublishedPackageVersion = "0.1.4";
+    briefPublishedPackageVersion = "0.1.5";
     briefPublishedPackageSpec = `runbrief@${briefPublishedPackageVersion}`;
     briefPublishedPackageInstallSpec = `runbrief@^${briefPublishedPackageVersion}`;
     TARGET_LABELS = {
@@ -33949,6 +33949,7 @@ var init_dist2 = __esm({
     "use strict";
     init_types();
     init_utils();
+    init_localCache();
     init_localLearning();
     init_localReceipts();
     init_localHandoffs();
@@ -34704,16 +34705,156 @@ var init_cloud = __esm({
   }
 });
 
+// ../mcp/src/autoScan.ts
+async function autoSyncScanSummary(scan, repoRoot, env = process.env, fetcher = fetch) {
+  const fingerprint = scanFingerprintFor(repoRoot, scan);
+  const cloud = cloudSyncStatus(env);
+  if (!cloud.configured) {
+    return {
+      status: "skipped",
+      changed: false,
+      scannedAt: scan.scannedAt,
+      reason: cloud.reason ?? "Cloud sync is not configured."
+    };
+  }
+  const previous = readAutoScanState(repoRoot);
+  const now = Date.now();
+  const lastSuccessfulAt = previous?.lastSuccessfulAt ? Date.parse(previous.lastSuccessfulAt) : Number.NaN;
+  const lastAttemptedAt = previous?.lastAttemptedAt ? Date.parse(previous.lastAttemptedAt) : Number.NaN;
+  const sameState = previous?.fingerprint === fingerprint;
+  if (sameState && Number.isFinite(lastSuccessfulAt) && now - lastSuccessfulAt < successfulResyncMs) {
+    return {
+      status: "unchanged",
+      changed: false,
+      scannedAt: scan.scannedAt,
+      reason: "The hosted map already matches this repo state."
+    };
+  }
+  if (sameState && Number.isFinite(lastAttemptedAt) && !Number.isFinite(lastSuccessfulAt) && now - lastAttemptedAt < failedSyncRetryMs) {
+    return {
+      status: "throttled",
+      changed: false,
+      scannedAt: scan.scannedAt,
+      reason: "The previous map sync failed recently; Brief will retry shortly."
+    };
+  }
+  const attemptedAt = new Date(now).toISOString();
+  const cloudSync = await syncScanSummary(scan, repoRoot, env, fetcher);
+  if (cloudSync.status === "accepted") {
+    writeBriefCacheFile(
+      repoRoot,
+      autoScanStateFile,
+      `${JSON.stringify(
+        {
+          fingerprint,
+          lastAttemptedAt: attemptedAt,
+          lastSuccessfulAt: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      )}
+`
+    );
+    return {
+      status: "synced",
+      changed: !sameState,
+      scannedAt: scan.scannedAt,
+      reason: sameState ? "The hosted map was revalidated after its daily refresh window." : "The hosted map was refreshed from the current repo state.",
+      cloudSync
+    };
+  }
+  writeBriefCacheFile(
+    repoRoot,
+    autoScanStateFile,
+    `${JSON.stringify(
+      { fingerprint, lastAttemptedAt: attemptedAt },
+      null,
+      2
+    )}
+`
+  );
+  return {
+    status: "failed",
+    changed: !sameState,
+    scannedAt: scan.scannedAt,
+    reason: cloudSync.reason,
+    cloudSync
+  };
+}
+function scanFingerprintFor(repoRoot, scan) {
+  const sourceIdentity = scan.sources.map((source) => `${source.path}:${source.contentHash}`).sort();
+  const mapIdentity = scan.map.map(
+    (node) => JSON.stringify({
+      type: node.type,
+      name: node.name,
+      path: node.path,
+      summary: node.summary,
+      tags: node.tags,
+      metadata: node.metadata
+    })
+  ).sort();
+  return contentHash(
+    JSON.stringify({
+      branch: runGit(repoRoot, ["branch", "--show-current"]),
+      commit: runGit(repoRoot, ["rev-parse", "HEAD"]),
+      changedPaths: runGit(repoRoot, [
+        "status",
+        "--short",
+        "--untracked-files=all"
+      ]),
+      sourceIdentity,
+      mapIdentity,
+      stats: scan.stats
+    })
+  );
+}
+function readAutoScanState(repoRoot) {
+  for (const filePath of briefCacheCandidatePaths(
+    repoRoot,
+    autoScanStateFile
+  )) {
+    const raw = readBriefLedgerFile(filePath);
+    if (!raw) continue;
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isAutoScanState(parsed)) continue;
+      return parsed;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function isAutoScanState(value) {
+  if (!value || typeof value !== "object") return false;
+  const state = value;
+  return typeof state.fingerprint === "string" && typeof state.lastAttemptedAt === "string" && (state.lastSuccessfulAt === void 0 || typeof state.lastSuccessfulAt === "string");
+}
+var autoScanStateFile, failedSyncRetryMs, successfulResyncMs;
+var init_autoScan = __esm({
+  "../mcp/src/autoScan.ts"() {
+    "use strict";
+    init_dist2();
+    init_cloud();
+    autoScanStateFile = "auto-scan.json";
+    failedSyncRetryMs = 6e4;
+    successfulResyncMs = 24 * 60 * 60 * 1e3;
+  }
+});
+
 // ../mcp/src/teamContext.ts
 async function scanRepoWithTeamContext(repoRoot, options2 = {}, env = process.env) {
   const localScan = scanRepo(repoRoot, options2);
-  const teamContext = await fetchTeamContext(repoRoot, env);
+  const [teamContext, autoScan] = await Promise.all([
+    fetchTeamContext(repoRoot, env),
+    autoSyncScanSummary(localScan, repoRoot, env)
+  ]);
   if (teamContext.status !== "fetched") {
-    return { scan: localScan, teamContext };
+    return { scan: localScan, teamContext, autoScan };
   }
   return {
     scan: mergeTeamContext(localScan, teamContext.context),
-    teamContext
+    teamContext,
+    autoScan
   };
 }
 function summarizeTeamContext(teamContext) {
@@ -34922,6 +35063,7 @@ var init_teamContext = __esm({
     "use strict";
     init_dist2();
     init_cloud();
+    init_autoScan();
     ruleKinds = /* @__PURE__ */ new Set([
       "workflow",
       "architecture",
@@ -36221,7 +36363,7 @@ var init_installStatus = __esm({
     "use strict";
     init_dist2();
     init_serverInstructions();
-    briefConnectorVersion = "0.1.4";
+    briefConnectorVersion = "0.1.5";
   }
 });
 
@@ -36495,7 +36637,7 @@ function renderWikiReadme(wiki, pageArtifacts) {
     "- Open the most relevant page under `pages/` and cite it in the plan, review, or handoff.",
     "- Before final handoff, run `brief.review_diff`; for multi-step work, also save handoff proof and verify receipts.",
     "- End each coding pass with a Brief final recap in one or two lines: name the Brief tools actually used, one concrete way they helped, and validation or remaining risk. Say plainly when Brief did not materially help.",
-    "- If the web app scan timestamp is stale, ask your connected agent to call `brief.scan_repo` from the active repo/worktree.",
+    "- The connected agent automatically rechecks map freshness at session start and before context; call `brief.scan_repo` from the active repo/worktree only when you need an immediate retry.",
     "- If this wiki looks stale, ask your connected agent to call `brief.initialize_repo_wiki` with `update: true`.",
     "- Prefer existing routes, helpers, tests, owners, and reference implementations surfaced here before adding new code.",
     "",
@@ -36503,7 +36645,7 @@ function renderWikiReadme(wiki, pageArtifacts) {
     "",
     "There are three freshness actions. Use the first when the web app timestamp is old, the second when repo-local wiki pages are stale, and the third when the team wants refresh to happen without reminders.",
     "",
-    "1. **Rescan the repo for the web app and code map**: ask the connected agent to call `brief.scan_repo` from the repo it is editing.",
+    "1. **Refresh the repo for the web app and code map**: when a connected agent starts, Brief automatically rechecks the map; call `brief.scan_repo` from the repo it is editing for an immediate retry.",
     "2. **Refresh the repo-local wiki**: ask the connected agent to call `brief.initialize_repo_wiki` with `update: true`.",
     "3. **Make refresh continuous**: after a trusted first run, ask the connected agent to call `brief.initialize_repo_wiki` with `update: true` and `writeGithubWorkflow: true`, then review the generated workflow PR behavior.",
     "",
@@ -36663,7 +36805,7 @@ function wikiAgentBlock() {
     "- Cite the wiki page and source files used in your plan, review, or handoff.",
     "- Before final handoff after code changes, call `brief.review_diff`; for multi-step work also call `brief.save_handoff` and `brief.verify_receipts`.",
     "- End each coding pass with a Brief final recap in one or two lines: name the Brief tools actually used, one concrete way they helped, and validation or remaining risk. Say plainly when Brief did not materially help.",
-    "- If the web app scan timestamp is stale, ask the connected agent to call `brief.scan_repo` from the active repo/worktree.",
+    "- The connected agent automatically rechecks map freshness at session start and before context; call `brief.scan_repo` from the active repo/worktree only when you need an immediate retry.",
     "- If `.brief/wiki` is stale, ask the connected agent to call `brief.initialize_repo_wiki` with `update: true` before trusting reuse guidance.",
     "- To keep wiki freshness continuous, ask the connected agent to call `brief.initialize_repo_wiki` with `update: true` and `writeGithubWorkflow: true`, then review the generated workflow.",
     '- Use `brief context --repo "$PWD" --task "<task>"` when you need a compact packet for a specific change.',
@@ -37989,7 +38131,7 @@ var init_server = __esm({
     server = new McpServer(
       {
         name: "brief",
-        version: "0.1.4"
+        version: "0.1.5"
       },
       {
         instructions: briefMcpInstructions
@@ -38166,9 +38308,12 @@ var init_server = __esm({
             })
           );
         }
-        const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot, {
-          maxFiles: 1200
-        });
+        const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(
+          repoRoot,
+          {
+            maxFiles: 1200
+          }
+        );
         const activation = task?.trim() ? await buildActivationContext({
           scan,
           repoRoot,
@@ -38203,6 +38348,7 @@ var init_server = __esm({
           skillLearning: summarizeSkillLearningForStart(skillLearning, void 0),
           connectorHealth: summarizeAgentConnectorHealth(setups),
           proofLoop: report.proofLoop,
+          mapRefresh: autoScan,
           ...activation ? { activation } : {},
           value: {
             receiptCount: report.receiptCount,
@@ -38232,6 +38378,7 @@ var init_server = __esm({
             valueReport: report,
             serverInstructionsActive: true
           }),
+          mapRefresh: autoScan,
           ...activation ? { activation } : {}
         });
       }
@@ -38590,13 +38737,14 @@ var init_server = __esm({
           return repoTargetBlock(repoTargetInfo);
         }
         const { repoRoot, rootResolution, repoTarget } = repoTargetInfo;
-        const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot);
+        const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(repoRoot);
         return jsonText({
           repoRoot,
           rootResolution,
           repoTarget,
           repoName: scan.repoName,
           teamContext: summarizeTeamContext(teamContext),
+          mapRefresh: autoScan,
           appliedContext: {
             rules: scan.rules.slice(0, 20),
             memories: scan.memories.slice(0, 12),
@@ -38728,9 +38876,12 @@ var init_server = __esm({
           });
         }
         const { rootResolution, repoRoot, repoTarget } = repoTargetInfo;
-        const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot, {
-          maxFiles: 1200
-        });
+        const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(
+          repoRoot,
+          {
+            maxFiles: 1200
+          }
+        );
         const task = request?.trim() || "Continue the current repo work safely.";
         const skillLearning = buildRepoSkillLearningReport(repoRoot, {
           maxFiles: 6e3
@@ -38800,6 +38951,7 @@ var init_server = __esm({
           ...readinessPreview ? { readinessPreview } : {},
           workflowWiring: summarizeWorkflowWiringForStart(workflowWiring),
           autoEngage: summarizeAutoEngageForStart(autoEngage),
+          mapRefresh: autoScan,
           skillLearning: summarizeSkillLearningForStart(
             skillLearning,
             learnedWorkflow
@@ -38850,6 +39002,7 @@ var init_server = __esm({
           sharedContext: summarizeBeforeYouCodeSharedContext(
             beforeYouCode.teamGuidance
           ),
+          mapRefresh: autoScan,
           referenceFirst: summarizeBeforeYouCodeReferences(beforeYouCode),
           ...learnedWorkflow ? {
             learnedWorkflow: {
@@ -38891,9 +39044,12 @@ var init_server = __esm({
           });
         }
         const { rootResolution, repoRoot, repoTarget } = repoTargetInfo;
-        const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot, {
-          maxFiles: 1200
-        });
+        const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(
+          repoRoot,
+          {
+            maxFiles: 1200
+          }
+        );
         const beforeYouCode = buildBeforeYouCodeMap(scan, {
           task,
           repoRoot,
@@ -38909,7 +39065,8 @@ var init_server = __esm({
           repoTarget,
           cockpit: beforeYouCode.cockpit,
           beforeYouCode: summarizeBeforeYouCodeForStart(beforeYouCode),
-          teamContext: summarizeTeamContext(teamContext)
+          teamContext: summarizeTeamContext(teamContext),
+          mapRefresh: autoScan
         });
       }
     );
@@ -38965,7 +39122,7 @@ var init_server = __esm({
           });
         }
         const { rootResolution, repoRoot, repoTarget } = repoTargetInfo;
-        const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot);
+        const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(repoRoot);
         const skillLearning = buildRepoSkillLearningReport(repoRoot, {
           maxFiles: 6e3
         });
@@ -39040,7 +39197,8 @@ var init_server = __esm({
             context: summarizePacket(packet),
             localReceipt: summarizeLocalReceipt(localReceipt2),
             cloudSync: cloudSync2,
-            teamContext: summarizeTeamContext(teamContext)
+            teamContext: summarizeTeamContext(teamContext),
+            mapRefresh: autoScan
           };
           return jsonText(
             expanded ? fullResponse2 : buildCompactStartEnvelope({
@@ -39586,7 +39744,7 @@ var init_server = __esm({
             }
           );
         }
-        const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot);
+        const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(repoRoot);
         const request = { task, repoRoot, agent: "mcp" };
         if (files) request.files = files;
         if (branch) request.branch = branch;
@@ -39615,7 +39773,8 @@ var init_server = __esm({
           repoTarget,
           localReceipt: summarizeLocalReceipt(localReceipt),
           cloudSync,
-          teamContext: summarizeTeamContext(teamContext)
+          teamContext: summarizeTeamContext(teamContext),
+          mapRefresh: autoScan
         });
       }
     );
@@ -39669,7 +39828,7 @@ var init_server = __esm({
           });
         }
         const { rootResolution, repoRoot, repoTarget } = repoTargetInfo;
-        const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot);
+        const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(repoRoot);
         const request = {
           task: missionTaskFromInputs(task, workItem, runtimeEvidence),
           repoRoot,
@@ -39722,7 +39881,8 @@ var init_server = __esm({
           repoTarget,
           localReceipt: summarizeLocalReceipt(localReceipt),
           cloudSync,
-          teamContext: summarizeTeamContext(teamContext)
+          teamContext: summarizeTeamContext(teamContext),
+          mapRefresh: autoScan
         });
       }
     );
@@ -41071,9 +41231,12 @@ async function runCli(commandName, commandArgs) {
       );
       return;
     }
-    const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot, {
-      maxFiles: 400
-    });
+    const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(
+      repoRoot,
+      {
+        maxFiles: 400
+      }
+    );
     const report = buildLocalValueReport(repoRoot, scan.repoName);
     const setups = generateAgentSetup(scan, { target: "all" });
     const skillLearning = buildRepoSkillLearningReport(repoRoot, {
@@ -41100,6 +41263,7 @@ async function runCli(commandName, commandArgs) {
       skillLearning: summarizeSkillLearningForCli(skillLearning, void 0),
       connectorHealth: summarizeAgentConnectorHealth(setups),
       proofLoop: report.proofLoop,
+      mapRefresh: autoScan,
       value: {
         receiptCount: report.receiptCount,
         contextPacketCount: report.contextPacketCount,
@@ -41112,21 +41276,24 @@ async function runCli(commandName, commandArgs) {
       next: report.proofLoop.next
     };
     printJson(
-      hasFlag(commandArgs, "full") ? fullStatus : compactInstallStatus({
-        mode: "cli",
-        repoRoot,
-        rootResolution,
-        repoTarget,
-        scan,
-        connectorReadiness: connector,
-        serverFreshness: freshness,
-        cloudSync: cloud,
-        teamContext: summarizedTeamContext,
-        readiness,
-        workflowWiring,
-        valueReport: report,
-        serverInstructionsActive: false
-      })
+      hasFlag(commandArgs, "full") ? fullStatus : {
+        ...compactInstallStatus({
+          mode: "cli",
+          repoRoot,
+          rootResolution,
+          repoTarget,
+          scan,
+          connectorReadiness: connector,
+          serverFreshness: freshness,
+          cloudSync: cloud,
+          teamContext: summarizedTeamContext,
+          readiness,
+          workflowWiring,
+          valueReport: report,
+          serverInstructionsActive: false
+        }),
+        mapRefresh: autoScan
+      }
     );
     return;
   }
@@ -41307,9 +41474,12 @@ async function runCli(commandName, commandArgs) {
     const stage = option2(commandArgs, "stage") ?? "auto";
     const maxLines = numberOption(commandArgs, "max-lines");
     const task = request?.trim() || "Continue the current repo work safely.";
-    const { scan, teamContext } = await scanRepoWithTeamContext(repoRoot, {
-      maxFiles: 1200
-    });
+    const { scan, teamContext, autoScan } = await scanRepoWithTeamContext(
+      repoRoot,
+      {
+        maxFiles: 1200
+      }
+    );
     const skillLearning = buildRepoSkillLearningReport(repoRoot, {
       maxFiles: 6e3
     });
@@ -41359,6 +41529,7 @@ async function runCli(commandName, commandArgs) {
       ...start && recommendation.mcpTool !== "brief.before_you_code" ? { start: summarizeStartForCli(start) } : {},
       workflowWiring: summarizeWorkflowWiringForCli(workflowWiring),
       autoEngage: summarizeAutoEngageForCli(autoEngage),
+      mapRefresh: autoScan,
       skillLearning: summarizeSkillLearningForCli(
         skillLearning,
         learnedWorkflow
@@ -41405,6 +41576,7 @@ async function runCli(commandName, commandArgs) {
         sharedContext: summarizeBeforeYouCodeSharedContext(
           beforeYouCode.teamGuidance
         ),
+        mapRefresh: autoScan,
         autoEngage: {
           status: autoEngage.status,
           chatFeedback: autoEngage.chatFeedback.slice(0, 1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runbrief",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "description": "Brief Connector: the local MCP companion for repo context, reuse guidance, review gates, and handoff proof.",
   "type": "module",