@montytools/cli 0.4.2 → 0.5.1

package/template/AGENTS.md

@@ -31,9 +31,16 @@ Folders are managed for you: this app lives in `~/Monty/<slug>`. `monty current`
    Icons from `lucide-react`. Don't install other component libraries or
    write raw-color CSS — use semantic tokens (`bg-background`,
    `text-muted-foreground`, …). Don't edit `src/index.css` theme tokens.
+   The look is Lyra: surfaces are stock components — borderless,
+   sharp-cornered — never hand-styled divs; chart marks are sharp
+   rectangles on real axes. The `monty-design` skill is the full spec.
 4. **Schema changes = edit `monty.config.ts` and save.** Types update
    immediately. Prefer additive changes; give new fields `.optional()` or
    `.default(...)` so existing records stay readable.
+5. **You are not done until the work is saved.** After every meaningful
+   change verified in dev, run `monty save "<what changed>"` — it builds,
+   typechecks, and pushes the working copy to the cloud copy, like
+   `git push main`. Unsaved work exists only on this machine.
 
 ## Data: define, then use
 
@@ -92,6 +99,98 @@ await update(row._id, { receipt });                     // store descriptor, not
 const { url } = useFileUrl(app, row.receipt);            // authenticated blob: URL for previews/downloads
 ```
 
+## Derived fields, metrics, pages (V2 — the platform renders these)
+
+Your config can carry a whole database app the platform shell renders for
+you — system table views, record drawers — no React needed.
+This SPA scaffold exists for the pages that ARE bespoke (`pages` entries
+with `kind: "custom"` mount your routes inside that shell).
+
+```ts
+import { defineApp, formula, lookup, montyDate, montyMoney, montyRef, rollup, self } from "@montytools/sdk";
+import { z } from "zod";
+
+export const app = defineApp({
+  slug: "pipeline",
+  tables: {
+    people: z.object({
+      name: z.string().min(1),
+      companyId: montyRef("companies"),          // typed relation
+      commissionRate: z.number().default(0.1),
+      // Derived fields live IN the table, like spreadsheet columns:
+      companyName: lookup(z.string(), { ref: "companyId", field: "name" }),
+      monthlySales: rollup(montyMoney(), {       // live aggregate (SUMIFS)
+        from: "sales",
+        where: { status: "won", salespersonId: self("_id") },
+        sum: "amount", over: "closedAt", range: "currentMonth",
+      }),
+      commission: formula(montyMoney(), "monthlySales * commissionRate"),
+    }),
+    companies: z.object({ name: z.string().min(1) }),
+    sales: z.object({
+      amount: montyMoney(),
+      status: z.enum(["open", "won", "lost"]).default("open"),
+      salespersonId: montyRef("people"),
+      closedAt: montyDate().optional(),
+    }),
+  },
+  metrics: {  // app-level named numbers formulas reach as `metrics.wonThisMonth`
+    wonThisMonth: rollup(montyMoney(), { from: "sales", where: { status: "won" }, sum: "amount", over: "closedAt", range: "currentMonth" }),
+  },
+  pages: {
+    people: { kind: "view", table: "people", summaries: { monthlySales: "sum" } },
+    reports: { kind: "custom", path: "/reports" },   // ← your src/routes/reports.tsx
+  },
+});
+```
+
+Rules that matter:
+
+- **Custom pages wear the platform chrome from `@montytools/sdk/ui`** — the
+  SAME components the shell renders its own pages with, so your page is
+  indistinguishable from a system table view. Every custom page opens with
+  `PageHeader`; without it the page looks foreign beside record pages:
+
+  ```tsx
+  import { PageHeader, PageHeaderButton } from "@montytools/sdk/ui";
+
+  <div className="flex h-full min-h-dvh flex-col">
+    <PageHeader icon={ChartColumn} title="Reports" meta="42 rows">
+      <PageHeaderButton onClick={exportCsv}>Export</PageHeaderButton>
+      <PageHeaderButton primary onClick={openNew}>
+        <Plus className="size-3.5" /> New
+      </PageHeaderButton>
+    </PageHeader>
+    <main className="min-h-0 flex-1 overflow-auto p-6">…</main>
+  </div>
+  ```
+
+  `primary` marks the page's one main action; other actions wear the quiet
+  control style; `icon` is any lucide icon (defaults to the custom-page
+  puzzle mark the sidebar uses). Also there: `FloatingBar` +
+  `FloatingBarButton` (the bottom-center bar for bulk-selection actions and
+  mode strips) and the Lyra table classes `SURFACE`/`THEAD`/`TH`/`ROW`/`CHIP`
+  for record-like tables (`<div className={SURFACE}><table>…`), identical to
+  the app's Configuration surfaces.
+- **Formulas are strings**, not functions — the Monty expression grammar
+  (`+ - * / %`, comparisons, `&& || !`, `IF/ROUND/ABS/MIN/MAX`,
+  `metrics.<name>`). A formula sees only fields declared ABOVE it. Type
+  errors and unknown identifiers fail the compile with the fix inline.
+- **Derived fields are read-only** — writing one through `useInsert`/
+  `useUpdate` is a `VALIDATION` error naming the field and its kind.
+- Rollup `where` values are equality literals or `self("ownField")` ("this
+  row's value"). `sum:` names a numeric field; `count: true` counts.
+- In custom pages, read metrics/rollups with `useMetric(app, "wonThisMonth")`
+  and `useAggregate(app, "people", "monthlySales", rowIds)`.
+- **Datasets** (computed row sets — hidden data, joins): declare the row
+  shape in `datasets: { leaderboard: z.object({...}) }`, implement it as a
+  `defineDataset` export in `server/index.ts` (≤1,000 rows — aggregate or
+  filter server-side), consume with `useDataset(app, "leaderboard")` —
+  polled (focus + optional interval + your own writes), NOT live.
+- `monty schema pull` regenerates this file from the platform if another
+  agent edited the schema remotely (the terminal will tell you when —
+  `MANIFEST_DRIFT`).
+
 ## Errors are instructions
 
 Every platform error is one line shaped like:
@@ -116,7 +215,7 @@ When logic must not run in the browser (private tables, third-party APIs with
 secret keys, webhooks, clocks), create `server/index.ts` with named async
 exports. Web-standard APIs only (`fetch`, `crypto`, `URL`, …) — no `node:`
 imports; it runs on Cloudflare Workers when Live and inside `monty dev` in
-Studio. Every export gets `ctx`: `ctx.records` (full CRUD on all your
+a session. Every export gets `ctx`: `ctx.records` (full CRUD on all your
 tables, including ones the UI never exposes), `ctx.secrets` (see below),
 `ctx.viewer` (who called: member session/visitor/schedule/none), and
 `ctx.track()` (emit an event).
@@ -160,10 +259,10 @@ Public functions are NOT callable through `useServerFn` — only at their
 public).
 
 **Secrets:** `monty secret set STRIPE_KEY` stores a key for Live (write-only,
-never in code or config). In Studio, put the same names in the gitignored
-`.monty/secrets.json`. Both arrive as `ctx.secrets.STRIPE_KEY`.
+never in code or config). In a dev session, put the same names in the
+gitignored `.monty/secrets.json`. Both arrive as `ctx.secrets.STRIPE_KEY`.
 
-**Studio behavior:** `monty dev` runs your schedules for real (a `cron:` line
+**Session behavior:** `monty dev` runs your schedules for real (a `cron:` line
 prints per firing, UTC) and serves public functions at
 `http://localhost:<port>/__monty/public/<name>` — curl them to test.
 
@@ -180,25 +279,24 @@ monty dev         # Vite + HMR, auto-picks a free port and prints it
 Headless? Verify with `monty build` then `monty typecheck` (typecheck builds
 first when needed — the build generates `src/routeTree.gen.ts`).
 
-**Studio vs Live:** every Monty app has two states. While `monty dev` runs,
-the app is in **Studio** — visible in the workspace to admins only
-(tunneled, `#dev` sandboxed data). **Live** is the published state the
-whole team sees. Going Live is the owner's **Publish** click in the
-workspace menu bar — it signals your running `monty dev`, which builds,
-typechecks, and uploads. You are done when the app works in Studio;
-leave `monty dev` running and let the owner publish. Only run
-`monty deploy` directly if the user explicitly asks.
+**One live app:** there is ONE copy of the app — the one the team uses.
+While `monty dev` runs, workspace admins see your running session's
+version automatically (tunneled); everyone else
+keeps the saved copy. After every meaningful change verified in dev, run
+`monty save "<what changed>"` — it pushes the work to the cloud copy,
+like `git push main` (build + typecheck gate it, so nothing uncompilable
+ever ships). Leave `monty dev` running while you work.
 
 **Driving your app in a browser (agents):** while `monty dev` runs, opening
 `http://localhost:5173` is ALREADY AUTHENTICATED — no sign-in screen (the dev
 server mints short-lived workspace tokens from the CLI login). Point
 Playwright or any browser automation at it, click through your app against
-reactive sandboxed data, and read your errors in the `monty dev` terminal
+reactive live data, and read your errors in the `monty dev` terminal
 (`[browser:error] …` lines). Edit → HMR → look → fix: verify your own work.
 
-Studio writes go to a sandboxed `#dev` namespace inside your real workspace —
-iterate freely, Live app data is untouched. The "STUDIO · … · sandbox data"
-badge confirms it.
+The session reads and writes the app's REAL records — there is one set
+of data, and every write journals into the app's Activity. Treat edits as
+real edits; the "SESSION · … · live data" badge reminds you.
 
 ## Modeling tips
 

package/template/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@fontsource-variable/roboto": "^5.2.10",
-    "@montytools/sdk": "^0.1.5",
+    "@montytools/sdk": "^0.2.1",
     "@tanstack/react-router": "1.170.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/template/src/index.css

@@ -3,6 +3,10 @@
 @import "shadcn/tailwind.css";
 @import "@fontsource-variable/roboto";
 
+/* Shared platform chrome (@montytools/sdk/ui) ships Tailwind classes in its
+   dist — scan it so they compile. */
+@source "../node_modules/@montytools/sdk/dist/ui.js";
+
 
 @custom-variant dark (&:is(.dark *));
 
@@ -85,37 +89,37 @@
 }
 
 .dark {
-    --background: oklch(0.153 0.006 107.1);
-    --foreground: oklch(0.988 0.003 106.5);
-    --card: oklch(0.228 0.013 107.4);
-    --card-foreground: oklch(0.988 0.003 106.5);
-    --popover: oklch(0.228 0.013 107.4);
-    --popover-foreground: oklch(0.988 0.003 106.5);
-    --primary: oklch(0.437 0.078 188.216);
-    --primary-foreground: oklch(0.984 0.014 180.72);
-    --secondary: oklch(0.274 0.006 286.033);
-    --secondary-foreground: oklch(0.985 0 0);
-    --muted: oklch(0.286 0.016 107.4);
-    --muted-foreground: oklch(0.737 0.021 106.9);
-    --accent: oklch(0.286 0.016 107.4);
-    --accent-foreground: oklch(0.988 0.003 106.5);
-    --destructive: oklch(0.704 0.191 22.216);
-    --border: oklch(1 0 0 / 10%);
-    --input: oklch(1 0 0 / 15%);
-    --ring: oklch(0.58 0.031 107.3);
-    --chart-1: oklch(0.855 0.138 181.071);
-    --chart-2: oklch(0.704 0.14 182.503);
-    --chart-3: oklch(0.6 0.118 184.704);
-    --chart-4: oklch(0.511 0.096 186.391);
-    --chart-5: oklch(0.437 0.078 188.216);
-    --sidebar: oklch(0.228 0.013 107.4);
-    --sidebar-foreground: oklch(0.988 0.003 106.5);
-    --sidebar-primary: oklch(0.704 0.14 182.503);
-    --sidebar-primary-foreground: oklch(0.277 0.046 192.524);
-    --sidebar-accent: oklch(0.286 0.016 107.4);
-    --sidebar-accent-foreground: oklch(0.988 0.003 106.5);
-    --sidebar-border: oklch(1 0 0 / 10%);
-    --sidebar-ring: oklch(0.58 0.031 107.3);
+    --background: #101112;
+    --foreground: #F1F2F3;
+    --card: #17181A;
+    --card-foreground: #F1F2F3;
+    --popover: #17181A;
+    --popover-foreground: #F1F2F3;
+    --primary: #266DF0;
+    --primary-foreground: #FFFFFF;
+    --secondary: rgb(255 255 255 / 0.05);
+    --secondary-foreground: #F1F2F3;
+    --muted: rgb(255 255 255 / 0.05);
+    --muted-foreground: rgb(255 255 255 / 0.6);
+    --accent: rgb(255 255 255 / 0.05);
+    --accent-foreground: #F1F2F3;
+    --destructive: oklch(0.68 0.19 25);
+    --border: #1B1C1F;
+    --input: #212224;
+    --ring: #266DF0;
+    --chart-1: #266DF0;
+    --chart-2: #4E8CFC;
+    --chart-3: #9B69FF;
+    --chart-4: #6EA5F7;
+    --chart-5: #2D3A55;
+    --sidebar: #101112;
+    --sidebar-foreground: #F1F2F3;
+    --sidebar-primary: #266DF0;
+    --sidebar-primary-foreground: #FFFFFF;
+    --sidebar-accent: rgb(255 255 255 / 0.05);
+    --sidebar-accent-foreground: #F1F2F3;
+    --sidebar-border: #1B1C1F;
+    --sidebar-ring: #266DF0;
 }
 
 @layer base {