@montytools/cli 0.2.10 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montytools/cli",
-  "version": "0.2.10",
+  "version": "0.4.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TomasMonty/monty-v2.git",

package/skills/monty-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: monty-build
-description: Build, run, and deploy Monty workspace apps. Use whenever the task involves a Monty app, monty.config.ts, the monty CLI (create/dev/deploy/add), the @montytools/sdk, or a prompt mentioning usemonty.dev. Covers folder discipline, the build loop, data/auth rules, and error handling.
+description: Build, run, and deploy Monty workspace apps. Use whenever the task involves a Monty app, monty.config.ts, the monty CLI (create/dev/logs/deploy/add), the @montytools/sdk, or a prompt mentioning usemonty.dev. Covers folder discipline, the build loop, data/auth rules, and error handling.
 ---
 
 # Building Monty apps
@@ -12,29 +12,42 @@ platform's job. The complete contract lives in the app's own `AGENTS.md`
 the territory.
 
 Every app has two states: **Live** (published — what members and visitors
-see) and **Studio** (development — your running `monty dev` session on
-`#dev`-sandboxed data). Those are the only names for them; "dev"/"prod"
-mean something else on this platform.
+see) and **Studio** (development — a running dev shell on `#dev`-sandboxed
+data, often already started for you by the Monty desktop). Those are the only
+names for them; "dev"/"prod" mean something else on this platform.
 
 ## Rules
 
-1. **Folders are managed.** Apps live in `~/Monty/<slug>`. `monty current`
-   tells you where you are; `cd "$(monty select <slug>)"` jumps to an app;
-   `monty apps` lists local ones. Never mkdir app folders by hand.
-2. **The loop:** `monty create <slug> --name "Name" --icon <lucide-icon>` →
+1. **Folders are managed.** Apps live in `~/.monty/apps/<id>` (a server-issued
+   id, minted when `monty create` registers the app — so create needs
+   `monty login` first). `monty current` tells you where you are;
+   `cd "$(monty select <slug>)"` jumps to an app; `monty apps` lists local
+   ones. Never mkdir app folders by hand, and never edit the `id:` line in
+   `monty.config.ts`.
+2. **The loop:** `monty create <slug> --name "Name" --icon <tabler-icon>` →
    (if the prompt includes a `build id`, pass it: `--build <id>` — the
    workspace's New app screen tracks your progress live) →
    `monty install` → edit `monty.config.ts` (zod tables) + `src/routes/` →
-   verify with `monty dev` — the app's Studio state (auto-port, already
-   authenticated, sandboxed data). **You are done when `monty dev` prints
-   the workspace Studio URL and the app works — leave `monty dev`
-   running.** Taking the app Live is the OWNER'S click (Publish in the
-   workspace menu bar); **never run `monty deploy` yourself** unless the
-   user explicitly asks for a direct Live deploy.
+   verify in Studio: run `monty dev` once — if the dev shell is already
+   running (the Monty desktop usually runs it for you) it prints the status,
+   Studio URL, and recent log lines, then **exits immediately**; if nothing
+   is running it starts the shell (start it in the background and move on).
+   Then iterate: edit code → vite hot-reloads → `monty logs -n 50` shows
+   whether it compiled and any browser errors. **You are done when
+   `monty dev` reports `state: online` (or prints the Studio URL on a fresh
+   start) and the app works.** Re-running `monty dev` is always safe — it
+   attaches, prints status, and exits. Never try to run a second dev
+   *server* for the same app (attach handles this for you) and never kill a
+   dev shell you didn't start; `monty dev --takeover` is the only sanctioned
+   restart when a session is wedged. Taking the app Live is the OWNER'S
+   click (Publish in the workspace menu bar); **never run `monty deploy`
+   yourself** unless the user explicitly asks for a direct Live deploy.
 3. **Everything through the CLI.** `monty install`, `monty build`,
    `monty typecheck`, `monty dev`, `monty deploy` — never run vite, tsc,
    pnpm, or npm scripts directly. `monty dev` auto-picks a free port and
-   prints it; `monty typecheck` builds first when needed.
+   prints it; `monty typecheck` builds first when needed. `monty logs`
+   (add `-f` to follow) is how you read the dev shell's output — vite build
+   errors, browser errors, and publish results all land there.
 4. **One import surface:** `@montytools/sdk` (`defineApp`, zod) and
    `@montytools/sdk/react` (hooks: `useList`, `useInsert`, …). Never import
    Clerk or Convex directly; never fetch external APIs from app code — the
@@ -46,7 +59,7 @@ mean something else on this platform.
 7. **Errors are instructions.** Every failure prints
    `[MontyError CODE] Fix: …` — do exactly what the Fix says; don't guess.
    Typecheck failures block deploy by design.
-8. **Verify before publish.** `monty dev` writes to the `#dev` Studio
+8. **Verify before publish.** The dev shell writes to the `#dev` Studio
    sandbox — Live team records are never touched, so exercise the app for
    real.
 
@@ -55,10 +68,11 @@ mean something else on this platform.
 | command | purpose |
 |---|---|
 | `monty login` | browser sign-in (loopback authorize), once per machine |
-| `monty create <slug>` | stamp a new app into `~/Monty/<slug>` |
+| `monty create <slug>` | register the app in the workspace + stamp it into `~/.monty/apps/<id>` (needs login) |
 | `monty current` / `select` / `apps` | where am I / jump to app / list local |
 | `monty install` / `build` / `typecheck` | full lifecycle via the CLI — no raw pnpm/vite/tsc |
-| `monty dev` | run the app in Studio (auto-picks a free port), sandboxed data, auto-auth |
+| `monty dev` | run the app in Studio, or attach to an already-running session (auto-port, sandboxed data, auto-auth) |
+| `monty logs [-n N] [-f]` | read/follow the dev shell log — the debugging window after every edit |
 | `monty add <name…>` | install curated shadcn components |
 | `monty deploy` | build + typecheck + upload straight to Live (owner escape hatch) |
 | `monty skills` | (re)install this skill for your agent |

package/template/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "allow": ["Bash(monty:*)", "Edit(**)", "Write(**)"]
+  }
+}

package/template/AGENTS.md

@@ -10,8 +10,8 @@ Folders are managed for you: this app lives in `~/Monty/<slug>`. `monty current`
 
 | File | What it is |
 |---|---|
-| `monty.config.ts` | Your data schema — plain zod. The ONLY place data shapes are defined. Also `name` + `icon` (any [lucide](https://lucide.dev/icons) icon name, e.g. `"receipt"`, `"users"`) — Monty renders your app's logo tile from it. |
-| `src/routes/` | Your UI — TanStack Router file routes (`index.tsx` = `/`). |
+| `monty.config.ts` | Your data schema — plain zod. The ONLY place data shapes are defined. Also `name` + `icon` (any [Tabler](https://tabler.io/icons) icon name, e.g. `"receipt"`, `"users"`) — Monty renders your app's logo tile from it. |
+| `src/routes/` | Your UI — TanStack Router file routes (`index.tsx` = `/`). The starter `index.tsx` is a blank-canvas placeholder — replace it with the real app. |
 | `src/main.tsx` | Wiring. Do not edit. |
 
 ## Rules (violations break the app)
@@ -110,6 +110,63 @@ Every platform error is one line shaped like:
 | `UNAUTHENTICATED` / `NO_ACTIVE_WORKSPACE` | App isn't running through the Monty host/dev shell. |
 | `MISSING_ENV` / `NO_PROVIDER` | `.env.local` or the `<MontyProvider>` in `main.tsx` was removed. |
 
+## Server code (optional): functions, public endpoints, schedules
+
+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
+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).
+
+```ts
+// server/index.ts
+import type { MontyFnContext, MontyPublicRequest } from "@montytools/sdk/server";
+
+// 1) App-called: invoke from the UI with useServerFn.
+export async function score(args: { sessionId: string }, ctx: MontyFnContext) {
+  const weights = await ctx.records.list("scoring");   // hidden table — fine here
+  return { verdict: weights.length > 0 ? "ok" : "empty" };
+}
+
+// 2) PUBLIC endpoint — declared in monty.config.ts `publicFns: ["stripe"]`,
+// then ANYONE on the internet can call GET/POST /__monty/public/stripe.
+// Verify a signature from ctx.secrets against the RAW req.body before
+// trusting anything; return { status, body?, contentType? } to control the
+// response (or return data for 200 JSON, or nothing for {"ok":true}).
+export async function stripe(req: MontyPublicRequest, ctx: MontyFnContext) {
+  if (!verify(req.headers["stripe-signature"], req.body, ctx.secrets.STRIPE_WEBHOOK_SECRET)) {
+    return { status: 401, body: "bad signature" };
+  }
+  await ctx.records.insert("payments", JSON.parse(req.body));
+  return { status: 200, body: "ok" };
+}
+
+// 3) SCHEDULED — declared in monty.config.ts `schedule: { digest: "0 9 * * *" }`
+// (5-field cron, UTC; max 3). Runs as digest({}, ctx) with
+// ctx.viewer = { lane: "schedule", cron }. Make it idempotent — re-runs happen.
+export async function digest(_args: Record<string, unknown>, ctx: MontyFnContext) { /* … */ }
+
+// 4) onEvent — reserved name: the platform calls it after every accepted
+// track() event. Forward to Slack/Meta/PostHog/your CRM here, with your keys.
+export async function onEvent(event: { name: string }, ctx: MontyFnContext) { /* … */ }
+```
+
+From the UI: `const score = useServerFn<Result>(app, "score"); await score({ sessionId })`.
+Public functions are NOT callable through `useServerFn` — only at their
+`/__monty/public/<name>` URL (and vice versa: undeclared functions are never
+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`.
+
+**Studio 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.
+
 ## Dev loop
 
 Everything goes through the `monty` CLI — never run vite, tsc, pnpm, or npm

package/template/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.monty/
+.env.local
+.env

package/template/index.html

@@ -3,10 +3,21 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Expenses</title>
+    <title>New app</title>
   </head>
   <body>
-    <div id="root"></div>
+    <div id="root">
+      <!-- Boot splash: the first paint, shown while the JS loads. React
+           replaces it with the SDK's identical MontySplash, so a cold open
+           is one continuous visual. If you theme the app dark-only, change
+           the background below to match. -->
+      <style>
+        @keyframes monty-pulse { 0%, 100% { opacity: 1 } 50% { opacity: .25 } }
+      </style>
+      <div style="display: grid; place-items: center; min-height: 100vh; background: oklch(1 0 0)">
+        <div style="width: 10px; height: 10px; border-radius: 999px; background: #999; animation: monty-pulse 1.2s ease-in-out infinite"></div>
+      </div>
+    </div>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

package/template/monty.config.ts

@@ -1,20 +1,21 @@
-import { z } from "zod";
 import { defineApp } from "@montytools/sdk";
 
 // This file is the ONLY place data shapes are defined. Edit it, save, and the
-// typed hooks in your components update immediately.
+// typed hooks in your components update immediately. The starter ships with no
+// tables — declare each one as a zod object as the app needs it, e.g.:
+//
+//   import { z } from "zod";
+//   tables: {
+//     tasks: z.object({
+//       title: z.string().min(1),
+//       done: z.boolean().default(false),
+//     }),
+//   },
 export const app = defineApp({
-  slug: "expenses",
-  name: "Expenses",
-  icon: "receipt",
-  tables: {
-    expenses: z.object({
-      title: z.string().min(1),
-      amount: z.number().positive(),
-      status: z.enum(["draft", "submitted", "approved"]).default("draft"),
-      assigneeId: z.string().optional(), // a workspace member's userId (from useMembers)
-    }),
-  },
+  slug: "new-app",
+  name: "New app",
+  icon: "layout-grid",
+  tables: {},
 });
 
 export type App = typeof app;

package/template/package.json

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

package/template/src/main.tsx

@@ -1,13 +1,15 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { RouterProvider, createRouter } from "@tanstack/react-router";
-import { MontyProvider } from "@montytools/sdk/react";
+import { MontyProvider, MontySplash } from "@montytools/sdk/react";
 
 import "./index.css";
 import { app } from "../monty.config";
 import { routeTree } from "./routeTree.gen";
 
-const router = createRouter({ routeTree });
+// defaultPendingComponent: lazy route chunks show the same splash the rest
+// of the boot uses instead of flashing blank.
+const router = createRouter({ routeTree, defaultPendingComponent: MontySplash });
 
 declare module "@tanstack/react-router" {
   interface Register {

package/template/src/routes/index.tsx

@@ -1,263 +1,38 @@
-import { useState } from "react";
 import { createFileRoute } from "@tanstack/react-router";
-import { CheckIcon, PlusIcon, TrashIcon } from "lucide-react";
+import { Sparkles } from "lucide-react";
 
-import {
-  useInsert,
-  useList,
-  useMembers,
-  useRemove,
-  useUpdate,
-} from "@montytools/sdk/react";
-import { Badge } from "@/components/ui/badge";
-import { Button } from "@/components/ui/button";
-import {
-  Card,
-  CardContent,
-  CardHeader,
-  CardTitle,
-} from "@/components/ui/card";
 import {
   Empty,
   EmptyDescription,
   EmptyHeader,
+  EmptyMedia,
   EmptyTitle,
 } from "@/components/ui/empty";
-import {
-  Field,
-  FieldError,
-  FieldGroup,
-  FieldLabel,
-} from "@/components/ui/field";
-import { Input } from "@/components/ui/input";
-import {
-  Select,
-  SelectContent,
-  SelectGroup,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@/components/ui/select";
-import { Spinner } from "@/components/ui/spinner";
-import {
-  Table,
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-} from "@/components/ui/table";
 
 import { app } from "../../monty.config";
 
 export const Route = createFileRoute("/")({
-  component: ExpenseBoard,
+  component: BlankCanvas,
 });
 
-type Status = "draft" | "submitted" | "approved";
-const NEXT_STATUS: Record<Status, Status | null> = {
-  draft: "submitted",
-  submitted: "approved",
-  approved: null,
-};
-const STATUS_VARIANT = {
-  draft: "secondary",
-  submitted: "default",
-  approved: "outline",
-} as const;
-
-function ExpenseBoard() {
-  const [statusFilter, setStatusFilter] = useState<Status | "all">("all");
-
-  // Live, typed, reactive — a teammate's write re-renders this list.
-  const { data: expenses, status, loadMore } = useList(app, "expenses", {
-    filter: statusFilter === "all" ? undefined : { status: statusFilter },
-    order: "desc",
-    limit: 50,
-  });
-  const members = useMembers();
-  const insert = useInsert(app, "expenses");
-  const update = useUpdate(app, "expenses");
-  const remove = useRemove(app, "expenses");
-
-  const [title, setTitle] = useState("");
-  const [amount, setAmount] = useState("");
-  // "__none" sentinel: a controlled Radix Select must never flip to undefined
-  // (it goes uncontrolled and keeps displaying the stale selection).
-  const [assigneeId, setAssigneeId] = useState("__none");
-  const [formError, setFormError] = useState<string | null>(null);
-
-  async function addExpense() {
-    setFormError(null);
-    try {
-      await insert({
-        title,
-        amount: Number(amount),
-        ...(assigneeId !== "__none" ? { assigneeId } : {}),
-      });
-      setTitle("");
-      setAmount("");
-      setAssigneeId("__none");
-    } catch (error) {
-      setFormError(error instanceof Error ? error.message : String(error));
-    }
-  }
-
-  const memberName = (userId?: string) =>
-    members?.find((m) => m.userId === userId)?.name ?? "—";
-
+// The starter ships empty on purpose: this page is what the person watching
+// the preview sees while their agent builds the first version. Replace this
+// whole route with the real app — don't build around it.
+function BlankCanvas() {
   return (
-    <main className="mx-auto flex max-w-4xl flex-col gap-6 p-6">
-      <header className="flex items-center justify-between">
-        <h1 className="text-2xl font-semibold">Expenses</h1>
-        <Select
-          value={statusFilter}
-          onValueChange={(v) => setStatusFilter(v as Status | "all")}
-        >
-          <SelectTrigger className="w-40">
-            <SelectValue placeholder="Filter status" />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectGroup>
-              <SelectItem value="all">All statuses</SelectItem>
-              <SelectItem value="draft">Draft</SelectItem>
-              <SelectItem value="submitted">Submitted</SelectItem>
-              <SelectItem value="approved">Approved</SelectItem>
-            </SelectGroup>
-          </SelectContent>
-        </Select>
-      </header>
-
-      <Card>
-        <CardHeader>
-          <CardTitle>Add expense</CardTitle>
-        </CardHeader>
-        <CardContent>
-          <FieldGroup>
-            <div className="flex flex-wrap items-end gap-4">
-              <Field className="min-w-48 flex-1">
-                <FieldLabel htmlFor="title">Title</FieldLabel>
-                <Input
-                  id="title"
-                  value={title}
-                  onChange={(e) => setTitle(e.target.value)}
-                  placeholder="Team lunch"
-                />
-              </Field>
-              <Field className="w-32">
-                <FieldLabel htmlFor="amount">Amount</FieldLabel>
-                <Input
-                  id="amount"
-                  type="number"
-                  value={amount}
-                  onChange={(e) => setAmount(e.target.value)}
-                  placeholder="42.50"
-                />
-              </Field>
-              <Field className="w-48">
-                <FieldLabel>Assignee</FieldLabel>
-                <Select value={assigneeId} onValueChange={setAssigneeId}>
-                  <SelectTrigger>
-                    <SelectValue placeholder="Unassigned" />
-                  </SelectTrigger>
-                  <SelectContent>
-                    <SelectGroup>
-                      <SelectItem value="__none">Unassigned</SelectItem>
-                      {(members ?? []).map((m) => (
-                        <SelectItem key={m.userId} value={m.userId}>
-                          {m.name}
-                        </SelectItem>
-                      ))}
-                    </SelectGroup>
-                  </SelectContent>
-                </Select>
-              </Field>
-              <Button onClick={addExpense}>
-                <PlusIcon data-icon="inline-start" />
-                Add
-              </Button>
-            </div>
-            {formError && <FieldError>{formError}</FieldError>}
-          </FieldGroup>
-        </CardContent>
-      </Card>
-
-      {status === "LoadingFirstPage" && expenses.length === 0 ? (
-        <div className="flex justify-center p-12">
-          <Spinner />
-        </div>
-      ) : expenses.length === 0 ? (
-        <Empty>
-          <EmptyHeader>
-            <EmptyTitle>No expenses yet</EmptyTitle>
-            <EmptyDescription>
-              Add the first one above — it appears for every teammate in real
-              time.
-            </EmptyDescription>
-          </EmptyHeader>
-        </Empty>
-      ) : (
-        <Card>
-          <CardContent>
-            <Table>
-              <TableHeader>
-                <TableRow>
-                  <TableHead>Title</TableHead>
-                  <TableHead>Amount</TableHead>
-                  <TableHead>Status</TableHead>
-                  <TableHead>Assignee</TableHead>
-                  <TableHead className="w-40" />
-                </TableRow>
-              </TableHeader>
-              <TableBody>
-                {expenses.map((e) => (
-                  <TableRow key={e._id}>
-                    <TableCell className="font-medium">{e.title}</TableCell>
-                    <TableCell>${e.amount.toFixed(2)}</TableCell>
-                    <TableCell>
-                      <Badge variant={STATUS_VARIANT[e.status]}>
-                        {e.status}
-                      </Badge>
-                    </TableCell>
-                    <TableCell>{memberName(e.assigneeId)}</TableCell>
-                    <TableCell>
-                      <div className="flex justify-end gap-2">
-                        {NEXT_STATUS[e.status] && (
-                          <Button
-                            variant="outline"
-                            size="sm"
-                            onClick={() =>
-                              update(e._id, { status: NEXT_STATUS[e.status]! })
-                            }
-                          >
-                            <CheckIcon data-icon="inline-start" />
-                            {NEXT_STATUS[e.status]}
-                          </Button>
-                        )}
-                        <Button
-                          variant="ghost"
-                          size="sm"
-                          onClick={() => remove(e._id)}
-                        >
-                          <TrashIcon data-icon="inline-start" />
-                          Delete
-                        </Button>
-                      </div>
-                    </TableCell>
-                  </TableRow>
-                ))}
-              </TableBody>
-            </Table>
-            {status === "CanLoadMore" && (
-              <div className="flex justify-center pt-4">
-                <Button variant="ghost" onClick={() => loadMore()}>
-                  Load more
-                </Button>
-              </div>
-            )}
-          </CardContent>
-        </Card>
-      )}
+    <main className="grid min-h-dvh place-items-center p-6">
+      <Empty>
+        <EmptyHeader>
+          <EmptyMedia variant="icon">
+            <Sparkles />
+          </EmptyMedia>
+          <EmptyTitle>{app.name} is a blank canvas</EmptyTitle>
+          <EmptyDescription>
+            Your agent builds the first version right on this page — changes
+            appear live as it works.
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
     </main>
   );
 }