tutuca 0.9.84 → 0.9.86

package/dist/tutuca-cli.js

@@ -15722,6 +15722,13 @@ function resolveTutucaBase(projectDir, self, forCdn) {
     return { base: DIST_PREFIX.replace(/\/$/, ""), serveDist: self.distRoot };
   return { base: `https://cdn.jsdelivr.net/npm/tutuca@${self.version}/dist`, serveDist: null };
 }
+function tutucaSource(base) {
+  if (base.startsWith("http"))
+    return "CDN";
+  if (base.startsWith("/node_modules"))
+    return "node_modules";
+  return "local dist";
+}
 function buildImports(base, { margaui }) {
   const dev = `${base}/tutuca-dev.js`;
   const imports = {
@@ -15809,6 +15816,40 @@ async function runDevTests(projectDir, devModuleUrls) {
   }
   return { totalTests, failedTests, withTests, failures, importErrors };
 }
+async function discoverModules(projectDir, devModuleUrls) {
+  await createNodeEnv();
+  const modules = [];
+  for (const url of devModuleUrls) {
+    const abs = resolve4(projectDir, url.slice(1));
+    try {
+      const mod = await import(abs);
+      const { normalized, present } = normalizeModule(mod, { path: abs });
+      modules.push({
+        url,
+        present: [...present],
+        components: normalized.components.map((c) => c.name),
+        sections: normalized.sections.map((s) => ({
+          title: s.title,
+          description: s.description,
+          items: s.items.map((it) => ({
+            title: it.title,
+            view: it.view,
+            componentName: it.componentName
+          }))
+        })),
+        macros: normalized.macros ? Object.keys(normalized.macros) : [],
+        requestHandlers: normalized.requestHandlers ? Object.keys(normalized.requestHandlers) : [],
+        error: null
+      });
+    } catch (e) {
+      modules.push({
+        url,
+        error: { code: e.code ?? null, message: e.message, where: e.where ?? null }
+      });
+    }
+  }
+  return modules;
+}
 function collectFailures(node, acc) {
   if (node.children) {
     for (const child of node.children)
@@ -15844,12 +15885,13 @@ async function run4(argv, opts = {}) {
       "no-margaui": { type: "boolean", default: false },
       "no-check": { type: "boolean", default: false },
       "no-tests": { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false }
     },
     allowPositionals: true
   });
   if (parsed.values.help) {
-    process.stdout.write(`tutuca storybook [dir] [--port <n>] [--out <dir>]
+    process.stdout.write(`tutuca storybook [dir] [--port <n>] [--out <dir>] [--dry-run]
                  [--no-margaui] [--no-check] [--no-tests]
 
   Auto-discovers co-located *.dev.js modules (recursively, skipping
@@ -15860,6 +15902,9 @@ async function run4(argv, opts = {}) {
   --port <n>     preferred port (default 4321; falls back to a free port)
   --out <dir>    write a static index.html + bootstrap (CDN import map)
                  instead of serving; host it from the project root
+  --dry-run      do all the prep (discover, import and normalize modules,
+                 resolve the runtime, run tests) and print what would be
+                 shown instead of serving; pass --json for structured output
   --no-margaui   skip margaui styling (renders functional but unstyled)
   --no-check     skip the in-browser check(app) dev validation
   --no-tests     skip running the modules' getTests() before serving
@@ -15899,6 +15944,63 @@ async function run4(argv, opts = {}) {
 `);
     return;
   }
+  if (parsed.values["dry-run"]) {
+    const { base: base2 } = resolveTutucaBase(projectDir, self, false);
+    const imports2 = buildImports(base2, { margaui });
+    const modules = await discoverModules(projectDir, devModuleUrls);
+    const tests = parsed.values["no-tests"] ? null : await runDevTests(projectDir, devModuleUrls);
+    const source = tutucaSource(base2);
+    const result = {
+      projectDir,
+      tutuca: { source, base: base2, version: self.version },
+      options: { margaui, check, runTests: !parsed.values["no-tests"] },
+      imports: imports2,
+      modules,
+      tests
+    };
+    if (opts.format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(`tutuca storybook dry run (no server started)
+  project: ${projectDir}
+  tutuca runtime: ${source} (${base2}, version ${self.version})
+  margaui: ${margaui ? "on" : "off"}, in-browser check: ${check ? "on" : "off"}
+  ${modules.length} dev module(s):
+`);
+    for (const m of modules) {
+      if (m.error) {
+        process.stdout.write(`    error ${m.url} — ${m.error.message}
+`);
+        continue;
+      }
+      const sectionItems = m.sections.reduce((n, s) => n + s.items.length, 0);
+      process.stdout.write(`    ok ${m.url} — ${m.components.length} component(s), ${m.sections.length} section(s), ${sectionItems} example(s)
+`);
+    }
+    if (tests) {
+      for (const ie of tests.importErrors) {
+        process.stdout.write(`  ! skipped tests for ${ie.url}: ${ie.message}
+`);
+      }
+      if (tests.withTests === 0) {
+        process.stdout.write(`  tests: no getTests() in any dev module
+`);
+      } else {
+        process.stdout.write(`  tests: ${tests.totalTests - tests.failedTests}/${tests.totalTests} passed across ${tests.withTests} module(s)
+`);
+        for (const f of tests.failures) {
+          process.stdout.write(`    failed ${f.fullPath}: ${f.error?.message ?? "failed"}
+`);
+        }
+      }
+    } else {
+      process.stdout.write(`  tests: skipped (--no-tests)
+`);
+    }
+    return;
+  }
   if (!parsed.values["no-tests"]) {
     const r = await runDevTests(projectDir, devModuleUrls);
     for (const ie of r.importErrors) {
@@ -15949,7 +16051,7 @@ async function run4(argv, opts = {}) {
   });
   server.on("listening", () => {
     const actual = server.address().port;
-    const where = base.startsWith("http") ? "CDN" : base.startsWith("/node_modules") ? "node_modules" : "local dist";
+    const where = tutucaSource(base);
     process.stdout.write(`tutuca storybook: http://localhost:${actual}/  (${devModuleUrls.length} dev modules, tutuca from ${where})
 `);
   });
@@ -15994,7 +16096,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 var describe = "Print a machine-readable schema (commands, flags, exit codes) as JSON.";
-var SCHEMA_VERSION = 2;
+var SCHEMA_VERSION = 3;
 var GLOBAL_FLAGS = [
   {
     name: "json",
@@ -16126,6 +16228,50 @@ var NO_MODULE_COMMANDS_META = {
     ],
     positionals: []
   },
+  storybook: {
+    describe: "Serve a live storybook for the project, auto-discovering co-located *.dev.js modules.",
+    needsModule: false,
+    flags: [
+      {
+        name: "port",
+        type: "string",
+        description: "Preferred port (default 4321; falls back to a free port)."
+      },
+      {
+        name: "out",
+        type: "string",
+        description: "Write a static index.html + bootstrap (CDN import map) instead of serving."
+      },
+      {
+        name: "no-margaui",
+        type: "boolean",
+        description: "Render unstyled (skip margaui)."
+      },
+      {
+        name: "no-check",
+        type: "boolean",
+        description: "Skip the in-browser check(app)."
+      },
+      {
+        name: "no-tests",
+        type: "boolean",
+        description: "Skip running the modules' getTests() before serving."
+      },
+      {
+        name: "dry-run",
+        type: "boolean",
+        description: "Do all prep (discover + import + normalize modules, resolve runtime, run tests) and print what would be shown instead of serving. Pass --json for structured output."
+      },
+      { name: "help", short: "h", type: "boolean" }
+    ],
+    positionals: [
+      {
+        name: "dir",
+        required: false,
+        description: "Project root to scan and serve (default: cwd)."
+      }
+    ]
+  },
   "agent-context": {
     describe: "Print this schema as JSON.",
     needsModule: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.84",
+  "version": "0.9.86",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -22,15 +22,16 @@
     "tutuca": "./dist/tutuca-cli.js"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rm -rf dist skill",
     "dist": "bun scripts/dist.js",
     "dist-ext": "bun scripts/dist-ext.js",
     "dist-immutable": "bun scripts/dist-immutable.js",
     "dist-all": "bun run dist-immutable && bun run dist && bun run dist-ext && bun run smoke",
     "smoke": "node scripts/smoke.js",
-    "release": "bun run dist-all && bun run build-skill && npm publish --access public",
-    "release-dry": "bun run dist-all && bun run build-skill && npm publish --dry-run",
+    "release": "bun run dist-all && bun run build-skill && (npm publish --access public; bun run clean-skill)",
+    "release-dry": "bun run dist-all && bun run build-skill && (npm publish --dry-run; bun run clean-skill)",
     "build-skill": "bun scripts/build-skill.js",
+    "clean-skill": "rm -rf skill",
     "test": "bun test test/*.test.js",
     "test-watch": "bun test --watch test/*.test.js",
     "format": "bunx @biomejs/biome format --write",

package/skill/tutuca/cli.md

@@ -40,6 +40,7 @@ Use `--module=<path>` if the path conflicts with positional parsing.
 | `lint <module> [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
 | `render <module> [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
 | `test <module> [name]`   | Run tests defined by `getTests({ describe, test, expect })`. Filter by component name, `--grep <pattern>`, or `--bail`. Exits **4** on any failure |
+| `storybook [dir]`        | Serve a live storybook for the project, auto-discovering co-located `*.dev.js` modules. Flags: `--port`, `--out`, `--dry-run` (prep + print, don't serve), `--no-margaui`, `--no-check`, `--no-tests`. No module path needed |
 | `help [cmd]`             | Show usage. No module path needed                                                                                      |
 | `feedback [message]`     | Append a feedback note (positional or stdin) to `~/.tutuca/feedback.jsonl`. No module path needed                      |
 | `install-skill [name]`   | Copy a bundled skill (`tutuca`, `margaui`, `immutable-js`, or `--all`) into `.claude/skills/`. No module path needed   |
@@ -187,6 +188,63 @@ export function getTests({ describe, test, expect }) {
 `tutuca test <module> Counter` picks it up. Untagged `test(...)` at the
 top of a tagged `describe` inherits the tag.
 
+## storybook — live component catalog
+
+`tutuca storybook [dir]` serves a browser storybook for a project with no
+setup. It recursively discovers co-located `*.dev.js` modules (see the
+`.dev.js` convention below), mounts them via the shipped `tutuca/storybook`
+library, and serves an ephemeral page — no config, no HTML to write.
+
+```sh
+tutuca storybook                 # scan + serve the current directory
+tutuca storybook ./packages/ui   # scan + serve another directory
+tutuca storybook --port 4321     # preferred port (falls back to a free one if taken)
+tutuca storybook --out ./_site   # write a static index.html + bootstrap instead of serving
+tutuca storybook --dry-run       # do all the prep + print what would be shown, don't serve (smoke test)
+tutuca storybook --dry-run --json # same, machine-readable for agents
+tutuca storybook --no-tests      # skip the pre-serve getTests() run
+tutuca storybook --no-margaui    # render unstyled (skip margaui)
+tutuca storybook --no-check      # skip the in-browser check(app)
+```
+
+It is **batteries-included by default**: before serving it runs each module's
+`getTests()` in the terminal, the page wires margaui styling, and the browser
+runs `check(app)`. Each is individually disablable with the `--no-*` flags.
+
+How tutuca itself is resolved (convention over configuration): a local
+`node_modules/tutuca` install if present, else the CLI's own `dist`, else the
+version-pinned CDN. All tutuca specifiers resolve to a single runtime, which
+component scope/identity requires. `--out` always pins the CDN so the static
+artifact is portable (host it from the project root so `/*.dev.js` paths resolve).
+
+### The `.dev.js` convention
+
+A `*.dev.js` file is a **dev-only module**: it holds stories
+(`getComponents()` + `getExamples()`), tests (`getTests()`), and any other
+development-time helpers for nearby components, and is **never shipped to
+production or the UI**. The `.dev.js` suffix is the contract — your app imports
+its real components directly and never a `.dev.js`, and a production build glob
+can exclude `**/*.dev.js`. Because they follow the full module convention, the
+same files are valid targets for `tutuca test`/`lint`/`render` too.
+
+```js
+// counter.dev.js — lives next to counter.js
+import { component, html } from "tutuca";
+import { Counter } from "./counter.js";
+
+export function getComponents() {
+  return [Counter];
+}
+export function getExamples() {
+  return { title: "Counter", items: [{ title: "Basic", value: Counter.make({}) }] };
+}
+export function getTests({ describe, test, expect }) {
+  describe(Counter, () => {
+    test("starts at zero", () => expect(Counter.make({}).count).toBe(0));
+  });
+}
+```
+
 ## Install skill assets
 
 `tutuca install-skill` copies bundled Claude Code skill files into

package/skill/tutuca/core.md

@@ -69,6 +69,23 @@ edit done:
    emitted HTML to verify structure (attributes, nesting, text); omit it
    when you only care that the render didn't crash.
 
+4. **Smoke-test the whole project** — when you've touched several
+   `*.dev.js` modules, or are about to launch the storybook, do a
+   project-wide dry run instead of opening a browser:
+
+        tutuca storybook --dry-run
+        tutuca storybook --dry-run --json    # machine-readable for agents
+
+   It does everything the server would do up front — discovers every
+   co-located `*.dev.js`, imports and normalizes each (catching a missing
+   `getComponents()` or a malformed `getExamples()` shape), runs their
+   `getTests()`, and resolves the runtime import map — then prints what
+   it *would* show instead of serving. A broken module is reported in
+   place (an `error` line, or `modules[].error` in `--json`) while the
+   others still report, so one bad module never hides the rest. This is
+   the fast "is the whole catalog wired up correctly?" check; steps 1–3
+   stay the per-module loop.
+
 Full reference: [cli.md](./cli.md).
 
 The Tutuca CLI only catches Tutuca-specific issues. For generic JS
@@ -988,6 +1005,12 @@ export, alias it instead of teaching tools a new name:
 export { allMyComponents as getComponents } from "./app.js";
 ```
 
+Put these exports in a co-located **`*.dev.js`** file (a dev-only module
+holding stories + tests, never shipped) and `tutuca storybook` auto-discovers
+and renders them with no setup — see [cli.md](./cli.md). The same shape is
+consumed by the shipped `tutuca/storybook` library (`mountStorybook`,
+`buildStorybook`) if you want to embed a storybook in your own page.
+
 ## See also
 
 - [component-design.md](./component-design.md) — design judgment for shaping a