forjajs 4.0.1 → 4.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/CHANGELOG.md +170 -7
- package/DOC-MAP.md +1 -0
- package/README.md +10 -2
- package/README.pt-BR.md +3 -0
- package/dist/apps/cli/src/index.d.ts +18 -1
- package/dist/apps/cli/src/index.js +161 -26
- package/dist/apps/cli/src/params.d.ts +44 -0
- package/dist/apps/cli/src/params.js +123 -0
- package/dist/bin/forja.js +234 -13
- package/dist/bin/init-project.js +11 -62
- package/dist/lib/cli-output.d.ts +29 -0
- package/dist/lib/cli-output.js +39 -0
- package/dist/lib/core/checks.d.ts +1 -1
- package/dist/lib/core/health.d.ts +9 -0
- package/dist/lib/core/health.js +9 -0
- package/dist/lib/core/project-smoke.d.ts +6 -2
- package/dist/lib/core/project-smoke.js +83 -7
- package/dist/lib/core/registry.d.ts +38 -571
- package/dist/lib/core/registry.js +174 -25
- package/dist/lib/core/release.d.ts +1 -571
- package/dist/lib/core/release.js +0 -3
- package/dist/lib/handoffs-index.d.ts +16 -0
- package/dist/lib/handoffs-index.js +29 -0
- package/dist/lib/llm/claude-output.d.ts +8 -0
- package/dist/lib/llm/claude-output.js +54 -0
- package/dist/lib/llm/context.d.ts +22 -0
- package/dist/lib/llm/context.js +39 -0
- package/dist/lib/llm/session.d.ts +6 -1
- package/dist/lib/llm/session.js +12 -2
- package/dist/lib/multi-ai-instructions.d.ts +28 -0
- package/dist/lib/multi-ai-instructions.js +83 -0
- package/dist/lib/orchestrate.d.ts +5 -0
- package/dist/lib/orchestrate.js +18 -0
- package/dist/lib/specs-index.d.ts +20 -0
- package/dist/lib/specs-index.js +51 -0
- package/dist/lib/sprint-index.d.ts +15 -0
- package/dist/lib/sprint-index.js +34 -0
- package/dist/lib/status-model.d.ts +64 -0
- package/dist/lib/status-model.js +180 -0
- package/dist/packages/evals/src/index.d.ts +2 -0
- package/dist/packages/evals/src/index.js +21 -0
- package/dist/packages/llm/src/index.d.ts +24 -3
- package/dist/packages/llm/src/index.js +51 -5
- package/dist/scripts/cost-economy.js +12 -10
- package/dist/scripts/drift-check.d.ts +2 -0
- package/dist/scripts/drift-check.js +57 -1
- package/dist/scripts/engineer.js +7 -4
- package/dist/scripts/forja-setup.d.ts +14 -0
- package/dist/scripts/forja-setup.js +58 -0
- package/dist/scripts/forja-status.d.ts +11 -0
- package/dist/scripts/forja-status.js +70 -0
- package/dist/scripts/hook-session-start.js +20 -46
- package/dist/scripts/llm-fit.js +113 -8
- package/dist/scripts/project-smoke.js +13 -3
- package/dist/scripts/simulate.js +18 -6
- package/dist/scripts/token-economy.js +34 -28
- package/dist/scripts/tools-doctor.js +14 -6
- package/docs/2x/CLI-CAPABILITIES.md +34 -10
- package/docs/agent-operating-contract.md +3 -1
- package/docs/cli-first-operacao.md +17 -0
- package/docs/contrato-saida-cli.md +79 -0
- package/docs/llm-evolution.md +2 -1
- package/docs/llm-fit-loop.md +74 -2
- package/docs/publishing.md +13 -16
- package/docs/quick-reference.md +13 -0
- package/docs/roadmap-v4.1.md +199 -0
- package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
- package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
- package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
- package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
- package/package.json +4 -1
- package/specs/cli-intuitiva-v1/plan.md +169 -0
- package/specs/cli-intuitiva-v1/spec.md +163 -0
- package/specs/cli-intuitiva-v1/tasks.md +224 -0
- package/specs/contrato-saida-cli/plan.md +162 -0
- package/specs/contrato-saida-cli/spec.md +157 -0
- package/specs/contrato-saida-cli/tasks.md +153 -0
- package/specs/drift-sentinel/spec.md +17 -8
- package/specs/forja-status-caminho-feliz/plan.md +149 -0
- package/specs/forja-status-caminho-feliz/spec.md +158 -0
- package/specs/forja-status-caminho-feliz/tasks.md +175 -0
- package/specs/llm-adaptador-claude/plan.md +117 -0
- package/specs/llm-adaptador-claude/spec.md +144 -0
- package/specs/llm-adaptador-claude/tasks.md +100 -0
- package/specs/llm-benchmark-recomendacao/plan.md +121 -0
- package/specs/llm-benchmark-recomendacao/spec.md +141 -0
- package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
- package/specs/llm-contexto-e-sessoes/plan.md +143 -0
- package/specs/llm-contexto-e-sessoes/spec.md +139 -0
- package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
- package/specs/mcp-cobertura-nucleo/plan.md +158 -0
- package/specs/mcp-cobertura-nucleo/spec.md +161 -0
- package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
- package/specs/projeto-gerado-confiavel/plan.md +148 -0
- package/specs/projeto-gerado-confiavel/spec.md +142 -0
- package/specs/projeto-gerado-confiavel/tasks.md +139 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,18 +2,181 @@
|
|
|
2
2
|
|
|
3
3
|
Histórico consolidado das mudanças estruturais do framework. Para decisões arquiteturais com rationale, ver `memory/90-decisions/`.
|
|
4
4
|
|
|
5
|
+
### Como escrever uma entrada de versão
|
|
6
|
+
|
|
7
|
+
Toda versão nova (ao tagear / publicar) abre com uma subseção **`### O que melhorou`** em
|
|
8
|
+
linguagem de produto: o diff observável em relação à versão anterior — o que o usuário passa a
|
|
9
|
+
conseguir fazer, o que para de dar errado, o que fica mais simples. Só depois vêm as seções
|
|
10
|
+
técnicas (`Adicionado`, `Alterado`, `Mudança de contrato`, `Notas…`). A nota de release do
|
|
11
|
+
GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — ver
|
|
12
|
+
[`docs/publishing.md`](docs/publishing.md).
|
|
13
|
+
|
|
5
14
|
---
|
|
6
15
|
|
|
7
|
-
## [
|
|
16
|
+
## [Unreleased]
|
|
8
17
|
|
|
9
|
-
###
|
|
18
|
+
### O que melhorou
|
|
10
19
|
|
|
11
|
-
|
|
12
|
-
estado ou das permissões do cache global; o cache é removido ao final do gate.
|
|
13
|
-
- Guia de publicação documenta o cache isolado, o acesso ao registry e a instalação das
|
|
14
|
-
dependências do checkout antes dos gates.
|
|
20
|
+
_(preencher a cada release: diff de produto vs. a versão anterior, antes das seções técnicas)_
|
|
15
21
|
|
|
16
|
-
|
|
22
|
+
## [4.1.1] — 2026-09-08 — Disciplina de release: README + "O que melhorou" acompanham toda versão
|
|
23
|
+
|
|
24
|
+
### O que melhorou
|
|
25
|
+
|
|
26
|
+
- **Toda versão nova passa a dizer, em linguagem de produto, o que melhorou.** Cada entrada do
|
|
27
|
+
`CHANGELOG.md` abre por uma subseção `### O que melhorou` — o diff observável vs. a versão
|
|
28
|
+
anterior — antes das seções técnicas. É esse bloco que vira a nota de release no GitHub.
|
|
29
|
+
- **O README não fica mais para trás.** Reconciliar `README.md` e `README.pt-BR.md` com o
|
|
30
|
+
comportamento da versão virou passo obrigatório do runbook de release, não um "se lembrar".
|
|
31
|
+
|
|
32
|
+
### Alterado
|
|
33
|
+
|
|
34
|
+
- `CHANGELOG.md` ganha a seção **"Como escrever uma entrada de versão"** e um esqueleto em
|
|
35
|
+
`[Unreleased]`; a entrada da 4.1.0 foi retroalimentada com sua subseção `### O que melhorou`.
|
|
36
|
+
- `docs/publishing.md` — "Preparar uma versão" reescrito como checklist de 6 passos: reconciliar
|
|
37
|
+
README (passo 2) e escrever o `### O que melhorou` (passo 3) são explícitos; a etapa de tag no
|
|
38
|
+
GitHub aponta para esse bloco como corpo da release.
|
|
39
|
+
- `docs/agent-operating-contract.md` (§Entrega) e `CLAUDE.md` (§Convenções → Releases) registram
|
|
40
|
+
a regra: README reconciliado + subseção `### O que melhorou` são parte da entrega de qualquer
|
|
41
|
+
bump de versão / tag / publicação.
|
|
42
|
+
- `README.md` / `README.pt-BR.md` — nova convenção **Releases** / **Releases**.
|
|
43
|
+
|
|
44
|
+
### Notas
|
|
45
|
+
|
|
46
|
+
- Sem mudança de código nem de contrato de CLI. Nenhum comando, flag ou saída `--json` muda.
|
|
47
|
+
|
|
48
|
+
## [4.1.0] — 2026-09-08 — Roadmap v4.1: menos erros, mais intuitivo, mais funcional com LLMs
|
|
49
|
+
|
|
50
|
+
### O que melhorou
|
|
51
|
+
|
|
52
|
+
- **Menos erros na CLI.** `--json` agora sempre devolve um único objeto com chave `status`
|
|
53
|
+
(`ok`/`error`/`rejected`) e exit codes previsíveis (0/1/2/127); comando com argumento
|
|
54
|
+
obrigatório faltando imprime o `Uso:` e falha limpo, sem stack trace; `simulate` com
|
|
55
|
+
recomendação `discard` passa a sinalizar rejeição (exit 2) em vez de fingir sucesso.
|
|
56
|
+
- **Operação mais intuitiva.** `forja help <comando>` (e `--help`) explica uso, exemplos e
|
|
57
|
+
próximos passos; `forja setup` cobre o primeiro uso num comando; `forja status` dá o retrato
|
|
58
|
+
único do estado e `forja next` diz a próxima ação e o comando exato; erro de digitação
|
|
59
|
+
(`forja plan`) sugere o comando certo (`spec:plan`); o `help` sem argumento mostra só o núcleo,
|
|
60
|
+
agrupado por domínio.
|
|
61
|
+
- **Mais funcional com LLMs.** Adaptador **Claude** com retomada de sessão (`llm:run --resume`,
|
|
62
|
+
`llm:sessions`), paridade com o Codex; `llm:run --engineer` injeta o contexto de engenharia no
|
|
63
|
+
prompt; `llm:recommend` passa a pesar latência e custo com evidência por candidato; `llm:eval`
|
|
64
|
+
reporta p50/p95 e custo por tarefa aceita; o fluxo SDD roda por MCP (cobertura 6 → 18 comandos).
|
|
65
|
+
- **Gerador de projeto mais confiável.** `project:smoke --ai <lista>` exercita o caminho real
|
|
66
|
+
multi-IA (memória + instruções nativas por IA) e o CI roda isso em matriz a cada PR.
|
|
67
|
+
- **Drift sentinel utilizável.** `forja drift:check --all` roda o sentinela uma vez por projeto
|
|
68
|
+
do workspace — o modo lote para retomar projetos parados há meses (SPEC-030 fecha em `done`).
|
|
69
|
+
|
|
70
|
+
**Roadmap v4.1 concluído** ([`docs/roadmap-v4.1.md`](docs/roadmap-v4.1.md)): as 12 workstreams
|
|
71
|
+
(W1–W12) — menos erros, operação mais intuitiva, mais funcional com LLMs — foram implementadas
|
|
72
|
+
pelo pipeline SDD do próprio Forja e merjadas em `main` (PRs #61–#69). Specs SPEC-043 a SPEC-050
|
|
73
|
+
em `done`; `drift-sentinel` (SPEC-030) segue `implementing` por desenho (ADR-0084, janela de
|
|
74
|
+
observação até 2026-10-08). ADRs estruturais: 0082 (contrato de saída CLI), 0083 (cobertura MCP
|
|
75
|
+
declarativa), 0084 (fecho do drift-sentinel), 0085 (adaptador Claude). Detalhe de cada frente
|
|
76
|
+
nas entradas abaixo.
|
|
77
|
+
|
|
78
|
+
### Adicionado
|
|
79
|
+
|
|
80
|
+
- `forja llm:run --engineer "<objetivo>"` — monta o contexto pelo façade `engineer` (ADRs, risco,
|
|
81
|
+
fluxo, …) e o embute no prompt. O hash cobre o prompt transmitido; em `contextRefs` fica só a
|
|
82
|
+
referência `engineer:<objetivo>`, nunca o conteúdo. Falha do façade → `errorCode:
|
|
83
|
+
"ENGINEER_FAILED"` antes de chamar o provedor. (SPEC-048)
|
|
84
|
+
- `forja llm:sessions list|show` — leitura das sessões LLM registradas (`llm_session`) para
|
|
85
|
+
recuperar o `SESSION_ID` que `llm:run --resume` exige. Somente leitura. (SPEC-048)
|
|
86
|
+
- `forja llm:eval` reporta `durationMsP50`/`durationMsP95` e `costPerAcceptedTask`
|
|
87
|
+
(`totalCost / tarefas aceitas`; 0 quando nenhuma). As métricas anteriores não mudam. (SPEC-049)
|
|
88
|
+
- `forja llm:recommend` pondera **latência e custo** além do fit declarado e do sucesso local
|
|
89
|
+
(bônus limitado — nunca inverte um fit) e devolve `evidence` por candidato
|
|
90
|
+
(`samples`, `medianDurationMs`, `meanCostUsd`, `successRate`) + `reasons` com `latency:p50=…` /
|
|
91
|
+
`cost:$…/run`. Nenhum percentual de ganho é afirmado antes de um baseline de 30 dias. (SPEC-049)
|
|
92
|
+
- Adaptador **Claude** com paridade de retomada e formato: `llm:run --profile claude` invoca
|
|
93
|
+
`claude -p "<prompt>" --output-format json [--resume <id>]` (`shell:false`, sem ler API keys),
|
|
94
|
+
normaliza o objeto JSON único do provedor (`result`/`session_id`/`usage`) e trata
|
|
95
|
+
`is_error`/`subtype` como erro visível. `RESUME_PROVIDERS = { codex, claude }` — `--resume` e
|
|
96
|
+
`llm:sessions` passam a valer para Claude. `--output-schema` com o perfil `claude` é validação
|
|
97
|
+
**local (Ajv)**, não geração garantida pelo provedor; `llm:probe claude` reporta
|
|
98
|
+
`features.resume: true` / `features.outputSchema: false`. (SPEC-050, ADR-0085)
|
|
99
|
+
- `forja help <comando>` — uso, argumentos posicionais, exemplos e próximos passos de cada
|
|
100
|
+
comando, a partir de campos novos e opcionais do registry (`usage`, `cliArgs`, `examples`,
|
|
101
|
+
`next`, `spec`, `tier`). `forja <comando> --help` faz o mesmo inline. (SPEC-043)
|
|
102
|
+
- `forja setup` — rotina de primeiro uso (`workspace:init` + `sync:universal`) atrás de
|
|
103
|
+
confirmação; `--yes` para uso não-interativo; aborta sem efeito quando não há TTY. (SPEC-043)
|
|
104
|
+
- `forja status` — retrato único do estado: workspace, sprint, corrida orchestrate aberta,
|
|
105
|
+
specs por status, últimos runs, handoffs em aberto. `--json` estável; cada seção degrada com
|
|
106
|
+
`indisponível: <motivo>`. (SPEC-044)
|
|
107
|
+
- `forja next` — a próxima ação recomendada e o comando exato, por prioridade determinística
|
|
108
|
+
(workspace ausente → `setup`; memória crua → `sync:universal`; corrida travada → parecer +
|
|
109
|
+
`orchestrate:advance`; spec `approved` sem plan → `spec:plan`; …). `--json` →
|
|
110
|
+
`{ action, command, reason }`. (SPEC-044)
|
|
111
|
+
- `suggest()` passou a casar por substring **e** distância de edição sobre o nome completo:
|
|
112
|
+
`forja plan` sugere `spec:plan`. Toda mensagem de comando desconhecido termina com
|
|
113
|
+
`forja help <palpite>`. (SPEC-043)
|
|
114
|
+
- Argumento posicional obrigatório em falta falha **antes** de invocar o script-filho, imprimindo
|
|
115
|
+
o `Uso:` do comando — sem stack trace. (SPEC-043)
|
|
116
|
+
- **Contrato de saída da CLI** ([ADR-0082](memory/90-decisions/0082-contrato-saida-cli.md),
|
|
117
|
+
[`docs/contrato-saida-cli.md`](docs/contrato-saida-cli.md)): `--json` emite um único objeto com
|
|
118
|
+
chave `status` (`ok`|`error`|`rejected`); exit codes 0/1/2/127. `lib/cli-output.ts`
|
|
119
|
+
(`emitOk`/`emitError`/`emitRejected`) impõe o formato; `test/cli-output-contract.test.js` itera
|
|
120
|
+
o registry e reprova qualquer `json: true` que desvie. Conjunto conformado: `status`, `next`,
|
|
121
|
+
`engineer`, `simulate`, `cost:economy`, `token:economy`. (SPEC-045)
|
|
122
|
+
- **Cobertura MCP de 6 → 18 comandos** ([ADR-0083](memory/90-decisions/0083-mcp-cobertura-declarativa.md)):
|
|
123
|
+
`spec:new`, `spec:plan`, `spec:tasks`, `query:universal`, `engineer`, `risk:assess`,
|
|
124
|
+
`orchestrate:status`, `orchestrate:advance`, `drift:check`, `code:context`, `status`, `next`
|
|
125
|
+
viram capabilities tipadas — `forja mcp:start` → `tools/list` passa a expô-las e o fluxo SDD
|
|
126
|
+
roda por `tools/call`. Mapeamento argv↔payload declarativo (`apps/cli/src/params.ts`,
|
|
127
|
+
`parseArgv`/`argvFor` inversos com round-trip test); o `if/else` por comando some. `spec:check`
|
|
128
|
+
e `tools:doctor` fecham o débito D7 de SPEC-045 (agora `json: true`). (SPEC-046)
|
|
129
|
+
- `forja project:smoke --ai <lista>` — o gate do projeto gerado passa a exercitar o caminho real
|
|
130
|
+
do `--ai` (memória + instruções nativas por IA), gerado só-memória e sem rede. (SPEC-047)
|
|
131
|
+
- Check `ai-instructions` no `project:smoke`: quando `--ai` é pedido, prova que cada
|
|
132
|
+
`.ia-instructions/<ai>.md` deriva da mesma fonte (corpo byte-idêntico entre IAs, só o cabeçalho
|
|
133
|
+
muda) e que `models.json` bate com a lista. É o análogo do `agent-topology`, na saída do gerador. (SPEC-047)
|
|
134
|
+
- `.github/workflows/ci.yml` — job `project-smoke-ai` em matriz (`claude` · `copilot` ·
|
|
135
|
+
`claude,copilot,gemini,codex`), tier barato, a cada PR e push. (SPEC-047)
|
|
136
|
+
- `lib/multi-ai-instructions.ts` — a escrita das instruções nativas por IA vira função `lib/`
|
|
137
|
+
testada, compartilhada por `bin/init-project.ts` e pelo smoke. (SPEC-047)
|
|
138
|
+
- `forja drift:check --all` — roda o sentinela de drift uma vez por projeto do workspace, cada um
|
|
139
|
+
num grafo isolado e persistente (`<projeto>/.context/drift-graph.db`). É o modo lote que a
|
|
140
|
+
SPEC-030 §3 previa: rodar antes de retomar um projeto parado há meses. (SPEC-030, ADR-0084)
|
|
141
|
+
|
|
142
|
+
### Alterado
|
|
143
|
+
|
|
144
|
+
- **SPEC-030 (Drift Sentinel) fecha** ([ADR-0084](memory/90-decisions/0084-drift-sentinel-fecha.md)):
|
|
145
|
+
a métrica de sucesso do §8 (drift real encontrado no mundo) era infalsificável como bloqueio de
|
|
146
|
+
`done` — foi reformulada para um aceite verificável agora (determinismo, zero falso positivo no
|
|
147
|
+
monorepo, `--all` completa), e "drift real no mundo" virou janela de observação até 2026-10-08.
|
|
148
|
+
`drift:check` segue como gate opt-in (`check:all --with-drift`), inalterado. Status → `done`.
|
|
149
|
+
- **`--json` de comando-capability** (`spec:check`, `tools:doctor`, `code:impact`, `spec:new`, …)
|
|
150
|
+
deixa de emitir o `ExecutionResult` cru e passa a seguir o contrato de saída (`{ status, … }`)
|
|
151
|
+
via o adaptador `toContract` em `bin/forja.ts`. O consumo por MCP (`tools/call`) não muda.
|
|
152
|
+
(SPEC-046, ADR-0083)
|
|
153
|
+
- **`token:economy --json`** deixa de emitir um array cru — passa a `{ "status": "ok",
|
|
154
|
+
"rows": [...] }`. Quebra do JSON desse comando (ADR-0082). (SPEC-045)
|
|
155
|
+
- **`simulate`** com recomendação `discard`: exit code passa de `0` para **`2`** e, com `--json`,
|
|
156
|
+
`status: "rejected"` — é um gate negativo, não sucesso (ADR-0082). (SPEC-045)
|
|
157
|
+
- **`cost:economy --json`** deixava de ser parseável (avisos de texto iam no stdout); agora o
|
|
158
|
+
stdout é só o objeto, avisos vão para o stderr. (SPEC-045)
|
|
159
|
+
|
|
160
|
+
- `forja help` (sem argumentos) lista só os comandos do núcleo (`tier: 'core'`), agrupados por
|
|
161
|
+
domínio, com rodapé para `forja help --all`. `forja help --all` preserva a saída completa
|
|
162
|
+
anterior; os sufixos `(SPEC-0XX)` saíram das descrições do núcleo para o detalhe de `help <cmd>`. (SPEC-043)
|
|
163
|
+
- `orchestrate` e os comandos de estado (`status`, `next`) abrem o bloco GSD no `forja help` —
|
|
164
|
+
o caminho feliz em primeiro lugar. (SPEC-044)
|
|
165
|
+
- `tools:doctor` e o bloco `<framework-status>` do SessionStart agrupam os checks em três blocos
|
|
166
|
+
rotulados — **Bloqueia o fluxo**, **Rotina de primeiro uso**, **Opcional (ferramentas)**. O
|
|
167
|
+
exit code do gate é inalterado. Mudança aditiva. (SPEC-043)
|
|
168
|
+
- `listSpecs` e `openHandoffs` saíram de `scripts/hook-session-start.ts` para
|
|
169
|
+
`lib/specs-index.ts` / `lib/handoffs-index.ts`, compartilhados com `forja status`. `listRuns`
|
|
170
|
+
novo em `lib/orchestrate.ts`. (SPEC-044)
|
|
171
|
+
|
|
172
|
+
### Notas de contrato
|
|
173
|
+
|
|
174
|
+
- Decidido no plan (`specs/cli-intuitiva-v1/`): o `--fix` da spec original virou o comando
|
|
175
|
+
dedicado `forja setup` — `tools:doctor` continua só diagnóstico, por desenho. O campo de args
|
|
176
|
+
posicionais no registry chama-se `cliArgs` (não `args`, que é o prefixo fixo do spawn).
|
|
177
|
+
- `spec:check` e `tools:doctor` entraram no contrato de saída via SPEC-046: o envelope da
|
|
178
|
+
capability MCP é convertido pelo adaptador `toContract` em `bin/forja.ts` (fecha o débito D7
|
|
179
|
+
de SPEC-045).
|
|
17
180
|
|
|
18
181
|
## [4.0.0] — 2026-09-05 — Integrações LLM, sessões e validação
|
|
19
182
|
|
package/DOC-MAP.md
CHANGED
|
@@ -55,6 +55,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
55
55
|
| Manual operacional CLI-first | `docs/manual-operacional-cli-sdd-gsd.md` |
|
|
56
56
|
| Modos embedded e studio | `docs/modos-de-operacao.md` |
|
|
57
57
|
| Guia curto CLI-first | `docs/cli-first-operacao.md` |
|
|
58
|
+
| Contrato de saída da CLI (`--json` + exit codes) | `docs/contrato-saida-cli.md` |
|
|
58
59
|
| Mudanças recentes | `CHANGELOG.md` |
|
|
59
60
|
| Decisões arquiteturais | `memory/90-decisions/` |
|
|
60
61
|
| Glossário | `docs/glossary.md` |
|
package/README.md
CHANGED
|
@@ -220,6 +220,11 @@ scripts are thin aliases that route through the core.
|
|
|
220
220
|
## Essential commands
|
|
221
221
|
|
|
222
222
|
```bash
|
|
223
|
+
# Orientation — the happy path
|
|
224
|
+
forja status # where am I: workspace, sprint, run, specs, runs, handoffs
|
|
225
|
+
forja next # what now: one line — the next action + the exact command
|
|
226
|
+
forja help [<command>|--all] # the core, or one command's usage/args/examples/next steps
|
|
227
|
+
|
|
223
228
|
# Workspace & projects
|
|
224
229
|
forja workspace:init # create ~/forja-workspace
|
|
225
230
|
forja project:new <name> --ai claude,copilot # create a project in the workspace
|
|
@@ -234,7 +239,7 @@ forja sprint:start # also: sprint:status · sprint:compl
|
|
|
234
239
|
forja gsd:plan <slug> # GSD runbook in .context/
|
|
235
240
|
forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
|
|
236
241
|
forja gsd:check <slug> # baseline runbook gates
|
|
237
|
-
forja orchestrate "<goal>" --slug <s> #
|
|
242
|
+
forja orchestrate "<goal>" --slug <s> # the default path: the whole SDD/GSD chain as a gated state machine (SPEC-021)
|
|
238
243
|
forja orchestrate:status <slug> # the machine state: stages, gates, verdicts
|
|
239
244
|
forja orchestrate:advance <slug> # run the stage gate; green → next; red → blocked
|
|
240
245
|
|
|
@@ -290,7 +295,7 @@ forja cost:economy # real $ cost per model, from the obs
|
|
|
290
295
|
forja project:check # framework standards (pre-commit)
|
|
291
296
|
forja tools:doctor # core X-ray; tells permission/lock from corruption; exit 1 if broken
|
|
292
297
|
forja release:check --publish # tarball gate before publishing
|
|
293
|
-
forja project:smoke # generated-project gate; --full installs
|
|
298
|
+
forja project:smoke # generated-project gate; --full installs+builds; --ai <list> checks native instructions
|
|
294
299
|
forja project:dashboard # static status report
|
|
295
300
|
|
|
296
301
|
# Governance & audit
|
|
@@ -360,6 +365,9 @@ output, code, and ADRs are readable regardless of language.
|
|
|
360
365
|
- **CLI-first** — sprints, SDD, GSD, handoffs, and governance by command; the UI is never a gate.
|
|
361
366
|
- **ADRs** — every structural decision becomes `memory/90-decisions/NNNN-title.md`.
|
|
362
367
|
- **Handoffs** — 7 required fields (ADR-0005), stored in SQLite (ADR-0008).
|
|
368
|
+
- **Releases** — every new version reconciles the README with its behavior and opens its
|
|
369
|
+
`CHANGELOG.md` entry with a `### O que melhorou` section (product-language diff vs. the previous
|
|
370
|
+
version, reused as the GitHub release note). Runbook: [`docs/publishing.md`](docs/publishing.md).
|
|
363
371
|
- **pt-BR** — communication and documentation in Portuguese.
|
|
364
372
|
|
|
365
373
|
## Roadmap
|
package/README.pt-BR.md
CHANGED
|
@@ -293,6 +293,9 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
|
|
|
293
293
|
- **CLI-first** — sprints, SDD, GSD, handoffs e governança por comando; o front nunca é gate.
|
|
294
294
|
- **ADRs** — toda decisão estrutural vira `memory/90-decisions/NNNN-titulo.md`.
|
|
295
295
|
- **Handoffs** — 7 campos obrigatórios (ADR-0005), gravados no SQLite (ADR-0008).
|
|
296
|
+
- **Releases** — toda versão nova reconcilia o README com o seu comportamento e abre a entrada do
|
|
297
|
+
`CHANGELOG.md` por uma seção `### O que melhorou` (diff em linguagem de produto vs. a versão
|
|
298
|
+
anterior, reusada como nota de release no GitHub). Runbook: [`docs/publishing.md`](docs/publishing.md).
|
|
296
299
|
- **pt-BR** — comunicação e documentação em português.
|
|
297
300
|
|
|
298
301
|
## Roadmap
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { type AgentIdentity, type CapabilityId, type ExecutionResult } from '../../../packages/contracts/src/index.ts';
|
|
2
2
|
import { CapabilityRegistry } from '../../../packages/core/src/index.ts';
|
|
3
|
-
import { PolicyEngine } from '../../../packages/policy/src/index.ts';
|
|
3
|
+
import { PolicyEngine, type PolicyCategory } from '../../../packages/policy/src/index.ts';
|
|
4
4
|
import { GraphLoop, type GraphDocumentSource } from '../../../packages/graph/src/index.ts';
|
|
5
|
+
import { type CapabilityParam } from './params.ts';
|
|
5
6
|
export interface LegacyCliResult {
|
|
6
7
|
readonly exitCode: number;
|
|
7
8
|
readonly stdout: string;
|
|
@@ -28,6 +29,22 @@ export declare function createLegacyCliRunner(root: string, cwd?: string): Legac
|
|
|
28
29
|
interface InputRecord {
|
|
29
30
|
readonly [key: string]: unknown;
|
|
30
31
|
}
|
|
32
|
+
interface CliCapabilitySpec<Input extends InputRecord> {
|
|
33
|
+
readonly id: CapabilityId;
|
|
34
|
+
readonly command: string;
|
|
35
|
+
readonly description: string;
|
|
36
|
+
readonly categories: readonly PolicyCategory[];
|
|
37
|
+
readonly permissions: readonly string[];
|
|
38
|
+
readonly risk: 'low' | 'medium' | 'high' | 'critical';
|
|
39
|
+
readonly sideEffects: readonly string[];
|
|
40
|
+
/** argv↔payload declarativo (SPEC-046). `toArgs` e o parse de argv derivam daqui. */
|
|
41
|
+
readonly params: readonly CapabilityParam[];
|
|
42
|
+
/** Opcional: só quando há checagem além de "required + tipo" (range, enum). Default: `makeValidator(params)`. */
|
|
43
|
+
readonly validateInput?: (value: unknown) => Input;
|
|
44
|
+
/** Opcional: `timeoutMs` do registry quando o default de 30s é curto. */
|
|
45
|
+
readonly timeoutMs?: number;
|
|
46
|
+
}
|
|
47
|
+
export declare const CLI_CAPABILITY_SPECS: readonly CliCapabilitySpec<InputRecord>[];
|
|
31
48
|
export declare const CLI_COMMAND_TO_CAPABILITY: Readonly<Record<string, CapabilityId>>;
|
|
32
49
|
/** Interface commands for discovering/executing capabilities; handlers remain in the registry. */
|
|
33
50
|
export declare const CLI_INTERFACE_COMMANDS: readonly ["capabilities:list", "capabilities:describe", "capability:execute", "mcp:start"];
|
|
@@ -5,6 +5,7 @@ import { CapabilityRegistry, } from "../../../packages/core/src/index.js";
|
|
|
5
5
|
import { PolicyEngine } from "../../../packages/policy/src/index.js";
|
|
6
6
|
import { COMMANDS, resolveScript } from "../../../lib/core/registry.js";
|
|
7
7
|
import { GraphIndexer } from "../../../packages/graph/src/index.js";
|
|
8
|
+
import { parseArgv, argvFor, makeValidator } from "./params.js";
|
|
8
9
|
export function createLegacyCliRunner(root, cwd = process.cwd()) {
|
|
9
10
|
return (command, args) => {
|
|
10
11
|
const definition = COMMANDS[command];
|
|
@@ -17,7 +18,8 @@ export function createLegacyCliRunner(root, cwd = process.cwd()) {
|
|
|
17
18
|
return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: [result.stderr ?? '', result.error?.message ?? ''].filter(Boolean).join('\n') };
|
|
18
19
|
};
|
|
19
20
|
}
|
|
20
|
-
const CLI_CAPABILITY_SPECS = [
|
|
21
|
+
export const CLI_CAPABILITY_SPECS = [
|
|
22
|
+
// --- Os 6 originais: mesma assinatura, `params` no lugar do `toArgs` manual (SPEC-046) ---
|
|
21
23
|
{
|
|
22
24
|
id: 'system.doctor',
|
|
23
25
|
command: 'tools:doctor',
|
|
@@ -26,8 +28,8 @@ const CLI_CAPABILITY_SPECS = [
|
|
|
26
28
|
permissions: ['read'],
|
|
27
29
|
risk: 'low',
|
|
28
30
|
sideEffects: [],
|
|
31
|
+
params: [],
|
|
29
32
|
validateInput: emptyInput,
|
|
30
|
-
toArgs: () => [],
|
|
31
33
|
},
|
|
32
34
|
{
|
|
33
35
|
id: 'code.impact',
|
|
@@ -37,8 +39,11 @@ const CLI_CAPABILITY_SPECS = [
|
|
|
37
39
|
permissions: ['read'],
|
|
38
40
|
risk: 'low',
|
|
39
41
|
sideEffects: [],
|
|
42
|
+
params: [
|
|
43
|
+
{ name: 'symbol', kind: 'positional', required: true },
|
|
44
|
+
{ name: 'depth', kind: 'positional', parse: 'int' },
|
|
45
|
+
],
|
|
40
46
|
validateInput: validateCodeImpactInput,
|
|
41
|
-
toArgs: (input) => input.depth === undefined ? [input.symbol] : [input.symbol, String(input.depth)],
|
|
42
47
|
},
|
|
43
48
|
{
|
|
44
49
|
id: 'context.budget',
|
|
@@ -48,8 +53,11 @@ const CLI_CAPABILITY_SPECS = [
|
|
|
48
53
|
permissions: ['read'],
|
|
49
54
|
risk: 'low',
|
|
50
55
|
sideEffects: ['context_run_record'],
|
|
56
|
+
params: [
|
|
57
|
+
{ name: 'target', kind: 'positional', required: true },
|
|
58
|
+
{ name: 'limitTokens', kind: 'positional', parse: 'int' },
|
|
59
|
+
],
|
|
51
60
|
validateInput: validateContextBudgetInput,
|
|
52
|
-
toArgs: (input) => input.limitTokens === undefined ? [input.target] : [input.target, String(input.limitTokens)],
|
|
53
61
|
},
|
|
54
62
|
{
|
|
55
63
|
id: 'spec.validate',
|
|
@@ -59,8 +67,8 @@ const CLI_CAPABILITY_SPECS = [
|
|
|
59
67
|
permissions: ['read'],
|
|
60
68
|
risk: 'low',
|
|
61
69
|
sideEffects: [],
|
|
70
|
+
params: [{ name: 'feature', kind: 'positional' }],
|
|
62
71
|
validateInput: validateSpecCheckInput,
|
|
63
|
-
toArgs: (input) => input.feature === undefined ? [] : [input.feature],
|
|
64
72
|
},
|
|
65
73
|
{
|
|
66
74
|
id: 'sprint.status',
|
|
@@ -70,8 +78,8 @@ const CLI_CAPABILITY_SPECS = [
|
|
|
70
78
|
permissions: ['read'],
|
|
71
79
|
risk: 'low',
|
|
72
80
|
sideEffects: [],
|
|
81
|
+
params: [{ name: 'project', kind: 'positional' }],
|
|
73
82
|
validateInput: validateSprintStatusInput,
|
|
74
|
-
toArgs: (input) => input.project === undefined ? [] : [input.project],
|
|
75
83
|
},
|
|
76
84
|
{
|
|
77
85
|
id: 'handoff.create',
|
|
@@ -81,8 +89,146 @@ const CLI_CAPABILITY_SPECS = [
|
|
|
81
89
|
permissions: ['write'],
|
|
82
90
|
risk: 'low',
|
|
83
91
|
sideEffects: ['handoff_record'],
|
|
92
|
+
params: [
|
|
93
|
+
{ name: 'phase', kind: 'positional', required: true },
|
|
94
|
+
{ name: 'slug', kind: 'positional', required: true },
|
|
95
|
+
{ name: 'context', kind: 'rest' },
|
|
96
|
+
],
|
|
84
97
|
validateInput: validateHandoffInput,
|
|
85
|
-
|
|
98
|
+
},
|
|
99
|
+
// --- SPEC-046 / ADR-0083: o núcleo do fluxo operável por MCP ---
|
|
100
|
+
{
|
|
101
|
+
id: 'spec.create',
|
|
102
|
+
command: 'spec:new',
|
|
103
|
+
description: 'Cria specs/<slug>/spec.md a partir do template.',
|
|
104
|
+
categories: ['write'],
|
|
105
|
+
permissions: ['write'],
|
|
106
|
+
risk: 'low',
|
|
107
|
+
sideEffects: ['spec_file'],
|
|
108
|
+
params: [{ name: 'slug', kind: 'positional', required: true }],
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
id: 'spec.plan',
|
|
112
|
+
command: 'spec:plan',
|
|
113
|
+
description: 'Deriva plan.md de uma spec aprovada.',
|
|
114
|
+
categories: ['write'],
|
|
115
|
+
permissions: ['write'],
|
|
116
|
+
risk: 'low',
|
|
117
|
+
sideEffects: ['spec_file'],
|
|
118
|
+
params: [{ name: 'slug', kind: 'positional', required: true }],
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
id: 'spec.tasks',
|
|
122
|
+
command: 'spec:tasks',
|
|
123
|
+
description: 'Decompõe plan.md em tasks.md.',
|
|
124
|
+
categories: ['write'],
|
|
125
|
+
permissions: ['write'],
|
|
126
|
+
risk: 'low',
|
|
127
|
+
sideEffects: ['spec_file'],
|
|
128
|
+
params: [{ name: 'slug', kind: 'positional', required: true }],
|
|
129
|
+
},
|
|
130
|
+
{
|
|
131
|
+
id: 'code.context',
|
|
132
|
+
command: 'code:context',
|
|
133
|
+
description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code).',
|
|
134
|
+
categories: ['read'],
|
|
135
|
+
permissions: ['read'],
|
|
136
|
+
risk: 'low',
|
|
137
|
+
sideEffects: [],
|
|
138
|
+
params: [
|
|
139
|
+
{ name: 'domain', kind: 'positional' },
|
|
140
|
+
{ name: 'code', kind: 'flag' },
|
|
141
|
+
],
|
|
142
|
+
},
|
|
143
|
+
{
|
|
144
|
+
id: 'memory.query',
|
|
145
|
+
command: 'query:universal',
|
|
146
|
+
description: 'Busca FTS5 na memória universal.',
|
|
147
|
+
categories: ['read', 'database'],
|
|
148
|
+
permissions: ['read'],
|
|
149
|
+
risk: 'low',
|
|
150
|
+
sideEffects: [],
|
|
151
|
+
params: [{ name: 'query', kind: 'positional', required: true }],
|
|
152
|
+
},
|
|
153
|
+
{
|
|
154
|
+
id: 'engineering.facade',
|
|
155
|
+
command: 'engineer',
|
|
156
|
+
description: 'Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado.',
|
|
157
|
+
categories: ['read', 'database', 'execution'],
|
|
158
|
+
permissions: ['read'],
|
|
159
|
+
risk: 'medium',
|
|
160
|
+
sideEffects: [],
|
|
161
|
+
params: [
|
|
162
|
+
{ name: 'objective', kind: 'positional', required: true },
|
|
163
|
+
{ name: 'ref', kind: 'flag-value', flag: '--ref' },
|
|
164
|
+
{ name: 'role', kind: 'flag-value', flag: '--role' },
|
|
165
|
+
],
|
|
166
|
+
timeoutMs: 120_000,
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
id: 'risk.assess',
|
|
170
|
+
command: 'risk:assess',
|
|
171
|
+
description: 'Score de risco 0-100 (7 fatores) sobre o diff de um ref.',
|
|
172
|
+
categories: ['read', 'database'],
|
|
173
|
+
permissions: ['read'],
|
|
174
|
+
risk: 'low',
|
|
175
|
+
sideEffects: ['risk_assessment'],
|
|
176
|
+
params: [{ name: 'ref', kind: 'positional' }],
|
|
177
|
+
},
|
|
178
|
+
{
|
|
179
|
+
id: 'orchestrate.status',
|
|
180
|
+
command: 'orchestrate:status',
|
|
181
|
+
description: 'O estado de uma corrida orchestrate: etapas, gates, vereditos.',
|
|
182
|
+
categories: ['read'],
|
|
183
|
+
permissions: ['read'],
|
|
184
|
+
risk: 'low',
|
|
185
|
+
sideEffects: [],
|
|
186
|
+
params: [{ name: 'slug', kind: 'positional', required: true }],
|
|
187
|
+
},
|
|
188
|
+
{
|
|
189
|
+
id: 'orchestrate.advance',
|
|
190
|
+
command: 'orchestrate:advance',
|
|
191
|
+
description: 'Roda o gate da etapa aberta; verde abre a próxima, vermelho trava com o parecer.',
|
|
192
|
+
categories: ['write', 'execution', 'database'],
|
|
193
|
+
permissions: ['write'],
|
|
194
|
+
risk: 'medium',
|
|
195
|
+
sideEffects: ['orchestrate_state'],
|
|
196
|
+
params: [{ name: 'slug', kind: 'positional', required: true }],
|
|
197
|
+
timeoutMs: 300_000,
|
|
198
|
+
},
|
|
199
|
+
{
|
|
200
|
+
id: 'drift.check',
|
|
201
|
+
command: 'drift:check',
|
|
202
|
+
description: 'Reindexa e sinaliza relações verified que a extração atual não reproduz mais.',
|
|
203
|
+
categories: ['read', 'database', 'execution'],
|
|
204
|
+
permissions: ['read'],
|
|
205
|
+
risk: 'medium',
|
|
206
|
+
sideEffects: ['graph_write'],
|
|
207
|
+
params: [
|
|
208
|
+
{ name: 'domain', kind: 'flag-value', flag: '--domain' },
|
|
209
|
+
{ name: 'all', kind: 'flag' }, // SPEC-030 §3 / ADR-0084: modo lote por projeto do workspace
|
|
210
|
+
],
|
|
211
|
+
timeoutMs: 120_000,
|
|
212
|
+
},
|
|
213
|
+
{
|
|
214
|
+
id: 'forja.status',
|
|
215
|
+
command: 'status',
|
|
216
|
+
description: 'Retrato único do estado: workspace, sprint, corrida, specs, runs, handoffs.',
|
|
217
|
+
categories: ['read'],
|
|
218
|
+
permissions: ['read'],
|
|
219
|
+
risk: 'low',
|
|
220
|
+
sideEffects: [],
|
|
221
|
+
params: [],
|
|
222
|
+
},
|
|
223
|
+
{
|
|
224
|
+
id: 'forja.next',
|
|
225
|
+
command: 'next',
|
|
226
|
+
description: 'A próxima ação recomendada e o comando exato para executá-la.',
|
|
227
|
+
categories: ['read'],
|
|
228
|
+
permissions: ['read'],
|
|
229
|
+
risk: 'low',
|
|
230
|
+
sideEffects: [],
|
|
231
|
+
params: [],
|
|
86
232
|
},
|
|
87
233
|
];
|
|
88
234
|
export const CLI_COMMAND_TO_CAPABILITY = Object.freeze(Object.fromEntries(CLI_CAPABILITY_SPECS.map((spec) => [spec.command, spec.id])));
|
|
@@ -138,27 +284,16 @@ export function capabilityIdForCommand(command) {
|
|
|
138
284
|
return command === 'graph:sync' ? 'graph.sync' : CLI_COMMAND_TO_CAPABILITY[command];
|
|
139
285
|
}
|
|
140
286
|
export function parseLegacyCommandInput(command, args) {
|
|
287
|
+
// `graph:sync` é o único sem comando CLI / sem params — os demais derivam de `spec.params` (SPEC-046).
|
|
141
288
|
if (command === 'graph:sync')
|
|
142
289
|
return { capabilityId: 'graph.sync', payload: {} };
|
|
143
290
|
const capabilityId = capabilityIdForCommand(command);
|
|
144
291
|
if (capabilityId === undefined)
|
|
145
292
|
throw new Error(`Command is not migrated to a capability: ${command}`);
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
return { capabilityId, payload: { symbol, ...(depth === undefined ? {} : { depth: Number(depth) }) } };
|
|
151
|
-
}
|
|
152
|
-
if (command === 'context:budget') {
|
|
153
|
-
const [target, limitTokens] = args;
|
|
154
|
-
return { capabilityId, payload: { target, ...(limitTokens === undefined ? {} : { limitTokens: Number(limitTokens) }) } };
|
|
155
|
-
}
|
|
156
|
-
if (command === 'spec:check')
|
|
157
|
-
return { capabilityId, payload: args[0] === undefined ? {} : { feature: args[0] } };
|
|
158
|
-
if (command === 'sprint:status')
|
|
159
|
-
return { capabilityId, payload: args[0] === undefined ? {} : { project: args[0] } };
|
|
160
|
-
const [phase, slug, ...contextParts] = args;
|
|
161
|
-
return { capabilityId, payload: { phase, slug, ...(contextParts.length === 0 ? {} : { context: contextParts.join(' ') }) } };
|
|
293
|
+
const spec = CLI_CAPABILITY_SPECS.find((s) => s.command === command);
|
|
294
|
+
if (spec === undefined)
|
|
295
|
+
throw new Error(`No capability spec for command: ${command}`);
|
|
296
|
+
return { capabilityId, payload: parseArgv(spec.params, args) };
|
|
162
297
|
}
|
|
163
298
|
export async function executeCliCapability(runtime, capabilityId, payload, correlationId) {
|
|
164
299
|
const definition = runtime.registry.describe(capabilityId);
|
|
@@ -206,16 +341,16 @@ function registerCliCapability(registry, runner, spec) {
|
|
|
206
341
|
requirements: [],
|
|
207
342
|
supportsAutonomy: true,
|
|
208
343
|
idempotent: true,
|
|
209
|
-
timeoutMs: 30_000,
|
|
344
|
+
timeoutMs: spec.timeoutMs ?? 30_000,
|
|
210
345
|
retry: { maxAttempts: 1, backoffMs: 0 },
|
|
211
346
|
aliases: [spec.command],
|
|
212
347
|
};
|
|
213
348
|
const registration = {
|
|
214
349
|
definition,
|
|
215
|
-
validateInput: spec.validateInput,
|
|
350
|
+
validateInput: spec.validateInput ?? makeValidator(spec.params),
|
|
216
351
|
validateOutput: validateCliPayload,
|
|
217
352
|
handler: async (input) => {
|
|
218
|
-
const args = spec.
|
|
353
|
+
const args = argvFor(spec.params, input);
|
|
219
354
|
const result = await runner(spec.command, args);
|
|
220
355
|
const capturedAt = new Date().toISOString();
|
|
221
356
|
const evidence = {
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* apps/cli/src/params.ts — mapeamento declarativo argv↔payload de um comando-capability
|
|
3
|
+
* (SPEC-046, ADR-0083).
|
|
4
|
+
*
|
|
5
|
+
* `parseArgv` e `argvFor` são inversas. Um teste de round-trip
|
|
6
|
+
* (`argvFor(params, parseArgv(params, argv)) === argv`) para todo spec é o contrato que impede
|
|
7
|
+
* as duas de divergirem — o `if/else` por comando que existia antes não tinha esse contrato.
|
|
8
|
+
*
|
|
9
|
+
* Convenção de ordem em `argvFor`: os params são emitidos na ordem em que aparecem em `params`.
|
|
10
|
+
* Um `positional` opcional só é seguro antes de outro `positional` se o anterior estiver sempre
|
|
11
|
+
* presente — na prática, opcionais ficam por último.
|
|
12
|
+
*/
|
|
13
|
+
export interface InputRecord {
|
|
14
|
+
readonly [key: string]: unknown;
|
|
15
|
+
}
|
|
16
|
+
export type CapabilityParam = {
|
|
17
|
+
readonly name: string;
|
|
18
|
+
readonly kind: 'positional';
|
|
19
|
+
readonly required?: boolean;
|
|
20
|
+
readonly parse?: 'string' | 'int';
|
|
21
|
+
} | {
|
|
22
|
+
readonly name: string;
|
|
23
|
+
readonly kind: 'flag';
|
|
24
|
+
} | {
|
|
25
|
+
readonly name: string;
|
|
26
|
+
readonly kind: 'flag-value';
|
|
27
|
+
readonly flag: string;
|
|
28
|
+
readonly required?: boolean;
|
|
29
|
+
readonly parse?: 'string' | 'int';
|
|
30
|
+
} | {
|
|
31
|
+
readonly name: string;
|
|
32
|
+
readonly kind: 'rest';
|
|
33
|
+
readonly required?: boolean;
|
|
34
|
+
};
|
|
35
|
+
/** argv → `{ [param.name]: value }`. Flags desconhecidas são ignoradas. */
|
|
36
|
+
export declare function parseArgv(params: readonly CapabilityParam[], argv: readonly string[]): InputRecord;
|
|
37
|
+
/** `{ [param.name]: value }` → argv, na ordem de `params`. */
|
|
38
|
+
export declare function argvFor(params: readonly CapabilityParam[], input: InputRecord): string[];
|
|
39
|
+
/**
|
|
40
|
+
* Validador base a partir de `params`: exige os `required` presentes e o tipo certo
|
|
41
|
+
* (`int` → número finito; resto → string). Specs com limite adicional (range, enum) embrulham
|
|
42
|
+
* esta função.
|
|
43
|
+
*/
|
|
44
|
+
export declare function makeValidator(params: readonly CapabilityParam[]): (value: unknown) => InputRecord;
|