sql-harness 0.3.4__tar.gz → 0.3.5__tar.gz

{sql_harness-0.3.4 → sql_harness-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-harness
-Version: 0.3.4
+Version: 0.3.5
 Summary: Single-process SQL + SSH CLI for LLM agents. PostgreSQL/MySQL/SSH via SQLAlchemy + paramiko. Plaintext credentials in one TOML file. Helpers auto-injected into the heredoc namespace.
 Project-URL: Source, https://github.com/zhaoliuxue/much_bigpy/tree/master/lab/sql_harness
 Project-URL: Issues, https://github.com/zhaoliuxue/much_bigpy/issues
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Database
 Classifier: Topic :: System :: Shells
 Requires-Python: >=3.12
+Requires-Dist: markdown-it-py<4,>=3
 Requires-Dist: paramiko<4,>=3.4
 Requires-Dist: psycopg[binary]<4,>=3.2
 Requires-Dist: pymysql<2,>=1.1
@@ -49,6 +50,9 @@ print(query("SELECT version()"))
 print(list_tables())
 print(describe("pg_class"))
 PY
+
+# 6. Browse + edit the docs (SKILL.md, interaction-skills/, your zone skills)
+uv run sql-harness web
 ```
 
 ## Architecture (~1k lines across 8 core files)

{sql_harness-0.3.4 → sql_harness-0.3.5}/SKILL.md

@@ -42,7 +42,7 @@ PY
 - **First call requires `use_workspace(name)`** — no implicit default.
 - Set `BH_SQL_ZONE_SKILLS=1` once so `use_workspace()` auto-surfaces that zone's per-DSN skill docs (see `interaction-skills/zone-skill-auto-surface.md`).
 - For task-specific helpers, drop them into `agent-workspace/zones/<conn>/helpers.py` and they merge into the heredoc namespace (per-zone, overriding the shared base).
-- Other subcommands: `init` (scaffold connections.toml + install preset zone skills), `doctor` (SELECT 1 on every connection), `edit`/`remove`/`show`, `workspace {list,use,close,show}`, `save`/`run`/`scripts`, `skill` (bare: emit packaged SKILL.md; `install`/`list`/`show`), `paths`, `open`, `stats`, `version`, `ssh {exec,upload,download,run-script,info}`.
+- Other subcommands: `init` (scaffold connections.toml + install preset zone skills), `doctor` (SELECT 1 on every connection), `edit`/`remove`/`show`, `workspace {list,use,close,show}`, `save`/`run`/`scripts`, `skill` (bare: emit packaged SKILL.md; `install`/`list`/`show`), `paths`, `open`, `web` (browse + edit the whole doc library in a local web UI — shipped docs, runtime zones, saved scripts), `stats`, `version`, `ssh {exec,upload,download,run-script,info}`.
 - Zone-scoped subcommands (`save`, `run`, `scripts`, `skill list/show`, `ssh`) need `-c <conn>` or `$BH_SQL_ACTIVE_CONNECTION`.
 - **Analytics (ON by default)**: every CLI call and every doc read (`apply_skill`, `skill`, `skill show`) is counted into `$BH_SQL_HOME/analytics.json`; view with `sql-harness stats`. Every executed command (CLI argv or heredoc body) plus failures is appended to `$BH_SQL_HOME/sql-harness.log` (NDJSON, one record per line). Disable both with `BH_SQL_ANALYTICS=0|off|false|no`. Extension point: `from sql_harness.analytics import on, CLI_INVOKED, DOC_READ, COMMAND_EXECUTED` to attach custom listeners (observer pattern).
 

{sql_harness-0.3.4 → sql_harness-0.3.5}/docs/AGENTS.md

@@ -18,8 +18,9 @@ Core code lives in `lab/sql_harness/src/sql_harness/`:
 - `agent_loader.py` — loads `$BH_SQL_AGENT_WORKSPACE/agent_helpers.py`
 - `analytics.py` — event bus (observer) + JSON stats + NDJSON execution log: CLI call counts, doc-read tracking, command/error history; `BH_SQL_ANALYTICS` (default ON), view with `sql-harness stats`
 - `output.py` — terminal output policy: UTF-8 stream setup, long-output spill to `$BH_SQL_HOME/tmp/output/`, concise error rendering; `BH_SQL_TRACEBACK=1` forces raw tracebacks
+- `webapp.py` — `sql-harness web`: serves the doc library (shipped docs + runtime zones + saved scripts) over loopback with an in-page editor. `resolve_doc()` is the write boundary — read its docstring before touching path handling
 - `run.py` — heredoc entry; delegates to CLI otherwise
-- `cli.py` — argparse subparser CLI (18 subcommands)
+- `cli.py` — argparse subparser CLI (19 subcommands)
 
 `SKILL.md` tells agents how to use the harness.
 `docs/install.md` tells agents how to install and configure it.

{sql_harness-0.3.4 → sql_harness-0.3.5}/docs/README.md

@@ -26,6 +26,9 @@ print(query("SELECT version()"))
 print(list_tables())
 print(describe("pg_class"))
 PY
+
+# 6. Browse + edit the docs (SKILL.md, interaction-skills/, your zone skills)
+uv run sql-harness web
 ```
 
 ## Architecture (~1k lines across 8 core files)

{sql_harness-0.3.4 → sql_harness-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-harness"
-version = "0.3.4"
+version = "0.3.5"
 description = "Single-process SQL + SSH CLI for LLM agents. PostgreSQL/MySQL/SSH via SQLAlchemy + paramiko. Plaintext credentials in one TOML file. Helpers auto-injected into the heredoc namespace."
 readme = "docs/README.md"
 license = { text = "MIT" }
@@ -24,6 +24,7 @@ dependencies = [
     "pymysql>=1.1,<2",
     "sqlalchemy>=2.0,<3",
     "paramiko>=3.4,<4",
+    "markdown-it-py>=3,<4",
 ]
 
 [project.scripts]
@@ -38,6 +39,10 @@ sql-harness = "sql_harness.run:main"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true
+
 [tool.hatch.build.targets.wheel]
 # Mirrors browser-harness's setuptools src-layout. The package source is
 # under `src/sql_harness/`; the package name (top-level import) is `sql_harness`.

sql_harness-0.3.5/src/sql_harness/_web/app.css

@@ -0,0 +1,191 @@
+/* sql-harness doc browser — docs-site styling, no framework. */
+
+:root {
+  --bg: #ffffff;
+  --bg-soft: #f6f7f9;
+  --bg-side: #fafbfc;
+  --fg: #1f2328;
+  --fg-soft: #59636e;
+  --fg-faint: #818b98;
+  --line: #d8dee4;
+  --line-soft: #eaeef2;
+  --accent: #0969da;
+  --accent-soft: #ddf4ff;
+  --danger: #cf222e;
+  --ok: #1a7f37;
+  --code-bg: #f6f8fa;
+  --radius: 6px;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+  --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0d1117; --bg-soft: #161b22; --bg-side: #0f141b;
+    --fg: #e6edf3; --fg-soft: #9198a1; --fg-faint: #6e7681;
+    --line: #30363d; --line-soft: #21262d;
+    --accent: #4493f8; --accent-soft: #121d2f;
+    --danger: #f85149; --ok: #3fb950; --code-bg: #161b22;
+  }
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0; height: 100%;
+  background: var(--bg); color: var(--fg);
+  font-family: var(--sans); font-size: 15px; line-height: 1.65;
+}
+
+.app { display: flex; height: 100vh; }
+
+/* --- sidebar --- */
+.sidebar {
+  width: 310px; flex: 0 0 310px; height: 100vh;
+  display: flex; flex-direction: column;
+  background: var(--bg-side); border-right: 1px solid var(--line);
+}
+.brand {
+  display: flex; align-items: baseline; gap: 8px;
+  padding: 16px 18px 12px; font-weight: 600;
+}
+.brand-name { font-size: 15px; letter-spacing: -0.01em; }
+.brand-ver { font-size: 12px; color: var(--fg-faint); font-weight: 400; }
+
+.filter {
+  margin: 0 12px 10px; padding: 7px 10px;
+  border: 1px solid var(--line); border-radius: var(--radius);
+  background: var(--bg); color: var(--fg); font-size: 13px; font-family: inherit;
+}
+.filter:focus { outline: none; border-color: var(--accent); }
+
+.nav { flex: 1; overflow-y: auto; padding: 0 8px 24px; }
+.group-title {
+  padding: 14px 10px 6px; font-size: 11px; font-weight: 600;
+  text-transform: uppercase; letter-spacing: 0.06em; color: var(--fg-faint);
+}
+.root-title {
+  display: flex; align-items: center; gap: 6px;
+  padding: 5px 10px; font-size: 13px; font-weight: 600; color: var(--fg-soft);
+}
+.badge {
+  font-size: 10px; font-weight: 500; padding: 1px 5px; border-radius: 20px;
+  background: var(--accent-soft); color: var(--accent);
+}
+.count { margin-left: auto; font-size: 11px; color: var(--fg-faint); font-weight: 400; }
+
+.nav details { margin: 0; }
+.nav summary {
+  cursor: pointer; list-style: none; padding: 3px 10px 3px 22px;
+  font-size: 13px; color: var(--fg-soft); border-radius: var(--radius);
+}
+.nav summary::-webkit-details-marker { display: none; }
+.nav summary::before { content: "▸ "; color: var(--fg-faint); font-size: 10px; }
+.nav details[open] > summary::before { content: "▾ "; }
+.nav summary:hover { background: var(--bg-soft); }
+
+.nav a {
+  display: block; padding: 3px 10px 3px 34px;
+  font-size: 13px; color: var(--fg-soft); text-decoration: none;
+  border-radius: var(--radius); overflow: hidden;
+  text-overflow: ellipsis; white-space: nowrap;
+}
+.nav a:hover { background: var(--bg-soft); color: var(--fg); }
+.nav a.active { background: var(--accent-soft); color: var(--accent); font-weight: 500; }
+.nav .empty { padding: 2px 10px 2px 34px; font-size: 12px; color: var(--fg-faint); }
+
+.sidebar-foot {
+  padding: 10px 18px; border-top: 1px solid var(--line-soft);
+  font-size: 12px; color: var(--fg-faint); display: flex; align-items: center; gap: 6px;
+}
+.dot { width: 7px; height: 7px; border-radius: 50%; background: var(--ok); }
+.dot.ro { background: var(--fg-faint); }
+
+/* --- content --- */
+.content { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+
+.doc-head {
+  display: flex; align-items: center; gap: 12px;
+  padding: 12px 32px; border-bottom: 1px solid var(--line-soft);
+  position: sticky; top: 0; background: var(--bg); z-index: 5;
+}
+.crumb {
+  font-family: var(--mono); font-size: 12px; color: var(--fg-faint);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1;
+}
+.actions { display: flex; gap: 8px; flex: 0 0 auto; }
+.actions button {
+  padding: 5px 12px; font-size: 13px; font-family: inherit;
+  border: 1px solid var(--line); border-radius: var(--radius);
+  background: var(--bg-soft); color: var(--fg); cursor: pointer;
+}
+.actions button:hover { border-color: var(--fg-faint); }
+.actions button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+.actions button.primary:hover { filter: brightness(1.08); }
+.actions button:disabled { opacity: 0.5; cursor: default; }
+
+.markdown, .editor { flex: 1; overflow-y: auto; }
+.markdown { padding: 28px 32px 80px; max-width: 860px; }
+.editor {
+  margin: 0; padding: 20px 24px; border: none; resize: none;
+  background: var(--code-bg); color: var(--fg);
+  font-family: var(--mono); font-size: 13px; line-height: 1.6;
+}
+.editor:focus { outline: none; }
+
+/* --- metadata panel --- */
+.meta {
+  margin: 20px 32px -8px; padding: 12px 16px;
+  border: 1px solid var(--line); border-left: 3px solid var(--accent);
+  border-radius: var(--radius); background: var(--bg-soft);
+  font-size: 13px; max-width: 860px;
+}
+.meta dl { margin: 0; display: grid; grid-template-columns: 90px 1fr; gap: 4px 12px; }
+.meta dt { color: var(--fg-faint); font-family: var(--mono); font-size: 12px; }
+.meta dd { margin: 0; color: var(--fg-soft); word-break: break-word; }
+
+/* --- status line --- */
+.status {
+  padding: 8px 32px; font-size: 13px; border-top: 1px solid var(--line-soft);
+  background: var(--bg-soft);
+}
+.status.err { color: var(--danger); }
+.status.ok { color: var(--ok); }
+
+/* --- markdown --- */
+.markdown h1, .markdown h2, .markdown h3, .markdown h4 {
+  line-height: 1.3; margin: 1.6em 0 0.6em; font-weight: 600; letter-spacing: -0.01em;
+}
+.markdown h1 { font-size: 1.9em; margin-top: 0; padding-bottom: 0.3em; border-bottom: 1px solid var(--line-soft); }
+.markdown h2 { font-size: 1.4em; padding-bottom: 0.25em; border-bottom: 1px solid var(--line-soft); }
+.markdown h3 { font-size: 1.15em; }
+.markdown p, .markdown ul, .markdown ol { margin: 0.85em 0; }
+.markdown ul, .markdown ol { padding-left: 1.6em; }
+.markdown li { margin: 0.25em 0; }
+.markdown a { color: var(--accent); text-decoration: none; }
+.markdown a:hover { text-decoration: underline; }
+.markdown code {
+  font-family: var(--mono); font-size: 0.87em;
+  background: var(--code-bg); padding: 0.15em 0.4em; border-radius: 4px;
+}
+.markdown pre {
+  background: var(--code-bg); padding: 14px 16px; border-radius: var(--radius);
+  overflow-x: auto; border: 1px solid var(--line-soft);
+}
+.markdown pre code { background: none; padding: 0; font-size: 12.5px; line-height: 1.55; }
+.markdown blockquote {
+  margin: 0.9em 0; padding: 0 1em; color: var(--fg-soft);
+  border-left: 3px solid var(--line);
+}
+.markdown table {
+  border-collapse: collapse; margin: 1em 0; display: block; overflow-x: auto; max-width: 100%;
+}
+.markdown th, .markdown td { border: 1px solid var(--line); padding: 6px 12px; text-align: left; }
+.markdown th { background: var(--bg-soft); font-weight: 600; }
+.markdown hr { border: none; border-top: 1px solid var(--line-soft); margin: 2em 0; }
+
+@media (max-width: 820px) {
+  .app { flex-direction: column; }
+  .sidebar { width: 100%; flex: 0 0 45vh; height: 45vh; border-right: none; border-bottom: 1px solid var(--line); }
+  .markdown, .doc-head, .status, .meta { padding-left: 16px; padding-right: 16px; margin-left: 0; margin-right: 0; }
+}

sql_harness-0.3.5/src/sql_harness/_web/app.js

@@ -0,0 +1,318 @@
+/* sql-harness doc browser. Vanilla JS, hash routing, no build step. */
+
+const $ = (id) => document.getElementById(id);
+
+const GROUP_LABELS = { source: "Shipped docs", runtime: "Runtime workspace" };
+
+const state = {
+  roots: [],
+  current: null,   // { root, path, sha256, raw, editable }
+  editing: false,
+  dirty: false,
+};
+
+/* --- helpers ------------------------------------------------------------- */
+
+function setStatus(msg, kind) {
+  const el = $("status");
+  if (!msg) { el.hidden = true; el.textContent = ""; return; }
+  el.hidden = false;
+  el.textContent = msg;
+  el.className = "status" + (kind ? " " + kind : "");
+}
+
+async function api(path, options) {
+  const res = await fetch(path, options);
+  let body = null;
+  try { body = await res.json(); } catch (_) { /* non-JSON error page */ }
+  if (!res.ok) {
+    const err = new Error((body && body.error) || res.status + " " + res.statusText);
+    err.status = res.status;
+    err.body = body;
+    throw err;
+  }
+  return body;
+}
+
+/* --- sidebar ------------------------------------------------------------- */
+
+function renderNav() {
+  const filter = $("filter").value.trim().toLowerCase();
+  const nav = $("nav");
+  nav.textContent = "";
+
+  const groups = {};
+  for (const root of state.roots) (groups[root.kind] ||= []).push(root);
+
+  for (const [kind, roots] of Object.entries(groups)) {
+    const title = document.createElement("div");
+    title.className = "group-title";
+    title.textContent = GROUP_LABELS[kind] || kind;
+    nav.appendChild(title);
+
+    for (const root of roots) {
+      const head = document.createElement("div");
+      head.className = "root-title";
+      const name = document.createElement("span");
+      name.textContent = root.label;
+      head.appendChild(name);
+      if (root.connection) {
+        const badge = document.createElement("span");
+        badge.className = "badge";
+        badge.textContent = root.connection;
+        head.appendChild(badge);
+      }
+      if (!root.editable) {
+        const ro = document.createElement("span");
+        ro.className = "badge";
+        ro.textContent = "只读";
+        head.appendChild(ro);
+      }
+      const count = document.createElement("span");
+      count.className = "count";
+      count.textContent = root.file_count;
+      head.appendChild(count);
+      nav.appendChild(head);
+
+      nav.appendChild(renderNodes(root, root.tree, ""));
+    }
+  }
+  if (!nav.children.length) {
+    const empty = document.createElement("div");
+    empty.className = "empty";
+    empty.textContent = "没有文档";
+    nav.appendChild(empty);
+  }
+  void filter;
+}
+
+function renderNodes(root, nodes, prefix) {
+  const frag = document.createDocumentFragment();
+  nodes.sort((a, b) => (a.type === "file") - (b.type === "file") || a.name.localeCompare(b.name));
+
+  for (const node of nodes) {
+    const path = prefix ? prefix + "/" + node.name : node.name;
+    if (node.type === "file") {
+      const a = document.createElement("a");
+      a.href = "#/" + encodeURIComponent(root.id) + "/" + encodeURI(path.split("/").map(encodeURIComponent).join("/"));
+      a.textContent = node.name;
+      a.dataset.key = root.id + ":" + path;
+      if (node.kind === "other") a.title = "不支持预览的文件类型";
+      frag.appendChild(a);
+    } else if (node.type === "dir") {
+      const det = document.createElement("details");
+      const sum = document.createElement("summary");
+      sum.textContent = node.name;
+      det.appendChild(sum);
+      det.appendChild(renderNodes(root, node.children || [], path));
+      frag.appendChild(det);
+    }
+  }
+  return frag;
+}
+
+function markActive() {
+  const key = state.current ? state.current.root + ":" + state.current.path : "";
+  document.querySelectorAll("#nav a").forEach((a) => {
+    const on = a.dataset.key === key;
+    a.classList.toggle("active", on);
+    if (on) {
+      a.closest("details")?.setAttribute("open", "");
+      a.scrollIntoView({ block: "nearest" });
+    }
+  });
+}
+
+/* --- document ------------------------------------------------------------ */
+
+function setEditing(on) {
+  state.editing = on;
+  $("editor").hidden = !on;
+  $("doc").hidden = on;
+  $("meta").hidden = on || $("meta").dataset.empty === "1";
+  $("btn-edit").hidden = on || !(state.current && state.current.editable);
+  $("btn-save").hidden = !on;
+  $("btn-cancel").hidden = !on;
+  $("btn-save").disabled = !state.dirty;
+  if (on) $("editor").focus();
+}
+
+function renderMeta(meta) {
+  const el = $("meta");
+  const keys = Object.keys(meta || {}).filter((k) => k !== "_raw");
+  el.textContent = "";
+  if (!keys.length) {
+    el.hidden = true;
+    el.dataset.empty = "1";
+    return;
+  }
+  const dl = document.createElement("dl");
+  for (const key of keys) {
+    const dt = document.createElement("dt");
+    dt.textContent = key;
+    const dd = document.createElement("dd");
+    dd.textContent = meta[key];
+    dl.append(dt, dd);
+  }
+  el.appendChild(dl);
+  el.dataset.empty = "0";
+  el.hidden = state.editing;
+}
+
+async function openDoc(rootId, path) {
+  if (state.dirty && !confirm("有未保存的修改，确定要离开吗？")) return;
+  setStatus("载入中…");
+  try {
+    const doc = await api("/api/doc?root=" + encodeURIComponent(rootId) + "&path=" + encodeURIComponent(path));
+    state.current = doc;
+    state.dirty = false;
+
+    $("crumb").textContent = doc.root + " / " + doc.path + "   ·   " + doc.size + " B";
+    $("editor").value = doc.raw;
+
+    if (doc.html === null) {
+      $("doc").innerHTML = "";
+      const p = document.createElement("p");
+      p.textContent = "该文件类型不支持预览（" + doc.kind + "）。";
+      $("doc").appendChild(p);
+    } else {
+      $("doc").innerHTML = doc.html;
+    }
+    renderMeta(doc.frontmatter);
+    setEditing(false);
+    markActive();
+    setStatus("");
+  } catch (err) {
+    setStatus("打开失败：" + err.message, "err");
+  }
+}
+
+async function save() {
+  if (!state.current) return;
+  const content = $("editor").value;
+  $("btn-save").disabled = true;
+  setStatus("保存中…");
+  try {
+    const res = await api("/api/doc", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        root: state.current.root,
+        path: state.current.path,
+        content: content,
+        base_sha256: state.current.sha256,
+      }),
+    });
+    state.dirty = false;
+    setStatus("已保存 " + res.size + " B", "ok");
+    await refreshTree();
+    await openDoc(state.current.root, state.current.path);
+  } catch (err) {
+    $("btn-save").disabled = false;
+    if (err.status === 409) {
+      const overwrite = confirm(
+        "这个文件在磁盘上已经被改过了（可能是 agent 写的）。\n\n" +
+        "确定 = 用我编辑器里的内容覆盖它\n取消 = 丢弃我的修改，重新载入磁盘版本"
+      );
+      if (overwrite) {
+        state.current.sha256 = err.body.sha256;
+        return save();
+      }
+      await refreshTree();
+      await openDoc(state.current.root, state.current.path);
+      return;
+    }
+    setStatus("保存失败：" + err.message, "err");
+  }
+}
+
+/* --- boot ---------------------------------------------------------------- */
+
+async function refreshTree() {
+  const data = await api("/api/tree");
+  state.roots = data.roots;
+  $("version").textContent = "v" + data.version;
+  renderNav();
+  markActive();
+}
+
+function applyHash() {
+  const hash = decodeURIComponent(location.hash.replace(/^#\/?/, ""));
+  if (!hash) return;
+  const idx = hash.indexOf("/");
+  if (idx < 0) return;
+  const rootId = hash.slice(0, idx);
+  const path = hash.slice(idx + 1).split("/").map(decodeURIComponent).join("/");
+  openDoc(rootId, path);
+}
+
+function boot() {
+  $("btn-refresh").addEventListener("click", async () => {
+    await refreshTree();
+    setStatus("文件树已刷新", "ok");
+  });
+  $("btn-edit").addEventListener("click", () => setEditing(true));
+  $("btn-cancel").addEventListener("click", () => {
+    if (state.dirty && !confirm("放弃未保存的修改？")) return;
+    state.dirty = false;
+    $("editor").value = state.current ? state.current.raw : "";
+    setEditing(false);
+    setStatus("");
+  });
+  $("btn-save").addEventListener("click", save);
+  $("editor").addEventListener("input", () => {
+    state.dirty = $("editor").value !== (state.current ? state.current.raw : "");
+    $("btn-save").disabled = !state.dirty;
+  });
+  $("filter").addEventListener("input", () => {
+    const q = $("filter").value.trim().toLowerCase();
+    document.querySelectorAll("#nav a").forEach((a) => {
+      a.style.display = !q || a.textContent.toLowerCase().includes(q) ? "" : "none";
+    });
+  });
+  window.addEventListener("hashchange", applyHash);
+  window.addEventListener("beforeunload", (e) => {
+    if (state.dirty) { e.preventDefault(); e.returnValue = ""; }
+  });
+  document.addEventListener("keydown", (e) => {
+    if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "s") {
+      e.preventDefault();
+      if (state.editing && state.dirty) save();
+    } else if (e.key === "Escape" && state.editing) {
+      $("btn-cancel").click();
+    }
+  });
+
+  api("/api/health").then((h) => {
+    $("ro-label").textContent = h.read_only ? "只读模式" : "可编辑";
+    if (h.read_only) $("ro-dot").classList.add("ro");
+  });
+
+  refreshTree()
+    .then(() => {
+      if (location.hash) applyHash();
+      else if (state.roots.length) {
+        // Open something real rather than an empty pane.
+        const first = state.roots.find((r) => r.file_count > 0);
+        const pick = firstFile(first);
+        if (pick && first) location.hash = "#/" + encodeURIComponent(first.id) + "/" + pick;
+      }
+    })
+    .catch((err) => setStatus("初始化失败：" + err.message, "err"));
+}
+
+function firstFile(root) {
+  if (!root) return null;
+  const walk = (nodes, prefix) => {
+    for (const n of nodes) {
+      const path = prefix ? prefix + "/" + n.name : n.name;
+      if (n.type === "file") return path;
+      const deeper = n.children && walk(n.children, path);
+      if (deeper) return deeper;
+    }
+    return null;
+  };
+  return walk(root.tree || [], "");
+}
+
+document.addEventListener("DOMContentLoaded", boot);

sql_harness-0.3.5/src/sql_harness/_web/index.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>sql-harness docs</title>
+<link rel="stylesheet" href="/static/app.css">
+</head>
+<body>
+<div class="app">
+  <aside class="sidebar">
+    <div class="brand">
+      <span class="brand-name">sql-harness</span>
+      <span class="brand-ver" id="version"></span>
+    </div>
+    <input id="filter" class="filter" type="search" placeholder="过滤文档…" autocomplete="off">
+    <nav id="nav" class="nav"></nav>
+    <div class="sidebar-foot">
+      <span class="dot" id="ro-dot"></span><span id="ro-label">可编辑</span>
+    </div>
+  </aside>
+
+  <main class="content">
+    <header class="doc-head">
+      <div class="crumb" id="crumb">选择左侧的文档</div>
+      <div class="actions">
+        <button id="btn-refresh" type="button" title="重新读取文件树">刷新</button>
+        <button id="btn-edit" type="button" hidden>编辑</button>
+        <button id="btn-save" type="button" class="primary" hidden>保存</button>
+        <button id="btn-cancel" type="button" hidden>取消</button>
+      </div>
+    </header>
+
+    <div id="meta" class="meta" hidden></div>
+    <article id="doc" class="markdown"></article>
+    <textarea id="editor" class="editor" hidden spellcheck="false"></textarea>
+    <div id="status" class="status" hidden></div>
+  </main>
+</div>
+<script src="/static/app.js"></script>
+</body>
+</html>