@montytools/cli 0.5.3 → 0.5.5

package/lib/compile.mjs

@@ -1,6 +1,6 @@
 // The ONE config-compile pipeline: esbuild-bundle a temp entry that runs the
 // app's OWN compileApp/zod/sdk instances on monty.config.ts, execute it in a
-// subprocess, parse the emitted metadata. Used by `monty dev`/`monty deploy`
+// subprocess, parse the emitted metadata. Used by `monty dev`/`monty save`
 // (bin/monty.mjs) and the demo harness (scripts/demo.mjs) — one pipeline, so
 // what a demo installs is byte-for-byte what a deploy would send.
 import { spawnSync } from "node:child_process";
@@ -19,7 +19,7 @@ export class CompileError extends Error {
 // Throws CompileError:
 // - CONFIG_BUNDLE_FAILED — esbuild could not bundle (usually unlinked deps)
 // - CONFIG_COMPILE_FAILED — the config threw while loading
-export async function compileAppConfig(appDir, { forceManifest = false } = {}) {
+export async function compileAppConfig(appDir) {
   appDir = resolve(appDir); // esbuild requires an absolute absWorkingDir
   // esbuild is a dependency of THIS package (@montytools/cli), so resolution
   // from here works for any caller — no per-script resolution dance.
@@ -31,7 +31,7 @@ export async function compileAppConfig(appDir, { forceManifest = false } = {}) {
   writeFileSync(entry, [
     `import { app } from "../monty.config";`,
     `import { compileApp } from "@montytools/sdk/compile";`,
-    `process.stdout.write(JSON.stringify(compileApp(app, { forceManifest: ${forceManifest} })));`,
+    `process.stdout.write(JSON.stringify(compileApp(app)));`,
   ].join("\n"));
   try {
     await build({

package/lib/schemaCodegen.mjs

@@ -220,8 +220,8 @@ export function manifestToConfig(manifest, { name, icon } = {}) {
     ...sdkImports.map((n) => `  ${n},`),
     `} from "@montytools/sdk";`,
     ``,
-    `// Regenerated by \`monty schema pull\` from the app's stored manifest.`,
-    `// Edit freely — \`monty dev\` / \`monty deploy\` push changes back; another`,
+    `// Regenerated by \`monty schema pull\` from the app's config stored in the workspace.`,
+    `// Edit freely — \`monty dev\` / \`monty save\` push changes back; another`,
     `// editor's remote changes surface as MANIFEST_DRIFT (then pull again).`,
     `export const app = defineApp({`,
     `  slug: ${JSON.stringify(manifest.slug)},`,

package/lib/schemaPull.mjs

@@ -41,8 +41,8 @@ export async function schemaPull({ appDir, host, key, slug, force, compileAppCon
   }
   if (!body.manifest) {
     fail(
-      "NO_MANIFEST",
-      `"${slug}" has no stored App Manifest (it is a V1 app or has never pushed one). Author monty.config.ts with V2 features and run \`monty dev\` or \`monty deploy\` first.`,
+      "NO_CONFIG",
+      `"${slug}" has no config stored in the workspace yet (a V1 app, or one that never pushed). Author monty.config.ts with V2 features and run \`monty dev\` or \`monty save\` first.`,
     );
   }
 
@@ -67,7 +67,7 @@ export async function schemaPull({ appDir, host, key, slug, force, compileAppCon
     if (localHash !== null && localHash !== cleanAgainst && localHash !== body.hash) {
       fail(
         "SCHEMA_DIRTY",
-        "monty.config.ts has schema changes that never reached the registry. Push them first (`monty dev` save or `monty deploy`), or discard them with --force (a .bak is kept).",
+        "monty.config.ts has schema changes that never reached the registry. Push them first (`monty dev` or `monty save`), or discard them with --force (a .bak is kept).",
       );
     }
   }

package/lib/views.mjs

@@ -107,8 +107,25 @@ export function parseHiddenColumns(input) {
   return [...new Set(input.split(",").map((field) => field.trim()).filter(Boolean))];
 }
 
+/** `--kanban <field>` makes the view a kanban laned by that select field's
+ * values; `--kanban none` makes it a table. */
+export function parseKanbanFlag(input) {
+  if (input === undefined) return undefined;
+  if (input === "none") return null;
+  const groupBy = input.trim();
+  if (groupBy === "") {
+    badViewConfig('--kanban needs a select field name, or "none" to make the view a table.');
+  }
+  return { type: "kanban", groupBy };
+}
+
 export function mergeViewConfig(existing, patch) {
   const base = isObject(existing) ? existing : {};
+  const kanban = Object.hasOwn(patch, "kanban")
+    ? patch.kanban
+    : base.type === "kanban" && typeof base.groupBy === "string"
+      ? { type: "kanban", groupBy: base.groupBy }
+      : null;
   return {
     filters: Object.hasOwn(patch, "filters")
       ? patch.filters
@@ -117,6 +134,7 @@ export function mergeViewConfig(existing, patch) {
     hidden: Object.hasOwn(patch, "hidden")
       ? patch.hidden
       : (Array.isArray(base.hidden) ? base.hidden : []),
+    ...(kanban ? { type: "kanban", groupBy: kanban.groupBy } : {}),
   };
 }
 
@@ -126,6 +144,7 @@ export function validateViewColumns(config, fieldNames) {
     ...Object.keys(config.filters),
     ...(config.sort ? [config.sort.column] : []),
     ...config.hidden,
+    ...(config.type === "kanban" && config.groupBy ? [config.groupBy] : []),
   ];
   const unknown = [...new Set(used.filter((field) => !known.has(field)))];
   if (unknown.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montytools/cli",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TomasMonty/monty-v2.git",
@@ -22,7 +22,7 @@
   "scripts": {
     "prepack": "node scripts/bundle-template.mjs",
     "typecheck": "node --check bin/monty.mjs && node --check lib/compile.mjs && node --check lib/schemaCodegen.mjs && node --check lib/schemaPull.mjs && node --check lib/views.mjs && node --check scripts/schema-roundtrip.mjs",
-    "test": "node --test test/views.test.mjs",
+    "test": "node --test \"test/*.test.mjs\"",
     "postinstall": "node bin/postinstall.mjs",
     "test:roundtrip": "node scripts/schema-roundtrip.mjs"
   },

package/skills/monty-build/SKILL.md

@@ -1,123 +1,111 @@
 ---
 name: monty-build
-description: Build, run, and save Monty workspace apps. Use whenever the task involves a Monty app, monty.config.ts, the monty CLI (create/dev/logs/save/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 save Monty workspace apps. Use whenever the task involves a Monty app, monty.config.ts, the monty CLI (create/connect/dev/logs/save), the @montytools/sdk, or a prompt mentioning usemonty.dev. Covers folder discipline, the build loop, data/auth rules, and error handling.
 ---
 
 # Building Monty apps
 
-Monty is a work OS: teams get internal apps built by coding agents. You write
-product logic only — data, auth, tenancy, deployment, and embedding are the
-platform's job. The complete contract lives in the app's own `AGENTS.md`
-(nearest-file-wins — read it before writing code). This skill is the map, not
-the territory.
+Monty is a work OS. Teams get internal apps built by coding agents. You write
+product logic only. Data, auth, tenancy, deployment, and embedding are the
+platform's job. The full contract is in the app's own `AGENTS.md`
+(nearest file wins). Read it before writing code.
 
-There is ONE copy of every app: **Live**, the cloud copy the team uses
-(`monty save` updates it). While a dev **session** runs (a dev shell on
-the app's LIVE records, often already started for you by the Monty desktop),
-workspace admins see the session's version automatically — no publish, no
-channel switch. "dev"/"prod" mean platform environments, never app states.
+Every app has ONE copy: **Live**, the cloud copy the team uses. `monty save`
+updates it. While a dev **session** runs (often already started for you by
+the Monty desktop), workspace admins see the session's version automatically.
+There is no publish step. "dev" and "prod" name platform environments, never
+app states.
 
 ## Rules
 
-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`. The folder IS the app's source: every file in it
-   rides the source snapshot on `monty save`, so never leave scratch files
-   here (manifest edits, notes, one-off scripts). Work in the OS temp dir
-   instead, or pipe — `monty schema | <edit> | monty schema set -` needs
-   no file at all — and delete anything temporary before saving.
-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` → shape the schema through `monty schema` /
-   `monty schema set` (a brand-new app's very first session lands its
-   monty.config.ts once; after that the workspace owns the schema) + edit
-   `src/routes/` →
-   verify in the session: run `monty dev` once — if the dev shell is already
-   running (the Monty desktop usually runs it for you) it prints the status,
-   app 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. 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. **You are not done
-   until you've saved: once the work is verified in the session, run
-   `monty save "<what changed>"`** — it builds, typechecks, and pushes the
-   working copy to the cloud copy, like `git push main`. Save after every
-   meaningful change, not just at the end; unsaved work exists only on this
+1. **Respect the folder.** `monty create` scaffolds new apps;
+   `monty connect <slug> [dir]` puts a copy of an existing app in any
+   folder you choose. Never mkdir an app folder by hand and never edit the
+   `id:` line in `monty.config.ts`. `monty current` says which app folder
+   you are in. Every file in the folder rides the source snapshot on
+   `monty save`, so keep scratch files out. Use the OS temp dir, or pipe
+   (`monty schema | <edit> | monty schema set -` needs no file), and delete
+   anything temporary before saving.
+2. **The loop.** `monty create <slug> --name "Name" --icon <tabler-icon>`
+   (pass `--build <id>` when the prompt includes one), then `monty install`.
+   Shape the schema with `monty schema` and `monty schema set`; edit
+   `src/routes/`. Run `monty dev` once. If a shell is already running it
+   prints status and exits; otherwise start it in the background. Then
+   iterate: edit, vite hot-reloads, `monty logs -n 50` shows compile and
+   browser errors. Re-running `monty dev` is always safe. Never start a
+   second dev server for the same app and never kill a shell you didn't
+   start; `monty dev --takeover` is the one sanctioned restart.
+   **You are not done until you've saved.** `monty save "<what changed>"`
+   builds, typechecks, and pushes to the cloud copy, like `git push main`.
+   Save after every meaningful change. Unsaved work exists only on this
    machine.
 3. **Everything through the CLI.** `monty install`, `monty build`,
-   `monty typecheck`, `monty dev`, `monty save` — 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. `monty logs`
-   (add `-f` to follow) is how you read the dev shell's output — vite build
-   errors, browser errors, and save 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
-   platform CSP blocks them.
-5. **The data schema lives in the WORKSPACE, not in code.** Read it with
-   `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. 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. **Prefer a saved view for filtered tables.** If the request is
-   one table with different filters, sorting, or hidden columns, use
-   `monty views set <table> <name> ...`. For example, an evaluation queue is
+   `monty typecheck`, `monty dev`, `monty save`. Never run vite, tsc, pnpm,
+   or npm scripts directly. `monty logs` (add `-f` to follow) is where vite
+   errors, browser errors, and save results land.
+4. **Import only the SDK.** `@montytools/sdk` (`defineApp`, zod) and
+   `@montytools/sdk/react` (hooks: `useList`, `useInsert`, ...). Never
+   import Clerk or Convex; never fetch external APIs from app code, the CSP
+   blocks them. Open external pages with `openExternal(url)` from the SDK,
+   called synchronously from the click handler. `window.open` and
+   `target="_blank"` are blocked in the app iframe.
+5. **The schema lives in the workspace, not in code.** Read it with
+   `monty schema` (JSON on stdout), change it with
+   `monty schema set '<json>'` — the whole config as one JSON argument, or
+   piped: `monty schema | <edit> | monty schema set -` (validated
+   server-side, additive by default). On workspace-owned apps,
+   editing `monty.config.ts` does not change the schema. Give every field a
+   `description` and every enum a `valueDescriptions` map saying when each
+   option applies; record-writing agents follow that guidance later.
+   Declare a page before shipping its route (`monty page add <name>` does
+   both); a save with an undeclared route refuses. Field names `_*`,
+   `updatedAt`, `createdBy` are reserved.
+6. **Prefer a saved view for filtered tables.** One table with different
+   filters, sorting, or hidden columns is `monty views set <table> <name>`.
+   An evaluation queue:
    `monty views set leads "Evaluate" --filter '{"pipelineId":null}'`.
-   Change selected properties or rename it later with
-   `monty views update <table> <name> ...`; omitted properties stay unchanged.
-   If that table needs actions, compose `RecordPage` from
-   `@montytools/sdk/react` and add typed row/header/selection/record actions
-   with the controls from `@montytools/sdk/ui`. Write the whole page yourself
-   only when the shared components no longer fit. Custom pages remain the
-   escape hatch.
-7. **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
-   the `monty-design` skill; read it before styling any page.
+   A board: `--kanban <select-field>` lanes records by that field
+   (`monty views set deals "Pipeline" --kanban stage`). Update later with
+   `monty views update`; omitted properties stay unchanged. If the table
+   needs actions, compose `RecordPage` from `@montytools/sdk/react` with
+   controls from `@montytools/sdk/ui`. Write a whole custom page only when
+   the shared components no longer fit.
+7. **UI is stock shadcn** (preset already wired). Install curated components
+   with `monty components add <name>`; `monty components [query]` lists the
+   catalog, `monty components docs <name>` prints one's source. How pages
+   should look is the `monty-design` skill; read it before styling.
 8. **Errors are instructions.** Every failure prints
-   `[MontyError CODE] Fix: …` — do exactly what the Fix says; don't guess.
-   Typecheck failures block the save by design.
+   `[MontyError CODE] Fix: ...`. Do what the Fix says. Typecheck failures
+   block the save by design.
 9. **Edits are real.** The dev shell reads and writes the app's LIVE
-   records — there is one set of data, and every write journals into the
-   app's Activity. Exercise the app for real; clean up test rows you
-   create; never seed junk into a team's working tables.
+   records, and every write journals into the app's Activity. Exercise the
+   app for real, clean up test rows, never seed junk into a team's tables.
 10. **Report platform failures when sharing is enabled.** `monty support
-   status` shows whether a workspace admin has allowed agent support
-   reports. If enabled, submit one report when a Monty platform error still
-   blocks the task after you followed its `Fix` and retried, or when the
-   requested work needs a missing Monty platform feature. Summarize the
-   thread. State the observed problem, expected behavior, attempted fixes,
-   and exact error. Do not paste the full conversation. If sharing is off,
-   ask the user before running `monty support enable --yes`; never grant
-   consent yourself. Do not file reports for ordinary app-code bugs or send
-   duplicates for the same incident.
+   status` shows whether an admin allowed agent reports. If enabled, submit
+   one report when a platform error still blocks you after following its
+   Fix, or when the task needs a missing platform feature. State the
+   problem, expected behavior, attempted fixes, and exact error. Don't
+   paste the conversation. If sharing is off, ask the user before running
+   `monty support enable --yes`. No reports for ordinary app-code bugs, no
+   duplicates.
 
 ## CLI reference
 
 | command | purpose |
 |---|---|
-| `monty login` | browser sign-in (loopback authorize), once per machine |
-| `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's session, or attach to an already-running one (auto-port, live 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 schema [slug]` | print the app's stored manifest (tables, pages, metrics) as JSON |
-| `monty schema set <file\|->` | write an edited manifest back (validated, CAS, additive by default) |
-| `monty views <list\|set\|update\|remove> <table>` | manage the shared saved views on a system record page |
-| `monty save ["what changed"]` | push the working copy to the cloud copy, like `git push main` (build + typecheck gate it) |
-| `monty support <status\|enable\|disable\|submit>` | manage consent and send a bounded agent-authored platform report |
-| `monty skills` | (re)install this skill for your agent |
+| `monty login` | browser sign-in, once per machine |
+| `monty connect <slug> [dir]` | pull an existing app into any folder, ready for `monty dev` |
+| `monty create <slug>` | register a new app and scaffold it (needs login) |
+| `monty current` / `select` / `apps` | where am I / jump to app / list local copies |
+| `monty install` / `build` / `typecheck` | lifecycle, no raw pnpm/vite/tsc |
+| `monty dev` | run the app's session, or attach to a running one |
+| `monty logs [-n N] [-f]` | read/follow the session log |
+| `monty save ["what changed"]` | push the working copy to the cloud copy (build + typecheck gate it) |
+| `monty history [slug]` | saved-version history, one row per save |
+| `monty schema [slug]` | print the app's config (stored in the workspace) as JSON |
+| `monty schema set '<json>'` (or `set -` piped) | write the edited config back (validated, CAS) |
+| `monty views <list\|set\|update\|remove> <table>` | manage shared saved views |
+| `monty page add <name>` | declare + scaffold a custom page |
+| `monty components add <name...>` | install curated shadcn components |
+| `monty support <status\|enable\|disable\|submit>` | consent + platform reports |
+| `monty skills` | (re)install this skill |

package/template/AGENTS.md

@@ -4,7 +4,7 @@ Monty is a work OS: your app runs inside a team's workspace, on shared reactive
 data, with auth and deployment handled by the platform. **You only write product
 logic.** Everything below is the complete contract.
 
-Folders are managed for you: this app lives in `~/Monty/<slug>`. `monty current` confirms where you are; `cd "$(monty select <slug>)"` jumps to any app; never create app folders by hand.
+`monty current` confirms which app folder you are in. Never create app folders by hand — `monty create` and `monty connect` do it.
 
 ## The three files that matter
 
@@ -24,10 +24,11 @@ Folders are managed for you: this app lives in `~/Monty/<slug>`. `monty current`
 3. **UI is shadcn/ui, preconfigured — never build components from scratch.**
    Before building any UI piece, run `monty components`. If the capability is
    listed (data tables, kanban, calendar, combobox, file upload, rich text,
-   charts, …) install the curated implementation with `monty add <name>`;
-   core shadcn components install by bare name (`monty add dialog tabs`).
-   Everything lands in `src/components/ui/*` already carrying the Monty
-   theme. `monty docs <name>` shows a component's source before installing.
+   charts, …) install the curated implementation with
+   `monty components add <name>`; core shadcn components install by bare
+   name (`monty components add dialog tabs`). Everything lands in
+   `src/components/ui/*` already carrying the Monty theme.
+   `monty components docs <name>` shows a component's source before installing.
    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.
@@ -106,6 +107,19 @@ await update(row._id, { receipt });                     // store descriptor, not
 const { url } = useFileUrl(app, row.receipt);            // authenticated blob: URL for previews/downloads
 ```
 
+Open an external HTTPS page with the SDK. Do not use `target="_blank"` or
+`window.open`; the app iframe blocks popups by design. Call `openExternal`
+synchronously from the click or key handler so the host can verify current
+user activation:
+
+```tsx
+import { openExternal } from "@montytools/sdk";
+
+<Button onClick={() => openExternal(profile.linkedinUrl)}>
+  Open LinkedIn
+</Button>
+```
+
 ## Derived fields, metrics, pages (V2 — the platform renders these)
 
 Your config can carry a whole database app the platform shell renders for

package/template/package.json

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