expxdev 0.1.0 → 0.1.1

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,137 +1,249 @@
1
- # expxdev
1
+ <div align="center">
2
2
 
3
- CLI do método Expx. Instala, atualiza e diagnostica o ecossistema de skills por projeto,
4
- e sobe o painel de operação que lê a pasta `docs/`.
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/banner-dark.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/banner-light.svg">
6
+ <img alt="expx — o CLI do metodo Expx" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/banner-light.svg" width="100%">
7
+ </picture>
5
8
 
6
- ## Instalação das skills
9
+ <p>
10
+ <a href="https://www.npmjs.com/package/expxdev"><img alt="npm: expxdev" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/badge-npm.svg"></a>
11
+ <img alt="harness: Claude Code" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/badge-claude.svg">
12
+ <img alt="harness: OpenCode" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/badge-opencode.svg">
13
+ <img alt="testes: 231 passed" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/badge-testes.svg">
14
+ <img alt="schema expx v1" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/badge-schema.svg">
15
+ <img alt="node >=20.19" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/badge-node.svg">
16
+ <img alt="licenca MIT" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/badge-license.svg">
17
+ </p>
18
+
19
+ <strong>O CLI do método Expx</strong> — instala, atualiza e diagnostica o ecossistema<br>
20
+ de skills para <a href="https://claude.com/claude-code">Claude Code</a> e <a href="https://opencode.ai">OpenCode</a>, e sobe o painel de operação.
21
+
22
+ </div>
7
23
 
8
24
  ```bash
9
25
  npx expxdev init
10
26
  ```
11
27
 
12
- O `init` busca as skills escolhidas nos repositórios oficiais, empacota as selecionadas
13
- como um plugin local chamado `expx` e configura o harness. Os comandos ficam com namespace
14
- no Claude Code (`/expx:sprintx-sprints`) e sem namespace no OpenCode (`/sprintx-sprints`).
28
+ O `init` busca as skills que você escolher nos repositórios oficiais, empacota apenas as
29
+ selecionadas como um plugin local chamado `expx` e configura o harness. Os comandos ficam
30
+ com namespace no Claude Code (`/expx:sprintx-sprints`) e sem namespace no OpenCode
31
+ (`/sprintx-sprints`).
15
32
 
16
- | Skill | O que faz |
17
- |---|---|
18
- | [`sprintx`](https://github.com/bittencourtthulio/sprintx) | planeja e executa features novas |
19
- | [`runx`](https://github.com/bittencourtthulio/runx) | ocorrências de manutenção do dia a dia |
20
- | [`legadox`](https://github.com/bittencourtthulio/legadox) | camada para projetos legados |
21
- | [`stackx`](https://github.com/bittencourtthulio/stackx) | descobre o dialeto técnico do repositório |
22
- | [`mergex`](https://github.com/bittencourtthulio/mergex) | versionamento, entrega e revisão de PRs |
33
+ > **A instalação é travada por lock; a atualização é um ato explícito.**
34
+ > Quem clona o projeto recebe exatamente as mesmas skills que o time está usando, sem rede e
35
+ > sem rodar nada. Quem atualiza decide quando, vendo antes o que muda.
36
+
37
+ ---
38
+
39
+ ## O ecossistema
40
+
41
+ O método Expx é um conjunto de skills que se compõem. O CLI é quem as instala e mantém.
42
+
43
+ <picture>
44
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/ecossistema-dark.svg">
45
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/ecossistema-light.svg">
46
+ <img alt="O CLI busca as cinco skills, empacota como plugin e configura os dois harnesses" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/ecossistema-light.svg" width="100%">
47
+ </picture>
48
+
49
+ | Skill | O que faz | Quando usar |
50
+ |---|---|---|
51
+ | **[sprintx](https://github.com/bittencourtthulio/sprintx)** | Planeja e executa **features novas** em seis fases: ingestão → descoberta → plano → orquestrador → auditoria → execução. Todo o esforço vai para o planejamento, e a execução é autônoma porque a ambiguidade já foi eliminada. | Construir algo que não existe |
52
+ | **[runx](https://github.com/bittencourtthulio/runx)** | A metade **Run**: ocorrências de manutenção em produção, em cinco estágios — investigação com causa raiz comprovada, plano, fix sob TDD, QA independente e relatórios de fechamento. | Corrigir, ajustar ou investigar o que já está no ar |
53
+ | **[legadox](https://github.com/bittencourtthulio/legadox)** | **Camada** que endurece o trabalho em projetos legados. Não acrescenta fase: muda o *rigor* de cada uma, proporcional ao raio de impacto da mudança. | Mexer em código sem testes ou sem dono |
54
+ | **[stackx](https://github.com/bittencourtthulio/stackx)** | **Camada** que descobre o dialeto técnico do repositório — convenções, padrões e aderência — para o código novo parecer com o que já existe. | Entrar em base desconhecida |
55
+ | **[mergex](https://github.com/bittencourtthulio/mergex)** | Versionamento, entrega e revisão: branch, um commit por task, portão de prontidão, descrição de PR, pacote de QA e abertura do pull request. | Levar o trabalho pronto até o merge |
56
+
57
+ **Camadas** (`legadox`, `stackx`) sozinhas não fazem nada — elas modificam o comportamento de
58
+ `sprintx` e `runx`. O CLI avisa se você selecionar uma camada sem base, mas nunca impede.
59
+
60
+ ---
23
61
 
24
- ### Subcomandos
62
+ ## Subcomandos
25
63
 
26
64
  | Comando | O que faz |
27
65
  |---|---|
28
- | `expx init` | instala as skills escolhidas neste projeto |
29
- | `expx panel` | sobe o painel lendo o `docs/` do projeto |
30
- | `expx add <skill...>` | acrescenta skills à seleção |
31
- | `expx remove <skill...>` | remove skills da seleção |
32
- | `expx update [skill...]` | atualiza as skills instaladas |
33
- | `expx doctor` | diagnostica uma instalação quebrada |
66
+ | `expx init` | Instala as skills escolhidas neste projeto |
67
+ | `expx panel` | Sobe o painel de operação lendo o `docs/` do projeto |
68
+ | `expx add <skill...>` | Acrescenta skills à seleção e remonta o plugin |
69
+ | `expx remove <skill...>` | Remove skills da seleção e remonta o plugin |
70
+ | `expx update [skill...]` | Atualiza as skills instaladas |
71
+ | `expx doctor` | Diagnostica uma instalação quebrada |
72
+
73
+ O painel funciona **sem `init`**: ele não precisa de nada instalado.
74
+
75
+ ### Modo não interativo
76
+
77
+ Toda pergunta do `init` tem equivalente por flag, para uso em script e CI:
78
+
79
+ ```bash
80
+ npx expxdev init --skills sprintx,runx,mergex --harness claude,opencode --yes
81
+ ```
82
+
83
+ | Flag | Efeito |
84
+ |---|---|
85
+ | `--skills <lista>` | Skills a instalar, separadas por vírgula |
86
+ | `--harness <lista>` | `claude`, `opencode`, ou os dois |
87
+ | `--painel` | Instala o painel como devDependency |
88
+ | `--yes` | Pula confirmações |
89
+
90
+ Sem terminal interativo e sem `--yes`, o `init` mostra o que faria e sai **sem escrever nada**.
91
+
92
+ ---
93
+
94
+ ## Versão, lock e atualização
95
+
96
+ <picture>
97
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/lock-dark.svg">
98
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/lock-light.svg">
99
+ <img alt="Instalacao travada por lock; atualizacao explicita que nunca sobrescreve trabalho local" src="https://raw.githubusercontent.com/bittencourtthulio/expxdev/main/.github/assets/lock-light.svg" width="100%">
100
+ </picture>
101
+
102
+ Por padrão o CLI busca a **maior tag de versão semântica** de cada repositório. Se o
103
+ repositório não tiver tag nenhuma, ele cai para a branch padrão e **avisa explicitamente**
104
+ que aquela skill não está travada em versão publicada — nunca segue a branch em silêncio
105
+ quando existe tag.
106
+
107
+ ### O que o `update` faz
108
+
109
+ 1. Descobre a versão alvo de cada skill instalada
110
+ 2. Compara com o lock — skill já em dia é reportada e **não é tocada**
111
+ 3. **Detecta modificação local**: se os arquivos divergirem do lock, não sobrescreve
112
+ 4. Mostra o resumo por skill: versão atual, versão nova, e o que mudou
113
+ 5. Bloqueia skill que exija uma versão de `expx-schema` maior que a suportada
114
+ 6. Pede confirmação e aplica
115
+ 7. Remonta o plugin do zero, reescreve o lock e valida
116
+
117
+ | Flag | Efeito |
118
+ |---|---|
119
+ | *(sem argumento)* | Atualiza todas as skills instaladas |
120
+ | `<skill...>` | Atualiza apenas as nomeadas |
121
+ | `--check` | Só mostra o que mudaria, não aplica nada |
122
+ | `--to <ref>` | Fixa uma skill numa tag ou commit específico |
123
+ | `--latest` | Segue a branch padrão em vez da maior tag |
124
+ | `--yes` | Pula confirmações |
34
125
 
35
- O painel funciona sem `init`: ele não precisa de nada instalado.
126
+ > **Rollback.** Como `.expx/` é commitado, desfazer uma atualização é revertê-lo pelo
127
+ > versionador (`git checkout -- .expx`). O `update` diz isso em toda execução que aplica.
36
128
 
37
- Flags do `init` (todas as perguntas têm equivalente por flag, para uso em script):
38
- `--skills sprintx,runx` · `--harness claude,opencode` · `--painel` · `--yes`
129
+ ---
39
130
 
40
- Flags do `update`: `--check` (só mostra) · `--to <ref>` · `--latest` · `--yes`
131
+ ## O que é criado no projeto
41
132
 
42
- ### Versão, lock e atualização
133
+ ```
134
+ .expx/
135
+ expx-lock.json versão exata de cada skill + hash por arquivo
136
+ marketplace/
137
+ .claude-plugin/marketplace.json
138
+ plugins/expx/
139
+ .claude-plugin/plugin.json name: "expx"
140
+ skills/<só as selecionadas>/
141
+ commands/<só os correspondentes>/
142
+ .claude/settings.json mesclado, nunca sobrescrito
143
+ .opencode/commands/ se OpenCode for escolhido
144
+ ```
43
145
 
44
- A instalação é travada por `.expx/expx-lock.json`, que é **commitado** junto com `.expx/`.
45
- Quem clona o projeto recebe as skills em disco. Por padrão o CLI busca a maior tag de
46
- versão semântica de cada repositório; sem nenhuma tag, segue a branch padrão e **avisa**
47
- que a skill não está travada em versão publicada.
146
+ **Todo o `.expx/` é commitado** é isso que faz quem clona receber as mesmas skills. O CLI
147
+ verifica que nenhuma regra de `.gitignore` o esteja ignorando.
48
148
 
49
- O `update` compara com o lock, mostra o que mudou e pede confirmação antes de aplicar.
50
- Se algum arquivo da skill foi alterado à mão, ele **não sobrescreve**: lista os arquivos e
51
- pede a decisão. Para desfazer uma atualização, reverta o `.expx/` pelo versionador.
149
+ O merge do `.claude/settings.json` faz backup datado antes de tocar, mescla apenas as chaves
150
+ necessárias e preserva todo o resto. JSON inválido não é consertado: o CLI avisa e sai.
52
151
 
53
- > **Registro do plugin no Claude Code.** Declarar o marketplace no `settings.json` do
54
- > projeto não instala o plugin — o `init` chama `claude plugin marketplace add` e
55
- > `claude plugin install`. Como esse registro grava um caminho absoluto na configuração do
56
- > usuário, ele não viaja no commit: cada pessoa roda `expx init` na própria máquina.
152
+ > **Sobre o registro do plugin.** Declarar o marketplace no `settings.json` do projeto **não
153
+ > instala** o plugin — isso foi verificado em execução, não presumido da documentação. O `init`
154
+ > chama `claude plugin marketplace add` e `claude plugin install`. Como esse registro grava um
155
+ > caminho absoluto na configuração do usuário, ele não viaja no commit: cada pessoa roda
156
+ > `expx init` na própria máquina. Sem o binário `claude` no PATH, o `.expx/` é montado
157
+ > normalmente e o CLI imprime os dois comandos para você rodar à mão.
57
158
 
58
159
  ---
59
160
 
60
- # O painel
161
+ ## O que o `doctor` verifica
162
+
163
+ ```bash
164
+ npx expxdev doctor
165
+ ```
166
+
167
+ - `.expx/` existe, lock legível, skills do lock presentes em disco
168
+ - divergência entre disco e lock, indicando modificação local
169
+ - skill não travada em versão publicada
170
+ - `plugin.json` e `marketplace.json` válidos, com name `expx`
171
+ - nenhuma skill referenciando caminho **fora da própria pasta**
172
+ - `settings.json` válido e com o plugin habilitado
173
+ - colisão de nome de skill entre Claude Code e OpenCode
174
+ - compatibilidade entre a versão do CLI e a estrutura em `.expx/`
175
+ - `.gitignore` ignorando `.expx/` indevidamente
176
+
177
+ Cada achado vem com a correção sugerida. Achado de severidade `aviso` não derruba a saída.
61
178
 
62
- a pasta `docs/` de um projeto, descobre os trabalhos gravados pelas skills
63
- [`sprintx`](https://github.com/bittencourtthulio/sprintx) e
64
- [`runx`](https://github.com/bittencourtthulio/runx), e mostra no navegador o que foi
65
- planejado, o que está em execução, o que travou e o histórico do que já foi entregue.
179
+ > **Por que "caminho fora da própria pasta" importa.** Ao instalar, o Claude Code **copia** o
180
+ > plugin para `~/.claude/plugins/cache/<marketplace>/<plugin>/<versão>/`, e só a pasta do
181
+ > plugin vai junto. Qualquer `../` dentro de uma skill sai da árvore copiada e deixa de
182
+ > resolver silenciosamente. O CLI recusa instalar uma skill assim.
66
183
 
67
- **Somente leitura.** O painel nunca escreve nos arquivos do projeto e nunca executa comando algum.
184
+ ---
68
185
 
69
- ## Uso
186
+ ## O painel
70
187
 
71
188
  ```bash
72
189
  npx expxdev panel
73
190
  ```
74
191
 
192
+ Lê a pasta `docs/` do projeto, descobre os trabalhos gravados por `sprintx` e `runx` e mostra
193
+ no navegador o que foi planejado, o que está em execução, o que travou e o histórico do que
194
+ já foi entregue.
195
+
196
+ **Somente leitura.** O painel nunca escreve nos arquivos do projeto e nunca executa comando
197
+ algum. O servidor escuta exclusivamente em `127.0.0.1` — não há flag que mude isso.
198
+
75
199
  | Flag | Padrão | O que faz |
76
200
  |---|---|---|
77
201
  | `--porta <n>` | `4000` | porta do servidor local |
78
202
  | `--dir <caminho>` | `./docs` | pasta de documentação a observar |
79
203
  | `--no-open` | — | não abre o navegador |
80
- | `--dias-bloqueio <n>` | `7` | a partir de quantos dias um bloqueio aberto é "antigo" |
81
- | `--ajuda` | — | mostra a ajuda |
204
+ | `--dias-bloqueio <n>` | `7` | dias a partir dos quais um bloqueio é antigo |
82
205
 
83
- ## O que o painel mostra
206
+ ---
84
207
 
85
- - **Visão global** — trabalhos em planejamento, execução, bloqueados e concluídos, separando feature de ocorrência; bloqueios abertos; ocorrências por tipo.
86
- - **Quadro por estágio** — 11 colunas (`f1`–`f6` da sprintx, `e1`–`e5` da runx), com filtro por ferramenta, tipo e status.
87
- - **Detalhe do trabalho** — sprints, fases e tasks com barra de progresso, dependências, destaque do paralelizável e do caminho crítico, bloqueios em evidência.
88
- - **Conformidade com o método** — violações mecanicamente detectáveis pelo frontmatter, cada uma apontando arquivo e linha.
89
- - **Histórico** — linha do tempo de `docs/relatorios/`, com busca por módulo e tipo. O relatório de uso fica em aba própria, com botão de copiar: é o texto que o suporte devolve ao cliente.
90
- - **Fora do schema** — arquivos que não puderam ser lidos, com o motivo. Nunca derrubam o servidor.
208
+ ## Segurança e limites
91
209
 
92
- ## Segurança
210
+ - **Nunca pede nem armazena credencial.** Repositório privado usa a credencial de git já
211
+ configurada na máquina.
212
+ - **Nunca escreve fora da raiz do projeto.**
213
+ - **Nunca escreve uma skill.** O CLI busca e empacota; jamais edita conteúdo de skill.
214
+ - **Escrita atômica.** A montagem acontece em pasta temporária e é trocada por `rename` ao
215
+ final: se falhar no meio, o `.expx/` anterior permanece intacto.
216
+ - Toda escrita destrutiva pede confirmação, com flag para pular em ambiente não interativo.
93
217
 
94
- O servidor escuta **exclusivamente em `127.0.0.1`**. Não há flag, variável de ambiente ou
95
- opção que mude isso: o painel serve documentação interna sem autenticação nenhuma, e expô-la
96
- na rede local entregaria o conteúdo a qualquer um no mesmo Wi-Fi. Todo método HTTP que não
97
- seja `GET` responde `405`.
218
+ ---
98
219
 
99
220
  ## Desenvolvimento
100
221
 
101
222
  ```bash
102
223
  npm install
103
- npm test # 89 testes
104
- npm run build # tsc strict + vite
224
+ npm test # 231 testes, sem acesso à rede
225
+ npm run typecheck
226
+ npm run build
105
227
  ```
106
228
 
107
- O projeto segue o próprio método que ele exibe. O planejamento inteiro está em
108
- [`docs/expx-panel/`](docs/expx-panel/): base de conhecimento, decisões, plano de sprints,
109
- auditoria e orquestrador. Apontar o painel para o próprio `docs/` deste repositório é o
110
- teste de aceitação mais honesto que existe:
229
+ TypeScript strict + ESM, Node 20.19, Vitest em três projetos (`servidor`, `ui`, `cli`). A
230
+ suíte roda contra repositórios git locais criados em tempo de teste — nenhum teste depende
231
+ de rede nem do estado do GitHub.
111
232
 
112
- ```bash
113
- node dist/cli/principal.js --dir docs
114
- ```
233
+ Arquitetura em camadas isoladas: resolução de versão e busca, normalização de layout,
234
+ montagem do plugin, configuração de harness, detecção de modificação local. Nenhuma regra de
235
+ negócio vive no código de linha de comando.
115
236
 
116
- ### Arquitetura
237
+ Este projeto foi planejado e executado com o próprio método — o plano completo, a base de
238
+ conhecimento e as decisões estão em [`docs/expx-cli/`](docs/expx-cli/).
117
239
 
118
- Três camadas, sem regra de negócio vazando para cima:
119
-
120
- ```
121
- src/parser/ recebe um caminho, devolve objeto tipado + rejeições + violações
122
- src/servidor/ expõe a API de leitura, observa o disco, difunde por websocket
123
- ui/src/ consome a API e renderiza — nenhuma regra de negócio aqui
124
- ```
125
-
126
- O parser é testável sozinho, contra `fixtures/` em disco: `projeto-ok` cobre os 13 kinds
127
- do contrato; `projeto-ruim` cobre YAML inválido, enum errado, chave ausente, versão de
128
- schema futura, pasta sem orquestrador e task paralelizável com dependência.
129
-
130
- ### O contrato
240
+ ---
131
241
 
132
- [`docs/contrato/CONTRATO-expx-schema-v1.md`](docs/contrato/CONTRATO-expx-schema-v1.md) é a
133
- referência do formato. Onde ele diverge do que as skills realmente gravam, o painel segue
134
- as **skills** — elas é que escrevem os arquivos que ele lê. As duas divergências estão
135
- registradas em [`docs/expx-panel/00-DECISOES.md`](docs/expx-panel/00-DECISOES.md) (D-01 e
136
- D-02) e o parser aceita o superconjunto, de modo que nenhum arquivo real se perde seja qual
137
- for o lado que venha a ser atualizado.
242
+ <div align="center">
243
+ <sub>Parte do método <strong>Expx</strong> ·
244
+ <a href="https://github.com/bittencourtthulio/sprintx">sprintx</a> ·
245
+ <a href="https://github.com/bittencourtthulio/runx">runx</a> ·
246
+ <a href="https://github.com/bittencourtthulio/legadox">legadox</a> ·
247
+ <a href="https://github.com/bittencourtthulio/stackx">stackx</a> ·
248
+ <a href="https://github.com/bittencourtthulio/mergex">mergex</a></sub>
249
+ </div>
@@ -11,7 +11,7 @@ export const SUBCOMANDOS = ["init", "panel", "add", "remove", "update", "doctor"
11
11
  const AJUDA = `
12
12
  expx — CLI do metodo Expx
13
13
 
14
- npx expx <subcomando> [opcoes]
14
+ npx expxdev <subcomando> [opcoes]
15
15
 
16
16
  expx init instala as skills escolhidas neste projeto
17
17
  expx panel sobe o painel de operacao lendo o docs/ do projeto
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "expxdev",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "CLI do metodo Expx: instala, atualiza e opera o ecossistema de skills, e sobe o painel de operacao",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "expx": "dist/cli/expx-bin.js",
8
+ "expxdev": "dist/cli/expx-bin.js",
8
9
  "expx-painel": "dist/cli/principal.js"
9
10
  },
10
11
  "engines": {
@@ -62,12 +63,12 @@
62
63
  "painel"
63
64
  ],
64
65
  "author": "Expx",
65
- "homepage": "https://github.com/bittencourtthulio/expx-painel#readme",
66
+ "homepage": "https://github.com/bittencourtthulio/expxdev#readme",
66
67
  "repository": {
67
68
  "type": "git",
68
- "url": "git+https://github.com/bittencourtthulio/expx-painel.git"
69
+ "url": "git+https://github.com/bittencourtthulio/expxdev.git"
69
70
  },
70
71
  "bugs": {
71
- "url": "https://github.com/bittencourtthulio/expx-painel/issues"
72
+ "url": "https://github.com/bittencourtthulio/expxdev/issues"
72
73
  }
73
74
  }