@stravica-ai/digital-operator-pa 0.1.39 → 0.1.41

package/dist/engineering-pa-core-extensions-atlassian/src/confluence/format.mjs

@@ -0,0 +1,260 @@
+// format.mjs - Terminal output formatting for Confluence data.
+//
+// Provides table rendering, page/space/comment formatting, and
+// ANSI color helpers. Used by CLI commands and workspace API handlers.
+//
+// Zero external dependencies.
+
+// ── ANSI color helpers ───────────────────────────────────────────────
+
+const IS_TTY = process.stdout.isTTY;
+
+function ansi(code, text) {
+  if (!IS_TTY) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+export function bold(text) { return ansi('1', text); }
+export function dim(text) { return ansi('2', text); }
+export function red(text) { return ansi('31', text); }
+export function green(text) { return ansi('32', text); }
+export function yellow(text) { return ansi('33', text); }
+export function blue(text) { return ansi('34', text); }
+export function cyan(text) { return ansi('36', text); }
+
+// ── Status color mapping ─────────────────────────────────────────────
+
+const STATUS_COLORS = {
+  'current': green,
+  'archived': dim,
+  'draft': yellow,
+  'trashed': red,
+};
+
+function colorStatus(status) {
+  if (!status) return '';
+  const lower = status.toLowerCase();
+  const colorFn = STATUS_COLORS[lower] || ((s) => s);
+  return colorFn(status);
+}
+
+// ── Table formatting ─────────────────────────────────────────────────
+
+/**
+ * Render rows as an aligned text table.
+ *
+ * @param {Array<object>} rows       Array of data objects
+ * @param {Array<object>} columns    Column definitions: { key, label, width?, align? }
+ *   - key: property name on each row
+ *   - label: column header text
+ *   - width: max column width (optional, auto-calculated if omitted)
+ *   - align: 'left' (default) or 'right'
+ * @returns {string} Formatted table
+ */
+export function formatTable(rows, columns) {
+  if (!rows || rows.length === 0) return '';
+
+  // Calculate column widths
+  const colWidths = columns.map((col) => {
+    const headerLen = col.label.length;
+    const maxDataLen = rows.reduce((max, row) => {
+      const val = String(row[col.key] ?? '');
+      return Math.max(max, val.length);
+    }, 0);
+    const natural = Math.max(headerLen, maxDataLen);
+    return col.width ? Math.min(natural, col.width) : natural;
+  });
+
+  // Header
+  const header = columns.map((col, i) => {
+    return pad(col.label, colWidths[i], col.align || 'left');
+  }).join('  ');
+
+  // Separator
+  const sep = colWidths.map((w) => '-'.repeat(w)).join('  ');
+
+  // Rows
+  const body = rows.map((row) => {
+    return columns.map((col, i) => {
+      const val = String(row[col.key] ?? '');
+      const truncated = val.length > colWidths[i]
+        ? val.slice(0, colWidths[i] - 1) + '\u2026'
+        : val;
+      return pad(truncated, colWidths[i], col.align || 'left');
+    }).join('  ');
+  });
+
+  return [bold(header), sep, ...body].join('\n');
+}
+
+function pad(str, width, align) {
+  if (align === 'right') return str.padStart(width);
+  return str.padEnd(width);
+}
+
+// ── Page formatting ──────────────────────────────────────────────────
+
+/**
+ * Format a single Confluence page for terminal display.
+ *
+ * @param {object} page   Page object (from v2 API response)
+ * @returns {string}      Formatted output
+ */
+export function formatPage(page) {
+  if (!page) return '';
+
+  const lines = [];
+
+  // Title
+  lines.push(`${bold(page.title || '(untitled)')}`);
+  lines.push('');
+
+  // ID + Status
+  const parts = [];
+  if (page.id) parts.push(`ID: ${page.id}`);
+  if (page.status) parts.push(colorStatus(page.status));
+  if (parts.length > 0) lines.push(parts.join('  |  '));
+
+  // Space
+  if (page.spaceId) lines.push(`Space ID: ${page.spaceId}`);
+  if (page._space) lines.push(`Space: ${page._space}`);
+
+  // Version
+  if (page.version) {
+    const ver = typeof page.version === 'object' ? page.version.number : page.version;
+    lines.push(`Version: ${ver}`);
+    if (page.version.message) {
+      lines.push(`Version message: ${page.version.message}`);
+    }
+  }
+
+  // Author
+  if (page.authorId) lines.push(`Author: ${page.authorId}`);
+  if (page._author) lines.push(`Author: ${page._author}`);
+
+  // Labels
+  if (page._labels && page._labels.length > 0) {
+    lines.push(`Labels: ${page._labels.join(', ')}`);
+  }
+
+  // Dates
+  if (page.createdAt) lines.push(`Created: ${formatDate(page.createdAt)}`);
+  if (page.version?.createdAt) lines.push(`Modified: ${formatDate(page.version.createdAt)}`);
+
+  // URL
+  if (page._links?.webui) {
+    lines.push(`URL: ${page._links.webui}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a list of pages as a compact table.
+ *
+ * @param {Array<object>} pages  Array of Confluence pages
+ * @returns {string}             Formatted table
+ */
+export function formatPageList(pages) {
+  if (!pages || pages.length === 0) return dim('No pages found.');
+
+  const rows = pages.map((page) => ({
+    id: page.id || '',
+    title: page.title || '',
+    status: page.status || '',
+    modified: page.version?.createdAt ? formatDate(page.version.createdAt) : '',
+  }));
+
+  return formatTable(rows, [
+    { key: 'id', label: 'ID', width: 12 },
+    { key: 'title', label: 'Title', width: 50 },
+    { key: 'status', label: 'Status', width: 10 },
+    { key: 'modified', label: 'Modified', width: 12 },
+  ]);
+}
+
+// ── Space formatting ─────────────────────────────────────────────────
+
+/**
+ * Format a single Confluence space for terminal display.
+ *
+ * @param {object} space   Space object
+ * @returns {string}       Formatted output
+ */
+export function formatSpace(space) {
+  if (!space) return '';
+
+  const lines = [];
+  lines.push(`${bold(space.key || '')}  ${space.name || ''}`);
+  if (space.type) lines.push(`Type: ${space.type}`);
+  if (space.status) lines.push(`Status: ${colorStatus(space.status)}`);
+  if (space.description?.plain?.value) {
+    lines.push(`\n${space.description.plain.value}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a list of spaces as a compact table.
+ *
+ * @param {Array<object>} spaces  Array of Confluence spaces
+ * @returns {string}              Formatted table
+ */
+export function formatSpaceList(spaces) {
+  if (!spaces || spaces.length === 0) return dim('No spaces found.');
+
+  const rows = spaces.map((space) => ({
+    key: space.key || '',
+    name: space.name || '',
+    type: space.type || '',
+    status: space.status || '',
+  }));
+
+  return formatTable(rows, [
+    { key: 'key', label: 'Key', width: 12 },
+    { key: 'name', label: 'Name', width: 40 },
+    { key: 'type', label: 'Type', width: 12 },
+    { key: 'status', label: 'Status', width: 10 },
+  ]);
+}
+
+// ── Comment formatting ───────────────────────────────────────────────
+
+/**
+ * Format a single Confluence comment for terminal display.
+ *
+ * @param {object} comment  Comment object
+ * @returns {string}        Formatted output
+ */
+export function formatComment(comment) {
+  if (!comment) return '';
+
+  const lines = [];
+
+  // v1 comment shape
+  const author = comment.author?.displayName || comment.authorId || 'Unknown';
+  const created = comment.created || comment.createdAt || '';
+  const version = comment.version?.number || '';
+
+  lines.push(`${bold(author)}  ${dim(formatDate(created))}${version ? dim(` (v${version})`) : ''}`);
+
+  // Body - caller should render storage to text/md before passing
+  if (comment._bodyText) {
+    lines.push(comment._bodyText);
+  }
+
+  return lines.join('\n');
+}
+
+// ── Date formatting ──────────────────────────────────────────────────
+
+function formatDate(isoString) {
+  if (!isoString) return '';
+  try {
+    const d = new Date(isoString);
+    return d.toISOString().slice(0, 10);
+  } catch {
+    return isoString;
+  }
+}

package/dist/engineering-pa-core-extensions-atlassian/src/confluence/mirror.mjs

@@ -0,0 +1,353 @@
+// mirror.mjs - Pure helpers for the folder mirror command.
+//
+// All functions here are pure (no I/O, no network) so they can be unit-tested
+// in isolation. The orchestration that actually walks the Confluence API and
+// writes to disk lives in commands/mirror-folder.mjs.
+//
+// Responsibilities:
+//   - Sanitise Confluence page/folder titles into filesystem-safe slugs.
+//   - Build a markdown page body with a metadata header block.
+//   - Plan a mirror tree (flatten a nested folder/page structure into a list
+//     of files-to-write with absolute-relative paths).
+//   - Compute the atomic-swap plan (what to preserve, what to discard).
+//
+// Zero external dependencies.
+
+// ── Title sanitisation ───────────────────────────────────────────────
+
+/**
+ * Sanitise a Confluence title into a filesystem-safe slug.
+ *
+ * Rules:
+ *   - lowercase
+ *   - strip diacritics
+ *   - replace spaces and path separators with hyphens
+ *   - drop characters outside [a-z0-9._-]
+ *   - collapse runs of hyphens
+ *   - trim leading/trailing hyphens, dots, and underscores
+ *   - cap length at 120 chars (leaves room for .md and numeric disambiguators)
+ *   - fall back to a stable placeholder if the result is empty
+ *
+ * @param {string} title
+ * @returns {string}
+ */
+export function sanitiseTitle(title) {
+  if (typeof title !== 'string' || title.length === 0) return 'untitled';
+
+  // Normalise & strip diacritics (NFD → drop combining marks).
+  let s = title.normalize('NFKD').replace(/[̀-ͯ]/g, '');
+  s = s.toLowerCase();
+
+  // Replace path separators and whitespace with hyphens.
+  s = s.replace(/[\\/]+/g, '-');
+  s = s.replace(/\s+/g, '-');
+
+  // Drop anything that isn't alphanumeric, hyphen, dot, or underscore.
+  s = s.replace(/[^a-z0-9._-]/g, '');
+
+  // Collapse repeated hyphens.
+  s = s.replace(/-{2,}/g, '-');
+
+  // Trim leading/trailing junk.
+  s = s.replace(/^[-._]+|[-._]+$/g, '');
+
+  if (s.length === 0) return 'untitled';
+  if (s.length > 120) s = s.slice(0, 120).replace(/-+$/, '');
+  if (s.length === 0) return 'untitled';
+
+  return s;
+}
+
+/**
+ * Disambiguate a slug within a directory by appending -<pageId> if a
+ * collision already exists. Mutates the provided usedSet so repeated
+ * calls stay consistent.
+ *
+ * @param {string} baseSlug
+ * @param {string|number} pageId        Used as the disambiguator
+ * @param {Set<string>} usedSet         Slugs already claimed in this directory
+ * @returns {string}                    A slug not present in usedSet
+ */
+export function disambiguate(baseSlug, pageId, usedSet) {
+  if (!usedSet.has(baseSlug)) {
+    usedSet.add(baseSlug);
+    return baseSlug;
+  }
+  const withId = `${baseSlug}-${pageId}`;
+  if (!usedSet.has(withId)) {
+    usedSet.add(withId);
+    return withId;
+  }
+  // Fallback - append a counter.
+  let n = 2;
+  while (usedSet.has(`${withId}-${n}`)) n++;
+  const final = `${withId}-${n}`;
+  usedSet.add(final);
+  return final;
+}
+
+// ── Metadata header ─────────────────────────────────────────────────
+
+/**
+ * Build the frontmatter-like metadata header block for a mirrored page.
+ * Uses YAML frontmatter fenced with --- so it's compatible with standard
+ * markdown tools and with our retrieval index-builder.
+ *
+ * Note: per-run timestamps deliberately do NOT live here - every nightly
+ * mirror would otherwise rewrite every page's frontmatter even when no
+ * Confluence content changed. The run-level timestamp is captured once,
+ * centrally, in the domain-root manifest (see buildManifest).
+ *
+ * @param {object} meta
+ * @param {string} meta.title
+ * @param {string} meta.pageId
+ * @param {string} meta.url
+ * @param {string} [meta.updatedAt]    ISO-8601 timestamp of Confluence's last edit
+ * @param {string} [meta.space]
+ * @param {string} [meta.version]
+ * @param {string[]} [meta.breadcrumb] Ordered ancestor titles (nearest last)
+ * @returns {string}
+ */
+export function buildMetadataHeader(meta) {
+  const lines = ['---'];
+  lines.push(`title: ${yamlString(meta.title || '')}`);
+  lines.push(`confluencePageId: ${yamlString(String(meta.pageId || ''))}`);
+  lines.push(`confluenceUrl: ${yamlString(meta.url || '')}`);
+  if (meta.space) lines.push(`confluenceSpace: ${yamlString(meta.space)}`);
+  if (meta.version != null) lines.push(`confluenceVersion: ${yamlString(String(meta.version))}`);
+  if (meta.updatedAt) lines.push(`confluenceUpdatedAt: ${yamlString(meta.updatedAt)}`);
+  if (Array.isArray(meta.breadcrumb) && meta.breadcrumb.length > 0) {
+    lines.push('confluenceBreadcrumb:');
+    for (const crumb of meta.breadcrumb) {
+      lines.push(`  - ${yamlString(crumb)}`);
+    }
+  }
+  lines.push('mirrorSource: confluence');
+  lines.push('readOnly: true');
+  lines.push('---');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Quote a YAML scalar value. Always double-quote and escape backslashes and
+ * double quotes - simplest safe path for arbitrary Confluence titles.
+ * @param {string} v
+ * @returns {string}
+ */
+function yamlString(v) {
+  const s = String(v == null ? '' : v);
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Compose the full markdown body for a mirrored page: frontmatter header
+ * + H1 title + a blank line + the converted markdown content.
+ *
+ * @param {object} meta        Passed to buildMetadataHeader
+ * @param {string} markdown    Already-converted markdown body (may be '')
+ * @returns {string}
+ */
+export function composeMarkdown(meta, markdown) {
+  const header = buildMetadataHeader(meta);
+  const title = (meta.title || 'Untitled').trim();
+  const body = (markdown || '').trim();
+  return `${header}# ${title}\n\n${body}\n`;
+}
+
+// ── Run manifest ────────────────────────────────────────────────────
+
+/**
+ * Build the run-level manifest object that describes a single mirror run.
+ * Written once per run as `manifest.json` at the domain root. Holds the
+ * data that previously lived in every page's `mirrorFetchedAt` field plus
+ * a sorted list of page IDs so a future drift-detection feature can
+ * compare runs without diffing every file.
+ *
+ * Pure: takes inputs, returns a plain object - the caller serialises and
+ * writes it.
+ *
+ * Page IDs are sorted ascending as strings (numeric Confluence IDs sort
+ * lexicographically the same as numerically when zero-padding is absent
+ * across same-length IDs; for safety we coerce to numeric where possible
+ * and fall back to lexical for non-numeric IDs).
+ *
+ * @param {object} input
+ * @param {string} input.domainId          Logical domain id (e.g. 'engineering-standards')
+ * @param {string|number} input.sourceFolderId  Confluence folder ID being mirrored
+ * @param {string} [input.sourceSpaceKey]  Confluence space key (or numeric space id)
+ * @param {string} input.mirrorRunAt       ISO-8601 timestamp of this run
+ * @param {Array<string|number>} input.pageIds  All page IDs included in the mirror
+ * @param {string} [input.mirrorToolVersion]    Version of the confluence tool
+ * @returns {object}
+ */
+export function buildManifest(input) {
+  const pageIds = Array.isArray(input.pageIds)
+    ? input.pageIds.map((id) => String(id))
+    : [];
+  const sortedPageIds = pageIds.slice().sort((a, b) => {
+    const an = Number(a);
+    const bn = Number(b);
+    if (Number.isFinite(an) && Number.isFinite(bn) && an !== bn) {
+      return an - bn;
+    }
+    if (a < b) return -1;
+    if (a > b) return 1;
+    return 0;
+  });
+
+  const manifest = {
+    domainId: String(input.domainId || ''),
+    sourceFolderId: String(input.sourceFolderId || ''),
+  };
+  if (input.sourceSpaceKey != null && input.sourceSpaceKey !== '') {
+    manifest.sourceSpaceKey = String(input.sourceSpaceKey);
+  }
+  manifest.mirrorRunAt = String(input.mirrorRunAt || '');
+  if (input.mirrorToolVersion) {
+    manifest.mirrorToolVersion = String(input.mirrorToolVersion);
+  }
+  manifest.pageCount = sortedPageIds.length;
+  manifest.pageIds = sortedPageIds;
+  return manifest;
+}
+
+/**
+ * Serialise a manifest object to its on-disk JSON form.
+ * 2-space indent, trailing newline. camelCase keys (caller's responsibility).
+ *
+ * @param {object} manifest
+ * @returns {string}
+ */
+export function serialiseManifest(manifest) {
+  return JSON.stringify(manifest, null, 2) + '\n';
+}
+
+// ── Tree planning ───────────────────────────────────────────────────
+
+/**
+ * Flatten a nested tree of folders and pages into a flat list of write
+ * operations. Each operation is `{ relPath, kind, node }` where `relPath`
+ * is a relative filesystem path (POSIX-style, using '/') rooted at the
+ * mirror target directory.
+ *
+ * Tree node shape:
+ *   {
+ *     type: 'folder' | 'page',
+ *     id: string,
+ *     title: string,
+ *     children: TreeNode[]   // for folder nodes and pages that have sub-pages
+ *   }
+ *
+ * Folders become directories; their children are nested under the directory.
+ * Pages become .md files. Pages that themselves have sub-pages become a
+ * <slug>/ directory containing index.md plus the child pages.
+ *
+ * @param {object[]} rootChildren   Top-level children of the root folder
+ * @returns {Array<{relPath: string, kind: 'file'|'dir', node: object, breadcrumb: string[]}>}
+ */
+export function planTree(rootChildren) {
+  const plan = [];
+  walk(rootChildren || [], '', [], plan);
+  return plan;
+}
+
+function walk(nodes, parentRel, parentBreadcrumb, plan) {
+  const usedSlugs = new Set();
+  for (const node of nodes) {
+    const slug = disambiguate(sanitiseTitle(node.title || 'untitled'), node.id, usedSlugs);
+    const breadcrumb = [...parentBreadcrumb, node.title || ''];
+
+    if (node.type === 'folder') {
+      const relPath = joinRel(parentRel, slug);
+      plan.push({ relPath, kind: 'dir', node, breadcrumb });
+      if (Array.isArray(node.children) && node.children.length > 0) {
+        walk(node.children, relPath, breadcrumb, plan);
+      }
+    } else if (node.type === 'page') {
+      const hasChildren = Array.isArray(node.children) && node.children.length > 0;
+      if (hasChildren) {
+        // Page becomes a directory; its content lives in index.md.
+        const dirRel = joinRel(parentRel, slug);
+        const indexRel = joinRel(dirRel, 'index.md');
+        plan.push({ relPath: dirRel, kind: 'dir', node, breadcrumb });
+        plan.push({ relPath: indexRel, kind: 'file', node, breadcrumb });
+        walk(node.children, dirRel, breadcrumb, plan);
+      } else {
+        const relPath = joinRel(parentRel, `${slug}.md`);
+        plan.push({ relPath, kind: 'file', node, breadcrumb });
+      }
+    }
+    // Other types (attachment, comment, etc) are ignored.
+  }
+}
+
+function joinRel(parent, child) {
+  if (!parent) return child;
+  return `${parent}/${child}`;
+}
+
+// ── Atomic-swap planning ────────────────────────────────────────────
+
+/**
+ * Compute the atomic-swap plan.
+ *
+ * After a successful mirror we need to:
+ *   1. Preserve the README.md (it documents the domain).
+ *   2. Remove every other file/dir currently under the target.
+ *   3. Move the staged mirror contents into place.
+ *
+ * This helper just returns the list of entries to preserve. Call sites
+ * decide how to apply it. Keeping the policy in a named function makes
+ * it trivial to unit-test and to change in one place.
+ *
+ * @returns {string[]}   Entry names (not paths) to preserve across a swap.
+ */
+export function preservedEntries() {
+  return ['README.md'];
+}
+
+/**
+ * Given an existing directory listing and the preservation set, split the
+ * listing into { toRemove, toKeep }. Input is a list of entry names (not
+ * paths). Purely lexical.
+ *
+ * @param {string[]} entries
+ * @returns {{ toRemove: string[], toKeep: string[] }}
+ */
+export function splitForSwap(entries) {
+  const preserve = new Set(preservedEntries());
+  const toRemove = [];
+  const toKeep = [];
+  for (const name of entries) {
+    // Always keep dotfiles - if a user or tool ever adds a .git or similar
+    // config to the directory, we don't clobber it.
+    if (name.startsWith('.')) {
+      toKeep.push(name);
+      continue;
+    }
+    if (preserve.has(name)) {
+      toKeep.push(name);
+    } else {
+      toRemove.push(name);
+    }
+  }
+  return { toRemove, toKeep };
+}
+
+// ── URL builder ─────────────────────────────────────────────────────
+
+/**
+ * Build the canonical web URL for a Confluence page.
+ * @param {string} domain     e.g. 'yoursite'
+ * @param {string|number} pageId
+ * @param {string} [webuiPath]  Optional _links.webui from v2 payload
+ * @returns {string}
+ */
+export function pageUrl(domain, pageId, webuiPath) {
+  const base = `https://${domain}.atlassian.net`;
+  if (webuiPath && typeof webuiPath === 'string') {
+    return `${base}/wiki${webuiPath.startsWith('/') ? '' : '/'}${webuiPath}`;
+  }
+  return `${base}/wiki/pages/viewpage.action?pageId=${encodeURIComponent(pageId)}`;
+}