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

package/dist/engineering-pa-core-extensions-atlassian/src/common/secrets.mjs

@@ -0,0 +1,158 @@
+// secrets.mjs - resolve Atlassian credentials for the jira and confluence
+// CLIs (and the shared client factories in src/jira, src/confluence).
+//
+// Both CLIs point at the same Atlassian site so the three required keys are
+// shared:
+//
+//   JIRA_DOMAIN     Atlassian subdomain, e.g. "yoursite" for yoursite.atlassian.net
+//   JIRA_EMAIL      Account email used with the API token
+//   JIRA_API_TOKEN  User-scoped API token from id.atlassian.com
+//
+// One optional key is also resolved on demand (never required):
+//
+//   JIRA_DEFAULT_PROJECT  Project key the `jira mine` verb narrows to when
+//                         the operator does not pass --project / --all. With
+//                         nothing configured, `mine` returns issues across
+//                         every project the account can see.
+//
+// Resolution order for each key:
+//   1. Explicit override via opts.secretsGet(key) (tests inject a function)
+//   2. Environment variable of the same name (JIRA_DOMAIN, ...)
+//   3. Platform `secrets` bin: `secrets get <ATLASSIAN_SECRETS_PREFIX?>KEY`
+//      Runs against the workspace-root vault the operator scaffold seeds.
+//      A prefix such as an org-slug like `acme/` (env var
+//      ATLASSIAN_SECRETS_PREFIX) picks a non-default scope via the platform
+//      full-scope reference form.
+//
+// The tool never prints or logs the values. All read paths run
+// `stdio: ['ignore', 'pipe', 'pipe']` and the caller's error strings never
+// interpolate the value.
+//
+// Zero npm dependencies. Uses node:child_process for the fallback bin call.
+
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Sentinel raised when a required credential cannot be resolved. Callers
+ * wrap this in their own JiraError / ConfluenceError with exit code 3.
+ */
+export class CredentialResolutionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CredentialResolutionError';
+  }
+}
+
+const KEYS = ['JIRA_DOMAIN', 'JIRA_EMAIL', 'JIRA_API_TOKEN'];
+
+/**
+ * Resolve a single Atlassian secret. Not for external use; the CLIs call
+ * loadAtlassianCredentials.
+ * @param {string} key
+ * @param {{ secretsGet?: (key: string) => string, secretsBin?: string, env?: Record<string,string> }} opts
+ * @returns {string}
+ */
+export function resolveSecret(key, opts = {}) {
+  if (typeof opts.secretsGet === 'function') {
+    const v = opts.secretsGet(key);
+    if (typeof v === 'string' && v.length > 0) return v.trim();
+    throw new CredentialResolutionError(`opts.secretsGet returned no value for ${key}`);
+  }
+
+  const env = opts.env ?? process.env;
+
+  const envValue = env[key];
+  if (typeof envValue === 'string' && envValue.length > 0) return envValue.trim();
+
+  const prefix = env.ATLASSIAN_SECRETS_PREFIX ?? '';
+  const scopedKey = `${prefix}${key}`;
+  const bin = opts.secretsBin ?? 'secrets';
+
+  try {
+    const out = execFileSync(bin, ['get', scopedKey], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
+    });
+    const trimmed = out.trim();
+    if (trimmed.length === 0) {
+      throw new CredentialResolutionError(
+        `platform \`secrets get ${scopedKey}\` returned empty output`,
+      );
+    }
+    return trimmed;
+  } catch (err) {
+    if (err instanceof CredentialResolutionError) throw err;
+    const stderrSnippet = err.stderr ? String(err.stderr).trim().split('\n').pop() : '';
+    const hint = stderrSnippet
+      ? ` (${stderrSnippet})`
+      : ' (bin missing? try `pnpm exec secrets get` from your operator repo)';
+    throw new CredentialResolutionError(
+      `could not read ${key} from env or \`secrets get ${scopedKey}\`${hint}`,
+    );
+  }
+}
+
+/**
+ * Resolve an OPTIONAL Atlassian setting. Same env -> secrets bin order as
+ * resolveSecret, but returns null instead of throwing when the key is
+ * absent so a caller can fall back to a "no default" branch cleanly. Used
+ * for JIRA_DEFAULT_PROJECT and any other future soft config the tools
+ * accept but never require.
+ *
+ * A missing env var and a bin call that exits non-zero, both return null;
+ * an empty string from the bin returns null too. Any other exec failure
+ * (bin missing, permission error) is swallowed so an operator without the
+ * `secrets` bin on PATH still gets the "no default" behaviour rather than
+ * a crash on an optional lookup. The primary credential path stays strict.
+ *
+ * @param {string} key
+ * @param {{ secretsGet?: (key: string) => string, secretsBin?: string, env?: Record<string,string> }} opts
+ * @returns {string | null}
+ */
+export function resolveOptionalSecret(key, opts = {}) {
+  if (typeof opts.secretsGet === 'function') {
+    try {
+      const v = opts.secretsGet(key);
+      if (typeof v === 'string' && v.length > 0) return v.trim();
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  const env = opts.env ?? process.env;
+
+  const envValue = env[key];
+  if (typeof envValue === 'string' && envValue.length > 0) return envValue.trim();
+
+  const prefix = env.ATLASSIAN_SECRETS_PREFIX ?? '';
+  const scopedKey = `${prefix}${key}`;
+  const bin = opts.secretsBin ?? 'secrets';
+
+  try {
+    const out = execFileSync(bin, ['get', scopedKey], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
+    });
+    const trimmed = out.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load all three Atlassian credentials. Test suites pass in
+ * `{ secretsGet: (key) => literal }` to skip both env vars and the bin.
+ *
+ * @param {{ secretsGet?: (key: string) => string, secretsBin?: string, env?: Record<string,string> }} opts
+ * @returns {{ domain: string, email: string, apiToken: string }}
+ */
+export function loadAtlassianCredentials(opts = {}) {
+  const domain = resolveSecret('JIRA_DOMAIN', opts);
+  const email = resolveSecret('JIRA_EMAIL', opts);
+  const apiToken = resolveSecret('JIRA_API_TOKEN', opts);
+  return { domain, email, apiToken };
+}

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;
+  }
+}