@brunosps00/dev-workflow 0.0.3 → 0.0.5

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

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+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;
+}
+
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(projectRoot, "package-lock.json"))) return "npm";
+  if (fs.existsSync(path.join(projectRoot, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+function updateManifest(manifestPath, patch) {
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const next = {
+    ...manifest,
+    execution: {
+      ...(manifest.execution ?? {}),
+      ...patch,
+    },
+  };
+  fs.writeFileSync(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
+}
+
+function detectTestDir(playwrightConfig) {
+  const content = fs.readFileSync(playwrightConfig, "utf8");
+  const match = content.match(/testDir:\s*"([^"]+)"/);
+  return match?.[1] ?? "e2e";
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function escapeForTemplate(value) {
+  return JSON.stringify(value);
+}
+
+function parseResolution(rawValue) {
+  const normalized = String(rawValue ?? "").trim().toLowerCase();
+  if (!normalized || normalized === "fullhd") {
+    return { width: 1920, height: 1080, label: "1920x1080" };
+  }
+
+  const match = normalized.match(/^(\d{3,5})x(\d{3,5})$/);
+  if (!match) {
+    return { width: 1920, height: 1080, label: "1920x1080" };
+  }
+
+  return {
+    width: Number(match[1]),
+    height: Number(match[2]),
+    label: `${Number(match[1])}x${Number(match[2])}`,
+  };
+}
+
+function createTemporaryPlaywrightConfig({
+  generatedDir,
+  flowDir,
+  baseUrl,
+  browserName,
+  resolution,
+}) {
+  const rawArtifactsDir = path.join(flowDir, "evidence", "playwright-artifacts");
+  ensureDir(rawArtifactsDir);
+
+  const configPath = path.join(generatedDir, "playwright.functional-doc.config.mjs");
+  const content = `import { defineConfig } from "@playwright/test";
+
+const rawOutputDir = ${escapeForTemplate(rawArtifactsDir)};
+const baseURL = process.env.BASE_URL ?? ${escapeForTemplate(baseUrl)};
+const generatedDir = ${escapeForTemplate(generatedDir)};
+
+export default defineConfig({
+  testDir: generatedDir,
+  outputDir: rawOutputDir,
+  fullyParallel: false,
+  retries: 0,
+  workers: 1,
+  reporter: "line",
+  use: {
+    baseURL,
+    video: {
+      mode: "on",
+      size: { width: ${resolution.width}, height: ${resolution.height} },
+    },
+    screenshot: "on",
+    trace: "retain-on-failure",
+    viewport: { width: ${resolution.width}, height: ${resolution.height} },
+  },
+  projects: [
+    {
+      name: ${escapeForTemplate(browserName)},
+      use: { browserName: ${escapeForTemplate(browserName)} },
+    },
+  ],
+});
+`;
+  fs.writeFileSync(configPath, content);
+  return { configPath, rawArtifactsDir };
+}
+
+function collectFilesByExtension(rootDir, extension) {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+
+  const found = [];
+  const queue = [rootDir];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(absolutePath);
+        continue;
+      }
+      if (absolutePath.toLowerCase().endsWith(extension.toLowerCase())) {
+        found.push(absolutePath);
+      }
+    }
+  }
+  return found.sort();
+}
+
+function copyArtifacts(flowDir, slug, rawArtifactsDir) {
+  const videoDir = path.join(flowDir, "evidence", "videos");
+  const screenshotDir = path.join(flowDir, "evidence", "screenshots");
+  ensureDir(videoDir);
+  ensureDir(screenshotDir);
+
+  const videos = collectFilesByExtension(rawArtifactsDir, ".webm");
+  const screenshots = collectFilesByExtension(rawArtifactsDir, ".png");
+
+  const copiedVideos = videos.map((sourcePath, index) => {
+    const destinationPath = path.join(videoDir, `${slug}${videos.length > 1 ? `-${index + 1}` : ""}.webm`);
+    fs.copyFileSync(sourcePath, destinationPath);
+    return destinationPath;
+  });
+
+  const copiedScreenshots = screenshots.map((sourcePath, index) => {
+    const destinationPath = path.join(screenshotDir, `${slug}${screenshots.length > 1 ? `-${index + 1}` : ""}.png`);
+    fs.copyFileSync(sourcePath, destinationPath);
+    return destinationPath;
+  });
+
+  return {
+    videos: copiedVideos,
+    screenshots: copiedScreenshots,
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.flowDir) {
+    throw new Error("Missing required argument: --flow-dir");
+  }
+
+  const flowDir = path.resolve(args.flowDir);
+  const manifestPath = path.join(flowDir, "manifest.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const projectRoot = path.resolve(manifest.project);
+  const scriptPath = path.resolve(manifest.outputs.script);
+  const packageManager = detectPackageManager(projectRoot);
+  const browserName = args.browserName || "chromium";
+  const resolution = parseResolution(
+    args.videoResolution
+    ?? manifest.artifacts?.human_final?.resolution
+    ?? manifest.videoResolution
+    ?? "fullhd"
+  );
+  const playwrightConfig = ["playwright.config.ts", "playwright.config.js"]
+    .map((file) => path.join(projectRoot, file))
+    .find((file) => fs.existsSync(file));
+
+  if (!playwrightConfig) {
+    updateManifest(manifestPath, {
+      status: "blocked",
+      reason: "Playwright configuration not found",
+    });
+    process.stdout.write("Playwright configuration not found.\n");
+    process.exit(0);
+  }
+
+  const testDir = detectTestDir(playwrightConfig);
+  const generatedDir = path.join(projectRoot, testDir, ".functional-doc-generated");
+  ensureDir(generatedDir);
+  const materializedScriptPath = path.join(generatedDir, path.basename(scriptPath));
+  fs.copyFileSync(scriptPath, materializedScriptPath);
+  const slug = path.basename(scriptPath, path.extname(scriptPath));
+  const { configPath: temporaryConfigPath, rawArtifactsDir } = createTemporaryPlaywrightConfig({
+    generatedDir,
+    flowDir,
+    baseUrl: manifest.baseUrl,
+    browserName,
+    resolution,
+  });
+
+  const commandArgs = ["exec", "playwright", "test", materializedScriptPath, "--config", temporaryConfigPath];
+  if (args.listOnly) {
+    commandArgs.push("--list");
+  }
+
+  const result = spawnSync(
+    packageManager,
+    commandArgs,
+    {
+      cwd: projectRoot,
+      env: {
+        ...process.env,
+        BASE_URL: manifest.baseUrl,
+      },
+      encoding: "utf8",
+    },
+  );
+
+  const logDir = path.join(flowDir, "evidence", "logs");
+  fs.mkdirSync(logDir, { recursive: true });
+  fs.writeFileSync(path.join(logDir, "playwright.stdout.log"), result.stdout ?? "");
+  fs.writeFileSync(path.join(logDir, "playwright.stderr.log"), result.stderr ?? "");
+
+  const copiedArtifacts = args.listOnly
+    ? { videos: [], screenshots: [] }
+    : copyArtifacts(flowDir, slug, rawArtifactsDir);
+
+  updateManifest(manifestPath, {
+    status: args.listOnly ? (result.status === 0 ? "listed" : "list_failed") : (result.status === 0 ? "passed" : "failed"),
+    command: `${packageManager} ${commandArgs.join(" ")}`,
+    exitCode: result.status ?? 1,
+    videoResolution: resolution.label,
+    materializedScript: materializedScriptPath,
+    temporaryConfig: temporaryConfigPath,
+    video: copiedArtifacts.videos[0] ?? null,
+    videos: copiedArtifacts.videos,
+    screenshots: copiedArtifacts.screenshots,
+    logs: [
+      path.join(logDir, "playwright.stdout.log"),
+      path.join(logDir, "playwright.stderr.log"),
+    ],
+  });
+
+  process.stdout.write(result.stdout ?? "");
+  process.stderr.write(result.stderr ?? "");
+  process.exit(result.status ?? 1);
+}
+
+main();

package/scaffold/en/commands/help.md

@@ -1,289 +0,0 @@
-<system_instructions>
-You are a workspace help assistant. When invoked, present the user with a complete guide of available commands, their integration flows, and when to use each one.
-
-## Behavior
-
-- If invoked without arguments (`/help`): show the complete guide below
-- If invoked with an argument (`/help create-prd`): show only the detailed section for that command
-
----
-
-# Command Guide - AI Dev Workflow
-
-## Overview
-
-This workspace uses an AI command system that automates the full development cycle: from planning (PRD) to merge (PR). Commands are in `ai/commands/` and are accessible in supported AI CLIs (e.g., Codex, Claude Code, OpenCode, GitHub Copilot), using the CLI prefix (`/command` or `$command`).
-
-## Main Development Flow
-
-```
-┌──────────────┐     ┌─────────────────┐     ┌───────────────┐
-│ /create-prd  │────>│/create-techspec │────>│ /create-tasks │
-│ (WHAT)       │     │ (HOW)           │     │ (WHEN)        │
-└──────────────┘     └─────────────────┘     └───────┬───────┘
-                                                     │
-                                       ┌─────────────┴─────────────┐
-                                       ▼                           ▼
-                              ┌────────────────┐         ┌─────────────────┐
-                              │  /run-task     │         │  /run-plan      │
-                              │ (one at a time)│         │  (all auto)     │
-                              └───────┬────────┘         └────────┬────────┘
-                                      │                           │
-                                      └─────────┬─────────────────┘
-                                                │
-                                                ▼
-                                      ┌─────────────────┐
-                                      │ Validation Lv 1 │ (automatic, embedded)
-                                      │ criteria+tests  │
-                                      └────────┬────────┘
-                                               │
-                                ┌──────────────┼──────────────┐
-                                ▼              ▼              ▼
-                      ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐
-                      │  /run-qa     │ │/review-impl. │ │  /code-review       │
-                      │ (visual QA)  │ │(PRD compliance│ │ (formal code review)│
-                      └──────────────┘ │  Level 2)    │ │ (Level 3)           │
-                                       └──────────────┘ └─────────────────────┘
-                                                │
-                                ┌───────────────┴───────────────┐
-                                ▼                               ▼
-                      ┌──────────────┐                 ┌────────────────┐
-                      │  /commit     │                 │ /commit-all    │
-                      │ (one project)│                 │ (submodules)   │
-                      └──────┬───────┘                 └───────┬────────┘
-                             │                                 │
-                             └────────────┬────────────────────┘
-                                          ▼
-                                ┌──────────────────┐
-                                │  /generate-pr    │
-                                │ (push + PR + URL)│
-                                └──────────────────┘
-                                          │
-                                          ▼
-                                ┌──────────────────┐
-                                │  /archive-prd    │
-                                │  (post-merge)    │
-                                └──────────────────┘
-```
-
-## Command Table
-
-### Planning
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/brainstorm` | Facilitates structured ideation before PRD or implementation | Problem, idea, or context | Options + trade-offs + recommendation |
-| `/create-prd` | Creates PRD with min. 7 clarification questions | Feature description | `ai/spec/prd-[name]/prd.md` |
-| `/create-techspec` | Creates technical specification from the PRD | PRD path | `ai/spec/prd-[name]/techspec.md` |
-| `/create-tasks` | Breaks PRD+TechSpec into tasks (max 2 RFs/task) | PRD path | `ai/spec/prd-[name]/tasks.md` + `*_task.md` |
-
-### Execution
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/run-task` | Implements ONE task + Level 1 validation + commit | PRD path | Code + commit |
-| `/run-plan` | Executes ALL tasks + final Level 2 review | PRD path | Code + commits + report |
-| `/bugfix` | Analyzes and fixes bugs (bug vs feature triage) | Target + description | Fix + commit OR PRD (if feature) |
-| `/fix-qa` | Fixes documented QA bugs and retests with evidence | PRD path | Code + `QA/bugs.md` + `QA/qa-report.md` updated |
-
-### Research
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/analyze-project` | Analyzes project structure and generates documentation | Project path | Architecture overview |
-| `/deep-research` | Multi-source research with citation tracking and verification | Topic or question | Research report with bibliography |
-
-### Quality (3 Levels)
-
-| Level | Command | When | Generates Report? |
-|-------|---------|------|-------------------|
-| **1** | *(embedded in /run-task)* | After each task | No (terminal output) |
-| **2** | `/review-implementation` | After all tasks / manual | Yes (formatted output) |
-| **3** | `/code-review` | Before PR / manual | Yes (`code-review.md`) |
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/run-qa` | Visual QA with Playwright MCP + accessibility | PRD path | `QA/qa-report.md` + `QA/screenshots/` + `QA/logs/` |
-| `/review-implementation` | Compares PRD vs code (RFs, endpoints, tasks) | PRD path | Gap report |
-| `/code-review` | Formal code review (quality, rules, tests) | PRD path | `code-review.md` |
-| `/refactoring-analysis` | Audit code smells and refactoring opportunities (Fowler's catalog) | PRD path | `refactoring-analysis.md` |
-
-### Versioning
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/commit` | Semantic commit (Conventional Commits) | - | Commit |
-| `/commit-all` | Commit across all submodules (inside-out) | - | Commits |
-| `/generate-pr` | Push + create PR + copy body + open URL | Target branch | PR on GitHub |
-
-### Maintenance
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/list-tasks` | Lists tasks and progress for a PRD | PRD path | Status table |
-| `/task-summary` | Shows details of a task without executing | Number + path | Task summary |
-| `/archive-prd` | Moves completed PRD to `ai/archived/prd/` | PRD path | Archived PRD |
-| `/help` | This command guide | (optional) command | This document |
-
-## Review Architecture (3 Levels)
-
-```
-LEVEL 1 - Post-Task Validation (automatic, lightweight)
-├── Embedded in /run-task
-├── Verifies task acceptance criteria
-├── Runs tests (pnpm test / npm test)
-├── Checks basic patterns (types, imports)
-├── No report file
-└── If fails: PAUSES execution
-
-LEVEL 2 - PRD Compliance (/review-implementation)
-├── Compares ALL RFs from PRD vs actual code
-├── Verifies ALL endpoints from TechSpec
-├── Checks real status of each task (ignores checkboxes)
-├── Identifies gaps, partial implementations, extra code
-├── Called automatically at end of /run-plan
-└── Available manually
-
-LEVEL 3 - Formal Code Review (/code-review)
-├── Everything from Level 2 +
-├── Quality analysis (SOLID, DRY, complexity, security)
-├── Conformance with project rules (ai/rules/)
-├── Tests with coverage
-├── Generates code-review.md in PRD directory
-└── Status: APPROVED / WITH CAVEATS / REJECTED
-```
-
-## Common Flows
-
-### New Feature (Full)
-```bash
-/brainstorm "initial idea"                      # 0. Explore options and trade-offs
-/create-prd                                     # 1. Describe the feature
-/create-techspec ai/spec/prd-name              # 2. Generate tech spec
-/create-tasks ai/spec/prd-name                 # 3. Break into tasks
-/run-plan ai/spec/prd-name                     # 4. Execute all (includes Level 1+2)
-/refactoring-analysis ai/spec/prd-name         # 5. Audit code smells (optional)
-/code-review ai/spec/prd-name                  # 6. Formal code review (Level 3)
-/generate-pr main                               # 7. Create PR
-/archive-prd ai/spec/prd-name                  # 8. After merge
-```
-
-### New Feature (Incremental)
-```bash
-/brainstorm "initial idea"                      # 0. Explore options and trade-offs
-/create-prd                                     # 1. PRD
-/create-techspec ai/spec/prd-name              # 2. TechSpec
-/create-tasks ai/spec/prd-name                 # 3. Tasks
-/run-task ai/spec/prd-name                     # 4. Task 1 (with Level 1)
-/run-task ai/spec/prd-name                     # 5. Task 2 (with Level 1)
-# ... repeat for each task
-/review-implementation ai/spec/prd-name        # 6. PRD review (Level 2)
-/code-review ai/spec/prd-name                  # 7. Code review (Level 3)
-/generate-pr main                               # 8. PR
-```
-
-### Simple Bug
-```bash
-/bugfix "bug description"                       # Analyze and fix
-/commit                                         # Commit the fix
-/generate-pr main                               # PR
-```
-
-### Complex Bug
-```bash
-/bugfix "description" --analysis                # Generate analysis document
-/create-techspec ai/spec/bugfix-name           # TechSpec for the fix
-/create-tasks ai/spec/bugfix-name              # Tasks for the fix
-/run-plan ai/spec/bugfix-name                  # Execute all
-/generate-pr main                               # PR
-```
-
-### Visual QA (Frontend)
-```bash
-/run-qa ai/spec/prd-name                       # QA with Playwright MCP
-# If bugs found:
-/bugfix "description"                           # Fix each bug
-/fix-qa ai/spec/prd-name                       # Fix + retest full cycle
-```
-
-### Deep Research
-```bash
-/deep-research "topic or question"              # Multi-source research with citations
-```
-
-## File Structure
-
-```
-your-project/
-├── ai/
-│   ├── commands/              # Source of truth for commands
-│   │   ├── help.md            # This guide
-│   │   ├── brainstorm.md
-│   │   ├── create-prd.md
-│   │   ├── create-techspec.md
-│   │   ├── create-tasks.md
-│   │   ├── run-task.md
-│   │   ├── run-plan.md
-│   │   ├── run-qa.md
-│   │   ├── code-review.md
-│   │   ├── refactoring-analysis.md
-│   │   ├── review-implementation.md
-│   │   ├── analyze-project.md
-│   │   ├── deep-research.md
-│   │   ├── bugfix.md
-│   │   ├── commit.md
-│   │   ├── commit-all.md
-│   │   ├── generate-pr.md
-│   │   └── archive-prd.md
-│   ├── templates/             # Document templates
-│   │   ├── prd-template.md
-│   │   ├── techspec-template.md
-│   │   ├── tasks-template.md
-│   │   ├── task-template.md
-│   │   └── bugfix-template.md
-│   ├── rules/                 # Project-specific rules
-│   │   └── *.md
-│   ├── tasks/                 # Active PRDs and tasks
-│   │   └── prd-[name]/
-│   │       ├── prd.md
-│   │       ├── techspec.md
-│   │       ├── tasks.md
-│   │       └── *_task.md
-│   └── archived/prd/          # Completed PRDs
-├── .codex/skills/             # Codex skills
-├── .claude/skills/            # Claude Code skills
-├── .opencode/commands/        # OpenCode commands
-└── .github/copilot-instructions.md  # Copilot instructions
-```
-
-## Tool Integration
-
-Commands work across multiple AI tools, all pointing to the same source `ai/commands/`:
-
-| Tool | Location | Format |
-|------|----------|--------|
-| **Codex CLI** | `.codex/skills/*/SKILL.md` | Skill referencing `ai/commands/` |
-| **Claude Code** | `.claude/skills/*/SKILL.md` | Skill referencing `ai/commands/` |
-| **OpenCode** | `.opencode/commands/*.md` | Command referencing `ai/commands/` |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | Instructions listing the commands |
-
-## FAQ
-
-**Q: What is the difference between `/run-task` and `/run-plan`?**
-- `/run-task` executes ONE task with manual control between each one
-- `/run-plan` executes ALL automatically with a final review
-
-**Q: Do I need to run `/review-implementation` manually?**
-- Not if using `/run-plan` (already included). Yes if using `/run-task` incrementally.
-
-**Q: When to use `/code-review` vs `/review-implementation`?**
-- `/review-implementation` (Level 2): Checks if PRD RFs were implemented
-- `/code-review` (Level 3): Additionally analyzes code quality and generates a formal report
-
-**Q: Does `/bugfix` always fix directly?**
-- No. It performs triage. If it is a feature (not a bug), it redirects to `/create-prd`. If it is a complex bug, it can generate an analysis document with `--analysis`.
-
-**Q: When should I use `/deep-research`?**
-- For comprehensive multi-source analysis, technology comparisons, state-of-the-art reviews, or any topic requiring cited evidence. Not for simple lookups or debugging.
-
-</system_instructions>