flet-box 1.1.2 → 1.1.3

package/bin/commands/create.js

@@ -20,6 +20,7 @@ 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 { CONTRACT_FILE, readContract } from "../utils/contract.js";
 import { c, banner, gradient } from "../utils/colors.js";
 
 /**
@@ -223,6 +224,7 @@ export const createProject = async (projectName, rawArgs = []) => {
     // AI agent contract: rules, memory and the generated API cheatsheet.
     ".fletbox/api",
     ".fletbox/memory/notes",
+    ".fletbox/metrics",
     ".claude",
     ".claude/skills",
     ".qoder/skills",
@@ -449,6 +451,12 @@ export const createProject = async (projectName, rawArgs = []) => {
     templates.cursorRules(),
   );
 
+  // The code-generation contract: one file at the package root, copied here
+  // byte-for-byte. AGENTS.md is this app's rules; this one is what an agent
+  // that *writes* code in the app must obey — the golden rule, the
+  // prohibitions, the ten design rules and the verification protocol.
+  createFile(path.join(projectPath, CONTRACT_FILE), readContract());
+
   // 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
@@ -496,6 +504,12 @@ export const createProject = async (projectName, rawArgs = []) => {
     path.join(projectPath, ".fletbox/memory/notes/current-status.md"),
     templates.memoryStatusMd(finalName, template),
   );
+  // The metrics log: one row per verify run, so the north metric can say how
+  // much of the generated code passed the gate with no correction at all.
+  createFile(
+    path.join(projectPath, ".fletbox/metrics/generations.md"),
+    templates.metricsLogMd(),
+  );
   createFile(
     path.join(projectPath, "scripts/check-app.mjs"),
     templates.checkAppScript(finalName),

package/bin/commands/createBundle.js

@@ -260,8 +260,8 @@ export const createBundle = async (targetArg) => {
   // Visual reference only: createBundle NEVER bumps the version — only
   // `flet-box release` does. Print what each release flag would produce so the
   // next version is visible at build time.
-  console.log(section("🔢", `Versión del bundle: ${appVersion}`, "#34d399"));
-  console.log(c("gray", "     Qué haría cada release:"));
+  console.log(section("🔢", `Bundle version: ${appVersion}`, "#34d399"));
+  console.log(c("gray", "     What each release would do:"));
   for (const [flag, type] of [
     ["--patch", "patch"],
     ["--minor", "minor"],

package/bin/commands/metrics.js

@@ -0,0 +1,448 @@
+/**
+ * @file bin/commands/metrics.js
+ * @description The north metric — how much generated code passes the gate with
+ * no correction at all.
+ *
+ * The rule this file exists to enforce is one line long: *do not optimise before
+ * measuring.* So every `flet-box verify` run appends a row to a log (see
+ * `recordGeneration` in `verify.js`), and this command reads those rows and
+ * answers two questions:
+ *
+ *   1. What share of the generated code passed the gate with no correction at
+ *      all? A **generation** is a run of failing rows closed by the first green
+ *      one — the rows before it are the corrections that were needed. The north
+ *      metric is the share of generations whose *first* run was green.
+ *   2. Which failures keep coming back? Those are the rules that have not been
+ *      written yet. Each one is printed with the rule that should own it, and a
+ *      code that recurs with no owner behind it **fails** this command: that is
+ *      the loop closing.
+ *   3. Was a failure the gate's own fault? A code can be recorded in the log's
+ *      "Gate defects" table with the window of runs it accounts for. Those runs
+ *      are the framework's debt, not a correction this project needed, so they
+ *      count as passes and never feed the rule loop. A run after the window's
+ *      `Fixed` day counts again: a defect that comes back cannot hide behind an
+ *      old row.
+ *
+ * Node core only: this file ships inside every app `flet-box create` builds.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { CODE_RULE } from "./checkUi.js";
+import { c } from "../utils/colors.js";
+
+/** How many times a code has to come back before it counts as a rule to write. */
+export const RECURRING = 3;
+
+/**
+ * Where a code should be taught, by the gate that reports it.
+ *
+ * A code without an owner is a rule that was never written: the gate proves the
+ * mistake happens, and nothing tells the next agent why it matters.
+ */
+export const OWNERS = {
+  CIRCULAR_IMPORT: "skills/fletbox-rules/SKILL.md R7 — one module, one direction",
+  SOURCE_OUTSIDE_ROOT: "skills/fletbox-rules/SKILL.md R7 — a module lives in src/",
+  HAND_WRITTEN_DOM: "skills/fletbox-rules/SKILL.md R7 — the engine is the only renderer",
+  UNKNOWN_EXPORT: "skills/fletbox-rules/SKILL.md R1 — FletBox only",
+  WRONG_STACK: "skills/fletbox-rules/SKILL.md R1 — FletBox only",
+  UNKNOWN_PROP: "skills/fletbox-rules/SKILL.md R2 — never invent an API",
+  POSITIONAL_ARG: "skills/fletbox-rules/SKILL.md R1 — a widget is a call with a props object",
+  MODULE_NOT_FOUND: "skills/fletbox-rules/SKILL.md R2 — look the module up",
+  MISSING_EXPORT: "skills/fletbox-rules/SKILL.md R2 — look the module up",
+  DEEP_IMPORT: "skills/fletbox-rules/SKILL.md R2 — import from the barrel",
+  UNDOCUMENTED_PROP: "src/index.d.ts — the declaration is the contract",
+  INVENTED_PROP: "src/index.d.ts — the declaration is the contract",
+  DEAD_PROP: "src/index.d.ts — the declaration or the widget",
+  GATE_FAILED: "the gate itself — a missing package, not a mistake in the code",
+  SYNTAX_ERROR: "the parser itself — the finding carries the line, the column and the hint",
+  TEST_SUITE_FAILED: "the project's own suite — run it alone, its failing line names the rule",
+  TYPE_ERROR: "skills/fletbox-rules/SKILL.md R2 — the declaration is the contract",
+};
+
+/**
+ * A code the gate itself got wrong, over a window of runs.
+ *
+ * The marker lives in the log, not in this file: it describes a moment in one
+ * project's history, and a table that hard-coded "MISSING_EXPORT is never the
+ * app's fault" would silence the real mistake the next time it happens.
+ *
+ * @typedef {object} GateDefect
+ * @property {string} code
+ * @property {string} seen First calendar day (YYYY-MM-DD) it accounts for.
+ * @property {string|null} fixed Last day it accounts for; null while it is open.
+ * @property {string} where Why the gate was wrong, and where the fix lives.
+ */
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const CODE = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Split a markdown table row into trimmed cells, or null when the line is not
+ * one. The log holds two tables and prose; both readers ignore the same lines.
+ *
+ * @param {string} line
+ * @returns {string[]|null}
+ */
+const cellsOf = (line) => {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("|")) return null;
+  return trimmed
+    .slice(1, trimmed.endsWith("|") ? -1 : undefined)
+    .split("|")
+    .map((cell) => cell.trim());
+};
+
+/**
+ * Read the "Gate defects" table out of a log's text.
+ *
+ * A run row starts with a timestamp and a registry row starts with a code, so
+ * the two tables share a file without either reader guessing.
+ *
+ * @param {string} text
+ * @returns {GateDefect[]}
+ */
+const parseDefectsFrom = (text) => {
+  const defects = [];
+  for (const line of text.split("\n")) {
+    const cells = cellsOf(line);
+    if (!cells || cells.length < 2) continue;
+    if (!CODE.test(cells[0]) || !DATE.test(cells[1])) continue;
+    defects.push({
+      code: cells[0],
+      seen: cells[1],
+      fixed: DATE.test(cells[2] || "") ? cells[2] : null,
+      where: cells.slice(3).join(" | ").trim(),
+    });
+  }
+  return defects;
+};
+
+/**
+ * Read the gate-defect records of a log file.
+ *
+ * @param {string} file
+ * @returns {GateDefect[]}
+ */
+export const parseDefects = (file) => parseDefectsFrom(fs.readFileSync(file, "utf8"));
+
+/**
+ * Whether a code was a gate defect on the day a run happened.
+ *
+ * @param {GateDefect[]} defects
+ * @param {string} code
+ * @param {string} when ISO timestamp of the run.
+ * @returns {boolean}
+ */
+export const gateDefect = (defects, code, when) => {
+  const day = when.slice(0, 10);
+  return defects.some(
+    (defect) =>
+      defect.code === code && day >= defect.seen && (!defect.fixed || day <= defect.fixed),
+  );
+};
+
+/**
+ * Split a row's codes into the gate's and this project's.
+ *
+ * A row that failed only because of a defect is exonerated: the correction it
+ * needed belonged to the framework, and holding it against the code under test
+ * is the metric lying about that code.
+ *
+ * @param {object} row
+ * @param {GateDefect[]} defects
+ * @returns {object}
+ */
+const classifyRow = (row, defects) => {
+  const defectCodes = row.codes.filter((code) => gateDefect(defects, code, row.when));
+  const appCodes = row.codes.filter((code) => !defectCodes.includes(code));
+  return {
+    ...row,
+    defectCodes,
+    appCodes,
+    exonerated: !row.ok && defectCodes.length > 0 && appCodes.length === 0,
+  };
+};
+
+/**
+ * The rule that owns a code.
+ *
+ * @param {string} code
+ * @returns {string|null} null when no rule owns it yet
+ */
+export const owner = (code) => {
+  if (OWNERS[code]) return OWNERS[code];
+  const rule = CODE_RULE[code];
+  return rule ? `skills/fletbox-design/SKILL.md rule ${rule}` : null;
+};
+
+/**
+ * Where a project's metrics log lives.
+ *
+ * A generated app keeps it under `.fletbox/`, next to the memory journal; the
+ * framework keeps it in `metrics/`. A project with no log is not measured —
+ * that is the whole point of the file existing.
+ *
+ * @param {string} root
+ * @returns {string|null}
+ */
+export const metricsLog = (root) => {
+  const candidates = [
+    path.join(root, ".fletbox", "metrics", "generations.md"),
+    path.join(root, "metrics", "generations.md"),
+  ];
+  return candidates.find((file) => fs.existsSync(file)) || null;
+};
+
+/**
+ * Read the rows of a metrics log.
+ *
+ * `codes` keeps everything the row reported; `defectCodes`, `appCodes` and
+ * `exonerated` come from the log's "Gate defects" table, so a caller can still
+ * see what happened without the metric charging it to the project.
+ *
+ * @param {string} file
+ * @returns {Array<{when: string, project: string, ok: boolean, gates: string, codes: string[], defectCodes: string[], appCodes: string[], exonerated: boolean}>}
+ */
+export const parseLog = (file) => {
+  const text = fs.readFileSync(file, "utf8");
+  const defects = parseDefectsFrom(text);
+  const rows = [];
+  for (const line of text.split("\n")) {
+    const cells = cellsOf(line);
+    if (!cells || cells.length < 5) continue;
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(cells[0])) continue;
+    rows.push(
+      classifyRow(
+        {
+          when: cells[0],
+          project: cells[1],
+          ok: cells[2] === "✓",
+          gates: cells[3],
+          codes: cells[4] === "—" ? [] : cells[4].split(",").map((code) => code.trim()),
+        },
+        defects,
+      ),
+    );
+  }
+  return rows;
+};
+
+/**
+ * Group the rows into generations: a run of failing rows closed by the first
+ * green one. A green row that follows a green row is its own generation.
+ *
+ * A run the gate itself failed is left out of the arithmetic: it measured
+ * nothing about the code under test, so counting it as a pass would move the
+ * number without the code getting better, and counting it as a correction
+ * would blame the project for the framework's defect.
+ *
+ * @param {Array<object>} rows
+ * @returns {Array<{project: string, firstTry: boolean, corrections: number, unfinished?: boolean}>}
+ */
+export const groupGenerations = (rows) => {
+  const byProject = new Map();
+  for (const row of rows) {
+    if (row.exonerated) continue;
+    if (!byProject.has(row.project)) byProject.set(row.project, []);
+    byProject.get(row.project).push(row);
+  }
+  const generations = [];
+  for (const [project, list] of byProject) {
+    let open = null;
+    for (const row of list) {
+      if (row.ok) {
+        generations.push({
+          project,
+          firstTry: !open,
+          corrections: open ? open.length : 0,
+        });
+        open = null;
+      } else {
+        open = open || [];
+        open.push(row);
+      }
+    }
+    if (open) {
+      generations.push({ project, firstTry: false, corrections: open.length, unfinished: true });
+    }
+  }
+  return generations;
+};
+
+/**
+ * Count how often each code was reported against the project — the occurrences
+ * the log's "Gate defects" table does not cover.
+ *
+ * @param {Array<object>} rows
+ * @returns {Map<string, number>}
+ */
+export const rankCodes = (rows) => {
+  const counts = new Map();
+  for (const row of rows) {
+    for (const code of row.appCodes ?? row.codes) {
+      counts.set(code, (counts.get(code) || 0) + 1);
+    }
+  }
+  return counts;
+};
+
+/**
+ * Count how often each gate defect accounted for a run.
+ *
+ * @param {Array<object>} rows
+ * @returns {Map<string, number>}
+ */
+export const rankDefects = (rows) => {
+  const counts = new Map();
+  for (const row of rows) {
+    for (const code of row.defectCodes ?? []) {
+      counts.set(code, (counts.get(code) || 0) + 1);
+    }
+  }
+  return counts;
+};
+
+/**
+ * The `flet-box metrics` command.
+ *
+ * @param {string[]} argv Flags after the command name.
+ * @param {{print?: (line: string) => void, root?: string}} [io]
+ * @returns {Promise<{exitCode: number, north: number, generations: number}>}
+ */
+export const metrics = async (argv = [], io = {}) => {
+  const print = io.print ?? ((line) => console.log(line));
+  const rootIndex = argv.indexOf("--root");
+  const root = path.resolve(
+    rootIndex >= 0 && argv[rootIndex + 1] ? argv[rootIndex + 1] : io.root || process.cwd(),
+  );
+  const logIndex = argv.indexOf("--log");
+  const file = logIndex >= 0 && argv[logIndex + 1]
+    ? path.resolve(argv[logIndex + 1])
+    : metricsLog(root);
+
+  if (!file || !fs.existsSync(file)) {
+    print(
+      c(
+        "yellow",
+        `📈 No metrics log yet — ${path.join(root, ".fletbox", "metrics", "generations.md")} does not exist.`,
+      ),
+    );
+    print(c("gray", "   Every `flet-box verify` run writes a row into it; run the gates once."));
+    return { exitCode: 0, north: 0, generations: 0 };
+  }
+
+  const rows = parseLog(file);
+  const generations = groupGenerations(rows);
+  const firstTry = generations.filter((generation) => generation.firstTry).length;
+  const north = generations.length ? firstTry / generations.length : 0;
+  const counts = rankCodes(rows);
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const defects = parseDefects(file);
+  const defectCounts = rankDefects(rows);
+  const exonerated = rows.filter((row) => row.exonerated).length;
+
+  print(c("brightCyan", `📈 ${path.relative(root, file) || file}`));
+  print(
+    c(
+      "gray",
+      generations.length
+        ? `   north metric — ${firstTry}/${generations.length} generation(s) passed with no correction (${(north * 100).toFixed(0)}%)`
+        : "   north metric — no generation to measure yet",
+    ),
+  );
+  print(c("gray", `   ${rows.length} run(s) logged`));
+  if (exonerated) {
+    print(
+      c(
+        "gray",
+        `   ${exonerated} run(s) failed only because of a gate defect — left out of the metric, not charged as a correction`,
+      ),
+    );
+  }
+
+  // The framework's debt, kept next to the number it distorts. A fixed defect
+  // stays on the record; an open one says the metric is measuring a broken gate.
+  if (defects.length) {
+    print("");
+    print(c("gray", "   gate defects — a code the gate reported, not the code it checked:"));
+    for (const defect of defects) {
+      const count = defectCounts.get(defect.code) || 0;
+      const status = defect.fixed ? `fixed ${defect.fixed}` : `⚠ OPEN since ${defect.seen}`;
+      print(
+        c(
+          defect.fixed ? "gray" : "yellow",
+          `   ${String(count).padStart(3)}× ${defect.code.padEnd(22)} ${status}${
+            defect.where ? ` · ${defect.where}` : ""
+          }`,
+        ),
+      );
+    }
+    const open = defects.filter((defect) => !defect.fixed);
+    if (open.length) {
+      print(
+        c(
+          "yellow",
+          `   ⚠ ${open.length} gate defect(s) still open — the metric is being read against a gate that is wrong.`,
+        ),
+      );
+    }
+  }
+
+  if (ranked.length) {
+    print("");
+    print(c("gray", "   the failures that come back, and the rule each one should own:"));
+    for (const [code, count] of ranked.slice(0, 3)) {
+      const where = owner(code);
+      print(
+        c(
+          "gray",
+          `   ${String(count).padStart(3)}× ${code.padEnd(22)} ${where || "— no rule owns this one yet"}`,
+        ),
+      );
+    }
+    // A code that comes back with a rule behind it is a different problem: the
+    // rule exists and the mistake still happens, so the rule is not landing.
+    // That is worth naming — it is the difference between "write the rule" and
+    // "make the rule impossible to miss".
+    const stubborn = ranked.filter(
+      ([code, count]) => count >= RECURRING && owner(code),
+    );
+    if (stubborn.length) {
+      print("");
+      for (const [code] of stubborn) {
+        print(
+          c(
+            "yellow",
+            `   ⚠ ${code} came back ${RECURRING} times with a rule behind it — the rule is not landing.`,
+          ),
+        );
+      }
+    }
+  }
+
+  const unowned = ranked.filter(([code, count]) => count >= RECURRING && !owner(code));
+  print("");
+  if (unowned.length) {
+    print(
+      c(
+        "red",
+        `❌ ${unowned.length} code(s) came back ${RECURRING} times or more and no rule owns them: ${unowned
+          .map(([code]) => code)
+          .join(", ")}`,
+      ),
+    );
+    print(
+      c(
+        "gray",
+        "   Write the rule where it belongs (the design skill, the rules skill, or the gate), then run again.",
+      ),
+    );
+    return { exitCode: 1, north, generations: generations.length };
+  }
+
+  print(c("green", "✅ every recurring failure has a rule behind it."));
+  return { exitCode: 0, north, generations: generations.length };
+};
+
+export default metrics;

package/bin/commands/release.js

@@ -29,6 +29,7 @@ import { c, banner, gradient } from "../utils/colors.js";
 import { createBundle } from "./createBundle.js";
 import { resolveUpdateUrl } from "../utils/bundleConfig.js";
 import { INITIAL_VERSION, incrementVersion, isValidVersion } from "../utils/version.js";
+import { isFrameworkProject, missingMigration } from "../utils/migrationGuide.js";
 
 /**
  * Runs a git command in `cwd`, returning trimmed stdout. Throws on failure.
@@ -109,6 +110,23 @@ export const release = async (argv = []) => {
   const current = isValidVersion(pkg.version) ? pkg.version : INITIAL_VERSION;
   const next = incrementVersion(current, type);
 
+  // ---- Guard: a major needs its migration guide ---------------------------
+  // A major is the release where an app has to change something, so the guide
+  // has to say what before the version exists. The guide belongs to the
+  // framework, so the guard never fires inside somebody's app.
+  if (type === "major" && isFrameworkProject(projectRoot)) {
+    const missing = missingMigration(next, projectRoot);
+    if (missing) {
+      console.error(c("red", `❌ The migration guide does not cover ${next}`));
+      console.log(c("gray", `   ${missing.reason}.`));
+      console.log(
+        c("gray", "   Add a section to docs/guides/migration.md that says what this major"),
+      );
+      console.log(c("gray", "   changes, one row per renamed or removed prop, then release again."));
+      process.exit(1);
+    }
+  }
+
   pkg.version = next;
   // Preserve the file's existing 2-space style + trailing newline.
   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");