Пост @Ra2007 — Open source — 28.05 18:09 / Хабр

Ra2007

28 мая в 18:095.5K

Open source * Программирование * Node.JS * Системы сборки * TypeScript *

archkit v0.1 — генератор TypeScript-библиотек с Clean Architecture: от спека до npm за один день

Неделю назад опубликовал на npm первый пакет, @autosergach/archkit. Одна команда:

npx @autosergach/archkit create my-lib

И получаешь TypeScript-библиотеку с Clean Architecture из коробки: domain, application, ports, рабочий use case и пять зелёных тестов. Не «hello world», а каркас который показывает как слои должны выглядеть. Ниже как это устроено и четыре грабли по дороге к npm publish.

Что внутри

my-lib/
├── src/
│   ├── domain/      # User, DomainError
│   ├── application/ # createUser use case
│   ├── ports/       # UserRepository interface
│   └── index.ts
├── tests/           # InMemoryUserRepository + 5 тестов
└── package.json     # ESM, strict TS, vitest 3, eslint 9

pnpm install && pnpm test, пять зелёных с первого запуска. Стек намеренно современный: ESM only, Node 20+, TypeScript 5.7+, vitest 3.2, eslint 9 flat config.

Архитектура изнутри

Забавно, что archkit изнутри устроен точно так же, как проект который генерирует: порты и адаптеры до мозга костей. Монорепо: приватный archkit-core (весь движок) и @autosergach/archkit (то что на npm). tsup бандлит core через noExternal, потребитель ставит один пакет.

FileSystemPort с двумя адаптерами: InMemoryFileSystemAdapter для тестов и NodeFileSystemAdapter для продакшена. Pipeline в три шага: buildInitPlan, renderTemplate, executePlan. С --dry-run третий шаг не выполняется.

Тесты: 35 + 3

35 unit-тестов гоняют весь движок через in-memory, без диска, меньше секунды на весь suite. 3 e2e-теста запускают настоящий pnpm install && pnpm test в os.tmpdir(). Именно они дают уверенность что сгенерированный проект работает у пользователя, и поймали несколько багов в шаблоне до публикации.

Один день с Claude Code

Весь v0.1.1, от пустой папки до npm publish, написал за одну сессию, примерно шесть часов. 9 атомарных коммитов: Claude Code писал код, я проверял и коммитил. До Claude Code такой объём занял бы неделю, и тесты я бы срезал.

4 урока из npm publish

1. cac и --no-X флаги. При --skip-install cac выставляет skipInstall: true по умолчанию, неявно. Фикс: проверять === true, а не !== undefined. Потерял час пока разобрался.

2. npm проверяет similarity, а не только занятость. archkit свободное имя, но npm отклонил из-за заброшенного arch-kit (2022, 12 загрузок). Ушёл в scoped namespace @autosergach/archkit, зато все следующие пакеты там же.

3. workspace:* в dependencies. Приватного archkit-core нет в registry. Если он в dependencies, npm падает при install у потребителя. Перенести в devDependencies, tsup бандлит его в dist.

4. Granular npm tokens и 2FA. Granular-токен с правами publish не проходит без «Bypass 2FA for publish». Опция выключена по умолчанию, нигде не выделена жирным. Получил 403.

Что дальше

v0.2: NestJS плюс React fullstack шаблон и --ai-ready флаг, который автогенерирует CLAUDE.md, .claude/settings.json, agents.md. Пишите в Issues если есть что сказать.

npm: https://www.npmjs.com/package/@autosergach/archkit
GitHub: https://github.com/autosergach/archkit

npx @autosergach/archkit create my-lib
cd my-lib && pnpm install && pnpm test
# → 5 passing