@kuyper/harness 0.1.0 → 0.1.1

package/README.md

@@ -18,6 +18,14 @@ Requisitos: Node.js 20 ou posterior, pnpm 9 ou posterior, Git e um repositório
 remoto chamado `origin`. O MVP assume uma pessoa, branches literais `main` e
 `dev`, e GitHub como remoto.
 
+**Versão mínima suportada e versão de certificação são coisas diferentes.** O
+mínimo acima é o que o pacote declara em `engines`. A jornada do guia 1 foi
+executada literalmente com **pnpm 12.4.2** — é essa a versão reproduzível do
+bootstrap. Atualize o pnpm **antes** de criar o projeto: depois do `pnpm init` a
+versão fica fixada no campo `packageManager` do projeto, e trocá-la no meio do
+caminho quebra os quatro gates. O passo 0 de
+[Começar um projeto](docs/guia/01-comecar.md) mostra a ordem correta.
+
 As oito interfaces públicas são `init`, `generate`, `validate`, `integrate`,
 `publish`, `update`, `rule` e `skill`. Invoque sempre o binário instalado no
 projeto:

package/dist/init.js

@@ -229,7 +229,9 @@ export async function init(options = {}) {
     await writeFileAtomic(join(kuyperDir, 'project', 'rules', 'sobre-o-projeto.md'), projectRuleContent);
     await writeFileAtomic(join(kuyperDir, 'STATE.md'), stateMd(todayIso()));
     await copyCoreTree(options.packageCoreDir ?? packageCorePath(), join(kuyperDir, 'core'));
-    await generate(options.packageCoreDir === undefined ? { projectRoot } : { projectRoot, packageCoreDir: options.packageCoreDir });
+    await generate(options.packageCoreDir === undefined
+        ? { projectRoot, silent: true }
+        : { projectRoot, packageCoreDir: options.packageCoreDir, silent: true });
     const pkgWithPrepare = { ...pkg, scripts: { ...pkg.scripts, prepare: PREPARE_SCRIPT } };
     await writeFileAtomic(packageJsonPath, `${JSON.stringify(pkgWithPrepare, null, 2)}\n`);
     const claudeEnabled = providers.includes('claude');

package/dist/update.js

@@ -315,7 +315,11 @@ export async function update(options = {}) {
             refuseR21CoreEdited(diffKeys(L, D).map((k) => join(CORE_REL, k)));
         }
     }
-    await generate({ projectRoot, ...(options.packageCoreDir !== undefined ? { packageCoreDir: options.packageCoreDir } : {}) });
+    await generate({
+        projectRoot,
+        silent: true,
+        ...(options.packageCoreDir !== undefined ? { packageCoreDir: options.packageCoreDir } : {}),
+    });
     const dirtyAfterGenerate = await dirtyPaths(projectRoot);
     if (dirtyAfterGenerate.length > 0)
         refuseR21PendingWrites(dirtyAfterGenerate);
@@ -413,7 +417,7 @@ export async function continueUpdate(options = {}) {
             refuseOrphanReplaces(rule, target);
         }
     }
-    const generateReport = await generate({ projectRoot, packageCoreDir });
+    const generateReport = await generate({ projectRoot, packageCoreDir, silent: true });
     const validateReport = await validate({ projectRoot, packageCoreDir, silent: true });
     if (validateReport.code !== 0) {
         refuseValidateInconsistent(validateReport.code === 1 ? validateReport.reason : validateReport.findings.join('; '));

package/docs/guia/01-comecar.md

@@ -4,16 +4,171 @@ Esta é a jornada completa, do repositório vazio à primeira publicação. O
 Harness não instala TypeScript, ESLint ou Vitest: os passos abaixo fazem isso
 explicitamente antes do `init`.
 
-Antes de começar, configure sua identidade do Git e a autenticação SSH do
-GitHub. Estes comandos precisam imprimir seu nome e e-mail; se não imprimirem,
-configure-os com `git config --global user.name "Seu Nome"` e
-`git config --global user.email "voce@example.com"`:
+**Como ler os blocos de comando:** cada bloco é uma colagem — copie inteiro,
+cole, execute. Onde é preciso ler a saída antes de continuar, o bloco vem
+sozinho e o texto diz o que observar. Nenhum bloco para sozinho no meio se um
+comando falhar, então confira o resultado de um antes de colar o próximo.
+
+## 0. Preparar o ambiente
+
+Três coisas precisam estar prontas **antes do primeiro commit**: a versão do
+pnpm, a identidade do Git e a autenticação do GitHub. Mudar qualquer uma delas
+depois não altera o que já foi feito — commits já criados mantêm o autor
+antigo, e trocar de pnpm no meio do bootstrap quebra os gates.
+
+### Versão do pnpm
+
+São duas coisas diferentes, e confundi-las quebra o bootstrap:
+
+- **Versão mínima suportada** — pnpm 9 ou posterior, o que `@kuyper/harness`
+  declara em `engines`.
+- **Versão que certificou esta jornada** — pnpm 12.4.2. É a versão com que os
+  comandos deste guia foram executados literalmente, do repositório vazio ao
+  primeiro `publish`.
+
+Atualize o pnpm **agora**, fora de qualquer diretório de projeto, e confirme o
+resultado antes de seguir:
+
+```bash
+cd ~
+curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=12.4.2 sh -
+```
+
+Agora recarregue o shell, para que o `PATH` enxergue a instalação nova. Este
+comando **substitui o processo do seu terminal**, então ele vai sozinho — nada
+colado depois dele na mesma leva chegaria a rodar:
+
+```bash
+exec zsh -l
+```
+
+Com o shell novo, confirme:
+
+```bash
+which pnpm
+pnpm --version
+```
+
+`source ~/.zshrc && rehash` tem o mesmo efeito de recarregar e não troca o
+processo. Se `pnpm --version` não imprimir a versão que você acabou de instalar
+— ou disser `command not found` —, a rota está em
+[Quando algo falha](06-falhas.md#pnpm-not-found-depois-de-reinstalar).
+
+**Não rode `pnpm self-update` durante a jornada.** A partir do `pnpm init` do
+passo 2 o projeto passa a ter um campo `packageManager` fixando a versão, e
+dentro de um projeto com esse campo o `self-update` não atualiza a instalação
+global: ele só reescreve o pin. O comando seguinte tenta então baixar e alternar
+sozinho para a versão nova, e uma troca incompleta derruba os quatro gates antes
+mesmo de eles chegarem a rodar. A recuperação está em
+[Quando algo falha](06-falhas.md#failed-to-switch-pnpm-depois-de-um-self-update).
+
+Trocar de versão depois é legítimo — mas como mudança explícita do ambiente do
+projeto: atualize a instalação fora dele, confirme com `pnpm --version` e ajuste
+o `packageManager` num commit próprio, nunca como resposta automática ao aviso
+de atualização.
+
+### Identidade do Git
+
+Se a opção **Keep my email addresses private** estiver ativa no GitHub, abra
+[Settings > Emails](https://github.com/settings/emails), copie o endereço
+`noreply` mostrado pela própria página e use-o no Git. Ele costuma ter o formato
+`ID+USUARIO@users.noreply.github.com`, mas copie o valor exato em vez de tentar
+adivinhar o ID:
+
+```bash
+git config --global user.name "Seu Nome"
+git config --global user.email "ID+SEU-USUARIO@users.noreply.github.com"
+```
+
+Se o seu e-mail pode aparecer publicamente nos commits, você pode configurá-lo
+no lugar do `noreply`. Em qualquer caso, estes comandos precisam imprimir os
+valores corretos antes de continuar:
 
 ```bash
 git config --global user.name
 git config --global user.email
 ```
 
+### Autenticação do GitHub
+
+**HTTPS e SSH são dois métodos independentes.** Estar logado no navegador, ou ter
+o GitHub CLI autenticado, **não** configura uma chave SSH. Numa máquina sem
+chave, um clone `git@github.com:...` falha assim:
+
+```
+git@github.com: Permission denied (publickey).
+```
+
+Escolha um método aqui e use **o mesmo** na URL do clone do passo 1. Esta jornada
+usa HTTPS com o GitHub CLI, porque o login fica armazenado e não precisa ser
+repetido a cada operação:
+
+```bash
+gh auth login -h github.com -p https -w
+```
+
+Este comando faz perguntas e abre o navegador, então vai sozinho. `-w` é o que
+abre o navegador para autorizar; `-p https` diz ao `gh` que as operações de Git
+deste host usam HTTPS, e ele configura o Git para reaproveitar a credencial
+guardada.
+
+Terminado o fluxo no navegador, confirme:
+
+```bash
+gh auth status
+```
+
+Precisa mostrar `Logged in to github.com` antes de você seguir. Feito isso,
+clone e push HTTPS funcionam sem pedir senha.
+
+<details>
+<summary>Alternativa: SSH</summary>
+
+SSH também funciona, mas exige uma chave que exista na máquina **e** esteja
+registrada no GitHub. Verifique as duas coisas antes de clonar:
+
+```bash
+ls ~/.ssh/id_ed25519.pub
+```
+
+```bash
+ssh -T git@github.com
+```
+
+`ssh -T` vai sozinho: na primeira conexão ele pede confirmação da impressão
+digital do servidor. Precisa responder
+`Hi SEU-USUARIO! You've successfully authenticated`.
+
+Se a chave não existir, ou se o GitHub não a reconhecer, crie uma. O
+`ssh-keygen` faz três perguntas — onde salvar e a senha da chave, duas vezes —,
+então também vai sozinho:
+
+```bash
+ssh-keygen -t ed25519 -C "seu-email"
+```
+
+Com a chave criada, registre-a no agente e no GitHub:
+
+```bash
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+gh ssh-key add ~/.ssh/id_ed25519.pub --title "$(hostname)"
+```
+
+E confirme:
+
+```bash
+ssh -T git@github.com
+```
+
+Sem o GitHub CLI, registre a chave à mão em
+[Settings > SSH and GPG keys](https://github.com/settings/keys), colando o
+conteúdo de `~/.ssh/id_ed25519.pub`. Só depois de `ssh -T` autenticar, troque a
+URL do clone do passo 1 por
+`git@github.com:${GITHUB_USER}/${PROJECT_NAME}.git`.
+
+</details>
+
 ## 1. Criar e clonar o repositório
 
 No GitHub, crie um repositório **privado e vazio**, sem README, `.gitignore` ou
@@ -22,23 +177,56 @@ licença. Troque os dois valores abaixo e execute:
 ```bash
 export GITHUB_USER="seu-usuario"
 export PROJECT_NAME="seu-projeto"
-git clone "git@github.com:${GITHUB_USER}/${PROJECT_NAME}.git"
+git clone "https://github.com/${GITHUB_USER}/${PROJECT_NAME}.git"
 cd "$PROJECT_NAME"
-git switch -c main
+
+if [ "$(git branch --show-current)" != "main" ]; then
+  git switch -c main
+fi
 ```
 
-Um clone vazio pode avisar que não tem branch; `git switch -c main` é esperado.
+O clone de um repositório vazio já deixa o checkout numa branch **não nascida** —
+normalmente `main`, porque é o padrão do GitHub. `git status -sb` mostra:
+
+```
+## No commits yet on main...origin/main [gone]
+```
+
+Isso é esperado, e não há nada a corrigir: `[gone]` só diz que o remoto ainda não
+tem nenhum commit para essa branch rastrear. O `[gone]` desaparece sozinho no
+primeiro `publish`.
+
+O objetivo da condição acima é apenas **garantir que o primeiro commit nasça em
+`main`**, não criar a branch a qualquer custo. Ela cobre os dois casos que
+existem de verdade: um remoto cujo padrão não é `main` (o clone cai numa
+`master` não nascida, e a branch precisa mesmo ser criada) e uma segunda
+execução destes passos num repositório que já tem commits, onde
+`git switch -c main` falharia com `fatal: a branch named 'main' already exists`.
 
 ## 2. Criar o projeto TypeScript e os quatro gates
 
-Os comandos abaixo criam uma configuração mínima que realmente compila, passa
-no lint e aceita um projeto ainda sem testes:
+Quatro blocos, nesta ordem. O primeiro cria o projeto e baixa as ferramentas:
 
 ```bash
 pnpm init
 pnpm pkg set type=module
 pnpm add -D typescript@^5.9.3 eslint@^10.9.1 @eslint/js@^10.0.1 typescript-eslint@^8.68.0 vitest@^4.1.11
+```
+
+Este é o único bloco do passo 2 que usa a rede, e é onde uma matriz de versões
+incompatível apareceria. Confirme que a instalação terminou sem erro antes de
+seguir.
 
+O `pnpm init` grava em `packageManager` a versão de pnpm que você confirmou no
+passo 0 — é ela que passa a valer para este projeto, em qualquer máquina. Em
+pnpm 12 ele grava também `devEngines.packageManager` com `"onFail": "download"`,
+que é exatamente a autorização para o pnpm baixar e trocar de versão sozinho
+quando o pin não bate com a instalação. Por isso o passo 0 insiste na ordem: com
+a versão certa instalada antes, essa troca automática nunca precisa acontecer.
+
+O segundo bloco só escreve arquivos — nenhum comando aqui acessa a rede:
+
+```bash
 cat > .gitignore <<'EOF'
 node_modules/
 dist/
@@ -78,26 +266,42 @@ export function hello(name: string): string {
   return `Olá, ${name}.`;
 }
 EOF
+```
+
+O terceiro declara os quatro scripts no `package.json`:
 
+```bash
 pnpm pkg set scripts.typecheck="tsc --noEmit"
 pnpm pkg set scripts.lint="eslint ."
 pnpm pkg set scripts.test="vitest run --passWithNoTests"
 pnpm pkg set scripts.build="tsc"
-
-pnpm typecheck
-pnpm lint
-pnpm test
-pnpm build
 ```
 
 O `--passWithNoTests` é deliberado: o gate existe desde o primeiro commit, antes
 de o primeiro teste existir.
 
+O quarto roda os quatro gates. Os `&&` fazem a sequência **parar no primeiro que
+falhar**, deixando o erro como a última coisa na tela — é a mesma forma que o
+Harness usa quando executa os gates por você:
+
+```bash
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
+```
+
+Os quatro precisam passar antes de você seguir para o passo 3.
+
 ## 3. Instalar o Harness e criar o commit raiz
 
 ```bash
 pnpm add -D @kuyper/harness
 pnpm exec kuyper --version
+```
+
+A versão impressa confirma que o binário do projeto responde. A invocação é
+sempre `pnpm exec kuyper`: o `pnpm add -D` instala o binário em
+`node_modules/.bin/`, que não está no `PATH` do seu terminal.
+
+```bash
 git add -A
 git commit -m "chore: inicia projeto"
 git switch -c dev
@@ -121,14 +325,31 @@ Revise `.kuyper/`, `CLAUDE.md`, `AGENTS.md`, `.claude/skills/`,
 
 ```bash
 pnpm exec kuyper validate
+```
+
+O relatório precisa dizer que a materialização está coerente antes de você
+commitar.
+
+```bash
 git add -A
 git commit -m "chore: inicializa Kuyper Harness"
+```
+
+Este commit passa pelos hooks que o `init` acabou de criar — é a primeira vez
+que os gates rodam sozinhos.
+
+```bash
 pnpm exec kuyper integrate
+```
+
+```bash
 pnpm exec kuyper publish
 ```
 
-Ao final, `main` local e `origin/main` apontam para o merge criado pelo
-`integrate`, e o checkout volta para `dev`.
+`integrate` e `publish` vêm separados de propósito: cada um roda os gates e
+imprime um relatório que vale ler antes do próximo. Ao final, `main` local e
+`origin/main` apontam para o merge criado pelo `integrate`, e o checkout volta
+para `dev`.
 
 ## 5. Trabalhar depois do primeiro publish
 
@@ -148,6 +369,13 @@ Quando uma segunda versão do Harness existir na npm:
 
 ```bash
 pnpm exec kuyper update
+```
+
+O relatório diz qual versão entrou e quais capacidades mudaram. Revise o
+`git diff` de `.kuyper/core/` antes de commitar — é para isso que a atualização
+passa pelo Git:
+
+```bash
 git add -A
 git commit -m "chore: atualiza Kuyper Harness"
 ```

package/docs/guia/06-falhas.md

@@ -3,6 +3,153 @@
 O Harness faz preflight antes de escrever e torna estado parcial visível. Não
 faz rollback automático.
 
+As três primeiras rotas abaixo são falhas do **ambiente**, durante o bootstrap do
+guia [Começar um projeto](01-comecar.md). Acontecem antes de o Harness existir no
+projeto e nenhuma delas é uma recusa dele.
+
+## Clone recusado com `Permission denied (publickey)`
+
+```
+git@github.com: Permission denied (publickey).
+```
+
+O clone usou SSH numa máquina sem chave SSH configurada. **HTTPS e SSH são
+autenticações independentes**: estar logado no navegador, ou ter o GitHub CLI
+autenticado, não cria nem registra uma chave SSH.
+
+Nada foi criado no disco — o clone falhou antes de escrever. Escolha um método e
+clone de novo com a URL correspondente. HTTPS com o GitHub CLI, que é o que esta
+jornada usa:
+
+```bash
+gh auth login -h github.com -p https -w
+```
+
+```bash
+gh auth status
+git clone "https://github.com/${GITHUB_USER}/${PROJECT_NAME}.git"
+```
+
+Ou SSH, configurando a chave de verdade antes. O `ssh-keygen` faz três perguntas
+e o `ssh -T` pede confirmação da impressão digital na primeira conexão, então os
+dois vão sozinhos:
+
+```bash
+ssh-keygen -t ed25519 -C "seu-email"
+```
+
+```bash
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+gh ssh-key add ~/.ssh/id_ed25519.pub --title "$(hostname)"
+```
+
+```bash
+ssh -T git@github.com
+```
+
+```bash
+git clone "git@github.com:${GITHUB_USER}/${PROJECT_NAME}.git"
+```
+
+`ssh -T` precisa responder `Hi SEU-USUARIO! You've successfully authenticated`
+antes do clone. Sem o GitHub CLI, registre `~/.ssh/id_ed25519.pub` à mão em
+[Settings > SSH and GPG keys](https://github.com/settings/keys).
+
+Se o repositório já tiver sido clonado com a URL errada, troque o remoto em vez
+de clonar de novo:
+
+```bash
+git remote set-url origin "https://github.com/${GITHUB_USER}/${PROJECT_NAME}.git"
+git remote -v
+```
+
+## `Failed to switch pnpm` depois de um `self-update`
+
+```
+ERROR  Failed to switch pnpm to v12.4.2
+spawnSync .../12.4.2/bin/pnpm Unknown system error -8
+```
+
+O `pnpm self-update` foi executado **dentro** de um projeto que já tem
+`packageManager` no `package.json`. Nesse caso ele não atualiza a instalação
+global: só reescreve o pin do projeto. O comando seguinte tenta então baixar e
+alternar sozinho para a versão nova, e essa instalação gerenciada ficou
+incompleta — o arquivo colocado no lugar do executável nativo é o fallback
+textual e sem shebang do `@pnpm/exe`, não um binário da sua plataforma. Os
+quatro gates falham antes mesmo de chegarem a rodar TypeScript ou ESLint.
+
+**Não volte o `packageManager` para a versão antiga.** Isso esconde a
+atualização em vez de concluí-la. Repare a versão que o pin já escolheu,
+reinstalando-a pelo instalador standalone oficial, **fora do projeto**:
+
+```bash
+cd ~
+curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=12.4.2 sh -
+```
+
+Recarregue o shell. `exec` substitui o processo do terminal, então este comando
+vai sozinho — o que for colado junto, depois dele, não chega a rodar:
+
+```bash
+exec zsh -l
+```
+
+Confirme no shell novo:
+
+```bash
+which pnpm
+pnpm --version
+```
+
+`pnpm --version` precisa imprimir a mesma versão que está no `packageManager`
+antes de você voltar ao projeto. Então reinstale as dependências e rode os
+quatro gates:
+
+```bash
+cd ~/Developer/seu-projeto
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+`pnpm --version` dentro do projeto e fora dele pode dar respostas diferentes, e
+isso é normal: dentro de um projeto o pnpm respeita o `packageManager`; fora,
+responde a versão que está instalada. Compare sempre a versão **de fora** com o
+valor do pin.
+
+## `pnpm not found` depois de reinstalar
+
+O instalador standalone coloca o binário em `$PNPM_HOME/bin`, mas um shell que
+já estava aberto continua com o `PATH` antigo — em instalações mais velhas,
+`$PNPM_HOME` sem o `/bin`. Recarregue o shell:
+
+```bash
+exec zsh -l
+```
+
+Ou, sem trocar de processo:
+
+```bash
+source ~/.zshrc
+rehash
+```
+
+Confira onde o binário está e o que o shell resolve:
+
+```bash
+ls "$PNPM_HOME/bin/pnpm"
+which pnpm
+pnpm --version
+```
+
+Se `ls` encontra o arquivo e `which pnpm` não encontra nada, o problema é o
+`PATH`: o bloco `# pnpm` do seu `~/.zshrc` precisa exportar
+`PATH="$PNPM_HOME/bin:$PATH"`. O instalador reescreve esse bloco, e abrir um
+terminal novo depois disso basta.
+
 ## Recusa antes de escrever
 
 Nada foi alterado. Siga os comandos mostrados pela recusa e execute novamente.
@@ -50,6 +197,50 @@ O remoto pode já ter recebido a `main`. Não repita o push às cegas: rode
 `pnpm exec kuyper publish`; ele compara `origin/main` e reconhece o que já foi
 publicado.
 
+## Push recusado pelo GitHub por e-mail privado (`GH007`)
+
+```
+remote: error: GH007: Your push would publish a private email address.
+```
+
+O GitHub recusou o push antes de receber os commits. Não é necessário tornar seu
+e-mail público, desativar a proteção nem recriar o projeto.
+
+Primeiro, abra [Settings > Emails](https://github.com/settings/emails), copie o
+endereço `noreply` exato mostrado pelo GitHub e configure-o:
+
+```bash
+git config --global user.name "Seu Nome"
+git config --global user.email "ID+SEU-USUARIO@users.noreply.github.com"
+```
+
+Essa configuração vale somente para commits futuros. Se o `GH007` aconteceu no
+**primeiro publish** deste guia, o remoto ainda está vazio e os commits locais
+podem ser corrigidos sem refazer a jornada. O comando abaixo preserva arquivos,
+mensagens, branches e merges, mas troca o autor e o responsável por todos os
+commits locais. Substitua os quatro valores antes de executar:
+
+```bash
+FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch -f --env-filter '
+export GIT_AUTHOR_NAME="Seu Nome"
+export GIT_AUTHOR_EMAIL="ID+SEU-USUARIO@users.noreply.github.com"
+export GIT_COMMITTER_NAME="Seu Nome"
+export GIT_COMMITTER_EMAIL="ID+SEU-USUARIO@users.noreply.github.com"
+' -- --all
+```
+
+Confira autor e responsável pelos commits e tente novamente:
+
+```bash
+git log main dev --format='%h  autor=%an <%ae>  commit=%cn <%ce>'
+pnpm exec kuyper publish
+```
+
+Os identificadores dos commits mudam porque o e-mail faz parte deles. Como o
+push foi recusado, não é necessário usar `--force`. **Não use essa recuperação
+indiscriminadamente se algum desses commits já estiver num remoto compartilhado**;
+reescrever commits já publicados exige combinar a mudança com as outras pessoas.
+
 ## Falha do pnpm no `update`
 
 `.kuyper/core/` ainda está íntegro. Escolha uma rota:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuyper/harness",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Copiloto de desenvolvimento: fonte canônica de rules e skills para Claude e Codex, gates e fluxo Git.",
   "type": "module",
   "license": "UNLICENSED",
@@ -16,14 +16,6 @@
     "node": ">=20",
     "pnpm": ">=9"
   },
-  "packageManager": "pnpm@10.30.3",
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "test": "vitest run --passWithNoTests",
-    "build": "tsc -p tsconfig.build.json",
-    "pretest": "tsc -p tsconfig.build.json"
-  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.3.0",
@@ -34,5 +26,12 @@
   },
   "dependencies": {
     "yaml": "^2.9.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.build.json",
+    "pretest": "tsc -p tsconfig.build.json"
   }
-}
+}