@brunosps00/dev-workflow 1.6.0 → 1.7.1

package/scaffold/scripts/open-design/gate-prototype.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+function parseArgs(argv) {
+  const result = {};
+  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) {
+      result[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      result[key] = true;
+      continue;
+    }
+    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(/\.html?$/, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 70) || "prototype"
+  );
+}
+
+function addResult(results, name, pass, details = "") {
+  results.push({ name, pass: Boolean(pass), details });
+}
+
+async function structuralChecks(page, html, results) {
+  const data = await page.evaluate(() => {
+    const visibleText = document.body ? document.body.innerText : "";
+    const hasDialogRole = Boolean(document.querySelector('[role="dialog"], [aria-modal="true"], [aria-labelledby]'));
+    const title = document.title.trim();
+    return { visibleText, hasDialogRole, title };
+  });
+
+  addResult(results, "title", data.title.length > 0, data.title || "missing document title");
+  addResult(results, "aberto-param", /\baberto\b/.test(html), "source contains aberto");
+  addResult(results, "replace-state", /replaceState/.test(html), "source contains replaceState");
+  addResult(results, "dialog-aria", data.hasDialogRole, "role=dialog, aria-modal, or aria-labelledby present");
+  addResult(results, "skeleton-state", /skeleton|carregando|loading/i.test(html + "\n" + data.visibleText));
+  addResult(results, "empty-state", /empty|vazio|sem\s+(resultado|dados|itens|registros)/i.test(html + "\n" + data.visibleText));
+  addResult(results, "error-state", /error|erro|falha|failed|retry|tentar novamente/i.test(html + "\n" + data.visibleText));
+}
+
+async function visibleDialog(page, selector) {
+  const selected = selector ? page.locator(selector).first() : page.locator('[role="dialog"], [aria-modal="true"]').first();
+  try {
+    return (await selected.count()) > 0 && (await selected.isVisible());
+  } catch {
+    return false;
+  }
+}
+
+async function clickFirstOpenable(page, rowSelector) {
+  const selector =
+    rowSelector ||
+    '[data-open], [data-id], tbody tr, [role="row"], [role="button"], article, li button, li, button';
+  const candidates = page.locator(selector);
+  const count = Math.min(await candidates.count(), 20);
+  for (let index = 0; index < count; index += 1) {
+    const candidate = candidates.nth(index);
+    try {
+      if (!(await candidate.isVisible())) continue;
+      await candidate.click({ timeout: 1500 });
+      return true;
+    } catch {
+      // Try the next plausible opener.
+    }
+  }
+  return false;
+}
+
+async function behavioralChecks(page, baseUrl, args, results) {
+  const dialogSelector = args.dialogSelector ? String(args.dialogSelector) : "";
+  if (!(await visibleDialog(page, dialogSelector))) {
+    const clicked = await clickFirstOpenable(page, args.rowSelector ? String(args.rowSelector) : "");
+    await page.waitForTimeout(300);
+    addResult(results, "open-drawer-click", clicked && (await visibleDialog(page, dialogSelector)), "first row/openable opens dialog or drawer");
+  } else {
+    addResult(results, "open-drawer-click", true, "dialog already visible");
+  }
+
+  const deepLinkId = args.deepLinkId ? String(args.deepLinkId) : "";
+  if (!deepLinkId) {
+    addResult(results, "deep-link-opens", false, "missing --deep-link-id");
+    addResult(results, "esc-clears-param", false, "missing --deep-link-id");
+    return;
+  }
+
+  const url = new URL(baseUrl);
+  url.searchParams.set("aberto", deepLinkId);
+  await page.goto(url.toString(), { waitUntil: "load" });
+  await page.waitForTimeout(500);
+
+  const expectedText = String(args.expectedText || deepLinkId);
+  const deepLinkData = await page.evaluate((text) => {
+    const bodyText = document.body ? document.body.innerText : "";
+    const hasDialog = Boolean(document.querySelector('[role="dialog"], [aria-modal="true"]'));
+    return {
+      hasDialog,
+      hasText: bodyText.toLowerCase().includes(text.toLowerCase()),
+      search: window.location.search,
+    };
+  }, expectedText);
+  addResult(
+    results,
+    "deep-link-opens",
+    deepLinkData.search.includes(`aberto=${encodeURIComponent(deepLinkId)}`) && deepLinkData.hasDialog && deepLinkData.hasText,
+    `expected visible text: ${expectedText}`,
+  );
+
+  await page.keyboard.press("Escape");
+  await page.waitForTimeout(500);
+  const searchAfterEsc = await page.evaluate(() => window.location.search);
+  addResult(results, "esc-clears-param", !new URLSearchParams(searchAfterEsc).has("aberto"), searchAfterEsc || "empty search");
+}
+
+async function captureScreenshots(browser, fileUrl, outDir, slug) {
+  const shots = [];
+  for (const scheme of ["light", "dark"]) {
+    const context = await browser.newContext({
+      colorScheme: scheme,
+      viewport: { width: 1440, height: 1000 },
+    });
+    const page = await context.newPage();
+    await page.goto(fileUrl, { waitUntil: "load" });
+    await page.evaluate((theme) => {
+      document.documentElement.setAttribute("data-theme", theme);
+    }, scheme);
+    await page.waitForTimeout(300);
+    const shotPath = path.join(outDir, `${slug}-${scheme}.png`);
+    await page.screenshot({ path: shotPath, fullPage: true });
+    shots.push({ colorScheme: scheme, path: shotPath });
+    await context.close();
+  }
+  return shots;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.file) {
+    throw new Error("Missing required argument: --file <prototype.html>");
+  }
+
+  const filePath = path.resolve(String(args.file));
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Prototype file not found: ${filePath}`);
+  }
+
+  const firefox = await importFirefox();
+  if (!firefox) {
+    throw new Error("Playwright is not installed. Run: npm i -D @playwright/test && npx playwright install firefox");
+  }
+
+  const html = fs.readFileSync(filePath, "utf8");
+  const outDir = path.resolve(String(args.out || path.join(".dw", ".open-design", "gate", slugify(path.basename(filePath)))));
+  fs.mkdirSync(outDir, { recursive: true });
+  const baseUrl = pathToFileURL(filePath).toString();
+  const slug = slugify(path.basename(filePath));
+
+  const browser = await firefox.launch({ headless: true });
+  const results = [];
+  let screenshots = [];
+  try {
+    const context = await browser.newContext({ colorScheme: "light", viewport: { width: 1440, height: 1000 } });
+    const page = await context.newPage();
+    await page.goto(baseUrl, { waitUntil: "load" });
+    await structuralChecks(page, html, results);
+    await behavioralChecks(page, baseUrl, args, results);
+    await context.close();
+    screenshots = await captureScreenshots(browser, baseUrl, outDir, slug);
+  } finally {
+    await browser.close();
+  }
+
+  const failed = results.filter((result) => !result.pass);
+  const summary = {
+    file: filePath,
+    score: Number(((results.length - failed.length) / results.length * 10).toFixed(1)),
+    pass: failed.length === 0,
+    results,
+    screenshots,
+  };
+  fs.writeFileSync(path.join(outDir, `${slug}-gate.json`), JSON.stringify(summary, null, 2) + "\n", "utf8");
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+
+  if (failed.length > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`gate-prototype: ${error.message}\n`);
+  process.exit(1);
+});

package/scaffold/skills/docker-compose-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docker-compose-recipes
-description: Use for docker-compose service blocks (postgres, redis, mailhog, minio, meilisearch, jaeger, traefik). Invoked by /dw-new-project, /dw-dockerize, or when composing dev/prod compose files.
+description: Use for docker-compose service blocks (postgres, pgvector, redis, mailpit, minio, meilisearch, jaeger, traefik). Invoked by /dw-new-project, /dw-dockerize, or when composing dev/prod compose files.
 allowed-tools:
   - Read
   - Write
@@ -49,13 +49,14 @@ Each row points to `services/<name>.yml`.
 | Service | Use | Default port(s) | Recipe |
 |---------|-----|-----------------|--------|
 | Postgres 16 (alpine) | Relational DB | `5432` | `services/postgres.yml` |
+| PostgreSQL 18 + pgvector 0.8.2 | Relational + vector DB | `5432` | `services/postgres-pgvector.yml` |
 | MySQL 8 | Relational DB | `3306` | `services/mysql.yml` |
 | Redis 7 (alpine) | Cache, pub/sub, BullMQ backend | `6379` | `services/redis.yml` |
 | Memcached 1.6 (alpine) | Cache | `11211` | `services/memcached.yml` |
 | RabbitMQ 3 (management-alpine) | Message broker + UI | `5672`, UI `15672` | `services/rabbitmq.yml` |
 | LocalStack | AWS-compatible local (S3, SQS, SNS, DynamoDB) | `4566` | `services/localstack.yml` |
-| MailHog | Default email-in-dev (capture only, never sends) | SMTP `1025`, UI `8025` | `services/mailhog.yml` |
-| Mailpit | Modern MailHog alternative | SMTP `1025`, UI `8025` | `services/mailpit.yml` |
+| Mailpit | Default email-in-dev (capture only, never sends) | SMTP `1025`, UI `8025` | `services/mailpit.yml` |
+| MailHog | Legacy email capture alternative | SMTP `1025`, UI `8025` | `services/mailhog.yml` |
 | smtp4dev | Windows-friendly SMTP capture | SMTP `2525`, UI `5000` | `services/smtp4dev.yml` |
 | MinIO | S3-compatible local | API `9000`, UI `9001` | `services/minio.yml` |
 | Meilisearch | Search engine (lightweight) | `7700` | `services/meilisearch.yml` |
@@ -76,12 +77,12 @@ Each row points to `services/<name>.yml`.
 - **Pin major.minor** in every `image:` line. Patch updates are safe; major bumps are deliberate.
 - **Always include healthcheck**. No service is allowed to be opaque about readiness.
 - **Default to dev**. Prod transforms are explicit (see `prod-vs-dev.md`).
-- **Email-in-dev defaults to MailHog**. The user must opt OUT of capture-only email for dev — never silently route to a real SMTP.
+- **Email-in-dev defaults to Mailpit**. The user must opt OUT of capture-only email for dev — never silently route to a real SMTP.
 - **Secrets never in the recipe**. Env vars reference `.env`; defaults in the recipe are OK only for non-secret config.
 
 ## Inspired by
 
-Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `redis`, `mailhog/mailhog`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
+Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `pgvector/pgvector`, `redis`, `axllent/mailpit`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
 
 ## Structured Return
 

package/scaffold/skills/docker-compose-recipes/references/compose-composition.md

@@ -4,7 +4,7 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
 
 ## The merge algorithm
 
-1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres, redis, mailhog, minio]`.
+1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres-pgvector, mailpit, minio]`.
 2. **Read each `services/<name>.yml`** as a standalone fragment. Each file declares ONE top-level service block (e.g., `postgres:`) plus comments at the bottom describing the volumes block to merge.
 3. **Concatenate under a single `services:` map.** Indent each block under `services:` in the final file. Order does not matter for compose, but for readability sort by tier: storage → cache/queue → search → email → observability → proxy.
 4. **Collect the volumes.** Each recipe's comments list the named volumes it needs. Aggregate them under a top-level `volumes:` block. Example:
@@ -31,7 +31,7 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
          condition: service_healthy
    ```
 
-8. **Add the app service(s) at the end.** For monorepo projects, declare an `api` service (and `web` if backend serves the frontend) that builds from the local Dockerfile.dev and binds the source as a volume for hot reload.
+8. **Apply the selected dev topology.** For `everything in Compose`, add the app service(s) at the end and bind source for hot reload. For `apps on host`, do not generate app services or Dockerfile.dev files; expose only infrastructure ports and point application-facing env vars at `localhost`.
 
 ## Final file shape
 
@@ -42,15 +42,15 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
 services:
   # --- storage tier ---
   postgres:
-    # ... contents from services/postgres.yml
+    # ... contents from services/postgres-pgvector.yml
 
   # --- cache tier ---
   redis:
     # ... contents from services/redis.yml
 
   # --- email-in-dev (capture only) ---
-  mailhog:
-    # ... contents from services/mailhog.yml
+  mailpit:
+    # ... contents from services/mailpit.yml
 
   # --- object storage ---
   minio:
@@ -72,8 +72,8 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
-      mailhog:
-        condition: service_started
+      mailpit:
+        condition: service_healthy
       minio:
         condition: service_healthy
 

package/scaffold/skills/docker-compose-recipes/references/env-conventions.md

@@ -23,7 +23,9 @@ POSTGRES_PORT=5432
 DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
 ```
 
-Compose performs variable substitution in `.env` references, so the application sees `DATABASE_URL` already-resolved.
+Compose performs variable substitution in `.env` references. When the application also runs in Compose, use service DNS such as `postgres`; when applications run on the host, the committed example must use `localhost` and the published host port instead.
+
+For the PostgreSQL + pgvector recipe, use the same connection variables. The image provides the extension binaries, but `CREATE EXTENSION IF NOT EXISTS vector` belongs in the application's reviewed migrations, not container startup scripts.
 
 ## What goes in `.env.example` vs `.env`
 

package/scaffold/skills/docker-compose-recipes/references/healthcheck-patterns.md

@@ -13,7 +13,7 @@ Every recipe ships a healthcheck. App services that depend on infra MUST gate st
 | RabbitMQ | `rabbitmq-diagnostics ping` | Built-in; takes ~30s to be ready, hence `start_period: 30s` |
 | LocalStack | `curl -sf http://localhost:4566/_localstack/health \| grep -q running` | Internal endpoint reports per-service readiness |
 | MailHog | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
-| Mailpit | `wget --spider http://localhost:8025` | Same |
+| Mailpit | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
 | smtp4dev | `wget --spider http://localhost:80` | UI on internal port 80 |
 | MinIO | `curl -f http://localhost:9000/minio/health/live` | Documented liveness endpoint |
 | Meilisearch | `curl -f http://localhost:7700/health` | Documented |
@@ -41,11 +41,11 @@ api:
       condition: service_healthy   # waits for the healthcheck to pass
     redis:
       condition: service_healthy
-    mailhog:
-      condition: service_started   # MailHog is light enough that started == ready
+    mailpit:
+      condition: service_healthy
 ```
 
-`service_healthy` is the strictest gate — no traffic until the healthcheck has passed at least once. Use it for all data stores. Use `service_started` only for stateless services (proxy, mail capture).
+`service_healthy` is the strictest gate — no traffic until the healthcheck has passed at least once. Use it for every dependency that declares a healthcheck, including Mailpit. Use `service_started` only when a dependency has no healthcheck to gate on.
 
 ## Common mistakes
 

package/scaffold/skills/docker-compose-recipes/services/mailpit.yml

@@ -1,9 +1,9 @@
-# Mailpit — modern alternative to MailHog (active maintenance, full-text search, REST API)
+# Mailpit — maintained email capture for local development
 # Env vars: MAILPIT_SMTP_PORT (default 1025), MAILPIT_UI_PORT (default 8025)
-# Application-side SMTP config: same as MailHog (drop-in replacement)
+# Application-side SMTP config: SMTP_HOST=mailpit; SMTP_PORT=1025
 
 mailpit:
-  image: axllent/mailpit:latest
+  image: axllent/mailpit:v1.30
   restart: unless-stopped
   ports:
     - "${MAILPIT_SMTP_PORT:-1025}:1025"
@@ -24,4 +24,4 @@ mailpit:
 #   mailpit_data: {}
 #
 # Prod notes:
-# - DEV ONLY. Do not ship to prod. See mailhog.yml notes for prod email guidance.
+# - DEV ONLY. Do not ship to prod; replace it with a real SMTP relay or transactional email API.

package/scaffold/skills/docker-compose-recipes/services/postgres-pgvector.yml

@@ -0,0 +1,31 @@
+# PostgreSQL 18 + pgvector 0.8.2 — relational and vector database
+# Env vars: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_PORT (default 5432)
+# Application-side: derive DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+# The image ships pgvector; create the extension in an application migration with: CREATE EXTENSION IF NOT EXISTS vector;
+
+postgres:
+  image: pgvector/pgvector:0.8.2-pg18
+  restart: unless-stopped
+  environment:
+    POSTGRES_USER: ${POSTGRES_USER:-app}
+    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}
+    POSTGRES_DB: ${POSTGRES_DB:-app}
+  ports:
+    - "${POSTGRES_PORT:-5432}:5432"
+  volumes:
+    - postgres_data:/var/lib/postgresql
+  healthcheck:
+    test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app} -d ${POSTGRES_DB:-app}"]
+    interval: 5s
+    timeout: 3s
+    retries: 10
+    start_period: 5s
+
+# volumes block to merge:
+# volumes:
+#   postgres_data: {}
+#
+# Prod notes:
+# - Use a current patch release derived from PostgreSQL 18 and pgvector 0.8.2 or newer compatible patch.
+# - Move POSTGRES_PASSWORD to a secret and remove the public port mapping.
+# - Keep CREATE EXTENSION and vector indexes in reviewed application migrations.