vite-plugin-typed-env 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm view:*)",
+      "WebFetch(domain:github.com)"
+    ]
+  }
+}

package/.prettierrc.cjs

@@ -0,0 +1,14 @@
+module.exports = {
+  printWidth: 120,
+  tabWidth: 2,
+  useTabs: false,
+  semi: false,
+  vueIndentScriptAndStyle: true,
+  trailingComma: 'none',
+  singleQuote: true,
+  bracketSpacing: true,
+  bracketSameLine: true,
+  arrowParens: 'always',
+  requirePragma: false,
+  insertPragma: false
+}

package/README.md

@@ -0,0 +1,194 @@
+# vite-plugin-typed-env
+
+A Vite plugin that automatically generates TypeScript types and Zod schemas from your `.env` files.
+
+## Features
+
+- **Auto-generated TypeScript types** - `env.d.ts` with proper type inference
+- **Zod schema generation** - Runtime validation with `env.schema.ts`
+- **Runtime loader** - `env.ts` that validates and exposes typed environment variables
+- **Vite `import.meta.env` augmentation** - Full type support for Vite's env system
+- **Hot reload** - Automatically regenerate types when `.env` files change
+- **Smart type inference** - Auto-detects types from values (boolean, number, URL, arrays, etc.)
+- **Annotation support** - Fine-grained type control via special comments
+
+## Installation
+
+```bash
+npm install vite-plugin-typed-env -D
+```
+
+## Usage
+
+### 1. Add to Vite config
+
+```ts
+// vite.config.ts
+import envTs from 'vite-plugin-typed-env'
+
+export default defineConfig({
+  plugins: [envTs()]
+})
+```
+
+### 2. Write your `.env` file
+
+```env
+# Database configuration
+DATABASE_URL=postgres://localhost:5432/mydb
+
+# API keys
+# @optional
+API_KEY=
+
+# Server settings
+# @type: port
+# @desc: The port the server listens on
+PORT=3000
+
+# Feature flags
+# @type: boolean
+DEBUG=true
+
+# Allowed origins (comma-separated)
+# @type: string[]
+ALLOWED_ORIGINS=http://localhost,https://example.com
+```
+
+### 3. Generated files
+
+The plugin generates three files in your configured output directory (default: `src/`):
+
+#### `env.d.ts` - TypeScript declarations
+
+```ts
+interface ImportMetaEnv {
+  readonly DATABASE_URL: string
+  readonly API_KEY?: string
+  /** The port the server listens on */
+  readonly PORT: number
+  readonly DEBUG: boolean
+  readonly ALLOWED_ORIGINS: string[]
+}
+```
+
+#### `env.schema.ts` - Zod validation schema
+
+```ts
+import { z } from 'zod'
+
+export const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  API_KEY: z.string().optional(),
+  // The port the server listens on
+  PORT: z.coerce.number().int().min(1).max(65535),
+  DEBUG: z.enum(['true', 'false', '1', '0']).transform((v) => v === 'true' || v === '1'),
+  ALLOWED_ORIGINS: z.string().transform((v) => v.split(',').map((s) => s.trim()))
+})
+
+export type Env = z.infer<typeof envSchema>
+```
+
+#### `env.ts` - Runtime loader
+
+```ts
+import { envSchema } from './env.schema'
+
+const _parsed = envSchema.safeParse(import.meta.env)
+
+if (!_parsed.success) {
+  throw new Error('[env-ts] Invalid environment variables')
+}
+
+export const env = _parsed.data
+export default env
+```
+
+### 4. Use in your code
+
+```ts
+// With schema validation
+import env from './env'
+
+console.log(env.PORT) // fully typed!
+
+// Or use Vite's import.meta.env
+console.log(import.meta.env.PORT) // also typed!
+```
+
+## Annotations
+
+Control type generation with special comments:
+
+| Annotation  | Example                | Description                      |
+| ----------- | ---------------------- | -------------------------------- |
+| `@type`     | `# @type: number`      | Override inferred type           |
+| `@optional` | `# @optional`          | Mark variable as optional        |
+| `@default`  | `# @default: 8080`     | Provide default value            |
+| `@desc`     | `# @desc: Server port` | Add description (shows in JSDoc) |
+
+### Supported `@type` values
+
+| Type          | TypeScript          | Zod Schema                                            |
+| ------------- | ------------------- | ----------------------------------------------------- |
+| `number`      | `number`            | `z.coerce.number()`                                   |
+| `boolean`     | `boolean`           | `z.enum([...]).transform()`                           |
+| `url`         | `string`            | `z.string().url()`                                    |
+| `port`        | `number`            | `z.coerce.number().int().min(1).max(65535)`           |
+| `email`       | `string`            | `z.string().email()`                                  |
+| `string[]`    | `string[]`          | `z.string().transform(v => v.split(','))`             |
+| `number[]`    | `number[]`          | `z.string().transform(v => v.split(',').map(Number))` |
+| `enum(a,b,c)` | `'a' \| 'b' \| 'c'` | `z.enum(['a','b','c'])`                               |
+
+## Options
+
+```ts
+envTs({
+  // Generate Zod schema file
+  // @default 'zod'
+  schema: 'zod' | false,
+
+  // Output directory (relative to project root)
+  // @default 'src'
+  output: 'src',
+
+  // Augment Vite's ImportMetaEnv type
+  // @default true
+  augmentImportMeta: true,
+
+  // Fail build if required vars are missing
+  // @default true
+  strict: true,
+
+  // Additional .env files to watch
+  // @default []
+  envFiles: ['.env.custom']
+})
+```
+
+## Type Inference
+
+The plugin automatically infers types from values:
+
+| Value Pattern                          | Inferred Type                  |
+| -------------------------------------- | ------------------------------ |
+| `true`, `false`, `1`, `0`, `yes`, `no` | `boolean`                      |
+| Pure numbers (`3000`, `3.14`)          | `number`                       |
+| URLs (`http://...`, `postgres://...`)  | `string` (with URL validation) |
+| Comma-separated numbers (`1,2,3`)      | `number[]`                     |
+| Comma-separated strings (`a,b,c`)      | `string[]`                     |
+| Empty value                            | `string` (optional)            |
+| Everything else                        | `string`                       |
+
+## Env File Priority
+
+Files are loaded in this order (later overrides earlier):
+
+1. `.env`
+2. `.env.local`
+3. `.env.{NODE_ENV}`
+4. `.env.{NODE_ENV}.local`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "vite-plugin-typed-env",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"*.ts\" \"*.cjs\" \"*.json\" \"*.md\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"*.ts\" \"*.cjs\" \"*.json\" \"*.md\""
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "prettier": "^3.8.2",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "vite": ">=4.0.0"
+  }
+}

package/src/generator.ts

@@ -0,0 +1,119 @@
+import type { EnvEntry } from './parser'
+import type { InferredType } from './inferrer'
+
+export interface GenerateOptions {
+  schema: 'zod' | 'valibot' | false
+  /** 是否扩展 Vite 的 ImportMetaEnv */
+  augmentImportMeta: boolean
+}
+
+interface EntryWithType {
+  entry: EnvEntry
+  inferred: InferredType
+}
+
+// ─── env.d.ts ────────────────────────────────────────────────────────────────
+
+export function generateDts(items: EntryWithType[], options: GenerateOptions): string {
+  const lines: string[] = []
+
+  lines.push(`// Auto-generated by vite-plugin-typed-env. DO NOT EDIT.`)
+  lines.push(`// Re-run vite to regenerate this file.`)
+  lines.push(``)
+
+  if (options.augmentImportMeta) {
+    lines.push(`/// <reference types="vite/client" />`)
+    lines.push(``)
+    lines.push(`interface ImportMetaEnv {`)
+    for (const { entry, inferred } of items) {
+      if (entry.annotations.description) {
+        lines.push(`  /** ${entry.annotations.description} */`)
+      }
+      const opt = inferred.isOptional ? '?' : ''
+      lines.push(`  readonly ${entry.key}${opt}: ${inferred.tsType}`)
+    }
+    lines.push(`}`)
+    lines.push(``)
+    lines.push(`interface ImportMeta {`)
+    lines.push(`  readonly env: ImportMetaEnv`)
+    lines.push(`}`)
+  } else {
+    lines.push(`export interface Env {`)
+    for (const { entry, inferred } of items) {
+      if (entry.annotations.description) {
+        lines.push(`  /** ${entry.annotations.description} */`)
+      }
+      const opt = inferred.isOptional ? '?' : ''
+      lines.push(`  ${entry.key}${opt}: ${inferred.tsType}`)
+    }
+    lines.push(`}`)
+  }
+
+  return lines.join('\n')
+}
+
+// ─── env.schema.ts ───────────────────────────────────────────────────────────
+
+export function generateZodSchema(items: EntryWithType[]): string {
+  const lines: string[] = []
+
+  lines.push(`// Auto-generated by vite-plugin-typed-env. DO NOT EDIT.`)
+  lines.push(`import { z } from 'zod'`)
+  lines.push(``)
+  lines.push(`export const envSchema = z.object({`)
+
+  for (const { entry, inferred } of items) {
+    if (entry.annotations.description) {
+      lines.push(`  // ${entry.annotations.description}`)
+    }
+    lines.push(`  ${entry.key}: ${inferred.zodSchema},`)
+  }
+
+  lines.push(`})`)
+  lines.push(``)
+  lines.push(`export type Env = z.infer<typeof envSchema>`)
+
+  return lines.join('\n')
+}
+
+// ─── env.ts (runtime loader) ─────────────────────────────────────────────────
+
+export function generateLoader(items: EntryWithType[], options: GenerateOptions): string {
+  const lines: string[] = []
+
+  lines.push(`// Auto-generated by vite-plugin-typed-env. DO NOT EDIT.`)
+  lines.push(``)
+
+  if (options.schema === 'zod') {
+    lines.push(`import { envSchema } from './env.schema'`)
+    lines.push(``)
+    lines.push(`const _parsed = envSchema.safeParse(import.meta.env)`)
+    lines.push(``)
+    lines.push(`if (!_parsed.success) {`)
+    lines.push(`  const errors = _parsed.error.flatten().fieldErrors`)
+    lines.push(`  const msg = Object.entries(errors)`)
+    lines.push(`    .map(([k, v]) => \`  \${k}: \${(v as string[]).join(', ')}\`)`)
+    lines.push(`    .join('\\n')`)
+    lines.push(`  throw new Error(\`[env-ts] Invalid environment variables:\\n\${msg}\`)`)
+    lines.push(`}`)
+    lines.push(``)
+    lines.push(`export const env = _parsed.data`)
+    lines.push(`export default env`)
+  } else {
+    // 无 schema 时，直接做简单的必填检查
+    const required = items.filter(({ inferred }) => !inferred.isOptional)
+    lines.push(`const _raw = import.meta.env`)
+    lines.push(``)
+    if (required.length > 0) {
+      lines.push(`const _required = [${required.map(({ entry }) => `'${entry.key}'`).join(', ')}] as const`)
+      lines.push(`for (const key of _required) {`)
+      lines.push(`  if (!_raw[key]) throw new Error(\`[env-ts] Missing required env var: \${key}\`)`)
+      lines.push(`}`)
+      lines.push(``)
+    }
+    lines.push(`export const env = _raw as import('./env').Env`)
+    lines.push(`export default env`)
+  }
+
+  return lines.join('\n')
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { Plugin, ResolvedConfig } from 'vite'
+import { parseEnvFile, type EnvEntry } from './parser'
+import { inferType } from './inferrer'
+import { generateDts, generateZodSchema, generateLoader } from './generator'
+
+export interface EnvTsOptions {
+  /**
+   * 生成 Zod schema 文件
+   * @default 'zod'
+   */
+  schema?: 'zod' | false
+  /**
+   * 生成文件的输出目录（相对于项目根目录）
+   * @default 'src'
+   */
+  output?: string
+  /**
+   * 是否扩展 Vite 的 ImportMetaEnv 类型
+   * 开启后 import.meta.env.YOUR_VAR 自动有类型
+   * @default true
+   */
+  augmentImportMeta?: boolean
+  /**
+   * 缺失必填变量时是否让构建失败
+   * @default true
+   */
+  strict?: boolean
+  /**
+   * 额外监听的 .env 文件（默认自动检测 .env, .env.local 等）
+   */
+  envFiles?: string[]
+}
+
+// ─── 核心函数 ─────────────────────────────────────────────────────────────────
+
+export async function generateTypes(envDir: string, outputDir: string, options: Required<EnvTsOptions>): Promise<void> {
+  // 1. 找到所有 .env 文件（按优先级顺序读取，后面的覆盖前面的）
+  const envFileNames = [
+    '.env',
+    '.env.local',
+    `.env.${process.env.NODE_ENV ?? 'development'}`,
+    `.env.${process.env.NODE_ENV ?? 'development'}.local`,
+    ...options.envFiles
+  ]
+
+  const entries = new Map<string, EnvEntry>()
+
+  for (const fileName of envFileNames) {
+    const filePath = path.join(envDir, fileName)
+    if (!fs.existsSync(filePath)) continue
+
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const parsed = parseEnvFile(content)
+
+    // 后读的文件覆盖先读的（保留注释/annotation）
+    for (const entry of parsed) {
+      entries.set(entry.key, entry)
+    }
+  }
+
+  if (entries.size === 0) {
+    console.warn('[env-ts] No .env files found or all are empty, skipping generation.')
+    return
+  }
+
+  // 2. 对每个变量做类型推断
+  const items = Array.from(entries.values()).map((entry) => ({
+    entry,
+    inferred: inferType(entry)
+  }))
+
+  // strict 模式：检查必填变量在 process.env 里是否真实存在
+  if (options.strict) {
+    const missing = items
+      .filter(({ inferred }) => !inferred.isOptional && inferred.defaultValue === undefined)
+      .filter(({ entry }) => {
+        const v = process.env[entry.key]
+        return v === undefined || v === ''
+      })
+      .map(({ entry }) => entry.key)
+
+    if (missing.length > 0) {
+      // 开发时警告，构建时报错
+      const msg = `[env-ts] Missing required env variables: ${missing.join(', ')}`
+      if (process.env.NODE_ENV === 'production') {
+        throw new Error(msg)
+      } else {
+        console.warn(msg)
+      }
+    }
+  }
+
+  // 3. 确保输出目录存在
+  fs.mkdirSync(outputDir, { recursive: true })
+
+  const genOptions = {
+    schema: options.schema,
+    augmentImportMeta: options.augmentImportMeta
+  }
+
+  // 4. 生成 env.d.ts
+  const dtsContent = generateDts(items, genOptions)
+  writeIfChanged(path.join(outputDir, 'env.d.ts'), dtsContent)
+
+  // 5. 生成 env.schema.ts（可选）
+  if (options.schema === 'zod') {
+    const schemaContent = generateZodSchema(items)
+    writeIfChanged(path.join(outputDir, 'env.schema.ts'), schemaContent)
+  }
+
+  // 6. 生成 env.ts（运行时 loader）
+  const loaderContent = generateLoader(items, genOptions)
+  writeIfChanged(path.join(outputDir, 'env.ts'), loaderContent)
+
+  console.log(`[env-ts] Generated ${items.length} env types → ${path.relative(process.cwd(), outputDir)}/`)
+}
+
+// 只在内容变化时写文件，避免触发不必要的热更新
+function writeIfChanged(filePath: string, content: string): void {
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf-8')
+    if (existing === content) return
+  }
+  fs.writeFileSync(filePath, content, 'utf-8')
+}
+
+// ─── Vite 插件 ────────────────────────────────────────────────────────────────
+
+export default function envTs(userOptions: EnvTsOptions = {}): Plugin {
+  const options: Required<EnvTsOptions> = {
+    schema: 'zod',
+    output: 'src',
+    augmentImportMeta: true,
+    strict: true,
+    envFiles: [],
+    ...userOptions
+  }
+
+  let config: ResolvedConfig
+  let outputDir: string
+
+  return {
+    name: 'vite-plugin-typed-env',
+    enforce: 'pre', // 在其他插件之前运行，确保类型文件先生成
+
+    configResolved(resolvedConfig) {
+      config = resolvedConfig
+      outputDir = path.resolve(config.root, options.output)
+    },
+
+    async buildStart() {
+      const envDir = config.envDir === false ? config.root : config.envDir
+      await generateTypes(envDir, outputDir, options)
+    },
+
+    async handleHotUpdate({ file, server }) {
+      if (!file) return
+
+      const fileName = path.basename(file)
+      const isEnvFile = fileName.startsWith('.env') || options.envFiles.includes(file)
+
+      if (!isEnvFile) return
+
+      console.log(`[env-ts] Detected change in ${fileName}, regenerating...`)
+      const envDir = config.envDir === false ? config.root : config.envDir
+      await generateTypes(envDir, outputDir, options)
+
+      // 通知 client 有文件更新（触发 TS 语言服务刷新）
+      server.hot.send({ type: 'full-reload' })
+    }
+  }
+}

package/src/inferrer.ts

@@ -0,0 +1,165 @@
+import type { EnvEntry } from './parser'
+
+export interface InferredType {
+  tsType: string // TypeScript 类型字符串
+  zodSchema: string // Zod schema 字符串
+  isOptional: boolean
+  defaultValue?: string
+}
+
+// 判断是否是布尔值
+function isBoolean(v: string): boolean {
+  return ['true', 'false', '1', '0', 'yes', 'no'].includes(v.toLowerCase())
+}
+
+// 判断是否是纯数字
+function isNumber(v: string): boolean {
+  return v !== '' && !isNaN(Number(v))
+}
+
+// 判断是否是 URL
+function isUrl(v: string): boolean {
+  try {
+    new URL(v)
+    return v.startsWith('http://') || v.startsWith('https://') || v.includes('://') // postgres://, redis:// 等
+  } catch {
+    return false
+  }
+}
+
+// 判断是否是逗号分隔的数字列表
+function isNumberArray(v: string): boolean {
+  if (!v.includes(',')) return false
+  return v.split(',').every((s) => isNumber(s.trim()))
+}
+
+// 判断是否是逗号分隔的字符串列表
+function isStringArray(v: string): boolean {
+  return v.includes(',') && v.split(',').length > 1
+}
+
+// 解析 @type 注释指令
+function inferFromAnnotation(ann: string): Pick<InferredType, 'tsType' | 'zodSchema'> | null {
+  // @type: enum(a, b, c)
+  const enumMatch = ann.match(/^enum\((.+)\)$/)
+  if (enumMatch) {
+    const values = enumMatch[1].split(',').map((s) => s.trim())
+    const tsLiterals = values.map((v) => `'${v}'`).join(' | ')
+    const zodValues = values.map((v) => `'${v}'`).join(', ')
+    return {
+      tsType: tsLiterals,
+      zodSchema: `z.enum([${zodValues}])`
+    }
+  }
+
+  // @type: number[]
+  if (ann === 'number[]') {
+    return {
+      tsType: 'number[]',
+      zodSchema: `z.string().transform(v => v.split(',').map(Number))`
+    }
+  }
+
+  // @type: string[]
+  if (ann === 'string[]') {
+    return {
+      tsType: 'string[]',
+      zodSchema: `z.string().transform(v => v.split(','))`
+    }
+  }
+
+  // @type: url
+  if (ann === 'url') {
+    return { tsType: 'string', zodSchema: `z.string().url()` }
+  }
+
+  // @type: number
+  if (ann === 'number') {
+    return { tsType: 'number', zodSchema: `z.coerce.number()` }
+  }
+
+  // @type: boolean
+  if (ann === 'boolean') {
+    return {
+      tsType: 'boolean',
+      zodSchema: `z.enum(['true','false','1','0']).transform(v => v === 'true' || v === '1')`
+    }
+  }
+
+  // @type: port
+  if (ann === 'port') {
+    return { tsType: 'number', zodSchema: `z.coerce.number().int().min(1).max(65535)` }
+  }
+
+  // @type: email
+  if (ann === 'email') {
+    return { tsType: 'string', zodSchema: `z.string().email()` }
+  }
+
+  return null
+}
+
+// 从值自动推断类型
+function inferFromValue(value: string): Pick<InferredType, 'tsType' | 'zodSchema'> {
+  if (value === '') {
+    return { tsType: 'string', zodSchema: 'z.string()' }
+  }
+
+  if (isBoolean(value)) {
+    return {
+      tsType: 'boolean',
+      zodSchema: `z.enum(['true','false','1','0','yes','no']).transform(v => ['true','1','yes'].includes(v.toLowerCase()))`
+    }
+  }
+
+  if (isNumber(value)) {
+    // 区分整数和浮点
+    const schema = Number.isInteger(Number(value)) ? 'z.coerce.number().int()' : 'z.coerce.number()'
+    return { tsType: 'number', zodSchema: schema }
+  }
+
+  if (isNumberArray(value)) {
+    return {
+      tsType: 'number[]',
+      zodSchema: `z.string().transform(v => v.split(',').map(Number))`
+    }
+  }
+
+  if (isUrl(value)) {
+    return { tsType: 'string', zodSchema: 'z.string().url()' }
+  }
+
+  if (isStringArray(value)) {
+    return {
+      tsType: 'string[]',
+      zodSchema: `z.string().transform(v => v.split(',').map(s => s.trim()))`
+    }
+  }
+
+  return { tsType: 'string', zodSchema: 'z.string().min(1)' }
+}
+
+export function inferType(entry: EnvEntry): InferredType {
+  const { value, annotations } = entry
+  const isOptional = annotations.optional === true || value === ''
+
+  // 优先使用 @type 注释
+  const fromAnnotation = annotations.type ? inferFromAnnotation(annotations.type) : null
+
+  const base = fromAnnotation ?? inferFromValue(value)
+
+  let zodSchema = base.zodSchema
+  // 处理 optional 和 default
+  if (annotations.default !== undefined) {
+    zodSchema = `${zodSchema}.default('${annotations.default}')`
+  } else if (isOptional) {
+    zodSchema = `${zodSchema}.optional()`
+  }
+
+  return {
+    tsType: base.tsType,
+    zodSchema,
+    isOptional,
+    defaultValue: annotations.default
+  }
+}

package/src/parser.ts

@@ -0,0 +1,72 @@
+export interface EnvEntry {
+  key: string
+  value: string
+  annotations: Annotations
+  comment: string
+}
+
+export interface Annotations {
+  type?: string // @type: url | enum(a,b,c) | number[] ...
+  optional?: boolean // @optional
+  default?: string // @default: foo
+  description?: string // @desc: some description
+}
+
+const ANNOTATION_RE = /^#\s*@(\w+)(?::\s*(.+))?$/
+
+function parseAnnotations(lines: string[]): Annotations {
+  const ann: Annotations = {}
+  for (const line of lines) {
+    const m = line.match(ANNOTATION_RE)
+    if (!m) continue
+    const [, key, value] = m
+    if (key === 'optional') ann.optional = true
+    else if (key === 'type' && value) ann.type = value.trim()
+    else if (key === 'default' && value) ann.default = value.trim()
+    else if (key === 'desc' && value) ann.description = value.trim()
+  }
+  return ann
+}
+
+export function parseEnvFile(content: string): EnvEntry[] {
+  const lines = content.split('\n')
+  const entries: EnvEntry[] = []
+  const pendingComments: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i].trim()
+
+    if (raw === '') {
+      pendingComments.length = 0
+      continue
+    }
+
+    if (raw.startsWith('#')) {
+      pendingComments.push(raw)
+      continue
+    }
+
+    const eqIdx = raw.indexOf('=')
+    if (eqIdx === -1) continue
+
+    const key = raw.slice(0, eqIdx).trim()
+    let value = raw.slice(eqIdx + 1).trim()
+
+    // 去除引号
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1)
+    }
+
+    const annotations = parseAnnotations(pendingComments)
+    const description = pendingComments
+      .filter((l) => !ANNOTATION_RE.test(l))
+      .map((l) => l.replace(/^#\s*/, ''))
+      .join(' ')
+      .trim()
+
+    entries.push({ key, value, annotations: { ...annotations, description: description || undefined }, comment: '' })
+    pendingComments.length = 0
+  }
+
+  return entries
+}

package/tests/index.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from 'vitest'
+import { parseEnvFile } from '../src/parser.js'
+import { inferType } from '../src/inferrer.js'
+import { generateDts, generateZodSchema } from '../src/generator.js'
+
+// ─── Parser ──────────────────────────────────────────────────────────────────
+
+describe('parseEnvFile', () => {
+  it('parses basic key=value', () => {
+    const result = parseEnvFile('PORT=3000\nHOST=localhost')
+    expect(result).toHaveLength(2)
+    expect(result[0]).toMatchObject({ key: 'PORT', value: '3000' })
+    expect(result[1]).toMatchObject({ key: 'HOST', value: 'localhost' })
+  })
+
+  it('strips quotes', () => {
+    const result = parseEnvFile(`DB_URL="postgres://localhost/mydb"`)
+    expect(result[0].value).toBe('postgres://localhost/mydb')
+  })
+
+  it('parses @type annotation', () => {
+    const result = parseEnvFile(`# @type: enum(info, warn, error)\nLOG_LEVEL=info`)
+    expect(result[0].annotations.type).toBe('enum(info, warn, error)')
+  })
+
+  it('parses @optional annotation', () => {
+    const result = parseEnvFile(`# @optional\nSENTRY_DSN=`)
+    expect(result[0].annotations.optional).toBe(true)
+  })
+
+  it('parses @default annotation', () => {
+    const result = parseEnvFile(`# @default: 3000\nPORT=`)
+    expect(result[0].annotations.default).toBe('3000')
+  })
+
+  it('ignores empty lines and resets comment buffer', () => {
+    const result = parseEnvFile(`# @optional\n\nPORT=3000`)
+    expect(result[0].annotations.optional).toBeUndefined()
+  })
+
+  it('parses description comment', () => {
+    const result = parseEnvFile(`# Database connection string\nDATABASE_URL=postgres://localhost/db`)
+    expect(result[0].annotations.description).toBe('Database connection string')
+  })
+})
+
+// ─── Inferrer ────────────────────────────────────────────────────────────────
+
+describe('inferType', () => {
+  const make = (value: string, annType?: string, optional?: boolean) =>
+    inferType({
+      key: 'TEST',
+      value,
+      comment: '',
+      annotations: { type: annType, optional }
+    })
+
+  it('infers number from numeric string', () => {
+    const r = make('3000')
+    expect(r.tsType).toBe('number')
+    expect(r.zodSchema).toContain('z.coerce.number()')
+  })
+
+  it('infers boolean from true/false', () => {
+    const r = make('true')
+    expect(r.tsType).toBe('boolean')
+  })
+
+  it('infers string for plain string', () => {
+    const r = make('hello')
+    expect(r.tsType).toBe('string')
+  })
+
+  it('infers url type for http URLs', () => {
+    const r = make('https://api.example.com')
+    expect(r.zodSchema).toContain('.url()')
+  })
+
+  it('infers number[] for comma-separated numbers', () => {
+    const r = make('1,2,3')
+    expect(r.tsType).toBe('number[]')
+  })
+
+  it('infers string[] for comma-separated strings', () => {
+    const r = make('a,b,c')
+    expect(r.tsType).toBe('string[]')
+  })
+
+  it('respects @type: enum annotation', () => {
+    const r = make('info', 'enum(info, warn, error)')
+    expect(r.tsType).toBe("'info' | 'warn' | 'error'")
+    expect(r.zodSchema).toContain("z.enum(['info', 'warn', 'error'])")
+  })
+
+  it('respects @type: url annotation', () => {
+    const r = make('not-a-url', 'url')
+    expect(r.zodSchema).toContain('.url()')
+  })
+
+  it('marks empty value as optional', () => {
+    const r = make('')
+    expect(r.isOptional).toBe(true)
+  })
+
+  it('marks @optional annotated entry as optional', () => {
+    const r = make('value', undefined, true)
+    expect(r.isOptional).toBe(true)
+    expect(r.zodSchema).toContain('.optional()')
+  })
+})
+
+// ─── Generator ───────────────────────────────────────────────────────────────
+
+describe('generateDts', () => {
+  const items = [
+    {
+      entry: { key: 'PORT', value: '3000', comment: '', annotations: { description: 'Server port' } },
+      inferred: { tsType: 'number', zodSchema: 'z.coerce.number()', isOptional: false }
+    },
+    {
+      entry: { key: 'SENTRY_DSN', value: '', comment: '', annotations: { optional: true } },
+      inferred: { tsType: 'string', zodSchema: 'z.string().optional()', isOptional: true }
+    }
+  ]
+
+  it('generates ImportMetaEnv augmentation', () => {
+    const output = generateDts(items, { schema: 'zod', augmentImportMeta: true })
+    expect(output).toContain('interface ImportMetaEnv')
+    expect(output).toContain('readonly PORT: number')
+    expect(output).toContain('readonly SENTRY_DSN?: string')
+  })
+
+  it('includes JSDoc from description', () => {
+    const output = generateDts(items, { schema: 'zod', augmentImportMeta: true })
+    expect(output).toContain('/** Server port */')
+  })
+})
+
+describe('generateZodSchema', () => {
+  const items = [
+    {
+      entry: { key: 'DATABASE_URL', value: 'postgres://localhost/db', comment: '', annotations: {} },
+      inferred: { tsType: 'string', zodSchema: 'z.string().url()', isOptional: false }
+    }
+  ]
+
+  it('generates valid zod schema', () => {
+    const output = generateZodSchema(items)
+    expect(output).toContain("import { z } from 'zod'")
+    expect(output).toContain('export const envSchema = z.object({')
+    expect(output).toContain('DATABASE_URL: z.string().url()')
+    expect(output).toContain('export type Env = z.infer<typeof envSchema>')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/tsdown.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  sourcemap: true
+})