tkeron 4.0.0-beta.16 → 4.0.0-beta.18

package/changelog.md

@@ -1,3 +1,73 @@
+# v4.0.0-beta.18
+
+## Code Quality & Architecture
+
+### Bug Fixes
+
+- **Fixed**: Removed `process.exit()` from library code (`build.ts`, `develop.ts`, `init.ts`) — errors now propagate via `throw`, letting wrappers handle exit
+- **Fixed**: Moved `reloadClients` Set inside `develop()` to prevent shared state across multiple server instances
+- **Fixed**: Removed `await` on synchronous `path.resolve()` calls in `build.ts` and `develop.ts`
+- **Fixed**: `log.error()` called without arguments in `processPre.ts` — now passes empty string
+
+### Code Style
+
+- **Changed**: Converted all `function` declarations to arrow functions (`initWrapper`, `processComponents`, `processComponentsTs`)
+- **Removed**: Comments in source code (`processCom.ts`, `processComTs.ts`)
+- **Removed**: Dead re-export of `setupSigintHandler` from `develop.ts`
+
+### Tests
+
+- **Fixed**: TS2532 errors in `getBuildResult.test.ts` (proper handling of possibly undefined values)
+- **Updated**: Tests adapted to new error propagation (no more `process.exit` mocking in library tests)
+- **Removed**: Redundant/dead test cases for removed behavior
+
+---
+
+# v4.0.0-beta.17
+
+## MCP Server Updates
+
+### API Migration
+
+- **Changed**: Migrated MCP server to new SDK API (`McpServer`, `registerResource`, `registerTool`)
+- **Removed**: Legacy API (`Server`, `setRequestHandler`)
+- **Benefit**: Better compatibility with MCP SDK 1.26.0, cleaner code structure
+
+### Tools Simplification
+
+- **Removed**: `tkeron_init`, `tkeron_build`, `tkeron_develop` tools
+- **Rationale**: MCP server now focuses on documentation and examples only
+- **Alternative**: AI agents should use terminal commands (`tk init`, `tk build`, `tk dev`) instead
+- **Kept**: `list_examples` and `get_example` tools (read-only)
+- **Annotations**: Added `readOnlyHint: true` to remaining tools
+
+### New Testing Documentation
+
+- **New**: `tkeron://testing` resource with comprehensive testing guide
+- **Location**: `docs/testing.md`
+- **Coverage**:
+  - How to use `getBuildResult()` for testing tkeron projects
+  - Proper test structure with `beforeAll()` for concurrent safety
+  - Testing patterns: file existence, DOM elements, bounded content, transformations
+  - Complete examples with best practices
+  - Rules summary (8 key rules)
+- **Purpose**: Help users write reliable tests for their tkeron projects
+
+### Documentation Updates
+
+- **Updated**: `docs/mcp-server.md` to reflect new tools approach
+- **Clarified**: AI agents can access examples but must use terminal for project operations
+- **Updated**: MCP server tests to include new `testing` resource
+
+### Tests
+
+- **New**: `examples/basic_build/basic_build.test.ts` - complete test suite demonstrating testing patterns
+- **Purpose**: Reference implementation for testing tkeron projects
+
+## Dependency Updates
+
+- **Updated**: `@modelcontextprotocol/sdk` from `^1.25.3` to `^1.26.0`
+
 # v4.0.0-beta.16
 
 ## Improvements

package/docs/mcp-server.md

@@ -99,6 +99,7 @@ The MCP server exposes the following documentation resources:
 | `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://testing`               | How to test tkeron projects with getBuildResult()    |
 
 ## What AI Agents Can Do
 
@@ -111,25 +112,19 @@ With access to the MCP server, AI agents can:
 - ✅ Provide accurate CLI commands and options
 - ✅ Debug common issues with components and pre-rendering
 - ✅ Recommend best practices and avoid anti-patterns
-- ✅ **Initialize new Tkeron projects directly**
-- ✅ **Build and develop Tkeron projects**
 - ✅ **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:
 
-### Documentation Tool
-
-- **`get_tkeron_docs`**: Retrieve specific documentation topics
-  - Parameters: `topic` (overview, getting-started, components-html, etc.)
-  - Returns the full markdown content of the requested documentation
-
 ### Example Management Tools
 
 - **`list_examples`**: List all available Tkeron example projects
-  - Shows example names, descriptions, and features
+  - 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
@@ -137,22 +132,7 @@ The MCP server provides the following tools for AI agents:
   - Returns file structure and all source code
   - Useful for learning patterns and bootstrapping projects
 
-### Project Management Tools
-
-- **`tkeron_init`**: Initialize a new Tkeron project
-  - Parameters: `projectPath` (absolute path), `force` (optional boolean)
-  - Creates the standard Tkeron structure (websrc/ with sample files)
-  - AI agents can create projects without user intervention
-
-- **`tkeron_build`**: Build a Tkeron project
-  - Parameters: `sourceDir`, `targetDir` (optional)
-  - Processes all `.pre.ts`, `.com.html`, and `.com.ts` files
-  - Generates production-ready output
-
-- **`tkeron_develop`**: Start the development server
-  - Parameters: `sourceDir`, `outputDir`, `port`, `host` (all optional)
-  - Launches hot-reload development server
-  - AI agents can test projects immediately after creation
+> **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
 

package/docs/testing.md

@@ -0,0 +1,331 @@
+# Testing Tkeron Projects
+
+## Overview
+
+Tkeron provides a `getBuildResult()` function that lets you test your built projects programmatically. This is useful for verifying that your components, pre-rendering scripts, and build output work correctly.
+
+**Important:** These tests validate YOUR project's build output — not tkeron internals. You're testing that your HTML, components, and scripts produce the expected result after the build.
+
+## Setup
+
+Install tkeron as a dependency in your project:
+
+```bash
+bun add -d tkeron
+```
+
+## API
+
+```typescript
+import { getBuildResult, type BuildResult } from "tkeron";
+
+const result: BuildResult = await getBuildResult("./websrc");
+```
+
+### BuildResult
+
+`getBuildResult()` returns a `Record<string, FileInfo>` indexed by relative path:
+
+```typescript
+type BuildResult = Record<string, FileInfo>;
+
+interface FileInfo {
+  fileName: string; // "index.html"
+  filePath: string; // "styles" or "" for root files
+  path: string; // "styles/main.css" (the key)
+  type: string; // MIME type: "text/html", "text/css", etc.
+  size: number; // size in bytes
+  fileHash: string; // SHA-256 hash
+  getContentAsString?: () => string; // text files only
+  dom?: Document; // HTML files only - parsed DOM
+}
+```
+
+- `dom` is only present on `.html` files. It provides full DOM API: `querySelector()`, `getElementById()`, `querySelectorAll()`, etc.
+- `getContentAsString()` is only present on text files (html, css, js, json, txt, svg, xml, ts, mjs, cjs, md, map).
+- Binary files (images, fonts) only have metadata — no `dom` or `getContentAsString`.
+
+## Test Structure
+
+### Single Build with beforeAll
+
+**Always** build once and share the result across tests. This is:
+
+- Concurrent-safe (`bun test --concurrent`)
+- Efficient (1 build instead of N builds)
+- Reliable (no race conditions)
+
+```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, "src");
+  let result: BuildResult;
+
+  beforeAll(async () => {
+    result = await getBuildResult(sourcePath);
+  });
+
+  it("should generate index.html", () => {
+    expect(result?.["index.html"]).toBeDefined();
+  });
+});
+```
+
+**Never** call `getBuildResult()` inside each `it()` — this causes race conditions in concurrent mode.
+
+## Testing Patterns
+
+### 1. Verify File Existence
+
+Check that expected output files exist:
+
+```typescript
+it("should generate expected files", () => {
+  expect(result?.["index.html"]).toBeDefined();
+  expect(result?.["index.js"]).toBeDefined();
+  expect(result?.["styles/main.css"]).toBeDefined();
+});
+```
+
+### 2. Verify Element Existence (Always Check First)
+
+**Rule:** Always verify an element exists BEFORE checking its properties.
+
+```typescript
+// ✅ CORRECT: check existence first, then properties
+it("should have login button", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const button = dom?.querySelector("#login-button");
+  expect(button).toBeDefined();
+  expect(button!.textContent).toBe("Log In");
+});
+
+// ❌ WRONG: accessing properties without checking existence
+it("should have login button", () => {
+  const dom = result?.["index.html"]?.dom;
+  expect(dom!.querySelector("#login-button")!.textContent).toBe("Log In");
+});
+```
+
+### 3. Verify Bounded Content
+
+Test specific, short, predictable values — not full output strings.
+
+```typescript
+// ✅ GOOD: specific, bounded values
+it("should have correct title", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const title = dom?.querySelector("title");
+  expect(title).toBeDefined();
+  expect(title!.textContent).toBe("My App");
+});
+
+// ✅ GOOD: keyword presence in compiled JS
+it("should contain event handling logic", () => {
+  const js = result?.["index.js"]?.getContentAsString!();
+  expect(js).toContain("addEventListener");
+});
+
+// ❌ BAD: comparing full minified JS output (fragile, breaks on any optimization change)
+it("should match exact JS", () => {
+  const js = result?.["index.js"]?.getContentAsString!();
+  expect(js).toBe('var t=0,e=document.querySelector("button")...');
+});
+
+// ❌ BAD: comparing full HTML output
+it("should match exact HTML", () => {
+  const html = result?.["index.html"]?.getContentAsString!();
+  expect(html).toBe("<!doctype html><html>...");
+});
+```
+
+**Why bounded:** Build output changes with optimizations, minification, and bundling. Test the **meaning**, not the **exact format**.
+
+### 4. Verify DOM Elements (Specific Queries)
+
+Test specific elements that matter to your project:
+
+```typescript
+it("should have navigation with correct links", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const homeLink = dom?.querySelector('nav a[href="/"]');
+  expect(homeLink).toBeDefined();
+  expect(homeLink!.textContent).toBe("Home");
+
+  const aboutLink = dom?.querySelector('nav a[href="/about"]');
+  expect(aboutLink).toBeDefined();
+});
+
+it("should have user profile section", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const profile = dom?.querySelector("#user-profile");
+  expect(profile).toBeDefined();
+
+  const avatar = profile?.querySelector("img.avatar");
+  expect(avatar).toBeDefined();
+  expect(avatar!.getAttribute("alt")).toBe("User avatar");
+});
+```
+
+### 5. Verify Tkeron Transformations
+
+Test that tkeron's build features work correctly in your project:
+
+**Script injection (TypeScript → JavaScript):**
+
+```typescript
+it("should have compiled script in head", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const script = dom?.querySelector('script[type="module"]');
+  expect(script).toBeDefined();
+  expect(script!.getAttribute("src")).toBe("./index.js");
+  expect(script!.parentElement!.tagName).toBe("HEAD");
+});
+```
+
+**Component substitution (.com.html):**
+
+```typescript
+it("should have processed nav component", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  // The <nav-menu> tag should be replaced by its .com.html content
+  const nav = dom?.querySelector("nav");
+  expect(nav).toBeDefined();
+
+  const links = dom?.querySelectorAll("nav a");
+  expect(links).toBeDefined();
+  expect(links!.length).toBeGreaterThan(0);
+});
+```
+
+**TypeScript component (.com.ts):**
+
+```typescript
+it("should have dynamically generated list", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const list = dom?.querySelector("#item-list");
+  expect(list).toBeDefined();
+
+  const items = list?.querySelectorAll("li");
+  expect(items).toBeDefined();
+  expect(items!.length).toBe(5);
+});
+```
+
+**Pre-rendering (.pre.ts):**
+
+```typescript
+it("should have pre-rendered content", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const generated = dom?.querySelector("#generated-content");
+  expect(generated).toBeDefined();
+  expect(generated!.textContent).not.toBe("");
+});
+```
+
+### 6. Verify File Metadata
+
+```typescript
+it("should have correct metadata", () => {
+  expect(result?.["index.html"]?.type).toBe("text/html");
+  expect(result?.["index.html"]?.size).toBeGreaterThan(0);
+  expect(result?.["index.html"]?.fileHash).toBeDefined();
+});
+
+it("should not have DOM on non-HTML files", () => {
+  expect(result?.["index.js"]?.dom).toBeUndefined();
+});
+
+it("should have correct path info for nested files", () => {
+  expect(result?.["pages/about.html"]?.fileName).toBe("about.html");
+  expect(result?.["pages/about.html"]?.filePath).toBe("pages");
+});
+```
+
+## Complete Example
+
+Here's a complete test file for a tkeron project with components:
+
+```typescript
+import { describe, it, expect, beforeAll } from "bun:test";
+import { getBuildResult, type BuildResult } from "tkeron";
+import { join } from "path";
+
+describe("my-website build", () => {
+  const sourcePath = join(import.meta.dir, "websrc");
+  let result: BuildResult;
+
+  beforeAll(async () => {
+    result = await getBuildResult(sourcePath);
+  });
+
+  it("should generate expected files", () => {
+    expect(result?.["index.html"]).toBeDefined();
+    expect(result?.["index.js"]).toBeDefined();
+    expect(result?.["about.html"]).toBeDefined();
+  });
+
+  it("should have page title", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const title = dom?.querySelector("title");
+    expect(title).toBeDefined();
+    expect(title!.textContent).toBe("My Website");
+  });
+
+  it("should have navigation from component", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const nav = dom?.querySelector("nav");
+    expect(nav).toBeDefined();
+
+    const homeLink = dom?.querySelector('nav a[href="/"]');
+    expect(homeLink).toBeDefined();
+    expect(homeLink!.textContent).toBe("Home");
+  });
+
+  it("should have footer from component", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const footer = dom?.querySelector("footer");
+    expect(footer).toBeDefined();
+  });
+
+  it("should have compiled JavaScript", () => {
+    const js = result?.["index.js"]?.getContentAsString!();
+
+    expect(js).toBeDefined();
+    expect(js!.length).toBeGreaterThan(0);
+  });
+
+  it("should have script injected in head", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const script = dom?.querySelector('head script[type="module"]');
+    expect(script).toBeDefined();
+    expect(script!.getAttribute("src")).toBe("./index.js");
+  });
+});
+```
+
+## Rules Summary
+
+1. **Build once** with `beforeAll()` — never inside individual tests
+2. **Check existence first** — always `expect(element).toBeDefined()` before accessing properties
+3. **Use optional chaining** (`?.`) for safe property access on result entries
+4. **Test bounded content** — specific values, keywords, attributes; not full output strings
+5. **Test specific elements** — query for elements that matter to your project
+6. **Verify transformations** — components processed, scripts injected, pre-rendering applied
+7. **Don't test the parser** — you're testing your project, not tkeron internals
+8. **Concurrent-safe** — tests must work with `bun test --concurrent`

package/mcp-server.ts

@@ -1,57 +1,33 @@
 #!/usr/bin/env bun
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync, existsSync, readdirSync, statSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { init } from "./src/init";
-import { build } from "./src/build";
-import { develop } from "./src/develop";
 
-// Resolve the docs directory - handle both direct execution and symlink execution
-const getDocsDir = () => {
-  // Try import.meta.dir first (Bun specific)
+const getBaseDir = () => {
   if (import.meta.dir) {
-    const docsPath = join(import.meta.dir, "docs");
-    if (existsSync(docsPath)) {
-      return docsPath;
-    }
+    return import.meta.dir;
   }
-
-  // Fallback: resolve from the actual file location
   const currentFile = import.meta.url
     ? fileURLToPath(import.meta.url)
     : __filename;
-  const currentDir = dirname(currentFile);
-  return join(currentDir, "docs");
+  return dirname(currentFile);
 };
 
-const DOCS_DIR = getDocsDir();
+const BASE_DIR = getBaseDir();
+const DOCS_DIR = join(BASE_DIR, "docs");
+const EXAMPLES_DIR = join(BASE_DIR, "examples");
 
-// Get examples directory
-const getExamplesDir = () => {
-  if (import.meta.dir) {
-    const examplesPath = join(import.meta.dir, "examples");
-    if (existsSync(examplesPath)) {
-      return examplesPath;
-    }
+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";
   }
-
-  const currentFile = import.meta.url
-    ? fileURLToPath(import.meta.url)
-    : __filename;
-  const currentDir = dirname(currentFile);
-  return join(currentDir, "examples");
+  return "0.0.0";
 };
 
-const EXAMPLES_DIR = getExamplesDir();
-
 const DOCS = [
   {
     uri: "tkeron://overview",
@@ -95,466 +71,191 @@ const DOCS = [
     description: "Patterns, anti-patterns, and limitations",
     file: "best-practices.md",
   },
-];
-
-const server = new Server(
   {
-    name: "tkeron-mcp",
-    version: "1.0.0",
+    uri: "tkeron://testing",
+    name: "Testing Tkeron Projects",
+    description:
+      "How to test tkeron projects using getBuildResult(), DOM assertions, and bounded content verification",
+    file: "testing.md",
   },
-  {
-    capabilities: {
-      resources: {},
-      tools: {},
-    },
-  },
-);
-
-server.setRequestHandler(ListResourcesRequestSchema, async () => {
-  return {
-    resources: DOCS.map((doc) => ({
-      uri: doc.uri,
-      name: doc.name,
-      description: doc.description,
-      mimeType: "text/markdown",
-    })),
-  };
-});
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  try {
-    const uri = request.params.uri;
-    const doc = DOCS.find((d) => d.uri === uri);
-
-    if (!doc) {
-      throw new Error(`Unknown resource: ${uri}`);
-    }
+];
 
-    const filePath = join(DOCS_DIR, doc.file);
+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_component_iteration:
+    "Component iteration: .com.ts with logic, .com.html for templates",
+};
 
-    // Check if file exists before reading
-    if (!existsSync(filePath)) {
-      throw new Error(`Documentation file not found: ${doc.file}`);
+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");
     }
+  }
 
-    const content = readFileSync(filePath, "utf-8");
+  return files;
+};
 
-    return {
-      contents: [
-        {
-          uri: doc.uri,
-          mimeType: "text/markdown",
-          text: content,
-        },
-      ],
-    };
-  } catch (error) {
-    throw error;
-  }
+const server = new McpServer({
+  name: "tkeron-mcp",
+  version: getVersion(),
 });
 
-// Tools handler - provide a simple tool to keep VS Code happy
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: "get_tkeron_docs",
-        description:
-          "Get Tkeron documentation. Available topics: overview, getting-started, components-html, components-typescript, pre-rendering, cli-reference, best-practices",
-        inputSchema: {
-          type: "object",
-          properties: {
-            topic: {
-              type: "string",
-              description: "Documentation topic to retrieve",
-              enum: [
-                "overview",
-                "getting-started",
-                "components-html",
-                "components-typescript",
-                "pre-rendering",
-                "cli-reference",
-                "best-practices",
-              ],
-            },
-          },
-          required: ["topic"],
-        },
-      },
-      {
-        name: "list_examples",
-        description:
-          "List all available Tkeron example projects with their descriptions",
-        inputSchema: {
-          type: "object",
-          properties: {},
-          required: [],
-        },
-      },
-      {
-        name: "get_example",
-        description:
-          "Get the source code and structure of a specific Tkeron example project",
-        inputSchema: {
-          type: "object",
-          properties: {
-            example: {
-              type: "string",
-              description:
-                "Example name (e.g., 'basic_build', 'with_component_iteration')",
-            },
-          },
-          required: ["example"],
-        },
-      },
-      {
-        name: "tkeron_init",
-        description:
-          "Initialize a new Tkeron project with the standard structure (websrc/ directory with sample files)",
-        inputSchema: {
-          type: "object",
-          properties: {
-            projectPath: {
-              type: "string",
-              description: "Absolute path where the project will be created",
-            },
-            force: {
-              type: "boolean",
-              description: "Overwrite existing files if they exist",
-              default: false,
-            },
-          },
-          required: ["projectPath"],
-        },
-      },
-      {
-        name: "tkeron_build",
-        description:
-          "Build a Tkeron project (processes .pre.ts, .com.html, and .com.ts files)",
-        inputSchema: {
-          type: "object",
-          properties: {
-            sourceDir: {
-              type: "string",
-              description:
-                "Absolute path to source directory (default: websrc/)",
-            },
-            targetDir: {
-              type: "string",
-              description: "Absolute path to output directory (default: web/)",
-            },
-          },
-          required: [],
-        },
-      },
-      {
-        name: "tkeron_develop",
-        description: "Start Tkeron development server with hot reload",
-        inputSchema: {
-          type: "object",
-          properties: {
-            sourceDir: {
-              type: "string",
-              description:
-                "Absolute path to source directory (default: websrc/)",
-            },
-            outputDir: {
-              type: "string",
-              description: "Absolute path to output directory (default: web/)",
-            },
-            port: {
-              type: "number",
-              description: "Port number for dev server (default: 3000)",
-              default: 3000,
-            },
-            host: {
-              type: "string",
-              description: "Host for dev server (default: localhost)",
-              default: "localhost",
-            },
-          },
-          required: [],
-        },
-      },
-    ],
-  };
-});
+for (const doc of DOCS) {
+  server.registerResource(
+    doc.name,
+    doc.uri,
+    { description: doc.description, mimeType: "text/markdown" },
+    () => {
+      const filePath = join(DOCS_DIR, doc.file);
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
+      if (!existsSync(filePath)) {
+        throw new Error(`Documentation file not found: ${doc.file}`);
+      }
 
-  if (name === "get_tkeron_docs") {
-    const topic = (args as any).topic;
-    const doc = DOCS.find((d) => d.uri === `tkeron://${topic}`);
+      const content = readFileSync(filePath, "utf-8");
 
-    if (!doc) {
       return {
-        content: [
+        contents: [
           {
-            type: "text",
-            text: `Unknown topic: ${topic}`,
+            uri: doc.uri,
+            mimeType: "text/markdown",
+            text: content,
           },
         ],
       };
-    }
+    },
+  );
+}
 
-    const filePath = join(DOCS_DIR, doc.file);
-    const content = readFileSync(filePath, "utf-8");
+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, "src")) ||
+          existsSync(join(examplePath, "websrc")))
+      );
+    });
+
+    const exampleList = examples.map((name) => ({
+      name,
+      description: EXAMPLE_DESCRIPTIONS[name] || "No description available",
+      path: `examples/${name}`,
+    }));
 
     return {
       content: [
         {
-          type: "text",
-          text: content,
+          type: "text" as const,
+          text: JSON.stringify(exampleList, null, 2),
         },
       ],
     };
-  }
-
-  if (name === "list_examples") {
-    try {
-      const examples = readdirSync(EXAMPLES_DIR).filter((name) => {
-        const examplePath = join(EXAMPLES_DIR, name);
-        // Accept both src/ and websrc/ directories (init_sample uses websrc/)
-        return (
-          statSync(examplePath).isDirectory() &&
-          (existsSync(join(examplePath, "src")) ||
-            existsSync(join(examplePath, "websrc")))
-        );
-      });
-
-      const exampleDescriptions: { [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_priority:
-          "TypeScript components (.com.ts) with local override priority",
-        with_com_mixed_priority:
-          "Mixed .com.html and .com.ts showing processing order",
-        with_component_iteration:
-          "Component iteration: .com.ts with logic, .com.html for templates",
-      };
-
-      const exampleList = examples.map((name) => ({
-        name,
-        description: exampleDescriptions[name] || "No description available",
-        path: `examples/${name}`,
-      }));
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(exampleList, null, 2),
-          },
-        ],
-      };
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Error listing examples: ${error instanceof Error ? error.message : String(error)}`,
-          },
-        ],
-      };
-    }
-  }
+  },
+);
 
-  if (name === "get_example") {
-    const exampleName = (args as any).example;
+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",
-            text: `Example not found: ${exampleName}`,
+            type: "text" as const,
+            text: `Example not found: ${exampleName}. Use the list_examples tool to see available examples.`,
           },
         ],
+        isError: true,
       };
     }
 
-    try {
-      // init_sample uses websrc/, others use src/
-      let srcPath = join(examplePath, "src");
-      if (!existsSync(srcPath)) {
-        srcPath = join(examplePath, "websrc");
-      }
-
-      if (!existsSync(srcPath)) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Example ${exampleName} does not have a src or websrc directory`,
-            },
-          ],
-        };
-      }
-
-      // Read all files in src directory recursively
-      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 sourceFiles = readDirRecursive(srcPath);
-
-      const result = {
-        example: exampleName,
-        path: `examples/${exampleName}`,
-        files: sourceFiles,
-      };
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2),
-          },
-        ],
-      };
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Error reading example: ${error instanceof Error ? error.message : String(error)}`,
-          },
-        ],
-      };
+    let srcPath = join(examplePath, "src");
+    if (!existsSync(srcPath)) {
+      srcPath = join(examplePath, "websrc");
     }
-  }
-
-  if (name === "tkeron_init") {
-    const projectPath = (args as any).projectPath;
-    const force = (args as any).force || false;
-
-    try {
-      await init({
-        projectName: projectPath,
-        force,
-        promptFn: async () => force, // Auto-confirm if force is true
-      });
 
+    if (!existsSync(srcPath)) {
       return {
         content: [
           {
-            type: "text",
-            text: `✅ Tkeron project initialized at ${projectPath}`,
-          },
-        ],
-      };
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Error initializing project: ${error instanceof Error ? error.message : String(error)}`,
+            type: "text" as const,
+            text: `Example ${exampleName} does not have a src or websrc directory`,
           },
         ],
+        isError: true,
       };
     }
-  }
-
-  if (name === "tkeron_build") {
-    const sourceDir = (args as any).sourceDir;
-    const targetDir = (args as any).targetDir;
 
-    try {
-      await build({ sourceDir, targetDir });
+    const sourceFiles = readDirRecursive(srcPath);
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: `✅ Build complete! Output: ${targetDir || "web/"}`,
-          },
-        ],
-      };
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Error building project: ${error instanceof Error ? error.message : String(error)}`,
-          },
-        ],
-      };
-    }
-  }
-
-  if (name === "tkeron_develop") {
-    const sourceDir = (args as any).sourceDir;
-    const outputDir = (args as any).outputDir;
-    const port = (args as any).port || 3000;
-    const host = (args as any).host || "localhost";
-
-    try {
-      const server = await develop({ sourceDir, outputDir, port, host });
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `✅ Development server started at http://${server.host}:${server.port}\n\n⚠️ Note: Server is running in the background. Use the returned server object to stop it later.`,
-          },
-        ],
-      };
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Error starting development server: ${error instanceof Error ? error.message : String(error)}`,
-          },
-        ],
-      };
-    }
-  }
-
-  throw new Error(`Unknown tool: ${name}`);
-});
-
-async function main() {
-  try {
-    console.error(`[tkeron-mcp] Starting server...`);
-    console.error(`[tkeron-mcp] Docs directory: ${DOCS_DIR}`);
-    console.error(`[tkeron-mcp] Available resources: ${DOCS.length}`);
+    const result = {
+      example: exampleName,
+      path: `examples/${exampleName}`,
+      files: sourceFiles,
+    };
 
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  },
+);
 
-    console.error(`[tkeron-mcp] Server started successfully`);
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    console.error(`[tkeron-mcp] Fatal error:`, errorMessage);
-    process.exit(1);
-  }
-}
+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] Unhandled error:`, error);
+  console.error(`[tkeron-mcp] Fatal error:`, error);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tkeron",
-  "version": "4.0.0-beta.16",
+  "version": "4.0.0-beta.18",
   "description": "CLI tool for backend-driven frontend development with TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/build.ts

@@ -24,10 +24,10 @@ export const build = async (options: BuildOptions) => {
     return;
   }
 
-  const source = await resolve(options.sourceDir || "websrc");
+  const source = resolve(options.sourceDir || "websrc");
   const target = options.targetDir
-    ? await resolve(options.targetDir)
-    : await resolve(dirname(source), "web");
+    ? resolve(options.targetDir)
+    : resolve(dirname(source), "web");
 
   const sourceParent = dirname(source);
   const tempDir = join(
@@ -67,14 +67,6 @@ export const build = async (options: BuildOptions) => {
         `\n💡 Tip: Create the directory first, check the path, or run 'tk init' to create a new project.`,
       );
       log.error(`   Expected: ${source}\n`);
-      process.exit(1);
-    }
-
-    if (
-      error.message &&
-      error.message.includes("must contain at least one hyphen")
-    ) {
-      process.exit(1);
     }
 
     throw error;

package/src/develop.ts

@@ -13,8 +13,6 @@ export interface TkeronDevOptions {
   logger?: Logger;
 }
 
-const reloadClients = new Set<ReadableStreamDefaultController>();
-
 export interface DevelopServer {
   stop: () => Promise<void>;
   port: number;
@@ -28,6 +26,8 @@ export const develop = async (
     throw new Error("Invalid options provided for develop");
   }
 
+  const reloadClients = new Set<ReadableStreamDefaultController>();
+
   const {
     port = 3000,
     host = "localhost",
@@ -36,28 +36,13 @@ export const develop = async (
     logger: log = defaultLogger,
   } = options;
 
-  const source = await resolve(sourceDir || "websrc");
+  const source = resolve(sourceDir || "websrc");
   const target = outputDir
-    ? await resolve(outputDir)
-    : await resolve(dirname(source), "web");
+    ? resolve(outputDir)
+    : resolve(dirname(source), "web");
 
   log.log("🔨 Building project...");
-  try {
-    await build({ sourceDir: source, targetDir: target, logger: log });
-  } catch (error: any) {
-    if (error.code === "ENOENT") {
-      const actualSourceDir = sourceDir || "websrc";
-      log.error(
-        `\n❌ Error: Source directory "${actualSourceDir}" does not exist.`,
-      );
-      log.error(
-        `\n💡 Tip: Create the directory first, check the path, or run 'tk init' to create a new project.`,
-      );
-      log.error(`   Expected: ${source}\n`);
-      process.exit(1);
-    }
-    throw error;
-  }
+  await build({ sourceDir: source, targetDir: target, logger: log });
   log.log("✅ Build complete!");
 
   const server = Bun.serve({
@@ -182,5 +167,3 @@ export const develop = async (
     host: server.hostname ?? host,
   };
 };
-
-export { setupSigintHandler } from "./setupSigintHandler";

package/src/init.ts

@@ -57,7 +57,7 @@ export const init = async (options: InitOptions) => {
 
           if (!shouldContinue) {
             log.log("\n❌ Operation cancelled.");
-            process.exit(0);
+            return;
           }
         }
 

package/src/initWrapper.ts

@@ -9,7 +9,7 @@ export interface InitWrapperOptions {
   [key: string]: any;
 }
 
-export async function initWrapper(options: InitWrapperOptions) {
+export const initWrapper = async (options: InitWrapperOptions) => {
   const log = options?.logger || defaultLogger;
 
   if (!options || typeof options !== "object") {
@@ -60,4 +60,4 @@ export async function initWrapper(options: InitWrapperOptions) {
     }
     process.exit(1);
   }
-}
+};

package/src/processCom.ts

@@ -60,14 +60,14 @@ export const processCom = async (
   return hasChanges;
 };
 
-async function processComponents(
+const processComponents = async (
   element: any,
   currentDir: string,
   rootDir: string,
   componentStack: string[],
   depth: number = 0,
   log: Logger = silentLogger,
-): Promise<boolean> {
+): Promise<boolean> => {
   let hasChanges = false;
   const MAX_DEPTH = 50;
   if (depth > MAX_DEPTH) {
@@ -183,7 +183,6 @@ async function processComponents(
       }
     }
 
-    // Recursively process child elements
     const childChanged = await processComponents(
       child,
       currentDir,
@@ -196,4 +195,4 @@ async function processComponents(
   }
 
   return hasChanges;
-}
+};

package/src/processComTs.ts

@@ -61,7 +61,7 @@ export const processComTs = async (
   return hasChanges;
 };
 
-async function processComponentsTs(
+const processComponentsTs = async (
   element: any,
   currentDir: string,
   rootDir: string,
@@ -69,7 +69,7 @@ async function processComponentsTs(
   depth: number = 0,
   log: Logger = silentLogger,
   options: ProcessComTsOptions = {},
-): Promise<boolean> {
+): Promise<boolean> => {
   let hasChanges = false;
   const MAX_DEPTH = 50;
   if (depth > MAX_DEPTH) {
@@ -251,7 +251,6 @@ ${codeWithoutImports}
       }
     }
 
-    // Recursively process child elements
     const childChanged = await processComponentsTs(
       child,
       currentDir,
@@ -265,4 +264,4 @@ ${codeWithoutImports}
   }
 
   return hasChanges;
-}
+};

package/src/processPre.ts

@@ -89,7 +89,7 @@ export const processPre = async (
       if (stdout) {
         log.error(`\nOutput:\n${stdout}`);
       }
-      log.error();
+      log.error("");
       throw new Error(`Pre-rendering failed for ${preFile}`);
     }
   }

package/tests/test-helpers.ts

@@ -11,7 +11,7 @@ const hashString = (str: string): number => {
   for (let i = 0; i < str.length; i++) {
     const char = str.charCodeAt(i);
     hash = (hash << 5) - hash + char;
-    hash = hash & hash; // Convert to 32bit integer
+    hash = hash & hash;
   }
   return Math.abs(hash);
 };
@@ -22,7 +22,7 @@ export const getTestResources = (
   testName: string,
 ): { port: number; dir: string } => {
   const hash = hashString(testName);
-  const port = 9000 + (hash % 10000); // Port range: 9000-18999
+  const port = 9000 + (hash % 10000);
   const uniqueId = `${hash}-${resourceCounter++}`;
   const dir = join(tmpdir(), `tkeron-test-${uniqueId}`);