@karmaniverous/get-dotenv 6.1.0 → 6.2.0

package/dist/plugins-aws.d.ts

@@ -20,9 +20,21 @@ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<s
  * @public
  */
 interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+    /**
+     * Fully resolved option bag used to compute this context.
+     */
     optionsResolved: TOptions;
+    /**
+     * Final composed dotenv environment for this invocation.
+     */
     dotenv: ProcessEnv;
+    /**
+     * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
+     */
     plugins?: Record<string, unknown>;
+    /**
+     * Per-plugin validated configuration slices keyed by realized mount path.
+     */
     pluginConfigs?: Record<string, unknown>;
 }
 
@@ -31,6 +43,14 @@ interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions>
  * For the current step this mirrors the RAW schema; later stages may further
  * narrow types post-resolution in the host pipeline.
  */
+/**
+ * CLI options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvCliOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
 declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
     defaultEnv: z.ZodOptional<z.ZodString>;
     dotenvToken: z.ZodOptional<z.ZodString>;
@@ -74,6 +94,14 @@ declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
  * For now, this mirrors the RAW schema; future stages may materialize defaults
  * and narrow shapes as resolution is wired into the host.
  */
+/**
+ * Programmatic options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
 declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
     defaultEnv: z.ZodOptional<z.ZodString>;
     dotenvToken: z.ZodOptional<z.ZodString>;
@@ -128,7 +156,7 @@ type Logger = Record<string, (...args: unknown[]) => void> | typeof console;
  * Canonical programmatic options type (schema-derived).
  * This type is the single source of truth for programmatic options.
  */
-type GetDotenvOptions = z.output<typeof getDotenvOptionsSchemaResolved> & {
+type GetDotenvOptions = Omit<z.output<typeof getDotenvOptionsSchemaResolved>, 'logger' | 'dynamic'> & {
     /**
      * Compile-time overlay: narrowed logger for DX (schema stores unknown).
      */
@@ -149,11 +177,15 @@ type Scripts = ScriptsTable;
  * stringly paths/vars, and inherited programmatic fields (minus normalized
  * shapes that are handled by resolution).
  */
-type GetDotenvCliOptions = z.output<typeof getDotenvCliOptionsSchemaResolved> & {
+type GetDotenvCliOptions = Omit<z.output<typeof getDotenvCliOptionsSchemaResolved>, 'logger' | 'dynamic' | 'scripts'> & {
     /**
      * Compile-only overlay for DX: logger narrowed from unknown.
      */
     logger: Logger;
+    /**
+     * Compile-only overlay for DX: dynamic map narrowed from unknown.
+     */
+    dynamic?: GetDotenvDynamic;
     /**
      * Compile-only overlay for DX: scripts narrowed from Record\<string, unknown\>.
      */
@@ -216,13 +248,37 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     getCtx(): GetDotenvCliCtx<TOptions>;
     /** Check whether a context has been resolved (non-throwing). */
     hasCtx(): boolean;
+    /**
+     * Resolve options and compute the dotenv context for this invocation.
+     *
+     * @param customOptions - Partial options to overlay for this invocation.
+     * @param opts - Optional resolver behavior switches (for example, whether to run `afterResolve`).
+     * @returns A promise resolving to the computed invocation context.
+     */
     resolveAndLoad(customOptions?: Partial<TOptions>, opts?: ResolveAndLoadOptions): Promise<GetDotenvCliCtx<TOptions>>;
+    /**
+     * Tag an option with a help group identifier for grouped root help rendering.
+     *
+     * @param opt - The Commander option to tag.
+     * @param group - Group identifier (for example, `base`, `app`, or `plugin:<name>`).
+     * @returns Nothing.
+     */
     setOptionGroup(opt: Option, group: string): void;
     /**
      * Create a dynamic option whose description is computed at help time
      * from the resolved configuration.
      */
+    /**
+     * Create a dynamic option whose description is computed at help time from the resolved configuration.
+     *
+     * @param flags - Commander option flags usage string.
+     * @param desc - Description builder called during help rendering with the resolved help config.
+     * @param parser - Optional argument parser.
+     * @param defaultValue - Optional default value.
+     * @returns A Commander `Option` instance with a dynamic description.
+     */
     createDynamicOption<Usage extends string>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option<Usage>;
+    /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
 /**
@@ -285,14 +341,40 @@ interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOption
  * return types from definePlugin provide stronger DX for shipped/typed plugins.
  */
 interface PluginWithInstanceHelpers<TOptions extends GetDotenvOptions = GetDotenvOptions, TConfig = unknown, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> extends GetDotenvCliPlugin<TOptions, TArgs, TOpts, TGlobal> {
+    /**
+     * Read the validated (and interpolated) configuration slice for this plugin instance.
+     *
+     * @param cli - The plugin mount (or any command under this mount) used to resolve the invocation context.
+     * @returns The plugin configuration slice, typed as `TCfg`.
+     * @throws Error when called before the host has resolved the invocation context.
+     */
     readConfig<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions, unknown[], OptionValues, OptionValues>): Readonly<TCfg>;
+    /**
+     * Create a Commander option whose help-time description receives the resolved root help config
+     * and this plugin instance’s validated configuration slice.
+     *
+     * @typeParam TCfg - The plugin configuration slice type.
+     * @typeParam Usage - The Commander usage string for the option flags.
+     * @param cli - The plugin mount used to associate the option with a realized mount path.
+     * @param flags - Commander option flags usage string.
+     * @param desc - Description builder receiving the resolved help config and the plugin config slice.
+     * @param parser - Optional argument parser.
+     * @param defaultValue - Optional default value.
+     * @returns A Commander `Option` instance with a dynamic description.
+     */
     createPluginDynamicOption<TCfg = TConfig, Usage extends string = string>(cli: GetDotenvCliPublic<TOptions, unknown[], OptionValues, OptionValues>, flags: Usage, desc: (cfg: ResolvedHelpConfig, pluginCfg: Readonly<TCfg>) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option<Usage>;
 }
 
 /**
- * Zod schema for AWS plugin configuration.
+ * AWS plugin configuration schema.
+ *
+ * @remarks
+ * This Zod schema is used by the host to validate the `plugins.aws` config slice.
+ *
+ * @public
+ * @hidden
  */
-declare const AwsPluginConfigSchema: z.ZodObject<{
+declare const awsPluginConfigSchema: z.ZodObject<{
     profile: z.ZodOptional<z.ZodString>;
     region: z.ZodOptional<z.ZodString>;
     defaultRegion: z.ZodOptional<z.ZodString>;
@@ -308,7 +390,7 @@ declare const AwsPluginConfigSchema: z.ZodObject<{
 /**
  * AWS plugin configuration object.
  */
-type AwsPluginConfig = z.infer<typeof AwsPluginConfigSchema>;
+type AwsPluginConfig = z.infer<typeof awsPluginConfigSchema>;
 /**
  * Arguments for resolving AWS context (profile/region/credentials).
  *
@@ -338,6 +420,12 @@ declare const awsPlugin: () => PluginWithInstanceHelpers<GetDotenvOptions, {
     strategy?: "cli-export" | "none" | undefined;
     loginOnDemand?: boolean | undefined;
 }, [], {}, {}>;
+/**
+ * AWS plugin instance type returned by {@link awsPlugin}.
+ *
+ * @public
+ */
+type AwsPlugin = ReturnType<typeof awsPlugin>;
 
 export { awsPlugin };
-export type { ResolveAwsContextOptions };
+export type { AwsPlugin, ResolveAwsContextOptions };