Doc Image Sync

interface:
  display_name: "Doc Image Sync"
  short_description: "为原型需求文档生成截图并自动回写对应章节"
  default_prompt: "使用 $doc-image-sync 为当前需求文档补配图：优先识别原型中的 data-shot 锚点，必要时补最小交互动作，执行截图并回写到对应章节。"

#!/usr/bin/env node

import fs from 'fs';
import path from 'path';
import { chromium } from 'playwright';

const cwd = process.cwd();

function parseArgs(argv) {
  const args = {};
  for (let i = 2; i < argv.length; i += 1) {
    const current = argv[i];
    if (current === '--config') args.config = argv[++i];
    else if (current === '--id') args.id = argv[++i];
    else if (current === '--help' || current === '-h') args.help = true;
  }
  return args;
}

function ensureDir(filePath) {
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
}

function resolvePath(p) {
  return path.isAbsolute(p) ? p : path.resolve(cwd, p);
}

async function runAction(page, action) {
  switch (action.type) {
    case 'click':
      await page.locator(action.selector).first().click();
      return;
    case 'dblclick':
      await page.locator(action.selector).first().dblclick();
      return;
    case 'hover':
      await page.locator(action.selector).first().hover();
      return;
    case 'waitForSelector':
      await page.locator(action.selector).waitFor({ state: action.state || 'visible', timeout: action.timeout || 10000 });
      return;
    case 'waitForTimeout':
      await page.waitForTimeout(action.ms || 300);
      return;
    case 'evaluate':
      await page.evaluate(new Function(`return (${action.script})`)());
      return;
    case 'scrollTo':
      await page.locator(action.selector).scrollIntoViewIfNeeded();
      return;
    default:
      throw new Error(`Unsupported action type: ${action.type}`);
  }
}

async function main() {
  const args = parseArgs(process.argv);
  if (args.help || !args.config) {
    console.log('Usage: node capture-shots.mjs --config <config.json> [--id <shotId>]');
    process.exit(args.help ? 0 : 1);
  }

  const configPath = resolvePath(args.config);
  const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
  const shots = (raw.shots || []).filter((item) => !args.id || item.id === args.id);

  if (!shots.length) {
    throw new Error('No shots found to execute.');
  }

  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage({ viewport: { width: 1600, height: 1200 }, deviceScaleFactor: 1 });

  for (const shot of shots) {
    const pagePath = resolvePath(shot.pagePath);
    const imagePath = resolvePath(shot.imagePath);
    const url = `file://${pagePath}`;
    console.log(`Capturing ${shot.id} -> ${shot.imagePath}`);
    await page.goto(url);
    await page.waitForLoadState('domcontentloaded');
    await page.waitForTimeout(300);

    for (const action of shot.actions || []) {
      await runAction(page, action);
    }

    ensureDir(imagePath);

    if (shot.type === 'fullpage') {
      await page.screenshot({ path: imagePath, fullPage: true, type: 'png' });
    } else {
      const locator = page.locator(shot.selector).first();
      await locator.waitFor({ state: 'visible', timeout: 10000 });
      const box = await locator.boundingBox();
      if (!box || box.width < 4 || box.height < 4) {
        throw new Error(`Invalid bounding box for ${shot.id}: ${shot.selector}`);
      }

      const padding = shot.padding || {};
      const clip = {
        x: Math.max(0, box.x - (padding.left || 0)),
        y: Math.max(0, box.y - (padding.top || 0)),
        width: box.width + (padding.left || 0) + (padding.right || 0),
        height: box.height + (padding.top || 0) + (padding.bottom || 0)
      };

      await page.screenshot({ path: imagePath, clip, type: 'png' });
    }
  }

  await browser.close();
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

#!/usr/bin/env node

import crypto from 'crypto';
import fs from 'fs';
import path from 'path';

const cwd = process.cwd();

function parseArgs(argv) {
  const args = {
    headingLevel: 3,
    type: 'element'
  };

  for (let i = 2; i < argv.length; i += 1) {
    const current = argv[i];
    if (current === '--doc') args.doc = argv[++i];
    else if (current === '--page') args.page = argv[++i];
    else if (current === '--config') args.config = argv[++i];
    else if (current === '--image-dir') args.imageDir = argv[++i];
    else if (current === '--heading-level') args.headingLevel = Number(argv[++i] || 3);
    else if (current === '--type') args.type = argv[++i];
    else if (current === '--selector') args.selector = argv[++i];
    else if (current === '--help' || current === '-h') args.help = true;
  }

  return args;
}

function resolvePath(p) {
  return path.isAbsolute(p) ? p : path.resolve(cwd, p);
}

function toPosix(p) {
  return p.split(path.sep).join('/');
}

function toRelative(p) {
  return toPosix(path.relative(cwd, p));
}

function ensureDir(dirPath) {
  fs.mkdirSync(dirPath, { recursive: true });
}

function parseHeadings(content, headingLevel) {
  const headingToken = '#'.repeat(headingLevel);
  return content
    .split('\n')
    .map((line) => line.trim())
    .filter((line) => line.startsWith(`${headingToken} `));
}

function createId(docPath, heading, index) {
  const hash = crypto.createHash('md5').update(`${docPath}:${heading}`).digest('hex').slice(0, 6);
  return `shot-${hash}-${String(index + 1).padStart(2, '0')}`;
}

function buildDefaultImageDir(docPath) {
  const demandName = path.basename(path.dirname(docPath));
  return path.resolve(cwd, '附件', demandName, 'screenshots', 'latest');
}

function buildDefaultFileName(index) {
  return `shot-${String(index + 1).padStart(2, '0')}.png`;
}

function main() {
  const args = parseArgs(process.argv);
  if (args.help || !args.doc || !args.page || !args.config) {
    console.log('Usage: node init-shot-config.mjs --doc <doc.md> --page <page.html> --config <config.json> [--image-dir <dir>] [--heading-level <n>] [--type <fullpage|element|scenario>] [--selector <css>]');
    process.exit(args.help ? 0 : 1);
  }

  const docPath = resolvePath(args.doc);
  const pagePath = resolvePath(args.page);
  const configPath = resolvePath(args.config);
  const imageDir = resolvePath(args.imageDir || buildDefaultImageDir(docPath));

  const docContent = fs.readFileSync(docPath, 'utf8');
  const headings = parseHeadings(docContent, args.headingLevel);
  if (!headings.length) {
    throw new Error(`No level-${args.headingLevel} headings found in ${docPath}`);
  }

  let config = { shots: [] };
  if (fs.existsSync(configPath)) {
    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
    if (!Array.isArray(config.shots)) config.shots = [];
  }

  ensureDir(path.dirname(configPath));

  const existingKeys = new Set(
    config.shots.map((shot) => `${toRelative(resolvePath(shot.docPath))}::${shot.sectionHeading || ''}`)
  );

  const newShots = [];
  for (const [index, heading] of headings.entries()) {
    const key = `${toRelative(docPath)}::${heading}`;
    if (existingKeys.has(key)) continue;

    const shot = {
      id: createId(docPath, heading, index),
      docPath: toRelative(docPath),
      sectionHeading: heading,
      pagePath: toRelative(pagePath),
      type: args.type,
      imagePath: toPosix(path.join(toRelative(imageDir), buildDefaultFileName(index))),
      mode: 'replace'
    };

    if (args.type !== 'fullpage') {
      shot.selector = args.selector || 'body';
    }

    newShots.push(shot);
  }

  config.shots.push(...newShots);
  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');

  console.log(`Added ${newShots.length} shots to ${toRelative(configPath)}`);
}

main();

#!/usr/bin/env node

import path from 'path';
import { fileURLToPath } from 'url';
import { spawnSync } from 'child_process';

const cwd = process.cwd();
const __filename = fileURLToPath(import.meta.url);
const scriptsDir = path.dirname(__filename);

function parseArgs(argv) {
  const args = {
    passthrough: []
  };

  for (let i = 2; i < argv.length; i += 1) {
    const current = argv[i];
    if (current === '--config') args.config = argv[++i];
    else if (current === '--id') args.id = argv[++i];
    else if (current === '--dry-run') args.dryRun = true;
    else if (current === '--skip-capture') args.skipCapture = true;
    else if (current === '--skip-update') args.skipUpdate = true;
    else if (current === '--help' || current === '-h') args.help = true;
    else args.passthrough.push(current);
  }

  return args;
}

function runNodeScript(scriptPath, args) {
  const result = spawnSync(process.execPath, [scriptPath, ...args], {
    cwd,
    stdio: 'inherit'
  });

  if (result.status !== 0) {
    process.exit(result.status || 1);
  }
}

function main() {
  const args = parseArgs(process.argv);

  if (args.help || !args.config) {
    console.log('Usage: node sync-doc-images.mjs --config <config.json> [--id <shotId>] [--dry-run] [--skip-capture] [--skip-update]');
    process.exit(args.help ? 0 : 1);
  }

  const baseArgs = ['--config', args.config];
  if (args.id) baseArgs.push('--id', args.id);

  if (!args.skipCapture) {
    runNodeScript(path.join(scriptsDir, 'capture-shots.mjs'), [...baseArgs, ...args.passthrough]);
  }

  if (!args.skipUpdate) {
    const updateArgs = [...baseArgs];
    if (args.dryRun) updateArgs.push('--dry-run');
    runNodeScript(path.join(scriptsDir, 'update-doc-images.mjs'), updateArgs);
  }
}

main();

#!/usr/bin/env node

import fs from 'fs';
import path from 'path';

const cwd = process.cwd();

function parseArgs(argv) {
  const args = {};
  for (let i = 2; i < argv.length; i += 1) {
    const current = argv[i];
    if (current === '--config') args.config = argv[++i];
    else if (current === '--id') args.id = argv[++i];
    else if (current === '--dry-run') args.dryRun = true;
    else if (current === '--help' || current === '-h') args.help = true;
  }
  return args;
}

function resolvePath(p) {
  return path.isAbsolute(p) ? p : path.resolve(cwd, p);
}

function toPosix(p) {
  return p.split(path.sep).join('/');
}

function buildImageBlock(docPath, imagePath) {
  const relative = toPosix(path.relative(path.dirname(docPath), imagePath));
  return `\n![](<${relative}>)\n`;
}

function normalizeLine(line) {
  return line.replace(/\s+/g, ' ').trim();
}

function isImageLine(line) {
  return /^!\[[^\]]*\]\((<)?[^)]+(>)?\)$/.test(line.trim());
}

function findSectionIndex(lines, shot) {
  const normalizedHeading = shot.sectionHeading ? normalizeLine(shot.sectionHeading) : null;
  const normalizedIncludes = shot.sectionHeadingIncludes ? normalizeLine(shot.sectionHeadingIncludes) : null;
  const headingRegex = shot.sectionHeadingRegex ? new RegExp(shot.sectionHeadingRegex) : null;

  const idx = lines.findIndex((line) => {
    const normalizedLine = normalizeLine(line);
    if (normalizedHeading && normalizedLine === normalizedHeading) return true;
    if (normalizedIncludes && normalizedLine.includes(normalizedIncludes)) return true;
    if (headingRegex && headingRegex.test(line)) return true;
    return false;
  });

  if (idx === -1) {
    const matcher = shot.sectionHeading || shot.sectionHeadingIncludes || shot.sectionHeadingRegex;
    throw new Error(`Section not found: ${matcher}`);
  }

  return idx;
}

function findSectionEnd(lines, startIndex) {
  for (let i = startIndex + 1; i < lines.length; i += 1) {
    if (/^#{1,6}\s+/.test(lines[i].trim())) {
      return i;
    }
  }
  return lines.length;
}

function upsertImageAfterSection(content, shot, imageBlock) {
  const lines = content.split('\n');
  const idx = findSectionIndex(lines, shot);
  const sectionEnd = findSectionEnd(lines, idx);

  let insertAt = idx + 1;
  while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt += 1;

  const mode = shot.mode || 'replace';
  const imageLineIndex = lines.findIndex((line, lineIndex) => lineIndex > idx && lineIndex < sectionEnd && isImageLine(line));

  if (mode === 'replace' && imageLineIndex !== -1) {
    lines[imageLineIndex] = imageBlock.trim();
    return lines.join('\n');
  }

  if (mode === 'skipIfExists' && imageLineIndex !== -1) {
    return lines.join('\n');
  }

  lines.splice(idx + 1, 0, '', imageBlock.trim(), '');
  return lines.join('\n');
}

function main() {
  const args = parseArgs(process.argv);
  if (args.help || !args.config) {
    console.log('Usage: node update-doc-images.mjs --config <config.json> [--id <shotId>] [--dry-run]');
    process.exit(args.help ? 0 : 1);
  }

  const configPath = resolvePath(args.config);
  const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
  const shots = (raw.shots || []).filter((item) => !args.id || item.id === args.id);

  const grouped = new Map();
  for (const shot of shots) {
    const docPath = resolvePath(shot.docPath);
    if (!grouped.has(docPath)) grouped.set(docPath, []);
    grouped.get(docPath).push(shot);
  }

  for (const [docPath, docShots] of grouped.entries()) {
    let content = fs.readFileSync(docPath, 'utf8');
    for (const shot of docShots) {
      const imagePath = resolvePath(shot.imagePath);
      if (!fs.existsSync(imagePath)) {
        throw new Error(`Image not found for shot ${shot.id}: ${imagePath}`);
      }
      const imageBlock = buildImageBlock(docPath, imagePath);
      content = upsertImageAfterSection(content, shot, imageBlock);
    }
    if (args.dryRun) {
      console.log(`[dry-run] Updated doc images: ${path.relative(cwd, docPath)}`);
      continue;
    }
    fs.writeFileSync(docPath, content, 'utf8');
    console.log(`Updated doc images: ${path.relative(cwd, docPath)}`);
  }
}

main();