@env-lane/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,221 @@
+interface CheckResult {
+    ok: boolean;
+    selectorKey: string;
+    violations: Array<{
+        file: string;
+        relativeFile: string;
+        line?: number;
+    }>;
+    missingRequired: Array<{
+        file: string;
+        relativeFile: string;
+        target: string;
+    }>;
+}
+declare function checkDotenvSelector(options?: {
+    cwd?: string;
+    configFile?: string;
+    target?: string;
+    build?: string;
+    requireOverride?: boolean;
+}): Promise<CheckResult>;
+
+type EnvLaneOutputFormat = 'text' | 'json' | 'dotenv';
+interface EnvSortTargetConfig {
+    baseDir?: string;
+    file?: string;
+    template?: string;
+    files?: Record<string, string>;
+}
+interface EnvLaneConfig {
+    selector?: {
+        /** Environment selector variable. Defaults to ENV_BUILD. */
+        envKey?: string;
+        /** Default build name when no CLI/API build is supplied. Defaults to local. */
+        defaultBuild?: string;
+        /** List of valid build names. If empty, all builds are allowed. */
+        builds?: string[];
+        /** Forbid selector envKey in dotenv files. Defaults to true. */
+        forbidInDotenv?: boolean;
+    };
+    workspace?: {
+        /** Optional package globs. Defaults to pnpm-workspace.yaml, then packages/* and apps/*. */
+        packageGlobs?: string[];
+        /** Additional aliases, keyed by alias, value package name or relative directory. */
+        aliases?: Record<string, string>;
+        /** Default target when multiple packages exist. Defaults to error. */
+        defaultTarget?: string;
+        /** Whether root is exposed as a target. Defaults to true. */
+        includeRoot?: boolean;
+    };
+    dotenv?: {
+        /** Ordered dotenv patterns relative to target dir. {build} is interpolated. */
+        order?: string[];
+        /** Build name that maps to localOverrideFile. Defaults to local. */
+        localBuildName?: string;
+        /** Override file for local build. Defaults to .env.local. */
+        localOverrideFile?: string;
+        /** Fail if the selected override file is missing. Defaults to false. */
+        requireOverride?: boolean;
+        /** Merge process.env after dotenv files. Defaults to true. */
+        includeProcessEnv?: boolean;
+    };
+    vault?: {
+        enabled?: boolean;
+        disableUnsafeWarning?: boolean;
+        configFile?: string;
+    };
+    output?: {
+        /** Default output format for CLI. */
+        format?: EnvLaneOutputFormat;
+    };
+    sort?: Record<string, EnvSortTargetConfig>;
+}
+interface ResolvedEnvLaneConfig {
+    rootDir: string;
+    selector: Required<NonNullable<EnvLaneConfig['selector']>>;
+    workspace: Required<Omit<NonNullable<EnvLaneConfig['workspace']>, 'aliases'>> & {
+        aliases: Record<string, string>;
+    };
+    dotenv: Required<NonNullable<EnvLaneConfig['dotenv']>>;
+    vault: Required<NonNullable<EnvLaneConfig['vault']>>;
+    output: Required<NonNullable<EnvLaneConfig['output']>>;
+    sort?: Record<string, EnvSortTargetConfig>;
+}
+interface WorkspacePackage {
+    name?: string;
+    dir: string;
+    relativeDir: string;
+    aliases: string[];
+    isRoot: boolean;
+}
+interface EnvFileRef {
+    kind: 'base' | 'override' | 'custom';
+    path: string;
+    relativePath: string;
+    exists: boolean;
+    required: boolean;
+    order: number;
+}
+interface EnvSource {
+    source: 'dotenv' | 'process' | 'selector';
+    file?: string;
+    relativeFile?: string;
+    line?: number;
+    shellOverride?: boolean;
+}
+interface ResolveEnvOptions {
+    cwd?: string;
+    configFile?: string;
+    target?: string;
+    build?: string;
+    includeProcessEnv?: boolean;
+    requireOverride?: boolean;
+    redact?: boolean;
+    showSecrets?: boolean;
+}
+interface ResolvedEnv {
+    rootDir: string;
+    target: WorkspacePackage;
+    build: string;
+    selectorKey: string;
+    files: EnvFileRef[];
+    values: Record<string, string>;
+    sources: Record<string, EnvSource>;
+}
+
+declare function defineConfig(config: EnvLaneConfig): EnvLaneConfig;
+declare function findWorkspaceRoot(cwd?: string): Promise<string>;
+declare function readPnpmWorkspaceGlobs(rootDir: string): string[];
+declare function loadEnvLaneConfig(options?: {
+    cwd?: string;
+    configFile?: string;
+}): Promise<ResolvedEnvLaneConfig>;
+
+declare function resolveBuildName(options: ResolveEnvOptions, envKey: string, defaultBuild: string): string;
+declare function listEnvFiles(options?: ResolveEnvOptions): Promise<EnvFileRef[]>;
+declare function listEnvFilesForTarget(config: ResolvedEnvLaneConfig, target: WorkspacePackage, options?: ResolveEnvOptions): EnvFileRef[];
+declare function resolveInjectedEnv(options?: ResolveEnvOptions): Promise<ResolvedEnv>;
+
+interface Logger {
+    log(message: any, ...args: any[]): void;
+    info(message: any, ...args: any[]): void;
+    warn(message: any, ...args: any[]): void;
+    error(message: any, ...args: any[]): void;
+    success(message: any, ...args: any[]): void;
+    debug(message: any, ...args: any[]): void;
+    /** For interactive prompts or raw stdout writes */
+    write(message: string): void;
+}
+declare function setLogger(logger: Logger): void;
+declare function getLogger(): Logger;
+
+declare function isSecretLikeKey(key: string): boolean;
+declare function redactValue(key: string, value: string, showSecrets?: boolean): string;
+declare function redactRecord(values: Record<string, string>, showSecrets?: boolean): Record<string, string>;
+
+declare function runWithInjectedEnv(options: {
+    cwd?: string;
+    configFile?: string;
+    target?: string;
+    build?: string;
+    command: string[];
+    runCwd?: 'target' | 'root' | string;
+    quiet?: boolean;
+}): Promise<number>;
+
+type SortOperationAction = 'move' | 'insert-commented' | 'append-extra' | 'append-duplicate' | 'group-duplicate';
+interface EnvSortPlan {
+    filePath: string;
+    templateFilePath: string;
+    changed: boolean;
+    currentContent: string;
+    nextContent: string;
+    operations: Array<{
+        action: SortOperationAction;
+        key: string;
+    }>;
+    summary: {
+        movedCount: number;
+        insertedCommentedCount: number;
+        appendedExtraCount: number;
+        appendedDuplicateCount: number;
+        groupedDuplicateCount: number;
+    };
+}
+declare function buildEnvSortPlan(envFilePath: string, templateFilePath: string): EnvSortPlan;
+declare function sortEnvFile(envFilePath: string, templateFilePath: string): Promise<{
+    movedCount: number;
+    insertedCommentedCount: number;
+    appendedExtraCount: number;
+    appendedDuplicateCount: number;
+    groupedDuplicateCount: number;
+    applied: boolean;
+    filePath: string;
+    templateFilePath: string;
+}>;
+declare function sortEnvFilesFromConfig(configPath: string, keyArg?: string, envSuffixArg?: string): Promise<{
+    applied: boolean;
+    count: number;
+    results: {
+        movedCount: number;
+        insertedCommentedCount: number;
+        appendedExtraCount: number;
+        appendedDuplicateCount: number;
+        groupedDuplicateCount: number;
+        applied: boolean;
+        filePath: string;
+        templateFilePath: string;
+    }[];
+}>;
+
+type WorkspaceResolveOptions = Pick<ResolveEnvOptions, 'cwd' | 'configFile'> & {
+    config?: ResolvedEnvLaneConfig;
+    packages?: WorkspacePackage[];
+};
+declare function listWorkspacePackages(options?: WorkspaceResolveOptions): Promise<WorkspacePackage[]>;
+declare function listWorkspacePackagesForConfig(config: ResolvedEnvLaneConfig): Promise<WorkspacePackage[]>;
+declare function resolveTargetPackageFromList(target: string | undefined, config: ResolvedEnvLaneConfig, packages: WorkspacePackage[]): WorkspacePackage;
+declare function resolveTargetPackage(target: string | undefined, options?: WorkspaceResolveOptions): Promise<WorkspacePackage>;
+
+export { type CheckResult, type EnvFileRef, type EnvLaneConfig, type EnvLaneOutputFormat, type EnvSortPlan, type EnvSortTargetConfig, type EnvSource, type Logger, type ResolveEnvOptions, type ResolvedEnv, type ResolvedEnvLaneConfig, type SortOperationAction, type WorkspacePackage, buildEnvSortPlan, checkDotenvSelector, defineConfig, findWorkspaceRoot, getLogger, isSecretLikeKey, listEnvFiles, listEnvFilesForTarget, listWorkspacePackages, listWorkspacePackagesForConfig, loadEnvLaneConfig, readPnpmWorkspaceGlobs, redactRecord, redactValue, resolveBuildName, resolveInjectedEnv, resolveTargetPackage, resolveTargetPackageFromList, runWithInjectedEnv, setLogger, sortEnvFile, sortEnvFilesFromConfig };

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+interface CheckResult {
+    ok: boolean;
+    selectorKey: string;
+    violations: Array<{
+        file: string;
+        relativeFile: string;
+        line?: number;
+    }>;
+    missingRequired: Array<{
+        file: string;
+        relativeFile: string;
+        target: string;
+    }>;
+}
+declare function checkDotenvSelector(options?: {
+    cwd?: string;
+    configFile?: string;
+    target?: string;
+    build?: string;
+    requireOverride?: boolean;
+}): Promise<CheckResult>;
+
+type EnvLaneOutputFormat = 'text' | 'json' | 'dotenv';
+interface EnvSortTargetConfig {
+    baseDir?: string;
+    file?: string;
+    template?: string;
+    files?: Record<string, string>;
+}
+interface EnvLaneConfig {
+    selector?: {
+        /** Environment selector variable. Defaults to ENV_BUILD. */
+        envKey?: string;
+        /** Default build name when no CLI/API build is supplied. Defaults to local. */
+        defaultBuild?: string;
+        /** List of valid build names. If empty, all builds are allowed. */
+        builds?: string[];
+        /** Forbid selector envKey in dotenv files. Defaults to true. */
+        forbidInDotenv?: boolean;
+    };
+    workspace?: {
+        /** Optional package globs. Defaults to pnpm-workspace.yaml, then packages/* and apps/*. */
+        packageGlobs?: string[];
+        /** Additional aliases, keyed by alias, value package name or relative directory. */
+        aliases?: Record<string, string>;
+        /** Default target when multiple packages exist. Defaults to error. */
+        defaultTarget?: string;
+        /** Whether root is exposed as a target. Defaults to true. */
+        includeRoot?: boolean;
+    };
+    dotenv?: {
+        /** Ordered dotenv patterns relative to target dir. {build} is interpolated. */
+        order?: string[];
+        /** Build name that maps to localOverrideFile. Defaults to local. */
+        localBuildName?: string;
+        /** Override file for local build. Defaults to .env.local. */
+        localOverrideFile?: string;
+        /** Fail if the selected override file is missing. Defaults to false. */
+        requireOverride?: boolean;
+        /** Merge process.env after dotenv files. Defaults to true. */
+        includeProcessEnv?: boolean;
+    };
+    vault?: {
+        enabled?: boolean;
+        disableUnsafeWarning?: boolean;
+        configFile?: string;
+    };
+    output?: {
+        /** Default output format for CLI. */
+        format?: EnvLaneOutputFormat;
+    };
+    sort?: Record<string, EnvSortTargetConfig>;
+}
+interface ResolvedEnvLaneConfig {
+    rootDir: string;
+    selector: Required<NonNullable<EnvLaneConfig['selector']>>;
+    workspace: Required<Omit<NonNullable<EnvLaneConfig['workspace']>, 'aliases'>> & {
+        aliases: Record<string, string>;
+    };
+    dotenv: Required<NonNullable<EnvLaneConfig['dotenv']>>;
+    vault: Required<NonNullable<EnvLaneConfig['vault']>>;
+    output: Required<NonNullable<EnvLaneConfig['output']>>;
+    sort?: Record<string, EnvSortTargetConfig>;
+}
+interface WorkspacePackage {
+    name?: string;
+    dir: string;
+    relativeDir: string;
+    aliases: string[];
+    isRoot: boolean;
+}
+interface EnvFileRef {
+    kind: 'base' | 'override' | 'custom';
+    path: string;
+    relativePath: string;
+    exists: boolean;
+    required: boolean;
+    order: number;
+}
+interface EnvSource {
+    source: 'dotenv' | 'process' | 'selector';
+    file?: string;
+    relativeFile?: string;
+    line?: number;
+    shellOverride?: boolean;
+}
+interface ResolveEnvOptions {
+    cwd?: string;
+    configFile?: string;
+    target?: string;
+    build?: string;
+    includeProcessEnv?: boolean;
+    requireOverride?: boolean;
+    redact?: boolean;
+    showSecrets?: boolean;
+}
+interface ResolvedEnv {
+    rootDir: string;
+    target: WorkspacePackage;
+    build: string;
+    selectorKey: string;
+    files: EnvFileRef[];
+    values: Record<string, string>;
+    sources: Record<string, EnvSource>;
+}
+
+declare function defineConfig(config: EnvLaneConfig): EnvLaneConfig;
+declare function findWorkspaceRoot(cwd?: string): Promise<string>;
+declare function readPnpmWorkspaceGlobs(rootDir: string): string[];
+declare function loadEnvLaneConfig(options?: {
+    cwd?: string;
+    configFile?: string;
+}): Promise<ResolvedEnvLaneConfig>;
+
+declare function resolveBuildName(options: ResolveEnvOptions, envKey: string, defaultBuild: string): string;
+declare function listEnvFiles(options?: ResolveEnvOptions): Promise<EnvFileRef[]>;
+declare function listEnvFilesForTarget(config: ResolvedEnvLaneConfig, target: WorkspacePackage, options?: ResolveEnvOptions): EnvFileRef[];
+declare function resolveInjectedEnv(options?: ResolveEnvOptions): Promise<ResolvedEnv>;
+
+interface Logger {
+    log(message: any, ...args: any[]): void;
+    info(message: any, ...args: any[]): void;
+    warn(message: any, ...args: any[]): void;
+    error(message: any, ...args: any[]): void;
+    success(message: any, ...args: any[]): void;
+    debug(message: any, ...args: any[]): void;
+    /** For interactive prompts or raw stdout writes */
+    write(message: string): void;
+}
+declare function setLogger(logger: Logger): void;
+declare function getLogger(): Logger;
+
+declare function isSecretLikeKey(key: string): boolean;
+declare function redactValue(key: string, value: string, showSecrets?: boolean): string;
+declare function redactRecord(values: Record<string, string>, showSecrets?: boolean): Record<string, string>;
+
+declare function runWithInjectedEnv(options: {
+    cwd?: string;
+    configFile?: string;
+    target?: string;
+    build?: string;
+    command: string[];
+    runCwd?: 'target' | 'root' | string;
+    quiet?: boolean;
+}): Promise<number>;
+
+type SortOperationAction = 'move' | 'insert-commented' | 'append-extra' | 'append-duplicate' | 'group-duplicate';
+interface EnvSortPlan {
+    filePath: string;
+    templateFilePath: string;
+    changed: boolean;
+    currentContent: string;
+    nextContent: string;
+    operations: Array<{
+        action: SortOperationAction;
+        key: string;
+    }>;
+    summary: {
+        movedCount: number;
+        insertedCommentedCount: number;
+        appendedExtraCount: number;
+        appendedDuplicateCount: number;
+        groupedDuplicateCount: number;
+    };
+}
+declare function buildEnvSortPlan(envFilePath: string, templateFilePath: string): EnvSortPlan;
+declare function sortEnvFile(envFilePath: string, templateFilePath: string): Promise<{
+    movedCount: number;
+    insertedCommentedCount: number;
+    appendedExtraCount: number;
+    appendedDuplicateCount: number;
+    groupedDuplicateCount: number;
+    applied: boolean;
+    filePath: string;
+    templateFilePath: string;
+}>;
+declare function sortEnvFilesFromConfig(configPath: string, keyArg?: string, envSuffixArg?: string): Promise<{
+    applied: boolean;
+    count: number;
+    results: {
+        movedCount: number;
+        insertedCommentedCount: number;
+        appendedExtraCount: number;
+        appendedDuplicateCount: number;
+        groupedDuplicateCount: number;
+        applied: boolean;
+        filePath: string;
+        templateFilePath: string;
+    }[];
+}>;
+
+type WorkspaceResolveOptions = Pick<ResolveEnvOptions, 'cwd' | 'configFile'> & {
+    config?: ResolvedEnvLaneConfig;
+    packages?: WorkspacePackage[];
+};
+declare function listWorkspacePackages(options?: WorkspaceResolveOptions): Promise<WorkspacePackage[]>;
+declare function listWorkspacePackagesForConfig(config: ResolvedEnvLaneConfig): Promise<WorkspacePackage[]>;
+declare function resolveTargetPackageFromList(target: string | undefined, config: ResolvedEnvLaneConfig, packages: WorkspacePackage[]): WorkspacePackage;
+declare function resolveTargetPackage(target: string | undefined, options?: WorkspaceResolveOptions): Promise<WorkspacePackage>;
+
+export { type CheckResult, type EnvFileRef, type EnvLaneConfig, type EnvLaneOutputFormat, type EnvSortPlan, type EnvSortTargetConfig, type EnvSource, type Logger, type ResolveEnvOptions, type ResolvedEnv, type ResolvedEnvLaneConfig, type SortOperationAction, type WorkspacePackage, buildEnvSortPlan, checkDotenvSelector, defineConfig, findWorkspaceRoot, getLogger, isSecretLikeKey, listEnvFiles, listEnvFilesForTarget, listWorkspacePackages, listWorkspacePackagesForConfig, loadEnvLaneConfig, readPnpmWorkspaceGlobs, redactRecord, redactValue, resolveBuildName, resolveInjectedEnv, resolveTargetPackage, resolveTargetPackageFromList, runWithInjectedEnv, setLogger, sortEnvFile, sortEnvFilesFromConfig };