@brunosps00/dev-workflow 1.6.0 → 1.7.1

package/scaffold/pt-br/commands/dw-open-design.md

@@ -0,0 +1,323 @@
+<system_instructions>
+Voce e o **runner headless do Open Design (`od`)** para gerar e iterar prototipos HTML em uma pasta de projeto,
+sem abrir Electron e sem depender do estado da GUI do usuario. Use o daemon do `nexu-io/open-design` em
+`--headless`, importe a pasta alvo uma vez, rode briefs single ou batch em serie, verifique o arquivo produzido,
+rode gate visual Playwright/Firefox e **PARE para o gate do dono** antes de qualquer commit.
+
+<critical>NUNCA use o estado da GUI do usuario. Sempre rode com `OD_DATA_DIR` isolado por projeto, por exemplo `.dw/.open-design/data/`.</critical>
+<critical>NUNCA commite prototipo reprovado. O gate e dual >=9: gate automatico + avaliacao visual propria >=9, depois gate do dono.</critical>
+<critical>O agente (`codex` ou `claude`) deve ser sempre explicito em `od run start --agent <agent>`. Se o usuario nao passar, resolva de config/estado do projeto; fallback `codex`.</critical>
+<critical>NUNCA despache o pedido cru do usuario para o `od`. O valor deste comando e refinar o prompt primeiro: ancore no codigo real, estruture o brief, qualifique estados/temas/a11y/deep-link, persista o brief revisavel e so entao anexe o apendice headless.</critical>
+
+## Inputs
+
+| Flag/argumento | Default | Descricao |
+|---|---:|---|
+| `--target <dir>` | `open-design/` | Pasta importada como projeto externo e onde os HTMLs serao escritos. |
+| `--brief <file>` | nenhum | Um brief markdown para uma run single. |
+| `--brief-glob <glob>` | nenhum | Batch em serie. Expanda para lista estavel e rode um prompt por vez. |
+| `--output <file>` | obrigatorio no brief/apendice | HTML esperado; verifique no filesystem depois da run. |
+| `--agent <codex|claude>` | estado/config -> `codex` | Agente repassado ao `od run start --agent`. |
+| `--platform <text>` | `Web responsivo desktop-first e mobile-safe` | Resposta pre-preenchida para o discovery da skill `web-prototype`. |
+| `--deep-link-id <id>` | nenhum | Valor usado no gate comportamental `?aberto=<id>` + Esc. |
+| `--refactor` | falso | Modo redesign/refactor de tela existente; captura prints atuais e ancora o brief no estado visivel + codigo real. |
+| `--url <url>` | nenhum | URL de app rodando para capturar prints atuais via Playwright Firefox. |
+| `--viewports <lista>` | `1440x900,375x812` | Viewports separados por virgula para `--refactor --url`; expanda conforme a dor (ex.: `1920x1080` para tabela larga). |
+| `--screenshot <path>` | repetivel | Print atual ja capturado quando nao houver `--url`; copie para `_refs/<slug>/`. |
+
+## 0. Refinar o brief
+
+Antes de qualquer pre-flight de daemon ou chamada ao `od`, transforme a intencao do usuario em um brief qualificado.
+Nao envie a frase crua do usuario para o runner.
+
+Contrato obrigatorio:
+
+| Etapa | Exigencia |
+|---|---|
+| Ancorar na realidade | Se a tela existe, leia o codigo real dela: colunas, enums, acoes, estados, permissoes, contracts e dominio. Leia tambem design system, prototipos irmaos e guias de design do projeto. E proibido inventar campo, status ou acao. |
+| Estruturar | Reescreva o pedido no esqueleto padrao abaixo, preenchendo paths reais e arquivo de saida exato. |
+| Qualificar | Cubra loading/skeleton, empty/vazio, erro/falha, light + dark, a11y, limites do design system local (ex.: <=6 cards/filtros), responsividade e deep-link. |
+| Persistir | Salve o brief refinado dentro do projeto, por exemplo `<target>/PROMPT-<slug>.md`. Ele e entregavel revisavel pelo dono, nao arquivo descartavel. |
+| Revisar se ja vier pronto | Se o usuario trouxer um brief ja qualificado, faca uma revisao rapida por checklist, ajuste apenas lacunas e persista a versao final. |
+
+Esqueleto padrao do brief refinado:
+
+```markdown
+# <titulo da tela/prototipo>
+
+Cole este brief no Open Design. Arquivo de saida exato: `<OUTPUT_FILE>`.
+
+## 1. Por que
+<dor real do usuario/produto; problema observavel que este prototipo precisa resolver>
+
+## 2. Decisao de interacao
+<padrao de navegacao, abertura, selecao, filtros, ordenacao, edicao e confirmacoes>
+
+## 3. Layout/lista
+Tabela/lista baseada apenas em colunas REAIS:
+
+| Coluna real | Origem/contract | Como aparece | Estado/limite |
+|---|---|---|---|
+| <nome> | <arquivo/API/schema> | <texto, badge, acao> | <truncate, vazio, erro> |
+
+## 4. Detalhe/acoes
+<drawer/modal/pagina de detalhe; acoes contextuais permitidas por estado/permissao real>
+
+## 5. Fidelidade de dominio
+Para o mock nao mentir: usar enums/status reais, dados de exemplo realistas no idioma do projeto e incluir estados raros/quebrados que existem no dominio.
+
+## 6. Direcao visual
+<tokens, componentes, densidade, referencias herdadas, prototipos irmaos e limites do design system>
+
+## Entregar
+- `<OUTPUT_FILE>`
+- `<OUTPUT_FILE>.artifact.json` se houver sidecar
+```
+
+So depois de persistir esse arquivo anexe o apendice headless em `.dw/.open-design/runs/` e despache a run.
+
+### 0R. Modo refactor/redesign
+
+Quando `--refactor` estiver presente, a fase 0 continua obrigatoria. Prints complementam a ancoragem no codigo; eles
+nao substituem leitura de contracts, enums, permissoes, estados, design system e prototipos irmaos.
+
+Capture ou copie os prints atuais para dentro da pasta importada, em `_refs/<slug>/`, antes de persistir o brief:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --url "<url>" \
+  --viewports "1440x900,375x812"
+```
+
+Sem URL de app rodando, aceite prints prontos repetindo `--screenshot`:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --screenshot "./antes-1440-light.png" \
+  --screenshot "./antes-375-dark.png"
+```
+
+Regras de captura:
+
+| Caso | Exigencia |
+|---|---|
+| Viewports | Default sensato: desktop `1440x900` + mobile `375x812`. O agente escolhe/expande conforme a dor: bug mobile inclui `375x812`; tabela larga inclui `1920x1080`; tablet/console inclui `768x1024`. |
+| Temas | Capture light e dark quando aplicavel. O helper usa `light,dark` por default e grava nomes como `_refs/<slug>/atual-1440-light.png` e `_refs/<slug>/atual-375-dark.png`. |
+| Caminho robusto | O agente do `od` le imagens do filesystem do projeto. Referencie caminhos relativos dentro do target; nao dependa de flag de imagem no `run start`. |
+| Higiene | `_refs/` e material de referencia nao devem virar prototipo. Se o projeto-alvo versiona prototipos finais, documente limpeza ou adicione `<target>/_refs/` ao `.gitignore` conforme a convencao local. |
+
+O brief refinado do modo refactor deve adicionar este bloco:
+
+```markdown
+## Referencias da tela atual
+Abra e ANALISE os prints antes de escrever:
+- `_refs/<slug>/atual-1440-light.png`
+- `_refs/<slug>/atual-375-dark.png`
+
+## O que esta errado hoje
+<dor apontando elementos visiveis nos prints: densidade, hierarquia, tabela, filtros, estados, contraste, mobile, etc.>
+
+## A ideia da mudanca
+<o que muda e por que; decisao de interacao/visual proposta pelo usuario ou pelo agente apos ler codigo e prints>
+
+## Preservar
+<fluxos, campos, permissoes, estados, copys, affordances e integracoes que nao podem mudar>
+```
+
+## Pre-flight
+
+| Checagem | Acao |
+|---|---|
+| Resolver `od` | `OD_CLI_DIR` vence. Senao use `~/.dw/vendor/open-design`. Se `apps/daemon/bin/od.mjs` nao existir, pare e mande rodar `dev-workflow install-deps`. |
+| Prerequisitos | O checkout do Open Design exige Node `~24` e pnpm `>=10.33`. Se faltarem, pare com instrucoes objetivas. |
+| Estado isolado | Crie `.dw/.open-design/`, `.dw/.open-design/data/`, `.dw/.open-design/runs/` e `.dw/.open-design/state.json`. |
+| Porta | Escolha porta livre em `127.0.0.1`; persista `daemonUrl` e `port` no state. |
+| Daemon vivo | Se `od daemon status --daemon-url <url> --json` retornar `ok: true`, reuse. Senao inicie novo daemon. |
+
+Comando base do daemon:
+
+```bash
+OD_DATA_DIR="$PWD/.dw/.open-design/data" \
+OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000 \
+node "$OD_DIR/apps/daemon/bin/od.mjs" daemon start \
+  --headless \
+  --host 127.0.0.1 \
+  --port "$PORT"
+```
+
+Ruido conhecido: `codex_core::shell_snapshot` pode logar `ERROR` de sintaxe. Isso e benigno; nao aborte se a run
+continua e o arquivo alvo e criado.
+
+## Import idempotente
+
+Use `project import-folder` na pasta alvo resolvida absoluta. Default: `<repo>/open-design/`.
+
+Persistir em `.dw/.open-design/state.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "targetDir": "/abs/repo/open-design",
+  "projectId": "<project.id>",
+  "conversationId": "<conversationId>",
+  "daemonUrl": "http://127.0.0.1:<port>",
+  "port": 17556,
+  "agent": "codex"
+}
+```
+
+Se `projectId` existe no state e `od project info <id> --daemon-url <url> --json` funciona para o mesmo
+`targetDir`, reuse. Caso contrario, reimporte:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" project import-folder "$TARGET_DIR" \
+  --daemon-url "$OD_URL" \
+  --name "$(basename "$TARGET_DIR")" \
+  --skill web-prototype \
+  --design-system default \
+  --json
+```
+
+Capture `project.id` e `conversationId`; nao dependa de estado global do app.
+
+## Apendice headless obrigatorio
+
+Anexe este bloco ao final de cada brief em um arquivo temporario dentro de `.dw/.open-design/runs/`.
+Preencha `<PLATFORM>`, `<OUTPUT_FILE>` e referencias irma se houver.
+
+```markdown
+---
+
+## Apendice headless para Open Design
+
+Plataforma-alvo: <PLATFORM>.
+
+Nao faca discovery e nao faca perguntas. Nao emita `<question-form>`. Siga este brief com as respostas acima e
+entregue arquivo primeiro.
+
+Arquivo de saida obrigatorio: `<OUTPUT_FILE>`.
+
+Contrato file-first:
+- Escreva o HTML diretamente no filesystem do projeto, exatamente em `<OUTPUT_FILE>`.
+- Nao altere arquivos existentes, exceto quando este prompt for explicitamente uma iteracao cirurgica sobre um arquivo alvo.
+- Se precisar criar sidecar, mantenha `<OUTPUT_FILE>.artifact.json` coerente.
+- Nao responda apenas com bloco `<artifact>` textual; run `succeeded` sem arquivo e falha.
+
+Para evitar timeout headless:
+- Escreva arquivos grandes em partes, com edicoes de aproximadamente 150 linhas por chamada.
+- Mantenha progresso visivel ate finalizar o HTML.
+
+Contexto de consistencia:
+- Leia prototipos irmaos em `prototipos/` ou na pasta indicada no brief antes de definir padroes visuais.
+- Preserve o sistema visual local quando houver referencia proxima.
+
+Deep-link obrigatorio:
+- Implemente `?aberto=<id>` para abrir o drawer/modal do item correto.
+- Ao fechar com Esc ou acao de fechar, limpe o parametro com `history.replaceState`.
+- O drawer/modal deve usar `role="dialog"` e atributos ARIA adequados.
+- Inclua estados skeleton/loading, empty/vazio e erro/falha.
+```
+
+## Run single
+
+Sempre passe `--agent` explicitamente:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file "$PROMPT_WITH_APPENDIX" \
+  --follow \
+  --json | tee ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+Depois da run, confira o arquivo. **Nao aceite apenas status `succeeded`:**
+
+```bash
+test -s "$TARGET_DIR/<OUTPUT_FILE>"
+```
+
+Registre no JSONL ou em sidecar de auditoria: brief, prompt com apendice, agente, daemonUrl, projectId,
+conversationId, output esperado, status final e resultado da verificacao do arquivo.
+
+## Batch
+
+Para `--brief-glob`, expanda os briefs, ordene por nome e rode em serie. Pare no primeiro caso em que:
+
+| Condicao | Resultado |
+|---|---|
+| run falha | `BLOCKED` com log JSONL |
+| run diz sucesso mas arquivo nao existe ou esta vazio | `FINDINGS` e follow-up cirurgico ou `BLOCKED` |
+| gate visual <9 | `FINDINGS`; iterar antes de continuar |
+
+Nao rode prompts em paralelo no mesmo projeto `od`; preserve auditabilidade e contexto.
+
+## Iteracao cirurgica
+
+Use follow-up run no mesmo `projectId`/`conversationId`, com prompt curto e arquivo alvo explicito:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file ".dw/.open-design/runs/<slug>.followup.md" \
+  --follow \
+  --json | tee -a ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+O follow-up deve dizer: arquivo unico, mudanca exata, nao tocar prototipos irmaos, manter deep-link e estados.
+
+## Gate visual obrigatorio
+
+Execute o gate automatico:
+
+```bash
+node .dw/scripts/open-design/gate-prototype.mjs \
+  --file "$TARGET_DIR/<OUTPUT_FILE>" \
+  --deep-link-id "<id-real>" \
+  --expected-text "<texto-do-item>" \
+  --out ".dw/.open-design/gate/<slug>"
+```
+
+O gate cobre:
+
+| Camada | Exigencia |
+|---|---|
+| Estrutural | `<title>`, `aberto`, `replaceState`, `role=dialog`/ARIA, skeleton/loading, empty/vazio, erro/falha. |
+| Screenshot | Firefox headless em light e dark, com `colorScheme` e `data-theme`. |
+| Comportamental | `?aberto=<id>` abre o item certo; Esc fecha e limpa o parametro. |
+| Avaliacao | Automatico PASS + sua nota visual >=9. Se abaixo de 9, faca follow-up cirurgico. |
+
+Depois de passar, **pare para o gate do dono**. Nao commite ate o dono aprovar.
+
+## Armadilhas validadas
+
+| Armadilha | Sintoma | Contorno obrigatorio |
+|---|---|---|
+| Discovery da `web-prototype` | Abre com `<question-form>` e encerra o turno; headless nao gera GenUI (`od ui list` vazio). | Anexar o apendice headless respondendo plataforma e proibindo perguntas/discovery. |
+| Timeout de inatividade | HTML grande fica silencioso e o run morre perto de 10min. | `OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000` no daemon + instruir escrita em partes de ~150 linhas. |
+| `codex_core::shell_snapshot` | Loga `ERROR` de sintaxe no stream. | Tratar como ruido se a run prossegue e o arquivo final existe. |
+| Estado da GUI | Config/agente/projetos vazam do app do usuario. | `OD_DATA_DIR` isolado sempre; `--agent`, `--skill` e `--design-system` explicitos. |
+
+## Structured Return
+
+**Status:** `PASS` | `FINDINGS` | `BLOCKED` | `NOT_APPLICABLE`  
+**Scope:** pasta alvo, briefs executados, agente usado, projectId/conversationId.  
+**Evidence:** logs JSONL, arquivo(s) HTML verificados, gate JSON, screenshots light/dark.  
+**Artifacts:** paths dos prototipos e sidecars.  
+**Decisions:** defaults/overrides aplicados (`agent`, `target`, plataforma, porta).  
+**Risks:** qualquer gate abaixo de 9, arquivo nao gerado apesar de run succeeded, dependencia ausente.  
+**Next Step:** gate do dono, follow-up cirurgico necessario, ou comando de resume exato.
+</system_instructions>

package/scaffold/pt-br/templates/project-onepager.md

@@ -23,20 +23,21 @@ services: []
 |--------|---------|---------------|
 | Forma | frontend / backend / fullstack | [por que essa forma — superficie unica, API para parceiros, etc.] |
 | Frontend | Next.js / Vite+React / n/a | [por que esse framework — SSR, simplicidade SPA, etc.] |
-| Backend | FastAPI / ASP.NET Core minimal / Axum / Fastify / n/a | [por que — expertise do time, ecosystem, alvo de latencia] |
-| Database | Postgres / MySQL / SQLite / MongoDB / nenhum | [por que esse DB — relacional, JSON-heavy, transacional, etc.] |
+| Backend | NestJS / Fastify / FastAPI / ASP.NET Core minimal / Axum / n/a | [por que — expertise do time, ecosystem, alvo de latencia] |
+| Database | Postgres / Postgres+pgvector / MySQL / SQLite / MongoDB / nenhum | [por que esse DB — relacional, vetorial, transacional, etc.] |
 | Cache | Redis / Memcached / nenhum | [por que ou por que nao] |
-| Fila | BullMQ / Celery / RabbitMQ / LocalStack SQS / nenhum | [por que ou nao + sync vs async workers] |
-| Email — dev | MailHog (default) / Mailpit / smtp4dev / nenhum | [normalmente MailHog — captura only, nunca envia real] |
+| Fila | pg-boss / BullMQ / Celery / RabbitMQ / LocalStack SQS / nenhum | [por que ou nao + sync vs async workers] |
+| Email — dev | Mailpit (default) / MailHog / smtp4dev / nenhum | [normalmente Mailpit — captura only, nunca envia real] |
 | Email — prod | SMTP / SendGrid / Resend / Postmark / SES / nenhum | [por que esse provider — volume, deliverability, custo] |
 | Object storage | S3 / MinIO (dev) / GCS / nenhum | [por que ou nao] |
 | Search | Meilisearch / Typesense / Elasticsearch / nenhum | [por que esse engine — features, escala, simplicidade] |
 | Observability | Sentry / OTel + Jaeger / nenhum | [por que essa abordagem — so error tracking, tracing completo, etc.] |
 | Reverse proxy | Traefik / Caddy / nenhum | [normalmente so multi-host dev ou prod] |
-| Auth | NextAuth / Lucia / Clerk / fastapi-users / dotnet Identity / JWT custom / nenhum | [por que — social login, B2B, etc.] |
+| Auth | Auth.js / OIDC generico / Clerk / fastapi-users / dotnet Identity / JWT custom / nenhum | [por que — social login, B2B, etc.] |
 | Linter / formatter | Biome / ESLint+Prettier / Ruff+Black / dotnet format / cargo fmt+clippy | [preferencia do time] |
 | Package manager | pnpm / npm / yarn / poetry / uv / cargo / dotnet | [preferencia do time] |
-| Monorepo orchestrator | pnpm workspaces / npm workspaces / Turborepo / Nx / n/a | [so para fullstack — caching/build] |
+| Workspace + task runner | pnpm workspaces + Turborepo / npm workspaces / Nx / n/a | [so para fullstack — caching/build] |
+| Topologia de dev | apps no host / tudo no Compose | [trade-off de hot reload e paridade] |
 | CI | GitHub Actions / nenhum | [normalmente GitHub Actions; pular so para repos nao-publicos] |
 
 ## Servicos & Infra
@@ -47,7 +48,7 @@ services: []
 |---------|--------------|----|--------------------|
 | postgres | 5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD=app, POSTGRES_DB=app |
 | redis | 6379 | — | (sem auth em dev) |
-| mailhog | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (sem auth) |
+| mailpit | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (sem auth) |
 | ... | ... | ... | ... |
 
 ## Diagrama da Arquitetura
@@ -59,12 +60,12 @@ services: []
 [ Browser ] -> [ Next.js (apps/web) ]
 
 # Fullstack
-[ Browser ] -> [ Next.js (apps/web) ] -> [ FastAPI (apps/api) ] -> [ Postgres ]
+[ Browser ] -> [ Next.js (apps/web) ] -> [ NestJS (apps/api) ] -> [ Postgres ]
                                                                 |-> [ Redis ]
-                                                                |-> [ MailHog ]
+                                                                |-> [ Mailpit ]
 
 # Com observability
-... -> [ FastAPI ] -> { OTLP } -> [ Jaeger ]
+... -> [ NestJS ] -> { OTLP } -> [ Jaeger ]
 ```
 
 ## Arquivos Gerados
@@ -75,7 +76,7 @@ services: []
 {{TARGET_DIR}}/
 ├── apps/
 │   ├── web/                      (criado por `pnpm create next-app`)
-│   └── api/                      (scaffold inline — FastAPI)
+│   └── api/                      (criado por `pnpm dlx @nestjs/cli` ou scaffold escolhido)
 ├── packages/
 │   └── shared/                   (criado pelo /dw-new-project)
 ├── docker-compose.dev.yml        (composto a partir de .agents/skills/docker-compose-recipes/)

package/scaffold/scripts/open-design/capture-current.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+function parseArgs(argv) {
+  const result = { screenshot: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (inlineValue !== undefined) {
+      if (key === "screenshot") result.screenshot.push(inlineValue);
+      else result[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      if (key === "screenshot") {
+        throw new Error("Missing value for --screenshot <path>.");
+      }
+      result[key] = true;
+      continue;
+    }
+    if (key === "screenshot") result.screenshot.push(next);
+    else result[key] = next;
+    index += 1;
+  }
+  return result;
+}
+
+async function importFirefox() {
+  try {
+    return (await import("@playwright/test")).firefox;
+  } catch {
+    try {
+      return (await import("playwright")).firefox;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function slugify(value) {
+  return (
+    String(value)
+      .toLowerCase()
+      .replace(/^https?:\/\//, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 70) || "screen"
+  );
+}
+
+function parseViewports(value) {
+  return String(value || "1440x900,375x812")
+    .split(",")
+    .map((entry) => {
+      const match = entry.trim().match(/^(\d{2,5})x(\d{2,5})$/);
+      if (!match) return null;
+      return { width: Number(match[1]), height: Number(match[2]) };
+    })
+    .filter(Boolean);
+}
+
+function parseThemes(value) {
+  return String(value || "light,dark")
+    .split(",")
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry === "light" || entry === "dark");
+}
+
+function inferProvidedName(source, index) {
+  const base = path.basename(source, path.extname(source)).toLowerCase();
+  const width = base.match(/(?:^|[^0-9])(\d{3,5})(?:x\d{3,5})?(?:[^0-9]|$)/)?.[1];
+  const theme = base.includes("dark") ? "dark" : base.includes("light") ? "light" : "";
+  if (width && theme) return `atual-${width}-${theme}.png`;
+  if (width) return `atual-${width}-${String(index + 1).padStart(2, "0")}.png`;
+  return `atual-ref-${String(index + 1).padStart(2, "0")}.png`;
+}
+
+async function captureFromUrl(args, outDir) {
+  if (!args.url) return [];
+  const firefox = await importFirefox();
+  if (!firefox) {
+    throw new Error("Playwright is not installed. Run: npm i -D @playwright/test && npx playwright install firefox");
+  }
+
+  const viewports = parseViewports(args.viewports);
+  if (viewports.length === 0) {
+    throw new Error("No valid --viewports entries. Use comma-separated WIDTHxHEIGHT values, for example 1440x900,375x812.");
+  }
+  const themes = parseThemes(args.themes);
+  if (themes.length === 0) {
+    throw new Error("No valid --themes entries. Use light,dark or one of them.");
+  }
+
+  const browser = await firefox.launch({ headless: true });
+  const shots = [];
+  try {
+    for (const viewport of viewports) {
+      for (const theme of themes) {
+        const context = await browser.newContext({
+          colorScheme: theme,
+          viewport,
+        });
+        const page = await context.newPage();
+        await page.goto(String(args.url), { waitUntil: "networkidle" }).catch(() => page.goto(String(args.url)));
+        await page.evaluate((value) => {
+          document.documentElement.setAttribute("data-theme", value);
+        }, theme);
+        await page.waitForTimeout(300);
+        const target = path.join(outDir, `atual-${viewport.width}-${theme}.png`);
+        await page.screenshot({ path: target, fullPage: true });
+        shots.push({ source: String(args.url), viewport, theme, path: target });
+        await context.close();
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  return shots;
+}
+
+function copyProvidedScreenshots(args, outDir) {
+  return args.screenshot.map((source, index) => {
+    const resolved = path.resolve(String(source));
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Screenshot not found: ${resolved}`);
+    }
+    const target = path.join(outDir, inferProvidedName(resolved, index));
+    fs.copyFileSync(resolved, target);
+    return { source: resolved, path: target };
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.url && args.screenshot.length === 0) {
+    throw new Error("Pass --url <app-url> or one or more --screenshot <path> values.");
+  }
+
+  const targetDir = path.resolve(String(args.target || "open-design"));
+  const slug = slugify(args.slug || args.url || "screen");
+  const outDir = path.resolve(String(args.out || path.join(targetDir, "_refs", slug)));
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const copied = copyProvidedScreenshots(args, outDir);
+  const captured = await captureFromUrl(args, outDir);
+  const shots = [...copied, ...captured];
+
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        targetDir,
+        refsDir: outDir,
+        relativeRefs: shots.map((shot) => path.relative(targetDir, shot.path).split(path.sep).join("/")),
+        shots,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`capture-current: ${error.message}\n`);
+  process.exit(1);
+});