@spec-wave/cli 0.13.0 → 0.15.0

package/README.md

@@ -68,7 +68,8 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 | `generate-spec` | Gera `spec.md` (usado pelo GitHub Action) |
 | `generate-plan` | Gera `plan.md` (usado pelo GitHub Action) |
 | `validate` | Valida spec.md e plan.md (usado pelo GitHub Action) |
-| `decompose` | Decompõe Feature em Stories e Tasks (usado pelo GitHub Action) |
+| `decompose` | Gera o rascunho da decomposição em `decomposition.md`; com `--apply`, cria as Stories/Tasks a partir do rascunho revisado (usado pelo GitHub Action) |
+| `move <n> <etapa>` | Move qualquer item do board (Feature, Story, Task, Bug, RFC) para uma Etapa — a Etapa nunca retrocede |
 | `code-review` | Move Feature para Code Review ao abrir PR (usado pelo GitHub Action) |
 | `qa` | Move Feature para QA ao aprovar PR (usado pelo GitHub Action) |
 | `implement` | Aciona o spec-kit localmente para implementar uma Feature (Stories pendentes em ordem de dependência), Story ou Task |
@@ -81,7 +82,7 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 | `generate-spec.yml` | label `spec-wave:spec` | Gera `docs/features/<slug>/spec.md` via IA |
 | `generate-plan.yml` | label `spec-wave:plan` | Gera `docs/features/<slug>/plan.md` via IA |
 | `validate.yml` | label `spec-wave:ready` | Valida seções obrigatórias; adiciona `spec-wave:plan-approved` |
-| `decompose.yml` | label `spec-wave:decompose` | Cria Stories e Tasks como sub-issues |
+| `decompose.yml` | labels `spec-wave:decompose` / `spec-wave:decompose-apply` | 1º grava e critica o rascunho `decomposition.md`; 2º cria Stories e Tasks como sub-issues |
 | `code-review.yml` | PR aberto/reaberto | Move Feature para `👀 Code Review` |
 | `qa.yml` | PR aprovado | Move Feature para `🧪 QA` |
 
@@ -285,20 +286,52 @@ O Action `validate.yml` verifica se todas as seções obrigatórias estão prese
 
 ---
 
-### 6. Decompor em Stories e Tasks
+### 6. Decompor em Stories e Tasks (duas etapas)
+
+A decomposição não cria issues de uma vez. Primeiro nasce um **rascunho revisável**;
+as issues só são criadas depois que você aprova.
+
+**6a. Gerar o rascunho:**
 
 ```bash
 gh issue edit 12 --add-label "spec-wave:decompose"
 ```
 
-O Action `decompose.yml` usa IA para criar sub-issues da Feature #12:
+O Action grava `docs/features/<slug>/decomposition.md` no repositório e submete o
+arquivo à crítica adversarial. **Nenhuma issue é criada.**
+
+```markdown
+# Decomposição — [FEATURE] Pagamento com PIX
+<!-- spec-wave:decomposition v1 issue=12 kind=stories -->
+
+## Story 1 — selecionar PIX como forma de pagamento
+
+**User story:** Como cliente, quero selecionar PIX, para pagar mais rápido
+**Depende de:** —
+
+### Task 1.1 — criar endpoint POST /orders/:id/payment/pix
+### Task 1.2 — integrar API do banco via webhook
+```
+
+Se a crítica encontrar contradições **graves**, ela comenta na issue citando
+`Story N` / `Task N.M`, aplica `spec-wave:critique-failed` e o Action **falha**.
+Você corrige o `decomposition.md` — o artefato que os achados referenciam — e
+reaplica `spec-wave:decompose`: o arquivo é criticado como está, sem ser regerado.
+
+**6b. Aplicar o rascunho aprovado:**
+
+```bash
+gh issue edit 12 --add-label "spec-wave:decompose-apply"
+```
+
+Agora as sub-issues da Feature #12 são criadas a partir do arquivo:
 
 ```
-#13 [STORY] Como cliente, quero selecionar PIX como forma de pagamento
+#13 [STORY] selecionar PIX como forma de pagamento
   #14 [TASK] Criar endpoint POST /orders/:id/payment/pix
   #15 [TASK] Integrar API do banco via webhook
   #16 [TASK] Exibir QR Code na tela de checkout
-#17 [STORY] Como cliente, quero receber confirmação do pagamento
+#17 [STORY] receber confirmação do pagamento
   #18 [TASK] Webhook de confirmação do banco
   #19 [TASK] Notificação por e-mail ao confirmar
 ```

package/bin/spec-wave.mjs

@@ -93,6 +93,9 @@ program
   .option('--skip-skill', 'Não verifica/atualiza a skill instalada')
   .option('--skip-config', 'Não verifica/atualiza o .spec-wave.json local')
   .option('--skip-repo', 'Não verifica/atualiza workflows e labels do repo')
+  .option('--branch [nome]', 'Envia os arquivos do repo como Pull Request numa branch, em um único commit (sem valor: spec-wave/update-v<versão>)')
+  .option('--config-in-pr', 'Força incluir o .spec-wave.json no Pull Request')
+  .option('--no-config-in-pr', 'Força manter o .spec-wave.json fora do Pull Request')
   .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
   .option('--yes', 'Aplica sem pedir confirmação')
   .action(async (options) => {
@@ -157,8 +160,9 @@ program
 
 program
   .command('decompose')
-  .description('Decompõe uma Feature em Stories e Tasks (usado pelo GitHub Action)')
+  .description('Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .option('--apply', 'Aplica o decomposition.md já revisado: cria as issues (sem esta flag, apenas gera/critica o rascunho)')
   .action(async (options) => {
     const { decompose } = await import('../src/commands/decompose.mjs');
     await decompose(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -212,6 +216,18 @@ program
     await task({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('move')
+  .description('Move qualquer item do board (Feature, Story, Task, Bug, RFC) para uma Etapa — a Etapa nunca retrocede')
+  .argument('<n>', 'Número da issue, ex.: 8 ou #8')
+  .argument('<etapa>', 'Etapa de destino, com ou sem emoji, ex.: "code review", "Homologação", "🎉 Done"')
+  .option('--status <valor>', 'Valor do campo Status no destino: Todo, In Progress ou Done (default: Todo)')
+  .action(async (n, etapa, options) => {
+    const { move } = await import('../src/commands/move.mjs');
+    await move({ issue: n, stage: etapa, ...options })
+      .catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('story')
   .description('Gerencia uma Story no board: review (move para Code Review)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-rest.mjs

@@ -4,6 +4,15 @@ function makeOctokit(token) {
   return new Octokit({ auth: token });
 }
 
+// Para as consultas em que 404 é um RESULTADO ESPERADO ("a branch ainda não
+// existe", "não há o que comparar") e não um erro: o logger padrão do Octokit
+// imprime a linha `GET ... - 404` no stderr, que no meio de um spinner parece
+// falha. Mesmo padrão do doctor.mjs, onde 404/403 também são respostas válidas.
+const silentLog = { debug() {}, info() {}, warn() {}, error() {} };
+function makeQuietOctokit(token) {
+  return new Octokit({ auth: token, log: silentLog });
+}
+
 export async function getOwnerNodeId(token, owner) {
   const octokit = makeOctokit(token);
   try {
@@ -87,6 +96,189 @@ export async function upsertFile(token, owner, repo, path, content, message) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Git Data API — commit ATÔMICO + Pull Request
+//
+// O upsertFile acima faz UM COMMIT POR ARQUIVO direto na branch default: oito
+// arquivos = oito commits, e uma falha no quinto deixa o repositório num estado
+// intermediário que ninguém pediu. Aqui a árvore inteira é montada primeiro e só
+// então nascem o commit e a ref — antes da createRef/updateRef nada é
+// ALCANÇÁVEL (os objetos existem no banco, mas nenhuma ref aponta para eles),
+// então uma falha no meio não muda o repositório observável.
+//
+// Três pegadinhas da API, todas documentadas porque custam tempo de depuração:
+//  • createTree SEM `base_tree` produz uma árvore com SÓ os arquivos enviados —
+//    o commit resultante APAGA todo o resto do repositório, e a API responde 201.
+//  • getRef/getCommit/updateRef querem o ref SEM o prefixo `refs/`
+//    ('heads/main'); createRef quer COM ('refs/heads/x'). Trocar dá 404/422 sem
+//    explicação.
+//  • pulls.list exige `head` qualificado com o owner ('owner:branch'): sem o
+//    prefixo a API IGNORA o filtro e devolve todos os PRs abertos.
+// ---------------------------------------------------------------------------
+
+/**
+ * Lê a ponta de uma branch: sha do commit e sha da ÁRVORE desse commit.
+ *
+ * A árvore é o que interessa para o `base_tree` e para detectar "nada mudou":
+ * git é endereçado por conteúdo, então árvore igual = conteúdo igual, sem
+ * precisar pedir diff.
+ *
+ * @returns {Promise<{commitSha: string, treeSha: string}|null>} null quando a
+ *          branch não existe (404) — o chamador decide criar vs. atualizar a ref.
+ */
+export async function getBranchHead(token, owner, repo, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = branch inexistente, não erro
+  let commitSha;
+  try {
+    const ref = await octokit.rest.git.getRef({ owner, repo, ref: `heads/${branch}` });
+    commitSha = ref.data.object.sha;
+  } catch (err) {
+    if (err.status === 404) return null;
+    throw err;
+  }
+  const commit = await octokit.rest.git.getCommit({ owner, repo, commit_sha: commitSha });
+  return { commitSha, treeSha: commit.data.tree.sha };
+}
+
+/**
+ * Compara `base...branch`.
+ *
+ * 'behind'/'identical' significa que a branch não tem nenhum commit que a base
+ * já não tenha — sinal típico de branch de um PR já mergeado com squash. Serve
+ * só para AVISAR antes de empilhar um commit numa branch obsoleta; nunca para
+ * decidir um force-push.
+ *
+ * @returns {Promise<'identical'|'ahead'|'behind'|'diverged'|null>} null se a
+ *          branch não existe ou a comparação falha (é só um aviso — não pode
+ *          derrubar o fluxo).
+ */
+export async function compareBranches(token, owner, repo, base, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = branch inexistente, não erro
+  try {
+    const res = await octokit.rest.repos.compareCommitsWithBasehead({
+      owner, repo, basehead: `${base}...${branch}`,
+    });
+    return res.data.status;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Grava N arquivos em UM único commit numa branch (criando-a a partir de `base`
+ * quando ainda não existe).
+ *
+ * Idempotente de propósito: rodar `update --branch fix/x` duas vezes não gera um
+ * segundo commit. Quando a branch já existe o pai é a PONTA DELA — não a base —
+ * então a atualização da ref é sempre fast-forward e `force` fica em false (uma
+ * corrida com outro push falha em vez de sobrescrever trabalho alheio).
+ *
+ * Se a árvore montada tiver o MESMO sha da árvore do pai, nada mudou de fato e o
+ * commit é pulado: commit vazio num PR só confunde quem revisa.
+ *
+ * @param {object} opts
+ * @param {string} opts.branch branch de trabalho (head do PR)
+ * @param {string} opts.base branch de partida quando `branch` ainda não existe
+ * @param {Array<{path: string, content: string}>} opts.files conteúdo FINAL de cada arquivo
+ * @param {string} opts.message mensagem do commit único
+ * @returns {Promise<{branch, base, commitSha, createdBranch, unchanged, baseSha}>}
+ */
+export async function commitFilesToBranch(token, owner, repo, { branch, base, files, message }) {
+  const octokit = makeOctokit(token);
+  if (!files?.length) throw new Error('commitFilesToBranch: nenhum arquivo a enviar.');
+
+  const baseHead = await getBranchHead(token, owner, repo, base);
+  if (!baseHead) throw new Error(`Branch base "${base}" não encontrada em ${owner}/${repo}.`);
+
+  const head = await getBranchHead(token, owner, repo, branch);
+  const parent = head ?? baseHead;
+
+  // `content` inline: a própria API cria o blob, poupando um createBlob por
+  // arquivo. Vale só para texto UTF-8 — todos os nossos templates são.
+  // mode: 100644 = arquivo comum (100755 executável, 040000 subárvore).
+  const tree = await octokit.rest.git.createTree({
+    owner,
+    repo,
+    base_tree: parent.treeSha, // SEM isto o commit apagaria o repositório inteiro
+    tree: files.map(f => ({ path: f.path, mode: '100644', type: 'blob', content: f.content })),
+  });
+
+  if (tree.data.sha === parent.treeSha) {
+    return {
+      branch, base, commitSha: parent.commitSha,
+      createdBranch: false, unchanged: true, baseSha: baseHead.commitSha,
+    };
+  }
+
+  const commit = await octokit.rest.git.createCommit({
+    owner, repo, message, tree: tree.data.sha, parents: [parent.commitSha],
+  });
+
+  if (head) {
+    await octokit.rest.git.updateRef({
+      owner, repo, ref: `heads/${branch}`, sha: commit.data.sha, force: false,
+    });
+  } else {
+    await octokit.rest.git.createRef({
+      owner, repo, ref: `refs/heads/${branch}`, sha: commit.data.sha,
+    });
+  }
+
+  return {
+    branch, base, commitSha: commit.data.sha,
+    createdBranch: !head, unchanged: false, baseSha: baseHead.commitSha,
+  };
+}
+
+/**
+ * PR ABERTO cuja head é `branch` neste mesmo repositório.
+ *
+ * @returns {Promise<{number, url, title, base}|null>}
+ */
+export async function findOpenPR(token, owner, repo, branch) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.pulls.list({
+    owner, repo, state: 'open', head: `${owner}:${branch}`, per_page: 1,
+  });
+  const pr = res.data[0];
+  return pr
+    ? { number: pr.number, url: pr.html_url, title: pr.title, base: pr.base.ref }
+    : null;
+}
+
+/**
+ * Abre o PR da branch — ou devolve o que já está aberto para ela.
+ *
+ * Rodar o update duas vezes não pode virar dois PRs. O findOpenPR cobre o caso
+ * normal; o catch do 422 cobre a corrida e o "No commits between base and head"
+ * (branch sem nada novo em relação à base → não existe PR a abrir → null).
+ * Qualquer outro 422 propaga com a mensagem real da API, senão uma base inválida
+ * viraria um silencioso "nada a revisar".
+ *
+ * @returns {Promise<{number, url, created}|null>}
+ */
+export async function ensurePullRequest(
+  token, owner, repo, { branch, base, title, body, draft = false }
+) {
+  const octokit = makeOctokit(token);
+  const existing = await findOpenPR(token, owner, repo, branch);
+  if (existing) return { ...existing, created: false };
+  try {
+    const res = await octokit.rest.pulls.create({
+      owner, repo, title, body, head: branch, base, draft,
+    });
+    return { number: res.data.number, url: res.data.html_url, created: true };
+  } catch (err) {
+    if (err.status !== 422) throw err;
+    const again = await findOpenPR(token, owner, repo, branch);
+    if (again) return { ...again, created: false };
+    const detail = err.response?.data?.errors?.map(e => e.message).filter(Boolean).join('; ')
+      || err.message;
+    if (/No commits between/i.test(detail)) return null;
+    throw new Error(detail);
+  }
+}
+
 // `id` é o database id da issue — exigido pela API de dependências
 // (blocked_by), que não aceita number nem node id.
 export async function createIssue(token, owner, repo, title, body, labels) {
@@ -235,10 +427,14 @@ export async function getPR(token, owner, repo, prNumber) {
   return res.data;
 }
 
-export async function getFileContent(token, owner, repo, path) {
+// `ref` é opcional (compatível com os chamadores de 4 argumentos): o modo PR do
+// `update` precisa ler o .spec-wave.json na BASE, não no que a API escolher.
+export async function getFileContent(token, owner, repo, path, ref) {
   const octokit = makeOctokit(token);
   try {
-    const res = await octokit.rest.repos.getContent({ owner, repo, path });
+    const res = await octokit.rest.repos.getContent({
+      owner, repo, path, ...(ref ? { ref } : {}),
+    });
     return Buffer.from(res.data.content, 'base64').toString('utf-8');
   } catch (err) {
     if (err.status === 404) return null;

package/src/commands/code-review.mjs

@@ -1,11 +1,10 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, getPR, commentOnIssue } from '../api/github-rest.mjs';
 import { addProjectItem, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
-import { CONFIG_FILE, STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType } from '../config.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType } from '../config.mjs';
 
 // Ao abrir o PR: Stories/Feature → Etapa "👀 Code Review" (Status "Todo");
 // Tasks → Etapa "🎉 Done" (Status "Done"), pois a implementação da task terminou.
@@ -118,11 +117,9 @@ export async function codeReview({ prNumber }) {
   const token = await resolveToken();
   const projectToken = process.env.PROJECT_TOKEN || token;
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
-  let cfg = {};
-  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
-  const owner = envOwner || cfg.owner;
-  const repo = envRepo || cfg.repo;
+  const { config: cfg } = loadConfig();
+  const owner = envOwner || cfg?.owner;
+  const repo = envRepo || cfg?.repo;
 
   if (!owner || !repo) {
     throw new Error(