makersclaw 0.6.0 → 0.8.0

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);
+}

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

@@ -0,0 +1,413 @@
+import { claw } from "./claw";
+import { dataChanged, inTurn, useDoorRead } from "./door";
+import { surfaceOfPath } from "./platform";
+
+// The company brain, through the data door.
+//
+// The brain is the workspace's shared records (contacts, companies,
+// deals, whatever kinds the workspace keeps), each in an area: Everyone,
+// Finance… An app never reaches it with SQL: its database login holds
+// none of it. It reads and writes through _claw/data, which the Makersclaw
+// gateway answers itself under this app's path, before anything reaches
+// the app, so it works while the app's machine sleeps (claw
+// docs/brain/CONTRACTS.md §8 and §10). The door hands the app only the
+// kinds its makersclaw.json declares, and only what the member may read.
+//
+// BROWSER, in both modes: call these from "use client" files, in a server
+// app too. The grant cookie is who is asking, and it makes a write a
+// person's press: confirmed, able to overwrite a confirmed value, erase or
+// merge. A write from the app's server would be app code acting:
+// unconfirmed, skipped over a confirmed value, never an erase. So there is
+// no Server Action for the brain. A server component reads with
+// lib/brain-server.js: the same reads, over the proxy's door grant.
+//
+// Every function resolves to a plain object and never throws, like
+// lib/data.js:
+//   - a read: the door's JSON as it came, plus `error: null`;
+//   - a write: the door's JSON as it came;
+//   - a refusal: { ok: false, error, code }. A read keeps its empty values
+//     (records: [], next: null…), so a surface renders it like no rows;
+//   - a 404 that names no code, or no network: { ok: false, error,
+//     unavailable: true }. A claw with no door yet: show a quiet "not
+//     connected yet", not an error.
+// Arguments are camelCase (ifVersion); the door's keys are not (if_version).
+//
+// The door writes the activity line for every write it takes, so nothing
+// here calls logActivity. Writes go one at a time, in the order called,
+// in the same turn as lib/door.js's; one that answers ok calls
+// dataChanged(), so every hook on the page reads again: these four
+// (useRecords, useRecord, useRecordCounts, useBrainSearch) and the own
+// tables' (lib/door.js). A server app may also router.refresh().
+
+/** A value the door's path needs was not given. */
+class Missing extends Error {}
+
+/** One path segment: an id or a kind, encoded, so "a/b" stays one. */
+function segment(value, what) {
+  if (value === undefined || value === null || value === "") throw new Missing(`needs ${what}`);
+  return encodeURIComponent(String(value));
+}
+
+/** A list of names as the door reads it, "a,b"; a string is taken as it is. */
+function names(value) {
+  if (value === undefined || value === null) return undefined;
+  return Array.isArray(value) ? value.map(String).join(",") : String(value);
+}
+
+/** A filter as the door reads it: JSON in the query. A string is taken
+ *  as JSON already. */
+function filter(where) {
+  if (where === undefined || where === null) return undefined;
+  return typeof where === "string" ? where : JSON.stringify(where);
+}
+
+/** "?a=1&b=2", leaving out what was not given. */
+function query(params) {
+  const q = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === "") continue;
+    q.set(key, String(value));
+  }
+  const text = q.toString();
+  return text ? `?${text}` : "";
+}
+
+/** The argument off, for a flag the door turns off with "0". */
+const off = (flag) => (flag === false ? 0 : undefined);
+
+/**
+ * The door's read routes: each turns its arguments into the path under
+ * _claw/data and names what an empty answer holds. A path of null asks
+ * nothing (a blank search). lib/brain-server.js reads the same paths.
+ */
+export const BRAIN_READS = {
+  kinds: {
+    empty: { kinds: [] },
+    path: () => "kinds",
+  },
+  listRecords: {
+    empty: { records: [], next: null },
+    path: ({ kind, where, order, limit, cursor, fields, prefix, state }) =>
+      `kinds/${segment(kind, "a kind")}/records` +
+      query({ where: filter(where), order, limit, cursor, fields: names(fields), prefix, state: off(state) }),
+  },
+  getRecord: {
+    empty: { record: null, links: null },
+    path: ({ id, links = false, state }) => `records/${segment(id, "an id")}` + query({ links: links ? 1 : undefined, state: off(state) }),
+  },
+  countRecords: {
+    empty: { count: 0, by: null },
+    path: ({ kind, by, where }) => `kinds/${segment(kind, "a kind")}/counts` + query({ by, where: filter(where) }),
+  },
+  searchBrain: {
+    empty: { results: [], meaning: false },
+    path: ({ q, kinds, limit, meaning }) =>
+      String(q ?? "").trim() ? "search" + query({ q, kinds: names(kinds), limit, meaning: off(meaning) }) : null,
+  },
+  recordHistory: {
+    empty: { changes: [], next: null },
+    path: ({ id, limit, cursor }) => `records/${segment(id, "an id")}/history` + query({ limit, cursor }),
+  },
+  brainChanges: {
+    empty: { changes: [], next: null },
+    path: ({ since, kinds }) => "changes" + query({ since, kinds: names(kinds) }),
+  },
+  brainLists: {
+    empty: { lists: [] },
+    path: ({ kind }) => "lists" + query({ kind }),
+  },
+  listMembers: {
+    empty: { list: null, records: [], next: null },
+    path: ({ list, limit, cursor }) => `lists/${segment(list, "a list")}` + query({ limit, cursor }),
+  },
+};
+
+/** What went wrong before anything was sent, said as the door would. */
+function refusedHere(name, error, empty = {}) {
+  const words = error instanceof Missing ? `${name} ${error.message}` : `${name}: ${error?.message ?? error}`;
+  return { ...empty, ok: false, error: words, code: "bad_request" };
+}
+
+/** A claw()-shaped answer → the result: the door's JSON as it came (a
+ *  read's with `error: null` and its empty values under it), or the
+ *  failure in the same keys. */
+function shaped(answer, empty, read) {
+  const data = answer?.data;
+  const json = data && typeof data === "object" && !Array.isArray(data);
+  if (answer?.ok && json && data.ok !== false) return read ? { ...empty, ...data, error: null } : data;
+  const out = { ...empty, ok: false };
+  if (answer?.ok) {
+    // A 2xx that is not the door's success: its refusal, or not its JSON.
+    out.error = json ? String(data.error || "the door refused") : "the door answered something that is not its JSON";
+    if (json && typeof data.code === "string" && data.code) out.code = data.code;
+    return out;
+  }
+  out.error = String(answer?.error || "the door refused");
+  if (answer?.code) out.code = answer.code;
+  if (answer?.unavailable) out.unavailable = true;
+  if (answer?.aborted) out.aborted = true;
+  return out;
+}
+
+/**
+ * Run one of BRAIN_READS: its path from the arguments, `send(path,
+ * signal)` for a claw()-shaped answer, then the result. Never throws.
+ * The browser's reads send through claw(); lib/brain-server.js passes a
+ * `send` of its own.
+ */
+export async function brainRead(name, args, send) {
+  const { empty, path } = BRAIN_READS[name];
+  let sub;
+  try {
+    sub = path(args ?? {});
+  } catch (error) {
+    return refusedHere(name, error, empty);
+  }
+  if (sub === null) return { ok: true, ...empty, error: null };
+  let answer;
+  try {
+    answer = await send(sub, args?.signal);
+  } catch (error) {
+    answer = { ok: false, error: String(error?.message ?? error) };
+  }
+  return shaped(answer, empty, true);
+}
+
+const viaCookie = (path, signal) => claw(`data/${path}`, { signal });
+
+/** The surface the page is on, for the door's activity line. */
+function pageSurface() {
+  return typeof location === "undefined" ? undefined : surfaceOfPath(location.pathname);
+}
+
+/** POST one write route, in its turn (lib/door.js inTurn). `build(args)`
+ *  → { path, body }, or { done } when there is nothing to send. A write
+ *  the door takes calls dataChanged(). Never throws. */
+async function post(name, args, build) {
+  let built;
+  try {
+    built = build(args ?? {});
+    if (built.done) return built.done;
+    // claw() would read a body that cannot be JSON as "not reachable".
+    JSON.stringify(built.body);
+  } catch (error) {
+    return refusedHere(name, error);
+  }
+  return inTurn(async () => {
+    let answer;
+    try {
+      answer = await claw(`data/${built.path}`, { method: "POST", body: built.body });
+    } catch (error) {
+      answer = { ok: false, error: String(error?.message ?? error) };
+    }
+    const out = shaped(answer, {}, false);
+    if (out.ok !== false) dataChanged();
+    return out;
+  });
+}
+
+/** One write as the door reads it. `surface` defaults to the page's
+ *  surface key (the <key> of /s/<key>, as logActivity's lines name it);
+ *  null sends none. */
+function writeBody(write) {
+  const { kind, id, fields, area, from, ifVersion, owner, surface, detail } = write ?? {};
+  return {
+    kind,
+    id,
+    fields,
+    area,
+    from,
+    if_version: ifVersion,
+    owner,
+    surface: surface === undefined ? pageSurface() : surface,
+    detail,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Reads. Each takes an optional `signal` to abort it.
+
+/** GET _claw/data/kinds: the kinds this app declared, with the words,
+ *  fields and counts the member may see.
+ *  → { ok, brain, kinds: [{ kind, label, plural, fields, key, filters,
+ *  label_field, reads, writes, count, unconfirmed }], error }. `brain` is
+ *  false while the workspace has no brain yet (every read is empty). */
+export function kinds(args) {
+  return brainRead("kinds", args, viaCookie);
+}
+
+/** GET _claw/data/kinds/<kind>/records: one kind's records, newest first.
+ *  `where` an object (below), `order` "-updated_at" (default) |
+ *  "updated_at" | "created_at" | "-created_at" | "label" | "-label" |
+ *  "<field>" | "-<field>", `limit` 50 (at most 200), `cursor` the last
+ *  answer's `next`, `fields` ["name", "email"] only those, `prefix` the
+ *  label starts with (pickers), `state: false` leaves each field's state
+ *  out. → { ok, records, next, error } */
+export function listRecords(args) {
+  return brainRead("listRecords", args, viaCookie);
+}
+
+/** GET _claw/data/records/<id>: one record; `links: true` adds its links
+ *  both ways, to records the member may read.
+ *  → { ok, record, links: { out, in } | null, error } */
+export function getRecord(args) {
+  return brainRead("getRecord", args, viaCookie);
+}
+
+/** GET _claw/data/kinds/<kind>/counts: how many records match `where`;
+ *  `by` a field counts per value ("null" for none).
+ *  → { ok, count, by: { [value]: n } | null, error } */
+export function countRecords(args) {
+  return brainRead("countRecords", args, viaCookie);
+}
+
+/** GET _claw/data/search: records by words and meaning, across `kinds`
+ *  (default: every kind the app reads), `limit` at most 50. `meaning:
+ *  false` is keywords only: nothing is embedded or charged (a picker that
+ *  searches as the member types). A blank `q` asks nothing.
+ *  → { ok, meaning, results: [{ record: { id, kind, label, area,
+ *  updated_at }, score, matched, snippet }], error } */
+export function searchBrain(args) {
+  return brainRead("searchBrain", args, viaCookie);
+}
+
+/** GET _claw/data/records/<id>/history: who changed what, newest first
+ *  (`limit` at most 100). → { ok, changes: [{ id, at, op, fields, before,
+ *  after, by: { member, app, via } }], next, error } */
+export function recordHistory(args) {
+  return brainRead("recordHistory", args, viaCookie);
+}
+
+/** GET _claw/data/changes: what changed in the member's areas and the
+ *  app's kinds since `since` (the last answer's `next`; none: from the
+ *  start). → { ok, changes: [{ id, at, op, kind, record_id }], next, error } */
+export function brainChanges(args) {
+  return brainRead("brainChanges", args, viaCookie);
+}
+
+/** GET _claw/data/lists: the lists of records, of one `kind` or all.
+ *  → { ok, lists: [{ id, name, kind, area, count }], error } */
+export function brainLists(args) {
+  return brainRead("brainLists", args, viaCookie);
+}
+
+/** GET _claw/data/lists/<list>: a list and its records, in order.
+ *  → { ok, list, records, next, error } */
+export function listMembers(args) {
+  return brainRead("listMembers", args, viaCookie);
+}
+
+// ---------------------------------------------------------------------------
+// Writes. The member's press, through the cookie; the door logs each.
+
+/** POST _claw/data/write: make or change one record. Without `id` the
+ *  door finds the record by the kind's key, or makes one. `fields` {
+ *  name: value | null } (null clears), `area` a new record's area (or a
+ *  move), `ifVersion` refuses with `changed` when someone saved since,
+ *  `owner` { kind: "member" | "group", id } | null, `surface` (default the
+ *  page's) and `detail` (one sentence) for the activity line.
+ *  → { ok, id, created, changed, version, skipped } | { ok: false, error, code } */
+export function writeRecord(args) {
+  return post("writeRecord", args, (write) => ({ path: "write", body: writeBody(write) }));
+}
+
+/** POST _claw/data/write with { writes }: up to 100 writes, one
+ *  transaction, all or none. → { ok, results: [one writeRecord answer
+ *  each] } | { ok: false, error, code } */
+export function writeRecords(args) {
+  return post("writeRecords", args, ({ writes }) => {
+    if (!Array.isArray(writes)) throw new Missing("needs a list of writes");
+    if (!writes.length) return { done: { ok: true, results: [] } };
+    return { path: "write", body: { writes: writes.map(writeBody) } };
+  });
+}
+
+/** POST _claw/data/records/<id>/confirm: the member says these `fields`
+ *  are right (none named: every unconfirmed one).
+ *  → { ok, confirmed, version } */
+export function confirmFields(args) {
+  return post("confirmFields", args, ({ id, fields }) => ({ path: `records/${segment(id, "an id")}/confirm`, body: { fields } }));
+}
+
+/** POST _claw/data/records/<id>/erase: gone for every app, with no undo.
+ *  A person's press only. → { ok, erased } */
+export function eraseRecord(args) {
+  return post("eraseRecord", args, ({ id, reason }) => ({ path: `records/${segment(id, "an id")}/erase`, body: { reason } }));
+}
+
+/** POST _claw/data/records/<keep>/merge: `drop` folds into `keep` (its
+ *  empty fields filled, its links and lists moved) and goes.
+ *  → { ok, id, merged, filled, version } */
+export function mergeRecords(args) {
+  return post("mergeRecords", args, ({ keep, drop }) => ({ path: `records/${segment(keep, "the id to keep")}/merge`, body: { drop } }));
+}
+
+/** POST _claw/data/links { op: "add" }: link two records (`type` default
+ *  "related"). → { ok, created } */
+export function linkRecords(args) {
+  return post("linkRecords", args, ({ from, to, type }) => ({ path: "links", body: { op: "add", from, to, type } }));
+}
+
+/** POST _claw/data/links { op: "remove" }: unlink them (no `type`: every
+ *  type). → { ok, removed } */
+export function unlinkRecords(args) {
+  return post("unlinkRecords", args, ({ from, to, type }) => ({ path: "links", body: { op: "remove", from, to, type } }));
+}
+
+/** POST _claw/data/lists: a new list of one kind's records.
+ *  → { ok, id } */
+export function createList(args) {
+  return post("createList", args, ({ name, kind, area }) => ({ path: "lists", body: { name, kind, area } }));
+}
+
+/** POST _claw/data/lists/<list>/members: `add` and `remove` record ids
+ *  (at most 500), `position` where the added go. → { ok, added, removed } */
+export function changeList(args) {
+  return post("changeList", args, ({ list, add, remove, position }) => ({
+    path: `lists/${segment(list, "a list")}/members`,
+    body: { add, remove, position },
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Hooks, for "use client" components: a read on mount, again on every
+// dataChanged() (a write of this page's that answered ok, or a browser
+// app's auto-refresh), with lib/door.js's rules: `loading` until the first
+// answer for these arguments, a re-read keeps the last values until the
+// new ones land, each answer a new array, a read no longer needed
+// aborted. Each returns the read's values with `loading` and `reload`.
+
+/** A brain read, for a hook: the browser's, through the cookie. */
+const hookRead = (name) => (args) => brainRead(name, args, viaCookie);
+
+/** A read's empty values, fresh: a hook hands out a new array each time. */
+const emptyOf = (name) => () => JSON.parse(JSON.stringify(BRAIN_READS[name].empty));
+
+/** listRecords as a hook. → { records, next, error, loading, reload } */
+export function useRecords(args) {
+  return useDoorRead(hookRead("listRecords"), args, { empty: emptyOf("listRecords") });
+}
+
+/** getRecord as a hook; no id asks nothing and answers record: null.
+ *  → { record, links, error, loading, reload } */
+export function useRecord(args) {
+  return useDoorRead(hookRead("getRecord"), args, {
+    empty: emptyOf("getRecord"),
+    idle: (a) => a.id === undefined || a.id === null || a.id === "",
+  });
+}
+
+/** countRecords as a hook. → { count, by, error, loading, reload } */
+export function useRecordCounts(args) {
+  return useDoorRead(hookRead("countRecords"), args, { empty: emptyOf("countRecords") });
+}
+
+/** searchBrain as a hook; a blank `q` asks nothing. For a picker that
+ *  searches as the member types, pass `meaning: false`: each keystroke
+ *  aborts the read before it. → { results, meaning, error, loading, reload } */
+export function useBrainSearch(args) {
+  return useDoorRead(hookRead("searchBrain"), args, {
+    empty: emptyOf("searchBrain"),
+    idle: (a) => !String(a.q ?? "").trim(),
+  });
+}

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

@@ -2,6 +2,8 @@
 // product's path, before it proxies anything to the app
 // (docs/ARTIFACT-CONTRACTS.md §5). It is reachable from the BROWSER only —
 // the grant cookie is the identity — so everything here is client-side.
+// One exception: the data door (lib/brain-server.js) also answers the
+// app's server, with a bearer, and clawAnswer reads its answers there.
 //
 // Every call resolves; nothing throws. A 404 that names no refusal, or a
 // network error, means the gateway has no such route yet, and comes back
@@ -16,7 +18,10 @@
 // lib/platform.js wraps them as ask / requests / stopRequest and
 // lib/hooks.js as useJob and useRequests. `chat` and `cancel` are the
 // 0.3.x door to the same work, streamed into the app (startJob /
-// cancelJob): kept for a claw that has no `ask` yet. What an app still
+// cancelJob): kept for a claw that has no `ask` yet. `llm` (0.8.0) is one
+// shot of model work answered in the page, not asking an agent: lib/
+// platform.js wraps it as llm and lib/hooks.js as useLlm, and the check
+// refuses a screen that names its path. What an app still
 // never calls is monitoring: the OS draws Agent, Runs and Activity as
 // tabs on its window. The rest of the gateway's routes (§5) stay
 // reachable through claw() / clawStream() for a surface that has a real
@@ -199,6 +204,15 @@ export async function claw(path, { method = "GET", body, signal } = {}) {
     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);
+}
+
+/** A gateway's response read the way claw() reads it: a 404 with or
+ *  without a code (notFound), a refusal's words and code, or the JSON.
+ *  lib/brain-server.js reaches the data door from the server, with a
+ *  bearer instead of the cookie, and reads its answers through this, so
+ *  a 404 means the same thing on both sides. */
+export async function clawAnswer(res) {
   if (res.status === 404) return notFound(res);
   if (!res.ok) return { ok: false, status: res.status, ...(await readFailure(res)), unavailable: false };
   const text = await res.text().catch(() => "");