builder.io 1.9.9 → 1.9.11

package/types/cli/backup.d.ts

@@ -26,11 +26,34 @@ export interface BackupGitRepoResultInvalid {
     reason: "project_removed";
 }
 export type BackupGitRepoResult = BackupGitRepoResultValid | BackupGitRepoResultInvalid;
+/**
+ * Creates a backup of git repository changes made by the AI system.
+ *
+ * This function handles both partial and full backups:
+ * - Partial backups: Only include commits created locally (on aiBranch) that aren't in upstream.
+ *   This keeps backups small and doesn't store the entire repo's code. Requires a clone from
+ *   upstream plus applying the backup to restore.
+ * - Full backups: Complete repo backup that can be directly cloned from.
+ *
+ * The aiBranch is where the AI creates commits as work progresses, while featureBranch
+ * is the base branch where work started (usually "main").
+ */
 export declare function backupGitRepo({ sys, credentials, projectId, branchName, repoPath, aiBranch, featureBranch, workspace, originalRepoUrl, debug, }: BackupGitRepoOptions): Promise<BackupGitRepoResult>;
 interface InitialCommitHashResult {
+    initialBranch: string;
     initialCommitHash: string;
     partial: boolean;
 }
+/**
+ * Determines the initial commit hash and whether to create a partial or full backup.
+ *
+ * Partial backups are preferred to keep backup sizes small, but full backups are needed when:
+ * - The repo is an example/starter template (users can't push to origin, need to fork)
+ * - There's no origin remote configured
+ *
+ * For partial backups, we fetch the latest state of the feature branch from origin
+ * to ensure the backup has the correct commit range reference.
+ */
 export declare function getInitialCommitHash({ sys, repoPath, featureBranch, debug, workspace, }: {
     sys: DevToolsSys;
     repoPath: string;
@@ -60,19 +83,30 @@ export interface GitBackupDownloadResultInvalid {
 }
 export type GitBackupDownloadResult = GitBackupDownloadResultValid | GitBackupDownloadResultInvalid;
 /**
- * Downloads a git backup bundle
- * @returns The path to the downloaded bundle file, or null if no backup exists
+ * Downloads a git backup bundle from remote storage.
+ * Handles both empty backups (no bundle file) and regular backups with bundle files.
+ * @returns The path to the downloaded bundle file, or undefined if it's an empty backup
  */
 export declare function downloadGitBackup(sys: DevToolsSys, response: BackupMetadata): Promise<GitBackupDownloadResult>;
 /**
- * Uploads a file stream to a signed URL
+ * Uploads a file stream to a signed URL (Google Cloud Storage).
+ * Uses MD5 hash for content verification as required by GCS.
  */
 export declare function uploadFileStream(filePath: string, signedUrl: string, size: number, contentMd5: string): Promise<Response>;
 export declare function computeMD5Hash(bundlePath: string): Promise<{
     contentMd5: string;
     size: number;
 }>;
+/**
+ * Updates the last commit hash in the database for tracking purposes.
+ * This is called frequently throughout the codebase (after every commit creation)
+ * to track the current state and determine if backups are up-to-date.
+ */
 export declare function setLastCommit(sys: DevToolsSys, credentials: Credentials, data: CodegenSetLastCommit, verbose: boolean): Promise<any>;
+/**
+ * Computes a unique backup reference string that combines version, repo URL, and commit hash.
+ * This reference can be used to identify and retrieve specific backups.
+ */
 export declare function computeBackupRef(input: {
     version: string | undefined;
     originalRepoUrl: string | undefined;

package/types/cli/codegen.d.ts

@@ -77,7 +77,7 @@ export declare class CodeGenSession {
     needsBackup(): Promise<boolean>;
     uploadBackup(): Promise<import("./backup").BackupGitRepoResultValid | import("./backup").BackupGitRepoResultInvalid | {
         success: boolean;
-        error: Error;
+        error: unknown;
     }>;
     getCommitMode(): CommitMode | undefined;
     setCommitMode(commitMode: CommitMode): void;
@@ -271,7 +271,11 @@ export declare class CodeGenSession {
      * @returns True if the delete was successful, false otherwise
      */
     deleteFile(filePath: string): Promise<boolean>;
-    getNetLinesChanged(): number;
+    getLinesStats(): {
+        net: number;
+        added: number;
+        removed: number;
+    };
     /**
      * Get git diff between current commit and remote branch
      * If remote current branch doesn't exist, gets diff between default branch and current branch