diff --git a/docs/ideas/codeboarding-integration.md b/docs/ideas/codeboarding-integration.md new file mode 100644 index 00000000..9de4df84 --- /dev/null +++ b/docs/ideas/codeboarding-integration.md @@ -0,0 +1,273 @@ +# CodeBoarding Integration Idea + +Дата проверки: 2026-05-03. + +## Короткий вывод + +CodeBoarding полезен для Agent Teams как опциональная визуализация архитектурного влияния агентских изменений. Он не выглядит как готовый embeddable real-time daemon для нашего Electron UI, но у него есть достаточная база для near real-time режима: + +- baseline анализ через `codeboarding full --local `; +- incremental анализ через `codeboarding incremental --local `; +- partial обновление компонента через `codeboarding partial --local --component-id `; +- выходные артефакты в `.codeboarding/`, включая `analysis.json`, Markdown и Mermaid; +- method/component change tracking в VS Code extension. + +Практичный продуктовый вариант: делаем CodeBoarding optional dependency, даём пользователю install/detect/setup в UI, запускаем full один раз, а дальше показываем live-ish overlay по изменениям агентов. Быструю подсветку делаем сами по git diff/task change ledger, а CodeBoarding incremental используем как более точный фоновый refresh. + +## Что проверено + +- GitHub repo: [CodeBoarding/CodeBoarding](https://github.com/CodeBoarding/CodeBoarding) +- Website: [codeboarding.org](https://www.codeboarding.org/) +- PyPI JSON: [pypi.org/pypi/codeboarding/json](https://pypi.org/pypi/codeboarding/json) +- Release: [v0.11.0](https://github.com/CodeBoarding/CodeBoarding/releases/tag/v0.11.0) +- VS Code Marketplace: [CodeBoarding extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) +- MCP repo: [CodeBoarding/CodeBoarding-MCP](https://github.com/CodeBoarding/CodeBoarding-MCP) + +На момент проверки: + +- Latest GitHub release: `v0.11.0`, published 2026-04-29. +- Latest PyPI version: `0.11.0`, requires Python `>=3.12,<3.14`. +- License: MIT. +- Repo активный: последний push был 2026-05-03. +- Основной стек CodeBoarding: Python CLI, static analysis, LSP, tree-sitter, LLM providers. +- Поддерживаемые языки из README/PyPI: Python, TypeScript, JavaScript, Java, Go, PHP, Rust, C#. +- LLM providers из README/PyPI: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter и другие. + +## Что CodeBoarding умеет + +Из README и CLI: + +- генерирует high-level architecture diagrams; +- генерирует deeper component diagrams; +- пишет Markdown документацию в `.codeboarding/`; +- пишет Mermaid output, который удобно показывать в нашем Markdown/Mermaid viewer; +- умеет incremental updates, когда есть предыдущий analysis; +- умеет partial update одного component id; +- для private repos использует `GITHUB_TOKEN`; +- конфиг LLM ключей хранит в `~/.codeboarding/config.toml`, но env vars имеют приоритет. + +Публичные команды CLI: + +```bash +codeboarding full --local /path/to/repo +codeboarding incremental --local /path/to/repo +codeboarding partial --local /path/to/repo --component-id "1.2" +``` + +Установка из README/PyPI: + +```bash +pipx install codeboarding --python python3.12 +codeboarding-setup +codeboarding full --local /path/to/repo +``` + +Важно: `codeboarding-setup` скачивает language server binaries в `~/.codeboarding/servers/`. Node.js/npm нужен для Python, TypeScript, JavaScript и PHP language servers; если Node/npm не найден, CodeBoarding может скачать pinned Node runtime в `~/.codeboarding/servers/nodeenv/`. + +## Real-time оценка + +В VS Code Marketplace заявлено: + +- `Realtime Component Change tracking` - можно видеть, в каких компонентах есть file edits. +- `0.11.0` - Git Commit Diff View, timeline slider, подсветка components/files/methods по recent commits. +- `0.11.0` - Faster Incremental Analysis, refresh переиспользует прошлые результаты и анализирует только затронутое. +- `0.10.0` - Method-Level Change Tracking. +- `0.10.0` - Real-time Method Updates. +- `0.10.2` - Smoother Real-time Updates. + +Но в open-source CLI я не нашёл отдельного публичного `watch`/daemon режима. В коде есть incremental pipeline, worktree diff, `incrementalDelta`, method-level statuses, comments про IDE/wrapper integration и snapshot target refs, но публичный CLI остаётся командным. + +Вывод: CodeBoarding позволяет сделать near real-time визуализацию, но real-time orchestration надо делать нам: + +1. watcher ловит изменения файлов от агента; +2. debounce, например 2-10 секунд; +3. быстрый overlay строится по git diff/task change ledger и текущему `.codeboarding/analysis.json`; +4. CodeBoarding incremental запускается фоном реже или на завершение task; +5. UI обновляет Mermaid/architecture map и affected components. + +## Что можно показать пользователю + +Хорошо подходит: + +- 🟢 новый файл попал в конкретный компонент; +- 🟡 метод или файл изменён внутри компонента; +- 🔴 файл/метод удалён; +- какие компоненты трогает конкретный агент; +- какие компоненты трогает конкретная task; +- архитектурный контекст рядом с code review; +- diff timeline по commits или task snapshots; +- Markdown/Mermaid docs прямо в нашем Project Editor/Review UI. + +Сложно или рискованно: + +- мгновенная перестройка диаграммы на каждый символ; +- точная визуализация rename/copy, потому что incremental pipeline сейчас может требовать full analysis для rename/copy; +- стабильная работа на очень больших репах без очереди, debounce и cancellation; +- full/incremental анализ без настроенного LLM provider; +- автоматическая установка Python 3.12/3.13 на всех OS без отдельного installer UX. + +## Варианты интеграции + +### 1. Optional CLI Runner + просмотр `.codeboarding/` + +🎯 9 🛡️ 8 🧠 4 +Примерно `250-450` строк. + +Суть: в Settings/Integrations добавляем CodeBoarding detect/install/run. Первый MVP только запускает `full`/`incremental`, показывает статус, открывает `.codeboarding/analysis.json` и Markdown/Mermaid в существующем viewer. + +Плюсы: + +- быстро проверить реальную пользу; +- почти не вмешивается в team/review lifecycle; +- опирается на уже существующие Markdown/Mermaid возможности; +- безопаснее, потому что dependency optional. + +Минусы: + +- это не live UX; +- пользователь сам интерпретирует изменения; +- нет красивой связки с задачами агентов. + +Когда выбирать: если хотим дешёвый probe перед большой фичей. + +### 2. Live-ish Overlay поверх baseline анализа + +🎯 9 🛡️ 8 🧠 5 +Примерно `900-1400` строк. + +Суть: CodeBoarding делает baseline `.codeboarding/analysis.json`. Дальше наш watcher/git status/task change ledger быстро мапит изменённые файлы на компоненты из baseline и подсвечивает affected components почти в реальном времени. CodeBoarding `incremental` запускается фоном по debounce, на завершение task или по кнопке refresh. + +Плюсы: + +- даёт пользователю ощущение real-time; +- не заставляет LLM работать на каждое маленькое изменение; +- хорошо ложится на агентские изменения и task review; +- можно показывать impact до завершения задачи. + +Минусы: + +- нужна собственная модель overlay state; +- baseline mapping может быть устаревшим до следующего incremental; +- для новых файлов компонент может определяться эвристикой до refresh. + +Когда выбирать: лучший первый продуктовый вариант. + +### 3. Architecture Review per Task + +🎯 8 🛡️ 7 🧠 8 +Примерно `1600-2500` строк. + +Суть: связываем CodeBoarding с review flow. Для каждой task показываем impacted components, changed methods, old/new architecture map, summary риска и ссылки на файлы. Можно добавить отдельную вкладку в task detail или review dialog. + +Плюсы: + +- максимальная ценность для Agent Teams; +- помогает ревьюить AI-generated changes не только по diff, но и по архитектурному влиянию; +- можно использовать как сильный selling point. + +Минусы: + +- крупная фича; +- нужны тесты на task-change mapping, IPC, persistence и UI; +- есть риск перегрузить review screen. + +Когда выбирать: после MVP и подтверждения, что карты реально помогают пользователям. + +## Варианты установки optional dependency + +### A. pipx install в user environment + +🎯 8 🛡️ 7 🧠 4 +Примерно `350-600` строк. + +UI проверяет `python3.12`/`python3.13`, `pipx`, `codeboarding`. Если нет, предлагает install через `pipx install codeboarding --python python3.12`, затем `codeboarding-setup`. + +Плюсы: соответствует README, изолированная среда, меньше конфликтов с системным Python. + +Минусы: надо отдельно вести UX для отсутствующего Python/pipx. + +### B. Скачать packaged binary из GitHub Release + +🎯 7 🛡️ 7 🧠 6 +Примерно `600-1000` строк. + +У CodeBoarding release `v0.11.0` содержит assets для macOS/Linux/Windows. Можно скачивать бинарь под OS, проверять sha256 asset и хранить в app-managed tools dir. + +Плюсы: меньше зависимости от Python/pipx у пользователя. + +Минусы: нужно аккуратно делать download, checksum, permissions, updates, notarization/security prompts. + +### C. Встроить Python package в наш app bundle + +🎯 4 🛡️ 5 🧠 9 +Примерно `1200-2200` строк. + +Пакуем CodeBoarding и Python runtime вместе с приложением. + +Плюсы: самый гладкий UX после установки. + +Минусы: тяжёлый bundle, OS-specific packaging, LSP binaries, security/update burden. Для optional feature это слишком дорого. + +Рекомендация: начать с A, потом рассмотреть B для packaged app. + +## Как это ложится на нашу архитектуру + +Так как фича пересекает main/preload/renderer и запускает внешний инструмент, её лучше делать по `docs/FEATURE_ARCHITECTURE_STANDARD.md`: + +```text +src/features/codeboarding/ + contracts/ + core/ + main/ + adapters/ + infrastructure/ + preload/ + renderer/ +``` + +Основные части: + +- contracts: DTO для status, install state, run request, run result, affected components; +- core: правила выбора режима `full`/`incremental`, debounce policy, overlay merge policy; +- main/infrastructure: binary detection, installer, command runner, output parser, `.codeboarding` reader; +- main/adapters/input: IPC handlers; +- preload: bridge; +- renderer: settings panel, project action, architecture map panel, task/review badges. + +Надо использовать path validation и не давать CodeBoarding работать вне выбранного project root. + +## MVP flow + +1. Пользователь открывает project. +2. UI показывает “Enable CodeBoarding architecture map”. +3. App проверяет наличие `codeboarding`. +4. Если нет, предлагает install. +5. После install запускает `codeboarding-setup`. +6. Первый запуск: `codeboarding full --local `. +7. App читает `.codeboarding/analysis.json`. +8. Показывает diagram/docs. +9. Когда агент меняет файлы, app быстро подсвечивает affected components по baseline mapping. +10. После debounce или завершения task запускает `codeboarding incremental --local `. +11. Если incremental возвращает `requiresFullAnalysis`, UI предлагает full refresh. + +## Риски + +- 🟠 LLM keys: без provider key full/incremental может не пройти. Нужен понятный setup и read-only detect. +- 🟠 Performance: full analysis может быть долгим. Нужны cancellation, queue, progress, timeout. +- 🟠 Dirty worktree: incremental умеет работать с worktree, но target refs и snapshots надо использовать аккуратно. +- 🟠 Cost: LLM вызовы могут стоить денег. Нужен явный opt-in и возможно “run on task complete” вместо постоянного refresh. +- 🟡 Security: не отправлять код в неизвестный сервис. CodeBoarding заявляет local processing plus direct provider API calls, но UX должен прямо показывать выбранный provider. +- 🟡 Generated files: `.codeboarding/` не всегда надо коммитить. Нужно дать настройку ignore/commit. +- 🟡 MCP: CodeBoarding-MCP выглядит сырым, поэтому не стоит брать его как основную интеграцию. + +## Рекомендация + +Делать поэтапно: + +1. MVP optional CLI runner и viewer. +2. Live-ish overlay на базе нашего task change ledger и CodeBoarding baseline. +3. Background incremental refresh. +4. Architecture Review per Task. +5. Только потом MCP/context tools для агентов. + +Самое ценное для пользователя: видеть не “агент изменил 12 файлов”, а “агент сейчас меняет Auth Runtime Detection и это затрагивает Provider Connection + Team Provisioning”. CodeBoarding может дать основу для такой карты, но realtime UX должен быть нашим. diff --git a/landing/assets/styles/brand-tokens.css b/landing/assets/styles/brand-tokens.css new file mode 100644 index 00000000..ee4ec4da --- /dev/null +++ b/landing/assets/styles/brand-tokens.css @@ -0,0 +1,136 @@ +:root { + color-scheme: light dark; + + --at-font-sans: "Inter", "Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, sans-serif; + --at-font-mono: "JetBrains Mono", "Fira Code", ui-monospace, SFMono-Regular, Menlo, monospace; + + --at-c-cyan: #00f0ff; + --at-c-cyan-strong: #00d4e6; + --at-c-cyan-deep: #0891b2; + --at-c-magenta: #ff00ff; + --at-c-green: #39ff14; + --at-c-gold: #ffd700; + --at-c-red: #ff4757; + + --at-c-dark-0: #05070b; + --at-c-dark-1: #0a0a0f; + --at-c-dark-2: #12121a; + --at-c-dark-3: #1e293b; + --at-c-light-0: #ffffff; + --at-c-light-1: #f8fafc; + --at-c-light-2: #f0f2f5; + + --at-c-text-dark-1: #e0e6ff; + --at-c-text-dark-2: #c8d6e5; + --at-c-text-dark-3: #a0a8c0; + --at-c-text-dark-muted: #8892b0; + --at-c-text-light-1: #1e293b; + --at-c-text-light-2: #475569; + --at-c-text-light-3: #64748b; + + --at-c-bg: var(--at-c-dark-1); + --at-c-bg-soft: rgba(10, 10, 15, 0.8); + --at-c-surface: var(--at-c-dark-2); + --at-c-surface-soft: rgba(10, 10, 15, 0.6); + --at-c-surface-raised: rgba(30, 41, 59, 0.78); + --at-c-text: var(--at-c-text-dark-1); + --at-c-text-soft: var(--at-c-text-dark-2); + --at-c-text-muted: var(--at-c-text-dark-muted); + --at-c-border: rgba(0, 240, 255, 0.12); + --at-c-border-strong: rgba(0, 240, 255, 0.28); + --at-c-focus: rgba(0, 240, 255, 0.55); + + --at-gradient-brand: linear-gradient(135deg, var(--at-c-cyan), var(--at-c-magenta)); + --at-gradient-brand-text: linear-gradient(135deg, #e0e6ff 0%, var(--at-c-cyan) 50%, var(--at-c-magenta) 100%); + --at-gradient-success: linear-gradient(135deg, var(--at-c-cyan), var(--at-c-green)); + --at-gradient-cyan-text: linear-gradient(135deg, #e0e6ff 0%, var(--at-c-cyan) 100%); + --at-gradient-panel: linear-gradient(135deg, rgba(0, 240, 255, 0.06), rgba(255, 0, 255, 0.035)); + + --at-radius-xs: 6px; + --at-radius-sm: 8px; + --at-radius-md: 10px; + --at-radius-lg: 12px; + --at-radius-xl: 16px; + --at-radius-2xl: 20px; + --at-radius-preview: 22px; + --at-radius-pill: 999px; + + --at-shadow-cyan-sm: 0 4px 20px rgba(0, 240, 255, 0.3); + --at-shadow-cyan-md: 0 8px 32px rgba(0, 240, 255, 0.08); + --at-shadow-cyan-lg: 0 20px 60px rgba(0, 0, 0, 0.55), 0 0 30px rgba(0, 240, 255, 0.06); + --at-shadow-card: 0 16px 32px -10px rgba(0, 0, 0, 0.35); + + --at-blur-sm: 8px; + --at-blur-md: 12px; + --at-blur-lg: 20px; + --at-glass-bg: rgba(10, 10, 15, 0.78); + --at-glass-bg-hover: rgba(10, 10, 15, 0.9); + --at-glass-border: 1px solid var(--at-c-border); + --at-glass-border-strong: 1px solid var(--at-c-border-strong); + + --at-grid-line: rgba(0, 240, 255, 0.03); + --at-scanline: rgba(0, 240, 255, 0.008); + --at-transition-fast: 0.15s ease; + --at-transition-base: 0.25s ease; + --at-transition-smooth: 0.35s cubic-bezier(0.4, 0, 0.2, 1); + + --at-z-header: 1000; +} + +.v-theme--light, +:root:not(.dark) { + --at-c-bg: var(--at-c-light-2); + --at-c-bg-soft: rgba(255, 255, 255, 0.82); + --at-c-surface: var(--at-c-light-0); + --at-c-surface-soft: rgba(255, 255, 255, 0.78); + --at-c-surface-raised: rgba(255, 255, 255, 0.92); + --at-c-text: var(--at-c-text-light-1); + --at-c-text-soft: var(--at-c-text-light-2); + --at-c-text-muted: var(--at-c-text-light-3); + --at-c-border: rgba(0, 0, 0, 0.08); + --at-c-border-strong: rgba(0, 139, 178, 0.3); + --at-c-focus: rgba(8, 145, 178, 0.5); + --at-glass-bg: rgba(255, 255, 255, 0.78); + --at-glass-bg-hover: rgba(255, 255, 255, 0.92); + --at-glass-border: 1px solid rgba(0, 0, 0, 0.08); + --at-glass-border-strong: 1px solid rgba(0, 139, 178, 0.25); + --at-shadow-card: 0 16px 32px -10px rgba(0, 0, 0, 0.12); + --at-shadow-cyan-lg: 0 20px 60px rgba(0, 180, 200, 0.12); + --at-grid-line: rgba(8, 145, 178, 0.045); +} + +.v-theme--dark, +.dark { + --at-c-bg: var(--at-c-dark-1); + --at-c-bg-soft: rgba(10, 10, 15, 0.8); + --at-c-surface: var(--at-c-dark-2); + --at-c-surface-soft: rgba(10, 10, 15, 0.6); + --at-c-surface-raised: rgba(30, 41, 59, 0.78); + --at-c-text: var(--at-c-text-dark-1); + --at-c-text-soft: var(--at-c-text-dark-2); + --at-c-text-muted: var(--at-c-text-dark-muted); + --at-c-border: rgba(0, 240, 255, 0.12); + --at-c-border-strong: rgba(0, 240, 255, 0.28); + --at-glass-bg: rgba(10, 10, 15, 0.78); + --at-glass-bg-hover: rgba(10, 10, 15, 0.92); +} + +.at-gradient-text { + background: var(--at-gradient-brand-text); + -webkit-background-clip: text; + background-clip: text; + -webkit-text-fill-color: transparent; +} + +.at-glass { + background: var(--at-glass-bg); + border: var(--at-glass-border); + backdrop-filter: blur(var(--at-blur-md)); + -webkit-backdrop-filter: blur(var(--at-blur-md)); + box-shadow: var(--at-shadow-cyan-md); +} + +.at-focus-ring:focus-visible { + outline: 2px solid var(--at-c-focus); + outline-offset: 3px; +} diff --git a/landing/assets/styles/main.scss b/landing/assets/styles/main.scss index 4f1ead04..85428476 100644 --- a/landing/assets/styles/main.scss +++ b/landing/assets/styles/main.scss @@ -1,10 +1,12 @@ +@import "./brand-tokens.css"; + :root { color-scheme: light dark; } body { margin: 0; - font-family: "Inter", "Segoe UI", system-ui, -apple-system, sans-serif; + font-family: var(--at-font-sans); background: rgb(var(--v-theme-background)); color: rgb(var(--v-theme-on-background)); } @@ -32,7 +34,7 @@ body { /* Monospace accent font for technical elements */ .mono { - font-family: "JetBrains Mono", "Fira Code", monospace; + font-family: var(--at-font-mono); } @media (max-width: 960px) { @@ -72,5 +74,5 @@ body { } .app-header { - backdrop-filter: blur(10px); + backdrop-filter: blur(var(--at-blur-md)); } diff --git a/landing/components/PageBackground.vue b/landing/components/PageBackground.vue index 6fa18bdc..2071bb88 100644 --- a/landing/components/PageBackground.vue +++ b/landing/components/PageBackground.vue @@ -26,8 +26,8 @@ position: absolute; inset: 0; background-image: - linear-gradient(rgba(0, 240, 255, 0.03) 1px, transparent 1px), - linear-gradient(90deg, rgba(0, 240, 255, 0.03) 1px, transparent 1px); + linear-gradient(var(--at-grid-line) 1px, transparent 1px), + linear-gradient(90deg, var(--at-grid-line) 1px, transparent 1px); background-size: 60px 60px; z-index: 1; } @@ -40,8 +40,8 @@ 0deg, transparent, transparent 2px, - rgba(0, 240, 255, 0.008) 2px, - rgba(0, 240, 255, 0.008) 4px + var(--at-scanline) 2px, + var(--at-scanline) 4px ); z-index: 2; } @@ -56,7 +56,7 @@ .page-bg__orb--1 { width: 900px; height: 900px; - background: #00f0ff; + background: var(--at-c-cyan); top: -200px; right: -150px; animation: orbDrift1 20s ease-in-out infinite; @@ -65,7 +65,7 @@ .page-bg__orb--2 { width: 700px; height: 700px; - background: #ff00ff; + background: var(--at-c-magenta); top: 300px; left: -200px; animation: orbDrift2 25s ease-in-out infinite; @@ -74,7 +74,7 @@ .page-bg__orb--3 { width: 800px; height: 800px; - background: #39ff14; + background: var(--at-c-green); top: 1200px; right: -100px; opacity: 0.05; @@ -84,7 +84,7 @@ .page-bg__orb--4 { width: 700px; height: 700px; - background: #00f0ff; + background: var(--at-c-cyan); top: 2100px; left: -150px; opacity: 0.06; @@ -94,7 +94,7 @@ .page-bg__orb--5 { width: 750px; height: 750px; - background: #ff00ff; + background: var(--at-c-magenta); top: 2900px; right: -120px; opacity: 0.05; @@ -104,7 +104,7 @@ .page-bg__orb--6 { width: 700px; height: 700px; - background: #ffd700; + background: var(--at-c-gold); top: 3600px; left: -100px; opacity: 0.04; @@ -114,7 +114,7 @@ .page-bg__orb--7 { width: 650px; height: 650px; - background: #00f0ff; + background: var(--at-c-cyan); top: 4300px; right: -80px; opacity: 0.05; diff --git a/landing/components/layout/AppFooter.vue b/landing/components/layout/AppFooter.vue index 74cb7a7d..76c83732 100644 --- a/landing/components/layout/AppFooter.vue +++ b/landing/components/layout/AppFooter.vue @@ -1,7 +1,12 @@