scenv 0.1.0

package/dist/index.cjs

@@ -0,0 +1,451 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  configure: () => configure,
+  discoverContextPaths: () => discoverContextPaths,
+  getCallbacks: () => getCallbacks,
+  getContextValues: () => getContextValues,
+  loadConfig: () => loadConfig,
+  parseSenvArgs: () => parseSenvArgs,
+  resetConfig: () => resetConfig,
+  senv: () => senv
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var CONFIG_FILENAME = "senv.config.json";
+var envKeyMap = {
+  SENV_CONTEXT: "contexts",
+  SENV_ADD_CONTEXTS: "addContexts",
+  SENV_PROMPT: "prompt",
+  SENV_IGNORE_ENV: "ignoreEnv",
+  SENV_IGNORE_CONTEXT: "ignoreContext",
+  SENV_SAVE_PROMPT: "savePrompt",
+  SENV_SAVE_CONTEXT_TO: "saveContextTo"
+};
+var programmaticConfig = {};
+var programmaticCallbacks = {};
+function getCallbacks() {
+  return { ...programmaticCallbacks };
+}
+function findConfigDir(startDir) {
+  let dir = startDir;
+  const root = (0, import_node_path.dirname)(dir);
+  for (; ; ) {
+    const candidate = (0, import_node_path.join)(dir, CONFIG_FILENAME);
+    if ((0, import_node_fs.existsSync)(candidate)) return dir;
+    if (dir === root) break;
+    dir = (0, import_node_path.dirname)(dir);
+  }
+  return null;
+}
+function configFromEnv() {
+  const out = {};
+  for (const [envKey, configKey] of Object.entries(envKeyMap)) {
+    const val = process.env[envKey];
+    if (val === void 0 || val === "") continue;
+    if (configKey === "contexts" || configKey === "addContexts") {
+      out[configKey] = val.split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (configKey === "ignoreEnv" || configKey === "ignoreContext") {
+      out[configKey] = val === "1" || val === "true" || val.toLowerCase() === "yes";
+    } else if (configKey === "prompt" || configKey === "savePrompt") {
+      const v = val.toLowerCase();
+      if (configKey === "prompt" && (v === "always" || v === "never" || v === "fallback" || v === "no-env"))
+        out[configKey] = v;
+      if (configKey === "savePrompt" && (v === "always" || v === "never" || v === "ask"))
+        out[configKey] = v;
+    } else if (configKey === "saveContextTo") {
+      out.saveContextTo = val;
+    }
+  }
+  return out;
+}
+function loadConfigFile(configDir) {
+  const path = (0, import_node_path.join)(configDir, CONFIG_FILENAME);
+  if (!(0, import_node_fs.existsSync)(path)) return {};
+  try {
+    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(
+        (x) => typeof x === "string"
+      );
+    if (Array.isArray(parsed.addContexts))
+      out.addContexts = parsed.addContexts.filter(
+        (x) => typeof x === "string"
+      );
+    if (typeof parsed.prompt === "string" && ["always", "never", "fallback", "no-env"].includes(parsed.prompt))
+      out.prompt = parsed.prompt;
+    if (typeof parsed.ignoreEnv === "boolean") out.ignoreEnv = parsed.ignoreEnv;
+    if (typeof parsed.ignoreContext === "boolean")
+      out.ignoreContext = parsed.ignoreContext;
+    if (parsed.set && typeof parsed.set === "object" && !Array.isArray(parsed.set))
+      out.set = parsed.set;
+    if (typeof parsed.savePrompt === "string" && ["always", "never", "ask"].includes(parsed.savePrompt))
+      out.savePrompt = parsed.savePrompt;
+    if (typeof parsed.saveContextTo === "string")
+      out.saveContextTo = parsed.saveContextTo;
+    if (typeof parsed.root === "string") out.root = parsed.root;
+    return out;
+  } catch {
+    return {};
+  }
+}
+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 replace = fromProgReplace ?? fromEnvReplace;
+  if (replace !== void 0) return replace;
+  const base = [...fromFile];
+  const add = [...fromEnvAdd, ...fromProgAdd];
+  const seen = new Set(base);
+  for (const c of add) {
+    if (!seen.has(c)) {
+      seen.add(c);
+      base.push(c);
+    }
+  }
+  return base;
+}
+function loadConfig(root) {
+  const startDir = root ?? programmaticConfig.root ?? process.cwd();
+  const configDir = findConfigDir(startDir);
+  const fileConfig = configDir ? loadConfigFile(configDir) : {};
+  const envConfig = configFromEnv();
+  const merged = {
+    ...fileConfig,
+    ...envConfig,
+    ...programmaticConfig
+  };
+  merged.contexts = mergeContexts(fileConfig, envConfig, programmaticConfig);
+  delete merged.addContexts;
+  if (configDir && !merged.root) merged.root = configDir;
+  else if (!merged.root) merged.root = startDir;
+  return merged;
+}
+function configure(partial) {
+  const { callbacks, ...configPartial } = partial;
+  programmaticConfig = { ...programmaticConfig, ...configPartial };
+  if (callbacks) {
+    programmaticCallbacks = { ...programmaticCallbacks, ...callbacks };
+  }
+}
+function resetConfig() {
+  programmaticConfig = {};
+  programmaticCallbacks = {};
+}
+
+// src/context.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var CONTEXT_SUFFIX = ".context.json";
+function discoverContextPathsInternal(dir, found) {
+  let entries;
+  try {
+    entries = (0, import_node_fs2.readdirSync)(dir, { withFileTypes: true }).map((d) => ({
+      name: d.name,
+      path: (0, import_node_path2.join)(dir, d.name)
+    }));
+  } catch {
+    return;
+  }
+  for (const { name, path } of entries) {
+    if (name.endsWith(CONTEXT_SUFFIX) && !name.startsWith(".")) {
+      const contextName = name.slice(0, -CONTEXT_SUFFIX.length);
+      if (!found.has(contextName)) found.set(contextName, path);
+    }
+  }
+  for (const { name, path } of entries) {
+    if (name === "." || name === "..") continue;
+    try {
+      if ((0, import_node_fs2.statSync)(path).isDirectory())
+        discoverContextPathsInternal(path, found);
+    } catch {
+    }
+  }
+}
+function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
+  discoverContextPathsInternal(dir, found);
+  return found;
+}
+function getContextValues() {
+  const config = loadConfig();
+  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;
+    try {
+      const raw = (0, import_node_fs2.readFileSync)(filePath, "utf-8");
+      const data = JSON.parse(raw);
+      for (const [k, v] of Object.entries(data)) {
+        if (typeof v === "string") out[k] = v;
+      }
+    } catch {
+    }
+  }
+  return out;
+}
+function getContextWritePath(contextName) {
+  const config = loadConfig();
+  const root = config.root ?? process.cwd();
+  const paths = discoverContextPaths(root);
+  const existing = paths.get(contextName);
+  if (existing) return existing;
+  return (0, import_node_path2.join)(root, `${contextName}${CONTEXT_SUFFIX}`);
+}
+function writeToContext(contextName, key, value) {
+  const path = getContextWritePath(contextName);
+  let data = {};
+  try {
+    const raw = (0, import_node_fs2.readFileSync)(path, "utf-8");
+    data = JSON.parse(raw);
+  } catch {
+  }
+  data[key] = value;
+  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");
+}
+
+// src/prompt-default.ts
+var import_node_readline = require("readline");
+function defaultPrompt(name, defaultValue) {
+  const defaultStr = defaultValue !== void 0 && defaultValue !== null ? String(defaultValue) : "";
+  const message = defaultStr ? `Enter ${name} [${defaultStr}]: ` : `Enter ${name}: `;
+  const rl = (0, import_node_readline.createInterface)({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve, reject) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      const value = trimmed !== "" ? trimmed : defaultStr;
+      resolve(value);
+    });
+    rl.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+  });
+}
+
+// src/variable.ts
+function defaultKeyFromName(name) {
+  return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
+}
+function defaultEnvFromKey(key) {
+  return key.toUpperCase().replace(/-/g, "_");
+}
+function normalizeValidatorResult(result) {
+  if (typeof result === "boolean") {
+    return result ? { success: true } : { success: false };
+  }
+  if (result.success === true) return result;
+  return result;
+}
+function senv(name, options = {}) {
+  const key = options.key ?? defaultKeyFromName(name);
+  const envKey = options.env ?? defaultEnvFromKey(key);
+  const validator = options.validator;
+  const promptFn = options.prompt;
+  const defaultValue = options.default;
+  async function resolveRaw() {
+    const config = loadConfig();
+    if (config.set?.[key] !== void 0) return config.set[key];
+    if (!config.ignoreEnv) {
+      const envVal = process.env[envKey];
+      if (envVal !== void 0 && envVal !== "") return envVal;
+    }
+    if (!config.ignoreContext) {
+      const ctx = getContextValues();
+      if (ctx[key] !== void 0) return ctx[key];
+    }
+    if (defaultValue !== void 0) {
+      return String(defaultValue);
+    }
+    return void 0;
+  }
+  function shouldPrompt(config, hadValue, hadEnv) {
+    const mode = config.prompt ?? "fallback";
+    if (mode === "never") return false;
+    if (mode === "always") return true;
+    if (mode === "fallback") return !hadValue;
+    if (mode === "no-env") return !hadEnv;
+    return false;
+  }
+  async function getResolvedValue() {
+    const config = loadConfig();
+    const raw = await resolveRaw();
+    const hadEnv = !config.ignoreEnv && process.env[envKey] !== void 0 && process.env[envKey] !== "";
+    const hadValue = raw !== void 0;
+    let wasPrompted = false;
+    let value;
+    if (shouldPrompt(config, hadValue, hadEnv)) {
+      const defaultForPrompt = raw !== void 0 ? raw : defaultValue;
+      const fn = promptFn ?? defaultPrompt;
+      value = await Promise.resolve(fn(name, defaultForPrompt));
+      wasPrompted = true;
+    } else if (raw !== void 0) {
+      value = raw;
+    } else if (defaultValue !== void 0) {
+      value = defaultValue;
+    } else {
+      throw new Error(`Missing value for variable "${name}" (key: ${key})`);
+    }
+    return { value, raw, hadEnv, wasPrompted };
+  }
+  function validate(value) {
+    if (!validator) return { success: true, data: value };
+    const result = validator(value);
+    const normalized = normalizeValidatorResult(result);
+    if (normalized.success) {
+      const data = "data" in normalized && normalized.data !== void 0 ? normalized.data : value;
+      return { success: true, data };
+    }
+    return {
+      success: false,
+      error: "error" in normalized ? normalized.error : void 0
+    };
+  }
+  async function get() {
+    const { value, wasPrompted } = await getResolvedValue();
+    const validated = validate(value);
+    if (!validated.success) {
+      throw new Error(
+        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
+      );
+    }
+    const final = validated.data;
+    if (wasPrompted) {
+      const config = loadConfig();
+      const savePrompt = config.savePrompt ?? "never";
+      const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
+      if (shouldAskSave) {
+        const callbacks = getCallbacks();
+        const ctxToSave = callbacks.onAskSaveAfterPrompt && await callbacks.onAskSaveAfterPrompt(
+          name,
+          final,
+          config.contexts ?? []
+        );
+        if (ctxToSave) writeToContext(ctxToSave, key, String(final));
+      }
+    }
+    return final;
+  }
+  async function safeGet() {
+    try {
+      const v = await get();
+      return { success: true, value: v };
+    } catch (err) {
+      return { success: false, error: err };
+    }
+  }
+  async function save(value) {
+    const toSave = value ?? (await getResolvedValue()).value;
+    const validated = validate(toSave);
+    if (!validated.success) {
+      throw new Error(
+        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
+      );
+    }
+    const config = loadConfig();
+    let contextName = config.saveContextTo;
+    if (contextName === "ask") {
+      const callbacks = getCallbacks();
+      if (typeof callbacks.onAskContext === "function") {
+        contextName = await callbacks.onAskContext(
+          name,
+          config.contexts ?? []
+        );
+      } else {
+        contextName = config.contexts?.[0] ?? "default";
+      }
+    }
+    if (!contextName) contextName = config.contexts?.[0] ?? "default";
+    writeToContext(contextName, key, String(validated.data));
+  }
+  return { get, safeGet, save };
+}
+
+// src/cli-args.ts
+function parseSenvArgs(argv) {
+  const config = {};
+  let i = 0;
+  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);
+    } else if (arg === "--add-context" && argv[i + 1] !== void 0) {
+      config.addContexts = 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)) {
+        config.prompt = v;
+      }
+    } else if (arg === "--ignore-env") {
+      config.ignoreEnv = true;
+    } else if (arg === "--ignore-context") {
+      config.ignoreContext = true;
+    } else if (arg === "--set" && argv[i + 1] !== void 0) {
+      const pair = argv[++i];
+      const eq = pair.indexOf("=");
+      if (eq > 0) {
+        config.set = config.set ?? {};
+        config.set[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+      }
+    } else if (arg === "--save-prompt" && argv[i + 1] !== void 0) {
+      const v = argv[++i].toLowerCase();
+      if (["always", "never", "ask"].includes(v)) {
+        config.savePrompt = v;
+      }
+    } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
+      config.saveContextTo = argv[++i];
+    } else if (arg.startsWith("--set=")) {
+      const pair = arg.slice(6);
+      const eq = pair.indexOf("=");
+      if (eq > 0) {
+        config.set = config.set ?? {};
+        config.set[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+      }
+    }
+    i++;
+  }
+  return config;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  configure,
+  discoverContextPaths,
+  getCallbacks,
+  getContextValues,
+  loadConfig,
+  parseSenvArgs,
+  resetConfig,
+  senv
+});

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+type PromptMode = "always" | "never" | "fallback" | "no-env";
+type SavePromptMode = "always" | "never" | "ask";
+interface SenvConfig {
+    /** Replace all contexts with this list (CLI: --context a,b,c) */
+    contexts?: string[];
+    /** Merge these contexts with existing (CLI: --add-context a,b,c) */
+    addContexts?: string[];
+    /** When to prompt for variable value */
+    prompt?: PromptMode;
+    /** Ignore environment variables during resolution */
+    ignoreEnv?: boolean;
+    /** Ignore loaded context during resolution */
+    ignoreContext?: boolean;
+    /** Override values: key -> string (CLI: --set key=val) */
+    set?: Record<string, string>;
+    /** When to ask "save for next time?" */
+    savePrompt?: SavePromptMode;
+    /** Where to save: context name or "ask" */
+    saveContextTo?: "ask" | string;
+    /** Root directory for config/context search (default: cwd) */
+    root?: string;
+}
+interface SenvCallbacks {
+    /** When user was just prompted for a value and savePrompt is ask/always: (variableName, value, contextNames) => context name to save to, or null to skip */
+    onAskSaveAfterPrompt?: (name: string, value: unknown, contextNames: string[]) => Promise<string | null>;
+    /** When saveContextTo is "ask": (variableName, contextNames) => context name to save to */
+    onAskContext?: (name: string, contextNames: string[]) => Promise<string>;
+}
+declare function getCallbacks(): SenvCallbacks;
+/**
+ * Load full config: file (from root or cwd) <- env <- programmatic. Precedence: programmatic > env > file.
+ */
+declare function loadConfig(root?: string): SenvConfig;
+/**
+ * Set programmatic config (e.g. from CLI flags). Merged on top of env and file in loadConfig().
+ */
+declare function configure(partial: Partial<SenvConfig> & {
+    callbacks?: SenvCallbacks;
+}): void;
+/**
+ * Reset programmatic config (mainly for tests).
+ */
+declare function resetConfig(): void;
+
+/**
+ * Recursively find all *.context.json files under dir. Returns map: contextName -> absolute path (first found wins).
+ */
+declare function discoverContextPaths(dir: string, found?: Map<string, string>): Map<string, string>;
+/**
+ * Load context files in the order of config.contexts; merge into one flat map (later context overwrites earlier for same key).
+ */
+declare function getContextValues(): Record<string, string>;
+
+type ValidatorResult<T> = boolean | {
+    success: true;
+    data?: T;
+} | {
+    success: false;
+    error?: unknown;
+};
+type PromptFn<T> = (name: string, defaultValue: T) => T | Promise<T>;
+interface SenvVariableOptions<T> {
+    key?: string;
+    env?: string;
+    default?: T;
+    validator?: (val: T) => ValidatorResult<T>;
+    prompt?: PromptFn<T>;
+}
+interface SenvVariable<T> {
+    get(): Promise<T>;
+    safeGet(): Promise<{
+        success: true;
+        value: T;
+    } | {
+        success: false;
+        error?: unknown;
+    }>;
+    save(value?: T): Promise<void>;
+}
+declare function senv<T>(name: string, options?: SenvVariableOptions<T>): SenvVariable<T>;
+
+/**
+ * Parse argv (e.g. process.argv.slice(2)) into SenvConfig 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
+ */
+declare function parseSenvArgs(argv: string[]): Partial<SenvConfig>;
+
+export { type PromptMode, type SavePromptMode, type SenvCallbacks, type SenvConfig, type SenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseSenvArgs, resetConfig, senv };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+type PromptMode = "always" | "never" | "fallback" | "no-env";
+type SavePromptMode = "always" | "never" | "ask";
+interface SenvConfig {
+    /** Replace all contexts with this list (CLI: --context a,b,c) */
+    contexts?: string[];
+    /** Merge these contexts with existing (CLI: --add-context a,b,c) */
+    addContexts?: string[];
+    /** When to prompt for variable value */
+    prompt?: PromptMode;
+    /** Ignore environment variables during resolution */
+    ignoreEnv?: boolean;
+    /** Ignore loaded context during resolution */
+    ignoreContext?: boolean;
+    /** Override values: key -> string (CLI: --set key=val) */
+    set?: Record<string, string>;
+    /** When to ask "save for next time?" */
+    savePrompt?: SavePromptMode;
+    /** Where to save: context name or "ask" */
+    saveContextTo?: "ask" | string;
+    /** Root directory for config/context search (default: cwd) */
+    root?: string;
+}
+interface SenvCallbacks {
+    /** When user was just prompted for a value and savePrompt is ask/always: (variableName, value, contextNames) => context name to save to, or null to skip */
+    onAskSaveAfterPrompt?: (name: string, value: unknown, contextNames: string[]) => Promise<string | null>;
+    /** When saveContextTo is "ask": (variableName, contextNames) => context name to save to */
+    onAskContext?: (name: string, contextNames: string[]) => Promise<string>;
+}
+declare function getCallbacks(): SenvCallbacks;
+/**
+ * Load full config: file (from root or cwd) <- env <- programmatic. Precedence: programmatic > env > file.
+ */
+declare function loadConfig(root?: string): SenvConfig;
+/**
+ * Set programmatic config (e.g. from CLI flags). Merged on top of env and file in loadConfig().
+ */
+declare function configure(partial: Partial<SenvConfig> & {
+    callbacks?: SenvCallbacks;
+}): void;
+/**
+ * Reset programmatic config (mainly for tests).
+ */
+declare function resetConfig(): void;
+
+/**
+ * Recursively find all *.context.json files under dir. Returns map: contextName -> absolute path (first found wins).
+ */
+declare function discoverContextPaths(dir: string, found?: Map<string, string>): Map<string, string>;
+/**
+ * Load context files in the order of config.contexts; merge into one flat map (later context overwrites earlier for same key).
+ */
+declare function getContextValues(): Record<string, string>;
+
+type ValidatorResult<T> = boolean | {
+    success: true;
+    data?: T;
+} | {
+    success: false;
+    error?: unknown;
+};
+type PromptFn<T> = (name: string, defaultValue: T) => T | Promise<T>;
+interface SenvVariableOptions<T> {
+    key?: string;
+    env?: string;
+    default?: T;
+    validator?: (val: T) => ValidatorResult<T>;
+    prompt?: PromptFn<T>;
+}
+interface SenvVariable<T> {
+    get(): Promise<T>;
+    safeGet(): Promise<{
+        success: true;
+        value: T;
+    } | {
+        success: false;
+        error?: unknown;
+    }>;
+    save(value?: T): Promise<void>;
+}
+declare function senv<T>(name: string, options?: SenvVariableOptions<T>): SenvVariable<T>;
+
+/**
+ * Parse argv (e.g. process.argv.slice(2)) into SenvConfig 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
+ */
+declare function parseSenvArgs(argv: string[]): Partial<SenvConfig>;
+
+export { type PromptMode, type SavePromptMode, type SenvCallbacks, type SenvConfig, type SenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseSenvArgs, resetConfig, senv };

package/dist/index.js

@@ -0,0 +1,423 @@
+// src/config.ts
+import { readFileSync, existsSync } from "fs";
+import { dirname, join } from "path";
+var CONFIG_FILENAME = "senv.config.json";
+var envKeyMap = {
+  SENV_CONTEXT: "contexts",
+  SENV_ADD_CONTEXTS: "addContexts",
+  SENV_PROMPT: "prompt",
+  SENV_IGNORE_ENV: "ignoreEnv",
+  SENV_IGNORE_CONTEXT: "ignoreContext",
+  SENV_SAVE_PROMPT: "savePrompt",
+  SENV_SAVE_CONTEXT_TO: "saveContextTo"
+};
+var programmaticConfig = {};
+var programmaticCallbacks = {};
+function getCallbacks() {
+  return { ...programmaticCallbacks };
+}
+function findConfigDir(startDir) {
+  let dir = startDir;
+  const root = dirname(dir);
+  for (; ; ) {
+    const candidate = join(dir, CONFIG_FILENAME);
+    if (existsSync(candidate)) return dir;
+    if (dir === root) break;
+    dir = dirname(dir);
+  }
+  return null;
+}
+function configFromEnv() {
+  const out = {};
+  for (const [envKey, configKey] of Object.entries(envKeyMap)) {
+    const val = process.env[envKey];
+    if (val === void 0 || val === "") continue;
+    if (configKey === "contexts" || configKey === "addContexts") {
+      out[configKey] = val.split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (configKey === "ignoreEnv" || configKey === "ignoreContext") {
+      out[configKey] = val === "1" || val === "true" || val.toLowerCase() === "yes";
+    } else if (configKey === "prompt" || configKey === "savePrompt") {
+      const v = val.toLowerCase();
+      if (configKey === "prompt" && (v === "always" || v === "never" || v === "fallback" || v === "no-env"))
+        out[configKey] = v;
+      if (configKey === "savePrompt" && (v === "always" || v === "never" || v === "ask"))
+        out[configKey] = v;
+    } else if (configKey === "saveContextTo") {
+      out.saveContextTo = val;
+    }
+  }
+  return out;
+}
+function loadConfigFile(configDir) {
+  const path = join(configDir, CONFIG_FILENAME);
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    const out = {};
+    if (Array.isArray(parsed.contexts))
+      out.contexts = parsed.contexts.filter(
+        (x) => typeof x === "string"
+      );
+    if (Array.isArray(parsed.addContexts))
+      out.addContexts = parsed.addContexts.filter(
+        (x) => typeof x === "string"
+      );
+    if (typeof parsed.prompt === "string" && ["always", "never", "fallback", "no-env"].includes(parsed.prompt))
+      out.prompt = parsed.prompt;
+    if (typeof parsed.ignoreEnv === "boolean") out.ignoreEnv = parsed.ignoreEnv;
+    if (typeof parsed.ignoreContext === "boolean")
+      out.ignoreContext = parsed.ignoreContext;
+    if (parsed.set && typeof parsed.set === "object" && !Array.isArray(parsed.set))
+      out.set = parsed.set;
+    if (typeof parsed.savePrompt === "string" && ["always", "never", "ask"].includes(parsed.savePrompt))
+      out.savePrompt = parsed.savePrompt;
+    if (typeof parsed.saveContextTo === "string")
+      out.saveContextTo = parsed.saveContextTo;
+    if (typeof parsed.root === "string") out.root = parsed.root;
+    return out;
+  } catch {
+    return {};
+  }
+}
+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 replace = fromProgReplace ?? fromEnvReplace;
+  if (replace !== void 0) return replace;
+  const base = [...fromFile];
+  const add = [...fromEnvAdd, ...fromProgAdd];
+  const seen = new Set(base);
+  for (const c of add) {
+    if (!seen.has(c)) {
+      seen.add(c);
+      base.push(c);
+    }
+  }
+  return base;
+}
+function loadConfig(root) {
+  const startDir = root ?? programmaticConfig.root ?? process.cwd();
+  const configDir = findConfigDir(startDir);
+  const fileConfig = configDir ? loadConfigFile(configDir) : {};
+  const envConfig = configFromEnv();
+  const merged = {
+    ...fileConfig,
+    ...envConfig,
+    ...programmaticConfig
+  };
+  merged.contexts = mergeContexts(fileConfig, envConfig, programmaticConfig);
+  delete merged.addContexts;
+  if (configDir && !merged.root) merged.root = configDir;
+  else if (!merged.root) merged.root = startDir;
+  return merged;
+}
+function configure(partial) {
+  const { callbacks, ...configPartial } = partial;
+  programmaticConfig = { ...programmaticConfig, ...configPartial };
+  if (callbacks) {
+    programmaticCallbacks = { ...programmaticCallbacks, ...callbacks };
+  }
+}
+function resetConfig() {
+  programmaticConfig = {};
+  programmaticCallbacks = {};
+}
+
+// src/context.ts
+import {
+  readFileSync as readFileSync2,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync
+} from "fs";
+import { join as join2, dirname as dirname2 } from "path";
+var CONTEXT_SUFFIX = ".context.json";
+function discoverContextPathsInternal(dir, found) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true }).map((d) => ({
+      name: d.name,
+      path: join2(dir, d.name)
+    }));
+  } catch {
+    return;
+  }
+  for (const { name, path } of entries) {
+    if (name.endsWith(CONTEXT_SUFFIX) && !name.startsWith(".")) {
+      const contextName = name.slice(0, -CONTEXT_SUFFIX.length);
+      if (!found.has(contextName)) found.set(contextName, path);
+    }
+  }
+  for (const { name, path } of entries) {
+    if (name === "." || name === "..") continue;
+    try {
+      if (statSync(path).isDirectory())
+        discoverContextPathsInternal(path, found);
+    } catch {
+    }
+  }
+}
+function discoverContextPaths(dir, found = /* @__PURE__ */ new Map()) {
+  discoverContextPathsInternal(dir, found);
+  return found;
+}
+function getContextValues() {
+  const config = loadConfig();
+  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;
+    try {
+      const raw = readFileSync2(filePath, "utf-8");
+      const data = JSON.parse(raw);
+      for (const [k, v] of Object.entries(data)) {
+        if (typeof v === "string") out[k] = v;
+      }
+    } catch {
+    }
+  }
+  return out;
+}
+function getContextWritePath(contextName) {
+  const config = loadConfig();
+  const root = config.root ?? process.cwd();
+  const paths = discoverContextPaths(root);
+  const existing = paths.get(contextName);
+  if (existing) return existing;
+  return join2(root, `${contextName}${CONTEXT_SUFFIX}`);
+}
+function writeToContext(contextName, key, value) {
+  const path = getContextWritePath(contextName);
+  let data = {};
+  try {
+    const raw = readFileSync2(path, "utf-8");
+    data = JSON.parse(raw);
+  } catch {
+  }
+  data[key] = value;
+  const dir = dirname2(path);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+// src/prompt-default.ts
+import { createInterface } from "readline";
+function defaultPrompt(name, defaultValue) {
+  const defaultStr = defaultValue !== void 0 && defaultValue !== null ? String(defaultValue) : "";
+  const message = defaultStr ? `Enter ${name} [${defaultStr}]: ` : `Enter ${name}: `;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve, reject) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      const value = trimmed !== "" ? trimmed : defaultStr;
+      resolve(value);
+    });
+    rl.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+  });
+}
+
+// src/variable.ts
+function defaultKeyFromName(name) {
+  return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
+}
+function defaultEnvFromKey(key) {
+  return key.toUpperCase().replace(/-/g, "_");
+}
+function normalizeValidatorResult(result) {
+  if (typeof result === "boolean") {
+    return result ? { success: true } : { success: false };
+  }
+  if (result.success === true) return result;
+  return result;
+}
+function senv(name, options = {}) {
+  const key = options.key ?? defaultKeyFromName(name);
+  const envKey = options.env ?? defaultEnvFromKey(key);
+  const validator = options.validator;
+  const promptFn = options.prompt;
+  const defaultValue = options.default;
+  async function resolveRaw() {
+    const config = loadConfig();
+    if (config.set?.[key] !== void 0) return config.set[key];
+    if (!config.ignoreEnv) {
+      const envVal = process.env[envKey];
+      if (envVal !== void 0 && envVal !== "") return envVal;
+    }
+    if (!config.ignoreContext) {
+      const ctx = getContextValues();
+      if (ctx[key] !== void 0) return ctx[key];
+    }
+    if (defaultValue !== void 0) {
+      return String(defaultValue);
+    }
+    return void 0;
+  }
+  function shouldPrompt(config, hadValue, hadEnv) {
+    const mode = config.prompt ?? "fallback";
+    if (mode === "never") return false;
+    if (mode === "always") return true;
+    if (mode === "fallback") return !hadValue;
+    if (mode === "no-env") return !hadEnv;
+    return false;
+  }
+  async function getResolvedValue() {
+    const config = loadConfig();
+    const raw = await resolveRaw();
+    const hadEnv = !config.ignoreEnv && process.env[envKey] !== void 0 && process.env[envKey] !== "";
+    const hadValue = raw !== void 0;
+    let wasPrompted = false;
+    let value;
+    if (shouldPrompt(config, hadValue, hadEnv)) {
+      const defaultForPrompt = raw !== void 0 ? raw : defaultValue;
+      const fn = promptFn ?? defaultPrompt;
+      value = await Promise.resolve(fn(name, defaultForPrompt));
+      wasPrompted = true;
+    } else if (raw !== void 0) {
+      value = raw;
+    } else if (defaultValue !== void 0) {
+      value = defaultValue;
+    } else {
+      throw new Error(`Missing value for variable "${name}" (key: ${key})`);
+    }
+    return { value, raw, hadEnv, wasPrompted };
+  }
+  function validate(value) {
+    if (!validator) return { success: true, data: value };
+    const result = validator(value);
+    const normalized = normalizeValidatorResult(result);
+    if (normalized.success) {
+      const data = "data" in normalized && normalized.data !== void 0 ? normalized.data : value;
+      return { success: true, data };
+    }
+    return {
+      success: false,
+      error: "error" in normalized ? normalized.error : void 0
+    };
+  }
+  async function get() {
+    const { value, wasPrompted } = await getResolvedValue();
+    const validated = validate(value);
+    if (!validated.success) {
+      throw new Error(
+        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
+      );
+    }
+    const final = validated.data;
+    if (wasPrompted) {
+      const config = loadConfig();
+      const savePrompt = config.savePrompt ?? "never";
+      const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
+      if (shouldAskSave) {
+        const callbacks = getCallbacks();
+        const ctxToSave = callbacks.onAskSaveAfterPrompt && await callbacks.onAskSaveAfterPrompt(
+          name,
+          final,
+          config.contexts ?? []
+        );
+        if (ctxToSave) writeToContext(ctxToSave, key, String(final));
+      }
+    }
+    return final;
+  }
+  async function safeGet() {
+    try {
+      const v = await get();
+      return { success: true, value: v };
+    } catch (err) {
+      return { success: false, error: err };
+    }
+  }
+  async function save(value) {
+    const toSave = value ?? (await getResolvedValue()).value;
+    const validated = validate(toSave);
+    if (!validated.success) {
+      throw new Error(
+        `Validation failed for "${name}": ${validated.error ?? "unknown"}`
+      );
+    }
+    const config = loadConfig();
+    let contextName = config.saveContextTo;
+    if (contextName === "ask") {
+      const callbacks = getCallbacks();
+      if (typeof callbacks.onAskContext === "function") {
+        contextName = await callbacks.onAskContext(
+          name,
+          config.contexts ?? []
+        );
+      } else {
+        contextName = config.contexts?.[0] ?? "default";
+      }
+    }
+    if (!contextName) contextName = config.contexts?.[0] ?? "default";
+    writeToContext(contextName, key, String(validated.data));
+  }
+  return { get, safeGet, save };
+}
+
+// src/cli-args.ts
+function parseSenvArgs(argv) {
+  const config = {};
+  let i = 0;
+  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);
+    } else if (arg === "--add-context" && argv[i + 1] !== void 0) {
+      config.addContexts = 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)) {
+        config.prompt = v;
+      }
+    } else if (arg === "--ignore-env") {
+      config.ignoreEnv = true;
+    } else if (arg === "--ignore-context") {
+      config.ignoreContext = true;
+    } else if (arg === "--set" && argv[i + 1] !== void 0) {
+      const pair = argv[++i];
+      const eq = pair.indexOf("=");
+      if (eq > 0) {
+        config.set = config.set ?? {};
+        config.set[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+      }
+    } else if (arg === "--save-prompt" && argv[i + 1] !== void 0) {
+      const v = argv[++i].toLowerCase();
+      if (["always", "never", "ask"].includes(v)) {
+        config.savePrompt = v;
+      }
+    } else if (arg === "--save-context-to" && argv[i + 1] !== void 0) {
+      config.saveContextTo = argv[++i];
+    } else if (arg.startsWith("--set=")) {
+      const pair = arg.slice(6);
+      const eq = pair.indexOf("=");
+      if (eq > 0) {
+        config.set = config.set ?? {};
+        config.set[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+      }
+    }
+    i++;
+  }
+  return config;
+}
+export {
+  configure,
+  discoverContextPaths,
+  getCallbacks,
+  getContextValues,
+  loadConfig,
+  parseSenvArgs,
+  resetConfig,
+  senv
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "scenv",
+  "version": "0.1.0",
+  "description": "Environment and context variables with runtime-configurable resolution",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PKWadsy/senv.git"
+  },
+  "keywords": [
+    "env",
+    "config",
+    "context",
+    "variables"
+  ],
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}