final review

Author: theoephraim

README.md

@@ -16,7 +16,7 @@
 ## Varlock
 > add declarative schema to your .env files using @env-spec decorator comments
 
-- 🛡️ validation, coercion, type safety w/ Intellisense
+- 🛡️ validation, coercion, type safety w/ IntelliSense
 - 🔏 protection for sensitive config values (log redaction, leak prevention)
 - 🌐 flexible multi-environment management
 - 💫 composition of values, functions, load from external sources

example-monorepo/packages/plugin-test/.env.schema

@@ -1,4 +1,4 @@
-z# @defaultRequired=infer @defaultSensitive=false
+# @defaultRequired=infer @defaultSensitive=false
 # @generateTypes(lang=ts, path=env.d.ts)
 #
 # @currentEnv=$APP_ENV
@@ -25,3 +25,8 @@ FOR_ENV_CHECK=forEnv(dev)
 EQ_CHECK=eq(1, 2)
 
 IF_EQ_CHECK=if(eq(1, 1), "yes", "no")
+
+# @required @sensitive
+# @docs(https://xyz.com/docs/api-keys)
+# @docs("Authentication guide", https://xyz.com/docs/auth-guide)
+XYZ_API_KEY=

packages/varlock-website/src/assets/docs/multiple-docs-intellisense.png

@@ -14,12 +14,11 @@ While many have traditionally shied away from using environment-specific `.env`
 
 
 ### Process overrides
-`varlock` will always treat environment variables passed into the process with the most precedence. This means you can rely on your external hosting platform to inject environment-specific values and still benefit from `varlock`'s validation and coercion logic.
+`varlock` will always treat environment variables passed into the process with the most precedence. Generally, we recommend moving as much configuration as possible into your `.env` files, but there are cases where you may want to override specific values at runtime, either from the environment itself, or by prepending them to your command (e.g., `APP_ENV=prod pnpm run build`).
 
-Sometimes you also may want to pass in env vars via the command line while running a command (e.g. `APP_ENV=prod pnpm run build`).
-
-However, we recommend using injected overrides sparingly, and instead moving more config into your `.env` files.
+At the very least, you'll often need to to inject an environment flag (e.g., `APP_ENV`) and a _secret-zero_ which allows access to the rest of your secrets.
 
+That said, as a first step to adopting `varlock`, you could rely entirely on process overrides to inject all config values, but still benefit from having a clear schema with validation applied to them.
 
 ### Loading environment-specific `.env` files
 

packages/varlock-website/src/content/docs/guides/environments.mdx

@@ -7,7 +7,7 @@ Plugins allow extending the functionality of Varlock. Specifically they may intr
 
 ```env-spec title="1Password plugin example" "@plugin" "@initOp" "opServiceAccountToken" /op\\(.*\\)/
 # @plugin(@varlock/1password-plugin) # load + install plugin
-# @initOp(allowAppAuth=true) # init via custom root decorator
+# @initOp(token=$OP_TOKEN, allowAppAuth=true) # init via custom root decorator
 # ---
 # @type=opServiceAccountToken # custom data type
 OP_TOKEN=

packages/varlock-website/src/content/docs/guides/plugins.mdx

@@ -41,7 +41,7 @@ Values may be static, or set using [functions](/reference/functions/), which can
 
 **Quote rules:**
 - Static values can be wrapped in quotes or not -- all quotes styles (<code>\`</code>, `"`, `'`) are supported
-- Values wrapped in single quotes do not support [expansion](#expansion)
+- Values wrapped in single quotes do not support [expansion](#ref-expansion)
 - Single line values may not contain newlines, but `\n` will be converted to an actual newline except in single quotes
 - Multiline values can be wrapped in <code>```</code>, `"""`. Also supported is `"` and `'` but not recommended.
 - Unquoted values will be parsed as a number/boolean/undefined where possible (`ITEM=foo` -> `"foo"`, while `ITEM=true` -> `true`), however data-types may further coerce values
@@ -55,6 +55,7 @@ STATIC_VALUE_QUOTED="#hashtag" # and are necessary in some cases
 BOOLEAN_VALUE=true
 NUMERIC_VALUE=123.456
 FUNCTION_VALUE=exec(`op read "op://api-config/item/credential"`)
+EXPANSION_VALUE=${OTHER_VAR}-suffix
 MULTILINE_VALUE="""
 multiple
 lines
@@ -112,7 +113,7 @@ Read more about string expansion in the [@env-spec reference](/env-spec/referenc
 ## Decorator details
 
 ### Functions vs single use
-Most decorators take a single value (e.g., `@sensitive`) and may be used only once per item, while some are function calls (e.g., `@docs()`) and may be called multiple times.
+Most decorators take a single value (e.g., `@sensitive`, `@currentEnv`) and may be used only once per item (or file in the case of a root decorator). Some decorators however, are function calls (e.g., `@docs()`, `@import()`) and may be called multiple times.
 
 ```env-spec
 # @sensitive=true
@@ -128,7 +129,7 @@ Values passed to decorators will be resolved, meaning if a decorator is expectin
 # @required=false
 NEVER_REQUIRED=
 
-# @required=forEnv(prod)
+# @required=forEnv(prod) # resolves to true/false depending on the current environment
 REQUIRED_FOR_PROD=
 ```
 

packages/varlock-website/src/content/docs/guides/schema.mdx

@@ -128,10 +128,10 @@ DB_PASS=op(op://my-vault/database-password/password)
 The secret reference for invidivual fields within an item can be found by clicking on the down arrow icon on the field and selecting `Copy Secret Reference`.
 :::
 
-If you used the `id` param during initialization and have multiple instances, the `op()` function accepts an optional first parameter to specify which instance id to use.
+If you have multiple plugin instances, the `op()` function accepts an optional first parameter to specify which instance id to use.
 
 ```env-spec /dev|prod/
-# @initOp(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=forEnv(dev))
+# @initOp(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=true)
 # @initOp(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false)
 # ---
 DEV_ITEM=op(dev, op://vault-name/item-name/field-name)

packages/varlock-website/src/content/docs/plugins/1password.mdx

@@ -3,6 +3,7 @@ title: "Config Item @decorators"
 description: A reference page of available env-spec decorators for items
 ---
 import Decorator from '@/components/decorator-doc-entry.astro'
+import docsImg from '@/assets/docs/multiple-docs-intellisense.png'
 
 Decorators in a comment block _directly_ preceeding a config item will be attached to that item.
 Multiple decorators can be specified on the same line.
@@ -18,16 +19,19 @@ More details of the minutiae of decorator handling can be found in the [@env-spe
 
 ## Built-in item decorators
 
+These are the item decorators that are built into Varlock. [Plugins](/guides/plugins/) may introduce more.
+
 <div class="reference-docs">
 <div>
 ### `@required`
-
 **Value type:** `boolean`
 
 Sets whether an item is _required_ - meaning validation will fail if the value resolves to `undefined` or an empty string.
 
 Default behavior for all items within the same file can be toggled using the [`@defaultRequired` root decorator](/reference/root-decorators/#defaultRequired).
 
+💡 Use the [`forEnv()` function](/reference/functions/#forenv) to set required based on the current environment.
+
 ```env-spec
 # @defaultRequired=false
 # ---
@@ -40,13 +44,10 @@ REQUIRED_FOR_PROD_ITEM=
 # @required=eq($OTHER, foo)
 REQUIRED_IF_OTHER_IS_FOO=
 ```
-
-You can also use the [`forEnv()` function](/reference/functions/#forenv) to dynamically set the value based on the current environment.
 </div>
 
 <div>
 ### `@optional`
-
 **Value type:** `boolean`
 
 Opposite of [`@required`](#required). Equivalent to writing `@required=false`.
@@ -57,16 +58,13 @@ Opposite of [`@required`](#required). Equivalent to writing `@required=false`.
 # @optional
 OPTIONAL_ITEM=
 ```
-
-You can also use the [`forEnv()` function](/reference/functions/#forenv) to dynamically set the value based on the current environment.
 </div>
 
 <div>
 ### `@sensitive`
-
 **Value type:** `boolean`
 
-Sets whether the item should be considered _sensitive_ - meaning it must be protected from leaking. The value will be always be redacted in CLI output, and client integrations can take further action to prevent leaks.
+Sets whether the item should be considered _sensitive_ - meaning it cannot be exposed to the public. The value will be always be redacted in CLI output, and client integrations can take further action to prevent leaks.
 
 Default behavior for all items can be set using the [`@defaultSensitive` root decorator](/reference/root-decorators/#defaultSensitive)
 
@@ -80,13 +78,12 @@ SERVICE_X_CLIENT_ID=
 
 <div>
 ### `@type`
-
 **Value type:** [`data type`](/reference/data-types) (name only or function call)
 
 Sets the data type of the item - which affects validation, coercion, and generated types.
 Note that some data types take additional arguments. See [data types reference](/reference/data-types) for more details.
 
-If not specified, a data type will be inferred if a static value is set, or default to `string` otherwise.
+If not specified, a data type will be inferred when possible, or default to `string` otherwise.
 
 ```env-spec
 # @type=url # name only
@@ -101,7 +98,6 @@ INFER_NUMBER=123 # data type of `number` will be inferred from the value
 
 <div>
 ### `@example`
-
 **Value type:** `string`
 
 Provides an example value for the item. This lets you avoid setting placeholder values that are not meant to be used.
@@ -114,30 +110,27 @@ SECRET_KEY=
 
 <div>
 ### `@docs()`
-
 **Arg types:** `[ url: string ] | [ description: string, url: string ]`
 
-URL of documentation related to the item. Can be called multiple times.
+URL of documentation related to the item. Will be included in [generated types](/reference/root-decorators/#generatetypes). _Can be called multiple times._
 
 ```env-spec
 # @docs(https://xyz.com/docs/api-keys)
-# @docs(Authentication guide, https://xyz.com/docs/auth-guide)
+# @docs("Authentication guide", https://xyz.com/docs/auth-guide)
 XYZ_API_KEY=
 ```
+
+<img src={docsImg.src} alt="example of docs() in generated types" style="max-width:280px"/>_example of `docs()` info in generated types / IntelliSense_
 </div>
 
 <div>
 ### `@docsUrl` (deprecated) ||docsurl||
-
 **Value type:** `string`
 
 URL of documentation related to the item.
 
-```env-spec
-# @docsUrl=https://platform.openai.com/docs/api-reference/authentication
-OPENAI_API_KEY=
-```
-</div>
-
+Use [`@docs()`](#docs) instead, which supports multiple docs entries with optional descriptions.
 
+`@docsUrl=https://example.com` -> `@docs(https://example.com)`
+</div>
 </div>

packages/varlock-website/src/content/docs/reference/item-decorators.mdx

@@ -12,20 +12,20 @@ Root decorators appear in the _header_ section of a .env file - which is a comme
 # @defaultSensitive=false @defaultRequired=infer
 # @generateTypes(lang=ts, path=./env.d.ts)
 # ---
-
-# ...
+# ... config items
 ```
 
 
 More details of the minutiae of decorator handling can be found in the [@env-spec reference](/env-spec/reference/#comments-and-decorators).
 
 ## Built-in root decorators
 
+These are the root decorators that are built into Varlock. [Plugins](/guides/plugins/) may introduce more.
+
 <div class="reference-docs">
 
 <div>
 ### `@currentEnv`
-
 **Value type:** [`ref()`](/reference/functions/#ref) (usually written as `$ITEM_NAME`)
 
 Sets the current _environment_ value, which will be used when determining if environment-specific .env files will be loaded (e.g. `.env.production`),
@@ -49,7 +49,6 @@ APP_ENV=dev
 
 <div>
 ### `@envFlag` (deprecated) ||envflag||
-
 **Value type:** `string` (must be a valid item name within same file)
 
 Sets the current _environment flag_ by name.
@@ -62,12 +61,11 @@ Sets the current _environment flag_ by name.
 
 <div>
 ### `@defaultRequired`
-
 **Value type:** `boolean | "infer"`
 
 Sets the default behavior of each item being _required_. Only applied to items that have a definition within the same file. Can be overridden on individual items using [`@required`](/reference/item-decorators/#required)/[`@optional`](/reference/item-decorators/#optional).
 
-- `infer` (default): Items with a value set in the same file will be required; items with an empty string or no value are optional. Can be overridden per item.
+- `infer` (default): Items with a value set in the same file will be required; items with an empty string or no value are optional.
 - `true`: All items are required unless marked optional.
 - `false`: All items are optional unless marked required.
 
@@ -90,7 +88,6 @@ REQUIRED_ITEM= # required (explicit)
 
 <div>
 ### `@defaultSensitive`
-
 **Value type:** `boolean | inferFromPrefix(PREFIX)`
 
 Sets the default state of each item being treated as [_sensitive_](/guides/secrets/). Only applied to items that have a definition within the same file. Can be overridden on individual items using [`@sensitive`](/reference/item-decorators/#sensitive).
@@ -134,7 +131,6 @@ FOO=bar  # will be ignored
 
 <div>
 ### `@import()`
-
 **Arg types:** `[ path: string, ...keys?: string[] ]`
 
 Imports other `.env` file(s) - useful for sharing config across monorepos and splitting up large schemas. _Can be called multiple times._
@@ -156,7 +152,6 @@ IMPORTED_ITEM=overriden-value
 
 <div>
 ### `@plugin()`
-
 **Arg types:** `[ identifier: string ]`
 
 Loads a plugin, which can register new root decorators, item decorators, and resolver functions. _Can be called multiple times._
@@ -177,7 +172,6 @@ XYZ_API_KEY=op(op://api-prod/xyz/api-key) # new resolver
 
 <div>
 ### `@generateTypes()`
-
 **Arg types (key/value):**
 - `lang`: Language to generate types for. Supported languages:
   - `ts` - TypeScript
@@ -193,7 +187,6 @@ Enables automatic type generation based on your schema. _Can be called multiple
 
 <div>
 ### `@redactLogs`
-
 **Value type:** `boolean`
 
 Controls whether sensitive config values are automatically redacted from console output. When enabled, any sensitive values will be replaced with `▒▒▒▒▒` in logs.
@@ -226,6 +219,8 @@ We feel that they are beneficial enough to have them on by default but you can a
 
 <div>
 ### `@preventLeaks`
+**Value type:** `boolean`
+
 Controls whether leak prevention is enabled. When enabled, varlock will scan outgoing HTTP responses to detect if sensitive values are being leaked.
 
 _Only applies in JavaScript based projects where varlock runtime code is imported._

packages/varlock-website/src/content/docs/reference/root-decorators.mdx

@@ -101,7 +101,7 @@ XYZ_TOKEN=exec('op read "op://api-prod/xyz/auth-token"')
           </div>
           <Image
             src={intellisenseImg}
-            alt="Intellisense demo"
+            alt="IntelliSense demo"
             class="img-with-border"
           />
         </div>