@whatalo/cli-kit 1.0.2 → 1.1.1

package/dist/bundle/index.cjs

@@ -0,0 +1,438 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bundle/index.ts
+var bundle_exports = {};
+__export(bundle_exports, {
+  BundleBuilder: () => BundleBuilder,
+  BundleUploader: () => BundleUploader,
+  BundleWatcher: () => BundleWatcher,
+  formatSize: () => formatSize
+});
+module.exports = __toCommonJS(bundle_exports);
+
+// src/bundle/builder.ts
+var import_node_child_process = require("child_process");
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+var MAX_BUNDLE_SIZE_BYTES = 10 * 1024 * 1024;
+async function collectFiles(dir, rootDir) {
+  const entries = await (0, import_promises.readdir)(dir, { withFileTypes: true });
+  const results = [];
+  const resolvedRoot = import_node_path.default.resolve(rootDir);
+  for (const entry of entries) {
+    const absolutePath = import_node_path.default.join(dir, entry.name);
+    const resolvedPath = import_node_path.default.resolve(absolutePath);
+    if (!resolvedPath.startsWith(resolvedRoot)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const nested = await collectFiles(absolutePath, rootDir);
+      results.push(...nested);
+    } else if (entry.isFile()) {
+      const fileStat = await (0, import_promises.stat)(absolutePath);
+      const relativePath = import_node_path.default.relative(rootDir, absolutePath);
+      if (relativePath.startsWith("..")) continue;
+      results.push({
+        relativePath,
+        absolutePath,
+        size: fileStat.size
+      });
+    }
+  }
+  return results;
+}
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+var BundleBuilder = class {
+  /**
+   * Runs the user-defined build command and collects the output files.
+   *
+   * @param buildCommand - Command string from config (e.g. "pnpm build")
+   * @param outputDir    - Build output directory (relative or absolute)
+   * @param cwd          - Working directory for the command (defaults to process.cwd())
+   * @throws If the build exits with a non-zero code or if total size exceeds 10 MB
+   */
+  async build(buildCommand, outputDir, cwd = process.cwd()) {
+    const startTime = Date.now();
+    const parts = buildCommand.trim().split(/\s+/);
+    const [cmd, ...args] = parts;
+    if (!cmd) {
+      throw new Error("build_command is empty in whatalo.app.toml");
+    }
+    await this.runBuildProcess(cmd, args, cwd);
+    const absoluteOutputDir = import_node_path.default.isAbsolute(outputDir) ? outputDir : import_node_path.default.join(cwd, outputDir);
+    let files;
+    try {
+      files = await collectFiles(absoluteOutputDir, absoluteOutputDir);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Build output directory not found at "${absoluteOutputDir}": ${message}`
+      );
+    }
+    if (files.length === 0) {
+      throw new Error(
+        `Build output directory "${absoluteOutputDir}" is empty after build.`
+      );
+    }
+    await this.validateIndexHtmlForCdn(files);
+    const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+    if (totalSize > MAX_BUNDLE_SIZE_BYTES) {
+      throw new Error(
+        `Bundle size ${formatSize(totalSize)} exceeds the 10 MB limit. Reduce your build output or use --no-cdn to skip CDN upload.`
+      );
+    }
+    const duration = Date.now() - startTime;
+    return { files, totalSize, duration };
+  }
+  /**
+   * Ensures index.html uses relative asset URLs so bundles work under
+   * session-scoped CDN paths like /dev-bundles/{sessionId}/.
+   */
+  async validateIndexHtmlForCdn(files) {
+    const indexFile = files.find((file) => file.relativePath === "index.html");
+    if (!indexFile) {
+      return;
+    }
+    const html = await (0, import_promises.readFile)(indexFile.absolutePath, "utf-8");
+    const hasRootAbsoluteAssetRefs = /(?:src|href)=["']\/assets\//i.test(html) || /(?:src|href)=["']\/[a-z0-9._-]+\//i.test(html);
+    if (hasRootAbsoluteAssetRefs) {
+      throw new Error(
+        "Build output uses root-absolute asset paths in index.html. CDN dev bundles are served from a subpath, so assets must be relative. If you use Vite, set `base: './'` in vite.config.ts and rebuild."
+      );
+    }
+  }
+  /**
+   * Spawns the build process and waits for it to finish.
+   * Captures stderr for error reporting on non-zero exit.
+   */
+  runBuildProcess(cmd, args, cwd) {
+    return new Promise((resolve, reject) => {
+      const proc = (0, import_node_child_process.spawn)(cmd, args, {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        // Never use shell: true — avoids injection
+        shell: false
+      });
+      let stderr = "";
+      let stdout = "";
+      if (proc.stdout) {
+        proc.stdout.on("data", (chunk) => {
+          stdout += chunk.toString("utf-8");
+        });
+      }
+      if (proc.stderr) {
+        proc.stderr.on("data", (chunk) => {
+          stderr += chunk.toString("utf-8");
+        });
+      }
+      proc.on("error", (err) => {
+        reject(
+          new Error(
+            `Failed to start build command "${cmd}": ${err.message}. Is the command installed and in PATH?`
+          )
+        );
+      });
+      proc.on("close", (code) => {
+        if (code === 0) {
+          resolve();
+          return;
+        }
+        const output = (stderr || stdout).trim();
+        reject(
+          new Error(
+            `Build failed with exit code ${code ?? "unknown"}.` + (output ? `
+
+${output}` : "")
+          )
+        );
+      });
+    });
+  }
+};
+
+// src/bundle/uploader.ts
+var import_promises2 = require("fs/promises");
+var UPLOAD_TIMEOUT_MS = 6e4;
+var CONTENT_TYPE_MAP = {
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".cjs": "application/javascript",
+  ".ts": "application/javascript",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".eot": "application/vnd.ms-fontobject",
+  ".txt": "text/plain",
+  ".xml": "application/xml",
+  ".map": "application/json",
+  ".webmanifest": "application/manifest+json"
+};
+function getContentType(filePath) {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  return CONTENT_TYPE_MAP[ext] ?? "application/octet-stream";
+}
+var BundleUploader = class {
+  /**
+   * Requests presigned URLs and uploads all files to the CDN in parallel.
+   *
+   * @param apiClient - Authenticated API client instance
+   * @param sessionId - Development session ID (used in the API path)
+   * @param files     - List of files from BundleBuilder.build()
+   * @returns The public CDN base URL for the uploaded bundle
+   * @throws If the API request fails or if index.html upload fails
+   */
+  async upload(apiClient, sessionId, files) {
+    for (const f of files) {
+      if (f.relativePath.includes("..") || f.relativePath.startsWith("/")) {
+        throw new Error(`Invalid file path: ${f.relativePath}`);
+      }
+    }
+    const payload = {
+      files: files.map((f) => ({ path: f.relativePath, size: f.size }))
+    };
+    const { urls, publicBaseUrl } = await apiClient.post(
+      `/api/dev-sessions/${sessionId}/upload-urls`,
+      payload
+    );
+    const uploadPromises = files.map(
+      (file) => this.uploadSingleFile(file, urls[file.relativePath])
+    );
+    const results = await Promise.allSettled(uploadPromises);
+    const fileResults = results.map((result, index) => {
+      if (result.status === "fulfilled") {
+        return result.value;
+      }
+      const filePath = files[index]?.relativePath ?? `file[${index}]`;
+      return {
+        path: filePath,
+        success: false,
+        error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+      };
+    });
+    const failed = fileResults.filter((r) => !r.success);
+    const indexFailed = failed.some(
+      (r) => r.path === "index.html" || r.path.endsWith("/index.html")
+    );
+    if (indexFailed) {
+      const indexError = failed.find(
+        (r) => r.path === "index.html" || r.path.endsWith("/index.html")
+      );
+      throw new Error(
+        `Critical upload failure: index.html could not be uploaded. ${indexError?.error ?? ""}`
+      );
+    }
+    for (const failure of failed) {
+      void failure;
+    }
+    return publicBaseUrl;
+  }
+  /**
+   * Uploads a single file to its presigned URL via HTTP PUT.
+   * Sets Content-Type and Content-Length headers as required by S3/R2.
+   */
+  async uploadSingleFile(file, presignedUrl) {
+    if (!presignedUrl) {
+      return {
+        path: file.relativePath,
+        success: false,
+        error: "No presigned URL returned from API"
+      };
+    }
+    try {
+      const body = await (0, import_promises2.readFile)(file.absolutePath);
+      const contentType = getContentType(file.relativePath);
+      const response = await fetch(presignedUrl, {
+        method: "PUT",
+        headers: {
+          "Content-Type": contentType,
+          "Content-Length": String(file.size)
+        },
+        body,
+        signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS)
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        return {
+          path: file.relativePath,
+          success: false,
+          error: `HTTP ${response.status}: ${text.slice(0, 200)}`
+        };
+      }
+      return { path: file.relativePath, success: true };
+    } catch (err) {
+      return {
+        path: file.relativePath,
+        success: false,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  /**
+   * Checks upload results and returns paths of any files that failed.
+   * Used by the caller for logging warnings.
+   */
+  static getFailedPaths(files, results) {
+    return results.map((r, i) => ({
+      path: files[i]?.relativePath ?? `file[${i}]`,
+      ok: r.status === "fulfilled" && r.value.success
+    })).filter((r) => !r.ok).map((r) => r.path);
+  }
+};
+
+// src/bundle/watcher.ts
+var import_node_fs = require("fs");
+var import_node_events = require("events");
+var import_node_path2 = __toESM(require("path"), 1);
+var DEBOUNCE_MS = 300;
+var BundleWatcher = class extends import_node_events.EventEmitter {
+  watcher = null;
+  debounceTimer = null;
+  isRebuilding = false;
+  pendingRebuild = false;
+  pendingChangedFile = "";
+  lastChangedFile = "";
+  /** Typed override for EventEmitter.on */
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  /** Typed override for EventEmitter.emit */
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+  /**
+   * Starts watching `srcDir` for changes.
+   * Calls `onRebuild` after each debounced change, serially.
+   *
+   * @param srcDir    - Directory to watch recursively
+   * @param onRebuild - Async callback invoked on each change batch
+   */
+  start(srcDir, onRebuild) {
+    if (this.watcher) {
+      throw new Error("BundleWatcher is already running. Call stop() first.");
+    }
+    try {
+      this.watcher = (0, import_node_fs.watch)(srcDir, { recursive: true }, (_, filename) => {
+        const changedFile = filename ? import_node_path2.default.normalize(filename) : "(unknown file)";
+        this.scheduleRebuild(changedFile, onRebuild);
+      });
+      this.watcher.on("error", (err) => {
+        this.emit("rebuild:error", { error: err });
+      });
+    } catch (err) {
+      throw new Error(
+        `Cannot watch directory "${srcDir}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  /** Stops watching and clears all pending timers */
+  stop() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+    this.isRebuilding = false;
+    this.pendingRebuild = false;
+    this.pendingChangedFile = "";
+    this.lastChangedFile = "";
+  }
+  /**
+   * Schedules a rebuild after the debounce window.
+   * If a rebuild is already in progress, marks a pending rebuild instead.
+   */
+  scheduleRebuild(changedFile, onRebuild) {
+    this.lastChangedFile = changedFile;
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    if (this.isRebuilding) {
+      this.pendingRebuild = true;
+      this.pendingChangedFile = changedFile;
+      return;
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      void this.executeRebuild(this.lastChangedFile, onRebuild);
+    }, DEBOUNCE_MS);
+  }
+  /**
+   * Executes the rebuild callback, then runs any pending rebuild that
+   * accumulated while this one was in progress.
+   */
+  async executeRebuild(changedFile, onRebuild) {
+    this.isRebuilding = true;
+    const startTime = Date.now();
+    this.emit("rebuild:start", { changedFile });
+    try {
+      await onRebuild();
+      const duration = Date.now() - startTime;
+      this.emit("rebuild:complete", { duration });
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit("rebuild:error", { error });
+    } finally {
+      this.isRebuilding = false;
+      if (this.pendingRebuild) {
+        this.pendingRebuild = false;
+        const nextFile = this.pendingChangedFile;
+        this.pendingChangedFile = "";
+        this.debounceTimer = setTimeout(() => {
+          this.debounceTimer = null;
+          void this.executeRebuild(nextFile, onRebuild);
+        }, DEBOUNCE_MS);
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BundleBuilder,
+  BundleUploader,
+  BundleWatcher,
+  formatSize
+});

package/dist/bundle/index.d.cts

@@ -0,0 +1,159 @@
+import { WhataloApiClient } from '../http/index.cjs';
+import { EventEmitter } from 'node:events';
+import '../types-DunvRQ0f.cjs';
+
+/**
+ * BundleBuilder — runs the user-defined build command and collects output files.
+ *
+ * Uses `spawn` (not `exec`) to avoid shell injection. The build command string
+ * is split on whitespace to produce [cmd, ...args].
+ *
+ * Size limit: 10 MB total across all output files.
+ */
+/** Represents a single file collected from the build output directory */
+interface BuildFile {
+    /** Path relative to the output directory root (e.g. "assets/main.js") */
+    relativePath: string;
+    /** Absolute path on disk */
+    absolutePath: string;
+    /** File size in bytes */
+    size: number;
+}
+/** Result returned by BundleBuilder.build() */
+interface BuildResult {
+    /** All files found in the output directory */
+    files: BuildFile[];
+    /** Sum of all file sizes in bytes */
+    totalSize: number;
+    /** Wall-clock time the build took in milliseconds */
+    duration: number;
+}
+/** Formats bytes as a human-readable string (e.g. "1.4 MB") */
+declare function formatSize(bytes: number): string;
+declare class BundleBuilder {
+    /**
+     * Runs the user-defined build command and collects the output files.
+     *
+     * @param buildCommand - Command string from config (e.g. "pnpm build")
+     * @param outputDir    - Build output directory (relative or absolute)
+     * @param cwd          - Working directory for the command (defaults to process.cwd())
+     * @throws If the build exits with a non-zero code or if total size exceeds 10 MB
+     */
+    build(buildCommand: string, outputDir: string, cwd?: string): Promise<BuildResult>;
+    /**
+     * Ensures index.html uses relative asset URLs so bundles work under
+     * session-scoped CDN paths like /dev-bundles/{sessionId}/.
+     */
+    private validateIndexHtmlForCdn;
+    /**
+     * Spawns the build process and waits for it to finish.
+     * Captures stderr for error reporting on non-zero exit.
+     */
+    private runBuildProcess;
+}
+
+/**
+ * BundleUploader — requests presigned PUT URLs from the API and uploads
+ * all build output files to R2/S3 in parallel.
+ *
+ * Strategy:
+ *  - Uses Promise.allSettled so partial failures don't abort the whole upload.
+ *  - index.html is considered the critical entry point; if it fails, the
+ *    entire upload is treated as failed (the CDN bundle would be unusable).
+ *  - Content-Type is derived from the file extension.
+ *  - Native fetch is used for PUT uploads — no extra dependencies.
+ */
+
+/** Result of a single file upload attempt */
+interface FileUploadResult {
+    path: string;
+    success: boolean;
+    error?: string;
+}
+declare class BundleUploader {
+    /**
+     * Requests presigned URLs and uploads all files to the CDN in parallel.
+     *
+     * @param apiClient - Authenticated API client instance
+     * @param sessionId - Development session ID (used in the API path)
+     * @param files     - List of files from BundleBuilder.build()
+     * @returns The public CDN base URL for the uploaded bundle
+     * @throws If the API request fails or if index.html upload fails
+     */
+    upload(apiClient: WhataloApiClient, sessionId: string, files: BuildFile[]): Promise<string>;
+    /**
+     * Uploads a single file to its presigned URL via HTTP PUT.
+     * Sets Content-Type and Content-Length headers as required by S3/R2.
+     */
+    private uploadSingleFile;
+    /**
+     * Checks upload results and returns paths of any files that failed.
+     * Used by the caller for logging warnings.
+     */
+    static getFailedPaths(files: BuildFile[], results: PromiseSettledResult<FileUploadResult>[]): string[];
+}
+
+/**
+ * BundleWatcher — watches a source directory for file changes and triggers
+ * a rebuild callback using the SerialBatchProcessor pattern.
+ *
+ * Key guarantees:
+ *  - Debounce: 300ms after the last detected change before triggering rebuild.
+ *  - Serial execution: if a rebuild is already in progress, the next one is
+ *    queued (not dropped) and runs immediately after the current one finishes.
+ *  - At most ONE pending rebuild is queued at a time (further changes during
+ *    an in-progress rebuild extend the debounce, not stack more rebuilds).
+ *  - Emits typed events for integration with the dev console output.
+ */
+
+interface RebuildStartEvent {
+    /** Path of the file that triggered the rebuild (relative to watched dir) */
+    changedFile: string;
+}
+interface RebuildCompleteEvent {
+    /** Wall-clock duration of the rebuild in milliseconds */
+    duration: number;
+}
+interface RebuildErrorEvent {
+    error: Error;
+}
+/** Typed events emitted by BundleWatcher */
+interface BundleWatcherEvents {
+    "rebuild:start": (event: RebuildStartEvent) => void;
+    "rebuild:complete": (event: RebuildCompleteEvent) => void;
+    "rebuild:error": (event: RebuildErrorEvent) => void;
+}
+declare class BundleWatcher extends EventEmitter {
+    private watcher;
+    private debounceTimer;
+    private isRebuilding;
+    private pendingRebuild;
+    private pendingChangedFile;
+    private lastChangedFile;
+    /** Typed override for EventEmitter.on */
+    on<K extends keyof BundleWatcherEvents>(event: K, listener: BundleWatcherEvents[K]): this;
+    /** Typed override for EventEmitter.emit */
+    emit<K extends keyof BundleWatcherEvents>(event: K, ...args: Parameters<BundleWatcherEvents[K]>): boolean;
+    /**
+     * Starts watching `srcDir` for changes.
+     * Calls `onRebuild` after each debounced change, serially.
+     *
+     * @param srcDir    - Directory to watch recursively
+     * @param onRebuild - Async callback invoked on each change batch
+     */
+    start(srcDir: string, onRebuild: () => Promise<void>): void;
+    /** Stops watching and clears all pending timers */
+    stop(): void;
+    /**
+     * Schedules a rebuild after the debounce window.
+     * If a rebuild is already in progress, marks a pending rebuild instead.
+     */
+    private scheduleRebuild;
+    /**
+     * Executes the rebuild callback, then runs any pending rebuild that
+     * accumulated while this one was in progress.
+     */
+    private executeRebuild;
+}
+
+export { type BuildFile, type BuildResult, BundleBuilder, BundleUploader, BundleWatcher, type BundleWatcherEvents, type RebuildCompleteEvent, type RebuildErrorEvent, type RebuildStartEvent, formatSize };