tutuca 0.9.30 → 0.9.31

package/README.md

@@ -95,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`.
 
@@ -138,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);
   }
 }
@@ -7719,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);
@@ -7835,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
@@ -8040,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.
 
@@ -8122,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:
@@ -8163,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}
 `);
@@ -8187,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();
@@ -8218,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 = {};
@@ -8619,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(`
@@ -8631,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
@@ -8652,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.
@@ -8688,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];
@@ -8706,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];

package/dist/tutuca-dev.js

@@ -1005,7 +1005,20 @@ class ANode extends BaseNode {
     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)
@@ -1025,10 +1038,8 @@ class ANode extends BaseNode {
       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":
@@ -1320,7 +1331,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) {
@@ -1597,7 +1608,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
+        });
       }
     }
   }
@@ -1779,7 +1793,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);
   }
 }
@@ -2117,7 +2131,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);
@@ -8068,7 +8086,7 @@ class ClassBuilder {
     return field;
   }
 }
-var fieldsByClass = new Map;
+var FIELD_CLASS = Symbol.for("tutuca.fieldClass");
 var fieldsByTypeName = {
   text: FieldString,
   int: FieldInt,
@@ -8105,7 +8123,7 @@ function classFromData(name, { fields = {}, methods, statics }) {
     else if (Map2.isMap(value) || value?.constructor === Object)
       b.addField(field, Map2(value), FieldMap);
     else {
-      const Field2 = fieldsByClass.get(value?.constructor) ?? FieldAny;
+      const Field2 = value?.[FIELD_CLASS] ?? FieldAny;
       b.addField(field, value, Field2);
     }
   }
@@ -8126,7 +8144,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);
@@ -8245,7 +8263,7 @@ var imKeyedIter = (seq, visit) => {
     visit(k, v, "sk");
 };
 var unkIter = () => {};
-var seqInfoByClass = new Map;
+var SEQ_INFO = Symbol.for("tutuca.seqInfo");
 
 // extra/klist.js
 class KList {
@@ -8337,11 +8355,11 @@ class FieldKList extends Field {
     };
   }
 }
-fieldsByClass.set(KList, FieldKList);
-seqInfoByClass.set(KList, (seq, visit) => {
+KList.prototype[FIELD_CLASS] = FieldKList;
+KList.prototype[SEQ_INFO] = (seq, visit) => {
   for (const k of seq.order)
     visit(k, seq.items.get(k), "data-sk");
-});
+};
 // index.js
 var css = String.raw;
 var html = String.raw;
@@ -8627,7 +8645,6 @@ export {
   tutuca,
   setIn$1 as setIn,
   set,
-  seqInfoByClass,
   removeIn,
   remove,
   mergeWith$1 as mergeWith,
@@ -8664,7 +8681,6 @@ export {
   getComponentsDocs,
   get,
   fromJS,
-  fieldsByClass,
   docComponents,
   css,
   component,
@@ -8680,6 +8696,7 @@ export {
   Stack2 as Stack,
   Set2 as Set,
   Seq,
+  SEQ_INFO,
   Repeat,
   Record,
   Range,
@@ -8703,6 +8720,7 @@ export {
   INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD,
   Map2 as IMap,
   FIELD_VAL_NOT_DEFINED,
+  FIELD_CLASS,
   DUPLICATE_ATTR_DEFINITION,
   Collection,
   COMPUTED_VAL_NOT_DEFINED,