Micro app factory

micro-app-factory

Turn rough ideas into portable static micro-apps with a gated workflow, deterministic QA, and a shareable build receipt.

Core Contract

• Build static HTML/CSS/JS by default. Do not require React, Vite, Vercel, Sites, Cloudflare, databases, payments, auth, or API keys for the first version unless the user explicitly asks.
• Support these app types: utility, quiz, calculator, content-tool, game, and landing.
• Wait for explicit user approval with the phrase Build it or an unambiguous equivalent before writing app files.
• Produce a real app package, not a plan-only answer: index.html, assets/css/styles.css, assets/js/app.js, README.md, and BUILD_RECEIPT.md.
• Run QA before handoff. At minimum, use the bundled QA script; add browser screenshots or Playwright checks when available and useful.
• Never claim deployment happened unless a deployment tool actually ran and returned a URL.

Workflow

1. Intake

   • If the user has an idea, restate it as a compact app brief.
   • If the user wants ideas from scratch, propose three small app directions with type, user value, and why it is buildable as a static app.
   • Ask the user to choose one direction if no direction is selected yet.

2. Build Spec

   • Present a short spec with: name, app type, audience, core interaction, data/content needed, style constraints, and done-when checks.
   • Keep the spec bounded enough to finish as a micro-app in one pass.
   • End by asking for Build it approval.

3. Generate

   • Convert the accepted spec into an idea JSON file.
   • Run python scripts/generate_static_app.py --idea <idea.json> --out <output-dir>.
   • Prefer a clean output directory named with a slug of the app name.

4. QA

   • Run python scripts/qa_static_app.py <app-dir> --format markdown --out <app-dir>/QA_REPORT.md.
   • Fix failures, rerun QA, and do not hand off until the report passes or a blocker is clearly documented.
   • When Node is available, the QA script checks JavaScript syntax with node --check.

5. Receipt

   • Run python scripts/build_receipt.py <app-dir> --qa <app-dir>/QA_REPORT.md.
   • Summarize the files, checks, usage instructions, and suggested next polish.

6. Handoff

   • Link the generated app folder and mention the QA status.
   • Include exact commands used when useful.
   • If deployment is requested, treat it as a separate explicit step and follow the relevant deployment tool or plugin.

Script Inputs

The generator accepts JSON shaped like:

{
  "name": "Writer Habit Tracker",
  "app_type": "utility",
  "description": "Track daily writing streaks without sign-in.",
  "audience": "writers who want a tiny local tracker",
  "features": ["daily check-in", "streak counter", "reset button"],
  "style": "calm, focused, high contrast"
}

Use only plain JSON values. If a field is missing, choose a conservative default and record it in the receipt.

Quality Bar

• The first screen must be the usable app experience, not a marketing page.
• Include labels, keyboard-friendly controls, visible focus states, and responsive layout.
• Store temporary state in localStorage only when it helps the micro-app work without a backend.
• Keep generated code readable and dependency-free.
• The QA report and receipt are part of the deliverable.