gulp-mu-gulp-api 0.3.3 → 0.3.5

package/README.md

@@ -32,6 +32,11 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.5
+
+- **Added** `PlaySound(sample, { loop? })` and `StopSound(sample)` — play named samples from the dashboard µAU sound atlas; `loop: true` repeats until `StopSound`.
+- **Changed** npm README: clearer i18x section (`Log`/`Warn` vs `.i18xTrans()` / `.i18xRegister()`).
+
 ### 0.3.3
 
 - **Changed** npm README: centered µGulp logo and µGulp ready badge (absolute raw URLs from the µGulp repo).
@@ -50,7 +55,7 @@ npm install gulp-mu-gulp-api
 ## Usage
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -77,7 +82,10 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');
+    PlaySignal('success');              // preset: success | error | attention
+    PlaySound('success');               // named atlas sample
+    PlaySound('engine', { loop: true }); // loop until StopSound('engine')
+    StopSound('engine');
     Speak('Theme build finished.');
 }
 BUILD_THEME.µDisplayName = 'Build Theme<context="µDisplayName"/>'.i18xRegister();
@@ -106,12 +114,16 @@ let values = await RequestForm({
 | :--- | :--- |
 | `IsMicroGulp()` / `IsµGulp()` | `true` when the task runs under µGulp™ with an attached dashboard |
 | `InstallStringExtensions()` | Installs µLib-compatible `String.prototype.i18xTrans()`/`i18xRegister()` (auto-run on import) |
-| `Log(text, values?)` / `Warn` / `LogError` | Localized `console.*` via i18x (`<context="task log"/>` etc.) |
-| `Translate(text, values?)` | Returns the translated string without logging |
+| `Log(text, values?)` / `Warn` / `LogError` | Localized `console.*` via i18x (`<context="task log"/>` etc.) — preferred for task log output |
+| `Translate(text, values?)` | Low-level: returns the translated string without logging (rarely needed directly) |
+| `"phrase".i18xTrans(values?)` | Prototype sugar for `Translate` — same result, ergonomic in expressions |
+| `"phrase".i18xRegister()` | Registers metadata text (returns the source phrase unchanged as the i18x key) |
 | `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?)` | Acoustic signal in the dashboard: `'success'` \| `'error'` \| `'attention'` (default) |
+| `PlaySignal(signal?)` | Preset acoustic signal: `'success'` \| `'error'` \| `'attention'` (default) |
+| `PlaySound(sample, options?)` | Named sample from the dashboard sound atlas; `options.loop` repeats until `StopSound` |
+| `StopSound(sample)` | Stops a looping sample started with `PlaySound(sample, { loop: true })` |
 | `Speak(text, options?)` | Speech output in the dashboard; `options`: `{ rate?, pitch?, volume? }` per-call overrides |
 | `RequestForm(form)` | Request a complete form; resolves with `{ fieldId: value, … }` |
 | `RequestTextInput(options)` | Single text field (with `validate` rules) |
@@ -172,6 +184,7 @@ A field descriptor is `{ id, type, label, default?, options?, validate?, min?, m
 | :--- | :--- | :--- |
 | `ReportProgress` | updating progress line | log line every 10% step |
 | `PlaySignal` | terminal bell (`attention`/`error`) | silent |
+| `PlaySound` / `StopSound` | `[sound] <name>` log line | silent |
 | `Speak` | `[speech]` log line | `[speech]` log line |
 | text/password/number/range input | readline prompt (Enter = default) | default value |
 | font/select/radio input | numbered list + readline | default value |
@@ -183,6 +196,22 @@ Sound and speech playback (mute, volume, speech rate/pitch) is configured centra
 
 MIT — © 2026 Meinolf Amekudzi
 
+### Publishing (maintainers)
+
+From the µGulp repo root (requires `npm login` and 2FA OTP when enabled):
+
+```powershell
+# PowerShell
+$env:NPM_OTP="123456"
+npm run publish:api
+```
+
+```bash
+NPM_OTP=123456 npm run publish:api
+```
+
+Bump `gulp-mu-gulp-api/package.json` before publishing. The task runs the module tests first.
+
 ---
 
 # Deutsch
@@ -199,6 +228,11 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.5
+
+- **Neu** `PlaySound(sample, { loop? })` und `StopSound(sample)` — benannte Samples aus dem Dashboard-µAU-Sound-Atlas; `loop: true` wiederholt bis `StopSound`.
+- **Geändert** npm-README: klarere i18x-Sektion (`Log`/`Warn` vs. `.i18xTrans()` / `.i18xRegister()`).
+
 ### 0.3.3
 
 - **Geändert** npm-README: zentriertes µGulp-Logo und µGulp-ready-Badge (absolute raw-URLs aus dem µGulp-Repo).
@@ -217,7 +251,7 @@ npm install gulp-mu-gulp-api
 ## Verwendung
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -244,7 +278,10 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');
+    PlaySignal('success');              // preset: success | error | attention
+    PlaySound('success');               // named atlas sample
+    PlaySound('engine', { loop: true }); // loop until StopSound('engine')
+    StopSound('engine');
     Speak('Theme build finished.');
 }
 BUILD_THEME.µDisplayName = 'Build Theme<context="µDisplayName"/>'.i18xRegister();
@@ -273,12 +310,16 @@ let values = await RequestForm({
 | :--- | :--- |
 | `IsMicroGulp()` / `IsµGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft |
 | `InstallStringExtensions()` | Installiert µLib-kompatible `String.prototype.i18xTrans()`/`i18xRegister()` (läuft beim Import automatisch) |
-| `Log(text, values?)` / `Warn` / `LogError` | Lokalisierte `console.*`-Ausgabe über i18x (`<context="task log"/>` usw.) |
-| `Translate(text, values?)` | Gibt den übersetzten String zurück, ohne zu loggen |
+| `Log(text, values?)` / `Warn` / `LogError` | Lokalisierte `console.*`-Ausgabe über i18x — bevorzugt für Task-Logs |
+| `Translate(text, values?)` | Low-Level: übersetzter String ohne Log (selten direkt nötig) |
+| `"phrase".i18xTrans(values?)` | Prototype-Kurzform für `Translate` |
+| `"phrase".i18xRegister()` | Metadaten-Text registrieren (gibt die Quellphrase unverändert zurück) |
 | `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?)` | Akustisches Signal im Dashboard: `'success'` \| `'error'` \| `'attention'` (Default) |
+| `PlaySignal(signal?)` | Vorgabe-Signal: `'success'` \| `'error'` \| `'attention'` (Default) |
+| `PlaySound(sample, options?)` | Benanntes Sample aus dem Sound-Atlas; `options.loop` wiederholt bis `StopSound` |
+| `StopSound(sample)` | Stoppt eine Schleife von `PlaySound(sample, { loop: true })` |
 | `Speak(text, options?)` | Sprachausgabe im Dashboard; `options`: `{ rate?, pitch?, volume? }` je Aufruf |
 | `RequestForm(form)` | Komplettes Formular anfordern; löst mit `{ fieldId: value, … }` auf |
 | `RequestTextInput(options)` | Einzelnes Textfeld (mit `validate`-Regeln) |
@@ -339,6 +380,7 @@ Ein Feld-Deskriptor ist `{ id, type, label, default?, options?, validate?, min?,
 | :--- | :--- | :--- |
 | `ReportProgress` | aktualisierende Fortschrittszeile | Log-Zeile je 10-%-Schritt |
 | `PlaySignal` | Terminal-Glocke (`attention`/`error`) | stumm |
+| `PlaySound` / `StopSound` | `[sound]`-Log-Zeile | stumm |
 | `Speak` | `[speech]`-Log-Zeile | `[speech]`-Log-Zeile |
 | Text-/Passwort-/Zahlen-/Range-Eingabe | readline-Prompt (Enter = Default) | Default-Wert |
 | Font-/Select-/Radio-Eingabe | nummerierte Liste + readline | Default-Wert |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.3",
+	"version": "0.3.5",
 	"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.",
 	"type": "module",
 	"main": "src/index.mjs",

package/src/index.mjs

@@ -43,7 +43,10 @@ const pendingUiRequests = new Map();
  * attached dashboard (progress and inputs are rendered in the webview)
  */
 export function IsMicroGulp() {
-	return typeof process.send === 'function' && process.env.MICROGULP === '1';
+	// The worker pool sets MICROGULP=1 for every forked task process. Relying
+	// only on process.send was too strict — some hosts still stream stdout
+	// correctly while structured IPC must be attempted separately.
+	return process.env.MICROGULP === '1';
 }
 
 /** Brand-aligned alias for {@link IsMicroGulp}. */
@@ -108,9 +111,12 @@ export function CreateProgress(_label) {
 	};
 }
 
-// -------------------------------------------------
-// structured log output (table / tree)
-// -------------------------------------------------
+function _SendStructuredLog(_format, _payload) {
+	if (!IsMicroGulp()) return false;
+	if (typeof process.send !== 'function') return false;
+	process.send({ type: 'structured-log', format: _format, payload: _payload });
+	return true;
+}
 
 /**
  * Sends a table to the dashboard log pane. The payload is JSON:
@@ -121,10 +127,7 @@ export function CreateProgress(_label) {
  */
 export function LogTable(_spec) {
 	let payload = _NormalizeTableSpec(_spec);
-	if (IsMicroGulp()) {
-		process.send({ type: 'structured-log', format: 'table', payload });
-		return;
-	}
+	if (_SendStructuredLog('table', payload)) return;
 	console.log(_AsciiTable(payload));
 }
 
@@ -137,10 +140,7 @@ export function LogTable(_spec) {
  */
 export function LogTree(_spec) {
 	let payload = _NormalizeTreeSpec(_spec);
-	if (IsMicroGulp()) {
-		process.send({ type: 'structured-log', format: 'tree', payload });
-		return;
-	}
+	if (_SendStructuredLog('tree', payload)) return;
 	for (let line of _AsciiTreeLines(payload)) console.log(line);
 }
 
@@ -153,10 +153,7 @@ export function LogTree(_spec) {
  */
 export function LogGallery(_spec) {
 	let payload = _NormalizeGallerySpec(_spec);
-	if (IsMicroGulp()) {
-		process.send({ type: 'structured-log', format: 'gallery', payload });
-		return;
-	}
+	if (_SendStructuredLog('gallery', payload)) return;
 	console.log(_AsciiGallery(payload));
 }
 
@@ -231,6 +228,48 @@ export function PlaySignal(_signal = 'attention') {
 	}
 }
 
+/**
+ * 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.
+ *
+ * CLI fallback: logs `[sound] <name>` on a TTY, silent otherwise.
+ *
+ * @param {string} _sample atlas sample name (e.g. `'success'`)
+ * @param {object} [_options]
+ * @param {boolean} [_options.loop] repeat until stopped (default `false`)
+ */
+export function PlaySound(_sample, _options = {}) {
+	let sample = String(_sample ?? '').trim();
+	if (!sample) return;
+	if (IsMicroGulp()) {
+		process.send({ type: 'sound', sample, loop: !!_options.loop });
+		return;
+	}
+	if (process.stdout.isTTY) {
+		console.log(`[sound] ${sample}${_options.loop ? ' (loop)' : ''}`);
+	}
+}
+
+/**
+ * Stops a looping sample started with `PlaySound(name, { loop: true })`.
+ * No-op for one-shot samples and outside µGulp (CLI logs `[sound-stop]` on TTY).
+ *
+ * @param {string} _sample atlas sample name passed to `PlaySound`
+ */
+export function StopSound(_sample) {
+	let sample = String(_sample ?? '').trim();
+	if (!sample) return;
+	if (IsMicroGulp()) {
+		process.send({ type: 'sound-stop', sample });
+		return;
+	}
+	if (process.stdout.isTTY) {
+		console.log(`[sound-stop] ${sample}`);
+	}
+}
+
 /**
  * Speaks a text through the µGulp dashboard speech output (Web Speech API,
  * respects the dashboard speech settings: enabled/volume/rate/pitch).
@@ -520,6 +559,8 @@ export default {
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,
+	PlaySound,
+	StopSound,
 	Speak,
 	RequestForm,
 	RequestTextInput,