tkeron 4.0.1 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/changelog.md CHANGED
@@ -1,3 +1,65 @@
1
+ # v4.2.0
2
+
3
+ ## Developer Experience
4
+
5
+ ### New Features
6
+
7
+ - **Added**: TypeScript configuration to `init_sample` example
8
+ - `tsconfig.json` - Minimal TypeScript configuration for IDE support
9
+ - `tkeron.d.ts` - Type definitions for `.com.ts` and `.pre.ts` files
10
+ - Enables IntelliSense for `com` variable in `.com.ts` files
11
+ - Enables IntelliSense for `document` variable in `.pre.ts` files
12
+ - Improves developer experience in VS Code and other IDEs
13
+
14
+ ### Bug Fixes
15
+
16
+ - **Fixed**: Variable naming conflict in `init_sample/websrc/index.ts`
17
+ - Renamed `count` to `clickCount` to avoid TypeScript scope collision
18
+ - **Fixed**: TypeScript type error in `init_sample/websrc/user-badge.com.ts`
19
+ - Added explicit `parseInt` radix parameter for type safety
20
+
21
+ ### Tests
22
+
23
+ - **Updated**: Test expectations to match renamed variables in `init_sample`
24
+
25
+ ---
26
+
27
+ # v4.1.0
28
+
29
+ ## Documentation & Developer Experience
30
+
31
+ ### New Features
32
+
33
+ - **Added**: `docs/common-issues.md` - Comprehensive troubleshooting guide
34
+ - Script tag references (most common issue)
35
+ - Component naming requirements (hyphen mandatory)
36
+ - File references and relative paths
37
+ - TypeScript compilation errors
38
+ - Component resolution rules
39
+ - Build performance tips
40
+ - Common AI agent mistakes prevention
41
+ - **Added**: MCP server resource `tkeron://common-issues` for AI agents
42
+ - Exposes troubleshooting documentation via MCP
43
+ - Helps AI agents prevent common mistakes
44
+ - Improves guided project creation
45
+
46
+ ### Bug Fixes
47
+
48
+ - **Improved**: Build error reporting in `buildEntrypoints.ts`
49
+ - Now shows detailed error messages from Bun.build()
50
+ - Displays file location and line numbers for errors
51
+ - Catches and reports exceptions with stack traces
52
+ - Better diagnosis of bundle failures
53
+ - **Added**: Artifact validation in `buildDir.ts`
54
+ - Throws clear error if bundle fails
55
+ - Prevents silent failures
56
+
57
+ ### Documentation
58
+
59
+ - **Updated**: `docs/mcp-server.md` - Documents new common-issues resource
60
+
61
+ ---
62
+
1
63
  # v4.0.1
2
64
 
3
65
  ## Logger System Migration
@@ -0,0 +1,224 @@
1
+ # Common Issues and Solutions
2
+
3
+ When building Tkeron projects, AI agents and users may encounter these common issues. This guide helps prevent and resolve them.
4
+
5
+ ## Script Tag References
6
+
7
+ ### Issue: "Bundle failed" or Cannot Resolve Module
8
+
9
+ **Problem:** HTML references `.js` files but source files are `.ts`
10
+
11
+ ```html
12
+ <!-- ❌ WRONG -->
13
+ <script src="index.js"></script>
14
+
15
+ <!-- ✅ CORRECT -->
16
+ <script type="module" src="index.ts"></script>
17
+ ```
18
+
19
+ **Why this happens:**
20
+
21
+ - Tkeron uses `Bun.build()` to bundle files
22
+ - Bun resolves all file references in HTML (scripts, stylesheets, images)
23
+ - If HTML references `index.js` but only `index.ts` exists, Bun fails with "Could not resolve"
24
+ - The error message may just say "Bundle failed" without details
25
+
26
+ **Solution:**
27
+
28
+ - Always reference `.ts` files directly in HTML
29
+ - Add `type="module"` attribute to script tags
30
+ - Tkeron will automatically compile `.ts` → `.js` and update the reference
31
+
32
+ **Example project structure:**
33
+
34
+ ```
35
+ websrc/
36
+ ├── index.html <!-- References index.ts -->
37
+ ├── index.ts <!-- Your TypeScript code -->
38
+ └── styles.css
39
+ ```
40
+
41
+ ```html
42
+ <!doctype html>
43
+ <html>
44
+ <head>
45
+ <link rel="stylesheet" href="styles.css" />
46
+ </head>
47
+ <body>
48
+ <h1>Hello</h1>
49
+ <script type="module" src="index.ts"></script>
50
+ </body>
51
+ </html>
52
+ ```
53
+
54
+ **After build** (`tk build`):
55
+
56
+ ```
57
+ web/
58
+ ├── index.html <!-- Now references index.js -->
59
+ ├── index.js <!-- Compiled from index.ts -->
60
+ └── index.css <!-- Bundled CSS -->
61
+ ```
62
+
63
+ ## Component Naming
64
+
65
+ ### Issue: Component Name Must Contain Hyphen
66
+
67
+ **Problem:** Custom elements without hyphens are invalid
68
+
69
+ ```html
70
+ <!-- ❌ WRONG -->
71
+ <header></header>
72
+ <!-- Reserved HTML tag -->
73
+ <button></button>
74
+ <!-- Reserved HTML tag -->
75
+
76
+ <!-- ✅ CORRECT -->
77
+ <app-header></app-header>
78
+ <my-button></my-button>
79
+ ```
80
+
81
+ **Why this happens:**
82
+
83
+ - HTML custom elements MUST contain at least one hyphen (web standard)
84
+ - This distinguishes them from standard HTML elements
85
+ - Tkeron validates this at build time
86
+
87
+ **Solution:**
88
+
89
+ - Always use hyphens in component names
90
+ - Match filename to element name (without `.com.html`/`.com.ts`)
91
+
92
+ **Examples:**
93
+
94
+ ```
95
+ user-card.com.html → <user-card>
96
+ nav-menu.com.html → <nav-menu>
97
+ blog-post.com.ts → <blog-post>
98
+ ```
99
+
100
+ ## File References
101
+
102
+ ### Issue: Assets Not Found After Build
103
+
104
+ **Problem:** Relative paths break after build
105
+
106
+ ```html
107
+ <!-- ❌ WRONG - breaks if HTML moves -->
108
+ <img src="images/logo.png" />
109
+
110
+ <!-- ✅ CORRECT - works from any HTML location -->
111
+ <img src="./images/logo.png" />
112
+ ```
113
+
114
+ **Why this happens:**
115
+
116
+ - Tkeron copies your entire source directory structure
117
+ - Relative paths must account for current file location
118
+ - Use `./` for same directory, `../` for parent
119
+
120
+ **Solution:**
121
+
122
+ - Always use explicit relative paths (`./` or `../`)
123
+ - Keep assets in source directory (`websrc/`)
124
+ - They'll be copied to output (`web/`) in same structure
125
+
126
+ ## TypeScript Compilation
127
+
128
+ ### Issue: TypeScript Errors Prevent Build
129
+
130
+ **Problem:** Type errors block compilation
131
+
132
+ ```typescript
133
+ // ❌ WRONG
134
+ const user = { name: "Alice" };
135
+ user.age = 30; // Error: Property 'age' does not exist
136
+ ```
137
+
138
+ **Why this happens:**
139
+
140
+ - Tkeron uses Bun's TypeScript transpiler
141
+ - Type errors can prevent successful builds
142
+ - Missing types for global variables
143
+
144
+ **Solution:**
145
+
146
+ - Use `tkeron.d.ts` for global type declarations
147
+ - Fix type errors before building
148
+ - Use `any` strategically if types are complex
149
+
150
+ ```typescript
151
+ // ✅ CORRECT
152
+ const user: { name: string; age?: number } = { name: "Alice" };
153
+ user.age = 30; // OK
154
+ ```
155
+
156
+ ## Component Resolution
157
+
158
+ ### Issue: Component Not Found
159
+
160
+ **Problem:** Tkeron can't find your component file
161
+
162
+ ```html
163
+ <!-- In blog/post.html -->
164
+ <user-card></user-card>
165
+ ```
166
+
167
+ **Why this happens:**
168
+
169
+ - Tkeron searches in 2 locations only:
170
+ 1. Same directory as HTML file
171
+ 2. Root directory (`websrc/`)
172
+ - Not in subdirectories or parent directories (except root)
173
+
174
+ **Solution:**
175
+ Either place component:
176
+
177
+ - In `blog/user-card.com.html` (next to `post.html`)
178
+ - Or in `websrc/user-card.com.html` (root, available everywhere)
179
+
180
+ ## Build Performance
181
+
182
+ ### Issue: Slow Builds
183
+
184
+ **Problem:** Large projects take time to build
185
+
186
+ **Why this happens:**
187
+
188
+ - Tkeron processes all files on every build
189
+ - Many components create processing overhead
190
+ - Large assets slow down copying
191
+
192
+ **Solution:**
193
+
194
+ - Use `tk dev` for development (hot reload)
195
+ - Only use `tk build` for production builds
196
+ - Keep assets reasonably sized
197
+ - Avoid excessive component nesting
198
+
199
+ ## Common AI Agent Mistakes
200
+
201
+ When AI agents build Tkeron projects, watch for:
202
+
203
+ 1. **Script references**: Always `.ts` in HTML, never `.js`
204
+ 2. **Component names**: Must contain hyphen
205
+ 3. **Type safety**: Don't over-complicate with types
206
+ 4. **File paths**: Use explicit relative paths (`./`, `../`)
207
+
208
+ ## Preventing Issues
209
+
210
+ **Before creating a Tkeron project:**
211
+
212
+ - ✅ Reference `.ts` files in HTML (Tkeron handles compilation)
213
+ - ✅ Use hyphens in all component names
214
+ - ✅ Use `./` for same-directory asset references
215
+ - ✅ Test with `tk dev` before building
216
+ - ✅ Keep components simple and focused
217
+
218
+ **After encountering errors:**
219
+
220
+ - Check script tag references first (most common)
221
+ - Verify component names have hyphens
222
+ - Ensure dependencies are installed
223
+ - Review file paths (use `./` explicitly)
224
+ - Run `tk build` to see full error messages
@@ -86,6 +86,46 @@ Same as HTML components:
86
86
  1. **Same directory** as the file using it
87
87
  2. **Root directory** (`websrc/`)
88
88
 
89
+ ### IDE Support & IntelliSense
90
+
91
+ For the best development experience, Tkeron projects include TypeScript configuration files:
92
+
93
+ **`tkeron.d.ts`** - Provides type definitions:
94
+
95
+ ```typescript
96
+ declare module "*.com.ts" {
97
+ global {
98
+ const com: HTMLElement;
99
+ }
100
+ }
101
+ ```
102
+
103
+ This tells your IDE that `com` is an `HTMLElement`, enabling:
104
+
105
+ - **IntelliSense** for `com.getAttribute()`, `com.innerHTML`, etc.
106
+ - **Type checking** for your component code
107
+ - **Auto-completion** for DOM methods and properties
108
+
109
+ **`tsconfig.json`** - TypeScript configuration:
110
+
111
+ ```json
112
+ {
113
+ "compilerOptions": {
114
+ "target": "ESNext",
115
+ "module": "ESNext",
116
+ "lib": ["ESNext", "DOM"],
117
+ "moduleResolution": "bundler",
118
+ "strict": true,
119
+ "skipLibCheck": true
120
+ },
121
+ "include": ["websrc/**/*", "tkeron.d.ts"]
122
+ }
123
+ ```
124
+
125
+ Both files are automatically created when you run `tk init`. If you created your project manually, you can copy them from the [init_sample example](https://github.com/pablotk/tkeron/tree/master/examples/init_sample).
126
+
127
+ **Note:** These files are only for IDE support and don't affect the build process. Tkeron uses Bun's built-in TypeScript support for compilation.
128
+
89
129
  ## Basic Examples
90
130
 
91
131
  ### Attribute-Based Content
@@ -38,7 +38,8 @@ my-website/
38
38
  │ ├── index.ts # TypeScript for index
39
39
  │ ├── index.pre.ts # Pre-rendering script
40
40
  │ └── *.com.html # Sample components
41
- └── tkeron.d.ts # TypeScript definitions
41
+ ├── tkeron.d.ts # TypeScript definitions
42
+ └── tsconfig.json # TypeScript configuration
42
43
  ```
43
44
 
44
45
  ### Initialize in Current Directory
@@ -99,6 +99,7 @@ The MCP server exposes the following documentation resources:
99
99
  | `tkeron://pre-rendering` | Transform HTML at build time with .pre.ts files |
100
100
  | `tkeron://cli-reference` | Complete command-line interface documentation |
101
101
  | `tkeron://best-practices` | Patterns, anti-patterns, and limitations |
102
+ | `tkeron://common-issues` | Troubleshooting guide and common mistakes |
102
103
  | `tkeron://testing` | How to test tkeron projects with getBuildResult() |
103
104
 
104
105
  ## What AI Agents Can Do
@@ -112,6 +113,7 @@ With access to the MCP server, AI agents can:
112
113
  - ✅ Provide accurate CLI commands and options
113
114
  - ✅ Debug common issues with components and pre-rendering
114
115
  - ✅ Recommend best practices and avoid anti-patterns
116
+ - ✅ **Prevent common mistakes** (script references, component naming, dependencies)
115
117
  - ✅ **List and explore example projects**
116
118
  - ✅ **Retrieve example code and structures**
117
119
  - ✅ **Initialize, build, and develop projects via terminal** (`tk init`, `tk build`, `tk dev`)
@@ -97,6 +97,26 @@ If the `.html` file doesn't exist, Tkeron creates a default one:
97
97
 
98
98
  Then your `.pre.ts` file runs on this template.
99
99
 
100
+ ### IDE Support & IntelliSense
101
+
102
+ The `tkeron.d.ts` file in your project provides type definitions for the `document` variable:
103
+
104
+ ```typescript
105
+ declare module "*.pre.ts" {
106
+ global {
107
+ const document: Document;
108
+ }
109
+ }
110
+ ```
111
+
112
+ This enables:
113
+
114
+ - **IntelliSense** for `document.querySelector()`, `document.getElementById()`, etc.
115
+ - **Type checking** for DOM manipulation
116
+ - **Auto-completion** for all Document methods and properties
117
+
118
+ The `tsconfig.json` ensures your IDE recognizes these types. Both files are automatically created by `tk init`.
119
+
100
120
  ## Basic Examples
101
121
 
102
122
  ### Set Page Title
@@ -0,0 +1,13 @@
1
+ // Augment global scope for .pre.ts files
2
+ declare module "*.pre.ts" {
3
+ global {
4
+ const document: Document;
5
+ }
6
+ }
7
+
8
+ // Augment global scope for .com.ts files
9
+ declare module "*.com.ts" {
10
+ global {
11
+ const com: HTMLElement;
12
+ }
13
+ }
@@ -1,10 +1,10 @@
1
1
  // Client-side TypeScript - runs in the browser
2
- let count = 0;
2
+ let clickCount = 0;
3
3
 
4
- const button = document.getElementById('increment') as HTMLButtonElement;
5
- const countDisplay = document.getElementById('count') as HTMLSpanElement;
4
+ const button = document.getElementById("increment") as HTMLButtonElement;
5
+ const countDisplay = document.getElementById("count") as HTMLSpanElement;
6
6
 
7
- button.addEventListener('click', () => {
8
- count++;
9
- countDisplay.textContent = count.toString();
7
+ button.addEventListener("click", () => {
8
+ clickCount++;
9
+ countDisplay.textContent = clickCount.toString();
10
10
  });
@@ -1,16 +1,17 @@
1
1
  // TypeScript component - runs at build time with logic
2
- const count = com.getAttribute('count') || '3';
2
+ const count = com.getAttribute("count") || "3";
3
+ const numCount = parseInt(count, 10);
3
4
 
4
5
  // Generate list dynamically
5
6
  const items = [];
6
- for (let i = 1; i <= parseInt(count); i++) {
7
+ for (let i = 1; i <= numCount; i++) {
7
8
  items.push(`<li>✓ Item ${i}</li>`);
8
9
  }
9
10
 
10
11
  com.innerHTML = `
11
12
  <div style="background: #f0fdf4; border-left: 3px solid #22c55e; padding: 0.75rem; border-radius: 4px;">
12
13
  <ul style="list-style: none; padding: 0; margin: 0; font-size: 0.9rem; color: #166534;">
13
- ${items.join('')}
14
+ ${items.join("")}
14
15
  </ul>
15
16
  </div>
16
17
  `;
package/mcp-server.ts CHANGED
@@ -71,6 +71,13 @@ const DOCS = [
71
71
  description: "Patterns, anti-patterns, and limitations",
72
72
  file: "best-practices.md",
73
73
  },
74
+ {
75
+ uri: "tkeron://common-issues",
76
+ name: "Common Issues and Solutions",
77
+ description:
78
+ "Troubleshooting guide: script references, component naming, dependencies, and common mistakes",
79
+ file: "common-issues.md",
80
+ },
74
81
  {
75
82
  uri: "tkeron://testing",
76
83
  name: "Testing Tkeron Projects",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tkeron",
3
- "version": "4.0.1",
3
+ "version": "4.2.0",
4
4
  "description": "CLI tool for backend-driven frontend development with TypeScript.",
5
5
  "type": "module",
6
6
  "main": "./src/index.ts",
package/src/buildDir.ts CHANGED
@@ -33,6 +33,10 @@ export const buildDir = async (
33
33
 
34
34
  const files = await buildEntrypoints(htmlFiles, sourceDir, { logger: log });
35
35
 
36
+ if (!files || !files.artifacts) {
37
+ throw new Error("Bundle failed");
38
+ }
39
+
36
40
  for (const a of files?.artifacts || []) {
37
41
  const outPath = join(targetDir, a.pathR);
38
42
  if (a.pathR.toLowerCase().endsWith(".html")) {
@@ -23,44 +23,71 @@ export const buildEntrypoints = async (
23
23
  return;
24
24
  }
25
25
 
26
- const { outputs, success } = await Bun.build({
27
- entrypoints: filePaths,
28
- minify: true,
29
- splitting: false,
30
- target: "browser",
31
- root,
32
- naming: {
33
- asset: "[dir]/[name].[ext]",
34
- chunk: "[dir]/[name].[ext]",
35
- entry: "[dir]/[name].[ext]",
36
- },
37
- });
26
+ try {
27
+ const result = await Bun.build({
28
+ entrypoints: filePaths,
29
+ minify: true,
30
+ splitting: false,
31
+ target: "browser",
32
+ root,
33
+ naming: {
34
+ asset: "[dir]/[name].[ext]",
35
+ chunk: "[dir]/[name].[ext]",
36
+ entry: "[dir]/[name].[ext]",
37
+ },
38
+ });
38
39
 
39
- if (!success) return;
40
+ const { outputs, success, logs } = result;
40
41
 
41
- const artifacts = await Promise.all(
42
- outputs?.map(async (artifact, index) => {
43
- const path = artifact.path;
44
- const pathR = normalize(artifact.path);
45
- const hash = artifact.hash;
46
- const kind = artifact.kind;
47
- const loader = artifact.loader;
48
- const type = artifact.type;
49
- const sourcemap = await artifact.sourcemap?.text();
42
+ if (!success) {
43
+ if (logs && logs.length > 0) {
44
+ log.error(`\n❌ Build failed with ${logs.length} error(s):\n`);
45
+ for (const logEntry of logs) {
46
+ log.error(`${logEntry.message}`);
47
+ if (logEntry.position) {
48
+ log.error(
49
+ ` at ${logEntry.position.file}:${logEntry.position.line}:${logEntry.position.column}`,
50
+ );
51
+ }
52
+ }
53
+ log.error("");
54
+ } else {
55
+ log.error(`\n❌ Build failed with no error details from Bun.build()`);
56
+ }
57
+ return;
58
+ }
50
59
 
51
- return {
52
- path,
53
- pathR,
54
- hash,
55
- index,
56
- kind,
57
- loader,
58
- type,
59
- sourcemap,
60
- artifact,
61
- };
62
- }),
63
- );
60
+ const artifacts = await Promise.all(
61
+ outputs?.map(async (artifact, index) => {
62
+ const path = artifact.path;
63
+ const pathR = normalize(artifact.path);
64
+ const hash = artifact.hash;
65
+ const kind = artifact.kind;
66
+ const loader = artifact.loader;
67
+ const type = artifact.type;
68
+ const sourcemap = await artifact.sourcemap?.text();
64
69
 
65
- return { artifacts };
70
+ return {
71
+ path,
72
+ pathR,
73
+ hash,
74
+ index,
75
+ kind,
76
+ loader,
77
+ type,
78
+ sourcemap,
79
+ artifact,
80
+ };
81
+ }),
82
+ );
83
+
84
+ return { artifacts };
85
+ } catch (error: any) {
86
+ log.error(`\n❌ Bun.build() threw an exception:`);
87
+ log.error(` ${error.message}`);
88
+ if (error.stack) {
89
+ log.error(`\n${error.stack}`);
90
+ }
91
+ throw error;
92
+ }
66
93
  };