thinkwell 0.3.2 → 0.4.0

package/bin/thinkwell

@@ -3,36 +3,54 @@
 /**
  * Thinkwell CLI launcher
  *
- * This Node.js script detects if Bun is available and delegates to it
- * with the @thinkwell/bun-plugin preloaded.
+ * This Node.js script serves as the entry point for the npm distribution.
+ * It uses Node.js with the pkg-style loader for script execution, requiring
+ * Node 24+ for native TypeScript support via --experimental-transform-types.
+ *
+ * The pkg binary distribution uses a separate entry point (main-pkg.cjs)
+ * which is compiled directly into the binary.
  */
 
-import { execSync, spawn } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { dirname, resolve, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Check if Bun is available and return version or null
-function getBunVersion() {
-  try {
-    const version = execSync("bun --version", { encoding: "utf-8" }).trim();
-    return version;
-  } catch {
-    return null;
-  }
-}
+// ============================================================================
+// Re-exec with Proper Node Flags
+// ============================================================================
+
+// Check if we need to re-exec with proper flags
+// We use an env var to prevent infinite re-exec loops
+const REEXEC_FLAG = "__THINKWELL_REEXEC__";
+
+if (!process.env[REEXEC_FLAG]) {
+  // Re-exec with experimental transform types and warning suppression
+  const result = spawnSync(process.execPath, [
+    "--experimental-transform-types",
+    "--disable-warning=ExperimentalWarning",
+    fileURLToPath(import.meta.url),
+    ...process.argv.slice(2),
+  ], {
+    stdio: "inherit",
+    env: { ...process.env, [REEXEC_FLAG]: "1" },
+  });
 
-// Get the path to the plugin
-function getPluginPath() {
-  // When installed via npm, the plugin is in our node_modules
-  return resolve(__dirname, "../node_modules/@thinkwell/bun-plugin/dist/index.js");
+  process.exit(result.status ?? 1);
 }
 
-// Get the path to our node_modules (where thinkwell packages are installed)
-function getNodeModulesPath() {
-  return resolve(__dirname, "../node_modules");
+// Minimum Node.js version for native TypeScript support
+const MIN_NODE_VERSION = 24;
+
+// ============================================================================
+// Path Helpers
+// ============================================================================
+
+// Get the path to the init command script
+function getInitCommandPath() {
+  return resolve(__dirname, "../dist/cli/init-command.js");
 }
 
 // Get the path to the types command script
@@ -40,18 +58,61 @@ function getTypesCommandPath() {
   return resolve(__dirname, "../dist/cli/types-command.js");
 }
 
-// Validate that required files exist for commands that require Bun
+// Get the path to the bundled CLI loader
+function getLoaderPath() {
+  return resolve(__dirname, "../dist-pkg/cli-loader.cjs");
+}
+
+// Get paths to the bundled thinkwell packages
+function getBundledPackagesPath() {
+  return {
+    thinkwell: resolve(__dirname, "../dist-pkg/thinkwell.cjs"),
+    acp: resolve(__dirname, "../dist-pkg/acp.cjs"),
+    protocol: resolve(__dirname, "../dist-pkg/protocol.cjs"),
+  };
+}
+
+// ============================================================================
+// Runtime Detection
+// ============================================================================
+
+// Get Node.js major version
+function getNodeMajorVersion() {
+  const match = process.version.match(/^v(\d+)/);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+// Validate Node.js version
+function validateNodeVersion() {
+  const nodeMajor = getNodeMajorVersion();
+  if (nodeMajor < MIN_NODE_VERSION) {
+    console.error(`Error: thinkwell requires Node.js ${MIN_NODE_VERSION} or later.`);
+    console.error(`Current version: ${process.version}`);
+    console.error("");
+    console.error("Node.js 24+ is required for native TypeScript support.");
+    console.error("Please upgrade Node.js: https://nodejs.org/");
+    process.exit(1);
+  }
+}
+
+// Validate that required files exist for script execution
 function validateInstallation() {
-  const pluginPath = getPluginPath();
-  const typesCommandPath = getTypesCommandPath();
+  const loaderPath = getLoaderPath();
+  const bundledPaths = getBundledPackagesPath();
   const errors = [];
 
-  if (!existsSync(pluginPath)) {
-    errors.push(`Plugin not found: ${pluginPath}`);
+  if (!existsSync(loaderPath)) {
+    errors.push(`Loader not found: ${loaderPath}`);
   }
 
-  if (!existsSync(typesCommandPath)) {
-    errors.push(`Types command not found: ${typesCommandPath}`);
+  for (const [name, path] of Object.entries(bundledPaths)) {
+    if (!existsSync(path)) {
+      errors.push(`Bundled ${name} not found: ${path}`);
+    }
   }
 
   if (errors.length > 0) {
@@ -75,6 +136,17 @@ function validateInitCommand() {
   }
 }
 
+// Validate types command is available
+function validateTypesCommand() {
+  const typesCommandPath = getTypesCommandPath();
+  if (!existsSync(typesCommandPath)) {
+    console.error("Error: thinkwell installation appears to be corrupted.");
+    console.error(`  - Types command not found: ${typesCommandPath}`);
+    console.error("\nTry reinstalling with: npm install thinkwell");
+    process.exit(1);
+  }
+}
+
 // Parse version from package.json
 async function getVersion() {
   const packagePath = resolve(__dirname, "../package.json");
@@ -82,12 +154,10 @@ async function getVersion() {
   return pkg.version;
 }
 
-// Get the path to the init command script
-function getInitCommandPath() {
-  return resolve(__dirname, "../dist/cli/init-command.js");
-}
+// ============================================================================
+// Help
+// ============================================================================
 
-// Show help message
 function showHelp() {
   console.log(`
 thinkwell - Run TypeScript scripts with automatic schema generation
@@ -119,10 +189,132 @@ For more information, visit: https://github.com/dherman/thinkwell
 `);
 }
 
+// ============================================================================
+// Bundled Module Registration
+// ============================================================================
+
+/**
+ * Register bundled thinkwell packages to global.__bundled__.
+ *
+ * For the npm distribution, we load the pre-bundled CJS packages from dist-pkg/.
+ * This mirrors what main-pkg.cjs does for the pkg binary distribution.
+ */
+async function registerBundledModules() {
+  const bundledPaths = getBundledPackagesPath();
+
+  try {
+    // Dynamic import the bundled CJS packages
+    const thinkwell = await import(bundledPaths.thinkwell);
+    const acpModule = await import(bundledPaths.acp);
+    const protocolModule = await import(bundledPaths.protocol);
+
+    // Register to global.__bundled__ for the loader to access
+    global.__bundled__ = {
+      thinkwell: thinkwell.default || thinkwell,
+      "@thinkwell/acp": acpModule.default || acpModule,
+      "@thinkwell/protocol": protocolModule.default || protocolModule,
+    };
+  } catch (error) {
+    console.error("Error: Failed to load bundled modules.");
+    console.error("");
+    if (process.env.DEBUG) {
+      console.error("Debug info:");
+      console.error(`  ${error.message}`);
+      console.error(error.stack);
+    }
+    console.error("Try reinstalling with: npm install thinkwell");
+    process.exit(1);
+  }
+}
+
+// ============================================================================
+// Script Execution
+// ============================================================================
+
+/**
+ * Run a user script using the CLI loader.
+ */
+async function runUserScript(scriptPath, args) {
+  // Resolve the script path
+  const resolvedPath = isAbsolute(scriptPath)
+    ? scriptPath
+    : resolve(process.cwd(), scriptPath);
+
+  // Check if the script file exists
+  if (!existsSync(resolvedPath)) {
+    console.error(`Error: Script not found: ${scriptPath}`);
+    console.error("");
+    console.error("Make sure the file exists and the path is correct.");
+    process.exit(1);
+  }
+
+  // Import the loader
+  const loaderPath = getLoaderPath();
+  const { runScript } = await import(loaderPath);
+
+  try {
+    await runScript(resolvedPath, args);
+  } catch (error) {
+    // Handle common error cases with helpful messages
+    if (error.message && error.message.includes("Cannot find module")) {
+      console.error(`Error: ${error.message}`);
+      console.error("");
+      console.error("Make sure the module is installed in your project's node_modules.");
+      process.exit(1);
+    }
+
+    if (error.message && error.message.includes("Cannot find package")) {
+      console.error(`Error: ${error.message}`);
+      console.error("");
+      console.error("Run 'npm install' or 'pnpm install' to install dependencies.");
+      process.exit(1);
+    }
+
+    // Re-throw other errors
+    throw error;
+  }
+}
+
+/**
+ * Run the types command.
+ *
+ * The types command uses the same loader infrastructure to process
+ * TypeScript files and generate .d.ts declarations.
+ */
+async function runTypesCommand(args) {
+  validateTypesCommand();
+  const typesCommandPath = getTypesCommandPath();
+
+  // Spawn Node.js with the types command
+  const child = spawn(process.execPath, [
+    "--experimental-transform-types",
+    "--disable-warning=ExperimentalWarning",
+    typesCommandPath,
+    ...args,
+  ], {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("error", (err) => {
+    console.error(`Error: Failed to run types command.`);
+    console.error(`  ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+
 async function main() {
   const args = process.argv.slice(2);
 
-  // Handle "init" subcommand first - does NOT require Bun
+  // Handle "init" subcommand first - does NOT require bundled modules
   // Must be before global --help so "init --help" shows init-specific help
   if (args[0] === "init") {
     validateInitCommand();
@@ -148,56 +340,16 @@ async function main() {
     process.exit(0);
   }
 
-  // All commands below require Bun
-  const bunVersion = getBunVersion();
-  if (!bunVersion) {
-    console.error("Error: Bun is required to run thinkwell scripts.");
-    console.error("");
-    console.error("The thinkwell runtime uses Bun for TypeScript execution and schema");
-    console.error("generation. This also enables features like compiled executables.");
-    console.error("");
-    console.error("To install Bun:");
-    console.error("  curl -fsSL https://bun.sh/install | bash");
-    console.error("");
-    console.error("Or via Homebrew:");
-    console.error("  brew install oven-sh/bun/bun");
-    console.error("");
-    console.error("For more information: https://bun.sh");
-    process.exit(1);
-  }
-
-  // Validate installation
-  validateInstallation();
-
   // Handle "types" subcommand
   if (args[0] === "types") {
-    const typesArgs = args.slice(1);
-    const typesCommandPath = getTypesCommandPath();
-    const bunArgs = [typesCommandPath, ...typesArgs];
-
-    const child = spawn("bun", bunArgs, {
-      stdio: "inherit",
-      env: process.env,
-    });
-
-    child.on("error", (err) => {
-      console.error(`Error: Failed to execute 'bun' command.`);
-      console.error(`  ${err.message}`);
-      if (err.code === "ENOENT") {
-        console.error("");
-        console.error("Bun was detected but cannot be executed.");
-        console.error("Ensure 'bun' is in your PATH and has execute permissions.");
-      }
-      process.exit(1);
-    });
-
-    child.on("exit", (code) => {
-      process.exit(code ?? 0);
-    });
-
+    await runTypesCommand(args.slice(1));
     return;
   }
 
+  // All script execution requires Node 24+ and proper installation
+  validateNodeVersion();
+  validateInstallation();
+
   // Handle "run" subcommand - just strip it
   const runArgs = args[0] === "run" ? args.slice(1) : args;
 
@@ -205,53 +357,24 @@ async function main() {
   if (runArgs.length === 0) {
     console.error("Error: No script provided.");
     console.error("");
-    console.error("Usage: thinkwell run <script.ts> [args...]");
+    console.error("Usage: thinkwell <script.ts> [args...]");
     process.exit(1);
   }
 
-  // Check if the script file exists
-  const scriptPath = runArgs[0];
-  if (!scriptPath.startsWith("-") && !existsSync(scriptPath)) {
-    // Try resolving relative to cwd
-    const resolvedPath = resolve(process.cwd(), scriptPath);
-    if (!existsSync(resolvedPath)) {
-      console.error(`Error: Script not found: ${scriptPath}`);
-      console.error("");
-      console.error("Make sure the file exists and the path is correct.");
-      process.exit(1);
-    }
-  }
-
-  // Delegate to bun with plugin preloaded
-  const pluginPath = getPluginPath();
-  const nodeModulesPath = getNodeModulesPath();
-  const bunArgs = ["--preload", pluginPath, ...runArgs];
+  // Register bundled modules before loading user scripts
+  await registerBundledModules();
 
-  // Add our node_modules to NODE_PATH so Bun can find thinkwell packages
-  // regardless of where the script is located
-  const nodePath = process.env.NODE_PATH
-    ? `${nodeModulesPath}:${process.env.NODE_PATH}`
-    : nodeModulesPath;
-
-  const child = spawn("bun", bunArgs, {
-    stdio: "inherit",
-    env: { ...process.env, NODE_PATH: nodePath },
-  });
-
-  child.on("error", (err) => {
-    console.error(`Error: Failed to execute 'bun' command.`);
-    console.error(`  ${err.message}`);
-    if (err.code === "ENOENT") {
-      console.error("");
-      console.error("Bun was detected but cannot be executed.");
-      console.error("Ensure 'bun' is in your PATH and has execute permissions.");
-    }
-    process.exit(1);
-  });
-
-  child.on("exit", (code) => {
-    process.exit(code ?? 0);
-  });
+  // Run the user script
+  const scriptPath = runArgs[0];
+  const scriptArgs = runArgs.slice(1);
+  await runUserScript(scriptPath, scriptArgs);
 }
 
-main();
+main().catch((error) => {
+  console.error("Unexpected error:");
+  console.error(`  ${error.message || error}`);
+  if (process.env.DEBUG) {
+    console.error(error.stack);
+  }
+  process.exit(1);
+});

package/dist/cli/loader.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Custom script loader for the pkg-compiled binary.
+ *
+ * This module provides the runtime infrastructure for loading and executing
+ * user scripts in the pkg binary. It handles:
+ *
+ * 1. **Module Resolution**: Routes imports to the appropriate source:
+ *    - `thinkwell:*` imports → bundled packages via `global.__bundled__`
+ *    - thinkwell packages → bundled packages via `global.__bundled__`
+ *    - External packages → user's node_modules via `require.resolve()`
+ *
+ * 2. **Import Transformation**: Rewrites user script imports before execution:
+ *    - `import { Agent } from "thinkwell:agent"` → bundled thinkwell
+ *    - `import { Agent } from "thinkwell"` → bundled thinkwell
+ *
+ * 3. **@JSONSchema Processing**: Generates JSON schemas for marked types and
+ *    injects namespace declarations with SchemaProvider implementations.
+ *
+ * 4. **Script Loading**: Uses Node's require() with temp files for transformed scripts
+ *
+ * Unlike the Bun plugin which runs at bundle time, this loader operates at
+ * runtime when the user script is executed.
+ */
+/**
+ * Global registry for bundled modules.
+ * This is populated by main-pkg.cjs before loading user scripts.
+ */
+declare global {
+    var __bundled__: Record<string, unknown> | undefined;
+}
+/**
+ * Initialize the bundled module registry.
+ *
+ * This should be called from main-pkg.cjs with the bundled package exports.
+ * The registry is used by createCustomRequire to route thinkwell imports.
+ *
+ * @param modules - Map of package names to their exports
+ */
+export declare function initializeBundledRegistry(modules: Record<string, unknown>): void;
+/**
+ * Strip shebang line from source if present.
+ *
+ * Shebangs are valid for executable scripts but not valid JS/TS syntax.
+ * We need to strip them before Module._compile processes the source.
+ *
+ * @param source - The script source code
+ * @returns Tuple of [shebang line or empty string, rest of source]
+ */
+export declare function extractShebang(source: string): [string, string];
+/**
+ * Transform thinkwell:* imports to use bundled packages.
+ *
+ * Rewrites import specifiers from the thinkwell:* URI scheme to
+ * their corresponding npm package names.
+ *
+ * @example
+ * ```typescript
+ * // Input:
+ * import { Agent } from "thinkwell:agent";
+ *
+ * // Output:
+ * import { Agent } from "thinkwell";
+ * ```
+ *
+ * @param source - The script source code
+ * @returns The source with thinkwell:* imports rewritten
+ */
+export declare function rewriteThinkwellImports(source: string): string;
+/**
+ * Transform imports to use the bundled module registry.
+ *
+ * In the pkg binary, we can't rely on Node's normal module resolution
+ * for bundled packages (they're in the /snapshot/ virtual filesystem).
+ * This transform rewrites imports to use global.__bundled__ directly.
+ *
+ * @example
+ * ```typescript
+ * // Input:
+ * import { Agent } from "thinkwell";
+ *
+ * // Output:
+ * const { Agent } = global.__bundled__["thinkwell"];
+ * ```
+ *
+ * @param source - The script source code
+ * @returns The source with bundled package imports transformed
+ */
+export declare function transformVirtualImports(source: string): string;
+/**
+ * Create a custom require function that routes imports appropriately.
+ *
+ * This function creates a require implementation that:
+ * 1. Checks bundled modules first (thinkwell packages)
+ * 2. Falls back to require.resolve from the script's directory
+ * 3. Falls back to global require for built-in modules
+ *
+ * @param scriptPath - Absolute path to the user script
+ * @returns A require function bound to the script's directory
+ */
+export declare function createCustomRequire(scriptPath: string): NodeJS.Require;
+/**
+ * Load and execute a user script with custom module resolution.
+ *
+ * This function handles two loading strategies:
+ *
+ * 1. **Direct require()** - For scripts that don't use thinkwell imports.
+ *    This leverages Node's --experimental-strip-types for TypeScript support.
+ *
+ * 2. **Transform and compile** - For scripts that use thinkwell:* imports
+ *    or import from bundled packages. The script is transformed and written
+ *    to a temp file, then required (which applies type stripping).
+ *
+ * @param scriptPath - Absolute path to the script to load
+ * @returns The module exports from the script
+ * @throws Error if the script cannot be loaded or executed
+ */
+export declare function loadScript(scriptPath: string): unknown;
+/**
+ * Load and execute a user script, handling both sync and async exports.
+ *
+ * After loading, this function checks if the script exports a main function
+ * or default export and executes it if present.
+ *
+ * @param scriptPath - Absolute path to the script to load
+ * @param args - Additional arguments to pass to the script's argv
+ * @returns Promise that resolves when script execution completes
+ */
+export declare function runScript(scriptPath: string, args?: string[]): Promise<void>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/cli/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/cli/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAqCH;;;GAGG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AASD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAS/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgB9D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqC9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,OAAO,CAqDhB;AAuDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAgEtD;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,EAAO,GAClB,OAAO,CAAC,IAAI,CAAC,CAyCf"}