@builder.io/dev-tools 0.2.31 → 0.11.33-dev.202509151402.6aa9b1f64

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

@@ -0,0 +1,68 @@
+import type { DevToolsSys } from "@builder.io/dev-tools/core";
+import { type FusionConfig, type WorkspaceFolder, type InitState, type InitStateStep, type InitStatusLog } from "$/ai-utils";
+import type { Credentials } from "../credentials";
+import { type GitBackupDownloadResult } from "../backup";
+export interface InitConfig {
+    fusionConfig: FusionConfig;
+    credentials: Credentials;
+    sys: DevToolsSys;
+    debug?: boolean;
+    sentryTags?: Record<string, string>;
+}
+export interface InitStatus {
+    message: string;
+    error?: string;
+}
+export declare class InitStateMachine {
+    logIdCounter: number;
+    initStatusLogs: InitStatusLog[];
+    sys: DevToolsSys;
+    config: InitConfig;
+    debug: boolean;
+    initState: InitState;
+    constructor(config: InitConfig);
+    checkout(branchName: string, ref: string, repoPath: string): Promise<boolean>;
+    execAsync(exec: string, args: string[], cwd?: string, retry?: number): Promise<string>;
+    git(args: string[], cwd?: string, retry?: number): Promise<string>;
+    performBackup({ sys, credentials, fusionConfig, volumePath, repositories, isConnectedToProvider, forcedFullBackup, }: {
+        sys: DevToolsSys;
+        credentials: Credentials;
+        fusionConfig: FusionConfig;
+        volumePath: string;
+        repositories: Required<WorkspaceFolder>[];
+        isConnectedToProvider: boolean;
+        forcedFullBackup: boolean;
+    }): Promise<void>;
+    performRegularBackup(args: Omit<Parameters<typeof this.performBackup>[0], "isConnectedToProvider" | "forcedFullBackup">): Promise<void>;
+    performOfflineBackup(args: Omit<Parameters<typeof this.performBackup>[0], "isConnectedToProvider" | "forcedFullBackup">): Promise<void>;
+    performForcedFullBackup(args: Omit<Parameters<typeof this.performBackup>[0], "isConnectedToProvider" | "forcedFullBackup">): Promise<void>;
+    init(): Promise<boolean>;
+    addInitLog(type: "status" | "log" | "error" | "complete", message: string, options?: {
+        step?: InitStateStep;
+        error?: string;
+        success?: boolean;
+    }): void;
+    clearInitLogs(): void;
+    hasFilesButNoGit(repoPath: string): Promise<boolean>;
+    step1CheckDirectories(volumePath: string, repositories: Required<WorkspaceFolder>[]): Promise<void>;
+    step2ConfigureGitRepositories(volumePath: string, repositories: Required<WorkspaceFolder>[]): Promise<void>;
+    step3ConfigureGitUser(volumePath: string, repositories: Required<WorkspaceFolder>[]): Promise<void>;
+    step4StashChanges(volumePath: string, repositories: Required<WorkspaceFolder>[]): Promise<void>;
+    step5CollectRepoInfo(config: InitConfig, volumePath: string, repositories: Required<WorkspaceFolder>[]): Promise<void>;
+    private isGitConfigured;
+    private getGitRemoteUrl;
+    private sanitizeGitRemoteUrl;
+    private cleanupLockFiles;
+    validateGitRepo(repoPath: string): Promise<void>;
+    /**
+     * If a backup is available, perform a backup recovery (and throw if it fails and cannot be recovered from).
+     * If no backup is available, do nothing.
+     */
+    private restoreFromPartialBackup;
+    private initializeGitRepo;
+    cloneRepository({ repo, repoPath, backupResult, }: {
+        repo: Required<WorkspaceFolder>;
+        repoPath: string;
+        backupResult: GitBackupDownloadResult | undefined;
+    }): Promise<boolean>;
+}

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

@@ -0,0 +1,6 @@
+import { type FusionConfig } from "$/ai-utils";
+import type { LaunchArgs } from "../launch";
+import type { DevToolsSys } from "types";
+export declare function getFusionConfig(sys: DevToolsSys, args: LaunchArgs): Promise<FusionConfig>;
+export declare function saveFusionConfig(sys: DevToolsSys, fusionConfig: FusionConfig): Promise<void>;
+export declare function trackConfigData(sys: DevToolsSys, fusionConfig: FusionConfig): void;

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

@@ -0,0 +1,64 @@
+import type { DevToolsSys } from "@builder.io/dev-tools/core";
+import { type RequestHandler as ProxyRequestHandler } from "http-proxy-middleware";
+import type { DevCommandState, EnvironmentVariable, HttpServerState } from "$/ai-utils";
+import EventEmitter from "events";
+import { ChildProcess } from "node:child_process";
+import type { FusionConfig, SetupCommandState } from "$/ai-utils";
+export type DevServerState = Exclude<SetupCommandState | DevCommandState, "installed" | "starting">;
+export interface SetupCommandResult {
+    code: number | null;
+    output: string;
+}
+export interface DevServerOrchestrator {
+    devCommand: string;
+    setupCommand: string | undefined;
+    setupState: SetupCommandState;
+    lastServerBody: string | undefined;
+    lastServerStatus: number | undefined;
+    devState: DevCommandState;
+    httpServerState: HttpServerState;
+    state: DevServerState;
+    proxyTarget: string;
+    proxyPort: number;
+    environmentVariables: EnvironmentVariable[];
+    envVars: Record<string, string>;
+    proxyMiddleware: ProxyRequestHandler | undefined;
+    pid: number | undefined;
+    autoDetectedUrl: string | undefined;
+    abortSetupCommand: () => void;
+    clearEnvVariables: () => void;
+    setEnvVariable: (key: string, value: string | undefined) => boolean;
+    ensureDevCommand: (abortSignal?: AbortSignal) => Promise<boolean>;
+    ensureSetupCommand: (abortSignal?: AbortSignal) => Promise<boolean>;
+    setupCommandPromise: Promise<SetupCommandResult> | undefined;
+    runSetupCommand: (signal?: AbortSignal) => Promise<SetupCommandResult>;
+    setSetupCommand: (newCommand: string, forceRestart?: boolean, signal?: AbortSignal) => Promise<SetupCommandResult | null>;
+    setDevCommand: (newCommand: string, forceRestart?: boolean, signal?: AbortSignal) => Promise<boolean>;
+    setProxyServer: (newProxyServer: string) => Promise<boolean>;
+    setPort: (newPort: number) => Promise<boolean>;
+    addCheckpoint: () => void;
+    getOpenPorts: () => Promise<number[]>;
+    getCheckpoints: (n: number, mode: "all" | "out" | "err") => string;
+    getAllStdout: () => string;
+    getAllStderr: () => string;
+    getOutput: () => string;
+    getSetupOutput: () => string;
+    waitUntilIdle: (initialWaitMs?: number, idleTimeMs?: number) => Promise<void>;
+    onClose: (callback: (code: number | null) => void) => void;
+    restart: (abortSignal?: AbortSignal) => Promise<void>;
+    emitter: EventEmitter<{
+        close: [number | null];
+        stdout: [string];
+        stderr: [string];
+        installStdout: [string];
+        installStderr: [string];
+        setupState: [SetupCommandState];
+        devState: [DevCommandState];
+        httpServerState: [HttpServerState];
+        urlDetected: [string];
+    }>;
+    close: () => Promise<void>;
+}
+export declare function devServerOrchestrator(sys: DevToolsSys, fusionConfig: FusionConfig, initialSetupState: "installed" | "not-installed" | "install-failed"): Promise<DevServerOrchestrator>;
+export declare const checkPortsListenedByPid: (pid: number) => number[];
+export declare function killProcess(sys: DevToolsSys, proc: ChildProcess | undefined, abortSignal?: AbortSignal, timeout?: number): Promise<boolean>;

package/types/cli/launch/dry-run-backup.d.ts

@@ -0,0 +1,9 @@
+import { type InitConfig } from "./InitStateMachine";
+import type { InitState } from "$/ai-utils";
+export declare const attemptDryRunBackupGit: (initConfig: InitConfig, realInitState: InitState) => Promise<{
+    success: boolean;
+    error: string;
+} | {
+    success: boolean;
+    error?: undefined;
+} | null>;

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

@@ -0,0 +1,3 @@
+export declare const isGitHubAuthError: (errorMessage: string) => boolean;
+export declare const getGitHubAuthErrorMessage: (repoName: string, hasGhToken: boolean) => string;
+export declare const getUserMessageForNpmInstallErrors: (errorOutput: string) => string;

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

@@ -0,0 +1,3 @@
+export declare const getKVHiddenComment: (key: string, value: string) => string;
+export declare const getPreviewUrl: (projectId: string, branchName: string) => string;
+export declare const getInitialDescription: (projectId: string, branchName: string) => string;

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

@@ -0,0 +1,4 @@
+import type { FusionMetrics } from "$/ai-utils";
+import type { Credentials } from "cli/credentials";
+import type { DevToolsSys } from "types";
+export declare function pushMetrics(sys: DevToolsSys, credentials: Credentials, body: FusionMetrics): Promise<void>;

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

@@ -0,0 +1,15 @@
+import type { FusionConfig } from "$/ai-utils";
+import type { DevToolsSys } from "types";
+export declare const getCommandWithShellArgs: (command: string, shell: string) => string[];
+export declare const isInRemoteContainer: () => boolean;
+export declare const getVolumePath: (fusionConfig: FusionConfig) => string;
+export declare function computeAIBranchName(featureBranch: string, sessionId: string): string;
+export declare const getAndParseGitRepoInfo: ({ sys, gitWorkingDirectory, strict, }: {
+    sys: DevToolsSys;
+    gitWorkingDirectory: string;
+    strict: boolean;
+}) => Promise<{
+    currentBranch: string;
+    featureBranch: string;
+    sessionId: string | undefined;
+}>;

package/types/cli/launch/machine-health.d.ts

@@ -0,0 +1,12 @@
+import type { DevToolsSys } from "@builder.io/dev-tools/core";
+import type { Credentials } from "../credentials";
+import type { FusionConfig, LaunchServerStatus } from "$/ai-utils";
+interface FusionStatusMonitor {
+    start: () => void;
+    stop: () => void;
+}
+/**
+ * Creates a fusion status monitor that pings the status endpoint periodically
+ */
+export declare function createFusionStatusMonitor(sys: DevToolsSys, credentials: Credentials, fusionConfig: FusionConfig, sharedState: LaunchServerStatus): FusionStatusMonitor | null;
+export {};

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

@@ -0,0 +1,3 @@
+import { type RequestHandler } from "http-proxy-middleware";
+import type { DevToolsSys } from "types";
+export declare const createProxy: (serverUrl: string, sys: DevToolsSys) => RequestHandler;

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

@@ -0,0 +1,20 @@
+import type { Express } from "express";
+import type { LaunchServerStatus } from "$/ai-utils";
+export declare const BUILDER_ENDPOINT_PREFIX = "/_builder.io";
+export declare const BUILDER_API_ENDPOINT_PREFIX: string;
+/**
+ * Endpoints that are not authenticated because they are used by the fly.io health check.
+ */
+export declare const NON_AUTHENTICATED_ENDPOINTS: {
+    readonly STATUS: "/status";
+    readonly PROXY_STATUS: "/proxy-status";
+    readonly STATUS_V2: "/status-v2";
+    readonly INIT_LOGS: "/init-logs";
+};
+export declare const configureServer: ({ app, validBuilderPrivateKey, authenticateProxy, isLocal, sharedState, }: {
+    app: Express;
+    validBuilderPrivateKey: string | undefined;
+    authenticateProxy: boolean;
+    isLocal: boolean;
+    sharedState: LaunchServerStatus;
+}) => void;

package/types/cli/launch.d.ts

@@ -0,0 +1,90 @@
+import type { DevToolsSys } from "@builder.io/dev-tools/core";
+import type { CLIArgs } from "./index";
+/**
+ * Large random-ish port number that is unlikely to be used
+ */
+export declare const PROXY_PORT = 48752;
+export interface LaunchArgs extends CLIArgs {
+    /** Project ID for the dev server. Only needed when running in a remote container. */
+    projectId?: string;
+    /** Branch name for the dev server. Only needed when running in a remote container. */
+    branchName?: string;
+    /** Silent mode for launch command */
+    silent?: boolean;
+    /** Port number for the dev server */
+    port?: number;
+    /** Port number for the dev server (shorthand) */
+    p?: number;
+    /** Dev server command to execute */
+    command?: string;
+    /** Install command to execute */
+    installCommand?: string;
+    /** Dev server command to execute (shorthand) */
+    c?: string;
+    /** Dev server URL to proxy to (alternative to command + port) */
+    serverUrl?: string;
+    /** Use development server instead of production for launch command */
+    dev?: boolean;
+    /** Use native builder:// protocol instead of https:// */
+    app?: boolean;
+    /** Skip browser auto-open (flag form) */
+    open?: boolean;
+    /**
+     * If true, CLI will run the init command instead of the launch command.
+     *
+     * @default false
+     */
+    fusionInit?: boolean;
+    /**
+     * If true, CLI will be interactive and prompt the user for input.
+     *
+     * @default true
+     */
+    interactive?: boolean;
+    /**
+     * Decides whether to skip authentication for the user's proxy server.
+     * Our own _builder.io/ endpoitns are always authenticated.
+     *
+     * @default false
+     */
+    authenticateProxy?: boolean;
+    /**
+     * Indicates the type of docker image the CLI is running on.
+     *
+     * @default "node"
+     */
+    dockerImageType?: "fusion-starter" | "node";
+    /**
+     * Output structured JSON data.
+     * Useful for programmatic consumption (e.g., VSCode extensions).
+     *
+     * @default false
+     */
+    jsonOutput?: boolean;
+    /**
+     * Enable local development mode with port availability checking.
+     * When enabled, automatically finds an available port if the default is in use.
+     *
+     * @default false
+     */
+    local?: boolean;
+    /**
+     * Enable privacy mode for codegen.
+     * When enabled, encrypts sensitive data in communication with the AI service.
+     *
+     * @default false
+     */
+    privacyMode?: boolean;
+    /**
+     * Auto-detect dev server URL and port from command output.
+     * When enabled, the system will parse the dev server output to automatically
+     * detect the server URL and port instead of requiring manual configuration.
+     *
+     * @default false
+     */
+    autoDetectDevServer?: boolean;
+}
+export declare function runFusionCommand({ sys, args, }: {
+    sys: DevToolsSys;
+    args: LaunchArgs;
+}): Promise<void>;

package/types/cli/prettier.d.ts

@@ -0,0 +1,3 @@
+import builtInPrettier from "prettier";
+export declare function loadPrettier(absoluteFilePath: string | undefined): typeof builtInPrettier;
+export declare function prettierFormat(workingDirectory: string, code: string, parser: string | undefined, filePath: string | undefined): Promise<string>;

package/types/cli/repo-indexing/component-discovery.d.ts

@@ -0,0 +1,15 @@
+import type { DevToolsSys } from "../../types";
+import type { Credentials } from "../credentials";
+import type { WorkspaceConfiguration } from "$/ai-utils";
+import type { Component } from "./types";
+export declare const discoverComponents: (sys: DevToolsSys, credentials: Credentials, sessionId: string, remoteComponents: Component[], opts?: {
+    force?: boolean;
+    designSystemPackage?: string;
+    designSystemVersion?: string;
+    workspaceConfig?: WorkspaceConfiguration;
+    debug?: boolean;
+}) => Promise<{
+    numComponentsFound: number;
+    componentsToIndex: Component[];
+    discoveredComponents: Component[];
+}>;

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

@@ -0,0 +1,19 @@
+import type { DevToolsSys } from "../../types";
+import type { Credentials } from "../credentials";
+import type { Component, ComponentIssue } from "./types";
+import type { WorkspaceConfiguration } from "$/ai-utils";
+export declare const processComponent: (sys: DevToolsSys, credentials: Credentials, sessionId: string, component: Component, opts?: {
+    designSystemId?: string | null;
+    designSystemPackage?: string;
+    designSystemVersion?: string;
+    retriesAllowed?: number;
+    workspaceConfig?: WorkspaceConfiguration;
+    debug?: boolean;
+    onIssue?: (issue: ComponentIssue) => void;
+}) => Promise<void>;
+export declare const processAgent: (sys: DevToolsSys, credentials: Credentials, discoveredComponents: Component[], opts?: {
+    designSystemId?: string | null;
+    retriesAllowed?: number;
+    debug?: boolean;
+}) => Promise<void>;
+export declare const deprecateObsoleteComponents: (credentials: Credentials, localComponents: Component[], remoteComponents: Component[]) => Promise<void>;

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

@@ -0,0 +1,41 @@
+import type { DevToolsSys } from "../../core";
+import { type Credentials } from "../credentials";
+import type { DesignSystem, GenerateUserMessage, WorkspaceConfiguration, StoreComponentDocsInput, UpdateDesignSystemInput, DesignSystemScope, DisplayDesignSystem } from "$/ai-utils";
+export declare const AGENT_FILE = "AGENTS.md";
+export declare const REPO_INDEXING_FOLDER = "repo-indexing";
+export interface UserSettings {
+    isAdminInOrganization: boolean;
+    email: string;
+}
+export declare const promptForDesignSystemScope: (credentials: Credentials, userSettings: UserSettings | null) => Promise<DesignSystemScope | undefined>;
+export declare const parseDesignSystem: (sys: DevToolsSys, designSystemPackage?: string) => Promise<{
+    name: any;
+    version: string | undefined;
+}>;
+export declare const storeComponentDocs: (credentials: Credentials, body: StoreComponentDocsInput, debug?: boolean) => Promise<any>;
+export declare const runCodeGen: (sys: DevToolsSys, credentials: Credentials, sessionId: string, message: GenerateUserMessage, debug?: boolean, designSystemPackage?: string, workspaceConfig?: WorkspaceConfiguration, opts?: {
+    tags?: object;
+    maxTokens?: number;
+}, metadata?: any) => Promise<string>;
+export declare const getAllDesignSystems: (credentials: Credentials, opts?: {
+    /**
+     * If true, only design systems that the user has permission to edit will be
+     * returned. If false, all design systems that the user has permission to edit
+     * as well as design systems that the user has permission to read but not edit
+     * will be returned. Defaults to false.
+     */
+    onlyEditAccess?: boolean;
+}) => Promise<DesignSystem[]>;
+export declare const getDisplayDesignSystems: (credentials: Credentials) => Promise<DisplayDesignSystem[]>;
+export declare const getDesignSystemsByScope: (scope: DesignSystemScope, designSystems: DesignSystem[]) => DesignSystem[];
+export declare const getDesignSystemByName: (designSystemName: string, designSystems: DesignSystem[]) => DesignSystem | null;
+export declare const getDesignSystemByNameAndScope: (credentials: Credentials, designSystemName: string, scope: DesignSystemScope, designSystems: DesignSystem[]) => DesignSystem | null;
+export declare const addDesignSystem: (credentials: Credentials, body: {
+    designSystemName: string;
+    designSystemVersion?: string;
+    designSystemPackage?: string;
+    status: string;
+    scope: DesignSystemScope;
+}) => Promise<any>;
+export declare const updateDesignSystem: (credentials: Credentials, body: UpdateDesignSystemInput) => Promise<any>;
+export declare const checkRepoIndexingFolder: (sys: DevToolsSys) => Promise<boolean>;

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

@@ -0,0 +1,24 @@
+import type { DevToolsSys } from "../../types";
+import type { CLIArgs } from "../index";
+import { type Credentials } from "../credentials";
+import type { Component, ComponentIssue } from "./types";
+export declare const displayComponentLibrarySummary: (components: Component[], indexedComponents: Component[], startTime: number, numFailed: number | undefined, isForce: boolean | undefined, designSystemName: string, issues?: ComponentIssue[]) => void;
+export interface RepoIndexingDoc {
+    name: string;
+    content: string | {
+        name: string;
+        description: string;
+        components: string[];
+        relevantFiles: string[];
+    }[];
+    createdDate: string;
+    description: string;
+    id: string;
+    ownerId: string;
+    userId: string;
+}
+export declare const runRepoIndexing: (sys: DevToolsSys, args: CLIArgs) => Promise<void>;
+export declare const isFeatureAllowed: (credentials: Credentials, debug?: boolean) => Promise<{
+    isAllowed: boolean;
+    reason?: string;
+}>;

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

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

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

@@ -0,0 +1,17 @@
+export interface Component {
+    id?: string;
+    name: string;
+    description: string;
+    relatedComponents: string[];
+    relevantFiles: string[];
+    designSystemPackage?: string;
+    designSystemVersion?: string;
+    hash?: string;
+    designSystemId?: string | null;
+    tokens?: number;
+}
+export interface ComponentIssue {
+    componentName: string;
+    error: string;
+    sessionId: string;
+}

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

@@ -0,0 +1,2 @@
+import type { DevToolsSys } from "../core";
+export declare const parseDesignSystemVersion: (sys: DevToolsSys, designSystemPackage: string) => Promise<string | null | undefined>;

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

@@ -0,0 +1,17 @@
+import type { DevToolsSys } from "../types";
+import type { CLIArgs } from "./index";
+export interface RepoIndexingDoc {
+    name: string;
+    content: string | {
+        name: string;
+        description: string;
+        components: string[];
+        relevantFiles: string[];
+    }[];
+    createdDate: string;
+    description: string;
+    id: string;
+    ownerId: string;
+    userId: string;
+}
+export declare const runRepoIndexing: (sys: DevToolsSys, args: CLIArgs) => Promise<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/report/figma-report.d.ts

@@ -0,0 +1,54 @@
+import type { FigmaComponentInfo } from "$/ai-utils";
+import type { CLIArgs } from "..";
+import type { DevToolsSys } from "../../core";
+import type { PublishedComponent, PublishedComponentSet } from "@figma/rest-api-spec";
+type Context = {
+    sys: DevToolsSys;
+    args: CLIArgs;
+    debug: (msg: unknown) => void;
+    figmaAuth: {
+        access_token: string;
+        oauth: boolean;
+    };
+};
+/**
+ * A component or component set
+ */
+type FigmaTeamComponent = {
+    /** The unique identifier for the component. */
+    key: string;
+    /** The unique identifier of the Figma file that contains the component. */
+    file_key: string;
+    /** The unique identifier of the component node within the Figma file. */
+    node_id: string;
+    /** A URL to a thumbnail image of the component. */
+    thumbnail_url?: string;
+    /** The name of the component. */
+    name: string;
+    /** The description of the component as entered by the publisher. */
+    description: string;
+    /** The component data. */
+    componentData?: FigmaComponentInfo;
+    /** Whether the component is published. */
+    isPublished?: boolean;
+};
+export declare function extractFigmaIds(url: string): {
+    teamId?: string;
+    fileKey?: string;
+    nodeId?: string;
+};
+export declare function fetchTeamComponents(context: Context, teamId: string, onProgress: () => void): Promise<PublishedComponent[]>;
+export declare function fetchTeamComponentSets(context: Context, teamId: string, onProgress: () => void): Promise<PublishedComponentSet[]>;
+/**
+ * Returns a list of components and component sets that are present in the file or selection as
+ * well as a set of remote keys for components that are referenced but not present.
+ */
+export declare function processFileOrSelection(context: Context, fileKey: string, nodeId?: string): Promise<{
+    fileComponents: FigmaTeamComponent[];
+    remoteKeys: Set<string>;
+}>;
+export declare function fetchRemoteComponentData(context: Context, remoteKeys: Set<string>): Promise<(FigmaTeamComponent | undefined)[]>;
+export declare function resolveComponentData(context: Context, components: FigmaTeamComponent[]): Promise<FigmaTeamComponent[]>;
+export declare function generateComponentReport(component: FigmaTeamComponent, baseDir: string): Promise<void>;
+export declare const runFigmaReport: (sys: DevToolsSys, args: CLIArgs) => Promise<void>;
+export {};

package/types/cli/server-ws.d.ts

@@ -0,0 +1,50 @@
+import type { Duplex } from "node:stream";
+import type { IncomingMessage } from "node:http";
+export type SocketRequest = {
+    id: number;
+    jsonrpc: string;
+    method: string;
+    params: any;
+};
+export type SocketResponse<T = any> = {
+    id?: number | null;
+    jsonrpc: string;
+    result?: T;
+    notification?: string;
+    params?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+};
+export type SocketSendOptions = {
+    timeout?: number;
+};
+export type SocketQueue = {
+    type: "request" | "notification";
+    result?: SocketResponse["result"];
+    error?: SocketResponse["error"];
+};
+import type { ServerOptions } from "ws";
+import type { WebSocket } from "ws";
+type RegisterFn<T = any> = (params: T, socketId: string) => Promise<any> | any;
+type SocketEvents = {
+    listening: () => Promise<void> | void;
+    connection: (socket: WebSocket, socketId: string) => Promise<void> | void;
+    disconnection: (socketId: string) => Promise<void> | void;
+    error: (error: Error) => Promise<void> | void;
+    "socket-error": (socketId: string, error: Error) => Promise<void> | void;
+    close: () => Promise<void> | void;
+};
+export declare function RPCWebSocketServer(opts: ServerOptions): {
+    on: <EventKey extends keyof SocketEvents>(event: EventKey, cb: SocketEvents[EventKey]) => void;
+    event: (e: string) => void;
+    handleUpgrade: (req: IncomingMessage, socket: Duplex, upgradeHead: Buffer, callback?: (client: WebSocket, request: IncomingMessage) => void) => Promise<void>;
+    clients: () => Map<string, WebSocket>;
+    register: <T = any>(method: string, fn: RegisterFn<T>) => void;
+    emit: (name: string, ...params: any[]) => void;
+    notify: (name: string, socketId: string, ...params: any[]) => void;
+    close: () => Promise<unknown>;
+};
+export {};

package/types/cli/spinner.d.ts

@@ -0,0 +1,6 @@
+export declare const spinner: () => {
+    start: (msg?: string) => void;
+    stop: (msg?: string, code?: number) => void;
+    message: (msg?: string) => void;
+    extra: (msg?: string) => void;
+};

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

@@ -0,0 +1,21 @@
+import type { AddCliOptions, DevToolsSys, FileNode, SyncInfo } from "../types";
+export declare function extractSignatureInfo(content: string): {
+    contentId?: string;
+    sessionKey?: string;
+    snippetId?: string;
+};
+export interface GetAllProjectFilesOptions {
+    basePath: string;
+    globPattern?: string | string[];
+    extraIgnorePatterns?: string[];
+    dot?: boolean;
+    deep?: number;
+    gitignore?: boolean;
+}
+export declare function getAllProjectFiles({ basePath, globPattern, extraIgnorePatterns, dot, deep, gitignore, }: GetAllProjectFilesOptions): Promise<string[]>;
+export declare function findBuilderFiles(basePath: string, targetContentId: string, targetSessionKey: string): Promise<FileNode[]>;
+export declare function filterNonImportantFiles(files: string[]): string[];
+export declare function getIgnorePatterns(basePath: string): (path: string) => boolean;
+export declare function watchDirectory(basePath: string, syncInfo: SyncInfo, onChange: (updatedSyncInfo: SyncInfo) => void): () => Promise<void>;
+export declare function setupSyncServer(sys: DevToolsSys, initialSyncInfo?: SyncInfo): Promise<void>;
+export declare function syncCommand(opts: AddCliOptions): Promise<SyncInfo | undefined>;

package/types/cli/track.d.ts

@@ -0,0 +1,5 @@
+import * as Amplitude from "@amplitude/analytics-node";
+import * as Sentry from "@sentry/node";
+export declare function initTracking(verbose: boolean): Promise<typeof Sentry>;
+export declare function track(eventName: string, options: Record<string, any>): Promise<Amplitude.Types.Result>;
+export declare function setUserId(id: string): Promise<void>;

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

@@ -0,0 +1 @@
+export declare const COMPONENT_GROUP_MDX_PROMPT = "# Component Documentation Generation\n\n## Objective\nGenerate comprehensive MDX documentation for a specific component, analyzing their interfaces, relationships, and usage patterns using the relevant files provided in the input.\n\n## Instructions\n\n### 1. Component Analysis\nFor the given component, 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{{COMPONENT_NAME}} has the following related components: {{RELATED_COMPONENTS}}\nThe following files are associated with {{COMPONENT_NAME}}: {{FILE_LIST}}\n\n### 2. Documentation Structure\nCreate comprehensive documentation covering:\n- **Component 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 component 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# {{COMPONENT_NAME}}\n\n## Overview\n\n### Purpose\n{{COMPONENT_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 components with coupling:]\n- Required parent-child relationships\n- Shared context dependencies  \n- Communication patterns between components\n- Related components\n\n## Components\n\n### [PrimaryComponent] {Primary Component for components with coupling}\n[Mark the main/root component for coupled components]\n\n**Purpose:** [What this specific component does]\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 components)\n  property: string; // Description of what this prop does\n  onAction?: () => void; // Optional callback description\n}\n```\n\n**Dependencies:** [For coupled components - what this component requires]\n**Provides:** [For coupled components - 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 components */}\n    </[PrimaryComponent]>\n  );\n}\n```\n\n### [DependentComponent] {Dependent Component for components with coupling}\n[Mark components that depend on the primary component]\n\n**Purpose:** [What this specific component does]\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 components\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 components}\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 components}\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 components}\n\n### Data Flow\n[Explain how data flows between the component and related components}\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 component's architecture]\n\n### Accessibility {When relevant}\n- [ARIA relationships between components]\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 component name: `{{COMPONENT_NAME_KEBAB}}.mdx`\n- Place in `repo-indexing/` folder\n- Example: `repo-indexing/{{COMPONENT_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 component description** - Expand on the provided description with specific use cases and implementation guidance\n4. **Document interdependencies** - For coupled components, 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 components, 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/{{COMPONENT_NAME_KEBAB}}.mdx`. You must use the Write tool in your response.";