plugins docs, 1pass plugin, general cleanup

Author: theoephraim

.cursor/rules/varlock.mdc

@@ -28,8 +28,8 @@ actions:
 
       1. File Structure:
          ```
-         .env.schema          # Schema definition with decorators
-         .env                 # Local development values
+         .env.schema          # Schema definition with decorators and default values
+         .env.local           # Local (git-ignored) development overrides
          .env.production      # Production values
          .env.staging         # Staging values
          ```
@@ -41,7 +41,7 @@ actions:
          - Values can be strings, numbers, booleans, or function calls
 
       3. Root Level Decorators:
-         - @envFlag - Sets environment flag key
+         - @currentEnv - Sets current environment env var (e.g., `@currentEnv=$APP_ENV`)
          - @defaultRequired - Sets default required state for all items
          - @defaultSensitive - Sets default sensitive state for all items
 
@@ -52,7 +52,7 @@ actions:
       4. Item Level Decorators:
          - @required - Makes item required (omit if @defaultRequired=true)
          - @sensitive - Marks item as sensitive (omit if @defaultSensitive=true)
-         - @type - Sets value type
+         - @type - Sets value type (omit if basic string with no additional settings)
          - @example - Provides example value
          - @trim - Trims whitespace
          - @deindent - Trims leading whitespace
@@ -112,10 +112,18 @@ examples:
   - input: |
       # Bad: Missing type decorator
       PORT=3000
+      # Bad: Unnecessary type decorator for basic string
+      # @type=string
+      BASIC_STRING
 
-      # Good: With type decorator
+      # Good: With type decorators when necessary
       # @type=port
       PORT=3000
+      # @type=string(startsWith=abc_)
+      STRING_WITH_VALIDATION=
+      # no @type necessary for basic strings
+      BASIC_STRING=
+
     output: "Environment variable with proper type"
 
 metadata:

README.md

@@ -16,15 +16,15 @@
 ## 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
 
 Your `.env.schema` is a declarative schema of your environment variables that lives within version control, so it will never be out of sync.
 
 ```bash
-# @defaultSensitive=false @defaultRequired=infer @envFlag=APP_ENV
+# @defaultSensitive=false @defaultRequired=infer @currentEnv=$APP_ENV
 # ---
 # our environment flag, will control automatic loading of `.env.xxx` files
 # @type=enum(development, preview, production, test

packages/integrations/nextjs/src/next-env-compat.ts

@@ -289,7 +289,7 @@ export function loadEnvConfig(
 
   // we must match @next/env default behaviour for which .env.XXX files to load
   // which is based on the current command (`next dev` vs `next build`) and `NODE_ENV=test`
-  // however we will pass it through and let the user ignore it by setting their own `@envFlag`
+  // however we will pass it through and let the user ignore it by setting their own `@currentEnv`
   let envFromNextCommand = dev ? 'development' : 'production';
   if (process.env.NODE_ENV === 'test') envFromNextCommand = 'test';
   debug('Inferred env mode (to match @next/env):', envFromNextCommand);

packages/plugins/1password/README.md

@@ -25,4 +25,4 @@ OP_TOKEN=
 
 # pull items from 1pass using new `op()` resolver
 XYZ_API_TOKEN=op("op://api-config/xyz/api-key")
-```
+```

packages/plugins/1password/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@varlock/1password-plugin",
-  "description": "Varlock plugin to pull data from 1Password",
+  "description": "Varlock plugin to pull data from 1password",
   "version": "0.0.0",
   "type": "module",
   "repository": {

packages/plugins/1password/tsconfig.json

@@ -1,7 +1,7 @@
 # This .env file uses https://varlock.dev
 # 
 # @defaultRequired=infer @defaultSensitive=false
-# @envFlag=APP_ENV
+# @currentEnv=$APP_ENV
 # @generateTypes(lang='ts', path='env.d.ts')
 # ---
 

packages/varlock-website/.env.schema

@@ -34,6 +34,7 @@ export default defineConfig({
         provider: fontProviders.google(),
         name: 'Inter',
         cssVariable: '--font-default',
+        weights: ['300', '400', '700'],
       },
     ],
   },
@@ -80,7 +81,8 @@ export default defineConfig({
             { label: 'Schema', slug: 'guides/schema' },
             { label: 'Secrets', slug: 'guides/secrets' },
             { label: 'Environments', slug: 'guides/environments' },
-            { label: '@import', slug: 'guides/import' },
+            { label: 'Imports', slug: 'guides/import' },
+            { label: 'Plugins', slug: 'guides/plugins' },
             { label: 'Migrate from dotenv', slug: 'guides/migrate-from-dotenv' },
             { label: 'Telemetry', slug: 'guides/telemetry' },
             { label: 'MCP', slug: 'guides/mcp', badge: 'new' },
@@ -102,6 +104,13 @@ export default defineConfig({
             { label: 'GitHub Actions', slug: 'integrations/github-action' },
           ],
         },
+        {
+          label: 'Plugins',
+          items: [
+            { label: 'Overview', slug: 'plugins/overview' },
+            { label: '1Password', slug: 'plugins/1password' },
+          ],
+        },
         {
           label: 'Reference',
           items: [

packages/varlock-website/astro.config.ts

@@ -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.
+:::