pi-weave 0.1.7 → 0.1.8

package/src/core/graph/model.ts

@@ -60,4 +60,28 @@ export interface GraphModel {
   staleness: StalenessReport | null;
   nodes: GraphNode[];
   edges: GraphEdge[];
+  /**
+   * slug → wiki-link targets that resolved to no note in the graph
+   * (weave-workspace §4.2).
+   *
+   * A `[[target]]` that matches nothing is not an error — it is Obsidian's
+   * ghost node, the affordance that offers to create the missing note. The
+   * builder used to count these and throw the names away, leaving
+   * `detail["dangling links"] = "3"` as the only trace; a display string is
+   * not something a UI can navigate.
+   *
+   * Lives here rather than on {@link GraphNode} because `detail` is
+   * display-only by contract and must not grow structure (§4.2 is explicit
+   * about preferring the model-level map). Notes with nothing unresolved are
+   * absent rather than present-and-empty, so the common case costs no bytes.
+   *
+   * Keyed by **slug**, not by node id: the consumers of this map (the note
+   * column, the wire payload's `dangling` field) speak slugs, and `note:` is
+   * a graph-internal prefix.
+   *
+   * Insertion order follows note order and each target list follows
+   * first-appearance order in the body, so the JSON stays byte-stable for
+   * unchanged inputs.
+   */
+  danglingLinks: Record<string, string[]>;
 }

package/src/core/index.ts

@@ -14,12 +14,24 @@ export * from "./vault";
 export * from "./repoIndex";
 export * from "./summaries";
 export * from "./workspace";
+export * from "./openInEditor";
 export * from "./graph/model";
 export * from "./graph/wikilinks";
+export * from "./view";
 export { buildGraph, dataTimestamp, DEFAULT_MAX_NOTES, type BuildGraphInput } from "./graph/build";
 export {
   buildCurrentGraph,
   readNoteForView,
   readOkfFileForView,
+  readRepositorySide,
   type ViewNote,
 } from "./graph/current";
+export {
+  classifyPath,
+  DEFAULT_STALENESS_TTL_MS,
+  WorkspaceCache,
+  type CacheStats,
+  type InvalidationScope,
+  type WorkspaceCacheOptions,
+  type WorkspaceSnapshot,
+} from "./cache/workspace";

package/src/core/openInEditor.ts

@@ -0,0 +1,69 @@
+/**
+ * Open a vault note in the user's editor.
+ *
+ * Originally `src/pi/viewer/tui/openNote.ts`, promoted into core because the
+ * browser workspace needs it too and `src/web/server/**` may not import
+ * `src/pi` (weave-workspace §2). It belongs here on the merits regardless:
+ * it is a pure fan-out over `core/vault` plus one `execFile`, with no
+ * harness and no terminal concept in it, and the same reasoning that put
+ * `readNoteForView` in core applies unchanged.
+ *
+ * The old path re-exports these two names, so no TUI file changed.
+ *
+ * Security: the slug is validated against the vault (traversal-safe) before
+ * any shell-out, and the command is invoked with `execFile`, not a shell, so
+ * neither the slug nor a `$EDITOR` containing metacharacters can compose a
+ * command. `$EDITOR` itself is trusted — it is the user's own configuration,
+ * and a hostile one already has whatever the user has.
+ */
+
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import { promisify } from "node:util";
+import { getNote, resolveNotePath } from "./vault";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * The OS command used to open a note file in the user's editor. Respects
+ * $EDITOR / $VISUAL (which may carry args, e.g. "code --wait"); falls back
+ * to the platform default opener. `env` and `os` are injectable so the
+ * mapping is unit-testable on any host without stubbing globals.
+ */
+export function openNoteCommand(
+  notePath: string,
+  env: NodeJS.ProcessEnv = process.env,
+  os: NodeJS.Platform = platform(),
+): { command: string; args: string[] } {
+  const editor = (env.EDITOR || env.VISUAL || "").trim();
+  if (editor) {
+    // editor is a trimmed non-empty string, so split+filter always yields a
+    // first segment — assert it rather than leave a dead `?? ""` branch.
+    const parts = editor.split(/\s+/).filter(Boolean);
+    const command = parts[0] as string;
+    return { command, args: [...parts.slice(1), notePath] };
+  }
+  if (os === "darwin") return { command: "open", args: [notePath] };
+  if (os === "win32") return { command: "cmd", args: ["/c", "start", "", notePath] };
+  return { command: "xdg-open", args: [notePath] };
+}
+
+/**
+ * Open a note in the OS editor. The slug is validated against the vault
+ * (traversal-safe) before any shell-out; returns false when the note does
+ * not exist or the slug is unsafe.
+ */
+export async function openNoteInEditor(
+  vaultRoot: string,
+  slug: string,
+  openCommand: (notePath: string) => { command: string; args: string[] } = openNoteCommand,
+): Promise<boolean> {
+  const path = resolveNotePath(vaultRoot, slug);
+  if (path === null) return false; // traversal-safe
+  const note = await getNote(vaultRoot, slug);
+  if (note === null) return false;
+  const { command, args } = openCommand(path);
+  if (!command) return false;
+  await execFileAsync(command, args);
+  return true;
+}

package/src/core/types.ts

@@ -22,11 +22,51 @@ export interface NoteMeta {
   source: NoteSource;
 }
 
+/**
+ * The verbatim lines of a note's front-matter block, in file order, without
+ * the enclosing `---` fences.
+ *
+ * This is how pi-weave keeps front matter **lossless**. `NoteMeta` names the
+ * five fields the engine understands; a vault is a directory of files a human
+ * also edits, so real notes carry keys the engine has never heard of —
+ * Obsidian's `aliases`, `cssclass`, `publish`, whatever the user invented last
+ * Tuesday. Modelling those as parsed values would mean re-emitting them, and
+ * re-emitting a value the parser only half-understands is how formatting (and
+ * then content) gets destroyed.
+ *
+ * So they are not parsed at all: the raw lines are carried through, and
+ * `serializeNote` replays them, substituting a freshly rendered line only for
+ * the keys `NoteMeta` actually owns. Unknown keys — including ones using
+ * syntax the subset parser cannot represent, such as block lists or folded
+ * scalars — come back out byte-identical, in their original order.
+ *
+ * Deliberately `readonly string[]` rather than a parsed record: a second
+ * representation of a line is a second thing that can disagree with the file.
+ * The key of a line is derived with the same rule the parser uses, at the one
+ * place that needs it.
+ */
+export type NoteFrontMatter = readonly string[];
+
 /** A vault note: metadata plus its Markdown body. */
 export interface Note extends NoteMeta {
   /** File-name slug (no extension). Stable identity of the note. */
   slug: string;
   body: string;
+  /**
+   * The note's front-matter block as it appeared on disk, so a read → write
+   * round trip preserves keys outside {@link NoteMeta} (see
+   * {@link NoteFrontMatter}).
+   *
+   * Optional because a `Note` need not have come from a file: graph fixtures
+   * and in-memory projections construct one directly. Absent means "no layout
+   * to preserve", and `serializeNote` then emits the canonical five fields.
+   *
+   * Not carried on {@link NoteSummary}, and deliberately not on the wire: the
+   * browser never needs to see a user's unknown keys in order for them to
+   * survive, because every write path re-reads the file it is about to
+   * overwrite.
+   */
+  frontMatter?: NoteFrontMatter;
 }
 
 /** Summary of one note for list/search output. */