@bakery-framework/plugin-db-explorer 2.0.0-alpha.11

package/src/shell.ts

@@ -0,0 +1,187 @@
+/**
+ * The HTML document the explorer boots into, and all of its CSS.
+ *
+ * Extracted from `setup.ts` when the client became a data editor: the sheet
+ * grew from twenty rules to a hundred and thirty, and a route table with a
+ * stylesheet in the middle of it is a route table nobody reads. `setup.ts`
+ * keeps the routing and the CSRF policy; this keeps the paint.
+ *
+ * There is **no markup generated from data here** — the body is an empty
+ * `#app` and a module script. Every value the user sees is written by
+ * `client/dom.ts` through `textContent`, which is why this plugin has no XSS
+ * surface even though it renders arbitrary row contents.
+ */
+
+const CSS = `
+  :root {
+    color-scheme: dark;
+    --bg: #0f1115; --panel: #151922; --line: #262b36; --line-soft: #1e2430;
+    --text: #e6e8ee; --dim: #9aa3b2; --faint: #5b6472;
+    --accent: #2f6feb; --accent-bg: #16233d; --accent-text: #cfe0ff;
+    --bad: #ff8ba0; --bad-bg: #2b1620; --good: #7ee2a8;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; background: var(--bg); color: var(--text); }
+  #app { display: flex; min-height: 100vh; }
+
+  .side-slot { flex-shrink: 0; }
+  .side { width: 230px; padding: 1rem; border-right: 1px solid var(--line); height: 100vh; overflow-y: auto; display: flex; flex-direction: column; gap: .3rem; }
+  .table-list { flex: 1; min-height: 0; overflow-y: auto; }
+  .system-toggle { border-top: 1px solid var(--line); padding-top: .5rem; cursor: pointer; display: block; }
+  .brand { font-size: 1rem; margin: 0 0 .2rem; }
+  .note { color: var(--dim); font-size: .8rem; }
+  .error, .row-error { color: var(--bad); }
+  .error { padding: 1rem; }
+  .table-btn { display: block; width: 100%; text-align: left; background: none; border: 0; color: #cfd6e4; padding: .35rem .5rem; border-radius: 6px; cursor: pointer; font: inherit; }
+  .table-btn:hover { background: #1a1f2b; }
+  .table-btn.active { background: var(--accent-bg); color: var(--accent-text); }
+  .table-btn .ro { color: var(--faint); float: right; }
+
+  /* The right-hand column: tab strip, the active view, then the status bar. */
+  .column { flex: 1; min-width: 0; display: flex; flex-direction: column; height: 100vh; }
+  .main { flex: 1; padding: 1rem 1.5rem; min-width: 0; overflow-y: auto; }
+
+  /* Table tabs. Italic is the preview state, borrowed from VS Code. */
+  .tabstrip { display: flex; align-items: stretch; gap: 2px; border-bottom: 1px solid var(--line); background: var(--panel); overflow-x: auto; }
+  .tab { display: flex; align-items: center; border-right: 1px solid var(--line); background: transparent; max-width: 16rem; }
+  .tab.active { background: var(--bg); box-shadow: inset 0 2px 0 var(--accent); }
+  .tab-label { font: inherit; font-family: ui-monospace, monospace; font-size: .8rem; background: none; border: 0; color: var(--dim); padding: .45rem .3rem .45rem .8rem; cursor: pointer; max-width: 13rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .tab.active .tab-label { color: var(--text); }
+  .tab.preview .tab-label { font-style: italic; }
+  .tab-close { font: inherit; background: none; border: 0; color: var(--faint); cursor: pointer; padding: .2rem .5rem .2rem .2rem; border-radius: 4px; }
+  .tab-close:hover { color: var(--bad); background: var(--bad-bg); }
+  .tab-new { font: inherit; background: none; border: 0; color: var(--dim); cursor: pointer; padding: .3rem .8rem; }
+  .tab-new:hover { color: var(--accent-text); }
+
+  /* Data / Structure / Relations — one level of nesting, and only one. */
+  .viewtabs { display: flex; gap: .2rem; padding: .3rem .8rem 0; border-bottom: 1px solid var(--line); background: var(--bg); }
+  .viewtab { font: inherit; font-size: .8rem; background: none; border: 0; border-bottom: 2px solid transparent; color: var(--dim); padding: .3rem .7rem; cursor: pointer; }
+  .viewtab:hover { color: var(--text); }
+  .viewtab.active { color: var(--accent-text); border-bottom-color: var(--accent); }
+  .newtab { padding: 2rem; }
+
+  .statusbar { border-top: 1px solid var(--line); background: var(--panel); color: var(--dim); font-size: .75rem; padding: .3rem 1rem; flex-shrink: 0; font-family: ui-monospace, monospace; }
+  .statusbar.dirty { color: var(--bad); }
+
+  /* Structure and Relations. */
+  .structure, .relations { display: flex; flex-direction: column; gap: 1.2rem; }
+  .structure-section h3 { margin: 0 0 .3rem; font-size: .9rem; }
+  .structure-grid td { white-space: normal; }
+  .relation-list { display: flex; flex-direction: column; gap: .3rem; margin-top: .4rem; }
+  .relation { display: flex; gap: .5rem; align-items: center; flex-wrap: wrap; }
+  .relation-cols { font-family: ui-monospace, monospace; font-size: .8rem; color: var(--dim); }
+
+  /* The filter builder: a chip per condition. */
+  .filter-bar { display: flex; gap: .4rem; flex-wrap: wrap; align-items: center; margin-bottom: .6rem; }
+  .filter-chip { display: flex; gap: .2rem; align-items: center; background: var(--panel); border: 1px solid var(--line); border-radius: 999px; padding: .15rem .3rem .15rem .5rem; }
+  .filter-chip .sel { border: 0; background: transparent; font-size: .78rem; }
+  .filter-value { font: inherit; font-size: .78rem; background: var(--bg); color: var(--text); border: 1px solid var(--line); border-radius: 4px; padding: .1rem .35rem; width: 8rem; }
+  .filter-drop { border: 0; background: none; color: var(--faint); padding: 0 .4rem; }
+  .filter-drop:hover { color: var(--bad); }
+  .filter-add { font-size: .78rem; }
+  .filter-clash { color: var(--bad); font-size: .75rem; }
+
+  .table-head { display: flex; align-items: baseline; gap: 1rem; flex-wrap: wrap; }
+  .table-head h2 { margin: .2rem 0 .8rem; font-family: ui-monospace, monospace; font-size: 1rem; }
+  .banner { border: 1px solid var(--line); border-left: 3px solid var(--accent); background: var(--panel); padding: .5rem .8rem; border-radius: 6px; margin: 0 0 .8rem; }
+  .banner.warn { border-left-color: var(--bad); }
+  .crumbs { display: flex; gap: .4rem; align-items: center; flex-wrap: wrap; margin-bottom: .5rem; }
+  .badge { background: var(--accent-bg); color: var(--accent-text); border-radius: 999px; padding: .05rem .5rem; font-size: .75rem; }
+  .badge.dirty { background: var(--bad-bg); color: var(--bad); }
+
+  .toolbar { display: flex; gap: .5rem; align-items: center; flex-wrap: wrap; margin-bottom: .6rem; }
+  .btn { font: inherit; padding: .25rem .7rem; border-radius: 6px; border: 1px solid var(--line); background: var(--panel); color: var(--text); cursor: pointer; }
+  .btn:hover:not(:disabled) { border-color: var(--accent); }
+  .btn:disabled { opacity: .4; cursor: default; }
+  .btn.primary { border-color: var(--accent); background: var(--accent-bg); color: var(--accent-text); }
+  .btn.danger-btn { border-color: var(--bad); color: var(--bad); }
+
+  .scroll { overflow: auto; border: 1px solid var(--line); border-radius: 8px; max-height: 70vh; }
+  .grid { border-collapse: collapse; width: 100%; font-size: .82rem; }
+  .grid th { text-align: left; padding: .45rem .7rem; background: var(--panel); cursor: pointer; white-space: nowrap; position: sticky; top: 0; z-index: 1; }
+  .grid th.pk::after { content: ' PK'; color: var(--faint); font-size: .7rem; }
+  .grid td { padding: .3rem .7rem; border-top: 1px solid var(--line-soft); font-family: ui-monospace, monospace; white-space: nowrap; max-width: 26rem; overflow: hidden; text-overflow: ellipsis; }
+  .grid td.null { color: var(--faint); font-style: italic; }
+  .grid td.num { text-align: right; }
+  .grid td.staged { background: var(--accent-bg); }
+  .grid td.bad { outline: 1px solid var(--bad); background: var(--bad-bg); }
+  .grid td.at { outline: 2px solid var(--accent); outline-offset: -2px; }
+  .grid td.editing { padding: .1rem .2rem; white-space: normal; overflow: visible; }
+  .grid td.pick, .grid th.pick { width: 2rem; text-align: center; }
+  .grid tr.focused { background: #1b2436; }
+  .grid tr[aria-busy='true'] { opacity: .5; }
+  .fk { font: inherit; background: none; border: 0; border-bottom: 1px dotted var(--accent); color: var(--accent-text); cursor: pointer; padding: 0; }
+
+  .row-bar-row { display: none; }
+  .row-bar-row.open { display: table-row; }
+  .row-bar-row td { background: var(--panel); }
+  .row-bar { display: flex; gap: .5rem; align-items: center; flex-wrap: wrap; }
+
+  .editor { display: flex; gap: .25rem; align-items: center; }
+  .editor.invalid .ed { border-color: var(--bad); }
+  .editor.is-null .ed { opacity: .4; }
+  .ed { font: inherit; font-family: ui-monospace, monospace; background: var(--bg); color: var(--text); border: 1px solid var(--accent); border-radius: 4px; padding: .15rem .3rem; min-width: 6rem; }
+  .ed-json { min-width: 22rem; }
+  .ed-long { min-width: 22rem; resize: vertical; }
+  .ed-check { min-width: 0; }
+  .ed-null { font: inherit; width: 1.6rem; border-radius: 4px; border: 1px solid var(--line); background: var(--panel); color: var(--dim); cursor: pointer; }
+  .ed-null[aria-pressed='true'] { border-color: var(--accent); color: var(--accent-text); }
+  .ed-null:disabled { opacity: .3; cursor: not-allowed; }
+  .ed-note { color: var(--bad); font-size: .75rem; }
+
+  .pager { margin-top: .8rem; display: flex; gap: .5rem; align-items: center; }
+  .filters { display: flex; gap: .4rem; flex-wrap: wrap; margin-bottom: .5rem; }
+  .filters input { font: inherit; font-size: .78rem; background: var(--panel); color: var(--text); border: 1px solid var(--line); border-radius: 4px; padding: .1rem .35rem; width: 8rem; }
+
+  dialog { background: var(--panel); color: var(--text); border: 1px solid var(--line); border-radius: 10px; padding: 1rem 1.2rem; max-width: 42rem; }
+  dialog.wide { max-width: 80rem; width: 90vw; }
+  dialog::backdrop { background: #0008; }
+  dialog h3 { margin: 0 0 .5rem; }
+  dialog h4 { margin: .8rem 0 .3rem; font-size: .85rem; color: var(--dim); }
+  .sel { font: inherit; background: var(--bg); color: var(--text); border: 1px solid var(--line); border-radius: 4px; padding: .15rem .3rem; }
+
+  /* The row side panel — where JSON, long text and both graph directions live. */
+  .panel { position: fixed; top: 0; right: 0; width: min(38rem, 100vw); height: 100vh; overflow-y: auto; background: var(--panel); border-left: 1px solid var(--line); padding: 1rem; z-index: 30; }
+  .panel-head { display: flex; justify-content: space-between; align-items: flex-start; gap: 1rem; }
+  .panel-title h3 { margin: 0; font-family: ui-monospace, monospace; }
+  .panel-fields { display: flex; flex-direction: column; gap: .6rem; margin: .8rem 0; }
+  .panel-field { display: flex; flex-direction: column; gap: .15rem; }
+  .panel-label { font-family: ui-monospace, monospace; font-size: .8rem; }
+  .panel-value { font-family: ui-monospace, monospace; color: var(--dim); word-break: break-all; }
+  .panel-refs { margin-top: 1rem; }
+  .panel-ref { display: flex; gap: .5rem; align-items: center; margin: .3rem 0; }
+  .panel-field .editor { width: 100%; }
+  .panel-field .ed { width: 100%; }
+
+  .undo-bar { position: fixed; left: 50%; bottom: 1.2rem; transform: translateX(-50%); display: flex; gap: .8rem; align-items: center; background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: .5rem .9rem; z-index: 40; }
+  .undo-bar.error { border-color: var(--bad); color: var(--bad); }
+
+  .drop { border: 2px dashed var(--line); border-radius: 10px; padding: 2rem; text-align: center; }
+  .drop.over { border-color: var(--accent); background: var(--accent-bg); }
+  .import-stage { display: flex; flex-direction: column; gap: .4rem; max-height: 75vh; overflow-y: auto; }
+  .import-head { display: flex; gap: .6rem; align-items: center; flex-wrap: wrap; }
+  .map-row { display: grid; grid-template-columns: 10rem 14rem 14rem auto auto; gap: .5rem; align-items: center; padding: .15rem 0; }
+  .map-name { font-family: ui-monospace, monospace; overflow: hidden; text-overflow: ellipsis; }
+  .map-samples { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .unmapped-row { display: flex; gap: .5rem; align-items: center; font-family: ui-monospace, monospace; font-size: .8rem; }
+  .tag { border-radius: 4px; padding: 0 .35rem; font-size: .7rem; font-family: ui-sans-serif, system-ui, sans-serif; }
+  .tag.required { background: var(--bad-bg); color: var(--bad); }
+  .tag.default { background: var(--accent-bg); color: var(--accent-text); }
+  .tag.nullable { background: #1a1f2b; color: var(--dim); }
+  .insert-rows { display: flex; flex-direction: column; gap: .8rem; max-height: 50vh; overflow-y: auto; }
+  .insert-row { display: grid; grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr)); gap: .4rem; border-top: 1px solid var(--line-soft); padding-top: .4rem; }
+`
+
+export const SHELL: string = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Database explorer</title>
+<style>${CSS}</style>
+</head>
+<body>
+<div id="app"><p class="note" style="padding:1rem">loading…</p></div>
+<script type="module" src="/_db/app.js"></script>
+</body>
+</html>`

package/src/validate.ts

@@ -0,0 +1,295 @@
+/**
+ * Turning a request body into bound values, or into a list of what is wrong
+ * with it.
+ *
+ * Two rules run through every function here.
+ *
+ * **Errors accumulate.** A 400 names every bad field, not the first one — a
+ * fifty-row paste fixed one error per round trip is fifty round trips, and the
+ * user cannot see the shape of their mistake.
+ *
+ * **Nothing is applied partially.** These functions only ever *describe* a
+ * write; the caller runs the statement, and only when the error list is empty.
+ * That is what makes "413 with nothing executed" and "400 with nothing
+ * executed" true statements rather than intentions.
+ *
+ * And an unknown column is an error, never a silently dropped key. A typo'd
+ * column in an edit that reports success is a row the user believes they
+ * changed and did not.
+ */
+
+import type { ColumnFacts, TableFacts } from './identity'
+import {
+  type ColumnMeta,
+  coerceValue,
+  comparableKind,
+  omittableOnInsert,
+} from './shared/coerce'
+
+export interface FieldError {
+  /** 0-based index into the request's `rows`/`edits`/`keys` array. */
+  row: number
+  column: string
+  code: string
+  message: string
+}
+
+export interface Validated {
+  /** Raw database column name → bound value. */
+  values: Record<string, unknown>
+  errors: FieldError[]
+}
+
+/** A request body member that has to be a plain object before anything else. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+const error = (
+  row: number,
+  column: string,
+  code: string,
+  message: string,
+): FieldError => ({ row, column, code, message })
+
+/**
+ * Resolve a wire column name against the table.
+ *
+ * Accepts the raw database name, and the camel spelling as a courtesy — the
+ * grid renders raw names, but a script written against a typed schema has camel
+ * ones and the two are the same column. Anything else is `unknown_column`.
+ */
+function findColumn(table: TableFacts, name: string): ColumnFacts | undefined {
+  return (
+    table.byName.get(name) ??
+    table.columns.find(column => column.camel === name)
+  )
+}
+
+function coerceInto(
+  values: Record<string, unknown>,
+  errors: FieldError[],
+  row: number,
+  column: ColumnFacts,
+  raw: unknown,
+): void {
+  const result = coerceValue(raw, column.meta)
+  if (result.ok) values[column.name] = result.value
+  else errors.push(error(row, column.name, result.code, result.message))
+}
+
+/**
+ * A whole row, for an INSERT.
+ *
+ * Every column is considered, not only the ones the caller sent: an absent key
+ * is fine when the database can fill it in (auto-increment, a default, or
+ * nullable) and is a `required` error otherwise. Refusing here rather than at
+ * the database is what keeps a 1,000-row insert from failing on row 700 with
+ * 699 rows already written — the whole statement is known to be well-formed
+ * before any of it runs.
+ */
+export function validateInsertRow(
+  input: unknown,
+  table: TableFacts,
+  row: number,
+): Validated {
+  const values: Record<string, unknown> = {}
+  const errors: FieldError[] = []
+
+  if (!isRecord(input)) {
+    return {
+      values,
+      errors: [error(row, '', 'not_a_row', 'expected an object')],
+    }
+  }
+
+  const seen = new Set<string>()
+  for (const [name, raw] of Object.entries(input)) {
+    const column = findColumn(table, name)
+    if (!column) {
+      errors.push(error(row, name, 'unknown_column', `no column named ${name}`))
+      continue
+    }
+    seen.add(column.name)
+    coerceInto(values, errors, row, column, raw)
+  }
+
+  for (const column of table.columns) {
+    if (seen.has(column.name)) continue
+    if (omittableOnInsert(column.meta)) continue
+    errors.push(
+      error(
+        row,
+        column.name,
+        'required',
+        `${column.name} cannot be null and has no default`,
+      ),
+    )
+  }
+
+  return { values, errors }
+}
+
+export interface PartialOptions {
+  /**
+   * Whether a `json` or `buffer` column may appear.
+   *
+   * `false` for `expect`, where the answer is not "be careful" but "this cannot
+   * be expressed": those two kinds have no portable equality predicate — see
+   * `comparableKind` — so an `expect` over one is a condition that never
+   * matches, which reads to the caller as a permanent conflict.
+   */
+  allowUncomparable: boolean
+  /** Which field of the request this is, for the message. */
+  label: string
+}
+
+/**
+ * A partial row — the `set` of an update, or the `expect` it is guarded by.
+ *
+ * Absent keys are absent, and that is the point: this function has no concept
+ * of a default, because "the caller did not mention this column" means "leave
+ * it alone" everywhere it is used.
+ */
+export function validatePartial(
+  input: unknown,
+  table: TableFacts,
+  row: number,
+  options: PartialOptions,
+): Validated {
+  const values: Record<string, unknown> = {}
+  const errors: FieldError[] = []
+
+  if (!isRecord(input)) {
+    return {
+      values,
+      errors: [
+        error(row, '', 'not_an_object', `${options.label} must be an object`),
+      ],
+    }
+  }
+
+  for (const [name, raw] of Object.entries(input)) {
+    const column = findColumn(table, name)
+    if (!column) {
+      errors.push(error(row, name, 'unknown_column', `no column named ${name}`))
+      continue
+    }
+    if (!options.allowUncomparable && !comparableKind(column.meta.kind)) {
+      errors.push(
+        error(
+          row,
+          column.name,
+          'uncomparable',
+          `a ${column.meta.kind} column cannot be compared in ${options.label}; ` +
+            'no dialect agrees on equality for one',
+        ),
+      )
+      continue
+    }
+    coerceInto(values, errors, row, column, raw)
+  }
+
+  return { values, errors }
+}
+
+/**
+ * The columns of `set` that may only be written with `force`.
+ *
+ * A `json` or `buffer` column cannot appear in `expect`, so an edit to one is
+ * unguarded by construction — it overwrites whatever is there, including
+ * whatever somebody else wrote a moment ago. `force` is how the caller says
+ * they know that. It is not a permission; it is an acknowledgement.
+ */
+export function unguardableColumns(
+  values: Record<string, unknown>,
+  table: TableFacts,
+): string[] {
+  return Object.keys(values).filter(name => {
+    const meta: ColumnMeta | undefined = table.byName.get(name)?.meta
+    return meta ? !comparableKind(meta.kind) : false
+  })
+}
+
+export interface ValidatedKey {
+  /** Raw column name → bound value, for the identity predicate. */
+  where: Record<string, unknown>
+  errors: FieldError[]
+}
+
+/**
+ * A wire key, against the table's identity.
+ *
+ * **The column set must be exactly equal** — not a subset, not a superset. A
+ * subset is a predicate that matches more than one row, which for a composite
+ * key is precisely the dashboard's bug (its MySQL path addresses rows by the
+ * *first* primary-key column, so one edit rewrites every row sharing it). A
+ * superset is a caller who believes the key contains something it does not, and
+ * silently ignoring the extra column would confirm that belief.
+ *
+ * The key is transparent by design — `{ col: value }` rather than an opaque
+ * token — so there is no server-side key cache to keep, and nothing that can go
+ * stale between rendering a page and saving a row (convention 6).
+ */
+export function validateKey(
+  input: unknown,
+  table: TableFacts,
+  row: number,
+): ValidatedKey {
+  const where: Record<string, unknown> = {}
+  const errors: FieldError[] = []
+
+  if (!isRecord(input)) {
+    return {
+      where,
+      errors: [error(row, '', 'not_a_key', 'key must be an object')],
+    }
+  }
+
+  const wanted = table.identity.cols
+  const resolved = new Map<string, unknown>()
+  for (const [name, raw] of Object.entries(input)) {
+    const column = findColumn(table, name)
+    if (!column) {
+      errors.push(error(row, name, 'unknown_column', `no column named ${name}`))
+      continue
+    }
+    resolved.set(column.name, raw)
+  }
+
+  const missing = wanted.filter(name => !resolved.has(name))
+  const extra = [...resolved.keys()].filter(name => !wanted.includes(name))
+  if (missing.length || extra.length) {
+    errors.push(
+      error(
+        row,
+        [...missing, ...extra].join(', '),
+        'key_mismatch',
+        `key must name exactly ${wanted.join(', ')}` +
+          (missing.length ? `; missing ${missing.join(', ')}` : '') +
+          (extra.length ? `; unexpected ${extra.join(', ')}` : ''),
+      ),
+    )
+    return { where, errors }
+  }
+
+  for (const name of wanted) {
+    const column = table.byName.get(name)!
+    const raw = resolved.get(name)
+    if (raw === null) {
+      // `col = NULL` is never true. A key column that is null is not a key.
+      errors.push(
+        error(
+          row,
+          name,
+          'null_key',
+          `${name} is part of the key and cannot be null`,
+        ),
+      )
+      continue
+    }
+    coerceInto(where, errors, row, column, raw)
+  }
+
+  return { where, errors }
+}