theforge-cli 0.1.0 → 0.2.0
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/CHANGELOG.md +433 -1
- package/README.md +44 -18
- package/dist/index.js +2565 -453
- package/docs/arquitetura.md +28 -26
- package/docs/capabilities.md +47 -0
- package/docs/registry-state-contract.md +81 -0
- package/package.json +1 -1
package/docs/arquitetura.md
CHANGED
|
@@ -7,32 +7,34 @@ vive em módulos especializados.**
|
|
|
7
7
|
|
|
8
8
|
## Mapa de módulos
|
|
9
9
|
|
|
10
|
-
| Módulo | Responsabilidade
|
|
11
|
-
| ------------------------ |
|
|
12
|
-
| `src/index.ts` | Só despacha: parse de args, menu, resolução do subcomando, SIGINT e erros fatais.
|
|
13
|
-
| `src/cmd/shared.ts` | Banner, preflight, catálogo efetivo, `--json`, seleção de Forjas por nome.
|
|
14
|
-
| `src/cmd/batch.ts` | Execução sequencial com spinner/taskLog por Forja.
|
|
15
|
-
| `src/cmd/query.ts` | `doctor`, `list`, `status`, `update --check`, `versions` (com `--json`).
|
|
16
|
-
| `src/cmd/manage.ts` | `pin`, `unpin`, `rollback`, `uninstall <forjas>`, `self update`, PATH.
|
|
17
|
-
| `src/cmd/run.ts` | Fluxo de instalação/clone/update/reinstall e resumo de execução com aprovação.
|
|
18
|
-
| `src/
|
|
19
|
-
| `src/
|
|
20
|
-
| `src/
|
|
21
|
-
| `src/
|
|
22
|
-
| `src/
|
|
23
|
-
| `src/
|
|
24
|
-
| `src/
|
|
25
|
-
| `src/
|
|
26
|
-
| `src/
|
|
27
|
-
| `src/
|
|
28
|
-
| `src/
|
|
29
|
-
| `src/
|
|
30
|
-
| `src/
|
|
31
|
-
| `src/
|
|
32
|
-
| `src/
|
|
33
|
-
| `src/
|
|
34
|
-
| `src/
|
|
35
|
-
| `src/
|
|
10
|
+
| Módulo | Responsabilidade |
|
|
11
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
12
|
+
| `src/index.ts` | Só despacha: parse de args, menu, resolução do subcomando, SIGINT e erros fatais. |
|
|
13
|
+
| `src/cmd/shared.ts` | Banner, preflight, catálogo efetivo, `--json`, seleção de Forjas por nome. |
|
|
14
|
+
| `src/cmd/batch.ts` | Execução sequencial com spinner/taskLog por Forja. |
|
|
15
|
+
| `src/cmd/query.ts` | `doctor`, `list`, `status`, `update --check`, `versions` (com `--json`). |
|
|
16
|
+
| `src/cmd/manage.ts` | `pin`, `unpin`, `rollback`, `uninstall <forjas>`, `self update`, PATH. |
|
|
17
|
+
| `src/cmd/run.ts` | Fluxo de instalação/clone/update/reinstall e resumo de execução com aprovação. |
|
|
18
|
+
| `src/cmd/registry.ts` | `install/uninstall --method registry` e `registry`: plano, confirmação, `--json`/`--report`, probes. |
|
|
19
|
+
| `src/registry/` | Método registry-first: `catalog` (dists PyPI), `pypi` (resolve + cache), `versions` (PEP 440 subset), `install` (venv isolada, sha256, receipt/state). |
|
|
20
|
+
| `src/prompts.ts` | Prompts interativos (diretório, seleção, confirmação) e tratamento de cancelamento via `isCancel()`. |
|
|
21
|
+
| `src/preflight.ts` | Verificações de ambiente antes de qualquer prompt: `git`, Node.js >= 20, `powershell.exe` no Windows. |
|
|
22
|
+
| `src/runner.ts` | Pipeline por repositório com cronômetro e fases: sincronizar → `.env` → script de instalação. |
|
|
23
|
+
| `src/env.ts` | Provisionamento do `.env` (`planEnvFile` decide, `ensureEnvFile` executa). |
|
|
24
|
+
| `src/report.ts` | Badges de status, linha por repositório e relatório consolidado. |
|
|
25
|
+
| `src/ui/theme.ts` | Paleta de cores (picocolors) e ícones emoji. Único ponto de contato com cores. |
|
|
26
|
+
| `src/ui/strings.ts` | Todas as strings visíveis ao usuário, em PT-BR. |
|
|
27
|
+
| `src/constants/repos.ts` | Catálogo fixo dos oito repositórios Forge. |
|
|
28
|
+
| `src/utils/system.ts` | Primitivas: resolução de caminho, `.git`, seleção de script por SO, `execa`, detalhe de erro. |
|
|
29
|
+
| `src/commands.ts` | Resolve o subcomando (`install`, `clone`, `update`, `pin`, `self ...`) a partir dos posicionais. |
|
|
30
|
+
| `src/menu.ts` | Menu principal; só aparece com TTY e sem comando/flags de seleção. |
|
|
31
|
+
| `src/safety.ts` | Nomes/URLs de repositório válidos, bloqueio de symlink/junction, redação de segredos, escrita atômica. |
|
|
32
|
+
| `src/git-revs.ts` | Tags, checkout destacado por ref/versão, verificação de atualização via fetch. |
|
|
33
|
+
| `src/lifecycle.ts` | Plano e execução de uninstall (com backup) e rollback de checkout. |
|
|
34
|
+
| `src/native-install.ts` | Monta o `<cli> install` nativo da Forja com as flags que ela documenta. |
|
|
35
|
+
| `src/status.ts` | Fase local (não clonado, clonado, instalado, falha), versão e alterações. |
|
|
36
|
+
| `src/self.ts` | Detecta o método de instalação do CLI e planeja o `self update`. |
|
|
37
|
+
| `src/types.ts` | Tipos compartilhados (`ForgeRepo`, `RepoResult`, `InstallScript`, `PreflightCheck`). |
|
|
36
38
|
|
|
37
39
|
## Fluxo de execução
|
|
38
40
|
|
package/docs/capabilities.md
CHANGED
|
@@ -17,6 +17,53 @@ Revisões inspecionadas (HEAD de `main` em 2026-10-12):
|
|
|
17
17
|
| forge-doctor-data | `3ac1cae` |
|
|
18
18
|
| forge-portal | `d0b6ba9` |
|
|
19
19
|
|
|
20
|
+
## Métodos de instalação do forge-cli
|
|
21
|
+
|
|
22
|
+
- **git** (default) — clone + bootstrap `setup.sh`/`setup.ps1` +
|
|
23
|
+
instalador nativo sob opt-in (`--native`, `--profile`, `--scope`,
|
|
24
|
+
`--components`). É o fluxo descrito na matriz abaixo.
|
|
25
|
+
- **registry** — `install <forja> --method registry`: resolve a dist no
|
|
26
|
+
PyPI, cria venv isolada em `~/.forge-cli/forges/<nome>/venv`, baixa a
|
|
27
|
+
wheel para `~/.forge-cli/cache/wheels/`, confere sha256 contra o
|
|
28
|
+
digest publicado e instala pelo caminho do artefato verificado.
|
|
29
|
+
`uninstall --method registry` remove venv + wheel cache + receipt com
|
|
30
|
+
confirmação; `--plan`, `--offline`, `--clean`, `--version` pinado,
|
|
31
|
+
`--json` e `--report` são honrados. `--native` delega ao instalador
|
|
32
|
+
nativo **da venv** (dry-run sem `--yes`; `--profile`/`--scope`/
|
|
33
|
+
`--components`/`--host`/`--gateway-profile` passam adiante);
|
|
34
|
+
Forjas cujo instalador é script de repositório (forge-doctor-api)
|
|
35
|
+
recebem skip honesto — a wheel não carrega o script.
|
|
36
|
+
- **lifecycle registry** — `update` (mais nova no PyPI; `--check` só
|
|
37
|
+
planeja; respeita pin), `reinstall` (mesma versão do receipt — reparo
|
|
38
|
+
de drift), `rollback` (desempilha `history` do receipt; rollback de
|
|
39
|
+
rollback funciona), `pin`/`unpin` (trava a versão instalada no state).
|
|
40
|
+
Tudo com o mesmo contrato: receipts atômicos, `--json`/`--report`,
|
|
41
|
+
flags git ignoradas avisadas, nomes desconhecidos → exit 2, falhas → 1.
|
|
42
|
+
- **hosts/MCP sem clone** — `forge-cli mcp <forja>` resolve o argv MCP
|
|
43
|
+
(forge.json do clone ou template `mcp` do catálogo + receipt:
|
|
44
|
+
`{bin}` = bin da venv, `{binDir}/x` = script irmão); `--verify` roda
|
|
45
|
+
`--version` como handshake. `hosts plan|register|validate|rollback`
|
|
46
|
+
usam o mesmo descritor — `hosts register` grava `mcpServers` apontando
|
|
47
|
+
para o binário da venv registry.
|
|
48
|
+
- **portal** — `GET /api/v1/registry/state` no forge-portal projeta
|
|
49
|
+
`~/.forge-cli/forges/state.json` (contrato
|
|
50
|
+
`docs/registry-state-contract.md`).
|
|
51
|
+
|
|
52
|
+
## Matriz registry (PyPI)
|
|
53
|
+
|
|
54
|
+
| Forja | Dist PyPI | Piso Python | MCP (venv) | Nativo `--native` |
|
|
55
|
+
| ----------------- | ------------------- | ----------- | ---------------------------- | --------------------------- |
|
|
56
|
+
| the-forge | `theforge-core` | >=3.11 | — (sem mcp_command) | `theforge install apply` |
|
|
57
|
+
| api-forge | `apiforge-af` | >=3.12 | `apiforge-mcp` | `apiforge install` |
|
|
58
|
+
| platform-forge | `platformforge` | >=3.10 | `platformforge-mcp` | `platformforge install` |
|
|
59
|
+
| spark-forge-aws | `sparkforge-aws` | >=3.10 | `sparkforge-aws mcp serve` | `sparkforge-aws install` |
|
|
60
|
+
| spark-forge-azure | `sparkforge-azure` | >=3.10 | `sparkforge-azure mcp serve` | `sparkforge-azure install` |
|
|
61
|
+
| forge-doctor-data | `forge-doctor-data` | >=3.11 | `forge-doctor-data mcp` | `forge-doctor-data install` |
|
|
62
|
+
| forge-doctor-api | `forge-doctor-api` | >=3.11 | `forge-doctor-api mcp` | **não** (script de repo) |
|
|
63
|
+
|
|
64
|
+
`requires_python` publicado no PyPI é autoritativo por release; o piso da
|
|
65
|
+
tabela compõe com ele (o mais restritivo vence).
|
|
66
|
+
|
|
20
67
|
## Modelo de instalação em duas fases
|
|
21
68
|
|
|
22
69
|
1. **Bootstrap** — `setup.sh` / `setup.ps1` (todas as Forjas Python) chamam
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Contrato de estado registry — `forge-cli/RegistryState/v1`
|
|
2
|
+
|
|
3
|
+
Fonte única do formato que `forge-cli` escreve e que leitores externos
|
|
4
|
+
(forge-portal, scripts, hosts) podem consumir. O CLI é o único escritor;
|
|
5
|
+
leitores são somente-leitura e nunca inventam campos.
|
|
6
|
+
|
|
7
|
+
## Arquivos
|
|
8
|
+
|
|
9
|
+
| Arquivo | Conteúdo | Escrita |
|
|
10
|
+
| ----------------------------------------- | ----------------------------------------------------- | --------------------------- |
|
|
11
|
+
| `~/.forge-cli/forges/state.json` | Índice agregado `{ "forges": { <nome>: <receipt> } }` | atômica (`writeFileAtomic`) |
|
|
12
|
+
| `~/.forge-cli/forges/<nome>/receipt.json` | Receipt por Forja | atômica |
|
|
13
|
+
| `~/.forge-cli/forges/<nome>/install.json` | Metadados da instalação ativa | atômica |
|
|
14
|
+
| `~/.forge-cli/forges/state.json.corrupt` | Backup quando o state não parseia | rename |
|
|
15
|
+
|
|
16
|
+
`~` = `os.homedir()` do processo CLI (override de testes: `home` explícito
|
|
17
|
+
nas APIs; o portal honra `FORGE_HOME_OVERRIDE`).
|
|
18
|
+
|
|
19
|
+
## `state.json`
|
|
20
|
+
|
|
21
|
+
```json
|
|
22
|
+
{
|
|
23
|
+
"forges": {
|
|
24
|
+
"<nome-da-forja>": { "<receipt>" }
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
- Chaves são nomes de Forja validados por `isSafeRepoName`
|
|
30
|
+
(`[a-z0-9][a-z0-9-]*`, sem `..`, `/`, `\`) — leitores podem confiar que
|
|
31
|
+
chaves não carregam traversal.
|
|
32
|
+
- Valores não-objeto são filtrados na leitura (state poisoned degrada
|
|
33
|
+
para ausência, nunca crash).
|
|
34
|
+
|
|
35
|
+
## Receipt (por Forja)
|
|
36
|
+
|
|
37
|
+
| Campo | Tipo | Semântica |
|
|
38
|
+
| ---------------- | --------------------------- | ------------------------------------ |
|
|
39
|
+
| `forge` | string | nome da Forja |
|
|
40
|
+
| `method` | `"registry"` | método de instalação |
|
|
41
|
+
| `dist` | string | distribuição PyPI instalada |
|
|
42
|
+
| `version` | string | versão resolvida (PEP 440) |
|
|
43
|
+
| `requiresPython` | string? | spec do release (PyPI) |
|
|
44
|
+
| `python` | string | interpretador usado na venv |
|
|
45
|
+
| `source` | string | `pypi` ou `offline-cache` |
|
|
46
|
+
| `venv` | string | path absoluto da venv |
|
|
47
|
+
| `bin` | string | path absoluto do console script |
|
|
48
|
+
| `installedAt` | string | ISO 8601 |
|
|
49
|
+
| `verifiedHash` | string | `sha256:<hex>` do artefato instalado |
|
|
50
|
+
| `verify.ok` | bool | pós-install `<bin> --help` passou |
|
|
51
|
+
| `files` | string[] | artefatos gravados (bounded) |
|
|
52
|
+
| `yanked` | bool | release marcada yanked no PyPI |
|
|
53
|
+
| `staleCache` | bool | metadados vieram de cache expirado |
|
|
54
|
+
| `pinned` | string? | pin ativo (`pin --method registry`) |
|
|
55
|
+
| `history` | `{version, installedAt}[]`? | versões anteriores (rollback) |
|
|
56
|
+
|
|
57
|
+
Campos novos podem aparecer em versões futuras do CLI — leitores devem
|
|
58
|
+
tolerar campos desconhecidos e tratar campos conhecidos ausentes como
|
|
59
|
+
`null`/não-presentes.
|
|
60
|
+
|
|
61
|
+
## Leitura (forge-portal)
|
|
62
|
+
|
|
63
|
+
`portal_core.forge_portal.read_registry_state()` projeta o state em
|
|
64
|
+
`forge-cli/RegistryState/v1`:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"schema": "forge-cli/RegistryState/v1",
|
|
69
|
+
"state_path": "...",
|
|
70
|
+
"present": true,
|
|
71
|
+
"forges": { "<nome>": { "<receipt projetado>" } }
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- `present: false` (+ `error: "malformed"` quando aplicável) se o
|
|
76
|
+
arquivo não existir, não parsear ou `forges` não for objeto —
|
|
77
|
+
o portal renderiza "não instalado", nunca um receipt inventado.
|
|
78
|
+
- `GET /api/v1/registry/state` expõe a mesma projeção (somente-leitura,
|
|
79
|
+
host loopback + sessão, como toda a API do portal).
|
|
80
|
+
- Projeção é whitelist de escalares/containers pequenos — nada de
|
|
81
|
+
objetos arbitrários vindos do disco.
|