dmno-dev/varlock — Repo Appraisal

Overview

What it is — Varlock is a TypeScript CLI tool and library that adds a schema DSL (@env-spec), type validation, secret management, and AI-safe config exposure to standard .env files.
Problem — .env files have no schema, secrets can leak to AI agents reading codebases, and .env.example files are perpetually out of sync with reality.
Who it's for — JavaScript/TypeScript developers managing multi-environment config, especially teams deploying AI agents that need config context without secret exposure.
Notable — Ships a purpose-built AI-safety mechanism (schema visible to agents, secrets never), a rich plugin ecosystem across all major secret backends (1Password, AWS, GCP, Azure, Bitwarden, Infisical, HashiCorp), and uses Bun as its package manager — directly mirroring PAI's own runtime.

Verdict

	Rating	Summary
Quality	excellent (22/24)	Actively maintained TypeScript monorepo with 3540 stars in 13 months, high-discipline tooling, and a comprehensive multi-package ecosystem.
PAI Relevance	integrate (0.88)	Fills PAI's env-schema gap directly, ships as a TypeScript/Bun CLI with MCP server, and introduces a novel AI-safe config pattern applicable to PAI's security hooks and agent credential handling.

Quality Assessment

22/24 — actively-maintained / adequately-documented / high-discipline

Health: 8/8 (actively-maintained)

Failed:

(none)

Passed:

H1: PASS — latest release @varlock/vite-integration@1.1.2 tagged 2026-05-25
H2: PASS — released 2 days ago, well within 12 months
H3: PASS — last commit 2026-05-27T13:47:05Z, same day as appraisal
H4: PASS — committed today
H5: PASS — archived: false
H6: PASS — 25 open issues, within healthy triage range (>0, <100)
H7: PASS — MIT license
H8: PASS — README carries GitHub Actions CI badge pointing to .github/workflows/test.yaml

Documentation: 6/8 (adequately-documented)

Failed:

D5: FAIL — no heading matching API, Configuration, Options, Reference, Commands, or Parameters visible in the provided excerpt; closest is ## Workflow which shows commands but doesn't match the probe keywords
D8: FAIL — no Limitations, Caveats, Known Issues, or Trade-offs section present in the excerpt

Passed:

D1: PASS — README is present and well-structured
D2: PASS — README is substantially longer than 1000 bytes with multiple major sections
D3: PASS — ## Installation section with CLI, Homebrew, cURL, and Docker install paths
D4: PASS — multiple annotated .env.schema code blocks under ## Workflow and plugin examples
D6: PASS — tagline "AI-safe .env files: Schemas for agents, Secrets for humans." appears in the first visible paragraph
D7: PASS — multiple links to https://varlock.dev docs site with specific sub-paths (installation, guides, integrations, AI-safe config guide)

Engineering Signals: 8/8 (high-discipline)

Failed:

(none)

Passed:

E1: PASS — TypeScript is the primary language
E2: PASS — root package.json present with full monorepo workspace config
E3: PASS — root manifest has ~21 dev dependencies, all tooling/linting (turbo, lefthook, eslint, bun-security-scanner); reasonable for a monorepo root
E4: PASS — test:ci, smoke-test, and test:frameworks scripts in manifest; CI badge confirms test runs in GitHub Actions
E5: PASS — 3540 stars, far above the 50-star threshold
E6: PASS — created 2025-04-11, ~13.5 months to 3540 stars = ~262 stars/month, well above 2/month
E7: PASS — 95 forks
E8: PASS — description "AI-safe .env files: Schemas for agents, Secrets for humans." is 50+ characters and clearly meaningful

PAI Relevance

Dimension	Score	Assessment
Harvest Value	2	The `@env-spec` JSDoc-in-.env DSL is a novel co-location pattern for schema + config; the runtime log redaction and AI-safe schema exposure (agents see types/descriptions, never secret values) is directly applicable to PAI's security hooks layer and to how PAI's 27 agents handle API credentials across Claude, GPT-5.4, and Kimi-K2.6.
Integration Readiness	2	TypeScript CLI with `bun` as its own package manager (`bun@1.3.11`), installable via `bun add varlock` or as a subprocess; ships a Vite integration directly applicable to the Conservancy project (SvelteKit/Vite), and an MCP server for agent-accessible docs.
Overlap Risk	1	Partial overlap with PAI's Silas/security agent and existing security hooks (which handle observability and PII), but no existing PAI skill covers structured `.env` schema management, secret scanning via git hooks, or AI-safe config exposure — the overlap is functional proximity, not duplication.
Gap Fill	2	PAI manages credentials for multiple AI providers and Cloudflare services with no schema enforcement, no leak-scanning hooks, and no runtime redaction; varlock addresses all three with zero PAI-internal equivalent.

Composite: 0.88

Landscape Position

Category: Security & Privacy

In this category: first entry — no prior secrets-management or env-schema tool appraised; elder-plinius--ST3GG (steganography) is the only other security-category repo and covers an entirely different domain

Standing: Varlock is the first and only env-schema/secrets-management tool in the landscape, making it the category-defining entry with no direct competition in the appraisal set.

Evidence Base

Density: 10/10 — README (first 8KB, substantive and complete for scoring purposes), dependency manifest (root package.json with full scripts, devDependencies, catalog, and engine constraints), GitHub metadata (stars, forks, issues, dates, release, topics, license, archived status), landscape context with prior appraisals and rolling summary all present.

Notes

The @env-spec RFC (tracked in GitHub Discussions #17) signals an attempt to standardize the DSL beyond varlock itself — worth monitoring for ecosystem adoption. The repo uses Bun as its own package manager, which is an unusually strong stack alignment signal for PAI. The MCP server for varlock docs makes the tool self-referentially AI-tool-friendly. Growth rate (~262 stars/month from a standing start in April 2025) indicates genuine product-market fit rather than hype spike. The varlock scan + git hook pattern for catching AI-generated code that accidentally leaks secrets is especially relevant for any PAI workflow that uses agentic coding loops.