tkeron 5.3.0 → 6.0.0

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/mcp-server.ts

@@ -1,272 +0,0 @@
-#!/usr/bin/env bun
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { readFileSync, existsSync, readdirSync, statSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-
-const getBaseDir = () => {
-  if (import.meta.dir) {
-    return import.meta.dir;
-  }
-  const currentFile = import.meta.url
-    ? fileURLToPath(import.meta.url)
-    : __filename;
-  return dirname(currentFile);
-};
-
-const BASE_DIR = getBaseDir();
-const DOCS_DIR = join(BASE_DIR, "docs");
-const EXAMPLES_DIR = join(BASE_DIR, "examples");
-
-const getVersion = (): string => {
-  const pkgPath = join(BASE_DIR, "package.json");
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    return pkg.version || "0.0.0";
-  }
-  return "0.0.0";
-};
-
-const DOCS = [
-  {
-    uri: "tkeron://overview",
-    name: "Tkeron Overview",
-    description: "What tkeron is, what it does, and what it's not",
-    file: "overview.md",
-  },
-  {
-    uri: "tkeron://getting-started",
-    name: "Getting Started",
-    description: "Installation, first project, and basic workflow",
-    file: "getting-started.md",
-  },
-  {
-    uri: "tkeron://components-html",
-    name: "HTML Components",
-    description: "Create reusable HTML components with .com.html files",
-    file: "components-html.md",
-  },
-  {
-    uri: "tkeron://components-typescript",
-    name: "TypeScript Components",
-    description: "Build dynamic components with .com.ts files",
-    file: "components-typescript.md",
-  },
-  {
-    uri: "tkeron://components-markdown",
-    name: "Markdown Components",
-    description: "Create components with Markdown using .com.md files",
-    file: "components-markdown.md",
-  },
-  {
-    uri: "tkeron://pre-rendering",
-    name: "Pre-rendering",
-    description: "Transform HTML at build time with .pre.ts files",
-    file: "pre-rendering.md",
-  },
-  {
-    uri: "tkeron://cli-reference",
-    name: "CLI Reference",
-    description: "Complete command-line interface documentation",
-    file: "cli-reference.md",
-  },
-  {
-    uri: "tkeron://best-practices",
-    name: "Best Practices",
-    description: "Patterns, anti-patterns, and limitations",
-    file: "best-practices.md",
-  },
-  {
-    uri: "tkeron://common-issues",
-    name: "Common Issues and Solutions",
-    description:
-      "Troubleshooting guide: script references, component naming, dependencies, and common mistakes",
-    file: "common-issues.md",
-  },
-  {
-    uri: "tkeron://testing",
-    name: "Testing Tkeron Projects",
-    description:
-      "How to test tkeron projects using getBuildResult(), DOM assertions, and bounded content verification",
-    file: "testing.md",
-  },
-];
-
-const EXAMPLE_DESCRIPTIONS: { [key: string]: string } = {
-  init_sample:
-    "Complete starter template with all features (used by 'tk init')",
-  basic_build: "Simple HTML + TypeScript bundling",
-  with_assets: "HTML in multiple directories with asset references",
-  with_pre: "Pre-rendering HTML at build time with .pre.ts files",
-  with_com_html_priority:
-    "Static HTML components (.com.html) with local override priority",
-  with_com_ts: "TypeScript components (.com.ts) generating HTML at build time",
-  with_com_ts_priority:
-    "TypeScript components (.com.ts) with local override priority",
-  with_com_mixed_priority:
-    "Mixed .com.html and .com.ts showing processing order",
-  with_com_html_in_ts:
-    "HTML template (.com.html) injected into .com.ts as com.innerHTML before execution",
-  with_component_iteration:
-    "Component iteration: .com.ts with logic, .com.html for templates",
-};
-
-const readDirRecursive = (
-  dir: string,
-  baseDir: string = dir,
-): { [key: string]: string } => {
-  const files: { [key: string]: string } = {};
-  const items = readdirSync(dir);
-
-  for (const item of items) {
-    const fullPath = join(dir, item);
-    const relativePath = fullPath.substring(baseDir.length + 1);
-
-    if (statSync(fullPath).isDirectory()) {
-      Object.assign(files, readDirRecursive(fullPath, baseDir));
-    } else {
-      files[relativePath] = readFileSync(fullPath, "utf-8");
-    }
-  }
-
-  return files;
-};
-
-const server = new McpServer({
-  name: "tkeron-mcp",
-  version: getVersion(),
-});
-
-for (const doc of DOCS) {
-  server.registerResource(
-    doc.name,
-    doc.uri,
-    { description: doc.description, mimeType: "text/markdown" },
-    () => {
-      const filePath = join(DOCS_DIR, doc.file);
-
-      if (!existsSync(filePath)) {
-        throw new Error(`Documentation file not found: ${doc.file}`);
-      }
-
-      const content = readFileSync(filePath, "utf-8");
-
-      return {
-        contents: [
-          {
-            uri: doc.uri,
-            mimeType: "text/markdown",
-            text: content,
-          },
-        ],
-      };
-    },
-  );
-}
-
-server.registerTool(
-  "list_examples",
-  {
-    description:
-      "List all available Tkeron example projects with their descriptions",
-    annotations: { readOnlyHint: true },
-  },
-  () => {
-    const examples = readdirSync(EXAMPLES_DIR).filter((name) => {
-      const examplePath = join(EXAMPLES_DIR, name);
-      return (
-        statSync(examplePath).isDirectory() &&
-        existsSync(join(examplePath, "websrc"))
-      );
-    });
-
-    const exampleList = examples.map((name) => ({
-      name,
-      description: EXAMPLE_DESCRIPTIONS[name] || "No description available",
-      path: `examples/${name}`,
-    }));
-
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text: JSON.stringify(exampleList, null, 2),
-        },
-      ],
-    };
-  },
-);
-
-server.registerTool(
-  "get_example",
-  {
-    description:
-      "Get the source code and structure of a specific Tkeron example project",
-    inputSchema: {
-      example: {
-        type: "string",
-        description:
-          "Example name (e.g., 'basic_build', 'with_component_iteration')",
-      },
-    } as any,
-    annotations: { readOnlyHint: true },
-  },
-  ({ example: exampleName }: { example: string }) => {
-    const examplePath = join(EXAMPLES_DIR, exampleName);
-
-    if (!existsSync(examplePath)) {
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: `Example not found: ${exampleName}. Use the list_examples tool to see available examples.`,
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const srcPath = join(examplePath, "websrc");
-
-    if (!existsSync(srcPath)) {
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: `Example ${exampleName} does not have a websrc directory`,
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const sourceFiles = readDirRecursive(srcPath);
-
-    const result = {
-      example: exampleName,
-      path: `examples/${exampleName}`,
-      files: sourceFiles,
-    };
-
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text: JSON.stringify(result, null, 2),
-        },
-      ],
-    };
-  },
-);
-
-const main = async () => {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error(`[tkeron-mcp] Server v${getVersion()} started`);
-};
-
-main().catch((error) => {
-  console.error(`[tkeron-mcp] Fatal error:`, error);
-  process.exit(1);
-});

package/src/cleanupOrphanedTempDirs.ts

@@ -1,31 +0,0 @@
-import { readdir, rm } from "fs/promises";
-import { join } from "path";
-import type { Logger } from "@tkeron/tools";
-
-export const TEMP_DIR_PREFIX = ".tktmp_build-";
-
-export const cleanupOrphanedTempDirs = async (
-  parentDir: string,
-  log: Logger,
-): Promise<void> => {
-  try {
-    const entries = await readdir(parentDir, { withFileTypes: true });
-    const orphanedDirs = entries.filter(
-      (entry) => entry.isDirectory() && entry.name.startsWith(TEMP_DIR_PREFIX),
-    );
-
-    await Promise.all(
-      orphanedDirs.map(async (dir) => {
-        const dirPath = join(parentDir, dir.name);
-        try {
-          await rm(dirPath, { recursive: true, force: true });
-          log.log(`🧹 Cleaned up orphaned temp directory: ${dir.name}`);
-        } catch (error) {
-          log.warn(
-            `Warning: Failed to cleanup orphaned temp directory ${dirPath}`,
-          );
-        }
-      }),
-    );
-  } catch (error) {}
-};

package/src/promptUser.ts

@@ -1,15 +0,0 @@
-export const promptUser = async (question: string): Promise<boolean> => {
-  const readline = await import("readline");
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      const response = answer.trim().toLowerCase();
-      resolve(response === "y" || response === "yes");
-    });
-  });
-};

package/src/setupSigintHandler.ts

@@ -1,6 +0,0 @@
-export const setupSigintHandler = (stopCallback: () => Promise<void>) => {
-  process.on("SIGINT", async () => {
-    await stopCallback();
-    process.exit(0);
-  });
-};