@montytools/cli 0.1.1 → 0.1.3

package/bin/monty.mjs

@@ -63,6 +63,7 @@ async function login() {
   mkdirSync(MONTY_HOME, { recursive: true });
   console.log(`logged-in: ${host} (key saved to ~/.monty/config.json)`);
   console.log(`apps home: ${MONTY_HOME}`);
+  installSkills({ silent: false });
 }
 
 // Loopback auth: serve one callback on 127.0.0.1, send the browser to
@@ -128,6 +129,110 @@ function openInBrowser(url) {
   }
 }
 
+
+
+// ── agent skills ─────────────────────────────────────────────────────────────
+// The build skill ships inside this package and is stamped wherever agents
+// look for it: ~/.claude/skills (user) and <app>/.claude + <app>/.agents
+// (project — self-propagating contract, refreshed whenever the CLI runs).
+const CLI_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const CLI_VERSION = JSON.parse(readFileSync(join(CLI_ROOT, "package.json"), "utf8")).version;
+const SKILLS_SRC = join(CLI_ROOT, "skills");
+
+function installSkillsInto(dir, { silent = true } = {}) {
+  if (!existsSync(SKILLS_SRC)) return false;
+  let changed = false;
+  for (const name of readdirSync(SKILLS_SRC)) {
+    const dest = join(dir, name);
+    const versionFile = join(dest, "VERSION");
+    const installed = existsSync(versionFile) ? readFileSync(versionFile, "utf8").trim() : null;
+    if (installed === CLI_VERSION) continue;
+    cpSync(join(SKILLS_SRC, name), dest, { recursive: true });
+    writeFileSync(versionFile, CLI_VERSION + "\n");
+    changed = true;
+  }
+  if (changed && !silent) console.log(`skills: installed -> ${dir} (v${CLI_VERSION})`);
+  return changed;
+}
+
+function installSkills({ appDir = null, silent = true } = {}) {
+  if (process.env.MONTY_NO_SKILLS) return;
+  try {
+    let changed = installSkillsInto(join(homedir(), ".claude", "skills"), { silent });
+    for (const base of appDir ? [join(appDir, ".claude", "skills"), join(appDir, ".agents", "skills")] : []) {
+      changed = installSkillsInto(base, { silent }) || changed;
+    }
+    if (changed && silent) console.log(`skills: refreshed (v${CLI_VERSION})`);
+  } catch {
+    /* skills are best-effort — never block a command */
+  }
+}
+
+// ── monty current / select / apps ───────────────────────────────────────────
+// Folder management users never think about: every app lives in ~/Monty,
+// `current` says where you are, `select` prints the folder for cd $(...).
+function findAppRoot(start) {
+  let d = start;
+  for (;;) {
+    if (existsSync(join(d, "monty.config.ts"))) return d;
+    const parent = dirname(d);
+    if (parent === d) return null;
+    d = parent;
+  }
+}
+
+function readSlugFromConfig(dir) {
+  try {
+    return /slug:\s*"([^"]+)"/.exec(readFileSync(join(dir, "monty.config.ts"), "utf8"))?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function listLocalApps() {
+  if (!existsSync(MONTY_HOME)) return [];
+  return readdirSync(MONTY_HOME)
+    .map((name) => join(MONTY_HOME, name))
+    .filter((p) => existsSync(join(p, "monty.config.ts")))
+    .map((p) => ({ path: p, slug: readSlugFromConfig(p) ?? basename(p) }));
+}
+
+function current() {
+  const root = findAppRoot(process.cwd());
+  if (!root) {
+    fail("NOT_IN_APP", `You are not inside a Monty app. \`monty apps\` lists local apps; cd "$(monty select <slug>)" jumps to one.`);
+  }
+  console.log(`app: ${readSlugFromConfig(root) ?? "?"}`);
+  console.log(`path: ${root}`);
+  if (!root.startsWith(MONTY_HOME)) {
+    console.log(`note: outside ${MONTY_HOME} (fine, but apps normally live there)`);
+  }
+}
+
+function select() {
+  const slug = rest.find((a) => !a.startsWith("--"));
+  if (!slug) {
+    fail("MISSING_SLUG", `Usage: cd "$(monty select <slug>)" — prints the app's folder.`);
+  }
+  const apps = listLocalApps();
+  const hit = apps.find((a) => a.slug === slug || basename(a.path) === slug);
+  if (!hit) {
+    const known = apps.map((a) => a.slug).join(", ") || "(none)";
+    fail("APP_NOT_LOCAL", `No local source for "${slug}" in ${MONTY_HOME}. Local apps: ${known}. Create it with \`monty create ${slug}\`.`);
+  }
+  // Bare path on stdout so command substitution works: cd "$(monty select x)"
+  console.log(hit.path);
+}
+
+function apps() {
+  const local = listLocalApps();
+  if (!local.length) {
+    console.log(`no local apps in ${MONTY_HOME} — create one with \`monty create <slug>\``);
+    return;
+  }
+  for (const a of local) console.log(`${a.slug}\t${a.path}`);
+}
+
 // ── monty create ───────────────────────────────────────────────────────────
 async function create() {
   const slug = rest.find((a) => !a.startsWith("--"));
@@ -199,6 +304,7 @@ async function create() {
     console.log(`config: WARNING — could not reach ${host}/api/config; copy .env.example to .env.local manually`);
   }
 
+  installSkills({ appDir: target });
   console.log(`created: ${target}`);
   console.log(`next: cd ${target} && pnpm install && monty dev`);
 }
@@ -440,6 +546,9 @@ function walk(dir) {
 }
 
 // ── dispatch ───────────────────────────────────────────────────────────────
+// Keep agent skills fresh on every invocation (user level + current app).
+installSkills({ appDir: findAppRoot(process.cwd()) });
+
 switch (command) {
   case "login":
     await login();
@@ -460,17 +569,34 @@ switch (command) {
   case "docs":
     await docs();
     break;
+  case "current":
+    current();
+    break;
+  case "select":
+    select();
+    break;
+  case "apps":
+    apps();
+    break;
+  case "skills":
+    installSkills({ appDir: findAppRoot(process.cwd()), silent: false });
+    console.log("skills: up to date");
+    break;
   case "deploy":
     await deploy();
     break;
   default:
-    console.log("usage: monty <login|create|dev|add|components|docs|deploy>");
+    console.log("usage: monty <login|create|current|select|apps|dev|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]   stamp a new app into ~/Monty/<slug>");
     console.log("  dev         [--port 5173]                  run the app locally (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("  deploy                                      build + upload this app");
+    console.log("  skills                                      install/refresh the agent build skill");
     process.exit(command ? 1 : 0);
 }

package/bin/postinstall.mjs

@@ -0,0 +1,24 @@
+// Best-effort: put the agent build skill where Claude Code looks for it
+// (~/.claude/skills) as soon as the package lands. Never fails the install;
+// set MONTY_NO_SKILLS=1 to opt out. `monty skills` re-runs this any time.
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+try {
+  if (process.env.MONTY_NO_SKILLS || process.env.CI) process.exit(0);
+  const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const src = join(root, "skills");
+  if (!existsSync(src)) process.exit(0);
+  const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+  const target = join(homedir(), ".claude", "skills");
+  mkdirSync(target, { recursive: true });
+  for (const name of readdirSync(src)) {
+    cpSync(join(src, name), join(target, name), { recursive: true });
+    writeFileSync(join(target, name, "VERSION"), version + "\n");
+  }
+  console.log(`monty: agent skill installed (~/.claude/skills, v${version})`);
+} catch {
+  /* silent — skills are a convenience, not a dependency */
+}

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@montytools/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "bin": {
     "monty": "./bin/monty.mjs"
   },
   "files": [
     "bin",
-    "template"
+    "template",
+    "skills"
   ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
     "prepack": "node scripts/bundle-template.mjs",
-    "typecheck": "node --check bin/monty.mjs"
+    "typecheck": "node --check bin/monty.mjs",
+    "postinstall": "node bin/postinstall.mjs"
   },
   "dependencies": {
     "esbuild": "^0.28.1"

package/skills/monty-build/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: monty-build
+description: Build, run, and deploy Monty workspace apps. Use whenever the task involves a Monty app, monty.config.ts, the monty CLI (create/dev/deploy/add), 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.
+
+## Rules
+
+1. **Folders are managed.** Apps live in `~/Monty/<slug>`. `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.
+2. **The loop:** `monty create <slug> --name "Name" --icon <lucide-icon>` →
+   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
+   `@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`,
+   `createdBy` are reserved. Push happens automatically on dev/deploy.
+5. **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
+   `[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
+   team records are never touched, so exercise the app for real.
+
+## CLI reference
+
+| command | purpose |
+|---|---|
+| `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 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

@@ -4,6 +4,8 @@ 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.
+
 ## The three files that matter
 
 | File | What it is |