@guilhermefsousa/open-spec-kit 0.0.9 → 0.0.11

package/src/commands/update.js

@@ -1,188 +1,158 @@
 import chalk from 'chalk';
 import ora from 'ora';
-import { readFile, writeFile, access, mkdir, readdir } from 'fs/promises';
-import { join } from 'path';
-import yaml from 'yaml';
+import { readFile, writeFile, access, mkdir, readdir, cp } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { GLOBAL_DIR, getGlobalPath } from '../utils/global-path.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates');
 
 export async function updateCommand() {
   console.log(chalk.bold('\n  open-spec-kit update\n'));
 
-  const cwd = process.cwd();
-  const spinner = ora('Lendo projects.yml...').start();
+  // Check global install exists
+  try {
+    await access(GLOBAL_DIR);
+  } catch {
+    console.log(chalk.red(`  Instalação global não encontrada (${GLOBAL_DIR})`));
+    console.log(chalk.dim('  Execute "open-spec-kit install" primeiro.\n'));
+    return;
+  }
+
+  const spinner = ora('Atualizando skills e rules globais...').start();
 
   try {
-    const projectsRaw = await readFile(join(cwd, 'projects.yml'), 'utf-8');
-    const projects = parseProjectsYaml(projectsRaw);
+    // Phase 1: Re-copy templates from npm package → global
+    spinner.text = 'Copiando templates atualizados...';
 
-    if (projects.agents.length === 0) {
-      spinner.fail('projects.yml não contém campo "agents". Execute "open-spec-kit init" primeiro.');
-      return;
+    const agentsSource = join(TEMPLATES_DIR, 'agents');
+    for (const subdir of ['skills', 'rules', 'agents', 'scripts']) {
+      const src = join(agentsSource, subdir);
+      const dest = getGlobalPath(subdir);
+      try {
+        await access(src);
+        await cp(src, dest, { recursive: true, force: true });
+      } catch { /* subdir may not exist in templates */ }
     }
 
-    spinner.succeed(`Agents configurados: ${projects.agents.join(', ')}`);
-
-    // Check source of truth files exist
-    const sourceFiles = [
-      '.agents/agents/spec-hub.agent.md',
-      '.agents/rules/ownership.instructions.md',
-      '.agents/rules/hub_structure.instructions.md',
+    spinner.succeed('Skills e rules globais atualizados');
+
+    // Phase 2: Sync Claude → Copilot mirrors
+    const syncSpinner = ora('Sincronizando mirrors Copilot...').start();
+    let synced = 0;
+
+    // Sync rules with Copilot frontmatter
+    const syncPairs = [
+      {
+        source: getGlobalPath('rules', 'ownership.instructions.md'),
+        target: getGlobalPath('github', 'instructions', 'ownership.instructions.md'),
+        label: 'ownership rules',
+        transform: (content) => addCopilotFrontmatter(content, 'specs/**,docs/**,projects.yml')
+      },
+      {
+        source: getGlobalPath('rules', 'hub_structure.instructions.md'),
+        target: getGlobalPath('github', 'instructions', 'hub_structure.instructions.md'),
+        label: 'structure rules',
+        transform: (content) => addCopilotFrontmatter(content, 'specs/**,docs/**,projects.yml')
+      },
     ];
 
-    const missingSource = [];
-    for (const f of sourceFiles) {
+    for (const { source, target, label, transform } of syncPairs) {
       try {
-        await access(join(cwd, f));
-      } catch {
-        missingSource.push(f);
+        const sourceContent = await readFile(source, 'utf-8');
+        const targetContent = transform(sourceContent);
+
+        let existingTarget = '';
+        try {
+          existingTarget = await readFile(target, 'utf-8');
+        } catch { /* target doesn't exist yet */ }
+
+        if (existingTarget !== targetContent) {
+          await mkdir(getGlobalPath('github', 'instructions'), { recursive: true });
+          await writeFile(target, targetContent);
+          synced++;
+          console.log(chalk.green(`    ✓ ${label} sincronizado`));
+        }
+      } catch (err) {
+        console.log(chalk.yellow(`    ⚠ Não foi possível sincronizar ${label}: ${err.message}`));
       }
     }
 
-    if (missingSource.length > 0) {
-      console.log(chalk.yellow('\n  Arquivos fonte ausentes (source of truth):'));
-      missingSource.forEach(f => console.log(chalk.dim(`    - ${f}`)));
-      console.log(chalk.dim('  Execute "open-spec-kit init" para gerar.'));
-      return;
-    }
+    // Sync skills
+    try {
+      const skillsDir = getGlobalPath('skills');
+      const skillEntries = await readdir(skillsDir, { withFileTypes: true });
+      const skillDirs = skillEntries.filter(e => e.isDirectory()).map(e => e.name);
+
+      for (const skillName of skillDirs) {
+        const source = join(skillsDir, skillName, 'SKILL.md');
+        const target = getGlobalPath('github', 'skills', skillName, 'SKILL.md');
 
-    // Sync Copilot files if configured
-    if (projects.agents.includes('copilot')) {
-      const syncSpinner = ora('Sincronizando arquivos Copilot...').start();
-
-      const syncPairs = [
-        {
-          source: '.agents/rules/ownership.instructions.md',
-          target: '.github/instructions/ownership.instructions.md',
-          label: 'ownership rules',
-          transform: (content) => addCopilotFrontmatter(content, 'specs/**,docs/**,projects.yml,.agents/**')
-        },
-        {
-          source: '.agents/rules/hub_structure.instructions.md',
-          target: '.github/instructions/hub_structure.instructions.md',
-          label: 'structure rules',
-          transform: (content) => addCopilotFrontmatter(content, 'specs/**,docs/**,projects.yml')
-        },
-      ];
-
-      let synced = 0;
-      for (const { source, target, label, transform } of syncPairs) {
         try {
-          const sourceContent = await readFile(join(cwd, source), 'utf-8');
-          const targetContent = transform(sourceContent);
+          const sourceContent = await readFile(source, 'utf-8');
 
           let existingTarget = '';
           try {
-            existingTarget = await readFile(join(cwd, target), 'utf-8');
+            existingTarget = await readFile(target, 'utf-8');
           } catch { /* target doesn't exist yet */ }
 
-          if (existingTarget !== targetContent) {
-            syncSpinner.text = `Atualizando ${label}...`;
-            await mkdir(join(cwd, '.github/instructions'), { recursive: true });
-            await writeFile(join(cwd, target), targetContent);
+          if (existingTarget !== sourceContent) {
+            await mkdir(getGlobalPath('github', 'skills', skillName), { recursive: true });
+            await writeFile(target, sourceContent);
             synced++;
-            console.log(chalk.green(`    ✓ ${label} sincronizado`));
+            console.log(chalk.green(`    ✓ skill ${skillName} sincronizado`));
           }
         } catch (err) {
-          console.log(chalk.yellow(`    ⚠ Não foi possível sincronizar ${label}: ${err.message}`));
-        }
-      }
-
-      if (synced > 0) {
-        syncSpinner.succeed(`${synced} arquivo(s) Copilot atualizado(s)`);
-      } else {
-        syncSpinner.succeed('Arquivos Copilot já estão sincronizados');
-      }
-
-      // Sync skills: .agents/skills/*/SKILL.md → .github/skills/*/SKILL.md
-      const skillsSpinner = ora('Sincronizando skills...').start();
-      let skillsSynced = 0;
-      try {
-        const skillsDir = join(cwd, '.agents', 'skills');
-        const skillEntries = await readdir(skillsDir, { withFileTypes: true });
-        const skillDirs = skillEntries.filter(e => e.isDirectory()).map(e => e.name);
-
-        for (const skillName of skillDirs) {
-          const source = join(skillsDir, skillName, 'SKILL.md');
-          const target = join(cwd, '.github', 'skills', skillName, 'SKILL.md');
-
-          try {
-            const sourceContent = await readFile(source, 'utf-8');
-
-            let existingTarget = '';
-            try {
-              existingTarget = await readFile(target, 'utf-8');
-            } catch { /* target doesn't exist yet */ }
-
-            if (existingTarget !== sourceContent) {
-              await mkdir(join(cwd, '.github', 'skills', skillName), { recursive: true });
-              await writeFile(target, sourceContent);
-              skillsSynced++;
-              console.log(chalk.green(`    ✓ skill ${skillName} sincronizado`));
-            }
-          } catch (err) {
-            if (err.code !== 'ENOENT') {
-              console.log(chalk.yellow(`    ⚠ Não foi possível sincronizar skill ${skillName}: ${err.message}`));
-            }
+          if (err.code !== 'ENOENT') {
+            console.log(chalk.yellow(`    ⚠ Não foi possível sincronizar skill ${skillName}: ${err.message}`));
           }
         }
-
-        if (skillsSynced > 0) {
-          skillsSpinner.succeed(`${skillsSynced} skill(s) Copilot atualizado(s)`);
-        } else {
-          skillsSpinner.succeed('Skills Copilot já estão sincronizados');
-        }
-      } catch (err) {
-        if (err.code === 'ENOENT') {
-          skillsSpinner.warn('Diretório .agents/skills/ não encontrado — skills não sincronizados');
-        } else {
-          skillsSpinner.warn(`Erro ao sincronizar skills: ${err.message}`);
-        }
       }
-    }
-
-    // Check MCP configs
-    if (projects.agents.includes('claude')) {
-      try {
-        await access(join(cwd, '.mcp.json'));
-        console.log(chalk.green('  ✓ .mcp.json (Claude Code) encontrado'));
-      } catch {
-        console.log(chalk.yellow('  ✗ .mcp.json (Claude Code) ausente — crie manualmente'));
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        console.log(chalk.yellow('  ⚠ Diretório skills/ global não encontrado'));
       }
     }
 
-    if (projects.agents.includes('copilot')) {
-      try {
-        await access(join(cwd, '.vscode/mcp.json'));
-        console.log(chalk.green('  ✓ .vscode/mcp.json (Copilot) encontrado'));
-      } catch {
-        console.log(chalk.yellow('  ✗ .vscode/mcp.json (Copilot) ausente — execute init'));
-      }
-    }
+    // Sync agent hub
+    try {
+      const claudeAgent = await readFile(getGlobalPath('agents', 'spec-hub.agent.md'), 'utf-8');
+      const copilotAgentPath = getGlobalPath('github', 'agents', 'spec-hub.agent.md');
 
-    // Check for spec-hub agent divergence between Claude and Copilot
-    if (projects.agents.includes('claude') && projects.agents.includes('copilot')) {
+      // Copy Copilot version from templates (has extra frontmatter)
+      const copilotTemplate = join(TEMPLATES_DIR, 'github', 'agents', 'spec-hub.agent.md');
       try {
-        const claudeAgentRaw = await readFile(join(cwd, '.agents/agents/spec-hub.agent.md'), 'utf-8');
-        const copilotAgentRaw = await readFile(join(cwd, '.github/agents/spec-hub.agent.md'), 'utf-8');
-
-        // Strip frontmatter (--- ... ---) from both to compare functional content
-        const stripFrontmatter = (content) => content.replace(/^---\n[\s\S]*?\n---\n+/, '').trim();
-        const claudeBody = stripFrontmatter(claudeAgentRaw);
-        const copilotBody = stripFrontmatter(copilotAgentRaw);
-
-        if (claudeBody === copilotBody) {
-          console.log(chalk.green('  ✓ spec-hub agent sincronizado entre Claude e Copilot'));
-        } else {
-          console.log(chalk.yellow('  ⚠ spec-hub agent diverge entre Claude (.agents/) e Copilot (.github/)'));
-          console.log(chalk.dim('  Atualize manualmente: o conteúdo funcional diferente entre plataformas.'));
-          console.log(chalk.dim('  Claude: .agents/agents/spec-hub.agent.md'));
-          console.log(chalk.dim('  Copilot: .github/agents/spec-hub.agent.md'));
+        await access(copilotTemplate);
+        const copilotContent = await readFile(copilotTemplate, 'utf-8');
+        let existing = '';
+        try { existing = await readFile(copilotAgentPath, 'utf-8'); } catch { /* */ }
+        if (existing !== copilotContent) {
+          await mkdir(getGlobalPath('github', 'agents'), { recursive: true });
+          await writeFile(copilotAgentPath, copilotContent);
+          synced++;
+          console.log(chalk.green('    ✓ spec-hub agent (Copilot) sincronizado'));
         }
-      } catch {
-        console.log(chalk.yellow('  ⚠ Não foi possível verificar divergência dos agent files'));
-      }
+      } catch { /* template not found */ }
+    } catch { /* ignore */ }
+
+    if (synced > 0) {
+      syncSpinner.succeed(`${synced} arquivo(s) Copilot atualizado(s)`);
+    } else {
+      syncSpinner.succeed('Tudo já sincronizado');
     }
 
-    console.log('');
+    // Update version.json
+    try {
+      const pkgPath = join(__dirname, '..', '..', 'package.json');
+      const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+      await writeFile(getGlobalPath('version.json'), JSON.stringify({
+        version: pkg.version,
+        installedAt: new Date().toISOString(),
+      }, null, 2) + '\n');
+    } catch { /* ignore version write failure */ }
+
+    console.log(chalk.dim(`\n  Diretório global: ${GLOBAL_DIR}\n`));
 
   } catch (err) {
     spinner.fail(`Erro: ${err.message}`);
@@ -191,24 +161,6 @@ export async function updateCommand() {
 }
 
 function addCopilotFrontmatter(content, applyTo) {
-  // Remove existing frontmatter if present
   const withoutFrontmatter = content.replace(/^---\n[\s\S]*?\n---\n/, '');
   return `---\napplyTo: "${applyTo}"\n---\n\n${withoutFrontmatter.trim()}\n`;
 }
-
-/**
- * Parse projects.yml using the yaml package (robust — handles all valid YAML).
- */
-function parseProjectsYaml(content) {
-  try {
-    const data = yaml.parse(content);
-    const agents = data?.project?.agents;
-    return {
-      agents: Array.isArray(agents) ? agents : [],
-      preset: data?.project?.preset || 'standard',
-      name: data?.project?.name || '',
-    };
-  } catch {
-    return { agents: [], preset: 'standard', name: '' };
-  }
-}

package/src/schemas/spec.schema.js

@@ -457,7 +457,7 @@ export function rule21_taskReposMatchProjects(tasks, repoNames) {
  */
 export function rule22_auditReportClean(auditContent) {
   if (auditContent === null) {
-    return result(22, true, 'WARNING', `audit-report.md not found (generated by /spec)`);
+    return result(22, true, 'WARNING', `audit-report.md not found (generated by /osk-spec)`);
   }
   const hasFail = auditContent.includes('❌');
   return result(22, !hasFail, 'ERROR',
@@ -517,7 +517,7 @@ export function rule28_noUnresolvedMarkers(contents) {
   return result(28, unique.length === 0, 'ERROR',
     unique.length === 0
       ? `No unresolved markers found`
-      : `Unresolved markers found: ${unique.join(', ')} — resolve before /dev`,
+      : `Unresolved markers found: ${unique.join(', ')} — resolve before /osk-build`,
     unique.length > 0 ? unique : undefined,
   );
 }
@@ -624,7 +624,7 @@ export function rule33_openDecisions(architectureContent) {
   const blocking = [];
 
   for (const line of lines) {
-    if (/\|\s*aberta\s*\|/i.test(line) && /\/spec|\/dev/i.test(line)) {
+    if (/\|\s*aberta\s*\|/i.test(line) && /\/osk-spec|\/osk-build/i.test(line)) {
       const cells = line.split('|').map(c => c.trim()).filter(Boolean);
       blocking.push(cells[1] || line.trim());
     }

package/src/utils/global-path.js

@@ -0,0 +1,73 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { readFile } from 'fs/promises';
+
+export const GLOBAL_DIR_NAME = '.open-spec-kit';
+export const GLOBAL_DIR = join(homedir(), GLOBAL_DIR_NAME);
+
+export function getGlobalPath(...segments) {
+  return join(GLOBAL_DIR, ...segments);
+}
+
+export function getGlobalPathPosix(...segments) {
+  return getGlobalPath(...segments).replace(/\\/g, '/');
+}
+
+export function getGlobalEnvPath() {
+  return getGlobalPath('.env');
+}
+
+/**
+ * Parse a .env file into a key-value object.
+ * Handles comments, empty lines, and quoted values.
+ */
+export function parseEnvContent(content) {
+  const env = {};
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    let value = trimmed.slice(eqIdx + 1).trim();
+    // Strip surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * Read and parse the global .env file.
+ */
+export async function readGlobalEnv() {
+  const content = await readFile(getGlobalEnvPath(), 'utf-8');
+  return parseEnvContent(content);
+}
+
+/**
+ * Parse JSON that may contain comments (JSONC, used by VS Code settings).
+ * Respects quoted strings so URLs like "https://..." are not corrupted.
+ */
+export function parseJsonc(text) {
+  let result = '';
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === '"') {
+      const start = i++;
+      while (i < text.length && text[i] !== '"') { if (text[i] === '\\') i++; i++; }
+      result += text.slice(start, ++i);
+    } else if (text[i] === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+    } else if (text[i] === '/' && text[i + 1] === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i += 2;
+    } else {
+      result += text[i++];
+    }
+  }
+  return JSON.parse(result.replace(/,\s*([}\]])/g, '$1'));
+}

package/templates/agents/agents/spec-hub.agent.md

@@ -1,6 +1,6 @@
 ---
 name: spec-agent
-description: "Orquestra o ciclo de especificação: lê contexto do projeto, invoca as skills (/setup, /discovery, /spec, /dev) e coordena agents do Labs quando necessário."
+description: "Orquestra o ciclo de especificação: lê contexto do projeto, invoca as skills (/osk-init, /osk-discover, /osk-spec, /osk-build) e coordena agents do Labs quando necessário."
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -25,10 +25,10 @@ Nunca gere specs sem ter lido o acima.
 
 | Skill | Comando | O que faz |
 |-------|---------|-----------|
-| Setup | `/setup @space_key` ou `/setup @page_id` | Bootstrap do projeto a partir do Confluence |
-| Discovery | `/discovery` | Análise de demanda, Q&A com PO, gera PRD |
-| Spec | `/spec` | Quebra PRD em specs técnicas (brief, cenários, contratos, tasks) |
-| Dev | `/dev NNN` | Orquestra implementação (TDD, MR, security, docs vivas) |
+| Setup | `/osk-init @space_key` ou `/osk-init @page_id` | Bootstrap do projeto a partir do Confluence |
+| Discovery | `/osk-discover` | Análise de demanda, Q&A com PO, gera PRD |
+| Spec | `/osk-spec` | Quebra PRD em specs técnicas (brief, cenários, contratos, tasks) |
+| Dev | `/osk-build NNN` | Orquestra implementação (TDD, MR, security, docs vivas) |
 
 As instruções completas de cada skill estão em `.agents/skills/*/SKILL.md`.
 
@@ -36,7 +36,7 @@ As instruções completas de cada skill estão em `.agents/skills/*/SKILL.md`.
 
 | Responsabilidade | Quem faz |
 |-----------------|----------|
-| Specs (brief, scenarios, contracts, tasks, links) | **spec-agent** via `/spec` |
+| Specs (brief, scenarios, contracts, tasks, links) | **spec-agent** via `/osk-spec` |
 | ADRs (`docs/decisions/`) | **spec-agent** |
 | Design Document (DD) no Confluence | **`design-doc`** (Labs agent) — fallback: spec-agent via MCP direto |
 | Implementação de código | **`dotnet-engineer` / `nodejs-engineer` / `java-engineer`** (Labs) |
@@ -60,12 +60,12 @@ As instruções completas de cada skill estão em `.agents/skills/*/SKILL.md`.
 
 ```
 Projeto (Space ou página raiz)
-├── 🎯 Visão do Produto        ← /setup gera
-├── 📖 Glossário                ← /setup gera | /discovery e /dev atualizam
-├── 📐 DD (Design Document)     ← design-doc agent gera | /dev atualiza
+├── 🎯 Visão do Produto        ← /osk-init gera
+├── 📖 Glossário                ← /osk-init gera | /osk-discover e /osk-build atualizam
+├── 📐 DD (Design Document)     ← design-doc agent gera | /osk-build atualiza
 ├── Demandas/                   ← PO joga docs aqui
-├── 🚀 Features/                ← /setup cria | /discovery escreve dúvidas + PRD
-├── 🏛️ Domínio/                 ← /setup gera | /dev atualiza
+├── 🚀 Features/                ← /osk-init cria | /osk-discover escreve dúvidas + PRD
+├── 🏛️ Domínio/                 ← /osk-init gera | /osk-build atualiza
 │   ├── 📏 Regras
 │   ├── 🔀 Fluxos
 │   ├── 📊 Tabelas de Referência
@@ -82,8 +82,8 @@ specs/NNN-nome/
   scenarios.md               ← Given/When/Then (viram testes)
   tasks.md                   ← tarefas por repo
   links.md                   ← PRs + link da feature page
-  audit-report.md            ← resultado do self-review do /spec
-  conformance-report.json    ← validação pós-implementação do /dev
+  audit-report.md            ← resultado do self-review do /osk-spec
+  conformance-report.json    ← validação pós-implementação do /osk-build
   conformance-history.log    ← histórico de validações (append por run)
   openapi.yaml               ← stub OpenAPI 3.0 (opcional, se REST endpoints)
 ```

package/templates/agents/rules/hub_structure.instructions.md

@@ -24,7 +24,7 @@ applyTo: '**/*.md'
 
 1. Created: spec directory with brief + scenarios + contracts + tasks
 2. In progress: tasks are checked off, links.md tracks PRs
-3. Post-merge sync: if implementation diverged intentionally from spec, /dev updates contracts.md and scenarios.md to match reality (Phase D.1.5)
+3. Post-merge sync: if implementation diverged intentionally from spec, /osk-build updates contracts.md and scenarios.md to match reality (Phase D.1.5)
 4. Done: all tasks checked, spec directory stays (it IS the history)
 
 Specs are NOT archived or moved. The spec directory with checked tasks IS the record.