more wip

Author: theoephraim

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-PRs are always welcome. 
+PRs are always welcome.
 
 **First, please read our [Code of Conduct](CODE_OF_CONDUCT.md).**
 
@@ -31,7 +31,11 @@ pnpm build:libs
 - [packages/vscode-plugin](./packages/vscode-plugin) - VSCode extension for @env-spec
 - [packages/integrations/nextjs](./packages/integrations/nextjs) - Next.js integration for varlock
 
-> See the README.md for each package for more details. 
+> See the README.md for each package for more details.
 
 
+## Debugging
 
+It is often useful to enable source maps in traces during local development.
+
+To do so run `export NODE_OPTIONS=--enable-source-maps` in your active terminal.

README.md

@@ -32,11 +32,11 @@ APP_ENV=development # default value, can override
 
 # API port
 # @type=port @example=3000
-API_PORT= 
+API_PORT=
 
 # API url including _expansion_ referencing another env var
 # @required @type=url
-API_URL=http://localhost:${API_PORT} 
+API_URL=http://localhost:${API_PORT}
 
 # API key with validation, securely fetched from 1Password
 # @required @sensitive @type=string(startsWith=sk-)
@@ -49,7 +49,7 @@ SOME_SERVICE_API_URL=https://api.someservice.com
 
 ## Installation
 
-You can get started with varlock by installing the CLI: 
+You can get started with varlock by installing the CLI:
 
 ```bash
 # Run the installation wizard, which will install as a dependency in a JavaScript project
@@ -67,13 +67,13 @@ See the full [installation docs](https://varlock.dev/getting-started/installatio
 
 ## Workflow
 
-Validate your `.env.schema` and pretty print your environment variables with: 
+Validate your `.env.schema` and pretty print your environment variables with:
 
 ```bash
 varlock load
 ```
 
-If you need to pass resolved env vars into another process, you can run: 
+If you need to pass resolved env vars into another process, you can run:
 
 ```bash
 varlock run -- python script.py
@@ -85,7 +85,7 @@ Or you can integrate more deeply with one of our [integrations](https://varlock.
 
 Varlock is built on top of @env-spec, a new DSL for attaching a schema and additional functionality to .env files using JSDoc style comments. The @env-spec package contains a parser and info about the spec itself.
 
-- @env-spec [docs](https://varlock.dev/env-spec/overview/) 
+- @env-spec [docs](https://varlock.dev/env-spec/overview/)
 - @env-spec [RFC](https://github.com/dmno-dev/varlock/discussions/17)
 
 

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

@@ -0,0 +1,21 @@
+
+# @plugin(./node_modules/@varlock/1password-plugin)
+# # @initPlugin(@varlock/1password-plugin, id=1pass, token=$OP_TOKEN, allowAppAuth=false)
+#
+# # @plugin(https://varlock-plugins-registry.dmno.workers.dev/varlock-1password-plugin-0.0.0.tgz)
+# @initOpVault(id=v1, account=dmnoinc, token=$OP_TOKEN, allowAppAuth=forEnv(dev))
+# # @initOpVault(id=v2, account=dmnoinc, token=$OP_TOKEN, allowAppAuth=true)
+#
+#
+# @defaultRequired=infer @defaultSensitive=false
+# ---
+
+
+# @sensitive @type=opServiceAccountToken
+OP_TOKEN=
+
+OP_VAULT_NAME=example
+
+OP1=op(v1, "op://dev test/${OP_VAULT_NAME}/credential")
+# OP2=op(v2, "op://dev test/${OP_VAULT_NAME}/staging")
+OP3=op(v1, "op://dev test/${OP_VAULT_NAME}/production")

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

@@ -0,0 +1,27 @@
+z# @defaultRequired=infer @defaultSensitive=false
+# @generateTypes(lang=ts, path=env.d.ts)
+#
+# @currentEnv=$APP_ENV
+# # @envFlag=APP_ENV
+# # @badDecorator
+#
+# @import(./.env.op)
+# ---
+
+# our environment flag
+# @type=enum(dev, preview, prod, test)
+# @docsUrl=https://example.com/docs/app_env
+APP_ENV=dev
+
+# some description
+# @required=true
+# @docs(https://example1.com)
+# @docs("Link label", https://example1.com)
+# @icon="streamline-block:smileys-sad"
+ITEM1=foo
+
+FOR_ENV_CHECK=forEnv(dev)
+
+EQ_CHECK=eq(1, 2)
+
+IF_EQ_CHECK=if(eq(1, 1), "yes", "no")

example-monorepo/packages/plugin-test/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "plugin-test",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "load": "varlock load"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@varlock/1password-plugin": "link:../../../packages/plugins/1password",
+    "varlock": "link:../../../packages/varlock"
+  },
+  "packageManager": "pnpm@10.14.0"
+}

example-monorepo/pnpm-lock.yaml

@@ -44,5 +44,5 @@
     "node": ">=22",
     "pnpm": ">=10"
   },
-  "packageManager": "pnpm@10.14.0"
+  "packageManager": "pnpm@10.18.3+sha512.bbd16e6d7286fd7e01f6b3c0b3c932cda2965c06a908328f74663f10a9aea51f1129eea615134bf992831b009eabe167ecb7008b597f40ff9bc75946aadfb08d"
 }

package.json

@@ -40,13 +40,10 @@ ConfigItem =
     });
   }
 
-ConfigItemKey = 
-  $([a-zA-Z_] [a-zA-Z0-9_.-]*)
+ConfigItemKey = $([a-zA-Z_] [a-zA-Z0-9_.-]*)
 
 ConfigItemValue = FunctionCall / multiLineString / quotedString / unquotedString
 
-
-
 CommentBlock =
   // not sure if we want to treat these as decorators if within comment block?
   comments:(@(IgnoredDecoratorComment / DecoratorComment / Comment) _n)+
@@ -59,7 +56,7 @@ CommentBlock =
     })
   }
 
-Comment = 
+Comment =
   !(Divider)
   "#" leadingSpace:$_ contents:$(
     // $("@" [a-zA-Z]+ ":"? __ [a-zA-Z] [^@\n]*)
@@ -98,17 +95,17 @@ DecoratorComment =
     })
   }
 
-Decorator = 
+Decorator =
   "@" name:DecoratorName
-  valueOrFnArgs:( 
-    "()" { return new ParsedEnvSpecFunctionArgs({ values: [] })}
-    / ("(" @FunctionArgs? ")")
-    / ("=" @(DecoratorValue))
+  val:(
+    FunctionArgs
+    / "=" DecoratorValue
   )?
   {
     return new ParsedEnvSpecDecorator({
       name,
-      valueOrFnArgs,
+      value: Array.isArray(val) ? val[1] : val,
+      isBareFnCall: val && !Array.isArray(val),
       _location: location(),
     })
   }
@@ -121,36 +118,44 @@ DecoratorValue = FunctionCall / quotedString / unquotedStringWithoutSpaces
 
 
 FunctionCall =
-  name:FunctionName "(" _ args:FunctionArgs? _ ")"
+  name:FunctionName
+  args:FunctionArgs  // includes the parens
   {
     return new ParsedEnvSpecFunctionCall({
       name,
-      args: args || new ParsedEnvSpecFunctionArgs({ values: [] }),
+      args,
       _location: location(),
     });
   }
+
 FunctionName = $([a-zA-Z] [a-zA-Z0-9_]*)
+
+// function args are a list, can be either array, or key/value, or mixed
+// fn(arr1, arry2, key=val, key2=val2)
 FunctionArgs =
+  "(" _
   values:(
     (
       (key:FunctionArgKeyName "=" val:FunctionArgValue { return new ParsedEnvSpecKeyValuePair({ key, val })})
       / FunctionArgValue
     )|1.., _ "," _|
-  )
+  )?
+  _ ")"
   {
     return new ParsedEnvSpecFunctionArgs({
-      values,
+      values: values || [],
       _location: location(),
     });
   }
+
 FunctionArgKeyName = $([a-zA-Z] [a-zA-Z0-9_]*)
 FunctionArgValue =
   FunctionCall
   / quotedString
   // slightly different here - can contain "#", cannot contain ")" or ","
-  / $([^ \n,)]+) { return new ParsedEnvSpecStaticValue({ rawValue: text(), _location: location() }) } 
+  / $([^ \n,)]+) { return new ParsedEnvSpecStaticValue({ rawValue: text(), _location: location() }) }
 
-Divider = 
+Divider =
   "#" leadingSpace:$_ contents:$([-=*#]|3..| [^\n]*) _n
   {
     return new ParsedEnvSpecDivider({