makersclaw 0.5.2 → 0.7.0

package/registry/blocks/stat-cards/README.md

@@ -125,27 +125,34 @@ States
 ## Example
 
 ```jsx
-// components/Overview.jsx — client: the numbers the server read
+// surfaces/overview.jsx — client: the numbers, read in the browser
 "use client";
-import { StatCards } from "./blocks/stat-cards";
+import { useRows } from "../lib/data";
 import { updateRow } from "../lib/actions";
+import { StatCards } from "../components/blocks/stat-cards";
 
-export default function Overview({ kpis, usage }) {
+export default function Overview() {
+  const summary = useRows({ source: "kpi_summary", limit: 1 });   // a view of the app's: this week's numbers, one row
+  const usage = useRows({ source: "quotas", orderBy: "name asc" });
+  const kpis = summary.rows[0] ?? {};
   return (
     <div className="grid gap-6">
       <StatCards
+        loading={summary.loading}
+        error={summary.error}
         items={[
-          { id: "mrr", label: "MRR", value: kpis.mrr, delta: kpis.mrrChange, trend: kpis.mrrWeeks, href: "/revenue" },
-          { id: "churn", label: "Logo churn", value: kpis.churn, delta: kpis.churnChange, invert: true },
-          { id: "trials", label: "Active trials", value: kpis.trials, previous: kpis.trialsLastWeek, delta: kpis.trialsChange },
+          { id: "mrr", label: "MRR", value: kpis.mrr, delta: kpis.mrr_change, trend: kpis.mrr_weeks, href: "/s/revenue" },
+          { id: "churn", label: "Logo churn", value: kpis.churn, delta: kpis.churn_change, invert: true },
+          { id: "trials", label: "Active trials", value: kpis.trials, previous: kpis.trials_last_week, delta: kpis.trials_change },
         ]}
         variant="cards"
       />
       <StatCards
         variant="usage"
         title="Plan usage"
-        items={usage.map((u) => ({ id: u.id, label: u.name, used: u.used, limit: u.limit, unit: u.unit }))}
-        onLimitChange={(item, limit) => updateRow({ source: "public.quotas", id: item.id, patch: { limit } })}
+        loading={usage.loading}
+        items={usage.rows.map((u) => ({ id: u.id, label: u.name, used: u.used, limit: u.limit, unit: u.unit }))}
+        onLimitChange={(item, limit) => updateRow({ source: "quotas", id: item.id, patch: { limit } })}
         limitLabel="Change budget"
       />
     </div>
@@ -153,6 +160,8 @@ export default function Overview({ kpis, usage }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 ## What it will not do
 
 - Fetch or compute: numbers come in formatted, changes already worked out.

package/registry/blocks/task-list/README.md

@@ -98,14 +98,15 @@ drag-to-reorder saves; tasks without one keep the order given.
 ## Example
 
 ```jsx
-// surfaces/tasks.jsx — server: load, hand over
-import { loadRows } from "../lib/data";
+// surfaces/tasks.jsx — client: read, hand over
+"use client";
+import { useRows } from "../lib/data";
 import Tasks from "../components/Tasks";
 
-export default async function TasksSurface() {
-  const { rows, error } = await loadRows({ source: "public.tasks", orderBy: "created_at asc" });
-  const people = await loadRows({ source: "public.people" });
-  return <Tasks tasks={rows} people={people.rows} error={error} />;
+export default function TasksSurface() {
+  const tasks = useRows({ source: "tasks", orderBy: "created_at asc" });
+  const people = useRows({ source: "people" });
+  return <Tasks tasks={tasks.rows} people={people.rows} loading={tasks.loading || people.loading} error={tasks.error} />;
 }
 ```
 
@@ -132,19 +133,19 @@ const COLUMNS = ["id", "title", "status", "assignees", "due", "priority", "tags"
 async function save(change) {
   for (const w of changeWrites(change, { columns: COLUMNS, keepNewIds: false })) {
     const r =
-      w.op === "insert" ? await insertRow({ source: "public.tasks", values: w.values, detail: w.values.title })
-      : w.op === "update" ? await updateRow({ source: "public.tasks", id: w.id, patch: w.patch })
-      : await deleteRow({ source: "public.tasks", id: w.id });
+      w.op === "insert" ? await insertRow({ source: "tasks", values: w.values, detail: w.values.title })
+      : w.op === "update" ? await updateRow({ source: "tasks", id: w.id, patch: w.patch })
+      : await deleteRow({ source: "tasks", id: w.id });
     if (r?.ok === false) return r;
   }
   return { ok: true };
 }
 
-export default function Tasks({ tasks, people, error }) {
+export default function Tasks({ tasks, people, loading, error }) {
   const [open, setOpen] = useState(null);
   return (
     <>
-      <TaskList tasks={tasks} statuses={STATUSES} people={people} onChange={save} onOpen={setOpen} error={error}
+      <TaskList tasks={tasks} statuses={STATUSES} people={people} onChange={save} onOpen={setOpen} loading={loading} error={error}
         starters={[{ label: "Weekly planning", tasks: [{ title: "Review last week" }, { title: "Pick three priorities" }] }]} />
       <Sheet open={Boolean(open)} onClose={() => setOpen(null)} title={open?.title}>{/* the task's fields */}</Sheet>
     </>
@@ -152,6 +153,8 @@ export default function Tasks({ tasks, people, error }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 Grouped by person, only open work, showing the project:
 
 ```jsx

package/registry/blocks/task-model/README.md

@@ -113,9 +113,9 @@ const COLUMNS = ["id", "title", "status", "assignees", "due", "priority", "paren
 
 async function onChange(change) {
   for (const w of changeWrites(change, { columns: COLUMNS, keepNewIds: false })) {
-    const r = w.op === "insert" ? await insertRow({ source: "public.tasks", values: w.values })
-            : w.op === "update" ? await updateRow({ source: "public.tasks", id: w.id, patch: w.patch })
-            : await deleteRow({ source: "public.tasks", id: w.id });
+    const r = w.op === "insert" ? await insertRow({ source: "tasks", values: w.values })
+            : w.op === "update" ? await updateRow({ source: "tasks", id: w.id, patch: w.patch })
+            : await deleteRow({ source: "tasks", id: w.id });
     if (r.ok === false) return r;
   }
   return { ok: true };

package/registry/blocks/transaction-list/README.md

@@ -79,22 +79,28 @@ An invoice row:
 ## Example
 
 ```jsx
-// components/Billing.jsx — client
+// surfaces/billing.jsx — client: invoices and payments
 "use client";
-import { TransactionList } from "./blocks/transaction-list";
+import { useRows } from "../lib/data";
+import { TransactionList } from "../components/blocks/transaction-list";
 
-export default function Billing({ invoices, payments, error }) {
+export default function Billing() {
+  const invoices = useRows({ source: "invoices", orderBy: "date desc" });
+  const payments = useRows({ source: "payments", orderBy: "date desc" });
   return (
     <div className="grid gap-6 lg:grid-cols-2">
       <TransactionList
         variant="invoices"
-        rows={invoices}
-        error={error}
+        rows={invoices.rows}
+        loading={invoices.loading}
+        error={invoices.error}
         description="Every invoice we have sent you."
-        downloadHref={(inv) => inv.pdfUrl}
+        downloadHref={(inv) => inv.pdf_url}
       />
       <TransactionList
-        rows={payments}
+        rows={payments.rows}
+        loading={payments.loading}
+        error={payments.error}
         dateFilter
         description="Money in and out of the account."
         onExport={async (rows) => {
@@ -109,6 +115,8 @@ export default function Billing({ invoices, payments, error }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 ## What it will not do
 
 - Sort, page, or filter by column: rows come in ordered, and a record set

package/registry/blocks/whiteboard/README.md

@@ -113,39 +113,45 @@ reuse them:
 A board page that saves itself:
 
 ```jsx
+// surfaces/board.jsx — client: one board, saved as it changes
 "use client";
-import { useState } from "react";
-import { Whiteboard } from "./blocks/whiteboard";
-import { sketchToText } from "./blocks/sketch-canvas";
+import { useSearchParams } from "next/navigation";
+import { useRow, whenLanded } from "../lib/data";
 import { updateRow } from "../lib/actions";
+import { Whiteboard } from "../components/blocks/whiteboard";
+import { sketchToText } from "../components/blocks/sketch-canvas";
 
-export default function BoardPage({ board, onShare }) {
-  const [title, setTitle] = useState(board.title);
+export default function BoardPage() {
+  const id = useSearchParams().get("row");
+  const { row: board, loading } = useRow({ source: "boards", id });
+  if (loading || !board) return null;
   return (
     <Whiteboard
-      title={title}
+      key={board.id}
+      title={board.title}
       onRename={async (next) => {
-        const res = await updateRow({ source: "public.boards", id: board.id, patch: { title: next } });
-        if (res.ok) setTitle(next);
+        const res = await updateRow({ source: "boards", id: board.id, patch: { title: next } });
+        if (res.ok) await whenLanded(); // the board is read again: the title is the new one
         return res;
       }}
-      defaultValue={board.sketch}                       // jsonb, may be null
-      onSave={(sketch) => updateRow({ source: "public.boards", id: board.id, patch: { sketch, sketch_text: sketchToText(sketch) } })}
-      onShare={onShare}
+      defaultValue={board.sketch}                       // jsonb, may be null; read once per board
+      onSave={(sketch) => updateRow({ source: "boards", id: board.id, patch: { sketch, sketch_text: sketchToText(sketch) } })}
       className="h-dvh rounded-none border-0"
     />
   );
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 Notes that become tasks (a `tasks` table of your own):
 
 ```jsx
 <Whiteboard
   defaultValue={board.sketch}
   onSave={save}
-  onCreateTask={({ title, sourceIds }) => insertRow({ source: "public.tasks", values: { title, board_id: board.id, source_ids: sourceIds } })}
-  onOpenTask={(task) => router.push(`/tasks/${task.id}`)}
+  onCreateTask={({ title, sourceIds }) => insertRow({ source: "tasks", values: { title, board_id: board.id, source_ids: sourceIds } })}
+  onOpenTask={(task) => router.push(`/s/tasks?row=${task.id}`)}
 />
 ```
 

package/src/cli.mjs

@@ -4,7 +4,7 @@
 // --json is the same result as one object, for the platform.
 
 import { delimiter, resolve } from "node:path";
-import { CliError, add, diff, init, remove, update } from "./install.mjs";
+import { CliError, add, diff, init, install, mode, remove, update } from "./install.mjs";
 import { loadItems, loadTemplate, packageInfo, readmeOf, searchItems, suggest, templateNames, useExtraBlockRoots } from "./registry.mjs";
 
 const COMMANDS = {
@@ -21,6 +21,9 @@ const COMMANDS = {
   diff: "diff",
   update: "update",
   upgrade: "update",
+  install: "install",
+  i: "install",
+  mode: "mode",
   help: "help",
 };
 
@@ -30,6 +33,8 @@ const VALUE_FLAGS = new Map([
   ["--template", "template"],
   ["--type", "type"],
   ["--limit", "limit"],
+  ["--tables", "tables"],
+  ["--mode", "mode"],
 ]);
 const BOOL_FLAGS = new Map([
   ["--json", "json"],
@@ -74,6 +79,8 @@ function helpText() {
   return `makersclaw ${version} — the Makersclaw app template, its kit and its blocks
 
   npx makersclaw init [dir] [-t next]     lay the template: base files, the kit, the check
+                     [--tables own|public] where its tables live (new apps: own; never changes an app's)
+                   [--mode browser|server] its mode (new apps: server; browser writes tables own too)
   npx makersclaw add <name...>            install blocks, or restore a kit component
   npx makersclaw search <words...>        find blocks and components by what they do
   npx makersclaw view <name>              one item: props, data, an example
@@ -82,9 +89,12 @@ function helpText() {
   npx makersclaw diff                     what update would change in this app
   npx makersclaw update [--major]         lay this version's fixed files and blocks
                      [--adopt]             …or take on an app laid before makersclaw (kit era)
+  npx makersclaw install                  the app's packages: pnpm, from pnpm-lock.yaml
+  npx makersclaw mode <browser|server>    switch the app's mode: its fixed files, and what its code must change
 
   --cwd <dir>   the app (default: this folder)       --json   one JSON object
   --force       init over an app that exists (your own files stay)
+  install: MAKERSCLAW_PNPM names a pnpm, MAKERSCLAW_PNPM_STORE its store
   templates: ${templateNames().join(", ")}`;
 }
 
@@ -100,6 +110,13 @@ function packageLines(changes) {
   return [`  package.json: ${changes.map((c) => `${c.name} ${c.from ?? "(new)"} → ${c.to}`).join(" · ")}`];
 }
 
+/** The lock's line, when it was written. What it left out is a note. */
+function lockLine(lock, written) {
+  if (!lock || !written) return [];
+  const kept = lock.carried.length ? ` · kept from yours: ${lock.carried.join(", ")}` : "";
+  return [`  pnpm-lock.yaml: cut from this release's lock, ${plural(lock.covered, "dependency", "dependencies")}${kept}`];
+}
+
 function layText(r, verb) {
   const head =
     verb === "update"
@@ -115,10 +132,11 @@ function layText(r, verb) {
   if (r.removed.length) lines.push(`  removed (no longer shipped): ${listLine(r.removed)}`);
   if (r.blocks.length) lines.push(`  blocks: ${r.blocks.join(", ")}`);
   lines.push(...packageLines(r.package));
-  lines.push(`  ${plural(r.pinned, "fixed file")} pinned in check/pins.json · makersclaw.json records ${r.version}`);
+  lines.push(...lockLine(r.lock, r.written.includes("pnpm-lock.yaml")));
+  lines.push(`  ${plural(r.pinned, "fixed file")} pinned in check/pins.json · makersclaw.json records ${r.version}, tables ${r.tables}, mode ${r.mode}`);
   for (const n of r.notes) lines.push(`  note: ${n}`);
   const next = [];
-  if (r.install) next.push("npm install");
+  if (r.install) next.push("npx makersclaw install");
   if (verb === "init" && !r.from) next.push("design app/shell.jsx and the surfaces", "find blocks: npx makersclaw search <what the surface needs>");
   else next.push("npm run check");
   lines.push(`next: ${next.join(" · ")}`);
@@ -134,7 +152,9 @@ function addText(r) {
     lines.push(`  ${a.import}`);
   }
   lines.push(...packageLines(r.package));
-  if (r.install) lines.push("next: npm install");
+  lines.push(...lockLine(r.lock, r.lock?.written));
+  for (const n of r.notes) lines.push(`  note: ${n}`);
+  if (r.install) lines.push("next: npx makersclaw install");
   for (const u of r.usage) if (u.readme) lines.push("", u.readme.trimEnd());
   return lines.join("\n");
 }
@@ -186,8 +206,25 @@ function listText(items) {
   return lines.join("\n");
 }
 
+function modeText(r) {
+  const lines = [
+    r.changed
+      ? `makersclaw ${r.version} · template ${r.template} · mode ${r.was} → ${r.mode}`
+      : `makersclaw ${r.version} · template ${r.template} · already ${r.mode}: its fixed files laid again`,
+  ];
+  if (r.written.length) lines.push(`  wrote ${plural(r.written.length, "file")}: ${listLine(r.written)}`);
+  if (r.removed.length) lines.push(`  removed (${r.mode} mode lays none): ${listLine(r.removed)}`);
+  lines.push(...packageLines(r.package));
+  lines.push(`  ${plural(r.pinned, "fixed file")} pinned in check/pins.json · makersclaw.json records mode ${r.mode}`);
+  for (const n of r.notes) lines.push(`  note: ${n}`);
+  lines.push(`the app's own code${r.changed ? " must change" : ", in this mode"}:`);
+  for (const c of r.change) lines.push(`  - ${c}`);
+  lines.push(`next: ${[...(r.install ? ["npx makersclaw install"] : []), "npm run check"].join(" · ")}`);
+  return lines.join("\n");
+}
+
 function diffText(r) {
-  const lines = [`makersclaw ${r.from} → ${r.to} · ${r.compatible ? "compatible" : "changes the contract — update --major"}`];
+  const lines = [`makersclaw ${r.from} → ${r.to} · ${r.compatible ? "compatible" : "changes the contract — update --major"} · mode ${r.mode}`];
   if (!r.entries.length && !r.package.length) {
     lines.push(`  nothing to update — the app matches makersclaw ${r.to}`);
     return lines.join("\n");
@@ -198,6 +235,16 @@ function diffText(r) {
   return lines.join("\n");
 }
 
+function installText(r) {
+  const how = r.manager === "pnpm" ? `pnpm ${r.version} (${r.via})` : `npm ${r.version ?? ""}`.trim();
+  const lock = r.manager !== "pnpm" ? "pnpm-lock.yaml not read" : r.frozen ? "frozen: pnpm-lock.yaml as laid" : `pnpm-lock.yaml updated — ${r.why}`;
+  const lines = [`installed with ${how} · ${lock}`];
+  if (r.manager === "pnpm") lines.push(`  node_modules hoisted, hard-linked from ${r.store ?? "pnpm's default store"}`);
+  for (const n of r.notes) lines.push(`  note: ${n}`);
+  lines.push("next: npm run check");
+  return lines.join("\n");
+}
+
 function templateFor(opts, fallback = "next") {
   const name = opts.template ?? fallback;
   const tpl = loadTemplate(name);
@@ -205,8 +252,9 @@ function templateFor(opts, fallback = "next") {
   return tpl;
 }
 
-/** Run one command. Returns { result, text } or throws a CliError. */
-export function run(opts) {
+/** Run one command. Returns { result, text } or throws a CliError.
+ *  `stderr` hears what must not wait for the end (install's fallback). */
+export function run(opts, { stderr = process.stderr, env = process.env } = {}) {
   const cwd = resolve(opts.cwd ?? process.cwd());
   switch (opts.command) {
     case "help":
@@ -215,7 +263,7 @@ export function run(opts) {
       return { result: packageInfo(), text: packageInfo().version };
     case "init": {
       const dir = opts.args[0] ? resolve(cwd, opts.args[0]) : cwd;
-      const result = init(dir, { template: opts.template ?? "next", force: Boolean(opts.force) });
+      const result = init(dir, { template: opts.template ?? "next", force: Boolean(opts.force), tables: opts.tables, mode: opts.mode });
       return { result: { dir, ...result }, text: layText(result, "init") };
     }
     case "update": {
@@ -233,6 +281,14 @@ export function run(opts) {
         text: `removed ${opts.args.join(", ")} — ${plural(result.removed.length, "file")}; installed now: ${result.blocks.join(", ") || "no blocks"}`,
       };
     }
+    case "install": {
+      const result = install(cwd, { env, onNote: (line) => stderr.write(`makersclaw: ${line}\n`) });
+      return { result: { dir: cwd, ...result }, text: installText(result) };
+    }
+    case "mode": {
+      const result = mode(cwd, opts.args[0] ?? opts.mode);
+      return { result: { dir: cwd, ...result }, text: modeText(result) };
+    }
     case "diff": {
       const result = diff(cwd);
       return { result: { dir: cwd, ...result }, text: diffText(result) };
@@ -299,7 +355,7 @@ export function main(argv, { stdout = process.stdout, stderr = process.stderr, e
   try {
     opts = parseArgs(argv);
     if (opts.help && opts.command !== "help") opts = { ...opts, command: "help" };
-    const { result, text } = run(opts);
+    const { result, text } = run(opts, { stderr, env });
     stdout.write(opts.json ? `${JSON.stringify({ ok: true, command: opts.command, ...result }, null, 2)}\n` : `${text}\n`);
     return 0;
   } catch (error) {