@karmaniverous/get-dotenv 6.0.0-1 → 6.1.0

package/templates/cli/index.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { createCli } from '@karmaniverous/get-dotenv/cli';
+import {
+  awsPlugin,
+  awsWhoamiPlugin,
+  batchPlugin,
+  cmdPlugin,
+  initPlugin,
+} from '@karmaniverous/get-dotenv/plugins';
+
+import { helloPlugin } from './plugins/hello';
+
+await createCli({
+  alias: 'mycli',
+  compose: (program) =>
+    program
+      .use(
+        cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }),
+      )
+      .use(batchPlugin())
+      .use(awsPlugin().use(awsWhoamiPlugin()))
+      .use(initPlugin())
+      .use(helloPlugin()),
+})();

package/templates/cli/plugins/hello.ts

@@ -0,0 +1,42 @@
+import {
+  definePlugin,
+  getRootCommand,
+} from '@karmaniverous/get-dotenv/cliHost';
+import { z } from 'zod';
+
+const HelloConfigSchema = z.object({
+  loud: z.boolean().optional().default(false),
+  color: z.string().optional(),
+});
+
+export const helloPlugin = () => {
+  const plugin = definePlugin({
+    ns: 'hello',
+    configSchema: HelloConfigSchema,
+    setup(cli) {
+      cli
+        .description('Say hello with current dotenv context')
+        .addOption(
+          plugin.createPluginDynamicOption(
+            cli,
+            '--loud',
+            (_bag, pluginCfg) =>
+              `print greeting in ALL CAPS${pluginCfg.loud ? ' (default)' : ''}`,
+          ),
+        )
+        .action(() => {
+          const ctx = cli.getCtx();
+          // Derive CLI name from the true root command using a typed helper.
+          const rootName = getRootCommand(cli).name();
+
+          const cfg = plugin.readConfig(cli);
+          const keys = Object.keys(ctx.dotenv);
+          const label = cfg.loud
+            ? `[${rootName}] DOTENV KEYS (${String(keys.length)}):`
+            : `[${rootName}] dotenv keys (${String(keys.length)}):`;
+          console.log(label, keys.join(', '));
+        });
+    },
+  });
+  return plugin;
+};

package/templates/config/js/getdotenv.config.js

@@ -1,7 +1,12 @@
 export default {
-  dotenvToken: '.env',
-  privateToken: 'local',
-  paths: './',
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
   vars: { APP_SETTING: 'app_value' },
   envVars: { dev: { ENV_SETTING: 'dev_value' } },
   dynamic: {

package/templates/config/json/public/getdotenv.config.json

@@ -1,7 +1,4 @@
 {
-  "dotenvToken": ".env",
-  "privateToken": "local",
-  "paths": "./",
   "vars": {
     "APP_SETTING": "app_value"
   },

package/templates/config/public/getdotenv.config.json

@@ -1,9 +1,4 @@
 {
-  "dotenvToken": ".env",
-  "privateToken": "local",
-  "paths": "./",
-  "loadProcess": true,
-  "log": false,
   "vars": {
     "APP_NAME": "my-app"
   },

package/templates/config/ts/getdotenv.config.ts

@@ -6,9 +6,14 @@ type Vars = {
 };
 
 export default defineGetDotenvConfig<Vars>({
-  dotenvToken: '.env',
-  privateToken: 'local',
-  paths: './',
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
   vars: { APP_SETTING: 'app_value' },
   envVars: { dev: { ENV_SETTING: 'dev_value' } },
   dynamic: {

package/templates/config/yaml/public/getdotenv.config.yaml

@@ -1,6 +1,3 @@
-dotenvToken: ".env"
-privateToken: "local"
-paths: "./"
 vars:
   APP_SETTING: "app_value"
 envVars:

package/dist/plugins-demo.d.ts

@@ -1,204 +0,0 @@
-import { z, ZodObject } from 'zod';
-import { Command, Option } from 'commander';
-
-/**
- * Scripts table shape (configurable shell type).
- */
-type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
-    cmd: string;
-    shell?: TShell | undefined;
-}>;
-
-declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
-    defaultEnv: z.ZodOptional<z.ZodString>;
-    dotenvToken: z.ZodOptional<z.ZodString>;
-    dynamicPath: z.ZodOptional<z.ZodString>;
-    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    env: z.ZodOptional<z.ZodString>;
-    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
-    excludeEnv: z.ZodOptional<z.ZodBoolean>;
-    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
-    excludePrivate: z.ZodOptional<z.ZodBoolean>;
-    excludePublic: z.ZodOptional<z.ZodBoolean>;
-    loadProcess: z.ZodOptional<z.ZodBoolean>;
-    log: z.ZodOptional<z.ZodBoolean>;
-    logger: z.ZodOptional<z.ZodUnknown>;
-    outputPath: z.ZodOptional<z.ZodString>;
-    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    privateToken: z.ZodOptional<z.ZodString>;
-    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
-}, z.core.$strip>;
-
-/**
- * A minimal representation of an environment key/value mapping.
- * Values may be `undefined` to represent "unset".
- */
-type ProcessEnv = Record<string, string | undefined>;
-/**
- * Dynamic variable function signature. Receives the current expanded variables
- * and the selected environment (if any), and returns either a string to set
- * or `undefined` to unset/skip the variable.
- */
-type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
-type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
-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> & {
-    /**
-     * Compile-time overlay: narrowed logger for DX (schema stores unknown).
-     */
-    logger?: Logger;
-    /**
-     * Compile-time overlay: narrowed dynamic map for DX (schema stores unknown).
-     */
-    dynamic?: GetDotenvDynamic;
-};
-
-declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
-    defaultEnv: z.ZodOptional<z.ZodString>;
-    dotenvToken: z.ZodOptional<z.ZodString>;
-    dynamicPath: z.ZodOptional<z.ZodString>;
-    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    env: z.ZodOptional<z.ZodString>;
-    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
-    excludeEnv: z.ZodOptional<z.ZodBoolean>;
-    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
-    excludePrivate: z.ZodOptional<z.ZodBoolean>;
-    excludePublic: z.ZodOptional<z.ZodBoolean>;
-    loadProcess: z.ZodOptional<z.ZodBoolean>;
-    log: z.ZodOptional<z.ZodBoolean>;
-    logger: z.ZodOptional<z.ZodUnknown>;
-    outputPath: z.ZodOptional<z.ZodString>;
-    privateToken: z.ZodOptional<z.ZodString>;
-    debug: z.ZodOptional<z.ZodBoolean>;
-    strict: z.ZodOptional<z.ZodBoolean>;
-    capture: z.ZodOptional<z.ZodBoolean>;
-    trace: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
-    redact: z.ZodOptional<z.ZodBoolean>;
-    warnEntropy: z.ZodOptional<z.ZodBoolean>;
-    entropyThreshold: z.ZodOptional<z.ZodNumber>;
-    entropyMinLength: z.ZodOptional<z.ZodNumber>;
-    entropyWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    redactPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    paths: z.ZodOptional<z.ZodString>;
-    pathsDelimiter: z.ZodOptional<z.ZodString>;
-    pathsDelimiterPattern: z.ZodOptional<z.ZodString>;
-    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    shell: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
-    vars: z.ZodOptional<z.ZodString>;
-    varsAssignor: z.ZodOptional<z.ZodString>;
-    varsAssignorPattern: z.ZodOptional<z.ZodString>;
-    varsDelimiter: z.ZodOptional<z.ZodString>;
-    varsDelimiterPattern: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-
-type Scripts = ScriptsTable;
-/**
- * Canonical CLI options type derived from the Zod schema output.
- * Includes CLI-only flags (debug/strict/capture/trace/redaction/entropy),
- * stringly paths/vars, and inherited programmatic fields (minus normalized
- * shapes that are handled by resolution).
- */
-type GetDotenvCliOptions = z.output<typeof getDotenvCliOptionsSchemaResolved> & {
-    /**
-     * Compile-only overlay for DX: logger narrowed from unknown.
-     */
-    logger?: Logger;
-    /**
-     * Compile-only overlay for DX: scripts narrowed from Record\<string, unknown\>.
-     */
-    scripts?: Scripts;
-};
-
-type ResolvedHelpConfig = Partial<GetDotenvCliOptions> & {
-    plugins: Record<string, unknown>;
-};
-/** Per-invocation context shared with plugins and actions. */
-type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
-    optionsResolved: TOptions;
-    dotenv: ProcessEnv;
-    plugins?: Record<string, unknown>;
-    pluginConfigs?: Record<string, unknown>;
-};
-
-/** src/cliHost/definePlugin.ts
- * Plugin contracts for the GetDotenv CLI host.
- *
- * This module exposes a structural public interface for the host that plugins
- * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
- * nominal class identity issues (private fields) in downstream consumers.
- */
-
-/**
- * Structural public interface for the host exposed to plugins.
- * - Extends Commander.Command so plugins can attach options/commands/hooks.
- * - Adds host-specific helpers used by built-in plugins.
- *
- * Purpose: remove nominal class identity (private fields) from the plugin seam
- * to avoid TS2379 under exactOptionalPropertyTypes in downstream consumers.
- */
-interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
-    ns(name: string): Command;
-    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
-    resolveAndLoad(customOptions?: Partial<TOptions>, opts?: {
-        runAfterResolve?: boolean;
-    }): Promise<GetDotenvCliCtx<TOptions>>;
-    setOptionGroup(opt: Option, group: string): void;
-    /**
-     * Create a dynamic option whose description is computed at help time
-     * from the resolved configuration.
-     */
-    createDynamicOption(flags: string, desc: (cfg: ResolvedHelpConfig & {
-        plugins: Record<string, unknown>;
-    }) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option;
-    createDynamicOption<TValue = unknown>(flags: string, desc: (cfg: ResolvedHelpConfig & {
-        plugins: Record<string, unknown>;
-    }) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option;
-}
-/** Public plugin contract used by the GetDotenv CLI host. */
-interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions> {
-    id?: string;
-    /**
-     * Setup phase: register commands and wiring on the provided CLI instance.
-     * Runs parent → children (pre-order).
-     */
-    setup: (cli: GetDotenvCliPublic<TOptions>) => void | Promise<void>;
-    /**
-     * After the dotenv context is resolved, initialize any clients/secrets
-     * or attach per-plugin state under ctx.plugins (by convention).
-     * Runs parent → children (pre-order).
-     */
-    afterResolve?: (cli: GetDotenvCliPublic<TOptions>, ctx: GetDotenvCliCtx<TOptions>) => void | Promise<void>;
-    /**
-     * Zod schema for this plugin's config slice (from config.plugins[id]).
-     * Enforced object-like (ZodObject) to simplify code paths and inference.
-     */
-    configSchema?: ZodObject;
-    /**
-     * Compositional children. Installed after the parent per pre-order.
-     */
-    children: GetDotenvCliPlugin<TOptions>[];
-    /**
-     * Compose a child plugin. Returns the parent to enable chaining.
-     */
-    use: (child: GetDotenvCliPlugin<TOptions>) => GetDotenvCliPlugin<TOptions>;
-}
-/**
- * Compile-time helper type: the plugin object returned by definePlugin always
- * includes the instance-bound helpers as required members. Keeping the public
- * interface optional preserves compatibility for ad-hoc/test plugins, while
- * return types from definePlugin provide stronger DX for shipped/typed plugins.
- */
-type PluginWithInstanceHelpers<TOptions extends GetDotenvOptions = GetDotenvOptions, TConfig = unknown> = GetDotenvCliPlugin<TOptions> & {
-    readConfig<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions>): Readonly<TCfg>;
-    createPluginDynamicOption<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions>, flags: string, desc: (cfg: ResolvedHelpConfig & {
-        plugins: Record<string, unknown>;
-    }, pluginCfg: Readonly<TCfg>) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option;
-};
-
-declare const demoPlugin: () => PluginWithInstanceHelpers<GetDotenvOptions, {}>;
-
-export { demoPlugin };