gulp-mu-gulp-api 0.3.12 → 0.4.0

package/README.md

@@ -37,6 +37,16 @@ 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.
+
 ### 0.3.12
 
 - **Added** `RegisterDashboardFont({ id, file, family?, usage? })` — registers a workspace font for µGulp dashboard **task icons** and/or **run-log** typography. `usage`: `'task-icons'` (default), `'log'`, or `'all'`. Call at gulpfile load time; the scan worker forwards the registry to the engine.
@@ -123,8 +133,8 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');              // preset: success | error | attention
-    PlaySound('success');               // named atlas sample
+    PlaySignal('success');              // preset → taskSuccess (also error→taskFailed, attention→requestAlert)
+    PlaySound('taskSuccess');           // named atlas sample (see MicroGulpSoundSchema.md)
     PlaySound('engine', { loop: true }); // loop until StopSound('engine')
     StopSound('engine');
     Speak('Theme build finished.');
@@ -165,8 +175,8 @@ let values = await RequestForm({
 | `GetLid()` / `SetLid(lid?)` | Active language id; `SetLid` clears to automatic when omitted |
 | `ReportProgress(value, label?)` | Report progress `0..1` to the task progress bar |
 | `CreateProgress(label?)` | Reporter object with `Update(value, stepLabel?)` and `Done()` |
-| `PlaySignal(signal?)` | Preset acoustic signal: `'success'` \| `'error'` \| `'attention'` (default) |
-| `PlaySound(sample, options?)` | Named sample from the dashboard sound atlas; `options.loop` repeats until `StopSound` |
+| `PlaySignal(signal?)` | Preset or schema name; presets: `'success'`→`taskSuccess`, `'error'`→`taskFailed`, `'attention'`→`requestAlert` |
+| `PlaySound(sample, options?)` | Named sample from the dashboard sound atlas (e.g. `taskStart`, `requestInfo`); `options.loop` repeats until `StopSound` |
 | `StopSound(sample)` | Stops a looping sample started with `PlaySound(sample, { loop: true })` |
 | `RegisterDashboardFont(spec)` | Registers a workspace font for dashboard task icons / run-log (`id`, `file`, optional `family` / `usage`: `task-icons`\|`log`\|`all`) |
 | `GetRegisteredDashboardFonts()` | Snapshot of fonts registered in this process (scan worker / tests) |
@@ -180,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)
 
@@ -310,6 +347,16 @@ 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.
+
 ### 0.3.12
 
 - **Neu** `RegisterDashboardFont({ id, file, family?, usage? })` — registriert einen Workspace-Font für **Task-Icons** und/oder die **Run-Log**-Typografie im µGulp-Dashboard. `usage`: `'task-icons'` (Default), `'log'` oder `'all'`. Aufruf beim Laden des Gulpfiles; der Scan-Worker reicht die Registry an die Engine weiter.
@@ -396,8 +443,8 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');              // preset: success | error | attention
-    PlaySound('success');               // named atlas sample
+    PlaySignal('success');              // preset → taskSuccess (also error→taskFailed, attention→requestAlert)
+    PlaySound('taskSuccess');           // named atlas sample (see MicroGulpSoundSchema.md)
     PlaySound('engine', { loop: true }); // loop until StopSound('engine')
     StopSound('engine');
     Speak('Theme build finished.');
@@ -438,8 +485,8 @@ let values = await RequestForm({
 | `GetLid()` / `SetLid(lid?)` | Aktive Sprach-ID; `SetLid` ohne Argument = automatische Auflösung |
 | `ReportProgress(value, label?)` | Fortschritt `0..1` an die Task-Progressbar melden |
 | `CreateProgress(label?)` | Reporter-Objekt mit `Update(value, stepLabel?)` und `Done()` |
-| `PlaySignal(signal?)` | Vorgabe-Signal: `'success'` \| `'error'` \| `'attention'` (Default) |
-| `PlaySound(sample, options?)` | Benanntes Sample aus dem Sound-Atlas; `options.loop` wiederholt bis `StopSound` |
+| `PlaySignal(signal?)` | Vorgabe oder Schema-Name; Presets: `'success'`→`taskSuccess`, `'error'`→`taskFailed`, `'attention'`→`requestAlert` |
+| `PlaySound(sample, options?)` | Benanntes Sample aus dem Sound-Atlas (z. B. `taskStart`, `requestInfo`); `options.loop` wiederholt bis `StopSound` |
 | `StopSound(sample)` | Stoppt eine Schleife von `PlaySound(sample, { loop: true })` |
 | `RegisterDashboardFont(spec)` | Registriert einen Workspace-Font für Dashboard-Task-Icons / Run-Log (`id`, `file`, optional `family` / `usage`: `task-icons`\|`log`\|`all`) |
 | `GetRegisteredDashboardFonts()` | Snapshot der in diesem Prozess registrierten Fonts (Scan-Worker / Tests) |
@@ -453,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.12",
-	"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

@@ -287,29 +287,35 @@ export function LogChart(_spec) {
 /**
  * Plays an acoustic signal in the µGulp dashboard (WebAudio, respects the
  * dashboard audio settings: mute/volume). CLI fallback: terminal bell for
- * 'attention' and 'error' on a TTY, silent otherwise.
+ * 'attention' / 'error' (and their schema aliases) on a TTY, silent otherwise.
  *
- * @param {'success'|'error'|'attention'} [_signal]
+ * Presets map to atlas samples: `success`→`taskSuccess`, `error`→`taskFailed`,
+ * `attention`→`requestAlert`. New schema names (`taskStart`, `requestInfo`, …)
+ * are also accepted.
+ *
+ * @param {string} [_signal]
  */
 export function PlaySignal(_signal = 'attention') {
 	if (IsMicroGulp()) {
 		process.send({ type: 'sound', signal: _signal });
 		return;
 	}
-	if (process.stdout.isTTY && (_signal === 'attention' || _signal === 'error')) {
+	let key = String(_signal ?? '').trim();
+	if (process.stdout.isTTY && (key === 'attention' || key === 'error' || key === 'requestAlert' || key === 'taskFailed')) {
 		process.stdout.write('\u0007');
 	}
 }
 
 /**
  * Plays a named sample from the dashboard sound atlas (µAU). Sample names match
- * the files bundled with µGulp (`success`, `error`, `attention`, or custom
- * atlas entries in the consumer skin). When `loop` is true the sample repeats
- * until `StopSound(sample)` is called.
+ * the files bundled with µGulp (see `dev/docs/MicroGulpSoundSchema.md`), e.g.
+ * `taskSuccess`, `taskFailed`, `requestAlert`, or custom atlas entries in a
+ * consumer theme pack. When `loop` is true the sample repeats until
+ * `StopSound(sample)` is called.
  *
  * CLI fallback: logs `[sound] <name>` on a TTY, silent otherwise.
  *
- * @param {string} _sample atlas sample name (e.g. `'success'`)
+ * @param {string} _sample atlas sample name (e.g. `'taskSuccess'`)
  * @param {object} [_options]
  * @param {boolean} [_options.loop] repeat until stopped (default `false`)
  */
@@ -849,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,
@@ -856,6 +918,8 @@ export default {
 	RegisterDashboardFont,
 	GetRegisteredDashboardFonts,
 	ClearRegisteredDashboardFonts,
+	GetParameters,
+	GetParameter,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,