@fullchico/harness 0.1.0 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,5 +1,16 @@
1
+ <img src="site/trem.svg" alt="" width="72" align="right">
2
+
1
3
  # FullChico Harness
2
4
 
5
+ [![npm](https://img.shields.io/npm/v/@fullchico/harness?label=npm&color=1d1b16)](https://www.npmjs.com/package/@fullchico/harness)
6
+ [![ci](https://github.com/fullchico/fullchico-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/fullchico/fullchico-harness/actions/workflows/ci.yml)
7
+
8
+ [Página do projeto](https://fullchico.github.io/fullchico-harness/) · [Pacote no npm](https://www.npmjs.com/package/@fullchico/harness)
9
+
10
+ ```bash
11
+ npx @fullchico/harness install .
12
+ ```
13
+
3
14
  Ambiente de desenvolvimento com agentes, para o Claude Code. Um plugin que padroniza, em
4
15
  todo projeto que o adota, o fluxo de uma mudança, os guardrails e o ambiente de
5
16
  desenvolvimento por feature.
@@ -43,13 +54,47 @@ com sandbox disponível. O remoto do projeto precisa ser HTTPS. Recomendado: `rt
43
54
 
44
55
  ## Instalar num projeto
45
56
 
46
- Um comando, na pasta do projeto (um repositório git):
57
+ Um comando, no seu terminal, na pasta do projeto (um repositório git):
47
58
 
48
59
  ```bash
49
60
  npx @fullchico/harness install .
50
61
  ```
51
62
 
52
- Com o repositório clonado, `/caminho/do/fullchico-harness/install /caminho/do/projeto` faz o mesmo.
63
+ É só isso. Ele grava os arquivos do harness, registra o marketplace, instala o plugin e as
64
+ skills. Depois abra o Claude Code na pasta e faça o pedido:
65
+
66
+ ```text
67
+ /harness:entregar quero um sistema de agendamento para uma barbearia
68
+ ```
69
+
70
+ Na primeira vez o Claude Code pergunta se você confia na pasta: aceite. O remoto pode vir
71
+ depois: sem ele a entrega roda até o fim, e só o envio e o pull request ficam esperando.
72
+
73
+ ### Deixar o Claude instalar
74
+
75
+ Se preferir, cole este pedido numa sessão do Claude Code aberta na pasta do projeto:
76
+
77
+ ```text
78
+ Instale o FullChico Harness neste projeto e deixe-o pronto para a primeira entrega. Pare se algo falhar, mostrando o erro exato.
79
+
80
+ 1. Confira os pré-requisitos: esta pasta é um repositório git (se não for, pergunte antes de criar um), e existem `python3`, `node`, `docker compose` e `claude`. Diga o que falta.
81
+ 2. Rode `npx @fullchico/harness install .` fora do sandbox do Bash, pedindo a minha permissão: o instalador precisa alcançar o GitHub para registrar o plugin, e dentro do sandbox isso é bloqueado. Um comando só faz tudo: grava os arquivos, registra o marketplace e instala o plugin e as skills.
82
+ 3. Confira o que foi gravado: `.harness/`, `.claude/settings.json`, `.claude/skills/`, `AGENTS.md`, `CLAUDE.md` e `harness.conf`. Não edite arquivo gerenciado pelo harness.
83
+ 4. Faça o commit do que foi gerado, numa branch.
84
+ 5. Peça-me para reiniciar o Claude Code nesta pasta, para o plugin e os hooks carregarem.
85
+
86
+ No fim, relate em poucas linhas o que foi instalado e o comando para começar a primeira entrega: `/harness:entregar <o que eu quero construir>`, num worktree de feature.
87
+ ```
88
+
89
+ ### Se algo não funcionar
90
+
91
+ - **Rodei o comando de dentro de uma sessão do Claude Code e o plugin não apareceu.** O
92
+ sandbox da sessão bloqueia o GitHub. Rode de novo no seu terminal, fora da sessão; o comando
93
+ pode ser repetido sem dano.
94
+ - **"A origem não bate com uma entrada já registrada".** Há um marketplace `fullchico` antigo
95
+ nas suas configurações: `claude plugin marketplace remove fullchico` e rode o instalador de novo.
96
+ - **Projeto que já tinha código.** Depois de instalar, rode `/harness:setup` numa sessão: ele
97
+ propõe o `harness.conf` a partir do que encontra.
53
98
 
54
99
  Ele grava `.harness/`, `.claude/settings.json`, `AGENTS.md`, `CLAUDE.md`, `docs/agents/` e
55
100
  `orca.yaml`, registra os marketplaces, e instala no escopo do projeto o plugin do harness e os
@@ -57,15 +102,6 @@ de terceiros (`mattpocock-skills`, `ponytail`). Se o `harness.conf` já estiver
57
102
  também grava as portas no `.env` e instala as dependências. Pode ser rodado de novo. Arquivo
58
103
  gerenciado alterado à mão trava a instalação; `--force` substitui.
59
104
 
60
- Num projeto novo falta um passo, numa sessão do Claude Code aberta nele:
61
-
62
- ```
63
- /harness:setup
64
- ```
65
-
66
- Ele propõe o `harness.conf` a partir do que encontra no projeto. Faça o commit do que foi
67
- gerado e reinicie a sessão.
68
-
69
105
  ### Perfis
70
106
 
71
107
  O instalador aceita `--profile`, e a escolha fica no `harness.conf`:
package/install CHANGED
@@ -79,18 +79,26 @@ for s in json.load(open(sys.argv[1])).get("project_skills", []):
79
79
  fi
80
80
 
81
81
  # Com o harness.conf já preenchido, deixa o worktree pronto: portas no .env e dependências.
82
- NEXT="Falta, numa sessão do Claude Code aberta no projeto: /harness:setup, que propõe o harness.conf."
82
+ NEXT="O harness.conf é preenchido na primeira entrega. Se o projeto já tem código, rode antes /harness:setup, que o propõe a partir do que encontra."
83
83
  if grep -Eq '^PROJECT="?[^"[:space:]]' "$ROOT/harness.conf" 2>/dev/null; then
84
84
  HARNESS_SKIP_PLUGIN=1 "$ROOT/.harness/setup-worktree" || exit $?
85
85
  NEXT="O harness.conf já estava preenchido: portas gravadas no .env e dependências instaladas."
86
86
  fi
87
87
 
88
+ if [ -n "${CLAUDECODE:-}" ]; then
89
+ cat >&2 <<'EOT'
90
+
91
+ install: você está dentro de uma sessão do Claude Code, e o sandbox dela bloqueia o GitHub: o
92
+ plugin pode não ter sido instalado. Os arquivos do projeto foram gravados. Para completar, rode
93
+ este mesmo comando no seu terminal, fora da sessão; ele pode ser repetido sem dano:
94
+ npx @fullchico/harness install <pasta do projeto>
95
+ EOT
96
+ fi
97
+
88
98
  cat <<EOT
89
99
 
90
100
  Harness $VERSION instalado em $ROOT, no perfil $PROFILE.
91
101
  $NEXT
92
- Abra o Claude Code uma vez nessa pasta, em modo interativo, e aceite o diálogo de confiança:
93
- sem isso ele ignora as permissões do projeto (.claude/settings.json), inclusive em sessões por linha de comando.
94
- Depois faça o commit do que foi gerado e envie a branch padrão ao remoto. Esse primeiro envio é
95
- seu, no terminal: os portões valem para ele também (.harness/approve em cada um).
102
+ Pronto. Abra o Claude Code nessa pasta (na primeira vez, aceite a confiança da pasta) e peça:
103
+ /harness:entregar <o que você quer construir>
96
104
  EOT
package/package.json CHANGED
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "name": "@fullchico/harness",
3
- "version": "0.1.0",
3
+ "version": "0.1.4",
4
4
  "description": "Trilhos e portões para projetos desenvolvidos com agentes no Claude Code: orquestração por ticket, revisão independente presa ao commit, ambiente por feature.",
5
5
  "license": "MIT",
6
6
  "author": "FullChico",
7
7
  "repository": {
8
8
  "type": "git",
9
- "url": "git+https://github.com/FullChico/fullchico-harness.git"
9
+ "url": "git+https://github.com/fullchico/fullchico-harness.git"
10
10
  },
11
- "homepage": "https://github.com/FullChico/fullchico-harness#readme",
11
+ "homepage": "https://github.com/fullchico/fullchico-harness#readme",
12
12
  "bugs": {
13
- "url": "https://github.com/FullChico/fullchico-harness/issues"
13
+ "url": "https://github.com/fullchico/fullchico-harness/issues"
14
14
  },
15
15
  "keywords": ["claude-code", "agents", "harness", "guardrails", "hooks"],
16
16
  "bin": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "harness",
3
- "version": "0.1.0",
3
+ "version": "0.1.4",
4
4
  "description": "Orquestração, guardrails e memória para projetos desenvolvidos com agentes.",
5
5
  "license": "MIT",
6
6
  "author": {
@@ -104,6 +104,10 @@ gravada por um hook a partir dessa resposta. Você não grava aprovação e não
104
104
  .harness/push
105
105
  ```
106
106
 
107
+ **Projeto sem remoto.** O comando confere os quatro portões do mesmo jeito e termina dizendo
108
+ que a branch está aprovada e que nada foi enviado. É um fim válido: pule o passo 6 (não há
109
+ pull request), faça o passo 7 e diga ao dono, no relato, o que falta para publicar.
110
+
107
111
  É o único caminho até o remoto. Se ele negar, leia o motivo: aprovação faltando para o
108
112
  commit atual quer dizer que houve commit depois da revisão, ou que um revisor não fechou
109
113
  a resposta no formato: dispare de novo o que faltou. Se o motivo for a branch padrão
@@ -19,7 +19,11 @@ ZERO=0000000000000000000000000000000000000000
19
19
  SPEC_GLOB='docs/specs/*/spec.md'
20
20
  [ -f "$H/map.env" ] && . "$H/map.env"
21
21
 
22
- if ! LS="$(git ls-remote --symref "$REMOTE_URL" HEAD 'refs/heads/*' 2>/dev/null)"; then
22
+ if [ -z "$REMOTE_URL" ]; then
23
+ # Projeto sem remoto: a base é a branch padrão local, a mesma que os revisores usaram.
24
+ LOCAL_BASE="$(python3 -I "$H/hooks/common.py" branch-base "$(git rev-parse HEAD)" 2>/dev/null)" || LOCAL_BASE=""
25
+ LS="${LOCAL_BASE:+$LOCAL_BASE HEAD}"
26
+ elif ! LS="$(git ls-remote --symref "$REMOTE_URL" HEAD 'refs/heads/*' 2>/dev/null)"; then
23
27
  echo "push negado: não consegui consultar o remoto ($REMOTE_URL) para medir o que a branch acrescenta." >&2
24
28
  exit 1
25
29
  fi
@@ -22,8 +22,17 @@ cd "$ROOT" || exit 1
22
22
  # Worktree de agente já integrado não sobra para depois da entrega.
23
23
  "$HERE/agents-clean" >/dev/null 2>&1 || true
24
24
  BRANCH="$(git symbolic-ref --short -q HEAD)" || die "o push é sempre de uma branch; este checkout não está em nenhuma."
25
- URL="$(git remote get-url origin 2>/dev/null)" || die "este repositório não tem o remoto origin."
26
25
  SHA="$(git rev-parse HEAD)"
26
+ if ! URL="$(git remote get-url origin 2>/dev/null)"; then
27
+ # Sem remoto não há para onde enviar, mas a entrega se confere igual: os mesmos portões,
28
+ # medidos contra a branch padrão local. Passou, está pronta; publicar é um passo do dono.
29
+ printf 'refs/heads/%s %s refs/heads/%s 0000000000000000000000000000000000000000\n' "$BRANCH" "$SHA" "$BRANCH" \
30
+ | "$HERE/gate-check" "" || exit 1
31
+ echo "Branch $BRANCH aprovada nos portões ($SHA). Projeto sem remoto: nada foi enviado."
32
+ echo "Para publicar: crie o repositório, ligue com \`git remote add origin <url https>\`, envie a branch"
33
+ echo "padrão (esse primeiro envio é do dono) e rode .harness/push de novo."
34
+ exit 0
35
+ fi
27
36
 
28
37
  printf 'refs/heads/%s %s refs/heads/%s 0000000000000000000000000000000000000000\n' "$BRANCH" "$SHA" "$BRANCH" \
29
38
  | "$HERE/gate-check" "$URL" || exit 1
@@ -44,8 +44,8 @@ perguntar.
44
44
  estiver na branch padrão, pare e peça ao dono para abrir o worktree da feature.
45
45
  - Confira que há remoto: `git remote get-url origin`, e que a branch padrão já está nele
46
46
  (`git ls-remote origin`). Sem remoto não existe push nem pull request; sem a branch padrão
47
- lá, o pull request não tem base, e o primeiro envio dela é do dono, no terminal. Avise o dono já agora, numa linha, e siga: a entrega vai até as aprovações, e o
48
- envio fica esperando o remoto. Não deixe para descobrir no fim.
47
+ lá, o pull request não tem base, e o primeiro envio dela é do dono, no terminal. Avise o dono já agora, numa linha, e siga: sem remoto a entrega vai até o fim
48
+ (portões conferidos, aplicativo de pé) e só o envio e o pull request ficam para depois.
49
49
  - Rode `.harness/fetch`. Se a branch padrão do remoto andou, traga-a para dentro da feature
50
50
  com `git merge origin/<branch padrão>`, antes de qualquer outra coisa.
51
51
  - Leia `GLOSSARY.md` e os ADRs em `docs/adr/`, se existirem.