Why penv adopted @env-spec instead of inventing a schema format

说明与用途

penv 采用 @env-spec 格式管理 .env 文件，避免了自定义格式的学习曲线，并与 varlock 兼容。通过自定义装饰器实现云集成。

问题

Developers need a schema for .env files to enforce types, required keys, and sensitive values, but creating a custom format adds learning curve and interoperability issues.

结果

By adopting @env-spec, penv achieved zero learning curve, easy schema generation, and interoperability with existing tools, while adding its own decorators for cloud integration.

工作流

• 1. Use @env-spec decorators in a .env.schema file to declare types, sensitivity, and other metadata.
• 2. Run penv init to generate the schema from an existing .env file and gitignore the .env.
• 3. Add custom decorators (@since, @rotate, @dynamicFrom) and headers (@schema, @penv) for penv-specific features.
• 4. Commit the .env.schema file; penv reads it for validation and agent execution.
• 5. For non-sensitive values, include them directly in the schema; secrets are managed in the cloud.
• 6. If needed, drop the same .env.schema into varlock for local loading.
• 7. Avoid .env.* cascade; penv uses a single .env file and cloud environments.
• 8. Use penv’s per-harness guards and typed codegen for secure agent sessions.

证据

penv’s .env.schema is an @env-spec file.

来源

penv init reads the .env you already have, writes the schema next to it, and gitignores .env.

来源