@enspirit/emb 0.15.0 → 0.17.0

package/dist/src/context.d.ts

@@ -1,3 +1,12 @@
 import { EmbContext } from './types.js';
 export declare const getContext: () => EmbContext;
 export declare const setContext: (ctx: EmbContext) => EmbContext;
+/**
+ * Check if the context's EMB_ROOT matches the current environment.
+ * Used to detect when tests switch between different example monorepos.
+ */
+export declare const isContextStale: () => boolean;
+/**
+ * Reset the context. Used in testing to ensure a fresh context for each test suite.
+ */
+export declare const resetContext: () => void;

package/dist/src/context.js

@@ -1,8 +1,27 @@
 let context;
+let contextEmbRoot;
 export const getContext = () => {
     return context;
 };
 export const setContext = (ctx) => {
     context = ctx;
+    contextEmbRoot = process.env.EMB_ROOT;
     return ctx;
 };
+/**
+ * Check if the context's EMB_ROOT matches the current environment.
+ * Used to detect when tests switch between different example monorepos.
+ */
+export const isContextStale = () => {
+    if (!context) {
+        return false;
+    }
+    return contextEmbRoot !== process.env.EMB_ROOT;
+};
+/**
+ * Reset the context. Used in testing to ensure a fresh context for each test suite.
+ */
+export const resetContext = () => {
+    context = undefined;
+    contextEmbRoot = undefined;
+};

package/dist/src/docker/compose/operations/ComposeLogsOperation.d.ts

@@ -0,0 +1,21 @@
+import { Writable } from 'node:stream';
+import * as z from 'zod';
+import { AbstractOperation } from '../../../operations/index.js';
+/**
+ * https://docs.docker.com/reference/cli/docker/compose/logs/
+ */
+export declare const ComposeLogsOperationInputSchema: z.ZodOptional<z.ZodObject<{
+    services: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    follow: z.ZodOptional<z.ZodBoolean>;
+    timestamps: z.ZodOptional<z.ZodBoolean>;
+    tail: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare class ComposeLogsOperation extends AbstractOperation<typeof ComposeLogsOperationInputSchema, void> {
+    protected out?: Writable | undefined;
+    /**
+     * @param out Optional writable stream to capture output. If not provided,
+     *            output is streamed directly to the terminal (stdio: 'inherit').
+     */
+    constructor(out?: Writable | undefined);
+    protected _run(input: z.input<typeof ComposeLogsOperationInputSchema>): Promise<void>;
+}

package/dist/src/docker/compose/operations/ComposeLogsOperation.js

@@ -0,0 +1,85 @@
+import { spawn } from 'node:child_process';
+import * as z from 'zod';
+import { AbstractOperation } from '../../../operations/index.js';
+/**
+ * https://docs.docker.com/reference/cli/docker/compose/logs/
+ */
+export const ComposeLogsOperationInputSchema = z
+    .object({
+    services: z
+        .array(z.string())
+        .optional()
+        .describe('The list of services to show logs for (all if omitted)'),
+    follow: z.boolean().optional().describe('Follow log output'),
+    timestamps: z.boolean().optional().describe('Show timestamps'),
+    tail: z
+        .number()
+        .optional()
+        .describe('Number of lines to show from the end'),
+})
+    .optional();
+export class ComposeLogsOperation extends AbstractOperation {
+    out;
+    /**
+     * @param out Optional writable stream to capture output. If not provided,
+     *            output is streamed directly to the terminal (stdio: 'inherit').
+     */
+    constructor(out) {
+        super(ComposeLogsOperationInputSchema);
+        this.out = out;
+    }
+    async _run(input) {
+        const { monorepo } = this.context;
+        const cmd = 'docker';
+        const args = ['compose', 'logs'];
+        const follow = input?.follow ?? true;
+        if (follow) {
+            args.push('-f');
+        }
+        if (input?.timestamps) {
+            args.push('-t');
+        }
+        if (input?.tail !== undefined) {
+            args.push('--tail', String(input.tail));
+        }
+        if (input?.services && input.services.length > 0) {
+            args.push(...input.services);
+        }
+        const child = spawn(cmd, args, {
+            stdio: this.out ? 'pipe' : 'inherit',
+            cwd: monorepo.rootDir,
+        });
+        if (this.out && child.stdout && child.stderr) {
+            child.stdout.pipe(this.out, { end: false });
+            child.stderr.pipe(this.out, { end: false });
+        }
+        const forward = (sig) => {
+            try {
+                child.kill(sig);
+            }
+            catch { }
+        };
+        const signals = [
+            'SIGINT',
+            'SIGTERM',
+            'SIGHUP',
+            'SIGQUIT',
+        ];
+        signals.forEach((sig) => {
+            process.on(sig, () => forward(sig));
+        });
+        return new Promise((resolve, reject) => {
+            child.on('error', (err) => {
+                reject(new Error(`Failed to execute docker compose logs: ${err.message}`));
+            });
+            child.on('exit', (code) => {
+                if (code !== null && code !== 0) {
+                    reject(new Error(`docker compose logs exited with code ${code}`));
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+}

package/dist/src/docker/compose/operations/index.d.ts

@@ -1,6 +1,7 @@
 export * from './ComposeDownOperation.js';
 export * from './ComposeExecOperation.js';
 export * from './ComposeExecShellOperation.js';
+export * from './ComposeLogsOperation.js';
 export * from './ComposePsOperation.js';
 export * from './ComposeRestartOperation.js';
 export * from './ComposeStartOperation.js';

package/dist/src/docker/compose/operations/index.js

@@ -1,6 +1,7 @@
 export * from './ComposeDownOperation.js';
 export * from './ComposeExecOperation.js';
 export * from './ComposeExecShellOperation.js';
+export * from './ComposeLogsOperation.js';
 export * from './ComposePsOperation.js';
 export * from './ComposeRestartOperation.js';
 export * from './ComposeStartOperation.js';

package/dist/src/index.d.ts

@@ -2,5 +2,6 @@ export * from './context.js';
 export * from './docker/index.js';
 export * from './errors.js';
 export * from './monorepo/index.js';
+export * from './secrets/index.js';
 export * from './types.js';
 export { run } from '@oclif/core';

package/dist/src/index.js

@@ -2,5 +2,6 @@ export * from './context.js';
 export * from './docker/index.js';
 export * from './errors.js';
 export * from './monorepo/index.js';
+export * from './secrets/index.js';
 export * from './types.js';
 export { run } from '@oclif/core';

package/dist/src/monorepo/monorepo.js

@@ -1,4 +1,4 @@
-import { TaskManagerFactory } from '../index.js';
+import { getContext, TaskManagerFactory } from '../index.js';
 import jsonpatch from 'fast-json-patch';
 import { join } from 'node:path';
 import { TemplateExpander } from '../utils/index.js';
@@ -106,12 +106,20 @@ export class Monorepo {
     }
     // Helper to expand a record of strings
     async expand(toExpand, vars, expander = new TemplateExpander()) {
+        const secrets = getContext()?.secrets;
+        const sources = {
+            env: process.env,
+            vars: vars || this.vars,
+        };
+        // Add all registered secret providers as sources
+        if (secrets) {
+            for (const providerName of secrets.getProviderNames()) {
+                sources[providerName] = secrets.createSource(providerName);
+            }
+        }
         const options = {
             default: 'vars',
-            sources: {
-                env: process.env,
-                vars: vars || this.vars,
-            },
+            sources,
         };
         return expander.expandRecord(toExpand, options);
     }

package/dist/src/monorepo/operations/tasks/RunTasksOperation.d.ts

@@ -21,7 +21,7 @@ export type TaskWithScriptAndComponent = TaskInfo & {
 export declare class RunTasksOperation implements IOperation<RunTasksOperationParams, Array<TaskInfo>> {
     run(params: RunTasksOperationParams): Promise<Array<TaskInfo>>;
     protected runDocker(task: TaskWithScriptAndComponent, out?: Writable): Promise<void>;
-    protected runLocal(task: TaskWithScript, out: Writable): Promise<import("stream").Readable>;
+    protected runLocal(task: TaskWithScript, _out: Writable): Promise<import("stream").Readable>;
     private defaultExecutorFor;
     private ensureExecutorValid;
     private availableExecutorsFor;

package/dist/src/monorepo/operations/tasks/RunTasksOperation.js

@@ -82,7 +82,7 @@ export class RunTasksOperation {
             env: await monorepo.expand(task.vars || {}),
         });
     }
-    async runLocal(task, out) {
+    async runLocal(task, _out) {
         const { monorepo } = getContext();
         const cwd = task.component
             ? monorepo.join(monorepo.component(task.component).rootDir)

package/dist/src/monorepo/plugins/VaultPlugin.d.ts

@@ -0,0 +1,46 @@
+import { VaultAuthConfig } from '../../secrets/providers/VaultProvider.js';
+import { AbstractPlugin } from './plugin.js';
+/**
+ * Configuration for the Vault plugin in .emb.yml
+ */
+export interface VaultPluginConfig {
+    /** Vault server address. Defaults to VAULT_ADDR env var. */
+    address?: string;
+    /** Authentication configuration */
+    auth?: VaultAuthConfig;
+    /** Vault namespace. Defaults to VAULT_NAMESPACE env var. */
+    namespace?: string;
+}
+/**
+ * Plugin that integrates HashiCorp Vault with EMB.
+ *
+ * Usage in .emb.yml:
+ * ```yaml
+ * plugins:
+ *   - name: vault
+ *     config:
+ *       address: ${env:VAULT_ADDR:-http://localhost:8200}
+ *       auth:
+ *         method: token
+ *         token: ${env:VAULT_TOKEN}
+ * ```
+ *
+ * Then use secrets in templates:
+ * ```yaml
+ * env:
+ *   DB_PASSWORD: ${vault:secret/myapp/db#password}
+ * ```
+ */
+export declare class VaultPlugin extends AbstractPlugin<VaultPluginConfig> {
+    static name: string;
+    private provider;
+    init(): Promise<void>;
+    /**
+     * Resolve the plugin configuration, filling in defaults from env vars.
+     */
+    private resolveConfig;
+    /**
+     * Resolve authentication configuration.
+     */
+    private resolveAuth;
+}

package/dist/src/monorepo/plugins/VaultPlugin.js

@@ -0,0 +1,91 @@
+import { getContext } from '../../context.js';
+import { VaultProvider, } from '../../secrets/providers/VaultProvider.js';
+import { AbstractPlugin } from './plugin.js';
+/**
+ * Plugin that integrates HashiCorp Vault with EMB.
+ *
+ * Usage in .emb.yml:
+ * ```yaml
+ * plugins:
+ *   - name: vault
+ *     config:
+ *       address: ${env:VAULT_ADDR:-http://localhost:8200}
+ *       auth:
+ *         method: token
+ *         token: ${env:VAULT_TOKEN}
+ * ```
+ *
+ * Then use secrets in templates:
+ * ```yaml
+ * env:
+ *   DB_PASSWORD: ${vault:secret/myapp/db#password}
+ * ```
+ */
+export class VaultPlugin extends AbstractPlugin {
+    static name = 'vault';
+    provider = null;
+    async init() {
+        const resolvedConfig = this.resolveConfig();
+        this.provider = new VaultProvider(resolvedConfig);
+        await this.provider.connect();
+        // Register the provider with the global SecretManager
+        const context = getContext();
+        if (context?.secrets) {
+            context.secrets.register('vault', this.provider);
+        }
+    }
+    /**
+     * Resolve the plugin configuration, filling in defaults from env vars.
+     */
+    resolveConfig() {
+        const address = this.config.address || process.env.VAULT_ADDR;
+        if (!address) {
+            throw new Error('Vault address not configured. Set VAULT_ADDR environment variable or configure address in plugin config.');
+        }
+        const auth = this.resolveAuth();
+        return {
+            address,
+            namespace: this.config.namespace || process.env.VAULT_NAMESPACE,
+            auth,
+        };
+    }
+    /**
+     * Resolve authentication configuration.
+     */
+    resolveAuth() {
+        // If explicit auth config is provided, use it
+        if (this.config.auth) {
+            return this.config.auth;
+        }
+        // Try to infer from environment
+        const token = process.env.VAULT_TOKEN;
+        if (token) {
+            return { method: 'token', token };
+        }
+        const roleId = process.env.VAULT_ROLE_ID;
+        const secretId = process.env.VAULT_SECRET_ID;
+        if (roleId && secretId) {
+            return { method: 'approle', roleId, secretId };
+        }
+        const k8sRole = process.env.VAULT_K8S_ROLE;
+        if (k8sRole) {
+            return { method: 'kubernetes', role: k8sRole };
+        }
+        // JWT auth (non-interactive, for CI/CD)
+        const jwt = process.env.VAULT_JWT;
+        const jwtRole = process.env.VAULT_JWT_ROLE;
+        if (jwt && jwtRole) {
+            return { method: 'jwt', role: jwtRole, jwt };
+        }
+        // OIDC auth (interactive browser flow)
+        const oidcRole = process.env.VAULT_OIDC_ROLE;
+        if (oidcRole !== undefined) {
+            return { method: 'oidc', role: oidcRole || undefined };
+        }
+        throw new Error('Vault authentication not configured. ' +
+            'Set VAULT_TOKEN, or VAULT_ROLE_ID + VAULT_SECRET_ID, ' +
+            'or VAULT_K8S_ROLE, or VAULT_JWT + VAULT_JWT_ROLE, ' +
+            'or VAULT_OIDC_ROLE environment variable, ' +
+            'or configure auth in plugin config.');
+    }
+}

package/dist/src/monorepo/plugins/index.d.ts

@@ -2,6 +2,7 @@ import { AbstractPlugin } from './plugin.js';
 export * from './AutoDockerPlugin.js';
 export * from './DotEnvPlugin.js';
 export * from './EmbfileLoaderPlugin.js';
+export * from './VaultPlugin.js';
 import { Monorepo } from '../index.js';
 export type AbstractPluginConstructor = new <C, P extends AbstractPlugin<C>>(config: C, monorepo: Monorepo) => P;
 export declare const registerPlugin: (plugin: AbstractPluginConstructor) => void;

package/dist/src/monorepo/plugins/index.js

@@ -1,9 +1,11 @@
 export * from './AutoDockerPlugin.js';
 export * from './DotEnvPlugin.js';
 export * from './EmbfileLoaderPlugin.js';
+export * from './VaultPlugin.js';
 import { AutoDockerPlugin } from './AutoDockerPlugin.js';
 import { DotEnvPlugin } from './DotEnvPlugin.js';
 import { EmbfileLoaderPlugin } from './EmbfileLoaderPlugin.js';
+import { VaultPlugin } from './VaultPlugin.js';
 const PluginRegistry = new Map();
 export const registerPlugin = (plugin) => {
     if (PluginRegistry.has(plugin.name)) {
@@ -21,3 +23,4 @@ export const getPlugin = (name) => {
 registerPlugin(AutoDockerPlugin);
 registerPlugin(DotEnvPlugin);
 registerPlugin(EmbfileLoaderPlugin);
+registerPlugin(VaultPlugin);

package/dist/src/secrets/SecretDiscovery.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Location where a secret reference was found.
+ */
+export interface SecretLocation {
+    /** Component name (if applicable) */
+    component?: string;
+    /** Field path within the config (e.g., "env.DB_PASSWORD") */
+    field: string;
+    /** File path where the reference was found */
+    file?: string;
+}
+/**
+ * A discovered secret reference in the configuration.
+ */
+export interface DiscoveredSecret {
+    /** Key within the secret (e.g., "password") */
+    key?: string;
+    /** Where this reference was found */
+    location: SecretLocation;
+    /** Original template string (e.g., "${vault:secret/myapp#password}") */
+    original: string;
+    /** Path to the secret (e.g., "secret/myapp/db") */
+    path: string;
+    /** Provider name (e.g., "vault") */
+    provider: string;
+}
+/**
+ * Discover all secret references in a configuration object.
+ *
+ * @param config - The configuration object to scan
+ * @param location - Base location information
+ * @param secretProviders - Set of registered secret provider names to look for
+ * @returns Array of discovered secret references
+ */
+export declare function discoverSecrets(config: Record<string, unknown>, location?: Omit<SecretLocation, 'field'>, secretProviders?: Set<string>): DiscoveredSecret[];
+/**
+ * Deduplicate secret references by provider+path+key.
+ * Keeps track of all locations where each secret is used.
+ */
+export interface AggregatedSecret {
+    key?: string;
+    locations: SecretLocation[];
+    path: string;
+    provider: string;
+}
+export declare function aggregateSecrets(secrets: DiscoveredSecret[]): AggregatedSecret[];

package/dist/src/secrets/SecretDiscovery.js

@@ -0,0 +1,82 @@
+// Matches ${provider:path#key} patterns for secret providers
+// We're specifically looking for non-env providers (vault, aws, azure, etc.)
+const SECRET_REGEX = /\${(\w+):([\w/.]+(?:-[\w/.]+)*)(?:#([\w-]+))?(?::-[^}]*)?}/g;
+/**
+ * Recursively find all secret references in an object.
+ */
+// eslint-disable-next-line max-params
+function findSecretsInValue(value, fieldPath, location, secretProviders, results) {
+    if (typeof value === 'string') {
+        // Find all secret references in the string
+        let match;
+        SECRET_REGEX.lastIndex = 0; // Reset regex state
+        while ((match = SECRET_REGEX.exec(value)) !== null) {
+            const [original, provider, pathWithKey, explicitKey] = match;
+            // Only include registered secret providers
+            if (!secretProviders.has(provider)) {
+                continue;
+            }
+            // Parse path and key - key can be after # or part of path
+            let path = pathWithKey;
+            let key = explicitKey;
+            // If no explicit key via #, check if path contains #
+            if (!key && path.includes('#')) {
+                const hashIndex = path.indexOf('#');
+                key = path.slice(hashIndex + 1);
+                path = path.slice(0, hashIndex);
+            }
+            results.push({
+                provider,
+                path,
+                key,
+                original,
+                location: {
+                    ...location,
+                    field: fieldPath,
+                },
+            });
+        }
+    }
+    else if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            findSecretsInValue(item, `${fieldPath}[${index}]`, location, secretProviders, results);
+        });
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const [key, val] of Object.entries(value)) {
+            const newPath = fieldPath ? `${fieldPath}.${key}` : key;
+            findSecretsInValue(val, newPath, location, secretProviders, results);
+        }
+    }
+}
+/**
+ * Discover all secret references in a configuration object.
+ *
+ * @param config - The configuration object to scan
+ * @param location - Base location information
+ * @param secretProviders - Set of registered secret provider names to look for
+ * @returns Array of discovered secret references
+ */
+export function discoverSecrets(config, location = {}, secretProviders = new Set()) {
+    const results = [];
+    findSecretsInValue(config, '', location, secretProviders, results);
+    return results;
+}
+export function aggregateSecrets(secrets) {
+    const map = new Map();
+    for (const secret of secrets) {
+        const id = `${secret.provider}:${secret.path}#${secret.key || ''}`;
+        if (map.has(id)) {
+            map.get(id).locations.push(secret.location);
+        }
+        else {
+            map.set(id, {
+                provider: secret.provider,
+                path: secret.path,
+                key: secret.key,
+                locations: [secret.location],
+            });
+        }
+    }
+    return [...map.values()];
+}

package/dist/src/secrets/SecretManager.d.ts

@@ -0,0 +1,52 @@
+import { AbstractSecretProvider, SecretReference } from './SecretProvider.js';
+/**
+ * Type for async source functions compatible with TemplateExpander.
+ */
+export type AsyncSecretSource = (key: string) => Promise<unknown>;
+/**
+ * Manages secret providers and creates template sources for them.
+ */
+export declare class SecretManager {
+    private providers;
+    /**
+     * Register a secret provider.
+     * @param name Provider name (e.g., 'vault', 'op')
+     * @param provider The provider instance
+     */
+    register(name: string, provider: AbstractSecretProvider): void;
+    /**
+     * Get a registered provider by name.
+     * @param name Provider name
+     * @returns The provider instance or undefined if not found
+     */
+    get(name: string): AbstractSecretProvider | undefined;
+    /**
+     * Check if a provider is registered.
+     * @param name Provider name
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered provider names.
+     */
+    getProviderNames(): string[];
+    /**
+     * Connect all registered providers.
+     */
+    connectAll(): Promise<void>;
+    /**
+     * Disconnect all registered providers.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Parse a secret reference string into a SecretReference object.
+     * Format: "path/to/secret#key" or "path/to/secret"
+     * @param refString The reference string to parse
+     */
+    parseReference(refString: string): SecretReference;
+    /**
+     * Create an async source function for use with TemplateExpander.
+     * @param providerName The name of the provider to use
+     * @returns An async function that resolves secrets
+     */
+    createSource(providerName: string): AsyncSecretSource;
+}

package/dist/src/secrets/SecretManager.js

@@ -0,0 +1,75 @@
+/**
+ * Manages secret providers and creates template sources for them.
+ */
+export class SecretManager {
+    providers = new Map();
+    /**
+     * Register a secret provider.
+     * @param name Provider name (e.g., 'vault', 'op')
+     * @param provider The provider instance
+     */
+    register(name, provider) {
+        if (this.providers.has(name)) {
+            throw new Error(`Secret provider '${name}' is already registered`);
+        }
+        this.providers.set(name, provider);
+    }
+    /**
+     * Get a registered provider by name.
+     * @param name Provider name
+     * @returns The provider instance or undefined if not found
+     */
+    get(name) {
+        return this.providers.get(name);
+    }
+    /**
+     * Check if a provider is registered.
+     * @param name Provider name
+     */
+    has(name) {
+        return this.providers.has(name);
+    }
+    /**
+     * Get all registered provider names.
+     */
+    getProviderNames() {
+        return [...this.providers.keys()];
+    }
+    /**
+     * Connect all registered providers.
+     */
+    async connectAll() {
+        await Promise.all([...this.providers.values()].map((p) => p.connect()));
+    }
+    /**
+     * Disconnect all registered providers.
+     */
+    async disconnectAll() {
+        await Promise.all([...this.providers.values()].map((p) => p.disconnect()));
+    }
+    /**
+     * Parse a secret reference string into a SecretReference object.
+     * Format: "path/to/secret#key" or "path/to/secret"
+     * @param refString The reference string to parse
+     */
+    parseReference(refString) {
+        const [path, key] = refString.split('#');
+        return { path, key };
+    }
+    /**
+     * Create an async source function for use with TemplateExpander.
+     * @param providerName The name of the provider to use
+     * @returns An async function that resolves secrets
+     */
+    createSource(providerName) {
+        return async (key) => {
+            const provider = this.get(providerName);
+            if (!provider) {
+                throw new Error(`Secret provider '${providerName}' not found. ` +
+                    `Available providers: ${this.getProviderNames().join(', ') || 'none'}`);
+            }
+            const ref = this.parseReference(key);
+            return provider.get(ref);
+        };
+    }
+}