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