tutuca 0.9.29 → 0.9.31

package/README.md

@@ -11,6 +11,9 @@ Zero-dependency batteries included SPA framework.
 
 ## Quick Start
 
+For an interactive walk-through with editable examples, see the
+[tutorial](https://marianoguerra.github.io/tutuca/tutorial.html).
+
 ### CDN (no install)
 
 ```html
@@ -92,6 +95,7 @@ tutuca help [command]
 | `lint [name]` | Run lint checks — all, or one by name (exit 2 on errors) |
 | `render [name] [--title t] [--view v]` | Render examples to HTML |
 | `doctor` | Lint + render smoke test over the whole module |
+| `install-skill [--user] [--force]` | Install the tutuca Claude Code skill (no module path needed) |
 
 Global flags: `-f, --format <cli\|md\|json\|html>`, `-o, --output <file>`, `--pretty`, `-h, --help`.
 
@@ -135,6 +139,27 @@ The invocation stays short even without wrapping, but common patterns:
 - **`justfile` / `Makefile`** — one recipe per subcommand, passing through positionals
 - **Programmatic** — `import "tutuca/cli"` (the bundled entry) for custom build integration
 
+## Use with Claude Code
+
+Tutuca ships an LLM-facing reference (`SKILL.md` + `core.md` / `cli.md` /
+`advanced.md`) packaged as a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills).
+Once installed, Claude auto-loads it whenever a session touches tutuca
+components, views, macros, or the CLI.
+
+```sh
+# project-scoped: writes ./.claude/skills/tutuca/ (commit it for the team)
+npx tutuca install-skill
+
+# or user-scoped: writes ~/.claude/skills/tutuca/
+npx tutuca install-skill --user
+
+# overwrite an existing install
+npx tutuca install-skill --force
+```
+
+The skill content is generated from `docs/llm/`, so the same reference
+runs locally (`tutuca <module> doctor`) and inside Claude.
+
 ## License
 
 MIT

package/dist/tutuca-cli.js

@@ -1394,7 +1394,7 @@ class ParseContext {
   parseHTML(html) {
     const t = this.document.createElement("template");
     t.innerHTML = html;
-    return Array.from(t.content.childNodes);
+    return t.content.childNodes;
   }
   addNodeIf(Class, val, extra) {
     if (val !== null) {
@@ -1614,7 +1614,20 @@ var init_anode = __esm(() => {
       return this.val.toPathItem();
     }
     static parse(html, px) {
-      return ANode.fromDOM(px.parseHTML(html)[0] ?? new px.Text(""), px);
+      const nodes = px.parseHTML(html);
+      if (nodes.length === 0)
+        return new TextNode("");
+      if (nodes.length === 1)
+        return ANode.fromDOM(nodes[0], px);
+      const childs = new Array(nodes.length);
+      for (let i = 0;i < nodes.length; i++)
+        childs[i] = ANode.fromDOM(nodes[i], px);
+      const trimmed = condenseChildsWhites(childs);
+      if (trimmed.length === 0)
+        return new TextNode("");
+      if (trimmed.length === 1)
+        return trimmed[0];
+      return new FragmentNode(trimmed);
     }
     static fromDOM(node, px) {
       if (node instanceof px.Text)
@@ -1634,10 +1647,8 @@ var init_anode = __esm(() => {
         switch (name) {
           case "slot":
             return new SlotNode(null, vp.const(value), maybeFragment(childs));
-          case "text": {
-            const v = vp.parseText(value, px);
-            return v !== null ? new RenderTextNode(null, v) : null;
-          }
+          case "text":
+            return px.addNodeIf(RenderTextNode, vp.parseText(value, px));
           case "render":
             return px.addNodeIf(RenderNode, vp.parseRender(value, px), as);
           case "render-it":
@@ -2025,7 +2036,11 @@ class ComponentStack {
     }
   }
   registerMacros(macros) {
-    Object.assign(this.macros, macros);
+    for (const key in macros) {
+      const lower = key.toLowerCase();
+      console.assert(this.macros[lower] === undefined, "macro key collision", lower);
+      this.macros[lower] = macros[key];
+    }
   }
   getCompFor(v) {
     return this.comps.getCompFor(v);
@@ -2083,7 +2098,10 @@ function checkMacroCallArgs(lx, view, Comp) {
     const { defaults } = macro;
     for (const argName in macroNode.attrs) {
       if (!(argName in defaults)) {
-        lx.error(UNKNOWN_MACRO_ARG, { name: argName, macroName: macroNode.name });
+        lx.error(UNKNOWN_MACRO_ARG, {
+          name: argName,
+          macroName: macroNode.name
+        });
       }
     }
   }
@@ -2244,7 +2262,7 @@ function checkConsistentAttrVal(lx, val, fields, proto, computed, scope, alter,
     if (alter[val.name] === undefined) {
       lx.error(ALT_HANDLER_NOT_DEFINED, { name: val.name });
     }
-  } else if (valName !== "ConstVal" && valName !== "BindVal") {
+  } else if (valName !== "ConstVal" && valName !== "BindVal" && valName !== "DynVal") {
     console.log(val);
   }
 }
@@ -2258,8 +2276,21 @@ function checkConsistentAttrs(lx, Comp, referencedAlters, referencedComputed) {
       for (const attr of view.ctx.attrs) {
         const { attrs, wrapperAttrs, textChild, isMacroCall } = attr;
         if (attrs?.constructor.name === "DynAttrs") {
+          const seenNames = new Set;
           for (const attr2 of attrs.items) {
-            if (attr2?.constructor.name === "Attr") {
+            const name = attr2?.name;
+            if (name !== undefined && name !== "data-eid") {
+              if (seenNames.has(name)) {
+                lx.error(DUPLICATE_ATTR_DEFINITION, { name });
+              } else {
+                seenNames.add(name);
+              }
+            }
+            if (attr2?.constructor.name === "IfAttr") {
+              for (const subVal of [attr2.condVal, attr2.thenVal, attr2.elseVal]) {
+                checkConsistentAttrVal(lx, subVal, fields, proto, computed, scope, alter, referencedAlters, referencedComputed, isMacroCall);
+              }
+            } else if (attr2?.val !== undefined) {
               checkConsistentAttrVal(lx, attr2.val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed, isMacroCall);
             }
           }
@@ -2346,7 +2377,7 @@ class LintContext {
     this.reports.push({ id, info, level, context: { ...this.frame } });
   }
 }
-var ALT_HANDLER_NOT_DEFINED = "ALT_HANDLER_NOT_DEFINED", ALT_HANDLER_NOT_REFERENCED = "ALT_HANDLER_NOT_REFERENCED", RENDER_IT_OUTSIDE_OF_LOOP = "RENDER_IT_OUTSIDE_OF_LOOP", UNKNOWN_EVENT_MODIFIER = "UNKNOWN_EVENT_MODIFIER", UNKNOWN_HANDLER_ARG_NAME = "UNKNOWN_HANDLER_ARG_NAME", INPUT_HANDLER_NOT_IMPLEMENTED = "INPUT_HANDLER_NOT_IMPLEMENTED", INPUT_HANDLER_NOT_REFERENCED = "INPUT_HANDLER_NOT_REFERENCED", INPUT_HANDLER_METHOD_NOT_IMPLEMENTED = "INPUT_HANDLER_METHOD_NOT_IMPLEMENTED", INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD = "INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD", INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER = "INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER", FIELD_VAL_NOT_DEFINED = "FIELD_VAL_NOT_DEFINED", COMPUTED_VAL_NOT_DEFINED = "COMPUTED_VAL_NOT_DEFINED", COMPUTED_NOT_REFERENCED = "COMPUTED_NOT_REFERENCED", UNKNOWN_REQUEST_NAME = "UNKNOWN_REQUEST_NAME", UNKNOWN_COMPONENT_NAME = "UNKNOWN_COMPONENT_NAME", UNKNOWN_MACRO_ARG = "UNKNOWN_MACRO_ARG", LEVEL_WARN = "warn", LEVEL_ERROR = "error", LEVEL_HINT = "hint", NO_WRAPPERS, KNOWN_HANDLER_NAMES, LintParseContext;
+var ALT_HANDLER_NOT_DEFINED = "ALT_HANDLER_NOT_DEFINED", ALT_HANDLER_NOT_REFERENCED = "ALT_HANDLER_NOT_REFERENCED", RENDER_IT_OUTSIDE_OF_LOOP = "RENDER_IT_OUTSIDE_OF_LOOP", UNKNOWN_EVENT_MODIFIER = "UNKNOWN_EVENT_MODIFIER", UNKNOWN_HANDLER_ARG_NAME = "UNKNOWN_HANDLER_ARG_NAME", INPUT_HANDLER_NOT_IMPLEMENTED = "INPUT_HANDLER_NOT_IMPLEMENTED", INPUT_HANDLER_NOT_REFERENCED = "INPUT_HANDLER_NOT_REFERENCED", INPUT_HANDLER_METHOD_NOT_IMPLEMENTED = "INPUT_HANDLER_METHOD_NOT_IMPLEMENTED", INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD = "INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD", INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER = "INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER", FIELD_VAL_NOT_DEFINED = "FIELD_VAL_NOT_DEFINED", COMPUTED_VAL_NOT_DEFINED = "COMPUTED_VAL_NOT_DEFINED", COMPUTED_NOT_REFERENCED = "COMPUTED_NOT_REFERENCED", DUPLICATE_ATTR_DEFINITION = "DUPLICATE_ATTR_DEFINITION", UNKNOWN_REQUEST_NAME = "UNKNOWN_REQUEST_NAME", UNKNOWN_COMPONENT_NAME = "UNKNOWN_COMPONENT_NAME", UNKNOWN_MACRO_ARG = "UNKNOWN_MACRO_ARG", LEVEL_WARN = "warn", LEVEL_ERROR = "error", LEVEL_HINT = "hint", NO_WRAPPERS, KNOWN_HANDLER_NAMES, LintParseContext;
 var init_lint_check = __esm(() => {
   init_anode();
   NO_WRAPPERS = {};
@@ -7706,7 +7737,7 @@ class Renderer {
     this.cache = new WeakMapDomCache;
   }
   getSeqInfo(seq) {
-    return isIndexed(seq) ? imIndexedIter : isKeyed(seq) ? imKeyedIter : seqInfoByClass.get(seq?.constructor) ?? unkIter;
+    return isIndexed(seq) ? imIndexedIter : isKeyed(seq) ? imKeyedIter : seq?.[SEQ_INFO] ?? unkIter;
   }
   renderTag(tag, attrs, childs) {
     return h(tag, attrs, childs);
@@ -7822,12 +7853,12 @@ var DATASET_ATTRS, imIndexedIter = (seq, visit) => {
 }, imKeyedIter = (seq, visit) => {
   for (const [k, v] of seq.toSeq().entries())
     visit(k, v, "sk");
-}, unkIter = () => {}, seqInfoByClass;
+}, unkIter = () => {}, SEQ_INFO;
 var init_renderer = __esm(() => {
   init_immutable();
   init_vdom();
   DATASET_ATTRS = ["nid", "cid", "eid", "vid", "si", "sk"];
-  seqInfoByClass = new Map;
+  SEQ_INFO = Symbol.for("tutuca.seqInfo");
 });
 
 // src/util/render.js
@@ -8027,11 +8058,105 @@ var init__registry = __esm(() => {
   };
 });
 
+// tools/cli/commands/install-skill.js
+var exports_install_skill = {};
+__export(exports_install_skill, {
+  run: () => run,
+  describe: () => describe
+});
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+function findSkillDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [resolve(here, "..", "..", "..", "skill"), resolve(here, "..", "skill")];
+  for (const c of candidates) {
+    if (existsSync(resolve(c, "SKILL.md")))
+      return c;
+  }
+  return null;
+}
+function targetDir(scope) {
+  if (scope === "user")
+    return resolve(homedir(), ".claude/skills/tutuca");
+  return resolve(process.cwd(), ".claude/skills/tutuca");
+}
+async function run(argv) {
+  const parsed = parseArgs({
+    args: argv,
+    options: {
+      user: { type: "boolean", default: false },
+      project: { type: "boolean", default: false },
+      force: { type: "boolean", short: "f", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    allowPositionals: false
+  });
+  if (parsed.values.help) {
+    process.stdout.write(`tutuca install-skill [--user | --project] [--force]
+` + `
+` + `  Copies SKILL.md + core.md + cli.md + advanced.md into
+` + `  .claude/skills/tutuca/. Defaults to --project (cwd).
+` + `  --user installs at ~/.claude/skills/tutuca/.
+` + `  --force overwrites existing files.
+`);
+    return;
+  }
+  if (parsed.values.user && parsed.values.project) {
+    process.stderr.write(`tutuca: --user and --project are mutually exclusive
+`);
+    process.exit(1);
+  }
+  const scope = parsed.values.user ? "user" : "project";
+  const target = targetDir(scope);
+  const src = findSkillDir();
+  if (!src) {
+    process.stderr.write(`tutuca: skill assets not found alongside this CLI.
+` + "If you're running from a checkout, run `bun scripts/build-skill.js` first.\n");
+    process.exit(1);
+  }
+  if (existsSync(target) && !parsed.values.force) {
+    const existing = readdirSync(target).filter((n) => SKILL_FILES.includes(n));
+    if (existing.length > 0) {
+      process.stderr.write(`tutuca: ${target} already contains skill files. Re-run with --force to overwrite.
+`);
+      process.exit(1);
+    }
+  }
+  mkdirSync(target, { recursive: true });
+  for (const name of SKILL_FILES) {
+    const from = resolve(src, name);
+    if (!existsSync(from)) {
+      process.stderr.write(`tutuca: missing skill asset: ${from}
+`);
+      process.exit(1);
+    }
+    const buf = readFileSync(from);
+    writeFileSync(resolve(target, name), buf);
+  }
+  const rel = scope === "project" ? ".claude/skills/tutuca" : target;
+  process.stdout.write(`installed tutuca skill → ${rel}
+`);
+  process.stdout.write(`Open a Claude Code session in this directory to use it.
+`);
+}
+var describe = "Install the tutuca Claude Code skill into .claude/skills/tutuca/.", SKILL_FILES;
+var init_install_skill = __esm(() => {
+  SKILL_FILES = ["SKILL.md", "core.md", "cli.md", "advanced.md"];
+});
+
 // tools/tutuca.js
 init__registry();
 
 // tools/cli/commands/help.js
-var describe = "Show usage. `help <command>` for per-command detail.";
+var exports_help = {};
+__export(exports_help, {
+  run: () => run2,
+  describe: () => describe2
+});
+var describe2 = "Show usage. `help <command>` for per-command detail.";
 var OVERVIEW = `tutuca — CLI for inspecting, documenting, linting and rendering tutuca
 components defined in an ES module.
 
@@ -8109,6 +8234,11 @@ COMMANDS (no module required)
       Without [command]: prints this full reference.
       With [command]: prints that command's one-line description.
 
+  install-skill [--user | --project] [--force]
+      Copy the bundled Claude Code skill (SKILL.md + core/cli/advanced.md)
+      into .claude/skills/tutuca/. Default scope is --project (cwd);
+      --user installs at ~/.claude/skills/tutuca/. --force overwrites.
+
 GLOBAL FLAGS
   -f, --format <cli|md|json|html>
       Output format. Defaults per command:
@@ -8150,19 +8280,22 @@ EXAMPLES
   # CI smoke test
   tutuca ./src/components.js doctor
 `;
-async function run(argv) {
+async function run2(argv) {
   const target = argv?.[0];
   if (!target) {
     process.stdout.write(OVERVIEW);
     return;
   }
   if (target === "help") {
-    process.stdout.write(`help: ${describe}
+    process.stdout.write(`help: ${describe2}
 `);
     return;
   }
   const { COMMANDS: COMMANDS2 } = await Promise.resolve().then(() => (init__registry(), exports__registry));
-  const cmd = COMMANDS2[target];
+  const noModule = {
+    "install-skill": await Promise.resolve().then(() => (init_install_skill(), exports_install_skill))
+  };
+  const cmd = COMMANDS2[target] ?? noModule[target];
   if (!cmd) {
     process.stderr.write(`tutuca: unknown command: ${target}
 `);
@@ -8174,8 +8307,11 @@ async function run(argv) {
   process.stdout.write("Run `tutuca help` for the full reference including signatures and flags.\n");
 }
 
+// tools/tutuca.js
+init_install_skill();
+
 // tools/cli/with-module.js
-import { parseArgs } from "node:util";
+import { parseArgs as parseArgs2 } from "node:util";
 
 // tools/cli/env.js
 init_anode();
@@ -8205,16 +8341,16 @@ async function createNodeEnv() {
 }
 
 // tools/cli/load.js
-import { resolve } from "node:path";
+import { resolve as resolve2 } from "node:path";
 async function loadAndNormalize(modulePath) {
-  const abs = resolve(modulePath);
+  const abs = resolve2(modulePath);
   const mod = await import(abs);
   const { normalized } = normalizeModule(mod, { path: abs });
   return normalized;
 }
 
 // tools/cli/output.js
-import { writeFileSync } from "node:fs";
+import { writeFileSync as writeFileSync2 } from "node:fs";
 
 // tools/format/cli.js
 var exports_cli = {};
@@ -8606,7 +8742,7 @@ async function formatResult(formatName, result, options = {}) {
 async function emit(result, { format: format5, pretty, output }) {
   const text = await formatResult(format5, result, { pretty });
   if (output) {
-    writeFileSync(output, text);
+    writeFileSync2(output, text);
   } else {
     process.stdout.write(text);
     if (!text.endsWith(`
@@ -8618,7 +8754,7 @@ async function emit(result, { format: format5, pretty, output }) {
 
 // tools/cli/with-module.js
 async function runCommand(cmd, argv, globalOpts) {
-  const parsed = parseArgs({
+  const parsed = parseArgs2({
     args: argv,
     options: cmd.parseOptions ?? {},
     allowPositionals: true
@@ -8639,6 +8775,10 @@ async function runCommand(cmd, argv, globalOpts) {
 }
 
 // tools/tutuca.js
+var NO_MODULE_COMMANDS = {
+  help: exports_help,
+  "install-skill": exports_install_skill
+};
 function usageError(msg) {
   process.stderr.write(`tutuca: ${msg}
 Run \`tutuca help\` for usage.
@@ -8675,13 +8815,13 @@ function extractGlobals(argv) {
 async function main() {
   const { opts, rest } = extractGlobals(process.argv.slice(2));
   if (rest.length === 0 || opts.help && rest.length === 0) {
-    await run([], opts);
+    await run2([], opts);
     return;
   }
   let command;
   let commandArgs;
-  if (rest[0] === "help") {
-    command = "help";
+  if (NO_MODULE_COMMANDS[rest[0]]) {
+    command = rest[0];
     commandArgs = rest.slice(1);
   } else if (opts.module) {
     command = rest[0];
@@ -8693,12 +8833,13 @@ async function main() {
     command = rest[1];
     commandArgs = rest.slice(2);
   }
-  if (opts.help) {
-    await run([command], opts);
+  if (NO_MODULE_COMMANDS[command]) {
+    const args = opts.help ? [...commandArgs, "--help"] : commandArgs;
+    await NO_MODULE_COMMANDS[command].run(args, opts);
     return;
   }
-  if (command === "help") {
-    await run(commandArgs, opts);
+  if (opts.help) {
+    await run2([command], opts);
     return;
   }
   const cmd = COMMANDS[command];