@venn-lang/env 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @venn-lang/env
+
+> The `env` namespace: the variables `venn.toml` declares, read as `env.NAME`.
+
+This plugin contributes no verbs. `env.NAME` is a read, not a call. What it contributes is the name
+itself, so a file that reads configuration has to say so with `use`, exactly like one that makes a
+request or an assertion. The reader should never have to know which names are magic.
+
+## Install
+
+`@venn-lang/env` is part of the stdlib the `venn` CLI and the language server load, so there is nothing
+to install. A file that reads configuration says so:
+
+```ruby
+use "venn/env"
+```
+
+## Usage
+
+```toml
+# venn.toml
+[env.local]
+BASE = "http://localhost:3000"
+
+[env.staging]
+BASE = "https://staging.example.com"
+```
+
+```ruby
+# config.vn
+module demo.config
+
+use "venn/assert"
+use "venn/env"
+
+flow "Config" {
+  step "reads the selected environment" {
+    log "base=${env.BASE} env=${env.name}"
+    expect env.name oneOf ["local", "staging"]
+  }
+}
+```
+
+```bash
+venn test config.vn --env staging
+```
+
+`--env` selects the environment and defaults to `local`. Both `venn run` and `venn test` accept it.
+
+## Names
+
+| Name | Where it comes from |
+| --- | --- |
+| `env.name` | The environment that was selected. Always present, whatever the manifest declares. |
+| `env.ANYTHING_ELSE` | The `[env.<name>]` table of `venn.toml`, a dotenv file, or the real process environment. |
+
+Values come from three places, lowest precedence first:
+
+1. `[env.<name>]` in `venn.toml`: the documented default, committed to the repository.
+2. The dotenv files, in order: `.env`, `.env.<name>`, `.env.local`, `.env.<name>.local`, or whatever
+   `[env] files` lists instead.
+3. The environment the process was started with.
+
+The real environment wins, because that is how CI passes a token in, and a value set on the command
+line should never lose to a file in the repository. It overrides rather than adds: a name has to be
+declared in one of the first two places for the third to fill it. That is what keeps `PATH` and
+`TEMP` out of the editor's completion, and what stops a typo silently reading something off the
+machine. A value that exists only in CI and is never declared is read through `secrets.*`, which
+needs no declaration and redacts what it returns.
+
+## Diagnostics
+
+`env.KEYCLOAK_URL` used to resolve to nothing at all: a typo produced an empty string and a puzzling
+404 rather than an error. Every `env.*` read is now checked against what the manifest declares,
+including reads written inside a `"${…}"` placeholder.
+
+| Code | When |
+| --- | --- |
+| `VN2007` | `env.*` is read in a file that never wrote `use "venn/env"`. |
+| `VN2006` | The name is not declared in `venn.toml`. The nearest declared name is offered: `"env.BAES" is not declared in venn.toml, did you mean "env.BASE"?` |
+
+Nothing is reported when the manifest could not be read at all: a wrong error about a variable that
+does exist is worse than no error.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `envPlugin` (also the default export) | The `PluginDefinition`: namespace `env` and nothing else. No actions, no matchers, no `typeDefs`, no required capability. |
+
+The namespace is deliberately empty. The values are the strings `venn.toml` declares, and the check
+above, not a type, is what catches `env.TPYO`.
+
+## See also
+
+- [`@venn-lang/cli`](../cli) for `--env`, the manifest and the dotenv files it reads.
+- [`@venn-lang/runtime`](../runtime) for the check that produces `VN2006` and `VN2007`.
+- [`@venn-lang/assert`](../std-assert) for the matchers used beside a configuration read.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { PluginDefinition } from "@venn-lang/sdk";
+//#region src/plugin.d.ts
+/**
+ * The `env` plugin: the namespace behind `env.NAME`.
+ *
+ * It contributes no verbs, because `env.NAME` is a read, not a call. What it
+ * contributes is the name itself, so a file that reads configuration has to say
+ * so with `use`, exactly like one that makes a request or an assertion. The
+ * values come from the `[env.*]` tables of `venn.toml`, chosen with `--env`.
+ */
+declare const envPlugin: PluginDefinition;
+//#endregion
+export { envPlugin as default, envPlugin };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/plugin.ts"],"mappings":";;;;;;;;;;cAUa,WAAW"}

package/dist/index.js

@@ -0,0 +1,19 @@
+import { definePlugin } from "@venn-lang/sdk";
+//#region src/plugin.ts
+/**
+* The `env` plugin: the namespace behind `env.NAME`.
+*
+* It contributes no verbs, because `env.NAME` is a read, not a call. What it
+* contributes is the name itself, so a file that reads configuration has to say
+* so with `use`, exactly like one that makes a request or an assertion. The
+* values come from the `[env.*]` tables of `venn.toml`, chosen with `--env`.
+*/
+const envPlugin = definePlugin({
+	name: "venn/env",
+	version: "0.0.0",
+	namespace: "env"
+});
+//#endregion
+export { envPlugin as default, envPlugin };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/plugin.ts"],"sourcesContent":["import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\n\n/**\n * The `env` plugin: the namespace behind `env.NAME`.\n *\n * It contributes no verbs, because `env.NAME` is a read, not a call. What it\n * contributes is the name itself, so a file that reads configuration has to say\n * so with `use`, exactly like one that makes a request or an assertion. The\n * values come from the `[env.*]` tables of `venn.toml`, chosen with `--env`.\n */\nexport const envPlugin: PluginDefinition = definePlugin({\n  name: \"venn/env\",\n  version: \"0.0.0\",\n  namespace: \"env\",\n});\n"],"mappings":";;;;;;;;;;AAUA,MAAa,YAA8B,aAAa;CACtD,MAAM;CACN,SAAS;CACT,WAAW;AACb,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@venn-lang/env",
+  "version": "0.1.0",
+  "description": "The env namespace: the variables venn.toml declares, read as env.NAME.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "env"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-env#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-env"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// The `env` namespace, read from venn.toml.
+export { envPlugin, envPlugin as default } from "./plugin.js";

package/src/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+
+/**
+ * The `env` plugin: the namespace behind `env.NAME`.
+ *
+ * It contributes no verbs, because `env.NAME` is a read, not a call. What it
+ * contributes is the name itself, so a file that reads configuration has to say
+ * so with `use`, exactly like one that makes a request or an assertion. The
+ * values come from the `[env.*]` tables of `venn.toml`, chosen with `--env`.
+ */
+export const envPlugin: PluginDefinition = definePlugin({
+  name: "venn/env",
+  version: "0.0.0",
+  namespace: "env",
+});