ultraenv 1.0.0

package/dist/chunk-5G2DU52U.js

@@ -0,0 +1,189 @@
+// src/core/errors.ts
+var UltraenvError = class extends Error {
+  /** Machine-readable error code (e.g., 'PARSE_ERROR', 'ENCRYPTION_ERROR') */
+  code;
+  /** Human-readable hint for how to fix this error */
+  hint;
+  /** The original cause of this error, if wrapping another error */
+  cause;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options.code ?? "ULTRAENV_ERROR";
+    this.hint = options.hint;
+    this.cause = options.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** Return a formatted string with code, message, and hint */
+  toString() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.hint !== void 0) {
+      parts.push(`  Hint: ${this.hint}`);
+    }
+    return parts.join("\n");
+  }
+};
+var ValidationError = class extends UltraenvError {
+  /** The variable name that failed validation */
+  field;
+  /** The actual value that was provided */
+  value;
+  /** The schema definition that was violated */
+  schema;
+  /** Expected type or constraint description */
+  expected;
+  constructor(field, value, message, options = {}) {
+    const fullMessage = message || `Validation failed for "${field}"`;
+    super(fullMessage, {
+      code: "VALIDATION_ERROR",
+      hint: options.hint ?? `Check the value of "${field}" in your .env file. Expected: ${options.expected ?? "see schema definition"}.`,
+      cause: options.cause
+    });
+    this.field = field;
+    this.value = value;
+    this.schema = options.schema;
+    this.expected = options.expected ?? "valid value";
+  }
+};
+var ParseError = class extends UltraenvError {
+  /** 1-based line number where the error occurred */
+  line;
+  /** 1-based column number where the error occurred */
+  column;
+  /** The raw content of the line that caused the error */
+  raw;
+  /** Path to the file being parsed */
+  filePath;
+  constructor(message, options = {}) {
+    const location = options.line !== void 0 ? ` at line ${options.line}${options.column !== void 0 ? `, column ${options.column}` : ""}` : "";
+    const file = options.filePath !== void 0 ? ` in "${options.filePath}"` : "";
+    const fullMessage = `${message}${file}${location}`;
+    super(fullMessage, {
+      code: "PARSE_ERROR",
+      hint: options.hint ?? "Check your .env file for invalid syntax. Each line should be in the format KEY=VALUE or # comment.",
+      cause: options.cause
+    });
+    this.line = options.line ?? 0;
+    this.column = options.column ?? 0;
+    this.raw = options.raw ?? "";
+    this.filePath = options.filePath ?? "";
+  }
+};
+var InterpolationError = class extends UltraenvError {
+  /** The variable reference that caused the error */
+  variable;
+  /** Whether this was caused by a circular reference */
+  circular;
+  constructor(message, options = {}) {
+    super(message, {
+      code: "INTERPOLATION_ERROR",
+      hint: options.hint ?? (options.circular ? "Circular variable references are not allowed. Check that no two variables reference each other." : `Make sure "${options.variable ?? "the referenced variable"}" is defined before it is referenced.`),
+      cause: options.cause
+    });
+    this.variable = options.variable ?? "";
+    this.circular = options.circular ?? false;
+  }
+};
+var EncryptionError = class extends UltraenvError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: "ENCRYPTION_ERROR",
+      hint: options.hint ?? 'Ensure your encryption key is valid and has not been corrupted. Try regenerating the key with "ultraenv key generate".',
+      cause: options.cause
+    });
+  }
+};
+var VaultError = class extends UltraenvError {
+  /** The environment name involved */
+  environment;
+  /** The vault operation that failed */
+  operation;
+  constructor(message, options = {}) {
+    super(message, {
+      code: "VAULT_ERROR",
+      hint: options.hint ?? `Check that the vault file exists and is properly formatted for environment "${options.environment ?? "unknown"}". Run "ultraenv vault status" for diagnostics.`,
+      cause: options.cause
+    });
+    this.environment = options.environment ?? "";
+    this.operation = options.operation ?? "";
+  }
+};
+var ScanError = class extends UltraenvError {
+  /** The file being scanned */
+  file;
+  /** The line number where the error occurred */
+  line;
+  /** The secret pattern that triggered the error */
+  pattern;
+  constructor(message, options = {}) {
+    super(message, {
+      code: "SCAN_ERROR",
+      hint: options.hint ?? "Check that all files being scanned are accessible and contain valid text content.",
+      cause: options.cause
+    });
+    this.file = options.file ?? "";
+    this.line = options.line ?? 0;
+    this.pattern = options.pattern ?? "";
+  }
+};
+var ConfigError = class extends UltraenvError {
+  /** The configuration field that is invalid */
+  field;
+  constructor(message, options = {}) {
+    super(message, {
+      code: "CONFIG_ERROR",
+      hint: options.hint ?? `Check your ultraenv configuration. The field "${options.field ?? "unknown"}" may have an invalid value or type.`,
+      cause: options.cause
+    });
+    this.field = options.field ?? "";
+  }
+};
+var FileSystemError = class extends UltraenvError {
+  /** The file or directory path involved */
+  path;
+  /** The operation that failed (e.g., 'read', 'write', 'mkdir') */
+  operation;
+  /** The underlying system error code (e.g., 'ENOENT', 'EACCES') */
+  code;
+  constructor(message, options = {}) {
+    const fsCode = options.code ?? options.cause?.code ?? "UNKNOWN";
+    const opHint = options.path !== void 0 ? `Could not ${options.operation ?? "access"} "${options.path}".` : "";
+    super(message, {
+      code: `FS_${fsCode}`,
+      hint: options.hint ?? `${opHint} Ensure the file exists and you have the necessary permissions.`,
+      cause: options.cause
+    });
+    this.path = options.path ?? "";
+    this.operation = options.operation ?? "";
+    this.code = fsCode;
+  }
+};
+function isUltraenvError(error) {
+  return error instanceof UltraenvError;
+}
+function getErrorMessage(error) {
+  if (error instanceof UltraenvError) {
+    return error.toString();
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return `Unknown error: ${String(error)}`;
+}
+
+export {
+  UltraenvError,
+  ValidationError,
+  ParseError,
+  InterpolationError,
+  EncryptionError,
+  VaultError,
+  ScanError,
+  ConfigError,
+  FileSystemError,
+  isUltraenvError,
+  getErrorMessage
+};

package/dist/chunk-6KS56D6E.js

@@ -0,0 +1,172 @@
+import {
+  writeFile
+} from "./chunk-3VYXPTYV.js";
+
+// src/typegen/json-schema.ts
+var JSON_SCHEMA_DRAFT_07 = "http://json-schema.org/draft-07/schema#";
+function schemaToJsonSchemaProperty(key, schema, includeDescriptions) {
+  const r = schema;
+  const schemaType = r.type;
+  const property = {
+    type: "string"
+  };
+  if (includeDescriptions && schema.description !== void 0) {
+    property.description = schema.description;
+  } else if (includeDescriptions) {
+    property.description = key;
+  }
+  if (schema.default !== void 0) {
+    property.default = schema.default;
+  } else if (r.hasDefault === true && typeof r.rawDefaultValue === "string") {
+    const raw = r.rawDefaultValue;
+    if (raw === "true") {
+      property.default = true;
+    } else if (raw === "false") {
+      property.default = false;
+    } else if (raw !== "" && !Number.isNaN(Number(raw)) && raw === String(Number(raw))) {
+      property.default = Number(raw);
+    } else {
+      property.default = raw;
+    }
+  }
+  switch (schemaType) {
+    case "string": {
+      property.type = "string";
+      const enumValues = r.enum;
+      if (Array.isArray(enumValues) && enumValues.length > 0) {
+        property.enum = [...enumValues];
+      }
+      if (typeof r.minLength === "number") {
+        property.minLength = r.minLength;
+      }
+      if (typeof r.maxLength === "number") {
+        property.maxLength = r.maxLength;
+      }
+      if (r.pattern instanceof RegExp) {
+        property.pattern = r.pattern.source;
+      }
+      if (typeof r.format === "string") {
+        property.format = mapFormat(r.format);
+      }
+      break;
+    }
+    case "number": {
+      property.type = r.integer === true ? "integer" : "number";
+      if (typeof r.min === "number") {
+        property.minimum = r.min;
+        if (r.positive === true) {
+          property.exclusiveMinimum = true;
+        }
+      }
+      if (typeof r.max === "number") {
+        property.maximum = r.max;
+        if (r.negative === true) {
+          property.exclusiveMaximum = true;
+        }
+      }
+      break;
+    }
+    case "boolean": {
+      property.type = "boolean";
+      break;
+    }
+    case "enum": {
+      property.type = "string";
+      const values = r.values;
+      if (Array.isArray(values) && values.length > 0) {
+        property.enum = [...values];
+      }
+      break;
+    }
+    case "array": {
+      property.type = "array";
+      property.items = { type: "string" };
+      if (typeof r.minItems === "number") {
+        property.minItems = r.minItems;
+      }
+      if (typeof r.maxItems === "number") {
+        property.maxItems = r.maxItems;
+      }
+      if (r.unique === true) {
+        property.uniqueItems = true;
+      }
+      if (typeof r.separator === "string" && r.separator !== ",") {
+        property.description = (property.description ?? "") + ` (separator: "${r.separator}")`;
+      }
+      break;
+    }
+    case "json": {
+      property.type = "object";
+      break;
+    }
+    case "date": {
+      property.type = "string";
+      property.format = "date-time";
+      break;
+    }
+    case "bigint": {
+      property.type = "string";
+      property.description = (property.description ?? "") + " (bigint as string)";
+      break;
+    }
+    default: {
+      property.type = "string";
+      break;
+    }
+  }
+  return property;
+}
+function mapFormat(format) {
+  const formatMap = /* @__PURE__ */ new Map([
+    ["email", "email"],
+    ["url", "uri"],
+    ["uuid", "uuid"],
+    ["hostname", "hostname"],
+    ["ip", "string"],
+    ["ipv4", "ipv4"],
+    ["ipv6", "ipv6"]
+  ]);
+  return formatMap.get(format) ?? "string";
+}
+async function generateJsonSchema(schema, outputPath, options) {
+  const content = generateJsonSchemaContent(schema, options);
+  if (outputPath !== void 0) {
+    await writeFile(outputPath, content);
+  }
+  return content;
+}
+function generateJsonSchemaContent(schema, options) {
+  const includeDescriptions = options?.includeDescriptions ?? true;
+  const indent = options?.indent ?? 2;
+  const title = options?.title ?? "Environment Variables";
+  const description = options?.description ?? "Schema for environment variables managed by ultraenv";
+  const properties = {};
+  const required = [];
+  const sortedKeys = Object.keys(schema).sort();
+  for (const key of sortedKeys) {
+    const schemaEntry = schema[key];
+    if (schemaEntry === void 0) continue;
+    properties[key] = schemaToJsonSchemaProperty(key, schemaEntry, includeDescriptions);
+    const r = schemaEntry;
+    const isOptional = schemaEntry.optional === true || schemaEntry.default !== void 0 || r.hasDefault === true;
+    if (!isOptional) {
+      required.push(key);
+    }
+  }
+  required.sort();
+  const document = {
+    $schema: JSON_SCHEMA_DRAFT_07,
+    title,
+    description,
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false
+  };
+  return JSON.stringify(document, null, indent) + "\n";
+}
+
+export {
+  generateJsonSchema,
+  generateJsonSchemaContent
+};

package/dist/chunk-AWN6ADV7.js

@@ -0,0 +1,328 @@
+import {
+  parseEnvFile
+} from "./chunk-HFXQGJY3.js";
+import {
+  exists,
+  readFile,
+  removeFile,
+  writeFile
+} from "./chunk-3VYXPTYV.js";
+import {
+  FileSystemError
+} from "./chunk-5G2DU52U.js";
+
+// src/environments/creator.ts
+import { resolve, join } from "path";
+var NODEJS_TEMPLATE = `# Node.js Backend Environment
+# Created by ultraenv
+
+# Server
+PORT=3000
+HOST=localhost
+NODE_ENV=development
+
+# Database
+DATABASE_URL=
+DATABASE_POOL_SIZE=10
+
+# Authentication
+JWT_SECRET=
+JWT_EXPIRES_IN=7d
+
+# CORS
+ALLOWED_ORIGINS=http://localhost:3000
+
+# Logging
+LOG_LEVEL=info
+LOG_FORMAT=json
+
+# Feature Flags
+DEBUG=false
+VERBOSE=false
+`;
+var NEXTJS_TEMPLATE = `# Next.js Frontend Environment
+# Created by ultraenv
+
+# Framework
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_API_URL=http://localhost:3001
+
+# Analytics
+NEXT_PUBLIC_GA_ID=
+NEXT_PUBLIC_SENTRY_DSN=
+
+# Feature Flags
+NEXT_PUBLIC_DEBUG=false
+NEXT_PUBLIC_MAINTENANCE=false
+`;
+var DOCKER_TEMPLATE = `# Docker Deployment Environment
+# Created by ultraenv
+
+# Container
+CONTAINER_PORT=3000
+HOST_PORT=3000
+
+# Database
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=
+POSTGRES_PASSWORD=
+POSTGRES_DB=
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+# Networking
+NETWORK_NAME=app-network
+`;
+var BUILTIN_TEMPLATES = /* @__PURE__ */ new Map([
+  ["nodejs", NODEJS_TEMPLATE],
+  ["nextjs", NEXTJS_TEMPLATE],
+  ["docker", DOCKER_TEMPLATE]
+]);
+function extractVariables(content, schema) {
+  const parsed = parseEnvFile(content);
+  const variables = [];
+  const seenKeys = /* @__PURE__ */ new Set();
+  if (schema !== void 0) {
+    for (const [key, schemaEntry] of Object.entries(schema)) {
+      if (seenKeys.has(key)) continue;
+      seenKeys.add(key);
+      const r = schemaEntry;
+      variables.push({
+        key,
+        value: "",
+        description: schemaEntry.description,
+        isSecret: r.isSecret === true,
+        isRequired: schemaEntry.optional !== true && schemaEntry.default === void 0 && r.hasDefault !== true,
+        hasDefault: schemaEntry.default !== void 0 || r.hasDefault === true,
+        defaultValue: typeof r.rawDefaultValue === "string" ? r.rawDefaultValue : void 0,
+        type: typeof r.typeName === "string" ? r.typeName : "string"
+      });
+    }
+  }
+  for (const envVar of parsed.vars) {
+    if (seenKeys.has(envVar.key)) continue;
+    seenKeys.add(envVar.key);
+    variables.push({
+      key: envVar.key,
+      value: envVar.value,
+      isSecret: false,
+      isRequired: false,
+      hasDefault: false,
+      type: "string"
+    });
+  }
+  return variables;
+}
+function generateEnvironmentContent(variables, values) {
+  const lines = [];
+  lines.push(`# Environment: generated by ultraenv`);
+  lines.push(`# Created: ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  lines.push("");
+  for (const variable of variables) {
+    if (variable.description !== void 0) {
+      lines.push(`# ${variable.description}`);
+    }
+    lines.push(`# type: ${variable.type}`);
+    if (variable.isRequired) {
+      lines.push("# required");
+    } else if (variable.hasDefault && variable.defaultValue !== void 0) {
+      lines.push(`# default: ${variable.defaultValue}`);
+    } else {
+      lines.push("# optional");
+    }
+    if (variable.isSecret) {
+      lines.push("# [SECRET]");
+    }
+    const providedValue = values[variable.key];
+    if (providedValue !== void 0) {
+      lines.push(`${variable.key}=${providedValue}`);
+    } else if (variable.hasDefault && variable.defaultValue !== void 0) {
+      lines.push(`${variable.key}=${variable.defaultValue}`);
+    } else if (variable.isSecret) {
+      lines.push(`${variable.key}=`);
+    } else if (variable.isRequired) {
+      lines.push(`${variable.key}=`);
+    } else {
+      lines.push(`# ${variable.key}=`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function collectValues(variables, providedValues) {
+  const values = { ...providedValues };
+  for (const variable of variables) {
+    if (variable.key in values) continue;
+    if (!variable.isRequired && !variable.hasDefault) continue;
+    if (variable.hasDefault && variable.defaultValue !== void 0) {
+      values[variable.key] = variable.defaultValue;
+    }
+  }
+  return values;
+}
+function validateEnvironmentName(name) {
+  if (name.length === 0) {
+    throw new FileSystemError("Environment name cannot be empty", {
+      path: "",
+      operation: "validate",
+      hint: 'Provide a valid environment name (e.g., "staging", "production").'
+    });
+  }
+  if (name.length > 64) {
+    throw new FileSystemError(
+      `Environment name too long: ${name.length} characters (max 64)`,
+      {
+        path: "",
+        operation: "validate",
+        hint: "Use a shorter environment name."
+      }
+    );
+  }
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new FileSystemError(
+      `Invalid environment name: "${name}". Only alphanumeric characters, hyphens, and underscores are allowed.`,
+      {
+        path: "",
+        operation: "validate",
+        hint: 'Use names like "staging", "production", "ci", "dev-v2", etc.'
+      }
+    );
+  }
+  const reserved = ["local", "example", "template", "bak", "backup", "old", "tmp", "temp"];
+  if (reserved.includes(name.toLowerCase())) {
+    throw new FileSystemError(
+      `Reserved environment name: "${name}"`,
+      {
+        path: "",
+        operation: "validate",
+        hint: `The name "${name}" is reserved. Choose a different name.`
+      }
+    );
+  }
+}
+async function createEnvironment(name, options) {
+  validateEnvironmentName(name);
+  const baseDir = resolve(options?.cwd ?? process.cwd());
+  const outputPath = join(baseDir, `.env.${name}`);
+  if (await exists(outputPath)) {
+    throw new FileSystemError(
+      `Environment file already exists: ".env.${name}"`,
+      {
+        path: outputPath,
+        operation: "create",
+        hint: "Delete the existing file first, or use a different environment name."
+      }
+    );
+  }
+  let content;
+  let variables = [];
+  if (options?.copyFrom !== void 0) {
+    const sourcePath = join(baseDir, `.env.${options.copyFrom}`);
+    if (!await exists(sourcePath)) {
+      throw new FileSystemError(
+        `Source environment not found: ".env.${options.copyFrom}"`,
+        {
+          path: sourcePath,
+          operation: "read",
+          hint: `Ensure ".env.${options.copyFrom}" exists before copying.`
+        }
+      );
+    }
+    content = await readFile(sourcePath);
+    variables = extractVariables(content, options?.schema);
+    const sourceParsed = parseEnvFile(content, sourcePath);
+    const sourceValues = {};
+    for (const envVar of sourceParsed.vars) {
+      sourceValues[envVar.key] = envVar.value;
+    }
+    content = generateEnvironmentContent(variables, {
+      ...sourceValues,
+      ...options?.values
+    });
+  } else if (options?.fromTemplate !== void 0) {
+    const templatePath = resolve(options.fromTemplate);
+    const builtinTemplate = BUILTIN_TEMPLATES.get(options.fromTemplate.toLowerCase());
+    if (builtinTemplate !== void 0) {
+      content = builtinTemplate;
+    } else if (await exists(templatePath)) {
+      content = await readFile(templatePath);
+    } else {
+      throw new FileSystemError(
+        `Template not found: "${options.fromTemplate}"`,
+        {
+          path: templatePath,
+          operation: "read",
+          hint: "Use a built-in template name (nodejs, nextjs, docker) or a valid file path."
+        }
+      );
+    }
+    variables = extractVariables(content, options?.schema);
+    const values = collectValues(variables, options?.values);
+    content = generateEnvironmentContent(variables, values);
+  } else if (options?.schema !== void 0) {
+    const schemaVars = [];
+    for (const [key, schemaEntry] of Object.entries(options.schema)) {
+      const r = schemaEntry;
+      schemaVars.push({
+        key,
+        value: "",
+        description: schemaEntry.description,
+        isSecret: r.isSecret === true,
+        isRequired: schemaEntry.optional !== true && schemaEntry.default === void 0 && r.hasDefault !== true,
+        hasDefault: schemaEntry.default !== void 0 || r.hasDefault === true,
+        defaultValue: typeof r.rawDefaultValue === "string" ? r.rawDefaultValue : void 0,
+        type: typeof r.typeName === "string" ? r.typeName : "string"
+      });
+    }
+    const values = collectValues(schemaVars, options?.values);
+    content = generateEnvironmentContent(schemaVars, values);
+  } else {
+    content = [
+      `# Environment: ${name}`,
+      `# Created by ultraenv on ${(/* @__PURE__ */ new Date()).toISOString()}`,
+      "",
+      "# Add your environment variables here",
+      ""
+    ].join("\n");
+  }
+  await writeFile(outputPath, content);
+}
+function listTemplates() {
+  return [
+    { name: "nodejs", description: "Node.js backend environment (PORT, DATABASE_URL, JWT, CORS, etc.)" },
+    { name: "nextjs", description: "Next.js frontend environment (NEXT_PUBLIC_* variables, analytics, etc.)" },
+    { name: "docker", description: "Docker deployment environment (container ports, Postgres, Redis, etc.)" }
+  ];
+}
+async function removeEnvironment(name, cwd) {
+  const baseDir = resolve(cwd ?? process.cwd());
+  const filePath = join(baseDir, `.env.${name}`);
+  if (!await exists(filePath)) {
+    throw new FileSystemError(
+      `Environment file not found: ".env.${name}"`,
+      {
+        path: filePath,
+        operation: "unlink",
+        hint: "The environment does not exist."
+      }
+    );
+  }
+  await removeFile(filePath);
+}
+async function duplicateEnvironment(sourceName, targetName, cwd) {
+  await createEnvironment(targetName, {
+    copyFrom: sourceName,
+    cwd
+  });
+}
+
+export {
+  createEnvironment,
+  listTemplates,
+  removeEnvironment,
+  duplicateEnvironment
+};