@spec-wave/cli 0.34.0 → 0.34.2

package/package.json

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

package/src/commands/decompose.mjs

@@ -36,7 +36,7 @@ import { resolveDocDir } from '../lib/doc-paths.mjs';
 import { docBlobUrl } from '../lib/repo-links.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
-import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { executionMode, missingRootMessage, resolveFlowContext } from '../lib/flow-run.mjs';
 import { publishArtifact } from '../lib/artifact-publish.mjs';
 import { buildDependencyMap, storiesFromAppliedDoc, DEPENDENCY_MAP_FILE } from '../lib/dependency-map.mjs';
 import { invalidateCache } from '../lib/net-cache.mjs';
@@ -1136,6 +1136,7 @@ export async function decompose({ issueNumber, apply }) {
 
   // Config do repo: raiz para os caminhos de documento e escalada da crítica.
   const { config, root } = loadConfig();
+  if (!root) throw new Error(missingRootMessage('decompose', executionMode()));
   const { rel: docRel } = resolveDocDir(root, issue, type);
 
   // Branch base: é dela que os documentos são lidos quando não estão no clone, e

package/src/commands/generate-bug.mjs

@@ -52,7 +52,7 @@ export async function generateBug({ issueNumber }) {
   // Mesmo contexto dos outros geradores: GITHUB_REPOSITORY quando existe, o
   // `.spec-wave.json` quando não. Este comando exigia a env crua e morria fora
   // do runner mandando exportá-la — dentro de um repo que já sabe seu owner/repo.
-  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-bug' });
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-bug', requireRoot: true });
   const n = parseInt(issueNumber, 10);
 
   console.log(`Buscando issue #${n}...`);

package/src/commands/generate-plan.mjs

@@ -132,7 +132,7 @@ async function critiquePlan({
 export async function generatePlan({ issueNumber }) {
   const token = await resolveToken();
   // Roda nos dois modos: no Action (disparado por label) e na sessão local.
-  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-plan' });
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-plan', requireRoot: true });
   console.log(`Modo de execução: ${mode}`);
 
   console.log(`Buscando issue #${issueNumber}...`);
@@ -384,7 +384,7 @@ export async function critique({ issueNumber, file, kind, failOnGrave = false })
   }
 
   const token = await resolveToken();
-  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'critique' });
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'critique', requireRoot: true });
   console.log(`Modo de execução: ${mode}`);
 
   const n = parseInt(issueNumber, 10);

package/src/commands/generate-qa-plan.mjs

@@ -27,7 +27,7 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { resolveDocDir } from '../lib/doc-paths.mjs';
 import { docBlobUrl } from '../lib/repo-links.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
-import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { executionMode, missingRootMessage, resolveFlowContext } from '../lib/flow-run.mjs';
 import { publishArtifact } from '../lib/artifact-publish.mjs';
 import { loadArtifact, isAwaitingMerge } from '../lib/doc-source.mjs';
 import { awaitingMergeBlock, renderPrLine } from '../lib/artifact-pr.mjs';
@@ -121,6 +121,7 @@ export async function generateQaPlan({ issueNumber }) {
   }
 
   const { config, root } = loadConfig();
+  if (!root) throw new Error(missingRootMessage('generate-qa-plan', executionMode()));
   const { rel: dirRel } = resolveDocDir(root, issue, type);
   const docRel = `${dirRel}/${QA_PLAN_FILE}`;
   const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);

package/src/commands/generate-spec.mjs

@@ -32,7 +32,7 @@ function formatLintWarning(lintFindings) {
 export async function generateSpec({ issueNumber }) {
   const token = await resolveToken();
   // Roda nos dois modos: no Action (disparado por label) e na sessão local.
-  const { owner, repo, root, mode } = resolveFlowContext({ command: 'generate-spec' });
+  const { owner, repo, root, mode } = resolveFlowContext({ command: 'generate-spec', requireRoot: true });
   console.log(`Modo de execução: ${mode}`);
 
   console.log(`Buscando issue #${issueNumber}...`);

package/src/lib/flow-run.mjs

@@ -43,9 +43,14 @@ export function executionMode(env = process.env) {
  * @param {string} [opts.cwd]
  * @param {string} [opts.command] nome do comando, para a mensagem de erro
  * @param {object} [opts.env]
+ * @param {boolean} [opts.requireRoot] comandos que ancoram caminhos/prompts na
+ *        raiz devem exigi-la: sem isto um repo nunca inicializado (checkout
+ *        dos Actions sem .spec-wave.json) seguia com root=null e morria três
+ *        chamadas depois com `path.join(null, …)` — "The path argument must
+ *        be of type string. Received null" (caso real, 2026-09-06).
  * @returns {{owner: string, repo: string, root: string|null, config: object|null, mode: 'actions'|'local'}}
  */
-export function resolveFlowContext({ cwd = process.cwd(), command = 'este comando', env = process.env } = {}) {
+export function resolveFlowContext({ cwd = process.cwd(), command = 'este comando', env = process.env, requireRoot = false } = {}) {
   // Repassa o `env` recebido: sem isso o modo local fica intestável dentro do
   // GitHub Actions, que define GITHUB_REPOSITORY em toda execução.
   const { owner, repo, root, config } = resolveRepoContext(cwd, env);
@@ -61,5 +66,26 @@ export function resolveFlowContext({ cwd = process.cwd(), command = 'este comand
           `  GITHUB_REPOSITORY=owner/repo spec-wave ${command} --issue-number 1`)
     );
   }
+  if (requireRoot && !root) {
+    throw new Error(missingRootMessage(command, mode));
+  }
   return { owner, repo, root, config, mode };
 }
+
+/**
+ * Mensagem de "repositório não inicializado" — compartilhada com os comandos
+ * que resolvem a raiz via loadConfig() direto (decompose, generate-qa-plan).
+ *
+ * @param {string} command
+ * @param {'actions'|'local'} mode
+ * @returns {string}
+ */
+export function missingRootMessage(command, mode) {
+  return (
+    `${CONFIG_FILE} não encontrado — spec-wave ${command} precisa da raiz do projeto.\n` +
+    (mode === 'actions'
+      ? `Este repositório ainda não foi inicializado para o spec-wave: rode \`spec-wave init\` ` +
+        `no repositório e commite o ${CONFIG_FILE}.`
+      : `Rode \`spec-wave init\` na raiz do repositório primeiro.`)
+  );
+}

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.34.0",
+  "version": "0.34.2",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",

package/src/templates/workflows/code-review.yml

@@ -35,8 +35,8 @@ jobs:
     outputs:
       feature: ${{ steps.resolve.outputs.feature }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 
@@ -69,9 +69,9 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/critique.yml

@@ -39,11 +39,11 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/decompose.yml

@@ -70,11 +70,11 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/generate-bug.yml

@@ -54,11 +54,11 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/generate-plan.yml

@@ -64,11 +64,11 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/generate-qa-plan.yml

@@ -41,11 +41,11 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/generate-spec.yml

@@ -64,11 +64,11 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/qa.yml

@@ -44,9 +44,9 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'
 

package/src/templates/workflows/validate.yml

@@ -38,9 +38,9 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: '24'