draftgo-cli 3.0.56 → 4.0.22

package/src/commands/verify.js

@@ -2,12 +2,17 @@
 
 const log = require('../logger');
 const check = require('./check');
-const verifyUi = require('./verifyUi');
+const visualVerify = require('./visualVerify');
 const { canonicalResourceType } = require('../worktree/types');
+const fs = require('fs');
+const path = require('path');
+const parse5 = require('parse5');
+const { loadProjectConfig } = require('../projectConfig');
+const { loadManifest, getEntry, absolutePath } = require('../worktree/manifest');
 
 function mode(value, fallback, flag) {
   const normalized = String(value == null ? fallback : value).toLowerCase();
-  if (!['auto', 'always', 'never'].includes(normalized)) throw new Error(`${flag} must be auto, always, or never.`);
+  if (!['always', 'never'].includes(normalized)) throw new Error(`${flag} must be always or never.`);
   return normalized;
 }
 
@@ -21,7 +26,11 @@ function resources(positional) {
 
 function viewports(flags) {
   const value = String(flags.viewport || '').toLowerCase();
-  if (!value) return [{ name: 'custom', width: flags.width, height: flags.height }];
+  if (!value) return [{
+    name: flags.width || flags.height ? 'custom' : 'desktop',
+    width: flags.width || 1440,
+    height: flags.height || 900,
+  }];
   if (value === 'mobile') return [{ name: 'mobile', width: 390, height: 844 }];
   if (value === 'desktop') return [{ name: 'desktop', width: 1440, height: 900 }];
   if (value === 'both') return [
@@ -31,13 +40,96 @@ function viewports(flags) {
   throw new Error('--viewport must be mobile, desktop, or both.');
 }
 
+function visualRequest(flags, url) {
+  const uiMode = mode(flags.ui, 'never', '--ui');
+  const screenshotMode = String(flags.screenshot || 'never').toLowerCase();
+  if (!['always', 'never'].includes(screenshotMode)) {
+    throw new Error('--screenshot must be always or never.');
+  }
+  const screenshotRequested = screenshotMode !== 'never';
+  if ((uiMode === 'always' || screenshotRequested) && !url) {
+    throw new Error('Visual verification requires --url <http://localhost:port/path>.');
+  }
+  return {
+    uiMode,
+    screenshotMode,
+    captureOnly: uiMode === 'never' && screenshotMode === 'always',
+    run: Boolean(url) && (uiMode === 'always' || screenshotRequested),
+  };
+}
+
+function walkNodes(node, visit) {
+  if (!node) return;
+  visit(node);
+  for (const child of node.childNodes || []) walkNodes(child, visit);
+}
+
+async function verifyPageComponents(projectDir, selected) {
+  const pages = selected.filter(item => item.resourceType === 'pages');
+  if (!pages.length) return [];
+  const config = loadProjectConfig(projectDir);
+  const manifest = loadManifest(projectDir);
+  const uses = [];
+  for (const page of pages) {
+    const entry = getEntry(manifest, 'pages', page.resourceId);
+    if (!entry) continue;
+    const file = absolutePath(projectDir, entry.local_path);
+    const source = fs.readFileSync(file, 'utf8');
+    const document = parse5.parse(source);
+    const instances = new Set();
+    walkNodes(document, node => {
+      const attrs = new Map((node.attrs || []).map(attr => [attr.name, attr.value]));
+      const name = attrs.get('data-dg-use');
+      if (!name) return;
+      if (!/^([a-z][a-z0-9-]*)\/([a-z][a-z0-9-]*)$/.test(name)) throw new Error(`pages ${page.resourceId}: invalid data-dg-use "${name}"`);
+      const instance = attrs.get('data-dg-instance');
+      if (instance) { if (instances.has(instance)) throw new Error(`pages ${page.resourceId}: duplicate data-dg-instance "${instance}"`); instances.add(instance); }
+      uses.push({ page: page.resourceId, node, attrs, name });
+    });
+  }
+  const cache = new Map();
+  for (const use of uses) {
+    if (!cache.has(use.name)) {
+      const slug = use.name.split('/')[1];
+      const response = await fetch(`${config.server}/api/components?library=${encodeURIComponent(use.name.split('/')[0])}&q=${encodeURIComponent(slug)}&page_size=100`, { headers: { Authorization: `Bearer ${config.token}` } });
+      const payload = await response.json().catch(() => ({}));
+      if (!response.ok) throw new Error(`component lookup failed for ${use.name} (${response.status})`);
+      const items = payload.data?.items || payload.items || [];
+      cache.set(use.name, items.find(item => item.slug === slug && (item.library_slug === use.name.split('/')[0] || item.full_name === use.name)) || null);
+    }
+    const component = cache.get(use.name);
+    if (!component) throw new Error(`pages ${use.page}: component not found ${use.name}`);
+    if (!component.published || Number(component.published_revision || 0) < 1) throw new Error(`pages ${use.page}: component is not published ${use.name}`);
+    const definition = component.published;
+    const rootTag = String(definition.root_tag || '').toLowerCase();
+    if (rootTag && String(use.node.nodeName || '').toLowerCase() !== rootTag) throw new Error(`pages ${use.page}: ${use.name} requires <${rootTag}> but found <${use.node.nodeName}>`);
+    const props = new Map((definition.props || []).map(prop => [prop.name, prop]));
+    for (const [name, value] of use.attrs) {
+      if (!name.startsWith('data-dg-prop-')) continue;
+      const propName = name.slice('data-dg-prop-'.length);
+      const prop = props.get(propName);
+      if (!prop) throw new Error(`pages ${use.page}: unknown prop ${name} on ${use.name}`);
+      if (prop.type === 'boolean' && !['', 'true', 'false', '1', '0'].includes(String(value).toLowerCase())) {
+        throw new Error(`pages ${use.page}: invalid boolean prop ${name} on ${use.name}`);
+      }
+      if (prop.type === 'number' && !Number.isFinite(Number(value))) {
+        throw new Error(`pages ${use.page}: invalid number prop ${name} on ${use.name}`);
+      }
+    }
+    const slots = new Set((definition.slots || []).map(slot => slot.name));
+    for (const child of use.node.childNodes || []) {
+      const slot = (child.attrs || []).find(attr => attr.name === 'data-dg-slot')?.value;
+      if (slot && slots.size && !slots.has(slot)) throw new Error(`pages ${use.page}: unknown slot ${slot} on ${use.name}`);
+    }
+  }
+  return uses;
+}
+
 async function verify(projectDir, positional = [], flags = {}) {
   let selected;
-  let uiMode;
   let remoteMode;
   try {
     selected = resources(positional);
-    uiMode = mode(flags.ui, 'auto', '--ui');
     remoteMode = flags.remote ? 'always' : 'never';
   } catch (error) {
     log.err(error.message);
@@ -45,6 +137,8 @@ async function verify(projectDir, positional = [], flags = {}) {
   }
 
   log.title('draftgo verify');
+  try { await verifyPageComponents(projectDir, selected); }
+  catch (error) { log.err(error.message); return 1; }
   const checkCode = await check(projectDir, [], {
     strict: flags.strict,
     remote: remoteMode === 'always',
@@ -55,31 +149,32 @@ async function verify(projectDir, positional = [], flags = {}) {
   if (checkCode !== 0) return checkCode;
 
   const url = String(flags.url || '').trim();
-  const runUi = uiMode === 'always' || (uiMode === 'auto' && Boolean(url));
-  if (!runUi) {
-    if (uiMode === 'always' && !url) {
-      log.err('--ui always requires --url <http://localhost:port/path>.');
-      return 1;
-    }
+  let visual;
+  try { visual = visualRequest(flags, url); }
+  catch (error) { log.err(error.message); return 1; }
+  if (!visual.run) {
+    if (url) log.warn('--url was provided without --screenshot always or --ui always; visual verification was skipped.');
     log.ok('Unified verification passed (UI skipped).');
     return 0;
   }
-  if (selected.length > 1) {
-    log.err('One --url can assert at most one resource. Run verify once per route for UI validation.');
-    return 1;
-  }
-
   let targets;
   try { targets = viewports(flags); }
   catch (error) { log.err(error.message); return 1; }
   for (const viewport of targets) {
-    const uiFlags = { ...flags, url, width: viewport.width, height: viewport.height, 'mobile-check': 'always' };
-    if (remoteMode === 'always' && selected.length === 1 && !uiFlags.resource) {
-      uiFlags.resource = `${selected[0].resourceType}:${selected[0].resourceId}`;
-    }
-    const code = await verifyUi(projectDir, [url], uiFlags);
+    const uiFlags = {
+      ...flags,
+      url,
+      width: viewport.width,
+      height: viewport.height,
+      'capture-only': visual.captureOnly,
+    };
+    const code = await visualVerify(projectDir, [url], uiFlags);
     if (code !== 0) return code;
   }
+  if (visual.captureOnly) {
+    log.ok(`Visual capture completed (${targets.map((item) => item.name).join(', ')}).`);
+    return 0;
+  }
   log.ok(`Unified verification passed (${targets.map((item) => item.name).join(', ')}).`);
   return 0;
 }
@@ -88,3 +183,5 @@ module.exports = verify;
 module.exports.mode = mode;
 module.exports.resources = resources;
 module.exports.viewports = viewports;
+module.exports.visualRequest = visualRequest;
+module.exports.verifyPageComponents = verifyPageComponents;

package/src/commands/{verifyUi.js → visualVerify.js}

@@ -3,53 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 const runtimeFiles = require('../runtimeFiles');
-const { spawnSync } = require('child_process');
 const log = require('../logger');
 const { configPath, loadProjectConfig } = require('../projectConfig');
-const { loadManifest, getEntry } = require('../worktree/manifest');
-const { canonicalResourceType } = require('../worktree/types');
-const { resolveMetadata } = require('../worktree/backend');
-const { inspectEntry, openMetadataSession } = require('../worktree/status');
-
-const UI_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.html', '.htm', '.jsx', '.tsx', '.vue', '.svelte']);
-
-function isUiFile(file) {
-  const normalized = String(file || '').replace(/\\/g, '/').toLowerCase();
-  const ext = path.extname(normalized);
-  if (UI_EXTENSIONS.has(ext)) return true;
-  if (!['.js', '.ts'].includes(ext)) return false;
-  return /(^|\/)(frontend|web|ui|components|pages|views|client)(\/|$)/.test(normalized)
-    || /(^|\/)(app|main|client)\.(js|ts)$/.test(normalized)
-    || normalized.startsWith('.draftgo/worktree/pages/')
-    || normalized.startsWith('.draftgo/worktree/navigations/')
-    || normalized.startsWith('.draftgo/worktree/docs/');
-}
-
-function gitChangedFiles(projectDir) {
-  const r = spawnSync('git', ['status', '--porcelain=v1', '--untracked-files=all'], {
-    cwd: projectDir,
-    encoding: 'utf8',
-    shell: false,
-  });
-  if (r.error || r.status !== 0) return null;
-  return String(r.stdout || '').split(/\r?\n/).filter(Boolean).map((line) => {
-    const raw = line.slice(3).trim();
-    const renamed = raw.includes(' -> ') ? raw.split(' -> ').pop() : raw;
-    return renamed.replace(/^"|"$/g, '');
-  });
-}
-
-function decideMobileCheck(projectDir, mode) {
-  if (mode === 'always') return { run: true, reason: 'mobile-check=always' };
-  if (mode === 'never') return { run: false, reason: 'mobile-check=never' };
-  const changed = gitChangedFiles(projectDir);
-  if (changed === null || changed.length === 0) {
-    return { run: true, reason: '无法从 Git diff 确认影响范围，执行单视口 smoke check' };
-  }
-  const uiFiles = changed.filter(isUiFile);
-  if (!uiFiles.length) return { run: false, reason: '本次变更未涉及页面、样式或前端组件' };
-  return { run: true, reason: `检测到 ${uiFiles.length} 个 UI 文件变更` };
-}
 
 function numberFlag(value, fallback, min, max) {
   const n = Number(value);
@@ -154,15 +109,6 @@ async function launchBrowser(chromium, requested, requestedPath) {
     + (lastError ? `；最后错误：${lastError.message.split('\n')[0]}` : ''));
 }
 
-function parseResourceSpec(value) {
-  const raw = String(value || '');
-  const separator = raw.indexOf(':');
-  if (separator <= 0 || separator === raw.length - 1) {
-    throw new Error('--resource 格式必须是 <pages|nav|docs>:<id>。');
-  }
-  return { resourceType: canonicalResourceType(raw.slice(0, separator)), resourceId: raw.slice(separator + 1) };
-}
-
 async function selectFrames(page, mode = 'auto') {
   const top = page.mainFrame ? page.mainFrame() : page;
   const selected = [{ frame: top, label: 'top' }];
@@ -208,50 +154,33 @@ async function inspectFrame(frame) {
   });
 }
 
-async function verifyRemoteResource(projectDir, spec) {
-  const { resourceType, resourceId } = parseResourceSpec(spec);
-  const entry = getEntry(loadManifest(projectDir), resourceType, resourceId);
-  if (!entry) throw new Error(`${resourceType} ${resourceId} 未 checkout。`);
-  const config = loadProjectConfig(projectDir);
-  const session = await openMetadataSession(config);
-  const remote = await resolveMetadata(config, resourceType, resourceId, {
-    ...session,
-    clientInitialized: true,
-  });
-  return inspectEntry(projectDir, entry, remote);
+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 verifyUi(projectDir, positional, flags = {}) {
+async function visualVerify(projectDir, positional, flags = {}) {
   const rawUrl = String(flags.url || positional[0] || '').trim();
   if (!/^https?:\/\//i.test(rawUrl)) {
-    log.err('用法：draftgo verify-ui <http://localhost:port/path>');
+    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 在 verify-ui 中只支持 auto、never。');
+    log.err('--token in visual verification accepts auto or never.');
     return 1;
   }
 
-  const mode = String(flags['mobile-check'] || 'auto').toLowerCase();
-  if (!['auto', 'always', 'never'].includes(mode)) {
-    log.err('--mobile-check 只支持 auto、always、never。');
-    return 1;
-  }
-  const decision = flags.resource
-    ? { run: true, reason: `resource=${flags.resource}` }
-    : decideMobileCheck(projectDir, mode);
-  if (!decision.run) {
-    log.ok(`跳过 UI smoke check：${decision.reason}`);
-    return 0;
-  }
-
   let url;
   try {
     url = configuredUiUrl(projectDir, rawUrl, tokenMode);
   } catch (err) {
-    log.err(`无法读取 verify-ui 的项目配置：${err.message}`);
+    log.err(`Unable to read visual verification config: ${err.message}`);
     return 1;
   }
 
@@ -263,30 +192,18 @@ async function verifyUi(projectDir, positional, flags = {}) {
     return 1;
   }
 
-  const width = numberFlag(flags.width, 390, 240, 3840);
-  const height = numberFlag(flags.height, 844, 320, 2160);
+  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 (!['on-failure', 'always', 'never'].includes(screenshotMode)) {
-    log.err('--screenshot 只支持 on-failure、always、never。');
+  if (!['always', 'never'].includes(screenshotMode)) {
+    log.err('--screenshot accepts always or never.');
     return 1;
   }
 
   let browser;
   try {
-    if (flags.resource) {
-      const resource = await verifyRemoteResource(projectDir, flags.resource);
-      log.info(`UI source: remote committed ${resource.resource_type} ${resource.resource_id}`);
-      log.info(`Remote version: ${resource.remote_version || '-'}; remote hash: ${resource.remote_hash || '-'}`);
-      if (['local_modified', 'diverged'].includes(resource.state)) {
-        log.warn(`Local worktree is not committed (${resource.state}); verify-ui will test the remote version.`);
-      }
-      if (!resource.local_matches_remote && resource.state !== 'local_modified') {
-        throw new Error(`Local and remote content differ (${resource.state}); UI verification stopped.`);
-      }
-    } else {
-      log.info('UI source: remote URL response; no local worktree version was asserted.');
-    }
+    log.info('UI source: requested URL response.');
     const launch = await launchBrowser(
       chromium,
       flags.browser && String(flags.browser),
@@ -302,6 +219,15 @@ async function verifyUi(projectDir, positional, flags = {}) {
 
     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) });
@@ -326,16 +252,6 @@ async function verifyUi(projectDir, positional, flags = {}) {
       else log.info(`Selector ${flags.selector}: visible in ${match}`);
     }
 
-    const shouldScreenshot = screenshotMode === 'always' || (screenshotMode === 'on-failure' && issues.length > 0);
-    let screenshotPath = null;
-    if (shouldScreenshot) {
-      const dir = path.join(projectDir, '.draftgo', 'artifacts', 'ui');
-      fs.mkdirSync(dir, { recursive: true });
-      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-ui');
-    }
-
     if (issues.length) {
       issues.forEach((issue) => log.err(issue));
       if (consoleErrors.length) consoleErrors.slice(0, 5).forEach((msg) => log.dim(`  console: ${msg}`));
@@ -344,7 +260,7 @@ async function verifyUi(projectDir, positional, flags = {}) {
       return 1;
     }
 
-    log.ok(`UI smoke check 通过：${width}x${height}，${frames.length} frame(s)，${decision.reason}`);
+    log.ok(`UI smoke check passed: ${width}x${height}, ${frames.length} frame(s).`);
     if (screenshotPath) log.info(`截图：${screenshotPath}`);
     return 0;
   } catch (err) {
@@ -355,15 +271,11 @@ async function verifyUi(projectDir, positional, flags = {}) {
   }
 }
 
-module.exports = verifyUi;
-module.exports.decideMobileCheck = decideMobileCheck;
-module.exports.gitChangedFiles = gitChangedFiles;
-module.exports.isUiFile = isUiFile;
+module.exports = visualVerify;
 module.exports.configuredUiUrl = configuredUiUrl;
 module.exports.redactUrlTokens = redactUrlTokens;
 module.exports.executableCandidates = executableCandidates;
 module.exports.playwrightCacheCandidates = playwrightCacheCandidates;
-module.exports.parseResourceSpec = parseResourceSpec;
-module.exports.verifyRemoteResource = verifyRemoteResource;
 module.exports.selectFrames = selectFrames;
 module.exports.inspectFrame = inspectFrame;
+module.exports.captureScreenshot = captureScreenshot;

package/src/commands/worklog.js

@@ -0,0 +1,90 @@
+'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|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 };
+}
+
+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) {
+  const blocks = 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 = readWorklog(projectDir);
+  const items = blocks.flatMap((block) => block.entries.map((entry) => ({ date: block.date, ...entry })));
+  output(flags, { path: worklogPath(projectDir), items });
+  if (flags.output !== 'json') items.forEach((item) => log.info(`${item.date}#${item.number} [${item.status}] ${item.title}`));
+  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, 'pending');
+  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);
+  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,57 @@
+'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 || {};
+  return operation.destructive === true || String(operation.risk || '').toLowerCase() === 'high';
+}
+
+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 incompatibleOperationError(operationId, error) {
+  const wrapped = new Error(
+    `DraftGo CLI and server contracts are incompatible for dangerous 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,
+  incompatibleOperationError,
+};