tkeron 5.3.0 → 6.0.1

package/skills/tkeron-testing/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: tkeron-testing
+description: "Testing tkeron projects programmatically with getBuildResult() from the 'tkeron' package. Covers the full BuildResult API (dom, getContentAsString, type, size, fileHash), Bun test setup, recipes (assert components inlined, meta tags present, TS compiled), and the rules for fast, deterministic tests. Use this skill when writing or debugging tests for a tkeron project."
+---
+
+# Tkeron — Testing
+
+Tkeron exposes `getBuildResult()` for programmatic testing of the build output. It runs a real build into a temporary directory, returns a structured map of every output file, and cleans up afterwards.
+
+## Basic Setup (Bun test)
+
+```typescript
+import { describe, it, expect, beforeAll } from "bun:test";
+import { getBuildResult, type BuildResult } from "tkeron";
+import { join } from "path";
+
+describe("my project", () => {
+  const sourcePath = join(import.meta.dir, "websrc");
+  let result: BuildResult;
+
+  beforeAll(async () => {
+    result = await getBuildResult(sourcePath);
+  });
+
+  it("generates index.html", () => {
+    expect(result["index.html"]).toBeDefined();
+  });
+
+  it("has the correct title", () => {
+    const dom = result["index.html"]?.dom;
+    const title = dom?.querySelector("title");
+    expect(title).toBeDefined();
+    expect(title!.textContent).toBe("My Site");
+  });
+});
+```
+
+---
+
+## API
+
+### `getBuildResult(sourcePath, options?) => Promise<BuildResult>`
+
+| Param        | Type                  | Notes                                                      |
+| ------------ | --------------------- | ---------------------------------------------------------- |
+| `sourcePath` | `string`              | Absolute path to the `websrc/` directory.                  |
+| `options`    | `{ logger?: Logger }` | Optional. Pass a custom logger; omit for silent (default). |
+
+Returns a `BuildResult` — a record keyed by the relative output path (e.g. `"index.html"`, `"blog/post.html"`, `"styles/main.css"`).
+
+### `FileInfo` — value of each entry
+
+```typescript
+interface FileInfo {
+  fileName: string; // "index.html"
+  filePath: string; // "" for root, "blog" for blog/index.html
+  path: string; // "index.html" / "blog/post.html"
+  type: string; // MIME type (e.g. "text/html")
+  size: number; // bytes
+  fileHash: string; // sha256 of the output
+  getContentAsString?: () => string; // ONLY for text files
+  dom?: Document; // ONLY for .html (parsed by @tkeron/html-parser)
+}
+```
+
+Text files (`html`, `css`, `js`, `json`, `txt`, `svg`, `xml`, `ts`, `md`, etc.) get `getContentAsString`. Only `.html` files get `dom`.
+
+> **`dom` is from `@tkeron/html-parser`, not jsdom**. It supports `querySelector`, `querySelectorAll`, `textContent`, `getAttribute`, `innerHTML`, etc. Do NOT assume jsdom-only APIs (no `getComputedStyle`, no event dispatch, no `MutationObserver`).
+
+---
+
+## Rules
+
+1. **Build ONCE in `beforeAll()`**, NEVER inside each `it()` — a build can take seconds.
+2. **Check existence BEFORE properties**: `expect(el).toBeDefined()` → then `el!.textContent`.
+3. **Assert specific, bounded values**, not full output — whitespace/minification changes break brittle tests.
+4. **Use `dom` for HTML assertions**, `getContentAsString()` for CSS/JS string searches.
+5. **Use absolute paths** for `sourcePath` (`join(import.meta.dir, "websrc")`).
+6. **Tests do not need to clean up** — `getBuildResult` removes its temp directory automatically.
+
+---
+
+## Recipes
+
+### Assert a component was inlined
+
+```typescript
+it("inlines <site-header>", () => {
+  const html = result["index.html"]?.getContentAsString?.() ?? "";
+  expect(html).not.toContain("<site-header>");
+  expect(html).toContain('class="site-header"');
+});
+```
+
+### Assert meta tags from `.pre.ts`
+
+```typescript
+it("sets canonical from page-meta util", () => {
+  const dom = result["about.html"]?.dom;
+  const canonical = dom?.querySelector('link[rel="canonical"]');
+  expect(canonical?.getAttribute("href")).toBe("https://example.com/about");
+});
+```
+
+### Assert TS was compiled and reference rewritten
+
+```typescript
+it("rewrites .ts to .js in the page", () => {
+  const html = result["index.html"]?.getContentAsString?.() ?? "";
+  expect(html).toMatch(/src="\.\/index\.js"/);
+  expect(result["index.js"]).toBeDefined();
+});
+```
+
+### Assert `.post.ts` ran on external links
+
+```typescript
+it("post.ts adds rel/target to external links", () => {
+  const dom = result["index.html"]?.dom;
+  const link = dom?.querySelector('a[href^="http"]');
+  expect(link?.getAttribute("rel")).toBe("noopener noreferrer");
+  expect(link?.getAttribute("target")).toBe("_blank");
+});
+```
+
+### Assert a `.com.ts` rendered each instance with its attributes
+
+```typescript
+it("user-badge renders one card per instance", () => {
+  const dom = result["index.html"]?.dom;
+  const cards = dom?.querySelectorAll(".badge");
+  expect(cards?.length).toBe(3);
+  expect(cards?.[0].querySelector(".badge-name")?.textContent).toBe("Alice");
+});
+```
+
+### Assert intermediate files do NOT appear in output
+
+```typescript
+it("does not emit .com.* or .pre.ts files", () => {
+  const paths = Object.keys(result);
+  expect(paths.some((p) => p.endsWith(".com.html"))).toBe(false);
+  expect(paths.some((p) => p.endsWith(".com.ts"))).toBe(false);
+  expect(paths.some((p) => p.endsWith(".pre.ts"))).toBe(false);
+  expect(paths.some((p) => p.endsWith(".post.ts"))).toBe(false);
+});
+```
+
+### Assert sub-route page exists
+
+```typescript
+it("emits blog/index.html as the /blog/ route", () => {
+  expect(result["blog/index.html"]).toBeDefined();
+  expect(result["blog/index.html"]?.filePath).toBe("blog");
+});
+```
+
+### Assert hash/size constraints (output budget)
+
+```typescript
+it("CSS bundle stays under 50 KB", () => {
+  const css = result["styles/main.css"];
+  expect(css).toBeDefined();
+  expect(css!.size).toBeLessThan(50_000);
+});
+```
+
+---
+
+## Running Tests
+
+```bash
+bun test                          # all tests
+bun test src/foo.test.ts          # one file
+bun test --watch                  # watch mode
+NODE_ENV=production bun test      # if your build depends on env
+```
+
+`getBuildResult` honors the same `NODE_ENV` as a normal `tk build`, so you can test prod-only behavior (analytics scripts, dev banners) by setting it.
+
+---
+
+## Common Test Failures
+
+| Symptom                               | Likely cause                                                                 |
+| ------------------------------------- | ---------------------------------------------------------------------------- |
+| `result["index.html"]` is `undefined` | Wrong `sourcePath`, or `index.html` was renamed/moved.                       |
+| `dom.querySelector(...)` returns null | Selector doesn't match — remember the wrapper custom tag is gone.            |
+| `el.textContent` is empty             | `.pre.ts`/`.post.ts` didn't run, or template wasn't loaded.                  |
+| Test passes locally, fails in CI      | Missing env var (`NODE_ENV`), or absolute paths assumed.                     |
+| Slow test suite                       | Building inside `it()` — move to `beforeAll`.                                |
+| Type error on `dom?.querySelector`    | Import `Document` from your test setup or cast — the dom is parser-flavored. |
+
+For build-time errors (the build itself fails), see `tkeron-troubleshooting`.

package/skills/tkeron-troubleshooting/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: tkeron-troubleshooting
+description: "Troubleshooting tkeron builds and the dev server: common errors with cause-and-fix (Bundle failed, Cannot resolve, missing hyphen, component not replaced, build hangs, websrc not found), dev server singleton recovery after a crash, debugging workflow (read web/, isolate the offending file, check iteration limits), and a quick diagnostic flowchart. Use this skill when a build fails, a component is not inlined, the dev server is down, or output looks wrong."
+---
+
+# Tkeron — Troubleshooting
+
+## Diagnostic Flowchart
+
+```
+Something is wrong
+│
+├─ Build fails with an error message?            → "Common Build Errors" section
+├─ Build succeeds but output is wrong?           → "Output Looks Wrong" section
+├─ Dev server is down / hot reload not working?  → "Dev Server Recovery" section
+├─ Test fails?                                   → see tkeron-testing → "Common Test Failures"
+└─ Type error in IDE only?                       → "IDE vs Build" section
+```
+
+---
+
+## Common Build Errors
+
+### `Bundle failed` / `Cannot resolve "./index.js"`
+
+**Cause**: HTML references `.js` but the source is `.ts`.
+
+```html
+<!-- ❌ -->
+<script src="index.js"></script>
+
+<!-- ✅ -->
+<script type="module" src="./index.ts"></script>
+```
+
+### `Cannot resolve "/styles.css"`
+
+**Cause**: absolute path in a `<link rel="stylesheet">`. Two problems: the path is absolute (Bun resolves from the source file, not the server root), and `<link rel="stylesheet">` is itself an anti-pattern in tkeron.
+
+**Fix**: replace the `<link>` with a `<global-styles>` component that inlines the CSS at build time. See `tkeron-patterns` → "CSS via components".
+
+```html
+<!-- ❌ BAD -->
+<link rel="stylesheet" href="/styles.css" />
+<!-- ⚠️ Works but anti-pattern (extra request, no dedup) -->
+<link rel="stylesheet" href="./styles.css" />
+<!-- ✅ GOOD — inlined, no extra request, dedup-friendly -->
+<global-styles></global-styles>
+```
+
+### `Component name must contain hyphen`
+
+**Cause**: a `.com.html` / `.com.ts` / `.com.md` whose base name has no hyphen, or collides with a standard HTML tag.
+
+Fix: rename to kebab-case with a hyphen: `card.com.html` → `info-card.com.html`. See `tkeron-organization` for naming rules.
+
+### `Source directory websrc does not exist`
+
+Fix: run `tk init .` to scaffold, or `mkdir websrc` and create at least an `index.html`.
+
+### `Skill files already exist: ...` (from `tk skills`)
+
+Fix: pass `--force` to overwrite, or delete the existing skill folder first.
+
+### `Skills directory not found in tkeron installation`
+
+**Cause**: corrupted or partial install of the `tkeron` package.
+
+Fix: `bun add -g tkeron@latest` (or reinstall locally).
+
+### Build hangs forever
+
+**Cause**: `fetch()` without timeout in `.pre.ts` / `.post.ts` / `.com.ts`. The build event loop waits for the promise.
+
+Fix: always wrap external fetches with `AbortController` + a 5 s timeout. See pattern in `tkeron-patterns`.
+
+### `Maximum iterations reached` (or component loop never settles)
+
+**Cause**: a `.com.ts` keeps emitting the same custom element it is processing, producing infinite expansion. Or two components reference each other circularly.
+
+Fix:
+
+1. Find the component whose `innerHTML` contains its own tag.
+2. Break the cycle (emit raw HTML instead of the wrapper, or use a different tag).
+3. Limit: 10 iterations, 50 nesting levels — exceeding either aborts the build.
+
+---
+
+## Output Looks Wrong
+
+### A component tag is still in `web/index.html`
+
+```html
+<!-- Final output still shows: -->
+<user-card></user-card>
+```
+
+Causes (in order of frequency):
+
+1. **File name mismatch**: tag is `<user-card>` but file is `userCard.com.html` or `usercard.com.html`. Tkeron is case-insensitive but expects matching kebab-case.
+2. **Wrong extension**: file ends in `.html` instead of `.com.html`.
+3. **File outside `websrc/`**: tkeron only scans `websrc/`.
+4. **Typo**: `<user-cards>` vs `user-card.com.html`.
+
+Verify:
+
+```bash
+ls websrc/**/*.com.* | grep -i user-card
+grep -rn "<user-card" websrc/
+```
+
+### A `.com.ts` runs but `com.innerHTML` is empty in output
+
+**Cause**: the `.com.ts` did not assign `com.innerHTML`. Only `com.innerHTML` survives — `textContent`, `appendChild`, `setAttribute` on `com` itself are all discarded.
+
+```typescript
+// ❌ — discarded
+com.textContent = "hi";
+com.appendChild(document.createElement("span"));
+
+// ✅ — preserved
+com.innerHTML = `<span>hi</span>`;
+```
+
+### A `<script>` inside `com.innerHTML` is corrupted in output
+
+**Cause**: the HTML parser re-serializes `innerHTML`, and `<`, `>`, `&` inside script JS get double-escaped.
+
+Fix:
+
+- Avoid comparison operators inside the inline script (`>=`, `<=`, `>`, `<`).
+- Use `matchMedia('(min-width: Xpx)')` instead of `window.innerWidth >= X`.
+- Move complex logic to a separate browser `.ts` file and only emit a `<script type="module" src="./x.ts"></script>` tag.
+
+### Custom CSS selector targets the wrapper tag and matches nothing
+
+**Cause**: the wrapper tag (`<my-section>`) disappears from the output — only the children of `innerHTML` remain.
+
+Fix: write CSS targeting the class/element you emit **inside** `innerHTML`, never the custom tag. See `tkeron-components` → "wrapper tag disappears".
+
+### `.pre.ts` ran but the page does not reflect it
+
+Checklist:
+
+1. Is the file named EXACTLY `<page>.pre.ts` next to `<page>.html`? Pairing is by file name.
+2. Did the script throw silently? Run `tk build` and read the full stderr.
+3. Are you querying nodes that don't exist yet because the component loop hasn't run? `.pre.ts` runs BEFORE components — query only what is in the source HTML.
+
+### `.post.ts` ran but did not see component output
+
+Same as above, but reversed: `.post.ts` runs AFTER the component loop, so you CAN query nodes emitted by components. If you can't, check the script name pairs the page, and that you didn't accidentally use `.pre.ts` instead.
+
+### Assets disappeared from `web/`
+
+Check:
+
+1. File names contain spaces? Tkeron silently fails to copy them. Rename to kebab-case.
+2. File is inside a `.com.*` or `.pre.ts` pair? Those are excluded from output by design.
+3. File has the `.com.html` / `.com.ts` / `.com.md` / `.pre.ts` / `.post.ts` extension? Those are never copied.
+
+---
+
+## Dev Server Recovery
+
+`tk dev` is a **singleton process** per port. The first thing to check is whether it is even running.
+
+### Check status
+
+```bash
+fuser 3000/tcp 2>/dev/null
+# Empty output → not running
+# Has output    → running
+```
+
+### Recovery after a crash
+
+`tk dev` can crash when an edit in `websrc/` introduces a compile or syntax error. Steps:
+
+1. Confirm it's down: `fuser 3000/tcp 2>/dev/null` returns empty.
+2. Read the terminal where `tk dev` was running — the last lines explain why it crashed.
+3. Identify the offending file in `websrc/` (TS error, malformed component, broken import).
+4. Fix the file.
+5. Relaunch **in background**:
+   ```bash
+   tk dev
+   ```
+   (In agent sessions, this MUST be an async terminal — `tk dev` blocks indefinitely.)
+6. Confirm it is up: `fuser 3000/tcp 2>/dev/null` returns output.
+
+### Port already in use
+
+```
+Error: listen EADDRINUSE :::3000
+```
+
+Cause: another `tk dev` (or another process) holds port 3000.
+
+```bash
+fuser -k 3000/tcp   # kill the holder
+# OR launch on a different port:
+tk dev 3001
+```
+
+### Hot reload not firing
+
+1. Browser tab too old (before the reload script was injected) → hard refresh once (`Ctrl+Shift+R`).
+2. SSE connection blocked by a proxy/extension → check DevTools → Network → `/dev-reload` should be `text/event-stream`, status `200`, hanging open.
+3. The watcher missed the file (rare on network volumes / Docker bind mounts) → restart `tk dev`.
+
+### `tk dev` blocks the agent terminal
+
+`tk dev` runs forever by design. In agent sessions:
+
+- ALWAYS launch it as an async terminal (background mode).
+- NEVER run it synchronously — it will time out and leave a zombie.
+- Use `fuser 3000/tcp 2>/dev/null` as the readiness check, not a sleep.
+
+---
+
+## Debugging Workflow
+
+When something is wrong, follow this order:
+
+1. **Reproduce with `tk build`** (not `tk dev`) — it's deterministic and gives full stderr.
+2. **Read `web/<page>.html`** — does the component appear unprocessed? Are scripts referenced as `.js`?
+3. **Isolate**: comment out custom elements one by one to find the offender.
+4. **Strip to minimum**: replace the suspect `.com.ts` body with `com.innerHTML = "OK";` and rebuild — confirms whether the file is even loaded.
+5. **Check naming**: file name vs tag name (kebab-case, hyphen, no collisions with standard HTML).
+6. **Check pairing**: `.pre.ts` / `.post.ts` must share the base name with the `.html`.
+7. **Check imports**: relative paths, no `.js` extensions for source TS files imported from build-time scripts.
+
+---
+
+## IDE vs Build
+
+The IDE can show errors that the build does not (and vice versa):
+
+| Symptom                                 | What it means                                                    |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| IDE: red squiggle on `com`              | `tkeron.d.ts` missing or not in `tsconfig.json` `include`.       |
+| IDE: red squiggle on `document` in .pre | Same as above for the `*.pre.ts` declaration.                    |
+| Build: passes but IDE shows type errors | Tkeron does NOT type-check. Run `bun x tsc --noEmit` to confirm. |
+| Build: fails with a TS-looking error    | It's a Bun **compile** error, not a type error — fix the syntax. |
+
+Recommended pre-commit / CI step:
+
+```bash
+bun x tsc --noEmit && tk build
+```
+
+---
+
+## Last-Resort Reset
+
+If the project is in a weird state (stale temp dirs, mismatched output):
+
+```bash
+# Remove the output and any leftover temp build dirs
+rm -rf web/ .tktmp_*
+tk build
+```
+
+`getBuildResult` cleans its own temp dirs (`.tktmp_buildresult-*`), but a hard-killed build can leave them behind. They are always siblings of `websrc/`.

package/src/build.ts

@@ -8,11 +8,9 @@ import { processPost } from "./processPost";
 import { deduplicateComStyles } from "./deduplicateComStyles";
 import { rm, exists, mkdir, cp } from "fs/promises";
 import type { Logger } from "@tkeron/tools";
-import { silentLogger } from "@tkeron/tools";
-import {
-  cleanupOrphanedTempDirs,
-  TEMP_DIR_PREFIX,
-} from "./cleanupOrphanedTempDirs";
+import { silentLogger, cleanupOrphanedTempDirs } from "@tkeron/tools";
+
+export const TEMP_DIR_PREFIX = ".tktmp_build-";
 
 export interface BuildOptions {
   sourceDir?: string;
@@ -38,7 +36,7 @@ export const build = async (options: BuildOptions) => {
     `${TEMP_DIR_PREFIX}${crypto.randomUUID()}`,
   );
 
-  await cleanupOrphanedTempDirs(sourceParent, log);
+  await cleanupOrphanedTempDirs(sourceParent, TEMP_DIR_PREFIX, log);
 
   try {
     await mkdir(tempDir, { recursive: true });

package/src/develop.ts

@@ -2,8 +2,7 @@ import { resolve, dirname } from "path";
 import { watch } from "fs";
 import { build } from "./build";
 import type { Logger } from "@tkeron/tools";
-import { logger as defaultLogger } from "@tkeron/tools";
-import { setupSigintHandler } from "./setupSigintHandler";
+import { logger as defaultLogger, setupSigintHandler } from "@tkeron/tools";
 
 export interface TkeronDevOptions {
   outputDir?: string;

package/src/init.ts

@@ -9,8 +9,7 @@ import {
 } from "fs";
 import { join, resolve, basename } from "path";
 import type { Logger } from "@tkeron/tools";
-import { silentLogger } from "@tkeron/tools";
-import { promptUser } from "./promptUser";
+import { silentLogger, promptUser } from "@tkeron/tools";
 import { ensureTsconfig } from "./ensureTsconfig";
 
 export interface InitOptions {

package/src/skills.ts

@@ -0,0 +1,139 @@
+import {
+  existsSync,
+  readdirSync,
+  mkdirSync,
+  cpSync,
+  statSync,
+  readFileSync,
+  writeFileSync,
+} from "fs";
+import { join, resolve } from "path";
+import type { Logger } from "@tkeron/tools";
+import {
+  silentLogger,
+  detectEnvironments,
+  addFrontmatterField,
+} from "@tkeron/tools";
+import type { Environment } from "@tkeron/tools";
+
+export interface SkillsOptions {
+  target?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  logger?: Logger;
+}
+
+const getTransform = (env: Environment) => {
+  if (env === "cursor") {
+    return (content: string) =>
+      addFrontmatterField(content, "alwaysApply", false);
+  }
+  return null;
+};
+
+const installToDir = (
+  skillNames: string[],
+  sourceDir: string,
+  targetDir: string,
+  transform: ((content: string) => string) | null,
+  force: boolean,
+  log: Logger,
+) => {
+  const conflicts: string[] = [];
+  for (const name of skillNames) {
+    const dest = join(targetDir, name, "SKILL.md");
+    if (existsSync(dest)) {
+      conflicts.push(name);
+    }
+  }
+
+  if (conflicts.length > 0 && !force) {
+    throw new Error(
+      `Skill files already exist: ${conflicts.join(", ")}. Use --force to overwrite.`,
+    );
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+
+  for (const name of skillNames) {
+    const src = join(sourceDir, name);
+    const dest = join(targetDir, name);
+    cpSync(src, dest, { recursive: true, force: true });
+
+    if (transform) {
+      const skillFile = join(dest, "SKILL.md");
+      if (existsSync(skillFile)) {
+        const content = readFileSync(skillFile, "utf-8");
+        writeFileSync(skillFile, transform(content), "utf-8");
+      }
+    }
+
+    log.log(`✓ Installed skill: ${name}`);
+  }
+};
+
+const previewToDir = (skillNames: string[], targetDir: string, log: Logger) => {
+  for (const name of skillNames) {
+    const dest = join(targetDir, name, "SKILL.md");
+    log.log(`○ Would install: ${name} → ${dest}`);
+  }
+};
+
+export const skills = async (options: SkillsOptions = {}) => {
+  const {
+    target,
+    force = false,
+    dryRun = false,
+    logger: log = silentLogger,
+  } = options;
+
+  const sourceDir = join(import.meta.dir, "..", "skills");
+
+  if (!existsSync(sourceDir)) {
+    throw new Error("Skills directory not found in tkeron installation");
+  }
+
+  const skillNames = readdirSync(sourceDir).filter((name) =>
+    statSync(join(sourceDir, name)).isDirectory(),
+  );
+
+  if (skillNames.length === 0) {
+    throw new Error("No skills available to install");
+  }
+
+  if (target !== undefined) {
+    const targetDir = resolve(process.cwd(), target);
+    if (dryRun) {
+      previewToDir(skillNames, targetDir, log);
+      log.log(
+        `\n📋 ${skillNames.length} skill(s) would be installed in ${targetDir}`,
+      );
+    } else {
+      installToDir(skillNames, sourceDir, targetDir, null, force, log);
+      log.log(`\n✅ ${skillNames.length} skill(s) installed in ${targetDir}`);
+    }
+    return;
+  }
+
+  const detected = detectEnvironments(process.cwd());
+
+  if (detected.length === 0) {
+    throw new Error("NO_ENVIRONMENTS_DETECTED");
+  }
+
+  for (const { env, target: envTarget } of detected) {
+    const targetDir = resolve(process.cwd(), envTarget);
+    if (dryRun) {
+      previewToDir(skillNames, targetDir, log);
+      log.log(
+        `\n📋 ${skillNames.length} skill(s) would be installed for ${env} in ${targetDir}`,
+      );
+    } else {
+      const transform = getTransform(env);
+      installToDir(skillNames, sourceDir, targetDir, transform, force, log);
+      log.log(
+        `\n✅ ${skillNames.length} skill(s) installed for ${env} in ${targetDir}`,
+      );
+    }
+  }
+};