@leon135/opencode-learn 0.0.0-stage → 0.1.0

package/plugins/md-link/core.ts

@@ -0,0 +1,238 @@
+/**
+ * md-link core — single source of truth for the Obsidian live-mirror pair.
+ *
+ * Consumers:
+ *   plugins/md-link/index.ts (server: mirrors assistant replies)
+ *   plugins/md-link/tui.ts   (TUI: ctrl+alt+m / /md-link toggle)
+ *
+ * The package's `.` entry (plugins/index.ts) registers the server part; the
+ * TUI part loads through the package's `./tui` export (plugins/tui.ts).
+ *
+ * State file contract (~/.config/opencode/md-link-state.json):
+ *   {
+ *     "defaultDir": "/abs/dir" | null,          // fallback output dir
+ *     "keep": 25 | null,                        // prune mirrors to N newest replies
+ *     "sessions": { "<sessionID>": "/abs/dir" } // "" dir = use defaultDir
+ *     "persist": true|false                     // true = mirrors survive TUI exit
+ *   }
+ *
+ * With persist=true, TUI exit keeps this project's mirror files AND their
+ * session entries, so the event subscription resumes mirroring into the same
+ * files on the next launch. Explicit /md-link OFF always deletes regardless.
+ *
+ * Mirror file contract (<dir>/<sessionID>.md):
+ *   Contains ONLY response blocks — no frontmatter, titles, or separators:
+ *     <!-- msg:<assistantMessageID>#<ordinal> -->   (dedup marker, invisible
+ *     **HH:MM**                                      in Obsidian preview)
+ *
+ *     <reply text>
+ *
+ * The server re-reads the state file on every event so TUI toggles apply
+ * instantly; writers use read-modify-write to stay concurrency-safe.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync, appendFileSync } from "fs"
+import { dirname, join } from "path"
+import { homedir } from "os"
+
+export const STATE_FILE = join(homedir(), ".config", "opencode", "md-link-state.json")
+
+export type MdLinkState = {
+  defaultDir: string | null
+  keep: number | null
+  sessions: Record<string, string>
+  /** True = mirror files + session entries survive TUI exit (resume next launch). */
+  persist?: boolean
+}
+
+const EMPTY_STATE: MdLinkState = { defaultDir: null, keep: null, sessions: {}, persist: false }
+
+/** Read state, migrating legacy formats (plain array / {sessions:[...]}). */
+export function loadState(): MdLinkState {
+  try {
+    if (!existsSync(STATE_FILE)) return { ...EMPTY_STATE, sessions: {} }
+    const raw = JSON.parse(readFileSync(STATE_FILE, "utf-8"))
+
+    if (Array.isArray(raw)) {
+      const sessions: Record<string, string> = {}
+      for (const x of raw) if (typeof x === "string") sessions[x] = ""
+      return { ...EMPTY_STATE, sessions }
+    }
+    if (raw && typeof raw === "object") {
+      const sessions: Record<string, string> = {}
+      const s = (raw as any).sessions
+      if (s && typeof s === "object" && !Array.isArray(s)) {
+        for (const [k, v] of Object.entries(s)) {
+          if (typeof k === "string" && k && typeof v === "string") sessions[k] = v
+        }
+      } else if (Array.isArray(s)) {
+        for (const x of s) if (typeof x === "string") sessions[x] = ""
+      }
+      return {
+        defaultDir: typeof raw.defaultDir === "string" ? raw.defaultDir : null,
+        keep: typeof raw.keep === "number" && raw.keep >= 1 ? Math.floor(raw.keep) : null,
+        sessions,
+        persist: raw.persist === true,
+      }
+    }
+  } catch {}
+  return { ...EMPTY_STATE, sessions: {} }
+}
+
+/** Atomic-enough write for our scale (single writer per toggle, tiny file). */
+export function saveState(st: MdLinkState): void {
+  try {
+    mkdirSync(dirname(STATE_FILE), { recursive: true })
+    writeFileSync(STATE_FILE, JSON.stringify(st, null, 2), "utf-8")
+  } catch {}
+}
+
+export function isEnabled(st: MdLinkState, sessionID: string): boolean {
+  return sessionID in st.sessions
+}
+
+/** Add a session (read-modify-write). Preserves any dir already recorded. */
+export function enableSession(st: MdLinkState, sessionID: string, dir = ""): void {
+  if (!(sessionID in st.sessions)) st.sessions[sessionID] = dir
+  saveState(st)
+}
+
+/** Remove a session (read-modify-write). */
+export function disableSession(st: MdLinkState, sessionID: string): void {
+  delete st.sessions[sessionID]
+  saveState(st)
+}
+
+/** Resolve where a session's mirror lives. Falls back through recorded dir → defaultDir → fallbackDir. */
+export function mirrorFile(st: MdLinkState, sessionID: string, fallbackDir?: string): string | null {
+  let dir = st.sessions[sessionID] ?? ""
+  if (!dir && st.defaultDir) dir = st.defaultDir
+  if (!dir && fallbackDir) dir = fallbackDir
+  if (!dir) return null
+  return join(dir, `${sessionID}_link.md`)
+}
+
+/** Create an empty mirror file (responses only — zero boilerplate). No-op if it exists. */
+export function touchMirror(file: string): void {
+  if (existsSync(file)) return
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, "", "utf-8")
+}
+
+export type AppendResult = "written" | "updated" | "duplicate" | "failed"
+
+/** Extract full reply text from a /message item (shapes vary: content[] parts or flat text). */
+export function messageText(m: any): string {
+  let text = ""
+  if (Array.isArray(m?.content)) {
+    text = m.content
+      .filter((c: any) => c?.type === "text" && typeof c.text === "string")
+      .map((c: any) => c.text)
+      .join("\n")
+  }
+  if (!text && typeof m?.text === "string") text = m.text
+  return text.trim()
+}
+
+/** Skill declarations are system-injected context, not learner prose. */
+export function stripSkillBlocks(text: string): string {
+  return text.replace(/<skill\b([^>]*)>[\s\S]*?<\/skill>/g, (_m, attrs: string) => {
+    const name = /name="([^"]+)"/.exec(attrs)?.[1]
+    return `[SKILL loaded: ${name ?? "(unknown)"}]`
+  })
+}
+
+/** Obsidian callout block: `> [!type] title` + quoted body lines. */
+export function callout(type: string, title: string, bodyLines: string[]): string {
+  const lines = [`> [!${type}] ${title}`]
+  for (const line of bodyLines) lines.push(line.length === 0 ? ">" : `> ${line}`)
+  return lines.join("\n")
+}
+
+/** User-prompt block, identical for the live event path and history backfill. */
+export function userPromptBlock(text: string): string {
+  return callout("quote", "YOU", stripSkillBlocks(text.trim()).split("\n"))
+}
+
+/** True if the file contains a block whose marker starts with `<!-- msg:<key>` */
+export function hasBlock(file: string, key: string): boolean {
+  try {
+    return readFileSync(file, "utf-8").includes(`<!-- msg:${key}`)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Append one reply block, deduped/upserted by markerKey, then prune to `keep`.
+ * With replace=true, an existing block for the same key is rewritten when its
+ * text differs (used by the poller while replies are still streaming).
+ * Block format (see module doc): marker comment, local HH:MM, blank line, text.
+ */
+export function appendMessage(
+  file: string,
+  opts: { text: string; markerKey?: string | null; replace?: boolean },
+  keep: number | null,
+): AppendResult {
+  const key = opts.markerKey ?? null
+  try {
+    if (key && hasBlock(file, key)) {
+      if (!opts.replace) return "duplicate"
+      return replaceBlock(file, key, opts.text) ? "updated" : "duplicate"
+    }
+    if (key === null && hasBlockLoose(file, opts.text)) return "duplicate"
+    const time = clock()
+    const marker = key ? `<!-- msg:${key} -->\n` : ""
+    appendFileSync(file, `${marker}**${time}**\n\n${opts.text.trim()}\n\n`, "utf-8")
+    pruneMirror(file, keep)
+    return "written"
+  } catch {
+    return "failed"
+  }
+}
+
+function hasBlockLoose(file: string, text: string): boolean {
+  try {
+    return readFileSync(file, "utf-8").includes(text.trim().slice(0, 80))
+  } catch {
+    return false
+  }
+}
+
+function clock(): string {
+  return new Date().toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" })
+}
+
+/** Rewrite an existing block's text in place. Returns false if unchanged/not found. */
+function replaceBlock(file: string, key: string, text: string): boolean {
+  const c = readFileSync(file, "utf-8")
+  const first = c.search(/<!-- msg:/)
+  if (first === -1) return false
+  const head = c.slice(0, first)
+  const blocks = c.slice(first).split(/(?=<!-- msg:)/g).filter((b) => b.trim().length > 0)
+  const idx = blocks.findIndex((b) => b.startsWith(`<!-- msg:${key}`))
+  if (idx === -1) return false
+  const fresh = `<!-- msg:${key} -->\n**${clock()}**\n\n${text.trim()}\n\n`
+  const norm = (s: string) => s.replace(/\s+/g, " ").trim()
+  if (norm(blocks[idx]) === norm(fresh)) return false
+  blocks[idx] = fresh
+  writeFileSync(file, head + blocks.join(""), "utf-8")
+  return true
+}
+
+/** Keep only the newest `keep` reply blocks. keep <= 0/null = unlimited. */
+export function pruneMirror(file: string, keep: number | null): void {
+  try {
+    if (!keep || keep < 1) return
+    const c = readFileSync(file, "utf-8")
+    const first = c.search(/<!-- msg:/)
+    if (first === -1) return
+    const head = c.slice(0, first)
+    const blocks = c
+      .slice(first)
+      .split(/(?=<!-- msg:)/g)
+      .filter((b) => b.trim().length > 0)
+    if (blocks.length <= keep) return
+    writeFileSync(file, head + blocks.slice(-keep).join(""), "utf-8")
+  } catch {}
+}

package/plugins/md-link/index.ts

@@ -0,0 +1,314 @@
+/**
+ * md-link — Obsidian live-mirror (server side).
+ *
+ * Mirrors a session to `<dir>/<sessionID>_link.md` for sessions enabled in
+ * the state file (see core.ts for the contracts). Sessions are toggled
+ * exclusively by the TUI plugin — this plugin never enables anything.
+ *
+ * Mirrors are transient by default — with persistence ON (/md-link-persist),
+ * session entries survive TUI exit and this subscription resumes them on next launch.
+ *
+ * What gets mirrored (teaching-session parity with the pi md-log):
+ *   - assistant replies   → ctx.event.subscribe session.text.delta (2.5 s
+ *                           throttle while streaming) + session.text.ended
+ *   - user prompts        → session.inbox.enqueued, as `> [!quote] YOU` callouts
+ *   - quiz_ask / question → tool hooks: question callout written at
+ *                           execute.before (pre-answer, sanitized input),
+ *                           feedback callout at execute.after (quiz_grade /
+ *                           question results)
+ * The subscription is aborted by the cleanup returned from setup; an
+ * unexpected stream exit is logged and re-armed (the old poller self-recovered).
+ */
+
+import type { Plugin } from "@opencode/plugin";
+import {
+  appendMessage,
+  callout,
+  hasBlock,
+  isEnabled,
+  loadState,
+  mirrorFile,
+  touchMirror,
+  userPromptBlock,
+} from "./core.ts";
+
+/** Streaming cadence: rewrite an in-flight reply block at most this often. */
+const DELTA_WRITE_MS = 2_500;
+/** Wait before re-subscribing after the event stream exits unexpectedly. */
+const RESUBSCRIBE_MS = 5_000;
+
+/** Append one block, keeping the existing text when the key is already mirrored. */
+function mirrorBlock(
+  file: string,
+  key: string,
+  text: string,
+  keep: number | null,
+): void {
+  if (!text || hasBlock(file, key)) return;
+  appendMessage(file, { text, markerKey: key, replace: true }, keep);
+}
+
+/** Write an assistant block, rewriting the existing one in place while streaming. */
+function writeAssistant(
+  file: string,
+  key: string,
+  text: string,
+  keep: number | null,
+): void {
+  if (!text) return;
+  appendMessage(file, { text, markerKey: key, replace: true }, keep);
+}
+
+/** The subset of the session event stream this plugin mirrors. */
+type MirrorEvent =
+  | {
+      type: "session.text.delta";
+      data: {
+        sessionID: string;
+        assistantMessageID: string;
+        ordinal: number;
+        delta: string;
+      };
+    }
+  | {
+      type: "session.text.ended";
+      data: {
+        sessionID: string;
+        assistantMessageID: string;
+        ordinal: number;
+        text: string;
+      };
+    }
+  | {
+      type: "session.inbox.enqueued";
+      data: {
+        sessionID: string;
+        inboxID: string;
+        item:
+          | { type: "user"; payload: { text: string } }
+          | { type: "synthetic" | "compaction" | "move" };
+      };
+    };
+
+// ── Q&A callouts via tool hooks ─────────────────────────────────────────────
+
+/** Resolve the mirror file for a session, or null if not enabled. */
+function mirrorFor(sessionID: unknown): string | null {
+  if (typeof sessionID !== "string" || !sessionID) return null;
+  const st = loadState();
+  if (!isEnabled(st, sessionID)) return null;
+  return mirrorFile(st, sessionID, process.cwd());
+}
+
+function appendQa(
+  file: string,
+  markerKey: string,
+  text: string,
+  keep: number | null,
+): void {
+  const res = appendMessage(file, { text, markerKey, replace: true }, keep);
+  // "duplicate" is the expected steady state on service restarts / re-reads.
+  if (res === "failed") console.error("[md-link] qa append failed:", markerKey);
+}
+
+function questionCallout(
+  label: string,
+  question: string,
+  details: string | undefined,
+  options: any[],
+): string {
+  const body: string[] = [];
+  for (const line of String(question || "").split("\n")) body.push(line);
+  if (details) {
+    body.push("");
+    for (const line of details.split("\n")) body.push(line);
+  }
+  const opts = Array.isArray(options) ? options : [];
+  if (opts.length > 0) {
+    body.push("");
+    opts.forEach((o, i) => body.push(`${i + 1}. ${o?.label ?? ""}`));
+  }
+  return callout("question", label, body);
+}
+
+function resultText(result: any): string {
+  if (typeof result === "string") return result;
+  if (typeof result?.content === "string") return result.content;
+  if (Array.isArray(result?.content)) {
+    return result.content
+      .filter((c: any) => c?.type === "text")
+      .map((c: any) => c.text)
+      .join("\n");
+  }
+  return String(result?.output ?? "");
+}
+
+/** Feedback callout from quiz_grade's result text (we control that format). */
+function gradeCallout(content: string): string {
+  const lines = content
+    .split("\n")
+    .filter(
+      (l) => l.trim().length > 0 && !/^Relay the verdict/i.test(l.trim()),
+    );
+  const first = lines[0] ?? "";
+  if (/answered correctly/i.test(first)) {
+    return callout("success", "Quiz — correct ✓", lines.slice(1));
+  }
+  if (/answered incorrectly/i.test(first)) {
+    return callout("failure", "Quiz — incorrect ✗", lines.slice(1));
+  }
+  if (/...?/i.test(content)) {
+    return callout("question", "Quiz — ...?", lines.slice(1));
+  }
+  if (/dismissed|not answered in time/i.test(content)) {
+    return callout("warning", "Quiz — dismissed", ["(no answer given)"]);
+  }
+  return callout("example", "Quiz", lines);
+}
+
+export async function setupMdLink(ctx: Plugin.Context): Promise<() => void> {
+  const controller = new AbortController();
+  /** In-flight assistant text per `<messageID>#<ordinal>` and its last write time. */
+  const inflight = new Map<string, { text: string; written: number }>();
+
+  const handleEvent = (event: MirrorEvent): void => {
+    try {
+      const st = loadState();
+      const sessionID = event.data.sessionID;
+      if (!isEnabled(st, sessionID)) return;
+      // Fallback chain: recorded dir → config defaultDir → cwd (no hardcoded paths).
+      const file = mirrorFile(st, sessionID, process.cwd());
+      if (!file) return;
+      touchMirror(file);
+
+      if (event.type === "session.inbox.enqueued") {
+        const item = event.data.item;
+        if (item.type !== "user") return;
+        const text = String(item.payload.text ?? "").trim();
+        if (text)
+          mirrorBlock(
+            file,
+            `${event.data.inboxID}`,
+            userPromptBlock(text),
+            st.keep,
+          );
+        return;
+      }
+
+      const key = `${event.data.assistantMessageID}#${event.data.ordinal}`;
+      if (event.type === "session.text.delta") {
+        const entry = inflight.get(key) ?? { text: "", written: 0 };
+        entry.text += event.data.delta;
+        const now = Date.now();
+        if (now - entry.written >= DELTA_WRITE_MS) {
+          entry.written = now;
+          writeAssistant(file, key, entry.text.trim(), st.keep);
+        }
+        inflight.set(key, entry);
+        return;
+      }
+
+      // session.text.ended: final text for the part, written immediately.
+      inflight.delete(key);
+      writeAssistant(file, key, event.data.text.trim(), st.keep);
+    } catch {} // one bad event must not stop the subscription
+  };
+
+  // Re-arm after an unexpected stream exit; the old poller recovered by itself.
+  const subscribe = async (): Promise<void> => {
+    while (!controller.signal.aborted) {
+      try {
+        for await (const event of ctx.event.subscribe({
+          types: [
+            "session.text.delta",
+            "session.text.ended",
+            "session.inbox.enqueued",
+          ],
+          signal: controller.signal,
+        })) {
+          handleEvent(event);
+        }
+        if (!controller.signal.aborted)
+          console.error("[md-link] event stream ended — resubscribing");
+      } catch (error) {
+        if (controller.signal.aborted) return;
+        console.error(
+          "[md-link] event subscription failed — resubscribing:",
+          error,
+        );
+      }
+      inflight.clear();
+      if (controller.signal.aborted) return;
+      await new Promise<void>((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          controller.signal.removeEventListener("abort", done);
+          resolve();
+        };
+        const timer = setTimeout(done, RESUBSCRIBE_MS);
+        controller.signal.addEventListener("abort", done, { once: true });
+      });
+    }
+  };
+
+  void subscribe();
+
+  // ── Q&A capture ─────────────────────────────────────────────────────────
+  // execute.before: write the question callout BEFORE the learner answers
+  // (quiz_ask/question inputs are sanitized — no answer material).
+  if (typeof ctx?.tool?.hook === "function") {
+    await ctx.tool.hook("execute.before", async (event: any) => {
+      try {
+        const file = mirrorFor(event.sessionID);
+        if (!file) return;
+        const { keep } = loadState();
+        if (event.tool === "quiz_ask") {
+          const input = event.input ?? {};
+          const block = questionCallout(
+            "Quiz",
+            input.question,
+            input.details,
+            input.options,
+          );
+          appendQa(file, `qa-ask-${event.id}`, block, keep);
+        } else if (event.tool === "question") {
+          const q = event.input?.questions?.[0] ?? {};
+          const block = questionCallout(
+            "Question",
+            q.question ?? q.header ?? "",
+            undefined,
+            q.options,
+          );
+          appendQa(file, `qa-ask-${event.id}`, block, keep);
+        }
+      } catch {}
+    });
+
+    // execute.after: write the feedback callout (answer already given).
+    await ctx.tool.hook("execute.after", async (event: any) => {
+      try {
+        const file = mirrorFor(event.sessionID);
+        if (!file) return;
+        const { keep } = loadState();
+        if (event.tool === "quiz_grade") {
+          const content = resultText(event.result);
+          if (content)
+            appendQa(file, `qa-grade-${event.id}`, gradeCallout(content), keep);
+        } else if (event.tool === "question" && event.status === "completed") {
+          const content = resultText(event.result);
+          if (content)
+            appendQa(
+              file,
+              `qa-grade-${event.id}`,
+              callout("example", "Answer", content.split("\n")),
+              keep,
+            );
+        }
+      } catch {}
+    });
+  } else {
+    console.error("[md-link] ctx.tool.hook unavailable — Q&A capture disabled");
+  }
+
+  return () => controller.abort();
+}