@townco/env 0.1.1

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@townco/env",
+  "type": "module",
+  "version": "0.1.1",
+  "description": "env",
+  "license": "UNLICENSED",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": "github:townco/town",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./update-schema": {
+      "import": "./dist/update-schema.js",
+      "types": "./dist/update-schema.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@townco/tsconfig": "0.1.48",
+    "ts-morph": "^27.0.2",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "schema:update": "bun src/update-schema"
+  },
+  "dependencies": {
+    "@townco/core": "0.0.29",
+    "zod": "^4.1.13"
+  }
+}

package/src/env-file.ts

@@ -0,0 +1,248 @@
+/**
+ * Represents a line in an .env file
+ */
+type EnvLine =
+  | { type: "comment"; content: string }
+  | { type: "blank" }
+  | { type: "entry"; key: string; value: string; raw: string };
+
+type EnvEntry = Extract<EnvLine, { type: "entry" }>;
+
+/**
+ * A data structure that represents a parsed .env file while preserving
+ * all original content including comments, blank lines, and order.
+ */
+export class EnvFile {
+  private lines: EnvLine[];
+
+  constructor(lines: EnvLine[] = []) {
+    this.lines = lines;
+  }
+
+  /**
+   * Parse a .env file string into an EnvFile structure
+   */
+  static parse(content: string): EnvFile {
+    const lines: EnvLine[] = content.split("\n").map((line): EnvLine => {
+      const trimmed = line.trim();
+
+      if (trimmed === "") {
+        return { type: "blank" };
+      }
+
+      if (trimmed.startsWith("#")) {
+        return { type: "comment", content: line };
+      }
+
+      const equalsIndex = line.indexOf("=");
+      if (equalsIndex === -1) {
+        // Malformed line, treat as comment
+        return { type: "comment", content: line };
+      }
+
+      const key = line.substring(0, equalsIndex).trim();
+      const value = line.substring(equalsIndex + 1);
+
+      return { type: "entry", key, value, raw: line };
+    });
+
+    return new EnvFile(lines);
+  }
+
+  /**
+   * Serialize the EnvFile back to a string
+   */
+  toString(): string {
+    return this.lines
+      .map((line) => {
+        switch (line.type) {
+          case "blank":
+            return "";
+          case "comment":
+            return line.content;
+          case "entry":
+            return line.raw;
+          default:
+            throw new Error(`Unknown line type`);
+        }
+      })
+      .join("\n");
+  }
+
+  /**
+   * Get all entries as a key-value record
+   */
+  toRecord(): Record<string, string> {
+    return Object.fromEntries(this.entries());
+  }
+
+  /**
+   * Find an entry line by key
+   */
+  private findEntry(key: string): EnvEntry | undefined {
+    const line = this.lines.find((l) => l.type === "entry" && l.key === key);
+    return line as EnvEntry | undefined;
+  }
+
+  /**
+   * Find the index of an entry by key
+   */
+  private findEntryIndex(key: string): number {
+    return this.lines.findIndex((l) => l.type === "entry" && l.key === key);
+  }
+
+  /**
+   * Create an entry line from key and value
+   */
+  private createEntry(key: string, value: string): EnvEntry {
+    const quotedValue = this.normalizeValue(value);
+    return {
+      type: "entry",
+      key,
+      value: quotedValue,
+      raw: `${key}=${quotedValue}`,
+    };
+  }
+
+  /**
+   * Normalize a value by ensuring it's properly quoted
+   */
+  private normalizeValue(value: string): string {
+    // Strip existing quotes if present, then add quotes
+    const unquoted =
+      value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+    return `"${unquoted}"`;
+  }
+
+  /**
+   * Find the insertion index for a new entry (before the final blank line if present)
+   */
+  private findInsertionIndex(): number {
+    const lastLine = this.lines[this.lines.length - 1];
+    return lastLine?.type === "blank"
+      ? this.lines.length - 1
+      : this.lines.length;
+  }
+
+  /**
+   * Get the value for a specific key
+   */
+  get(key: string): string | undefined {
+    return this.findEntry(key)?.value;
+  }
+
+  /**
+   * Set a value for a key. If the key exists, updates it in place.
+   * If it doesn't exist, appends it above the final newline (if present).
+   * Values are always double quoted.
+   */
+  set(key: string, value: string): this {
+    const index = this.findEntryIndex(key);
+    const entry = this.createEntry(key, value);
+
+    if (index !== -1) {
+      this.lines[index] = entry;
+    } else {
+      this.lines.splice(this.findInsertionIndex(), 0, entry);
+    }
+
+    return this;
+  }
+
+  /**
+   * Delete a key-value entry
+   */
+  delete(key: string): this {
+    this.lines = this.lines.filter(
+      (l) => !(l.type === "entry" && l.key === key),
+    );
+    return this;
+  }
+
+  /**
+   * Check if a key exists
+   */
+  has(key: string): boolean {
+    return this.findEntry(key) !== undefined;
+  }
+
+  /**
+   * Get all keys
+   */
+  keys(): string[] {
+    return this.lines
+      .filter((l): l is EnvEntry => l.type === "entry")
+      .map((l) => l.key);
+  }
+
+  /**
+   * Iterate over all entries
+   */
+  *entries(): IterableIterator<[string, string]> {
+    for (const line of this.lines) {
+      if (line.type === "entry") {
+        yield [line.key, line.value];
+      }
+    }
+  }
+
+  /**
+   * Apply a function to all entries and return a new EnvFile
+   */
+  map(fn: (key: string, value: string) => [string, string]): EnvFile {
+    const newLines = this.lines.map((line) => {
+      if (line.type === "entry") {
+        const [newKey, newValue] = fn(line.key, line.value);
+        return this.createEntry(newKey, newValue);
+      }
+      return line;
+    });
+
+    return new EnvFile(newLines);
+  }
+
+  /**
+   * Filter entries based on a predicate
+   */
+  filter(fn: (key: string, value: string) => boolean): EnvFile {
+    const newLines = this.lines.filter((line) => {
+      if (line.type === "entry") {
+        return fn(line.key, line.value);
+      }
+      return true; // Keep comments and blank lines
+    });
+
+    return new EnvFile(newLines);
+  }
+
+  /**
+   * Add a comment line
+   */
+  addComment(content: string): this {
+    const comment = content.startsWith("#") ? content : `# ${content}`;
+    this.lines.push({ type: "comment", content: comment });
+    return this;
+  }
+
+  /**
+   * Add a blank line
+   */
+  addBlank(): this {
+    this.lines.push({ type: "blank" });
+    return this;
+  }
+
+  /**
+   * Get the raw lines array for custom operations
+   */
+  getLines(): readonly EnvLine[] {
+    return this.lines;
+  }
+
+  /**
+   * Create a clone of this EnvFile
+   */
+  clone(): EnvFile {
+    return new EnvFile([...this.lines]);
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+export const envSchema = z.object({
+  ANTHROPIC_API_KEY: z.string().min(1),
+  AWS_ACCESS_KEY_ID: z.string().min(1),
+  AWS_SECRET_ACCESS_KEY: z.string().min(1),
+  EXA_API_KEY: z.string().min(1),
+  FLY_TOKEN: z.string().min(1),
+  NEXT_PUBLIC_SITE_URL: z.string().min(1),
+  NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
+  NEXT_PUBLIC_SUPABASE_URL: z.string().min(1),
+  SUPABASE_ACCESS_TOKEN: z.string().min(1),
+  SUPABASE_ANON_KEY: z.string().min(1),
+  SUPABASE_DB_PASSWORD: z.string().min(1),
+  SUPABASE_PROJECT_ID: z.string().min(1),
+  SUPABASE_SRC_ARC_BUCKET: z.string().min(1),
+  SUPABASE_URL: z.string().min(1),
+});
+
+export type Env = z.infer<typeof envSchema>;
+export const parseEnv = (env = process.env) => envSchema.parse(env);
+export { EnvFile } from "./env-file";

package/src/update-schema.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Biome } from "@biomejs/js-api/nodejs";
+import { findRoot } from "@townco/core";
+import { Project, SyntaxKind } from "ts-morph";
+
+const envSchemaTsSrc = path.join("packages", "env", "src", "index.ts");
+
+export const updateSchema = async ({
+  envSchemaSrc = envSchemaTsSrc,
+  ...opts
+}: {
+  envFile?: string;
+  envSchemaSrc?: string;
+} = {}) => {
+  const envFile = opts.envFile ?? path.join(await findRoot(), ".env.in");
+  const root = await findRoot();
+  const keys = (await Bun.file(envFile).text())
+    .split("\n")
+    .filter((line) => line.match(/^[A-Z_]+\=/))
+    .map((line) => line.split("=")[0])
+    .filter((k): k is string => Boolean(k))
+    .sort();
+
+  const src = new Project().addSourceFileAtPath(envSchemaSrc);
+  const obj = src
+    .getVariableDeclaration("envSchema")!
+    .getInitializerIfKindOrThrow(SyntaxKind.CallExpression)
+    .getArguments()[0]
+    ?.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+
+  obj?.getProperties().forEach((p) => p.remove());
+  obj?.addPropertyAssignments(
+    keys.map((name) => ({ name, initializer: "z.string().min(1)" })),
+  );
+
+  const biome = new Biome();
+  src.replaceWithText(
+    biome.formatContent(biome.openProject(root).projectKey, src.getFullText(), {
+      filePath: src.getFilePath(),
+    }).content,
+  );
+  await src.save();
+};
+
+if (import.meta.main) await updateSchema();

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@townco/tsconfig",
+  "compilerOptions": { "outDir": "./dist", "rootDir": "./src" },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", ".sst"]
+}