@h3y6e/gunshi-plugin-env 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 heyhoe
+
+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

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @h3y6e/gunshi-plugin-env
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Fill [gunshi](https://gunshi.dev) flags from environment variables.
+
+## Installation
+
+```sh
+# npm
+npm install @h3y6e/gunshi-plugin-env
+
+# deno
+deno add jsr:@h3y6e/gunshi-plugin-env
+```
+
+Requires gunshi 1.x.
+
+## Usage
+
+```ts
+import env, { pluginId } from "@h3y6e/gunshi-plugin-env";
+import type { EnvExtension, PluginId } from "@h3y6e/gunshi-plugin-env";
+import { cli, defineWithTypes } from "gunshi";
+
+const command = defineWithTypes<{ extensions: Record<PluginId, EnvExtension> }>()({
+  name: "greet",
+  args: {
+    loud: { type: "boolean", description: "Shout" },
+  },
+  run: (ctx) => {
+    if (ctx.values.loud) return console.log("HELLO!");
+    console.log(`hello (${ctx.extensions[pluginId].name("loud")}=1 to shout)`);
+  },
+});
+
+await cli(process.argv.slice(2), command, { name: "greet", plugins: [env()] });
+```
+
+```sh
+greet               # hello (GREET_LOUD=1 to shout)
+greet --loud        # HELLO!
+GREET_LOUD=1 greet  # HELLO!
+```
+
+## Features
+
+### Variable names
+
+A flag not given on the command line takes `<CLI>_<FLAG>` in upper snake case: `--dry-run` of `greet` reads `GREET_DRY_RUN`. Positionals, `--help`, and `--version` are not filled.
+
+### Values
+
+As in [usage](https://usage.jdx.dev), a boolean is true only for `1`, `true`, `True`, or `TRUE`. Other types are parsed and validated by gunshi as on the command line, `conflicts` included.
+
+### Context extension
+
+`ctx.extensions[pluginId].name(key)` returns the variable of a flag.
+
+## Limitations
+
+This plugin fills the values just before the command's `run` and puts them only in the context passed to `run`. Before that, gunshi validates arguments with the values from the command line alone, and it passes its own context to the hooks. This leads to the following:
+
+- A `required` flag has to be given on the command line; a variable does not satisfy it. Leave `required` off flags meant to come from variables.
+- `onBeforeCommand` and `onAfterCommand` see the values before the variables fill them. Read the filled values in the command's `run`.
+- Of other plugins, only the decorators of those listed after env in `plugins` see the filled values. Extensions see only the values before the variables fill them.
+
+## API References
+
+[JSR](https://jsr.io/@h3y6e/gunshi-plugin-env/doc)
+
+## License
+
+[MIT](LICENSE)

package/lib/index.d.ts

@@ -0,0 +1,25 @@
+import { PluginWithExtension } from "gunshi/plugin";
+//#region src/plugin.d.ts
+/** The unique identifier of the env plugin */
+export declare const pluginId: "h3y6e:env";
+type PluginId = typeof pluginId;
+/** The env plugin's extension on the command context */
+interface EnvExtension {
+  /** The environment variable that fills the flag with this key */
+  name: (key: string) => string;
+}
+/**
+ * Env plugin
+ *
+ * A flag that is not given on the command line takes the value of `<CLI>_<FLAG>`, both in upper
+ * snake case. As in usage, a boolean is true for `1`, `true`, `True`, or `TRUE` and false
+ * otherwise; any other type is parsed and validated by gunshi as on the command line, and the value
+ * is checked against `conflicts`. A required flag still has to be given on the command line,
+ * because gunshi checks it before plugins run, and the command hooks see the values before the
+ * variables fill them.
+ *
+ * @returns A defined plugin that fills flags from environment variables
+ */
+export default function env(): PluginWithExtension<EnvExtension>;
+//#endregion
+export type { EnvExtension, PluginId };

package/lib/index.js

@@ -0,0 +1,113 @@
+import { parseArgs, resolveArgs } from "gunshi";
+import { plugin } from "gunshi/plugin";
+import { kebabnize } from "gunshi/utils";
+//#region src/plugin.ts
+/**
+* @license MIT
+* @author h3y6e
+*/
+/** The unique identifier of the env plugin */
+const pluginId = "h3y6e:env";
+const BUILTINS = /* @__PURE__ */ new Set(["help", "version"]);
+function snake(text) {
+	return text.replaceAll(/([a-z0-9])([A-Z])|([A-Z])([A-Z][a-z])/g, "$1$3_$2$4").replaceAll(/[^A-Za-z0-9]+/g, "_").replaceAll(/^_|_$/g, "").toUpperCase();
+}
+function flagName(key, arg, toKebab) {
+	return toKebab || arg.toKebab ? kebabnize(key) : key;
+}
+function fromEnv(key, arg, raw, toKebab) {
+	const value = arg.type === "boolean" ? String([
+		"1",
+		"true",
+		"True",
+		"TRUE"
+	].includes(raw)) : raw;
+	const { type, choices, parse, multiple } = arg;
+	const schema = {
+		type,
+		choices,
+		parse,
+		multiple,
+		toKebab: arg.toKebab
+	};
+	const token = `--${flagName(key, arg, toKebab)}=${value}`;
+	return resolveArgs({ [key]: schema }, parseArgs([token]), { toKebab });
+}
+function conflictError(args, given, toKebab) {
+	const schemas = {};
+	const argv = [];
+	for (const [key, arg] of Object.entries(args)) {
+		if (!given(key)) continue;
+		schemas[key] = {
+			type: "string",
+			conflicts: arg.conflicts,
+			toKebab: arg.toKebab
+		};
+		argv.push(`--${flagName(key, arg, toKebab)}=_`);
+	}
+	return resolveArgs(schemas, parseArgs(argv), { toKebab }).error;
+}
+/**
+* Env plugin
+*
+* A flag that is not given on the command line takes the value of `<CLI>_<FLAG>`, both in upper
+* snake case. As in usage, a boolean is true for `1`, `true`, `True`, or `TRUE` and false
+* otherwise; any other type is parsed and validated by gunshi as on the command line, and the value
+* is checked against `conflicts`. A required flag still has to be given on the command line,
+* because gunshi checks it before plugins run, and the command hooks see the values before the
+* variables fill them.
+*
+* @returns A defined plugin that fills flags from environment variables
+*/
+function env() {
+	return plugin({
+		id: pluginId,
+		name: "env",
+		extension: (ctx) => {
+			const cli = ctx.env.name;
+			if (!cli) throw new Error("The env plugin names variables after the CLI; give cli() a name");
+			return { name: (key) => `${snake(cli)}_${snake(key)}` };
+		},
+		setup(ctx) {
+			ctx.decorateCommand((run) => async (c) => {
+				const { name } = c.extensions[pluginId];
+				const values = { ...c.values };
+				const args = c.args;
+				const filled = /* @__PURE__ */ new Set();
+				const errors = [];
+				for (const [key, arg] of Object.entries(args)) {
+					const builtin = BUILTINS.has(key) && c.env.globalOptions?.has(key);
+					if (arg.type === "positional" || builtin || c.explicit[key]) continue;
+					const raw = process.env[name(key)];
+					if (raw === void 0) continue;
+					const parsed = fromEnv(key, arg, raw, c.toKebab);
+					if (parsed.error) errors.push(...parsed.error.errors);
+					else {
+						values[key] = parsed.values[key];
+						filled.add(key);
+					}
+				}
+				const given = (k) => c.explicit[k] || filled.has(k);
+				errors.push(...conflictError(args, given, c.toKebab)?.errors ?? []);
+				if (errors.length > 0) {
+					const error = new AggregateError(errors);
+					const message = await c.env.renderValidationErrors?.(c, error);
+					if (message) c.log(message);
+					throw error;
+				}
+				return run({
+					...c,
+					values
+				});
+			});
+		}
+	});
+}
+//#endregion
+//#region src/index.ts
+/**
+* @license MIT
+* @author h3y6e
+*/
+//#endregion
+export { env as default, pluginId };

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@h3y6e/gunshi-plugin-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "gunshi plugin that fills flags from environment variables",
+  "keywords": [
+    "cli",
+    "env",
+    "gunshi",
+    "plugin"
+  ],
+  "bugs": {
+    "url": "https://github.com/h3y6e/gunshi-plugins/issues"
+  },
+  "license": "MIT",
+  "author": "h3y6e",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h3y6e/gunshi-plugins.git",
+    "directory": "packages/env"
+  },
+  "files": [
+    "lib"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint:jsr": "deno publish --dry-run --allow-dirty",
+    "prepack": "aubr build",
+    "typecheck:deno": "deno check src/index.ts"
+  },
+  "devDependencies": {
+    "gunshi": "^1.0.0-rc.1",
+    "publint": "^0.3.25",
+    "tsdown": "^0.23.0"
+  },
+  "peerDependencies": {
+    "gunshi": "^1.0.0-rc.1"
+  },
+  "engines": {
+    "node": ">= 22.12"
+  }
+}