@spec-wave/cli 1.3.0 → 1.5.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/package.json +1 -1
- package/protocol/scm.v1.json +154 -0
- package/protocol/tracker.v1.json +175 -0
- package/src/api/github-rest.mjs +109 -0
- package/src/commands/audit.mjs +3 -4
- package/src/commands/code-review.mjs +11 -6
- package/src/commands/decompose.mjs +29 -9
- package/src/commands/doctor.mjs +389 -220
- package/src/commands/generate-bug.mjs +17 -7
- package/src/commands/generate-plan.mjs +21 -13
- package/src/commands/generate-qa-plan.mjs +19 -11
- package/src/commands/generate-spec.mjs +19 -6
- package/src/commands/implement.mjs +105 -49
- package/src/commands/init.mjs +36 -6
- package/src/commands/issue.mjs +6 -2
- package/src/commands/merge.mjs +31 -18
- package/src/commands/mode.mjs +18 -10
- package/src/commands/move.mjs +3 -3
- package/src/commands/order.mjs +30 -20
- package/src/commands/preflight.mjs +10 -5
- package/src/commands/qa-lead.mjs +41 -31
- package/src/commands/qa-run.mjs +83 -55
- package/src/commands/qa.mjs +10 -6
- package/src/commands/refresh.mjs +6 -3
- package/src/commands/repair-stage.mjs +1 -1
- package/src/commands/repo.mjs +7 -7
- package/src/commands/run.mjs +7 -4
- package/src/commands/story.mjs +3 -3
- package/src/commands/task.mjs +3 -3
- package/src/commands/triage.mjs +3 -3
- package/src/commands/uninstall.mjs +14 -5
- package/src/commands/update.mjs +47 -19
- package/src/commands/validate.mjs +3 -4
- package/src/commands/workspace.mjs +2 -2
- package/src/lib/artifact-publish.mjs +4 -3
- package/src/lib/board.mjs +22 -24
- package/src/lib/config-ports.mjs +114 -0
- package/src/lib/critique.mjs +11 -1
- package/src/lib/doc-source.mjs +16 -2
- package/src/lib/doctor-capabilities.mjs +168 -0
- package/src/lib/implement-board.mjs +6 -1
- package/src/lib/implement-stream.mjs +87 -0
- package/src/lib/pr-ready.mjs +24 -11
- package/src/lib/story-graph.mjs +26 -6
- package/src/lib/tag-registry.mjs +58 -0
- package/src/lib/usage-report.mjs +15 -2
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugins/load.mjs +427 -0
- package/src/plugins/scm-github/index.mjs +71 -2
- package/src/plugins/tracker-github-projects/index.mjs +52 -10
- package/src/ports/capabilities.mjs +47 -0
- package/src/ports/index.mjs +347 -0
- package/src/ports/scm.mjs +39 -2
- package/src/ports/tracker.mjs +94 -3
- package/src/ports/types.mjs +59 -6
- package/src/setup/files.mjs +2 -2
- package/src/setup/labels.mjs +2 -2
- package/src/setup/project.mjs +2 -2
- package/src/ui/wizard.mjs +76 -1
package/package.json
CHANGED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://github.com/astratech-net-br/spec-wave-cli/blob/main/packages/spec-wave/protocol/scm.v1.json",
|
|
4
|
+
"title": "spec-wave scm plugin manifest v1",
|
|
5
|
+
"description": "Contrato do MANIFESTO que um plugin de SCM exporta como default do seu módulo ESM — quem hospeda o código, os documentos e os Pull Requests (GitHub, Azure DevOps Repos). Mesma estrutura e mesmas limitações do tracker.v1.json: valida a parte declarativa, documenta a semântica em `description`, e deixa a conformidade das funções para @spec-wave/plugin-conformance.\n\nA porta de SCM existe porque Jira não hospeda código. `merge`, `fix-pr`, `artifact-publish` e todo o ciclo `docs/features/<slug>/*.md` → Pull Request são responsabilidade DAQUI, não do tracker — e hoje estão misturados com as chamadas de board no mesmo src/api/github-rest.mjs.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["specWaveScmApi", "kind", "displayName", "capabilities"],
|
|
8
|
+
"additionalProperties": true,
|
|
9
|
+
"properties": {
|
|
10
|
+
"specWaveScmApi": {
|
|
11
|
+
"type": "integer",
|
|
12
|
+
"const": 1,
|
|
13
|
+
"description": "Versão do contrato, conferida pelo loader antes da primeira chamada. Ver a justificativa em tracker.v1.json."
|
|
14
|
+
},
|
|
15
|
+
"kind": {
|
|
16
|
+
"type": "string",
|
|
17
|
+
"pattern": "^[a-z][a-z0-9-]*$",
|
|
18
|
+
"description": "Identificador estável gravado em `scm.kind` do .spec-wave.json e chave da resolução por convenção (`@spec-wave/scm-<kind>`). Valores desta fase: `github`, `azure-devops`."
|
|
19
|
+
},
|
|
20
|
+
"displayName": { "type": "string", "description": "Rótulo no `p.select` do init e no doctor." },
|
|
21
|
+
"packageName": { "type": "string", "description": "Nome npm, quando fora da convenção `@spec-wave/scm-<kind>`." },
|
|
22
|
+
"capabilities": {
|
|
23
|
+
"type": "object",
|
|
24
|
+
"description": "O que este SCM sabe fazer. O core degrada a partir daqui em vez de descobrir na falha.",
|
|
25
|
+
"required": ["fileWrites", "pullRequests", "variables", "automation"],
|
|
26
|
+
"additionalProperties": true,
|
|
27
|
+
"properties": {
|
|
28
|
+
"fileWrites": {
|
|
29
|
+
"type": "object",
|
|
30
|
+
"required": ["mode"],
|
|
31
|
+
"description": "Como um documento gerado chega ao repositório. Importa porque src/lib/artifact-publish.mjs publica spec.md, plan.md, bug.md, decomposition.md e qa-plan.md em branch própria (`spec-wave/<key>-<suffix>`) e conta com atomicidade.",
|
|
32
|
+
"properties": {
|
|
33
|
+
"mode": {
|
|
34
|
+
"type": "string",
|
|
35
|
+
"enum": ["tree-commit-ref", "push"],
|
|
36
|
+
"description": "`tree-commit-ref` = a Git Data API do GitHub em três passos (createTree com base_tree → createCommit → create/updateRef), que é o que commitFilesToBranch faz hoje. `push` = uma única chamada com refUpdates + commits[].changes[] (`POST .../pushes` do Azure DevOps). O `push` é MAIS simples e igualmente atômico; o contrato expõe a diferença porque a recuperação de erro é outra — no modo `push` uma rejeição de ref é uma resposta só, no `tree-commit-ref` pode ter deixado tree e commit órfãos."
|
|
37
|
+
},
|
|
38
|
+
"atomicMultiFile": {
|
|
39
|
+
"type": "boolean",
|
|
40
|
+
"description": "Vários arquivos num commit só. `false` obrigaria artifact-publish a serializar, e um dependency-map.json ficaria num commit diferente do decomposition.md que o gerou."
|
|
41
|
+
},
|
|
42
|
+
"concurrentPublishRetry": {
|
|
43
|
+
"type": "boolean",
|
|
44
|
+
"description": "O plugin classifica rejeição de escrita entre disputa transitória (perdeu a corrida: non-fast-forward, cannot lock ref) e recusa deliberada (branch protegida, auth). O core PRECISA dessa distinção: src/lib/git-retry.mjs só repete o primeiro caso, porque repetir o segundo multiplica um erro determinístico, e não repetir o primeiro joga fora um documento cuja chamada de modelo já foi paga."
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
},
|
|
48
|
+
"pullRequests": {
|
|
49
|
+
"type": "object",
|
|
50
|
+
"required": ["draft", "retarget", "mergeStrategies", "reviewModel"],
|
|
51
|
+
"description": "O PR é a unidade de entrega de todo documento gerado E de toda Story implementada (em pilha, na ordem topológica de `merge`).",
|
|
52
|
+
"properties": {
|
|
53
|
+
"draft": {
|
|
54
|
+
"type": "boolean",
|
|
55
|
+
"description": "Suporte a PR rascunho e à promoção para revisão. No GitHub a promoção é GraphQL-only (markPullRequestReadyForReview; a REST ignora); no Azure DevOps é `PATCH {isDraft: false}`. É o que src/lib/pr-ready.mjs usa para abrir a revisão de uma pilha só quando ela está completa."
|
|
56
|
+
},
|
|
57
|
+
"retarget": {
|
|
58
|
+
"type": "boolean",
|
|
59
|
+
"description": "Trocar a branch de destino de um PR aberto (`updatePRBase`; `targetRefName` no Azure DevOps). Sem isto NÃO HÁ PR empilhado: é assim que `merge` reaponta o PR dependente para a base depois de integrar o anterior, e é exatamente o passo que, feito à mão com --delete-branch, fecha o PR seguinte."
|
|
60
|
+
},
|
|
61
|
+
"mergeStrategies": {
|
|
62
|
+
"type": "array",
|
|
63
|
+
"items": { "type": "string", "enum": ["merge", "squash", "rebase"] },
|
|
64
|
+
"description": "Estratégias aceitas. Hoje o core pede `merge` fixo (mergePR method:'merge'). No Azure DevOps 'mergear' é completar o PR (`PATCH status: completed` + `completionOptions.mergeStrategy`), o que muda o formato do erro quando a política do repositório exige build verde."
|
|
65
|
+
},
|
|
66
|
+
"reviewModel": {
|
|
67
|
+
"type": "string",
|
|
68
|
+
"enum": ["decision", "vote"],
|
|
69
|
+
"description": "`decision` = um veredito agregado por revisor com enum fechado (APPROVED / CHANGES_REQUESTED / REVIEW_REQUIRED) — o plugin já devolve o enum do core. `vote` = voto numérico crú por revisor (10 aprovado, 5 aprovado com sugestões, 0 sem voto, −5 aguardando autor, −10 rejeitado), que é o modelo do Azure DevOps: `listPullRequestReviews` devolve `{reviewer, vote: number}[]` sem normalizar, e é a porta de SCM no CORE — não o plugin — que aplica a regra fixa do RFC-006 §7.2 (qualquer `−10` é `changes_requested`; `≥10` sem `−10` é `approved`; o resto é `pending`) para produzir `PullRequestRef.reviewDecision`. Normalizar no plugin faria dois plugins `vote` normalizarem diferente."
|
|
70
|
+
},
|
|
71
|
+
"referenceSearch": {
|
|
72
|
+
"type": "boolean",
|
|
73
|
+
"description": "O plugin consegue achar os PRs que citam uma chave de work item (`findPullRequestsReferencing`). É a única forma de `merge`, `code-review`, `qa` e `pr-ready` ligarem PR a item quando o vínculo nativo não está disponível — isto é, sempre que tracker e SCM são de fornecedores diferentes, caso em que a operação `closingKeyword(ref)` devolve `null` (ver `operations`)."
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
"variables": {
|
|
78
|
+
"type": "string",
|
|
79
|
+
"enum": ["repo", "none"],
|
|
80
|
+
"description": "`repo` = existe variável no escopo do repositório legível pela automação (Actions variables: getRepoVariable/setRepoVariable, onde vive SPEC_WAVE_EXECUTION e que todos os 9 workflows consultam em `vars.SPEC_WAVE_EXECUTION != 'local'`). `none` = não existe equivalente no escopo do repositório (no Azure DevOps as variáveis vivem em variable group do Pipelines, que é escopo de projeto e outro modelo de permissão). Em `none` o kill switch de execução passa a morar SÓ no .spec-wave.json, e o `doctor` perde a checagem de divergência entre config e variável remota — que é justamente a checagem que hoje pega 'o usuário acha que desligou os Actions e está pagando minutos'. A perda tem que estar documentada, não escondida."
|
|
81
|
+
},
|
|
82
|
+
"automation": {
|
|
83
|
+
"type": "string",
|
|
84
|
+
"enum": ["github-actions", "azure-pipelines", "none"],
|
|
85
|
+
"description": "Qual motor de automação o `init` provisiona e o `doctor`/a UI consultam. `github-actions` = os 9 templates de src/templates/workflows/ (gatilho por label da issue). `azure-pipelines` = YAML de pipeline, SEM gatilho por label — o disparo vem de fora (Jira Automation chamando a API de runs). `none` = só `execution.mode: local`, com `spec-wave run <item>` como único gatilho. Os templates atuais NÃO são portáveis: o desenho de `concurrency` (`spec-wave-item-<issue>` para o que publica, `spec-wave-noop-<run_id>` para o que vai ser pulado) precisa ser reexpresso por motor."
|
|
86
|
+
},
|
|
87
|
+
"remoteDispatch": {
|
|
88
|
+
"type": "object",
|
|
89
|
+
"description": "Como um agente externo (tipicamente uma regra de Automation do Jira via 'Send web request') pede a execução de um passo do fluxo. É a Fase 2 do disparo; na Fase 1 o tracker não-GitHub força `execution.mode: local`. `mechanism` é a única fonte de verdade — não existe um `supported` paralelo, pelo mesmo motivo de `automation`/`variables`: um valor seria `true`+`none` sempre que o outro campo já disser tudo.",
|
|
90
|
+
"required": ["mechanism"],
|
|
91
|
+
"properties": {
|
|
92
|
+
"mechanism": {
|
|
93
|
+
"type": "string",
|
|
94
|
+
"enum": ["repository-dispatch", "pipeline-run", "none"],
|
|
95
|
+
"description": "`repository-dispatch` = `POST /repos/{o}/{r}/dispatches` com client_payload. `pipeline-run` = `POST .../pipelines/{id}/runs` com template parameters. `none` = disparo remoto não suportado. Em `repository-dispatch`/`pipeline-run` o payload é o mesmo par `{action, key}`, e a serialização por item passa a ser chaveada por `key` em vez de por número de issue."
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
},
|
|
99
|
+
"identity": {
|
|
100
|
+
"type": "object",
|
|
101
|
+
"description": "Forma do endereço do repositório, para que o core não precise saber o formato de cada SCM ao montar `scm.config` e ao exibir links.",
|
|
102
|
+
"properties": {
|
|
103
|
+
"configKeys": {
|
|
104
|
+
"type": "array",
|
|
105
|
+
"items": { "type": "string" },
|
|
106
|
+
"description": "Chaves que compõem o endereço. `['owner','repo']` no GitHub; `['org','project','repo']` no Azure DevOps — o nível extra de `project` é o que quebra o par owner/repo que src/lib/project-root.mjs:90 resolveRepoContext() devolve hoje."
|
|
107
|
+
},
|
|
108
|
+
"branchNameConstraints": {
|
|
109
|
+
"type": "object",
|
|
110
|
+
"description": "Limites do nome de branch. O core gera `spec-wave/<key>-<suffix>` (ARTIFACT_BRANCH_PREFIX em src/lib/artifact-pr.mjs) e precisa saber se a chave do tracker cabe ali sem transformação.",
|
|
111
|
+
"properties": {
|
|
112
|
+
"maxLength": { "type": "integer", "minimum": 1 },
|
|
113
|
+
"allowedPattern": { "type": "string" }
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
},
|
|
120
|
+
"configSchema": {
|
|
121
|
+
"type": "object",
|
|
122
|
+
"description": "JSON Schema (draft-07) do bloco `scm.config` do .spec-wave.json. `{owner, repo}` no GitHub; `{org, project, repo}` no Azure DevOps. Validado pelo doctor e na entrada de todo comando, para que config incompleta falhe antes de gastar rede ou modelo."
|
|
123
|
+
},
|
|
124
|
+
"credentials": {
|
|
125
|
+
"type": "array",
|
|
126
|
+
"description": "Credenciais consumidas pelo plugin, no molde do campo `secret` de AI_PROVIDERS. O valor nunca passa pelo .spec-wave.json.",
|
|
127
|
+
"items": {
|
|
128
|
+
"type": "object",
|
|
129
|
+
"required": ["env", "label"],
|
|
130
|
+
"properties": {
|
|
131
|
+
"env": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
|
|
132
|
+
"label": { "type": "string" },
|
|
133
|
+
"hint": { "type": "string" },
|
|
134
|
+
"optional": { "type": "boolean" }
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
},
|
|
138
|
+
"operations": {
|
|
139
|
+
"type": "array",
|
|
140
|
+
"description": "⚠️ OPCIONAL E NÃO NORMATIVA desde a Fase 2 (bloco H), pela mesma razão do tracker: o loader NÃO lê este array — as funções da porta são a declaração, e uma lista paralela é uma segunda fonte que pode afirmar o que a chamada não encontra. Quem verifica é `scmRequiredOperations` + `checkScmPort`, sobre as funções reais. O campo fica como contrato LEGÍVEL (e `test/ports-conditional-parity.test.mjs` compara a prosa das CONDICIONAIS com as tabelas de runtime e com os marcadores `[op]` do JSDoc).\n\nOBRIGATÓRIAS SEMPRE: setup, verify, defaultBranch, isInitialized, readFile, writeFiles, deleteFile, branchHead, compare, deleteBranch, findOpenPullRequest, ensurePullRequest, getPullRequest, listPullRequestCommitMessages, listPullRequestReviews, listOpenPullRequests, mergePullRequest, closingKeyword, fileUrl, listAutomationRuns.\n\n`closingKeyword({ref, trackerKind, prLink, hubLink})` devolve a CLÁUSULA INTEIRA (`Closes #123`) quando SCM e tracker são o mesmo fornecedor, e `null` em qualquer outro caso — a decisão não é uma capability estática porque depende do PAR tracker+SCM, não só do SCM; ver `pullRequests.referenceSearch`. ⚠️ Assinatura corrigida na v1.1: `(ref, trackerKind)` não bastava. Com a RFC-005 (um hub, N repos de código) o PR de uma Story vive num repo e a issue vive no hub, e `closesRef()` (src/commands/implement.mjs:189) já emite hoje a forma QUALIFICADA `owner/repo#n`. Sem `prLink` e `hubLink` a operação não sabe se pode usar a forma curta — e a forma curta num repo de código fecha a issue errada, ou nenhuma.\n\n`fileUrl({link, ref, pathRel})` devolve a URL navegável de um arquivo numa ref. ⚠️ Acrescentada na v1.1: estava faltando, e sem ela `src/lib/repo-links.mjs` continua cravando `https://github.com/<owner>/<repo>/blob/<ref>/<path>` — string que entra em todo comentário de issue e corpo de PR que o fluxo gera. É a operação mais fácil de esquecer justamente porque a função que a implementa hoje é pura e parece neutra.\n\n`listAutomationRuns` devolve `[]` quando `automation: 'none'`, nunca lança. Nota: a CLI não lista runs hoje — quem o faz é a spec-wave-ui (`server/src/services/specReviewService.ts`), que portanto é a implementação de referência desta operação.\n\nCONDICIONAIS: markReadyForReview (pullRequests.draft); setPullRequestBase (pullRequests.retarget); findPullRequestsReferencing (pullRequests.referenceSearch); getVariable/setVariable/deleteVariable (variables: repo); installAutomation (automation != none); dispatch (remoteDispatch.mechanism != none).",
|
|
141
|
+
"items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9]*$" },
|
|
142
|
+
"minItems": 1,
|
|
143
|
+
"uniqueItems": true
|
|
144
|
+
},
|
|
145
|
+
"automationTemplates": {
|
|
146
|
+
"type": "string",
|
|
147
|
+
"description": "Caminho, relativo à raiz do pacote, do diretório com os templates de automação deste SCM — o que o `init` publica e o `update` mantém. No plugin do GitHub são os 9 arquivos hoje em src/templates/workflows/; num plugin de Azure DevOps é o YAML de pipeline equivalente. Fica no PLUGIN e não no core porque o formato é do motor, não do fluxo."
|
|
148
|
+
},
|
|
149
|
+
"skillFragment": {
|
|
150
|
+
"type": "string",
|
|
151
|
+
"description": "Caminho, relativo à raiz do pacote, de um markdown com as instruções específicas deste SCM para o agente, injetado nas skills pelo `install-skill`. É onde vive o que hoje está cravado em `fix-pr/SKILL.md` (10 chamadas cruas a `gh pr`/`gh api`) e nas instruções de PR empilhado de `implement`/`merge`."
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://github.com/astratech-net-br/spec-wave-cli/blob/main/packages/spec-wave/protocol/tracker.v1.json",
|
|
4
|
+
"title": "spec-wave tracker plugin manifest v1",
|
|
5
|
+
"description": "Contrato do MANIFESTO que um plugin de tracker exporta como default do seu módulo ESM — o rastreador de work items (GitHub Projects, Jira). Descreve a parte DECLARATIVA (versão da API, kind, capabilities, schema de config, nomes das operações); a semântica de cada operação vive no campo `description` de `operations` e na RFC-006. Um JSON Schema não valida assinatura de função, então o que este arquivo garante é que o core possa (a) recusar um plugin de API incompatível antes da primeira chamada, (b) saber o que degradar, e (c) validar o bloco `tracker` do .spec-wave.json contra `configSchema`. A conformidade das funções é verificada em runtime por @spec-wave/plugin-conformance, não aqui.\n\n⚠️ `tracker` NÃO é `provider`. Em todo o resto do projeto (config.mjs AI_PROVIDERS, src/agent/, apps/docs/ia/providers.md) `provider` e `backend` significam provider de IA. Reusar essas palavras aqui colidiria com a documentação existente.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["specWaveTrackerApi", "kind", "displayName", "capabilities"],
|
|
8
|
+
"additionalProperties": true,
|
|
9
|
+
"properties": {
|
|
10
|
+
"specWaveTrackerApi": {
|
|
11
|
+
"type": "integer",
|
|
12
|
+
"const": 1,
|
|
13
|
+
"description": "Versão do contrato. O loader do core compara ANTES de chamar qualquer operação e falha com mensagem acionável quando divergir — um plugin publicado independentemente vai ficar para trás do core, e descobrir isso na primeira chamada de rede é o pior momento possível."
|
|
14
|
+
},
|
|
15
|
+
"kind": {
|
|
16
|
+
"type": "string",
|
|
17
|
+
"pattern": "^[a-z][a-z0-9-]*$",
|
|
18
|
+
"description": "Identificador estável gravado em `tracker.kind` do .spec-wave.json. É a chave da resolução por convenção do loader (`@spec-wave/tracker-<kind>`), por isso é kebab-case e não muda entre versões do plugin. Valores desta fase: `github-projects`, `jira`."
|
|
19
|
+
},
|
|
20
|
+
"displayName": {
|
|
21
|
+
"type": "string",
|
|
22
|
+
"description": "Rótulo exibido no `p.select` do `spec-wave init` e no `doctor`. Mesmo papel do campo `label` de AI_PROVIDERS."
|
|
23
|
+
},
|
|
24
|
+
"packageName": {
|
|
25
|
+
"type": "string",
|
|
26
|
+
"description": "Nome npm do plugin, quando ele não segue a convenção `@spec-wave/tracker-<kind>`. Gravado em `tracker.package` para que a resolução seja explícita e não dependa de adivinhação."
|
|
27
|
+
},
|
|
28
|
+
"capabilities": {
|
|
29
|
+
"type": "object",
|
|
30
|
+
"description": "O que este tracker sabe fazer. O core LÊ isto para degradar em vez de falhar: sem `dependencies` nativas ele usa a forma textual `Depende de: #N` que src/lib/dependencies.mjs já aceita; sem `milestones` os comandos de trilha (preflight, audit, qa-lead) se recusam com mensagem clara em vez de estourar. Toda capability ausente é tratada como `false`/mínima — um plugin novo nunca ganha poder por omissão.",
|
|
31
|
+
"required": ["stages", "progress", "fields", "boardProvisioning", "commentFormat", "identity"],
|
|
32
|
+
"additionalProperties": true,
|
|
33
|
+
"properties": {
|
|
34
|
+
"hierarchy": {
|
|
35
|
+
"type": "string",
|
|
36
|
+
"enum": ["native", "none"],
|
|
37
|
+
"description": "`native` = existe relação pai/filho consultável (sub-issues do GitHub, campo `parent` do Jira). `none` faz `decompose --apply` registrar a filiação apenas no corpo do item e no decomposition.md, e `implement`/`order` passam a depender do dependency-map.json em vez da árvore remota."
|
|
38
|
+
},
|
|
39
|
+
"dependencies": {
|
|
40
|
+
"type": "string",
|
|
41
|
+
"enum": ["native", "textual"],
|
|
42
|
+
"description": "`native` = há link tipado de bloqueio (API de dependencies do GitHub, issueLink `Blocks` do Jira). `textual` força o fallback `Depende de: #N` no corpo. Não é degradação grave: src/lib/story-graph.mjs já faz a UNIÃO das duas representações, e a textual é a que sobrevive a qualquer tracker."
|
|
43
|
+
},
|
|
44
|
+
"milestones": {
|
|
45
|
+
"type": "string",
|
|
46
|
+
"enum": ["native", "none"],
|
|
47
|
+
"description": "Agrupamento por entrega. GitHub usa milestones; Jira usa Versions (`fixVersions`) — e NÃO Sprints, porque é `listIssuesByMilestone` + a tela de Planning que consomem isso, ambos com semântica de release, não de iteração."
|
|
48
|
+
},
|
|
49
|
+
"stages": {
|
|
50
|
+
"type": "object",
|
|
51
|
+
"required": ["mode"],
|
|
52
|
+
"description": "Como a Etapa (a coluna do kanban) é escrita. É a diferença mais funda entre GitHub e Jira e a razão de esta capability existir.",
|
|
53
|
+
"properties": {
|
|
54
|
+
"mode": {
|
|
55
|
+
"type": "string",
|
|
56
|
+
"enum": ["set", "transition"],
|
|
57
|
+
"description": "`set` = escrita direta de um valor (single-select do Projects v2). `transition` = NÃO existe 'set status': só se caminha pelo workflow (`GET /rest/api/3/issue/{key}/transitions` → `POST`), e só as transições permitidas aparecem. Em `transition` o plugin é responsável por achar o caminho (inclusive multi-salto) e por falhar de forma legível quando não houver nenhum. O invariante 'a Etapa só avança' continua sendo do CORE (shouldAdvanceStage em src/lib/board.mjs), sobre as etapas canônicas de STATUS_OPTIONS — o plugin nunca decide direção."
|
|
58
|
+
},
|
|
59
|
+
"multiHop": {
|
|
60
|
+
"type": "boolean",
|
|
61
|
+
"description": "Só faz sentido com `mode: transition`. `true` = o plugin tenta uma sequência de transições quando não há salto direto. `false` = uma transição ou erro. Existe porque multi-salto atravessa statuses intermediários e dispara as automações do Jira nesses statuses; quem liga isso precisa saber que efeito colateral está aceitando."
|
|
62
|
+
},
|
|
63
|
+
"reopenable": {
|
|
64
|
+
"type": "boolean",
|
|
65
|
+
"description": "O tracker permite voltar a uma etapa anterior. Usado só por `repair-stage` (a única escapatória ao guard, hoje setItemStage). Em `transition` isso pode ser impossível mesmo com permissão de admin."
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
"progress": {
|
|
70
|
+
"type": "string",
|
|
71
|
+
"enum": ["native", "none"],
|
|
72
|
+
"description": "PROGRESSO dentro da etapa atual — Todo / In Progress / Done (`PROGRESS_*` em config.mjs). NÃO é `stage` e NÃO é open/closed (isso é `closeSemantics`): é uma terceira dimensão, e ela é decisão do CORE. `task start` marca In Progress SEM mexer na Etapa, porque a Task continua em 🚧 Desenvolvimento — e é isso que distingue \"a Story tem trabalho em curso\" de \"a Story mudou de coluna\". No GitHub é o campo nativo \"Status\" do Projects v2, escrito por seis call sites (advanceToStage, setItemStage, setItemStatus e os comandos task/story/qa-run).\n\n`none` = o tracker não tem essa dimensão, e o core PULA a escrita em vez de emulá-la. É o caso do Jira, onde o status É a etapa: emular com um campo custom criaria duas fontes de verdade para a mesma coluna.\n\n⚠️ Esta capability foi acrescentada na revisão da RFC (v1.1) porque o manifesto original NÃO CONSEGUIA DESCREVER O GITHUB: `fields` é lista fechada e a descrição abaixo negava a existência de um `status` separado de `stage`. Um contrato que não descreve a única implementação existente reprovaria o plugin default no kit de conformidade."
|
|
73
|
+
},
|
|
74
|
+
"fields": {
|
|
75
|
+
"type": "object",
|
|
76
|
+
"description": "Quais dos campos do RFC-001 este tracker consegue persistir, e como. `native` = campo próprio do tracker; `mapped` = exige uma entrada em `tracker.fieldMap` descoberta no init (caso do Story Points no Jira, que é `customfield_1XXXX` variável por site); `tag` = emulado por label; `none` = não persiste, e o core para de oferecer o campo em vez de escrever em lugar nenhum. Lista FECHADA de propósito (`additionalProperties: false`): são os únicos campos que o core lê hoje (`CUSTOM_FIELDS` em config.mjs, mais `stage`, que é a Etapa). Não existe campo `status` separado de `stage` aqui — open/closed é `capabilities.closeSemantics`, e o progresso Todo/In Progress/Done é `capabilities.progress`. Os três são dimensões distintas e nenhum deles é um campo desta lista.\n\n⚠️ `release` NÃO é o milestone, e a distinção é normativa. `release` é um campo ANOTADO no item, texto livre, sem entidade própria — não se lista, não se cria, não tem data-alvo (no GitHub é um campo TEXT do Projects v2; na spec-wave-ui é uma label). O milestone é uma ENTIDADE do tracker, com chave, título e `dueOn`, que se lista por `listMilestones` e pela qual se filtra por `listWorkItemsByMilestone`, e que se escreve por `setMilestone` — nunca por `setField`. São eixos independentes: um item pode ter os dois, um ou nenhum. Sem esta frase um plugin pode representar `release` COMO o milestone de boa-fé, e aí `setField({field: 'release'})` e `setMilestone()` viram dois caminhos de escrita para o mesmo valor sem nada que os mantenha coerentes; um plugin que só tenha um dos dois declara o outro ausente em vez de fundi-los. O sintoma de confundir é mudo: a escrita tem SUCESSO e os filtros por milestone seguem sem enxergar o item.",
|
|
77
|
+
"additionalProperties": false,
|
|
78
|
+
"properties": {
|
|
79
|
+
"stage": { "$ref": "#/definitions/fieldSupport" },
|
|
80
|
+
"workItemType": { "$ref": "#/definitions/fieldSupport" },
|
|
81
|
+
"priority": { "$ref": "#/definitions/fieldSupport" },
|
|
82
|
+
"storyPoints": { "$ref": "#/definitions/fieldSupport" },
|
|
83
|
+
"area": { "$ref": "#/definitions/fieldSupport" },
|
|
84
|
+
"release": { "$ref": "#/definitions/fieldSupport" }
|
|
85
|
+
}
|
|
86
|
+
},
|
|
87
|
+
"workItemTypes": {
|
|
88
|
+
"type": "string",
|
|
89
|
+
"enum": ["create", "map-only"],
|
|
90
|
+
"description": "`create` = o init cria as 8 opções de WORK_ITEM_TYPES. `map-only` = os tipos são entidades do tracker que a API de uso não cria (issue types do Jira): o init exige `tracker.typeMap`. Relevante porque `Feature`, `Initiative`, `Spike` e `RFC` não existem num Jira padrão — Epic é o nível mais alto sem Advanced Roadmaps."
|
|
91
|
+
},
|
|
92
|
+
"boardProvisioning": {
|
|
93
|
+
"type": "string",
|
|
94
|
+
"enum": ["create", "map-only"],
|
|
95
|
+
"description": "`create` = o init PROVISIONA o board (é o que setup/project.mjs faz hoje: cria o Project, o campo Etapa com as 12 opções de STATUS_OPTIONS e os campos custom). `map-only` = as etapas são entidades administrativas que a API de uso não cria (statuses de workflow do Jira): o init MAPEIA as 12 etapas canônicas para o que já existe e grava `tracker.stageMap`. Confundir os dois modos é o erro que transforma o init num pedido de permissão de admin que o usuário não tem."
|
|
96
|
+
},
|
|
97
|
+
"commentFormat": {
|
|
98
|
+
"type": "string",
|
|
99
|
+
"enum": ["markdown", "adf", "wiki"],
|
|
100
|
+
"description": "Formato aceito no corpo de comentário e de work item. O spec-wave escreve MARKDOWN em todo lugar (commentOnIssue, lib/usage-report.mjs, renderOrderComment, o corpo das Stories do decompose). `adf` (Atlassian Document Format, exigido pela API v3 do Jira) obriga o plugin a converter na ida E na volta — a volta importa porque a UI renderiza esses comentários com react-markdown."
|
|
101
|
+
},
|
|
102
|
+
"commentMarkers": {
|
|
103
|
+
"type": "boolean",
|
|
104
|
+
"description": "O tracker preserva, byte a byte, um comentário HTML (`<!-- spec-wave:… -->`) embutido num corpo de comentário ou de work item. NÃO é cosmético: sete módulos usam esses marcadores como ESTADO legível por máquina — USAGE_MARKER (src/lib/usage-report.mjs:15, acha e atualiza o próprio comentário de custo), CRITIQUE_MARKER_RE e DECISIONS_MARKER_RE (src/lib/critique.mjs:444,478), QA_REPORT_MARKER_RE e QA_ORIGIN_MARKER_RE (src/lib/qa-report.mjs:127,133, e é o que dá idempotência à criação de Bug por cenário em src/lib/qa-lead.mjs:420) e o marcador de trilha de QA na descrição do milestone (src/lib/qa-lead.mjs:512). Em ADF não existe comentário HTML: `false` obriga o plugin a oferecer um armazenamento de propriedade alternativo (ver `operations.getItemProperty`/`setItemProperty`), e um plugin que devolve `false` sem implementar esse par reprova na conformidade."
|
|
105
|
+
},
|
|
106
|
+
"tagConstraints": {
|
|
107
|
+
"type": "object",
|
|
108
|
+
"description": "Limites do vocabulário de tags. Existe porque as ~25 labels de TRIGGER_LABELS e as derivadas (`spec-wave:model:<alias>`, `spec-wave:dev-agent-<fila>`) são o vocabulário de controle do fluxo: se o tracker não aceitar a grafia, o fluxo não tem gatilho. O Jira aceita `spec-wave:spec` (só proíbe espaço); um tracker que proibisse `:` exigiria um separador alternativo declarado aqui.",
|
|
109
|
+
"properties": {
|
|
110
|
+
"maxLength": { "type": "integer", "minimum": 1 },
|
|
111
|
+
"allowedPattern":{ "type": "string", "description": "Regex que toda tag precisa casar." },
|
|
112
|
+
"colors": { "type": "boolean", "description": "O tracker guarda cor por tag. `false` faz o core ignorar o campo `color` de ALL_LABELS em vez de tentar escrevê-lo." },
|
|
113
|
+
"descriptions": { "type": "boolean", "description": "O tracker guarda descrição por tag (o `description` de ALL_LABELS, que é o que explica cada gatilho para quem olha o board)." }
|
|
114
|
+
}
|
|
115
|
+
},
|
|
116
|
+
"closeSemantics": {
|
|
117
|
+
"type": "string",
|
|
118
|
+
"enum": ["state", "transition-and-resolution"],
|
|
119
|
+
"description": "`state` = existe open/closed (setIssueState do GitHub). `transition-and-resolution` = não existe: fechar é transicionar para um status da categoria Done e preencher resolution (Jira). O `triage` é o único consumidor (rejeitar/duplicar fecha o Bug), mas ele fecha assumindo hoje que 'closed' é um estado."
|
|
120
|
+
},
|
|
121
|
+
"reopen": {
|
|
122
|
+
"type": "string",
|
|
123
|
+
"enum": ["native", "none"],
|
|
124
|
+
"description": "`native` = o tracker sabe REABRIR um item fechado (`reopenWorkItem`). Ausente vale `none`, e o core recusa com mensagem em vez de tentar e estourar no meio do comando.\n\nCapability própria, e não um corolário de `closeSemantics`, por uma assimetria real: todo valor de `closeSemantics` implica que FECHAR é possível, mas SAIR de Done depende de existir a transição no workflow do site — no Jira isso é configuração de quem instalou, não característica do fornecedor.\n\nA operação não leva argumento de destino, e isso só é possível porque `state`, `stage` e `progress` são três dimensões separadas aqui: reabrir não decide para qual Etapa o item volta, porque a Etapa não muda. Num tracker `transition-and-resolution` o plugin transiciona para o status não-Done correspondente à Etapa atual e limpa a resolution.\n\n⚠️ Acrescentada depois da Fase 1 porque o contrato já sabia LER um item reaberto — `WorkItem.stateReason` tem `reopened` no enum — e não tinha como produzir um. A rota existia (`setIssueState` aceita o estado) e só era chamada com 'closed', pelo único consumidor que havia. Faltava a operação, não o conceito."
|
|
125
|
+
},
|
|
126
|
+
"identity": {
|
|
127
|
+
"type": "object",
|
|
128
|
+
"required": ["keyPattern"],
|
|
129
|
+
"description": "Forma da chave pública do work item. Necessário porque a `key` vai para nome de branch (`spec-wave/<key>-<suffix>`), para trailer de commit e para o corpo do PR — o core precisa saber sanitizar sem inventar regra por tracker.",
|
|
130
|
+
"properties": {
|
|
131
|
+
"keyPattern": { "type": "string", "description": "Regex da chave, ANCORADA e sem zero à esquerda: `^[1-9][0-9]*$` no GitHub (issue 0 não existe e `007` não endereça a 7), `^[A-Z][A-Z0-9_]*-[0-9]+$` no Jira.\n\n⚠️ NÃO pode admitir `#`. O que a PORTA devolve nunca contém `#` — invariante do contrato, cobrado na CARGA por `checkKeyPattern` (exportada de src/ports/tracker.mjs e chamada por checkTrackerPort), e a mesma função que o kit de conformidade da Fase 2 usa, para não existirem duas cópias da regra. O escopo é a porta: `refKey()` do core normaliza sem validar, e endurecê-la seria mudar a função mais carregada do core por causa de entrada que nenhum tracker produz. Em três lugares `#` é sigilo ou separador em texto que o fluxo gera e reanalisa: `refKey()` descarta um `#` inicial (ali ele é o prefixo da referência, não parte da chave), `Depende de: #4, #5` é escrito no corpo das Stories e lido de volta, e `owner/repo#n` sai no `closingKeyword` em multi-repo. Uma chave com `#` tornaria `#A#B` indistinguível de duas referências, e o estrago apareceria como dependência que some — não como erro. É o irmão de `branchSafe`: aquele cobre o destino NOME DE BRANCH, este cobre o destino REFERÊNCIA TEXTUAL. Sem par `refSafe`/`refToken` porque nenhum fornecedor conhecido precisa — proibir sai mais barato que parametrizar." },
|
|
132
|
+
"keyIsNumeric": { "type": "boolean", "description": "`true` só no GitHub. É o que autoriza o core a manter a compatibilidade com `#N` — em `false`, toda sintaxe `#N` (Closes, Depende de) tem que passar pelo plugin." },
|
|
133
|
+
"branchSafe": { "type": "boolean", "description": "A chave pode ir crua para nome de branch. `false` obriga o plugin a expor um `branchToken(key)`." }
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
},
|
|
138
|
+
"configSchema": {
|
|
139
|
+
"type": "object",
|
|
140
|
+
"description": "JSON Schema (draft-07) do bloco `tracker.config` do .spec-wave.json — o que este tracker precisa saber para se conectar. `{site, projectKey}` no Jira, `{projectId, projectNumber, fields}` no GitHub Projects. O core valida o config contra isto no `doctor` e no início de todo comando, para que uma configuração incompleta falhe antes de gastar chamada de rede ou token de modelo."
|
|
141
|
+
},
|
|
142
|
+
"credentials": {
|
|
143
|
+
"type": "array",
|
|
144
|
+
"description": "Credenciais que o plugin consome, no molde do campo `secret` de AI_PROVIDERS. O core usa isto para: pedir no init, checar presença no doctor, e listar no `install`/nos templates de automação. O VALOR nunca passa pelo .spec-wave.json.",
|
|
145
|
+
"items": {
|
|
146
|
+
"type": "object",
|
|
147
|
+
"required": ["env", "label"],
|
|
148
|
+
"properties": {
|
|
149
|
+
"env": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "Nome da variável de ambiente / secret." },
|
|
150
|
+
"label": { "type": "string", "description": "Como pedir ao usuário." },
|
|
151
|
+
"hint": { "type": "string", "description": "Como obter o valor (ex.: 'crie um API token em id.atlassian.com/manage-profile/security/api-tokens')." },
|
|
152
|
+
"optional": { "type": "boolean" }
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
},
|
|
156
|
+
"operations": {
|
|
157
|
+
"type": "array",
|
|
158
|
+
"description": "⚠️ OPCIONAL E NÃO NORMATIVA desde a Fase 2 (bloco H) — o que vale é a prosa abaixo, não o array.\n\nO rascunho deste manifesto exigia esta lista em `required` e dizia que o loader a compararia com as capabilities. **O loader NÃO a lê**, e a decisão é do bloco A: as FUNÇÕES da porta são a declaração. Uma lista paralela é uma segunda fonte cujo modo de falha é o pior que existe — o manifesto afirma que a operação existe, e a chamada encontra `undefined`, em produção, depois de o loader ter dito 'conforme'. O que o core faz em vez disso é verificar as funções REAIS contra as capabilities declaradas (`trackerRequiredOperations` + `checkTrackerPort`, em `src/ports/tracker.mjs`), que é a mesma garantia sem a segunda fonte.\n\nO campo fica porque esta prosa é o CONTRATO LEGÍVEL de quem escreve um plugin, e porque `test/ports-conditional-parity.test.mjs` a compara com as tabelas de runtime — as condicionais abaixo têm de bater com `TRACKER_CONDITIONAL_OPERATIONS` e com os marcadores `[op]` do JSDoc, nas três fontes. Declará-la é bem-vindo como documentação; omiti-la não reprova nada.\n\nOBRIGATÓRIAS SEMPRE: setup, verify, createWorkItem, getWorkItem, updateWorkItem, listWorkItemsByTag, addComment, listComments, updateComment, addTag, removeTag, ensureTags, listTags, getStage, setStage, getField, setField, boardSnapshot, closeWorkItem. `updateWorkItem` (título e/ou corpo) é sempre exigida e é PARCIAL: campo não passado não é tocado. A parcialidade é requisito — o corpo de uma Story carrega a linha `Depende de: #N` que outras ferramentas leem, e uma escrita que exigisse o corpo inteiro faria um renomear de título apagar dependência em silêncio. Sem capability que a desligue: `createWorkItem` já toma `title` e `body`, então todo tracker que implementa a criação sabe escrever os dois — não existe fornecedor onde nascer com título seja possível e renomear não. Foi acrescentada depois da Fase 1 por uma varredura que cruzou os argumentos de `createWorkItem` com os mutadores existentes: cinco dos seis tinham par, `title` e `body` não.\n\n`closeWorkItem` é sempre exigida porque todo valor de `closeSemantics` (`state`, `transition-and-resolution`) implica que fechar É possível — não existe valor do enum que desligue a operação; só o COMO fechar varia por `closeSemantics`.\n\nCONDICIONAIS: syncStages (boardProvisioning: create — reescreve o vocabulário de etapas do board; num tracker map-only reconciliar etapa é REMAPEAR o stageMap, não criar, então a operação não existe lá); getProgress/setProgress (progress: native); addChild/listChildren/getParent (hierarchy: native); addBlockedBy/listBlockedBy (dependencies: native); reopenWorkItem (reopen: native — a inversa de closeWorkItem, sem argumento de destino porque reabrir não decide Etapa); listMilestones/getMilestone/setMilestoneDescription/listWorkItemsByMilestone/setMilestone/createMilestone/updateMilestone (milestones: native — leitura E escrita; a lista nasceu só com as quatro de leitura porque a CLI nunca escreveu milestone, e um contrato derivado de um consumidor read-only herda o silêncio dele em vez de uma decisão. NÃO existe deleteMilestone, e a ausência é deliberada: o GitHub apaga e desassocia as issues em silêncio, enquanto o Jira não deleta uma Version sem que se diga o destino do que aponta para ela — a assinatura, quando existir, leva o destino dos itens no argumento. Fechar uma entrega é updateMilestone com state: closed, não um verbo próprio. setMilestone e listWorkItemsByMilestone ENDEREÇAM por chave — `{key}` basta, e não o MilestoneRef inteiro: quem tem só o número (uma cascata Feature→Stories tem) teria de forjar `title: ''` para chamar, o que é apostar que o plugin ignora o campo forjado — aposta sobre um plugin específico, já que o próximo pode sobrescrever o título de verdade com o vazio. Mesma razão do parcial de getParent: ninguém inventa dado para conseguir chamar); deleteTag/countOpenWithTag (usados por uninstall e update); getItemProperty/setItemProperty (commentMarkers: false); branchToken (identity.branchSafe: false).",
|
|
159
|
+
"items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9]*$" },
|
|
160
|
+
"minItems": 1,
|
|
161
|
+
"uniqueItems": true
|
|
162
|
+
},
|
|
163
|
+
"skillFragment": {
|
|
164
|
+
"type": "string",
|
|
165
|
+
"description": "Caminho, relativo à raiz do pacote, de um markdown com as instruções específicas deste tracker para o agente (como aplicar um gatilho, como se chama a Etapa aqui). O `install-skill` injeta o fragmento nas skills, que no core ficam com texto neutro. Sem isso, as 28 skills de src/plugin/skills/ continuariam dizendo `gh issue edit <n> --add-label` para quem usa Jira."
|
|
166
|
+
}
|
|
167
|
+
},
|
|
168
|
+
"definitions": {
|
|
169
|
+
"fieldSupport": {
|
|
170
|
+
"type": "string",
|
|
171
|
+
"enum": ["native", "mapped", "tag", "none"],
|
|
172
|
+
"description": "`native` = campo próprio, escrito direto. `mapped` = existe, mas o id é descoberto no init e vive em `tracker.fieldMap` (Story Points no Jira). `tag` = emulado por label. `none` = não persiste; o core omite o campo em vez de escrever em lugar nenhum."
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
}
|
package/src/api/github-rest.mjs
CHANGED
|
@@ -722,3 +722,112 @@ export async function deleteRepoVariable(token, owner, repo, name) {
|
|
|
722
722
|
throw err;
|
|
723
723
|
}
|
|
724
724
|
}
|
|
725
|
+
|
|
726
|
+
/**
|
|
727
|
+
* Issues com a label, paginadas. Pull Request NÃO entra — para a REST ele é uma
|
|
728
|
+
* issue, e para o fluxo não é; quem filtra é o plugin, porque `pull_request` é
|
|
729
|
+
* forma do GitHub.
|
|
730
|
+
*/
|
|
731
|
+
export async function listIssuesByLabel(token, owner, repo, { labels, state = 'open' } = {}) {
|
|
732
|
+
const octokit = makeOctokit(token);
|
|
733
|
+
return octokit.paginate('GET /repos/{owner}/{repo}/issues', {
|
|
734
|
+
owner, repo, labels, state, per_page: 100,
|
|
735
|
+
});
|
|
736
|
+
}
|
|
737
|
+
|
|
738
|
+
// ── Diagnóstico (RFC-006 Fase 2, bloco G leva 2) ────────────────────────────
|
|
739
|
+
//
|
|
740
|
+
// As quatro rotas abaixo vinham de `commands/doctor.mjs`, que as chamava com
|
|
741
|
+
// Octokit CRU — a última ilha de GitHub no core, e a entrada que sobrava na
|
|
742
|
+
// allowlist da barreira. Elas não viraram operação de porta: nenhuma delas tem
|
|
743
|
+
// equivalente em Jira ou Azure DevOps, e inventar `listActionsSecrets()` no
|
|
744
|
+
// contrato é exatamente o risco §6.1 do plano. O caminho é outro — o `verify()`
|
|
745
|
+
// do plugin de SCM, que JÁ existe no contrato, as reporta como FATOS.
|
|
746
|
+
//
|
|
747
|
+
// Todas usam o octokit MUDO: aqui 403 e 404 são respostas esperadas ("o token
|
|
748
|
+
// não administra o repositório", "a branch não é protegida"), e o logger padrão
|
|
749
|
+
// as imprimiria como erro no meio do spinner do doctor.
|
|
750
|
+
|
|
751
|
+
/**
|
|
752
|
+
* NOMES dos secrets do Actions visíveis ao repositório — os dele e os da
|
|
753
|
+
* organização compartilhados com ele (é onde a GitHub App da org costuma viver).
|
|
754
|
+
*
|
|
755
|
+
* Só nomes: a API nunca expõe valores. Lança se nem os do repositório forem
|
|
756
|
+
* legíveis; os de organização são best-effort, porque listá-los exige uma
|
|
757
|
+
* permissão a mais e a ausência dela é comum.
|
|
758
|
+
*/
|
|
759
|
+
export async function listActionsSecretNames(token, owner, repo) {
|
|
760
|
+
const octokit = makeQuietOctokit(token);
|
|
761
|
+
const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets', { owner, repo });
|
|
762
|
+
const names = (res.data.secrets || []).map(s => s.name);
|
|
763
|
+
try {
|
|
764
|
+
const org = await octokit.request(
|
|
765
|
+
'GET /repos/{owner}/{repo}/actions/organization-secrets', { owner, repo });
|
|
766
|
+
for (const s of org.data.secrets || []) if (!names.includes(s.name)) names.push(s.name);
|
|
767
|
+
} catch {
|
|
768
|
+
// repositório de usuário, ou sem permissão para ver os da org
|
|
769
|
+
}
|
|
770
|
+
return names;
|
|
771
|
+
}
|
|
772
|
+
|
|
773
|
+
/**
|
|
774
|
+
* "Allow GitHub Actions to create and approve pull requests" está ligado?
|
|
775
|
+
*
|
|
776
|
+
* Vem DESLIGADO em muitas organizações, e é a falha mais provável da publicação
|
|
777
|
+
* de documento por PR. `null` quando a resposta não traz o campo; a consulta
|
|
778
|
+
* exige `administration: read`, que o GITHUB_TOKEN não tem, então o 403 LANÇA e
|
|
779
|
+
* quem chama decide — "não consegui ver" não é "está desligado".
|
|
780
|
+
*/
|
|
781
|
+
export async function getActionsCanCreatePullRequests(token, owner, repo) {
|
|
782
|
+
const octokit = makeQuietOctokit(token);
|
|
783
|
+
const res = await octokit.request(
|
|
784
|
+
'GET /repos/{owner}/{repo}/actions/permissions/workflow', { owner, repo });
|
|
785
|
+
return res.data?.can_approve_pull_request_reviews ?? null;
|
|
786
|
+
}
|
|
787
|
+
|
|
788
|
+
/**
|
|
789
|
+
* Contextos de status check OBRIGATÓRIOS na branch, ou `[]` quando não há
|
|
790
|
+
* proteção com checks.
|
|
791
|
+
*
|
|
792
|
+
* 404 é o caso comum (branch sem proteção) e vira `[]`; qualquer outro erro
|
|
793
|
+
* lança, porque "sem permissão para ler a proteção" não pode ser confundido com
|
|
794
|
+
* "não há check obrigatório" — a diferença decide um FAIL do doctor.
|
|
795
|
+
*/
|
|
796
|
+
export async function getRequiredStatusChecks(token, owner, repo, branch) {
|
|
797
|
+
const octokit = makeQuietOctokit(token);
|
|
798
|
+
try {
|
|
799
|
+
const res = await octokit.rest.repos.getBranchProtection({ owner, repo, branch });
|
|
800
|
+
return res.data?.required_status_checks?.contexts || [];
|
|
801
|
+
} catch (err) {
|
|
802
|
+
if (err.status === 404) return [];
|
|
803
|
+
throw err;
|
|
804
|
+
}
|
|
805
|
+
}
|
|
806
|
+
|
|
807
|
+
/**
|
|
808
|
+
* O usuário do token é membro ATIVO da organização?
|
|
809
|
+
*
|
|
810
|
+
* `null` quando não dá para saber — o owner pode ser conta pessoal (404), ou o
|
|
811
|
+
* token pode não ter permissão de consultar membership. Nos dois casos "não sei"
|
|
812
|
+
* é diferente de "não é", e o `doctor` mostra coisas diferentes.
|
|
813
|
+
*/
|
|
814
|
+
export async function getOrgMembershipState(token, org) {
|
|
815
|
+
const octokit = makeQuietOctokit(token);
|
|
816
|
+
try {
|
|
817
|
+
const res = await octokit.request('GET /user/memberships/orgs/{org}', { org });
|
|
818
|
+
return res.data?.state ?? null;
|
|
819
|
+
} catch {
|
|
820
|
+
return null;
|
|
821
|
+
}
|
|
822
|
+
}
|
|
823
|
+
|
|
824
|
+
/** Ficha do repositório: nome completo, visibilidade e branch default. */
|
|
825
|
+
export async function getRepoInfo(token, owner, repo) {
|
|
826
|
+
const octokit = makeQuietOctokit(token);
|
|
827
|
+
const res = await octokit.rest.repos.get({ owner, repo });
|
|
828
|
+
return {
|
|
829
|
+
fullName: res.data.full_name,
|
|
830
|
+
isPrivate: !!res.data.private,
|
|
831
|
+
defaultBranch: res.data.default_branch,
|
|
832
|
+
};
|
|
833
|
+
}
|
package/src/commands/audit.mjs
CHANGED
|
@@ -22,8 +22,7 @@ import { readdirSync } from 'node:fs';
|
|
|
22
22
|
import path from 'node:path';
|
|
23
23
|
|
|
24
24
|
import { resolveToken } from '../api/auth.mjs';
|
|
25
|
-
import {
|
|
26
|
-
import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
|
|
25
|
+
import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
|
|
27
26
|
import { CONFIG_FILE } from '../config.mjs';
|
|
28
27
|
import { detectIssueType } from '../lib/issue-type.mjs';
|
|
29
28
|
import { featureDocPaths } from '../lib/doc-paths.mjs';
|
|
@@ -95,8 +94,8 @@ export async function audit({ milestone: milestoneArg, critique = false, json =
|
|
|
95
94
|
return falhar(`Sem token utilizável para ${owner}/${repo}: ${err.message}`);
|
|
96
95
|
}
|
|
97
96
|
|
|
98
|
-
const tracker =
|
|
99
|
-
const scm =
|
|
97
|
+
const tracker = await requireTracker({ token, owner, repo, deps });
|
|
98
|
+
const scm = await requireScm({ link: resolveScmLink({ owner, repo }), token, deps });
|
|
100
99
|
|
|
101
100
|
const s = json ? null : p.spinner();
|
|
102
101
|
s?.start('Montando o catálogo de Features...');
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { appendFileSync } from 'node:fs';
|
|
2
2
|
import { resolveToken } from '../api/auth.mjs';
|
|
3
|
-
import {
|
|
4
|
-
import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
|
|
3
|
+
import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
|
|
5
4
|
|
|
6
5
|
// WorkItem → a forma `{number, nodeId, title, labels}` que este arquivo usa nos
|
|
7
6
|
// mapas de Stories/Tasks. Um lugar só, no ponto de leitura.
|
|
@@ -229,11 +228,12 @@ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = fa
|
|
|
229
228
|
|
|
230
229
|
// Porta do repositório DO PR — `--pr-repo` pode apontar para um repo de
|
|
231
230
|
// código, e o número de PR colide entre repositórios.
|
|
232
|
-
const prScm =
|
|
233
|
-
link:
|
|
231
|
+
const prScm = await requireScm({
|
|
232
|
+
link: resolveScmLink({
|
|
234
233
|
owner: prRepo.owner, repo: prRepo.repo, role: sameRepo(prRepo, hub) ? 'hub' : 'code',
|
|
235
234
|
}),
|
|
236
235
|
token,
|
|
236
|
+
deps,
|
|
237
237
|
});
|
|
238
238
|
const pr = await prScm.getPullRequest({ number: String(prNum) });
|
|
239
239
|
const prCriadoEm = pr?.createdAt ?? null;
|
|
@@ -286,7 +286,7 @@ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = fa
|
|
|
286
286
|
// Uma instância para todo o comando: o memo de item do board é dela, e é o
|
|
287
287
|
// que mantém a contagem de chamadas igual à de antes.
|
|
288
288
|
// PROJECT_TOKEN é a credencial do board; `token` segue fazendo as issues.
|
|
289
|
-
const { tracker, error: projectError } = openTracker({ token, projectToken, owner, repo, tracker: deps.tracker });
|
|
289
|
+
const { tracker, error: projectError } = await openTracker({ token, projectToken, owner, repo, tracker: deps.tracker });
|
|
290
290
|
if (projectError) {
|
|
291
291
|
console.warn(`${projectError} — board não atualizado.`);
|
|
292
292
|
return;
|
|
@@ -458,7 +458,12 @@ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = fa
|
|
|
458
458
|
);
|
|
459
459
|
}
|
|
460
460
|
// O comentário vai no PR, no repositório do PR.
|
|
461
|
-
|
|
461
|
+
// `deps.prTracker` e NÃO `deps.tracker`: o PR #77 do repo de código não é a
|
|
462
|
+
// issue #77 do hub, e o `.catch(() => {})` aqui esconderia o engano. Por isso
|
|
463
|
+
// a porta do PR entra pelo seam próprio, mesmo passando pelo loader.
|
|
464
|
+
await (await requireTracker({
|
|
465
|
+
token, owner: prRepo.owner, repo: prRepo.repo, deps: { tracker: deps.prTracker },
|
|
466
|
+
}))
|
|
462
467
|
.addComment({ ref: { key: String(prNum) }, body: partes.join('\n\n') })
|
|
463
468
|
.catch(() => {});
|
|
464
469
|
}
|