makersclaw 0.2.0 → 0.3.0

package/registry/blocks/code-editor/demo.jsx

@@ -0,0 +1,205 @@
+"use client";
+
+// CodeEditor three ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   SQL     a query box over a small CRM schema: autocomplete knows the
+//           tables, Cmd/Ctrl+Enter (or Run) runs the statement under the
+//           cursor against rows in memory; a misspelt table comes back as
+//           an error drawn on the text, as a database would report it.
+//   JSON    a webhook payload, checked as you type, with a Format button
+//           through the handle.
+//   Empty   the first-run state with its placeholder, and read-only.
+import { useState } from "react";
+import { Badge, Button, Notice, Switch, TabPanel, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tabs } from "../components/ui";
+import { CodeEditor, useCodeEditor } from "../components/blocks/code-editor";
+
+const CRM_TABLES = [
+  {
+    name: "deals",
+    description: "Every open and closed deal",
+    columns: [
+      { name: "id", type: "uuid", primaryKey: true },
+      { name: "account_id", type: "uuid", description: "The account this deal is with" },
+      { name: "owner", type: "text" },
+      { name: "amount", type: "numeric" },
+      { name: "stage", type: "text", description: "lead · qualified · proposal · won · lost" },
+      { name: "closed_at", type: "timestamptz" },
+    ],
+  },
+  {
+    name: "accounts",
+    description: "Companies you sell to",
+    columns: [
+      { name: "id", type: "uuid", primaryKey: true },
+      { name: "name", type: "text" },
+      { name: "industry", type: "text" },
+      { name: "employees", type: "int4" },
+    ],
+  },
+  { name: "contacts", columns: [{ name: "id", type: "uuid", primaryKey: true }, { name: "account_id", type: "uuid" }, { name: "email", type: "text" }, { name: "title", type: "text" }] },
+];
+
+const STARTING_QUERY = `-- Pipeline by stage this quarter
+SELECT stage, count(*) AS deals, sum(amount) AS total
+FROM deals
+WHERE closed_at >= date_trunc('quarter', now())
+GROUP BY stage
+ORDER BY total DESC;
+
+-- Try a mistake: run this one (put the cursor on it)
+SELECT name FROM acounts LIMIT 5;`;
+
+const BY_STAGE = [
+  { stage: "won", deals: 14, total: 412800 },
+  { stage: "proposal", deals: 9, total: 268500 },
+  { stage: "qualified", deals: 21, total: 190250 },
+  { stage: "lead", deals: 37, total: 88400 },
+];
+
+const money = (n) => n.toLocaleString("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 });
+const KNOWN = new Set(CRM_TABLES.map((t) => t.name));
+
+function SqlDemo() {
+  const [sql, setSql] = useState(STARTING_QUERY);
+  const [problems, setProblems] = useState([]);
+  const [result, setResult] = useState(null);
+  const [running, setRunning] = useState(false);
+
+  async function run({ statement, from }) {
+    setRunning(true);
+    await new Promise((r) => setTimeout(r, 380));
+    setRunning(false);
+    // What a database would say about a table it does not have.
+    const m = /\bfrom\s+([a-z_]+)/i.exec(statement);
+    if (m && !KNOWN.has(m[1].toLowerCase())) {
+      const position = m.index + m[0].length - m[1].length + 1;
+      const error = `relation "${m[1]}" does not exist`;
+      setProblems([{ position: from + position, message: `${error}. Did you mean "accounts"?` }]);
+      setResult({ ok: false, error });
+      return;
+    }
+    setProblems([]);
+    setResult({ ok: true, rows: BY_STAGE, ms: 38 });
+  }
+
+  return (
+    <div className="grid gap-3">
+      <CodeEditor
+        language="sql"
+        schema={CRM_TABLES}
+        value={sql}
+        onChange={setSql}
+        onRun={run}
+        runLabel={running ? "Running…" : "Run"}
+        diagnostics={problems}
+        placeholder="Write a query — try SELECT * FROM deals"
+        label="Query"
+      />
+      {result?.ok === false ? (
+        <Notice tone="danger" title="The query did not run">
+          {result.error}. The line is marked in the editor.
+        </Notice>
+      ) : result?.ok ? (
+        <div className="overflow-x-auto rounded-lg border border-border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>stage</TableHead>
+                <TableHead className="text-right">deals</TableHead>
+                <TableHead className="text-right">total</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {result.rows.map((r) => (
+                <TableRow key={r.stage}>
+                  <TableCell>{r.stage}</TableCell>
+                  <TableCell className="text-right tabular-nums">{r.deals}</TableCell>
+                  <TableCell className="text-right tabular-nums">{money(r.total)}</TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+          <p className="border-t border-border px-3 py-2 text-xs text-muted-foreground">
+            {result.rows.length} rows in {result.ms} ms
+          </p>
+        </div>
+      ) : (
+        <p className="text-sm text-muted-foreground">Put the cursor in a statement and press Run. Type <code className="font-mono">deals.</code> to see its columns.</p>
+      )}
+    </div>
+  );
+}
+
+const WEBHOOK_BODY = `{
+  "event": "deal.won",
+  "occurred_at": "2026-09-18T14:02:11Z",
+  "deal": {
+    "id": "d_8f21c0",
+    "name": "Northwind — annual plan",
+    "amount": 48000,
+    "currency": "USD",
+    "owner": { "name": "Priya Raman", "email": "priya@acme-sales.co" },
+    "tags": ["expansion", "q3"]
+  },
+  "retry": false
+}`;
+
+function JsonDemo() {
+  const [text, setText] = useState(WEBHOOK_BODY);
+  const ed = useCodeEditor();
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <p className="me-auto text-sm text-muted-foreground">Delete a comma to see the check. Format lays it out again.</p>
+        <Button size="sm" icon="wand" onClick={() => ed.current?.format()}>
+          Format
+        </Button>
+        <Button size="sm" variant="quiet" icon="refresh" onClick={() => setText(WEBHOOK_BODY)}>
+          Reset
+        </Button>
+      </div>
+      <CodeEditor language="json" value={text} onChange={setText} editorRef={ed} label="Webhook body" />
+    </div>
+  );
+}
+
+function EmptyDemo() {
+  const [text, setText] = useState("");
+  const [readOnly, setReadOnly] = useState(false);
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-center gap-x-4">
+        <Switch id="ce-readonly" label="Read-only" checked={readOnly} onChange={(e) => setReadOnly(e.target.checked)} />
+        {text ? <Badge variant="soft">{text.split("\n").length} lines</Badge> : null}
+      </div>
+      <CodeEditor value={text} onChange={setText} readOnly={readOnly} placeholder="Paste a script or write a note in plain text…" minHeight={160} label="Notes" />
+    </div>
+  );
+}
+
+export default function CodeEditorDemo() {
+  const [tab, setTab] = useState("sql");
+  return (
+    <div className="mx-auto w-full max-w-3xl">
+      <Tabs
+        aria-label="Examples"
+        tabs={[
+          { key: "sql", label: "SQL" },
+          { key: "json", label: "JSON" },
+          { key: "empty", label: "Empty" },
+        ]}
+        value={tab}
+        onChange={setTab}
+      />
+      <TabPanel tab="sql" value={tab}>
+        <SqlDemo />
+      </TabPanel>
+      <TabPanel tab="json" value={tab}>
+        <JsonDemo />
+      </TabPanel>
+      <TabPanel tab="empty" value={tab}>
+        <EmptyDemo />
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/code-editor/index.js

@@ -0,0 +1,8 @@
+// The CodeEditor block — `makersclaw add code-editor`. Fixed: compose it
+// through its props (README.md beside this file). The helpers read SQL and
+// JSON anywhere, the server included; the blocks built on this one
+// (json-editor, sql-console…) import it, never @codemirror/* directly.
+export { CodeEditor, useCodeEditor, LANGUAGES, SQL_DIALECTS } from "./code-editor";
+export { splitStatements, statementAt, sqlNamespace } from "./sql";
+export { checkJson, formatJson, stringifyJson } from "./json";
+export { lineCol, offsetOf, normalizeDiagnostics } from "./text";

package/registry/blocks/code-editor/json.js

@@ -0,0 +1,317 @@
+// JSON helpers: a checker that says what is wrong in words people use, and
+// a formatter that keeps the text's own keys, order and numbers.
+//
+// Why our own parser: JSON.parse's messages differ by browser ("Unexpected
+// token } in JSON at position 41" in one, no position at all in another)
+// and never say how to fix the mistake. This one walks the text the same
+// everywhere and names the usual slips — a missing or trailing comma, a
+// key without quotes, single quotes, a comment. Plain functions: node and
+// the server run them too.
+import { lineCol } from "./text";
+
+class JsonSlip extends Error {
+  constructor(message, from, to) {
+    super(message);
+    this.from = from;
+    this.to = to;
+  }
+}
+
+const WS = new Set([" ", "\t", "\n", "\r"]);
+const WORD = /[A-Za-z_$][\w$]*/y;
+const NUMBER = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+const LOOSE_NUMBER = /[-+]?(?:\d[\d_]*)?\.?\d*(?:[eE][+-]?\d+)?/y;
+
+/**
+ * Check a JSON text. { ok: true, value } or { ok: false, error: { message,
+ * from, to, line, col } } — offsets into the text, line and col 1-based.
+ * An empty text is an error ("Nothing here yet…") unless `allowEmpty`.
+ */
+export function checkJson(text, { allowEmpty = false } = {}) {
+  const s = String(text ?? "");
+  let i = 0;
+  const opens = [];
+
+  const slip = (message, from = i, to = from + 1) => {
+    throw new JsonSlip(message, Math.min(from, s.length), Math.min(Math.max(to, from), s.length));
+  };
+  const skip = () => {
+    for (;;) {
+      while (i < s.length && WS.has(s[i])) i++;
+      if (s[i] === "/" && (s[i + 1] === "/" || s[i + 1] === "*")) {
+        const end = s[i + 1] === "/" ? s.indexOf("\n", i) : s.indexOf("*/", i + 2) + 2;
+        slip("JSON has no comments — remove this one", i, end > i ? end : s.length);
+      }
+      return;
+    }
+  };
+  const openedAt = (o) => `the ${o.ch === "{" ? "object" : "list"} opened on line ${lineCol(s, o.at).line}`;
+
+  function string() {
+    const start = i;
+    i++;
+    let out = "";
+    while (i < s.length) {
+      const c = s[i];
+      if (c === '"') {
+        i++;
+        return out;
+      }
+      if (c === "\n") slip("This text is missing its closing quote", start, i);
+      if (c < " ") slip("Tabs and line breaks inside text must be written \\t and \\n", i, i + 1);
+      if (c === "\\") {
+        const e = s[i + 1];
+        const map = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+        if (e in map) {
+          out += map[e];
+          i += 2;
+          continue;
+        }
+        if (e === "u" && /^[0-9a-fA-F]{4}$/.test(s.slice(i + 2, i + 6))) {
+          out += String.fromCharCode(parseInt(s.slice(i + 2, i + 6), 16));
+          i += 6;
+          continue;
+        }
+        slip(`"\\${e ?? ""}" is not an escape JSON knows — write \\\\ for a backslash`, i, i + 2);
+      }
+      out += c;
+      i++;
+    }
+    slip("This text is missing its closing quote", start, s.length);
+  }
+
+  function value() {
+    skip();
+    if (i >= s.length) {
+      const o = opens[opens.length - 1];
+      slip(o ? `The JSON ends too soon — close ${openedAt(o)}` : "Nothing here yet — start with { } or [ ]", s.length, s.length);
+    }
+    const c = s[i];
+    if (c === "{") return object();
+    if (c === "[") return array();
+    if (c === '"') return string();
+    if (c === "'") slip("Use double quotes (\") for text, not single quotes", i, closingSingle(i));
+    NUMBER.lastIndex = i;
+    const num = NUMBER.exec(s);
+    if (num && num[0] && num[0] !== "-") {
+      const after = s[i + num[0].length];
+      if (!after || !/[\w.]/.test(after)) {
+        i += num[0].length;
+        return Number(num[0]);
+      }
+    }
+    if (/[-+.\d]/.test(c)) {
+      LOOSE_NUMBER.lastIndex = i;
+      const loose = LOOSE_NUMBER.exec(s)?.[0] || c;
+      slip(`"${loose}" is not a number JSON can read — no leading zeros, + signs or trailing dots`, i, i + loose.length);
+    }
+    WORD.lastIndex = i;
+    const w = WORD.exec(s)?.[0];
+    if (w === "true" || w === "false" || w === "null") {
+      i += w.length;
+      return w === "true" ? true : w === "false" ? false : null;
+    }
+    if (w) {
+      const lower = w.toLowerCase();
+      if (lower === "true" || lower === "false" || lower === "null") slip(`Write ${lower} in lower case`, i, i + w.length);
+      if (w === "undefined" || w === "NaN" || w === "Infinity") slip(`${w} is not JSON — use null`, i, i + w.length);
+      slip(`Text must be in double quotes: "${w}"`, i, i + w.length);
+    }
+    if (c === "}" || c === "]") slip(`A value is missing before this ${c}`, i);
+    if (c === ",") slip("A value is missing before this comma", i);
+    slip(`"${c}" cannot start a value`, i);
+  }
+
+  function closingSingle(from) {
+    const end = s.indexOf("'", from + 1);
+    const nl = s.indexOf("\n", from + 1);
+    return end > 0 && (nl < 0 || end < nl) ? end + 1 : from + 1;
+  }
+
+  function object() {
+    opens.push({ ch: "{", at: i });
+    i++;
+    const out = {};
+    skip();
+    if (s[i] === "}") {
+      i++;
+      opens.pop();
+      return out;
+    }
+    for (;;) {
+      skip();
+      if (i >= s.length) slip(`The JSON ends too soon — close ${openedAt(opens[opens.length - 1])} with }`, s.length, s.length);
+      const c = s[i];
+      if (c === "}") slip("Remove this trailing comma", lastComma(i), lastComma(i) + 1);
+      if (c === "'") slip("Keys need double quotes, not single quotes", i, closingSingle(i));
+      if (c !== '"') {
+        WORD.lastIndex = i;
+        const w = WORD.exec(s)?.[0];
+        if (w) slip(`Keys need double quotes: "${w}"`, i, i + w.length);
+        slip("A key in double quotes goes here", i);
+      }
+      const key = string();
+      skip();
+      if (s[i] !== ":") slip(i >= s.length ? "The JSON ends too soon — a : and a value go here" : `A colon (:) goes between "${key}" and its value`, i, i + 1);
+      i++;
+      out[key] = value(); // a duplicate key: the last one wins, as in JSON.parse
+      skip();
+      if (s[i] === ",") {
+        i++;
+        continue;
+      }
+      if (s[i] === "}") {
+        i++;
+        opens.pop();
+        return out;
+      }
+      if (i >= s.length) slip(`The JSON ends too soon — close ${openedAt(opens[opens.length - 1])} with }`, s.length, s.length);
+      if (s[i] === "]") slip(`This ] closes a list, but ${openedAt(opens[opens.length - 1])} needs a }`, i);
+      slip("A comma is missing before this", i, tokenEnd(i));
+    }
+  }
+
+  function array() {
+    opens.push({ ch: "[", at: i });
+    i++;
+    const out = [];
+    skip();
+    if (s[i] === "]") {
+      i++;
+      opens.pop();
+      return out;
+    }
+    for (;;) {
+      skip();
+      if (s[i] === "]" && out.length) slip("Remove this trailing comma", lastComma(i), lastComma(i) + 1);
+      out.push(value());
+      skip();
+      if (s[i] === ",") {
+        i++;
+        continue;
+      }
+      if (s[i] === "]") {
+        i++;
+        opens.pop();
+        return out;
+      }
+      if (i >= s.length) slip(`The JSON ends too soon — close ${openedAt(opens[opens.length - 1])} with ]`, s.length, s.length);
+      if (s[i] === "}") slip(`This } closes an object, but ${openedAt(opens[opens.length - 1])} needs a ]`, i);
+      slip("A comma is missing before this", i, tokenEnd(i));
+    }
+  }
+
+  const lastComma = (before) => {
+    let k = before - 1;
+    while (k > 0 && s[k] !== ",") k--;
+    return k;
+  };
+  const tokenEnd = (from) => {
+    if (s[from] === '"') {
+      const e = s.indexOf('"', from + 1);
+      return e > 0 ? e + 1 : from + 1;
+    }
+    let k = from;
+    while (k < s.length && !WS.has(s[k]) && !",:{}[]".includes(s[k])) k++;
+    return Math.max(k, from + 1);
+  };
+
+  try {
+    skip();
+    if (i >= s.length) {
+      if (allowEmpty) return { ok: true, value: undefined, empty: true };
+      slip("Nothing here yet — start with { } or [ ]", 0, 0);
+    }
+    const v = value();
+    skip();
+    if (i < s.length) slip(opens.length ? "Unexpected text" : "There is more after the end of the JSON — remove it, or wrap both in [ ]", i, s.length);
+    return { ok: true, value: v };
+  } catch (e) {
+    if (!(e instanceof JsonSlip)) throw e;
+    const { line, col } = lineCol(s, e.from);
+    return { ok: false, error: { message: e.message, from: e.from, to: e.to, line, col } };
+  }
+}
+
+/**
+ * Lay a JSON text out again, keeping its keys, their order and its numbers
+ * exactly as written (JSON.stringify would reorder number-like keys and
+ * round big numbers). `indent` 2 (default), a number of spaces or "\t";
+ * `indent: 0` minifies. Short arrays of plain values stay on one line when
+ * they fit in `width` (80). Returns null when the text is not valid JSON.
+ */
+export function formatJson(text, { indent = 2, width = 80 } = {}) {
+  const s = String(text ?? "");
+  if (!checkJson(s).ok) return null;
+  const tokens = tokenize(s);
+  const pad = typeof indent === "string" ? indent : " ".repeat(Math.max(0, indent | 0));
+  if (!pad) return tokens.map((t) => t.v).join("");
+  let k = 0;
+  function node(depth) {
+    const t = tokens[k++];
+    if (t.v !== "{" && t.v !== "[") return t.v;
+    const close = t.v === "{" ? "}" : "]";
+    if (tokens[k].v === close) {
+      k++;
+      return t.v + close;
+    }
+    const items = [];
+    const plain = [];
+    for (;;) {
+      let key = "";
+      if (t.v === "{") {
+        key = tokens[k].v + ": ";
+        k += 2;
+      }
+      const start = k;
+      const v = node(depth + 1);
+      plain.push(tokens[start].v !== "{" && tokens[start].v !== "[");
+      items.push(key + v);
+      const sep = tokens[k++].v;
+      if (sep === close) break;
+    }
+    const inner = pad.repeat(depth + 1);
+    if (t.v === "[" && plain.every(Boolean)) {
+      const one = "[" + items.join(", ") + "]";
+      if (one.length + inner.length <= width) return one;
+    }
+    return t.v + "\n" + items.map((x) => inner + x).join(",\n") + "\n" + pad.repeat(depth) + close;
+  }
+  return node(0);
+}
+
+/** A valid JSON text → its tokens: punctuation, strings, numbers, words. */
+function tokenize(s) {
+  const out = [];
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    if (WS.has(c)) {
+      i++;
+      continue;
+    }
+    if ("{}[],:".includes(c)) {
+      out.push({ v: c });
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      let j = i + 1;
+      while (s[j] !== '"') j += s[j] === "\\" ? 2 : 1;
+      out.push({ v: s.slice(i, j + 1) });
+      i = j + 1;
+      continue;
+    }
+    let j = i;
+    while (j < s.length && !WS.has(s[j]) && !"{}[],:".includes(s[j])) j++;
+    out.push({ v: s.slice(i, j) });
+    i = j;
+  }
+  return out;
+}
+
+/** A JS value → a JSON text, 2-space indented (the tree view's output). */
+export function stringifyJson(value, indent = 2) {
+  if (value === undefined) return "";
+  return formatJson(JSON.stringify(value), { indent }) ?? JSON.stringify(value, null, indent);
+}

package/registry/blocks/code-editor/sql.js

@@ -0,0 +1,136 @@
+// SQL helpers: statements, and the schema autocomplete reads.
+//
+// Plain functions of strings and objects, so they run in node and on the
+// server (sql-console runs `splitStatements` before it calls the database).
+
+/**
+ * The statements in a script, in order: [{ from, to, text }]. `from`/`to`
+ * are offsets into `sql` (the statement's own text, trimmed, without its
+ * `;`). A `;` inside a string ('it''s'), a quoted name ("a;b", `a;b`), a
+ * comment (-- …, /* … *\/) or a Postgres dollar-quoted body ($$ … $$,
+ * $fn$ … $fn$) does not end a statement. A stretch holding only comments
+ * or whitespace is not a statement. `opts.backslash: true` also reads \'
+ * as an escaped quote inside '…' (MySQL); Postgres and SQLite do not.
+ */
+export function splitStatements(sql, opts = {}) {
+  const s = String(sql ?? "");
+  const out = [];
+  let start = 0;
+  let i = 0;
+  let meaningful = false;
+  const push = (end) => {
+    if (meaningful) {
+      let a = start;
+      let b = end;
+      while (a < b && /\s/.test(s[a])) a++;
+      while (b > a && /\s/.test(s[b - 1])) b--;
+      out.push({ from: a, to: b, text: s.slice(a, b) });
+    }
+    meaningful = false;
+  };
+  while (i < s.length) {
+    const c = s[i];
+    const n = s[i + 1];
+    if (c === "-" && n === "-") {
+      const e = s.indexOf("\n", i);
+      i = e < 0 ? s.length : e + 1;
+      continue;
+    }
+    if (c === "/" && n === "*") {
+      const e = s.indexOf("*/", i + 2);
+      i = e < 0 ? s.length : e + 2;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") {
+      meaningful = true;
+      i++;
+      while (i < s.length) {
+        if (s[i] === c) {
+          if (s[i + 1] === c) i += 2; // '' or "" is an escaped quote
+          else break;
+        } else if (s[i] === "\\" && c === "'" && opts.backslash) i += 2;
+        else i++;
+      }
+      i++;
+      continue;
+    }
+    if (c === "$") {
+      const m = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(s.slice(i, i + 64));
+      if (m) {
+        meaningful = true;
+        const tag = m[0];
+        const e = s.indexOf(tag, i + tag.length);
+        i = e < 0 ? s.length : e + tag.length;
+        continue;
+      }
+    }
+    if (c === ";") {
+      push(i);
+      i++;
+      start = i;
+      continue;
+    }
+    if (!/\s/.test(c)) meaningful = true;
+    i++;
+  }
+  push(s.length);
+  return out;
+}
+
+/**
+ * The statement to run for a cursor at `pos`: the one the cursor is in,
+ * or — when it sits between statements — the one it follows on the same
+ * line (just after a `;`), else the next one, else the last. Null when the
+ * script has no statement. `opts.backslash`: as splitStatements.
+ */
+export function statementAt(sql, pos, opts = {}) {
+  const s = String(sql ?? "");
+  const all = splitStatements(s, opts);
+  if (!all.length) return null;
+  const at = Math.max(0, Math.min(s.length, pos | 0));
+  for (const st of all) if (at >= st.from && at <= st.to) return st;
+  // Between statements: the previous one if nothing but `;`/spaces/comment
+  // on the same line separates them.
+  let prev = null;
+  for (const st of all) if (st.to <= at) prev = st;
+  if (prev && !s.slice(prev.to, at).includes("\n")) return prev;
+  return all.find((st) => st.from >= at) ?? prev ?? all[all.length - 1];
+}
+
+/**
+ * The tables autocomplete offers, as the editor's SQL mode wants them.
+ *
+ *   tables  [{ name, schema?, description?, columns: [
+ *             { name, type?, description?, primaryKey? } | "name" ] }]
+ *
+ * Returns { namespace, tables } for @codemirror/lang-sql's `schema`: a
+ * table completes as a table (its description beside it), its columns
+ * complete after `table.` and anywhere in a query that names it, each
+ * with its type. Tables in a `schema` nest under it (`public.deals`).
+ */
+export function sqlNamespace(tables) {
+  const namespace = {};
+  const list = [];
+  for (const t of tables ?? []) {
+    if (!t || !t.name) continue;
+    const columns = (t.columns ?? [])
+      .map((c) => (typeof c === "string" ? { name: c } : c))
+      .filter((c) => c && c.name)
+      .map((c) => ({
+        label: String(c.name),
+        type: "property",
+        detail: [c.type, c.primaryKey ? "key" : null].filter(Boolean).join(" · ") || undefined,
+        info: c.description || undefined,
+        boost: c.primaryKey ? 1 : 0,
+      }));
+    const node = { self: { label: String(t.name), type: "type", detail: `${columns.length} column${columns.length === 1 ? "" : "s"}`, info: t.description || undefined }, children: columns };
+    if (t.schema) {
+      const holder = (namespace[t.schema] ??= { self: { label: String(t.schema), type: "namespace" }, children: {} });
+      holder.children[t.name] = node;
+    } else {
+      namespace[t.name] = node;
+    }
+    list.push({ name: String(t.name), schema: t.schema ?? null, columns: columns.map((c) => c.label) });
+  }
+  return { namespace, tables: list };
+}