@dotdotgod/cli 0.1.35 → 0.1.40

package/src/trello/custom-fields.mjs

@@ -0,0 +1,106 @@
+export const DEFAULT_DOTDOTGOD_CUSTOM_FIELD_NAME = 'dotdotgod-view';
+
+function cleanString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function dotdotgodCustomFieldName({ env = process.env, name = '' } = {}) {
+  return cleanString(name) || cleanString(env.DOTDOTGOD_TRELLO_CUSTOM_FIELD_NAME) || DEFAULT_DOTDOTGOD_CUSTOM_FIELD_NAME;
+}
+
+export function buildLinkedDocsCustomFieldData({ docsPath, githubUrl, trelloUrl, repositoryKey, repositoryLabel, title, summary, traceabilityState, traceabilityDetails = [] } = {}) {
+  return {
+    repositoryKey: cleanString(repositoryKey),
+    repositoryLabel: cleanString(repositoryLabel) || cleanString(repositoryKey).split('/').filter(Boolean).at(-1) || '',
+    docsPath: cleanString(docsPath),
+    githubUrl: cleanString(githubUrl),
+    trelloUrl: cleanString(trelloUrl),
+    title: cleanString(title),
+    summary: cleanString(summary),
+    traceabilityState: cleanString(traceabilityState) || 'not_required',
+    traceabilityDetails: Array.isArray(traceabilityDetails) ? traceabilityDetails.map((item) => String(item)) : [],
+  };
+}
+
+function normalizeEntry(entry = {}) {
+  return buildLinkedDocsCustomFieldData(entry);
+}
+
+export function serializeLinkedDocsCustomFieldPayload(entries = []) {
+  return JSON.stringify({ version: 1, entries: entries.map(normalizeEntry) });
+}
+
+export function parseLinkedDocsCustomFieldPayload(text = '') {
+  const value = cleanString(text);
+  if (!value) return { ok: true, entries: [] };
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: 'TRELLO_CUSTOM_FIELD_INVALID',
+        message: `dotdotgod custom field contains invalid JSON. Cause: ${error.message}. Fix: clear the custom field or restore a valid dotdotgod linked-docs payload, then retry sync.`,
+      },
+    };
+  }
+  if (!parsed || parsed.version !== 1 || !Array.isArray(parsed.entries)) {
+    return {
+      ok: false,
+      error: {
+        code: 'TRELLO_CUSTOM_FIELD_INVALID',
+        message: 'dotdotgod custom field has an unsupported shape. Fix: clear the custom field or restore a version 1 linked-docs payload with an entries array, then retry sync.',
+      },
+    };
+  }
+  const entries = parsed.entries.map(normalizeEntry);
+  const keys = entries.map((entry) => entry.repositoryKey).filter(Boolean);
+  if (keys.length !== new Set(keys).size) {
+    return {
+      ok: false,
+      error: {
+        code: 'TRELLO_CUSTOM_FIELD_DUPLICATE_REPOSITORY',
+        message: 'dotdotgod custom field contains duplicate repository entries. Fix: keep one entry per repository key, then retry sync.',
+      },
+    };
+  }
+  return { ok: true, entries };
+}
+
+export function mergeLinkedDocsCustomFieldValue(existingText = '', entry = {}) {
+  const current = normalizeEntry(entry);
+  if (!current.repositoryKey) {
+    return {
+      ok: false,
+      error: {
+        code: 'TRELLO_CUSTOM_FIELD_REPOSITORY_MISSING',
+        message: 'Cannot update dotdotgod custom field without a repository key. Fix: run from a trusted GitHub Actions repository or configure repository metadata, then retry sync.',
+      },
+    };
+  }
+  const parsed = parseLinkedDocsCustomFieldPayload(existingText);
+  if (!parsed.ok) return parsed;
+  const entries = [...parsed.entries];
+  const index = entries.findIndex((item) => item.repositoryKey === current.repositoryKey);
+  let action = 'create-payload';
+  if (index >= 0) {
+    const before = JSON.stringify(entries[index]);
+    const after = JSON.stringify(current);
+    action = before === after ? 'unchanged-entry' : 'replace-entry';
+    entries[index] = current;
+  } else if (entries.length > 0) {
+    action = 'append-entry';
+    entries.push(current);
+  } else {
+    entries.push(current);
+  }
+  const text = serializeLinkedDocsCustomFieldPayload(entries);
+  const status = cleanString(existingText) === text ? 'unchanged' : 'written';
+  return { ok: true, status, action: status === 'unchanged' ? 'unchanged-entry' : action, text, entries, preservedRepositoryEntries: entries.filter((item) => item.repositoryKey !== current.repositoryKey).length };
+}
+
+export function customFieldTextValue(card = {}, idCustomField = '') {
+  const item = Array.isArray(card.customFieldItems) ? card.customFieldItems.find((fieldItem) => fieldItem?.idCustomField === idCustomField) : null;
+  return typeof item?.value?.text === 'string' ? item.value.text : '';
+}

package/src/trello/github-url.mjs

@@ -0,0 +1,107 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+export function normalizeGitHubRepositoryKey(value = '') {
+  const text = String(value).trim();
+  const match = text.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/u);
+  if (!match) return null;
+  return `${match[1]}/${match[2]}`;
+}
+
+export function normalizeGitHubRemote(value = '') {
+  const text = String(value).trim();
+  if (!text) return null;
+  let match = text.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/u);
+  if (match) return { repositoryUrl: `https://github.com/${match[1]}/${match[2]}`, repositoryKey: `${match[1]}/${match[2]}` };
+  match = text.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/u);
+  if (match) return { repositoryUrl: `https://github.com/${match[1]}/${match[2]}`, repositoryKey: `${match[1]}/${match[2]}` };
+  return null;
+}
+
+function encodePath(path = '') {
+  return path.split('/').map((part) => encodeURIComponent(part)).join('/');
+}
+
+function repositoryFromPackage(root) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    const raw = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+    return normalizeGitHubRemote(String(raw ?? '').replace(/^git\+/, ''));
+  } catch {
+    return null;
+  }
+}
+
+function gitValue(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  if (result.status !== 0) return '';
+  return result.stdout.trim();
+}
+
+function repositoryResult(repositoryUrl, repositoryKey, source, warnings = []) {
+  return { ok: true, repositoryUrl, repositoryKey, source, warnings, errors: [] };
+}
+
+export function resolveGitHubRepositoryIdentity({ root = '.', repository, repositoryUrl, remoteUrl, env = process.env, git = true, mode = 'dry-run' } = {}) {
+  const warnings = [];
+  const explicitKey = normalizeGitHubRepositoryKey(repository);
+  if (explicitKey) return repositoryResult(`https://github.com/${explicitKey}`, explicitKey, 'explicit-repository', warnings);
+
+  const explicitRemote = normalizeGitHubRemote(repositoryUrl);
+  if (explicitRemote) return repositoryResult(explicitRemote.repositoryUrl, explicitRemote.repositoryKey, 'explicit-repository-url', warnings);
+
+  const actionsKey = normalizeGitHubRepositoryKey(env?.GITHUB_REPOSITORY);
+  if (actionsKey) return repositoryResult(`https://github.com/${actionsKey}`, actionsKey, 'github-actions', warnings);
+  if (mode === 'write' && env?.GITHUB_REPOSITORY && !actionsKey) {
+    return { ok: false, repositoryUrl: '', repositoryKey: '', source: '', warnings, errors: [{ code: 'GITHUB_REPOSITORY_KEY_INVALID', message: 'Could not resolve a valid GitHub repository key from GITHUB_REPOSITORY. Fix: run the trusted workflow with GITHUB_REPOSITORY in owner/name form, then retry sync.' }] };
+  }
+
+  const injectedRemote = normalizeGitHubRemote(remoteUrl);
+  if (injectedRemote) {
+    warnings.push({ code: 'GITHUB_URL_REMOTE_FALLBACK', message: 'GitHub URL resolved from injected git remote fallback.' });
+    return repositoryResult(injectedRemote.repositoryUrl, injectedRemote.repositoryKey, 'remote-url', warnings);
+  }
+
+  if (mode !== 'write') {
+    const packageRepo = repositoryFromPackage(root);
+    if (packageRepo) {
+      warnings.push({ code: 'GITHUB_URL_PACKAGE_FALLBACK', message: 'GitHub URL resolved from package repository metadata.' });
+      return repositoryResult(packageRepo.repositoryUrl, packageRepo.repositoryKey, 'package', warnings);
+    }
+    if (git) {
+      const remote = gitValue(root, ['remote', 'get-url', 'origin']);
+      const gitRepo = normalizeGitHubRemote(remote);
+      if (gitRepo) {
+        warnings.push({ code: 'GITHUB_URL_GIT_REMOTE_FALLBACK', message: 'GitHub URL resolved from local git origin remote.' });
+        return repositoryResult(gitRepo.repositoryUrl, gitRepo.repositoryKey, 'git-remote', warnings);
+      }
+    }
+  }
+
+  const code = mode === 'write' ? 'GITHUB_REPOSITORY_KEY_UNRESOLVED' : 'GITHUB_URL_UNRESOLVED_REPOSITORY';
+  const message = mode === 'write'
+    ? 'Could not resolve a trusted GitHub repository key for Trello custom field entry. Fix: run write mode from GitHub Actions with GITHUB_REPOSITORY or provide explicit GitHub repository metadata, then retry sync.'
+    : 'Could not resolve a GitHub repository URL.';
+  return { ok: false, repositoryUrl: '', repositoryKey: '', source: '', warnings, errors: [{ code, message }] };
+}
+
+export function resolveGitHubFileUrl({ root = '.', file, repository, repositoryUrl, branch, remoteUrl, env = process.env, git = true, mode = 'dry-run' } = {}) {
+  const identity = resolveGitHubRepositoryIdentity({ root, repository, repositoryUrl, remoteUrl, env, git, mode });
+  const warnings = [...(identity.warnings ?? [])];
+  let resolvedBranch = branch;
+  if (!resolvedBranch && mode === 'write') {
+    if (env?.GITHUB_REF_NAME) resolvedBranch = env.GITHUB_REF_NAME;
+    else if (typeof env?.GITHUB_REF === 'string' && env.GITHUB_REF.startsWith('refs/heads/')) resolvedBranch = env.GITHUB_REF.slice('refs/heads/'.length);
+    else if (env?.GITHUB_DEFAULT_BRANCH) resolvedBranch = env.GITHUB_DEFAULT_BRANCH;
+  }
+  if (!resolvedBranch && git && mode !== 'write') {
+    resolvedBranch = gitValue(root, ['branch', '--show-current']);
+    if (resolvedBranch) warnings.push({ code: 'GITHUB_URL_GIT_BRANCH_FALLBACK', message: 'GitHub branch resolved from local git state.' });
+  }
+  const errors = [];
+  if (!identity.ok) errors.push(...identity.errors);
+  if (!resolvedBranch) errors.push({ code: 'GITHUB_URL_UNRESOLVED_BRANCH', message: 'Could not resolve a GitHub branch.' });
+  if (errors.length > 0) return { ok: false, url: '', repositoryKey: identity.repositoryKey ?? '', repositoryUrl: identity.repositoryUrl ?? '', warnings, errors };
+  return { ok: true, url: `${identity.repositoryUrl}/blob/${encodeURIComponent(resolvedBranch)}/${encodePath(file)}`, repositoryKey: identity.repositoryKey, repositoryUrl: identity.repositoryUrl, warnings, errors: [] };
+}

package/src/trello/metadata.mjs

@@ -0,0 +1,52 @@
+const TRELLO_KEYS = new Set(['trelloUrl', 'trelloShortLink', 'trelloCardId']);
+
+export function parseFrontmatter(content = '') {
+  if (!String(content).startsWith('---\n')) return { data: {}, errors: [] };
+  const end = String(content).indexOf('\n---', 4);
+  if (end === -1) return { data: {}, errors: [{ code: 'TRELLO_FRONTMATTER_INVALID', message: 'Frontmatter start marker is missing a closing marker.' }] };
+  const raw = String(content).slice(4, end).split('\n');
+  const data = {};
+  const errors = [];
+  for (const [index, line] of raw.entries()) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = trimmed.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    if (Object.hasOwn(data, key)) errors.push({ code: 'TRELLO_FRONTMATTER_DUPLICATE_KEY', message: `Duplicate frontmatter key: ${key}.`, line: index + 2 });
+    data[key] = value;
+  }
+  return { data, errors };
+}
+
+export function extractTrelloShortLink(trelloUrl = '') {
+  let url;
+  try {
+    url = new URL(trelloUrl);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'https:' || url.hostname !== 'trello.com') return null;
+  const parts = url.pathname.split('/').filter(Boolean);
+  if (parts[0] !== 'c' || !parts[1] || parts.length > 3) return null;
+  return parts[1];
+}
+
+export function parseTrelloMetadata(content = '') {
+  const { data, errors } = parseFrontmatter(content);
+  const warnings = [];
+  const unsupported = [...TRELLO_KEYS].filter((key) => key !== 'trelloUrl' && Object.hasOwn(data, key));
+  const trelloUrl = typeof data.trelloUrl === 'string' ? data.trelloUrl.trim() : '';
+  if (unsupported.length > 0) {
+    warnings.push({ code: 'TRELLO_UNSUPPORTED_METADATA', message: `Unsupported Trello metadata ignored in Phase 1: ${unsupported.join(', ')}. Use trelloUrl only.` });
+  }
+  if (!trelloUrl) {
+    errors.push({ code: 'TRELLO_METADATA_MISSING_URL', message: 'Missing required frontmatter field: trelloUrl.' });
+    return { ok: false, trelloUrl: '', shortLink: '', warnings, errors };
+  }
+  const shortLink = extractTrelloShortLink(trelloUrl);
+  if (!shortLink) errors.push({ code: 'TRELLO_METADATA_INVALID_URL', message: 'trelloUrl must match https://trello.com/c/<shortLink>/ or https://trello.com/c/<shortLink>/<slug>.' });
+  return { ok: errors.length === 0, trelloUrl, shortLink: shortLink ?? '', warnings, errors };
+}

package/src/trello/report.mjs

@@ -0,0 +1,60 @@
+function plural(value, label) {
+  return `${value} ${label}${value === 1 ? '' : 's'}`;
+}
+
+function pushMessages(lines, label, messages, indent = '') {
+  if ((messages ?? []).length === 0) return;
+  lines.push(`${indent}${label}:`);
+  for (const message of messages) lines.push(`${indent}  - ${message.code}: ${message.message}`);
+}
+
+export function formatTrelloDryRunReport(report) {
+  const lines = ['Trello docs sync dry-run'];
+  lines.push(`Root: ${report.root}`);
+  lines.push(`Scan paths: ${report.scanPaths.join(', ')}`);
+  lines.push(`Matched: ${plural(report.totals.matchedFiles, 'file')}; planned: ${plural(report.totals.plannedUpdates, 'update')}; warnings: ${report.totals.warnings}; errors: ${report.totals.errors}`);
+  pushMessages(lines, 'Warnings', report.warnings);
+  pushMessages(lines, 'Errors', report.errors);
+  for (const file of report.files) {
+    lines.push('');
+    lines.push(`File: ${file.file}`);
+    lines.push(`  Trello URL: ${file.trelloUrl || '(missing)'}`);
+    if (file.shortLink) lines.push(`  Trello short link: ${file.shortLink}`);
+    lines.push(`  GitHub URL: ${file.githubUrl || '(unresolved)'}`);
+    if (file.repositoryKey) lines.push(`  Repository entry: ${file.repositoryKey}`);
+    lines.push(`  Planned attachment: ${file.plannedAttachmentAction}`);
+    lines.push(`  Planned custom field: ${file.plannedCustomFieldAction}`);
+    lines.push(`  Sync status: ${file.syncStatus}`);
+    lines.push(`  Traceability: ${file.traceability.state}${file.traceability.details.length ? ` (${file.traceability.details.join(', ')})` : ''}`);
+    pushMessages(lines, 'Warnings', file.warnings, '  ');
+    pushMessages(lines, 'Errors', file.errors, '  ');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function formatTrelloWriteReport(report) {
+  const lines = ['Trello docs sync write'];
+  lines.push(`Root: ${report.root}`);
+  lines.push(`Scan paths: ${report.scanPaths.join(', ')}`);
+  lines.push(`Matched: ${plural(report.totals.matchedFiles, 'file')}; written: ${report.totals.written}; unchanged: ${report.totals.unchanged}; blocked: ${report.totals.blocked}; conflict: ${report.totals.conflict}; api-failed: ${report.totals.apiFailed}; warnings: ${report.totals.warnings}; errors: ${report.totals.errors}`);
+  pushMessages(lines, 'Warnings', report.warnings);
+  pushMessages(lines, 'Errors', report.errors);
+  for (const file of report.files) {
+    lines.push('');
+    lines.push(`File: ${file.file}`);
+    lines.push(`  Trello URL: ${file.trelloUrl || '(missing)'}`);
+    if (file.shortLink) lines.push(`  Trello short link: ${file.shortLink}`);
+    lines.push(`  GitHub URL: ${file.githubUrl || '(unresolved)'}`);
+    if (file.repositoryKey) lines.push(`  Repository entry: ${file.repositoryKey}`);
+    lines.push(`  Attachment: ${file.attachment?.status ?? 'not-run'}`);
+    const customFieldAction = file.customField?.action ? ` (${file.customField.action})` : '';
+    lines.push(`  Custom field: ${file.customField?.status ?? 'not-run'}${customFieldAction}`);
+    if (file.customField?.name) lines.push(`  Custom field name: ${file.customField.name}`);
+    if (file.customField?.preservedRepositoryEntries > 0) lines.push(`  Preserved repository entries: ${file.customField.preservedRepositoryEntries}`);
+    lines.push(`  Final status: ${file.finalStatus ?? file.syncStatus}`);
+    lines.push(`  Traceability: ${file.traceability.state}${file.traceability.details.length ? ` (${file.traceability.details.join(', ')})` : ''}`);
+    pushMessages(lines, 'Warnings', file.warnings, '  ');
+    pushMessages(lines, 'Errors', file.errors, '  ');
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/trello/summary.mjs

@@ -0,0 +1,60 @@
+import { extractDotdotgodTraceabilityBlocks, validateTraceabilityBlock } from '../docs/traceability.mjs';
+import { requiresTraceability } from '../memory/config.mjs';
+
+export function summarizeTraceability({ content = '', root = '.', file = '', config } = {}) {
+  const blocks = extractDotdotgodTraceabilityBlocks(content);
+  if (blocks.some((block) => block.error)) {
+    return { state: 'invalid', details: blocks.filter((block) => block.error).map((block) => `Invalid JSON at line ${block.line}: ${block.error}`), errors: [{ code: 'TRELLO_TRACEABILITY_INVALID', message: 'Malformed json dotdotgod traceability block.' }] };
+  }
+  if (blocks.length === 0) {
+    const required = requiresTraceability(file, config);
+    return { state: required ? 'missing' : 'not_required', details: [], errors: required ? [{ code: 'TRELLO_TRACEABILITY_MISSING', message: 'Missing required json dotdotgod traceability block.' }] : [] };
+  }
+  const errors = blocks.flatMap((block) => validateTraceabilityBlock(block.data, root, file, block.line, config));
+  if (errors.length > 0) return { state: 'invalid', details: errors.map((error) => `${error.code}: ${error.message.split('\n')[0]}`), errors: [{ code: 'TRELLO_TRACEABILITY_INVALID', message: 'Invalid json dotdotgod traceability block.' }] };
+  const latest = blocks.at(-1).data;
+  const details = [];
+  if (Array.isArray(latest.implementedBy) && latest.implementedBy.length > 0) details.push(`implementedBy: ${latest.implementedBy.length}`);
+  if (Array.isArray(latest.verifiedBy) && latest.verifiedBy.length > 0) details.push(`verifiedBy: ${latest.verifiedBy.length}`);
+  if (Array.isArray(latest.relatedDocs) && latest.relatedDocs.length > 0) details.push(`relatedDocs: ${latest.relatedDocs.length}`);
+  return { state: 'present', details, errors: [] };
+}
+
+function stripFrontmatter(content = '') {
+  return String(content).replace(/^---\n[\s\S]*?\n---\n?/u, '');
+}
+
+function stripCodeBlocks(content = '') {
+  return String(content).replace(/```[\s\S]*?```/gu, '');
+}
+
+function compactText(value = '', maxLength = 280) {
+  const compact = String(value).replace(/\s+/gu, ' ').trim();
+  if (compact.length <= maxLength) return compact;
+  return `${compact.slice(0, maxLength - 1).trimEnd()}…`;
+}
+
+export function summarizeMarkdownPreview({ content = '', file = '' } = {}) {
+  const body = stripCodeBlocks(stripFrontmatter(content));
+  const lines = body.split(/\r?\n/u).map((line) => line.trim());
+  const title = lines.find((line) => /^#\s+\S/u.test(line))?.replace(/^#\s+/u, '').trim() || file.split('/').at(-1)?.replace(/\.md$/u, '') || '';
+  const summary = compactText(lines.find((line) => line && !line.startsWith('#') && !line.startsWith('<!--') && !line.startsWith('- ') && !line.startsWith('|')) ?? '');
+  return { title: compactText(title, 120), summary };
+}
+
+export function buildLinkedDocsData({ file, content = '', githubUrl, trelloUrl, syncStatus, traceability, repositoryKey } = {}) {
+  const preview = summarizeMarkdownPreview({ content, file });
+  return {
+    docsPath: file,
+    githubUrl,
+    trelloUrl,
+    syncStatus,
+    repositoryKey,
+    repositoryLabel: String(repositoryKey ?? '').split('/').filter(Boolean).at(-1) || '',
+    title: preview.title,
+    summary: preview.summary,
+    traceabilityState: traceability?.state ?? 'not_required',
+    traceabilityDetails: [...(traceability?.details ?? [])],
+  };
+}
+

package/src/trello/sync.mjs

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { rel } from '../common/paths.mjs';
+import { matchPathPattern, readMemoryConfig, trelloSyncPaths } from '../memory/config.mjs';
+import { parseTrelloMetadata } from './metadata.mjs';
+import { resolveGitHubFileUrl } from './github-url.mjs';
+import { buildLinkedDocsData, summarizeTraceability } from './summary.mjs';
+import { formatTrelloDryRunReport, formatTrelloWriteReport } from './report.mjs';
+import { createTrelloClient, resolveTrelloCredentials } from './client.mjs';
+import { customFieldTextValue, dotdotgodCustomFieldName, mergeLinkedDocsCustomFieldValue } from './custom-fields.mjs';
+
+function shouldSkipDir(path) {
+  return path === '.git' || path === 'node_modules' || path === '.dotdotgod';
+}
+
+function walkMarkdown(root, dir = root, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!shouldSkipDir(entry.name)) walkMarkdown(root, join(dir, entry.name), files);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) files.push(join(dir, entry.name));
+  }
+  return files;
+}
+
+function matchedByPatterns(path, patterns) {
+  return patterns.some((pattern) => matchPathPattern(path, pattern));
+}
+
+function fileReport({ file, trelloUrl = '', shortLink = '', githubUrl = '', repositoryKey = '', syncStatus = 'blocked', traceability = { state: 'not_required', details: [] }, warnings = [], errors = [], linkedDocsData = null }) {
+  return { file, trelloUrl, shortLink, githubUrl, repositoryKey, plannedAttachmentAction: errors.length > 0 ? 'blocked' : 'add-or-verify', plannedCustomFieldAction: errors.length > 0 ? 'blocked' : 'sync-linked-docs', syncStatus, traceability, linkedDocsData, warnings, errors };
+}
+
+function actionableError(error, fallback = 'Trello API request failed. Fix: check credentials, card access, and Trello response details, then retry.') {
+  if (error && typeof error === 'object' && error.code && error.message) return error;
+  return { code: 'TRELLO_API_FAILED', message: error?.message ? `${error.message} Fix: check credentials, card access, and Trello response details, then retry.` : fallback };
+}
+
+function duplicateErrors(files) {
+  const byShortLink = new Map();
+  for (const file of files.filter((item) => item.syncStatus === 'planned')) {
+    byShortLink.set(file.shortLink, [...(byShortLink.get(file.shortLink) ?? []), file]);
+  }
+  const duplicateShortLinks = new Set([...byShortLink.entries()].filter(([, group]) => group.length > 1).map(([shortLink]) => shortLink));
+  for (const shortLink of duplicateShortLinks) {
+    const paths = byShortLink.get(shortLink).map((file) => file.file).join(', ');
+    for (const file of byShortLink.get(shortLink)) {
+      file.errors.push({ code: 'TRELLO_DUPLICATE_CARD', message: `Multiple markdown files point to Trello card ${shortLink}: ${paths}. Fix: keep only one markdown file linked to this Trello card, then retry sync.` });
+      file.syncStatus = 'conflict';
+      file.plannedAttachmentAction = 'conflict';
+      file.plannedCustomFieldAction = 'conflict';
+    }
+  }
+  return duplicateShortLinks.size;
+}
+
+export function planTrelloDryRun(rootInput = '.', options = {}) {
+  const root = resolve(rootInput);
+  const config = options.config ?? readMemoryConfig(root);
+  const scanPaths = trelloSyncPaths(config);
+  const reportWarnings = [];
+  const reportErrors = [];
+  if (config.errors?.length) reportErrors.push(...config.errors.map((error) => ({ code: error.code, message: error.message })));
+  const allFiles = walkMarkdown(root).map((file) => ({ abs: file, rel: rel(root, file) })).filter((file) => matchedByPatterns(file.rel, scanPaths)).sort((a, b) => a.rel.localeCompare(b.rel));
+  const files = [];
+  if (allFiles.length === 0) reportWarnings.push({ code: 'TRELLO_NO_MATCHING_DOCS', message: 'No markdown files matched Trello sync paths.' });
+  for (const item of allFiles) {
+    const content = readFileSync(item.abs, 'utf8');
+    const metadata = parseTrelloMetadata(content);
+    const warnings = [...metadata.warnings];
+    const errors = [...metadata.errors];
+    let githubUrl = '';
+    let repositoryKey = '';
+    if (errors.length === 0) {
+      const resolved = resolveGitHubFileUrl({ root, file: item.rel, env: options.env ?? process.env, mode: options.mode ?? 'dry-run', ...(options.github ?? {}) });
+      warnings.push(...resolved.warnings);
+      if (resolved.ok) {
+        githubUrl = resolved.url;
+        repositoryKey = resolved.repositoryKey;
+      } else errors.push(...resolved.errors);
+    }
+    const traceability = summarizeTraceability({ content, root, file: item.rel, config });
+    if (traceability.errors.length > 0) errors.push(...traceability.errors);
+    const syncStatus = errors.length > 0 ? 'blocked' : 'planned';
+    const linkedDocsData = buildLinkedDocsData({ file: item.rel, content, githubUrl, trelloUrl: metadata.trelloUrl, syncStatus, traceability, repositoryKey });
+    files.push(fileReport({ file: item.rel, trelloUrl: metadata.trelloUrl, shortLink: metadata.shortLink, githubUrl, repositoryKey, syncStatus, traceability: { state: traceability.state, details: traceability.details }, warnings, errors, linkedDocsData }));
+  }
+  duplicateErrors(files);
+  const warningCount = reportWarnings.length + files.reduce((sum, file) => sum + file.warnings.length, 0);
+  const errorCount = reportErrors.length + files.reduce((sum, file) => sum + file.errors.length, 0);
+  const report = { ok: errorCount === 0, command: 'trello sync', mode: 'dry-run', root, scanPaths, totals: { matchedFiles: files.length, plannedUpdates: files.filter((file) => file.syncStatus === 'planned').length, warnings: warningCount, errors: errorCount }, warnings: reportWarnings, errors: reportErrors, files };
+  return { report, exitCode: errorCount > 0 ? 1 : 0 };
+}
+
+function trustedCiWriteContext(env = process.env) {
+  const defaultBranch = env.GITHUB_DEFAULT_BRANCH || env.DOTDOTGOD_DEFAULT_BRANCH || env.GITHUB_EVENT_REPOSITORY_DEFAULT_BRANCH;
+  return env.GITHUB_ACTIONS === 'true' && env.GITHUB_EVENT_NAME === 'push' && Boolean(defaultBranch) && env.GITHUB_REF === `refs/heads/${defaultBranch}`;
+}
+
+async function runTrelloWrite(rootInput = '.', options = {}) {
+  const env = options.env ?? process.env;
+  const { report: dryRunReport } = planTrelloDryRun(rootInput, { ...options, mode: 'write', env });
+  const report = { ...dryRunReport, mode: 'write', customFieldName: dotdotgodCustomFieldName({ env, name: options.customFieldName }), files: dryRunReport.files.map((file) => ({ ...file, attachment: { status: 'not-run' }, customField: { status: 'not-run' }, finalStatus: file.syncStatus === 'blocked' ? 'blocked' : 'pending' })) };
+
+  if (!trustedCiWriteContext(env)) {
+    return { exitCode: 2, stderr: 'Trello write mode is only allowed from the trusted GitHub Actions default-branch push workflow. Fix: run dotdotgod trello sync <root> --dry-run locally or merge docs to the default branch so the workflow can write to Trello.', report };
+  }
+
+  if (report.files.length === 0) {
+    report.totals = { matchedFiles: 0, written: 0, unchanged: 0, blocked: 0, conflict: 0, apiFailed: 0, warnings: report.totals.warnings, errors: report.totals.errors };
+    report.ok = report.totals.errors === 0;
+    return { report, exitCode: report.ok ? 0 : 1 };
+  }
+
+  const credentials = options.credentials ?? resolveTrelloCredentials({ env });
+  if (!credentials.ok) return { exitCode: 2, stderr: credentials.error.message, report };
+
+  const client = options.trelloClient ?? createTrelloClient({ credentials: credentials.credentials, fetchImpl: options.fetch, baseUrl: options.trelloBaseUrl });
+
+  for (const file of report.files) {
+    if (file.syncStatus === 'blocked') {
+      file.finalStatus = 'blocked';
+      continue;
+    }
+    if (file.syncStatus === 'conflict') {
+      file.finalStatus = 'conflict';
+      continue;
+    }
+    let step = 'card';
+    try {
+      const card = await client.getCard(file.shortLink);
+      step = 'attachments';
+      const attachments = await client.listAttachments(file.shortLink);
+      if (attachments.some((attachment) => attachment?.url === file.githubUrl)) {
+        file.attachment.status = 'unchanged';
+      } else {
+        step = 'attachment-create';
+        await client.createAttachment(file.shortLink, file.githubUrl);
+        file.attachment.status = 'written';
+      }
+      step = 'custom-field-definition';
+      const fields = await client.listCustomFields(card.idBoard);
+      let field = fields.find((item) => item?.name === report.customFieldName && item?.type === 'text');
+      if (!field) field = await client.createCustomField(card.idBoard, { name: report.customFieldName, type: 'text' });
+      if (!field?.id) throw { code: 'TRELLO_CUSTOM_FIELD_INVALID', message: 'Trello custom field creation returned no field id. Fix: check board custom field permissions and retry.' };
+      const merged = mergeLinkedDocsCustomFieldValue(customFieldTextValue(card, field.id), file.linkedDocsData);
+      if (!merged.ok) {
+        file.customField.status = 'conflict';
+        file.errors.push(merged.error);
+        file.finalStatus = 'conflict';
+        continue;
+      }
+      file.customField.action = merged.action;
+      file.customField.preservedRepositoryEntries = merged.preservedRepositoryEntries ?? 0;
+      file.customField.name = report.customFieldName;
+      if (merged.status === 'unchanged') {
+        file.customField.status = 'unchanged';
+      } else {
+        step = 'custom-field-update';
+        await client.updateCardCustomFieldText(card.id, field.id, merged.text);
+        file.customField.status = 'written';
+      }
+      file.finalStatus = file.attachment.status === 'written' || file.customField.status === 'written' ? 'written' : 'unchanged';
+    } catch (error) {
+      const normalized = actionableError(error);
+      if (step === 'attachment-create') file.attachment.status = 'failed';
+      else if (step.startsWith('custom-field')) file.customField.status = 'failed';
+      file.finalStatus = 'api-failed';
+      file.errors.push(normalized);
+    }
+  }
+
+  const counts = { written: 0, unchanged: 0, blocked: 0, conflict: 0, apiFailed: 0 };
+  for (const file of report.files) {
+    if (file.finalStatus === 'written') counts.written += 1;
+    else if (file.finalStatus === 'unchanged') counts.unchanged += 1;
+    else if (file.finalStatus === 'blocked') counts.blocked += 1;
+    else if (file.finalStatus === 'conflict') counts.conflict += 1;
+    else if (file.finalStatus === 'api-failed') counts.apiFailed += 1;
+  }
+  const warningCount = report.warnings.length + report.files.reduce((sum, file) => sum + file.warnings.length, 0);
+  const errorCount = report.errors.length + report.files.reduce((sum, file) => sum + file.errors.length, 0);
+  report.totals = { matchedFiles: report.files.length, ...counts, warnings: warningCount, errors: errorCount };
+  report.ok = counts.blocked === 0 && counts.conflict === 0 && counts.apiFailed === 0 && errorCount === 0;
+  return { report, exitCode: report.ok ? 0 : 1 };
+}
+
+export function runTrelloSync(argv = [], options = {}) {
+  if (argv[0] !== 'sync') return { exitCode: 2, stderr: `Unknown Trello command: ${argv[0] ?? ''}`.trim() };
+  const args = argv.slice(1);
+  let root = '.';
+  let dryRun = false;
+  for (const arg of args) {
+    if (arg === '--dry-run') dryRun = true;
+    else if (arg.startsWith('-')) return { exitCode: 2, stderr: `Unknown option: ${arg}` };
+    else root = arg;
+  }
+  const resolvedRoot = resolve(root);
+  if (!existsSync(resolvedRoot) || !statSync(resolvedRoot).isDirectory()) return { exitCode: 2, stderr: `Project root not found: ${resolvedRoot}` };
+  if (dryRun) {
+    const { report, exitCode } = planTrelloDryRun(resolvedRoot, options);
+    return { exitCode, stdout: formatTrelloDryRunReport(report), report };
+  }
+  return runTrelloWrite(resolvedRoot, options).then((result) => ({ ...result, stdout: result.stdout ?? (result.report ? formatTrelloWriteReport(result.report) : '') }));
+}