@breadstone-infrastructure/nx-tasks 0.0.256 → 0.0.258

package/src/executors/scss-style-transform/executor.task.ts

@@ -0,0 +1,50 @@
+// #region Imports
+
+import { ConsoleLogger, logSeparator, Path, type IFileCacheOptions, File } from '@breadstone-infrastructure/utilities';
+import { compile, type OutputStyle } from 'sass';
+import type { PackageJson } from 'type-fest';
+import { withCaching } from '../../utils/withCaching';
+
+// #endregion
+
+/**
+ * @description Task to transform SCSS files to CSS.
+ * @public
+ */
+export namespace StyleTransformTask {
+
+    export interface IStyleTransformTaskOptions {
+        cwd: string;
+        packageJson: PackageJson;
+        cache?: IFileCacheOptions;
+        outputStyle: OutputStyle;
+        files?: Array<{
+            src: string;
+            dest: string;
+        }>;
+        verbose?: boolean;
+    }
+
+    export async function run(options: IStyleTransformTaskOptions): Promise<void> {
+        const logger = new ConsoleLogger();
+
+        logSeparator(logger, 'Style Transform');
+
+        const fileCache = withCaching(options.cache);
+
+        for (const file of options.files ?? []) {
+            const src = Path.combine(options.cwd, file.src);
+            const dest = Path.combine(options.cwd, file.dest);
+
+            const result = compile(src, {
+                silenceDeprecations: ['mixed-decls'],
+                style: options.outputStyle
+            });
+
+            File.writeAllText(dest, result.css);
+        }
+
+        return Promise.resolve();
+    }
+
+}

package/src/executors/scss-style-transform/executor.ts

@@ -0,0 +1,38 @@
+
+// #region Imports
+
+import { Path } from '@breadstone-infrastructure/utilities';
+import type { ExecutorContext } from '@nx/devkit';
+import { getProjectPackageJson } from '../../utils/getProjectPackageJson';
+import { getProjectRoot } from '../../utils/getProjectRoot';
+import { isVerbose } from '../../utils/isVerbose';
+import type { StyleTransformTask } from './executor.task';
+
+// #endregion
+
+export type StyleTransformExecutorOptions = Omit<StyleTransformTask.IStyleTransformTaskOptions, 'cwd' | 'tsConfigJson' | 'packageJson'>;
+
+/**
+ * @public
+ */
+export default async function runExecutor(options: StyleTransformExecutorOptions, context: ExecutorContext): Promise<{ success: boolean }> {
+    try {
+        const task = (await import('./executor.task')).StyleTransformTask;
+
+        await task.run({
+            cwd: getProjectRoot(context),
+            packageJson: getProjectPackageJson(context),
+            cache: {
+                enabled: options.cache?.enabled ?? context.target?.cache ?? false,
+                dirPath: Path.combine(getProjectRoot(context), '.cache')
+            },
+            files: options.files,
+            outputStyle: options.outputStyle,
+            verbose: isVerbose(context, options),
+        });
+        return { success: true };
+    } catch (error) {
+        console.error(error);
+        return { success: false };
+    }
+}

package/src/executors/scss-style-transform/schema.json

@@ -0,0 +1 @@
+{}

package/src/executors/secrets-config-sync/executor.options.ts

@@ -0,0 +1,10 @@
+// #region Imports
+
+import type { SecretsConfigSyncTask } from './executor.task';
+
+// #endregion
+
+/**
+ * @public
+ */
+export type SecretsConfigSyncExecutorOptions = Omit<SecretsConfigSyncTask.ISecretsConfigSyncTaskOptions, 'cwd'>;

package/src/executors/secrets-config-sync/executor.task.ts

@@ -0,0 +1,163 @@
+// #region Imports
+
+import { bold, ConsoleLogger, File, gray, green, type ILogger, logTree, Path, yellow } from '@breadstone-infrastructure/utilities';
+import * as dotenv from 'dotenv';
+import type { SecretsProviderType } from './providers/secrets-provider.factory';
+import { createSecretsProvider } from './providers/secrets-provider.factory';
+
+// #endregion
+
+export namespace SecretsConfigSyncTask {
+
+    // #region Interfaces
+
+    export interface ISecretsConfigSyncTaskOptions {
+        cwd: string;
+        provider: SecretsProviderType;
+        project: string;
+        config: string;
+        envFile: string;
+        apiKey?: string;
+        vaultUrl?: string;
+    }
+
+    // #endregion
+
+    // #region Types
+
+    type SyncAction = 'added' | 'updated' | 'unchanged';
+
+    interface ISyncResult {
+        key: string;
+        action: SyncAction;
+    }
+
+    // #endregion
+
+    // #region Functions
+
+    /**
+     * Loads the existing environment variables from the .env file.
+     *
+     * @param envFilePath - Path to the .env file.
+     * @param logger - Logger instance.
+     * @returns A record of environment variables.
+     */
+    function loadEnvFile(envFilePath: string, logger: ILogger): Record<string, string> {
+        if (!File.exists(envFilePath)) {
+            return {};
+        }
+
+        logger.log(`Loading .env file from: ${envFilePath}`);
+        const envConfig = dotenv.config({ path: envFilePath });
+        if (envConfig.error) {
+            throw new Error(`Error loading .env file: ${envConfig.error.message}`);
+        }
+        return envConfig.parsed ?? {};
+    }
+
+    /**
+     * Computes the diff between current env and fetched secrets.
+     *
+     * @param currentEnv - The current environment variables.
+     * @param secrets - The fetched secrets from the provider.
+     * @returns A list of sync results.
+     */
+    function computeDiff(currentEnv: Record<string, string>, secrets: Record<string, string>): Array<ISyncResult> {
+        const results: Array<ISyncResult> = [];
+
+        for (const key of Object.keys(secrets)) {
+            if (!(key in currentEnv)) {
+                results.push({ key, action: 'added' });
+            } else if (currentEnv[key] !== secrets[key]) {
+                results.push({ key, action: 'updated' });
+            } else {
+                results.push({ key, action: 'unchanged' });
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * Returns a colored tag string for the given sync action.
+     */
+    function formatActionTag(action: SyncAction): string {
+        switch (action) {
+            case 'added':
+                return green(bold('[added]'));
+            case 'updated':
+                return yellow(bold('[updated]'));
+            case 'unchanged':
+                return gray(bold('[unchanged]'));
+        }
+    }
+
+    /**
+     * Logs the sync results as a single alphabetically sorted tree with colored action tags.
+     */
+    function logResults(logger: ILogger, results: Array<ISyncResult>): void {
+        const sorted = [...results].sort((a, b) => a.key.localeCompare(b.key));
+
+        logTree(logger, `Keys (${sorted.length})`, sorted.map(r => ({
+            label: `${r.key} ${formatActionTag(r.action)}`
+        })));
+    }
+
+    /**
+     * Writes updated secrets to the .env file.
+     *
+     * @param envFilePath - Path to the .env file.
+     * @param updatedEnv - The updated environment variables.
+     */
+    function updateEnvFile(envFilePath: string, updatedEnv: Record<string, string>): void {
+        const envContent = Object.entries(updatedEnv)
+            .map(([key, value]) => `${key}="${value}"`)
+            .join('\n');
+        File.writeAllText(envFilePath, envContent);
+    }
+
+    // #endregion
+
+    // #region Main Task
+
+    export async function run(options: ISecretsConfigSyncTaskOptions): Promise<void> {
+        const logger = new ConsoleLogger();
+        const providerType = options.provider ?? 'doppler';
+
+        try {
+            const provider = createSecretsProvider(providerType);
+
+            // Step 1: Authenticate with the provider
+            logger.log(`Authenticating with ${providerType}...`);
+            const token = await provider.authenticate(options.apiKey, true);
+
+            // Step 2: Fetch secrets from the provider
+            logger.log(`Fetching secrets from ${providerType}...`);
+            const secrets = await provider.fetchSecrets(token, options.project, options.config, logger, options.vaultUrl);
+
+            // Step 3: Load the current environment file
+            logger.log('Loading current .env file...');
+            const envPath = Path.combine(options.cwd, options.envFile);
+            const currentEnv = loadEnvFile(envPath, logger);
+
+            // Step 4: Compute and log the diff
+            const diff = computeDiff(currentEnv, secrets);
+            logResults(logger, diff);
+
+            // Step 5: Merge and update the .env file with new secrets
+            const mergedEnv = {
+                ...currentEnv,
+                ...secrets
+            };
+            updateEnvFile(envPath, mergedEnv);
+
+            logger.log('Successfully wrote updated secrets to .env file.');
+        } catch (error) {
+            logger.error(`Error: ${(error as Error).message}`);
+            throw error;
+        }
+    }
+
+    // #endregion
+}

package/src/executors/secrets-config-sync/executor.ts

@@ -0,0 +1,32 @@
+// #region Imports
+
+import type { ExecutorContext } from '@nx/devkit';
+import { getProjectRoot } from '../../utils/getProjectRoot';
+import type { SecretsConfigSyncExecutorOptions } from './executor.options';
+
+// #endregion
+
+/**
+ * Nx executor that fetches secrets from a configurable provider and writes them to local .env files.
+ *
+ * @public
+ */
+export default async function runExecutor(options: SecretsConfigSyncExecutorOptions, context: ExecutorContext): Promise<{ success: boolean }> {
+    try {
+        const task = (await import('./executor.task')).SecretsConfigSyncTask;
+
+        await task.run({
+            cwd: getProjectRoot(context),
+            provider: options.provider,
+            project: options.project,
+            config: options.config,
+            envFile: options.envFile,
+            apiKey: options.apiKey,
+            vaultUrl: options.vaultUrl
+        });
+        return { success: true };
+    } catch (error) {
+        console.error(error);
+        return { success: false };
+    }
+}

package/src/executors/secrets-config-sync/providers/azure-keyvault.provider.ts

@@ -0,0 +1,180 @@
+// #region Imports
+
+import type { ILogger } from '@breadstone-infrastructure/utilities';
+import { prompt } from 'enquirer';
+import type { ISecretsProvider } from './secrets-provider.interface';
+
+// #endregion
+
+// #region Interfaces
+
+interface IAzureKeyVaultSecretItem {
+    id: string;
+    attributes: {
+        enabled: boolean;
+        created: number;
+        updated: number;
+    };
+}
+
+interface IAzureKeyVaultSecretListResponse {
+    value: Array<IAzureKeyVaultSecretItem>;
+    nextLink?: string;
+}
+
+interface IAzureKeyVaultSecretValueResponse {
+    value: string;
+    id: string;
+    attributes: {
+        enabled: boolean;
+    };
+}
+
+// #endregion
+
+/**
+ * Secrets provider implementation for Azure Key Vault.
+ *
+ * Uses the Key Vault REST API with a Bearer token (e.g. from `az account get-access-token`
+ * or a service principal client credential flow). The token must be provided via `apiKey`
+ * or entered interactively.
+ *
+ * @public
+ */
+export class AzureKeyVaultSecretsProvider implements ISecretsProvider {
+
+    // #region Methods
+
+    /**
+     * @inheritdoc
+     */
+    public async authenticate(apiKey?: string, interactive?: boolean): Promise<string> {
+        if (apiKey) {
+            return apiKey;
+        }
+
+        if (interactive) {
+            const credentials = await prompt<{ token: string }>([
+                {
+                    type: 'input',
+                    name: 'token',
+                    message: 'Enter your Azure Key Vault access token:\nYou can obtain one via `az account get-access-token --resource https://vault.azure.net --query accessToken -o tsv`.'
+                }
+            ]);
+
+            if (!credentials.token) {
+                throw new Error('No Azure Key Vault access token provided. Aborting.');
+            }
+
+            return credentials.token;
+        }
+
+        throw new Error('No Azure Key Vault access token provided and interactive mode is disabled.');
+    }
+
+    /**
+     * Fetches all secrets from an Azure Key Vault.
+     *
+     * The `project` and `config` parameters are ignored. The vault is identified
+     * solely by `vaultUrl`.
+     *
+     * @inheritdoc
+     */
+    public async fetchSecrets(token: string, _project: string, _config: string, logger: ILogger, vaultUrl?: string): Promise<Record<string, string>> {
+        if (!vaultUrl) {
+            throw new Error('vaultUrl is required for the azure-keyvault provider.');
+        }
+
+        const normalizedVaultUrl = vaultUrl.endsWith('/') ? vaultUrl.slice(0, -1) : vaultUrl;
+        const secrets: Record<string, string> = {};
+
+        // Step 1: List all secrets (paged)
+        const secretItems = await this.listSecrets(token, normalizedVaultUrl);
+        logger.log(`Found ${secretItems.length} secrets in Key Vault.`);
+
+        // Step 2: Fetch each secret value
+        for (const item of secretItems) {
+            const secretName = this.extractSecretName(item.id);
+            const value = await this.getSecretValue(token, normalizedVaultUrl, secretName);
+            secrets[secretName] = value;
+        }
+
+        logger.log(`Fetched ${Object.keys(secrets).length} secrets from Azure Key Vault [${normalizedVaultUrl}].`);
+
+        return secrets;
+    }
+
+    // #endregion
+
+    // #region Properties
+
+    // #endregion
+
+    // #region Fields
+
+    // #endregion
+
+    // #region Ctor
+
+    // #endregion
+
+    // #region Private Methods
+
+    /**
+     * Lists all secrets in the vault (handles pagination).
+     */
+    private async listSecrets(token: string, vaultUrl: string): Promise<Array<IAzureKeyVaultSecretItem>> {
+        const allItems: Array<IAzureKeyVaultSecretItem> = [];
+        let nextLink: string | undefined = `${vaultUrl}/secrets?api-version=7.4`;
+
+        while (nextLink) {
+            const response = await fetch(nextLink, {
+                headers: { Authorization: `Bearer ${token}` }
+            });
+
+            if (!response.ok) {
+                throw new Error(`Failed to list Azure Key Vault secrets (HTTP ${response.status}): ${response.statusText}`);
+            }
+
+            const data = await response.json() as IAzureKeyVaultSecretListResponse;
+            const enabledItems = data.value.filter(item => item.attributes.enabled);
+            allItems.push(...enabledItems);
+            nextLink = data.nextLink;
+        }
+
+        return allItems;
+    }
+
+    /**
+     * Fetches the current value of a single secret.
+     */
+    private async getSecretValue(token: string, vaultUrl: string, secretName: string): Promise<string> {
+        const url = `${vaultUrl}/secrets/${encodeURIComponent(secretName)}?api-version=7.4`;
+
+        const response = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}` }
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to fetch Azure Key Vault secret "${secretName}" (HTTP ${response.status}): ${response.statusText}`);
+        }
+
+        const data = await response.json() as IAzureKeyVaultSecretValueResponse;
+
+        return data.value;
+    }
+
+    /**
+     * Extracts the secret name from a Key Vault secret ID URL.
+     *
+     * @example
+     * `https://my-vault.vault.azure.net/secrets/MY_SECRET` → `MY_SECRET`
+     */
+    private extractSecretName(secretId: string): string {
+        const parts = secretId.split('/');
+
+        return parts[parts.length - 1];
+    }
+
+    // #endregion
+}

package/src/executors/secrets-config-sync/providers/doppler.provider.ts

@@ -0,0 +1,84 @@
+// #region Imports
+
+import type { ILogger } from '@breadstone-infrastructure/utilities';
+import { prompt } from 'enquirer';
+import type { ISecretsProvider } from './secrets-provider.interface';
+
+// #endregion
+
+// #region Interfaces
+
+interface IDopplerSecretsResponse {
+    success: boolean;
+    secrets: Record<string, {
+        raw: string;
+        computed: string;
+        note: string;
+        rawVisibility: 'unmasked' | 'masked';
+        computedVisibility: 'unmasked' | 'masked';
+        rawValueType: object;
+        computedValueType: object;
+    }>;
+}
+
+// #endregion
+
+/**
+ * Secrets provider implementation for Doppler.
+ *
+ * @public
+ */
+export class DopplerSecretsProvider implements ISecretsProvider {
+
+    // #region Methods
+
+    /**
+     * @inheritdoc
+     */
+    public async authenticate(apiKey?: string, interactive?: boolean): Promise<string> {
+        if (apiKey) {
+            return apiKey;
+        }
+
+        if (interactive) {
+            const credentials = await prompt<{ apiKey: string }>([
+                {
+                    type: 'input',
+                    name: 'apiKey',
+                    message: 'Enter your Doppler API key:\nYou can find it in your Doppler account settings.'
+                }
+            ]);
+
+            if (!credentials.apiKey) {
+                throw new Error('No Doppler API key provided. Aborting.');
+            }
+
+            return credentials.apiKey;
+        }
+
+        throw new Error('No Doppler API key provided and interactive mode is disabled.');
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public async fetchSecrets(token: string, project: string, config: string, logger: ILogger): Promise<Record<string, string>> {
+        const apiUrl = `https://api.doppler.com/v3/configs/config/secrets?project=${encodeURIComponent(project)}&config=${encodeURIComponent(config)}&include_dynamic_secrets=false&include_managed_secrets=true`;
+
+        const response = await fetch(apiUrl, {
+            headers: { Authorization: `Bearer ${token}` }
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to fetch Doppler secrets (HTTP ${response.status}): ${response.statusText}`);
+        }
+
+        const data = await response.json() as IDopplerSecretsResponse;
+
+        logger.log(`Fetched ${Object.keys(data.secrets).length} secrets from Doppler [${project}/${config}].`);
+
+        return Object.fromEntries(Object.entries(data.secrets).map(([key, value]) => [key, value.raw]));
+    }
+
+    // #endregion
+}

package/src/executors/secrets-config-sync/providers/secrets-provider.factory.ts

@@ -0,0 +1,33 @@
+// #region Imports
+
+import { AzureKeyVaultSecretsProvider } from './azure-keyvault.provider';
+import { DopplerSecretsProvider } from './doppler.provider';
+import type { ISecretsProvider } from './secrets-provider.interface';
+
+// #endregion
+
+/**
+ * The supported secrets provider types.
+ *
+ * @public
+ */
+export type SecretsProviderType = 'doppler' | 'azure-keyvault';
+
+/**
+ * Creates an {@link ISecretsProvider} instance for the given provider type.
+ *
+ * @param type - The provider type to instantiate.
+ * @returns The corresponding secrets provider.
+ *
+ * @public
+ */
+export function createSecretsProvider(type: SecretsProviderType): ISecretsProvider {
+    switch (type) {
+        case 'doppler':
+            return new DopplerSecretsProvider();
+        case 'azure-keyvault':
+            return new AzureKeyVaultSecretsProvider();
+        default:
+            throw new Error(`Unknown secrets provider type: "${type}". Supported: doppler, azure-keyvault.`);
+    }
+}

package/src/executors/secrets-config-sync/providers/secrets-provider.interface.ts

@@ -0,0 +1,34 @@
+// #region Imports
+
+import type { ILogger } from '@breadstone-infrastructure/utilities';
+
+// #endregion
+
+/**
+ * Abstraction for a secrets provider that can authenticate and fetch secrets.
+ *
+ * @public
+ */
+export interface ISecretsProvider {
+
+    /**
+     * Authenticates with the provider and returns an access token.
+     *
+     * @param apiKey - An optional API key or access token. If provided, it is used directly.
+     * @param interactive - Whether to prompt the user for credentials if none are provided.
+     * @returns The resolved access token.
+     */
+    authenticate(apiKey?: string, interactive?: boolean): Promise<string>;
+
+    /**
+     * Fetches all secrets from the provider.
+     *
+     * @param token - The access token obtained from {@link authenticate}.
+     * @param project - The project identifier (Doppler project name, or ignored for Azure Key Vault).
+     * @param config - The config identifier (Doppler config name, or ignored for Azure Key Vault).
+     * @param logger - Logger instance for status output.
+     * @param vaultUrl - The Azure Key Vault URL (only used by the azure-keyvault provider).
+     * @returns A flat record of secret key-value pairs.
+     */
+    fetchSecrets(token: string, project: string, config: string, logger: ILogger, vaultUrl?: string): Promise<Record<string, string>>;
+}

package/src/executors/secrets-config-sync/schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "cli": "nx",
+  "title": "Secrets Config Sync",
+  "description": "Fetches secrets from a configurable provider (Doppler, Azure Key Vault) and writes them to local .env files.",
+  "type": "object",
+  "properties": {
+    "provider": {
+      "type": "string",
+      "description": "The secrets provider to use.",
+      "enum": [
+        "doppler",
+        "azure-keyvault"
+      ],
+      "default": "doppler"
+    },
+    "project": {
+      "type": "string",
+      "description": "The project identifier (e.g. Doppler project name)."
+    },
+    "config": {
+      "type": "string",
+      "description": "The configuration identifier (e.g. Doppler config name: dev, prev, prod)."
+    },
+    "envFile": {
+      "type": "string",
+      "description": "The relative path to the .env file to write secrets to."
+    },
+    "apiKey": {
+      "type": "string",
+      "description": "The API key or access token for the secrets provider. If omitted, the user is prompted interactively."
+    },
+    "vaultUrl": {
+      "type": "string",
+      "description": "The Azure Key Vault URL (e.g. https://my-vault.vault.azure.net). Required when provider is azure-keyvault."
+    }
+  },
+  "required": [
+    "project",
+    "config",
+    "envFile"
+  ],
+  "additionalProperties": false
+}

package/src/executors/secrets-vercel-sync/executor.options.ts

@@ -0,0 +1,12 @@
+// #region Imports
+
+import type { SecretsVercelSyncTask } from './executor.task';
+
+// #endregion
+
+/**
+ * Executor options for the secrets-vercel-sync executor.
+ *
+ * @public
+ */
+export type SecretsVercelSyncExecutorOptions = Omit<SecretsVercelSyncTask.ISecretsVercelSyncTaskOptions, 'cwd'>;