flet-box 1.0.4 → 1.0.6

package/bin/commands/create.js

@@ -17,6 +17,7 @@ import { fileURLToPath } from "url";
 import { createFile, copyFile, makeExecutable } from "../utils/helpers.js";
 import * as templates from "../utils/templates.js";
 import { parseGithubRepo } from "../utils/bundleConfig.js";
+import { checkApi } from "../commands/checkApi.js";
 import { c, banner, gradient } from "../utils/colors.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -179,6 +180,11 @@ export const createProject = async (projectName, rawArgs = []) => {
     "src",
     "src/assets/fonts",
     "src/database",
+    // AI agent contract: rules, memory and the generated API cheatsheet.
+    ".fletbox/api",
+    ".fletbox/memory/notes",
+    ".claude",
+    ".cursor/rules",
   ];
   const extraDirs =
     template === "blank" ? [] : ["src/screens", "src/components"];
@@ -291,16 +297,16 @@ export const createProject = async (projectName, rawArgs = []) => {
       path.join(projectPath, "src/screens/AboutScreen.js"),
       templates.aboutScreenJs(),
     );
+    // Barrel export so app.js and screens can import all screens from one place.
+    createFile(
+      path.join(projectPath, "src/screens/index.js"),
+      templates.screensIndexJs(template),
+    );
     if (template === "adaptive") {
       createFile(
         path.join(projectPath, "src/screens/ProfileScreen.js"),
         templates.profileScreenJs(),
       );
-      // Barrel export so app.js can import all screens from one place.
-      createFile(
-        path.join(projectPath, "src/screens/index.js"),
-        templates.screensIndexJs(),
-      );
     }
     // Layout components (skipped for blank).
     if (template !== "blank") {
@@ -365,11 +371,70 @@ export const createProject = async (projectName, rawArgs = []) => {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // AI agent contract (AGENTS.md + pointers + memory + checker)
+  // ---------------------------------------------------------------------------
+  // Written into every app so an AI editing it looks APIs up instead of inventing
+  // them, and has a machine gate that proves it right or wrong offline.
+  const pkgVersion = (() => {
+    try {
+      return JSON.parse(
+        fs.readFileSync(path.join(sourcePackageDir, "package.json"), "utf8"),
+      ).version;
+    } catch {
+      return "unknown";
+    }
+  })();
+
+  createFile(
+    path.join(projectPath, "AGENTS.md"),
+    templates.agentsMd(finalName, template, pkgVersion),
+  );
+  createFile(
+    path.join(projectPath, ".claude/CLAUDE.md"),
+    templates.claudeMd(),
+  );
+  createFile(
+    path.join(projectPath, ".cursor/rules/fletbox.mdc"),
+    templates.cursorRules(),
+  );
+  createFile(
+    path.join(projectPath, ".fletbox/memory/MEMORY.md"),
+    templates.memoryIndexMd(finalName),
+  );
+  createFile(
+    path.join(projectPath, ".fletbox/memory/notes/baseline.md"),
+    templates.memoryBaselineMd(finalName, template, pkgVersion),
+  );
+  createFile(
+    path.join(projectPath, "scripts/check-app.mjs"),
+    templates.checkAppScript(finalName),
+  );
+
+  // Generate the API cheatsheet from the framework the CLI was installed with.
+  // `npm install` is not required here: check-api resolves the package sources
+  // from its own copy, so a fresh app can be validated fully offline.
+  await checkApi(["--emit-api", "--root", projectPath], {
+    print: (line) => console.log(line),
+  });
+
   makeExecutable(path.join(projectPath, "run.sh"));
 
   console.log(
     `\n${gradient(` ✅ Project "${finalName}" created successfully!`, "#34d399", "#22d3ee")}\n`,
   );
+
+  // Prove the starter code passes the gate the agent will be held to.
+  const { exitCode } = await checkApi(["--root", projectPath]);
+  if (exitCode !== 0) {
+    console.warn(
+      c(
+        "yellow",
+        `⚠️  Starter code reported issues — check-api exited ${exitCode}. Fix them before building on top.`,
+      ),
+    );
+  }
+
   console.log(`  ${c("brightCyan", "cd")} ${finalName}`);
   console.log(`  ${c("brightCyan", "npm install")}`);
   console.log(`  ${c("brightCyan", "npm run dev")}\n`);
@@ -403,4 +468,11 @@ export const createProject = async (projectName, rawArgs = []) => {
         "         Enable GitHub Pages (Settings → Pages → Source: GitHub Actions) for the web preview.\n",
     ),
   );
+  console.log(
+    c(
+      "gray",
+      "AI:      AGENTS.md is the contract for any assistant editing this app.\n" +
+        "         npm run check verifies every widget/prop against the installed package.\n",
+    ),
+  );
 };

package/bin/utils/dtsProps.js

@@ -0,0 +1,191 @@
+// bin/utils/dtsProps.js
+// ============================================================
+// MINIMAL `.d.ts` INTERFACE READER FOR THE CLI VALIDATOR
+// ============================================================
+// A generated app cannot build TypeScript, so the CLI derives the declared API
+// straight from the shipped `src/index.d.ts` text. This parser understands the
+// subset the file actually uses:
+//
+//   export interface ButtonProps extends CommonProps {
+//     text?: string;
+//     items: Array<{ icon: string; label?: string }>;
+//   }
+//   export interface GridViewProps extends Omit<ListViewProps, 'wrapItems'> {}
+//
+// It is deliberately forgiving: an unparseable member is skipped instead of
+// throwing, because a partial API list still catches invented props, which is
+// the whole point of `flet-box check-api`.
+// ============================================================
+
+/**
+ * Split a brace-matched region into top-level interface members.
+ *
+ * Semicolons and newlines only end a member when every bracket, brace, paren
+ * and type-argument list is closed, so `Array<{ a: number; b: number }>` stays
+ * one member instead of two.
+ *
+ * @param {string} body Text between the interface's outer braces.
+ * @returns {string[]} Member sources, comments still attached.
+ */
+const splitMembers = (body) => {
+  const members = [];
+  let depth = 0;
+  let current = "";
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    // `=>` is an arrow, not a closed type-argument list: consuming the `>` here
+    // is what made every prop after the first callback type vanish.
+    if (ch === "=" && body[i + 1] === ">") {
+      current += "=>";
+      i++;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(" || ch === "<") depth++;
+    else if (ch === "}" || ch === "]" || ch === ")" || ch === ">") depth--;
+    else if (depth === 0 && (ch === ";" || ch === "\n")) {
+      if (current.trim()) members.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) members.push(current.trim());
+  return members;
+};
+
+/**
+ * Parse `extends A, Omit<B, 'x' | 'y'>` into structured parents.
+ *
+ * @param {string} clause Everything between `extends` and the opening brace.
+ * @returns {Array<{ name: string, omit: string[] }>}
+ */
+export const parseExtendsClause = (clause) => {
+  if (!clause) return [];
+  // The captured clause still carries the keyword itself; leaving it in would
+  // resolve a parent named `extends` and silently drop all inherited props.
+  const text = clause.replace(/^\s*extends\s+/i, "");
+  const parents = [];
+  let depth = 0;
+  let current = "";
+  const parts = [];
+  for (const ch of text) {
+    if (ch === "<") depth++;
+    else if (ch === ">") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  parts.push(current);
+  for (const raw of parts) {
+    const text = raw.trim();
+    if (!text) continue;
+    const omit = /^Omit\s*<\s*([A-Za-z_$][\w$]*)\s*,\s*([^>]*)>/.exec(text);
+    if (omit) {
+      parents.push({
+        name: omit[1],
+        omit: [...omit[2].matchAll(/['"]([^'"]+)['"]/g)].map((m) => m[1]),
+      });
+      continue;
+    }
+    const plain = /^([A-Za-z_$][\w$]*)/.exec(text);
+    if (plain) parents.push({ name: plain[1], omit: [] });
+  }
+  return parents;
+};
+
+/**
+ * Read every `interface`/`type X = { ... }` declaration out of a `.d.ts` source.
+ *
+ * @param {string} source Full file text.
+ * @returns {Map<string, { parents: Array<{ name: string, omit: string[] }>, props: Map<string, { type: string, optional: boolean }> }>}
+ */
+export const parseInterfaces = (source) => {
+  const interfaces = new Map();
+  // Comments can contain `interface` in prose; strip them first so brace
+  // matching never starts on a documentation example.
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+  const header =
+    /(export\s+)?(?:declare\s+)?(?:interface\s+([A-Za-z_$][\w$]*)|type\s+([A-Za-z_$][\w$]*)\s*=\s*)([^{]*)\{/g;
+  let match;
+  while ((match = header.exec(code))) {
+    const name = match[2] || match[3];
+    if (!name) continue;
+    const clause = match[4] || "";
+    const open = match.index + match[0].length - 1;
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < code.length; i++) {
+      if (code[i] === "{") depth++;
+      else if (code[i] === "}") {
+        depth--;
+        if (depth === 0) {
+          close = i;
+          break;
+        }
+      }
+    }
+    if (close < 0) continue;
+    const props = new Map();
+    for (const member of splitMembers(code.slice(open + 1, close))) {
+      const field = /^['"]?([A-Za-z_$][\w$]*)['"]?\s*(\?)?\s*:\s*([\s\S]+)$/.exec(
+        member.replace(/\s+/g, " ").trim(),
+      );
+      if (!field) continue;
+      props.set(field[1], {
+        type: field[3].replace(/;$/, "").trim(),
+        optional: field[2] === "?",
+      });
+    }
+    interfaces.set(name, { parents: parseExtendsClause(clause), props });
+    header.lastIndex = close;
+  }
+  return interfaces;
+};
+
+/**
+ * Flatten an interface with its inheritance chain, honouring `Omit<...>`.
+ *
+ * @param {Map} interfaces Output of `parseInterfaces`.
+ * @param {string} name Interface to resolve.
+ * @param {Set<string>} [seen] Guard against a cyclic `extends`.
+ * @returns {Map<string, { type: string, optional: boolean, declaredBy: string }>}
+ */
+export const resolveInterfaceProps = (interfaces, name, seen = new Set()) => {
+  const resolved = new Map();
+  if (seen.has(name)) return resolved;
+  seen.add(name);
+  const entry = interfaces.get(name);
+  if (!entry) return resolved;
+  for (const parent of entry.parents) {
+    const inherited = resolveInterfaceProps(interfaces, parent.name, seen);
+    for (const [prop, info] of inherited) {
+      if (parent.omit.includes(prop)) continue;
+      if (!resolved.has(prop)) resolved.set(prop, info);
+    }
+  }
+  for (const [prop, info] of entry.props) {
+    resolved.set(prop, { ...info, declaredBy: name });
+  }
+  return resolved;
+};
+
+/**
+ * Find the declaration that types a widget's props object.
+ *
+ * `AppBar` is typed by `AppBarProps`; a few widgets reuse another widget's
+ * interface, so the search also accepts the first `<Name>Props` that exists.
+ *
+ * @param {Map} interfaces
+ * @param {string} widgetName Exported widget name.
+ * @returns {string | null}
+ */
+export const propsInterfaceFor = (interfaces, widgetName) => {
+  const direct = `${widgetName}Props`;
+  if (interfaces.has(direct)) return direct;
+  const alt = `${widgetName}Options`;
+  if (interfaces.has(alt)) return alt;
+  return null;
+};

package/bin/utils/moduleExports.js

@@ -0,0 +1,165 @@
+/**
+ * @file bin/utils/moduleExports.js
+ * @description Resolve a relative import to the export surface of the file it
+ * points at, so `check-api` can catch broken wiring between an app's own
+ * modules — the failure class a flet-box-only API check cannot see.
+ *
+ * This is a static reader, not a module loader: it never executes app code, so
+ * it works offline, in CI, and on files that would throw at import time.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { neutralise } from "./neutralise.js";
+
+const IDENT = "[A-Za-z_$][\\w$]*";
+
+/**
+ * Resolve a relative/absolute specifier the way the browser ESM loader would,
+ * for the conventions this project enforces (explicit `.js` extensions).
+ *
+ * @param {string} fromFile Absolute path of the importing file.
+ * @param {string} spec The raw specifier, e.g. `./screens/HomeScreen.js`.
+ * @returns {string|null} Absolute path, or null when nothing matches.
+ */
+export const resolveLocalModule = (fromFile, spec) => {
+  if (!spec.startsWith(".") && !spec.startsWith("/")) return null;
+  const base = spec.startsWith("/")
+    ? spec.slice(1)
+    : path.resolve(path.dirname(fromFile), spec);
+  const candidates = /\.(m?js|json)$/.test(base)
+    ? [base]
+    : [`${base}.js`, `${base}.mjs`, path.join(base, "index.js")];
+  for (const candidate of candidates) {
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch {
+      /* keep looking */
+    }
+  }
+  return null;
+};
+
+/**
+ * @typedef {object} ModuleSurface
+ * @property {Set<string>} named Named exports, including names re-exported from
+ *   another module.
+ * @property {boolean} hasDefault Whether `export default` appears.
+ * @property {boolean} opaque True when the surface could not be read completely,
+ *   so callers must not report missing names.
+ */
+
+const emptySurface = (opaque) => ({
+  named: new Set(),
+  hasDefault: false,
+  opaque,
+});
+
+/**
+ * Read the export surface of a local module, following re-exports.
+ *
+ * @param {string} absFile Absolute path of the module.
+ * @param {Map<string, ModuleSurface>} [cache] Shared cache for the whole scan.
+ * @param {Set<string>} [chain] Modules being resolved right now, for cycles.
+ * @returns {ModuleSurface}
+ */
+export const readModuleExports = (absFile, cache = new Map(), chain = new Set()) => {
+  if (cache.has(absFile)) return cache.get(absFile);
+  // index.js -> Screen.js -> index.js must not recurse forever. Returning an
+  // opaque throwaway keeps the caller from reporting names the cycle does export.
+  if (chain.has(absFile)) return emptySurface(true);
+
+  const surface = emptySurface(false);
+  let raw;
+  try {
+    raw = fs.readFileSync(absFile, "utf8");
+  } catch {
+    surface.opaque = true;
+    return surface;
+  }
+  const code = neutralise(raw, { keepStrings: true });
+
+  // export default / export default function|class NAME
+  if (new RegExp(`export\\s+default\\b`).test(code)) surface.hasDefault = true;
+
+  // export const|let|var|function|class NAME  (incl. multi-declarator and async)
+  const declRe = new RegExp(
+    `export\\s+(?:async\\s+)?(?:const|let|var|function|class)\\s+(${IDENT})`,
+    "g",
+  );
+  let decl;
+  while ((decl = declRe.exec(code))) {
+    surface.named.add(decl[1]);
+    // `export const a = 1, b = 2;` — only accept a later name when it is
+    // immediately assigned, so type-ish commas cannot invent an export.
+    const tail = code.slice(decl.index + decl[0].length, code.indexOf(";", decl.index));
+    const extraRe = new RegExp(`,\\s*(${IDENT})\\s*=`, "g");
+    let extra;
+    while ((extra = extraRe.exec(tail))) surface.named.add(extra[1]);
+  }
+
+  // export { A, B as C } [from './mod.js']
+  const bracesRe = /export\s*\{([^}]*)\}(\s*from\s*['"]([^'"]+)['"])?/g;
+  let braces;
+  while ((braces = bracesRe.exec(code))) {
+    const source = braces[3];
+    let fromSurface = null;
+    if (source) {
+      const target = resolveLocalModule(absFile, source);
+      // A specifier that is not local (a package re-export) is taken on trust:
+      // guessing here would produce false alarms about the app's own files.
+      if (target) {
+        chain.add(absFile);
+        fromSurface = readModuleExports(target, cache, chain);
+        chain.delete(absFile);
+      } else if (!source.startsWith(".")) {
+        fromSurface = emptySurface(true);
+      }
+    }
+    for (const part of braces[1].split(",")) {
+      const token = part.trim();
+      if (!token) continue;
+      const aliased = new RegExp(`^(${IDENT})\\s+as\\s+(${IDENT})$`).exec(token);
+      const original = aliased ? aliased[1] : token;
+      const exportedAs = aliased ? aliased[2] : token;
+      if (original === "default") {
+        if (!source) surface.hasDefault = true;
+        else surface.named.add(exportedAs);
+        continue;
+      }
+      if (!source) {
+        surface.named.add(exportedAs);
+      } else if (fromSurface && !fromSurface.opaque) {
+        if (fromSurface.named.has(original)) surface.named.add(exportedAs);
+      } else {
+        surface.named.add(exportedAs);
+      }
+    }
+  }
+
+  // export * [as NS] from './mod.js'
+  const starRe = new RegExp(
+    `export\\s+\\*\\s*(?:as\\s+(${IDENT})\\s+)?from\\s*['"]([^'"]+)['"]`,
+    "g",
+  );
+  let star;
+  while ((star = starRe.exec(code))) {
+    if (star[1]) {
+      surface.named.add(star[1]);
+      continue;
+    }
+    const target = resolveLocalModule(absFile, star[2]);
+    if (!target) {
+      if (!star[2].startsWith(".")) surface.opaque = true;
+      continue;
+    }
+    chain.add(absFile);
+    const fromSurface = readModuleExports(target, cache, chain);
+    chain.delete(absFile);
+    for (const name of fromSurface.named) surface.named.add(name);
+    if (fromSurface.opaque) surface.opaque = true;
+  }
+
+  cache.set(absFile, surface);
+  return surface;
+};

package/bin/utils/neutralise.js

@@ -0,0 +1,64 @@
+/**
+ * @file bin/utils/neutralise.js
+ * @description Comment/string stripper that preserves character offsets.
+ */
+
+/**
+ * Strip comments, and optionally string bodies, keeping character offsets.
+ *
+ * Two passes are needed: imports must read their module specifier, while the
+ * call-site scanner must not see braces inside string literals. String contents
+ * are replaced by an equal-length filler so line numbers stay correct.
+ *
+ * @param {string} code
+ * @param {{ keepStrings?: boolean }} [options]
+ * @returns {string}
+ */
+export const neutralise = (code, { keepStrings = false } = {}) => {
+  let out = "";
+  let i = 0;
+  while (i < code.length) {
+    const ch = code[i];
+    const next = code[i + 1];
+    if (ch === "/" && next === "/") {
+      while (i < code.length && code[i] !== "\n") {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      while (i < code.length && !(code[i] === "*" && code[i + 1] === "/")) {
+        out += code[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      out += "  ";
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      out += ch;
+      i++;
+      while (i < code.length) {
+        if (code[i] === "\\") {
+          out += keepStrings ? code.slice(i, i + 2) : "  ";
+          i += 2;
+          continue;
+        }
+        if (code[i] === quote) {
+          out += quote;
+          i++;
+          break;
+        }
+        const fill = keepStrings ? code[i] : code[i] === "\n" ? "\n" : " ";
+        out += fill;
+        i++;
+      }
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+};