more docs cleanup

Author: theoephraim

packages/varlock-website/src/content/docs/env-spec/reference.mdx

@@ -57,7 +57,7 @@ BAZ= # @dec # this is @ignored too
 
 ### Decorators
 
-Decorators are used within comments to attach structured data to specific config items, or within a standalone comment blockto alter a group of items or the entire document and loading process.
+Decorators are used within comments to attach structured data to specific config items, or within a standalone comment block to alter a group of items or the entire document and loading process.
 
 - Each decorator has a name and optional value (`@name=value`) or is a bare function call `@func()`
 - Decorators with values may only be used once per comment block, while function calls may be used multiple times
@@ -91,7 +91,7 @@ A divider is a comment that serves as a separator, like a `<hr/>` in HTML.
 # ---
 ITEM1=
 ITEM2=
-# --- another divider --- 
+# --- another divider ---
 ITEM3=
 ```
 
@@ -100,9 +100,9 @@ ITEM3=
 ### Config Item Comments
 Comment lines directly preceeding an item will be attached to that item, along with the decorators contained within.
 
-- A blank line or a divider will break the above comments from being attached to the item
+- A blank line or a divider will break the above comments from being attached to the item below
 - Both decorator and regular comment lines may be interspersed
-- Post-value comments may also contain decorators, but is not recommended
+- Post-value comments may also contain decorators, but should be used sparingly
 
 ```env-spec
 # these comments are attached to ITEM1 below
@@ -162,6 +162,7 @@ Values are interpreted similarly for config item values, decorator values, and v
 - A value in quotes is _always_ treated as a string -- `@d1="with spaces"`, `@trueString="true"`, `@numStr="123"`
 - All quote styles ``[`'"]`` are ok -- ``@dq="c" @bt=`b` @sq='a'``
 - Escaped quotes matching the wrapping quote style are ok -- `@ok="escaped\"quote"`
+- Single quote wrapped strings do not support [expansion (see below)](#expansion)
 - In `"` or `` ` `` wrapped values, the string `\n` will be converted to an actual newline
 - Multi-line strings may be wrapped in ``(```|"""|"|')``
   - only available for config item values, not decorators or within function args
@@ -175,7 +176,7 @@ In each case, much of the handling is the same.
 - a value must not be wrapped in quotes to be interpreted as a function call
 - function names must start with a letter, and can then contain letters, numbers, and underscores `/[a-ZA-Z][a-ZA-Z0-9_]*/`
 - you can pass no args, a single arg, or multiple args
-- you may also pass key value pairs at the end of the list, and they will be combined into a single object at the end of the array
+- you may also pass key value pairs at the end of the list
 - each value will be interpreted using common value-handling rules (see above)
 
 ```env-spec
@@ -184,4 +185,28 @@ SINGLE_ARG=fn(asdf)
 MULTIPLE_ARGS=fn(one, "two", three, 123.456)
 KEY_VALUE_ARGS=fn(key1=v1, key2="v2", key3=true)
 MIXED_ARGS=fn(item1, item2, key1=v1, key2="v2", key3=true)
+NOT_FN_CALL="fn()" # treated as string
 ```
+
+### String expansion ||expansion||
+While the parser itself does not include any implemention of specific functions, it does handle _expansion_ of strings - and it uses several function calls under the hood to do so. This means a few basic function calls, while not implemented, have specific inherent meaning and must be implemented similarly across all tools that support this spec.
+
+Expansion can be used within item values, decorator values, and function call arguments.
+
+_Note that single quote wrapped strings are NOT expanded._
+
+- `$ITEM_NAME` -> `ref(ITEM_NAME)`
+- `${ITEM_NAME}` -> `ref(ITEM_NAME)`
+- `pre${ITEM_NAME}post` -> `concat("pre", ref(ITEM_NAME), "post")`
+- `${ITEM_NAME:-defaultval}` -> `fallback(ref(ITEM_NAME), "defaultval")`
+- `${ITEM_NAME-defaultval}` -> `fallback(ref(ITEM_NAME), "defaultval")`
+- `$(my-cli arg --arg2)` -> `exec("my-cli arg --arg2")`
+
+:::note[Keep it simple]
+We recommend using expansion only for simple refs `$ITEM`/`${ITEM}` and skipping the rest.
+
+- Use bracketed version within a larger string - `fn("${ENV}_db")`
+- Skip the brackets otherwise - `fn($ENV)`
+
+The rest is implemented to match other popular tools, but we do not recommend using them, as intent can be more clearly expressed using function calls directly.
+:::

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

@@ -22,7 +22,7 @@ For now, all imported files must be `.env` files (and may contain @env-spec deco
 
 ### Single file
 
-- Path must begin with `./` or `../`
+- Path must begin with `./` or `../` or `/`
 - Imported file name must be begin with `.env.`
 
 ```env-spec
@@ -31,7 +31,7 @@ For now, all imported files must be `.env` files (and may contain @env-spec deco
 
 ### Directory
 
-- Path must begin with `./` or `../`
+- Path must begin with `./` or `../` or `/`
 - Path must end with a trailing `/`
 - Multiple `.env.*` files will be detected and loaded, based on the current environment flag, similar to what happens in the current directory (see [environments guide](/guides/environments#loading-environment-specific-env-files))
 - The environment flag value will be inherited, unless another `@currentEnv` is defined within the directory's `.env.schema`

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

@@ -5,9 +5,9 @@ description: Using plugins with varlock
 
 Plugins allow extending the functionality of Varlock. Specifically they may introduce new [root decorators](/reference/root-decorators/), [item decorators](/reference/item-decorators/), [data types](/reference/data-types/), and [resolver functions](/reference/functions/).
 
-```env-spec title="1Password plugin example" "@plugin" "@initOpVault" "opServiceAccountToken" /op\\(.*\\)/
+```env-spec title="1Password plugin example" "@plugin" "@initOp" "opServiceAccountToken" /op\\(.*\\)/
 # @plugin(@varlock/1password-plugin) # load + install plugin
-# @initOpVault(allowAppAuth=true) # init via custom root decorator
+# @initOp(allowAppAuth=true) # init via custom root decorator
 # ---
 # @type=opServiceAccountToken # custom data type
 OP_TOKEN=
@@ -66,8 +66,8 @@ Plugins are initialized using custom root decorators that they introduce. In som
 
 A plugin initialization root decorator is used to set IDs, toggle features, and wire up auth. Note that sensitive data should be passed in via references to config items within your schema.
 
-```env-spec title="Plugin initialization example" "@initOpVault"
-# @initOpVault(account=acmeco, token=$OP_TOKEN, allowAppAuth=forEnv(dev))
+```env-spec title="Plugin initialization example" "@initOp"
+# @initOp(account=acmeco, token=$OP_TOKEN, allowAppAuth=forEnv(dev))
 # ---
 # @type=opServiceAccountToken @sensitive
 OP_TOKEN=
@@ -80,10 +80,10 @@ In secret storage tools, you should segment your data to follow the [_principle
 We cannot always assume that you won't need access to multiple segments at the same time. In these cases, a plugin may be designed to be initialized multiple times with some kind of id parameter. Resolver functions and decorators can then accept an additional parameter to specify which instance to use.
 
 
-```env-spec title=".env.schema" "@initOpVault" /id=[a-z]+/ /\\((dev),/
+```env-spec title=".env.schema" "@initOp" /id=[a-z]+/ /\\((dev),/
 # @plugin(@varlock/1password-plugin)
-# @initOpVault(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=forEnv(dev))
-# @initOpVault(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false);
+# @initOp(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=forEnv(dev))
+# @initOp(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false);
 # ---
 # @type=opServiceAccountToken @sensitive
 OP_TOKEN_DEV=

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

@@ -88,30 +88,26 @@ Functions may be composed together to create more complex value resolution logic
 
 ```env-spec
 # @required=forEnv(prod)
-API_DOMAIN=if(eq($APP_ENV, prod), api.myapp.com, staging-api.myapp.com)
+API_DOMAIN=if(eq(ref(APP_ENV), prod), api.myapp.com, staging-api.myapp.com)
 ```
 
 
-### Value Expansion ||expansion||
+### Referencing other values ||ref-expansion||
 
-`varlock` supports _expansion_ like other .env tools - such as [dotenv-expand](https://github.com/motdotla/dotenv-expand). However unlike other tools, it uses [function calls](/reference/functions/) to implement this.
+Within values and function args, you often need to reference other env vars within your schema.
 
-- `prefix-${OTHER}` -> `concat("prefix", ref("OTHER"))`
-- `$OTHER` -> `ref("OTHER")`
-- `${OTHER}` -> `ref("OTHER")`
-- `${OTHER:-defaultval}` -> `fallback(ref("OTHER"), "defaultval")`
-- `$(whoami)` -> `exec("whoami")`
+You may use [`ref()`](/reference/functions/#ref) but we support _expansion_ syntax (like many other .env tools) for convenience.
 
-While you could call those functions directly, in many cases it will be more clear to use expansion, or a mix of function calls and expansion. For example:
+Both `$ITEM` and `${ITEM}` are equivalent to `ref(ITEM)`.
 
-```env-spec
-OP_VAULT_NAME=api-config-prod
-MY_KEY=exec(`op read "op://${OP_VAULT_NAME}/service/api-key"`)
-```
-
-More details:
+We recommend using the bracket version only when used within a larger string.
 
+```env-spec /\\$\\{[^\\}]+\\}/ /\\$[A-Z]+/
+WITH_BRACKETS=exec(`op read "op://${OP_VAULT_NAME}/service/api-key"`)
+NO_BRACKETS=fallback($OTHERVAR, foo)
+```
 
+Read more about string expansion in the [@env-spec reference](/env-spec/reference/#expansion).
 
 ## Decorator details
 

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

@@ -21,58 +21,73 @@ See the [plugins guide](/guides/plugins/#installation) for more instructions on
 # 1. Load the plugin
 # @plugin(@varlock/1password-plugin)
 #
-# 2. Initialize the plugin, wiring it up to a service account token (see step 3)
-# @initOpVault(token=$OP_TOKEN)
+# 2. Initialize the plugin - see below for more details on options
+# @initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
 # ---
 
-# 3. Add a service account token config item
+# 3. Add a service account token config item (if applicable)
 # @type=opServiceAccountToken @sensitive
 OP_TOKEN=
 ```
 
-### Vault & service account setup
+### Vault setup
 
-If you already use 1Password and your secrets live in a vault that holds other sensitive data, you should create a new vault and move your secrets to it, because **the access system of 1Password is based on vaults, not individual items**.
+If your secrets are already stored in 1Password, you may not need to do anything. However, if secrets live in a vault that holds other sensitive data, you should create a new vault and move your secrets to it, because **the access system of 1Password is based on vaults, not individual items**.
 
-<Steps>
+You can create multiple vaults to segment access to different environments, services, etc. This can be done using any 1Password app, the web app, or the CLI. [link](https://support.1password.com/create-share-vaults/#create-a-vault)
+
+Remember to grant access to necessary team members, particularly if you plan on using the desktop app auth method during local development, as they will be authenticating as themselves.
+
+:::tip[Vault organization best practices]
+Consider how you want to organize your vaults and service accounts, keeping in mind [best practices](https://support.1password.com/business-security-practices/#access-management-and-the-principle-of-least-privilege). At a minimum, we recommend having a vault for highly sensitive production secrets and another for everything else.
+:::
+
+### Service account setup (for deployed environments)
+
+If you plan on using data from 1Password in deployed environments (CI/CD, production, etc), you will need to create a [service account](https://developer.1password.com/docs/service-accounts/get-started/) to allow machine-to-machine authentication. You could also use a service account for local development, although we recommend using the desktop app auth method described below for convenience.
 
-1. **Create a vault** in your 1Password account which will be used to hold your secrets. You can create multiple vaults to segment access to different environments, services, etc. This can be done using any 1Password app, the web app, or the CLI. [link](https://support.1password.com/create-share-vaults/#create-a-vault)
+This service account token will now serve as your _secret-zero_ - which grants access to the rest of your sensitive data stored in 1Password.
 
-2. **Create a new service account** and grant access to necessary vault(s). This is a special account used for machine-to-machine communication. This can only be done in the 1Password web interface. Be sure to save the new service account token in another vault so you can find it later. [link](https://developer.1password.com/docs/service-accounts/get-started/)
+<Steps>
+1. **Create a new service account** and grant access to necessary vault(s). This is a special account used for machine-to-machine communication. This can only be done in the 1Password web interface. Be sure to save the new service account token in another vault so you can find it later. [link](https://developer.1password.com/docs/service-accounts/get-started/)
     :::note[Vault access is set during creation only]
     Vault access rules cannot be edited after creation, so if your vault setup changes, you will need to create new service account(s) and update the tokens.
     :::
 
-3. **Grant vault access to users/teams (optional)**. Your developers may need access to at least some of your vaults, especially if using the app based auth mentioned below. [link](https://support.1password.com/create-share-vaults-teams/#share-a-vault)
-
-4. **Ensure vault service account access is enabled (optional)**. Each vault has a toggle to disable service account access _in general_. It is on by default, so you will likely not need to do anything. [link](https://developer.1password.com/docs/service-accounts/manage-service-accounts/#manage-access)
+2. **Wire up the service account token in your config**. Add a config item of type `opServiceAccountToken` to hold the token value, and reference it when initializing the plugin.
 
+    ```diff lang="env-spec" title=".env.schema" add="token=$OP_TOKEN"
+    # @plugin(@varlock/1password-plugin)
+    # @initOp(token=$OP_TOKEN)
+    # ---
+    +# @type=opServiceAccountToken @sensitive
+    +OP_TOKEN=
+    ```
+3. **Set your service account token in deployed environments**. Copy the token value from where you saved it earlier, and set it in deployed environments using your platform's env var management UI. Be sure to use the same name as you defined in your schema (e.g. `OP_TOKEN`).
 </Steps>
 
-This service account token will now serve as your _secret-zero_ - which grants access to the rest of your sensitive data stored in 1Password. It must be set locally (unless relying on app-based auth) and in any deployed environments, usually as an environment variable with your platform's env var management UI.
-
-:::tip[Vault organization best practices]
-Consider how you want to organize your vaults and service accounts, keeping in mind [best practices](https://support.1password.com/business-security-practices/#access-management-and-the-principle-of-least-privilege). At a minimum, we recommend having a vault for highly sensitive production secrets and another for everything else.
+:::caution[Ensure service account access is enabled]
+Each vault has a toggle to disable service account access _in general_. It is on by default, so you will likely not need to do anything. [link](https://developer.1password.com/docs/service-accounts/manage-service-accounts/#manage-access)
 :::
 
 
-### Desktop app auth (optional)
+### Desktop app auth (for local dev)
 
 During local development, you may find it convenient to skip the service account tokens and instead rely on your local 1Password desktop app (via the [CLI integration](https://developer.1password.com/docs/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration)), including using its biometric unlocking features.
 
 <Steps>
 1. **Opt-in while initializing the plugin**
     ```diff lang="env-spec" title='.env.schema' add="allowAppAuth=true"
     # @plugin(@varlock/1password-plugin)
-    # @initOpVault(token=$OP_TOKEN, allowAppAuth=true)
+    # @initOp(token=$OP_TOKEN, allowAppAuth=true)
     ```
 
     You may use other functions to conditionally enable this, for example `forEnv(dev)`.
 
 2. **Specify 1Password account (optional)**
     ```diff lang="env-spec" title='.env.schema' add="account=acmeco"
     # @plugin(@varlock/1password-plugin)
-    # @initOpVault(token=$OP_TOKEN, allowAppAuth=true, account=acmeco)
+    # @initOp(token=$OP_TOKEN, allowAppAuth=true, account=acmeco)
     ```
 
     This value is passed through under the `--account` flag to the `op` CLI, and accepts account shorthand, sign-in address, account ID, or user ID.
@@ -111,8 +126,8 @@ The secret reference for invidivual fields within an item can be found by clicki
 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.
 
 ```env-spec /dev|prod/
-# @initOpVault(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=forEnv(dev))
-# @initOpVault(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false)
+# @initOp(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=forEnv(dev))
+# @initOp(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false)
 # ---
 DEV_ITEM=op(dev, op://vault-name/item-name/field-name)
 PROD_ITEM=op(prod, op://vault-name/item-name/field-name)
@@ -130,18 +145,18 @@ PROD_ITEM=op(prod, op://vault-name/item-name/field-name)
 ### Root decorators
 <div class="reference-docs">
 <div>
-#### `@initOpVault()`
+#### `@initOp()`
 
 Initializes an instance of the 1Password plugin - setting up options and authentication. Can be called multiple times to set up different instances.
 
 **Key/value args:**
 - `id` (optional): identifier for this instance, used when multiple instances are needed
-- `token`: service account token. Should be a reference to a config item of type `opServiceAccountToken`.
+- `token` (optional): service account token. Should be a reference to a config item of type `opServiceAccountToken`.
 - `allowAppAuth` (optional): boolean flag to enable authenticating using the local desktop app
 - `account` (optional): limits the `op` cli to connect to specific 1Password account (shorthand, sign-in address, account ID, or user ID)
 
-```env-spec "@initOpVault"
-# @initOpVault(id=notProd, token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
+```env-spec "@initOp"
+# @initOp(id=notProd, token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
 # ---
 # @type=opServiceAccountToken
 OP_TOKEN=