tkeron 4.5.0 → 5.0.0

package/changelog.md

@@ -1,3 +1,38 @@
+# v5.0.0
+
+## Breaking: sourceDir and targetDir removed as CLI arguments
+
+- `tk build` and `tk dev` no longer accept positional directory arguments
+- Fixed convention: source in `websrc/`, output in `web/`
+- To migrate: rename your source directory to `websrc/` (`mv your-dir websrc`)
+- Output is always `web/` (sibling of `websrc/`) — no longer configurable via CLI
+- `port` and `host` remain as positional arguments for `tk dev`
+
+## Fix: pre-rendering module resolution in projects without node_modules
+
+- `processPre.ts` now injects the absolute resolved path of `@tkeron/html-parser` instead of the bare specifier
+- Fixes failure when the user's project lives inside a workspace root with a `node_modules/` that doesn't include `@tkeron` dependencies
+
+### Migration
+
+```bash
+# Before (v4.x)
+tk build src dist
+tk dev src dist 8080
+
+# After (v5.0)
+tk build
+tk dev 8080
+```
+
+### What changed
+
+- `buildWrapper` no longer forwards `sourceDir`/`targetDir` to `build()`
+- CLI positioned arguments for directories removed from `build` and `develop` commands
+- Documentation updated (cli-reference, getting-started)
+
+---
+
 # v4.5.0
 
 ## tsconfig.json Generation on Init

package/docs/cli-reference.md

@@ -52,30 +52,22 @@ Build your project by processing source files into static output.
 **Usage:**
 
 ```bash
-tk build [sourceDir] [targetDir]
+tk build
 ```
 
-**Arguments:**
+**Convention:**
 
-| Argument    | Type   | Default  | Description                                    |
-| ----------- | ------ | -------- | ---------------------------------------------- |
-| `sourceDir` | string | `websrc` | Source directory containing your project files |
-| `targetDir` | string | `web`    | Output directory for built files               |
+- Source directory: `websrc/` (relative to current directory)
+- Output directory: `web/` (sibling of `websrc/`)
 
 **Examples:**
 
 ```bash
-# Build with defaults (websrc → web)
+# Build the project
 tk build
 
-# Build with custom source directory
-tk build src web
-
-# Build to custom output directory
-tk build websrc dist
-
-# Build with both custom
-tk build source output
+# Using alias
+tk b
 ```
 
 **Build Process:**
@@ -120,17 +112,20 @@ Start a development server with hot reload.
 **Usage:**
 
 ```bash
-tk develop [sourceDir] [outputDir] [port] [host]
+tk develop [port] [host]
 ```
 
 **Arguments:**
 
-| Argument    | Type   | Default     | Description                 |
-| ----------- | ------ | ----------- | --------------------------- |
-| `sourceDir` | string | `websrc`    | Source directory to watch   |
-| `outputDir` | string | `web`       | Output directory for builds |
-| `port`      | number | `3000`      | Port for development server |
-| `host`      | string | `localhost` | Host to bind server to      |
+| Argument | Type   | Default     | Description                 |
+| -------- | ------ | ----------- | --------------------------- |
+| `port`   | number | `3000`      | Port for development server |
+| `host`   | string | `localhost` | Host to bind server to      |
+
+**Convention:**
+
+- Source directory: `websrc/` (relative to current directory)
+- Output directory: `web/` (sibling of `websrc/`)
 
 **Examples:**
 
@@ -138,17 +133,14 @@ tk develop [sourceDir] [outputDir] [port] [host]
 # Start with defaults
 tk dev
 
-# Custom source and output
-tk dev src dist
-
 # Custom port
-tk dev websrc web 8080
+tk dev 8080
 
 # Bind to all interfaces
-tk dev websrc web 3000 0.0.0.0
+tk dev 3000 0.0.0.0
 
 # Complete custom configuration
-tk develop source output 8080 0.0.0.0
+tk develop 8080 0.0.0.0
 ```
 
 **What It Does:**
@@ -317,7 +309,7 @@ tk init . --force
 cd my-website
 
 # Start development server
-tk dev websrc
+tk dev
 
 # Open http://localhost:3000
 ```
@@ -356,7 +348,7 @@ Quick reference for command shortcuts:
 ```bash
 tk b                    # Same as: tk build
 tk d                    # Same as: tk develop
-tk dev websrc web 8080  # Same as: tk develop websrc web 8080
+tk dev 8080             # Same as: tk develop 8080
 tk i my-site            # Same as: tk init my-site
 ```
 
@@ -430,22 +422,19 @@ Tkeron uses **convention over configuration**. There are no configuration files.
 
 **Project Structure Convention:**
 
-- Source directory: `websrc/` (default)
-- Output directory: `web/` (default)
+- Source directory: `websrc/` (fixed)
+- Output directory: `web/` (fixed)
 - Component files: `*.com.html` and `*.com.ts`
 - Pre-render files: `*.pre.ts`
 - Type definitions: `tkeron.d.ts`
 
 **Customization:**
 
-All customization is done via command-line arguments:
+Server configuration is done via command-line arguments:
 
 ```bash
-# Custom directories
-tk build src dist
-
 # Custom server config
-tk dev src dist 8080 0.0.0.0
+tk dev 8080 0.0.0.0
 ```
 
 ---
@@ -580,7 +569,7 @@ Error: Port 3000 is already in use
 
 ```bash
 # Use different port
-tk dev websrc web 3001
+tk dev 3001
 ```
 
 ### Source Directory Not Found
@@ -597,8 +586,8 @@ tk dev websrc web 3001
 # Create directory
 mkdir websrc
 
-# Or use correct path
-tk build src web
+# Or initialize a new project
+tk init .
 ```
 
 ### Permission Denied
@@ -668,11 +657,8 @@ tk dev
 # Build for production
 NODE_ENV=production tk build
 
-# Build to custom directory
-tk build websrc dist
-
 # Development on port 8080
-tk dev websrc web 8080
+tk dev 8080
 
 # Initialize in current directory
 tk init .

package/docs/getting-started.md

@@ -65,22 +65,20 @@ tk init my-website --force
 Build your project to compile it into static files:
 
 ```bash
-tk build websrc web
+tk build
 ```
 
-**Parameters:**
+**Convention:**
 
-- First argument: source directory (default: `websrc`)
-- Second argument: output directory (default: `web`)
+- Source: `websrc/` (relative to current directory)
+- Output: `web/` (sibling of `websrc/`)
 
-**Shorthand:**
+**Using alias:**
 
 ```bash
-tk build
+tk b
 ```
 
-This uses the defaults: `websrc` → `web`
-
 **Output structure:**
 
 ```
@@ -110,20 +108,18 @@ This will:
 **Custom configuration:**
 
 ```bash
-tk dev websrc web 8080 0.0.0.0
+tk dev 8080 0.0.0.0
 ```
 
 **Parameters:**
 
-- Source directory (default: `websrc`)
-- Output directory (default: `web`)
 - Port (default: `3000`)
 - Host (default: `localhost`)
 
 **Example with custom port:**
 
 ```bash
-tk dev websrc web 8080
+tk dev 8080
 ```
 
 Visit `http://localhost:8080` in your browser.
@@ -212,17 +208,14 @@ Open `web/index.html` in your browser. You'll see the greeting component inlined
 # Show help
 tk
 
-# Build with defaults
+# Build the project
 tk build
 
-# Build with custom directories
-tk build src dist
-
 # Start dev server
 tk dev
 
 # Start dev server on port 8080
-tk dev websrc web 8080
+tk dev 8080
 
 # Initialize new project
 tk init my-project
@@ -248,14 +241,14 @@ Now that you have a basic understanding:
 
 ### "Source directory does not exist"
 
-Make sure you're running commands from the right directory:
+Make sure you're running commands from the right directory and that `websrc/` exists:
 
 ```bash
 # Check if websrc exists
 ls websrc
 
-# Or specify the correct path
-tk build path/to/websrc path/to/web
+# Or run tk init to create a new project
+tk init .
 ```
 
 ### "Command not found: tk"
@@ -271,7 +264,7 @@ bun install -g tkeron
 Use a different port:
 
 ```bash
-tk dev websrc web 3001
+tk dev 3001
 ```
 
 ### Components not working

package/examples/init_sample/tkeron.d.ts

@@ -1,13 +1 @@
-// Augment global scope for .pre.ts files
-declare module "*.pre.ts" {
-  global {
-    const document: Document;
-  }
-}
-
-// Augment global scope for .com.ts files
-declare module "*.com.ts" {
-  global {
-    const com: HTMLElement;
-  }
-}
+declare const com: HTMLElement;

package/index.ts

@@ -15,8 +15,6 @@ getCommands("tkeron", packageJson.version)
   .addCommand("build")
   .addAlias("b")
   .addDescription("Build the project")
-  .addPositionedArgument("sourceDir")
-  .addPositionedArgument("targetDir")
   .setCallback(buildWrapper)
 
   .commands()
@@ -25,8 +23,6 @@ getCommands("tkeron", packageJson.version)
   .addAlias("dev")
   .addAlias("d")
   .addDescription("Start development server")
-  .addPositionedArgument("sourceDir")
-  .addPositionedArgument("targetDir")
   .addPositionedArgument("port")
   .addPositionedArgument("host")
   .setCallback(develop)

package/package.json

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

package/src/buildWrapper.ts

@@ -3,8 +3,6 @@ import type { Logger } from "@tkeron/tools";
 import { logger as defaultLogger } from "@tkeron/tools";
 
 export interface BuildWrapperOptions {
-  sourceDir?: string;
-  targetDir?: string;
   logger?: Logger;
   [key: string]: any;
 }
@@ -13,7 +11,7 @@ export const buildWrapper = async (options: BuildWrapperOptions) => {
   const log = options?.logger || defaultLogger;
 
   try {
-    await build({ ...options, logger: log });
+    await build({ logger: log });
   } catch (error: any) {
     log.error(`\n❌ Build failed: ${error.message}\n`);
     process.exit(1);

package/src/ensureTsconfig.ts

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const REQUIRED_INCLUDES = ["websrc/**/*", "tkeron.d.ts"];
+
+const DEFAULT_COMPILER_OPTIONS = {
+  target: "ESNext",
+  module: "ESNext",
+  lib: ["ESNext", "DOM"],
+  moduleResolution: "bundler",
+  strict: true,
+  skipLibCheck: true,
+};
+
+const createFreshTsconfig = () => ({
+  compilerOptions: { ...DEFAULT_COMPILER_OPTIONS },
+  include: [...REQUIRED_INCLUDES],
+});
+
+const mergeIncludes = (existing: string[]): string[] => {
+  const merged = [...existing];
+  for (const entry of REQUIRED_INCLUDES) {
+    if (!merged.includes(entry)) {
+      merged.push(entry);
+    }
+  }
+  return merged;
+};
+
+export const ensureTsconfig = (
+  targetPath: string,
+  previousTsconfig?: Record<string, unknown>,
+) => {
+  const tsconfigPath = join(targetPath, "tsconfig.json");
+
+  if (previousTsconfig) {
+    const existingIncludes = Array.isArray(previousTsconfig.include)
+      ? (previousTsconfig.include as string[])
+      : [];
+    const merged = {
+      ...previousTsconfig,
+      include: mergeIncludes(existingIncludes),
+    };
+    writeFileSync(tsconfigPath, JSON.stringify(merged, null, 2));
+    return;
+  }
+
+  if (existsSync(tsconfigPath)) {
+    try {
+      const content = readFileSync(tsconfigPath, "utf-8");
+      const parsed = JSON.parse(content);
+      const existingIncludes = Array.isArray(parsed.include)
+        ? (parsed.include as string[])
+        : [];
+      const merged = { ...parsed, include: mergeIncludes(existingIncludes) };
+      writeFileSync(tsconfigPath, JSON.stringify(merged, null, 2));
+      return;
+    } catch {
+      writeFileSync(
+        tsconfigPath,
+        JSON.stringify(createFreshTsconfig(), null, 2),
+      );
+      return;
+    }
+  }
+
+  writeFileSync(tsconfigPath, JSON.stringify(createFreshTsconfig(), null, 2));
+};

package/src/init.ts

@@ -4,7 +4,6 @@ import {
   mkdirSync,
   copyFileSync,
   readFileSync,
-  writeFileSync,
   readdirSync,
   rmSync,
 } from "fs";
@@ -12,6 +11,7 @@ import { join, resolve, basename } from "path";
 import type { Logger } from "@tkeron/tools";
 import { silentLogger } from "@tkeron/tools";
 import { promptUser } from "./promptUser";
+import { ensureTsconfig } from "./ensureTsconfig";
 
 export interface InitOptions {
   projectName: string;
@@ -30,6 +30,8 @@ export const init = async (options: InitOptions) => {
   const targetPath = resolve(process.cwd(), projectName);
   const isCurrentDir = projectName === "." || targetPath === process.cwd();
 
+  let skipWebsrc = false;
+
   if (existsSync(targetPath)) {
     if (!isCurrentDir) {
       if (!force) {
@@ -57,18 +59,22 @@ export const init = async (options: InitOptions) => {
             "\nDo you want to overwrite them? (y/N): ",
           );
 
-          if (!shouldContinue) {
-            log.log("\n❌ Operation cancelled.");
-            return;
+          if (shouldContinue) {
+            existingTkeronFiles.forEach((file) => {
+              const filePath = join(targetPath, file);
+              rmSync(filePath, { recursive: true, force: true });
+            });
+            log.log("✓ Cleaned existing tkeron files");
+          } else {
+            skipWebsrc = existingTkeronFiles.includes("websrc");
           }
+        } else {
+          existingTkeronFiles.forEach((file) => {
+            const filePath = join(targetPath, file);
+            rmSync(filePath, { recursive: true, force: true });
+          });
+          log.log("✓ Cleaned existing tkeron files");
         }
-
-        existingTkeronFiles.forEach((file) => {
-          const filePath = join(targetPath, file);
-          rmSync(filePath, { recursive: true, force: true });
-        });
-
-        log.log("✓ Cleaned existing tkeron files");
       }
     }
   }
@@ -91,36 +97,27 @@ export const init = async (options: InitOptions) => {
   }
 
   const tsconfigPath = join(targetPath, "tsconfig.json");
-  let existingTsconfig: Record<string, unknown> | null = null;
-  if (isCurrentDir && existsSync(tsconfigPath)) {
+  let previousTsconfig: Record<string, unknown> | undefined;
+  if (existsSync(tsconfigPath)) {
     try {
-      existingTsconfig = JSON.parse(readFileSync(tsconfigPath, "utf-8"));
+      previousTsconfig = JSON.parse(readFileSync(tsconfigPath, "utf-8"));
     } catch {
-      existingTsconfig = null;
+      previousTsconfig = undefined;
     }
   }
 
   mkdirSync(targetPath, { recursive: true });
-  cpSync(templatePath, targetPath, { recursive: true });
+  const websrcInTemplate = join(templatePath, "websrc");
+  cpSync(templatePath, targetPath, {
+    recursive: true,
+    filter: skipWebsrc
+      ? (src: string) =>
+          src !== websrcInTemplate && !src.startsWith(websrcInTemplate + "/")
+      : undefined,
+  });
   copyFileSync(tkeronDtsPath, join(targetPath, "tkeron.d.ts"));
 
-  if (existingTsconfig !== null) {
-    const templateTsconfig = JSON.parse(readFileSync(tsconfigPath, "utf-8"));
-    const requiredIncludes: string[] = Array.isArray(templateTsconfig.include)
-      ? (templateTsconfig.include as string[])
-      : [];
-    const existingIncludes: string[] = Array.isArray(existingTsconfig.include)
-      ? (existingTsconfig.include as string[])
-      : [];
-    const mergedIncludes = [...existingIncludes];
-    for (const entry of requiredIncludes) {
-      if (!mergedIncludes.includes(entry)) {
-        mergedIncludes.push(entry);
-      }
-    }
-    const merged = { ...existingTsconfig, include: mergedIncludes };
-    writeFileSync(tsconfigPath, JSON.stringify(merged, null, 2));
-  }
+  ensureTsconfig(targetPath, previousTsconfig);
 
   const projectDisplayName = isCurrentDir ? basename(targetPath) : projectName;
   log.log(`✓ Created project "${projectDisplayName}"`);

package/src/processComTs.ts

@@ -137,7 +137,9 @@ const processComponentsTs = async (
 
           const elementHTML = (child as any).outerHTML;
 
-          log.info(`Processing component <${tagName}> from ${componentPath}`);
+          log.info(
+            `Processing component <${tagName}> from ${componentPath.replace(rootDir, ".")}`,
+          );
 
           const tempDoc = parseHTML(
             "<html><body>" + elementHTML + "</body></html>",
@@ -199,7 +201,9 @@ ${codeWithoutImports}
               await executeComponent(com);
             }
           } catch (execError: any) {
-            log.error(`\n❌ Error executing component <${tagName}>:`);
+            log.error(
+              `\n❌ Error executing component <${tagName}>: ${componentPath.replace(rootDir, ".")}`,
+            );
             log.error(`   ${execError.message}`);
             throw execError;
           }

package/src/processPre.ts

@@ -7,6 +7,8 @@ const packageJsonPath = join(import.meta.dir, "..", "package.json");
 const packageJson = await Bun.file(packageJsonPath).json();
 const TKERON_VERSION = packageJson.version;
 
+const HTML_PARSER_PATH = import.meta.resolve("@tkeron/html-parser");
+
 const DEFAULT_HTML = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -48,7 +50,7 @@ export const processPre = async (
       : DEFAULT_HTML;
 
     const modifiedCode = `
-        import { parseHTML } from "@tkeron/html-parser";
+        import { parseHTML } from ${JSON.stringify(HTML_PARSER_PATH)};
 
         const htmlPath = ${JSON.stringify(htmlFile)};
         const htmlContent = ${JSON.stringify(htmlContent)};

package/tkeron.d.ts

@@ -1,13 +1 @@
-// Augment global scope for .pre.ts files
-declare module "*.pre.ts" {
-  global {
-    const document: Document;
-  }
-}
-
-// Augment global scope for .com.ts files
-declare module "*.com.ts" {
-  global {
-    const com: HTMLElement;
-  }
-}
+declare const com: HTMLElement;