feat(config): centralize environment variable access with Zod validation

[galligan]

Summary

Centralizes all environment variable access in @outfitter/config with Zod validation, eliminating scattered biome-ignore comments and providing type-safe env access.

Problem

12 biome-ignore comments across the codebase due to conflict between:

• TypeScript's noPropertyAccessFromIndexSignature (requires process.env["KEY"])
• Biome's useLiteralKeys (prefers process.env.KEY)

Solution

Single centralized access point with proper validation:

import { env, getEnvBoolean } from "@outfitter/config";

// Static access (parsed once at module load)
console.log(env.NODE_ENV);  // "development" | "test" | "production"
console.log(env.HOME);       // string | undefined

// Dynamic access (for runtime-changing values like in tests)
if (getEnvBoolean("NO_COLOR")) {
  // disable colors
}

Changes

New in @outfitter/config

• portSchema — Port validation (1-65535) with coercion
• booleanSchema — String to boolean ("true"/"1" → true)
• optionalBooleanSchema — Optional boolean handling
• parseEnv<T>() — Generic schema-based env parsing
• getEnvBoolean() — Dynamic runtime env reads
• env — Pre-parsed typed environment object
• 17 new tests

Updated @outfitter/ui

• Uses getEnvBoolean() for terminal detection
• Removed 3 biome-ignore comments

Benefits

• One biome-ignore instead of 12 scattered
• Runtime validation — fails fast with clear errors
• Type coercion — strings become proper booleans
• Type safety — env.NODE_ENV typed as union

Test plan

• 17 new env validation tests pass
• All 38 UI tests pass
• Typecheck passes
• Lint passes

Fixes #22

🤖 Generated with Claude Code

[galligan]

• fix(errors): avoid TaggedError extends warnings #106 : 2 dependent PRs (#107 , #116 )
• chore(release): align package versions to 0.1.0 #105
• docs: add README and CHANGELOG for testing, kit, outfitter #95
• feat(templates): add daemon project template #94
• feat(templates): add MCP server project template #93
• feat(templates): add CLI project template #92
• fix(cli): implement confirmDestructive prompts #104
• fix(cli): implement createCLI and command builder #103
• feat(kit): add @outfitter/kit meta-package #91
• docs(daemon): add README and CHANGELOG #90
• fix(daemon): fix locking module bugs (GREEN phase) #89
• test(daemon): add locking module tests (RED phase) #88
• feat(daemon): add errors, platform, and locking module stubs #87
• feat(outfitter): add doctor command for environment validation #86
• feat(outfitter): add init command with project scaffolding #85
• feat(daemon): add IPC communication and health checks #84
• feat(daemon): add types and lifecycle management #83
• feat(index): add FTS5 full-text search implementation #82
• feat(index): add types for FTS5 full-text search #81
• feat(testing): add MCP and CLI test harnesses #80
• feat(testing): add test fixture utilities #79
• feat(mcp): add MCP server implementation with typed handlers #78
• feat(mcp): add types and interfaces for MCP server #77
• feat(ui): add Shape discriminated union and render() #76
• feat(ui): add createTokens semantic color layer #75
• feat(state): add pagination helpers #74
• feat(logging): add DEFAULT_PATTERNS for common secret redaction #73
• feat(ui): add formatRelative() for human-readable timestamps #72
• feat(state): add encodeCursor/decodeCursor for pagination #71
• feat(types): add hashId() for deterministic short identifiers #70
• feat(contracts): add Logger.child() and fix AssertionError category #69
• feat(config): centralize environment variable access with Zod validation #42 👈 (View in Graphite)
• fix(logging): enable redaction by default when global rules exist #41
• docs(ui): add README, CHANGELOG, and TSDoc comments #39
• docs(state): add README, CHANGELOG, and TSDoc comments #38
• docs(file-ops): add README, CHANGELOG, and TSDoc comments #37
• docs(logging): add README, CHANGELOG, and TSDoc comments #36
• docs(config): add README, CHANGELOG, and TSDoc comments #35
• fix(cli): enforce cursor TTL #114
• fix(tests): remove placeholder tests #113
• chore(gitattributes): prefer ours for bun lockfiles #115
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fd471f2f48

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Greptile Summary

• Centralizes environment variable access in @outfitter/config with Zod validation to eliminate 12 scattered biome-ignore comments throughout the codebase
• Implements type-safe env schemas for ports (1-65535), booleans (string to boolean coercion), and a pre-parsed env object with proper typing
• Adds comprehensive test coverage with 17 new tests and updates @outfitter/ui to use the new centralized env access functions

Important Files Changed

Filename	Overview
packages/config/src/env.ts	New centralized env validation module with critical type safety issue in the exported env object using unsafe type assertion
packages/config/src/index.ts	Added env validation exports but left existing XDG functions using direct process.env access, creating inconsistency

Confidence score: 3/5

• This PR requires careful review due to a critical type safety issue in the core environment validation module
• Score lowered due to unsafe type assertion in env export that could mask validation errors and incomplete migration leaving direct process.env usage in XDG functions
• Pay close attention to packages/config/src/env.ts line 210 where the type assertion could cause runtime issues

Sequence Diagram

sequenceDiagram
    participant User
    participant App as "Application Code"
    participant Config as "@outfitter/config"
    participant Zod as "Zod Validator"
    participant ProcessEnv as "process.env"
    
    User->>App: "Import env from @outfitter/config"
    App->>Config: "import { env }"
    Config->>Zod: "appEnvSchema.parse(process.env)"
    Zod->>ProcessEnv: "Read environment variables"
    ProcessEnv-->>Zod: "Raw string values"
    Zod->>Zod: "Transform and validate"
    Zod-->>Config: "Typed environment object"
    Config-->>App: "Pre-parsed env"
    App->>App: "Access typed env.NODE_ENV, env.NO_COLOR, etc."

Loading

[greptile-apps]

Additional Comments (1)

1. packages/config/src/index.ts, line 106-107 (link)

   style: These direct process.env accesses should use the new centralized env system to eliminate biome-ignore comments. Are these XDG functions planned to be updated to use the centralized env access in a follow-up PR?

_{3 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[galligan]

Updated color detection to treat NO_COLOR presence as disable and honor FORCE_COLOR numeric levels (0 disables, 1+ enables).

[galligan]

Removed the unnecessary Env type assertion by wiring env through parseEnv(appEnvSchema) and dropped the now-unused lint suppression. Restacked and resubmitted.

[galligan]

Resubmitted after sync/restack. NO_COLOR/FORCE_COLOR handling and env typing fixes are in place on this branch; no further changes needed here.

[galligan]

Addressed the Greptile note by deriving Env from the schema and typing the schema shape explicitly; env stays validated at module load. Updated the PR with the new commit.

[galligan]

Merge activity

• Jan 24, 1:54 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jan 24, 2:13 PM UTC: Graphite rebased this pull request as part of a merge.
• Jan 24, 2:13 PM UTC: @galligan merged this pull request with Graphite.