@montytools/cli 0.5.1 → 0.5.2

package/bin/monty.mjs

@@ -984,7 +984,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.2.1";
+const MIN_SDK = "0.2.2";
 const SDK_VITE_CACHE_STAMP = "sdk-vite-cache-version";
 
 function installedSdkVersion(appDir) {
@@ -2874,7 +2874,7 @@ function cronFieldMatches(field, value, [lo, hi], idx) {
 // API. `app` is the plain slug — every app has ONE set of records.
 // 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"]);
+const DATA_VALUE_FLAGS = new Set(["app", "filter", "order", "limit", "cursor", "data", "key", "unset", "host", "name", "type", "out", "table", "record", "field"]);
 
 // rest, minus flags AND their values — `monty data list leads --app crm`
 // must not read "crm" as a positional. Boolean flags have no value and
@@ -2936,7 +2936,7 @@ async function dataAuth() {
   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 };
+  return { host, convexUrl, token: body.token };
 }
 
 // One records function over Convex's public HTTP API (plain-JSON format —
@@ -2990,10 +2990,57 @@ function dataUsage() {
   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("  upload  <path> [--name N] [--type mime]     store a file (10MB cap); prints the descriptor to put in a `file` field");
+  console.log("          [--table <t> --record <id> --field <f>]   …and set that row's field in the same command");
+  console.log("  download <file-id> [--out path]             fetch a stored file's bytes (id from a row's file field)");
   console.log("target: --app <slug> (or run inside the app folder)");
   process.exit(1);
 }
 
+// Uploads without --type get the MIME their extension implies; unknown
+// extensions stay application/octet-stream (the server stores, never sniffs).
+const MIME_BY_EXT = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif",
+  webp: "image/webp", svg: "image/svg+xml", ico: "image/x-icon",
+  pdf: "application/pdf", json: "application/json", csv: "text/csv",
+  txt: "text/plain", md: "text/markdown", html: "text/html",
+  zip: "application/zip", mp3: "audio/mpeg", wav: "audio/wav",
+  mp4: "video/mp4", webm: "video/webm",
+};
+
+function inferContentType(name) {
+  const ext = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
+  return (ext && MIME_BY_EXT[ext]) || "application/octet-stream";
+}
+
+const DATA_MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+// POST/GET on the host's /api/files — the same rail the SDK file helpers
+// ride, authorized with the invocation's 5-minute workspace token.
+async function callFiles(method, params, auth, app, opts = {}) {
+  const url = new URL("/api/files", auth.host);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+  let r;
+  try {
+    r = await fetch(url, {
+      method,
+      headers: {
+        authorization: `Bearer ${auth.token}`,
+        "x-monty-app": app,
+        ...(opts.contentType ? { "content-type": opts.contentType } : {}),
+      },
+      ...(opts.body !== undefined ? { body: opts.body } : {}),
+    });
+  } catch {
+    fail("HOST_UNREACHABLE", `The file endpoint at ${auth.host} did not answer — check the network and retry.`);
+  }
+  if (!r.ok) {
+    const err = await r.json().catch(() => null);
+    fail(err?.code ?? `HTTP_${r.status}`, err?.fix ?? "The file request failed. Retry; if it persists, report it.");
+  }
+  return r;
+}
+
 async function data() {
   const [verb, table, id] = dataPositionals();
 
@@ -3028,6 +3075,82 @@ async function data() {
     return;
   }
 
+  if (verb === "upload") {
+    // The positional is a file PATH, not a table — the descriptor this
+    // prints is what a `file`-typed field stores; --table/--record/--field
+    // set it on an existing row in the same command.
+    const path = table;
+    if (!path) fail("MISSING_PATH", "Usage: monty data upload <path> [--name N] [--type mime] [--table <t> --record <id> --field <f>].");
+    const attachTable = flag("table");
+    const attachRecord = flag("record");
+    const attachField = flag("field");
+    const attachFlags = [attachTable, attachRecord, attachField].filter((f) => f !== undefined);
+    if (attachFlags.length > 0 && attachFlags.length < 3) {
+      fail("BAD_ATTACH", "Attaching needs all three of --table, --record, and --field — or none (then put the printed descriptor in a file field yourself).");
+    }
+    let bytes;
+    try {
+      bytes = readFileSync(path);
+    } catch {
+      fail("NO_SUCH_FILE", `Could not read "${path}" — check the path.`);
+    }
+    if (bytes.byteLength === 0) fail("EMPTY_FILE", `"${path}" is empty — nothing to upload.`);
+    if (bytes.byteLength > DATA_MAX_FILE_BYTES) {
+      fail("FILE_TOO_LARGE", `Files are limited to ${DATA_MAX_FILE_BYTES} bytes; "${path}" is ${bytes.byteLength}. Compress it first.`);
+    }
+    const name = flag("name") ?? basename(path);
+    const contentType = flag("type") ?? inferContentType(name);
+    const app = resolveDataApp();
+    const auth = await dataAuth();
+    if (attachFlags.length === 3) {
+      // Prove the target row exists BEFORE storing bytes — a failed attach
+      // after the upload would orphan the file.
+      const row = await callRecords("query", "get", { app, table: attachTable, id: attachRecord }, auth);
+      if (!row) fail("NOT_FOUND", `No record "${attachRecord}" in table "${attachTable}" — ids come from \`monty data list ${attachTable}\`.`);
+    }
+    const res = await callFiles("POST", { name }, auth, app, { body: bytes, contentType });
+    const file = await res.json();
+    if (attachFlags.length === 3) {
+      await callRecords("mutation", "update", {
+        app,
+        table: attachTable,
+        id: attachRecord,
+        data: { [attachField]: file },
+      }, auth);
+      printJson({ ok: true, id: attachRecord, field: attachField, file });
+    } else {
+      printJson({ file });
+    }
+    return;
+  }
+
+  if (verb === "download") {
+    // The positional is the file id (a row's file-field descriptor carries
+    // it), not a table.
+    const fileId = table;
+    if (!fileId) fail("MISSING_ID", "Usage: monty data download <file-id> [--out path] — ids come from a row's file field (its `id` key).");
+    const app = resolveDataApp();
+    const auth = await dataAuth();
+    const res = await callFiles("GET", { id: fileId }, auth, app);
+    const disposition = res.headers.get("content-disposition") ?? "";
+    const remoteName = /filename="([^"]+)"/.exec(disposition)?.[1] ?? fileId;
+    const out = flag("out") ?? remoteName;
+    const body = Buffer.from(await res.arrayBuffer());
+    try {
+      writeFileSync(out, body);
+    } catch {
+      fail("WRITE_FAILED", `Could not write to "${out}" — check the path and permissions.`);
+    }
+    printJson({
+      ok: true,
+      path: out,
+      name: remoteName,
+      contentType: res.headers.get("content-type") ?? "application/octet-stream",
+      size: body.byteLength,
+    });
+    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).`);

package/lib/schemaCodegen.mjs

@@ -32,7 +32,8 @@ export function manifestHash(manifest) {
 
 const IMPORTABLE = [
   "defineApp", "formula", "lookup", "montyDate", "montyFileSchema",
-  "montyMember", "montyMoney", "montyPercent", "montyRef", "rollup", "self",
+  "montyMember", "montyMoney", "montyMultiSelect", "montyPercent",
+  "montyPhone", "montyRating", "montyRef", "montySelect", "rollup", "self",
 ];
 
 function fieldsInOrder(section) {
@@ -56,10 +57,20 @@ function storedSource(spec, used) {
       src = `montyRef(${JSON.stringify(spec.table)})`;
       break;
     case "enum":
-      src = `z.enum(${JSON.stringify(spec.values)})`;
+      if (spec.valueDescriptions) {
+        used.add("montySelect");
+        src = `montySelect(${JSON.stringify(spec.values)}, ${JSON.stringify(spec.valueDescriptions)})`;
+      } else {
+        src = `z.enum(${JSON.stringify(spec.values)})`;
+      }
       break;
     case "multiSelect":
-      src = `z.array(z.enum(${JSON.stringify(spec.values)}))`;
+      if (spec.valueDescriptions) {
+        used.add("montyMultiSelect");
+        src = `montyMultiSelect(${JSON.stringify(spec.values)}, ${JSON.stringify(spec.valueDescriptions)})`;
+      } else {
+        src = `z.array(z.enum(${JSON.stringify(spec.values)}))`;
+      }
       break;
     case "email":
       src = "z.email()";
@@ -81,6 +92,7 @@ function storedSource(spec, used) {
       src = "z.any()";
   }
   if (spec.optional) src += ".optional()";
+  if (spec.description) src += `.describe(${JSON.stringify(spec.description)})`;
   return src;
 }
 
@@ -115,6 +127,7 @@ function rollupSource(spec, used, indent) {
   else lines.push("count: true,");
   if (spec.over !== undefined) lines.push(`over: ${JSON.stringify(spec.over)},`);
   if (spec.range !== undefined) lines.push(`range: ${JSON.stringify(spec.range)},`);
+  if (spec.description !== undefined) lines.push(`description: ${JSON.stringify(spec.description)},`);
   const body = lines.map((l) => `${pad}  ${l}`).join("\n");
   return `rollup(${outputSource(spec.output, used)}, {\n${body}\n${pad}})`;
 }
@@ -125,10 +138,10 @@ function fieldSource(spec, used, indent) {
       return storedSource(spec, used);
     case "formula":
       used.add("formula");
-      return `formula(${outputSource(spec.output, used)}, ${JSON.stringify(spec.expr)})`;
+      return `formula(${outputSource(spec.output, used)}, ${JSON.stringify(spec.expr)}${spec.description !== undefined ? `, ${JSON.stringify(spec.description)}` : ""})`;
     case "lookup":
       used.add("lookup");
-      return `lookup(${outputSource(spec.output, used)}, { ref: ${JSON.stringify(spec.ref)}, field: ${JSON.stringify(spec.field)} })`;
+      return `lookup(${outputSource(spec.output, used)}, { ref: ${JSON.stringify(spec.ref)}, field: ${JSON.stringify(spec.field)}${spec.description !== undefined ? `, description: ${JSON.stringify(spec.description)}` : ""} })`;
     case "rollup":
       return rollupSource(spec, used, indent);
     default:

package/package.json

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

package/skills/monty-build/SKILL.md

@@ -65,9 +65,12 @@ channel switch. "dev"/"prod" mean platform environments, never app states.
    `monty schema` (JSON on stdout); change it by editing that JSON and
    running `monty schema set <file>` — validated server-side, additive by
    default. On workspace-owned apps, `monty.config.ts` edits do NOT change
-   the schema. Declare a page in the manifest BEFORE shipping its route —
-   a save with an undeclared route refuses with the fix. Field names `_*`,
-   `updatedAt`, `createdBy` are reserved.
+   the schema. Give every field a `description` and every enum/multiSelect
+   a `valueDescriptions` map saying WHEN each option applies — that's the
+   guidance later record-writing agents follow. Declare a page in the
+   manifest BEFORE shipping its route — a save with an undeclared route
+   refuses with the fix. Field names `_*`, `updatedAt`, `createdBy` are
+   reserved.
 6. **UI is stock shadcn** (preset already wired). Add curated components with
    `monty add <name>`; browse with `monty components` / `monty docs <name>`.
    How pages should LOOK — Lyra surfaces, dark-only, the chart language — is

package/skills/monty-operate/SKILL.md

@@ -40,7 +40,16 @@ normal operating work; that is what this command is for.
    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.
+   a misspelled field is silently a new field, not an error. The schema's
+   `description` and `enumDescriptions` annotations are the app's own
+   instructions for filling a field in: where a field has options (an
+   `enum`, alone or as array items), pick the option whose description
+   matches the situation — never your own reading of the option's name,
+   and never a value outside the list. A field without options has no
+   fixed vocabulary, so its `description` plus the conventions visible in
+   existing rows (`list` first) are the contract — write explicit,
+   consistently formatted values, not free-hand variants of the same
+   thing.
 3. **Every write is real** — operating work targets the team's data, and
    the app's Activity journals it. Destructive verbs (`remove`, bulk
    `update`) deserve a confirmation with the user unless they clearly
@@ -57,6 +66,13 @@ normal operating work; that is what this command is for.
 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`.
+8. **File fields hold descriptors, never bytes or paths.** A `file`-typed
+   field stores exactly the object `monty data upload` prints
+   (`{id, name, contentType, size, uploadedAt, uploadedBy}`). Upload
+   first, then reference: use the attach flags to set an existing row's
+   field in one command, or paste the printed descriptor into `--data`
+   when inserting. Never hand-write a descriptor — an id that no upload
+   produced 404s on download.
 
 ## Command reference
 
@@ -69,6 +85,8 @@ normal operating work; that is what this command is for.
 | `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 |
+| `monty data upload <path> [--name N] [--type mime] [--table <t> --record <id> --field <f>]` | store a file (10MB cap); prints the descriptor a `file` field holds — the attach flags set it on an existing row in the same command |
+| `monty data download <file-id> [--out path]` | fetch a stored file's bytes to disk; the id is the `id` key of a row's file descriptor |
 
 All verbs take `--app <slug>`. Output is one JSON document on
 stdout.

package/template/AGENTS.md

@@ -36,7 +36,10 @@ Folders are managed for you: this app lives in `~/Monty/<slug>`. `monty current`
    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.
+   `.default(...)` so existing records stay readable. Describe fields for
+   the next agent that fills them in: `.describe("what this holds")` on any
+   field, and `montySelect`/`montyMultiSelect` instead of bare `z.enum` so
+   every option says WHEN it applies, not what the word means.
 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
@@ -46,7 +49,7 @@ Folders are managed for you: this app lives in `~/Monty/<slug>`. `monty current`
 
 ```ts
 // monty.config.ts
-import { defineApp, montyFileSchema } from "@montytools/sdk";
+import { defineApp, montyFileSchema, montySelect } from "@montytools/sdk";
 import { z } from "zod";
 
 export const app = defineApp({
@@ -54,8 +57,12 @@ export const app = defineApp({
   tables: {
     expenses: z.object({
       title: z.string().min(1),
-      amount: z.number().positive(),
-      status: z.enum(["draft", "submitted", "approved"]).default("draft"),
+      amount: z.number().positive().describe("Receipt total in USD, tax included."),
+      status: montySelect(["draft", "submitted", "approved"], {
+        draft: "Still being filled in, not yet sent for review.",
+        submitted: "Awaiting a manager's decision.",
+        approved: "Cleared for reimbursement.",
+      }).default("draft"),
       assigneeId: z.string().optional(), // userId from useMembers()
       receipt: montyFileSchema.optional(),
     }),
@@ -216,9 +223,12 @@ 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
 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).
+tables, including ones the UI never exposes), `ctx.files` (platform file
+storage: `upload(data, {name?, contentType?}) → MontyFile`,
+`download(fileOrId) → Blob`, `remove(fileOrId)` — same descriptors as the
+`useUploadFile` hook, 10MB cap), `ctx.secrets` (see below), `ctx.viewer`
+(who called: member session/visitor/schedule/none), and `ctx.track()`
+(emit an event).
 
 ```ts
 // server/index.ts

package/template/package.json

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