@openprd/cli 0.1.0

package/src/time.js

@@ -0,0 +1,33 @@
+const SHANGHAI_TIME_ZONE = 'Asia/Shanghai';
+
+function partsFrom(date = new Date()) {
+  const formatter = new Intl.DateTimeFormat('zh-CN', {
+    timeZone: SHANGHAI_TIME_ZONE,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  });
+  const parts = Object.fromEntries(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+  return {
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: parts.hour,
+    minute: parts.minute,
+    second: parts.second,
+  };
+}
+
+export function timestamp(date = new Date()) {
+  const parts = partsFrom(date);
+  return `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute}:${parts.second}`;
+}
+
+export function compactTimestamp(date = new Date()) {
+  const parts = partsFrom(date);
+  return `${parts.year}${parts.month}${parts.day}-${parts.hour}${parts.minute}${parts.second}`;
+}

package/src/visual-compare.js

@@ -0,0 +1,216 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import sharp from 'sharp';
+import { compactTimestamp } from './time.js';
+
+const DEFAULT_PANEL_WIDTH = 1180;
+const DEFAULT_QUALITY = 85;
+const DEFAULT_REFERENCE_LABEL = '效果图';
+const DEFAULT_ACTUAL_LABEL = '实现截图';
+const OUTPUT_FORMATS = new Set(['jpg', 'jpeg', 'png', 'webp']);
+
+function normalizeFormat(format, outPath) {
+  const requested = String(format || '').trim().toLowerCase();
+  if (requested) {
+    if (!OUTPUT_FORMATS.has(requested)) {
+      throw new Error(`Unsupported visual compare format: ${format}. Use jpg, png, or webp.`);
+    }
+    return requested === 'jpeg' ? 'jpg' : requested;
+  }
+
+  const ext = path.extname(String(outPath || '')).slice(1).toLowerCase();
+  if (OUTPUT_FORMATS.has(ext)) {
+    return ext === 'jpeg' ? 'jpg' : ext;
+  }
+  return 'jpg';
+}
+
+function outputExtension(format) {
+  return format === 'jpeg' ? 'jpg' : format;
+}
+
+function defaultOutputPath(projectRoot, format) {
+  return path.join(
+    projectRoot,
+    '.openprd',
+    'harness',
+    'visual-reviews',
+    `visual-compare-${compactTimestamp()}.${outputExtension(format)}`,
+  );
+}
+
+function parsePositiveInteger(value, fallback, label) {
+  if (value === null || value === undefined || value === '') {
+    return fallback;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function parseQuality(value) {
+  const quality = parsePositiveInteger(value, DEFAULT_QUALITY, '--quality');
+  if (quality < 1 || quality > 100) {
+    throw new Error('--quality must be between 1 and 100.');
+  }
+  return quality;
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function labelSvg(label) {
+  const text = escapeXml(label);
+  const charCount = Array.from(label).length;
+  const width = Math.max(126, charCount * 26 + 42);
+  return Buffer.from(`
+<svg width="${width}" height="46" viewBox="0 0 ${width} 46" xmlns="http://www.w3.org/2000/svg">
+  <rect x="0" y="0" width="${width}" height="46" rx="14" fill="#111827" fill-opacity="0.82"/>
+  <rect x="0.75" y="0.75" width="${width - 1.5}" height="44.5" rx="13.25" fill="none" stroke="#ffffff" stroke-opacity="0.22" stroke-width="1.5"/>
+  <text x="21" y="30" fill="#ffffff" font-size="22" font-weight="700" font-family="PingFang SC, Noto Sans CJK SC, Microsoft YaHei, Arial Unicode MS, sans-serif">${text}</text>
+</svg>`);
+}
+
+async function resizePanel(inputPath, panelWidth) {
+  const source = path.resolve(inputPath);
+  const metadata = await sharp(source).metadata();
+  if (!metadata.width || !metadata.height) {
+    throw new Error(`Cannot read image dimensions: ${inputPath}`);
+  }
+  const { data, info } = await sharp(source)
+    .rotate()
+    .resize({
+      width: panelWidth,
+      fit: 'inside',
+      withoutEnlargement: true,
+    })
+    .png()
+    .toBuffer({ resolveWithObject: true });
+  return {
+    input: data,
+    width: info.width,
+    height: info.height,
+    source,
+    original: {
+      width: metadata.width,
+      height: metadata.height,
+      format: metadata.format ?? null,
+    },
+  };
+}
+
+function encodePipeline(image, format, quality) {
+  if (format === 'png') {
+    return image.png();
+  }
+  if (format === 'webp') {
+    return image.webp({ quality });
+  }
+  return image.jpeg({ quality });
+}
+
+async function visualCompareWorkspace(projectRoot, options = {}) {
+  const reference = options.reference;
+  const actual = options.actual;
+  if (!reference) {
+    throw new Error('Missing --reference image path.');
+  }
+  if (!actual) {
+    throw new Error('Missing --actual image path.');
+  }
+
+  const format = normalizeFormat(options.format, options.out);
+  const outputPath = options.out
+    ? path.resolve(projectRoot, options.out)
+    : defaultOutputPath(projectRoot, format);
+  const quality = parseQuality(options.quality);
+  const maxPanelWidth = parsePositiveInteger(options.maxPanelWidth, DEFAULT_PANEL_WIDTH, '--max-panel-width');
+  const referenceLabel = options.referenceLabel || DEFAULT_REFERENCE_LABEL;
+  const actualLabel = options.actualLabel || DEFAULT_ACTUAL_LABEL;
+
+  const referencePanel = await resizePanel(reference, maxPanelWidth);
+  const actualPanel = await resizePanel(actual, maxPanelWidth);
+  const panelWidth = Math.min(
+    maxPanelWidth,
+    Math.max(referencePanel.width, actualPanel.width),
+  );
+  const maxPanelHeight = Math.max(referencePanel.height, actualPanel.height);
+  const margin = 24;
+  const gap = 24;
+  const canvasWidth = margin * 2 + panelWidth * 2 + gap;
+  const canvasHeight = margin * 2 + maxPanelHeight;
+  const leftPanelX = margin;
+  const rightPanelX = margin + panelWidth + gap;
+  const top = margin;
+
+  const referenceLeft = leftPanelX + Math.round((panelWidth - referencePanel.width) / 2);
+  const actualLeft = rightPanelX + Math.round((panelWidth - actualPanel.width) / 2);
+  const referenceTop = top + Math.round((maxPanelHeight - referencePanel.height) / 2);
+  const actualTop = top + Math.round((maxPanelHeight - actualPanel.height) / 2);
+
+  const canvas = sharp({
+    create: {
+      width: canvasWidth,
+      height: canvasHeight,
+      channels: 3,
+      background: '#111827',
+    },
+  }).composite([
+    { input: referencePanel.input, left: referenceLeft, top: referenceTop },
+    { input: actualPanel.input, left: actualLeft, top: actualTop },
+    { input: labelSvg(referenceLabel), left: referenceLeft + 16, top: referenceTop + 16 },
+    { input: labelSvg(actualLabel), left: actualLeft + 16, top: actualTop + 16 },
+  ]);
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await encodePipeline(canvas, format, quality).toFile(outputPath);
+
+  return {
+    ok: true,
+    action: 'visual-compare',
+    projectRoot,
+    outputPath,
+    format,
+    quality: format === 'png' ? null : quality,
+    maxPanelWidth,
+    labels: {
+      reference: referenceLabel,
+      actual: actualLabel,
+    },
+    reference: {
+      path: referencePanel.source,
+      original: referencePanel.original,
+      rendered: {
+        width: referencePanel.width,
+        height: referencePanel.height,
+      },
+    },
+    actual: {
+      path: actualPanel.source,
+      original: actualPanel.original,
+      rendered: {
+        width: actualPanel.width,
+        height: actualPanel.height,
+      },
+    },
+    canvas: {
+      width: canvasWidth,
+      height: canvasHeight,
+    },
+    nextActions: [
+      '把输出图片作为视觉评审证据查看：左侧效果图，右侧实现截图。',
+      '如果仍有明显差异，继续按效果图复刻并重新运行 visual-compare。',
+      '只有对比图确认一致后，才声明本阶段界面视觉实现完成。',
+    ],
+  };
+}
+
+export { visualCompareWorkspace };

package/src/work-unit-migration.js

@@ -0,0 +1,232 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { canonicalReviewPath, defaultReviewArtifactPath, renderReviewArtifact, renderReviewEntryHtml, writeHtmlArtifact } from './html-artifacts.js';
+import { summarizeSnapshot } from './prd-core.js';
+import { appendWorkflowEvent, buildWorkflowTaskGraph, loadWorkspace, readVersionIndex, readVersionSnapshot, writeVersionIndex, writeVersionSnapshot } from './workspace-core.js';
+import { exists, readText, writeJson } from './fs-utils.js';
+import { writeWorkUnitBinding } from './work-unit.js';
+import { timestamp } from './time.js';
+
+function legacyWorkUnitId(ws, snapshot) {
+  const versionId = snapshot.versionId ?? 'v0000';
+  const source = [
+    ws.projectRoot,
+    versionId,
+    snapshot.digest ?? '',
+    snapshot.title ?? '',
+  ].join('\0');
+  const suffix = crypto.createHash('sha256').update(source).digest('hex').slice(0, 8);
+  return `wu-legacy-${versionId}-${suffix}`;
+}
+
+function sortVersionIds(versionIds) {
+  return [...versionIds].sort((a, b) => {
+    const numberA = Number(String(a).replace(/^v/i, ''));
+    const numberB = Number(String(b).replace(/^v/i, ''));
+    if (Number.isFinite(numberA) && Number.isFinite(numberB) && numberA !== numberB) {
+      return numberA - numberB;
+    }
+    return String(a).localeCompare(String(b));
+  });
+}
+
+async function collectVersionIds(ws) {
+  const index = await readVersionIndex(ws);
+  const ids = new Set(index.map((entry) => entry.versionId).filter(Boolean));
+  const files = await fs.readdir(ws.paths.versionsDir).catch(() => []);
+  for (const file of files) {
+    if (file.endsWith('.json')) {
+      ids.add(path.basename(file, '.json'));
+    }
+  }
+  return sortVersionIds(ids);
+}
+
+async function loadBackfillSnapshot(ws, versionId) {
+  const snapshot = await readVersionSnapshot(ws, versionId);
+  if (!snapshot) {
+    return null;
+  }
+  if (snapshot.content) {
+    return snapshot;
+  }
+  const markdownPath = path.join(ws.paths.versionsDir, `${versionId}.md`);
+  const content = await readText(markdownPath).catch(() => null);
+  return content ? { ...snapshot, content } : snapshot;
+}
+
+function resolveBackfillStatus(ws, snapshot, isLatest) {
+  const currentState = ws.data.currentState ?? {};
+  const stored = currentState.reviewStatus;
+  if (isLatest && stored?.versionId === snapshot.versionId && stored.status) {
+    return stored.status;
+  }
+  if (isLatest && ['frozen', 'handed_off'].includes(currentState.status)) {
+    return 'confirmed';
+  }
+  return 'pending-confirmation';
+}
+
+function buildBackfilledSnapshot(ws, snapshot, isLatest) {
+  const content = snapshot.content ?? '';
+  const digest = snapshot.digest ?? crypto.createHash('sha256').update(content).digest('hex');
+  return {
+    ...snapshot,
+    digest,
+    workUnitId: snapshot.workUnitId ?? legacyWorkUnitId(ws, { ...snapshot, digest }),
+    targetRoot: snapshot.targetRoot ?? (isLatest ? ws.data.currentState?.targetRoot : null) ?? ws.projectRoot,
+  };
+}
+
+async function writeReviewBundle(ws, snapshot, isLatest) {
+  const activeReviewArtifact = defaultReviewArtifactPath(ws);
+  const reviewPath = canonicalReviewPath(ws, snapshot.versionId);
+  await writeHtmlArtifact(reviewPath, renderReviewArtifact({ snapshot }));
+
+  if (isLatest) {
+    await writeHtmlArtifact(activeReviewArtifact, renderReviewEntryHtml({
+      entryPath: activeReviewArtifact,
+      reviewPath,
+      title: `${snapshot.title} / 评审入口`,
+    }));
+  }
+
+  return {
+    activeReviewArtifact: isLatest ? activeReviewArtifact : null,
+    reviewPath,
+  };
+}
+
+function snapshotNeedsIdentityUpdate(before, after) {
+  return before.digest !== after.digest
+    || before.workUnitId !== after.workUnitId
+    || before.targetRoot !== after.targetRoot;
+}
+
+async function backfillWorkUnitsWorkspace(projectRoot, options = {}) {
+  const ws = await loadWorkspace(projectRoot);
+  if (!(await exists(ws.workspaceRoot))) {
+    throw new Error(`Missing workspace: ${ws.workspaceRoot}`);
+  }
+
+  const dryRun = Boolean(options.dryRun);
+  const versionIds = await collectVersionIds(ws);
+  const latestVersionId = versionIds.at(-1) ?? null;
+  const changes = [];
+  const bindings = [];
+  const errors = [];
+  let changedVersions = 0;
+
+  for (const versionId of versionIds) {
+    const snapshot = await loadBackfillSnapshot(ws, versionId);
+    if (!snapshot) {
+      errors.push(`Missing version snapshot: ${versionId}`);
+      continue;
+    }
+
+    const isLatest = versionId === latestVersionId;
+    const nextSnapshot = buildBackfilledSnapshot(ws, snapshot, isLatest);
+    const needsSnapshotUpdate = snapshotNeedsIdentityUpdate(snapshot, nextSnapshot);
+    const status = resolveBackfillStatus(ws, nextSnapshot, isLatest);
+    const activeReviewArtifact = isLatest ? defaultReviewArtifactPath(ws) : null;
+
+    changes.push({
+      path: path.relative(ws.projectRoot, path.join(ws.paths.versionsDir, `${versionId}.json`)),
+      status: dryRun ? 'planned' : (needsSnapshotUpdate ? 'updated' : 'unchanged'),
+      versionId,
+      workUnitId: nextSnapshot.workUnitId,
+    });
+    changes.push({
+      path: path.relative(ws.projectRoot, canonicalReviewPath(ws, nextSnapshot.versionId)),
+      status: dryRun ? 'planned' : 'refreshed',
+      versionId,
+      workUnitId: nextSnapshot.workUnitId,
+    });
+
+    if (dryRun) {
+      changedVersions += 1;
+      continue;
+    }
+
+    if (needsSnapshotUpdate) {
+      await writeVersionSnapshot(ws, nextSnapshot);
+    }
+    const writtenReview = await writeReviewBundle(ws, nextSnapshot, isLatest);
+    const binding = await writeWorkUnitBinding(ws, {
+      snapshot: nextSnapshot,
+      reviewPath: writtenReview.reviewPath,
+      activeReviewPath: writtenReview.activeReviewArtifact,
+      targetRoot: nextSnapshot.targetRoot,
+      status,
+    });
+    if (binding) {
+      bindings.push(binding);
+      changes.push({
+        path: path.relative(ws.projectRoot, binding.path),
+        status: 'updated',
+        versionId,
+        workUnitId: nextSnapshot.workUnitId,
+      });
+    }
+
+    changedVersions += 1;
+  }
+
+  if (!dryRun && versionIds.length > 0) {
+    const snapshots = [];
+    for (const versionId of versionIds) {
+      const snapshot = await readVersionSnapshot(ws, versionId);
+      if (snapshot) {
+        snapshots.push(summarizeSnapshot(snapshot));
+      }
+    }
+    await writeVersionIndex(ws, snapshots);
+
+    const latestSnapshot = await readVersionSnapshot(ws, latestVersionId);
+    if (latestSnapshot) {
+      const currentState = ws.data.currentState ?? {};
+      const status = resolveBackfillStatus(ws, latestSnapshot, true);
+      const nextState = {
+        ...currentState,
+        latestVersionId: latestSnapshot.versionId,
+        latestVersionDigest: latestSnapshot.digest,
+        activeWorkUnitId: latestSnapshot.workUnitId,
+        targetRoot: latestSnapshot.targetRoot,
+        reviewStatus: {
+          ...(currentState.reviewStatus ?? {}),
+          versionId: latestSnapshot.versionId,
+          workUnitId: latestSnapshot.workUnitId,
+          status,
+          reviewPath: canonicalReviewPath(ws, latestSnapshot.versionId),
+          entryPath: defaultReviewArtifactPath(ws),
+          artifact: defaultReviewArtifactPath(ws),
+          stableArtifact: canonicalReviewPath(ws, latestSnapshot.versionId),
+          updatedAt: currentState.reviewStatus?.updatedAt ?? timestamp(),
+        },
+      };
+      await writeJson(ws.paths.currentState, nextState);
+      await writeJson(ws.paths.taskGraph, buildWorkflowTaskGraph(latestSnapshot));
+    }
+
+    await appendWorkflowEvent(ws, 'work_units_backfilled', {
+      versions: versionIds.length,
+      changedVersions,
+    });
+  }
+
+  return {
+    ok: errors.length === 0,
+    action: 'backfill-work-units',
+    projectRoot: ws.projectRoot,
+    workspaceRoot: ws.workspaceRoot,
+    dryRun,
+    totalVersions: versionIds.length,
+    changedVersions,
+    bindings,
+    changes,
+    errors,
+  };
+}
+
+export { backfillWorkUnitsWorkspace };

package/src/work-unit.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readJson, writeJson } from './fs-utils.js';
+import { timestamp } from './time.js';
+
+function normalizeWorkUnitId(value) {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+  const text = String(value).trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(text)) {
+    throw new Error('Work unit id must start with a letter or number and only contain letters, numbers, dot, underscore, colon, or dash.');
+  }
+  return text;
+}
+
+function generateWorkUnitId() {
+  const compactTime = timestamp().replace(/[^0-9]/g, '').slice(0, 14);
+  return `wu-${compactTime}-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+function workUnitFileName(workUnitId) {
+  return `${workUnitId.replace(/[^A-Za-z0-9._-]/g, '_')}.json`;
+}
+
+function workUnitStatePath(ws, workUnitId) {
+  return path.join(ws.workspaceRoot, 'engagements', 'work-units', workUnitFileName(workUnitId));
+}
+
+function resolveTargetRoot(ws, value) {
+  return value ? path.resolve(ws.projectRoot, value) : ws.projectRoot;
+}
+
+async function readWorkUnitBinding(ws, workUnitId) {
+  if (!workUnitId) {
+    return null;
+  }
+  return readJson(workUnitStatePath(ws, workUnitId)).catch(() => null);
+}
+
+async function writeWorkUnitBinding(ws, {
+  snapshot,
+  reviewArtifact,
+  stableReviewArtifact,
+  reviewPath,
+  activeReviewPath,
+  reviewBundle,
+  targetRoot,
+  status = 'pending-confirmation',
+}) {
+  if (!snapshot.workUnitId) {
+    return null;
+  }
+  const filePath = workUnitStatePath(ws, snapshot.workUnitId);
+  const previous = await readJson(filePath).catch(() => null);
+  const binding = {
+    ...(previous ?? {}),
+    version: 1,
+    workUnitId: snapshot.workUnitId,
+    title: snapshot.title,
+    status,
+    projectRoot: ws.projectRoot,
+    workspaceRoot: ws.workspaceRoot,
+    targetRoot: targetRoot ?? snapshot.targetRoot ?? ws.projectRoot,
+    latestVersionId: snapshot.versionId,
+    latestVersionDigest: snapshot.digest,
+    reviewPath: reviewPath ?? stableReviewArtifact ?? null,
+    activeReviewPath: activeReviewPath ?? reviewArtifact ?? null,
+    reviewArtifact: reviewPath ?? stableReviewArtifact ?? null,
+    activeReviewArtifact: activeReviewPath ?? reviewArtifact ?? null,
+    artifactBundle: reviewBundle ?? previous?.artifactBundle ?? null,
+    createdAt: previous?.createdAt ?? snapshot.createdAt,
+    updatedAt: timestamp(),
+  };
+  await writeJson(filePath, binding);
+  return {
+    ...binding,
+    path: filePath,
+  };
+}
+
+export {
+  generateWorkUnitId,
+  normalizeWorkUnitId,
+  readWorkUnitBinding,
+  resolveTargetRoot,
+  writeWorkUnitBinding,
+};