tkeron 5.3.0 → 6.0.1

package/skills/tkeron/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: tkeron
+description: "Tkeron core overview: what it is, full CLI reference (build, dev, init, skills), file-type summary, build lifecycle, IDE support files, environment variables, build-time vs runtime. Load this skill first when starting any tkeron task — it is the entry point that points to the other tkeron-* skills."
+---
+
+# Tkeron — Core
+
+## What It Is
+
+CLI build tool for vanilla web development. Compiles TypeScript, processes HTML/TS/Markdown components, runs pre-/post-rendering scripts, generates static files ready to deploy. Powered by **Bun**. Zero frameworks. Zero runtime. Zero external bundlers.
+
+## The tkeron skill set
+
+| Skill                    | When to load it                                                            |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `tkeron` (this one)      | Always first. CLI, lifecycle, file-type overview.                          |
+| `tkeron-components`      | Creating/editing `.com.html`, `.com.ts`, `.com.md`, `.pre.ts`, `.post.ts`. |
+| `tkeron-organization`    | Designing project structure, deciding when to componentize, naming.        |
+| `tkeron-patterns`        | Implementing features — best patterns, anti-patterns, max-pre-render rule. |
+| `tkeron-testing`         | Writing tests with `getBuildResult` from `tkeron`.                         |
+| `tkeron-troubleshooting` | Build fails, dev server crashes, component is not replaced, common errors. |
+
+---
+
+## Input and Output
+
+```
+project/
+├── tkeron.d.ts        # IDE types (com, document globals)
+├── tsconfig.json      # TS config for IDE
+├── websrc/            # ← INPUT (all source files live here)
+│   ├── index.html     # Pages (root = sitemap)
+│   ├── index.ts       # Browser TypeScript (compiled to .js)
+│   ├── index.pre.ts   # Pre-rendering (build time, before components)
+│   ├── index.post.ts  # Post-processing (build time, after components)
+│   ├── about.html     # More pages at root = more routes
+│   ├── docs/          # Subdirectories = sub-routes
+│   │   └── *.html
+│   ├── components/    # Components (NOT routes) — see tkeron-organization
+│   ├── styles/        # CSS, assets
+│   └── utils/         # Helpers imported by .com.ts or .pre.ts
+└── web/               # ← OUTPUT (generated by tk build)
+    ├── index.html     # Processed HTML (components inlined)
+    ├── index.js       # TS compiled
+    └── styles/        # CSS copied
+```
+
+**Fixed directories**: `websrc/` is input, `web/` is output. No configuration. Convention over configuration.
+
+> **IMPORTANT**: `web/` is generated by `tk build` and `tk dev`. It MUST be in `.gitignore`. **Never edit or commit its contents** — any manual change is overwritten on the next build.
+
+**Files NOT copied to output**: `*.com.html`, `*.com.ts`, `*.com.md`, `*.pre.ts`, `*.post.ts`.
+
+---
+
+## CLI Reference
+
+```bash
+tk                              # Banner + version
+tk init <name>                  # New project in <name>/
+tk init .                       # Initialize in current directory
+tk init <name> --force          # Overwrite existing
+tk build                        # Compile websrc/ → web/
+tk b                            # Alias for build
+tk dev                          # Dev server on localhost:3000 + hot reload
+tk dev 8080                     # Custom port
+tk dev 8080 0.0.0.0             # Custom port + host
+tk skills                       # Install AI agent skills (auto-detect env)
+tk skills <dir>                 # Install into a custom directory
+tk skills --force               # Overwrite existing skill files
+```
+
+| Command      | Aliases          | What it does                                |
+| ------------ | ---------------- | ------------------------------------------- |
+| `tk build`   | `tk b`           | Full build of `websrc/` → `web/`            |
+| `tk develop` | `tk dev`, `tk d` | Dev server + watch + hot reload (singleton) |
+| `tk init`    | `tk i`           | Create project from template                |
+| `tk skills`  | —                | Install AI agent skills                     |
+
+### `tk dev` — important
+
+- Defaults: port `3000`, host `localhost`. Positional args: `tk dev <port> <host>`.
+- **Singleton per port**: only one instance at a time. Check `fuser 3000/tcp 2>/dev/null` before launching.
+- Watches `websrc/`, rebuilds on save, broadcasts via SSE on `/dev-reload`, injects the reload script before `</body>`.
+- Clean URLs: `/about` serves `about.html`, `/blog/` serves `blog/index.html`.
+- **In agent sessions**: ALWAYS run `tk dev` in background (it blocks indefinitely). NEVER run it synchronously.
+- If it crashes after a `websrc/` edit → see `tkeron-troubleshooting`.
+
+### `tk build` — required after editing `websrc/`
+
+> **RULE**: After any change in `websrc/`, run `tk build` and then read the relevant files in `web/` (`web/*.html`, `web/*.js`) to verify components were inlined and TS compiled as expected.
+
+If output is wrong → fix in `websrc/` and rebuild. **NEVER edit `web/` directly.**
+
+### `tk init` — what it creates
+
+```
+project/
+├── websrc/
+│   ├── index.html              # Sample home page
+│   ├── index.ts                # Sample browser TS
+│   ├── index.pre.ts            # Sample pre-render
+│   ├── api-service.ts          # Sample service
+│   ├── *.com.html              # Sample HTML components
+│   └── user-badge.com.ts       # Sample TS component
+├── tkeron.d.ts                 # IDE types
+└── tsconfig.json               # TS config for IDE
+```
+
+Behavior:
+
+- In an empty/new directory: creates the full template.
+- In a directory with an existing `websrc/` or `tkeron.d.ts`: prompts before overwriting (use `--force` to skip the prompt).
+- Always preserves any pre-existing fields in your `tsconfig.json` and merges the tkeron defaults.
+
+### `tk skills` — environment auto-detection
+
+`tk skills` (no argument) detects the AI environment from the current directory and installs into the matching folder:
+
+| Detected marker           | Environment | Install target    | Special transform                        |
+| ------------------------- | ----------- | ----------------- | ---------------------------------------- |
+| `.cursor/`                | cursor      | `.cursor/rules/`  | adds `alwaysApply: false` to frontmatter |
+| `.github/`                | copilot     | `.github/skills/` | none                                     |
+| `.claude/` or `CLAUDE.md` | claude      | `.claude/rules/`  | none                                     |
+
+- Multiple environments detected → installs into all of them.
+- None detected → prompts to create `./skills/`.
+- Explicit target (`tk skills my-skills-dir`) → installs there, no env detection, no transform.
+- Conflicts (skill file already exists) → fails with a clear message; use `--force` to overwrite.
+
+---
+
+## Build Lifecycle — Exact Order
+
+```
+websrc/  ─────────────────────────────────────────────────→  web/
+
+  [1] .pre.ts          Run pre-render scripts (Bun runtime)
+                        Each .pre.ts modifies its paired .html
+                        — runs BEFORE components, can inject custom elements
+
+  [2] Iterative loop (max 10 iterations, until no more changes):
+      ├─ .com.ts       Execute TypeScript components
+      ├─ .com.html     Inline HTML components
+      └─ .com.md       Render Markdown components
+
+  [3] .post.ts         Run post-render scripts (Bun runtime)
+                        Each .post.ts mutates its paired .html with the
+                        components ALREADY resolved — final DOM walk
+
+  [4] .ts → .js        Compile TypeScript (Bun.build)
+
+  [5] Asset copy       Copy everything else to the output
+```
+
+**Key order**: `.pre.ts` runs FIRST (can inject custom elements that the component loop then processes). `.post.ts` runs LAST (sees the fully-resolved DOM — perfect for `loading="lazy"`, `rel="noopener"`, TOCs, heading `id`s).
+
+Limits: max **10 iterations**, max **50 nesting levels**, no circular dependencies.
+
+---
+
+## File Types — Summary
+
+| Extension   | When it runs             | Runtime    | Special variable     | Copied to web/ |
+| ----------- | ------------------------ | ---------- | -------------------- | -------------- |
+| `.html`     | —                        | —          | —                    | ✅ (processed) |
+| `.ts`       | Browser                  | V8/Browser | `window`, `document` | ✅ (→ .js)     |
+| `.com.html` | Build time               | —          | —                    | ❌             |
+| `.com.ts`   | Build time               | Bun        | `com`                | ❌             |
+| `.com.md`   | Build time               | —          | —                    | ❌             |
+| `.pre.ts`   | Build time (BEFORE coms) | Bun        | `document`           | ❌             |
+| `.post.ts`  | Build time (AFTER coms)  | Bun        | `document`           | ❌             |
+
+> Full reference (the `com` API, attribute reading, nesting, examples) lives in `tkeron-components`.
+
+### `.html` — Page essentials
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>My Site</title>
+    <global-styles></global-styles>
+  </head>
+  <body>
+    <site-header></site-header>
+    <main>Content</main>
+    <script type="module" src="./index.ts"></script>
+  </body>
+</html>
+```
+
+**Three non-negotiable rules**:
+
+1. **`src="index.ts"` with `type="module"`**, NEVER `.js`. Tkeron compiles and rewrites the reference.
+2. **Relative paths only** (`./`, `../`). NEVER absolute (`/file.ext`) — Bun cannot resolve them at build time. Applies to `.html`, `.com.html`, and `url()` in CSS.
+3. **CSS via components, never `<link rel="stylesheet">`**. A `<global-styles>` component reads the `.css` file at build time and inlines it as `<style>` — no extra request, dedup-friendly. See `tkeron-patterns` → "CSS via components".
+
+---
+
+## IDE — Support Files
+
+Generated by `tk init`. For the IDE only, do not affect the build.
+
+### `tkeron.d.ts`
+
+```typescript
+declare module "*.com.ts" {
+  global {
+    const com: HTMLElement;
+  }
+}
+
+declare module "*.pre.ts" {
+  global {
+    const document: Document;
+  }
+}
+
+declare module "*.post.ts" {
+  global {
+    const document: Document;
+  }
+}
+```
+
+### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext", "DOM"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["websrc/**/*", "tkeron.d.ts"]
+}
+```
+
+---
+
+## Environment Variables
+
+```typescript
+// In .pre.ts, .post.ts or .com.ts (build time)
+process.env.TKERON_VERSION; // tkeron version (injected automatically)
+process.env.NODE_ENV; // development / production
+process.env.MY_VAR; // any custom variable
+```
+
+```bash
+NODE_ENV=production MY_VAR=value tk build
+```
+
+Browser `.ts` files do **not** see `process.env` — `process` does not exist in the browser. To pass build-time values to the runtime, write them into the DOM from a `.pre.ts` (e.g. `<meta name="config" content="...">`) and read them from `.ts`.
+
+---
+
+## Type Checking
+
+Tkeron does NOT type-check, it only compiles. To check types:
+
+```bash
+bun x tsc --noEmit && tk build
+```
+
+---
+
+## Build Time vs Runtime — Quick Reference
+
+| Aspect         | Build (`.pre.ts`, `.com.ts`, `.post.ts`) | Runtime (`.ts` → `.js`) |
+| -------------- | ---------------------------------------- | ----------------------- |
+| When it runs   | `tk build`                               | User's browser          |
+| Runtime        | Bun                                      | V8/Browser              |
+| `fetch()`      | ✅                                       | ✅                      |
+| `window`       | ❌                                       | ✅                      |
+| `localStorage` | ❌                                       | ✅                      |
+| DOM events     | ❌ (lost in output)                      | ✅                      |
+| npm packages   | ✅                                       | ❌ (not bundled)        |
+| Bun APIs       | ✅                                       | ❌                      |
+| `process.env`  | ✅                                       | ❌                      |
+
+For full do/don't rules and the **maximum pre-render** rule, load `tkeron-patterns`.