tkeron 5.3.0 → 6.0.0

package/examples/init_sample/websrc/index.html

@@ -12,7 +12,7 @@
         box-sizing: border-box;
       }
       body {
-        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+        font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
         line-height: 1.6;
         color: #1a1a1a;
         background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
@@ -49,7 +49,7 @@
         backdrop-filter: blur(10px);
         padding: 1.5rem;
         border-radius: 12px;
-        box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
         grid-row: span 2;
       }
       .hero .features {
@@ -67,17 +67,22 @@
         width: 200px;
         height: 200px;
         margin-bottom: 1rem;
-        filter: drop-shadow(0 4px 6px rgba(0,0,0,0.2));
+        filter: drop-shadow(0 4px 6px rgba(0, 0, 0, 0.2));
         animation: float 3s ease-in-out infinite;
       }
       @keyframes float {
-        0%, 100% { transform: translateY(0); }
-        50% { transform: translateY(-10px); }
+        0%,
+        100% {
+          transform: translateY(0);
+        }
+        50% {
+          transform: translateY(-10px);
+        }
       }
       h1 {
         font-size: 2rem;
         margin-bottom: 0.25rem;
-        text-shadow: 0 2px 4px rgba(0,0,0,0.2);
+        text-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
       }
       .subtitle {
         font-size: 0.9rem;
@@ -87,12 +92,14 @@
         background: white;
         padding: 1.25rem;
         border-radius: 12px;
-        box-shadow: 0 4px 6px rgba(0,0,0,0.1);
-        transition: transform 0.2s, box-shadow 0.2s;
+        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+        transition:
+          transform 0.2s,
+          box-shadow 0.2s;
       }
       section:hover {
         transform: translateY(-4px);
-        box-shadow: 0 8px 12px rgba(0,0,0,0.15);
+        box-shadow: 0 8px 12px rgba(0, 0, 0, 0.15);
       }
       h2 {
         color: #667eea;
@@ -118,12 +125,14 @@
         cursor: pointer;
         font-size: 1rem;
         font-weight: 600;
-        transition: transform 0.1s, box-shadow 0.2s;
-        box-shadow: 0 2px 4px rgba(0,0,0,0.2);
+        transition:
+          transform 0.1s,
+          box-shadow 0.2s;
+        box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
       }
       button:hover {
         transform: scale(1.05);
-        box-shadow: 0 4px 8px rgba(0,0,0,0.3);
+        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
       }
       button:active {
         transform: scale(0.98);
@@ -141,18 +150,20 @@
         background: #f0f0f0;
         padding: 0.2rem 0.4rem;
         border-radius: 4px;
-        font-family: 'Courier New', monospace;
+        font-family: "Courier New", monospace;
         font-size: 0.9em;
       }
       p {
         margin-bottom: 0.5rem;
       }
       a {
-        transition: transform 0.2s, box-shadow 0.2s;
+        transition:
+          transform 0.2s,
+          box-shadow 0.2s;
       }
       a:hover {
         transform: translateY(-2px);
-        box-shadow: 0 4px 8px rgba(0,0,0,0.3);
+        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
       }
       .crypto-prices-container {
         display: grid;
@@ -165,7 +176,7 @@
         padding: 1.25rem;
         border-radius: 12px;
         color: white;
-        box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
         transition: transform 0.2s;
       }
       .crypto-card:hover {
@@ -182,7 +193,7 @@
         font-size: 1rem;
       }
       .crypto-symbol {
-        background: rgba(255,255,255,0.2);
+        background: rgba(255, 255, 255, 0.2);
         padding: 0.25rem 0.5rem;
         border-radius: 4px;
         font-size: 0.75rem;
@@ -207,20 +218,42 @@
         <html-components-card></html-components-card>
         <ts-components-card></ts-components-card>
         <counter-card></counter-card>
-        
+
         <!-- Crypto Prices - fetched at build time -->
-        <section style="grid-column: span 3;">
+        <section style="grid-column: span 3">
           <h2>💰 Asset Prices (Build Time)</h2>
-          <p style="font-size: 0.85rem; margin-bottom: 0.75rem;">Real cryptocurrency prices fetched from CoinGecko API at build time:</p>
+          <p style="font-size: 0.85rem; margin-bottom: 0.75rem">
+            Real cryptocurrency prices fetched from CoinGecko API at build time:
+          </p>
           <div id="crypto-prices" class="crypto-prices-container"></div>
         </section>
-        
+
         <!-- Pre-rendered content with external API data -->
-        <section style="grid-column: span 3;">
+        <section style="grid-column: span 3">
           <h2>💬 Quote of the Build</h2>
-          <p style="font-size: 0.85rem; margin-bottom: 0.75rem;">This content was fetched from an external API at build time:</p>
-          <div id="pre-rendered-quote" style="margin: 1rem 0; padding: 0.75rem; background: #f8f9fa; border-radius: 8px; border-left: 4px solid #667eea;"></div>
-          <div id="build-metadata" style="margin-top: 1rem; padding-top: 0.75rem; border-top: 1px solid #eee; font-size: 0.75rem; color: #999;"></div>
+          <p style="font-size: 0.85rem; margin-bottom: 0.75rem">
+            This content was fetched from an external API at build time:
+          </p>
+          <div
+            id="pre-rendered-quote"
+            style="
+              margin: 1rem 0;
+              padding: 0.75rem;
+              background: #f8f9fa;
+              border-radius: 8px;
+              border-left: 4px solid #667eea;
+            "
+          ></div>
+          <div
+            id="build-metadata"
+            style="
+              margin-top: 1rem;
+              padding-top: 0.75rem;
+              border-top: 1px solid #eee;
+              font-size: 0.75rem;
+              color: #999;
+            "
+          ></div>
         </section>
       </div>
     </div>

package/examples/init_sample/websrc/index.pre.ts

@@ -1,8 +1,12 @@
 // Pre-rendering - runs at build time
 // Demonstrates importing any TypeScript module for pre-rendering
-import { getRandomQuote, getBuildMetadata, getCryptoPrices } from './api-service';
+import {
+  getRandomQuote,
+  getBuildMetadata,
+  getCryptoPrices,
+} from "./api-service";
 
-const buildTimeElement = document.getElementById('build-time');
+const buildTimeElement = document.getElementById("build-time");
 
 if (buildTimeElement) {
   const now = new Date();
@@ -10,7 +14,7 @@ if (buildTimeElement) {
 }
 
 // Fetch data from external API at build time
-const quoteElement = document.getElementById('pre-rendered-quote');
+const quoteElement = document.getElementById("pre-rendered-quote");
 if (quoteElement) {
   const quote = await getRandomQuote();
   quoteElement.innerHTML = `
@@ -22,7 +26,7 @@ if (quoteElement) {
 }
 
 // Add build metadata
-const metadataElement = document.getElementById('build-metadata');
+const metadataElement = document.getElementById("build-metadata");
 if (metadataElement) {
   const metadata = await getBuildMetadata();
   metadataElement.innerHTML = `
@@ -38,15 +42,17 @@ if (metadataElement) {
 }
 
 // Fetch crypto prices at build time
-const cryptoPricesElement = document.getElementById('crypto-prices');
+const cryptoPricesElement = document.getElementById("crypto-prices");
 if (cryptoPricesElement) {
   const prices = await getCryptoPrices();
-  
-  const pricesHtml = prices.map(crypto => {
-    const changeColor = crypto.price_change_percentage_24h >= 0 ? '#10b981' : '#ef4444';
-    const changeSymbol = crypto.price_change_percentage_24h >= 0 ? '▲' : '▼';
-    
-    return `
+
+  const pricesHtml = prices
+    .map((crypto) => {
+      const changeColor =
+        crypto.price_change_percentage_24h >= 0 ? "#10b981" : "#ef4444";
+      const changeSymbol = crypto.price_change_percentage_24h >= 0 ? "▲" : "▼";
+
+      return `
       <div class="crypto-card">
         <div class="crypto-header">
           <span class="crypto-name">${crypto.name}</span>
@@ -58,9 +64,8 @@ if (cryptoPricesElement) {
         </div>
       </div>
     `;
-  }).join('');
-  
+    })
+    .join("");
+
   cryptoPricesElement.innerHTML = pricesHtml;
 }
-
-

package/examples/init_sample/websrc/ts-components-card.com.html

@@ -1,6 +1,11 @@
 <section>
   <h2>⚡ TypeScript Components</h2>
-  <p style="margin-bottom: 0.75rem;">Dynamic generation with <code>.com.ts</code>:</p>
+  <p style="margin-bottom: 0.75rem">
+    Dynamic generation with <code>.com.ts</code>:
+  </p>
   <user-badge count="3"></user-badge>
-  <p style="font-size: 0.85rem; color: #666; margin-top: 0.75rem;">✓ Loops & conditionals<br>✓ Read attributes dynamically<br>✓ Build-time code execution</p>
+  <p style="font-size: 0.85rem; color: #666; margin-top: 0.75rem">
+    ✓ Loops & conditionals<br />✓ Read attributes dynamically<br />✓ Build-time
+    code execution
+  </p>
 </section>

package/index.ts

@@ -3,6 +3,7 @@ import { getCommands } from "@tkeron/commands";
 import { buildWrapper } from "./src/buildWrapper";
 import { develop } from "./src/develop";
 import { initWrapper } from "./src/initWrapper";
+import { skillsWrapper } from "./src/skillsWrapper";
 import { showBanner } from "./src/banner";
 import packageJson from "./package.json";
 
@@ -36,5 +37,19 @@ getCommands("tkeron", packageJson.version)
   .addOption("force")
   .setCallback(initWrapper)
 
+  .commands()
+
+  .addCommand("skills")
+  .addDescription("Install AI agent skills into the current project")
+  .addPositionedArgument("target")
+  .addOption("force")
+  .addOption({
+    name: "dryRun",
+    aliases: ["dry-run"],
+    type: "boolean",
+    description: "Preview what would be installed without making changes",
+  })
+  .setCallback(skillsWrapper)
+
   .commands()
   .start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tkeron",
-  "version": "5.3.0",
+  "version": "6.0.0",
   "description": "CLI build tool for vanilla web development with TypeScript.",
   "type": "module",
   "main": "./src/index.ts",
@@ -12,8 +12,7 @@
   },
   "bin": {
     "tkeron": "./index.ts",
-    "tk": "./index.ts",
-    "tkeron-mcp": "./mcp-server.ts"
+    "tk": "./index.ts"
   },
   "scripts": {
     "tk": "bun index.ts ",
@@ -23,15 +22,14 @@
   "author": "tkeron",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@tkeron/commands": "0.4.7",
-    "@tkeron/html-parser": "1.5.6",
-    "@tkeron/tools": "^0.4.1"
+    "@tkeron/commands": "0.4.8",
+    "@tkeron/html-parser": "1.5.7",
+    "@tkeron/tools": "^0.5.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.11",
-    "prettier": "^3.8.1",
-    "typescript": "^6.0.2"
+    "@types/bun": "^1.3.14",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
   },
   "keywords": [
     "cli",
@@ -41,9 +39,7 @@
     "pre-rendering",
     "static-site-generator",
     "backend-driven",
-    "mcp",
-    "model-context-protocol",
-    "ai-integration"
+    "ai-agents"
   ],
   "publishConfig": {
     "access": "public"

package/skills/tkeron/SKILL.md

@@ -0,0 +1,286 @@
+---
+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>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <site-header></site-header>
+    <main>Content</main>
+    <script type="module" src="./index.ts"></script>
+  </body>
+</html>
+```
+
+**Two non-negotiable rules**:
+
+1. **`src="index.ts"` with `type="module"`**, NEVER `.js`. Tkeron compiles and rewrites the reference.
+2. **Relative paths only** (`./`, `../`). NEVER absolute (`/styles.css`) — Bun cannot resolve them at build time. Applies to `.html`, `.com.html`, and `url()` in CSS.
+
+---
+
+## 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`.