draftgo-cli 1.0.4

package/src/commands/visualVerify.js

@@ -0,0 +1,281 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const runtimeFiles = require('../runtimeFiles');
+const log = require('../logger');
+const { configPath, loadProjectConfig } = require('../projectConfig');
+
+function numberFlag(value, fallback, min, max) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(min, Math.min(max, Math.round(n))) : fallback;
+}
+
+function configuredUiUrl(projectDir, rawUrl, tokenMode = 'auto') {
+  if (tokenMode === 'never') return rawUrl;
+  if (!fs.existsSync(configPath(projectDir))) return rawUrl;
+
+  const config = loadProjectConfig(projectDir, { requireToken: false });
+  if (!config.token) return rawUrl;
+
+  let target;
+  try {
+    target = new URL(rawUrl);
+  } catch {
+    return rawUrl;
+  }
+  const server = new URL(config.server);
+  if (target.origin !== server.origin) return rawUrl;
+  target.searchParams.set('token', config.token);
+  return target.toString();
+}
+
+function redactUrlTokens(message) {
+  return String(message || '')
+    .replace(/([?&]token=)[^&#\s]+/gi, '$1<redacted>')
+    .replace(/\bsat_[A-Za-z0-9._~+/-]+/g, '<redacted>');
+}
+
+function executableCandidates() {
+  const explicit = process.env.DRAFTGO_BROWSER_PATH ? [process.env.DRAFTGO_BROWSER_PATH] : [];
+  if (process.platform === 'win32') {
+    const roots = [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter(Boolean);
+    const rels = [
+      ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
+      ['Google', 'Chrome', 'Application', 'chrome.exe'],
+      ['Chromium', 'Application', 'chrome.exe'],
+    ];
+    return [...explicit, ...roots.flatMap((root) => rels.map((parts) => path.join(root, ...parts)))];
+  }
+  if (process.platform === 'darwin') {
+    return [...explicit,
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ];
+  }
+  return [...explicit, '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/microsoft-edge', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+}
+
+function playwrightCacheCandidates() {
+  const root = process.env.PLAYWRIGHT_BROWSERS_PATH
+    || (process.platform === 'win32'
+      ? path.join(process.env.LOCALAPPDATA || '', 'ms-playwright')
+      : path.join(process.env.HOME || '', '.cache', 'ms-playwright'));
+  if (!root || !fs.existsSync(root)) return [];
+  const candidates = [];
+  const visit = (directory, depth) => {
+    if (depth > 3) return;
+    let entries;
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isFile() && /^(?:chrome(?:-headless-shell)?|chromium|msedge|headless_shell)(?:\.exe)?$/i.test(entry.name)) candidates.push(absolute);
+      else if (entry.isDirectory()) visit(absolute, depth + 1);
+    }
+  };
+  visit(root, 0);
+  return candidates;
+}
+
+async function launchBrowser(chromium, requested, requestedPath) {
+  const attempts = [];
+  if (requestedPath) attempts.push({ executablePath: requestedPath, label: `path:${requestedPath}` });
+  if (requested && requested !== 'chromium') attempts.push({ channel: requested });
+  for (const executablePath of [...executableCandidates(), ...playwrightCacheCandidates()].filter((candidate) => fs.existsSync(candidate))) {
+    if (!attempts.some((attempt) => attempt.executablePath === executablePath)) {
+      attempts.push({ executablePath, label: `path:${executablePath}` });
+    }
+  }
+  if (!requested || requested === 'chromium') attempts.push({});
+  for (const channel of ['msedge', 'chrome']) {
+    if (!attempts.some((a) => a.channel === channel)) attempts.push({ channel });
+  }
+
+  let lastError = null;
+  const attempted = [];
+  for (const options of attempts) {
+    try {
+      const { label, ...launchOptions } = options;
+      const browser = await chromium.launch({ headless: true, ...launchOptions });
+      return { browser, selected: label || options.channel || 'playwright-managed', attempted };
+    } catch (err) {
+      lastError = err;
+      attempted.push(`${options.label || options.channel || 'playwright-managed'}: ${String(err.message || err).split('\n')[0]}`);
+    }
+  }
+  throw new Error(`未找到可用的 Chromium/Chrome/Edge。请使用 --browser-path <executable> 或 DRAFTGO_BROWSER_PATH。`
+    + `尝试记录：${attempted.join('; ')}`
+    + (lastError ? `；最后错误：${lastError.message.split('\n')[0]}` : ''));
+}
+
+async function selectFrames(page, mode = 'auto') {
+  const top = page.mainFrame ? page.mainFrame() : page;
+  const selected = [{ frame: top, label: 'top' }];
+  if (mode === 'top') return selected;
+  if (!['auto', 'all'].includes(mode)) {
+    const handle = await page.locator(mode).first().elementHandle().catch(() => null);
+    const frame = handle && await handle.contentFrame().catch(() => null);
+    if (!frame) throw new Error(`Frame not found: ${mode}`);
+    return [{ frame, label: `selector:${mode}` }];
+  }
+  const frames = page.frames ? page.frames() : [];
+  for (let index = 0; index < frames.length; index += 1) {
+    const frame = frames[index];
+    if (frame === top) continue;
+    let visible = true;
+    if (mode === 'auto') {
+      const element = await frame.frameElement().catch(() => null);
+      visible = Boolean(element && await element.isVisible().catch(() => false));
+    }
+    if (visible) selected.push({
+      frame,
+      label: `frame:${frame.name && frame.name() ? frame.name() : index}`,
+    });
+  }
+  return selected;
+}
+
+async function inspectFrame(frame) {
+  return frame.evaluate(() => {
+    const body = document.body;
+    const root = document.documentElement;
+    return {
+      bodyTextLength: body ? (body.innerText || '').trim().length : 0,
+      bodyHeight: body ? body.getBoundingClientRect().height : 0,
+      hasVisibleMedia: body ? Array.from(body.querySelectorAll('img,svg,canvas,video,iframe,input,button')).some((element) => {
+        const rect = element.getBoundingClientRect();
+        return rect.width > 1 && rect.height > 1;
+      }) : false,
+      horizontalOverflow: root.scrollWidth > window.innerWidth + 1,
+      scrollWidth: root.scrollWidth,
+      viewportWidth: window.innerWidth,
+    };
+  });
+}
+
+async function captureScreenshot(projectDir, page) {
+  const dir = path.join(projectDir, '.draftgo', 'artifacts', 'ui');
+  fs.mkdirSync(dir, { recursive: true });
+  const screenshotPath = path.join(dir, `ui-check-${process.pid}-${Date.now()}.png`);
+  await page.screenshot({ path: screenshotPath, fullPage: true });
+  runtimeFiles.register(projectDir, screenshotPath, 'ui-artifact', 'verify');
+  return screenshotPath;
+}
+
+async function visualVerify(projectDir, positional, flags = {}) {
+  const rawUrl = String(flags.url || positional[0] || '').trim();
+  if (!/^https?:\/\//i.test(rawUrl)) {
+    log.err('Usage: draftgo verify --url <http://localhost:port/path> --screenshot always|--ui always');
+    return 1;
+  }
+
+  const tokenMode = String(flags.token || 'auto').toLowerCase();
+  if (!['auto', 'never'].includes(tokenMode)) {
+    log.err('--token in visual verification accepts auto or never.');
+    return 1;
+  }
+
+  let url;
+  try {
+    url = configuredUiUrl(projectDir, rawUrl, tokenMode);
+  } catch (err) {
+    log.err(`Unable to read visual verification config: ${err.message}`);
+    return 1;
+  }
+
+  let chromium;
+  try {
+    ({ chromium } = require('playwright-core'));
+  } catch {
+    log.err('缺少 playwright-core，请重新安装或升级 draftgo-cli。');
+    return 1;
+  }
+
+  const width = numberFlag(flags.width, 1440, 240, 3840);
+  const height = numberFlag(flags.height, 900, 320, 2160);
+  const waitMs = numberFlag(flags['wait-ms'], 500, 0, 10000);
+  const screenshotMode = String(flags.screenshot || 'never').toLowerCase();
+  if (!['always', 'never'].includes(screenshotMode)) {
+    log.err('--screenshot accepts always or never.');
+    return 1;
+  }
+
+  let browser;
+  try {
+    log.info('UI source: requested URL response.');
+    const launch = await launchBrowser(
+      chromium,
+      flags.browser && String(flags.browser),
+      flags['browser-path'] && String(flags['browser-path']),
+    );
+    browser = launch.browser;
+    log.info(`Browser: ${launch.selected}`);
+    const page = await browser.newPage({ viewport: { width, height } });
+    const consoleErrors = [];
+    const pageErrors = [];
+    page.on('console', (msg) => { if (msg.type() === 'error') consoleErrors.push(redactUrlTokens(msg.text())); });
+    page.on('pageerror', (err) => pageErrors.push(redactUrlTokens(err.message)));
+
+    const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    if (waitMs) await page.waitForTimeout(waitMs);
+    let screenshotPath = null;
+    if (screenshotMode === 'always' || flags['capture-only']) {
+      screenshotPath = await captureScreenshot(projectDir, page);
+    }
+    if (flags['capture-only']) {
+      log.ok(`截图已生成：${width}x${height}`);
+      log.info(`截图：${screenshotPath}`);
+      return 0;
+    }
+    const frames = await selectFrames(page, String(flags.frame || 'auto'));
+    const states = [];
+    for (const item of frames) states.push({ ...item, state: await inspectFrame(item.frame) });
+
+    const issues = [];
+    if (response && response.status() >= 400) issues.push(`页面返回 HTTP ${response.status()}`);
+    if (!states.some(({ state }) => state.bodyHeight && (state.bodyTextLength || state.hasVisibleMedia))) issues.push('页面疑似空白');
+    for (const { label, state } of states) {
+      if (state.horizontalOverflow) issues.push(`${label} 横向溢出：scrollWidth=${state.scrollWidth}, viewport=${state.viewportWidth}`);
+    }
+    if (consoleErrors.length) issues.push(`console error ${consoleErrors.length} 条`);
+    if (pageErrors.length) issues.push(`page error ${pageErrors.length} 条`);
+    if (flags.selector) {
+      let match = null;
+      for (const item of frames) {
+        if (await item.frame.locator(String(flags.selector)).first().isVisible().catch(() => false)) {
+          match = item.label;
+          break;
+        }
+      }
+      if (!match) issues.push(`关键元素在已检查 frame 中不可见：${flags.selector}`);
+      else log.info(`Selector ${flags.selector}: visible in ${match}`);
+    }
+
+    if (issues.length) {
+      issues.forEach((issue) => log.err(issue));
+      if (consoleErrors.length) consoleErrors.slice(0, 5).forEach((msg) => log.dim(`  console: ${msg}`));
+      if (pageErrors.length) pageErrors.slice(0, 5).forEach((msg) => log.dim(`  page: ${msg}`));
+      if (screenshotPath) log.info(`失败截图：${screenshotPath}`);
+      return 1;
+    }
+
+    log.ok(`UI smoke check passed: ${width}x${height}, ${frames.length} frame(s).`);
+    if (screenshotPath) log.info(`截图：${screenshotPath}`);
+    return 0;
+  } catch (err) {
+    log.err(`UI smoke check 失败：${redactUrlTokens(err.message)}`);
+    return 1;
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+module.exports = visualVerify;
+module.exports.configuredUiUrl = configuredUiUrl;
+module.exports.redactUrlTokens = redactUrlTokens;
+module.exports.executableCandidates = executableCandidates;
+module.exports.playwrightCacheCandidates = playwrightCacheCandidates;
+module.exports.selectFrames = selectFrames;
+module.exports.inspectFrame = inspectFrame;
+module.exports.captureScreenshot = captureScreenshot;

package/src/commands/worklog.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const log = require('../logger');
+const {
+  appendItem,
+  mutateWorklog,
+  normalizeDate,
+  readWorklog,
+  renderWorklog,
+  resolveReference,
+  updateItem,
+  worklogPath,
+} = require('../worklog');
+
+function printUsage() {
+  log.err('Usage: draftgo work start|add|start-item|wait|complete|show|list <value>');
+}
+
+function output(flags, value) {
+  if (flags.output === 'json') console.log(JSON.stringify(value, null, 2));
+}
+
+function latestReference(blocks) {
+  const block = blocks[blocks.length - 1];
+  return `${block.date}#${block.entries[block.entries.length - 1].number}`;
+}
+
+function resultFor(blocks, reference) {
+  const resolved = resolveReference(blocks, reference);
+  return { date: resolved.block.date, ...resolved.entry, status: visibleStatus(resolved.entry.status) };
+}
+
+function visibleStatus(status) { return status === 'pending' ? 'waiting' : status; }
+function visibleBlocks(blocks) {
+  return blocks.map(block => ({ ...block, entries: block.entries.map(entry => ({ ...entry, status: visibleStatus(entry.status) })) }));
+}
+
+function add(projectDir, positional, flags, status) {
+  const title = positional.join(' ').trim();
+  if (!title) { printUsage(); return 1; }
+  const result = mutateWorklog(projectDir, (blocks) => {
+    const date = normalizeDate(flags.date);
+    const next = appendItem(blocks, title, status, flags.note ? [String(flags.note).trim()] : [], date);
+    return { blocks: next, reference: latestReference(next) };
+  });
+  const item = resultFor(result.blocks, result.reference);
+  output(flags, { path: result.path, item });
+  if (flags.output !== 'json') {
+    const verb = status === 'active' ? 'Started' : 'Added';
+    log.ok(`${verb} work item #${item.number} (${item.date}#${item.number}): ${item.title}`);
+  }
+  return 0;
+}
+
+function change(projectDir, positional, flags, status) {
+  const reference = positional[0];
+  if (!reference) { printUsage(); return 1; }
+  const result = mutateWorklog(projectDir, (blocks) => {
+    const note = flags.note == null ? '' : String(flags.note).trim();
+    const next = updateItem(blocks, reference, status, note);
+    return { blocks: next, reference };
+  });
+  output(flags, { path: result.path, item: resultFor(result.blocks, result.reference) });
+  if (flags.output !== 'json') log.ok(`Worklog item ${result.reference} marked ${status}.`);
+  return 0;
+}
+
+function show(projectDir, flags, reference) {
+  if (reference) {
+    const item = resultFor(readWorklog(projectDir), reference);
+    item.reference = `${item.date}#${item.number}`;
+    output(flags, { path: worklogPath(projectDir), item });
+    if (flags.output !== 'json') {
+      log.info(`${item.reference} [${item.status}] ${item.title}`);
+      item.notes.forEach((note) => log.plain(`  ${note}`));
+    }
+    return 0;
+  }
+  const blocks = visibleBlocks(readWorklog(projectDir));
+  output(flags, { path: worklogPath(projectDir), blocks });
+  if (flags.output !== 'json') console.log(renderWorklog(blocks) || 'Worklog is empty.');
+  return 0;
+}
+
+function list(projectDir, flags) {
+  const blocks = visibleBlocks(readWorklog(projectDir));
+  const statuses = ['active', 'waiting', 'completed'];
+  if (flags.status !== undefined && !statuses.includes(flags.status)) throw new Error('status must be active, waiting, or completed.');
+  const date = flags.date === undefined ? undefined : normalizeDate(flags.date);
+  const limit = flags.limit === undefined ? 20 : Number(flags.limit);
+  const offset = flags.offset === undefined ? 0 : Number(flags.offset);
+  if (typeof flags.limit === 'boolean' || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('limit must be between 1 and 100.');
+  if (typeof flags.offset === 'boolean' || !Number.isSafeInteger(offset) || offset < 0) throw new Error('offset must be a non-negative integer.');
+  const matching = blocks.flatMap((block) => block.entries.map((entry) => ({ date: block.date, ...entry, reference: `${block.date}#${entry.number}` })))
+    .filter((item) => (!flags.status || item.status === flags.status) && (!date || item.date === date)).reverse();
+  const items = matching.slice(offset, offset + limit);
+  const nextOffset = offset + items.length < matching.length ? offset + items.length : null;
+  output(flags, { path: worklogPath(projectDir), items, total: matching.length, next_offset: nextOffset });
+  if (flags.output !== 'json') items.forEach((item) => log.info(`${item.date}#${item.number} [${item.status}] ${item.title}`));
+  if (flags.output !== 'json' && nextOffset !== null) log.dim(`More items: repeat with --offset ${nextOffset}.`);
+  return 0;
+}
+
+async function worklog(projectDir, positional = [], flags = {}) {
+  const operation = positional[0] || 'show';
+  if (operation === 'start') return add(projectDir, positional.slice(1), flags, 'active');
+  if (operation === 'add') return add(projectDir, positional.slice(1), flags, 'waiting');
+  if (operation === 'wait') return change(projectDir, positional.slice(1), flags, 'waiting');
+  if (operation === 'start-item' || operation === 'start_item') return change(projectDir, positional.slice(1), flags, 'active');
+  if (operation === 'complete' || operation === 'done') return change(projectDir, positional.slice(1), flags, 'completed');
+  if (operation === 'show') return show(projectDir, flags, positional[1]);
+  if (operation === 'list') return list(projectDir, flags);
+  throw new Error(`Unknown worklog operation ${operation}.`);
+}
+
+worklog.printUsage = printUsage;
+module.exports = worklog;

package/src/consoleEncoding.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+/**
+ * Windows console hosts still use the active console code page to decode the
+ * UTF-8 bytes Node writes. Switch only an interactive console to UTF-8.
+ *
+ * This deliberately does not run for redirected stdout: JSON consumers and
+ * MCP stdio use pipes, where Node's UTF-8 byte stream is already correct and
+ * changing a shared console would be both unnecessary and surprising.
+ */
+function configureConsoleUtf8(options = {}) {
+  const platform = options.platform || process.platform;
+  const stdout = options.stdout || process.stdout;
+  const run = options.spawnSync || spawnSync;
+
+  if (platform !== 'win32' || !stdout || !stdout.isTTY) return false;
+
+  try {
+    // chcp changes the code page for the inherited Windows console. Redirect
+    // its own localized status line so stdout remains exclusively CLI output.
+    run('cmd.exe', ['/d', '/s', '/c', 'chcp 65001 >nul'], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    return true;
+  } catch {
+    // Encoding setup is a presentation enhancement; never block the command.
+    return false;
+  }
+}
+
+module.exports = { configureConsoleUtf8 };

package/src/contractCompatibility.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const HARD_INCOMPATIBLE_CODES = new Set([
+  'CONTRACT_INCOMPATIBLE',
+  'CLIENT_VERSION_UNSUPPORTED',
+  'CLI_VERSION_UNSUPPORTED',
+]);
+
+function errorCode(error) {
+  return String(error && error.code || '').trim().toUpperCase();
+}
+
+function isContractCompatibilityError(error) {
+  const code = errorCode(error);
+  return code === 'CONTRACT_CHANGED' || HARD_INCOMPATIBLE_CODES.has(code);
+}
+
+function isHardContractIncompatibility(error) {
+  return HARD_INCOMPATIBLE_CODES.has(errorCode(error));
+}
+
+function isDangerousOperation(contract) {
+  const operation = contract && contract.operation || contract || {};
+  const risk = String(operation.risk || '').toLowerCase();
+  return operation.destructive === true || risk === 'high' || risk === 'critical';
+}
+
+function canonicalValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalValue(value[key])]));
+}
+
+function sameOperationContract(left, right) {
+  const leftOperation = left && left.operation || left || {};
+  const rightOperation = right && right.operation || right || {};
+  return JSON.stringify(canonicalValue(leftOperation)) === JSON.stringify(canonicalValue(rightOperation));
+}
+
+function canRetryAfterContractChange(left, right) {
+  const operation = right && right.operation || right || {};
+  const method = String(operation.method || '').toUpperCase();
+  return method === 'GET' || method === 'HEAD' || sameOperationContract(left, right);
+}
+
+function incompatibleOperationError(operationId, error) {
+  const wrapped = new Error(
+    `DraftGo CLI and server contracts are incompatible for operation ${operationId}; `
+    + 'the call was blocked before retry. Upgrade DraftGo CLI, then describe and confirm the operation again.',
+  );
+  wrapped.code = 'CLI_CONTRACT_INCOMPATIBLE';
+  wrapped.details = error && (error.details || error.data);
+  wrapped.cause = error;
+  return wrapped;
+}
+
+module.exports = {
+  errorCode,
+  isContractCompatibilityError,
+  isHardContractIncompatibility,
+  isDangerousOperation,
+  sameOperationContract,
+  canRetryAfterContractChange,
+  incompatibleOperationError,
+};

package/src/detect.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const path = require('path');
+const { exists } = require('./fsx');
+const { platforms } = require('./platforms');
+
+// Each target declares one or more signals (files/dirs). If ANY signal matches,
+// the target is considered "in use" in the current project. Signals must be
+// host-owned directories or files, not generic instruction files such as
+// AGENTS.md that several tools may share.
+const SIGNALS = Object.fromEntries(
+  platforms.map((p) => [p.name, p.signals || []])
+);
+
+function detectTargets(projectDir) {
+  const hits = [];
+  for (const [name, signals] of Object.entries(SIGNALS)) {
+    if (signals.some((s) => exists(path.join(projectDir, s)))) {
+      hits.push(name);
+    }
+  }
+  return hits;
+}
+
+module.exports = { SIGNALS, detectTargets };

package/src/diffReport.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+
+function lineStats(output) {
+  let additions = 0;
+  let deletions = 0;
+  let inHunk = false;
+  for (const line of String(output || '').split(/\r?\n/)) {
+    if (line.startsWith('@@ ')) {
+      inHunk = true;
+      continue;
+    }
+    if (line.startsWith('diff --git ')) {
+      inHunk = false;
+      continue;
+    }
+    if (!inHunk || line === '\') continue;
+    if (line.startsWith('+')) additions += 1;
+    else if (line.startsWith('-')) deletions += 1;
+  }
+  return { additions, deletions, lines_changed: additions + deletions };
+}
+
+function byteSize(file) {
+  return fs.statSync(file).size;
+}
+
+function fileStat(file) {
+  const base_bytes = byteSize(file.base_path);
+  const local_bytes = byteSize(file.local_path);
+  return {
+    path: file.path,
+    changed: Boolean(file.changed),
+    ...lineStats(file.output),
+    base_bytes,
+    local_bytes,
+    bytes_delta: local_bytes - base_bytes,
+  };
+}
+
+function resourceMetadata(entry) {
+  return {
+    resource_type: entry.resource_type,
+    resource_id: entry.resource_id,
+    title: entry.title || null,
+    route: entry.route || null,
+    slug: entry.slug || null,
+    local_path: entry.local_path || null,
+    base_path: entry.base_path || null,
+    base_version: entry.base_version ?? null,
+    base_revision: entry.base_revision ?? null,
+    base_etag: entry.base_etag ?? null,
+  };
+}
+
+function report(entry, files) {
+  const file_stats = files.map(fileStat);
+  const changed_files = file_stats.filter((file) => file.changed);
+  const additions = changed_files.reduce((total, file) => total + file.additions, 0);
+  const deletions = changed_files.reduce((total, file) => total + file.deletions, 0);
+  const base_bytes = file_stats.reduce((total, file) => total + file.base_bytes, 0);
+  const local_bytes = file_stats.reduce((total, file) => total + file.local_bytes, 0);
+  return {
+    resource: resourceMetadata(entry),
+    changed: changed_files.length > 0,
+    bytes: { base: base_bytes, local: local_bytes, delta: local_bytes - base_bytes },
+    stats: {
+      files_changed: changed_files.length,
+      additions,
+      deletions,
+      lines_changed: additions + deletions,
+      files: file_stats,
+    },
+  };
+}
+
+function resourceLabel(resource) {
+  return `${resource.resource_type} ${resource.resource_id}`;
+}
+
+function formatSummary(value) {
+  const { resource, bytes } = value;
+  const fields = [
+    `${resourceLabel(resource)}: ${value.changed ? 'changed' : 'no local changes'}`,
+    `title: ${resource.title || '-'}`,
+    `path: ${resource.local_path || '-'}`,
+    `base version: ${resource.base_version ?? '-'}`,
+    `base revision: ${resource.base_revision ?? '-'}`,
+    `bytes: ${bytes.base} -> ${bytes.local} (${bytes.delta >= 0 ? '+' : ''}${bytes.delta})`,
+  ];
+  if (resource.route) fields.splice(2, 0, `route: ${resource.route}`);
+  return `${fields.join('\n')}\n`;
+}
+
+function formatStat(value) {
+  const { stats } = value;
+  const files = stats.files.filter((file) => file.changed).map((file) => {
+    const marker = `${file.additions ? `${'+'.repeat(Math.min(file.additions, 20))}` : ''}${file.deletions ? `${'-'.repeat(Math.min(file.deletions, 20))}` : ''}` || '0';
+    return `${file.path} | ${file.lines_changed} ${marker}`;
+  });
+  const summary = `${stats.files_changed} file${stats.files_changed === 1 ? '' : 's'} changed, ${stats.additions} insertion${stats.additions === 1 ? '' : 's'}(+), ${stats.deletions} deletion${stats.deletions === 1 ? '' : 's'}(-)`;
+  return `${formatSummary(value)}${files.length ? `${files.join('\n')}\n` : ''}${summary}\n`;
+}
+
+module.exports = { lineStats, report, formatSummary, formatStat };