@montytools/cli 0.4.0 → 0.4.1

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.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TomasMonty/monty-v2.git",

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 {