scenv 0.7.0 → 0.9.0

package/README.md

@@ -48,7 +48,7 @@ Prompting (when to ask the user) is controlled by config `prompt`: `always` | `n
 
 | Package                                                        | Purpose                                                       |
 | -------------------------------------------------------------- | ------------------------------------------------------------- |
-| [scenv-zod](https://www.npmjs.com/package/scenv-zod)           | `validator(zodSchema)` for type-safe validation and coercion. |
+| [scenv-zod](https://www.npmjs.com/package/scenv-zod)           | `parser(zodSchema)` for type-safe parsing and coercion. |
 | [scenv-inquirer](https://www.npmjs.com/package/scenv-inquirer) | `prompt()` and callbacks for interactive prompts.             |
 
 ## Documentation

package/dist/index.cjs

@@ -48,12 +48,12 @@ 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) => {
+  return new Promise((resolve2, reject) => {
     rl.question(message, (answer) => {
       rl.close();
       const trimmed = answer.trim();
       const value = trimmed !== "" ? trimmed : defaultStr;
-      resolve(value);
+      resolve2(value);
     });
     rl.on("error", (err) => {
       rl.close();
@@ -72,7 +72,7 @@ var envKeyMap = {
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
   SCENV_SAVE_CONTEXT_TO: "saveContextTo",
-  SCENV_CONTEXT_DIR: "contextDir",
+  SCENV_SAVE_MODE: "saveMode",
   SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
@@ -108,8 +108,10 @@ function configFromEnv() {
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
-    } else if (configKey === "contextDir") {
-      out.contextDir = val;
+    } else if (configKey === "saveMode") {
+      const v = val.toLowerCase();
+      if (v === "all" || v === "prompts-only")
+        out[configKey] = v;
     } else if (configKey === "logLevel") {
       const v = val.toLowerCase();
       if (LOG_LEVELS.includes(v)) out.logLevel = v;
@@ -149,8 +151,8 @@ function loadConfigFile(configDir) {
       out.set = parsed.set;
     if (typeof parsed.saveContextTo === "string")
       out.saveContextTo = parsed.saveContextTo;
-    if (typeof parsed.contextDir === "string") out.contextDir = parsed.contextDir;
-    else if (typeof parsed.contextsDir === "string") out.contextDir = parsed.contextsDir;
+    if (typeof parsed.saveMode === "string" && ["all", "prompts-only"].includes(parsed.saveMode))
+      out.saveMode = parsed.saveMode;
     if (typeof parsed.root === "string") out.root = parsed.root;
     if (typeof parsed.logLevel === "string" && LOG_LEVELS.includes(parsed.logLevel))
       out.logLevel = parsed.logLevel;
@@ -238,7 +240,7 @@ var CONFIG_LOG_KEYS = [
   "ignoreContext",
   "set",
   "saveContextTo",
-  "contextDir",
+  "saveMode",
   "logLevel"
 ];
 function configForLog(config) {
@@ -259,7 +261,7 @@ function logConfigLoaded(config) {
     if (config.ignoreEnv === true) parts.push("ignoreEnv=true");
     if (config.ignoreContext === true) parts.push("ignoreContext=true");
     if (config.saveContextTo !== void 0) parts.push("saveContextTo=" + config.saveContextTo);
-    if (config.contextDir !== void 0) parts.push("contextDir=" + config.contextDir);
+    if (config.saveMode !== void 0) parts.push("saveMode=" + config.saveMode);
     log("info", "config loaded", parts.join(" "));
   }
   if (levelNum >= LEVEL_NUM.debug) {
@@ -328,10 +330,23 @@ function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
   return found;
 }
 function getContext(contextName, root) {
-  const config = loadConfig();
-  const searchRoot = root ?? config.root ?? process.cwd();
-  const paths = discoverContextPaths(searchRoot);
-  const filePath = paths.get(contextName);
+  let filePath;
+  if (root !== void 0) {
+    const paths = discoverContextPaths(root);
+    filePath = paths.get(contextName);
+  } else {
+    const cwd = process.cwd();
+    const paths = discoverContextPaths(cwd);
+    filePath = paths.get(contextName);
+    if (!filePath) {
+      const config = loadConfig();
+      const projectRoot = config.root ?? cwd;
+      if (projectRoot !== cwd) {
+        const rootPaths = discoverContextPaths(projectRoot);
+        filePath = rootPaths.get(contextName);
+      }
+    }
+  }
   if (!filePath) {
     log("trace", `getContext: context "${contextName}" not found`);
     return {};
@@ -356,17 +371,9 @@ function getMergedContextValues() {
   const config = loadConfig();
   logConfigLoaded(config);
   if (config.ignoreContext) return {};
-  const root = config.root ?? process.cwd();
-  const paths = discoverContextPaths(root);
+  const searchRoot = process.cwd();
+  const paths = discoverContextPaths(searchRoot);
   const out = {};
-  if (config.saveContextTo) {
-    const savePath = resolveSaveContextPath(config.saveContextTo);
-    const saveCtx = getContextAtPath(savePath);
-    for (const [k, v] of Object.entries(saveCtx)) out[k] = v;
-    if (Object.keys(saveCtx).length > 0) {
-      log("debug", `saveContextTo "${config.saveContextTo}" loaded keys=${JSON.stringify(Object.keys(saveCtx))}`);
-    }
-  }
   for (const contextName of config.context ?? []) {
     const filePath = paths.get(contextName);
     if (!filePath) {
@@ -398,32 +405,11 @@ function getContextWritePath(contextName) {
     return contextName.endsWith(CONTEXT_SUFFIX) ? contextName : contextName + CONTEXT_SUFFIX;
   }
   const config = loadConfig();
-  const root = config.root ?? process.cwd();
-  const paths = discoverContextPaths(root);
+  const paths = discoverContextPaths(process.cwd());
   const existing = paths.get(contextName);
   if (existing) return existing;
-  const saveDir = config.contextDir ? (0, import_node_path2.isAbsolute)(config.contextDir) ? config.contextDir : (0, import_node_path2.join)(root, config.contextDir) : root;
-  return (0, import_node_path2.join)(saveDir, `${contextName}${CONTEXT_SUFFIX}`);
-}
-function resolveSaveContextPath(nameOrPath) {
-  if ((0, import_node_path2.isAbsolute)(nameOrPath) || nameOrPath.includes(import_node_path2.sep)) {
-    return nameOrPath.endsWith(CONTEXT_SUFFIX) ? nameOrPath : nameOrPath + CONTEXT_SUFFIX;
-  }
-  return getContextWritePath(nameOrPath);
-}
-function getContextAtPath(filePath) {
-  if (!(0, import_node_fs2.existsSync)(filePath)) 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 {
-    return {};
-  }
+  const projectRoot = config.root ?? process.cwd();
+  return (0, import_node_path2.join)(projectRoot, `${contextName}${CONTEXT_SUFFIX}`);
 }
 function writeToContext(contextName, key, value) {
   const path = getContextWritePath(contextName);
@@ -491,7 +477,7 @@ function defaultKeyFromName(name) {
 function defaultEnvFromKey(key) {
   return key.toUpperCase().replace(/-/g, "_");
 }
-function normalizeValidatorResult(result) {
+function normalizeParserResult(result) {
   if (typeof result === "boolean") {
     return result ? { success: true } : { success: false };
   }
@@ -501,7 +487,7 @@ function normalizeValidatorResult(result) {
 function scenv(name, options = {}) {
   const key = options.key ?? defaultKeyFromName(name);
   const envKey = options.env ?? defaultEnvFromKey(key);
-  const validator = options.validator;
+  const parserFn = options.parser;
   const promptFn = options.prompt;
   const defaultValue = options.default;
   async function resolveRaw() {
@@ -588,10 +574,10 @@ function scenv(name, options = {}) {
     log("info", `variable "${name}" (key=${key}) resolved from ${resolvedFrom}`);
     return { value, raw, hadEnv, wasPrompted };
   }
-  function validate(value) {
-    if (!validator) return { success: true, data: value };
-    const result = validator(value);
-    const normalized = normalizeValidatorResult(result);
+  function parse(value) {
+    if (!parserFn) return { success: true, data: value };
+    const result = parserFn(value);
+    const normalized = normalizeParserResult(result);
     if (normalized.success) {
       const data = "data" in normalized && normalized.data !== void 0 ? normalized.data : value;
       return { success: true, data };
@@ -603,17 +589,18 @@ function scenv(name, options = {}) {
   }
   async function get(options2) {
     const { value, wasPrompted } = await getResolvedValue(options2);
-    const validated = validate(value);
-    if (!validated.success) {
-      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+    const parsed = parse(value);
+    if (!parsed.success) {
+      const errMsg = `Parsing failed for "${name}": ${parsed.error ?? "unknown"}`;
       log("error", errMsg);
       throw new Error(errMsg);
     }
-    const final = validated.data;
-    if (wasPrompted) {
-      const config = loadConfig();
-      setInMemoryContext(key, String(final));
-      if (config.saveContextTo) {
+    const final = parsed.data;
+    const config = loadConfig();
+    if (wasPrompted) setInMemoryContext(key, String(final));
+    if (config.saveContextTo) {
+      const saveMode = config.saveMode ?? "all";
+      if (saveMode === "all" || wasPrompted) {
         writeToContext(config.saveContextTo, key, String(final));
         log("info", `Saved key=${key} to saveContextTo ${config.saveContextTo}`);
       }
@@ -630,16 +617,16 @@ function scenv(name, options = {}) {
   }
   async function save(value) {
     const toSave = value ?? (await getResolvedValue()).value;
-    const validated = validate(toSave);
-    if (!validated.success) {
-      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+    const parsed = parse(toSave);
+    if (!parsed.success) {
+      const errMsg = `Parsing failed for "${name}": ${parsed.error ?? "unknown"}`;
       log("error", errMsg);
       throw new Error(errMsg);
     }
     const config = loadConfig();
-    setInMemoryContext(key, String(validated.data));
+    setInMemoryContext(key, String(parsed.data));
     if (config.saveContextTo) {
-      writeToContext(config.saveContextTo, key, String(validated.data));
+      writeToContext(config.saveContextTo, key, String(parsed.data));
       log("info", `Saved key=${key} to saveContextTo ${config.saveContextTo}`);
     }
   }
@@ -647,12 +634,15 @@ function scenv(name, options = {}) {
 }
 
 // src/cli-args.ts
+var import_node_path3 = require("path");
 function parseScenvArgs(argv) {
   const config = {};
   let i = 0;
   while (i < argv.length) {
     const arg = argv[i];
-    if (arg === "--context" && argv[i + 1] !== void 0) {
+    if (arg === "--root" && argv[i + 1] !== void 0) {
+      config.root = (0, import_node_path3.resolve)(argv[++i]);
+    } else if (arg === "--context" && argv[i + 1] !== void 0) {
       config.context = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--add-context" && argv[i + 1] !== void 0) {
       config.addContext = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
@@ -674,8 +664,11 @@ function parseScenvArgs(argv) {
       }
     } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
       config.saveContextTo = argv[++i];
-    } else if (arg === "--context-dir" && argv[i + 1] !== void 0) {
-      config.contextDir = argv[++i];
+    } else if (arg === "--save-mode" && argv[i + 1] !== void 0) {
+      const v = argv[++i].toLowerCase();
+      if (v === "all" || v === "prompts-only") {
+        config.saveMode = v;
+      }
     } else if ((arg === "--log-level" || arg === "--log") && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (LOG_LEVELS.includes(v)) {

package/dist/index.d.cts

@@ -13,6 +13,12 @@ type PromptMode = "always" | "never" | "fallback" | "no-env";
 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];
+/**
+ * When to write resolved values to saveContextTo during get().
+ * - `"all"` – Save every resolved variable (from set, env, context, or prompt). Useful for re-running with the same values.
+ * - `"prompts-only"` – Save only when the user was prompted. Default is `"all"`.
+ */
+type SaveMode = "all" | "prompts-only";
 /**
  * Full scenv configuration. Built from file (scenv.config.json), environment (SCENV_*),
  * and programmatic config (configure()), with programmatic > env > file precedence.
@@ -33,9 +39,9 @@ interface ScenvConfig {
     set?: Record<string, string>;
     /** Optional path or context name (without .context.json) where to save resolved values. If set, all saves go here and this context is used before prompting. If unset, values are saved to an in-memory context only (same process). */
     saveContextTo?: string;
-    /** Directory to save context files to when the context is not already discovered. Relative to root unless absolute. If unset, new context files are saved under root. */
-    contextDir?: string;
-    /** Root directory for config file search and context discovery. Default is cwd or the directory containing scenv.config.json. */
+    /** When to write to saveContextTo during get(): "all" (default) saves every resolved variable; "prompts-only" saves only when the user was prompted. */
+    saveMode?: SaveMode;
+    /** Project root: where to search for scenv.config.json and where new context files are saved. Defaults to the directory containing scenv.config.json (when found) or cwd. Context files are discovered from cwd. */
     root?: string;
     /** Logging level. Default is `"none"`. Messages go to stderr. */
     logLevel?: LogLevel;
@@ -120,17 +126,18 @@ declare function discoverContextPaths(dir: string, found?: Map<string, string>):
 /**
  * Loads key-value pairs from a single context file. Used when resolving @context:key references.
  * Does not depend on config.context or ignoreContext; the context file is read if it exists
- * under the config root.
+ * under the search directory.
  *
  * @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.
+ * @param root - Optional directory to search. If omitted, searches from process.cwd() then from project root (config.root) if the context is not found under cwd.
  * @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. If {@link ScenvConfig.saveContextTo}
- * is set, that context (file path or name) is loaded first; then {@link ScenvConfig.context}
- * order. Respects {@link ScenvConfig.ignoreContext}. Later contexts overwrite earlier for the same key.
+ * Loads and merges context values from the current config from {@link ScenvConfig.context} only.
+ * saveContextTo is not used for resolution; it is only a write target. To use the same context
+ * for reading, add it explicitly via context or addContext.
+ * Respects {@link ScenvConfig.ignoreContext}. Later contexts overwrite earlier for the same key.
  * Used during variable resolution (set > env > in-memory > merged context > default).
  *
  * @returns A flat record of key → string value. Empty if ignoreContext is true or no context loaded.
@@ -139,7 +146,7 @@ declare function getMergedContextValues(): Record<string, string>;
 /**
  * Returns the file path used for a context name or path when saving.
  * - If contextName is path-like (absolute or contains path separator), returns that path with .context.json appended if not already present.
- * - Otherwise, if that context was already discovered under config.root, returns its path; else uses config.contextDir (if set) or root.
+ * - Otherwise, if that context was already discovered under cwd, returns its path; else saves under project root (config.root or cwd).
  *
  * @param contextName - Context name (e.g. "dev", "prod") or file path without suffix (e.g. "/path/to/myfile" → myfile.context.json).
  * @returns Absolute path to the context JSON file.
@@ -147,18 +154,35 @@ declare function getMergedContextValues(): Record<string, string>;
 declare function getContextWritePath(contextName: 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.
+ * Return type for a variable's optional `parser` function. Input is always the raw string
+ * (from set/env/context) or the default. Use a boolean for simple pass/fail, or an object
+ * to pass a parsed/transformed value or a custom error.
+ * - `true` or `{ success: true, data?: T }` – parsing passed; optional `data` is the output value (type T).
+ * - `false` or `{ success: false, error?: unknown }` – parsing failed; `.get()` throws with the error.
  */
-type ValidatorResult<T> = boolean | {
+type ParserResult<T> = boolean | {
     success: true;
     data?: T;
 } | {
     success: false;
     error?: unknown;
 };
+/**
+ * Infers the variable's value type (output type) from options: when a parser returns
+ * `{ success: true, data: D }`, that D is used; otherwise the type comes from `default` or defaults to string.
+ */
+type InferVariableType<O> = O extends {
+    parser: (v: unknown) => infer R;
+} ? R extends {
+    success: true;
+    data: infer D;
+} ? D extends undefined ? O extends {
+    default: infer Def;
+} ? Def : string : D : O extends {
+    default: infer Def;
+} ? Def : string : O extends {
+    default: infer Def;
+} ? Def : string;
 /**
  * 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).
@@ -168,16 +192,17 @@ 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`.
+ * Input from set/env/context is always string; `default` and the variable's value type are the output type T.
  */
-interface ScenvVariableOptions<T> {
+interface ScenvVariableOptions<T = string> {
     /** 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). */
+    /** Fallback when nothing is provided via --set, env, or context (and we're not prompting). Same type T as the variable's output (not parsed). */
     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. Parses the raw string (or default) into output type T. Receives raw value (typically string). Return { success: true, data } with the parsed value; variable type is inferred from data. */
+    parser?: (val: unknown) => ParserResult<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>;
 }
@@ -197,8 +222,8 @@ interface GetOptions<T> {
  */
 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.
+     * Resolve and return the value. Uses resolution order (set > env > context > default) and any prompt/parser.
+     * @throws If no value is found and no default/prompt, or if parsing fails.
      */
     get(options?: GetOptions<T>): Promise<T>;
     /**
@@ -234,11 +259,10 @@ interface ScenvVariable<T> {
  * 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
+ * ## Parser
  *
- * 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.
+ * If you pass a parser option, it is called with the raw value (typically string from set/env/context) or the default.
+ * Return { success: true, data } with the parsed output; the variable's type is inferred from data. On { success: false }, get() throws.
  *
  * ## save()
  *
@@ -247,22 +271,27 @@ interface ScenvVariable<T> {
  * When the user is prompted during get(), the value is always saved (to saveContextTo file if set, and always to in-memory)
  * so a second get() on the same variable does not prompt again.
  *
- * @typeParam T - Value type (default string). Use a validator to coerce to number, boolean, etc.
+ * @typeParam T - Output (value) type of the variable, e.g. string, number, URL. Defaults to string.
  * @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().
+ * @param options - Optional. key, env, default, parser, prompt. See {@link ScenvVariableOptions}.
+ * @returns A {@link ScenvVariable<T>} with get(), safeGet(), and save().
  *
  * @example
  * const apiUrl = scenv("API URL", { default: "http://localhost:4000" });
  * const url = await apiUrl.get();
+ *
+ * @example
+ * const port = scenv<number>("Port", { parser: parser(z.coerce.number()), default: 3000 });
+ * const n = await port.get(); // number
  */
-declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): ScenvVariable<T>;
+declare function scenv<T = string>(name: string, options?: ScenvVariableOptions<T>): ScenvVariable<T>;
 
 /**
  * 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:
+ * - `--root path` – Project root (where to find scenv.config.json and where new context files are saved). Relative paths are resolved from cwd.
  * - `--context a,b,c` – Set context list (replace).
  * - `--add-context x,y` – Add context names.
  * - `--prompt always|never|fallback|no-env` – Prompt mode.
@@ -270,7 +299,7 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  * - `--ignore-context` – Set ignoreContext to true.
  * - `--set key=value` or `--set=key=value` – Add to set overrides (multiple allowed).
  * - `--save-context-to pathOrName` – saveContextTo (path or context name without .context.json).
- * - `--context-dir path` – contextDir (directory to save context files to by default).
+ * - `--save-mode all|prompts-only` – When to write to saveContextTo during get(); default is all.
  * - `--log-level level`, `--log level`, `--log=level` – logLevel.
  *
  * @param argv - Array of CLI arguments (e.g. process.argv.slice(2)).
@@ -278,4 +307,4 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type GetOptions, LOG_LEVELS, type LogLevel, type PromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContext, getContextWritePath, getInMemoryContext, getMergedContextValues, loadConfig, parseScenvArgs, resetConfig, resetInMemoryContext, resetLogState, scenv, setInMemoryContext };
+export { type DefaultPromptFn, type GetOptions, type InferVariableType, LOG_LEVELS, type LogLevel, type ParserResult, type PromptMode, type SaveMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, type ScenvVariableOptions, configure, discoverContextPaths, getCallbacks, getContext, getContextWritePath, getInMemoryContext, getMergedContextValues, loadConfig, parseScenvArgs, resetConfig, resetInMemoryContext, resetLogState, scenv, setInMemoryContext };

package/dist/index.d.ts

@@ -13,6 +13,12 @@ type PromptMode = "always" | "never" | "fallback" | "no-env";
 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];
+/**
+ * When to write resolved values to saveContextTo during get().
+ * - `"all"` – Save every resolved variable (from set, env, context, or prompt). Useful for re-running with the same values.
+ * - `"prompts-only"` – Save only when the user was prompted. Default is `"all"`.
+ */
+type SaveMode = "all" | "prompts-only";
 /**
  * Full scenv configuration. Built from file (scenv.config.json), environment (SCENV_*),
  * and programmatic config (configure()), with programmatic > env > file precedence.
@@ -33,9 +39,9 @@ interface ScenvConfig {
     set?: Record<string, string>;
     /** Optional path or context name (without .context.json) where to save resolved values. If set, all saves go here and this context is used before prompting. If unset, values are saved to an in-memory context only (same process). */
     saveContextTo?: string;
-    /** Directory to save context files to when the context is not already discovered. Relative to root unless absolute. If unset, new context files are saved under root. */
-    contextDir?: string;
-    /** Root directory for config file search and context discovery. Default is cwd or the directory containing scenv.config.json. */
+    /** When to write to saveContextTo during get(): "all" (default) saves every resolved variable; "prompts-only" saves only when the user was prompted. */
+    saveMode?: SaveMode;
+    /** Project root: where to search for scenv.config.json and where new context files are saved. Defaults to the directory containing scenv.config.json (when found) or cwd. Context files are discovered from cwd. */
     root?: string;
     /** Logging level. Default is `"none"`. Messages go to stderr. */
     logLevel?: LogLevel;
@@ -120,17 +126,18 @@ declare function discoverContextPaths(dir: string, found?: Map<string, string>):
 /**
  * Loads key-value pairs from a single context file. Used when resolving @context:key references.
  * Does not depend on config.context or ignoreContext; the context file is read if it exists
- * under the config root.
+ * under the search directory.
  *
  * @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.
+ * @param root - Optional directory to search. If omitted, searches from process.cwd() then from project root (config.root) if the context is not found under cwd.
  * @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. If {@link ScenvConfig.saveContextTo}
- * is set, that context (file path or name) is loaded first; then {@link ScenvConfig.context}
- * order. Respects {@link ScenvConfig.ignoreContext}. Later contexts overwrite earlier for the same key.
+ * Loads and merges context values from the current config from {@link ScenvConfig.context} only.
+ * saveContextTo is not used for resolution; it is only a write target. To use the same context
+ * for reading, add it explicitly via context or addContext.
+ * Respects {@link ScenvConfig.ignoreContext}. Later contexts overwrite earlier for the same key.
  * Used during variable resolution (set > env > in-memory > merged context > default).
  *
  * @returns A flat record of key → string value. Empty if ignoreContext is true or no context loaded.
@@ -139,7 +146,7 @@ declare function getMergedContextValues(): Record<string, string>;
 /**
  * Returns the file path used for a context name or path when saving.
  * - If contextName is path-like (absolute or contains path separator), returns that path with .context.json appended if not already present.
- * - Otherwise, if that context was already discovered under config.root, returns its path; else uses config.contextDir (if set) or root.
+ * - Otherwise, if that context was already discovered under cwd, returns its path; else saves under project root (config.root or cwd).
  *
  * @param contextName - Context name (e.g. "dev", "prod") or file path without suffix (e.g. "/path/to/myfile" → myfile.context.json).
  * @returns Absolute path to the context JSON file.
@@ -147,18 +154,35 @@ declare function getMergedContextValues(): Record<string, string>;
 declare function getContextWritePath(contextName: 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.
+ * Return type for a variable's optional `parser` function. Input is always the raw string
+ * (from set/env/context) or the default. Use a boolean for simple pass/fail, or an object
+ * to pass a parsed/transformed value or a custom error.
+ * - `true` or `{ success: true, data?: T }` – parsing passed; optional `data` is the output value (type T).
+ * - `false` or `{ success: false, error?: unknown }` – parsing failed; `.get()` throws with the error.
  */
-type ValidatorResult<T> = boolean | {
+type ParserResult<T> = boolean | {
     success: true;
     data?: T;
 } | {
     success: false;
     error?: unknown;
 };
+/**
+ * Infers the variable's value type (output type) from options: when a parser returns
+ * `{ success: true, data: D }`, that D is used; otherwise the type comes from `default` or defaults to string.
+ */
+type InferVariableType<O> = O extends {
+    parser: (v: unknown) => infer R;
+} ? R extends {
+    success: true;
+    data: infer D;
+} ? D extends undefined ? O extends {
+    default: infer Def;
+} ? Def : string : D : O extends {
+    default: infer Def;
+} ? Def : string : O extends {
+    default: infer Def;
+} ? Def : string;
 /**
  * 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).
@@ -168,16 +192,17 @@ 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`.
+ * Input from set/env/context is always string; `default` and the variable's value type are the output type T.
  */
-interface ScenvVariableOptions<T> {
+interface ScenvVariableOptions<T = string> {
     /** 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). */
+    /** Fallback when nothing is provided via --set, env, or context (and we're not prompting). Same type T as the variable's output (not parsed). */
     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. Parses the raw string (or default) into output type T. Receives raw value (typically string). Return { success: true, data } with the parsed value; variable type is inferred from data. */
+    parser?: (val: unknown) => ParserResult<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>;
 }
@@ -197,8 +222,8 @@ interface GetOptions<T> {
  */
 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.
+     * Resolve and return the value. Uses resolution order (set > env > context > default) and any prompt/parser.
+     * @throws If no value is found and no default/prompt, or if parsing fails.
      */
     get(options?: GetOptions<T>): Promise<T>;
     /**
@@ -234,11 +259,10 @@ interface ScenvVariable<T> {
  * 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
+ * ## Parser
  *
- * 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.
+ * If you pass a parser option, it is called with the raw value (typically string from set/env/context) or the default.
+ * Return { success: true, data } with the parsed output; the variable's type is inferred from data. On { success: false }, get() throws.
  *
  * ## save()
  *
@@ -247,22 +271,27 @@ interface ScenvVariable<T> {
  * When the user is prompted during get(), the value is always saved (to saveContextTo file if set, and always to in-memory)
  * so a second get() on the same variable does not prompt again.
  *
- * @typeParam T - Value type (default string). Use a validator to coerce to number, boolean, etc.
+ * @typeParam T - Output (value) type of the variable, e.g. string, number, URL. Defaults to string.
  * @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().
+ * @param options - Optional. key, env, default, parser, prompt. See {@link ScenvVariableOptions}.
+ * @returns A {@link ScenvVariable<T>} with get(), safeGet(), and save().
  *
  * @example
  * const apiUrl = scenv("API URL", { default: "http://localhost:4000" });
  * const url = await apiUrl.get();
+ *
+ * @example
+ * const port = scenv<number>("Port", { parser: parser(z.coerce.number()), default: 3000 });
+ * const n = await port.get(); // number
  */
-declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): ScenvVariable<T>;
+declare function scenv<T = string>(name: string, options?: ScenvVariableOptions<T>): ScenvVariable<T>;
 
 /**
  * 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:
+ * - `--root path` – Project root (where to find scenv.config.json and where new context files are saved). Relative paths are resolved from cwd.
  * - `--context a,b,c` – Set context list (replace).
  * - `--add-context x,y` – Add context names.
  * - `--prompt always|never|fallback|no-env` – Prompt mode.
@@ -270,7 +299,7 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  * - `--ignore-context` – Set ignoreContext to true.
  * - `--set key=value` or `--set=key=value` – Add to set overrides (multiple allowed).
  * - `--save-context-to pathOrName` – saveContextTo (path or context name without .context.json).
- * - `--context-dir path` – contextDir (directory to save context files to by default).
+ * - `--save-mode all|prompts-only` – When to write to saveContextTo during get(); default is all.
  * - `--log-level level`, `--log level`, `--log=level` – logLevel.
  *
  * @param argv - Array of CLI arguments (e.g. process.argv.slice(2)).
@@ -278,4 +307,4 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type GetOptions, LOG_LEVELS, type LogLevel, type PromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContext, getContextWritePath, getInMemoryContext, getMergedContextValues, loadConfig, parseScenvArgs, resetConfig, resetInMemoryContext, resetLogState, scenv, setInMemoryContext };
+export { type DefaultPromptFn, type GetOptions, type InferVariableType, LOG_LEVELS, type LogLevel, type ParserResult, type PromptMode, type SaveMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, type ScenvVariableOptions, configure, discoverContextPaths, getCallbacks, getContext, getContextWritePath, getInMemoryContext, getMergedContextValues, loadConfig, parseScenvArgs, resetConfig, resetInMemoryContext, resetLogState, scenv, setInMemoryContext };

package/dist/index.js

@@ -8,12 +8,12 @@ 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) => {
+  return new Promise((resolve2, reject) => {
     rl.question(message, (answer) => {
       rl.close();
       const trimmed = answer.trim();
       const value = trimmed !== "" ? trimmed : defaultStr;
-      resolve(value);
+      resolve2(value);
     });
     rl.on("error", (err) => {
       rl.close();
@@ -32,7 +32,7 @@ var envKeyMap = {
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
   SCENV_SAVE_CONTEXT_TO: "saveContextTo",
-  SCENV_CONTEXT_DIR: "contextDir",
+  SCENV_SAVE_MODE: "saveMode",
   SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
@@ -68,8 +68,10 @@ function configFromEnv() {
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
-    } else if (configKey === "contextDir") {
-      out.contextDir = val;
+    } else if (configKey === "saveMode") {
+      const v = val.toLowerCase();
+      if (v === "all" || v === "prompts-only")
+        out[configKey] = v;
     } else if (configKey === "logLevel") {
       const v = val.toLowerCase();
       if (LOG_LEVELS.includes(v)) out.logLevel = v;
@@ -109,8 +111,8 @@ function loadConfigFile(configDir) {
       out.set = parsed.set;
     if (typeof parsed.saveContextTo === "string")
       out.saveContextTo = parsed.saveContextTo;
-    if (typeof parsed.contextDir === "string") out.contextDir = parsed.contextDir;
-    else if (typeof parsed.contextsDir === "string") out.contextDir = parsed.contextsDir;
+    if (typeof parsed.saveMode === "string" && ["all", "prompts-only"].includes(parsed.saveMode))
+      out.saveMode = parsed.saveMode;
     if (typeof parsed.root === "string") out.root = parsed.root;
     if (typeof parsed.logLevel === "string" && LOG_LEVELS.includes(parsed.logLevel))
       out.logLevel = parsed.logLevel;
@@ -198,7 +200,7 @@ var CONFIG_LOG_KEYS = [
   "ignoreContext",
   "set",
   "saveContextTo",
-  "contextDir",
+  "saveMode",
   "logLevel"
 ];
 function configForLog(config) {
@@ -219,7 +221,7 @@ function logConfigLoaded(config) {
     if (config.ignoreEnv === true) parts.push("ignoreEnv=true");
     if (config.ignoreContext === true) parts.push("ignoreContext=true");
     if (config.saveContextTo !== void 0) parts.push("saveContextTo=" + config.saveContextTo);
-    if (config.contextDir !== void 0) parts.push("contextDir=" + config.contextDir);
+    if (config.saveMode !== void 0) parts.push("saveMode=" + config.saveMode);
     log("info", "config loaded", parts.join(" "));
   }
   if (levelNum >= LEVEL_NUM.debug) {
@@ -295,10 +297,23 @@ function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
   return found;
 }
 function getContext(contextName, root) {
-  const config = loadConfig();
-  const searchRoot = root ?? config.root ?? process.cwd();
-  const paths = discoverContextPaths(searchRoot);
-  const filePath = paths.get(contextName);
+  let filePath;
+  if (root !== void 0) {
+    const paths = discoverContextPaths(root);
+    filePath = paths.get(contextName);
+  } else {
+    const cwd = process.cwd();
+    const paths = discoverContextPaths(cwd);
+    filePath = paths.get(contextName);
+    if (!filePath) {
+      const config = loadConfig();
+      const projectRoot = config.root ?? cwd;
+      if (projectRoot !== cwd) {
+        const rootPaths = discoverContextPaths(projectRoot);
+        filePath = rootPaths.get(contextName);
+      }
+    }
+  }
   if (!filePath) {
     log("trace", `getContext: context "${contextName}" not found`);
     return {};
@@ -323,17 +338,9 @@ function getMergedContextValues() {
   const config = loadConfig();
   logConfigLoaded(config);
   if (config.ignoreContext) return {};
-  const root = config.root ?? process.cwd();
-  const paths = discoverContextPaths(root);
+  const searchRoot = process.cwd();
+  const paths = discoverContextPaths(searchRoot);
   const out = {};
-  if (config.saveContextTo) {
-    const savePath = resolveSaveContextPath(config.saveContextTo);
-    const saveCtx = getContextAtPath(savePath);
-    for (const [k, v] of Object.entries(saveCtx)) out[k] = v;
-    if (Object.keys(saveCtx).length > 0) {
-      log("debug", `saveContextTo "${config.saveContextTo}" loaded keys=${JSON.stringify(Object.keys(saveCtx))}`);
-    }
-  }
   for (const contextName of config.context ?? []) {
     const filePath = paths.get(contextName);
     if (!filePath) {
@@ -365,32 +372,11 @@ function getContextWritePath(contextName) {
     return contextName.endsWith(CONTEXT_SUFFIX) ? contextName : contextName + CONTEXT_SUFFIX;
   }
   const config = loadConfig();
-  const root = config.root ?? process.cwd();
-  const paths = discoverContextPaths(root);
+  const paths = discoverContextPaths(process.cwd());
   const existing = paths.get(contextName);
   if (existing) return existing;
-  const saveDir = config.contextDir ? isAbsolute(config.contextDir) ? config.contextDir : join2(root, config.contextDir) : root;
-  return join2(saveDir, `${contextName}${CONTEXT_SUFFIX}`);
-}
-function resolveSaveContextPath(nameOrPath) {
-  if (isAbsolute(nameOrPath) || nameOrPath.includes(sep)) {
-    return nameOrPath.endsWith(CONTEXT_SUFFIX) ? nameOrPath : nameOrPath + CONTEXT_SUFFIX;
-  }
-  return getContextWritePath(nameOrPath);
-}
-function getContextAtPath(filePath) {
-  if (!existsSync2(filePath)) 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 {
-    return {};
-  }
+  const projectRoot = config.root ?? process.cwd();
+  return join2(projectRoot, `${contextName}${CONTEXT_SUFFIX}`);
 }
 function writeToContext(contextName, key, value) {
   const path = getContextWritePath(contextName);
@@ -458,7 +444,7 @@ function defaultKeyFromName(name) {
 function defaultEnvFromKey(key) {
   return key.toUpperCase().replace(/-/g, "_");
 }
-function normalizeValidatorResult(result) {
+function normalizeParserResult(result) {
   if (typeof result === "boolean") {
     return result ? { success: true } : { success: false };
   }
@@ -468,7 +454,7 @@ function normalizeValidatorResult(result) {
 function scenv(name, options = {}) {
   const key = options.key ?? defaultKeyFromName(name);
   const envKey = options.env ?? defaultEnvFromKey(key);
-  const validator = options.validator;
+  const parserFn = options.parser;
   const promptFn = options.prompt;
   const defaultValue = options.default;
   async function resolveRaw() {
@@ -555,10 +541,10 @@ function scenv(name, options = {}) {
     log("info", `variable "${name}" (key=${key}) resolved from ${resolvedFrom}`);
     return { value, raw, hadEnv, wasPrompted };
   }
-  function validate(value) {
-    if (!validator) return { success: true, data: value };
-    const result = validator(value);
-    const normalized = normalizeValidatorResult(result);
+  function parse(value) {
+    if (!parserFn) return { success: true, data: value };
+    const result = parserFn(value);
+    const normalized = normalizeParserResult(result);
     if (normalized.success) {
       const data = "data" in normalized && normalized.data !== void 0 ? normalized.data : value;
       return { success: true, data };
@@ -570,17 +556,18 @@ function scenv(name, options = {}) {
   }
   async function get(options2) {
     const { value, wasPrompted } = await getResolvedValue(options2);
-    const validated = validate(value);
-    if (!validated.success) {
-      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+    const parsed = parse(value);
+    if (!parsed.success) {
+      const errMsg = `Parsing failed for "${name}": ${parsed.error ?? "unknown"}`;
       log("error", errMsg);
       throw new Error(errMsg);
     }
-    const final = validated.data;
-    if (wasPrompted) {
-      const config = loadConfig();
-      setInMemoryContext(key, String(final));
-      if (config.saveContextTo) {
+    const final = parsed.data;
+    const config = loadConfig();
+    if (wasPrompted) setInMemoryContext(key, String(final));
+    if (config.saveContextTo) {
+      const saveMode = config.saveMode ?? "all";
+      if (saveMode === "all" || wasPrompted) {
         writeToContext(config.saveContextTo, key, String(final));
         log("info", `Saved key=${key} to saveContextTo ${config.saveContextTo}`);
       }
@@ -597,16 +584,16 @@ function scenv(name, options = {}) {
   }
   async function save(value) {
     const toSave = value ?? (await getResolvedValue()).value;
-    const validated = validate(toSave);
-    if (!validated.success) {
-      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+    const parsed = parse(toSave);
+    if (!parsed.success) {
+      const errMsg = `Parsing failed for "${name}": ${parsed.error ?? "unknown"}`;
       log("error", errMsg);
       throw new Error(errMsg);
     }
     const config = loadConfig();
-    setInMemoryContext(key, String(validated.data));
+    setInMemoryContext(key, String(parsed.data));
     if (config.saveContextTo) {
-      writeToContext(config.saveContextTo, key, String(validated.data));
+      writeToContext(config.saveContextTo, key, String(parsed.data));
       log("info", `Saved key=${key} to saveContextTo ${config.saveContextTo}`);
     }
   }
@@ -614,12 +601,15 @@ function scenv(name, options = {}) {
 }
 
 // src/cli-args.ts
+import { resolve } from "path";
 function parseScenvArgs(argv) {
   const config = {};
   let i = 0;
   while (i < argv.length) {
     const arg = argv[i];
-    if (arg === "--context" && argv[i + 1] !== void 0) {
+    if (arg === "--root" && argv[i + 1] !== void 0) {
+      config.root = resolve(argv[++i]);
+    } else if (arg === "--context" && argv[i + 1] !== void 0) {
       config.context = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--add-context" && argv[i + 1] !== void 0) {
       config.addContext = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
@@ -641,8 +631,11 @@ function parseScenvArgs(argv) {
       }
     } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
       config.saveContextTo = argv[++i];
-    } else if (arg === "--context-dir" && argv[i + 1] !== void 0) {
-      config.contextDir = argv[++i];
+    } else if (arg === "--save-mode" && argv[i + 1] !== void 0) {
+      const v = argv[++i].toLowerCase();
+      if (v === "all" || v === "prompts-only") {
+        config.saveMode = v;
+      }
     } else if ((arg === "--log-level" || arg === "--log") && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (LOG_LEVELS.includes(v)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenv",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Environment and context variables with runtime-configurable resolution",
   "repository": {
     "type": "git",