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

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

@@ -0,0 +1,123 @@
+// search.mjs - Search Confluence with CQL.
+//
+// Usage:
+//   confluence search <CQL> [--max N] [--expand]
+//
+// Uses v1 endpoint: GET /wiki/rest/api/content/search?cql=...
+// --expand includes body.storage in results.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { formatTable, bold, dim } from '../format.mjs';
+
+const HELP = `confluence search - CQL search
+
+Usage:
+  confluence search <CQL> [--max N] [--expand]
+
+Arguments:
+  CQL             CQL query string (quote if it contains spaces)
+
+Options:
+  --max N         Maximum results to return (default: 25)
+  --expand        Include body.storage in results
+  --help, -h      Show this help
+
+CQL examples:
+  confluence search "text ~ 'api documentation'"
+  confluence search "space = DEV AND type = page"
+  confluence search "label = 'important' ORDER BY lastModified DESC"
+  confluence search "creator = currentUser() AND lastModified > now('-7d')"
+`;
+
+/**
+ * Run the search command.
+ *
+ * @param {string[]} argv  Remaining args after 'search'
+ * @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 cql = args._.join(' ');
+  if (!cql) {
+    logError('Usage: confluence search <CQL> [--max N] [--expand]');
+    return 1;
+  }
+
+  const maxResults = args.max ? parseInt(args.max, 10) : 25;
+  if (isNaN(maxResults) || maxResults < 1) {
+    logError('--max must be a positive integer');
+    return 1;
+  }
+
+  const expand = args.expand === true;
+
+  const client = deps.client || createClient();
+
+  try {
+    const params = {
+      cql,
+      limit: String(maxResults),
+    };
+    if (expand) {
+      params.expand = 'body.storage';
+    }
+
+    const results = [];
+    let count = 0;
+    for await (const item of client.paginateOffset('/wiki/rest/api/content/search', params, maxResults)) {
+      results.push(item);
+      count++;
+      if (count >= maxResults) break;
+    }
+
+    if (results.length === 0) {
+      log(dim('No results found.'));
+      return 0;
+    }
+
+    log(bold('Search results') + dim(` (${results.length})\n`));
+
+    const rows = results.map((item) => ({
+      id: item.id || '',
+      title: item.title || '',
+      type: item.type || '',
+      space: item._expandable?.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: 'type', label: 'Type', width: 10 },
+      { key: 'space', label: 'Space', width: 10 },
+      { key: 'modified', label: 'Modified', width: 12 },
+    ]));
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Search failed: ${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;
+  }
+}

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

@@ -0,0 +1,82 @@
+// spaces.mjs - List Confluence spaces.
+//
+// Usage:
+//   confluence spaces [--filter QUERY] [--status current|archived|all]
+//
+// Fetches spaces via v2 cursor pagination and renders as a table.
+// Default status: current.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { formatSpaceList, bold, dim } from '../format.mjs';
+
+const HELP = `confluence spaces - List Confluence spaces
+
+Usage:
+  confluence spaces [--filter QUERY] [--status current|archived|all]
+
+Options:
+  --filter QUERY          Case-insensitive filter on space name or key
+  --status STATUS         Filter by status: current (default), archived, all
+  --help, -h              Show this help
+`;
+
+/**
+ * Run the spaces command.
+ *
+ * @param {string[]} argv  Remaining args after 'spaces'
+ * @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 filter = args.filter ? args.filter.toLowerCase() : null;
+  const status = args.status || 'current';
+
+  const client = deps.client || createClient();
+
+  try {
+    const params = {};
+    if (status !== 'all') {
+      params.status = status;
+    }
+
+    const spaces = [];
+    for await (const space of client.paginateCursor('/wiki/api/v2/spaces', params)) {
+      spaces.push(space);
+    }
+
+    let filtered = spaces;
+    if (filter) {
+      filtered = spaces.filter((s) => {
+        const name = (s.name || '').toLowerCase();
+        const key = (s.key || '').toLowerCase();
+        return name.includes(filter) || key.includes(filter);
+      });
+    }
+
+    if (filtered.length === 0) {
+      log(dim(filter ? `No spaces matching "${filter}".` : 'No spaces found.'));
+      return 0;
+    }
+
+    log(bold('Spaces') + dim(` (${filtered.length}${filter ? ' matching' : ''})\n`));
+    log(formatSpaceList(filtered));
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to list spaces: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,155 @@
+// test.mjs - Live API contract smoke test.
+//
+// Hits key Confluence endpoints and validates response shapes. NO MUTATIONS.
+// Used to verify the API still behaves as expected after upgrades,
+// config changes, or permission adjustments.
+//
+// Exit 0 if all pass, 2 if any fail.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { bold, dim, green, red, yellow } from '../format.mjs';
+
+const HELP = `confluence test - Live API contract smoke test
+
+Usage:
+  confluence test
+
+Runs read-only checks against the Confluence API to validate response shapes
+and connectivity. No data is created, modified, or deleted.
+
+Options:
+  --help, -h  Show this help
+`;
+
+/**
+ * Run the test command.
+ *
+ * @param {string[]} argv  Remaining args after 'test'
+ * @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;
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    log(HELP);
+    return 0;
+  }
+
+  const client = deps.client || createClient();
+
+  log(bold('Confluence API Contract Tests\n'));
+
+  const results = [];
+
+  // ── Test 1: Auth check ───────────────────────────────────────────
+  results.push(await runTest(log, 'Auth (GET /wiki/rest/api/user/current)', async () => {
+    const { data } = await client.get('/wiki/rest/api/user/current');
+    assert(data.displayName, 'missing displayName');
+    assert(data.accountId || data.username, 'missing accountId or username');
+    return `user: ${data.displayName}`;
+  }));
+
+  // ── Test 2: Spaces (v2) ──────────────────────────────────────────
+  let firstSpaceKey = null;
+  results.push(await runTest(log, 'Spaces (GET /wiki/api/v2/spaces)', async () => {
+    const { data } = await client.get('/wiki/api/v2/spaces?limit=5');
+    assert(Array.isArray(data.results), 'results is not an array');
+    if (data.results.length > 0) {
+      firstSpaceKey = data.results[0].key;
+    }
+    return `${data.results.length} space(s)${firstSpaceKey ? `, first: ${firstSpaceKey}` : ''}`;
+  }));
+
+  // ── Test 3: Pages in space (v2) ──────────────────────────────────
+  let firstPageId = null;
+  results.push(await runTest(log, 'Pages in space (GET /wiki/api/v2/spaces/{id}/pages)', async () => {
+    if (!firstSpaceKey) {
+      return 'SKIP: no space found';
+    }
+    // Resolve space key to ID
+    const { data: spaceData } = await client.get(
+      `/wiki/api/v2/spaces?keys=${encodeURIComponent(firstSpaceKey)}&limit=1`
+    );
+    const spaceId = spaceData.results[0]?.id;
+    if (!spaceId) return 'SKIP: could not resolve space ID';
+
+    const { data } = await client.get(`/wiki/api/v2/spaces/${spaceId}/pages?limit=5`);
+    assert(Array.isArray(data.results), 'results is not an array');
+    if (data.results.length > 0) {
+      firstPageId = data.results[0].id;
+    }
+    return `${data.results.length} page(s)${firstPageId ? `, first ID: ${firstPageId}` : ''}`;
+  }));
+
+  // ── Test 4: Page fetch (v2) ──────────────────────────────────────
+  results.push(await runTest(log, 'Page fetch (GET /wiki/api/v2/pages/{id})', async () => {
+    if (!firstPageId) {
+      return 'SKIP: no page from listing to fetch';
+    }
+    const { data } = await client.get(
+      `/wiki/api/v2/pages/${firstPageId}?body-format=storage`
+    );
+    assert(data.title, 'missing title');
+    assert(data.id, 'missing id');
+    return `${data.id}: ${data.title}`;
+  }));
+
+  // ── Test 5: CQL search (v1) ─────────────────────────────────────
+  results.push(await runTest(log, 'CQL search (GET /wiki/rest/api/content/search)', async () => {
+    const { data } = await client.get(
+      `/wiki/rest/api/content/search?cql=${encodeURIComponent('type = page')}&limit=3`
+    );
+    assert(Array.isArray(data.results), 'results is not an array');
+    return `${data.results.length} result(s)`;
+  }));
+
+  // ── Summary ──────────────────────────────────────────────────────
+  const passed = results.filter((r) => r.passed).length;
+  const total = results.length;
+  const skipped = results.filter((r) => r.skipped).length;
+
+  log('');
+  const color = passed === total ? green : (passed >= total - 1 ? yellow : red);
+  log(color(bold(`${passed}/${total} passed`)) + (skipped ? dim(` (${skipped} skipped)`) : ''));
+
+  return passed === total ? 0 : 2;
+}
+
+/**
+ * Run a single test and print result.
+ *
+ * @param {Function} log       Output function
+ * @param {string} name        Test name
+ * @param {Function} testFn    Async function to execute
+ * @returns {Promise<{ passed: boolean, skipped: boolean }>}
+ */
+async function runTest(log, name, testFn) {
+  const start = Date.now();
+  try {
+    const detail = await testFn();
+    const ms = Date.now() - start;
+    const skipped = typeof detail === 'string' && detail.startsWith('SKIP:');
+    if (skipped) {
+      log(`  ${yellow('SKIP')}  ${name}  ${dim(`${ms}ms`)}  ${dim(detail.slice(6))}`);
+      return { passed: true, skipped: true };
+    }
+    log(`  ${green('PASS')}  ${name}  ${dim(`${ms}ms`)}  ${dim(detail || '')}`);
+    return { passed: true, skipped: false };
+  } catch (err) {
+    const ms = Date.now() - start;
+    const msg = err instanceof ConfluenceError ? err.message : (err.message || String(err));
+    log(`  ${red('FAIL')}  ${name}  ${dim(`${ms}ms`)}  ${red(msg)}`);
+    return { passed: false, skipped: false };
+  }
+}
+
+/**
+ * Simple assertion helper - throws on falsy value.
+ */
+function assert(value, message) {
+  if (!value) {
+    throw new Error(`Assertion failed: ${message}`);
+  }
+}

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

@@ -0,0 +1,103 @@
+// tree.mjs - Show page tree: ancestors (breadcrumb) + children.
+//
+// Usage:
+//   confluence tree <ID>
+//
+// Uses v1 endpoints for ancestor/child data.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { bold, dim, cyan } from '../format.mjs';
+
+const HELP = `confluence tree - Show page tree
+
+Usage:
+  confluence tree <ID>
+
+Arguments:
+  ID              Page ID (numeric)
+
+Options:
+  --help, -h      Show this help
+
+Shows the page's ancestors (breadcrumb path from root) and immediate children.
+
+Examples:
+  confluence tree 12345
+`;
+
+/**
+ * Run the tree command.
+ *
+ * @param {string[]} argv  Remaining args after 'tree'
+ * @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 tree <ID>');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    // Fetch the page with ancestors via v1
+    const { data: page } = await client.get(
+      `/wiki/rest/api/content/${encodeURIComponent(pageId)}?expand=ancestors,children.page`
+    );
+
+    const title = page.title || '(untitled)';
+
+    // Print ancestors (breadcrumb)
+    const ancestors = page.ancestors || [];
+    log(bold('Ancestors (breadcrumb):'));
+    if (ancestors.length === 0) {
+      log(dim('  (root page - no ancestors)'));
+    } else {
+      for (let i = 0; i < ancestors.length; i++) {
+        const indent = '  '.repeat(i + 1);
+        log(`${indent}${dim(ancestors[i].id)} ${ancestors[i].title}`);
+      }
+    }
+
+    // Current page
+    const indent = '  '.repeat(ancestors.length + 1);
+    log(`${indent}${cyan(bold(`${page.id} ${title}`))} ${dim('(current)')}`);
+
+    // Children
+    const children = page.children?.page?.results || [];
+    log('');
+    log(bold('Children:'));
+    if (children.length === 0) {
+      log(dim('  (no children)'));
+    } else {
+      const childIndent = '  '.repeat(ancestors.length + 2);
+      for (const child of children) {
+        log(`${childIndent}${dim(child.id)} ${child.title}`);
+      }
+      const size = page.children?.page?.size;
+      if (size && size > children.length) {
+        log(dim(`  ... and ${size - children.length} more`));
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to get page tree: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,134 @@
+// update.mjs - Update a Confluence page.
+//
+// Usage:
+//   confluence update <ID> [--from-file FILE.md] [-t TITLE] [-b BODY] [-m MESSAGE]
+//
+// Auto-fetches current version and increments.
+// If --from-file, reads markdown and converts to storage format.
+// -m sets version message.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { markdownToStorage, textToStorage } from '../storage.mjs';
+import { bold, green } from '../format.mjs';
+import { readFileSync } from 'node:fs';
+
+const HELP = `confluence update - Update a page
+
+Usage:
+  confluence update <ID> [--from-file FILE.md] [-t TITLE] [-b BODY] [-m MESSAGE]
+
+Arguments:
+  ID              Page ID (numeric)
+
+Options:
+  --from-file FILE  Read new markdown content from file
+  -t TITLE          New page title
+  -b BODY           New body text (converted to storage format)
+  -m MESSAGE        Version message (appears in page history)
+  --help, -h        Show this help
+
+The current page version is auto-fetched and incremented. At least one of
+--from-file, -t, or -b must be provided.
+
+Examples:
+  confluence update 12345 --from-file ./docs/api.md -m "Updated API docs"
+  confluence update 12345 -t "New Title"
+  confluence update 12345 -b "Updated body content." -m "Quick fix"
+`;
+
+/**
+ * Run the update command.
+ *
+ * @param {string[]} argv  Remaining args after 'update'
+ * @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 update <ID> [--from-file FILE.md] [-t TITLE] [-b BODY] [-m MSG]');
+    return 1;
+  }
+
+  const fromFile = args['from-file'] || null;
+  const title = args.t || args.title || null;
+  const bodyText = args.b || args.body || null;
+  const message = args.m || args.message || null;
+
+  if (!fromFile && !title && !bodyText) {
+    logError('No updates specified. Provide at least one of: --from-file, -t, -b');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    // Fetch current page to get version number and title
+    const { data: current } = await client.get(
+      `/wiki/api/v2/pages/${encodeURIComponent(pageId)}?body-format=storage`
+    );
+
+    const currentVersion = current.version?.number || 1;
+    const currentTitle = current.title || '';
+
+    // Build update payload
+    const payload = {
+      id: pageId,
+      status: 'current',
+      title: title || currentTitle,
+      version: {
+        number: currentVersion + 1,
+      },
+    };
+
+    if (message) {
+      payload.version.message = message;
+    }
+
+    // Build body if provided
+    if (fromFile) {
+      const readFn = deps.readFileSync || readFileSync;
+      const md = readFn(fromFile, 'utf-8');
+      payload.body = {
+        representation: 'storage',
+        value: markdownToStorage(md),
+      };
+    } else if (bodyText) {
+      payload.body = {
+        representation: 'storage',
+        value: textToStorage(bodyText),
+      };
+    } else {
+      // Title-only update - keep existing body
+      payload.body = {
+        representation: 'storage',
+        value: current.body?.storage?.value || '',
+      };
+    }
+
+    await client.put(`/wiki/api/v2/pages/${encodeURIComponent(pageId)}`, payload);
+
+    log(green(`${bold(payload.title)} updated to version ${currentVersion + 1}.`));
+    if (message) {
+      log(`  Message: ${message}`);
+    }
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to update page: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}