flet-box 1.0.9 → 1.1.0

package/bin/commands/checkUi.js

@@ -109,13 +109,54 @@ export const WARN_CODES = new Set([
   "UNCONSTRAINED_FORM_WIDTH",
 ]);
 
-const INFO_CODES = new Set([
+export const INFO_CODES = new Set([
   "SMALL_PRESET",
   "CROWDED_FORM",
   "LIST_WITHOUT_STATE",
   "MULTIPLE_PRIMARY_ACTIONS",
 ]);
 
+/**
+ * Which design rule each code proves, and the number the finding prints.
+ *
+ * The gate is the machine half of a contract whose human half is
+ * `skills/fletbox-design/SKILL.md`: 25 numbered rules, read by the agent that
+ * builds the screen. A finding that says `OFF_SCALE_SPACING` tells the reader the
+ * value is wrong; a finding that says `OFF_SCALE_SPACING — rule 07` tells them to
+ * open rule 07 and learn *why*, which is the only way the next screen is right
+ * without being told twice. `scripts/check-skills.mjs` fails if a code is missing
+ * here, if a number here is not a heading in the skill, or if the skill does not
+ * name that code inside the rule it is filed under — so this table and that file
+ * cannot drift apart.
+ */
+export const CODE_RULE = {
+  RAW_COLOR: "03",
+  OFF_SCALE_SPACING: "07",
+  OFF_SCALE_RADIUS: "03",
+  OFF_SCALE_TYPE: "08",
+  SMALL_TAP_TARGET: "03",
+  LOW_CONTRAST: "11",
+  UNLABELED_FIELD: "13",
+  UNLABELED_TOGGLE: "11",
+  DESTRUCTIVE_COLOR: "14",
+  UNREADABLE: "00",
+  LOW_CONTRAST_SOFT: "11",
+  LOW_CONTRAST_UI: "11",
+  LOW_CONTRAST_ON_SURFACE: "11",
+  HAND_MIXED_COLOR: "03",
+  DEAD_ELEVATION: "10",
+  IMAGE_NO_ALT: "11",
+  ICON_ONLY_CONTROL: "11",
+  CENTERED_BODY_TEXT: "08",
+  GENERIC_ACTION_LABEL: "14",
+  CONFIRM_ORDER: "14",
+  UNCONSTRAINED_FORM_WIDTH: "13",
+  SMALL_PRESET: "03",
+  CROWDED_FORM: "06",
+  LIST_WITHOUT_STATE: "12",
+  MULTIPLE_PRIMARY_ACTIONS: "04",
+};
+
 /**
  * The legal home for a hex value is the app's own token file. Anything else in
  * `src/` that types a color by hand is the drift this rule exists to catch.
@@ -1319,7 +1360,15 @@ export const checkUi = async (argv = [], io = {}) => {
 
   if (asJson) {
     print(
-      JSON.stringify({ package: api.pkg.version, scanned: files.length, findings }, null, 2),
+      JSON.stringify(
+        {
+          package: api.pkg.version,
+          scanned: files.length,
+          findings: findings.map((item) => ({ rule: CODE_RULE[item.code] || null, ...item })),
+        },
+        null,
+        2,
+      ),
     );
   } else {
     print(
@@ -1338,10 +1387,11 @@ export const checkUi = async (argv = [], io = {}) => {
       byCode.get(item.code).push(item);
     }
     for (const [code, list] of byCode) {
+      const rule = CODE_RULE[code];
       print(
         section(
           "•",
-          `${code} — ${list.length} finding(s)`,
+          `${code}${rule ? ` — rule ${rule}` : ""} — ${list.length} finding(s)`,
           ERROR_CODES.has(code) ? "#f87171" : INFO_CODES.has(code) ? "#94a3b8" : "#fbbf24",
         ),
       );

package/bin/commands/create.js

@@ -19,8 +19,16 @@ import * as templates from "../utils/templates.js";
 import { parseGithubRepo } from "../utils/bundleConfig.js";
 import { checkApi } from "../commands/checkApi.js";
 import { unpack } from "../commands/unpack.js";
+import { skillNames, readSkill } from "../utils/skills.js";
 import { c, banner, gradient } from "../utils/colors.js";
 
+/**
+ * Skills that every screen needs, whatever the task. Their Cursor twin rule loads
+ * with the file instead of waiting to be picked by description; the rest are
+ * read when their description matches what the agent is about to do.
+ */
+const ALWAYS_ON_SKILLS = new Set(["fletbox-rules", "fletbox-design"]);
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -216,8 +224,8 @@ export const createProject = async (projectName, rawArgs = []) => {
     ".fletbox/api",
     ".fletbox/memory/notes",
     ".claude",
-    ".claude/skills/fletbox-clean-ui",
-    ".qoder/skills/fletbox-clean-ui",
+    ".claude/skills",
+    ".qoder/skills",
     ".cursor/rules",
   ];
   const extraDirs =
@@ -437,23 +445,36 @@ export const createProject = async (projectName, rawArgs = []) => {
     templates.cursorRules(),
   );
 
-  // The clean-UI skill. Claude Code loads `.claude/skills/<name>/SKILL.md` by
-  // description, so the agent picks it up whenever it touches a screen without
-  // being told. `.qoder/skills/` holds a byte-identical copy because Qoder reads
-  // the same shape from a different root — one text, two loaders, never two edits.
-  const cleanUiSkill = templates.cleanUiSkill();
-  createFile(
-    path.join(projectPath, ".claude/skills/fletbox-clean-ui/SKILL.md"),
-    cleanUiSkill,
-  );
-  createFile(
-    path.join(projectPath, ".qoder/skills/fletbox-clean-ui/SKILL.md"),
-    cleanUiSkill,
-  );
-  createFile(
-    path.join(projectPath, ".cursor/rules/fletbox-clean-ui.mdc"),
-    templates.cleanUiCursorRule(),
-  );
+  // The agent skills: `skills/` at the package root is the only source, one
+  // kebab-case folder per subject (rules, design, motion, memory). The app gets
+  // the same text twice over: once as `skills/` at its own root — the folder any
+  // assistant or person reads first, and the one AGENTS.md §0 indexes — and once
+  // mirrored into `.claude/skills/` and `.qoder/skills/`, because Claude Code and
+  // Qoder load a skill by frontmatter description from those two roots and offer it
+  // without being told. Cursor has no skills folder, so each skill also ships as a
+  // pointer rule in `.cursor/rules/`. One text, three loaders, never three edits.
+  const skillList = skillNames();
+  if (skillList.length === 0) {
+    console.log(
+      c(
+        "yellow",
+        "⚠️  This flet-box package ships no skills/ folder — the app will have no design or motion contract.",
+      ),
+    );
+  }
+  for (const name of skillList) {
+    const text = readSkill(name);
+    createFile(path.join(projectPath, "skills", name, "SKILL.md"), text);
+    createFile(
+      path.join(projectPath, ".claude/skills", name, "SKILL.md"),
+      text,
+    );
+    createFile(path.join(projectPath, ".qoder/skills", name, "SKILL.md"), text);
+    createFile(
+      path.join(projectPath, ".cursor/rules", `${name}.mdc`),
+      templates.skillCursorRule(name, { alwaysApply: ALWAYS_ON_SKILLS.has(name) }),
+    );
+  }
   createFile(
     path.join(projectPath, "scripts/check-ui.mjs"),
     templates.checkUiScript(finalName),
@@ -467,6 +488,10 @@ export const createProject = async (projectName, rawArgs = []) => {
     path.join(projectPath, ".fletbox/memory/notes/baseline.md"),
     templates.memoryBaselineMd(finalName, template, pkgVersion),
   );
+  createFile(
+    path.join(projectPath, ".fletbox/memory/notes/current-status.md"),
+    templates.memoryStatusMd(finalName, template),
+  );
   createFile(
     path.join(projectPath, "scripts/check-app.mjs"),
     templates.checkAppScript(finalName),

package/bin/utils/skills.js

@@ -0,0 +1,59 @@
+// bin/utils/skills.js
+//
+// The `skills/` folder at the package root is the ONLY source for the agent
+// skills. Claude Code and Qoder load `.claude/skills/<name>/SKILL.md` and
+// `.qoder/skills/<name>/SKILL.md` by frontmatter description, so `flet-box create`
+// copies each file into both roots byte-for-byte. Keeping the text in a real
+// markdown file (instead of a 450-line array of strings in templates.js) means an
+// editor, a diff and `scripts/check-skills.mjs` can all read the same bytes the
+// agent will.
+//
+// Node core only: `bin/` may not import a devDependency at module scope.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** Absolute path of the folder that holds every shipped skill. */
+export const skillRoot = () => path.join(packageDir, "skills");
+
+/** Kebab-case folder names, sorted, skipping anything without a SKILL.md. */
+export const skillNames = () => {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(skillRoot(), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => fs.existsSync(path.join(skillRoot(), name, "SKILL.md")))
+    .sort();
+};
+
+/**
+ * The full skill text, frontmatter included.
+ * @throws when the skill does not exist — a missing skill is a build error, not
+ * a silent skip, or an app ships with half the contract and no one notices.
+ */
+export const readSkill = (name) =>
+  fs.readFileSync(path.join(skillRoot(), name, "SKILL.md"), "utf8");
+
+/** The `key: value` lines between the two `---` fences. */
+export const readFrontmatter = (name) => {
+  const text = readSkill(name);
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) throw new Error(`skill "${name}" has no frontmatter block`);
+  const fields = {};
+  for (const line of match[1].split("\n")) {
+    const pair = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+    if (pair) fields[pair[1]] = pair[2];
+  }
+  return fields;
+};
+
+/** One short sentence for a Cursor rule or an index: the description field. */
+export const skillDescription = (name) => readFrontmatter(name).description || name;