builder.io 1.6.125 → 1.6.127

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

@@ -28,10 +28,12 @@ export interface ToolContext extends Partial<FusionContext> {
     workingDirectory: string;
     allowedCommands: RegExp[];
     bashWorkingDirectory: string;
+    filterText: (text: string) => string;
     resolveWorkspacePath: (path: string, forceWorkspace: boolean) => {
         resolvedPath: string;
         workspaceFolder?: WorkspaceFolder;
     };
+    absolutePathToWorkspaceUrl: (absolutePath: string) => string | undefined;
     workspaceFolders: Array<{
         path: string;
         name?: string;

package/types/cli/codegen.d.ts

@@ -209,6 +209,10 @@ export declare class CodeGenSession {
     waitForEventLoop(): Promise<void>;
     agentCompletion(userMessage: GenerateUserMessage, signal: AbortSignal | undefined, onStep: (step: GenerateCompletionStep) => void): Promise<void>;
     commitWorkInProgress(lastTurn: CodegenTurn): Promise<string | undefined>;
+    getChangesReport(): Promise<{
+        diff: string;
+        files: string[];
+    } | undefined>;
     isCleanWorkTree(): Promise<boolean>;
     /**
      * Resolves a workspace file path to its actual file system path
@@ -220,6 +224,12 @@ export declare class CodeGenSession {
         resolvedPath: string;
         workspaceFolder?: WorkspaceFolder;
     };
+    /**
+     * Converts an absolute file system path to a workspace URL
+     * @param absolutePath The absolute file system path to convert
+     * @returns The workspace URL if the path can be converted, undefined otherwise
+     */
+    absolutePathToWorkspaceUrl(absolutePath: string): string | undefined;
     /**
      * Reads a file from the workspace
      * @param filePath A file path that may include a workspace prefix

package/types/cli/launch/dev-server-orchestrator.d.ts

@@ -19,6 +19,7 @@ export interface DevServerOrchestrator {
     state: DevServerState;
     proxyTarget: string;
     proxyPort: number;
+    envVars: Record<string, string>;
     proxyMiddleware: ProxyRequestHandler | undefined;
     pid: number | undefined;
     abortSetupCommand: () => void;

package/types/cli/repo-indexing.mock.d.ts

@@ -0,0 +1,5 @@
+export declare const mockDeps: {
+    getStoredComponentDocs: () => Promise<never[]>;
+    storeComponentDocs: () => Promise<{}>;
+    runCodeGen: () => Promise<string>;
+};

package/types/cli/utils/component-group-mdx-prompt.d.ts

@@ -1 +1 @@
-export declare const COMPONENT_GROUP_MDX_PROMPT = "# Component Group Documentation Generation\n\n## Objective\nGenerate comprehensive MDX documentation for a specific component group, analyzing their interfaces, relationships, and usage patterns using only the relevant files provided in the input.\n\n## Instructions\n\n### 1. Component Analysis\nFor the given component group, analyze each relevant file by:\n- **Interdependency mapping** - Document how components depend on each other\n- **Interface examination** - Extract and document all props, their types, and descriptions\n- **Context analysis** - Identify shared state, contexts, or communication patterns\n- **Compositional patterns** - Document required parent-child relationships\n- **Usage pattern analysis** - Identify how components work together\n- **Example extraction** - Find real usage examples from the codebase\n\n### 2. Documentation Structure\nCreate comprehensive documentation covering:\n- **Group rationale** - Why these components work together and when to use them\n- **Architectural overview** - How the components form a cohesive system\n- **Component interfaces** - Detailed prop documentation with interdependencies\n- **Composition patterns** - Required and optional usage combinations\n- **Integration examples** - Real-world scenarios showing the group in action\n- **Best practices** - Recommended usage patterns and guidelines\n\n## Required Output Format\n\nGenerate an MDX file with this structure:\n\n```mdx\n---\n# {{GROUP_NAME}} Components\n\n## Overview\n\n### Purpose\n{{GROUP_DESCRIPTION}}\n\n### When to Use\n[Expand on the use cases mentioned in the description - be specific about scenarios, user needs, and implementation contexts]\n\n### Architecture\n[Explain the architectural pattern based on coupling strength:]\n- **Critical/Strong Coupling**: Describe the required relationships, shared context, or compositional hierarchy\n- **Moderate Coupling**: Explain how components enhance each other\n- **No Coupling**: Note that this is a standalone component\n\n### Component Interdependencies\n[Map out component relationships - only for groups with coupling:]\n- Required parent-child relationships\n- Shared context dependencies  \n- Communication patterns between components\n\n## Components\n\n### [PrimaryComponent] {Primary Component for groups with coupling}\n[Mark the main/root component for coupled groups]\n\n**Purpose:** [What this specific component does within the group]\n\n**Interface:**\n```typescript\ninterface [PrimaryComponent]Props {\n  // Document all props with types and descriptions\n  children: React.ReactNode; // Required child components (for coupled groups)\n  property: string; // Description of what this prop does\n  onAction?: () => void; // Optional callback description\n}\n```\n\n**Dependencies:** [For coupled groups - what this component requires]\n**Provides:** [For coupled groups - what context/state this component provides to children]\n\n**Usage Example:**\n```tsx\nimport { [PrimaryComponent] } from '@your-library/components';\n\nfunction Example() {\n  return (\n    <[PrimaryComponent]\n      property=\"value\"\n      onAction={() => console.log('action')}\n    >\n      {/* Required children for coupled groups */}\n    </[PrimaryComponent]>\n  );\n}\n```\n\n### [DependentComponent] {Dependent Component for groups with coupling}\n[Mark components that depend on the primary component]\n\n**Purpose:** [What this specific component does within the group]\n\n**Interface:**\n```typescript\ninterface [DependentComponent]Props {\n  // Props specific to this component\n  // Note any props that are passed down from parent context\n}\n```\n\n**Context Dependencies:** [What context/state this component requires from parent]\n**Parent Requirements:** [Required parent components for proper functionality]\n\n**Usage Example:**\n```tsx\n// Must be used within [PrimaryComponent] for coupled groups\n<[PrimaryComponent]>\n  <[DependentComponent] prop=\"value\">\n    Content\n  </[DependentComponent]>\n</[PrimaryComponent]>\n```\n\n### [StandaloneComponent] {For uncoupled components}\n[For components with no coupling]\n\n**Purpose:** [What this component does and when to use it]\n\n**Interface:**\n```typescript\ninterface [StandaloneComponent]Props {\n  // All props with types and descriptions\n}\n```\n\n**Usage Example:**\n```tsx\nimport { [StandaloneComponent] } from '@your-library/components';\n\nfunction Example() {\n  return (\n    <[StandaloneComponent]\n      property=\"value\"\n      onAction={() => console.log('action')}\n    />\n  );\n}\n```\n\n## Integration Patterns\n\n### Basic Usage {Only for coupled groups}\n```tsx\nimport { [PrimaryComponent], [DependentComponent1], [DependentComponent2] } from '@your-library/components';\n\n// Minimal required structure\nfunction BasicExample() {\n  return (\n    <[PrimaryComponent]>\n      <[DependentComponent1]>Required content</[DependentComponent1]>\n      <[DependentComponent2]>More content</[DependentComponent2]>\n    </[PrimaryComponent]>\n  );\n}\n```\n\n### Advanced Usage {Only for coupled groups}\n```tsx\n// Complex usage with all features\nfunction AdvancedExample() {\n  return (\n    <[PrimaryComponent] \n      property=\"value\" \n      onAction={handleAction}\n    >\n      <[DependentComponent1] prop=\"value\">\n        <Content />\n      </[DependentComponent1]>\n      <[DependentComponent2] prop=\"value\">\n        <MoreContent />\n      </[DependentComponent2]>\n    </[PrimaryComponent]>\n  );\n}\n```\n\n### Common Variations {Adapt based on component types}\n```tsx\n// Show different ways to use the component(s)\n// Include conditional rendering, different prop combinations, etc.\n```\n\n## Component Relationships {Only for coupled groups}\n\n### Data Flow\n[Explain how data flows between components in the group]\n\n### Context Sharing\n[Document shared contexts, providers, or state management]\n\n### Event Handling\n[Describe how events bubble up or propagate between components]\n\n## Best Practices\n\n### Usage Guidelines\n- [Specific recommendation based on component purpose and use cases]\n- [Another recommendation focusing on accessibility or performance]\n- [Usage pattern guidance based on the group's architecture]\n\n### Accessibility {When relevant}\n- [ARIA relationships between components for coupled groups]\n- [Keyboard navigation patterns]\n- [Screen reader considerations]\n\n### Performance {When relevant}\n- [Optimization recommendations]\n- [State management best practices]\n- [Rendering performance considerations]\n\n## Common Patterns {Expand based on component functionality}\n\n### Pattern 1: [Specific Pattern Name]\n```tsx\n// Example showing a specific usage pattern\n// Include comments explaining why this pattern is recommended\n```\n\n### Pattern 2: [Another Pattern Name]\n```tsx\n// Another common pattern with explanation\n```\n\n```\n\n## File Generation Requirements\n\n**File Naming:**\n- Use kebab-case derived from group name: `{{GROUP_NAME_KEBAB}}.mdx`\n- Place in `repo-indexing/` folder\n- Example: `repo-indexing/{{GROUP_NAME_KEBAB}}.mdx`\n\n**Content Requirements:**\n1. **Use coupling strength context** - Adapt documentation structure based on couplingStrength value\n2. **Extract real interfaces** - Don't create placeholder interfaces, extract actual TypeScript interfaces from the codebase\n3. **Leverage group description** - Expand on the provided description with specific use cases and implementation guidance\n4. **Document interdependencies** - For coupled groups, clearly explain component relationships and requirements\n5. **Include practical examples** - Use realistic, working code examples that demonstrate proper usage\n6. **Show integration patterns** - For coupled groups, demonstrate required composition patterns\n**Coupling-Specific Requirements:**\n- **Critical/Strong Coupling**: Focus on required relationships, composition patterns, and shared context\n- **Moderate Coupling**: Show how components enhance each other and optional usage patterns  \n- **No Coupling**: Document standalone usage, variants, and individual component capabilities\n\n\n## Input Format\nYou will receive a single component group object:\n```json\n{\n  \"name\": \"{{GROUP_NAME}}\", \n  \"description\": \"{{GROUP_DESCRIPTION}}\",\n  \"components\": [{{COMPONENT_LIST}}],\n}\n```\n\n## Output\nReturn only the complete MDX file content, ready to be saved as `repo-indexing/{{GROUP_NAME_KEBAB}}.mdx`";
+export declare const COMPONENT_GROUP_MDX_PROMPT = "# Component Group Documentation Generation\n\n## Objective\nGenerate comprehensive MDX documentation for a specific component group, analyzing their interfaces, relationships, and usage patterns using only the relevant files provided in the input.\n\n## Instructions\n\n### 1. Component Analysis\nFor the given component group, analyze each relevant file by:\n- **Interdependency mapping** - Document how components depend on each other\n- **Interface examination** - Extract and document all props, their types, and descriptions\n- **Context analysis** - Identify shared state, contexts, or communication patterns\n- **Compositional patterns** - Document required parent-child relationships\n- **Usage pattern analysis** - Identify how components work together\n- **Example extraction** - Find real usage examples from the codebase\n\n### 2. Documentation Structure\nCreate comprehensive documentation covering:\n- **Group rationale** - Why these components work together and when to use them\n- **Architectural overview** - How the components form a cohesive system\n- **Component interfaces** - Detailed prop documentation with interdependencies\n- **Composition patterns** - Required and optional usage combinations\n- **Integration examples** - Real-world scenarios showing the group in action\n- **Best practices** - Recommended usage patterns and guidelines\n\n## Required Output Format\n\nGenerate an MDX file with this structure:\n\n```mdx\n---\n# {{GROUP_NAME}} Components\n\n## Overview\n\n### Purpose\n{{GROUP_DESCRIPTION}}\n\n### When to Use\n[Expand on the use cases mentioned in the description - be specific about scenarios, user needs, and implementation contexts]\n\n### Architecture\n[Explain the architectural pattern based on coupling strength:]\n- **Critical/Strong Coupling**: Describe the required relationships, shared context, or compositional hierarchy\n- **Moderate Coupling**: Explain how components enhance each other\n- **No Coupling**: Note that this is a standalone component\n\n### Component Interdependencies\n[Map out component relationships - only for groups with coupling:]\n- Required parent-child relationships\n- Shared context dependencies  \n- Communication patterns between components\n\n## Components\n\n### [PrimaryComponent] {Primary Component for groups with coupling}\n[Mark the main/root component for coupled groups]\n\n**Purpose:** [What this specific component does within the group]\n\n**Interface:**\n```typescript\ninterface [PrimaryComponent]Props {\n  // Document all props with types and descriptions\n  children: React.ReactNode; // Required child components (for coupled groups)\n  property: string; // Description of what this prop does\n  onAction?: () => void; // Optional callback description\n}\n```\n\n**Dependencies:** [For coupled groups - what this component requires]\n**Provides:** [For coupled groups - what context/state this component provides to children]\n\n**Usage Example:**\n```tsx\nimport { [PrimaryComponent] } from '@your-library/components';\n\nfunction Example() {\n  return (\n    <[PrimaryComponent]\n      property=\"value\"\n      onAction={() => console.log('action')}\n    >\n      {/* Required children for coupled groups */}\n    </[PrimaryComponent]>\n  );\n}\n```\n\n### [DependentComponent] {Dependent Component for groups with coupling}\n[Mark components that depend on the primary component]\n\n**Purpose:** [What this specific component does within the group]\n\n**Interface:**\n```typescript\ninterface [DependentComponent]Props {\n  // Props specific to this component\n  // Note any props that are passed down from parent context\n}\n```\n\n**Context Dependencies:** [What context/state this component requires from parent]\n**Parent Requirements:** [Required parent components for proper functionality]\n\n**Usage Example:**\n```tsx\n// Must be used within [PrimaryComponent] for coupled groups\n<[PrimaryComponent]>\n  <[DependentComponent] prop=\"value\">\n    Content\n  </[DependentComponent]>\n</[PrimaryComponent]>\n```\n\n### [StandaloneComponent] {For uncoupled components}\n[For components with no coupling]\n\n**Purpose:** [What this component does and when to use it]\n\n**Interface:**\n```typescript\ninterface [StandaloneComponent]Props {\n  // All props with types and descriptions\n}\n```\n\n**Usage Example:**\n```tsx\nimport { [StandaloneComponent] } from '@your-library/components';\n\nfunction Example() {\n  return (\n    <[StandaloneComponent]\n      property=\"value\"\n      onAction={() => console.log('action')}\n    />\n  );\n}\n```\n\n## Integration Patterns\n\n### Basic Usage {Only for coupled groups}\n```tsx\nimport { [PrimaryComponent], [DependentComponent1], [DependentComponent2] } from '@your-library/components';\n\n// Minimal required structure\nfunction BasicExample() {\n  return (\n    <[PrimaryComponent]>\n      <[DependentComponent1]>Required content</[DependentComponent1]>\n      <[DependentComponent2]>More content</[DependentComponent2]>\n    </[PrimaryComponent]>\n  );\n}\n```\n\n### Advanced Usage {Only for coupled groups}\n```tsx\n// Complex usage with all features\nfunction AdvancedExample() {\n  return (\n    <[PrimaryComponent] \n      property=\"value\" \n      onAction={handleAction}\n    >\n      <[DependentComponent1] prop=\"value\">\n        <Content />\n      </[DependentComponent1]>\n      <[DependentComponent2] prop=\"value\">\n        <MoreContent />\n      </[DependentComponent2]>\n    </[PrimaryComponent]>\n  );\n}\n```\n\n### Common Variations {Adapt based on component types}\n```tsx\n// Show different ways to use the component(s)\n// Include conditional rendering, different prop combinations, etc.\n```\n\n## Component Relationships {Only for coupled groups}\n\n### Data Flow\n[Explain how data flows between components in the group]\n\n### Context Sharing\n[Document shared contexts, providers, or state management]\n\n### Event Handling\n[Describe how events bubble up or propagate between components]\n\n## Best Practices\n\n### Usage Guidelines\n- [Specific recommendation based on component purpose and use cases]\n- [Another recommendation focusing on accessibility or performance]\n- [Usage pattern guidance based on the group's architecture]\n\n### Accessibility {When relevant}\n- [ARIA relationships between components for coupled groups]\n- [Keyboard navigation patterns]\n- [Screen reader considerations]\n\n### Performance {When relevant}\n- [Optimization recommendations]\n- [State management best practices]\n- [Rendering performance considerations]\n\n## Common Patterns {Expand based on component functionality}\n\n### Pattern 1: [Specific Pattern Name]\n```tsx\n// Example showing a specific usage pattern\n// Include comments explaining why this pattern is recommended\n```\n\n### Pattern 2: [Another Pattern Name]\n```tsx\n// Another common pattern with explanation\n```\n\n```\n\n## File Generation Requirements\n\n**File Naming:**\n- Use kebab-case derived from group name: `{{GROUP_NAME_KEBAB}}.mdx`\n- Place in `repo-indexing/` folder\n- Example: `repo-indexing/{{GROUP_NAME_KEBAB}}.mdx`\n\n**Content Requirements:**\n1. **Use coupling strength context** - Adapt documentation structure based on couplingStrength value\n2. **Extract real interfaces** - Don't create placeholder interfaces, extract actual TypeScript interfaces from the codebase\n3. **Leverage group description** - Expand on the provided description with specific use cases and implementation guidance\n4. **Document interdependencies** - For coupled groups, clearly explain component relationships and requirements\n5. **Include practical examples** - Use realistic, working code examples that demonstrate proper usage\n6. **Show integration patterns** - For coupled groups, demonstrate required composition patterns\n**Coupling-Specific Requirements:**\n- **Critical/Strong Coupling**: Focus on required relationships, composition patterns, and shared context\n- **Moderate Coupling**: Show how components enhance each other and optional usage patterns  \n- **No Coupling**: Document standalone usage, variants, and individual component capabilities\n\n## Output\nReturn only the complete MDX file content, ready to be saved as `repo-indexing/{{GROUP_NAME_KEBAB}}.mdx`";

package/types/cli/utils/workspace-path-resolver.d.ts

@@ -50,3 +50,43 @@ export interface ResolveWorkspacePathResult {
  * ```
  */
 export declare function resolveWorkspacePath(options: ResolveWorkspacePathOptions): ResolveWorkspacePathResult;
+export interface AbsolutePathToWorkspaceUrlOptions {
+    absolutePath: string;
+    workspace?: WorkspaceConfiguration;
+    workingDirectory: string;
+    sys: DevToolsSys;
+    canCollapseWorkspace?: boolean;
+}
+/**
+ * Converts an absolute file system path to a workspace URL if possible.
+ *
+ * This function is the inverse of `resolveWorkspacePath`. It takes an absolute path
+ * and attempts to convert it back to a workspace-relative path (e.g., "frontend/src/file.ts").
+ *
+ * @param options Configuration object containing all required parameters
+ * @param options.absolutePath The absolute file system path to convert
+ * @param options.workspace Optional workspace configuration with folders
+ * @param options.workingDirectory The base working directory
+ * @param options.sys DevToolsSys object providing path resolution functions
+ * @param options.canCollapseWorkspace If true, handles collapsible workspace scenarios
+ * @returns The workspace URL if the path can be converted, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * import { createNodeSys } from '@builder.io/dev-tools/node';
+ *
+ * const workspaceUrl = absolutePathToWorkspaceUrl({
+ *   absolutePath: '/home/user/project/packages/frontend/src/components/Button.tsx',
+ *   workingDirectory: '/home/user/project',
+ *   sys: createNodeSys(),
+ *   workspace: {
+ *     folders: [
+ *       { name: 'frontend', path: './packages/frontend' },
+ *       { name: 'backend', path: './packages/backend' }
+ *     ]
+ *   }
+ * });
+ * // Returns: 'frontend/src/components/Button.tsx'
+ * ```
+ */
+export declare function absolutePathToWorkspaceUrl(options: AbsolutePathToWorkspaceUrlOptions): string | undefined;