gulp-mu-gulp-api 0.3.13 → 0.4.0

package/README.md

@@ -37,6 +37,12 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.4.0
+
+- **Added** `GetParameters()` / `GetParameter(id, fallback)` — values for the inputs a task declared with `µParameters`. µGulp asks for them once before the task body runs and passes them in as `MICROGULP_PARAMS` (JSON) plus one flat `MICROGULP_PARAM_<ID>` per parameter.
+- Works outside µGulp too: set the same environment variables by hand (`MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY`) or rely on the declared defaults.
+- Related gulpfile metadata added by µGulp 0.7.0: `µParameters` (declarative inputs), `µKeyBinding` (dashboard shortcut), `µWatch` (file trigger). They are plain task properties — no API call needed.
+
 ### 0.3.13
 
 - **Updated** `PlaySignal` / `PlaySound` docs and CLI fallbacks for the µGulp sound schema (`taskSuccess`, `taskFailed`, `requestAlert`, …). Legacy presets `success` / `error` / `attention` remain valid.
@@ -184,6 +190,33 @@ let values = await RequestForm({
 | `RequestFontInput(options)` | Font selection (`options`: font list) |
 | `RequestSelectInput(options)` | Single selection from a fixed option list |
 | `RequestMultiSelectInput(options)` | Multi selection (checkbox group), always resolves to a `string[]` |
+| `GetParameters()` | Values of the task's declared `µParameters` (map id → typed value) |
+| `GetParameter(id, fallback?)` | Single declared parameter value, with an env fallback |
+
+### Declared task parameters (`µParameters`)
+
+Instead of asking inside the task body, declare the inputs once and read them at the top of the task. µGulp shows one form before the run, remembers the answers for the next run and passes the values in as environment:
+
+```javascript
+import { GetParameters, Log } from 'gulp-mu-gulp-api';
+
+export async function DEPLOY() {
+    let { target, tag, dryRun } = GetParameters();
+    Log('Deploying <tag/> to <target/><context="task log"/>', { tag, target });
+}
+DEPLOY.µParameters = [
+    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging' },
+    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
+    { id: 'dryRun', type: 'boolean', default: true },
+    { id: 'token', type: 'password' },   // never stored, never logged
+];
+```
+
+The declaration uses the same field types as `RequestForm` plus the `boolean` shorthand (a single checkbox). `id` must be env-var safe. Values arrive as `MICROGULP_PARAMS` (JSON) and `MICROGULP_PARAM_<ID>`, so shell steps in the task can read them as well — and running the gulpfile through the plain gulp CLI works by setting those variables yourself:
+
+```bash
+MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY
+```
 
 ### Localized task metadata (`.i18xRegister()` + placeholders)
 
@@ -314,6 +347,12 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.4.0
+
+- **Neu** `GetParameters()` / `GetParameter(id, fallback)` — Werte für die Eingaben, die ein Task per `µParameters` deklariert hat. µGulp fragt sie einmal vor dem Task-Rumpf ab und übergibt sie als `MICROGULP_PARAMS` (JSON) plus je Parameter ein flaches `MICROGULP_PARAM_<ID>`.
+- Funktioniert auch ohne µGulp: dieselben Umgebungsvariablen von Hand setzen (`MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY`) oder die deklarierten Defaults nutzen.
+- Ergänzende Gulpfile-Metadaten aus µGulp 0.7.0: `µParameters` (deklarative Eingaben), `µKeyBinding` (Dashboard-Kürzel), `µWatch` (Datei-Trigger). Reine Task-Eigenschaften — kein API-Aufruf nötig.
+
 ### 0.3.13
 
 - **Aktualisiert** `PlaySignal` / `PlaySound` für das µGulp-Sound-Schema (`taskSuccess`, `taskFailed`, `requestAlert`, …). Legacy-Presets `success` / `error` / `attention` bleiben gültig.
@@ -461,6 +500,33 @@ let values = await RequestForm({
 | `RequestFontInput(options)` | Schriftart-Auswahl (`options`: Font-Liste) |
 | `RequestSelectInput(options)` | Einzelauswahl aus fester Optionsliste |
 | `RequestMultiSelectInput(options)` | Mehrfachauswahl (Checkbox-Gruppe), löst immer mit `string[]` auf |
+| `GetParameters()` | Werte der per `µParameters` deklarierten Task-Eingaben (Map id → typisierter Wert) |
+| `GetParameter(id, fallback?)` | Einzelner deklarierter Parameterwert, mit Env-Fallback |
+
+### Deklarierte Task-Parameter (`µParameters`)
+
+Statt im Task-Rumpf zu fragen, werden die Eingaben einmal deklariert und am Task-Anfang gelesen. µGulp zeigt vor dem Lauf ein Formular, merkt die Antworten für den nächsten Lauf und übergibt die Werte als Umgebung:
+
+```javascript
+import { GetParameters, Log } from 'gulp-mu-gulp-api';
+
+export async function DEPLOY() {
+    let { target, tag, dryRun } = GetParameters();
+    Log('Deploying <tag/> to <target/><context="task log"/>', { tag, target });
+}
+DEPLOY.µParameters = [
+    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging' },
+    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
+    { id: 'dryRun', type: 'boolean', default: true },
+    { id: 'token', type: 'password' },   // wird nie gespeichert oder geloggt
+];
+```
+
+Die Deklaration nutzt die Feldtypen von `RequestForm` plus die Kurzform `boolean` (eine einzelne Checkbox). `id` muss als Umgebungsvariablenname taugen. Die Werte kommen als `MICROGULP_PARAMS` (JSON) und `MICROGULP_PARAM_<ID>` an — auch Shell-Schritte im Task können sie lesen, und unter der reinen gulp-CLI setzt man sie einfach selbst:
+
+```bash
+MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY
+```
 
 ### Lokalisierte Task-Metadaten (`.i18xRegister()` + Platzhalter)
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.13",
-	"description": "Public task API for the µGulp orchestrator: progress reporting, sound signals, speech output, localized console output (i18x) and interactive UI inputs (text, password, number, textarea, color, font, select, radio, multi-select checkbox, range slider, date/time, file) from within gulp tasks — with graceful CLI fallbacks when running without µGulp.",
+	"version": "0.4.0",
+	"description": "Public task API for the µGulp orchestrator: progress reporting, declared task parameters, sound signals, speech output, localized console output (i18x) and interactive UI inputs (text, password, number, textarea, color, font, select, radio, multi-select checkbox, range slider, date/time, file) from within gulp tasks — with graceful CLI fallbacks when running without µGulp.",
 	"type": "module",
 	"main": "src/index.mjs",
 	"exports": {
@@ -28,6 +28,9 @@
 		"prompt",
 		"multiselect",
 		"form",
+		"parameters",
+		"watch",
+		"keybinding",
 		"task-api"
 	],
 	"license": "MIT",

package/src/index.mjs

@@ -855,6 +855,62 @@ export function ClearRegisteredDashboardFonts() {
 	registeredDashboardFonts.clear();
 }
 
+// -------------------------------------------------
+// declared task parameters (µParameters)
+// -------------------------------------------------
+
+/**
+ * Values for the parameters a task declared with `µParameters`. µGulp collects
+ * them once before the task body runs (dashboard form, remembered defaults or
+ * values handed in by a repeat run) and passes them in as environment, so this
+ * works from any npm package in the pipeline.
+ *
+ * Outside µGulp the same values can be supplied by hand:
+ * `MICROGULP_PARAMS='{"target":"staging"}' npx gulp DEPLOY` — or per parameter
+ * with `MICROGULP_PARAM_TARGET=staging`.
+ *
+ * @returns {Record<string, any>} typed values (strings, numbers, booleans, string lists)
+ *
+ * @example
+ * export async function DEPLOY() {
+ *     let { target, dryRun } = GetParameters();
+ *     Log('Deploying to <target/><context="task log"/>', { target });
+ * }
+ * DEPLOY.µParameters = [
+ *     { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging' },
+ *     { id: 'dryRun', type: 'boolean', default: true },
+ * ];
+ */
+export function GetParameters() {
+	let raw = process.env.MICROGULP_PARAMS;
+	if (!raw) return {};
+	try {
+		let parsed = JSON.parse(raw);
+		if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Single declared parameter value.
+ *
+ * @param {string} _id parameter id as declared in µParameters
+ * @param {any} [_fallback] returned when the parameter was not answered
+ * @returns {any}
+ */
+export function GetParameter(_id, _fallback) {
+	let values = GetParameters();
+	if (Object.hasOwn(values, _id) && values[_id] != null && values[_id] !== '') {
+		return values[_id];
+	}
+	// Flat per-parameter env fallback for CLI runs and shell steps.
+	let flat = process.env['MICROGULP_PARAM_' + String(_id).toUpperCase()];
+	if (flat != null && flat !== '') return flat;
+	return _fallback;
+}
+
 export default {
 	IsMicroGulp,
 	IsµGulp,
@@ -862,6 +918,8 @@ export default {
 	RegisterDashboardFont,
 	GetRegisteredDashboardFonts,
 	ClearRegisteredDashboardFonts,
+	GetParameters,
+	GetParameter,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,