Refactor scan-site and security-review skills for improved user experience and code clarity

- Updated SKILL.md for scan-site to streamline user options and remove unnecessary confirmation steps before scanning.
- Enhanced get-latest-report.js to improve error handling and modularize the main function.
- Refactored poll-deep-scan.js to introduce better timeout handling and improve readability.
- Simplified start-deep-scan.js by consolidating argument parsing and error handling.
- Transformed transform-report.js to improve report parsing and error messaging, ensuring better handling of malformed reports.
- Revised security-review SKILL.md to reduce phases from seven to six, clarifying workflow and user interactions.
- Updated flow.md to reflect changes in the security-review skill phases and improve clarity on user-facing beats.

Author: Ramachandran R

plugins/power-pages/scripts/build-review-data.js

@@ -1,12 +1,34 @@
 #!/usr/bin/env node
-// Consolidates per-skill review JSON files into the data file consumed by render-review.js.
-// Run with --help for flags.
 
 const fs = require('fs');
 const path = require('path');
 
-if (process.argv.includes('--help')) {
-  process.stdout.write(`build-review-data.js — Consolidate per-skill JSON into a single review data file.
+const REQUIRED_FLAGS = [
+  'reportName',
+  'inputDir',
+  'siteName',
+  'goalLabel',
+  'scopeLabel',
+  'output',
+];
+
+const SECTION_MAP = {
+  'scan-site.json': { id: 'site-scan', label: 'Live Site Scan', icon: '◐' },
+  'manage-headers.json': { id: 'headers', label: 'Browser Headers', icon: '◑' },
+  'manage-firewall.json': {
+    id: 'firewall',
+    label: 'Web Application Firewall',
+    icon: '◆',
+  },
+  'audit-permissions.json': { id: 'permissions', label: 'Roles & Permissions', icon: '◇' },
+  'setup-auth.json': { id: 'auth', label: 'Access & Identity', icon: '◈' },
+};
+
+// Every severity a finding may carry. `pass` is shown as a stat but excluded
+// from the issue count by the report template.
+const SEVERITIES = ['critical', 'high', 'warning', 'medium', 'info', 'low', 'pass'];
+
+const HELP = `build-review-data.js — Consolidate per-skill JSON into a single review data file.
 
 Usage:
   node build-review-data.js --reportName <name> --inputDir <dir> --siteName <name> --goalLabel <label> --scopeLabel <label> --output <path> [--summary <text>] [--nextStepsFile <path>]
@@ -25,143 +47,148 @@ Flags:
 Exit codes:
   0  Success (data file written; status JSON on stdout)
   1  Invocation error (missing flag or unreadable input dir)
-
-Examples:
-  node build-review-data.js --reportName "<report-name>" --inputDir <input-dir> --siteName "<site-name>" --goalLabel "<goal-label>" --scopeLabel "<scope-label>" --output <output-file>
-  node build-review-data.js --reportName "<report-name>" --inputDir <input-dir> --siteName "<site-name>" --goalLabel "<goal-label>" --scopeLabel "<scope-label>" --summary "<summary-text>" --nextStepsFile <next-steps-file> --output <output-file>
-`);
-  process.exit(0);
-}
+`;
 
 function getArg(name, fallback = null) {
   const idx = process.argv.indexOf('--' + name);
   return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : fallback;
 }
 
-const reportName = getArg('reportName');
-const inputDir = getArg('inputDir');
-const siteName = getArg('siteName');
-const goalLabel = getArg('goalLabel');
-const scopeLabel = getArg('scopeLabel');
-const outputPath = getArg('output');
-const summaryArg = getArg('summary', '');
-const nextStepsFile = getArg('nextStepsFile');
-
-for (const [name, value] of [['reportName', reportName], ['inputDir', inputDir], ['siteName', siteName], ['goalLabel', goalLabel], ['scopeLabel', scopeLabel], ['output', outputPath]]) {
-  if (!value) {
-    process.stderr.write(`Missing required flag: --${name}\n`);
-    process.exit(1);
+function readNextSteps(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return Array.isArray(parsed) ? parsed.filter((x) => typeof x === 'string') : [];
+  } catch (err) {
+    process.stderr.write(`Could not read next-steps file: ${err.message}\n`);
+    return [];
   }
 }
 
-if (!fs.existsSync(inputDir)) {
-  process.stderr.write(`Input dir not found: ${inputDir}\n`);
-  process.exit(1);
+function formatGeneratedAt(now) {
+  const pad = (n) => String(n).padStart(2, '0');
+  // Intl returns "GMT+5:30" on some platforms; keep only the short abbreviation when present.
+  const tzName =
+    new Intl.DateTimeFormat(undefined, { timeZoneName: 'short' })
+      .formatToParts(now)
+      .find((p) => p.type === 'timeZoneName')?.value || '';
+  const stamp =
+    `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
+    `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+  return tzName ? `${stamp} ${tzName}` : stamp;
 }
 
-const SECTION_MAP = {
-  'scan-site.json':         { id: 'site-scan',   label: 'Live Site Scan',           icon: '◐' },
-  'manage-headers.json':    { id: 'headers',     label: 'Browser Headers',          icon: '◑' },
-  'manage-firewall.json':   { id: 'firewall',    label: 'Web Application Firewall', icon: '◆' },
-  'audit-permissions.json': { id: 'permissions', label: 'Roles & Permissions',      icon: '◇' },
-  'setup-auth.json':        { id: 'auth',        label: 'Access & Identity',        icon: '◈' },
-};
-
-// Severities that may appear on findings — ordered by precedence (most severe first).
-// pass is excluded from the "issue" count but still shown as its own stat.
-const SEVERITIES = ['critical', 'high', 'warning', 'medium', 'info', 'low', 'pass'];
-
-const sections = [];
-const totals = Object.fromEntries(SEVERITIES.map(s => [s, 0]));
-
-for (const fileName of fs.readdirSync(inputDir).sort()) {
-  if (!fileName.endsWith('.json')) continue;
-  if (fileName === path.basename(outputPath)) continue;
-  const filePath = path.join(inputDir, fileName);
-
-  let raw;
-  try {
-    raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (err) {
-    process.stderr.write(`Skipping ${fileName}: ${err.message}\n`);
-    continue;
-  }
-
-  // Skip files that aren't recognized sections (intermediate tool outputs, helper files like next-steps).
-  if (!SECTION_MAP[fileName]) continue;
-  const meta = SECTION_MAP[fileName];
+function skippedSection(meta, reason) {
+  return {
+    id: meta.id,
+    icon: meta.icon,
+    label: meta.label,
+    description: '',
+    findings: [
+      {
+        id: `${meta.id}-skipped`,
+        severity: 'info',
+        title: `${meta.label} check was skipped`,
+        details: reason || 'No additional detail.',
+      },
+    ],
+    details: {},
+  };
+}
 
-  if (raw && raw.status === 'skipped') {
+function buildSections(inputDir, outputBasename) {
+  const sections = [];
+  const totals = Object.fromEntries(SEVERITIES.map((s) => [s, 0]));
+
+  for (const fileName of fs.readdirSync(inputDir).sort()) {
+    if (!fileName.endsWith('.json')) continue;
+    if (fileName === outputBasename) continue;
+    const meta = SECTION_MAP[fileName];
+    if (!meta) continue;
+
+    const filePath = path.join(inputDir, fileName);
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (err) {
+      process.stderr.write(`Skipping ${fileName}: ${err.message}\n`);
+      continue;
+    }
+
+    if (raw?.status === 'skipped') {
+      sections.push(skippedSection(meta, raw.reason));
+      totals.info += 1;
+      continue;
+    }
+
+    const findings = Array.isArray(raw?.findings) ? raw.findings : [];
     sections.push({
       id: meta.id,
       icon: meta.icon,
       label: meta.label,
       description: '',
-      findings: [{
-        id: `${meta.id}-skipped`,
-        severity: 'info',
-        title: `${meta.label} check was skipped`,
-        details: raw.reason || 'No additional detail.',
-      }],
-      details: {},
+      findings,
+      details: raw?.details || {},
     });
-    totals.info += 1;
-    continue;
+
+    for (const f of findings) {
+      if (f.severity && totals[f.severity] !== undefined) totals[f.severity] += 1;
+    }
   }
 
-  const findings = Array.isArray(raw?.findings) ? raw.findings : [];
-  const details = raw?.details || {};
+  return { sections, totals };
+}
 
-  sections.push({
-    id: meta.id,
-    icon: meta.icon,
-    label: meta.label,
-    description: '',
-    findings,
-    details,
-  });
+function main() {
+  if (process.argv.includes('--help')) {
+    process.stdout.write(HELP);
+    return;
+  }
 
-  for (const f of findings) {
-    if (f.severity && totals[f.severity] !== undefined) totals[f.severity] += 1;
+  const values = Object.fromEntries(REQUIRED_FLAGS.map((flag) => [flag, getArg(flag)]));
+  for (const flag of REQUIRED_FLAGS) {
+    if (!values[flag]) {
+      process.stderr.write(`Missing required flag: --${flag}\n`);
+      process.exit(1);
+    }
   }
-}
 
-let nextSteps = [];
-if (nextStepsFile) {
-  try {
-    const ns = JSON.parse(fs.readFileSync(nextStepsFile, 'utf8'));
-    if (Array.isArray(ns)) nextSteps = ns.filter(x => typeof x === 'string');
-  } catch (err) {
-    process.stderr.write(`Could not read next-steps file: ${err.message}\n`);
+  const inputDir = values.inputDir;
+  const outputPath = values.output;
+  if (!fs.existsSync(inputDir)) {
+    process.stderr.write(`Input dir not found: ${inputDir}\n`);
+    process.exit(1);
   }
-}
 
-const now = new Date();
-const pad = (n) => String(n).padStart(2, '0');
-// Local-timezone short name (e.g. "IST", "PST"). Intl gives "GMT+5:30" on some platforms — strip to just the abbreviation when present.
-const tzName = new Intl.DateTimeFormat(undefined, { timeZoneName: 'short' }).formatToParts(now).find(p => p.type === 'timeZoneName')?.value || '';
-const generatedAt = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}${tzName ? ' ' + tzName : ''}`;
-
-const payload = {
-  REPORT_NAME: reportName,
-  SITE_NAME: siteName,
-  GOAL_LABEL: goalLabel,
-  SCOPE_LABEL: scopeLabel,
-  GENERATED_AT: generatedAt,
-  REVIEW_DATA: {
-    summary: summaryArg || '',
-    totals,
-    sections,
-    nextSteps,
-  },
-};
+  const summary = getArg('summary', '');
+  const nextStepsFile = getArg('nextStepsFile');
+  const nextSteps = nextStepsFile ? readNextSteps(nextStepsFile) : [];
+
+  const { sections, totals } = buildSections(inputDir, path.basename(outputPath));
+
+  const payload = {
+    REPORT_NAME: values.reportName,
+    SITE_NAME: values.siteName,
+    GOAL_LABEL: values.goalLabel,
+    SCOPE_LABEL: values.scopeLabel,
+    GENERATED_AT: formatGeneratedAt(new Date()),
+    REVIEW_DATA: { summary: summary || '', totals, sections, nextSteps },
+  };
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, JSON.stringify(payload, null, 2));
+
+  process.stdout.write(
+    JSON.stringify({
+      status: 'ok',
+      outputPath,
+      totals,
+      sectionsCount: sections.length,
+    }) + '\n'
+  );
+}
 
-fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-fs.writeFileSync(outputPath, JSON.stringify(payload, null, 2));
+if (require.main === module) {
+  main();
+}
 
-process.stdout.write(JSON.stringify({
-  status: 'ok',
-  outputPath,
-  totals,
-  sectionsCount: sections.length,
-}) + '\n');
+module.exports = { buildSections, formatGeneratedAt, SECTION_MAP, SEVERITIES };