dsh-desktop-kit 0.0.0-stage → 2.0.0

package/skills/wow-design/assets/scripts/README.md

@@ -0,0 +1,312 @@
+# design-qa — инструменты визуальной проверки UI
+
+Набор CLI-инструментов для петли «собрал → снял скриншоты → проверил доступность/технику → исправил → снова снял».
+Используется в WOW-дизайне (дизайн-кит `projects/design-kit/`) и для проверки любых других страниц.
+
+| Инструмент | Что делает |
+|---|---|
+| `capture.mjs` | PNG-скриншоты страницы во всех viewport и темах через headless Chrome (CDP) |
+| `audit.mjs` | axe-core + кастомные проверки (overflow, tap-targets, заголовки, alt, шрифты, консоль) → `audit.json` + `audit.md` |
+| `validate-package.mjs` | Валидатор портативного пакета DSH (ZIP или каталог): структура, скиллы, секреты, sha256 |
+
+## Требования окружения
+
+- Node.js 24 (в репозитории уже есть `node_modules` с `playwright-core` и `axe-core` — ставить ничего не нужно).
+- Chrome, запущенный с `--remote-debugging-port=9333` (в текущем окружении он уже запущен).
+  Если CDP недоступен, `capture/audit` **сами** запускают `chrome.exe` из `ms-playwright` с временным профилем
+  (порт берётся свободный). Чужой Chrome инструменты **не перезапускают**.
+- Переопределение браузера: `--cdp <url>` / env `CDP_URL`, путь к chrome.exe — env `CHROME_PATH`.
+- Все артефакты по умолчанию складываются в `tmp/qa-artifacts/` (от корня workspace).
+
+Запускать команды удобнее из корня workspace:
+
+```powershell
+node tools/design-qa/capture.mjs projects/design-kit/showcase.html --name showcase
+node tools/design-qa/audit.mjs projects/design-kit/showcase.html --name showcase
+node tools/design-qa/validate-package.mjs dist/dsh-portable-2026-11-04-dry.zip
+```
+
+---
+
+## capture.mjs — скриншоты
+
+```
+node tools/design-qa/capture.mjs <путь-к-html|url> --name <name> [опции]
+```
+
+| Опция | Описание |
+|---|---|
+| `--name <name>` | Префикс имён PNG (по умолчанию — имя html-файла) |
+| `--out <dir>` | Куда писать PNG и `shots.json` (по умолчанию `tmp/qa-artifacts`) |
+| `--viewports <list>` | `desktop,tablet,mobile` или `1440x900,390x844` (по умолчанию все три) |
+| `--themes <list>` | `light,dark` (по умолчанию обе) |
+| `--full` / `--no-full` | Полная страница (по умолчанию включено) или только видимая часть |
+| `--selector <css>` | Снять только первый элемент по селектору (например, `"main"` или `"#components"`) |
+| `--dpr <1..4>` | `devicePixelRatio` (retina-скриншоты; по умолчанию 1) |
+| `--preset <id>` | Выставить `data-preset` на `<html>`: `aurora`, `graphite`, `editorial`, `warm`, `swiss` |
+| `--serve` | Отдать страницу локальным HTTP-сервером (нужно для `<script type="module">`) |
+| `--cdp <url>` | CDP-эндпоинт (по умолчанию `http://127.0.0.1:9333`) |
+| `--timeout <ms>` | Таймаут загрузки (по умолчанию 30000) |
+| `--json` | Манифест в stdout как JSON (логи — в stderr) |
+| `-h, --help` | Справка |
+
+Что происходит внутри (важно для предсказуемости скриншотов):
+
+1. Подключение к CDP (при недоступности — fallback-запуск Chromium).
+2. Путь к локальному html превращается в `file://` URL (валидное URL-кодирование кириллицы и пробелов).
+3. `data-theme`/`data-preset` выставляются **до** первой отрисовки (init script), затем повторно после загрузки —
+   на случай, если JS страницы перезапишет тему из localStorage.
+4. Ожидание `document.fonts.ready`; отдельно фиксируется `document.fonts.status`.
+5. Инжектится CSS, гасящий анимации/переходы и скрывающий скроллбар (чтобы layout не зависел от 15-px скроллбара).
+6. Страница проскролливается сверху вниз и обратно — срабатывают reveal-анимации (IntersectionObserver) и lazy-load;
+   изображения принудительно декодируются.
+7. Стабилизация (несколько кадров + повторное ожидание шрифтов), затем скриншот.
+
+Результат:
+
+```
+tmp/qa-artifacts/
+  showcase-desktop-light.png   # <name>-<viewport>-<theme>.png
+  showcase-desktop-dark.png
+  showcase-tablet-light.png    ...
+  showcase-mobile-dark.png
+  shots.json                   # манифест прогона
+```
+
+`shots.json`: `name`, `source`, `url`, `browser`, `options`, `shots[]` (viewport/theme/dpr/размеры PNG, title,
+scrollWidth/scrollHeight, `fonts.status`, ошибки консоли/сети, `error`), агрегированные `consoleErrors`,
+`pageErrors`, `failedRequests`, `totals`, `ok`.
+
+Коды выхода: `0` — все скриншоты сняты; `1` — ошибка/частичный сбой (смотрите `shots.json` → `error`).
+Страница со сломанными ассетами всё равно снимается: ошибки фиксируются в манифесте.
+
+Примеры:
+
+```powershell
+# Полный набор 6 скриншотов
+node tools/design-qa/capture.mjs projects/design-kit/showcase.html --name showcase
+
+# Скриншоты сразу в каталог дизайн-кита (как в DoD)
+node tools/design-qa/capture.mjs projects/design-kit/showcase.html --name showcase --out projects/design-kit/screenshots
+
+# Только мобильный тёмный + двойное разрешение
+node tools/design-qa/capture.mjs projects/design-kit/pages/dashboard.html --name dashboard --viewports mobile --themes dark --dpr 2
+
+# Отдельный блок (не вся страница)
+node tools/design-qa/capture.mjs projects/design-kit/showcase.html --name palette --selector "#colors"
+
+# Страница с ES-модулями (file:// их блокирует CORS)
+node tools/design-qa/capture.mjs projects/design-kit/showcase.html --name showcase --serve
+```
+
+---
+
+## audit.mjs — доступность и технический аудит
+
+```
+node tools/design-qa/audit.mjs <путь-к-html|url> [--out <dir>] [--name <name>] [--json]
+```
+
+| Опция | Описание |
+|---|---|
+| `--out <dir>` | Каталог отчётов (по умолчанию `tmp/qa-artifacts`) |
+| `--name <name>` | Имена файлов `<name>-audit.json` / `<name>-audit.md`; без `--name` — `audit.json` / `audit.md` |
+| `--themes <list>` | `light,dark` (по умолчанию обе) |
+| `--preset <id>` | Выставить `data-preset` |
+| `--serve` / `--cdp` / `--timeout` | Как у capture |
+| `--json` | Полный JSON в stdout (логи — в stderr) |
+
+Что проверяется (каждая тема × desktop 1440×900 и mobile 390×844):
+
+- **axe-core** из `node_modules/axe-core/axe.min.js` (теги: `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22aa`, `best-practice`).
+  Контраст текста проверяется отдельно в обеих темах.
+- **Горизонтальный overflow** на 390px: `scrollWidth > clientWidth`, с поиском элементов-виновников
+  (исключая содержимое легитимных `overflow-x:auto` контейнеров).
+- **Tap-targets (WCAG 2.5.8)**:
+  - иконочные цели `< 24×24px` (кнопки/ссылки без видимого текста) → **critical** (блокер exit-кода);
+  - цели `24–39px`, текстовые ссылки малой высоты и нативные контролы (checkbox/radio/select) → **minor**
+    (best practice, на вердикт не влияет);
+  - инлайновые ссылки в тексте/навигации (`a` внутри `p`, `li`, `nav`, breadcrumbs) → advisory, не считаются.
+- **Порядок заголовков**: нет h1 / несколько h1 / пропуск уровня (`h2 → h4`).
+- **Изображения**: отсутствие атрибута `alt`, битые картинки (`naturalWidth === 0`).
+- **Ссылки/кнопки без доступного имени** (текст, `aria-label`, `aria-labelledby`, `title`, `img alt`).
+- **Шрифты**: `document.fonts.status !== "loaded"`, `@font-face` со статусом `error`.
+- **Консоль и сеть**: `console.error`, `pageerror`, сбои загрузки ресурсов (404, CORS, битые пути).
+  Шум, который создаёт сам axe-core (XHR к CSS на `file://`), отфильтрован — диагностика снимается до инжекта axe.
+
+Severity и код выхода:
+
+| Severity | Влияет на exit code |
+|---|---|
+| `critical` | да |
+| `serious` | да |
+| `moderate` / `minor` | нет |
+
+Коды выхода: `0` — нет critical/serious; `2` — есть critical/serious (страницу нельзя сдавать); `1` — сбой инструмента.
+
+`audit.md` (человекочитаемо): вердикт, сводка по severity, **топ-10 «что чинить в первую очередь»** с подсказками
+по исправлению, разделы axe по правилам (id, impact, helpUrl, узлы), кастомные проверки (overflow, tap-targets,
+заголовки, изображения, ссылки, шрифты), консоль/сеть, таблица прогонов.
+`audit.json` (машиночитаемо): `summary`, `issues[]` (source/id/severity/theme/viewport/help/helpUrl/nodes/seenIn/fix),
+`axe[]` по прогонам, `custom[]` (сырые метрики), `console`, `fonts`, `options`, `exitCode`.
+
+Как читать отчёт:
+
+1. `## Вердикт` — PASS/FAIL и counts. Цель для UI: `critical = 0`, `serious = 0`.
+2. `## Что чинить в первую очередь` — 10 самых важных пунктов с готовой формулировкой правки.
+3. `## Axe: нарушения` — конкретные CSS-селекторы/HTML и `failureSummary` (что именно не так).
+4. `## Кастомные проверки` — overflow/tap-targets/заголовки/alt/шрифты.
+5. `## Консоль и сеть` — ошибки JS и незагруженные ресурсы.
+
+Пример:
+
+```powershell
+node tools/design-qa/audit.mjs projects/design-kit/showcase.html --name showcase
+# exit 0 — чисто; 2 — есть блокеры (аудит-файлы в tmp/qa-artifacts/)
+```
+
+---
+
+## validate-package.mjs — валидатор портативного пакета DSH
+
+```
+node tools/design-qa/validate-package.mjs <zip|каталог> [--json] [--skip-secrets] [--quiet]
+```
+
+Проверки:
+
+1. **Структура** — обязательные `install.ps1`, `README.md`, `metadata.json`, `payload/AGENTS.md`,
+   `payload/memory/`, `payload/skills/`, `payload/profiles/desktop/`; рекомендуемые
+   `УСТАНОВИТЬ.cmd`, `payload/memory/INDEX.md`, `payload/profiles/desktop/cordis.yml`, `package.json`.
+2. **metadata.json** — валидный JSON, обязательные поля `schemaVersion` (number), `exportedAt` (ISO-дата),
+   `dshVersion` (string); отсутствие рекомендуемых полей — предупреждение.
+3. **Скиллы** — для каждого `payload/skills/<name>/SKILL.md`: YAML-frontmatter, `name` в kebab-case,
+   `name` совпадает с именем папки, есть `description` и `whenToUse`, нет дублей имён, файл не пустой, UTF-8.
+4. **Целостность ZIP** — читается каждая запись, проверяются CRC32 и размер (обрезанный/битый архив → FAIL);
+   для каталога — проверяется читаемость всех файлов.
+5. **Битые/опасные пути** — path traversal (`..`), абсолютные пути/буква диска, пустые сегменты, управляющие
+   символы, дубликаты, коллизии регистра, конфликт «файл и каталог», сегменты с точкой/пробелом на конце,
+   длинные пути; обратные слэши определяются как стиль упаковщика (одно предупреждение, не 90).
+6. **Секреты** в текстовых файлах: `sk-…`, `gh*_…`, `AKIA/ASIA…`, `AIza…`, `xox…`, `npm_…`, приватные ключи.
+   Найденное **маскируется** в отчёте; заглушки/примеры (`sk-xxx`, `<...>`, `example`) игнорируются.
+7. **Размеры и sha256** — размер архива, `sha256` ZIP, `content-sha256` (хеш по содержимому файлов) и топ-5
+   крупнейших файлов. `content-sha256` для каталога и ZIP с тем же содержимым **совпадает** — удобный инвариант
+   при пересборке.
+
+Коды выхода: `0` — OK (могут быть предупреждения); `1` — FAIL (есть ошибки); `2` — не удалось прочитать
+входные данные/неверные аргументы. Предупреждения не блокируют приёмку.
+
+Примеры:
+
+```powershell
+# Каталог сборки
+node tools/design-qa/validate-package.mjs tmp/package-build/dsh-portable-2026-11-04-dry
+
+# Готовый ZIP + сверка sha256 с SHA256SUMS.txt
+node tools/design-qa/validate-package.mjs dist/dsh-portable-2026-11-04-dry.zip
+Get-Content dist/SHA256SUMS.txt   # sha256 архива должен совпасть
+
+# Машиночитаемый результат
+node tools/design-qa/validate-package.mjs dist/dsh-portable-2026-11-04-dry.zip --json
+```
+
+Проверено на реальных артефактах:
+
+- `%USERPROFILE%\Downloads\dsh-portable-2026-11-03.zip` — **OK**, 15 скиллов, 94 файла;
+- `tmp/package-build/dsh-portable-2026-11-04-dry` (каталог) — **OK**, 17 скиллов (включая `wow-design`,
+  `design-critique`), 289 файлов, 0 ошибок/предупреждений;
+- `dist/dsh-portable-2026-11-04-dry.zip` — **OK**, sha256 совпал с `dist/SHA256SUMS.txt`
+  (`3e5480d7…e35fd8`), `content-sha256` совпал с каталогом (`ea12c490…38f999`);
+- fixtures с намеренными нарушениями — **FAIL** (см. ниже).
+
+---
+
+## Фикстуры и самопроверка инструментов
+
+```
+tools/design-qa/fixtures/
+  test.html                    # эталонная страница: без нарушений (обе темы, reveal, lazy, таблица)
+  broken.html                  # страница с намеренными нарушениями (для негативного теста audit)
+  package-ok/                  # валидный мини-пакет (генерируется)
+  package-bad/                 # пакет с ошибками (генерируется)
+  make-fixtures.mjs            # пересоздаёт package-ok / package-bad
+```
+
+Регрессионная проверка инструментов (ожидаемые результаты):
+
+```powershell
+cd %USERPROFILE%\Documents\deepseek-harness\default-workspace
+
+# 0) фикстуры пакетов
+node tools/design-qa/fixtures/make-fixtures.mjs
+
+# 1) capture: 6/6 скриншотов, exit 0
+node tools/design-qa/capture.mjs tools/design-qa/fixtures/test.html --name fixture
+
+# 2) audit эталона: PASS, exit 0
+node tools/design-qa/audit.mjs tools/design-qa/fixtures/test.html --name fixture-test
+
+# 3) audit «плохой» страницы: FAIL, exit 2 (color-contrast, image-alt, button-name, overflow, pageerror…)
+node tools/design-qa/audit.mjs tools/design-qa/fixtures/broken.html --name fixture-broken
+
+# 4) валидатор пакета: OK, exit 0
+node tools/design-qa/validate-package.mjs tools/design-qa/fixtures/package-ok
+
+# 5) валидатор «плохого» пакета: FAIL, exit 1
+node tools/design-qa/validate-package.mjs tools/design-qa/fixtures/package-bad
+```
+
+Дополнительно проверены: обрезанный ZIP (exit 2 + понятная ошибка), ZIP с `../`/дублями/конфликтами
+(FAIL с кодами `PATH_INVALID`, `PATH_CONFLICT`), секреты в тексте (маскируются).
+
+---
+
+## CDP и браузер: детали
+
+- По умолчанию `capture/audit` подключаются к `http://127.0.0.1:9333` (env `CDP_URL` или `--cdp`).
+- Чужой Chrome **не перезапускается и не закрывается**: соединение открывается/закрывается, вкладки закрываются,
+  браузер продолжает работать для других агентов.
+- Если CDP недоступен, инструмент запускает свой headless Chromium (`ms-playwright/chromium-*/chrome-win64/chrome.exe`,
+  путь можно задать `CHROME_PATH`) с временным профилем и свободным портом. Временный профиль удаляется.
+- При ошибке «Не найден chrome.exe» — задайте `CHROME_PATH` или запустите Chrome с `--remote-debugging-port=9333`.
+- `--serve` поднимает локальный статический HTTP-сервер (корень — текущий каталог, случайный порт) — это решает
+  проблему ES-модулей и XHR с `file://`, но для обычных «двойной клик по html» страниц не нужен.
+
+## Ограничения и предостережения
+
+- **Скриншоты и отчёты могут содержать данные со страницы** (текст, HTML-фрагменты). `tmp/qa-artifacts/` — рабочая
+  зона, не коммитить в git и не выкладывать наружу.
+- `file://` + `<script type="module">`/`fetch`/XHR — браузер блокирует; для таких страниц используйте `--serve`
+  (или не используйте модули в «открываемых двойным кликом» страницах).
+- Очень длинные страницы при `--dpr 2` могут упираться в лимиты CDP — инструмент автоматически откатывается на
+  `scale: css`, затем на видимую часть (это фиксируется в `shots.json` → `note`).
+- ZIP-валидатор поддерживает обычные ZIP (store/deflate). **ZIP64 и зашифрованные архивы не поддерживаются**
+  (для пакета DSH не нужны) — выдаётся понятная ошибка.
+- Проверка секретов — эвристика по регулярным выражениям и может давать ложные срабатывания/пропуски;
+  она не заменяет нормальный secret-scanning в CI.
+- `audit` эмулирует `prefers-reduced-motion: reduce` (стабильные скриншоты + проверка reduced-motion ветки).
+  Для проверки «как с анимациями» добавьте `--motion` (не документирован в help, но поддерживается).
+- Инструменты рассчитаны на Chromium (Chrome/Edge). Firefox/WebKit не проверялись.
+
+## Состав каталога
+
+```
+tools/design-qa/
+  capture.mjs            # скриншоты
+  audit.mjs              # axe + кастомные проверки
+  validate-package.mjs   # валидатор портативного пакета DSH
+  lib/args.mjs           # мини-парсер CLI
+  lib/browser.mjs        # CDP/fallback, viewport/темы, подготовка страницы, статический сервер
+  lib/zip.mjs            # ZIP-ридер (store/deflate + CRC32) без внешних зависимостей
+  fixtures/              # тестовые страницы и пакеты + make-fixtures.mjs
+  README.md              # этот файл
+```
+
+## Петля WOW-дизайна (как встроить в работу)
+
+1. Сверстал страницу → `capture.mjs` (desktop/tablet/mobile × light/dark).
+2. Посмотрел PNG глазами (`read_image`) → критика по рубрике (`tmp/design-research/04-critique-rubric.md`).
+3. Исправил → `capture.mjs` снова (минимум 2 итерации, зафиксировать, что исправлено).
+4. `audit.mjs` перед сдачей: цель — `critical = 0`, `serious = 0`, нет overflow на 390, `fonts.status = loaded`,
+   нет ошибок консоли.
+5. Валидатор пакета — после сборки архива: `OK` + сверка `sha256` с `SHA256SUMS.txt`.