thinkwell 0.4.0 → 0.4.1

package/dist/cli/build.js

@@ -0,0 +1,954 @@
+/**
+ * Build command for creating self-contained executables from user scripts.
+ *
+ * This module provides the `thinkwell build` command that compiles user scripts
+ * into standalone binaries using the same pkg-based tooling as the thinkwell CLI.
+ *
+ * The build process follows a two-stage pipeline:
+ * 1. **Pre-bundle with esbuild** - Bundle user script + thinkwell packages into CJS
+ * 2. **Compile with pkg** - Create self-contained binary with Node.js runtime
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, copyFileSync, chmodSync, createWriteStream, } from "node:fs";
+import { dirname, resolve, basename, join, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { styleText } from "node:util";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { spawn, execSync } from "node:child_process";
+import ora from "ora";
+import * as esbuild from "esbuild";
+// Handle both ESM and CJS contexts for __dirname
+// When bundled to CJS, import.meta.url won't work, but global __dirname will
+const __dirname = typeof import.meta?.url === "string"
+    ? dirname(fileURLToPath(import.meta.url))
+    : globalThis.__dirname || dirname(process.argv[1]);
+// Map user-friendly target names to pkg target names
+const TARGET_MAP = {
+    "darwin-arm64": "node24-macos-arm64",
+    "darwin-x64": "node24-macos-x64",
+    "linux-x64": "node24-linux-x64",
+    "linux-arm64": "node24-linux-arm64",
+};
+// Detect the current host platform
+function detectHostTarget() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "darwin" && arch === "arm64")
+        return "darwin-arm64";
+    if (platform === "darwin" && arch === "x64")
+        return "darwin-x64";
+    if (platform === "linux" && arch === "x64")
+        return "linux-x64";
+    if (platform === "linux" && arch === "arm64")
+        return "linux-arm64";
+    throw new Error(`Unsupported platform: ${platform}-${arch}. ` +
+        `Supported platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64`);
+}
+/**
+ * Parse and validate build options from command-line arguments.
+ */
+export function parseBuildArgs(args) {
+    const options = {
+        entry: "",
+        targets: [],
+        include: [],
+    };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "-o" || arg === "--output") {
+            i++;
+            if (i >= args.length) {
+                throw new Error("Missing value for --output");
+            }
+            options.output = args[i];
+        }
+        else if (arg === "-t" || arg === "--target") {
+            i++;
+            if (i >= args.length) {
+                throw new Error("Missing value for --target");
+            }
+            const target = args[i];
+            const validTargets = ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64", "host"];
+            if (!validTargets.includes(target)) {
+                throw new Error(`Invalid target '${target}'. Valid targets: ${validTargets.join(", ")}`);
+            }
+            options.targets.push(target);
+        }
+        else if (arg === "--include") {
+            i++;
+            if (i >= args.length) {
+                throw new Error("Missing value for --include");
+            }
+            options.include.push(args[i]);
+        }
+        else if (arg === "--verbose" || arg === "-v") {
+            options.verbose = true;
+        }
+        else if (arg === "--quiet" || arg === "-q") {
+            options.quiet = true;
+        }
+        else if (arg === "--dry-run" || arg === "-n") {
+            options.dryRun = true;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        else {
+            // Positional argument - entry file
+            if (options.entry) {
+                throw new Error(`Unexpected argument: ${arg}`);
+            }
+            options.entry = arg;
+        }
+        i++;
+    }
+    // Validate entry
+    if (!options.entry) {
+        throw new Error("No entry file specified");
+    }
+    // Default target is host
+    if (options.targets.length === 0) {
+        options.targets = ["host"];
+    }
+    return options;
+}
+/**
+ * Initialize the build context with resolved paths and validated inputs.
+ */
+function initBuildContext(options) {
+    // Resolve entry path
+    const entryPath = isAbsolute(options.entry)
+        ? options.entry
+        : resolve(process.cwd(), options.entry);
+    if (!existsSync(entryPath)) {
+        const suggestion = options.entry.endsWith(".ts") || options.entry.endsWith(".js")
+            ? ""
+            : "\n  Did you mean to add a .ts or .js extension?";
+        throw new Error(`Entry file not found: ${options.entry}${suggestion}\n` +
+            `  Working directory: ${process.cwd()}`);
+    }
+    const entryBasename = basename(entryPath).replace(/\.(ts|js|mts|mjs|cts|cjs)$/, "");
+    const entryDir = dirname(entryPath);
+    // Create build directory in the entry file's directory
+    const buildDir = join(entryDir, ".thinkwell-build");
+    // Find the thinkwell dist-pkg directory
+    // When running from npm install: node_modules/thinkwell/dist-pkg
+    // When running from source: packages/thinkwell/dist-pkg
+    const thinkwellDistPkg = resolve(__dirname, "../../dist-pkg");
+    if (!existsSync(thinkwellDistPkg)) {
+        throw new Error(`Thinkwell dist-pkg not found at ${thinkwellDistPkg}.\n` +
+            `  This may indicate a corrupted installation.\n` +
+            `  Try reinstalling thinkwell: npm install thinkwell`);
+    }
+    // Resolve "host" targets to actual platform
+    const resolvedTargets = options.targets.map((t) => t === "host" ? detectHostTarget() : t);
+    // Deduplicate targets
+    const uniqueTargets = [...new Set(resolvedTargets)];
+    return {
+        entryPath,
+        entryBasename,
+        entryDir,
+        buildDir,
+        thinkwellDistPkg,
+        resolvedTargets: uniqueTargets,
+        options,
+    };
+}
+/**
+ * Generate the output path for a given target.
+ */
+function getOutputPath(ctx, target) {
+    if (ctx.options.output) {
+        if (ctx.resolvedTargets.length === 1) {
+            // Single target: use exact output path
+            return isAbsolute(ctx.options.output)
+                ? ctx.options.output
+                : resolve(process.cwd(), ctx.options.output);
+        }
+        else {
+            // Multiple targets: append target suffix
+            const base = isAbsolute(ctx.options.output)
+                ? ctx.options.output
+                : resolve(process.cwd(), ctx.options.output);
+            return `${base}-${target}`;
+        }
+    }
+    else {
+        // Default: <entry-basename>-<target> in current directory
+        return resolve(process.cwd(), `${ctx.entryBasename}-${target}`);
+    }
+}
+/**
+ * Generate the wrapper entry point that sets up global.__bundled__.
+ *
+ * This creates a CJS file that:
+ * 1. Loads the pre-bundled thinkwell packages
+ * 2. Registers them in global.__bundled__
+ * 3. Loads and runs the user's bundled code
+ */
+function generateWrapperSource(userBundlePath) {
+    return `#!/usr/bin/env node
+/**
+ * Generated wrapper for thinkwell build.
+ * This file is auto-generated - do not edit.
+ */
+
+// Register bundled thinkwell packages
+const thinkwell = require('./thinkwell.cjs');
+const acpModule = require('./acp.cjs');
+const protocolModule = require('./protocol.cjs');
+
+global.__bundled__ = {
+  'thinkwell': thinkwell,
+  '@thinkwell/acp': acpModule,
+  '@thinkwell/protocol': protocolModule,
+};
+
+// Load the user's bundled code
+require('./${basename(userBundlePath)}');
+`;
+}
+/**
+ * Stage 1: Bundle user script with esbuild.
+ *
+ * This bundles the user's entry point along with all its dependencies
+ * into a single CJS file. The thinkwell packages are marked as external
+ * since they'll be provided via global.__bundled__.
+ */
+async function bundleUserScript(ctx) {
+    const outputFile = join(ctx.buildDir, `${ctx.entryBasename}-bundle.cjs`);
+    if (ctx.options.verbose) {
+        console.log(`  Bundling ${ctx.entryPath}...`);
+    }
+    // Note: When running from a compiled binary, ESBUILD_BINARY_PATH is set
+    // by main-pkg.cjs before this module loads.
+    try {
+        await esbuild.build({
+            entryPoints: [ctx.entryPath],
+            bundle: true,
+            platform: "node",
+            format: "cjs",
+            outfile: outputFile,
+            // External: Node built-ins
+            external: ["node:*"],
+            // Mark thinkwell packages as external - they're provided via global.__bundled__
+            // But actually, we need to transform the imports, so let's bundle them
+            // and use a banner to set up the module aliases
+            banner: {
+                js: `
+// Alias thinkwell packages to global.__bundled__
+const __origRequire = require;
+require = function(id) {
+  if (id === 'thinkwell' || id === 'thinkwell:agent' || id === 'thinkwell:connectors') {
+    return global.__bundled__['thinkwell'];
+  }
+  if (id === '@thinkwell/acp' || id === 'thinkwell:acp') {
+    return global.__bundled__['@thinkwell/acp'];
+  }
+  if (id === '@thinkwell/protocol' || id === 'thinkwell:protocol') {
+    return global.__bundled__['@thinkwell/protocol'];
+  }
+  return __origRequire(id);
+};
+require.resolve = __origRequire.resolve;
+require.cache = __origRequire.cache;
+require.extensions = __origRequire.extensions;
+require.main = __origRequire.main;
+`,
+            },
+            // Resolve thinkwell imports to bundled versions during bundle time
+            plugins: [
+                {
+                    name: "thinkwell-resolver",
+                    setup(build) {
+                        // Resolve thinkwell:* imports to the npm package
+                        build.onResolve({ filter: /^thinkwell:/ }, (args) => {
+                            const moduleName = args.path.replace("thinkwell:", "");
+                            const moduleMap = {
+                                agent: "thinkwell",
+                                acp: "@thinkwell/acp",
+                                protocol: "@thinkwell/protocol",
+                                connectors: "thinkwell",
+                            };
+                            const resolved = moduleMap[moduleName];
+                            if (resolved) {
+                                // Mark as external - will be provided by global.__bundled__ at runtime
+                                return { path: resolved, external: true };
+                            }
+                            return null;
+                        });
+                        // Mark thinkwell packages as external
+                        build.onResolve({ filter: /^(thinkwell|@thinkwell\/(acp|protocol))$/ }, (args) => {
+                            return { path: args.path, external: true };
+                        });
+                    },
+                },
+            ],
+            sourcemap: false,
+            minify: false,
+            keepNames: true,
+            target: "node24",
+            logLevel: ctx.options.verbose ? "info" : "silent",
+        });
+    }
+    catch (error) {
+        // Provide helpful error messages for common failures
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("Could not resolve")) {
+            const match = message.match(/Could not resolve "([^"]+)"/);
+            const moduleName = match ? match[1] : "unknown module";
+            throw new Error(`Could not resolve dependency "${moduleName}".\n` +
+                `  Make sure all dependencies are installed: npm install\n` +
+                `  If this is a dev dependency, it may need to be a regular dependency.`);
+        }
+        if (message.includes("No loader is configured")) {
+            throw new Error(`Unsupported file type in import.\n` +
+                `  esbuild cannot bundle this file type by default.\n` +
+                `  Consider using --include to embed the file as an asset instead.`);
+        }
+        throw error;
+    }
+    return outputFile;
+}
+/**
+ * Copy thinkwell pre-bundled packages to build directory.
+ */
+function copyThinkwellBundles(ctx) {
+    const bundles = ["thinkwell.cjs", "acp.cjs", "protocol.cjs"];
+    for (const bundle of bundles) {
+        const src = join(ctx.thinkwellDistPkg, bundle);
+        const dest = join(ctx.buildDir, bundle);
+        if (!existsSync(src)) {
+            throw new Error(`Thinkwell bundle not found: ${src}`);
+        }
+        const content = readFileSync(src);
+        writeFileSync(dest, content);
+        if (ctx.options.verbose) {
+            console.log(`  Copied ${bundle}`);
+        }
+    }
+}
+/**
+ * Check if running from a pkg-compiled binary.
+ */
+function isRunningFromCompiledBinary() {
+    // @ts-expect-error process.pkg is set by pkg at runtime
+    return typeof process.pkg !== "undefined";
+}
+// ============================================================================
+// Portable Node.js Download (for compiled binary builds)
+// ============================================================================
+/** Pinned Node.js version for portable runtime */
+const PORTABLE_NODE_VERSION = "24.1.0";
+/** Get the thinkwell cache directory */
+function getCacheDir() {
+    return process.env.THINKWELL_CACHE_DIR || join(homedir(), ".cache", "thinkwell");
+}
+/** Get the thinkwell version from package.json */
+function getThinkwellVersion() {
+    try {
+        const pkgPath = resolve(__dirname, "../../package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Map process.platform/arch to Node.js download format.
+ */
+function getNodePlatformArch() {
+    const platform = process.platform === "darwin" ? "darwin" : "linux";
+    const arch = process.arch; // x64 or arm64
+    return { platform, arch };
+}
+/**
+ * Download a file from a URL with progress reporting.
+ */
+async function downloadFile(url, destPath, spinner) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+    }
+    const contentLength = response.headers.get("content-length");
+    const totalBytes = contentLength ? parseInt(contentLength, 10) : 0;
+    // Ensure directory exists
+    mkdirSync(dirname(destPath), { recursive: true });
+    const fileStream = createWriteStream(destPath);
+    const reader = response.body?.getReader();
+    if (!reader) {
+        throw new Error("No response body");
+    }
+    let downloadedBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            fileStream.write(Buffer.from(value));
+            downloadedBytes += value.length;
+            if (spinner && totalBytes > 0) {
+                const percent = Math.round((downloadedBytes / totalBytes) * 100);
+                const downloadedMB = (downloadedBytes / 1024 / 1024).toFixed(1);
+                const totalMB = (totalBytes / 1024 / 1024).toFixed(1);
+                spinner.text = `Downloading Node.js runtime... ${downloadedMB} MB / ${totalMB} MB (${percent}%)`;
+            }
+        }
+    }
+    finally {
+        fileStream.end();
+    }
+    // Wait for file to be fully written
+    await new Promise((resolve, reject) => {
+        fileStream.on("finish", resolve);
+        fileStream.on("error", reject);
+    });
+}
+/**
+ * Compute SHA-256 hash of a file.
+ */
+function hashFile(filePath) {
+    const content = readFileSync(filePath);
+    return createHash("sha256").update(content).digest("hex");
+}
+/**
+ * Fetch the expected SHA-256 checksum for a Node.js download.
+ */
+async function fetchExpectedChecksum(version, filename) {
+    const url = `https://nodejs.org/dist/v${version}/SHASUMS256.txt`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch checksums: ${response.status}`);
+    }
+    const text = await response.text();
+    for (const line of text.split("\n")) {
+        // Format: "hash  filename"
+        const parts = line.trim().split(/\s+/);
+        if (parts.length === 2 && parts[1] === filename) {
+            return parts[0];
+        }
+    }
+    throw new Error(`Checksum not found for ${filename}`);
+}
+/**
+ * Extract a .tar.gz archive using the system tar command.
+ */
+function extractTarGz(archivePath, destDir) {
+    execSync(`tar -xzf "${archivePath}" -C "${destDir}"`, {
+        stdio: "pipe",
+    });
+}
+/**
+ * Ensure portable Node.js is available in the cache.
+ *
+ * Downloads from nodejs.org if not cached, verifies checksum, and extracts.
+ * Returns the path to the node binary.
+ */
+async function ensurePortableNode(spinner) {
+    const version = PORTABLE_NODE_VERSION;
+    const { platform, arch } = getNodePlatformArch();
+    const cacheDir = join(getCacheDir(), "node", `v${version}`);
+    const nodeBinary = process.platform === "win32" ? "node.exe" : "node";
+    const nodePath = join(cacheDir, nodeBinary);
+    // Check if already cached
+    if (existsSync(nodePath)) {
+        return nodePath;
+    }
+    const filename = `node-v${version}-${platform}-${arch}.tar.gz`;
+    const url = `https://nodejs.org/dist/v${version}/${filename}`;
+    const archivePath = join(cacheDir, filename);
+    spinner?.start("Downloading Node.js runtime (first time only)...");
+    try {
+        // Ensure cache directory exists
+        mkdirSync(cacheDir, { recursive: true });
+        // Download
+        await downloadFile(url, archivePath, spinner);
+        // Verify checksum
+        spinner?.start("Verifying download integrity...");
+        const expectedHash = await fetchExpectedChecksum(version, filename);
+        const actualHash = hashFile(archivePath);
+        if (actualHash !== expectedHash) {
+            // Clean up the corrupted download
+            rmSync(archivePath, { force: true });
+            throw new Error(`Node.js download verification failed.\n\n` +
+                `  Expected: ${expectedHash}\n` +
+                `  Actual:   ${actualHash}\n\n` +
+                `This may indicate a corrupted download or network interference.\n` +
+                `Please retry or report this issue.`);
+        }
+        // Extract
+        spinner?.start("Extracting Node.js...");
+        extractTarGz(archivePath, cacheDir);
+        // Move node binary to cache root
+        // The tarball extracts to node-v{version}-{platform}-{arch}/bin/node
+        const extractedDir = join(cacheDir, `node-v${version}-${platform}-${arch}`);
+        const extractedBin = join(extractedDir, "bin", nodeBinary);
+        copyFileSync(extractedBin, nodePath);
+        chmodSync(nodePath, 0o755);
+        // Cleanup: remove extracted directory and archive
+        rmSync(extractedDir, { recursive: true, force: true });
+        rmSync(archivePath, { force: true });
+        spinner?.succeed(`Node.js v${version} cached to ${cacheDir}`);
+        return nodePath;
+    }
+    catch (error) {
+        // Cleanup on error
+        rmSync(cacheDir, { recursive: true, force: true });
+        const message = error instanceof Error ? error.message : String(error);
+        // Provide helpful error messages
+        if (message.includes("ETIMEDOUT") || message.includes("ENOTFOUND")) {
+            throw new Error(`Failed to download Node.js runtime.\n\n` +
+                `  URL: ${url}\n` +
+                `  Error: ${message}\n\n` +
+                `Check your network connection and try again.\n` +
+                `If behind a proxy, set HTTPS_PROXY environment variable.`);
+        }
+        throw error;
+    }
+}
+/**
+ * Ensure the pkg CLI bundle and its auxiliary files are extracted from the
+ * compiled binary's assets.
+ *
+ * pkg requires several auxiliary files at runtime:
+ * - pkg-cli.cjs - The main bundled CLI
+ * - package.json - pkg's version info (read as ../package.json from cacheDir)
+ * - pkg-prelude/ - JavaScript files injected into compiled binaries
+ * - pkg-dictionary/ - Compression dictionaries for bytecode
+ * - pkg-common.cjs - Common utilities
+ *
+ * Returns the path to the extracted pkg-cli.cjs file.
+ */
+function ensurePkgCli() {
+    const version = getThinkwellVersion();
+    const pkgCliBaseDir = join(getCacheDir(), "pkg-cli");
+    const cacheDir = join(pkgCliBaseDir, version);
+    const pkgCliPath = join(cacheDir, "pkg-cli.cjs");
+    // Check if already cached (check for main file and a prelude file)
+    const preludeCheck = join(cacheDir, "pkg-prelude", "bootstrap.js");
+    if (existsSync(pkgCliPath) && existsSync(preludeCheck)) {
+        return pkgCliPath;
+    }
+    // Base path for pkg assets in the compiled binary's snapshot
+    const distPkgPath = resolve(__dirname, "../../dist-pkg");
+    // Extract main CLI bundle
+    const cliSrc = join(distPkgPath, "pkg-cli.cjs");
+    if (!existsSync(cliSrc)) {
+        throw new Error(`pkg CLI not found in compiled binary assets.\n` +
+            `  Expected at: ${cliSrc}\n\n` +
+            `This may indicate a build issue. Please report this.`);
+    }
+    mkdirSync(cacheDir, { recursive: true });
+    copyFileSync(cliSrc, pkgCliPath);
+    // Extract pkg's package.json (for version info)
+    // pkg reads ../package.json relative to __dirname (which is cacheDir)
+    // So we place it in the parent directory (pkgCliBaseDir)
+    const pkgJsonSrc = join(distPkgPath, "package.json");
+    if (existsSync(pkgJsonSrc)) {
+        copyFileSync(pkgJsonSrc, join(pkgCliBaseDir, "package.json"));
+    }
+    // Extract prelude files
+    const preludeDir = join(cacheDir, "pkg-prelude");
+    mkdirSync(preludeDir, { recursive: true });
+    for (const file of ["bootstrap.js", "diagnostic.js"]) {
+        const src = join(distPkgPath, "pkg-prelude", file);
+        if (existsSync(src)) {
+            copyFileSync(src, join(preludeDir, file));
+        }
+    }
+    // Extract common.js
+    const commonSrc = join(distPkgPath, "pkg-common.cjs");
+    if (existsSync(commonSrc)) {
+        copyFileSync(commonSrc, join(cacheDir, "pkg-common.cjs"));
+    }
+    // Extract dictionary files
+    // pkg reads ../dictionary relative to __dirname (which is cacheDir)
+    // So we place it in the parent directory (pkgCliBaseDir/dictionary/)
+    const dictionaryDir = join(pkgCliBaseDir, "dictionary");
+    mkdirSync(dictionaryDir, { recursive: true });
+    for (const file of ["v8-7.8.js", "v8-8.4.js", "v8-12.4.js"]) {
+        const src = join(distPkgPath, "pkg-dictionary", file);
+        if (existsSync(src)) {
+            copyFileSync(src, join(dictionaryDir, file));
+        }
+    }
+    return pkgCliPath;
+}
+/**
+ * Spawn a subprocess and wait for completion.
+ */
+function spawnAsync(command, args, options = {}) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env || process.env,
+            stdio: options.verbose ? "inherit" : "pipe",
+        });
+        let stdout = "";
+        let stderr = "";
+        if (!options.verbose) {
+            proc.stdout?.on("data", (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on("data", (data) => {
+                stderr += data.toString();
+            });
+        }
+        proc.on("close", (code) => {
+            resolve({
+                exitCode: code ?? 1,
+                stdout,
+                stderr,
+            });
+        });
+        proc.on("error", (error) => {
+            resolve({
+                exitCode: 1,
+                stdout,
+                stderr: error.message,
+            });
+        });
+    });
+}
+/**
+ * Compile using pkg via subprocess (for compiled binary environment).
+ *
+ * This function is called when running from a compiled thinkwell binary.
+ * It downloads a portable Node.js runtime and uses the bundled pkg CLI
+ * to perform the compilation as a subprocess.
+ */
+async function compileWithPkgSubprocess(ctx, wrapperPath, target, outputPath, spinner) {
+    // Ensure portable Node.js is available
+    const nodePath = await ensurePortableNode(spinner);
+    // Extract pkg CLI from snapshot
+    const pkgCliPath = ensurePkgCli();
+    const pkgTarget = TARGET_MAP[target];
+    // Ensure output directory exists
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    // Build pkg CLI arguments
+    const args = [
+        pkgCliPath,
+        wrapperPath,
+        "--targets",
+        pkgTarget,
+        "--output",
+        outputPath,
+        "--options",
+        "experimental-transform-types,disable-warning=ExperimentalWarning",
+        "--public",
+    ];
+    // Add assets if specified
+    if (ctx.options.include && ctx.options.include.length > 0) {
+        for (const pattern of ctx.options.include) {
+            args.push("--assets", pattern);
+        }
+    }
+    spinner?.start(`Compiling for ${target}...`);
+    const result = await spawnAsync(nodePath, args, {
+        cwd: ctx.buildDir,
+        env: {
+            ...process.env,
+            // Set pkg cache path for pkg-fetch downloads
+            PKG_CACHE_PATH: join(getCacheDir(), "pkg-cache"),
+        },
+        verbose: ctx.options.verbose,
+    });
+    if (result.exitCode !== 0) {
+        const errorOutput = result.stderr || result.stdout;
+        throw new Error(`pkg compilation failed for ${target}.\n\n` +
+            `Exit code: ${result.exitCode}\n` +
+            (errorOutput ? `Output:\n${errorOutput}` : ""));
+    }
+}
+/**
+ * Stage 2: Compile with pkg.
+ *
+ * Uses @yao-pkg/pkg to create a self-contained binary.
+ *
+ * When running from a compiled thinkwell binary, this function uses a
+ * subprocess approach: downloading a portable Node.js runtime and executing
+ * the bundled pkg CLI as a child process. This works around pkg's dynamic
+ * import limitations in the virtual filesystem.
+ *
+ * When running from npm/source, this function uses @yao-pkg/pkg programmatically.
+ */
+async function compileWithPkg(ctx, wrapperPath, target, outputPath, spinner) {
+    // When running from a compiled binary, use subprocess approach
+    if (isRunningFromCompiledBinary()) {
+        await compileWithPkgSubprocess(ctx, wrapperPath, target, outputPath, spinner);
+        return;
+    }
+    // Normal path: use pkg programmatically
+    const { exec } = await import("@yao-pkg/pkg");
+    const pkgTarget = TARGET_MAP[target];
+    // Ensure output directory exists
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    // Build pkg configuration
+    const pkgConfig = [
+        wrapperPath,
+        "--targets",
+        pkgTarget,
+        "--output",
+        outputPath,
+        "--options",
+        "experimental-transform-types,disable-warning=ExperimentalWarning",
+        "--public", // Include source instead of bytecode (required for cross-compilation)
+    ];
+    // Add assets if specified
+    if (ctx.options.include && ctx.options.include.length > 0) {
+        for (const pattern of ctx.options.include) {
+            pkgConfig.push("--assets", pattern);
+        }
+    }
+    await exec(pkgConfig);
+}
+// ============================================================================
+// Top-Level Await Detection
+// ============================================================================
+/**
+ * Detect top-level await usage in the entry file.
+ * Returns an array of line numbers where top-level await is found.
+ */
+function detectTopLevelAwait(filePath) {
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n");
+    const awaits = [];
+    // Track nesting depth of functions/classes
+    let depth = 0;
+    let inMultiLineComment = false;
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i];
+        // Handle multi-line comments
+        if (inMultiLineComment) {
+            const endIdx = line.indexOf("*/");
+            if (endIdx !== -1) {
+                line = line.slice(endIdx + 2);
+                inMultiLineComment = false;
+            }
+            else {
+                continue;
+            }
+        }
+        // Remove single-line comments
+        const singleLineCommentIdx = line.indexOf("//");
+        if (singleLineCommentIdx !== -1) {
+            line = line.slice(0, singleLineCommentIdx);
+        }
+        // Handle multi-line comment start
+        const multiLineStart = line.indexOf("/*");
+        if (multiLineStart !== -1) {
+            const multiLineEnd = line.indexOf("*/", multiLineStart);
+            if (multiLineEnd !== -1) {
+                line = line.slice(0, multiLineStart) + line.slice(multiLineEnd + 2);
+            }
+            else {
+                line = line.slice(0, multiLineStart);
+                inMultiLineComment = true;
+            }
+        }
+        // Count function/class/arrow function depth changes
+        // This is a simplified heuristic - not a full parser
+        const openBraces = (line.match(/\{/g) || []).length;
+        const closeBraces = (line.match(/\}/g) || []).length;
+        // Check for function/class/arrow declarations that increase depth
+        if (/\b(function|class|async\s+function)\b/.test(line) && line.includes("{")) {
+            depth += 1;
+        }
+        else if (/=>\s*\{/.test(line)) {
+            depth += 1;
+        }
+        // Adjust depth for brace changes (simplified)
+        depth += openBraces - closeBraces;
+        if (depth < 0)
+            depth = 0;
+        // Check for await at top level (depth 0)
+        if (depth === 0 && /\bawait\b/.test(line)) {
+            // Make sure it's not inside a string
+            const withoutStrings = line.replace(/(["'`])(?:(?!\1)[^\\]|\\.)*\1/g, "");
+            if (/\bawait\b/.test(withoutStrings)) {
+                awaits.push(i + 1); // 1-indexed line numbers
+            }
+        }
+    }
+    return awaits;
+}
+// ============================================================================
+// Output Helpers
+// ============================================================================
+/** Log output respecting quiet mode */
+function log(ctx, message) {
+    if (!ctx.options.quiet) {
+        console.log(message);
+    }
+}
+/** Create a spinner respecting quiet mode */
+function createSpinner(ctx, text) {
+    return ora({
+        text,
+        isSilent: ctx.options.quiet,
+    });
+}
+/**
+ * Run a dry-run build that shows what would be built without actually building.
+ */
+function runDryRun(ctx) {
+    console.log(styleText("bold", "Dry run mode - no files will be created\n"));
+    console.log(styleText("bold", "Entry point:"));
+    console.log(`  ${ctx.entryPath}\n`);
+    console.log(styleText("bold", "Targets:"));
+    for (const target of ctx.resolvedTargets) {
+        const outputPath = getOutputPath(ctx, target);
+        console.log(`  ${target} → ${outputPath}`);
+    }
+    console.log();
+    if (ctx.options.include && ctx.options.include.length > 0) {
+        console.log(styleText("bold", "Assets to include:"));
+        for (const pattern of ctx.options.include) {
+            console.log(`  ${pattern}`);
+        }
+        console.log();
+    }
+    console.log(styleText("bold", "Build steps:"));
+    console.log("  1. Bundle user script with esbuild");
+    console.log("  2. Copy thinkwell packages");
+    console.log("  3. Generate wrapper entry point");
+    console.log(`  4. Compile with pkg for ${ctx.resolvedTargets.length} target(s)`);
+    console.log();
+    // Check for potential issues
+    const topLevelAwaits = detectTopLevelAwait(ctx.entryPath);
+    if (topLevelAwaits.length > 0) {
+        console.log(styleText("yellow", "Warning: Top-level await detected"));
+        console.log("  Top-level await is not supported in compiled binaries.");
+        console.log(`  Found at line(s): ${topLevelAwaits.join(", ")}`);
+        console.log("  Wrap async code in an async main() function instead.\n");
+    }
+    console.log(styleText("dim", "Run without --dry-run to build."));
+}
+/**
+ * Main build function.
+ */
+export async function runBuild(options) {
+    const ctx = initBuildContext(options);
+    // Check for top-level await and warn
+    const topLevelAwaits = detectTopLevelAwait(ctx.entryPath);
+    if (topLevelAwaits.length > 0) {
+        console.log(styleText("yellow", "Warning: Top-level await detected"));
+        console.log("  Top-level await is not supported in compiled binaries.");
+        console.log(`  Found at line(s): ${topLevelAwaits.join(", ")}`);
+        console.log("  Wrap async code in an async main() function instead.\n");
+    }
+    // Handle dry-run mode
+    if (options.dryRun) {
+        runDryRun(ctx);
+        return;
+    }
+    log(ctx, `Building ${styleText("bold", ctx.entryBasename)}...\n`);
+    // Create build directory
+    if (existsSync(ctx.buildDir)) {
+        rmSync(ctx.buildDir, { recursive: true });
+    }
+    mkdirSync(ctx.buildDir, { recursive: true });
+    try {
+        // Stage 1: Bundle user script
+        let spinner = createSpinner(ctx, "Bundling with esbuild...");
+        spinner.start();
+        const userBundlePath = await bundleUserScript(ctx);
+        spinner.succeed("User script bundled");
+        // Stage 2: Copy thinkwell bundles
+        spinner = createSpinner(ctx, "Preparing thinkwell packages...");
+        spinner.start();
+        copyThinkwellBundles(ctx);
+        spinner.succeed("Thinkwell packages ready");
+        // Generate wrapper
+        const wrapperPath = join(ctx.buildDir, "wrapper.cjs");
+        const wrapperSource = generateWrapperSource(userBundlePath);
+        writeFileSync(wrapperPath, wrapperSource);
+        if (ctx.options.verbose) {
+            log(ctx, "  Generated wrapper entry point");
+        }
+        // Stage 3: Compile with pkg for each target
+        const outputs = [];
+        for (const target of ctx.resolvedTargets) {
+            const outputPath = getOutputPath(ctx, target);
+            spinner = createSpinner(ctx, `Compiling for ${target}...`);
+            spinner.start();
+            await compileWithPkg(ctx, wrapperPath, target, outputPath, spinner);
+            outputs.push(outputPath);
+            spinner.succeed(`Built ${basename(outputPath)}`);
+        }
+        log(ctx, "");
+        log(ctx, styleText("green", "Build complete!"));
+        log(ctx, "");
+        log(ctx, styleText("bold", "Output:"));
+        for (const output of outputs) {
+            log(ctx, `  ${output}`);
+        }
+    }
+    finally {
+        // Clean up build directory
+        if (!ctx.options.verbose) {
+            try {
+                rmSync(ctx.buildDir, { recursive: true });
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+        else {
+            log(ctx, `\nBuild artifacts preserved in: ${ctx.buildDir}`);
+        }
+    }
+}
+/**
+ * Show help for the build command.
+ */
+export function showBuildHelp() {
+    console.log(`
+thinkwell build - Compile TypeScript scripts into standalone executables
+
+Usage:
+  thinkwell build [options] <entry>
+
+Arguments:
+  entry                  TypeScript or JavaScript entry point
+
+Options:
+  -o, --output <path>    Output file path (default: ./<name>-<target>)
+  -t, --target <target>  Target platform (can be specified multiple times)
+  --include <glob>       Additional files to embed as assets
+  -n, --dry-run          Show what would be built without building
+  -q, --quiet            Suppress all output except errors (for CI)
+  -v, --verbose          Show detailed build output
+  -h, --help             Show this help message
+
+Targets:
+  host                   Current platform (default)
+  darwin-arm64           macOS on Apple Silicon
+  darwin-x64             macOS on Intel
+  linux-x64              Linux on x64
+  linux-arm64            Linux on ARM64
+
+Examples:
+  thinkwell build src/agent.ts                     Build for current platform
+  thinkwell build src/agent.ts -o dist/my-agent    Specify output path
+  thinkwell build src/agent.ts --target linux-x64  Build for Linux
+  thinkwell build src/agent.ts -t darwin-arm64 -t linux-x64  Multi-platform
+  thinkwell build src/agent.ts --dry-run           Preview build without executing
+
+The resulting binary is self-contained and includes:
+  - Node.js 24 runtime with TypeScript support
+  - All thinkwell packages
+  - Your bundled application code
+
+Note: Binaries are ~70-90 MB due to the embedded Node.js runtime.
+`);
+}
+//# sourceMappingURL=build.js.map