@arki/env 0.0.1 → 0.0.3

package/dist/contracts/index.d.ts

@@ -2,7 +2,7 @@ export declare const contracts: {
     json: <T extends import("zod").ZodType>(schema: T) => import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<Awaited<import("zod").infer<T>>, string>>;
     csvArray: <T extends import("zod").ZodType>(itemSchema: T) => import("zod").ZodPipe<import("zod").ZodTransform<unknown, unknown>, import("zod").ZodArray<T>>;
     csvSet: <T extends import("zod").ZodType>(itemSchema: T) => import("zod").ZodPipe<import("zod").ZodTransform<unknown, unknown>, import("zod").ZodArray<T>>;
-    url: (defaultValue?: string) => import("zod").ZodString | import("zod").ZodDefault<import("zod").ZodString>;
+    url: (defaultValue?: string) => import("zod").ZodURL | import("zod").ZodDefault<import("zod").ZodURL>;
     databaseUrl: () => import("zod").ZodURL;
     redisUrl: () => import("zod").ZodURL;
     string: (defaultValue?: string) => import("zod").ZodString | import("zod").ZodDefault<import("zod").ZodString>;

package/dist/contracts/urls.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 export declare const urlContracts: {
-    url: (defaultValue?: string) => z.ZodString | z.ZodDefault<z.ZodString>;
+    url: (defaultValue?: string) => z.ZodURL | z.ZodDefault<z.ZodURL>;
     databaseUrl: () => z.ZodURL;
     redisUrl: () => z.ZodURL;
 };

package/dist/contracts/urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/contracts/urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY;yBACF,MAAM;;;CAiB5B,CAAC"}
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/contracts/urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY;yBACF,MAAM;;;CAoB5B,CAAC"}

package/dist/contracts/urls.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export const urlContracts = {
     url: (defaultValue) => {
-        const schema = z.string().url();
+        const schema = z.url();
         return defaultValue ? schema.default(defaultValue) : schema;
     },
     databaseUrl: () => z

package/dist/contracts/urls.js.map

@@ -1 +1 @@
-{"version":3,"file":"urls.js","sourceRoot":"","sources":["../../src/contracts/urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,GAAG,EAAE,CAAC,YAAqB,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC;QAChC,OAAO,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED,WAAW,EAAE,GAAG,EAAE,CAChB,CAAC;SACE,GAAG,EAAE;SACL,MAAM,CACL,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC,EACvE,2DAA2D,CAC5D;IAEL,QAAQ,EAAE,GAAG,EAAE,CACb,CAAC;SACE,GAAG,EAAE;SACL,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,iDAAiD,CAAC;CACjI,CAAC"}
+{"version":3,"file":"urls.js","sourceRoot":"","sources":["../../src/contracts/urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,GAAG,EAAE,CAAC,YAAqB,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACvB,OAAO,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED,WAAW,EAAE,GAAG,EAAE,CAChB,CAAC;SACE,GAAG,EAAE;SACL,MAAM,CACL,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC,EACvE,2DAA2D,CAC5D;IAEL,QAAQ,EAAE,GAAG,EAAE,CACb,CAAC;SACE,GAAG,EAAE;SACL,MAAM,CACL,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAChE,iDAAiD,CAClD;CACN,CAAC"}

package/dist/core/define-env.d.ts

@@ -1,13 +1,54 @@
+import { createEnv } from '@t3-oss/env-core';
+import type { CreateEnv, DefaultCombinedSchema } from '@t3-oss/env-core';
 import type { ZodType } from 'zod';
-type CoreEnvConfig = {
-    server: Record<string, ZodType>;
+/** The issue shape t3-oss hands to `onValidationError`, derived so it stays in sync with the lib. */
+type ValidationIssues = Parameters<NonNullable<Parameters<typeof createEnv>[0]['onValidationError']>>[0];
+/**
+ * Thin, type-preserving wrapper over `@t3-oss/env-core`'s `createEnv`. Generic over the server,
+ * client, shared and composed schemas so the parsed env keeps its exact inferred types — the wrapper
+ * adds the ARKI defaults (auto `runtimeEnv`, prod-safe `skipValidation`, a legible labelled error
+ * handler) without widening any value to `unknown`.
+ *
+ * `TPrefix` is kept as a string-literal generic on purpose: `createEnv` uses it to enforce that
+ * client keys (and only client keys) carry the prefix. Widening it to `string` would make every
+ * server key collapse to a type-level `ErrorMessage`, so the prefix must stay a literal.
+ */
+export declare function defineEnv<TServer extends Record<string, ZodType>, TClient extends Record<string, ZodType> = NonNullable<unknown>, TShared extends Record<string, ZodType> = NonNullable<unknown>, const TPrefix extends string = '', const TExtends extends Array<Record<string, unknown>> = []>(config: {
+    /**
+     * Label shown in validation-error logs, e.g. `'@acme/backend'`. Without it a misconfigured
+     * deploy logs a bare "Invalid environment variables" with no hint which env failed — exactly the
+     * blind failure this wrapper exists to prevent.
+     */
+    name?: string;
+    server: TServer;
+    /** Client-side schema. Every key must start with `clientPrefix` (enforced by `createEnv`). */
+    client?: TClient;
+    /** Prefix client keys must carry, e.g. `'VITE_'`. Defaults to `''` (no client vars). */
+    clientPrefix?: TPrefix;
+    /** Shared vars available to both client and server, unprefixed (e.g. `NODE_ENV`). */
+    shared?: TShared;
+    /**
+     * Already-built envs to compose in (e.g. `@arki/auth`, `@arki/db`). Their parsed variables merge
+     * into the result with full types; each was validated by its own `createEnv` at import time.
+     */
+    extends?: TExtends;
+    /**
+     * Explicit runtime source. Omit it and `defineEnv` auto-builds one by reading `process.env` for
+     * every declared key — correct for any server-side env. Provide it only when the auto-build would
+     * be wrong: Vite/`start` apps whose client vars come from `import.meta.env` in the browser, or
+     * keys with a fallback/alias (e.g. `DB_URL: process.env.DB_URL ?? process.env.DATABASE_URL`).
+     */
+    runtimeEnv?: Record<string, string | boolean | number | undefined>;
     options?: {
         skipValidation?: boolean;
-        onValidationError?: (issues: any) => never;
+        /**
+         * Treat empty-string env values as `undefined` so defaults apply (e.g. `PORT=` in `.env`, or a
+         * Docker arg baked as `X=""`). Defaults to `true` — set `false` only if an app intentionally
+         * accepts `""` as a valid required string.
+         */
+        emptyStringAsUndefined?: boolean;
+        onValidationError?: (issues: ValidationIssues) => never;
     };
-};
-export declare function defineEnv(config: CoreEnvConfig): Readonly<{
-    [x: string]: unknown;
-}>;
+}): CreateEnv<DefaultCombinedSchema<TServer, TClient, TShared>, TExtends>;
 export {};
 //# sourceMappingURL=define-env.d.ts.map

package/dist/core/define-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-env.d.ts","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,KAAK,aAAa,GAAG;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QAEzB,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,KAAK,CAAC;KAC5C,CAAC;CACH,CAAC;AAEF,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa;;GAiB9C"}
+{"version":3,"file":"define-env.d.ts","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,qGAAqG;AACrG,KAAK,gBAAgB,GAAG,UAAU,CAChC,WAAW,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAClE,CAAC,CAAC,CAAC,CAAC;AAkBL;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,EAC9D,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,EAC9D,KAAK,CAAC,OAAO,SAAS,MAAM,GAAG,EAAE,EACjC,KAAK,CAAC,QAAQ,SAAS,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAC1D,MAAM,EAAE;IACR;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IACnE,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB;;;;WAIG;QACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;QACjC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,KAAK,CAAC;KACzD,CAAC;CACH,GAAG,SAAS,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAwDxE"}

package/dist/core/define-env.js

@@ -1,18 +1,76 @@
 import { createEnv } from '@t3-oss/env-core';
+/**
+ * Fold validation issues into a human-legible, log-pipeline-safe string. The t3-oss default handler
+ * logs `issues` as a raw object, which platforms like Coolify collapse to `[Object]` — so the var
+ * that actually failed never reaches the logs. A flat `  path: message` list survives transport.
+ */
+function formatIssues(name, issues) {
+    const label = name ? `[${name}] ` : '';
+    const lines = issues.map(issue => {
+        const path = (issue.path ?? [])
+            .map(seg => (typeof seg === 'object' && seg !== null && 'key' in seg ? String(seg.key) : String(seg)))
+            .join('.');
+        return `  ${path || '(root)'}: ${issue.message}`;
+    });
+    return `❌ ${label}Invalid environment variables:\n${lines.join('\n')}`;
+}
+/**
+ * Thin, type-preserving wrapper over `@t3-oss/env-core`'s `createEnv`. Generic over the server,
+ * client, shared and composed schemas so the parsed env keeps its exact inferred types — the wrapper
+ * adds the ARKI defaults (auto `runtimeEnv`, prod-safe `skipValidation`, a legible labelled error
+ * handler) without widening any value to `unknown`.
+ *
+ * `TPrefix` is kept as a string-literal generic on purpose: `createEnv` uses it to enforce that
+ * client keys (and only client keys) carry the prefix. Widening it to `string` would make every
+ * server key collapse to a type-level `ErrorMessage`, so the prefix must stay a literal.
+ */
 export function defineEnv(config) {
     const skipValidation = config.options?.skipValidation ?? (!!process.env.CI || process.env.NODE_ENV !== 'development');
-    // Auto-generate runtimeEnv (no Next.js bundler constraints)
-    const runtimeEnv = {};
-    for (const key of Object.keys(config.server)) {
-        runtimeEnv[key] = process.env[key];
+    // Use the caller's explicit runtimeEnv when supplied (Vite client vars via import.meta.env, or
+    // fallback aliases). Otherwise auto-build from every declared key (server + client + shared);
+    // createEnv tolerates keys absent from process.env (they parse as undefined → optional/default).
+    let runtimeEnv;
+    if (config.runtimeEnv) {
+        runtimeEnv = config.runtimeEnv;
     }
-    return createEnv({
+    else {
+        runtimeEnv = {};
+        for (const key of Object.keys(config.server)) {
+            runtimeEnv[key] = process.env[key];
+        }
+        for (const key of Object.keys(config.client ?? {})) {
+            runtimeEnv[key] = process.env[key];
+        }
+        for (const key of Object.keys(config.shared ?? {})) {
+            runtimeEnv[key] = process.env[key];
+        }
+    }
+    const onValidationError = config.options?.onValidationError ??
+        ((issues) => {
+            const message = formatIssues(config.name, issues);
+            console.error(message);
+            throw new Error(message);
+        });
+    // `createEnv`'s `server`/`client` params are conditional on `clientPrefix` being a *concrete*
+    // string literal; inside a generic wrapper `TPrefix` is abstract, so the body cannot be verified
+    // for all prefixes and the call argument must be asserted once. The PUBLIC contract stays exact:
+    // the explicit return type above reconstructs `createEnv`'s own result from the generics, and the
+    // caller's `server`/`client`/`extends` are fully type-checked against `TServer`/`TClient`/`TExtends`
+    // at the call site. This is the only seam where types are asserted — value types are never widened.
+    const options = {
+        shared: config.shared ?? {},
+        extends: config.extends,
         server: config.server,
-        client: {},
-        clientPrefix: '',
+        client: config.client ?? {},
+        clientPrefix: config.clientPrefix ?? '',
         runtimeEnv,
         skipValidation,
-        onValidationError: config.options?.onValidationError,
-    });
+        // Default ON: in containerized deploys an unset var is baked as "" (e.g. Docker `ENV X=${X}`
+        // with no build arg), not left absent. Treating "" as undefined lets `.default()`/`.optional()`
+        // apply as intended instead of failing format checks like `z.url()` on an empty string.
+        emptyStringAsUndefined: config.options?.emptyStringAsUndefined ?? true,
+        onValidationError,
+    };
+    return createEnv(options);
 }
 //# sourceMappingURL=define-env.js.map

package/dist/core/define-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-env.js","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAY7C,MAAM,UAAU,SAAS,CAAC,MAAqB;IAC7C,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,EAAE,cAAc,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,CAAC,CAAC;IAEtH,4DAA4D;IAC5D,MAAM,UAAU,GAAuC,EAAE,CAAC;IAC1D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7C,UAAU,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,SAAS,CAAC;QACf,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,EAAE;QACV,YAAY,EAAE,EAAE;QAChB,UAAU;QACV,cAAc;QACd,iBAAiB,EAAE,MAAM,CAAC,OAAO,EAAE,iBAAiB;KACrD,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"define-env.js","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"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"}

package/dist/dot.d.ts

@@ -1,10 +1,10 @@
 /**
  * DOT adapter for `@arki/env`.
  *
- * Wraps `defineEnv()` as a `DotPip` so a DOT app can validate its
+ * Wraps `defineEnv()` as a DOT pip so a DOT app can validate its
  * environment alongside any other services. The pip is sync (env
  * validation is sync), so the `boot` hook returns the validated env
- * object synchronously through the standard `services` channel.
+ * object synchronously through the standard provides channel.
  *
  * @example
  * ```ts
@@ -19,11 +19,21 @@
  * console.log(app.services.env.PORT); // number, typed.
  * ```
  *
+ * To mount a second env scope in the same app, rename the published wire
+ * key at the mount site:
+ *
+ * ```ts
+ * import { rename } from '@arki/dot';
+ *
+ * .use(env({ schema: appSchema }))
+ * .use(rename(env({ schema: publicSchema }), { env: 'publicEnv' }, 'public-env'))
+ * ```
+ *
  * The `@arki/dot` package is an OPTIONAL peer of `@arki/env`. Importing
  * this adapter without `@arki/dot` installed will fail at module load —
  * that is intentional: the adapter only makes sense in a DOT app.
  */
-import { type DotPip } from '@arki/dot/pip';
+import { type EmptyShape, type Pip } from '@arki/dot/pip';
 import type { ZodType } from 'zod';
 /**
  * Options for the env DOT adapter.
@@ -34,11 +44,6 @@ import type { ZodType } from 'zod';
 export type EnvDotOptions<TSchema extends Record<string, ZodType>> = {
     /** Zod schemas for each env var the pip validates. */
     readonly schema: TSchema;
-    /**
-     * Pip name override. Defaults to `'env'`. Use this only when
-     * composing multiple env scopes inside the same app (rare).
-     */
-    readonly name?: string;
     /**
      * Forwarded to `defineEnv`. If `true`, the validator is skipped
      * entirely. By default, validation is skipped when `CI` is set or
@@ -46,14 +51,7 @@ export type EnvDotOptions<TSchema extends Record<string, ZodType>> = {
      */
     readonly skipValidation?: boolean;
 };
-/**
- * The shape of services published by the env adapter.
- *
- * The key is configurable via `options.name` (defaults to `'env'`) so
- * downstream pips can pick the right env when multiple env scopes
- * exist. For the default single-env case, `app.services.env` is the
- * validated record.
- */
+/** The shape of services published by the env adapter. */
 export type EnvServices<TSchema extends Record<string, ZodType>> = {
     readonly env: {
         readonly [K in keyof TSchema]: TSchema[K] extends ZodType<infer U> ? U : never;
@@ -63,7 +61,7 @@ export type EnvServices<TSchema extends Record<string, ZodType>> = {
  * Build a DOT pip that validates and publishes a typed `env` service.
  *
  * @param options - Schema + optional config.
- * @returns A `DotPip` that registers an `env`-kind service.
+ * @returns A pip that publishes `services.env`.
  */
-export declare function env<TSchema extends Record<string, ZodType>>(options: EnvDotOptions<TSchema>): DotPip<EnvServices<TSchema>>;
+export declare function env<TSchema extends Record<string, ZodType>>(options: EnvDotOptions<TSchema>): Pip<EmptyShape, EnvServices<TSchema>>;
 //# sourceMappingURL=dot.d.ts.map

package/dist/dot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACnE,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;KAAE,CAAC;CAClG,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAC9B,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAyB9B"}
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAO,KAAK,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACnE,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;KAAE,CAAC;CAClG,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAC9B,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAuBvC"}

package/dist/dot.js

@@ -1,10 +1,10 @@
 /**
  * DOT adapter for `@arki/env`.
  *
- * Wraps `defineEnv()` as a `DotPip` so a DOT app can validate its
+ * Wraps `defineEnv()` as a DOT pip so a DOT app can validate its
  * environment alongside any other services. The pip is sync (env
  * validation is sync), so the `boot` hook returns the validated env
- * object synchronously through the standard `services` channel.
+ * object synchronously through the standard provides channel.
  *
  * @example
  * ```ts
@@ -19,24 +19,32 @@
  * console.log(app.services.env.PORT); // number, typed.
  * ```
  *
+ * To mount a second env scope in the same app, rename the published wire
+ * key at the mount site:
+ *
+ * ```ts
+ * import { rename } from '@arki/dot';
+ *
+ * .use(env({ schema: appSchema }))
+ * .use(rename(env({ schema: publicSchema }), { env: 'publicEnv' }, 'public-env'))
+ * ```
+ *
  * The `@arki/dot` package is an OPTIONAL peer of `@arki/env`. Importing
  * this adapter without `@arki/dot` installed will fail at module load —
  * that is intentional: the adapter only makes sense in a DOT app.
  */
-import { defineDotPip } from '@arki/dot/pip';
+import { pip } from '@arki/dot/pip';
 import { defineEnv } from './core/define-env.js';
 /**
  * Build a DOT pip that validates and publishes a typed `env` service.
  *
  * @param options - Schema + optional config.
- * @returns A `DotPip` that registers an `env`-kind service.
+ * @returns A pip that publishes `services.env`.
  */
 export function env(options) {
-    const name = options.name ?? 'env';
-    return defineDotPip({
-        name,
+    return pip({
+        name: 'env',
         version: '0.1.0',
-        provides: ['env'],
         configure(ctx) {
             ctx.registerService('env', 'env');
         },
@@ -52,7 +60,7 @@ export function env(options) {
             // The runtime guarantee comes from Zod-side validation inside
             // `defineEnv`. No `any` involved — the cast is type-only.
             const envObject = validated;
-            return { services: { env: envObject } };
+            return { env: envObject };
         },
     });
 }

package/dist/dot.js.map

@@ -1 +1 @@
-{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAe,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAoCjD;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CACjB,OAA+B;IAE/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC;IACnC,OAAO,YAAY,CAAuB;QACxC,IAAI;QACJ,OAAO,EAAE,OAAO;QAChB,QAAQ,EAAE,CAAC,KAAK,CAAC;QACjB,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,IAAI;YACF,MAAM,SAAS,GAAG,SAAS,CAAC;gBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,OAAO,EACL,OAAO,CAAC,cAAc,KAAK,SAAS;oBAClC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE;oBAC5C,CAAC,CAAC,SAAS;aAChB,CAAC,CAAC;YACH,oEAAoE;YACpE,kEAAkE;YAClE,8DAA8D;YAC9D,0DAA0D;YAC1D,MAAM,SAAS,GAAG,SAAmD,CAAC;YACtE,OAAO,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;QAC1C,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,GAAG,EAA6B,MAAM,eAAe,CAAC;AAG/D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAwBjD;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CACjB,OAA+B;IAE/B,OAAO,GAAG,CAAC;QACT,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,OAAO;QAChB,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,IAAI;YACF,MAAM,SAAS,GAAG,SAAS,CAAC;gBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,OAAO,EACL,OAAO,CAAC,cAAc,KAAK,SAAS;oBAClC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE;oBAC5C,CAAC,CAAC,SAAS;aAChB,CAAC,CAAC;YACH,oEAAoE;YACpE,kEAAkE;YAClE,8DAA8D;YAC9D,0DAA0D;YAC1D,MAAM,SAAS,GAAG,SAAmD,CAAC;YACtE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/env",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Type-safe environment variable parsing for ARKI — defineEnv() built on @t3-oss/env-core with Zod contracts for common variable shapes.",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,12 @@
   },
   "files": [
     "dist/**",
+    "src/**",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/tests/**",
+    "!src/**/test/**",
+    "!src/**/__tests__/**",
     "README.md",
     "LICENSE",
     "package.json"
@@ -56,7 +62,7 @@
     "zod": "4.3.5"
   },
   "peerDependencies": {
-    "@arki/dot": "^0.1.1"
+    "@arki/dot": "^0.1.2"
   },
   "peerDependenciesMeta": {
     "@arki/dot": {

package/src/contracts/common.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+export const commonContracts = {
+  string: (defaultValue?: string) => {
+    const schema = z.string();
+    return defaultValue ? schema.default(defaultValue) : schema;
+  },
+
+  number: (defaultValue?: number) => {
+    const schema = z.coerce.number();
+    return defaultValue ? schema.default(defaultValue) : schema;
+  },
+
+  port: (defaultValue = 3000) =>
+    z
+      .coerce.number()
+      .min(1, 'Port must be at least 1')
+      .max(65_535, 'Port must be at most 65535')
+      .default(defaultValue),
+
+  nodeEnv: () => z.enum(['development', 'production', 'test']).default('development'),
+
+  boolean: (defaultValue = false) =>
+    z
+      .enum(['true', 'false', '1', '0'])
+      .default(defaultValue ? 'true' : 'false')
+      .transform(val => val === 'true' || val === '1'),
+
+  logLevel: (defaultValue: 'debug' | 'info' | 'warn' | 'error' = 'info') =>
+    z.enum(['debug', 'info', 'warn', 'error']).default(defaultValue),
+};

package/src/contracts/index.ts

@@ -0,0 +1,17 @@
+import { commonContracts } from './common.js';
+import { parseContracts } from './parsing.js';
+import { urlContracts } from './urls.js';
+
+// Unified contracts export
+export const contracts = {
+  ...commonContracts,
+  ...urlContracts,
+  ...parseContracts,
+};
+
+// Individual category exports
+
+
+export {commonContracts} from './common.js';
+export {urlContracts} from './urls.js';
+export {parseContracts} from './parsing.js';

package/src/contracts/parsing.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const parseContracts = {
+  json: <T extends z.ZodType>(schema: T) =>
+    z.string().transform((str) => {
+      const parsed = JSON.parse(str);
+      return schema.parse(parsed) as z.infer<T>;
+    }),
+
+  csvArray: <T extends z.ZodType>(itemSchema: T) =>
+    z.preprocess(
+      (val) => {
+        if (typeof val !== 'string') return val;
+        return val.split(',').map((s) => s.trim());
+      },
+      z.array(itemSchema)
+    ),
+
+  csvSet: <T extends z.ZodType>(itemSchema: T) =>
+    z.preprocess(
+      (val) => {
+        if (typeof val !== 'string') return val;
+        return [...new Set(val.split(',').map((s) => s.trim()))];
+      },
+      z.array(itemSchema)
+    ),
+};

package/src/contracts/urls.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+export const urlContracts = {
+  url: (defaultValue?: string) => {
+    const schema = z.url();
+    return defaultValue ? schema.default(defaultValue) : schema;
+  },
+
+  databaseUrl: () =>
+    z
+      .url()
+      .refine(
+        url => url.startsWith('postgres://') || url.startsWith('postgresql://'),
+        'Database URL must start with postgres:// or postgresql://',
+      ),
+
+  redisUrl: () =>
+    z
+      .url()
+      .refine(
+        url => url.startsWith('redis://') || url.startsWith('rediss://'),
+        'Redis URL must start with redis:// or rediss://',
+      ),
+};

package/src/core/define-env.ts

@@ -0,0 +1,134 @@
+import { createEnv } from '@t3-oss/env-core';
+import type { CreateEnv, DefaultCombinedSchema } from '@t3-oss/env-core';
+import type { ZodType } from 'zod';
+
+/** The issue shape t3-oss hands to `onValidationError`, derived so it stays in sync with the lib. */
+type ValidationIssues = Parameters<
+  NonNullable<Parameters<typeof createEnv>[0]['onValidationError']>
+>[0];
+
+/**
+ * Fold validation issues into a human-legible, log-pipeline-safe string. The t3-oss default handler
+ * logs `issues` as a raw object, which platforms like Coolify collapse to `[Object]` — so the var
+ * that actually failed never reaches the logs. A flat `  path: message` list survives transport.
+ */
+function formatIssues(name: string | undefined, issues: ValidationIssues): string {
+  const label = name ? `[${name}] ` : '';
+  const lines = issues.map(issue => {
+    const path = (issue.path ?? [])
+      .map(seg => (typeof seg === 'object' && seg !== null && 'key' in seg ? String(seg.key) : String(seg)))
+      .join('.');
+    return `  ${path || '(root)'}: ${issue.message}`;
+  });
+  return `❌ ${label}Invalid environment variables:\n${lines.join('\n')}`;
+}
+
+/**
+ * Thin, type-preserving wrapper over `@t3-oss/env-core`'s `createEnv`. Generic over the server,
+ * client, shared and composed schemas so the parsed env keeps its exact inferred types — the wrapper
+ * adds the ARKI defaults (auto `runtimeEnv`, prod-safe `skipValidation`, a legible labelled error
+ * handler) without widening any value to `unknown`.
+ *
+ * `TPrefix` is kept as a string-literal generic on purpose: `createEnv` uses it to enforce that
+ * client keys (and only client keys) carry the prefix. Widening it to `string` would make every
+ * server key collapse to a type-level `ErrorMessage`, so the prefix must stay a literal.
+ */
+export function defineEnv<
+  TServer extends Record<string, ZodType>,
+  TClient extends Record<string, ZodType> = NonNullable<unknown>,
+  TShared extends Record<string, ZodType> = NonNullable<unknown>,
+  const TPrefix extends string = '',
+  const TExtends extends Array<Record<string, unknown>> = [],
+>(config: {
+  /**
+   * Label shown in validation-error logs, e.g. `'@acme/backend'`. Without it a misconfigured
+   * deploy logs a bare "Invalid environment variables" with no hint which env failed — exactly the
+   * blind failure this wrapper exists to prevent.
+   */
+  name?: string;
+  server: TServer;
+  /** Client-side schema. Every key must start with `clientPrefix` (enforced by `createEnv`). */
+  client?: TClient;
+  /** Prefix client keys must carry, e.g. `'VITE_'`. Defaults to `''` (no client vars). */
+  clientPrefix?: TPrefix;
+  /** Shared vars available to both client and server, unprefixed (e.g. `NODE_ENV`). */
+  shared?: TShared;
+  /**
+   * Already-built envs to compose in (e.g. `@arki/auth`, `@arki/db`). Their parsed variables merge
+   * into the result with full types; each was validated by its own `createEnv` at import time.
+   */
+  extends?: TExtends;
+  /**
+   * Explicit runtime source. Omit it and `defineEnv` auto-builds one by reading `process.env` for
+   * every declared key — correct for any server-side env. Provide it only when the auto-build would
+   * be wrong: Vite/`start` apps whose client vars come from `import.meta.env` in the browser, or
+   * keys with a fallback/alias (e.g. `DB_URL: process.env.DB_URL ?? process.env.DATABASE_URL`).
+   */
+  runtimeEnv?: Record<string, string | boolean | number | undefined>;
+  options?: {
+    skipValidation?: boolean;
+    /**
+     * Treat empty-string env values as `undefined` so defaults apply (e.g. `PORT=` in `.env`, or a
+     * Docker arg baked as `X=""`). Defaults to `true` — set `false` only if an app intentionally
+     * accepts `""` as a valid required string.
+     */
+    emptyStringAsUndefined?: boolean;
+    onValidationError?: (issues: ValidationIssues) => never;
+  };
+}): CreateEnv<DefaultCombinedSchema<TServer, TClient, TShared>, TExtends> {
+  const skipValidation =
+    config.options?.skipValidation ?? (!!process.env.CI || process.env.NODE_ENV !== 'development');
+
+  // Use the caller's explicit runtimeEnv when supplied (Vite client vars via import.meta.env, or
+  // fallback aliases). Otherwise auto-build from every declared key (server + client + shared);
+  // createEnv tolerates keys absent from process.env (they parse as undefined → optional/default).
+  let runtimeEnv: Record<string, string | boolean | number | undefined>;
+  if (config.runtimeEnv) {
+    runtimeEnv = config.runtimeEnv;
+  } else {
+    runtimeEnv = {};
+    for (const key of Object.keys(config.server)) {
+      runtimeEnv[key] = process.env[key];
+    }
+    for (const key of Object.keys(config.client ?? {})) {
+      runtimeEnv[key] = process.env[key];
+    }
+    for (const key of Object.keys(config.shared ?? {})) {
+      runtimeEnv[key] = process.env[key];
+    }
+  }
+
+  const onValidationError =
+    config.options?.onValidationError ??
+    ((issues: ValidationIssues): never => {
+      const message = formatIssues(config.name, issues);
+      console.error(message);
+      throw new Error(message);
+    });
+
+  // `createEnv`'s `server`/`client` params are conditional on `clientPrefix` being a *concrete*
+  // string literal; inside a generic wrapper `TPrefix` is abstract, so the body cannot be verified
+  // for all prefixes and the call argument must be asserted once. The PUBLIC contract stays exact:
+  // the explicit return type above reconstructs `createEnv`'s own result from the generics, and the
+  // caller's `server`/`client`/`extends` are fully type-checked against `TServer`/`TClient`/`TExtends`
+  // at the call site. This is the only seam where types are asserted — value types are never widened.
+  const options = {
+    shared: config.shared ?? {},
+    extends: config.extends,
+    server: config.server,
+    client: config.client ?? {},
+    clientPrefix: config.clientPrefix ?? '',
+    runtimeEnv,
+    skipValidation,
+    // Default ON: in containerized deploys an unset var is baked as "" (e.g. Docker `ENV X=${X}`
+    // with no build arg), not left absent. Treating "" as undefined lets `.default()`/`.optional()`
+    // apply as intended instead of failing format checks like `z.url()` on an empty string.
+    emptyStringAsUndefined: config.options?.emptyStringAsUndefined ?? true,
+    onValidationError,
+  } satisfies Record<string, unknown>;
+
+  return createEnv(options as Parameters<typeof createEnv>[0]) as CreateEnv<
+    DefaultCombinedSchema<TServer, TClient, TShared>,
+    TExtends
+  >;
+}

package/src/core/index.ts

@@ -0,0 +1,2 @@
+export { defineEnv } from './define-env.js';
+export { contracts } from '../contracts/index.js';

package/src/dot.ts

@@ -0,0 +1,95 @@
+/**
+ * DOT adapter for `@arki/env`.
+ *
+ * Wraps `defineEnv()` as a DOT pip so a DOT app can validate its
+ * environment alongside any other services. The pip is sync (env
+ * validation is sync), so the `boot` hook returns the validated env
+ * object synchronously through the standard provides channel.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ * import { env } from '@arki/env/dot';
+ * import { z } from 'zod';
+ *
+ * const app = await defineApp('my-app')
+ *   .use(env({ schema: { PORT: z.coerce.number().default(3000) } }))
+ *   .boot();
+ *
+ * console.log(app.services.env.PORT); // number, typed.
+ * ```
+ *
+ * To mount a second env scope in the same app, rename the published wire
+ * key at the mount site:
+ *
+ * ```ts
+ * import { rename } from '@arki/dot';
+ *
+ * .use(env({ schema: appSchema }))
+ * .use(rename(env({ schema: publicSchema }), { env: 'publicEnv' }, 'public-env'))
+ * ```
+ *
+ * The `@arki/dot` package is an OPTIONAL peer of `@arki/env`. Importing
+ * this adapter without `@arki/dot` installed will fail at module load —
+ * that is intentional: the adapter only makes sense in a DOT app.
+ */
+
+import { pip, type EmptyShape, type Pip } from '@arki/dot/pip';
+import type { ZodType } from 'zod';
+
+import { defineEnv } from './core/define-env.js';
+
+/**
+ * Options for the env DOT adapter.
+ *
+ * @typeParam TSchema - The shape of the `server` schema record. The
+ *   resulting `app.services.env` is typed from this.
+ */
+export type EnvDotOptions<TSchema extends Record<string, ZodType>> = {
+  /** Zod schemas for each env var the pip validates. */
+  readonly schema: TSchema;
+  /**
+   * Forwarded to `defineEnv`. If `true`, the validator is skipped
+   * entirely. By default, validation is skipped when `CI` is set or
+   * `NODE_ENV !== 'development'`.
+   */
+  readonly skipValidation?: boolean;
+};
+
+/** The shape of services published by the env adapter. */
+export type EnvServices<TSchema extends Record<string, ZodType>> = {
+  readonly env: { readonly [K in keyof TSchema]: TSchema[K] extends ZodType<infer U> ? U : never };
+};
+
+/**
+ * Build a DOT pip that validates and publishes a typed `env` service.
+ *
+ * @param options - Schema + optional config.
+ * @returns A pip that publishes `services.env`.
+ */
+export function env<TSchema extends Record<string, ZodType>>(
+  options: EnvDotOptions<TSchema>,
+): Pip<EmptyShape, EnvServices<TSchema>> {
+  return pip({
+    name: 'env',
+    version: '0.1.0',
+    configure(ctx) {
+      ctx.registerService('env', 'env');
+    },
+    boot() {
+      const validated = defineEnv({
+        server: options.schema,
+        options:
+          options.skipValidation !== undefined
+            ? { skipValidation: options.skipValidation }
+            : undefined,
+      });
+      // `defineEnv` returns a Proxy from `@t3-oss/env-core`; we narrow it
+      // to the schema-derived shape so downstream typing flows through.
+      // The runtime guarantee comes from Zod-side validation inside
+      // `defineEnv`. No `any` involved — the cast is type-only.
+      const envObject = validated as unknown as EnvServices<TSchema>['env'];
+      return { env: envObject };
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// Re-export contracts for convenience
+export { contracts } from './contracts/index.js';