@invarn/cibuild 1.3.16 → 1.3.18

package/dist/src/yaml/env-resolver.js

@@ -0,0 +1,405 @@
+/**
+ * Environment variable resolution and interpolation
+ * Merges global and workflow-level environment variables
+ * Supports variable interpolation in multiple formats
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { SecretsManager } from './secrets-manager.js';
+/**
+ * Hints for common variables that require user configuration
+ */
+const CIBUILD_VARIABLE_HINTS = {
+    CIBUILD_PUBLIC_INSTALL_PAGE_URL: 'Public URL where users can download/install the built app.\n\n' +
+        'Purpose:\n' +
+        '  • Used in Slack notifications and other build artifacts\n' +
+        '  • Provides a download link for QA, stakeholders, or beta testers\n' +
+        '  • Commonly points to artifact hosting (Firebase App Distribution, TestFlight, etc.)\n\n' +
+        'Expected format:\n' +
+        '  ┌────────────────────────────────────────────────────────┐\n' +
+        '  │ https://example.com/downloads/myapp-v1.0.0.apk         │\n' +
+        '  │ https://appdistribution.firebase.dev/i/abc123          │\n' +
+        '  │ https://testflight.apple.com/join/xyz456               │\n' +
+        '  └────────────────────────────────────────────────────────┘\n\n' +
+        'How to set:\n' +
+        '  • Add to your YAML under app.envs or workflows.[name].envs:\n' +
+        '    envs:\n' +
+        '      - CIBUILD_PUBLIC_INSTALL_PAGE_URL: "https://your-url-here"\n' +
+        '  • Or set dynamically in a previous step that uploads the build\n' +
+        '  • Or leave it as a placeholder if not using artifact distribution',
+    CIBUILD_PUBLIC_INSTALL_PAGE_QR_CODE_IMAGE_URL: 'URL to a QR code image for easy mobile download/install.\n\n' +
+        'Purpose:\n' +
+        '  • Used in Slack notifications for quick mobile access\n' +
+        '  • QR code typically points to CIBUILD_PUBLIC_INSTALL_PAGE_URL\n\n' +
+        'Expected format:\n' +
+        '  ┌────────────────────────────────────────────────────────┐\n' +
+        '  │ https://example.com/qr-codes/myapp-v1.0.0.png          │\n' +
+        '  │ https://api.qrserver.com/v1/create-qr-code/?data=...   │\n' +
+        '  └────────────────────────────────────────────────────────┘\n\n' +
+        'How to set:\n' +
+        '  • Add to your YAML under app.envs or workflows.[name].envs\n' +
+        '  • Or generate dynamically in a previous step\n' +
+        '  • Or use a QR code generation service with the install URL',
+    CIBUILD_PULL_REQUEST: 'Pull request number or ID for PR builds.\n\n' +
+        'Expected format:\n' +
+        '  ┌────────────────────────────────────────────────────────┐\n' +
+        '  │ 123                                                     │\n' +
+        '  │ pr-456                                                  │\n' +
+        '  └────────────────────────────────────────────────────────┘\n\n' +
+        'How to set:\n' +
+        '  • Typically provided by CI system for PR builds\n' +
+        '  • Or set manually: export CIBUILD_PULL_REQUEST="123"',
+    CIBUILD_GIT_TAG: 'Git tag name for tag-triggered builds.\n\n' +
+        'Expected format:\n' +
+        '  ┌────────────────────────────────────────────────────────┐\n' +
+        '  │ v1.0.0                                                  │\n' +
+        '  │ release-2024-01-15                                      │\n' +
+        '  └────────────────────────────────────────────────────────┘\n\n' +
+        'How to set:\n' +
+        '  • Typically provided by CI system for tag builds\n' +
+        '  • Or set manually: export CIBUILD_GIT_TAG="v1.0.0"',
+};
+export class MissingEnvironmentVariableError extends Error {
+    variableName;
+    stepName;
+    hint;
+    constructor(variableName, stepName, hint) {
+        const stepInfo = stepName ? ` required by step: '${stepName}'` : '';
+        const hintInfo = hint ? `\n\n${hint}` : '';
+        super(`Missing environment variable: '${variableName}'${stepInfo}\n` +
+            `Check your YAML file's 'app.envs' or 'workflows.[name].envs' sections.${hintInfo}`);
+        this.variableName = variableName;
+        this.stepName = stepName;
+        this.hint = hint;
+        this.name = 'MissingEnvironmentVariableError';
+    }
+}
+/**
+ * EnvResolver handles environment variable merging and interpolation
+ */
+export class EnvResolver {
+    envVars;
+    referencedVars = new Set();
+    secretsManager;
+    constructor(pipeline, workflow, workflowName, platform, stack, yamlFilePath) {
+        this.envVars = new Map();
+        this.secretsManager = new SecretsManager();
+        // Step 1: Add built-in environment variables (auto-detected defaults)
+        this.addBuiltInVars(workflowName, platform, stack, yamlFilePath);
+        // Step 2: Load secrets — overrides auto-detected built-ins with user-stored values
+        // Workflow-specific secrets take precedence over global secrets
+        const allSecrets = this.secretsManager.getAll(workflowName);
+        for (const [key, value] of Object.entries(allSecrets)) {
+            this.envVars.set(key, value);
+        }
+        // Step 3: Add global environment variables (app.envs) — overrides secrets
+        if (pipeline.app?.envs) {
+            this.mergeEnvVars(pipeline.app.envs);
+        }
+        // Step 4: Add workflow-level environment variables — highest priority, overrides everything
+        if (workflow.envs) {
+            this.mergeEnvVars(workflow.envs);
+        }
+    }
+    /**
+     * Gets the value of an environment variable
+     * @param name Variable name
+     * @returns Variable value or undefined if not found
+     */
+    get(name) {
+        this.referencedVars.add(name);
+        return this.envVars.get(name);
+    }
+    /**
+     * Checks if an environment variable is defined
+     * @param name Variable name
+     * @returns True if variable exists
+     */
+    has(name) {
+        return this.envVars.has(name);
+    }
+    /**
+     * Registers a variable as a step output passthrough.
+     * When this variable appears in a later step's inputs it will be kept as
+     * the literal shell reference "$NAME" so the shell resolves it at runtime.
+     */
+    registerStepOutput(name) {
+        if (!this.envVars.has(name)) {
+            this.envVars.set(name, `$${name}`);
+        }
+    }
+    /**
+     * Gets all environment variables as a plain object
+     * @returns Object with all environment variables
+     */
+    getAll() {
+        const result = {};
+        for (const [key, value] of this.envVars.entries()) {
+            result[key] = value;
+        }
+        return result;
+    }
+    /**
+     * Interpolates environment variables in a string
+     * Supports four formats:
+     * - $VAR
+     * - ${VAR}
+     * - {{getenv "VAR"}}
+     * - {{checksum "path/to/file"}}
+     *
+     * @param str String to interpolate
+     * @param stepName Optional step name for error messages
+     * @returns Interpolated string
+     * @throws MissingEnvironmentVariableError if referenced variable not found
+     */
+    interpolate(str, stepName) {
+        let result = str;
+        // Format 1: {{checksum "file"}}
+        result = result.replace(/\{\{checksum "([^"]+)"\}\}/g, (match, filePath) => {
+            return this.computeChecksum(filePath);
+        });
+        // Format 2: {{getenv "VAR"}}
+        result = result.replace(/\{\{getenv "([^"]+)"\}\}/g, (match, varName) => {
+            return this.resolveVar(varName, stepName);
+        });
+        // Format 3: ${VAR}
+        result = result.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (match, varName) => {
+            return this.resolveVar(varName, stepName);
+        });
+        // Format 4: $VAR (must not be followed by alphanumeric or underscore)
+        result = result.replace(/\$([A-Z_][A-Z0-9_]*)(?![A-Z0-9_])/g, (match, varName) => {
+            return this.resolveVar(varName, stepName);
+        });
+        return result;
+    }
+    /**
+     * Interpolates environment variables in an object recursively
+     * @param obj Object to interpolate
+     * @param stepName Optional step name for error messages
+     * @returns Interpolated object
+     */
+    interpolateObject(obj, stepName) {
+        if (typeof obj === 'string') {
+            return this.interpolate(obj, stepName);
+        }
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this.interpolateObject(item, stepName));
+        }
+        if (obj && typeof obj === 'object') {
+            const result = {};
+            for (const [key, value] of Object.entries(obj)) {
+                result[key] = this.interpolateObject(value, stepName);
+            }
+            return result;
+        }
+        return obj;
+    }
+    /**
+     * Validates that all referenced variables are defined
+     * @throws MissingEnvironmentVariableError if any referenced variable is missing
+     */
+    validateReferencedVars() {
+        for (const varName of this.referencedVars) {
+            if (!this.envVars.has(varName)) {
+                throw new MissingEnvironmentVariableError(varName);
+            }
+        }
+    }
+    /**
+     * Resolves a single variable reference
+     * @param varName Variable name
+     * @param stepName Optional step name for error messages
+     * @returns Variable value
+     * @throws MissingEnvironmentVariableError if variable not found
+     */
+    resolveVar(varName, stepName) {
+        this.referencedVars.add(varName);
+        const value = this.envVars.get(varName);
+        if (value === undefined) {
+            // Check if we have a hint for this variable
+            const hint = CIBUILD_VARIABLE_HINTS[varName];
+            throw new MissingEnvironmentVariableError(varName, stepName, hint);
+        }
+        return value;
+    }
+    /**
+     * Computes MD5 checksum of a file
+     * @param filePath Path to file (relative to current working directory)
+     * @returns MD5 hash of file contents
+     * @throws Error if file does not exist or cannot be read
+     */
+    computeChecksum(filePath) {
+        try {
+            // Resolve relative path to absolute path
+            const absolutePath = path.resolve(process.cwd(), filePath);
+            // Check if file exists
+            if (!fs.existsSync(absolutePath)) {
+                throw new Error(`File not found: ${filePath}`);
+            }
+            // Read file and compute MD5 hash
+            const fileBuffer = fs.readFileSync(absolutePath);
+            const hash = crypto.createHash('md5');
+            hash.update(fileBuffer);
+            return hash.digest('hex');
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to compute checksum for "${filePath}": ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Adds built-in environment variables
+     * @param workflowName Name of the current workflow
+     * @param platform Detected platform
+     * @param stack Optional stack identifier
+     */
+    addBuiltInVars(workflowName, platform, stack, yamlFilePath) {
+        // CI Build native variables (FR-9.2)
+        const buildNumber = process.env.BUILD_NUMBER || '1';
+        const buildUrl = process.env.BUILD_URL || 'https://cibuild.io/builds/1';
+        const appTitle = process.env.APP_TITLE || 'CI Build Build';
+        // Extract YAML filename (without extension) for use in naming resources like SSH keys
+        if (yamlFilePath) {
+            const yamlFilename = path.basename(yamlFilePath, path.extname(yamlFilePath));
+            this.envVars.set('CIBUILD_YAML_FILENAME', yamlFilename);
+        }
+        this.envVars.set('CIBUILD_BUILD_NUMBER', buildNumber);
+        this.envVars.set('CIBUILD_BUILD_URL', buildUrl);
+        this.envVars.set('CIBUILD_APP_TITLE', appTitle);
+        // Writable scratch path on local APFS disk. The sandbox runner sets this
+        // in the guest shell; outside a sandbox we fall back to TMPDIR so
+        // pipelines that reference $CIBUILD_SCRATCH still interpolate to
+        // something writable.
+        this.envVars.set('CIBUILD_SCRATCH', process.env.CIBUILD_SCRATCH || process.env.TMPDIR || '/tmp');
+        // Auto-detect git metadata from local repo
+        const git = (cmd, fallback) => {
+            try {
+                return execSync(`git ${cmd}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim() || fallback;
+            }
+            catch {
+                return fallback;
+            }
+        };
+        // Common built-in variables
+        const gitBranch = process.env.GIT_BRANCH || git('rev-parse --abbrev-ref HEAD', 'main');
+        const gitCommit = git('rev-parse HEAD', process.env.GIT_COMMIT || 'HEAD');
+        const gitRepoUrl = process.env.CIBUILD_GIT_REPOSITORY_URL || process.env.GIT_REPOSITORY_URL || git('remote get-url origin', '');
+        // Source directory
+        this.envVars.set('CIBUILD_SOURCE_DIR', process.cwd());
+        // Git variables
+        this.envVars.set('CIBUILD_GIT_BRANCH', gitBranch);
+        this.envVars.set('CIBUILD_GIT_COMMIT', gitCommit);
+        this.envVars.set('CIBUILD_GIT_REPOSITORY_URL', gitRepoUrl);
+        this.envVars.set('CIBUILD_TRIGGERED_WORKFLOW_ID', workflowName);
+        // Git metadata (auto-detected from local repo)
+        this.envVars.set('GIT_CLONE_COMMIT_HASH', gitCommit);
+        this.envVars.set('GIT_CLONE_COMMIT_AUTHOR_NAME', git('log -1 --format=%an', process.env.GIT_AUTHOR_NAME || ''));
+        this.envVars.set('GIT_CLONE_COMMIT_AUTHOR_EMAIL', git('log -1 --format=%ae', process.env.GIT_AUTHOR_EMAIL || ''));
+        this.envVars.set('GIT_CLONE_COMMIT_COMMITER_NAME', git('log -1 --format=%cn', process.env.GIT_COMMITTER_NAME || ''));
+        this.envVars.set('GIT_CLONE_COMMIT_COMMITER_EMAIL', git('log -1 --format=%ce', process.env.GIT_COMMITTER_EMAIL || ''));
+        this.envVars.set('GIT_CLONE_COMMIT_MESSAGE_SUBJECT', git('log -1 --format=%s', process.env.GIT_COMMIT_MESSAGE || ''));
+        this.envVars.set('GIT_CLONE_COMMIT_MESSAGE_BODY', git('log -1 --format=%b', ''));
+        // Platform-specific built-in variables
+        if (stack) {
+            this.envVars.set('CIBUILD_STACK', stack);
+        }
+        if (platform === 'macos') {
+            // Extract Xcode version from stack if available
+            if (stack) {
+                const xcodeMatch = stack.match(/xcode-(\d+\.\d+)/);
+                if (xcodeMatch) {
+                    this.envVars.set('CIBUILD_XCODE_VERSION', xcodeMatch[1]);
+                }
+            }
+            // Default Xcode scheme (can be overridden by user)
+            if (!this.envVars.has('CIBUILD_SCHEME')) {
+                this.envVars.set('CIBUILD_SCHEME', process.env.XCODE_SCHEME || 'Release');
+            }
+        }
+        if (platform === 'linux') {
+            // JAVA_HOME (can be overridden by user)
+            this.envVars.set('JAVA_HOME', process.env.JAVA_HOME || '/usr/lib/jvm/java-17-openjdk');
+            this.envVars.set('CIBUILD_GRADLE_VERSION', process.env.GRADLE_VERSION || '8.0');
+        }
+    }
+    /**
+     * Merges environment variables from YAML array format
+     * @param envArray Array of environment variable objects
+     */
+    mergeEnvVars(envArray) {
+        for (const envObj of envArray) {
+            for (const [key, value] of Object.entries(envObj)) {
+                // First resolve any secret references
+                const secretResolved = this.resolveSecretReference(value);
+                // Then interpolate in case it references other env vars
+                const interpolated = this.interpolateEnvValue(secretResolved);
+                // Don't overwrite a non-empty value (e.g. a loaded secret) with an empty
+                // YAML placeholder string — secrets are loaded before YAML envs and should
+                // survive empty placeholder declarations like `KEYSTORE_BASE64: ""`
+                if (interpolated === '' && this.envVars.get(key)) {
+                    continue;
+                }
+                this.envVars.set(key, interpolated);
+            }
+        }
+    }
+    /**
+     * Resolves $SECRET{secret_id} references to actual secret values
+     * @param value Value that may contain a secret reference
+     * @returns Resolved value with secret content, or empty string if secret not found
+     */
+    resolveSecretReference(value) {
+        // Convert non-strings to strings first
+        if (typeof value !== 'string') {
+            return String(value);
+        }
+        // Check for $SECRET{secret_id} pattern
+        const secretMatch = value.match(/^\$SECRET\{([^}]+)\}$/);
+        if (!secretMatch) {
+            return value;
+        }
+        const secretId = secretMatch[1];
+        const secretValue = this.secretsManager.getSecret(secretId);
+        if (!secretValue) {
+            // Return empty string silently — the validation step will report this
+            return '';
+        }
+        return secretValue;
+    }
+    /**
+     * Interpolates environment variable value during initial setup
+     * This allows env vars to reference other env vars
+     * @param value Raw value
+     * @returns Interpolated value or original if interpolation fails
+     */
+    interpolateEnvValue(value) {
+        try {
+            return this.interpolate(value);
+        }
+        catch (err) {
+            // If interpolation fails during setup, return the raw value
+            // It will be interpolated later when all vars are available
+            return value;
+        }
+    }
+}
+/**
+ * Helper function to create an EnvResolver for a workflow
+ * @param pipeline Parsed YAML pipeline
+ * @param workflowName Name of the workflow
+ * @param platform Detected platform
+ * @param stack Optional stack identifier
+ * @returns EnvResolver instance
+ */
+export function createEnvResolver(pipeline, workflowName, platform, stack) {
+    const workflow = pipeline.workflows[workflowName];
+    if (!workflow) {
+        throw new Error(`Workflow '${workflowName}' not found`);
+    }
+    return new EnvResolver(pipeline, workflow, workflowName, platform, stack);
+}
+//# sourceMappingURL=env-resolver.js.map

package/dist/src/yaml/env-resolver.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for environment variable resolution
+ */
+export {};
+//# sourceMappingURL=env-resolver.test.d.ts.map

package/dist/src/yaml/env-resolver.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-resolver.test.d.ts","sourceRoot":"","sources":["../../../src/yaml/env-resolver.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}