@montytools/cli 0.4.0 → 0.4.2

package/bin/monty.mjs

@@ -11,13 +11,20 @@ import { StringDecoder } from "node:string_decoder";
 import { createServer } from "node:http";
 import { connect as netConnect } from "node:net";
 import { homedir } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { CATALOG, REGISTRIES } from "./catalog.mjs";
 import { CompileError, compileAppConfig } from "../lib/compile.mjs";
 
-const CONFIG_DIR = join(homedir(), ".monty");
+// MONTY_HOME overrides the state root (default ~/.monty): config.json,
+// apps/, and desktop.json all live under it. This is how a second, isolated
+// Monty state coexists on one machine — the desktop's dev channel points it
+// at ~/.monty-dev so platform development never touches the real state. A
+// custom root is a sandbox: the legacy visible home (~/Monty) is not scanned.
+const CONFIG_DIR = process.env.MONTY_HOME
+  ? resolve(process.env.MONTY_HOME)
+  : join(homedir(), ".monty");
 const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 const DEFAULT_HOST = "https://usemonty.dev";
 const DEV_SESSION_HEARTBEAT_MS = 30_000;
@@ -336,7 +343,11 @@ function scanAppsHome(root) {
 }
 
 function listLocalApps() {
-  return [...scanAppsHome(MONTY_HOME), ...scanAppsHome(LEGACY_MONTY_HOME)];
+  // A MONTY_HOME sandbox lists only its own apps — leaking the legacy home
+  // into an isolated root would defeat the isolation.
+  return process.env.MONTY_HOME
+    ? scanAppsHome(MONTY_HOME)
+    : [...scanAppsHome(MONTY_HOME), ...scanAppsHome(LEGACY_MONTY_HOME)];
 }
 
 function current() {
@@ -661,6 +672,19 @@ async function create() {
     },
   });
 
+  // The bundled template ships `.gitignore` as `gitignore` (npm-packlist
+  // hard-excludes the real name from tarballs); the in-repo template has the
+  // real file. Normalize, and backfill for bundles that carried neither —
+  // without a .gitignore, tailwind v4's content scan includes .monty/ and
+  // full-reloads Studio on every dev.json touch.
+  const gitignorePath = join(target, ".gitignore");
+  if (existsSync(join(target, "gitignore"))) {
+    renameSync(join(target, "gitignore"), gitignorePath);
+  }
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, "node_modules/\ndist/\n.monty/\n.env.local\n.env\n");
+  }
+
   // Stamp identity into the copied files. The id line is INSERTED (the
   // template ships without one — only real creates have a server id).
   const configPath = join(target, "monty.config.ts");
@@ -795,7 +819,7 @@ async function freePort(start) {
 // Apps pin @montytools/sdk at scaffold time and go stale — the CLI knows the
 // minimum SDK its workflows need (e.g. tunnel-host allowlisting lives in the
 // SDK's vite plugin) and upgrades the app automatically before dev/deploy.
-const MIN_SDK = "0.1.3";
+const MIN_SDK = "0.1.5";
 const SDK_VITE_CACHE_STAMP = "sdk-vite-cache-version";
 
 function installedSdkVersion(appDir) {
@@ -2260,6 +2284,265 @@ function cronFieldMatches(field, value, [lo, hi], idx) {
   return false;
 }
 
+// ── monty data ─────────────────────────────────────────────────────────────
+// The agent verbs for OPERATING an app: read and write its records from any
+// terminal — no browser, no dev session. Auth is the mk_ key exchanged at
+// /api/dev-token for a 5-minute workspace token (member lane, org_id from
+// the verified JWT), then the 6 public records functions over Convex's HTTP
+// API. `app` picks the records namespace: the plain slug is Live; --studio
+// targets "{slug}#dev" (the Studio sandbox — same wire literal the dev
+// shell uses). Results are ONE JSON document on stdout so agents can pipe.
+
+const DATA_VALUE_FLAGS = new Set(["app", "filter", "order", "limit", "cursor", "data", "key", "unset", "host"]);
+
+// rest, minus flags AND their values — `monty data list leads --app crm`
+// must not read "crm" as a positional. Boolean flags (--studio) have no
+// value and are skipped alone.
+function dataPositionals() {
+  const out = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a.startsWith("--")) {
+      if (DATA_VALUE_FLAGS.has(a.slice(2))) i++;
+      continue;
+    }
+    out.push(a);
+  }
+  return out;
+}
+
+function parseJsonFlag(name) {
+  const raw = flag(name);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    fail("BAD_JSON", `--${name} is not valid JSON. Quote the whole value in single quotes, e.g. --${name} '{"field":"value"}'. Got: ${raw.slice(0, 120)}`);
+  }
+}
+
+// Which records namespace a data verb targets. Slug from --app or the
+// surrounding app folder; existence is decided server-side (an unknown slug
+// simply has zero records — list makes that visible immediately).
+function resolveDataApp() {
+  const explicit = flag("app");
+  const root = findAppRoot(process.cwd());
+  const slug = explicit ?? (root ? readSlugFromConfig(root) : null);
+  if (!slug) {
+    fail("NO_APP", "Say which app: pass --app <slug>, or run inside an app folder. `monty apps` lists local apps.");
+  }
+  return rest.includes("--studio") ? `${slug}#dev` : slug;
+}
+
+// mk_ key → { convexUrl, token }. The token is workspace-scoped and expires
+// in 5 minutes — minted fresh per invocation, never stored.
+async function dataAuth() {
+  const { host, key } = loadConfig();
+  if (!key) fail("NOT_LOGGED_IN", `Reading and writing app data needs your workspace (${host}). Run \`monty login\` first.`);
+  let convexUrl = null;
+  try {
+    convexUrl = (await fetch(`${host}/api/config`).then((r) => r.json()))?.convexUrl;
+  } catch { /* handled below */ }
+  if (!convexUrl) fail("HOST_UNREACHABLE", `Could not read ${host}/api/config — is the host up and the network reachable?`);
+  const r = await fetch(`${host}/api/dev-token`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${key}` },
+  });
+  const body = await r.json().catch(() => null);
+  if (!r.ok || !body?.token) {
+    fail(body?.code ?? `HTTP_${r.status}`, body?.fix ?? "Minting a workspace token failed. Run `monty login`, then retry.");
+  }
+  return { convexUrl, token: body.token };
+}
+
+// One records function over Convex's public HTTP API (plain-JSON format —
+// app data is JSON by construction, no convex encoding needed). ConvexError
+// payloads carry { code, fix } and surface verbatim: errors stay
+// instructions in the terminal the agent is watching.
+async function callRecords(kind, fn, args, auth) {
+  let body = null;
+  try {
+    const r = await fetch(`${auth.convexUrl}/api/${kind}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${auth.token}` },
+      body: JSON.stringify({ path: `records:${fn}`, args, format: "json" }),
+    });
+    body = await r.json().catch(() => null);
+  } catch { /* handled below */ }
+  if (!body) fail("CONVEX_UNREACHABLE", `The data backend at ${auth.convexUrl} did not answer — check the network and retry.`);
+  if (body.status !== "success") {
+    const d = body.errorData;
+    if (d && typeof d === "object" && d.code) fail(d.code, d.fix ?? body.errorMessage ?? "See the error code.");
+    fail("CONVEX_ERROR", body.errorMessage ?? "Unknown data-layer error — retry; if it persists, report it.");
+  }
+  return body.value;
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+// The documented row shape everywhere on the platform (SDK hooks, server
+// functions) is FLATTENED: app fields at the top level + the four system
+// fields. Mirror it here — and don't echo workspaceId/appId/table back;
+// scope is the caller's own arguments, not row payload.
+function flattenRow(doc) {
+  if (!doc) return null;
+  return {
+    ...doc.data,
+    _id: doc._id,
+    _creationTime: doc._creationTime,
+    updatedAt: doc.updatedAt,
+    createdBy: doc.createdBy,
+  };
+}
+
+function dataUsage() {
+  console.log("usage: monty data <verb> [table] [flags]     read/write an app's Live records (add --studio for the Studio sandbox)");
+  console.log("  schema  [table]                             the app's table shapes (from local monty.config.ts — `monty pull` first if needed)");
+  console.log("  list    <table> [--filter '{\"k\":\"v\"}'] [--order asc|desc] [--limit N] [--cursor C]");
+  console.log("  get     <table> <id>");
+  console.log("  insert  <table> --data '<json|[json,…]>'");
+  console.log("  update  <table> <id> --data '<json>' [--unset field,field]");
+  console.log("  upsert  <table> --key <field[,field]> --data '<json|[json,…]>'   find-or-create matched on the key fields (idempotent)");
+  console.log("  remove  <table> <id>");
+  console.log("target: --app <slug> (or run inside the app folder); default is LIVE data — --studio targets the sandbox");
+  process.exit(1);
+}
+
+async function data() {
+  const [verb, table, id] = dataPositionals();
+
+  if (verb === "schema") {
+    // Shape comes from the LOCAL source checkout (compiled through the real
+    // pipeline) — the same monty.config.ts that defines what the app stores.
+    const explicit = flag("app");
+    const root = explicit
+      ? (listLocalApps().find((a) => a.slug === explicit || a.id === explicit)?.path ?? null)
+      : findAppRoot(process.cwd());
+    if (!root) {
+      fail("APP_NOT_LOCAL", explicit
+        ? `No local source for "${explicit}" on this machine — run \`monty pull ${explicit}\` first, or cd into the app folder.`
+        : "Not inside an app folder. Pass --app <slug> (needs the source pulled locally) or cd into the app.");
+    }
+    let meta;
+    try {
+      meta = await compileAppConfig(root);
+    } catch (e) {
+      if (e instanceof CompileError) fail(e.code, e.fix);
+      throw e;
+    }
+    const tables = meta.schemaJson?.tables ?? {};
+    if (table !== undefined) {
+      if (!tables[table]) {
+        fail("NO_SUCH_TABLE", `App "${meta.slug}" has no table "${table}". Tables: ${Object.keys(tables).join(", ") || "(none)"}.`);
+      }
+      printJson({ app: meta.slug, table, schema: tables[table] });
+    } else {
+      printJson({ app: meta.slug, tables });
+    }
+    return;
+  }
+
+  const VERBS = new Set(["list", "get", "insert", "update", "upsert", "remove"]);
+  if (!verb || !VERBS.has(verb)) dataUsage();
+  if (!table) fail("MISSING_TABLE", `\`monty data ${verb}\` needs a table name: monty data ${verb} <table> … (\`monty data schema\` lists tables).`);
+
+  const app = resolveDataApp();
+  const auth = await dataAuth();
+
+  switch (verb) {
+    case "list": {
+      const filter = parseJsonFlag("filter");
+      const order = flag("order");
+      if (order !== undefined && order !== "asc" && order !== "desc") {
+        fail("BAD_ORDER", `--order must be "asc" or "desc" (default desc, newest first). Got: ${order}`);
+      }
+      const limit = Math.min(Math.max(parseInt(flag("limit") ?? "100", 10) || 100, 1), 1024);
+      const value = await callRecords("query", "list", {
+        app,
+        table,
+        ...(filter !== undefined ? { filter } : {}),
+        ...(order !== undefined ? { order } : {}),
+        paginationOpts: { numItems: limit, cursor: flag("cursor") ?? null },
+      }, auth);
+      printJson({
+        rows: value.page.map(flattenRow),
+        count: value.page.length,
+        // A non-null cursor means MORE rows exist: repeat with --cursor <c>.
+        cursor: value.isDone ? null : value.continueCursor,
+      });
+      return;
+    }
+    case "get": {
+      if (!id) fail("MISSING_ID", "Usage: monty data get <table> <id> — ids come from list on the same table.");
+      printJson(flattenRow(await callRecords("query", "get", { app, table, id }, auth)));
+      return;
+    }
+    case "insert": {
+      const input = parseJsonFlag("data");
+      if (input === undefined) fail("MISSING_DATA", `Usage: monty data insert ${table} --data '{"field":"value"}' — an array inserts each element.`);
+      const rows = Array.isArray(input) ? input : [input];
+      const ids = [];
+      for (const row of rows) {
+        ids.push(await callRecords("mutation", "insert", { app, table, data: row }, auth));
+      }
+      printJson(Array.isArray(input) ? { ids } : { id: ids[0] });
+      return;
+    }
+    case "update": {
+      if (!id) fail("MISSING_ID", "Usage: monty data update <table> <id> --data '{…}' — ids come from list/get on the same table.");
+      const patch = parseJsonFlag("data");
+      if (patch === undefined) fail("MISSING_DATA", `Usage: monty data update ${table} ${id} --data '{"field":"newValue"}' (shallow-merged; --unset a,b removes fields).`);
+      const unsetRaw = flag("unset");
+      await callRecords("mutation", "update", {
+        app,
+        table,
+        id,
+        data: patch,
+        ...(unsetRaw ? { unset: unsetRaw.split(",").map((s) => s.trim()).filter(Boolean) } : {}),
+      }, auth);
+      printJson({ ok: true, id });
+      return;
+    }
+    case "upsert": {
+      // --key names the FIELDS that identify a row (e.g. --key linkedinUrl);
+      // values come from each data row, so one flag serves single and batch
+      // writes alike — and re-running an import never duplicates.
+      const keyFields = (flag("key") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+      if (keyFields.length === 0) {
+        fail("MISSING_KEY", `Usage: monty data upsert ${table} --key <field[,field]> --data '{…}' — key fields identify the row to match on.`);
+      }
+      const input = parseJsonFlag("data");
+      if (input === undefined) fail("MISSING_DATA", `Usage: monty data upsert ${table} --key ${keyFields.join(",")} --data '{"${keyFields[0]}":"…", …}' — an array upserts each element.`);
+      const rows = Array.isArray(input) ? input : [input];
+      const ids = [];
+      for (const row of rows) {
+        const key = {};
+        for (const f of keyFields) {
+          if (row[f] === undefined) {
+            fail("MISSING_KEY_FIELD", `A data row is missing key field "${f}" — every row must carry its own key values. Row: ${JSON.stringify(row).slice(0, 120)}`);
+          }
+          key[f] = row[f];
+        }
+        // patch = the caller's fields (merged over an existing row); full =
+        // the stored row on insert. The CLI applies no zod defaults, so they
+        // are the same object here — `monty data schema` shows what a
+        // complete row needs.
+        ids.push(await callRecords("mutation", "upsert", { app, table, key, patch: row, full: row }, auth));
+      }
+      printJson(Array.isArray(input) ? { ids } : { id: ids[0] });
+      return;
+    }
+    case "remove": {
+      if (!id) fail("MISSING_ID", "Usage: monty data remove <table> <id> — ids come from list/get on the same table.");
+      await callRecords("mutation", "remove", { app, table, id }, auth);
+      printJson({ ok: true, id, removed: true });
+      return;
+    }
+  }
+}
+
 // ── dispatch ───────────────────────────────────────────────────────────────
 // Keep agent skills fresh on every invocation (user level + current app).
 // `dev` and `logs` skip the refresh here: attach and log reads must stay
@@ -2327,11 +2610,14 @@ switch (command) {
   case "deploy":
     await deploy();
     break;
+  case "data":
+    await data();
+    break;
   case "secret":
     await secret();
     break;
   default:
-    console.log("usage: monty <login|create|pull|commit|log|current|select|apps|install|dev|logs|build|typecheck|add|components|docs|deploy|skills>");
+    console.log("usage: monty <login|create|pull|commit|log|current|select|apps|install|dev|logs|build|typecheck|add|components|docs|deploy|data|skills>");
     console.log("  login       [--host <url>] [--key <mk_...>]  sign in (opens your browser to authorize)");
     console.log("  create      <slug> [--name N] [--icon I] [--build ID]  register + stamp a new app into ~/.monty/apps/<id> (needs login)");
     console.log("  pull        <slug> [--version H] [--force]  restore the app's source snapshot (latest, or one from `monty log`)");
@@ -2349,6 +2635,7 @@ switch (command) {
     console.log("  build                                       production build (vite, via monty)");
     console.log("  typecheck                                   typecheck (builds first if needed)");
     console.log("  deploy                                      build + upload this app straight to Live");
+    console.log("  data        <verb> [table] [flags]          read/write an app's records from the terminal (`monty data` for verbs)");
     console.log("  skills                                      install/refresh the agent build skill");
     process.exit(command ? 1 : 0);
 }

package/package.json

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

package/skills/monty-operate/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: monty-operate
+description: Operate a team's Monty workspace apps from the terminal — read and write a Live app's records with `monty data`. Use whenever the task is to put data INTO an existing Monty app or read data from one: add leads to a CRM, import scraped or external data, update or clean up records, check what an app currently stores, or automate recurring work against apps on usemonty.dev. Building or changing an app itself is monty-build, not this.
+---
+
+# Operating Monty apps
+
+A Monty workspace runs internal apps (CRMs, trackers, dashboards) whose data
+lives on the platform. `monty data` is how you — the operating agent — read
+and write that data directly from the terminal: no browser session, no dev
+server. You do the work (browse, scrape, decide, transform); the app is
+where the results land, and open app tabs update live as you write.
+
+Two data channels per app: **Live** (the team's real records — the default
+target) and the **Studio sandbox** (`--studio` — development data, never
+seen by the team). Writing to Live is normal operating work; that is what
+this command is for.
+
+## The loop
+
+1. **Find the app.** `monty apps` lists local apps; run inside the app
+   folder (`cd "$(monty select <slug>)"`) or pass `--app <slug>` to every
+   command.
+2. **Learn the shape — never guess.** `monty data schema` prints every
+   table; `monty data schema <table>` one table. (Schema compiles from the
+   local source — if the app isn't on this machine, `monty pull <slug>`
+   first.)
+3. **See what's there.** `monty data list <table> --limit 20` before
+   writing: learn the field conventions from real rows and avoid duplicating
+   what exists.
+4. **Write.** Prefer `upsert` with a `--key` for anything imported or
+   scraped; `insert` only for rows that are genuinely new by construction.
+5. **Verify.** `list`/`get` the rows you touched; report counts (added,
+   updated, skipped) with specifics.
+
+## Rules
+
+1. **Imports are idempotent.** Any repeatable job (scraping, syncing,
+   importing) writes with
+   `monty data upsert <table> --key <identityField> --data '[…]'` — the key
+   names the field(s) that identify a row (a URL, an email, an external id),
+   values come from each row, and re-running never duplicates.
+2. **Schema first, rows second.** Field names come from
+   `monty data schema`, exact spelling. The server stores what you send —
+   a misspelled field is silently a new field, not an error.
+3. **Live is the default and that's correct** — operating work targets the
+   team's real data. Use `--studio` only when explicitly rehearsing.
+   Destructive verbs (`remove`, bulk `update`) on Live deserve a
+   confirmation with the user unless they clearly asked for the cleanup.
+4. **Batch with arrays.** `--data` accepts a single object or an array;
+   arrays write row by row and return all ids in order.
+5. **Paginate honestly.** `list` returns `"cursor": null` when complete; a
+   non-null cursor means more rows exist — repeat with `--cursor <c>`
+   before claiming totals.
+6. **Errors are instructions.** Every failure prints
+   `[MontyError CODE] Fix: …` — do what the Fix says. `NOT_LOGGED_IN` means
+   run `monty login` (once per machine); `NOT_FOUND` on an id means it came
+   from the wrong table or a stale listing — re-`list`, never retry blind.
+7. **Rows come back flattened**: your fields at the top level plus system
+   fields `_id`, `_creationTime`, `updatedAt`, `createdBy`. System fields
+   are read-only — never send them in `--data`.
+
+## Command reference
+
+| command | purpose |
+|---|---|
+| `monty data schema [table]` | table shapes from the app's config — read this before any write |
+| `monty data list <table> [--filter '{"k":"v"}'] [--order asc\|desc] [--limit N] [--cursor C]` | newest-first rows; filter is exact-match on fields |
+| `monty data get <table> <id>` | one row (null if the id isn't in this table) |
+| `monty data insert <table> --data '<json\|[json,…]>'` | create rows |
+| `monty data upsert <table> --key <field[,field]> --data '<json\|[json,…]>'` | find-or-create matched on the key fields — the idempotent write |
+| `monty data update <table> <id> --data '<json>' [--unset a,b]` | shallow-merge onto one row; `--unset` deletes fields |
+| `monty data remove <table> <id>` | delete one row |
+
+All verbs take `--app <slug>` and `--studio`. Output is one JSON document on
+stdout.
+
+## Example: import scraped leads into a CRM app
+
+```sh
+monty data schema leads --app crm                # shape: name, company, title, linkedinUrl, status…
+monty data list leads --app crm --limit 50       # what's already in the pipeline
+# …browse/scrape/decide, then land the batch idempotently:
+monty data upsert leads --app crm --key linkedinUrl --data '[
+  {"name":"Dana Reeve","company":"Acme","title":"VP Ops","linkedinUrl":"https://linkedin.com/in/dana-r","status":"new"},
+  {"name":"Sam Ortiz","company":"Initech","title":"Head of RevOps","linkedinUrl":"https://linkedin.com/in/sam-o","status":"new"}
+]'
+monty data list leads --app crm --filter '{"status":"new"}'   # verify, then report counts
+```

package/template/gitignore

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

package/template/index.html

@@ -6,7 +6,18 @@
     <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/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@fontsource-variable/roboto": "^5.2.10",
-    "@montytools/sdk": "^0.1.4",
+    "@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 {