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

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

@@ -0,0 +1,351 @@
+// mirror-page.mjs - Mirror a Confluence page subtree (descendants) to local markdown.
+//
+// Usage:
+//   confluence mirror-page <PAGE_ID> [--target DIR] [--dry-run] [--no-reindex]
+//
+// Behaviour:
+//   Mirror semantics match mirror-folder. The only difference is the root
+//   node: instead of a folder, the subtree root is a Confluence page, and
+//   we walk via the page-children endpoint. The root page itself is NOT
+//   written - only its descendants are mirrored - matching mirror-folder
+//   which excludes the root folder. Same staging + atomic-swap + reindex
+//   pipeline.
+//
+// Why this exists alongside mirror-folder:
+//   Some Confluence sites keep a content set under a single top-level page
+//   rather than a folder. The v2 folder/direct-children endpoint can't reach page-rooted
+//   trees, so we need an explicit page-rooted entry point.
+
+import { mkdir, writeFile, rm, readdir, rename, stat, readFile } from 'node:fs/promises';
+import { basename, join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { storageToMarkdown } from '../storage.mjs';
+import {
+  composeMarkdown,
+  planTree,
+  splitForSwap,
+  pageUrl,
+  buildManifest,
+  serialiseManifest,
+} from '../mirror.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_REPO_ROOT = resolve(__dirname, '..', '..', '..', '..', '..', '..');
+
+const HELP = `confluence mirror-page - Mirror a Confluence page subtree to local markdown
+
+Usage:
+  confluence mirror-page <PAGE_ID> [options]
+
+Arguments:
+  PAGE_ID            Numeric Confluence page ID (root of the subtree).
+
+Options:
+  --target DIR       Target directory (default: operator/knowledge/mirror/).
+  --dry-run          Walk the tree and print the plan; write nothing.
+  --no-reindex       Skip the npm run reindex step after a successful mirror.
+  --help, -h         Show this help.
+
+Behaviour:
+  Walks the page's descendants (recursively), fetches each as markdown,
+  and mirrors the hierarchy into the target directory. The root page itself
+  is NOT included - only its descendants. README.md in the target is
+  preserved across runs; everything else is wiped and replaced.
+
+Examples:
+  confluence mirror-page 3543138535
+  confluence mirror-page 3543138535 --target /tmp/scratch --dry-run
+`;
+
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logProgress = deps.logProgress || ((msg) => console.error(msg));
+  const logError = deps.logError || console.error;
+  const { parseArgs } = await import('../cli.mjs');
+  const args = parseArgs(argv);
+
+  if (args.help || args.h) {
+    log(HELP);
+    return 0;
+  }
+
+  const pageId = args._[0];
+  if (!pageId) {
+    logError('Usage: confluence mirror-page <PAGE_ID> [--target DIR] [--dry-run]');
+    return 1;
+  }
+
+  const repoRoot = deps.repoRoot || process.env.DAVE_ROOT || DEFAULT_REPO_ROOT;
+  const target = args.target
+    ? resolve(args.target)
+    : join(repoRoot, 'operator', 'knowledge', 'mirror');
+  const dryRun = !!args['dry-run'];
+  const skipReindex = !!args['no-reindex'];
+
+  const client = deps.client || createClient();
+
+  let domain;
+  try {
+    domain = client.getCredentials().domain;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to load credentials: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+
+  try {
+    logProgress(`Walking Confluence page ${pageId}…`);
+    const rootMeta = await fetchPageMeta(client, pageId);
+    logProgress(`  Page: ${rootMeta.title} (space ${rootMeta.spaceId})`);
+
+    const rootChildren = await collectPageDescendants(client, pageId, logProgress);
+    const pageCount = countPages(rootChildren);
+    logProgress(`  Discovered ${pageCount} descendant page(s).`);
+
+    if (pageCount === 0) {
+      logError('No descendant pages found under page. Refusing to wipe target.');
+      return 2;
+    }
+
+    const plan = planTree(rootChildren);
+    if (dryRun) {
+      log(`Target: ${target}`);
+      log(`Root page: ${rootMeta.title} (${pageId})`);
+      log(`Plan (${plan.length} entries):`);
+      for (const entry of plan) {
+        log(`  [${entry.kind}] ${entry.relPath} - ${entry.node.title}`);
+      }
+      return 0;
+    }
+
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const stagingDir = join(target, `.mirror-tmp-${stamp}`);
+    logProgress(`Staging directory: ${stagingDir}`);
+
+    await mkdir(target, { recursive: true });
+    await mkdir(stagingDir, { recursive: true });
+
+    try {
+      const mirrorRunAt = new Date().toISOString();
+      const mirroredPageIds = [];
+      let writtenFiles = 0;
+      for (const entry of plan) {
+        const absPath = join(stagingDir, ...entry.relPath.split('/'));
+        if (entry.kind === 'dir') {
+          await mkdir(absPath, { recursive: true });
+          continue;
+        }
+        logProgress(`  Fetching page ${entry.node.id} - ${entry.node.title}`);
+        const pageBody = await fetchPageMarkdown(client, entry.node.id);
+        const md = composeMarkdown(
+          {
+            title: entry.node.title,
+            pageId: entry.node.id,
+            url: pageUrl(domain, entry.node.id, pageBody.webuiPath),
+            space: rootMeta.spaceId ? String(rootMeta.spaceId) : undefined,
+            version: pageBody.version,
+            updatedAt: pageBody.updatedAt,
+            breadcrumb: entry.breadcrumb,
+          },
+          pageBody.markdown,
+        );
+        await mkdir(dirname(absPath), { recursive: true });
+        await writeFile(absPath, md, 'utf-8');
+        mirroredPageIds.push(String(entry.node.id));
+        writtenFiles++;
+      }
+      logProgress(`  Wrote ${writtenFiles} file(s) to staging.`);
+
+      const mirrorToolVersion = await readToolVersion();
+      const manifest = buildManifest({
+        domainId: basename(target),
+        sourceFolderId: pageId,
+        sourceSpaceKey: rootMeta.spaceId ? String(rootMeta.spaceId) : undefined,
+        mirrorRunAt,
+        pageIds: mirroredPageIds,
+        mirrorToolVersion,
+      });
+      const manifestPath = join(stagingDir, 'manifest.json');
+      await writeFile(manifestPath, serialiseManifest(manifest), 'utf-8');
+      logProgress(`  Wrote manifest.json (${manifest.pageCount} page IDs).`);
+
+      logProgress('Swapping staged content into target…');
+      await swapIntoTarget(target, stagingDir);
+      logProgress('Swap complete.');
+    } finally {
+      await rm(stagingDir, { recursive: true, force: true }).catch(() => {});
+    }
+
+    if (!skipReindex) {
+      logProgress('Running npm run reindex…');
+      const rc = runReindex(repoRoot, logProgress);
+      if (rc !== 0) {
+        // Soft-fail (acceptance ruling C2, 2026-07-14): on the composed v2
+        // workspace there is no local `reindex` script - domains.json is
+        // estate-composed and refreshed by the librarian, not by this tool.
+        // A completed mirror is a success; a stale local index is a warning.
+        logError(`Reindex exited with code ${rc}. Mirror completed; domains.json refresh is estate-side on v2 (warning only).`);
+      }
+    }
+
+    logProgress(`Mirror complete: ${pageCount} page(s) written to ${target}.`);
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Mirror failed: ${err.message}`);
+      return err.exitCode;
+    }
+    logError(`Mirror failed: ${err.message || err}`);
+    return 2;
+  }
+}
+
+// ── API walkers ──────────────────────────────────────────────────────
+
+async function fetchPageMeta(client, pageId) {
+  const { data } = await client.get(`/wiki/api/v2/pages/${encodeURIComponent(pageId)}`);
+  return data;
+}
+
+async function fetchPageChildren(client, pageId) {
+  const results = [];
+  let cursor = null;
+  for (let i = 0; i < 200; i++) {
+    const query = new URLSearchParams({ limit: '100' });
+    if (cursor) query.set('cursor', cursor);
+    const path = `/wiki/api/v2/pages/${encodeURIComponent(pageId)}/children?${query.toString()}`;
+    const { data } = await client.get(path);
+    for (const item of data.results || []) results.push(item);
+    const nextPath = data._links?.next;
+    if (!nextPath) break;
+    const nextCursor = extractCursor(nextPath);
+    if (!nextCursor || nextCursor === cursor) break;
+    cursor = nextCursor;
+  }
+  return results;
+}
+
+function extractCursor(nextPath) {
+  try {
+    const match = nextPath.match(/[?&]cursor=([^&]+)/);
+    if (match) return decodeURIComponent(match[1]);
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+async function collectPageDescendants(client, pageId, logProgress) {
+  const children = await fetchPageChildren(client, pageId);
+  const nodes = [];
+  for (const child of children) {
+    if (logProgress) logProgress(`  ↳ page: ${child.title}`);
+    const sub = await collectPageDescendants(client, child.id, null);
+    nodes.push({
+      type: 'page',
+      id: String(child.id),
+      title: child.title || 'untitled',
+      children: sub,
+    });
+  }
+  return nodes;
+}
+
+function countPages(nodes) {
+  let n = 0;
+  for (const node of nodes) {
+    if (node.type === 'page') n++;
+    if (Array.isArray(node.children)) n += countPages(node.children);
+  }
+  return n;
+}
+
+// ── Page fetching ────────────────────────────────────────────────────
+
+async function fetchPageMarkdown(client, pageId) {
+  const { data } = await client.get(
+    `/wiki/api/v2/pages/${encodeURIComponent(pageId)}?body-format=storage`,
+  );
+  const storageBody = data.body?.storage?.value || '';
+  const markdown = storageToMarkdown(storageBody);
+  return {
+    markdown,
+    version: data.version?.number,
+    updatedAt: data.version?.createdAt,
+    webuiPath: data._links?.webui,
+  };
+}
+
+// ── Atomic swap ──────────────────────────────────────────────────────
+
+async function swapIntoTarget(target, stagingDir) {
+  const existing = await readdir(target);
+  const { toRemove } = splitForSwap(existing.filter((e) => !isStagingDir(e)));
+  for (const name of toRemove) {
+    await rm(join(target, name), { recursive: true, force: true });
+  }
+
+  const staged = await readdir(stagingDir);
+  for (const name of staged) {
+    const from = join(stagingDir, name);
+    const to = join(target, name);
+    try {
+      await stat(to);
+      continue;
+    } catch {
+      // safe to move
+    }
+    await rename(from, to);
+  }
+}
+
+function isStagingDir(name) {
+  return name.startsWith('.mirror-tmp-');
+}
+
+// ── Tool version ─────────────────────────────────────────────────────
+
+async function readToolVersion() {
+  try {
+    const pkgPath = resolve(__dirname, '..', '..', 'package.json');
+    const raw = await readFile(pkgPath, 'utf-8');
+    const pkg = JSON.parse(raw);
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+      return pkg.version;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Reindex ──────────────────────────────────────────────────────────
+
+function runReindex(repoRoot, logProgress) {
+  const result = spawnSync('npm', ['run', 'reindex'], {
+    cwd: repoRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  if (result.stdout) logProgress(result.stdout.trimEnd());
+  if (result.stderr) logProgress(result.stderr.trimEnd());
+  return result.status ?? 1;
+}
+
+// ── Re-exports for testing ───────────────────────────────────────────
+
+export const _test = {
+  extractCursor,
+  countPages,
+  swapIntoTarget,
+  isStagingDir,
+  readToolVersion,
+  fetchPageMeta,
+  fetchPageChildren,
+  collectPageDescendants,
+};

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

@@ -0,0 +1,127 @@
+// page.mjs - Get a single Confluence page.
+//
+// Usage:
+//   confluence page <ID> [--format md|storage|text] [--save FILE]
+//
+// Default format: md (converts storage to markdown).
+// Shows metadata: space, version, author, labels, modified date.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { storageToMarkdown, storageToText } from '../storage.mjs';
+import { formatPage, bold, dim, green } from '../format.mjs';
+import { writeFileSync } from 'node:fs';
+
+const HELP = `confluence page - Get page content
+
+Usage:
+  confluence page <ID> [--format md|storage|text] [--save FILE]
+
+Arguments:
+  ID              Page ID (numeric)
+
+Options:
+  --format FMT    Output format: md (default), storage, text
+  --save FILE     Save content to file
+  --help, -h      Show this help
+
+Examples:
+  confluence page 12345
+  confluence page 12345 --format storage
+  confluence page 12345 --format md --save output.md
+`;
+
+/**
+ * Run the page command.
+ *
+ * @param {string[]} argv  Remaining args after 'page'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+  const { parseArgs } = await import('../cli.mjs');
+  const args = parseArgs(argv);
+
+  if (args.help || args.h) {
+    log(HELP);
+    return 0;
+  }
+
+  const pageId = args._[0];
+  if (!pageId) {
+    logError('Usage: confluence page <ID> [--format md|storage|text] [--save FILE]');
+    return 1;
+  }
+
+  const format = args.format || 'md';
+  if (!['md', 'storage', 'text'].includes(format)) {
+    logError('--format must be one of: md, storage, text');
+    return 1;
+  }
+
+  const saveFile = args.save || null;
+
+  const client = deps.client || createClient();
+
+  try {
+    // Fetch page with body in storage format
+    const { data: page } = await client.get(
+      `/wiki/api/v2/pages/${encodeURIComponent(pageId)}?body-format=storage`
+    );
+
+    // Fetch labels
+    let labels = [];
+    try {
+      const { data: labelData } = await client.get(
+        `/wiki/api/v2/pages/${encodeURIComponent(pageId)}/labels`
+      );
+      labels = (labelData.results || []).map((l) => l.name || l.label || l.prefix + ':' + l.name);
+    } catch {
+      // Labels fetch may fail - non-critical
+    }
+
+    // Enrich page object for formatting
+    page._labels = labels;
+
+    // Print metadata
+    log(formatPage(page));
+    log('');
+
+    // Extract storage body
+    const storageBody = page.body?.storage?.value || '';
+
+    // Convert to requested format
+    let content;
+    switch (format) {
+      case 'storage':
+        content = storageBody;
+        break;
+      case 'text':
+        content = storageToText(storageBody);
+        break;
+      case 'md':
+      default:
+        content = storageToMarkdown(storageBody);
+        break;
+    }
+
+    // Save or print
+    if (saveFile) {
+      const writeFn = deps.writeFileSync || writeFileSync;
+      writeFn(saveFile, content, 'utf-8');
+      log(green(`Content saved to ${saveFile}`));
+    } else {
+      log(dim('--- Content ---'));
+      log(content);
+    }
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to get page: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,107 @@
+// pages.mjs - List pages in a Confluence space.
+//
+// Usage:
+//   confluence pages <SPACE_KEY> [--limit N]
+//
+// Resolves space key → space ID via API, then lists pages.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { formatPageList, bold, dim } from '../format.mjs';
+
+const HELP = `confluence pages - List pages in a space
+
+Usage:
+  confluence pages <SPACE_KEY> [--limit N]
+
+Arguments:
+  SPACE_KEY       Space key (e.g. DEV, DOCS)
+
+Options:
+  --limit N       Maximum pages to return (default: 25)
+  --help, -h      Show this help
+
+Examples:
+  confluence pages DEV
+  confluence pages DOCS --limit 50
+`;
+
+/**
+ * Resolve a space key to a space ID via the v2 API.
+ *
+ * @param {object} client       Confluence client
+ * @param {string} spaceKey     Space key (e.g. DEV)
+ * @returns {Promise<string>}   Space ID
+ */
+async function resolveSpaceId(client, spaceKey) {
+  const { data } = await client.get(
+    `/wiki/api/v2/spaces?keys=${encodeURIComponent(spaceKey)}&limit=1`
+  );
+  const results = data.results || [];
+  if (results.length === 0) {
+    throw new ConfluenceError(`Space not found: ${spaceKey}`, 2);
+  }
+  return results[0].id;
+}
+
+/**
+ * Run the pages command.
+ *
+ * @param {string[]} argv  Remaining args after 'pages'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+  const { parseArgs } = await import('../cli.mjs');
+  const args = parseArgs(argv);
+
+  if (args.help || args.h) {
+    log(HELP);
+    return 0;
+  }
+
+  const spaceKey = args._[0];
+  if (!spaceKey) {
+    logError('Usage: confluence pages <SPACE_KEY> [--limit N]');
+    return 1;
+  }
+
+  const limit = args.limit ? parseInt(args.limit, 10) : 25;
+  if (isNaN(limit) || limit < 1) {
+    logError('--limit must be a positive integer');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    const spaceId = await resolveSpaceId(client, spaceKey.toUpperCase());
+
+    const pages = [];
+    let count = 0;
+    for await (const page of client.paginateCursor(`/wiki/api/v2/spaces/${spaceId}/pages`, {
+      sort: '-modified-date',
+    })) {
+      pages.push(page);
+      count++;
+      if (count >= limit) break;
+    }
+
+    if (pages.length === 0) {
+      log(dim(`No pages found in space ${spaceKey}.`));
+      return 0;
+    }
+
+    log(bold(`Pages in ${spaceKey.toUpperCase()}`) + dim(` (${pages.length})\n`));
+    log(formatPageList(pages));
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to list pages: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,107 @@
+// recent.mjs - Recently modified Confluence pages.
+//
+// Usage:
+//   confluence recent [--space SPACE] [--days N]
+//
+// Uses CQL: lastModified > now("-Nd")
+// Default: 7 days.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { formatTable, bold, dim } from '../format.mjs';
+
+const HELP = `confluence recent - Recently modified pages
+
+Usage:
+  confluence recent [--space KEY] [--days N]
+
+Options:
+  --space KEY     Filter by space key
+  --days N        How many days back to look (default: 7)
+  --help, -h      Show this help
+
+Examples:
+  confluence recent
+  confluence recent --space DEV --days 3
+`;
+
+/**
+ * Run the recent command.
+ *
+ * @param {string[]} argv  Remaining args after 'recent'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+  const { parseArgs } = await import('../cli.mjs');
+  const args = parseArgs(argv);
+
+  if (args.help || args.h) {
+    log(HELP);
+    return 0;
+  }
+
+  const space = args.space || null;
+  const days = args.days ? parseInt(args.days, 10) : 7;
+
+  if (isNaN(days) || days < 1) {
+    logError('--days must be a positive integer');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    let cql = `type = page AND lastModified > now("-${days}d") ORDER BY lastModified DESC`;
+    if (space) {
+      cql = `type = page AND space = "${space.toUpperCase()}" AND lastModified > now("-${days}d") ORDER BY lastModified DESC`;
+    }
+
+    const results = [];
+    for await (const item of client.paginateOffset('/wiki/rest/api/content/search', {
+      cql,
+    }, 25)) {
+      results.push(item);
+      if (results.length >= 25) break;
+    }
+
+    if (results.length === 0) {
+      log(dim(`No pages modified in the last ${days} day(s).`));
+      return 0;
+    }
+
+    log(bold(`Recently modified pages`) + dim(` (last ${days} days)\n`));
+
+    const rows = results.map((item) => ({
+      id: item.id || '',
+      title: item.title || '',
+      space: item.space?.key || '',
+      modified: item.version?.when ? formatDate(item.version.when) : '',
+    }));
+
+    log(formatTable(rows, [
+      { key: 'id', label: 'ID', width: 12 },
+      { key: 'title', label: 'Title', width: 50 },
+      { key: 'space', label: 'Space', width: 10 },
+      { key: 'modified', label: 'Modified', width: 12 },
+    ]));
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to fetch recent pages: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}
+
+function formatDate(isoString) {
+  if (!isoString) return '';
+  try {
+    return new Date(isoString).toISOString().slice(0, 10);
+  } catch {
+    return isoString;
+  }
+}