wizz-method 2.20.1 → 2.22.0

package/tools/hooks/wizz-sprint-archive-lib.js

@@ -0,0 +1,311 @@
+// wizz-sprint-archive-lib.js — arquivamento do sprint que `encerrar` fecha.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Copiado para `_wizz/hooks/`
+// junto com o wizz-feature.js (SUPPORT_FILES do installer). Não é hook.
+//
+// Planeja tudo antes de tocar no disco e aplica com desfazer: o encerrar do
+// Lucrare (2026-10-19) quebrou com ENOTDIR no meio, num sprint reaberto cujo
+// nome já existia em `_arquivo/<slug>/`, e deixou metade movida.
+//
+//   1. Planejar: os moves (mesclando com o arquivo morto; arquivo de mesmo
+//      nome e conteúdo diferente vai para o lado como `<nome>.anterior-<data>`,
+//      idêntico só some da origem), o dono do `sprint-status.yaml` da raiz, os
+//      links dos `.md` do sprint e as referências de fora (CLAUDE.md, roteiros,
+//      html de design). Código e config de fora só são listados, nunca editados.
+//   2. Aplicar: edições, depois moves. Qualquer erro desfaz o que já foi feito,
+//      na ordem inversa, e relança.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const lib = require('./wizz-feature-lib.js');
+const { walkText } = require('./wizz-arrumar.js');
+
+const STATUS_FILE = 'sprint-status.yaml';
+// Texto de gente: a referência ao sprint é reescrita. Código, json e yaml de
+// fora são só listados (reescrever import ou config às cegas quebra build).
+const MARKDOWN_EXT = new Set(['.md', '.mdx', '.markdown']);
+const REWRITE_EXT = new Set([...MARKDOWN_EXT, '.txt', '.html', '.htm']);
+
+function escapeRe(s) {
+  return s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+const toPosix = (p) => p.split(path.sep).join('/');
+
+function sameContent(a, b) {
+  try {
+    return fs.readFileSync(a).equals(fs.readFileSync(b));
+  } catch {
+    return false;
+  }
+}
+
+/** `spec-x.md` → `spec-x.anterior-<data>.md`, com sufixo -2, -3... se já existir. */
+function asideName(dest, taken) {
+  const dir = path.dirname(dest);
+  const base = path.basename(dest);
+  const dot = base.lastIndexOf('.');
+  const [stem, ext] = dot > 0 ? [base.slice(0, dot), base.slice(dot)] : [base, ''];
+  for (let n = 1; ; n++) {
+    const candidate = path.join(dir, `${stem}.anterior-${lib.today()}${n > 1 ? `-${n}` : ''}${ext}`);
+    if (!fs.existsSync(candidate) && !taken.has(candidate)) {
+      taken.add(candidate);
+      return candidate;
+    }
+  }
+}
+
+/** Planeja levar `src` para `dest`, mesclando com o que o arquivo morto já tem. */
+function planTree(src, dest, plan) {
+  if (!fs.existsSync(dest)) {
+    plan.renames.push({ from: src, to: dest });
+    return;
+  }
+  const srcIsDir = fs.lstatSync(src).isDirectory();
+  const destIsDir = fs.lstatSync(dest).isDirectory();
+  if (srcIsDir && destIsDir) {
+    for (const name of fs.readdirSync(src)) planTree(path.join(src, name), path.join(dest, name), plan);
+    plan.emptied.push(src);
+    return;
+  }
+  if (!srcIsDir && !destIsDir && sameContent(src, dest)) {
+    plan.duplicates.push(src);
+    return;
+  }
+  plan.asides.push({ from: dest, to: asideName(dest, plan.taken) });
+  plan.renames.push({ from: src, to: dest });
+}
+
+function markdownFiles(dir) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.flatMap((e) => {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) return markdownFiles(abs);
+    return e.isFile() && e.name.endsWith('.md') ? [abs] : [];
+  });
+}
+
+/** Valor cru de `chave:` no topo de um yaml simples (sem parser: o hook não tem dependência). */
+function yamlTopValue(text, key) {
+  const m = new RegExp(String.raw`^${key}:\s*(.*)$`, 'm').exec(text);
+  return m
+    ? m[1]
+        .replace(/\s+#.*$/, '')
+        .replaceAll(/^["']|["']$/g, '')
+        .trim()
+    : '';
+}
+
+/** Chaves de `development_status:` (stories, épicos, retros). */
+function statusKeys(text) {
+  const lines = text.split('\n');
+  const head = lines.findIndex((l) => /^development_status:\s*$/.test(l));
+  if (head === -1) return [];
+  const keys = [];
+  for (let i = head + 1; i < lines.length && (/^\s/.test(lines[i]) || !lines[i].trim()); i++) {
+    const m = /^\s+([\w.-]+):/.exec(lines[i]);
+    if (m) keys.push(m[1]);
+  }
+  return keys;
+}
+
+function openSprints(dirs) {
+  const names = new Set();
+  for (const base of [dirs.planning, dirs.implementation]) {
+    try {
+      for (const e of fs.readdirSync(base, { withFileTypes: true })) if (e.isDirectory() && e.name !== lib.ARCHIVE_DIR) names.add(e.name);
+    } catch {
+      // pasta de artefato ainda não existe
+    }
+  }
+  return [...names];
+}
+
+/**
+ * De quem é o `sprint-status.yaml` da raiz da implementação. Só vai junto
+ * quando é do sprint que fecha; na dúvida fica (e a linha avisa).
+ * @returns {{owned: boolean, motivo: string}}
+ */
+function statusOwnership(root, slug, dirs, file) {
+  if (fs.existsSync(path.join(dirs.implementation, slug, STATUS_FILE)))
+    return { owned: false, motivo: `o sprint já tem o dele em ${slug}/${STATUS_FILE}` };
+  const text = fs.readFileSync(file, 'utf8');
+  const declared = lib.toSlug(yamlTopValue(text, 'feature') || yamlTopValue(text, 'sprint'));
+  if (declared) return declared === slug ? { owned: true, motivo: '' } : { owned: false, motivo: `declara o sprint ${declared}` };
+  const location = yamlTopValue(text, 'story_location');
+  if (location) {
+    const abs = lib.resolveConfigPath(location, root, location);
+    const sprint = path.relative(dirs.implementation, abs).split(path.sep)[0];
+    if (sprint && sprint !== '..' && sprint !== '' && !path.isAbsolute(sprint) && path.relative(dirs.implementation, abs) !== '')
+      return sprint === slug ? { owned: true, motivo: '' } : { owned: false, motivo: `story_location aponta ${sprint}` };
+  }
+  const sprints = openSprints(dirs);
+  const hasStory = (sprint, key) => fs.existsSync(path.join(dirs.implementation, sprint, `${key}.md`));
+  const keys = statusKeys(text);
+  const owners = new Set(sprints.filter((s) => keys.some((k) => hasStory(s, k))));
+  if (owners.size === 1)
+    return owners.has(slug) ? { owned: true, motivo: '' } : { owned: false, motivo: `as stories são de ${[...owners][0]}` };
+  if (owners.size > 1) return { owned: false, motivo: `as stories são de ${[...owners].join(', ')}` };
+  const others = sprints.filter((s) => s !== slug);
+  return others.length === 0
+    ? { owned: true, motivo: '' }
+    : { owned: false, motivo: `dono incerto (sprints abertos: ${others.join(', ')})` };
+}
+
+/**
+ * Referências de fora do sprint. Texto de gente é reescrito (link relativo
+ * de markdown + caminho a partir da raiz); o resto que ainda cita a pasta
+ * velha volta como lista.
+ */
+function planExternalRefs(root, moves, mapAbs, pending) {
+  const skip = moves.map((m) => m.src);
+  try {
+    for (const e of fs.readdirSync(root, { withFileTypes: true }))
+      if (e.isDirectory() && e.name.startsWith('.')) skip.push(path.join(root, e.name));
+  } catch {
+    // raiz ilegível: sem referências externas
+  }
+  const prefixes = moves.map((m) => ({
+    re: new RegExp(String.raw`(?<![\w-])${escapeRe(toPosix(path.relative(root, m.src)))}(?![\w.-])`, 'g'),
+    to: toPosix(path.relative(root, m.dest)),
+  }));
+  const segments = moves.map(
+    (m) => new RegExp(String.raw`(?<![\w-])${escapeRe(`${path.basename(path.dirname(m.src))}/${path.basename(m.src)}`)}(?![\w.-])`),
+  );
+  const listed = [];
+  for (const file of walkText(root, skip)) {
+    const text = pending.get(file) ?? fs.readFileSync(file, 'utf8');
+    const ext = path.extname(file).toLowerCase();
+    const isMarkdown = MARKDOWN_EXT.has(ext);
+    if (!isMarkdown && !segments.some((re) => re.test(text))) continue;
+    let next = text;
+    if (isMarkdown) next = lib.rebaseMarkdownLinks(next, path.dirname(file), path.dirname(file), mapAbs, { onlyMoved: true });
+    if (REWRITE_EXT.has(ext)) for (const { re, to } of prefixes) next = next.replace(re, to);
+    if (next !== text) pending.set(file, next);
+    if (segments.some((re) => re.test(next))) listed.push(path.relative(root, file));
+  }
+  return listed;
+}
+
+/**
+ * Planeja o arquivamento sem tocar no disco.
+ * @param {string} root
+ * @param {string} slug
+ * @param {{edits?: Map<string, string>}} [opts] - edições já decididas (a spec com o status final)
+ */
+function planArchive(root, slug, { edits = new Map() } = {}) {
+  const dirs = lib.artifactDirs(root);
+  const pending = new Map(edits);
+  const moves = [dirs.planning, dirs.implementation].map((base) => ({
+    src: path.join(base, slug),
+    dest: path.join(base, lib.ARCHIVE_DIR, slug),
+  }));
+  const mapAbs = (abs) => {
+    const hit = moves.find((m) => abs === m.src || abs.startsWith(m.src + path.sep));
+    return hit ? hit.dest + abs.slice(hit.src.length) : abs;
+  };
+  const plan = { renames: [], asides: [], duplicates: [], emptied: [], taken: new Set(), pending, moves, status: null, externas: [] };
+
+  // Links relativos (`../`) descem um nível junto com o arquivo.
+  for (const { src } of moves) {
+    for (const file of markdownFiles(src)) {
+      const text = pending.get(file) ?? fs.readFileSync(file, 'utf8');
+      const next = lib.rebaseMarkdownLinks(text, path.dirname(file), path.dirname(mapAbs(file)), mapAbs);
+      if (next !== text) pending.set(file, next);
+    }
+  }
+  plan.externas = planExternalRefs(root, moves, mapAbs, pending);
+  for (const { src, dest } of moves) if (fs.existsSync(src)) planTree(src, dest, plan);
+
+  const status = path.join(dirs.implementation, STATUS_FILE);
+  if (fs.existsSync(status)) {
+    const { owned, motivo } = statusOwnership(root, slug, dirs, status);
+    const dest = path.join(moves[1].dest, STATUS_FILE);
+    plan.status = { file: status, dest, owned, motivo };
+    if (owned) {
+      plan.externas = plan.externas.filter((f) => path.join(root, f) !== status);
+      if (fs.existsSync(dest) || plan.renames.some((r) => r.to === dest)) plan.asides.push({ from: dest, to: asideName(dest, plan.taken) });
+      plan.renames.push({ from: status, to: dest });
+    }
+  }
+  return plan;
+}
+
+/** mkdir -p que devolve o desfazer (só as pastas que ele criou). */
+function mkdirTracked(dir, undo) {
+  const first = fs.mkdirSync(dir, { recursive: true });
+  if (!first) return;
+  const created = [];
+  for (let d = dir; ; d = path.dirname(d)) {
+    created.push(d);
+    if (d === first || path.dirname(d) === d) break;
+  }
+  undo.push(() => {
+    for (const d of created) fs.rmdirSync(d);
+  });
+}
+
+/**
+ * Aplica o plano. Erro no meio desfaz tudo na ordem inversa e relança.
+ * @returns {{asides: string[]}}
+ */
+function applyArchive(plan) {
+  const undo = [];
+  const rename = (from, to) => {
+    mkdirTracked(path.dirname(to), undo);
+    fs.renameSync(from, to);
+    undo.push(() => fs.renameSync(to, from));
+  };
+  try {
+    for (const [file, text] of plan.pending) {
+      const before = fs.existsSync(file) ? fs.readFileSync(file) : null;
+      mkdirTracked(path.dirname(file), undo);
+      fs.writeFileSync(file, text);
+      undo.push(() => (before === null ? fs.unlinkSync(file) : fs.writeFileSync(file, before)));
+    }
+    // O que já está no arquivo morto vai para o lado antes de o novo chegar.
+    for (const { from, to } of plan.asides) rename(from, to);
+    for (const { from, to } of plan.renames) rename(from, to);
+    for (const file of plan.duplicates) {
+      const content = fs.readFileSync(file);
+      fs.unlinkSync(file);
+      undo.push(() => fs.writeFileSync(file, content));
+    }
+    // Mais fundo primeiro: a pasta-mãe só esvazia depois das filhas.
+    for (const dir of [...plan.emptied].sort((a, b) => b.length - a.length)) {
+      fs.rmdirSync(dir);
+      undo.push(() => fs.mkdirSync(dir));
+    }
+  } catch (error) {
+    const failures = [];
+    for (const step of undo.toReversed()) {
+      try {
+        step();
+      } catch (undoError) {
+        failures.push(undoError.message);
+      }
+    }
+    error.desfeito = failures.length === 0;
+    if (failures.length > 0) error.message += ` (desfazer incompleto: ${failures.join('; ')})`;
+    throw error;
+  }
+  return { asides: plan.asides.map((a) => a.to) };
+}
+
+/**
+ * O sprint já foi fechado: nenhuma pasta aberta e o arquivo morto existe.
+ * @param {string} root
+ * @param {string} slug
+ */
+function isArchived(root, slug) {
+  const dirs = lib.artifactDirs(root);
+  const bases = [dirs.planning, dirs.implementation];
+  return !bases.some((b) => fs.existsSync(path.join(b, slug))) && bases.some((b) => fs.existsSync(path.join(b, lib.ARCHIVE_DIR, slug)));
+}
+
+module.exports = { planArchive, applyArchive, isArchived, statusOwnership, asideName, STATUS_FILE };

package/tools/installer/core/hooks-settings.js

@@ -66,6 +66,7 @@ const SUPPORT_FILES = [
   'wizz-layout-lib.js',
   'wizz-cerebro-lib.js',
   'wizz-debug-lib.js',
+  'wizz-sprint-archive-lib.js',
   'wizz-feature.js',
   'wizz-arrumar.js',
 ];

package/tools/installer/core/installer.js

@@ -24,6 +24,7 @@ const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
 const { applyProjectInstructions, removeProjectInstructions } = require('./project-instructions');
 const userFilePreservation = require('./user-file-preservation');
 const moduleConfigWriter = require('./module-config-writer');
+const { absoluteOutputFolder } = require('../modules/core-seed');
 const helpCatalog = require('./help-catalog');
 const quickUpdateModule = require('./quick-update');
 
@@ -295,6 +296,11 @@ class Installer {
   ) {
     const isQuickUpdate = config.isQuickUpdate();
     const moduleConfigs = officialModules.moduleConfigs;
+    // Quick update copies the prior answers verbatim: a relative output_folder
+    // left by 2.20.1 heals here, before any config file is written.
+    if (moduleConfigs.core?.output_folder) {
+      moduleConfigs.core = { ...moduleConfigs.core, output_folder: absoluteOutputFolder(moduleConfigs.core.output_folder) };
+    }
 
     const dirResults = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
     // Set true inside configTask the moment the A14 tmp→real swap actually

package/tools/installer/modules/core-seed.js

@@ -0,0 +1,72 @@
+/**
+ * Semente do [core] para os caminhos sem pergunta (`--yes`, flags de linha
+ * de comando e o install guiado), fora do ui.js.
+ *
+ * Duas regras que o sync da 2.20.1 quebrou no Lucrare (2026-10-19):
+ *   1. Reinstalar nunca troca uma resposta já dada. O caminho `--yes` lia as
+ *      respostas antigas de `collectedConfig.core` (vazio àquela altura) em
+ *      vez do armazém do `loadExistingConfig`, e caía nos defaults fixos:
+ *      `user_name` virava o login da máquina e o idioma virava English.
+ *   2. `output_folder` é sempre `{project-root}/<pasta>`, igual ao `result:`
+ *      do core/module.yaml e a planning/implementation. Valor cru (default
+ *      fixo, `--output-folder`, install guiado) pulava o template e gravava
+ *      relativo; skills que trocam `{output_folder}` literal escreviam
+ *      relativo ao cwd (worktrees em `.claude/worktrees/`).
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+
+const PROJECT_ROOT = '{project-root}';
+
+/**
+ * `_wizz-output` → `{project-root}/_wizz-output`. Valor que já começa com
+ * `{project-root}` ou é absoluto fica como está.
+ * @param {string} value
+ * @returns {string}
+ */
+function absoluteOutputFolder(value) {
+  if (typeof value !== 'string' || !value.trim()) return value;
+  const raw = value.trim();
+  if (raw.startsWith(PROJECT_ROOT) || path.isAbsolute(raw)) return raw;
+  const clean = raw.replace(/^\.\//, '').replaceAll('\\', '/').replace(/\/+$/, '');
+  return `${PROJECT_ROOT}/${clean}`;
+}
+
+function systemUsername() {
+  let name;
+  try {
+    name = os.userInfo().username;
+  } catch {
+    name = process.env.USER || process.env.USERNAME || 'User';
+  }
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/**
+ * Defaults do [core] para um install do zero com `--yes`.
+ * {directory_name} default per src/core-skills/module.yaml — matches what the
+ * interactive flow resolves via buildQuestion()'s {directory_name} placeholder.
+ * @param {string} directory
+ */
+function defaultCoreConfig(directory) {
+  return {
+    user_name: systemUsername(),
+    project_name: path.basename(directory),
+    communication_language: 'English',
+    document_output_language: 'English',
+    output_folder: absoluteOutputFolder('_wizz-output'),
+  };
+}
+
+/**
+ * O [core] da instalação anterior, como o `loadExistingConfig` leu
+ * (config.toml + config.user.toml). `{}` sem instalação.
+ * @param {{_existingConfig?: Record<string, Record<string, unknown>> | null}} collector
+ */
+function existingCoreConfig(collector) {
+  const core = collector && collector._existingConfig && collector._existingConfig.core;
+  return core && typeof core === 'object' && !Array.isArray(core) ? { ...core } : {};
+}
+
+module.exports = { absoluteOutputFolder, defaultCoreConfig, existingCoreConfig };

package/tools/installer/modules/mcp-config.js

@@ -54,6 +54,9 @@ function resolveMcps(registry, selectedAreas) {
       // verify it boots. Carried here so prepareMcps() can act on it; dropped
       // from what toServerConfig() writes (it never belongs in .mcp.json).
       setup: mcp.setup || null,
+      // `optional` (2026-10-24): the UI leaves it UNCHECKED in the multiselect,
+      // so it is only recommended unless the user picks it explicitly.
+      optional: mcp.optional === true,
     }),
   });
 }

package/tools/installer/ui.js

@@ -28,6 +28,7 @@ const { resolveMcps, partitionGloballyConfigured } = require('./modules/mcp-conf
 const { resolveClis, detectClis } = require('./modules/cli-config');
 const prompts = require('./prompts');
 const { parseSetEntries } = require('./set-overrides');
+const { absoluteOutputFolder, defaultCoreConfig, existingCoreConfig } = require('./modules/core-seed');
 const { isGuidedEligible, runGuidedInstall } = require('./guided/flow');
 const guidedSteps = require('./guided/steps');
 const { normalizeLang, t: guidedT } = require('./guided/messages');
@@ -739,11 +740,13 @@ class UI {
     const selected = await prompts.multiselect({
       message: options.mcpMessage || it('mcpQuestion'),
       options: resolved.map((m) => ({
-        label: m.id,
+        label: m.optional ? `${m.id} (opcional)` : m.id,
         value: m.id,
         hint: m.when,
       })),
-      initialValues: resolved.map((m) => m.id),
+      // Entries flagged `optional` in the registry start unchecked: they are
+      // recommended, never written to .mcp.json without an explicit pick.
+      initialValues: resolved.filter((m) => !m.optional).map((m) => m.id),
       required: false,
     });
 
@@ -1239,14 +1242,16 @@ class UI {
         if (!options.quiet) await prompts.log.info(`Using document output language from command-line: ${options.documentOutputLanguage}`);
       }
       if (options.outputFolder) {
-        coreConfig.output_folder = options.outputFolder;
+        coreConfig.output_folder = absoluteOutputFolder(options.outputFolder);
         if (!options.quiet) await prompts.log.info(`Using output folder from command-line: ${options.outputFolder}`);
       }
 
-      // Load existing config to merge with provided options
+      // Load existing config to merge with provided options: a flag changes
+      // only its own key, the other prior answers stay.
       await configCollector.loadExistingConfig(directory);
-      const existingConfig = configCollector.collectedConfig.core || {};
-      configCollector.collectedConfig.core = { ...existingConfig, ...coreConfig };
+      const merged = { ...existingCoreConfig(configCollector), ...coreConfig };
+      if (merged.output_folder) merged.output_folder = absoluteOutputFolder(merged.output_folder);
+      configCollector.collectedConfig.core = merged;
 
       // If not all options are provided, collect the missing ones interactively (unless --yes flag)
       if (
@@ -1256,27 +1261,12 @@ class UI {
         await configCollector.collectModuleConfig('core', directory, false, true);
       }
     } else if (options.yes) {
-      // Use all defaults when --yes flag is set
+      // Use all defaults when --yes flag is set. With a prior install, core is
+      // NOT seeded here: collectAllConfigurations collects it with the prior
+      // answers as defaults (reinstall never changes config.user.toml).
       await configCollector.loadExistingConfig(directory);
-      const existingConfig = configCollector.collectedConfig.core || {};
-
-      if (Object.keys(existingConfig).length === 0) {
-        let safeUsername;
-        try {
-          safeUsername = os.userInfo().username;
-        } catch {
-          safeUsername = process.env.USER || process.env.USERNAME || 'User';
-        }
-        const defaultUsername = safeUsername.charAt(0).toUpperCase() + safeUsername.slice(1);
-        configCollector.collectedConfig.core = {
-          user_name: defaultUsername,
-          // {directory_name} default per src/core-skills/module.yaml — matches what the
-          // interactive flow resolves via buildQuestion()'s {directory_name} placeholder.
-          project_name: path.basename(directory),
-          communication_language: 'English',
-          document_output_language: 'English',
-          output_folder: '_wizz-output',
-        };
+      if (Object.keys(existingCoreConfig(configCollector)).length === 0) {
+        configCollector.collectedConfig.core = defaultCoreConfig(directory);
         if (!options.quiet) await prompts.log.info('Using default configuration (--yes flag)');
       }
     }