flet-box 1.0.5 → 1.0.7

package/README.md

@@ -101,11 +101,38 @@ flet-box check-api                      # scan src/ for invented widgets/props
 flet-box check-api --props Button       # print the real props of one widget
 flet-box check-api --list               # print every public export
 flet-box check-api --emit-api           # (re)generate .fletbox/api/cheatsheet.md
+
+# Read one widget from every surface at once (offline)
+flet-box unpack Text                    # each prop, where it goes, and what is dead
+flet-box unpack Text --example          # a paste-ready call, built only from verified props
+flet-box unpack Modal --diff            # where types, engine, docs and code disagree
+flet-box unpack --all --md              # every widget, as .fletbox/api/api.json + api.md
+
+# Repair (writes files; run `npm run check` afterwards to confirm)
+flet-box audit-fix                      # fix imports and prop typos in one pass
+flet-box audit-fix --only imports       # just the import wiring
+flet-box audit-fix --only props         # just `chilldren` → `children`
 ```
 
 In a generated app these are also `npm run check` (and `npm run check -- --props Button`),
 because `flet-box create` writes `scripts/check-app.mjs` plus the `AGENTS.md` contract
-that points any AI assistant at the real API.
+that points any AI assistant at the real API. `npm run fix` runs `audit-fix`.
+
+`audit-fix` only rewrites a name when exactly one real name is close enough to be
+certain — a wrong "fix" that happens to be a valid prop changes the UI silently and
+silences the gate, which is worse than the error it replaced. Anything ambiguous is
+printed under *Left for you to decide* and the file is not touched.
+
+`flet-box unpack` answers the question the types alone cannot: a prop can be declared,
+documented and still reach nothing. It cross-checks the four places a prop lives —
+`src/index.d.ts`, the `ALL_PROPS` translation table, the widget's own source, its doc
+page — and labels each disagreement: **DEAD** (typed, read by nothing), **INVENTED**
+(read by the widget, declared nowhere), **UNDOCUMENTED** (the engine routes it, the
+interface hides it), **DOC-ONLY** and **CODE-ONLY** (the page and the code each promise
+something the other never heard of). `--example` uses only that verified set, so what it
+prints is the whole API you can safely paste; `unpack --all --json` writes the same facts
+as `.fletbox/api/api.json` for the AI agent inside an app, which is the surface it should
+invent against.
 
 ## Android and iOS
 

package/bin/cli.js

@@ -14,17 +14,19 @@ import fs from "fs";
 import path from "path";
 import { createProject } from "./commands/create.js";
 import { checkApi } from "./commands/checkApi.js";
+import { auditFix } from "./commands/auditFix.js";
+import { toPng } from "./commands/toPng.js";
+import { images } from "./commands/images.js";
+import { pruneAssets } from "./commands/pruneAssets.js";
+import { unpack } from "./commands/unpack.js";
 import { packageManager } from "./commands/package.js";
 import { createBundle } from "./commands/createBundle.js";
 import { buildAndroid } from "./commands/buildAndroid.js";
 import { buildIOS } from "./commands/buildIOS.js";
 import { runNative } from "./commands/runNative.js";
-import { runDevServer } from "./commands/runServer.js";
 import { createScreen } from "./commands/createScreen.js";
 import { createComponent } from "./commands/createComponent.js";
 import { killServer } from "./commands/killServer.js";
-import { runBundle } from "./commands/runBundle.js";
-import { runCloudflareDemo } from "./commands/runCloudflare.js";
 import { release } from "./commands/release.js";
 import { c, gradient, section, banner, divider, width, setupCtrlC } from "./utils/colors.js";
 
@@ -66,6 +68,7 @@ ${cmd("create --adaptive", "responsive (mobile + desktop)")}
 ${cmd("create --blank", "empty project")}
 ${cmd("create --full", "AppBar+Drawer+BottomNav")}
 ${cmd("create --sidebar", "desktop (Sidebar+AppBar)")}
+${cmd("create --template <name>", "same four by name: basic|adaptive|blank|full|sidebar")}
 ${cmd("create --repo <user/repo>", "set GitHub repo for OTA updates")}
 ${cmd("screen <name|num>", "Create screen(s) (1-10)")}
 ${cmd("component <name|num>", "Create component(s) (1-10)")}
@@ -79,6 +82,23 @@ ${cmd("   └─ --props <Widget>", "print one widget's real props")}
 ${cmd("   └─ --list", "list every widget")}
 ${cmd("   └─ --emit-api", "write .fletbox/api/cheatsheet.md")}
 ${cmd("   └─ alias", "check | checkApi | doctor")}
+${cmd("unpack <Widget>", "Everything one widget really accepts, and what works")}
+${cmd("   └─ --example", "paste-ready call using only verified props")}
+${cmd("   └─ --diff", "what the docs or types claim that the code ignores")}
+${cmd("   └─ unpack --all", "every widget; --json / --md write .fletbox/api/")}
+${cmd("audit-fix", "Rewrite broken imports, missing imports and misspelled props")}
+${cmd("   └─ --only imports|props", "run one repair instead of both")}
+${cmd("   └─ alias", "fix-imports | fix-path-imports | auditFix")}
+${cmd("to-png [dir]", "Convert JPEG/BMP/GIF images to PNG, no dependencies")}
+${cmd("   └─ --replace", "remove each source after its PNG was written and read back")}
+${cmd("   └─ --out <dir> | --force | --flat | --dry-run", "where to write, and what to touch")}
+${cmd("   └─ alias", "topng | convert-images")}
+${cmd("images [dir]", "Shrink JPG/PNG photos to a byte budget with the platform WebP encoder")}
+${cmd("   └─ --budget <KB> | --width <px>", "what 'small enough' means (default 40KB)")}
+${cmd("   └─ --install", "install the encoder this machine is missing")}
+${cmd("   └─ alias", "optimize-images | imgs")}
+${cmd("prune-assets [dir]", "Delete images the app never references (dry run unless --apply)")}
+${cmd("   └─ alias", "prune")}
 ${cmd("build android", "Build Android debug APK")}
 ${cmd("build android --release", "Build unsigned release APK/AAB to sign yourself")}
 ${cmd("build ios", "Build iOS Simulator app (macOS + Xcode)")}
@@ -89,7 +109,7 @@ ${cmd("   └─ --livereload", "hot reload on the device")}
 ${cmd("run", "Static file server")}
 ${cmd("run --hot", "Dev server with hot reload")}
 ${cmd("run-spa", "SPA + hot reload")}
-${cmd("cloudflare", "Serve demo on a public Cloudflare HTTPS tunnel")}
+${cmd("cloudflare [dir]", "Build the bundle, then tunnel it: public HTTPS demo link")}
 ${cmd("   └─ alias", "cf | demo | tunnel")}
 ${cmd("run-bundle [dir]", "Build & serve the bundle (single app.js)")}
 ${cmd("pkg", "Open the package manager")}
@@ -113,6 +133,8 @@ ${section("✨", "EXAMPLES")}
   ${c("gray", "cd my-app && flet-box run-spa")}
   ${c("gray", "flet-box run-bundle            # build & preview production")}
   ${c("gray", "flet-box cloudflare            # public HTTPS demo link in console")}
+  ${c("gray", "flet-box unpack Text --example # what Text really accepts, as code")}
+  ${c("gray", "flet-box unpack --all --json   # dump the verified API for your AI agent")}
   ${c("gray", "flet-box kill-server 8000      # kill the parasite server")}
 
 ${divider("", "#3730a3")}
@@ -168,6 +190,16 @@ const parseFlags = () => {
   return flags;
 };
 
+/**
+ * The bundle directory a command works on: the second argument when it is a
+ * plain name, `www` otherwise. Flags never reach here, so `flet-box cloudflare
+ * --port 9000` cannot mistake `--port` for a target.
+ *
+ * @returns {string}
+ */
+const bundleTarget = () =>
+  args[1] && /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/.test(args[1]) ? args[1] : "www";
+
 /**
  * Guards commands that must run inside a FletBox project directory.
  * Exits with a descriptive error when `src/app.js` is not found in the
@@ -210,7 +242,7 @@ async function main() {
           console.log(
             c(
               "gray",
-              "Usage: flet-box create <project-name> [--adaptive|--blank|--full|--sidebar|--repo user/repo]",
+              "Usage: flet-box create <project-name> [--adaptive|--blank|--full|--sidebar|--template <name>|--repo user/repo]",
             ),
           );
           process.exit(1);
@@ -277,6 +309,44 @@ async function main() {
         break;
       }
 
+      case "unpack": {
+        const { exitCode } = await unpack(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "audit-fix":
+      case "auditFix":
+      case "fix-imports":
+      case "fix-path-imports": {
+        const { exitCode } = await auditFix(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "to-png":
+      case "topng":
+      case "convert-images": {
+        const { exitCode } = await toPng(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "images":
+      case "optimize-images":
+      case "imgs": {
+        const { exitCode } = await images(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "prune-assets":
+      case "prune": {
+        const { exitCode } = await pruneAssets(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
       case "build":
         if (args[1] === "android") {
           buildAndroid(args.slice(2));
@@ -323,7 +393,11 @@ async function main() {
           runNative(args.slice(1));
           break;
         }
-        await runDevServer({
+        // The server commands are the only ones that pull in `ws`/`chokidar`,
+        // which are devDependencies: a consumer installing `flet-box` from npm
+        // has neither, so loading them at module scope would break every CLI
+        // command for them. Import them when a server is actually started.
+        await (await import("./commands/runServer.js")).runDevServer({
           spaMode: false,
           hotReload: flags.hot,
           port: flags.port,
@@ -336,16 +410,8 @@ async function main() {
       case "runBundle":
       case "preview": {
         ensureProject();
-        // Accept an explicit target directory as the second argument, but reject
-        // anything that looks like a flag (starts with "-") to avoid misparses.
-        const targetDir =
-          args[1] &&
-          /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/.test(args[1]) &&
-          !args[1].startsWith("-")
-            ? args[1]
-            : "www";
-        await runBundle({
-          target: targetDir,
+        await (await import("./commands/runBundle.js")).runBundle({
+          target: bundleTarget(),
           port: flags.port,
           askPort: !flags.portExplicit,
           logRequests: flags.logRequests,
@@ -357,7 +423,7 @@ async function main() {
       case "runSpa":
       case "spa":
         ensureProject();
-        await runDevServer({
+        await (await import("./commands/runServer.js")).runDevServer({
           spaMode: true,
           hotReload: true,
           port: flags.port,
@@ -371,7 +437,8 @@ async function main() {
       case "demo":
       case "tunnel":
         ensureProject();
-        await runCloudflareDemo({
+        await (await import("./commands/runCloudflare.js")).runCloudflareDemo({
+          target: bundleTarget(),
           port: flags.port,
           logRequests: flags.logRequests,
         });