kodu 2.2.0 → 3.0.2

package/skills/litefront-prototype/SKILL.md

@@ -1,484 +0,0 @@
----
-name: litefront-prototype
-description: >
-  Создание интерактивных прототипов на базе LiteFront (Vite, React 19, TanStack Router,
-  URQL, FSD, Tailwind v4 + DaisyUI v5). Приоритет: скорость прототипирования
-  и визуальное качество через существующую инфраструктуру проекта.
----
-
-# LiteFront Prototype Skill
-
-> **ПРОТОТИП — всё симулируется.** Нет реального бэкенда, нет реального API, нет реальной авторизации, нет реальной загрузки файлов. Цель — интерактивный UI, который работает офлайн без внешних зависимостей.
-
-## Правила прототипа (строго соблюдать)
-
-| Что | Правило |
-|-----|---------|
-| **Авторизация** | `VITE_MOCK_AUTH=true` → `MockAuthProvider`. **Не подключать** Logto / любой OIDC-сервер |
-| **GraphQL API** | Только `createMockExchange` — никаких реальных HTTP-запросов к бэкенду |
-| **Загрузка файлов** | Симулировать через `mockUpload` — никакого реального upload-сервера |
-| **Внешние сервисы** | Любые внешние вызовы — только через моки в памяти |
-| **Генерация типов** | `npm run gen` не нужен — типы писать вручную |
-| **Переменные окружения** | `VITE_GRAPHQL_API_URL` и другие API-переменные игнорируются при мокинге |
-
----
-
-## Директория и инициализация
-
-Все файлы создавать внутри папки **`prototype/`**.
-
-Если `prototype/` пуста или не существует — инициализируй через LiteFront:
-
-```bash
-npx degit uxname/litefront prototype
-cd prototype
-npm install
-cp .env.example .env
-```
-
-Сразу после инициализации добавить в `.env`:
-```
-VITE_MOCK_AUTH=true
-```
-
-**После инициализации (обязательно):**
-1. **Прочитай `prototype/AGENTS.md`** — главный источник конвенций проекта: структура файлов, архитектура, команды, паттерны кода. Без этого нельзя правильно генерировать код.
-2. Изучи `src/` — какие слои FSD уже есть, какие компоненты существуют.
-3. Проверь `package.json` — список доступных скриптов и зависимостей.
-4. Убедись, что в `.env` установлено `VITE_MOCK_AUTH=true`.
-
-## Технологический стек
-
-| Слой | Технология |
-|------|-----------|
-| **Билд** | Vite 8 + React 19 + TypeScript 6 (strict) |
-| **Роутинг** | TanStack Router v1 (file-based, авто-код-сплиттинг) |
-| **Данные** | URQL + `createMockExchange` (никакого реального GraphQL API) |
-| **Стейт** | Zustand 5 (локальный), URQL с моками (серверный) |
-| **Стили** | Tailwind v4 + DaisyUI v5 (themes: cmyk / dark) |
-| **Аутентификация** | `MockAuthProvider` через `VITE_MOCK_AUTH=true` (без реального OIDC) |
-| **i18n** | ParaglideJS (Inlang), `messages/{locale}.json` |
-| **UI-кит** | DaisyUI, Lucide-React (иконки), Sonner (тосты) |
-| **Архитектура** | Feature-Sliced Design (FSD) |
-
-## Архитектура FSD (Feature-Sliced Design)
-
-```
-src/
-├── app/           # Инициализация, провайдеры, ErrorBoundary
-├── entities/      # Бизнес-сущности (counter, user, project…)
-├── features/      # Пользовательские сценарии (auth, createProject…)
-├── pages/         # Компоненты страниц
-├── routes/        # Определения роутов TanStack Router
-├── shared/        # Переиспользуемое: api, ui, config, lib
-├── widgets/       # Композиционные блоки (Header, Sidebar…)
-├── graphql/       # .graphql-файлы (queries/, mutations/, fragments/)
-└── generated/     # Авто-генерация (роуты, GraphQL-типы)
-```
-
-**Правила FSD:**
-- Слой может импортировать только нижележащие слои: `pages` → `widgets` → `features` → `entities` → `shared`.
-- Слайс (папка внутри слоя) не импортирует другие слайсы того же слоя.
-- Публичное API слайса — через `index.ts` (barrel export).
-
-**Path aliases** (уже настроены в `tsconfig.json`):
-`@shared/*`, `@entities/*`, `@features/*`, `@widgets/*`, `@pages/*`, `@generated/*`, `@public/*`
-
----
-
-## 1. Существующие компоненты (уже есть в проекте)
-
-Не создавай их заново — используй готовые:
-
-- **`@features/auth`** — `useAuth()`, `AuthGuard`, `MockAuthProvider`
-- **`@entities/counter`** — `useCounterStore`, `Counter`
-- **`@widgets/Header`** — `Header`
-- **`@shared/ui/ErrorFallback`** — готовая страница ошибки с категориями (AUTH, ACCESS, NETWORK, SERVER, UNKNOWN)
-- **`@shared/ui/Toaster`** — `toast` из Sonner + кастомные стили
-- **`@pages/404`** — страница 404
-
-## 2. Роутинг (TanStack Router)
-
-Файлы роутов — в `src/routes/`. Роуты разделяют логику (`index.tsx`) и ленивый компонент (`index.lazy.tsx`).
-
-**Новый роут:**
-```tsx
-// src/routes/projects.tsx
-import { createFileRoute } from '@tanstack/react-router';
-
-export const Route = createFileRoute('/projects')({
-  head: () => ({
-    meta: [
-      { title: 'Projects | LiteFront' },
-      { name: 'description', content: 'Manage projects' },
-    ],
-  }),
-});
-```
-
-```tsx
-// src/routes/projects.lazy.tsx
-import { ProjectsPage } from '@pages/projects';
-import { createLazyFileRoute } from '@tanstack/react-router';
-
-export const Route = createLazyFileRoute('/projects')({
-  component: ProjectsPage,
-});
-```
-
-**Страница:**
-```tsx
-// src/pages/projects/ui/index.tsx
-import { useAuth } from '@features/auth';
-import { Link, useNavigate } from '@tanstack/react-router';
-import { Plus } from 'lucide-react';
-
-export function ProjectsPage() {
-  const auth = useAuth();
-  const navigate = useNavigate();
-
-  return (
-    <div>
-      <div className="flex items-center justify-between mb-6">
-        <h1 className="text-2xl font-bold">Projects</h1>
-        <button onClick={() => navigate({ to: '/projects/new' })}
-                className="btn btn-primary">
-          <Plus className="size-4" /> New
-        </button>
-      </div>
-      {auth.isAuthenticated && (
-        <p className="text-sm text-base-content/60 mb-4">
-          Signed in as {auth.user?.profile?.email}
-        </p>
-      )}
-      <Link to="/projects/$id" params={{ id: '123' }}>Project</Link>
-    </div>
-  );
-}
-```
-
-**Auth guard на роут (симулированный):**
-```tsx
-// src/routes/protected/index.tsx
-import { createFileRoute, redirect } from '@tanstack/react-router';
-
-export const Route = createFileRoute('/protected/')({
-  beforeLoad: ({ context }) => {
-    if (!context.auth.isAuthenticated) {
-      throw redirect({ to: '/' });
-    }
-  },
-});
-```
-
-С `VITE_MOCK_AUTH=true` `context.auth.isAuthenticated` всегда `true` — редирект не произойдёт.
-
-**Навигация в коде:** `useNavigate()` из `@tanstack/react-router`.
-**Запрещено** использовать `<a href>`.
-
-**После создания нового файла роута — запусти `npm run gen:routes`**
-для перегенерации `src/generated/routeTree.gen.ts`.
-
-## 3. Авторизация (только симуляция)
-
-`VITE_MOCK_AUTH=true` в `.env` активирует `MockAuthProvider` из `@features/auth`.
-**Не подключать** реальный OIDC-сервер (Logto или любой другой) — прототип работает без него.
-
-```tsx
-// Мок-пользователь доступен сразу без логина:
-const auth = useAuth();
-// auth.isAuthenticated === true
-// auth.user?.profile?.email === 'mock@example.com'
-```
-
-`AuthGuard` и защищённые роуты работают через мок — дополнительной настройки не нужно.
-
-## 4. Данные (только моки, без GraphQL API)
-
-В прототипе **нет реального GraphQL API**. Все данные хранятся в памяти и возвращаются через `createMockExchange`.
-Никаких HTTP-запросов к бэкенду. `npm run gen` не нужен.
-
-### Mock exchange
-
-```ts
-// src/shared/api/mock-exchange.ts
-import { Exchange, makeResult } from 'urql';
-import { pipe, mergeMap, fromValue } from 'wonka';
-
-type Mocks = Record<
-  string,
-  (variables?: Record<string, unknown>) => Record<string, unknown>
->;
-
-export const createMockExchange = (mocks: Mocks): Exchange => {
-  return ({ forward }) => (ops$) =>
-    pipe(
-      ops$,
-      mergeMap((operation) => {
-        const queryName = operation.query.definitions[0]?.name?.value;
-        const handler = queryName ? mocks[queryName] : undefined;
-
-        if (handler) {
-          const data = handler(operation.variables as Record<string, unknown>);
-          return fromValue(makeResult(operation, { data }));
-        }
-
-        return pipe(fromValue(operation), forward);
-      }),
-    );
-};
-```
-
-### Подключение в GraphQL-клиент
-
-```ts
-// src/shared/api/graphql-client.ts
-import { createMockExchange } from './mock-exchange';
-import type { Mocks } from './mock-exchange';
-
-export const createGraphQLClient = (
-  accessToken?: string,
-  mocks?: Mocks,
-): Client => {
-  const exchanges = [
-    cacheExchange,
-    errorExchange({ onError: (error) => { /* ... */ } }),
-  ];
-
-  if (mocks) exchanges.push(createMockExchange(mocks));
-
-  exchanges.push(fetchExchange);
-
-  return new Client({
-    url: import.meta.env.VITE_GRAPHQL_API_URL,
-    exchanges,
-    fetchOptions: {
-      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
-    },
-    requestPolicy: 'cache-and-network',
-  });
-};
-```
-
-### Мок-данные в `__root.tsx`
-
-```tsx
-// src/routes/__root.tsx
-import { GraphQLProvider, createGraphQLClient } from '@shared/api';
-
-const mockData = {
-  GetProjects: () => ({
-    projects: [
-      { id: 'p-1', name: 'Project Alpha', status: 'active' },
-      { id: 'p-2', name: 'Project Beta', status: 'draft' },
-    ],
-  }),
-  CreateProject: (vars) => ({
-    createProject: { id: 'p-new', name: vars?.input?.name || 'New' },
-  }),
-};
-
-function RootComponent() {
-  const auth = useAuth();
-  const client = useMemo(
-    () => createGraphQLClient(auth.user?.id_token, mockData),
-    [auth.user?.id_token],
-  );
-  // ...
-}
-```
-
-### Пример компонента с мок-данными
-
-```tsx
-import { useGetProjectsQuery } from '@generated/graphql';
-
-function ProjectsList() {
-  const [{ data, fetching, error }] = useGetProjectsQuery();
-
-  if (fetching) return <span className="loading loading-spinner loading-lg" />;
-  if (error) return <p className="text-error">{error.message}</p>;
-  if (!data?.projects.length)
-    return (
-      <div className="text-center py-20 bg-base-100 rounded-xl border-2 border-dashed border-base-300">
-        <p className="text-base-content/50">No projects yet</p>
-      </div>
-    );
-
-  return (
-    <div className="overflow-x-auto bg-base-100 rounded-xl shadow-sm border border-base-300">
-      <table className="table table-zebra">
-        <thead>
-          <tr>
-            <th>Name</th>
-          </tr>
-        </thead>
-        <tbody>
-          {data.projects.map((project) => (
-            <tr key={project.id} className="hover">
-              <td>{project.name}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </div>
-  );
-}
-```
-
-### Правила мок-данных
-
-1. Все данные — в памяти, никаких внешних сервисов.
-2. UI должен выглядеть как с реальными данными: таблицы непустые, навигация работает, тосты показываются.
-3. Для списков — минимум 2–3 элемента (не пусто, не единичная запись).
-4. Состояния loading/empty/error должны быть визуально видны при соответствующих условиях.
-
-### Типы без codegen
-
-`npm run gen` не нужен. Типы писать вручную:
-
-```ts
-// src/shared/api/mock-types.ts
-export interface Project {
-  id: string;
-  name: string;
-  status: 'active' | 'draft' | 'archived';
-}
-```
-
-Либо использовать локальную схему в `codegen.yml`:
-```yaml
-schema: "./src/generated/schema.graphql"
-documents: "./src/graphql/**/*.graphql"
-```
-
-## 5. Загрузка файлов (только симуляция)
-
-В прототипе файлы **не загружаются на сервер**. Симулировать через `mockUpload`:
-
-```ts
-// src/shared/api/mock-upload.ts
-export async function mockUpload(file: File): Promise<{ url: string; name: string }> {
-  await new Promise((r) => setTimeout(r, 800)); // имитация задержки
-  return {
-    url: URL.createObjectURL(file), // временный локальный URL для превью
-    name: file.name,
-  };
-}
-```
-
-```tsx
-import { mockUpload } from '@shared/api/mock-upload';
-import { toast } from '@shared/ui/Toaster';
-
-function FileUploader() {
-  const [preview, setPreview] = useState<string | null>(null);
-
-  const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
-    const file = e.target.files?.[0];
-    if (!file) return;
-    const result = await mockUpload(file);
-    setPreview(result.url);
-    toast.success(`Файл загружен: ${result.name}`);
-  };
-
-  return (
-    <div>
-      <input type="file" onChange={handleFile} className="file-input file-input-bordered" />
-      {preview && <img src={preview} alt="preview" className="mt-2 max-h-48 rounded-lg" />}
-    </div>
-  );
-}
-```
-
-Для файлов не-изображений — показывать имя и размер, возвращать мок-URL `/mock/uploaded/<filename>`.
-
-## 6. Локальный стейт (Zustand)
-
-Для стейта, который не идёт через GraphQL:
-
-```tsx
-import { create } from 'zustand';
-import { devtools } from 'zustand/middleware';
-
-interface UIState {
-  sidebarOpen: boolean;
-  toggleSidebar: () => void;
-}
-
-export const useUIStore = create(
-  devtools<UIState>((set) => ({
-    sidebarOpen: false,
-    toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
-  })),
-);
-```
-
-## 7. Стили (Tailwind + DaisyUI)
-
-- **DaisyUI:** `btn`, `card`, `input`, `badge`, `modal`, `table`, `table-zebra`, `loading loading-spinner`, `toggle`, `select`, `alert`, `avatar`, `tooltip`.
-- **Модалки:** используй тег `<dialog>` + `useRef`. Открытие: `.showModal()`.
-  Закрытие: `<form method="dialog">`.
-- **Иконки:** `lucide-react`.
-- **Темы:** `cmyk` (светлая, по умолчанию), `dark` (тёмная, prefers-color-scheme).
-  DaisyUI-темы подключаются через атрибут `data-theme` на `<html>`.
-- **Цвета DaisyUI:** `bg-base-100`, `text-base-content`, `text-primary`,
-  `border-base-300`, `bg-primary`, `text-primary-content` и т.д.
-  Не используй хардкодные цвета — только семантические токены темы.
-
-## 8. i18n (ParaglideJS)
-
-Сообщения — в `messages/{locale}.json`. Используй готовые или добавляй новые.
-
-```json
-{
-  "projects_title": "Projects",
-  "project_created": "Project created successfully"
-}
-```
-
-Импорт в коде:
-```tsx
-import * as m from '@generated/paraglide/messages';
-// m.projects_title() → "Projects"
-```
-
-Для прототипа i18n можно временно пропустить — используй прямые строки.
-
-## 9. Порядок действий при генерации кода
-
-1. **Прочитай `prototype/AGENTS.md`** — конвенции проекта, структура, паттерны.
-2. Изучи структуру `src/` — какие слайсы FSD уже есть.
-3. Определи, в какой слой FSD ложится новая фича.
-4. **Настрой моки данных** — все операции через `createMockExchange` (никаких реальных API-вызовов).
-5. **Авторизация — только через `VITE_MOCK_AUTH=true`**, не подключать Logto.
-6. **Загрузка файлов — только через `mockUpload`**, без реального сервера.
-7. Добавь мок-данные для новых операций в `mockData` в `__root.tsx`.
-8. Используй существующие компоненты где возможно.
-9. Следуй паттернам из существующих страниц.
-
-## 10. Команды
-
-```bash
-npm run start:dev    # Dev-сервер (localhost:3000)
-npm run gen:routes   # Генерация routeTree.gen.ts (нужен после нового роута)
-npm run check        # Линтинг + typecheck + Knip
-npm run lint:fix     # Biome с автофиксом
-npm run build        # Production-сборка
-npm run test:dev     # Тесты (Vitest, watch)
-npm run test:e2e:dev # Playwright UI mode
-```
-
-`npm run gen` (GraphQL codegen) в прототипе **не нужен** — типы пишутся вручную.
-
-## 11. Формат ответа
-
-Отвечай **только** блоками кода. Перед каждым блоком указывай путь
-(относительно `prototype/`). Выводи файлы целиком.
-
-```
-**`src/pages/projects/ui/index.tsx`**
-\`\`\`tsx
-// полный код файла
-\`\`\`
-```

package/skills/ops/SKILL.md

@@ -1,94 +0,0 @@
----
-name: ops
-description: >
-  Работа с проектами и стендами (local/dev/stage/prod) из любого места: глобальный
-  реестр проектов, активный стенд, деплой по runbook. Запускай при /ops или запросах
-  «задеплой X на dev», «переключи стенд», «как деплоить этот проект», «добавь проект»,
-  «куда деплоить», «покажи мои проекты».
-metadata:
-  level: multi
-  output: ~/.config/kodu/registry.json + <project>/.runbook/
----
-
-# Навык ops — стенды и деплой
-
-Этот навык помогает работать со **стендами** проектов: local, dev, stage, prod.
-Он рассчитан на джунов: **тебе не нужно руками править никакие JSON-файлы** — просто
-скажи агенту, что хочешь, а агент сам выполнит нужную команду `kodu ops` или поправит
-файл за тебя.
-
-## Главные понятия (простыми словами)
-
-- **Стенд** — это окружение, куда мы что-то запускаем: `local` (твой компьютер),
-  `dev` (тестовый сервер), `stage` (предпрод), `prod` (боевой, осторожно!).
-- **Реестр** — общий список всех проектов на твоей машине. Файл:
-  `~/.config/kodu/registry.json`. Создаётся сам. Благодаря ему `kodu` находит проект
-  по имени **из любой папки**.
-- **Runbook** — файл `.runbook/runbook.md` внутри проекта, где по шагам расписано,
-  как работать с каждым стендом (куда зайти, какой `docker compose` запустить, как
-  склонировать репозиторий). Лежит в `.gitignore` и **не коммитится**.
-- **Активный стенд** — текущий стенд, с которым ты работаешь. Хранится в
-  `.runbook/config.json`.
-
-## Команды `kodu`, на которые опирается навык
-
-| Команда | Что делает |
-|---|---|
-| `kodu ops init` | Настроить стенды в текущем проекте (создаёт `.runbook/`, чинит `.gitignore`, добавляет проект в реестр) |
-| `kodu ops list` | Показать все проекты и их активные стенды |
-| `kodu ops add <name> --path <dir>` | Зарегистрировать проект под уникальным именем |
-| `kodu ops status [name]` | Показать активный стенд проекта |
-| `kodu ops use <stand>` | Переключить активный стенд (в текущем проекте) |
-| `kodu ops use <name> <stand>` | Переключить активный стенд указанного проекта (из любого места) |
-| `kodu ops path <name>` | Напечатать путь к репозиторию (удобно: `cd $(kodu ops path my-api)`) |
-| `kodu ops runbook <name> [stand]` | Показать инструкции по стенду |
-
-## Создание и изменение конфига по запросу (ключевой раздел)
-
-**Никогда не заставляй пользователя редактировать JSON руками.** Когда он просит
-что-то изменить — сам выполни команду или отредактируй файл, потом покажи результат
-человеческим языком.
-
-| Что говорит пользователь | Что делает агент |
-|---|---|
-| «добавь проект my-api, он в ~/work/my-api» | `kodu ops add my-api --path ~/work/my-api` |
-| «настрой стенды здесь» / «инициализируй проект» | `kodu ops init` (из папки проекта), помочь заполнить runbook |
-| «переключи меня на dev» | `kodu ops use dev` |
-| «переключи billing на prod» | `kodu ops use billing prod` (спросить подтверждение, т.к. prod) |
-| «добавь стенд stage в этот проект» | `kodu ops use stage` (стенд добавится автоматически) либо поправить `.runbook/config.json` |
-| «поменяй путь к проекту billing на …» | поправить запись в `~/.config/kodu/registry.json` за пользователя |
-| «какие у меня проекты / стенды?» | `kodu ops list` или `kodu ops status` |
-| «где лежит проект X?» | `kodu ops path X` |
-
-После любого изменения — кратко скажи: **что поменял и зачем**, и при необходимости
-покажи `kodu ops status`.
-
-## Как задеплоить проект на стенд
-
-1. Найди проект: `kodu ops path <name>` (получишь путь) или работай в его папке.
-2. Прочитай инструкции стенда: `kodu ops runbook <name> <stand>` (или открой
-   `.runbook/runbook.md`).
-3. Выполни шаги из runbook по порядку (git, `docker compose`, ssh и т.д.).
-   **Перед каждой опасной командой покажи её пользователю.**
-4. Если в runbook остались плейсхолдеры `<...>` — попроси у пользователя детали и
-   помоги заполнить файл.
-
-## Bootstrap нового проекта
-
-Если в проекте ещё нет `.runbook/`:
-1. Из папки проекта выполни `kodu ops init` (можно `--name <имя>`, если имя папки
-   не подходит).
-2. Простыми словами объясни джуну, что появилось: папка `.runbook/` с `config.json`
-   (активный стенд) и `runbook.md` (инструкции), и что `.runbook/` уже добавлен в
-   `.gitignore`.
-3. Помоги заполнить `runbook.md` под реальную инфраструктуру.
-
-## Гард-рейлы (обязательно)
-
-- **prod — только с подтверждением.** Перед любым действием на стенде `prod`
-  явно спроси: «Точно деплоим на prod?».
-- **`.gitignore` — автоматически.** Папка `.runbook/` всегда должна быть в
-  `.gitignore`; `kodu ops init` делает это сам. Никогда не коммить `.runbook/`.
-- **Показывай команды.** Перед `docker compose down`, удалением, миграциями и
-  прочими необратимыми шагами — покажи команду пользователю.
-- **Объясняй изменения.** На каждое изменение конфига — одна строка «что и зачем».