@brunosps00/dev-workflow 1.1.2 → 1.2.0

package/scaffold/pt-br/commands/dw-skill-health.md

@@ -10,8 +10,10 @@ Voce e o auditor de saude de skills e agentes do dev-workflow.
 1. Leia `scaffold/skill-registry.json` ao auditar o repo dev-workflow, ou `.dw/skill-registry.json` + `.agents/skills/` em projetos consumidores.
 2. Agrupe skills por `kind`: `protocol`, `domain-pack`, `recipe-pack`, `asset-pack`.
 3. Valide que toda skill tem trigger, output esperado, owner, load policy e limite de contexto.
-4. Aponte nomes duplicados, `SKILL.md` ausente, frontmatter ausente, `SKILL.md` grande demais, e references/assets lidos sem trigger especifico.
-5. Recomende manter, compactar entrypoint, mesclar, reclassificar, ou remover da visibilidade core.
+4. Valide que todo `SKILL.md` bundled tem contrato `## Structured Return` com `Status`, `Scope`, `Evidence`, `Artifacts`, `Decisions`, `Risks` e `Next Step`.
+5. Confirme que o vocabulario de `Status` esta explicito: `PASS`, `FINDINGS`, `BLOCKED`, `NOT_APPLICABLE`.
+6. Aponte nomes duplicados, `SKILL.md` ausente, frontmatter ausente, `SKILL.md` grande demais, metadata de output esperado desatualizada, e references/assets lidos sem trigger especifico.
+7. Recomende manter, compactar entrypoint, mesclar, reclassificar, adicionar retorno estruturado, ou remover da visibilidade core.
 
 ## Taxonomia
 
@@ -23,7 +25,13 @@ Voce e o auditor de saude de skills e agentes do dev-workflow.
 `SKILL.md` deve ser um roteador/protocolo curto. Regras longas, exemplos, paletas, receitas, services e assets ficam em references/assets/rules/recipes e sao carregados sob demanda.
 
 ## Saida
-Retorne um relatorio conciso. Nao delete arquivos.
+Retorne um relatorio conciso com uma secao de retorno estruturado. Nao delete arquivos.
+
+Inclua:
+- Status geral: `PASS`, `FINDINGS` ou `BLOCKED`.
+- Issues de registry/schema.
+- Cobertura de retorno estruturado, incluindo qualquer skill sem contrato ou vocabulario de status.
+- Top 3 fixes.
 
 Marcador final: `## SKILL-HEALTH COMPLETE`
 </system_instructions>

package/scaffold/pt-br/references/refactoring-catalog.md

@@ -1,6 +1,6 @@
 # Catálogo de Refatoração — Exemplos Antes/Depois
 
-Referência para `/dw-brainstorm --refactor`. Baseado no catálogo de Fowler.
+Referência para `/dw-refactor` e `/dw-brainstorm --mode=refactor-audit`. Baseado no catálogo de Fowler.
 
 ## 1. Função Longa → Extract Function
 

package/scaffold/pt-br/templates/constitution-template.md

@@ -71,7 +71,7 @@ mode: defaults | custom
 **P-008 — Queries N+1 são flagueadas em code review** (severity: info)
 **Regra:** Loops ou operações em lista que disparam chamadas DB/HTTP por item devem batchar (ex: `IN (...)`, `findMany`, DataLoader) ou ser explicitamente justificadas.
 **Why:** Padrões N+1 escalam linearmente com tamanho dos dados e silenciosamente degradam até que a carga de produção revele.
-**Enforcement:** `dw-code-review` e `dw-refactoring-analysis` detectam padrões await-em-loop contra módulos de repository / API client.
+**Enforcement:** `/dw-review` e `/dw-refactor` detectam padrões await-em-loop contra módulos de repository / API client.
 
 ---
 

package/scaffold/scripts/cdp-relay/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cdp-relay"
 version = "0.1.0"
 edition = "2021"
-description = "Tiny TCP forwarder so WSL can reach a Windows browser's CDP debug port in NAT mode. Source for the prebuilt dev-workflow relay; no runtime dependency."
+description = "Tiny forward/reverse TCP relay so WSL can reach a Windows browser's CDP debug port in NAT mode without admin setup."
 
 [[bin]]
 name = "cdp-relay"

package/scaffold/scripts/cdp-relay/src/main.rs

@@ -1,15 +1,20 @@
 //! cdp-relay — a tiny TCP forwarder.
 //!
-//! Listens on 0.0.0.0:<listen> and forwards every connection to 127.0.0.1:<target>.
-//! dev-workflow runs this on the Windows side so WSL (NAT networking) can reach a Windows
-//! browser's CDP remote-debugging port, which Chromium binds to loopback only. std-only:
-//! no crates, no runtime. dev-workflow ships a prebuilt Windows x64 .exe; this source is
-//! kept for maintainers who need to rebuild it.
+//! Default mode listens on 0.0.0.0:<listen> and forwards every connection to
+//! 127.0.0.1:<target>. Reverse mode connects outbound to a WSL broker, then forwards
+//! each broker-approved session to 127.0.0.1:<target>. dev-workflow uses reverse mode
+//! on WSL NAT so no Windows admin/firewall rule is required. std-only: no crates, no
+//! runtime. dev-workflow ships a prebuilt Windows x64 .exe; this source is kept for
+//! maintainers who need to rebuild it.
 
 use std::env;
-use std::io;
+use std::io::{self, Read};
 use std::net::{Shutdown, TcpListener, TcpStream};
 use std::thread;
+use std::time::Duration;
+
+const DEFAULT_REVERSE_POOL: usize = 8;
+const RETRY_DELAY: Duration = Duration::from_millis(200);
 
 fn pump(mut from: TcpStream, mut to: TcpStream) {
     let _ = io::copy(&mut from, &mut to);
@@ -17,29 +22,36 @@ fn pump(mut from: TcpStream, mut to: TcpStream) {
     let _ = to.shutdown(Shutdown::Write);
 }
 
+fn bridge(left: TcpStream, right: TcpStream) -> io::Result<()> {
+    left.set_nodelay(true).ok();
+    right.set_nodelay(true).ok();
+
+    let left_rx = left.try_clone()?;
+    let right_rx = right.try_clone()?;
+    thread::spawn(move || pump(left, right_rx));
+    thread::spawn(move || pump(right, left_rx));
+    Ok(())
+}
+
 fn handle(client: TcpStream, target_port: u16) -> io::Result<()> {
-    client.set_nodelay(true).ok();
     let upstream = TcpStream::connect(("127.0.0.1", target_port))?;
-    upstream.set_nodelay(true).ok();
-
-    let client_rx = client.try_clone()?;
-    let upstream_rx = upstream.try_clone()?;
-    // client -> upstream
-    thread::spawn(move || pump(client, upstream));
-    // upstream -> client
-    thread::spawn(move || pump(upstream_rx, client_rx));
-    Ok(())
+    bridge(client, upstream)
 }
 
-fn main() {
-    let args: Vec<String> = env::args().collect();
-    if args.len() < 3 {
-        eprintln!("usage: cdp-relay <listen_port> <target_port>");
-        std::process::exit(2);
+fn wait_for_go(stream: &mut TcpStream) -> io::Result<()> {
+    let mut seen = Vec::with_capacity(3);
+    let mut byte = [0u8; 1];
+    while seen.len() < 3 {
+        stream.read_exact(&mut byte)?;
+        seen.push(byte[0]);
+        if seen == b"GO\n" {
+            return Ok(());
+        }
     }
-    let listen_port: u16 = args[1].parse().expect("invalid listen port");
-    let target_port: u16 = args[2].parse().expect("invalid target port");
+    Err(io::Error::new(io::ErrorKind::InvalidData, "expected GO"))
+}
 
+fn run_listen(listen_port: u16, target_port: u16) -> io::Result<()> {
     let listener = TcpListener::bind(("0.0.0.0", listen_port)).expect("bind failed");
     for stream in listener.incoming() {
         if let Ok(client) = stream {
@@ -47,4 +59,89 @@ fn main() {
             let _ = handle(client, target_port);
         }
     }
+    Ok(())
+}
+
+fn handle_reverse_session(mut broker: TcpStream, target_port: u16) -> io::Result<()> {
+    broker.set_nodelay(true).ok();
+    wait_for_go(&mut broker)?;
+    let upstream = TcpStream::connect(("127.0.0.1", target_port))?;
+    bridge(broker, upstream)
+}
+
+fn reverse_worker(broker_host: String, broker_port: u16, target_port: u16) {
+    loop {
+        match TcpStream::connect((broker_host.as_str(), broker_port)) {
+            Ok(broker) => {
+                if handle_reverse_session(broker, target_port).is_err() {
+                    thread::sleep(RETRY_DELAY);
+                }
+            }
+            Err(_) => thread::sleep(RETRY_DELAY),
+        }
+    }
+}
+
+fn run_reverse(broker_host: String, broker_port: u16, target_port: u16, pool_size: usize) {
+    let pool_size = pool_size.max(1);
+    for _ in 0..pool_size {
+        let host = broker_host.clone();
+        thread::spawn(move || reverse_worker(host, broker_port, target_port));
+    }
+    loop {
+        thread::sleep(Duration::from_secs(3600));
+    }
+}
+
+fn usage() -> ! {
+    eprintln!("usage:");
+    eprintln!("  cdp-relay <listen_port> <target_port>");
+    eprintln!("  cdp-relay --reverse <broker_host> <broker_port> <target_port> [pool_size]");
+    std::process::exit(2);
+}
+
+fn parse_port(value: &str, name: &str) -> u16 {
+    value.parse().unwrap_or_else(|_| {
+        eprintln!("invalid {name}");
+        std::process::exit(2);
+    })
+}
+
+fn parse_pool(value: Option<&String>) -> usize {
+    value
+        .map(|s| {
+            s.parse().unwrap_or_else(|_| {
+                eprintln!("invalid pool_size");
+                std::process::exit(2);
+            })
+        })
+        .unwrap_or(DEFAULT_REVERSE_POOL)
+}
+
+fn main() {
+    let args: Vec<String> = env::args().collect();
+    if args.get(1).map(String::as_str) == Some("--reverse") {
+        if args.len() < 5 {
+            usage();
+        }
+        let broker_host = args[2].clone();
+        let broker_port = parse_port(&args[3], "broker_port");
+        let target_port = parse_port(&args[4], "target_port");
+        run_reverse(
+            broker_host,
+            broker_port,
+            target_port,
+            parse_pool(args.get(5)),
+        );
+    }
+
+    if args.len() < 3 {
+        usage();
+    }
+    let listen_port = parse_port(&args[1], "listen_port");
+    let target_port = parse_port(&args[2], "target_port");
+    if let Err(err) = run_listen(listen_port, target_port) {
+        eprintln!("cdp-relay: {err}");
+        std::process::exit(1);
+    }
 }

package/scaffold/scripts/functional-doc/run-playwright-flow.mjs

@@ -6,10 +6,9 @@
 // which is the only mechanism that works over connectOverCDP (recordVideo does not).
 // Driving directly also removes the dependency on the project's playwright.config.*.
 //
-// Browser selection is delegated to ../lib/resolve-browser.mjs (WSL-resilient): a Windows
-// browser over CDP when reachable, otherwise the full headless Chromium (desktop-faithful,
-// no WSLg). The flow module is plain .mjs exporting `async function flow({ page, context,
-// expect, baseURL, step, shot })`.
+// Browser selection is delegated to ../lib/resolve-browser.mjs (WSL-resilient): Playwright
+// Chromium is primary, with a configured Windows/CDP target only as fallback. The flow module
+// is plain .mjs exporting `async function flow({ page, context, expect, baseURL, step, shot })`.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -79,22 +78,51 @@ async function importPlaywright() {
   }
 }
 
-async function openBrowser(chromium, descriptor) {
+async function openBrowser(chromium, descriptor, log) {
   if (descriptor.mode === "cdp") {
-    const browser = await chromium.connectOverCDP(descriptor.endpoint);
-    return { browser, cleanup: descriptor.cleanup ?? (async () => {}) };
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(descriptor.endpoint);
+    } catch (error) {
+      await (descriptor.cleanup ?? (async () => {}))();
+      throw error;
+    }
+    return { browser, descriptor, cleanup: descriptor.cleanup ?? (async () => {}) };
+  }
+  try {
+    const browser = await chromium.launch(descriptor.launchOptions);
+    return {
+      browser,
+      descriptor,
+      cleanup: async () => {
+        try {
+          await browser.close();
+        } catch {
+          // ignore
+        }
+      },
+    };
+  } catch (primaryError) {
+    if (typeof descriptor.openFallback !== "function") {
+      throw primaryError;
+    }
+    log(`browser launch failed (${primaryError.message}); trying CDP fallback from ${descriptor.fallback?.source ?? "config"}.`);
+    let fallbackDescriptor;
+    try {
+      fallbackDescriptor = await descriptor.openFallback();
+    } catch (fallbackError) {
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${fallbackError.message}`);
+    }
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(fallbackDescriptor.endpoint);
+    } catch (error) {
+      await (fallbackDescriptor.cleanup ?? (async () => {}))();
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${error.message}`);
+    }
+    log(`browser fallback: mode=${fallbackDescriptor.mode} source=${fallbackDescriptor.source}`);
+    return { browser, descriptor: fallbackDescriptor, cleanup: fallbackDescriptor.cleanup ?? (async () => {}) };
   }
-  const browser = await chromium.launch(descriptor.launchOptions);
-  return {
-    browser,
-    cleanup: async () => {
-      try {
-        await browser.close();
-      } catch {
-        // ignore
-      }
-    },
-  };
 }
 
 async function openContext(browser, descriptor, { resolution, baseURL }) {
@@ -168,15 +196,18 @@ async function main() {
   };
 
   const descriptor = await resolveBrowser({ projectRoot, headless: true });
-  log(`browser: mode=${descriptor.mode} source=${descriptor.source}`);
+  log(
+    `browser: mode=${descriptor.mode} source=${descriptor.source}` +
+      (descriptor.fallback ? ` fallback=${descriptor.fallback.source}` : ""),
+  );
   if (args.browserName && args.browserName !== "chromium") {
     log(`note: --browser-name=${args.browserName} ignored; screencast/CDP require Chromium.`);
   }
 
-  const { browser, cleanup: cleanupBrowser } = await openBrowser(chromium, descriptor);
-  const { context, owns: ownsContext } = await openContext(browser, descriptor, { resolution, baseURL });
+  const { browser, descriptor: activeDescriptor, cleanup: cleanupBrowser } = await openBrowser(chromium, descriptor, log);
+  const { context, owns: ownsContext } = await openContext(browser, activeDescriptor, { resolution, baseURL });
   const page = await context.newPage();
-  if (descriptor.mode === "cdp") {
+  if (activeDescriptor.mode === "cdp") {
     try {
       await page.setViewportSize({ width: resolution.width, height: resolution.height });
     } catch {
@@ -263,8 +294,8 @@ async function main() {
 
   updateManifest(manifestPath, {
     status,
-    browserMode: descriptor.mode,
-    browserSource: descriptor.source,
+    browserMode: activeDescriptor.mode,
+    browserSource: activeDescriptor.source,
     recording,
     videoResolution: resolution.label,
     video: videoExists ? videoPath : null,

package/scaffold/scripts/lib/capture-screenshots.mjs

@@ -62,6 +62,55 @@ function slugify(value) {
   );
 }
 
+async function openBrowser(chromium, descriptor) {
+  if (descriptor.mode === "cdp") {
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(descriptor.endpoint);
+    } catch (error) {
+      await (descriptor.cleanup ?? (async () => {}))();
+      throw error;
+    }
+    return { browser, descriptor, cleanup: descriptor.cleanup ?? (async () => {}) };
+  }
+  try {
+    const browser = await chromium.launch(descriptor.launchOptions);
+    return {
+      browser,
+      descriptor,
+      cleanup: async () => {
+        try {
+          await browser.close();
+        } catch {
+          // ignore
+        }
+      },
+    };
+  } catch (primaryError) {
+    if (typeof descriptor.openFallback !== "function") {
+      throw primaryError;
+    }
+    process.stderr.write(
+      `browser launch failed (${primaryError.message}); trying CDP fallback from ${descriptor.fallback?.source ?? "config"}.\n`,
+    );
+    let fallbackDescriptor;
+    try {
+      fallbackDescriptor = await descriptor.openFallback();
+    } catch (fallbackError) {
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${fallbackError.message}`);
+    }
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(fallbackDescriptor.endpoint);
+    } catch (error) {
+      await (fallbackDescriptor.cleanup ?? (async () => {}))();
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${error.message}`);
+    }
+    process.stderr.write(`browser fallback: mode=${fallbackDescriptor.mode} source=${fallbackDescriptor.source}\n`);
+    return { browser, descriptor: fallbackDescriptor, cleanup: fallbackDescriptor.cleanup ?? (async () => {}) };
+  }
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!args.url) {
@@ -85,27 +134,17 @@ async function main() {
 
   fs.mkdirSync(outDir, { recursive: true });
   const descriptor = await resolveBrowser({ projectRoot: process.cwd(), headless: true });
-  process.stderr.write(`browser: mode=${descriptor.mode} source=${descriptor.source}\n`);
+  process.stderr.write(
+    `browser: mode=${descriptor.mode} source=${descriptor.source}` +
+      (descriptor.fallback ? ` fallback=${descriptor.fallback.source}` : "") +
+      "\n",
+  );
 
-  let browser;
-  let cleanup = async () => {};
-  if (descriptor.mode === "cdp") {
-    browser = await chromium.connectOverCDP(descriptor.endpoint);
-    cleanup = descriptor.cleanup ?? (async () => {});
-  } else {
-    browser = await chromium.launch(descriptor.launchOptions);
-    cleanup = async () => {
-      try {
-        await browser.close();
-      } catch {
-        // ignore
-      }
-    };
-  }
+  const { browser, descriptor: activeDescriptor, cleanup } = await openBrowser(chromium, descriptor);
 
   const shots = [];
   try {
-    const existing = descriptor.mode === "cdp" ? browser.contexts()[0] : null;
+    const existing = activeDescriptor.mode === "cdp" ? browser.contexts()[0] : null;
     const context = existing ?? (await browser.newContext());
     const ownsContext = !existing;
     const page = await context.newPage();