tkeron 5.3.0 → 6.0.1

package/src/skillsWrapper.ts

@@ -0,0 +1,79 @@
+import { skills } from "./skills.js";
+import type { Logger } from "@tkeron/tools";
+import { logger as defaultLogger } from "@tkeron/tools";
+import { createInterface } from "readline";
+
+const stdinConfirm = async (message: string): Promise<boolean> => {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise<boolean>((resolve) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      resolve(trimmed === "y" || trimmed === "yes");
+    });
+  });
+};
+
+export interface SkillsWrapperOptions {
+  target?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  logger?: Logger;
+  confirm?: (message: string) => Promise<boolean>;
+  [key: string]: any;
+}
+
+export const skillsWrapper = async (options: SkillsWrapperOptions = {}) => {
+  const log = options?.logger || defaultLogger;
+  const confirm = options?.confirm ?? stdinConfirm;
+
+  try {
+    await skills({
+      target: options.target,
+      force: options.force,
+      dryRun: options.dryRun,
+      logger: log,
+    });
+  } catch (error: any) {
+    if (error.message === "NO_ENVIRONMENTS_DETECTED") {
+      if (options.dryRun) {
+        log.log(
+          "\n⚠ No known AI environment detected (.cursor/, .github/, .claude/).",
+        );
+        log.log("  Would create a skills/ directory in the current directory.");
+        return;
+      }
+      log.log(
+        "\n⚠ No known AI environment detected (.cursor/, .github/, .claude/).",
+      );
+      log.log(
+        "  A skills/ directory will be created in the current directory instead.",
+      );
+
+      const proceed = await confirm("  Continue? (y/N): ");
+      if (!proceed) {
+        log.log("Aborted.");
+        return;
+      }
+
+      try {
+        await skills({ target: "skills", force: options.force, logger: log });
+      } catch (err: any) {
+        log.error(`\n❌ ${err.message}\n`);
+        if (/already exist/i.test(err.message)) {
+          log.error(
+            "💡 Tip: pass --force to overwrite existing skill files.\n",
+          );
+        }
+        process.exit(1);
+      }
+      return;
+    }
+
+    log.error(`\n❌ ${error.message}\n`);
+    if (/already exist/i.test(error.message)) {
+      log.error("💡 Tip: pass --force to overwrite existing skill files.\n");
+    }
+    process.exit(1);
+  }
+};

package/docs/mcp-server.md

@@ -1,240 +0,0 @@
-# MCP Server
-
-Tkeron includes a Model Context Protocol (MCP) server that exposes comprehensive documentation to AI agents and development tools.
-
-## What is MCP?
-
-The Model Context Protocol is a standard for providing context to AI agents. Tkeron's MCP server allows AI assistants to access up-to-date documentation about how to use Tkeron, its capabilities, and limitations.
-
-## Installation
-
-The MCP server is included when you install Tkeron globally:
-
-```bash
-bun install -g tkeron
-```
-
-This installs three commands:
-
-- `tk` / `tkeron` - The main CLI tool
-- `tkeron-mcp` - The MCP server
-
-## Configuration
-
-### VS Code
-
-Add to your MCP configuration file (`~/.config/Code/User/mcp.json`):
-
-```json
-{
-  "servers": {
-    "tkeron": {
-      "command": "tkeron-mcp"
-    }
-  }
-}
-```
-
-If the global command is not found, use Bun directly:
-
-```json
-{
-  "servers": {
-    "tkeron": {
-      "command": "bun",
-      "args": ["run", "/absolute/path/to/tkeron/mcp-server.ts"]
-    }
-  }
-}
-```
-
-**Note:** This is the VS Code format. Other editors (Cursor, Windsurf, etc.) may use different configuration formats.
-
-````
-
-**Find the path:**
-```bash
-# If tkeron is installed globally
-dirname $(which tk)
-# Returns something like: /home/user/.bun/bin
-
-# The mcp-server.ts is in the same directory
-ls $(dirname $(which tk))/mcp-server.ts
-````
-
-### Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent on other platforms:
-
-```json
-{
-  "mcpServers": {
-    "tkeron": {
-      "command": "tkeron-mcp"
-    }
-  }
-}
-```
-
-### Other MCP Clients
-
-Any MCP-compatible client can use the server. Configure it to run:
-
-```bash
-tkeron-mcp
-```
-
-The server communicates via stdio transport.
-
-## Available Resources
-
-The MCP server exposes the following documentation resources:
-
-| URI                              | Description                                          |
-| -------------------------------- | ---------------------------------------------------- |
-| `tkeron://overview`              | What Tkeron is, what it does, and what it's not      |
-| `tkeron://getting-started`       | Installation, first project, and basic workflow      |
-| `tkeron://components-html`       | Create reusable HTML components with .com.html files |
-| `tkeron://components-typescript` | Build dynamic components with .com.ts files          |
-| `tkeron://pre-rendering`         | Transform HTML at build time with .pre.ts files      |
-| `tkeron://cli-reference`         | Complete command-line interface documentation        |
-| `tkeron://best-practices`        | Patterns, anti-patterns, and limitations             |
-| `tkeron://common-issues`         | Troubleshooting guide and common mistakes            |
-| `tkeron://testing`               | How to test tkeron projects with getBuildResult()    |
-
-## What AI Agents Can Do
-
-With access to the MCP server, AI agents can:
-
-- ✅ Understand Tkeron's capabilities and limitations
-- ✅ Help users create components correctly
-- ✅ Suggest appropriate patterns for different use cases
-- ✅ Identify when Tkeron is NOT the right tool
-- ✅ Provide accurate CLI commands and options
-- ✅ Debug common issues with components and pre-rendering
-- ✅ Recommend best practices and avoid anti-patterns
-- ✅ **Prevent common mistakes** (script references, component naming, dependencies)
-- ✅ **List and explore example projects**
-- ✅ **Retrieve example code and structures**
-- ✅ **Initialize, build, and develop projects via terminal** (`tk init`, `tk build`, `tk dev`)
-
-## Available Tools
-
-The MCP server provides the following tools for AI agents:
-
-### Example Management Tools
-
-- **`list_examples`**: List all available Tkeron example projects
-  - No parameters required
-  - Returns example names, descriptions, and paths
-  - Helps users discover what's possible with Tkeron
-
-- **`get_example`**: Get the complete source code of an example
-  - Parameters: `example` (name of the example project)
-  - Returns file structure and all source code
-  - Useful for learning patterns and bootstrapping projects
-
-> **Note:** The MCP server only provides documentation and examples. It does NOT modify files. The AI agent should use terminal commands (`tk init`, `tk build`, `tk dev`) to manage projects.
-
-## Benefits
-
-### For Users
-
-- Get accurate help from AI assistants
-- AI understands your project structure
-- Contextual suggestions based on Tkeron's docs
-- Fewer mistakes and faster development
-
-### For AI Agents
-
-- Access to authoritative, up-to-date documentation
-- Clear understanding of limitations and constraints
-- Examples and patterns to reference
-- Ability to distinguish between what Tkeron can and can't do
-
-## Verification
-
-To verify the MCP server is working:
-
-1. Install Tkeron globally
-2. Configure your MCP client
-3. Restart your IDE/editor
-4. Ask your AI assistant: "What is Tkeron?"
-
-The assistant should be able to provide an accurate description based on the documentation.
-
-## Troubleshooting
-
-### "Command not found: tkeron-mcp"
-
-Make sure Tkeron is installed globally:
-
-```bash
-bun install -g tkeron
-which tkeron-mcp
-```
-
-### "Cannot find module"
-
-Ensure all dependencies are installed:
-
-```bash
-cd $(dirname $(which tkeron-mcp))
-bun install
-```
-
-### MCP Client Not Connecting
-
-Check your configuration file syntax:
-
-- Valid JSON
-- Correct command path
-- Proper permissions on the executable
-
-### Resources Not Loading
-
-Verify the docs directory exists:
-
-```bash
-ls $(dirname $(which tkeron-mcp))/docs/
-```
-
-All markdown files should be present.
-
-## For Developers
-
-### Adding New Resources
-
-To add new documentation resources:
-
-1. Create a new `.md` file in `docs/`
-2. Add an entry to the `DOCS` array in `mcp-server.ts`:
-
-```typescript
-{
-  uri: "tkeron://new-topic",
-  name: "New Topic",
-  description: "Description of the topic",
-  file: "new-topic.md",
-}
-```
-
-3. Rebuild and publish the package
-
-### Testing Locally
-
-Run the MCP server directly:
-
-```bash
-bun run mcp-server.ts
-```
-
-It will wait for stdio input (this is normal for MCP servers).
-
-Test with an MCP client or use the MCP inspector tool.
-
-## Related Documentation
-
-- [Overview](./overview.md) - Learn what Tkeron is
-- [Getting Started](./getting-started.md) - Start using Tkeron
-- [Best Practices](./best-practices.md) - Patterns and anti-patterns

package/examples/init_sample/websrc/api-service.ts

@@ -1,98 +0,0 @@
-// External API service - can be imported in .pre.ts files
-// Demonstrates that pre-rendering can use any TypeScript module
-
-export interface Quote {
-  id: number;
-  quote: string;
-  author: string;
-}
-
-/**
- * Fetches a random quote from a public API
- * This runs at build time during pre-rendering
- */
-export async function getRandomQuote(): Promise<Quote> {
-  try {
-    const response = await fetch('https://dummyjson.com/quotes/random');
-    
-    if (!response.ok) {
-      throw new Error(`HTTP error! status: ${response.status}`);
-    }
-    
-    const data = await response.json();
-    return data as Quote;
-  } catch (error) {
-    // Fallback quote if API fails
-    console.warn('API call failed, using fallback quote');
-    return {
-      id: 0,
-      quote: "The only way to do great work is to love what you do.",
-      author: "Steve Jobs"
-    };
-  }
-}
-
-/**
- * Gets build metadata
- */
-export async function getBuildMetadata() {
-  return {
-    timestamp: new Date().toLocaleString(),
-    runtime: `Bun ${Bun.version}`,
-    tkeron: process.env.TKERON_VERSION || 'unknown',
-    platform: process.platform
-  };
-}
-
-export interface CryptoPrice {
-  id: string;
-  symbol: string;
-  name: string;
-  current_price: number;
-  price_change_percentage_24h: number;
-}
-
-/**
- * Fetches cryptocurrency prices from CoinGecko API
- * This runs at build time during pre-rendering
- */
-export async function getCryptoPrices(): Promise<CryptoPrice[]> {
-  try {
-    const response = await fetch(
-      'https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&ids=bitcoin,ethereum,solana&order=market_cap_desc&sparkline=false'
-    );
-    
-    if (!response.ok) {
-      throw new Error(`HTTP error! status: ${response.status}`);
-    }
-    
-    const data = await response.json();
-    return data as CryptoPrice[];
-  } catch (error) {
-    // Fallback data if API fails
-    console.warn('Crypto API call failed, using fallback data');
-    return [
-      {
-        id: 'bitcoin',
-        symbol: 'btc',
-        name: 'Bitcoin',
-        current_price: 95000,
-        price_change_percentage_24h: 2.5
-      },
-      {
-        id: 'ethereum',
-        symbol: 'eth',
-        name: 'Ethereum',
-        current_price: 3500,
-        price_change_percentage_24h: -1.2
-      },
-      {
-        id: 'solana',
-        symbol: 'sol',
-        name: 'Solana',
-        current_price: 180,
-        price_change_percentage_24h: 5.8
-      }
-    ];
-  }
-}

package/examples/init_sample/websrc/counter-card.com.html

@@ -1,9 +0,0 @@
-<section>
-  <h2>🎯 Client-side TypeScript</h2>
-  <p style="margin-bottom: 0.75rem;">Interactive features in the browser:</p>
-  <div class="counter">
-    <button id="increment">Click me!</button>
-    <div class="count">Clicks: <span id="count">0</span></div>
-  </div>
-  <p style="font-size: 0.85rem; color: #666; margin-top: 0.75rem;">✓ Event handling & DOM manipulation<br>✓ Regular TypeScript for interactivity</p>
-</section>

package/examples/init_sample/websrc/hero-section.com.html

@@ -1,23 +0,0 @@
-<div class="hero">
-  <div>
-    <img src="./profile.png" alt="tkeron logo" class="logo">
-    <h1>tkeron</h1>
-    <p class="subtitle">Build-time TypeScript for modern web development</p>
-  </div>
-  <div class="features">
-    <ul style="list-style: none;">
-      <li>⚡ Fast builds with Bun</li>
-      <li>🎯 Build-time HTML generation</li>
-      <li>🧩 HTML & TypeScript components</li>
-      <li>🔧 Pure TypeScript & HTML</li>
-    </ul>
-  </div>
-  <div style="margin-top: 1.5rem; display: flex; gap: 0.75rem; width: 100%;">
-    <a href="https://www.npmjs.com/package/tkeron" target="_blank" style="flex: 1; padding: 0.65rem; background: rgba(203, 56, 55, 0.9); color: white; text-decoration: none; border-radius: 6px; text-align: center; font-weight: 600; font-size: 0.85rem; transition: background 0.2s;">
-      📦 npm
-    </a>
-    <a href="https://github.com/tkeron/tkeron" target="_blank" style="flex: 1; padding: 0.65rem; background: rgba(36, 41, 46, 0.9); color: white; text-decoration: none; border-radius: 6px; text-align: center; font-weight: 600; font-size: 0.85rem; transition: background 0.2s;">
-      ⭐ GitHub
-    </a>
-  </div>
-</div>

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

@@ -1,6 +0,0 @@
-<section>
-  <h2>🧩 HTML Components</h2>
-  <p style="margin-bottom: 0.75rem;">Reusable components with <code>.com.html</code>:</p>
-  <info-card></info-card>
-  <p style="font-size: 0.85rem; color: #666; margin-top: 0.75rem;">✓ Nested components support<br>✓ Build-time replacement</p>
-</section>

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

@@ -1,6 +0,0 @@
-<section>
-  <h2>⚡ TypeScript Components</h2>
-  <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>
-</section>

package/examples/init_sample/websrc/user-badge.com.ts

@@ -1,17 +0,0 @@
-// TypeScript component - runs at build time with logic
-const count = com.getAttribute("count") || "3";
-const numCount = parseInt(count, 10);
-
-// Generate list dynamically
-const items = [];
-for (let i = 1; i <= numCount; i++) {
-  items.push(`<li>✓ Item ${i}</li>`);
-}
-
-com.innerHTML = `
-  <div style="background: #f0fdf4; border-left: 3px solid #22c55e; padding: 0.75rem; border-radius: 4px;">
-    <ul style="list-style: none; padding: 0; margin: 0; font-size: 0.9rem; color: #166534;">
-      ${items.join("")}
-    </ul>
-  </div>
-`;