makersclaw 0.1.0

package/templates/next/files/surfaces/README.md

@@ -0,0 +1,32 @@
+# surfaces/
+
+One file per domain surface, named after its key: `surfaces/<key>.jsx`.
+Each default-exports a component. It receives `surface` (`{ key, kind,
+label, source }`) and `searchParams` (the URL query; `?row=<id>` means
+"highlight this row").
+
+A server surface reads with `../lib/data` and renders; a surface that
+needs hooks or handlers starts with `"use client"`, uses `../lib/hooks`
+and `../lib/actions`, and cannot import `../lib/data` — split it into a
+server file that loads rows and a client component that gets them as
+props (see `../README.md` §4).
+
+Agent, Runs and Activity are not surfaces. The OS draws them as tabs on
+the app window, beside the App tab these files fill; their keys
+(`agent`, `runs`, `activity`) are reserved and no file here may take
+one. Settings (model, prompt, skills, connections, schedule) are not a
+surface either: they are the window's Settings tab, the same for every
+artifact.
+
+Commissioning work IS a surface's business. A surface that lists objects
+the agent can produce carries the verb that starts one ("Generate a
+launch plan", beside the manual "New launch plan") and draws the panel
+that follows it — `useJob()` in `../lib/hooks.js`, §5 of `../README.md`.
+The panel is not a surface and takes no key: it opens because the founder
+pressed something and closes when the work lands.
+
+Register each in `../surfaces.js` (import + entry with `component`).
+Until the entry has a `component` the surface is planned: marked in the
+nav, "Makersclaw is building this" on its page.
+
+The API is in `../README.md` §5.

package/templates/next/files/surfaces.js

@@ -0,0 +1,53 @@
+/**
+ * The surface manifest — the one file that says what this app shows.
+ * The shell's nav lists these in order; /s/<key> renders the matching
+ * component; the desk checklist reads the same list.
+ *
+ *   key        the route segment and the `surface` stamped on activity rows
+ *   label      what the nav shows
+ *   kind       optional, free text, one or two words for the checklist
+ *              ("board", "inbox", "report") — not an enum, nothing keys on it
+ *   source     the table the surface reads, when it reads one
+ *   home       true on the one surface / opens; otherwise the first entry
+ *   component  the surface's component. LEAVE IT OUT while the surface is
+ *              still planned: the nav shows it as planned and its page says
+ *              "Makersclaw is building this". Add the file under surfaces/,
+ *              import it here, set `component`, and it is built.
+ *
+ * Only DOMAIN surfaces live here — the things the app finds, makes, sends
+ * or receives. Agent, Runs and Activity are not surfaces: the OS draws
+ * them as tabs on every app window, beside the App tab this manifest
+ * fills. Their keys (`agent`, `runs`, `activity`) are reserved and an
+ * entry may not take one. The template ships this list empty;
+ * Makersclaw writes this file from the blueprint (artifact_scaffold).
+ * Import it from server code only (pages, layout): entries with a
+ * component pull in server components.
+ */
+
+// A domain surface, once built, looks like this:
+//
+//   import Investors from "./surfaces/investors";
+//   { key: "investors", label: "Investors", kind: "board", source: "public.investors", home: true, component: Investors },
+
+const surfaces = [];
+
+export default surfaces;
+
+/** The surface / opens: the one flagged `home`, else the first entry;
+ *  undefined while the manifest is empty (app/page.jsx says so). */
+export function homeSurface() {
+  return surfaces.find((s) => s.home) ?? surfaces[0];
+}
+
+/** The nav's view of the manifest: plain data, no components, so it can
+ *  cross into client components (app/shell.jsx). */
+export function surfaceNav() {
+  return surfaces.map(({ key, label, kind, source, home, component }) => ({
+    key,
+    label,
+    kind: kind ?? null,
+    source: source ?? null,
+    home: Boolean(home),
+    built: Boolean(component),
+  }));
+}

package/templates/next/template.json

@@ -0,0 +1,118 @@
+{
+  "name": "next",
+  "title": "Makersclaw app (Next.js 15)",
+  "description": "The behaviour every app shares, the parts every app is assembled from, and none of the app's own look — the colours are the workspace's. It carries the data layer (lib/data.js, lib/db.js), the write actions that log activity (lib/actions.js), the _claw platform client with its identity wrapper and hooks (lib/claw.js, lib/platform.js, lib/hooks.js), routing (/s/<key>), the middleware, error boundaries, Tailwind v4 mapped to the workspace theme (app/globals.css + _claw/theme.css), the kit (components/ui), the parts bound to the data layer (components/parts) and `npm run check`. The app designs the inside of the App tab on top: app/shell.jsx and every domain surface, assembled from the kit and the blocks with tokens only.",
+  "files": {
+    "fixed": [
+      "app/globals.css",
+      "app/layout.jsx",
+      "app/page.jsx",
+      "app/error.jsx",
+      "app/global-error.jsx",
+      "app/not-found.jsx",
+      "app/error-relay.jsx",
+      "app/auto-refresh.jsx",
+      "app/s/[key]/page.jsx",
+      "lib/*.js",
+      "components/ui/*",
+      "components/parts/*",
+      "check/run.mjs",
+      "middleware.js",
+      "next.config.mjs",
+      "postcss.config.mjs"
+    ],
+    "docs": ["README.md", "surfaces/README.md", "schema.sql"],
+    "starter": ["app/shell.jsx", "surfaces.js"],
+    "merged": ["package.json"]
+  },
+  "components": [
+    {
+      "name": "button",
+      "type": "component",
+      "title": "Button, IconButton",
+      "description": "The one button: variant primary (one per surface) · secondary · quiet · danger · link; size md (44px) · sm; icon; href for a link. IconButton for an icon alone, label required.",
+      "tags": ["button", "action", "link", "icon button"],
+      "files": ["components/ui/button.jsx"]
+    },
+    {
+      "name": "field",
+      "type": "component",
+      "title": "Field, Input, Textarea, Select, Switch, Checkbox",
+      "description": "Form controls with their label, hint and error. Select with empty options renders a muted line, never a disabled dropdown.",
+      "tags": ["form", "input", "select", "dropdown", "textarea", "switch", "checkbox", "toggle"],
+      "files": ["components/ui/field.jsx"]
+    },
+    {
+      "name": "notice",
+      "type": "component",
+      "title": "Card, Notice, Badge, Kicker, Empty",
+      "description": "Containers and signals: Card, Notice (tone neutral · info · success · warning · danger), Badge, Kicker (the small line above a heading), Empty (a search or filter with no matches).",
+      "tags": ["card", "alert", "notice", "badge", "empty state", "status"],
+      "files": ["components/ui/notice.jsx"]
+    },
+    {
+      "name": "sheet",
+      "type": "component",
+      "title": "Sheet, Confirm",
+      "description": "The one overlay — a rail beside the work (side end), a dialog (center) or a bottom sheet; every side is a bottom sheet on a narrow window. Confirm is the \"delete this?\" case.",
+      "tags": ["dialog", "modal", "drawer", "overlay", "confirm", "rail"],
+      "files": ["components/ui/sheet.jsx"]
+    },
+    {
+      "name": "tabs",
+      "type": "component",
+      "title": "Tabs, TabPanel",
+      "description": "Views of ONE thing (a record's notes | history), with roving focus. Never for the app's surfaces — those are the shell's nav.",
+      "tags": ["tabs", "views", "segmented"],
+      "files": ["components/ui/tabs.jsx"]
+    },
+    {
+      "name": "menu",
+      "type": "component",
+      "title": "Menu",
+      "description": "The \"…\" of a row, on the Popover API. Empty items render nothing: a menu is earned by having actions.",
+      "tags": ["menu", "dropdown", "actions", "overflow"],
+      "files": ["components/ui/menu.jsx"]
+    },
+    {
+      "name": "icon",
+      "type": "component",
+      "title": "Icon",
+      "description": "One inline sprite of stroke glyphs; ICON_NAMES lists them. A missing glyph is added here, never drawn as an <svg> in a surface.",
+      "tags": ["icon", "glyph", "svg"],
+      "files": ["components/ui/icon.jsx"]
+    },
+    {
+      "name": "depiction",
+      "type": "component",
+      "title": "Depiction",
+      "description": "The frame for a picture of something that exists elsewhere (a tweet, a LinkedIn post) — scales it to the column without reflowing it. README §3c.",
+      "tags": ["depiction", "preview", "mockup", "frame"],
+      "files": ["components/ui/depiction.jsx"]
+    },
+    {
+      "name": "cx",
+      "type": "component",
+      "title": "cx",
+      "description": "Join class names, dropping the falsy ones.",
+      "tags": ["classnames", "utility"],
+      "files": ["components/ui/cx.js"]
+    },
+    {
+      "name": "fixture",
+      "type": "part",
+      "title": "useFixture, isSample, FixtureNotice",
+      "description": "The worked example shown while a table is empty — rows in code, never INSERTed; clearing writes nothing; a sample row carries _sample.",
+      "tags": ["example", "sample", "fixture", "empty state", "onboarding"],
+      "files": ["components/parts/fixture.jsx"]
+    },
+    {
+      "name": "record-switcher",
+      "type": "part",
+      "title": "RecordSwitcher",
+      "description": "Pick a saved record or make a new one; with nothing saved it shows only New.",
+      "tags": ["switcher", "picker", "saved", "records", "select"],
+      "files": ["components/parts/record-switcher.jsx"]
+    }
+  ]
+}