scenv 0.5.0 → 0.6.0

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
@@ -46,21 +46,21 @@ Prompting (when to ask the user) is controlled by config `prompt`: `always` | `n
 
 ## 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

@@ -86,13 +86,14 @@ async function defaultAskContext(name, contextNames) {
 var LOG_LEVELS = ["none", "trace", "debug", "info", "warn", "error"];
 var CONFIG_FILENAME = "scenv.config.json";
 var envKeyMap = {
-  SCENV_CONTEXT: "contexts",
-  SCENV_ADD_CONTEXTS: "addContexts",
+  SCENV_CONTEXT: "context",
+  SCENV_ADD_CONTEXT: "addContext",
   SCENV_PROMPT: "prompt",
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
   SCENV_SAVE_PROMPT: "shouldSavePrompt",
   SCENV_SAVE_CONTEXT_TO: "saveContextTo",
+  SCENV_CONTEXT_DIR: "contextDir",
   SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
@@ -120,7 +121,7 @@ function configFromEnv() {
   for (const [envKey, configKey] of Object.entries(envKeyMap)) {
     const val = process.env[envKey];
     if (val === void 0 || val === "") continue;
-    if (configKey === "contexts" || configKey === "addContexts") {
+    if (configKey === "context" || configKey === "addContext") {
       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";
@@ -132,6 +133,8 @@ function configFromEnv() {
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
+    } else if (configKey === "contextDir") {
+      out.contextDir = val;
     } else if (configKey === "logLevel") {
       const v = val.toLowerCase();
       if (LOG_LEVELS.includes(v)) out.logLevel = v;
@@ -146,12 +149,20 @@ function loadConfigFile(configDir) {
     const raw = (0, import_node_fs.readFileSync)(path, "utf-8");
     const parsed = JSON.parse(raw);
     const out = {};
-    if (Array.isArray(parsed.contexts))
-      out.contexts = parsed.contexts.filter(
+    if (Array.isArray(parsed.context))
+      out.context = parsed.context.filter(
         (x) => typeof x === "string"
       );
-    if (Array.isArray(parsed.addContexts))
-      out.addContexts = parsed.addContexts.filter(
+    else if (Array.isArray(parsed.contexts))
+      out.context = parsed.contexts.filter(
+        (x) => typeof x === "string"
+      );
+    if (Array.isArray(parsed.addContext))
+      out.addContext = parsed.addContext.filter(
+        (x) => typeof x === "string"
+      );
+    else if (Array.isArray(parsed.addContexts))
+      out.addContext = parsed.addContexts.filter(
         (x) => typeof x === "string"
       );
     if (typeof parsed.prompt === "string" && ["always", "never", "fallback", "no-env"].includes(parsed.prompt))
@@ -165,6 +176,8 @@ function loadConfigFile(configDir) {
       out.shouldSavePrompt = parsed.shouldSavePrompt ?? parsed.savePrompt;
     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.root === "string") out.root = parsed.root;
     if (typeof parsed.logLevel === "string" && LOG_LEVELS.includes(parsed.logLevel))
       out.logLevel = parsed.logLevel;
@@ -180,11 +193,11 @@ function loadConfigFile(configDir) {
   }
 }
 function mergeContexts(fileConfig, envConfig, progConfig) {
-  const fromFile = fileConfig.contexts ?? fileConfig.addContexts ?? [];
-  const fromEnvAdd = envConfig.addContexts ?? [];
-  const fromEnvReplace = envConfig.contexts;
-  const fromProgAdd = progConfig.addContexts ?? [];
-  const fromProgReplace = progConfig.contexts;
+  const fromFile = fileConfig.context ?? fileConfig.addContext ?? [];
+  const fromEnvAdd = envConfig.addContext ?? [];
+  const fromEnvReplace = envConfig.context;
+  const fromProgAdd = progConfig.addContext ?? [];
+  const fromProgReplace = progConfig.context;
   const replace = fromProgReplace ?? fromEnvReplace;
   if (replace !== void 0) return replace;
   const base = [...fromFile];
@@ -208,8 +221,8 @@ function loadConfig(root) {
     ...envConfig,
     ...programmaticConfig
   };
-  merged.contexts = mergeContexts(fileConfig, envConfig, programmaticConfig);
-  delete merged.addContexts;
+  merged.context = mergeContexts(fileConfig, envConfig, programmaticConfig);
+  delete merged.addContext;
   if (configDir && !merged.root) merged.root = configDir;
   else if (!merged.root) merged.root = startDir;
   return merged;
@@ -252,7 +265,7 @@ function logConfigLoaded(config) {
     "info",
     "config loaded",
     "root=" + (config.root ?? "(cwd)"),
-    "contexts=" + JSON.stringify(config.contexts ?? [])
+    "context=" + JSON.stringify(config.context ?? [])
   );
 }
 function log(level, msg, ...args) {
@@ -338,7 +351,7 @@ function getMergedContextValues() {
   const root = config.root ?? process.cwd();
   const paths = discoverContextPaths(root);
   const out = {};
-  for (const contextName of config.contexts ?? []) {
+  for (const contextName of config.context ?? []) {
     const filePath = paths.get(contextName);
     if (!filePath) {
       log("warn", `context "${contextName}" not found (no *.context.json)`);
@@ -370,7 +383,8 @@ function getContextWritePath(contextName) {
   const paths = discoverContextPaths(root);
   const existing = paths.get(contextName);
   if (existing) return existing;
-  return (0, import_node_path2.join)(root, `${contextName}${CONTEXT_SUFFIX}`);
+  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 writeToContext(contextName, key, value) {
   const path = getContextWritePath(contextName);
@@ -388,26 +402,49 @@ function writeToContext(contextName, key, value) {
 }
 
 // src/variable.ts
-var CONTEXT_REF_REGEX = /^@([^:]+):(.+)$/;
+var CONTEXT_REF_FULL_REGEX = /^@([^:]+):(.+)$/;
+var CONTEXT_REF_SHORT_REGEX = /^@([^:]+)$/;
+var ENV_REF_REGEX = /\$([A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})/g;
 var MAX_CONTEXT_REF_DEPTH = 10;
-function resolveContextReference(raw, depth = 0) {
+function expandEnvReferences(str) {
+  return str.replace(ENV_REF_REGEX, (_, name) => {
+    const key = name.startsWith("{") ? name.slice(1, -1) : name;
+    return process.env[key] ?? "";
+  });
+}
+function resolveContextReference(raw, currentKey, 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 afterEnv = expandEnvReferences(raw);
+  let contextName;
+  let refKey;
+  const fullMatch = afterEnv.match(CONTEXT_REF_FULL_REGEX);
+  if (fullMatch) {
+    [, contextName, refKey] = fullMatch;
+  } else {
+    const shortMatch = afterEnv.match(CONTEXT_REF_SHORT_REGEX);
+    if (!shortMatch) return afterEnv;
+    contextName = shortMatch[1];
+    if (currentKey === void 0) {
+      throw new Error(
+        `Context reference @${contextName} (short form) cannot be resolved without a variable key. Use @${contextName}:<key> to specify a key.`
+      );
+    }
+    refKey = currentKey;
+  }
   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).`;
+    const displayRef = refKey === currentKey ? `@${contextName}` : `@${contextName}:${refKey}`;
+    const msg = hasContext ? `Context reference ${displayRef} could not be resolved: key "${refKey}" is not defined in context "${contextName}".` : `Context reference ${displayRef} could not be resolved: context "${contextName}" not found (no ${contextName}.context.json).`;
     log("error", msg);
     throw new Error(msg);
   }
-  return resolveContextReference(resolved, depth + 1);
+  return resolveContextReference(resolved, currentKey, depth + 1);
 }
 function defaultKeyFromName(name) {
   return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
@@ -433,7 +470,7 @@ 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}`);
-      const raw = resolveContextReference(config.set[key]);
+      const raw = resolveContextReference(config.set[key], key);
       return { raw, source: "set" };
     }
     if (!config.ignoreEnv) {
@@ -441,7 +478,7 @@ function scenv(name, options = {}) {
       const envVal = process.env[envKey];
       if (envVal !== void 0 && envVal !== "") {
         log("trace", "resolveRaw: env hit");
-        const raw = resolveContextReference(envVal);
+        const raw = resolveContextReference(envVal, key);
         return { raw, source: "env" };
       }
     }
@@ -450,7 +487,7 @@ function scenv(name, options = {}) {
       const ctx = getMergedContextValues();
       if (ctx[key] !== void 0) {
         log("trace", `resolveRaw: context hit key=${key}`);
-        const raw = resolveContextReference(ctx[key]);
+        const raw = resolveContextReference(ctx[key], key);
         return { raw, source: "context" };
       }
     }
@@ -477,7 +514,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;
+    const resolvedDefault = effectiveDefault === void 0 ? void 0 : typeof effectiveDefault === "string" ? resolveContextReference(effectiveDefault, key) : effectiveDefault;
     let wasPrompted = false;
     let value;
     let resolvedFrom;
@@ -491,7 +528,7 @@ function scenv(name, options = {}) {
       }
       const defaultForPrompt = raw !== void 0 ? raw : resolvedDefault;
       let promptedValue = await Promise.resolve(fn(name, defaultForPrompt));
-      value = typeof promptedValue === "string" ? resolveContextReference(promptedValue) : promptedValue;
+      value = typeof promptedValue === "string" ? resolveContextReference(promptedValue, key) : promptedValue;
       wasPrompted = true;
       resolvedFrom = "prompt";
     } else if (raw !== void 0) {
@@ -546,7 +583,7 @@ function scenv(name, options = {}) {
       }
       if (!doSave) return final;
       const callbacks = getCallbacks();
-      const contextNames = config.contexts ?? [];
+      const contextNames = config.context ?? [];
       let ctxToSave;
       if (config.saveContextTo === "ask") {
         if (typeof callbacks.onAskContext !== "function") {
@@ -590,10 +627,10 @@ function scenv(name, options = {}) {
       }
       contextName = await callbacks.onAskContext(
         name,
-        config.contexts ?? []
+        config.context ?? []
       );
     }
-    if (!contextName) contextName = config.contexts?.[0] ?? "default";
+    if (!contextName) contextName = config.context?.[0] ?? "default";
     writeToContext(contextName, key, String(validated.data));
     log("info", `Saved key=${key} to context ${contextName}`);
   }
@@ -607,9 +644,9 @@ function parseScenvArgs(argv) {
   while (i < argv.length) {
     const arg = argv[i];
     if (arg === "--context" && argv[i + 1] !== void 0) {
-      config.contexts = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
+      config.context = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--add-context" && argv[i + 1] !== void 0) {
-      config.addContexts = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
+      config.addContext = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--prompt" && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (["always", "never", "fallback", "no-env"].includes(v)) {
@@ -633,6 +670,8 @@ 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 === "--log-level" || arg === "--log") && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (LOG_LEVELS.includes(v)) {

package/dist/index.d.cts

@@ -27,9 +27,9 @@ type LogLevel = (typeof LOG_LEVELS)[number];
  */
 interface ScenvConfig {
     /** Replace the context list entirely (CLI: `--context a,b,c`). Loaded in order; later overwrites earlier for same key. */
-    contexts?: string[];
-    /** Merge these context names with existing (CLI: `--add-context a,b,c`). Ignored if `contexts` is set in the same layer. */
-    addContexts?: string[];
+    context?: string[];
+    /** Merge these context names with existing (CLI: `--add-context a,b,c`). Ignored if `context` is set in the same layer. */
+    addContext?: string[];
     /** When to prompt for a variable value. See {@link PromptMode}. Default is `"fallback"`. */
     prompt?: PromptMode;
     /** If true, environment variables are not used during resolution. */
@@ -42,6 +42,8 @@ interface ScenvConfig {
     shouldSavePrompt?: SavePromptMode;
     /** Target context for saving: a context name, or `"ask"` to use {@link ScenvCallbacks.onAskContext}. */
     saveContextTo?: "ask" | 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. */
     root?: string;
     /** Logging level. Default is `"none"`. Messages go to stderr. */
@@ -79,7 +81,7 @@ declare function getCallbacks(): ScenvCallbacks;
  * 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.
+ * @returns The merged {@link ScenvConfig} with at least `root` and `context` defined.
  */
 declare function loadConfig(root?: string): ScenvConfig;
 /**
@@ -119,7 +121,7 @@ declare function resetLogState(): void;
 declare function discoverContextPaths(dir: string, found?: Map<string, string>): Map<string, string>;
 /**
  * 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
+ * Does not depend on config.context 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.
@@ -128,12 +130,12 @@ declare function discoverContextPaths(dir: string, found?: Map<string, string>):
  */
 declare function getContext(contextName: string, root?: string): Record<string, string>;
 /**
- * Loads and merges context values from the current config. Respects {@link ScenvConfig.contexts}
+ * Loads and merges context values from the current config. Respects {@link ScenvConfig.context}
  * 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.
+ * @returns A flat record of key → string value. Empty if ignoreContext is true or no context loaded.
  */
 declare function getMergedContextValues(): Record<string, string>;
 
@@ -218,7 +220,7 @@ interface ScenvVariable<T> {
  * 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)
+ * - Context files (merged key-value from the context list 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
@@ -254,14 +256,15 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  * 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.
+ * - `--context a,b,c` – Set context list (replace).
+ * - `--add-context x,y` – Add context names.
  * - `--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.
+ * - `--context-dir path` – contextDir (directory to save context files to by default).
  * - `--log-level level`, `--log level`, `--log=level` – logLevel.
  *
  * @param argv - Array of CLI arguments (e.g. process.argv.slice(2)).

package/dist/index.d.ts

@@ -27,9 +27,9 @@ type LogLevel = (typeof LOG_LEVELS)[number];
  */
 interface ScenvConfig {
     /** Replace the context list entirely (CLI: `--context a,b,c`). Loaded in order; later overwrites earlier for same key. */
-    contexts?: string[];
-    /** Merge these context names with existing (CLI: `--add-context a,b,c`). Ignored if `contexts` is set in the same layer. */
-    addContexts?: string[];
+    context?: string[];
+    /** Merge these context names with existing (CLI: `--add-context a,b,c`). Ignored if `context` is set in the same layer. */
+    addContext?: string[];
     /** When to prompt for a variable value. See {@link PromptMode}. Default is `"fallback"`. */
     prompt?: PromptMode;
     /** If true, environment variables are not used during resolution. */
@@ -42,6 +42,8 @@ interface ScenvConfig {
     shouldSavePrompt?: SavePromptMode;
     /** Target context for saving: a context name, or `"ask"` to use {@link ScenvCallbacks.onAskContext}. */
     saveContextTo?: "ask" | 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. */
     root?: string;
     /** Logging level. Default is `"none"`. Messages go to stderr. */
@@ -79,7 +81,7 @@ declare function getCallbacks(): ScenvCallbacks;
  * 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.
+ * @returns The merged {@link ScenvConfig} with at least `root` and `context` defined.
  */
 declare function loadConfig(root?: string): ScenvConfig;
 /**
@@ -119,7 +121,7 @@ declare function resetLogState(): void;
 declare function discoverContextPaths(dir: string, found?: Map<string, string>): Map<string, string>;
 /**
  * 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
+ * Does not depend on config.context 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.
@@ -128,12 +130,12 @@ declare function discoverContextPaths(dir: string, found?: Map<string, string>):
  */
 declare function getContext(contextName: string, root?: string): Record<string, string>;
 /**
- * Loads and merges context values from the current config. Respects {@link ScenvConfig.contexts}
+ * Loads and merges context values from the current config. Respects {@link ScenvConfig.context}
  * 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.
+ * @returns A flat record of key → string value. Empty if ignoreContext is true or no context loaded.
  */
 declare function getMergedContextValues(): Record<string, string>;
 
@@ -218,7 +220,7 @@ interface ScenvVariable<T> {
  * 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)
+ * - Context files (merged key-value from the context list 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
@@ -254,14 +256,15 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  * 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.
+ * - `--context a,b,c` – Set context list (replace).
+ * - `--add-context x,y` – Add context names.
  * - `--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.
+ * - `--context-dir path` – contextDir (directory to save context files to by default).
  * - `--log-level level`, `--log level`, `--log=level` – logLevel.
  *
  * @param argv - Array of CLI arguments (e.g. process.argv.slice(2)).

package/dist/index.js

@@ -50,13 +50,14 @@ async function defaultAskContext(name, contextNames) {
 var LOG_LEVELS = ["none", "trace", "debug", "info", "warn", "error"];
 var CONFIG_FILENAME = "scenv.config.json";
 var envKeyMap = {
-  SCENV_CONTEXT: "contexts",
-  SCENV_ADD_CONTEXTS: "addContexts",
+  SCENV_CONTEXT: "context",
+  SCENV_ADD_CONTEXT: "addContext",
   SCENV_PROMPT: "prompt",
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
   SCENV_SAVE_PROMPT: "shouldSavePrompt",
   SCENV_SAVE_CONTEXT_TO: "saveContextTo",
+  SCENV_CONTEXT_DIR: "contextDir",
   SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
@@ -84,7 +85,7 @@ function configFromEnv() {
   for (const [envKey, configKey] of Object.entries(envKeyMap)) {
     const val = process.env[envKey];
     if (val === void 0 || val === "") continue;
-    if (configKey === "contexts" || configKey === "addContexts") {
+    if (configKey === "context" || configKey === "addContext") {
       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";
@@ -96,6 +97,8 @@ function configFromEnv() {
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
+    } else if (configKey === "contextDir") {
+      out.contextDir = val;
     } else if (configKey === "logLevel") {
       const v = val.toLowerCase();
       if (LOG_LEVELS.includes(v)) out.logLevel = v;
@@ -110,12 +113,20 @@ function loadConfigFile(configDir) {
     const raw = readFileSync(path, "utf-8");
     const parsed = JSON.parse(raw);
     const out = {};
-    if (Array.isArray(parsed.contexts))
-      out.contexts = parsed.contexts.filter(
+    if (Array.isArray(parsed.context))
+      out.context = parsed.context.filter(
         (x) => typeof x === "string"
       );
-    if (Array.isArray(parsed.addContexts))
-      out.addContexts = parsed.addContexts.filter(
+    else if (Array.isArray(parsed.contexts))
+      out.context = parsed.contexts.filter(
+        (x) => typeof x === "string"
+      );
+    if (Array.isArray(parsed.addContext))
+      out.addContext = parsed.addContext.filter(
+        (x) => typeof x === "string"
+      );
+    else if (Array.isArray(parsed.addContexts))
+      out.addContext = parsed.addContexts.filter(
         (x) => typeof x === "string"
       );
     if (typeof parsed.prompt === "string" && ["always", "never", "fallback", "no-env"].includes(parsed.prompt))
@@ -129,6 +140,8 @@ function loadConfigFile(configDir) {
       out.shouldSavePrompt = parsed.shouldSavePrompt ?? parsed.savePrompt;
     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.root === "string") out.root = parsed.root;
     if (typeof parsed.logLevel === "string" && LOG_LEVELS.includes(parsed.logLevel))
       out.logLevel = parsed.logLevel;
@@ -144,11 +157,11 @@ function loadConfigFile(configDir) {
   }
 }
 function mergeContexts(fileConfig, envConfig, progConfig) {
-  const fromFile = fileConfig.contexts ?? fileConfig.addContexts ?? [];
-  const fromEnvAdd = envConfig.addContexts ?? [];
-  const fromEnvReplace = envConfig.contexts;
-  const fromProgAdd = progConfig.addContexts ?? [];
-  const fromProgReplace = progConfig.contexts;
+  const fromFile = fileConfig.context ?? fileConfig.addContext ?? [];
+  const fromEnvAdd = envConfig.addContext ?? [];
+  const fromEnvReplace = envConfig.context;
+  const fromProgAdd = progConfig.addContext ?? [];
+  const fromProgReplace = progConfig.context;
   const replace = fromProgReplace ?? fromEnvReplace;
   if (replace !== void 0) return replace;
   const base = [...fromFile];
@@ -172,8 +185,8 @@ function loadConfig(root) {
     ...envConfig,
     ...programmaticConfig
   };
-  merged.contexts = mergeContexts(fileConfig, envConfig, programmaticConfig);
-  delete merged.addContexts;
+  merged.context = mergeContexts(fileConfig, envConfig, programmaticConfig);
+  delete merged.addContext;
   if (configDir && !merged.root) merged.root = configDir;
   else if (!merged.root) merged.root = startDir;
   return merged;
@@ -216,7 +229,7 @@ function logConfigLoaded(config) {
     "info",
     "config loaded",
     "root=" + (config.root ?? "(cwd)"),
-    "contexts=" + JSON.stringify(config.contexts ?? [])
+    "context=" + JSON.stringify(config.context ?? [])
   );
 }
 function log(level, msg, ...args) {
@@ -239,7 +252,7 @@ import {
   readdirSync,
   statSync
 } from "fs";
-import { join as join2, dirname as dirname2 } from "path";
+import { join as join2, dirname as dirname2, isAbsolute } from "path";
 var CONTEXT_SUFFIX = ".context.json";
 function discoverContextPathsInternal(dir, found) {
   let entries;
@@ -308,7 +321,7 @@ function getMergedContextValues() {
   const root = config.root ?? process.cwd();
   const paths = discoverContextPaths(root);
   const out = {};
-  for (const contextName of config.contexts ?? []) {
+  for (const contextName of config.context ?? []) {
     const filePath = paths.get(contextName);
     if (!filePath) {
       log("warn", `context "${contextName}" not found (no *.context.json)`);
@@ -340,7 +353,8 @@ function getContextWritePath(contextName) {
   const paths = discoverContextPaths(root);
   const existing = paths.get(contextName);
   if (existing) return existing;
-  return join2(root, `${contextName}${CONTEXT_SUFFIX}`);
+  const saveDir = config.contextDir ? isAbsolute(config.contextDir) ? config.contextDir : join2(root, config.contextDir) : root;
+  return join2(saveDir, `${contextName}${CONTEXT_SUFFIX}`);
 }
 function writeToContext(contextName, key, value) {
   const path = getContextWritePath(contextName);
@@ -358,26 +372,49 @@ function writeToContext(contextName, key, value) {
 }
 
 // src/variable.ts
-var CONTEXT_REF_REGEX = /^@([^:]+):(.+)$/;
+var CONTEXT_REF_FULL_REGEX = /^@([^:]+):(.+)$/;
+var CONTEXT_REF_SHORT_REGEX = /^@([^:]+)$/;
+var ENV_REF_REGEX = /\$([A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})/g;
 var MAX_CONTEXT_REF_DEPTH = 10;
-function resolveContextReference(raw, depth = 0) {
+function expandEnvReferences(str) {
+  return str.replace(ENV_REF_REGEX, (_, name) => {
+    const key = name.startsWith("{") ? name.slice(1, -1) : name;
+    return process.env[key] ?? "";
+  });
+}
+function resolveContextReference(raw, currentKey, 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 afterEnv = expandEnvReferences(raw);
+  let contextName;
+  let refKey;
+  const fullMatch = afterEnv.match(CONTEXT_REF_FULL_REGEX);
+  if (fullMatch) {
+    [, contextName, refKey] = fullMatch;
+  } else {
+    const shortMatch = afterEnv.match(CONTEXT_REF_SHORT_REGEX);
+    if (!shortMatch) return afterEnv;
+    contextName = shortMatch[1];
+    if (currentKey === void 0) {
+      throw new Error(
+        `Context reference @${contextName} (short form) cannot be resolved without a variable key. Use @${contextName}:<key> to specify a key.`
+      );
+    }
+    refKey = currentKey;
+  }
   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).`;
+    const displayRef = refKey === currentKey ? `@${contextName}` : `@${contextName}:${refKey}`;
+    const msg = hasContext ? `Context reference ${displayRef} could not be resolved: key "${refKey}" is not defined in context "${contextName}".` : `Context reference ${displayRef} could not be resolved: context "${contextName}" not found (no ${contextName}.context.json).`;
     log("error", msg);
     throw new Error(msg);
   }
-  return resolveContextReference(resolved, depth + 1);
+  return resolveContextReference(resolved, currentKey, depth + 1);
 }
 function defaultKeyFromName(name) {
   return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
@@ -403,7 +440,7 @@ 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}`);
-      const raw = resolveContextReference(config.set[key]);
+      const raw = resolveContextReference(config.set[key], key);
       return { raw, source: "set" };
     }
     if (!config.ignoreEnv) {
@@ -411,7 +448,7 @@ function scenv(name, options = {}) {
       const envVal = process.env[envKey];
       if (envVal !== void 0 && envVal !== "") {
         log("trace", "resolveRaw: env hit");
-        const raw = resolveContextReference(envVal);
+        const raw = resolveContextReference(envVal, key);
         return { raw, source: "env" };
       }
     }
@@ -420,7 +457,7 @@ function scenv(name, options = {}) {
       const ctx = getMergedContextValues();
       if (ctx[key] !== void 0) {
         log("trace", `resolveRaw: context hit key=${key}`);
-        const raw = resolveContextReference(ctx[key]);
+        const raw = resolveContextReference(ctx[key], key);
         return { raw, source: "context" };
       }
     }
@@ -447,7 +484,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;
+    const resolvedDefault = effectiveDefault === void 0 ? void 0 : typeof effectiveDefault === "string" ? resolveContextReference(effectiveDefault, key) : effectiveDefault;
     let wasPrompted = false;
     let value;
     let resolvedFrom;
@@ -461,7 +498,7 @@ function scenv(name, options = {}) {
       }
       const defaultForPrompt = raw !== void 0 ? raw : resolvedDefault;
       let promptedValue = await Promise.resolve(fn(name, defaultForPrompt));
-      value = typeof promptedValue === "string" ? resolveContextReference(promptedValue) : promptedValue;
+      value = typeof promptedValue === "string" ? resolveContextReference(promptedValue, key) : promptedValue;
       wasPrompted = true;
       resolvedFrom = "prompt";
     } else if (raw !== void 0) {
@@ -516,7 +553,7 @@ function scenv(name, options = {}) {
       }
       if (!doSave) return final;
       const callbacks = getCallbacks();
-      const contextNames = config.contexts ?? [];
+      const contextNames = config.context ?? [];
       let ctxToSave;
       if (config.saveContextTo === "ask") {
         if (typeof callbacks.onAskContext !== "function") {
@@ -560,10 +597,10 @@ function scenv(name, options = {}) {
       }
       contextName = await callbacks.onAskContext(
         name,
-        config.contexts ?? []
+        config.context ?? []
       );
     }
-    if (!contextName) contextName = config.contexts?.[0] ?? "default";
+    if (!contextName) contextName = config.context?.[0] ?? "default";
     writeToContext(contextName, key, String(validated.data));
     log("info", `Saved key=${key} to context ${contextName}`);
   }
@@ -577,9 +614,9 @@ function parseScenvArgs(argv) {
   while (i < argv.length) {
     const arg = argv[i];
     if (arg === "--context" && argv[i + 1] !== void 0) {
-      config.contexts = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
+      config.context = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--add-context" && argv[i + 1] !== void 0) {
-      config.addContexts = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
+      config.addContext = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--prompt" && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (["always", "never", "fallback", "no-env"].includes(v)) {
@@ -603,6 +640,8 @@ 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 === "--log-level" || arg === "--log") && argv[i + 1] !== void 0) {
       const v = argv[++i].toLowerCase();
       if (LOG_LEVELS.includes(v)) {

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "scenv",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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",