gulp-mu-gulp-api 0.3.13 → 0.4.1

package/README.md

@@ -37,6 +37,17 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.4.1
+
+- **Fixed** a placeholder with an unknown named format rendered as an empty string instead of its value — gulp lifecycle lines lost their duration (`Finished 'task' after`). The raw value is kept when the format is missing.
+- **Fixed** `SetLid()` kept the dictionary of the previous language cached, so a language switch inside a running worker could still translate with stale texts.
+
+### 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 +195,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 +352,17 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.4.1
+
+- **Behoben** Ein Platzhalter mit unbekanntem benanntem Format wurde als leerer Text gerendert statt mit seinem Wert — den Gulp-Lifecycle-Zeilen fehlte dadurch die Dauer (`Finished 'task' after`). Fehlt das Format, bleibt der Rohwert erhalten.
+- **Behoben** `SetLid()` behielt das Wörterbuch der vorherigen Sprache im Cache; ein Sprachwechsel im laufenden Worker konnte weiter mit veralteten Texten übersetzen.
+
+### 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 +510,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.1",
+	"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/i18x-engine.mjs

@@ -627,7 +627,10 @@ export function Trans(_text, _placeholders, _ctx) {
 					let subContext = localFormats ? { ...ctx, formats: { ...(ctx.formats ?? {}), ...localFormats } } : ctx;
 					value = FormatValue(Number(value) || 0, attrValue, subContext);
 				} else {
-					value = '';
+					// Missing named format must not swallow the placeholder (e.g.
+					// gulp lifecycle "after <duration format="progressDuration"/>"
+					// would otherwise render as "Finished 'task' after ").
+					value = value === undefined || value === null ? '' : String(value);
 				}
 			} else if (attrKey === 'enumeration') {
 				let options = attrValue.split('|');

package/src/i18x.mjs

@@ -195,8 +195,10 @@ export function GetLid() {
  */
 export function SetLid(_lid) {
 	activeLid = _lid ? _BestAvailableLid(_lid, _AvailableLids()) : null;
+	dictionaryCache.clear();
 	formatDefinitionCache.clear();
 	formatRegistryCache.clear();
+	availableLids = null;
 }
 
 /** Loads and caches `<dir>/<lid>.json`; a missing/broken file yields source text. */

package/src/index.mjs

@@ -386,9 +386,11 @@ export function Speak(_text, _options) {
  * { value, label?, checked?, disabled? }.
  *
  * Validation rules: { required?, minLength?, pattern?, minSelected? } —
- * checks run asynchronously in the webview before submission.
+ * checks run in the webview; required / minSelected also keep the submit
+ * button disabled until the form is valid. Multi-select `required` means
+ * at least one option.
  *
- * @param {object} _form { title, fields: [...] }
+ * @param {object} _form { title?, submitLabel?, fields: [...] }
  * @returns {Promise<object>} map fieldId -> value
  */
 export async function RequestForm(_form) {
@@ -855,6 +857,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 +920,8 @@ export default {
 	RegisterDashboardFont,
 	GetRegisteredDashboardFonts,
 	ClearRegisteredDashboardFonts,
+	GetParameters,
+	GetParameter,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,