scenv 0.4.2 → 0.5.1

package/README.md

@@ -28,9 +28,9 @@ const apiUrl = scenv("API URL", {
   default: "http://localhost:4000",
 });
 
-const url = await apiUrl.get();         // throws if missing or invalid
-const result = await apiUrl.safeGet();  // { success, value? } | { success: false, error? }
-await apiUrl.save();                    // write current value to a context file
+const url = await apiUrl.get(); // throws if missing or invalid
+const result = await apiUrl.safeGet(); // { success, value? } | { success: false, error? }
+await apiUrl.save(); // write current value to a context file
 ```
 
 ## Resolution order
@@ -40,25 +40,27 @@ await apiUrl.save();                    // write current value to a context file
 3. **Context** – merged JSON context files
 4. **Default** – variable’s `default` option
 
+Any string value matching **`@<context>:<key>`** (e.g. `@prod:core_server_url`) is resolved from that context file first—in set, env, context, default, and prompts.
+
 Prompting (when to ask the user) is controlled by config `prompt`: `always` | `never` | `fallback` | `no-env`.
 
 ## Optional integrations
 
-| Package | Purpose |
-|--------|--------|
-| [scenv-zod](https://www.npmjs.com/package/scenv-zod) | `validator(zodSchema)` for type-safe validation and coercion. |
-| [scenv-inquirer](https://www.npmjs.com/package/scenv-inquirer) | `prompt()` and callbacks for interactive prompts. |
+| Package                                                        | Purpose                                                       |
+| -------------------------------------------------------------- | ------------------------------------------------------------- |
+| [scenv-zod](https://www.npmjs.com/package/scenv-zod)           | `validator(zodSchema)` for type-safe validation and coercion. |
+| [scenv-inquirer](https://www.npmjs.com/package/scenv-inquirer) | `prompt()` and callbacks for interactive prompts.             |
 
 ## Documentation
 
-Full docs (config, contexts, resolution, saving, API) live in the [monorepo](https://github.com/PKWadsy/senv):
+Full docs (config, contexts, resolution, saving, API) live in the [monorepo](https://github.com/PKWadsy/scenv):
 
-- [Configuration](https://github.com/PKWadsy/senv/blob/main/docs/CONFIGURATION.md)
-- [Contexts](https://github.com/PKWadsy/senv/blob/main/docs/CONTEXTS.md)
-- [Resolution](https://github.com/PKWadsy/senv/blob/main/docs/RESOLUTION.md)
-- [Saving](https://github.com/PKWadsy/senv/blob/main/docs/SAVING.md)
-- [API reference](https://github.com/PKWadsy/senv/blob/main/docs/API.md)
-- [Integration (scenv-zod, scenv-inquirer)](https://github.com/PKWadsy/senv/blob/main/docs/INTEGRATION.md)
+- [Configuration](https://github.com/PKWadsy/scenv/blob/main/docs/CONFIGURATION.md)
+- [Contexts](https://github.com/PKWadsy/scenv/blob/main/docs/CONTEXTS.md)
+- [Resolution](https://github.com/PKWadsy/scenv/blob/main/docs/RESOLUTION.md)
+- [Saving](https://github.com/PKWadsy/scenv/blob/main/docs/SAVING.md)
+- [API reference](https://github.com/PKWadsy/scenv/blob/main/docs/API.md)
+- [Integration (scenv-zod, scenv-inquirer)](https://github.com/PKWadsy/scenv/blob/main/docs/INTEGRATION.md)
 
 ## License
 

package/dist/index.cjs

@@ -24,7 +24,8 @@ __export(index_exports, {
   configure: () => configure,
   discoverContextPaths: () => discoverContextPaths,
   getCallbacks: () => getCallbacks,
-  getContextValues: () => getContextValues,
+  getContext: () => getContext,
+  getMergedContextValues: () => getMergedContextValues,
   loadConfig: () => loadConfig,
   parseScenvArgs: () => parseScenvArgs,
   resetConfig: () => resetConfig,
@@ -36,6 +37,52 @@ module.exports = __toCommonJS(index_exports);
 // src/config.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
+
+// src/prompt-default.ts
+var import_node_readline = require("readline");
+function ask(message) {
+  const rl = (0, import_node_readline.createInterface)({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve, reject) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+    rl.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+  });
+}
+function defaultPrompt(name, defaultValue) {
+  const defaultStr = defaultValue !== void 0 && defaultValue !== null ? String(defaultValue) : "";
+  const message = defaultStr ? `Enter ${name} [${defaultStr}]: ` : `Enter ${name}: `;
+  const rl = (0, import_node_readline.createInterface)({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve, reject) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      const value = trimmed !== "" ? trimmed : defaultStr;
+      resolve(value);
+    });
+    rl.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+  });
+}
+async function defaultAskWhetherToSave(name, _value) {
+  const answer = await ask(`Save "${name}" for next time? (y/n): `);
+  const v = answer.toLowerCase();
+  return v === "y" || v === "yes" || v === "1" || v === "true";
+}
+async function defaultAskContext(name, contextNames) {
+  const hint = contextNames.length > 0 ? ` (${contextNames.join(", ")})` : "";
+  const answer = await ask(`Save "${name}" to which context?${hint}: `);
+  if (answer) return answer;
+  return contextNames[0] ?? "default";
+}
+
+// src/config.ts
 var LOG_LEVELS = ["none", "trace", "debug", "info", "warn", "error"];
 var CONFIG_FILENAME = "scenv.config.json";
 var envKeyMap = {
@@ -44,14 +91,18 @@ var envKeyMap = {
   SCENV_PROMPT: "prompt",
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
-  SCENV_SAVE_PROMPT: "savePrompt",
+  SCENV_SAVE_PROMPT: "shouldSavePrompt",
   SCENV_SAVE_CONTEXT_TO: "saveContextTo",
   SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
 var programmaticCallbacks = {};
 function getCallbacks() {
-  return { ...programmaticCallbacks };
+  return {
+    defaultPrompt: programmaticCallbacks.defaultPrompt ?? defaultPrompt,
+    onAskWhetherToSave: programmaticCallbacks.onAskWhetherToSave ?? defaultAskWhetherToSave,
+    onAskContext: programmaticCallbacks.onAskContext ?? defaultAskContext
+  };
 }
 function findConfigDir(startDir) {
   let dir = startDir;
@@ -73,11 +124,11 @@ function configFromEnv() {
       out[configKey] = val.split(",").map((s) => s.trim()).filter(Boolean);
     } else if (configKey === "ignoreEnv" || configKey === "ignoreContext") {
       out[configKey] = val === "1" || val === "true" || val.toLowerCase() === "yes";
-    } else if (configKey === "prompt" || configKey === "savePrompt") {
+    } else if (configKey === "prompt" || configKey === "shouldSavePrompt") {
       const v = val.toLowerCase();
       if (configKey === "prompt" && (v === "always" || v === "never" || v === "fallback" || v === "no-env"))
         out[configKey] = v;
-      if (configKey === "savePrompt" && (v === "always" || v === "never" || v === "ask"))
+      if (configKey === "shouldSavePrompt" && (v === "always" || v === "never" || v === "ask"))
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
@@ -110,8 +161,8 @@ function loadConfigFile(configDir) {
       out.ignoreContext = parsed.ignoreContext;
     if (parsed.set && typeof parsed.set === "object" && !Array.isArray(parsed.set))
       out.set = parsed.set;
-    if (typeof parsed.savePrompt === "string" && ["always", "never", "ask"].includes(parsed.savePrompt))
-      out.savePrompt = parsed.savePrompt;
+    if (typeof (parsed.shouldSavePrompt ?? parsed.savePrompt) === "string" && ["always", "never", "ask"].includes(parsed.shouldSavePrompt ?? parsed.savePrompt))
+      out.shouldSavePrompt = parsed.shouldSavePrompt ?? parsed.savePrompt;
     if (typeof parsed.saveContextTo === "string")
       out.saveContextTo = parsed.saveContextTo;
     if (typeof parsed.root === "string") out.root = parsed.root;
@@ -255,7 +306,32 @@ function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
   );
   return found;
 }
-function getContextValues() {
+function getContext(contextName, root) {
+  const config = loadConfig();
+  const searchRoot = root ?? config.root ?? process.cwd();
+  const paths = discoverContextPaths(searchRoot);
+  const filePath = paths.get(contextName);
+  if (!filePath) {
+    log("trace", `getContext: context "${contextName}" not found`);
+    return {};
+  }
+  try {
+    const raw = (0, import_node_fs2.readFileSync)(filePath, "utf-8");
+    const data = JSON.parse(raw);
+    const out = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (typeof v === "string") out[k] = v;
+    }
+    return out;
+  } catch (err) {
+    log(
+      "trace",
+      `getContext: "${contextName}" unreadable: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return {};
+  }
+}
+function getMergedContextValues() {
   const config = loadConfig();
   logConfigLoaded(config);
   if (config.ignoreContext) return {};
@@ -312,6 +388,27 @@ function writeToContext(contextName, key, value) {
 }
 
 // src/variable.ts
+var CONTEXT_REF_REGEX = /^@([^:]+):(.+)$/;
+var MAX_CONTEXT_REF_DEPTH = 10;
+function resolveContextReference(raw, depth = 0) {
+  if (depth >= MAX_CONTEXT_REF_DEPTH) {
+    throw new Error(
+      `Context reference resolution exceeded max depth (${MAX_CONTEXT_REF_DEPTH}): possible circular reference`
+    );
+  }
+  const match = raw.match(CONTEXT_REF_REGEX);
+  if (!match) return raw;
+  const [, contextName, refKey] = match;
+  const ctx = getContext(contextName);
+  const resolved = ctx[refKey];
+  if (resolved === void 0) {
+    const hasContext = Object.keys(ctx).length > 0;
+    const msg = hasContext ? `Context reference @${contextName}:${refKey} could not be resolved: key "${refKey}" is not defined in context "${contextName}".` : `Context reference @${contextName}:${refKey} could not be resolved: context "${contextName}" not found (no ${contextName}.context.json).`;
+    log("error", msg);
+    throw new Error(msg);
+  }
+  return resolveContextReference(resolved, depth + 1);
+}
 function defaultKeyFromName(name) {
   return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
 }
@@ -336,22 +433,25 @@ function scenv(name, options = {}) {
     log("trace", `resolveRaw: checking set for key=${key}`);
     if (config.set?.[key] !== void 0) {
       log("trace", `resolveRaw: set hit key=${key}`);
-      return { raw: config.set[key], source: "set" };
+      const raw = resolveContextReference(config.set[key]);
+      return { raw, source: "set" };
     }
     if (!config.ignoreEnv) {
       log("trace", `resolveRaw: checking env ${envKey}`);
       const envVal = process.env[envKey];
       if (envVal !== void 0 && envVal !== "") {
         log("trace", "resolveRaw: env hit");
-        return { raw: envVal, source: "env" };
+        const raw = resolveContextReference(envVal);
+        return { raw, source: "env" };
       }
     }
     if (!config.ignoreContext) {
       log("trace", "resolveRaw: checking context");
-      const ctx = getContextValues();
+      const ctx = getMergedContextValues();
       if (ctx[key] !== void 0) {
         log("trace", `resolveRaw: context hit key=${key}`);
-        return { raw: ctx[key], source: "context" };
+        const raw = resolveContextReference(ctx[key]);
+        return { raw, source: "context" };
       }
     }
     log("trace", "resolveRaw: no value");
@@ -377,6 +477,7 @@ function scenv(name, options = {}) {
       `prompt decision key=${key} prompt=${config.prompt ?? "fallback"} hadValue=${hadValue} hadEnv=${hadEnv} -> ${doPrompt ? "prompt" : "no prompt"}`
     );
     const effectiveDefault = overrides?.default !== void 0 ? overrides.default : defaultValue;
+    const resolvedDefault = effectiveDefault === void 0 ? void 0 : typeof effectiveDefault === "string" ? resolveContextReference(effectiveDefault) : effectiveDefault;
     let wasPrompted = false;
     let value;
     let resolvedFrom;
@@ -388,15 +489,16 @@ function scenv(name, options = {}) {
           `Prompt required for variable "${name}" (key: ${key}) but no prompt was supplied and no defaultPrompt callback is configured. Set a prompt on the variable or configure({ callbacks: { defaultPrompt: ... } }).`
         );
       }
-      const defaultForPrompt = raw !== void 0 ? raw : effectiveDefault;
-      value = await Promise.resolve(fn(name, defaultForPrompt));
+      const defaultForPrompt = raw !== void 0 ? raw : resolvedDefault;
+      let promptedValue = await Promise.resolve(fn(name, defaultForPrompt));
+      value = typeof promptedValue === "string" ? resolveContextReference(promptedValue) : promptedValue;
       wasPrompted = true;
       resolvedFrom = "prompt";
     } else if (raw !== void 0) {
       value = raw;
       resolvedFrom = source;
-    } else if (effectiveDefault !== void 0) {
-      value = effectiveDefault;
+    } else if (resolvedDefault !== void 0) {
+      value = resolvedDefault;
       resolvedFrom = "default";
     } else {
       throw new Error(`Missing value for variable "${name}" (key: ${key})`);
@@ -428,25 +530,36 @@ function scenv(name, options = {}) {
     const final = validated.data;
     if (wasPrompted) {
       const config = loadConfig();
-      const savePrompt = config.savePrompt ?? (config.prompt === "never" ? "never" : "ask");
-      const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
-      if (shouldAskSave) {
-        const callbacks = getCallbacks();
-        if (typeof callbacks.onAskSaveAfterPrompt !== "function") {
+      const mode = config.shouldSavePrompt ?? (config.prompt === "never" ? "never" : "ask");
+      if (mode === "never") return final;
+      let doSave;
+      if (mode === "ask") {
+        const callbacks2 = getCallbacks();
+        if (typeof callbacks2.onAskWhetherToSave !== "function") {
           throw new Error(
-            `savePrompt is "${savePrompt}" but onAskSaveAfterPrompt callback is not set. Configure callbacks via configure({ callbacks: { onAskSaveAfterPrompt: ... } }).`
+            `shouldSavePrompt is "ask" but onAskWhetherToSave callback is not set. Configure callbacks via configure({ callbacks: { onAskWhetherToSave: ... } }).`
           );
         }
-        const ctxToSave = await callbacks.onAskSaveAfterPrompt(
-          name,
-          final,
-          config.contexts ?? []
-        );
-        if (ctxToSave) {
-          writeToContext(ctxToSave, key, String(final));
-          log("info", `Saved key=${key} to context ${ctxToSave}`);
+        doSave = await callbacks2.onAskWhetherToSave(name, final);
+      } else {
+        doSave = true;
+      }
+      if (!doSave) return final;
+      const callbacks = getCallbacks();
+      const contextNames = config.contexts ?? [];
+      let ctxToSave;
+      if (config.saveContextTo === "ask") {
+        if (typeof callbacks.onAskContext !== "function") {
+          throw new Error(
+            `saveContextTo is "ask" but onAskContext callback is not set. Configure callbacks via configure({ callbacks: { onAskContext: ... } }).`
+          );
         }
+        ctxToSave = await callbacks.onAskContext(name, contextNames);
+      } else {
+        ctxToSave = config.saveContextTo ?? contextNames[0] ?? "default";
       }
+      writeToContext(ctxToSave, key, String(final));
+      log("info", `Saved key=${key} to context ${ctxToSave}`);
     }
     return final;
   }
@@ -516,7 +629,7 @@ function parseScenvArgs(argv) {
     } else if (arg === "--save-prompt" && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (["always", "never", "ask"].includes(v)) {
-        config.savePrompt = v;
+        config.shouldSavePrompt = v;
       }
     } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
       config.saveContextTo = argv[++i];
@@ -548,7 +661,8 @@ function parseScenvArgs(argv) {
   configure,
   discoverContextPaths,
   getCallbacks,
-  getContextValues,
+  getContext,
+  getMergedContextValues,
   loadConfig,
   parseScenvArgs,
   resetConfig,

package/dist/index.d.cts

@@ -1,67 +1,148 @@
+/**
+ * When to prompt the user for a variable value during resolution.
+ * - `"always"` – Always call the variable's prompt (or defaultPrompt) when resolving.
+ * - `"never"` – Never prompt; use set/env/context/default only.
+ * - `"fallback"` – Prompt only when no value was found from set, env, or context.
+ * - `"no-env"` – Prompt when the env var is not set (even if context has a value).
+ */
 type PromptMode = "always" | "never" | "fallback" | "no-env";
+/**
+ * What to do with the value after the user was just prompted for it.
+ * - `"never"` – Do not save; discard for next time.
+ * - `"always"` – Save it (no prompt). Use saveContextTo or onAskContext only to pick where.
+ * - `"ask"` – Call {@link ScenvCallbacks.onAskWhetherToSave}; if true save, if false don't save.
+ */
 type SavePromptMode = "always" | "never" | "ask";
+/**
+ * Valid log levels. Use with {@link ScenvConfig.logLevel}.
+ * Messages at or above the configured level are written to stderr.
+ */
 declare const LOG_LEVELS: readonly ["none", "trace", "debug", "info", "warn", "error"];
+/** Log level type. `"none"` disables logging; higher values are more verbose. */
 type LogLevel = (typeof LOG_LEVELS)[number];
+/**
+ * Full scenv configuration. Built from file (scenv.config.json), environment (SCENV_*),
+ * and programmatic config (configure()), with programmatic > env > file precedence.
+ * All properties are optional; defaults apply when omitted.
+ */
 interface ScenvConfig {
-    /** Replace all contexts with this list (CLI: --context a,b,c) */
+    /** Replace the context list entirely (CLI: `--context a,b,c`). Loaded in order; later overwrites earlier for same key. */
     contexts?: string[];
-    /** Merge these contexts with existing (CLI: --add-context a,b,c) */
+    /** Merge these context names with existing (CLI: `--add-context a,b,c`). Ignored if `contexts` is set in the same layer. */
     addContexts?: string[];
-    /** When to prompt for variable value */
+    /** When to prompt for a variable value. See {@link PromptMode}. Default is `"fallback"`. */
     prompt?: PromptMode;
-    /** Ignore environment variables during resolution */
+    /** If true, environment variables are not used during resolution. */
     ignoreEnv?: boolean;
-    /** Ignore loaded context during resolution */
+    /** If true, context files are not loaded during resolution. */
     ignoreContext?: boolean;
-    /** Override values: key -> string (CLI: --set key=val) */
+    /** Override values by key (CLI: `--set key=value`). Takes precedence over env and context. */
     set?: Record<string, string>;
-    /** When to ask "save for next time?" */
-    savePrompt?: SavePromptMode;
-    /** Where to save: context name or "ask" */
+    /** After a prompt: "never" = don't save, "always" = save without asking, "ask" = call onAskWhetherToSave (then save if true). */
+    shouldSavePrompt?: SavePromptMode;
+    /** Target context for saving: a context name, or `"ask"` to use {@link ScenvCallbacks.onAskContext}. */
     saveContextTo?: "ask" | string;
-    /** Root directory for config/context search (default: cwd) */
+    /** Root directory for config file search and context discovery. Default is cwd or the directory containing scenv.config.json. */
     root?: string;
-    /** Log level: none (default), trace, debug, info, warn, error */
+    /** Logging level. Default is `"none"`. Messages go to stderr. */
     logLevel?: LogLevel;
 }
-/** (name, defaultValue) => value; used when a variable has no prompt option. Overridable per variable. */
+/**
+ * Default prompt function signature. Called when a variable has no `prompt` option and
+ * config requests prompting. Receives the variable's display name and default value;
+ * returns the value to use (sync or async). Overridable per variable via the variable's
+ * `prompt` option or per call via get({ prompt: fn }).
+ */
 type DefaultPromptFn = (name: string, defaultValue: unknown) => unknown | Promise<unknown>;
+/**
+ * Callbacks for interactive behaviour. All have built-in readline defaults when not set.
+ * Pass to {@link configure} via `configure({ callbacks: { ... } })`.
+ */
 interface ScenvCallbacks {
-    /** Default prompt when a variable does not provide its own `prompt`. Variable's `prompt` overrides this. */
+    /** Used when a variable does not define its own `prompt`. Variable-level `prompt` overrides this. */
     defaultPrompt?: DefaultPromptFn;
-    /** When user was just prompted for a value and savePrompt is ask/always: (variableName, value, contextNames) => context name to save to, or null to skip */
-    onAskSaveAfterPrompt?: (name: string, value: unknown, contextNames: string[]) => Promise<string | null>;
-    /** When saveContextTo is "ask": (variableName, contextNames) => context name to save to */
+    /** Called only when {@link ScenvConfig.shouldSavePrompt} is "ask" and the user was just prompted. Return true to save, false to skip. (With "always", we save without calling this.) */
+    onAskWhetherToSave?: (name: string, value: unknown) => Promise<boolean>;
+    /** Called when the save destination is ambiguous: saveContextTo is "ask", or after a prompt when the user said yes and saveContextTo is "ask". Return the context name to write to. */
     onAskContext?: (name: string, contextNames: string[]) => Promise<string>;
 }
+/**
+ * Returns the current callbacks (with built-in defaults merged in for any unset callback).
+ * Useful for inspection or to pass a subset to another layer. Each call returns a new object.
+ *
+ * @returns Copy of the effective callbacks: defaultPrompt, onAskWhetherToSave, onAskContext (always defined).
+ */
 declare function getCallbacks(): ScenvCallbacks;
 /**
- * Load full config: file (from root or cwd) <- env <- programmatic. Precedence: programmatic > env > file.
+ * Loads the full merged configuration. Searches for scenv.config.json upward from the given
+ * root (or cwd / programmatic root), then overlays SCENV_* env vars, then programmatic config.
+ * Use this to read the effective config (e.g. for logging or conditional logic).
+ *
+ * @param root - Optional directory to start searching for scenv.config.json. If omitted, uses programmatic config.root or process.cwd().
+ * @returns The merged {@link ScenvConfig} with at least `root` and `contexts` defined.
  */
 declare function loadConfig(root?: string): ScenvConfig;
 /**
- * Set programmatic config (e.g. from CLI flags). Merged on top of env and file in loadConfig().
+ * Merges config and/or callbacks into the programmatic layer. Programmatic config has
+ * highest precedence in {@link loadConfig}. Call multiple times to merge; later values
+ * overwrite earlier for the same key. Typical use: pass the result of {@link parseScenvArgs}
+ * or your own partial config.
+ *
+ * @param partial - Partial config and/or `callbacks`. Omitted keys are left unchanged. Nested objects (e.g. callbacks, set) are merged shallowly with existing.
  */
 declare function configure(partial: Partial<ScenvConfig> & {
     callbacks?: ScenvCallbacks;
 }): void;
 /**
- * Reset programmatic config (mainly for tests).
+ * Clears all programmatic config and callbacks. File and env config are unaffected.
+ * Mainly for tests. After calling, the next loadConfig() will not include any programmatic overrides.
  */
 declare function resetConfig(): void;
 
-/** Reset internal log state (e.g. config-loaded guard). Useful in tests after resetConfig(). */
+/**
+ * Resets internal log state (e.g. the "config loaded" one-time guard). Call after
+ * {@link resetConfig} in tests if you need to see config-loaded messages again or
+ * assert on log output.
+ */
 declare function resetLogState(): void;
 
 /**
- * Recursively find all *.context.json files under dir. Returns map: contextName -> absolute path (first found wins).
+ * Recursively discovers all `*.context.json` files under a directory. Context name is the
+ * filename without the suffix (e.g. `dev.context.json` → "dev"). First file found for a
+ * given name wins. Used internally for loading and saving; you can call it to inspect
+ * available contexts.
+ *
+ * @param dir - Root directory to search (e.g. config.root or process.cwd()).
+ * @param found - Optional existing map to merge results into. If omitted, a new Map is used.
+ * @returns Map from context name to absolute file path.
  */
 declare function discoverContextPaths(dir: string, found?: Map<string, string>): Map<string, string>;
 /**
- * Load context files in the order of config.contexts; merge into one flat map (later context overwrites earlier for same key).
+ * Loads key-value pairs from a single context file. Used when resolving @context:key references.
+ * Does not depend on config.contexts or ignoreContext; the context file is read if it exists
+ * under the config root.
+ *
+ * @param contextName - Name of the context (e.g. "prod", "dev") — file is contextName.context.json.
+ * @param root - Optional root directory to search. If omitted, uses loadConfig().root.
+ * @returns A flat record of key → string value from that context file. Empty if file not found or invalid.
+ */
+declare function getContext(contextName: string, root?: string): Record<string, string>;
+/**
+ * Loads and merges context values from the current config. Respects {@link ScenvConfig.contexts}
+ * order and {@link ScenvConfig.ignoreContext}. Each context file is a JSON object of string
+ * key-value pairs; later contexts overwrite earlier for the same key. Used during variable
+ * resolution (set > env > context > default).
+ *
+ * @returns A flat record of key → string value. Empty if ignoreContext is true or no contexts loaded.
  */
-declare function getContextValues(): Record<string, string>;
+declare function getMergedContextValues(): Record<string, string>;
 
+/**
+ * Return type for a variable's optional `validator` function. Use a boolean for simple
+ * pass/fail, or an object to pass a transformed value or a custom error.
+ * - `true` or `{ success: true, data?: T }` – validation passed; optional `data` replaces the value.
+ * - `false` or `{ success: false, error?: unknown }` – validation failed; `.get()` throws with the error.
+ */
 type ValidatorResult<T> = boolean | {
     success: true;
     data?: T;
@@ -69,23 +150,51 @@ type ValidatorResult<T> = boolean | {
     success: false;
     error?: unknown;
 };
+/**
+ * Prompt function signature. Called when config requests prompting for this variable.
+ * Receives the variable's display name and the current default (from set/env/context or option default).
+ * Return the value to use (sync or async). Used as the variable's `prompt` option or in get({ prompt: fn }).
+ */
 type PromptFn<T> = (name: string, defaultValue: T) => T | Promise<T>;
+/**
+ * Options when creating a variable with {@link scenv}. All properties are optional.
+ * If you omit `key` and `env`, they are derived from `name`: e.g. "API URL" → key `api_url`, env `API_URL`.
+ */
 interface ScenvVariableOptions<T> {
+    /** Internal key for --set, context files, and env. Default: name lowercased, spaces → underscores, non-alphanumeric stripped (e.g. "API URL" → "api_url"). */
     key?: string;
+    /** Environment variable name (e.g. API_URL). Default: key uppercased, hyphens → underscores. */
     env?: string;
+    /** Fallback when nothing is provided via --set, env, or context (and we're not prompting). */
     default?: T;
+    /** Optional. Run after value is resolved or prompted. Return true / { success: true } to accept, false / { success: false, error } to reject (get() throws). Use to coerce types or enforce rules. */
     validator?: (val: T) => ValidatorResult<T>;
+    /** Optional. Called when config says to prompt (e.g. prompt: "fallback" and no value found). Overrides callbacks.defaultPrompt for this variable. */
     prompt?: PromptFn<T>;
 }
-/** Overrides for a single .get() or .safeGet() call. */
+/**
+ * Overrides for a single get() or safeGet() call. Only that call is affected.
+ */
 interface GetOptions<T> {
-    /** Use this prompt for this call instead of the variable's prompt or callbacks.defaultPrompt. */
+    /** Use this prompt for this call only (e.g. a one-off inquirer prompt). */
     prompt?: PromptFn<T>;
-    /** Use this as the default for this call if no value from set/env/context. */
+    /** Use this as the default for this call when no value from set/env/context. */
     default?: T;
 }
+/**
+ * A scenv variable: a named setting (e.g. "API URL") whose value is resolved from CLI overrides (--set),
+ * then environment variables, then context files, then default (or an optional prompt). You call get() or
+ * safeGet() to read the value; optionally save() to persist it to a context file for next time.
+ */
 interface ScenvVariable<T> {
+    /**
+     * Resolve and return the value. Uses resolution order (set > env > context > default) and any prompt/validator.
+     * @throws If no value is found and no default/prompt, or if validation fails.
+     */
     get(options?: GetOptions<T>): Promise<T>;
+    /**
+     * Like get(), but never throws. Returns { success: true, value } or { success: false, error }.
+     */
     safeGet(options?: GetOptions<T>): Promise<{
         success: true;
         value: T;
@@ -93,15 +202,71 @@ interface ScenvVariable<T> {
         success: false;
         error?: unknown;
     }>;
+    /**
+     * Write the value to a context file (e.g. for next run). Target context comes from config.saveContextTo or onAskContext.
+     * If you don't pass a value, the last resolved value is used. Does not prompt "save?"; it saves.
+     */
     save(value?: T): Promise<void>;
 }
+/**
+ * Creates a scenv variable: a named config value (e.g. API URL, port) that you read with get() or safeGet()
+ * and optionally write with save(). You pass a display name and optional options; key and env are derived from
+ * the name if you omit them.
+ *
+ * ## Resolution (how get() gets a value)
+ *
+ * get() first looks for a raw value in this order, stopping at the first found:
+ * - Set overrides from config (e.g. from --set key=value or configure({ set: { key: "value" } }))
+ * - Environment variable (e.g. API_URL for key "api_url")
+ * - Context files (merged key-value from the contexts in config, e.g. dev.context.json)
+ *
+ * If config says to prompt (see prompt mode in config: "always", "fallback", "no-env"), the prompt callback
+ * may run. When it runs, it receives the variable name and a suggested value (the raw value if any, otherwise
+ * the default option). The callback's return value is used as the value. When we don't prompt, we use the
+ * raw value if present, otherwise the default option, otherwise get() throws (no value).
+ *
+ * ## Validator
+ *
+ * If you pass a validator option, it is called with the resolved or prompted value. It can return true or
+ * { success: true } to accept, or false or { success: false, error } to reject; on reject, get() throws.
+ * Use it to coerce types (e.g. string to number) or enforce rules.
+ *
+ * ## save()
+ *
+ * The variable has a save(value?) method. It writes the value (or the last resolved value if you omit it)
+ * to a context file. The target context comes from config.saveContextTo or from the onAskContext callback
+ * when saveContextTo is "ask". save() does not ask "save?"; it saves. Optional "save after prompt" behavior
+ * is controlled by config.shouldSavePrompt and callbacks.onAskWhetherToSave.
+ *
+ * @typeParam T - Value type (default string). Use a validator to coerce to number, boolean, etc.
+ * @param name - Display name used in prompts and errors. If you omit key/env, key is derived from name (e.g. "API URL" → "api_url") and env from key (e.g. "API_URL").
+ * @param options - Optional. key, env, default, validator, prompt. See {@link ScenvVariableOptions}.
+ * @returns A {@link ScenvVariable} with get(), safeGet(), and save().
+ *
+ * @example
+ * const apiUrl = scenv("API URL", { default: "http://localhost:4000" });
+ * const url = await apiUrl.get();
+ */
 declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): ScenvVariable<T>;
 
 /**
- * Parse argv (e.g. process.argv.slice(2)) into ScenvConfig for configure().
- * Supports: --context a,b,c --add-context x,y --prompt fallback --ignore-env --ignore-context
- * --set key=value --save-prompt ask --save-context-to prod --log-level trace
+ * Parses command-line arguments into a partial {@link ScenvConfig} suitable for {@link configure}.
+ * Typical use: `configure(parseScenvArgs(process.argv.slice(2)))`. Unrecognized flags are ignored.
+ *
+ * Supported flags:
+ * - `--context a,b,c` – Set contexts (replace).
+ * - `--add-context x,y` – Add contexts.
+ * - `--prompt always|never|fallback|no-env` – Prompt mode.
+ * - `--ignore-env` – Set ignoreEnv to true.
+ * - `--ignore-context` – Set ignoreContext to true.
+ * - `--set key=value` or `--set=key=value` – Add to set overrides (multiple allowed).
+ * - `--save-prompt always|never|ask` – shouldSavePrompt.
+ * - `--save-context-to name` – saveContextTo.
+ * - `--log-level level`, `--log level`, `--log=level` – logLevel.
+ *
+ * @param argv - Array of CLI arguments (e.g. process.argv.slice(2)).
+ * @returns Partial ScenvConfig with only the keys that were present in argv.
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type GetOptions, LOG_LEVELS, type LogLevel, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, resetLogState, scenv };
+export { type DefaultPromptFn, type GetOptions, LOG_LEVELS, type LogLevel, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContext, getMergedContextValues, loadConfig, parseScenvArgs, resetConfig, resetLogState, scenv };

package/dist/index.d.ts

@@ -1,67 +1,148 @@
+/**
+ * When to prompt the user for a variable value during resolution.
+ * - `"always"` – Always call the variable's prompt (or defaultPrompt) when resolving.
+ * - `"never"` – Never prompt; use set/env/context/default only.
+ * - `"fallback"` – Prompt only when no value was found from set, env, or context.
+ * - `"no-env"` – Prompt when the env var is not set (even if context has a value).
+ */
 type PromptMode = "always" | "never" | "fallback" | "no-env";
+/**
+ * What to do with the value after the user was just prompted for it.
+ * - `"never"` – Do not save; discard for next time.
+ * - `"always"` – Save it (no prompt). Use saveContextTo or onAskContext only to pick where.
+ * - `"ask"` – Call {@link ScenvCallbacks.onAskWhetherToSave}; if true save, if false don't save.
+ */
 type SavePromptMode = "always" | "never" | "ask";
+/**
+ * Valid log levels. Use with {@link ScenvConfig.logLevel}.
+ * Messages at or above the configured level are written to stderr.
+ */
 declare const LOG_LEVELS: readonly ["none", "trace", "debug", "info", "warn", "error"];
+/** Log level type. `"none"` disables logging; higher values are more verbose. */
 type LogLevel = (typeof LOG_LEVELS)[number];
+/**
+ * Full scenv configuration. Built from file (scenv.config.json), environment (SCENV_*),
+ * and programmatic config (configure()), with programmatic > env > file precedence.
+ * All properties are optional; defaults apply when omitted.
+ */
 interface ScenvConfig {
-    /** Replace all contexts with this list (CLI: --context a,b,c) */
+    /** Replace the context list entirely (CLI: `--context a,b,c`). Loaded in order; later overwrites earlier for same key. */
     contexts?: string[];
-    /** Merge these contexts with existing (CLI: --add-context a,b,c) */
+    /** Merge these context names with existing (CLI: `--add-context a,b,c`). Ignored if `contexts` is set in the same layer. */
     addContexts?: string[];
-    /** When to prompt for variable value */
+    /** When to prompt for a variable value. See {@link PromptMode}. Default is `"fallback"`. */
     prompt?: PromptMode;
-    /** Ignore environment variables during resolution */
+    /** If true, environment variables are not used during resolution. */
     ignoreEnv?: boolean;
-    /** Ignore loaded context during resolution */
+    /** If true, context files are not loaded during resolution. */
     ignoreContext?: boolean;
-    /** Override values: key -> string (CLI: --set key=val) */
+    /** Override values by key (CLI: `--set key=value`). Takes precedence over env and context. */
     set?: Record<string, string>;
-    /** When to ask "save for next time?" */
-    savePrompt?: SavePromptMode;
-    /** Where to save: context name or "ask" */
+    /** After a prompt: "never" = don't save, "always" = save without asking, "ask" = call onAskWhetherToSave (then save if true). */
+    shouldSavePrompt?: SavePromptMode;
+    /** Target context for saving: a context name, or `"ask"` to use {@link ScenvCallbacks.onAskContext}. */
     saveContextTo?: "ask" | string;
-    /** Root directory for config/context search (default: cwd) */
+    /** Root directory for config file search and context discovery. Default is cwd or the directory containing scenv.config.json. */
     root?: string;
-    /** Log level: none (default), trace, debug, info, warn, error */
+    /** Logging level. Default is `"none"`. Messages go to stderr. */
     logLevel?: LogLevel;
 }
-/** (name, defaultValue) => value; used when a variable has no prompt option. Overridable per variable. */
+/**
+ * Default prompt function signature. Called when a variable has no `prompt` option and
+ * config requests prompting. Receives the variable's display name and default value;
+ * returns the value to use (sync or async). Overridable per variable via the variable's
+ * `prompt` option or per call via get({ prompt: fn }).
+ */
 type DefaultPromptFn = (name: string, defaultValue: unknown) => unknown | Promise<unknown>;
+/**
+ * Callbacks for interactive behaviour. All have built-in readline defaults when not set.
+ * Pass to {@link configure} via `configure({ callbacks: { ... } })`.
+ */
 interface ScenvCallbacks {
-    /** Default prompt when a variable does not provide its own `prompt`. Variable's `prompt` overrides this. */
+    /** Used when a variable does not define its own `prompt`. Variable-level `prompt` overrides this. */
     defaultPrompt?: DefaultPromptFn;
-    /** When user was just prompted for a value and savePrompt is ask/always: (variableName, value, contextNames) => context name to save to, or null to skip */
-    onAskSaveAfterPrompt?: (name: string, value: unknown, contextNames: string[]) => Promise<string | null>;
-    /** When saveContextTo is "ask": (variableName, contextNames) => context name to save to */
+    /** Called only when {@link ScenvConfig.shouldSavePrompt} is "ask" and the user was just prompted. Return true to save, false to skip. (With "always", we save without calling this.) */
+    onAskWhetherToSave?: (name: string, value: unknown) => Promise<boolean>;
+    /** Called when the save destination is ambiguous: saveContextTo is "ask", or after a prompt when the user said yes and saveContextTo is "ask". Return the context name to write to. */
     onAskContext?: (name: string, contextNames: string[]) => Promise<string>;
 }
+/**
+ * Returns the current callbacks (with built-in defaults merged in for any unset callback).
+ * Useful for inspection or to pass a subset to another layer. Each call returns a new object.
+ *
+ * @returns Copy of the effective callbacks: defaultPrompt, onAskWhetherToSave, onAskContext (always defined).
+ */
 declare function getCallbacks(): ScenvCallbacks;
 /**
- * Load full config: file (from root or cwd) <- env <- programmatic. Precedence: programmatic > env > file.
+ * Loads the full merged configuration. Searches for scenv.config.json upward from the given
+ * root (or cwd / programmatic root), then overlays SCENV_* env vars, then programmatic config.
+ * Use this to read the effective config (e.g. for logging or conditional logic).
+ *
+ * @param root - Optional directory to start searching for scenv.config.json. If omitted, uses programmatic config.root or process.cwd().
+ * @returns The merged {@link ScenvConfig} with at least `root` and `contexts` defined.
  */
 declare function loadConfig(root?: string): ScenvConfig;
 /**
- * Set programmatic config (e.g. from CLI flags). Merged on top of env and file in loadConfig().
+ * Merges config and/or callbacks into the programmatic layer. Programmatic config has
+ * highest precedence in {@link loadConfig}. Call multiple times to merge; later values
+ * overwrite earlier for the same key. Typical use: pass the result of {@link parseScenvArgs}
+ * or your own partial config.
+ *
+ * @param partial - Partial config and/or `callbacks`. Omitted keys are left unchanged. Nested objects (e.g. callbacks, set) are merged shallowly with existing.
  */
 declare function configure(partial: Partial<ScenvConfig> & {
     callbacks?: ScenvCallbacks;
 }): void;
 /**
- * Reset programmatic config (mainly for tests).
+ * Clears all programmatic config and callbacks. File and env config are unaffected.
+ * Mainly for tests. After calling, the next loadConfig() will not include any programmatic overrides.
  */
 declare function resetConfig(): void;
 
-/** Reset internal log state (e.g. config-loaded guard). Useful in tests after resetConfig(). */
+/**
+ * Resets internal log state (e.g. the "config loaded" one-time guard). Call after
+ * {@link resetConfig} in tests if you need to see config-loaded messages again or
+ * assert on log output.
+ */
 declare function resetLogState(): void;
 
 /**
- * Recursively find all *.context.json files under dir. Returns map: contextName -> absolute path (first found wins).
+ * Recursively discovers all `*.context.json` files under a directory. Context name is the
+ * filename without the suffix (e.g. `dev.context.json` → "dev"). First file found for a
+ * given name wins. Used internally for loading and saving; you can call it to inspect
+ * available contexts.
+ *
+ * @param dir - Root directory to search (e.g. config.root or process.cwd()).
+ * @param found - Optional existing map to merge results into. If omitted, a new Map is used.
+ * @returns Map from context name to absolute file path.
  */
 declare function discoverContextPaths(dir: string, found?: Map<string, string>): Map<string, string>;
 /**
- * Load context files in the order of config.contexts; merge into one flat map (later context overwrites earlier for same key).
+ * Loads key-value pairs from a single context file. Used when resolving @context:key references.
+ * Does not depend on config.contexts or ignoreContext; the context file is read if it exists
+ * under the config root.
+ *
+ * @param contextName - Name of the context (e.g. "prod", "dev") — file is contextName.context.json.
+ * @param root - Optional root directory to search. If omitted, uses loadConfig().root.
+ * @returns A flat record of key → string value from that context file. Empty if file not found or invalid.
+ */
+declare function getContext(contextName: string, root?: string): Record<string, string>;
+/**
+ * Loads and merges context values from the current config. Respects {@link ScenvConfig.contexts}
+ * order and {@link ScenvConfig.ignoreContext}. Each context file is a JSON object of string
+ * key-value pairs; later contexts overwrite earlier for the same key. Used during variable
+ * resolution (set > env > context > default).
+ *
+ * @returns A flat record of key → string value. Empty if ignoreContext is true or no contexts loaded.
  */
-declare function getContextValues(): Record<string, string>;
+declare function getMergedContextValues(): Record<string, string>;
 
+/**
+ * Return type for a variable's optional `validator` function. Use a boolean for simple
+ * pass/fail, or an object to pass a transformed value or a custom error.
+ * - `true` or `{ success: true, data?: T }` – validation passed; optional `data` replaces the value.
+ * - `false` or `{ success: false, error?: unknown }` – validation failed; `.get()` throws with the error.
+ */
 type ValidatorResult<T> = boolean | {
     success: true;
     data?: T;
@@ -69,23 +150,51 @@ type ValidatorResult<T> = boolean | {
     success: false;
     error?: unknown;
 };
+/**
+ * Prompt function signature. Called when config requests prompting for this variable.
+ * Receives the variable's display name and the current default (from set/env/context or option default).
+ * Return the value to use (sync or async). Used as the variable's `prompt` option or in get({ prompt: fn }).
+ */
 type PromptFn<T> = (name: string, defaultValue: T) => T | Promise<T>;
+/**
+ * Options when creating a variable with {@link scenv}. All properties are optional.
+ * If you omit `key` and `env`, they are derived from `name`: e.g. "API URL" → key `api_url`, env `API_URL`.
+ */
 interface ScenvVariableOptions<T> {
+    /** Internal key for --set, context files, and env. Default: name lowercased, spaces → underscores, non-alphanumeric stripped (e.g. "API URL" → "api_url"). */
     key?: string;
+    /** Environment variable name (e.g. API_URL). Default: key uppercased, hyphens → underscores. */
     env?: string;
+    /** Fallback when nothing is provided via --set, env, or context (and we're not prompting). */
     default?: T;
+    /** Optional. Run after value is resolved or prompted. Return true / { success: true } to accept, false / { success: false, error } to reject (get() throws). Use to coerce types or enforce rules. */
     validator?: (val: T) => ValidatorResult<T>;
+    /** Optional. Called when config says to prompt (e.g. prompt: "fallback" and no value found). Overrides callbacks.defaultPrompt for this variable. */
     prompt?: PromptFn<T>;
 }
-/** Overrides for a single .get() or .safeGet() call. */
+/**
+ * Overrides for a single get() or safeGet() call. Only that call is affected.
+ */
 interface GetOptions<T> {
-    /** Use this prompt for this call instead of the variable's prompt or callbacks.defaultPrompt. */
+    /** Use this prompt for this call only (e.g. a one-off inquirer prompt). */
     prompt?: PromptFn<T>;
-    /** Use this as the default for this call if no value from set/env/context. */
+    /** Use this as the default for this call when no value from set/env/context. */
     default?: T;
 }
+/**
+ * A scenv variable: a named setting (e.g. "API URL") whose value is resolved from CLI overrides (--set),
+ * then environment variables, then context files, then default (or an optional prompt). You call get() or
+ * safeGet() to read the value; optionally save() to persist it to a context file for next time.
+ */
 interface ScenvVariable<T> {
+    /**
+     * Resolve and return the value. Uses resolution order (set > env > context > default) and any prompt/validator.
+     * @throws If no value is found and no default/prompt, or if validation fails.
+     */
     get(options?: GetOptions<T>): Promise<T>;
+    /**
+     * Like get(), but never throws. Returns { success: true, value } or { success: false, error }.
+     */
     safeGet(options?: GetOptions<T>): Promise<{
         success: true;
         value: T;
@@ -93,15 +202,71 @@ interface ScenvVariable<T> {
         success: false;
         error?: unknown;
     }>;
+    /**
+     * Write the value to a context file (e.g. for next run). Target context comes from config.saveContextTo or onAskContext.
+     * If you don't pass a value, the last resolved value is used. Does not prompt "save?"; it saves.
+     */
     save(value?: T): Promise<void>;
 }
+/**
+ * Creates a scenv variable: a named config value (e.g. API URL, port) that you read with get() or safeGet()
+ * and optionally write with save(). You pass a display name and optional options; key and env are derived from
+ * the name if you omit them.
+ *
+ * ## Resolution (how get() gets a value)
+ *
+ * get() first looks for a raw value in this order, stopping at the first found:
+ * - Set overrides from config (e.g. from --set key=value or configure({ set: { key: "value" } }))
+ * - Environment variable (e.g. API_URL for key "api_url")
+ * - Context files (merged key-value from the contexts in config, e.g. dev.context.json)
+ *
+ * If config says to prompt (see prompt mode in config: "always", "fallback", "no-env"), the prompt callback
+ * may run. When it runs, it receives the variable name and a suggested value (the raw value if any, otherwise
+ * the default option). The callback's return value is used as the value. When we don't prompt, we use the
+ * raw value if present, otherwise the default option, otherwise get() throws (no value).
+ *
+ * ## Validator
+ *
+ * If you pass a validator option, it is called with the resolved or prompted value. It can return true or
+ * { success: true } to accept, or false or { success: false, error } to reject; on reject, get() throws.
+ * Use it to coerce types (e.g. string to number) or enforce rules.
+ *
+ * ## save()
+ *
+ * The variable has a save(value?) method. It writes the value (or the last resolved value if you omit it)
+ * to a context file. The target context comes from config.saveContextTo or from the onAskContext callback
+ * when saveContextTo is "ask". save() does not ask "save?"; it saves. Optional "save after prompt" behavior
+ * is controlled by config.shouldSavePrompt and callbacks.onAskWhetherToSave.
+ *
+ * @typeParam T - Value type (default string). Use a validator to coerce to number, boolean, etc.
+ * @param name - Display name used in prompts and errors. If you omit key/env, key is derived from name (e.g. "API URL" → "api_url") and env from key (e.g. "API_URL").
+ * @param options - Optional. key, env, default, validator, prompt. See {@link ScenvVariableOptions}.
+ * @returns A {@link ScenvVariable} with get(), safeGet(), and save().
+ *
+ * @example
+ * const apiUrl = scenv("API URL", { default: "http://localhost:4000" });
+ * const url = await apiUrl.get();
+ */
 declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): ScenvVariable<T>;
 
 /**
- * Parse argv (e.g. process.argv.slice(2)) into ScenvConfig for configure().
- * Supports: --context a,b,c --add-context x,y --prompt fallback --ignore-env --ignore-context
- * --set key=value --save-prompt ask --save-context-to prod --log-level trace
+ * Parses command-line arguments into a partial {@link ScenvConfig} suitable for {@link configure}.
+ * Typical use: `configure(parseScenvArgs(process.argv.slice(2)))`. Unrecognized flags are ignored.
+ *
+ * Supported flags:
+ * - `--context a,b,c` – Set contexts (replace).
+ * - `--add-context x,y` – Add contexts.
+ * - `--prompt always|never|fallback|no-env` – Prompt mode.
+ * - `--ignore-env` – Set ignoreEnv to true.
+ * - `--ignore-context` – Set ignoreContext to true.
+ * - `--set key=value` or `--set=key=value` – Add to set overrides (multiple allowed).
+ * - `--save-prompt always|never|ask` – shouldSavePrompt.
+ * - `--save-context-to name` – saveContextTo.
+ * - `--log-level level`, `--log level`, `--log=level` – logLevel.
+ *
+ * @param argv - Array of CLI arguments (e.g. process.argv.slice(2)).
+ * @returns Partial ScenvConfig with only the keys that were present in argv.
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type GetOptions, LOG_LEVELS, type LogLevel, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, resetLogState, scenv };
+export { type DefaultPromptFn, type GetOptions, LOG_LEVELS, type LogLevel, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContext, getMergedContextValues, loadConfig, parseScenvArgs, resetConfig, resetLogState, scenv };

package/dist/index.js

@@ -1,6 +1,52 @@
 // src/config.ts
 import { readFileSync, existsSync } from "fs";
 import { dirname, join } from "path";
+
+// src/prompt-default.ts
+import { createInterface } from "readline";
+function ask(message) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve, reject) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+    rl.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+  });
+}
+function defaultPrompt(name, defaultValue) {
+  const defaultStr = defaultValue !== void 0 && defaultValue !== null ? String(defaultValue) : "";
+  const message = defaultStr ? `Enter ${name} [${defaultStr}]: ` : `Enter ${name}: `;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve, reject) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      const value = trimmed !== "" ? trimmed : defaultStr;
+      resolve(value);
+    });
+    rl.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+  });
+}
+async function defaultAskWhetherToSave(name, _value) {
+  const answer = await ask(`Save "${name}" for next time? (y/n): `);
+  const v = answer.toLowerCase();
+  return v === "y" || v === "yes" || v === "1" || v === "true";
+}
+async function defaultAskContext(name, contextNames) {
+  const hint = contextNames.length > 0 ? ` (${contextNames.join(", ")})` : "";
+  const answer = await ask(`Save "${name}" to which context?${hint}: `);
+  if (answer) return answer;
+  return contextNames[0] ?? "default";
+}
+
+// src/config.ts
 var LOG_LEVELS = ["none", "trace", "debug", "info", "warn", "error"];
 var CONFIG_FILENAME = "scenv.config.json";
 var envKeyMap = {
@@ -9,14 +55,18 @@ var envKeyMap = {
   SCENV_PROMPT: "prompt",
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
-  SCENV_SAVE_PROMPT: "savePrompt",
+  SCENV_SAVE_PROMPT: "shouldSavePrompt",
   SCENV_SAVE_CONTEXT_TO: "saveContextTo",
   SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
 var programmaticCallbacks = {};
 function getCallbacks() {
-  return { ...programmaticCallbacks };
+  return {
+    defaultPrompt: programmaticCallbacks.defaultPrompt ?? defaultPrompt,
+    onAskWhetherToSave: programmaticCallbacks.onAskWhetherToSave ?? defaultAskWhetherToSave,
+    onAskContext: programmaticCallbacks.onAskContext ?? defaultAskContext
+  };
 }
 function findConfigDir(startDir) {
   let dir = startDir;
@@ -38,11 +88,11 @@ function configFromEnv() {
       out[configKey] = val.split(",").map((s) => s.trim()).filter(Boolean);
     } else if (configKey === "ignoreEnv" || configKey === "ignoreContext") {
       out[configKey] = val === "1" || val === "true" || val.toLowerCase() === "yes";
-    } else if (configKey === "prompt" || configKey === "savePrompt") {
+    } else if (configKey === "prompt" || configKey === "shouldSavePrompt") {
       const v = val.toLowerCase();
       if (configKey === "prompt" && (v === "always" || v === "never" || v === "fallback" || v === "no-env"))
         out[configKey] = v;
-      if (configKey === "savePrompt" && (v === "always" || v === "never" || v === "ask"))
+      if (configKey === "shouldSavePrompt" && (v === "always" || v === "never" || v === "ask"))
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
@@ -75,8 +125,8 @@ function loadConfigFile(configDir) {
       out.ignoreContext = parsed.ignoreContext;
     if (parsed.set && typeof parsed.set === "object" && !Array.isArray(parsed.set))
       out.set = parsed.set;
-    if (typeof parsed.savePrompt === "string" && ["always", "never", "ask"].includes(parsed.savePrompt))
-      out.savePrompt = parsed.savePrompt;
+    if (typeof (parsed.shouldSavePrompt ?? parsed.savePrompt) === "string" && ["always", "never", "ask"].includes(parsed.shouldSavePrompt ?? parsed.savePrompt))
+      out.shouldSavePrompt = parsed.shouldSavePrompt ?? parsed.savePrompt;
     if (typeof parsed.saveContextTo === "string")
       out.saveContextTo = parsed.saveContextTo;
     if (typeof parsed.root === "string") out.root = parsed.root;
@@ -226,7 +276,32 @@ function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
   );
   return found;
 }
-function getContextValues() {
+function getContext(contextName, root) {
+  const config = loadConfig();
+  const searchRoot = root ?? config.root ?? process.cwd();
+  const paths = discoverContextPaths(searchRoot);
+  const filePath = paths.get(contextName);
+  if (!filePath) {
+    log("trace", `getContext: context "${contextName}" not found`);
+    return {};
+  }
+  try {
+    const raw = readFileSync2(filePath, "utf-8");
+    const data = JSON.parse(raw);
+    const out = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (typeof v === "string") out[k] = v;
+    }
+    return out;
+  } catch (err) {
+    log(
+      "trace",
+      `getContext: "${contextName}" unreadable: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return {};
+  }
+}
+function getMergedContextValues() {
   const config = loadConfig();
   logConfigLoaded(config);
   if (config.ignoreContext) return {};
@@ -283,6 +358,27 @@ function writeToContext(contextName, key, value) {
 }
 
 // src/variable.ts
+var CONTEXT_REF_REGEX = /^@([^:]+):(.+)$/;
+var MAX_CONTEXT_REF_DEPTH = 10;
+function resolveContextReference(raw, depth = 0) {
+  if (depth >= MAX_CONTEXT_REF_DEPTH) {
+    throw new Error(
+      `Context reference resolution exceeded max depth (${MAX_CONTEXT_REF_DEPTH}): possible circular reference`
+    );
+  }
+  const match = raw.match(CONTEXT_REF_REGEX);
+  if (!match) return raw;
+  const [, contextName, refKey] = match;
+  const ctx = getContext(contextName);
+  const resolved = ctx[refKey];
+  if (resolved === void 0) {
+    const hasContext = Object.keys(ctx).length > 0;
+    const msg = hasContext ? `Context reference @${contextName}:${refKey} could not be resolved: key "${refKey}" is not defined in context "${contextName}".` : `Context reference @${contextName}:${refKey} could not be resolved: context "${contextName}" not found (no ${contextName}.context.json).`;
+    log("error", msg);
+    throw new Error(msg);
+  }
+  return resolveContextReference(resolved, depth + 1);
+}
 function defaultKeyFromName(name) {
   return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
 }
@@ -307,22 +403,25 @@ function scenv(name, options = {}) {
     log("trace", `resolveRaw: checking set for key=${key}`);
     if (config.set?.[key] !== void 0) {
       log("trace", `resolveRaw: set hit key=${key}`);
-      return { raw: config.set[key], source: "set" };
+      const raw = resolveContextReference(config.set[key]);
+      return { raw, source: "set" };
     }
     if (!config.ignoreEnv) {
       log("trace", `resolveRaw: checking env ${envKey}`);
       const envVal = process.env[envKey];
       if (envVal !== void 0 && envVal !== "") {
         log("trace", "resolveRaw: env hit");
-        return { raw: envVal, source: "env" };
+        const raw = resolveContextReference(envVal);
+        return { raw, source: "env" };
       }
     }
     if (!config.ignoreContext) {
       log("trace", "resolveRaw: checking context");
-      const ctx = getContextValues();
+      const ctx = getMergedContextValues();
       if (ctx[key] !== void 0) {
         log("trace", `resolveRaw: context hit key=${key}`);
-        return { raw: ctx[key], source: "context" };
+        const raw = resolveContextReference(ctx[key]);
+        return { raw, source: "context" };
       }
     }
     log("trace", "resolveRaw: no value");
@@ -348,6 +447,7 @@ function scenv(name, options = {}) {
       `prompt decision key=${key} prompt=${config.prompt ?? "fallback"} hadValue=${hadValue} hadEnv=${hadEnv} -> ${doPrompt ? "prompt" : "no prompt"}`
     );
     const effectiveDefault = overrides?.default !== void 0 ? overrides.default : defaultValue;
+    const resolvedDefault = effectiveDefault === void 0 ? void 0 : typeof effectiveDefault === "string" ? resolveContextReference(effectiveDefault) : effectiveDefault;
     let wasPrompted = false;
     let value;
     let resolvedFrom;
@@ -359,15 +459,16 @@ function scenv(name, options = {}) {
           `Prompt required for variable "${name}" (key: ${key}) but no prompt was supplied and no defaultPrompt callback is configured. Set a prompt on the variable or configure({ callbacks: { defaultPrompt: ... } }).`
         );
       }
-      const defaultForPrompt = raw !== void 0 ? raw : effectiveDefault;
-      value = await Promise.resolve(fn(name, defaultForPrompt));
+      const defaultForPrompt = raw !== void 0 ? raw : resolvedDefault;
+      let promptedValue = await Promise.resolve(fn(name, defaultForPrompt));
+      value = typeof promptedValue === "string" ? resolveContextReference(promptedValue) : promptedValue;
       wasPrompted = true;
       resolvedFrom = "prompt";
     } else if (raw !== void 0) {
       value = raw;
       resolvedFrom = source;
-    } else if (effectiveDefault !== void 0) {
-      value = effectiveDefault;
+    } else if (resolvedDefault !== void 0) {
+      value = resolvedDefault;
       resolvedFrom = "default";
     } else {
       throw new Error(`Missing value for variable "${name}" (key: ${key})`);
@@ -399,25 +500,36 @@ function scenv(name, options = {}) {
     const final = validated.data;
     if (wasPrompted) {
       const config = loadConfig();
-      const savePrompt = config.savePrompt ?? (config.prompt === "never" ? "never" : "ask");
-      const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
-      if (shouldAskSave) {
-        const callbacks = getCallbacks();
-        if (typeof callbacks.onAskSaveAfterPrompt !== "function") {
+      const mode = config.shouldSavePrompt ?? (config.prompt === "never" ? "never" : "ask");
+      if (mode === "never") return final;
+      let doSave;
+      if (mode === "ask") {
+        const callbacks2 = getCallbacks();
+        if (typeof callbacks2.onAskWhetherToSave !== "function") {
           throw new Error(
-            `savePrompt is "${savePrompt}" but onAskSaveAfterPrompt callback is not set. Configure callbacks via configure({ callbacks: { onAskSaveAfterPrompt: ... } }).`
+            `shouldSavePrompt is "ask" but onAskWhetherToSave callback is not set. Configure callbacks via configure({ callbacks: { onAskWhetherToSave: ... } }).`
           );
         }
-        const ctxToSave = await callbacks.onAskSaveAfterPrompt(
-          name,
-          final,
-          config.contexts ?? []
-        );
-        if (ctxToSave) {
-          writeToContext(ctxToSave, key, String(final));
-          log("info", `Saved key=${key} to context ${ctxToSave}`);
+        doSave = await callbacks2.onAskWhetherToSave(name, final);
+      } else {
+        doSave = true;
+      }
+      if (!doSave) return final;
+      const callbacks = getCallbacks();
+      const contextNames = config.contexts ?? [];
+      let ctxToSave;
+      if (config.saveContextTo === "ask") {
+        if (typeof callbacks.onAskContext !== "function") {
+          throw new Error(
+            `saveContextTo is "ask" but onAskContext callback is not set. Configure callbacks via configure({ callbacks: { onAskContext: ... } }).`
+          );
         }
+        ctxToSave = await callbacks.onAskContext(name, contextNames);
+      } else {
+        ctxToSave = config.saveContextTo ?? contextNames[0] ?? "default";
       }
+      writeToContext(ctxToSave, key, String(final));
+      log("info", `Saved key=${key} to context ${ctxToSave}`);
     }
     return final;
   }
@@ -487,7 +599,7 @@ function parseScenvArgs(argv) {
     } else if (arg === "--save-prompt" && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (["always", "never", "ask"].includes(v)) {
-        config.savePrompt = v;
+        config.shouldSavePrompt = v;
       }
     } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
       config.saveContextTo = argv[++i];
@@ -518,7 +630,8 @@ export {
   configure,
   discoverContextPaths,
   getCallbacks,
-  getContextValues,
+  getContext,
+  getMergedContextValues,
   loadConfig,
   parseScenvArgs,
   resetConfig,

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "scenv",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Environment and context variables with runtime-configurable resolution",
-  "repository": { "type": "git", "url": "https://github.com/PKWadsy/scenv" },
-  "publishConfig": { "access": "public", "provenance": true },
-  "keywords": ["env", "config", "context", "variables"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PKWadsy/scenv"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "env",
+    "config",
+    "context",
+    "variables"
+  ],
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",