feat: implement asset upload and management in CLI push command

- Enhanced the `submitCliPush` function to support optional asset uploads alongside Firestore YAML operations.
- Introduced new interfaces for handling asset upload parameters and results.
- Updated the `pushCommand` to include asset upload logic, ensuring assets are uploaded only when necessary.
- Added functionality to collect asset filenames and integrate them into the push process.
- Implemented tests to verify asset upload behavior and integration with existing commands.

Author: sharjeelyunus

src/cloud/firestoreClient.ts

@@ -5,6 +5,7 @@
 
 import type {
   ApplicationDTO,
+  AssetDTO,
   WidgetDTO,
   ScriptDTO,
   ActionDTO,
@@ -15,6 +16,7 @@ import type {
 import { EnsembleDocumentType } from '../core/dto.js';
 import { getArtifactConfig, type ArtifactProp } from '../core/artifacts.js';
 import { processWithConcurrency } from '../core/concurrency.js';
+import { uploadProjectAssetsForPush } from '../core/pushAssets.js';
 import { getEnsembleFirebaseProject } from '../config/env.js';
 
 const DEFAULT_FIRESTORE_CONCURRENCY = 15;
@@ -192,6 +194,7 @@ export type CloudApp = Pick<
   | 'screens'
   | 'theme'
   | 'translations'
+  | 'assets'
 >;
 
 /** Metadata for a saved version (commit); snapshot stored in same doc. */
@@ -430,16 +433,27 @@ async function applyYamlOperationsForKind(
   );
 }
 
+/** Optional local asset uploads after Firestore YAML apply (studio cloud function + .env.config). */
+export interface CliPushExtras {
+  projectRoot: string;
+  assetFileNames?: string[];
+}
+
+export interface CliPushResult {
+  assetsUploaded: number;
+}
+
 /**
  * Apply a push payload directly to Firestore, updating YAML artifacts in-place.
- * This updates screens, widgets, scripts, translations, and theme under the app document.
+ * Optionally uploads new assets (studio-uploadAsset + .env.config) in the same operation.
  */
 export async function submitCliPush(
   appId: string,
   idToken: string,
   payload: unknown,
-  options?: FirestoreClientOptions
-): Promise<void> {
+  options?: FirestoreClientOptions,
+  extras?: CliPushExtras
+): Promise<CliPushResult> {
   const project = getEnsembleFirebaseProject();
   assertValidPushPayload(payload);
   const p = payload as PushPayloadShape;
@@ -459,6 +473,18 @@ export async function submitCliPush(
   if (p.theme) {
     await applyYamlOperationsForKind('theme', appId, idToken, project, [p.theme], options);
   }
+
+  const names = extras?.assetFileNames?.filter((n) => n.trim() !== '') ?? [];
+  if (names.length === 0 || !extras?.projectRoot) {
+    return { assetsUploaded: 0 };
+  }
+  const assetsUploaded = await uploadProjectAssetsForPush(
+    appId,
+    idToken,
+    extras.projectRoot,
+    names
+  );
+  return { assetsUploaded };
 }
 
 function parseFirestoreString(field: { stringValue?: string } | undefined): string | undefined {
@@ -731,6 +757,22 @@ function toTranslationDTO(doc: FirestoreDocument, defaultLocale: boolean): Trans
   };
 }
 
+function toAssetDTO(doc: FirestoreDocument): AssetDTO {
+  const base = firestoreDocToEnsembleBase(doc);
+  const fields = (doc.fields ?? {}) as FirestoreFields;
+  const fileName = parseFirestoreString(fields.fileName as { stringValue?: string }) ?? base.name;
+  const publicUrl = parseFirestoreString(fields.publicUrl as { stringValue?: string });
+  const copyText = parseFirestoreString(fields.copyText as { stringValue?: string });
+  return {
+    ...base,
+    name: fileName,
+    fileName,
+    type: EnsembleDocumentType.Asset,
+    ...(publicUrl !== undefined && { publicUrl }),
+    ...(copyText !== undefined && { copyText }),
+  };
+}
+
 function getCollaboratorRole(
   collaboratorsField:
     | { mapValue?: { fields?: Record<string, { stringValue?: string }> } }
@@ -984,13 +1026,15 @@ export async function fetchCloudApp(
 
   const screens: ScreenDTO[] = [];
   const translations: TranslationDTO[] = [];
+  const assets: AssetDTO[] = [];
   let theme: ThemeDTO | undefined;
   const i18nDocs: FirestoreDocument[] = [];
   for (const doc of artifacts) {
     const docId = getDocId(doc.name);
     const type = parseFirestoreString((doc.fields?.type as { stringValue?: string }) ?? undefined);
     if (type === 'screen') screens.push(toScreenDTO(doc));
     else if (type === 'i18n') i18nDocs.push(doc);
+    else if (type === 'asset') assets.push(toAssetDTO(doc));
     else if (type === 'theme') {
       if (!theme || docId === 'theme') {
         theme = toThemeDTO(doc);
@@ -1020,6 +1064,7 @@ export async function fetchCloudApp(
     screens,
     ...(theme && { theme }),
     ...(translations.length > 0 && { translations }),
+    ...(assets.length > 0 && { assets }),
   };
 }
 

src/commands/add.ts

@@ -6,6 +6,7 @@ import { loadProjectConfig } from '../config/projectConfig.js';
 import { resolveAppContext } from '../config/projectConfig.js';
 import { getValidAuthSession } from '../auth/session.js';
 import { uploadAssetToStudio } from '../cloud/assetClient.js';
+import { upsertEnvConfig } from '../core/envConfig.js';
 import { upsertManifestEntry, type RootManifest } from '../core/manifest.js';
 import { ui } from '../core/ui.js';
 import { withSpinner } from '../lib/spinner.js';
@@ -56,53 +57,6 @@ async function fileExists(filePath: string): Promise<boolean> {
   }
 }
 
-function parseEnvConfig(raw: string): {
-  lines: string[];
-  keyToLineIndex: Map<string, number>;
-} {
-  const lines = raw.split(/\r?\n/);
-  const keyToLineIndex = new Map<string, number>();
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i].trim();
-    if (!line || line.startsWith('#')) continue;
-    const eq = line.indexOf('=');
-    if (eq <= 0) continue;
-    const key = line.slice(0, eq).trim();
-    if (key) keyToLineIndex.set(key, i);
-  }
-  return { lines, keyToLineIndex };
-}
-
-async function upsertEnvConfig(
-  projectRoot: string,
-  entries: Array<{ key: string; value: string; overwrite?: boolean }>
-): Promise<void> {
-  const envPath = path.join(projectRoot, '.env.config');
-  let raw = '';
-  try {
-    raw = await fs.readFile(envPath, 'utf8');
-  } catch {
-    raw = '';
-  }
-  const parsed = parseEnvConfig(raw);
-  // Avoid introducing visual gaps when appending new entries.
-  while (parsed.lines.length > 0 && parsed.lines[parsed.lines.length - 1].trim() === '') {
-    parsed.lines.pop();
-  }
-  for (const entry of entries) {
-    const line = `${entry.key}=${entry.value}`;
-    const existingIdx = parsed.keyToLineIndex.get(entry.key);
-    if (existingIdx === undefined) {
-      parsed.lines.push(line);
-      parsed.keyToLineIndex.set(entry.key, parsed.lines.length - 1);
-    } else if (entry.overwrite !== false) {
-      parsed.lines[existingIdx] = line;
-    }
-  }
-  const normalized = parsed.lines.join('\n').replace(/\n*$/, '\n');
-  await fs.writeFile(envPath, normalized, 'utf8');
-}
-
 async function addAsset(
   projectRoot: string,
   assetPathInput: string

src/commands/push.ts

@@ -34,6 +34,31 @@ export interface PushOptions {
 
 const DESTRUCTIVE_CHANGE_PROMPT_THRESHOLD = 25;
 
+/** Firestore/YAML artifact changes only (not asset uploads via studio function). */
+function yamlArtifactChangeTotal(summary: PushSummary): number {
+  const k = summary.byKind;
+  return (
+    k.screens.created +
+    k.screens.updated +
+    k.screens.deleted +
+    k.widgets.created +
+    k.widgets.updated +
+    k.widgets.deleted +
+    k.scripts.created +
+    k.scripts.updated +
+    k.scripts.deleted +
+    k.actions.created +
+    k.actions.updated +
+    k.actions.deleted +
+    k.translations.created +
+    k.translations.updated +
+    k.translations.deleted +
+    k.theme.created +
+    k.theme.updated +
+    k.theme.deleted
+  );
+}
+
 function printPushSummary(summary: PushSummary, options: { verbose?: boolean; isNoop?: boolean }) {
   const { appName, environment, counts } = summary;
   const totalChanges = counts.created + counts.updated + counts.deleted;
@@ -60,6 +85,7 @@ function printPushSummary(summary: PushSummary, options: { verbose?: boolean; is
       ['actions', summary.byKind.actions],
       ['translations', summary.byKind.translations],
       ['theme', summary.byKind.theme],
+      ['assets', summary.byKind.assets],
     ];
 
     for (const [kind, c] of entries) {
@@ -307,9 +333,12 @@ export async function pushCommand(options: PushOptions = {}): Promise<void> {
     });
 
     const summary = plan.summary;
-    const changedCount = summary.counts.created + summary.counts.updated + summary.counts.deleted;
+    const yamlChangeTotal = yamlArtifactChangeTotal(summary);
+    const assetsToUpload = plan.diff.assets.new
+      .map((item) => (item as { fileName?: string }).fileName)
+      .filter((fn): fn is string => typeof fn === 'string' && fn.length > 0);
 
-    if (changedCount === 0) {
+    if (yamlChangeTotal === 0 && assetsToUpload.length === 0) {
       ui.info('Up to date. Nothing to push.');
       return;
     }
@@ -352,9 +381,7 @@ export async function pushCommand(options: PushOptions = {}): Promise<void> {
     let confirmed = options.yes ?? false;
     const isInteractive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
     const hasDeletes = summary.counts.deleted > 0;
-    const largeChangeSet =
-      summary.counts.created + summary.counts.updated + summary.counts.deleted >=
-      DESTRUCTIVE_CHANGE_PROMPT_THRESHOLD;
+    const largeChangeSet = yamlChangeTotal >= DESTRUCTIVE_CHANGE_PROMPT_THRESHOLD;
 
     if (!confirmed) {
       if (!isInteractive) {
@@ -365,12 +392,28 @@ export async function pushCommand(options: PushOptions = {}): Promise<void> {
         return;
       }
 
+      const yamlCreatedOrUpdated =
+        summary.byKind.screens.created +
+        summary.byKind.screens.updated +
+        summary.byKind.widgets.created +
+        summary.byKind.widgets.updated +
+        summary.byKind.scripts.created +
+        summary.byKind.scripts.updated +
+        summary.byKind.actions.created +
+        summary.byKind.actions.updated +
+        summary.byKind.translations.created +
+        summary.byKind.translations.updated +
+        summary.byKind.theme.created +
+        summary.byKind.theme.updated;
+
       const headline =
         hasDeletes || largeChangeSet
-          ? `This will delete ${summary.counts.deleted} item(s) and apply ${
-              summary.counts.created + summary.counts.updated
-            } other change(s). Continue? [y/N]`
-          : 'Proceed with push?';
+          ? `This will delete ${summary.counts.deleted} item(s) and apply ${yamlCreatedOrUpdated} other change(s)${
+              assetsToUpload.length > 0 ? `, and upload ${assetsToUpload.length} asset(s)` : ''
+            }. Continue? [y/N]`
+          : `Proceed with push${
+              assetsToUpload.length > 0 ? ` and upload ${assetsToUpload.length} asset(s)` : ''
+            }?`;
 
       const { proceed } = await prompts({
         type: 'confirm',
@@ -391,9 +434,17 @@ export async function pushCommand(options: PushOptions = {}): Promise<void> {
     }
 
     try {
-      await withSpinner('Pushing changes to cloud...', () =>
-        submitCliPush(appId, idToken, pushPayload, firestoreOptions)
-      );
+      if (yamlChangeTotal > 0 || assetsToUpload.length > 0) {
+        const { assetsUploaded } = await withSpinner('Pushing changes to cloud...', () =>
+          submitCliPush(appId, idToken, pushPayload, firestoreOptions, {
+            projectRoot: root,
+            ...(assetsToUpload.length > 0 && { assetFileNames: assetsToUpload }),
+          })
+        );
+        if (assetsUploaded > 0) {
+          ui.success(`Uploaded ${assetsUploaded} asset(s) and updated .env.config.`);
+        }
+      }
 
       if (manifestNeedsRefresh && bundle) {
         // Only refresh manifest when artifact changes can affect its contents.

src/commands/release.ts

@@ -118,6 +118,7 @@ export async function releaseCreateCommand(options: ReleaseCreateOptions = {}):
     ...(localApp.translations &&
       localApp.translations.length > 0 && { translations: localApp.translations }),
     ...(localApp.theme && { theme: localApp.theme }),
+    ...(localApp.assets && localApp.assets.length > 0 && { assets: localApp.assets }),
   };
 
   try {

src/core/appCollector.ts

@@ -17,6 +17,8 @@ export interface ParsedAppFiles {
   actions: Record<string, string>;
   translations: Record<string, string>;
   theme?: string;
+  /** Basenames of files under assets/ (binary files are not read into memory). */
+  assetFiles?: string[];
 }
 
 export type CollectOptions = Partial<Record<ArtifactProp, boolean>>;
@@ -36,6 +38,19 @@ async function readTextFile(filePath: string): Promise<string> {
   return fs.readFile(filePath, 'utf8');
 }
 
+async function collectAssetBasenames(rootDir: string): Promise<string[]> {
+  const assetsDir = path.join(rootDir, 'assets');
+  try {
+    const entries = await fs.readdir(assetsDir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile())
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
 export async function collectAppFiles(
   rootDir: string,
   collectOptions: CollectOptions = {},
@@ -138,6 +153,11 @@ export async function collectAppFiles(
 
   await walk(rootDir);
 
+  const assetFiles = await collectAssetBasenames(rootDir);
+  if (assetFiles.length > 0) {
+    result.assetFiles = assetFiles;
+  }
+
   reportStatus('reading', {
     rootDir,
     taskCount: tasks.length,
@@ -175,6 +195,7 @@ export async function collectAppFiles(
     scriptCount: Object.keys(result.scripts).length,
     widgetCount: Object.keys(result.widgets).length,
     translationCount: Object.keys(result.translations).length,
+    assetCount: assetFiles.length,
     hasTheme: typeof result.theme === 'string',
   });