page-analyzer 1.2.1 → 1.2.3

package/llm/providers/codex-cli-provider.js

@@ -0,0 +1,154 @@
+import { BaseLlmProvider } from './base-provider.js';
+import { runCli, makeTmpOutFile } from './cli-runner.js';
+
+const FAST_MODEL_NAME = 'gpt-5.5';
+
+/**
+ * Codex CLI provider — invokes the locally installed `codex exec` command.
+ *
+ * Auth is whatever the user's local codex install already has; no API key needed.
+ * Returns the final agent message (read from `-o` outfile) as a plain string,
+ * matching the BaseLlmProvider contract.
+ */
+export class CodexCliProvider extends BaseLlmProvider {
+  constructor(config = {}) {
+    super(config);
+    if (!this.model) {
+      throw new Error('CodexCliProvider: model is required');
+    }
+    this.cliPath = config.cliPath || 'codex';
+    this.cwd = config.cwd || null;
+    this.fast = typeof config.fast === 'boolean'
+      ? config.fast
+      : this.model === FAST_MODEL_NAME;
+  }
+
+  buildArgs(outFile) {
+    const args = [
+      'exec',
+      '-m', this.model,
+      '--skip-git-repo-check',
+      '--sandbox', 'read-only',
+      '--ephemeral',
+      '--color', 'never',
+      '--dangerously-bypass-approvals-and-sandbox',
+      '-o', outFile
+    ];
+    if (this.fast) {
+      args.push('-c', 'service_tier="fast"');
+    }
+    return args;
+  }
+
+  resolveInteractionContext(metadata) {
+    const context = metadata && typeof metadata === 'object' ? metadata : {};
+    const domain = String(context.domain || '').trim();
+    const nodeId = String(context.nodeId || '').trim();
+    if (!domain || !nodeId) {
+      return null;
+    }
+    return {
+      domain,
+      nodeId,
+      operation: String(context.operation || 'analysis').trim() || 'analysis',
+      chunkLabel: String(context.chunkLabel || '').trim() || null
+    };
+  }
+
+  async makeRequest(prompt, options = {}) {
+    const metadata = options && typeof options.metadata === 'object' ? options.metadata : {};
+    const interactionContext = this.resolveInteractionContext(metadata);
+    const { filePath: outFile, cleanup } = await makeTmpOutFile('codex-cli', 'last-message.txt');
+    const args = this.buildArgs(outFile);
+    const requestPayload = { argv: [this.cliPath, ...args], model: this.model, fast: this.fast };
+
+    let failureLogged = false;
+    try {
+      const result = await runCli({
+        command: this.cliPath,
+        args,
+        prompt,
+        timeoutMs: this.timeout,
+        outFile,
+        cwd: this.cwd || undefined
+      });
+
+      const outputText = String(result.outFileContent ?? '').trim();
+      if (result.code !== 0 || !outputText) {
+        if (interactionContext) {
+          await this.emitInteractionLog({
+            ...interactionContext,
+            provider: 'Codex',
+            model: this.model,
+            requestId: null,
+            inputText: prompt,
+            outputText: outputText || null,
+            requestPayload,
+            responsePayload: { stdout: result.stdout, stderr: result.stderr, code: result.code, signal: result.signal },
+            usagePromptTokens: null,
+            usageCompletionTokens: null,
+            usageReasoningTokens: null,
+            usageCost: null
+          });
+          failureLogged = true;
+        }
+        const reason = result.code !== 0
+          ? `exited with code ${result.code}${result.signal ? ` (signal ${result.signal})` : ''}`
+          : 'produced empty output file';
+        const stderrTail = String(result.stderr || '').slice(-500);
+        throw new Error(`codex exec ${reason}${stderrTail ? `: ${stderrTail}` : ''}`);
+      }
+
+      if (interactionContext) {
+        await this.emitInteractionLog({
+          ...interactionContext,
+          provider: 'Codex',
+          model: this.model,
+          requestId: null,
+          inputText: prompt,
+          outputText,
+          requestPayload,
+          responsePayload: { stdout: result.stdout, stderr: result.stderr, code: result.code, signal: result.signal },
+          usagePromptTokens: null,
+          usageCompletionTokens: null,
+          usageReasoningTokens: null,
+          usageCost: null
+        });
+      }
+
+      return outputText;
+    } catch (error) {
+      if (!failureLogged && interactionContext) {
+        await this.emitInteractionLog({
+          ...interactionContext,
+          provider: 'Codex',
+          model: this.model,
+          requestId: null,
+          inputText: prompt,
+          outputText: null,
+          requestPayload,
+          responsePayload: null,
+          usagePromptTokens: null,
+          usageCompletionTokens: null,
+          usageReasoningTokens: null,
+          usageCost: null
+        });
+      }
+      throw error;
+    } finally {
+      await cleanup();
+    }
+  }
+
+  async analyze(content, options = {}) {
+    const requestOptions = { ...options };
+    delete requestOptions.parseJson;
+    return this.makeRequestWithRetry(() => this.makeRequest(String(content ?? ''), requestOptions));
+  }
+
+  validateConfig() {
+    if (!this.model) {
+      throw new Error('Model is required');
+    }
+  }
+}

package/llm/providers/index.js

@@ -0,0 +1,61 @@
+import { OpenAiProvider } from './openai-provider.js';
+import { CodexCliProvider } from './codex-cli-provider.js';
+import { ClaudeCliProvider } from './claude-cli-provider.js';
+
+export const LLM_PROVIDER_TYPES = Object.freeze(['openai', 'codex', 'claude']);
+
+/**
+ * Build the right LLM provider instance from an llmConfig object.
+ *
+ * @param {Object} llmConfig
+ * @param {'openai'|'codex'|'claude'} [llmConfig.type='openai']
+ * @param {string} llmConfig.model
+ * @param {string} [llmConfig.apiKey]
+ * @param {string} [llmConfig.apiEndpoint]
+ * @param {string} [llmConfig.cliPath]
+ * @param {string} [llmConfig.cwd]
+ * @param {boolean} [llmConfig.fast]
+ * @param {number} [llmConfig.maxTokens]
+ * @param {number} [llmConfig.temperature]
+ * @param {number} [llmConfig.timeout]
+ * @param {number} [llmConfig.maxRetries]
+ * @param {Function} [llmConfig.interactionLogger]
+ */
+export function createLlmProvider(llmConfig = {}) {
+  const type = String(llmConfig.type || 'openai').toLowerCase();
+  const shared = {
+    model: llmConfig.model,
+    timeout: llmConfig.timeout,
+    maxRetries: llmConfig.maxRetries,
+    maxTokens: llmConfig.maxTokens,
+    interactionLogger: llmConfig.interactionLogger
+  };
+
+  switch (type) {
+    case 'openai':
+      return new OpenAiProvider({
+        ...shared,
+        apiKey: llmConfig.apiKey,
+        apiEndpoint: llmConfig.apiEndpoint,
+        temperature: llmConfig.temperature
+      });
+    case 'codex':
+      return new CodexCliProvider({
+        ...shared,
+        cliPath: llmConfig.cliPath,
+        cwd: llmConfig.cwd,
+        fast: llmConfig.fast
+      });
+    case 'claude':
+      return new ClaudeCliProvider({
+        ...shared,
+        cliPath: llmConfig.cliPath,
+        cwd: llmConfig.cwd
+      });
+    default:
+      throw new Error(`Unknown llm.type: ${llmConfig.type}. Expected one of: ${LLM_PROVIDER_TYPES.join(', ')}`);
+  }
+}
+
+export { OpenAiProvider, CodexCliProvider, ClaudeCliProvider };
+export { BaseLlmProvider } from './base-provider.js';

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "page-analyzer",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "type": "module",
   "description": "Standalone page analysis module.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liuzemei/page-analyzer.git"
+  },
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "node test/smoke.test.js",
     "analyze": "node scripts/analyze.js",

package/page-extractor.js

@@ -5,7 +5,8 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { createHash } from 'node:crypto';
+import { HeadObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
 
 // In-browser block extraction function (serialized into page.evaluate)
 // Imported from the project's extract-blocks script
@@ -41,6 +42,24 @@ function createSnapshotRunId() {
     .replace(/^-+|-+$/g, '');
 }
 
+function createS3DomainSegment(url) {
+  const source = String(url || '').trim();
+  try {
+    const parsed = new URL(source);
+    const hostname = parsed.hostname
+      .toLowerCase()
+      .replace(/[^a-z0-9.-]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+    return hostname || 'page';
+  } catch {
+    return createSnapshotSlug(source);
+  }
+}
+
+function createFileMd5(body) {
+  return createHash('md5').update(body).digest('hex');
+}
+
 function getBlockNumber(block, fallbackIndex) {
   return Number.isInteger(block?.blockIdx) ? block.blockIdx : fallbackIndex;
 }
@@ -96,8 +115,8 @@ function normalizeS3Config(config) {
   };
 }
 
-function joinS3Key(prefix, filename) {
-  return [prefix, filename].filter(Boolean).join('/');
+function joinS3Key(...parts) {
+  return parts.filter(Boolean).join('/');
 }
 
 function encodeS3Key(key) {
@@ -119,6 +138,12 @@ function getErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+function isS3NotFoundError(error) {
+  const statusCode = error?.$metadata?.httpStatusCode;
+  const errorName = String(error?.name || error?.Code || error?.code || '');
+  return statusCode === 404 || errorName === 'NotFound' || errorName === 'NoSuchKey';
+}
+
 export class PageExtractor {
   constructor(config = {}) {
     this.config = {
@@ -136,6 +161,10 @@ export class PageExtractor {
       textPreviewMaxChars: Number.isInteger(config.textPreviewMaxChars)
         ? Math.max(120, config.textPreviewMaxChars)
         : 1200,
+      sizedElementsEnabled: Boolean(config.sizedElementsEnabled),
+      sizedElementMinSize: Number.isInteger(config.sizedElementMinSize)
+        ? Math.max(0, config.sizedElementMinSize)
+        : 24,
       waitForImagesLoaded: Boolean(config.waitForImagesLoaded),
       fullPageScreenshot: Boolean(config.fullPageScreenshot),
       blockScreenshots: Boolean(config.blockScreenshots),
@@ -176,13 +205,30 @@ export class PageExtractor {
     return this.s3Client;
   }
 
-  async uploadScreenshotToS3(filename, body) {
+  async s3ObjectExists(client, key) {
+    const s3Config = this.config.s3;
+    try {
+      await client.send(new HeadObjectCommand({
+        Bucket: s3Config.bucket,
+        Key: key
+      }));
+      return true;
+    } catch (error) {
+      if (isS3NotFoundError(error)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  async uploadScreenshotToS3(targetUrl, body) {
     const s3Config = this.config.s3;
     if (!s3Config) {
       throw new Error('S3 is not configured');
     }
 
-    const key = joinS3Key(s3Config.prefix, filename);
+    const domain = createS3DomainSegment(targetUrl);
+    const key = joinS3Key(s3Config.prefix, domain, `${createFileMd5(body)}.png`);
     const client = this.getS3Client();
     const commandInput = {
       Bucket: s3Config.bucket,
@@ -194,6 +240,9 @@ export class PageExtractor {
     let lastError = null;
     for (let attempt = 1; attempt <= s3Config.maxUploadAttempts; attempt += 1) {
       try {
+        if (await this.s3ObjectExists(client, key)) {
+          return buildS3Url(s3Config, key);
+        }
         const command = new PutObjectCommand(commandInput);
         await client.send(command);
         return buildS3Url(s3Config, key);
@@ -201,7 +250,7 @@ export class PageExtractor {
         lastError = error;
         if (attempt < s3Config.maxUploadAttempts) {
           console.warn(
-            `[page-analyzer] Failed to upload ${key} to S3, retrying ` +
+            `[page-analyzer] Failed to check/upload ${key} to S3, retrying ` +
             `(${attempt}/${s3Config.maxUploadAttempts}): ${getErrorMessage(error)}`
           );
         }
@@ -431,6 +480,147 @@ export class PageExtractor {
     });
   }
 
+  /**
+   * Collect ALL visible DOM elements that have "some size" (width > minSize OR
+   * height > minSize), each annotated with basic raw info. Broader than
+   * collectElementGeometries (which is interactive-only); used to nest element
+   * detail under each block in the analysis output.
+   */
+  async collectSizedElements(page) {
+    const minSize = this.config.sizedElementMinSize;
+    const records = await page.evaluate((minSizePx) => {
+      const INTERACTIVE_SELECTOR = 'a, button, form, input, select, textarea, [onclick], [role="button"], [role="link"]';
+      const SKIP_TAGS = new Set([
+        'script', 'style', 'noscript', 'template', 'meta', 'link', 'br', 'wbr', 'head', 'title'
+      ]);
+      const MEDIA_TAGS = new Set(['img', 'source', 'video', 'iframe', 'audio', 'embed']);
+      const records = [];
+
+      const normalizeTextInPage = (value, maxLength = 240) => String(value || '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maxLength);
+
+      const normalizeHref = (value) => {
+        const raw = String(value || '').trim();
+        if (!raw) return '';
+        try {
+          const resolved = new URL(raw, location.href);
+          resolved.hash = '';
+          const href = resolved.href;
+          return href.endsWith('/') && href !== `${resolved.origin}/`
+            ? href.slice(0, -1)
+            : href;
+        } catch {
+          return raw;
+        }
+      };
+
+      const buildPath = (el, useNthOfType) => {
+        if (!el || !el.tagName) return '';
+        const parts = [];
+        let current = el;
+        while (current && current.tagName && current.tagName.toLowerCase() !== 'body') {
+          const parent = current.parentElement;
+          if (!parent || parent.tagName.toLowerCase() === 'html') break;
+          const tag = current.tagName.toLowerCase();
+          const siblings = Array.from(parent.children).filter((child) => {
+            if (!(child instanceof Element)) return false;
+            return useNthOfType ? child.tagName.toLowerCase() === tag : true;
+          });
+          const index = siblings.indexOf(current) + 1;
+          const suffix = useNthOfType
+            ? `:nth-of-type(${index})`
+            : `:nth-child(${index})`;
+          parts.unshift(`${tag}${suffix}`);
+          current = parent;
+        }
+        if (parts.length === 0) return '';
+        return `body > ${parts.join(' > ')}`;
+      };
+
+      const pageWidth = Math.max(
+        document.documentElement?.scrollWidth || 0,
+        document.body?.scrollWidth || 0
+      );
+      const pageHeight = Math.max(
+        document.documentElement?.scrollHeight || 0,
+        document.body?.scrollHeight || 0
+      );
+
+      for (const element of document.querySelectorAll('body *')) {
+        if (!(element instanceof Element)) continue;
+        const tag = element.tagName.toLowerCase();
+        if (SKIP_TAGS.has(tag)) continue;
+
+        const style = getComputedStyle(element);
+        if (style.display === 'none') continue;
+        if (style.visibility === 'hidden' || style.visibility === 'collapse') continue;
+        if (parseFloat(style.opacity) === 0) continue;
+
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) continue;
+        if (!(rect.width > minSizePx || rect.height > minSizePx)) continue;
+
+        const top = rect.top + window.scrollY;
+        const left = rect.left + window.scrollX;
+        // Skip elements positioned fully outside the document (e.g. a11y skip-links at top:-17000)
+        if (top + rect.height <= 0 || left + rect.width <= 0) continue;
+        if (pageHeight > 0 && top >= pageHeight) continue;
+        if (pageWidth > 0 && left >= pageWidth) continue;
+
+        let imageAlt = '';
+        if (tag === 'img') {
+          imageAlt = normalizeTextInPage(element.getAttribute('alt') || '', 240);
+        } else {
+          const childImg = element.querySelector(':scope > img');
+          if (childImg) {
+            imageAlt = normalizeTextInPage(childImg.getAttribute('alt') || '', 240);
+          }
+        }
+
+        let src = '';
+        if (MEDIA_TAGS.has(tag)) {
+          src = normalizeHref(element.getAttribute('src') || element.currentSrc || '');
+        }
+
+        const role = element.getAttribute('role') || '';
+        const roleLower = role.toLowerCase();
+
+        records.push({
+          tag,
+          text: normalizeTextInPage(element.innerText || element.textContent || ''),
+          href: normalizeHref(
+            element.getAttribute('href')
+            || element.getAttribute('action')
+            || element.getAttribute('formaction')
+            || ''
+          ),
+          src,
+          width: rect.width,
+          height: rect.height,
+          top,
+          left,
+          cssSelector: buildPath(element, true),
+          id: element.id || '',
+          class: normalizeTextInPage(element.getAttribute('class') || '', 240),
+          role,
+          ariaLabel: normalizeTextInPage(element.getAttribute('aria-label') || '', 120),
+          imageAlt,
+          interactive: element.matches(INTERACTIVE_SELECTOR)
+            || element.hasAttribute('onclick')
+            || roleLower === 'button'
+            || roleLower === 'link'
+        });
+      }
+
+      return records;
+    }, minSize);
+
+    console.log(`[page-analyzer] Collected ${records.length} sized elements (width or height > ${minSize}px)`);
+    return records;
+  }
+
   async collectPageSize(page) {
     return page.evaluate(() => {
       const html = document.documentElement;
@@ -572,16 +762,16 @@ export class PageExtractor {
       await fs.mkdir(this.config.snapshotDir, { recursive: true });
     }
 
-    const prefix = `${createSnapshotSlug(targetUrl)}-${createSnapshotRunId()}`;
+    const localPrefix = `${createSnapshotSlug(targetUrl)}-${createSnapshotRunId()}`;
     const screenshots = {};
 
     if (fullPageScreenshot) {
-      const fullPageFilename = `${prefix}-full-page.png`;
       try {
         if (useS3) {
           const body = await page.screenshot({ fullPage: true });
-          screenshots.fullPage = await this.uploadScreenshotToS3(fullPageFilename, body);
+          screenshots.fullPage = await this.uploadScreenshotToS3(targetUrl, body);
         } else {
+          const fullPageFilename = `${localPrefix}-full-page.png`;
           const fullPagePath = path.join(this.config.snapshotDir, fullPageFilename);
           await page.screenshot({
             path: fullPagePath,
@@ -603,15 +793,13 @@ export class PageExtractor {
         const block = blocks[index];
         const blockIdx = getBlockNumber(block, index);
 
-        const blockLabel = String(blockIdx).padStart(3, '0').replace(/[^0-9a-z-]+/gi, '-');
-        const blockFilename = `${prefix}-block-${blockLabel}.png`;
         try {
           if (useS3) {
             const body = await this.captureBlockScreenshotData(page, block);
             if (!body) {
               continue;
             }
-            const url = await this.uploadScreenshotToS3(blockFilename, body);
+            const url = await this.uploadScreenshotToS3(targetUrl, body);
             const screenshotRecord = {
               blockIdx,
               path: url
@@ -626,6 +814,8 @@ export class PageExtractor {
             continue;
           }
 
+          const blockLabel = String(blockIdx).padStart(3, '0').replace(/[^0-9a-z-]+/gi, '-');
+          const blockFilename = `${localPrefix}-block-${blockLabel}.png`;
           const blockPath = path.join(this.config.snapshotDir, blockFilename);
           const captured = await this.captureBlockScreenshot(page, block, blockPath);
           if (captured) {
@@ -696,11 +886,11 @@ export class PageExtractor {
 
   /**
    * Extract page data from an already prepared Playwright page:
-   * html, blocks, elementGeometries, screenshots.
+   * html, blocks, elementGeometries, sizedElements, screenshots.
    * When config.s3 is provided, screenshots are uploaded to S3 and returned as URLs.
    * @param {import('playwright').Page} page - Prepared Playwright page
    * @param {string} targetUrl - URL loaded in the page
-   * @returns {Promise<{html, blocks, elementGeometries, screenshots, pageSize}>}
+   * @returns {Promise<{html, blocks, elementGeometries, sizedElements, screenshots, pageSize}>}
    */
   async extractPreparedPage(page, targetUrl) {
     const viewport = {
@@ -721,17 +911,20 @@ export class PageExtractor {
     });
     const blocks = Array.isArray(blocksResult?.blocks) ? blocksResult.blocks : [];
     const elementGeometries = await this.collectElementGeometries(page);
+    const sizedElements = this.config.sizedElementsEnabled
+      ? await this.collectSizedElements(page)
+      : [];
     const finalPageSize = await this.collectPageSize(page);
     const screenshots = await this.captureScreenshots(page, targetUrl, blocks);
 
-    return { html, blocks, elementGeometries, screenshots, pageSize: finalPageSize };
+    return { html, blocks, elementGeometries, sizedElements, screenshots, pageSize: finalPageSize };
   }
 
   /**
-   * Extract page data: html, blocks, elementGeometries, screenshots.
+   * Extract page data: html, blocks, elementGeometries, sizedElements, screenshots.
    * When config.s3 is provided, screenshots are uploaded to S3 and returned as URLs.
    * @param {string} url - URL to extract
-   * @returns {Promise<{html, blocks, elementGeometries, screenshots, pageSize}>}
+   * @returns {Promise<{html, blocks, elementGeometries, sizedElements, screenshots, pageSize}>}
    */
   async extract(url) {
     return this.withPreparedPage(url, async (page, targetUrl) => {

package/scripts/analyze.js

@@ -33,14 +33,19 @@ loadDotEnv(path.join(projectRoot, '.env'));
 
 const url = process.argv[2] || 'https://www.jcb.co.jp/ordercard/kojin_card/os_card_w2.html';
 
+const llmType = (process.env.LLM_TYPE || 'openai').toLowerCase();
+const llmConfig = { type: llmType, model: process.env.LLM_MODEL };
+if (llmType === 'openai') {
+  llmConfig.apiKey = process.env.LLM_API_KEY;
+  llmConfig.apiEndpoint = process.env.LLM_API_ENDPOINT;
+}
+
 const result = await analyzeUrl(url, {
   fullPageScreenshot: true,
   blockScreenshots: true,
-  llm: {
-    apiKey: process.env.LLM_API_KEY,
-    apiEndpoint: process.env.LLM_API_ENDPOINT,
-    model: process.env.LLM_MODEL
-  }
+  showElement: true,
+  elementSize: 24,
+  llm: llmConfig
 });
 
 fs.writeFileSync(