windows-mqtt AGENTS.md

AGENTS Instructions

This repo contains a Node.js project for controlling a PC via MQTT, wrapped in a Tauri v2 desktop app.

Environment

Run source "$HOME/.cargo/env" before any cargo/rust commands.

ESM-соглашения

Весь JS в проекте — ES-модули ("type": "module" в package.json). При правке кода:

• Относительные импорты обязаны нести расширение .js (./foo.js, не ./foo).
• CJS-зависимости импортируются дефолтом и деструктурируются (import pkg from 'x'; const { thing } = pkg;), а не именованными импортами — именованные экспорты из CJS зависят от cjs-module-lexer, который ненадёжен на пакетах с нативными аддонами.
• Если у зависимости в exports есть ключ require, но нет import, голый import уходит в default и может отличаться от того, что отдавал require() — именно так одна строка молча сменила протокол OBS на msgpack вместо JSON (src/modules/obs.js, обходится импортом подпути obs-websocket-js/json). Перед переводом любой зависимости стоит сверить import.meta.resolve('pkg') с прежним require.resolve('pkg').
• Тот же механизм уже стоил второго модуля: ws под ESM резолвится в wrapper.mjs, чей default — класс WebSocket БЕЗ статик, поэтому new WebSocket.Server() из src/modules/tabs.js падал с TypeError с самого перехода на ESM (глотал initModules()). Сервер берётся только именованным импортом import { WebSocketServer } from 'ws' — wrapper.mjs настоящий ESM, оговорка про cjs-module-lexer к нему не относится.
• require() в проекте больше нет.
• Планка рантайма: import.meta.dirname требует Node ≥ 20.11 (боевой код), registerHooks — Node ≥ 22.15 (только тесты, test/modules-registry.test.js). Поля engines в package.json намеренно нет.
• data/ под .gitignore и содержит CommonJS-файлы (data/index.js и т. п.), поэтому там лежит собственный data/package.json с {"type":"commonjs"} — на свежем клоне его надо создать заново.

Tauri Architecture

• Tauri v2 (not v1, not Electron). Config schema: https://schema.tauri.app/config/2
• Rust backend in src-tauri/src/main.rs — resolves an "app root" (dev: project root; bundled: resource_dir/_up_) via resolve_app_root, spawns the Node.js server from setup() as a child process via tauri-plugin-shell, and kills it gracefully on Quit (sends app/shutdown IPC action, then hard-kills after 800ms)
• Permissions defined in src-tauri/capabilities/default.json (replaces v1 allowlist)
• Tray icon built inside .setup() using TrayIconBuilder, with on_menu_event and on_tray_icon_event closures
• Shell commands use app.shell().command() (from ShellExt trait), NOT tauri::api::process::Command
• CommandEvent::Stdout/Stderr returns Vec<u8>, convert with String::from_utf8_lossy
• Build check: cd src-tauri && cargo check
• Типы без TypeScript: jsconfig.json включает checkJs, npm run typecheck (tsc --noEmit) гоняется первым шагом npm test. Файлы остаются .js, шага сборки нет — bundle.resources, deploy-fast.js и спавн src/index.js из Rust продолжают работать с россыпью исходников. strict намеренно выключен: в нём проект даёт ~450 ошибок, из них ~380 — разметка implicit any без единого реального дефекта. Формы конфига описаны одним @typedef Config в src/config-loader.js (индексная сигнатура: ключи задаёт пользователь в YAML). Нетипизированные зависимости обязаны иметь @types/* в devDependencies — иначе allowJs заставляет tsc проверять их собственный JS и сыпать сотней чужих ошибок.
• JS tests: npm test (npm run typecheck && node --test test/**/*.test.js). Pure logic only — never spawn Windows/native binaries in tests. Modules with native addons are covered by test/native-modules.test.js, which auto-skips where those addons aren't installed (e.g. Linux).
• JS/Rust config-path coupling: resolveAppFile/resolveConfigPath in src/paths.js must stay in sync with config_candidates/resolve_config_path in src-tauri/src/main.rs (same search order, same config.example.yml fallback).
• Dev run: npm run start-tauri or cargo tauri dev. The npm scripts use scripts/tauri-wrapper.js to ensure MSVC linker is available when running from Git Bash (vcvars64.bat is invoked before Tauri). If you see LNK1181: cannot open input file 'kernel32.lib', ensure the "Desktop development with C++" workload includes the Windows 10/11 SDK.