@montytools/cli 0.1.5 → 0.2.0

package/bin/monty.mjs

@@ -362,36 +362,214 @@ async function create() {
 
   installSkills({ appDir: target });
   console.log(`created: ${target}`);
-  console.log(`next: cd ${target} && pnpm install && monty dev`);
+  console.log(`next: cd ${target} && monty install && monty dev`);
+}
+
+
+// ── monty install / build / typecheck ───────────────────────────────────────
+// The full app lifecycle goes through the CLI — agents never invoke pnpm,
+// vite, or tsc directly. Same underlying tools, agent-shaped output, and the
+// build-before-typecheck ordering handled for you.
+function installDeps() {
+  const appDir = requireAppDir("install");
+  const pm = spawnSync("pnpm", ["--version"], { stdio: "ignore" }).status === 0 ? "pnpm" : "npm";
+  run(appDir, "install", [pm, "install"],
+    "Dependency install failed. Read the package manager error above; usually network or a bad package.json edit.");
+}
+
+function buildApp() {
+  const appDir = requireAppDir("build");
+  run(appDir, "build", ["npx", "vite", "build"],
+    "The production build failed. Read the vite error above; it names the file to fix.");
+}
+
+function typecheckApp() {
+  const appDir = requireAppDir("typecheck");
+  // routeTree.gen.ts is generated by the build — without it tsc fails on a
+  // fresh checkout, so build first when it's missing.
+  if (!existsSync(join(appDir, "src", "routeTree.gen.ts"))) {
+    run(appDir, "build", ["npx", "vite", "build"],
+      "The production build failed. Read the vite error above; it names the file to fix.");
+  }
+  run(appDir, "typecheck", ["npx", "tsc", "--noEmit"],
+    "TypeScript errors above. Fix them in the listed files.");
+}
+
+
+async function freePort(start) {
+  for (let p = start; p < start + 50; p++) {
+    const ok = await new Promise((resolve) => {
+      const probe = createServer();
+      probe.once("error", () => resolve(false));
+      probe.listen(p, "127.0.0.1", () => probe.close(() => resolve(true)));
+    });
+    if (ok) return p;
+  }
+  fail("NO_FREE_PORT", `No free port between ${start} and ${start + 49}. Pass --port <n>.`);
 }
 
 // ── monty dev ──────────────────────────────────────────────────────────────
+// Development mode: vite locally + a Cloudflare quick tunnel registered as
+// the app's DEV channel, so workspace admins see the app live (HMR included)
+// at usemonty.dev while it runs. Data is #dev-sandboxed automatically (vite
+// dev build). The heartbeat doubles as the publish poll: when an owner
+// clicks Publish in the workspace, this process builds + uploads for real.
 async function dev() {
-  const appDir = process.cwd();
-  if (!existsSync(join(appDir, "monty.config.ts"))) {
-    fail("NOT_A_MONTY_APP", "No monty.config.ts here. Run `monty dev` from your app's root directory.");
-  }
+  const appDir = requireAppDir("dev");
   const meta = await compileConfig(appDir);
-  const host = loadConfig()?.host ?? DEFAULT_HOST;
-  const port = Number(flag("port") ?? 5173);
+  const cfg = loadConfig();
+  const host = cfg?.host ?? DEFAULT_HOST;
+  // Auto-pick a free port (agents run several apps side by side); an
+  // explicit --port is honored strictly.
+  const requested = flag("port");
+  const port = requested ? Number(requested) : await freePort(5173);
 
   console.log(`dev: starting vite on :${port} (app "${meta.slug}")`);
   const child = spawn("npx", ["vite", "dev", "--port", String(port), "--strictPort"], {
     cwd: appDir,
     stdio: ["ignore", "pipe", "inherit"],
   });
+
+  let tunnelChild = null;
+  let hbTimer = null;
+  let publishing = false;
+  let ended = false;
+  const buildFile = join(appDir, ".monty", "build");
+  const buildId = existsSync(buildFile) ? readFileSync(buildFile, "utf8").trim() : undefined;
+
+  async function endSession() {
+    if (ended) return;
+    ended = true;
+    if (hbTimer) clearInterval(hbTimer);
+    try { tunnelChild?.kill(); } catch { /* already gone */ }
+    if (cfg?.key) {
+      try {
+        await fetch(`${host}/api/dev-session`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${cfg.key}`, "content-type": "application/json" },
+          body: JSON.stringify({ slug: meta.slug, end: true }),
+          signal: AbortSignal.timeout(2000),
+        });
+      } catch { /* best effort */ }
+    }
+  }
+
+  async function heartbeat(originUrl) {
+    try {
+      const r = await fetch(`${host}/api/dev-session`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${cfg.key}`, "content-type": "application/json" },
+        body: JSON.stringify({ slug: meta.slug, tunnelUrl: originUrl, name: meta.name, icon: meta.icon, buildId }),
+      });
+      const data = await r.json().catch(() => null);
+      if (!r.ok) {
+        console.log(`dev-session: ${data?.code ?? r.status}${data?.fix ? ` — ${data.fix}` : ""}`);
+        return;
+      }
+      if (data?.publishRequested && !publishing) {
+        publishing = true;
+        console.log("publish: requested from the workspace — building & uploading…");
+        await new Promise((resolve) => {
+          const pub = spawn(process.execPath, [fileURLToPath(import.meta.url), "deploy", "--from-dev"], {
+            cwd: appDir,
+            stdio: ["ignore", "inherit", "inherit"],
+          });
+          pub.on("exit", (code) => {
+            console.log(
+              code === 0
+                ? "publish: done — the workspace now serves the new version (dev session continues)"
+                : "publish: FAILED — fix the errors above, then click Publish again",
+            );
+            resolve(undefined);
+          });
+        });
+        publishing = false;
+      }
+    } catch { /* transient network hiccup — next beat retries */ }
+  }
+
+  async function startDevSession() {
+    if (!cfg?.key) {
+      console.log("dev: not logged in — workspace dev mode disabled (run `monty login`)");
+      return;
+    }
+    let originUrl = `http://localhost:${port}`;
+    if (!rest.includes("--no-tunnel")) {
+      console.log("tunnel: starting (cloudflared quick tunnel)…");
+      const t = await startTunnel(port);
+      tunnelChild = t.child;
+      if (t.url) {
+        originUrl = t.url;
+        console.log(`tunnel: ${t.url}`);
+      } else {
+        console.log("tunnel: unavailable — dev mode registered on localhost (visible on this machine's browser only)");
+      }
+    }
+    await heartbeat(originUrl);
+    console.log(`workspace: ${host}/apps/${meta.slug} — DEV mode for admins while this runs; click Publish there to ship`);
+    hbTimer = setInterval(() => void heartbeat(originUrl), 30_000);
+  }
+
   let announced = false;
   child.stdout.on("data", (chunk) => {
     const text = chunk.toString();
     process.stdout.write(text);
     if (!announced && /localhost:\d+/.test(text)) {
       announced = true;
-      console.log(`open: ${host}/apps/${meta.slug}?dev=http://localhost:${port}`);
       console.log(`data: sandboxed to "${meta.slug}#dev" (live records untouched)`);
       console.log(`ready: http://localhost:${port}`);
+      void startDevSession();
     }
   });
-  child.on("exit", (code) => process.exit(code ?? 0));
+  child.on("exit", (code) => {
+    void endSession().then(() => process.exit(code ?? 0));
+  });
+  process.on("SIGINT", () => {
+    void endSession().then(() => process.exit(130));
+  });
+  process.on("SIGTERM", () => {
+    void endSession().then(() => process.exit(143));
+  });
+}
+
+// Cloudflare quick tunnel via the cloudflared npm wrapper (downloads the
+// binary on first use). Resolves with the public URL, or null on failure —
+// dev mode then falls back to localhost-only registration.
+function startTunnel(port) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn("npx", ["-y", "cloudflared", "tunnel", "--url", `http://localhost:${port}`], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch {
+      return resolve({ child: null, url: null });
+    }
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        resolve({ child, url: null });
+      }
+    }, 45_000);
+    const scan = (chunk) => {
+      const m = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/.exec(String(chunk));
+      if (m && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve({ child, url: m[0] });
+      }
+    };
+    child.stdout.on("data", scan);
+    child.stderr.on("data", scan);
+    child.on("exit", () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve({ child: null, url: null });
+      }
+    });
+  });
 }
 
 // ── monty add / components / docs ──────────────────────────────────────────
@@ -400,9 +578,9 @@ async function dev() {
 // implementation. Only catalog registries and core shadcn resolve.
 
 function requireAppDir(cmd) {
-  const appDir = process.cwd();
-  if (!existsSync(join(appDir, "monty.config.ts"))) {
-    fail("NOT_A_MONTY_APP", `No monty.config.ts here. Run \`monty ${cmd}\` from your app's root directory.`);
+  const appDir = findAppRoot(process.cwd());
+  if (!appDir) {
+    fail("NOT_A_MONTY_APP", `Not inside a Monty app. \`monty apps\` lists local apps; cd "$(monty select <slug>)" jumps to one — then run \`monty ${cmd}\`.`);
   }
   return appDir;
 }
@@ -494,9 +672,9 @@ async function docs() {
 
 // ── monty deploy ───────────────────────────────────────────────────────────
 async function deploy() {
-  const appDir = process.cwd();
-  if (!existsSync(join(appDir, "monty.config.ts"))) {
-    fail("NOT_A_MONTY_APP", "No monty.config.ts here. Run `monty deploy` from your app's root directory.");
+  const appDir = requireAppDir("deploy");
+  if (!rest.includes("--from-dev")) {
+    console.log("note: direct deploy skips workspace review — the usual flow is `monty dev` + the Publish button in the workspace.");
   }
   const config = loadConfig();
   if (!config?.key) {
@@ -642,20 +820,32 @@ switch (command) {
     installSkills({ appDir: findAppRoot(process.cwd()), silent: false });
     console.log("skills: up to date");
     break;
+  case "install":
+    installDeps();
+    break;
+  case "build":
+    buildApp();
+    break;
+  case "typecheck":
+    typecheckApp();
+    break;
   case "deploy":
     await deploy();
     break;
   default:
-    console.log("usage: monty <login|create|current|select|apps|dev|add|components|docs|deploy|skills>");
+    console.log("usage: monty <login|create|current|select|apps|install|dev|build|typecheck|add|components|docs|deploy|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]  stamp a new app into ~/Monty/<slug>");
-    console.log("  dev         [--port 5173]                  run the app locally (sandboxed data)");
+    console.log("  dev         [--port N]                      run locally, auto-picks a free port (sandboxed data)");
     console.log("  add         <name...>                      install curated UI components (see `monty components`)");
     console.log("  components  [query]                        list the curated component catalog");
     console.log("  docs        <name>                         view a component's source before installing");
     console.log("  current                                     which app folder am I in?");
     console.log("  select      <slug>                          print an app's folder — cd \"$(monty select x)\"");
     console.log("  apps                                        list local apps in ~/Monty");
+    console.log("  install                                     install app dependencies");
+    console.log("  build                                       production build (vite, via monty)");
+    console.log("  typecheck                                   typecheck (builds first if needed)");
     console.log("  deploy                                      build + upload this app");
     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.1.5",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "monty": "./bin/monty.mjs"

package/skills/monty-build/SKILL.md

@@ -19,21 +19,29 @@ the territory.
 2. **The loop:** `monty create <slug> --name "Name" --icon <lucide-icon>` →
    (if the prompt includes a `build id`, pass it: `--build <id>` — the
    workspace's New app screen tracks your progress live) →
-   edit `monty.config.ts` (zod tables) + `src/routes/` → verify with
-   `monty dev` (localhost:5173, already authenticated, sandboxed data) →
-   `monty deploy`. You are done when deploy prints the URL.
-3. **One import surface:** `@montytools/sdk` (`defineApp`, zod) and
+   `monty install` → edit `monty.config.ts` (zod tables) + `src/routes/` →
+   verify with `monty dev` (auto-port, already authenticated, sandboxed
+   data). **You are done when `monty dev` prints the workspace dev URL and
+   the app works — leave `monty dev` running.** Publishing to the whole
+   workspace is the OWNER'S click (Publish in the workspace menu bar);
+   **never run `monty deploy` yourself** unless the user explicitly asks
+   for a direct production 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.
+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.
-4. **Schema is zod in `monty.config.ts`.** Field names `_*`, `updatedAt`,
+5. **Schema is zod in `monty.config.ts`.** Field names `_*`, `updatedAt`,
    `createdBy` are reserved. Push happens automatically on dev/deploy.
-5. **UI is stock shadcn** (preset already wired). Add curated components with
+6. **UI is stock shadcn** (preset already wired). Add curated components with
    `monty add <name>`; browse with `monty components` / `monty docs <name>`.
-6. **Errors are instructions.** Every failure prints
+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.
-7. **Verify before deploy.** `monty dev` writes to a `#dev` sandbox — live
+8. **Verify before deploy.** `monty dev` writes to a `#dev` sandbox — live
    team records are never touched, so exercise the app for real.
 
 ## CLI reference
@@ -43,7 +51,8 @@ the territory.
 | `monty login` | browser sign-in (loopback authorize), once per machine |
 | `monty create <slug>` | stamp a new app into `~/Monty/<slug>` |
 | `monty current` / `select` / `apps` | where am I / jump to app / list local |
-| `monty dev` | run locally on :5173, sandboxed data, auto-auth |
+| `monty install` / `build` / `typecheck` | full lifecycle via the CLI — no raw pnpm/vite/tsc |
+| `monty dev` | run locally (auto-picks a free port), sandboxed data, auto-auth |
 | `monty add <name…>` | install curated shadcn components |
 | `monty deploy` | build + typecheck + upload; app appears in the workspace |
 | `monty skills` | (re)install this skill for your agent |

package/template/AGENTS.md

@@ -102,14 +102,24 @@ Every platform error is one line shaped like:
 
 ## Dev loop
 
+Everything goes through the `monty` CLI — never run vite, tsc, pnpm, or npm
+scripts directly:
+
 ```
-pnpm dev          # Vite + HMR on :5173; sign in with your workspace account
+monty install     # dependencies
+monty dev         # Vite + HMR, auto-picks a free port and prints it
 ```
 
-Headless? Verify with `pnpm exec vite build` then `pnpm exec tsc --noEmit` — in
-that order: the first build generates `src/routeTree.gen.ts`, without which
-typecheck fails on a fresh app. `monty deploy` runs both itself (it never
-uploads code that doesn't compile), so deploy is self-verifying.
+Headless? Verify with `monty build` then `monty typecheck` (typecheck builds
+first when needed — the build generates `src/routeTree.gen.ts`).
+
+**Development vs production:** while `monty dev` runs, the app is live in
+the workspace in DEV mode (workspace admins only, tunneled, `#dev` sandboxed
+data). Shipping to the whole team is the owner's **Publish** click in the
+workspace menu bar — it signals your running `monty dev`, which builds,
+typechecks, and uploads. You are done when the app works in dev mode;
+leave `monty dev` running and let the owner publish. Only run
+`monty deploy` directly if the user explicitly asks.
 
 **Driving your app in a browser (agents):** while `monty dev` runs, opening
 `http://localhost:5173` is ALREADY AUTHENTICATED — no sign-in screen (the dev