µGulp™ (microGulp)

Rock your Gulp!

µGulp™, the interactive near-zero-latency task orchestrator with rich visuals, webview controls, and audio feedback.

Version 0.9.5 · Proprietary License

English · Deutsch · Français · Español · Русский · 日本語 · 한국어

---

English

Rock your Gulp!

µGulp™, the interactive near-zero-latency task orchestrator with rich visuals, webview controls, and audio feedback — shipped as an IDE extension in three editions (VS Code / Cursor registered, VS Code / Cursor Free, JetBrains IDEs) with a Carbon/Neon webview dashboard.

Highlights

µGulp™ ships as µGulp™ (VS Code / Cursor), µGulp™ Free (VS Code / Cursor) and µGulp™ for JetBrains IDEs (IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip and other IntelliJ-based IDEs). The split below is the current plan and may still change before the public marketplace launch. Do not install the registered VS Code extension and µGulp™ Free side by side — they share the same command IDs. The registered VS Code edition must be registered before it will run tasks — or uninstall it and use µGulp™ Free.

	µGulp™ VS Code / Cursor	µGulp™ Free VS Code / Cursor	µGulp™ JetBrains IDEs
Price (month / year)	0 € / $0	0 € / $0	0 € / $0
Task dashboard, preload, i18x, parameters, µWatch, history	yes	yes	yes
License / registration	required	none	none
Skins (Neon Carbon, Ice Light, IDE Dark / Light, Automatic)	yes	IDE Dark / Light from the IDE theme (not selectable)	yes
Custom theme ZIP packs	yes	—	yes
Diagnosis engine	yes	—	yes
Windows UAC elevation	yes	—	yes
Host settings	microgulp.*	microgulp.*	Settings → Tools → µGulp
Marketplace (listing not public yet)	VS Code · Open VSX	VS Code · Open VSX	JetBrains (de.amekudzi.microgulp)

All editions are currently free (0 € / $0 per month and per year). The bullets below describe the full product. Free follows the IDE/OS theme with IDE Dark / IDE Light (no Appearance picker) and omits theme packs, diagnosis and elevation.

The registered VS Code / Cursor edition re-checks the local account against https://microgulp.dev on every 10th host start and at least every 24 hours while the host is running and the server answers. Parallel calls and repeats inside one minute are suppressed. The client distinguishes a valid registration, a confirmed revocation (only a signed grant for this email and license key), and a failed check. Network errors, server outages and unsigned or tampered bodies never revoke. A last-known-valid grant stays usable offline; a 14-day offline window is proposed, but locking new work after that window is not enabled until that behavior is agreed. A confirmed revocation blocks new tasks and watches; running tasks, settings, logs and history stay available. Settings → Check registration re-validates; a later successful registration restores work. µGulp™ Free and the JetBrains edition do not use this check. There is no public lock endpoint and no remote code loading.

• Preloaded workers — warm Node processes with the gulpfile already imported; near-zero click-to-run latency (avoids cold-start scans from AV software)
• Grouped task list with icons and localizable copy — nest tasks with µGroup paths (Build/Production), collapsible groups, µIcon (glyph or image) and µDisplayName / µDescription / µTooltip registered with .i18xRegister() and translated live via i18x-catalog; µOrder sorts tasks and groups
• Parallel task grid — multiple isolated run sectors side by side, each with its own log stream
• Web dashboard — live ANSI-colored logs, filtered output, determinate progress bars, rich forms for user input (text, color, font, select, multiselect, …)
• Live gulpfile watch — workspace watcher rescans on save and swaps stale workers automatically
• No lock-in — µ-prefixed metadata is invisible to the classic gulp CLI and every API helper has a CLI fallback, so the same gulpfile runs unchanged with, without, and after µGulp™ (details)
• i18n-ready gulp tasks — .i18xRegister() registers metadata phrases (embedded context tags on display names, descriptions, tooltips, groups) in the project dictionary and returns the American English source unchanged; the dashboard translates them later via i18x-catalog with placeholders (version, project, …) from µI18xContext. Console output uses .i18xTrans() / Log() for immediate translation, including placeholder resolution
• Dashboard localization — bundled GUI dictionaries for en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, and ko-KR (settings: automatic or fixed locale); more languages planned via i18xe sync. The user handbook ships as a PDF per dashboard language
• Dictionary sync for your gulpfiles — Settings → Project i18x (gulp) scans the sources with the i18xe-sync parser, writes i18x/gulp/<lid>.json for the languages you pick, keeps existing translations and merges the standard formats; a <lid>.status.json sidecar lists what a local AI still has to translate
• Declarative task parameters — µParameters asks once before the run, hands values over as MICROGULP_PARAMS / GetParameters(), remembers the last answers, keeps passwords out of logs, and can hide fields with visibleWhen
• Watch / trigger tasks — µWatch globs run a task on file changes, with debounce, coalescing and a runaway breaker; armed per task from the dashboard
• Task shortcuts — µKeyBinding chords with per-platform variants (ctrl+shift+F1, cmd+shift+Escape), badges and conflict warnings; µGulp: Run Task for IDE-global keybindings
• Structured log output — tasks emit JSON payloads rendered inline in the run log (tables, trees, image galleries, callouts, key/value metrics, status badges, code blocks, inline-SVG bar charts) — Content-Security-Policy safe, no plugin or iframe required; chart width is capped and LogTable headers/rows use skin-tinted colors with hover
• Persistent task history & file logging — every run is written to .microgulp/logs (raw .log + structured .ndjson), a history.ndjson index survives reconnects/IDE restarts; a dashboard history panel opens each transcript (logToFile, logRetention)
• Modal dialogs — ShowModalMessage / ShowConfirmMessage as AiDPix-style glass panels in the dashboard (info/warning/error, Yes/No, OK/Cancel); optional native VS Code/Cursor modals via presentation or microgulp.modalPresentation (gulp-mu-gulp-api); dedicated README section
• Clickable error locations — file:line:column in the run log opens in the host editor (VS Code tab, JetBrains IDE editor)
• Concurrency matrix — per-task exclusive runs and allow/deny rules (µExecutionConcurrency, µExecutionRestrictions)
• Dashboard skins — Neon Carbon, Ice Light, plus plain IDE Dark / IDE Light; Appearance picker with Automatic (follow IDE/OS theme) (Free: IDE Dark / IDE Light from the IDE theme, not selectable)
• Custom theme ZIP packs — install globally (~/.microgulp/themes); packs can include CSS, graphics, fonts and optional sound atlases; import/remove under Settings → Appearance (not in Free)
• Project fonts for icons & logs — RegisterDashboardFont / µDashboardFonts / dashboardFonts for glyph µIcon and run-log typefaces; optional µIconFont per task (gulp-mu-gulp-api 0.3.12)
• Optional acoustic control — completion sounds, error alarms and speech output (dashboard settings)
• Optional form reminder — when a task waits for dashboard input, remind the user after a configurable delay via sound and/or speech; repeats until the form is answered
• Auto-close finished runs — optional countdown in the sector header (click to keep open); a task can override with µAutoClose (-1 keep open, a positive number is seconds, omitted uses Settings → Finished Runs, default 30 s); Restart beside Close
• Windows administrator elevation — optional per-task UAC prompt (µRequiresElevation, µElevationReason); the IDE can run normally while individual tasks (e.g. editing hosts) run elevated (registered VS Code / JetBrains; not in Free)
• Diagnosis engine — import errors and stack traces become actionable suggestions in the dashboard (registered VS Code / JetBrains; not in Free)
• <version/> from the gulpfile — µI18xContext.version is the preferred source for task titles; optional versionSources only fill in when the gulpfile omits version (no overwrite of consumer release configs)
• Reliable LogError vs. Node warnings — LogError / real console.error still fail the run; Node DeprecationWarning and other process warnings do not (failed banner shows the first real error text)
• Legacy prompt bridge — inquirer / gulp-prompt / prompts redirected to dashboard forms without editing gulpfiles
• gulp-mu-gulp-api — npm module for progress, sound, speech, interactive inputs, modal dialogs and dashboard fonts from inside tasks

Snapshot

Hosts	VS Code, Cursor AI, JetBrains IDEs (Settings → Tools → µGulp), any browser on 127.0.0.1 via microgulp-serve --http
Runtime	Node.js 22+ (ESM)
Gulpfiles	Single gulpfile.mjs or regex discovery across the workspace
Config	Extension settings (VS Code/Cursor), Settings → Tools → µGulp (JetBrains), optional microgulp.config.json (team / CLI)
Engine	IDE-independent — same src/engine in every host
Languages	Dashboard GUI: en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR (bundled); gulp output via project i18x/gulp/; handbook PDF per dashboard language
Task order	µOrder (ascending integer); groups by minimum order in subtree; unordered tasks last (alphabetical)

Click a task → a warm worker runs it immediately. Edit the gulpfile → the task list updates on its own. Several tasks can run in parallel; each gets its own dashboard sector with a neon progress bar when the task calls ReportProgress from gulp-mu-gulp-api.

No lock-in: your gulpfile stays a plain gulpfile

Adopting µGulp™ does not make your build depend on µGulp™. A gulpfile prepared for the dashboard still runs under the classic gulp CLI, in CI, and on machines where µGulp™ was never installed — and it keeps running when µGulp™ is uninstalled again.

Backward compatible — everything degrades to plain gulp

What you add	What plain gulp does with it
µDisplayName, µIcon, µGroup, µOrder, µKeyBinding, µWatch, µAutoClose, µRequiresElevation, …	Nothing. They are ordinary properties on the exported function; the gulp CLI addresses tasks by export name and ignores unknown properties. Task names and CLI addressing are untouched — that is exactly why the µ prefix exists
µParameters	Not asked. The task reads GetParameters() / GetParameter(id, fallback), which fall back to the declared defaults, or to MICROGULP_PARAMS / MICROGULP_PARAM_<ID> env vars you can set by hand in a CI job
ReportProgress(...)	Prints a percentage line to stdout (single \r line on a TTY, throttled lines in CI) instead of driving the neon bar
RequestForm, ShowModalMessage, PlaySignal, Speak, LogTable, LogChart, …	Every helper has a CLI fallback: prompts resolve to their defaults, modals print a bracketed line and return ok, sound and speech are no-ops, structured logs render as text
.i18xRegister() / .i18xTrans()	i18xRegister() returns the American English source string unchanged; i18xTrans() falls back to the source text when no dictionary is present. Without µGulp™ you simply get English console output
.microgulp/ (logs, remembered parameters)	Only written when µGulp™ runs the task. It is a disposable cache directory — add it to .gitignore and delete it any time

gulp-mu-gulp-api is a normal npm package with no runtime dependencies, and IsMicroGulp() tells a task whether it is being orchestrated. Removing µGulp™ means uninstalling the extension — no gulpfile edits required.

Forward compatible — new µGulp™ versions do not break old gulpfiles

Metadata is additive and unknown keys are ignored on both sides. A gulpfile written for a newer µGulp™ runs in an older one with the newer features simply unavailable (no shortcut badge, no watch toggle, no parameter form — the task still starts). Unknown structured-log formats are skipped instead of breaking the run, and the host protocol carries a version number so an outdated host can detect a mismatch rather than misinterpret it.

The practical consequence: you can try µGulp™ on a production build script, hand the same repository to a colleague who runs npx gulp BUILD in a terminal, and neither setup notices the other.

Installation

Marketplace pages are reserved but not public yet (the source repository is still private). Until the listings go live, install from the packages in this repo / a GitHub Release.

Edition	Package	Marketplace (planned)
µGulp™ (VS Code / Cursor)	packages/microgulp_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ Free (VS Code / Cursor)	packages/microgulp-free_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ (JetBrains IDEs)	see JetBrains IDEs below	JetBrains Marketplace (plugin id de.amekudzi.microgulp)

Local VSIX install:

code --install-extension packages/microgulp_latest.vsix       # VS Code, registered
cursor --install-extension packages/microgulp_latest.vsix     # Cursor AI, registered
code --install-extension packages/microgulp-free_latest.vsix  # VS Code, Free

• Build from source: npm install, then npm run build — the registered and Free .vsix files land in packages/.

Afterwards run µGulp: Open Dashboard from the command palette (or click the µGulp™ rocket in the status bar).

JetBrains IDEs

The JetBrains plugin is a platform plugin (com.intellij.modules.platform) — it installs in IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip and other IntelliJ-based IDEs. It ships in two packages — pick the one matching your IDE build (Help → About):

IDE build	since-build	Package
2024.2 – 2026.1 (until 261.*)	242	packages/microgulp-jetbrains_latest.zip
2026.2 and newer	262	packages/microgulp-jetbrains-2026.2_latest.zip

Pick the matching zip. IntelliJ IDEA, PhpStorm, WebStorm and the other IntelliJ-based IDEs share these two packages — choose by platform build, not by product name. Each package declares <idea-version since-build="…"/> in the plugin descriptor — the IDE will not load the other one. microgulp-jetbrains is since-build="242" / until-build="261.*" (2024.2–2026.1). microgulp-jetbrains-2026.2 is since-build="262" with no upper bound (2026.2+). Read the platform build under Help → About.

The JetBrains Marketplace listing (plugin id de.amekudzi.microgulp) uses the Latin display name MicroGulp — µ and ™ are not allowed in <name>. The dashboard, tool window, website and this README keep µGulp™. Both zips share that plugin id. plugin.xml versions are derived from the single product version in RELEASES.json as SemVer prereleases (<product>-idea242, <product>-idea262; Marketplace SemVer Only), except product 0.9.3 on the 242–261.* channel which stays at marketplace version 0.9.3 (already submitted). The 262 package for 0.9.3 is 0.9.3-idea262. VS Code / Free keep the unsuffixed product version. Zip names stay *_V<product>.zip. Both JetBrains packages ship the same product changelog. License: https://microgulp.dev/en/license/. The source repository stays private — do not publish a source-code URL on the Marketplace listing.

Build 262 moved JCEF out of the core platform into the bundled Web Browser (JCEF) plugin, so the descriptor has to declare it explicitly — hence the separate package. Install via Settings → Plugins → ⚙ → Install Plugin from Disk… and open the µGulp tool window. Engine options live under Settings → Tools → µGulp (Node path, gulpfile discovery, preload/pool, watch, run logs) — same role as the VS Code microgulp.* settings. Appearance, sound and language stay in the dashboard ⚙ panel. The plugin is a thin JCEF adapter — the entire engine runs in a bundled Node.js sidecar, so Node.js 22+ must be installed (PATH, MICROGULP_NODE, or the Node path setting). If JCEF is unavailable — stripped IDE builds, disabled browser plugin — the tool window still starts the engine and offers a button that opens the dashboard in your regular browser.

Building and checking the packages

npm run jetbrains (alias npm run phpstorm) builds both zips, npm run jetbrains:verify checks them. No Gradle involved:

• Each package is compiled against the oldest IntelliJ platform it supports — the 242 package against a 2024.2 IDE, the 262 package against the installed IDE. javac then rejects an API that only exists in a newer build instead of letting it ship. The adapter uses only platform APIs (tool window, settings, JCEF, editor), so the same zip runs in every IntelliJ-based IDE.
• npm run jetbrains:verify runs the JetBrains Plugin Verifier over both zips, at both ends of their declared range (2024.2 and 2026.1 for the legacy package, 262 for the other one). It reports missing classes and methods, deprecated or internal API, and descriptor defects.
• The Plugin Verifier fat-jar lives in dev/tools/intellij-plugin-verifier/ (verifier-cli-1.410-all.jar; downloaded there from Maven Central if missing). Needed IntelliJ platform distributions are downloaded once into MICROGULP_IDE_CACHE (default %LOCALAPPDATA%\microgulp\ide-cache, ~/.cache/microgulp/ide-cache elsewhere) and reused; the locally installed IDE is used directly when its build matches. MICROGULP_SKIP_IDE_DOWNLOAD=1 keeps offline builds working — they then compile against the installed IDE and skip the missing verification targets.
• One thing the verifier cannot see: it resolves against the whole IDE and ignores the classloader isolation of content modules, so a missing module dependency still reads as compatible. The build therefore refuses to pack a package for build 262+ that touches JCEF without declaring com.intellij.modules.jcef and its two modules.

Known JetBrains / JCEF log noise (harmless)

The first time the µGulp tool window embeds the dashboard, the IDE log may show an error like:

JBCefApp$Holder <clinit> requests ProxyMigrationService instance. Class initialization must not depend on services.

That comes from JetBrains' own JCEF stack (JBCefApp → proxy settings → HttpConfigurable), not from the µGulp plugin. The platform still completes JCEF startup; if the dashboard appears afterwards, you can ignore the entry. It is unrelated to PhpStorm 2025 vs. 2026 — any JetBrains IDE using the same JCEF build can emit it. Only investigate further if the tool window stays blank or shows a real µGulp startup error (Node path, sidecar, gulpfile scan).

The same dashboard also runs in any plain browser: npm run serve -- --cwd <project> --http 9310 --preload, then open http://127.0.0.1:9310/.

Configuration file microgulp.config.json (JetBrains & CLI)

In VS Code / Cursor the engine is configured through the extension settings (microgulp.gulpfilePattern etc.). The JetBrains plugin mirrors those engine options under Settings → Tools → µGulp (passed as sidecar CLI flags on the next tool-window open). Optionally, a project-root microgulp.config.json still supplies team-wide defaults and keys that are not on the IDE page (dashboardFonts, metadataWatchFiles, versionSources). Plain CLI/browser usage via microgulp-serve reads the file when no CLI flag is given:

{
	"gulpfilePattern": "gulpfile.*\\.mjs$",
	"poolSize": 2,
	"maxParallel": 6,
	"preload": true,
	"watchGulpfiles": true
}

Key	Type	Default	Meaning
gulpfile	string	"gulpfile.mjs"	Single gulpfile, relative to the project root
gulpfilePattern	string	—	Case-insensitive regex against workspace-relative POSIX paths; discovers all matching gulpfiles (wins over gulpfile)
poolSize	int ≥ 0	2	Warm workers per gulpfile
maxParallel	int ≥ 1	6	Maximum concurrent task runs
preload	bool	false	Warm up the worker pools right after startup (PhpStorm IDE setting defaults to on; CLI needs --preload)
watchGulpfiles	bool	true	Auto-rescan on gulpfile changes
metadataWatchFiles	string[]	["package.json", "RELEASES.json"]	Optional. Workspace-relative files whose changes trigger a metadata rescan (e.g. after a version bump). Prefer watching the file your gulpfile reads at init.
versionSources	string[] or objects	["package.json"]	Optional. Live JSON fallback for <version/> when the gulpfile does not set µI18xContext.version. Rarely needed for consumer projects — see below.
dashboardFonts	array	—	Optional. Project fonts for task icons / run log (see Dashboard fonts)
logToFile	bool	true	Persist run transcripts (.log + .ndjson) and the task history to disk
logDirectory	string	.microgulp/logs	Directory for transcripts and the history index, relative to the project root
logRetention	int ≥ 0	200	Max runs kept in the history (0 = unlimited); older runs and their log files are pruned

Precedence: command line / JetBrains IDE settings > microgulp.config.json > built-in defaults. Invalid values and unknown keys are ignored with a warning on stderr; the file is versionable and applies to the whole team. After editing IDE settings or the file, reopen the µGulp tool window (respawns the sidecar) or restart microgulp-serve.

In VS Code / Cursor the same keys are available as microgulp.metadataWatchFiles and microgulp.versionSources (non-empty extension settings win over microgulp.config.json). Empty arrays disable metadata watches or live version reads from files.

<version/> in task titles (preferred vs optional)

Preferred (most consumer projects): export µI18xContext from the gulpfile and set version there (read your single release source at module init). Use metadataWatchFiles so changes to that source rescan and refresh warm workers:

export const µI18xContext = { project: 'MyApp', version: _ReadReleaseVersion() };
MAKE_BUILD.µDisplayName = 'Build V<version/><context="µDisplayName"/>'.i18xRegister();

{
	"metadataWatchFiles": ["configs/systemconfig.js"]
}

When µI18xContext.version is set, live versionSources do not override it.

Optional — versionSources: only useful if you do not set µI18xContext.version and want the engine to resolve <version/> from JSON on disk (and refresh it on GetTasksPayload without re-importing the gulpfile). Supported shapes:

• "package.json" — uses the npm "version" field
• "RELEASES.json" — µGulp-style file; see Versioning (RELEASES.json) for the exact schema (releases[0].main / minor / revision)
• { "file": "config/version.json", "field": "version" } — any JSON file + dotted field path

Example (optional live JSON only — no gulpfile version):

{
	"metadataWatchFiles": ["package.json", "RELEASES.json"],
	"versionSources": ["RELEASES.json", "package.json"]
}

Logic: src/engine/ProjectMetadata.mjs; placeholders are built in BuildSourceI18xContext.

Project structure

gulpfile.mjs             Project build: tests, theme CSS (µCSS), package + deploy
RELEASES.json            Version source (main/minor/revision, i18xe-ready info texts)
gulp-mu-gulp-api/        Standalone npm module: public task API
  src/index.mjs          Progress, text/color/font/select inputs, forms
  tests/                 The module's own node:test suite
skins/                   One directory per skin (neon-carbon is the default)
  neon-carbon/
    neon-carbon.µcss.mjs µCSS skin manifest (Carbon/Neon variables)
    neon-carbon.µ.css    Skin source → compiled into src/webview/skins/neon-carbon/
  ice-light/             Light frosted-glass skin (cool blue outward glow)
    ice-light.µcss.mjs   µCSS skin manifest (ice palette)
    ice-light.µ.css      Skin source → compiled into src/webview/skins/ice-light/
  ide-dark/              Plain IDE-aligned dark (VS Code–like, no neon/carbon)
  ide-light/             Plain IDE-aligned light companion
src/
  engine/                IDE-independent core (no VS Code APIs!)
    TaskEngine.mjs       Orchestrator: scan, preload, queue, events
    TaskWorkerPool.mjs   Pool of prewarmed worker processes
    ConcurrencyGuard.mjs Evaluates executionConcurrency/-Restrictions
    Diagnostics.mjs      Diagnosis engine (stack traces → concrete suggestions)
    PluginHost.mjs       Lifecycle hooks for plugins
    GulpfileDiscovery.mjs  Regex-based gulpfile discovery in the workspace
    ReleaseInfo.mjs      Release management: RELEASES.json, version strings, history
  worker/
    TaskWorker.mjs       Child process: imports the gulpfile, runs tasks
  bridge/
    gulp-ugulp-bridge.mjs  Public bridge: npm packages ↔ webview forms
  host/
    HostProtocol.mjs     Event/command names (the single host boundary)
    Daemon.mjs           Engine owner for sidecar hosts
    microgulp-serve.mjs  stdio NDJSON CLI (PhpStorm preparation)
  extension/
    extension.cjs        Thin VS Code / Cursor adapter (the only CJS module)
  webview/
    dashboard.css        Fallback stylesheet for fresh checkouts
    dashboard.js         TaskGrid, log streaming, forms, audio engine
    skins/<name>/dashboard.css  µCSS-generated skins (webview default: neon-carbon)
tests/                   node:test suites (unit + engine integration)
demo/
  gulpfile.mjs           Example gulpfile with every µGulp™ metadata tag
  run-demo.mjs           Headless engine smoke test (no IDE)
dev/
  prompts/               AI migration prompts (existing gulpfile → µGulp + i18x)
    OptimizeGulpfileForMicroGulp.md
    OptimizeGulpfileForMicroGulp.params.example.json

Architecture principles

• The engine layer is IDE-free. src/engine and src/worker know no VS Code APIs. Communication runs through events (engine → host) and plain-JSON commands (host → engine). Porting to PhpStorm (phase 2) is therefore a pure adapter swap — the minimal sidecar npm run serve (src/host/microgulp-serve.mjs, NDJSON on stdio) is already in place.
• Task preloading. The TaskWorkerPool keeps prewarmed Node processes around in which the gulpfile has already been imported. Starting a task hands over a warm worker and refills the pool in the background. After a run the process is discarded (fresh module state).
• Dynamic imports. Heavy npm packages (mssql, docx-templates, makensis, …) must only be loaded inside the task body via await import() — static top-level imports are reserved for the orchestrator core logic.
• Languages. GUI texts are American English and go through String.i18xTrans() (i18xe wiring to follow); code comments English; manuals/documentation German.

Dashboard localization

The dashboard GUI ships with bundled i18x dictionaries for en-US (source), de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, and ko-KR. Choose the language in dashboard settings (automatic follows the host or browser locale). Gulpfile console output uses the same language via MICROGULP_LANG in the worker and your project's i18x/gulp/<lid>.json files. The user handbook ships as a PDF per dashboard language.

To seed or refresh those gulp dictionaries without an i18xe server: Settings → Project i18x (gulp) → Scan & update i18x/gulp…. µGulp™ parses phrases with the i18xe-sync scanner (plus Log/Warn/LogError), keeps existing translations, merges standard format definitions, and writes <lid>.status.json sidecars (missing / orphans) for local AI translation.

Layer	Who provides it	Today	Planned
Dashboard GUI	µGulp (extension)	en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR	More marketplace languages via the i18xe sync pipeline
Gulp tasks & logs	Your project	i18x/gulp/*.json next to the gulpfile	Same — consumer projects never ship i18x/prod
Hyphenation	µGulp webview assets	String.prototype.Hyphenation() with bundled <lid>.hyphen.json where present	Additional locales as hyphen data is synced from i18xe

Context tags, mandatory formats, and the language roadmap: dev/docs/MicroGulpI18xProfile.md. A live i18xe server connection for the dashboard GUI dictionaries remains optional (lane 3); consumer gulp dictionaries use the offline scan above.

Gulpfile discovery (regex-configurable)

µGulp™ notices gulpfile changes on disk by itself: a workspace watcher (microgulp.watchGulpfiles, on by default) rescans automatically after every change and swaps the warm workers for fresh ones running the current code. While a scan runs, the task list shows an animated progress indicator; the dashboard therefore has no rescan button anymore — the µGulp: Rescan Tasks command (command palette) remains as a manual force refresh. If a gulpfile fails to load (syntax error, missing module), a dismissible error banner with diagnosis and stack trace appears right in the dashboard.

µGulp™ finds gulpfiles either through a single path or through a regex pattern that searches the entire workspace:

• microgulp.gulpfilePattern — a JavaScript regex (case-insensitive) tested against the workspace-relative path (POSIX notation with /). When set, every matching file is scanned; tasks are grouped by their source in the dashboard. Example: (^|/)gulpfile\.(m|c)?js$ finds gulpfile.mjs/.js/.cjs at the root and in every subfolder.
• microgulp.gulpfilePath — the classic single path (default gulpfile.mjs). Only used while gulpfilePattern is empty.

node_modules, .git and hidden folders (.*) are never descended into. Every discovered gulpfile gets its own warm worker pool with the gulpfile's folder as working directory, so nested subprojects with relative paths run correctly. The discovery logic lives IDE-independently in src/engine/GulpfileDiscovery.mjs and is therefore available to the CLI and the JetBrains adapter as well.

When more than one gulpfile matches, the left task column shows a source heading per script file (workspace-relative path, e.g. gulpfile.mjs, nested/gulpfile.mjs); tasks from different files are not mixed at the top level. Within each source, tasks still nest by their µGroup path (Build/Production, …). With a single gulpfile, the heading is omitted — only µGroup nesting applies. If scanned gulpfiles export tasks but none import gulp-mu-gulp-api, the dashboard shows a dismissible hint linking to the npm package and the AI migration prompt.

µGulp™ metadata on a Gulp task

The recommended form is µ-prefixed tags in CamelCase (µDisplayName, µIcon, …) — they are invisible to the classic gulp CLI, so gulpfiles stay fully compatible on systems without µGulp™ (the gulp CLI addresses tasks via function.displayName; a pretty name with spaces would break task addressing there):

export async function BUILD_STYLES() { /* ... */ }
BUILD_STYLES.µDisplayName = 'Build Styles';
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.';
BUILD_STYLES.µTooltip = 'Runs the µCSS pipeline (sprites, fonts, sounds included).';
BUILD_STYLES.µIcon = '\u25A3';   // font symbol — or an image data URI:
// BUILD_STYLES.µIcon = 'data:image/svg+xml,%3Csvg ...';  (png/webp too)
BUILD_STYLES.µIconFont = 'ProjectIcons'; // optional — see Dashboard fonts below
BUILD_STYLES.µGroup = 'Build/Assets';                 // nested group (path syntax)
BUILD_STYLES.µOrder = 10;                             // sort position in the dashboard (ascending)
BUILD_STYLES.µExecutionConcurrency = true;            // false = exclusive
BUILD_STYLES.µExecutionRestrictions = { deny: ['CLEAN'] }; // parallel matrix
BUILD_STYLES.µKeyBinding = { key: 'ctrl+shift+B', mac: 'cmd+shift+B' }; // dashboard shortcut
BUILD_STYLES.µWatch = { files: ['skins/**/*.µ.css'] }; // optional file trigger
BUILD_STYLES.µAutoClose = -1;                         // keep the finished sector
BUILD_STYLES.µParameters = [                          // asked before the run
  { id: 'target', type: 'select', options: ['debug', 'release'], default: 'debug' },
];
// Windows only — show the UAC prompt when the host is not already elevated:
BUILD_STYLES.µRequiresElevation = true;
BUILD_STYLES.µElevationReason =
  'Modifies the Windows hosts file.<context="µElevationReason"/>'.i18xRegister();

µGroup assigns the task to a nested group in the task overview. The definition follows a directory-like path syntax: µGroup = 'Build/Production' creates the group Build with subgroup Production. Groups are collapsible in the dashboard; tasks without µGroup stay at the top level. The assignment is optional and purely visual — it has no effect on execution or concurrency.

µOrder sets the sort position in the left column (ascending integer). Sibling tasks and groups are ordered by µOrder; tasks without it appear after all ordered tasks (tie-breaker: display name). Groups sort by the lowest µOrder in their subtree.

Modifier keys on a group header:

Action	Effect
Click	toggle the group
Ctrl+Click (Cmd+Click)	toggle every group on the same level
Alt+Click	toggle all groups

µRequiresElevation marks a task that needs Administrator rights on Windows (for example rewriting C:\Windows\System32\drivers\etc\hosts). When the IDE runs normally, µGulp™ starts a one-shot elevated worker and shows the usual UAC dialog — you do not have to launch Cursor or VS Code as Administrator. If the host process is already elevated, the warm worker pool is used as usual. On non-Windows platforms the flag is ignored. Optional µElevationReason appears in the task tooltip (⛿ badge in the dashboard).

Task shortcuts (µKeyBinding)

A task can carry its own keyboard chord. The chord works while the dashboard has focus — VS Code and PhpStorm cannot register keybindings at runtime, so µGulp™ handles them itself instead of pretending to own IDE-global keys.

BUILD.µKeyBinding = 'ctrl+shift+B';                      // same chord everywhere
DEPLOY.µKeyBinding = { key: 'ctrl+alt+D', mac: 'cmd+alt+D' };
STOP.µKeyBinding = { key: 'ctrl+shift+Escape' };         // named keys: F1…F24, Escape, Tab, Space, arrows, …

Part	Accepted
Modifiers	ctrl, control, alt, option, shift, meta, cmd, command, super, win
Keys	single characters (b, 7, +), F1–F24, Escape/Esc, Enter, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up/Down/Left/Right
Platform keys	key (fallback), mac, win, linux — the matching platform wins, key fills the rest

cmd maps to the Command key on macOS and to Ctrl elsewhere, so a single key chord stays usable on all platforms. The chord appears as a badge next to the task name; if two tasks claim the same chord, both badges turn amber and the tooltip says so (µGulp™ refuses to guess which one you meant).

For a truly IDE-global shortcut, bind the command µGulp: Run Task yourself — it takes the task as an argument:

// keybindings.json (VS Code / Cursor)
{ "key": "ctrl+shift+f9", "command": "microgulp.runTask", "args": { "task": "gulpfile.mjs::BUILD_STYLES" } }

Without args the command opens a quick pick of the scanned tasks.

Declarative task parameters (µParameters)

Instead of asking for input from inside the task body, a task can declare what it needs. µGulp™ shows one form before the run starts, remembers the answers for next time, and hands the values to the task through the environment:

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 = {
  submitLabel: 'Start Deploy<context="button text"/>'.i18xRegister(),
  fields: [
    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging',
      label: 'Target<context="task parameter"/>'.i18xRegister() },
    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
    { id: 'servers', type: 'checkbox', options: ['a', 'b'], required: true }, // submit stays disabled until ≥1
    { id: 'dryRun', type: 'boolean', default: true },
    { id: 'notify', type: 'boolean', default: false,
      visibleWhen: { dryRun: false } },   // only when not a dry run
    { id: 'token', type: 'password' },   // never stored, never logged
  ],
};

A plain array of fields still works. The wrapper adds form chrome (title, submitLabel); µParameterSubmitLabel on the task is an equivalent alternative for the button text.

Field	Meaning
id	required; must be env-var safe ([A-Za-z_][A-Za-z0-9_]*)
type	text (default), textarea, password, number, range, boolean (slide switch), checkbox (multi-select), radio, select, font, color
label, description, placeholder	shown in the form (i18x via .i18xRegister())
default	pre-filled value; a remembered answer from the last run wins
options	['a','b'], [{ value, label, disabled }] or { a: 'Label A' }
required, pattern, minLength, minSelected	validated live in the dashboard — the submit button stays disabled until every visible rule passes (required on a checkbox means at least one option)
min, max, step, rows	numeric / textarea details
remember	false keeps the value out of the store (implicit for password)
visibleWhen	show the field only while other answers match — e.g. { dryRun: false } or { servers: 'prod' } (multi-select: contains). Hidden fields are not validated; missing answers fall back to default
submitLabel / title	form wrapper keys (or µParameterSubmitLabel / µParameterTitle on the task) — i18x via .i18xRegister()

The values arrive as MICROGULP_PARAMS (JSON) plus one flat MICROGULP_PARAM_<ID> per parameter, so shell steps inside a task can read them too. GetParameters() / GetParameter('target', 'staging') from gulp-mu-gulp-api parse them; under the plain gulp CLI you can supply the same variables by hand:

MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY

Answers are remembered per task in .microgulp/parameters.json and pre-fill the next form. Passwords and remember: false values are neither stored nor written to the transcript, the history or the dashboard — they show up as ••••. The run log and the history entry record the values a run started with, so you can see afterwards what was answered. Elevated tasks (µRequiresElevation) cannot show a form from their one-way process, so they run with the remembered values over the declared defaults.

Watch / trigger tasks (µWatch)

A task can run itself whenever the files it cares about change:

BUILD_CSS.µWatch = 'src/**/*.µ.css';                  // shorthand
BUILD_CSS.µWatch = {
  files: ['src/**/*.µ.css', 'skins/*/manifest.json'], // globs, relative to the gulpfile
  ignore: ['**/*.tmp'],
  debounceMs: 300,                                    // quiet time after the last change
  autoStart: false,                                   // arm as soon as the gulpfile is scanned
  parameters: { target: 'debug' },                     // fixed µParameters for triggered runs
};

Watching is opt-in per task: a ◉ toggle appears next to the task name (cyan while armed) unless the declaration says autoStart: true. Globs support **, *, ?, {a,b} and character classes; node_modules, .git, .microgulp, .idea and .vscode are never watched.

Guard rails, because a build task that writes into its own watch set would otherwise spin forever:

• a burst of change events becomes one run (debounce)
• while a run of the task is active, at most one follow-up run is queued
• more than 20 triggered runs within a minute suspend the watcher (amber toggle, the tooltip explains why); toggling it off and on again re-arms it

A triggered run names the file that fired it in its log (Triggered by src/a.css), and it never opens a parameter form — a trigger uses the pinned or remembered values, so nothing waits for a human who is not looking.

Keep a finished run open (µAutoClose)

Finished run sectors close after 30 seconds by default (Settings → Finished Runs). A task can override that:

SHOW_OUTPUT.µAutoClose = -1;   // keep the sector (never auto-close)
QUICK.µAutoClose = 8;          // close after 8 seconds

Value	Meaning
omitted / true	inherit the dashboard setting (default 30 s)
-1, false, 0	do not auto-close this task
positive integer	close after that many seconds (overrides the dashboard delay)

The yellow countdown chip still lets the user keep the sector. µAutoClose is a number or boolean — no .i18xRegister().

Clickable error locations

File references in the run log become links: src/engine/TaskEngine.mjs:412:9, at Object.<anonymous> (gulpfile.mjs:88:15), tsc/eslint output and MSBuild-style file(12,7). Clicking one (or pressing Enter on it) opens that file at that line and column in the host editor — an editor tab in VS Code/Cursor, the IDE editor via the JCEF bridge in PhpStorm.

The path is resolved on the host side against the gulpfile directory of the run first, then the workspace root, so multi-gulpfile workspaces jump to the right copy of an ambiguous name. Only existing files with source-like extensions are opened; URLs, timestamps and version numbers are left alone.

Theme packs (ZIP)

Custom dashboard themes can be distributed as ZIP packs and installed globally (user-wide under ~/.microgulp/themes/, override with MICROGULP_THEMES_DIR). They are independent of the project workspace.

Pack layout (precompiled — no µCSS source required):

manifest.json     // { "id", "displayName", "version", "appearance": "dark"|"light" }
dashboard.css
imgs/…            // optional graphics / cursors
fonts/…           // optional
snds/…            // optional µAU atlas: microgulp.sounds.weba (or .wav/.mp3) + microgulp.sounds.json

In the dashboard: Settings → Appearance → Import theme ZIP…. Built-in skins stay in the picker; Automatic still maps to Neon Carbon / Ice Light. Remove a pack with Remove selected pack.

From this repo you can pack a compiled skin after npm run theme:

node dev/tools/pack-theme.mjs ide-dark
# → packages/microgulp-theme-ide-dark.zip

Sound atlas (µAU)

Dashboard cues are built from dev/media/final/sounds/microgulp/: default/ is the base for every skin; optional <skin-id>/ folders override by filename stem. Atlases ship as WebA (audio-only WebM/Opus, microgulp.sounds.weba). Identical samples are de-duplicated. Full catalog: dev/docs/MicroGulpSoundSchema.md.

PlaySignal('success'|'error'|'attention') maps to taskSuccess / taskFailed / requestAlert; PlaySound uses the schema names directly.

Dashboard fonts (task icons & run log)

Project fonts are independent of the built-in skins. Register them in the gulpfile (preferred) or via microgulp.config.json / the microgulp.dashboardFonts setting:

import { RegisterDashboardFont } from 'gulp-mu-gulp-api';

RegisterDashboardFont({
  id: 'ProjectIcons',
  file: 'assets/task-icons.woff2',   // relative to the gulpfile directory
  usage: 'task-icons',               // or 'log' / 'all'
});

// Or declarative:
export const µDashboardFonts = [
  { id: 'ProjectLog', file: 'assets/log.woff2', usage: 'log' },
];

BUILD.µIcon = '\uE101';
BUILD.µIconFont = 'ProjectIcons';     // optional when a single task-icons font is registered

usage: 'task-icons' styles glyph µIcon entries (first registered font is the default; µIconFont overrides per task). usage: 'log' sets the run-sector log typeface. Files must stay under the workspace (woff2 / woff / ttf / otf).

Per-property fallback cascade: µDisplayName → ugulp.displayName (namespace object) → displayName (Gulp's own field) → export name. executionRestrictions supports deny (always wins) and allow (whitelist: everything unlisted is forbidden).

Task metadata strings use i18x with the context tag inside the phrase. .i18xRegister() only registers the phrase for i18xe-sync and the project dictionary — it returns the source text unchanged; translation happens later when the dashboard renders metadata (TransProperty() via i18x-catalog), with placeholders such as <version/> filled from µI18xContext. For console output, use .i18xTrans() or Log()/Warn()/LogError(), which translate immediately at runtime (including placeholders):

BUILD_STYLES.µDisplayName = 'Build Styles<context="µDisplayName"/>'.i18xRegister();
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();

Context tags, mandatory formats, and the marketplace language plan: dev/docs/MicroGulpI18xProfile.md.

AI-assisted gulpfile migration

To migrate an existing large gulpfile (console output, task metadata, i18x/gulp dictionaries, optional µKeyBinding / µParameters / µWatch / µAutoClose) use the maintained prompt in the repository:

File	Purpose
dev/prompts/OptimizeGulpfileForMicroGulp.md	Copy-paste prompt for Cursor, Claude, ChatGPT, …
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json	Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version)

Workflow

1. Copy the params example to your project root as microgulp-optimize.params.json and fill in projectRoot, gulpfilePath, supportedLanguages (e.g. en-US, de-DE, zh-CN), gulpMuGulpApiVersion (^0.4.0 or newer), microGulpMinVersion (0.7.0), and githubRepoUrl / githubRef (default: https://github.com/mamekudz/microGulp, V0.7.0 or main).
2. Open the prompt markdown, replace the {{PLACEHOLDER}} table with your values (or attach the params file and gulpfile in Cursor).
3. Let the AI run the migration. Step 0 in the prompt is mandatory: a timestamped backup of the gulpfile (e.g. gulpfile.mjs.20260703-142559.bak) before any edit.
4. Verify with node --check gulpfile.mjs, test tasks in the µGulp dashboard (including any new shortcuts while the dashboard has focus), then commit gulpfile.mjs, i18x/gulp/*.json, and package.json.

Consumer projects need only i18x/gulp/<lid>.json — no i18x/prod. The prompt is updated with µGulp releases; check this repo for the latest version before migrating. It covers i18x rules (register vs. translate, no µMeta) and declarative UX: dashboard µKeyBinding (not IDE-global unless the user binds microgulp.runTask), µParameters / GetParameters(), µWatch, and µAutoClose.

Public task API (gulp-mu-gulp-api)

Third-party gulpfiles and npm packages inside the stream use the extended dashboard features through the standalone npm module **gulp-mu-gulp-api** (lives as its own project under gulp-mu-gulp-api/, published to npm separately):

import { ReportProgress, RequestTextInput, RequestColorInput, RequestForm, ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

export async function BUILD_THEME() {
    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
    let title = await RequestTextInput({ label: 'Product title', validate: { required: true, minLength: 3 } });
    let ok = await ShowConfirmMessage({
        title: 'Overwrite theme?',
        message: 'Existing skin files will be replaced.',
        presentation: 'webview',
    });
    if (ok.button !== 'yes') return;
    for (let step = 1; step <= 10; step++) {
        // ... work ...
        ReportProgress(step / 10, 'compiling theme');   // determinate neon progress bar in the sector
    }
    await ShowModalMessage({
        variant: 'info',
        title: 'Theme ready',
        message: 'Skin files written.',
    });
}

The module is dependency-free and talks to the engine directly over the µGulp™ worker's IPC channel (detection via IsMicroGulp() / IsµGulp()). Without µGulp™ everything degrades cleanly: progress goes to the terminal, inputs via readline (TTY) or default values (CI). Details in gulp-mu-gulp-api/README.md. The internal module src/bridge/gulp-ugulp-bridge.mjs remains as the low-level transport; new consumers should use gulp-mu-gulp-api.

Modal dialogs (ShowModalMessage)

Since V0.5.29 (API: gulp-mu-gulp-api 0.3.11+), tasks can show blocking modal dialogs — for acknowledgments, warnings before continuing, or Yes/No and OK/Cancel confirmations. Use them sparingly (not for routine log lines); prefer Log() / structured log helpers for normal output.

Webview glass panels (default)

When presentation is webview (the default), modals render inside the µGulp dashboard as AiDPix/Oxyd-style glass panels:

Feature	Detail
Frame	9-slice glasspanel.png (glasspanel-ice.png in the ice-light skin)
Variants	info (turquoise header), warning, error — colored header bar per variant
Buttons	Carbon-styled actions; primary button highlighted
Overlay	Scroll the mouse wheel over the dimmed backdrop to adjust overlay brightness (8–88 %); long message bodies scroll inside the panel
Keyboard	Escape → cancel/no (or first button); Enter → primary button

Implementation: src/webview/WebviewModal.js, src/webview/webview-modal.css (loaded by the VS Code webview and the HTTP dashboard).

API

import { ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

// Single acknowledgment (default button: OK)
await ShowModalMessage({
    variant: 'warning',          // 'info' | 'warning' | 'error'
    title: 'Disk almost full',
    message: 'Less than 1 GB free on the build drive.',
    presentation: 'webview',     // optional — see below
});

// Yes/No confirmation (default style)
let answer = await ShowConfirmMessage({
    title: 'Overwrite output?',
    message: 'Existing files in dist/ will be replaced.',
});
if (answer.button !== 'yes') return;

// OK/Cancel preset
let discard = await ShowConfirmMessage({
    title: 'Discard changes?',
    message: 'Unsaved theme tweaks will be lost.',
    style: 'ok-cancel',          // default: 'yes-no'
});

Both helpers return Promise<{ button: string }> — e.g. 'ok', 'yes', 'no', 'cancel', or custom button ids from ShowModalMessage({ buttons: [{ id: 'retry', label: 'Retry', primary: true }] }).

CLI fallback (plain gulp, CI, no TTY): bracketed console output and the primary/default button — no blocking prompt.

Where the modal appears (presentation)

Value	Behavior
webview	In-dashboard glass panel (default)
ide	Native VS Code / Cursor modal (showInformationMessage / showWarningMessage / showErrorMessage with { modal: true })
auto	Native IDE dialog when the Extension Host is available; otherwise the webview glass panel

Per-call presentation overrides the host default.

Host defaults

Host	Setting
VS Code / Cursor	Extension setting microgulp.modalPresentation (webview | ide | auto, default webview)
Browser demo / PhpStorm JCEF	Dashboard Settings → Modal presentation (same three values)

Fallback: PhpStorm and a browser dashboard always use the webview glass panel — presentation: 'ide' is mapped to webview there. Only the VS Code/Cursor Extension Host can show native IDE modals.

Try the demos

After µGulp: Open Sample Project, the dashboard lists a Demo group:

Task	Effect
DEMO_MODAL_DIALOGS	All variants + Yes/No + OK/Cancel with presentation: 'webview'
DEMO_IDE_MODAL_DIALOGS	Same flow with presentation: 'ide' (native modals in Cursor/VS Code; webview fallback in PhpStorm / the browser)

Further API details: gulp-mu-gulp-api/README.md.

µGulp ready certification

npm modules whose root gulpfile is fully integrated with the µGulp dashboard may display the µGulp ready badge on their npm README and project pages.

Requirement	Detail
Gulpfile	Exported tasks carry µGulp metadata (µDisplayName, µDescription, µGroup, …)
API	Uses gulp-mu-gulp-api for logging, progress and optional dashboard features
CLI fallback	Tasks remain runnable with plain gulp / npx gulp when µGulp is not installed
Badge asset	Canonical PNG: media/microgulp-ready.png in the µGulp repo. npm README: absolute raw URL (npm rewrites relative paths to microCSS/HEAD/... even inside HTML). Example: <a href="https://microgulp.dev"><img src="https://microgulp.dev/assets/media/microgulp-ready.png" alt="µGulp ready" width="150"></a>
package.json	Optional "microgulp": { "ready": true, "certifiedSince": "<semver>" } for machine-readable discovery

Certified modules

npm package	Since	Notes
gulp-mu-gulp-api	0.3.11	Official task API — Log, ReportProgress, i18x console layer, dashboard forms, ShowModalMessage / ShowConfirmMessage; npm README badge since 0.3.3
gulp-mu-css (µCSS™)	2.5.15	Monorepo root gulpfile.mjs with full task metadata, i18x/gulp/ (en-US, de-DE) and LogBuildDebugReport on demo builds; npm README badge via absolute raw URL since 2.5.14
gulp-mu-ps (µPS)	1.3.5	Test/render tasks in the shared root gulpfile (TEST_MICROPS, RENDER_EXAMPLES, …)
gulp-mu-ft (µFT)	0.1.5	Test task TEST_MICROFT in the shared root gulpfile
gulp-mu-au (µAU)	0.1.6	Test task TEST_MICROAU in the shared root gulpfile

To apply for certification, migrate your gulpfile with dev/prompts/OptimizeGulpfileForMicroGulp.md and open an issue or PR in the µGulp or module repository.

Versioning (RELEASES.json)

This file is µGulp’s own release format — the single source of truth for this repository. Consumer projects do not need a RELEASES.json; they typically keep their product version in their own config (and expose it via µI18xContext.version). Optional versionSources: ["RELEASES.json"] only helps if you adopt this same JSON layout.

Every release entry carries main/minor/revision, a timestamp, a beta flag and a list of info texts. The info texts carry the i18x context tag <context="release info"/> and are registered via String.i18xRegister(), so the i18xe engine can translate them automatically.

Schema (newest release first — releases[0] is current):

{
    "releases": [
        {
            "main": 0, "minor": 2, "revision": 0, "date": "2026-07-02 15:30", "beta": false,
            "info": [ "Release management added<context=\"release info\"/>" ]
        }
    ]
}

When versionSources includes "RELEASES.json", the engine resolves <version/> to "main.minor.revision" from releases[0] (e.g. "0.2.0").

The module src/engine/ReleaseInfo.mjs provides:

• GetVersionString() / GetFullVersionString() — "0.2.0" or "0.1.4ß" (ß suffix for beta builds).
• GetVersionHistoryText({ maxReleases, includeBeta }) — the complete history as a formatted string for the console (task SHOW_VERSION_HISTORY or npm run history).
• BUILD_PACKAGE syncs the package.json version and the version line at the top of this README from RELEASES.json automatically and stamps it into the artifact name (microgulp_V0.2.0.vsix, betas with a _beta suffix). A new release only needs a new entry at the top of RELEASES.json.

Project build (gulpfile.mjs)

The project builds itself through its own gulpfile (dogfooding: it runs in the µGulp™ dashboard, through the gulp CLI, through classic Gulp IDE extensions and headless):

Invocation	Task	Purpose
npm test	RUN_TESTS	node:test suites in tests/ (unit + engine integration with real worker processes)
npm run theme	CREATE_THEME_DATA	Compiles every skins/<name>/<name>.µ.css via µCSS (gulp-mu-css BuildSkin) into src/webview/skins/<name>/dashboard.css (default: neon-carbon)
npm run package	BUILD_PACKAGE	Stages the extension into tmp/package/ and creates the .vsix in packages/ (also refreshed as microgulp_latest.vsix)
npm run deploy	DEPLOY_EXTENSION	Automated update cycle: build the .vsix and install it via cursor --install-extension (reload the window afterwards)
npm run build	BUILD_ALL	Full pipeline: clean → tests → theme → package
npm run history	SHOW_VERSION_HISTORY	Prints the formatted version history from RELEASES.json to the console
npm run accounts	ACCOUNTS	Read-only listing of production LICENSE_KV registrations (--status, --edition; token from CLOUDFLARE_API_TOKEN or website/.env)
npm run website	BUILD_WEBSITE	Turns README language sections into website/ (all languages selectable; / follows the browser language)
npm run website:deploy	DEPLOY_WEBSITE	Builds, tests and publishes website/ to Cloudflare Worker microgulp-web (microgulp.dev; local Wrangler login)
npm run backup	BACKUP_TO_NAS	Incremental robocopy mirror to Z:\\Projects\\microGulp (override with MICROGULP_NAS_BACKUP)
—	PUBLISH_API	Publishes gulp-mu-gulp-api to npm (runs its tests first; npm login required)
—	CLEAN	Removes tmp/ and packages/ (exclusive, write lock)

Notes:

• gulp-mu-css is wired in as a local file: dependency on C:\Projects\microCSS\gulp-mu-css and — like every heavy package — is only loaded inside the task body via await import().
• BUILD_PACKAGE produces a real .vsix once @vscode/vsce is installed (npm i -D @vscode/vsce); without vsce the task falls back to a zip of the staging folder.
• Skins are self-contained: one directory per skin under skins/ (e.g. skins/neon-carbon/, skins/ice-light/, skins/ide-dark/), each with a <name>.µcss.mjs manifest and a same-named <name>.µ.css source. CREATE_THEME_DATA discovers and builds every skin; neon-carbon (dark) is the default and ice-light ships a bright frosted-glass companion. ide-dark / ide-light are plain VS Code–like surfaces without carbon weave or neon pulse. Additional/user skins can be dropped in as sibling directories. The dashboard skin picker (Settings → Appearance) offers an Automatic mode that follows the IDE/OS light or dark theme (maps to ice-light / neon-carbon).
• The webview automatically prefers the generated default skin (src/webview/skins/neon-carbon/dashboard.css); the hand-written dashboard.css remains as a fallback for fresh checkouts.
• The dashboard header shows the yellow microscope mark (baselogo.svg) via µCSS data-URI inlining next to the neon µGulp™ title (background-image: µ(DataUri("imgs/baselogo.svg"))). The single source of truth for finished art assets is dev/media/final/; the build syncs media/logo.png (extension icon), media/logo_readme.png (README), src/webview/skins/<name>/imgs/baselogo.svg (dashboard) and jetbrains/resources/icons/baseoutlinelogo.svg (JetBrains tool window + plugin list) from there.

This repository also ships demo/gulpfile.mjs for local development:

npm run demo          # headless engine smoke test
npm run demo:web      # browser dashboard (microgulp-serve --http)
npm run demo:ide      # Extension Development Host with demo/ as the workspace

F5 in VS Code/Cursor (launch configuration "Run µGulp Extension") opens the same demo workspace.

Try it

Installed extension: Command Palette → µGulp: Open Sample Project (JetBrains: Tools → µGulp: Open Sample Project). That copies a sample gulpfile with Demo and Build tasks (progress, forms, structured logs, sounds, modals) to ~/.microgulp/sample and opens it. Then µGulp: Open Dashboard. The user handbook is Settings → Handbook (or µGulp: Open Handbook); every dashboard language is listed there.

Handbook PDFs: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어

License

µGulp™ (extension, engine, dashboard, JetBrains adapter) is proprietary software — see LICENSE. You may use the distributed binaries free of charge; copying, modifying, or redistributing the source code is not permitted.

The companion npm package gulp-mu-gulp-api remains under the MIT License so Gulp tasks can adopt it without restrictions.

Roadmap / open points of this draft

Shipped in V0.5.0

• [x] i18x layer in the webview: language setting (automatic/en-US/de-DE/zh-CN), context-tagged GUI strings, format definitions taken over from the i18xe server — the direct i18xe-server connection follows later
• [x] µ-task metadata: .i18xRegister() registers phrases for i18xe/dashboard; translation and placeholders at dashboard render time via i18x-catalog + µI18xContext; console via .i18xTrans() / Log()
• [x] Public task API **gulp-mu-gulp-api** on npm (progress, sound/speech, interactive forms with CLI fallbacks; IsMicroGulp, InstallStringExtensions)
• [x] Legacy prompt libraries (inquirer, gulp-prompt, prompts) redirected to dashboard forms without editing gulpfiles
• [x] Extended dashboard form controls (radio, range, textarea, password, number, date/time, file, multi-select checkbox)
• [x] Dashboard settings (acoustic control, speech output, form reminder, error handling, language)
• [x] Console rendering in task sectors (ANSI colors, \r progress-line overwrite, timestamps)
• [x] Persistent task history & log redirection to files (raw .log + structured .ndjson, history.ndjson index, retention, dashboard history panel)
• [x] microgulp.config.json for team/CLI defaults (PhpStorm IDE settings + VS Code extension settings take precedence when set)
• [x] Dashboard task sort order via µOrder (ascending; groups by subtree minimum)
• [x] Phase 2: JetBrains adapter — JCEF tool window + Node sidecar + HTTP/SSE dashboard + Settings → Tools → µGulp (all IntelliJ-based IDEs)
• [x] Optional per-task Windows UAC elevation (µRequiresElevation, µElevationReason) — IDE stays non-admin
• [x] Dashboard localization documented: bundled en-US / de-DE / zh-CN; consumer projects supply i18x/gulp only
• [x] Multi-skin dashboard (Neon Carbon, Ice Light, IDE Dark/Light) + global theme ZIP packs (Appearance import; optional sounds/graphics)
• [x] Per-theme µAU sound atlases (default/ + skin overrides, PCM dedupe); catalog in dev/docs/MicroGulpSoundSchema.md
• [x] Project fonts for task icons / run log (RegisterDashboardFont, µIconFont, dashboardFonts; gulp-mu-gulp-api 0.3.12)
• [x] Task shortcuts (µKeyBinding, per-platform chords, conflict badge) + µGulp: Run Task for IDE-global keybindings
• [x] Declarative task parameters (µParameters, GetParameters(), remembered answers, redacted secrets)
• [x] Watch / trigger tasks (µWatch globs, debounce, runaway breaker, dashboard toggle)
• [x] Per-task auto-close override (µAutoClose: -1 keep open, positive seconds, omitted uses Settings)
• [x] Clickable error locations in the run log (VS Code editor tab, PhpStorm JCEF bridge)
• [x] CI matrix over Windows / Linux / macOS on Node 22 and 24
• [x] Offline i18x/gulp dictionary sync in the dashboard (i18xe-sync parser, target-language dialog, standard formats, <lid>.status.json for AI translation)

Still open

• [ ] Document µLib (microLib), then adopt it as the utility layer in µGulp (i18x today is a local webview subset)
• [ ] Direct i18xe-server connection: live translation sync instead of the bundled de-DE/zh-CN dictionaries
• [ ] Extend µLib's GUI.mjs with additional special controls for the dashboard forms
• [ ] Visual polish of the webview dashboard
• [ ] Extend the µCSS skin: add the symbol font and sprites to the manifest
• [ ] Speech output via i18xe (atlas samples already replace WebAudio beeps when present)
• [x] JetBrains plugin: Settings → Tools → µGulp (engine options)
• [ ] JetBrains Marketplace distribution (deferred — local ZIP install only for now)
• [ ] Publish the VS Code/Cursor extension to a marketplace (deferred — ship via GitHub Releases / packages/*_latest.* for now)

---

Deutsch

Rock your Gulp!

µGulp™ — der interaktive Task-Orchestrator mit nahezu null Latenz, stylischer Dashboard-Ausgabe, Webview-Steuerung und akustischem Feedback — als IDE-Erweiterung in drei Editionen (VS Code / Cursor registriert, VS Code / Cursor Free, JetBrains-IDEs) mit einem Carbon/Neon-Webview-Dashboard.

Highlights

µGulp™ gibt es als µGulp™ (VS Code / Cursor), µGulp™ Free (VS Code / Cursor) und µGulp™ für JetBrains-IDEs (IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip und andere IntelliJ-basierte IDEs). Die Aufteilung unten ist der aktuelle Stand und kann sich vor dem Marketplace-Start noch ändern. Die registrierte VS-Code-Erweiterung und µGulp™ Free nicht nebeneinander installieren — dieselben Kommando-IDs. Die registrierte VS-Code-Edition muss vor dem ersten Task registriert werden — sonst deinstallieren und µGulp™ Free nutzen.

	µGulp™ VS Code / Cursor	µGulp™ Free VS Code / Cursor	µGulp™ JetBrains-IDEs
Preis (Monat / Jahr)	0 € / $0	0 € / $0	0 € / $0
Task-Dashboard, Preload, i18x, Parameter, µWatch, Historie	ja	ja	ja
Lizenz / Registrierung	Pflicht	keine	keine
Skins (Neon Carbon, Ice Light, IDE Dunkel / Hell, Automatik)	ja	IDE Dunkel / Hell nach IDE-Theme (nicht wählbar)	ja
Eigene Theme-ZIP-Packs	ja	—	ja
Diagnose-Engine	ja	—	ja
Windows-UAC-Elevation	ja	—	ja
Host-Einstellungen	microgulp.*	microgulp.*	Settings → Tools → µGulp
Marketplace (Eintrag noch nicht öffentlich)	VS Code · Open VSX	VS Code · Open VSX	JetBrains (de.amekudzi.microgulp)

Alle Editionen sind derzeit kostenlos (0 € / $0 pro Monat und pro Jahr). Die Stichpunkte darunter beschreiben das volle Produkt. Free folgt dem IDE-/OS-Theme mit IDE Dunkel / IDE Hell (kein Appearance-Picker) und lässt Theme-Packs, Diagnose und Elevation weg.

Die registrierte VS-Code-/Cursor-Edition prüft das lokale Konto gegen https://microgulp.dev bei jedem zehnten Host-Start und spätestens alle 24 Stunden, solange die Erweiterung läuft und der Server antwortet. Parallele Anfragen und Wiederholungen innerhalb einer Minute unterbleiben. Der Client unterscheidet gültig, bestätigter Widerruf (nur eine signierte Freigabe für diese E-Mail und diesen Lizenzschlüssel) und fehlgeschlagene Prüfung. Netzwerkfehler, Serverausfälle sowie unsignierte oder veränderte Antworten gelten nie als Widerruf. Eine zuletzt gültige Freigabe bleibt offline nutzbar; vorgeschlagen ist eine 14-Tage-Frist — das Sperren neuer Arbeit nach Ablauf ist noch nicht aktiv, bis dieses Verhalten abgestimmt ist. Ein bestätigter Widerruf verhindert neue Tasks und Watches; laufende Tasks, Einstellungen, Logs und Historie bleiben. Einstellungen → Registrierung prüfen fordert eine erneute Prüfung; eine spätere erfolgreiche Registrierung schaltet wieder frei. µGulp™ Free und die JetBrains-Ausgabe nutzen diese Prüfung nicht. Es gibt keinen öffentlichen Sperrendpunkt und kein Nachladen von Code.

• Preload von Tasks — warme Node-Worker mit bereits importiertem Gulpfile; nahezu kein Kaltstart beim Klick (umgeht Echtzeit-Virenscanner-Latenzen)
• Strukturierte Task-Gruppen mit Icons und lokalisierbaren Texten — Tasks per µGroup-Pfad verschachteln (Build/Production), einklappbare Gruppen, µIcon (Glyph oder Bild) sowie µDisplayName / µDescription / µTooltip per .i18xRegister() und Live-Übersetzung über i18x-catalog; µOrder sortiert Tasks und Gruppen
• Paralleles Task-Grid — mehrere isolierte Lauf-Sektoren nebeneinander, jeweils mit eigenem Log-Stream
• Web-basierte Ausgabe und Formulare — Live-Logs mit ANSI-Farben, Filter, determinierte Progressbars, Formulare für Benutzereingaben (Text, Farbe, Schrift, Auswahl, Mehrfachauswahl, …)
• Watch für die Task-Übersicht — Workspace-Watcher scannt bei Speichern neu und tauscht veraltete Worker aus
• Keine Abhängigkeit — µ-Metadaten sind für die klassische gulp-CLI unsichtbar und jeder API-Helfer hat einen CLI-Fallback: dasselbe Gulpfile läuft unverändert mit, ohne und nach µGulp™ (Details)
• Automatisch internationalisierbare Gulp-Tasks — .i18xRegister() registriert Metadaten-Phrasen (eingebettete Kontext-Tags an Anzeigenamen, Beschreibungen, Tooltips, Gruppen) im Projekt-Wörterbuch und gibt den amerikanischen Quelltext unverändert zurück; das Dashboard übersetzt sie später über i18x-catalog mit Platzhaltern (version, project, …) aus µI18xContext. Konsolenausgabe nutzt .i18xTrans() / Log() für sofortige Übersetzung inkl. Platzhalter-Auflösung
• Dashboard-Lokalisierung — gebündelte GUI-Wörterbücher für en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP und ko-KR (Einstellungen: automatisch oder feste Locale); weitere Sprachen geplant über i18xe-Sync. Das Benutzerhandbuch liegt als PDF je Dashboard-Sprache vor
• Wörterbuch-Sync für eigene Gulpfiles — Einstellungen → Projekt-i18x (gulp) scannt die Quellen mit dem i18xe-sync-Parser, schreibt i18x/gulp/<lid>.json für die gewählten Sprachen, behält bestehende Übersetzungen und mergt die Standard-Formate; eine <lid>.status.json listet, was eine lokale KI noch übersetzen muss
• Deklarative Task-Parameter — µParameters fragt einmal vor dem Lauf, übergibt die Werte als MICROGULP_PARAMS / GetParameters(), merkt die letzten Antworten, hält Passwörter aus Logs heraus und kann Felder per visibleWhen ausblenden
• Watch-/Trigger-Tasks — µWatch-Globs starten den Task bei Dateiänderungen, mit Debounce, Zusammenfassen und Runaway-Bremse; pro Task im Dashboard scharfschalten
• Task-Tastenkürzel — µKeyBinding mit plattformspezifischen Varianten (ctrl+shift+F1, cmd+shift+Escape), Badge und Kollisionswarnung; µGulp: Run Task für IDE-globale Kürzel
• Strukturierte Log-Ausgabe — Tasks senden JSON-Payloads, die inline im Run-Log gerendert werden (Tabellen, Bäume, Bildgalerien, Callouts, Key/Value-Metriken, Status-Badges, Codeblöcke, Inline-SVG-Balkendiagramme) — Content-Security-Policy-sicher, ohne Plugin oder iframe; Chart-Breite begrenzt, LogTable-Header/Zeilen mit Skin-Tint und Hover
• Persistente Task-Historie & Log-Umlenkung in Dateien — jeder Run wird nach .microgulp/logs geschrieben (roh .log + strukturiert .ndjson), ein history.ndjson-Index übersteht Reconnects/IDE-Neustarts; ein Historie-Panel im Dashboard öffnet jedes Transkript (logToFile, logRetention)
• Modal-Dialoge — ShowModalMessage / ShowConfirmMessage als AiDPix-Glaspanels im Dashboard (Info/Warnung/Fehler, Ja/Nein, OK/Abbrechen); optional native VS-Code-/Cursor-Modals über presentation oder microgulp.modalPresentation (gulp-mu-gulp-api); eigener README-Abschnitt
• Klickbare Fehlerstellen — datei:zeile:spalte im Run-Log öffnet die Stelle im Editor der IDE (VS-Code-Tab, JetBrains-Editor)
• Concurrency-Matrix — exklusive Tasks und Allow/Deny-Regeln (µExecutionConcurrency, µExecutionRestrictions)
• Dashboard-Skins — Neon Carbon, Ice Light sowie schlicht IDE Dunkel / IDE Hell; Appearance-Picker mit Automatik (folgt IDE-/OS-Theme) (Free: IDE Dunkel / IDE Hell nach IDE-Theme, nicht wählbar)
• Eigene Theme-ZIP-Packs — global installierbar (~/.microgulp/themes); Packs können CSS, Grafiken, Fonts und optionale Sound-Atlanten enthalten; Import/Entfernen unter Einstellungen → Erscheinungsbild (nicht in Free)
• Projekt-Fonts für Icons & Logs — RegisterDashboardFont / µDashboardFonts / dashboardFonts für Glyph-µIcon und Run-Log-Schrift; optional µIconFont pro Task (gulp-mu-gulp-api 0.3.12)
• Optionale akustische Kontrolle — Ende-Sounds, Fehleralarm und Sprachausgabe (Dashboard-Einstellungen)
• Optionale Formular-Erinnerung — wenn ein Task auf eine Dashboard-Eingabe wartet, nach einstellbarer Verzögerung per Sound und/oder Sprache erinnern; wiederholt bis das Formular beantwortet ist
• Auto-Schließen abgeschlossener Läufe — optionaler Countdown im Sektor-Header (Klick zum Behalten); ein Task überschreibt das mit µAutoClose (-1 offen halten, positive Zahl = Sekunden, weggelassen nutzt Einstellungen → Abgeschlossene Läufe, Standard 30 s); Neu starten neben Schließen
• Windows-Administrator-Elevation — optionaler UAC-Dialog pro Task (µRequiresElevation, µElevationReason); die IDE kann normal laufen, während einzelne Tasks (z. B. hosts-Datei) elevated starten (registriertes VS Code / JetBrains; nicht in Free)
• Diagnose-Engine — Importfehler und Stack-Traces werden zu konkreten Lösungsvorschlägen im Dashboard (registriertes VS Code / JetBrains; nicht in Free)
• <version/> aus dem Gulpfile — µI18xContext.version ist die bevorzugte Quelle für Task-Titel; optionales versionSources greift nur, wenn das Gulpfile keine version setzt (kein Überschreiben der Verbraucher-Release-Config)
• Zuverlässiges LogError vs. Node-Warnings — LogError / echte console.error-Aufrufe lassen den Run fehlschlagen; Node-DeprecationWarning und andere Prozess-Warnings nicht (Failed-Banner zeigt den ersten echten Fehlertext)
• Legacy-Prompt-Brücke — inquirer / gulp-prompt / prompts auf Dashboard-Formulare umgeleitet, ohne Gulpfile-Anpassung
• gulp-mu-gulp-api — npm-Modul für Fortschritt, Sound, Sprache, interaktive Eingaben, Modal-Dialoge und Dashboard-Fonts aus Tasks heraus

Snapshot

Hosts	VS Code, Cursor AI, JetBrains-IDEs (Settings → Tools → µGulp), jeder Browser auf 127.0.0.1 via microgulp-serve --http
Laufzeit	Node.js 22+ (ESM)
Gulpfiles	Einzelnes gulpfile.mjs oder Regex-Discovery im Workspace
Konfiguration	Erweiterungseinstellungen (VS Code/Cursor), Settings → Tools → µGulp (JetBrains), optional microgulp.config.json (Team / CLI)
Engine	IDE-unabhängig — dieselbe src/engine in jedem Host
Sprachen	Dashboard-GUI: en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR (gebündelt); Gulp-Ausgabe über Projekt-i18x/gulp/; Handbuch als PDF in derselben Sprache
Task-Reihenfolge	µOrder (aufsteigende Ganzzahl); Gruppen nach kleinstem Order-Wert im Unterbaum; Tasks ohne Order zuletzt (alphabetisch)

Klick auf einen Task → warmer Worker startet sofort. Gulpfile speichern → Task-Liste aktualisiert sich von selbst. Mehrere Tasks parallel; jeder bekommt eine eigene Dashboard-Sektion mit Neon-Progressbar, sobald der Task ReportProgress aus gulp-mu-gulp-api meldet.

Keine Abhängigkeit: das Gulpfile bleibt ein normales Gulpfile

Wer µGulp™ einsetzt, macht seinen Build nicht von µGulp™ abhängig. Ein für das Dashboard vorbereitetes Gulpfile läuft weiterhin unter der klassischen gulp-CLI, in der CI und auf Rechnern, auf denen µGulp™ nie installiert war — und es läuft weiter, wenn µGulp™ wieder deinstalliert wird.

Rückwärtskompatibel — alles fällt auf reines gulp zurück

Ergänzung im Gulpfile	Verhalten unter reinem gulp
µDisplayName, µIcon, µGroup, µOrder, µKeyBinding, µWatch, µAutoClose, µRequiresElevation, …	Nichts. Es sind gewöhnliche Eigenschaften an der exportierten Funktion; die gulp-CLI adressiert Tasks über den Exportnamen und ignoriert unbekannte Eigenschaften. Task-Namen und CLI-Adressierung bleiben unberührt — genau dafür gibt es das µ-Präfix
µParameters	Wird nicht abgefragt. Der Task liest GetParameters() / GetParameter(id, fallback); diese greifen auf die deklarierten Defaults zurück oder auf die Umgebungsvariablen MICROGULP_PARAMS / MICROGULP_PARAM_<ID>, die sich in einem CI-Job von Hand setzen lassen
ReportProgress(...)	Schreibt eine Prozentzeile auf stdout (eine \r-Zeile am TTY, gedrosselte Zeilen in der CI) statt die Neon-Leiste zu steuern
RequestForm, ShowModalMessage, PlaySignal, Speak, LogTable, LogChart, …	Jeder Helfer hat einen CLI-Fallback: Abfragen liefern ihre Defaults, Modals geben eine Zeile aus und antworten ok, Sound und Sprache sind wirkungslos, strukturierte Logs erscheinen als Text
.i18xRegister() / .i18xTrans()	i18xRegister() gibt den amerikanisch-englischen Quelltext unverändert zurück; i18xTrans() fällt ohne Wörterbuch auf den Quelltext zurück. Ohne µGulp™ gibt es also schlicht englische Konsolenausgabe
.microgulp/ (Logs, gemerkte Parameter)	Entsteht nur, wenn µGulp™ den Task ausführt. Ein wegwerfbares Cache-Verzeichnis — in .gitignore aufnehmen und jederzeit löschbar

gulp-mu-gulp-api ist ein normales npm-Paket ohne Laufzeit-Abhängigkeiten, und IsMicroGulp() sagt einem Task, ob er gerade orchestriert wird. µGulp™ zu entfernen heißt: Erweiterung deinstallieren — ohne eine Zeile im Gulpfile zu ändern.

Vorwärtskompatibel — neue µGulp™-Versionen brechen alte Gulpfiles nicht

Metadaten sind additiv, unbekannte Schlüssel werden auf beiden Seiten ignoriert. Ein Gulpfile für ein neueres µGulp™ läuft in einem älteren, die neueren Funktionen stehen dort einfach nicht bereit (kein Shortcut-Badge, kein Watch-Schalter, kein Parameter-Formular — der Task startet trotzdem). Unbekannte Formate strukturierter Logs werden übersprungen statt den Lauf abzubrechen, und das Host-Protokoll trägt eine Versionsnummer, damit ein veralteter Host eine Abweichung erkennt statt sie falsch zu deuten.

Praktische Folge: µGulp™ lässt sich an einem produktiven Build-Skript ausprobieren, während ein Kollege dasselbe Repository per npx gulp BUILD im Terminal nutzt — keine der beiden Seiten merkt etwas von der anderen.

Installation (DE)

Die Marketplace-Seiten sind reserviert, aber noch nicht öffentlich (das Quell-Repository ist noch privat). Bis die Einträge live gehen, aus den Paketen in diesem Repo bzw. einem GitHub-Release installieren.

Edition	Paket	Marketplace (geplant)
µGulp™ (VS Code / Cursor)	packages/microgulp_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ Free (VS Code / Cursor)	packages/microgulp-free_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ (JetBrains-IDEs)	siehe JetBrains-IDEs unten	JetBrains Marketplace (Plugin-ID de.amekudzi.microgulp)

Lokale VSIX-Installation:

code --install-extension packages/microgulp_latest.vsix       # VS Code, registriert
cursor --install-extension packages/microgulp_latest.vsix     # Cursor AI, registriert
code --install-extension packages/microgulp-free_latest.vsix  # VS Code, Free

• Aus den Quellen bauen: npm install, dann npm run build — registriertes und Free-.vsix landen in packages/.

Danach in der Befehlspalette µGulp: Open Dashboard ausführen (oder auf die µGulp™-Rakete in der Statusleiste klicken).

JetBrains-IDEs

Das JetBrains-Plugin ist ein Plattform-Plugin (com.intellij.modules.platform) — es läuft in IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip und anderen IntelliJ-basierten IDEs. Es gibt zwei Pakete — passend zum IDE-Build wählen (Help → About):

IDE-Build	since-build	Paket
2024.2 – 2026.1 (bis 261.*)	242	packages/microgulp-jetbrains_latest.zip
2026.2 und neuer	262	packages/microgulp-jetbrains-2026.2_latest.zip

Passendes ZIP wählen. IntelliJ IDEA, PhpStorm, WebStorm und die übrigen IntelliJ-basierten IDEs teilen sich diese zwei Pakete — nach Plattform-Build wählen, nicht nach Produktname. Jedes Paket trägt <idea-version since-build="…"/> im Plugin-Descriptor — die IDE lädt das andere nicht. microgulp-jetbrains ist since-build="242" / until-build="261.*" (2024.2–2026.1). microgulp-jetbrains-2026.2 ist since-build="262" ohne Obergrenze (2026.2+). Den Plattform-Build zeigt Help → About.

Der JetBrains-Marketplace-Eintrag (Plugin-ID de.amekudzi.microgulp) trägt den lateinischen Anzeigenamen MicroGulp — µ und ™ sind in <name> unzulässig. Dashboard, Toolwindow, Website und dieses README behalten µGulp™. Beide ZIPs teilen diese Plugin-ID. Die plugin.xml-Versionen entstehen aus der einen Produktversion in RELEASES.json als SemVer-Prereleases (<Produkt>-idea242, <Produkt>-idea262; Marketplace SemVer Only), außer Produkt 0.9.3 auf dem Kanal 242–261.* — der bleibt bei Marketplace-Version 0.9.3 (bereits eingereicht). Das 262er Paket zu 0.9.3 ist 0.9.3-idea262. VS Code / Free behalten die Produktversion ohne Suffix. Die ZIP-Namen bleiben *_V<Produkt>.zip. Beide JetBrains-Pakete verwenden denselben Produkt-Changelog. Lizenz: https://microgulp.dev/en/license/. Das Quell-Repository bleibt privat — auf dem Marketplace keine Source-Code-URL angeben.

Ab Build 262 liegt JCEF nicht mehr in der Kernplattform, sondern im gebündelten Plugin Web Browser (JCEF), das im Manifest ausdrücklich angemeldet werden muss — daher das eigene Paket. Installation über Settings → Plugins → ⚙ → Install Plugin from Disk…, danach das Toolwindow µGulp öffnen. Engine-Optionen unter Settings → Tools → µGulp (Node-Pfad, Gulpfile-Discovery, Preload/Pool, Watch, Run-Logs) — analog zu den VS-Code-microgulp.*-Settings. Erscheinungsbild, Sound und Sprache bleiben im Dashboard-⚙-Panel. Das Plugin ist ein dünner JCEF-Adapter — die gesamte Engine läuft in einem mitgelieferten Node.js-Sidecar, daher muss Node.js 22+ installiert sein (PATH, MICROGULP_NODE oder Node-Pfad-Setting). Fehlt JCEF — etwa in abgespeckten IDE-Builds oder bei deaktiviertem Browser-Plugin —, startet das Toolwindow trotzdem die Engine und bietet eine Schaltfläche, die das Dashboard im normalen Browser öffnet.

Pakete bauen und prüfen

npm run jetbrains (Alias npm run phpstorm) baut beide ZIPs, npm run jetbrains:verify prüft sie. Ohne Gradle:

• Jedes Paket wird gegen die älteste IntelliJ-Plattform kompiliert, die es unterstützt — das 242er Paket gegen eine IDE 2024.2, das 262er gegen die installierte IDE. Damit weist bereits javac eine API zurück, die es nur in neueren Builds gibt, statt sie auszuliefern. Der Adapter nutzt nur Plattform-APIs (Toolwindow, Settings, JCEF, Editor), dasselbe ZIP gilt daher für alle IntelliJ-basierten IDEs.
• npm run jetbrains:verify lässt den JetBrains Plugin Verifier über beide ZIPs laufen, jeweils an beiden Enden des angegebenen Bereichs (2024.2 und 2026.1 für das Legacy-Paket, 262 für das andere). Gemeldet werden fehlende Klassen und Methoden, veraltete oder interne API sowie Mängel im Manifest.
• Die Plugin-Verifier-JAR liegt unter dev/tools/intellij-plugin-verifier/ (verifier-cli-1.410-all.jar; bei Bedarf von Maven Central dorthin). Die benötigten IntelliJ-Plattform-Distributionen landen einmalig in MICROGULP_IDE_CACHE (Standard %LOCALAPPDATA%\microgulp\ide-cache, sonst ~/.cache/microgulp/ide-cache) und werden wiederverwendet; passt der Build der lokal installierten IDE, wird diese direkt genutzt. Mit MICROGULP_SKIP_IDE_DOWNLOAD=1 bleibt der Build offline nutzbar — er kompiliert dann gegen die installierte IDE und überspringt die fehlenden Prüfziele.
• Eines sieht der Verifier nicht: Er löst gegen die gesamte IDE auf und ignoriert die Classloader-Trennung der Content-Module, eine fehlende Modul-Abhängigkeit gilt ihm also weiterhin als kompatibel. Deshalb verweigert der Build ein Paket für Build 262+, das JCEF nutzt, ohne com.intellij.modules.jcef und die beiden Module anzumelden.

Bekannter JetBrains-/JCEF-Logeintrag (harmlos)

Beim ersten Einbetten des Dashboards ins µGulp-Toolwindow kann im IDE-Log ein Fehler erscheinen wie:

JBCefApp$Holder <clinit> requests ProxyMigrationService instance. Class initialization must not depend on services.

Ursache ist der eigene JCEF-Stack von JetBrains (JBCefApp → Proxy-Einstellungen → HttpConfigurable), nicht das µGulp-Plugin. JCEF startet trotzdem durch; wenn das Dashboard danach sichtbar ist, kann der Eintrag ignoriert werden. Er hängt nicht an PhpStorm 2025 vs. 2026 — jede JetBrains-IDE mit demselben JCEF-Build kann ihn ausgeben. Nur wenn das Toolwindow leer bleibt oder eine echte µGulp-Startmeldung erscheint (Node-Pfad, Sidecar, Gulpfile-Scan), lohnt sich die Fehlersuche.

Dasselbe Dashboard läuft auch in jedem Browser: npm run serve -- --cwd <projekt> --http 9310 --preload, dann http://127.0.0.1:9310/ öffnen.

Konfigurationsdatei microgulp.config.json (JetBrains & CLI)

In VS Code / Cursor wird die Engine über die Erweiterungseinstellungen konfiguriert (microgulp.gulpfilePattern usw.). Das JetBrains-Plugin spiegelt dieselben Engine-Optionen unter Settings → Tools → µGulp (werden als Sidecar-CLI-Flags beim nächsten Öffnen des Toolwindows übergeben). Optional liefert eine microgulp.config.json im Projektstamm teamweite Defaults und Schlüssel, die nicht auf der IDE-Seite stehen (dashboardFonts, metadataWatchFiles, versionSources). CLI-/Browser-Betrieb über microgulp-serve liest die Datei, wenn kein CLI-Flag gesetzt ist:

{
	"gulpfilePattern": "gulpfile.*\\.mjs$",
	"poolSize": 2,
	"maxParallel": 6,
	"preload": true,
	"watchGulpfiles": true
}

Schlüssel	Typ	Default	Bedeutung
gulpfile	String	"gulpfile.mjs"	Einzelnes Gulpfile, relativ zum Projektstamm
gulpfilePattern	String	—	Case-insensitives Regex gegen workspace-relative POSIX-Pfade; findet alle passenden Gulpfiles (hat Vorrang vor gulpfile)
poolSize	Int ≥ 0	2	Warme Worker pro Gulpfile
maxParallel	Int ≥ 1	6	Maximal gleichzeitige Task-Läufe
preload	Bool	false	Worker-Pools direkt nach dem Start vorwärmen (JetBrains-IDE-Setting standardmäßig an; CLI braucht --preload)
watchGulpfiles	Bool	true	Automatischer Rescan bei Gulpfile-Änderungen
metadataWatchFiles	String[]	["package.json", "RELEASES.json"]	Optional. Workspace-relative Dateien für Metadaten-Rescan. Am besten die Datei beobachten, die das Gulpfile beim Init liest.
versionSources	String[] oder Objekte	["package.json"]	Optional. Live-JSON-Fallback für <version/>, nur wenn das Gulpfile kein µI18xContext.version setzt. Für die meisten Verbraucherprojekte unnötig.
logToFile	Bool	true	Run-Transkripte (.log + .ndjson) und die Task-Historie auf die Festplatte schreiben
logDirectory	String	.microgulp/logs	Verzeichnis für Transkripte und den Historie-Index, relativ zum Projektstamm
logRetention	Int ≥ 0	200	Maximale Anzahl Runs in der Historie (0 = unbegrenzt); ältere Runs und ihre Logdateien werden entfernt

Vorrang: Kommandozeile / JetBrains-IDE-Settings > microgulp.config.json > eingebaute Defaults. Ungültige Werte und unbekannte Schlüssel werden mit einer Warnung auf stderr ignoriert; die Datei ist versionierbar und gilt damit fürs ganze Team. Nach dem Bearbeiten der IDE-Settings oder der Datei das µGulp-Toolwindow neu öffnen (startet den Sidecar neu) bzw. microgulp-serve neu starten.

Empfohlen: µI18xContext.version im Gulpfile setzen + metadataWatchFiles auf die eigene Versionsquelle. versionSources ist optional (Live-JSON ohne Gulpfile-version); "RELEASES.json" nur sinnvoll mit dem Schema unter Versionierung (RELEASES.json). Ausführliche Beispiele: englischer Abschnitt Configuration file.

Projektstruktur

Die kommentierte Verzeichnisübersicht steht im englischen Abschnitt unter Project structure — die Pfade und Kommentare gelten unverändert.

Architekturprinzipien

• Engine-Schicht ist IDE-frei. src/engine und src/worker kennen keine VS-Code-APIs. Die Kommunikation läuft über Events (Engine → Host) und Plain-JSON-Kommandos (Host → Engine). Damit ist die Portierung auf PhpStorm (Phase 2) ein reiner Adapter-Tausch — der minimale Sidecar npm run serve (src/host/microgulp-serve.mjs, NDJSON auf stdio) ist bereits vorbereitet.
• Task-Preloading. Der TaskWorkerPool hält vorgewärmte Node-Prozesse bereit, in denen das Gulpfile bereits importiert wurde. Beim Start eines Tasks wird ein warmer Worker übergeben und der Pool im Hintergrund aufgefüllt. Nach einem Lauf wird der Prozess verworfen (frischer Modulzustand).
• Dynamische Imports. Schwere npm-Pakete (mssql, docx-templates, makensis, …) dürfen im Gulpfile nur per await import() im Task-Body geladen werden — statische Top-Level-Imports sind der Orchestrator-Kernlogik vorbehalten.
• Sprachen. GUI-Texte sind American English und laufen über String.i18xTrans() (i18xe-Anbindung folgt); Code-Kommentare English; Handbücher/Dokumentation Deutsch.

Dashboard-Lokalisierung

Die Dashboard-GUI bringt gebündelte i18x-Wörterbücher für en-US (Quelle), de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP und ko-KR mit. Die Sprache wählt man in den Dashboard-Einstellungen (automatic = Host- oder Browser-Locale). Gulpfile-Konsolenausgabe folgt derselben Sprache über MICROGULP_LANG im Worker und die Projektdateien i18x/gulp/<lid>.json. Das Benutzerhandbuch liegt als PDF je Dashboard-Sprache vor.

Wörterbücher ohne i18xe-Server anlegen oder aktualisieren: Einstellungen → Projekt-i18x (gulp) → i18x/gulp scannen & aktualisieren…. µGulp™ parst Phrasen mit dem i18xe-sync-Scanner (plus Log/Warn/LogError), behält bestehende Übersetzungen, mergt Standard-Formate und schreibt <lid>.status.json-Begleitdateien (missing / orphans) für lokale KI-Übersetzung.

Ebene	Wer liefert	Heute	Geplant
Dashboard-GUI	µGulp (Extension)	en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR	Weitere Marketplace-Sprachen über die i18xe-Sync-Pipeline
Gulp-Tasks & Logs	Ihr Projekt	i18x/gulp/*.json neben dem Gulpfile	Unverändert — Verbraucherprojekte liefern nie i18x/prod
Silbentrennung	µGulp-Webview-Assets	String.prototype.Hyphenation() mit gebündelten <lid>.hyphen.json, wo vorhanden	Weitere Locales, sobald Hyphen-Daten aus i18xe synchronisiert werden

Kontext-Tags, Pflicht-Formate und Sprach-Roadmap: dev/docs/MicroGulpI18xProfile.md. Eine Live-Anbindung an den i18xe-Server für die Dashboard-GUI bleibt optional (Lane 3); Verbraucher-Gulp-Wörterbücher nutzen den Offline-Scan oben.

Gulpfile-Erkennung (per Regex konfigurierbar)

Gulpfile-Änderungen auf der Festplatte erkennt µGulp™ von selbst: Ein Workspace-Watcher (microgulp.watchGulpfiles, Standard an) scannt nach jeder Änderung automatisch neu und tauscht die warmen Worker gegen frische mit dem aktuellen Code. Während des Scans zeigt die Task-Liste eine animierte Fortschrittsanzeige; das Dashboard hat deshalb keinen Rescan-Button mehr — der Befehl µGulp: Rescan Tasks (Befehlspalette) bleibt als manueller Force-Refresh bestehen. Lädt ein Gulpfile nicht (Syntaxfehler, fehlendes Modul), erscheint ein schließbares Fehlerbanner mit Diagnose und Stack-Trace direkt im Dashboard.

µGulp™ findet Gulpfiles wahlweise über einen einzelnen Pfad oder über ein Regex-Muster, das den gesamten Workspace durchsucht:

• microgulp.gulpfilePattern — ein JavaScript-Regex (case-insensitive), das gegen den workspace-relativen Pfad (POSIX-Schreibweise mit /) getestet wird. Ist es gesetzt, wird jede passende Datei gescannt; die Tasks werden im Dashboard nach ihrer Quelle gruppiert. Beispiel: (^|/)gulpfile\.(m|c)?js$ findet gulpfile.mjs/.js/.cjs im Stamm und in jedem Unterordner.
• microgulp.gulpfilePath — der klassische Einzelpfad (Default gulpfile.mjs). Wird nur verwendet, wenn gulpfilePattern leer ist.

node_modules, .git und versteckte Ordner (.*) werden bei der Suche nie betreten. Jedes gefundene Gulpfile bekommt einen eigenen warmen Worker-Pool mit dem Verzeichnis des Gulpfiles als Arbeitsverzeichnis, sodass verschachtelte Unterprojekte mit relativen Pfaden korrekt laufen. Die Discovery-Logik liegt IDE-unabhängig in src/engine/GulpfileDiscovery.mjs und steht damit auch der CLI und dem JetBrains-Adapter zur Verfügung.

Treffen mehrere Gulpfiles zu, zeigt die linke Task-Spalte je Script-Datei eine Quell-Überschrift (workspace-relativer Pfad, z. B. gulpfile.mjs, nested/gulpfile.mjs); Tasks verschiedener Dateien werden nicht auf oberster Ebene gemischt. Innerhalb einer Quelle gelten weiterhin µGroup-Verschachtelungen (Build/Production, …). Bei einem Gulpfile entfällt die Überschrift — nur µGroup-Gruppen bleiben. Exportieren die Gulpfiles Tasks, importiert aber keines gulp-mu-gulp-api, erscheint ein schließbarer Hinweis mit Links zum npm-Paket und zum KI-Migrations-Prompt.

µGulp™-Metadaten am Gulp-Task

Empfohlen sind µ-präfixierte Tags in CamelCase (µDisplayName, µIcon, …) — sie sind für die klassische gulp-CLI unsichtbar, dadurch bleiben Gulpfiles auf Systemen ohne µGulp™ voll kompatibel (die gulp-CLI adressiert Tasks über function.displayName; ein hübscher Name mit Leerzeichen würde dort die Task-Adressierung brechen). Das Code-Beispiel steht im englischen Abschnitt unter µGulp™ metadata on a Gulp task.

µGroup ordnet den Task einer verschachtelten Gruppe in der Task-Übersicht zu. Die Definition folgt einer Verzeichnis-Pfadsyntax: µGroup = 'Build/Production' erzeugt die Gruppe Build mit Untergruppe Production. Gruppen sind im Dashboard ein-/ausklappbar; Tasks ohne µGroup stehen auf oberster Ebene. Die Zuordnung ist optional und rein visuell — sie hat keinen Einfluss auf Ausführung oder Concurrency.

µOrder legt die Sortierposition in der linken Spalte fest (aufsteigende Ganzzahl). Geschwister-Tasks und -Gruppen werden nach µOrder sortiert; Tasks ohne Wert erscheinen nach allen sortierten Tasks (Tie-Breaker: Anzeigename). Gruppen sortieren nach dem kleinsten µOrder in ihrem Unterbaum.

Sondertasten am Gruppen-Header:

Aktion	Wirkung
Klick	Gruppe auf-/zuklappen
Strg+Klick (Cmd+Klick)	alle Gruppen derselben Ebene auf-/zuklappen
Alt+Klick	alle Gruppen auf-/zuklappen

µRequiresElevation kennzeichnet Tasks, die unter Windows Administratorrechte brauchen (z. B. Schreiben in C:\Windows\System32\drivers\etc\hosts). Läuft die IDE normal, startet µGulp™ einen einmaligen elevated Worker und zeigt den üblichen UAC-Dialog — Cursor oder VS Code müssen nicht als Administrator gestartet werden. Ist der Host-Prozess bereits elevated, gilt der warme Worker-Pool wie gewohnt. Auf Nicht-Windows-Plattformen wird das Flag ignoriert. Optionales µElevationReason erscheint im Task-Tooltip (⛿-Badge im Dashboard). Code-Beispiel: englischer Abschnitt µGulp™ metadata on a Gulp task.

Task-Tastenkürzel (µKeyBinding)

Jeder Task kann sein eigenes Tastenkürzel mitbringen. Es greift, während das Dashboard den Fokus hat — VS Code und PhpStorm erlauben keine Tastenbelegung zur Laufzeit, µGulp™ verarbeitet die Kürzel deshalb selbst statt IDE-globale Tasten zu beanspruchen.

BUILD.µKeyBinding = 'ctrl+shift+B';                      // überall dasselbe Kürzel
DEPLOY.µKeyBinding = { key: 'ctrl+alt+D', mac: 'cmd+alt+D' };
STOP.µKeyBinding = { key: 'ctrl+shift+Escape' };         // benannte Tasten: F1…F24, Escape, Tab, Space, Pfeile, …

Bestandteil	Erlaubt
Modifikatoren	ctrl, control, alt, option, shift, meta, cmd, command, super, win
Tasten	Einzelzeichen (b, 7, +), F1–F24, Escape/Esc, Enter, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up/Down/Left/Right
Plattform-Schlüssel	key (Fallback), mac, win, linux — die passende Plattform gewinnt, key füllt den Rest

cmd steht unter macOS für die Command-Taste, sonst für Ctrl — ein einzelnes key-Kürzel bleibt damit plattformübergreifend nutzbar. Das Kürzel erscheint als Badge neben dem Task-Namen; belegen zwei Tasks dasselbe Kürzel, werden beide Badges amber und der Tooltip weist darauf hin (µGulp™ rät nicht, welcher Task gemeint war).

Für ein wirklich IDE-globales Kürzel den Befehl µGulp: Run Task selbst belegen — er nimmt den Task als Argument:

// keybindings.json (VS Code / Cursor)
{ "key": "ctrl+shift+f9", "command": "microgulp.runTask", "args": { "task": "gulpfile.mjs::BUILD_STYLES" } }

Ohne args öffnet der Befehl eine Auswahlliste der gescannten Tasks.

Deklarative Task-Parameter (µParameters)

Statt Eingaben im Task-Rumpf abzufragen, deklariert ein Task, was er braucht. µGulp™ zeigt vor dem Lauf ein Formular, merkt die Antworten für das nächste Mal und übergibt die Werte über die Umgebung. Vollständige Feldtabelle: englischer Abschnitt Declarative task parameters.

DEPLOY.µParameters = {
  submitLabel: 'Start Deploy<context="button text"/>'.i18xRegister(),
  fields: [
    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging' },
    { id: 'servers', type: 'checkbox', options: ['a', 'b'], required: true }, // Absenden bleibt disabled, bis ≥1 gewählt
    { id: 'dryRun', type: 'boolean', default: true },
    { id: 'token', type: 'password' },
  ],
};

required / minSelected prüfen live — der Absenden-Button bleibt disabled, bis die sichtbaren Regeln passen. submitLabel (oder µParameterSubmitLabel am Task) setzt den Button-Text. Die Werte kommen als MICROGULP_PARAMS (JSON) plus je Parameter ein flaches MICROGULP_PARAM_<ID> an; GetParameters() / GetParameter('target', 'staging') aus gulp-mu-gulp-api lesen sie, unter der reinen gulp-CLI lassen sich dieselben Variablen von Hand setzen. Antworten werden pro Task in .microgulp/parameters.json gemerkt und füllen das nächste Formular vor. Passwörter und Felder mit remember: false landen weder im Wertespeicher noch im Transkript, der Historie oder dem Dashboard — dort steht ••••. Elevated Tasks können aus ihrem Einwegprozess kein Formular zeigen und laufen mit gemerkten Werten bzw. den Defaults.

Watch-/Trigger-Tasks (µWatch)

Ein Task kann sich selbst starten, sobald die Dateien wechseln, die ihn interessieren:

BUILD_CSS.µWatch = 'src/**/*.µ.css';                  // Kurzform
BUILD_CSS.µWatch = {
  files: ['src/**/*.µ.css', 'skins/*/manifest.json'], // Globs, relativ zum Gulpfile
  ignore: ['**/*.tmp'],
  debounceMs: 300,                                    // Ruhezeit nach der letzten Änderung
  autoStart: false,                                   // direkt beim Scan scharfschalten
  parameters: { target: 'debug' },                    // feste µParameters für getriggerte Läufe
};

Beobachtung ist pro Task freiwillig: neben dem Task-Namen erscheint ein ◉-Schalter (cyan wenn scharf), sofern die Deklaration nicht autoStart: true sagt. Globs unterstützen **, *, ?, {a,b} und Zeichenklassen; node_modules, .git, .microgulp, .idea und .vscode werden nie beobachtet.

Schutzmechanismen, weil ein Build-Task, der in seine eigene Watch-Menge schreibt, sonst endlos kreisen würde:

• eine Änderungs-Salve ergibt einen Lauf (Debounce)
• läuft der Task noch, wird höchstens ein Folgelauf vorgemerkt
• mehr als 20 getriggerte Läufe pro Minute pausieren den Watcher (amber Schalter, Tooltip erklärt es); aus- und wieder einschalten schärft ihn neu

Ein getriggerter Lauf nennt die auslösende Datei im Log und öffnet nie ein Parameter-Formular — Trigger nutzen die festgelegten oder gemerkten Werte, damit nichts auf einen Menschen wartet, der nicht hinsieht.

Abgeschlossenen Lauf offen halten (µAutoClose)

Abgeschlossene Sektoren schließen sich standardmäßig nach 30 Sekunden (Einstellungen → Abgeschlossene Läufe). Ein Task kann das überschreiben:

SHOW_OUTPUT.µAutoClose = -1;   // Sektor behalten (nie automatisch schließen)
QUICK.µAutoClose = 8;          // nach 8 Sekunden schließen

Wert	Bedeutung
weggelassen / true	Dashboard-Einstellung (Standard 30 s)
-1, false, 0	diesen Task nicht automatisch schließen
positive Ganzzahl	nach so vielen Sekunden schließen (überschreibt die Dashboard-Verzögerung)

Der gelbe Countdown-Chip lässt den Sektor weiterhin behalten. µAutoClose ist Zahl oder Boolean — kein .i18xRegister().

Klickbare Fehlerstellen

Dateiangaben im Run-Log werden zu Links: src/engine/TaskEngine.mjs:412:9, at Object.<anonymous> (gulpfile.mjs:88:15), tsc-/eslint-Ausgaben und MSBuild-Formate wie datei(12,7). Ein Klick (oder Enter auf dem Link) öffnet die Datei an Zeile und Spalte im Editor der IDE — Editor-Tab in VS Code/Cursor, IDE-Editor über die JCEF-Brücke in PhpStorm.

Der Pfad wird hostseitig zuerst gegen das Gulpfile-Verzeichnis des Laufs, dann gegen den Workspace-Stamm aufgelöst; bei mehreren Gulpfiles landet man so in der richtigen Kopie einer mehrdeutigen Datei. Geöffnet werden nur existierende Dateien mit quelltextartiger Endung; URLs, Zeitstempel und Versionsnummern bleiben unangetastet.

Theme-Packs (ZIP)

Eigene Dashboard-Themes lassen sich als ZIP-Packs verteilen und global installieren (~/.microgulp/themes/, Override: MICROGULP_THEMES_DIR) — unabhängig vom Workspace. Details und Pack-Layout: englischer Abschnitt Theme packs (ZIP).

Im Dashboard: Einstellungen → Erscheinungsbild → Theme-ZIP importieren…. Automatisch bleibt bei Neon Carbon / Ice Light.

Sound-Atlas (µAU)

Dashboard-Signale kommen aus dev/media/final/sounds/microgulp/: default/ als Basis, optionale <skin-id>/-Ordner überschreiben nach Dateistamm. Atlanten werden als WebA (audio-only WebM/Opus, microgulp.sounds.weba) ausgeliefert; identische Samples werden dedupliziert. Katalog: dev/docs/MicroGulpSoundSchema.md.

Dashboard-Fonts (Task-Icons & Run-Log)

Projekt-Fonts sind unabhängig von den eingebauten Skins. Registrierung im Gulpfile (bevorzugt) oder über microgulp.config.json / Setting microgulp.dashboardFonts — siehe englischen Abschnitt Dashboard fonts.

Fallback-Kaskade pro Eigenschaft: µDisplayName → ugulp.displayName (Namespace-Objekt) → displayName (Gulps eigenes Feld) → Exportname. executionRestrictions unterstützt deny (gewinnt immer) und allow (Whitelist: alles Nichtgelistete ist verboten).

Metadaten-Strings nutzen i18x mit eingebettetem Kontext-Tag. .i18xRegister() registriert die Phrase nur für i18xe-sync und das Projekt-Wörterbuch — sie gibt den Quelltext unverändert zurück; die Übersetzung erfolgt später, wenn das Dashboard Metadaten rendert (TransProperty() über i18x-catalog), mit Platzhaltern wie <version/> aus µI18xContext. Für Konsolenausgabe .i18xTrans() oder Log()/Warn()/LogError() verwenden — sofortige Übersetzung zur Laufzeit inkl. Platzhalter:

BUILD_STYLES.µDisplayName = 'Build Styles<context="µDisplayName"/>'.i18xRegister();
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();

Kontext-Tags, Pflicht-Formate und Sprachkontingent: dev/docs/MicroGulpI18xProfile.md.

Gulpfile-Migration mit KI

Zum Umbau eines bestehenden Gulpfiles (Konsolenausgabe, Task-Metadaten, i18x/gulp-Wörterbücher, optional µKeyBinding / µParameters / µWatch / µAutoClose) liegt ein gepflegter Prompt im Repository:

Datei	Zweck
dev/prompts/OptimizeGulpfileForMicroGulp.md	Copy-Paste-Prompt für Cursor, Claude, ChatGPT, …
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json	Parameter-Vorlage (Projektpfad, Gulpfile-Name, unterstützte Sprachen, gulp-mu-gulp-api-Version)

Ablauf

1. Parameter-Beispiel ins Projektstammverzeichnis kopieren als microgulp-optimize.params.json und ausfüllen: projectRoot, gulpfilePath, supportedLanguages (z. B. en-US, de-DE, zh-CN), gulpMuGulpApiVersion (^0.4.0 oder neuer), microGulpMinVersion (0.7.0), sowie githubRepoUrl / githubRef (Standard: https://github.com/mamekudz/microGulp, V0.7.0 oder main).
2. Prompt-Markdown öffnen, {{PLACEHOLDER}}-Tabelle mit den Werten ersetzen (oder in Cursor Params-Datei und Gulpfile anhängen).
3. Migration durch die KI ausführen lassen. Schritt 0 im Prompt ist Pflicht: zeitgestempeltes Backup des Gulpfiles (z. B. gulpfile.mjs.20260703-142559.bak) vor jeder Änderung.
4. Prüfen mit node --check gulpfile.mjs, Tasks im µGulp-Dashboard testen (inkl. neuer Tastenkürzel bei Dashboard-Fokus), dann gulpfile.mjs, i18x/gulp/*.json und package.json committen.

Verbraucherprojekte brauchen nur i18x/gulp/<lid>.json — kein i18x/prod. Den Prompt bei µGulp-Releases aktualisieren; vor einer Migration die aktuelle Version in diesem Repository prüfen. Er deckt i18x-Regeln (Register vs. Translate, kein µMeta) und deklarative UX ab: Dashboard-µKeyBinding (nicht IDE-global, außer der Nutzer belegt microgulp.runTask), µParameters / GetParameters(), µWatch, µAutoClose.

Öffentliche Task-API (gulp-mu-gulp-api)

Fremde Gulpfiles und npm-Pakete innerhalb des Streams nutzen die erweiterten Dashboard-Funktionen über das eigenständige npm-Modul **gulp-mu-gulp-api** (liegt als eigenes Projekt unter gulp-mu-gulp-api/, wird separat auf npm veröffentlicht). Das Code-Beispiel steht im englischen Abschnitt unter Public task API.

Das Modul ist abhängigkeitsfrei und spricht direkt über den IPC-Kanal des µGulp™-Workers mit der Engine (Erkennung via IsMicroGulp() / IsµGulp()). Ohne µGulp™ degradiert alles sauber: Fortschritt aufs Terminal, Eingaben per readline (TTY) oder Default-Werte (CI). Details in gulp-mu-gulp-api/README.md. Das interne Modul src/bridge/gulp-ugulp-bridge.mjs bleibt als Low-Level-Transport bestehen; neue Consumer sollten gulp-mu-gulp-api verwenden.

Modal-Dialoge (ShowModalMessage)

Seit V0.5.29 (API: gulp-mu-gulp-api 0.3.11+) können Tasks blockierende Modal-Dialoge anzeigen — für Bestätigungen, Warnungen vor dem Weitermachen oder Ja/Nein- bzw. OK/Abbrechen-Abfragen. Sparsam einsetzen (nicht für normale Log-Zeilen); für Routineausgaben Log() bzw. strukturierte Log-Helfer bevorzugen.

Webview-Glaspanels (Standard)

Bei presentation: 'webview' (Default) erscheinen Modals im µGulp-Dashboard als AiDPix/Oxyd-Glaspanels:

Merkmal	Detail
Rahmen	9-Slice glasspanel.png (ice-light: glasspanel-ice.png)
Varianten	info (türkise Leiste), warning, error — farbige Kopfzeile je Variante
Buttons	Carbon-Optik; Primary-Button hervorgehoben
Overlay	Mausrad über den abgedunkelten Hintergrund dimmt/hellt das Overlay (8–88 %); lange Texte scrollen im Panel
Tastatur	Escape → Abbrechen/Nein (oder erster Button); Enter → Primary-Button

Implementierung: src/webview/WebviewModal.js, src/webview/webview-modal.css (VS-Code-Webview und HTTP-Dashboard).

API

Das Code-Beispiel steht im englischen Abschnitt Modal dialogs (ShowModalMessage). Kurzüberblick:

• ShowModalMessage({ variant?, title?, message?, buttons?, presentation? }) — Einzelmeldung; Standard-Button OK.
• ShowConfirmMessage({ title?, message?, variant?, style?, presentation? }) — Bestätigung; style: 'yes-no' (Default) oder 'ok-cancel'.
• Rückgabe: Promise<{ button: string }> — z. B. 'yes', 'no', 'ok', 'cancel' oder eigene Button-ids.

CLI-Fallback (plain gulp, CI, kein TTY): geklammerte Konsolenausgabe und Primary-/Default-Button — kein blockierender Prompt.

Wo der Dialog erscheint (presentation)

Wert	Verhalten
webview	Glaspanel im Dashboard (Default)
ide	Natives VS-Code-/Cursor-Modal (show*Message mit { modal: true })
auto	IDE-Dialog, wenn der Extension Host verfügbar; sonst Webview-Glaspanel

Pro Aufruf überschreibt presentation die Host-Voreinstellung.

Host-Defaults

Host	Einstellung
VS Code / Cursor	Extension-Setting microgulp.modalPresentation (webview | ide | auto, Default webview)
Browser-Demo / PhpStorm JCEF	Dashboard Einstellungen → Modal presentation (dieselben drei Werte)

Fallback: PhpStorm und ein Browser-Dashboard nutzen immer das Webview-Glaspanel — presentation: 'ide' wird dort auf Webview abgebildet. Native IDE-Modals gibt es nur im VS-Code-/Cursor-Extension-Host.

Demos ausprobieren

Nach µGulp: Open Sample Project stehen in der Gruppe Demo:

Task	Wirkung
DEMO_MODAL_DIALOGS	Alle Varianten + Ja/Nein + OK/Abbrechen mit presentation: 'webview'
DEMO_IDE_MODAL_DIALOGS	Gleicher Ablauf mit presentation: 'ide' (native Modals in Cursor/VS Code; Webview-Fallback in PhpStorm / im Browser)

Weitere API-Details: gulp-mu-gulp-api/README.md.

µGulp-ready-Zertifizierung

npm-Module, deren Root-Gulpfile vollständig ins µGulp-Dashboard integriert ist, dürfen das µGulp ready-Logo auf npm-README und Projektseiten zeigen.

Anforderung	Detail
Gulpfile	Exportierte Tasks mit µGulp-Metadaten (µDisplayName, µDescription, µGroup, …)
API	Nutzung von gulp-mu-gulp-api für Logging, Fortschritt und optionale Dashboard-Features
CLI-Fallback	Tasks bleiben mit plain gulp / npx gulp lauffähig, wenn µGulp nicht installiert ist
Badge-Asset	Kanonisches PNG: media/microgulp-ready.png im µGulp-Repo. npm-README: absolute raw-URL (npm schreibt relative Pfade auf microCSS/HEAD/... um). Beispiel: <img src="https://microgulp.dev/assets/media/microgulp-ready.png" …> in <a href="https://microgulp.dev">
package.json	Optional "microgulp": { "ready": true, "certifiedSince": "<semver>" } für maschinenlesbare Erkennung

Zertifizierte Module

npm-Paket	Seit	Hinweis
gulp-mu-gulp-api	0.3.11	Offizielle Task-API — Log, ReportProgress, i18x-Konsolenschicht, Dashboard-Formulare, ShowModalMessage / ShowConfirmMessage; npm-README-Badge ab 0.3.3
gulp-mu-css (µCSS™)	2.5.15	Monorepo-Root-gulpfile.mjs mit vollständigen Task-Metadaten, i18x/gulp/ (en-US, de-DE) und LogBuildDebugReport bei Demo-Builds; npm-README-Badge per absoluter raw-URL ab 2.5.14
gulp-mu-ps (µPS)	1.3.5	Test-/Render-Tasks im gemeinsamen Root-gulpfile.mjs (TEST_MICROPS, RENDER_EXAMPLES, …)
gulp-mu-ft (µFT)	0.1.5	Test-Task TEST_MICROFT im gemeinsamen Root-gulpfile.mjs
gulp-mu-au (µAU)	0.1.6	Test-Task TEST_MICROAU im gemeinsamen Root-gulpfile.mjs

Migration mit dev/prompts/OptimizeGulpfileForMicroGulp.md; Zertifizierung per Issue oder PR im µGulp- oder Modul-Repository.

Versionierung (RELEASES.json)

RELEASES.json ist das Release-Format von µGulp selbst — einzige Versionsquelle dieses Repositories. Verbraucherprojekte brauchen keine RELEASES.json; sie halten die Produktversion typischerweise in der eigenen Config und setzen µI18xContext.version. Optionales versionSources: ["RELEASES.json"] lohnt sich nur, wenn ihr dieselbe JSON-Struktur übernehmt (Schema und Beispiele: englischer Abschnitt Versioning (RELEASES.json)).

Jeder Release-Eintrag enthält main/minor/revision, Zeitstempel, beta-Flag und eine Liste von Info-Texten. Die Info-Texte tragen den i18x-Kontext-Tag <context="release info"/> und werden über String.i18xRegister() registriert, sodass die i18xe-Engine sie automatisch übersetzen kann. Bei versionSources mit "RELEASES.json" wird <version/> aus releases[0] als "main.minor.revision" gelesen.

Das Modul src/engine/ReleaseInfo.mjs liefert dazu:

• GetVersionString() / GetFullVersionString() — "0.2.0" bzw. "0.1.4ß" (ß-Suffix für Beta-Builds).
• GetVersionHistoryText({ maxReleases, includeBeta }) — die komplette Historie als formatierter String für die Konsole (Task SHOW_VERSION_HISTORY bzw. npm run history).
• BUILD_PACKAGE synchronisiert die package.json-Version und die Versionszeile am Kopf dieses READMEs automatisch aus RELEASES.json und stempelt sie in den Artefaktnamen (microgulp_V0.2.0.vsix, Betas mit Suffix _beta). Für ein neues Release genügt also ein neuer Eintrag oben in RELEASES.json.

Projekt-Build (gulpfile.mjs)

Das Projekt baut sich selbst über sein eigenes Gulpfile (Dogfooding: läuft im µGulp™-Dashboard, über die gulp-CLI, über klassische Gulp-IDE-Erweiterungen und headless):

Aufruf	Task	Zweck
npm test	RUN_TESTS	node:test-Suiten in tests/ (Unit + Engine-Integration mit echten Worker-Prozessen)
npm run theme	CREATE_THEME_DATA	Kompiliert jedes skins/<name>/<name>.µ.css via µCSS (gulp-mu-css BuildSkin) nach src/webview/skins/<name>/dashboard.css (Standard: neon-carbon)
npm run package	BUILD_PACKAGE	Staged die Extension nach tmp/package/ und erzeugt das .vsix in packages/ (zusätzlich aktualisiert als microgulp_latest.vsix)
npm run deploy	DEPLOY_EXTENSION	Update-Zyklus automatisiert: .vsix bauen und per cursor --install-extension installieren (danach Fenster neu laden)
npm run build	BUILD_ALL	Komplette Pipeline: Clean → Tests → Theme → Paket
npm run history	SHOW_VERSION_HISTORY	Gibt die formatierte Versionshistorie aus RELEASES.json auf der Konsole aus
npm run accounts	ACCOUNTS	Nur-Lesen-Liste der Produktions-Registrierungen in LICENSE_KV (--status, --edition; Token aus CLOUDFLARE_API_TOKEN oder website/.env)
npm run website	BUILD_WEBSITE	Erzeugt aus den Sprachabschnitten der README die Website unter website/ (alle Sprachen wählbar; / folgt der Browsersprache)
npm run website:deploy	DEPLOY_WEBSITE	Baut, prüft und veröffentlicht website/ auf den Cloudflare-Worker microgulp-web (microgulp.dev; lokale Wrangler-Anmeldung)
npm run backup	BACKUP_TO_NAS	Inkrementelle robocopy-Spiegelung nach Z:\\Projects\\microGulp (Override: MICROGULP_NAS_BACKUP)
—	PUBLISH_API	Veröffentlicht gulp-mu-gulp-api auf npm (führt vorher dessen Tests aus; npm login erforderlich)
—	CLEAN	Entfernt tmp/ und packages/ (exklusiv, Schreibsperre)

Hinweise:

• gulp-mu-css ist als lokale file:-Abhängigkeit auf C:\Projects\microCSS\gulp-mu-css eingebunden und wird — wie alle schweren Pakete — erst im Task-Body per await import() geladen.
• BUILD_PACKAGE erzeugt ein echtes .vsix, sobald @vscode/vsce installiert ist (npm i -D @vscode/vsce); ohne vsce fällt der Task auf ein Zip des Staging-Ordners zurück.
• Skins sind eigenständig: ein Verzeichnis pro Skin unter skins/ (z. B. skins/neon-carbon/, skins/ice-light/, skins/ide-dark/), jeweils mit einem <name>.µcss.mjs-Manifest und einer gleichnamigen <name>.µ.css-Quelle. CREATE_THEME_DATA erkennt und baut jeden Skin; neon-carbon (dunkel) ist der Standard, ice-light liefert ein helles Frostglas-Pendant. ide-dark / ide-light sind schlichte VS-Code-ähnliche Flächen ohne Carbon-Muster und Neon-Puls. Weitere/eigene Skins lassen sich als Geschwister-Verzeichnisse ergänzen. Die Skin-Auswahl im Dashboard (Einstellungen → Erscheinungsbild) bietet einen Automatik-Modus, der dem hellen/dunklen IDE-/OS-Theme folgt (ice-light / neon-carbon).
• Das Webview bevorzugt automatisch das generierte Standard-Skin (src/webview/skins/neon-carbon/dashboard.css); das handgeschriebene dashboard.css bleibt als Fallback für frische Checkouts.
• Das Dashboard zeigt links neben dem Neon-Schriftzug µGulp™ das gelbe Mikroskop (baselogo.svg) per µCSS-Data-URI-Inlining (background-image: µ(DataUri("imgs/baselogo.svg"))). Quelle aller fertigen Art-Assets ist dev/media/final/; der Build synchronisiert daraus media/logo.png (Extension-Icon), media/logo_readme.png (README), src/webview/skins/<name>/imgs/baselogo.svg (Dashboard) und jetbrains/resources/icons/baseoutlinelogo.svg (JetBrains-Toolwindow + Plugin-Liste).

Dieses Repository enthält zusätzlich demo/gulpfile.mjs für die lokale Entwicklung:

npm run demo          # Headless-Engine-Smoke-Test
npm run demo:web      # Browser-Dashboard (microgulp-serve --http)
npm run demo:ide      # Extension Development Host mit demo/ als Workspace

F5 in VS Code/Cursor (Launch-Konfiguration „Run µGulp Extension“) öffnet denselben Demo-Workspace.

Ausprobieren

Installierte Erweiterung: Befehlspalette → µGulp: Open Sample Project (JetBrains: Tools → µGulp: Open Sample Project). Damit wird ein Sample-Gulpfile mit Demo- und Build-Tasks (Fortschritt, Formulare, strukturierte Logs, Sound, Modals) nach ~/.microgulp/sample kopiert und geöffnet. Danach µGulp: Open Dashboard. Das Benutzerhandbuch liegt unter Einstellungen → Handbook (oder µGulp: Open Handbook); dort sind alle Sprachvarianten aufrufbar.

Handbuch-PDFs: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어

Lizenz

µGulp™ (Extension, Engine, Dashboard, JetBrains-Adapter) ist proprietäre Software — siehe LICENSE. Die verteilten Binärdateien dürfen kostenlos genutzt werden; Kopieren, Ändern oder Weiterverbreiten des Quellcodes ist nicht gestattet.

Das begleitende npm-Paket gulp-mu-gulp-api bleibt unter der MIT-Lizenz, damit Gulp-Tasks es uneingeschränkt einbinden können.

Roadmap / offene Punkte des Entwurfs

In V0.5.0 umgesetzt

• [x] i18x-Schicht im Webview: Spracheinstellung (automatisch/en-US/de-DE/zh-CN), Kontext-Tags an allen GUI-Strings, Formatdefinitionen aus dem i18xe-Server übernommen — die direkte i18xe-Server-Anbindung folgt später
• [x] µ-Task-Metadaten: .i18xRegister() registriert Phrasen für i18xe/Dashboard; Übersetzung und Platzhalter beim Dashboard-Render über i18x-catalog + µI18xContext; Konsole über .i18xTrans() / Log()
• [x] Öffentliche Task-API **gulp-mu-gulp-api** auf npm (Fortschritt, Sound/Sprache, interaktive Formulare mit CLI-Fallbacks; IsMicroGulp, InstallStringExtensions)
• [x] Legacy-Prompt-Bibliotheken (inquirer, gulp-prompt, prompts) auf Dashboard-Formulare umgeleitet, ohne Gulpfiles anzufassen
• [x] Erweiterte Dashboard-Formularsteuerelemente (Radio, Range, Textarea, Passwort, Zahl, Datum/Uhrzeit, Datei, Mehrfachauswahl per Checkbox)
• [x] Dashboard-Einstellungen (akustische Kontrolle, Sprachausgabe, Formular-Erinnerung, Fehlerbehandlung, Sprache)
• [x] Konsolen-Rendering in den Task-Sektoren (ANSI-Farben, \r-Fortschrittszeilen, Zeitstempel)
• [x] Persistente Task-Historie & Log-Umlenkung in Dateien (roh .log + strukturiert .ndjson, history.ndjson-Index, Retention, Historie-Panel im Dashboard)
• [x] microgulp.config.json für Team-/CLI-Defaults (JetBrains-IDE-Settings + VS-Code-Extension-Settings haben Vorrang, wenn gesetzt)
• [x] Task-Sortierung im Dashboard über µOrder (aufsteigend; Gruppen nach Minimum im Unterbaum)
• [x] Phase 2: JetBrains-Adapter — JCEF-Toolwindow + Node-Sidecar + HTTP/SSE-Dashboard + Settings → Tools → µGulp (alle IntelliJ-basierten IDEs)
• [x] Optionale Windows-UAC-Elevation pro Task (µRequiresElevation, µElevationReason) — IDE bleibt non-admin
• [x] Dashboard-Lokalisierung dokumentiert: gebündelt en-US / de-DE / zh-CN; Verbraucherprojekte liefern nur i18x/gulp
• [x] Multi-Skin-Dashboard (Neon Carbon, Ice Light, IDE Dunkel/Hell) + globale Theme-ZIP-Packs (Appearance-Import; optionale Sounds/Grafiken)
• [x] Themenbezogene µAU-Soundatlanten (default/ + Skin-Overrides, PCM-Dedup); Katalog in dev/docs/MicroGulpSoundSchema.md
• [x] Projekt-Fonts für Task-Icons / Run-Log (RegisterDashboardFont, µIconFont, dashboardFonts; gulp-mu-gulp-api 0.3.12)
• [x] Task-Tastenkürzel (µKeyBinding, plattformspezifische Kürzel, Kollisions-Badge) + µGulp: Run Task für IDE-globale Belegung
• [x] Deklarative Task-Parameter (µParameters, GetParameters(), gemerkte Antworten, maskierte Geheimnisse)
• [x] Watch-/Trigger-Tasks (µWatch-Globs, Debounce, Runaway-Bremse, Dashboard-Schalter)
• [x] Auto-Schließen pro Task überschreibbar (µAutoClose: -1 offen halten, positive Sekunden, sonst Einstellungen)
• [x] Klickbare Fehlerstellen im Run-Log (VS-Code-Editor-Tab, PhpStorm-JCEF-Brücke)
• [x] CI-Matrix über Windows / Linux / macOS auf Node 22 und 24
• [x] Offline-Sync der i18x/gulp-Wörterbücher im Dashboard (i18xe-sync-Parser, Sprachdialog, Standard-Formate, <lid>.status.json für KI-Übersetzung)

Noch offen

• [ ] µLib (microLib) dokumentieren, danach als Utility-Schicht in µGulp einsetzen (i18x ist derzeit eine lokale Webview-Teilmenge)
• [ ] Direkte i18xe-Server-Anbindung: Live-Übersetzungssync statt der mitgelieferten de-DE/zh-CN-Wörterbücher
• [ ] GUI.mjs aus µLib um weitere spezielle Steuerelemente für die Dashboard-Formulare erweitern
• [ ] Optisches Feintuning des Webview-Dashboards
• [ ] µCSS-Skin ausbauen: Symbol-Font und Sprites ins Manifest aufnehmen
• [ ] Sprachausgabe über i18xe (Atlas-Samples ersetzen WebAudio-Beeps bereits, sofern vorhanden)
• [x] JetBrains-Plugin: Settings → Tools → µGulp (Engine-Optionen, alle IntelliJ-basierten IDEs)
• [ ] JetBrains-Marketplace-Verteilung (zurückgestellt — vorerst Installation vom lokalen ZIP)
• [ ] VS-Code-/Cursor-Erweiterung in einem Marketplace veröffentlichen (zurückgestellt — Verteilung über GitHub-Releases / packages/*_latest.*)

---

Français

Rock your Gulp!

µGulp™, l'orchestrateur de tâches interactif à latence quasi nulle, avec visuels riches, commandes webview et retour audio — livré comme extension IDE en trois éditions (VS Code / Cursor enregistré, VS Code / Cursor Free, IDEs JetBrains) avec un tableau de bord webview Carbon/Neon.

Points forts

µGulp™ est livré comme µGulp™ (VS Code / Cursor), µGulp™ Free (VS Code / Cursor) et µGulp™ pour les IDEs JetBrains (IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip et autres IDEs basés sur IntelliJ). La répartition ci-dessous est le plan actuel et peut encore changer avant le lancement public sur le marketplace. N'installez pas l'extension VS Code enregistrée et µGulp™ Free côte à côte — elles partagent les mêmes IDs de commande. L'édition VS Code enregistrée doit être enregistrée avant d'exécuter des tâches — ou désinstallez-la et utilisez µGulp™ Free.

	µGulp™ VS Code / Cursor	µGulp™ Free VS Code / Cursor	µGulp™ JetBrains IDEs
Prix (mois / an)	0 € / $0	0 € / $0	0 € / $0
Tableau de bord des tâches, preload, i18x, paramètres, µWatch, historique	oui	oui	oui
Licence / enregistrement	requis	aucun	aucun
Skins (Neon Carbon, Ice Light, IDE Dark / Light, Automatic)	oui	IDE Dark / Light selon le thème de l'IDE (non sélectionnable)	oui
Packs de thème ZIP personnalisés	oui	—	oui
Moteur de diagnostic	oui	—	oui
Élévation UAC Windows	oui	—	oui
Réglages de l'hôte	microgulp.*	microgulp.*	Settings → Tools → µGulp
Marketplace (fiche pas encore publique)	VS Code · Open VSX	VS Code · Open VSX	JetBrains (de.amekudzi.microgulp)

Toutes les éditions sont actuellement gratuites (0 € / $0 par mois et par an). Les points ci-dessous décrivent le produit complet. Free suit le thème IDE/OS avec IDE Dark / IDE Light (pas de sélecteur Appearance) et omet les packs de thème, le diagnostic et l'élévation.

• Workers préchargés — processus Node chauds avec le gulpfile déjà importé ; latence clic-à-exécution quasi nulle (évite les scans de démarrage à froid des logiciels antivirus)
• Liste de tâches groupée avec icônes et textes localisables — imbriquer les tâches avec des chemins µGroup (Build/Production), groupes repliables, µIcon (glyphe ou image) et µDisplayName / µDescription / µTooltip enregistrés avec .i18xRegister() et traduits en direct via i18x-catalog ; µOrder trie les tâches et les groupes
• Grille de tâches parallèle — plusieurs secteurs d'exécution isolés côte à côte, chacun avec son propre flux de journal
• Tableau de bord web — journaux ANSI colorés en direct, sortie filtrée, barres de progression déterminées, formulaires riches pour l'entrée de l'utilisateur (texte, couleur, police, select, multiselect, …)
• Surveillance live du gulpfile — le watcher du workspace rescane à l'enregistrement et remplace automatiquement les workers obsolètes
• Sans verrouillage — les métadonnées préfixées µ sont invisibles pour la CLI gulp classique et chaque helper d'API a un repli CLI, donc le même gulpfile s'exécute inchangé avec, sans et après µGulp™ (détails)
• Tâches gulp prêtes pour l'i18n — .i18xRegister() enregistre les phrases de métadonnées (balises de contexte intégrées sur les noms d'affichage, descriptions, infobulles, groupes) dans le dictionnaire du projet et renvoie la source en anglais américain inchangée ; le tableau de bord les traduit ensuite via i18x-catalog avec les espaces réservés (version, project, …) de µI18xContext. La sortie console utilise .i18xTrans() / Log() pour une traduction immédiate, y compris la résolution des espaces réservés
• Localisation du tableau de bord — dictionnaires GUI groupés pour en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP et ko-KR (réglages : automatique ou locale fixe) ; d'autres langues sont prévues via i18xe sync. Le manuel utilisateur est un PDF dans la langue du tableau de bord
• Synchronisation des dictionnaires pour vos gulpfiles — Settings → Project i18x (gulp) scanne les sources avec le parseur i18xe-sync, écrit i18x/gulp/<lid>.json pour les langues choisies, conserve les traductions existantes et fusionne les formats standard ; un fichier satellite <lid>.status.json liste ce qu'une IA locale doit encore traduire
• Paramètres de tâche déclaratifs — µParameters demande une fois avant l'exécution, transmet les valeurs comme MICROGULP_PARAMS / GetParameters(), mémorise les dernières réponses, tient les mots de passe hors des journaux et peut masquer des champs avec visibleWhen
• Tâches watch / déclenchement — les globs µWatch lancent une tâche sur les changements de fichiers, avec debounce, coalescence et disjoncteur en cas d'emballement ; armé par tâche depuis le tableau de bord
• Raccourcis de tâche — accords µKeyBinding avec variantes par plateforme (ctrl+shift+F1, cmd+shift+Escape), badges et avertissements de conflit ; µGulp: Run Task pour les raccourcis globaux de l'IDE
• Sortie de journal structurée — les tâches émettent des charges JSON rendues en ligne dans le journal d'exécution (tableaux, arbres, galeries d'images, encadrés, métriques clé/valeur, badges d'état, blocs de code, histogrammes SVG inline) — sûr pour la Content-Security-Policy, sans plugin ni iframe ; la largeur des graphiques est plafonnée et les en-têtes/lignes LogTable utilisent des couleurs teintées par le skin, avec survol
• Historique persistant des tâches et journalisation fichier — chaque exécution est écrite dans .microgulp/logs (.log brut + .ndjson structuré), un index history.ndjson survit aux reconnexions/redémarrages de l'IDE ; un panneau d'historique du tableau de bord ouvre chaque transcription (logToFile, logRetention)
• Dialogues modaux — ShowModalMessage / ShowConfirmMessage comme panneaux de verre style AiDPix dans le tableau de bord (info/avertissement/erreur, Oui/Non, OK/Annuler) ; modaux natifs VS Code/Cursor optionnels via presentation ou microgulp.modalPresentation (gulp-mu-gulp-api) ; section README dédiée
• Emplacements d'erreur cliquables — file:line:column dans le journal d'exécution s'ouvre dans l'éditeur hôte (onglet VS Code, éditeur IDE JetBrains)
• Matrice de concurrence — exécutions exclusives par tâche et règles allow/deny (µExecutionConcurrency, µExecutionRestrictions)
• Skins du tableau de bord — Neon Carbon, Ice Light, plus IDE Dark / IDE Light simples ; sélecteur Appearance avec Automatic (suivre le thème IDE/OS) (Free : IDE Dark / IDE Light selon le thème de l'IDE, non sélectionnable)
• Packs de thème ZIP personnalisés — installation globale (~/.microgulp/themes) ; les packs peuvent inclure CSS, graphismes, polices et atlas sonores optionnels ; import/suppression sous Settings → Appearance (pas dans Free)
• Polices de projet pour icônes et journaux — RegisterDashboardFont / µDashboardFonts / dashboardFonts pour le glyphe µIcon et les polices du journal d'exécution ; µIconFont optionnel par tâche (gulp-mu-gulp-api 0.3.12)
• Contrôle acoustique optionnel — sons de fin, alarmes d'erreur et sortie vocale (réglages du tableau de bord)
• Rappel de formulaire optionnel — lorsqu'une tâche attend une entrée du tableau de bord, rappeler l'utilisateur après un délai configurable par son et/ou parole ; se répète jusqu'à ce que le formulaire soit répondu
• Fermeture automatique des exécutions terminées — compte à rebours optionnel dans l'en-tête du secteur (cliquer pour garder ouvert) ; une tâche peut le remplacer avec µAutoClose (-1 garder ouvert, un nombre positif = secondes, omis = Settings → Finished Runs, 30 s par défaut) ; Restart à côté de Close
• Élévation administrateur Windows — invite UAC optionnelle par tâche (µRequiresElevation, µElevationReason) ; l'IDE peut tourner normalement tandis que des tâches individuelles (p. ex. édition de hosts) s'exécutent en élevé (VS Code enregistré / JetBrains ; pas dans Free)
• Moteur de diagnostic — les erreurs d'import et traces de pile deviennent des suggestions actionnables dans le tableau de bord (VS Code enregistré / JetBrains ; pas dans Free)
• <version/> depuis le gulpfile — µI18xContext.version est la source préférée pour les titres de tâche ; versionSources optionnel ne complète que lorsque le gulpfile omet version (pas d'écrasement des configs de release du consommateur)
• LogError fiable vs. avertissements Node — LogError / un vrai console.error font toujours échouer l'exécution ; DeprecationWarning Node et les autres avertissements de processus ne le font pas (la bannière d'échec affiche le premier vrai texte d'erreur)
• Pont de prompts hérités — inquirer / gulp-prompt / prompts redirigés vers les formulaires du tableau de bord sans modifier les gulpfiles
• gulp-mu-gulp-api — module npm pour la progression, le son, la parole, les entrées interactives, les dialogues modaux et les polices du tableau de bord depuis l'intérieur des tâches

Aperçu

Hosts	VS Code, Cursor AI, JetBrains IDEs (Settings → Tools → µGulp), tout navigateur sur 127.0.0.1 via microgulp-serve --http
Runtime	Node.js 22+ (ESM)
Gulpfiles	Un seul gulpfile.mjs ou découverte regex dans le workspace
Config	Réglages d'extension (VS Code/Cursor), Settings → Tools → µGulp (JetBrains), microgulp.config.json optionnel (équipe / CLI)
Engine	Indépendant de l'IDE — le même src/engine dans chaque hôte
Langues	GUI du tableau de bord : en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR (groupées) ; sortie gulp via i18x/gulp/ du projet ; manuel en PDF dans la langue du tableau de bord
Ordre des tâches	µOrder (entier croissant) ; groupes par ordre minimum dans le sous-arbre ; tâches sans ordre en dernier (alphabétique)

Cliquez une tâche → un worker chaud l'exécute immédiatement. Modifiez le gulpfile → la liste des tâches se met à jour toute seule. Plusieurs tâches peuvent tourner en parallèle ; chacune reçoit son propre secteur de tableau de bord avec une barre de progression néon lorsque la tâche appelle ReportProgress depuis gulp-mu-gulp-api.

Sans verrouillage : le gulpfile reste un gulpfile classique

Adopter µGulp™ ne rend pas votre build dépendant de µGulp™. Un gulpfile préparé pour le tableau de bord s'exécute toujours sous la CLI gulp classique, en CI, et sur des machines où µGulp™ n'a jamais été installé — et il continue de tourner lorsque µGulp™ est désinstallé.

Rétrocompatible — tout se dégrade vers gulp simple

Ce que vous ajoutez	Ce que gulp simple en fait
µDisplayName, µIcon, µGroup, µOrder, µKeyBinding, µWatch, µAutoClose, µRequiresElevation, …	Rien. Ce sont des propriétés ordinaires sur la fonction exportée ; la CLI gulp adresse les tâches par nom d'export et ignore les propriétés inconnues. Les noms de tâches et l'adressage CLI restent intacts — c'est exactement pourquoi le préfixe µ existe
µParameters	Non demandés. La tâche lit GetParameters() / GetParameter(id, fallback), qui se rabattent sur les défauts déclarés, ou sur les variables d'environnement MICROGULP_PARAMS / MICROGULP_PARAM_<ID> que vous pouvez poser à la main dans un job CI
ReportProgress(...)	Imprime une ligne de pourcentage sur stdout (une seule ligne \r sur un TTY, lignes limitées en CI) au lieu de piloter la barre néon
RequestForm, ShowModalMessage, PlaySignal, Speak, LogTable, LogChart, …	Chaque helper a un repli CLI : les invites se résolvent à leurs défauts, les modaux impriment une ligne entre crochets et renvoient ok, son et parole sont des no-ops, les journaux structurés s'affichent en texte
.i18xRegister() / .i18xTrans()	i18xRegister() renvoie la chaîne source en anglais américain inchangée ; i18xTrans() se rabat sur le texte source lorsqu'aucun dictionnaire n'est présent. Sans µGulp™ vous obtenez simplement une sortie console en anglais
.microgulp/ (journaux, paramètres mémorisés)	Écrit uniquement lorsque µGulp™ exécute la tâche. C'est un répertoire cache jetable — ajoutez-le à .gitignore et supprimez-le à tout moment

gulp-mu-gulp-api est un paquet npm normal sans dépendances d'exécution, et IsMicroGulp() indique à une tâche si elle est orchestrée. Retirer µGulp™ signifie désinstaller l'extension — aucune modification de gulpfile requise.

Compatible vers l'avant — les nouvelles versions de µGulp™ ne cassent pas les anciens gulpfiles

Les métadonnées sont additives et les clés inconnues sont ignorées des deux côtés. Un gulpfile écrit pour un µGulp™ plus récent s'exécute dans un plus ancien, les fonctions plus récentes étant simplement indisponibles (pas de badge de raccourci, pas de bascule watch, pas de formulaire de paramètres — la tâche démarre quand même). Les formats de journal structuré inconnus sont ignorés au lieu de casser l'exécution, et le protocole hôte porte un numéro de version pour qu'un hôte obsolète détecte un écart plutôt que de le mal interpréter.

Conséquence pratique : vous pouvez essayer µGulp™ sur un script de build de production, donner le même dépôt à un collègue qui lance npx gulp BUILD dans un terminal, et aucune des deux configurations ne remarque l'autre.

Installation

Les pages marketplace sont réservées mais pas encore publiques (le dépôt source est encore privé). Tant que les fiches ne sont pas en ligne, installez depuis les paquets de ce dépôt / une GitHub Release.

Édition	Paquet	Marketplace (prévu)
µGulp™ (VS Code / Cursor)	packages/microgulp_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ Free (VS Code / Cursor)	packages/microgulp-free_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ (JetBrains IDEs)	voir IDEs JetBrains ci-dessous	JetBrains Marketplace (plugin id de.amekudzi.microgulp)

Installation VSIX locale :

code --install-extension packages/microgulp_latest.vsix       # VS Code, registered
cursor --install-extension packages/microgulp_latest.vsix     # Cursor AI, registered
code --install-extension packages/microgulp-free_latest.vsix  # VS Code, Free

• Compiler depuis les sources : npm install, puis npm run build — les fichiers .vsix enregistré et Free atterrissent dans packages/.

Ensuite lancez µGulp: Open Dashboard depuis la palette de commandes (ou cliquez la fusée µGulp™ dans la barre d'état).

IDEs JetBrains

Le plugin JetBrains est un plugin de plateforme (com.intellij.modules.platform) — il s'installe dans IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip et d'autres IDEs basés sur IntelliJ. Il est livré en deux paquets — choisissez celui qui correspond au build de votre IDE (Help → About) :

IDE build	since-build	Paquet
2024.2 – 2026.1 (jusqu'à 261.*)	242	packages/microgulp-jetbrains_latest.zip
2026.2 et plus récent	262	packages/microgulp-jetbrains-2026.2_latest.zip

Prenez le zip correspondant. IntelliJ IDEA, PhpStorm, WebStorm et les autres IDEs basés sur IntelliJ partagent ces deux paquets — choisissez selon le build plateforme, pas le nom du produit. Chaque paquet déclare <idea-version since-build="…"/> dans le descripteur — l'IDE n'accepte pas l'autre. microgulp-jetbrains est since-build="242" / until-build="261.*" (2024.2–2026.1). microgulp-jetbrains-2026.2 est since-build="262" sans borne supérieure (2026.2+). Le build plateforme est dans Help → About.

La fiche JetBrains Marketplace (id de plugin de.amekudzi.microgulp) utilise le nom latin MicroGulp — µ et ™ sont interdits dans <name>. Le tableau de bord, la fenêtre d'outils, le site et ce README gardent µGulp™. Les deux zips partagent cet id. Les versions plugin.xml sont dérivées de la version produit unique dans RELEASES.json en prereleases SemVer (<produit>-idea242, <produit>-idea262 ; Marketplace SemVer Only), sauf le produit 0.9.3 sur le canal 242–261.* qui reste en version marketplace 0.9.3 (déjà déposée). Le paquet 262 pour 0.9.3 est 0.9.3-idea262. VS Code / Free gardent la version produit sans suffixe. Les noms de zip restent *_V<produit>.zip. Les deux paquets JetBrains portent le même journal de la version produit. Licence : https://microgulp.dev/en/license/. Le dépôt source reste privé — n'indiquez pas d'URL de code source sur la fiche Marketplace.

Le build 262 a déplacé JCEF hors de la plateforme cœur vers le plugin groupé Web Browser (JCEF), donc le descripteur doit le déclarer explicitement — d'où le paquet séparé. Installez via Settings → Plugins → ⚙ → Install Plugin from Disk… et ouvrez la fenêtre d'outils µGulp. Les options moteur sont sous Settings → Tools → µGulp (chemin Node, découverte du gulpfile, preload/pool, watch, journaux d'exécution) — même rôle que les réglages VS Code microgulp.*. Apparence, son et langue restent dans le panneau ⚙ du tableau de bord. Le plugin est un adaptateur JCEF mince — tout le moteur tourne dans un sidecar Node.js groupé, donc Node.js 22+ doit être installé (PATH, MICROGULP_NODE, ou le réglage de chemin Node). Si JCEF est indisponible — builds IDE allégés, plugin navigateur désactivé — la fenêtre d'outils démarre quand même le moteur et propose un bouton qui ouvre le tableau de bord dans votre navigateur habituel.

Compilation et vérification des paquets

npm run jetbrains (alias npm run phpstorm) construit les deux zips, npm run jetbrains:verify les vérifie. Pas de Gradle :

• Chaque paquet est compilé contre la plus ancienne plateforme IntelliJ qu'il prend en charge — le paquet 242 contre un IDE 2024.2, le paquet 262 contre l'IDE installé. javac refuse alors une API qui n'existe que dans un build plus récent au lieu de la laisser partir. L'adaptateur n'utilise que les APIs de plateforme (fenêtre d'outils, réglages, JCEF, éditeur), donc le même zip tourne dans chaque IDE basé sur IntelliJ.
• npm run jetbrains:verify lance le JetBrains Plugin Verifier sur les deux zips, aux deux extrémités de leur plage déclarée (2024.2 et 2026.1 pour le paquet legacy, 262 pour l'autre). Il signale les classes et méthodes manquantes, les APIs dépréciées ou internes, et les défauts de descripteur.
• Le fat-jar Plugin Verifier se trouve dans dev/tools/intellij-plugin-verifier/ (verifier-cli-1.410-all.jar ; téléchargé depuis Maven Central s'il manque). Les distributions de la plateforme IntelliJ nécessaires sont téléchargées une fois dans MICROGULP_IDE_CACHE (défaut %LOCALAPPDATA%\microgulp\ide-cache, ~/.cache/microgulp/ide-cache ailleurs) et réutilisées ; l'IDE installé localement est utilisé directement lorsque son build correspond. MICROGULP_SKIP_IDE_DOWNLOAD=1 garde les builds hors ligne fonctionnels — ils compilent alors contre l'IDE installé et sautent les cibles de vérification manquantes.
• Une chose que le vérificateur ne voit pas : il résout contre l'IDE entier et ignore l'isolation classloader des modules de contenu, donc une dépendance de module manquante se lit encore comme compatible. Le build refuse donc d'empaqueter un paquet pour le build 262+ qui touche JCEF sans déclarer com.intellij.modules.jcef et ses deux modules.

Bruit connu dans le journal JetBrains / JCEF (sans danger)

La première fois que la fenêtre d'outils µGulp embarque le tableau de bord, le journal de l'IDE peut afficher une erreur comme :

JBCefApp$Holder <clinit> requests ProxyMigrationService instance. Class initialization must not depend on services.

Cela vient de la propre pile JCEF de JetBrains (JBCefApp → réglages proxy → HttpConfigurable), pas du plugin µGulp. La plateforme termine quand même le démarrage JCEF ; si le tableau de bord apparaît ensuite, vous pouvez ignorer l'entrée. Cela n'est pas lié à PhpStorm 2025 vs. 2026 — tout IDE JetBrains utilisant le même build JCEF peut l'émettre. N'enquêtez plus loin que si la fenêtre d'outils reste vide ou affiche une vraie erreur de démarrage µGulp (chemin Node, sidecar, scan du gulpfile).

Le même tableau de bord tourne aussi dans n'importe quel navigateur simple : npm run serve -- --cwd <project> --http 9310 --preload, puis ouvrez http://127.0.0.1:9310/.

Fichier de configuration microgulp.config.json (JetBrains et CLI)

Dans VS Code / Cursor le moteur est configuré via les réglages d'extension (microgulp.gulpfilePattern etc.). Le plugin JetBrains reflète ces options moteur sous Settings → Tools → µGulp (passées comme drapeaux CLI du sidecar à la prochaine ouverture de la fenêtre d'outils). En option, un microgulp.config.json à la racine du projet fournit encore des défauts d'équipe et des clés absentes de la page IDE (dashboardFonts, metadataWatchFiles, versionSources). L'usage CLI/navigateur via microgulp-serve lit le fichier lorsqu'aucun drapeau CLI n'est donné :

{
	"gulpfilePattern": "gulpfile.*\\.mjs$",
	"poolSize": 2,
	"maxParallel": 6,
	"preload": true,
	"watchGulpfiles": true
}

Key	Type	Default	Meaning
gulpfile	string	"gulpfile.mjs"	Single gulpfile, relative to the project root
gulpfilePattern	string	—	Case-insensitive regex against workspace-relative POSIX paths; discovers all matching gulpfiles (wins over gulpfile)
poolSize	int ≥ 0	2	Warm workers per gulpfile
maxParallel	int ≥ 1	6	Maximum concurrent task runs
preload	bool	false	Warm up the worker pools right after startup (PhpStorm IDE setting defaults to on; CLI needs --preload)
watchGulpfiles	bool	true	Auto-rescan on gulpfile changes
metadataWatchFiles	string[]	["package.json", "RELEASES.json"]	Optional. Workspace-relative files whose changes trigger a metadata rescan (e.g. after a version bump). Prefer watching the file your gulpfile reads at init.
versionSources	string[] or objects	["package.json"]	Optional. Live JSON fallback for <version/> when the gulpfile does not set µI18xContext.version. Rarely needed for consumer projects — see below.
dashboardFonts	array	—	Optional. Project fonts for task icons / run log (see Polices du tableau de bord)
logToFile	bool	true	Persist run transcripts (.log + .ndjson) and the task history to disk
logDirectory	string	.microgulp/logs	Directory for transcripts and the history index, relative to the project root
logRetention	int ≥ 0	200	Max runs kept in the history (0 = unlimited); older runs and their log files are pruned

Priorité : ligne de commande / réglages IDE JetBrains > microgulp.config.json > défauts intégrés. Les valeurs invalides et les clés inconnues sont ignorées avec un avertissement sur stderr ; le fichier est versionnable et s'applique à toute l'équipe. Après modification des réglages IDE ou du fichier, rouvrez la fenêtre d'outils µGulp (respawn le sidecar) ou redémarrez microgulp-serve.

Dans VS Code / Cursor les mêmes clés sont disponibles comme microgulp.metadataWatchFiles et microgulp.versionSources (les réglages d'extension non vides l'emportent sur microgulp.config.json). Des tableaux vides désactivent les surveillances de métadonnées ou les lectures de version live depuis les fichiers.

<version/> dans les titres de tâche (préféré vs optionnel)

Préféré (la plupart des projets consommateurs) : exportez µI18xContext depuis le gulpfile et y posez version (lisez votre unique source de release à l'init du module). Utilisez metadataWatchFiles pour que les changements de cette source rescannent et rafraîchissent les workers chauds :

export const µI18xContext = { project: 'MyApp', version: _ReadReleaseVersion() };
MAKE_BUILD.µDisplayName = 'Build V<version/><context="µDisplayName"/>'.i18xRegister();

{
	"metadataWatchFiles": ["configs/systemconfig.js"]
}

Lorsque µI18xContext.version est défini, les versionSources live ne le remplacent pas.

Optionnel — versionSources : utile seulement si vous ne définissez pas µI18xContext.version et voulez que le moteur résolve <version/> depuis du JSON sur disque (et le rafraîchisse sur GetTasksPayload sans réimporter le gulpfile). Formes prises en charge :

• "package.json" — utilise le champ npm "version"
• "RELEASES.json" — fichier style µGulp ; voir Versionnement (RELEASES.json) pour le schéma exact (releases[0].main / minor / revision)
• { "file": "config/version.json", "field": "version" } — n'importe quel fichier JSON + chemin de champ pointé

Exemple (JSON live optionnel uniquement — pas de version dans le gulpfile) :

{
	"metadataWatchFiles": ["package.json", "RELEASES.json"],
	"versionSources": ["RELEASES.json", "package.json"]
}

Logique : src/engine/ProjectMetadata.mjs ; les espaces réservés sont construits dans BuildSourceI18xContext.

Structure du projet

gulpfile.mjs             Project build: tests, theme CSS (µCSS), package + deploy
RELEASES.json            Version source (main/minor/revision, i18xe-ready info texts)
gulp-mu-gulp-api/        Standalone npm module: public task API
  src/index.mjs          Progress, text/color/font/select inputs, forms
  tests/                 The module's own node:test suite
skins/                   One directory per skin (neon-carbon is the default)
  neon-carbon/
    neon-carbon.µcss.mjs µCSS skin manifest (Carbon/Neon variables)
    neon-carbon.µ.css    Skin source → compiled into src/webview/skins/neon-carbon/
  ice-light/             Light frosted-glass skin (cool blue outward glow)
    ice-light.µcss.mjs   µCSS skin manifest (ice palette)
    ice-light.µ.css      Skin source → compiled into src/webview/skins/ice-light/
  ide-dark/              Plain IDE-aligned dark (VS Code–like, no neon/carbon)
  ide-light/             Plain IDE-aligned light companion
src/
  engine/                IDE-independent core (no VS Code APIs!)
    TaskEngine.mjs       Orchestrator: scan, preload, queue, events
    TaskWorkerPool.mjs   Pool of prewarmed worker processes
    ConcurrencyGuard.mjs Evaluates executionConcurrency/-Restrictions
    Diagnostics.mjs      Diagnosis engine (stack traces → concrete suggestions)
    PluginHost.mjs       Lifecycle hooks for plugins
    GulpfileDiscovery.mjs  Regex-based gulpfile discovery in the workspace
    ReleaseInfo.mjs      Release management: RELEASES.json, version strings, history
  worker/
    TaskWorker.mjs       Child process: imports the gulpfile, runs tasks
  bridge/
    gulp-ugulp-bridge.mjs  Public bridge: npm packages ↔ webview forms
  host/
    HostProtocol.mjs     Event/command names (the single host boundary)
    Daemon.mjs           Engine owner for sidecar hosts
    microgulp-serve.mjs  stdio NDJSON CLI (PhpStorm preparation)
  extension/
    extension.cjs        Thin VS Code / Cursor adapter (the only CJS module)
  webview/
    dashboard.css        Fallback stylesheet for fresh checkouts
    dashboard.js         TaskGrid, log streaming, forms, audio engine
    skins/<name>/dashboard.css  µCSS-generated skins (webview default: neon-carbon)
tests/                   node:test suites (unit + engine integration)
demo/
  gulpfile.mjs           Example gulpfile with every µGulp™ metadata tag
  run-demo.mjs           Headless engine smoke test (no IDE)
dev/
  prompts/               AI migration prompts (existing gulpfile → µGulp + i18x)
    OptimizeGulpfileForMicroGulp.md
    OptimizeGulpfileForMicroGulp.params.example.json

Principes d'architecture

• La couche moteur est libre d'IDE. src/engine et src/worker ne connaissent aucune API VS Code. La communication passe par des événements (moteur → hôte) et des commandes JSON simples (hôte → moteur). Porter vers PhpStorm (phase 2) est donc un simple échange d'adaptateur — le sidecar minimal npm run serve (src/host/microgulp-serve.mjs, NDJSON sur stdio) est déjà en place.
• Préchargement des tâches. Le TaskWorkerPool conserve des processus Node préchauffés dans lesquels le gulpfile a déjà été importé. Démarrer une tâche remet un worker chaud et recharge le pool en arrière-plan. Après une exécution le processus est jeté (état de module frais).
• Imports dynamiques. Les paquets npm lourds (mssql, docx-templates, makensis, …) ne doivent être chargés que dans le corps de la tâche via await import() — les imports statiques de premier niveau sont réservés à la logique cœur de l'orchestrateur.
• Langues. Les textes GUI sont en anglais américain et passent par String.i18xTrans() (câblage i18xe à suivre) ; commentaires de code en anglais ; manuels/documentation en allemand.

Localisation du tableau de bord

Le GUI du tableau de bord est livré avec des dictionnaires i18x groupés pour en-US (source), de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP et ko-KR. Choisissez la langue dans les réglages du tableau de bord (automatic suit la locale de l'hôte ou du navigateur). La sortie console du gulpfile utilise la même langue via MICROGULP_LANG dans le worker et les fichiers i18x/gulp/<lid>.json de votre projet. Le manuel utilisateur est un PDF dans la langue du tableau de bord.

Pour amorcer ou rafraîchir ces dictionnaires gulp sans serveur i18xe : Settings → Project i18x (gulp) → Scan & update i18x/gulp…. µGulp™ parse les phrases avec le scanner i18xe-sync (plus Log/Warn/LogError), conserve les traductions existantes, fusionne les définitions de format standard et écrit des satellites <lid>.status.json (missing / orphans) pour la traduction IA locale.

Layer	Who provides it	Today	Planned
Dashboard GUI	µGulp (extension)	en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR	More marketplace languages via the i18xe sync pipeline
Gulp tasks & logs	Your project	i18x/gulp/*.json next to the gulpfile	Same — consumer projects never ship i18x/prod
Hyphenation	µGulp webview assets	String.prototype.Hyphenation() with bundled <lid>.hyphen.json where present	Additional locales as hyphen data is synced from i18xe

Balises de contexte, formats obligatoires et feuille de route des langues : dev/docs/MicroGulpI18xProfile.md. Une connexion serveur i18xe live pour les dictionnaires GUI du tableau de bord reste optionnelle (voie 3) ; les dictionnaires gulp consommateurs utilisent le scan hors ligne ci-dessus.

Découverte des gulpfiles (configurable par regex)

µGulp™ remarque tout seul les changements de gulpfile sur le disque : un watcher de workspace (microgulp.watchGulpfiles, activé par défaut) rescane automatiquement après chaque changement et remplace les workers chauds par des neufs exécutant le code actuel. Pendant un scan, la liste des tâches affiche un indicateur de progression animé ; le tableau de bord n'a donc plus de bouton rescan — la commande µGulp: Rescan Tasks (palette de commandes) reste comme rafraîchissement forcé manuel. Si un gulpfile échoue à charger (erreur de syntaxe, module manquant), une bannière d'erreur refermable avec diagnostic et trace de pile apparaît directement dans le tableau de bord.

µGulp™ trouve les gulpfiles soit par un chemin unique, soit par un motif regex qui cherche dans tout le workspace :

• microgulp.gulpfilePattern — un regex JavaScript (insensible à la casse) testé contre le chemin relatif au workspace (notation POSIX avec /). Lorsqu'il est défini, chaque fichier correspondant est scanné ; les tâches sont groupées par source dans le tableau de bord. Exemple : (^|/)gulpfile\.(m|c)?js$ trouve gulpfile.mjs/.js/.cjs à la racine et dans chaque sous-dossier.
• microgulp.gulpfilePath — le chemin unique classique (défaut gulpfile.mjs). Utilisé seulement tant que gulpfilePattern est vide.

node_modules, .git et les dossiers cachés (.*) ne sont jamais descendus. Chaque gulpfile découvert reçoit son propre pool de workers chauds avec le dossier du gulpfile comme répertoire de travail, donc les sous-projets imbriqués avec chemins relatifs s'exécutent correctement. La logique de découverte vit indépendamment de l'IDE dans src/engine/GulpfileDiscovery.mjs et est donc aussi disponible pour la CLI et l'adaptateur JetBrains.

Lorsque plus d'un gulpfile correspond, la colonne de tâches de gauche affiche un en-tête de source par fichier de script (chemin relatif au workspace, p. ex. gulpfile.mjs, nested/gulpfile.mjs) ; les tâches de fichiers différents ne sont pas mélangées au niveau supérieur. Dans chaque source, les tâches s'imbriquent encore par leur chemin µGroup (Build/Production, …). Avec un seul gulpfile, l'en-tête est omis — seule l'imbrication µGroup s'applique. Si les gulpfiles scannés exportent des tâches mais aucun n'importe gulp-mu-gulp-api, le tableau de bord affiche un indice refermable vers le paquet npm et le prompt de migration IA.

Métadonnées µGulp™ sur une tâche Gulp

La forme recommandée est des balises préfixées µ en CamelCase (µDisplayName, µIcon, …) — elles sont invisibles pour la CLI gulp classique, donc les gulpfiles restent pleinement compatibles sur les systèmes sans µGulp™ (la CLI gulp adresse les tâches via function.displayName ; un joli nom avec des espaces casserait l'adressage des tâches là-bas) :

export async function BUILD_STYLES() { /* ... */ }
BUILD_STYLES.µDisplayName = 'Build Styles';
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.';
BUILD_STYLES.µTooltip = 'Runs the µCSS pipeline (sprites, fonts, sounds included).';
BUILD_STYLES.µIcon = '\u25A3';   // font symbol — or an image data URI:
// BUILD_STYLES.µIcon = 'data:image/svg+xml,%3Csvg ...';  (png/webp too)
BUILD_STYLES.µIconFont = 'ProjectIcons'; // optional — see Dashboard fonts below
BUILD_STYLES.µGroup = 'Build/Assets';                 // nested group (path syntax)
BUILD_STYLES.µOrder = 10;                             // sort position in the dashboard (ascending)
BUILD_STYLES.µExecutionConcurrency = true;            // false = exclusive
BUILD_STYLES.µExecutionRestrictions = { deny: ['CLEAN'] }; // parallel matrix
BUILD_STYLES.µKeyBinding = { key: 'ctrl+shift+B', mac: 'cmd+shift+B' }; // dashboard shortcut
BUILD_STYLES.µWatch = { files: ['skins/**/*.µ.css'] }; // optional file trigger
BUILD_STYLES.µAutoClose = -1;                         // keep the finished sector
BUILD_STYLES.µParameters = [                          // asked before the run
  { id: 'target', type: 'select', options: ['debug', 'release'], default: 'debug' },
];
// Windows only — show the UAC prompt when the host is not already elevated:
BUILD_STYLES.µRequiresElevation = true;
BUILD_STYLES.µElevationReason =
  'Modifies the Windows hosts file.<context="µElevationReason"/>'.i18xRegister();

µGroup assigne la tâche à un groupe imbriqué dans l'aperçu des tâches. La définition suit une syntaxe de chemin de répertoire : µGroup = 'Build/Production' crée le groupe Build avec le sous-groupe Production. Les groupes sont repliables dans le tableau de bord ; les tâches sans µGroup restent au niveau supérieur. L'affectation est optionnelle et purement visuelle — elle n'a aucun effet sur l'exécution ou la concurrence.

µOrder fixe la position de tri dans la colonne de gauche (entier croissant). Les tâches et groupes frères sont ordonnés par µOrder ; les tâches sans valeur apparaissent après toutes les tâches ordonnées (départage : nom d'affichage). Les groupes trient par le plus petit µOrder de leur sous-arbre.

Touches modificatrices sur un en-tête de groupe :

Action	Effect
Click	toggle the group
Ctrl+Click (Cmd+Click)	toggle every group on the same level
Alt+Click	toggle all groups

µRequiresElevation marque une tâche qui a besoin de droits Administrateur sous Windows (par exemple réécrire C:\Windows\System32\drivers\etc\hosts). Lorsque l'IDE tourne normalement, µGulp™ démarre un worker élevé unique et affiche le dialogue UAC habituel — vous n'avez pas à lancer Cursor ou VS Code en tant qu'Administrateur. Si le processus hôte est déjà élevé, le pool de workers chauds est utilisé comme d'habitude. Sur les plateformes non Windows le drapeau est ignoré. µElevationReason optionnel apparaît dans l'infobulle de la tâche (badge ⛿ dans le tableau de bord).

Raccourcis de tâche (µKeyBinding)

Une tâche peut porter son propre accord clavier. L'accord fonctionne tant que le tableau de bord a le focus — VS Code et PhpStorm ne peuvent pas enregistrer de raccourcis à l'exécution, donc µGulp™ les gère lui-même au lieu de prétendre posséder des touches globales de l'IDE.

BUILD.µKeyBinding = 'ctrl+shift+B';                      // same chord everywhere
DEPLOY.µKeyBinding = { key: 'ctrl+alt+D', mac: 'cmd+alt+D' };
STOP.µKeyBinding = { key: 'ctrl+shift+Escape' };         // named keys: F1…F24, Escape, Tab, Space, arrows, …

Part	Accepted
Modifiers	ctrl, control, alt, option, shift, meta, cmd, command, super, win
Keys	single characters (b, 7, +), F1–F24, Escape/Esc, Enter, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up/Down/Left/Right
Platform keys	key (fallback), mac, win, linux — the matching platform wins, key fills the rest

cmd correspond à la touche Command sur macOS et à Ctrl ailleurs, donc un seul accord key reste utilisable sur toutes les plateformes. L'accord apparaît comme un badge à côté du nom de la tâche ; si deux tâches revendiquent le même accord, les deux badges deviennent ambre et l'infobulle le dit (µGulp™ refuse de deviner laquelle vous visiez).

Pour un raccourci vraiment global à l'IDE, liez vous-même la commande µGulp: Run Task — elle prend la tâche comme argument :

// keybindings.json (VS Code / Cursor)
{ "key": "ctrl+shift+f9", "command": "microgulp.runTask", "args": { "task": "gulpfile.mjs::BUILD_STYLES" } }

Sans args la commande ouvre une sélection rapide des tâches scannées.

Paramètres de tâche déclaratifs (µParameters)

Au lieu de demander une entrée depuis le corps de la tâche, une tâche peut déclarer ce dont elle a besoin. µGulp™ affiche un formulaire avant le démarrage, mémorise les réponses pour la prochaine fois et transmet les valeurs à la tâche via l'environnement :

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 = {
  submitLabel: 'Start Deploy<context="button text"/>'.i18xRegister(),
  fields: [
    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging',
      label: 'Target<context="task parameter"/>'.i18xRegister() },
    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
    { id: 'servers', type: 'checkbox', options: ['a', 'b'], required: true }, // submit stays disabled until ≥1
    { id: 'dryRun', type: 'boolean', default: true },
    { id: 'notify', type: 'boolean', default: false,
      visibleWhen: { dryRun: false } },   // only when not a dry run
    { id: 'token', type: 'password' },   // never stored, never logged
  ],
};

Un simple tableau de champs fonctionne encore. L'enveloppe ajoute le chrome du formulaire (title, submitLabel) ; µParameterSubmitLabel sur la tâche est une alternative équivalente pour le texte du bouton.

Field	Meaning
id	required; must be env-var safe ([A-Za-z_][A-Za-z0-9_]*)
type	text (default), textarea, password, number, range, boolean (slide switch), checkbox (multi-select), radio, select, font, color
label, description, placeholder	shown in the form (i18x via .i18xRegister())
default	pre-filled value; a remembered answer from the last run wins
options	['a','b'], [{ value, label, disabled }] or { a: 'Label A' }
required, pattern, minLength, minSelected	validated live in the dashboard — the submit button stays disabled until every visible rule passes (required on a checkbox means at least one option)
min, max, step, rows	numeric / textarea details
remember	false keeps the value out of the store (implicit for password)
visibleWhen	show the field only while other answers match — e.g. { dryRun: false } or { servers: 'prod' } (multi-select: contains). Hidden fields are not validated; missing answers fall back to default
submitLabel / title	form wrapper keys (or µParameterSubmitLabel / µParameterTitle on the task) — i18x via .i18xRegister()

Les valeurs arrivent comme MICROGULP_PARAMS (JSON) plus un MICROGULP_PARAM_<ID> plat par paramètre, donc les étapes shell dans une tâche peuvent aussi les lire. GetParameters() / GetParameter('target', 'staging') depuis gulp-mu-gulp-api les parse ; sous la CLI gulp simple vous pouvez fournir les mêmes variables à la main :

MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY

Les réponses sont mémorisées par tâche dans .microgulp/parameters.json et préremplissent le formulaire suivant. Les mots de passe et les valeurs remember: false ne sont ni stockés ni écrits dans la transcription, l'historique ou le tableau de bord — ils apparaissent comme ••••. Le journal d'exécution et l'entrée d'historique enregistrent les valeurs avec lesquelles une exécution a démarré, pour que vous puissiez voir ensuite ce qui a été répondu. Les tâches élevées (µRequiresElevation) ne peuvent pas afficher de formulaire depuis leur processus à sens unique, elles s'exécutent donc avec les valeurs mémorisées plutôt que les défauts déclarés.

Tâches watch / déclenchement (µWatch)

Une tâche peut se lancer elle-même lorsque les fichiers qui l'intéressent changent :

BUILD_CSS.µWatch = 'src/**/*.µ.css';                  // shorthand
BUILD_CSS.µWatch = {
  files: ['src/**/*.µ.css', 'skins/*/manifest.json'], // globs, relative to the gulpfile
  ignore: ['**/*.tmp'],
  debounceMs: 300,                                    // quiet time after the last change
  autoStart: false,                                   // arm as soon as the gulpfile is scanned
  parameters: { target: 'debug' },                     // fixed µParameters for triggered runs
};

La surveillance est opt-in par tâche : un basculeur ◉ apparaît à côté du nom de la tâche (cyan lorsqu'armé) sauf si la déclaration dit autoStart: true. Les globs prennent en charge **, *, ?, {a,b} et les classes de caractères ; node_modules, .git, .microgulp, .idea et .vscode ne sont jamais surveillés.

Gardes-fous, parce qu'une tâche de build qui écrit dans son propre ensemble de surveillance tournerait autrement indéfiniment :

• une rafale d'événements de changement devient une exécution (debounce)
• pendant qu'une exécution de la tâche est active, au plus une exécution de suivi est mise en file
• plus de 20 exécutions déclenchées en une minute suspendent le watcher (bascule ambre, l'infobulle explique pourquoi) ; l'éteindre et le rallumer le réarme

Une exécution déclenchée nomme le fichier qui l'a lancée dans son journal (Triggered by src/a.css), et n'ouvre jamais de formulaire de paramètres — un déclencheur utilise les valeurs épinglées ou mémorisées, donc rien n'attend un humain qui ne regarde pas.

Garder une exécution terminée ouverte (µAutoClose)

Les secteurs terminés se ferment par défaut après 30 secondes (Settings → Finished Runs). Une tâche peut le remplacer :

SHOW_OUTPUT.µAutoClose = -1;   // garder le secteur (jamais de fermeture auto)
QUICK.µAutoClose = 8;          // fermer après 8 secondes

Valeur	Signification
omis / true	réglage du tableau de bord (30 s par défaut)
-1, false, 0	ne pas fermer automatiquement cette tâche
entier positif	fermer après ce nombre de secondes (remplace le délai du tableau de bord)

La puce jaune de compte à rebours permet toujours de garder le secteur. µAutoClose est un nombre ou un booléen — pas de .i18xRegister().

Emplacements d'erreur cliquables

Les références de fichier dans le journal d'exécution deviennent des liens : src/engine/TaskEngine.mjs:412:9, at Object.<anonymous> (gulpfile.mjs:88:15), sorties tsc/eslint et file(12,7) style MSBuild. Un clic (ou Entrée dessus) ouvre ce fichier à cette ligne et colonne dans l'éditeur hôte — un onglet éditeur dans VS Code/Cursor, l'éditeur IDE via le pont JCEF dans PhpStorm.

Le chemin est résolu côté hôte d'abord contre le répertoire gulpfile de l'exécution, puis la racine du workspace, donc les workspaces multi-gulpfile sautent à la bonne copie d'un nom ambigu. Seuls les fichiers existants avec des extensions de type source sont ouverts ; URLs, horodatages et numéros de version sont laissés tels quels.

Packs de thème (ZIP)

Les thèmes de tableau de bord personnalisés peuvent être distribués comme packs ZIP et installés globalement (pour l'utilisateur sous ~/.microgulp/themes/, surcharge avec MICROGULP_THEMES_DIR). Ils sont indépendants du workspace du projet.

Disposition du pack (précompilé — aucune source µCSS requise) :

manifest.json     // { "id", "displayName", "version", "appearance": "dark"|"light" }
dashboard.css
imgs/…            // optional graphics / cursors
fonts/…           // optional
snds/…            // optional µAU atlas: microgulp.sounds.weba (or .wav/.mp3) + microgulp.sounds.json

Dans le tableau de bord : Settings → Appearance → Import theme ZIP…. Les skins intégrés restent dans le sélecteur ; Automatic mappe toujours vers Neon Carbon / Ice Light. Retirez un pack avec Remove selected pack.

Depuis ce dépôt vous pouvez empaqueter un skin compilé après npm run theme :

node dev/tools/pack-theme.mjs ide-dark
# → packages/microgulp-theme-ide-dark.zip

Atlas sonore (µAU)

Les signaux du tableau de bord sont construits depuis dev/media/final/sounds/microgulp/ : default/ est la base pour chaque skin ; des dossiers <skin-id>/ optionnels surchargent par radical de nom de fichier. Les atlas sont livrés en WebA (WebM/Opus audio seul, microgulp.sounds.weba). Les échantillons identiques sont dédupliqués. Catalogue complet : dev/docs/MicroGulpSoundSchema.md.

PlaySignal('success'|'error'|'attention') mappe vers taskSuccess / taskFailed / requestAlert ; PlaySound utilise les noms du schéma directement.

Polices du tableau de bord (icônes de tâche et journal)

Les polices de projet sont indépendantes des skins intégrés. Enregistrez-les dans le gulpfile (préféré) ou via microgulp.config.json / le réglage microgulp.dashboardFonts :

import { RegisterDashboardFont } from 'gulp-mu-gulp-api';

RegisterDashboardFont({
  id: 'ProjectIcons',
  file: 'assets/task-icons.woff2',   // relative to the gulpfile directory
  usage: 'task-icons',               // or 'log' / 'all'
});

// Or declarative:
export const µDashboardFonts = [
  { id: 'ProjectLog', file: 'assets/log.woff2', usage: 'log' },
];

BUILD.µIcon = '\uE101';
BUILD.µIconFont = 'ProjectIcons';     // optional when a single task-icons font is registered

usage: 'task-icons' habille les entrées glyphe µIcon (la première police enregistrée est le défaut ; µIconFont surcharge par tâche). usage: 'log' fixe la police du journal du secteur d'exécution. Les fichiers doivent rester sous le workspace (woff2 / woff / ttf / otf).

Cascade de repli par propriété : µDisplayName → ugulp.displayName (objet namespace) → displayName (propre champ de Gulp) → nom d'export. executionRestrictions prend en charge deny (gagne toujours) et allow (liste blanche : tout ce qui n'est pas listé est interdit).

Les chaînes de métadonnées de tâche utilisent i18x avec la balise de contexte à l'intérieur de la phrase. .i18xRegister() n'enregistre la phrase que pour i18xe-sync et le dictionnaire du projet — elle renvoie le texte source inchangé ; la traduction a lieu plus tard lorsque le tableau de bord rend les métadonnées (TransProperty() via i18x-catalog), avec des espaces réservés comme <version/> remplis depuis µI18xContext. Pour la sortie console, utilisez .i18xTrans() ou Log()/Warn()/LogError(), qui traduisent immédiatement à l'exécution (espaces réservés inclus) :

BUILD_STYLES.µDisplayName = 'Build Styles<context="µDisplayName"/>'.i18xRegister();
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();

Balises de contexte, formats obligatoires et plan de langues marketplace : dev/docs/MicroGulpI18xProfile.md.

Migration de gulpfile assistée par IA

Pour migrer un gros gulpfile existant (sortie console, métadonnées de tâche, dictionnaires i18x/gulp, optionnellement µKeyBinding / µParameters / µWatch / µAutoClose) utilisez le prompt maintenu dans le dépôt :

File	Purpose
dev/prompts/OptimizeGulpfileForMicroGulp.md	Copy-paste prompt for Cursor, Claude, ChatGPT, …
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json	Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version)

Workflow

1. Copiez l'exemple de params à la racine de votre projet comme microgulp-optimize.params.json et renseignez projectRoot, gulpfilePath, supportedLanguages (p. ex. en-US, de-DE, zh-CN), gulpMuGulpApiVersion (^0.4.0 ou plus récent), microGulpMinVersion (0.7.0), et githubRepoUrl / githubRef (défaut : https://github.com/mamekudz/microGulp, V0.7.0 ou main).
2. Ouvrez le markdown du prompt, remplacez la table {{PLACEHOLDER}} par vos valeurs (ou joignez le fichier params et le gulpfile dans Cursor).
3. Laissez l'IA exécuter la migration. L'étape 0 du prompt est obligatoire : une sauvegarde horodatée du gulpfile (p. ex. gulpfile.mjs.20260703-142559.bak) avant toute modification.
4. Vérifiez avec node --check gulpfile.mjs, testez les tâches dans le tableau de bord µGulp (y compris les nouveaux raccourcis tant que le tableau de bord a le focus), puis validez gulpfile.mjs, i18x/gulp/*.json et package.json.

Les projets consommateurs n'ont besoin que de i18x/gulp/<lid>.json — pas de i18x/prod. Le prompt est mis à jour avec les releases µGulp ; consultez ce dépôt pour la dernière version avant de migrer. Il couvre les règles i18x (register vs. translate, pas de µMeta) et l'UX déclarative : µKeyBinding du tableau de bord (pas global à l'IDE sauf si l'utilisateur lie microgulp.runTask), µParameters / GetParameters(), µWatch et µAutoClose.

API publique des tâches (gulp-mu-gulp-api)

Les gulpfiles tiers et les paquets npm dans le flux utilisent les fonctions étendues du tableau de bord via le module npm autonome **gulp-mu-gulp-api** (vit comme son propre projet sous gulp-mu-gulp-api/, publié sur npm séparément) :

import { ReportProgress, RequestTextInput, RequestColorInput, RequestForm, ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

export async function BUILD_THEME() {
    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
    let title = await RequestTextInput({ label: 'Product title', validate: { required: true, minLength: 3 } });
    let ok = await ShowConfirmMessage({
        title: 'Overwrite theme?',
        message: 'Existing skin files will be replaced.',
        presentation: 'webview',
    });
    if (ok.button !== 'yes') return;
    for (let step = 1; step <= 10; step++) {
        // ... work ...
        ReportProgress(step / 10, 'compiling theme');   // determinate neon progress bar in the sector
    }
    await ShowModalMessage({
        variant: 'info',
        title: 'Theme ready',
        message: 'Skin files written.',
    });
}

Le module est sans dépendances et parle au moteur directement via le canal IPC du worker µGulp™ (détection via IsMicroGulp() / IsµGulp()). Sans µGulp™ tout se dégrade proprement : la progression va au terminal, les entrées via readline (TTY) ou valeurs par défaut (CI). Détails dans gulp-mu-gulp-api/README.md. Le module interne src/bridge/gulp-ugulp-bridge.mjs reste le transport bas niveau ; les nouveaux consommateurs doivent utiliser gulp-mu-gulp-api.

Dialogues modaux (ShowModalMessage)

Depuis V0.5.29 (API : gulp-mu-gulp-api 0.3.11+), les tâches peuvent afficher des dialogues modaux bloquants — pour des accusés de réception, des avertissements avant de continuer, ou des confirmations Oui/Non et OK/Annuler. Utilisez-les avec parcimonie (pas pour les lignes de journal de routine) ; préférez Log() / les helpers de journal structuré pour la sortie normale.

Panneaux de verre Webview (défaut)

Lorsque presentation est webview (le défaut), les modaux s'affichent dans le tableau de bord µGulp comme panneaux de verre style AiDPix/Oxyd :

Feature	Detail
Frame	9-slice glasspanel.png (glasspanel-ice.png in the ice-light skin)
Variants	info (turquoise header), warning, error — colored header bar per variant
Buttons	Carbon-styled actions; primary button highlighted
Overlay	Scroll the mouse wheel over the dimmed backdrop to adjust overlay brightness (8–88 %) ; long message bodies scroll inside the panel
Keyboard	Escape → cancel/no (or first button); Enter → primary button

Implémentation : src/webview/WebviewModal.js, src/webview/webview-modal.css (chargés par le webview VS Code et le tableau de bord HTTP).

API

import { ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

// Single acknowledgment (default button: OK)
await ShowModalMessage({
    variant: 'warning',          // 'info' | 'warning' | 'error'
    title: 'Disk almost full',
    message: 'Less than 1 GB free on the build drive.',
    presentation: 'webview',     // optional — see below
});

// Yes/No confirmation (default style)
let answer = await ShowConfirmMessage({
    title: 'Overwrite output?',
    message: 'Existing files in dist/ will be replaced.',
});
if (answer.button !== 'yes') return;

// OK/Cancel preset
let discard = await ShowConfirmMessage({
    title: 'Discard changes?',
    message: 'Unsaved theme tweaks will be lost.',
    style: 'ok-cancel',          // default: 'yes-no'
});

Les deux helpers renvoient Promise<{ button: string }> — p. ex. 'ok', 'yes', 'no', 'cancel', ou des ids de bouton personnalisés depuis ShowModalMessage({ buttons: [{ id: 'retry', label: 'Retry', primary: true }] }).

Repli CLI (gulp simple, CI, pas de TTY) : sortie console entre crochets et le bouton primaire/défaut — pas d'invite bloquante.

Emplacement du modal (presentation)

Value	Behavior
webview	In-dashboard glass panel (default)
ide	Native VS Code / Cursor modal (showInformationMessage / showWarningMessage / showErrorMessage with { modal: true })
auto	Native IDE dialog when the Extension Host is available; otherwise the webview glass panel

Le presentation par appel surcharge le défaut de l'hôte.

Défauts hôte

Host	Setting
VS Code / Cursor	Extension setting microgulp.modalPresentation (webview | ide | auto, default webview)
Browser demo / PhpStorm JCEF	Dashboard Settings → Modal presentation (same three values)

Repli : PhpStorm et un tableau de bord navigateur utilisent toujours le panneau de verre webview — presentation: 'ide' y est mappé vers webview. Seul l'Extension Host VS Code/Cursor peut afficher des modaux IDE natifs.

Essayer les démos

Après µGulp: Open Sample Project, le tableau de bord liste un groupe Demo :

Task	Effect
DEMO_MODAL_DIALOGS	All variants + Yes/No + OK/Cancel with presentation: 'webview'
DEMO_IDE_MODAL_DIALOGS	Same flow with presentation: 'ide' (native modals in Cursor/VS Code; webview fallback in PhpStorm / the browser)

Détails API supplémentaires : gulp-mu-gulp-api/README.md.

Certification µGulp ready

Les modules npm dont le gulpfile racine est pleinement intégré au tableau de bord µGulp peuvent afficher le badge µGulp ready sur leur README npm et leurs pages projet.

Requirement	Detail
Gulpfile	Exported tasks carry µGulp metadata (µDisplayName, µDescription, µGroup, …)
API	Uses gulp-mu-gulp-api for logging, progress and optional dashboard features
CLI fallback	Tasks remain runnable with plain gulp / npx gulp when µGulp is not installed
Badge asset	Canonical PNG: media/microgulp-ready.png in the µGulp repo. npm README: absolute raw URL (npm rewrites relative paths to microCSS/HEAD/... even inside HTML). Example: <a href="https://microgulp.dev"><img src="https://microgulp.dev/assets/media/microgulp-ready.png" alt="µGulp ready" width="150"></a>
package.json	Optional "microgulp": { "ready": true, "certifiedSince": "<semver>" } for machine-readable discovery

Modules certifiés

npm package	Since	Notes
gulp-mu-gulp-api	0.3.11	Official task API — Log, ReportProgress, i18x console layer, dashboard forms, ShowModalMessage / ShowConfirmMessage; npm README badge since 0.3.3
gulp-mu-css (µCSS™)	2.5.15	Monorepo root gulpfile.mjs with full task metadata, i18x/gulp/ (en-US, de-DE) and LogBuildDebugReport on demo builds; npm README badge via absolute raw URL since 2.5.14
gulp-mu-ps (µPS)	1.3.5	Test/render tasks in the shared root gulpfile (TEST_MICROPS, RENDER_EXAMPLES, …)
gulp-mu-ft (µFT)	0.1.5	Test task TEST_MICROFT in the shared root gulpfile
gulp-mu-au (µAU)	0.1.6	Test task TEST_MICROAU in the shared root gulpfile

Pour demander la certification, migrez votre gulpfile avec dev/prompts/OptimizeGulpfileForMicroGulp.md et ouvrez une issue ou une PR dans le dépôt µGulp ou du module.

Versionnement (RELEASES.json)

Ce fichier est le format de release de µGulp lui-même — la source unique de vérité pour ce dépôt. Les projets consommateurs n'ont pas besoin d'un RELEASES.json ; ils gardent généralement leur version produit dans leur propre config (et l'exposent via µI18xContext.version). Un versionSources: ["RELEASES.json"] optionnel n'aide que si vous adoptez cette même disposition JSON.

Chaque entrée de release porte main/minor/revision, un horodatage, un drapeau beta et une liste de textes d'info. Les textes d'info portent la balise de contexte i18x <context="release info"/> et sont enregistrés via String.i18xRegister(), donc le moteur i18xe peut les traduire automatiquement.

Schéma (release la plus récente en premier — releases[0] est actuel) :

{
    "releases": [
        {
            "main": 0, "minor": 2, "revision": 0, "date": "2026-07-02 15:30", "beta": false,
            "info": [ "Release management added<context=\"release info\"/>" ]
        }
    ]
}

Lorsque versionSources inclut "RELEASES.json", le moteur résout <version/> en "main.minor.revision" depuis releases[0] (p. ex. "0.2.0").

Le module src/engine/ReleaseInfo.mjs fournit :

• GetVersionString() / GetFullVersionString() — "0.2.0" ou "0.1.4ß" (suffixe ß pour les builds bêta).
• GetVersionHistoryText({ maxReleases, includeBeta }) — l'historique complet comme chaîne formatée pour la console (tâche SHOW_VERSION_HISTORY ou npm run history).
• BUILD_PACKAGE synchronise la version package.json et la ligne de version en tête de ce README depuis RELEASES.json automatiquement et la frappe dans le nom d'artefact (microgulp_V0.2.0.vsix, bêtas avec suffixe _beta). Une nouvelle release n'a besoin que d'une nouvelle entrée en tête de RELEASES.json.

Compilation du projet (gulpfile.mjs)

Le projet se compile lui-même via son propre gulpfile (dogfooding : il tourne dans le tableau de bord µGulp™, via la CLI gulp, via les extensions IDE Gulp classiques et headless) :

Invocation	Task	Purpose
npm test	RUN_TESTS	node:test suites in tests/ (unit + engine integration with real worker processes)
npm run theme	CREATE_THEME_DATA	Compiles every skins/<name>/<name>.µ.css via µCSS (gulp-mu-css BuildSkin) into src/webview/skins/<name>/dashboard.css (default: neon-carbon)
npm run package	BUILD_PACKAGE	Stages the extension into tmp/package/ and creates the .vsix in packages/ (also refreshed as microgulp_latest.vsix)
npm run deploy	DEPLOY_EXTENSION	Automated update cycle: build the .vsix and install it via cursor --install-extension (reload the window afterwards)
npm run build	BUILD_ALL	Full pipeline: clean → tests → theme → package
npm run history	SHOW_VERSION_HISTORY	Prints the formatted version history from RELEASES.json to the console
npm run accounts	ACCOUNTS	Read-only listing of production LICENSE_KV registrations (--status, --edition; token from CLOUDFLARE_API_TOKEN or website/.env)
npm run website	BUILD_WEBSITE	Turns README language sections into website/ (all languages selectable; / follows the browser language)
npm run website:deploy	DEPLOY_WEBSITE	Builds, tests and publishes website/ to Cloudflare Worker microgulp-web (microgulp.dev; local Wrangler login)
npm run backup	BACKUP_TO_NAS	Incremental robocopy mirror to Z:\\Projects\\microGulp (override with MICROGULP_NAS_BACKUP)
—	PUBLISH_API	Publishes gulp-mu-gulp-api to npm (runs its tests first; npm login required)
—	CLEAN	Removes tmp/ and packages/ (exclusive, write lock)

Notes :

• gulp-mu-css est câblé comme dépendance file: locale sur C:\Projects\microCSS\gulp-mu-css et — comme chaque paquet lourd — n'est chargé que dans le corps de la tâche via await import().
• BUILD_PACKAGE produit un vrai .vsix une fois @vscode/vsce installé (npm i -D @vscode/vsce) ; sans vsce la tâche se rabat sur un zip du dossier de staging.
• Les skins sont autonomes : un répertoire par skin sous skins/ (p. ex. skins/neon-carbon/, skins/ice-light/, skins/ide-dark/), chacun avec un manifeste <name>.µcss.mjs et une source <name>.µ.css du même nom. CREATE_THEME_DATA découvre et construit chaque skin ; neon-carbon (sombre) est le défaut et ice-light livre un compagnon verre dépoli clair. ide-dark / ide-light sont des surfaces simples style VS Code sans tissage carbon ni pouls néon. Des skins supplémentaires/utilisateur peuvent être déposés comme répertoires frères. Le sélecteur de skin du tableau de bord (Settings → Appearance) offre un mode Automatic qui suit le thème clair ou sombre IDE/OS (mappe vers ice-light / neon-carbon).
• Le webview préfère automatiquement le skin défaut généré (src/webview/skins/neon-carbon/dashboard.css) ; le dashboard.css écrit à la main reste comme repli pour les checkouts frais.
• L'en-tête du tableau de bord affiche la marque microscope jaune (baselogo.svg) via inlining data-URI µCSS à côté du titre néon µGulp™ (background-image: µ(DataUri("imgs/baselogo.svg"))). La source unique de vérité pour les assets artistiques finis est dev/media/final/ ; le build synchronise media/logo.png (icône d'extension), media/logo_readme.png (README), src/webview/skins/<name>/imgs/baselogo.svg (tableau de bord) et jetbrains/resources/icons/baseoutlinelogo.svg (fenêtre d'outils JetBrains + liste de plugins) depuis là.

Ce dépôt livre aussi demo/gulpfile.mjs pour le développement local :

npm run demo          # headless engine smoke test
npm run demo:web      # browser dashboard (microgulp-serve --http)
npm run demo:ide      # Extension Development Host with demo/ as the workspace

F5 dans VS Code/Cursor (configuration de lancement "Run µGulp Extension") ouvre le même workspace de démo.

Essayer

Extension installée : Palette de commandes → µGulp: Open Sample Project (JetBrains : Tools → µGulp: Open Sample Project). Cela copie un gulpfile d'exemple avec des tâches Demo et Build (progression, formulaires, journaux structurés, sons, modaux) vers ~/.microgulp/sample et l'ouvre. Puis µGulp: Open Dashboard. Le manuel utilisateur est Settings → Handbook (ou µGulp: Open Handbook) ; toutes les langues du tableau de bord y sont listées.

Manuels PDF : Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어

Licence

µGulp™ (extension, moteur, tableau de bord, adaptateur JetBrains) est un logiciel propriétaire — voir LICENSE. Vous pouvez utiliser les binaires distribués gratuitement ; copier, modifier ou redistribuer le code source n'est pas autorisé.

Le paquet npm compagnon gulp-mu-gulp-api reste sous la licence MIT afin que les tâches Gulp puissent l'adopter sans restrictions.

Feuille de route / points ouverts de ce brouillon

Livré dans V0.5.0

• [x] Couche i18x dans le webview : réglage de langue (automatic/en-US/de-DE/zh-CN/fr-FR/es-ES/ru-RU/ja-JP/ko-KR), chaînes GUI taguées contexte, définitions de format reprises du serveur i18xe — la connexion directe au serveur i18xe suit plus tard
• [x] Métadonnées de tâche µ : .i18xRegister() enregistre les phrases pour i18xe/tableau de bord ; traduction et espaces réservés au rendu du tableau de bord via i18x-catalog + µI18xContext ; console via .i18xTrans() / Log()
• [x] API publique des tâches **gulp-mu-gulp-api** sur npm (progression, son/parole, formulaires interactifs avec replis CLI ; IsMicroGulp, InstallStringExtensions)
• [x] Bibliothèques de prompts héritées (inquirer, gulp-prompt, prompts) redirigées vers les formulaires du tableau de bord sans modifier les gulpfiles
• [x] Contrôles de formulaire étendus du tableau de bord (radio, range, textarea, password, number, date/time, file, checkbox multi-sélection)
• [x] Réglages du tableau de bord (contrôle acoustique, sortie vocale, rappel de formulaire, gestion des erreurs, langue)
• [x] Rendu console dans les secteurs de tâche (couleurs ANSI, écrasement de ligne de progression \r, horodatages)
• [x] Historique persistant des tâches et redirection de journal vers fichiers (.log brut + .ndjson structuré, index history.ndjson, rétention, panneau d'historique du tableau de bord)
• [x] microgulp.config.json pour les défauts équipe/CLI (réglages IDE PhpStorm + réglages d'extension VS Code ont priorité lorsqu'ils sont définis)
• [x] Ordre de tri des tâches du tableau de bord via µOrder (croissant ; groupes par minimum du sous-arbre)
• [x] Phase 2 : adaptateur JetBrains — fenêtre d'outils JCEF + sidecar Node + tableau de bord HTTP/SSE + Settings → Tools → µGulp (tous les IDEs basés sur IntelliJ)
• [x] Élévation UAC Windows optionnelle par tâche (µRequiresElevation, µElevationReason) — l'IDE reste non-admin
• [x] Localisation du tableau de bord documentée : en-US / de-DE / zh-CN / fr-FR / es-ES / ru-RU / ja-JP / ko-KR groupés ; les projets consommateurs ne fournissent que i18x/gulp
• [x] Tableau de bord multi-skin (Neon Carbon, Ice Light, IDE Dark/Light) + packs de thème ZIP globaux (import Appearance ; sons/graphismes optionnels)
• [x] Atlas sonores µAU par thème (default/ + surcharges de skin, déduplication PCM) ; catalogue dans dev/docs/MicroGulpSoundSchema.md
• [x] Polices de projet pour icônes de tâche / journal d'exécution (RegisterDashboardFont, µIconFont, dashboardFonts ; gulp-mu-gulp-api 0.3.12)
• [x] Raccourcis de tâche (µKeyBinding, accords par plateforme, badge de conflit) + µGulp: Run Task pour les raccourcis globaux de l'IDE
• [x] Paramètres de tâche déclaratifs (µParameters, GetParameters(), réponses mémorisées, secrets masqués)
• [x] Tâches watch / déclenchement (globs µWatch, debounce, disjoncteur d'emballement, bascule du tableau de bord)
• [x] Fermeture automatique par tâche (µAutoClose : -1 garder ouvert, secondes positives, sinon réglages)
• [x] Emplacements d'erreur cliquables dans le journal d'exécution (onglet éditeur VS Code, pont JCEF PhpStorm)
• [x] Matrice CI sur Windows / Linux / macOS sous Node 22 et 24
• [x] Synchronisation hors ligne des dictionnaires i18x/gulp dans le tableau de bord (parseur i18xe-sync, dialogue de langue cible, formats standard, <lid>.status.json pour la traduction IA)

Encore ouvert

• [ ] Documenter µLib (microLib), puis l'adopter comme couche utilitaire dans µGulp (i18x aujourd'hui est un sous-ensemble webview local)
• [ ] Connexion i18xe-server directe : synchronisation de traduction live au lieu des dictionnaires groupés
• [ ] Étendre GUI.mjs de µLib avec des contrôles spéciaux supplémentaires pour les formulaires du tableau de bord
• [ ] Finition visuelle du tableau de bord webview
• [ ] Étendre le skin µCSS : ajouter la police de symboles et les sprites au manifeste
• [ ] Sortie vocale via i18xe (les échantillons d'atlas remplacent déjà les bips WebAudio lorsqu'ils sont présents)
• [x] Plugin JetBrains : Settings → Tools → µGulp (options moteur)
• [ ] Distribution JetBrains Marketplace (reportée — installation ZIP locale seulement pour l'instant)
• [ ] Publier l'extension VS Code/Cursor sur un marketplace (reporté — livrer via GitHub Releases / packages/*_latest.* pour l'instant)

---

Español

Rock your Gulp!

µGulp™, el orquestador interactivo de tareas de latencia casi nula, con visuales ricos, controles webview y retorno de audio — se entrega como extensión IDE en tres ediciones (VS Code / Cursor registrado, VS Code / Cursor Free, IDEs JetBrains) con un panel webview Carbon/Neon.

Destacados

µGulp™ se entrega como µGulp™ (VS Code / Cursor), µGulp™ Free (VS Code / Cursor) y µGulp™ para IDEs JetBrains (IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip y otros IDEs basados en IntelliJ). El reparto siguiente es el plan actual y aún puede cambiar antes del lanzamiento público en el marketplace. No instale la extensión VS Code registrada y µGulp™ Free juntas — comparten los mismos IDs de comando. La edición VS Code registrada debe registrarse antes de ejecutar tareas — o desinstálela y use µGulp™ Free.

	µGulp™ VS Code / Cursor	µGulp™ Free VS Code / Cursor	µGulp™ JetBrains IDEs
Precio (mes / año)	0 € / $0	0 € / $0	0 € / $0
Panel de tareas, preload, i18x, parámetros, µWatch, historial	sí	sí	sí
Licencia / registro	obligatorio	ninguno	ninguno
Skins (Neon Carbon, Ice Light, IDE Dark / Light, Automatic)	sí	IDE Dark / Light según el tema del IDE (no seleccionable)	sí
Packs ZIP de tema personalizados	sí	—	sí
Motor de diagnóstico	sí	—	sí
Elevación UAC de Windows	sí	—	sí
Ajustes del host	microgulp.*	microgulp.*	Settings → Tools → µGulp
Marketplace (ficha aún no pública)	VS Code · Open VSX	VS Code · Open VSX	JetBrains (de.amekudzi.microgulp)

Todas las ediciones son actualmente gratuitas (0 € / $0 al mes y al año). Los puntos siguientes describen el producto completo. Free sigue el tema IDE/OS con IDE Dark / IDE Light (sin selector Appearance) y omite packs de tema, diagnóstico y elevación.

• Workers precargados — procesos Node calientes con el gulpfile ya importado; latencia de clic a ejecución casi nula (evita los escaneos de arranque en frío del software antivirus)
• Lista de tareas agrupada con iconos y textos localizables — anide tareas con rutas µGroup (Build/Production), grupos plegables, µIcon (glifo o imagen) y µDisplayName / µDescription / µTooltip registrados con .i18xRegister() y traducidos en vivo vía i18x-catalog; µOrder ordena tareas y grupos
• Rejilla de tareas en paralelo — varios sectores de ejecución aislados uno al lado del otro, cada uno con su propio flujo de registro
• Panel web — registros ANSI en color en vivo, salida filtrada, barras de progreso determinadas, formularios ricos para la entrada del usuario (texto, color, fuente, select, multiselect, …)
• Vigilancia en vivo del gulpfile — el watcher del workspace reescanea al guardar y sustituye automáticamente los workers obsoletos
• Sin atadura — los metadatos con prefijo µ son invisibles para la CLI gulp clásica y cada helper de API tiene un fallback CLI, así que el mismo gulpfile se ejecuta sin cambios con, sin y después de µGulp™ (detalles)
• Tareas gulp listas para i18n — .i18xRegister() registra frases de metadatos (etiquetas de contexto incrustadas en nombres visibles, descripciones, tooltips, grupos) en el diccionario del proyecto y devuelve la fuente en inglés americano sin cambios; el panel las traduce después vía i18x-catalog con marcadores (version, project, …) de µI18xContext. La salida de consola usa .i18xTrans() / Log() para traducción inmediata, incluida la resolución de marcadores
• Localización del panel — diccionarios GUI empaquetados para en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP y ko-KR (ajustes: automático o locale fija); más idiomas previstos vía i18xe sync. El manual de usuario se entrega como PDF en el idioma del panel
• Sincronización de diccionarios para sus gulpfiles — Settings → Project i18x (gulp) escanea las fuentes con el parser i18xe-sync, escribe i18x/gulp/<lid>.json para los idiomas que elija, conserva las traducciones existentes y fusiona los formatos estándar; un sidecar <lid>.status.json lista lo que una IA local aún debe traducir
• Parámetros de tarea declarativos — µParameters pregunta una vez antes de la ejecución, entrega los valores como MICROGULP_PARAMS / GetParameters(), recuerda las últimas respuestas, mantiene las contraseñas fuera de los registros y puede ocultar campos con visibleWhen
• Tareas watch / disparo — los globs µWatch ejecutan una tarea al cambiar archivos, con debounce, coalescencia y disyuntor ante descontrol; se arma por tarea desde el panel
• Atajos de tarea — acordes µKeyBinding con variantes por plataforma (ctrl+shift+F1, cmd+shift+Escape), insignias y avisos de conflicto; µGulp: Run Task para atajos globales del IDE
• Salida de registro estructurada — las tareas emiten cargas JSON renderizadas en línea en el registro de ejecución (tablas, árboles, galerías de imágenes, recuadros, métricas clave/valor, insignias de estado, bloques de código, gráficos de barras SVG inline) — seguro para Content-Security-Policy, sin plugin ni iframe; el ancho de los gráficos está limitado y los encabezados/filas de LogTable usan colores teñidos por el skin, con hover
• Historial persistente de tareas y registro en archivo — cada ejecución se escribe en .microgulp/logs (.log crudo + .ndjson estructurado), un índice history.ndjson sobrevive a reconexiones/reinicios del IDE; un panel de historial abre cada transcripción (logToFile, logRetention)
• Diálogos modales — ShowModalMessage / ShowConfirmMessage como paneles de cristal estilo AiDPix en el panel (info/aviso/error, Sí/No, OK/Cancelar); modales nativos opcionales de VS Code/Cursor vía presentation o microgulp.modalPresentation (gulp-mu-gulp-api); sección README propia
• Ubicaciones de error clicables — file:line:column en el registro de ejecución se abre en el editor del host (pestaña VS Code, editor IDE JetBrains)
• Matriz de concurrencia — ejecuciones exclusivas por tarea y reglas allow/deny (µExecutionConcurrency, µExecutionRestrictions)
• Skins del panel — Neon Carbon, Ice Light, más IDE Dark / IDE Light sencillos; selector Appearance con Automatic (seguir el tema IDE/OS) (Free: IDE Dark / IDE Light según el tema del IDE, no seleccionable)
• Packs ZIP de tema personalizados — instalación global (~/.microgulp/themes); los packs pueden incluir CSS, gráficos, fuentes y atlas de sonido opcionales; importar/quitar en Settings → Appearance (no en Free)
• Fuentes de proyecto para iconos y registros — RegisterDashboardFont / µDashboardFonts / dashboardFonts para el glifo µIcon y las tipografías del registro; µIconFont opcional por tarea (gulp-mu-gulp-api 0.3.12)
• Control acústico opcional — sonidos de fin, alarmas de error y salida de voz (ajustes del panel)
• Recordatorio de formulario opcional — cuando una tarea espera entrada del panel, recordar al usuario tras un retraso configurable por sonido y/o voz; se repite hasta que se responda el formulario
• Cierre automático de ejecuciones terminadas — cuenta atrás opcional en la cabecera del sector (clic para mantener abierto); una tarea lo anula con µAutoClose (-1 mantener abierto, un número positivo = segundos, omitido usa Settings → Finished Runs, 30 s por defecto); Restart junto a Close
• Elevación de administrador de Windows — aviso UAC opcional por tarea (µRequiresElevation, µElevationReason); el IDE puede ejecutarse con normalidad mientras tareas individuales (p. ej. editar hosts) se ejecutan elevadas (VS Code registrado / JetBrains; no en Free)
• Motor de diagnóstico — errores de importación y trazas de pila se convierten en sugerencias accionables en el panel (VS Code registrado / JetBrains; no en Free)
• <version/> desde el gulpfile — µI18xContext.version es la fuente preferida para los títulos de tarea; versionSources opcional solo rellena cuando el gulpfile omite version (sin sobrescribir las configs de release del consumidor)
• LogError fiable frente a avisos de Node — LogError / un console.error real siguen fallando la ejecución; DeprecationWarning de Node y otros avisos de proceso no (el banner de fallo muestra el primer texto de error real)
• Puente de prompts heredados — inquirer / gulp-prompt / prompts redirigidos a formularios del panel sin editar gulpfiles
• gulp-mu-gulp-api — módulo npm para progreso, sonido, voz, entradas interactivas, diálogos modales y fuentes del panel desde dentro de las tareas

Instantánea

Hosts	VS Code, Cursor AI, JetBrains IDEs (Settings → Tools → µGulp), cualquier navegador en 127.0.0.1 vía microgulp-serve --http
Runtime	Node.js 22+ (ESM)
Gulpfiles	Un solo gulpfile.mjs o descubrimiento regex en el workspace
Config	Ajustes de extensión (VS Code/Cursor), Settings → Tools → µGulp (JetBrains), microgulp.config.json opcional (equipo / CLI)
Engine	Independiente del IDE — el mismo src/engine en cada host
Idiomas	GUI del panel: en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR (empaquetados); salida gulp vía i18x/gulp/ del proyecto; manual como PDF en el idioma del panel
Orden de tareas	µOrder (entero ascendente); grupos por el orden mínimo del subárbol; tareas sin orden al final (alfabético)

Clic en una tarea → un worker caliente la ejecuta de inmediato. Edite el gulpfile → la lista de tareas se actualiza sola. Varias tareas pueden ejecutarse en paralelo; cada una obtiene su propio sector del panel con una barra de progreso neón cuando la tarea llama a ReportProgress desde gulp-mu-gulp-api.

Sin atadura: el gulpfile sigue siendo un gulpfile normal

Adoptar µGulp™ no hace que su build dependa de µGulp™. Un gulpfile preparado para el panel sigue ejecutándose bajo la CLI gulp clásica, en CI y en máquinas donde µGulp™ nunca se instaló — y sigue funcionando cuando se desinstala µGulp™.

Compatible hacia atrás — todo degrada a gulp simple

Qué añade	Qué hace gulp simple con ello
µDisplayName, µIcon, µGroup, µOrder, µKeyBinding, µWatch, µAutoClose, µRequiresElevation, …	Nada. Son propiedades ordinarias de la función exportada; la CLI gulp aborda las tareas por nombre de export e ignora propiedades desconocidas. Los nombres de tarea y el direccionamiento CLI no se tocan — por eso existe el prefijo µ
µParameters	No se preguntan. La tarea lee GetParameters() / GetParameter(id, fallback), que caen a los defaults declarados o a las variables de entorno MICROGULP_PARAMS / MICROGULP_PARAM_<ID> que puede fijar a mano en un job CI
ReportProgress(...)	Imprime una línea de porcentaje en stdout (una sola línea \r en un TTY, líneas limitadas en CI) en lugar de conducir la barra neón
RequestForm, ShowModalMessage, PlaySignal, Speak, LogTable, LogChart, …	Cada helper tiene un fallback CLI: las peticiones se resuelven a sus defaults, los modales imprimen una línea entre corchetes y devuelven ok, sonido y voz son no-ops, los registros estructurados se muestran como texto
.i18xRegister() / .i18xTrans()	i18xRegister() devuelve la cadena fuente en inglés americano sin cambios; i18xTrans() cae al texto fuente cuando no hay diccionario. Sin µGulp™ obtiene simplemente salida de consola en inglés
.microgulp/ (registros, parámetros recordados)	Solo se escribe cuando µGulp™ ejecuta la tarea. Es un directorio caché desechable — añádalo a .gitignore y bórrelo cuando quiera

gulp-mu-gulp-api es un paquete npm normal sin dependencias de ejecución, e IsMicroGulp() indica a una tarea si está siendo orquestada. Quitar µGulp™ significa desinstalar la extensión — sin editar el gulpfile.

Compatible hacia adelante — las versiones nuevas de µGulp™ no rompen gulpfiles antiguos

Los metadatos son aditivos y las claves desconocidas se ignoran en ambos lados. Un gulpfile escrito para un µGulp™ más nuevo se ejecuta en uno más antiguo con las funciones nuevas simplemente no disponibles (sin insignia de atajo, sin interruptor watch, sin formulario de parámetros — la tarea arranca igual). Los formatos de registro estructurado desconocidos se omiten en lugar de romper la ejecución, y el protocolo del host lleva un número de versión para que un host desactualizado detecte un desajuste en vez de malinterpretarlo.

Consecuencia práctica: puede probar µGulp™ en un script de build de producción, entregar el mismo repositorio a un colega que ejecuta npx gulp BUILD en un terminal, y ninguno de los dos entornos nota al otro.

Instalación

Las páginas del marketplace están reservadas pero aún no son públicas (el repositorio fuente sigue privado). Hasta que las fichas estén en vivo, instale desde los paquetes de este repo / una GitHub Release.

Edición	Paquete	Marketplace (previsto)
µGulp™ (VS Code / Cursor)	packages/microgulp_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ Free (VS Code / Cursor)	packages/microgulp-free_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ (JetBrains IDEs)	véase IDEs JetBrains más abajo	JetBrains Marketplace (plugin id de.amekudzi.microgulp)

Instalación VSIX local:

code --install-extension packages/microgulp_latest.vsix       # VS Code, registered
cursor --install-extension packages/microgulp_latest.vsix     # Cursor AI, registered
code --install-extension packages/microgulp-free_latest.vsix  # VS Code, Free

• Compilar desde el código fuente: npm install, luego npm run build — los .vsix registrado y Free llegan a packages/.

Después ejecute µGulp: Open Dashboard desde la paleta de comandos (o pulse el cohete µGulp™ en la barra de estado).

IDEs JetBrains

El plugin JetBrains es un plugin de plataforma (com.intellij.modules.platform) — se instala en IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip y otros IDEs basados en IntelliJ. Se entrega en dos paquetes — elija el que coincida con el build de su IDE (Help → About):

IDE build	since-build	Paquete
2024.2 – 2026.1 (hasta 261.*)	242	packages/microgulp-jetbrains_latest.zip
2026.2 y más nuevo	262	packages/microgulp-jetbrains-2026.2_latest.zip

Elija el zip correcto. IntelliJ IDEA, PhpStorm, WebStorm y los demás IDEs basados en IntelliJ comparten estos dos paquetes — elija por build de plataforma, no por nombre de producto. Cada paquete declara <idea-version since-build="…"/> en el descriptor — la IDE no carga el otro. microgulp-jetbrains es since-build="242" / until-build="261.*" (2024.2–2026.1). microgulp-jetbrains-2026.2 es since-build="262" sin tope (2026.2+). El build de plataforma está en Help → About.

La ficha de JetBrains Marketplace (id de plugin de.amekudzi.microgulp) usa el nombre latino MicroGulp — µ y ™ no están permitidos en <name>. El dashboard, la ventana de herramientas, el sitio y este README conservan µGulp™. Ambos zips comparten ese id. Las versiones de plugin.xml se derivan de la única versión de producto en RELEASES.json como prereleases SemVer (<producto>-idea242, <producto>-idea262; Marketplace SemVer Only), salvo el producto 0.9.3 en el canal 242–261.* que permanece en la versión de marketplace 0.9.3 (ya enviada). El paquete 262 de 0.9.3 es 0.9.3-idea262. VS Code / Free conservan la versión de producto sin sufijo. Los nombres de zip siguen *_V<producto>.zip. Ambos paquetes JetBrains llevan el mismo registro de cambios del producto. Licencia: https://microgulp.dev/en/license/. El repositorio fuente permanece privado — no publique una URL de código fuente en la ficha de Marketplace.

El build 262 sacó JCEF de la plataforma núcleo al plugin empaquetado Web Browser (JCEF), así que el descriptor debe declararlo de forma explícita — de ahí el paquete aparte. Instale vía Settings → Plugins → ⚙ → Install Plugin from Disk… y abra la ventana de herramientas µGulp. Las opciones del motor están en Settings → Tools → µGulp (ruta de Node, descubrimiento del gulpfile, preload/pool, watch, registros de ejecución) — el mismo papel que los ajustes VS Code microgulp.*. Apariencia, sonido e idioma se quedan en el panel ⚙ del dashboard. El plugin es un adaptador JCEF delgado — todo el motor corre en un sidecar Node.js empaquetado, así que Node.js 22+ debe estar instalado (PATH, MICROGULP_NODE o el ajuste de ruta de Node). Si JCEF no está disponible — builds IDE recortados, plugin de navegador desactivado — la ventana de herramientas sigue arrancando el motor y ofrece un botón que abre el panel en su navegador habitual.

Compilación y comprobación de los paquetes

npm run jetbrains (alias npm run phpstorm) construye ambos zips, npm run jetbrains:verify los comprueba. Sin Gradle:

• Cada paquete se compila contra la plataforma IntelliJ más antigua que admite — el paquete 242 contra un IDE 2024.2, el paquete 262 contra el IDE instalado. javac rechaza entonces una API que solo existe en un build más nuevo en vez de dejarla salir. El adaptador usa solo APIs de plataforma (ventana de herramientas, ajustes, JCEF, editor), así que el mismo zip corre en cada IDE basado en IntelliJ.
• npm run jetbrains:verify ejecuta el JetBrains Plugin Verifier sobre ambos zips, en ambos extremos de su rango declarado (2024.2 y 2026.1 para el paquete legacy, 262 para el otro). Informa de clases y métodos faltantes, API deprecada o interna, y defectos del descriptor.
• El fat-jar Plugin Verifier está en dev/tools/intellij-plugin-verifier/ (verifier-cli-1.410-all.jar; se descarga de Maven Central si falta). Las distribuciones de la plataforma IntelliJ necesarias se descargan una vez en MICROGULP_IDE_CACHE (por defecto %LOCALAPPDATA%\microgulp\ide-cache, ~/.cache/microgulp/ide-cache en otros sitios) y se reutilizan; el IDE instalado localmente se usa directamente cuando su build coincide. MICROGULP_SKIP_IDE_DOWNLOAD=1 mantiene los builds sin red — entonces compilán contra el IDE instalado y omiten los destinos de verificación faltantes.
• Una cosa que el verificador no ve: resuelve contra todo el IDE e ignora el aislamiento de classloader de los módulos de contenido, así que una dependencia de módulo faltante sigue leyéndose como compatible. Por eso el build se niega a empaquetar un paquete para build 262+ que toque JCEF sin declarar com.intellij.modules.jcef y sus dos módulos.

Ruido conocido en el registro JetBrains / JCEF (inofensivo)

La primera vez que la ventana de herramientas µGulp incrusta el panel, el registro del IDE puede mostrar un error como:

JBCefApp$Holder <clinit> requests ProxyMigrationService instance. Class initialization must not depend on services.

Proviene de la propia pila JCEF de JetBrains (JBCefApp → ajustes de proxy → HttpConfigurable), no del plugin µGulp. La plataforma sigue completando el arranque de JCEF; si el panel aparece después, puede ignorar la entrada. No está relacionado con PhpStorm 2025 vs. 2026 — cualquier IDE JetBrains con el mismo build JCEF puede emitirlo. Solo investigue más si la ventana de herramientas se queda en blanco o muestra un error real de arranque de µGulp (ruta de Node, sidecar, escaneo del gulpfile).

El mismo panel también corre en cualquier navegador: npm run serve -- --cwd <project> --http 9310 --preload, luego abra http://127.0.0.1:9310/.

Archivo de configuración microgulp.config.json (JetBrains y CLI)

En VS Code / Cursor el motor se configura con los ajustes de la extensión (microgulp.gulpfilePattern etc.). El plugin JetBrains refleja esas opciones del motor en Settings → Tools → µGulp (se pasan como flags CLI del sidecar en la siguiente apertura de la ventana de herramientas). Opcionalmente, un microgulp.config.json en la raíz del proyecto sigue aportando defaults de equipo y claves que no están en la página IDE (dashboardFonts, metadataWatchFiles, versionSources). El uso CLI/navegador vía microgulp-serve lee el archivo cuando no hay flag CLI:

{
	"gulpfilePattern": "gulpfile.*\\.mjs$",
	"poolSize": 2,
	"maxParallel": 6,
	"preload": true,
	"watchGulpfiles": true
}

Key	Type	Default	Meaning
gulpfile	string	"gulpfile.mjs"	Single gulpfile, relative to the project root
gulpfilePattern	string	—	Case-insensitive regex against workspace-relative POSIX paths; discovers all matching gulpfiles (wins over gulpfile)
poolSize	int ≥ 0	2	Warm workers per gulpfile
maxParallel	int ≥ 1	6	Maximum concurrent task runs
preload	bool	false	Warm up the worker pools right after startup (PhpStorm IDE setting defaults to on; CLI needs --preload)
watchGulpfiles	bool	true	Auto-rescan on gulpfile changes
metadataWatchFiles	string[]	["package.json", "RELEASES.json"]	Optional. Workspace-relative files whose changes trigger a metadata rescan (e.g. after a version bump). Prefer watching the file your gulpfile reads at init.
versionSources	string[] or objects	["package.json"]	Optional. Live JSON fallback for <version/> when the gulpfile does not set µI18xContext.version. Rarely needed for consumer projects — see below.
dashboardFonts	array	—	Optional. Project fonts for task icons / run log (see Fuentes del panel)
logToFile	bool	true	Persist run transcripts (.log + .ndjson) and the task history to disk
logDirectory	string	.microgulp/logs	Directory for transcripts and the history index, relative to the project root
logRetention	int ≥ 0	200	Max runs kept in the history (0 = unlimited); older runs and their log files are pruned

Precedencia: línea de comandos / ajustes IDE JetBrains > microgulp.config.json > defaults integrados. Los valores inválidos y las claves desconocidas se ignoran con un aviso en stderr; el archivo es versionable y aplica a todo el equipo. Tras editar los ajustes IDE o el archivo, vuelva a abrir la ventana de herramientas µGulp (respawnea el sidecar) o reinicie microgulp-serve.

En VS Code / Cursor las mismas claves están disponibles como microgulp.metadataWatchFiles y microgulp.versionSources (los ajustes de extensión no vacíos ganan sobre microgulp.config.json). Arrays vacíos desactivan las vigilancias de metadatos o las lecturas de versión en vivo desde archivos.

<version/> en los títulos de tarea (preferido vs opcional)

Preferido (la mayoría de los proyectos consumidores): exporte µI18xContext desde el gulpfile y fije version ahí (lea su única fuente de release en el init del módulo). Use metadataWatchFiles para que los cambios de esa fuente reescaneen y refresquen los workers calientes:

export const µI18xContext = { project: 'MyApp', version: _ReadReleaseVersion() };
MAKE_BUILD.µDisplayName = 'Build V<version/><context="µDisplayName"/>'.i18xRegister();

{
	"metadataWatchFiles": ["configs/systemconfig.js"]
}

Cuando µI18xContext.version está definido, los versionSources en vivo no lo sobrescriben.

Opcional — versionSources: solo útil si no fija µI18xContext.version y quiere que el motor resuelva <version/> desde JSON en disco (y lo refresque en GetTasksPayload sin reimportar el gulpfile). Formas admitidas:

• "package.json" — usa el campo npm "version"
• "RELEASES.json" — archivo estilo µGulp; véase Control de versiones (RELEASES.json) para el esquema exacto (releases[0].main / minor / revision)
• { "file": "config/version.json", "field": "version" } — cualquier archivo JSON + ruta de campo con puntos

Ejemplo (solo JSON en vivo opcional — sin version en el gulpfile):

{
	"metadataWatchFiles": ["package.json", "RELEASES.json"],
	"versionSources": ["RELEASES.json", "package.json"]
}

Lógica: src/engine/ProjectMetadata.mjs; los marcadores se construyen en BuildSourceI18xContext.

Estructura del proyecto

gulpfile.mjs             Project build: tests, theme CSS (µCSS), package + deploy
RELEASES.json            Version source (main/minor/revision, i18xe-ready info texts)
gulp-mu-gulp-api/        Standalone npm module: public task API
  src/index.mjs          Progress, text/color/font/select inputs, forms
  tests/                 The module's own node:test suite
skins/                   One directory per skin (neon-carbon is the default)
  neon-carbon/
    neon-carbon.µcss.mjs µCSS skin manifest (Carbon/Neon variables)
    neon-carbon.µ.css    Skin source → compiled into src/webview/skins/neon-carbon/
  ice-light/             Light frosted-glass skin (cool blue outward glow)
    ice-light.µcss.mjs   µCSS skin manifest (ice palette)
    ice-light.µ.css      Skin source → compiled into src/webview/skins/ice-light/
  ide-dark/              Plain IDE-aligned dark (VS Code–like, no neon/carbon)
  ide-light/             Plain IDE-aligned light companion
src/
  engine/                IDE-independent core (no VS Code APIs!)
    TaskEngine.mjs       Orchestrator: scan, preload, queue, events
    TaskWorkerPool.mjs   Pool of prewarmed worker processes
    ConcurrencyGuard.mjs Evaluates executionConcurrency/-Restrictions
    Diagnostics.mjs      Diagnosis engine (stack traces → concrete suggestions)
    PluginHost.mjs       Lifecycle hooks for plugins
    GulpfileDiscovery.mjs  Regex-based gulpfile discovery in the workspace
    ReleaseInfo.mjs      Release management: RELEASES.json, version strings, history
  worker/
    TaskWorker.mjs       Child process: imports the gulpfile, runs tasks
  bridge/
    gulp-ugulp-bridge.mjs  Public bridge: npm packages ↔ webview forms
  host/
    HostProtocol.mjs     Event/command names (the single host boundary)
    Daemon.mjs           Engine owner for sidecar hosts
    microgulp-serve.mjs  stdio NDJSON CLI (PhpStorm preparation)
  extension/
    extension.cjs        Thin VS Code / Cursor adapter (the only CJS module)
  webview/
    dashboard.css        Fallback stylesheet for fresh checkouts
    dashboard.js         TaskGrid, log streaming, forms, audio engine
    skins/<name>/dashboard.css  µCSS-generated skins (webview default: neon-carbon)
tests/                   node:test suites (unit + engine integration)
demo/
  gulpfile.mjs           Example gulpfile with every µGulp™ metadata tag
  run-demo.mjs           Headless engine smoke test (no IDE)
dev/
  prompts/               AI migration prompts (existing gulpfile → µGulp + i18x)
    OptimizeGulpfileForMicroGulp.md
    OptimizeGulpfileForMicroGulp.params.example.json

Principios de arquitectura

• La capa del motor está libre de IDE. src/engine y src/worker no conocen APIs de VS Code. La comunicación va por eventos (motor → host) y comandos JSON simples (host → motor). Portar a PhpStorm (fase 2) es por tanto un simple cambio de adaptador — el sidecar mínimo npm run serve (src/host/microgulp-serve.mjs, NDJSON en stdio) ya está en su sitio.
• Precarga de tareas. El TaskWorkerPool mantiene procesos Node precalentados en los que el gulpfile ya se importó. Arrancar una tarea entrega un worker caliente y rellena el pool en segundo plano. Tras una ejecución el proceso se descarta (estado de módulo fresco).
• Imports dinámicos. Los paquetes npm pesados (mssql, docx-templates, makensis, …) solo deben cargarse dentro del cuerpo de la tarea vía await import() — los imports estáticos de primer nivel están reservados a la lógica núcleo del orquestador.
• Idiomas. Los textos GUI son inglés americano y pasan por String.i18xTrans() (cableado i18xe pendiente); comentarios de código en inglés; manuales/documentación en alemán.

Localización del panel

La GUI del panel se entrega con diccionarios i18x empaquetados para en-US (fuente), de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP y ko-KR. Elija el idioma en los ajustes del panel (automatic sigue la locale del host o del navegador). La salida de consola del gulpfile usa el mismo idioma vía MICROGULP_LANG en el worker y los archivos i18x/gulp/<lid>.json de su proyecto. El manual de usuario se entrega como PDF en el idioma del panel.

Para sembrar o refrescar esos diccionarios gulp sin servidor i18xe: Settings → Project i18x (gulp) → Scan & update i18x/gulp…. µGulp™ analiza las frases con el escáner i18xe-sync (más Log/Warn/LogError), conserva las traducciones existentes, fusiona las definiciones de formato estándar y escribe sidecars <lid>.status.json (missing / orphans) para traducción IA local.

Layer	Who provides it	Today	Planned
Dashboard GUI	µGulp (extension)	en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR	More marketplace languages via the i18xe sync pipeline
Gulp tasks & logs	Your project	i18x/gulp/*.json next to the gulpfile	Same — consumer projects never ship i18x/prod
Hyphenation	µGulp webview assets	String.prototype.Hyphenation() with bundled <lid>.hyphen.json where present	Additional locales as hyphen data is synced from i18xe

Etiquetas de contexto, formatos obligatorios y hoja de ruta de idiomas: dev/docs/MicroGulpI18xProfile.md. Una conexión servidor i18xe en vivo para los diccionarios GUI del panel sigue siendo opcional (vía 3); los diccionarios gulp del consumidor usan el escaneo sin conexión de arriba.

Detección de gulpfiles (configurable por regex)

µGulp™ nota solo los cambios de gulpfile en disco: un watcher del workspace (microgulp.watchGulpfiles, activo por defecto) reescanea automáticamente tras cada cambio y sustituye los workers calientes por unos frescos que ejecutan el código actual. Mientras corre un escaneo, la lista de tareas muestra un indicador de progreso animado; el panel ya no tiene botón de reescaneo — el comando µGulp: Rescan Tasks (paleta de comandos) permanece como refresco forzado manual. Si un gulpfile no carga (error de sintaxis, módulo faltante), aparece un banner de error descartable con diagnóstico y traza de pila en el propio panel.

µGulp™ encuentra gulpfiles por un camino único o por un patrón regex que busca en todo el workspace:

• microgulp.gulpfilePattern — un regex JavaScript (insensible a mayúsculas) probado contra la ruta relativa al workspace (notación POSIX con /). Cuando está definido, se escanea cada archivo coincidente; las tareas se agrupan por fuente en el panel. Ejemplo: (^|/)gulpfile\.(m|c)?js$ encuentra gulpfile.mjs/.js/.cjs en la raíz y en cada subcarpeta.
• microgulp.gulpfilePath — el camino único clásico (default gulpfile.mjs). Solo se usa mientras gulpfilePattern está vacío.

Nunca se desciende a node_modules, .git ni carpetas ocultas (.*). Cada gulpfile descubierto recibe su propio pool de workers calientes con la carpeta del gulpfile como directorio de trabajo, así que los subproyectos anidados con rutas relativas se ejecutan bien. La lógica de descubrimiento vive independiente del IDE en src/engine/GulpfileDiscovery.mjs y por tanto está disponible también para la CLI y el adaptador JetBrains.

Cuando coincide más de un gulpfile, la columna izquierda de tareas muestra un encabezado de fuente por archivo de script (ruta relativa al workspace, p. ej. gulpfile.mjs, nested/gulpfile.mjs); las tareas de archivos distintos no se mezclan en el nivel superior. Dentro de cada fuente, las tareas siguen anidándose por su ruta µGroup (Build/Production, …). Con un solo gulpfile se omite el encabezado — solo aplica el anidado µGroup. Si los gulpfiles escaneados exportan tareas pero ninguno importa gulp-mu-gulp-api, el panel muestra una pista descartable al paquete npm y al prompt de migración IA.

Metadatos µGulp™ en una tarea Gulp

La forma recomendada son etiquetas con prefijo µ en CamelCase (µDisplayName, µIcon, …) — son invisibles para la CLI gulp clásica, así que los gulpfiles siguen siendo plenamente compatibles en sistemas sin µGulp™ (la CLI gulp aborda las tareas vía function.displayName; un nombre bonito con espacios rompería el direccionamiento de tareas allí):

export async function BUILD_STYLES() { /* ... */ }
BUILD_STYLES.µDisplayName = 'Build Styles';
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.';
BUILD_STYLES.µTooltip = 'Runs the µCSS pipeline (sprites, fonts, sounds included).';
BUILD_STYLES.µIcon = '\u25A3';   // font symbol — or an image data URI:
// BUILD_STYLES.µIcon = 'data:image/svg+xml,%3Csvg ...';  (png/webp too)
BUILD_STYLES.µIconFont = 'ProjectIcons'; // optional — see Dashboard fonts below
BUILD_STYLES.µGroup = 'Build/Assets';                 // nested group (path syntax)
BUILD_STYLES.µOrder = 10;                             // sort position in the dashboard (ascending)
BUILD_STYLES.µExecutionConcurrency = true;            // false = exclusive
BUILD_STYLES.µExecutionRestrictions = { deny: ['CLEAN'] }; // parallel matrix
BUILD_STYLES.µKeyBinding = { key: 'ctrl+shift+B', mac: 'cmd+shift+B' }; // dashboard shortcut
BUILD_STYLES.µWatch = { files: ['skins/**/*.µ.css'] }; // optional file trigger
BUILD_STYLES.µAutoClose = -1;                         // keep the finished sector
BUILD_STYLES.µParameters = [                          // asked before the run
  { id: 'target', type: 'select', options: ['debug', 'release'], default: 'debug' },
];
// Windows only — show the UAC prompt when the host is not already elevated:
BUILD_STYLES.µRequiresElevation = true;
BUILD_STYLES.µElevationReason =
  'Modifies the Windows hosts file.<context="µElevationReason"/>'.i18xRegister();

µGroup asigna la tarea a un grupo anidado en el resumen de tareas. La definición sigue una sintaxis de ruta de directorio: µGroup = 'Build/Production' crea el grupo Build con el subgrupo Production. Los grupos son plegables en el panel; las tareas sin µGroup se quedan en el nivel superior. La asignación es opcional y puramente visual — no afecta a la ejecución ni a la concurrencia.

µOrder fija la posición de orden en la columna izquierda (entero ascendente). Las tareas y grupos hermanos se ordenan por µOrder; las tareas sin valor aparecen tras todas las ordenadas (desempate: nombre visible). Los grupos ordenan por el µOrder más bajo de su subárbol.

Teclas modificadoras en la cabecera de un grupo:

Action	Effect
Click	toggle the group
Ctrl+Click (Cmd+Click)	toggle every group on the same level
Alt+Click	toggle all groups

µRequiresElevation marca una tarea que necesita derechos de Administrador en Windows (por ejemplo reescribir C:\Windows\System32\drivers\etc\hosts). Cuando el IDE corre con normalidad, µGulp™ arranca un worker elevado de un solo uso y muestra el diálogo UAC habitual — no tiene que lanzar Cursor o VS Code como Administrador. Si el proceso host ya está elevado, se usa el pool de workers calientes como de costumbre. En plataformas que no son Windows el flag se ignora. El µElevationReason opcional aparece en el tooltip de la tarea (insignia ⛿ en el panel).

Atajos de tarea (µKeyBinding)

Una tarea puede llevar su propio acorde de teclado. El acorde funciona mientras el panel tiene el foco — VS Code y PhpStorm no pueden registrar atajos en tiempo de ejecución, así que µGulp™ los gestiona él mismo en vez de pretender poseer teclas globales del IDE.

BUILD.µKeyBinding = 'ctrl+shift+B';                      // same chord everywhere
DEPLOY.µKeyBinding = { key: 'ctrl+alt+D', mac: 'cmd+alt+D' };
STOP.µKeyBinding = { key: 'ctrl+shift+Escape' };         // named keys: F1…F24, Escape, Tab, Space, arrows, …

Part	Accepted
Modifiers	ctrl, control, alt, option, shift, meta, cmd, command, super, win
Keys	single characters (b, 7, +), F1–F24, Escape/Esc, Enter, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up/Down/Left/Right
Platform keys	key (fallback), mac, win, linux — the matching platform wins, key fills the rest

cmd se mapea a la tecla Command en macOS y a Ctrl en el resto, así que un solo acorde key sigue siendo usable en todas las plataformas. El acorde aparece como insignia junto al nombre de la tarea; si dos tareas reclaman el mismo acorde, ambas insignias se vuelven ámbar y el tooltip lo dice (µGulp™ se niega a adivinar cuál quería).

Para un atajo realmente global del IDE, vincule usted mismo el comando µGulp: Run Task — toma la tarea como argumento:

// keybindings.json (VS Code / Cursor)
{ "key": "ctrl+shift+f9", "command": "microgulp.runTask", "args": { "task": "gulpfile.mjs::BUILD_STYLES" } }

Sin args el comando abre una selección rápida de las tareas escaneadas.

Parámetros de tarea declarativos (µParameters)

En vez de pedir entrada desde el cuerpo de la tarea, una tarea puede declarar lo que necesita. µGulp™ muestra un formulario antes de arrancar, recuerda las respuestas para la próxima vez y entrega los valores a la tarea por el entorno:

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 = {
  submitLabel: 'Start Deploy<context="button text"/>'.i18xRegister(),
  fields: [
    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging',
      label: 'Target<context="task parameter"/>'.i18xRegister() },
    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
    { id: 'servers', type: 'checkbox', options: ['a', 'b'], required: true }, // submit stays disabled until ≥1
    { id: 'dryRun', type: 'boolean', default: true },
    { id: 'notify', type: 'boolean', default: false,
      visibleWhen: { dryRun: false } },   // only when not a dry run
    { id: 'token', type: 'password' },   // never stored, never logged
  ],
};

Un array simple de campos sigue funcionando. El envoltorio añade el cromo del formulario (title, submitLabel); µParameterSubmitLabel en la tarea es una alternativa equivalente para el texto del botón.

Field	Meaning
id	required; must be env-var safe ([A-Za-z_][A-Za-z0-9_]*)
type	text (default), textarea, password, number, range, boolean (slide switch), checkbox (multi-select), radio, select, font, color
label, description, placeholder	shown in the form (i18x via .i18xRegister())
default	pre-filled value; a remembered answer from the last run wins
options	['a','b'], [{ value, label, disabled }] or { a: 'Label A' }
required, pattern, minLength, minSelected	validated live in the dashboard — the submit button stays disabled until every visible rule passes (required on a checkbox means at least one option)
min, max, step, rows	numeric / textarea details
remember	false keeps the value out of the store (implicit for password)
visibleWhen	show the field only while other answers match — e.g. { dryRun: false } or { servers: 'prod' } (multi-select: contains). Hidden fields are not validated; missing answers fall back to default
submitLabel / title	form wrapper keys (or µParameterSubmitLabel / µParameterTitle on the task) — i18x via .i18xRegister()

Los valores llegan como MICROGULP_PARAMS (JSON) más un MICROGULP_PARAM_<ID> plano por parámetro, así que los pasos de shell dentro de una tarea también pueden leerlos. GetParameters() / GetParameter('target', 'staging') de gulp-mu-gulp-api los analizan; bajo la CLI gulp simple puede suministrar las mismas variables a mano:

MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY

Las respuestas se recuerdan por tarea en .microgulp/parameters.json y rellenan el siguiente formulario. Las contraseñas y los valores remember: false no se almacenan ni se escriben en la transcripción, el historial ni el panel — aparecen como ••••. El registro de ejecución y la entrada de historial anotan los valores con los que arrancó una ejecución, para que después se vea qué se respondió. Las tareas elevadas (µRequiresElevation) no pueden mostrar un formulario desde su proceso de un solo sentido, así que se ejecutan con los valores recordados por encima de los defaults declarados.

Tareas watch / disparo (µWatch)

Una tarea puede ejecutarse sola cuando cambian los archivos que le importan:

BUILD_CSS.µWatch = 'src/**/*.µ.css';                  // shorthand
BUILD_CSS.µWatch = {
  files: ['src/**/*.µ.css', 'skins/*/manifest.json'], // globs, relative to the gulpfile
  ignore: ['**/*.tmp'],
  debounceMs: 300,                                    // quiet time after the last change
  autoStart: false,                                   // arm as soon as the gulpfile is scanned
  parameters: { target: 'debug' },                     // fixed µParameters for triggered runs
};

La vigilancia es opt-in por tarea: aparece un interruptor ◉ junto al nombre de la tarea (cian cuando está armado) salvo que la declaración diga autoStart: true. Los globs admiten **, *, ?, {a,b} y clases de caracteres; nunca se vigilan node_modules, .git, .microgulp, .idea ni .vscode.

Barandillas, porque una tarea de build que escribe en su propio conjunto de vigilancia giraría para siempre:

• una ráfaga de eventos de cambio se convierte en una ejecución (debounce)
• mientras una ejecución de la tarea está activa, como mucho se encola una ejecución de seguimiento
• más de 20 ejecuciones disparadas en un minuto suspenden el watcher (interruptor ámbar, el tooltip explica por qué); apagarlo y volver a encenderlo lo rearma

Una ejecución disparada nombra en su registro el archivo que la disparó (Triggered by src/a.css) y nunca abre un formulario de parámetros — un disparo usa los valores fijados o recordados, así que nada espera a un humano que no está mirando.

Mantener abierta una ejecución terminada (µAutoClose)

Los sectores terminados se cierran por defecto a los 30 segundos (Settings → Finished Runs). Una tarea puede anularlo:

SHOW_OUTPUT.µAutoClose = -1;   // mantener el sector (nunca cierre automático)
QUICK.µAutoClose = 8;          // cerrar a los 8 segundos

Valor	Significado
omitido / true	ajuste del panel (30 s por defecto)
-1, false, 0	no cerrar automáticamente esta tarea
entero positivo	cerrar tras esos segundos (anula el retraso del panel)

El chip amarillo de cuenta atrás sigue permitiendo conservar el sector. µAutoClose es un número o un boolean — sin .i18xRegister().

Ubicaciones de error clicables

Las referencias de archivo en el registro de ejecución se convierten en enlaces: src/engine/TaskEngine.mjs:412:9, at Object.<anonymous> (gulpfile.mjs:88:15), salidas tsc/eslint y file(12,7) estilo MSBuild. Un clic (o Enter encima) abre ese archivo en esa línea y columna en el editor del host — una pestaña de editor en VS Code/Cursor, el editor IDE vía el puente JCEF en PhpStorm.

La ruta se resuelve en el host primero contra el directorio del gulpfile de la ejecución, luego la raíz del workspace, así que los workspaces con varios gulpfiles saltan a la copia correcta de un nombre ambiguo. Solo se abren archivos existentes con extensiones de tipo fuente; URLs, marcas de tiempo y números de versión se dejan en paz.

Packs de tema (ZIP)

Los temas personalizados del panel se pueden distribuir como packs ZIP e instalar globalmente (para el usuario bajo ~/.microgulp/themes/, override con MICROGULP_THEMES_DIR). Son independientes del workspace del proyecto.

Disposición del pack (precompilado — no se requiere fuente µCSS):

manifest.json     // { "id", "displayName", "version", "appearance": "dark"|"light" }
dashboard.css
imgs/…            // optional graphics / cursors
fonts/…           // optional
snds/…            // optional µAU atlas: microgulp.sounds.weba (or .wav/.mp3) + microgulp.sounds.json

En el panel: Settings → Appearance → Import theme ZIP…. Los skins integrados se quedan en el selector; Automatic sigue mapeando a Neon Carbon / Ice Light. Quite un pack con Remove selected pack.

Desde este repo puede empaquetar un skin compilado después de npm run theme:

node dev/tools/pack-theme.mjs ide-dark
# → packages/microgulp-theme-ide-dark.zip

Atlas de sonido (µAU)

Las señales del panel se construyen desde dev/media/final/sounds/microgulp/: default/ es la base de cada skin; carpetas <skin-id>/ opcionales sobrescriben por radical de nombre de archivo. Los atlas se entregan como WebA (WebM/Opus solo audio, microgulp.sounds.weba). Las muestras idénticas se deduplican. Catálogo completo: dev/docs/MicroGulpSoundSchema.md.

PlaySignal('success'|'error'|'attention') se mapea a taskSuccess / taskFailed / requestAlert; PlaySound usa los nombres del esquema directamente.

Fuentes del panel (iconos de tarea y registro)

Las fuentes de proyecto son independientes de los skins integrados. Regístrelas en el gulpfile (preferido) o vía microgulp.config.json / el ajuste microgulp.dashboardFonts:

import { RegisterDashboardFont } from 'gulp-mu-gulp-api';

RegisterDashboardFont({
  id: 'ProjectIcons',
  file: 'assets/task-icons.woff2',   // relative to the gulpfile directory
  usage: 'task-icons',               // or 'log' / 'all'
});

// Or declarative:
export const µDashboardFonts = [
  { id: 'ProjectLog', file: 'assets/log.woff2', usage: 'log' },
];

BUILD.µIcon = '\uE101';
BUILD.µIconFont = 'ProjectIcons';     // optional when a single task-icons font is registered

usage: 'task-icons' estiliza las entradas glifo µIcon (la primera fuente registrada es el default; µIconFont sobrescribe por tarea). usage: 'log' fija la tipografía del registro del sector. Los archivos deben quedarse bajo el workspace (woff2 / woff / ttf / otf).

Cascada de fallback por propiedad: µDisplayName → ugulp.displayName (objeto namespace) → displayName (campo propio de Gulp) → nombre de export. executionRestrictions admite deny (siempre gana) y allow (lista blanca: todo lo no listado está prohibido).

Las cadenas de metadatos de tarea usan i18x con la etiqueta de contexto dentro de la frase. .i18xRegister() solo registra la frase para i18xe-sync y el diccionario del proyecto — devuelve el texto fuente sin cambios; la traducción ocurre después cuando el panel renderiza metadatos (TransProperty() vía i18x-catalog), con marcadores como <version/> rellenados desde µI18xContext. Para salida de consola, use .i18xTrans() o Log()/Warn()/LogError(), que traducen de inmediato en tiempo de ejecución (marcadores incluidos):

BUILD_STYLES.µDisplayName = 'Build Styles<context="µDisplayName"/>'.i18xRegister();
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();

Etiquetas de contexto, formatos obligatorios y plan de idiomas del marketplace: dev/docs/MicroGulpI18xProfile.md.

Migración de gulpfile asistida por IA

Para migrar un gulpfile existente grande (salida de consola, metadatos de tarea, diccionarios i18x/gulp, opcionalmente µKeyBinding / µParameters / µWatch / µAutoClose) use el prompt mantenido en el repositorio:

File	Purpose
dev/prompts/OptimizeGulpfileForMicroGulp.md	Copy-paste prompt for Cursor, Claude, ChatGPT, …
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json	Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version)

Workflow

1. Copie el ejemplo de params a la raíz de su proyecto como microgulp-optimize.params.json y rellene projectRoot, gulpfilePath, supportedLanguages (p. ej. en-US, de-DE, zh-CN), gulpMuGulpApiVersion (^0.4.0 o más nuevo), microGulpMinVersion (0.7.0), y githubRepoUrl / githubRef (default: https://github.com/mamekudz/microGulp, V0.7.0 o main).
2. Abra el markdown del prompt, sustituya la tabla {{PLACEHOLDER}} por sus valores (o adjunte el archivo params y el gulpfile en Cursor).
3. Deje que la IA ejecute la migración. El paso 0 del prompt es obligatorio: una copia de seguridad con marca de tiempo del gulpfile (p. ej. gulpfile.mjs.20260703-142559.bak) antes de cualquier edición.
4. Verifique con node --check gulpfile.mjs, pruebe las tareas en el panel µGulp (incluidos los atajos nuevos mientras el panel tiene el foco), luego confirme gulpfile.mjs, i18x/gulp/*.json y package.json.

Los proyectos consumidores solo necesitan i18x/gulp/<lid>.json — no i18x/prod. El prompt se actualiza con las releases de µGulp; consulte este repo para la última versión antes de migrar. Cubre las reglas i18x (register vs. translate, sin µMeta) y la UX declarativa: µKeyBinding del panel (no global del IDE salvo que el usuario vincule microgulp.runTask), µParameters / GetParameters(), µWatch y µAutoClose.

API pública de tareas (gulp-mu-gulp-api)

Los gulpfiles de terceros y los paquetes npm dentro del flujo usan las funciones extendidas del panel a través del módulo npm autónomo **gulp-mu-gulp-api** (vive como proyecto propio bajo gulp-mu-gulp-api/, publicado en npm por separado):

import { ReportProgress, RequestTextInput, RequestColorInput, RequestForm, ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

export async function BUILD_THEME() {
    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
    let title = await RequestTextInput({ label: 'Product title', validate: { required: true, minLength: 3 } });
    let ok = await ShowConfirmMessage({
        title: 'Overwrite theme?',
        message: 'Existing skin files will be replaced.',
        presentation: 'webview',
    });
    if (ok.button !== 'yes') return;
    for (let step = 1; step <= 10; step++) {
        // ... work ...
        ReportProgress(step / 10, 'compiling theme');   // determinate neon progress bar in the sector
    }
    await ShowModalMessage({
        variant: 'info',
        title: 'Theme ready',
        message: 'Skin files written.',
    });
}

El módulo no tiene dependencias y habla con el motor directamente por el canal IPC del worker µGulp™ (detección vía IsMicroGulp() / IsµGulp()). Sin µGulp™ todo degrada con limpieza: el progreso va al terminal, las entradas vía readline (TTY) o valores por defecto (CI). Detalles en gulp-mu-gulp-api/README.md. El módulo interno src/bridge/gulp-ugulp-bridge.mjs sigue como transporte de bajo nivel; los nuevos consumidores deben usar gulp-mu-gulp-api.

Diálogos modales (ShowModalMessage)

Desde V0.5.29 (API: gulp-mu-gulp-api 0.3.11+), las tareas pueden mostrar diálogos modales bloqueantes — para acuses, avisos antes de continuar, o confirmaciones Sí/No y OK/Cancelar. Úselos con moderación (no para líneas de registro rutinarias); prefiera Log() / helpers de registro estructurado para la salida normal.

Paneles de cristal Webview (default)

Cuando presentation es webview (el default), los modales se renderizan dentro del panel µGulp como paneles de cristal estilo AiDPix/Oxyd:

Feature	Detail
Frame	9-slice glasspanel.png (glasspanel-ice.png in the ice-light skin)
Variants	info (turquoise header), warning, error — colored header bar per variant
Buttons	Carbon-styled actions; primary button highlighted
Overlay	Scroll the mouse wheel over the dimmed backdrop to adjust overlay brightness (8–88 %); long message bodies scroll inside the panel
Keyboard	Escape → cancel/no (or first button); Enter → primary button

Implementación: src/webview/WebviewModal.js, src/webview/webview-modal.css (cargados por el webview de VS Code y el panel HTTP).

API

import { ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

// Single acknowledgment (default button: OK)
await ShowModalMessage({
    variant: 'warning',          // 'info' | 'warning' | 'error'
    title: 'Disk almost full',
    message: 'Less than 1 GB free on the build drive.',
    presentation: 'webview',     // optional — see below
});

// Yes/No confirmation (default style)
let answer = await ShowConfirmMessage({
    title: 'Overwrite output?',
    message: 'Existing files in dist/ will be replaced.',
});
if (answer.button !== 'yes') return;

// OK/Cancel preset
let discard = await ShowConfirmMessage({
    title: 'Discard changes?',
    message: 'Unsaved theme tweaks will be lost.',
    style: 'ok-cancel',          // default: 'yes-no'
});

Ambos helpers devuelven Promise<{ button: string }> — p. ej. 'ok', 'yes', 'no', 'cancel', o ids de botón personalizados desde ShowModalMessage({ buttons: [{ id: 'retry', label: 'Retry', primary: true }] }).

Fallback CLI (gulp simple, CI, sin TTY): salida de consola entre corchetes y el botón primario/default — sin prompt bloqueante.

Dónde aparece el modal (presentation)

Value	Behavior
webview	In-dashboard glass panel (default)
ide	Native VS Code / Cursor modal (showInformationMessage / showWarningMessage / showErrorMessage with { modal: true })
auto	Native IDE dialog when the Extension Host is available; otherwise the webview glass panel

El presentation por llamada sobrescribe el default del host.

Defaults del host

Host	Setting
VS Code / Cursor	Extension setting microgulp.modalPresentation (webview | ide | auto, default webview)
Browser demo / PhpStorm JCEF	Dashboard Settings → Modal presentation (same three values)

Fallback: PhpStorm y un panel de navegador siempre usan el panel de cristal webview — presentation: 'ide' se mapea a webview allí. Solo el Extension Host de VS Code/Cursor puede mostrar modales nativos del IDE.

Probar las demos

Tras µGulp: Open Sample Project, el panel lista un grupo Demo:

Task	Effect
DEMO_MODAL_DIALOGS	All variants + Yes/No + OK/Cancel with presentation: 'webview'
DEMO_IDE_MODAL_DIALOGS	Same flow with presentation: 'ide' (native modals in Cursor/VS Code; webview fallback in PhpStorm / the browser)

Más detalles de API: gulp-mu-gulp-api/README.md.

Certificación µGulp ready

Los módulos npm cuyo gulpfile raíz está plenamente integrado con el panel µGulp pueden mostrar la insignia µGulp ready en su README de npm y páginas de proyecto.

Requirement	Detail
Gulpfile	Exported tasks carry µGulp metadata (µDisplayName, µDescription, µGroup, …)
API	Uses gulp-mu-gulp-api for logging, progress and optional dashboard features
CLI fallback	Tasks remain runnable with plain gulp / npx gulp when µGulp is not installed
Badge asset	Canonical PNG: media/microgulp-ready.png in the µGulp repo. npm README: absolute raw URL (npm rewrites relative paths to microCSS/HEAD/... even inside HTML). Example: <a href="https://microgulp.dev"><img src="https://microgulp.dev/assets/media/microgulp-ready.png" alt="µGulp ready" width="150"></a>
package.json	Optional "microgulp": { "ready": true, "certifiedSince": "<semver>" } for machine-readable discovery

Módulos certificados

npm package	Since	Notes
gulp-mu-gulp-api	0.3.11	Official task API — Log, ReportProgress, i18x console layer, dashboard forms, ShowModalMessage / ShowConfirmMessage; npm README badge since 0.3.3
gulp-mu-css (µCSS™)	2.5.15	Monorepo root gulpfile.mjs with full task metadata, i18x/gulp/ (en-US, de-DE) and LogBuildDebugReport on demo builds; npm README badge via absolute raw URL since 2.5.14
gulp-mu-ps (µPS)	1.3.5	Test/render tasks in the shared root gulpfile (TEST_MICROPS, RENDER_EXAMPLES, …)
gulp-mu-ft (µFT)	0.1.5	Test task TEST_MICROFT in the shared root gulpfile
gulp-mu-au (µAU)	0.1.6	Test task TEST_MICROAU in the shared root gulpfile

Para solicitar la certificación, migre su gulpfile con dev/prompts/OptimizeGulpfileForMicroGulp.md y abra un issue o PR en el repositorio de µGulp o del módulo.

Control de versiones (RELEASES.json)

Este archivo es el formato de release de µGulp — la única fuente de verdad de este repositorio. Los proyectos consumidores no necesitan un RELEASES.json; suelen guardar su versión de producto en su propia config (y exponerla vía µI18xContext.version). Un versionSources: ["RELEASES.json"] opcional solo ayuda si adopta esta misma disposición JSON.

Cada entrada de release lleva main/minor/revision, una marca de tiempo, un flag beta y una lista de textos informativos. Los textos informativos llevan la etiqueta de contexto i18x <context="release info"/> y se registran vía String.i18xRegister(), así que el motor i18xe puede traducirlos automáticamente.

Esquema (release más nueva primero — releases[0] es la actual):

{
    "releases": [
        {
            "main": 0, "minor": 2, "revision": 0, "date": "2026-07-02 15:30", "beta": false,
            "info": [ "Release management added<context=\"release info\"/>" ]
        }
    ]
}

Cuando versionSources incluye "RELEASES.json", el motor resuelve <version/> a "main.minor.revision" desde releases[0] (p. ej. "0.2.0").

El módulo src/engine/ReleaseInfo.mjs proporciona:

• GetVersionString() / GetFullVersionString() — "0.2.0" o "0.1.4ß" (sufijo ß para builds beta).
• GetVersionHistoryText({ maxReleases, includeBeta }) — el historial completo como cadena formateada para la consola (tarea SHOW_VERSION_HISTORY o npm run history).
• BUILD_PACKAGE sincroniza la versión de package.json y la línea de versión al inicio de este README desde RELEASES.json automáticamente y la estampa en el nombre del artefacto (microgulp_V0.2.0.vsix, betas con sufijo _beta). Una release nueva solo necesita una entrada nueva al inicio de RELEASES.json.

Compilación del proyecto (gulpfile.mjs)

El proyecto se compila a sí mismo con su propio gulpfile (dogfooding: corre en el panel µGulp™, por la CLI gulp, por extensiones IDE Gulp clásicas y headless):

Invocation	Task	Purpose
npm test	RUN_TESTS	node:test suites in tests/ (unit + engine integration with real worker processes)
npm run theme	CREATE_THEME_DATA	Compiles every skins/<name>/<name>.µ.css via µCSS (gulp-mu-css BuildSkin) into src/webview/skins/<name>/dashboard.css (default: neon-carbon)
npm run package	BUILD_PACKAGE	Stages the extension into tmp/package/ and creates the .vsix in packages/ (also refreshed as microgulp_latest.vsix)
npm run deploy	DEPLOY_EXTENSION	Automated update cycle: build the .vsix and install it via cursor --install-extension (reload the window afterwards)
npm run build	BUILD_ALL	Full pipeline: clean → tests → theme → package
npm run history	SHOW_VERSION_HISTORY	Prints the formatted version history from RELEASES.json to the console
npm run accounts	ACCOUNTS	Read-only listing of production LICENSE_KV registrations (--status, --edition; token from CLOUDFLARE_API_TOKEN or website/.env)
npm run website	BUILD_WEBSITE	Turns README language sections into website/ (all languages selectable; / follows the browser language)
npm run website:deploy	DEPLOY_WEBSITE	Builds, tests and publishes website/ to Cloudflare Worker microgulp-web (microgulp.dev; local Wrangler login)
npm run backup	BACKUP_TO_NAS	Incremental robocopy mirror to Z:\\Projects\\microGulp (override with MICROGULP_NAS_BACKUP)
—	PUBLISH_API	Publishes gulp-mu-gulp-api to npm (runs its tests first; npm login required)
—	CLEAN	Removes tmp/ and packages/ (exclusive, write lock)

Notas:

• gulp-mu-css está cableado como dependencia file: local en C:\Projects\microCSS\gulp-mu-css y — como todo paquete pesado — solo se carga dentro del cuerpo de la tarea vía await import().
• BUILD_PACKAGE produce un .vsix real una vez instalado @vscode/vsce (npm i -D @vscode/vsce); sin vsce la tarea cae a un zip de la carpeta de staging.
• Los skins son autónomos: un directorio por skin bajo skins/ (p. ej. skins/neon-carbon/, skins/ice-light/, skins/ide-dark/), cada uno con un manifiesto <name>.µcss.mjs y una fuente <name>.µ.css del mismo nombre. CREATE_THEME_DATA descubre y construye cada skin; neon-carbon (oscuro) es el default e ice-light entrega un compañero de cristal esmerilado claro. ide-dark / ide-light son superficies sencillas estilo VS Code sin tejido carbon ni pulso neón. Se pueden dejar skins adicionales/de usuario como directorios hermanos. El selector de skin del panel (Settings → Appearance) ofrece un modo Automatic que sigue el tema claro u oscuro IDE/OS (mapea a ice-light / neon-carbon).
• El webview prefiere automáticamente el skin default generado (src/webview/skins/neon-carbon/dashboard.css); el dashboard.css escrito a mano permanece como fallback para checkouts frescos.
• La cabecera del panel muestra la marca del microscopio amarillo (baselogo.svg) vía inlining data-URI de µCSS junto al título neón µGulp™ (background-image: µ(DataUri("imgs/baselogo.svg"))). La única fuente de verdad de los assets artísticos terminados es dev/media/final/; el build sincroniza desde ahí media/logo.png (icono de extensión), media/logo_readme.png (README), src/webview/skins/<name>/imgs/baselogo.svg (panel) y jetbrains/resources/icons/baseoutlinelogo.svg (ventana de herramientas JetBrains + lista de plugins).

Este repositorio también entrega demo/gulpfile.mjs para el desarrollo local:

npm run demo          # headless engine smoke test
npm run demo:web      # browser dashboard (microgulp-serve --http)
npm run demo:ide      # Extension Development Host with demo/ as the workspace

F5 en VS Code/Cursor (configuración de lanzamiento "Run µGulp Extension") abre el mismo workspace de demo.

Pruébalo

Extensión instalada: Paleta de comandos → µGulp: Open Sample Project (JetBrains: Tools → µGulp: Open Sample Project). Eso copia un gulpfile de ejemplo con tareas Demo y Build (progreso, formularios, registros estructurados, sonidos, modales) a ~/.microgulp/sample y lo abre. Luego µGulp: Open Dashboard. El manual de usuario está en Settings → Handbook (o µGulp: Open Handbook); allí aparecen todos los idiomas del panel.

Manuales PDF: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어

Licencia

µGulp™ (extensión, motor, panel, adaptador JetBrains) es software propietario — véase LICENSE. Puede usar los binarios distribuidos de forma gratuita; copiar, modificar o redistribuir el código fuente no está permitido.

El paquete npm compañero gulp-mu-gulp-api permanece bajo la licencia MIT para que las tareas Gulp puedan adoptarlo sin restricciones.

Hoja de ruta / puntos abiertos de este borrador

Entregado en V0.5.0

• [x] Capa i18x en el webview: ajuste de idioma (automatic/en-US/de-DE/zh-CN/fr-FR/es-ES/ru-RU/ja-JP/ko-KR), cadenas GUI con etiqueta de contexto, definiciones de formato tomadas del servidor i18xe — la conexión directa al servidor i18xe sigue después
• [x] Metadatos de tarea µ: .i18xRegister() registra frases para i18xe/panel; traducción y marcadores en el render del panel vía i18x-catalog + µI18xContext; consola vía .i18xTrans() / Log()
• [x] API pública de tareas **gulp-mu-gulp-api** en npm (progreso, sonido/voz, formularios interactivos con fallbacks CLI; IsMicroGulp, InstallStringExtensions)
• [x] Bibliotecas de prompts heredadas (inquirer, gulp-prompt, prompts) redirigidas a formularios del panel sin editar gulpfiles
• [x] Controles de formulario ampliados del panel (radio, range, textarea, password, number, date/time, file, checkbox de selección múltiple)
• [x] Ajustes del panel (control acústico, salida de voz, recordatorio de formulario, manejo de errores, idioma)
• [x] Render de consola en los sectores de tarea (colores ANSI, sobrescritura de línea de progreso \r, marcas de tiempo)
• [x] Historial persistente de tareas y redirección de registro a archivos (.log crudo + .ndjson estructurado, índice history.ndjson, retención, panel de historial)
• [x] microgulp.config.json para defaults de equipo/CLI (ajustes IDE de PhpStorm + ajustes de extensión VS Code tienen prioridad cuando están definidos)
• [x] Orden de tareas del panel vía µOrder (ascendente; grupos por el mínimo del subárbol)
• [x] Fase 2: adaptador JetBrains — ventana de herramientas JCEF + sidecar Node + panel HTTP/SSE + Settings → Tools → µGulp (todos los IDEs basados en IntelliJ)
• [x] Elevación UAC de Windows opcional por tarea (µRequiresElevation, µElevationReason) — el IDE se queda no-admin
• [x] Localización del panel documentada: en-US / de-DE / zh-CN / fr-FR / es-ES / ru-RU / ja-JP / ko-KR empaquetados; los proyectos consumidores solo aportan i18x/gulp
• [x] Panel multi-skin (Neon Carbon, Ice Light, IDE Dark/Light) + packs ZIP de tema globales (import Appearance; sonidos/gráficos opcionales)
• [x] Atlas de sonido µAU por tema (default/ + overrides de skin, deduplicación PCM); catálogo en dev/docs/MicroGulpSoundSchema.md
• [x] Fuentes de proyecto para iconos de tarea / registro (RegisterDashboardFont, µIconFont, dashboardFonts; gulp-mu-gulp-api 0.3.12)
• [x] Atajos de tarea (µKeyBinding, acordes por plataforma, insignia de conflicto) + µGulp: Run Task para atajos globales del IDE
• [x] Parámetros de tarea declarativos (µParameters, GetParameters(), respuestas recordadas, secretos enmascarados)
• [x] Tareas watch / disparo (globs µWatch, debounce, disyuntor de descontrol, interruptor del panel)
• [x] Cierre automático por tarea (µAutoClose: -1 mantener abierto, segundos positivos, si no los ajustes)
• [x] Ubicaciones de error clicables en el registro de ejecución (pestaña de editor VS Code, puente JCEF de PhpStorm)
• [x] Matriz CI sobre Windows / Linux / macOS en Node 22 y 24
• [x] Sincronización sin conexión de diccionarios i18x/gulp en el panel (parser i18xe-sync, diálogo de idioma destino, formatos estándar, <lid>.status.json para traducción IA)

Aún abierto

• [ ] Documentar µLib (microLib), luego adoptarlo como capa de utilidades en µGulp (i18x hoy es un subconjunto webview local)
• [ ] Conexión i18xe-server directa: sincronización de traducción en vivo en lugar de los diccionarios empaquetados
• [ ] Ampliar GUI.mjs de µLib con controles especiales adicionales para los formularios del panel
• [ ] Pulido visual del panel webview
• [ ] Ampliar el skin µCSS: añadir la fuente de símbolos y los sprites al manifiesto
• [ ] Salida de voz vía i18xe (las muestras del atlas ya sustituyen los beeps WebAudio cuando están presentes)
• [x] Plugin JetBrains: Settings → Tools → µGulp (opciones del motor)
• [ ] Distribución JetBrains Marketplace (aplazada — solo instalación ZIP local por ahora)
• [ ] Publicar la extensión VS Code/Cursor en un marketplace (aplazado — entregar vía GitHub Releases / packages/*_latest.* por ahora)

---

Русский

Rock your Gulp!

µGulp™ — интерактивный оркестратор задач с почти нулевой задержкой, богатой визуализацией, элементами управления webview и звуковой обратной связью — поставляется как расширение IDE в трёх изданиях (VS Code / Cursor с регистрацией, VS Code / Cursor Free, IDE JetBrains) с webview-панелью Carbon/Neon.

Особенности

µGulp™ поставляется как µGulp™ (VS Code / Cursor), µGulp™ Free (VS Code / Cursor) и µGulp™ для IDE JetBrains (IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip и другие IDE на базе IntelliJ). Разделение ниже — текущий план и ещё может измениться до публичного запуска marketplace. Не устанавливайте зарегистрированное расширение VS Code и µGulp™ Free рядом — у них одни и те же ID команд. Зарегистрированное издание VS Code нужно зарегистрировать до запуска задач — либо удалите его и используйте µGulp™ Free.

	µGulp™ VS Code / Cursor	µGulp™ Free VS Code / Cursor	µGulp™ JetBrains IDEs
Цена (месяц / год)	0 € / $0	0 € / $0	0 € / $0
Панель задач, preload, i18x, параметры, µWatch, история	да	да	да
Лицензия / регистрация	обязательна	нет	нет
Скины (Neon Carbon, Ice Light, IDE Dark / Light, Automatic)	да	IDE Dark / Light по теме IDE (не выбирается)	да
Пользовательские ZIP-пакеты тем	да	—	да
Движок диагностики	да	—	да
Повышение прав UAC Windows	да	—	да
Настройки хоста	microgulp.*	microgulp.*	Settings → Tools → µGulp
Marketplace (карточка ещё не публична)	VS Code · Open VSX	VS Code · Open VSX	JetBrains (de.amekudzi.microgulp)

Все издания сейчас бесплатны (0 € / $0 в месяц и в год). Пункты ниже описывают полный продукт. Free следует теме IDE/ОС с IDE Dark / IDE Light (без выбора Appearance) и не включает пакеты тем, диагностику и повышение прав.

• Предзагруженные worker'ы — тёплые процессы Node с уже импортированным gulpfile; почти нулевая задержка от клика до запуска (избегает холодного сканирования антивируса)
• Сгруппированный список задач с иконками и локализуемыми текстами — вложенность через пути µGroup (Build/Production), сворачиваемые группы, µIcon (глиф или изображение) и µDisplayName / µDescription / µTooltip, зарегистрированные через .i18xRegister() и переводимые на лету через i18x-catalog; µOrder сортирует задачи и группы
• Параллельная сетка задач — несколько изолированных секторов запуска рядом, у каждого свой поток журнала
• Веб-панель — живые ANSI-журналы, фильтрованный вывод, детерминированные полосы прогресса, богатые формы для ввода пользователя (текст, цвет, шрифт, select, multiselect, …)
• Живое наблюдение за gulpfile — watcher рабочей области пересканирует при сохранении и автоматически заменяет устаревшие worker'ы
• Без привязки — метаданные с префиксом µ невидимы классической CLI gulp, и у каждого помощника API есть CLI-запасной путь, поэтому тот же gulpfile выполняется без изменений с µGulp™, без него и после удаления (подробности)
• Gulp-задачи, готовые к i18n — .i18xRegister() регистрирует фразы метаданных (встроенные контекстные теги у отображаемых имён, описаний, подсказок, групп) в словаре проекта и возвращает американский английский источник без изменений; панель переводит их позже через i18x-catalog с подстановками (version, project, …) из µI18xContext. Консольный вывод использует .i18xTrans() / Log() для немедленного перевода, включая разрешение подстановок
• Локализация панели — встроенные GUI-словари для en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP и ko-KR (настройки: автоматически или фиксированная локаль); другие языки планируются через i18xe sync. Руководство пользователя поставляется как PDF на языке панели
• Синхронизация словарей для ваших gulpfile — Settings → Project i18x (gulp) сканирует исходники парсером i18xe-sync, пишет i18x/gulp/<lid>.json для выбранных языков, сохраняет существующие переводы и сливает стандартные форматы; соседний <lid>.status.json перечисляет, что ещё должна перевести локальная ИИ
• Декларативные параметры задачи — µParameters спрашивает один раз перед запуском, передаёт значения как MICROGULP_PARAMS / GetParameters(), запоминает последние ответы, не пишет пароли в журналы и может скрывать поля через visibleWhen
• Watch / триггерные задачи — глобы µWatch запускают задачу при изменении файлов, с debounce, объединением и предохранителем от разгона; вооружаются по задаче с панели
• Горячие клавиши задач — аккорды µKeyBinding с вариантами по платформе (ctrl+shift+F1, cmd+shift+Escape), значки и предупреждения о конфликтах; µGulp: Run Task для глобальных сочетаний IDE
• Структурированный журнал — задачи испускают JSON-нагрузки, которые рисуются прямо в журнале запуска (таблицы, деревья, галереи изображений, выноски, метрики ключ/значение, статусные значки, блоки кода, столбчатые диаграммы inline-SVG) — безопасно для Content-Security-Policy, без плагина и iframe; ширина диаграмм ограничена, заголовки/строки LogTable используют цвета скина с наведением
• Постоянная история задач и файловый журнал — каждый запуск пишется в .microgulp/logs (сырой .log + структурированный .ndjson), индекс history.ndjson переживает переподключения/перезапуски IDE; панель истории открывает каждую расшифровку (logToFile, logRetention)
• Модальные диалоги — ShowModalMessage / ShowConfirmMessage как стеклянные панели в стиле AiDPix на панели (информация/предупреждение/ошибка, Да/Нет, OK/Отмена); опциональные нативные модалки VS Code/Cursor через presentation или microgulp.modalPresentation (gulp-mu-gulp-api); отдельный раздел README
• Кликабельные места ошибок — file:line:column в журнале запуска открывается в редакторе хоста (вкладка VS Code, редактор IDE JetBrains)
• Матрица параллелизма — эксклюзивные запуски по задаче и правила allow/deny (µExecutionConcurrency, µExecutionRestrictions)
• Скины панели — Neon Carbon, Ice Light, плюс простые IDE Dark / IDE Light; выбор Appearance с Automatic (следовать теме IDE/ОС) (Free: IDE Dark / IDE Light по теме IDE, не выбирается)
• Пользовательские ZIP-пакеты тем — глобальная установка (~/.microgulp/themes); пакеты могут включать CSS, графику, шрифты и опциональные звуковые атласы; импорт/удаление в Settings → Appearance (нет в Free)
• Шрифты проекта для иконок и журналов — RegisterDashboardFont / µDashboardFonts / dashboardFonts для глифа µIcon и шрифтов журнала запуска; опциональный µIconFont на задачу (gulp-mu-gulp-api 0.3.12)
• Опциональное акустическое управление — звуки завершения, сигналы ошибок и речь (настройки панели)
• Опциональное напоминание о форме — когда задача ждёт ввода на панели, напомнить пользователю после настраиваемой задержки звуком и/или речью; повторяется, пока форма не отвечена
• Автозакрытие завершённых запусков — опциональный отсчёт в заголовке сектора (клик, чтобы оставить открытым); задача перекрывает это через µAutoClose (-1 оставить открытым, положительное число = секунды, без указания — Settings → Finished Runs, по умолчанию 30 с); Restart рядом с Close
• Повышение прав администратора Windows — опциональный запрос UAC на задачу (µRequiresElevation, µElevationReason); IDE может работать обычным образом, пока отдельные задачи (например правка hosts) идут с повышенными правами (зарегистрированный VS Code / JetBrains; нет в Free)
• Движок диагностики — ошибки импорта и трассировки стека становятся практичными подсказками на панели (зарегистрированный VS Code / JetBrains; нет в Free)
• <version/> из gulpfile — µI18xContext.version — предпочтительный источник для заголовков задач; опциональный versionSources заполняет только когда gulpfile не задаёт version (без перезаписи конфигов релиза потребителя)
• Надёжный LogError против предупреждений Node — LogError / настоящий console.error по-прежнему валят запуск; DeprecationWarning Node и прочие предупреждения процесса — нет (баннер сбоя показывает первый настоящий текст ошибки)
• Мост устаревших prompt'ов — inquirer / gulp-prompt / prompts перенаправляются в формы панели без правки gulpfile
• gulp-mu-gulp-api — npm-модуль для прогресса, звука, речи, интерактивного ввода, модальных диалогов и шрифтов панели изнутри задач

Снимок

Hosts	VS Code, Cursor AI, JetBrains IDEs (Settings → Tools → µGulp), любой браузер на 127.0.0.1 через microgulp-serve --http
Runtime	Node.js 22+ (ESM)
Gulpfiles	Один gulpfile.mjs или regex-обнаружение по рабочей области
Config	Настройки расширения (VS Code/Cursor), Settings → Tools → µGulp (JetBrains), опциональный microgulp.config.json (команда / CLI)
Engine	Независим от IDE — тот же src/engine в каждом хосте
Языки	GUI панели: en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR (встроены); вывод gulp через проектный i18x/gulp/; руководство как PDF на языке панели
Порядок задач	µOrder (возрастающее целое); группы по минимальному порядку в поддереве; задачи без порядка в конце (по алфавиту)

Клик по задаче → тёплый worker запускает её сразу. Правка gulpfile → список задач обновляется сам. Несколько задач могут идти параллельно; каждая получает свой сектор панели с неоновой полосой прогресса, когда задача вызывает ReportProgress из gulp-mu-gulp-api.

Без привязки: gulpfile остаётся обычным gulpfile

Внедрение µGulp™ не делает сборку зависимой от µGulp™. Gulpfile, подготовленный для панели, по-прежнему выполняется классической CLI gulp, в CI и на машинах, где µGulp™ никогда не ставили — и продолжает работать после удаления µGulp™.

Обратная совместимость — всё деградирует до обычного gulp

Что вы добавляете	Что с этим делает обычный gulp
µDisplayName, µIcon, µGroup, µOrder, µKeyBinding, µWatch, µAutoClose, µRequiresElevation, …	Ничего. Это обычные свойства экспортированной функции; CLI gulp адресует задачи по имени экспорта и игнорирует неизвестные свойства. Имена задач и CLI-адресация не тронуты — именно поэтому существует префикс µ
µParameters	Не спрашиваются. Задача читает GetParameters() / GetParameter(id, fallback), которые падают на объявленные значения по умолчанию или на переменные окружения MICROGULP_PARAMS / MICROGULP_PARAM_<ID>, которые можно задать вручную в CI-задании
ReportProgress(...)	Печатает строку процентов в stdout (одна строка \r на TTY, урезанные строки в CI) вместо неоновой полосы
RequestForm, ShowModalMessage, PlaySignal, Speak, LogTable, LogChart, …	У каждого помощника есть CLI-запасной путь: запросы разрешаются в значения по умолчанию, модалки печатают строку в скобках и возвращают ok, звук и речь — пустые операции, структурированные журналы идут текстом
.i18xRegister() / .i18xTrans()	i18xRegister() возвращает американский английский исходник без изменений; i18xTrans() падает на исходный текст, когда словаря нет. Без µGulp™ вы просто получаете английский вывод в консоль
.microgulp/ (журналы, запомненные параметры)	Пишется только когда µGulp™ запускает задачу. Это одноразовый кэш-каталог — добавьте его в .gitignore и удаляйте когда угодно

gulp-mu-gulp-api — обычный npm-пакет без зависимостей времени выполнения, а IsMicroGulp() сообщает задаче, оркестрируется ли она. Убрать µGulp™ значит удалить расширение — правки gulpfile не нужны.

Прямая совместимость — новые версии µGulp™ не ломают старые gulpfile

Метаданные аддитивны, неизвестные ключи игнорируются с обеих сторон. Gulpfile, написанный под более новый µGulp™, выполняется в более старом, просто без новых функций (нет значка сочетания, нет переключателя watch, нет формы параметров — задача всё равно стартует). Неизвестные форматы структурированного журнала пропускаются, а не ломают запуск, и протокол хоста несёт номер версии, чтобы устаревший хост заметил несовпадение, а не истолковал его неверно.

Практический итог: можно попробовать µGulp™ на производственном скрипте сборки, отдать тот же репозиторий коллеге, который запускает npx gulp BUILD в терминале, и ни одна сторона не заметит другую.

Установка

Страницы marketplace зарезервированы, но ещё не публичны (исходный репозиторий всё ещё закрыт). Пока карточки не выйдут в эфир, ставьте из пакетов этого репозитория / GitHub Release.

Издание	Пакет	Marketplace (планируется)
µGulp™ (VS Code / Cursor)	packages/microgulp_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ Free (VS Code / Cursor)	packages/microgulp-free_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ (JetBrains IDEs)	см. IDE JetBrains ниже	JetBrains Marketplace (plugin id de.amekudzi.microgulp)

Локальная установка VSIX:

code --install-extension packages/microgulp_latest.vsix       # VS Code, registered
cursor --install-extension packages/microgulp_latest.vsix     # Cursor AI, registered
code --install-extension packages/microgulp-free_latest.vsix  # VS Code, Free

• Сборка из исходников: npm install, затем npm run build — зарегистрированный и Free .vsix попадают в packages/.

Затем выполните µGulp: Open Dashboard из палитры команд (или нажмите ракету µGulp™ в строке состояния).

IDE JetBrains

Плагин JetBrains — платформенный плагин (com.intellij.modules.platform) — ставится в IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip и другие IDE на базе IntelliJ. Поставляется двумя пакетами — выберите тот, что соответствует сборке вашей IDE (Help → About):

IDE build	since-build	Пакет
2024.2 – 2026.1 (до 261.*)	242	packages/microgulp-jetbrains_latest.zip
2026.2 и новее	262	packages/microgulp-jetbrains-2026.2_latest.zip

Берите подходящий zip. IntelliJ IDEA, PhpStorm, WebStorm и остальные IDE на базе IntelliJ делят эти два пакета — выбирайте по сборке платформы, не по имени продукта. В дескрипторе каждого пакета стоит <idea-version since-build="…"/> — IDE не загрузит другой. microgulp-jetbrains — since-build="242" / until-build="261.*" (2024.2–2026.1). microgulp-jetbrains-2026.2 — since-build="262" без верхней границы (2026.2+). Сборку платформы показывает Help → About.

Карточка JetBrains Marketplace (id плагина de.amekudzi.microgulp) использует латинское имя MicroGulp — µ и ™ в <name> недопустимы. Дашборд, окно инструментов, сайт и этот README сохраняют µGulp™. Оба zip делят этот id. Версии plugin.xml выводятся из единственной версии продукта в RELEASES.json как SemVer-prerelease (<продукт>-idea242, <продукт>-idea262; Marketplace SemVer Only), кроме продукта 0.9.3 на канале 242–261.* — там остаётся версия marketplace 0.9.3 (уже подана). Пакет 262 для 0.9.3 — 0.9.3-idea262. VS Code / Free оставляют версию продукта без суффикса. Имена zip остаются *_V<продукт>.zip. Оба пакета JetBrains несут один и тот же журнал версии продукта. Лицензия: https://microgulp.dev/en/license/. Исходный репозиторий остаётся закрытым — не публикуйте URL исходного кода на карточке Marketplace.

Сборка 262 вынесла JCEF из ядра платформы в комплектный плагин Web Browser (JCEF), поэтому дескриптор должен объявить его явно — отсюда отдельный пакет. Установка через Settings → Plugins → ⚙ → Install Plugin from Disk…, затем откройте окно инструментов µGulp. Параметры движка — в Settings → Tools → µGulp (путь Node, обнаружение gulpfile, preload/pool, watch, журналы запусков) — та же роль, что у настроек VS Code microgulp.*. Внешний вид, звук и язык остаются в панели ⚙ дашборда. Плагин — тонкий адаптер JCEF: весь движок работает в комплектном sidecar Node.js, поэтому должен быть установлен Node.js 22+ (PATH, MICROGULP_NODE или настройка пути Node). Если JCEF недоступен — урезанные сборки IDE, отключённый браузерный плагин — окно инструментов всё равно запускает движок и предлагает кнопку, открывающую панель в обычном браузере.

Сборка и проверка пакетов

npm run jetbrains (псевдоним npm run phpstorm) собирает оба zip, npm run jetbrains:verify проверяет их. Без Gradle:

• Каждый пакет компилируется против самой старой платформы IntelliJ, которую он поддерживает — пакет 242 против IDE 2024.2, пакет 262 против установленной IDE. Тогда javac отвергает API, которая есть только в более новой сборке, вместо того чтобы её выпустить. Адаптер использует только платформенные API (окно инструментов, настройки, JCEF, редактор), поэтому один и тот же zip работает в каждой IDE на базе IntelliJ.
• npm run jetbrains:verify гоняет JetBrains Plugin Verifier по обоим zip, на обоих концах заявленного диапазона (2024.2 и 2026.1 для legacy-пакета, 262 для другого). Сообщает о недостающих классах и методах, устаревшем или внутреннем API и дефектах дескриптора.
• Fat-jar Plugin Verifier лежит в dev/tools/intellij-plugin-verifier/ (verifier-cli-1.410-all.jar; при отсутствии скачивается с Maven Central). Нужные дистрибутивы платформы IntelliJ скачиваются один раз в MICROGULP_IDE_CACHE (по умолчанию %LOCALAPPDATA%\microgulp\ide-cache, иначе ~/.cache/microgulp/ide-cache) и переиспользуются; локально установленная IDE используется напрямую, когда её сборка совпадает. MICROGULP_SKIP_IDE_DOWNLOAD=1 сохраняет офлайн-сборки — они тогда компилируются против установленной IDE и пропускают отсутствующие цели проверки.
• Чего верификатор не видит: он разрешает против всей IDE и игнорирует изоляцию classloader модулей содержимого, поэтому отсутствующая зависимость модуля всё ещё читается как совместимая. Поэтому сборка отказывается упаковывать пакет для сборки 262+, который трогает JCEF, не объявив com.intellij.modules.jcef и его два модуля.

Известный шум журнала JetBrains / JCEF (безвредный)

В первый раз, когда окно инструментов µGulp встраивает панель, журнал IDE может показать ошибку вроде:

JBCefApp$Holder <clinit> requests ProxyMigrationService instance. Class initialization must not depend on services.

Это идёт из собственного стека JCEF JetBrains (JBCefApp → настройки прокси → HttpConfigurable), не из плагина µGulp. Платформа всё равно завершает запуск JCEF; если панель потом появляется, запись можно игнорировать. Это не связано с PhpStorm 2025 vs. 2026 — любая IDE JetBrains с той же сборкой JCEF может это выдать. Разбирайтесь дальше только если окно инструментов остаётся пустым или показывает настоящую ошибку запуска µGulp (путь Node, sidecar, сканирование gulpfile).

Та же панель работает и в любом обычном браузере: npm run serve -- --cwd <project> --http 9310 --preload, затем откройте http://127.0.0.1:9310/.

Файл конфигурации microgulp.config.json (JetBrains и CLI)

В VS Code / Cursor движок настраивается через настройки расширения (microgulp.gulpfilePattern и т. д.). Плагин JetBrains отражает эти параметры движка в Settings → Tools → µGulp (передаются как CLI-флаги sidecar при следующем открытии окна инструментов). Опционально корневой microgulp.config.json по-прежнему даёт командные значения по умолчанию и ключи, которых нет на странице IDE (dashboardFonts, metadataWatchFiles, versionSources). Обычное CLI/браузерное использование через microgulp-serve читает файл, когда CLI-флаг не задан:

{
	"gulpfilePattern": "gulpfile.*\\.mjs$",
	"poolSize": 2,
	"maxParallel": 6,
	"preload": true,
	"watchGulpfiles": true
}

Key	Type	Default	Meaning
gulpfile	string	"gulpfile.mjs"	Single gulpfile, relative to the project root
gulpfilePattern	string	—	Case-insensitive regex against workspace-relative POSIX paths; discovers all matching gulpfiles (wins over gulpfile)
poolSize	int ≥ 0	2	Warm workers per gulpfile
maxParallel	int ≥ 1	6	Maximum concurrent task runs
preload	bool	false	Warm up the worker pools right after startup (PhpStorm IDE setting defaults to on; CLI needs --preload)
watchGulpfiles	bool	true	Auto-rescan on gulpfile changes
metadataWatchFiles	string[]	["package.json", "RELEASES.json"]	Optional. Workspace-relative files whose changes trigger a metadata rescan (e.g. after a version bump). Prefer watching the file your gulpfile reads at init.
versionSources	string[] or objects	["package.json"]	Optional. Live JSON fallback for <version/> when the gulpfile does not set µI18xContext.version. Rarely needed for consumer projects — see below.
dashboardFonts	array	—	Optional. Project fonts for task icons / run log (see Шрифты панели)
logToFile	bool	true	Persist run transcripts (.log + .ndjson) and the task history to disk
logDirectory	string	.microgulp/logs	Directory for transcripts and the history index, relative to the project root
logRetention	int ≥ 0	200	Max runs kept in the history (0 = unlimited); older runs and their log files are pruned

Приоритет: командная строка / настройки IDE JetBrains > microgulp.config.json > встроенные значения по умолчанию. Неверные значения и неизвестные ключи игнорируются с предупреждением в stderr; файл версионируется и действует на всю команду. После правки настроек IDE или файла снова откройте окно инструментов µGulp (перезапускает sidecar) или перезапустите microgulp-serve.

В VS Code / Cursor те же ключи доступны как microgulp.metadataWatchFiles и microgulp.versionSources (непустые настройки расширения побеждают microgulp.config.json). Пустые массивы отключают наблюдение за метаданными или живое чтение версии из файлов.

<version/> в заголовках задач (предпочтительно vs опционально)

Предпочтительно (большинство проектов-потребителей): экспортируйте µI18xContext из gulpfile и задайте там version (читайте единственный источник релиза при инициализации модуля). Используйте metadataWatchFiles, чтобы изменения этого источника пересканировали и обновляли тёплые worker'ы:

export const µI18xContext = { project: 'MyApp', version: _ReadReleaseVersion() };
MAKE_BUILD.µDisplayName = 'Build V<version/><context="µDisplayName"/>'.i18xRegister();

{
	"metadataWatchFiles": ["configs/systemconfig.js"]
}

Когда задан µI18xContext.version, живые versionSources его не переопределяют.

Опционально — versionSources: полезно только если вы не задаёте µI18xContext.version и хотите, чтобы движок разрешал <version/> из JSON на диске (и обновлял его на GetTasksPayload без повторного импорта gulpfile). Поддерживаемые формы:

• "package.json" — использует поле npm "version"
• "RELEASES.json" — файл в стиле µGulp; точная схема в Версии (RELEASES.json) (releases[0].main / minor / revision)
• { "file": "config/version.json", "field": "version" } — любой JSON-файл + точечный путь поля

Пример (только опциональный живой JSON — без version в gulpfile):

{
	"metadataWatchFiles": ["package.json", "RELEASES.json"],
	"versionSources": ["RELEASES.json", "package.json"]
}

Логика: src/engine/ProjectMetadata.mjs; подстановки собираются в BuildSourceI18xContext.

Структура проекта

gulpfile.mjs             Project build: tests, theme CSS (µCSS), package + deploy
RELEASES.json            Version source (main/minor/revision, i18xe-ready info texts)
gulp-mu-gulp-api/        Standalone npm module: public task API
  src/index.mjs          Progress, text/color/font/select inputs, forms
  tests/                 The module's own node:test suite
skins/                   One directory per skin (neon-carbon is the default)
  neon-carbon/
    neon-carbon.µcss.mjs µCSS skin manifest (Carbon/Neon variables)
    neon-carbon.µ.css    Skin source → compiled into src/webview/skins/neon-carbon/
  ice-light/             Light frosted-glass skin (cool blue outward glow)
    ice-light.µcss.mjs   µCSS skin manifest (ice palette)
    ice-light.µ.css      Skin source → compiled into src/webview/skins/ice-light/
  ide-dark/              Plain IDE-aligned dark (VS Code–like, no neon/carbon)
  ide-light/             Plain IDE-aligned light companion
src/
  engine/                IDE-independent core (no VS Code APIs!)
    TaskEngine.mjs       Orchestrator: scan, preload, queue, events
    TaskWorkerPool.mjs   Pool of prewarmed worker processes
    ConcurrencyGuard.mjs Evaluates executionConcurrency/-Restrictions
    Diagnostics.mjs      Diagnosis engine (stack traces → concrete suggestions)
    PluginHost.mjs       Lifecycle hooks for plugins
    GulpfileDiscovery.mjs  Regex-based gulpfile discovery in the workspace
    ReleaseInfo.mjs      Release management: RELEASES.json, version strings, history
  worker/
    TaskWorker.mjs       Child process: imports the gulpfile, runs tasks
  bridge/
    gulp-ugulp-bridge.mjs  Public bridge: npm packages ↔ webview forms
  host/
    HostProtocol.mjs     Event/command names (the single host boundary)
    Daemon.mjs           Engine owner for sidecar hosts
    microgulp-serve.mjs  stdio NDJSON CLI (PhpStorm preparation)
  extension/
    extension.cjs        Thin VS Code / Cursor adapter (the only CJS module)
  webview/
    dashboard.css        Fallback stylesheet for fresh checkouts
    dashboard.js         TaskGrid, log streaming, forms, audio engine
    skins/<name>/dashboard.css  µCSS-generated skins (webview default: neon-carbon)
tests/                   node:test suites (unit + engine integration)
demo/
  gulpfile.mjs           Example gulpfile with every µGulp™ metadata tag
  run-demo.mjs           Headless engine smoke test (no IDE)
dev/
  prompts/               AI migration prompts (existing gulpfile → µGulp + i18x)
    OptimizeGulpfileForMicroGulp.md
    OptimizeGulpfileForMicroGulp.params.example.json

Принципы архитектуры

• Слой движка свободен от IDE. src/engine и src/worker не знают API VS Code. Связь идёт через события (движок → хост) и простые JSON-команды (хост → движок). Перенос на PhpStorm (фаза 2) поэтому — чистая смена адаптера; минимальный sidecar npm run serve (src/host/microgulp-serve.mjs, NDJSON на stdio) уже на месте.
• Предзагрузка задач. TaskWorkerPool держит прогретые процессы Node, в которых gulpfile уже импортирован. Запуск задачи отдаёт тёплый worker и пополняет пул в фоне. После запуска процесс выбрасывается (свежее состояние модуля).
• Динамические импорты. Тяжёлые npm-пакеты (mssql, docx-templates, makensis, …) должны загружаться только внутри тела задачи через await import() — статические импорты верхнего уровня зарезервированы для ядра оркестратора.
• Языки. Тексты GUI — американский английский и идут через String.i18xTrans() (проводка i18xe ещё впереди); комментарии в коде на английском; руководства/документация на немецком.

Локализация панели

GUI панели поставляется со встроенными словарями i18x для en-US (источник), de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP и ko-KR. Язык выбирается в настройках панели (automatic следует локали хоста или браузера). Консольный вывод gulpfile использует тот же язык через MICROGULP_LANG в worker и файлы проекта i18x/gulp/<lid>.json. Руководство пользователя поставляется как PDF на языке панели.

Чтобы посеять или обновить эти gulp-словари без сервера i18xe: Settings → Project i18x (gulp) → Scan & update i18x/gulp…. µGulp™ разбирает фразы сканером i18xe-sync (плюс Log/Warn/LogError), сохраняет существующие переводы, сливает стандартные определения форматов и пишет соседние <lid>.status.json (missing / orphans) для локального ИИ-перевода.

Layer	Who provides it	Today	Planned
Dashboard GUI	µGulp (extension)	en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR	More marketplace languages via the i18xe sync pipeline
Gulp tasks & logs	Your project	i18x/gulp/*.json next to the gulpfile	Same — consumer projects never ship i18x/prod
Hyphenation	µGulp webview assets	String.prototype.Hyphenation() with bundled <lid>.hyphen.json where present	Additional locales as hyphen data is synced from i18xe

Контекстные теги, обязательные форматы и языковая дорожная карта: dev/docs/MicroGulpI18xProfile.md. Живое подключение к серверу i18xe для GUI-словарей панели остаётся опциональным (дорожка 3); gulp-словари потребителя используют офлайн-сканирование выше.

Обнаружение gulpfile (настраивается regex)

µGulp™ сам замечает изменения gulpfile на диске: watcher рабочей области (microgulp.watchGulpfiles, включён по умолчанию) автоматически пересканирует после каждого изменения и меняет тёплые worker'ы на свежие с текущим кодом. Пока идёт сканирование, список задач показывает анимированный индикатор прогресса; у панели поэтому больше нет кнопки rescan — команда µGulp: Rescan Tasks (палитра команд) остаётся как ручное принудительное обновление. Если gulpfile не загружается (синтаксическая ошибка, отсутствующий модуль), в панели появляется закрываемый баннер ошибки с диагностикой и трассировкой стека.

µGulp™ находит gulpfile либо по одному пути, либо по regex-шаблону, который ищет по всей рабочей области:

• microgulp.gulpfilePattern — JavaScript-regex (без учёта регистра) против пути относительно рабочей области (POSIX с /). Когда задан, сканируется каждый подходящий файл; задачи группируются по источнику на панели. Пример: (^|/)gulpfile\.(m|c)?js$ находит gulpfile.mjs/.js/.cjs в корне и в каждой подпапке.
• microgulp.gulpfilePath — классический одиночный путь (по умолчанию gulpfile.mjs). Используется только пока gulpfilePattern пуст.

В node_modules, .git и скрытые папки (.*) никогда не спускаются. Каждый найденный gulpfile получает собственный пул тёплых worker'ов с папкой gulpfile как рабочим каталогом, поэтому вложенные подпроекты с относительными путями работают правильно. Логика обнаружения живёт независимо от IDE в src/engine/GulpfileDiscovery.mjs и поэтому доступна CLI и адаптеру JetBrains.

Когда совпадает больше одного gulpfile, левая колонка задач показывает заголовок источника на каждый файл скрипта (путь относительно рабочей области, напр. gulpfile.mjs, nested/gulpfile.mjs); задачи из разных файлов не смешиваются на верхнем уровне. Внутри каждого источника задачи по-прежнему вкладываются по пути µGroup (Build/Production, …). При одном gulpfile заголовок опускается — действует только вложенность µGroup. Если просканированные gulpfile экспортируют задачи, но ни один не импортирует gulp-mu-gulp-api, панель показывает закрываемую подсказку со ссылками на npm-пакет и промпт миграции ИИ.

Метаданные µGulp™ у задачи Gulp

Рекомендуемая форма — теги с префиксом µ в CamelCase (µDisplayName, µIcon, …) — они невидимы классической CLI gulp, поэтому gulpfile остаются полностью совместимы на системах без µGulp™ (CLI gulp адресует задачи через function.displayName; красивое имя с пробелами сломало бы адресацию задач там):

export async function BUILD_STYLES() { /* ... */ }
BUILD_STYLES.µDisplayName = 'Build Styles';
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.';
BUILD_STYLES.µTooltip = 'Runs the µCSS pipeline (sprites, fonts, sounds included).';
BUILD_STYLES.µIcon = '\u25A3';   // font symbol — or an image data URI:
// BUILD_STYLES.µIcon = 'data:image/svg+xml,%3Csvg ...';  (png/webp too)
BUILD_STYLES.µIconFont = 'ProjectIcons'; // optional — see Dashboard fonts below
BUILD_STYLES.µGroup = 'Build/Assets';                 // nested group (path syntax)
BUILD_STYLES.µOrder = 10;                             // sort position in the dashboard (ascending)
BUILD_STYLES.µExecutionConcurrency = true;            // false = exclusive
BUILD_STYLES.µExecutionRestrictions = { deny: ['CLEAN'] }; // parallel matrix
BUILD_STYLES.µKeyBinding = { key: 'ctrl+shift+B', mac: 'cmd+shift+B' }; // dashboard shortcut
BUILD_STYLES.µWatch = { files: ['skins/**/*.µ.css'] }; // optional file trigger
BUILD_STYLES.µAutoClose = -1;                         // keep the finished sector
BUILD_STYLES.µParameters = [                          // asked before the run
  { id: 'target', type: 'select', options: ['debug', 'release'], default: 'debug' },
];
// Windows only — show the UAC prompt when the host is not already elevated:
BUILD_STYLES.µRequiresElevation = true;
BUILD_STYLES.µElevationReason =
  'Modifies the Windows hosts file.<context="µElevationReason"/>'.i18xRegister();

µGroup назначает задачу вложенной группе в обзоре задач. Определение следует синтаксису пути каталога: µGroup = 'Build/Production' создаёт группу Build с подгруппой Production. Группы сворачиваются на панели; задачи без µGroup остаются на верхнем уровне. Назначение необязательно и чисто визуально — на выполнение и параллелизм не влияет.

µOrder задаёт позицию сортировки в левой колонке (возрастающее целое). Соседние задачи и группы упорядочиваются по µOrder; задачи без значения идут после всех упорядоченных (тай-брейк: отображаемое имя). Группы сортируются по наименьшему µOrder в своём поддереве.

Клавиши-модификаторы на заголовке группы:

Action	Effect
Click	toggle the group
Ctrl+Click (Cmd+Click)	toggle every group on the same level
Alt+Click	toggle all groups

µRequiresElevation помечает задачу, которой нужны права администратора в Windows (например перезапись C:\Windows\System32\drivers\etc\hosts). Когда IDE работает обычным образом, µGulp™ запускает одноразовый повышенный worker и показывает обычный диалог UAC — Cursor или VS Code не нужно запускать от администратора. Если процесс хоста уже повышен, используется пул тёплых worker'ов как обычно. На не-Windows платформах флаг игнорируется. Опциональный µElevationReason появляется в подсказке задачи (значок ⛿ на панели).

Горячие клавиши задач (µKeyBinding)

Задача может нести собственный клавиатурный аккорд. Аккорд работает пока фокус на панели — VS Code и PhpStorm не могут регистрировать сочетания во время выполнения, поэтому µGulp™ обрабатывает их сам, а не притворяется владельцем глобальных клавиш IDE.

BUILD.µKeyBinding = 'ctrl+shift+B';                      // same chord everywhere
DEPLOY.µKeyBinding = { key: 'ctrl+alt+D', mac: 'cmd+alt+D' };
STOP.µKeyBinding = { key: 'ctrl+shift+Escape' };         // named keys: F1…F24, Escape, Tab, Space, arrows, …

Part	Accepted
Modifiers	ctrl, control, alt, option, shift, meta, cmd, command, super, win
Keys	single characters (b, 7, +), F1–F24, Escape/Esc, Enter, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up/Down/Left/Right
Platform keys	key (fallback), mac, win, linux — the matching platform wins, key fills the rest

cmd соответствует клавише Command на macOS и Ctrl в остальных местах, поэтому один аккорд key остаётся usable на всех платформах. Аккорд появляется значком рядом с именем задачи; если две задачи заявляют один аккорд, оба значка становятся янтарными и подсказка об этом говорит (µGulp™ отказывается угадывать, какую вы имели в виду).

Для по-настоящему глобального сочетания IDE привяжите команду µGulp: Run Task сами — она принимает задачу как аргумент:

// keybindings.json (VS Code / Cursor)
{ "key": "ctrl+shift+f9", "command": "microgulp.runTask", "args": { "task": "gulpfile.mjs::BUILD_STYLES" } }

Без args команда открывает быстрый выбор просканированных задач.

Декларативные параметры задачи (µParameters)

Вместо запроса ввода из тела задачи задача может объявить, что ей нужно. µGulp™ показывает одну форму до старта, запоминает ответы на следующий раз и передаёт значения задаче через окружение:

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 = {
  submitLabel: 'Start Deploy<context="button text"/>'.i18xRegister(),
  fields: [
    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging',
      label: 'Target<context="task parameter"/>'.i18xRegister() },
    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
    { id: 'servers', type: 'checkbox', options: ['a', 'b'], required: true }, // submit stays disabled until ≥1
    { id: 'dryRun', type: 'boolean', default: true },
    { id: 'notify', type: 'boolean', default: false,
      visibleWhen: { dryRun: false } },   // only when not a dry run
    { id: 'token', type: 'password' },   // never stored, never logged
  ],
};

Простой массив полей по-прежнему работает. Обёртка добавляет оформление формы (title, submitLabel); µParameterSubmitLabel на задаче — равноценная альтернатива для текста кнопки.

Field	Meaning
id	required; must be env-var safe ([A-Za-z_][A-Za-z0-9_]*)
type	text (default), textarea, password, number, range, boolean (slide switch), checkbox (multi-select), radio, select, font, color
label, description, placeholder	shown in the form (i18x via .i18xRegister())
default	pre-filled value; a remembered answer from the last run wins
options	['a','b'], [{ value, label, disabled }] or { a: 'Label A' }
required, pattern, minLength, minSelected	validated live in the dashboard — the submit button stays disabled until every visible rule passes (required on a checkbox means at least one option)
min, max, step, rows	numeric / textarea details
remember	false keeps the value out of the store (implicit for password)
visibleWhen	show the field only while other answers match — e.g. { dryRun: false } or { servers: 'prod' } (multi-select: contains). Hidden fields are not validated; missing answers fall back to default
submitLabel / title	form wrapper keys (or µParameterSubmitLabel / µParameterTitle on the task) — i18x via .i18xRegister()

Значения приходят как MICROGULP_PARAMS (JSON) плюс плоский MICROGULP_PARAM_<ID> на параметр, поэтому шаги оболочки внутри задачи тоже могут их читать. GetParameters() / GetParameter('target', 'staging') из gulp-mu-gulp-api разбирают их; под обычной CLI gulp те же переменные можно задать вручную:

MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY

Ответы запоминаются по задаче в .microgulp/parameters.json и предзаполняют следующую форму. Пароли и значения remember: false не сохраняются и не пишутся в расшифровку, историю или панель — они показываются как ••••. Журнал запуска и запись истории фиксируют значения, с которыми стартовал запуск, чтобы потом было видно, что ответили. Повышенные задачи (µRequiresElevation) не могут показать форму из своего одностороннего процесса, поэтому идут с запомненными значениями поверх объявленных значений по умолчанию.

Watch / триггерные задачи (µWatch)

Задача может запускать себя, когда меняются файлы, которые ей важны:

BUILD_CSS.µWatch = 'src/**/*.µ.css';                  // shorthand
BUILD_CSS.µWatch = {
  files: ['src/**/*.µ.css', 'skins/*/manifest.json'], // globs, relative to the gulpfile
  ignore: ['**/*.tmp'],
  debounceMs: 300,                                    // quiet time after the last change
  autoStart: false,                                   // arm as soon as the gulpfile is scanned
  parameters: { target: 'debug' },                     // fixed µParameters for triggered runs
};

Наблюдение включается по задаче: рядом с именем задачи появляется переключатель ◉ (циан, когда вооружён), если декларация не говорит autoStart: true. Глобы поддерживают **, *, ?, {a,b} и классы символов; node_modules, .git, .microgulp, .idea и .vscode никогда не наблюдаются.

Ограничители, потому что задача сборки, которая пишет в свой же набор наблюдения, иначе крутилась бы вечно:

• пачка событий изменения становится одним запуском (debounce)
• пока запуск задачи активен, в очередь ставится не больше одного последующего запуска
• больше 20 сработавших запусков за минуту приостанавливают watcher (янтарный переключатель, подсказка объясняет почему); выключение и включение снова вооружает его

Сработавший запуск называет в журнале файл, который его вызвал (Triggered by src/a.css), и никогда не открывает форму параметров — триггер использует закреплённые или запомненные значения, поэтому никто не ждёт человека, который не смотрит.

Оставить завершённый запуск открытым (µAutoClose)

Завершённые секторы по умолчанию закрываются через 30 секунд (Settings → Finished Runs). Задача может это переопределить:

SHOW_OUTPUT.µAutoClose = -1;   // оставить сектор (без автозакрытия)
QUICK.µAutoClose = 8;          // закрыть через 8 секунд

Значение	Смысл
опущено / true	настройка панели (по умолчанию 30 с)
-1, false, 0	не закрывать эту задачу автоматически
положительное целое	закрыть через столько секунд (перекрывает задержку панели)

Жёлтый чип обратного отсчёта по-прежнему позволяет оставить сектор. µAutoClose — число или boolean — без .i18xRegister().

Кликабельные места ошибок

Ссылки на файлы в журнале запуска становятся ссылками: src/engine/TaskEngine.mjs:412:9, at Object.<anonymous> (gulpfile.mjs:88:15), вывод tsc/eslint и стиль MSBuild file(12,7). Клик (или Enter на ссылке) открывает этот файл на этой строке и колонке в редакторе хоста — вкладка редактора в VS Code/Cursor, редактор IDE через мост JCEF в PhpStorm.

Путь разрешается на стороне хоста сначала относительно каталога gulpfile запуска, затем корня рабочей области, поэтому рабочие области с несколькими gulpfile прыгают в правильную копию неоднозначного имени. Открываются только существующие файлы с расширениями исходников; URL, метки времени и номера версий не трогаются.

Пакеты тем (ZIP)

Пользовательские темы панели можно распространять как ZIP-пакеты и ставить глобально (на пользователя в ~/.microgulp/themes/, переопределение MICROGULP_THEMES_DIR). Они независимы от рабочей области проекта.

Раскладка пакета (прекомпилировано — исходник µCSS не нужен):

manifest.json     // { "id", "displayName", "version", "appearance": "dark"|"light" }
dashboard.css
imgs/…            // optional graphics / cursors
fonts/…           // optional
snds/…            // optional µAU atlas: microgulp.sounds.weba (or .wav/.mp3) + microgulp.sounds.json

На панели: Settings → Appearance → Import theme ZIP…. Встроенные скины остаются в выборе; Automatic по-прежнему отображается на Neon Carbon / Ice Light. Удалить пакет — Remove selected pack.

Из этого репозитория можно упаковать скомпилированный скин после npm run theme:

node dev/tools/pack-theme.mjs ide-dark
# → packages/microgulp-theme-ide-dark.zip

Звуковой атлас (µAU)

Сигналы панели собираются из dev/media/final/sounds/microgulp/: default/ — база каждого скина; опциональные папки <skin-id>/ перекрывают по основе имени файла. Атласы поставляются как WebA (только аудио WebM/Opus, microgulp.sounds.weba). Одинаковые сэмплы дедуплицируются. Полный каталог: dev/docs/MicroGulpSoundSchema.md.

PlaySignal('success'|'error'|'attention') отображается на taskSuccess / taskFailed / requestAlert; PlaySound использует имена схемы напрямую.

Шрифты панели (иконки задач и журнал)

Шрифты проекта независимы от встроенных скинов. Регистрируйте их в gulpfile (предпочтительно) или через microgulp.config.json / настройку microgulp.dashboardFonts:

import { RegisterDashboardFont } from 'gulp-mu-gulp-api';

RegisterDashboardFont({
  id: 'ProjectIcons',
  file: 'assets/task-icons.woff2',   // relative to the gulpfile directory
  usage: 'task-icons',               // or 'log' / 'all'
});

// Or declarative:
export const µDashboardFonts = [
  { id: 'ProjectLog', file: 'assets/log.woff2', usage: 'log' },
];

BUILD.µIcon = '\uE101';
BUILD.µIconFont = 'ProjectIcons';     // optional when a single task-icons font is registered

usage: 'task-icons' оформляет записи глифа µIcon (первый зарегистрированный шрифт — по умолчанию; µIconFont перекрывает на задачу). usage: 'log' задаёт гарнитуру журнала сектора запуска. Файлы должны оставаться под рабочей областью (woff2 / woff / ttf / otf).

Каскад запасных значений по свойству: µDisplayName → ugulp.displayName (объект пространства имён) → displayName (собственное поле Gulp) → имя экспорта. executionRestrictions поддерживает deny (всегда побеждает) и allow (белый список: всё неперечисленное запрещено).

Строки метаданных задачи используют i18x с контекстным тегом внутри фразы. .i18xRegister() только регистрирует фразу для i18xe-sync и словаря проекта — возвращает исходный текст без изменений; перевод происходит позже, когда панель рисует метаданные (TransProperty() через i18x-catalog), с подстановками вроде <version/> из µI18xContext. Для консольного вывода используйте .i18xTrans() или Log()/Warn()/LogError(), которые переводят сразу во время выполнения (включая подстановки):

BUILD_STYLES.µDisplayName = 'Build Styles<context="µDisplayName"/>'.i18xRegister();
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();

Контекстные теги, обязательные форматы и план языков marketplace: dev/docs/MicroGulpI18xProfile.md.

Миграция gulpfile с помощью ИИ

Чтобы мигрировать существующий большой gulpfile (консольный вывод, метаданные задач, словари i18x/gulp, опционально µKeyBinding / µParameters / µWatch / µAutoClose), используйте поддерживаемый промпт в репозитории:

File	Purpose
dev/prompts/OptimizeGulpfileForMicroGulp.md	Copy-paste prompt for Cursor, Claude, ChatGPT, …
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json	Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version)

Workflow

1. Скопируйте пример params в корень проекта как microgulp-optimize.params.json и заполните projectRoot, gulpfilePath, supportedLanguages (напр. en-US, de-DE, zh-CN), gulpMuGulpApiVersion (^0.4.0 или новее), microGulpMinVersion (0.7.0) и githubRepoUrl / githubRef (по умолчанию: https://github.com/mamekudz/microGulp, V0.7.0 или main).
2. Откройте markdown промпта, замените таблицу {{PLACEHOLDER}} своими значениями (или приложите файл params и gulpfile в Cursor).
3. Пусть ИИ выполнит миграцию. Шаг 0 в промпте обязателен: датированная резервная копия gulpfile (напр. gulpfile.mjs.20260703-142559.bak) до любой правки.
4. Проверьте node --check gulpfile.mjs, протестируйте задачи в панели µGulp (включая новые сочетания, пока фокус на панели), затем зафиксируйте gulpfile.mjs, i18x/gulp/*.json и package.json.

Проектам-потребителям нужен только i18x/gulp/<lid>.json — не i18x/prod. Промпт обновляется с релизами µGulp; перед миграцией сверьтесь с этим репозиторием. Он покрывает правила i18x (register vs. translate, без µMeta) и декларативный UX: µKeyBinding панели (не глобально в IDE, пока пользователь не привяжет microgulp.runTask), µParameters / GetParameters(), µWatch и µAutoClose.

Публичный API задач (gulp-mu-gulp-api)

Сторонние gulpfile и npm-пакеты внутри потока используют расширенные функции панели через автономный npm-модуль **gulp-mu-gulp-api** (живёт как свой проект в gulp-mu-gulp-api/, публикуется на npm отдельно):

import { ReportProgress, RequestTextInput, RequestColorInput, RequestForm, ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

export async function BUILD_THEME() {
    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
    let title = await RequestTextInput({ label: 'Product title', validate: { required: true, minLength: 3 } });
    let ok = await ShowConfirmMessage({
        title: 'Overwrite theme?',
        message: 'Existing skin files will be replaced.',
        presentation: 'webview',
    });
    if (ok.button !== 'yes') return;
    for (let step = 1; step <= 10; step++) {
        // ... work ...
        ReportProgress(step / 10, 'compiling theme');   // determinate neon progress bar in the sector
    }
    await ShowModalMessage({
        variant: 'info',
        title: 'Theme ready',
        message: 'Skin files written.',
    });
}

Модуль без зависимостей и говорит с движком напрямую по IPC-каналу worker'а µGulp™ (обнаружение через IsMicroGulp() / IsµGulp()). Без µGulp™ всё чисто деградирует: прогресс идёт в терминал, ввод через readline (TTY) или значения по умолчанию (CI). Подробности в gulp-mu-gulp-api/README.md. Внутренний модуль src/bridge/gulp-ugulp-bridge.mjs остаётся низкоуровневым транспортом; новым потребителям следует использовать gulp-mu-gulp-api.

Модальные диалоги (ShowModalMessage)

С V0.5.29 (API: gulp-mu-gulp-api 0.3.11+) задачи могут показывать блокирующие модальные диалоги — для подтверждений, предупреждений перед продолжением или Да/Нет и OK/Отмена. Используйте их умеренно (не для обычных строк журнала); для штатного вывода предпочитайте Log() / помощники структурированного журнала.

Стеклянные панели Webview (по умолчанию)

Когда presentation равно webview (значение по умолчанию), модалки рисуются внутри панели µGulp как стеклянные панели в стиле AiDPix/Oxyd:

Feature	Detail
Frame	9-slice glasspanel.png (glasspanel-ice.png in the ice-light skin)
Variants	info (turquoise header), warning, error — colored header bar per variant
Buttons	Carbon-styled actions; primary button highlighted
Overlay	Scroll the mouse wheel over the dimmed backdrop to adjust overlay brightness (8–88 %); long message bodies scroll inside the panel
Keyboard	Escape → cancel/no (or first button); Enter → primary button

Реализация: src/webview/WebviewModal.js, src/webview/webview-modal.css (загружаются webview VS Code и HTTP-панелью).

API

import { ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

// Single acknowledgment (default button: OK)
await ShowModalMessage({
    variant: 'warning',          // 'info' | 'warning' | 'error'
    title: 'Disk almost full',
    message: 'Less than 1 GB free on the build drive.',
    presentation: 'webview',     // optional — see below
});

// Yes/No confirmation (default style)
let answer = await ShowConfirmMessage({
    title: 'Overwrite output?',
    message: 'Existing files in dist/ will be replaced.',
});
if (answer.button !== 'yes') return;

// OK/Cancel preset
let discard = await ShowConfirmMessage({
    title: 'Discard changes?',
    message: 'Unsaved theme tweaks will be lost.',
    style: 'ok-cancel',          // default: 'yes-no'
});

Оба помощника возвращают Promise<{ button: string }> — напр. 'ok', 'yes', 'no', 'cancel' или пользовательские id кнопок из ShowModalMessage({ buttons: [{ id: 'retry', label: 'Retry', primary: true }] }).

CLI-запасной путь (обычный gulp, CI, без TTY): вывод в скобках и основная/кнопка по умолчанию — без блокирующего запроса.

Где появляется модалка (presentation)

Value	Behavior
webview	In-dashboard glass panel (default)
ide	Native VS Code / Cursor modal (showInformationMessage / showWarningMessage / showErrorMessage with { modal: true })
auto	Native IDE dialog when the Extension Host is available; otherwise the webview glass panel

presentation на вызов перекрывает значение хоста по умолчанию.

Значения хоста по умолчанию

Host	Setting
VS Code / Cursor	Extension setting microgulp.modalPresentation (webview | ide | auto, default webview)
Browser demo / PhpStorm JCEF	Dashboard Settings → Modal presentation (same three values)

Запасной путь: PhpStorm и браузерная панель всегда используют стеклянную панель webview — presentation: 'ide' там отображается на webview. Только Extension Host VS Code/Cursor может показывать нативные модалки IDE.

Попробовать демо

После µGulp: Open Sample Project панель показывает группу Demo:

Task	Effect
DEMO_MODAL_DIALOGS	All variants + Yes/No + OK/Cancel with presentation: 'webview'
DEMO_IDE_MODAL_DIALOGS	Same flow with presentation: 'ide' (native modals in Cursor/VS Code; webview fallback in PhpStorm / the browser)

Дальнейшие детали API: gulp-mu-gulp-api/README.md.

Сертификация µGulp ready

Npm-модули, чей корневой gulpfile полностью интегрирован с панелью µGulp, могут показывать значок µGulp ready на npm README и страницах проекта.

Requirement	Detail
Gulpfile	Exported tasks carry µGulp metadata (µDisplayName, µDescription, µGroup, …)
API	Uses gulp-mu-gulp-api for logging, progress and optional dashboard features
CLI fallback	Tasks remain runnable with plain gulp / npx gulp when µGulp is not installed
Badge asset	Canonical PNG: media/microgulp-ready.png in the µGulp repo. npm README: absolute raw URL (npm rewrites relative paths to microCSS/HEAD/... even inside HTML). Example: <a href="https://microgulp.dev"><img src="https://microgulp.dev/assets/media/microgulp-ready.png" alt="µGulp ready" width="150"></a>
package.json	Optional "microgulp": { "ready": true, "certifiedSince": "<semver>" } for machine-readable discovery

Сертифицированные модули

npm package	Since	Notes
gulp-mu-gulp-api	0.3.11	Official task API — Log, ReportProgress, i18x console layer, dashboard forms, ShowModalMessage / ShowConfirmMessage; npm README badge since 0.3.3
gulp-mu-css (µCSS™)	2.5.15	Monorepo root gulpfile.mjs with full task metadata, i18x/gulp/ (en-US, de-DE) and LogBuildDebugReport on demo builds; npm README badge via absolute raw URL since 2.5.14
gulp-mu-ps (µPS)	1.3.5	Test/render tasks in the shared root gulpfile (TEST_MICROPS, RENDER_EXAMPLES, …)
gulp-mu-ft (µFT)	0.1.5	Test task TEST_MICROFT in the shared root gulpfile
gulp-mu-au (µAU)	0.1.6	Test task TEST_MICROAU in the shared root gulpfile

Чтобы подать заявку на сертификацию, мигрируйте gulpfile с dev/prompts/OptimizeGulpfileForMicroGulp.md и откройте issue или PR в репозитории µGulp или модуля.

Версии (RELEASES.json)

Этот файл — собственный формат релиза µGulp — единственный источник истины этого репозитория. Проектам-потребителям RELEASES.json не нужен; они обычно держат версию продукта в своём конфиге (и отдают её через µI18xContext.version). Опциональный versionSources: ["RELEASES.json"] помогает только если вы принимаете ту же JSON-раскладку.

Каждая запись релиза несёт main/minor/revision, метку времени, флаг beta и список информационных текстов. Информационные тексты несут контекстный тег i18x <context="release info"/> и регистрируются через String.i18xRegister(), поэтому движок i18xe может переводить их автоматически.

Схема (новейший релиз первым — releases[0] текущий):

{
    "releases": [
        {
            "main": 0, "minor": 2, "revision": 0, "date": "2026-07-02 15:30", "beta": false,
            "info": [ "Release management added<context=\"release info\"/>" ]
        }
    ]
}

Когда versionSources включает "RELEASES.json", движок разрешает <version/> в "main.minor.revision" из releases[0] (напр. "0.2.0").

Модуль src/engine/ReleaseInfo.mjs предоставляет:

• GetVersionString() / GetFullVersionString() — "0.2.0" или "0.1.4ß" (суффикс ß для бета-сборок).
• GetVersionHistoryText({ maxReleases, includeBeta }) — полная история как форматированная строка для консоли (задача SHOW_VERSION_HISTORY или npm run history).
• BUILD_PACKAGE синхронизирует версию package.json и строку версии в начале этого README из RELEASES.json автоматически и штампует её в имя артефакта (microgulp_V0.2.0.vsix, беты с суффиксом _beta). Новому релизу нужна только новая запись в начале RELEASES.json.

Сборка проекта (gulpfile.mjs)

Проект собирает себя через собственный gulpfile (dogfooding: работает в панели µGulp™, через CLI gulp, через классические Gulp-расширения IDE и headless):

Invocation	Task	Purpose
npm test	RUN_TESTS	node:test suites in tests/ (unit + engine integration with real worker processes)
npm run theme	CREATE_THEME_DATA	Compiles every skins/<name>/<name>.µ.css via µCSS (gulp-mu-css BuildSkin) into src/webview/skins/<name>/dashboard.css (default: neon-carbon)
npm run package	BUILD_PACKAGE	Stages the extension into tmp/package/ and creates the .vsix in packages/ (also refreshed as microgulp_latest.vsix)
npm run deploy	DEPLOY_EXTENSION	Automated update cycle: build the .vsix and install it via cursor --install-extension (reload the window afterwards)
npm run build	BUILD_ALL	Full pipeline: clean → tests → theme → package
npm run history	SHOW_VERSION_HISTORY	Prints the formatted version history from RELEASES.json to the console
npm run accounts	ACCOUNTS	Read-only listing of production LICENSE_KV registrations (--status, --edition; token from CLOUDFLARE_API_TOKEN or website/.env)
npm run website	BUILD_WEBSITE	Turns README language sections into website/ (all languages selectable; / follows the browser language)
npm run website:deploy	DEPLOY_WEBSITE	Builds, tests and publishes website/ to Cloudflare Worker microgulp-web (microgulp.dev; local Wrangler login)
npm run backup	BACKUP_TO_NAS	Incremental robocopy mirror to Z:\\Projects\\microGulp (override with MICROGULP_NAS_BACKUP)
—	PUBLISH_API	Publishes gulp-mu-gulp-api to npm (runs its tests first; npm login required)
—	CLEAN	Removes tmp/ and packages/ (exclusive, write lock)

Замечания:

• gulp-mu-css подключён как локальная зависимость file: на C:\Projects\microCSS\gulp-mu-css и — как каждый тяжёлый пакет — загружается только внутри тела задачи через await import().
• BUILD_PACKAGE делает настоящий .vsix, когда установлен @vscode/vsce (npm i -D @vscode/vsce); без vsce задача падает на zip папки staging.
• Скины автономны: один каталог на скин под skins/ (напр. skins/neon-carbon/, skins/ice-light/, skins/ide-dark/), у каждого манифест <name>.µcss.mjs и одноимённый исходник <name>.µ.css. CREATE_THEME_DATA обнаруживает и собирает каждый скин; neon-carbon (тёмный) — значение по умолчанию, ice-light даёт светлого матового стеклянного компаньона. ide-dark / ide-light — простые поверхности в стиле VS Code без углеродного плетения и неонового пульса. Дополнительные/пользовательские скины можно класть соседними каталогами. Выбор скина панели (Settings → Appearance) предлагает режим Automatic, который следует светлой или тёмной теме IDE/ОС (отображается на ice-light / neon-carbon).
• Webview автоматически предпочитает сгенерированный скин по умолчанию (src/webview/skins/neon-carbon/dashboard.css); рукописный dashboard.css остаётся запасным для свежих checkout.
• Заголовок панели показывает жёлтую метку микроскопа (baselogo.svg) через встраивание data-URI µCSS рядом с неоновым заголовком µGulp™ (background-image: µ(DataUri("imgs/baselogo.svg"))). Единственный источник готовых художественных ассетов — dev/media/final/; сборка синхронизирует оттуда media/logo.png (иконка расширения), media/logo_readme.png (README), src/webview/skins/<name>/imgs/baselogo.svg (панель) и jetbrains/resources/icons/baseoutlinelogo.svg (окно инструментов JetBrains + список плагинов).

Этот репозиторий также поставляет demo/gulpfile.mjs для локальной разработки:

npm run demo          # headless engine smoke test
npm run demo:web      # browser dashboard (microgulp-serve --http)
npm run demo:ide      # Extension Development Host with demo/ as the workspace

F5 в VS Code/Cursor (конфигурация запуска "Run µGulp Extension") открывает ту же демо-рабочую область.

Попробовать

Установленное расширение: палитра команд → µGulp: Open Sample Project (JetBrains: Tools → µGulp: Open Sample Project). Это копирует пример gulpfile с задачами Demo и Build (прогресс, формы, структурированные журналы, звуки, модалки) в ~/.microgulp/sample и открывает его. Затем µGulp: Open Dashboard. Руководство пользователя — Settings → Handbook (или µGulp: Open Handbook); там перечислены все языки панели.

PDF-руководства: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어

Лицензия

µGulp™ (расширение, движок, панель, адаптер JetBrains) — проприетарное ПО — см. LICENSE. Распространяемые двоичные файлы можно использовать бесплатно; копирование, изменение или распространение исходного кода не разрешено.

Сопутствующий npm-пакет gulp-mu-gulp-api остаётся под лицензией MIT, чтобы задачи Gulp могли принимать его без ограничений.

Дорожная карта / открытые пункты черновика

Поставлено в V0.5.0

• [x] Слой i18x в webview: настройка языка (automatic/en-US/de-DE/zh-CN/fr-FR/es-ES/ru-RU/ja-JP/ko-KR), GUI-строки с контекстными тегами, определения форматов с сервера i18xe — прямое подключение к серверу i18xe позже
• [x] Метаданные задач µ: .i18xRegister() регистрирует фразы для i18xe/панели; перевод и подстановки при отрисовке панели через i18x-catalog + µI18xContext; консоль через .i18xTrans() / Log()
• [x] Публичный API задач **gulp-mu-gulp-api** на npm (прогресс, звук/речь, интерактивные формы с CLI-запасными путями; IsMicroGulp, InstallStringExtensions)
• [x] Устаревшие библиотеки prompt (inquirer, gulp-prompt, prompts) перенаправлены в формы панели без правки gulpfile
• [x] Расширенные элементы форм панели (radio, range, textarea, password, number, date/time, file, checkbox множественного выбора)
• [x] Настройки панели (акустическое управление, речь, напоминание о форме, обработка ошибок, язык)
• [x] Отрисовка консоли в секторах задач (ANSI-цвета, перезапись строки прогресса \r, метки времени)
• [x] Постоянная история задач и перенаправление журнала в файлы (сырой .log + структурированный .ndjson, индекс history.ndjson, удержание, панель истории)
• [x] microgulp.config.json для командных/CLI значений по умолчанию (настройки IDE PhpStorm + настройки расширения VS Code имеют приоритет, когда заданы)
• [x] Порядок сортировки задач панели через µOrder (по возрастанию; группы по минимуму поддерева)
• [x] Фаза 2: адаптер JetBrains — окно инструментов JCEF + sidecar Node + панель HTTP/SSE + Settings → Tools → µGulp (все IDE на базе IntelliJ)
• [x] Опциональное повышение прав UAC Windows на задачу (µRequiresElevation, µElevationReason) — IDE остаётся не-админом
• [x] Локализация панели задокументирована: встроены en-US / de-DE / zh-CN / fr-FR / es-ES / ru-RU / ja-JP / ko-KR; проекты-потребители поставляют только i18x/gulp
• [x] Многоскиновая панель (Neon Carbon, Ice Light, IDE Dark/Light) + глобальные ZIP-пакеты тем (импорт Appearance; опциональные звуки/графика)
• [x] Звуковые атласы µAU по теме (default/ + перекрытия скина, дедупликация PCM); каталог в dev/docs/MicroGulpSoundSchema.md
• [x] Шрифты проекта для иконок задач / журнала запуска (RegisterDashboardFont, µIconFont, dashboardFonts; gulp-mu-gulp-api 0.3.12)
• [x] Горячие клавиши задач (µKeyBinding, аккорды по платформе, значок конфликта) + µGulp: Run Task для глобальных сочетаний IDE
• [x] Декларативные параметры задачи (µParameters, GetParameters(), запомненные ответы, скрытые секреты)
• [x] Watch / триггерные задачи (глобы µWatch, debounce, предохранитель разгона, переключатель панели)
• [x] Переопределение автозакрытия у задачи (µAutoClose: -1 оставить открытым, положительные секунды, иначе настройки)
• [x] Кликабельные места ошибок в журнале запуска (вкладка редактора VS Code, мост JCEF PhpStorm)
• [x] Матрица CI по Windows / Linux / macOS на Node 22 и 24
• [x] Офлайн-синхронизация словарей i18x/gulp на панели (парсер i18xe-sync, диалог целевого языка, стандартные форматы, <lid>.status.json для ИИ-перевода)

Ещё открыто

• [ ] Документировать µLib (microLib), затем принять как слой утилит в µGulp (i18x сегодня — локальное webview-подмножество)
• [ ] Прямое подключение i18xe-server: живая синхронизация перевода вместо встроенных словарей
• [ ] Расширить GUI.mjs из µLib дополнительными специальными элементами для форм панели
• [ ] Визуальная доводка webview-панели
• [ ] Расширить скин µCSS: добавить шрифт символов и спрайты в манифест
• [ ] Речевой вывод через i18xe (сэмплы атласа уже заменяют WebAudio-пищи, когда есть)
• [x] Плагин JetBrains: Settings → Tools → µGulp (параметры движка)
• [ ] Распространение JetBrains Marketplace (отложено — пока только локальная ZIP-установка)
• [ ] Публикация расширения VS Code/Cursor в marketplace (отложено — поставка через GitHub Releases / packages/*_latest.* пока)

---

日本語

Rock your Gulp!

µGulp™ は、リッチなビジュアル、webview コントロール、音声フィードバックを備えた、ほぼゼロレイテンシの対話型タスクオーケストレータです。IDE 拡張として 3 つのエディション（VS Code / Cursor 登録版、VS Code / Cursor Free、JetBrains IDE）で提供され、Carbon/Neon の webview ダッシュボードを備えます。

ハイライト

µGulp™ は µGulp™（VS Code / Cursor）、µGulp™ Free（VS Code / Cursor）、JetBrains IDE 向け µGulp™（IntelliJ IDEA、PhpStorm、WebStorm、PyCharm、Rider、CLion、GoLand、RubyMine、DataGrip およびその他の IntelliJ 系 IDE）として提供されます。以下の区分は現行計画であり、公開マーケットプレイス開始前に まだ変わる可能性があります。登録済み VS Code 拡張と µGulp™ Free を並べてインストールしないでください。同じコマンド ID を共有します。登録済み VS Code エディションはタスク実行前に登録が必要です。またはアンインストールして µGulp™ Free を使ってください。

	µGulp™ VS Code / Cursor	µGulp™ Free VS Code / Cursor	µGulp™ JetBrains IDEs
価格（月 / 年）	0 € / $0	0 € / $0	0 € / $0
タスクダッシュボード、preload、i18x、パラメータ、µWatch、履歴	あり	あり	あり
ライセンス / 登録	必須	なし	なし
スキン（Neon Carbon、Ice Light、IDE Dark / Light、Automatic）	あり	IDE テーマに従う IDE Dark / Light（選択不可）	あり
カスタムテーマ ZIP パック	あり	—	あり
診断エンジン	あり	—	あり
Windows UAC 昇格	あり	—	あり
ホスト設定	microgulp.*	microgulp.*	Settings → Tools → µGulp
Marketplace（掲載は未公開）	VS Code · Open VSX	VS Code · Open VSX	JetBrains (de.amekudzi.microgulp)

全エディションは 現在無料 です（月額・年額とも 0 € / $0）。以下の箇条書きは フル 製品を説明します。Free は IDE Dark / IDE Light で IDE/OS テーマに従い（Appearance ピッカーなし）、テーマパック・診断・昇格はありません。

• プリロード済みワーカー — gulpfile をすでにインポートした温かい Node プロセス。クリックから実行までの遅延はほぼゼロ（AV ソフトのコールドスタートスキャンを回避）
• アイコンとローカライズ可能な文言を持つグループ化タスク一覧 — µGroup パス（Build/Production）で入れ子、折りたたみグループ、µIcon（グリフまたは画像）、.i18xRegister() で登録し i18x-catalog でライブ翻訳される µDisplayName / µDescription / µTooltip。µOrder がタスクとグループを並べ替え
• 並列タスクグリッド — 隔離された実行セクタを横並びにし、それぞれ独自のログストリーム
• Web ダッシュボード — ライブ ANSI 色付きログ、フィルタ出力、確定進捗バー、ユーザー入力用の豊富なフォーム（テキスト、色、フォント、select、multiselect、…）
• ライブ gulpfile 監視 — ワークスペースウォッチャーが保存時に再スキャンし、古いワーカーを自動入替
• ロックインなし — µ 接頭辞のメタデータはクラシック gulp CLI から見えず、各 API ヘルパーには CLI フォールバックがあるため、同じ gulpfile は µGulp™ あり・なし・削除後でもそのまま動きます（詳細）
• i18n 対応 gulp タスク — .i18xRegister() はメタデータフレーズ（表示名、説明、ツールチップ、グループに埋め込まれたコンテキストタグ）をプロジェクト辞書に登録し、米語ソースをそのまま返します。ダッシュボードは後で i18x-catalog 経由で翻訳し、プレースホルダ（version、project、…）は µI18xContext から埋めます。コンソール出力は .i18xTrans() / Log() で 即時 翻訳（プレースホルダ解決を含む）
• ダッシュボードのローカライズ — 同梱 GUI 辞書は en-US、de-DE、zh-CN、fr-FR、es-ES、ru-RU、ja-JP、ko-KR（設定：自動または固定ロケール）。追加言語は i18xe sync で予定。ユーザーハンドブックはダッシュボード言語の PDF
• gulpfile 用辞書同期 — Settings → Project i18x (gulp) が i18xe-sync パーサーでソースをスキャンし、選んだ言語の i18x/gulp/<lid>.json を書き、既存翻訳を保ち標準フォーマットをマージ。<lid>.status.json サイドカーがローカル AI がまだ訳すべき項目を列挙
• 宣言的タスクパラメータ — µParameters は実行前に一度尋ね、値を MICROGULP_PARAMS / GetParameters() で渡し、前回の回答を記憶し、パスワードをログから外し、visibleWhen でフィールドを隠せます
• ウォッチ / トリガータスク — µWatch グロブがファイル変更でタスクを実行。デバウンス、合体、暴走ブレーカー付き。ダッシュボードからタスクごとに武装
• タスクショートカット — プラットフォーム別バリアント付き µKeyBinding（ctrl+shift+F1、cmd+shift+Escape）、バッジと衝突警告。IDE グローバルには µGulp: Run Task
• 構造化ログ出力 — タスクが JSON ペイロードを出し、実行ログ内にインライン描画（表、木、画像ギャラリー、コールアウト、キー/値メトリクス、ステータスバッジ、コードブロック、インライン SVG 棒グラフ）。Content-Security-Policy 安全、プラグインや iframe 不要。チャート幅は上限あり、LogTable のヘッダ/行はスキン着色とホバー
• 永続タスク履歴とファイルログ — 各実行は .microgulp/logs に書き込み（生 .log + 構造化 .ndjson）。history.ndjson インデックスは再接続/IDE 再起動を生き残る。ダッシュボード履歴パネルが各トランスクリプトを開く（logToFile、logRetention）
• モーダルダイアログ — ダッシュボード内の AiDPix 風ガラスパネルとしての ShowModalMessage / ShowConfirmMessage（情報/警告/エラー、はい/いいえ、OK/キャンセル）。presentation または microgulp.modalPresentation による任意のネイティブ VS Code/Cursor モーダル（gulp-mu-gulp-api）。専用 README 節
• クリック可能なエラー位置 — 実行ログの file:line:column がホストエディタで開く（VS Code タブ、JetBrains IDE エディタ）
• 並行マトリクス — タスクごとの排他実行と allow/deny 規則（µExecutionConcurrency、µExecutionRestrictions）
• ダッシュボードスキン — Neon Carbon、Ice Light、加えて素の IDE Dark / IDE Light。Automatic（IDE/OS テーマ追従）付き Appearance ピッカー (Free: IDE テーマ由来の IDE Dark / IDE Light、選択不可)
• カスタムテーマ ZIP パック — グローバルインストール（~/.microgulp/themes）。パックには CSS、グラフィック、フォント、任意のサウンドアトラスを含められます。Settings → Appearance でインポート/削除 (Free にはなし)
• アイコンとログ用プロジェクトフォント — グリフ µIcon と実行ログ書体向けの RegisterDashboardFont / µDashboardFonts / dashboardFonts。タスクごとの任意 µIconFont（gulp-mu-gulp-api 0.3.12）
• 任意の音響制御 — 完了音、エラーアラーム、音声出力（ダッシュボード設定）
• 任意のフォームリマインダ — タスクがダッシュボード入力待ちのとき、設定可能な遅延後に音および/または音声で通知。フォームが回答されるまで繰り返し
• 完了実行の自動クローズ — セクタヘッダの任意カウントダウン（クリックで開いたまま）。タスクは µAutoClose で上書き（-1 は開いたまま、正の数は秒、省略時は Settings → Finished Runs、既定 30 秒）。Close の横に Restart
• Windows 管理者昇格 — タスクごとの任意 UAC プロンプト（µRequiresElevation、µElevationReason）。IDE は通常実行のまま、個別タスク（例: hosts 編集）だけ昇格 (登録済み VS Code / JetBrains。Free にはなし)
• 診断エンジン — インポートエラーとスタックトレースがダッシュボード上の実行可能な提案になる (登録済み VS Code / JetBrains。Free にはなし)
• gulpfile からの <version/> — タスクタイトルの優先ソースは µI18xContext.version。任意の versionSources は gulpfile が version を省略したときだけ埋める（消費者のリリース設定を上書きしない）
• 信頼できる LogError 対 Node 警告 — LogError / 本物の console.error は実行を失敗させる。Node の DeprecationWarning とその他のプロセス警告は失敗にしない（失敗バナーは最初の本物のエラーテキストを表示）
• レガシープロンプトブリッジ — gulpfile を編集せずに inquirer / gulp-prompt / prompts をダッシュボードフォームへリダイレクト
• gulp-mu-gulp-api — タスク内から進捗、音、音声、対話入力、モーダル、ダッシュボードフォントを使う npm モジュール

スナップショット

Hosts	VS Code、Cursor AI、JetBrains IDEs（Settings → Tools → µGulp）、microgulp-serve --http 経由の 127.0.0.1 上の任意ブラウザ
Runtime	Node.js 22+（ESM）
Gulpfiles	単一の gulpfile.mjs またはワークスペース全体の正規表現検出
Config	拡張設定（VS Code/Cursor）、Settings → Tools → µGulp（JetBrains）、任意の microgulp.config.json（チーム / CLI）
Engine	IDE 非依存 — どのホストでも同じ src/engine
言語	ダッシュボード GUI: en-US、de-DE、zh-CN、fr-FR、es-ES、ru-RU、ja-JP、ko-KR（同梱）。gulp 出力はプロジェクトの i18x/gulp/。ハンドブックはダッシュボード言語の PDF
タスク順	µOrder（昇順整数）。グループは部分木の最小順。未指定タスクは最後（アルファベット順）

タスクをクリック → 温かいワーカーがすぐ実行。gulpfile を編集 → タスク一覧は自動更新。複数タスクを並列実行でき、タスクが gulp-mu-gulp-api の ReportProgress を呼ぶと各セクタにネオン進捗バーが付きます。

ロックインなし: gulpfile は普通の gulpfile のまま

µGulp™ を導入しても、ビルドが µGulp™ に 依存することはありません。ダッシュボード向けに整えた gulpfile は、クラシックな gulp CLI、CI、µGulp™ を一度も入れていないマシンでも動き、µGulp™ をアンインストールしても動き続けます。

後方互換 — すべて素の gulp に劣化

追加するもの	素の gulp での扱い
µDisplayName、µIcon、µGroup、µOrder、µKeyBinding、µWatch、µAutoClose、µRequiresElevation、…	何もしない。エクスポート関数上の普通のプロパティ。gulp CLI はエクスポート名でタスクを指し、未知のプロパティを無視します。タスク名と CLI アドレスは無傷 — それが µ 接頭辞の理由です
µParameters	尋ねない。タスクは GetParameters() / GetParameter(id, fallback) を読み、宣言されたデフォルト、または CI ジョブで手でセットできる MICROGULP_PARAMS / MICROGULP_PARAM_<ID> 環境変数に落ちます
ReportProgress(...)	ネオンバーを駆動する代わりに、stdout にパーセント行を出します（TTY では単一 \r 行、CI では間引き行）
RequestForm、ShowModalMessage、PlaySignal、Speak、LogTable、LogChart、…	各ヘルパーに CLI フォールバックあり。プロンプトはデフォルトへ、モーダルは括弧付き行を出して ok を返し、音と音声は no-op、構造化ログはテキスト
.i18xRegister() / .i18xTrans()	i18xRegister() は米語ソース文字列をそのまま返す。辞書が無いとき i18xTrans() はソーステキストに落ちる。µGulp™ 無しでは英語コンソール出力になるだけ
.microgulp/（ログ、記憶したパラメータ）	µGulp™ がタスクを走らせたときだけ書かれる。捨ててよいキャッシュディレクトリ — .gitignore に入れていつでも削除

gulp-mu-gulp-api は 実行時依存なし の普通の npm パッケージで、IsMicroGulp() はタスクがオーケストレーションされているかを伝えます。µGulp™ の削除は拡張のアンインストールであり、gulpfile の編集は不要です。

前方互換 — 新しい µGulp™ は古い gulpfile を壊さない

メタデータは加算的で、未知キーは双方で無視されます。新しい µGulp™ 向けの gulpfile は古い版でも動き、新しい機能が無いだけです（ショートカットバッジなし、ウォッチトグルなし、パラメータフォームなし — タスクは起動します）。未知の構造化ログ形式は実行を壊さずスキップされ、ホストプロトコルはバージョン番号を持つので、古いホストは誤解釈ではなく不一致を検出できます。

実務上の帰結: 本番ビルドスクリプトで µGulp™ を試し、同じリポジトリをターミナルで npx gulp BUILD する同僚に渡しても、どちらも相手に気づきません。

インストール

Marketplace ページは予約済みですが まだ公開されていません（ソースリポジトリはまだ非公開）。掲載が生きるまでは、このリポジトリ / GitHub Release のパッケージからインストールしてください。

エディション	パッケージ	Marketplace（予定）
µGulp™（VS Code / Cursor）	packages/microgulp_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ Free（VS Code / Cursor）	packages/microgulp-free_latest.vsix	VS Code Marketplace · Open VSX
µGulp™（JetBrains IDEs）	下記 JetBrains IDE を参照	JetBrains Marketplace（plugin id de.amekudzi.microgulp）

ローカル VSIX インストール:

code --install-extension packages/microgulp_latest.vsix       # VS Code, registered
cursor --install-extension packages/microgulp_latest.vsix     # Cursor AI, registered
code --install-extension packages/microgulp-free_latest.vsix  # VS Code, Free

• ソースからビルド: npm install のあと npm run build — 登録版と Free の .vsix が packages/ に入ります。

その後、コマンドパレットから µGulp: Open Dashboard を実行（またはステータスバーの µGulp™ ロケットをクリック）。

JetBrains IDE

JetBrains プラグインはプラットフォームプラグイン（com.intellij.modules.platform）で、IntelliJ IDEA、PhpStorm、WebStorm、PyCharm、Rider、CLion、GoLand、RubyMine、DataGrip およびその他の IntelliJ 系 IDE に入ります。パッケージは 2 つ — IDE ビルドに合う方を選んでください（Help → About）:

IDE build	since-build	パッケージ
2024.2 – 2026.1（261.* まで）	242	packages/microgulp-jetbrains_latest.zip
2026.2 以降	262	packages/microgulp-jetbrains-2026.2_latest.zip

合う zip を選んでください。 IntelliJ IDEA、PhpStorm、WebStorm ほか IntelliJ 系 IDE は同じ 2 パッケージです — 製品名ではなくプラットフォームビルドで選んでください。各パッケージのディスクリプタに <idea-version since-build="…"/> があり、IDE はもう一方を読みません。microgulp-jetbrains は since-build="242" / until-build="261.*"（2024.2–2026.1）。microgulp-jetbrains-2026.2 は since-build="262" で上限なし（2026.2+）。プラットフォームビルドは Help → About にあります。

JetBrains Marketplace の掲載（プラグイン ID de.amekudzi.microgulp）はラテン表記 MicroGulp です — <name> に µ と ™ は使えません。ダッシュボード、ツールウィンドウ、サイト、この README は µGulp™ のままです。両方の zip がこの ID を共有します。plugin.xml のバージョンは RELEASES.json の単一製品バージョンから SemVer プレリリースとして導出します（<製品>-idea242、<製品>-idea262；Marketplace SemVer Only）。ただし製品 0.9.3 の 242–261.* チャネルは marketplace 版 0.9.3 のままです（提出済み）。0.9.3 の 262 パッケージは 0.9.3-idea262 です。VS Code / Free はサフィックスなしの製品バージョンです。zip 名は *_V<製品>.zip のままです。両 JetBrains パッケージは同じ製品チェンジログを載せます。ライセンス: https://microgulp.dev/en/license/。ソースリポジトリは非公開のままです — Marketplace 掲載にソースコード URL を出さないでください。

ビルド 262 は JCEF をコアプラットフォームから同梱の Web Browser (JCEF) プラグインへ移したため、ディスクリプタで明示宣言が必要です — そのため別パッケージです。Settings → Plugins → ⚙ → Install Plugin from Disk… でインストールし、µGulp ツールウィンドウを開きます。エンジンオプションは Settings → Tools → µGulp（Node パス、gulpfile 検出、preload/pool、watch、実行ログ）— VS Code の microgulp.* と同じ役割です。外観、音、言語はダッシュボードの ⚙ パネルに残ります。プラグインは薄い JCEF アダプタで、エンジン全体は同梱 Node.js サイドカーで動くため、Node.js 22+ が必要です（PATH、MICROGULP_NODE、または Node パス設定）。JCEF が使えない場合 — 削減 IDE ビルド、ブラウザプラグイン無効 — ツールウィンドウはそれでもエンジンを起動し、通常のブラウザでダッシュボードを開くボタンを出します。

パッケージのビルドと検査

npm run jetbrains（別名 npm run phpstorm）が両方の zip を作り、npm run jetbrains:verify が検査します。Gradle は使いません:

• 各パッケージは サポートする最古の IntelliJ プラットフォームに対してコンパイル されます — 242 パッケージは 2024.2 IDE、262 パッケージはインストール済み IDE。新しいビルドにしか無い API は javac が拒否し、出荷させません。アダプタはプラットフォーム API（ツールウィンドウ、設定、JCEF、エディタ）だけを使うので、同じ zip がすべての IntelliJ 系 IDE で動きます。
• npm run jetbrains:verify は JetBrains Plugin Verifier を両 zip に走らせ、宣言範囲の両端（レガシーは 2024.2 と 2026.1、もう一方は 262）で検査します。欠落クラス/メソッド、非推奨または内部 API、ディスクリプタ欠陥を報告します。
• Plugin Verifier の fat-jar は dev/tools/intellij-plugin-verifier/（verifier-cli-1.410-all.jar。無ければ Maven Central からそこに取得）。必要な IntelliJ プラットフォーム配布は一度 MICROGULP_IDE_CACHE（既定 %LOCALAPPDATA%\microgulp\ide-cache、他環境は ~/.cache/microgulp/ide-cache）へダウンロードして再利用。ローカル IDE のビルドが一致すればそれを直接使います。MICROGULP_SKIP_IDE_DOWNLOAD=1 はオフラインビルドを維持 — インストール済み IDE に対してコンパイルし、欠けた検証ターゲットはスキップします。
• verifier が見えない点: 全体 IDE に対して解決し、コンテンツモジュールの classloader 隔離を無視するため、欠けたモジュール依存でも互換と読まれます。そのためビルドは、JCEF に触れる 262+ 向けパッケージを com.intellij.modules.jcef とその 2 モジュール無しでは梱包しません。

既知の JetBrains / JCEF ログノイズ（無害）

µGulp ツールウィンドウが初めてダッシュボードを埋め込むとき、IDE ログに次のようなエラーが出ることがあります:

JBCefApp$Holder <clinit> requests ProxyMigrationService instance. Class initialization must not depend on services.

これは JetBrains 自身の JCEF スタック（JBCefApp → プロキシ設定 → HttpConfigurable）から来ており、µGulp プラグインではありません。プラットフォームは JCEF 起動を完了します。その後ダッシュボードが出れば、この項目は 無視して構いません。PhpStorm 2025 対 2026 とは無関係で、同じ JCEF ビルドを使う任意の JetBrains IDE が出し得ます。ツールウィンドウが空白のまま、または本物の µGulp 起動エラー（Node パス、サイドカー、gulpfile スキャン）が出たときだけ追加調査してください。

同じダッシュボードは任意の素のブラウザでも動きます: npm run serve -- --cwd <project> --http 9310 --preload のあと http://127.0.0.1:9310/ を開く。

設定ファイル microgulp.config.json（JetBrains と CLI）

VS Code / Cursor ではエンジンは拡張設定（microgulp.gulpfilePattern など）で構成します。JetBrains プラグインは同じエンジンオプションを Settings → Tools → µGulp に映し、次のツールウィンドウオープン時にサイドカー CLI フラグとして渡します。任意で、プロジェクトルートの microgulp.config.json がチーム共通デフォルトと、IDE ページに無いキー（dashboardFonts、metadataWatchFiles、versionSources）をまだ供給します。CLI フラグが無いときの microgulp-serve による素の CLI/ブラウザ利用はファイルを読みます:

{
	"gulpfilePattern": "gulpfile.*\\.mjs$",
	"poolSize": 2,
	"maxParallel": 6,
	"preload": true,
	"watchGulpfiles": true
}

Key	Type	Default	Meaning
gulpfile	string	"gulpfile.mjs"	Single gulpfile, relative to the project root
gulpfilePattern	string	—	Case-insensitive regex against workspace-relative POSIX paths; discovers all matching gulpfiles (wins over gulpfile)
poolSize	int ≥ 0	2	Warm workers per gulpfile
maxParallel	int ≥ 1	6	Maximum concurrent task runs
preload	bool	false	Warm up the worker pools right after startup (PhpStorm IDE setting defaults to on; CLI needs --preload)
watchGulpfiles	bool	true	Auto-rescan on gulpfile changes
metadataWatchFiles	string[]	["package.json", "RELEASES.json"]	Optional. Workspace-relative files whose changes trigger a metadata rescan (e.g. after a version bump). Prefer watching the file your gulpfile reads at init.
versionSources	string[] or objects	["package.json"]	Optional. Live JSON fallback for <version/> when the gulpfile does not set µI18xContext.version. Rarely needed for consumer projects — see below.
dashboardFonts	array	—	Optional. Project fonts for task icons / run log (see ダッシュボードフォント)
logToFile	bool	true	Persist run transcripts (.log + .ndjson) and the task history to disk
logDirectory	string	.microgulp/logs	Directory for transcripts and the history index, relative to the project root
logRetention	int ≥ 0	200	Max runs kept in the history (0 = unlimited); older runs and their log files are pruned

優先順位: コマンドライン / JetBrains IDE 設定 > microgulp.config.json > 組み込みデフォルト。 無効値と未知キーは stderr 警告付きで無視。ファイルはバージョン管理でき、チーム全体に適用されます。IDE 設定またはファイルを編集したら、µGulp ツールウィンドウを開き直す（サイドカー再生成）か microgulp-serve を再起動してください。

VS Code / Cursor では同じキーが microgulp.metadataWatchFiles と microgulp.versionSources として使えます（空でない拡張設定が microgulp.config.json に勝ちます）。空配列はメタデータ監視やファイルからのライブバージョン読み取りを無効化します。

タスクタイトルの <version/>（推奨 vs 任意）

推奨（ほとんどの消費者プロジェクト）: gulpfile から µI18xContext をエクスポートし、そこで version を設定（モジュール初期化時に単一のリリースソースを読む）。そのソースの変更で再スキャンし温かいワーカーを更新するよう metadataWatchFiles を使います:

export const µI18xContext = { project: 'MyApp', version: _ReadReleaseVersion() };
MAKE_BUILD.µDisplayName = 'Build V<version/><context="µDisplayName"/>'.i18xRegister();

{
	"metadataWatchFiles": ["configs/systemconfig.js"]
}

µI18xContext.version が設定されているとき、ライブ versionSources はそれを 上書きしません。

任意 — versionSources: µI18xContext.version を 設定せず、エンジンにディスク上の JSON から <version/> を解決させたい（かつ gulpfile を再インポートせず GetTasksPayload で更新したい）場合だけ有用。対応する形:

• "package.json" — npm の "version" フィールドを使用
• "RELEASES.json" — µGulp 形式。正確なスキーマは バージョン管理 (RELEASES.json)（releases[0].main / minor / revision）
• { "file": "config/version.json", "field": "version" } — 任意の JSON ファイル + ドット区切りフィールドパス

例（任意のライブ JSON のみ — gulpfile の version なし）:

{
	"metadataWatchFiles": ["package.json", "RELEASES.json"],
	"versionSources": ["RELEASES.json", "package.json"]
}

ロジック: src/engine/ProjectMetadata.mjs。プレースホルダは BuildSourceI18xContext で構築。

プロジェクト構成

gulpfile.mjs             Project build: tests, theme CSS (µCSS), package + deploy
RELEASES.json            Version source (main/minor/revision, i18xe-ready info texts)
gulp-mu-gulp-api/        Standalone npm module: public task API
  src/index.mjs          Progress, text/color/font/select inputs, forms
  tests/                 The module's own node:test suite
skins/                   One directory per skin (neon-carbon is the default)
  neon-carbon/
    neon-carbon.µcss.mjs µCSS skin manifest (Carbon/Neon variables)
    neon-carbon.µ.css    Skin source → compiled into src/webview/skins/neon-carbon/
  ice-light/             Light frosted-glass skin (cool blue outward glow)
    ice-light.µcss.mjs   µCSS skin manifest (ice palette)
    ice-light.µ.css      Skin source → compiled into src/webview/skins/ice-light/
  ide-dark/              Plain IDE-aligned dark (VS Code–like, no neon/carbon)
  ide-light/             Plain IDE-aligned light companion
src/
  engine/                IDE-independent core (no VS Code APIs!)
    TaskEngine.mjs       Orchestrator: scan, preload, queue, events
    TaskWorkerPool.mjs   Pool of prewarmed worker processes
    ConcurrencyGuard.mjs Evaluates executionConcurrency/-Restrictions
    Diagnostics.mjs      Diagnosis engine (stack traces → concrete suggestions)
    PluginHost.mjs       Lifecycle hooks for plugins
    GulpfileDiscovery.mjs  Regex-based gulpfile discovery in the workspace
    ReleaseInfo.mjs      Release management: RELEASES.json, version strings, history
  worker/
    TaskWorker.mjs       Child process: imports the gulpfile, runs tasks
  bridge/
    gulp-ugulp-bridge.mjs  Public bridge: npm packages ↔ webview forms
  host/
    HostProtocol.mjs     Event/command names (the single host boundary)
    Daemon.mjs           Engine owner for sidecar hosts
    microgulp-serve.mjs  stdio NDJSON CLI (PhpStorm preparation)
  extension/
    extension.cjs        Thin VS Code / Cursor adapter (the only CJS module)
  webview/
    dashboard.css        Fallback stylesheet for fresh checkouts
    dashboard.js         TaskGrid, log streaming, forms, audio engine
    skins/<name>/dashboard.css  µCSS-generated skins (webview default: neon-carbon)
tests/                   node:test suites (unit + engine integration)
demo/
  gulpfile.mjs           Example gulpfile with every µGulp™ metadata tag
  run-demo.mjs           Headless engine smoke test (no IDE)
dev/
  prompts/               AI migration prompts (existing gulpfile → µGulp + i18x)
    OptimizeGulpfileForMicroGulp.md
    OptimizeGulpfileForMicroGulp.params.example.json

アーキテクチャ原則

• エンジン層は IDE フリー。 src/engine と src/worker は VS Code API を知りません。通信はイベント（エンジン → ホスト）と素の JSON コマンド（ホスト → エンジン）です。PhpStorm への移植（フェーズ 2）は純粋なアダプタ入替です。最小サイドカー npm run serve（src/host/microgulp-serve.mjs、stdio 上の NDJSON）はすでにあります。
• タスクプリロード。 TaskWorkerPool は gulpfile をすでにインポートした予熱済み Node プロセスを保持します。タスク開始は温かいワーカーを渡し、プールをバックグラウンドで補充します。実行後プロセスは破棄されます（新しいモジュール状態）。
• 動的インポート。 重い npm パッケージ（mssql、docx-templates、makensis、…）はタスク本体の中でのみ await import() で読み込むこと。静的トップレベル import はオーケストレータ中核ロジック専用です。
• 言語。 GUI テキストは米語で String.i18xTrans() を通ります（i18xe 配線は後続）。コードコメントは英語。マニュアル/ドキュメントはドイツ語。

ダッシュボードのローカライズ

ダッシュボード GUI は en-US（ソース）、de-DE、zh-CN、fr-FR、es-ES、ru-RU、ja-JP、ko-KR の同梱 i18x 辞書を出荷します。言語はダッシュボード設定で選びます（automatic はホストまたはブラウザロケールに従う）。gulpfile コンソール出力はワーカーの MICROGULP_LANG とプロジェクトの i18x/gulp/<lid>.json で同じ言語を使います。ユーザーハンドブックはダッシュボード言語の PDF。

i18xe サーバ無しでこれらの gulp 辞書を種まきまたは更新: Settings → Project i18x (gulp) → Scan & update i18x/gulp…。µGulp™ は i18xe-sync スキャナ（加えて Log/Warn/LogError）でフレーズを解析し、既存翻訳を保ち、標準フォーマット定義をマージし、ローカル AI 翻訳用の <lid>.status.json サイドカー（missing / orphans）を書きます。

Layer	Who provides it	Today	Planned
Dashboard GUI	µGulp (extension)	en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR	More marketplace languages via the i18xe sync pipeline
Gulp tasks & logs	Your project	i18x/gulp/*.json next to the gulpfile	Same — consumer projects never ship i18x/prod
Hyphenation	µGulp webview assets	String.prototype.Hyphenation() with bundled <lid>.hyphen.json where present	Additional locales as hyphen data is synced from i18xe

コンテキストタグ、必須フォーマット、言語ロードマップ: dev/docs/MicroGulpI18xProfile.md。ダッシュボード GUI 辞書向けのライブ i18xe サーバ 接続は任意のまま（レーン 3）。消費者 gulp 辞書は上記のオフラインスキャンを使います。

Gulpfile の検出 (正規表現で設定可能)

µGulp™ はディスク上の gulpfile 変更を自分で気づきます。ワークスペースウォッチャー（microgulp.watchGulpfiles、既定オン）が変更後に自動再スキャンし、温かいワーカーを現行コードの新しいものに入れ替えます。スキャン中、タスク一覧はアニメーション進捗を示します。そのためダッシュボードに再スキャンボタンはもうありません。コマンド µGulp: Rescan Tasks（コマンドパレット）は手動強制更新として残ります。gulpfile の読み込み失敗（構文エラー、欠落モジュール）では、診断とスタックトレース付きの閉じられるエラーバナーがダッシュボードに出ます。

µGulp™ は 単一パス またはワークスペース全体を探す 正規表現パターン で gulpfile を見つけます:

• microgulp.gulpfilePattern — ワークスペース相対パス（/ の POSIX 記法）に対する JavaScript 正規表現（大文字小文字無視）。設定時は一致する すべての ファイルをスキャンし、タスクはダッシュボードでソース別にグループ化。例: (^|/)gulpfile\.(m|c)?js$ はルートと各サブフォルダの gulpfile.mjs/.js/.cjs を見つけます。
• microgulp.gulpfilePath — クラシックな単一パス（既定 gulpfile.mjs）。gulpfilePattern が空のときだけ使用。

node_modules、.git、隠しフォルダ（.*）には降りません。発見した各 gulpfile は、gulpfile のフォルダを作業ディレクトリとする 独自の温かいワーカープール を得るので、相対パスの入れ子サブプロジェクトも正しく動きます。検出ロジックは IDE 非依存で src/engine/GulpfileDiscovery.mjs にあり、CLI と JetBrains アダプタでも使えます。

複数 の gulpfile が一致すると、左のタスク列はスクリプトファイルごとに ソース見出し（ワークスペース相対パス、例: gulpfile.mjs、nested/gulpfile.mjs）を示し、異なるファイルのタスクはトップレベルで 混ぜません。各ソース内では引き続き µGroup パス（Build/Production、…）で入れ子になります。単一 gulpfile では見出しは省略され、µGroup 入れ子だけが適用されます。スキャンした gulpfile がタスクをエクスポートしても どれも gulp-mu-gulp-api を import しない場合、ダッシュボードは npm パッケージ と AI 移行プロンプト への閉じられるヒントを出します。

Gulp タスク上の µGulp™ メタデータ

推奨形は CamelCase の µ 接頭辞タグ（µDisplayName、µIcon、…）です。クラシック gulp CLI からは見えないため、µGulp™ の無いシステムでも gulpfile は完全互換です（gulp CLI は function.displayName でタスクを指す。空白付きの見栄えの良い名前はそこでタスク指定を壊します）:

export async function BUILD_STYLES() { /* ... */ }
BUILD_STYLES.µDisplayName = 'Build Styles';
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.';
BUILD_STYLES.µTooltip = 'Runs the µCSS pipeline (sprites, fonts, sounds included).';
BUILD_STYLES.µIcon = '\u25A3';   // font symbol — or an image data URI:
// BUILD_STYLES.µIcon = 'data:image/svg+xml,%3Csvg ...';  (png/webp too)
BUILD_STYLES.µIconFont = 'ProjectIcons'; // optional — see Dashboard fonts below
BUILD_STYLES.µGroup = 'Build/Assets';                 // nested group (path syntax)
BUILD_STYLES.µOrder = 10;                             // sort position in the dashboard (ascending)
BUILD_STYLES.µExecutionConcurrency = true;            // false = exclusive
BUILD_STYLES.µExecutionRestrictions = { deny: ['CLEAN'] }; // parallel matrix
BUILD_STYLES.µKeyBinding = { key: 'ctrl+shift+B', mac: 'cmd+shift+B' }; // dashboard shortcut
BUILD_STYLES.µWatch = { files: ['skins/**/*.µ.css'] }; // optional file trigger
BUILD_STYLES.µAutoClose = -1;                         // keep the finished sector
BUILD_STYLES.µParameters = [                          // asked before the run
  { id: 'target', type: 'select', options: ['debug', 'release'], default: 'debug' },
];
// Windows only — show the UAC prompt when the host is not already elevated:
BUILD_STYLES.µRequiresElevation = true;
BUILD_STYLES.µElevationReason =
  'Modifies the Windows hosts file.<context="µElevationReason"/>'.i18xRegister();

µGroup はタスク概要の 入れ子グループ に割り当てます。定義はディレクトリ風パス: µGroup = 'Build/Production' は Build グループと Production サブグループを作ります。グループはダッシュボードで折りたたみ可能。µGroup 無しのタスクはトップレベルに残ります。割り当ては任意で見た目のみ — 実行や並行性には影響しません。

µOrder は左列の 並べ替え位置（昇順整数）です。兄弟タスクとグループは µOrder で並び、値の無いタスクはすべての順序付きタスクの後（タイブレーク: 表示名）。グループは部分木の最小 µOrder で並びます。

グループヘッダの修飾キー:

Action	Effect
Click	toggle the group
Ctrl+Click (Cmd+Click)	toggle every group on the same level
Alt+Click	toggle all groups

µRequiresElevation は Windows で管理者権限 が必要なタスクを示します（例: C:\Windows\System32\drivers\etc\hosts の書き換え）。IDE が通常実行のとき、µGulp™ はワンショット昇格ワーカーを起動し、いつもの UAC ダイアログ を出します。Cursor や VS Code を管理者として起動する必要はありません。ホストプロセスがすでに昇格していれば、温かいワーカープールをいつもどおり使います。非 Windows ではフラグは無視されます。任意の µElevationReason はタスクツールチップに出ます（ダッシュボードの ⛿ バッジ）。

タスクショートカット (µKeyBinding)

タスクは独自のキーボードコードを持てます。コードは ダッシュボードにフォーカスがあるあいだ 有効です。VS Code と PhpStorm は実行時にキーバインドを登録できないため、µGulp™ は IDE グローバルキーを所有するふりをせず自分で処理します。

BUILD.µKeyBinding = 'ctrl+shift+B';                      // same chord everywhere
DEPLOY.µKeyBinding = { key: 'ctrl+alt+D', mac: 'cmd+alt+D' };
STOP.µKeyBinding = { key: 'ctrl+shift+Escape' };         // named keys: F1…F24, Escape, Tab, Space, arrows, …

Part	Accepted
Modifiers	ctrl, control, alt, option, shift, meta, cmd, command, super, win
Keys	single characters (b, 7, +), F1–F24, Escape/Esc, Enter, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up/Down/Left/Right
Platform keys	key (fallback), mac, win, linux — the matching platform wins, key fills the rest

cmd は macOS では Command キー、他では Ctrl なので、単一の key コードは全プラットフォームで使えます。コードはタスク名の横にバッジとして出ます。2 タスクが同じコードを主張すると両方のバッジが琥珀になり、ツールチップがそう言います（µGulp™ はどちらを意図したか推測しません）。

本当に IDE グローバル なショートカットには、コマンド µGulp: Run Task を自分でバインドしてください。タスクを引数に取ります:

// keybindings.json (VS Code / Cursor)
{ "key": "ctrl+shift+f9", "command": "microgulp.runTask", "args": { "task": "gulpfile.mjs::BUILD_STYLES" } }

args 無しでは、スキャン済みタスクのクイックピックを開きます。

宣言的タスクパラメータ (µParameters)

タスク本体内から入力を尋ねる代わりに、必要なものを 宣言 できます。µGulp™ は実行開始前に 1 つのフォームを出し、次回のために回答を覚え、環境経由で値をタスクに渡します:

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 = {
  submitLabel: 'Start Deploy<context="button text"/>'.i18xRegister(),
  fields: [
    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging',
      label: 'Target<context="task parameter"/>'.i18xRegister() },
    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
    { id: 'servers', type: 'checkbox', options: ['a', 'b'], required: true }, // submit stays disabled until ≥1
    { id: 'dryRun', type: 'boolean', default: true },
    { id: 'notify', type: 'boolean', default: false,
      visibleWhen: { dryRun: false } },   // only when not a dry run
    { id: 'token', type: 'password' },   // never stored, never logged
  ],
};

プレーンなフィールド配列もまだ動きます。ラッパーはフォームの外枠（title、submitLabel）を足します。タスク上の µParameterSubmitLabel はボタン文言の同等の代替です。

Field	Meaning
id	required; must be env-var safe ([A-Za-z_][A-Za-z0-9_]*)
type	text (default), textarea, password, number, range, boolean (slide switch), checkbox (multi-select), radio, select, font, color
label, description, placeholder	shown in the form (i18x via .i18xRegister())
default	pre-filled value; a remembered answer from the last run wins
options	['a','b'], [{ value, label, disabled }] or { a: 'Label A' }
required, pattern, minLength, minSelected	validated live in the dashboard — the submit button stays disabled until every visible rule passes (required on a checkbox means at least one option)
min, max, step, rows	numeric / textarea details
remember	false keeps the value out of the store (implicit for password)
visibleWhen	show the field only while other answers match — e.g. { dryRun: false } or { servers: 'prod' } (multi-select: contains). Hidden fields are not validated; missing answers fall back to default
submitLabel / title	form wrapper keys (or µParameterSubmitLabel / µParameterTitle on the task) — i18x via .i18xRegister()

値は MICROGULP_PARAMS（JSON）とパラメータごとの平坦な MICROGULP_PARAM_<ID> として届くので、タスク内のシェルステップも読めます。gulp-mu-gulp-api の GetParameters() / GetParameter('target', 'staging') が解析します。素の gulp CLI では同じ変数を手で渡せます:

MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY

回答はタスクごとに .microgulp/parameters.json に記憶され、次のフォームを埋めます。パスワードと remember: false の値はストアにもトランスクリプト・履歴・ダッシュボードにも書かれず、•••• と出ます。実行ログと履歴エントリは実行開始時の値を記録するので、後から何と答えたか分かります。昇格タスク（µRequiresElevation）は一方通行プロセスからフォームを出せないため、宣言デフォルトより記憶値で走ります。

ウォッチ / トリガータスク (µWatch)

関心のあるファイルが変わると、タスクは自分自身を実行できます:

BUILD_CSS.µWatch = 'src/**/*.µ.css';                  // shorthand
BUILD_CSS.µWatch = {
  files: ['src/**/*.µ.css', 'skins/*/manifest.json'], // globs, relative to the gulpfile
  ignore: ['**/*.tmp'],
  debounceMs: 300,                                    // quiet time after the last change
  autoStart: false,                                   // arm as soon as the gulpfile is scanned
  parameters: { target: 'debug' },                     // fixed µParameters for triggered runs
};

監視は タスクごとのオプトイン です。autoStart: true でない限り、タスク名の横に ◉ トグル（武装時はシアン）が出ます。グロブは **、*、?、{a,b}、文字クラスをサポート。node_modules、.git、.microgulp、.idea、.vscode は決して監視しません。

ガードレール。自分の監視集合へ書き込むビルドタスクは、さもなくば永遠に回ります:

• 変更イベントのバーストは 1 実行になる（デバウンス）
• タスク実行中は後続実行は最大 1 件キュー
• 1 分以内に 20 を超えるトリガー実行はウォッチャーを 停止（琥珀トグル、ツールチップが理由を説明）。オフにして再度オンで再武装

トリガー実行は発火したファイルをログに名付け（Triggered by src/a.css）、パラメータフォームは決して開きません。トリガーは固定または記憶値を使うので、見ていない人間を待ちません。

完了した実行を開いたままにする (µAutoClose)

完了したセクタは既定で 30 秒後 に閉じます（Settings → Finished Runs）。タスクで上書きできます:

SHOW_OUTPUT.µAutoClose = -1;   // セクタを残す（自動クローズなし）
QUICK.µAutoClose = 8;          // 8 秒後に閉じる

値	意味
省略 / true	ダッシュボード設定（既定 30 秒）
-1, false, 0	このタスクを自動クローズしない
正の整数	その秒数後に閉じる（ダッシュボード遅延を上書き）

黄色いカウントダウンチップでセクタを残せます。µAutoClose は数値または boolean で、.i18xRegister() は不要です。

クリック可能なエラー位置

実行ログ内のファイル参照はリンクになります: src/engine/TaskEngine.mjs:412:9、at Object.<anonymous> (gulpfile.mjs:88:15)、tsc/eslint 出力、MSBuild 風 file(12,7)。クリック（または Enter）でホストエディタのその行・列が開きます — VS Code/Cursor ではエディタタブ、PhpStorm では JCEF ブリッジ経由の IDE エディタ。

パスはホスト側でまず実行の gulpfile ディレクトリ、次にワークスペースルートに対して解決されるので、複数 gulpfile のワークスペースでも曖昧な名前の正しいコピーへ飛びます。ソース風拡張子の既存ファイルだけを開きます。URL、タイムスタンプ、バージョン番号はそのままです。

テーマパック (ZIP)

カスタムダッシュボードテーマは ZIP パック として配布し、グローバル にインストールできます（ユーザー全体で ~/.microgulp/themes/、上書きは MICROGULP_THEMES_DIR）。プロジェクトワークスペースから独立しています。

パックレイアウト（プリコンパイル — µCSS ソース不要）:

manifest.json     // { "id", "displayName", "version", "appearance": "dark"|"light" }
dashboard.css
imgs/…            // optional graphics / cursors
fonts/…           // optional
snds/…            // optional µAU atlas: microgulp.sounds.weba (or .wav/.mp3) + microgulp.sounds.json

ダッシュボード: Settings → Appearance → Import theme ZIP…。組み込みスキンはピッカーに残ります。Automatic は引き続き Neon Carbon / Ice Light にマップ。パック削除は Remove selected pack。

このリポジトリでは npm run theme のあとコンパイル済みスキンをパックできます:

node dev/tools/pack-theme.mjs ide-dark
# → packages/microgulp-theme-ide-dark.zip

サウンドアトラス (µAU)

ダッシュボード合図は dev/media/final/sounds/microgulp/ から組み立てます。default/ が全スキンの土台。任意の <skin-id>/ フォルダがファイル名ステムで上書き。アトラスは WebA（音声のみ WebM/Opus、microgulp.sounds.weba）として出荷。同一サンプルは重複排除。全カタログ: dev/docs/MicroGulpSoundSchema.md。

PlaySignal('success'|'error'|'attention') は taskSuccess / taskFailed / requestAlert にマップ。PlaySound はスキーマ名を直接使います。

ダッシュボードフォント (タスクアイコンと実行ログ)

プロジェクトフォントは組み込みスキンから独立しています。gulpfile（推奨）または microgulp.config.json / 設定 microgulp.dashboardFonts で登録:

import { RegisterDashboardFont } from 'gulp-mu-gulp-api';

RegisterDashboardFont({
  id: 'ProjectIcons',
  file: 'assets/task-icons.woff2',   // relative to the gulpfile directory
  usage: 'task-icons',               // or 'log' / 'all'
});

// Or declarative:
export const µDashboardFonts = [
  { id: 'ProjectLog', file: 'assets/log.woff2', usage: 'log' },
];

BUILD.µIcon = '\uE101';
BUILD.µIconFont = 'ProjectIcons';     // optional when a single task-icons font is registered

usage: 'task-icons' はグリフ µIcon エントリを飾ります（最初に登録したフォントが既定。µIconFont がタスクごとに上書き）。usage: 'log' は実行セクタのログ書体を設定。ファイルはワークスペース下に置くこと（woff2 / woff / ttf / otf）。

プロパティごとのフォールバック連鎖: µDisplayName → ugulp.displayName（名前空間オブジェクト）→ displayName（Gulp 自身のフィールド）→ エクスポート名。executionRestrictions は deny（常に勝つ）と allow（ホワイトリスト: 未掲載は禁止）をサポート。

タスクメタデータ文字列はフレーズ 内部 のコンテキストタグ付き i18x を使います。.i18xRegister() はフレーズを i18xe-sync とプロジェクト辞書に登録するだけ — ソーステキストをそのまま返します。翻訳はダッシュボードがメタデータを描画するとき（i18x-catalog 経由の TransProperty()）、<version/> などのプレースホルダは µI18xContext から埋まります。コンソール出力 には .i18xTrans() または Log()/Warn()/LogError() を使い、実行時に即時翻訳（プレースホルダ含む）します:

BUILD_STYLES.µDisplayName = 'Build Styles<context="µDisplayName"/>'.i18xRegister();
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();

コンテキストタグ、必須フォーマット、マーケットプレイス言語計画: dev/docs/MicroGulpI18xProfile.md。

AI による gulpfile 移行

既存 の大きな gulpfile（コンソール出力、タスクメタデータ、i18x/gulp 辞書、任意の µKeyBinding / µParameters / µWatch / µAutoClose）を移行するには、リポジトリ内の保守プロンプトを使います:

File	Purpose
dev/prompts/OptimizeGulpfileForMicroGulp.md	Copy-paste prompt for Cursor, Claude, ChatGPT, …
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json	Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version)

Workflow

1. params 例をプロジェクトルートに microgulp-optimize.params.json としてコピーし、projectRoot、gulpfilePath、supportedLanguages（例: en-US、de-DE、zh-CN）、gulpMuGulpApiVersion（^0.4.0 以降）、microGulpMinVersion（0.7.0）、githubRepoUrl / githubRef（既定: https://github.com/mamekudz/microGulp、V0.7.0 または main）を記入。
2. プロンプト markdown を開き、{{PLACEHOLDER}} 表を値で置換（または Cursor で params ファイルと gulpfile を添付）。
3. AI に移行を実行させる。プロンプトのステップ 0 は必須: 編集前のタイムスタンプ付き gulpfile バックアップ（例: gulpfile.mjs.20260703-142559.bak）。
4. node --check gulpfile.mjs で確認し、µGulp ダッシュボードでタスクをテスト（ダッシュボードフォーカス中の新しいショートカットを含む）。その後 gulpfile.mjs、i18x/gulp/*.json、package.json をコミット。

消費者プロジェクトが必要なのは i18x/gulp/<lid>.json だけ — i18x/prod は不要。プロンプトは µGulp リリースで更新されます。移行前にこのリポジトリの最新版を確認してください。i18x 規則（register 対 translate、µMeta なし）と 宣言的 UX をカバー: ダッシュボード µKeyBinding（ユーザーが microgulp.runTask をバインドしない限り IDE グローバルではない）、µParameters / GetParameters()、µWatch、µAutoClose。

公開タスク API (gulp-mu-gulp-api)

ストリーム内の第三者 gulpfile と npm パッケージは、スタンドアロン npm モジュール **gulp-mu-gulp-api**（gulp-mu-gulp-api/ 下の独自プロジェクト、npm に別公開）経由で拡張ダッシュボード機能を使います:

import { ReportProgress, RequestTextInput, RequestColorInput, RequestForm, ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

export async function BUILD_THEME() {
    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
    let title = await RequestTextInput({ label: 'Product title', validate: { required: true, minLength: 3 } });
    let ok = await ShowConfirmMessage({
        title: 'Overwrite theme?',
        message: 'Existing skin files will be replaced.',
        presentation: 'webview',
    });
    if (ok.button !== 'yes') return;
    for (let step = 1; step <= 10; step++) {
        // ... work ...
        ReportProgress(step / 10, 'compiling theme');   // determinate neon progress bar in the sector
    }
    await ShowModalMessage({
        variant: 'info',
        title: 'Theme ready',
        message: 'Skin files written.',
    });
}

モジュールは依存無しで、µGulp™ ワーカーの IPC チャネル経由でエンジンと直接話します（検出は IsMicroGulp() / IsµGulp()）。µGulp™ 無しではきれいに劣化: 進捗は端末へ、入力は readline（TTY）またはデフォルト値（CI）。詳細は gulp-mu-gulp-api/README.md。内部モジュール src/bridge/gulp-ugulp-bridge.mjs は低レベル輸送として残ります。新規消費者は gulp-mu-gulp-api を使うべきです。

モーダルダイアログ (ShowModalMessage)

V0.5.29 以降（API: gulp-mu-gulp-api 0.3.11+）、タスクは ブロックするモーダルダイアログ を出せます — 確認、続行前の警告、はい/いいえと OK/キャンセル。日常のログ行には使わず控えめに。通常出力は Log() / 構造化ログヘルパーを優先。

Webview ガラスパネル（既定）

presentation が webview（既定）のとき、モーダルは µGulp ダッシュボード内 に AiDPix/Oxyd 風 ガラスパネル として描画されます:

Feature	Detail
Frame	9-slice glasspanel.png (glasspanel-ice.png in the ice-light skin)
Variants	info (turquoise header), warning, error — colored header bar per variant
Buttons	Carbon-styled actions; primary button highlighted
Overlay	Scroll the mouse wheel over the dimmed backdrop to adjust overlay brightness (8–88 %); long message bodies scroll inside the panel
Keyboard	Escape → cancel/no (or first button); Enter → primary button

実装: src/webview/WebviewModal.js、src/webview/webview-modal.css（VS Code webview と HTTP ダッシュボードが読み込み）。

API

import { ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

// Single acknowledgment (default button: OK)
await ShowModalMessage({
    variant: 'warning',          // 'info' | 'warning' | 'error'
    title: 'Disk almost full',
    message: 'Less than 1 GB free on the build drive.',
    presentation: 'webview',     // optional — see below
});

// Yes/No confirmation (default style)
let answer = await ShowConfirmMessage({
    title: 'Overwrite output?',
    message: 'Existing files in dist/ will be replaced.',
});
if (answer.button !== 'yes') return;

// OK/Cancel preset
let discard = await ShowConfirmMessage({
    title: 'Discard changes?',
    message: 'Unsaved theme tweaks will be lost.',
    style: 'ok-cancel',          // default: 'yes-no'
});

両ヘルパーは Promise<{ button: string }> を返します — 例: 'ok'、'yes'、'no'、'cancel'、または ShowModalMessage({ buttons: [{ id: 'retry', label: 'Retry', primary: true }] }) のカスタムボタン id。

CLI フォールバック（素の gulp、CI、TTY なし）: 括弧付きコンソール出力とプライマリ/デフォルトボタン — ブロックするプロンプトなし。

モーダルの表示場所 (presentation)

Value	Behavior
webview	In-dashboard glass panel (default)
ide	Native VS Code / Cursor modal (showInformationMessage / showWarningMessage / showErrorMessage with { modal: true })
auto	Native IDE dialog when the Extension Host is available; otherwise the webview glass panel

呼び出しごとの presentation はホスト既定を 上書き します。

ホスト既定

Host	Setting
VS Code / Cursor	Extension setting microgulp.modalPresentation (webview | ide | auto, default webview)
Browser demo / PhpStorm JCEF	Dashboard Settings → Modal presentation (same three values)

フォールバック: PhpStorm とブラウザダッシュボードは常に webview ガラスパネルを使います — そこでは presentation: 'ide' は webview にマップ。ネイティブ IDE モーダルを出せるのは VS Code/Cursor Extension Host だけです。

デモを試す

µGulp: Open Sample Project のあと、ダッシュボードは Demo グループを一覧します:

Task	Effect
DEMO_MODAL_DIALOGS	All variants + Yes/No + OK/Cancel with presentation: 'webview'
DEMO_IDE_MODAL_DIALOGS	Same flow with presentation: 'ide' (native modals in Cursor/VS Code; webview fallback in PhpStorm / the browser)

追加の API 詳細: gulp-mu-gulp-api/README.md。

µGulp ready 認定

ルート gulpfile が µGulp ダッシュボードに完全統合された npm モジュールは、npm README とプロジェクトページに µGulp ready バッジを表示できます。

Requirement	Detail
Gulpfile	Exported tasks carry µGulp metadata (µDisplayName, µDescription, µGroup, …)
API	Uses gulp-mu-gulp-api for logging, progress and optional dashboard features
CLI fallback	Tasks remain runnable with plain gulp / npx gulp when µGulp is not installed
Badge asset	Canonical PNG: media/microgulp-ready.png in the µGulp repo. npm README: absolute raw URL (npm rewrites relative paths to microCSS/HEAD/... even inside HTML). Example: <a href="https://microgulp.dev"><img src="https://microgulp.dev/assets/media/microgulp-ready.png" alt="µGulp ready" width="150"></a>
package.json	Optional "microgulp": { "ready": true, "certifiedSince": "<semver>" } for machine-readable discovery

認定モジュール

npm package	Since	Notes
gulp-mu-gulp-api	0.3.11	Official task API — Log, ReportProgress, i18x console layer, dashboard forms, ShowModalMessage / ShowConfirmMessage; npm README badge since 0.3.3
gulp-mu-css (µCSS™)	2.5.15	Monorepo root gulpfile.mjs with full task metadata, i18x/gulp/ (en-US, de-DE) and LogBuildDebugReport on demo builds; npm README badge via absolute raw URL since 2.5.14
gulp-mu-ps (µPS)	1.3.5	Test/render tasks in the shared root gulpfile (TEST_MICROPS, RENDER_EXAMPLES, …)
gulp-mu-ft (µFT)	0.1.5	Test task TEST_MICROFT in the shared root gulpfile
gulp-mu-au (µAU)	0.1.6	Test task TEST_MICROAU in the shared root gulpfile

認定を申請するには、dev/prompts/OptimizeGulpfileForMicroGulp.md で gulpfile を移行し、µGulp またはモジュールリポジトリで issue または PR を開いてください。

バージョン管理 (RELEASES.json)

このファイルは µGulp 自身のリリース形式 — この リポジトリの唯一の真実源です。消費者プロジェクトに RELEASES.json は 不要 です。製品バージョンは通常自前の設定に置き、µI18xContext.version で公開します。任意の versionSources: ["RELEASES.json"] は、同じ JSON 配置を採用する場合だけ役立ちます。

各リリースエントリは main/minor/revision、タイムスタンプ、beta フラグ、情報テキスト一覧を持ちます。情報テキストは i18x コンテキストタグ <context="release info"/> を持ち、String.i18xRegister() で登録されるため、i18xe エンジンが自動翻訳できます。

スキーマ（最新リリースが先頭 — releases[0] が現行）:

{
    "releases": [
        {
            "main": 0, "minor": 2, "revision": 0, "date": "2026-07-02 15:30", "beta": false,
            "info": [ "Release management added<context=\"release info\"/>" ]
        }
    ]
}

versionSources に "RELEASES.json" が含まれると、エンジンは releases[0] から <version/> を "main.minor.revision" に解決します（例: "0.2.0"）。

モジュール src/engine/ReleaseInfo.mjs が提供:

• GetVersionString() / GetFullVersionString() — "0.2.0" または "0.1.4ß"（ベータビルドの ß 接尾辞）。
• GetVersionHistoryText({ maxReleases, includeBeta }) — コンソール向け整形履歴文字列（タスク SHOW_VERSION_HISTORY または npm run history）。
• BUILD_PACKAGE は package.json バージョンとこの README 先頭のバージョン行を RELEASES.json から自動同期し、成果物名に刻印します（microgulp_V0.2.0.vsix、ベータは _beta 接尾辞）。新しいリリースは RELEASES.json 先頭の新エントリだけが必要です。

プロジェクトビルド (gulpfile.mjs)

プロジェクトは自前の gulpfile で自分をビルドします（ドッグフーディング: µGulp™ ダッシュボード、gulp CLI、クラシック Gulp IDE 拡張、ヘッドレスで動作）:

Invocation	Task	Purpose
npm test	RUN_TESTS	node:test suites in tests/ (unit + engine integration with real worker processes)
npm run theme	CREATE_THEME_DATA	Compiles every skins/<name>/<name>.µ.css via µCSS (gulp-mu-css BuildSkin) into src/webview/skins/<name>/dashboard.css (default: neon-carbon)
npm run package	BUILD_PACKAGE	Stages the extension into tmp/package/ and creates the .vsix in packages/ (also refreshed as microgulp_latest.vsix)
npm run deploy	DEPLOY_EXTENSION	Automated update cycle: build the .vsix and install it via cursor --install-extension (reload the window afterwards)
npm run build	BUILD_ALL	Full pipeline: clean → tests → theme → package
npm run history	SHOW_VERSION_HISTORY	Prints the formatted version history from RELEASES.json to the console
npm run accounts	ACCOUNTS	Read-only listing of production LICENSE_KV registrations (--status, --edition; token from CLOUDFLARE_API_TOKEN or website/.env)
npm run website	BUILD_WEBSITE	Turns README language sections into website/ (all languages selectable; / follows the browser language)
npm run website:deploy	DEPLOY_WEBSITE	Builds, tests and publishes website/ to Cloudflare Worker microgulp-web (microgulp.dev; local Wrangler login)
npm run backup	BACKUP_TO_NAS	Incremental robocopy mirror to Z:\\Projects\\microGulp (override with MICROGULP_NAS_BACKUP)
—	PUBLISH_API	Publishes gulp-mu-gulp-api to npm (runs its tests first; npm login required)
—	CLEAN	Removes tmp/ and packages/ (exclusive, write lock)

注記:

• gulp-mu-css は C:\Projects\microCSS\gulp-mu-css へのローカル file: 依存として配線され — 重いパッケージと同様 — タスク本体内でのみ await import() で読み込まれます。
• BUILD_PACKAGE は @vscode/vsce が入ると本物の .vsix を作ります（npm i -D @vscode/vsce）。vsce 無しではステージングフォルダの zip に落ちます。
• スキンは自己完結: skins/ 下にスキンごと 1 ディレクトリ（例: skins/neon-carbon/、skins/ice-light/、skins/ide-dark/）。それぞれ <name>.µcss.mjs マニフェストと同名の <name>.µ.css ソース。CREATE_THEME_DATA は全スキンを発見してビルド。neon-carbon（ダーク）が既定、ice-light は明るいフロストガラスの相棒。ide-dark / ide-light はカーボン織りやネオン脈動の無い素の VS Code 風面。追加/ユーザースキンは兄弟ディレクトリとして置けます。ダッシュボードスキンピッカー（Settings → Appearance）は IDE/OS の明暗テーマに従う Automatic モードを提供（ice-light / neon-carbon にマップ）。
• webview は生成済み既定スキン（src/webview/skins/neon-carbon/dashboard.css）を自動優先。手書き dashboard.css は新規チェックアウト用フォールバックとして残ります。
• ダッシュボードヘッダはネオン µGulp™ タイトルの横に黄色顕微鏡マーク（baselogo.svg）を µCSS data-URI インラインで出します（background-image: µ(DataUri("imgs/baselogo.svg"))）。完成アートアセットの唯一の真実源は dev/media/final/。ビルドはそこから media/logo.png（拡張アイコン）、media/logo_readme.png（README）、src/webview/skins/<name>/imgs/baselogo.svg（ダッシュボード）、jetbrains/resources/icons/baseoutlinelogo.svg（JetBrains ツールウィンドウ + プラグイン一覧）を同期します。

このリポジトリはローカル開発用に demo/gulpfile.mjs も出荷します:

npm run demo          # headless engine smoke test
npm run demo:web      # browser dashboard (microgulp-serve --http)
npm run demo:ide      # Extension Development Host with demo/ as the workspace

VS Code/Cursor の F5（起動構成 "Run µGulp Extension"）は同じデモワークスペースを開きます。

試す

インストール済み拡張: コマンドパレット → µGulp: Open Sample Project（JetBrains: Tools → µGulp: Open Sample Project）。Demo と Build タスク（進捗、フォーム、構造化ログ、音、モーダル）付きのサンプル gulpfile を ~/.microgulp/sample にコピーして開きます。その後 µGulp: Open Dashboard。ユーザーハンドブックは Settings → Handbook（または µGulp: Open Handbook）。ダッシュボードの全言語がそこに並びます。

ハンドブック PDF: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어

ライセンス

µGulp™（拡張、エンジン、ダッシュボード、JetBrains アダプタ）は プロプライエタリソフトウェア です — LICENSE を参照。配布バイナリは無償で使えます。ソースコードの複製、改変、再配布は許可されません。

付属 npm パッケージ gulp-mu-gulp-api は MIT ライセンス のままなので、Gulp タスクは制限なく採用できます。

ロードマップ / 本草案の未解決点

V0.5.0 で出荷済み

• [x] webview の i18x 層: 言語設定（automatic/en-US/de-DE/zh-CN/fr-FR/es-ES/ru-RU/ja-JP/ko-KR）、コンテキストタグ付き GUI 文字列、i18xe サーバから引き継いだフォーマット定義 — 直接 i18xe サーバ接続は後続
• [x] µ タスクメタデータ: .i18xRegister() が i18xe/ダッシュボード用フレーズを登録。翻訳とプレースホルダはダッシュボード描画時に i18x-catalog + µI18xContext。コンソールは .i18xTrans() / Log()
• [x] npm 上の公開タスク API **gulp-mu-gulp-api**（進捗、音/音声、CLI フォールバック付き対話フォーム。IsMicroGulp、InstallStringExtensions）
• [x] レガシープロンプトライブラリ（inquirer、gulp-prompt、prompts）を gulpfile 編集なしでダッシュボードフォームへリダイレクト
• [x] 拡張ダッシュボードフォーム制御（radio、range、textarea、password、number、date/time、file、複数選択 checkbox）
• [x] ダッシュボード設定（音響制御、音声出力、フォームリマインダ、エラー処理、言語）
• [x] タスクセクタのコンソール描画（ANSI 色、\r 進捗行上書き、タイムスタンプ）
• [x] 永続タスク履歴とファイルへのログ転送（生 .log + 構造化 .ndjson、history.ndjson インデックス、保持、ダッシュボード履歴パネル）
• [x] チーム/CLI デフォルト用 microgulp.config.json（設定時は PhpStorm IDE 設定 + VS Code 拡張設定が優先）
• [x] µOrder によるダッシュボードタスク並べ替え（昇順。グループは部分木最小）
• [x] フェーズ 2: JetBrains アダプタ — JCEF ツールウィンドウ + Node サイドカー + HTTP/SSE ダッシュボード + Settings → Tools → µGulp（すべての IntelliJ 系 IDE）
• [x] タスクごとの任意 Windows UAC 昇格（µRequiresElevation、µElevationReason）— IDE は非管理者のまま
• [x] ダッシュボードローカライズを文書化: 同梱 en-US / de-DE / zh-CN / fr-FR / es-ES / ru-RU / ja-JP / ko-KR。消費者プロジェクトは i18x/gulp のみ供給
• [x] マルチスキンダッシュボード（Neon Carbon、Ice Light、IDE Dark/Light）+ グローバルテーマ ZIP パック（Appearance インポート。任意の音/グラフィック）
• [x] テーマごとの µAU サウンドアトラス（default/ + スキン上書き、PCM 重複排除）。カタログは dev/docs/MicroGulpSoundSchema.md
• [x] タスクアイコン / 実行ログ用プロジェクトフォント（RegisterDashboardFont、µIconFont、dashboardFonts。gulp-mu-gulp-api 0.3.12）
• [x] タスクショートカット（µKeyBinding、プラットフォーム別コード、衝突バッジ）+ IDE グローバル用 µGulp: Run Task
• [x] 宣言的タスクパラメータ（µParameters、GetParameters()、記憶した回答、伏せた秘密）
• [x] ウォッチ / トリガータスク（µWatch グロブ、デバウンス、暴走ブレーカー、ダッシュボードトグル）
• [x] タスクごとの自動クローズ上書き（µAutoClose：-1 は開いたまま、正の秒、省略時は設定）
• [x] 実行ログ内のクリック可能なエラー位置（VS Code エディタタブ、PhpStorm JCEF ブリッジ）
• [x] Windows / Linux / macOS × Node 22 と 24 の CI マトリクス
• [x] ダッシュボード内のオフライン i18x/gulp 辞書同期（i18xe-sync パーサー、対象言語ダイアログ、標準フォーマット、AI 翻訳用 <lid>.status.json）

まだ未解決

• [ ] µLib（microLib）を文書化し、µGulp のユーティリティ層として採用（今日の i18x はローカル webview サブセット）
• [ ] 直接 i18xe-server 接続: 同梱辞書の代わりにライブ翻訳同期
• [ ] µLib の GUI.mjs にダッシュボードフォーム用の追加特殊コントロール
• [ ] webview ダッシュボードの見た目磨き
• [ ] µCSS スキン拡張: シンボルフォントとスプライトをマニフェストへ
• [ ] i18xe 経由の音声出力（アトラスサンプルがあるときはすでに WebAudio ビープを置換）
• [x] JetBrains プラグイン: Settings → Tools → µGulp（エンジンオプション）
• [ ] JetBrains Marketplace 配布（延期 — 当面はローカル ZIP インストールのみ）
• [ ] VS Code/Cursor 拡張のマーケットプレイス公開（延期 — 当面は GitHub Releases / packages/*_latest.* で出荷）

---

한국어

Rock your Gulp!

µGulp™는 풍부한 시각, webview 컨트롤, 오디오 피드백을 갖춘 거의 제로 지연의 대화형 태스크 오케스트레이터입니다. IDE 확장으로 세 가지 에디션(VS Code / Cursor 등록판, VS Code / Cursor Free, JetBrains IDE)과 Carbon/Neon webview 대시보드로 제공됩니다.

하이라이트

µGulp™는 µGulp™(VS Code / Cursor), µGulp™ Free(VS Code / Cursor), JetBrains IDE용 µGulp™(IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip 및 기타 IntelliJ 계열 IDE)로 제공됩니다. 아래 구분은 현재 계획이며 공개 마켓플레이스 출시 전에 아직 바뀔 수 있습니다. 등록된 VS Code 확장과 µGulp™ Free를 나란히 설치하지 마십시오. 같은 명령 ID를 공유합니다. 등록된 VS Code 에디션은 태스크를 실행하기 전에 등록해야 합니다. 아니면 제거하고 µGulp™ Free를 사용하십시오.

	µGulp™ VS Code / Cursor	µGulp™ Free VS Code / Cursor	µGulp™ JetBrains IDEs
가격(월 / 년)	0 € / $0	0 € / $0	0 € / $0
태스크 대시보드, preload, i18x, 매개변수, µWatch, 기록	예	예	예
라이선스 / 등록	필수	없음	없음
스킨(Neon Carbon, Ice Light, IDE Dark / Light, Automatic)	예	IDE 테마의 IDE Dark / Light(선택 불가)	예
사용자 테마 ZIP 팩	예	—	예
진단 엔진	예	—	예
Windows UAC 승격	예	—	예
호스트 설정	microgulp.*	microgulp.*	Settings → Tools → µGulp
Marketplace(목록 아직 비공개)	VS Code · Open VSX	VS Code · Open VSX	JetBrains (de.amekudzi.microgulp)

모든 에디션은 현재 무료입니다(월·년 모두 0 € / $0). 아래 항목은 전체 제품을 설명합니다. Free는 IDE Dark / IDE Light로 IDE/OS 테마를 따르며(Appearance 선택기 없음) 테마 팩, 진단, 승격은 없습니다.

• 미리 로드된 워커 — gulpfile을 이미 가져온 따뜻한 Node 프로세스. 클릭에서 실행까지 지연이 거의 없음(AV 소프트웨어의 콜드 스타트 스캔 회피)
• 아이콘과 지역화 가능한 문구가 있는 그룹 태스크 목록 — µGroup 경로(Build/Production)로 중첩, 접을 수 있는 그룹, µIcon(글리프 또는 이미지), .i18xRegister()로 등록하고 i18x-catalog로 실시간 번역되는 µDisplayName / µDescription / µTooltip. µOrder가 태스크와 그룹을 정렬
• 병렬 태스크 그리드 — 격리된 실행 섹터를 나란히, 각각 자체 로그 스트림
• 웹 대시보드 — 실시간 ANSI 색 로그, 필터 출력, 확정 진행 막대, 사용자 입력용 풍부한 폼(텍스트, 색, 글꼴, select, multiselect, …)
• 라이브 gulpfile 감시 — 워크스페이스 워처가 저장 시 재스캔하고 오래된 워커를 자동 교체
• 종속 없음 — µ 접두 메타데이터는 클래식 gulp CLI에 보이지 않고 모든 API 헬퍼에 CLI 폴백이 있어, 같은 gulpfile이 µGulp™ 있든 없든 제거 후에도 그대로 실행됩니다(자세히)
• i18n 준비 gulp 태스크 — .i18xRegister()는 메타데이터 구절(표시 이름, 설명, 툴팁, 그룹의 내장 컨텍스트 태그)을 프로젝트 사전에 등록하고 미국 영어 소스를 그대로 반환합니다. 대시보드는 나중에 i18x-catalog로 번역하고 자리 표시자(version, project, …)는 µI18xContext에서 채웁니다. 콘솔 출력은 .i18xTrans() / Log()로 즉시 번역(자리 표시자 해석 포함)
• 대시보드 로컬라이제이션 — 번들 GUI 사전 en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR(설정: 자동 또는 고정 로케일). 추가 언어는 i18xe sync로 예정. 사용자 핸드북은 대시보드 언어의 PDF
• gulpfile용 사전 동기화 — Settings → Project i18x (gulp)가 i18xe-sync 파서로 소스를 스캔하고 고른 언어의 i18x/gulp/<lid>.json을 쓰며, 기존 번역을 유지하고 표준 형식을 병합. <lid>.status.json 사이드카가 로컬 AI가 아직 번역할 항목을 나열
• 선언적 태스크 매개변수 — µParameters는 실행 전에 한 번 묻고, 값을 MICROGULP_PARAMS / GetParameters()로 넘기며, 마지막 답을 기억하고, 비밀번호를 로그에서 빼며, visibleWhen으로 필드를 숨길 수 있습니다
• 워치 / 트리거 태스크 — µWatch 글롭이 파일 변경 시 태스크를 실행. 디바운스, 합치기, 폭주 차단기. 대시보드에서 태스크별로 무장
• 태스크 단축키 — 플랫폼별 변형이 있는 µKeyBinding(ctrl+shift+F1, cmd+shift+Escape), 배지와 충돌 경고. IDE 전역에는 µGulp: Run Task
• 구조화 로그 출력 — 태스크가 JSON 페이로드를 내보내고 실행 로그에 인라인 렌더(표, 트리, 이미지 갤러리, 콜아웃, 키/값 메트릭, 상태 배지, 코드 블록, 인라인 SVG 막대 차트). Content-Security-Policy 안전, 플러그인/iframe 불필요. 차트 너비 상한, LogTable 헤더/행은 스킨 색과 호버
• 영구 태스크 기록과 파일 로깅 — 각 실행은 .microgulp/logs에 기록(원시 .log + 구조화 .ndjson). history.ndjson 인덱스는 재연결/IDE 재시작을 견딥니다. 대시보드 기록 패널이 각 전사본을 엽니다(logToFile, logRetention)
• 모달 대화상자 — 대시보드의 AiDPix 스타일 유리 패널인 ShowModalMessage / ShowConfirmMessage(정보/경고/오류, 예/아니요, OK/취소). presentation 또는 microgulp.modalPresentation로 선택적 네이티브 VS Code/Cursor 모달(gulp-mu-gulp-api). 전용 README 절
• 클릭 가능한 오류 위치 — 실행 로그의 file:line:column이 호스트 편집기에서 열림(VS Code 탭, JetBrains IDE 편집기)
• 동시성 행렬 — 태스크별 배타 실행과 allow/deny 규칙(µExecutionConcurrency, µExecutionRestrictions)
• 대시보드 스킨 — Neon Carbon, Ice Light, 그리고 단순한 IDE Dark / IDE Light. Automatic(IDE/OS 테마 추종)이 있는 Appearance 선택기 (Free: IDE 테마의 IDE Dark / IDE Light, 선택 불가)
• 사용자 테마 ZIP 팩 — 전역 설치(~/.microgulp/themes). 팩에 CSS, 그래픽, 글꼴, 선택적 사운드 아틀라스를 넣을 수 있습니다. Settings → Appearance에서 가져오기/제거 (Free에는 없음)
• 아이콘과 로그용 프로젝트 글꼴 — 글리프 µIcon과 실행 로그 서체용 RegisterDashboardFont / µDashboardFonts / dashboardFonts. 태스크별 선택 µIconFont(gulp-mu-gulp-api 0.3.12)
• 선택적 음향 제어 — 완료 소리, 오류 알람, 음성 출력(대시보드 설정)
• 선택적 폼 알림 — 태스크가 대시보드 입력을 기다릴 때, 설정 가능한 지연 후 소리 및/또는 음성으로 알림. 폼이 답할 때까지 반복
• 완료된 실행 자동 닫기 — 섹터 헤더의 선택 카운트다운(클릭하면 유지). 작업은 µAutoClose로 덮어씀(-1 유지, 양의 수는 초, 생략 시 Settings → Finished Runs, 기본 30초). Close 옆 Restart
• Windows 관리자 승격 — 태스크별 선택 UAC 프롬프트(µRequiresElevation, µElevationReason). IDE는 보통으로 두고 개별 태스크(예: hosts 편집)만 승격 (등록 VS Code / JetBrains. Free에는 없음)
• 진단 엔진 — 가져오기 오류와 스택 추적이 대시보드의 실행 가능한 제안이 됨 (등록 VS Code / JetBrains. Free에는 없음)
• gulpfile의 <version/> — 태스크 제목의 우선 소스는 µI18xContext.version. 선택 versionSources는 gulpfile이 version을 생략할 때만 채움(소비자 릴리스 설정을 덮어쓰지 않음)
• 신뢰할 수 있는 LogError 대 Node 경고 — LogError / 실제 console.error는 실행을 실패시킴. Node DeprecationWarning과 기타 프로세스 경고는 실패가 아님(실패 배너는 첫 실제 오류 텍스트를 표시)
• 레거시 프롬프트 브리지 — gulpfile을 고치지 않고 inquirer / gulp-prompt / prompts를 대시보드 폼으로 리디렉트
• gulp-mu-gulp-api — 태스크 안에서 진행, 소리, 음성, 대화형 입력, 모달, 대시보드 글꼴용 npm 모듈

스냅샷

Hosts	VS Code, Cursor AI, JetBrains IDEs(Settings → Tools → µGulp), microgulp-serve --http를 통한 127.0.0.1의 아무 브라우저
Runtime	Node.js 22+(ESM)
Gulpfiles	단일 gulpfile.mjs 또는 워크스페이스 정규식 검색
Config	확장 설정(VS Code/Cursor), Settings → Tools → µGulp(JetBrains), 선택 microgulp.config.json(팀 / CLI)
Engine	IDE 독립 — 모든 호스트에서 같은 src/engine
언어	대시보드 GUI: en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR(번들). gulp 출력은 프로젝트 i18x/gulp/. 핸드북은 대시보드 언어의 PDF
태스크 순서	µOrder(오름차순 정수). 그룹은 하위 트리 최소 순서. 순서 없는 태스크는 마지막(알파벳)

태스크를 클릭 → 따뜻한 워커가 즉시 실행. gulpfile을 편집 → 태스크 목록이 스스로 갱신. 여러 태스크를 병렬로 돌릴 수 있으며, 태스크가 gulp-mu-gulp-api의 ReportProgress를 호출하면 각 섹터에 네온 진행 막대가 생깁니다.

종속 없음: gulpfile은 일반 gulpfile로 유지됩니다

µGulp™를 도입해도 빌드가 µGulp™에 의존하지 않습니다. 대시보드용으로 준비한 gulpfile은 클래식 gulp CLI, CI, µGulp™를 한 번도 설치하지 않은 머신에서도 실행되며, µGulp™를 제거해도 계속 실행됩니다.

하위 호환 — 모두 평범한 gulp로 저하

추가하는 것	평범한 gulp가 하는 일
µDisplayName, µIcon, µGroup, µOrder, µKeyBinding, µWatch, µAutoClose, µRequiresElevation, …	아무것도 하지 않음. 내보낸 함수의 평범한 속성. gulp CLI는 내보내기 이름으로 태스크를 가리키고 알 수 없는 속성을 무시합니다. 태스크 이름과 CLI 주소는 그대로 — 그것이 µ 접두사의 이유입니다
µParameters	묻지 않음. 태스크는 GetParameters() / GetParameter(id, fallback)를 읽고, 선언된 기본값 또는 CI 작업에서 손으로 설정할 수 있는 MICROGULP_PARAMS / MICROGULP_PARAM_<ID> 환경 변수로 떨어집니다
ReportProgress(...)	네온 막대를 구동하는 대신 stdout에 퍼센트 줄을 출력(TTY에서는 단일 \r 줄, CI에서는 제한된 줄)
RequestForm, ShowModalMessage, PlaySignal, Speak, LogTable, LogChart, …	각 헬퍼에 CLI 폴백이 있음. 프롬프트는 기본값으로, 모달은 괄호 줄을 출력하고 ok를 반환, 소리와 음성은 no-op, 구조화 로그는 텍스트
.i18xRegister() / .i18xTrans()	i18xRegister()는 미국 영어 소스 문자열을 그대로 반환. 사전이 없으면 i18xTrans()는 소스 텍스트로 떨어짐. µGulp™ 없이는 영어 콘솔 출력만 나옴
.microgulp/(로그, 기억한 매개변수)	µGulp™가 태스크를 실행할 때만 기록. 버릴 수 있는 캐시 디렉터리 — .gitignore에 넣고 언제든 삭제

gulp-mu-gulp-api는 런타임 의존성 없는 일반 npm 패키지이며, IsMicroGulp()는 태스크가 오케스트레이션되는지 알려줍니다. µGulp™를 제거하는 것은 확장을 제거하는 것이며 gulpfile 편집은 필요 없습니다.

상위 호환 — 새 µGulp™ 버전이 옛 gulpfile을 깨지 않음

메타데이터는 가산적이고 알 수 없는 키는 양쪽에서 무시됩니다. 더 새 µGulp™용 gulpfile은 더 옛 버전에서도 실행되며 새 기능만 없을 뿐입니다(단축키 배지 없음, 워치 토글 없음, 매개변수 폼 없음 — 태스크는 시작). 알 수 없는 구조화 로그 형식은 실행을 깨지 않고 건너뛰며, 호스트 프로토콜은 버전 번호를 가져 오래된 호스트가 오해하지 않고 불일치를 감지합니다.

실무적 결과: 프로덕션 빌드 스크립트에서 µGulp™를 시험하고, 터미널에서 npx gulp BUILD를 쓰는 동료에게 같은 저장소를 넘겨도 어느 쪽도 서로를 눈치채지 못합니다.

설치

Marketplace 페이지는 예약되었지만 아직 공개되지 않았습니다(소스 저장소는 아직 비공개). 목록이 살아날 때까지 이 저장소 / GitHub Release의 패키지로 설치하십시오.

에디션	패키지	Marketplace(예정)
µGulp™(VS Code / Cursor)	packages/microgulp_latest.vsix	VS Code Marketplace · Open VSX
µGulp™ Free(VS Code / Cursor)	packages/microgulp-free_latest.vsix	VS Code Marketplace · Open VSX
µGulp™(JetBrains IDEs)	아래 JetBrains IDE 참고	JetBrains Marketplace(plugin id de.amekudzi.microgulp)

로컬 VSIX 설치:

code --install-extension packages/microgulp_latest.vsix       # VS Code, registered
cursor --install-extension packages/microgulp_latest.vsix     # Cursor AI, registered
code --install-extension packages/microgulp-free_latest.vsix  # VS Code, Free

• 소스에서 빌드: npm install 후 npm run build — 등록판과 Free .vsix가 packages/에 들어갑니다.

그다음 명령 팔레트에서 µGulp: Open Dashboard를 실행(또는 상태 표시줄의 µGulp™ 로켓을 클릭).

JetBrains IDE

JetBrains 플러그인은 플랫폼 플러그인(com.intellij.modules.platform)이며 IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip 및 기타 IntelliJ 계열 IDE에 설치됩니다. 패키지는 두 개 — IDE 빌드에 맞는 것을 고르십시오(Help → About):

IDE build	since-build	패키지
2024.2 – 2026.1(261.*까지)	242	packages/microgulp-jetbrains_latest.zip
2026.2 이상	262	packages/microgulp-jetbrains-2026.2_latest.zip

맞는 zip을 고르십시오. IntelliJ IDEA, PhpStorm, WebStorm 및 기타 IntelliJ 계열 IDE는 이 두 패키지를 공유합니다 — 제품명이 아니라 플랫폼 빌드로 고르십시오. 각 패키지 디스크립터에 <idea-version since-build="…"/>가 있어 IDE는 다른 쪽을 로드하지 않습니다. microgulp-jetbrains는 since-build="242" / until-build="261.*"(2024.2–2026.1). microgulp-jetbrains-2026.2는 since-build="262"이며 상한 없음(2026.2+). 플랫폼 빌드는 Help → About에 있습니다.

JetBrains Marketplace 목록(플러그인 ID de.amekudzi.microgulp)은 라틴 표시 이름 MicroGulp을 씁니다 — <name>에 µ와 ™은 허용되지 않습니다. 대시보드, 도구 창, 사이트, 이 README는 µGulp™을 유지합니다. 두 zip이 그 ID를 공유합니다. plugin.xml 버전은 RELEASES.json의 단일 제품 버전에서 SemVer 프리릴리스로 파생됩니다(<제품>-idea242, <제품>-idea262; Marketplace SemVer Only). 다만 제품 0.9.3의 242–261.* 채널은 marketplace 버전 0.9.3으로 남습니다(이미 제출됨). 0.9.3의 262 패키지는 0.9.3-idea262입니다. VS Code / Free는 접미사 없는 제품 버전을 유지합니다. zip 이름은 *_V<제품>.zip으로 남습니다. 두 JetBrains 패키지는 같은 제품 변경 기록을 실습니다. 라이선스: https://microgulp.dev/en/license/. 소스 저장소는 비공개로 남습니다 — Marketplace 목록에 소스 코드 URL을 올리지 마십시오.

빌드 262는 JCEF를 핵심 플랫폼에서 번들 Web Browser (JCEF) 플러그인으로 옮겼으므로 디스크립터가 명시적으로 선언해야 합니다 — 그래서 별도 패키지입니다. *Settings → Plugins → ⚙ → Install Plugin from Disk…*로 설치하고 µGulp 도구 창을 엽니다. 엔진 옵션은 Settings → Tools → µGulp(Node 경로, gulpfile 검색, preload/pool, watch, 실행 로그) — VS Code microgulp.*와 같은 역할. 모양, 소리, 언어는 대시보드 ⚙ 패널에 남습니다. 플러그인은 얇은 JCEF 어댑터이며 엔진 전체는 번들 Node.js 사이드카에서 돌아가므로 Node.js 22+가 설치되어야 합니다(PATH, MICROGULP_NODE, 또는 Node 경로 설정). JCEF를 쓸 수 없으면 — 축소 IDE 빌드, 브라우저 플러그인 비활성 — 도구 창은 그래도 엔진을 시작하고 일반 브라우저에서 대시보드를 여는 단추를 제공합니다.

패키지 빌드와 검사

npm run jetbrains(별칭 npm run phpstorm)이 두 zip을 만들고 npm run jetbrains:verify가 검사합니다. Gradle 없음:

• 각 패키지는 지원하는 가장 오래된 IntelliJ 플랫폼에 대해 컴파일됩니다 — 242 패키지는 2024.2 IDE, 262 패키지는 설치된 IDE. 더 새 빌드에만 있는 API는 javac가 거부하여 출하하지 않습니다. 어댑터는 플랫폼 API(도구 창, 설정, JCEF, 편집기)만 쓰므로 같은 zip이 모든 IntelliJ 계열 IDE에서 돌아갑니다.
• npm run jetbrains:verify는 JetBrains Plugin Verifier를 두 zip에, 선언 범위 양끝(레거시는 2024.2와 2026.1, 다른 것은 262)에서 돌립니다. 빠진 클래스/메서드, 폐기 또는 내부 API, 디스크립터 결함을 보고합니다.
• Plugin Verifier fat-jar는 dev/tools/intellij-plugin-verifier/에 있습니다(verifier-cli-1.410-all.jar. 없으면 Maven Central에서 그곳으로). 필요한 IntelliJ 플랫폼 배포본은 한 번 MICROGULP_IDE_CACHE(기본 %LOCALAPPDATA%\microgulp\ide-cache, 다른 곳은 ~/.cache/microgulp/ide-cache)에 받아 재사용. 로컬 IDE 빌드가 맞으면 그것을 직접 씁니다. MICROGULP_SKIP_IDE_DOWNLOAD=1은 오프라인 빌드를 유지 — 설치된 IDE에 대해 컴파일하고 빠진 검증 대상은 건너뜁니다.
• verifier가 못 보는 점: 전체 IDE에 대해 해석하고 콘텐츠 모듈의 classloader 격리를 무시하므로, 빠진 모듈 의존성도 호환으로 읽힙니다. 그래서 빌드는 JCEF를 건드리는 262+ 패키지를 com.intellij.modules.jcef와 그 두 모듈 없이 포장하지 않습니다.

알려진 JetBrains / JCEF 로그 소음(무해)

µGulp 도구 창이 처음 대시보드를 넣을 때 IDE 로그에 이런 오류가 날 수 있습니다:

JBCefApp$Holder <clinit> requests ProxyMigrationService instance. Class initialization must not depend on services.

이는 JetBrains 자체 JCEF 스택(JBCefApp → 프록시 설정 → HttpConfigurable)에서 오며 µGulp 플러그인이 아닙니다. 플랫폼은 JCEF 시작을 완료합니다. 그다음 대시보드가 보이면 이 항목은 무시해도 됩니다. PhpStorm 2025 대 2026과 무관하며, 같은 JCEF 빌드를 쓰는 어떤 JetBrains IDE도 낼 수 있습니다. 도구 창이 비어 있거나 실제 µGulp 시작 오류(Node 경로, 사이드카, gulpfile 스캔)가 있을 때만 더 조사하십시오.

같은 대시보드는 아무 일반 브라우저에서도 돌아갑니다: npm run serve -- --cwd <project> --http 9310 --preload 후 http://127.0.0.1:9310/를 엽니다.

구성 파일 microgulp.config.json(JetBrains와 CLI)

VS Code / Cursor에서 엔진은 확장 설정(microgulp.gulpfilePattern 등)으로 구성됩니다. JetBrains 플러그인은 같은 엔진 옵션을 Settings → Tools → µGulp에 반영하고, 다음 도구 창 열 때 사이드카 CLI 플래그로 넘깁니다. 선택적으로 프로젝트 루트 **microgulp.config.json**이 팀 기본값과 IDE 페이지에 없는 키(dashboardFonts, metadataWatchFiles, versionSources)를 여전히 공급합니다. CLI 플래그가 없을 때 microgulp-serve의 일반 CLI/브라우저 사용은 파일을 읽습니다:

{
	"gulpfilePattern": "gulpfile.*\\.mjs$",
	"poolSize": 2,
	"maxParallel": 6,
	"preload": true,
	"watchGulpfiles": true
}

Key	Type	Default	Meaning
gulpfile	string	"gulpfile.mjs"	Single gulpfile, relative to the project root
gulpfilePattern	string	—	Case-insensitive regex against workspace-relative POSIX paths; discovers all matching gulpfiles (wins over gulpfile)
poolSize	int ≥ 0	2	Warm workers per gulpfile
maxParallel	int ≥ 1	6	Maximum concurrent task runs
preload	bool	false	Warm up the worker pools right after startup (PhpStorm IDE setting defaults to on; CLI needs --preload)
watchGulpfiles	bool	true	Auto-rescan on gulpfile changes
metadataWatchFiles	string[]	["package.json", "RELEASES.json"]	Optional. Workspace-relative files whose changes trigger a metadata rescan (e.g. after a version bump). Prefer watching the file your gulpfile reads at init.
versionSources	string[] or objects	["package.json"]	Optional. Live JSON fallback for <version/> when the gulpfile does not set µI18xContext.version. Rarely needed for consumer projects — see below.
dashboardFonts	array	—	Optional. Project fonts for task icons / run log (see 대시보드 글꼴)
logToFile	bool	true	Persist run transcripts (.log + .ndjson) and the task history to disk
logDirectory	string	.microgulp/logs	Directory for transcripts and the history index, relative to the project root
logRetention	int ≥ 0	200	Max runs kept in the history (0 = unlimited); older runs and their log files are pruned

우선순위: 명령줄 / JetBrains IDE 설정 > microgulp.config.json > 내장 기본값. 잘못된 값과 알 수 없는 키는 stderr 경고와 함께 무시. 파일은 버전 관리 가능하며 팀 전체에 적용됩니다. IDE 설정이나 파일을 고친 뒤 µGulp 도구 창을 다시 열거나(사이드카 재생성) microgulp-serve를 재시작하십시오.

VS Code / Cursor에서는 같은 키가 microgulp.metadataWatchFiles와 microgulp.versionSources로 있습니다(비어 있지 않은 확장 설정이 microgulp.config.json을 이김). 빈 배열은 메타데이터 감시나 파일에서 라이브 버전 읽기를 끕니다.

태스크 제목의 <version/>(권장 vs 선택)

권장(대부분의 소비자 프로젝트): gulpfile에서 µI18xContext를 내보내고 거기서 version을 설정(모듈 초기화 때 단일 릴리스 소스를 읽음). 그 소스 변경이 재스캔하고 따뜻한 워커를 새로 고치도록 metadataWatchFiles를 쓰십시오:

export const µI18xContext = { project: 'MyApp', version: _ReadReleaseVersion() };
MAKE_BUILD.µDisplayName = 'Build V<version/><context="µDisplayName"/>'.i18xRegister();

{
	"metadataWatchFiles": ["configs/systemconfig.js"]
}

µI18xContext.version이 설정되면 라이브 versionSources는 그것을 덮어쓰지 않습니다.

선택 — versionSources: µI18xContext.version을 설정하지 않고 엔진이 디스크 JSON에서 <version/>을 해석하게 하고 싶을 때만 유용합니다(gulpfile을 다시 가져오지 않고 GetTasksPayload에서 새로 고침). 지원 형태:

• "package.json" — npm "version" 필드 사용
• "RELEASES.json" — µGulp 스타일 파일. 정확한 스키마는 버전 관리 (RELEASES.json)(releases[0].main / minor / revision)
• { "file": "config/version.json", "field": "version" } — 임의 JSON 파일 + 점 필드 경로

예(선택 라이브 JSON만 — gulpfile version 없음):

{
	"metadataWatchFiles": ["package.json", "RELEASES.json"],
	"versionSources": ["RELEASES.json", "package.json"]
}

로직: src/engine/ProjectMetadata.mjs. 자리 표시자는 BuildSourceI18xContext에서 만듭니다.

프로젝트 구조

gulpfile.mjs             Project build: tests, theme CSS (µCSS), package + deploy
RELEASES.json            Version source (main/minor/revision, i18xe-ready info texts)
gulp-mu-gulp-api/        Standalone npm module: public task API
  src/index.mjs          Progress, text/color/font/select inputs, forms
  tests/                 The module's own node:test suite
skins/                   One directory per skin (neon-carbon is the default)
  neon-carbon/
    neon-carbon.µcss.mjs µCSS skin manifest (Carbon/Neon variables)
    neon-carbon.µ.css    Skin source → compiled into src/webview/skins/neon-carbon/
  ice-light/             Light frosted-glass skin (cool blue outward glow)
    ice-light.µcss.mjs   µCSS skin manifest (ice palette)
    ice-light.µ.css      Skin source → compiled into src/webview/skins/ice-light/
  ide-dark/              Plain IDE-aligned dark (VS Code–like, no neon/carbon)
  ide-light/             Plain IDE-aligned light companion
src/
  engine/                IDE-independent core (no VS Code APIs!)
    TaskEngine.mjs       Orchestrator: scan, preload, queue, events
    TaskWorkerPool.mjs   Pool of prewarmed worker processes
    ConcurrencyGuard.mjs Evaluates executionConcurrency/-Restrictions
    Diagnostics.mjs      Diagnosis engine (stack traces → concrete suggestions)
    PluginHost.mjs       Lifecycle hooks for plugins
    GulpfileDiscovery.mjs  Regex-based gulpfile discovery in the workspace
    ReleaseInfo.mjs      Release management: RELEASES.json, version strings, history
  worker/
    TaskWorker.mjs       Child process: imports the gulpfile, runs tasks
  bridge/
    gulp-ugulp-bridge.mjs  Public bridge: npm packages ↔ webview forms
  host/
    HostProtocol.mjs     Event/command names (the single host boundary)
    Daemon.mjs           Engine owner for sidecar hosts
    microgulp-serve.mjs  stdio NDJSON CLI (PhpStorm preparation)
  extension/
    extension.cjs        Thin VS Code / Cursor adapter (the only CJS module)
  webview/
    dashboard.css        Fallback stylesheet for fresh checkouts
    dashboard.js         TaskGrid, log streaming, forms, audio engine
    skins/<name>/dashboard.css  µCSS-generated skins (webview default: neon-carbon)
tests/                   node:test suites (unit + engine integration)
demo/
  gulpfile.mjs           Example gulpfile with every µGulp™ metadata tag
  run-demo.mjs           Headless engine smoke test (no IDE)
dev/
  prompts/               AI migration prompts (existing gulpfile → µGulp + i18x)
    OptimizeGulpfileForMicroGulp.md
    OptimizeGulpfileForMicroGulp.params.example.json

아키텍처 원칙

• 엔진 층은 IDE가 없습니다. src/engine과 src/worker는 VS Code API를 모릅니다. 통신은 이벤트(엔진 → 호스트)와 평범한 JSON 명령(호스트 → 엔진)입니다. PhpStorm으로의 이식(2단계)은 따라서 순수 어댑터 교체입니다. 최소 사이드카 npm run serve(src/host/microgulp-serve.mjs, stdio의 NDJSON)는 이미 있습니다.
• 태스크 프리로드. TaskWorkerPool은 gulpfile을 이미 가져온 예열 Node 프로세스를 유지합니다. 태스크 시작은 따뜻한 워커를 넘기고 백그라운드에서 풀을 채웁니다. 실행 후 프로세스는 버려집니다(새 모듈 상태).
• 동적 가져오기. 무거운 npm 패키지(mssql, docx-templates, makensis, …)는 태스크 본문 안에서만 await import()로 로드해야 합니다. 정적 최상위 import는 오케스트레이터 핵심 로직 전용입니다.
• 언어. GUI 텍스트는 미국 영어이며 String.i18xTrans()를 거칩니다(i18xe 배선은 후속). 코드 주석은 영어. 매뉴얼/문서는 독일어.

대시보드 로컬라이제이션

대시보드 GUI는 en-US(소스), de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR의 번들 i18x 사전과 함께 출하됩니다. 언어는 대시보드 설정에서 고릅니다(automatic은 호스트 또는 브라우저 로케일을 따름). gulpfile 콘솔 출력은 워커의 MICROGULP_LANG과 프로젝트의 i18x/gulp/<lid>.json으로 같은 언어를 씁니다. 사용자 핸드북은 대시보드 언어의 PDF.

i18xe 서버 없이 이 gulp 사전을 심거나 새로 고치려면: Settings → Project i18x (gulp) → Scan & update i18x/gulp…. µGulp™는 i18xe-sync 스캐너(더하기 Log/Warn/LogError)로 구절을 파싱하고, 기존 번역을 유지하며, 표준 형식 정의를 병합하고, 로컬 AI 번역용 <lid>.status.json 사이드카(missing / orphans)를 씁니다.

Layer	Who provides it	Today	Planned
Dashboard GUI	µGulp (extension)	en-US, de-DE, zh-CN, fr-FR, es-ES, ru-RU, ja-JP, ko-KR	More marketplace languages via the i18xe sync pipeline
Gulp tasks & logs	Your project	i18x/gulp/*.json next to the gulpfile	Same — consumer projects never ship i18x/prod
Hyphenation	µGulp webview assets	String.prototype.Hyphenation() with bundled <lid>.hyphen.json where present	Additional locales as hyphen data is synced from i18xe

컨텍스트 태그, 필수 형식, 언어 로드맵: dev/docs/MicroGulpI18xProfile.md. 대시보드 GUI 사전용 라이브 i18xe 서버 연결은 선택으로 남습니다(레인 3). 소비자 gulp 사전은 위의 오프라인 스캔을 씁니다.

Gulpfile 검색 (정규식으로 구성)

µGulp™는 디스크의 gulpfile 변경을 스스로 알아챕니다. 워크스페이스 워처(microgulp.watchGulpfiles, 기본 켜짐)가 변경 후 자동 재스캔하고 따뜻한 워커를 현재 코드의 새 것으로 바꿉니다. 스캔 중 태스크 목록은 애니메이션 진행을 보여 줍니다. 그래서 대시보드에 재스캔 단추는 더 없습니다. µGulp: Rescan Tasks 명령(명령 팔레트)은 수동 강제 새로 고침으로 남습니다. gulpfile 로드 실패(구문 오류, 빠진 모듈)면 진단과 스택 추적이 있는 닫을 수 있는 오류 배너가 대시보드에 나타납니다.

µGulp™는 단일 경로 또는 워크스페이스 전체를 찾는 정규식 패턴으로 gulpfile을 찾습니다:

• microgulp.gulpfilePattern — 워크스페이스 상대 경로(/ POSIX 표기)에 대한 JavaScript 정규식(대소문자 무시). 설정되면 일치하는 모든 파일을 스캔하고 태스크는 대시보드에서 소스별로 묶입니다. 예: (^|/)gulpfile\.(m|c)?js$는 루트와 각 하위 폴더의 gulpfile.mjs/.js/.cjs를 찾습니다.
• microgulp.gulpfilePath — 클래식 단일 경로(기본 gulpfile.mjs). gulpfilePattern이 비어 있을 때만 사용.

node_modules, .git, 숨김 폴더(.*)에는 내려가지 않습니다. 발견한 각 gulpfile은 gulpfile 폴더를 작업 디렉터리로 하는 자체 따뜻한 워커 풀을 받아, 상대 경로의 중첩 하위 프로젝트도 올바르게 실행됩니다. 검색 로직은 IDE 독립적으로 src/engine/GulpfileDiscovery.mjs에 있어 CLI와 JetBrains 어댑터에서도 쓸 수 있습니다.

둘 이상의 gulpfile이 맞으면 왼쪽 태스크 열은 스크립트 파일마다 소스 제목(워크스페이스 상대 경로, 예: gulpfile.mjs, nested/gulpfile.mjs)을 보이고, 다른 파일의 태스크는 최상위에서 섞이지 않습니다. 각 소스 안에서는 여전히 µGroup 경로(Build/Production, …)로 중첩됩니다. 하나의 gulpfile이면 제목은 생략되고 µGroup 중첩만 적용됩니다. 스캔한 gulpfile이 태스크를 내보내도 어느 것도 gulp-mu-gulp-api를 import하지 않으면, 대시보드는 npm 패키지와 AI 마이그레이션 프롬프트로 가는 닫을 수 있는 힌트를 보입니다.

Gulp 작업의 µGulp™ 메타데이터

권장 형태는 CamelCase의 µ 접두 태그(µDisplayName, µIcon, …)입니다. 클래식 gulp CLI에는 보이지 않아 µGulp™가 없는 시스템에서도 gulpfile이 완전히 호환됩니다(gulp CLI는 function.displayName으로 태스크를 가리킴. 공백이 있는 예쁜 이름은 거기서 태스크 지정을 깨뜨림):

export async function BUILD_STYLES() { /* ... */ }
BUILD_STYLES.µDisplayName = 'Build Styles';
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.';
BUILD_STYLES.µTooltip = 'Runs the µCSS pipeline (sprites, fonts, sounds included).';
BUILD_STYLES.µIcon = '\u25A3';   // font symbol — or an image data URI:
// BUILD_STYLES.µIcon = 'data:image/svg+xml,%3Csvg ...';  (png/webp too)
BUILD_STYLES.µIconFont = 'ProjectIcons'; // optional — see Dashboard fonts below
BUILD_STYLES.µGroup = 'Build/Assets';                 // nested group (path syntax)
BUILD_STYLES.µOrder = 10;                             // sort position in the dashboard (ascending)
BUILD_STYLES.µExecutionConcurrency = true;            // false = exclusive
BUILD_STYLES.µExecutionRestrictions = { deny: ['CLEAN'] }; // parallel matrix
BUILD_STYLES.µKeyBinding = { key: 'ctrl+shift+B', mac: 'cmd+shift+B' }; // dashboard shortcut
BUILD_STYLES.µWatch = { files: ['skins/**/*.µ.css'] }; // optional file trigger
BUILD_STYLES.µAutoClose = -1;                         // keep the finished sector
BUILD_STYLES.µParameters = [                          // asked before the run
  { id: 'target', type: 'select', options: ['debug', 'release'], default: 'debug' },
];
// Windows only — show the UAC prompt when the host is not already elevated:
BUILD_STYLES.µRequiresElevation = true;
BUILD_STYLES.µElevationReason =
  'Modifies the Windows hosts file.<context="µElevationReason"/>'.i18xRegister();

µGroup은 태스크 개요의 중첩 그룹에 할당합니다. 정의는 디렉터리 경로 문법: µGroup = 'Build/Production'은 Build 그룹과 Production 하위 그룹을 만듭니다. 그룹은 대시보드에서 접을 수 있습니다. µGroup 없는 태스크는 최상위에 남습니다. 할당은 선택이며 순수 시각 — 실행이나 동시성에 영향 없습니다.

µOrder는 왼쪽 열의 정렬 위치(오름차순 정수)입니다. 형제 태스크와 그룹은 µOrder로 정렬되고, 값 없는 태스크는 모든 정렬된 태스크 뒤(타이브레이크: 표시 이름). 그룹은 하위 트리의 가장 낮은 µOrder로 정렬됩니다.

그룹 헤더의 수정 키:

Action	Effect
Click	toggle the group
Ctrl+Click (Cmd+Click)	toggle every group on the same level
Alt+Click	toggle all groups

µRequiresElevation은 Windows에서 관리자 권한이 필요한 태스크를 표시합니다(예: C:\Windows\System32\drivers\etc\hosts 다시 쓰기). IDE가 보통으로 돌면 µGulp™는 일회 승격 워커를 시작하고 평소 UAC 대화상자를 보여 줍니다. Cursor나 VS Code를 관리자로 시작할 필요는 없습니다. 호스트 프로세스가 이미 승격되어 있으면 따뜻한 워커 풀을 평소처럼 씁니다. 비 Windows에서는 플래그를 무시합니다. 선택 µElevationReason은 태스크 툴팁에 나타납니다(대시보드의 ⚑ 배지).

태스크 단축키 (µKeyBinding)

태스크는 자체 키보드 코드를 가질 수 있습니다. 코드는 대시보드에 포커스가 있는 동안 동작합니다. VS Code와 PhpStorm은 런타임에 키바인딩을 등록할 수 없으므로, µGulp™는 IDE 전역 키를 소유한 척하지 않고 스스로 처리합니다.

BUILD.µKeyBinding = 'ctrl+shift+B';                      // same chord everywhere
DEPLOY.µKeyBinding = { key: 'ctrl+alt+D', mac: 'cmd+alt+D' };
STOP.µKeyBinding = { key: 'ctrl+shift+Escape' };         // named keys: F1…F24, Escape, Tab, Space, arrows, …

Part	Accepted
Modifiers	ctrl, control, alt, option, shift, meta, cmd, command, super, win
Keys	single characters (b, 7, +), F1–F24, Escape/Esc, Enter, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up/Down/Left/Right
Platform keys	key (fallback), mac, win, linux — the matching platform wins, key fills the rest

cmd는 macOS에서 Command 키, 그 밖에서는 Ctrl이므로 단일 key 코드는 모든 플랫폼에서 쓸 수 있습니다. 코드는 태스크 이름 옆 배지로 나타납니다. 두 태스크가 같은 코드를 주장하면 두 배지가 호박색이 되고 툴팁이 그렇게 말합니다(µGulp™는 어느 쪽을 뜻했는지 추측하지 않음).

진짜 IDE 전역 단축키는 명령 µGulp: Run Task를 직접 바인딩하십시오. 태스크를 인수로 받습니다:

// keybindings.json (VS Code / Cursor)
{ "key": "ctrl+shift+f9", "command": "microgulp.runTask", "args": { "task": "gulpfile.mjs::BUILD_STYLES" } }

args 없으면 스캔된 태스크의 빠른 선택을 엽니다.

선언적 태스크 매개변수 (µParameters)

태스크 본문 안에서 입력을 묻는 대신, 필요한 것을 선언할 수 있습니다. µGulp™는 실행 시작 전에 한 폼을 보여주고, 다음을 위해 답을 기억하며, 환경으로 값을 태스크에 넘깁니다:

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 = {
  submitLabel: 'Start Deploy<context="button text"/>'.i18xRegister(),
  fields: [
    { id: 'target', type: 'select', options: ['staging', 'production'], default: 'staging',
      label: 'Target<context="task parameter"/>'.i18xRegister() },
    { id: 'tag', type: 'text', required: true, pattern: '^v\\d+\\.\\d+' },
    { id: 'servers', type: 'checkbox', options: ['a', 'b'], required: true }, // submit stays disabled until ≥1
    { id: 'dryRun', type: 'boolean', default: true },
    { id: 'notify', type: 'boolean', default: false,
      visibleWhen: { dryRun: false } },   // only when not a dry run
    { id: 'token', type: 'password' },   // never stored, never logged
  ],
};

평범한 필드 배열도 여전히 동작합니다. 래퍼는 폼 크롬(title, submitLabel)을 더합니다. 태스크의 µParameterSubmitLabel은 단추 텍스트의 동등한 대안입니다.

Field	Meaning
id	required; must be env-var safe ([A-Za-z_][A-Za-z0-9_]*)
type	text (default), textarea, password, number, range, boolean (slide switch), checkbox (multi-select), radio, select, font, color
label, description, placeholder	shown in the form (i18x via .i18xRegister())
default	pre-filled value; a remembered answer from the last run wins
options	['a','b'], [{ value, label, disabled }] or { a: 'Label A' }
required, pattern, minLength, minSelected	validated live in the dashboard — the submit button stays disabled until every visible rule passes (required on a checkbox means at least one option)
min, max, step, rows	numeric / textarea details
remember	false keeps the value out of the store (implicit for password)
visibleWhen	show the field only while other answers match — e.g. { dryRun: false } or { servers: 'prod' } (multi-select: contains). Hidden fields are not validated; missing answers fall back to default
submitLabel / title	form wrapper keys (or µParameterSubmitLabel / µParameterTitle on the task) — i18x via .i18xRegister()

값은 MICROGULP_PARAMS(JSON)와 매개변수마다 평평한 MICROGULP_PARAM_<ID>로 오므로 태스크 안 셸 단계도 읽을 수 있습니다. gulp-mu-gulp-api의 GetParameters() / GetParameter('target', 'staging')가 파싱합니다. 평범한 gulp CLI에서는 같은 변수를 손으로 줄 수 있습니다:

MICROGULP_PARAM_TARGET=staging npx gulp DEPLOY

답은 태스크마다 .microgulp/parameters.json에 기억되어 다음 폼을 채웁니다. 비밀번호와 remember: false 값은 저장소에도 전사본·기록·대시보드에도 쓰이지 않고 ••••로 보입니다. 실행 로그와 기록 항목은 실행이 시작한 값을 기록해 나중에 무엇을 답했는지 볼 수 있습니다. 승격 태스크(µRequiresElevation)는 일방 프로세스에서 폼을 보여줄 수 없어 선언 기본값보다 기억된 값으로 실행됩니다.

워치 / 트리거 태스크 (µWatch)

관심 있는 파일이 바뀌면 태스크가 스스로 실행될 수 있습니다:

BUILD_CSS.µWatch = 'src/**/*.µ.css';                  // shorthand
BUILD_CSS.µWatch = {
  files: ['src/**/*.µ.css', 'skins/*/manifest.json'], // globs, relative to the gulpfile
  ignore: ['**/*.tmp'],
  debounceMs: 300,                                    // quiet time after the last change
  autoStart: false,                                   // arm as soon as the gulpfile is scanned
  parameters: { target: 'debug' },                     // fixed µParameters for triggered runs
};

감시는 태스크별 옵트인입니다. 선언이 autoStart: true가 아니면 태스크 이름 옆에 ◉ 토글(무장 시 시안)이 나타납니다. 글롭은 **, *, ?, {a,b}, 문자 클래스를 지원. node_modules, .git, .microgulp, .idea, .vscode는 절대 감시하지 않습니다.

가드레일. 자기 감시 집합에 쓰는 빌드 태스크는 그렇지 않으면 영원히 돕니다:

• 변경 이벤트 폭주는 한 실행이 됨(디바운스)
• 태스크 실행이 활성인 동안 후속 실행은 최대 하나 대기
• 1분에 트리거 실행 20회 초과는 워처를 일시 중지(호박색 토글, 툴팁이 이유 설명). 끄고 다시 켜면 재무장

트리거 실행은 발화한 파일을 로그에 이름 붙이고(Triggered by src/a.css) 매개변수 폼을 절대 열지 않습니다. 트리거는 고정 또는 기억 값을 쓰므로, 보고 있지 않은 사람을 기다리지 않습니다.

완료된 실행을 열어 두기 (µAutoClose)

완료된 섹터는 기본 30초 후에 닫힙니다(Settings → Finished Runs). 작업에서 덮어쓸 수 있습니다:

SHOW_OUTPUT.µAutoClose = -1;   // 섹터 유지(자동 닫기 없음)
QUICK.µAutoClose = 8;          // 8초 후 닫기

값	의미
생략 / true	대시보드 설정(기본 30초)
-1, false, 0	이 작업을 자동으로 닫지 않음
양의 정수	해당 초 후에 닫기(대시보드 지연을 덮어씀)

노란 카운트다운 칩으로 섹터를 유지할 수 있습니다. µAutoClose는 숫자 또는 boolean이며 .i18xRegister()는 쓰지 않습니다.

클릭 가능한 오류 위치

실행 로그의 파일 참조는 링크가 됩니다: src/engine/TaskEngine.mjs:412:9, at Object.<anonymous> (gulpfile.mjs:88:15), tsc/eslint 출력, MSBuild 스타일 file(12,7). 클릭(또는 Enter)하면 호스트 편집기의 그 줄·열이 열립니다 — VS Code/Cursor는 편집기 탭, PhpStorm은 JCEF 브리지를 통한 IDE 편집기.

경로는 호스트에서 먼저 실행의 gulpfile 디렉터리, 다음 워크스페이스 루트에 대해 해석되므로, 다중 gulpfile 워크스페이스도 모호한 이름의 올바른 복사본으로 뜁니다. 소스형 확장자의 기존 파일만 엽니다. URL, 타임스탬프, 버전 번호는 그대로 둡니다.

테마 팩 (ZIP)

사용자 대시보드 테마는 ZIP 팩으로 배포하고 전역으로 설치할 수 있습니다(사용자 전체 ~/.microgulp/themes/, 덮어쓰기는 MICROGULP_THEMES_DIR). 프로젝트 워크스페이스와 독립입니다.

팩 레이아웃(미리 컴파일 — µCSS 소스 불필요):

manifest.json     // { "id", "displayName", "version", "appearance": "dark"|"light" }
dashboard.css
imgs/…            // optional graphics / cursors
fonts/…           // optional
snds/…            // optional µAU atlas: microgulp.sounds.weba (or .wav/.mp3) + microgulp.sounds.json

대시보드: Settings → Appearance → Import theme ZIP…. 내장 스킨은 선택기에 남습니다. Automatic은 여전히 Neon Carbon / Ice Light로 매핑. 팩 제거는 Remove selected pack.

이 저장소에서는 npm run theme 후 컴파일된 스킨을 팩할 수 있습니다:

node dev/tools/pack-theme.mjs ide-dark
# → packages/microgulp-theme-ide-dark.zip

사운드 아틀라스 (µAU)

대시보드 신호는 dev/media/final/sounds/microgulp/에서 만듭니다. **default/**가 모든 스킨의 기반. 선택 <skin-id>/ 폴더가 파일명 줄기로 덮어씀. 아틀라스는 WebA(오디오 전용 WebM/Opus, microgulp.sounds.weba)로 출하. 동일 샘플은 중복 제거. 전체 카탈로그: dev/docs/MicroGulpSoundSchema.md.

PlaySignal('success'|'error'|'attention')은 taskSuccess / taskFailed / requestAlert로 매핑. PlaySound는 스키마 이름을 직접 씁니다.

대시보드 글꼴 (태스크 아이콘과 실행 로그)

프로젝트 글꼴은 내장 스킨과 독립입니다. gulpfile(권장) 또는 microgulp.config.json / 설정 microgulp.dashboardFonts로 등록:

import { RegisterDashboardFont } from 'gulp-mu-gulp-api';

RegisterDashboardFont({
  id: 'ProjectIcons',
  file: 'assets/task-icons.woff2',   // relative to the gulpfile directory
  usage: 'task-icons',               // or 'log' / 'all'
});

// Or declarative:
export const µDashboardFonts = [
  { id: 'ProjectLog', file: 'assets/log.woff2', usage: 'log' },
];

BUILD.µIcon = '\uE101';
BUILD.µIconFont = 'ProjectIcons';     // optional when a single task-icons font is registered

usage: 'task-icons'는 글리프 µIcon 항목을 꾸밉니다(처음 등록한 글꼴이 기본. µIconFont가 태스크마다 덮어씀). usage: 'log'는 실행 섹터 로그 서체를 설정. 파일은 워크스페이스 아래에 두어야 합니다(woff2 / woff / ttf / otf).

속성별 폴백 연쇄: µDisplayName → ugulp.displayName(네임스페이스 객체) → displayName(Gulp 자체 필드) → 내보내기 이름. executionRestrictions는 deny(항상 이김)와 allow(화이트리스트: 목록에 없는 것은 금지)를 지원합니다.

태스크 메타데이터 문자열은 구절 안의 컨텍스트 태그가 있는 i18x를 씁니다. **.i18xRegister()**는 구절을 i18xe-sync와 프로젝트 사전에만 등록하고 소스 텍스트를 그대로 반환합니다. 번역은 대시보드가 메타데이터를 그릴 때(i18x-catalog의 TransProperty()) 일어나며 <version/> 같은 자리 표시자는 µI18xContext에서 채워집니다. 콘솔 출력에는 .i18xTrans() 또는 **Log()/Warn()/LogError()**를 써서 런타임에 즉시 번역합니다(자리 표시자 포함):

BUILD_STYLES.µDisplayName = 'Build Styles<context="µDisplayName"/>'.i18xRegister();
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();

컨텍스트 태그, 필수 형식, 마켓플레이스 언어 계획: dev/docs/MicroGulpI18xProfile.md.

AI 지원 gulpfile 마이그레이션

기존 대형 gulpfile(콘솔 출력, 태스크 메타데이터, i18x/gulp 사전, 선택 µKeyBinding / µParameters / µWatch / µAutoClose)을 이전하려면 저장소의 유지 프롬프트를 쓰십시오:

File	Purpose
dev/prompts/OptimizeGulpfileForMicroGulp.md	Copy-paste prompt for Cursor, Claude, ChatGPT, …
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json	Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version)

Workflow

1. params 예를 프로젝트 루트에 microgulp-optimize.params.json으로 복사하고 projectRoot, gulpfilePath, supportedLanguages(예: en-US, de-DE, zh-CN), gulpMuGulpApiVersion(^0.4.0 이상), microGulpMinVersion(0.7.0), githubRepoUrl / githubRef(기본: https://github.com/mamekudz/microGulp, V0.7.0 또는 main)를 채웁니다.
2. 프롬프트 마크다운을 열고 {{PLACEHOLDER}} 표를 값으로 바꾸거나 Cursor에서 params 파일과 gulpfile을 첨부합니다.
3. AI가 마이그레이션을 실행하게 합니다. 프롬프트의 0단계는 필수: 편집 전 타임스탬프가 있는 gulpfile 백업(예: gulpfile.mjs.20260703-142559.bak).
4. node --check gulpfile.mjs로 확인하고 µGulp 대시보드에서 태스크를 시험(대시보드 포커스 중 새 단축키 포함)한 뒤 gulpfile.mjs, i18x/gulp/*.json, package.json을 커밋합니다.

소비자 프로젝트는 i18x/gulp/<lid>.json만 필요합니다 — i18x/prod 없음. 프롬프트는 µGulp 릴리스와 함께 갱신됩니다. 이전 전에 이 저장소의 최신판을 확인하십시오. i18x 규칙(register 대 translate, µMeta 없음)과 선언적 UX를 다룹니다: 대시보드 µKeyBinding(사용자가 microgulp.runTask를 바인딩하지 않으면 IDE 전역이 아님), µParameters / GetParameters(), µWatch, µAutoClose.

공개 작업 API (gulp-mu-gulp-api)

스트림 안의 제3자 gulpfile과 npm 패키지는 독립 npm 모듈 **gulp-mu-gulp-api**(gulp-mu-gulp-api/ 아래 자체 프로젝트, npm에 별도 게시)를 통해 확장 대시보드 기능을 씁니다:

import { ReportProgress, RequestTextInput, RequestColorInput, RequestForm, ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

export async function BUILD_THEME() {
    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
    let title = await RequestTextInput({ label: 'Product title', validate: { required: true, minLength: 3 } });
    let ok = await ShowConfirmMessage({
        title: 'Overwrite theme?',
        message: 'Existing skin files will be replaced.',
        presentation: 'webview',
    });
    if (ok.button !== 'yes') return;
    for (let step = 1; step <= 10; step++) {
        // ... work ...
        ReportProgress(step / 10, 'compiling theme');   // determinate neon progress bar in the sector
    }
    await ShowModalMessage({
        variant: 'info',
        title: 'Theme ready',
        message: 'Skin files written.',
    });
}

모듈은 의존성 없고 µGulp™ 워커의 IPC 채널로 엔진과 직접 이야기합니다(감지는 IsMicroGulp() / IsµGulp()). µGulp™ 없이는 깨끗이 저하: 진행은 터미널로, 입력은 readline(TTY) 또는 기본값(CI). 자세한 내용은 gulp-mu-gulp-api/README.md. 내부 모듈 src/bridge/gulp-ugulp-bridge.mjs는 저수준 전송으로 남습니다. 새 소비자는 gulp-mu-gulp-api를 써야 합니다.

모달 대화상자 (ShowModalMessage)

V0.5.29부터(API: gulp-mu-gulp-api 0.3.11+) 태스크는 차단 모달 대화상자를 보일 수 있습니다 — 확인, 계속 전 경고, 예/아니요와 OK/취소. 일상 로그 줄에는 쓰지 마십시오. 일반 출력은 Log() / 구조화 로그 헬퍼를 선호.

Webview 유리 패널(기본)

presentation이 webview(기본)이면 모달은 µGulp 대시보드 안에 AiDPix/Oxyd 스타일 유리 패널로 그려집니다:

Feature	Detail
Frame	9-slice glasspanel.png (glasspanel-ice.png in the ice-light skin)
Variants	info (turquoise header), warning, error — colored header bar per variant
Buttons	Carbon-styled actions; primary button highlighted
Overlay	Scroll the mouse wheel over the dimmed backdrop to adjust overlay brightness (8–88 %); long message bodies scroll inside the panel
Keyboard	Escape → cancel/no (or first button); Enter → primary button

구현: src/webview/WebviewModal.js, src/webview/webview-modal.css(VS Code webview와 HTTP 대시보드가 로드).

API

import { ShowModalMessage, ShowConfirmMessage } from 'gulp-mu-gulp-api';

// Single acknowledgment (default button: OK)
await ShowModalMessage({
    variant: 'warning',          // 'info' | 'warning' | 'error'
    title: 'Disk almost full',
    message: 'Less than 1 GB free on the build drive.',
    presentation: 'webview',     // optional — see below
});

// Yes/No confirmation (default style)
let answer = await ShowConfirmMessage({
    title: 'Overwrite output?',
    message: 'Existing files in dist/ will be replaced.',
});
if (answer.button !== 'yes') return;

// OK/Cancel preset
let discard = await ShowConfirmMessage({
    title: 'Discard changes?',
    message: 'Unsaved theme tweaks will be lost.',
    style: 'ok-cancel',          // default: 'yes-no'
});

두 헬퍼는 Promise<{ button: string }>을 반환합니다 — 예: 'ok', 'yes', 'no', 'cancel', 또는 ShowModalMessage({ buttons: [{ id: 'retry', label: 'Retry', primary: true }] })의 사용자 단추 id.

CLI 폴백(평범한 gulp, CI, TTY 없음): 괄호 콘솔 출력과 기본/기본 단추 — 차단 프롬프트 없음.

모달이 나타나는 곳 (presentation)

Value	Behavior
webview	In-dashboard glass panel (default)
ide	Native VS Code / Cursor modal (showInformationMessage / showWarningMessage / showErrorMessage with { modal: true })
auto	Native IDE dialog when the Extension Host is available; otherwise the webview glass panel

호출별 presentation은 호스트 기본을 덮어씁니다.

호스트 기본

Host	Setting
VS Code / Cursor	Extension setting microgulp.modalPresentation (webview | ide | auto, default webview)
Browser demo / PhpStorm JCEF	Dashboard Settings → Modal presentation (same three values)

폴백: PhpStorm과 브라우저 대시보드는 항상 webview 유리 패널을 씁니다 — 거기서 presentation: 'ide'는 webview로 매핑. 네이티브 IDE 모달을 보일 수 있는 것은 VS Code/Cursor Extension Host뿐입니다.

데모 시험

µGulp: Open Sample Project 후 대시보드는 Demo 그룹을 나열합니다:

Task	Effect
DEMO_MODAL_DIALOGS	All variants + Yes/No + OK/Cancel with presentation: 'webview'
DEMO_IDE_MODAL_DIALOGS	Same flow with presentation: 'ide' (native modals in Cursor/VS Code; webview fallback in PhpStorm / the browser)

추가 API 세부: gulp-mu-gulp-api/README.md.

µGulp ready 인증

루트 gulpfile이 µGulp 대시보드와 완전히 통합된 npm 모듈은 npm README와 프로젝트 페이지에 µGulp ready 배지를 표시할 수 있습니다.

Requirement	Detail
Gulpfile	Exported tasks carry µGulp metadata (µDisplayName, µDescription, µGroup, …)
API	Uses gulp-mu-gulp-api for logging, progress and optional dashboard features
CLI fallback	Tasks remain runnable with plain gulp / npx gulp when µGulp is not installed
Badge asset	Canonical PNG: media/microgulp-ready.png in the µGulp repo. npm README: absolute raw URL (npm rewrites relative paths to microCSS/HEAD/... even inside HTML). Example: <a href="https://microgulp.dev"><img src="https://microgulp.dev/assets/media/microgulp-ready.png" alt="µGulp ready" width="150"></a>
package.json	Optional "microgulp": { "ready": true, "certifiedSince": "<semver>" } for machine-readable discovery

인증된 모듈

npm package	Since	Notes
gulp-mu-gulp-api	0.3.11	Official task API — Log, ReportProgress, i18x console layer, dashboard forms, ShowModalMessage / ShowConfirmMessage; npm README badge since 0.3.3
gulp-mu-css (µCSS™)	2.5.15	Monorepo root gulpfile.mjs with full task metadata, i18x/gulp/ (en-US, de-DE) and LogBuildDebugReport on demo builds; npm README badge via absolute raw URL since 2.5.14
gulp-mu-ps (µPS)	1.3.5	Test/render tasks in the shared root gulpfile (TEST_MICROPS, RENDER_EXAMPLES, …)
gulp-mu-ft (µFT)	0.1.5	Test task TEST_MICROFT in the shared root gulpfile
gulp-mu-au (µAU)	0.1.6	Test task TEST_MICROAU in the shared root gulpfile

인증을 신청하려면 dev/prompts/OptimizeGulpfileForMicroGulp.md로 gulpfile을 이전하고 µGulp 또는 모듈 저장소에서 이슈나 PR을 여십시오.

버전 관리 (RELEASES.json)

이 파일은 µGulp 자체의 릴리스 형식 — 이 저장소의 유일한 진실 원천입니다. 소비자 프로젝트는 RELEASES.json이 필요 없습니다. 제품 버전은 보통 자체 설정에 두고 µI18xContext.version으로 노출합니다. 선택 versionSources: ["RELEASES.json"]은 같은 JSON 배치를 채택할 때만 도움이 됩니다.

각 릴리스 항목은 main/minor/revision, 타임스탬프, beta 플래그, 정보 텍스트 목록을 가집니다. 정보 텍스트는 i18x 컨텍스트 태그 <context="release info"/>를 갖고 String.i18xRegister()로 등록되어 i18xe 엔진이 자동 번역할 수 있습니다.

스키마(최신 릴리스가 앞 — releases[0]이 현재):

{
    "releases": [
        {
            "main": 0, "minor": 2, "revision": 0, "date": "2026-07-02 15:30", "beta": false,
            "info": [ "Release management added<context=\"release info\"/>" ]
        }
    ]
}

versionSources에 "RELEASES.json"이 있으면 엔진은 releases[0]에서 <version/>을 "main.minor.revision"으로 해석합니다(예: "0.2.0").

모듈 src/engine/ReleaseInfo.mjs가 제공합니다:

• GetVersionString() / GetFullVersionString() — "0.2.0" 또는 "0.1.4ß"(베타 빌드의 ß 접미).
• GetVersionHistoryText({ maxReleases, includeBeta }) — 콘솔용 형식 지정된 전체 기록(태스크 SHOW_VERSION_HISTORY 또는 npm run history).
• BUILD_PACKAGE는 package.json 버전과 이 README 맨 위 버전 줄을 RELEASES.json에서 자동 동기화하고 산출물 이름에 찍습니다(microgulp_V0.2.0.vsix, 베타는 _beta 접미). 새 릴리스는 RELEASES.json 맨 앞의 새 항목만 필요합니다.

프로젝트 빌드 (gulpfile.mjs)

프로젝트는 자체 gulpfile로 자신을 빌드합니다(도그푸딩: µGulp™ 대시보드, gulp CLI, 클래식 Gulp IDE 확장, 헤드리스에서 실행):

Invocation	Task	Purpose
npm test	RUN_TESTS	node:test suites in tests/ (unit + engine integration with real worker processes)
npm run theme	CREATE_THEME_DATA	Compiles every skins/<name>/<name>.µ.css via µCSS (gulp-mu-css BuildSkin) into src/webview/skins/<name>/dashboard.css (default: neon-carbon)
npm run package	BUILD_PACKAGE	Stages the extension into tmp/package/ and creates the .vsix in packages/ (also refreshed as microgulp_latest.vsix)
npm run deploy	DEPLOY_EXTENSION	Automated update cycle: build the .vsix and install it via cursor --install-extension (reload the window afterwards)
npm run build	BUILD_ALL	Full pipeline: clean → tests → theme → package
npm run history	SHOW_VERSION_HISTORY	Prints the formatted version history from RELEASES.json to the console
npm run accounts	ACCOUNTS	Read-only listing of production LICENSE_KV registrations (--status, --edition; token from CLOUDFLARE_API_TOKEN or website/.env)
npm run website	BUILD_WEBSITE	Turns README language sections into website/ (all languages selectable; / follows the browser language)
npm run website:deploy	DEPLOY_WEBSITE	Builds, tests and publishes website/ to Cloudflare Worker microgulp-web (microgulp.dev; local Wrangler login)
npm run backup	BACKUP_TO_NAS	Incremental robocopy mirror to Z:\\Projects\\microGulp (override with MICROGULP_NAS_BACKUP)
—	PUBLISH_API	Publishes gulp-mu-gulp-api to npm (runs its tests first; npm login required)
—	CLEAN	Removes tmp/ and packages/ (exclusive, write lock)

참고:

• gulp-mu-css는 C:\Projects\microCSS\gulp-mu-css의 로컬 file: 의존성으로 연결되어 있으며 — 모든 무거운 패키지처럼 — 태스크 본문 안에서만 await import()로 로드됩니다.
• BUILD_PACKAGE는 @vscode/vsce가 설치되면 진짜 .vsix를 만듭니다(npm i -D @vscode/vsce). vsce 없으면 스테이징 폴더 zip으로 떨어집니다.
• 스킨은 독립적: skins/ 아래 스킨당 한 디렉터리(예: skins/neon-carbon/, skins/ice-light/, skins/ide-dark/). 각각 <name>.µcss.mjs 매니페스트와 같은 이름의 <name>.µ.css 소스. CREATE_THEME_DATA는 모든 스킨을 찾아 빌드. neon-carbon(어둠)이 기본, ice-light는 밝은 프로스트 유리 동반자. ide-dark / ide-light는 카본 직조나 네온 맥박 없는 단순한 VS Code 풍 면. 추가/사용자 스킨은 형제 디렉터리로 둘 수 있습니다. 대시보드 스킨 선택기(Settings → Appearance)는 IDE/OS 명암 테마를 따르는 Automatic 모드를 제공합니다(ice-light / neon-carbon으로 매핑).
• webview는 생성된 기본 스킨(src/webview/skins/neon-carbon/dashboard.css)을 자동 선호. 손으로 쓴 dashboard.css는 새 체크아웃용 폴백으로 남습니다.
• 대시보드 헤더는 네온 µGulp™ 제목 옆에 노란 현미경 마크(baselogo.svg)를 µCSS data-URI 인라인으로 보여 줍니다(background-image: µ(DataUri("imgs/baselogo.svg"))). 완성 아트 자산의 유일한 진실 원천은 dev/media/final/. 빌드는 거기서 media/logo.png(확장 아이콘), media/logo_readme.png(README), src/webview/skins/<name>/imgs/baselogo.svg(대시보드), jetbrains/resources/icons/baseoutlinelogo.svg(JetBrains 도구 창 + 플러그인 목록)를 동기화합니다.

이 저장소는 로컬 개발용 demo/gulpfile.mjs도 제공합니다:

npm run demo          # headless engine smoke test
npm run demo:web      # browser dashboard (microgulp-serve --http)
npm run demo:ide      # Extension Development Host with demo/ as the workspace

VS Code/Cursor의 F5(시작 구성 "Run µGulp Extension")는 같은 데모 워크스페이스를 엽니다.

사용해 보기

설치된 확장: 명령 팔레트 → µGulp: Open Sample Project(JetBrains: Tools → µGulp: Open Sample Project). Demo와 Build 태스크(진행, 폼, 구조화 로그, 소리, 모달)가 있는 샘플 gulpfile을 ~/.microgulp/sample에 복사하고 엽니다. 그다음 µGulp: Open Dashboard. 사용자 핸드북은 Settings → Handbook(또는 µGulp: Open Handbook)에 있으며, 대시보드의 모든 언어가 나열됩니다.

핸드북 PDF: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어

라이선스

µGulp™(확장, 엔진, 대시보드, JetBrains 어댑터)는 독점 소프트웨어입니다 — LICENSE를 보십시오. 배포 바이너리는 무료로 쓸 수 있습니다. 소스 코드의 복사, 수정, 재배포는 허용되지 않습니다.

동반 npm 패키지 gulp-mu-gulp-api는 MIT 라이선스로 남아 Gulp 태스크가 제한 없이 채택할 수 있습니다.

로드맵 / 이 초안의 미결 사항

V0.5.0에서 출하됨

• [x] webview의 i18x 층: 언어 설정(automatic/en-US/de-DE/zh-CN/fr-FR/es-ES/ru-RU/ja-JP/ko-KR), 컨텍스트 태그 GUI 문자열, i18xe 서버에서 가져온 형식 정의 — 직접 i18xe 서버 연결은 후속
• [x] µ 태스크 메타데이터: .i18xRegister()가 i18xe/대시보드용 구절 등록. 번역과 자리 표시자는 대시보드 렌더 시 i18x-catalog + µI18xContext. 콘솔은 .i18xTrans() / Log()
• [x] npm의 공개 태스크 API **gulp-mu-gulp-api**(진행, 소리/음성, CLI 폴백이 있는 대화형 폼. IsMicroGulp, InstallStringExtensions)
• [x] 레거시 프롬프트 라이브러리(inquirer, gulp-prompt, prompts)를 gulpfile 편집 없이 대시보드 폼으로 리디렉트
• [x] 확장 대시보드 폼 컨트롤(radio, range, textarea, password, number, date/time, file, 다중 선택 checkbox)
• [x] 대시보드 설정(음향 제어, 음성 출력, 폼 알림, 오류 처리, 언어)
• [x] 태스크 섹터의 콘솔 렌더(ANSI 색, \r 진행 줄 덮어쓰기, 타임스탬프)
• [x] 영구 태스크 기록과 파일로 로그 리다이렉트(원시 .log + 구조화 .ndjson, history.ndjson 인덱스, 보존, 대시보드 기록 패널)
• [x] 팀/CLI 기본값용 microgulp.config.json(설정되면 PhpStorm IDE 설정 + VS Code 확장 설정이 우선)
• [x] µOrder로 대시보드 태스크 정렬(오름차순. 그룹은 하위 트리 최소)
• [x] 2단계: JetBrains 어댑터 — JCEF 도구 창 + Node 사이드카 + HTTP/SSE 대시보드 + Settings → Tools → µGulp(모든 IntelliJ 계열 IDE)
• [x] 태스크별 선택 Windows UAC 승격(µRequiresElevation, µElevationReason) — IDE는 비관리자 유지
• [x] 대시보드 로컬라이제이션 문서화: 번들 en-US / de-DE / zh-CN / fr-FR / es-ES / ru-RU / ja-JP / ko-KR. 소비자 프로젝트는 i18x/gulp만 공급
• [x] 다중 스킨 대시보드(Neon Carbon, Ice Light, IDE Dark/Light) + 전역 테마 ZIP 팩(Appearance 가져오기. 선택 소리/그래픽)
• [x] 테마별 µAU 사운드 아틀라스(default/ + 스킨 덮어쓰기, PCM 중복 제거). 카탈로그는 dev/docs/MicroGulpSoundSchema.md
• [x] 태스크 아이콘 / 실행 로그용 프로젝트 글꼴(RegisterDashboardFont, µIconFont, dashboardFonts. gulp-mu-gulp-api 0.3.12)
• [x] 태스크 단축키(µKeyBinding, 플랫폼별 코드, 충돌 배지) + IDE 전역용 µGulp: Run Task
• [x] 선언적 태스크 매개변수(µParameters, GetParameters(), 기억한 답, 가린 비밀)
• [x] 워치 / 트리거 태스크(µWatch 글롭, 디바운스, 폭주 차단기, 대시보드 토글)
• [x] 작업별 자동 닫기 덮어쓰기(µAutoClose: -1 유지, 양의 초, 생략 시 설정)
• [x] 실행 로그의 클릭 가능한 오류 위치(VS Code 편집기 탭, PhpStorm JCEF 브리지)
• [x] Windows / Linux / macOS × Node 22와 24의 CI 행렬
• [x] 대시보드 안 오프라인 i18x/gulp 사전 동기화(i18xe-sync 파서, 대상 언어 대화상자, 표준 형식, AI 번역용 <lid>.status.json)

아직 미결

• [ ] µLib(microLib)를 문서화한 뒤 µGulp의 유틸리티 층으로 채택(오늘의 i18x는 로컬 webview 부분집합)
• [ ] 직접 i18xe-server 연결: 번들 사전 대신 라이브 번역 동기화
• [ ] µLib의 GUI.mjs에 대시보드 폼용 추가 특수 컨트롤
• [ ] webview 대시보드의 시각 다듬기
• [ ] µCSS 스킨 확장: 심볼 글꼴과 스프라이트를 매니페스트에
• [ ] i18xe를 통한 음성 출력(아틀라스 샘플이 있으면 이미 WebAudio 비프를 대체)
• [x] JetBrains 플러그인: Settings → Tools → µGulp(엔진 옵션)
• [ ] JetBrains Marketplace 배포(연기 — 당분간 로컬 ZIP 설치만)
• [ ] VS Code/Cursor 확장의 마켓플레이스 공개(연기 — 당분간 GitHub Releases / packages/*_latest.*로 출하)