@spec-wave/cli 0.13.0 → 0.15.0

package/src/lib/pr-branch.mjs

@@ -0,0 +1,267 @@
+// Regras PURAS do modo `--branch` do update (arquivos do repo via Pull Request).
+//
+// Até aqui o `update` era a única exceção ao fluxo de PR: commitava os arquivos
+// do repo direto na branch default, um commit por arquivo. Em repositório com
+// proteção de branch isso falha no meio da execução e deixa parte aplicada; e
+// mesmo sem proteção, contorna a revisão que todo o resto do fluxo tem.
+//
+// Tudo aqui é puro de propósito. A suíte não tem nenhuma infraestrutura de mock
+// de HTTP, então a única forma de testar o modo PR é manter as DECISÕES (nome da
+// branch, o que entra no PR, o que o corpo do PR conta a quem revisa) separadas
+// das chamadas de rede, que ficam em api/github-rest.mjs.
+
+import { CLI_VERSION } from './templates.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+
+/**
+ * Nome automático da branch quando `--branch` vem sem valor.
+ *
+ * Deliberadamente SEM timestamp: rodar o update duas vezes para a MESMA versão
+ * da CLI tem que reaproveitar o mesmo PR, não espalhar uma branch nova por
+ * tentativa. O bump de versão é o que separa uma atualização da próxima, e ele
+ * já está no nome.
+ *
+ * @param {string} [version]
+ * @returns {string}
+ */
+export function autoBranchName(version = CLI_VERSION) {
+  return `spec-wave/update-v${version}`;
+}
+
+// Proibições de `git check-ref-format` para refs/heads/<nome>: caractere
+// de controle e espaço (\u0000-\u0020), DEL (\u007f) e os
+// metacaracteres de revisão. Escapes explícitos de propósito: caractere de
+// controle literal no fonte é invisível e não sobrevive a copiar/colar.
+const REF_FORBIDDEN = /[\u0000-\u0020\u007f~^:?*[\\]/;
+
+const MAX_BRANCH_LENGTH = 200;
+
+/**
+ * Resolve e VALIDA o nome da branch (função PURA).
+ *
+ * Validar aqui, antes de qualquer chamada de rede, evita o pior desperdício
+ * possível: gastar meia dúzia de requisições de comparação e só descobrir no
+ * `createRef` que o nome tinha um espaço — com a mensagem crua da API, longe da
+ * causa.
+ *
+ * Mesmo contrato de `resolveStageName` em lib/board.mjs: `{valor, error}`.
+ *
+ * @param {string|boolean|undefined|null} value valor de `options.branch` — o
+ *        commander entrega `true` para `--branch` sem valor
+ * @param {object} [opts]
+ * @param {string} [opts.version] versão usada no nome automático
+ * @returns {{ branch: string|null, error: string|null }}
+ */
+export function resolveBranchName(value, { version = CLI_VERSION } = {}) {
+  if (value === true || value === undefined || value === null || String(value).trim() === '') {
+    return { branch: autoBranchName(version), error: null };
+  }
+
+  let branch = String(value).trim();
+  // Erro comum: colar o ref completo em vez do nome. Corrigir é mais útil que recusar.
+  if (branch.startsWith('refs/heads/')) branch = branch.slice('refs/heads/'.length);
+
+  const bad = (why) => ({ branch: null, error: `Nome de branch inválido ("${branch}"): ${why}.` });
+
+  if (!branch) return bad('nome vazio');
+  if (branch.length > MAX_BRANCH_LENGTH) {
+    return bad(`nome longo demais (máximo ${MAX_BRANCH_LENGTH} caracteres)`);
+  }
+  if (REF_FORBIDDEN.test(branch)) {
+    return bad('não pode conter espaço, caractere de controle ou ~ ^ : ? * [ \\');
+  }
+  if (branch.includes('..')) return bad('não pode conter ".."');
+  if (branch.includes('@{')) return bad('não pode conter "@{"');
+  if (branch === '@') return bad('não pode ser apenas "@"');
+  if (branch.startsWith('/') || branch.endsWith('/')) return bad('não pode começar nem terminar com "/"');
+  if (branch.includes('//')) return bad('não pode conter "//"');
+  if (branch.startsWith('-')) return bad('não pode começar com "-"');
+  if (branch.endsWith('.')) return bad('não pode terminar com "."');
+  if (branch.toUpperCase() === 'HEAD') return bad('"HEAD" é reservado');
+  for (const part of branch.split('/')) {
+    if (part.startsWith('.')) return bad('nenhum componente pode começar com "."');
+    if (part.endsWith('.lock')) return bad('nenhum componente pode terminar com ".lock"');
+  }
+  return { branch, error: null };
+}
+
+/**
+ * Título do PR — e assunto do commit único (função PURA).
+ *
+ * A mesma frase nos dois lugares de propósito: no modo PR existe um commit só, e
+ * ver textos diferentes para a mesma mudança na lista de commits e no título do
+ * PR só gera dúvida.
+ */
+export function composePrTitle({ version = CLI_VERSION } = {}) {
+  return `chore(spec-wave): atualiza arquivos do repo para v${version}`;
+}
+
+/**
+ * Mensagem do commit ÚNICO (função PURA).
+ *
+ * O corpo lista arquivo + motivo porque este é o único commit da branch: ele
+ * precisa se explicar sozinho num `git log` feito seis meses depois, sem o PR
+ * aberto ao lado.
+ *
+ * @param {object} [a]
+ * @param {string} [a.version]
+ * @param {Array<{path: string, reason: string}>} [a.files]
+ * @returns {string}
+ */
+export function buildCommitMessage({ version = CLI_VERSION, files = [] } = {}) {
+  const subject = composePrTitle({ version });
+  if (!files.length) return `${subject}\n`;
+  return `${subject}\n\n${files.map(f => `- ${f.path} (${f.reason})`).join('\n')}\n`;
+}
+
+/**
+ * Corpo do PR (função PURA).
+ *
+ * Quem revisa precisa saber DUAS coisas que o diff não mostra:
+ *  • as labels já foram aplicadas direto na base — label é metadado do
+ *    repositório, não existe forma de versioná-la num PR, então ela mudou ANTES
+ *    de alguém revisar isto;
+ *  • a skill dos agentes foi atualizada em máquina local, fora do repositório.
+ * Sem esses dois blocos o PR parece ser a totalidade do que o update fez — e não é.
+ *
+ * @param {object} [a]
+ * @param {Array<{path: string, reason: string}>} [a.files] arquivos que ENTRARAM no commit
+ * @param {{included: boolean, reason: string}|null} [a.config] decisão sobre o .spec-wave.json
+ * @param {{created: string[], updated: string[], removed: string[]}|null} [a.labels]
+ *        labels EFETIVAMENTE aplicadas (não o diff detectado — o corpo não pode
+ *        prometer o que falhou)
+ * @param {string[]} [a.skill] nomes dos agentes cuja skill foi atualizada localmente
+ * @returns {string} markdown
+ */
+export function composePrBody({
+  version = CLI_VERSION, base = '?', branch = '?',
+  files = [], config = null, labels = null, skill = [],
+} = {}) {
+  const l = [];
+  l.push(`Atualização gerada por \`spec-wave update\` (CLI v${version}).`);
+  l.push('');
+  l.push(`Base: \`${base}\` · Branch: \`${branch}\``);
+  l.push('');
+  l.push('## Arquivos do repositório');
+  l.push('');
+  if (files.length) for (const f of files) l.push(`- \`${f.path}\` — ${f.reason}`);
+  else l.push('_Nenhum._');
+
+  if (config) {
+    l.push('');
+    l.push(`## ${CONFIG_FILE}`);
+    l.push('');
+    l.push(config.included
+      ? `Incluído neste PR — ${config.reason}.`
+      : `**Fora** deste PR — ${config.reason}.`);
+  }
+
+  const labelTotal = labels
+    ? labels.created.length + labels.updated.length + labels.removed.length
+    : 0;
+  if (labelTotal) {
+    l.push('');
+    l.push(`## Labels — JÁ aplicadas em \`${base}\`, fora deste PR`);
+    l.push('');
+    l.push(
+      'Label é metadado do repositório e não pode ser versionada: estas mudanças já ' +
+      'valem, com ou sem o merge deste PR.'
+    );
+    l.push('');
+    if (labels.created.length) l.push(`- criadas: ${labels.created.map(n => `\`${n}\``).join(', ')}`);
+    if (labels.updated.length) l.push(`- atualizadas: ${labels.updated.map(n => `\`${n}\``).join(', ')}`);
+    if (labels.removed.length) l.push(`- removidas (descontinuadas): ${labels.removed.map(n => `\`${n}\``).join(', ')}`);
+  }
+
+  if (skill.length) {
+    l.push('');
+    l.push('## Skill dos agentes — fora deste PR');
+    l.push('');
+    l.push(
+      `Atualizada localmente em: ${skill.map(n => `\`${n}\``).join(', ')}. ` +
+      'Não faz parte do repositório.'
+    );
+  }
+
+  l.push('');
+  l.push('---');
+  l.push(`Depois do merge, \`npx @spec-wave/cli@${version} update --dry-run\` deve reportar tudo em dia.`);
+  return `${l.join('\n')}\n`;
+}
+
+/**
+ * O .spec-wave.json entra no PR? (função PURA)
+ *
+ * Política herdada do init (ver o comentário em commands/init.mjs): o config é
+ * gravado LOCAL de propósito. Quem não o commitou escolheu mantê-lo fora do
+ * versionamento, e passar a versioná-lo é decisão de projeto — não pode ser
+ * efeito colateral de um `update`. Logo: só entra se JÁ estiver versionado na
+ * base. `--config-in-pr` / `--no-config-in-pr` forçam os dois lados.
+ *
+ * Cobre também o caso em que o config NÃO está desatualizado pela versão mas o
+ * arquivo local difere do que está na base (alguém regenerou e esqueceu de
+ * commitar): entra igual, porque é exatamente para isso que o PR serve.
+ *
+ * @param {object} [a]
+ * @param {string|null|undefined} [a.remote] conteúdo do config na base (null/undefined = não versionado)
+ * @param {string|null} [a.desired] conteúdo que deveria estar lá
+ * @param {boolean} [a.willRegenerate] o conteúdo ainda vai ser regenerado (no
+ *        resumo e no dry-run ele não existe); o regenerado SEMPRE difere do
+ *        remoto, porque `refreshedAt` muda a cada execução
+ * @param {boolean|undefined} [a.force] undefined | true (--config-in-pr) | false (--no-config-in-pr)
+ * @returns {{ included: boolean, reason: string }}
+ */
+export function decideConfigInPr({ remote, desired, willRegenerate = false, force } = {}) {
+  const versioned = remote !== null && remote !== undefined;
+  if (force === false) return { included: false, reason: '--no-config-in-pr' };
+  if (!desired && !willRegenerate) {
+    return { included: false, reason: 'sem conteúdo local para enviar' };
+  }
+  if (force === true) {
+    return versioned
+      ? { included: true, reason: '--config-in-pr' }
+      : { included: true, reason: `--config-in-pr (passa a versionar o ${CONFIG_FILE})` };
+  }
+  if (!versioned) {
+    return {
+      included: false,
+      reason: 'não está versionado na base, segue apenas local ' +
+        '(use --config-in-pr para versioná-lo)',
+    };
+  }
+  if (!willRegenerate && remote === desired) {
+    return { included: false, reason: 'já idêntico na base' };
+  }
+  return { included: true, reason: 'versionado na base e divergente do local' };
+}
+
+/**
+ * Traduz o erro cru da Git Data API para uma dica acionável (função PURA).
+ *
+ * Sem isto o usuário vê "Not Found" num POST e conclui que o repositório não
+ * existe, quando o problema é um token sem escrita em Contents — e "Resource not
+ * accessible" não diz QUAL permissão falta.
+ *
+ * @param {{status?: number, message?: string}} err
+ * @returns {string}
+ */
+export function explainGitWriteError(err) {
+  const msg = err?.message || 'erro desconhecido';
+  switch (err?.status) {
+    case 401:
+      return `${msg} — token inválido ou expirado.`;
+    case 403:
+      return `${msg} — o token não tem permissão de escrita. Precisa de "Contents: write" e ` +
+        '"Pull requests: write" (fine-grained) ou do escopo `repo` (classic).';
+    case 404:
+      return `${msg} — repositório ou branch inexistente, OU token sem acesso a este ` +
+        'repositório (o GitHub responde 404 em vez de 403 para não revelar repos privados).';
+    case 409:
+      return `${msg} — repositório vazio (sem nenhum commit): rode \`spec-wave init\` antes.`;
+    case 422:
+      return `${msg} — o GitHub recusou a operação. Causas comuns: regra de proteção/ruleset ` +
+        'na branch (commits da API não são assinados) ou branch já em dia.';
+    default:
+      return msg;
+  }
+}

package/src/lib/project-root.mjs

@@ -0,0 +1,93 @@
+// Descoberta da raiz do projeto spec-wave (o diretório com .spec-wave.json).
+//
+// Antes, cada comando fazia `path.join(process.cwd(), CONFIG_FILE)` — mais de
+// dez cópias da mesma linha, e nenhuma subia na árvore. O efeito prático era que
+// qualquer comando rodado de dentro de `apps/web` falhava com "repositório não
+// inicializado", mesmo com o config uma pasta acima. Aqui o config é procurado
+// subindo até a raiz do filesystem, como o git faz com o .git.
+//
+// Achar o config é metade do problema: os documentos gerados vivem em
+// `docs/features/<slug>/`, relativo à RAIZ, não ao cwd. Por isso `loadConfig`
+// devolve `root` e existe `resolveFromRoot` — sem eles, rodar de um
+// subdiretório acharia o config e erraria todos os caminhos de documento.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { CONFIG_FILE } from '../config.mjs';
+
+/**
+ * Procura o .spec-wave.json em `cwd` e nos diretórios acima (função quase pura:
+ * só toca o filesystem via existsSync).
+ *
+ * @param {string} [cwd=process.cwd()] diretório onde começar a busca
+ * @returns {string|null} caminho absoluto do arquivo, ou null se não houver
+ */
+export function findConfigPath(cwd = process.cwd()) {
+  let dir = path.resolve(cwd);
+  // path.dirname('/') === '/': a igualdade é o que encerra o laço na raiz.
+  for (;;) {
+    const candidate = path.join(dir, CONFIG_FILE);
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Localiza e lê o .spec-wave.json.
+ *
+ * Nunca lança: devolve `error` legível para o chamador compor a mensagem que já
+ * exibia ("… — board não atualizado.", "Rode spec-wave init primeiro.").
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @returns {{ config: object|null, root: string|null, configPath: string|null, error: string|null }}
+ *          root = diretório que contém o config (âncora dos caminhos de documento)
+ */
+export function loadConfig(cwd = process.cwd()) {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) {
+    return { config: null, root: null, configPath: null, error: `${CONFIG_FILE} não encontrado` };
+  }
+  const root = path.dirname(configPath);
+  try {
+    return { config: JSON.parse(readFileSync(configPath, 'utf-8')), root, configPath, error: null };
+  } catch (err) {
+    return { config: null, root, configPath, error: `${CONFIG_FILE} corrompido (${err.message})` };
+  }
+}
+
+/**
+ * Resolve um caminho relativo do projeto (ex.: `docs/features/<slug>`) contra a
+ * raiz descoberta, com fallback para o cwd quando não há config — assim os
+ * comandos que rodam sem `.spec-wave.json` (ou em teste) seguem funcionando.
+ *
+ * @param {string|null} root raiz devolvida por loadConfig
+ * @param {...string} parts segmentos relativos
+ * @returns {string} caminho absoluto
+ */
+export function resolveFromRoot(root, ...parts) {
+  return path.resolve(root || process.cwd(), ...parts);
+}
+
+/**
+ * Resolve owner/repo: env GITHUB_REPOSITORY (padrão dos comandos rodados em
+ * Action) com fallback no .spec-wave.json — comandos locais rodam sem essa env.
+ *
+ * Era o mesmo bloco copiado em story/task/order/qa/code-review/validate.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @returns {{ owner: string|undefined, repo: string|undefined,
+ *             root: string|null, config: object|null, error: string|null }}
+ */
+export function resolveRepoContext(cwd = process.cwd()) {
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { config, root, error } = loadConfig(cwd);
+  return {
+    owner: envOwner || config?.owner,
+    repo: envRepo || config?.repo,
+    root,
+    config,
+    error,
+  };
+}

package/src/lib/templates.mjs

@@ -0,0 +1,53 @@
+// Leitura dos templates empacotados, com resolução de placeholders.
+//
+// Os workflows chamavam `npx @spec-wave/cli@latest`, o que significava que uma
+// release da CLI mudava o comportamento de pipelines já em andamento — foi o que
+// aconteceu quando a 0.13.0 removeu o `--force` sem que nada no repositório
+// mudasse. Agora o template traz `{{CLI_VERSION}}` e o `init`/`update` gravam a
+// versão fixa, tornando o bump um diff explícito e revisável.
+//
+// A substituição PRECISA passar por aqui nos dois lados: o `init`/`setupFiles`
+// que escreve, e o `update` que compara byte a byte com o remoto. Se só um lado
+// resolvesse o placeholder, todo `update` veria os seis workflows como
+// "desatualizados" para sempre.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
+
+const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
+export const CLI_VERSION = pkg.version;
+
+const PLACEHOLDERS = { CLI_VERSION };
+
+/**
+ * Resolve os placeholders `{{NOME}}` de um template (função PURA).
+ *
+ * Placeholder desconhecido é deixado intacto em vez de virar string vazia: um
+ * `{{TYPO}}` visível no arquivo gerado é muito mais fácil de diagnosticar do que
+ * um trecho que simplesmente desapareceu.
+ *
+ * @param {string} content conteúdo cru do template
+ * @param {object} [values] sobrescreve/estende os placeholders padrão
+ * @returns {string}
+ */
+export function renderTemplate(content, values = {}) {
+  const table = { ...PLACEHOLDERS, ...values };
+  return String(content ?? '').replace(
+    /\{\{(\w+)\}\}/g,
+    (match, key) => (key in table ? String(table[key]) : match)
+  );
+}
+
+/**
+ * Lê um template empacotado com os placeholders já resolvidos.
+ *
+ * @param {...string} parts caminho relativo dentro de src/templates
+ * @returns {string}
+ */
+export function readTemplate(...parts) {
+  return renderTemplate(readFileSync(path.join(TEMPLATES_DIR, ...parts), 'utf-8'));
+}

package/src/setup/files.mjs

@@ -1,15 +1,8 @@
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
 import { upsertFile, getFileContent, isRepoInitialized } from '../api/github-rest.mjs';
 import { WORKFLOW_FILES } from '../config.mjs';
-
-const __dir = path.dirname(fileURLToPath(import.meta.url));
-const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
-
-function readTemplate(...parts) {
-  return readFileSync(path.join(TEMPLATES_DIR, ...parts), 'utf-8');
-}
+// readTemplate resolve {{CLI_VERSION}} — é o que fixa a versão da CLI nos
+// workflows gravados no repo-alvo (ver src/lib/templates.mjs).
+import { readTemplate } from '../lib/templates.mjs';
 
 export async function setupFiles(token, owner, repo, spinner) {
   spinner.message('Verificando repositório...');