feat: enhance release management with storage integration and verbose error handling

- Introduced `StorageClient` for uploading and downloading release snapshots to/from Firebase Storage.
- Updated `release create` command to upload snapshots and store their paths in Firestore.
- Enhanced error handling in release commands to provide verbose output for debugging.
- Modified README to reflect new command options and clarify the release creation process.
- Added tests for storage client functionality and updated existing tests to accommodate changes in snapshot handling.

Author: sharjeelyunus

README.md

@@ -98,10 +98,12 @@ To release a new version, go to GitHub → Actions → run the workflow **Releas
 - **release create** — `--app <alias>` — App alias (default: `default`)
 - **release create** — `-m, --message <msg>` — Release message (skips prompt)
 - **release create** — `-y, --yes` — Skip message prompt (use empty message)
+- **release create** — `--verbose` — Show full Firestore/Storage error response text (debugging)
 - **release list** — `--app <alias>` — App alias (default: `default`)
 - **release list** — `--limit <n>` — Maximum number of releases to show (default: 20)
 - **release list** — `--json` — Print releases as machine-readable JSON (for scripts)
 - **release use** — `--app <alias>` — App alias (default: `default`)
+- **release use** — `--hash <hash>` — Non-interactive: use release by hash
 - **release use** — `--hash <hash>` — Non-interactive: use release by hash (printed by `release list`)
 
 ### `ensemble add`
@@ -158,14 +160,12 @@ To release a new version, go to GitHub → Actions → run the workflow **Releas
 
 You can save and use snapshots of your app state in the cloud:
 
-- **Create a release from cloud:** After you have pushed and verified that the app is working as expected, run **`ensemble release create`** to save a snapshot (release) of the **current cloud state** with an optional message.
+- **Create a release from local state:** After you have local changes you want to “tag”, run **`ensemble release create`** to save a snapshot (release) of the **current local app state** with an optional message.
 - **List releases:** Run **`ensemble release list`** to see recent releases.
 - **Use a release locally:** Run **`ensemble release use`** to choose a release and update **local files only** to that snapshot. Then run **`ensemble push`** to apply that state to the cloud.
 
 When you run `ensemble release` **without a subcommand** in an interactive terminal, the CLI opens an interactive menu that lets you choose between **create**, **list**, and **use**. In non-interactive environments (e.g. CI), you must call an explicit subcommand such as `ensemble release list` or `ensemble release use --hash <hash>`.
 
-Releases are retained for **30 days**; after that they are deleted automatically by Firestore TTL.
-
 ### Exit codes
 
 - `0` — Command completed successfully (including “Up to date. Nothing to push/pull.”).

src/cloud/firestoreClient.ts

@@ -173,6 +173,7 @@ type FirestoreValue =
   | { stringValue: string }
   | { booleanValue: boolean }
   | { timestampValue: string }
+  | { integerValue: string }
   | { mapValue: { fields: Record<string, FirestoreValue> } }
   | { referenceValue: string };
 
@@ -200,20 +201,19 @@ export interface VersionMetadata {
   createdAt: string;
   createdBy: { name: string; email?: string; id: string };
   expiresAt: string;
+  snapshotPath: string;
 }
 
-/** Full version doc as returned by getVersion (metadata + snapshot). */
-export interface VersionDoc extends VersionMetadata {
-  snapshot: CloudApp;
-}
+/** Version doc metadata (snapshot stored in Storage). */
+export type VersionDoc = VersionMetadata;
 
 export interface CreateVersionParams {
   message: string;
   createdAt: string;
   createdBy: { name: string; email?: string; id: string };
   /** Must be Firestore Timestamp (e.g. 30 days from now). Use ISO string for timestampValue. */
   expiresAt: string;
-  snapshot: CloudApp;
+  snapshotPath: string;
 }
 
 const ALLOWED_ROLES = new Set(['write', 'owner']);
@@ -1114,7 +1114,7 @@ export async function createVersion(
     createdAt: { timestampValue: params.createdAt },
     expiresAt: { timestampValue: params.expiresAt },
     ...(createdByVal && { createdBy: createdByVal }),
-    snapshot: { stringValue: JSON.stringify(params.snapshot) },
+    snapshotPath: { stringValue: params.snapshotPath },
   };
 
   logDebug(options, {
@@ -1157,15 +1157,18 @@ function parseVersionDoc(doc: FirestoreDocument): VersionDoc | null {
     name: 'Unknown',
     id: '',
   };
-  const snapshotStr = parseFirestoreString(fields.snapshot as { stringValue?: string });
-  let snapshot: CloudApp;
-  try {
-    snapshot = JSON.parse(snapshotStr ?? '{}') as CloudApp;
-  } catch {
-    return null;
-  }
   if (createdAt === undefined || expiresAt === undefined) return null;
-  return { id, message, createdAt, createdBy, expiresAt, snapshot };
+  const snapshotPath = parseFirestoreString(fields.snapshotPath as { stringValue?: string });
+  if (!snapshotPath) return null;
+
+  return {
+    id,
+    message,
+    createdAt,
+    createdBy,
+    expiresAt,
+    snapshotPath,
+  };
 }
 
 export interface ListVersionsResult {
@@ -1276,33 +1279,13 @@ export async function getVersion(
     throw await toFirestoreError('get version', res, options);
   }
 
-  const doc = (await res.json()) as { name?: string; fields?: Record<string, FirestoreValue> };
-  const fields = doc?.fields ?? {};
-  const id = getDocId(doc.name ?? '');
-  const message = parseFirestoreString(fields.message as { stringValue?: string }) ?? '';
-  const createdAt = parseFirestoreTimestamp(fields.createdAt as { timestampValue?: string }) ?? '';
-  const expiresAt = parseFirestoreTimestamp(fields.expiresAt as { timestampValue?: string }) ?? '';
-  const createdBy = parseUpdatedBy(fields.createdBy as { referenceValue?: string }) ?? {
-    name: 'Unknown',
-    id: '',
-  };
-  const snapshotStr = parseFirestoreString(fields.snapshot as { stringValue?: string });
-  let snapshot: CloudApp;
-  try {
-    snapshot = JSON.parse(snapshotStr ?? '{}') as CloudApp;
-  } catch {
+  const doc = (await res.json()) as FirestoreDocument;
+  const parsed = parseVersionDoc(doc);
+  if (!parsed) {
     throw new FirestoreClientError({
       code: 'UNKNOWN',
-      message: 'Version snapshot data is invalid.',
+      message: 'Version metadata is invalid.',
     });
   }
-
-  return {
-    id,
-    message,
-    createdAt,
-    createdBy,
-    expiresAt,
-    snapshot,
-  };
+  return parsed;
 }

src/cloud/storageClient.ts

@@ -0,0 +1,94 @@
+import { getEnsembleFirebaseProject } from '../config/env.js';
+
+export class StorageClientError extends Error {
+  status?: number;
+  hint?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  cause?: any;
+
+  constructor(params: { message: string; status?: number; hint?: string; cause?: unknown }) {
+    super(params.message);
+    this.name = 'StorageClientError';
+    this.status = params.status;
+    this.hint = params.hint;
+    this.cause = params.cause;
+  }
+}
+
+export interface UploadReleaseSnapshotResult {
+  bucket: string;
+  objectPath: string;
+}
+
+function objectPathForRelease(appId: string, versionId: string): string {
+  return `releases/${appId}/${versionId}.json`;
+}
+
+function storageAuthHeader(idToken: string): string {
+  // Firebase Storage v0 API accepts Firebase Auth tokens.
+  // Note: This is different from Google Cloud Storage OAuth tokens.
+  return `Firebase ${idToken}`;
+}
+
+async function toStorageError(context: string, res: Response): Promise<StorageClientError> {
+  const text = await res.text();
+  return new StorageClientError({
+    message: `Storage ${context} failed (${res.status})`,
+    status: res.status,
+    hint:
+      res.status === 401 || res.status === 403
+        ? 'Authentication/authorization failed for Storage. Check your login session and Storage rules/IAM.'
+        : undefined,
+    cause: text.slice(0, 500),
+  });
+}
+
+export async function uploadReleaseSnapshot(
+  appId: string,
+  idToken: string,
+  versionId: string,
+  snapshotJson: string
+): Promise<UploadReleaseSnapshotResult> {
+  const bucket = `${getEnsembleFirebaseProject()}.appspot.com`;
+  const objectPath = objectPathForRelease(appId, versionId);
+  const url = `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(
+    bucket
+  )}/o?uploadType=media&name=${encodeURIComponent(objectPath)}`;
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: storageAuthHeader(idToken),
+      'Content-Type': 'application/json',
+    },
+    body: snapshotJson,
+  });
+
+  if (!res.ok) {
+    throw await toStorageError('upload release snapshot', res);
+  }
+
+  return { bucket, objectPath };
+}
+
+export async function downloadReleaseSnapshotJson(
+  idToken: string,
+  snapshotPath: string
+): Promise<string> {
+  const bucket = `${getEnsembleFirebaseProject()}.appspot.com`;
+  const url = `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(
+    bucket
+  )}/o/${encodeURIComponent(snapshotPath)}?alt=media`;
+
+  const res = await fetch(url, {
+    headers: {
+      Authorization: storageAuthHeader(idToken),
+    },
+  });
+
+  if (!res.ok) {
+    throw await toStorageError('download release snapshot', res);
+  }
+
+  return await res.text();
+}

src/commands/release.ts

@@ -1,3 +1,4 @@
+import crypto from 'crypto';
 import prompts from 'prompts';
 
 import {
@@ -10,6 +11,11 @@ import {
   type FirestoreClientOptions,
   type VersionDoc,
 } from '../cloud/firestoreClient.js';
+import {
+  downloadReleaseSnapshotJson,
+  StorageClientError,
+  uploadReleaseSnapshot,
+} from '../cloud/storageClient.js';
 import { applyCloudStateToFs } from '../core/applyToFs.js';
 import { buildDocumentsFromParsed } from '../core/buildDocuments.js';
 import { ArtifactProps, type ArtifactProp } from '../core/artifacts.js';
@@ -26,6 +32,8 @@ export interface ReleaseCreateOptions {
   message?: string;
   /** Skip message prompt (use empty message) */
   yes?: boolean;
+  /** Show verbose error details */
+  verbose?: boolean;
 }
 
 export interface ReleaseListOptions {
@@ -113,6 +121,12 @@ export async function releaseCreateCommand(options: ReleaseCreateOptions = {}):
   };
 
   try {
+    const snapshotJson = JSON.stringify(snapshot);
+    const versionId = crypto.randomUUID().replace(/-/g, '');
+    const upload = await withSpinner('Uploading snapshot to storage...', () =>
+      uploadReleaseSnapshot(appId, idToken, versionId, snapshotJson)
+    );
+
     await createVersion(
       appId,
       idToken,
@@ -121,7 +135,7 @@ export async function releaseCreateCommand(options: ReleaseCreateOptions = {}):
         createdAt: now.toISOString(),
         createdBy: { name: session.name ?? 'User', id: userId },
         expiresAt,
-        snapshot,
+        snapshotPath: upload.objectPath,
       },
       firestoreOptions
     );
@@ -130,6 +144,19 @@ export async function releaseCreateCommand(options: ReleaseCreateOptions = {}):
     if (err instanceof FirestoreClientError) {
       ui.error(err.message);
       if (err.hint) ui.note(err.hint);
+      if (options.verbose && err.cause) {
+        ui.note('Firestore response:');
+        // eslint-disable-next-line no-console
+        console.log(typeof err.cause === 'string' ? err.cause : String(err.cause));
+      }
+    } else if (err instanceof StorageClientError) {
+      ui.error(err.message);
+      if (err.hint) ui.note(err.hint);
+      if (options.verbose && err.cause) {
+        ui.note('Storage response:');
+        // eslint-disable-next-line no-console
+        console.log(typeof err.cause === 'string' ? err.cause : String(err.cause));
+      }
     } else {
       ui.error(err instanceof Error ? err.message : String(err));
     }
@@ -339,10 +366,15 @@ export async function releaseUseCommand(options: ReleaseUseOptions = {}): Promis
       }
     }
 
+    const snapshotJson = await withSpinner('Downloading snapshot...', () =>
+      downloadReleaseSnapshotJson(idToken, versionDoc.snapshotPath)
+    );
+    const snapshot = JSON.parse(snapshotJson) as CloudApp;
+
     const localFiles = await collectAppFiles(projectRoot);
     const appHome = appConfig.appHome as string | undefined;
     await withSpinner('Writing local files...', () =>
-      applyCloudStateToFs(projectRoot, versionDoc.snapshot, localFiles, enabledByProp, {
+      applyCloudStateToFs(projectRoot, snapshot, localFiles, enabledByProp, {
         manifestOptions: { appHomeFromConfig: appHome },
         onProgress: (completed, total) => {
           if (total > 0 && completed % 25 === 0) {

src/core/manifest.ts

@@ -25,13 +25,24 @@ export interface BuildManifestOptions {
   homeScreenNameOverride?: string;
 }
 
-/** Preserve existing manifest entries by name; only add minimal { name } for new ones. */
+/** Preserve existing manifest entries by name and order; only add minimal { name } for new ones. */
 function mergeByName<T extends { name: string }>(
   existing: T[] | undefined,
   cloudNames: string[]
 ): T[] {
-  const existingByName = new Map((existing ?? []).map((e) => [e.name, e]));
-  return cloudNames.map((name) => existingByName.get(name) ?? ({ name } as T));
+  const existingList = existing ?? [];
+  const cloudNameSet = new Set(cloudNames);
+
+  // 1. Keep existing entries that still exist in cloud, in the same order as manifest.
+  const keptExisting: T[] = existingList.filter((e) => cloudNameSet.has(e.name));
+
+  // 2. Append any new cloud names that are not already present.
+  const keptNames = new Set(keptExisting.map((e) => e.name));
+  const appended: T[] = cloudNames
+    .filter((name) => !keptNames.has(name))
+    .map((name) => ({ name }) as T);
+
+  return [...keptExisting, ...appended];
 }
 
 export function buildManifestObject(