µGulp™ FreeRock your Gulp! µGulp™ Free - interactive Gulp dashboard for VS Code and Cursor (IDE Dark / IDE Light from the IDE theme). Installation Launch VS Code Quick Open ( Ctrl+P), paste the following command, and press enter.Copied to clipboard |
µGulp™ (microGulp)
Rock your Gulp! µGulp™, the interactive near-zero-latency task orchestrator with rich visuals, webview controls, and audio feedback. Version 2.1.0 · Proprietary License English · Deutsch · Français · Español · Русский · 日本語 · 한국어 EnglishRock your Gulp! µGulp™ adds an interactive dashboard to Gulp for VS Code, Cursor, and JetBrains IDEs. Your tasks gain dynamic display names, clear groups, icons, descriptions, and tooltips. You can see which task belongs to which project and target, whether it is running, and whether it succeeded. Forms, progress indicators, and separate live output accompany execution. The regular Gulp CLI remains available; required packages and suitable input values still apply. AI and MCP are optional. Getting started: install the extension for your IDE, open a project containing a gulpfile, and start a task in the µGulp™ dashboard. You need Node.js 22 or later and your project's required packages. Gulp is a JavaScript tool for recurring tasks; a gulpfile describes those tasks. µGulp™ adds the interface for operating them. HighlightsStatus as of 2.1.0, October 20, 2026: local testing is in progress; not yet published. Global tasks, the revised onboarding flow, and project-task presentation are implemented. Previous acceptance results remain tied to their respective versions; a successful individual test is not a full approval. The verified workflows and their limits are documented below.
Design project tasks in your preferred languageSet up project tasks configures the presentation of existing tasks in the selected project Gulpfile. Global tasks spanning projects are managed separately and are not changed by this assistant. The editing language applies to proposed display names, descriptions, tooltips, and groups. The selector uses the centrally maintained language list from the i18xe project, with language codes and native names; you can also enter other valid BCP 47 language codes. The selection is prefilled from Prepare text suggestions with IDE agent creates a limited request for missing text fields. The Gulpfile always contains English en-US source text; for a different editing language, the assistant adds the corresponding translations to Load suggestions into form displays the checked proposals. Existing metadata, translation keys, computed values, and fields edited manually in the meantime are preserved. The request expires after ten minutes and is rejected if the Gulpfile or dictionary has changed. The preview shows both files together; only explicit application with backup writes the Gulpfile and dictionary, and undo restores the previous state. Linguistic and factual review remains the user's responsibility. The eight bundled µGulp™ interface languages are separate from this. Further downloadable or installable translation packages for the µGulp™ interface are planned for version 2.2.0 and are not yet part of this assistant. For icons, enter a symbol or emoji, or select a PNG, JPEG, or WebP image up to 64 KiB. A direct preview shows your selection. The image is embedded in the Gulpfile, so it does not depend on the original file path. New SVG files and image URLs are not imported here. Existing icon metadata is preserved when applied without changes. Improve an existing Gulpfile selectivelyThe setup assistant first performs a purely static check for existing µGulp™ presentation metadata on your tasks. A display name, description, group, icon, or tooltip is enough to indicate that a task's presentation has already been adapted. This is not a complete quality assessment of the Gulpfile. Not every task needs every one of these details. If all detected tasks are already adapted, no automatic optimization prompt appears. For partially adapted Gulpfiles, the dialog proposes only tasks without such details. You can first add names, descriptions, groups, icons, and tooltips, review the change preview, and explicitly apply it with backup. Undo remains available. You can access further AI recipes afterwards or by deliberately skipping this step. Computed or imported metadata cannot always be assessed unambiguously. In that case, the assistant reports an unknown optimization status and does not change these values automatically. Keyboard shortcuts are only an optional tip; their absence is not treated as a need for optimization. A missing global-task assignment is not a deficiency either. Further AI recipes and keyboard shortcuts are initially unselected in the second step. Global tasks for selected projectsGlobal tasks let you avoid finding and starting the same task separately in every project. A shared ID connects the appropriate implementation in your projects: NASBU can back up different folders in each project, for example. The Web Console shows the participating projects with titles and icons; you explicitly choose which ones to start. A global definition consists of a stable ID and a descriptive title. The executable implementation remains in each project's Gulpfile. This does not distribute shared source code or automatically copy tasks into other projects. Different projects can implement the same ID to suit their own requirements. Add µGlobalTask = { id: "NASBU", title: "NAS-Sicherung" } to the exported task. IDs start with an uppercase letter and contain no more than 64 uppercase letters, digits, underscores, or hyphens. A project may offer an ID exactly once. Marked tasks appear in the project dashboard in their own Global tasks group; this replaces any existing µGroup for these tasks. Open the Web Console and expand Global tasks. Refresh the list and select the shared task. Under Configure project, save the values from µParameters once for that project. They are stored locally in .microgulp/global-tasks.json. A changed parameter definition requires configuration again. Passwords and values marked remember: false are not saved here; these tasks still require interactive operation in the project. Under Define a global task, you can set the ID and title centrally. The list also detects IDs from connected projects. A central title makes the display consistent; it does not create an executable implementation. Definitions are stored in the user directory under .microgulp/global-tasks.json. Select projects by title and icon. If the same project has multiple IDE windows, select exactly one session. Preview selection shows only these projects and their saved values. Only Start selected tasks hands execution over to the respective IDE. Closed projects or IDEs are not opened automatically. The batch start uses the saved parameters without showing input forms again. If a task nevertheless requests a µGulp dialog, that run fails with global-task-dialog-required. Tasks requiring elevated Windows privileges and persistent tasks are not started globally. Gulp code remains local program code; external programs with their own dialogs do not thereby become unattended tasks. Previews are short-lived and can only be used once. Changes to the Gulpfile, task definition, saved parameters, or Project Controls invalidate them. If the IDE session ends or changes, you must select and review again. All selected sessions are checked before the first task starts. A batch start is not a transaction: if a connection fails after the first start, earlier projects may already be running. The result shows projects that started, failed, or have not yet started. There is no automatic retry and no automatic undo of executed tasks. Progress, logs, and stopping are available in the respective project dashboard. Start a task in another projectA task in project A can use RunGlobalTask from gulp-mu-gulp-api to start an implementation marked with µGlobalTask in project B and wait for it to finish. Pass the exact project ID and global task ID. The target parameters must first be configured in project B's dashboard. Project B needs an active connection with its µGulp dashboard open. If multiple sessions are open for the target project, also specify the sessionId of the desired session. Closed projects or IDEs are not opened automatically. The response contains the status, run ID, and duration. taskResult is present only if the target task called ReportTaskResult. The call starts the target task through its connected IDE session; no visible Web Console window is opened. Self-calls and recursive project chains are rejected. The timeout ranges from 1 to 300 seconds; the default is 120 seconds. The target task may already have started when a timeout occurs. Global calls require an active, trusted IDE session with the µGulp dashboard open and an edition with IDE API access. The project overview and existing simple task controls remain available. Independent execution of closed projects in the Background Host, global hardware buttons, and global MCP tools are not part of this 2.1.0 scope. Editions and featuresThree editions, all currently free (0 € / $0 per month and per year). “Free” here is the listing price, not an open-source license - the source repository stays private.
Do not install the registered VS Code/Cursor edition and µGulp™ Free side by side - they share the same command IDs. Register the full VS Code/Cursor edition before it will run tasks, or uninstall it and use µGulp™ Free.
All editions are currently free (€0 / $0 per month and per year). The highlight list describes the full product; edition limits appear in the table. Free follows the IDE/OS theme with IDE Dark / IDE Light (no Appearance picker) and omits theme packs, diagnostics, elevation, hardware integrations and IDE actions. The local Web Console remains available in Free: project overview, status and host administration are usable; advanced actions (Open/Focus Project, Start Application, IDE actions, preferred IDE) are reserved for the other editions. The registered VS Code / Cursor edition re-checks the local account against New in 2.0.0The setup assistant adds AI recipes to existing projects and shows every file change before applying it. Optional MCP access to your IDE agent and support for translation and handbook maintenance are also new. Everyday use stays simple: open a project, choose a task, run it. A general AI workflow generator, semantic optimization of arbitrary tasks, and evolutionary self-optimization are unimplemented ideas with no promised scope or date. Available since 1.1.0Optional form information appears before input fields. Tasks can explicitly enable cancellation and persistence of eligible choices. Form contract and examples · 1.1.0 release notes Setup assistant and AI recipesSet up project tasks opens the dashboard assistant for an existing gulpfile. It statically analyzes ESM/CommonJS, offers appropriate configuration fields, and shows all changes before applying them. The nine AI recipes cover display names and descriptions, free-form and project-based task groups, shortcuts, NAS backup, microCSS, initial setup, and GitHub and npm preparation.
Required dependencies appear in the preview and are subsequently installed with Prepare initial setup and publicationThe Initial setup, GitHub publication, and npm publication AI recipes add preparation tasks to your existing gulpfile. Each AI recipe has a form for the project name and settings. Tasks show relevant checks and commands; they do not install dependencies, push, or publish. Applying changes in the assistant is not authorization to publish either.
Automatic version increases support stable versions such as Neither preview nor task startup queries the registry. The npm plan therefore requires a registry check, tests, build, package content inspection, and sign-in before actual publication. A local version increase does not confirm that the version is available in the registry. A published package cannot be published again with the same version. npm publication · npm versioning · GitHub release draft Organize tasks by projectEach of the three AI recipes creates four preparation tasks under Project name/Info, Project name/Build, Project name/Tools, and Project name/Maintenance. Info holds inventory and result checks, Build covers build preparation, Tools contains helper and verification steps, and Maintenance covers setup, versioning, and release preparation. Task names default to Project-based task groups ( MCP provides the same forms and changes through Setup through MCPThe separate MCP adapter provides the same workflow through Node.js 22 or later and an active session of the updated host are required. After installing the separate SDK dependencies ( Review text suggestions and reconnect MCP after an updateOpen Set up project tasks and select the Gulpfile, the desired tasks, and the editing language. Prepare the text request only once the IDE agent is connected to the µGulp™ MCP server. Copy the displayed request into that chat. Leave the form open; the request is valid for ten minutes and belongs to the current project engine. After the agent responds, click Load suggestions into form in the same form. Review the added names, descriptions, tooltips, and groups. The review-required response only means that a proposal exists; it confirms neither its quality nor a change to the Gulpfile. You can correct or omit unsuitable or uninformative text. The agent must not invent unknown functionality from a task name. Then review the change preview and apply it with backup if appropriate. Undo this change restores the backed-up state as long as no subsequent changes have been made. A request prepared directly in chat is not automatically linked to an already open form. For the form workflow, therefore, start with the request shown there. Prepare a new request after expiration, a language change, or an engine restart. An extension update may change the installation directory. Check the path to microgulp-mcp.mjs in the MCP configuration and install the separate SDK dependencies in the new src/mcp directory with npm ci --omit=dev --ignore-scripts. An enabled server is not proof of a working connection. For Connection closed, check the server log; if @modelcontextprotocol/sdk is missing, these dependencies are absent from the directory being used. Reconnect the MCP server and open a new agent chat. Use list_projects to check the current session. Text suggestions require prepare_setup_text, get_setup_text, and submit_setup_text to be available. If list_projects returns a project without a session, open its µGulp™ dashboard. Both a reachable MCP connection and an active project engine are required. Graphical MCP app in Cursor
Without After restarting Cursor, the host, or MCP, call Connect MCP in Cursor and IntelliJMCP and skills are optional. Everyday use still means opening a project, selecting a task, and running it. The following steps require the project to be open in the updated µGulp™ host. Use the actual installation directory: in Cursor the adapter is under This configuration example applies to both clients. Replace the absolute example paths with local paths;
First verification request: “Call the Skills with your existing agentQuery the versioned library with Example translation profile; all three JSON files must already exist in the project:
A simple request is: “Use profile texte-de with the existing agent, submit the result through MCP, and show me the preview. Stop before applying. No direct file changes.” Apply and undo are subsequently requested explicitly. Prepare again after Handbook maintenance with evidence-backed previewA profile with The workflow through Example customer handbookThe source file may be named Place this entry under its own name in Update existing skill profilesProfiles with skill version 1.0.0 remain executable for translation and handbook maintenance. The profile file and hash are not automatically rewritten. Without sourceLanguage, old translation profiles retain an undetermined source language (und); the agent infers it from the supplied text. Old handbook profiles still use de-DE when no language is specified. Explicit language settings take precedence. New customer profiles use 1.1.0 with deliberately chosen source file and language; project-specific editorial rules belong only in the profile. For a permanent migration, back up the profile, check version and languages, and prepare a new assignment. Unknown versions or invalid individual profiles appear as non-executable without blocking valid neighboring profiles. An invalid profile file as a whole is still rejected. Library pins and integrity values are not automatically renewed. Preview, placeholder protection, backup, undo, and the automatic DOCX application block also apply to legacy profiles. Restore the dashboard connection in IntelliJIf the project engine ends in IntelliJ, the open µGulp™ tool window detects it and offers Reconnect dashboard. Hiding and showing the tool window restarts an engine detected as stopped. An engine still running is not restarted; tasks are not repeated. A startup error stays visible with a retry option, without an automatic retry loop. Startup without a readiness message is aborted after at most 120 seconds. Check the Node path and project settings, then choose Reconnect dashboard. After reconnecting, call list_projects again and select the new session. Do not reuse old proposal and undo IDs in a new session; inspect existing backups before requesting new changes. A green MCP server status alone does not prove an active dashboard session. Verified workflows and approvalsThe configurable customer profiles with skill version 1.1.0 were tested through MCP in installed Cursor and IntelliJ clients by October 19, 2026: en-GB to fr-CA, translation preview preserving a placeholder, application, and byte-exact undo. The handbook used a freely chosen DOCX source and report language; automatic application was rejected with handbook-report-requires-editorial-work and its DOCX hash remained unchanged. Compatibility of existing 1.0.0 profiles was additionally confirmed afterward in IntelliJ. These checks demonstrate the controlled workflow, not the linguistic quality of arbitrary agent results. On October 19, 2026, IntelliJ reconnection after a stopped project engine was tested through Reconnect dashboard: the new session was reachable over MCP, and subsequent legacy-profile checks passed. Translation changes were applied and undone byte for byte; the server rejected automatic handbook application and the DOCX stayed unchanged. This demonstrates the tested reconnection case, not restoration of arbitrary running tasks or old proposal IDs. The final local Windows run with Node.js 22 passed 1115 tests, with no failures and four explicitly skipped platform/device cases. Another 31 MCP/website tests passed. Updated VS Code, Cursor Internal, and Free packages were installed and checked with a successful dashboard task. JetBrains Plugin Verifier confirms compatibility with tested platform builds 242, 261, and 262; the two reported deprecated API calls have been removed. The corrected JetBrains package was installed and tested locally on Windows in IntelliJ IDEA 2026.2.2: confirming a prefilled file path, canceling file selection, opening a log file, complete initial dashboard rendering, hiding and reopening, maximizing and restoring, and resizing the tool window. Moving between monitors with different DPI scaling was not tested. Earlier native MCP acceptance results remain tied to their respective package versions. These results do not replace a fresh cross-platform CI run or outstanding physical hardware tests. From October 17 to 19, 2026, locally installed 2.0.0 packages were tested on Windows with the real Cursor agent and Codex in IntelliJ AI chat: translation preview, apply, read-only file verification, and byte-exact undo; also evidence-backed handbook preview, rejected automatic DOCX application, and unchanged DOCX hash. The graphical MCP app was tested in Cursor; this does not validate a graphical app in IntelliJ. Other agents and operating systems are not covered. An initial Cursor run reported Startup configuration, tool workflow, and limits Snapshot
Click a task → an available warm worker handles the run without reimporting the gulpfile. Save the gulpfile → the task list refreshes automatically. Run multiple tasks in parallel; each gets its own dashboard section with a neon progress bar when the task calls Keep using the Gulp CLIAdditional task metadata does not change CLI addressing. Existing builds can continue under the classic Behavior without a dashboard
Observe version requirements The classic Gulp CLI ignores additional metadata. This is not a blanket compatibility promise for arbitrary host, Gulp, or API versions: new API calls may require newer packages, and IDE actions need appropriate host capabilities. Observe version requirements and check existing calls after an update. In practice, a colleague can continue running existing build tasks with InstallationµGulp™ is available now. Install from the public listings:
The source repository stays private. Do not install the registered VS Code/Cursor edition and µGulp™ Free side by side - they share the same command IDs. Afterwards run JetBrains IDEsThe JetBrains plugin is a platform plugin (
The JetBrains Marketplace listing (plugin id 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 Marketplace variant. Install from the JetBrains Marketplace (Settings → Plugins → Marketplace, search MicroGulp) 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 Building and checking the packages
Known JetBrains / JCEF log noise (harmless)The first time the µGulp tool window embeds the dashboard, the IDE log may show an error like:
That comes from JetBrains' own JCEF stack ( The same dashboard also runs in any plain browser: Offline packagesThese files exist only in a local checkout of the source repository. They are not the public installation path. Local VSIX install:
JetBrains zips from a local build:
Install a local zip via Settings → Plugins → ⚙ → Install Plugin from Disk… Configuration file
|
| Key | Type | Default | Meaning |
|---|---|---|---|
gulpfile |
string | - | Single gulpfile relative to the project root; must stay inside 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. |
project |
object | - | Optional. Project identity for the task list: title, description, logo (SVG/PNG/WebP, relative to the project root). Without values, no extra header. |
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. Changes to project (title, description, logo) are picked up without an IDE restart when gulpfile watch is on. After editing other IDE settings or the file, reopen the µGulp tool window (respawns the sidecar) or restart microgulp-serve.
Project identity (project)
Optional compact header above the task list so that, with several IDE windows open, it is immediately clear which workspace the tasks belong to:
{
"project": {
"title": "ESP][",
"description": "Apple II emulator for ESP32-S3",
"logo": "./assets/esp2.svg"
}
}
- All three fields are optional; missing metadata leaves the previous layout unchanged.
logo: paths relative to the project root; formats SVG, PNG, WebP. Missing or invalid files are ignored (header without logo).- Tooltip on the header: title, description (if set) and absolute workspace path.
- Project identity appears in the dashboard task list and the Web Console. Stream Deck shows the project logo and title on the group browser's Root key, preserving the logo's aspect ratio and keeping the title in a separate band; an unusable logo gets a fallback. Logitech MX uses the project image supplied by the connected host for workspace selection and the µGulp™ key, falling back to the brand image. Full device acceptance testing remains outstanding; no project-logo display is promised for Flexbar.
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/engineandsrc/workerknow 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 sidecarnpm run serve(src/host/microgulp-serve.mjs, NDJSON on stdio) is already in place. - Task preloading. The
TaskWorkerPoolkeeps 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 viaawait 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™ discovers gulpfiles through a single path or a regex pattern that searches the entire workspace. Selection belongs to the project and is identical in VS Code, Cursor, JetBrains and the CLI:
- Explicit IDE or CLI override: VS Code/Cursor setting, JetBrains Settings → Tools → µGulp, or
microgulp-serve --gulpfile/--gulpfile-pattern. An empty field is not an override. microgulp.config.jsonat the project root (gulpfileorgulpfilePattern).- Default:
gulpfile.mjsat the project root, otherwise discovery with(^|/)gulpfile\.(m|c)?js$.
At each level a pattern takes precedence over a single path. A path outside the project root is rejected; a missing file falls back to the next level with a warning.
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$findsgulpfile.mjs/.js/.cjsat the root and in every subfolder.microgulp.gulpfilePath- explicit single path; empty by default so thatmicrogulp.config.jsonapplies.
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 |
A group header also reports what it hides: it takes over the amber attention mark when a task inside is flagged with µAttention, and dims when every task inside is disabled via µEnabled. Both work while the group is collapsed.
Group start state (µGroups)
Long task lists read better with groups closed. The optional module-level export µGroups decides how the list looks on first render - globally and per group. Everything stays expanded without it, every group remains collapsible by hand, and a manual toggle outranks the declaration for the rest of the session.
// Terse: every group starts collapsed
export const µGroups = 'collapsed';
// Full: global default plus per-group exceptions
export const µGroups = {
collapsed: 'all', // 'all' | 'none' (or true / false)
groups: {
'Demo': 'open', // starts expanded
'Build/Production': true, // starts collapsed
},
};
Group keys are µGroup paths and may include the <context="…"/> tag; matching ignores case and spacing. The most specific declared ancestor wins, then the global default - so 'Build' also covers 'Build/Production' unless that child is declared separately. Keys are identifiers, not user-visible text, so they are not registered with .i18xRegister().
µ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, file, folder |
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, accept |
numeric / textarea details; accept on file is .zip,.json |
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.
Large option lists (select / radio / checkbox) are supported: the host keeps up to 5000 entries per field by default (override MICROGULP_MAX_SELECT_OPTIONS; 0 = unlimited). If a list is truncated, the dashboard shows a warning - silent clipping is gone. Selects with 24+ options get a filter field. Ad-hoc RequestForm from gulp-mu-gulp-api has no host cap on the live payload; the same field types and filter apply there.
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().
Draw attention to a task (µAttention)
A task can pulse in the left column when it needs a look (missing install, version drift, stale output):
DEPLOY.µAttention = () => installed !== current;
DEPLOY.µAttentionTooltip = 'Cursor has V<installed/>; workspace is V<version/>.<context="µAttentionTooltip"/>'.i18xRegister();
DEPLOY.µInstalledVersion = () => installed || '-';
| Property | Meaning |
|---|---|
µAttention |
true or a function returning true highlights the row (amber pulse + pip). Default off. Same factory pattern as µEnabled. |
µAttentionTooltip |
Optional extra tooltip line shown first while highlighted. Use .i18xRegister(). |
µInstalledVersion |
Optional string or factory for the <installed/> placeholder |
µAttentionWatch |
Optional triggers that only re-evaluate the factory: a path, path array, or { files, intervalMs }. ~/… is allowed. Never starts the task. |
Call NotifyTasksChanged() after the state that drives µAttention changes. Optional µAttentionWatch re-evaluates the factory without starting the task - workspace files, ~/… paths, or an intervalMs poll (for folders outside the project such as Cursor's extension directory). Unlike µWatch, a hit never runs the task.
INSTALL.µAttention = () => installed !== current;
INSTALL.µAttentionWatch = { files: ['~/.cursor/extensions'], intervalMs: 8000 };
PUBLISH.µAttentionWatch = ['website/en/index.html', 'RELEASES.json'];
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.µShortDisplayName = 'CSS, Build Styles<context="µShortDisplayName"/>'.i18xRegister(); // Optionaler Kurztext für Stream Deck und Logitech MX
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();
µShortDisplayName is an optional i18x phrase for compact hardware labels. It changes neither the dashboard display name nor the task ID. If needed, it can contain “short text, original text”, such as CSS, Build Styles. The µShortDisplayName context tag belongs only in the i18x source phrase; the host removes it before output. No tags appear on the device.
Context tags, mandatory formats, and the marketplace language plan: dev/docs/MicroGulpI18xProfile.md.
Task presentation and control from the gulpfile
µGulp™ shows whether each task is inactive, disabled, starting, running, waiting for input, stopping, completed successfully or failed. The state border remains visible with custom icons. Pending input adds a violet dialog icon; answer in the dashboard.
38 SVG icons provide semantic presentation. µTaskKind and µPresentation describe the task, such as build, test, copy or publish. Icons follow the theme, can be replaced by a theme and support reduced motion. Run animations indicate activity; on failure, the original design becomes charred. Existing µIcon and µIconFont settings are preserved.
Mark a long-running service with µExecutionType = 'persistent' so it can be stopped again. This is independent of µWatch, which reruns a task after file changes, and µAttention, which marks required work. µAttentionWatch can reevaluate that hint after file changes or at an interval without executing the task.
A Gulp task can also control the task overview:
import { SetGroupState, RevealTask, SetTaskEmphasis } from 'gulp-mu-gulp-api';
SetGroupState('Build', 'open');
RevealTask('PUBLISH_NPM', { expand: true, scroll: true, highlight: 'attention' });
SetTaskEmphasis('PUBLISH_NPM', null);
µGroups defines the initial state; later group changes apply to the session. Highlighting and execution state remain independent: a running task can also require attention. The dashboard and hardware receive the same task state. Opening a dashboard group does not start its tasks.
IDE actions from tasks
Gulp tasks import Ide from gulp-mu-gulp-api. The implemented 1.0.0 scope comprises eight functions:
| Function | Purpose |
|---|---|
Ide.Capabilities() |
Query host family, edition, supported operations and semantic actions; available even when executing functions are locked |
Ide.Projects() |
Query known projects, live sessions and configured application choices |
Ide.Action(id) |
Execute a semantic action in the current IDE host |
Ide.OpenProject(request) |
Open a known project in the selected installation or focus its exact session |
Ide.StartApplication(applicationId) |
Start a known or explicitly configured local application |
Ide.Execute({ vscode, jetbrains, args }) |
Execute the native command specified for the current host family |
Ide.Vscode.ExecuteCommand(commandId, ...args) |
Execute an allowed VS Code/Cursor command |
Ide.JetBrains.ExecuteAction(actionId) |
Execute an allowed JetBrains action |
The shared Ide.Action catalog contains open-settings, save-all, open-terminal, open-problems, find-in-project, quick-open, command-palette, next-editor, previous-editor, run and debug. Run/Debug use the current native configuration. Availability depends on the IDE, installed plugins and allowed commands; the catalog does not guarantee identical capabilities across JetBrains products.
Ide.OpenProject takes projectId from Ide.Projects().result.projects and, for example, applicationId from the returned application choices. An exact session requires both sessionId and connectionId. Stale targets are rejected rather than replaced with another session.
µHost marks the required IDE family; µIdeApi = true marks tasks that need this interface. The engine checks edition, registration and allowed commands. In µGulp™ Free, Ide.Capabilities() remains available as a query; the other seven functions are locked, including Ide.Projects(). The readable Web Console project overview remains available independently.
Calls return a Promise with { ok, result } or { ok: false, code, message }. Without µGulp™ IPC, for example in the plain gulp CLI, all eight return unsupported-host; they do not launch an IDE. Missing edition or registration permission returns unsupported-edition or unsupported-registration. A gulpfile can provide its own fallback for CLI and CI.
This API scope describes the repository implementation, not availability in an already published npm version. Ide.OpenUrl is planned only and unavailable.
Hardware integrations
Control tasks through Elgato Stream Deck and Stream Deck Mobile, Logitech MX Creative Console and Actions Ring, and ENIAC Flexbar. Hardware features are included in all versions except µGulp™ Free. There is no Free edition for JetBrains.
µGulp™ does more than place a static icon on a key. Live Animated Task States means presentation follows the actual execution state from the same engine as the dashboard (inactive → starting → running → finished or failed, plus disabled, waiting-for-input, stopping). Animation runs during start/run/stop/input; success and failure are briefly visible (failure includes Burn→Charred). µWatch remains a separate on/off overlay; session schedules can add a countdown or n/m to the key. (Actions Ring: titles only, SDK without LCD animation.) Contract and state list: TaskPresentationAndHardware.md.
Enable the workspace connection in the dashboard under Settings → Hardware integrations. The appropriate device plugin connects keys to that project's tasks. Running services can be stopped; input requests are answered in the dashboard.
Context-aware controller surfaces
µGulp™ uses a shared active project context for Visual Studio Code, Cursor and JetBrains. Stream Deck restores the last view per workspace and device. Logitech retains its existing dynamic workspace selection; its folder is process-wide. Flexbar does not automatically follow the IDE project.
The active project is shared; Stream Deck views are stored per device. When another application is in the foreground, µGulp™ returns a browser profile it opened to Stream Deck. Which default or Smart Profile appears next depends on Elgato and the user's configuration; automatic Smart Profile switching is not guaranteed.
Example:
Cursor: microGulp
MX -> Build
Stream Deck -> Release
Alt-Tab
JetBrains: BlueShift
MX -> Build
Stream Deck -> Test
Alt-Tab
VS Code: ESP][
MX -> Upload
Stream Deck -> Monitor
Returning to an IDE window restores that workspace's previous Stream Deck view. Device views are stored separately; physical acceptance with multiple Stream Decks is still pending.
If a group disappears after a gulpfile change, restoration falls back to the nearest valid parent or the project root. Follow active IDE project is on by default. Manual workspace selection on the Logitech keypad takes precedence. Technical limits: Follow the active IDE project.
Elgato Stream Deck and Stream Deck Mobile
Follow and profiles: With Follow active IDE project enabled, µGulp™ adopts the focused IDE project when its hardware connection is available and may open its bundled browser profile. If the browser is already visible, only project content changes. Leaving the IDE context returns a profile opened by µGulp™. Elgato Smart Profiles can additionally be configured in Stream Deck; µGulp™ does not guarantee their activation. Details and troubleshooting: Stream Deck.
Group browser: Open µGulp Group on another profile (e.g. Default) opens the browser with dynamic groups and tasks. This action opens the configured start group. Follow and a µGulp Group Slot key used as an entry point instead restore the active workspace's saved view; a new session without a saved view starts at the project root. Paging, Back and Root follow the navigation grid. The Root key shows the project logo with its aspect ratio preserved and the title in a separate band; an unusable logo gets a fallback. Back at the project root exits the browser. Stream Deck Mobile selects the template by grid size (including 3×2 and 5×3).
Fixed single-task assignment: you can still drag µGulp Task onto a key and select the workspace and task. Names, animated execution states and icons come from the connected workspace. Stream Deck Mobile uses the same integration.
Technical details and template list: Stream Deck, device group navigation contract.
Logitech individual tasks or an app profile
Logitech offers two setup approaches:
- Assign tasks individually: use Start a Single µGulp Task to bind a workspace and task permanently to a key. This applies to individual keypad keys and Actions Ring (titles only, SDK without LCD animation). The keypad folder shows icons and execution states.
- Create an app profile in Options+, for example for Cursor: its configured key layout becomes active automatically when the app gains focus. On the keypad, General µGulp Functions opens the matching workspace's tasks with icons and live execution indicators. Within the IDE, the µGulp™ plugin follows the focused workspace; manual workspace selection remains until it is released or the connection is lost.
Options+ therefore selects the app's key layout, while µGulp™ selects the workspace. Configure the profile once in Options+. Switching apps may close the dynamic folder; press the µGulp™ key to reopen it. Actions Ring uses fixed single-task assignments; the dynamic list with task icons belongs to the keypad.
Logitech MX uses the project image supplied by the connected host for workspace selection and the µGulp™ key, falling back to the brand image. Full device acceptance testing remains outstanding. Programmatic opening of the Dynamic Folder and independent navigation on multiple physical MX devices are not guaranteed; SDK questions remain open. Existing Logitech support remains limited and experimental.
ENIAC Flexbar
The Flexbar plugin connects actions configured in FlexDesigner to µGulp™ tasks and their execution states (the same state semantics as Stream Deck). Testing on physical Flexbar hardware is still pending.
Technical setup and plugin builds: Stream Deck, Logitech, Flexbar.
Task scheduler (session)
Session schedules decide only when a task starts; execution remains the normal StartTask path (dashboard sector, logs and hardware states are unchanged).
| Mode | Declaration | Summary |
|---|---|---|
| Timer | µSchedule = { after: '10s' } |
once after the duration |
| Interval | { every: '10s' } |
repeats; nextRun after each run |
| Repetition | { every: '5s', repeat: 5 } |
completed after n runs |
| Cron | { cron: '*/1 * * * *' } |
5 fields, host local time (croner) |
Imperative API: ScheduleTask, SetScheduleEnabled, CancelSchedule, RunScheduleNow (gulp-mu-gulp-api). Dashboard: countdown from nextRun, Enable/Disable/Cancel/Run now. While µWatch is armed or the task is running, a scheduled start is skipped (schedule-skipped). Hardware keys can show a countdown or n/m overlay. Details and demos A-G: TaskScheduler.md.
Controllers gamepads and joysticks
Gamepads, joysticks and other compatible input devices can serve as freely configurable workflow controllers. Enable support under Settings → Controllers; configuration provides profiles, button and axis learning, dead zones, sensitivity and live diagnostics. Mappings can start or stop tasks and control the task overview.
On Windows x64, input detection also works without dashboard focus. It requires an installed Node.js version 22 or newer. Native controller components are not yet included for other desktop platforms; supported browsers provide the Gamepad API as a fallback.
The 3Dconnexion SpaceMouse Wireless has a device-measured profile with six axes and two buttons. Configure other devices through calibration and custom mappings. If a controller supports vibration, optional feedback can signal task start, success or failure. Its scope and effect depend on the device.
Setup, device profiles and diagnostics: controller documentation.
AI-assisted gulpfile migration
To migrate an existing large gulpfile (console output, task metadata, i18x/gulp dictionaries, optional µKeyBinding / µParameters / µWatch / µAutoClose, plus optional project identity in microgulp.config.json) use the maintained prompt in the repository:
| File | Purpose |
|---|---|
dev/prompts/OptimizeGulpfileForMicroGulp.md |
Copy-paste prompt for Cursor, Claude, ChatGPT, … (first migration) |
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json |
Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version) |
dev/prompts/EnhanceExistingMicroGulpProject.md |
Check an existing µGulp™ project for optional newer features (no blind activation) |
The migration prompt now also covers µTaskKind, µPresentation, µExecutionType, µAttentionWatch, waiting for input and a sensible project identity (title / short description / existing logo; merge config only). Existing µIcon glyphs and µIconFont mappings are preserved. The core manages execution states; persistent services, file triggers and attention remain separate. Hardware integrations are enabled per workspace and included in all versions except µGulp™ Free; testing on physical Flexbar hardware is pending. Before migrating, compare required product and API versions with the current project state.
The prompt also requires i18x-formatted values: int for counters, floatFix1/floatFix2 for decimals, byteSize for bytes, progressDuration for milliseconds and date/time formats. FormatValue() is available for structured output. Project dictionaries are updated together with their matching <format> definitions; existing translations are preserved. The custom engine's provisional limitations are respected.
For grouping and the task tree, it covers µGroup, µOrder, µGroups, SetGroupState, RevealTask and SetTaskEmphasis. Hardware guidance explains the Stream Deck group browser (entry key and dynamic slot profiles), fixed Logitech tasks including Actions Ring, and Options+ app profiles with workspace selection by µGulp™.
Workflow
- Copy the parameter example into the project root as
microgulp-optimize.params.jsonand fill inprojectRoot,gulpfilePath,supportedLanguages(such asen-US,de-DE,zh-CN),gulpMuGulpApiVersion(local reference^0.6.0; check the installed/published version),microGulpMinVersion(1.0.0), andgithubRepoUrl/githubRef(default:https://github.com/mamekudz/microGulp, a verified ref such asmain). - Open the prompt markdown, replace the
{{PLACEHOLDER}}table with your values (or attach the params file and gulpfile in Cursor). - 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. - Verify with
node --check gulpfile.mjs, test tasks in the µGulp dashboard (including any new shortcuts while the dashboard has focus), then commitgulpfile.mjs,i18x/gulp/*.json, andpackage.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) |
The Scheduler demos group (A-G) demonstrates session schedules (µSchedule): a one-shot timer, interval, repetition, Cron, overlap skipping, scheduled failure and Watch+Schedule. All demo schedules start disabled (autoStart: false); arm them individually using their icon buttons. Details and API: dev/docs/TaskScheduler.md.
Further API details: gulp-mu-gulp-api/README.md.
µGulp™ Ready
A project intentionally provides at least one useful µGulp-specific interaction or output, documents a normal Gulp/CLI path, and verifies both paths itself. Ordinary Gulp compatibility or cosmetic metadata alone is not enough. The badge is free to use under the published rules; no application or official certification is involved.
Requirements, self-certification and badge usage.
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 (taskSHOW_VERSION_HISTORYornpm run history).BUILD_PACKAGEsyncs thepackage.jsonversion and the version line at the top of this README fromRELEASES.jsonautomatically and stamps it into the artifact name (microgulp_V0.2.0.vsix, betas with a_betasuffix). A new release only needs a new entry at the top ofRELEASES.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 deploy:developer |
DEPLOY_DEVELOPER |
Rebuild the unpublished Developer edition (microgulp-internal), install it into Cursor, highlight when the installed version differs, then offer Reload Window |
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-cssis wired in as a localfile:dependency onC:\Projects\microCSS\gulp-mu-cssand - like every heavy package - is only loaded inside the task body viaawait import().BUILD_PACKAGEproduces a real.vsixonce@vscode/vsceis 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.mjsmanifest and a same-named<name>.µ.csssource.CREATE_THEME_DATAdiscovers 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-writtendashboard.cssremains 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 isdev/media/final/; the build syncsmedia/logo.png(extension icon),media/logo_readme.png(README),src/webview/skins/<name>/imgs/baselogo.svg(dashboard) andjetbrains/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). This copies and opens a sample gulpfile with demo and build tasks (progress, forms, structured logs, sound, modals, plus countdown, custom icons, failure presentation, persistent service and Attention/Reset) under ~/.microgulp/sample. Then use µGulp: Open Dashboard. The user handbook is under Settings → Handbook (or µGulp: Open Handbook), where all language versions are available.
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
Already implemented
[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 viai18x-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, folder, multi-select checkbox)
[x] Dashboard settings (acoustic control, speech output, form reminder, error handling, language)
[x] Console rendering in task sectors (ANSI colors,
\rprogress-line overwrite, timestamps)[x] Persistent task history & log redirection to files (raw
.log+ structured.ndjson,history.ndjsonindex, retention, dashboard history panel)[x]
microgulp.config.jsonfor 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/gulponly[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 indev/docs/MicroGulpSoundSchema.md[x] Project identity (
project.title/description/logoinmicrogulp.config.json; compact header in the task list)[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 Taskfor IDE-global keybindings[x] Declarative task parameters (
µParameters,GetParameters(), remembered answers, redacted secrets)[x] Watch / trigger tasks (
µWatchglobs, debounce, runaway breaker, dashboard toggle)[x] Per-task auto-close override (
µAutoClose:-1keep open, positive seconds, omitted uses Settings)[x] Attention highlight (
µAttentionpulse + pip; optionalµAttentionTooltip/µInstalledVersion)[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/gulpdictionary sync in the dashboard (i18xe-sync parser, target-language dialog, standard formats,<lid>.status.jsonfor AI translation)[x] Consistent task states, 38 semantic icons, input indication, theme fallback and reduced motion
[x] Task tree and highlighting through
SetGroupState,RevealTaskandSetTaskEmphasis[x] Eight IDE API functions and visible host/availability indicators
[x] Web Console, KnownProjectRegistry / Project Center, Open/Focus Project and shared Background Host
[x] Stream Deck: Follow, last view per workspace and device, and project logos on the Root key
[x] Stream Deck/Mobile, Logitech and Flexbar integration; Logitech with single-task assignments and a dynamic keypad folder
[x] Controller profiles with calibration and diagnostics; desktop input on Windows x64 and a SpaceMouse Wireless profile
Still open
[ ]
Ide.OpenUrland IDE-less task execution through the Background Host: planned, outside the implemented 1.0.0 scope[ ] Logitech MX: physical acceptance including the project image, plus open SDK questions about Dynamic Folder and multiple-device operation
[ ] Stream Deck: physical multiple-device acceptance and interaction with Elgato Smart Profiles
[ ] Flexbar: test on physical hardware
[ ] Native controller components for Linux and macOS
[ ] 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'sGUI.mjswith 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)
[x] JetBrains Marketplace listing (plugin 34255; registry availability is not a verified fresh install in every IDE)
[x] VS Code/Cursor listings on Microsoft Marketplace and Open VSX (registered and Free)
Web Console and Project Center
The local Web Console brings known and connected projects together in the Project Center. It embeds the existing dashboard with tasks, Project Controls, parameters, history and live events; it does not create a second TaskEngine. Open it through µGulp: Open Web Console in VS Code/Cursor, Open Web Console in the JetBrains tool window, or npm run console -- open in the developer checkout. The Console uses local HTTP/SSE without a browser plugin and listens only on 127.0.0.1; it is not a LAN or remote-access service.
Known projects and sessions
The KnownProjectRegistry stores project path, ProjectId, title, description, logo, preferred IDE and last-seen time in ~/.microgulp/known-projects.json. Project metadata comes from microgulp.config.json. The overview distinguishes connected, closed and unavailable. A known entry is not a running engine. Live IDE sessions are tracked separately; multiple windows for the same project can be selected individually.
Follow active IDE project follows the shared active project context. Selecting a session manually pins it only in this browser tab and does not change the controller pin. When another application is in the foreground, the last displayed session remains visible while it is still alive.
The overview and embedded dashboard remain accessible in µGulp™ Free; normal task permissions still apply. Host administration is also available. Open/Focus Project, Start Application, IDE actions and setting the preferred IDE are checked server-side on every call for edition and registration permission. Missing permission returns unsupported-edition or unsupported-registration.
Open and focus projects
Open/Focus Project uses the selected IDE family, specific product and installation. If a matching session exists, its window is focused. Ambiguous matches require session selection. A focus failure does not trigger a second IDE launch; exact window focus is currently Windows-specific. Without a matching session, the known project opens in the selected installation. Parallel requests are coalesced; if launch confirmation does not arrive, an explicit retry is required. A slow project startup may therefore temporarily appear unconfirmed.
Known Windows user installations are detected. Other IDE installations and applications can be configured in ~/.microgulp/applications.json with an absolute executable path and optional fixed arguments; JetBrains requires the specific product. Start Application starts a known application without a shell command. General focusing of arbitrary third-party applications is outside the scope. Windsurf detection is experimental and does not constitute approval of another IDE.
Background Host
A shared Background Host provides the Web Console, known projects, active project and controller context - one process per user, independent of the IDE. The first IDE starts it as needed; closing an IDE does not terminate it. Optional start at login makes the Web Console available even without an open IDE at http://127.0.0.1:47821/console. Without an IDE it lists known projects; with the required edition permission they can be opened in Cursor, VS Code or JetBrains. Tasks are controlled through a connected IDE session. IDE-less task execution and automatic engine-owner handover are not part of 1.0.0.
Settings apply to all IDEs and are stored only in host-settings.json: Start at login and Show background UI are independent. Hiding the UI does not stop the host. The port is global (default 47821, valid range 1024 to 65535). A change restarts the running host; the Web Console moves to the new address. If another application occupies the requested port, the previous port is retained. There is no random port or bind-address field: the host listens only on 127.0.0.1.
On first start µGulp™ asks once per user, not per IDE: Enable µGulp Background Host? Enable turns on start at login. Not now leaves it off; an IDE can still start the host as needed.
The same controls are available in VS Code and Cursor (µGulp: Background Host Settings), in JetBrains (Settings → Tools → µGulp Background Host and Background Host in the tool window), in the Web Console's Background Host section, and through npm run console -- status|open|restart|stop|port <n>|autostart on|off|ui on|off. The Windows tray menu opens the Web Console, shows status, connected IDEs and known projects, and toggles start at login. The port is not changed there. Stop terminates only the host; an IDE may start it again later.
| Platform | Autostart | System UI |
|---|---|---|
| Windows | User login entry | Tray (optional; headless operation remains valid) |
| macOS | LaunchAgent | Menu bar prepared, not yet tested on macOS hardware |
| Linux | XDG autostart | Headless; no tray dependency |
Console texts are currently available in German and English; other languages fall back to English. Host controls use their own localized texts. The full implemented task API is described in IDE actions from tasks.
Deutsch
Rock your Gulp!
µGulp™ ergänzt Gulp um ein interaktives Dashboard für VS Code, Cursor und JetBrains-IDEs. Deine Tasks erhalten dynamische Anzeigenamen, übersichtliche Gruppen, Icons, Beschreibungen und Tooltips. So siehst du, welche Aufgabe zu welchem Projekt und Ziel gehört, ob sie läuft und ob sie erfolgreich war. Formulare, Fortschrittsanzeigen und getrennte Live-Ausgaben begleiten die Ausführung. Die normale Gulp-CLI bleibt als Ausführungsweg erhalten; benötigte Pakete und passende Eingabewerte gelten weiterhin. KI und MCP sind optional.
Zum Einstieg: Erweiterung für deine IDE installieren, ein Projekt mit Gulpfile öffnen und im µGulp™-Dashboard einen Task starten. Voraussetzung ist Node.js ab Version 22 sowie die für dein Projekt benötigten Pakete. Gulp ist ein JavaScript-Werkzeug für wiederkehrende Aufgaben; ein Gulpfile beschreibt diese Aufgaben. µGulp™ ergänzt dafür die Bedienoberfläche.
Highlights
Stand 2.1.0, 20.10.2026: lokal in Prüfung, noch nicht veröffentlicht. Globale Tasks, der angepasste Einstieg und die Gestaltung von Projekt-Tasks sind implementiert. Die bisherigen Abnahmen bleiben ihrem jeweiligen Versionsstand zugeordnet; ein erfolgreicher Teiltest ist keine vollständige Freigabe. Die geprüften Abläufe und ihre Grenzen sind unten dokumentiert.
- NEU in 2.1.0: Projekt-Tasks verständlich gestalten - Bearbeitungssprache wählen, fehlende englische Quelltexte und Übersetzungen mit dem vorhandenen IDE-Agenten vorschlagen lassen sowie Symbole oder eigene Bilder direkt prüfen. Das Gulpfile bleibt auf en-US; Übersetzungen kommen in
i18x/gulp/<sprache>.json. Vorschau, Sicherung und Rücknahme gelten für beide Dateien. - Dynamische Tasknamen, Gruppen, Icons und Tooltips - verständliche Anzeigenamen statt bloßer Funktionsnamen; Namen mit aktuellen Projektwerten wie Version oder Ziel, verschachtelte und einklappbare Gruppen, eigene Icons, Beschreibungen und Tooltips. Mit
µDisplayName,µGroup,µIcon,µDescriptionundµTooltipgestaltest du die Taskliste passend zu deinem Projekt. Texte können lokalisiert werden;µOrdersortiert Tasks und Gruppen,µGroupslegt den Startzustand fest. - Preload von Tasks - warme Node-Worker haben das Gulpfile bereits importiert und verkürzen die Startphase, wenn ein vorbereiteter Worker verfügbar ist; besonders hilfreich bei aufwendigen Imports und Echtzeit-Virenscans
- Task-Zustände auf einen Blick - Start, Ausführung, Eingabebedarf, Stoppen, Erfolg und Fehler werden einheitlich dargestellt; die Zustandsrahmen bleiben auch mit eigenen Icons sichtbar
- 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, …)
- 🔴 NEU in 2.1.0: Passender Einstieg für dein vorhandenes Gulpfile - bereits angepasste Tasks erkennen, gezielt fehlende Darstellungsangaben ergänzen und jede Änderung vorab prüfen. Weitere KI-Rezepte folgen optional; fehlende Tastenkürzel sind nur ein Tipp.
- 🔴 NEU in 2.1.0: Mehrere Projekte mit einer gemeinsamen Aufgabe bedienen - etwa NAS-Sicherungen oder Projektprüfungen über eine gemeinsame ID wie
NASBUanstoßen. Projekte mit Titel und Icon gezielt auswählen, die jeweilige Konfiguration vorab speichern und vor dem Sammelstart prüfen. Jedes Projekt behält seine eigene Umsetzung, Ausgabe und Historie. - 🔴 NEU in 2.0.0: Einrichtungsassistent und KI-Rezepte - Metadaten vorhandener Tasks über Konfigurationsformulare ergänzen, NAS-Backup oder microCSS integrieren sowie Ersteinrichtung und GitHub-/npm-Veröffentlichungen vorbereiten. Alle Dateiänderungen zuerst in der Vorschau prüfen, anschließend mit Sicherung übernehmen und bei unverändertem Dateistand zurücknehmen. Die Vorbereitungstasks veröffentlichen nicht selbst.
- 🔴 NEU in 2.0.0: Projektgruppen und Versionsvorbereitung - Tasks unter Projektname/Info, Build, Tools und Maintenance ordnen; eine npm-Versionserhöhung samt vorhandenen Lockdateien vorab prüfen und gemeinsam übernehmen.
- 🔴 NEU in 2.0.0: Den vorhandenen KI-Agenten einbinden - Einrichtung und Pflege über MCP in Cursor oder IntelliJ nutzen; im Standard ohne zusätzlichen µGulp™-API-Schlüssel. In Cursor steht der Assistent zusätzlich als grafische App im Chat bereit.
- 🔴 NEU in 2.0.0: Übersetzungen gezielt pflegen - nur fehlende oder anhand einer Vergleichsquelle als geändert erkannte Texte in flachen JSON-Wörterbüchern vorschlagen lassen, Platzhalter prüfen und die geprüften Änderungen mit Sicherung und Rücknahme übernehmen. Quell- und Zielsprache wählst du selbst.
- 🔴 NEU in 2.0.0: Handbuchpflege unterstützen - nach Codeänderungen Anpassungsbedarf in deiner DOCX-Quelle mit Quellbelegen aufzeigen. Dokument, Sprache und Redaktionsregeln bestimmst du; die redaktionelle Bearbeitung bleibt bei dir.
- Bestehende Profile weiterverwenden und Verbindung wiederherstellen - Skillprofile 1.0.0 bleiben nutzbar; nach einer beendeten IntelliJ-Projekt-Engine lässt sich das Dashboard gezielt wiederverbinden. Neue Sitzung auswählen und neue Vorschläge prüfen; laufende Tasks werden nicht automatisch wiederholt.
- Web Console und Project Center - bekannte Projekte mit Titel, Beschreibung, Logo und Sitzungsstatus in einer lokalen Projektzentrale; bestehende Dashboards im Browser öffnen, dem aktiven IDE-Projekt folgen oder eine Sitzung nur für diesen Tab festhalten (Übersicht und Host-Verwaltung auch in Free)
- Open/Focus Project - ein bekanntes Projekt in einer konkreten IDE-Installation öffnen oder sein bereits geöffnetes Fenster fokussieren; bei mehreren Sitzungen gezielt auswählen (nicht in Free; exakter Fensterfokus derzeit unter Windows)
- Background Host - gemeinsame Web Console und aktiver Projektkontext in einem Prozess pro Benutzer; optionaler Start bei der Anmeldung und gemeinsame Host-Einstellungen, auch ohne geöffnete IDE; der Host selbst startet keine Projekt-Engine
- Projektidentität - optionaler Projekttitel, Mini-Beschreibung und Logo direkt über der Taskliste; besonders hilfreich bei mehreren geöffneten Projekten oder IDE-Fenstern (
microgulp.config.json→project) - Project Controls - kompakte Select-/Radio-/Checkbox-Zeile unter der Projektidentität für projektweiten Zustand (z. B. Target); sofort wirksam für Displaynamen, Task-/Gruppensichtbarkeit und Task-Ausführung; Werte pro Workspace unter
.microgulp/project-controls.json - Live Animated Task States - unterstützte Hardware (Stream Deck, Logitech-Keypad, Flexbar) zeigt nicht nur statische Icons, sondern den tatsächlichen Laufzeitzustand aus derselben Engine wie das Dashboard: Start, Laufanimation, Eingabebedarf, Stoppen, Erfolg, Fehler (inkl. Burn/Charred) sowie deaktiviert; Watch-Toggle und Scheduler-Countdown erscheinen als zusätzliche Overlays. Die Animation ist Statusfeedback, kein Dekor. (nicht in µGulp™ Free; Flexbar: Hardwaretest ausstehend; Actions Ring: nur Titel, SDK ohne LCD-Animation)
- 38 semantische Task-Icons - passende SVG-Motive über
µTaskKind/µPresentation, Laufanimationen, violettes Dialogsymbol bei Eingabebedarf, Theme-Overrides und reduzierte Bewegung; ein Fehler hinterlässt das ursprüngliche Motiv verkohlt - Task-Scheduler (Session) -
µSchedule/ScheduleTaskmit Timer (after), Intervall (every), Wiederholung (repeat) und Cron (5 Felder, Lokalzeit); Dashboard-Countdown, Enable/Disable/Cancel/Run now; Hardware zeigt Countdown bzw.n/mam Key. Ausführung bleibt ein normalerStartTask - Dauerhafte Dienste gezielt steuern -
µExecutionTypeunterscheidet einmalige Tasks von persistenten Prozessen; laufende Dienste lassen sich wieder stoppen - Taskbaum aus dem Gulpfile steuern -
SetGroupState,RevealTaskundSetTaskEmphasisöffnen Gruppen, machen den nächsten Arbeitsschritt sichtbar und setzen oder entfernen Hervorhebungen - Watch für die Task-Übersicht - Workspace-Watcher scannt bei Speichern neu und tauscht veraltete Worker aus
- Gulp-CLI weiterverwenden - zusätzliche Task-Metadaten lassen die technischen Exportnamen unverändert. Importierte API-Pakete bleiben erforderlich; Eingaben benötigen CLI-Werte oder geeignete Defaults, IDE-Aktionen weiterhin einen passenden Host (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 überi18x-catalogmit 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 herunterladbare und installierbare Oberflächenpakete sind für 2.2.0 vorgesehen. Das Benutzerhandbuch liegt als PDF je gebündelter 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>.jsonfür die gewählten Sprachen, behält bestehende Übersetzungen und mergt die Standard-Formate; eine<lid>.status.jsonlistet, was eine lokale KI noch übersetzen muss - Deklarative Task-Parameter -
µParametersfragt einmal vor dem Lauf, übergibt die Werte alsMICROGULP_PARAMS/GetParameters(), merkt die letzten Antworten, hält Passwörter aus Logs heraus und kann Felder pervisibleWhenausblenden - Watch-/Trigger-Tasks -
µWatch-Globs starten den Task bei Dateiänderungen, mit Debounce, Zusammenfassen und Runaway-Bremse; pro Task im Dashboard scharfschalten - Hardware-Unterstützung - Elgato Stream Deck, Logitech MX Creative Console / Actions Ring, Flexbar und Gamepads werden unterstützt. Enthalten in allen Versionen außer µGulp™ Free (Einrichtung und Gerätestand).
- Logitech folgt dem Workspace - feste Einzel-Task-Zuweisungen oder ein Options+-Profil für die App; das Plugin zeigt im dynamischen Keypad-Ordner den Workspace des fokussierten IDE-Fensters
- Stream Deck folgt dem Workspace - Follow übernimmt das Projekt im aktiven IDE-Fenster, merkt sich die letzte Ansicht je Workspace und Gerät und zeigt das Projektlogo mit Titel auf der Root-Taste. Gruppenpfad und Seite werden beim Zurückkehren wiederhergestellt. (Mehrgeräteabnahme offen; Elgato Smart Profiles sind keine Funktionsgarantie. Logitech bleibt beim bisherigen eingeschränkten Umfang; Flexbar schaltet nicht automatisch mit.)
- Controller als Workflow-Steuerung - Gamepads und Joysticks mit eigenen Profilen, Einlernen, Totzonen und Diagnose; unter Windows x64 auch ohne Dashboard-Fokus, einschließlich eines gemessenen SpaceMouse-Wireless-Profils und optionaler Vibration auf unterstützten Geräten
- Acht IDE-API-Funktionen - Fähigkeiten und bekannte Projekte abfragen, semantische oder native IDE-Aktionen ausführen, Projekte öffnen/fokussieren und konfigurierte Anwendungen starten;
µHost/µIdeApikennzeichnen die Task-Verfügbarkeit. Ausführende Funktionen sind nicht in Free verfügbar;Ide.Capabilities()liefert die Fähigkeiten des Hosts (API-Umfang). - Task-Tastenkürzel -
µKeyBindingmit plattformspezifischen Varianten (ctrl+shift+F1,cmd+shift+Escape), Badge und Kollisionswarnung;µGulp: Run Taskfü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/logsgeschrieben (roh.log+ strukturiert.ndjson), einhistory.ndjson-Index übersteht Reconnects/IDE-Neustarts; ein Historie-Panel im Dashboard öffnet jedes Transkript (logToFile,logRetention) - Native Datei- und Ordnerauswahl - Dateifelder in Formularen öffnen den Auswahldialog von VS Code/Cursor oder JetBrains und liefern den tatsächlichen Pfad
- Modal-Dialoge -
ShowModalMessage/ShowConfirmMessageals AiDPix-Glaspanels im Dashboard (Info/Warnung/Fehler, Ja/Nein, OK/Abbrechen); optional native VS-Code-/Cursor-Modals überpresentationodermicrogulp.modalPresentation(gulp-mu-gulp-api); eigener README-Abschnitt - Klickbare Fehlerstellen -
datei:zeile:spalteim 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/dashboardFontsfür Glyph-µIconund Run-Log-Schrift; optionalµIconFontpro 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(-1offen halten, positive Zahl = Sekunden, weggelassen nutzt Einstellungen → Abgeschlossene Läufe, Standard 30 s); Neu starten neben Schließen - Aufmerksamkeits-Hervorhebung ohne Taskstart -
µAttentionmarkiert Handlungsbedarf,µAttentionWatchaktualisiert ihn bei Dateiänderungen oder per Intervall; mit Tooltip, installierter Version und sichtbarem Hinweis auch an zugeklappten Gruppen - 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 (nicht in µGulp™ Free) - Diagnose-Engine - Importfehler und Stack-Traces werden zu konkreten Lösungsvorschlägen im Dashboard (nicht in µGulp™ Free)
<version/>aus dem Gulpfile -µI18xContext.versionist die bevorzugte Quelle für Task-Titel; optionalesversionSourcesgreift nur, wenn das Gulpfile keineversionsetzt (kein Überschreiben der Verbraucher-Release-Config)- Zuverlässiges LogError vs. Node-Warnings -
LogError/ echteconsole.error-Aufrufe lassen den Run fehlschlagen; Node-DeprecationWarningund andere Prozess-Warnings nicht (Failed-Banner zeigt den ersten echten Fehlertext) - Legacy-Prompt-Brücke -
inquirer/gulp-prompt/promptsauf 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
Projekt-Tasks in der gewünschten Sprache gestalten
Projekt-Tasks einrichten gestaltet die vorhandenen Tasks im ausgewählten Projekt-Gulpfile. Globale, projektübergreifende Tasks werden separat verwaltet und durch diesen Assistenten nicht verändert.
Die Bearbeitungssprache gilt für vorgeschlagene Anzeigenamen, Beschreibungen, Tooltips und Gruppen. Das Auswahlfeld verwendet zentral gepflegte Sprachcodes mit nativen Namen aus dem i18xe-Projekt; zusätzliche gültige BCP 47-Sprachcodes lassen sich ebenfalls eingeben. Die Auswahl wird aus package.json unter microgulp.editingLanguage vorbelegt. Fehlt diese Angabe, verwendet das Formular die Browsersprache der IDE-Webansicht. Die Oberflächensprache bleibt unabhängig; du kannst die Bearbeitungssprache vor jedem Auftrag ändern.
Textvorschläge mit IDE-Agent vorbereiten erstellt einen begrenzten Auftrag für fehlende Textfelder. Das Gulpfile enthält stets englische en-US-Quelltexte; bei einer anderen Bearbeitungssprache ergänzt der Assistent die passenden Übersetzungen in i18x/gulp/<sprache>.json. Bereits vorhandene Übersetzungen werden nicht überschrieben. Im Dashboard kopierst du den angezeigten Auftrag in den verbundenen Cursor- oder IntelliJ-Agent-Chat; in der grafischen MCP-App steht An IDE-Agent senden zur Verfügung, sofern der Client Nachrichten unterstützt. Der vorhandene Agent erzeugt die Texte und reicht sie über MCP zurück. Ein zusätzlicher API-Schlüssel ist nicht erforderlich. Der Assistent startet keinen Agenten im Hintergrund und verwendet keinen kostenpflichtigen Ersatzdienst.
Mit Vorschläge ins Formular laden werden die geprüften Vorschläge sichtbar. Bereits vorhandene Metadaten, Übersetzungsschlüssel, berechnete Werte und währenddessen manuell bearbeitete Felder bleiben erhalten. Der Auftrag läuft nach zehn Minuten ab und wird bei geändertem Gulpfile oder Wörterbuch abgewiesen. Die Vorschau zeigt Änderungen an Gulpfile und Wörterbuch zusammen; erst die ausdrückliche Übernahme mit Sicherung schreibt beide Dateien, und die Rücknahme stellt den vorherigen Stand wieder her. Die sprachliche und sachliche Prüfung bleibt beim Benutzer.
Die acht gebündelten µGulp™-Oberflächensprachen sind davon getrennt. Weitere herunterladbare oder installierbare Übersetzungspakete für die µGulp™-Oberfläche sind für Version 2.2.0 vorgesehen und noch nicht Teil dieses Assistenten.
Für Icons gibst du ein Symbol oder Emoji ein oder wählst ein PNG-, JPEG- oder WebP-Bild bis 64 KiB. Eine direkte Vorschau zeigt die Auswahl. Das Bild wird im Gulpfile eingebettet; es entsteht keine Abhängigkeit vom ursprünglichen Dateipfad. Neue SVG-Dateien und Bild-URLs werden hier nicht importiert. Vorhandene Icon-Metadaten bleiben bei unveränderter Übernahme erhalten.
Bestehendes Gulpfile gezielt verbessern
Der Einrichtungsassistent prüft zuerst rein statisch, ob deine Tasks bereits Darstellungsmetadaten für µGulp™ besitzen. Ein vorhandener Anzeigename, eine Beschreibung, Gruppe, ein Icon oder Tooltip genügt als erkennbarer Hinweis auf eine bereits angepasste Taskdarstellung. Das ist keine vollständige Qualitätsbewertung des Gulpfiles. Nicht jeder Task benötigt jede dieser Angaben.
Sind alle erkannten Tasks bereits angepasst, erscheint keine automatische Optimierungsaufforderung. Bei teilweise angepassten Gulpfiles schlägt der Dialog nur Tasks ohne solche Angaben vor. Zuerst kannst du Namen, Beschreibungen, Gruppen, Icons und Tooltips ergänzen, die Änderungsvorschau prüfen und ausdrücklich mit Sicherung übernehmen. Die Rücknahme bleibt verfügbar. Weitere KI-Rezepte erreichst du anschließend oder durch bewusstes Überspringen dieses Schritts.
Berechnete oder importierte Metadaten lassen sich nicht immer eindeutig beurteilen. Dann meldet der Assistent den unbekannten Optimierungsstand und verändert diese Werte nicht automatisch. Tastenkürzel sind ausschließlich ein optionaler Tipp; ihr Fehlen gilt nicht als Optimierungsbedarf. Auch eine fehlende Zuordnung zu globalen Tasks ist kein Mangel. Weitere KI-Rezepte und Tastenkürzel sind im zweiten Schritt zunächst abgewählt.
Globale Tasks für ausgewählte Projekte
Mit globalen Tasks musst du dieselbe Aufgabe nicht mehr in jedem Projekt einzeln suchen und starten. Eine gemeinsame ID verbindet die passende Umsetzung deiner Projekte: NASBU kann etwa in jedem Projekt andere Ordner sichern. Die Web Console zeigt dir die beteiligten Projekte mit Titel und Icon; du wählst ausdrücklich aus, welche davon starten sollen.
Die globale Definition besteht aus einer stabilen ID und einem verständlichen Titel. Die ausführbare Implementierung bleibt im Gulpfile des jeweiligen Projekts. Das verteilt keinen gemeinsamen Quellcode und kopiert keine Tasks automatisch in andere Projekte. Unterschiedliche Projekte können dieselbe ID passend zu ihren eigenen Anforderungen implementieren.
Ergänze am exportierten Task µGlobalTask = { id: "NASBU", title: "NAS-Sicherung" }. IDs beginnen mit einem Großbuchstaben und enthalten höchstens 64 Großbuchstaben, Ziffern, Unterstriche oder Minuszeichen. Ein Projekt darf eine ID genau einmal anbieten. Markierte Tasks erscheinen im Projektdashboard unter der eigenen Gruppe Globale Tasks; ein vorhandenes µGroup wird für diese Tasks ersetzt.
Öffne die Web Console und klappe Globale Tasks auf. Aktualisiere die Liste und wähle die gemeinsame Aufgabe. Unter Projekt konfigurieren speicherst du die Angaben aus µParameters einmal für das jeweilige Projekt. Sie liegen lokal in .microgulp/global-tasks.json. Eine geänderte Parameterdefinition erfordert eine erneute Konfiguration. Passwörter und mit remember: false markierte Angaben werden hier nicht gespeichert; solche Tasks benötigen weiterhin die interaktive Projektbedienung.
Unter Globale Aufgabe definieren kannst du ID und Titel zentral festlegen. Die Liste erkennt außerdem die IDs verbundener Projekte. Ein zentraler Titel vereinheitlicht die Anzeige; er erzeugt keine ausführbare Implementierung. Definitionen liegen im Benutzerverzeichnis unter .microgulp/global-tasks.json.
Wähle die Projekte anhand von Titel und Icon aus. Bei mehreren IDE-Fenstern desselben Projekts wählst du genau eine Sitzung. Auswahl prüfen zeigt ausschließlich diese Projekte und ihre gespeicherten Werte. Erst Ausgewählte Tasks starten übergibt den Lauf an die jeweilige IDE. Geschlossene Projekte oder IDEs werden nicht automatisch geöffnet.
Der Sammelstart verwendet die gespeicherten Parameter ohne erneute Eingabeformulare. Fordert der Task trotzdem einen µGulp-Dialog an, schlägt dieser Lauf mit global-task-dialog-required fehl. Erhöhte Windows-Rechte und dauerhaft laufende Tasks werden nicht global gestartet. Gulp-Code bleibt lokaler Programmcode; externe Programme mit eigenen Dialogen werden dadurch nicht zu unbeaufsichtigten Tasks.
Vorschauen sind kurzlebig und nur einmal verwendbar. Änderungen am Gulpfile, an der Taskdefinition, den gespeicherten Parametern oder Project Controls machen sie ungültig. Endet oder wechselt die IDE-Sitzung, musst du erneut auswählen und prüfen. Vor dem ersten Start werden alle ausgewählten Sitzungen geprüft.
Ein Sammelstart ist keine Transaktion: Fällt eine Verbindung nach dem ersten Start aus, können vorherige Projekte bereits laufen. Das Ergebnis zeigt gestartete, fehlgeschlagene und noch nicht gestartete Projekte. Es gibt keine automatische Wiederholung und keine automatische Rücknahme ausgeführter Tasks. Fortschritt, Protokolle und Stoppen stehen im jeweiligen Projektdashboard bereit.
Einen Task gezielt in einem anderen Projekt starten
Ein Task in Projekt A kann mit RunGlobalTask aus gulp-mu-gulp-api eine mit µGlobalTask markierte Implementierung in Projekt B starten und auf deren Abschluss warten. Übergib die exakte Projekt-ID und die globale Task-ID. Die Zielparameter müssen zuvor im Dashboard von Projekt B konfiguriert sein. Projekt B muss mit einem aktiven µGulp-Dashboard verbunden sein; wenn mehrere Sitzungen offen sind, gib zusätzlich deren sessionId an. Geschlossene Projekte oder IDEs werden nicht automatisch geöffnet.
import { RunGlobalTask } from 'gulp-mu-gulp-api';
const result = await RunGlobalTask({
projectId: 'Projekt-ID-von-B',
globalId: 'DEPLOY',
timeoutMs: 120000
});
if (!result.ok) throw new Error(result.error ?? result.code);
console.log(result.taskResult);
Die Antwort enthält Status, Lauf-ID und Dauer; taskResult ist nur vorhanden, wenn der Ziel-Task ReportTaskResult aufgerufen hat. Der Aufruf startet den Task über die verbundene IDE-Sitzung des Zielprojekts und öffnet dafür kein sichtbares Web-Console-Fenster. Selbstaufrufe und rekursive Projektketten werden abgewiesen. Das Zeitlimit darf zwischen 1 und 300 Sekunden liegen; ohne Angabe gelten 120 Sekunden. Ein Timeout kann eintreten, obwohl der Ziel-Task bereits gestartet wurde.
Globale Aufrufe benötigen eine aktive, vertrauenswürdige IDE-Sitzung mit geöffnetem µGulp-Dashboard und eine Ausgabe mit IDE-API-Zugriff. Die Projektübersicht und die bisherige einfache Taskbedienung bleiben erhalten. Eine eigenständige Ausführung geschlossener Projekte im Background Host, globale Hardware-Tasten und globale MCP-Werkzeuge gehören nicht zu diesem 2.1.0-Umfang.
Editionen und Funktionsumfang
µ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. 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. JetBrains erfordert keine µGulp™-Registrierung; eine Free-Version für JetBrains gibt es nicht.
| µ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, µSchedule, 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 |
| Hardware-Integrationen (Stream Deck, Logitech, Flexbar) | ja | - | ja |
| IDE-Aktionen aus Tasks | ja | - | ja |
| Web Console: Projektübersicht, Sitzungsstatus, eingebettetes Dashboard | ja | ja, normale Task-Berechtigungen gelten | ja |
| Background Host und Host-Verwaltung | ja | ja | ja |
| Open/Focus Project, Start Application, IDE-Aktionen, bevorzugte IDE | ja | - | ja |
| Host-Einstellungen | microgulp.* |
microgulp.* |
Settings → Tools → µGulp |
| Marketplace | Für VS Code installieren · Von Open VSX installieren | µGulp™ Free installieren · Von Open VSX installieren | Für JetBrains installieren (de.amekudzi.microgulp) |
Alle Editionen sind derzeit kostenlos (0 € / $0 pro Monat und pro Jahr). Die Highlight-Liste beschreibt das volle Produkt; die Editionsgrenzen stehen in der Tabelle. Free folgt dem IDE-/OS-Theme mit IDE Dunkel / IDE Hell (kein Appearance-Picker) und lässt Theme-Packs, Diagnose, Elevation, Hardware-Integrationen und IDE-Aktionen weg. Die lokale Web Console bleibt in Free verfügbar: Projektübersicht, Status und Host-Verwaltung bleiben nutzbar; erweiterte Aktionen (Open/Focus Project, Start Application, IDE-Aktionen, bevorzugte IDE) bleiben den anderen Ausgaben vorbehalten.
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.
Neu in 2.0.0
Der Einrichtungsassistent ergänzt bestehende Projekte mit KI-Rezepten und zeigt alle Dateiänderungen vor der Übernahme. Neu sind auch die optionale MCP-Anbindung an deinen IDE-Agenten sowie Hilfen für Übersetzungen und Handbuchpflege. Der tägliche Einstieg bleibt: Projekt öffnen, Task auswählen, starten.
Ein allgemeiner KI-Workflow-Generator, semantische Optimierung beliebiger Tasks und evolutionäre Selbstoptimierung sind nicht implementierte Ausbauideen ohne zugesagten Umfang oder Termin.
Bereits seit 1.1.0
Optionale Formularinformationen stehen vor den Eingabefeldern. Tasks können Abbrechen und das Merken geeigneter Auswahlwerte ausdrücklich aktivieren. µI18xContext.GetValues() liefert einen synchronen Metadatenstand pro Scan; geänderte Platzhalter aktualisieren auch die Taskliste. Bestehende Gulpfiles und Formularantworten bleiben kompatibel. Die neuen Funktionen sind in gulp-mu-gulp-api 0.7.0 dokumentiert.
Formularvertrag und Beispiele · Releasehinweise 1.1.0
Einrichtungsassistent und KI-Rezepte
Projekt-Tasks einrichten öffnet im Dashboard den Assistenten für ein vorhandenes Gulpfile. Er analysiert ESM/CommonJS statisch, bietet passende Konfigurationsfelder an und zeigt vor der Übernahme alle Änderungen. Die neun KI-Rezepte umfassen Anzeigenamen und Beschreibungen, freie und projektbezogene Taskgruppen, Tastenkürzel, NAS-Backup, microCSS, Ersteinrichtung sowie GitHub- und npm-Vorbereitung.
- NAS-Backup: Projektkennung, Quelle, mehrere Ziele, Sicherungsmodus, Verzeichnis oder ZIP, Kopierverfahren und Ausschlüsse. Probelauf ist voreingestellt; Zielkennungen werden zur bewussten Vorbereitung angezeigt. Die Einrichtung selbst greift nicht auf das NAS zu.
- microCSS: vorhandenes vertrauenswürdiges Manifest, Quell- und Ausgabeordner, Komprimierung und Grafikvorschauen. Jeder Build verwendet einen neuen Ausgabe-Unterordner.
- Sichere Übernahme: vollständige Dateivorschau, Quellhashprüfung, Schutz vorhandener KI-Rezeptdateien, Sicherung unter
.microgulp/setup-backupsund Rücknahme der letzten unveränderten Übernahme in derselben Sitzung.
Benötigte Abhängigkeiten werden in der Vorschau aufgeführt und anschließend mit npm install im jeweiligen KI-Rezeptordner installiert. Die drei neuen Vorbereitungskonzepte benötigen keine zusätzlichen KI-Rezeptpakete. Imports im microCSS-Manifest benötigen ihre Pakete zusätzlich im Quellprojekt. Laufende Tasks und Scans blockieren Änderungen. Dynamische Gulpfile-Konstruktionen können manuelle Anpassungen erfordern.
Ersteinrichtung und Veröffentlichungen vorbereiten
Die KI-Rezepte Ersteinrichtung, GitHub-Veröffentlichung und npm-Veröffentlichung ergänzen dein vorhandenes Gulpfile um Vorbereitungstasks. Jedes KI-Rezept hat ein Formular für den Projektnamen und seine Einstellungen. Die Tasks zeigen passende Prüfschritte und Befehle an; sie installieren keine Abhängigkeiten und führen keinen Push oder Publish aus. Auch die Übernahme im Assistenten ist keine Freigabe zur Veröffentlichung.
- Ersteinrichtung (
project-bootstrap): Paketdatei, Git-Zustand, Ausschlüsse, Abhängigkeiten sowie vorhandene Build- und Testskripte prüfen. Bei einem neuen Projekt zunächst ein leeresgulpfile.mjsanlegen und im Assistenten auswählen. Fehlende Paketdateien werden als Vorbereitungsschritt genannt, nicht still erzeugt. - GitHub (
github-release):Eigentümer/Repositoryund Sichtbarkeit wählen. Der Plan führt durch Anmeldung, Remote- und Dateiprüfung, bewusstes Anlegen eines fehlenden Repositorys, Push des geprüften Commits und einen Release-Entwurf mit geprüftem Tag. Repository-Erstellung, Push und Veröffentlichung bleiben getrennte, ausdrücklich zu beauftragende Schritte. - npm (
npm-release): Patch, Minor oder Major sowie Registry, Zugriff und Veröffentlichungskanal wählen. Mit Versionserhöhung in die Dateivorschau aufnehmen zeigt der Assistent die höhere Version inpackage.jsonund vorhandenenpackage-lock.json/npm-shrinkwrap.json. Bei Übernahme werden diese Dateien gemeinsam mit dem Gulpfile gesichert und geändert; die Rücknahme stellt sie bytegenau wieder her. Ohne diese Option enthält der Plan die Versionserhöhung als noch auszuführenden Schritt.
Die automatische Versionserhöhung unterstützt stabile Versionen wie 1.2.3; Vorabversionen und Workspace-Sammelpakete erfordern einen projektspezifischen Ablauf. Private Pakete, widersprüchliche Lockdateien oder abweichende Veröffentlichungseinstellungen blockieren die automatische Änderung. Bei vorhandener RELEASES.json die automatische Versionserhöhung abwählen und den Versionsabgleich des Projekts verwenden. Andere eigene Versionsquellen ebenfalls über den projektspezifischen Ablauf pflegen. Ein bereits durch diese Einrichtung erhöhter Stand wird beim Start der Vorbereitungstasks nicht nochmals erhöht.
Die Registry wird bei Vorschau und Taskstart nicht abgefragt. Der npm-Plan verlangt deshalb vor der tatsächlichen Veröffentlichung die Registry-Prüfung, Tests, Build, Kontrolle des Paketinhalts und Anmeldung. Die lokale Versionserhöhung bestätigt noch nicht, dass die Version in der Registry frei ist. Ein veröffentlichtes Paket mit derselben Version kann nicht erneut veröffentlicht werden. npm-Veröffentlichung · npm-Versionierung · GitHub-Release-Entwurf
Aufgaben nach Projekt ordnen
Alle drei KI-Rezepte legen je vier Vorbereitungstasks unter Projektname/Info, Projektname/Build, Projektname/Tools und Projektname/Maintenance an. Info enthält Bestands- und Ergebnisprüfungen, Build die Build-Vorbereitung, Tools Hilfs- und Prüfschritte und Maintenance Einrichtung, Versionierung und Release-Vorbereitung. Die Tasknamen beginnen standardmäßig mit SETUP_PROJECT, PREPARE_GITHUB_RELEASE oder PREPARE_NPM_RELEASE; angehängt wird die Kategorie in Großbuchstaben.
Mit Projektbezogene Taskgruppen (project-structure) ordnest du auch ausgewählte bestehende Tasks ein: Projektname eingeben und pro Task eine der vier Kategorien wählen. Exportnamen und Taskcode bleiben unverändert. Dieses KI-Rezept und das freie KI-Rezept Taskgruppen lassen sich nicht gleichzeitig anwenden. Die Zuordnung erscheint in der Vorschau und wird mitgesichert.
Über MCP stehen dieselben Formulare und Änderungen über list_recipes, get_recipe, preview_setup, apply_setup und undo_setup bereit. get_recipe und list_library liefern auch die versionierten Anweisungen für den IDE-Agenten, einschließlich Versionsprüfung und Veröffentlichungsfreigabe. Ein gesonderter automatisch veröffentlichender KI-Skill ist nicht Bestandteil dieser KI-Rezepte. Projektstart-, GitHub- und npm-KI-Rezept wurden bis zum 19.10.2026 zusätzlich in den installierten Cursor- und IntelliJ-Clients über MCP geprüft: Vorschau, Übernahme, lesende Dateikontrolle und Rücknahme. Die Ausgangshashes wurden wiederhergestellt, einschließlich Paketdatei und Lockdatei bei der npm-Versionserhöhung. Es wurden dabei keine Vorbereitungstasks gestartet, Registry-Abfragen ausgeführt oder Veröffentlichungen vorgenommen.
Einrichtung über MCP
Der separate MCP-Adapter bietet denselben Ablauf über list_recipes, get_recipe, list_setup_files, analyze_gulpfile, preview_setup, apply_setup und undo_setup. list_projects, list_tasks und get_task liefern Projekte, konkrete IDE-Sitzungen und den Taskkatalog. Mit open_setup_assistant öffnet ein MCP-Apps-fähiger Client wie Cursor die grafische Einrichtung direkt im Chat: Gulpfile auswählen, analysieren, KI-Rezepte ankreuzen, Formulare ausfüllen und die vollständige Änderungsvorschau prüfen. Übernahme und Rücknahme erfolgen über eigene Schaltflächen mit denselben Schutzprüfungen wie im Dashboard. Cursor kann die Werkzeugaufrufe der App zunächst zur Freigabe vorlegen. Clients ohne MCP Apps verwenden weiterhin die einzelnen Werkzeuge.
Node.js 22 oder neuer und eine laufende Sitzung des aktualisierten Hosts sind erforderlich. Nach Installation der separaten SDK-Abhängigkeiten (npm ci --prefix <Installationsordner>/src/mcp --omit=dev --ignore-scripts) startet der Client node <Installationsordner>/src/mcp/microgulp-mcp.mjs --project <absoluter-Projektpfad>. Änderungen benötigen zusätzlich --setup-write-project <derselbe-Projektpfad>. Ohne diese beim Start gesetzte Freigabe sind nur Lesen, Analyse und Vorschau möglich. Vorschläge sind nach MCP-Prozess und IDE-Sitzung getrennt. Taskstart, automatische Paketinstallation und Veröffentlichung gehören nicht zu diesen Werkzeugen.
Textvorschläge prüfen und MCP nach einem Update verbinden
Öffne Projekt-Tasks einrichten und wähle das Gulpfile, die gewünschten Tasks und die Bearbeitungssprache. Bereite den Textauftrag erst vor, wenn der IDE-Agent mit dem µGulp™-MCP-Server verbunden ist. Kopiere den angezeigten Auftrag in diesen Chat. Lass das Formular geöffnet; der Auftrag gilt zehn Minuten und gehört zur aktuellen Projekt-Engine.
Nach der Rückmeldung des Agenten klicke im selben Formular auf Vorschläge ins Formular laden. Prüfe die ergänzten Namen, Beschreibungen, Tooltips und Gruppen. Die Rückmeldung review-required bedeutet nur, dass ein Vorschlag vorliegt; sie bestätigt weder dessen Qualität noch eine Änderung am Gulpfile. Unpassende oder nichtssagende Texte kannst du korrigieren oder weglassen. Der Agent darf aus einem Tasknamen keine unbekannte Funktion erfinden.
Prüfe anschließend die Änderungsvorschau und übernimm sie bei Bedarf mit Sicherung. Diese Änderung zurücknehmen stellt den gesicherten Stand wieder her, solange keine nachträglichen Änderungen vorliegen. Wurde der Auftrag direkt im Chat vorbereitet, ist er nicht automatisch mit einem bereits geöffneten Formular verbunden. Für den Formularablauf beginne deshalb mit dem dort angezeigten Auftrag. Nach Ablauf, Sprachwechsel oder Engine-Neustart bereite einen neuen Auftrag vor.
Nach einem Erweiterungsupdate kann sich der Installationsordner ändern. Prüfe den Pfad zur microgulp-mcp.mjs in der MCP-Konfiguration und installiere die separaten SDK-Abhängigkeiten im neuen src/mcp-Ordner mit npm ci --omit=dev --ignore-scripts. Ein eingeschalteter Server ist noch kein Nachweis einer funktionierenden Verbindung. Bei Connection closed prüfe das Serverprotokoll; fehlt @modelcontextprotocol/sdk, fehlen diese Abhängigkeiten im verwendeten Ordner.
Verbinde den MCP-Server erneut und öffne einen neuen Agenten-Chat. Prüfe mit list_projects die aktuelle Sitzung. Für Textvorschläge müssen prepare_setup_text, get_setup_text und submit_setup_text verfügbar sein. Liefert list_projects ein Projekt ohne Sitzung, öffne dessen µGulp™-Dashboard. Eine erreichbare MCP-Verbindung und eine aktive Projekt-Engine sind beide erforderlich.
Grafische MCP-App in Cursor
- Öffne das Projekt in Cursor und verbinde den eingerichteten µGulp™-MCP-Server. Der Server bietet Werkzeuge für Einrichtung, Taskzugriff und optionale Skills sowie eine UI-Ressource.
- Bitte den Cursor-Agenten: „Ermittle mit
list_projectsdie aktuelle Sitzung dieses Projekts und öffne dafüropen_setup_assistant. Danach keine weiteren Änderungen ausführen.“ Klappe das Werkzeugergebnis im Chat auf, falls die App eingeklappt ist. - Wähle das Gulpfile und klicke Analyze gulpfile. Bestätige eine von Cursor angeforderte Werkzeugfreigabe selbst. Wähle die KI-Rezepte und fülle die angezeigten Felder aus: NAS-Projektkennung, Quelle und Ziele; microCSS-Manifest, Quelle und Ausgabe; Anzeigenamen, Beschreibungen, Gruppen und Tastenkürzel.
- Klicke Preview changes. Prüfe die Vorher-/Nachher-Ansicht, den vollständigen neuen Gulpfile-Inhalt und die aufklappbaren neuen KI-Rezeptdateien. Die Vorschau zeigt auch benötigte Pakete und die Vorbereitung der NAS-Zielkennungen. Bis hierhin werden keine Dateien geschrieben.
- Apply changes and create backup übernimmt den geprüften Vorschlag und sichert die Originale unter
.microgulp/setup-backups. Geänderte Quelldateien, bereits vorhandene KI-Rezeptdateien oder laufende Tasks verhindern eine unsichere Übernahme. - Undo this change stellt die Originaldateien bytegenau wieder her und entfernt ausschließlich die bei dieser Übernahme angelegten KI-Rezeptdateien. Nachträgliche Änderungen blockieren die Rücknahme. Die letzte Übernahme lässt sich nur in derselben MCP-Verbindung und IDE-Sitzung zurücknehmen.
Ohne --setup-write-project stehen Analyse und Vorschau zur Verfügung; die Übernahme ist ausgeblendet. Die Oberfläche startet keine Tasks und installiert keine Pakete. Mehrere App-Ansichten und Agentenaufrufe derselben Verbindung teilen die letzte Vorschau: Bearbeite deshalb jeweils nur einen Vorschlag.
Nach einem Cursor-, Host- oder MCP-Neustart list_projects und open_setup_assistant erneut aufrufen und neu analysieren. Eine alte Ansicht kann ide-session-unavailable melden. Vorschauen gelten zehn Minuten. Bricht die Verbindung beim Übernehmen ab, prüfe zuerst den Dateistand und die Sicherung, bevor du erneut schreibst. Nach einem VSIX-Update den MCP-Installationspfad prüfen, die SDK-Abhängigkeiten bei Bedarf erneut installieren und den Server neu verbinden.
MCP in Cursor und IntelliJ verbinden
MCP und Skills sind optional. Für den Alltag genügt weiterhin: Projekt öffnen, Task auswählen, starten. Für die folgenden Schritte muss das Projekt im aktualisierten µGulp™-Host geöffnet sein. Verwende den tatsächlichen Installationsordner: In Cursor liegt der Adapter unter src/mcp, im entpackten JetBrains-Plugin unter microgulp/src/mcp. Installiere dort die separaten SDK-Abhängigkeiten wie oben beschrieben.
Diese Beispielkonfiguration gilt für beide Clients. Ersetze die absoluten Beispielpfade durch deine lokalen Pfade; --setup-write-project erlaubt die spätere geprüfte Übernahme und Rücknahme in genau diesem Projekt:
{
"mcpServers": {
"microgulp": {
"command": "C:/Program Files/nodejs/node.exe",
"args": [
"C:/Pfad/zur/Installation/src/mcp/microgulp-mcp.mjs",
"--project", "C:/Projekte/MeinProjekt",
"--setup-write-project", "C:/Projekte/MeinProjekt"
]
}
}
}
- Cursor: Ergänze den Server in der projektbezogenen
.cursor/mcp.json, ohne vorhandene Servereinträge zu entfernen. Aktiviere ihn in der MCP-Verwaltung und prüfe den Verbindungsstatus. Nach Änderungen an der Serverkonfiguration neu verbinden und einen neuen Agenten-Chat öffnen. - IntelliJ: Unter Settings → Tools → AI Assistant → Model Context Protocol (MCP) den Server mit Add als STDIO-Verbindung hinzufügen, die JSON-Konfiguration einfügen und mit Apply starten. Unter Tools → AI Assistant → Agents zusätzlich Pass custom MCP servers aktivieren und bestätigen. Pass IntelliJ MCP server betrifft den eingebauten IDE-Server und ersetzt diese Weitergabe nicht. Anschließend einen neuen Chat mit dem gewünschten Agenten öffnen. Geprüft wurde hier Codex mit ChatGPT-Anmeldung; µGulp™ benötigt dafür keinen separaten API-Schlüssel. JetBrains-Einrichtung
Erster Prüfauftrag: „Rufe beim MCP-Server microgulp das Werkzeug list_projects auf. Keine Ressourcenabfrage und keine Änderungen.“ Prüfe Projektpfad, IDE und Sitzung in der tatsächlichen Werkzeugantwort. unknown MCP server oder fehlende Werkzeuge bedeuten, dass der Chat noch keine Verbindung hat. Dann Serverstatus, Weitergabe und neuen Chat prüfen. Eine erfolgreiche Ressourcenabfrage ersetzt den Werkzeugtest nicht. Verwende die gelieferten projectId und sessionId; alte Sitzungskennungen nicht übernehmen.
Skills mit dem vorhandenen Agenten
Die versionierte Bibliothek wird mit list_library abgefragt. Projektprofile liegen in .microgulp/agent-profiles.json; sie legen erlaubte Eingabedateien und die Skill-Version fest. Der Standard execution: "client" verwendet den vorhandenen IDE-Agenten. Separate skillGrants sind nur für den ausdrücklich aktivierten API-Modus erforderlich; eine leere Liste verhindert den normalen Client-Ablauf nicht. start_api_skill ist kein automatischer Ersatz für eine fehlende Agentenverbindung.
Beispiel für ein Übersetzungsprofil; die drei JSON-Dateien müssen bereits im Projekt liegen:
{
"schemaVersion": 1,
"profiles": {
"texte-de": {
"enabled": true,
"skill": "localization",
"version": "1.1.0",
"execution": "client",
"configuration": {
"source": "i18x/source.json",
"target": "i18x/de-DE.json",
"baseline": "i18x/source-baseline.json",
"sourceLanguage": "en-US",
"language": "de-DE"
}
}
}
}
inspect_skill_profileliefert den aktuellen Profilhash.start_skillerhält Profil-ID, diesen Hash und eine neue eindeutigerequestId. Der vorbereitete Arbeitsauftrag gilt 30 Minuten.- Der Agent bearbeitet die gelieferten Einträge und sendet sein Ergebnis mit Job-ID und unverändertem
digestansubmit_skill_result. Dabei entsteht ein gespeicherter Vorschlag unter.microgulp/proposals/<id>/proposal.json; die Übersetzungsdatei bleibt unverändert. - Prüfe die Vorschau: Zielpfad, geänderte Texte, erhaltene Platzhalter und unveränderte Einträge. Erst danach
apply_skill_proposalmit der Vorschlags-ID freigeben. µGulp™ prüft die Quellen erneut und sichert den Originalinhalt unter.microgulp/proposals/<id>/original.json. - Kontrolliere die tatsächliche Datei.
undo_skill_proposalnimmt genau diese Übernahme mit derselben ID zurück, solange die Datei danach unverändert geblieben ist und dieselbe MCP-Verbindung und Host-Sitzung bestehen. Für eine Abnahme den Datei-Hash vor dem Test und nach der Rücknahme vergleichen.
Ein einfacher Auftrag lautet: „Verwende das Profil texte-de mit dem vorhandenen Agenten, reiche das Ergebnis über MCP ein und zeige mir die Vorschau. Stoppe vor der Übernahme. Keine direkten Dateiänderungen.“ Übernahme und Rücknahme werden anschließend ausdrücklich beauftragt. Nach skill-expired neu vorbereiten; bei unknown-skill-run oder unknown-undo zuerst Sitzung, Dateistand und Sicherung prüfen. Nicht blind wiederholen oder die Rücknahme durch direkte Schreibzugriffe ersetzen.
Handbuchpflege mit belegter Vorschau
Ein Profil mit skill: "handbook-maintenance", Version 1.1.0 und execution: "client" nennt unter configuration eine frei benannte DOCX-Datei im Projekt als master, deren sourceLanguage, die Implementierungsdateien in files und einen vollständigen vorhandenen Git-Commit als baselineCommit. outputLanguage bestimmt optional die Sprache der Vorschläge; ohne Angabe gilt die Ausgangssprache. chapters grenzt die Kapitel ein, editorialRules enthält optionale projektspezifische Redaktionsvorgaben. Der Commit muss aus dem geöffneten Projekt lesbar sein. Dateiformate wie PDF oder Markdown werden vom Handbuch-Skill derzeit nicht verarbeitet.
Der Ablauf bis submit_skill_result entspricht dem Übersetzungs-Skill. Die Vorschau enthält Änderungsvorschläge mit Datei- und Zeilenbelegen sowie den Hinweis editorial-review-required. Eine automatische DOCX-Übernahme gibt es nicht: apply_skill_proposal weist einen Handbuchbericht mit handbook-report-requires-editorial-work zurück. Die redaktionelle Bearbeitung erfolgt separat in deiner konfigurierten DOCX-Quelle. Der Skill aktualisiert keine Vergleichsbaselines, Übersetzungen oder fertigen Ausgaben. Die Regel „zuerst deutsche .src.-Dateien, spätere Übersetzung nur der Differenzen“ ist eine Konvention unseres eigenen µGulp™-Projekts und steht ausschließlich in dessen Profil; Kunden legen ihren Redaktionsablauf selbst fest.
Beispiel für ein Kundenhandbuch
Die Quelldatei darf etwa docs/Customer Guide.docx heißen. Das folgende Profil verwendet Englisch als Ausgangssprache und Französisch für die Vorschläge. Ersetze den Platzhalter durch einen echten vollständigen Git-Commit aus deinem Projekt:
{
"enabled": true,
"skill": "handbook-maintenance",
"version": "1.1.0",
"execution": "client",
"configuration": {
"master": "docs/Customer Guide.docx",
"sourceLanguage": "en-US",
"outputLanguage": "fr-CA",
"files": ["src/build.mjs"],
"baselineCommit": "<vollständiger Git-Commit>",
"editorialRules": "Kundenterminologie erhalten und bestehende Kapitelstruktur beachten."
}
}
Dieser Eintrag gehört unter einem eigenen Namen in profiles der .microgulp/agent-profiles.json. Sprachkennungen wie de-DE, en, fr-CA oder zh-Hant werden geprüft. Die Sprache des Agentenergebnisses wird nicht automatisch sprachlich zertifiziert. Quell- und Zieldatei einer Übersetzung müssen verschieden sein; unterstützt werden flache JSON-Wörterbücher mit Zeichenketten, keine allgemeine Übersetzung von Markdown oder DOCX.
Vorhandene Skillprofile aktualisieren
Profile mit Skill-Version 1.0.0 bleiben für Übersetzung und Handbuchpflege ausführbar. Die Profildatei und ihr Hash werden nicht automatisch umgeschrieben. Ohne sourceLanguage bleibt die Ausgangssprache alter Übersetzungsprofile unbestimmt (und); der Agent ermittelt sie aus dem gelieferten Text. Alte Handbuchprofile verwenden ohne Sprachangabe weiterhin de-DE. Explizite Sprachangaben haben Vorrang. Neue Kundenprofile verwenden 1.1.0 mit bewusst gewählter Quelldatei und Ausgangssprache; projektspezifische Redaktionsregeln gehören nur ins Profil. Für eine dauerhafte Umstellung das Profil sichern, Version und Sprachen prüfen und einen neuen Auftrag vorbereiten. Unbekannte Versionen oder fehlerhafte Profile erscheinen einzeln als nicht ausführbar und blockieren keine gültigen Nachbarprofile. Eine insgesamt ungültige Profildatei wird weiterhin abgewiesen. Bibliotheks-Pins samt Integritätswerten werden nicht automatisch erneuert. Vorschau, Platzhalterschutz, Sicherung, Rücknahme und die Sperre gegen automatische DOCX-Übernahme gelten auch für Altprofile.
Dashboard-Verbindung in IntelliJ wiederherstellen
Wenn die Projekt-Engine in IntelliJ beendet wurde, erkennt das geöffnete µGulp™-Toolfenster dies und bietet Reconnect dashboard an. Beim Aus- und erneuten Einblenden des Toolfensters startet eine als beendet erkannte Engine wieder. Eine noch laufende Engine wird dabei nicht neu gestartet; Tasks werden nicht wiederholt. Bei einem Startfehler bleibt die Fehlermeldung mit Wiederholungsmöglichkeit sichtbar, ohne automatische Versuchsschleife. Ein Start ohne Bereitschaftsmeldung wird nach spätestens 120 Sekunden abgebrochen. Danach Node-Pfad und Projekteinstellungen prüfen und Reconnect dashboard wählen. Nach der Wiederverbindung list_projects erneut aufrufen und die neue Sitzung auswählen. Alte Vorschlags- und Rücknahme-IDs nicht in einer neuen Sitzung weiterverwenden; vorhandene Sicherungen vor einem neuen Änderungsauftrag prüfen. Ein grüner MCP-Serverstatus allein belegt keine aktive Dashboard-Sitzung.
Geprüfte Abläufe und Freigaben
Die konfigurierbaren Kundenprofile mit Skill-Version 1.1.0 wurden bis zum 19.10.2026 in den installierten Cursor- und IntelliJ-Clients über MCP geprüft: en-GB nach fr-CA, Übersetzungsvorschau mit erhaltenem Platzhalter, Übernahme und bytegenaue Rücknahme. Beim Handbuch waren DOCX-Quelle und Berichtssprache frei gewählt; die automatische Übernahme wurde mit handbook-report-requires-editorial-work abgewiesen und der DOCX-Hash blieb unverändert. Die Kompatibilität bestehender 1.0.0-Profile wurde anschließend zusätzlich im IntelliJ-Client bestätigt. Diese Prüfungen belegen den kontrollierten Ablauf, nicht die sprachliche Qualität beliebiger Agentenergebnisse.
Am 19.10.2026 wurde in IntelliJ die Wiederverbindung nach einer beendeten Projekt-Engine über Reconnect dashboard geprüft: Die neue Sitzung war über MCP erreichbar, und die anschließenden Altprofil-Prüfungen bestanden. Übersetzungsänderungen wurden übernommen und bytegenau zurückgenommen; die automatische Handbuchübernahme wurde vom Server abgewiesen, die DOCX-Datei blieb unverändert. Das belegt den geprüften Wiederverbindungsfall, keine Wiederherstellung beliebiger laufender Tasks oder alter Vorschlags-IDs.
Der abschließende lokale Testlauf unter Windows mit Node.js 22 bestand mit 1115 erfolgreichen Tests, keinem Fehler und vier ausdrücklich übersprungenen Plattform-/Gerätefällen. Weitere 31 MCP-/Website-Tests bestanden. Die aktualisierten VS-Code-, Cursor-Internal- und Free-Pakete wurden installiert und mit einem erfolgreichen Dashboard-Task geprüft. Der JetBrains Plugin Verifier bestätigt Kompatibilität mit den geprüften Plattformständen 242, 261 und 262; die beiden beanstandeten veralteten API-Aufrufe sind entfernt. Das korrigierte JetBrains-Paket wurde unter Windows in IntelliJ IDEA 2026.2.2 lokal installiert und geprüft: vorbelegten Dateipfad bestätigen, Dateiauswahl abbrechen, Logdatei öffnen sowie vollständiger Dashboard-Aufbau, Ausblenden und Wiederöffnen, Maximieren und Wiederherstellen und Größenänderungen des Toolfensters. Monitorwechsel mit unterschiedlicher DPI-Skalierung wurden nicht geprüft. Frühere native MCP-Abnahmen bleiben ihrem jeweiligen Paketstand zugeordnet. Ein neuer plattformübergreifender CI-Lauf und die noch offenen physischen Hardwareprüfungen sind damit nicht ersetzt.
Vom 17. bis 19.10.2026 wurden die lokal installierten 2.0.0-Pakete unter Windows mit dem echten Cursor-Agenten und mit Codex im IntelliJ-AI-Chat geprüft: Übersetzungsvorschau, Übernahme, lesende Dateikontrolle und bytegenaue Rücknahme; außerdem Handbuchvorschau mit Quellbelegen, abgewiesene automatische DOCX-Übernahme und unveränderter DOCX-Hash. Die grafische MCP-App wurde in Cursor geprüft; daraus folgt keine Abnahme einer grafischen App in IntelliJ. Andere Agenten und Betriebssysteme sind durch diese Prüfung nicht abgedeckt.
Ein erster Cursor-Lauf meldete unknown-undo; dessen Ursache blieb ungeklärt. Der anschließende vollständige Durchlauf bestand. Deshalb bleiben Sitzung und Sicherung bei Fehlern ausdrücklich zu prüfen. Eine Ablehnung durch die Freigabeprüfung des Clients, etwa Guardian, ist keine µGulp™-Werkzeugantwort und kein bestandener Negativtest. Freigaben nicht umgehen; ein zusätzlich nötiger Versuch benötigt eine ausdrückliche zusätzliche Autorisierung. Für einen DOCX-Negativtest müssen die tatsächliche µGulp™-Fehlermeldung und der danach gelesene unveränderte Hash vorliegen.
Startkonfiguration, Werkzeugablauf und Grenzen
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 → ein verfügbarer warmer Worker übernimmt den Lauf ohne erneuten Gulpfile-Import. 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.
Gulp-CLI weiterverwenden
Zusätzliche Task-Metadaten ändern die CLI-Adressierung nicht. Bestehende Buildabläufe können unter der klassischen gulp-CLI und in der CI weiterlaufen. Importierte Pakete bleiben nötig; Eingabewerte und hostabhängige Aktionen müssen für diesen Ausführungsweg geeignet sein. Prüfe die bisherigen CLI-Aufrufe nach einer Integration.
Verhalten ohne Dashboard
| Ergänzung im Gulpfile | Verhalten unter reinem gulp |
|---|---|
µDisplayName, µIcon, µGroup, µGroups, µOrder, µKeyBinding, µWatch, µAutoClose, µAttention, µ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/ |
Enthält je nach Nutzung auch KI-Rezeptcode, Profile, Konfiguration und Sicherungen. Nicht pauschal löschen: importierter KI-Rezeptcode kann für CLI-Läufe erforderlich sein. Projektdateien gezielt versionieren; lokale Logs, Zugangsdaten und Sicherungen ausschließen |
gulp-mu-gulp-api ist ein normales npm-Paket ohne Laufzeit-Abhängigkeiten, und IsMicroGulp() sagt einem Task, ob er gerade orchestriert wird. Beim Entfernen der Erweiterung benötigte Pakete und KI-Rezeptdateien behalten. Hostabhängige Aktionen benötigen einen passenden Fallback.
Versionsgrenzen beachten
Zusätzliche Metadaten werden von der klassischen Gulp-CLI ignoriert. Daraus folgt keine pauschale Kompatibilitätszusage für beliebige Host-, Gulp- oder API-Versionen: Neue API-Aufrufe können neuere Pakete voraussetzen, IDE-Aktionen passende Hostfähigkeiten. Versionsvoraussetzungen beachten und bestehende Aufrufe nach einem Update prüfen.
Praktische Folge: Ein Kollege kann vorhandene Build-Tasks weiterhin per npx gulp BUILD im Terminal nutzen, während du sie im Dashboard bedienst. Beide Ausführungswege verwenden dieselben Projektdateien; parallele Schreibzugriffe müssen im Projekt abgestimmt werden.
Installation (DE)
µGulp™ ist jetzt verfügbar. Installation über die öffentlichen Einträge:
| Edition | Installieren |
|---|---|
| µGulp™ (VS Code / Cursor) | Für VS Code installieren · Von Open VSX installieren |
| µGulp™ Free (VS Code / Cursor) | µGulp™ Free installieren · Von Open VSX installieren |
| µGulp™ (JetBrains-IDEs) | Für JetBrains installieren |
Das Quell-Repository bleibt privat. Die registrierte VS-Code-/Cursor-Erweiterung und µGulp™ Free nicht nebeneinander installieren - dieselben Kommando-IDs.
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. Für JetBrains installieren über den Marketplace; der Eintrag bietet zwei kompatibilitätsspezifische Builds, die IDE erhält den passenden (Help → About):
| IDE-Build | since-build |
Marketplace |
|---|---|---|
2024.2 - 2026.1 (bis 261.*) |
242 |
Für JetBrains installieren |
| 2026.2 und neuer | 262 |
Für JetBrains installieren |
Der Marketplace wählt den passenden Build. IntelliJ IDEA, PhpStorm, WebStorm und die übrigen IntelliJ-basierten IDEs teilen sich diese zwei Varianten - nach Plattform-Build, nicht nach Produktname. Jede Variante trägt
<idea-version since-build="…"/>im Plugin-Descriptor - die IDE lädt die andere nicht. Die Variante 2024.2-2026.1 istsince-build="242"/until-build="261.*". Die Variante 2026.2+ istsince-build="262"ohne Obergrenze. 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 die eigene Marketplace-Variante. Installation über den JetBrains Marketplace (Settings → Plugins → Marketplace, Suche MicroGulp), 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:verifylä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 inMICROGULP_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. MitMICROGULP_SKIP_IDE_DOWNLOAD=1bleibt 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.jcefund 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.
Offline-Pakete
Diese Dateien gibt es nur in einem lokalen Checkout des Quell-Repository. Sie sind nicht der öffentliche Installationsweg.
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, dannnpm run build- registriertes und Free-.vsixlanden inpackages/.
JetBrains-ZIPs aus einem lokalen Build:
| IDE-Build | Paket |
|---|---|
2024.2 - 2026.1 (bis 261.*) |
packages/microgulp-jetbrains_latest.zip |
| 2026.2 und neuer | packages/microgulp-jetbrains-2026.2_latest.zip |
Lokales ZIP über Settings → Plugins → ⚙ → Install Plugin from Disk… einspielen.
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, project). 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,
"project": {
"title": "My Project",
"description": "Build, test and deployment tasks",
"logo": "./assets/project-logo.svg"
}
}
| Schlüssel | Typ | Default | Bedeutung |
|---|---|---|---|
gulpfile |
String | - | Einzelnes Gulpfile, relativ zum Projektstamm; darf den Projektstamm nicht verlassen |
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. |
project |
Objekt | - | Optional. Projektidentität für die Taskleiste: title, description, logo (SVG/PNG/WebP, relativ zum Projektstamm). Ohne Angaben kein zusätzlicher Kopf. |
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. Änderungen an project (Titel, Beschreibung, Logo) werden bei aktivem Gulpfile-Watch ohne IDE-Neustart übernommen. Nach dem Bearbeiten anderer IDE-Settings oder der Datei das µGulp™-Toolwindow neu öffnen (startet den Sidecar neu) bzw. microgulp-serve neu starten.
Projektidentität (project)
Optionaler kompakter Kopf über der Taskliste, damit bei mehreren offenen IDE-Fenstern sofort erkennbar ist, zu welchem Workspace die Tasks gehören:
{
"project": {
"title": "ESP][",
"description": "Apple II emulator for ESP32-S3",
"logo": "./assets/esp2.svg"
}
}
- Alle drei Felder sind optional; fehlende Metadaten lassen das bisherige Layout unverändert.
logo: relative Pfade zum Projektstamm; Formate SVG, PNG, WebP. Fehlende oder ungültige Dateien werden ignoriert (Header ohne Logo).- Tooltip am Kopf: Titel, Beschreibung (falls gesetzt) und absoluter Workspace-Pfad.
- Die Projektidentität erscheint in der Dashboard-Taskleiste und in der Web Console. Stream Deck zeigt Projektlogo und Titel auf der Root-Taste des Gruppenbrowsers; ohne verwendbares Logo erscheint eine Ersatzdarstellung. Logitech MX verwendet die vom verbundenen Host gelieferte Projektgrafik für Workspace-Auswahl und µGulp™-Taste; ohne verwendbare Grafik erscheint das Markenbild. Die vollständige Geräteabnahme steht aus. Für Flexbar wird keine Projektlogo-Anzeige zugesagt.
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/engineundsrc/workerkennen 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 Sidecarnpm run serve(src/host/microgulp-serve.mjs, NDJSON auf stdio) ist bereits vorbereitet. - Task-Preloading. Der
TaskWorkerPoolhä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 perawait 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. Die Auswahl gehört zum Projekt und ist in VS Code, Cursor, JetBrains und CLI identisch:
- Expliziter Override der IDE oder CLI: VS-Code-/Cursor-Einstellung, JetBrains Settings → Tools → µGulp oder
microgulp-serve --gulpfile/--gulpfile-pattern. Ein leeres Feld ist kein Override. microgulp.config.jsonim Projektstamm (gulpfileodergulpfilePattern).- Standard:
gulpfile.mjsim Projektstamm, sonst Discovery über(^|/)gulpfile\.(m|c)?js$.
Auf jeder Ebene hat ein Muster Vorrang vor einem Einzelpfad. Ein Einzelpfad außerhalb des Projektstamms wird abgelehnt; eine fehlende Datei fällt mit Warnung auf die nächste Ebene zurück.
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$findetgulpfile.mjs/.js/.cjsim Stamm und in jedem Unterordner.microgulp.gulpfilePath- expliziter Einzelpfad; standardmäßig leer, damitmicrogulp.config.jsongilt.
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 |
Der Gruppen-Header zeigt außerdem, was er verbirgt: Er übernimmt die bernsteinfarbene Aufmerksamkeits-Markierung, sobald ein Task darin µAttention meldet, und wird blass, wenn alle enthaltenen Tasks über µEnabled deaktiviert sind. Beides gilt auch bei zugeklappter Gruppe.
Startzustand der Gruppen (µGroups)
Lange Task-Listen sind mit geschlossenen Gruppen übersichtlicher. Der optionale Modul-Export µGroups bestimmt, wie die Liste beim ersten Aufbau aussieht - global und je Gruppe. Ohne ihn bleibt alles aufgeklappt, jede Gruppe bleibt von Hand bedienbar, und ein manueller Klick hat für den Rest der Sitzung Vorrang vor der Deklaration.
// Kurzform: alle Gruppen starten zugeklappt
export const µGroups = 'collapsed';
// Vollform: globaler Standard plus Ausnahmen je Gruppe
export const µGroups = {
collapsed: 'all', // 'all' | 'none' (oder true / false)
groups: {
'Demo': 'open', // startet aufgeklappt
'Build/Production': true, // startet zugeklappt
},
};
Die Schlüssel sind µGroup-Pfade und dürfen den <context="…"/>-Tag enthalten; Groß-/Kleinschreibung und Leerzeichen spielen beim Vergleich keine Rolle. Der am tiefsten passende deklarierte Vorfahre gewinnt, danach greift der globale Standard - 'Build' deckt also auch 'Build/Production' ab, solange dieses Kind nicht eigens deklariert ist. Die Schlüssel sind Bezeichner und kein sichtbarer Text, sie werden deshalb nicht mit .i18xRegister() registriert.
µ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.
Lange Optionslisten (select / radio / checkbox) sind erlaubt: Der Host hält standardmäßig bis zu 5000 Einträge pro Feld (Override MICROGULP_MAX_SELECT_OPTIONS; 0 = unbegrenzt). Wird gekürzt, warnt das Dashboard sichtbar - stilles Abschneiden entfällt. Ab 24 Optionen erscheint ein Filterfeld. Ad-hoc-RequestForm aus gulp-mu-gulp-api hat kein Host-Cap auf der Live-Payload; dieselben Feldtypen und der Filter gelten auch dort.
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().
Task zur Aufmerksamkeit hervorheben (µAttention)
Ein Task kann in der linken Spalte pulsen, wenn er einen Blick braucht (fehlende Installation, Versionsunterschied, veraltete Ausgabe):
DEPLOY.µAttention = () => installed !== current;
DEPLOY.µAttentionTooltip = 'Cursor has V<installed/>; workspace is V<version/>.<context="µAttentionTooltip"/>'.i18xRegister();
DEPLOY.µInstalledVersion = () => installed || '-';
| Eigenschaft | Bedeutung |
|---|---|
µAttention |
true oder eine Funktion, die true liefert, hebt die Zeile hervor (amber Puls + Punkt). Standard aus. Gleiches Factory-Muster wie µEnabled. |
µAttentionTooltip |
Optionale extra Tooltip-Zeile, die während der Hervorhebung zuerst erscheint. Mit .i18xRegister(). |
µInstalledVersion |
Optionaler String oder Factory für den Platzhalter <installed/> |
µAttentionWatch |
Optionale Trigger, die nur die Factory neu auswerten: Pfad, Pfadliste oder { files, intervalMs }. ~/… ist erlaubt. Startet den Task nie. |
Nach einer Änderung des Zustands, der µAttention treibt, NotifyTasksChanged() aufrufen. Optionales µAttentionWatch wertet die Factory neu aus, ohne den Task zu starten - Workspace-Dateien, ~/…-Pfade oder ein intervalMs-Poll (für Ordner außerhalb des Projekts, etwa das Cursor-Erweiterungsverzeichnis). Anders als µWatch startet ein Treffer den Task nie.
INSTALL.µAttention = () => installed !== current;
INSTALL.µAttentionWatch = { files: ['~/.cursor/extensions'], intervalMs: 8000 };
PUBLISH.µAttentionWatch = ['website/en/index.html', 'RELEASES.json'];
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.µShortDisplayName = 'CSS, Build Styles<context="µShortDisplayName"/>'.i18xRegister(); // Optionaler Kurztext für Stream Deck und Logitech MX
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();
µShortDisplayName ist eine optionale i18x-Phrase für knappe Hardware-Beschriftungen. Sie ändert weder den Dashboard-Anzeigenamen noch die Task-ID. Bei Bedarf kann sie „Kurztext, Originaltext“ enthalten, etwa CSS, Build Styles. Das Kontext-Tag µShortDisplayName gehört nur in die i18x-Quellphrase; der Host entfernt es vor der Ausgabe. Auf dem Gerät erscheinen keine Tags.
Kontext-Tags, Pflicht-Formate und Sprachkontingent: dev/docs/MicroGulpI18xProfile.md.
Task-Darstellung und Steuerung aus dem Gulpfile
µGulp™ zeigt für jeden Task, ob er inaktiv oder deaktiviert ist, startet, läuft, auf eine Eingabe wartet, stoppt, erfolgreich beendet wurde oder fehlgeschlagen ist. Der Zustandsrahmen bleibt auch bei eigenen Icons sichtbar. Eine offene Eingabe erhält zusätzlich ein violettes Dialogsymbol; die Antwort erfolgt im Dashboard.
Für die semantische Darstellung stehen 38 SVG-Icons zur Verfügung. µTaskKind und µPresentation beschreiben die Aufgabe, zum Beispiel Build, Test, Kopieren oder Veröffentlichen. Die Icons folgen dem Theme, können im Theme ersetzt werden und unterstützen reduzierte Bewegung. Laufanimationen zeigen Aktivität; bei einem Fehler geht das ursprüngliche Motiv in eine verkohlte Darstellung über. Eigene µIcon- und µIconFont-Angaben bleiben erhalten.
Ein dauerhaft laufender Dienst wird mit µExecutionType = 'persistent' gekennzeichnet und kann wieder gestoppt werden. Das ist unabhängig von µWatch, das einen Task bei Dateiänderungen erneut startet, und von µAttention, das Handlungsbedarf markiert. Mit µAttentionWatch lässt sich dieser Hinweis bei Dateiänderungen oder in einem Intervall neu bewerten, ohne den Task auszuführen.
Auch die Task-Übersicht lässt sich aus einem Gulp-Task heraus steuern:
import { SetGroupState, RevealTask, SetTaskEmphasis } from 'gulp-mu-gulp-api';
SetGroupState('Build', 'open');
RevealTask('PUBLISH_NPM', { expand: true, scroll: true, highlight: 'attention' });
SetTaskEmphasis('PUBLISH_NPM', null);
µGroups legt den Startzustand fest; spätere Gruppenänderungen gelten für die Sitzung. Hervorhebung und Laufstatus bleiben unabhängig voneinander: Ein laufender Task kann gleichzeitig Aufmerksamkeit verlangen. Dashboard und Hardware erhalten denselben Taskzustand. Das Öffnen einer Gruppe im Dashboard ist kein Start ihrer Tasks.
IDE-Aktionen aus Tasks
Gulp-Tasks importieren Ide aus gulp-mu-gulp-api. Der implementierte 1.0.0-Umfang umfasst acht Funktionen:
| Funktion | Aufgabe |
|---|---|
Ide.Capabilities() |
Hostfamilie, Edition, unterstützte Operationen und semantische Aktionen abfragen; auch bei gesperrten ausführenden Funktionen verfügbar |
Ide.Projects() |
Bekannte Projekte, lebende Sitzungen und konfigurierte Anwendungsauswahl abfragen |
Ide.Action(id) |
Eine semantische Aktion im aktuellen IDE-Host ausführen |
Ide.OpenProject(request) |
Ein bekanntes Projekt in der gewählten Installation öffnen oder seine konkrete Sitzung fokussieren |
Ide.StartApplication(applicationId) |
Eine bekannte oder explizit konfigurierte lokale Anwendung starten |
Ide.Execute({ vscode, jetbrains, args }) |
Den für die aktuelle Hostfamilie angegebenen nativen Befehl ausführen |
Ide.Vscode.ExecuteCommand(commandId, ...args) |
Einen freigegebenen VS-Code-/Cursor-Befehl ausführen |
Ide.JetBrains.ExecuteAction(actionId) |
Eine freigegebene JetBrains-Aktion ausführen |
Der gemeinsame Aktionskatalog für Ide.Action enthält open-settings, save-all, open-terminal, open-problems, find-in-project, quick-open, command-palette, next-editor, previous-editor, run und debug. Run/Debug verwenden die aktuelle native Konfiguration. Die Verfügbarkeit hängt von IDE, installierten Plugins und freigegebenen Befehlen ab; der Katalog garantiert keine identischen Fähigkeiten aller JetBrains-Produkte.
Ide.OpenProject übernimmt projectId aus Ide.Projects().result.projects und beispielsweise applicationId aus der zurückgegebenen Anwendungsauswahl. Für eine konkrete Sitzung werden sessionId und connectionId gemeinsam übergeben. Veraltete Ziele werden abgelehnt, nicht durch eine andere Sitzung ersetzt.
µHost kennzeichnet die benötigte IDE-Familie, µIdeApi = true Tasks, die diese Schnittstelle benötigen. Die Engine prüft Edition, Registrierung und erlaubte Befehle. In µGulp™ Free bleibt Ide.Capabilities() als Abfrage verfügbar; die übrigen sieben Funktionen sind gesperrt, auch Ide.Projects(). Davon unabhängig bleibt die lesbare Projektübersicht der Web Console verfügbar.
Die Aufrufe liefern ein Promise mit { ok, result } oder { ok: false, code, message }. Ohne µGulp™-IPC, etwa unter der normalen gulp-CLI, liefern alle acht unsupported-host; sie starten dort keine IDE. Eine fehlende Editions- oder Registrierungsfreigabe wird als unsupported-edition bzw. unsupported-registration zurückgemeldet. Für CLI und CI kann das Gulpfile einen eigenen Ersatzweg anbieten.
Der API-Umfang beschreibt die Implementierung im Repository, nicht die Verfügbarkeit in einer bereits veröffentlichten npm-Version. Ide.OpenUrl ist nur geplant und nicht verfügbar.
Hardware-Integrationen
Tasks lassen sich über Elgato Stream Deck und Stream Deck Mobile, Logitech MX Creative Console und Actions Ring sowie ENIAC Flexbar bedienen. Die Hardware-Funktionen sind in allen Versionen außer µGulp™ Free enthalten. Für JetBrains gibt es keine Free-Version.
µGulp™ legt nicht nur ein statisches Icon auf eine Taste. Live Animated Task States bedeuten: Die Darstellung folgt dem tatsächlichen Laufzeitzustand derselben Engine wie im Dashboard (inactive → starting → running → finished bzw. failed, plus disabled, waiting-for-input, stopping). Während Start/Lauf/Stop/Eingabe läuft die Animation; Erfolg und Fehler werden kurz sichtbar (Fehler inkl. Burn→Charred). µWatch bleibt ein separates Ein/Aus-Overlay; Session-Schedules können Countdown bzw. n/m am Key ergänzen. (Actions Ring: nur Titel, SDK ohne LCD-Animation.) Vertrag und Zustandsliste: TaskPresentationAndHardware.md.
Die Verbindung zum jeweiligen Workspace wird im Dashboard unter Einstellungen → Hardware integrations aktiviert. Das passende Geräteplugin verbindet die Tasten mit den Tasks dieses Projekts. Laufende Dienste lassen sich stoppen, Eingabeanforderungen werden im Dashboard beantwortet.
Kontextbewusste Controller-Oberflächen
µGulp™ verwendet einen gemeinsamen aktiven Projektkontext für Visual Studio Code, Cursor und JetBrains. Stream Deck stellt die letzte Ansicht je Workspace und Gerät wieder her. Logitech behält die bestehende dynamische Workspace-Auswahl; sein Ordner ist prozessweit. Flexbar folgt dem IDE-Projekt nicht automatisch.
Das aktive Projekt ist gemeinsam, die Stream-Deck-Ansicht wird je Gerät gespeichert. Bei einer fremden Vordergrundanwendung gibt µGulp™ ein von ihm geöffnetes Browser-Profil an Stream Deck zurück. Welches Default- oder Smart Profile danach erscheint, hängt von Elgato und der Benutzerkonfiguration ab; eine garantierte Smart-Profile-Umschaltung wird nicht zugesagt.
Beispiel:
Cursor: microGulp
MX -> Build
Stream Deck -> Release
Alt-Tab
JetBrains: BlueShift
MX -> Build
Stream Deck -> Test
Alt-Tab
VS Code: ESP][
MX -> Upload
Stream Deck -> Monitor
Die Rückkehr zu einem IDE-Fenster stellt auf dem Stream Deck die zuvor genutzte Ansicht dieses Workspace wieder her. Geräteansichten sind getrennt gespeichert; eine physische Abnahme mit mehreren Stream Decks steht noch aus.
Fehlt eine Gruppe nach einer Gulpfile-Änderung, fällt die Wiederherstellung auf den nächsten noch gültigen Elternknoten oder auf die Projektwurzel zurück. Der Schalter Follow active IDE project steht standardmäßig an. Eine manuelle Workspace-Wahl am Logitech-Keypad hat Vorrang. Technische Grenzen: Aktives IDE-Projekt folgen.
Elgato Stream Deck und Stream Deck Mobile
Follow und Profile: Bei aktivem Follow active IDE project übernimmt µGulp™ das fokussierte IDE-Projekt mit verfügbarer Hardwareverbindung und kann dessen mitgeliefertes Browser-Profil öffnen. Ist es bereits sichtbar, wechselt nur der Projektinhalt. Beim Verlassen des IDE-Kontexts wird ein von µGulp™ geöffnetes Profil zurückgegeben. Elgato Smart Profiles können zusätzlich in Stream Deck konfiguriert werden; ihre Aktivierung wird von µGulp™ nicht garantiert. Details und Fehlersuche: Stream Deck.
Gruppenbrowser: Open µGulp™ Group auf einem anderen Profil (z. B. Default) öffnet den Browser mit dynamischen Gruppen und Tasks. Diese Aktion öffnet die konfigurierte Startgruppe. Follow und eine als Einstieg verwendete µGulp™ Group Slot-Taste stellen dagegen die gespeicherte Ansicht des aktiven Workspace wieder her; ohne gespeicherte Ansicht beginnt eine neue Sitzung an der Projektwurzel. Blättern, Zurück und Root folgen dem Navigationsraster. Die Root-Taste zeigt Projektlogo und Titel mit erhaltenem Seitenverhältnis; ohne verwendbares Logo erscheint eine Ersatzdarstellung. Zurück an der Projektwurzel verlässt den Browser. Stream Deck Mobile wählt die Vorlage nach der Rastergröße (u. a. 3×2 und 5×3).
Feste Einzel-Task-Zuweisung: µGulp™ Task auf eine beliebige Taste ziehen, Workspace und Task wählen. Namen, animierte Laufzustände und Icons kommen aus dem verbundenen Workspace. Stream Deck Mobile verwendet dieselbe Integration.
Technische Details und Vorlagenliste: Stream Deck, Vertrag Device-Gruppen-Navigation.
Logitech: einzelne Tasks oder ein Profil für die App
Für Logitech gibt es zwei Einrichtungswege:
- Einzelne Tasks separat zuweisen: Mit Start a Single µGulp™ Task einen Workspace und einen Task fest an eine Taste binden. Das gilt für einzelne Keypad-Tasten und den Actions Ring (nur Titel, SDK ohne LCD-Animation). Der Keypad-Ordner zeigt Icons und Laufzustände.
- Ein App-Profil in Options+ einrichten, zum Beispiel für Cursor: Die dort konfigurierte Tastenbelegung wird automatisch aktiv, wenn die App im Fokus ist. Auf dem Keypad öffnet General µGulp™ Functions die Tasks des passenden Workspace mit Icons und Live-Laufanzeige. Das µGulp™-Plugin folgt innerhalb der IDE dem fokussierten Workspace; eine manuelle Workspace-Auswahl bleibt bis zur Freigabe der Auswahl oder bis zum Verbindungsverlust bestehen.
Options+ wählt also die Tastenbelegung für die App, µGulp™ den Workspace. Das Profil wird einmal in Options+ eingerichtet. Nach einem App-Wechsel kann der dynamische Ordner geschlossen sein; ein Druck auf die µGulp™-Taste öffnet ihn wieder. Der Actions Ring nutzt die feste Einzel-Task-Zuweisung; die dynamische Liste mit Task-Icons gehört zum Keypad.
Die Projektgrafik für Workspace-Auswahl und µGulp™-Taste ist in Logitech MX implementiert; sie kommt vom verbundenen Host, mit Markenbild als Ersatz. Die vollständige Geräteabnahme steht aus. Programmatisches Öffnen des Dynamic Folder und unabhängige Navigation mehrerer physischer MX-Geräte sind nicht zugesichert; die SDK-Fragen bleiben offen. Der vorhandene Logitech-Umfang bleibt eingeschränkt und experimentell.
ENIAC Flexbar
Das Flexbar-Plugin verbindet die in FlexDesigner konfigurierten Aktionen mit µGulp™-Tasks und deren Laufzuständen (gleiche State-Semantik wie Stream Deck). Der Test mit konkreter Flexbar-Hardware steht noch aus.
Technische Einrichtung und Plugin-Builds: Stream Deck, Logitech, Flexbar.
Task-Scheduler (Session)
Session-Zeitpläne entscheiden nur wann ein Task startet; die Ausführung bleibt der normale StartTask-Pfad (Dashboard-Sektor, Logs, Hardware-Zustände unverändert).
| Modus | Deklaration | Kurz |
|---|---|---|
| Timer | µSchedule = { after: '10s' } |
einmal nach Dauer |
| Intervall | { every: '10s' } |
wiederholt; nextRun nach jedem Lauf |
| Wiederholung | { every: '5s', repeat: 5 } |
nach n Läufen completed |
| Cron | { cron: '*/1 * * * *' } |
5 Felder, Host-Lokalzeit (croner) |
Imperativ: ScheduleTask, SetScheduleEnabled, CancelSchedule, RunScheduleNow (gulp-mu-gulp-api). Dashboard: Countdown aus nextRun, Enable/Disable/Cancel/Run now. Solange µWatch scharf oder der Task läuft, wird ein geplanter Start übersprungen (schedule-skipped). Hardware-Keys können Countdown bzw. n/m als Overlay zeigen. Details und Demo A-G: TaskScheduler.md.
Controller, Gamepads und Joysticks
Gamepads, Joysticks und andere kompatible Eingabegeräte lassen sich als frei belegbare Workflow-Steuerung nutzen. Unter Einstellungen → Controllers wird die Unterstützung eingeschaltet; die Konfiguration bietet Profile, das Einlernen von Tasten und Achsen, Totzonen, Empfindlichkeit sowie eine Live-Diagnose. Belegungen können Tasks starten oder stoppen und die Task-Übersicht steuern.
Auf Windows x64 läuft die Eingabeerkennung auch ohne Fokus auf dem Dashboard. Ein installiertes Node.js ab Version 22 ist dafür erforderlich. Für andere Desktop-Plattformen sind die nativen Controller-Komponenten noch nicht enthalten; in unterstützten Browsern steht die Gamepad-API als Ersatzweg zur Verfügung.
Für die 3Dconnexion SpaceMouse Wireless gibt es ein am Gerät ermitteltes Profil mit sechs Achsen und zwei Tasten. Andere Geräte lassen sich über die Kalibrierung und eigene Belegungen einrichten. Unterstützt der Controller Vibration, können optionale Rückmeldungen beispielsweise Taskstart, Erfolg oder Fehler signalisieren. Umfang und Wirkung hängen vom jeweiligen Gerät ab.
Einrichtung, Geräteprofile und Diagnose: Controller-Dokumentation.
Gulpfile-Migration mit KI
Zum Umbau eines bestehenden Gulpfiles (Konsolenausgabe, Task-Metadaten, i18x/gulp-Wörterbücher, optional µKeyBinding / µParameters / µWatch / µAutoClose, sowie optionale Projektidentität in microgulp.config.json) liegt ein gepflegter Prompt im Repository:
| Datei | Zweck |
|---|---|
dev/prompts/OptimizeGulpfileForMicroGulp.md |
Copy-Paste-Prompt für Cursor, Claude, ChatGPT, … (Erstumstellung) |
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json |
Parameter-Vorlage (Projektpfad, Gulpfile-Name, unterstützte Sprachen, gulp-mu-gulp-api-Version) |
dev/prompts/EnhanceExistingMicroGulpProject.md |
Bestehendes µGulp™-Projekt auf optionale neuere Möglichkeiten prüfen (keine Blind-Aktivierung) |
Der Umstellungsprompt berücksichtigt jetzt auch µTaskKind, µPresentation, µExecutionType, µAttentionWatch, das Warten auf Eingaben und eine sinnvolle project-Identität (Titel / Mini-Beschreibung / vorhandenes Logo, Config nur mergen). Bestehende µIcon-Glyphen und µIconFont-Zuordnungen bleiben erhalten. Der Core verwaltet Laufzustände; dauerhafte Dienste, Dateitrigger und Aufmerksamkeit bleiben getrennt. Die Hardware-Integrationen werden je Workspace aktiviert und sind in allen Versionen außer µGulp™ Free enthalten; bei Flexbar steht der Test mit konkreter Hardware aus. Die benötigten Produkt- und API-Versionen vor der Migration mit dem aktuellen Stand des Projekts abgleichen.
Der Prompt verlangt außerdem i18x-formatierte Werte: int für Zähler, floatFix1/floatFix2 für Dezimalzahlen, byteSize für Bytes, progressDuration für Millisekunden und die Datums-/Zeitformate. Für strukturierte Ausgaben steht FormatValue() bereit. Projektwörterbücher werden mitsamt den passenden <format>-Definitionen aktualisiert; bestehende Übersetzungen bleiben erhalten. Die vorläufigen Grenzen der eigenen Engine werden berücksichtigt.
Für Gruppierung und Taskbaum behandelt er µGroup, µOrder, µGroups sowie SetGroupState, RevealTask und SetTaskEmphasis. Die Hardware-Hinweise erklären den Stream-Deck-Gruppenbrowser (Einstiegstaste und dynamische Slot-Profile) sowie feste Logitech-Tasks einschließlich Actions Ring und Options+-App-Profile mit Workspace-Auswahl durch µGulp™.
Ablauf
- Parameter-Beispiel ins Projektstammverzeichnis kopieren als
microgulp-optimize.params.jsonund ausfüllen:projectRoot,gulpfilePath,supportedLanguages(z. B.en-US,de-DE,zh-CN),gulpMuGulpApiVersion(^0.6.0; installierte/veröffentlichte Version prüfen),microGulpMinVersion(1.0.0), sowiegithubRepoUrl/githubRef(Standard:https://github.com/mamekudz/microGulp, ein geprüfter Ref wiemain). - Prompt-Markdown öffnen,
{{PLACEHOLDER}}-Tabelle mit den Werten ersetzen (oder in Cursor Params-Datei und Gulpfile anhängen). - 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. - Prüfen mit
node --check gulpfile.mjs, Tasks im µGulp™-Dashboard testen (inkl. neuer Tastenkürzel bei Dashboard-Fokus), danngulpfile.mjs,i18x/gulp/*.jsonundpackage.jsoncommitten.
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) |
Die Gruppe Scheduler demos (A-G) zeigt Session-Zeitpläne (µSchedule): einmaliger Timer, Intervall, Wiederholung, Cron, Überlappungs-Skip, geplanter Fehler sowie Watch+Schedule. Alle Demo-Zeitpläne starten deaktiviert (autoStart: false) - einzeln per Icon-Button scharfschalten. Details und API: dev/docs/TaskScheduler.md.
Weitere API-Details: gulp-mu-gulp-api/README.md.
µGulp™ Ready
Ein Projekt bietet bewusst mindestens eine nützliche µGulp™-spezifische Bedienung oder Ausgabe, dokumentiert den normalen Gulp-/CLI-Weg und prüft beide Wege selbst. Bloße Gulp-Kompatibilität oder dekorative Metadaten reichen nicht. Das Badge ist nach den veröffentlichten Regeln kostenlos nutzbar; es gibt keinen Antrag und keine offizielle Zertifizierung.
Anforderungen, Selbsterklärung und Badge-Nutzung.
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 (TaskSHOW_VERSION_HISTORYbzw.npm run history).BUILD_PACKAGEsynchronisiert diepackage.json-Version und die Versionszeile am Kopf dieses READMEs automatisch ausRELEASES.jsonund 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 inRELEASES.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 deploy:developer |
DEPLOY_DEVELOPER |
Baut die unveröffentlichte Developer-Ausgabe (microgulp-internal), installiert sie in Cursor, hebt sie bei Versionsunterschied hervor und bietet Reload Window an |
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-cssist als lokalefile:-Abhängigkeit aufC:\Projects\microCSS\gulp-mu-csseingebunden und wird - wie alle schweren Pakete - erst im Task-Body perawait import()geladen.BUILD_PACKAGEerzeugt ein echtes.vsix, sobald@vscode/vsceinstalliert 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_DATAerkennt 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 handgeschriebenedashboard.cssbleibt 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 istdev/media/final/; der Build synchronisiert darausmedia/logo.png(Extension-Icon),media/logo_readme.png(README),src/webview/skins/<name>/imgs/baselogo.svg(Dashboard) undjetbrains/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 sowie Countdown, eigene Icons, Fehlerdarstellung, persistenter Dienst und Attention/Reset) 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
Bereits 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 überi18x-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, Ordner, 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.jsonfü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 indev/docs/MicroGulpSoundSchema.md[x] Projektidentität (
project.title/description/logoinmicrogulp.config.json; kompakter Kopf in der Taskleiste)[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 Taskfü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:-1offen halten, positive Sekunden, sonst Einstellungen)[x] Aufmerksamkeits-Hervorhebung (
µAttentionPuls + Punkt; optionalµAttentionTooltip/µInstalledVersion)[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.jsonfür KI-Übersetzung)[x] Einheitliche Task-Zustände, 38 semantische Icons, Eingabeanzeige, Theme-Fallback und reduzierte Bewegung
[x] Taskbaum und Hervorhebungen über
SetGroupState,RevealTaskundSetTaskEmphasis[x] Acht IDE-API-Funktionen sowie sichtbare Host-/Verfügbarkeitskennzeichnungen
[x] Web Console, KnownProjectRegistry / Project Center, Open/Focus Project und gemeinsamer Background Host
[x] Stream Deck: Follow, letzte Ansicht je Workspace und Gerät sowie Projektlogos auf der Root-Taste
[x] Stream-Deck-/Mobile-, Logitech- und Flexbar-Integration; Logitech mit Einzel-Task-Zuweisung und dynamischem Keypad-Ordner
[x] Controller-Profile mit Kalibrierung und Diagnose; Desktop-Eingabe unter Windows x64 und SpaceMouse-Wireless-Profil
Noch offen
[ ]
Ide.OpenUrlund IDE-lose Task-Ausführung über den Background Host: geplant, nicht Teil des implementierten 1.0.0-Umfangs[ ] Logitech MX: physische Abnahme einschließlich Projektgrafik sowie offene SDK-Fragen zu Dynamic Folder und Mehrgerätebetrieb
[ ] Stream Deck: physische Mehrgeräteabnahme und Zusammenspiel mit Elgato Smart Profiles
[ ] Flexbar: Test mit konkreter Hardware
[ ] Native Controller-Komponenten für Linux und macOS
[ ]
µ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.mjsausµLibum 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)
[x] JetBrains-Marketplace-Eintrag (Plugin 34255; Registry-Verfügbarkeit ist keine geprüfte Frischinstallation in jeder IDE)
[x] VS-Code-/Cursor-Einträge im Microsoft Marketplace und auf Open VSX (registriert und Free)
Web Console und Projektzentrale
Die lokale Web Console führt bekannte und verbundene Projekte im Project Center zusammen. Sie bettet das vorhandene Dashboard mit Tasks, Project Controls, Parametern, Historie und Live-Ereignissen ein; sie erzeugt keine zweite TaskEngine. Start über µGulp: Open Web Console in VS Code/Cursor, Open Web Console im JetBrains-Toolwindow oder npm run console -- open im Entwickler-Checkout. Die Console verwendet lokales HTTP/SSE ohne Browser-Plugin und hört nur auf 127.0.0.1; sie ist kein LAN- oder Fernzugang.
Bekannte Projekte und Sitzungen
Die KnownProjectRegistry speichert Projektpfad, ProjectId, Titel, Beschreibung, Logo, bevorzugte IDE und letzten Sichtkontakt unter ~/.microgulp/known-projects.json. Die Übersicht unterscheidet verbunden, geschlossen und nicht verfügbar. Ein bekannter Eintrag ist keine laufende Engine. Lebende IDE-Sitzungen werden getrennt geführt; mehrere Fenster desselben Projekts sind einzeln auswählbar.
Follow active IDE project folgt dem gemeinsamen aktiven Projektkontext. Eine manuelle Sitzungswahl hält die Auswahl nur in diesem Browser-Tab fest und verändert den Controller-Pin nicht. Bei einer fremden Vordergrundanwendung bleibt die zuletzt dargestellte Sitzung sichtbar, solange sie noch lebt.
Die Übersicht und das eingebettete Dashboard bleiben in µGulp™ Free erreichbar; normale Task-Berechtigungen gelten weiterhin. Auch die Host-Verwaltung bleibt nutzbar. Open/Focus Project, Start Application, IDE-Aktionen und das Setzen der bevorzugten IDE werden dagegen serverseitig pro Aufruf auf Editions- und Registrierungsfreigabe geprüft.
Projekte öffnen und fokussieren
Open/Focus Project verwendet die gewählte IDE-Familie, das konkrete Produkt und dessen Installation. Gibt es eine passende Sitzung, wird ihr Fenster fokussiert. Mehrdeutige Treffer verlangen eine Sitzungswahl. Ein Fokusfehler löst keinen zweiten IDE-Start aus; exakter Fensterfokus ist derzeit Windows-spezifisch. Ohne passende Sitzung wird das bekannte Projekt in der gewählten Installation geöffnet. Parallele Anforderungen werden zusammengefasst; bleibt die Startbestätigung aus, ist ein ausdrücklicher Wiederholungsversuch nötig.
Bekannte Windows-Benutzerinstallationen werden erkannt; weitere IDE-Installationen und Anwendungen lassen sich in ~/.microgulp/applications.json konfigurieren. Start Application startet eine dort bekannte Anwendung ohne Shellbefehl. Allgemeines Fokussieren beliebiger Fremdanwendungen gehört nicht zum Funktionsumfang. Windsurf-Erkennung ist experimentell und keine Freigabe einer weiteren IDE.
Background Host
Web Console, bekannte Projekte, aktives Projekt und Controller-Kontext stellt ein gemeinsamer Background Host bereit - ein Prozess pro Benutzer, unabhängig von der IDE. Die erste IDE startet ihn bei Bedarf; das Schließen einer IDE beendet ihn nicht. Optional startet er bei der Anmeldung, sodass die Web Console schon ohne geöffnete IDE unter http://127.0.0.1:47821/console erreichbar ist. Ohne IDE zeigt sie bekannte Projekte; mit passender Editionsfreigabe lassen sie sich in Cursor, VS Code oder JetBrains öffnen. Tasks werden über eine verbundene IDE-Sitzung bedient. IDE-lose Task-Ausführung und automatischer Engine-Owner-Wechsel sind nicht Bestandteil von 1.0.0.
Einstellungen gelten für alle IDEs gemeinsam und liegen nur in host-settings.json: Start at login und Show background UI sind unabhängig. Die Oberfläche auszublenden beendet den Host nicht. Der Port gilt global (Standard 47821, gültig 1024 bis 65535). Eine Änderung startet den laufenden Host neu; die Web Console wechselt auf die neue Adresse. Belegt eine andere Anwendung den Port, bleibt der bisherige Port erhalten. Es gibt keinen Zufallsport und kein Feld für die Bind-Adresse: der Host hört nur auf 127.0.0.1.
Beim ersten Start fragt µGulp™ einmal für den Benutzer, nicht je IDE: Enable µGulp™ Background Host? Enable schaltet den Start bei der Anmeldung ein. Not now lässt ihn aus; eine IDE darf den Host weiterhin bei Bedarf starten.
Dieselbe Bedienung gibt es in VS Code und Cursor (µGulp: Background Host Settings), in JetBrains (Settings → Tools → µGulp Background Host und Background Host im Toolwindow), im Bereich Background Host der Web Console und über npm run console -- status|open|restart|stop|port <n>|autostart on|off|ui on|off. Das Windows-Infobereichsmenü öffnet die Web Console, zeigt Status, verbundene IDEs und bekannte Projekte und schaltet den Start bei der Anmeldung. Den Port ändert man dort nicht.
| Plattform | Autostart | Systemoberfläche |
|---|---|---|
| Windows | Anmeldeeintrag des Benutzers | Infobereich (optional, headless bleibt gültig) |
| macOS | LaunchAgent | Menüleiste vorbereitet, noch nicht auf macOS-Hardware geprüft |
| Linux | XDG-Autostart | headless; keine Tray-Abhängigkeit |
Die Console-Texte liegen derzeit auf Deutsch und Englisch vor; weitere Sprachen fallen auf Englisch zurück. Die Host-Bedienung hat eigene lokalisierte Texte. Den vollständigen implementierten Task-API-Umfang beschreibt IDE-Aktionen aus Tasks.
Français
Rock your Gulp!
µGulp™ ajoute à Gulp un tableau de bord interactif pour VS Code, Cursor et les IDE JetBrains. Vos tâches gagnent des noms dynamiques, des groupes clairs, des icônes, descriptions et infobulles. Vous voyez quelle tâche correspond à quel projet et cible, si elle s'exécute et si elle a réussi. Formulaires, progression et sorties séparées en direct accompagnent l'exécution. La CLI Gulp classique reste disponible ; paquets nécessaires et valeurs d'entrée adaptées restent requis. IA et MCP sont facultatifs.
Pour commencer : installer l'extension de votre IDE, ouvrir un projet avec un gulpfile et lancer une tâche dans le tableau de bord µGulp™. Node.js 22 ou ultérieur et les paquets du projet sont nécessaires. Gulp est un outil JavaScript pour les tâches récurrentes ; le gulpfile décrit ces tâches. µGulp™ ajoute leur interface de commande.
Points forts
État au 20 octobre 2026, version 2.1.0 : vérification locale en cours, pas encore publiée. Les tâches globales, le parcours de prise en main adapté et la présentation des tâches de projet sont implémentés. Les validations précédentes restent associées à leurs versions respectives ; la réussite d'un test partiel ne constitue pas une validation complète. Les parcours vérifiés et leurs limites sont documentés ci-dessous.
- NOUVEAU dans la version 2.1.0 : Rendre les tâches de projet compréhensibles - choisissez la langue d'édition, demandez à votre agent IDE existant de proposer les textes sources anglais et les traductions manquants, puis vérifiez directement les symboles ou vos propres images. Le Gulpfile reste en en-US ; les traductions vont dans
i18x/gulp/<sprache>.json. L'aperçu, la sauvegarde et l'annulation couvrent les deux fichiers. - Noms dynamiques, groupes, icônes et infobulles - des noms compréhensibles plutôt que de simples noms de fonctions ; valeurs actuelles du projet comme version ou cible, groupes imbriqués et repliables, icônes, descriptions et infobulles personnalisées.
µDisplayName,µGroup,µIcon,µDescriptionetµTooltipadaptent la liste au projet. Les textes peuvent être localisés ;µOrdertrie tâches et groupes,µGroupsfixe leur état initial. - Préchargement des tâches - les workers Node déjà initialisés ont importé le gulpfile et réduisent le temps de démarrage lorsqu’un worker préparé est disponible ; particulièrement utile pour les imports coûteux et les analyses antivirus en temps réel
- Les états des tâches en un coup d’œil - démarrage, exécution, attente d’une saisie, arrêt, réussite et échec ont une présentation cohérente ; les bordures d’état restent visibles avec les icônes personnalisées
- 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, …)
- 🔴 NOUVEAU dans la version 2.1.0 : Un point de départ adapté à votre Gulpfile existant - reconnaître les tâches déjà adaptées, compléter précisément les informations de présentation manquantes et vérifier chaque modification au préalable. Les autres recettes IA sont facultatives ; les raccourcis clavier manquants ne sont qu'une suggestion.
- 🔴 NOUVEAU dans la version 2.1.0 : Piloter plusieurs projets avec une tâche commune - lancer, par exemple, des sauvegardes NAS ou des vérifications de projets via un identifiant commun comme
NASBU. Sélectionnez précisément les projets à partir de leur titre et de leur icône, enregistrez leur configuration respective au préalable et vérifiez-la avant le lancement groupé. Chaque projet conserve sa propre implémentation, sa sortie et son historique. - 🔴 NOUVEAU en 2.0.0 : Assistant et recettes IA - ajouter des métadonnées par formulaire, intégrer sauvegarde NAS ou microCSS, préparer configuration initiale et publications GitHub/npm. Vérifier tous les fichiers en aperçu, appliquer avec sauvegarde et annuler si les fichiers restent inchangés. Les tâches préparatoires ne publient rien.
- 🔴 NOUVEAU en 2.0.0 : Groupes de projet et préparation des versions - classer sous nom du projet/Info, Build, Tools et Maintenance ; prévisualiser et appliquer ensemble l'augmentation npm et les lockfiles existants.
- 🔴 NOUVEAU en 2.0.0 : Connecter l'agent IA existant - configuration et maintenance par MCP dans Cursor ou IntelliJ, sans clé API µGulp™ supplémentaire par défaut. Cursor propose aussi l'assistant graphique dans le chat.
- 🔴 NOUVEAU en 2.0.0 : Traductions ciblées - proposer seulement les textes absents ou identifiés comme modifiés par comparaison dans des dictionnaires JSON plats, vérifier les espaces réservés et appliquer les changements validés avec sauvegarde et annulation. Vous choisissez les langues source et cible.
- 🔴 NOUVEAU en 2.0.0 : Aide à la maintenance des manuels - après modification du code, signaler les adaptations de votre DOCX avec preuves source. Vous choisissez document, langue et règles ; la rédaction reste votre responsabilité.
- Conserver les profils et rétablir la connexion - les profils 1.0.0 restent utilisables ; reconnecter le tableau de bord après l'arrêt du moteur IntelliJ, sélectionner la nouvelle session et vérifier de nouvelles propositions. Les tâches ne sont pas répétées automatiquement.
- Web Console et Project Center - projets connus avec titre, description, logo et état des sessions dans un centre local ; ouvrir les tableaux de bord existants dans le navigateur, suivre le projet IDE actif ou fixer une session uniquement pour cet onglet (vue d'ensemble et administration de l'hôte également dans Free)
- Open/Focus Project - ouvrir un projet connu dans une installation IDE précise ou activer sa fenêtre existante ; sélectionner explicitement la session s'il y en a plusieurs (hors Free ; activation exacte d'une fenêtre actuellement sous Windows)
- Background Host - Web Console et contexte du projet actif communs dans un processus par utilisateur ; démarrage à la connexion facultatif et paramètres partagés, même sans IDE ouvert ; l'hôte ne démarre pas lui-même de moteur de projet
- Identité du projet - titre de projet optionnel, mini-description et logo directement au-dessus de la liste des tâches ; particulièrement utile avec plusieurs projets ou fenêtres IDE ouvertes (
microgulp.config.json→project) - Project Controls - ligne compacte de listes, boutons radio et cases à cocher sous l'identité du projet pour son état global (par exemple la cible) ; effet immédiat sur les noms affichés, la visibilité des tâches/groupes et l'exécution ; valeurs par workspace dans
.microgulp/project-controls.json - États de tâche animés en direct - les périphériques compatibles (Stream Deck, keypad Logitech, Flexbar) affichent l’état d’exécution réel du même moteur que le tableau de bord, au-delà des icônes statiques : démarrage, animation pendant l’exécution, attente d’une saisie, arrêt, réussite, échec (Burn/Charred compris) et désactivation ; les bascules de surveillance et comptes à rebours du planificateur apparaissent en surimpression. L’animation indique l’état, elle ne décore pas. (absent de µGulp™ Free ; test matériel Flexbar en attente ; Actions Ring : titres uniquement, SDK sans animation LCD)
- 38 icônes de tâche sémantiques - illustrations SVG cohérentes via
µTaskKind/µPresentation, animations d’exécution, icône de dialogue violette lorsqu’une saisie est requise, adaptations au thème et prise en charge de la réduction des animations ; en cas d’échec, le dessin d’origine apparaît carbonisé - Planificateur de tâches (session) -
µSchedule/ScheduleTaskavec minuteries (after), intervalles (every), répétitions (repeat) et Cron (5 champs, heure locale) ; compte à rebours dans le tableau de bord et commandes Enable/Disable/Cancel/Run now ; le matériel affiche un compte à rebours oun/msur la touche. L’exécution suit toujours le chemin normal deStartTask - Contrôle des services persistants -
µExecutionTypedistingue les tâches ponctuelles des processus persistants ; les services en cours peuvent être arrêtés - Contrôle de l’arborescence des tâches depuis le gulpfile -
SetGroupState,RevealTasketSetTaskEmphasisdéploient les groupes, révèlent la prochaine étape et définissent ou retirent la mise en évidence - Surveillance live du gulpfile - le watcher du workspace rescane à l'enregistrement et remplace automatiquement les workers obsolètes
- Conserver la CLI Gulp - les métadonnées supplémentaires ne modifient pas les noms exportés. Les paquets API importés restent requis ; les entrées exigent des valeurs CLI ou des défauts adaptés, les actions IDE un hôte compatible (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 viai18x-catalogavec 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 packs d'interface téléchargeables et installables sont prévus pour la version 2.2.0. Le manuel utilisateur est disponible en PDF pour chaque langue d'interface fournie avec le 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>.jsonpour les langues choisies, conserve les traductions existantes et fusionne les formats standard ; un fichier satellite<lid>.status.jsonliste ce qu'une IA locale doit encore traduire - Paramètres de tâche déclaratifs -
µParametersdemande une fois avant l'exécution, transmet les valeurs commeMICROGULP_PARAMS/GetParameters(), mémorise les dernières réponses, tient les mots de passe hors des journaux et peut masquer des champs avecvisibleWhen - Tâches watch / déclenchement - les globs
µWatchlancent 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 - Prise en charge matérielle - Elgato Stream Deck, Logitech MX Creative Console / Actions Ring, Flexbar et manettes sont désormais pris en charge, pour un contrôle des tâches Gulp à un autre niveau. Inclus dans toutes les éditions sauf µGulp™ Free (configuration et état du périphérique).
- Logitech suit l’espace de travail - affectations fixes de tâches individuelles ou profil d’application Options+ ; le plugin affiche le contenu de l’espace de travail de la fenêtre IDE active dans le dossier dynamique du keypad
- Stream Deck suit le workspace - Follow reprend le projet de la fenêtre IDE active, mémorise la dernière vue par workspace et appareil et affiche son logo et son titre sur la touche Root. Le chemin de groupe et la page sont restaurés au retour. (Validation multi-appareils en attente ; Elgato Smart Profiles sans garantie. Logitech conserve son périmètre limité ; Flexbar ne suit pas automatiquement.)
- Des contrôleurs pour vos workflows - manettes et joysticks avec profils personnalisés, apprentissage des entrées, zones mortes et diagnostics ; sous Windows x64, ils fonctionnent aussi sans que le tableau de bord soit actif, avec un profil mesuré pour SpaceMouse Wireless et des vibrations facultatives sur les appareils compatibles
- Huit fonctions API IDE - consulter capacités et projets connus, exécuter des actions IDE sémantiques ou natives, ouvrir/activer des projets et démarrer des applications configurées ;
µHost/µIdeApiindiquent la disponibilité. Les fonctions exécutantes sont absentes de Free ;Ide.Capabilities()décrit les capacités de l'hôte (périmètre API). - Raccourcis de tâche - accords
µKeyBindingavec variantes par plateforme (ctrl+shift+F1,cmd+shift+Escape), badges et avertissements de conflit ;µGulp: Run Taskpour 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(.logbrut +.ndjsonstructuré), un indexhistory.ndjsonsurvit aux reconnexions/redémarrages de l'IDE ; un panneau d'historique du tableau de bord ouvre chaque transcription (logToFile,logRetention) - Sélection native de fichiers et dossiers - les champs de fichier des formulaires ouvrent le sélecteur de VS Code/Cursor ou JetBrains et renvoient le véritable chemin
- Dialogues modaux -
ShowModalMessage/ShowConfirmMessagecomme panneaux de verre style AiDPix dans le tableau de bord (info/avertissement/erreur, Oui/Non, OK/Annuler) ; modaux natifs VS Code/Cursor optionnels viapresentationoumicrogulp.modalPresentation(gulp-mu-gulp-api) ; section README dédiée - Emplacements d'erreur cliquables -
file:line:columndans 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/dashboardFontspour le glypheµIconet les polices du journal d'exécution ;µIconFontoptionnel 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(-1garder ouvert, un nombre positif = secondes, omis = Settings → Finished Runs, 30 s par défaut) ; Restart à côté de Close - Mise en évidence d’une intervention sans lancer de tâche -
µAttentionsignale le travail requis ;µAttentionWatchactualise le signal après une modification de fichier ou à intervalles réguliers, avec infobulle, version installée et indicateurs visibles même dans les groupes repliés - Élévation des privilèges administrateur Windows - demande UAC facultative par tâche (
µRequiresElevation,µElevationReason) ; l’IDE peut fonctionner normalement tandis que certaines tâches, comme la modification du fichierhosts, s’exécutent avec des privilèges élevés (absent de µGulp™ Free) - Moteur de diagnostic - les erreurs d’import et les traces de pile deviennent des suggestions utiles dans le tableau de bord (absent de µGulp™ Free)
<version/>depuis le gulpfile -µI18xContext.versionest la source préférée pour les titres de tâche ;versionSourcesoptionnel ne complète que lorsque le gulpfile ometversion(pas d'écrasement des configs de release du consommateur)- LogError fiable vs. avertissements Node -
LogError/ un vraiconsole.errorfont toujours échouer l'exécution ;DeprecationWarningNode 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/promptsredirigé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
Présenter les tâches de projet dans la langue souhaitée
Configurer les tâches du projet définit la présentation des tâches existantes dans le Gulpfile du projet sélectionné. Les tâches globales communes à plusieurs projets sont gérées séparément et ne sont pas modifiées par cet assistant.
La langue d'édition s'applique aux noms affichés, descriptions, infobulles et groupes proposés. Le sélecteur utilise la liste de langues maintenue de manière centralisée par le projet i18xe, avec les codes de langue et les noms natifs ; vous pouvez également saisir d'autres codes de langue BCP 47 valides. La sélection est préremplie à partir de microgulp.editingLanguage dans package.json. Si ce paramètre est absent, le formulaire utilise la langue du navigateur de la vue web de l'IDE. La langue de l'interface reste indépendante ; vous pouvez changer la langue d'édition avant chaque demande.
Préparer des suggestions de texte avec l'agent IDE crée une demande limitée aux champs de texte manquants. Le Gulpfile contient toujours les textes sources anglais en-US ; pour une autre langue d'édition, l'assistant ajoute les traductions correspondantes dans i18x/gulp/<sprache>.json. Les traductions existantes ne sont pas écrasées. Dans le tableau de bord, copiez la demande affichée dans le chat de l'agent Cursor ou IntelliJ connecté ; l'app MCP graphique propose Envoyer à l'agent IDE si le client prend en charge les messages. L'agent existant génère les textes et les renvoie via MCP. Aucune clé API supplémentaire n'est nécessaire. L'assistant ne lance aucun agent en arrière-plan et n'utilise aucun service de remplacement payant.
Charger les suggestions dans le formulaire affiche les propositions vérifiées. Les métadonnées, clés de traduction, valeurs calculées et champs modifiés manuellement entre-temps sont préservés. La demande expire après dix minutes et est rejetée si le Gulpfile ou le dictionnaire a changé. L'aperçu présente les deux fichiers ensemble ; seule une application explicite avec sauvegarde écrit le Gulpfile et le dictionnaire, et l'annulation restaure l'état précédent. La vérification linguistique et factuelle reste à la charge de l'utilisateur.
Les huit langues d'interface fournies avec µGulp™ sont distinctes de ce choix. D'autres packs de traduction téléchargeables ou installables pour l'interface µGulp™ sont prévus pour la version 2.2.0 et ne font pas encore partie de cet assistant.
Pour les icônes, saisissez un symbole ou un emoji, ou sélectionnez une image PNG, JPEG ou WebP de 64 KiB maximum. Un aperçu direct montre votre sélection. L'image est intégrée dans le Gulpfile ; elle ne dépend donc pas du chemin du fichier d'origine. Les nouveaux fichiers SVG et les URL d'images ne sont pas importés ici. Les métadonnées d'icône existantes sont préservées lors d'une application sans modification.
Améliorer un Gulpfile existant de manière ciblée
L'assistant de configuration vérifie d'abord, de manière purement statique, si vos tâches possèdent déjà des métadonnées de présentation pour µGulp™. Un nom affiché, une description, un groupe, une icône ou une infobulle suffit à indiquer que la présentation d'une tâche a déjà été adaptée. Ce n'est pas une évaluation complète de la qualité du Gulpfile. Chaque tâche n'a pas besoin de toutes ces informations.
Si toutes les tâches détectées sont déjà adaptées, aucune invitation automatique à les optimiser n'apparaît. Pour les Gulpfiles partiellement adaptés, la boîte de dialogue ne propose que les tâches sans ces informations. Vous pouvez d'abord ajouter noms, descriptions, groupes, icônes et infobulles, vérifier l'aperçu des modifications, puis les appliquer explicitement avec sauvegarde. L'annulation reste disponible. Les autres recettes IA sont accessibles ensuite ou en choisissant de passer cette étape.
Les métadonnées calculées ou importées ne peuvent pas toujours être évaluées sans ambiguïté. L'assistant signale alors un état d'optimisation inconnu et ne modifie pas automatiquement ces valeurs. Les raccourcis clavier sont uniquement une suggestion facultative ; leur absence n'est pas considérée comme un besoin d'optimisation. L'absence d'affectation à une tâche globale n'est pas non plus un défaut. Les autres recettes IA et les raccourcis clavier sont initialement désélectionnés à la deuxième étape.
Tâches globales pour les projets sélectionnés
Avec les tâches globales, vous n'avez plus à chercher et à lancer la même tâche séparément dans chaque projet. Un identifiant commun relie les implémentations correspondantes de vos projets : NASBU peut, par exemple, sauvegarder des dossiers différents dans chaque projet. La Web Console présente les projets concernés avec leur titre et leur icône ; vous choisissez explicitement ceux qui doivent démarrer.
La définition globale comprend un identifiant stable et un titre compréhensible. L'implémentation exécutable reste dans le Gulpfile de chaque projet. Ce mécanisme ne distribue pas de code source commun et ne copie pas automatiquement les tâches dans d'autres projets. Différents projets peuvent implémenter le même identifiant selon leurs propres besoins.
Ajoutez µGlobalTask = { id: "NASBU", title: "NAS-Sicherung" } à la tâche exportée. Les identifiants commencent par une lettre majuscule et contiennent au maximum 64 lettres majuscules, chiffres, traits de soulignement ou signes moins. Un projet ne peut proposer un identifiant qu'une seule fois. Les tâches ainsi marquées apparaissent dans le tableau de bord du projet sous leur propre groupe Tâches globales ; un éventuel µGroup est remplacé pour ces tâches.
Ouvrez la Web Console et développez Tâches globales. Actualisez la liste et choisissez la tâche commune. Dans Configurer le projet, enregistrez une fois les valeurs de µParameters pour le projet concerné. Elles sont stockées localement dans .microgulp/global-tasks.json. Une modification de la définition des paramètres nécessite une nouvelle configuration. Les mots de passe et les valeurs marquées remember: false ne sont pas enregistrés ici ; ces tâches nécessitent toujours une utilisation interactive au niveau du projet.
Dans Définir une tâche globale, vous pouvez définir l'identifiant et le titre de manière centralisée. La liste détecte également les identifiants des projets connectés. Un titre centralisé uniformise l'affichage ; il ne crée aucune implémentation exécutable. Les définitions sont stockées dans le répertoire utilisateur, sous .microgulp/global-tasks.json.
Sélectionnez les projets à partir de leur titre et de leur icône. Si plusieurs fenêtres d'IDE sont ouvertes pour un même projet, choisissez exactement une session. Vérifier la sélection affiche uniquement ces projets et leurs valeurs enregistrées. Seul Lancer les tâches sélectionnées transmet le lancement à chaque IDE. Les projets ou IDE fermés ne sont pas ouverts automatiquement.
Le lancement groupé utilise les paramètres enregistrés sans afficher de nouveaux formulaires de saisie. Si la tâche demande malgré tout une boîte de dialogue µGulp, cette exécution échoue avec global-task-dialog-required. Les tâches nécessitant des privilèges Windows élevés et les tâches permanentes ne sont pas lancées globalement. Le code Gulp reste du code exécuté localement ; les programmes externes dotés de leurs propres boîtes de dialogue ne deviennent pas pour autant des tâches sans intervention.
Les aperçus ont une durée de validité limitée et ne peuvent être utilisés qu'une seule fois. Toute modification du Gulpfile, de la définition de la tâche, des paramètres enregistrés ou des Project Controls les invalide. Si la session IDE se termine ou change, vous devez refaire la sélection et la vérification. Toutes les sessions sélectionnées sont vérifiées avant le premier lancement.
Un lancement groupé n'est pas une transaction : si une connexion est interrompue après le premier lancement, les projets précédents peuvent déjà être en cours d'exécution. Le résultat indique les projets démarrés, ceux en échec et ceux qui n'ont pas encore démarré. Il n'y a ni nouvelle tentative automatique ni annulation automatique des tâches exécutées. La progression, les journaux et l'arrêt sont disponibles dans le tableau de bord de chaque projet.
Lancer une tâche dans un autre projet
Une tâche du projet A peut utiliser RunGlobalTask de gulp-mu-gulp-api pour lancer dans le projet B une implémentation marquée avec µGlobalTask et attendre sa fin. Transmettez l'identifiant exact du projet et l'identifiant de la tâche globale. Les paramètres cibles doivent avoir été configurés au préalable dans le tableau de bord du projet B. Le projet B doit disposer d'une connexion active avec son tableau de bord µGulp ouvert. Si plusieurs sessions sont ouvertes pour le projet cible, indiquez également le sessionId de la session souhaitée. Les projets ou IDE fermés ne sont pas ouverts automatiquement.
import { RunGlobalTask } from 'gulp-mu-gulp-api';
const result = await RunGlobalTask({
projectId: 'Projekt-ID-von-B',
globalId: 'DEPLOY',
timeoutMs: 120000
});
if (!result.ok) throw new Error(result.error ?? result.code);
console.log(result.taskResult);
La réponse contient l'état, l'identifiant d'exécution et la durée. taskResult n'est présent que si la tâche cible a appelé ReportTaskResult. L'appel lance la tâche cible via sa session IDE connectée ; aucune fenêtre visible de la Web Console n'est ouverte. Les appels à soi-même et les chaînes récursives de projets sont rejetés. Le délai d'attente est compris entre 1 et 300 secondes ; sa valeur par défaut est de 120 secondes. La tâche cible peut déjà avoir démarré lorsque le délai expire.
Les appels globaux nécessitent une session IDE active et approuvée, avec le tableau de bord µGulp ouvert, ainsi qu'une édition donnant accès à l'API de l'IDE. La vue d'ensemble des projets et l'utilisation simple des tâches existantes restent disponibles. L'exécution autonome de projets fermés dans le Background Host, les touches matérielles globales et les outils MCP globaux ne font pas partie du périmètre de cette version 2.1.0.
Éditions et fonctionnalités
µGulp™ est disponible en µGulp™ (VS Code / Cursor), µGulp™ Free (VS Code / Cursor) et µGulp™ pour les IDE JetBrains (IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip et les autres IDE basés sur IntelliJ). La comparaison ci-dessous reflète les éditions actuelles. N’installe pas l’extension VS Code enregistrée en même temps que µGulp™ Free : elles partagent les mêmes identifiants de commande. Enregistre l’édition complète de VS Code avant de lancer une première tâche, ou désinstalle-la et utilise µGulp™ Free. JetBrains ne nécessite pas d’inscription µGulp™ et n’existe pas en édition 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, préchargement, i18x, paramètres, µWatch, µSchedule, 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 |
| Intégrations matérielles (Stream Deck, Logitech, Flexbar) | oui | - | oui |
| Actions IDE depuis les tâches | oui | - | oui |
| Web Console : projets, état des sessions, tableau de bord intégré | oui | oui, les droits habituels des tâches s'appliquent | oui |
| Background Host et administration de l'hôte | oui | oui | oui |
| Open/Focus Project, Start Application, actions IDE, IDE préféré | oui | - | oui |
| Réglages de l'hôte | microgulp.* |
microgulp.* |
Settings → Tools → µGulp |
| Marketplace | Installer pour VS Code · Installer depuis Open VSX | Installer µGulp Free · Installer depuis Open VSX | Installer pour 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. L’édition Free suit le thème de l’IDE/du système avec IDE Dark / IDE Light (sans sélecteur d’apparence) et n’inclut ni packs de thèmes, ni diagnostics, ni élévation, ni intégrations matérielles, ni actions IDE. La Web Console locale reste disponible dans Free : projets, état et administration de l'hôte restent accessibles ; les actions avancées (Open/Focus Project, Start Application, actions IDE, IDE préféré) sont réservées aux autres éditions.
Nouveautés de la version 2.0.0
L'assistant ajoute des recettes IA aux projets existants et montre toutes les modifications de fichiers avant application. La connexion MCP facultative à l'agent de l'IDE et les aides à la traduction et à la maintenance des manuels sont également nouvelles. L'utilisation quotidienne reste simple : ouvrir le projet, choisir une tâche, la lancer.
Un générateur général de workflows IA, l'optimisation sémantique de tâches quelconques et l'auto-optimisation évolutive sont des idées non implémentées, sans périmètre ni échéance promis.
Disponible depuis la version 1.1.0
Les informations facultatives du formulaire précèdent les champs de saisie. Les tâches peuvent activer explicitement l’annulation et la mémorisation des choix admissibles. µI18xContext.GetValues() fournit un état synchrone des métadonnées à chaque analyse ; les espaces réservés modifiés actualisent aussi la liste des tâches. Les gulpfiles existants et les réponses réussies restent compatibles. Ces fonctions sont documentées dans gulp-mu-gulp-api 0.7.0.
Contrat des formulaires et exemples · Notes de version 1.1.0
Assistant de configuration et recettes IA
Configurer les tâches du projet ouvre dans le tableau de bord l'assistant pour un gulpfile existant. Il analyse statiquement ESM/CommonJS, propose les champs adaptés et montre toutes les modifications avant application. Les neuf recettes IA couvrent noms affichés et descriptions, groupes libres ou liés au projet, raccourcis, sauvegarde NAS, microCSS, configuration initiale et préparation GitHub et npm.
- Sauvegarde NAS : identifiant du projet, source, plusieurs destinations, mode de sauvegarde, dossier ou ZIP, méthode de copie et exclusions. La simulation est sélectionnée par défaut ; les identifiants des destinations sont affichés pour une préparation explicite. La configuration n'accède pas elle-même au NAS.
- microCSS : manifeste existant de confiance, dossiers source et sortie, compression et aperçus graphiques. Chaque build utilise un nouveau sous-dossier de sortie.
- Application sûre : aperçu complet des fichiers, vérification des hashes source, protection des fichiers de recette IA existants, sauvegarde sous
.microgulp/setup-backupset annulation de la dernière application inchangée dans la même session.
Les dépendances nécessaires figurent dans l'aperçu puis sont installées avec npm install dans le dossier de la recette IA. Les trois nouveaux concepts de préparation ne nécessitent aucun paquet de recette IA supplémentaire. Les imports du manifeste microCSS nécessitent aussi leurs paquets dans le projet source. Les tâches et analyses en cours bloquent les modifications. Les constructions dynamiques du gulpfile peuvent nécessiter des adaptations manuelles.
Préparer la configuration initiale et les publications
Les recettes IA Configuration initiale, Publication GitHub et Publication npm ajoutent des tâches de préparation au gulpfile existant. Chaque recette IA dispose d'un formulaire pour le nom du projet et ses réglages. Les tâches affichent vérifications et commandes appropriées ; elles n'installent aucune dépendance et n'effectuent ni push ni publication. L'application dans l'assistant n'autorise pas non plus une publication.
- Configuration initiale (
project-bootstrap) : vérifier fichier de paquet, état Git, exclusions, dépendances et scripts de build/test existants. Pour un nouveau projet, créer d'abord ungulpfile.mjsvide et le sélectionner. Les fichiers de paquet absents sont signalés comme étape de préparation, jamais créés silencieusement. - GitHub (
github-release) : choisirEigentümer/Repositoryet la visibilité. Le plan guide la connexion, les contrôles du remote et des fichiers, la création délibérée d'un dépôt absent, le push du commit vérifié et un brouillon de release avec un tag contrôlé. Création du dépôt, push et publication restent des étapes séparées à demander explicitement. - npm (
npm-release) : choisir patch, minor ou major, registre, accès et canal. Inclure l'augmentation de version dans l'aperçu des fichiers montre la nouvelle version danspackage.jsonet lespackage-lock.json/npm-shrinkwrap.jsonexistants. Leur application sauvegarde et modifie ces fichiers avec le gulpfile ; l'annulation les restaure octet pour octet. Sans cette option, le plan présente l'augmentation comme une étape restante.
L'augmentation automatique prend en charge les versions stables comme 1.2.3 ; les préversions et ensembles de paquets workspace nécessitent un processus propre au projet. Paquets privés, lockfiles contradictoires ou réglages de publication divergents bloquent la modification automatique. Si RELEASES.json existe, désactiver cette option et utiliser la synchronisation des versions du projet. Les autres sources de version personnalisées relèvent aussi du processus du projet. Le démarrage des tâches préparatoires n'augmente pas une seconde fois une version déjà augmentée par cette configuration.
Ni l'aperçu ni le démarrage d'une tâche n'interrogent le registre. Le plan npm exige donc avant publication réelle la vérification du registre, les tests, le build, le contrôle du contenu du paquet et la connexion. L'augmentation locale ne confirme pas que la version est disponible dans le registre. Un paquet déjà publié ne peut pas être republié avec la même version. Publication npm · Versionnement npm · Brouillon de release GitHub
Organiser les tâches par projet
Chacune des trois recettes IA crée quatre tâches préparatoires sous Nom du projet/Info, Nom du projet/Build, Nom du projet/Tools et Nom du projet/Maintenance. Info contient les contrôles d'inventaire et de résultat, Build la préparation du build, Tools les aides et vérifications, Maintenance la configuration, le versionnement et la préparation des releases. Les noms commencent par défaut par SETUP_PROJECT, PREPARE_GITHUB_RELEASE ou PREPARE_NPM_RELEASE, puis la catégorie en majuscules.
Groupes de tâches par projet (project-structure) permet également de classer des tâches existantes : saisir le nom du projet et choisir l'une des quatre catégories par tâche. Noms exportés et code restent inchangés. Cette recette IA ne peut pas être appliquée en même temps que la recette IA libre Groupes de tâches. L'affectation figure dans l'aperçu et est sauvegardée.
MCP propose les mêmes formulaires et modifications avec list_recipes, get_recipe, preview_setup, apply_setup et undo_setup. get_recipe et list_library fournissent aussi les instructions versionnées pour l'agent IDE, y compris vérification des versions et autorisation de publication. Aucun skill IA séparé publiant automatiquement ne fait partie de ces recettes IA. Au 19 octobre 2026, les recettes IA de démarrage de projet, GitHub et npm ont également été vérifiées par MCP dans les clients Cursor et IntelliJ installés : aperçu, application, contrôle des fichiers en lecture seule et annulation. Les hashes initiaux ont été restaurés, y compris ceux du paquet et du lockfile pour l'augmentation npm. Aucune tâche préparatoire, requête au registre ou publication n'a été exécutée pendant ces tests.
Configuration par MCP
L'adaptateur MCP séparé fournit le même parcours via list_recipes, get_recipe, list_setup_files, analyze_gulpfile, preview_setup, apply_setup et undo_setup. list_projects, list_tasks et get_task fournissent projets, sessions IDE précises et catalogue de tâches. Avec open_setup_assistant, un client compatible MCP Apps comme Cursor ouvre la configuration graphique dans le chat : sélectionner et analyser le gulpfile, cocher les recettes IA, remplir les formulaires et contrôler l'aperçu complet. Application et annulation utilisent des boutons distincts et les mêmes protections que le tableau de bord. Cursor peut demander d'autoriser les appels d'outils. Les clients sans MCP Apps utilisent toujours les outils séparés.
Node.js 22 ou ultérieur et une session active de l'hôte mis à jour sont nécessaires. Après installation des dépendances SDK séparées (npm ci --prefix <Installationsordner>/src/mcp --omit=dev --ignore-scripts), le client lance node <Installationsordner>/src/mcp/microgulp-mcp.mjs --project <absoluter-Projektpfad>. Les modifications exigent aussi --setup-write-project <derselbe-Projektpfad>. Sans cette autorisation au démarrage, seuls lecture, analyse et aperçu sont possibles. Les propositions sont séparées par processus MCP et session IDE. Ces outils ne démarrent pas de tâches, n'installent pas automatiquement de paquets et ne publient rien.
Vérifier les suggestions de texte et reconnecter MCP après une mise à jour
Ouvrez Configurer les tâches du projet et sélectionnez le Gulpfile, les tâches souhaitées et la langue d'édition. Préparez la demande de texte uniquement lorsque l'agent IDE est connecté au serveur MCP de µGulp™. Copiez la demande affichée dans ce chat. Laissez le formulaire ouvert ; la demande est valable dix minutes et appartient au moteur de projet actuel.
Après la réponse de l'agent, cliquez sur Charger les suggestions dans le formulaire dans le même formulaire. Vérifiez les noms, descriptions, infobulles et groupes ajoutés. La réponse review-required signifie uniquement qu'une proposition existe ; elle ne confirme ni sa qualité ni une modification du Gulpfile. Vous pouvez corriger ou omettre les textes inadaptés ou peu informatifs. L'agent ne doit pas inventer une fonction inconnue à partir du nom d'une tâche.
Vérifiez ensuite l'aperçu des modifications et appliquez-les avec sauvegarde si nécessaire. Annuler cette modification restaure l'état sauvegardé tant qu'aucune modification ultérieure n'a été effectuée. Une demande préparée directement dans le chat n'est pas automatiquement liée à un formulaire déjà ouvert. Pour le parcours par formulaire, commencez donc par la demande qui y est affichée. Préparez une nouvelle demande après expiration, changement de langue ou redémarrage du moteur.
Une mise à jour de l'extension peut changer le répertoire d'installation. Vérifiez le chemin vers microgulp-mcp.mjs dans la configuration MCP et installez les dépendances SDK séparées dans le nouveau dossier src/mcp avec npm ci --omit=dev --ignore-scripts. Un serveur activé ne prouve pas que la connexion fonctionne. En cas de Connection closed, consultez le journal du serveur ; si @modelcontextprotocol/sdk est absent, ces dépendances manquent dans le dossier utilisé.
Reconnectez le serveur MCP et ouvrez un nouveau chat d'agent. Vérifiez la session actuelle avec list_projects. Les suggestions de texte nécessitent la disponibilité de prepare_setup_text, get_setup_text et submit_setup_text. Si list_projects renvoie un projet sans session, ouvrez son tableau de bord µGulp™. Une connexion MCP accessible et un moteur de projet actif sont tous deux nécessaires.
Application MCP graphique dans Cursor
- Ouvrir le projet dans Cursor et connecter le serveur MCP µGulp™ configuré. Il propose des outils de configuration, d'accès aux tâches et de skills facultatifs ainsi qu'une ressource UI.
- Demander à l'agent Cursor : « Utilise
list_projectspour identifier la session actuelle du projet et ouvreopen_setup_assistantpour elle. N'effectue ensuite aucune autre modification. » Déplier le résultat de l'outil si l'application est repliée. - Choisir le gulpfile et cliquer sur Analyze gulpfile. Confirmer soi-même toute autorisation d'outil demandée par Cursor. Choisir les recettes IA et remplir les champs : identifiant NAS, source et destinations ; manifeste microCSS, source et sortie ; noms affichés, descriptions, groupes et raccourcis.
- Cliquer sur Preview changes. Contrôler les vues avant/après, le gulpfile complet et les nouveaux fichiers de recette IA dépliables. L'aperçu indique aussi paquets nécessaires et préparation des identifiants NAS. Aucun fichier n'est encore écrit.
- Apply changes and create backup applique la proposition vérifiée et sauvegarde les originaux sous
.microgulp/setup-backups. Sources modifiées, fichiers de recette IA préexistants ou tâches en cours empêchent une application dangereuse. - Undo this change restaure les originaux octet pour octet et retire seulement les fichiers de recette IA créés par cette application. Toute modification ultérieure bloque l'annulation. La dernière application ne peut être annulée que dans la même connexion MCP et session IDE.
Sans --setup-write-project, analyse et aperçu restent disponibles ; l'application est masquée. L'interface ne lance ni tâches ni installations. Plusieurs vues et appels de l'agent sur une même connexion partagent le dernier aperçu : traiter une seule proposition à la fois.
Après redémarrage de Cursor, de l'hôte ou de MCP, rappeler list_projects et open_setup_assistant, puis réanalyser. Une ancienne vue peut signaler ide-session-unavailable. Les aperçus sont valables dix minutes. Si la connexion se coupe pendant l'application, contrôler fichiers et sauvegarde avant toute nouvelle écriture. Après une mise à jour VSIX, vérifier le chemin MCP, réinstaller au besoin ses dépendances SDK et reconnecter le serveur.
Connecter MCP dans Cursor et IntelliJ
MCP et les skills sont facultatifs. Au quotidien, il suffit toujours d'ouvrir le projet, de choisir une tâche et de la lancer. Pour les étapes suivantes, le projet doit être ouvert dans l'hôte µGulp™ mis à jour. Utiliser le vrai dossier d'installation : adaptateur sous src/mcp dans Cursor, sous microgulp/src/mcp dans le plugin JetBrains décompressé. Y installer les dépendances SDK séparées comme indiqué plus haut.
Cet exemple de configuration convient aux deux clients. Remplacer les chemins absolus par les chemins locaux ; --setup-write-project autorise ensuite l'application vérifiée et l'annulation dans ce seul projet :
{
"mcpServers": {
"microgulp": {
"command": "C:/Program Files/nodejs/node.exe",
"args": [
"C:/Pfad/zur/Installation/src/mcp/microgulp-mcp.mjs",
"--project", "C:/Projekte/MeinProjekt",
"--setup-write-project", "C:/Projekte/MeinProjekt"
]
}
}
}
- Cursor : ajouter le serveur dans
.cursor/mcp.jsondu projet sans supprimer les entrées existantes. L'activer dans la gestion MCP et contrôler la connexion. Après modification de configuration, reconnecter et ouvrir un nouveau chat d'agent. - IntelliJ : sous Settings → Tools → AI Assistant → Model Context Protocol (MCP), ajouter avec Add une connexion STDIO, coller le JSON et démarrer avec Apply. Sous Tools → AI Assistant → Agents, activer et confirmer aussi Pass custom MCP servers. Pass IntelliJ MCP server concerne le serveur intégré et ne remplace pas cette transmission. Ouvrir ensuite un nouveau chat avec l'agent choisi. Codex avec connexion ChatGPT a été testé ici ; aucun autre secret API µGulp™ n'est nécessaire. Configuration JetBrains
Première vérification : « Appelle l'outil list_projects du serveur MCP microgulp. Aucune requête de ressources ni modification. » Contrôler chemin, IDE et session dans la réponse réelle. unknown MCP server ou des outils absents indiquent que le chat n'est pas encore connecté. Vérifier alors état du serveur, transmission et nouveau chat. Une requête de ressources réussie ne remplace pas ce test. Utiliser les projectId et sessionId retournés, jamais d'anciens identifiants.
Skills avec l'agent existant
Interroger la bibliothèque versionnée avec list_library. Les profils du projet se trouvent dans .microgulp/agent-profiles.json et définissent les entrées autorisées et la version du skill. Le défaut execution: "client" utilise l'agent de l'IDE. Des skillGrants séparés ne sont nécessaires que pour le mode API explicitement activé ; une liste vide n'empêche pas le parcours client normal. start_api_skill n'est pas un remplacement automatique d'une connexion d'agent absente.
Exemple de profil de traduction ; les trois fichiers JSON doivent déjà exister dans le projet :
{
"schemaVersion": 1,
"profiles": {
"texte-de": {
"enabled": true,
"skill": "localization",
"version": "1.1.0",
"execution": "client",
"configuration": {
"source": "i18x/source.json",
"target": "i18x/de-DE.json",
"baseline": "i18x/source-baseline.json",
"sourceLanguage": "en-US",
"language": "de-DE"
}
}
}
}
inspect_skill_profilefournit le hash actuel du profil.start_skillreçoit l'identifiant du profil, ce hash et un nouveaurequestIdunique. La mission préparée est valable 30 minutes.- L'agent traite les entrées fournies et envoie résultat, identifiant du travail et
digestinchangé àsubmit_skill_result. Une proposition est enregistrée sous.microgulp/proposals/<id>/proposal.json; le fichier traduit reste inchangé. - Contrôler l'aperçu : cible, textes modifiés, espaces réservés préservés et entrées inchangées. Autoriser ensuite seulement
apply_skill_proposalavec l'identifiant de proposition. µGulp™ revérifie les sources et sauvegarde l'original sous.microgulp/proposals/<id>/original.json. - Contrôler le fichier réel.
undo_skill_proposalannule cette application avec le même identifiant si le fichier reste inchangé et que la connexion MCP et la session hôte sont les mêmes. Pour la validation, comparer le hash avant test et après annulation.
Demande simple : « Utilise le profil texte-de avec l'agent existant, soumets le résultat par MCP et montre l'aperçu. Arrête-toi avant l'application. Aucune modification directe. » Application et annulation sont ensuite explicitement demandées. Après skill-expired, préparer à nouveau ; pour unknown-skill-run ou unknown-undo, vérifier d'abord session, fichiers et sauvegarde. Ne pas répéter aveuglément ni remplacer l'annulation par une écriture directe.
Maintenance du manuel avec aperçu étayé
Un profil skill: "handbook-maintenance", version 1.1.0, avec execution: "client", définit dans configuration un DOCX du projet librement nommé comme master, sa sourceLanguage, les fichiers d'implémentation dans files et un commit Git complet existant comme baselineCommit. outputLanguage choisit facultativement la langue des propositions ; sinon la langue source s'applique. chapters limite les chapitres ; editorialRules contient les règles éditoriales facultatives du projet. Le commit doit être lisible depuis le projet ouvert. Le skill ne traite actuellement ni PDF ni Markdown.
Le parcours jusqu'à submit_skill_result est celui du skill de traduction. L'aperçu contient les propositions avec références de fichiers et lignes et editorial-review-required. Aucune application DOCX automatique : apply_skill_proposal refuse un rapport avec handbook-report-requires-editorial-work. La modification éditoriale est effectuée séparément dans votre DOCX configuré. Le skill n'actualise ni baselines, ni traductions, ni sorties finales. « Sources allemandes .src. d'abord, puis traduction des seules différences » est une convention de notre projet µGulp™, uniquement dans son profil ; les clients définissent leur propre processus.
Exemple de manuel client
La source peut s'appeler docs/Customer Guide.docx. Ce profil utilise l'anglais comme source et le français pour les propositions. Remplacer l'espace réservé par un vrai commit Git complet du projet :
{
"enabled": true,
"skill": "handbook-maintenance",
"version": "1.1.0",
"execution": "client",
"configuration": {
"master": "docs/Customer Guide.docx",
"sourceLanguage": "en-US",
"outputLanguage": "fr-CA",
"files": ["src/build.mjs"],
"baselineCommit": "<vollständiger Git-Commit>",
"editorialRules": "Kundenterminologie erhalten und bestehende Kapitelstruktur beachten."
}
}
Placer cette entrée sous un nom propre dans profiles de .microgulp/agent-profiles.json. Les identifiants comme de-DE, en, fr-CA et zh-Hant sont vérifiés. La langue du résultat n'est pas certifiée linguistiquement de façon automatique. Source et cible d'une traduction doivent être différentes ; seuls les dictionnaires JSON plats contenant des chaînes sont pris en charge, pas la traduction générale de Markdown ou DOCX.
Actualiser les profils existants
Les profils de skill 1.0.0 restent exécutables pour traduction et maintenance des manuels. Fichier et hash ne sont pas réécrits automatiquement. Sans sourceLanguage, la langue source des anciens profils de traduction reste indéterminée (und) ; l'agent la déduit du texte. Les anciens profils de manuel conservent de-DE sans langue indiquée. Les indications explicites priment. Les nouveaux profils clients utilisent 1.1.0 avec source et langue choisies ; les règles éditoriales propres au projet restent dans son profil. Pour une migration durable, sauvegarder, vérifier version et langues, puis préparer une nouvelle mission. Versions inconnues et profils erronés sont marqués individuellement non exécutables sans bloquer les profils valides voisins. Un fichier de profils globalement invalide reste refusé. Pins et valeurs d'intégrité de la bibliothèque ne sont pas renouvelés automatiquement. Aperçu, protection des espaces réservés, sauvegarde, annulation et blocage DOCX s'appliquent aussi aux anciens profils.
Rétablir la connexion du tableau de bord IntelliJ
Si le moteur du projet IntelliJ s'arrête, la fenêtre µGulp™ ouverte le détecte et propose Reconnect dashboard. Masquer puis réafficher la fenêtre redémarre un moteur détecté arrêté. Un moteur actif n'est pas redémarré ; les tâches ne sont pas répétées. En cas d'erreur de démarrage, le message et l'option de réessai restent visibles, sans boucle automatique. Sans signal de disponibilité, le démarrage est interrompu après au maximum 120 secondes. Vérifier chemin Node et réglages du projet, puis choisir Reconnect dashboard. Après reconnexion, rappeler list_projects et choisir la nouvelle session. Ne pas réutiliser d'anciens identifiants de proposition ou d'annulation ; contrôler les sauvegardes avant une nouvelle demande de modification. Un état MCP vert ne prouve pas à lui seul qu'une session de tableau de bord est active.
Parcours vérifiés et autorisations
Les profils clients configurables de skill 1.1.0 ont été testés par MCP dans Cursor et IntelliJ installés au 19 octobre 2026 : en-GB vers fr-CA, aperçu avec espace réservé conservé, application et annulation octet pour octet. Pour le manuel, source DOCX et langue du rapport étaient libres ; l'application automatique a été refusée avec handbook-report-requires-editorial-work et le hash DOCX n'a pas changé. La compatibilité des profils 1.0.0 a ensuite été confirmée dans IntelliJ. Ces tests démontrent le parcours contrôlé, pas la qualité linguistique de tout résultat d'agent.
Le 19 octobre 2026, la reconnexion après arrêt du moteur a été testée dans IntelliJ avec Reconnect dashboard : nouvelle session accessible par MCP et tests des anciens profils réussis. Les traductions ont été appliquées puis annulées octet pour octet ; le serveur a refusé l'application automatique du manuel et le DOCX n'a pas changé. Cela prouve le cas testé, pas la restauration de tâches quelconques en cours ou d'anciens identifiants de proposition.
Le dernier test local Windows avec Node.js 22 a réussi avec 1115 tests, aucun échec et quatre cas de plateforme/périphérique explicitement ignorés. Les 31 tests MCP/site supplémentaires ont réussi. Les paquets VS Code, Cursor Internal et Free actualisés ont été installés et vérifiés avec une tâche réussie. JetBrains Plugin Verifier confirme la compatibilité avec les plateformes testées 242, 261 et 262 ; les deux appels API obsolètes signalés ont été supprimés. Le paquet JetBrains corrigé a été installé et testé localement sous Windows dans IntelliJ IDEA 2026.2.2 : confirmation du chemin prérempli, annulation du sélecteur, ouverture du journal, affichage complet initial, masquage/réouverture, maximisation/restauration et redimensionnement de la fenêtre. Le passage entre écrans à échelles DPI différentes n'a pas été testé. Les anciennes validations MCP restent liées à leurs paquets respectifs. Cela ne remplace ni un nouveau CI multiplateforme ni les essais matériels physiques restants.
Du 17 au 19 octobre 2026, les paquets 2.0.0 installés localement ont été testés sous Windows avec le vrai agent Cursor et Codex dans le chat IntelliJ : aperçu de traduction, application, contrôle en lecture seule et annulation octet pour octet ; aperçu de manuel étayé, refus DOCX automatique et hash inchangé. L'application graphique MCP a été testée dans Cursor ; cela ne valide pas une application graphique IntelliJ. Les autres agents et systèmes ne sont pas couverts.
Un premier essai Cursor a signalé unknown-undo ; sa cause est restée inconnue. Le parcours complet suivant a réussi. Session et sauvegarde doivent donc être explicitement contrôlées en cas d'erreur. Un refus du contrôle d'autorisation client, par exemple Guardian, n'est ni une réponse d'outil µGulp™ ni un test négatif réussi. Ne pas contourner les autorisations ; toute tentative supplémentaire exige une autorisation supplémentaire explicite. Le test DOCX exige l'erreur réelle µGulp™ et un hash inchangé relu après l'appel.
Configuration de démarrage, parcours et limites
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) |
Clique sur une tâche → un worker déjà disponible exécute la tâche sans réimporter le gulpfile. Enregistre le gulpfile → la liste des tâches s’actualise automatiquement. Exécute plusieurs tâches en parallèle ; chacune dispose de son propre secteur dans le tableau de bord, avec une barre de progression néon si la tâche appelle ReportProgress de gulp-mu-gulp-api.
Conserver la CLI Gulp
Les métadonnées supplémentaires ne changent pas l'adressage CLI. Les builds existants peuvent continuer sous la CLI gulp classique et en CI. Les paquets importés restent nécessaires ; les valeurs d'entrée et actions dépendantes de l'hôte doivent convenir à ce parcours. Vérifier les appels CLI existants après intégration.
Comportement sans tableau de bord
| 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/ |
Selon les usages, contient aussi code de recette IA, profils, configuration et sauvegardes. Ne pas tout supprimer : le code importé peut être nécessaire en CLI. Versionner les fichiers de projet sélectivement ; exclure journaux locaux, identifiants secrets et sauvegardes |
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. Conserver paquets et recettes IA nécessaires en retirant l'extension. Les actions liées à l'hôte nécessitent une solution de repli adaptée.
Respecter les exigences de version
La CLI Gulp classique ignore les métadonnées supplémentaires. Cela ne garantit pas une compatibilité générale entre toutes versions d'hôte, Gulp ou API : de nouveaux appels peuvent nécessiter de nouveaux paquets, les actions IDE des capacités adaptées. Respecter les versions requises et vérifier les appels après mise à jour.
Un collègue peut donc continuer à lancer les tâches existantes avec npx gulp BUILD dans le terminal pendant que vous utilisez le tableau de bord. Les deux chemins utilisent les mêmes fichiers ; coordonner les écritures parallèles dans le projet.
Installation
µGulp™ est disponible maintenant. Installez depuis les fiches publiques :
| Édition | Installer |
|---|---|
| µGulp™ (VS Code / Cursor) | Installer pour VS Code · Installer depuis Open VSX |
| µGulp™ Free (VS Code / Cursor) | Installer µGulp Free · Installer depuis Open VSX |
| µGulp™ (JetBrains IDEs) | Installer pour JetBrains |
Le dépôt source reste privé. N'installez pas l'édition VS Code/Cursor enregistrée et µGulp™ Free côte à côte - elles partagent les mêmes identifiants de commande.
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. Installer pour JetBrains depuis le Marketplace ; la fiche propose deux builds selon la compatibilité, et l'IDE reçoit celui qui correspond (Help → About) :
| IDE build | since-build |
Marketplace |
|---|---|---|
2024.2 - 2026.1 (jusqu'à 261.*) |
242 |
Installer pour JetBrains |
| 2026.2 et plus récent | 262 |
Installer pour JetBrains |
Le Marketplace sélectionne le build correspondant. IntelliJ IDEA, PhpStorm, WebStorm et les autres IDEs basés sur IntelliJ partagent ces deux variantes - selon le build plateforme, pas le nom du produit. Chaque variante déclare
<idea-version since-build="…"/>dans le descripteur - l'IDE n'accepte pas l'autre. La variante 2024.2-2026.1 estsince-build="242"/until-build="261.*". La variante 2026.2+ estsince-build="262"sans borne supérieure. 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ù la variante Marketplace séparée. Installez depuis le JetBrains Marketplace (Settings → Plugins → Marketplace, recherche MicroGulp) 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:verifylance 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 dansMICROGULP_IDE_CACHE(défaut%LOCALAPPDATA%\microgulp\ide-cache,~/.cache/microgulp/ide-cacheailleurs) et réutilisées ; l'IDE installé localement est utilisé directement lorsque son build correspond.MICROGULP_SKIP_IDE_DOWNLOAD=1garde 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.jcefet 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/.
Paquets hors ligne
Ces fichiers n'existent que dans un checkout local du dépôt source. Ce n'est pas le chemin d'installation public.
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, puisnpm run build- les fichiers.vsixenregistré et Free atterrissent danspackages/.
Zips JetBrains d'un build local :
| IDE build | Paquet |
|---|---|
2024.2 - 2026.1 (jusqu'à 261.*) |
packages/microgulp-jetbrains_latest.zip |
| 2026.2 et plus récent | packages/microgulp-jetbrains-2026.2_latest.zip |
Installez un zip local via Settings → Plugins → ⚙ → Install Plugin from Disk…
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, project). 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 unique relatif à la racine du projet ; doit rester dans cette racine |
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. |
project |
objet | - | Optionnel. Identité du projet pour la liste des tâches : title, description, logo (SVG/PNG/WebP, relatif à la racine). Sans valeurs, pas d'en-tête supplémentaire. |
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. Les changements de project (titre, description, logo) sont pris en compte sans redémarrage de l'IDE lorsque la surveillance du gulpfile est active.
Identité du projet (project)
En-tête compact optionnel au-dessus de la liste des tâches, pour reconnaître immédiatement, avec plusieurs fenêtres IDE ouvertes, à quel espace de travail appartiennent les tâches :
{
"project": {
"title": "ESP][",
"description": "Apple II emulator for ESP32-S3",
"logo": "./assets/esp2.svg"
}
}
- Les trois champs sont optionnels ; sans métadonnées, la disposition précédente reste inchangée.
logo: chemins relatifs à la racine du projet ; formats SVG, PNG, WebP. Fichiers absents ou invalides ignorés (en-tête sans logo).- Infobulle sur l'en-tête : titre, description (si définie) et chemin absolu de l'espace de travail.
- L'identité du projet apparaît dans la liste du tableau de bord et la Web Console. Stream Deck affiche logo et titre sur la touche Root du navigateur de groupes, en conservant les proportions du logo et une bande distincte pour le titre ; un logo inutilisable reçoit une représentation de remplacement. Logitech MX utilise l’image du projet fournie par l’hôte connecté pour la sélection du workspace et la touche µGulp™, avec l’image de marque comme remplacement. La validation complète sur appareil reste à faire ; aucun affichage de logo de projet n'est promis pour Flexbar.
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/engineetsrc/workerne 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 minimalnpm run serve(src/host/microgulp-serve.mjs, NDJSON sur stdio) est déjà en place. - Préchargement des tâches. Le
TaskWorkerPoolconserve 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 viaawait 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™ découvre les gulpfiles par un chemin unique ou un motif regex parcourant tout le workspace. La sélection appartient au projet et est identique dans VS Code, Cursor, JetBrains et la CLI :
- Surcharge explicite de l'IDE ou de la CLI : paramètre VS Code/Cursor, JetBrains Settings → Tools → µGulp ou
microgulp-serve --gulpfile/--gulpfile-pattern. Un champ vide n'est pas une surcharge. microgulp.config.jsonà la racine (gulpfileougulpfilePattern).- Par défaut :
gulpfile.mjsà la racine, sinon découverte avec(^|/)gulpfile\.(m|c)?js$.
À chaque niveau, un motif prime sur un chemin unique. Un chemin hors de la racine est rejeté ; un fichier absent entraîne un avertissement et le passage au niveau suivant.
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$trouvegulpfile.mjs/.js/.cjsà la racine et dans chaque sous-dossier.microgulp.gulpfilePath- chemin unique explicite ; vide par défaut pour appliquermicrogulp.config.json.
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, file, folder |
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, accept |
numeric / textarea details; accept on file is .zip,.json |
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.
Les longues listes (select / radio / checkbox) sont prises en charge : l'hôte conserve par défaut jusqu'à 5000 entrées par champ (surcharge MICROGULP_MAX_SELECT_OPTIONS ; 0 = illimité). Une réduction affiche un avertissement, sans troncature silencieuse. Un filtre apparaît dès 24 options. Les formulaires RequestForm ad hoc de gulp-mu-gulp-api n'ont pas de plafond d'hôte pour leur charge utile en direct ; les mêmes types de champs et le filtre s'appliquent.
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.µShortDisplayName = 'CSS, Build Styles<context="µShortDisplayName"/>'.i18xRegister(); // Optionaler Kurztext für Stream Deck und Logitech MX
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();
µShortDisplayName est une phrase i18x facultative pour les libellés courts du matériel. Elle ne modifie ni le nom du tableau de bord ni l’identifiant de tâche. Elle peut contenir « texte court, texte original », par exemple CSS, Build Styles. La balise de contexte µShortDisplayName appartient seulement à la phrase source i18x ; l’hôte la retire avant affichage. Aucune balise n’apparaît sur l’appareil.
Balises de contexte, formats obligatoires et plan de langues marketplace : dev/docs/MicroGulpI18xProfile.md.
Présentation et contrôle des tâches depuis le gulpfile
µGulp™ indique si chaque tâche est inactive, désactivée, en démarrage, en cours, en attente d’une saisie, en arrêt, terminée avec succès ou en échec. La bordure d’état reste visible avec les icônes personnalisées. Une saisie en attente ajoute une icône de dialogue violette ; réponds dans le tableau de bord.
38 icônes SVG offrent une présentation sémantique. µTaskKind et µPresentation décrivent la tâche, par exemple compilation, test, copie ou publication. Les icônes suivent le thème, peuvent être personnalisées par thème et respectent la préférence de réduction des animations. Les animations indiquent l’activité ; en cas d’échec, le dessin d’origine est carbonisé. Les paramètres µIcon et µIconFont existants sont conservés.
Marque un service de longue durée avec µExecutionType = 'persistent' pour pouvoir l’arrêter. Cette propriété est indépendante de µWatch, qui relance une tâche après des modifications de fichiers, et de µAttention, qui signale une intervention nécessaire. µAttentionWatch peut réévaluer ce signal après des modifications de fichiers ou à intervalles réguliers sans exécuter la tâche.
Une tâche Gulp peut également contrôler la vue d’ensemble des tâches :
import { SetGroupState, RevealTask, SetTaskEmphasis } from 'gulp-mu-gulp-api';
SetGroupState('Build', 'open');
RevealTask('PUBLISH_NPM', { expand: true, scroll: true, highlight: 'attention' });
SetTaskEmphasis('PUBLISH_NPM', null);
µGroups définit l’état initial ; les changements de groupes suivants s’appliquent à la session. La mise en évidence et l’état d’exécution sont indépendants : une tâche en cours peut également nécessiter une intervention. Le tableau de bord et le matériel reçoivent le même état de tâche. Ouvrir un groupe dans le tableau de bord ne lance pas ses tâches.
Actions IDE depuis les tâches
Les tâches Gulp importent Ide depuis gulp-mu-gulp-api. Le périmètre 1.0.0 implémenté comprend huit fonctions :
| Fonction | Rôle |
|---|---|
Ide.Capabilities() |
Consulter famille d'hôte, édition, opérations et actions sémantiques prises en charge ; disponible même si les fonctions exécutantes sont verrouillées |
Ide.Projects() |
Consulter projets connus, sessions actives et applications configurées |
Ide.Action(id) |
Exécuter une action sémantique dans l'hôte IDE actuel |
Ide.OpenProject(request) |
Ouvrir un projet connu dans l'installation choisie ou activer sa session précise |
Ide.StartApplication(applicationId) |
Démarrer une application locale connue ou explicitement configurée |
Ide.Execute({ vscode, jetbrains, args }) |
Exécuter la commande native indiquée pour la famille d'hôte actuelle |
Ide.Vscode.ExecuteCommand(commandId, ...args) |
Exécuter une commande VS Code/Cursor autorisée |
Ide.JetBrains.ExecuteAction(actionId) |
Exécuter une action JetBrains autorisée |
Le catalogue commun de Ide.Action contient open-settings, save-all, open-terminal, open-problems, find-in-project, quick-open, command-palette, next-editor, previous-editor, run et debug. Run/Debug utilisent la configuration native actuelle. La disponibilité dépend de l'IDE, des plugins installés et des commandes autorisées ; le catalogue ne garantit pas des capacités identiques dans tous les produits JetBrains.
Ide.OpenProject reprend projectId depuis Ide.Projects().result.projects et, par exemple, applicationId dans les applications renvoyées. Une session précise exige sessionId et connectionId ensemble. Les cibles périmées sont rejetées, sans remplacement par une autre session.
µHost indique la famille IDE requise ; µIdeApi = true marque les tâches utilisant cette interface. Le moteur vérifie édition, enregistrement et commandes autorisées. Dans µGulp™ Free, Ide.Capabilities() reste consultable ; les sept autres fonctions sont verrouillées, y compris Ide.Projects(). La vue lisible des projets de la Web Console reste disponible indépendamment.
Les appels renvoient une Promise avec { ok, result } ou { ok: false, code, message }. Sans IPC µGulp™, par exemple dans la CLI gulp classique, les huit renvoient unsupported-host et ne lancent aucun IDE. Une autorisation d'édition ou d'enregistrement manquante renvoie unsupported-edition ou unsupported-registration. Le gulpfile peut prévoir son propre repli pour CLI et CI.
Ce périmètre décrit l'implémentation du dépôt, pas la disponibilité dans une version npm déjà publiée. Ide.OpenUrl est seulement prévu et indisponible.
Intégrations matérielles
Contrôle les tâches avec Elgato Stream Deck et Stream Deck Mobile, Logitech MX Creative Console et Actions Ring, ainsi que ENIAC Flexbar. Les fonctions matérielles sont incluses dans toutes les éditions sauf µGulp™ Free. JetBrains ne propose pas d’édition Free.
µGulp™ ne se contente pas d’afficher une icône statique sur une touche. Live Animated Task States signifie que la présentation suit l’état d’exécution réel du même moteur que le tableau de bord (inactive → starting → running → finished ou failed, ainsi que disabled, waiting-for-input et stopping). L’animation s’exécute au démarrage, pendant l’exécution, l’arrêt ou la saisie ; la réussite et l’échec restent visibles brièvement (l’échec inclut Burn→Charred). µWatch reste une surimpression marche/arrêt distincte ; les programmes de session peuvent ajouter un compte à rebours ou n/m sur la touche. (Actions Ring : titres uniquement, SDK sans animation LCD.) Contrat et liste des états : TaskPresentationAndHardware.md.
Active la connexion de l’espace de travail dans le tableau de bord sous Settings → Hardware integrations. Le plugin de périphérique correspondant relie les touches aux tâches du projet. Les services en cours peuvent être arrêtés ; les demandes de saisie reçoivent une réponse dans le tableau de bord.
Surfaces de contrôleur sensibles au contexte
µGulp™ utilise un contexte de projet actif commun à Visual Studio Code, Cursor et JetBrains. Stream Deck restaure la dernière vue par workspace et appareil. Logitech conserve sa sélection dynamique existante ; son dossier est partagé par le processus. Flexbar ne suit pas automatiquement le projet IDE.
Le projet actif est commun ; les vues Stream Deck sont enregistrées par appareil. Lorsqu'une autre application est au premier plan, µGulp™ restitue à Stream Deck un profil de navigateur qu'il a ouvert. Le profil par défaut ou Smart Profile affiché ensuite dépend d'Elgato et de la configuration utilisateur ; aucun changement automatique de Smart Profile n'est garanti.
Exemple :
Cursor: microGulp
MX -> Build
Stream Deck -> Release
Alt-Tab
JetBrains: BlueShift
MX -> Build
Stream Deck -> Test
Alt-Tab
VS Code: ESP][
MX -> Upload
Stream Deck -> Monitor
Le retour dans une fenêtre IDE restaure la vue Stream Deck précédente de ce workspace. Les vues sont enregistrées séparément par appareil ; la validation physique avec plusieurs Stream Decks reste à faire.
Si un groupe disparaît après une modification du gulpfile, la restauration revient au parent valide le plus proche ou à la racine. Follow active IDE project est activé par défaut. Le choix manuel du workspace sur le keypad Logitech prime. Limites techniques : Suivre le projet IDE actif.
Elgato Stream Deck et Stream Deck Mobile
Follow et profils : Avec Follow active IDE project, µGulp™ reprend le projet IDE ayant le focus et une connexion matérielle disponible, et peut ouvrir son profil de navigateur fourni. Si le navigateur est déjà visible, seul le contenu change. Quitter le contexte IDE restitue un profil ouvert par µGulp™. Les Elgato Smart Profiles peuvent être configurés en complément dans Stream Deck ; leur activation n'est pas garantie par µGulp™. Détails et dépannage : Stream Deck.
Navigateur de groupes : Open µGulp Group sur un autre profil (par exemple Default) ouvre le navigateur avec des groupes et tâches dynamiques. Cette action ouvre le groupe de départ configuré. Follow et une touche µGulp Group Slot utilisée comme entrée restaurent plutôt la vue mémorisée du workspace actif ; une nouvelle session sans vue mémorisée commence à la racine. Pagination, Retour et Root suivent la grille. Root affiche le logo avec ses proportions conservées et le titre dans une bande distincte ; un logo inutilisable reçoit une représentation de remplacement. Retour à la racine quitte le navigateur. Stream Deck Mobile choisit le modèle selon la grille, notamment 3×2 et 5×3.
Affectation fixe d’une tâche : tu peux toujours faire glisser µGulp Task sur une touche et sélectionner l’espace de travail et la tâche. Les noms, états d’exécution animés et icônes proviennent de l’espace de travail connecté. Stream Deck Mobile utilise la même intégration.
Détails techniques et liste des modèles : Stream Deck, contrat de navigation par groupes sur le périphérique.
Tâches individuelles ou profil d’application Logitech
Logitech propose deux méthodes de configuration :
- Affecter les tâches individuellement : utilise Start a Single µGulp Task pour lier durablement un espace de travail et une tâche à une touche. Cela fonctionne pour les touches individuelles du keypad et Actions Ring (titres uniquement, SDK sans animation LCD). Le dossier du keypad affiche les icônes et les états d’exécution.
- Créer un profil d’application dans Options+, par exemple pour Cursor : la disposition de touches configurée s’active automatiquement lorsque l’application passe au premier plan. Sur le keypad, General µGulp Functions ouvre les tâches de l’espace de travail correspondant avec icônes et indicateurs d’exécution en direct. Dans l’IDE, le plugin µGulp™ suit l’espace de travail de la fenêtre active ; la sélection manuelle reste prioritaire jusqu’à sa désactivation ou à la perte de la connexion.
Options+ choisit donc la disposition de touches de l’application, tandis que µGulp™ choisit l’espace de travail. Configure le profil une fois dans Options+. Un changement d’application peut fermer le dossier dynamique ; appuie sur la touche µGulp™ pour le rouvrir. Actions Ring utilise des affectations fixes d’une tâche ; la liste dynamique et ses icônes sont destinées au keypad.
Logitech MX utilise l’image du projet fournie par l’hôte connecté pour la sélection du workspace et la touche µGulp™, avec l’image de marque comme remplacement. La validation complète sur appareil reste à faire. L'ouverture programmée du Dynamic Folder et la navigation indépendante sur plusieurs appareils MX physiques ne sont pas garanties ; les questions SDK restent ouvertes. La prise en charge existante de Logitech demeure limitée et expérimentale.
ENIAC Flexbar
Le plugin Flexbar relie les actions configurées dans FlexDesigner aux tâches µGulp™ et à leurs états d’exécution (même sémantique que Stream Deck). Les tests sur une Flexbar physique sont encore en attente.
Configuration technique et création des plugins : Stream Deck, Logitech, Flexbar.
Planificateur de tâches (session)
Les programmes de session décident uniquement quand une tâche démarre ; l’exécution suit le chemin normal de StartTask (secteur du tableau de bord, journaux et états matériels inchangés).
| Mode | Déclaration | Résumé |
|---|---|---|
| Minuterie | µSchedule = { after: '10s' } |
une fois après le délai |
| Intervalle | { every: '10s' } |
répétition ; nextRun après chaque exécution |
| Répétition | { every: '5s', repeat: 5 } |
completed après n exécutions |
| Cron | { cron: '*/1 * * * *' } |
5 champs, heure locale de l’hôte (croner) |
API impérative : ScheduleTask, SetScheduleEnabled, CancelSchedule, RunScheduleNow (gulp-mu-gulp-api). Tableau de bord : compte à rebours depuis nextRun, Enable/Disable/Cancel/Run now. Tant que µWatch est armé ou que la tâche s’exécute, le démarrage planifié est ignoré (schedule-skipped). Les touches matérielles peuvent afficher un compte à rebours ou n/m. Détails et démos A-G : TaskScheduler.md.
Manettes, gamepads et joysticks
Les manettes, joysticks et autres périphériques compatibles peuvent servir de contrôleurs configurables pour les workflows. Active leur prise en charge sous Settings → Controllers ; la configuration comprend des profils, l’apprentissage des boutons et axes, les zones mortes, la sensibilité et les diagnostics en direct. Les affectations peuvent lancer ou arrêter des tâches et contrôler la vue d’ensemble.
Sous Windows x64, la détection fonctionne aussi lorsque le tableau de bord n’est pas actif. Node.js 22 ou ultérieur doit être installé. Les composants natifs ne sont pas encore inclus pour les autres systèmes de bureau ; les navigateurs compatibles fournissent l’API Gamepad comme solution de remplacement.
La 3Dconnexion SpaceMouse Wireless dispose d’un profil mesuré sur le périphérique avec six axes et deux boutons. Configure les autres périphériques avec un étalonnage et des affectations personnalisées. Si une manette prend en charge les vibrations, un retour facultatif peut signaler le démarrage, la réussite ou l’échec d’une tâche. Sa portée et son effet dépendent du périphérique.
Configuration, profils de périphériques et diagnostics : documentation des manettes.
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, plus identité de projet optionnelle dans microgulp.config.json) utilisez le prompt maintenu dans le dépôt :
| File | Purpose |
|---|---|
dev/prompts/OptimizeGulpfileForMicroGulp.md |
Prompt copier-coller pour Cursor, Claude, ChatGPT, … (première migration) |
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json |
Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version) |
dev/prompts/EnhanceExistingMicroGulpProject.md |
Examiner un projet µGulp™ existant pour des fonctions récentes facultatives (aucune activation aveugle) |
Le prompt de migration couvre désormais aussi µTaskKind, µPresentation, µExecutionType, µAttentionWatch et l’attente d’une saisie et une identité project sensée (titre / mini-description / logo existant ; fusion de config uniquement). Les glyphes µIcon et les associations µIconFont existants sont conservés. Le cœur gère les états d’exécution ; services persistants, déclencheurs de fichiers et alertes restent distincts. Les intégrations matérielles s’activent par espace de travail et sont incluses dans toutes les éditions sauf µGulp™ Free ; les tests Flexbar sur matériel réel restent en attente. Avant la migration, compare les versions requises du produit et de l’API à l’état actuel du projet.
Le prompt impose également les valeurs formatées par i18x : int pour les compteurs, floatFix1 / floatFix2 pour les décimales, byteSize pour les octets, progressDuration pour les millisecondes et les formats de date/heure. FormatValue() est disponible pour les sorties structurées. Les dictionnaires du projet sont actualisés avec les définitions <format> correspondantes ; les traductions existantes sont conservées. Les limites provisoires du moteur personnalisé sont respectées.
Pour le regroupement et l’arborescence des tâches, le prompt couvre µGroup, µOrder, µGroups, SetGroupState, RevealTask et SetTaskEmphasis. Les instructions matérielles expliquent le navigateur de groupes Stream Deck (touche d’entrée et profils avec emplacements dynamiques), les tâches Logitech fixes, y compris Actions Ring, et les profils d’application Options+ avec sélection de l’espace de travail par µGulp™.
Workflow
- Copie l’exemple de paramètres à la racine du projet sous
microgulp-optimize.params.json, puis renseigneprojectRoot,gulpfilePath,supportedLanguages(par exempleen-US,de-DE,zh-CN),gulpMuGulpApiVersion(référence locale^0.6.0; vérifie la version installée/publiée),microGulpMinVersion(1.0.0) etgithubRepoUrl/githubRef(par défaut :https://github.com/mamekudz/microGulp, une référence vérifiée telle quemain). - Ouvrez le markdown du prompt, remplacez la table
{{PLACEHOLDER}}par vos valeurs (ou joignez le fichier params et le gulpfile dans Cursor). - 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. - 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 validezgulpfile.mjs,i18x/gulp/*.jsonetpackage.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) |
Le groupe Scheduler demos (A-G) illustre les programmes de session (µSchedule) : minuterie ponctuelle, intervalle, répétition, Cron, chevauchement ignoré, échec planifié et Watch+Schedule. Toutes les démos sont désactivées au départ (autoStart: false) ; active-les individuellement avec leurs boutons d’icône. Détails et API : dev/docs/TaskScheduler.md.
Détails API supplémentaires : gulp-mu-gulp-api/README.md.
µGulp™ Ready
Un projet propose au moins une interaction ou sortie utile propre à µGulp, documente un accès Gulp/CLI normal et vérifie lui-même les deux modes. La compatibilité Gulp ou des métadonnées décoratives seules ne suffisent pas. Le badge est gratuit selon les règles publiées, sans demande ni certification officielle.
Exigences et utilisation du badge (anglais).
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âcheSHOW_VERSION_HISTORYounpm run history).BUILD_PACKAGEsynchronise la versionpackage.jsonet la ligne de version en tête de ce README depuisRELEASES.jsonautomatiquement 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 deRELEASES.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-cssest câblé comme dépendancefile:locale surC:\Projects\microCSS\gulp-mu-csset - comme chaque paquet lourd - n'est chargé que dans le corps de la tâche viaawait import().BUILD_PACKAGEproduit un vrai.vsixune fois@vscode/vsceinstallé (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.mjset une source<name>.µ.cssdu même nom.CREATE_THEME_DATAdé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) ; ledashboard.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 estdev/media/final/; le build synchronisemedia/logo.png(icône d'extension),media/logo_readme.png(README),src/webview/skins/<name>/imgs/baselogo.svg(tableau de bord) etjetbrains/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). Cette commande copie et ouvre un gulpfile d’exemple avec tâches de démonstration et de compilation (progression, formulaires, journaux structurés, sons, fenêtres modales, compte à rebours, icônes personnalisées, présentation d’échec, service persistant et Attention/Reset) sous ~/.microgulp/sample. Utilise ensuite µGulp: Open Dashboard. Le manuel utilisateur se trouve sous Settings → Handbook (ou µGulp: Open Handbook) ; toutes les langues y sont disponibles.
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
Déjà implémenté
[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 viai18x-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 (
.logbrut +.ndjsonstructuré, indexhistory.ndjson, rétention, panneau d'historique du tableau de bord)[x]
microgulp.config.jsonpour 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 dansdev/docs/MicroGulpSoundSchema.md[x] Identité du projet (
project.title/description/logodansmicrogulp.config.json; en-tête compact dans la liste des tâches)[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 Taskpour 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:-1garder 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/gulpdans le tableau de bord (parseur i18xe-sync, dialogue de langue cible, formats standard,<lid>.status.jsonpour la traduction IA)[x] États de tâche cohérents, 38 icônes sémantiques, indication de saisie, thème de secours et réduction des animations
[x] Arborescence des tâches et mise en évidence via
SetGroupState,RevealTasketSetTaskEmphasis[x] Huit fonctions API IDE et indicateurs visibles d'hôte/disponibilité
[x] Web Console, KnownProjectRegistry / Project Center, Open/Focus Project et Background Host commun
[x] Stream Deck : Follow, dernière vue par workspace et appareil, logos sur Root
[x] Intégrations Stream Deck/Mobile, Logitech et Flexbar ; Logitech avec affectations individuelles et dossier dynamique de keypad
[x] Profils de manette avec étalonnage et diagnostics ; entrées de bureau sous Windows x64 et profil SpaceMouse Wireless
Encore ouvert
[ ]
Ide.OpenUrlet exécution de tâches sans IDE via le Background Host : prévus, hors du périmètre 1.0.0 implémenté[ ] Logitech MX : validation physique, image de projet comprise, et questions SDK ouvertes sur Dynamic Folder et plusieurs appareils
[ ] Stream Deck : validation physique multi-appareils et interaction avec Elgato Smart Profiles
[ ] Flexbar : tests sur matériel physique
[ ] Composants natifs de manette pour Linux et macOS
[ ] 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.mjsdeµLibavec 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)
[x] Fiche JetBrains Marketplace (plugin 34255 ; la présence dans le registre n'est pas une installation fraîche vérifiée dans chaque IDE)
[x] Fiches VS Code/Cursor sur Microsoft Marketplace et Open VSX (enregistrée et Free)
Web Console et Project Center
La Web Console locale réunit projets connus et connectés dans le Project Center. Elle intègre le tableau de bord existant avec tâches, Project Controls, paramètres, historique et événements en direct ; elle ne crée pas de seconde TaskEngine. Ouvrir via µGulp: Open Web Console dans VS Code/Cursor, Open Web Console dans la fenêtre d'outils JetBrains ou npm run console -- open dans le dépôt de développement. La Console utilise HTTP/SSE local sans plugin de navigateur et écoute seulement sur 127.0.0.1 ; ce n'est pas un accès LAN ou distant.
Projets connus et sessions
La KnownProjectRegistry conserve chemin du projet, ProjectId, titre, description, logo, IDE préféré et dernier contact dans ~/.microgulp/known-projects.json. Les métadonnées viennent de microgulp.config.json. La vue distingue connecté, fermé et indisponible. Une entrée connue n'est pas un moteur actif. Les sessions IDE actives sont suivies séparément ; plusieurs fenêtres d'un même projet sont sélectionnables individuellement.
Follow active IDE project suit le contexte de projet actif commun. Une session choisie manuellement est fixée uniquement dans cet onglet, sans modifier le pin du contrôleur. Lorsqu'une autre application est au premier plan, la dernière session affichée reste visible tant qu'elle est active.
La vue des projets et le tableau de bord intégré restent accessibles dans µGulp™ Free ; les droits habituels des tâches s'appliquent. L'administration de l'hôte reste disponible. Open/Focus Project, Start Application, actions IDE et choix de l'IDE préféré sont vérifiés côté serveur à chaque appel pour les droits d'édition et d'enregistrement. Une autorisation manquante renvoie unsupported-edition ou unsupported-registration.
Ouvrir et activer des projets
Open/Focus Project utilise la famille IDE, le produit et l'installation choisis. Une session correspondante active sa fenêtre. Plusieurs résultats exigent un choix de session. Un échec d'activation ne lance pas un deuxième IDE ; l'activation exacte de fenêtre est actuellement propre à Windows. Sans session correspondante, le projet connu s'ouvre dans l'installation choisie. Les demandes parallèles sont regroupées ; sans confirmation du démarrage, une nouvelle tentative explicite est nécessaire. Un démarrage lent peut donc sembler temporairement non confirmé.
Les installations Windows connues de l'utilisateur sont détectées. D'autres installations IDE et applications peuvent être configurées dans ~/.microgulp/applications.json avec un chemin exécutable absolu et des arguments fixes facultatifs ; JetBrains exige le produit précis. Start Application démarre une application connue sans commande shell. L'activation générale d'applications tierces arbitraires est hors périmètre. La détection de Windsurf est expérimentale, pas une homologation d'un autre IDE.
Background Host
Un Background Host commun fournit Web Console, projets connus, projet actif et contexte des contrôleurs - un processus par utilisateur, indépendant de l'IDE. Le premier IDE le démarre au besoin ; fermer un IDE ne l'arrête pas. Le démarrage à la connexion facultatif rend la Console accessible sans IDE ouvert sur http://127.0.0.1:47821/console. Sans IDE, il liste les projets connus ; avec les droits d'édition requis, ils peuvent s'ouvrir dans Cursor, VS Code ou JetBrains. Les tâches se commandent via une session IDE connectée. L'exécution sans IDE et le transfert automatique du propriétaire du moteur ne font pas partie de 1.0.0.
Les paramètres valent pour tous les IDE et sont conservés uniquement dans host-settings.json : Start at login et Show background UI sont indépendants. Masquer l'interface n'arrête pas l'hôte. Le port est global (47821 par défaut, de 1024 à 65535). Une modification redémarre l'hôte actif et déplace la Console vers la nouvelle adresse. Si une autre application occupe le port demandé, le précédent est conservé. Aucun port aléatoire ni champ d'adresse d'écoute : seulement 127.0.0.1.
Au premier démarrage, µGulp™ demande une fois par utilisateur, pas par IDE : Enable µGulp Background Host? Enable active le démarrage à la connexion. Not now le laisse désactivé ; un IDE peut toujours démarrer l'hôte au besoin.
Les mêmes commandes sont disponibles dans VS Code et Cursor (µGulp: Background Host Settings), JetBrains (Settings → Tools → µGulp Background Host et Background Host dans la fenêtre d'outils), la section Background Host de la Console et via npm run console -- status|open|restart|stop|port <n>|autostart on|off|ui on|off. Le menu de zone de notification Windows ouvre la Console, affiche état, IDE connectés et projets connus, et bascule le démarrage à la connexion. Le port ne s'y modifie pas. Stop arrête seulement l'hôte ; un IDE peut le redémarrer plus tard.
| Plateforme | Démarrage automatique | Interface système |
|---|---|---|
| Windows | Entrée de connexion utilisateur | Zone de notification (facultative ; fonctionnement sans interface possible) |
| macOS | LaunchAgent | Barre de menus préparée, pas encore testée sur matériel macOS |
| Linux | Démarrage XDG | Sans interface ; aucune dépendance à une zone de notification |
Les textes de la Console existent actuellement en allemand et anglais ; les autres langues utilisent l'anglais. Les commandes de l'hôte disposent de leurs propres textes localisés. L'API complète implémentée est décrite dans Actions IDE depuis les tâches.
Español
Rock your Gulp!
µGulp™ añade a Gulp un dashboard interactivo para VS Code, Cursor y los IDE JetBrains. Las tareas reciben nombres dinámicos, grupos claros, iconos, descripciones y ayudas emergentes. Así se ve qué tarea pertenece a qué proyecto y destino, si se ejecuta y si ha terminado correctamente. Formularios, progreso y salidas independientes en directo acompañan la ejecución. La CLI Gulp normal sigue disponible; siguen siendo necesarios los paquetes y valores de entrada adecuados. IA y MCP son opcionales.
Para empezar: instalar la extensión del IDE, abrir un proyecto con gulpfile e iniciar una tarea en el dashboard µGulp™. Se necesita Node.js 22 o posterior y los paquetes del proyecto. Gulp es una herramienta JavaScript para tareas recurrentes; el gulpfile las describe. µGulp™ añade la interfaz de control.
Funciones destacadas
Estado de la versión 2.1.0, 20/10/2026: en comprobación local, aún sin publicar. Las tareas globales, el inicio adaptado y la presentación de las tareas de proyecto están implementados. Las validaciones anteriores siguen asociadas a sus respectivas versiones; superar una prueba parcial no constituye una aprobación completa. Los procesos verificados y sus límites se documentan más abajo.
- NUEVO en 2.1.0: Diseñar tareas de proyecto comprensibles - elige el idioma de edición, pide al agente del IDE existente que proponga los textos fuente en inglés y las traducciones que falten, y comprueba directamente símbolos o imágenes propias. El Gulpfile se mantiene en en-US; las traducciones van a
i18x/gulp/<sprache>.json. La vista previa, la copia de seguridad y la reversión abarcan ambos archivos. - Nombres dinámicos, grupos, iconos y ayudas emergentes - nombres comprensibles en lugar de simples funciones; valores actuales como versión o destino, grupos anidados y plegables, iconos propios, descripciones y ayudas.
µDisplayName,µGroup,µIcon,µDescriptionyµTooltipadaptan la lista al proyecto. Los textos se pueden localizar;µOrderordena tareas y grupos yµGroupsdefine el estado inicial. - Precarga de tareas - los workers de Node ya han importado el gulpfile y reducen el tiempo de inicio cuando hay un worker preparado; resulta especialmente útil con importaciones costosas y análisis antivirus en tiempo real
- Estados de las tareas de un vistazo - inicio, ejecución, espera de datos, detención, éxito y error tienen una presentación coherente; los bordes de estado siguen visibles con iconos personalizados
- 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, …)
- 🔴 NUEVO en 2.1.0: Un inicio adecuado para tu Gulpfile existente - detectar tareas ya adaptadas, completar solo los datos de presentación que falten y revisar cada cambio antes de aplicarlo. Las demás recetas de IA son opcionales; los atajos de teclado que falten son solo una sugerencia.
- 🔴 NUEVO en 2.1.0: Gestionar varios proyectos con una tarea común - iniciar, por ejemplo, copias de seguridad NAS o comprobaciones de proyectos mediante un ID común como
NASBU. Selecciona los proyectos por su título e icono, guarda previamente la configuración de cada uno y revísala antes del inicio conjunto. Cada proyecto conserva su propia implementación, salida e historial. - 🔴 NUEVO en 2.0.0: Asistente y recetas de IA - añadir metadatos con formularios, integrar copia NAS o microCSS y preparar configuración inicial y publicaciones GitHub/npm. Revisar antes todos los cambios, aplicar con respaldo y deshacer si no se modifican después. Las tareas preparatorias no publican.
- 🔴 NUEVO en 2.0.0: Grupos de proyecto y versiones - ordenar bajo nombre del proyecto/Info, Build, Tools y Maintenance; revisar y aplicar conjuntamente el incremento npm y los lockfiles existentes.
- 🔴 NUEVO en 2.0.0: Conectar el agente IA existente - configuración y mantenimiento por MCP en Cursor o IntelliJ, sin clave API µGulp™ adicional por defecto. Cursor también ofrece una app gráfica en el chat.
- 🔴 NUEVO en 2.0.0: Traducciones selectivas - proponer solo textos ausentes o detectados como modificados frente a una referencia en diccionarios JSON planos, revisar marcadores y aplicar cambios comprobados con respaldo y deshacer. Usted elige origen y destino.
- 🔴 NUEVO en 2.0.0: Ayuda para mantener manuales - mostrar qué adaptar en su DOCX después de cambios de código, con referencias. Usted elige documento, idioma y reglas; la edición sigue en sus manos.
- Conservar perfiles y restaurar conexiones - los perfiles 1.0.0 siguen funcionando; reconectar el dashboard tras terminar el motor IntelliJ, elegir sesión nueva y revisar propuestas nuevas. Las tareas no se repiten automáticamente.
- Web Console y Project Center - proyectos conocidos con título, descripción, logotipo y estado de sesión en un centro local; abrir paneles existentes en el navegador, seguir el proyecto IDE activo o fijar una sesión solo para esta pestaña (vista general y administración del host también en Free)
- Open/Focus Project - abrir un proyecto conocido en una instalación IDE concreta o enfocar su ventana existente; elegir explícitamente la sesión si hay varias (no en Free; enfoque exacto de ventanas actualmente en Windows)
- Background Host - Web Console y contexto del proyecto activo compartidos en un proceso por usuario; inicio al iniciar sesión opcional y ajustes comunes, incluso sin IDE abierto; el host no inicia por sí mismo un motor de proyecto
- Identidad del proyecto - título de proyecto opcional, mini descripción y logo directamente encima de la lista de tareas; especialmente útil con varios proyectos o ventanas IDE abiertas (
microgulp.config.json→project) - Project Controls - fila compacta de selectores, botones de opción y casillas bajo la identidad del proyecto para su estado global (p. ej., destino); efecto inmediato en nombres, visibilidad de tareas/grupos y ejecución; valores por workspace en
.microgulp/project-controls.json - Estados animados de las tareas en directo - el hardware compatible (Stream Deck, teclados Logitech, Flexbar) muestra el estado real de ejecución del mismo motor que el panel, más allá de los iconos estáticos: inicio, animación durante la ejecución, espera de datos, detención, éxito, error (incluidos Burn/Charred) y desactivación; las activaciones de vigilancia y las cuentas atrás del programador aparecen como superposiciones adicionales. La animación informa del estado, no es decorativa. (no disponible en µGulp™ Free; pendiente de probar Flexbar con hardware real; Actions Ring: solo títulos, SDK sin animación LCD)
- 38 iconos semánticos para tareas - diseños SVG coherentes mediante
µTaskKind/µPresentation, animaciones durante la ejecución, icono de diálogo violeta cuando se necesita una entrada, adaptaciones al tema y compatibilidad con movimiento reducido; si la tarea falla, el diseño original aparece chamuscado - Programador de tareas (sesión) -
µSchedule/ScheduleTaskcon temporizadores (after), intervalos (every), repeticiones (repeat) y Cron (5 campos, hora local); cuenta atrás en el panel y controles Enable/Disable/Cancel/Run now; el hardware muestra una cuenta atrás on/men la tecla. La ejecución sigue el flujo normal deStartTask - Control de servicios persistentes -
µExecutionTypedistingue las tareas puntuales de los procesos persistentes; se pueden detener los servicios en ejecución - Controlar el árbol de tareas desde el gulpfile -
SetGroupState,RevealTaskySetTaskEmphasisdespliegan grupos, muestran el siguiente paso y añaden o quitan el resaltado - Vigilancia en vivo del gulpfile - el watcher del workspace reescanea al guardar y sustituye automáticamente los workers obsoletos
- Seguir usando la CLI Gulp - los metadatos no cambian nombres exportados. Los paquetes API importados siguen siendo necesarios; entradas requieren valores CLI o predeterminados adecuados y acciones IDE un host apropiado (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íai18x-catalogcon 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); se prevén otros paquetes de interfaz descargables e instalables para 2.2.0. El manual del usuario está disponible como PDF para cada idioma incluido con el panel
- Sincronización de diccionarios para sus gulpfiles - Settings → Project i18x (gulp) escanea las fuentes con el parser i18xe-sync, escribe
i18x/gulp/<lid>.jsonpara los idiomas que elija, conserva las traducciones existentes y fusiona los formatos estándar; un sidecar<lid>.status.jsonlista lo que una IA local aún debe traducir - Parámetros de tarea declarativos -
µParameterspregunta una vez antes de la ejecución, entrega los valores comoMICROGULP_PARAMS/GetParameters(), recuerda las últimas respuestas, mantiene las contraseñas fuera de los registros y puede ocultar campos convisibleWhen - Tareas watch / disparo - los globs
µWatchejecutan una tarea al cambiar archivos, con debounce, coalescencia y disyuntor ante descontrol; se arma por tarea desde el panel - Compatibilidad con hardware - ya se admiten Elgato Stream Deck, Logitech MX Creative Console / Actions Ring, Flexbar y mandos, para llevar el control de Gulp a otro nivel. Incluido en todas las ediciones excepto µGulp™ Free (configuración y estado del dispositivo).
- Logitech sigue el espacio de trabajo - asignaciones fijas de tareas individuales o un perfil de aplicación de Options+; el plugin muestra en la carpeta dinámica del teclado el espacio de trabajo de la ventana del IDE activa
- Stream Deck sigue al workspace - Follow adopta el proyecto de la ventana IDE activa, recuerda la última vista por workspace y dispositivo y muestra logotipo y título en Root. Ruta de grupo y página se restauran al volver. (Validación con varios dispositivos pendiente; Elgato Smart Profiles sin garantía. Logitech mantiene su alcance limitado; Flexbar no sigue automáticamente.)
- Mandos para tus flujos de trabajo - gamepads y joysticks con perfiles personalizados, aprendizaje de entradas, zonas muertas y diagnósticos; en Windows x64 también funcionan sin el foco del panel e incluyen un perfil medido de SpaceMouse Wireless y vibración opcional en los dispositivos compatibles
- Ocho funciones de la API IDE - consultar capacidades y proyectos conocidos, ejecutar acciones IDE semánticas o nativas, abrir/enfocar proyectos e iniciar aplicaciones configuradas;
µHost/µIdeApiindican disponibilidad. Las funciones ejecutoras no están en Free;Ide.Capabilities()informa de las capacidades del host (alcance de la API). - Atajos de tarea - acordes
µKeyBindingcon variantes por plataforma (ctrl+shift+F1,cmd+shift+Escape), insignias y avisos de conflicto;µGulp: Run Taskpara 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(.logcrudo +.ndjsonestructurado), un índicehistory.ndjsonsobrevive a reconexiones/reinicios del IDE; un panel de historial abre cada transcripción (logToFile,logRetention) - Selección nativa de archivos y carpetas - los campos de archivo de los formularios abren el selector de VS Code/Cursor o JetBrains y devuelven la ruta real
- Diálogos modales -
ShowModalMessage/ShowConfirmMessagecomo paneles de cristal estilo AiDPix en el panel (info/aviso/error, Sí/No, OK/Cancelar); modales nativos opcionales de VS Code/Cursor víapresentationomicrogulp.modalPresentation(gulp-mu-gulp-api); sección README propia - Ubicaciones de error clicables -
file:line:columnen 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/dashboardFontspara el glifoµIcony las tipografías del registro;µIconFontopcional 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(-1mantener abierto, un número positivo = segundos, omitido usa Settings → Finished Runs, 30 s por defecto); Restart junto a Close - Resaltado de tareas pendientes sin iniciar una tarea -
µAttentionseñala el trabajo que requiere atención;µAttentionWatchactualiza el aviso tras cambios de archivo o a intervalos, con información emergente, versión instalada e indicadores visibles incluso en grupos contraídos - Elevación a administrador en Windows - solicitud UAC opcional por tarea (
µRequiresElevation,µElevationReason); el IDE puede funcionar normalmente mientras algunas tareas, como editar el archivohosts, se ejecutan con permisos elevados (no disponible en µGulp™ Free) - Motor de diagnóstico - los errores de importación y las trazas de pila se convierten en sugerencias útiles en el panel (no disponible en µGulp™ Free)
<version/>desde el gulpfile -µI18xContext.versiones la fuente preferida para los títulos de tarea;versionSourcesopcional solo rellena cuando el gulpfile omiteversion(sin sobrescribir las configs de release del consumidor)- LogError fiable frente a avisos de Node -
LogError/ unconsole.errorreal siguen fallando la ejecución;DeprecationWarningde 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/promptsredirigidos 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
Diseñar tareas de proyecto en el idioma deseado
Configurar tareas del proyecto define la presentación de las tareas existentes en el Gulpfile del proyecto seleccionado. Las tareas globales que abarcan varios proyectos se gestionan por separado y este asistente no las modifica.
El idioma de edición se aplica a los nombres visibles, descripciones, ayudas emergentes y grupos propuestos. El selector utiliza la lista de idiomas mantenida de forma centralizada en el proyecto i18xe, con códigos de idioma y nombres nativos; también puedes introducir otros códigos de idioma BCP 47 válidos. La selección se rellena a partir de microgulp.editingLanguage en package.json. Si falta este ajuste, el formulario utiliza el idioma del navegador de la vista web del IDE. El idioma de la interfaz es independiente; puedes cambiar el idioma de edición antes de cada solicitud.
Preparar sugerencias de texto con el agente del IDE crea una solicitud limitada a los campos de texto que faltan. El Gulpfile siempre contiene textos fuente en inglés en-US; para otro idioma de edición, el asistente añade las traducciones correspondientes a i18x/gulp/<sprache>.json. Las traducciones existentes no se sobrescriben. En el panel, copia la solicitud mostrada al chat del agente de Cursor o IntelliJ conectado; la app MCP gráfica ofrece Enviar al agente del IDE si el cliente admite mensajes. El agente existente genera los textos y los devuelve mediante MCP. No se necesita ninguna clave API adicional. El asistente no inicia un agente en segundo plano ni utiliza un servicio alternativo de pago.
Cargar sugerencias en el formulario muestra las propuestas comprobadas. Se conservan los metadatos, las claves de traducción, los valores calculados y los campos editados manualmente mientras tanto. La solicitud caduca a los diez minutos y se rechaza si ha cambiado el Gulpfile o el diccionario. La vista previa muestra ambos archivos juntos; solo la aplicación explícita con copia de seguridad escribe el Gulpfile y el diccionario, y la reversión restaura el estado anterior. La revisión lingüística y factual sigue siendo responsabilidad del usuario.
Los ocho idiomas de interfaz incluidos con µGulp™ son independientes de esta selección. Otros paquetes de traducción descargables o instalables para la interfaz de µGulp™ están previstos para la versión 2.2.0 y todavía no forman parte de este asistente.
Para los iconos, introduce un símbolo o emoji, o selecciona una imagen PNG, JPEG o WebP de hasta 64 KiB. Una vista previa directa muestra la selección. La imagen se incrusta en el Gulpfile, por lo que no depende de la ruta del archivo original. Aquí no se importan nuevos archivos SVG ni URL de imágenes. Los metadatos de icono existentes se conservan si se aplican sin cambios.
Mejorar un Gulpfile existente de forma selectiva
El asistente de configuración comprueba primero, de forma puramente estática, si tus tareas ya tienen metadatos de presentación para µGulp™. Un nombre visible, una descripción, un grupo, un icono o una ayuda emergente basta para indicar que la presentación de una tarea ya está adaptada. No es una evaluación completa de la calidad del Gulpfile. No todas las tareas necesitan todos esos datos.
Si todas las tareas detectadas ya están adaptadas, no aparece ninguna invitación automática a optimizarlas. En los Gulpfiles parcialmente adaptados, el diálogo solo propone tareas sin esos datos. Primero puedes añadir nombres, descripciones, grupos, iconos y ayudas emergentes, revisar la vista previa y aplicar los cambios explícitamente con copia de seguridad. La reversión sigue disponible. Después puedes acceder a otras recetas de IA, o hacerlo omitiendo este paso de forma deliberada.
Los metadatos calculados o importados no siempre pueden evaluarse sin ambigüedad. En ese caso, el asistente indica que se desconoce el estado de optimización y no modifica esos valores automáticamente. Los atajos de teclado son solo una sugerencia opcional; su ausencia no se considera una necesidad de optimización. Tampoco es un defecto que no haya una asignación a tareas globales. Las demás recetas de IA y los atajos de teclado están inicialmente desmarcados en el segundo paso.
Tareas globales para los proyectos seleccionados
Con las tareas globales ya no tienes que buscar e iniciar la misma tarea por separado en cada proyecto. Un ID común conecta las implementaciones correspondientes de tus proyectos: NASBU puede, por ejemplo, guardar carpetas distintas en cada proyecto. La Web Console muestra los proyectos participantes con su título e icono; tú seleccionas expresamente cuáles deben iniciarse.
La definición global consta de un ID estable y un título comprensible. La implementación ejecutable permanece en el Gulpfile de cada proyecto. Este mecanismo no distribuye código fuente común ni copia tareas automáticamente a otros proyectos. Distintos proyectos pueden implementar el mismo ID según sus propias necesidades.
Añade µGlobalTask = { id: "NASBU", title: "NAS-Sicherung" } a la tarea exportada. Los ID comienzan con una letra mayúscula y contienen como máximo 64 letras mayúsculas, dígitos, guiones bajos o signos menos. Cada proyecto puede ofrecer un ID una sola vez. Las tareas marcadas aparecen en el panel del proyecto dentro de su propio grupo Tareas globales; cualquier µGroup existente se sustituye para estas tareas.
Abre la Web Console y despliega Tareas globales. Actualiza la lista y selecciona la tarea común. En Configurar proyecto, guarda una vez los valores de µParameters para el proyecto correspondiente. Se almacenan localmente en .microgulp/global-tasks.json. Si cambia la definición de los parámetros, es necesario volver a configurarlos. Las contraseñas y los valores marcados con remember: false no se guardan aquí; esas tareas siguen requiriendo el uso interactivo desde el proyecto.
En Definir una tarea global puedes establecer el ID y el título de forma centralizada. La lista también detecta los ID de los proyectos conectados. Un título centralizado unifica la visualización; no crea ninguna implementación ejecutable. Las definiciones se guardan en el directorio del usuario, en .microgulp/global-tasks.json.
Selecciona los proyectos por su título e icono. Si hay varias ventanas del IDE para un mismo proyecto, elige exactamente una sesión. Revisar selección muestra exclusivamente esos proyectos y sus valores guardados. Solo Iniciar tareas seleccionadas envía la ejecución a cada IDE. Los proyectos o IDE cerrados no se abren automáticamente.
El inicio conjunto utiliza los parámetros guardados sin mostrar nuevos formularios de entrada. Si la tarea solicita aun así un diálogo de µGulp, esa ejecución falla con global-task-dialog-required. Las tareas que requieren privilegios elevados de Windows y las tareas de ejecución permanente no se inician globalmente. El código Gulp sigue siendo código ejecutado localmente; los programas externos con sus propios diálogos no se convierten por ello en tareas desatendidas.
Las vistas previas tienen una validez limitada y solo pueden utilizarse una vez. Los cambios en el Gulpfile, la definición de la tarea, los parámetros guardados o los Project Controls las invalidan. Si la sesión del IDE termina o cambia, debes volver a seleccionar y revisar. Todas las sesiones seleccionadas se comprueban antes del primer inicio.
Un inicio conjunto no es una transacción: si una conexión falla después del primer inicio, los proyectos anteriores pueden estar ya en ejecución. El resultado muestra los proyectos iniciados, los fallidos y los que aún no se han iniciado. No hay reintentos automáticos ni reversión automática de las tareas ejecutadas. El progreso, los registros y la opción de detener están disponibles en el panel de cada proyecto.
Iniciar una tarea en otro proyecto
Una tarea del proyecto A puede usar RunGlobalTask de gulp-mu-gulp-api para iniciar en el proyecto B una implementación marcada con µGlobalTask y esperar a que termine. Indica el ID exacto del proyecto y el ID de la tarea global. Los parámetros de destino deben haberse configurado previamente en el panel del proyecto B. El proyecto B necesita una conexión activa con su panel de µGulp abierto. Si hay varias sesiones abiertas para el proyecto de destino, indica también el sessionId de la sesión deseada. Los proyectos o IDE cerrados no se abren automáticamente.
import { RunGlobalTask } from 'gulp-mu-gulp-api';
const result = await RunGlobalTask({
projectId: 'Projekt-ID-von-B',
globalId: 'DEPLOY',
timeoutMs: 120000
});
if (!result.ok) throw new Error(result.error ?? result.code);
console.log(result.taskResult);
La respuesta contiene el estado, el ID de ejecución y la duración. taskResult solo está presente si la tarea de destino ha llamado a ReportTaskResult. La llamada inicia la tarea de destino mediante su sesión del IDE conectada; no se abre ninguna ventana visible de la Web Console. Se rechazan las llamadas a sí mismo y las cadenas recursivas de proyectos. El tiempo de espera va de 1 a 300 segundos; el valor predeterminado es de 120 segundos. Cuando se agota el tiempo de espera, la tarea de destino puede haberse iniciado ya.
Las llamadas globales requieren una sesión del IDE activa y de confianza con el panel de µGulp abierto, además de una edición con acceso a la API del IDE. Se mantienen la vista general de proyectos y el manejo sencillo de tareas existente. La ejecución autónoma de proyectos cerrados en el Background Host, los botones físicos globales y las herramientas MCP globales no forman parte del alcance de esta versión 2.1.0.
Ediciones y funciones
µGulp™ está disponible 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). La comparación siguiente refleja las ediciones actuales. No instales la extensión registrada de VS Code junto a µGulp™ Free: comparten los ID de comando. Registra la edición completa de VS Code antes de ejecutar la primera tarea o desinstálala y usa µGulp™ Free. JetBrains no requiere registro de µGulp™ y no tiene edición 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, precarga, i18x, parámetros, µWatch, µSchedule, 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í |
| Integraciones de hardware (Stream Deck, Logitech, Flexbar) | sí | - | sí |
| Acciones del IDE desde las tareas | sí | - | sí |
| Web Console: proyectos, estado de sesiones, panel integrado | sí | sí, se aplican los permisos habituales de las tareas | sí |
| Background Host y administración del host | sí | sí | sí |
| Open/Focus Project, Start Application, acciones IDE, IDE preferido | sí | - | sí |
| Ajustes del host | microgulp.* |
microgulp.* |
Settings → Tools → µGulp |
| Marketplace | Instalar para VS Code · Instalar desde Open VSX | Instalar µGulp Free · Instalar desde Open VSX | Instalar para JetBrains (de.amekudzi.microgulp) |
Todas las ediciones son gratuitas actualmente (0 € / 0 $ al mes y al año). Los puntos siguientes describen el producto completo. Free sigue el tema del IDE/sistema con IDE Dark / IDE Light (sin selector de apariencia) y no incluye paquetes de temas, diagnósticos, elevación, integraciones de hardware ni acciones del IDE. La Web Console local sigue disponible en Free: proyectos, estado y administración del host; las acciones avanzadas (Open/Focus Project, Start Application, acciones IDE, IDE preferido) quedan reservadas a las otras ediciones.
Novedades de 2.0.0
El asistente añade recetas de IA a proyectos existentes y muestra todos los cambios de archivos antes de aplicarlos. También incorpora la conexión MCP opcional al agente del IDE y ayudas para traducción y mantenimiento de manuales. El uso diario sigue siendo sencillo: abrir el proyecto, elegir una tarea e iniciarla.
Un generador general de workflows con IA, la optimización semántica de tareas arbitrarias y la autooptimización evolutiva son ideas sin implementar, sin alcance ni fecha prometidos.
Disponible desde 1.1.0
La información opcional del formulario aparece antes de los campos. Las tareas pueden activar expresamente la cancelación y el almacenamiento de las selecciones permitidas. µI18xContext.GetValues() proporciona metadatos síncronos en cada análisis; los marcadores modificados también actualizan la lista de tareas. Los gulpfiles existentes y las respuestas correctas siguen siendo compatibles. Las funciones están documentadas en gulp-mu-gulp-api 0.7.0.
Contrato de formularios y ejemplos · Notas de 1.1.0
Asistente de configuración y recetas de IA
Configurar tareas del proyecto abre el asistente del dashboard para un gulpfile existente. Analiza estáticamente ESM/CommonJS, ofrece los campos adecuados y muestra todos los cambios antes de aplicarlos. Las nueve recetas de IA cubren nombres y descripciones, grupos libres y por proyecto, atajos, copias NAS, microCSS, configuración inicial y preparación de GitHub y npm.
- Copia NAS: identificador del proyecto, origen, varios destinos, modo, directorio o ZIP, método de copia y exclusiones. La simulación está seleccionada inicialmente; se muestran los identificadores de destino para prepararlos conscientemente. La configuración no accede al NAS.
- microCSS: manifiesto existente de confianza, directorios de origen y salida, compresión y vistas previas gráficas. Cada build usa un subdirectorio de salida nuevo.
- Aplicación segura: vista previa completa, comprobación del hash del origen, protección de archivos de receta de IA existentes, copia bajo
.microgulp/setup-backupsy deshacer la última aplicación no modificada en la misma sesión.
Las dependencias aparecen en la vista previa y después se instalan con npm install en el directorio de cada receta de IA. Los tres conceptos de preparación nuevos no requieren paquetes de receta de IA adicionales. Los imports del manifiesto microCSS también necesitan sus paquetes en el proyecto de origen. Tareas y análisis en curso bloquean los cambios. Las construcciones dinámicas del gulpfile pueden requerir ajustes manuales.
Preparar configuración inicial y publicaciones
Las recetas de IA Configuración inicial, Publicación GitHub y Publicación npm añaden tareas preparatorias al gulpfile existente. Cada receta de IA tiene un formulario para el nombre del proyecto y sus opciones. Las tareas muestran comprobaciones y comandos adecuados; no instalan dependencias ni ejecutan push o publicación. Aplicar en el asistente tampoco autoriza a publicar.
- Configuración inicial (
project-bootstrap): revisar archivo de paquete, estado Git, exclusiones, dependencias y scripts de build y pruebas existentes. En un proyecto nuevo, crear primero ungulpfile.mjsvacío y seleccionarlo. Los archivos de paquete ausentes se mencionan como preparación, no se crean silenciosamente. - GitHub (
github-release): elegirEigentümer/Repositoryy visibilidad. El plan guía inicio de sesión, revisión del remote y archivos, creación deliberada de un repositorio ausente, push del commit revisado y borrador de release con etiqueta comprobada. Crear el repositorio, hacer push y publicar siguen siendo pasos separados que deben solicitarse expresamente. - npm (
npm-release): elegir patch, minor o major, registro, acceso y canal. Incluir incremento de versión en la vista previa muestra la versión superior enpackage.jsony lospackage-lock.json/npm-shrinkwrap.jsonexistentes. Al aplicar, se guardan y modifican junto al gulpfile; deshacer los restaura byte por byte. Sin esa opción, el plan mantiene el incremento como paso pendiente.
El incremento automático admite versiones estables como 1.2.3; las preliminares y conjuntos de paquetes workspace requieren un proceso específico. Paquetes privados, lockfiles contradictorios o ajustes de publicación distintos bloquean el cambio automático. Si existe RELEASES.json, desactivar el incremento automático y usar la sincronización de versiones del proyecto. Mantener otras fuentes de versión propias mediante el proceso específico. Al iniciar las tareas preparatorias no se vuelve a aumentar una versión ya aumentada en la configuración.
Ni la vista previa ni el inicio de tareas consultan el registro. Por eso el plan npm exige verificar el registro, probar, compilar, inspeccionar el contenido e iniciar sesión antes de publicar realmente. El aumento local no confirma que la versión esté disponible en el registro. Un paquete publicado no puede publicarse otra vez con la misma versión. Publicación npm · Versionado npm · Borrador de release GitHub
Organizar tareas por proyecto
Cada una de las tres recetas de IA crea cuatro tareas bajo Nombre del proyecto/Info, Nombre del proyecto/Build, Nombre del proyecto/Tools y Nombre del proyecto/Maintenance. Info contiene revisiones de inventario y resultados; Build, preparación de compilación; Tools, ayudas y comprobaciones; Maintenance, configuración, versiones y preparación de releases. Los nombres empiezan por defecto con SETUP_PROJECT, PREPARE_GITHUB_RELEASE o PREPARE_NPM_RELEASE, seguidos de la categoría en mayúsculas.
Grupos por proyecto (project-structure) también clasifica tareas existentes seleccionadas: indicar el proyecto y una de las cuatro categorías por tarea. Nombres exportados y código no cambian. Esta receta de IA y la receta de IA libre Grupos de tareas no pueden aplicarse a la vez. La asignación aparece en la vista previa y se respalda.
MCP ofrece los mismos formularios y cambios con list_recipes, get_recipe, preview_setup, apply_setup y undo_setup. get_recipe y list_library también entregan instrucciones versionadas para el agente IDE, incluida la revisión de versión y autorización de publicación. No incluyen un skill IA separado que publique automáticamente. Hasta el 19 de octubre de 2026 se comprobaron también las recetas de IA de inicio, GitHub y npm mediante MCP en los clientes instalados Cursor e IntelliJ: vista previa, aplicación, lectura de archivos y deshacer. Se restauraron los hashes originales, incluidos paquete y lockfile en el incremento npm. En esas pruebas no se iniciaron tareas preparatorias, consultaron registros ni realizaron publicaciones.
Configuración mediante MCP
El adaptador MCP separado ofrece el mismo proceso con list_recipes, get_recipe, list_setup_files, analyze_gulpfile, preview_setup, apply_setup y undo_setup. list_projects, list_tasks y get_task proporcionan proyectos, sesiones IDE concretas y catálogo. Con open_setup_assistant, un cliente MCP Apps como Cursor abre la configuración gráfica en el chat: seleccionar y analizar gulpfile, marcar recetas de IA, rellenar formularios y comprobar todos los cambios. Aplicar y deshacer tienen botones independientes con las mismas protecciones del dashboard. Cursor puede pedir autorización para los llamados de la app. Los clientes sin MCP Apps usan las herramientas individuales.
Se necesita Node.js 22 o posterior y una sesión activa del host actualizado. Tras instalar las dependencias SDK separadas (npm ci --prefix <Installationsordner>/src/mcp --omit=dev --ignore-scripts), el cliente inicia node <Installationsordner>/src/mcp/microgulp-mcp.mjs --project <absoluter-Projektpfad>. Los cambios requieren además --setup-write-project <derselbe-Projektpfad>. Sin esa autorización de arranque solo se permite leer, analizar y previsualizar. Las propuestas se separan por proceso MCP y sesión IDE. Estas herramientas no inician tareas, instalan paquetes automáticamente ni publican.
Revisar sugerencias de texto y reconectar MCP tras una actualización
Abre Configurar tareas del proyecto y selecciona el Gulpfile, las tareas deseadas y el idioma de edición. Prepara la solicitud de texto solo cuando el agente del IDE esté conectado al servidor MCP de µGulp™. Copia la solicitud mostrada a ese chat. Deja el formulario abierto; la solicitud es válida durante diez minutos y pertenece al motor de proyecto actual.
Cuando el agente responda, pulsa Cargar sugerencias en el formulario dentro del mismo formulario. Revisa los nombres, descripciones, ayudas emergentes y grupos añadidos. La respuesta review-required solo significa que existe una propuesta; no confirma su calidad ni un cambio en el Gulpfile. Puedes corregir u omitir los textos inadecuados o poco informativos. El agente no debe inventar funciones desconocidas a partir del nombre de una tarea.
Revisa después la vista previa de los cambios y aplícalos con copia de seguridad si procede. Revertir este cambio restaura el estado guardado mientras no haya modificaciones posteriores. Una solicitud preparada directamente en el chat no se vincula automáticamente con un formulario ya abierto. Para el flujo mediante formulario, empieza por la solicitud que aparece en él. Prepara una nueva solicitud tras la caducidad, un cambio de idioma o un reinicio del motor.
Una actualización de la extensión puede cambiar el directorio de instalación. Comprueba la ruta a microgulp-mcp.mjs en la configuración MCP e instala las dependencias SDK separadas en el nuevo directorio src/mcp con npm ci --omit=dev --ignore-scripts. Que un servidor esté activado no demuestra que la conexión funcione. Si aparece Connection closed, comprueba el registro del servidor; si falta @modelcontextprotocol/sdk, esas dependencias no están en el directorio utilizado.
Vuelve a conectar el servidor MCP y abre un nuevo chat del agente. Comprueba la sesión actual con list_projects. Para las sugerencias de texto deben estar disponibles prepare_setup_text, get_setup_text y submit_setup_text. Si list_projects devuelve un proyecto sin sesión, abre su panel de µGulp™. Se necesitan tanto una conexión MCP accesible como un motor de proyecto activo.
App MCP gráfica en Cursor
- Abrir el proyecto y conectar el servidor MCP µGulp™ configurado. Ofrece herramientas de configuración, tareas, skills opcionales y un recurso UI.
- Pedir al agente: «Usa
list_projectspara identificar la sesión actual y abreopen_setup_assistantpara ella. Después no hagas más cambios». Expandir el resultado si la app está plegada. - Elegir gulpfile y Analyze gulpfile. Confirmar personalmente las autorizaciones solicitadas por Cursor. Seleccionar recetas de IA y completar campos: identificador NAS, origen y destinos; manifiesto microCSS, origen y salida; nombres, descripciones, grupos y atajos.
- Pulsar Preview changes. Revisar antes/después, gulpfile nuevo completo y archivos de receta de IA desplegables. Se muestran paquetes y preparación de identificadores NAS. Hasta aquí no se escribe ningún archivo.
- Apply changes and create backup aplica lo revisado y guarda originales bajo
.microgulp/setup-backups. Fuentes modificadas, recetas de IA preexistentes o tareas activas impiden una aplicación insegura. - Undo this change restaura originales byte por byte y elimina solo los archivos de receta de IA creados por esa aplicación. Cambios posteriores bloquean deshacer. La última aplicación solo puede deshacerse en la misma conexión MCP y sesión IDE.
Sin --setup-write-project, siguen disponibles análisis y vista previa; aplicar queda oculto. La interfaz no inicia tareas ni instala paquetes. Varias vistas y llamadas del agente en una conexión comparten la última propuesta: trabajar solo con una a la vez.
Tras reiniciar Cursor, host o MCP, volver a llamar list_projects y open_setup_assistant y analizar de nuevo. Una vista antigua puede devolver ide-session-unavailable. Las vistas previas valen diez minutos. Si se corta la conexión al aplicar, comprobar archivos y copia antes de volver a escribir. Después de actualizar el VSIX, verificar la ruta MCP, reinstalar dependencias SDK si es necesario y reconectar.
Conectar MCP en Cursor e IntelliJ
MCP y los skills son opcionales. Para el día a día basta abrir el proyecto, elegir tarea e iniciarla. Los siguientes pasos necesitan el proyecto abierto en el host µGulp™ actualizado. Usar la carpeta real: adaptador bajo src/mcp en Cursor y microgulp/src/mcp en el plugin JetBrains extraído. Instalar allí las dependencias SDK como se ha indicado.
Esta configuración sirve para ambos clientes. Sustituir rutas absolutas de ejemplo por las locales; --setup-write-project permite después aplicar y deshacer cambios revisados en ese proyecto concreto:
{
"mcpServers": {
"microgulp": {
"command": "C:/Program Files/nodejs/node.exe",
"args": [
"C:/Pfad/zur/Installation/src/mcp/microgulp-mcp.mjs",
"--project", "C:/Projekte/MeinProjekt",
"--setup-write-project", "C:/Projekte/MeinProjekt"
]
}
}
}
- Cursor: añadir el servidor en
.cursor/mcp.jsondel proyecto sin eliminar los existentes. Activarlo en la gestión MCP y revisar el estado. Tras cambios de configuración, reconectar y abrir un chat nuevo. - IntelliJ: en Settings → Tools → AI Assistant → Model Context Protocol (MCP) usar Add para una conexión STDIO, pegar JSON e iniciar con Apply. En Tools → AI Assistant → Agents, activar y confirmar además Pass custom MCP servers. Pass IntelliJ MCP server corresponde al servidor IDE integrado y no sustituye ese reenvío. Abrir después un chat nuevo con el agente elegido. Aquí se probó Codex con acceso ChatGPT; µGulp™ no necesita una clave API adicional. Configuración JetBrains
Primera solicitud de prueba: «Llama a list_projects del servidor MCP microgulp. Sin consultas de recursos ni cambios». Revisar ruta, IDE y sesión en la respuesta real. unknown MCP server o herramientas ausentes indican que el chat aún no está conectado. Revisar estado, reenvío y nuevo chat. Una consulta de recursos correcta no sustituye esta prueba. Usar projectId y sessionId devueltos, no identificadores antiguos.
Skills con el agente existente
Consultar la biblioteca versionada con list_library. Los perfiles están en .microgulp/agent-profiles.json y definen archivos de entrada permitidos y versión del skill. El valor predeterminado execution: "client" usa el agente IDE existente. Los skillGrants independientes solo son necesarios para el modo API activado expresamente; una lista vacía no impide el proceso cliente normal. start_api_skill no sustituye automáticamente una conexión ausente.
Ejemplo de perfil de traducción; los tres JSON deben existir ya en el proyecto:
{
"schemaVersion": 1,
"profiles": {
"texte-de": {
"enabled": true,
"skill": "localization",
"version": "1.1.0",
"execution": "client",
"configuration": {
"source": "i18x/source.json",
"target": "i18x/de-DE.json",
"baseline": "i18x/source-baseline.json",
"sourceLanguage": "en-US",
"language": "de-DE"
}
}
}
}
inspect_skill_profiledevuelve el hash actual.start_skillrecibe ID del perfil, hash y unrequestIdnuevo único. El encargo preparado vale 30 minutos.- El agente procesa las entradas y envía resultado, ID de trabajo y
digestsin cambios asubmit_skill_result. Se guarda la propuesta en.microgulp/proposals/<id>/proposal.json; la traducción permanece intacta. - Revisar destino, textos modificados, marcadores preservados y entradas intactas. Solo entonces autorizar
apply_skill_proposalcon el ID. µGulp™ vuelve a verificar fuentes y guarda el original en.microgulp/proposals/<id>/original.json. - Revisar el archivo real.
undo_skill_proposalrevierte esa aplicación con el mismo ID si no cambió después y se mantienen conexión MCP y sesión host. En una aceptación, comparar hash anterior y posterior a deshacer.
Una solicitud sencilla: «Usa el perfil texte-de con el agente existente, envía el resultado por MCP y muestra la vista previa. Detente antes de aplicar. Sin cambios directos de archivos». Aplicar y deshacer se solicitan después expresamente. Tras skill-expired, preparar de nuevo; ante unknown-skill-run o unknown-undo, revisar antes sesión, archivos y respaldo. No repetir a ciegas ni sustituir deshacer por escritura directa.
Mantenimiento del manual con vista previa fundamentada
Un perfil con skill: "handbook-maintenance", versión 1.1.0 y execution: "client" indica en configuration cualquier DOCX del proyecto como master, su sourceLanguage, archivos de implementación en files y un commit Git completo existente como baselineCommit. outputLanguage determina opcionalmente el idioma de propuestas; si falta se usa el de origen. chapters limita capítulos; editorialRules contiene reglas editoriales opcionales del proyecto. El commit debe poder leerse desde el proyecto abierto. El skill no procesa actualmente PDF ni Markdown.
Hasta submit_skill_result, el proceso coincide con traducción. La vista previa incluye propuestas con archivos y líneas como evidencia y editorial-review-required. No existe aplicación automática a DOCX: apply_skill_proposal rechaza el informe con handbook-report-requires-editorial-work. La edición se hace aparte en el DOCX configurado. El skill no actualiza baselines, traducciones ni salidas finales. «Primero fuentes alemanas .src., después traducir solo diferencias» es una norma de nuestro proyecto µGulp™, solo en su perfil; cada cliente define su proceso editorial.
Ejemplo de manual de cliente
El origen puede llamarse docs/Customer Guide.docx. Este perfil usa inglés como origen y francés para propuestas. Sustituir el marcador por un commit Git real completo del proyecto:
{
"enabled": true,
"skill": "handbook-maintenance",
"version": "1.1.0",
"execution": "client",
"configuration": {
"master": "docs/Customer Guide.docx",
"sourceLanguage": "en-US",
"outputLanguage": "fr-CA",
"files": ["src/build.mjs"],
"baselineCommit": "<vollständiger Git-Commit>",
"editorialRules": "Kundenterminologie erhalten und bestehende Kapitelstruktur beachten."
}
}
Incluir esta entrada con nombre propio en profiles de .microgulp/agent-profiles.json. Se validan identificadores como de-DE, en, fr-CA o zh-Hant. El idioma del resultado no recibe certificación lingüística automática. Origen y destino de traducción deben diferir; se admiten diccionarios JSON planos con cadenas, no traducción general de Markdown o DOCX.
Actualizar perfiles existentes
Los perfiles de skill 1.0.0 siguen ejecutándose para traducción y manuales. Archivo y hash no se reescriben automáticamente. Sin sourceLanguage, los perfiles antiguos de traducción conservan origen indeterminado (und); el agente lo deduce del texto. Los de manual conservan de-DE si no se especifica idioma. Las indicaciones explícitas prevalecen. Los nuevos perfiles usan 1.1.0 con archivo e idioma elegidos; las reglas específicas pertenecen solo al perfil. Para migrar permanentemente, respaldar perfil, revisar versión e idiomas y preparar encargo nuevo. Versiones desconocidas o perfiles erróneos se marcan individualmente no ejecutables sin bloquear vecinos válidos. Un archivo globalmente inválido sigue rechazándose. Los pins e integridad de biblioteca no se renuevan automáticamente. Vista previa, protección de marcadores, respaldo, deshacer y bloqueo DOCX también rigen para perfiles antiguos.
Restaurar la conexión del dashboard en IntelliJ
Si termina el motor del proyecto, la ventana µGulp™ abierta lo detecta y ofrece Reconnect dashboard. Ocultarla y volver a mostrarla reinicia un motor detectado como detenido. No reinicia motores activos ni repite tareas. Ante error de inicio, mantiene mensaje y opción de reintento sin bucle automático. Un inicio sin señal de disponibilidad se cancela tras un máximo de 120 segundos. Revisar ruta Node y ajustes, y elegir Reconnect dashboard. Tras reconectar, llamar list_projects y elegir sesión nueva. No reutilizar IDs de propuestas o de deshacer de sesiones anteriores; revisar respaldos antes de otro cambio. El estado verde MCP por sí solo no prueba una sesión activa del dashboard.
Procesos verificados y autorizaciones
Los perfiles de clientes configurables con skill 1.1.0 se comprobaron por MCP en Cursor e IntelliJ instalados hasta el 19 de octubre de 2026: en-GB a fr-CA, vista previa con marcador preservado, aplicación y deshacer byte por byte. Se eligieron libremente DOCX y lengua del informe; la aplicación automática se rechazó con handbook-report-requires-editorial-work y el hash DOCX no cambió. La compatibilidad de perfiles 1.0.0 se confirmó después también en IntelliJ. Esto acredita el proceso controlado, no la calidad lingüística de cualquier resultado.
El 19 de octubre de 2026 se probó Reconnect dashboard tras terminar el motor en IntelliJ: la sesión nueva era accesible por MCP y los perfiles antiguos pasaron después las pruebas. Se aplicaron traducciones y deshicieron byte por byte; el servidor rechazó la aplicación automática del manual, dejando el DOCX intacto. Acredita ese caso de reconexión, no recuperar tareas arbitrarias activas o IDs antiguos.
La última ejecución local Windows con Node.js 22 pasó 1115 pruebas, sin fallos y con cuatro casos de plataforma/dispositivo omitidos expresamente. Pasaron otras 31 pruebas MCP/web. Se instalaron los paquetes actualizados VS Code, Cursor Internal y Free y se verificaron con una tarea correcta. JetBrains Plugin Verifier confirma compatibilidad con plataformas probadas 242, 261 y 262; se eliminaron las dos llamadas API obsoletas señaladas. El paquete corregido se instaló y probó en Windows con IntelliJ IDEA 2026.2.2: confirmar ruta predefinida, cancelar selección, abrir log, dashboard completo al inicio, ocultar/reabrir, maximizar/restaurar y redimensionar ventana. No se probaron cambios entre monitores con distinta escala DPI. Las aceptaciones MCP anteriores conservan su versión de paquete. No sustituye un CI multiplataforma nuevo ni pruebas físicas pendientes.
Del 17 al 19 de octubre de 2026 se probaron paquetes 2.0.0 locales en Windows con el agente real Cursor y Codex en IntelliJ: vista previa, aplicar, lectura y deshacer byte por byte; también propuesta de manual fundamentada, rechazo DOCX automático y hash intacto. La app gráfica MCP se probó en Cursor; no implica aceptación de app gráfica IntelliJ. No cubre otros agentes ni sistemas.
Un primer intento Cursor devolvió unknown-undo, sin aclararse la causa. El ciclo completo posterior pasó. Por eso deben comprobarse sesión y respaldo ante errores. Un rechazo del control de autorización cliente, como Guardian, no es respuesta de herramienta µGulp™ ni prueba negativa superada. No eludir autorizaciones; cualquier intento adicional requiere autorización adicional explícita. La prueba negativa DOCX exige la respuesta real µGulp™ y leer después un hash intacto.
Configuración inicial, proceso y límites
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) |
Haz clic en una tarea → un worker disponible la ejecuta sin volver a importar el gulpfile. Guarda el gulpfile → la lista de tareas se actualiza automáticamente. Ejecuta varias tareas en paralelo; cada una tiene su propio sector en el panel y una barra de progreso de neón si la tarea llama a ReportProgress de gulp-mu-gulp-api.
Seguir usando la CLI Gulp
Los metadatos adicionales no cambian cómo se invocan las tareas. Los builds existentes pueden seguir bajo gulp clásico y CI. Siguen necesitándose los paquetes importados; entradas y acciones dependientes del host deben servir para esa vía. Revisar las llamadas CLI anteriores tras integrar.
Comportamiento sin dashboard
| 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/ |
Según el uso, también contiene recetas de IA, perfiles, configuración y respaldos. No borrarlo indiscriminadamente: el código importado puede ser necesario en CLI. Versionar archivos del proyecto selectivamente; excluir logs locales, credenciales y respaldos |
gulp-mu-gulp-api es un paquete npm normal sin dependencias de ejecución, e IsMicroGulp() indica si la tarea está orquestada. Conservar paquetes y recetas de IA necesarios al quitar la extensión. Las acciones dependientes del host requieren una alternativa apropiada.
Respetar requisitos de versión
La CLI Gulp clásica ignora metadatos adicionales. Eso no garantiza compatibilidad general de cualquier versión de host, Gulp o API: nuevas llamadas pueden requerir paquetes nuevos y acciones IDE capacidades específicas. Respetar requisitos y revisar llamadas tras actualizar.
Un compañero puede seguir usando npx gulp BUILD en el terminal mientras usted usa el dashboard. Ambas vías comparten archivos; coordinar escrituras simultáneas dentro del proyecto.
Instalación
µGulp™ ya está disponible. Instale desde las fichas públicas:
| Edición | Instalar |
|---|---|
| µGulp™ (VS Code / Cursor) | Instalar para VS Code · Instalar desde Open VSX |
| µGulp™ Free (VS Code / Cursor) | Instalar µGulp Free · Instalar desde Open VSX |
| µGulp™ (JetBrains IDEs) | Instalar para JetBrains |
El repositorio fuente permanece privado. No instale la edición VS Code/Cursor registrada y µGulp™ Free a la vez - comparten los mismos identificadores de comando.
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. Instalar para JetBrains desde el Marketplace; la ficha ofrece dos compilaciones según compatibilidad, y la IDE recibe la que corresponde (Help → About):
| IDE build | since-build |
Marketplace |
|---|---|---|
2024.2 - 2026.1 (hasta 261.*) |
242 |
Instalar para JetBrains |
| 2026.2 y más nuevo | 262 |
Instalar para JetBrains |
El Marketplace elige la compilación adecuada. IntelliJ IDEA, PhpStorm, WebStorm y los demás IDEs basados en IntelliJ comparten estas dos variantes - por build de plataforma, no por nombre de producto. Cada variante declara
<idea-version since-build="…"/>en el descriptor - la IDE no carga la otra. La variante 2024.2-2026.1 essince-build="242"/until-build="261.*". La variante 2026.2+ essince-build="262"sin tope. 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í la variante Marketplace aparte. Instale desde el JetBrains Marketplace (Settings → Plugins → Marketplace, busque MicroGulp) 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:verifyejecuta 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 enMICROGULP_IDE_CACHE(por defecto%LOCALAPPDATA%\microgulp\ide-cache,~/.cache/microgulp/ide-cacheen otros sitios) y se reutilizan; el IDE instalado localmente se usa directamente cuando su build coincide.MICROGULP_SKIP_IDE_DOWNLOAD=1mantiene 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.jcefy 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/.
Paquetes sin conexión
Estos archivos existen solo en un checkout local del repositorio fuente. No son la vía de instalación pública.
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, luegonpm run build- los.vsixregistrado y Free llegan apackages/.
Zips JetBrains de un build local:
| IDE build | Paquete |
|---|---|
2024.2 - 2026.1 (hasta 261.*) |
packages/microgulp-jetbrains_latest.zip |
| 2026.2 y más nuevo | packages/microgulp-jetbrains-2026.2_latest.zip |
Instale un zip local vía Settings → Plugins → ⚙ → Install Plugin from Disk…
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, project). 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 único relativo a la raíz del proyecto; debe permanecer dentro de ella |
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. |
project |
objeto | - | Opcional. Identidad del proyecto para la lista de tareas: title, description, logo (SVG/PNG/WebP, relativo a la raíz). Sin valores, sin cabecera extra. |
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. Los cambios en project (título, descripción, logo) se aplican sin reiniciar el IDE si la vigilancia del gulpfile está activa.
Identidad del proyecto (project)
Cabecera compacta opcional encima de la lista de tareas para reconocer de inmediato, con varias ventanas IDE abiertas, a qué espacio de trabajo pertenecen las tareas:
{
"project": {
"title": "ESP][",
"description": "Apple II emulator for ESP32-S3",
"logo": "./assets/esp2.svg"
}
}
- Los tres campos son opcionales; sin metadatos, el diseño anterior no cambia.
logo: rutas relativas a la raíz del proyecto; formatos SVG, PNG, WebP. Archivos ausentes o inválidos se ignoran (cabecera sin logo).- Tooltip en la cabecera: título, descripción (si existe) y ruta absoluta del espacio de trabajo.
- La identidad del proyecto aparece en la lista del panel y la Web Console. Stream Deck muestra logotipo y título en Root del navegador de grupos, conserva las proporciones y reserva una franja para el título; si el logotipo no es utilizable se usa una representación alternativa. Logitech MX utiliza la imagen del proyecto suministrada por el host conectado para seleccionar workspace y para la tecla µGulp™, con la imagen de marca como alternativa. La aceptación completa en dispositivos está pendiente; no se promete su visualización en Flexbar.
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/engineysrc/workerno 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ínimonpm run serve(src/host/microgulp-serve.mjs, NDJSON en stdio) ya está en su sitio. - Precarga de tareas. El
TaskWorkerPoolmantiene 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íaawait 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™ descubre gulpfiles mediante una ruta única o un patrón regex que recorre todo el workspace. La selección pertenece al proyecto y es idéntica en VS Code, Cursor, JetBrains y CLI:
- Anulación explícita del IDE o CLI: ajuste de VS Code/Cursor, JetBrains Settings → Tools → µGulp o
microgulp-serve --gulpfile/--gulpfile-pattern. Un campo vacío no es una anulación. microgulp.config.jsonen la raíz (gulpfileogulpfilePattern).- Predeterminado:
gulpfile.mjsen la raíz; en su ausencia, descubrimiento con(^|/)gulpfile\.(m|c)?js$.
En cada nivel, un patrón prevalece sobre una ruta única. Se rechazan rutas fuera de la raíz; si falta el archivo, se avisa y se pasa al siguiente nivel.
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$encuentragulpfile.mjs/.js/.cjsen la raíz y en cada subcarpeta.microgulp.gulpfilePath- ruta única explícita; vacía por defecto para que se apliquemicrogulp.config.json.
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, file, folder |
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, accept |
numeric / textarea details; accept on file is .zip,.json |
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.
Se admiten listas largas (select / radio / checkbox): el host conserva hasta 5000 entradas por campo por defecto (anulación MICROGULP_MAX_SELECT_OPTIONS; 0 = sin límite). Si se recortan, el panel muestra una advertencia, sin truncamiento silencioso. Desde 24 opciones aparece un filtro. RequestForm ad hoc de gulp-mu-gulp-api no tiene límite de host en su carga en directo; se aplican los mismos tipos de campo y filtro.
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.µShortDisplayName = 'CSS, Build Styles<context="µShortDisplayName"/>'.i18xRegister(); // Optionaler Kurztext für Stream Deck und Logitech MX
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();
µShortDisplayName es una frase i18x opcional para etiquetas breves de hardware. No cambia el nombre del dashboard ni el ID de tarea. Puede contener «texto corto, texto original», como CSS, Build Styles. La etiqueta de contexto µShortDisplayName solo pertenece a la frase fuente i18x; el host la elimina antes de mostrarla. No aparecen etiquetas en el dispositivo.
Etiquetas de contexto, formatos obligatorios y plan de idiomas del marketplace: dev/docs/MicroGulpI18xProfile.md.
Presentación y control de tareas desde el gulpfile
µGulp™ muestra si cada tarea está inactiva, desactivada, iniciándose, en ejecución, esperando datos, deteniéndose, completada correctamente o fallida. El borde de estado sigue visible con iconos personalizados. Cuando se espera una entrada, aparece un icono de diálogo violeta; responde en el panel.
38 iconos SVG ofrecen una presentación semántica. µTaskKind y µPresentation describen la tarea, por ejemplo, compilación, prueba, copia o publicación. Los iconos siguen el tema, pueden sustituirse mediante un tema y admiten movimiento reducido. Las animaciones muestran la actividad; cuando hay un error, el diseño original aparece chamuscado. Se conservan los ajustes existentes de µIcon y µIconFont.
Marca un servicio de larga duración con µExecutionType = 'persistent' para poder detenerlo. Esto es independiente de µWatch, que vuelve a ejecutar una tarea tras cambios de archivos, y de µAttention, que señala trabajo pendiente. µAttentionWatch puede volver a evaluar ese aviso tras cambios de archivos o a intervalos sin ejecutar la tarea.
Una tarea Gulp también puede controlar la vista general de tareas:
import { SetGroupState, RevealTask, SetTaskEmphasis } from 'gulp-mu-gulp-api';
SetGroupState('Build', 'open');
RevealTask('PUBLISH_NPM', { expand: true, scroll: true, highlight: 'attention' });
SetTaskEmphasis('PUBLISH_NPM', null);
µGroups define el estado inicial; los cambios posteriores en los grupos se aplican a la sesión. El resaltado y el estado de ejecución son independientes: una tarea en ejecución también puede requerir atención. El panel y el hardware reciben el mismo estado de tarea. Abrir un grupo en el panel no inicia sus tareas.
Acciones del IDE desde las tareas
Las tareas Gulp importan Ide de gulp-mu-gulp-api. El alcance 1.0.0 implementado incluye ocho funciones:
| Función | Finalidad |
|---|---|
Ide.Capabilities() |
Consultar familia del host, edición, operaciones y acciones semánticas disponibles; accesible incluso con funciones ejecutoras bloqueadas |
Ide.Projects() |
Consultar proyectos conocidos, sesiones activas y aplicaciones configuradas |
Ide.Action(id) |
Ejecutar una acción semántica en el host IDE actual |
Ide.OpenProject(request) |
Abrir un proyecto conocido en la instalación elegida o enfocar su sesión exacta |
Ide.StartApplication(applicationId) |
Iniciar una aplicación local conocida o configurada explícitamente |
Ide.Execute({ vscode, jetbrains, args }) |
Ejecutar el comando nativo indicado para la familia de host actual |
Ide.Vscode.ExecuteCommand(commandId, ...args) |
Ejecutar un comando permitido de VS Code/Cursor |
Ide.JetBrains.ExecuteAction(actionId) |
Ejecutar una acción permitida de JetBrains |
El catálogo común de Ide.Action incluye open-settings, save-all, open-terminal, open-problems, find-in-project, quick-open, command-palette, next-editor, previous-editor, run y debug. Run/Debug usan la configuración nativa actual. La disponibilidad depende del IDE, plugins instalados y comandos permitidos; no se garantizan capacidades idénticas en todos los productos JetBrains.
Ide.OpenProject toma projectId de Ide.Projects().result.projects y, por ejemplo, applicationId de las aplicaciones devueltas. Una sesión exacta exige sessionId y connectionId juntos. Los destinos obsoletos se rechazan, sin sustituirlos por otra sesión.
µHost indica la familia IDE requerida; µIdeApi = true marca tareas que necesitan esta interfaz. El motor verifica edición, registro y comandos permitidos. En µGulp™ Free, Ide.Capabilities() sigue disponible como consulta; las otras siete funciones están bloqueadas, incluida Ide.Projects(). La vista de proyectos legible de la Web Console sigue disponible independientemente.
Las llamadas devuelven una Promise con { ok, result } o { ok: false, code, message }. Sin IPC de µGulp™, por ejemplo con gulp CLI normal, las ocho devuelven unsupported-host y no inician ningún IDE. La falta de permiso de edición o registro devuelve unsupported-edition o unsupported-registration. El gulpfile puede ofrecer su propia alternativa para CLI y CI.
Este alcance describe la implementación del repositorio, no su disponibilidad en una versión npm ya publicada. Ide.OpenUrl solo está previsto y no está disponible.
Integraciones de hardware
Controla tareas con Elgato Stream Deck y Stream Deck Mobile, Logitech MX Creative Console y Actions Ring y ENIAC Flexbar. Las funciones de hardware están incluidas en todas las ediciones excepto µGulp™ Free. JetBrains no tiene edición Free.
µGulp™ hace más que mostrar un icono fijo en una tecla. Live Animated Task States significa que la presentación sigue el estado real de ejecución del mismo motor que el panel (inactive → starting → running → finished o failed, además de disabled, waiting-for-input y stopping). La animación aparece durante el inicio, la ejecución, la detención y la espera de datos; el éxito y el error se muestran brevemente (el error incluye Burn→Charred). µWatch sigue siendo una superposición independiente de activación/desactivación; los programas de sesión pueden añadir una cuenta atrás o n/m a la tecla. (Actions Ring: solo títulos, SDK sin animación LCD). Contrato y lista de estados: TaskPresentationAndHardware.md.
Activa la conexión del espacio de trabajo en el panel, en Settings → Hardware integrations. El plugin adecuado del dispositivo conecta las teclas con las tareas de ese proyecto. Se pueden detener los servicios en ejecución; las solicitudes de entrada se responden en el panel.
Superficies de control sensibles al contexto
µGulp™ usa un contexto de proyecto activo común para Visual Studio Code, Cursor y JetBrains. Stream Deck restaura la última vista por workspace y dispositivo. Logitech conserva su selección dinámica existente; su carpeta abarca todo el proceso. Flexbar no sigue automáticamente al proyecto IDE.
El proyecto activo es común; las vistas Stream Deck se guardan por dispositivo. Cuando otra aplicación está en primer plano, µGulp™ devuelve a Stream Deck un perfil de navegador que abrió. El perfil predeterminado o Smart Profile que aparezca después depende de Elgato y la configuración del usuario; no se garantiza el cambio automático de Smart Profiles.
Ejemplo:
Cursor: microGulp
MX -> Build
Stream Deck -> Release
Alt-Tab
JetBrains: BlueShift
MX -> Build
Stream Deck -> Test
Alt-Tab
VS Code: ESP][
MX -> Upload
Stream Deck -> Monitor
Volver a una ventana IDE restaura la vista Stream Deck anterior de ese workspace. Las vistas se guardan por separado por dispositivo; falta la validación física con varios Stream Decks.
Si desaparece un grupo tras cambiar el gulpfile, se restaura el padre válido más cercano o la raíz. Follow active IDE project está activado por defecto. La selección manual del workspace en el keypad Logitech tiene prioridad. Límites técnicos: Seguir el proyecto IDE activo.
Elgato Stream Deck y Stream Deck Mobile
Follow y perfiles: Con Follow active IDE project, µGulp™ adopta el proyecto IDE enfocado con conexión de hardware disponible y puede abrir su perfil de navegador incluido. Si ya es visible, solo cambia el contenido. Al salir del contexto IDE se devuelve un perfil abierto por µGulp™. Se pueden configurar Elgato Smart Profiles adicionales en Stream Deck; µGulp™ no garantiza su activación. Detalles y diagnóstico: Stream Deck.
Navegador de grupos: Open µGulp Group en otro perfil (p. ej., Default) abre el navegador con grupos y tareas dinámicos. Esta acción abre el grupo inicial configurado. Follow y una tecla µGulp Group Slot usada como entrada restauran, en cambio, la vista guardada del workspace activo; una sesión nueva sin vista guardada empieza en la raíz. Páginas, Atrás y Root siguen la cuadrícula. Root muestra el logotipo sin deformarlo y el título en una franja aparte; un logotipo inutilizable recibe una alternativa. Atrás en la raíz sale del navegador. Stream Deck Mobile elige la plantilla por tamaño de cuadrícula, incluidos 3×2 y 5×3.
Asignación fija de una tarea: puedes seguir arrastrando µGulp Task a una tecla y seleccionar el espacio de trabajo y la tarea. Los nombres, los estados animados de ejecución y los iconos proceden del espacio de trabajo conectado. Stream Deck Mobile usa la misma integración.
Detalles técnicos y lista de plantillas: Stream Deck, contrato de navegación por grupos en dispositivos.
Tareas individuales de Logitech o perfil de aplicación
Logitech ofrece dos métodos de configuración:
- Asignar tareas individualmente: usa Start a Single µGulp Task para vincular de forma permanente un espacio de trabajo y una tarea a una tecla. Está disponible para teclas individuales del teclado y para Actions Ring (solo títulos; SDK sin animación LCD). La carpeta del teclado muestra iconos y estados de ejecución.
- Crear un perfil de aplicación en Options+, por ejemplo, para Cursor: la distribución de teclas configurada se activa automáticamente cuando la aplicación obtiene el foco. En el teclado, General µGulp Functions abre las tareas del espacio de trabajo correspondiente con iconos e indicadores de ejecución en directo. Dentro del IDE, el plugin de µGulp™ sigue el espacio de trabajo de la ventana activa; la selección manual mantiene la prioridad hasta que se desactiva o se pierde la conexión.
Así, Options+ selecciona la distribución de teclas de la aplicación y µGulp™ selecciona el espacio de trabajo. Configura el perfil una sola vez en Options+. Al cambiar de aplicación puede cerrarse la carpeta dinámica; pulsa la tecla de µGulp™ para volver a abrirla. Actions Ring usa asignaciones fijas de tareas; la lista dinámica con iconos está pensada para el teclado.
Logitech MX utiliza la imagen del proyecto suministrada por el host conectado para seleccionar workspace y para la tecla µGulp™, con la imagen de marca como alternativa. La aceptación completa en dispositivos está pendiente. No se garantizan la apertura programática del Dynamic Folder ni la navegación independiente en varios dispositivos MX físicos; las cuestiones del SDK siguen abiertas. El soporte Logitech existente permanece limitado y experimental.
ENIAC Flexbar
El plugin de Flexbar conecta las acciones configuradas en FlexDesigner con las tareas de µGulp™ y sus estados de ejecución (con la misma semántica de estados que Stream Deck). Aún está pendiente probarlo con una Flexbar física.
Configuración técnica y compilaciones de los plugins: Stream Deck, Logitech, Flexbar.
Programador de tareas (sesión)
Los programas de sesión solo deciden cuándo se inicia una tarea; la ejecución sigue el flujo normal de StartTask (el sector del panel, los registros y los estados del hardware no cambian).
| Modo | Declaración | Resumen |
|---|---|---|
| Temporizador | µSchedule = { after: '10s' } |
una vez, al terminar el intervalo |
| Intervalo | { every: '10s' } |
se repite; nextRun se calcula después de cada ejecución |
| Repetición | { every: '5s', repeat: 5 } |
completed tras n ejecuciones |
| Cron | { cron: '*/1 * * * *' } |
5 campos, hora local del host (croner) |
API imperativa: ScheduleTask, SetScheduleEnabled, CancelSchedule, RunScheduleNow (gulp-mu-gulp-api). Panel: cuenta atrás desde nextRun, Enable/Disable/Cancel/Run now. Mientras µWatch esté armado o la tarea siga en ejecución, se omite el inicio programado (schedule-skipped). Las teclas de hardware pueden mostrar una cuenta atrás o n/m. Detalles y demos A-G: TaskScheduler.md.
Mandos, gamepads y joysticks
Los gamepads, joysticks y otros dispositivos compatibles se pueden configurar como controladores para los flujos de trabajo. Activa la compatibilidad en Settings → Controllers; la configuración incluye perfiles, aprendizaje de botones y ejes, zonas muertas, sensibilidad y diagnósticos en directo. Las asignaciones pueden iniciar o detener tareas y controlar la vista general de tareas.
En Windows x64, la detección también funciona sin que el panel tenga el foco. Se requiere Node.js 22 o posterior instalado. Los componentes nativos aún no están incluidos para otros sistemas de escritorio; los navegadores compatibles ofrecen la Gamepad API como alternativa.
La 3Dconnexion SpaceMouse Wireless tiene un perfil medido en el dispositivo con seis ejes y dos botones. Configura otros dispositivos mediante calibración y asignaciones propias. Si un mando admite vibración, la respuesta opcional puede indicar el inicio, el éxito o el error de una tarea. Su alcance y efecto dependen del dispositivo.
Configuración, perfiles de dispositivos y diagnóstico: documentación de mandos.
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, más identidad de proyecto opcional en microgulp.config.json) use el prompt mantenido en el repositorio:
| File | Purpose |
|---|---|
dev/prompts/OptimizeGulpfileForMicroGulp.md |
Prompt copiar y pegar para Cursor, Claude, ChatGPT, … (primera migración) |
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json |
Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version) |
dev/prompts/EnhanceExistingMicroGulpProject.md |
Examinar un proyecto µGulp™ existente para funciones recientes opcionales (sin activación a ciegas) |
El prompt de migración también cubre ahora µTaskKind, µPresentation, µExecutionType, µAttentionWatch y la espera de datos y una identidad project razonable (título / mini descripción / logo existente; solo fusionar config). Se conservan los glifos µIcon y las asignaciones µIconFont existentes. El núcleo gestiona los estados de ejecución; los servicios persistentes, los disparadores de archivos y la atención siguen siendo funciones independientes. Las integraciones de hardware se activan por espacio de trabajo y se incluyen en todas las ediciones salvo µGulp™ Free; está pendiente probar Flexbar con hardware real. Antes de migrar, compara las versiones requeridas del producto y la API con el estado actual del proyecto.
El prompt también exige valores formateados con i18x: int para contadores, floatFix1 / floatFix2 para decimales, byteSize para bytes, progressDuration para milisegundos y formatos de fecha y hora. FormatValue() está disponible para las salidas estructuradas. Los diccionarios del proyecto se actualizan junto con las definiciones <format> correspondientes; se conservan las traducciones existentes. Se respetan las limitaciones provisionales del motor personalizado.
Para la agrupación y el árbol de tareas, incluye µGroup, µOrder, µGroups, SetGroupState, RevealTask y SetTaskEmphasis. Las indicaciones de hardware explican el navegador de grupos de Stream Deck (tecla de acceso y perfiles con ranuras dinámicas), las tareas fijas de Logitech, incluido Actions Ring, y los perfiles de aplicación de Options+ con selección del espacio de trabajo por µGulp™.
Workflow
- Copia el ejemplo de parámetros a la raíz del proyecto como
microgulp-optimize.params.jsony completaprojectRoot,gulpfilePath,supportedLanguages(por ejemplo,en-US,de-DE,zh-CN),gulpMuGulpApiVersion(referencia local^0.6.0; comprueba la versión instalada/publicada),microGulpMinVersion(1.0.0) ygithubRepoUrl/githubRef(por defecto:https://github.com/mamekudz/microGulp, una referencia verificada comomain). - Abra el markdown del prompt, sustituya la tabla
{{PLACEHOLDER}}por sus valores (o adjunte el archivo params y el gulpfile en Cursor). - 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. - Verifique con
node --check gulpfile.mjs, pruebe las tareas en el panel µGulp (incluidos los atajos nuevos mientras el panel tiene el foco), luego confirmegulpfile.mjs,i18x/gulp/*.jsonypackage.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) |
El grupo Scheduler demos (A-G) muestra programas de sesión (µSchedule): temporizador de una ejecución, intervalo, repetición, Cron, omisión de solapamientos, error programado y Watch+Schedule. Todas las demos empiezan desactivadas (autoStart: false); actívalas una a una con sus botones de icono. Detalles y API: dev/docs/TaskScheduler.md.
Más detalles de API: gulp-mu-gulp-api/README.md.
µGulp™ Ready
Un proyecto incorpora al menos una interacción o salida útil específica de µGulp, documenta una vía Gulp/CLI normal y comprueba ambas vías por sí mismo. La compatibilidad con Gulp o los metadatos decorativos no bastan. La insignia es gratuita según las reglas publicadas, sin solicitud ni certificación oficial.
Requisitos y uso de la insignia (inglés).
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 (tareaSHOW_VERSION_HISTORYonpm run history).BUILD_PACKAGEsincroniza la versión depackage.jsony la línea de versión al inicio de este README desdeRELEASES.jsonautomá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 deRELEASES.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-cssestá cableado como dependenciafile:local enC:\Projects\microCSS\gulp-mu-cssy - como todo paquete pesado - solo se carga dentro del cuerpo de la tarea víaawait import().BUILD_PACKAGEproduce un.vsixreal 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.mjsy una fuente<name>.µ.cssdel mismo nombre.CREATE_THEME_DATAdescubre 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); eldashboard.cssescrito 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 esdev/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) yjetbrains/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). Copia y abre un gulpfile de ejemplo con tareas de demostración y compilación (progreso, formularios, registros estructurados, sonido, modales, además de cuenta atrás, iconos personalizados, presentación de errores, servicio persistente y Attention/Reset) en ~/.microgulp/sample. Después, usa µGulp: Open Dashboard. El manual de usuario está en Settings → Handbook (o µGulp: Open Handbook), donde están disponibles todos los idiomas.
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
Ya implementado
[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íai18x-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 (
.logcrudo +.ndjsonestructurado, índicehistory.ndjson, retención, panel de historial)[x]
microgulp.config.jsonpara 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 endev/docs/MicroGulpSoundSchema.md[x] Identidad del proyecto (
project.title/description/logoenmicrogulp.config.json; cabecera compacta en la lista de tareas)[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 Taskpara 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:-1mantener 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/gulpen el panel (parser i18xe-sync, diálogo de idioma destino, formatos estándar,<lid>.status.jsonpara traducción IA)[x] Estados de tarea coherentes, 38 iconos semánticos, indicador de entrada, tema alternativo y movimiento reducido
[x] Árbol de tareas y resaltado mediante
SetGroupState,RevealTaskySetTaskEmphasis[x] Ocho funciones API IDE e indicadores visibles de host/disponibilidad
[x] Web Console, KnownProjectRegistry / Project Center, Open/Focus Project y Background Host común
[x] Stream Deck: Follow, última vista por workspace y dispositivo y logotipos en Root
[x] Integración con Stream Deck/Mobile, Logitech y Flexbar; Logitech con asignaciones de tarea individuales y carpeta dinámica para el teclado
[x] Perfiles de mando con calibración y diagnósticos; entradas de escritorio en Windows x64 y perfil de SpaceMouse Wireless
Aún abierto
[ ]
Ide.OpenUrly ejecución de tareas sin IDE mediante Background Host: previstos, fuera del alcance 1.0.0 implementado[ ] Logitech MX: aceptación física incluida la imagen del proyecto y cuestiones SDK abiertas sobre Dynamic Folder y varios dispositivos
[ ] Stream Deck: validación física multidispositivo e interacción con Elgato Smart Profiles
[ ] Flexbar: probar con hardware físico
[ ] Componentes nativos para mandos en Linux y macOS
[ ] 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.mjsdeµLibcon 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)
[x] Ficha JetBrains Marketplace (plugin 34255; la presencia en el registro no es una instalación nueva verificada en cada IDE)
[x] Fichas VS Code/Cursor en Microsoft Marketplace y Open VSX (registrada y Free)
Web Console y Project Center
La Web Console local reúne proyectos conocidos y conectados en Project Center. Integra el panel existente con tareas, Project Controls, parámetros, historial y eventos en directo; no crea una segunda TaskEngine. Se abre con µGulp: Open Web Console en VS Code/Cursor, Open Web Console en la ventana de herramientas JetBrains o npm run console -- open en el repositorio de desarrollo. Usa HTTP/SSE local sin plugin de navegador y escucha solo en 127.0.0.1; no ofrece acceso LAN o remoto.
Proyectos conocidos y sesiones
KnownProjectRegistry guarda ruta, ProjectId, título, descripción, logotipo, IDE preferido y último contacto en ~/.microgulp/known-projects.json. Los metadatos proceden de microgulp.config.json. La vista distingue conectado, cerrado y no disponible. Una entrada conocida no es un motor en ejecución. Las sesiones IDE activas se registran aparte; varias ventanas del mismo proyecto se pueden elegir individualmente.
Follow active IDE project sigue el contexto activo común. Una sesión seleccionada manualmente queda fijada solo en esta pestaña, sin cambiar la fijación del controlador. Cuando otra aplicación está en primer plano, la última sesión mostrada permanece visible mientras siga activa.
La vista de proyectos y el panel integrado siguen accesibles en µGulp™ Free; se aplican los permisos habituales de tareas. La administración del host también está disponible. Open/Focus Project, Start Application, acciones IDE y selección del IDE preferido se verifican en el servidor en cada llamada según edición y registro. Si falta permiso se devuelve unsupported-edition o unsupported-registration.
Abrir y enfocar proyectos
Open/Focus Project usa la familia IDE, producto e instalación elegidos. Si existe una sesión compatible, enfoca su ventana. Varios resultados exigen elegir sesión. Un fallo de enfoque no inicia un segundo IDE; el enfoque exacto es actualmente específico de Windows. Sin sesión compatible, abre el proyecto conocido en la instalación elegida. Las solicitudes paralelas se agrupan; si no llega la confirmación de inicio, se requiere un reintento explícito. Un arranque lento puede parecer temporalmente sin confirmar.
Se detectan instalaciones Windows conocidas del usuario. Otras instalaciones IDE y aplicaciones se configuran en ~/.microgulp/applications.json con ruta absoluta al ejecutable y argumentos fijos opcionales; JetBrains requiere el producto concreto. Start Application inicia una aplicación conocida sin comando shell. El enfoque general de aplicaciones ajenas arbitrarias queda fuera del alcance. La detección de Windsurf es experimental, no una aprobación de otro IDE.
Background Host
Un Background Host compartido proporciona Web Console, proyectos conocidos, proyecto activo y contexto de controladores - un proceso por usuario, independiente del IDE. El primer IDE lo inicia cuando hace falta; cerrar el IDE no lo termina. El inicio opcional al iniciar sesión permite acceder a http://127.0.0.1:47821/console sin IDE abierto. Sin IDE lista proyectos conocidos; con los permisos de edición adecuados pueden abrirse en Cursor, VS Code o JetBrains. Las tareas se controlan a través de una sesión IDE conectada. La ejecución sin IDE y el traspaso automático del propietario del motor no forman parte de 1.0.0.
Los ajustes son comunes a todos los IDE y se guardan solo en host-settings.json: Start at login y Show background UI son independientes. Ocultar la interfaz no detiene el host. El puerto es global (47821 por defecto, de 1024 a 65535). Cambiarlo reinicia el host activo; la Console pasa a la nueva dirección. Si otra aplicación ocupa el puerto solicitado, se conserva el anterior. No hay puerto aleatorio ni campo de dirección de escucha: solo 127.0.0.1.
En el primer inicio, µGulp™ pregunta una vez por usuario, no por IDE: Enable µGulp Background Host? Enable activa el inicio al iniciar sesión. Not now lo deja desactivado; un IDE puede iniciar el host cuando lo necesite.
Los mismos controles aparecen en VS Code y Cursor (µGulp: Background Host Settings), JetBrains (Settings → Tools → µGulp Background Host y Background Host en la ventana de herramientas), la sección Background Host de la Console y npm run console -- status|open|restart|stop|port <n>|autostart on|off|ui on|off. El menú de la bandeja Windows abre la Console, muestra estado, IDE conectados y proyectos conocidos, y cambia el inicio al iniciar sesión. El puerto no se cambia allí. Stop termina solo el host; un IDE puede iniciarlo de nuevo.
| Plataforma | Inicio automático | Interfaz del sistema |
|---|---|---|
| Windows | Entrada de inicio de sesión del usuario | Bandeja (opcional; puede funcionar sin interfaz) |
| macOS | LaunchAgent | Barra de menús preparada, aún sin prueba en hardware macOS |
| Linux | Inicio XDG | Sin interfaz; sin dependencia de bandeja |
Los textos de Console están disponibles en alemán e inglés; otros idiomas usan inglés. Los controles del host tienen textos localizados propios. La API completa implementada se describe en Acciones IDE desde tareas.
Русский
Rock your Gulp!
µGulp™ дополняет Gulp интерактивным dashboard для VS Code, Cursor и IDE JetBrains. Задачи получают динамические имена, понятные группы, значки, описания и подсказки. Видно, к какому проекту и цели относится задача, выполняется ли она и успешна ли. Формы, прогресс и раздельный поток вывода сопровождают выполнение. Обычная Gulp CLI сохраняется; нужные пакеты и подходящие входные значения всё ещё необходимы. ИИ и MCP необязательны.
Начало работы: установить расширение IDE, открыть проект с gulpfile и запустить задачу в dashboard µGulp™. Нужны Node.js 22 или новее и пакеты проекта. Gulp - JavaScript-инструмент повторяющихся задач; gulpfile описывает их. µGulp™ добавляет интерфейс управления.
Основные возможности
Состояние 2.1.0 на 20.10.2026: локальная проверка продолжается, версия еще не опубликована. Глобальные задачи, обновленное начало работы и оформление задач проекта реализованы. Прежние приемочные проверки относятся к соответствующим версиям; успешная частичная проверка не означает полной приемки. Проверенные процессы и ограничения описаны ниже.
- НОВОЕ в 2.1.0: Понятное оформление задач проекта - выберите язык редактирования, поручите существующему агенту IDE предложить недостающие английские исходные тексты и переводы, сразу проверьте символы или собственные изображения. Gulpfile остается на en-US; переводы сохраняются в
i18x/gulp/<sprache>.json. Предварительный просмотр, резервная копия и отмена распространяются на оба файла. - Динамические имена, группы, значки и подсказки - понятные названия вместо имён функций; текущие значения версии или цели, вложенные сворачиваемые группы, собственные значки, описания и подсказки.
µDisplayName,µGroup,µIcon,µDescriptionиµTooltipадаптируют список к проекту. Тексты локализуются;µOrderсортирует задачи и группы,µGroupsзадаёт начальное состояние. - Предварительная загрузка задач - тёплые воркеры Node уже импортировали Gulpfile и сокращают запуск, если подготовленный воркер доступен; особенно полезно при тяжёлых импортах и сканировании файлов антивирусом в реальном времени
- Состояния задач с первого взгляда - запуск, выполнение, ожидание ввода, остановка, успех и ошибка отображаются единообразно; рамка состояния видна и с собственными значками
- Параллельная сетка задач - несколько изолированных секторов запуска рядом, у каждого свой поток журнала
- Веб-панель - живые ANSI-журналы, фильтрованный вывод, детерминированные полосы прогресса, богатые формы для ввода пользователя (текст, цвет, шрифт, select, multiselect, …)
- 🔴 НОВОЕ в 2.1.0: Подходящее начало работы с вашим Gulpfile - распознайте уже настроенные задачи, дополните недостающие сведения об отображении и заранее проверьте каждое изменение. Другие ИИ-рецепты доступны по желанию; отсутствие сочетаний клавиш вызывает лишь совет.
- 🔴 НОВОЕ в 2.1.0: Общая задача для нескольких проектов - например, запуск NAS-резервирования или проверок проектов по общему ID вроде
NASBU. Явно выберите проекты по названию и значку, заранее сохраните настройки каждого и проверьте их перед общим запуском. Каждый проект сохраняет собственную реализацию, вывод и историю. - 🔴 НОВОЕ в 2.0.0: Мастер и ИИ-рецепты - добавить метаданные через формы, интегрировать NAS или microCSS, подготовить старт проекта и публикацию GitHub/npm. Сначала проверить все изменения, применить с копией и отменить при неизменных файлах. Подготовительные задачи сами не публикуют.
- 🔴 НОВОЕ в 2.0.0: Группы проекта и версии - распределять задачи по имя проекта/Info, Build, Tools, Maintenance; предварительно проверить и совместно применить повышение npm-версии и существующие lock-файлы.
- 🔴 НОВОЕ в 2.0.0: Существующий ИИ-агент - настройка и обслуживание через MCP в Cursor или IntelliJ, по умолчанию без отдельного API-ключа µGulp™. В Cursor мастер также доступен графически в чате.
- 🔴 НОВОЕ в 2.0.0: Выборочные переводы - предлагать только отсутствующие или изменённые относительно baseline тексты плоских JSON-словарей, проверять заполнители и применять проверенное с копией и отменой. Исходный и целевой языки выбираете вы.
- 🔴 НОВОЕ в 2.0.0: Помощь с руководством - после изменений кода показать нужные правки DOCX с доказательствами. Документ, язык и правила выбираете вы; редакционная работа остаётся вашей.
- Сохранить профили и восстановить связь - профили 1.0.0 работают; после завершения движка IntelliJ можно подключить dashboard заново, выбрать новую сессию и проверить новые предложения. Задачи автоматически не повторяются.
- Web Console и Project Center - известные проекты с названием, описанием, логотипом и состоянием сеансов в локальном центре; открытие существующих панелей в браузере, следование за активным проектом IDE или закрепление сеанса только для этой вкладки (обзор и управление хостом доступны в Free)
- Open/Focus Project - открыть известный проект в конкретной установленной IDE или активировать уже открытое окно; при нескольких сеансах выбрать нужный явно (не в Free; точная активация окна пока под Windows)
- Background Host - общая Web Console и контекст активного проекта в одном процессе на пользователя; необязательный запуск при входе и общие настройки, даже без открытой IDE; сам хост не запускает движок проекта
- Идентичность проекта - необязательные название проекта, краткое описание и логотип прямо над списком задач; особенно полезно при нескольких открытых проектах или окнах IDE (
microgulp.config.json→project) - Project Controls - компактная строка списков, переключателей и флажков под идентификацией проекта для общего состояния (например, целевой платформы); сразу влияет на имена, видимость задач/групп и выполнение; значения workspace хранятся в
.microgulp/project-controls.json - Live Animated Task States - поддерживаемые устройства (Stream Deck, клавиатура Logitech, Flexbar) показывают фактическое состояние выполнения из того же движка, что и Dashboard, а не только статичные значки: запуск, анимация выполнения, ожидание ввода, остановка, успех, ошибка (включая Burn/Charred) и отключённое состояние; переключатели Watch и обратный отсчёт планировщика отображаются дополнительными слоями. Анимация сообщает о состоянии, а не служит украшением. (нет в µGulp™ Free; Flexbar: проверка на устройстве ещё не проведена; Actions Ring: только заголовки, SDK без анимации LCD)
- 38 семантических значков задач - подходящие SVG-мотивы через
µTaskKind/µPresentation, анимация выполнения, фиолетовый значок диалога при необходимости ввода, переопределения тем и режим уменьшения движения; при ошибке исходный мотив становится обугленным - Планировщик задач (сеанс) -
µSchedule/ScheduleTask: таймеры (after), интервалы (every), повторения (repeat) и Cron (5 полей, локальное время); обратный отсчёт и Enable/Disable/Cancel/Run now в Dashboard; на клавише устройства показывается обратный отсчёт илиn/m. Запуск остаётся обычным вызовомStartTask - Управление постоянными службами -
µExecutionTypeразличает разовые задачи и постоянные процессы; выполняющуюся службу можно остановить - Управление деревом задач из Gulpfile -
SetGroupState,RevealTaskиSetTaskEmphasisраскрывают группы, показывают следующий шаг и устанавливают либо снимают выделение - Живое наблюдение за gulpfile - watcher рабочей области пересканирует при сохранении и автоматически заменяет устаревшие worker'ы
- Продолжать использовать Gulp CLI - метаданные не меняют экспортируемые имена. Импортируемые API-пакеты нужны; ввод требует CLI-значений или подходящих стандартов, IDE-действия - совместимого хоста (подробнее).
- 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 (настройки: автоматически или фиксированная локаль); дополнительные загружаемые и устанавливаемые пакеты интерфейса запланированы для 2.2.0. Руководство пользователя доступно в PDF для каждого встроенного языка панели
- Синхронизация словарей для ваших gulpfile - Settings → Project i18x (gulp) сканирует исходники парсером i18xe-sync, пишет
i18x/gulp/<lid>.jsonдля выбранных языков, сохраняет существующие переводы и сливает стандартные форматы; соседний<lid>.status.jsonперечисляет, что ещё должна перевести локальная ИИ - Декларативные параметры задачи -
µParametersспрашивает один раз перед запуском, передаёт значения какMICROGULP_PARAMS/GetParameters(), запоминает последние ответы, не пишет пароли в журналы и может скрывать поля черезvisibleWhen - Watch / триггерные задачи - глобы
µWatchзапускают задачу при изменении файлов, с debounce, объединением и предохранителем от разгона; вооружаются по задаче с панели - Поддержка устройств - теперь можно управлять Gulp с помощью Elgato Stream Deck, Logitech MX Creative Console / Actions Ring, Flexbar и геймпадов. Доступно во всех редакциях, кроме µGulp™ Free (настройка и статус устройств).
- Logitech следует за рабочим пространством - фиксированные назначения отдельных задач или профиль Options+ для приложения; плагин показывает рабочее пространство активного окна IDE в динамической папке клавиатуры
- Stream Deck следует за workspace - Follow принимает проект активного окна IDE, запоминает последнюю страницу и группы для каждого workspace и устройства и показывает логотип с названием на Root. При возврате восстанавливаются путь группы и страница. (Проверка нескольких физических устройств ещё предстоит; Elgato Smart Profiles не гарантируются. Logitech сохраняет ограниченный объём функций; Flexbar автоматически не следует.)
- Контроллеры для рабочих процессов - геймпады и джойстики с пользовательскими профилями, обучением вводу, мёртвыми зонами и диагностикой; в Windows x64 работают и без фокуса Dashboard, включая профиль SpaceMouse Wireless, настроенный по результатам измерений, и вибрацию на совместимых устройствах
- Восемь функций IDE API - запрос возможностей и известных проектов, семантические или нативные действия IDE, открытие/активация проектов и запуск настроенных приложений;
µHost/µIdeApiотмечают доступность. Выполняющие функции недоступны в Free;Ide.Capabilities()сообщает возможности хоста (объём API). - Горячие клавиши задач - аккорды
µ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) - Выбор файлов и папок штатным диалогом - поля файлов в формах открывают средство выбора VS Code/Cursor или JetBrains и возвращают настоящий путь
- Модальные диалоги -
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 - Выделение требующих внимания задач без запуска -
µAttentionотмечает необходимость действий;µAttentionWatchобновляет отметку после изменений файлов или через заданный интервал, показывает подсказку, установленную версию и видимые индикаторы даже у свёрнутых групп - Повышение прав администратора в Windows - необязательный запрос UAC для каждой задачи (
µRequiresElevation,µElevationReason); IDE может работать обычно, а отдельные задачи (например, изменение файлаhosts) запускаться с повышенными правами (нет в µGulp™ Free) - Диагностический движок - ошибки импорта и трассировки стека превращаются в практические подсказки прямо в Dashboard (нет в µGulp™ Free)
<version/>из gulpfile -µI18xContext.version- предпочтительный источник для заголовков задач; опциональныйversionSourcesзаполняет только когда gulpfile не задаётversion(без перезаписи конфигов релиза потребителя)- Надёжный LogError против предупреждений Node -
LogError/ настоящийconsole.errorпо-прежнему валят запуск;DeprecationWarningNode и прочие предупреждения процесса - нет (баннер сбоя показывает первый настоящий текст ошибки) - Мост устаревших prompt'ов -
inquirer/gulp-prompt/promptsперенаправляются в формы панели без правки gulpfile gulp-mu-gulp-api- npm-модуль для прогресса, звука, речи, интерактивного ввода, модальных диалогов и шрифтов панели изнутри задач
Оформление задач проекта на выбранном языке
Команда «Настроить задачи проекта» оформляет существующие задачи в выбранном Gulpfile проекта. Глобальные задачи для нескольких проектов управляются отдельно и этим мастером не изменяются.
Язык редактирования применяется к предлагаемым отображаемым именам, описаниям, подсказкам и группам. Поле выбора использует централизованно поддерживаемый список языков проекта i18xe с кодами и названиями на родном языке; можно также ввести другие допустимые коды BCP 47. Исходное значение берется из microgulp.editingLanguage в package.json. Если оно отсутствует, форма использует язык браузера веб-представления IDE. Язык интерфейса независим; язык редактирования можно менять перед каждым запросом.
Команда «Подготовить текстовые предложения с агентом IDE» создает ограниченный запрос для отсутствующих текстовых полей. Gulpfile всегда содержит английские исходные тексты en-US; при другом языке редактирования мастер добавляет соответствующие переводы в i18x/gulp/<sprache>.json. Существующие переводы не перезаписываются. В панели скопируйте показанный запрос в подключенный чат агента Cursor или IntelliJ; графическое MCP-приложение предлагает «Отправить агенту IDE», если клиент поддерживает сообщения. Существующий агент создает тексты и возвращает их через MCP. Дополнительный API-ключ не требуется. Мастер не запускает агента в фоне и не использует платную резервную службу.
Команда «Загрузить предложения в форму» показывает проверенные предложения. Существующие метаданные, ключи переводов, вычисляемые значения и поля, отредактированные вручную за это время, сохраняются. Запрос истекает через десять минут и отклоняется, если изменились Gulpfile или словарь. Предварительный просмотр показывает оба файла вместе; только явное применение с резервной копией записывает Gulpfile и словарь, а отмена восстанавливает предыдущее состояние. Языковая и содержательная проверка остаются за пользователем.
Восемь встроенных языков интерфейса µGulp™ независимы от этого механизма. Дополнительные загружаемые или устанавливаемые пакеты перевода интерфейса µGulp™ запланированы для версии 2.2.0 и пока не входят в этот мастер.
Для значков введите символ или эмодзи либо выберите изображение PNG, JPEG или WebP размером до 64 KiB. Выбранное сразу видно в предварительном просмотре. Изображение встраивается в Gulpfile и не зависит от исходного пути файла. Новые файлы SVG и URL изображений здесь не импортируются. Существующие метаданные значков сохраняются, если применить форму без их изменения.
Целенаправленное улучшение существующего Gulpfile
Мастер настройки сначала проверяет исключительно статически, есть ли у задач метаданные отображения для µGulp™. Отображаемого имени, описания, группы, значка или подсказки достаточно, чтобы распознать уже настроенное представление задачи. Это не полная оценка качества Gulpfile. Не каждой задаче нужны все эти сведения.
Если все распознанные задачи уже настроены, автоматическое предложение оптимизации не появляется. Для частично настроенных Gulpfile диалог предлагает только задачи без таких сведений. Сначала можно добавить имена, описания, группы, значки и подсказки, проверить предварительный просмотр и явно применить изменения с резервной копией. Отмена остается доступной. Другие ИИ-рецепты доступны затем или при сознательном пропуске этого шага.
Вычисляемые или импортируемые метаданные не всегда можно однозначно оценить. В таком случае мастер сообщает, что состояние оптимизации неизвестно, и автоматически эти значения не меняет. Сочетания клавиш предлагаются исключительно как необязательный совет; их отсутствие не считается потребностью в оптимизации. Отсутствие связи с глобальными задачами также не является недостатком. Другие ИИ-рецепты и сочетания клавиш на втором шаге изначально не выбраны.
Глобальные задачи для выбранных проектов
С глобальными задачами больше не нужно искать и запускать одну и ту же задачу отдельно в каждом проекте. Общий ID связывает подходящие реализации ваших проектов: например, NASBU может резервировать разные папки в каждом проекте. Web Console показывает участвующие проекты с названиями и значками; вы явно выбираете, какие из них запускать.
Глобальное определение состоит из стабильного ID и понятного названия. Исполняемая реализация остается в Gulpfile соответствующего проекта. Общий исходный код не распространяется, задачи не копируются автоматически в другие проекты. Разные проекты могут реализовать один ID в соответствии со своими требованиями.
Добавьте к экспортируемой задаче µGlobalTask = { id: "NASBU", title: "NAS-Sicherung" }. ID начинается с заглавной буквы и содержит не более 64 заглавных букв, цифр, подчеркиваний или знаков минуса. Проект может предоставлять каждый ID ровно один раз. Помеченные задачи появляются в панели проекта в отдельной группе «Глобальные задачи»; для них существующий µGroup заменяется.
Откройте Web Console и разверните «Глобальные задачи». Обновите список и выберите общую задачу. В разделе «Настроить проект» один раз сохраните значения из µParameters для соответствующего проекта. Они хранятся локально в .microgulp/global-tasks.json. Изменение определения параметров требует повторной настройки. Пароли и значения с remember: false здесь не сохраняются; такие задачи по-прежнему требуют интерактивной работы в проекте.
В разделе «Определить глобальную задачу» можно централизованно задать ID и название. Список также распознает ID подключенных проектов. Центральное название делает отображение единообразным, но не создает исполняемую реализацию. Определения хранятся в пользовательском каталоге в .microgulp/global-tasks.json.
Выберите проекты по названию и значку. Если для одного проекта открыто несколько окон IDE, выберите ровно один сеанс. «Проверить выбор» показывает только эти проекты и их сохраненные значения. Лишь «Запустить выбранные задачи» передает запуск соответствующим IDE. Закрытые проекты или IDE автоматически не открываются.
Общий запуск использует сохраненные параметры без повторных форм ввода. Если задача все же запрашивает диалог µGulp, этот запуск завершается ошибкой global-task-dialog-required. Задачи с повышенными правами Windows и постоянно работающие задачи глобально не запускаются. Код Gulp остается локальным программным кодом; внешние программы с собственными диалогами от этого не становятся задачами для выполнения без участия пользователя.
Предварительные просмотры краткосрочны и используются только один раз. Изменения Gulpfile, определения задачи, сохраненных параметров или Project Controls делают их недействительными. Если сеанс IDE завершился или сменился, повторите выбор и проверку. Перед первым запуском проверяются все выбранные сеансы.
Общий запуск не является транзакцией: если связь оборвется после первого запуска, предыдущие проекты уже могут работать. Результат показывает запущенные, завершившиеся ошибкой и еще не запущенные проекты. Автоматического повтора и автоматической отмены выполненных задач нет. Прогресс, журналы и остановка доступны в панели соответствующего проекта.
Запуск задачи из одного проекта в другом
Задача в проекте A может с помощью RunGlobalTask из gulp-mu-gulp-api запустить реализацию, помеченную µGlobalTask, в проекте B и дождаться ее завершения. Передайте точный ID проекта и глобальный ID задачи. Параметры целевой задачи нужно заранее настроить в панели проекта B. Проект B должен иметь активное соединение с открытой панелью µGulp. Если для целевого проекта открыто несколько сеансов, дополнительно укажите sessionId нужного сеанса. Закрытые проекты или IDE автоматически не открываются.
import { RunGlobalTask } from 'gulp-mu-gulp-api';
const result = await RunGlobalTask({
projectId: 'Projekt-ID-von-B',
globalId: 'DEPLOY',
timeoutMs: 120000
});
if (!result.ok) throw new Error(result.error ?? result.code);
console.log(result.taskResult);
Ответ содержит состояние, ID запуска и длительность. taskResult присутствует только в случае, если целевая задача вызвала ReportTaskResult. Вызов запускает целевую задачу через подключенный сеанс IDE; видимое окно Web Console для этого не открывается. Вызовы самого себя и рекурсивные цепочки проектов отклоняются. Тайм-аут составляет от 1 до 300 секунд; по умолчанию 120 секунд. При тайм-ауте целевая задача уже может быть запущена.
Глобальные вызовы требуют активного доверенного сеанса IDE с открытой панелью µGulp и редакции с доступом к IDE API. Обзор проектов и прежнее простое управление задачами сохраняются. Самостоятельное выполнение закрытых проектов в Background Host, глобальные аппаратные клавиши и глобальные MCP-инструменты не входят в объем 2.1.0.
Редакции и функции
µ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). Сравнение ниже отражает текущие редакции. Не устанавливайте зарегистрированное расширение VS Code одновременно с µGulp™ Free: у них совпадают идентификаторы команд. Зарегистрируйте полную редакцию VS Code до запуска первой задачи либо удалите её и используйте µGulp™ Free. Для JetBrains регистрация µGulp™ не требуется; редакции Free для JetBrains нет.
| µGulp™ VS Code / Cursor |
µGulp™ Free VS Code / Cursor |
µGulp™ JetBrains IDEs |
|
|---|---|---|---|
| Цена (месяц / год) | 0 € / $0 | 0 € / $0 | 0 € / $0 |
Панель задач, предварительная загрузка, i18x, параметры, µWatch, µSchedule, история |
да | да | да |
| Лицензия / регистрация | обязательна | нет | нет |
| Скины (Neon Carbon, Ice Light, IDE Dark / Light, Automatic) | да | IDE Dark / Light по теме IDE (не выбирается) | да |
| Пользовательские ZIP-пакеты тем | да | - | да |
| Движок диагностики | да | - | да |
| Повышение прав UAC Windows | да | - | да |
| Аппаратные интеграции (Stream Deck, Logitech, Flexbar) | да | - | да |
| Действия IDE из задач | да | - | да |
| Web Console: проекты, состояние сеансов, встроенная панель | да | да, действуют обычные разрешения задач | да |
| Background Host и управление хостом | да | да | да |
| Open/Focus Project, Start Application, действия IDE, предпочитаемая IDE | да | - | да |
| Настройки хоста | microgulp.* |
microgulp.* |
Settings → Tools → µGulp |
| Marketplace | Установить для VS Code · Установить из Open VSX | Установить µGulp Free · Установить из Open VSX | Установить для JetBrains (de.amekudzi.microgulp) |
Все редакции сейчас бесплатны (0 € / $0 в месяц и в год). Пункты ниже описывают полный продукт. Free использует тему IDE/ОС - IDE Dark / IDE Light (без выбора темы) - и не включает пакеты тем, диагностику, повышение прав, аппаратные интеграции и действия IDE. Локальная Web Console доступна и в Free: обзор проектов, состояние и управление хостом; расширенные действия (Open/Focus Project, Start Application, действия IDE, предпочитаемая IDE) доступны только в остальных редакциях.
Новое в 2.0.0
Мастер добавляет ИИ-рецепты в существующие проекты и показывает все изменения файлов перед применением. Также появились необязательное подключение MCP к агенту IDE и помощь с переводами и руководствами. Повседневный порядок прежний: открыть проект, выбрать задачу, запустить.
Универсальный генератор рабочих процессов ИИ, семантическая оптимизация произвольных задач и эволюционная самооптимизация остаются нереализованными идеями без обещанных сроков и объёма.
Доступно с 1.1.0
Необязательная информация формы отображается перед полями ввода. Задачи могут явно включать отмену и сохранение допустимых выбранных значений. µI18xContext.GetValues() синхронно получает метаданные при каждом сканировании; изменение подстановок также обновляет список задач. Существующие gulpfile и успешные ответы форм сохраняют совместимость. Новые функции описаны в gulp-mu-gulp-api 0.7.0.
Контракт форм и примеры · Примечания к 1.1.0
Мастер настройки и ИИ-рецепты
Настроить задачи проекта открывает в dashboard мастер для существующего gulpfile. Он статически анализирует ESM/CommonJS, предлагает подходящие поля и показывает все изменения до применения. Девять ИИ-рецептов охватывают отображаемые имена и описания, свободные группы и группы проекта, сочетания клавиш, NAS-резервирование, microCSS, первоначальную настройку, подготовку GitHub и npm.
- NAS-резервирование: идентификатор проекта, источник, несколько назначений, режим, каталог или ZIP, способ копирования и исключения. По умолчанию включён пробный запуск; идентификаторы назначений показаны для осознанной подготовки. Сама настройка не обращается к NAS.
- microCSS: существующий доверенный манифест, папки источника и вывода, сжатие и предпросмотр изображений. Каждый build использует новую подпапку вывода.
- Безопасное применение: полный предпросмотр файлов, проверка хешей источников, защита существующих файлов ИИ-рецептов, копия в
.microgulp/setup-backupsи отмена последнего неизменённого применения в той же сессии.
Нужные зависимости указаны в предпросмотре; затем их устанавливают через npm install в папке соответствующего ИИ-рецепта. Три новых варианта подготовки не требуют дополнительных пакетов ИИ-рецептов. Импорты манифеста microCSS требуют своих пакетов также в исходном проекте. Выполняющиеся задачи и сканирования блокируют изменения. Динамические конструкции gulpfile могут потребовать ручной адаптации.
Подготовка первоначальной настройки и публикации
ИИ-рецепты Первоначальная настройка, Публикация GitHub и Публикация npm добавляют подготовительные задачи в существующий gulpfile. У каждого есть форма имени проекта и параметров. Задачи показывают подходящие проверки и команды; не устанавливают зависимости, не делают push и не публикуют. Применение в мастере также не разрешает публикацию.
- Первоначальная настройка (
project-bootstrap): проверить файл пакета, состояние Git, исключения, зависимости, существующие скрипты сборки и тестов. Для нового проекта сначала создать пустойgulpfile.mjsи выбрать его. Отсутствующие файлы пакета перечисляются как шаг подготовки, а не создаются незаметно. - GitHub (
github-release): выбратьEigentümer/Repositoryи видимость. План охватывает вход, проверку remote и файлов, осознанное создание отсутствующего репозитория, push проверенного коммита и черновик релиза с проверенным тегом. Создание репозитория, push и публикация остаются отдельными действиями по явному поручению. - npm (
npm-release): выбрать patch, minor или major, реестр, доступ и канал. Включить повышение версии в предпросмотр файлов показывает новую версию вpackage.jsonи существующихpackage-lock.json/npm-shrinkwrap.json. При применении эти файлы сохраняются и меняются вместе с gulpfile; отмена восстанавливает их побайтно. Без опции план оставляет повышение отдельным предстоящим шагом.
Автоматическое повышение поддерживает стабильные версии вроде 1.2.3; предварительные версии и наборы workspace-пакетов требуют процесса проекта. Приватные пакеты, противоречивые lock-файлы или отличающиеся параметры публикации блокируют автоматическое изменение. При наличии RELEASES.json отключить автоматическое повышение и использовать синхронизацию версий проекта. Другие собственные источники версии также обслуживаются процессом проекта. Запуск подготовительных задач не повышает повторно версию, уже повышенную при настройке.
Предпросмотр и запуск задачи не запрашивают реестр. Поэтому план npm требует до реальной публикации проверки реестра, тестов, сборки, проверки содержимого пакета и входа. Локальное повышение не подтверждает доступность версии в реестре. Опубликованный пакет нельзя повторно опубликовать с той же версией. Публикация npm · Версии npm · Черновик релиза GitHub
Группировка задач по проекту
Каждый из трёх ИИ-рецептов создаёт четыре задачи в Имя проекта/Info, Имя проекта/Build, Имя проекта/Tools и Имя проекта/Maintenance. Info содержит проверки исходного состояния и результата, Build подготовку сборки, Tools вспомогательные проверки, Maintenance настройку, версии и подготовку релиза. По умолчанию имена начинаются с SETUP_PROJECT, PREPARE_GITHUB_RELEASE или PREPARE_NPM_RELEASE, затем добавляется категория прописными буквами.
Группы задач проекта (project-structure) позволяют распределить и выбранные существующие задачи: ввести имя проекта и выбрать одну из четырёх категорий для каждой. Экспортируемые имена и код неизменны. Этот ИИ-рецепт нельзя применять одновременно со свободным ИИ-рецептом Группы задач. Распределение видно в предпросмотре и входит в резервную копию.
MCP предоставляет те же формы и изменения через list_recipes, get_recipe, preview_setup, apply_setup и undo_setup. get_recipe и list_library также выдают версионированные инструкции агенту IDE, включая проверку версии и разрешение публикации. Отдельного автоматически публикующего ИИ-skill в ИИ-рецептах нет. К 19 октября 2026 года ИИ-рецепты старта проекта, GitHub и npm дополнительно проверены через MCP в установленных Cursor и IntelliJ: предпросмотр, применение, чтение файлов и отмена. Исходные хеши восстановлены, включая пакет и lock-файл при повышении npm-версии. Подготовительные задачи, запросы реестра и публикации при этом не выполнялись.
Настройка через MCP
Отдельный адаптер MCP предоставляет тот же процесс через list_recipes, get_recipe, list_setup_files, analyze_gulpfile, preview_setup, apply_setup и undo_setup. list_projects, list_tasks и get_task дают проекты, конкретные сессии IDE и каталог задач. С open_setup_assistant клиент MCP Apps, например Cursor, открывает графическую настройку в чате: выбрать и проанализировать gulpfile, отметить ИИ-рецепты, заполнить формы и проверить полный предпросмотр. Применение и отмена имеют отдельные кнопки с защитой как в dashboard. Cursor может запросить разрешение вызовов приложения. Клиенты без MCP Apps продолжают использовать отдельные инструменты.
Нужны Node.js 22 или новее и активная сессия обновлённого хоста. После установки отдельных SDK-зависимостей (npm ci --prefix <Installationsordner>/src/mcp --omit=dev --ignore-scripts) клиент запускает node <Installationsordner>/src/mcp/microgulp-mcp.mjs --project <absoluter-Projektpfad>. Для изменений требуется также --setup-write-project <derselbe-Projektpfad>. Без этого разрешения при старте доступны только чтение, анализ и предпросмотр. Предложения разделены по процессу MCP и сессии IDE. Эти инструменты не запускают задачи, не устанавливают пакеты автоматически и не публикуют.
Проверка текстовых предложений и подключение MCP после обновления
Откройте «Настроить задачи проекта» и выберите Gulpfile, нужные задачи и язык редактирования. Подготавливайте запрос текстов только после подключения агента IDE к MCP-серверу µGulp™. Скопируйте показанный запрос в этот чат. Оставьте форму открытой: запрос действует десять минут и относится к текущему движку проекта.
После ответа агента нажмите «Загрузить предложения в форму» в той же форме. Проверьте добавленные имена, описания, подсказки и группы. Ответ review-required означает лишь наличие предложения; он не подтверждает ни его качество, ни изменение Gulpfile. Неподходящие или бессодержательные тексты можно исправить или исключить. Агент не должен придумывать неизвестную функциональность на основании имени задачи.
Затем проверьте предварительный просмотр изменений и при необходимости примените их с резервной копией. Команда «Отменить это изменение» восстанавливает сохраненное состояние, если последующих изменений не было. Запрос, подготовленный прямо в чате, не связывается автоматически с уже открытой формой. Поэтому для работы через форму начинайте с показанного в ней запроса. После истечения срока, смены языка или перезапуска движка подготовьте новый запрос.
После обновления расширения каталог установки может измениться. Проверьте путь к microgulp-mcp.mjs в конфигурации MCP и установите отдельные зависимости SDK в новом каталоге src/mcp командой npm ci --omit=dev --ignore-scripts. Включенный сервер еще не доказывает, что соединение работает. При Connection closed проверьте журнал сервера; если отсутствует @modelcontextprotocol/sdk, эти зависимости не установлены в используемом каталоге.
Переподключите MCP-сервер и откройте новый чат агента. Проверьте текущий сеанс через list_projects. Для текстовых предложений должны быть доступны prepare_setup_text, get_setup_text и submit_setup_text. Если list_projects возвращает проект без сеанса, откройте его панель µGulp™. Необходимы и доступное MCP-соединение, и активный движок проекта.
Графическое MCP-приложение в Cursor
- Открыть проект в Cursor и подключить настроенный MCP-сервер µGulp™. Он предлагает инструменты настройки, доступа к задачам, необязательные skills и UI-ресурс.
- Попросить агента: «Определи текущую сессию проекта через
list_projectsи открой для неёopen_setup_assistant. После этого ничего не меняй». Развернуть результат инструмента, если приложение свёрнуто. - Выбрать gulpfile и Analyze gulpfile. Самостоятельно подтвердить запрошенные Cursor разрешения. Выбрать ИИ-рецепты и заполнить поля: идентификатор NAS, источник и назначения; манифест microCSS, источник и вывод; имена, описания, группы и клавиши.
- Нажать Preview changes. Проверить до/после, полный новый gulpfile и разворачиваемые новые файлы ИИ-рецептов. Здесь также указаны пакеты и подготовка идентификаторов NAS. Пока никакие файлы не записаны.
- Apply changes and create backup применяет проверенное предложение и сохраняет оригиналы в
.microgulp/setup-backups. Изменённые источники, существующие файлы ИИ-рецептов и активные задачи предотвращают небезопасное применение. - Undo this change побайтно восстанавливает оригиналы и удаляет лишь файлы ИИ-рецептов, созданные этим применением. Последующие правки блокируют отмену. Последнее применение отменяется только в том же соединении MCP и сессии IDE.
Без --setup-write-project остаются анализ и предпросмотр; применение скрыто. Интерфейс не запускает задачи и не устанавливает пакеты. Несколько представлений и вызовов агента одного соединения разделяют последний предпросмотр: работать следует с одним предложением за раз.
После перезапуска Cursor, хоста или MCP снова вызвать list_projects и open_setup_assistant и повторить анализ. Старое представление может сообщить ide-session-unavailable. Предпросмотры действуют десять минут. Если связь оборвалась при применении, сначала проверить файлы и копию. После обновления VSIX проверить путь установки MCP, при необходимости повторно установить SDK-зависимости и подключить сервер.
Подключение MCP в Cursor и IntelliJ
MCP и skills необязательны. Для обычной работы достаточно открыть проект, выбрать задачу и запустить. Следующие шаги требуют открытого проекта в обновлённом хосте µGulp™. Использовать фактическую папку установки: адаптер в src/mcp у Cursor, в microgulp/src/mcp распакованного плагина JetBrains. Установить туда отдельные SDK-зависимости, как описано выше.
Пример подходит обоим клиентам. Заменить абсолютные пути своими; --setup-write-project разрешает последующее проверенное применение и отмену именно в этом проекте:
{
"mcpServers": {
"microgulp": {
"command": "C:/Program Files/nodejs/node.exe",
"args": [
"C:/Pfad/zur/Installation/src/mcp/microgulp-mcp.mjs",
"--project", "C:/Projekte/MeinProjekt",
"--setup-write-project", "C:/Projekte/MeinProjekt"
]
}
}
}
- Cursor: добавить сервер в
.cursor/mcp.jsonпроекта, сохранив существующие записи. Включить в управлении MCP и проверить состояние. После правок конфигурации переподключить и открыть новый чат агента. - IntelliJ: в Settings → Tools → AI Assistant → Model Context Protocol (MCP) через Add добавить STDIO, вставить JSON и запустить через Apply. В Tools → AI Assistant → Agents также включить и подтвердить Pass custom MCP servers. Pass IntelliJ MCP server относится к встроенному серверу IDE и не заменяет передачу пользовательских серверов. Затем открыть новый чат выбранного агента. Здесь проверен Codex со входом ChatGPT; отдельный API-ключ µGulp™ не нужен. Настройка JetBrains
Первый запрос: «Вызови инструмент list_projects сервера MCP microgulp. Без запросов ресурсов и изменений». Проверить путь проекта, IDE и сессию в настоящем ответе. unknown MCP server или отсутствие инструментов означают, что чат ещё не подключён. Проверить состояние сервера, передачу и новый чат. Успешный запрос ресурсов не заменяет проверку инструмента. Использовать возвращённые projectId и sessionId, не старые идентификаторы.
Skills с существующим агентом
Версионированная библиотека доступна через list_library. Профили в .microgulp/agent-profiles.json задают разрешённые входные файлы и версию skill. Стандарт execution: "client" использует агента IDE. Отдельные skillGrants нужны только для явно включённого режима API; пустой список не мешает обычному клиентскому процессу. start_api_skill не является автоматической заменой отсутствующему соединению агента.
Пример профиля перевода; все три JSON-файла уже должны существовать:
{
"schemaVersion": 1,
"profiles": {
"texte-de": {
"enabled": true,
"skill": "localization",
"version": "1.1.0",
"execution": "client",
"configuration": {
"source": "i18x/source.json",
"target": "i18x/de-DE.json",
"baseline": "i18x/source-baseline.json",
"sourceLanguage": "en-US",
"language": "de-DE"
}
}
}
}
inspect_skill_profileвозвращает текущий хеш.start_skillполучает ID профиля, хеш и новый уникальныйrequestId. Задание действует 30 минут.- Агент обрабатывает записи и передаёт результат, ID задания и неизменённый
digestвsubmit_skill_result. Предложение сохраняется в.microgulp/proposals/<id>/proposal.json; файл перевода неизменён. - Проверить цель, изменённые тексты, сохранённые заполнители и неизменённые записи. Только затем разрешить
apply_skill_proposalс ID предложения. µGulp™ повторно проверяет источники и сохраняет оригинал в.microgulp/proposals/<id>/original.json. - Проверить фактический файл.
undo_skill_proposalотменяет это применение с тем же ID, если файл не изменился и сохраняются соединение MCP и сессия хоста. Для приёмки сравнить хеш до теста и после отмены.
Простой запрос: «Используй профиль texte-de с текущим агентом, отправь результат через MCP и покажи предпросмотр. Остановись до применения. Не меняй файлы напрямую». Применение и отмена запрашиваются отдельно. После skill-expired подготовить заново; при unknown-skill-run или unknown-undo сначала проверить сессию, файлы и копию. Не повторять вслепую и не заменять отмену прямой записью.
Руководство: предпросмотр с доказательствами
Профиль с skill: "handbook-maintenance", версией 1.1.0 и execution: "client" задаёт в configuration произвольно названный DOCX проекта как master, его sourceLanguage, файлы реализации в files и полный существующий Git-коммит как baselineCommit. outputLanguage необязательно задаёт язык предложений; иначе используется исходный. chapters ограничивает главы, editorialRules содержит необязательные редакционные правила проекта. Коммит должен читаться из открытого проекта. PDF и Markdown этот skill пока не обрабатывает.
До submit_skill_result процесс совпадает с переводом. Предпросмотр содержит предложения со ссылками на файлы и строки и editorial-review-required. Автоматического применения DOCX нет: apply_skill_proposal отклоняет отчёт с handbook-report-requires-editorial-work. Редактирование выполняется отдельно в настроенном DOCX. Skill не обновляет сравнительные baseline, переводы или готовые выходные документы. Правило «сначала немецкие .src., потом только перевод различий» относится исключительно к профилю нашего проекта µGulp™; клиенты определяют свой порядок.
Пример руководства клиента
Источник может называться docs/Customer Guide.docx. Этот профиль использует английский источник и французские предложения. Заменить заполнитель настоящим полным Git-коммитом проекта:
{
"enabled": true,
"skill": "handbook-maintenance",
"version": "1.1.0",
"execution": "client",
"configuration": {
"master": "docs/Customer Guide.docx",
"sourceLanguage": "en-US",
"outputLanguage": "fr-CA",
"files": ["src/build.mjs"],
"baselineCommit": "<vollständiger Git-Commit>",
"editorialRules": "Kundenterminologie erhalten und bestehende Kapitelstruktur beachten."
}
}
Запись помещают под своим именем в profiles файла .microgulp/agent-profiles.json. Проверяются языковые коды вроде de-DE, en, fr-CA и zh-Hant. Язык результата агента автоматически лингвистически не сертифицируется. Источник и цель перевода должны различаться; поддерживаются плоские JSON-словари строк, а не общий перевод Markdown или DOCX.
Обновление существующих профилей
Профили skill 1.0.0 продолжают работать для переводов и руководств. Файл и хеш автоматически не переписываются. Без sourceLanguage язык старых переводческих профилей остаётся неопределённым (und); агент определяет его по тексту. Старые профили руководств без языка сохраняют de-DE. Явные настройки приоритетны. Новые клиентские профили используют 1.1.0 с сознательно выбранными источником и языком; правила проекта хранятся только в профиле. Для постоянной миграции сохранить копию, проверить версию и языки, подготовить новое задание. Неизвестные версии и ошибочные профили индивидуально помечаются неисполняемыми, не блокируя соседние корректные. Некорректный файл профилей в целом по-прежнему отклоняется. Пины библиотеки и значения целостности не обновляются автоматически. Предпросмотр, защита заполнителей, копия, отмена и запрет автоматического DOCX действуют и для старых профилей.
Восстановление соединения dashboard в IntelliJ
После завершения движка проекта открытое окно µGulp™ обнаруживает это и предлагает Reconnect dashboard. Скрытие и повторное отображение окна запускает движок, определённый как остановленный. Работающий движок не перезапускается; задачи не повторяются. При ошибке запуска сообщение и возможность повторить остаются видимыми, без автоматического цикла. Без сигнала готовности запуск прекращается максимум через 120 секунд. Проверить путь Node и настройки, затем выбрать Reconnect dashboard. После восстановления снова вызвать list_projects и выбрать новую сессию. Старые ID предложений и отмены не использовать в новой сессии; проверить копии до нового поручения на изменения. Зелёный статус MCP сам по себе не подтверждает активную сессию dashboard.
Проверенные процессы и разрешения
Настраиваемые клиентские профили skill 1.1.0 проверены через MCP в установленных Cursor и IntelliJ к 19 октября 2026 года: en-GB в fr-CA, предпросмотр с сохранённым заполнителем, применение и побайтная отмена. Источник DOCX и язык отчёта выбирались свободно; автоматическое применение отклонено с handbook-report-requires-editorial-work, хеш не изменился. Совместимость профилей 1.0.0 затем дополнительно подтверждена в IntelliJ. Это доказывает контролируемый процесс, но не качество любых результатов агента.
19 октября 2026 года проверено восстановление IntelliJ через Reconnect dashboard после завершения движка: новая сессия доступна по MCP, последующие тесты старых профилей успешны. Переводы применены и побайтно отменены; автоматическое изменение руководства отвергнуто сервером, DOCX неизменён. Это подтверждает конкретный случай восстановления, а не произвольные работающие задачи или старые ID.
Последний локальный запуск Windows с Node.js 22 завершился 1115 успешными тестами, без ошибок и с четырьмя явно пропущенными случаями платформ/устройств. Ещё 31 тест MCP/сайта успешен. Обновлённые пакеты VS Code, Cursor Internal и Free установлены и проверены успешной задачей dashboard. JetBrains Plugin Verifier подтверждает совместимость с проверенными платформами 242, 261 и 262; два замеченных устаревших API-вызова удалены. Исправленный пакет JetBrains установлен и проверен локально в Windows с IntelliJ IDEA 2026.2.2: подтверждение предзаполненного пути, отмена выбора, открытие лога, полный начальный dashboard, скрытие/открытие, разворачивание/восстановление и изменение размеров окна. Переходы между мониторами с разным DPI не проверялись. Прежние нативные MCP-приёмки остаются привязанными к своим пакетам. Это не заменяет новый межплатформенный CI и оставшиеся физические аппаратные тесты.
17-19 октября 2026 года локальные пакеты 2.0.0 проверены в Windows настоящим агентом Cursor и Codex в чате IntelliJ: предпросмотр перевода, применение, чтение файла, побайтная отмена; также обоснованный отчёт руководства, отказ автоматического DOCX и неизменный хеш. Графическое MCP-приложение проверено в Cursor, что не подтверждает графическое приложение IntelliJ. Другие агенты и ОС не охвачены.
Первый запуск Cursor сообщил unknown-undo; причина осталась невыясненной. Следующий полный цикл прошёл успешно. Поэтому при ошибках нужно явно проверять сессию и копию. Отказ клиентской проверки разрешений, например Guardian, не является ответом µGulp™ или успешным негативным тестом. Не обходить разрешения; дополнительная попытка требует отдельного явного разрешения. Для негативного DOCX-теста нужны реальная ошибка µGulp™ и прочитанный после неё неизменный хеш.
Настройка запуска, процесс и ограничения
Снимок
| 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 (возрастающее целое); группы по минимальному порядку в поддереве; задачи без порядка в конце (по алфавиту) |
Нажмите задачу → доступный тёплый воркер выполнит её без повторного импорта Gulpfile. Сохраните Gulpfile → список задач обновится автоматически. Можно запускать несколько задач параллельно; каждая получит отдельный сектор Dashboard с неоновой полосой прогресса, если задача вызывает ReportProgress из gulp-mu-gulp-api.
Продолжать использовать Gulp CLI
Дополнительные метаданные не меняют CLI-адресацию. Существующие сборки могут продолжать работать с обычным gulp и CI. Импортируемые пакеты нужны; входные значения и зависимые от хоста действия должны подходить этому пути. Проверить прежние CLI-вызовы после интеграции.
Поведение без dashboard
| Что вы добавляете | Что с этим делает обычный 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/ |
В зависимости от использования содержит также ИИ-рецепты, профили, конфигурацию и копии. Не удалять без разбора: импортируемый код может требоваться CLI. Версионировать файлы проекта выборочно; исключить локальные логи, секреты и резервные копии |
gulp-mu-gulp-api - обычный npm-пакет без зависимостей времени выполнения, а IsMicroGulp() сообщает задаче, оркестрируется ли она. После удаления расширения сохранить нужные пакеты и ИИ-рецепты. Зависимые от хоста действия требуют подходящего резервного пути.
Учитывать требования версий
Обычная Gulp CLI игнорирует дополнительные метаданные. Это не обещание совместимости любых версий хоста, Gulp и API: новые вызовы могут требовать новых пакетов, IDE-действия - нужных возможностей хоста. Соблюдать требования и проверять вызовы после обновления.
Коллега может продолжать запускать задачи через npx gulp BUILD в терминале, пока вы используете dashboard. Оба пути работают с одними файлами; параллельную запись нужно согласовать в проекте.
Установка
µGulp™ уже доступен. Устанавливайте из публичных карточек:
| Издание | Установка |
|---|---|
| µGulp™ (VS Code / Cursor) | Установить для VS Code · Установить из Open VSX |
| µGulp™ Free (VS Code / Cursor) | Установить µGulp Free · Установить из Open VSX |
| µGulp™ (JetBrains IDEs) | Установить для JetBrains |
Исходный репозиторий остаётся закрытым. Не ставьте зарегистрированное издание VS Code/Cursor и µGulp™ Free рядом - у них одни и те же ID команд.
Затем выполните µGulp: Open Dashboard из палитры команд (или нажмите ракету µGulp™ в строке состояния).
IDE JetBrains
Плагин JetBrains - платформенный плагин (com.intellij.modules.platform) - ставится в IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip и другие IDE на базе IntelliJ. Установить для JetBrains с Marketplace; карточка предлагает две сборки по совместимости, IDE получает подходящую (Help → About):
| IDE build | since-build |
Marketplace |
|---|---|---|
2024.2 - 2026.1 (до 261.*) |
242 |
Установить для JetBrains |
| 2026.2 и новее | 262 |
Установить для JetBrains |
Marketplace выбирает подходящую сборку. IntelliJ IDEA, PhpStorm, WebStorm и остальные IDE на базе IntelliJ делят эти два варианта - по сборке платформы, не по имени продукта. В дескрипторе каждого варианта стоит
<idea-version since-build="…"/>- IDE не загрузит другой. Вариант 2024.2-2026.1 -since-build="242"/until-build="261.*". Вариант 2026.2+ -since-build="262"без верхней границы. Сборку платформы показывает 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), поэтому дескриптор должен объявить его явно - отсюда отдельный вариант Marketplace. Установка через JetBrains Marketplace (Settings → Plugins → Marketplace, поиск MicroGulp), затем откройте окно инструментов µ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/.
Офлайн-пакеты
Эти файлы есть только в локальном checkout исходного репозитория. Это не публичный путь установки.
Локальная установка 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/.
JetBrains zip из локальной сборки:
| IDE build | Пакет |
|---|---|
2024.2 - 2026.1 (до 261.*) |
packages/microgulp-jetbrains_latest.zip |
| 2026.2 и новее | packages/microgulp-jetbrains-2026.2_latest.zip |
Локальный zip ставится через Settings → Plugins → ⚙ → Install Plugin from Disk…
Файл конфигурации microgulp.config.json (JetBrains и CLI)
В VS Code / Cursor движок настраивается через настройки расширения (microgulp.gulpfilePattern и т. д.). Плагин JetBrains отражает эти параметры движка в Settings → Tools → µGulp (передаются как CLI-флаги sidecar при следующем открытии окна инструментов). Опционально корневой microgulp.config.json по-прежнему даёт командные значения по умолчанию и ключи, которых нет на странице IDE (dashboardFonts, metadataWatchFiles, versionSources, project). Обычное CLI/браузерное использование через microgulp-serve читает файл, когда CLI-флаг не задан:
{
"gulpfilePattern": "gulpfile.*\\.mjs$",
"poolSize": 2,
"maxParallel": 6,
"preload": true,
"watchGulpfiles": true
}
| Key | Type | Default | Meaning |
|---|---|---|---|
gulpfile |
string | - | Единственный gulpfile относительно корня проекта; выход за пределы корня запрещён |
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. |
project |
объект | - | Необязательно. Идентичность проекта для списка задач: title, description, logo (SVG/PNG/WebP, относительно корня). Без значений дополнительного заголовка нет. |
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. Изменения project (название, описание, логотип) применяются без перезапуска IDE при активном gulpfile-watch.
Идентичность проекта (project)
Необязательный компактный заголовок над списком задач, чтобы при нескольких открытых окнах IDE сразу было видно, к какому рабочему пространству относятся задачи:
{
"project": {
"title": "ESP][",
"description": "Apple II emulator for ESP32-S3",
"logo": "./assets/esp2.svg"
}
}
- Все три поля необязательны; без метаданных прежняя вёрстка не меняется.
logo: пути относительно корня проекта; форматы SVG, PNG, WebP. Отсутствующие или неверные файлы игнорируются (заголовок без логотипа).- Подсказка на заголовке: название, описание (если задано) и абсолютный путь рабочего пространства.
- Идентификация проекта отображается в списке панели и Web Console. Stream Deck показывает логотип с сохранением пропорций и название в отдельной полосе на Root браузера групп; непригодный логотип заменяется резервным изображением. Logitech MX использует изображение проекта от подключённого хоста для выбора workspace и клавиши µGulp™, с фирменным изображением как резервным. Полная приёмка на устройстве ещё предстоит; для Flexbar такое отображение не обещается.
В 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) поэтому - чистая смена адаптера; минимальный sidecarnpm 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™ находит gulpfiles по единственному пути или регулярному выражению, охватывающему весь workspace. Выбор относится к проекту и одинаков в VS Code, Cursor, JetBrains и CLI:
- Явное переопределение IDE или CLI: настройка VS Code/Cursor, JetBrains Settings → Tools → µGulp или
microgulp-serve --gulpfile/--gulpfile-pattern. Пустое поле ничего не переопределяет. microgulp.config.jsonв корне (gulpfileилиgulpfilePattern).- По умолчанию:
gulpfile.mjsв корне, иначе поиск по(^|/)gulpfile\.(m|c)?js$.
На каждом уровне шаблон имеет приоритет над единственным путём. Путь вне корня отклоняется; отсутствие файла вызывает предупреждение и переход к следующему уровню.
microgulp.gulpfilePattern- JavaScript-regex (без учёта регистра) против пути относительно рабочей области (POSIX с/). Когда задан, сканируется каждый подходящий файл; задачи группируются по источнику на панели. Пример:(^|/)gulpfile\.(m|c)?js$находитgulpfile.mjs/.js/.cjsв корне и в каждой подпапке.microgulp.gulpfilePath- явно заданный единственный путь; по умолчанию пуст, чтобы применялсяmicrogulp.config.json.
В 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, file, folder |
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, accept |
numeric / textarea details; accept on file is .zip,.json |
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) не могут показать форму из своего одностороннего процесса, поэтому идут с запомненными значениями поверх объявленных значений по умолчанию.
Поддерживаются длинные списки (select / radio / checkbox): по умолчанию хост сохраняет до 5000 вариантов на поле (переопределение MICROGULP_MAX_SELECT_OPTIONS; 0 = без ограничения). Сокращение сопровождается видимым предупреждением, а не скрытым обрезанием. От 24 вариантов появляется фильтр. У разовых RequestForm из gulp-mu-gulp-api нет лимита хоста для передаваемых в реальном времени данных; применяются те же типы полей и фильтр.
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.µShortDisplayName = 'CSS, Build Styles<context="µShortDisplayName"/>'.i18xRegister(); // Optionaler Kurztext für Stream Deck und Logitech MX
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();
µShortDisplayName - необязательная i18x-фраза для коротких аппаратных подписей. Она не меняет имя dashboard или ID задачи. При необходимости содержит «короткий текст, исходный текст», например CSS, Build Styles. Контекстный тег µShortDisplayName нужен только в исходной i18x-фразе; хост удаляет его перед выводом. На устройстве теги не показываются.
Контекстные теги, обязательные форматы и план языков marketplace: dev/docs/MicroGulpI18xProfile.md.
Представление и управление задачами из Gulpfile
µGulp™ показывает, находится ли задача в покое или отключена, запускается, выполняется, ожидает ввода, останавливается, завершилась успешно или с ошибкой. Рамка состояния остаётся видимой и с собственными значками. Для незавершённого запроса ввода появляется фиолетовый значок диалога; ответьте в Dashboard.
Для семантического представления доступны 38 SVG-значков. µTaskKind и µPresentation описывают задачу - например, сборку, тестирование, копирование или публикацию. Значки соответствуют теме, могут заменяться темой и поддерживают уменьшение движения. Анимация показывает выполнение; при ошибке исходный мотив становится обугленным. Настройки µIcon и µIconFont сохраняются.
Постоянная служба отмечается через µExecutionType = 'persistent', и её можно остановить. Это не связано с µWatch, который повторно запускает задачу при изменении файлов, и µAttention, который отмечает необходимость действий. С помощью µAttentionWatch отметку можно обновлять после изменений файлов или через заданный интервал, не запуская задачу.
Из задачи Gulp можно управлять и обзором задач:
import { SetGroupState, RevealTask, SetTaskEmphasis } from 'gulp-mu-gulp-api';
SetGroupState('Build', 'open');
RevealTask('PUBLISH_NPM', { expand: true, scroll: true, highlight: 'attention' });
SetTaskEmphasis('PUBLISH_NPM', null);
µGroups задаёт начальное состояние; последующие изменения групп действуют в течение сеанса. Выделение и состояние выполнения независимы: выполняющаяся задача одновременно может требовать внимания. Dashboard и устройства получают одно и то же состояние задачи. Раскрытие группы в Dashboard не запускает её задачи.
Действия IDE из задач
Задачи Gulp импортируют Ide из gulp-mu-gulp-api. Реализованный объём 1.0.0 включает восемь функций:
| Функция | Назначение |
|---|---|
Ide.Capabilities() |
Запросить семейство хоста, редакцию, доступные операции и семантические действия; доступна даже при блокировке выполняющих функций |
Ide.Projects() |
Запросить известные проекты, живые сеансы и настроенные приложения |
Ide.Action(id) |
Выполнить семантическое действие в текущем хосте IDE |
Ide.OpenProject(request) |
Открыть известный проект в выбранной установке IDE или активировать его конкретный сеанс |
Ide.StartApplication(applicationId) |
Запустить известное или явно настроенное локальное приложение |
Ide.Execute({ vscode, jetbrains, args }) |
Выполнить нативную команду, указанную для текущего семейства хоста |
Ide.Vscode.ExecuteCommand(commandId, ...args) |
Выполнить разрешённую команду VS Code/Cursor |
Ide.JetBrains.ExecuteAction(actionId) |
Выполнить разрешённое действие JetBrains |
Общий каталог Ide.Action содержит open-settings, save-all, open-terminal, open-problems, find-in-project, quick-open, command-palette, next-editor, previous-editor, run и debug. Run/Debug используют текущую нативную конфигурацию. Доступность зависит от IDE, установленных плагинов и разрешённых команд; одинаковые возможности всех продуктов JetBrains не гарантируются.
Ide.OpenProject получает projectId из Ide.Projects().result.projects и, например, applicationId из возвращённого списка приложений. Для конкретного сеанса нужны одновременно sessionId и connectionId. Устаревшие цели отклоняются, а не заменяются другим сеансом.
µHost указывает нужное семейство IDE; µIdeApi = true отмечает задачи, использующие интерфейс. Движок проверяет редакцию, регистрацию и разрешённые команды. В µGulp™ Free запрос Ide.Capabilities() доступен; остальные семь функций заблокированы, включая Ide.Projects(). Читаемый обзор проектов Web Console доступен независимо.
Вызовы возвращают Promise с { ok, result } или { ok: false, code, message }. Без IPC µGulp™, например в обычной gulp CLI, все восемь возвращают unsupported-host и не запускают IDE. Отсутствие разрешения редакции или регистрации даёт unsupported-edition или unsupported-registration. В gulpfile можно предусмотреть собственную альтернативу для CLI и CI.
Этот объём описывает реализацию в репозитории, а не доступность в уже опубликованной версии npm. Ide.OpenUrl только запланирован и недоступен.
Аппаратные интеграции
Управляйте задачами с помощью Elgato Stream Deck и Stream Deck Mobile, Logitech MX Creative Console и Actions Ring, а также ENIAC Flexbar. Аппаратные функции доступны во всех версиях, кроме µGulp™ Free. Для JetBrains редакции Free нет.
µGulp™ выводит на клавишу не просто статичный значок. Live Animated Task States означают, что отображение следует за фактическим состоянием выполнения того же движка, что и в Dashboard (inactive → starting → running → finished или failed, а также disabled, waiting-for-input, stopping). Во время запуска, выполнения, остановки и ожидания ввода идёт анимация; успех и ошибка кратко показываются отдельно (ошибка: Burn → Charred). µWatch - отдельный переключаемый слой; расписания сеанса могут добавить на клавишу обратный отсчёт или n/m. (Actions Ring: только заголовки, SDK без анимации LCD.) Контракт и список состояний: TaskPresentationAndHardware.md.
Подключение к нужному рабочему пространству включается в Dashboard: Настройки → Hardware integrations. Плагин устройства связывает клавиши с задачами этого проекта. Выполняющиеся службы можно остановить, а на запросы ввода ответить в Dashboard.
Контекстные поверхности контроллеров
µGulp™ использует общий контекст активного проекта для Visual Studio Code, Cursor и JetBrains. Stream Deck восстанавливает последнюю страницу и группы для каждого workspace и устройства. Logitech сохраняет существующий динамический выбор workspace; его папка общая для процесса. Flexbar автоматически не следует за проектом IDE.
Активный проект общий, а представления Stream Deck хранятся по устройствам. Когда на переднем плане другое приложение, µGulp™ возвращает Stream Deck профиль браузера, который сам открыл. Появление обычного или Smart Profile зависит от Elgato и настроек пользователя; автоматическое переключение Smart Profiles не гарантируется.
Пример:
Cursor: microGulp
MX -> Build
Stream Deck -> Release
Alt-Tab
JetBrains: BlueShift
MX -> Build
Stream Deck -> Test
Alt-Tab
VS Code: ESP][
MX -> Upload
Stream Deck -> Monitor
Возврат в окно IDE восстанавливает прежнее представление Stream Deck для этого workspace. Представления устройств хранятся раздельно; физическая проверка нескольких Stream Decks ещё предстоит.
Если группа исчезла после изменения gulpfile, восстановление возвращается к ближайшему допустимому родителю или корню. Follow active IDE project включён по умолчанию. Ручной выбор workspace на клавиатуре Logitech имеет приоритет. Технические ограничения: Следование за активным проектом IDE.
Elgato Stream Deck и Stream Deck Mobile
Follow и профили: При включённом Follow active IDE project µGulp™ принимает проект окна IDE в фокусе с доступным аппаратным соединением и может открыть комплектный профиль браузера. Если браузер уже виден, меняется только содержимое. При уходе из контекста IDE профиль, открытый µGulp™, возвращается. Elgato Smart Profiles можно дополнительно настроить в Stream Deck; их активация со стороны µGulp™ не гарантируется. Подробности: Stream Deck.
Браузер групп: Open µGulp Group на другом профиле (например, Default) открывает браузер с динамическими группами и задачами. Эта команда открывает настроенную начальную группу. Follow и клавиша µGulp Group Slot, используемая для входа, восстанавливают сохранённое представление активного workspace; новый сеанс без сохранённого представления начинается в корне. Страницы, Назад и Root следуют сетке. Root показывает логотип без искажения пропорций и название в отдельной полосе; непригодный логотип заменяется. Назад в корне выходит из браузера. Stream Deck Mobile выбирает шаблон по размеру сетки, включая 3×2 и 5×3.
Фиксированное назначение отдельной задачи: по-прежнему можно перетащить µGulp Task на клавишу и выбрать рабочее пространство и задачу. Имена, анимированные состояния выполнения и значки берутся из подключённого рабочего пространства. В Stream Deck Mobile используется та же интеграция.
Технические сведения и список шаблонов: Stream Deck, контракт навигации по группам на устройствах.
Logitech: отдельные задачи или профиль приложения
Для Logitech доступны два способа настройки:
- Отдельно назначить задачи: с помощью Start a Single µGulp Task привяжите рабочее пространство и задачу к клавише. Это работает и для клавиш Keypad, и для Actions Ring (только заголовки, SDK без анимации LCD). Папка Keypad показывает значки и состояния выполнения.
- Настроить профиль приложения в Options+, например для Cursor: выбранная там раскладка автоматически включается, когда приложение получает фокус. На Keypad действие General µGulp Functions открывает задачи подходящего рабочего пространства со значками и индикаторами выполнения. Плагин µGulp™ следует за активным рабочим пространством IDE; ручной выбор сохраняется, пока вы не сбросите его или соединение не будет потеряно.
Итак, Options+ выбирает раскладку клавиш для приложения, а µGulp™ - рабочее пространство. Профиль настраивается в Options+ один раз. После переключения приложения динамическая папка может закрыться; нажмите клавишу µGulp™, чтобы открыть её снова. Actions Ring использует фиксированное назначение отдельной задачи; динамический список со значками задач предназначен для Keypad.
Logitech MX использует изображение проекта от подключённого хоста для выбора workspace и клавиши µGulp™, с фирменным изображением как резервным. Полная приёмка на устройстве ещё предстоит. Программное открытие Dynamic Folder и независимая навигация нескольких физических MX не гарантируются; вопросы SDK остаются открытыми. Существующая поддержка Logitech ограничена и экспериментальна.
ENIAC Flexbar
Плагин Flexbar связывает действия, настроенные в FlexDesigner, с задачами µGulp™ и их состояниями выполнения (та же семантика состояний, что у Stream Deck). Проверка на реальном устройстве Flexbar ещё не проведена.
Техническая настройка и сборки плагинов: Stream Deck, Logitech, Flexbar.
Планировщик задач (сеанс)
Расписание сеанса определяет только когда запускать задачу; выполнение идёт по обычному пути StartTask (сектор Dashboard, журналы и состояния устройств не меняются).
| Режим | Объявление | Кратко |
|---|---|---|
| Таймер | µSchedule = { after: '10s' } |
один запуск через заданное время |
| Интервал | { every: '10s' } |
повтор; nextRun обновляется после каждого запуска |
| Повторение | { every: '5s', repeat: 5 } |
после n запусков состояние completed |
| Cron | { cron: '*/1 * * * *' } |
5 полей, локальное время хоста (croner) |
Императивный API: ScheduleTask, SetScheduleEnabled, CancelSchedule, RunScheduleNow (gulp-mu-gulp-api). Dashboard: обратный отсчёт по nextRun, Enable/Disable/Cancel/Run now. Пока активен µWatch или выполняется задача, запланированный запуск пропускается (schedule-skipped). На аппаратных клавишах поверх состояния может отображаться обратный отсчёт или n/m. Подробности и демонстрации A-G: TaskScheduler.md.
Контроллеры, геймпады и джойстики
Геймпады, джойстики и другие совместимые устройства ввода можно использовать для управления рабочими процессами с настраиваемыми назначениями. Поддержка включается в Настройки → Controllers; параметры позволяют создавать профили, обучать кнопки и оси, задавать мёртвые зоны и чувствительность, а также запускать диагностику в реальном времени. Назначения могут запускать и останавливать задачи и управлять их списком.
В Windows x64 ввод распознаётся и тогда, когда Dashboard не в фокусе. Для этого требуется установленная Node.js версии 22 или новее. Для других настольных платформ встроенные компоненты контроллеров пока не входят в пакет; в поддерживаемых браузерах можно использовать Gamepad API.
Для 3Dconnexion SpaceMouse Wireless предусмотрен профиль, измеренный на устройстве: шесть осей и две кнопки. Другие устройства можно настроить с помощью калибровки и собственных назначений. Если контроллер поддерживает вибрацию, она может дополнительно сигнализировать, например, о запуске задачи, успехе или ошибке. Возможности зависят от конкретного устройства.
Настройка, профили устройств и диагностика: документация по контроллерам.
Миграция gulpfile с помощью ИИ
Чтобы мигрировать существующий большой gulpfile (консольный вывод, метаданные задач, словари i18x/gulp, опционально µKeyBinding / µParameters / µWatch / µAutoClose, плюс необязательная идентичность проекта в microgulp.config.json), используйте поддерживаемый промпт в репозитории:
| File | Purpose |
|---|---|
dev/prompts/OptimizeGulpfileForMicroGulp.md |
Промпт для Cursor, Claude, ChatGPT, … (первая миграция) |
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json |
Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version) |
dev/prompts/EnhanceExistingMicroGulpProject.md |
Проверить существующий проект µGulp™ на необязательные новые возможности (без слепого включения) |
Теперь запрос на адаптацию также учитывает µTaskKind, µPresentation, µExecutionType, µAttentionWatch и ожидание ввода и разумную идентичность project (название / краткое описание / существующий логотип; только слияние config). Существующие глифы µIcon и назначения µIconFont сохраняются. Ядро управляет состояниями выполнения; постоянные службы, файловые триггеры и внимание остаются раздельными механизмами. Аппаратные интеграции включаются отдельно для каждого рабочего пространства и доступны во всех редакциях, кроме µGulp™ Free; проверка Flexbar на реальном устройстве ещё не проведена. Перед миграцией сверяй требуемые версии продукта и API с текущим состоянием проекта.
Промпт также требует форматировать значения средствами i18x: int для счётчиков, floatFix1/floatFix2 для десятичных чисел, byteSize для байтов, progressDuration для миллисекунд и форматы дат и времени. Для структурированного вывода предусмотрен FormatValue(). Словари проекта обновляются вместе с соответствующими определениями <format>; существующие переводы сохраняются. Ограничения предварительной версии собственного движка учитываются.
Для группировки и дерева задач промпт учитывает µGroup, µOrder, µGroups, а также SetGroupState, RevealTask и SetTaskEmphasis. В подсказках по устройствам описаны браузер групп Stream Deck (клавиша входа и динамические шаблоны слотов), а также фиксированные задачи Logitech, включая Actions Ring и профили Options+ для приложений с выбором рабочего пространства через µGulp™.
Workflow
- Скопируй пример параметров в корень проекта как
microgulp-optimize.params.jsonи заполни его:projectRoot,gulpfilePath,supportedLanguages(например,en-US,de-DE,zh-CN),gulpMuGulpApiVersion(локальная эталонная версия^0.6.0; проверь установленную/опубликованную версию),microGulpMinVersion(1.0.0), а такжеgithubRepoUrl/githubRef(по умолчаниюhttps://github.com/mamekudz/microGulp, проверенный ref, напримерmain). - Откройте markdown промпта, замените таблицу
{{PLACEHOLDER}}своими значениями (или приложите файл params и gulpfile в Cursor). - Пусть ИИ выполнит миграцию. Шаг 0 в промпте обязателен: датированная резервная копия gulpfile (напр.
gulpfile.mjs.20260703-142559.bak) до любой правки. - Проверьте
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) |
Группа Scheduler demos (A-G) показывает расписания сеанса (µSchedule): однократный таймер, интервал, повторение, Cron, пропуск перекрытия, запланированную ошибку и Watch+Schedule. Все демонстрационные расписания изначально отключены (autoStart: false); включайте каждое отдельно кнопкой со значком. Подробности и API: dev/docs/TaskScheduler.md.
Дальнейшие детали API: gulp-mu-gulp-api/README.md.
µGulp™ Ready
Проект предоставляет хотя бы одно полезное взаимодействие или вывод для µGulp, документирует обычный запуск через Gulp/CLI и самостоятельно проверяет оба варианта. Одной совместимости с 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 с демонстрационными и сборочными задачами (прогресс, формы, структурированные журналы, звук, модальные окна, а также обратный отсчёт, собственные значки, отображение ошибок, постоянная служба и Attention/Reset) в ~/.microgulp/sample. Затем откройте µGulp: Open Dashboard. Руководство пользователя доступно через Настройки → Handbook (или µGulp: Open Handbook); там можно открыть все языковые версии.
PDF-руководства: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어
Лицензия
µGulp™ (расширение, движок, панель, адаптер JetBrains) - проприетарное ПО - см. LICENSE. Распространяемые двоичные файлы можно использовать бесплатно; копирование, изменение или распространение исходного кода не разрешено.
Сопутствующий npm-пакет gulp-mu-gulp-api остаётся под лицензией MIT, чтобы задачи Gulp могли принимать его без ограничений.
Дорожная карта / открытые пункты черновика
Уже реализовано
[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] Идентичность проекта (
project.title/description/logoвmicrogulp.config.json; компактный заголовок в списке задач)[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для ИИ-перевода)[x] Единые состояния задач, 38 семантических значков, индикатор ввода, запасной вариант темы и уменьшение движения
[x] Дерево задач и выделение через
SetGroupState,RevealTaskиSetTaskEmphasis[x] Восемь функций IDE API и видимые индикаторы хоста/доступности
[x] Web Console, KnownProjectRegistry / Project Center, Open/Focus Project и общий Background Host
[x] Stream Deck: Follow, последнее представление по workspace и устройству, логотипы проектов на Root
[x] Интеграция Stream Deck / Mobile, Logitech и Flexbar; у Logitech - назначение отдельных задач и динамическая папка Keypad
[x] Профили контроллеров с калибровкой и диагностикой; ввод на настольном компьютере в Windows x64 и профиль SpaceMouse Wireless
Ещё открыто
[ ]
Ide.OpenUrlи выполнение задач без IDE через Background Host: запланированы, не входят в реализованный объём 1.0.0[ ] Logitech MX: физическая приёмка, включая изображение проекта, и открытые вопросы SDK по Dynamic Folder и нескольким устройствам
[ ] Stream Deck: физическая проверка нескольких устройств и взаимодействие с Elgato Smart Profiles
[ ] Flexbar: проверка на реальном устройстве
[ ] Встроенные компоненты контроллеров для Linux и macOS
[ ] Документировать
µLib(microLib), затем принять как слой утилит в µGulp (i18x сегодня - локальное webview-подмножество)[ ] Прямое подключение i18xe-server: живая синхронизация перевода вместо встроенных словарей
[ ] Расширить
GUI.mjsизµLibдополнительными специальными элементами для форм панели[ ] Визуальная доводка webview-панели
[ ] Расширить скин µCSS: добавить шрифт символов и спрайты в манифест
[ ] Речевой вывод через i18xe (сэмплы атласа уже заменяют WebAudio-пищи, когда есть)
[x] Плагин JetBrains: Settings → Tools → µGulp (параметры движка)
[x] Карточка JetBrains Marketplace (плагин 34255; наличие в реестре - не проверенная свежая установка в каждой IDE)
[x] Карточки VS Code/Cursor в Microsoft Marketplace и Open VSX (с регистрацией и Free)
Web Console и Project Center
Локальная Web Console объединяет известные и подключённые проекты в Project Center. Она встраивает существующую панель с задачами, Project Controls, параметрами, историей и событиями в реальном времени; вторую TaskEngine не создаёт. Открытие: µGulp: Open Web Console в VS Code/Cursor, Open Web Console в окне инструментов JetBrains или npm run console -- open в рабочей копии разработчика. Console использует локальный HTTP/SSE без плагина браузера и слушает только 127.0.0.1; это не доступ по LAN или удалённой сети.
Известные проекты и сеансы
KnownProjectRegistry сохраняет путь, ProjectId, название, описание, логотип, предпочитаемую IDE и время последнего контакта в ~/.microgulp/known-projects.json. Метаданные берутся из microgulp.config.json. Обзор различает подключён, закрыт и недоступен. Известная запись не является работающим движком. Живые сеансы IDE учитываются отдельно; несколько окон одного проекта выбираются по отдельности.
Follow active IDE project следует общему активному контексту. Ручной выбор закрепляет сеанс только в данной вкладке и не меняет закрепление контроллера. При другом приложении на переднем плане последний отображённый сеанс остаётся видимым, пока он жив.
Обзор и встроенная панель доступны в µGulp™ Free; действуют обычные разрешения задач. Управление хостом также доступно. Для Open/Focus Project, Start Application, действий IDE и выбора предпочитаемой IDE сервер при каждом вызове проверяет разрешение редакции и регистрации. При его отсутствии возвращается unsupported-edition или unsupported-registration.
Открытие и активация проектов
Open/Focus Project использует выбранное семейство IDE, конкретный продукт и установку. При совпадающем сеансе активируется его окно. Неоднозначность требует выбора сеанса. Ошибка фокуса не запускает вторую IDE; точная активация окна пока специфична для Windows. Без подходящего сеанса известный проект открывается в выбранной установке. Параллельные запросы объединяются; без подтверждения старта нужна явная повторная попытка. Медленный запуск проекта поэтому может временно отображаться неподтверждённым.
Обнаруживаются известные пользовательские установки Windows. Другие IDE и приложения задаются в ~/.microgulp/applications.json абсолютным путём к исполняемому файлу и необязательными фиксированными аргументами; для JetBrains нужен конкретный продукт. Start Application запускает известное приложение без shell-команды. Общая активация произвольных сторонних приложений не входит в объём. Обнаружение Windsurf экспериментально, это не одобрение ещё одной IDE.
Background Host
Общий Background Host предоставляет Web Console, известные проекты, активный проект и контекст контроллеров - один процесс на пользователя, независимо от IDE. Первая IDE запускает его по необходимости; закрытие IDE его не завершает. Необязательный старт при входе обеспечивает Console на http://127.0.0.1:47821/console без открытой IDE. Без IDE он показывает известные проекты; при разрешённой редакции их можно открыть в Cursor, VS Code или JetBrains. Задачи управляются через подключённый сеанс IDE. Выполнение без IDE и автоматическая передача владения движком не входят в 1.0.0.
Настройки общие для всех IDE и хранятся только в host-settings.json: Start at login и Show background UI независимы. Скрытие интерфейса не останавливает хост. Порт общий (47821 по умолчанию, допустимо от 1024 до 65535). Изменение перезапускает работающий хост; Console переходит на новый адрес. Если требуемый порт занят другим приложением, сохраняется прежний. Случайного порта и поля адреса привязки нет: только 127.0.0.1.
При первом запуске µGulp™ спрашивает один раз на пользователя, не на IDE: Enable µGulp Background Host? Enable включает старт при входе. Not now оставляет его выключенным; IDE по-прежнему может запустить хост по необходимости.
Одинаковое управление доступно в VS Code и Cursor (µGulp: Background Host Settings), JetBrains (Settings → Tools → µGulp Background Host и Background Host в окне инструментов), разделе Background Host в Console и через npm run console -- status|open|restart|stop|port <n>|autostart on|off|ui on|off. Меню Windows в области уведомлений открывает Console, показывает состояние, подключённые IDE и известные проекты и переключает старт при входе. Порт там не меняется. Stop завершает только хост; IDE может позднее запустить его снова.
| Платформа | Автозапуск | Системный интерфейс |
|---|---|---|
| Windows | Запись входа пользователя | Область уведомлений (необязательна; работа без интерфейса допустима) |
| macOS | LaunchAgent | Строка меню подготовлена, на оборудовании macOS ещё не проверена |
| Linux | Автозапуск XDG | Без интерфейса; зависимости от трея нет |
Тексты Console пока доступны на немецком и английском; другие языки используют английский. Управление хостом имеет собственные локализованные тексты. Полный реализованный API описан в разделе Действия IDE из задач.
日本語
Rock your Gulp!
µGulp™はGulpに、VS Code、Cursor、JetBrains IDE向けの対話型dashboardを追加します。 タスクには動的な表示名、分かりやすいグループ、アイコン、説明、ツールチップが付きます。どのプロジェクトと対象の処理か、実行中か、成功したかを確認できます。フォーム、進捗、個別のライブ出力が実行を支えます。通常のGulp CLIも使え、必要なパッケージと適切な入力値は引き続き必要です。AIとMCPは任意です。
始め方: IDE用拡張を入れ、gulpfileがあるプロジェクトを開き、µGulp™のタスクを実行します。Node.js 22以降とプロジェクトの必要パッケージを用意します。Gulpは反復作業用JavaScriptツールで、gulpfileがタスクを記述します。µGulp™は操作画面を追加します。
主な機能
2026 年 10 月 20 日時点の 2.1.0: ローカルで検証中で、まだ公開されていません。グローバルタスク、改善された導入手順、プロジェクトタスクの表示設定は実装済みです。従来の受け入れ結果は各バージョンに対応し、一部のテストの成功は全面的な承認を意味しません。検証済みの処理と制限は下記を参照してください。
- 2.1.0 の新機能: プロジェクトのタスク表示を分かりやすく整える - 編集言語を選び、既存の IDE エージェントに不足している英語ソーステキストと翻訳を提案させ、記号や独自の画像をその場で確認できます。Gulpfile は en-US のままで、翻訳は
i18x/gulp/<sprache>.jsonに保存します。プレビュー、バックアップ、取り消しは両方のファイルに適用されます。 - 動的なタスク名、グループ、アイコン、ツールチップ - 単なる関数名ではなく理解しやすい表示名、現在の版や対象、入れ子で折りたためるグループ、独自のアイコン/説明/ヒントを使えます。
µDisplayName、µGroup、µIcon、µDescription、µTooltipで一覧をプロジェクトに合わせます。テキストは翻訳でき、µOrderが並び順、µGroupsが初期状態を定めます。 - TaskのPreload - ウォームNodeワーカーはGulpfileをあらかじめ読み込むため、準備済みのワーカーが使える場合は起動時間を短縮できます。重いモジュール読み込みやリアルタイムのウイルススキャンがある環境で特に役立ちます。
- Taskの状態をひと目で確認 - 開始、実行中、入力待ち、停止、成功、エラーを統一して表示します。独自アイコンを使っている場合も状態の枠線が表示されます。
- 並列タスクグリッド - 隔離された実行セクタを横並びにし、それぞれ独自のログストリーム
- Web ダッシュボード - ライブ ANSI 色付きログ、フィルタ出力、確定進捗バー、ユーザー入力用の豊富なフォーム（テキスト、色、フォント、select、multiselect、…）
- 🔴 2.1.0 の新機能: 既存の Gulpfile に合った導入手順 - 調整済みのタスクを認識し、不足している表示情報だけを補い、各変更を事前に確認できます。追加のAIレシピは任意です。キーボードショートカットの不足はヒントとして扱います。
- 🔴 2.1.0 の新機能: 共通のタスクで複数のプロジェクトを操作 -
NASBUなどの共通 ID を使い、NAS バックアップやプロジェクトの検査を開始できます。タイトルとアイコンで対象プロジェクトを選び、各プロジェクトの設定を事前に保存し、一括開始の前に確認します。実装、出力、履歴はプロジェクトごとに独立しています。 - 🔴 2.0.0の新機能: アシスタントとAIレシピ - フォームでメタデータを追加し、NAS/microCSSを統合して初期設定やGitHub/npm公開を準備します。全変更を確認してから保存付きで適用し、その後未変更なら取り消せます。準備タスク自身は公開しません。
- 🔴 2.0.0の新機能: プロジェクト分類と版準備 - プロジェクト名/Info、Build、Tools、Maintenanceに整理し、npm版更新と既存ロックファイルを確認してまとめて適用します。
- 🔴 2.0.0の新機能: 既存AIエージェントの接続 - Cursor/IntelliJのMCPで設定と保守を行い、既定では別のµGulp™ APIキーは不要です。Cursorではチャット内のグラフィカルアプリも使えます。
- 🔴 2.0.0の新機能: 必要箇所だけ翻訳を保守 - フラットJSON辞書の不足項目と比較ソースから変更と判定した項目だけを提案させ、プレースホルダーを確認し、保存/取り消し付きで適用します。ソースと対象言語は自分で選びます。
- 🔴 2.0.0の新機能: マニュアル保守を支援 - コード変更後、DOCXの修正候補を根拠付きで示します。文書、言語、規則を選び、編集自体は利用者が行います。
- 既存プロファイルの継続と再接続 - 1.0.0は引き続き使え、IntelliJエンジン終了後に再接続できます。新セッションと新提案を確認し、タスクは自動再実行しません。
- Web Console と Project Center - 名前、説明、ロゴ、セッション状態を持つ既知のプロジェクトをローカルのプロジェクトセンターに表示。既存ダッシュボードをブラウザーで開き、アクティブな IDE プロジェクトを追跡するか、このタブだけでセッションを固定できます。(一覧とホスト管理は Free でも利用可能)
- Open/Focus Project - 指定した IDE インストールで既知のプロジェクトを開くか、既存のウィンドウを前面にします。複数のセッションがあれば明示的に選択します。(Free では利用不可。正確なウィンドウフォーカスは現在 Windows のみ)
- Background Host - ユーザーごとに一つのプロセスで Web Console とアクティブなプロジェクトのコンテキストを共有。任意のログイン時起動と共通設定を提供し、IDE を開いていなくても利用できます。ホスト自体はプロジェクトエンジンを起動しません。
- プロジェクト識別 - タスク一覧の直上に任意のプロジェクトタイトル、短い説明、ロゴ。複数プロジェクトや IDE ウィンドウを開いているときに特に有用（
microgulp.config.json→project） - Project Controls - プロジェクト識別情報の下に選択、ラジオ、チェックボックスを配置し、ターゲットなどのプロジェクト全体の状態を設定。表示名、タスク／グループの表示、実行に即座に反映し、値は workspace ごとに
.microgulp/project-controls.jsonに保存します。 - Live Animated Task States - 対応ハードウェア（Stream Deck、Logitechキーパッド、Flexbar）は、静的なアイコンだけでなく、ダッシュボードと同じエンジンが示す実際の実行状態も表示します。開始、実行アニメーション、入力待ち、停止、成功、エラー（Burn/Charredを含む）、無効状態を表示し、Watch切り替えやスケジューラーのカウントダウンも追加オーバーレイで表示します。アニメーションは装飾ではなく状態を伝えるものです。(µGulp™ Freeには含まれません。Flexbarは実機テスト待ち。Actions Ringはタイトルのみで、SDKはLCDアニメーション非対応。)
- 意味に基づくTaskアイコン38種 -
µTaskKind/µPresentationに対応するSVGモチーフ、実行アニメーション、入力待ち時の紫色のダイアログ記号、テーマによる上書き、動きを抑える設定に対応します。エラーが発生すると元のモチーフが焦げた表示になります。 - Taskスケジューラー（セッション） -
µSchedule/ScheduleTaskでタイマー（after）、間隔（every）、繰り返し（repeat）、Cron（5フィールド、ローカル時刻）を設定できます。ダッシュボードのカウントダウン、Enable/Disable/Cancel/Run nowに対応し、ハードウェアキーにはカウントダウンまたはn/mが表示されます。実行には通常のStartTask経路を使います。 - 常駐サービスを必要に応じて制御 -
µExecutionTypeで単発Taskと常駐プロセスを区別し、実行中のサービスを停止できます。 - GulpfileからTaskツリーを操作 -
SetGroupState、RevealTask、SetTaskEmphasisでグループを開き、次の作業を表示し、強調表示を設定または解除できます。 - ライブ gulpfile 監視 - ワークスペースウォッチャーが保存時に再スキャンし、古いワーカーを自動入替
- Gulp CLIを継続利用 - メタデータはエクスポート名を変えません。importしたAPIパッケージは必要で、入力にはCLI値または適切な既定値、IDE操作には対応ホストが必要です(詳細)。
- 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（設定：自動または固定ロケール）。追加のダウンロード・インストール可能な画面パッケージは 2.2.0 で予定されています。ユーザーハンドブックは同梱された各ダッシュボード言語の PDF で提供します。
- gulpfile 用辞書同期 - Settings → Project i18x (gulp) が i18xe-sync パーサーでソースをスキャンし、選んだ言語の
i18x/gulp/<lid>.jsonを書き、既存翻訳を保ち標準フォーマットをマージ。<lid>.status.jsonサイドカーがローカル AI がまだ訳すべき項目を列挙 - 宣言的タスクパラメータ -
µParametersは実行前に一度尋ね、値をMICROGULP_PARAMS/GetParameters()で渡し、前回の回答を記憶し、パスワードをログから外し、visibleWhenでフィールドを隠せます - ウォッチ / トリガータスク -
µWatchグロブがファイル変更でタスクを実行。デバウンス、合体、暴走ブレーカー付き。ダッシュボードからタスクごとに武装 - ハードウェア対応 - Elgato Stream Deck、Logitech MX Creative Console / Actions Ring、Flexbar、ゲームパッドを利用できるようになりました。Gulpの操作が新たな段階に進みます。µGulp™ Freeを除くすべてのバージョンに含まれます（設定とデバイスの状況）。
- LogitechがWorkspaceに追従 - Taskを個別に固定するか、アプリ用のOptions+プロファイルを使えます。プラグインは動的なキーパッドフォルダーに、フォーカス中のIDEウィンドウのWorkspaceを表示します。
- Stream Deck が workspace を追跡 - Follow はアクティブな IDE ウィンドウのプロジェクトを採用し、workspace とデバイスごとに最後の表示を記憶して Root キーにロゴと名前を表示します。戻るとグループパスとページを復元します。(実機での複数デバイス検証は未完了。Elgato Smart Profiles は保証しません。Logitech は従来の限定的な機能範囲を維持し、Flexbar は自動追跡しません。)
- ワークフロー操作用コントローラー - ゲームパッドとジョイスティックに、専用プロファイル、入力学習、デッドゾーン、診断機能を用意しています。Windows x64ではダッシュボードにフォーカスがなくても利用でき、実測したSpaceMouse Wirelessプロファイルと、対応デバイス向けのオプション振動も含まれます。
- 8 個の IDE API 関数 - 機能と既知のプロジェクトを照会し、意味ベースまたはネイティブの IDE 操作、プロジェクトの起動／フォーカス、設定済みアプリの起動を実行。
µHost/µIdeApiはタスクの利用可否を示します。実行系関数は Free では利用不可。Ide.Capabilities()はホスト機能を返します（API 範囲）。 - タスクショートカット - プラットフォーム別バリアント付き
µ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） - ネイティブのファイル・フォルダー選択 - フォームのファイル欄からVS Code/CursorまたはJetBrainsの選択ダイアログを開き、実際のパスを取得できます。
- モーダルダイアログ - ダッシュボード内の 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 - Taskを開始しない注意表示 -
µAttentionが対応の必要な状態を示し、µAttentionWatchがファイル変更または一定間隔で状態を更新します。ツールチップ、インストール済みバージョン、折りたたまれたグループでも見える注意表示に対応します。 - Windows管理者権限への昇格 - TaskごとにUACダイアログを表示できます（
µRequiresElevation、µElevationReason）。IDEを通常権限で起動したまま、一部のTask（例:hostsファイルの変更）だけを昇格して実行できます。(µGulp™ Freeには含まれません。) - 診断エンジン - モジュール読み込みエラーやスタックトレースを、ダッシュボード上の具体的な解決案に変換します。(µGulp™ 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 モジュール
希望する言語でプロジェクトのタスク表示を整える
「プロジェクトのタスクを設定」は、選択したプロジェクトの Gulpfile にある既存タスクの表示を整えます。プロジェクトをまたぐグローバルタスクは別に管理され、このアシスタントでは変更されません。
編集言語は、提案する表示名、説明、ツールチップ、グループに適用されます。選択欄は i18xe プロジェクトで一元管理される言語コードと各言語の名称を使用し、ほかの有効な BCP 47 言語コードも入力できます。初期値は package.json の microgulp.editingLanguage から取得します。この指定がなければ、フォームは IDE の Web ビューのブラウザー言語を使用します。画面の言語とは独立しており、依頼のたびに編集言語を変更できます。
「IDE エージェントでテキスト提案を準備」は、不足するテキストフィールドに限定した依頼を作成します。Gulpfile には常に英語 en-US のソーステキストを保存し、別の編集言語を選んだ場合は、アシスタントが対応する翻訳を i18x/gulp/<sprache>.json に追加します。既存の翻訳は上書きしません。ダッシュボードでは、表示された依頼を接続済みの Cursor または IntelliJ のエージェントチャットにコピーします。グラフィカル MCP アプリでは、クライアントがメッセージに対応している場合に「IDE エージェントに送信」を使用できます。既存のエージェントがテキストを生成し、MCP 経由で返します。追加の API キーは不要です。アシスタントはバックグラウンドでエージェントを開始せず、有料の代替サービスも使用しません。
「提案をフォームに読み込む」で、検査された提案を表示します。既存のメタデータ、翻訳キー、計算された値、処理中に手動編集したフィールドは保持されます。依頼の有効期間は 10 分で、Gulpfile または辞書が変更されると拒否されます。プレビューには両方のファイルが一緒に表示されます。バックアップ付きの適用を明示的に行ったときだけ Gulpfile と辞書に書き込み、取り消すと以前の状態に戻ります。言語と内容の妥当性はユーザーが確認する必要があります。
同梱された 8 つの µGulp™ 画面言語は、これとは別です。µGulp™ の画面用に追加でダウンロードまたはインストールできる翻訳パッケージはバージョン 2.2.0 で予定されており、このアシスタントにはまだ含まれません。
アイコンには記号や絵文字を入力するか、64 KiB 以下の PNG、JPEG、WebP 画像を選択します。選択内容はその場でプレビューされます。画像は Gulpfile に埋め込まれるため、元のファイルパスには依存しません。新しい SVG ファイルや画像 URL はここではインポートしません。既存のアイコンメタデータを変更せずに適用した場合、その情報は保持されます。
既存の Gulpfile を必要な箇所だけ改善する
セットアップアシスタントはまず静的解析だけで、タスクに µGulp™ の表示メタデータがすでにあるかを確認します。表示名、説明、グループ、アイコン、ツールチップのいずれかがあれば、表示が調整済みであることを認識できます。これは Gulpfile 全体の品質評価ではありません。すべてのタスクにすべての項目が必要なわけではありません。
認識されたすべてのタスクが調整済みの場合、自動的な最適化の案内は表示されません。一部だけ調整済みの Gulpfile では、そのような情報がないタスクだけをダイアログが提案します。まず名前、説明、グループ、アイコン、ツールチップを補い、変更プレビューを確認して、明示的にバックアップ付きで適用できます。取り消しも引き続き利用可能です。その後、またはこの手順を意図的にスキップして、ほかのAIレシピへ進めます。
計算またはインポートされたメタデータは、常に明確に評価できるとは限りません。その場合、アシスタントは最適化の状態を不明とし、値を自動変更しません。キーボードショートカットは任意のヒントにすぎず、ないことを最適化の必要性とはみなしません。グローバルタスクへの割り当てがないことも問題ではありません。2 番目の手順では、追加AIレシピとショートカットは初期状態で選択されていません。
選択したプロジェクトのグローバルタスク
グローバルタスクを使えば、同じ作業をプロジェクトごとに探して個別に開始する必要がなくなります。共通の ID が各プロジェクトの対応する実装を結び付けます。たとえば NASBU はプロジェクトごとに異なるフォルダーをバックアップできます。Web Console は対象となるプロジェクトをタイトルとアイコン付きで表示し、その中から実行するものを明示的に選択できます。
グローバル定義は、固定の ID と分かりやすいタイトルで構成されます。実行可能な実装は各プロジェクトの Gulpfile に残ります。共通のソースコードを配布したり、別のプロジェクトにタスクを自動コピーしたりするものではありません。同じ ID を、プロジェクトごとの要件に合うように実装できます。
エクスポートされたタスクに µGlobalTask = { id: "NASBU", title: "NAS-Sicherung" } を追加します。ID は大文字で始まり、大文字、数字、アンダースコア、ハイフンを合計 64 文字まで使用できます。1 つのプロジェクトで同じ ID を提供できるのは 1 回だけです。指定したタスクはプロジェクトのダッシュボードの専用グループ「グローバルタスク」に表示されます。これらのタスクでは、既存の µGroup はこのグループに置き換わります。
Web Console を開き、「グローバルタスク」を展開します。一覧を更新して共通のタスクを選びます。「プロジェクトを設定」で、µParameters の値を各プロジェクトに一度保存します。値はローカルの .microgulp/global-tasks.json に保存されます。パラメーター定義が変更された場合は再設定が必要です。パスワードや remember: false を指定した値はここには保存されません。そのようなタスクは、引き続きプロジェクト内で対話的に操作する必要があります。
「グローバルタスクを定義」で ID とタイトルを一元的に指定できます。一覧には、接続中のプロジェクトから検出された ID も表示されます。共通のタイトルは表示を統一するだけで、実行可能な実装を作成するものではありません。定義はユーザーディレクトリ内の .microgulp/global-tasks.json に保存されます。
タイトルとアイコンでプロジェクトを選択します。同じプロジェクトの IDE ウィンドウが複数ある場合は、セッションを 1 つだけ選びます。「選択内容を確認」には、選択したプロジェクトと保存済みの値だけが表示されます。「選択したタスクを開始」を押して初めて、各 IDE に実行が渡されます。閉じているプロジェクトや IDE が自動的に開くことはありません。
一括開始では、入力フォームを再表示せずに保存済みのパラメーターを使用します。それでもタスクが µGulp ダイアログを要求した場合、その実行は global-task-dialog-required で失敗します。Windows の昇格した権限が必要なタスクや常駐タスクは、グローバルでは開始されません。Gulp コードは引き続きローカルのプログラムコードです。独自のダイアログを持つ外部プログラムが、これによって無人実行できるタスクになるわけではありません。
プレビューの有効期間は短く、1 回だけ使用できます。Gulpfile、タスク定義、保存済みパラメーター、Project Controls の変更によって無効になります。IDE セッションが終了したり変わったりした場合は、選択と確認をやり直す必要があります。最初の開始前に、選択されたすべてのセッションを検査します。
一括開始はトランザクションではありません。最初の開始後に接続が切れると、それ以前のプロジェクトはすでに実行中の可能性があります。結果には、開始済み、失敗、未開始のプロジェクトが表示されます。自動再試行も、実行済みタスクの自動取り消しもありません。進捗、ログ、停止操作は、各プロジェクトのダッシュボードで利用できます。
別のプロジェクトのタスクを指定して開始する
プロジェクト A のタスクは、gulp-mu-gulp-api の RunGlobalTask を使い、プロジェクト B の µGlobalTask で指定された実装を開始して完了を待つことができます。正確なプロジェクト ID とグローバルタスク ID を渡してください。対象のパラメーターは、あらかじめプロジェクト B のダッシュボードで設定しておく必要があります。プロジェクト B には、µGulp ダッシュボードを開いたアクティブな接続が必要です。対象プロジェクトで複数のセッションが開いている場合は、目的のセッションの sessionId も指定します。閉じているプロジェクトや IDE は自動的には開きません。
import { RunGlobalTask } from 'gulp-mu-gulp-api';
const result = await RunGlobalTask({
projectId: 'Projekt-ID-von-B',
globalId: 'DEPLOY',
timeoutMs: 120000
});
if (!result.ok) throw new Error(result.error ?? result.code);
console.log(result.taskResult);
応答には状態、実行 ID、所要時間が含まれます。taskResult は、対象タスクが ReportTaskResult を呼んだ場合だけ含まれます。呼び出しは接続中の IDE セッションを通して対象タスクを開始し、表示用の Web Console ウィンドウは開きません。自己呼び出しと再帰的なプロジェクトの連鎖は拒否されます。時間制限は 1 秒から 300 秒で、未指定なら 120 秒です。タイムアウトが起きた場合でも、対象タスクがすでに開始している可能性があります。
グローバル呼び出しには、µGulp ダッシュボードが開かれた、稼働中かつ信頼された IDE セッションと、IDE API にアクセスできるエディションが必要です。プロジェクト一覧と従来の簡単なタスク操作はそのまま利用できます。Background Host で閉じたプロジェクトを単独実行する機能、グローバルなハードウェアキー、グローバルな MCP ツールは、この 2.1.0 の範囲には含まれません。
エディションと機能範囲
µ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エディションは、最初のTaskを実行する前に登録が必要です。登録しない場合は拡張機能をアンインストールしてµGulp™ Freeを利用してください。JetBrainsではµGulp™の登録は不要で、JetBrains向けFree版はありません。
| µGulp™ VS Code / Cursor |
µGulp™ Free VS Code / Cursor |
µGulp™ JetBrains IDEs |
|
|---|---|---|---|
| 価格（月 / 年） | 0 € / $0 | 0 € / $0 | 0 € / $0 |
Taskダッシュボード、Preload、i18x、パラメーター、µWatch、µSchedule、履歴 |
はい | はい | はい |
| ライセンス / 登録 | 必須 | なし | なし |
| スキン（Neon Carbon、Ice Light、IDE Dark / Light、Automatic） | あり | IDE テーマに従う IDE Dark / Light（選択不可） | あり |
| カスタムテーマ ZIP パック | あり | - | あり |
| 診断エンジン | あり | - | あり |
| Windows UAC 昇格 | あり | - | あり |
| ハードウェア連携（Stream Deck、Logitech、Flexbar） | はい | - | はい |
| TaskからのIDEアクション | はい | - | はい |
| Web Console：プロジェクト一覧、セッション状態、埋め込みダッシュボード | あり | あり。通常のタスク権限を適用 | あり |
| Background Host とホスト管理 | あり | あり | あり |
| Open/Focus Project、Start Application、IDE 操作、優先 IDE | あり | - | あり |
| ホスト設定 | microgulp.* |
microgulp.* |
Settings → Tools → µGulp |
| Marketplace | VS Code にインストール · Open VSX からインストール | µGulp Free をインストール · Open VSX からインストール | JetBrains にインストール (de.amekudzi.microgulp) |
現在、すべてのエディションを無料（月額0 € / $0、年額0 € / $0）で利用できます。以下の項目は製品全体の機能です。Free版はIDE/OSのテーマに従い、IDE Dark / IDE Lightのみを使います（Appearance選択機能なし）。テーマパック、診断、権限昇格、ハードウェア連携、IDEアクションは含まれません。 ローカル Web Console は Free でも利用できます。プロジェクト一覧、状態、ホスト管理は使用できますが、拡張操作（Open/Focus Project、Start Application、IDE 操作、優先 IDE）は他のエディション専用です。
2.0.0の新機能
セットアップアシスタントは既存プロジェクトにAIレシピを追加し、適用前にすべてのファイル変更を表示します。IDEエージェントへの任意のMCP接続、翻訳とマニュアル保守の支援も追加されました。日常の操作は、プロジェクトを開き、タスクを選んで実行するだけです。
汎用AIワークフロー生成、任意のタスクの意味に基づく最適化、進化的な自己最適化は未実装の構想で、範囲や時期は約束されていません。
1.1.0から利用可能
任意のフォーム情報を入力欄の前に表示できます。タスクはキャンセルと保存可能な選択値の記憶を明示的に有効化できます。µI18xContext.GetValues() はスキャンごとに同期的なメタデータを提供し、プレースホルダーの変更はタスク一覧にも反映されます。既存の gulpfile と成功時のフォーム応答は互換性を維持します。新機能は gulp-mu-gulp-api 0.7.0 に記載されています。
セットアップアシスタントとAIレシピ
プロジェクトのタスクを設定から、既存gulpfile用のアシスタントを開きます。ESM/CommonJSを静的に解析し、適切な設定項目を提示し、適用前に変更を表示します。9つのAIレシピは表示名と説明、自由なグループとプロジェクト別グループ、ショートカット、NASバックアップ、microCSS、初期設定、GitHub/npmの準備を扱います。
- NASバックアップ: プロジェクト識別子、ソース、複数の保存先、方式、ディレクトリまたはZIP、コピー方法、除外。既定はドライランです。保存先識別子を表示し、明示的に準備します。設定自体はNASにアクセスしません。
- microCSS: 既存の信頼できるマニフェスト、ソースと出力フォルダー、圧縮、画像プレビュー。ビルドごとに新しい出力サブフォルダーを使います。
- 安全な適用: 全ファイルのプレビュー、ソースハッシュ検証、既存AIレシピファイルの保護、
.microgulp/setup-backupsへの保存、同一セッションで直近の未変更の適用を取り消す機能。
必要な依存関係はプレビューに表示され、その後各AIレシピフォルダーでnpm installします。新しい3種類の準備機能には追加のAIレシピパッケージは不要です。microCSSマニフェストのimport先はソースプロジェクトにも必要です。実行中のタスクやスキャンは変更をブロックします。動的なgulpfile構造には手動調整が必要な場合があります。
初期設定と公開を準備する
初期設定、GitHub公開、npm公開のAIレシピは既存gulpfileに準備タスクを追加します。それぞれプロジェクト名と設定のフォームがあります。タスクは確認手順とコマンドを表示しますが、依存関係のインストール、push、公開は行いません。アシスタントでの適用も公開許可ではありません。
- 初期設定 (
project-bootstrap): パッケージファイル、Git状態、除外、依存関係、既存ビルド/テストスクリプトを確認します。新規プロジェクトでは先に空のgulpfile.mjsを作成して選択します。不足するパッケージファイルは準備手順として示し、黙って作りません。 - GitHub (
github-release):Eigentümer/Repositoryと公開範囲を選択します。ログイン、remoteとファイルの確認、不足リポジトリの明示的作成、確認済みコミットのpush、確認済みタグによるリリース下書きを計画します。リポジトリ作成、push、公開は個別に明示的な指示が必要です。 - npm (
npm-release): patch/minor/major、レジストリ、アクセス、チャネルを選択します。バージョン更新をファイルプレビューに含めると、package.jsonと既存のpackage-lock.json/npm-shrinkwrap.jsonに新しい版を表示します。適用時はgulpfileと一緒に保存して変更し、取り消しでバイト単位に復元します。未選択ならバージョン更新は未実施の手順として残ります。
自動更新は1.2.3などの安定版を扱います。プレリリースやworkspaceのパッケージ集合にはプロジェクト固有の手順が必要です。非公開パッケージ、矛盾するロックファイル、異なる公開設定は自動変更をブロックします。RELEASES.jsonがある場合は自動更新を外し、プロジェクトのバージョン同期を使います。独自の他のバージョンソースも固有の手順で管理します。設定で更新済みの版を準備タスク起動時に再度上げることはありません。
プレビューとタスク起動はレジストリに問い合わせません。npm計画は実際の公開前に、レジストリ確認、テスト、ビルド、パッケージ内容確認、ログインを要求します。ローカル更新はその版がレジストリで空いている証明ではありません。公開済みパッケージを同じ版で再公開することはできません。npm公開 · npmバージョン管理 · GitHubリリース下書き
プロジェクト別にタスクを整理する
3つのAIレシピは各4つの準備タスクをプロジェクト名/Info、プロジェクト名/Build、プロジェクト名/Tools、プロジェクト名/Maintenanceに作成します。Infoは現状と結果の確認、Buildはビルド準備、Toolsは補助と検証、Maintenanceは設定、バージョン管理、リリース準備です。既定の名前はSETUP_PROJECT、PREPARE_GITHUB_RELEASE、PREPARE_NPM_RELEASEで始まり、大文字のカテゴリーが続きます。
プロジェクト別タスクグループ (project-structure)では既存の選択タスクも分類できます。プロジェクト名と各タスクの4分類のいずれかを選びます。エクスポート名とコードは変えません。自由なタスクグループAIレシピとの同時適用はできません。割り当てはプレビューに現れ、保存対象になります。
MCPでもlist_recipes、get_recipe、preview_setup、apply_setup、undo_setupで同じフォームと変更を扱います。get_recipeとlist_libraryはバージョン確認や公開許可を含む版管理されたエージェント指示も返します。自動公開する別のAIスキルは含まれません。2026年10月19日までに、プロジェクト開始、GitHub、npmAIレシピをインストール済みCursorとIntelliJのMCPでも検証しました。プレビュー、適用、読み取り確認、取り消しを行い、npmのパッケージとロックファイルを含む初期ハッシュを復元しました。準備タスクの実行、レジストリ照会、公開は行っていません。
MCP経由の設定
別のMCPアダプターはlist_recipes、get_recipe、list_setup_files、analyze_gulpfile、preview_setup、apply_setup、undo_setupで同じ処理を提供します。list_projects、list_tasks、get_taskはプロジェクト、具体的なIDEセッション、タスク一覧を返します。CursorなどのMCP Appsクライアントはopen_setup_assistantでチャット内の画面を開きます。gulpfileを選んで解析し、AIレシピとフォームを設定して全変更を確認します。適用と取り消しは別ボタンで、dashboardと同じ保護を使います。Cursorはツール実行の許可を求める場合があります。MCP Apps非対応クライアントは個別ツールを使います。
Node.js 22以降と更新済みホストの実行中セッションが必要です。別のSDK依存関係をnpm ci --prefix <Installationsordner>/src/mcp --omit=dev --ignore-scriptsで入れ、クライアントがnode <Installationsordner>/src/mcp/microgulp-mcp.mjs --project <absoluter-Projektpfad>を起動します。変更には--setup-write-project <derselbe-Projektpfad>も必要です。起動時の許可がなければ読み取り、解析、プレビューのみです。提案はMCPプロセスとIDEセッションごとに分離されます。タスク起動、自動インストール、公開はこれらのツールの機能ではありません。
テキストの提案を確認し、更新後に MCP を再接続する
「プロジェクトのタスクを設定」を開き、Gulpfile、対象タスク、編集言語を選びます。IDE エージェントが µGulp™ MCP サーバーに接続してから、テキストの依頼を準備してください。表示された依頼をそのチャットにコピーします。フォームは開いたままにしてください。依頼は 10 分間有効で、現在のプロジェクトエンジンに結び付いています。
エージェントから応答が来たら、同じフォームの「提案をフォームに読み込む」をクリックします。追加された名前、説明、ツールチップ、グループを確認してください。review-required は提案があることだけを示し、その品質や Gulpfile の変更を確認するものではありません。不適切な文章や意味の乏しい文章は、修正するか省略できます。エージェントはタスク名だけから未知の機能を創作してはいけません。
続いて変更プレビューを確認し、必要ならバックアップ付きで適用します。「この変更を取り消す」は、その後に変更がなければバックアップした状態を復元します。チャットで直接準備した依頼は、すでに開かれているフォームに自動的には関連付けられません。そのため、フォームで操作する場合は、そこに表示された依頼から始めてください。有効期限切れ、言語の変更、エンジンの再起動後には、新しい依頼を準備します。
拡張機能の更新後はインストールフォルダーが変わる場合があります。MCP 設定の microgulp-mcp.mjs へのパスを確認し、新しい src/mcp フォルダーで npm ci --omit=dev --ignore-scripts を実行して、別途必要な SDK 依存関係をインストールします。サーバーが有効でも、接続が機能している証拠にはなりません。Connection closed が出たらサーバーログを確認してください。@modelcontextprotocol/sdk が見つからない場合、使用中のフォルダーにこれらの依存関係がありません。
MCP サーバーを再接続し、新しいエージェントチャットを開きます。list_projects で現在のセッションを確認してください。テキスト提案には prepare_setup_text、get_setup_text、submit_setup_text が必要です。list_projects がセッションのないプロジェクトを返した場合、その µGulp™ ダッシュボードを開きます。到達可能な MCP 接続と、稼働中のプロジェクトエンジンの両方が必要です。
CursorのグラフィカルMCPアプリ
- Cursorでプロジェクトを開き、設定済みµGulp™ MCPサーバーを接続します。設定、タスクアクセス、任意のスキルのツールとUIリソースを提供します。
- エージェントに「
list_projectsでこのプロジェクトの現在のセッションを調べ、open_setup_assistantを開いてください。その後は変更しないでください」と依頼します。折りたたまれていればツール結果を展開します。 - gulpfileを選びAnalyze gulpfileを押します。Cursorの許可要求は自分で承認します。AIレシピを選び、NAS識別子/ソース/保存先、microCSSマニフェスト/ソース/出力、表示名/説明/グループ/ショートカットを入力します。
- Preview changesで前後表示、完全な新gulpfile、展開できる新AIレシピファイルを確認します。必要パッケージとNAS識別子の準備も表示されます。まだファイルは書きません。
- Apply changes and create backupは確認済み提案を適用し、原本を
.microgulp/setup-backupsに保存します。ソース変更、既存AIレシピファイル、実行中タスクは危険な適用を防ぎます。 - Undo this changeは原本をバイト単位に戻し、その適用で作成したAIレシピファイルだけを削除します。後の編集は取り消しをブロックします。同じMCP接続とIDEセッションでのみ直近の適用を取り消せます。
--setup-write-projectがなければ解析とプレビューのみで、適用は非表示です。画面はタスクやインストールを実行しません。同一接続の複数画面とエージェント呼び出しは最後のプレビューを共有するため、一度に一つの提案を扱います。
Cursor、ホスト、MCPの再起動後はlist_projectsとopen_setup_assistantを再度呼び、再解析します。古い画面はide-session-unavailableを返す場合があります。有効期間は10分です。適用中に切断されたら再書き込み前にファイルとバックアップを確認します。VSIX更新後はMCPのインストール先を確認し、必要ならSDK依存関係を再インストールして再接続します。
CursorとIntelliJにMCPを接続する
MCPとスキルは任意です。日常はプロジェクトを開いてタスクを選び実行するだけです。次の操作には更新済みホストでプロジェクトを開く必要があります。実際のインストール先を使います。Cursorはsrc/mcp、展開したJetBrainsプラグインはmicrogulp/src/mcpです。前述のSDK依存関係をそこに入れます。
次の設定例は両クライアントに使えます。絶対パスをローカルの値に置き換えます。--setup-write-projectはこのプロジェクトだけで後の確認済み適用と取り消しを許可します。
{
"mcpServers": {
"microgulp": {
"command": "C:/Program Files/nodejs/node.exe",
"args": [
"C:/Pfad/zur/Installation/src/mcp/microgulp-mcp.mjs",
"--project", "C:/Projekte/MeinProjekt",
"--setup-write-project", "C:/Projekte/MeinProjekt"
]
}
}
}
- Cursor: 既存エントリーを消さず、プロジェクトの
.cursor/mcp.jsonに追加します。MCP管理で有効にし、接続状態を確認します。設定変更後は再接続して新しいエージェントチャットを開きます。 - IntelliJ: Settings → Tools → AI Assistant → Model Context Protocol (MCP)でAddからSTDIO接続を追加し、JSONを貼ってApplyで開始します。Tools → AI Assistant → AgentsのPass custom MCP serversも有効にして確定します。Pass IntelliJ MCP serverは組み込みIDEサーバー用で、これの代わりにはなりません。希望するエージェントで新しいチャットを開きます。ここではChatGPTログインのCodexを検証しました。追加のµGulp™ APIキーは不要です。JetBrains設定
最初の依頼は「MCPサーバーmicrogulpのlist_projectsを呼んでください。リソース照会や変更はしないでください」です。実際の応答でパス、IDE、セッションを確認します。unknown MCP serverやツール不足は未接続を意味します。サーバー状態、転送、新規チャットを確認します。リソース照会成功はツール検証の代用になりません。返されたprojectIdとsessionIdを使い、古い値は使いません。
既存エージェントによるスキル
版管理されたライブラリーはlist_libraryで照会します。.microgulp/agent-profiles.jsonのプロファイルが許可入力とスキル版を定めます。既定のexecution: "client"はIDEエージェントを使います。別のskillGrantsは明示的なAPIモードのみで必要で、空でも通常のクライアント処理は可能です。start_api_skillはエージェント未接続時の自動代替ではありません。
翻訳プロファイル例です。3つのJSONはプロジェクトに存在する必要があります。
{
"schemaVersion": 1,
"profiles": {
"texte-de": {
"enabled": true,
"skill": "localization",
"version": "1.1.0",
"execution": "client",
"configuration": {
"source": "i18x/source.json",
"target": "i18x/de-DE.json",
"baseline": "i18x/source-baseline.json",
"sourceLanguage": "en-US",
"language": "de-DE"
}
}
}
}
inspect_skill_profileは現在のハッシュを返します。start_skillにはプロファイルID、ハッシュ、新しい一意のrequestIdを渡します。準備済み依頼は30分有効です。- エージェントは項目を処理し、結果、ジョブID、未変更の
digestをsubmit_skill_resultへ送ります。.microgulp/proposals/<id>/proposal.jsonに提案を保存し、翻訳ファイルは変えません。 - 対象パス、変更テキスト、維持されたプレースホルダーと未変更項目を確認します。その後だけ提案IDの
apply_skill_proposalを許可します。µGulp™はソースを再確認し、原本を.microgulp/proposals/<id>/original.jsonに保存します。 - 実ファイルを確認します。
undo_skill_proposalはファイルがその後未変更で同じ接続とホストセッションなら、同じIDでその適用を取り消します。受け入れ検証では前後のファイルハッシュを比較します。
簡単な依頼は「既存エージェントでtexte-deを使い、MCPで結果を提出してプレビューを表示してください。適用前に止め、直接編集しないでください」です。適用と取り消しは別途明示します。skill-expired後は再準備し、unknown-skill-runやunknown-undoでは先にセッション、ファイル、バックアップを確認します。盲目的な再試行や直接書き込みによる代替は行いません。
根拠付きプレビューによるマニュアル保守
skill: "handbook-maintenance"、版1.1.0、execution: "client"のプロファイルはconfigurationに任意名のDOCXをmaster、そのsourceLanguage、実装をfiles、完全な既存GitコミットをbaselineCommitとして指定します。outputLanguageで提案言語を選べ、未指定ならソース言語です。chaptersは章を絞り、editorialRulesは任意のプロジェクト編集規則です。コミットは開いたプロジェクトから読める必要があります。PDFやMarkdownは現在対象外です。
submit_skill_resultまでの手順は翻訳と同じです。プレビューはファイル/行の根拠付き提案とeditorial-review-requiredを含みます。DOCXの自動適用はありません。 apply_skill_proposalはhandbook-report-requires-editorial-workで拒否します。編集は設定済みDOCXで別に行います。比較ベースライン、翻訳、最終出力は更新しません。「先にドイツ語.src.、後で差分のみ翻訳」は当社µGulp™プロジェクトのプロファイルだけの規則です。利用者が自分の編集手順を決めます。
顧客マニュアルの例
ソースはdocs/Customer Guide.docxなど任意です。この例は英語ソースにフランス語の提案を使います。プレースホルダーをプロジェクトの本物の完全なGitコミットに替えます。
{
"enabled": true,
"skill": "handbook-maintenance",
"version": "1.1.0",
"execution": "client",
"configuration": {
"master": "docs/Customer Guide.docx",
"sourceLanguage": "en-US",
"outputLanguage": "fr-CA",
"files": ["src/build.mjs"],
"baselineCommit": "<vollständiger Git-Commit>",
"editorialRules": "Kundenterminologie erhalten und bestehende Kapitelstruktur beachten."
}
}
この項目を.microgulp/agent-profiles.jsonのprofiles内に独自名で置きます。de-DE、en、fr-CA、zh-Hantなどの識別子は検証されますが、結果の言語品質は自動認証されません。翻訳のソースと対象は別ファイルで、文字列のフラットJSON辞書のみ対応し、MarkdownやDOCXの汎用翻訳ではありません。
既存スキルプロファイルの更新
1.0.0プロファイルは翻訳とマニュアルで実行可能なままです。ファイルとハッシュは自動変更しません。sourceLanguageなしの古い翻訳は不明言語(und)のままで、エージェントがテキストから判断します。古いマニュアルは未指定時de-DEを使います。明示設定が優先です。新規顧客プロファイルは1.1.0でソースと言語を選び、プロジェクト固有の規則はプロファイルに置きます。恒久移行はバックアップ、版と言語確認、新規依頼の順です。未知の版や不正プロファイルは個別に実行不可になり、隣の正常プロファイルを妨げません。ファイル全体が不正なら拒否します。ライブラリーのピンと完全性値は自動更新しません。プレビュー、プレースホルダー保護、バックアップ、取り消し、DOCX禁止は旧版にも適用されます。
IntelliJのdashboard接続を復旧する
プロジェクトエンジン終了を開いたµGulp™ウィンドウが検知するとReconnect dashboardを示します。非表示から再表示すると、終了が確認されたエンジンを再起動します。動作中は再起動せず、タスクも再実行しません。開始失敗はメッセージと再試行を表示し、自動ループしません。準備完了通知がなければ最大120秒で中断します。Nodeパスと設定を確認してReconnect dashboardを選びます。再接続後にlist_projectsを呼び、新規セッションを選びます。古い提案/取り消しIDを引き継がず、変更依頼前に保存済みコピーを確認します。MCPが緑でもdashboardセッションが動作中とは限りません。
検証済みの処理と許可
スキル1.1.0の顧客プロファイルは2026年10月19日までにインストール済みCursor/IntelliJのMCPで検証されました。en-GBからfr-CA、プレースホルダー維持のプレビュー、適用、バイト単位の取り消しです。DOCXソースと報告言語は自由に選び、自動適用はhandbook-report-requires-editorial-workで拒否され、ハッシュは不変でした。1.0.0互換性も後でIntelliJで確認しました。これは制御手順の証明で、任意のAI結果の言語品質の保証ではありません。
2026年10月19日、エンジン終了後のReconnect dashboardをIntelliJで検証しました。新しいセッションがMCPから利用でき、旧プロファイル検証も成功しました。翻訳は適用後バイト単位に戻り、マニュアル自動適用はサーバーが拒否してDOCXは不変でした。検証した再接続の証明であり、任意の実行タスクや旧IDの復元ではありません。
最後のWindows/Node.js 22ローカル検証は1115成功、失敗なし、明示的なプラットフォーム/機器スキップ4件でした。追加のMCP/サイト31件も成功しました。更新したVS Code、Cursor Internal、Freeをインストールし、dashboardタスク成功を確認しました。JetBrains Plugin Verifierは242/261/262との互換性を確認し、問題の非推奨API呼び出し2件は削除済みです。修正JetBrainsパッケージをWindowsのIntelliJ IDEA 2026.2.2で確認しました。事前入力パスの確定、選択取り消し、ログを開く操作、初回全体表示、非表示/再表示、最大化/復元、ウィンドウサイズ変更です。異なるDPIのモニター間移動は未検証です。過去のネイティブMCP検証はそのパッケージ版に対応します。新しいクロスプラットフォームCIや残る実機試験の代わりではありません。
2026年10月17-19日、ローカル2.0.0をWindowsで実際のCursorエージェントとIntelliJ AIチャットのCodexで確認しました。翻訳プレビュー、適用、読み取り、バイト単位の取り消し、根拠付きマニュアルプレビュー、DOCX拒否と不変ハッシュを含みます。グラフィカルMCPはCursorでの検証で、IntelliJの画面検証ではありません。他のエージェント/OSは対象外です。
最初のCursor実行はunknown-undoとなり、原因未解明でした。次の完全な実行は成功しました。エラー時はセッションとコピーを明示的に確認します。Guardianなどクライアントの許可審査の拒否はµGulp™応答でも成功した負のテストでもありません。許可を迂回せず、追加試行には明示的な追加許可が必要です。DOCX負のテストは実際のµGulp™エラーと、その後に読み取った不変ハッシュが必要です。
スナップショット
| 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（昇順整数）。グループは部分木の最小順。未指定タスクは最後（アルファベット順） |
Taskをクリックすると、利用可能なウォームワーカーがGulpfileを再読み込みせずに実行します。Gulpfileを保存するとTask一覧が自動更新されます。複数のTaskを並行実行でき、それぞれがReportProgressをgulp-mu-gulp-apiから通知すると、専用のダッシュボードセクションにネオンの進捗バーが表示されます。
Gulp CLIを継続利用
追加メタデータはCLIでの指定方法を変えません。既存ビルドは通常のgulpやCIで続けられます。importしたパッケージは必要で、入力とホスト依存の操作はその経路に適する必要があります。統合後は既存CLI呼び出しを確認してください。
dashboardなしでの動作
| 追加するもの | 素の 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/ |
用途によってAIレシピコード、プロファイル、設定、保存コピーも含みます。一括削除しないでください。importされたコードはCLIでも必要な場合があります。プロジェクトファイルを選んで版管理し、ローカルログ、資格情報、バックアップは除外します |
gulp-mu-gulp-apiは実行時依存関係なしの通常のnpmパッケージで、IsMicroGulp()が現在の実行環境を示します。拡張を削除しても必要なパッケージとAIレシピは残します。ホスト依存操作には適切な代替が必要です。
バージョン条件を確認
通常のGulp CLIは追加メタデータを無視しますが、任意のホスト/Gulp/API版の互換保証ではありません。新しいAPIは新パッケージを、IDE操作は対応機能を要する場合があります。版の条件を確認し、更新後に既存呼び出しを検証します。
同僚が端末でnpx gulp BUILDを使う一方、自分はdashboardを使えます。両方とも同じファイルを扱うため、同時書き込みはプロジェクトで調整します。
インストール
µGulp™ は今すぐ利用できます。公開掲載からインストールしてください:
| エディション | インストール |
|---|---|
| µGulp™（VS Code / Cursor） | VS Code にインストール · Open VSX からインストール |
| µGulp™ Free（VS Code / Cursor） | µGulp Free をインストール · Open VSX からインストール |
| µGulp™（JetBrains IDEs） | JetBrains にインストール |
ソースリポジトリは非公開のままです。登録版 VS Code/Cursor と µGulp™ Free を並べて入れないでください - 同じコマンド ID を共有します。
その後、コマンドパレットから µGulp: Open Dashboard を実行（またはステータスバーの µGulp™ ロケットをクリック）。
JetBrains IDE
JetBrains プラグインはプラットフォームプラグイン（com.intellij.modules.platform）で、IntelliJ IDEA、PhpStorm、WebStorm、PyCharm、Rider、CLion、GoLand、RubyMine、DataGrip およびその他の IntelliJ 系 IDE に入ります。JetBrains にインストール は Marketplace から。掲載は互換性別の 2 ビルドを提供し、IDE は合う方を受け取ります（Help → About）:
| IDE build | since-build |
Marketplace |
|---|---|---|
2024.2 - 2026.1（261.* まで） |
242 |
JetBrains にインストール |
| 2026.2 以降 | 262 |
JetBrains にインストール |
Marketplace が合うビルドを選びます。 IntelliJ IDEA、PhpStorm、WebStorm ほか IntelliJ 系 IDE は同じ 2 バリアントです - 製品名ではなくプラットフォームビルドで決まります。各バリアントのディスクリプタに
<idea-version since-build="…"/>があり、IDE はもう一方を読みません。2024.2-2026.1 はsince-build="242"/until-build="261.*"。2026.2+ はsince-build="262"で上限なし。プラットフォームビルドは 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) プラグインへ移したため、ディスクリプタで明示宣言が必要です - そのため別の Marketplace バリアントです。JetBrains Marketplace（Settings → Plugins → Marketplace で MicroGulp を検索）からインストールし、µ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/ を開く。
オフラインパッケージ
これらのファイルはソースリポジトリのローカル checkout にだけあります。公開のインストール経路ではありません。
ローカル 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/に入ります。
ローカルビルドの JetBrains zip:
| IDE build | パッケージ |
|---|---|
2024.2 - 2026.1（261.* まで） |
packages/microgulp-jetbrains_latest.zip |
| 2026.2 以降 | packages/microgulp-jetbrains-2026.2_latest.zip |
ローカル zip は Settings → Plugins → ⚙ → Install Plugin from Disk… で入れます。
設定ファイル microgulp.config.json（JetBrains と CLI）
VS Code / Cursor ではエンジンは拡張設定（microgulp.gulpfilePattern など）で構成します。JetBrains プラグインは同じエンジンオプションを Settings → Tools → µGulp に映し、次のツールウィンドウオープン時にサイドカー CLI フラグとして渡します。任意で、プロジェクトルートの microgulp.config.json がチーム共通デフォルトと、IDE ページに無いキー（dashboardFonts、metadataWatchFiles、versionSources、project）をまだ供給します。CLI フラグが無いときの microgulp-serve による素の CLI/ブラウザ利用はファイルを読みます:
{
"gulpfilePattern": "gulpfile.*\\.mjs$",
"poolSize": 2,
"maxParallel": 6,
"preload": true,
"watchGulpfiles": true
}
| Key | Type | Default | Meaning |
|---|---|---|---|
gulpfile |
string | - | プロジェクトルートからの相対パスで指定する単一 gulpfile。ルート外は不可 |
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. |
project |
object | - | 任意。 タスク一覧用のプロジェクト識別: title、description、logo（SVG/PNG/WebP、プロジェクトルート相対）。値なしなら追加見出しなし。 |
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 を再起動してください。
プロジェクト識別 (project)
タスク一覧の上に任意のコンパクトな見出しを置き、複数の IDE ウィンドウを開いているときに、どのワークスペースのタスクかがすぐ分かるようにします:
{
"project": {
"title": "ESP][",
"description": "Apple II emulator for ESP32-S3",
"logo": "./assets/esp2.svg"
}
}
- 3 フィールドとも任意。メタデータが無いと従来のレイアウトのままです。
logo: プロジェクトルートからの相対パス。形式は SVG、PNG、WebP。欠落や無効なファイルは無視（ロゴ無しの見出し）。- 見出しのツールチップ: タイトル、説明（あれば）、ワークスペースの絶対パス。
- プロジェクト識別情報はダッシュボードのタスクリストと Web Console に表示されます。Stream Deck のグループブラウザーの Root キーではロゴの縦横比を維持し、名前を別の帯に表示します。使用できないロゴには代替表示を使います。Logitech MXは接続ホストのプロジェクト画像をworkspace選択とµGulp™キーに使用し、使用できなければブランド画像を表示します。実機での完全な受け入れ検証は未完了で、Flexbar のロゴ表示も約束しません。
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™ は 単一パス または workspace 全体を検索する 正規表現パターン で gulpfile を検出します。選択はプロジェクトに属し、VS Code、Cursor、JetBrains、CLI で共通です。
- IDE／CLI の明示的な上書き： VS Code/Cursor の設定、JetBrains の Settings → Tools → µGulp、または
microgulp-serve --gulpfile/--gulpfile-pattern。空欄は上書きではありません。 - ルートの
microgulp.config.json（gulpfileまたはgulpfilePattern）。 - 既定： ルートの
gulpfile.mjs。なければ(^|/)gulpfile\.(m|c)?js$で検出。
各段階でパターンが単一パスより優先されます。ルート外のパスは拒否され、ファイルがなければ警告して次の段階へ進みます。
microgulp.gulpfilePattern- ワークスペース相対パス（/の POSIX 記法）に対する JavaScript 正規表現（大文字小文字無視）。設定時は一致する すべての ファイルをスキャンし、タスクはダッシュボードでソース別にグループ化。例:(^|/)gulpfile\.(m|c)?js$はルートと各サブフォルダのgulpfile.mjs/.js/.cjsを見つけます。microgulp.gulpfilePath- 明示的な単一パス。既定は空欄で、microgulp.config.jsonが適用されます。
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, file, folder |
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, accept |
numeric / textarea details; accept on file is .zip,.json |
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）は一方通行プロセスからフォームを出せないため、宣言デフォルトより記憶値で走ります。
長い選択肢リスト（select / radio / checkbox）に対応しています。ホストは既定でフィールドごとに 5000 項目まで保持します（MICROGULP_MAX_SELECT_OPTIONS で変更、0 は無制限）。省略時には警告を表示し、黙って切り捨てません。24 項目以上でフィルターが表示されます。gulp-mu-gulp-api の随時 RequestForm はライブデータにホスト側の上限を設けません。同じフィールド型とフィルターを使用します。
ウォッチ / トリガータスク (µ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.µShortDisplayName = 'CSS, Build Styles<context="µShortDisplayName"/>'.i18xRegister(); // Optionaler Kurztext für Stream Deck und Logitech MX
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();
µShortDisplayNameは短い機器ラベル用の任意i18xフレーズです。dashboardの表示名とタスクIDは変えません。必要ならCSS, Build Stylesのように「短い文、元の文」を含められます。µShortDisplayNameのコンテキストタグはi18xソース専用で、ホストが出力前に除去します。機器にタグは出ません。
コンテキストタグ、必須フォーマット、マーケットプレイス言語計画: dev/docs/MicroGulpI18xProfile.md。
GulpfileからTaskの表示と操作を管理
µGulp™はTaskごとに、非アクティブまたは無効、開始中、実行中、入力待ち、停止中、成功終了、失敗の状態を表示します。独自アイコンを使っていても状態枠は表示されます。入力待ちでは紫色のダイアログ記号も表示され、ダッシュボードで応答できます。
意味に基づく表示には38種のSVGアイコンを利用できます。µTaskKindとµPresentationで、ビルド、テスト、コピー、公開などTaskの種類を表します。アイコンはテーマに従い、テーマ側で差し替えられ、動きを抑える設定にも対応します。実行アニメーションは処理中であることを示し、エラー時には元のモチーフが焦げた表示になります。独自のµIconとµIconFontの指定は維持されます。
継続して動作するサービスにはµExecutionType = 'persistent'を設定し、後から停止できます。これはファイル変更時にTaskを再実行するµWatchや、対応が必要な状態を示すµAttentionとは別の機能です。µAttentionWatchを使うと、Taskを実行せずにファイル変更後または一定間隔で注意状態を再評価できます。
Gulp TaskからTask一覧を操作することもできます:
import { SetGroupState, RevealTask, SetTaskEmphasis } from 'gulp-mu-gulp-api';
SetGroupState('Build', 'open');
RevealTask('PUBLISH_NPM', { expand: true, scroll: true, highlight: 'attention' });
SetTaskEmphasis('PUBLISH_NPM', null);
µGroupsで初期状態を指定します。以降のグループ変更はそのセッション中に適用されます。強調表示と実行状態は独立しているため、実行中のTaskに注意が必要な状態を同時に表示できます。ダッシュボードとハードウェアには同じTask状態が届きます。ダッシュボードでグループを開いても、その中のTaskは実行されません。
TaskからIDEアクションを実行
Gulp タスクは gulp-mu-gulp-api から Ide をインポートします。実装済みの 1.0.0 範囲は次の 8 関数です。
| 関数 | 用途 |
|---|---|
Ide.Capabilities() |
ホストファミリー、エディション、対応する操作と意味ベースのアクションを照会。実行系関数がロックされていても利用可能 |
Ide.Projects() |
既知のプロジェクト、稼働中のセッション、設定済みアプリの候補を照会 |
Ide.Action(id) |
現在の IDE ホストで意味ベースのアクションを実行 |
Ide.OpenProject(request) |
選択したインストールで既知のプロジェクトを開くか、その特定セッションを前面にする |
Ide.StartApplication(applicationId) |
既知または明示的に設定されたローカルアプリを起動 |
Ide.Execute({ vscode, jetbrains, args }) |
現在のホストファミリーに指定したネイティブコマンドを実行 |
Ide.Vscode.ExecuteCommand(commandId, ...args) |
許可された VS Code/Cursor コマンドを実行 |
Ide.JetBrains.ExecuteAction(actionId) |
許可された JetBrains アクションを実行 |
Ide.Action の共通カタログは open-settings、save-all、open-terminal、open-problems、find-in-project、quick-open、command-palette、next-editor、previous-editor、run、debug です。Run/Debug は現在のネイティブ設定を使用します。利用可否は IDE、インストール済みプラグイン、許可されたコマンドに依存し、すべての JetBrains 製品で同じ機能があることは保証しません。
Ide.OpenProject は Ide.Projects().result.projects の projectId と、返されたアプリ候補の applicationId などを使用します。特定セッションには sessionId と connectionId の両方が必要です。古い対象は拒否し、別のセッションへ置き換えません。
µHost は必要な IDE ファミリーを示し、µIdeApi = true はこのインターフェースが必要なタスクを示します。エンジンはエディション、登録、許可コマンドを確認します。µGulp™ Free では Ide.Capabilities() の照会は可能ですが、Ide.Projects() を含む他の 7 関数はロックされます。それとは独立して Web Console のプロジェクト一覧は閲覧できます。
呼び出しは { ok, result } または { ok: false, code, message } の Promise を返します。通常の gulp CLI など µGulp™ IPC のない環境では全 8 関数が unsupported-host を返し、IDE を起動しません。エディションまたは登録の許可がなければ unsupported-edition または unsupported-registration を返します。CLI／CI 用の代替処理は gulpfile 側で用意できます。
この範囲はリポジトリ内の実装を示し、公開済み npm バージョンでの利用を保証するものではありません。Ide.OpenUrl は計画のみで利用できません。
ハードウェア連携
Elgato Stream DeckとStream Deck Mobile、Logitech MX Creative ConsoleとActions Ring、ENIAC FlexbarからTaskを操作できます。ハードウェア機能はµGulp™ Freeを除くすべてのバージョンに含まれます。JetBrainsにFree版はありません。
µGulp™はキーに静的なアイコンを表示するだけではありません。Live Animated Task Statesでは、ダッシュボードと同じエンジンの実際の実行状態（inactive → starting → running → finishedまたはfailed、およびdisabled、waiting-for-input、stopping）に表示が連動します。開始、実行、停止、入力待ちではアニメーションし、成功とエラーは短時間表示されます（エラーはBurn→Charredを含む）。µWatchは独立したオン/オフ表示です。セッションスケジュールではキーにカウントダウンまたはn/mを重ねて表示できます。*(Actions Ringはタイトルのみで、SDKはLCDアニメーション非対応。)*仕様と状態一覧: TaskPresentationAndHardware.md。
ダッシュボードの設定 → Hardware integrationsでWorkspaceへの接続を有効にします。対応するデバイスプラグインがキーをこのプロジェクトのTaskに接続します。実行中のサービスは停止でき、入力要求にはダッシュボードで応答できます。
コンテキストに対応するコントローラー表示
µGulp™ は Visual Studio Code、Cursor、JetBrains に共通のアクティブプロジェクトコンテキストを使用します。Stream Deck は workspace とデバイスごとに最後の表示を復元します。Logitech は既存の動的 workspace 選択を維持し、そのフォルダーはプロセス全体で共通です。Flexbar は IDE プロジェクトを自動追跡しません。
アクティブプロジェクトは共通で、Stream Deck の表示はデバイスごとに保存されます。他のアプリが前面になると、µGulp™ は自分が開いたブラウザープロファイルを Stream Deck に返します。その後に表示される既定／Smart Profile は Elgato とユーザー設定次第で、自動切り替えは保証しません。
例：
Cursor: microGulp
MX -> Build
Stream Deck -> Release
Alt-Tab
JetBrains: BlueShift
MX -> Build
Stream Deck -> Test
Alt-Tab
VS Code: ESP][
MX -> Upload
Stream Deck -> Monitor
IDE ウィンドウに戻ると、その workspace の以前の Stream Deck 表示を復元します。デバイスの表示は個別保存され、複数の Stream Deck の実機検証は未完了です。
gulpfile の変更でグループがなくなると、最も近い有効な親かルートに戻ります。Follow active IDE project は既定でオンです。Logitech keypad の手動 workspace 選択が優先されます。技術的な制約：アクティブ IDE プロジェクトの追跡。
Elgato Stream DeckとStream Deck Mobile
Follow とプロファイル： Follow active IDE project が有効な場合、µGulp™ は利用可能なハードウェア接続を持つ、フォーカス中の IDE プロジェクトを採用し、付属ブラウザープロファイルを開くことがあります。既に表示中なら内容だけを変更します。IDE コンテキストを離れると µGulp™ が開いたプロファイルを返します。Elgato Smart Profiles は Stream Deck で追加設定できますが、µGulp™ はその有効化を保証しません。詳細：Stream Deck。
グループブラウザー： 別のプロファイル（Default など）の Open µGulp Group は動的なグループとタスクを表示し、設定した開始グループを開きます。一方、Follow と入口に使う µGulp Group Slot キーはアクティブ workspace の保存済み表示を復元し、保存がない新規セッションはルートから始まります。ページ、戻る、Root はナビゲーションのグリッドに従います。Root ではロゴの縦横比を保ち、名前を別の帯に表示します。無効なロゴには代替表示を使用します。ルートで戻ると終了します。Stream Deck Mobile は 3×2、5×3 などのグリッドサイズでテンプレートを選びます。
Taskを個別に固定割り当て: µGulp Taskをキーにドラッグし、WorkspaceとTaskを選ぶ方法も引き続き使えます。Task名、実行アニメーション状態、アイコンは接続先Workspaceから取得します。Stream Deck Mobileも同じ連携を利用します。
技術情報とテンプレート一覧: Stream Deck、仕様 Deviceグループナビゲーション。
Logitech: Taskの個別割り当てまたはアプリプロファイル
Logitechの設定方法は2通りあります:
- Taskを個別に割り当てる: Start a Single µGulp TaskでWorkspaceとTaskをキーに固定します。キーパッドの個別キーとActions Ringで使えます（Actions Ringはタイトルのみで、SDKはLCDアニメーション非対応）。キーパッドのフォルダーにはアイコンと実行状態が表示されます。
- Options+でアプリプロファイルを設定（例: Cursor）: アプリにフォーカスがあると、設定したキー配置が自動的に有効になります。キーパッドでGeneral µGulp Functionsを開くと、対応するWorkspaceのTask、アイコン、Live実行表示が現れます。µGulp™プラグインはIDE内でフォーカス中のWorkspaceに追従します。手動で選んだWorkspaceは、選択を解除するか接続が切れるまで維持されます。
つまり、Options+がアプリのキー配置を選び、µGulp™がWorkspaceを選びます。プロファイルはOptions+で一度設定します。アプリ切り替え後に動的フォルダーが閉じている場合は、µGulp™キーを押すと再び開きます。Actions RingではTaskを個別に固定割り当て、Taskアイコン付きの動的リストはキーパッドで使います。
Logitech MXは接続ホストのプロジェクト画像をworkspace選択とµGulp™キーに使用し、使用できなければブランド画像を表示します。実機での完全な受け入れ検証は未完了です。Dynamic Folder のプログラムによるオープンと複数の実機 MX での独立した操作は保証しません。SDK の問題は未解決です。既存の Logitech 対応は限定的かつ実験的です。
ENIAC Flexbar
FlexbarプラグインはFlexDesignerで設定したアクションを µGulp™ Taskとその実行状態に結び付けます（状態の意味はStream Deckと同じです）。Flexbar実機でのテストはまだ行われていません。
技術設定とプラグインのビルド: Stream Deck、Logitech、Flexbar。
Taskスケジューラー（セッション）
セッションスケジュールが決めるのはTaskの開始時刻だけです。実行には通常のStartTask経路を使うため、ダッシュボードのセクター、ログ、ハードウェア状態は変わりません。
| モード | 宣言 | 内容 |
|---|---|---|
| タイマー | µSchedule = { after: '10s' } |
指定時間後に1回実行 |
| 間隔 | { every: '10s' } |
繰り返し実行; 各実行後にnextRunを更新 |
| 繰り返し | { every: '5s', repeat: 5 } |
n回実行後にcompleted |
| Cron | { cron: '*/1 * * * *' } |
5フィールド、ホストのローカル時刻（croner） |
命令型API: ScheduleTask、SetScheduleEnabled、CancelSchedule、RunScheduleNow（gulp-mu-gulp-api）。ダッシュボード: nextRunに基づくカウントダウンとEnable/Disable/Cancel/Run now。µWatchが有効な間、またはTask実行中は予約開始をスキップします（schedule-skipped）。ハードウェアキーにはカウントダウンまたはn/mを重ねて表示できます。詳細とデモA-G: TaskScheduler.md。
コントローラー、ゲームパッド、ジョイスティック
ゲームパッド、ジョイスティック、その他の対応入力デバイスを自由に割り当て、ワークフロー操作に使えます。設定 → Controllersで有効にすると、プロファイル、ボタンや軸の入力学習、デッドゾーン、感度、ライブ診断を設定できます。割り当てた入力でTaskを開始・停止し、Task一覧を操作できます。
Windows x64ではダッシュボードにフォーカスがない状態でも入力を検出します。この機能にはNode.js 22以降のインストールが必要です。他のデスクトップOSにはネイティブコントローラー機能がまだ含まれていません。対応ブラウザーでは代替としてGamepad APIを利用できます。
3Dconnexion SpaceMouse Wirelessには、実機で測定した6軸・2ボタンのプロファイルがあります。他のデバイスはキャリブレーションと独自割り当てで設定できます。コントローラーが振動に対応していれば、Taskの開始、成功、エラーなどを振動で知らせる設定も可能です。対応範囲と動作はデバイスによって異なります。
設定、デバイスプロファイル、診断: コントローラーのドキュメント。
AI による gulpfile 移行
既存 の大きな gulpfile（コンソール出力、タスクメタデータ、i18x/gulp 辞書、任意の µKeyBinding / µParameters / µWatch / µAutoClose、および任意の プロジェクト識別（microgulp.config.json）を移行するには、リポジトリ内の保守プロンプトを使います:
| File | Purpose |
|---|---|
dev/prompts/OptimizeGulpfileForMicroGulp.md |
Cursor、Claude、ChatGPT 向けコピー＆ペーストプロンプト（初回移行） |
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json |
Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version) |
dev/prompts/EnhanceExistingMicroGulpProject.md |
既存の µGulp™ プロジェクトで任意の新機能を検討（無条件に有効化しない） |
移行プロンプトはµTaskKind、µPresentation、µExecutionType、µAttentionWatch、入力待ち、および妥当な project 識別（タイトル / 短い説明 / 既存ロゴ、設定はマージのみ）も考慮するようになりました。既存のµIconグリフとµIconFontの割り当ては維持されます。Coreが実行状態を管理し、常駐サービス、ファイルトリガー、注意表示はそれぞれ独立しています。ハードウェア連携はWorkspaceごとに有効化し、µGulp™ Freeを除くすべてのバージョンに含まれます。Flexbarは実機テスト待ちです。移行前に必要な製品/APIバージョンをプロジェクトの現状と照合してください。
プロンプトはi18x形式の値も指定します。カウンターにはint、小数にはfloatFix1/floatFix2、バイトにはbyteSize、ミリ秒にはprogressDuration、日付と時刻には対応する形式を使います。構造化出力にはFormatValue()を使えます。プロジェクトの辞書を対応する<format>定義とともに更新し、既存の翻訳は保持します。独自エンジンに関する暫定的な制限も考慮します。
グループ化とTaskツリーでは、µGroup、µOrder、µGroups、SetGroupState、RevealTask、SetTaskEmphasisを扱います。ハードウェアに関する説明では、Stream Deckのグループブラウザー（入口キーと動的スロットプロファイル）と、Actions RingやOptions+アプリプロファイルを含むLogitechの固定Task、µGulp™によるWorkspace選択を説明します。
Workflow
- パラメーター例をプロジェクトルートに
microgulp-optimize.params.jsonとしてコピーし、次を設定します:projectRoot、gulpfilePath、supportedLanguages（例:en-US、de-DE、zh-CN）、gulpMuGulpApiVersion（ローカル基準は^0.6.0; インストール済み/公開済みバージョンを確認）、microGulpMinVersion（1.0.0）、およびgithubRepoUrl/githubRef（既定値:https://github.com/mamekudz/microGulp,mainなど確認済みのref）。 - プロンプト markdown を開き、
{{PLACEHOLDER}}表を値で置換（または Cursor で params ファイルと gulpfile を添付）。 - AI に移行を実行させる。プロンプトのステップ 0 は必須: 編集前のタイムスタンプ付き gulpfile バックアップ（例:
gulpfile.mjs.20260703-142559.bak）。 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) |
Scheduler demosグループ（A-G）では、セッションスケジュール（µSchedule）の例を確認できます。1回限りのタイマー、間隔実行、繰り返し、Cron、重複実行のスキップ、予約エラー、Watch+Scheduleを扱います。デモのスケジュールはすべて初期状態で無効です（autoStart: false）。アイコンボタンで必要なものだけ個別に有効化してください。詳細とAPI: dev/docs/TaskScheduler.md。
追加の API 詳細: gulp-mu-gulp-api/README.md。
µGulp™ Ready
µGulp 固有の有用な操作または出力を少なくとも一つ提供し、通常の Gulp/CLI の実行方法を文書化して、両方を開発者自身が検証します。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" が含まれると、エンジンは 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）。進捗、フォーム、構造化ログ、サウンド、モーダル、カウントダウン、独自アイコン、エラー表示、常駐サービス、Attention/ResetなどのデモおよびビルドTaskを含むSample Gulpfileを~/.microgulp/sampleにコピーして開きます。続いてµGulp: Open Dashboardを実行してください。ユーザーガイドは設定 → HandbookまたはµGulp: Open Handbookから開け、各言語版を選べます。
ハンドブック PDF: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어
ライセンス
µGulp™（拡張、エンジン、ダッシュボード、JetBrains アダプタ）は プロプライエタリソフトウェア です - LICENSE を参照。配布バイナリは無償で使えます。ソースコードの複製、改変、再配布は許可されません。
付属 npm パッケージ gulp-mu-gulp-api は MIT ライセンス のままなので、Gulp タスクは制限なく採用できます。
ロードマップ / 本草案の未解決点
実装済み
[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] プロジェクト識別（
microgulp.config.jsonのproject.title/description/logo；タスク一覧のコンパクトな見出し）[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）[x] 統一されたTask状態、意味に基づくアイコン38種、入力表示、テーマのフォールバック、動きを抑える設定
[x]
SetGroupState、RevealTask、SetTaskEmphasisによるTaskツリーと強調表示[x] 8 個の IDE API 関数とホスト／利用可否表示
[x] Web Console、KnownProjectRegistry / Project Center、Open/Focus Project、共通 Background Host
[x] Stream Deck：Follow、workspace とデバイスごとの最終表示、Root キーのプロジェクトロゴ
[x] Stream Deck/Mobile、Logitech、Flexbar連携。LogitechではTaskの個別割り当てとキーパッドの動的フォルダーに対応
[x] キャリブレーションと診断に対応したコントローラープロファイル。Windows x64でのデスクトップ入力とSpaceMouse Wirelessプロファイル
まだ未解決
[ ]
Ide.OpenUrlと Background Host による IDE なしのタスク実行：計画のみで、実装済み 1.0.0 範囲外[ ] Logitech MX: プロジェクト画像を含む実機検証と、Dynamic Folder/複数機器に関するSDKの未解決事項
[ ] Stream Deck：複数実機の検証と Elgato Smart Profiles との連携
[ ] Flexbar: 実機テスト
[ ] LinuxとmacOS向けネイティブコントローラー機能
[ ]
µLib（microLib）を文書化し、µGulp のユーティリティ層として採用（今日の i18x はローカル webview サブセット）[ ] 直接 i18xe-server 接続: 同梱辞書の代わりにライブ翻訳同期
[ ]
µLibのGUI.mjsにダッシュボードフォーム用の追加特殊コントロール[ ] webview ダッシュボードの見た目磨き
[ ] µCSS スキン拡張: シンボルフォントとスプライトをマニフェストへ
[ ] i18xe 経由の音声出力（アトラスサンプルがあるときはすでに WebAudio ビープを置換）
[x] JetBrains プラグイン: Settings → Tools → µGulp（エンジンオプション）
[x] JetBrains Marketplace 掲載（プラグイン 34255。レジストリ掲載は各 IDE での新規インストールの検証ではありません）
[x] Microsoft Marketplace と Open VSX の VS Code/Cursor 掲載（登録版と Free）
Web Console と Project Center
ローカル Web Console は既知／接続中のプロジェクトを Project Center にまとめます。タスク、Project Controls、パラメーター、履歴、ライブイベントを含む既存ダッシュボードを埋め込み、2 番目の TaskEngine は作りません。VS Code/Cursor の µGulp: Open Web Console、JetBrains ツールウィンドウの Open Web Console、開発用チェックアウトの npm run console -- open で開きます。ブラウザープラグイン不要のローカル HTTP/SSE を使い、127.0.0.1 のみで待ち受けます。LAN／リモートアクセスではありません。
既知のプロジェクトとセッション
KnownProjectRegistry はパス、ProjectId、名前、説明、ロゴ、優先 IDE、最終確認時刻を ~/.microgulp/known-projects.json に保存します。メタデータは microgulp.config.json に由来します。一覧は 接続中、閉じている、利用不可 を区別します。既知の項目は実行中エンジンではありません。稼働中 IDE セッションは別に管理し、同じプロジェクトの複数ウィンドウも個別選択できます。
Follow active IDE project は共通のアクティブプロジェクトを追跡します。手動選択はこのタブだけでセッションを固定し、コントローラーの固定は変更しません。他のアプリが前面でも、最後に表示したセッションが生きていれば表示を維持します。
µGulp™ Free でも一覧と埋め込みダッシュボードにアクセスでき、通常のタスク権限が適用されます。ホスト管理も使用可能です。Open/Focus Project、Start Application、IDE 操作、優先 IDE の設定は呼び出しごとにサーバーでエディションと登録の許可を確認します。許可がなければ unsupported-edition または unsupported-registration を返します。
プロジェクトを開いてフォーカスする
Open/Focus Project は選択した IDE ファミリー、製品、インストールを使います。一致するセッションがあればそのウィンドウを前面にし、複数候補なら選択が必要です。フォーカス失敗で 2 番目の IDE を起動しません。正確なフォーカスは現在 Windows 固有です。一致するセッションがなければ指定インストールで既知のプロジェクトを開きます。同時要求はまとめられ、起動確認がなければ明示的な再試行が必要です。遅い起動は一時的に未確認として表示されることがあります。
既知の Windows ユーザーインストールを検出します。その他の IDE／アプリは実行ファイルの絶対パスと任意の固定引数で ~/.microgulp/applications.json に設定できます。JetBrains は具体的な製品が必要です。Start Application は shell コマンドなしで既知のアプリを起動します。任意の外部アプリの汎用フォーカスは範囲外です。Windsurf 検出は実験的で、別 IDE の承認ではありません。
Background Host
共通の Background Host は IDE と独立してユーザーごとに 1 プロセスで Web Console、既知のプロジェクト、アクティブプロジェクト、コントローラーコンテキストを提供します。最初の IDE が必要に応じて起動し、IDE を閉じても終了しません。任意のログイン時起動で、IDE を開かずに http://127.0.0.1:47821/console にアクセスできます。IDE がなければ既知のプロジェクトを一覧表示し、必要なエディション許可があれば Cursor、VS Code、JetBrains で開けます。タスクは接続中の IDE セッションを通じて操作します。IDE なしの実行とエンジン所有者の自動移譲は 1.0.0 に含まれません。
設定は全 IDE 共通で host-settings.json のみに保存します。Start at login と Show background UI は独立し、UI を隠してもホストは停止しません。ポートは共通（既定 47821、有効範囲 1024～65535）。変更で稼働中ホストを再起動し、Console は新アドレスへ移ります。他のアプリが希望ポートを使用中なら元のポートを維持します。ランダムポートやバインドアドレス欄はなく、127.0.0.1 のみです。
初回起動時、µGulp™ は IDE ごとではなくユーザーに 1 回だけ Enable µGulp Background Host? と尋ねます。Enable はログイン時起動を有効にし、Not now は無効のままにします。IDE は必要に応じて起動できます。
同じ操作は VS Code／Cursor（µGulp: Background Host Settings）、JetBrains（Settings → Tools → µGulp Background Host とツールウィンドウの Background Host）、Console の Background Host、npm run console -- status|open|restart|stop|port <n>|autostart on|off|ui on|off にあります。Windows トレイメニューは Console を開き、状態、接続 IDE、既知のプロジェクトを表示し、ログイン時起動を切り替えます。ポート変更はできません。Stop はホストだけを終了し、IDE が後で再起動できます。
| プラットフォーム | 自動起動 | システム UI |
|---|---|---|
| Windows | ユーザーのログイン項目 | トレイ（任意。headless 動作も可） |
| macOS | LaunchAgent | メニューバーは準備済み。macOS 実機では未検証 |
| Linux | XDG 自動起動 | headless。トレイへの依存なし |
Console の文章は現在ドイツ語と英語で提供し、他の言語は英語にフォールバックします。ホスト操作には独自の翻訳があります。実装済みタスク API は タスクからの IDE 操作 を参照してください。
한국어
Rock your Gulp!
µGulp™는 Gulp에 VS Code, Cursor, JetBrains IDE용 대화형 대시보드를 추가합니다. 태스크에 동적 표시 이름, 명확한 그룹, 아이콘, 설명, 툴팁을 부여합니다. 어떤 프로젝트와 대상의 작업인지, 실행 중인지, 성공했는지 알 수 있습니다. 폼, 진행 표시, 분리된 실시간 출력이 실행을 돕습니다. 일반 Gulp CLI도 유지되며 필요한 패키지와 적합한 입력값은 계속 필요합니다. AI와 MCP는 선택 사항입니다.
시작하기: IDE용 확장을 설치하고 Gulpfile 프로젝트를 열어 µGulp™ 대시보드에서 태스크를 시작합니다. Node.js 22 이상과 프로젝트 패키지가 필요합니다. Gulp는 반복 작업용 JavaScript 도구이고 Gulpfile이 작업을 정의합니다. µGulp™는 조작 화면을 제공합니다.
주요 기능
2026년 10월 20일 기준 2.1.0 상태: 로컬 검증 중이며 아직 게시하지 않았습니다. 전역 작업, 개선된 시작 절차, 프로젝트 작업 꾸미기가 구현되었습니다. 기존 인수 검증은 각각 해당 버전에 속하며 일부 테스트 성공이 전체 승인을 뜻하지는 않습니다. 검증한 절차와 제한은 아래에 설명합니다.
- 2.1.0 신규: 이해하기 쉬운 프로젝트 작업 꾸미기 - 편집 언어를 선택하고 기존 IDE 에이전트로 누락된 영어 원문과 번역을 제안받으며 기호나 사용자 이미지를 즉시 확인합니다. Gulpfile은 en-US로 유지되며 번역은
i18x/gulp/<sprache>.json에 저장됩니다. 미리 보기, 백업, 되돌리기는 두 파일에 모두 적용됩니다. - 동적 이름, 그룹, 아이콘과 툴팁 - 단순 함수 이름 대신 이해하기 쉬운 이름, 현재 버전이나 대상, 중첩되고 접을 수 있는 그룹, 사용자 아이콘/설명/툴팁을 사용합니다.
µDisplayName,µGroup,µIcon,µDescription,µTooltip으로 목록을 프로젝트에 맞춥니다. 문구는 지역화 가능하며µOrder는 정렬,µGroups는 초기 상태를 정합니다. - Task Preload - 웜 Node 워커는 Gulpfile을 미리 가져와 두므로 준비된 워커가 있을 때 시작 단계가 짧아집니다. 무거운 가져오기 작업이나 실시간 바이러스 검사 환경에서 특히 유용합니다.
- 한눈에 보는 Task 상태 - 시작, 실행 중, 입력 대기, 중지, 성공 및 오류를 일관된 방식으로 표시합니다. 사용자 지정 아이콘을 사용해도 상태 테두리가 보입니다.
- 병렬 태스크 그리드 - 격리된 실행 섹터를 나란히, 각각 자체 로그 스트림
- 웹 대시보드 - 실시간 ANSI 색 로그, 필터 출력, 확정 진행 막대, 사용자 입력용 풍부한 폼(텍스트, 색, 글꼴, select, multiselect, …)
- 🔴 2.1.0 신규: 기존 Gulpfile에 맞는 시작 절차 - 이미 설정된 작업을 인식하고 누락된 표시 정보만 보완하며 변경 사항을 미리 확인합니다. 다른 AI 레시피는 선택 사항이며 단축키가 없으면 도움말만 표시합니다.
- 🔴 2.1.0 신규: 하나의 공통 작업으로 여러 프로젝트 실행 - 예를 들어
NASBU같은 공통 ID로 NAS 백업이나 프로젝트 검사를 시작합니다. 제목과 아이콘을 보고 프로젝트를 명시적으로 선택하고, 프로젝트별 설정을 미리 저장한 뒤 일괄 실행 전에 확인합니다. 각 프로젝트는 자체 구현, 출력, 기록을 유지합니다. - 🔴 2.0.0 새 기능: 도우미와 AI 레시피 - 폼으로 메타데이터를 추가하고 NAS/microCSS를 통합하며 초기 설정과 GitHub/npm 게시를 준비합니다. 모든 변경을 먼저 보고 백업과 함께 적용하며 이후 불변이면 되돌립니다. 준비 태스크는 게시하지 않습니다.
- 🔴 2.0.0 새 기능: 프로젝트 그룹과 버전 준비 - 프로젝트 이름/Info, Build, Tools, Maintenance로 정리하고 npm 버전 증가와 기존 lockfile을 미리 확인해 함께 적용합니다.
- 🔴 2.0.0 새 기능: 기존 AI 에이전트 연결 - Cursor/IntelliJ MCP로 설정과 유지보수하며 기본적으로 별도 µGulp™ API 키는 필요 없습니다. Cursor에는 채팅의 그래픽 앱도 있습니다.
- 🔴 2.0.0 새 기능: 선택적 번역 관리 - 평면 JSON 사전의 누락 또는 비교 소스에서 변경된 문구만 제안받고 자리표시자를 확인한 뒤 백업/되돌리기와 함께 적용합니다. 소스와 대상 언어를 직접 선택합니다.
- 🔴 2.0.0 새 기능: 설명서 관리 지원 - 코드 변경 후 DOCX 수정 필요를 근거와 함께 제시합니다. 문서, 언어, 편집 규칙은 직접 정하며 편집은 사용자 몫입니다.
- 기존 프로필과 재연결 - 1.0.0 프로필을 계속 사용하며 IntelliJ 엔진 종료 후 대시보드를 재연결합니다. 새 세션과 제안을 확인하며 태스크는 자동 반복하지 않습니다.
- Web Console 및 Project Center - 제목, 설명, 로고, 세션 상태가 있는 알려진 프로젝트를 로컬 센터에 표시합니다. 기존 대시보드를 브라우저에서 열고 활성 IDE 프로젝트를 따르거나 현재 탭에만 세션을 고정합니다. (목록과 호스트 관리는 Free에서도 제공)
- Open/Focus Project - 특정 IDE 설치에서 알려진 프로젝트를 열거나 기존 창에 포커스를 줍니다. 세션이 여러 개면 명시적으로 선택합니다. (Free 제외. 정확한 창 포커스는 현재 Windows 전용)
- Background Host - 사용자당 하나의 프로세스에서 Web Console과 활성 프로젝트 컨텍스트를 공유합니다. 선택적인 로그인 시 시작과 공통 설정을 제공하며 IDE가 열려 있지 않아도 사용할 수 있습니다. 호스트 자체는 프로젝트 엔진을 시작하지 않습니다.
- 프로젝트 식별 - 작업 목록 바로 위에 선택적 프로젝트 제목, 짧은 설명, 로고. 여러 프로젝트나 IDE 창을 열었을 때 특히 유용(
microgulp.config.json→project) - Project Controls - 프로젝트 식별 정보 아래의 선택 목록, 라디오, 체크박스로 대상 등 프로젝트 전체 상태를 설정합니다. 표시 이름, 작업/그룹 가시성과 실행에 즉시 반영하며 workspace별 값은
.microgulp/project-controls.json에 저장합니다. - Live Animated Task States - 지원되는 하드웨어(Stream Deck, Logitech 키패드, Flexbar)는 정적 아이콘뿐 아니라 대시보드와 같은 엔진의 실제 실행 상태를 표시합니다. 시작, 실행 애니메이션, 입력 대기, 중지, 성공, 오류(Burn/Charred 포함) 및 비활성 상태가 표시됩니다. Watch 전환과 스케줄러 카운트다운은 추가 오버레이로 나타납니다. 애니메이션은 장식이 아닌 상태 피드백입니다. (µGulp™ Free에는 미포함; Flexbar는 하드웨어 테스트 대기 중; Actions Ring은 제목만 표시하며 SDK가 LCD 애니메이션을 지원하지 않음)
- 의미 기반 Task 아이콘 38종 -
µTaskKind/µPresentation에 맞는 SVG 그림, 실행 애니메이션, 입력 대기 시 보라색 대화상자 기호, 테마 재정의 및 동작 줄이기를 지원합니다. 오류가 발생하면 원래 그림이 그을린 모양으로 바뀝니다. - Task 스케줄러 (세션) -
µSchedule/ScheduleTask로 타이머(after), 간격 실행(every), 반복(repeat) 및 Cron(5개 필드, 현지 시간)을 설정합니다. 대시보드 카운트다운과 Enable/Disable/Cancel/Run now를 지원하며, 하드웨어 키에는 카운트다운 또는n/m이 표시됩니다. 실행은 일반StartTask경로를 따릅니다. - 지속 서비스를 필요한 대로 제어 -
µExecutionType으로 일회성 Task와 지속 프로세스를 구분하며 실행 중인 서비스를 중지할 수 있습니다. - Gulpfile에서 Task 트리 제어 -
SetGroupState,RevealTask및SetTaskEmphasis로 그룹을 열고 다음 작업을 표시하며 강조 표시를 설정하거나 해제합니다. - 라이브 gulpfile 감시 - 워크스페이스 워처가 저장 시 재스캔하고 오래된 워커를 자동 교체
- Gulp CLI 계속 사용 - 메타데이터는 export 이름을 바꾸지 않습니다. 가져온 API 패키지는 필요하며 입력은 CLI 값이나 적절한 기본값, IDE 동작은 호환 호스트가 필요합니다(자세히).
- 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(설정: 자동 또는 고정 로케일); 추가로 다운로드하고 설치할 수 있는 인터페이스 패키지는 2.2.0에 예정되어 있습니다. 사용자 핸드북은 기본 포함된 대시보드 언어마다 PDF로 제공됩니다.
- gulpfile용 사전 동기화 - Settings → Project i18x (gulp)가 i18xe-sync 파서로 소스를 스캔하고 고른 언어의
i18x/gulp/<lid>.json을 쓰며, 기존 번역을 유지하고 표준 형식을 병합.<lid>.status.json사이드카가 로컬 AI가 아직 번역할 항목을 나열 - 선언적 태스크 매개변수 -
µParameters는 실행 전에 한 번 묻고, 값을MICROGULP_PARAMS/GetParameters()로 넘기며, 마지막 답을 기억하고, 비밀번호를 로그에서 빼며,visibleWhen으로 필드를 숨길 수 있습니다 - 워치 / 트리거 태스크 -
µWatch글롭이 파일 변경 시 태스크를 실행. 디바운스, 합치기, 폭주 차단기. 대시보드에서 태스크별로 무장 - 하드웨어 지원 - 이제 Elgato Stream Deck, Logitech MX Creative Console / Actions Ring, Flexbar 및 게임패드를 지원합니다. Gulp 제어를 한 단계 끌어올립니다. µGulp™ Free를 제외한 모든 버전에 포함됩니다(설정 및 기기 현황).
- Logitech이 Workspace를 따릅니다 - 개별 Task를 키에 고정하거나 앱용 Options+ 프로필을 만들 수 있습니다. 플러그인은 동적 키패드 폴더에 포커스된 IDE 창의 Workspace를 표시합니다.
- Stream Deck이 workspace를 따름 - Follow는 활성 IDE 창의 프로젝트를 선택하고 workspace와 장치별 마지막 보기를 기억하며 Root 키에 로고와 제목을 표시합니다. 돌아오면 그룹 경로와 페이지를 복원합니다. (여러 실물 장치 검증은 미완료. Elgato Smart Profiles는 보장하지 않습니다. Logitech은 기존 제한적 범위를 유지하며 Flexbar는 자동으로 따르지 않습니다.)
- 워크플로 제어용 컨트롤러 - 게임패드와 조이스틱에 자체 프로필, 입력 학습, 데드존 및 진단을 제공합니다. Windows x64에서는 대시보드에 포커스가 없어도 사용할 수 있으며, 기기에서 측정한 SpaceMouse Wireless 프로필과 지원 기기의 선택적 진동도 포함합니다.
- IDE API 함수 8개 - 기능과 알려진 프로젝트 조회, 의미 기반 또는 네이티브 IDE 작업 실행, 프로젝트 열기/포커스와 설정된 앱 시작을 제공합니다.
µHost/µIdeApi는 사용 가능 여부를 표시합니다. 실행 함수는 Free에서 사용할 수 없으며Ide.Capabilities()는 호스트 기능을 알려 줍니다(API 범위). - 태스크 단축키 - 플랫폼별 변형이 있는
µ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) - 네이티브 파일 및 폴더 선택 - 양식의 파일 필드에서 VS Code/Cursor 또는 JetBrains 선택 대화상자를 열고 실제 경로를 반환합니다.
- 모달 대화상자 - 대시보드의 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 - Task를 시작하지 않는 주의 표시 -
µAttention은 조치가 필요한 상태를 표시하고µAttentionWatch는 파일 변경 또는 일정 간격으로 이를 갱신합니다. 툴팁, 설치 버전 및 접힌 그룹에서도 보이는 표시를 제공합니다. - Windows 관리자 권한 상승 - Task별 UAC 대화상자를 선택적으로 표시합니다(
µRequiresElevation,µElevationReason). IDE는 일반 권한으로 실행하면서 특정 Task(예:hosts파일 작업)만 높은 권한으로 시작할 수 있습니다. (µGulp™ Free에는 미포함) - 진단 엔진 - 가져오기 오류와 스택 추적을 대시보드의 구체적인 해결 제안으로 바꿉니다. (µGulp™ Free에는 미포함)
- gulpfile의
<version/>- 태스크 제목의 우선 소스는µI18xContext.version. 선택versionSources는 gulpfile이version을 생략할 때만 채움(소비자 릴리스 설정을 덮어쓰지 않음) - 신뢰할 수 있는 LogError 대 Node 경고 -
LogError/ 실제console.error는 실행을 실패시킴. NodeDeprecationWarning과 기타 프로세스 경고는 실패가 아님(실패 배너는 첫 실제 오류 텍스트를 표시) - 레거시 프롬프트 브리지 - gulpfile을 고치지 않고
inquirer/gulp-prompt/prompts를 대시보드 폼으로 리디렉트 gulp-mu-gulp-api- 태스크 안에서 진행, 소리, 음성, 대화형 입력, 모달, 대시보드 글꼴용 npm 모듈
원하는 언어로 프로젝트 작업 꾸미기
‘프로젝트 작업 설정’은 선택한 프로젝트 Gulpfile의 기존 작업 표시를 구성합니다. 여러 프로젝트에 걸친 전역 작업은 별도로 관리하며 이 도우미는 변경하지 않습니다.
편집 언어는 제안하는 표시 이름, 설명, 툴팁, 그룹에 적용됩니다. 선택 필드는 i18xe 프로젝트에서 중앙 관리하는 언어 코드와 원어 이름 목록을 사용하며, 다른 유효한 BCP 47 언어 코드도 입력할 수 있습니다. 기본 선택값은 package.json의 microgulp.editingLanguage에서 가져옵니다. 이 값이 없으면 IDE 웹뷰의 브라우저 언어를 사용합니다. 인터페이스 언어는 별개이며, 각 요청 전에 편집 언어를 변경할 수 있습니다.
‘IDE 에이전트로 텍스트 제안 준비’는 누락된 텍스트 필드만을 위한 제한된 요청을 만듭니다. Gulpfile에는 항상 영어 en-US 원문을 사용하며, 다른 편집 언어를 선택하면 도우미가 i18x/gulp/<sprache>.json에 해당 번역을 추가합니다. 기존 번역은 덮어쓰지 않습니다. 대시보드에서는 표시된 요청을 연결된 Cursor 또는 IntelliJ 에이전트 채팅에 복사합니다. 그래픽 MCP 앱에서는 클라이언트가 메시지를 지원하면 ‘IDE 에이전트에 보내기’를 사용할 수 있습니다. 기존 에이전트가 텍스트를 생성하고 MCP를 통해 돌려줍니다. 추가 API 키는 필요하지 않습니다. 도우미는 백그라운드에서 에이전트를 시작하거나 유료 대체 서비스를 사용하지 않습니다.
‘제안을 폼으로 불러오기’를 누르면 확인된 제안이 표시됩니다. 기존 메타데이터, 번역 키, 계산된 값, 그동안 직접 편집한 필드는 유지됩니다. 요청은 10분 후 만료되며 Gulpfile이나 사전이 변경되면 거부됩니다. 미리 보기는 두 파일을 함께 보여 줍니다. 백업을 포함한 적용을 명시적으로 승인해야 Gulpfile과 사전을 기록하며, 되돌리기는 이전 상태를 복원합니다. 언어와 내용의 검토는 사용자의 책임입니다.
µGulp™에 기본 포함된 인터페이스 언어 8개는 별개입니다. 다운로드하거나 설치할 수 있는 추가 µGulp™ 인터페이스 번역 패키지는 버전 2.2.0에 예정되어 있으며 아직 이 도우미에 포함되지 않습니다.
아이콘은 기호나 이모지를 입력하거나 64 KiB 이하의 PNG, JPEG, WebP 이미지를 선택합니다. 선택 결과를 즉시 미리 볼 수 있습니다. 이미지는 Gulpfile에 내장되므로 원래 파일 경로에 의존하지 않습니다. 여기서는 새 SVG 파일이나 이미지 URL을 가져오지 않습니다. 기존 아이콘 메타데이터는 변경 없이 적용하면 그대로 유지됩니다.
기존 Gulpfile을 필요한 부분만 개선하기
설정 도우미는 먼저 정적 분석만으로 작업에 µGulp™ 표시 메타데이터가 이미 있는지 확인합니다. 표시 이름, 설명, 그룹, 아이콘, 툴팁 중 하나만 있어도 작업 표시가 이미 설정된 것으로 인식합니다. 이는 Gulpfile의 전체 품질 평가가 아닙니다. 모든 작업에 이 항목이 전부 필요한 것은 아닙니다.
인식한 모든 작업이 이미 설정되어 있으면 자동 최적화 안내가 나타나지 않습니다. 일부만 설정된 Gulpfile에서는 해당 정보가 없는 작업만 제안합니다. 먼저 이름, 설명, 그룹, 아이콘, 툴팁을 추가하고 변경 미리 보기를 확인한 뒤 백업과 함께 적용하도록 명시적으로 승인할 수 있습니다. 되돌리기도 계속 사용할 수 있습니다. 다른 AI 레시피는 이후에 이용하거나 이 단계를 의도적으로 건너뛰어 이용할 수 있습니다.
계산되거나 가져온 메타데이터는 항상 명확하게 판단할 수 있는 것은 아닙니다. 이 경우 도우미는 최적화 상태를 알 수 없다고 표시하며 값을 자동으로 변경하지 않습니다. 단축키는 선택적 도움말일 뿐이며, 없다고 최적화가 필요한 것으로 판단하지 않습니다. 전역 작업에 연결되지 않은 것도 결함이 아닙니다. 두 번째 단계에서는 다른 AI 레시피와 단축키가 기본적으로 선택 해제되어 있습니다.
선택한 프로젝트의 전역 작업
전역 작업을 사용하면 같은 작업을 프로젝트마다 찾아서 시작할 필요가 없습니다. 공통 ID가 프로젝트별 구현을 연결합니다. 예를 들어 NASBU가 프로젝트마다 다른 폴더를 백업할 수 있습니다. Web Console은 참여 프로젝트를 제목과 아이콘으로 표시하며, 실행할 프로젝트는 사용자가 명시적으로 선택합니다.
전역 정의는 안정적인 ID와 이해하기 쉬운 제목으로 구성됩니다. 실행 구현은 각 프로젝트의 Gulpfile에 남습니다. 공통 소스 코드를 배포하거나 작업을 다른 프로젝트로 자동 복사하지 않습니다. 여러 프로젝트가 같은 ID를 각자의 요구에 맞게 구현할 수 있습니다.
내보낸 작업에 µGlobalTask = { id: "NASBU", title: "NAS-Sicherung" }을 추가합니다. ID는 대문자로 시작하며 대문자, 숫자, 밑줄, 빼기 기호를 합쳐 최대 64자까지 사용할 수 있습니다. 한 프로젝트는 같은 ID를 정확히 한 번만 제공할 수 있습니다. 표시된 작업은 프로젝트 대시보드의 별도 전역 작업 그룹에 나타나며, 해당 작업의 기존 µGroup은 대체됩니다.
Web Console에서 전역 작업을 펼칩니다. 목록을 새로 고치고 공통 작업을 선택합니다. 프로젝트 설정에서 각 프로젝트의 µParameters 값을 한 번 저장합니다. 값은 로컬 .microgulp/global-tasks.json에 저장됩니다. 매개변수 정의가 변경되면 다시 설정해야 합니다. 비밀번호와 remember: false로 표시한 값은 여기에 저장하지 않으며, 이런 작업은 계속 프로젝트의 대화형 조작이 필요합니다.
전역 작업 정의에서 ID와 제목을 중앙에서 지정할 수 있습니다. 목록은 연결된 프로젝트의 ID도 인식합니다. 중앙 제목은 표시를 통일하지만 실행 구현을 만들지는 않습니다. 정의는 사용자 디렉터리의 .microgulp/global-tasks.json에 저장됩니다.
제목과 아이콘으로 프로젝트를 선택합니다. 같은 프로젝트의 IDE 창이 여러 개면 세션을 정확히 하나 선택합니다. 선택 검토는 선택한 프로젝트와 저장된 값만 보여 줍니다. 선택한 작업 시작을 눌러야 각 IDE에 실행을 전달합니다. 닫힌 프로젝트나 IDE를 자동으로 열지는 않습니다.
일괄 실행은 입력 양식을 다시 표시하지 않고 저장된 매개변수를 사용합니다. 그런데도 작업이 µGulp 대화상자를 요청하면 해당 실행은 global-task-dialog-required 오류로 실패합니다. Windows 권한 상승이 필요한 작업과 계속 실행되는 작업은 전역으로 시작하지 않습니다. Gulp 코드는 로컬 프로그램 코드로 유지됩니다. 자체 대화상자가 있는 외부 프로그램이 이 기능으로 무인 실행 작업이 되지는 않습니다.
미리 보기는 짧은 기간 동안 한 번만 사용할 수 있습니다. Gulpfile, 작업 정의, 저장된 매개변수 또는 Project Controls가 바뀌면 무효가 됩니다. IDE 세션이 종료되거나 바뀌면 다시 선택하고 검토해야 합니다. 첫 작업을 시작하기 전에 선택한 모든 세션을 확인합니다.
일괄 실행은 트랜잭션이 아닙니다. 첫 실행 후 연결이 끊기면 앞선 프로젝트는 이미 실행 중일 수 있습니다. 결과는 시작된 프로젝트, 실패한 프로젝트, 아직 시작하지 않은 프로젝트를 보여 줍니다. 자동 재시도나 실행된 작업의 자동 되돌리기는 없습니다. 진행률, 로그, 중지는 각 프로젝트 대시보드에서 확인하고 조작합니다.
한 프로젝트에서 다른 프로젝트의 작업 실행하기
프로젝트 A의 작업은 gulp-mu-gulp-api의 RunGlobalTask로 프로젝트 B에서 µGlobalTask로 표시한 구현을 실행하고 완료를 기다릴 수 있습니다. 정확한 프로젝트 ID와 전역 작업 ID를 전달합니다. 대상 매개변수는 프로젝트 B의 대시보드에서 미리 설정해야 합니다. 프로젝트 B는 µGulp 대시보드가 열린 활성 연결이 필요합니다. 대상 프로젝트의 세션이 여러 개 열려 있으면 원하는 세션의 sessionId도 지정합니다. 닫힌 프로젝트나 IDE는 자동으로 열리지 않습니다.
import { RunGlobalTask } from 'gulp-mu-gulp-api';
const result = await RunGlobalTask({
projectId: 'Projekt-ID-von-B',
globalId: 'DEPLOY',
timeoutMs: 120000
});
if (!result.ok) throw new Error(result.error ?? result.code);
console.log(result.taskResult);
응답에는 상태, 실행 ID, 소요 시간이 포함됩니다. taskResult는 대상 작업이 ReportTaskResult를 호출한 경우에만 있습니다. 호출은 연결된 IDE 세션을 통해 대상 작업을 실행하며, 이때 표시되는 Web Console 창을 열지 않습니다. 자기 자신에 대한 호출과 재귀적인 프로젝트 연결은 거부됩니다. 제한 시간은 1~300초이며 생략하면 120초입니다. 시간 초과가 발생해도 대상 작업이 이미 시작되었을 수 있습니다.
전역 호출에는 µGulp 대시보드가 열려 있는 활성 상태의 신뢰된 IDE 세션과 IDE API 접근 권한이 있는 에디션이 필요합니다. 프로젝트 개요와 기존의 간단한 작업 조작은 유지됩니다. Background Host에서 닫힌 프로젝트를 독립 실행하는 기능, 전역 하드웨어 키, 전역 MCP 도구는 2.1.0 범위에 포함되지 않습니다.
에디션과 기능 범위
µ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 에디션은 첫 Task 실행 전에 등록해야 합니다. 등록하지 않으려면 확장을 제거하고 µGulp™ Free를 사용하세요. JetBrains는 µGulp™ 등록이 필요 없으며 JetBrains용 Free 버전은 없습니다.
| µGulp™ VS Code / Cursor |
µGulp™ Free VS Code / Cursor |
µGulp™ JetBrains IDEs |
|
|---|---|---|---|
| 가격(월 / 년) | 0 € / $0 | 0 € / $0 | 0 € / $0 |
Task 대시보드, Preload, i18x, 매개변수, µWatch, µSchedule, 기록 |
예 | 예 | 예 |
| 라이선스 / 등록 | 필수 | 없음 | 없음 |
| 스킨(Neon Carbon, Ice Light, IDE Dark / Light, Automatic) | 예 | IDE 테마의 IDE Dark / Light(선택 불가) | 예 |
| 사용자 테마 ZIP 팩 | 예 | - | 예 |
| 진단 엔진 | 예 | - | 예 |
| Windows UAC 승격 | 예 | - | 예 |
| 하드웨어 통합 (Stream Deck, Logitech, Flexbar) | 예 | - | 예 |
| Task에서 IDE 작업 실행 | 예 | - | 예 |
| Web Console: 프로젝트 목록, 세션 상태, 내장 대시보드 | 예 | 예, 일반 작업 권한 적용 | 예 |
| Background Host 및 호스트 관리 | 예 | 예 | 예 |
| Open/Focus Project, Start Application, IDE 작업, 선호 IDE | 예 | - | 예 |
| 호스트 설정 | microgulp.* |
microgulp.* |
Settings → Tools → µGulp |
| Marketplace | VS Code용 설치 · Open VSX에서 설치 | µGulp Free 설치 · Open VSX에서 설치 | JetBrains용 설치 (de.amekudzi.microgulp) |
현재 모든 에디션은 무료입니다(월 €0 / $0, 연 €0 / $0). 아래 항목은 전체 제품의 기능을 설명합니다. Free 버전은 IDE/OS 테마를 따르며 IDE Dark / IDE Light만 제공합니다(Appearance 선택기 없음). 테마 팩, 진단, 권한 상승, 하드웨어 통합 및 IDE 작업은 제공하지 않습니다. 로컬 Web Console은 Free에서도 사용할 수 있습니다. 프로젝트 목록, 상태, 호스트 관리는 제공되지만 확장 작업(Open/Focus Project, Start Application, IDE 작업, 선호 IDE)은 다른 에디션에서만 사용할 수 있습니다.
2.0.0의 새 기능
설정 도우미는 기존 프로젝트에 AI 레시피를 추가하고 적용 전에 모든 파일 변경을 보여 줍니다. IDE 에이전트와의 선택적 MCP 연결, 번역 및 설명서 유지보수 지원도 새 기능입니다. 일상적인 사용은 그대로입니다. 프로젝트를 열고 태스크를 선택해 실행합니다.
범용 AI 워크플로 생성기, 임의 태스크의 의미 기반 최적화, 진화적 자기 최적화는 구현되지 않은 확장 아이디어이며 범위나 일정이 약속되지 않았습니다.
1.1.0부터 제공
선택적 폼 정보를 입력 필드 앞에 표시합니다. 작업에서 취소와 저장 가능한 선택값 기억을 명시적으로 활성화할 수 있습니다. µI18xContext.GetValues()는 스캔마다 동기식 메타데이터를 제공하며, 자리표시자 변경은 작업 목록에도 반영됩니다. 기존 gulpfile과 성공한 폼 응답은 호환성을 유지합니다. 새 기능은 gulp-mu-gulp-api 0.7.0에 문서화되어 있습니다.
설정 도우미와 AI 레시피
프로젝트 작업 설정은 기존 Gulpfile용 도우미를 대시보드에 엽니다. ESM/CommonJS를 정적으로 분석하고 적절한 설정 필드를 제공하며 적용 전에 모든 변경을 표시합니다. 아홉 AI 레시피는 표시 이름과 설명, 자유 그룹과 프로젝트별 그룹, 단축키, NAS 백업, microCSS, 초기 설정, GitHub/npm 준비를 다룹니다.
- NAS 백업: 프로젝트 식별자, 소스, 여러 대상, 백업 모드, 디렉터리 또는 ZIP, 복사 방법과 제외 항목. 기본값은 모의 실행이며 대상 식별자를 표시해 명시적으로 준비합니다. 설정 자체는 NAS에 접근하지 않습니다.
- microCSS: 기존의 신뢰할 수 있는 매니페스트, 소스와 출력 폴더, 압축, 이미지 미리보기. 빌드마다 새 출력 하위 폴더를 사용합니다.
- 안전한 적용: 전체 파일 미리보기, 소스 해시 확인, 기존 AI 레시피 파일 보호,
.microgulp/setup-backups의 백업, 같은 세션에서 마지막 적용 후 변경이 없는 상태의 되돌리기.
필요한 의존성은 미리보기에 표시되며 이후 해당 AI 레시피 폴더에서 npm install로 설치합니다. 세 가지 새 준비 기능은 별도 AI 레시피 패키지를 요구하지 않습니다. microCSS 매니페스트의 import는 소스 프로젝트에도 해당 패키지가 필요합니다. 실행 중 태스크와 스캔은 변경을 막습니다. 동적 Gulpfile 구성은 수동 수정이 필요할 수 있습니다.
초기 설정과 게시 준비
초기 설정, GitHub 게시, npm 게시 AI 레시피는 기존 Gulpfile에 준비 태스크를 추가합니다. 각 AI 레시피는 프로젝트 이름과 설정 폼을 제공합니다. 태스크는 점검 단계와 명령을 보여 주지만 의존성을 설치하거나 push 또는 게시를 실행하지 않습니다. 도우미의 적용도 게시 승인이 아닙니다.
- 초기 설정 (
project-bootstrap): 패키지 파일, Git 상태, 제외, 의존성, 기존 빌드/테스트 스크립트를 확인합니다. 새 프로젝트는 먼저 빈gulpfile.mjs를 만들고 선택합니다. 없는 패키지 파일은 준비 단계로 안내하며 몰래 생성하지 않습니다. - GitHub (
github-release):Eigentümer/Repository와 공개 범위를 선택합니다. 로그인, remote와 파일 확인, 없는 저장소의 명시적 생성, 검토한 커밋 push, 확인한 태그의 릴리스 초안을 안내합니다. 저장소 생성, push, 게시에는 각각 별도 명시적 요청이 필요합니다. - npm (
npm-release): patch/minor/major와 레지스트리, 접근, 게시 채널을 선택합니다. 버전 증가를 파일 미리보기에 포함하면package.json과 기존package-lock.json/npm-shrinkwrap.json의 새 버전을 보여 줍니다. 적용은 Gulpfile과 함께 백업하고 변경하며 되돌리기는 바이트 단위로 복원합니다. 선택하지 않으면 계획에 아직 할 일로 남습니다.
자동 버전 증가는 1.2.3 같은 안정 버전을 지원합니다. 사전 버전과 workspace 패키지 모음은 프로젝트별 절차가 필요합니다. 비공개 패키지, 충돌하는 lockfile, 다른 게시 설정은 자동 변경을 막습니다. RELEASES.json이 있으면 자동 증가를 해제하고 프로젝트의 버전 동기화를 사용합니다. 다른 자체 버전 소스도 프로젝트별 절차로 관리합니다. 설정에서 이미 올린 버전은 준비 태스크를 시작해도 다시 올리지 않습니다.
미리보기와 태스크 시작은 레지스트리를 조회하지 않습니다. 따라서 npm 계획은 실제 게시 전에 레지스트리 확인, 테스트, 빌드, 패키지 내용 검사와 로그인을 요구합니다. 로컬 버전 증가는 레지스트리에서 사용 가능한 버전임을 입증하지 않습니다. 같은 버전으로 이미 게시한 패키지를 다시 게시할 수 없습니다. npm 게시 · npm 버전 관리 · GitHub 릴리스 초안
프로젝트별 태스크 정리
세 AI 레시피 각각은 프로젝트 이름/Info, 프로젝트 이름/Build, 프로젝트 이름/Tools, 프로젝트 이름/Maintenance 아래 네 준비 태스크를 만듭니다. Info는 현황과 결과 확인, Build는 빌드 준비, Tools는 보조/검증 단계, Maintenance는 설정, 버전, 릴리스 준비입니다. 기본 이름은 SETUP_PROJECT, PREPARE_GITHUB_RELEASE, PREPARE_NPM_RELEASE로 시작하고 대문자 범주를 붙입니다.
**프로젝트별 태스크 그룹 (project-structure)**은 선택한 기존 태스크도 분류합니다. 프로젝트 이름과 태스크마다 네 범주 중 하나를 선택합니다. export 이름과 코드는 유지됩니다. 자유로운 태스크 그룹 AI 레시피와 동시에 적용할 수 없습니다. 분류는 미리보기에 표시되고 백업됩니다.
MCP도 list_recipes, get_recipe, preview_setup, apply_setup, undo_setup으로 같은 폼과 변경을 제공합니다. get_recipe와 list_library는 버전 확인과 게시 승인을 포함한 버전 관리된 에이전트 지침도 제공합니다. 자동 게시하는 별도 AI 스킬은 포함되지 않습니다. 2026년 10월 19일까지 설치된 Cursor와 IntelliJ의 실제 MCP로 프로젝트 시작, GitHub, npm을 추가 검증했습니다. 미리보기, 적용, 읽기 확인, 되돌리기를 수행해 npm 패키지와 lockfile을 포함한 원래 해시를 복원했습니다. 준비 태스크 실행, 레지스트리 조회, 게시는 하지 않았습니다.
MCP를 통한 설정
별도 MCP 어댑터는 list_recipes, get_recipe, list_setup_files, analyze_gulpfile, preview_setup, apply_setup, undo_setup으로 같은 절차를 제공합니다. list_projects, list_tasks, get_task는 프로젝트, 구체적인 IDE 세션과 태스크 목록을 제공합니다. Cursor 같은 MCP Apps 클라이언트는 open_setup_assistant로 채팅에 그래픽 설정을 엽니다. Gulpfile 선택/분석, AI 레시피 선택, 폼 입력, 전체 미리보기 확인을 진행합니다. 적용/되돌리기는 별도 버튼으로 대시보드와 동일한 보호 검사를 사용합니다. Cursor가 도구 실행 승인을 먼저 요청할 수 있습니다. MCP Apps가 없는 클라이언트는 개별 도구를 사용합니다.
Node.js 22 이상과 업데이트된 호스트의 활성 세션이 필요합니다. 별도 SDK 의존성을 npm ci --prefix <Installationsordner>/src/mcp --omit=dev --ignore-scripts로 설치한 뒤 클라이언트는 node <Installationsordner>/src/mcp/microgulp-mcp.mjs --project <absoluter-Projektpfad>를 실행합니다. 변경에는 --setup-write-project <derselbe-Projektpfad>도 필요합니다. 시작 시 이 승인이 없으면 읽기, 분석, 미리보기만 됩니다. 제안은 MCP 프로세스와 IDE 세션별로 구분됩니다. 태스크 시작, 자동 설치, 게시는 이 도구의 기능이 아닙니다.
텍스트 제안 검토와 업데이트 후 MCP 연결
‘프로젝트 작업 설정’을 열고 Gulpfile, 원하는 작업, 편집 언어를 선택합니다. IDE 에이전트가 µGulp™ MCP 서버에 연결된 후에 텍스트 요청을 준비합니다. 표시된 요청을 해당 채팅에 복사합니다. 폼을 열어 두십시오. 요청은 10분 동안 유효하며 현재 프로젝트 엔진에 속합니다.
에이전트의 응답 후 같은 폼에서 ‘제안을 폼으로 불러오기’를 누릅니다. 추가된 이름, 설명, 툴팁, 그룹을 확인합니다. review-required 응답은 제안이 있다는 뜻일 뿐, 품질이나 Gulpfile 변경을 확인하는 것은 아닙니다. 부적절하거나 의미 없는 문구는 수정하거나 제외할 수 있습니다. 에이전트가 작업 이름만으로 알 수 없는 기능을 만들어 내서는 안 됩니다.
이어서 변경 미리 보기를 확인하고 필요하면 백업과 함께 적용합니다. ‘이 변경 되돌리기’는 이후 추가 변경이 없는 경우 백업한 상태를 복원합니다. 채팅에서 직접 준비한 요청은 이미 열린 폼에 자동으로 연결되지 않습니다. 따라서 폼에서 작업하려면 그 폼에 표시된 요청으로 시작합니다. 요청 만료, 언어 변경, 엔진 재시작 후에는 새 요청을 준비합니다.
확장 업데이트 후 설치 폴더가 바뀔 수 있습니다. MCP 설정에서 microgulp-mcp.mjs 경로를 확인하고 새 src/mcp 폴더에 npm ci --omit=dev --ignore-scripts로 별도 SDK 종속성을 설치합니다. 서버가 켜져 있다는 것만으로 연결이 작동한다고 볼 수는 없습니다. Connection closed가 표시되면 서버 로그를 확인하십시오. @modelcontextprotocol/sdk가 없다고 나오면 사용 중인 폴더에 해당 종속성이 없는 것입니다.
MCP 서버를 다시 연결하고 새 에이전트 채팅을 엽니다. list_projects로 현재 세션을 확인합니다. 텍스트 제안에는 prepare_setup_text, get_setup_text, submit_setup_text가 필요합니다. list_projects가 세션 없는 프로젝트를 반환하면 그 프로젝트의 µGulp™ 대시보드를 여십시오. 접근 가능한 MCP 연결과 활성 프로젝트 엔진이 모두 필요합니다.
Cursor의 그래픽 MCP 앱
- 프로젝트를 열고 구성한 µGulp™ MCP 서버를 연결합니다. 서버는 설정, 태스크 접근, 선택적 스킬 도구와 UI 리소스를 제공합니다.
- 에이전트에 “
list_projects로 현재 세션을 확인하고open_setup_assistant를 열어 주세요. 이후 다른 변경은 하지 마세요”라고 요청합니다. 앱이 접혔으면 도구 결과를 펼칩니다. - Gulpfile을 선택하고 Analyze gulpfile을 누릅니다. Cursor가 요구하는 도구 승인은 직접 확인합니다. AI 레시피를 선택하고 NAS 식별자/소스/대상, microCSS 매니페스트/소스/출력, 표시 이름/설명/그룹/단축키를 입력합니다.
- Preview changes에서 전후 화면, 완전한 새 Gulpfile, 펼칠 수 있는 새 AI 레시피 파일을 확인합니다. 패키지와 NAS 식별자 준비도 표시됩니다. 아직 파일은 쓰지 않습니다.
- Apply changes and create backup은 검토한 제안을 적용하고 원본을
.microgulp/setup-backups에 저장합니다. 변경된 소스, 기존 AI 레시피 파일, 실행 중 태스크는 안전하지 않은 적용을 막습니다. - Undo this change는 원본을 바이트 단위로 복원하고 그 적용에서 만든 AI 레시피 파일만 제거합니다. 이후 변경은 되돌리기를 막습니다. 마지막 적용은 동일 MCP 연결과 IDE 세션에서만 되돌릴 수 있습니다.
--setup-write-project가 없으면 분석/미리보기만 가능하고 적용은 숨겨집니다. 화면은 태스크를 시작하거나 패키지를 설치하지 않습니다. 같은 연결의 여러 화면과 에이전트 호출은 마지막 미리보기를 공유하므로 한 번에 하나의 제안을 처리합니다.
Cursor, 호스트, MCP 재시작 후에는 list_projects와 open_setup_assistant를 다시 호출하고 분석합니다. 오래된 화면은 ide-session-unavailable을 반환할 수 있습니다. 미리보기는 10분간 유효합니다. 적용 중 연결이 끊기면 다시 쓰기 전에 파일과 백업을 확인합니다. VSIX 업데이트 후 MCP 설치 경로를 점검하고 필요하면 SDK 의존성을 다시 설치해 연결합니다.
Cursor와 IntelliJ에 MCP 연결
MCP와 스킬은 선택 사항입니다. 일상 사용은 프로젝트를 열고 태스크를 선택해 실행하면 됩니다. 다음 단계에는 업데이트된 µGulp™ 호스트에서 프로젝트가 열려 있어야 합니다. 실제 설치 폴더를 사용합니다. Cursor는 src/mcp, 압축 해제한 JetBrains 플러그인은 microgulp/src/mcp입니다. 앞서 설명한 SDK 의존성을 그곳에 설치합니다.
다음 예제는 두 클라이언트 모두에 적용됩니다. 절대 경로를 실제 경로로 바꿉니다. --setup-write-project는 해당 프로젝트에서만 검토 후 적용과 되돌리기를 허용합니다.
{
"mcpServers": {
"microgulp": {
"command": "C:/Program Files/nodejs/node.exe",
"args": [
"C:/Pfad/zur/Installation/src/mcp/microgulp-mcp.mjs",
"--project", "C:/Projekte/MeinProjekt",
"--setup-write-project", "C:/Projekte/MeinProjekt"
]
}
}
}
- Cursor: 기존 서버를 지우지 말고 프로젝트
.cursor/mcp.json에 추가합니다. MCP 관리에서 활성화하고 연결을 확인합니다. 설정을 변경하면 재연결하고 새 에이전트 채팅을 엽니다. - IntelliJ: **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**에서 Add로 STDIO 연결을 추가하고 JSON을 붙여 Apply로 시작합니다. Tools → AI Assistant → Agents에서 Pass custom MCP servers도 켜고 확인합니다. Pass IntelliJ MCP server는 내장 IDE 서버용으로 이를 대신하지 않습니다. 원하는 에이전트의 새 채팅을 엽니다. 여기서는 ChatGPT 로그인 Codex를 검증했으며 별도 µGulp™ API 키는 필요 없습니다. JetBrains 설정
첫 확인 요청은 “MCP 서버 microgulp의 list_projects를 호출하세요. 리소스 조회와 변경은 하지 마세요”입니다. 실제 응답에서 경로, IDE, 세션을 확인합니다. unknown MCP server나 도구 부재는 아직 채팅이 연결되지 않았다는 뜻입니다. 서버 상태, 전달 설정, 새 채팅을 확인합니다. 리소스 조회 성공은 도구 검사를 대체하지 않습니다. 반환된 projectId와 sessionId를 쓰고 오래된 ID는 쓰지 않습니다.
기존 에이전트를 사용하는 스킬
버전 관리된 라이브러리는 list_library로 조회합니다. .microgulp/agent-profiles.json의 프로필이 허용 입력과 스킬 버전을 지정합니다. 기본 execution: "client"는 기존 IDE 에이전트를 사용합니다. 별도 skillGrants는 명시적 API 모드에서만 필요하며 빈 목록은 일반 클라이언트 절차를 막지 않습니다. start_api_skill은 연결 없는 에이전트의 자동 대체 수단이 아닙니다.
번역 프로필 예입니다. 세 JSON 파일은 프로젝트에 이미 있어야 합니다.
{
"schemaVersion": 1,
"profiles": {
"texte-de": {
"enabled": true,
"skill": "localization",
"version": "1.1.0",
"execution": "client",
"configuration": {
"source": "i18x/source.json",
"target": "i18x/de-DE.json",
"baseline": "i18x/source-baseline.json",
"sourceLanguage": "en-US",
"language": "de-DE"
}
}
}
}
inspect_skill_profile은 현재 프로필 해시를 제공합니다.start_skill에는 프로필 ID, 해시, 새 고유requestId를 전달합니다. 준비된 작업은 30분 유효합니다.- 에이전트가 항목을 처리하고 결과, 작업 ID, 변경 없는
digest를submit_skill_result에 보냅니다..microgulp/proposals/<id>/proposal.json에 제안을 저장하고 번역 파일은 바꾸지 않습니다. - 대상 경로, 변경 텍스트, 유지된 자리표시자와 변경 없는 항목을 확인합니다. 이후에만 제안 ID로
apply_skill_proposal을 승인합니다. µGulp™가 소스를 다시 확인하고.microgulp/proposals/<id>/original.json에 원본을 백업합니다. - 실제 파일을 확인합니다.
undo_skill_proposal은 이후 파일이 변하지 않고 동일 MCP 연결과 호스트 세션이 유지될 때 같은 ID로 되돌립니다. 인수 검증은 시작 전과 되돌린 후 해시를 비교합니다.
간단한 요청은 “기존 에이전트로 texte-de 프로필을 사용하고 MCP로 제출해 미리보기를 보여 주세요. 적용 전에 멈추고 파일을 직접 수정하지 마세요”입니다. 적용과 되돌리기는 이후 명시적으로 요청합니다. skill-expired면 다시 준비하고, unknown-skill-run이나 unknown-undo면 먼저 세션, 파일, 백업을 확인합니다. 무작정 반복하거나 직접 쓰기로 대체하지 않습니다.
근거 있는 미리보기로 설명서 유지보수
skill: "handbook-maintenance", 버전 1.1.0, execution: "client" 프로필은 configuration에 프로젝트의 임의 이름 DOCX를 master, 언어를 sourceLanguage, 구현 파일을 files, 완전한 기존 Git 커밋을 baselineCommit으로 지정합니다. outputLanguage는 제안 언어를 선택하며 없으면 소스 언어입니다. chapters는 장을 한정하고 editorialRules는 선택적인 프로젝트 편집 규칙입니다. 커밋은 열린 프로젝트에서 읽을 수 있어야 합니다. PDF나 Markdown은 현재 처리하지 않습니다.
submit_skill_result까지는 번역과 같습니다. 미리보기에는 파일/행 근거와 editorial-review-required가 있습니다. DOCX 자동 적용은 없습니다. apply_skill_proposal은 handbook-report-requires-editorial-work로 거부합니다. 편집은 설정한 DOCX에서 별도로 합니다. 비교 기준, 번역, 완성 출력은 갱신하지 않습니다. “독일어 .src. 먼저, 이후 차이만 번역”은 우리 µGulp™ 프로젝트 프로필만의 규칙이며 고객은 자신의 절차를 정합니다.
고객 설명서 예
소스 이름은 docs/Customer Guide.docx처럼 자유롭습니다. 이 프로필은 영어 소스와 프랑스어 제안을 사용합니다. 자리표시자를 프로젝트의 실제 완전한 Git 커밋으로 바꿉니다.
{
"enabled": true,
"skill": "handbook-maintenance",
"version": "1.1.0",
"execution": "client",
"configuration": {
"master": "docs/Customer Guide.docx",
"sourceLanguage": "en-US",
"outputLanguage": "fr-CA",
"files": ["src/build.mjs"],
"baselineCommit": "<vollständiger Git-Commit>",
"editorialRules": "Kundenterminologie erhalten und bestehende Kapitelstruktur beachten."
}
}
이 항목을 .microgulp/agent-profiles.json의 profiles에 고유 이름으로 넣습니다. de-DE, en, fr-CA, zh-Hant 같은 식별자는 검증하지만 결과의 언어 품질을 자동 인증하지는 않습니다. 번역 소스와 대상은 달라야 하며 문자열의 평면 JSON 사전만 지원합니다. Markdown이나 DOCX의 범용 번역이 아닙니다.
기존 스킬 프로필 갱신
1.0.0 프로필은 번역과 설명서에서 계속 실행됩니다. 파일과 해시는 자동 변경하지 않습니다. sourceLanguage가 없는 기존 번역은 미정(und)이며 에이전트가 텍스트에서 판단합니다. 기존 설명서 프로필은 미지정 시 de-DE입니다. 명시적 설정이 우선합니다. 새 고객 프로필은 1.1.0에서 소스와 언어를 선택하며 프로젝트 규칙은 프로필에만 둡니다. 영구 전환은 백업, 버전/언어 확인, 새 작업 준비 순서입니다. 알 수 없는 버전이나 잘못된 개별 프로필은 실행 불가로 표시하지만 정상 이웃을 막지 않습니다. 전체 프로필 파일이 잘못되면 거부합니다. 라이브러리 pin과 무결성 값은 자동 갱신하지 않습니다. 미리보기, 자리표시자 보호, 백업, 되돌리기와 DOCX 금지는 기존 프로필에도 적용됩니다.
IntelliJ 대시보드 연결 복구
프로젝트 엔진이 종료되면 열린 µGulp™ 창이 감지하고 Reconnect dashboard를 제공합니다. 창을 숨겼다 열면 종료로 감지된 엔진을 시작합니다. 실행 중 엔진은 재시작하지 않고 태스크도 반복하지 않습니다. 시작 오류는 메시지와 재시도 선택을 표시하며 자동 반복하지 않습니다. 준비 알림이 없으면 최대 120초 후 중단합니다. Node 경로와 프로젝트 설정을 확인한 후 Reconnect dashboard를 선택합니다. 다시 list_projects를 호출하고 새 세션을 선택합니다. 과거 제안/되돌리기 ID를 재사용하지 말고 새 변경 전에 기존 백업을 확인합니다. MCP의 녹색 상태만으로 활성 대시보드 세션을 입증할 수 없습니다.
검증한 절차와 승인
스킬 1.1.0 고객 프로필은 2026년 10월 19일까지 설치된 Cursor/IntelliJ의 MCP에서 검증했습니다. en-GB에서 fr-CA로, 자리표시자 유지 미리보기, 적용, 바이트 단위 되돌리기입니다. DOCX 소스와 보고 언어는 자유롭게 골랐고 자동 적용은 handbook-report-requires-editorial-work로 거부되어 해시가 유지되었습니다. 1.0.0 호환성도 이후 IntelliJ에서 확인했습니다. 통제된 절차의 증거이며 임의 에이전트 결과의 언어 품질 보장은 아닙니다.
2026년 10월 19일 IntelliJ에서 엔진 종료 후 Reconnect dashboard를 확인했습니다. 새 세션에 MCP로 접근했고 기존 프로필 검증도 통과했습니다. 번역은 적용 후 바이트 단위로 복원했고 설명서 자동 적용은 서버가 거부해 DOCX가 유지되었습니다. 해당 재연결 사례를 입증하며 임의 실행 중 태스크나 오래된 ID 복원은 아닙니다.
마지막 Windows/Node.js 22 로컬 검증은 1115 성공, 실패 없음, 명시적 플랫폼/장치 건너뛰기 네 건입니다. 추가 MCP/웹사이트 31건도 성공했습니다. 업데이트한 VS Code, Cursor Internal, Free를 설치해 대시보드 태스크 성공을 확인했습니다. JetBrains Plugin Verifier는 테스트한 242/261/262와 호환됨을 확인했고 지적된 구식 API 호출 두 건을 제거했습니다. 수정 패키지를 Windows의 IntelliJ IDEA 2026.2.2에 설치해 확인했습니다. 미리 채운 경로 확인, 선택 취소, 로그 열기, 최초 전체 표시, 숨기기/다시 열기, 최대화/복원, 창 크기 변경입니다. 다른 DPI 모니터 간 이동은 미검증입니다. 이전 네이티브 MCP 검증은 해당 패키지 버전에 귀속됩니다. 새로운 다중 플랫폼 CI나 남은 실물 하드웨어 검사를 대체하지 않습니다.
2026년 10월 17-19일 Windows의 로컬 2.0.0 패키지를 실제 Cursor 에이전트와 IntelliJ AI 채팅 Codex로 확인했습니다. 번역 미리보기, 적용, 읽기, 바이트 단위 되돌리기와 근거 있는 설명서 미리보기, DOCX 자동 적용 거부, 불변 해시를 포함합니다. 그래픽 MCP 앱은 Cursor에서 검증했으며 IntelliJ의 그래픽 앱 인수는 아닙니다. 다른 에이전트와 OS는 포함하지 않습니다.
첫 Cursor 실행은 unknown-undo였고 원인은 미해결입니다. 다음 전체 실행은 성공했습니다. 오류 시 세션과 백업을 반드시 확인해야 합니다. Guardian 같은 클라이언트 승인 검토의 거부는 µGulp™ 도구 응답이나 통과한 거부 테스트가 아닙니다. 승인을 우회하지 말고 추가 시도에는 명시적인 추가 승인을 받습니다. DOCX 거부 테스트에는 실제 µGulp™ 오류와 이후 읽은 불변 해시가 필요합니다.
스냅샷
| 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(오름차순 정수). 그룹은 하위 트리 최소 순서. 순서 없는 태스크는 마지막(알파벳) |
Task를 클릭하면 사용 가능한 웜 워커가 Gulpfile을 다시 가져오지 않고 실행을 맡습니다. Gulpfile을 저장하면 Task 목록이 자동으로 갱신됩니다. 여러 Task를 병렬로 실행할 수 있으며 각 Task가 ReportProgress를 gulp-mu-gulp-api에서 호출하면 자체 대시보드 섹션에 네온 진행 막대가 표시됩니다.
Gulp CLI 계속 사용
추가 메타데이터는 CLI 호출 방식을 바꾸지 않습니다. 기존 빌드는 일반 gulp와 CI에서 계속 실행할 수 있습니다. 가져온 패키지는 필요하며 입력과 호스트 의존 작업은 그 경로에 맞아야 합니다. 통합 후 기존 CLI 호출을 확인합니다.
대시보드 없는 동작
| 추가하는 것 | 평범한 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/ |
사용에 따라 AI 레시피 코드, 프로필, 설정, 백업도 포함합니다. 무조건 삭제하지 마세요. 가져온 코드는 CLI에도 필요할 수 있습니다. 프로젝트 파일을 선택해 버전 관리하고 로컬 로그, 자격 증명, 백업은 제외합니다 |
gulp-mu-gulp-api는 런타임 의존성 없는 일반 npm 패키지이며 IsMicroGulp()는 오케스트레이션 여부를 알려 줍니다. 확장을 제거해도 필요한 패키지와 AI 레시피 파일은 유지합니다. 호스트 의존 동작에는 적절한 대체 경로가 필요합니다.
버전 요구사항 확인
일반 Gulp CLI는 추가 메타데이터를 무시하지만 모든 호스트/Gulp/API 버전 호환성을 보장하지 않습니다. 새 API는 새 패키지, IDE 동작은 호스트 기능을 요구할 수 있습니다. 버전 조건을 지키고 업데이트 후 기존 호출을 확인합니다.
동료는 터미널에서 npx gulp BUILD를 실행하고 사용자는 대시보드를 이용할 수 있습니다. 두 경로가 같은 파일을 사용하므로 동시 쓰기는 프로젝트에서 조율합니다.
설치
µGulp™는 지금 사용할 수 있습니다. 공개 목록에서 설치하십시오:
| 에디션 | 설치 |
|---|---|
| µGulp™(VS Code / Cursor) | VS Code용 설치 · Open VSX에서 설치 |
| µGulp™ Free(VS Code / Cursor) | µGulp Free 설치 · Open VSX에서 설치 |
| µGulp™(JetBrains IDEs) | JetBrains용 설치 |
소스 저장소는 비공개로 남습니다. 등록된 VS Code/Cursor 에디션과 µGulp™ Free를 나란히 설치하지 마십시오 - 같은 명령 ID를 공유합니다.
그다음 명령 팔레트에서 µGulp: Open Dashboard를 실행(또는 상태 표시줄의 µGulp™ 로켓을 클릭).
JetBrains IDE
JetBrains 플러그인은 플랫폼 플러그인(com.intellij.modules.platform)이며 IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, Rider, CLion, GoLand, RubyMine, DataGrip 및 기타 IntelliJ 계열 IDE에 설치됩니다. JetBrains용 설치는 Marketplace에서. 목록은 호환성별 두 빌드를 제공하고 IDE는 맞는 쪽을 받습니다(Help → About):
| IDE build | since-build |
Marketplace |
|---|---|---|
2024.2 - 2026.1(261.*까지) |
242 |
JetBrains용 설치 |
| 2026.2 이상 | 262 |
JetBrains용 설치 |
Marketplace가 맞는 빌드를 고릅니다. IntelliJ IDEA, PhpStorm, WebStorm 및 기타 IntelliJ 계열 IDE는 이 두 변형을 공유합니다 - 제품명이 아니라 플랫폼 빌드로 결정됩니다. 각 변형 디스크립터에
<idea-version since-build="…"/>가 있어 IDE는 다른 쪽을 로드하지 않습니다. 2024.2-2026.1은since-build="242"/until-build="261.*". 2026.2+는since-build="262"이며 상한 없음. 플랫폼 빌드는 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) 플러그인으로 옮겼으므로 디스크립터가 명시적으로 선언해야 합니다 - 그래서 별도 Marketplace 변형입니다. JetBrains Marketplace(Settings → Plugins → Marketplace에서 MicroGulp 검색)로 설치하고 µ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/를 엽니다.
오프라인 패키지
이 파일들은 소스 저장소의 로컬 checkout에만 있습니다. 공개 설치 경로가 아닙니다.
로컬 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/에 들어갑니다.
로컬 빌드의 JetBrains zip:
| IDE build | 패키지 |
|---|---|
2024.2 - 2026.1(261.*까지) |
packages/microgulp-jetbrains_latest.zip |
| 2026.2 이상 | packages/microgulp-jetbrains-2026.2_latest.zip |
로컬 zip은 *Settings → Plugins → ⚙ → Install Plugin from Disk…*로 넣습니다.
구성 파일 microgulp.config.json(JetBrains와 CLI)
VS Code / Cursor에서 엔진은 확장 설정(microgulp.gulpfilePattern 등)으로 구성됩니다. JetBrains 플러그인은 같은 엔진 옵션을 Settings → Tools → µGulp에 반영하고, 다음 도구 창 열 때 사이드카 CLI 플래그로 넘깁니다. 선택적으로 프로젝트 루트 **microgulp.config.json**이 팀 기본값과 IDE 페이지에 없는 키(dashboardFonts, metadataWatchFiles, versionSources, project)를 여전히 공급합니다. CLI 플래그가 없을 때 microgulp-serve의 일반 CLI/브라우저 사용은 파일을 읽습니다:
{
"gulpfilePattern": "gulpfile.*\\.mjs$",
"poolSize": 2,
"maxParallel": 6,
"preload": true,
"watchGulpfiles": true
}
| Key | Type | Default | Meaning |
|---|---|---|---|
gulpfile |
string | - | 프로젝트 루트 기준의 단일 gulpfile. 루트 밖의 경로는 허용하지 않음 |
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. |
project |
object | - | 선택. 작업 목록용 프로젝트 식별: title, description, logo(SVG/PNG/WebP, 프로젝트 루트 상대). 값이 없으면 추가 헤더 없음. |
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를 재시작하십시오. gulpfile 감시가 켜져 있으면 project(제목, 설명, 로고) 변경이 IDE 재시작 없이 반영됩니다.
프로젝트 식별 (project)
작업 목록 위에 선택적 컴팩트 헤더를 두어, IDE 창이 여러 개일 때 작업이 어느 워크스페이스인지 바로 구분합니다:
{
"project": {
"title": "ESP][",
"description": "Apple II emulator for ESP32-S3",
"logo": "./assets/esp2.svg"
}
}
- 세 필드 모두 선택 사항입니다. 메타데이터가 없으면 기존 레이아웃이 유지됩니다.
logo: 프로젝트 루트 기준 상대 경로. 형식 SVG, PNG, WebP. 없거나 잘못된 파일은 무시(로고 없는 헤더).- 헤더 툴팁: 제목, 설명(있으면), 워크스페이스 절대 경로.
- 프로젝트 식별 정보는 대시보드 작업 목록과 Web Console에 표시됩니다. Stream Deck 그룹 브라우저의 Root 키는 로고 비율을 유지하고 제목을 별도 띠에 표시합니다. 사용할 수 없는 로고에는 대체 표시를 사용합니다. Logitech MX는 연결 호스트의 프로젝트 이미지를 workspace 선택과 µGulp™ 키에 사용하고 없으면 브랜드 이미지를 표시합니다. 전체 장치 인수 검증은 아직 완료되지 않았으며 Flexbar의 프로젝트 로고 표시도 약속하지 않습니다.
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™는 단일 경로 또는 전체 workspace를 검색하는 정규식 패턴으로 gulpfile을 찾습니다. 선택은 프로젝트에 속하며 VS Code, Cursor, JetBrains, CLI에서 동일합니다.
- 명시적인 IDE/CLI 재정의: VS Code/Cursor 설정, JetBrains Settings → Tools → µGulp 또는
microgulp-serve --gulpfile/--gulpfile-pattern. 빈 필드는 재정의가 아닙니다. - 루트의
microgulp.config.json(gulpfile또는gulpfilePattern). - 기본값: 루트의
gulpfile.mjs. 없으면(^|/)gulpfile\.(m|c)?js$로 검색합니다.
각 단계에서 패턴이 단일 경로보다 우선합니다. 루트 밖 경로는 거부하고 파일이 없으면 경고와 함께 다음 단계로 넘어갑니다.
microgulp.gulpfilePattern- 워크스페이스 상대 경로(/POSIX 표기)에 대한 JavaScript 정규식(대소문자 무시). 설정되면 일치하는 모든 파일을 스캔하고 태스크는 대시보드에서 소스별로 묶입니다. 예:(^|/)gulpfile\.(m|c)?js$는 루트와 각 하위 폴더의gulpfile.mjs/.js/.cjs를 찾습니다.microgulp.gulpfilePath- 명시적인 단일 경로. 기본값은 비어 있어microgulp.config.json이 적용됩니다.
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, file, folder |
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, accept |
numeric / textarea details; accept on file is .zip,.json |
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)는 일방 프로세스에서 폼을 보여줄 수 없어 선언 기본값보다 기억된 값으로 실행됩니다.
긴 옵션 목록(select / radio / checkbox)을 지원합니다. 호스트는 기본적으로 필드당 5000개 항목을 유지합니다(MICROGULP_MAX_SELECT_OPTIONS로 변경, 0은 무제한). 줄이면 대시보드에 경고를 표시하며 조용히 잘라 내지 않습니다. 24개부터 필터가 나타납니다. gulp-mu-gulp-api의 임시 RequestForm은 실시간 데이터에 호스트 제한을 적용하지 않으며 같은 필드 유형과 필터를 사용합니다.
워치 / 트리거 태스크 (µ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.µShortDisplayName = 'CSS, Build Styles<context="µShortDisplayName"/>'.i18xRegister(); // Optionaler Kurztext für Stream Deck und Logitech MX
BUILD_STYLES.µDescription = 'Compiles the µCSS skin into deploy-ready stylesheets.<context="µDescription"/>'.i18xRegister();
BUILD_STYLES.µGroup = 'Build/Assets<context="µGroup"/>'.i18xRegister();
µShortDisplayName은 짧은 하드웨어 표시용 선택적 i18x 문구입니다. 대시보드 표시 이름이나 태스크 ID를 바꾸지 않습니다. 필요하면 CSS, Build Styles처럼 “짧은 문구, 원래 문구”를 넣을 수 있습니다. µShortDisplayName 문맥 태그는 i18x 소스에만 넣고 호스트가 출력 전에 제거합니다. 장치에는 태그가 표시되지 않습니다.
컨텍스트 태그, 필수 형식, 마켓플레이스 언어 계획: dev/docs/MicroGulpI18xProfile.md.
Gulpfile에서 Task 표시 및 제어
µGulp™는 각 Task가 비활성 또는 사용 중지 상태인지, 시작 또는 실행 중인지, 입력을 기다리는지, 중지 중인지, 성공적으로 끝났는지 또는 실패했는지 표시합니다. 사용자 지정 아이콘을 사용해도 상태 테두리는 보입니다. 입력 대기 중에는 보라색 대화상자 기호가 추가되며 대시보드에서 응답할 수 있습니다.
의미 기반 표시에 SVG 아이콘 38종을 사용할 수 있습니다. µTaskKind와 µPresentation은 빌드, 테스트, 복사 또는 게시처럼 작업의 성격을 나타냅니다. 아이콘은 테마를 따르고 테마에서 교체할 수 있으며 동작 줄이기를 지원합니다. 실행 애니메이션은 작업 중임을 보여주고, 오류가 발생하면 원래 그림이 그을린 모양으로 바뀝니다. 사용자 지정 µIcon 및 µIconFont 설정은 유지됩니다.
지속 실행 서비스는 µExecutionType = 'persistent'로 표시하며 다시 중지할 수 있습니다. 이는 파일 변경 시 Task를 다시 실행하는 µWatch 및 조치 필요 상태를 표시하는 µAttention과 별개입니다. µAttentionWatch를 사용하면 Task를 실행하지 않고 파일 변경 후 또는 일정 간격으로 알림 상태를 다시 확인할 수 있습니다.
Gulp Task에서 Task 개요 화면도 제어할 수 있습니다:
import { SetGroupState, RevealTask, SetTaskEmphasis } from 'gulp-mu-gulp-api';
SetGroupState('Build', 'open');
RevealTask('PUBLISH_NPM', { expand: true, scroll: true, highlight: 'attention' });
SetTaskEmphasis('PUBLISH_NPM', null);
µGroups가 초기 상태를 정하며 이후 그룹 변경은 세션에 적용됩니다. 강조 표시와 실행 상태는 서로 독립적이므로 실행 중인 Task에 조치 필요 표시를 함께 나타낼 수 있습니다. 대시보드와 하드웨어에는 같은 Task 상태가 전달됩니다. 대시보드에서 그룹을 여는 동작은 그 그룹의 Task를 시작하지 않습니다.
Task에서 IDE 작업 실행
Gulp 작업은 gulp-mu-gulp-api에서 Ide를 가져옵니다. 구현된 1.0.0 범위는 다음 함수 8개입니다.
| 함수 | 용도 |
|---|---|
Ide.Capabilities() |
호스트 계열, 에디션, 지원 작업과 의미 기반 작업 조회. 실행 함수가 잠겨 있어도 사용 가능 |
Ide.Projects() |
알려진 프로젝트, 활성 세션, 설정된 앱 선택지 조회 |
Ide.Action(id) |
현재 IDE 호스트에서 의미 기반 작업 실행 |
Ide.OpenProject(request) |
선택한 설치에서 알려진 프로젝트를 열거나 해당 세션에 포커스 |
Ide.StartApplication(applicationId) |
알려진 또는 명시적으로 설정된 로컬 앱 시작 |
Ide.Execute({ vscode, jetbrains, args }) |
현재 호스트 계열에 지정한 네이티브 명령 실행 |
Ide.Vscode.ExecuteCommand(commandId, ...args) |
허용된 VS Code/Cursor 명령 실행 |
Ide.JetBrains.ExecuteAction(actionId) |
허용된 JetBrains 작업 실행 |
Ide.Action 공통 카탈로그는 open-settings, save-all, open-terminal, open-problems, find-in-project, quick-open, command-palette, next-editor, previous-editor, run, debug를 포함합니다. Run/Debug는 현재 네이티브 구성을 사용합니다. 사용 가능 여부는 IDE, 설치된 플러그인, 허용 명령에 따라 달라지며 모든 JetBrains 제품의 동일한 기능을 보장하지 않습니다.
Ide.OpenProject는 Ide.Projects().result.projects의 projectId와 반환된 앱 선택지의 applicationId 등을 사용합니다. 특정 세션에는 sessionId와 connectionId가 모두 필요합니다. 오래된 대상은 거부하며 다른 세션으로 대체하지 않습니다.
µHost는 필요한 IDE 계열을 표시하고 µIdeApi = true는 이 인터페이스가 필요한 작업을 표시합니다. 엔진은 에디션, 등록, 허용 명령을 확인합니다. µGulp™ Free에서 Ide.Capabilities() 조회는 가능하지만 Ide.Projects()를 포함한 나머지 7개 함수는 잠겨 있습니다. Web Console의 읽을 수 있는 프로젝트 목록은 별도로 제공됩니다.
호출은 { ok, result } 또는 { ok: false, code, message }의 Promise를 반환합니다. 일반 gulp CLI처럼 µGulp™ IPC가 없으면 8개 모두 unsupported-host를 반환하고 IDE를 실행하지 않습니다. 에디션 또는 등록 권한이 없으면 unsupported-edition 또는 unsupported-registration을 반환합니다. CLI와 CI용 대체 경로는 gulpfile에서 제공할 수 있습니다.
이 범위는 저장소 구현을 설명하며 이미 게시된 npm 버전의 제공 여부를 뜻하지 않습니다. Ide.OpenUrl은 계획 단계이며 사용할 수 없습니다.
하드웨어 통합
Elgato Stream Deck 및 Stream Deck Mobile, Logitech MX Creative Console 및 Actions Ring, ENIAC Flexbar로 Task를 제어할 수 있습니다. 하드웨어 기능은 µGulp™ Free를 제외한 모든 버전에 포함됩니다. JetBrains용 Free 버전은 없습니다.
µGulp™는 키에 정적 아이콘만 표시하지 않습니다. Live Animated Task States는 대시보드와 같은 엔진의 실제 실행 상태(inactive → starting → running → finished 또는 failed, 그리고 disabled, waiting-for-input, stopping)에 따라 표시가 바뀐다는 뜻입니다. 시작, 실행, 중지 또는 입력 대기 중에는 애니메이션이 작동하고 성공과 오류는 잠시 표시됩니다(오류는 Burn→Charred 포함). µWatch는 별도 켜기/끄기 오버레이이며 세션 스케줄은 키에 카운트다운 또는 n/m을 추가할 수 있습니다. (Actions Ring: 제목만 표시하며 SDK가 LCD 애니메이션을 지원하지 않음) 사양 및 상태 목록: TaskPresentationAndHardware.md.
대시보드의 설정 → Hardware integrations에서 Workspace 연결을 활성화합니다. 해당 기기 플러그인이 키를 프로젝트 Task에 연결합니다. 실행 중인 서비스는 중지할 수 있고 입력 요청은 대시보드에서 응답할 수 있습니다.
컨텍스트를 반영하는 컨트롤러 화면
µGulp™는 Visual Studio Code, Cursor, JetBrains에 공통인 활성 프로젝트 컨텍스트를 사용합니다. Stream Deck은 workspace와 장치별 마지막 보기를 복원합니다. Logitech은 기존 동적 workspace 선택을 유지하며 폴더는 프로세스 전체에서 공유합니다. Flexbar는 IDE 프로젝트를 자동으로 따르지 않습니다.
활성 프로젝트는 공통이고 Stream Deck 보기는 장치별로 저장됩니다. 다른 앱이 전면에 오면 µGulp™는 자신이 연 브라우저 프로필을 Stream Deck에 돌려줍니다. 이후 기본 또는 Smart Profile이 표시되는지는 Elgato와 사용자 설정에 달려 있으며 자동 전환을 보장하지 않습니다.
예:
Cursor: microGulp
MX -> Build
Stream Deck -> Release
Alt-Tab
JetBrains: BlueShift
MX -> Build
Stream Deck -> Test
Alt-Tab
VS Code: ESP][
MX -> Upload
Stream Deck -> Monitor
IDE 창으로 돌아오면 해당 workspace의 이전 Stream Deck 보기를 복원합니다. 장치별 보기는 따로 저장하며 여러 Stream Deck 실물 검증은 아직 남아 있습니다.
gulpfile 변경 후 그룹이 없어지면 가장 가까운 유효 부모 또는 프로젝트 루트를 복원합니다. Follow active IDE project는 기본적으로 켜져 있습니다. Logitech keypad에서 수동으로 선택한 workspace가 우선합니다. 기술적 한계: 활성 IDE 프로젝트 따르기.
Elgato Stream Deck 및 Stream Deck Mobile
Follow 및 프로필: Follow active IDE project를 켜면 µGulp™는 하드웨어 연결이 가능한 포커스된 IDE 프로젝트를 선택하고 포함된 브라우저 프로필을 열 수 있습니다. 이미 표시 중이면 프로젝트 내용만 바뀝니다. IDE 컨텍스트를 떠나면 µGulp™가 연 프로필을 돌려줍니다. Elgato Smart Profiles는 Stream Deck에서 추가 설정할 수 있지만 µGulp™는 활성화를 보장하지 않습니다. 자세한 내용: Stream Deck.
그룹 브라우저: 다른 프로필(예: Default)의 Open µGulp Group은 동적 그룹과 작업을 표시하며 설정된 시작 그룹을 엽니다. 반면 Follow와 진입점으로 쓰는 µGulp Group Slot 키는 활성 workspace의 저장된 보기를 복원하고, 저장이 없는 새 세션은 루트에서 시작합니다. 페이지, 뒤로, Root는 탐색 격자를 따릅니다. Root는 로고 비율을 유지하고 제목을 별도 띠에 표시하며 사용할 수 없는 로고에는 대체 표시를 씁니다. 루트에서 뒤로 누르면 종료합니다. Stream Deck Mobile은 3×2, 5×3 등 격자 크기로 템플릿을 선택합니다.
고정 단일 Task 할당: µGulp Task를 키에 끌어다 놓고 Workspace와 Task를 선택할 수도 있습니다. 이름, 실행 애니메이션 상태 및 아이콘은 연결된 Workspace에서 가져옵니다. Stream Deck Mobile도 같은 통합 기능을 사용합니다.
기술 세부 정보와 템플릿 목록: Stream Deck, 사양 Device 그룹 탐색.
Logitech: 개별 Task 또는 앱 프로필
Logitech 설정에는 두 가지 방법이 있습니다:
- Task를 각각 따로 할당: Start a Single µGulp Task를 사용해 Workspace와 Task 하나를 키에 고정합니다. 개별 키패드 키와 Actions Ring에서 사용할 수 있습니다(Actions Ring은 제목만 표시하며 SDK가 LCD 애니메이션을 지원하지 않음). 키패드 폴더에는 아이콘과 실행 상태가 표시됩니다.
- Options+에서 앱 프로필 설정, 예를 들어 Cursor: 앱에 포커스가 있을 때 설정한 키 배치가 자동으로 활성화됩니다. 키패드에서 General µGulp Functions를 열면 해당 Workspace의 Task와 아이콘, Live 실행 표시가 나타납니다. µGulp™ 플러그인은 IDE에서 포커스된 Workspace를 따릅니다. 수동 Workspace 선택은 선택을 해제하거나 연결이 끊길 때까지 유지됩니다.
즉, Options+는 앱의 키 배치를 선택하고 µGulp™는 Workspace를 선택합니다. Options+ 프로필은 한 번 설정하면 됩니다. 앱을 전환한 뒤 동적 폴더가 닫힐 수 있으며 µGulp™ 키를 누르면 다시 열립니다. Actions Ring은 고정 단일 Task 할당을 사용하고 Task 아이콘이 있는 동적 목록은 키패드에서 사용합니다.
Logitech MX는 연결 호스트의 프로젝트 이미지를 workspace 선택과 µGulp™ 키에 사용하고 없으면 브랜드 이미지를 표시합니다. 전체 장치 인수 검증은 아직 완료되지 않았습니다. Dynamic Folder를 프로그램으로 열기와 여러 실물 MX 장치의 독립 탐색은 보장하지 않으며 SDK 문제는 미해결입니다. 기존 Logitech 지원은 제한적이고 실험적입니다.
ENIAC Flexbar
Flexbar 플러그인은 FlexDesigner에서 설정한 작업을 µGulp™ Task와 연결하고 실행 상태도 표시합니다(Stream Deck과 같은 상태 의미). 실제 Flexbar 하드웨어 테스트는 아직 진행되지 않았습니다.
기술 설정 및 플러그인 빌드: Stream Deck, Logitech, Flexbar.
Task 스케줄러 (세션)
세션 스케줄은 Task를 시작할 시점만 정합니다. 실행은 일반 StartTask 경로를 따르며 대시보드 섹터, 로그 및 하드웨어 상태는 그대로 유지됩니다.
| 모드 | 선언 | 설명 |
|---|---|---|
| 타이머 | µSchedule = { after: '10s' } |
지정 시간 후 한 번 실행 |
| 간격 | { every: '10s' } |
반복 실행; 매 실행 후 nextRun 갱신 |
| 반복 횟수 | { every: '5s', repeat: 5 } |
n회 실행 후 completed 상태 |
| Cron | { cron: '*/1 * * * *' } |
5개 필드, 호스트 현지 시간 (croner) |
명령형 API: ScheduleTask, SetScheduleEnabled, CancelSchedule, RunScheduleNow (gulp-mu-gulp-api). 대시보드: nextRun 기반 카운트다운, Enable/Disable/Cancel/Run now. µWatch가 활성화되어 있거나 Task가 실행 중이면 예약 시작을 건너뜁니다(schedule-skipped). 하드웨어 키에는 카운트다운 또는 n/m 오버레이가 표시될 수 있습니다. 자세한 내용과 데모 A-G: TaskScheduler.md.
컨트롤러, 게임패드 및 조이스틱
게임패드, 조이스틱 및 기타 호환 입력 장치를 자유롭게 매핑해 워크플로 제어기로 사용할 수 있습니다. 설정 → Controllers에서 지원을 켜고 프로필, 버튼 및 축 입력 학습, 데드존, 감도 및 실시간 진단을 설정하세요. 매핑을 통해 Task를 시작하거나 중지하고 Task 개요를 조작할 수 있습니다.
Windows x64에서는 대시보드에 포커스가 없어도 입력을 감지합니다. 이를 위해 Node.js 22 이상이 설치되어 있어야 합니다. 다른 데스크톱 플랫폼에는 네이티브 컨트롤러 구성 요소가 아직 포함되지 않았습니다. 지원되는 브라우저에서는 대안으로 Gamepad API를 사용할 수 있습니다.
3Dconnexion SpaceMouse Wireless에는 기기에서 측정한 6축 및 2버튼 프로필이 제공됩니다. 다른 기기는 보정하고 직접 매핑해 설정할 수 있습니다. 컨트롤러가 진동을 지원하면 Task 시작, 성공 또는 오류를 선택적으로 알릴 수 있습니다. 지원 범위와 동작은 기기에 따라 다릅니다.
설정, 기기 프로필 및 진단: 컨트롤러 문서.
AI 지원 gulpfile 마이그레이션
기존 대형 gulpfile(콘솔 출력, 태스크 메타데이터, i18x/gulp 사전, 선택 µKeyBinding / µParameters / µWatch / µAutoClose, 그리고 선택 프로젝트 식별(microgulp.config.json)을 이전하려면 저장소의 유지 프롬프트를 쓰십시오:
| File | Purpose |
|---|---|
dev/prompts/OptimizeGulpfileForMicroGulp.md |
Cursor, Claude, ChatGPT용 복사-붙여넣기 프롬프트(첫 마이그레이션) |
dev/prompts/OptimizeGulpfileForMicroGulp.params.example.json |
Parameter template (project path, gulpfile name, supported languages, gulp-mu-gulp-api version) |
dev/prompts/EnhanceExistingMicroGulpProject.md |
기존 µGulp™ 프로젝트에서 선택적인 새 기능 검토(무조건 활성화하지 않음) |
마이그레이션 프롬프트는 이제 µTaskKind, µPresentation, µExecutionType, µAttentionWatch 입력 대기 및 합리적인 project 식별(제목 / 짧은 설명 / 기존 로고, 설정은 병합만)도 고려합니다. 기존 µIcon 글리프와 µIconFont 연결은 보존됩니다. Core가 실행 상태를 관리하며 지속 서비스, 파일 트리거 및 주의 표시는 서로 구분됩니다. 하드웨어 통합은 Workspace마다 활성화하며 µGulp™ Free를 제외한 모든 버전에 포함됩니다. Flexbar는 실제 하드웨어 테스트가 남아 있습니다. 마이그레이션 전에 필요한 제품 및 API 버전을 프로젝트의 현재 버전과 대조하세요.
프롬프트는 i18x 형식 값도 요구합니다. 카운터에는 int, 소수에는 floatFix1/floatFix2, 바이트에는 byteSize, 밀리초에는 progressDuration, 날짜와 시간에는 해당 형식을 사용합니다. 구조화된 출력에는 FormatValue()를 사용할 수 있습니다. 프로젝트 사전은 알맞은 <format> 정의와 함께 갱신하며 기존 번역은 유지합니다. 자체 엔진의 임시 제한도 반영합니다.
그룹화와 Task 트리에는 µGroup, µOrder, µGroups, SetGroupState, RevealTask 및 SetTaskEmphasis를 적용합니다. 하드웨어 안내에는 Stream Deck 그룹 브라우저(진입 키와 동적 슬롯 프로필)와 Actions Ring 및 Options+ 앱 프로필을 포함한 고정 Logitech Task, 그리고 µGulp™의 Workspace 선택 방식이 설명되어 있습니다.
Workflow
- 매개변수 예제를 프로젝트 루트에
microgulp-optimize.params.json으로 복사해 다음 값을 입력하세요:projectRoot,gulpfilePath,supportedLanguages(예:en-US,de-DE,zh-CN),gulpMuGulpApiVersion(로컬 기준^0.6.0; 설치/게시된 버전 확인),microGulpMinVersion(1.0.0), 그리고githubRepoUrl/githubRef(기본값:https://github.com/mamekudz/microGulp,main처럼 확인된 ref). - 프롬프트 마크다운을 열고
{{PLACEHOLDER}}표를 값으로 바꾸거나 Cursor에서 params 파일과 gulpfile을 첨부합니다. - AI가 마이그레이션을 실행하게 합니다. 프롬프트의 0단계는 필수: 편집 전 타임스탬프가 있는 gulpfile 백업(예:
gulpfile.mjs.20260703-142559.bak). 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) |
Scheduler demos 그룹(A-G)은 세션 스케줄(µSchedule)을 보여줍니다. 일회성 타이머, 간격 실행, 반복, Cron, 중복 실행 건너뛰기, 예약된 오류 및 Watch+Schedule을 다룹니다. 모든 데모 스케줄은 처음에 비활성화되어 있습니다(autoStart: false). 아이콘 버튼으로 필요한 스케줄만 개별 활성화하세요. 자세한 내용과 API: dev/docs/TaskScheduler.md.
추가 API 세부: gulp-mu-gulp-api/README.md.
µGulp™ Ready
프로젝트는 유용한 µGulp 전용 상호작용이나 출력을 하나 이상 제공하고, 일반 Gulp/CLI 실행 방법을 문서화하며 두 경로를 직접 검증해야 합니다. 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"이 있으면 엔진은 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). 데모 및 빌드 Task(진행 상황, 양식, 구조화된 로그, 사운드, 모달, 카운트다운, 사용자 지정 아이콘, 오류 표시, 지속 서비스 및 Attention/Reset)가 포함된 샘플 Gulpfile을 ~/.microgulp/sample에 복사하고 엽니다. 그런 다음 µGulp: Open Dashboard를 실행하세요. 사용자 안내서는 설정 → Handbook 또는 µGulp: Open Handbook에서 열 수 있으며 모든 언어 버전을 선택할 수 있습니다.
핸드북 PDF: Deutsch · English · 中文 · Français · Español · Русский · 日本語 · 한국어
라이선스
µGulp™(확장, 엔진, 대시보드, JetBrains 어댑터)는 독점 소프트웨어입니다 - LICENSE를 보십시오. 배포 바이너리는 무료로 쓸 수 있습니다. 소스 코드의 복사, 수정, 재배포는 허용되지 않습니다.
동반 npm 패키지 gulp-mu-gulp-api는 MIT 라이선스로 남아 Gulp 태스크가 제한 없이 채택할 수 있습니다.
로드맵 / 이 초안의 미결 사항
구현 완료
[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] 프로젝트 식별(
microgulp.config.json의project.title/description/logo; 작업 목록의 컴팩트 헤더)[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)[x] 일관된 Task 상태, 의미 기반 아이콘 38종, 입력 표시, 테마 대체 및 동작 줄이기
[x]
SetGroupState,RevealTask,SetTaskEmphasis를 통한 Task 트리 및 강조 표시[x] IDE API 함수 8개와 호스트/사용 가능 여부 표시
[x] Web Console, KnownProjectRegistry / Project Center, Open/Focus Project 및 공통 Background Host
[x] Stream Deck: Follow, workspace와 장치별 마지막 보기, Root 키 프로젝트 로고
[x] Stream Deck/Mobile, Logitech 및 Flexbar 통합; Logitech 개별 Task 할당 및 동적 키패드 폴더 지원
[x] 보정과 진단을 지원하는 컨트롤러 프로필; Windows x64 데스크톱 입력 및 SpaceMouse Wireless 프로필
아직 미결
[ ]
Ide.OpenUrl및 Background Host의 IDE 없는 작업 실행: 계획 단계이며 구현된 1.0.0 범위 밖[ ] Logitech MX: 프로젝트 이미지 포함 실물 인수 검증과 Dynamic Folder/여러 장치의 미해결 SDK 문제
[ ] Stream Deck: 여러 실물 장치 검증 및 Elgato Smart Profiles 연동
[ ] Flexbar: 실제 하드웨어 테스트
[ ] Linux 및 macOS 네이티브 컨트롤러 구성 요소
[ ]
µLib(microLib)를 문서화한 뒤 µGulp의 유틸리티 층으로 채택(오늘의 i18x는 로컬 webview 부분집합)[ ] 직접 i18xe-server 연결: 번들 사전 대신 라이브 번역 동기화
[ ]
µLib의GUI.mjs에 대시보드 폼용 추가 특수 컨트롤[ ] webview 대시보드의 시각 다듬기
[ ] µCSS 스킨 확장: 심볼 글꼴과 스프라이트를 매니페스트에
[ ] i18xe를 통한 음성 출력(아틀라스 샘플이 있으면 이미 WebAudio 비프를 대체)
[x] JetBrains 플러그인: Settings → Tools → µGulp(엔진 옵션)
[x] JetBrains Marketplace 목록(플러그인 34255. 레지스트리 제공은 모든 IDE에서의 신규 설치 검증이 아님)
[x] Microsoft Marketplace와 Open VSX의 VS Code/Cursor 목록(등록판과 Free)
Web Console 및 Project Center
로컬 Web Console은 알려진 프로젝트와 연결된 프로젝트를 Project Center에 모읍니다. 작업, Project Controls, 매개변수, 기록, 실시간 이벤트가 있는 기존 대시보드를 내장하며 두 번째 TaskEngine을 만들지 않습니다. VS Code/Cursor의 µGulp: Open Web Console, JetBrains 도구 창의 Open Web Console, 개발 체크아웃의 npm run console -- open으로 엽니다. 브라우저 플러그인 없이 로컬 HTTP/SSE를 쓰며 127.0.0.1만 수신합니다. LAN 또는 원격 접근 기능이 아닙니다.
알려진 프로젝트와 세션
KnownProjectRegistry는 경로, ProjectId, 제목, 설명, 로고, 선호 IDE, 마지막 확인 시간을 ~/.microgulp/known-projects.json에 저장합니다. 메타데이터는 microgulp.config.json에서 가져옵니다. 목록은 연결됨, 닫힘, 사용 불가를 구분합니다. 알려진 항목은 실행 중인 엔진이 아닙니다. 활성 IDE 세션은 따로 관리하며 같은 프로젝트의 여러 창도 개별 선택할 수 있습니다.
Follow active IDE project는 공통 활성 프로젝트 컨텍스트를 따릅니다. 수동 세션 선택은 이 탭에만 고정되며 컨트롤러 고정은 바꾸지 않습니다. 다른 앱이 전면에 와도 마지막으로 표시한 세션이 살아 있으면 계속 표시합니다.
µGulp™ Free에서도 목록과 내장 대시보드에 접근할 수 있으며 일반 작업 권한이 적용됩니다. 호스트 관리도 사용할 수 있습니다. Open/Focus Project, Start Application, IDE 작업, 선호 IDE 설정은 호출마다 서버에서 에디션과 등록 권한을 확인합니다. 권한이 없으면 unsupported-edition 또는 unsupported-registration을 반환합니다.
프로젝트 열기 및 포커스
Open/Focus Project는 선택한 IDE 계열, 구체적인 제품과 설치를 사용합니다. 일치하는 세션이 있으면 해당 창에 포커스를 줍니다. 후보가 여러 개면 세션 선택이 필요합니다. 포커스 실패로 두 번째 IDE를 실행하지 않으며 정확한 창 포커스는 현재 Windows 전용입니다. 일치하는 세션이 없으면 선택한 설치에서 알려진 프로젝트를 엽니다. 병렬 요청은 합쳐지고 시작 확인이 없으면 명시적인 재시도가 필요합니다. 느린 시작은 일시적으로 미확인 상태로 표시될 수 있습니다.
알려진 Windows 사용자 설치를 감지합니다. 다른 IDE와 앱은 실행 파일 절대 경로와 선택적인 고정 인수로 ~/.microgulp/applications.json에 설정할 수 있으며 JetBrains는 구체적인 제품이 필요합니다. Start Application은 shell 명령 없이 알려진 앱을 시작합니다. 임의의 외부 앱에 대한 일반 포커스는 범위 밖입니다. Windsurf 감지는 실험적이며 다른 IDE를 승인한 것이 아닙니다.
Background Host
공통 Background Host는 IDE와 독립적인 사용자당 한 프로세스로 Web Console, 알려진 프로젝트, 활성 프로젝트, 컨트롤러 컨텍스트를 제공합니다. 첫 IDE가 필요할 때 시작하며 IDE를 닫아도 종료되지 않습니다. 선택적인 로그인 시 시작을 쓰면 IDE 없이 http://127.0.0.1:47821/console에 접근할 수 있습니다. IDE가 없으면 알려진 프로젝트를 표시하고 필요한 에디션 권한이 있으면 Cursor, VS Code, JetBrains에서 열 수 있습니다. 작업은 연결된 IDE 세션으로 제어합니다. IDE 없는 실행과 엔진 소유자의 자동 인계는 1.0.0에 포함되지 않습니다.
설정은 모든 IDE에 공통이며 host-settings.json에만 저장합니다. Start at login과 Show background UI는 독립적이며 UI를 숨겨도 호스트를 멈추지 않습니다. 포트는 공통입니다(기본 47821, 범위 1024~65535). 변경하면 실행 중인 호스트가 재시작되고 Console은 새 주소로 이동합니다. 다른 앱이 요청한 포트를 쓰면 이전 포트를 유지합니다. 임의 포트나 바인딩 주소 필드는 없으며 127.0.0.1만 사용합니다.
처음 시작할 때 µGulp™는 IDE별이 아닌 사용자당 한 번 *Enable µGulp Background Host?*라고 묻습니다. Enable은 로그인 시 시작을 켜고 Not now는 끈 상태로 둡니다. IDE는 필요하면 호스트를 시작할 수 있습니다.
동일한 제어는 VS Code/Cursor(µGulp: Background Host Settings), JetBrains(Settings → Tools → µGulp Background Host와 도구 창의 Background Host), Console의 Background Host, npm run console -- status|open|restart|stop|port <n>|autostart on|off|ui on|off에 있습니다. Windows 트레이 메뉴는 Console을 열고 상태, 연결 IDE, 알려진 프로젝트를 표시하며 로그인 시 시작을 전환합니다. 포트는 거기서 바꾸지 않습니다. Stop은 호스트만 종료하며 IDE가 나중에 다시 시작할 수 있습니다.
| 플랫폼 | 자동 시작 | 시스템 UI |
|---|---|---|
| Windows | 사용자 로그인 항목 | 트레이(선택적이며 headless 운영 가능) |
| macOS | LaunchAgent | 메뉴 막대 준비됨. macOS 실물에서는 미검증 |
| Linux | XDG 자동 시작 | headless. 트레이 의존성 없음 |
Console 문구는 현재 독일어와 영어로 제공하며 다른 언어는 영어로 대체합니다. 호스트 제어는 별도의 현지화 문구를 사용합니다. 전체 구현 API는 작업에서 IDE 작업 실행을 참고하세요.