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

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

@@ -0,0 +1,313 @@
+// cli.mjs - Confluence Fetch CLI.
+//
+// Single-command CLI that wraps the full retrieval pipeline:
+//   confluence-fetch <phrase> [options]
+//
+// Exit codes:
+//   0 - success
+//   1 - usage error (bad args)
+//   2 - API/logical error (page not found, auth failed, no results)
+//   3 - transport/IO failure (network error, vault unavailable)
+
+import { retrieve, createConfluenceClient, searchPages } from './fetch.mjs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+
+// ── Help text ────────────────────────────────────────────────────────
+
+const HELP = `confluence-fetch - Search, fetch, save, and view Confluence pages
+
+Usage:
+  confluence-fetch <phrase> [options]
+
+Arguments:
+  phrase              Search phrase (title or content)
+
+Options:
+  --max N             Maximum search results (default: 5)
+  --pick N            Auto-select Nth result, 1-based (default: 1)
+  --search-type TYPE  Search strategy: auto, title, text (default: auto)
+  --list              List search results without fetching
+  --viewer-base URL   Workspace viewer base URL (default: http://127.0.0.1:4222)
+  --no-open           Do not open the viewer URL after saving
+  --help, -h          Show this help
+
+Search strategy (--search-type):
+  auto    Try title search first; fall back to full-text if no results (default)
+  title   Search by title only
+  text    Search by full-text content only
+
+Examples:
+  confluence-fetch "observability standards"
+  confluence-fetch "API documentation" --max 10 --pick 2
+  confluence-fetch "deployment runbook" --search-type text
+  confluence-fetch "architecture" --list
+`;
+
+// ── Arg parser ───────────────────────────────────────────────────────
+
+/**
+ * Parse argv into flags and positional args.
+ *
+ * @param {string[]} argv  Arguments
+ * @returns {{ _: string[], [key: string]: string|boolean }}
+ */
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--') {
+      args._.push(...argv.slice(i + 1));
+      break;
+    }
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      if (key.startsWith('no-')) {
+        // --no-open → open = false
+        args[key.slice(3)] = false;
+        continue;
+      }
+      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;
+}
+
+// ── ANSI helpers ─────────────────────────────────────────────────────
+
+const IS_TTY = process.stdout.isTTY;
+function ansi(code, text) { return IS_TTY ? `\x1b[${code}m${text}\x1b[0m` : text; }
+function bold(text) { return ansi('1', text); }
+function dim(text) { return ansi('2', text); }
+function green(text) { return ansi('32', text); }
+function cyan(text) { return ansi('36', text); }
+
+// ── Format search results ────────────────────────────────────────────
+
+/**
+ * Format search results as a numbered list.
+ *
+ * @param {Array<{id: string, title: string, space: string}>} results
+ * @returns {string}
+ */
+function formatResults(results) {
+  if (!results || results.length === 0) return dim('No results found.');
+
+  const lines = results.map((r, i) => {
+    const num = String(i + 1).padStart(2);
+    const space = r.space ? dim(` [${r.space}]`) : '';
+    return `  ${dim(num + '.')} ${r.title || '(untitled)'}${space}  ${dim('ID:' + r.id)}`;
+  });
+
+  return lines.join('\n');
+}
+
+// ── Run ──────────────────────────────────────────────────────────────
+
+/**
+ * Run the CLI.
+ *
+ * @param {string[]} argv   Arguments after the command name
+ * @param {object} [deps]   Dependency overrides for testing
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+  const args = parseArgs(argv);
+
+  // Help
+  if (args.help || args.h) {
+    log(HELP);
+    return 0;
+  }
+
+  // Phrase is required
+  const phrase = args._.join(' ');
+  if (!phrase) {
+    logError('Usage: confluence-fetch <phrase> [options]');
+    logError('Run with --help for full usage.');
+    return 1;
+  }
+
+  // Parse options
+  const max = args.max ? parseInt(args.max, 10) : 5;
+  if (isNaN(max) || max < 1) {
+    logError('--max must be a positive integer');
+    return 1;
+  }
+
+  const pick = args.pick ? parseInt(args.pick, 10) : 1;
+  if (isNaN(pick) || pick < 1) {
+    logError('--pick must be a positive integer (1-based)');
+    return 1;
+  }
+
+  const searchType = args['search-type'] || 'auto';
+  if (!['auto', 'title', 'text'].includes(searchType)) {
+    logError('--search-type must be one of: auto, title, text');
+    return 1;
+  }
+
+  const listOnly = args.list === true;
+  const viewerBase = args['viewer-base'] || 'http://127.0.0.1:4222';
+  const shouldOpen = args.open !== false; // default true unless --no-open
+
+  // Create client
+  let client;
+  if (deps.client) {
+    client = deps.client;
+  } else {
+    try {
+      client = await createConfluenceClient();
+    } catch (err) {
+      logError(`Failed to initialise Confluence client: ${err.message}`);
+      return 3;
+    }
+  }
+
+  try {
+    // List mode - just search and display results
+    if (listOnly) {
+      log(bold('Searching Confluence: ') + dim(`"${phrase}"`));
+      log('');
+
+      const { results, searchType: usedType } = await searchPages(client, phrase, {
+        max,
+        searchType,
+      });
+
+      log(dim(`Search type: ${usedType}`) + dim(` | ${results.length} result(s)`));
+      log('');
+
+      if (results.length === 0) {
+        log(dim('No results found.'));
+        return 0;
+      }
+
+      const formatted = results.map((r) => ({
+        id: r.id,
+        title: r.title || '(untitled)',
+        space: r.space?.key || '',
+      }));
+
+      log(formatResults(formatted));
+      log('');
+      log(dim('Use --pick N to fetch a specific result:'));
+      log(dim(`  confluence-fetch "${phrase}" --pick N`));
+      return 0;
+    }
+
+    // Full retrieval mode
+    log(bold('Fetching from Confluence: ') + dim(`"${phrase}"`));
+    log('');
+
+    const result = await retrieve(client, phrase, {
+      max,
+      pick,
+      searchType,
+      viewerBase,
+      repoRoot: deps.repoRoot || REPO_ROOT,
+      notesDir: deps.notesDir,
+      writeFileSync: deps.writeFileSync,
+      storageToMarkdown: deps.storageToMarkdown,
+    });
+
+    if (result.resultCount === 0) {
+      log(dim('No results found for: ') + `"${phrase}"`);
+      log('');
+      log(dim('Tips:'));
+      log(dim('  - Try broader search terms'));
+      log(dim('  - Use --search-type text for full-text search'));
+      return 2;
+    }
+
+    // Show what was found if multiple results
+    if (result.resultCount > 1) {
+      log(dim(`Found ${result.resultCount} result(s) via ${result.searchType} search. Fetching #${pick}:`));
+      log('');
+      log(formatResults(result.results));
+      log('');
+    }
+
+    // Show the fetched page
+    log(green('Saved: ') + bold(result.title));
+    log(dim('  File: ') + result.filePath);
+    log(dim('  View: ') + cyan(result.viewerUrl));
+
+    // Open in browser
+    if (shouldOpen && !deps.writeFileSync) {
+      const openUrl = deps.openUrl || defaultOpenUrl;
+      await openUrl(result.viewerUrl);
+      log('');
+      log(dim('Opened in browser.'));
+    }
+
+    return 0;
+  } catch (err) {
+    // Check for ConfluenceError-shaped errors
+    if (err.name === 'ConfluenceError' || err.exitCode) {
+      logError(`Confluence error: ${err.message}`);
+      return err.exitCode || 2;
+    }
+    logError(`Error: ${err.message}`);
+    return 3;
+  }
+}
+
+// ── Open URL ─────────────────────────────────────────────────────────
+
+/**
+ * Open a URL in the default browser.
+ * @param {string} url
+ */
+async function defaultOpenUrl(url) {
+  const { execFile } = await import('node:child_process');
+  const { promisify } = await import('node:util');
+  const execFileAsync = promisify(execFile);
+
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    await execFileAsync('open', [url]);
+  } else if (platform === 'win32') {
+    await execFileAsync('cmd', ['/c', 'start', '', url]);
+  } else {
+    await execFileAsync('xdg-open', [url]);
+  }
+}
+
+// ── Entry point ──────────────────────────────────────────────────────
+
+/**
+ * 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) {
+    console.error(`confluence-fetch: ${err.message || err}`);
+    process.exitCode = 3;
+  }
+}

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

@@ -0,0 +1,327 @@
+// fetch.mjs - Core Confluence page retrieval logic.
+//
+// Orchestrates the full retrieval flow:
+//   1. Search Confluence by title (falls back to full-text)
+//   2. Select the best match (or let the caller choose)
+//   3. Fetch the page content as markdown
+//   4. Save to operator/notes/
+//   5. Return the viewer URL
+//
+// Delegates to the Confluence tool via its public entry point
+// (operator/extensions/tools/confluence/index.mjs), never its src/
+// internals, which may be reorganised without notice.
+// Zero external dependencies - uses only Node built-ins.
+
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync, writeFileSync as nodeWriteFileSync, readFileSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── Path resolution ──────────────────────────────────────────────────
+
+// Repo root: env override, else cwd. Invoked from a workspace root.
+const REPO_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+
+// Public entry point of the sibling Confluence tool. Stable contract:
+// see operator/extensions/tools/confluence/README.md "Library usage".
+// Resolved relative to this module, so it survives repo relocation.
+const CONFLUENCE_ENTRY = new URL('../confluence/storage.mjs', import.meta.url);
+
+// Default notes directory for saved pages
+const NOTES_DIR = resolve(REPO_ROOT, 'operator', 'notes');
+
+// Read the workspace port from the merged operator config - the device-local
+// preferences.local.json overlay over the synced preferences.json - falling
+// back to the platform default (4200).
+//
+// The overlay (preferences.local.json) is the operator's device-scoped
+// escape hatch: gitignored, so a per-device workspacePort never travels
+// through the synced base file. Precedence matches the platform's own
+// reader in engineering-pa-core src/desk/team-scope.mjs mergePreferences().
+const PREFERENCES_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.json');
+const PREFERENCES_LOCAL_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.local.json');
+const PLATFORM_DEFAULT_PORT = 4200;
+
+function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    // Missing or malformed - that layer contributes nothing.
+    return null;
+  }
+}
+
+/**
+ * Resolve the local workspace port from the merged preferences.
+ * Overlay keys win; keys it omits fall through to the synced base; a device
+ * with no overlay behaves exactly as before this change.
+ *
+ * Paths are injectable for tests only - production callers pass nothing.
+ *
+ * @param {object} [paths]
+ * @param {string} [paths.base]   preferences.json path.
+ * @param {string} [paths.local]  preferences.local.json path.
+ * @returns {number}
+ */
+export function resolveWorkspacePort({ base = PREFERENCES_PATH, local = PREFERENCES_LOCAL_PATH } = {}) {
+  const prefs = { ...(readJsonObject(base) || {}), ...(readJsonObject(local) || {}) };
+  return typeof prefs.workspacePort === 'number' ? prefs.workspacePort : PLATFORM_DEFAULT_PORT;
+}
+
+const DEFAULT_VIEWER_BASE = `http://127.0.0.1:${resolveWorkspacePort()}`;
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Sanitise a page title for use as a filename.
+ * Converts to lowercase, replaces non-alphanumeric chars with hyphens,
+ * collapses consecutive hyphens, trims leading/trailing hyphens.
+ *
+ * @param {string} title  Page title
+ * @returns {string}      Sanitised filename stem
+ */
+export function sanitiseTitle(title) {
+  if (!title) return 'untitled';
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
+    || 'untitled';
+}
+
+/**
+ * Build the viewer URL for a saved file.
+ *
+ * @param {string} filePath     Absolute path to the saved file
+ * @param {string} repoRoot     Absolute path to the repo root
+ * @param {string} viewerBase   Base URL for the workspace viewer
+ * @returns {string}            Full viewer URL
+ */
+export function buildViewerUrl(filePath, repoRoot, viewerBase) {
+  // The viewer expects a repo-relative path
+  const relative = filePath.startsWith(repoRoot)
+    ? filePath.slice(repoRoot.length + 1)
+    : filePath;
+  return `${viewerBase}/viewer.html?file=${encodeURIComponent(relative)}`;
+}
+
+// ── Search ───────────────────────────────────────────────────────────
+
+/**
+ * Search Confluence for pages matching a phrase.
+ * Tries title search first; falls back to full-text if no results.
+ *
+ * @param {object} client       Confluence API client
+ * @param {string} phrase       Search phrase
+ * @param {object} [options]
+ * @param {number} [options.max]          Max results (default: 5)
+ * @param {string} [options.searchType]   'title', 'text', or 'auto' (default: 'auto')
+ * @returns {Promise<{ results: Array, searchType: string }>}
+ */
+export async function searchPages(client, phrase, options = {}) {
+  const max = options.max || 5;
+  const searchType = options.searchType || 'auto';
+
+  // Build CQL for title search
+  const titleCql = `title ~ '${escapeCql(phrase)}' AND type = page`;
+  // Build CQL for full-text search
+  const textCql = `text ~ '${escapeCql(phrase)}' AND type = page`;
+
+  async function runSearch(cql, limit) {
+    const results = [];
+    for await (const item of client.paginateOffset('/wiki/rest/api/content/search', { cql, limit: String(limit) }, limit)) {
+      results.push(item);
+      if (results.length >= limit) break;
+    }
+    return results;
+  }
+
+  if (searchType === 'text') {
+    const results = await runSearch(textCql, max);
+    return { results, searchType: 'text' };
+  }
+
+  if (searchType === 'title') {
+    const results = await runSearch(titleCql, max);
+    return { results, searchType: 'title' };
+  }
+
+  // Auto mode: try title first, fall back to text
+  const titleResults = await runSearch(titleCql, max);
+  if (titleResults.length > 0) {
+    return { results: titleResults, searchType: 'title' };
+  }
+
+  const textResults = await runSearch(textCql, max);
+  return { results: textResults, searchType: 'text' };
+}
+
+/**
+ * Escape single quotes in CQL values.
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeCql(value) {
+  return value.replace(/'/g, "\\'");
+}
+
+// ── Fetch page ───────────────────────────────────────────────────────
+
+/**
+ * Fetch a single Confluence page and convert to markdown.
+ *
+ * @param {object} client         Confluence API client
+ * @param {string} pageId         Page ID
+ * @param {object} [deps]         Dependency overrides for testing
+ * @param {Function} [deps.storageToMarkdown]  Storage converter override
+ * @returns {Promise<{ title: string, markdown: string, pageId: string, spaceId: string }>}
+ */
+export async function fetchPage(client, pageId, deps = {}) {
+  const { data: page } = await client.get(
+    `/wiki/api/v2/pages/${encodeURIComponent(pageId)}?body-format=storage`
+  );
+
+  const storageBody = page.body?.storage?.value || '';
+
+  // Load storage converter
+  let storageToMarkdown;
+  if (deps.storageToMarkdown) {
+    storageToMarkdown = deps.storageToMarkdown;
+  } else {
+    const confluence = await import(CONFLUENCE_ENTRY);
+    storageToMarkdown = confluence.storageToMarkdown;
+  }
+
+  const markdown = storageToMarkdown(storageBody);
+
+  return {
+    title: page.title || 'Untitled',
+    markdown,
+    pageId: page.id,
+    spaceId: page.spaceId || null,
+  };
+}
+
+// ── Save ─────────────────────────────────────────────────────────────
+
+/**
+ * Save markdown content to operator/notes/.
+ *
+ * @param {string} title      Page title (used to generate filename)
+ * @param {string} markdown   Markdown content
+ * @param {object} [options]
+ * @param {string} [options.notesDir]       Override notes directory
+ * @param {string} [options.filename]       Override filename (without extension)
+ * @param {Function} [options.writeFileSync]  Write function override for testing
+ * @returns {string}  Absolute path to the saved file
+ */
+export function savePage(title, markdown, options = {}) {
+  const notesDir = options.notesDir || NOTES_DIR;
+  const stem = options.filename || `confluence-${sanitiseTitle(title)}`;
+  const filePath = resolve(notesDir, `${stem}.md`);
+
+  // Prepend a metadata header
+  const header = `# ${title}\n\n*Retrieved from Confluence on ${new Date().toISOString().slice(0, 10)}*\n\n---\n\n`;
+  const content = header + markdown;
+
+  const writeFn = options.writeFileSync || nodeWriteFileSync;
+
+  // Ensure the directory exists
+  if (!options.writeFileSync) {
+    mkdirSync(notesDir, { recursive: true });
+  }
+
+  writeFn(filePath, content, 'utf-8');
+  return filePath;
+}
+
+// ── Full retrieval flow ─────────────────────────────────────────────
+
+/**
+ * Execute the full retrieval pipeline:
+ *   search -> select -> fetch -> save -> return viewer URL
+ *
+ * @param {object} client        Confluence API client
+ * @param {string} phrase        Search phrase
+ * @param {object} [options]
+ * @param {number} [options.max]            Max search results (default: 5)
+ * @param {number} [options.pick]           1-based index to auto-pick from results
+ * @param {string} [options.searchType]     'title', 'text', or 'auto'
+ * @param {string} [options.notesDir]       Override notes directory
+ * @param {string} [options.viewerBase]     Override viewer base URL
+ * @param {string} [options.repoRoot]       Override repo root path
+ * @param {Function} [options.writeFileSync]   Override for testing
+ * @param {Function} [options.storageToMarkdown]  Override for testing
+ * @returns {Promise<{ filePath: string, viewerUrl: string, title: string, pageId: string, searchType: string, resultCount: number }>}
+ */
+export async function retrieve(client, phrase, options = {}) {
+  const repoRoot = options.repoRoot || REPO_ROOT;
+  const viewerBase = options.viewerBase || DEFAULT_VIEWER_BASE;
+  const pick = options.pick || 1;
+
+  // Step 1: Search
+  const { results, searchType } = await searchPages(client, phrase, {
+    max: options.max,
+    searchType: options.searchType,
+  });
+
+  if (results.length === 0) {
+    return {
+      filePath: null,
+      viewerUrl: null,
+      title: null,
+      pageId: null,
+      searchType,
+      resultCount: 0,
+      results: [],
+    };
+  }
+
+  // Step 2: Select
+  const index = Math.max(0, Math.min(pick - 1, results.length - 1));
+  const selected = results[index];
+
+  // Step 3: Fetch
+  const page = await fetchPage(client, selected.id, {
+    storageToMarkdown: options.storageToMarkdown,
+  });
+
+  // Step 4: Save
+  const filePath = savePage(page.title, page.markdown, {
+    notesDir: options.notesDir || resolve(repoRoot, 'operator', 'notes'),
+    writeFileSync: options.writeFileSync,
+  });
+
+  // Step 5: Build viewer URL
+  const viewerUrl = buildViewerUrl(filePath, repoRoot, viewerBase);
+
+  return {
+    filePath,
+    viewerUrl,
+    title: page.title,
+    pageId: page.pageId,
+    searchType,
+    resultCount: results.length,
+    results: results.map((r) => ({
+      id: r.id,
+      title: r.title || '',
+      space: r.space?.key || '',
+    })),
+  };
+}
+
+// ── Exports for the Confluence client loader ────────────────────────
+
+/**
+ * Create a Confluence client via the Confluence tool's public entry.
+ * @param {object} [options]  Client options (see the confluence README)
+ * @returns {object}          Confluence API client
+ */
+export async function createConfluenceClient(options = {}) {
+  const { createClient } = await import(CONFLUENCE_ENTRY);
+  return createClient(options);
+}