scenv 0.3.3 → 0.4.1

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  LOG_LEVELS: () => LOG_LEVELS,
   configure: () => configure,
   discoverContextPaths: () => discoverContextPaths,
   getCallbacks: () => getCallbacks,
@@ -27,6 +28,7 @@ __export(index_exports, {
   loadConfig: () => loadConfig,
   parseScenvArgs: () => parseScenvArgs,
   resetConfig: () => resetConfig,
+  resetLogState: () => resetLogState,
   scenv: () => scenv
 });
 module.exports = __toCommonJS(index_exports);
@@ -34,6 +36,7 @@ module.exports = __toCommonJS(index_exports);
 // src/config.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
+var LOG_LEVELS = ["none", "trace", "debug", "info", "warn", "error"];
 var CONFIG_FILENAME = "scenv.config.json";
 var envKeyMap = {
   SCENV_CONTEXT: "contexts",
@@ -42,7 +45,8 @@ var envKeyMap = {
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
   SCENV_SAVE_PROMPT: "savePrompt",
-  SCENV_SAVE_CONTEXT_TO: "saveContextTo"
+  SCENV_SAVE_CONTEXT_TO: "saveContextTo",
+  SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
 var programmaticCallbacks = {};
@@ -77,6 +81,9 @@ function configFromEnv() {
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
+    } else if (configKey === "logLevel") {
+      const v = val.toLowerCase();
+      if (LOG_LEVELS.includes(v)) out.logLevel = v;
     }
   }
   return out;
@@ -108,8 +115,16 @@ function loadConfigFile(configDir) {
     if (typeof parsed.saveContextTo === "string")
       out.saveContextTo = parsed.saveContextTo;
     if (typeof parsed.root === "string") out.root = parsed.root;
+    if (typeof parsed.logLevel === "string" && LOG_LEVELS.includes(parsed.logLevel))
+      out.logLevel = parsed.logLevel;
     return out;
-  } catch {
+  } catch (err) {
+    const envLevel = process.env.SCENV_LOG_LEVEL?.toLowerCase();
+    if (envLevel && envLevel !== "none" && ["trace", "debug", "info", "warn", "error"].includes(envLevel)) {
+      console.error(
+        `[scenv] error: failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     return {};
   }
 }
@@ -160,6 +175,47 @@ function resetConfig() {
   programmaticCallbacks = {};
 }
 
+// src/log.ts
+var LEVEL_NUM = {
+  none: -1,
+  trace: 0,
+  debug: 1,
+  info: 2,
+  warn: 3,
+  error: 4
+};
+function getLevelNum() {
+  const config = loadConfig();
+  const level = config.logLevel ?? "none";
+  return LEVEL_NUM[level];
+}
+var configLoadedLogged = false;
+function resetLogState() {
+  configLoadedLogged = false;
+}
+function logConfigLoaded(config) {
+  if (configLoadedLogged) return;
+  if (getLevelNum() < LEVEL_NUM.info) return;
+  configLoadedLogged = true;
+  log(
+    "info",
+    "config loaded",
+    "root=" + (config.root ?? "(cwd)"),
+    "contexts=" + JSON.stringify(config.contexts ?? [])
+  );
+}
+function log(level, msg, ...args) {
+  const configured = getLevelNum();
+  if (configured < 0) return;
+  if (LEVEL_NUM[level] < configured) return;
+  const prefix = `[scenv] ${level}:`;
+  if (args.length === 0) {
+    console.error(prefix, msg);
+  } else {
+    console.error(prefix, msg, ...args);
+  }
+}
+
 // src/context.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
@@ -191,24 +247,43 @@ function discoverContextPathsInternal(dir, found) {
 }
 function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
   discoverContextPathsInternal(dir, found);
+  log(
+    "debug",
+    "context discovery",
+    "dir=" + dir,
+    "found=" + JSON.stringify([...found.entries()].map(([n, p]) => ({ name: n, path: p })))
+  );
   return found;
 }
 function getContextValues() {
   const config = loadConfig();
+  logConfigLoaded(config);
   if (config.ignoreContext) return {};
   const root = config.root ?? process.cwd();
   const paths = discoverContextPaths(root);
   const out = {};
   for (const contextName of config.contexts ?? []) {
     const filePath = paths.get(contextName);
-    if (!filePath) continue;
+    if (!filePath) {
+      log("warn", `context "${contextName}" not found (no *.context.json)`);
+      continue;
+    }
     try {
       const raw = (0, import_node_fs2.readFileSync)(filePath, "utf-8");
       const data = JSON.parse(raw);
+      const keys = [];
       for (const [k, v] of Object.entries(data)) {
-        if (typeof v === "string") out[k] = v;
+        if (typeof v === "string") {
+          out[k] = v;
+          keys.push(k);
+        }
       }
-    } catch {
+      log("debug", `context "${contextName}" loaded keys=${JSON.stringify(keys)}`);
+    } catch (err) {
+      log(
+        "warn",
+        `context "${contextName}" unreadable or invalid JSON: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
   }
   return out;
@@ -230,6 +305,7 @@ function writeToContext(contextName, key, value) {
   } catch {
   }
   data[key] = value;
+  log("trace", "writeToContext", "path=" + path, "key=" + key);
   const dir = (0, import_node_path2.dirname)(path);
   (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
   (0, import_node_fs2.writeFileSync)(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
@@ -257,16 +333,29 @@ function scenv(name, options = {}) {
   const defaultValue = options.default;
   async function resolveRaw() {
     const config = loadConfig();
-    if (config.set?.[key] !== void 0) return config.set[key];
+    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" };
+    }
     if (!config.ignoreEnv) {
+      log("trace", `resolveRaw: checking env ${envKey}`);
       const envVal = process.env[envKey];
-      if (envVal !== void 0 && envVal !== "") return envVal;
+      if (envVal !== void 0 && envVal !== "") {
+        log("trace", "resolveRaw: env hit");
+        return { raw: envVal, source: "env" };
+      }
     }
     if (!config.ignoreContext) {
+      log("trace", "resolveRaw: checking context");
       const ctx = getContextValues();
-      if (ctx[key] !== void 0) return ctx[key];
+      if (ctx[key] !== void 0) {
+        log("trace", `resolveRaw: context hit key=${key}`);
+        return { raw: ctx[key], source: "context" };
+      }
     }
-    return void 0;
+    log("trace", "resolveRaw: no value");
+    return { raw: void 0, source: void 0 };
   }
   function shouldPrompt(config, hadValue, hadEnv) {
     const mode = config.prompt ?? "fallback";
@@ -278,13 +367,20 @@ function scenv(name, options = {}) {
   }
   async function getResolvedValue(overrides) {
     const config = loadConfig();
-    const raw = await resolveRaw();
+    logConfigLoaded(config);
+    const { raw, source } = await resolveRaw();
     const hadEnv = !config.ignoreEnv && process.env[envKey] !== void 0 && process.env[envKey] !== "";
     const hadValue = raw !== void 0;
+    const doPrompt = shouldPrompt(config, hadValue, hadEnv);
+    log(
+      "debug",
+      `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;
     let wasPrompted = false;
     let value;
-    if (shouldPrompt(config, hadValue, hadEnv)) {
+    let resolvedFrom;
+    if (doPrompt) {
       const callbacks = getCallbacks();
       const fn = overrides?.prompt ?? promptFn ?? callbacks.defaultPrompt;
       if (typeof fn !== "function") {
@@ -295,13 +391,17 @@ function scenv(name, options = {}) {
       const defaultForPrompt = raw !== void 0 ? raw : effectiveDefault;
       value = await Promise.resolve(fn(name, defaultForPrompt));
       wasPrompted = true;
+      resolvedFrom = "prompt";
     } else if (raw !== void 0) {
       value = raw;
+      resolvedFrom = source;
     } else if (effectiveDefault !== void 0) {
       value = effectiveDefault;
+      resolvedFrom = "default";
     } else {
       throw new Error(`Missing value for variable "${name}" (key: ${key})`);
     }
+    log("info", `variable "${name}" (key=${key}) resolved from ${resolvedFrom}`);
     return { value, raw, hadEnv, wasPrompted };
   }
   function validate(value) {
@@ -321,14 +421,14 @@ function scenv(name, options = {}) {
     const { value, wasPrompted } = await getResolvedValue(options2);
     const validated = validate(value);
     if (!validated.success) {
-      throw new Error(
-        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
-      );
+      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+      log("error", errMsg);
+      throw new Error(errMsg);
     }
     const final = validated.data;
     if (wasPrompted) {
       const config = loadConfig();
-      const savePrompt = config.savePrompt ?? "never";
+      const savePrompt = config.savePrompt ?? "ask";
       const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
       if (shouldAskSave) {
         const callbacks = getCallbacks();
@@ -342,7 +442,10 @@ function scenv(name, options = {}) {
           final,
           config.contexts ?? []
         );
-        if (ctxToSave) writeToContext(ctxToSave, key, String(final));
+        if (ctxToSave) {
+          writeToContext(ctxToSave, key, String(final));
+          log("info", `Saved key=${key} to context ${ctxToSave}`);
+        }
       }
     }
     return final;
@@ -359,9 +462,9 @@ function scenv(name, options = {}) {
     const toSave = value ?? (await getResolvedValue()).value;
     const validated = validate(toSave);
     if (!validated.success) {
-      throw new Error(
-        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
-      );
+      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+      log("error", errMsg);
+      throw new Error(errMsg);
     }
     const config = loadConfig();
     let contextName = config.saveContextTo;
@@ -379,6 +482,7 @@ function scenv(name, options = {}) {
     }
     if (!contextName) contextName = config.contexts?.[0] ?? "default";
     writeToContext(contextName, key, String(validated.data));
+    log("info", `Saved key=${key} to context ${contextName}`);
   }
   return { get, safeGet, save };
 }
@@ -416,6 +520,16 @@ function parseScenvArgs(argv) {
       }
     } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
       config.saveContextTo = argv[++i];
+    } else if ((arg === "--log-level" || arg === "--log") && argv[i + 1] !== void 0) {
+      const v = argv[++i].toLowerCase();
+      if (LOG_LEVELS.includes(v)) {
+        config.logLevel = v;
+      }
+    } else if (arg.startsWith("--log=")) {
+      const v = arg.slice(6).toLowerCase();
+      if (LOG_LEVELS.includes(v)) {
+        config.logLevel = v;
+      }
     } else if (arg.startsWith("--set=")) {
       const pair = arg.slice(6);
       const eq = pair.indexOf("=");
@@ -430,6 +544,7 @@ function parseScenvArgs(argv) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  LOG_LEVELS,
   configure,
   discoverContextPaths,
   getCallbacks,
@@ -437,5 +552,6 @@ function parseScenvArgs(argv) {
   loadConfig,
   parseScenvArgs,
   resetConfig,
+  resetLogState,
   scenv
 });

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 type PromptMode = "always" | "never" | "fallback" | "no-env";
 type SavePromptMode = "always" | "never" | "ask";
+declare const LOG_LEVELS: readonly ["none", "trace", "debug", "info", "warn", "error"];
+type LogLevel = (typeof LOG_LEVELS)[number];
 interface ScenvConfig {
     /** Replace all contexts with this list (CLI: --context a,b,c) */
     contexts?: string[];
@@ -19,6 +21,8 @@ interface ScenvConfig {
     saveContextTo?: "ask" | string;
     /** Root directory for config/context search (default: cwd) */
     root?: string;
+    /** Log level: none (default), trace, debug, info, warn, error */
+    logLevel?: LogLevel;
 }
 /** (name, defaultValue) => value; used when a variable has no prompt option. Overridable per variable. */
 type DefaultPromptFn = (name: string, defaultValue: unknown) => unknown | Promise<unknown>;
@@ -46,6 +50,9 @@ declare function configure(partial: Partial<ScenvConfig> & {
  */
 declare function resetConfig(): void;
 
+/** Reset internal log state (e.g. config-loaded guard). Useful in tests after resetConfig(). */
+declare function resetLogState(): void;
+
 /**
  * Recursively find all *.context.json files under dir. Returns map: contextName -> absolute path (first found wins).
  */
@@ -93,8 +100,8 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
 /**
  * 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
+ * --set key=value --save-prompt ask --save-context-to prod --log-level trace
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type GetOptions, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, scenv };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 type PromptMode = "always" | "never" | "fallback" | "no-env";
 type SavePromptMode = "always" | "never" | "ask";
+declare const LOG_LEVELS: readonly ["none", "trace", "debug", "info", "warn", "error"];
+type LogLevel = (typeof LOG_LEVELS)[number];
 interface ScenvConfig {
     /** Replace all contexts with this list (CLI: --context a,b,c) */
     contexts?: string[];
@@ -19,6 +21,8 @@ interface ScenvConfig {
     saveContextTo?: "ask" | string;
     /** Root directory for config/context search (default: cwd) */
     root?: string;
+    /** Log level: none (default), trace, debug, info, warn, error */
+    logLevel?: LogLevel;
 }
 /** (name, defaultValue) => value; used when a variable has no prompt option. Overridable per variable. */
 type DefaultPromptFn = (name: string, defaultValue: unknown) => unknown | Promise<unknown>;
@@ -46,6 +50,9 @@ declare function configure(partial: Partial<ScenvConfig> & {
  */
 declare function resetConfig(): void;
 
+/** Reset internal log state (e.g. config-loaded guard). Useful in tests after resetConfig(). */
+declare function resetLogState(): void;
+
 /**
  * Recursively find all *.context.json files under dir. Returns map: contextName -> absolute path (first found wins).
  */
@@ -93,8 +100,8 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
 /**
  * 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
+ * --set key=value --save-prompt ask --save-context-to prod --log-level trace
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type GetOptions, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, scenv };
+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 };

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/config.ts
 import { readFileSync, existsSync } from "fs";
 import { dirname, join } from "path";
+var LOG_LEVELS = ["none", "trace", "debug", "info", "warn", "error"];
 var CONFIG_FILENAME = "scenv.config.json";
 var envKeyMap = {
   SCENV_CONTEXT: "contexts",
@@ -9,7 +10,8 @@ var envKeyMap = {
   SCENV_IGNORE_ENV: "ignoreEnv",
   SCENV_IGNORE_CONTEXT: "ignoreContext",
   SCENV_SAVE_PROMPT: "savePrompt",
-  SCENV_SAVE_CONTEXT_TO: "saveContextTo"
+  SCENV_SAVE_CONTEXT_TO: "saveContextTo",
+  SCENV_LOG_LEVEL: "logLevel"
 };
 var programmaticConfig = {};
 var programmaticCallbacks = {};
@@ -44,6 +46,9 @@ function configFromEnv() {
         out[configKey] = v;
     } else if (configKey === "saveContextTo") {
       out.saveContextTo = val;
+    } else if (configKey === "logLevel") {
+      const v = val.toLowerCase();
+      if (LOG_LEVELS.includes(v)) out.logLevel = v;
     }
   }
   return out;
@@ -75,8 +80,16 @@ function loadConfigFile(configDir) {
     if (typeof parsed.saveContextTo === "string")
       out.saveContextTo = parsed.saveContextTo;
     if (typeof parsed.root === "string") out.root = parsed.root;
+    if (typeof parsed.logLevel === "string" && LOG_LEVELS.includes(parsed.logLevel))
+      out.logLevel = parsed.logLevel;
     return out;
-  } catch {
+  } catch (err) {
+    const envLevel = process.env.SCENV_LOG_LEVEL?.toLowerCase();
+    if (envLevel && envLevel !== "none" && ["trace", "debug", "info", "warn", "error"].includes(envLevel)) {
+      console.error(
+        `[scenv] error: failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     return {};
   }
 }
@@ -127,6 +140,47 @@ function resetConfig() {
   programmaticCallbacks = {};
 }
 
+// src/log.ts
+var LEVEL_NUM = {
+  none: -1,
+  trace: 0,
+  debug: 1,
+  info: 2,
+  warn: 3,
+  error: 4
+};
+function getLevelNum() {
+  const config = loadConfig();
+  const level = config.logLevel ?? "none";
+  return LEVEL_NUM[level];
+}
+var configLoadedLogged = false;
+function resetLogState() {
+  configLoadedLogged = false;
+}
+function logConfigLoaded(config) {
+  if (configLoadedLogged) return;
+  if (getLevelNum() < LEVEL_NUM.info) return;
+  configLoadedLogged = true;
+  log(
+    "info",
+    "config loaded",
+    "root=" + (config.root ?? "(cwd)"),
+    "contexts=" + JSON.stringify(config.contexts ?? [])
+  );
+}
+function log(level, msg, ...args) {
+  const configured = getLevelNum();
+  if (configured < 0) return;
+  if (LEVEL_NUM[level] < configured) return;
+  const prefix = `[scenv] ${level}:`;
+  if (args.length === 0) {
+    console.error(prefix, msg);
+  } else {
+    console.error(prefix, msg, ...args);
+  }
+}
+
 // src/context.ts
 import {
   readFileSync as readFileSync2,
@@ -164,24 +218,43 @@ function discoverContextPathsInternal(dir, found) {
 }
 function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
   discoverContextPathsInternal(dir, found);
+  log(
+    "debug",
+    "context discovery",
+    "dir=" + dir,
+    "found=" + JSON.stringify([...found.entries()].map(([n, p]) => ({ name: n, path: p })))
+  );
   return found;
 }
 function getContextValues() {
   const config = loadConfig();
+  logConfigLoaded(config);
   if (config.ignoreContext) return {};
   const root = config.root ?? process.cwd();
   const paths = discoverContextPaths(root);
   const out = {};
   for (const contextName of config.contexts ?? []) {
     const filePath = paths.get(contextName);
-    if (!filePath) continue;
+    if (!filePath) {
+      log("warn", `context "${contextName}" not found (no *.context.json)`);
+      continue;
+    }
     try {
       const raw = readFileSync2(filePath, "utf-8");
       const data = JSON.parse(raw);
+      const keys = [];
       for (const [k, v] of Object.entries(data)) {
-        if (typeof v === "string") out[k] = v;
+        if (typeof v === "string") {
+          out[k] = v;
+          keys.push(k);
+        }
       }
-    } catch {
+      log("debug", `context "${contextName}" loaded keys=${JSON.stringify(keys)}`);
+    } catch (err) {
+      log(
+        "warn",
+        `context "${contextName}" unreadable or invalid JSON: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
   }
   return out;
@@ -203,6 +276,7 @@ function writeToContext(contextName, key, value) {
   } catch {
   }
   data[key] = value;
+  log("trace", "writeToContext", "path=" + path, "key=" + key);
   const dir = dirname2(path);
   mkdirSync(dir, { recursive: true });
   writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
@@ -230,16 +304,29 @@ function scenv(name, options = {}) {
   const defaultValue = options.default;
   async function resolveRaw() {
     const config = loadConfig();
-    if (config.set?.[key] !== void 0) return config.set[key];
+    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" };
+    }
     if (!config.ignoreEnv) {
+      log("trace", `resolveRaw: checking env ${envKey}`);
       const envVal = process.env[envKey];
-      if (envVal !== void 0 && envVal !== "") return envVal;
+      if (envVal !== void 0 && envVal !== "") {
+        log("trace", "resolveRaw: env hit");
+        return { raw: envVal, source: "env" };
+      }
     }
     if (!config.ignoreContext) {
+      log("trace", "resolveRaw: checking context");
       const ctx = getContextValues();
-      if (ctx[key] !== void 0) return ctx[key];
+      if (ctx[key] !== void 0) {
+        log("trace", `resolveRaw: context hit key=${key}`);
+        return { raw: ctx[key], source: "context" };
+      }
     }
-    return void 0;
+    log("trace", "resolveRaw: no value");
+    return { raw: void 0, source: void 0 };
   }
   function shouldPrompt(config, hadValue, hadEnv) {
     const mode = config.prompt ?? "fallback";
@@ -251,13 +338,20 @@ function scenv(name, options = {}) {
   }
   async function getResolvedValue(overrides) {
     const config = loadConfig();
-    const raw = await resolveRaw();
+    logConfigLoaded(config);
+    const { raw, source } = await resolveRaw();
     const hadEnv = !config.ignoreEnv && process.env[envKey] !== void 0 && process.env[envKey] !== "";
     const hadValue = raw !== void 0;
+    const doPrompt = shouldPrompt(config, hadValue, hadEnv);
+    log(
+      "debug",
+      `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;
     let wasPrompted = false;
     let value;
-    if (shouldPrompt(config, hadValue, hadEnv)) {
+    let resolvedFrom;
+    if (doPrompt) {
       const callbacks = getCallbacks();
       const fn = overrides?.prompt ?? promptFn ?? callbacks.defaultPrompt;
       if (typeof fn !== "function") {
@@ -268,13 +362,17 @@ function scenv(name, options = {}) {
       const defaultForPrompt = raw !== void 0 ? raw : effectiveDefault;
       value = await Promise.resolve(fn(name, defaultForPrompt));
       wasPrompted = true;
+      resolvedFrom = "prompt";
     } else if (raw !== void 0) {
       value = raw;
+      resolvedFrom = source;
     } else if (effectiveDefault !== void 0) {
       value = effectiveDefault;
+      resolvedFrom = "default";
     } else {
       throw new Error(`Missing value for variable "${name}" (key: ${key})`);
     }
+    log("info", `variable "${name}" (key=${key}) resolved from ${resolvedFrom}`);
     return { value, raw, hadEnv, wasPrompted };
   }
   function validate(value) {
@@ -294,14 +392,14 @@ function scenv(name, options = {}) {
     const { value, wasPrompted } = await getResolvedValue(options2);
     const validated = validate(value);
     if (!validated.success) {
-      throw new Error(
-        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
-      );
+      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+      log("error", errMsg);
+      throw new Error(errMsg);
     }
     const final = validated.data;
     if (wasPrompted) {
       const config = loadConfig();
-      const savePrompt = config.savePrompt ?? "never";
+      const savePrompt = config.savePrompt ?? "ask";
       const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
       if (shouldAskSave) {
         const callbacks = getCallbacks();
@@ -315,7 +413,10 @@ function scenv(name, options = {}) {
           final,
           config.contexts ?? []
         );
-        if (ctxToSave) writeToContext(ctxToSave, key, String(final));
+        if (ctxToSave) {
+          writeToContext(ctxToSave, key, String(final));
+          log("info", `Saved key=${key} to context ${ctxToSave}`);
+        }
       }
     }
     return final;
@@ -332,9 +433,9 @@ function scenv(name, options = {}) {
     const toSave = value ?? (await getResolvedValue()).value;
     const validated = validate(toSave);
     if (!validated.success) {
-      throw new Error(
-        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
-      );
+      const errMsg = `Validation failed for "${name}": ${validated.error ?? "unknown"}`;
+      log("error", errMsg);
+      throw new Error(errMsg);
     }
     const config = loadConfig();
     let contextName = config.saveContextTo;
@@ -352,6 +453,7 @@ function scenv(name, options = {}) {
     }
     if (!contextName) contextName = config.contexts?.[0] ?? "default";
     writeToContext(contextName, key, String(validated.data));
+    log("info", `Saved key=${key} to context ${contextName}`);
   }
   return { get, safeGet, save };
 }
@@ -389,6 +491,16 @@ function parseScenvArgs(argv) {
       }
     } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
       config.saveContextTo = argv[++i];
+    } else if ((arg === "--log-level" || arg === "--log") && argv[i + 1] !== void 0) {
+      const v = argv[++i].toLowerCase();
+      if (LOG_LEVELS.includes(v)) {
+        config.logLevel = v;
+      }
+    } else if (arg.startsWith("--log=")) {
+      const v = arg.slice(6).toLowerCase();
+      if (LOG_LEVELS.includes(v)) {
+        config.logLevel = v;
+      }
     } else if (arg.startsWith("--set=")) {
       const pair = arg.slice(6);
       const eq = pair.indexOf("=");
@@ -402,6 +514,7 @@ function parseScenvArgs(argv) {
   return config;
 }
 export {
+  LOG_LEVELS,
   configure,
   discoverContextPaths,
   getCallbacks,
@@ -409,5 +522,6 @@ export {
   loadConfig,
   parseScenvArgs,
   resetConfig,
+  resetLogState,
   scenv
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenv",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Environment and context variables with runtime-configurable resolution",
   "repository": { "type": "git", "url": "https://github.com/PKWadsy/scenv" },
   "publishConfig": { "access": "public", "provenance": true },