morphix-env 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+interface SourceBase {
+    /** A later source may replace keys supplied by an earlier source. */
+    override?: boolean;
+    /** Only a missing local file source may be optional. */
+    optional?: boolean;
+}
+interface InfisicalSource extends SourceBase {
+    provider: 'infisical';
+    paths: string[];
+    projectId?: string;
+    siteUrl?: string;
+    env?: string;
+    envPrefix?: string;
+}
+interface LocalSource extends SourceBase {
+    provider: 'local';
+    files: string[];
+}
+interface DotenvxSource extends SourceBase {
+    provider: 'dotenvx';
+    files: string[];
+}
+interface KeychainSource extends SourceBase {
+    provider: 'os-keychain';
+    service: string;
+    platform?: 'macos';
+}
+interface DopplerSource extends SourceBase {
+    provider: 'doppler';
+    project: string;
+    config: string;
+}
+/**
+ * External provider plugin: any executable named `mx-env-provider-<plugin>`
+ * found on PATH. It is invoked once per key with the key name as argv[1] and
+ * writes the value to stdout (one trailing line ending stripped). Provider
+ * login/bootstrap stays inside the plugin, never in repository config.
+ */
+interface PluginSource extends SourceBase {
+    provider: 'plugin';
+    plugin: string;
+    keys: string[];
+}
+type SecretSource = InfisicalSource | LocalSource | DotenvxSource | KeychainSource | DopplerSource | PluginSource;
+interface ProfileDefinition {
+    sources: string[];
+    extends?: string;
+}
+type ProfileInput = string[] | ProfileDefinition;
+interface MxEnvConfig {
+    /** Legacy Infisical configuration retained for backwards compatibility. */
+    infisical?: {
+        projectId?: string;
+        paths: string[];
+        siteUrl?: string;
+        /** Automatically add a prefix (such as VITE_) to loaded keys. */
+        envPrefix?: string;
+    };
+    /** Legacy local override files retained for backwards compatibility. */
+    envFiles?: string[];
+    /** Client __env.js generation configuration. */
+    generate?: {
+        out?: string;
+        filter?: string;
+    };
+    /** Named whole-source collections. Source values never belong in this file. */
+    sources?: Record<string, SecretSource>;
+    /** Named ordered source profiles. */
+    profiles?: Record<string, ProfileInput>;
+    /** Profile selected when a caller does not pass --profile. */
+    defaultProfile?: string;
+}
+interface LoadedConfig {
+    config: MxEnvConfig;
+    path: string;
+    baseDir: string;
+    exists: boolean;
+}
+interface ConfigLayers {
+    global: LoadedConfig;
+    project: LoadedConfig;
+    globalEnvFile: string;
+}
+interface LoadConfigOptions {
+    cwd?: string;
+    homeDir?: string;
+}
+/**
+ * Loads the two intentional configuration discovery points. Values are never
+ * read here; ~/.mx-env/.env is represented as a source by composition later.
+ */
+declare function loadConfigLayers(options?: LoadConfigOptions): ConfigLayers;
+/**
+ * Returns human-readable validation problems without echoing provider values.
+ * Provider credentials deliberately have no place in the declared schema.
+ */
+declare function validateConfig(config: MxEnvConfig, label?: string): string[];
+
+type SourceAvailability = 'loaded' | 'missing-optional' | 'skipped';
+interface SourceEntry {
+    name: string;
+    source: SecretSource;
+    baseDir: string;
+    /** Internal conventional source. Never emitted as a user configuration declaration. */
+    globalImplicit?: boolean;
+    /** Legacy compatibility sources are allowed to skip missing Infisical setup. */
+    legacy?: boolean;
+}
+interface LoadedSource {
+    name: string;
+    provider: SecretSource['provider'];
+    values: Record<string, string>;
+    availability: SourceAvailability;
+}
+
+interface ComposeOptions {
+    profile?: string | null;
+    noGlobal?: boolean;
+    noInfisical?: boolean;
+    envName?: string | null;
+    allowInsecureGlobal?: boolean;
+    envFiles?: string[];
+    baseEnvironment?: NodeJS.ProcessEnv;
+    homeDir?: string;
+}
+interface KeyProvenance {
+    key: string;
+    source: string;
+    provider: SecretSource['provider'];
+    precedence: number;
+    overriddenSources: string[];
+}
+interface SourceStatus {
+    name: string;
+    provider: SecretSource['provider'];
+    availability: LoadedSource['availability'];
+    keyCount: number;
+}
+interface EnvironmentComposition {
+    environment: NodeJS.ProcessEnv;
+    profileName: string;
+    sourceStatuses: SourceStatus[];
+    provenance: Record<string, KeyProvenance>;
+    /** Value-free source descriptors used by the one-shot editor. */
+    sourceEntries: SourceEntry[];
+    /** Kept only in memory for output redaction during this invocation. */
+    redactionValues: string[];
+}
+declare class CompositionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolves sources in precedence order without mutating global process.env.
+ * A caller receives an environment object suitable for exactly one child run.
+ */
+declare function composeEnvironment(layers: ConfigLayers, options?: ComposeOptions): Promise<EnvironmentComposition>;
+
+/**
+ * Redacts exact in-memory values while preserving normal stream output. This is
+ * deliberately not an exfiltration boundary: a child process can transform a
+ * value before printing it. It prevents the common accidental direct echo.
+ */
+declare class StreamingRedactor {
+    private readonly values;
+    private pending;
+    constructor(values: string[]);
+    write(chunk: Buffer | string): string;
+    flush(): string;
+    private incompletePrefixLength;
+    private redact;
+    private lastCompleteMatchEnd;
+}
+
+export { type ComposeOptions, CompositionError, type ConfigLayers, type EnvironmentComposition, type KeyProvenance, type LoadConfigOptions, type LoadedConfig, type MxEnvConfig, type ProfileDefinition, type ProfileInput, type SecretSource, type SourceEntry, type SourceStatus, StreamingRedactor, composeEnvironment, loadConfigLayers, validateConfig };