@leon135/opencode-learn 0.0.0-stage → 0.1.0

package/plugins/skills.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { Plugin, Skill } from "@opencode/plugin"
+
+const BUNDLED = [
+  { id: "teach", file: "../skills/teach/SKILL.md" },
+  { id: "visualize", file: "../skills/visualize/SKILL.md" },
+]
+
+function frontmatterField(frontmatter: string, key: string): string | undefined {
+  const line = frontmatter.split(/\r?\n/).find((candidate) => candidate.startsWith(`${key}:`))
+  if (line === undefined) return undefined
+  return line
+    .slice(key.length + 1)
+    .trim()
+    .replace(/^(['"])(.*)\1$/, "$2")
+}
+
+function readSkill(id: string, file: string) {
+  const path = fileURLToPath(new URL(file, import.meta.url))
+  const raw = readFileSync(path, "utf8")
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  const frontmatter = match?.[1] ?? ""
+  return {
+    id,
+    name: frontmatterField(frontmatter, "name") ?? id,
+    description: frontmatterField(frontmatter, "description"),
+    path,
+    content: (match ? raw.slice(match[0].length) : raw).trim(),
+  }
+}
+
+export async function setupSkills(ctx: Plugin.Context): Promise<void> {
+  const skills = BUNDLED.map(({ id, file }) => readSkill(id, file))
+  await ctx.skill.transform((editor) => {
+    for (const skill of skills) {
+      editor.add({
+        id: Skill.ID.make(skill.id),
+        name: Skill.Name.make(skill.name),
+        description: skill.description,
+        path: Skill.Info.fields.path.make(skill.path),
+        content: skill.content,
+      })
+    }
+  })
+}

package/plugins/tui.ts

@@ -0,0 +1,17 @@
+import { Plugin } from "@opencode/plugin/tui"
+import { setupMdLinkTui } from "./md-link/tui.ts"
+import { setupVizTui } from "./viz/tui.ts"
+
+export default Plugin.define({
+  id: "opencode-learn.tui",
+  async setup(ctx) {
+    const cleanups: (Plugin.Cleanup | void)[] = []
+    cleanups.push(await setupVizTui(ctx))
+    cleanups.push(await setupMdLinkTui(ctx))
+    return () => {
+      for (const cleanup of cleanups.reverse()) {
+        if (typeof cleanup === "function") cleanup()
+      }
+    }
+  },
+})

package/plugins/viz/common.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared helpers for the learn visual authoring loops (write_/edit_/render_
+ * trios for SVG and Mermaid, registered by plugins/viz/index.ts):
+ * subprocess runner, per-session managed source file, exact-match editor,
+ * and publishing a chosen render into <worktree>/viz with a unique filename.
+ *
+ * Ported from the pi visual-tools extension's _common.ts. Differences vs the
+ * original: macOS PATH extras dropped (Linux binaries live in /usr/bin),
+ * staging moved under /tmp/opencode, and sessions are keyed by OpenCode
+ * sessionID (one server process serves many sessions) instead of pid.
+ */
+
+import { spawn } from "node:child_process"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+
+export const RENDER_TIMEOUT_MS_DEFAULT = 120_000
+
+/** Transient session/preview files live outside any vault: only PUBLISHED
+ *  PNGs ever land inside the learner's project (viz/). */
+export const STAGING_ROOT = join(tmpdir(), "opencode", "viz-tools")
+export const FILES_DIRNAME = "viz"
+
+export interface RunResult {
+  code: number | null
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+export function run(
+  cmd: string,
+  args: string[],
+  opts: { cwd?: string; timeoutMs?: number },
+): Promise<RunResult> {
+  return new Promise((resolveRun) => {
+    const child = spawn(cmd, args, {
+      cwd: opts.cwd,
+      env: process.env,
+    })
+    let stdout = ""
+    let stderr = ""
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill("SIGKILL")
+    }, opts.timeoutMs ?? RENDER_TIMEOUT_MS_DEFAULT)
+    child.stdout.on("data", (d) => (stdout += d.toString()))
+    child.stderr.on("data", (d) => (stderr += d.toString()))
+    child.on("error", (err) => {
+      clearTimeout(timer)
+      resolveRun({ code: null, stdout, stderr: stderr + String(err), timedOut })
+    })
+    child.on("close", (code) => {
+      clearTimeout(timer)
+      resolveRun({ code, stdout, stderr, timedOut })
+    })
+  })
+}
+
+/** Per-session managed source file state. */
+export interface Session {
+  workDir: string
+  bodyPath: string
+}
+
+const sessions = new Map<string, Session>()
+
+function sessionKey(group: string, sessionID: string): string {
+  // Sanitize: sessionIDs are [A-Za-z0-9_] but never trust wire data for paths.
+  const sid = sessionID.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 64) || "anon"
+  return `${group}-${sid}`
+}
+
+/** Write the full source to the session's managed file, creating its work dir. */
+export function writeBody(
+  group: string,
+  bodyFileName: string,
+  source: string,
+  sessionID: string,
+): Session {
+  const key = sessionKey(group, sessionID)
+  const workDir = join(STAGING_ROOT, key)
+  mkdirSync(workDir, { recursive: true })
+  const bodyPath = join(workDir, bodyFileName)
+  writeFileSync(bodyPath, source, "utf8")
+  const s: Session = { workDir, bodyPath }
+  sessions.set(key, s)
+  return s
+}
+
+/** Current managed file for this group+session, or undefined if none yet. */
+export function currentBody(group: string, sessionID: string): Session | undefined {
+  return sessions.get(sessionKey(group, sessionID))
+}
+
+/**
+ * Exact-match single replacement on the current source: old_text must appear
+ * exactly once. Returns the updated content and the match offset, or throws
+ * a precise error.
+ */
+export function applyEdit(current: string, oldText: string, newText: string): { updated: string; index: number } {
+  if (oldText === "") throw new Error("`old_text` must be non-empty.")
+  if (oldText === newText) throw new Error("`old_text` and `new_text` are identical.")
+  const first = current.indexOf(oldText)
+  if (first === -1) {
+    throw new Error("`old_text` not found in the current source — match it exactly.")
+  }
+  const second = current.indexOf(oldText, first + 1)
+  if (second !== -1) {
+    let n = 0
+    let i = current.indexOf(oldText)
+    while (i !== -1) {
+      n++
+      i = current.indexOf(oldText, i + oldText.length)
+    }
+    throw new Error(`\`old_text\` appears ${n} times — add surrounding context to make it unique.`)
+  }
+  const updated = current.slice(0, first) + newText + current.slice(first + oldText.length)
+  return { updated, index: first }
+}
+
+/** A small numbered window of `content` around char offset `index`. */
+export function snippetAround(content: string, index: number, contextLines = 3): string {
+  const before = content.slice(0, index)
+  const hitLine = before.split("\n").length - 1
+  const lines = content.split("\n")
+  const start = Math.max(0, hitLine - contextLines)
+  const end = Math.min(lines.length - 1, hitLine + contextLines)
+  const width = String(end + 1).length
+  const out: string[] = []
+  for (let i = start; i <= end; i++) out.push(`${String(i + 1).padStart(width)}  ${lines[i]}`)
+  return out.join("\n")
+}
+
+/** Copy a rendered PNG into `filesDir` (the exact output directory) with a unique, slugified name. */
+export function publish(pngPath: string, slug: string, filesDir?: string): { filename: string; path: string } {
+  const dir = filesDir || join(process.cwd(), FILES_DIRNAME)
+  mkdirSync(dir, { recursive: true })
+  const clean =
+    slug
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "viz"
+  const filename = `viz-${clean}-${Date.now()}.png`
+  const dest = join(dir, filename)
+  copyFileSync(pngPath, dest)
+  return { filename, path: dest }
+}
+
+export { existsSync, join, mkdirSync, readFileSync, writeFileSync }

package/plugins/viz/index.ts

@@ -0,0 +1,245 @@
+import { homedir } from "node:os"
+import { isAbsolute } from "node:path"
+import type { Plugin } from "@opencode/plugin"
+import {
+  applyEdit,
+  currentBody,
+  existsSync,
+  FILES_DIRNAME,
+  join,
+  mkdirSync,
+  publish,
+  readFileSync,
+  run,
+  snippetAround,
+  writeBody,
+  writeFileSync,
+} from "./common.ts"
+
+/**
+ * opencode-learn (viz tools) — the visual maker authoring loops as v2 custom tools.
+ *
+ * Ported from the pi visual-tools extension (extensions/visual-tools/):
+ *   svg      → write_svg / edit_svg / render_svg   (rsvg-convert, fallback magick)
+ *   mermaid  → write_mermaid / edit_mermaid / render_mermaid  (mmdc from PATH)
+ *
+ * Each trio shares ONE per-session managed source file (keyed by OpenCode
+ * sessionID when the harness provides it, else a shared key), so a maker
+ * writes, exact-match-edits, and renders without naming files.
+ *
+ * v2 beta constraint (see ocv2-findings): custom tool results cannot deliver
+ * images to the model. render_* therefore returns the PNG's absolute path and
+ * instructs the agent to LOOK at it via the native read tool — same
+ * render-and-inspect loop, one extra step.
+ */
+
+const SVG_GROUP = "svg"
+const MERMAID_GROUP = "mermaid"
+const SVG_BODY = "diagram.svg"
+const MERMAID_BODY = "diagram.mmd"
+
+/** Session key from the optional per-call context the harness passes execute. */
+function sid(tctx: any): string {
+  const s = tctx?.sessionID ?? tctx?.callID ?? tctx?.messageID
+  return typeof s === "string" && s.length > 0 ? s : "shared"
+}
+
+export async function setupViz(ctx: Plugin.Context): Promise<void> {
+  // Publish base: the project directory is captured once at setup. A configured
+  // defaultDir (viz-state.json, md-link-style) overrides it and is re-read on
+  // every publish so /viz-dir changes apply immediately; empty means publish
+  // into the project's viz/.
+  const projectDir = ctx.location?.directory ?? process.cwd()
+  const VIZ_STATE_FILE = join(homedir(), ".config", "opencode", "viz-state.json")
+
+  function resolvePublishDir(): string {
+    try {
+      const st = JSON.parse(readFileSync(VIZ_STATE_FILE, "utf8"))
+      const configured = typeof st?.defaultDir === "string" ? st.defaultDir.trim() : ""
+      if (configured) {
+        return isAbsolute(configured) ? configured : join(projectDir, configured)
+      }
+    } catch {}
+    return join(projectDir, FILES_DIRNAME)
+  }
+
+  // ── managed-file helpers shared by both trios ────────────────────────────
+  function requireBody(group: string, bodyFile: string, tctx: any) {
+    const s = currentBody(group, sid(tctx))
+    if (!s || !existsSync(s.bodyPath)) return null
+    return s
+  }
+
+  function makeWriteTool(group: string, bodyFile: string, kind: string, extraDesc: string) {
+    const cap = kind.toUpperCase()
+    return {
+      name: `write_${kind}`,
+      description:
+        `Write the FULL ${cap} source to this session's managed file (your first draft or a complete rewrite). ` +
+        `You do NOT name the file — edit_${kind} and render_${kind} act on the same one.\n\n` +
+        extraDesc +
+        ` Writing does NOT render — call render_${kind} when ready. For a small fix, prefer edit_${kind} over rewriting.`,
+      input: {
+        type: "object",
+        properties: {
+          source: { type: "string", description: `The complete ${cap} document.` },
+        },
+        required: ["source"],
+        additionalProperties: false,
+      },
+      execute: async (input: any, tctx: any) => {
+        try {
+          const source = String(input.source ?? "").trim()
+          if (!source) throw new Error(`\`write_${kind}\` requires a non-empty \`source\`.`)
+          if (kind === "svg" && !source.includes("<svg")) {
+            throw new Error("`write_svg`: source must be a complete <svg>…</svg> document.")
+          }
+          const s = writeBody(group, bodyFile, source, sid(tctx))
+          const lines = source.split("\n").length
+          return {
+            content: `Wrote ${lines}-line ${cap} source.\nCall render_${kind} to render it, or edit_${kind} to tweak it.`,
+          }
+        } catch (error) {
+          return { content: `❌ write_${kind} failed: ${error instanceof Error ? error.message : String(error)}` }
+        }
+      },
+    }
+  }
+
+  function makeEditTool(kind: string) {
+    const cap = kind.toUpperCase()
+    return {
+      name: `edit_${kind}`,
+      description:
+        `Make a single exact-match replacement in this session's ${cap} source — the same contract as the built-in edit, locked to the one managed file. ` +
+        `\`old_text\` must appear EXACTLY ONCE (include surrounding context for uniqueness); on 0 or >1 matches the call fails and nothing changes. ` +
+        `Call write_${kind} first. Editing does NOT render.`,
+      input: {
+        type: "object",
+        properties: {
+          old_text: { type: "string", description: "Exact substring of the current source to replace (must match once)." },
+          new_text: { type: "string", description: "Replacement text for `old_text`." },
+        },
+        required: ["old_text", "new_text"],
+        additionalProperties: false,
+      },
+      execute: async (input: any, tctx: any) => {
+        try {
+          const s = requireBody(kind === "svg" ? SVG_GROUP : MERMAID_GROUP, kind === "svg" ? SVG_BODY : MERMAID_BODY, tctx)
+          if (!s) throw new Error(`edit_${kind}: no source yet — call write_${kind} first.`)
+          const current = readFileSync(s.bodyPath, "utf8")
+          const { updated, index } = applyEdit(current, String(input.old_text ?? ""), String(input.new_text ?? ""))
+          writeFileSync(s.bodyPath, updated, "utf8")
+          return {
+            content:
+              `Applied edit. Updated region:\n\`\`\`\n${snippetAround(updated, index)}\n\`\`\`\nCall render_${kind} to see it.`,
+          }
+        } catch (error) {
+          return { content: `❌ edit_${kind} failed: ${error instanceof Error ? error.message : String(error)}` }
+        }
+      },
+    }
+  }
+
+  function makeRenderTool(kind: string) {
+    const cap = kind.toUpperCase()
+    return {
+      name: `render_${kind}`,
+      description:
+        `Render the CURRENT session ${cap} source to a PNG, then OPEN the returned PNG path with the read tool and LOOK at it before continuing — ` +
+        `rendering success proves nothing about correctness. You do NOT pass the source here; call write_${kind} first.\n\n` +
+        `Iterate freely with no \`save_as\` (preview only). When it is correct and clean, call once more with \`save_as\` set to a short kebab-case topic slug: ` +
+        `that publishes the PNG into <project>/viz (or the dir configured via ~/.config/opencode/viz-state.json) with a unique filename and returns the filename to embed. On a render error this returns error text — fix with edit_${kind} and re-render.`,
+      input: {
+        type: "object",
+        properties: {
+          save_as: {
+            type: "string",
+            description:
+              "Short kebab-case topic slug (e.g. 'number-line'). When set, publishes to <project>/viz as viz-<slug>-<timestamp>.png. Omit for preview-only.",
+          },
+        },
+        additionalProperties: false,
+      },
+      execute: async (input: any, tctx: any) => {
+        let outPath = ""
+        try {
+          const group = kind === "svg" ? SVG_GROUP : MERMAID_GROUP
+          const bodyFile = kind === "svg" ? SVG_BODY : MERMAID_BODY
+          const s = requireBody(group, bodyFile, tctx)
+          if (!s) throw new Error(`render_${kind}: no source yet — call write_${kind} first.`)
+          mkdirSync(s.workDir, { recursive: true })
+          outPath = join(s.workDir, `render-${Date.now()}.png`)
+
+          let res =
+            kind === "svg"
+              ? await run("rsvg-convert", ["-z", "2", s.bodyPath, "-o", outPath], {
+                  cwd: s.workDir,
+                  timeoutMs: 60_000,
+                })
+              : await run("mmdc", ["-i", s.bodyPath, "-o", outPath, "-s", "2", "-b", "white"], {
+                  cwd: s.workDir,
+                  timeoutMs: 120_000,
+                })
+
+          // SVG fallback chain: rsvg-convert → ImageMagick.
+          if (kind === "svg" && !(res.code === 0 && existsSync(outPath))) {
+            res = await run("magick", ["-density", "192", "-background", "white", s.bodyPath, outPath], {
+              cwd: s.workDir,
+              timeoutMs: 60_000,
+            })
+          }
+
+          if (res.code !== 0 || !existsSync(outPath)) {
+            const detail = (res.stderr || res.stdout || "unknown error").split("\n").slice(-30).join("\n")
+            const note = res.timedOut ? `${kind === "svg" ? "SVG" : "mmdc"} render timed out.\n\n` : ""
+            return {
+              content:
+                `${note}${cap} render FAILED — no PNG produced. Fix the source with edit_${kind} and call render_${kind} again.\n\nError:\n${detail}`,
+            }
+          }
+
+          const look = `NOW open ${outPath} with the read tool and LOOK at it. `
+          if (input.save_as) {
+            const pub = publish(outPath, String(input.save_as), resolvePublishDir())
+            return {
+              content:
+                `Published to viz/.\nfilename: ${pub.filename}\npath: ${pub.path}\n\n${look}Confirm it is correct and true to the brief before returning it.`,
+            }
+          }
+          return {
+            content:
+              `Preview render (not yet saved): ${outPath}\n\n${look}` +
+              `Are coordinates/arrows/relationships correct, labels clear, nothing clipped or cramped? ` +
+              `Fix with edit_${kind}, or re-render with \`save_as\` to publish.`,
+          }
+        } catch (error) {
+          return { content: `❌ render_${kind} failed: ${error instanceof Error ? error.message : String(error)}` }
+        }
+      },
+    }
+  }
+
+  await ctx.tool.transform((tools: any) => {
+    tools.add(
+      makeWriteTool(
+        SVG_GROUP,
+        SVG_BODY,
+        "svg",
+        "`source` is a complete `<svg …>…</svg>` document with an explicit width/height (or viewBox), readable font sizes, and a light or transparent background.",
+      ) as any,
+    )
+    tools.add(makeEditTool("svg") as any)
+    tools.add(makeRenderTool("svg") as any)
+    tools.add(
+      makeWriteTool(
+        MERMAID_GROUP,
+        MERMAID_BODY,
+        "mermaid",
+        "`source` is a complete Mermaid diagram, e.g. `graph TD`/`graph LR`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, `classDiagram`, `mindmap`, or `timeline`.",
+      ) as any,
+    )
+    tools.add(makeEditTool("mermaid") as any)
+    tools.add(makeRenderTool("mermaid") as any)
+  })
+}

package/plugins/viz/tui.ts

@@ -0,0 +1,104 @@
+/**
+ * opencode-learn.tui — TUI command for the viz publish directory.
+ *
+ * The opencode-learn server plugin reads defaultDir from
+ * ~/.config/opencode/viz-state.json on every publish (empty = the project dir
+ * captured at plugin setup, ctx.location.directory, + viz/). This module adds
+ * the /viz-dir command that edits it:
+ *
+ *   /viz-dir            open the dialog (prefilled with the current value)
+ *   /viz-dir <path>     set it directly; relative paths resolve against the
+ *                       session's project at publish time
+ *
+ * Empty input in the dialog clears the override. This module loads through
+ * the package's `./tui` export, reached from plugins/tui.ts.
+ */
+
+import { readFileSync, writeFileSync } from "fs"
+import { homedir } from "node:os"
+import { isAbsolute, join } from "node:path"
+import type { Plugin } from "@opencode/plugin/tui"
+
+type DirResult = { ok: true; value: string } | { ok: false; error: string }
+type ToastVariant = "info" | "success" | "warning" | "error"
+
+const STATE_FILE = join(homedir(), ".config", "opencode", "viz-state.json")
+
+function loadState(): { defaultDir: string } {
+  try {
+    const raw = JSON.parse(readFileSync(STATE_FILE, "utf8"))
+    return { defaultDir: typeof raw?.defaultDir === "string" ? raw.defaultDir : "" }
+  } catch {
+    return { defaultDir: "" }
+  }
+}
+
+function saveState(st: { defaultDir: string }): void {
+  writeFileSync(STATE_FILE, JSON.stringify(st, null, 2), "utf8")
+}
+
+/** Light validation: publish creates the dir, so it only has to be sane. */
+function validateDir(raw: string): DirResult {
+  const v = String(raw ?? "").trim().replace(/^["']+|["']+$/g, "")
+  if (v.includes("\0")) return { ok: false, error: "invalid path" }
+  if (v.split("/").includes("..")) return { ok: false, error: "path may not contain '..'" }
+  if (v.length > 0 && !/^[A-Za-z0-9 ._\-\/~]+$/.test(v)) {
+    return { ok: false, error: `unsupported characters in "${v}"` }
+  }
+  return { ok: true, value: v }
+}
+
+export async function setupVizTui(ctx: Plugin.Context): Promise<void> {
+  const toast = (message: string, variant: ToastVariant = "info") => {
+    try {
+      ctx.ui?.toast?.show?.({ title: "viz", message, variant })
+    } catch {}
+  }
+
+  async function openSetDirDialog(): Promise<void> {
+    try {
+      const v = await ctx.ui.dialog.prompt({
+        title: "viz output directory",
+        description: "Where render_* saves published PNGs. Empty = the session project's viz/.",
+        placeholder: "absolute path, or relative to the project",
+        value: loadState().defaultDir,
+      })
+      if (typeof v !== "string") return // cancelled
+      const res = validateDir(v)
+      if (!res.ok) {
+        toast(`Invalid dir: ${res.error}`, "error")
+        return
+      }
+      const st = loadState()
+      st.defaultDir = res.value
+      saveState(st)
+      toast(
+        res.value
+          ? `Viz output dir set → ${res.value}${isAbsolute(res.value) ? "" : " (relative to project)"}`
+          : "Viz output dir cleared — publishing into the session project's viz/",
+      )
+    } catch (e: any) {
+      toast(`Cannot open dialog: ${e?.message ?? e}`, "error")
+    }
+  }
+
+  // ——— registration (callable directly from setup; removed on deactivate) ———
+
+  ctx.keymap.layer(() => ({
+    mode: "global",
+    priority: 1,
+    enabled: true,
+    commands: [
+      {
+        id: "viz.setdir",
+        title: "Output directory…",
+        group: "viz",
+        palette: true,
+        slash: { name: "viz-dir" },
+        run: () => openSetDirDialog(),
+      },
+    ],
+  }))
+
+  return undefined
+}