@nu-art/build-and-install 0.401.9 → 0.500.6

package/units/implementations/firebase/Unit_FirebaseHostingApp.js

@@ -1,110 +1,45 @@
-import { ImplementationMissingException, LogLevel } from '@nu-art/ts-common';
-import { CONST_DeployHostingDir, CONST_DeploymentMetadata, CONST_FirebaseJSON, CONST_FirebaseRC, CONST_HostingBuildTarball, CONST_StagingDir, CONST_TrashDir, CONST_VersionApp } from '../../../config/consts.js';
+import { LogLevel } from '@nu-art/ts-common';
 import { Commando_Basic, Commando_NVM, CommandoException } from '@nu-art/commando';
+import { Unit_HostingApp } from './Unit_HostingApp.js';
 import { resolve } from 'path';
-import { Unit_TypescriptLib } from '../Unit_TypescriptLib.js';
-import { deployLogFilter, ensureArtifactRegistryRepository } from './common.js';
 import { FileSystemUtils } from '@nu-art/ts-common/utils/FileSystemUtils';
 /**
- * Firebase Hosting application unit.
- *
- * **Key Features**:
- * - Extends Unit_TypescriptLib (compiles TypeScript)
- * - Manages Firebase hosting configuration (firebase.json, .firebaserc)
- * - Supports multiple environments (local, staging, production)
- * - Implements launch and deploy phases
- *
- * **Phases Implemented**:
- * - `prepare()`: Resolves Firebase hosting config files
- * - `compile()`: Compiles TypeScript (without declarations)
- * - `launch()`: Starts Firebase hosting emulator
- * - `deploy()`: Deploys to Firebase hosting
- *
- * **Configuration**:
- * - `servingPort`: Port for local hosting server
- * - `hostingConfig`: Firebase hosting configuration (public folder, rewrites)
- * - `envConfig`: Environment-specific config (projectId, isLocal)
+ * Firebase Hosting application unit (webpack bundler).
+ * Extends Unit_HostingApp; implements compile via npm run build, launch via npm run start.
  */
-export class Unit_FirebaseHostingApp extends Unit_TypescriptLib {
-    hosting = {};
-    injectedMetadata = {};
-    static DefaultConfig_FirebaseHosting = {
-        servingPort: 8100,
-        output: 'dist',
-    };
+export class Unit_FirebaseHostingApp extends Unit_HostingApp {
+    static DefaultConfig_FirebaseHosting = Unit_HostingApp.DefaultConfig_Hosting;
     constructor(config) {
         super(config);
         this.addToClassStack(Unit_FirebaseHostingApp);
     }
-    //######################### Phase Implementations #########################
     async prepare() {
         await super.prepare();
-        await this.resolveHostingRC();
-        await this.resolveHostingJSON();
-        await this.resolveHostingRuntimeConfig();
+        await this.resolveWebpackEnvConfig();
     }
-    async compile() {
-        await this.resolveTSConfig(resolve(this.config.fullPath, './src'), 'main', { compilerOptions: { declaration: false } });
-        await this.clearOutputDir();
-        await this.createAppVersionFile();
-        await this.compileImpl();
-    }
-    async launch() {
-        this.setStatus('Launching');
-        await this.releaseWebpackPorts();
-        await this.runApp();
-    }
-    async releaseWebpackPorts() {
-        return this.releasePorts([`${this.config.servingPort}`]);
-    }
-    async deploy() {
-        const commando = this.allocateCommando(Commando_NVM).applyNVM()
-            .cd(this.config.fullPath)
-            .setLogLevelFilter(deployLogFilter)
-            // example: Function URL (hello(us-central1)): https://hello-kv65k7yylq-uc.a.run.app
-            .onLog(/.*Hosting URL.*(https:\/\/.*?)$/, match => {
-            this.hosting[match[1]] = match[2];
-        });
-        const debug = this.runtimeContext.runtimeParams.verbose ? ' --debug' : '';
-        await this.executeAsyncCommando(commando, `${this.npmCommand('firebase')}${debug} deploy --only hosting`);
-    }
-    //######################### ResolveConfig Logic #########################
-    getEnvConfig() {
-        const envConfig = this.config.envConfig;
-        if (!envConfig)
-            throw new ImplementationMissingException(`Missing EnvConfig in unit ${this.config.label}`);
-        return envConfig;
-    }
-    async resolveHostingRC() {
+    async resolveWebpackEnvConfig() {
         const envConfig = this.getEnvConfig();
-        const rcConfig = { projects: { default: envConfig.projectId } };
-        const targetPath = `${this.config.fullPath}/${CONST_FirebaseRC}`;
-        await FileSystemUtils.file.write.json(targetPath, rcConfig);
-    }
-    async resolveHostingJSON() {
-        const envConfig = this.getEnvConfig();
-        const targetPath = `${this.config.fullPath}/${CONST_FirebaseJSON}`;
-        let fileContent;
-        if (envConfig.isLocal)
-            fileContent = {};
-        else
-            fileContent = {
-                hosting: this.config.hostingConfig ?? {
-                    'public': 'dist',
-                    'rewrites': [
-                        { 'source': '**', 'destination': '/index.html' }
-                    ]
-                }
-            };
-        await FileSystemUtils.file.write.json(targetPath, fileContent);
-    }
-    async resolveHostingRuntimeConfig() {
-        const envConfig = this.getEnvConfig().config;
-        const targetPath = resolve(this.config.fullPath, `./src/main/config.ts`);
-        const fileContent = `export const config = ${JSON.stringify(envConfig, null, 2)};`;
+        const wp = envConfig.webpackConfig;
+        const minifyHtml = wp?.minifyHtml ?? false;
+        const devServerSSL = wp?.devServerSSL ?? false;
+        const devServerPort = wp?.devServerPort ?? this.config.servingPort;
+        const sslKey = wp?.sslKey ? `"${wp.sslKey}"` : 'undefined';
+        const sslCert = wp?.sslCert ? `"${wp.sslCert}"` : 'undefined';
+        const envName = this.runtimeContext.runtimeParams.environment ?? 'local';
+        const targetPath = resolve(this.config.fullPath, 'webpack-env.generated.ts');
+        const fileContent = [
+            `/** Generated by BAI during prepare - do not edit */`,
+            `export const webpackEnvConfig = {`,
+            `  envName: "${envName}",`,
+            `  minifyHtml: ${minifyHtml},`,
+            `  devServerSSL: ${devServerSSL},`,
+            `  devServerPort: ${devServerPort},`,
+            `  sslKey: ${sslKey},`,
+            `  sslCert: ${sslCert},`,
+            `};\n`,
+        ].join('\n');
         await FileSystemUtils.file.write(targetPath, fileContent);
     }
-    //######################### Compile Logic #########################
     async compileImpl() {
         const commando = this.allocateCommando(Commando_NVM, Commando_Basic).applyNVM()
             .cd(this.config.fullPath);
@@ -113,212 +48,15 @@ export class Unit_FirebaseHostingApp extends Unit_TypescriptLib {
                 throw new CommandoException(`Error compiling`, stdout, stderr, exitCode);
         });
     }
-    async createAppVersionFile() {
-        //Writing the file to the package source instead of the output is fine,
-        //Webpack bundles files into the output automatically!
-        const targetPath = `${this.config.fullPath}/src/main/${CONST_VersionApp}`;
-        const appVersion = this.runtimeContext.version;
-        await FileSystemUtils.file.write.json(targetPath, { version: appVersion });
-    }
-    //######################### Launch Logic #########################
     async runApp() {
         const commando = this.allocateCommando(Commando_NVM).applyNVM()
             .setUID(this.config.key)
             .cd(this.config.fullPath)
-            .setLogLevelFilter((log, type) => {
+            .setLogLevelFilter((log) => {
             if (log.toLowerCase().includes('<i>'))
                 return LogLevel.Info;
         });
         await this.executeAsyncCommando(commando, 'npm run start');
         this.logWarning('HOSTING TERMINATED');
     }
-    //######################### Build Push Image Phase #########################
-    /**
-     * Builds hosting output and uploads it to Artifact Registry as a generic package.
-     *
-     * **Process**:
-     * 1. Validates hostingDeployment config exists
-     * 2. Creates deployment-metadata.json with build information
-     * 3. Creates tarball of hosting output directory
-     * 4. Uploads to Artifact Registry as generic package
-     *
-     * **Requirements**:
-     * - `--build-push-image <tag>` CLI flag with tag value
-     * - `hostingDeployment` config in unit config with `packageName` field
-     * - `packageName` must comply with Artifact Registry naming restrictions
-     * - gcloud CLI installed and authenticated
-     * - Artifact Registry API enabled in GCP project
-     */
-    async buildPushImage() {
-        const hostingDeployment = this.config.hostingDeployment;
-        if (!hostingDeployment) {
-            throw new ImplementationMissingException(`Missing hostingDeployment config in unit ${this.config.key}`);
-        }
-        const buildTag = this.runtimeContext.runtimeParams.buildPushImage;
-        if (!buildTag) {
-            throw new ImplementationMissingException(`Missing buildPushImage runtime param in unit ${this.config.key}`);
-        }
-        const artifactRegistry = hostingDeployment.artifactRegistry;
-        const packageName = hostingDeployment.packageName;
-        if (!packageName) {
-            throw new ImplementationMissingException(`Missing packageName in hostingDeployment config for unit ${this.config.key}`);
-        }
-        this.logInfo(`Building and uploading hosting package to Artifact Registry:`);
-        this.logInfo(`  Package: ${packageName}`);
-        this.logInfo(`  Tag: ${buildTag}`);
-        // Check for dry run mode
-        if (this.runtimeContext.runtimeParams.dryRun) {
-            this.logInfo(`[DRY RUN] Would build and upload hosting package: ${packageName}:${buildTag}`);
-            return;
-        }
-        // Ensure Artifact Registry repository exists
-        const commando = this.allocateCommando();
-        await ensureArtifactRegistryRepository(commando, artifactRegistry, 'generic', this);
-        // Create deployment-metadata.json in output directory
-        const metadata = {
-            ...this.injectedMetadata,
-            'build.timestamp': new Date().toISOString(),
-            'build.tag': buildTag,
-            'build.project': artifactRegistry.projectId,
-            'build.package-name': packageName,
-            'version': this.runtimeContext.version,
-            'git.commit': process.env.GIT_COMMIT || '',
-            'git.branch': process.env.GIT_BRANCH || '',
-            'build.user': process.env.USER || '',
-        };
-        this.logDebug(`Metadata: `, metadata);
-        // Create staging directory for tarball contents
-        const buildOutputDir = resolve(this.config.fullPath, CONST_TrashDir);
-        const stagingDir = resolve(buildOutputDir, CONST_StagingDir);
-        await FileSystemUtils.folder.delete(stagingDir);
-        await FileSystemUtils.folder.create(stagingDir);
-        const tarballPath = resolve(buildOutputDir, CONST_HostingBuildTarball);
-        // Copy all files to staging directory
-        const outputDirName = resolve(this.config.output).split('/').pop() || 'dist';
-        // Copy firebase.json, .firebaserc, dist folder, and create deployment-metadata.json
-        await FileSystemUtils.folder.copy(this.config.output, resolve(stagingDir, outputDirName));
-        await FileSystemUtils.file.write.json(resolve(stagingDir, CONST_DeploymentMetadata), metadata);
-        // Create tarball from staging directory contents
-        // Note: Use explicit file list to include hidden files (.*) which * wildcard doesn't match
-        commando.cd(stagingDir);
-        await this.executeAsyncCommando(commando, `tar -czf ${tarballPath} ${CONST_DeploymentMetadata} ${outputDirName}`, (stdout, stderr, exitCode) => {
-            if (exitCode !== 0)
-                throw new CommandoException(`Failed to create tarball (exit code ${exitCode})`, stdout, stderr, exitCode);
-        });
-        this.logInfo(`Created tarball: ${tarballPath}`);
-        // Upload to Artifact Registry
-        const region = artifactRegistry.region;
-        const repository = artifactRegistry.repository;
-        const projectId = artifactRegistry.projectId;
-        // Upload file - package and version are created automatically if they don't exist
-        // Note: Generic packages don't support "latest" version like Docker images
-        // The build tag should be used for deployment (defaults to 'latest' if not specified)
-        await this.executeAsyncCommando(commando, `gcloud artifacts generic upload --package=${packageName} --version=${buildTag} --source=${tarballPath} --location=${region} --repository=${repository} --project=${projectId}`, (stdout, stderr, exitCode) => {
-            if (exitCode !== 0)
-                throw new CommandoException(`Failed to upload hosting package to Artifact Registry (exit code ${exitCode})`, stdout, stderr, exitCode);
-        });
-        this.logInfo(`Successfully uploaded hosting package: ${packageName}:${buildTag} and ${packageName}:latest`);
-    }
-    //######################### Deploy Image Phase #########################
-    /**
-     * Deploys hosting build from Artifact Registry to Firebase Hosting.
-     *
-     * **Process**:
-     * 1. Validates hostingDeployment config exists
-     * 2. Downloads tarball from Artifact Registry
-     * 3. Extracts to temp directory
-     * 4. Sets up Firebase tools (package.json + npm install)
-     * 5. Deploys to Firebase Hosting
-     * 6. Validates deployment by fetching deployment-metadata.json
-     *
-     * **Requirements**:
-     * - `--deploy-image <tag>` CLI flag with tag value
-     * - `hostingDeployment` config in unit config with `packageName` field
-     * - Package must already exist in Artifact Registry (built via buildPushImage)
-     * - gcloud CLI installed and authenticated
-     * - Firebase CLI (installed via npm in temp directory)
-     */
-    async deployImage() {
-        const hostingDeployment = this.config.hostingDeployment;
-        if (!hostingDeployment) {
-            throw new ImplementationMissingException(`Missing hostingDeployment config in unit ${this.config.key}`);
-        }
-        const deployTag = this.runtimeContext.runtimeParams.deployImage;
-        if (!deployTag) {
-            throw new ImplementationMissingException(`Missing deployImage runtime param in unit ${this.config.key}. Generic packages require a specific version tag (cannot use 'latest')`);
-        }
-        const artifactRegistry = hostingDeployment.artifactRegistry;
-        const packageName = hostingDeployment.packageName;
-        if (!packageName) {
-            throw new ImplementationMissingException(`Missing packageName in hostingDeployment config for unit ${this.config.key}`);
-        }
-        const region = artifactRegistry.region;
-        const repository = artifactRegistry.repository;
-        const projectId = artifactRegistry.projectId;
-        this.logInfo(`Deploying hosting package: ${packageName}:${deployTag}`);
-        // Check for dry run mode
-        if (this.runtimeContext.runtimeParams.dryRun) {
-            this.logInfo(`[DRY RUN] Would deploy hosting package: ${packageName}:${deployTag}`);
-            return;
-        }
-        // Setup temp directory for deployment
-        const deployTempDir = resolve(this.config.fullPath, `${CONST_TrashDir}/${CONST_DeployHostingDir}`);
-        this.logInfo(`Setting up deployment directory: ${deployTempDir}`);
-        await FileSystemUtils.folder.delete(deployTempDir);
-        await FileSystemUtils.folder.create(deployTempDir);
-        const commando = this.allocateCommando(Commando_NVM)
-            .applyNVM()
-            .cd(deployTempDir)
-            .mark();
-        // Download tarball from Artifact Registry
-        // Note: --destination must be a directory, not a file path
-        this.logInfo(`Downloading hosting package from Artifact Registry from: ${projectId}/${repository}/${packageName}/${deployTag}`);
-        await this.executeAsyncCommando(commando, `gcloud artifacts generic download --package=${packageName} --version=${deployTag} --destination=${deployTempDir} --location=${region} --repository=${repository} --project=${projectId}`, (stdout, stderr, exitCode) => {
-            if (exitCode !== 0)
-                throw new CommandoException(`Failed to download hosting package from Artifact Registry (exit code ${exitCode})`, stdout, stderr, exitCode);
-        });
-        // Find the downloaded file (gcloud downloads with auto-generated name based on package and version)
-        // The file will be named: {packageName}-{version}.tar.gz
-        this.logInfo(`Locating downloaded tarball...`);
-        const downloadedFiles = await FileSystemUtils.folder.list(deployTempDir);
-        const tarballFile = downloadedFiles.find(file => file.endsWith('.tar.gz'));
-        if (!tarballFile)
-            throw new ImplementationMissingException(`Downloaded tarball not found in ${deployTempDir}. Files found: ${downloadedFiles.join(', ')}`);
-        const tarballPath = resolve(deployTempDir, tarballFile);
-        this.logDebug(`Downloaded tarball: ${tarballPath}`);
-        // Extract tarball directly to deployTempDir (contains firebase.json, .firebaserc, and dist/)
-        this.logInfo(`Extracting hosting package...`);
-        this.logInfo(`Extracting hosting package...`);
-        await this.executeAsyncCommando(commando, `tar -xzf ${tarballPath} -C ${deployTempDir}`, (stdout, stderr, exitCode) => {
-            if (exitCode !== 0) {
-                throw new CommandoException(`Failed to extract tarball (exit code ${exitCode})`, stdout, stderr, exitCode);
-            }
-        });
-        this.logInfo(`Extracted hosting package to: ${deployTempDir}`);
-        this.logInfo(`Copying firebase configs..`);
-        const firebaseJsonPath = resolve(this.config.fullPath, CONST_FirebaseJSON);
-        const firebaseRcPath = resolve(this.config.fullPath, CONST_FirebaseRC);
-        await FileSystemUtils.file.copy(firebaseJsonPath, resolve(deployTempDir, CONST_FirebaseJSON));
-        await FileSystemUtils.file.copy(firebaseRcPath, resolve(deployTempDir, CONST_FirebaseRC));
-        this.logDebug(`Copied firebase configs!`);
-        // firebase.json and .firebaserc are already in deployTempDir from tarball extraction
-        // Deploy using firebase CLI
-        const envConfig = this.getEnvConfig();
-        this.logInfo(`Deploying to Firebase Hosting: ${deployTempDir} => ${envConfig.projectId}`);
-        const deployCommando = this.allocateCommando(Commando_NVM).applyNVM()
-            .cd(deployTempDir)
-            .setLogLevelFilter(deployLogFilter)
-            .onLog(/.*Hosting URL.*(https:\/\/.*?)$/, match => {
-            this.hosting[match[1]] = match[2];
-        });
-        const debug = this.runtimeContext.runtimeParams.verbose ? ' --debug' : '';
-        await this.executeAsyncCommando(deployCommando, `npx firebase${debug} deploy --only hosting`, (stdout, stderr, exitCode) => {
-            if (exitCode !== 0) {
-                throw new CommandoException(`Failed to deploy hosting (exit code ${exitCode})`, stdout, stderr, exitCode);
-            }
-        });
-        this.logInfo(`Hosting deployed: `, this.hosting);
-        // Cleanup temp directory (optional - keep for debugging)
-        // await FileSystemUtils.folder.delete(deployTempDir);
-    }
 }

package/units/implementations/firebase/Unit_HostingApp.d.ts

@@ -0,0 +1,59 @@
+import { FirebasePackageConfig } from '../../../config/types/package/package.js';
+import { UnitPhaseImplementor } from '../../../core/types.js';
+import { StringMap, TS_Object } from '@nu-art/ts-common';
+import { Phase_BuildPushImage, Phase_Deploy, Phase_DeployImage, Phase_Launch } from '../../../phases/definitions/consts.js';
+import { Unit_TypescriptLib, Unit_TypescriptLib_Config } from '../Unit_TypescriptLib.js';
+export type FirebaseHostingConfig = {
+    public: string;
+    rewrites: {
+        source: string;
+        destination: string;
+    }[];
+};
+export type FirebaseHosting_EnvConfig = {
+    config: TS_Object;
+    projectId: string;
+    isLocal?: boolean;
+};
+export type Unit_HostingApp_Config = Unit_TypescriptLib_Config & {
+    firebaseConfig?: FirebasePackageConfig;
+    servingPort: number;
+    hostingConfig?: FirebaseHostingConfig;
+    envConfig: FirebaseHosting_EnvConfig;
+    sources?: string[];
+    hostingDeployment?: {
+        artifactRegistry: {
+            region: string;
+            repository: string;
+            projectId: string;
+        };
+        packageName: string;
+    };
+};
+/**
+ * Abstract base for hosting application units (Firebase Hosting with webpack or Vite).
+ * Handles Firebase config resolution, deploy, buildPushImage, deployImage.
+ * Subclasses implement compileImpl() and runApp() for the specific bundler.
+ */
+export declare abstract class Unit_HostingApp<C extends Unit_HostingApp_Config = Unit_HostingApp_Config> extends Unit_TypescriptLib<C> implements UnitPhaseImplementor<[Phase_Launch, Phase_Deploy, Phase_BuildPushImage, Phase_DeployImage]> {
+    hosting: StringMap;
+    injectedMetadata: StringMap;
+    static DefaultConfig_Hosting: {
+        servingPort: number;
+        output: string;
+    };
+    constructor(config: Unit_HostingApp<C>['config']);
+    prepare(): Promise<void>;
+    compile(): Promise<void>;
+    launch(): Promise<void>;
+    deploy(): Promise<void>;
+    protected getEnvConfig(): C["envConfig"];
+    private resolveHostingRC;
+    private resolveHostingJSON;
+    private resolveHostingRuntimeConfig;
+    protected abstract compileImpl(): Promise<void>;
+    protected abstract runApp(): Promise<void>;
+    protected createAppVersionFile(): Promise<void>;
+    buildPushImage(): Promise<void>;
+    deployImage(): Promise<void>;
+}

package/units/implementations/firebase/Unit_HostingApp.js

@@ -0,0 +1,225 @@
+import { ImplementationMissingException } from '@nu-art/ts-common';
+import { CONST_DeployHostingDir, CONST_DeploymentMetadata, CONST_FirebaseJSON, CONST_FirebaseRC, CONST_HostingBuildTarball, CONST_StagingDir, CONST_TrashDir, CONST_VersionApp } from '../../../config/consts.js';
+import { Commando_NVM, CommandoException } from '@nu-art/commando';
+import { resolve } from 'path';
+import { Unit_TypescriptLib } from '../Unit_TypescriptLib.js';
+import { deployLogFilter, ensureArtifactRegistryRepository } from './common.js';
+import { FileSystemUtils } from '@nu-art/ts-common/utils/FileSystemUtils';
+/**
+ * Abstract base for hosting application units (Firebase Hosting with webpack or Vite).
+ * Handles Firebase config resolution, deploy, buildPushImage, deployImage.
+ * Subclasses implement compileImpl() and runApp() for the specific bundler.
+ */
+export class Unit_HostingApp extends Unit_TypescriptLib {
+    hosting = {};
+    injectedMetadata = {};
+    static DefaultConfig_Hosting = {
+        servingPort: 8100,
+        output: 'dist',
+    };
+    constructor(config) {
+        super(config);
+        this.addToClassStack(Unit_HostingApp);
+    }
+    //######################### Phase Implementations #########################
+    async prepare() {
+        await super.prepare();
+        await this.resolveHostingRC();
+        await this.resolveHostingJSON();
+        await this.resolveHostingRuntimeConfig();
+    }
+    async compile() {
+        await this.resolveTSConfig(resolve(this.config.fullPath, './src'), 'main', { compilerOptions: { declaration: false } });
+        await this.clearOutputDir();
+        await this.createAppVersionFile();
+        await this.compileImpl();
+    }
+    async launch() {
+        this.setStatus('Launching');
+        await this.releasePorts([`${this.config.servingPort}`]);
+        await this.runApp();
+    }
+    async deploy() {
+        const commando = this.allocateCommando(Commando_NVM).applyNVM()
+            .cd(this.config.fullPath)
+            .setLogLevelFilter(deployLogFilter)
+            .onLog(/.*Hosting URL.*(https:\/\/.*?)$/, match => {
+            this.hosting[match[1]] = match[2];
+        });
+        const debug = this.runtimeContext.runtimeParams.verbose ? ' --debug' : '';
+        await this.executeAsyncCommando(commando, `${this.npmCommand('firebase')}${debug} deploy --only hosting`);
+    }
+    //######################### ResolveConfig Logic #########################
+    getEnvConfig() {
+        const envConfig = this.config.envConfig;
+        if (!envConfig)
+            throw new ImplementationMissingException(`Missing EnvConfig in unit ${this.config.label}`);
+        return envConfig;
+    }
+    async resolveHostingRC() {
+        const envConfig = this.getEnvConfig();
+        const rcConfig = { projects: { default: envConfig.projectId } };
+        const targetPath = `${this.config.fullPath}/${CONST_FirebaseRC}`;
+        await FileSystemUtils.file.write.json(targetPath, rcConfig);
+    }
+    async resolveHostingJSON() {
+        const envConfig = this.getEnvConfig();
+        const targetPath = `${this.config.fullPath}/${CONST_FirebaseJSON}`;
+        let fileContent;
+        if (envConfig.isLocal)
+            fileContent = {};
+        else
+            fileContent = {
+                hosting: this.config.hostingConfig ?? {
+                    'public': 'dist',
+                    'rewrites': [
+                        { 'source': '**', 'destination': '/index.html' }
+                    ]
+                }
+            };
+        await FileSystemUtils.file.write.json(targetPath, fileContent);
+    }
+    async resolveHostingRuntimeConfig() {
+        const envConfig = this.getEnvConfig().config;
+        const targetPath = resolve(this.config.fullPath, `./src/main/config.ts`);
+        const fileContent = `export const config = ${JSON.stringify(envConfig, null, 2)};`;
+        await FileSystemUtils.file.write(targetPath, fileContent);
+    }
+    //######################### Shared helpers #########################
+    async createAppVersionFile() {
+        const targetPath = `${this.config.fullPath}/src/main/${CONST_VersionApp}`;
+        const appVersion = this.runtimeContext.version;
+        await FileSystemUtils.file.write.json(targetPath, { version: appVersion });
+    }
+    //######################### Build Push Image Phase #########################
+    async buildPushImage() {
+        const hostingDeployment = this.config.hostingDeployment;
+        if (!hostingDeployment) {
+            throw new ImplementationMissingException(`Missing hostingDeployment config in unit ${this.config.key}`);
+        }
+        const buildTag = this.runtimeContext.runtimeParams.buildPushImage;
+        if (!buildTag) {
+            throw new ImplementationMissingException(`Missing buildPushImage runtime param in unit ${this.config.key}`);
+        }
+        const artifactRegistry = hostingDeployment.artifactRegistry;
+        const packageName = hostingDeployment.packageName;
+        if (!packageName) {
+            throw new ImplementationMissingException(`Missing packageName in hostingDeployment config for unit ${this.config.key}`);
+        }
+        this.logInfo(`Building and uploading hosting package to Artifact Registry:`);
+        this.logInfo(`  Package: ${packageName}`);
+        this.logInfo(`  Tag: ${buildTag}`);
+        if (this.runtimeContext.runtimeParams.dryRun) {
+            this.logInfo(`[DRY RUN] Would build and upload hosting package: ${packageName}:${buildTag}`);
+            return;
+        }
+        const commando = this.allocateCommando();
+        await ensureArtifactRegistryRepository(commando, artifactRegistry, 'generic', this);
+        const metadata = {
+            ...this.injectedMetadata,
+            'build.timestamp': new Date().toISOString(),
+            'build.tag': buildTag,
+            'build.project': artifactRegistry.projectId,
+            'build.package-name': packageName,
+            'version': this.runtimeContext.version,
+            'git.commit': process.env.GIT_COMMIT || '',
+            'git.branch': process.env.GIT_BRANCH || '',
+            'build.user': process.env.USER || '',
+        };
+        this.logDebug(`Metadata: `, metadata);
+        const buildOutputDir = resolve(this.config.fullPath, CONST_TrashDir);
+        const stagingDir = resolve(buildOutputDir, CONST_StagingDir);
+        await FileSystemUtils.folder.delete(stagingDir);
+        await FileSystemUtils.folder.create(stagingDir);
+        const tarballPath = resolve(buildOutputDir, CONST_HostingBuildTarball);
+        const outputDirName = resolve(this.config.output).split('/').pop() || 'dist';
+        await FileSystemUtils.folder.copy(this.config.output, resolve(stagingDir, outputDirName));
+        await FileSystemUtils.file.write.json(resolve(stagingDir, CONST_DeploymentMetadata), metadata);
+        commando.cd(stagingDir);
+        await this.executeAsyncCommando(commando, `tar -czf ${tarballPath} ${CONST_DeploymentMetadata} ${outputDirName}`, (stdout, stderr, exitCode) => {
+            if (exitCode !== 0)
+                throw new CommandoException(`Failed to create tarball (exit code ${exitCode})`, stdout, stderr, exitCode);
+        });
+        this.logInfo(`Created tarball: ${tarballPath}`);
+        const region = artifactRegistry.region;
+        const repository = artifactRegistry.repository;
+        const projectId = artifactRegistry.projectId;
+        await this.executeAsyncCommando(commando, `gcloud artifacts generic upload --package=${packageName} --version=${buildTag} --source=${tarballPath} --location=${region} --repository=${repository} --project=${projectId}`, (stdout, stderr, exitCode) => {
+            if (exitCode !== 0)
+                throw new CommandoException(`Failed to upload hosting package to Artifact Registry (exit code ${exitCode})`, stdout, stderr, exitCode);
+        });
+        this.logInfo(`Successfully uploaded hosting package: ${packageName}:${buildTag} and ${packageName}:latest`);
+    }
+    //######################### Deploy Image Phase #########################
+    async deployImage() {
+        const hostingDeployment = this.config.hostingDeployment;
+        if (!hostingDeployment) {
+            throw new ImplementationMissingException(`Missing hostingDeployment config in unit ${this.config.key}`);
+        }
+        const deployTag = this.runtimeContext.runtimeParams.deployImage;
+        if (!deployTag) {
+            throw new ImplementationMissingException(`Missing deployImage runtime param in unit ${this.config.key}. Generic packages require a specific version tag (cannot use 'latest')`);
+        }
+        const artifactRegistry = hostingDeployment.artifactRegistry;
+        const packageName = hostingDeployment.packageName;
+        if (!packageName) {
+            throw new ImplementationMissingException(`Missing packageName in hostingDeployment config for unit ${this.config.key}`);
+        }
+        const region = artifactRegistry.region;
+        const repository = artifactRegistry.repository;
+        const projectId = artifactRegistry.projectId;
+        this.logInfo(`Deploying hosting package: ${packageName}:${deployTag}`);
+        if (this.runtimeContext.runtimeParams.dryRun) {
+            this.logInfo(`[DRY RUN] Would deploy hosting package: ${packageName}:${deployTag}`);
+            return;
+        }
+        const deployTempDir = resolve(this.config.fullPath, `${CONST_TrashDir}/${CONST_DeployHostingDir}`);
+        this.logInfo(`Setting up deployment directory: ${deployTempDir}`);
+        await FileSystemUtils.folder.delete(deployTempDir);
+        await FileSystemUtils.folder.create(deployTempDir);
+        const commando = this.allocateCommando(Commando_NVM)
+            .applyNVM()
+            .cd(deployTempDir)
+            .mark();
+        this.logInfo(`Downloading hosting package from Artifact Registry from: ${projectId}/${repository}/${packageName}/${deployTag}`);
+        await this.executeAsyncCommando(commando, `gcloud artifacts generic download --package=${packageName} --version=${deployTag} --destination=${deployTempDir} --location=${region} --repository=${repository} --project=${projectId}`, (stdout, stderr, exitCode) => {
+            if (exitCode !== 0)
+                throw new CommandoException(`Failed to download hosting package from Artifact Registry (exit code ${exitCode})`, stdout, stderr, exitCode);
+        });
+        this.logInfo(`Locating downloaded tarball...`);
+        const downloadedFiles = await FileSystemUtils.folder.list(deployTempDir);
+        const tarballFile = downloadedFiles.find(file => file.endsWith('.tar.gz'));
+        if (!tarballFile)
+            throw new ImplementationMissingException(`Downloaded tarball not found in ${deployTempDir}. Files found: ${downloadedFiles.join(', ')}`);
+        const tarballPath = resolve(deployTempDir, tarballFile);
+        this.logDebug(`Downloaded tarball: ${tarballPath}`);
+        this.logInfo(`Extracting hosting package...`);
+        await this.executeAsyncCommando(commando, `tar -xzf ${tarballPath} -C ${deployTempDir}`, (stdout, stderr, exitCode) => {
+            if (exitCode !== 0) {
+                throw new CommandoException(`Failed to extract tarball (exit code ${exitCode})`, stdout, stderr, exitCode);
+            }
+        });
+        this.logInfo(`Extracted hosting package to: ${deployTempDir}`);
+        this.logInfo(`Copying firebase configs..`);
+        const firebaseJsonPath = resolve(this.config.fullPath, CONST_FirebaseJSON);
+        const firebaseRcPath = resolve(this.config.fullPath, CONST_FirebaseRC);
+        await FileSystemUtils.file.copy(firebaseJsonPath, resolve(deployTempDir, CONST_FirebaseJSON));
+        await FileSystemUtils.file.copy(firebaseRcPath, resolve(deployTempDir, CONST_FirebaseRC));
+        this.logDebug(`Copied firebase configs!`);
+        const envConfig = this.getEnvConfig();
+        this.logInfo(`Deploying to Firebase Hosting: ${deployTempDir} => ${envConfig.projectId}`);
+        const deployCommando = this.allocateCommando(Commando_NVM).applyNVM()
+            .cd(deployTempDir)
+            .setLogLevelFilter(deployLogFilter)
+            .onLog(/.*Hosting URL.*(https:\/\/.*?)$/, match => {
+            this.hosting[match[1]] = match[2];
+        });
+        const debug = this.runtimeContext.runtimeParams.verbose ? ' --debug' : '';
+        await this.executeAsyncCommando(deployCommando, `npx firebase${debug} deploy --only hosting`, (stdout, stderr, exitCode) => {
+            if (exitCode !== 0) {
+                throw new CommandoException(`Failed to deploy hosting (exit code ${exitCode})`, stdout, stderr, exitCode);
+            }
+        });
+        this.logInfo(`Hosting deployed: `, this.hosting);
+    }
+}

package/units/implementations/firebase/Unit_ViteHostingApp.d.ts

@@ -0,0 +1,10 @@
+import { Unit_HostingApp, Unit_HostingApp_Config } from './Unit_HostingApp.js';
+/**
+ * Firebase Hosting application unit (Vite bundler).
+ * Extends Unit_HostingApp; implements compile via vite build, launch via vite (dev server).
+ */
+export declare class Unit_ViteHostingApp<C extends Unit_HostingApp_Config = Unit_HostingApp_Config> extends Unit_HostingApp<C> {
+    constructor(config: Unit_ViteHostingApp<C>['config']);
+    protected compileImpl(): Promise<void>;
+    protected runApp(): Promise<void>;
+}