@builder.io/dev-tools 1.32.1-dev.202603131244.00dcaa12e → 1.32.1-dev.202603131340.b521e1bad

package/types/cli/code-tools.d.ts

@@ -4,6 +4,7 @@ import { type DevServerOrchestrator } from "./launch/dev-server-orchestrator";
 import type { CodeGenEventEmitter } from "./codegen";
 import { CodeGenSession } from "./codegen";
 import type { Credentials } from "./credentials";
+import type { Logger } from "../common/logger";
 import type { LocalMCPClientManager } from "./mcp-local";
 import type { createFusionStatusMonitor } from "./launch/machine-health";
 export interface LLMToolCalls {
@@ -20,6 +21,7 @@ export interface ToolResolution {
 }
 export interface ToolContext {
     debug: boolean;
+    logger: Logger;
     sys: DevToolsSys;
     credentials: Credentials;
     asyncSubAgents: boolean;

package/types/cli/codegen.d.ts

@@ -62,8 +62,6 @@ export interface CodeGenSessionOptionsBase {
     includeMemories?: boolean;
     fusionStatusMonitor?: FusionStatusMonitor;
     asyncSubAgents?: boolean;
-    /** Per-repo GitHub tokens from init phase (relative repo path → token) */
-    initialRepoTokens?: ReadonlyMap<string, string>;
 }
 export interface CodeGenSessionOptionsSession extends CodeGenSessionOptionsBase {
     sessionOrCompletionId?: string;
@@ -98,7 +96,6 @@ export declare class CodeGenSession {
     get gitEnabledFolders(): WorkspaceFolder[];
     /** Returns runtime git repo contexts for all enabled repos */
     get gitRepoContexts(): readonly GitRepoContext[];
-    getGhTokenForPath(workingDir: string): string | undefined;
     get workingDirectory(): string;
     get bashWorkingDirectory(): string;
     getSessionMode(): SessionMode;

package/types/cli/launch/InitStateMachine.d.ts

@@ -88,8 +88,6 @@ export declare class InitStateMachine {
     private initializeGitRepo;
     private fetchGitConfigsOnce;
     private applyGitConfig;
-    /** Returns a read-only view of the per-repo token map (path → token). */
-    get repoTokenMap(): ReadonlyMap<string, string>;
     runInitializationCommand({ repo, tempCloningDir, repoPath, initCommand, }: {
         repo: ValidatedWorkspaceFolder;
         tempCloningDir: string;

package/types/cli/mcp-local.d.ts

@@ -74,7 +74,7 @@ export interface LocalMCPClientManager {
 /**
  * Create a local MCP client manager from server definitions
  */
-export declare function createLocalMCPClientManager(servers: MCPServerDefinition[], sys: DevToolsSys, workingDirectory: string, debug: boolean, signal?: AbortSignal): Promise<LocalMCPClientManager>;
+export declare function createLocalMCPClientManager(servers: MCPServerDefinition[], sys: DevToolsSys, workingDirectory: string, signal?: AbortSignal): Promise<LocalMCPClientManager>;
 /**
  * Apply environment variable substitution to MCP server configuration
  * This is separated from loadMCPConfig to allow easy unit testing
@@ -91,4 +91,4 @@ export declare function applyEnvSubstitutionRemote(serverConfig: Omit<MCPServerR
  * If a server with the same name exists in both, fusionConfig takes precedence
  * Supports both stdio (command-based) and remote (http/sse) server definitions
  */
-export declare function loadMCPConfig(sys: DevToolsSys, workingDirectory: string, serverConfigs: MCPServerConfig, autoImportLocalMCPs: boolean, debug?: boolean, signal?: AbortSignal): Promise<MCPServerDefinition[]>;
+export declare function loadMCPConfig(sys: DevToolsSys, workingDirectory: string, serverConfigs: MCPServerConfig, autoImportLocalMCPs: boolean, signal?: AbortSignal): Promise<MCPServerDefinition[]>;

package/types/cli/utils/codegen-utils.d.ts

@@ -95,5 +95,4 @@ export declare function generateGitStatusReminder(gitStatus: GenerateCompletionS
     trigger: "session-start" | "sync-success" | "push-success" | "pull-success";
     syncedBranches?: string[];
     pushedToRemote?: boolean;
-    hasGhToken?: boolean;
 }): string;

package/types/cli/utils/git.d.ts

@@ -3,7 +3,6 @@ import type { Credentials } from "../credentials";
 import type { GitConfigs, GitDiagnostics } from "$/ai-utils";
 export interface RunCommandOptions {
     cwd?: string;
-    debug?: boolean;
     sys: DevToolsSys;
     timeout?: number;
     skipLogging?: boolean;

package/types/common/logger.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Structured logger for dev-tools.
+ *
+ * ## Enabling debug logs
+ *
+ * Debug output is **off by default**. Two ways to turn it on:
+ *
+ * ### 1. `DEBUG` environment variable
+ *
+ * Set to any truthy value to enable debug output for all loggers:
+ *
+ * ```sh
+ * DEBUG=1 npx @builder.io/dev-tools ...
+ * ```
+ *
+ * ### 2. `--debug` CLI flag
+ *
+ * Sets `process.env.DEBUG = "1"` early in the CLI entry point, enabling
+ * debug output for all loggers (including module-level ones created at
+ * import time, since `DEBUG` is checked lazily at call time).
+ *
+ * ```sh
+ * npx @builder.io/dev-tools --debug ...
+ * ```
+ *
+ * ### `LOG_LEVEL` environment variable
+ *
+ * Controls the minimum severity for `info`, `warn`, and `error` messages.
+ * Accepted values: `debug`, `info` (default), `warn`, `error`.
+ *
+ * `LOG_LEVEL` does **not** affect `debug()` output — debug messages are
+ * controlled exclusively by the `DEBUG` env var / `--debug` CLI flag.
+ * This is intentional: debug is an explicit opt-in, and the default
+ * `LOG_LEVEL=info` must not silently suppress explicitly requested output.
+ *
+ * ```sh
+ * DEBUG=1 npx @builder.io/dev-tools ...                    # debug + info/warn/error
+ * LOG_LEVEL=error npx @builder.io/dev-tools ...            # errors only (no debug)
+ * LOG_LEVEL=warn DEBUG=1 npx @builder.io/dev-tools ...     # debug + warn/error
+ * ```
+ *
+ * ### Per-call options (`loggerOptions`)
+ *
+ * Any log method accepts an optional trailing `{ loggerOptions: { ... } }`
+ * argument with:
+ *
+ * - `debug: true`  — only emit this call when debug mode is enabled.
+ *   Useful for error/warn/info calls that should only appear during
+ *   debugging (e.g. stack traces, verbose diagnostics).
+ * - `stderr: true` — force output to stderr even for methods that
+ *   normally write to stdout (debug, info). Useful when stdout is
+ *   reserved for a protocol (e.g. MCP stdio JSON-RPC).
+ *
+ * ```ts
+ * logger.error("Stack trace:", err.stack, { loggerOptions: { debug: true } });
+ * logger.info("Server running on stdio", { loggerOptions: { stderr: true } });
+ * ```
+ *
+ * ### Cloud environments
+ *
+ * When `FUSION_ENVIRONMENT` is `cloud` or `cloud-v2`, all output is emitted
+ * as newline-delimited JSON (GCP Cloud Logging compatible) with `severity`,
+ * `message`, `timestamp`, and optional `context` fields. The `stderr` option
+ * controls which stream is used but does not affect the `severity` field —
+ * GCP reads severity from the JSON payload, not from the stream.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogCallOptions {
+    /** Force output to stderr (useful when stdout is reserved, e.g. MCP stdio). */
+    stderr?: boolean;
+    /** Only emit this call when debug mode is enabled on the logger. */
+    debug?: boolean;
+}
+interface LogCallOptionsWrapper {
+    loggerOptions: LogCallOptions;
+}
+export interface Logger {
+    debug(...args: [...any[], LogCallOptionsWrapper]): void;
+    debug(...args: any[]): void;
+    info(...args: [...any[], LogCallOptionsWrapper]): void;
+    info(...args: any[]): void;
+    warn(...args: [...any[], LogCallOptionsWrapper]): void;
+    warn(...args: any[]): void;
+    error(...args: [...any[], LogCallOptionsWrapper]): void;
+    error(...args: any[]): void;
+}
+export interface CreateLoggerOptions {
+    /**
+     * Enable debug output. Accepts a static boolean or a lazy `() => boolean`
+     * for runtime checks (e.g. checking multiple env vars). When omitted,
+     * defaults to checking `process.env.DEBUG` lazily at call time.
+     */
+    debug?: boolean | (() => boolean);
+    level?: LogLevel;
+}
+export declare function createLogger(context?: string, options?: CreateLoggerOptions): Logger;
+export {};

package/types/core/component-map-builder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Component Map Builder
+ *
+ * Builds a map of component names to their source file locations for the Design tab.
+ * This allows the Design tab to work without requiring React's _debugSource or customer plugins.
+ */
+import type { DevToolsSys } from "../types";
+export interface ComponentLocation {
+    file: string;
+    line: number;
+    column: number;
+    displayName: string;
+}
+export type ComponentMap = Record<string, ComponentLocation[]>;
+/**
+ * Build a map of component names to their source locations
+ */
+export declare function buildComponentMap(sys: DevToolsSys, rootDir?: string): Promise<ComponentMap>;
+/**
+ * Cache for component map with file watching
+ */
+export declare class ComponentMapCache {
+    private cache;
+    private lastBuilt;
+    private building;
+    private readonly ttl;
+    private sys;
+    private rootDir;
+    constructor(sys: DevToolsSys, rootDir?: string);
+    /**
+     * Get the component map, building it if necessary
+     */
+    get(): Promise<ComponentMap>;
+    /**
+     * Invalidate the cache
+     */
+    invalidate(): void;
+    /**
+     * Force rebuild of the component map
+     */
+    rebuild(): Promise<ComponentMap>;
+}

package/types/server/source-map-resolver/cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LRU cache for source maps and TraceMap instances
+ */
+import { TraceMap } from "@jridgewell/trace-mapping";
+import type { SourceMapV3 } from "./types";
+interface CachedSourceMap {
+    json: SourceMapV3;
+    /** TraceMap instances keyed by section index (-1 for non-indexed maps) */
+    tracers: Map<number, TraceMap>;
+}
+/**
+ * Get or create cache key from bundled path and source mapping URL
+ */
+export declare function getCacheKey(bundledPath: string, sourceMappingURL: string): string;
+/**
+ * Get cached source map data
+ * Returns undefined if not cached, null if cached as failed
+ */
+export declare function getCached(key: string): CachedSourceMap | null | undefined;
+/**
+ * Cache a successfully loaded source map
+ */
+export declare function setCached(key: string, json: SourceMapV3): CachedSourceMap;
+/**
+ * Cache a failed load attempt (negative caching)
+ */
+export declare function setCachedFailure(key: string): void;
+/**
+ * Get or create a TraceMap for a specific section (or -1 for non-indexed)
+ */
+export declare function getOrCreateTracer(entry: CachedSourceMap, sectionIndex: number, mapJson: SourceMapV3): TraceMap;
+/**
+ * Clear all cached data
+ */
+export declare function clearCache(): void;
+export {};

package/types/server/source-map-resolver/indexed-map-resolver.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Utilities for handling indexed source maps (section maps)
+ */
+import type { SourceMapSection, SectionMatch } from "./types";
+/**
+ * Find the section containing a given position in an indexed source map.
+ * Sections are ordered by offset, so we find the last one that starts
+ * at or before the target position.
+ */
+export declare function findMatchingSection(sections: SourceMapSection[], line: number, column: number): SectionMatch | null;

package/types/server/source-map-resolver/loader.d.ts

@@ -0,0 +1,16 @@
+/**
+ * File and source map loading utilities
+ */
+import type { ResolveContext } from "./types";
+/**
+ * Extract sourceMappingURL from JS file content
+ */
+export declare function extractSourceMappingURL(content: string): string | null;
+/**
+ * Load JS file content from dev server or filesystem
+ */
+export declare function loadJSContent(ctx: ResolveContext, bundledPath: string, isServerChunk: boolean): Promise<string | null>;
+/**
+ * Load source map content from various sources
+ */
+export declare function loadSourceMapContent(ctx: ResolveContext, bundledPath: string, sourceMappingURL: string): Promise<string | null>;

package/types/server/source-map-resolver/security.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Security utilities for path validation and sanitization
+ */
+/**
+ * Check if a resolved path is safely within the project root.
+ * Prevents sibling directory access (e.g., /project-sensitive when root is /project)
+ */
+export declare function isPathWithinRoot(filePath: string, rootPath: string): boolean;
+/**
+ * Sanitize and validate a bundled path input.
+ * Returns decoded path or null if invalid.
+ */
+export declare function sanitizeBundledPath(bundledPath: string): string | null;
+/**
+ * Check if a chunk filename is definitely internal (not user code)
+ */
+export declare function isDefinitelyInternalChunk(filename: string): boolean;
+/**
+ * Check if a resolved source path is framework code
+ */
+export declare function isFrameworkCode(sourcePath: string): boolean;

package/types/server/source-map-resolver/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared types for source map resolution
+ */
+export interface OriginalPosition {
+    source: string;
+    line: number;
+    column: number;
+    name?: string;
+}
+/**
+ * Source Map v3 JSON structure
+ * Based on: https://sourcemaps.info/spec.html
+ */
+export interface SourceMapV3 {
+    version: number;
+    file?: string;
+    sourceRoot?: string;
+    sources?: string[];
+    sourcesContent?: (string | null)[];
+    names?: string[];
+    mappings?: string;
+    sections?: SourceMapSection[];
+}
+export interface SourceMapSection {
+    offset: {
+        line: number;
+        column: number;
+    };
+    map?: SourceMapV3;
+    url?: string;
+}
+export interface ResolveContext {
+    projectRoot: string;
+    devServerUrl: string;
+}
+export interface SectionMatch {
+    section: SourceMapSection;
+    index: number;
+    relativeLine: number;
+    relativeColumn: number;
+}

package/types/server/source-map-resolver/validation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Source map validation utilities
+ */
+import type { SourceMapV3 } from "./types";
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate a source map v3 structure
+ */
+export declare function validateSourceMap(json: unknown): ValidationResult;
+/**
+ * Clean up source map structure before processing
+ */
+export declare function prepareSourceMap(json: SourceMapV3): SourceMapV3;

package/types/server/source-map-resolver.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Server-side source map resolution using @jridgewell/trace-mapping
+ * Fetches bundled files from dev server and resolves to original source locations
+ */
+import type { OriginalPosition } from "./source-map-resolver/types";
+import { clearCache } from "./source-map-resolver/cache";
+export type { OriginalPosition };
+export { clearCache as clearSourceMapCache };
+/**
+ * Resolve a bundled file location to its original source location
+ * @param projectRoot Root directory of the project (for file fallback)
+ * @param devServerUrl Base URL of the dev server (e.g., http://localhost:3000)
+ * @param bundledPath Path to the bundled file (e.g., /_next/static/chunks/app/page.js)
+ * @param line Line number in bundled file (1-indexed)
+ * @param column Column number in bundled file (0-indexed)
+ */
+export declare function resolveSourceLocation(projectRoot: string, devServerUrl: string, bundledPath: string, line: number, column: number): Promise<OriginalPosition | null>;
+/**
+ * Batch resolve multiple source locations with deduplication
+ */
+export declare function batchResolveSourceLocations(projectRoot: string, devServerUrl: string, locations: Array<{
+    bundledPath: string;
+    line: number;
+    column: number;
+}>): Promise<Array<OriginalPosition | null>>;