Перейти к содержимому
TSMC

Разработка

Нужны Node.js ≥ 24 и pnpm.

Окно терминала
pnpm install
pnpm build   # собрать веб-интерфейс и CLI (packages/cli/dist)
pnpm start   # http://127.0.0.1:3000, данные в data/tsmc.db

Разработка: pnpm dev (API на :3000, интерфейс с hot reload на http://localhost:5173).

Проверки:

Окно терминала
pnpm typecheck
pnpm test        # unit- и API-тесты (vitest)
pnpm e2e         # сборка интерфейса и браузерные тесты (Playwright) на демо-данных

Для pnpm e2e нужен браузер: pnpm --filter @tsmc/e2e exec playwright install chromium или установленный Chrome/Edge через PW_CHANNEL=chrome / PW_CHANNEL=msedge.

CI (GitHub Actions, .github/workflows/ci.yml) на каждый push и PR запускает проверку типов, тесты, браузерные тесты и собирает Docker-образ с проверкой запуска. Из main образ публикуется как ghcr.io/<владелец>/tsmc:latest, из тегов v* — с номером версии. Отчёт упавших браузерных тестов сохраняется артефактом playwright-report.

При первом открытии интерфейс предложит создать администратора.

Порядок работы с ветками

Заголовок раздела «Порядок работы с ветками»

Каждый этап разрабатывается в отдельной ветке stage-N-<name>, создаваемой от актуального main. По завершении этапа ветка вливается в main через --no-ff, поэтому граница каждого этапа видна в истории. Ветки этапов не удаляются.

Документация

Заголовок раздела «Документация»

Этот сайт — пакет packages/site (Astro Starlight): страницы на русском лежат в src/content/docs, на английском — в src/content/docs/en. Правка документации идёт в том же pull request, что и изменение кода.

Окно терминала
pnpm --filter @tsmc/site dev     # http://localhost:4321 с перезагрузкой при правке
pnpm --filter @tsmc/site build   # сборка в packages/site/dist

Справочники собираются из кода скриптом scripts/generate.ts перед каждой сборкой: маршруты API с ролями и полями запроса, справка CLI и список изменений по слитым pull request. Сборка падает, если:

  • у маршрута API нет описания в src/api-docs.ts (или описан маршрут, которого уже нет);
  • переменная TSMC_*, которую читает сервер или CLI, не описана в Переменные окружения;
  • ссылка между страницами ведёт в никуда.

Workflow .github/workflows/docs.yml собирает сайт на каждом pull request и публикует его на Cloudflare Pages: main — как сам сайт, pull request — как превью своей ветки (нужны секреты CLOUDFLARE_API_TOKEN и CLOUDFLARE_ACCOUNT_ID).

Публикация на Cloudflare Pages

Заголовок раздела «Публикация на Cloudflare Pages»
  1. Войдите на dash.cloudflare.com (бесплатного тарифа достаточно).
  2. ID аккаунта: на главной странице панели, в меню аккаунта «Copy account ID» или в адресе dash.cloudflare.com/<ID аккаунта>/… — строка из 32 символов.
  3. API-токен: значок профиля → My Profile → API Tokens → Create Token → Create Custom Token. Имя — например, tsmc docs from GitHub; Permissions: Account · Cloudflare Pages · Edit; Account Resources: Include · ваш аккаунт. Continue to summary → Create Token, скопируйте токен — он показывается один раз.
  4. Секреты репозитория: GitHub → Settings → Secrets and variables → Actions → New repository secret: CLOUDFLARE_API_TOKEN (токен) и CLOUDFLARE_ACCOUNT_ID (ID аккаунта).
  5. Первая публикация: Actions → Docs → Run workflow на main (или следующее слияние в main). Проект tsmc-docs создаётся сам, адрес сайта — в выводе шага «Publish to Cloudflare Pages», обычно https://tsmc-docs.pages.dev (если имя занято, Cloudflare добавит к нему суффикс).
  6. Адрес сайта: Settings → Secrets and variables → Actions → Variables → New repository variable DOCS_URL с этим адресом — по нему строятся канонические ссылки и карта сайта.

Превью pull request — по адресу https://<ветка>.tsmc-docs.pages.dev. Чтобы сайт видели только свои, его можно закрыть входом через Cloudflare Access (Zero Trust → Access → Applications), бесплатно для небольших команд.

Главная страница сайта — визитка продукта (src/landing, тексты на двух языках в content.ts). Скриншоты на ней — настоящий интерфейс на демо-данных; после заметных изменений интерфейса их снимают заново:

Окно терминала
pnpm build && pnpm --filter @tsmc/e2e screens   # PW_CHANNEL=msedge|chrome — установленный браузер

Скрипт сам поднимает демо-сервер и кладёт снимки в packages/site/public/screens/{ru,en}.

Astro загружает нативные модули (компилятор, разбор Markdown). На Windows их может заблокировать политика контроля приложений (Smart App Control) или не найтись Microsoft Visual C++ Redistributable (x64) — тогда сайт локально не соберётся. Его всегда собирает CI: готовую сборку можно скачать из запуска workflow (артефакт docs-site).