spec-first-copilot 0.5.0-beta.6 → 0.5.0-beta.8

package/bin/cli.js

@@ -2,26 +2,35 @@
 
 const path = require('path');
 const { init } = require('../lib/init');
+const { update } = require('../lib/update');
 
 const args = process.argv.slice(2);
 const command = args[0];
 
 function printUsage() {
-  console.log('Usage: spec-first-copilot init --name=<project-name> [--target=<path>]');
+  console.log('Usage:');
+  console.log('  spec-first-copilot init --name=<project-name> [--target=<path>]');
+  console.log('  spec-first-copilot update [--target=<path>] [--force]');
   console.log('');
-  console.log('Creates a new spec-first project configured for GitHub Copilot.');
+  console.log('Commands:');
+  console.log('  init     Create a new spec-first project');
+  console.log('  update   Update an existing project with new framework files');
+  console.log('           (adds missing files, updates framework files like skills/adapters/agents)');
   console.log('');
   console.log('Options:');
-  console.log('  --name=<name>    Project name (required)');
-  console.log('  --target=<path>  Target directory (defaults to ./<name>)');
+  console.log('  --name=<name>    Project name (required for init)');
+  console.log('  --target=<path>  Target directory (defaults to ./<name> for init, cwd for update)');
+  console.log('  --force          Force update all files, not just framework files (use with caution)');
 }
 
 function parseArgs(args) {
-  const parsed = {};
+  const parsed = { flags: [] };
   for (const arg of args) {
     const match = arg.match(/^--(\w+)=(.+)$/);
     if (match) {
       parsed[match[1]] = match[2];
+    } else if (arg.startsWith('--')) {
+      parsed.flags.push(arg.slice(2));
     }
   }
   return parsed;
@@ -43,6 +52,15 @@ if (command === 'init') {
     templatesDir,
     targetDir: opts.target || undefined,
   });
+} else if (command === 'update') {
+  const opts = parseArgs(args.slice(1));
+  const templatesDir = path.join(__dirname, '..', 'templates');
+
+  update({
+    templatesDir,
+    targetDir: opts.target || undefined,
+    force: opts.flags.includes('force'),
+  });
 } else {
   printUsage();
   if (command) {

package/lib/update.js

@@ -0,0 +1,130 @@
+const fs = require('fs');
+const path = require('path');
+
+const FRAMEWORK_DIRS = [
+  path.join('.github', 'adapters'),
+  path.join('.github', 'skills'),
+  path.join('.github', 'agents'),
+  path.join('.github', 'templates'),
+  path.join('.github', 'instructions'),
+];
+
+const FRAMEWORK_FILES = [
+  path.join('.github', 'rules.md'),
+  path.join('.github', 'copilot-instructions.md'),
+  path.join('.github', 'CHANGELOG.md'),
+  'sfw.config.yml.example',
+];
+
+function update({ templatesDir, targetDir, force }) {
+  const dest = targetDir || process.cwd();
+
+  if (!fs.existsSync(dest)) {
+    console.error(`Error: directory "${dest}" does not exist.`);
+    console.error('Run "spec-first-copilot init --name=<name>" first to create a project.');
+    process.exit(1);
+  }
+
+  const githubDir = path.join(dest, '.github');
+  if (!fs.existsSync(githubDir)) {
+    console.error('Error: not a spec-first project (missing .github/ directory).');
+    console.error('Run "spec-first-copilot init --name=<name>" first.');
+    process.exit(1);
+  }
+
+  console.log(`\nUpdating project in ${dest}\n`);
+
+  const stats = { added: [], updated: [], skipped: 0 };
+  syncDir(templatesDir, dest, force, stats, dest);
+
+  console.log('');
+  if (stats.added.length > 0) {
+    console.log(`Added (${stats.added.length}):`);
+    for (const f of stats.added) console.log(`  + ${f}`);
+  }
+  if (stats.updated.length > 0) {
+    console.log(`Updated (${stats.updated.length}):`);
+    for (const f of stats.updated) console.log(`  ~ ${f}`);
+  }
+  if (stats.added.length === 0 && stats.updated.length === 0) {
+    console.log('Already up to date — no new files to add.');
+  } else {
+    console.log(`\n${stats.added.length} added, ${stats.updated.length} updated, ${stats.skipped} unchanged`);
+  }
+  console.log('');
+}
+
+function syncDir(src, dest, force, stats, root) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      syncDir(srcPath, destPath, force, stats, root);
+    } else {
+      syncFile(srcPath, destPath, force, stats, root);
+    }
+  }
+}
+
+function syncFile(src, dest, force, stats, root) {
+  const rel = path.relative(root, dest);
+  const exists = fs.existsSync(dest);
+
+  if (exists && !force) {
+    const isFramework = isFrameworkPath(rel);
+    if (!isFramework) {
+      stats.skipped++;
+      return;
+    }
+    const srcContent = fs.readFileSync(src, 'utf-8');
+    const destContent = fs.readFileSync(dest, 'utf-8');
+    if (srcContent === destContent) {
+      stats.skipped++;
+      return;
+    }
+    fs.writeFileSync(dest, srcContent, 'utf-8');
+    stats.updated.push(rel);
+    return;
+  }
+
+  if (exists && force) {
+    const srcContent = fs.readFileSync(src, 'utf-8');
+    const destContent = fs.readFileSync(dest, 'utf-8');
+    if (srcContent === destContent) {
+      stats.skipped++;
+      return;
+    }
+    fs.writeFileSync(dest, srcContent, 'utf-8');
+    stats.updated.push(rel);
+    return;
+  }
+
+  const textExtensions = ['.md', '.yaml', '.yml', '.json', '.js', '.ts', '.gitignore', '.gitkeep', ''];
+  const ext = path.extname(src).toLowerCase();
+  const basename = path.basename(src);
+  const isText = textExtensions.includes(ext) || basename.startsWith('.');
+
+  if (isText) {
+    const content = fs.readFileSync(src, 'utf-8');
+    fs.writeFileSync(dest, content, 'utf-8');
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+  stats.added.push(rel);
+}
+
+function isFrameworkPath(rel) {
+  const normalized = rel.split(path.sep).join('/');
+  for (const dir of FRAMEWORK_DIRS) {
+    const normalizedDir = dir.split(path.sep).join('/');
+    if (normalized.startsWith(normalizedDir + '/')) return true;
+  }
+  for (const file of FRAMEWORK_FILES) {
+    const normalizedFile = file.split(path.sep).join('/');
+    if (normalized === normalizedFile) return true;
+  }
+  return false;
+}
+
+module.exports = { update };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.5.0-beta.6",
+  "version": "0.5.0-beta.8",
   "description": "Spec-first workflow kit for GitHub Copilot — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-copilot": "bin/cli.js"

package/templates/.github/CHANGELOG.md

@@ -0,0 +1,112 @@
+# SFW Changelog — spec-first-copilot
+
+> Este arquivo é atualizado automaticamente pelo `spec-first-copilot update`.
+> O agent deve ler este arquivo quando o usuário perguntar sobre mudanças,
+> funcionalidades novas, ou o que está disponível no framework.
+>
+> **Não editar manualmente** — será sobrescrito no próximo update.
+
+---
+
+## 0.5.0-beta.7 (2026-04-12)
+
+### Novo: Comando `/sf-load <nome>`
+Puxa insumos do backend configurado (Confluence ou filesystem) para `workspace/Input/{nome}/`.
+- Busca o scope pelo nome no backend (match exato)
+- Desce recursivamente na árvore (Confluence `get_page_children` é apenas direto — `/sf-load` faz loop)
+- Baixa conteúdo + attachments
+- Log incremental em `.ai/sf-load-log.md` (NOVO/MODIFICADO/INALTERADO via sha256)
+- Idempotente — rodar N vezes sem mudanças no backend não altera nada
+- Referência: `.github/commands/sf-load.md`
+
+### Novo: Adapter layer (Confluence + Filesystem)
+Pipeline agora é backend-agnóstico via adapters plugáveis.
+- **ConfluenceAdapter** — fala com Confluence via MCP `sooperset/mcp-atlassian`
+- **FilesystemAdapter** — lê/escreve direto no disco (também serve como mock pra testes)
+- Configurado em `sfw.config.yml` (copiar de `sfw.config.yml.example`)
+- Interface: `.github/adapters/interface.md` (7 métodos)
+- Erros tipados: `.github/adapters/errors.md` (6 classes)
+- Naming engine: `.github/adapters/naming.md` (placeholders `{scope}`, `{type}`)
+- Registry: `.github/adapters/registry.md`
+- Setup guide: `.github/adapters/SETUP.md` (passo a passo de MCP + Confluence)
+
+### Novo: `sfw.config.yml`
+Manifesto do projeto que define de onde vêm e pra onde vão os artefatos.
+- `input.adapter` — de onde puxar insumos (`confluence` ou `filesystem`)
+- `output.targets[].mode` — ligar/desligar publish (`auto`, `manual`, `off`)
+- `naming.output_container` — template do nome da subpasta no Output (ex: `out_{scope}`)
+- `naming.output_artifact` — template do nome do artefato (ex: `{scope} - {type}`)
+- Copiar `sfw.config.yml.example` e preencher. Zero segredos neste arquivo.
+
+### Novo: `SETUP.md` — Guia de configuração
+Guia passo a passo em `.github/adapters/SETUP.md`:
+- Setup Confluence: uvx, .mcp.json, token Atlassian, space key, page IDs
+- Setup 100% local (filesystem, zero dependências)
+- Como ligar/desligar Confluence via `mode: auto|manual|off`
+- Troubleshooting: tabela com todos os gotchas conhecidos
+- **IMPORTANTE**: Confluence NÃO é CLI. Acesso via MCP tools prefixadas `mcp__atlassian__confluence_*`
+
+### Novo: CLI `update`
+```bash
+npx spec-first-copilot update           # adiciona novos, atualiza framework
+npx spec-first-copilot update --force   # sobrescreve tudo incluindo copilot-instructions.md
+```
+Atualiza projeto existente sem perder arquivos do usuário.
+
+### Breaking: `/sf-setup-projeto` → `/sf-new-project <nome>`
+- Antes: `/sf-setup-projeto` era hardcoded pra pasta `setup_projeto`
+- Agora: `/sf-new-project <nome>` recebe o nome como argumento (simétrico com `/sf-feature <nome>`)
+- `/sf-new-project` gera TRD (bootstrap técnico), `/sf-feature` gera PRD (feature)
+- **Não existe mais pasta mágica** — usuário nomeia livremente em `workspace/Input/`
+- O antigo `setup-projeto.md` foi removido. Usar `new-project.md`
+
+### Breaking: `{sequence}` removido
+- Antes: todo item tinha prefixo numérico `001 - ` pra unicidade no Confluence
+- Agora: usuário nomeia livremente, agent segue o nome do Input
+- Naming simplificado: só `{scope}` e `{type}` como placeholders
+- Premissa: 1 space Confluence = 1 projeto (multi-projeto no mesmo space requer nomes únicos no Input)
+
+### Breaking: Output agrupado por scope
+- Antes: artefatos flat no Output (ex: `001 - TRD setup_projeto`)
+- Agora: subpasta por scope (ex: `out_app_barbearia/app_barbearia - TRD`)
+- Container configurável via `naming.output_container` (default: `out_{scope}`)
+- Artifact configurável via `naming.output_artifact` (default: `{scope} - {type}`)
+
+---
+
+## 0.5.0-beta.2 (2026-04-11)
+
+### Refactor: `docs/specs/` → `specs/` (top-level)
+- Projeções do SDD (brief, contracts, scenarios, tasks) movidas pra raiz
+- Regra: humano lê `workspace/Output/`, agent lê `specs/`
+
+### Refactor: 3-zone separation
+- `.github/` = AI config (rules, templates, commands, agents)
+- `docs/` = system knowledge (5 docs de sistema)
+- `workspace/` = team content (Input/ + Output/)
+
+---
+
+## 0.4.0 (2026-04-10) — v1 stable
+
+### Funcionalidades base
+- 9 commands: setup-projeto, feature, discovery, extract, design, plan, dev, merge-delta, session-finish
+- 7 agents: backend-coder, frontend-coder, db-coder, infra-coder, doc-writer, reviewer, security-reviewer
+- Templates: PRD, TRD, SDD, tasks, Progresso, context, extract-log, backlog, projetos.yaml
+- Templates de estrutura: architecture, domain, conventions, apiContracts, decisions
+- Pipeline: extract → design → plan → dev com checkpoints de aprovação
+- Delta Specs (SDD §11) + merge-delta automático
+- Security Reviewer como gate pós-dev
+- Multi-repo via projetos.yaml
+- Entregáveis contínuos (fases de entrega)
+
+---
+
+## Como usar este arquivo
+
+Se o usuário perguntar:
+- **"O que tem de novo?"** → ler a versão mais recente acima
+- **"Como uso o /sf-load?"** → apontar pra `.github/commands/sf-load.md`
+- **"Como configuro Confluence?"** → apontar pra `.github/adapters/SETUP.md`
+- **"O que é adapter?"** → apontar pra `.github/adapters/interface.md`
+- **"O que mudou de setup-projeto?"** → seção "Breaking" do 0.5.0-beta.7