@ayronforge/envil 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Toledo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @ayronforge/envil
+
+Typesafe environment variables using [Effect Schema](https://effect.website/docs/schema/introduction).
+
+![NPM Version](https://img.shields.io/npm/v/@ayronforge/envil)
+![License](https://img.shields.io/npm/l/@ayronforge/envil)
+
+Never deploy with invalid environment variables again. **envil** validates all your env vars at startup, gives you full TypeScript autocompletion, and keeps server secrets out of client bundles — powered by the [Effect](https://effect.website) ecosystem.
+
+## Documentation
+
+For schemas, helpers, prefix support, framework presets, composable envs, resolvers, and more — visit the **[documentation](https://ayronforge.com/envil)**.
+
+## Highlights
+
+- **Full type inference** — env vars are fully typed from your schemas, no manual annotations needed
+- **Client / server separation** — server-only vars throw at runtime if accessed on the client
+- **Eager validation** — all errors collected and reported at once on startup
+- **Built-in schemas** — booleans, ports, URLs, database URLs, JSON, enums, and more
+- **Secret manager resolvers** — fetch secrets from AWS, GCP, Azure Key Vault, and 1Password
+
+## Requirements
+
+- **Node.js** 18+
+- **ESM only**
+- [**effect**](https://effect.website) ^3.19.11
+
+## Installation
+
+```bash
+# npm
+npm install @ayronforge/envil effect
+
+# pnpm
+pnpm add @ayronforge/envil effect
+
+# bun
+bun add @ayronforge/envil effect
+```
+
+## CLI (`envil`)
+
+This package ships a CLI named `envil` with deterministic schema/example round-tripping:
+
+```bash
+# infer env.ts from .env.example
+envil add env --input .env.example --output src/env.ts --force
+
+# regenerate .env.example from env.ts manifest
+envil add example --input src/env.ts --output .env.example --force
+```
+
+`envil add env` supports:
+
+- `--framework <nextjs|vite|expo|nuxt|sveltekit|astro>`
+- `--client-prefix <prefix>`
+- `--server-prefix <prefix>`
+- `--shared-prefix <prefix>`
+- `--force`
+
+`envil add example` supports:
+
+- `--force`
+
+Both commands support `--help` for full usage output.
+
+## Quick start
+
+```ts
+import {
+  createEnv,
+  requiredString,
+  port,
+  withDefault,
+  boolean,
+  postgresUrl,
+  redacted,
+} from "@ayronforge/envil";
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: postgresUrl,
+    API_SECRET: redacted(requiredString),
+    PORT: withDefault(port, 3000),
+    DEBUG: withDefault(boolean, false),
+  },
+  client: {
+    PUBLIC_API_URL: requiredString,
+  },
+});
+
+env.DATABASE_URL; // string — fully typed
+env.API_SECRET;   // Redacted<string> — unwrap with Redacted.value(env.API_SECRET)
+env.PORT;         // number — transformed from string
+```
+
+If any variable is missing or invalid, `createEnv()` throws immediately with detailed errors:
+
+```
+EnvValidationError: Invalid environment variables:
+DATABASE_URL: Expected a valid PostgreSQL connection URL
+API_SECRET: Expected a string with at least 1 character(s), actual ""
+```
+
+## Acknowledgements
+
+This project is heavily inspired by [T3 Env](https://env.t3.gg) by [T3 OSS](https://github.com/t3-oss/t3-env). Thanks to the T3 team for their work and contributions to open source.
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli/dotenv-codec.d.ts

@@ -0,0 +1,3 @@
+import { type DotenvDocument } from "./types.ts";
+export declare function decodeDotenvText(text: string): DotenvDocument;
+export declare function encodeDotenvText(document: DotenvDocument): string;

package/dist/cli/fs-utils.d.ts

@@ -0,0 +1,7 @@
+export declare function pathExists(filePath: string): Promise<boolean>;
+export declare function resolveFromCwd(cwd: string, filePath: string): string;
+export declare function getDefaultEnvOutputPath(cwd: string): Promise<string>;
+export declare function getDefaultExampleInputPath(cwd: string): Promise<string>;
+export declare function ensureWritableTarget(targetPath: string, force: boolean): Promise<void>;
+export declare function readTextFileOrThrow(filePath: string, label: string): Promise<string>;
+export declare function writeFileAtomic(targetPath: string, contents: string): Promise<void>;

package/dist/cli/generate-env-ts.d.ts

@@ -0,0 +1,2 @@
+import { type InferredModel } from "./types.ts";
+export declare function generateEnvTs(model: InferredModel): string;

package/dist/cli/generate-example.d.ts

@@ -0,0 +1,2 @@
+import { type Manifest } from "./types.ts";
+export declare function generateExample(manifest: Manifest): string;

package/dist/cli/index.d.ts

@@ -0,0 +1,7 @@
+export { decodeDotenvText, encodeDotenvText } from "./dotenv-codec.ts";
+export { getDefaultEnvOutputPath, getDefaultExampleInputPath, resolveFromCwd } from "./fs-utils.ts";
+export { generateExample } from "./generate-example.ts";
+export { generateEnvTs } from "./generate-env-ts.ts";
+export { inferModel } from "./infer.ts";
+export { decodeManifestFromSource, encodeManifestBlock } from "./manifest-codec.ts";
+export * from "./types.ts";

package/dist/cli/infer.d.ts

@@ -0,0 +1,6 @@
+import type { DotenvDocument, InferredModel, PrefixConfig } from "./types.ts";
+interface InferOptions {
+    readonly prefix: PrefixConfig;
+}
+export declare function inferModel(document: DotenvDocument, options: InferOptions): InferredModel;
+export {};

package/dist/cli/literals.d.ts

@@ -0,0 +1,5 @@
+export declare function parseLiteral(input: string): unknown;
+export declare function toCodeLiteral(value: unknown): string;
+export declare function toDirectiveLiteral(value: unknown): string;
+export declare function toEnvValueLiteral(value: unknown): string;
+export declare function parseBooleanDirective(value: string | undefined, defaultValue: boolean): boolean;

package/dist/cli/manifest-codec.d.ts

@@ -0,0 +1,3 @@
+import { type Manifest } from "./types.ts";
+export declare function decodeManifestFromSource(source: string): Manifest;
+export declare function encodeManifestBlock(manifest: Manifest): string;

package/dist/cli/types.d.ts

@@ -0,0 +1,61 @@
+export declare const BUCKETS: readonly ["server", "client", "shared"];
+export type Bucket = (typeof BUCKETS)[number];
+export declare const SCHEMA_KINDS: readonly ["requiredString", "boolean", "integer", "number", "port", "url", "postgresUrl", "redisUrl", "mongoUrl", "mysqlUrl", "commaSeparated", "commaSeparatedNumbers", "commaSeparatedUrls", "json"];
+export type SchemaKind = (typeof SCHEMA_KINDS)[number];
+export declare const FRAMEWORKS: readonly ["nextjs", "vite", "expo", "nuxt", "sveltekit", "astro"];
+export type Framework = (typeof FRAMEWORKS)[number];
+export interface PrefixConfig {
+    readonly server: string;
+    readonly client: string;
+    readonly shared: string;
+}
+export interface ParsedDirectives {
+    readonly type?: SchemaKind;
+    readonly optional?: boolean;
+    readonly hasDefault?: boolean;
+    readonly defaultValue?: unknown;
+    readonly redacted?: boolean;
+    readonly bucket?: Bucket;
+}
+export interface DotenvAssignment {
+    readonly key: string;
+    readonly value: string;
+    readonly line: number;
+    readonly sectionBucket?: Bucket;
+    readonly directives: ParsedDirectives;
+}
+export interface DotenvDocument {
+    readonly entries: ReadonlyArray<DotenvAssignment>;
+}
+export interface InferredVariable {
+    readonly schemaKey: string;
+    readonly runtimeKey: string;
+    readonly bucket: Bucket;
+    readonly kind: SchemaKind;
+    readonly optional: boolean;
+    readonly hasDefault: boolean;
+    readonly defaultValue?: unknown;
+    readonly redacted: boolean;
+    readonly sourceLine: number;
+}
+export interface InferredModel {
+    readonly prefix: PrefixConfig;
+    readonly variables: ReadonlyArray<InferredVariable>;
+    readonly runtimeEnv: Readonly<Record<string, string | undefined>>;
+}
+export interface ManifestVariable {
+    readonly name: string;
+    readonly bucket: Bucket;
+    readonly kind: SchemaKind;
+    readonly optional: boolean;
+    readonly hasDefault: boolean;
+    readonly defaultValue?: unknown;
+    readonly redacted: boolean;
+}
+export interface ManifestV1 {
+    readonly version: 1;
+    readonly prefix: PrefixConfig;
+    readonly variables: ReadonlyArray<ManifestVariable>;
+}
+export type Manifest = ManifestV1;
+export declare const MANIFEST_VERSION: 1;

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+interface CliIO {
+    cwd: () => string;
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+}
+export declare function runCli(argv: string[], io?: Partial<CliIO>): Promise<number>;
+export {};