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

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

@@ -0,0 +1,165 @@
+// cli.mjs - Confluence CLI command router.
+//
+// Routes subcommands to handler modules. Handles help text, unknown commands,
+// and maps ConfluenceError to process exit codes.
+//
+// Exit codes:
+//   0 - success
+//   1 - usage error (bad args, unknown command)
+//   2 - API/logical error (page not found, auth failed)
+//   3 - transport/IO failure (network error, vault unavailable)
+
+import { ConfluenceError } from './client.mjs';
+
+// ── Help text ────────────────────────────────────────────────────────
+
+const HELP = `confluence - Confluence CLI for your Atlassian site
+
+Usage:
+  confluence <command> [options]
+
+Commands:
+  auth                                Verify credentials and show current user
+  spaces [--filter Q] [--status S]    List spaces (default: current)
+  pages <SPACE_KEY> [--limit N]       List pages in a space
+  page <ID> [--format md|storage|text] [--save FILE]
+                                      Get page content
+  search <CQL> [--max N] [--expand]   CQL search
+  create -s SPACE -t TITLE [--from-file FILE.md] [-b BODY] [--parent ID]
+                                      Create a page
+  update <ID> [--from-file FILE.md] [-t TITLE] [-b BODY] [-m MSG]
+                                      Update a page
+  comment <ID> [TEXT] [--list]        Add or list comments
+  label <ID> <LABEL...> [--remove]    Add or remove labels
+  tree <ID>                           Show page tree (ancestors + children)
+  recent [--space KEY] [--days N]     Recently modified pages
+  mine [--days N]                     Current user's pages
+  mirror-folder <FOLDER_ID> [--target DIR] [--dry-run] [--no-reindex]
+                                      Mirror a folder subtree to local markdown
+  mirror-page <PAGE_ID> [--target DIR] [--dry-run] [--no-reindex]
+                                      Mirror a page subtree (descendants) to local markdown
+  test                                Live API smoke test
+
+Run 'confluence <command> --help' for command-specific help.
+`;
+
+// ── Arg parser ───────────────────────────────────────────────────────
+
+/**
+ * Parse argv into flags and positional args.
+ * Handles --flag value, -f value, and boolean flags.
+ *
+ * @param {string[]} argv  Arguments after the command name
+ * @returns {{ _: string[], [key: string]: string|boolean }}
+ */
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--') {
+      // Everything after -- is positional
+      args._.push(...argv.slice(i + 1));
+      break;
+    }
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      // Boolean flag if next arg is also a flag or end of args
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('-')) {
+        args[key] = true;
+      } else {
+        args[key] = argv[++i];
+      }
+    } else if (argv[i].startsWith('-') && argv[i].length === 2) {
+      const key = argv[i].slice(1);
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('-')) {
+        args[key] = true;
+      } else {
+        args[key] = argv[++i];
+      }
+    } else {
+      args._.push(argv[i]);
+    }
+  }
+  return args;
+}
+
+// ── Command loading ──────────────────────────────────────────────────
+
+const COMMANDS = {
+  auth: () => import('./commands/auth.mjs'),
+  spaces: () => import('./commands/spaces.mjs'),
+  pages: () => import('./commands/pages.mjs'),
+  page: () => import('./commands/page.mjs'),
+  search: () => import('./commands/search.mjs'),
+  create: () => import('./commands/create.mjs'),
+  update: () => import('./commands/update.mjs'),
+  comment: () => import('./commands/comment.mjs'),
+  label: () => import('./commands/label.mjs'),
+  tree: () => import('./commands/tree.mjs'),
+  recent: () => import('./commands/recent.mjs'),
+  mine: () => import('./commands/mine.mjs'),
+  'mirror-folder': () => import('./commands/mirror-folder.mjs'),
+  'mirror-page': () => import('./commands/mirror-page.mjs'),
+  test: () => import('./commands/test.mjs'),
+};
+
+// ── Router ───────────────────────────────────────────────────────────
+
+/**
+ * Run the CLI router.
+ *
+ * @param {string[]} argv    process.argv.slice(2)
+ * @param {object} [deps]    Dependency overrides for testing
+ * @param {object} [deps.client]  Confluence client instance
+ * @param {Function} [deps.log]   Output function (default: console.log)
+ * @param {Function} [deps.logError]  Error output (default: console.error)
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv, deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+
+  const cmd = argv[0];
+
+  // No command or help
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    log(HELP);
+    return 0;
+  }
+
+  // Unknown command
+  const loader = COMMANDS[cmd];
+  if (!loader) {
+    logError(`Unknown command: ${cmd}\n`);
+    log(HELP);
+    return 1;
+  }
+
+  // Load and run command
+  const mod = await loader();
+  const rest = argv.slice(1);
+  return mod.run(rest, deps);
+}
+
+/**
+ * CLI entry point. Uses `process.exitCode` (not `process.exit`) so pending
+ * piped-stdout writes drain before Node exits - exit-before-drain
+ * truncates at the first pipe-buffer boundary (~8KB on macOS). Same class
+ * as w-2026-08-31-dave-039.
+ *
+ * @param {string[]} argv  process.argv.slice(2)
+ */
+export async function main(argv) {
+  try {
+    const code = await run(argv);
+    process.exitCode = code ?? 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      console.error(`confluence: ${err.message}`);
+      process.exitCode = err.exitCode;
+      return;
+    }
+    // Unexpected error
+    console.error(`confluence: ${err.message || err}`);
+    process.exitCode = 3;
+  }
+}

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

@@ -0,0 +1,294 @@
+// client.mjs - Confluence Cloud REST API client.
+//
+// Handles credential loading (vault), auth, request building, error handling,
+// rate-limit retry, and two pagination models:
+//   - Offset-based (v1 endpoints: CQL search, labels, comments, page tree)
+//   - Cursor-based (v2 endpoints: page CRUD, reading labels/comments/attachments)
+//
+// Reuses JIRA_* vault secrets - same Atlassian site.
+// Zero external dependencies - uses Node.js built-in fetch() and child_process.
+
+import { loadAtlassianCredentials } from '../common/secrets.mjs';
+
+// ---- Exit-code-aware error ----------------------------------------------
+
+export class ConfluenceError extends Error {
+  constructor(message, exitCode = 2) {
+    super(message);
+    this.name = 'ConfluenceError';
+    this.exitCode = exitCode;
+  }
+}
+
+// ---- Credential loading -------------------------------------------------
+
+/**
+ * Load the three Atlassian credentials from env vars first, else the
+ * platform `secrets` bin. Reuses JIRA_* keys for both Jira and Confluence
+ * because they target the same Atlassian site.
+ * @param {object} opts  { secretsGet } override for testing
+ * @returns {{ domain: string, email: string, apiToken: string }}
+ */
+export function getCredentials(opts = {}) {
+  try {
+    return loadAtlassianCredentials(opts);
+  } catch (err) {
+    throw new ConfluenceError(err.message, 3);
+  }
+}
+
+// ── Client factory ───────────────────────────────────────────────────
+
+/**
+ * Create a Confluence API client.
+ *
+ * @param {object} [options]
+ * @param {string} [options.domain]       Atlassian subdomain (skips vault read)
+ * @param {string} [options.email]        Auth email (skips vault read)
+ * @param {string} [options.apiToken]     API token (skips vault read)
+ * @param {string} [options.secretsBin]   Path to secrets CLI (testing)
+ * @param {Function} [options.fetchFn]    fetch() override (testing)
+ * @param {number} [options.maxRetries]   Max retries on 429/5xx (default: 1)
+ * @returns {object} Client with request, get, post, put, del, paginateOffset, paginateCursor, getCredentials
+ */
+export function createClient(options = {}) {
+  const fetchFn = options.fetchFn ?? globalThis.fetch;
+  const maxRetries = options.maxRetries ?? 1;
+
+  // Credentials are loaded lazily on first use, unless explicitly provided
+  let _creds = null;
+
+  function creds() {
+    if (_creds) return _creds;
+    if (options.domain && options.email && options.apiToken) {
+      _creds = {
+        domain: options.domain,
+        email: options.email,
+        apiToken: options.apiToken,
+      };
+    } else {
+      _creds = getCredentials({ secretsBin: options.secretsBin });
+    }
+    return _creds;
+  }
+
+  function baseUrl() {
+    return `https://${creds().domain}.atlassian.net`;
+  }
+
+  function authHeader() {
+    const { email, apiToken } = creds();
+    return `Basic ${Buffer.from(`${email}:${apiToken}`).toString('base64')}`;
+  }
+
+  // ── Core request ─────────────────────────────────────────────────
+
+  /**
+   * Make a Confluence API request.
+   *
+   * @param {string} method     HTTP method
+   * @param {string} path       URL path (e.g. /wiki/api/v2/pages/123)
+   * @param {object} [body]     Request body (will be JSON-stringified)
+   * @param {object} [headers]  Extra headers to merge
+   * @returns {Promise<{ status: number, data: any, headers: Headers }>}
+   */
+  async function request(method, path, body, headers = {}) {
+    const url = `${baseUrl()}${path}`;
+    const reqHeaders = {
+      'Authorization': authHeader(),
+      'Accept': 'application/json',
+      ...headers,
+    };
+    if (body !== undefined && body !== null) {
+      reqHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOpts = {
+      method,
+      headers: reqHeaders,
+    };
+    if (body !== undefined && body !== null) {
+      fetchOpts.body = JSON.stringify(body);
+    }
+
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      let res;
+      try {
+        res = await fetchFn(url, fetchOpts);
+      } catch (err) {
+        lastError = new ConfluenceError(`Network error: ${err.message}`, 3);
+        continue;
+      }
+
+      // Rate limited - wait and retry
+      if (res.status === 429) {
+        const retryAfter = parseInt(res.headers.get('Retry-After') || '5', 10);
+        if (attempt < maxRetries) {
+          await sleep(retryAfter * 1000);
+          continue;
+        }
+        throw new ConfluenceError(`Rate limited (429). Retry-After: ${retryAfter}s`, 2);
+      }
+
+      // 5xx - retry if attempts remain, otherwise throw immediately
+      if (res.status >= 500) {
+        if (attempt < maxRetries) {
+          lastError = new ConfluenceError(`Server error: ${res.status}`, 2);
+          await sleep(1000);
+          continue;
+        }
+        throw new ConfluenceError(`Server error: ${res.status}`, 2);
+      }
+
+      // Parse response
+      let data = null;
+      if (res.status !== 204) {
+        const contentType = res.headers.get('Content-Type') || '';
+        if (contentType.includes('application/json')) {
+          data = await res.json();
+        } else {
+          const text = await res.text();
+          if (text) data = text;
+        }
+      }
+
+      // 4xx errors
+      if (res.status >= 400) {
+        const msgs = [];
+        if (data && data.errorMessages) msgs.push(...data.errorMessages);
+        if (data && data.errors) {
+          if (Array.isArray(data.errors)) {
+            for (const e of data.errors) {
+              msgs.push(e.title || e.message || JSON.stringify(e));
+            }
+          } else {
+            for (const [field, msg] of Object.entries(data.errors)) {
+              msgs.push(`${field}: ${msg}`);
+            }
+          }
+        }
+        if (data && data.message) msgs.push(data.message);
+        const detail = msgs.length > 0 ? msgs.join('; ') : `HTTP ${res.status}`;
+        throw new ConfluenceError(`Confluence API error (${res.status}): ${detail}`, 2);
+      }
+
+      return { status: res.status, data, headers: res.headers };
+    }
+
+    // All retries exhausted
+    throw lastError || new ConfluenceError('Request failed after retries', 3);
+  }
+
+  // ── Convenience methods ──────────────────────────────────────────
+
+  async function get(path) {
+    return request('GET', path);
+  }
+
+  async function post(path, body) {
+    return request('POST', path, body);
+  }
+
+  async function put(path, body) {
+    return request('PUT', path, body);
+  }
+
+  async function del(path) {
+    return request('DELETE', path);
+  }
+
+  // ── Offset-based pagination (v1 endpoints) ────────────────────────
+
+  /**
+   * Async generator for offset-based paginated endpoints (v1).
+   * Used for CQL search, labels, comments, page tree.
+   *
+   * @param {string} path         Base path (e.g. /wiki/rest/api/content/search)
+   * @param {object} [params]     Extra query params
+   * @param {number} [pageSize]   Results per page (default: 25)
+   * @yields {object}             Each item from the paginated results
+   */
+  async function* paginateOffset(path, params = {}, pageSize = 25) {
+    let start = 0;
+    let hasMore = true;
+
+    while (hasMore) {
+      const query = new URLSearchParams({
+        ...params,
+        start: String(start),
+        limit: String(pageSize),
+      });
+      const fullPath = `${path}?${query.toString()}`;
+      const { data } = await get(fullPath);
+
+      const items = data.results || [];
+      for (const item of items) {
+        yield item;
+      }
+
+      // v1 uses _links.next or size < limit to signal end
+      hasMore = data._links?.next != null && items.length >= pageSize;
+      start += items.length;
+
+      if (items.length === 0) break;
+    }
+  }
+
+  // ── Cursor-based pagination (v2 endpoints) ────────────────────────
+
+  /**
+   * Async generator for cursor-based paginated endpoints (v2).
+   * Follows _links.next URL with cursor parameter.
+   *
+   * @param {string} path         Base path (e.g. /wiki/api/v2/spaces)
+   * @param {object} [params]     Extra query params
+   * @param {number} [pageSize]   Results per page (default: 25)
+   * @yields {object}             Each item from the paginated results
+   */
+  async function* paginateCursor(path, params = {}, pageSize = 25) {
+    const query = new URLSearchParams({
+      ...params,
+      limit: String(pageSize),
+    });
+    let nextPath = `${path}?${query.toString()}`;
+
+    while (nextPath) {
+      const { data } = await get(nextPath);
+
+      const items = data.results || [];
+      for (const item of items) {
+        yield item;
+      }
+
+      if (items.length === 0) break;
+
+      // v2 provides full next URL in _links.next - but it's a path, not absolute
+      if (data._links?.next) {
+        nextPath = data._links.next;
+      } else {
+        nextPath = null;
+      }
+    }
+  }
+
+  // ── Public API ───────────────────────────────────────────────────
+
+  return {
+    request,
+    get,
+    post,
+    put,
+    del,
+    paginateOffset,
+    paginateCursor,
+    getCredentials: () => creds(),
+  };
+}
+
+// ── Utilities ────────────────────────────────────────────────────────
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

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

@@ -0,0 +1,59 @@
+// auth.mjs - Verify Confluence credentials.
+//
+// Calls GET /wiki/api/v2/users/current (via v1 /wiki/rest/api/user/current)
+// and prints the current user's details.
+// Exit 0 on success, 2 on auth failure.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { bold, green, red } from '../format.mjs';
+
+const HELP = `confluence auth - Verify Confluence credentials
+
+Usage:
+  confluence auth
+
+Checks the configured Confluence credentials by fetching the current user's
+profile. Uses the same JIRA_* vault secrets (same Atlassian site).
+Prints display name, email, account type, and user key.
+`;
+
+/**
+ * Run the auth command.
+ *
+ * @param {string[]} argv  Remaining args after 'auth'
+ * @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();
+
+  try {
+    const { data } = await client.get('/wiki/rest/api/user/current');
+
+    log(green('Authentication successful.\n'));
+    log(`  ${bold('Name:')}         ${data.displayName || 'N/A'}`);
+    log(`  ${bold('Email:')}        ${data.email || 'N/A'}`);
+    log(`  ${bold('Username:')}     ${data.username || 'N/A'}`);
+    log(`  ${bold('Account ID:')}   ${data.accountId || 'N/A'}`);
+    log(`  ${bold('Account Type:')} ${data.accountType || 'N/A'}`);
+
+    const creds = client.getCredentials();
+    log(`  ${bold('Site:')}         ${creds.domain}.atlassian.net`);
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(red(`Authentication failed: ${err.message}`));
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,174 @@
+// comment.mjs - Add or list comments on a Confluence page.
+//
+// Usage:
+//   confluence comment <ID> <TEXT...>    Add a comment
+//   confluence comment <ID> --list       List comments
+//
+// Uses v1 endpoint for writing comments (v2 POST returns 405).
+// Uses v2 endpoint for reading comments.
+
+import { createClient, ConfluenceError } from '../client.mjs';
+import { textToStorage, storageToText } from '../storage.mjs';
+import { formatComment, bold, dim, green } from '../format.mjs';
+
+const HELP = `confluence comment - Add or list comments on a page
+
+Usage:
+  confluence comment <ID> <TEXT>         Add a comment to a page
+  confluence comment <ID> -- <TEXT>      Add a comment (text after --)
+  confluence comment <ID> --list         List recent comments
+
+Options:
+  --list          List comments instead of adding one
+  --help, -h      Show this help
+
+Comments are added via the v1 API (v2 POST returns 405).
+Comment text is converted to Confluence storage format.
+
+Examples:
+  confluence comment 12345 "This page needs updating."
+  confluence comment 12345 --list
+`;
+
+/**
+ * Parse comment command args.
+ * Handles -- separator, --list flag, and positional args.
+ */
+function parseCommentArgs(argv) {
+  let pageId = null;
+  let list = false;
+  const textParts = [];
+  let afterDash = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--') {
+      afterDash = true;
+      continue;
+    }
+    if (afterDash) {
+      textParts.push(argv[i]);
+      continue;
+    }
+    if (argv[i] === '--list') {
+      list = true;
+      continue;
+    }
+    if (argv[i] === '--help' || argv[i] === '-h') {
+      return { pageId: null, text: null, list: false, help: true };
+    }
+    if (!pageId) {
+      pageId = argv[i];
+    } else {
+      textParts.push(argv[i]);
+    }
+  }
+
+  const text = textParts.length > 0 ? textParts.join(' ') : null;
+  return { pageId, text, list, help: false };
+}
+
+/**
+ * Run the comment command.
+ *
+ * @param {string[]} argv  Remaining args after 'comment'
+ * @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 { pageId, text, list, help } = parseCommentArgs(argv);
+
+  if (help) {
+    log(HELP);
+    return 0;
+  }
+
+  if (!pageId) {
+    logError('Usage: confluence comment <ID> <TEXT>\n       confluence comment <ID> --list');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  if (list) {
+    return listComments(client, pageId, log, logError);
+  }
+
+  if (!text) {
+    logError('Usage: confluence comment <ID> <TEXT>\nProvide comment text as arguments or after --');
+    return 1;
+  }
+
+  return addComment(client, pageId, text, log, logError);
+}
+
+/**
+ * List comments on a page (via v2 endpoint).
+ */
+async function listComments(client, pageId, log, logError) {
+  try {
+    const comments = [];
+    for await (const comment of client.paginateCursor(
+      `/wiki/api/v2/pages/${encodeURIComponent(pageId)}/footer-comments`,
+      { 'body-format': 'storage' }
+    )) {
+      comments.push(comment);
+    }
+
+    if (comments.length === 0) {
+      log(dim(`No comments on page ${pageId}.`));
+      return 0;
+    }
+
+    log(bold(`Comments on page ${pageId}`) + dim(` (${comments.length})\n`));
+
+    for (const comment of comments) {
+      // Render storage body to text
+      const bodyStorage = comment.body?.storage?.value || '';
+      comment._bodyText = storageToText(bodyStorage);
+      log(formatComment(comment));
+      log('');
+    }
+
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to list comments: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Add a comment to a page (via v1 endpoint - v2 POST returns 405).
+ */
+async function addComment(client, pageId, text, log, logError) {
+  try {
+    const storageBody = textToStorage(text);
+    const { data } = await client.post('/wiki/rest/api/content', {
+      type: 'comment',
+      container: {
+        id: pageId,
+        type: 'page',
+      },
+      body: {
+        storage: {
+          value: storageBody,
+          representation: 'storage',
+        },
+      },
+    });
+
+    log(green(`Comment added to page ${pageId}.`) + dim(` (id: ${data.id})`));
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfluenceError) {
+      logError(`Failed to add comment: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}