@montytools/cli 0.5.5 → 0.5.6

package/lib/schemaCodegen.mjs

@@ -220,9 +220,13 @@ export function manifestToConfig(manifest, { name, icon } = {}) {
     ...sdkImports.map((n) => `  ${n},`),
     `} from "@montytools/sdk";`,
     ``,
-    `// 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).`,
+    `// GENERATED by Monty from the app's config stored in the workspace.`,
+    `// DO NOT EDIT: edits here never land anywhere, and this file is`,
+    `// overwritten on every sync (a running \`monty dev\` regenerates it within`,
+    `// a heartbeat of a remote change; \`monty save\` and \`monty schema pull\``,
+    `// refresh it too). Change the app through the doors instead:`,
+    `// \`monty schema set\`, the MCP schema_update tool, or Configuration.`,
+    `// Import { app } from it for typed SDK hooks — that part is yours.`,
     `export const app = defineApp({`,
     `  slug: ${JSON.stringify(manifest.slug)},`,
     ...(name ? [`  name: ${JSON.stringify(name)},`] : []),

package/lib/schemaPull.mjs

@@ -1,16 +1,17 @@
-// `monty schema pull` — regenerate monty.config.ts from the app's stored
-// Live manifest (the schema-as-data flow: another agent may have edited the
-// schema via the API/MCP; this brings the code checkout back in sync).
-// Distinct from `monty pull`, which restores the whole SOURCE SNAPSHOT.
+// `monty schema pull` — regenerate src/monty.gen.ts from the app's stored
+// manifest (the schema-as-data flow: the workspace owns the config; this
+// file is its generated, never-hand-edited mirror, giving app code typed
+// SDK hooks and the runtime zod schemas). Distinct from `monty pull`,
+// which restores the whole SOURCE SNAPSHOT.
 //
-// Safety: refuses when the local config has schema changes that never
-// reached the registry (compile-and-compare against the base hash recorded
-// in .monty/schema.json) — "deploy or discard", like git with a dirty tree.
-// The old file is backed up beside the new one on every overwrite.
+// No dirty check, no backup: the gen module is not an editor — nothing in
+// it can be "local changes" — so regeneration is a plain overwrite. The
+// same call runs from the dev-session heartbeat (a remote schema edit
+// lands here within ~30s) and from `monty save`/`monty connect`.
 
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { manifestHash, manifestToConfig } from "./schemaCodegen.mjs";
+import { manifestToConfig } from "./schemaCodegen.mjs";
 
 const STATE_FILE = ["schema.json"]; // .monty/schema.json
 
@@ -31,7 +32,20 @@ export function writeSchemaState(appDir, hash) {
   writeFileSync(join(dir, ...STATE_FILE), JSON.stringify({ hash, syncedAt: Date.now() }) + "\n");
 }
 
-export async function schemaPull({ appDir, host, key, slug, force, compileAppConfig, fail }) {
+/** Write src/monty.gen.ts from a manifest. Only apps with code get the
+ * module (a config-only folder has nothing that could import it). Returns
+ * whether a file was written. */
+export function writeGenModule(appDir, manifest, { name, icon } = {}) {
+  const srcDir = join(appDir, "src");
+  if (!existsSync(srcDir)) return false;
+  writeFileSync(
+    join(srcDir, "monty.gen.ts"),
+    manifestToConfig(manifest, { name, icon: icon ?? undefined }),
+  );
+  return true;
+}
+
+export async function schemaPull({ appDir, host, key, slug, quiet, fail }) {
   const res = await fetch(`${host}/api/schema?slug=${encodeURIComponent(slug)}`, {
     headers: { authorization: `Bearer ${key}` },
   });
@@ -39,45 +53,17 @@ export async function schemaPull({ appDir, host, key, slug, force, compileAppCon
   if (!res.ok || !body?.ok) {
     fail(body?.code ?? `HTTP_${res.status}`, body?.fix ?? "Could not fetch the app's schema — check the connection and `monty login`.");
   }
-  if (!body.manifest) {
-    fail(
-      "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.`,
+  // An empty registry config is still a config — generate from it.
+  const manifest = body.manifest ?? { slug, tables: {} };
+  const wrote = writeGenModule(appDir, manifest, { name: body.name, icon: body.icon });
+  if (body.hash) writeSchemaState(appDir, body.hash);
+  if (!quiet) {
+    console.log(
+      wrote
+        ? `schema: pulled "${slug}" (${Object.keys(manifest.tables ?? {}).length} tables) -> src/monty.gen.ts`
+        : `schema: "${slug}" synced (config-only app — no code, no gen module; read it with \`monty schema\`)`,
     );
+    if (body.hash) console.log(`base:   ${body.hash.slice(0, 12)} (.monty/schema.json — the CAS base for the next push)`);
   }
-
-  const configPath = join(appDir, "monty.config.ts");
-  if (existsSync(configPath) && !force) {
-    // Dirty check: does the local config compile to the manifest this
-    // checkout last synced? If not, pulling would clobber local edits.
-    const state = readSchemaState(appDir);
-    let localHash = null;
-    try {
-      const compiled = await compileAppConfig(appDir);
-      localHash = compiled.manifest ? manifestHash(compiled.manifest) : null;
-    } catch {
-      // A config that doesn't compile can't be proven clean — refuse without
-      // --force rather than silently discarding whatever it holds.
-      fail(
-        "SCHEMA_DIRTY",
-        "monty.config.ts does not compile, so local schema edits cannot be verified against the registry. Fix it and deploy, or re-run with --force to REPLACE it (a .bak is kept).",
-      );
-    }
-    const cleanAgainst = state?.hash ?? body.hash;
-    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` or `monty save`), or discard them with --force (a .bak is kept).",
-      );
-    }
-  }
-
-  if (existsSync(configPath)) {
-    renameSync(configPath, `${configPath}.bak`);
-    console.log(`backup: monty.config.ts.bak`);
-  }
-  writeFileSync(configPath, manifestToConfig(body.manifest, { name: body.name, icon: body.icon ?? undefined }));
-  writeSchemaState(appDir, body.hash);
-  console.log(`schema: pulled "${slug}" (${Object.keys(body.manifest.tables).length} tables) -> monty.config.ts`);
-  console.log(`base:   ${body.hash.slice(0, 12)} (.monty/schema.json — the CAS base for the next push)`);
+  return { wrote, hash: body.hash ?? null, manifest };
 }

package/lib/styleLint.mjs

@@ -0,0 +1,175 @@
+// The Monty style lint — the platform's stylelint-polaris equivalent for
+// Tailwind class strings. Rules are disallow-lists grouped by category with
+// an instruction message per finding (Polaris's coverage-plugin shape); the
+// allowed vocabularies are IMPORTED from @monty/tokens/manifest.mjs so the
+// lint can never drift from the tokens. It runs blocking inside `monty save`
+// (beside the typecheck), advisory at `monty dev`, and standalone as
+// `monty style`.
+//
+// Scope: agent-authored app code only — src/**/*.{ts,tsx,jsx} minus the
+// vendored kit (src/components/ui/**), generated files, and wiring. A line
+// carrying `monty-style-ignore` is skipped (the stylelint-disable of this
+// system; use it for the rare sanctioned exception, never to silence a page).
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+let manifestPromise;
+function loadManifest() {
+  // Published tarball: prepack copies the manifest beside this file.
+  // Repo checkout: import straight from packages/tokens — the dependency
+  // direction that keeps rules derived from tokens.
+  manifestPromise ??= (async () => {
+    for (const p of [
+      join(HERE, "tokens-manifest.mjs"),
+      join(HERE, "../../tokens/manifest.mjs"),
+    ]) {
+      if (existsSync(p)) return import(pathToFileURL(p).href);
+    }
+    return null;
+  })();
+  return manifestPromise;
+}
+
+const SIDE = "(?:-(?:t|b|l|r|tl|tr|bl|br|s|e|ss|se|es|ee))?";
+const COLOR_PROPS = "(?:bg|text|border|ring|outline|fill|stroke|from|via|to|divide|decoration|caret|accent)";
+
+function buildRules(m) {
+  const hues = m.PALETTE_HUES.join("|");
+  return [
+    {
+      category: "type",
+      // Arbitrary sizes only — arbitrary COLOR values on text- belong to color.
+      re: /\btext-\[(?!#|rgb|hsl|oklch|var\(|color-mix)[^\]]+\]/g,
+      fix: () => "use the ladder (text-body is the default)",
+    },
+    {
+      category: "type",
+      re: /\btext-(?:xs|sm|base|lg|xl|[2-9]xl)\b/g,
+      fix: (got) => `use ${m.TEXT_SUGGESTIONS[got] ?? "the ladder"}`,
+    },
+    {
+      category: "weight",
+      re: /\bfont-(?:thin|extralight|light|bold|extrabold|black)\b/g,
+      fix: () => "use font-medium (or the weight the ladder style carries)",
+    },
+    {
+      category: "color",
+      re: new RegExp(`\\b${COLOR_PROPS}-\\[(?:#|rgb|hsl|oklch|var\\(|color-mix)[^\\]]*\\]`, "g"),
+      fix: () => "use a semantic token class",
+    },
+    {
+      category: "color",
+      re: new RegExp(`\\b${COLOR_PROPS}-(?:${hues})-\\d{2,3}(?:/\\d{1,3})?\\b`, "g"),
+      fix: (got) => {
+        const hue = got.match(new RegExp(`-(${hues})-`))?.[1];
+        return `use ${m.HUE_SUGGESTIONS[hue] ?? "a semantic token"}`;
+      },
+    },
+    {
+      category: "color",
+      re: /["'`]#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?["'`]/g,
+      fix: () => "use var(--chart-1…5) or a semantic class",
+    },
+    {
+      category: "radius",
+      re: new RegExp(`\\brounded${SIDE}-\\[[^\\]]+\\]`, "g"),
+      fix: () => "corners are sharp — delete it",
+    },
+    {
+      category: "radius",
+      re: new RegExp(`\\brounded${SIDE}-(?:xs|sm|md|lg|xl|[234]xl)\\b`, "g"),
+      fix: () => "corners are sharp — delete it (rounded-full only for dots/avatars)",
+    },
+    {
+      category: "elevation",
+      re: /\bshadow-\[[^\]]+\]/g,
+      fix: () => `use ${m.SHADOWS_ALLOWED.slice(0, 3).join("/")}`,
+    },
+    {
+      category: "elevation",
+      re: /\bshadow-(?:2xs|xs|sm|md|lg|xl|2xl|inner)\b/g,
+      fix: () => `use ${m.SHADOWS_ALLOWED.slice(0, 3).join("/")}`,
+    },
+  ];
+}
+
+const SKIP_FILES = new Set(["main.tsx", "vite-env.d.ts", "monty.gen.ts", "routeTree.gen.ts"]);
+
+function* sourceFiles(dir, base = dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const p = join(dir, entry.name);
+    const rel = relative(base, p);
+    if (entry.isDirectory()) {
+      // The vendored kit is template/registry-owned — its internals may
+      // legitimately carry classes agents must not write.
+      if (rel === join("components", "ui") || entry.name === "node_modules") continue;
+      yield* sourceFiles(p, base);
+    } else if (/\.(?:tsx|jsx|ts)$/.test(entry.name)) {
+      if (SKIP_FILES.has(entry.name) || entry.name.endsWith(".gen.ts")) continue;
+      yield p;
+    }
+  }
+}
+
+/** Scan an app folder. Returns [{ file, line, category, got, fix }] sorted
+ * by file then line; [] when clean (or when src/ doesn't exist —
+ * config-only apps have nothing to lint). */
+export async function lintStyles(appDir) {
+  const manifest = await loadManifest();
+  if (!manifest) return []; // never block a save on a broken lint install
+  const rules = buildRules(manifest);
+  const src = join(appDir, "src");
+  const violations = [];
+  for (const file of sourceFiles(src)) {
+    const rel = join("src", relative(src, file));
+    const lines = readFileSync(file, "utf8").split("\n");
+    lines.forEach((text, i) => {
+      if (text.includes("monty-style-ignore")) return;
+      for (const rule of rules) {
+        for (const match of text.matchAll(rule.re)) {
+          violations.push({
+            file: rel,
+            line: i + 1,
+            category: rule.category,
+            got: match[0],
+            fix: rule.fix(match[0]),
+          });
+        }
+      }
+    });
+  }
+  return violations.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+
+const MAX_LINES = 40;
+
+/** Findings grouped by category, each under its token-vocabulary lede. */
+export async function formatViolations(violations) {
+  const manifest = await loadManifest();
+  const byCategory = new Map();
+  for (const v of violations) {
+    if (!byCategory.has(v.category)) byCategory.set(v.category, []);
+    byCategory.get(v.category).push(v);
+  }
+  const out = [];
+  let shown = 0;
+  for (const [category, list] of byCategory) {
+    out.push(`${category} — ${manifest?.CATEGORY_MESSAGES?.[category] ?? ""}`);
+    for (const v of list) {
+      if (shown >= MAX_LINES) break;
+      out.push(`  ${v.file}:${v.line}  ${v.got} → ${v.fix}`);
+      shown++;
+    }
+  }
+  if (violations.length > shown) out.push(`  … and ${violations.length - shown} more`);
+  return out.join("\n");
+}

package/lib/tokens-manifest.mjs

@@ -0,0 +1,90 @@
+// The machine-readable half of the Monty design tokens (tokens.css is the
+// stylesheet). The style lint in the CLI derives its allowed lists and
+// suggestions from HERE — Polaris's pattern (stylelint-polaris imports
+// polaris-tokens) — so the rules can never drift from the tokens.
+// Keep this file in lockstep with tokens.css.
+
+/** The six text styles a Monty page uses. */
+export const TEXT_LADDER = [
+  "text-tick",
+  "text-meta",
+  "text-body",
+  "text-title",
+  "text-heading",
+  "text-stat",
+];
+
+/** What each off-ladder Tailwind size maps to. */
+export const TEXT_SUGGESTIONS = {
+  "text-xs": "text-meta",
+  "text-sm": "text-body (content) or text-title (titles)",
+  "text-base": "text-body",
+  "text-lg": "text-heading",
+  "text-xl": "text-heading",
+  "text-2xl": "text-stat",
+  "text-3xl": "text-stat",
+  "text-4xl": "text-stat",
+  "text-5xl": "text-stat",
+  "text-6xl": "text-stat",
+  "text-7xl": "text-stat",
+  "text-8xl": "text-stat",
+  "text-9xl": "text-stat",
+};
+
+/** Allowed font weights (400 default / 500 titled / 600 via heading+stat). */
+export const WEIGHTS_ALLOWED = ["font-normal", "font-medium", "font-semibold"];
+
+/** The radius policy: sharp everywhere; these are the only radius classes. */
+export const RADIUS_ALLOWED = [
+  "rounded-none",
+  "rounded-full",
+  "rounded-control",
+  "rounded-control-sm",
+  "rounded-overlay",
+];
+
+/** The only three shadows (plus shadow-none). */
+export const SHADOWS_ALLOWED = ["shadow-control", "shadow-btn-primary", "shadow-menu", "shadow-none"];
+
+/** Tailwind default palette hues — banned; the palette is the platform's. */
+export const PALETTE_HUES = [
+  "slate", "gray", "zinc", "neutral", "stone",
+  "red", "orange", "amber", "yellow", "lime",
+  "green", "emerald", "teal", "cyan", "sky",
+  "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose",
+];
+
+/** Where a banned hue should point instead. */
+export const HUE_SUGGESTIONS = {
+  red: "text-destructive / bg-destructive",
+  orange: "text-warning",
+  amber: "text-warning",
+  yellow: "text-warning",
+  lime: "text-success",
+  green: "text-success",
+  emerald: "text-success",
+  teal: "text-success",
+  blue: "bg-primary / text-link",
+  sky: "text-link",
+  indigo: "bg-primary",
+  cyan: "text-link",
+  violet: "var(--chart-3)",
+  purple: "var(--chart-3)",
+  fuchsia: "var(--chart-3)",
+  pink: "var(--chart-3)",
+  rose: "text-destructive",
+  slate: "text-muted-foreground / bg-accent",
+  gray: "text-muted-foreground / bg-accent",
+  zinc: "text-muted-foreground / bg-accent",
+  neutral: "text-muted-foreground / bg-accent",
+  stone: "text-muted-foreground / bg-accent",
+};
+
+/** Category ledes — the default instruction on each violation class. */
+export const CATEGORY_MESSAGES = {
+  type: "The type ladder is text-tick/meta/body/title/heading/stat; most text needs no size class at all (text-body is on <body>).",
+  weight: "Weights are 400/500/600 — font-medium for titled text; 600 arrives via text-heading/text-stat.",
+  color: "Colors come from the semantic tokens (bg-background, text-muted-foreground, var(--chart-2), …) — the palette is the platform's.",
+  radius: "Corners are sharp by policy; rounded-full (dots, avatars) is the one exception.",
+  elevation: "Elevation is shadow-control (rest controls), shadow-btn-primary (the one primary action), or shadow-menu (overlays).",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montytools/cli",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TomasMonty/monty-v2.git",
@@ -21,7 +21,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",
+    "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 && node --check lib/styleLint.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,6 +1,6 @@
 ---
 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/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.
+description: Build, run, and save Monty workspace apps. Use whenever the task involves a Monty app, its schema (monty schema / src/monty.gen.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
@@ -20,8 +20,8 @@ app states.
 
 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
+   folder you choose. Never mkdir an app folder by hand and never edit
+   `.monty/app.json` (the identity stamp). `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
@@ -53,8 +53,10 @@ app states.
    `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
+   server-side, additive by default). `src/monty.gen.ts` is the GENERATED
+   mirror of that config — import `{ app }` from it for typed hooks, never
+   edit it (it regenerates within a heartbeat of any change while
+   `monty dev` runs). 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