makersclaw 0.6.0 → 0.7.0

package/templates/next/files/components/ui/item.jsx

@@ -17,7 +17,7 @@ import { Icon } from "./icon";
 //   meta        a count, a date, a Badge — muted, on the right
 //   actions     buttons on the far right (IconButton, Menu); they sit above
 //               the row's target, so they click on their own
-//   href        a next/link row · `onClick` a button row · neither: static
+//   href        a next/link row · `onClick` a button row · neither: a plain row
 //   size        default (56px) · sm (44px, for dense lists and rails) ·
 //               lg (64px, roomier: a pipeline's runs, a list read at leisure)
 //   variant     plain (no fill) · outline (a bordered card) · muted (a filled panel)
@@ -58,7 +58,7 @@ const STACKED = {
 
 const TARGET = "outline-none after:absolute after:inset-0";
 
-// The row filled while its target (or a static row itself) is current.
+// The row filled while its target (or a plain row itself) is current.
 const CURRENT =
   "has-[[data-item-target][aria-current]:not([aria-current=false])]:bg-accent " +
   "[&[aria-current]:not([aria-current=false])]:bg-accent";

package/templates/next/files/components/ui/notice.jsx

@@ -2,7 +2,7 @@ import { cx } from "./cx";
 import { IconButton } from "./button";
 import { Icon } from "./icon";
 
-// Static parts: a card, a notice, a badge, a kicker, the empty state.
+// Plain parts: a card, a notice, a badge, a kicker, the empty state.
 // Server-safe (no hooks), so a server surface can use them directly.
 
 const TONES = {

package/templates/next/files/components/ui/separator.jsx

@@ -1,6 +1,6 @@
 import { cx } from "./cx";
 
-// Small static parts that shape a layout: a separator, a key cap, a box
+// Small plain parts that shape a layout: a separator, a key cap, a box
 // that keeps its ratio. Server-safe (no hooks).
 
 /**

package/templates/next/files/lib/actions.js

@@ -2,13 +2,22 @@
 
 import { headers } from "next/headers";
 import { revalidatePath } from "next/cache";
-import { ident, logActivity, query } from "./db";
+import { ident, logActivity, query, requestMember, transaction } from "./db";
 
 // Every write the app makes. Callable from server and client components
 // alike (they are server actions). Each one goes through lib/db.js,
 // records an activity row, and re-renders the app. Table and column names
 // are quoted through ident(), which refuses anything that is not a plain
-// identifier. Returns { ok } or { ok: false, error }; never throws.
+// identifier. Returns { ok } or { ok: false, error, code }; never throws.
+// `code` is the one the platform's data door answers a browser app with
+// (lib/door.js), so a surface branches on it the same way in both modes.
+//
+// Each write runs in its own transaction that first tells the database
+// who is asking (transaction() in lib/db.js: claw.member_id and
+// claw.member_email, local to it), so a trigger or an action function
+// reads the member here as it does in a browser app, behind the platform's
+// door. The activity line is written after the COMMIT, never inside it:
+// a line that fails must not undo the write it describes.
 //
 // `surface` is optional: proxy.js stamps the current surface key on
 // the request, so a surface rarely needs to pass it.
@@ -20,13 +29,12 @@ import { ident, logActivity, query } from "./db";
 // words. Pass a detail when the surface can say what changed in plain
 // words; leave it out and the tab shows the action word alone.
 
+/** The line's `by`, as the door writes it: the member's email, else
+ *  their id, else unknown (a local run). */
 async function actor() {
-  try {
-    const email = (await headers()).get("x-claw-user-email");
-    return email ? `user:${email}` : "user:unknown";
-  } catch {
-    return "user:unknown";
-  }
+  const { id, email } = await requestMember();
+  if (email) return `user:${email}`;
+  return id ? `user:${id}` : "user:unknown";
 }
 
 async function surfaceOf(explicit) {
@@ -97,36 +105,88 @@ async function setClause(source, cols) {
   return cols.map((c, i) => `${ident(c)} = $${i + 2}`).join(", ") + (await stampFor(source, cols));
 }
 
-function fail(error) {
+// Postgres's raise_exception: what a plpgsql `raise exception` says.
+const REFUSED = "P0001";
+
+// The data door's codes for Postgres's errors (claw's STATIC-SPEC §1,
+// "Errors reach the Builder"). Up to 0.6.x a failure here had no code, so
+// a surface that branched on the door's `code` in a browser app fell
+// through to its generic path after `makersclaw mode server`.
+const CODES = new Map([
+  [REFUSED, "action_refused"],
+  ["23505", "conflict"], // unique
+  ["23503", "conflict"], // foreign key
+  ["23502", "bad_request"], // not null
+  ["22P02", "bad_request"], // not a value of the column's type
+  ["22007", "bad_request"], // not a date or time
+  ["22008", "bad_request"], // a date or time out of range
+  ["57014", "too_slow"],
+  ["40001", "try_again"], // serialization
+  ["40P01", "try_again"], // deadlock
+  ["55P03", "try_again"], // lock not available
+]);
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+
+/** A failure's code, as the door gives it. `missing` names the one error
+ *  that means the statement's own table or function is not there: 42P01
+ *  no_such_table for a table's write, 42883 no_such_action for an
+ *  action. Postgres raises it with no `where` (the context an error from
+ *  inside a function or a trigger carries); from inside, it is the
+ *  code's fault, bad_request, as the rest of class 42. ident()'s refusal
+ *  is bad_request; a connection that failed is failed. */
+function codeOf(error, missing) {
+  const state = typeof error?.code === "string" && SQLSTATE.test(error.code) ? error.code : "";
+  if (!state) return /^invalid identifier: /.test(error?.message ?? "") ? "bad_request" : "failed";
+  if (missing?.[state] && !error.where) return missing[state];
+  if (CODES.has(state)) return CODES.get(state);
+  return state.startsWith("42") ? "bad_request" : "failed";
+}
+
+function fail(error, missing) {
   const message = error?.message ?? String(error);
-  console.error(`[actions] write failed: ${message}`);
-  return { ok: false, error: message };
+  const code = codeOf(error, missing);
+  // A trigger's own raise exception is a deliberate no, as an action's is
+  // (runAction): a warning, or the log tail sends the platform agent after it.
+  if (code === "action_refused") console.warn(`[actions] refused: ${message}`);
+  else console.error(`[actions] write failed: ${message}`);
+  return { ok: false, error: message, code };
 }
 
+/** A write refused here, with the door's code for it. */
+const refused = (error, code) => ({ ok: false, error, code });
+
+/** What the door reads a table's write failing with, when the table is not there. */
+const NO_TABLE = { "42P01": "no_such_table" };
+
 /** Change columns of one row. `patch` is { column: value }; updated_at
- *  becomes now() when the table has one (above). */
-export async function updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data }) {
+ *  becomes now() when the table has one (above). `log: false` writes no
+ *  activity line: for a save that is typing, not a decision (an autosave
+ *  every few keystrokes would flood the Activity tab). */
+export async function updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data, log }) {
   try {
+    const table = ident(source);
+    const key = ident(idColumn);
     const cols = Object.keys(patch ?? {}).filter((c) => patch[c] !== undefined);
-    if (!cols.length) return { ok: false, error: "nothing to change" };
+    if (!cols.length) return refused("nothing to change", "bad_request");
     const sets = await setClause(source, cols);
-    const { rowCount } = await query(
-      `UPDATE ${ident(source)} SET ${sets} WHERE ${ident(idColumn)} = $1`,
-      [id, ...cols.map((c) => patch[c])],
+    const { rowCount } = await transaction((q) =>
+      q(`UPDATE ${table} SET ${sets} WHERE ${key} = $1`, [id, ...cols.map((c) => patch[c])]),
     );
-    if (!rowCount) return { ok: false, error: "row not found" };
-    await logActivity({
-      action,
-      surface: await surfaceOf(surface),
-      row_ref: id,
-      detail: detail ?? `${cols.join(", ")} changed`,
-      data: data ?? patch,
-      by: await actor(),
-    });
+    if (!rowCount) return refused("row not found", "not_found");
+    if (log !== false) {
+      await logActivity({
+        action,
+        surface: await surfaceOf(surface),
+        row_ref: id,
+        detail: detail ?? `${cols.join(", ")} changed`,
+        data: data ?? patch,
+        by: await actor(),
+      });
+    }
     done();
     return { ok: true };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
   }
 }
 
@@ -148,12 +208,10 @@ export async function moveRow({ source, idColumn = "id", id, stateColumn, to, su
 export async function insertRow({ source, idColumn = "id", values, surface, action = "added", detail }) {
   try {
     const cols = Object.keys(values ?? {}).filter((c) => values[c] !== undefined);
-    if (!cols.length) return { ok: false, error: "nothing to add" };
+    if (!cols.length) return refused("nothing to add", "bad_request");
     const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
-    const { rows } = await query(
-      `INSERT INTO ${ident(source)} (${cols.map(ident).join(", ")}) VALUES (${placeholders}) RETURNING ${ident(idColumn)}`,
-      cols.map((c) => values[c]),
-    );
+    const text = `INSERT INTO ${ident(source)} (${cols.map(ident).join(", ")}) VALUES (${placeholders}) RETURNING ${ident(idColumn)}`;
+    const { rows } = await transaction((q) => q(text, cols.map((c) => values[c])));
     const id = rows[0]?.[idColumn];
     await logActivity({
       action,
@@ -166,14 +224,15 @@ export async function insertRow({ source, idColumn = "id", values, surface, acti
     done();
     return { ok: true, id };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
   }
 }
 
 export async function deleteRow({ source, idColumn = "id", id, surface, detail }) {
   try {
-    const { rowCount } = await query(`DELETE FROM ${ident(source)} WHERE ${ident(idColumn)} = $1`, [id]);
-    if (!rowCount) return { ok: false, error: "row not found" };
+    const text = `DELETE FROM ${ident(source)} WHERE ${ident(idColumn)} = $1`;
+    const { rowCount } = await transaction((q) => q(text, [id]));
+    if (!rowCount) return refused("row not found", "not_found");
     await logActivity({
       action: "removed",
       surface: await surfaceOf(surface),
@@ -184,7 +243,7 @@ export async function deleteRow({ source, idColumn = "id", id, surface, detail }
     done();
     return { ok: true };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
   }
 }
 
@@ -195,7 +254,8 @@ export async function deleteRow({ source, idColumn = "id", id, surface, detail }
  * has a plain `key text` column and Postgres rejects ON CONFLICT without a
  * unique index on it. JSON mode sets the key inside the jsonb `column` of
  * the row `id` in `source`. An update stamps updated_at as updateRow's
- * does; the insert leaves it to the column's default.
+ * does; the insert leaves it to the column's default. The UPDATE and the
+ * INSERT run in one transaction (up to 0.6.x they were two).
  */
 export async function saveSetting({
   mode = "table",
@@ -210,24 +270,21 @@ export async function saveSetting({
   surface,
 }) {
   try {
-    if (!key) return { ok: false, error: "no key" };
+    if (!key) return refused("no key", "bad_request");
     if (mode === "json") {
+      const col = ident(column);
       const stamp = await stampFor(source, [column]);
-      const { rowCount } = await query(
-        `UPDATE ${ident(source)} SET ${ident(column)} = jsonb_set(COALESCE(${ident(column)}, '{}'::jsonb), $2::text[], $3::jsonb, true)${stamp} WHERE ${ident(idColumn)} = $1`,
-        [id, [key], JSON.stringify(value ?? null)],
-      );
-      if (!rowCount) return { ok: false, error: "row not found" };
+      const text = `UPDATE ${ident(source)} SET ${col} = jsonb_set(COALESCE(${col}, '{}'::jsonb), $2::text[], $3::jsonb, true)${stamp} WHERE ${ident(idColumn)} = $1`;
+      const { rowCount } = await transaction((q) => q(text, [id, [key], JSON.stringify(value ?? null)]));
+      if (!rowCount) return refused("row not found", "not_found");
     } else {
       const stored = typeof value === "object" && value !== null ? JSON.stringify(value) : value;
+      const [table, keyCol, valueCol] = [ident(source), ident(keyColumn), ident(valueColumn)];
       const stamp = await stampFor(source, [valueColumn]);
-      const { rowCount } = await query(
-        `UPDATE ${ident(source)} SET ${ident(valueColumn)} = $2${stamp} WHERE ${ident(keyColumn)} = $1`,
-        [key, stored],
-      );
-      if (!rowCount) {
-        await query(`INSERT INTO ${ident(source)} (${ident(keyColumn)}, ${ident(valueColumn)}) VALUES ($1, $2)`, [key, stored]);
-      }
+      await transaction(async (q) => {
+        const { rowCount } = await q(`UPDATE ${table} SET ${valueCol} = $2${stamp} WHERE ${keyCol} = $1`, [key, stored]);
+        if (!rowCount) await q(`INSERT INTO ${table} (${keyCol}, ${valueCol}) VALUES ($1, $2)`, [key, stored]);
+      });
     }
     await logActivity({
       action: "edited",
@@ -240,6 +297,68 @@ export async function saveSetting({
     done();
     return { ok: true };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
+  }
+}
+
+// An action's name as the door takes it: one bare, lower-case name. The
+// door calls only a function of the app's own schema, so a name with a
+// schema (`app_x.fn`) or capitals (`CloseCycle`), which ident() quotes
+// and Postgres would find, worked here and is no_such_action there.
+// Refused here too, so a surface that works in one mode works in the
+// other.
+const ACTION_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
+
+/**
+ * Run an action: a function in the app's own schema, `(args jsonb)
+ * returns jsonb`, for any write of more than one row, or one that decides
+ * something. The screen calls it here; the app's agent runs the same
+ * function with `sql` (`select close_cycle($1::jsonb)`), so the two never
+ * drift. It runs inside transaction(), after the member is set, so it
+ * reads who is asking from `current_setting('claw.member_email', true)`.
+ * It says no with `raise exception '<sentence>'`: the sentence comes back
+ * as `error`, code action_refused, and the log says it was refused, not
+ * that the app failed. A name that is not one bare lower-case name, or no
+ * function of it that takes jsonb, is no_such_action, as at the door.
+ *
+ * The activity line is this call's: `action` defaults to the function's
+ * name, `row_ref` is `rowRef` or the result's `id`. The function never
+ * writes claw_app.activity itself. `log: false` writes no line (an
+ * autosave). `args` defaults to {}.
+ *   → { ok: true, result } | { ok: false, error, code }
+ */
+export async function runAction({ name, args, surface, action, detail, rowRef, log } = {}) {
+  if (typeof name !== "string" || !ACTION_NAME.test(name)) {
+    const error = `no action ${JSON.stringify(name ?? null)}: an action is named in lower case, a-z, 0-9 and _, with no schema (close_cycle)`;
+    console.error(`[actions] ${error}`);
+    return refused(error, "no_such_action");
+  }
+  try {
+    const text = `SELECT ${ident(name)}($1::jsonb) AS result`;
+    const json = JSON.stringify(args === undefined ? {} : args);
+    const { rows } = await transaction((q) => q(text, [json]));
+    const result = rows[0]?.result ?? null;
+    if (log !== false) {
+      const returned = result && typeof result === "object" && !Array.isArray(result) ? result.id : undefined;
+      await logActivity({
+        action: action || name,
+        surface: await surfaceOf(surface),
+        row_ref: rowRef ?? returned ?? null,
+        detail: detail ?? null,
+        by: await actor(),
+      });
+    }
+    done();
+    return { ok: true, result };
+  } catch (error) {
+    // P0001 is the function's own raise exception: a deliberate no ("that
+    // cycle is already closed"), which the member acts on. Logged as an
+    // error, the log tail would send the platform agent chasing it as a
+    // bug, which the door avoids by not recording it either.
+    if (error?.code === REFUSED) {
+      console.warn(`[actions] ${name} refused: ${error.message}`);
+      return refused(error.message, "action_refused");
+    }
+    return fail(error, { "42883": "no_such_action" });
   }
 }

package/templates/next/files/lib/brain-server.js

@@ -0,0 +1,96 @@
+import { headers } from "next/headers";
+import { clawAnswer } from "./claw";
+import { brainRead } from "./brain";
+
+// The company brain's reads, from a SERVER component, in a server app.
+// The same nine reads as lib/brain.js, with the same arguments and
+// results (claw docs/brain/CONTRACTS.md §10); no writes. A write from the
+// server would be app code acting, never the member's press, so writes go
+// from the browser through lib/brain.js even here.
+//
+// The browser's door grant is its cookie, which never reaches this
+// server. Here the grant is the bearer the product proxy stamps on each
+// member's request as `x-claw-door` (5 minutes, bound to this app and
+// that member), read with headers(), and the door is CLAW_DOOR_URL (the
+// app's public origin and path plus /_claw/data). No header (a render
+// outside a member's request, or a machine whose proxy does not stamp it
+// yet) or no CLAW_DOOR_URL: each read answers { ok: false, unavailable:
+// true, code: "no_door" } and asks nothing. Read in the browser then.
+//
+// This file pulls in next/headers, so a "use client" file cannot import
+// it (the build says so), as with lib/data.js.
+
+const NO_DOOR = "no door grant on this request: read the brain in the browser (lib/brain.js)";
+
+/** The bearer the proxy stamped on this request, or null. */
+async function doorGrant() {
+  try {
+    return (await headers()).get("x-claw-door") || null;
+  } catch {
+    return null; // outside a request there are no headers at all
+  }
+}
+
+/** Send one read to the door with the bearer: a claw()-shaped answer. */
+async function viaDoorGrant(path, signal) {
+  const grant = await doorGrant();
+  const door = String(process.env.CLAW_DOOR_URL ?? "").replace(/\/+$/, "");
+  if (!grant || !door) return { ok: false, status: 0, error: NO_DOOR, code: "no_door", unavailable: true };
+  let res;
+  try {
+    res = await fetch(`${door}/${path}`, {
+      cache: "no-store",
+      headers: { accept: "application/json", authorization: `Bearer ${grant}` },
+      signal,
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
+    return { ok: false, status: 0, error: "not reachable", unavailable: true };
+  }
+  return clawAnswer(res);
+}
+
+/** → { ok, brain, kinds, error }, as lib/brain.js kinds(). */
+export function kinds(args) {
+  return brainRead("kinds", args, viaDoorGrant);
+}
+
+/** → { ok, records, next, error }, as lib/brain.js listRecords(). */
+export function listRecords(args) {
+  return brainRead("listRecords", args, viaDoorGrant);
+}
+
+/** → { ok, record, links, error }, as lib/brain.js getRecord(). */
+export function getRecord(args) {
+  return brainRead("getRecord", args, viaDoorGrant);
+}
+
+/** → { ok, count, by, error }, as lib/brain.js countRecords(). */
+export function countRecords(args) {
+  return brainRead("countRecords", args, viaDoorGrant);
+}
+
+/** → { ok, meaning, results, error }, as lib/brain.js searchBrain(). */
+export function searchBrain(args) {
+  return brainRead("searchBrain", args, viaDoorGrant);
+}
+
+/** → { ok, changes, next, error }, as lib/brain.js recordHistory(). */
+export function recordHistory(args) {
+  return brainRead("recordHistory", args, viaDoorGrant);
+}
+
+/** → { ok, changes, next, error }, as lib/brain.js brainChanges(). */
+export function brainChanges(args) {
+  return brainRead("brainChanges", args, viaDoorGrant);
+}
+
+/** → { ok, lists, error }, as lib/brain.js brainLists(). */
+export function brainLists(args) {
+  return brainRead("brainLists", args, viaDoorGrant);
+}
+
+/** → { ok, list, records, next, error }, as lib/brain.js listMembers(). */
+export function listMembers(args) {
+  return brainRead("listMembers", args, viaDoorGrant);
+}