pi-weave 0.1.21 → 0.1.23

package/src/core/vault.ts

@@ -10,6 +10,7 @@ import {
   unquoteField,
   upsertFrontMatterFields,
 } from "./frontmatter";
+import { auditLinks, rewriteLinks, RAW_NOTES_HEADING, type LinkAudit, type LinkFix } from "./links/repair";
 import { withMutationQueue } from "./mutex";
 import { NOTES_DIR, OKF_MANIFEST } from "./paths";
 import { slugify, uniqueSlug } from "./slug";
@@ -281,8 +282,13 @@ export function formatRawAppend(rawText: string, date: Date = new Date()): strin
   return `<!-- appended ${timestamp} -->\n${fence}\n${rawText.trim()}\n${fence}`;
 }
 
-/** The append-only tail where verbatim user scribbles live. */
-export const RAW_NOTES_HEADING = "## Raw";
+/**
+ * The append-only tail where verbatim user scribbles live.
+ *
+ * Defined in `./links/repair` — the module that must never write past it —
+ * and re-exported here, where every caller already looks for it.
+ */
+export { RAW_NOTES_HEADING };
 
 /** The never-edit notice comment at the top of a raw tail (skill format). */
 export const RAW_TAIL_NOTICE =
@@ -462,6 +468,134 @@ async function isDirectory(path: string): Promise<boolean> {
   }
 }
 
+/**
+ * Rewrite every wiki-link in the vault through `resolve`, which maps a stale
+ * target to its replacement slug (or null to leave it alone).
+ *
+ * Two properties matter and are easy to get wrong:
+ *
+ * - **`updated` is not bumped.** A link repair is bookkeeping, not an edit to
+ *   what the note says. Bumping it would reorder the entire vault by recency
+ *   on the first repair pass and make "what changed lately" useless.
+ * - **Lock-free.** Every caller already holds the vault lock (the queue is
+ *   non-reentrant — see {@link LOCK_NS} — so taking it again here would wait
+ *   on itself forever).
+ *
+ * Returns the note slugs that changed and the total number of links rewritten.
+ */
+async function rewriteVaultLinks(
+  root: string,
+  resolve: (target: string, noteSlug: string) => string | null,
+): Promise<{ notes: string[]; links: number }> {
+  const files = (await listNoteFiles(root)).filter(isMarkdown);
+  const touched: string[] = [];
+  let links = 0;
+  for (const file of files) {
+    const slug = file.slice(0, -".md".length);
+    const path = resolveNotePath(root, slug);
+    if (path === null) continue;
+    const note = await getNote(root, slug);
+    if (note === null) continue;
+    const { body, changed } = rewriteLinks(note.body, (target) => resolve(target, slug));
+    if (changed === 0) continue;
+
+    // Splice the new body into the ORIGINAL file text rather than going
+    // through `writeNote`.
+    //
+    // `writeNote` reserializes from the parsed note, and serialization is
+    // lossy in ways that are harmless for an edit and unacceptable here: it
+    // normalizes line endings and trailing whitespace. Those bytes can lie
+    // inside the append-only `## Raw` tail, so a *link repair* — which must
+    // not touch the tail at all — would rewrite a user's verbatim dictation.
+    // `rewriteLinks` already guarantees it only edits offsets above the tail,
+    // so replacing exactly that span preserves every other byte in the file.
+    let original: string;
+    try {
+      original = await fs.readFile(path, "utf8");
+    } catch {
+      continue; // raced a delete
+    }
+    const at = original.lastIndexOf(note.body);
+    if (at === -1) continue; // body not found verbatim; refuse rather than guess
+    const next = original.slice(0, at) + body + original.slice(at + note.body.length);
+    // Atomic replace where it is safe: rename cannot truncate a note on a
+    // crash. A *file* symlink is the exception — renaming over it would
+    // silently replace the link with a regular file and orphan the real
+    // note — so those are written in place, through the link, as every other
+    // vault write already does. (A symlinked *directory* is unaffected:
+    // `path` then names a real file inside it.)
+    const link = await fs.lstat(path).then((s) => s.isSymbolicLink(), () => false);
+    if (link) {
+      await fs.writeFile(path, next, "utf8");
+    } else {
+      const tmp = `${path}.weave-${process.pid}.tmp`;
+      await fs.writeFile(tmp, next, "utf8");
+      await fs.rename(tmp, path);
+    }
+    touched.push(slug);
+    links += changed;
+  }
+  return { notes: touched, links };
+}
+
+/**
+ * Point inbound links at a note's new home after a rename or move.
+ *
+ * This is the root cause of stale links: before this existed, every rename
+ * silently broke every backlink pointing at the old slug, and the only repair
+ * was an agent rereading the vault. One helper, called by all three movers.
+ */
+async function repointBacklinks(root: string, moves: ReadonlyMap<string, string>): Promise<void> {
+  if (moves.size === 0) return;
+  await rewriteVaultLinks(root, (target) => moves.get(target) ?? null);
+}
+
+/** The outcome of a vault-wide link repair. */
+export interface LinkRepairResult {
+  /** The audit the repair acted on (or would have, for a dry run). */
+  audit: LinkAudit;
+  /** Fixes actually written. Empty for a dry run. */
+  applied: LinkFix[];
+  /** Note slugs rewritten. */
+  notes: string[];
+}
+
+/**
+ * Audit the vault's wiki-links and, when `apply` is set, repair every
+ * unambiguous one.
+ *
+ * Idempotent: a second run finds nothing, because the first turned each
+ * stale target into a real slug. Ambiguous and unresolvable links are
+ * reported and left exactly as they are — this function never guesses and
+ * never invents a note.
+ */
+export async function repairVaultLinks(root: string, options: { apply?: boolean } = {}): Promise<LinkRepairResult> {
+  // A dry run needs no lock: it writes nothing, and a report of a vault that
+  // changed a millisecond later is no less true than one taken under a lock.
+  if (options.apply !== true) {
+    return { audit: auditLinks(await readVault(root)), applied: [], notes: [] };
+  }
+  // Applying does, and the audit has to happen *inside* it. Auditing first
+  // and locking second leaves a window in which a concurrent rename or edit
+  // invalidates a decision — a target that was unique when audited may be
+  // ambiguous by the time it is written — and the stale fix would be applied
+  // anyway, then reported as if it had been checked.
+  return withVaultLock(root, async () => {
+    const audit = auditLinks(await readVault(root));
+    if (audit.fixable.length === 0) return { audit, applied: [], notes: [] };
+    // Keyed by note, because the audit already decided per-note; the rewrite
+    // obeys that decision rather than re-deriving it.
+    const byNote = new Map<string, Map<string, string>>();
+    for (const fix of audit.fixable) {
+      const map = byNote.get(fix.slug) ?? new Map<string, string>();
+      map.set(fix.from, fix.to);
+      byNote.set(fix.slug, map);
+    }
+    const { notes } = await rewriteVaultLinks(root, (target, noteSlug) => byNote.get(noteSlug)?.get(target) ?? null);
+    return { audit, applied: audit.fixable, notes };
+  });
+}
+
 /** Rename a note in place and keep its front-matter title in sync. */
 export async function renameNote(root: string, slug: string, name: string, now = new Date()): Promise<VaultMutationResult> {
   const from = resolveNotePath(root, slug);
@@ -477,6 +611,7 @@ export async function renameNote(root: string, slug: string, name: string, now =
     if (from !== to && await exists(to)) return { ok: false, reason: "collision" };
     if (from !== to) await fs.rename(from, to);
     await writeNote(to, target, { ...note, title, updated: now.toISOString() }, note.body, note.frontMatter);
+    if (from !== to) await repointBacklinks(root, new Map([[slug, target]]));
     return { ok: true, slug: target };
   });
 }
@@ -495,6 +630,7 @@ export async function moveNote(root: string, slug: string, folder: string | null
     if (from === to) return { ok: true, slug };
     if (await exists(to)) return { ok: false, reason: "collision" };
     await fs.rename(from, to);
+    await repointBacklinks(root, new Map([[slug, target]]));
     return { ok: true, slug: target };
   });
 }
@@ -522,7 +658,15 @@ export async function renameFolder(root: string, folder: string, name: string):
   return withVaultLock(root, async () => {
     if (!(await isDirectory(from))) return { ok: false, reason: "missing" };
     if (from !== to && await exists(to)) return { ok: false, reason: "collision" };
-    if (from !== to) await fs.rename(from, to);
+    if (from === to) return { ok: true, path: target };
+    // Every note under the folder changes slug, so the whole subtree's
+    // backlinks move with it — collected before the rename, while the old
+    // paths still exist.
+    const moved = (await listNoteFiles(root))
+      .filter((f) => isMarkdown(f) && f.startsWith(`${folder}/`))
+      .map((f) => f.slice(0, -".md".length));
+    await fs.rename(from, to);
+    await repointBacklinks(root, new Map(moved.map((s) => [s, `${target}/${s.slice(folder.length + 1)}`])));
     return { ok: true, path: target };
   });
 }

package/src/core/view/health.ts

@@ -120,6 +120,10 @@ export function healthModel(model: GraphModel): HealthModel {
     if (dangling.length > HEALTH_LIST_CAP) {
       linkRows.push({ id: "health:link:dangling:more", text: `  … and ${dangling.length - HEALTH_LIST_CAP} more` });
     }
+    // How many are *repairable* is not knowable from the graph: resolution
+    // needs note bodies and titles, which the model flattens away. Point at
+    // the tool that does know rather than re-deriving a worse answer here.
+    linkRows.push({ id: "health:link:dangling:repair", text: "  repair: weave_note action=links (fix: true to apply)" });
   }
   if (hubs.length > 0) {
     linkRows.push({ id: "health:link:hubs-h", text: `top hubs (by degree):` });

package/src/pi/tools/noteTool.ts

@@ -12,12 +12,100 @@ import {
   getNote,
   listNotes,
   NOTES_DIR,
+  repairVaultLinks,
   resolveNotePath,
   withMutationQueue,
   resolveVaultRoot,
   searchNotes,
+  suggestLinks,
+  readVault,
+  type LinkRepairResult,
+  type SuggestionReport,
 } from "../../core";
 
+/** Cap on how many rows of each link-audit category get printed. */
+const LINK_REPORT_CAP = 20;
+
+/** Cap on notes printed by `list`; `details.notes` still carries them all. */
+const LIST_CAP = 50;
+
+function capped<T>(items: readonly T[], render: (item: T) => string): string[] {
+  const lines = items.slice(0, LINK_REPORT_CAP).map(render);
+  if (items.length > LINK_REPORT_CAP) lines.push(`  … and ${items.length - LINK_REPORT_CAP} more`);
+  return lines;
+}
+
+/**
+ * Render suggestions as the text the model reads.
+ *
+ * Every row carries the shared terms that earned it. A bare score is
+ * unreviewable; the evidence is what lets a human accept or reject a
+ * suggestion without opening both notes.
+ */
+function formatSuggestions(report: SuggestionReport, focus: string | undefined): string {
+  if (report.suggestions.length === 0) {
+    return focus === undefined
+      ? `No unlinked notes share enough distinctive vocabulary to suggest a connection (${report.considered} note(s) considered).`
+      : `Nothing unlinked looks related to '${focus}' (${report.considered} note(s) considered).`;
+  }
+  const head = focus === undefined
+    ? `${report.suggestions.length} suggested connection(s) across ${report.considered} note(s):`
+    : `${report.suggestions.length} note(s) look related to '${focus}':`;
+  const rows = report.suggestions.map((s) => {
+    const pair = focus === undefined ? `${s.a} ↔ ${s.b}` : s.a === focus ? s.b : s.a;
+    return `  ${s.score.toFixed(3)}  ${pair}\n         shared: ${s.shared.join(", ")}`;
+  });
+  return [
+    head,
+    ...rows,
+    "",
+    "These are suggestions, not links — nothing was written. Add a [[wikilink]] to any pair worth keeping.",
+  ].join("\n");
+}
+
+/** Render a link audit (and any repair) as the text the model reads. */
+function formatLinkReport(result: LinkRepairResult, applied: boolean): string {
+  const { audit } = result;
+  const stale = audit.total - audit.resolved;
+  // Occurrences, not rows. `total`/`resolved` count every `[[…]]` in the
+  // vault, while `fixable`/`unresolvable` are grouped (per note+target, per
+  // target). Reporting "70 stale" beside "40 unresolvable" with no unit
+  // invites the reader to subtract them and find 30 phantom links; saying
+  // what each number counts is the whole fix.
+  const lines = [
+    `${audit.total} wiki-link(s): ${audit.resolved} resolved, ${stale} stale.`,
+  ];
+  if (applied) {
+    lines.push(
+      result.applied.length === 0
+        ? "Nothing to repair automatically."
+        : `Repaired ${result.applied.length} link(s) across ${result.notes.length} note(s):`,
+      ...capped(result.applied, (f) => `  ${f.slug}: [[${f.from}]] → [[${f.to}]] (${f.rule})`),
+    );
+  } else if (audit.fixable.length > 0) {
+    lines.push(
+      `${audit.fixable.length} auto-fixable (re-run with fix: true):`,
+      ...capped(audit.fixable, (f) => `  ${f.slug}: [[${f.from}]] → [[${f.to}]] (${f.rule})`),
+    );
+  }
+  if (audit.ambiguous.length > 0) {
+    lines.push(
+      `${audit.ambiguous.length} ambiguous link(s) (several candidates — pick one and edit the note):`,
+      ...capped(audit.ambiguous, (a) => `  ${a.slug}: [[${a.target}]] → ${a.candidates.join(" | ")}`),
+    );
+  }
+  if (audit.unresolvable.length > 0) {
+    lines.push(
+      `${audit.unresolvable.length} unresolvable target(s) (no such note — write it or drop the link):`,
+      ...capped(audit.unresolvable, (u) => `  [[${u.target}]] ← ${u.notes.join(", ")}`),
+    );
+  }
+  if (audit.fixable.length === 0 && audit.ambiguous.length === 0 && audit.unresolvable.length === 0) {
+    lines.push("Every link resolves.");
+  }
+  return lines.join("\n");
+}
+
 /**
  * `weave_note` — the smart-notepad tool (design §1: vault knowledge).
  *
@@ -30,17 +118,21 @@ export function registerNoteTool(pi: ExtensionAPI): void {
     label: "Weave Note",
     description:
       "Read and write notes in the pi-weave vault — a persistent, human-readable knowledge base " +
-      "of Markdown notes. Actions: list (all notes), get (one note by slug), add (new note), " +
+      "of Markdown notes. Actions: list (all notes — avoid on large vaults, prefer search), get (one note by slug), add (new note), " +
       "append (extend a note; raw=true appends verbatim dictation into the ## Raw tail), " +
-      "finalize (restructure a note above its raw tail), search (title/tags/body). " +
+      "finalize (restructure a note above its raw tail), search (title/tags/body), " +
+      "links (audit stale [[wiki-links]]; fix=true repairs the unambiguous ones), " +
+      "suggest (rank unlinked notes that share distinctive vocabulary; reports only, never writes). " +
       "Use it to remember decisions, facts, and user preferences across sessions.",
     promptSnippet: "Remember and retrieve durable knowledge in the pi-weave vault",
     promptGuidelines: [
       "Use weave_note to store durable knowledge (decisions, preferences, key facts) that should survive the session, marking source as agent-written knowledge.",
       "Use weave_note with action=search before answering questions about past decisions, people, or projects; generated notes under sessions/ carry takeaways from earlier sessions.",
+      "Use weave_note with action=links to find and repair stale [[wiki-links]] deterministically instead of rereading the vault to reconnect notes by hand; add fix=true to apply the unambiguous repairs.",
+      "Use weave_note with action=suggest to discover notes that belong together but are not linked (optionally scoped to one slug); it only reports — propose the links to the user rather than writing them.",
     ],
     parameters: Type.Object({
-      action: StringEnum(["list", "get", "add", "append", "finalize", "search"] as const),
+      action: StringEnum(["list", "get", "add", "append", "finalize", "search", "links", "suggest"] as const),
       title: Type.Optional(Type.String({ description: "Note title (add)" })),
       text: Type.Optional(Type.String({ description: "Markdown body (add), addition (append), or restructured body above the raw tail (finalize)" })),
       tags: Type.Optional(Type.Array(Type.String(), { description: "Tags (add)" })),
@@ -48,6 +140,8 @@ export function registerNoteTool(pi: ExtensionAPI): void {
       raw: Type.Optional(Type.Boolean({ description: "append: add text as verbatim dictation to the ## Raw tail (timestamped fenced block; tail created if missing). Use for dictation/scribbles; omit for structured Markdown additions" })),
       source: Type.Optional(StringEnum(["human", "agent"] as const, { description: "Provenance (add): human for user-scribbled notes, agent for Pi-drafted (default agent)" })),
       query: Type.Optional(Type.String({ description: "Search query (search)" })),
+      fix: Type.Optional(Type.Boolean({ description: "links: apply the unambiguous repairs. Omit for a read-only report" })),
+      limit: Type.Optional(Type.Number({ description: "suggest: how many suggestions to return (default 20)" })),
     }),
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const vault = resolveVaultRoot();
@@ -61,9 +155,21 @@ export function registerNoteTool(pi: ExtensionAPI): void {
               details: { action: "list", notes: [] },
             };
           }
-          const lines = notes.map(
+          // Truncated, because the whole list is rarely the answer and on a
+          // large vault it is actively harmful: hundreds of lines of slugs
+          // crowd out the conversation that prompted the call. Newest first
+          // (`listNotes` order), so the cap keeps what is most likely wanted,
+          // and the footer names `search` — the action that answers "is there
+          // a note about X" without reading the vault aloud.
+          const shown = notes.slice(0, LIST_CAP);
+          const lines = shown.map(
             (n) => `- ${n.slug}: ${n.title}${n.tags.length > 0 ? ` [${n.tags.join(", ")}]` : ""} (updated ${n.updated}, source: ${n.source})`,
           );
+          if (notes.length > shown.length) {
+            lines.push(
+              `… and ${notes.length - shown.length} more (newest ${shown.length} shown) — use action=search to find a specific note.`,
+            );
+          }
           return {
             content: [{ type: "text", text: `${notes.length} note(s) in ${vault}:\n${lines.join("\n")}` }],
             details: { action: "list", notes },
@@ -182,6 +288,40 @@ export function registerNoteTool(pi: ExtensionAPI): void {
             details: { action: "search", hits },
           };
         }
+
+        case "suggest": {
+          const { notes } = await readVault(vault);
+          const report = suggestLinks(
+            { notes },
+            {
+              ...(params.slug ? { slug: params.slug } : {}),
+              ...(params.limit !== undefined ? { limit: params.limit } : {}),
+            },
+          );
+          return {
+            content: [{ type: "text", text: formatSuggestions(report, params.slug) }],
+            details: { action: "suggest", considered: report.considered, suggestions: report.suggestions },
+          };
+        }
+
+        case "links": {
+          const apply = params.fix === true;
+          const result = await repairVaultLinks(vault, apply ? { apply: true } : {});
+          return {
+            content: [{ type: "text", text: formatLinkReport(result, apply) }],
+            details: {
+              action: "links",
+              fixed: apply,
+              total: result.audit.total,
+              resolved: result.audit.resolved,
+              fixable: result.audit.fixable,
+              ambiguous: result.audit.ambiguous,
+              unresolvable: result.audit.unresolvable,
+              applied: result.applied,
+              notes: result.notes,
+            },
+          };
+        }
       }
     },
   });