@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-replatform/resources/rp-source-wordpress/scripts/wp-discovery.js

@@ -0,0 +1,774 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { createProgressLogger, parseProgressArgs } = require('../../../lib/progress-log.js');
+
+// Transport, auth, throttling, and pagination-header parsing live in the shared
+// adapter lib so the bulk-extract reader generated by rp-import-codegen inherits
+// the exact same discipline instead of re-deriving it.
+const {
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_RATE_LIMIT_RPM,
+  DEFAULT_MAX_RETRIES,
+  configureRateLimit,
+  buildHeaders,
+  normalizeBaseUrl,
+  fetchJson,
+  parseTotalHeader,
+} = require('../lib/wp-http.js');
+const { classifyRoutes, summarizeSkippedByCategory } = require('../lib/wp-route-classifier.js');
+
+const DEFAULT_SAMPLE_LIMIT = 3;
+let progress;
+
+function printUsage() {
+  console.log(`Usage:
+  node wp-discovery.js --base-url <url> --out-dir <dir> [auth options]
+
+Required:
+  --base-url <url>              WordPress site base URL, e.g. https://example.com
+  --out-dir <dir>               Directory to write discovery markdown files into
+
+Authentication options:
+  --username <name>             WordPress username for Application Password auth
+  --application-password <pw>   WordPress Application Password
+  --api-key <token>             API key/token for custom auth setups
+  --api-key-header <name>       Header name for --api-key. Defaults to Authorization
+  --auth-header <'Name: Value'> Add a raw HTTP header. Can be repeated.
+
+Optional:
+  --sample-limit <n>            Number of sample records per entity. Default: 3
+  --timeout-ms <n>              Request timeout in ms. Default: 60000
+  --rate-limit-rpm <n>          Max requests per minute. Default: 120
+  --max-retries <n>             Retries on 429/503 (honors Retry-After). Default: 3
+  --commerce-mode <mode>        WooCommerce read mode: public | authenticated.
+                                Defaults to public without auth, otherwise authenticated.
+  --include-namespace <ns>      Only inspect a namespace. Can be repeated.
+  --include-route <path>        Force-sample a route. Can be repeated.
+  --include-excluded-category <category>
+                                Force-sample an excluded category. Can be repeated.
+  --exclude-route <path>        Skip a route even if otherwise sampled. Can be repeated.
+  --override-reason <text>      Reason recorded for include/exclude overrides.
+  --progress-log <path>         Append progress NDJSON records to this file.
+  --help                        Show this help text
+
+Examples:
+  node wp-discovery.js \
+    --base-url https://example.com \
+    --out-dir migrations/acme/data/wp-discovery \
+    --username admin \
+    --application-password 'abcd efgh ijkl mnop'
+
+  node wp-discovery.js \
+    --base-url https://example.com \
+    --out-dir migrations/acme/data/wp-discovery \
+    --api-key $WP_API_KEY \
+    --api-key-header X-API-Key
+`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    authHeaders: [],
+    includeNamespaces: [],
+    includeRoutes: [],
+    includeExcludedCategories: [],
+    excludeRoutes: [],
+    overrideReason: null,
+    sampleLimit: DEFAULT_SAMPLE_LIMIT,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+    rateLimitRpm: DEFAULT_RATE_LIMIT_RPM,
+    maxRetries: DEFAULT_MAX_RETRIES,
+    commerceMode: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    switch (arg) {
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+      case '--base-url':
+        args.baseUrl = next;
+        i += 1;
+        break;
+      case '--out-dir':
+        args.outDir = next;
+        i += 1;
+        break;
+      case '--username':
+        args.username = next;
+        i += 1;
+        break;
+      case '--application-password':
+        args.applicationPassword = next;
+        i += 1;
+        break;
+      case '--api-key':
+        args.apiKey = next;
+        i += 1;
+        break;
+      case '--api-key-header':
+        args.apiKeyHeader = next;
+        i += 1;
+        break;
+      case '--auth-header':
+        args.authHeaders.push(next);
+        i += 1;
+        break;
+      case '--sample-limit':
+        args.sampleLimit = Number.parseInt(next, 10);
+        i += 1;
+        break;
+      case '--timeout-ms':
+        args.timeoutMs = Number.parseInt(next, 10);
+        i += 1;
+        break;
+      case '--rate-limit-rpm':
+        args.rateLimitRpm = Number.parseInt(next, 10);
+        i += 1;
+        break;
+      case '--max-retries':
+        args.maxRetries = Number.parseInt(next, 10);
+        i += 1;
+        break;
+      case '--commerce-mode':
+        args.commerceMode = next;
+        i += 1;
+        break;
+      case '--include-namespace':
+        args.includeNamespaces.push(next);
+        i += 1;
+        break;
+      case '--include-route':
+        args.includeRoutes.push(next);
+        i += 1;
+        break;
+      case '--include-excluded-category':
+        args.includeExcludedCategories.push(next);
+        i += 1;
+        break;
+      case '--exclude-route':
+        args.excludeRoutes.push(next);
+        i += 1;
+        break;
+      case '--override-reason':
+        args.overrideReason = next;
+        i += 1;
+        break;
+      default:
+        if (arg.startsWith('--')) {
+          throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+  }
+
+  if (!args.baseUrl) {
+    args.baseUrl = process.env.WP_BASE_URL || process.env.WP_SITE_URL;
+  }
+  if (!args.outDir) {
+    args.outDir = process.env.WP_DISCOVERY_OUT_DIR;
+  }
+  if (!args.apiKey) {
+    args.apiKey = process.env.WP_API_KEY;
+  }
+  if (!args.apiKeyHeader) {
+    args.apiKeyHeader = process.env.WP_API_KEY_HEADER;
+  }
+  if (!args.username) {
+    args.username = process.env.WP_USERNAME;
+  }
+  if (!args.applicationPassword) {
+    args.applicationPassword = process.env.WP_APPLICATION_PASSWORD;
+  }
+  if (args.authHeaders.length === 0 && process.env.WP_AUTH_HEADER) {
+    args.authHeaders.push(process.env.WP_AUTH_HEADER);
+  }
+
+  if (!Number.isFinite(args.sampleLimit) || args.sampleLimit < 1) {
+    args.sampleLimit = DEFAULT_SAMPLE_LIMIT;
+  }
+  if (!Number.isFinite(args.timeoutMs) || args.timeoutMs < 1000) {
+    args.timeoutMs = DEFAULT_TIMEOUT_MS;
+  }
+  if (!Number.isFinite(args.rateLimitRpm) || args.rateLimitRpm < 1) {
+    args.rateLimitRpm = DEFAULT_RATE_LIMIT_RPM;
+  }
+  if (!Number.isFinite(args.maxRetries) || args.maxRetries < 0) {
+    args.maxRetries = DEFAULT_MAX_RETRIES;
+  }
+  if (args.commerceMode !== 'public' && args.commerceMode !== 'authenticated') {
+    args.commerceMode = (args.username && args.applicationPassword) || args.apiKey || args.authHeaders.length > 0
+      ? 'authenticated'
+      : 'public';
+  }
+
+  return args;
+}
+
+function endpointMethods(endpoint) {
+  const raw = endpoint?.methods;
+  if (Array.isArray(raw)) {
+    return raw.map(String);
+  }
+  if (typeof raw === 'string') {
+    return raw.split(',').map((value) => value.trim()).filter(Boolean);
+  }
+  if (raw && typeof raw === 'object') {
+    return Object.keys(raw);
+  }
+  return [];
+}
+
+function routeSegments(routePath) {
+  return routePath.split('/').filter(Boolean);
+}
+
+function summarizeRelationships(record) {
+  const links = record?._links;
+  if (!links || typeof links !== 'object') {
+    return [];
+  }
+  // HAL housekeeping rels carry no entity relationship signal.
+  const ignored = new Set(['self', 'collection', 'about', 'curies']);
+  const relationships = [];
+
+  for (const [rel, entries] of Object.entries(links)) {
+    if (ignored.has(rel)) {
+      continue;
+    }
+    const list = Array.isArray(entries) ? entries : [entries];
+    const hrefs = list.map((entry) => entry?.href).filter(Boolean);
+    if (hrefs.length === 0) {
+      continue;
+    }
+    relationships.push({
+      rel,
+      embeddable: list.some((entry) => entry?.embeddable === true),
+      hrefs,
+    });
+  }
+
+  return relationships;
+}
+
+function isParameterizedRoute(routePath) {
+  return routePath.includes('(?P<');
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'entity';
+}
+
+function summarizeAuthMode(args) {
+  if (args.username && args.applicationPassword) {
+    return 'basic-application-password';
+  }
+  if (args.apiKey) {
+    return `api-key:${args.apiKeyHeader || 'Authorization'}`;
+  }
+  if (args.authHeaders.length > 0) {
+    return 'custom-header';
+  }
+  return 'none';
+}
+
+function summarizeOverrides(args) {
+  return {
+    includeRoutes: args.includeRoutes,
+    includeNamespaces: args.includeNamespaces,
+    includeExcludedCategories: args.includeExcludedCategories,
+    excludeRoutes: args.excludeRoutes,
+    overrideReason: args.overrideReason,
+    commerceMode: args.commerceMode,
+  };
+}
+
+function deriveEntityCandidates(indexJson, includeNamespaces) {
+  const routes = indexJson?.routes || {};
+  const candidates = [];
+
+  for (const [routePath, routeDefinition] of Object.entries(routes)) {
+    if (!routePath.startsWith('/') || routePath === '/' || isParameterizedRoute(routePath)) {
+      continue;
+    }
+
+    const segments = routeSegments(routePath);
+    if (segments.length < 2) {
+      continue;
+    }
+
+    const namespace = segments.slice(0, 2).join('/');
+    if (includeNamespaces.length > 0 && !includeNamespaces.includes(namespace)) {
+      continue;
+    }
+
+    const endpoints = Array.isArray(routeDefinition?.endpoints) ? routeDefinition.endpoints : [];
+    const getEndpoint = endpoints.find((endpoint) => endpointMethods(endpoint).includes('GET'));
+    if (!getEndpoint) {
+      continue;
+    }
+
+    const entityName = segments[segments.length - 1];
+    const supportsPagination = Boolean(getEndpoint?.args?.page || getEndpoint?.args?.per_page);
+    const hasSchema = Boolean(getEndpoint?.schema || routeDefinition?.schema);
+
+    if (!hasSchema && !supportsPagination && segments.length < 3) {
+      continue;
+    }
+
+    // Derive the file name from the full path after the namespace so distinct
+    // routes that share a last segment (e.g. /wp/v2/categories vs.
+    // /wp/v2/block-patterns/categories) do not collide onto one file.
+    const pathSlug = slugify(segments.slice(2).join('-')) || slugify(entityName);
+
+    candidates.push({
+      entityName,
+      namespace,
+      routePath,
+      endpoints,
+      getEndpoint,
+      routeDefinition,
+      supportsPagination,
+      fileName: `${slugify(namespace)}--${pathSlug}.md`,
+    });
+  }
+
+  const unique = new Map();
+  for (const candidate of candidates) {
+    const key = `${candidate.namespace}:${candidate.routePath}`;
+    if (!unique.has(key)) {
+      unique.set(key, candidate);
+    }
+  }
+
+  return [...unique.values()].sort((a, b) => a.routePath.localeCompare(b.routePath));
+}
+
+async function inspectEntity(baseUrl, headers, candidate, options) {
+  const details = {
+    entityName: candidate.entityName,
+    namespace: candidate.namespace,
+    routePath: candidate.routePath,
+    fileName: candidate.fileName,
+    classification: candidate.classification || null,
+    methods: [...new Set(candidate.endpoints.flatMap(endpointMethods))].sort(),
+    supportsPagination: candidate.supportsPagination,
+    discoveryNotes: [],
+    requestErrors: [],
+    collectionArgs: candidate.getEndpoint?.args || null,
+    schema: candidate.getEndpoint?.schema || candidate.routeDefinition?.schema || null,
+    optionsSchema: null,
+    sampleRecords: [],
+    sampleRecordCount: 0,
+    recordCount: null,
+    inUse: null,
+    relationships: [],
+    responseShape: 'unknown',
+  };
+
+  const optionsResponse = await fetchJson(baseUrl, candidate.routePath, {
+    headers,
+    method: 'OPTIONS',
+    timeoutMs: options.timeoutMs,
+    progress: options.progress,
+    progressContext: {
+      step: 'inspect-endpoint',
+      entity: candidate.routePath,
+    },
+  });
+
+  if (optionsResponse.ok && optionsResponse.json) {
+    const optionEndpoints = Array.isArray(optionsResponse.json?.endpoints) ? optionsResponse.json.endpoints : [];
+    const getEndpoint = optionEndpoints.find((endpoint) => endpointMethods(endpoint).includes('GET'));
+    if (getEndpoint?.args) {
+      details.collectionArgs = getEndpoint.args;
+    }
+    if (optionsResponse.json?.schema) {
+      details.optionsSchema = optionsResponse.json.schema;
+      details.schema = optionsResponse.json.schema;
+    } else if (getEndpoint?.schema) {
+      details.optionsSchema = getEndpoint.schema;
+      details.schema = getEndpoint.schema;
+    }
+  } else if (optionsResponse.status !== 404 && optionsResponse.status !== 405) {
+    details.requestErrors.push({
+      request: 'OPTIONS',
+      routePath: candidate.routePath,
+      status: optionsResponse.status,
+      statusText: optionsResponse.statusText,
+      url: optionsResponse.url,
+    });
+  }
+
+  const query = candidate.supportsPagination ? { per_page: options.sampleLimit } : {};
+  const sampleResponse = await fetchJson(baseUrl, candidate.routePath, {
+    headers,
+    method: 'GET',
+    query,
+    timeoutMs: options.timeoutMs,
+    progress: options.progress,
+    progressContext: {
+      step: 'inspect-endpoint',
+      entity: candidate.routePath,
+    },
+  });
+
+  if (sampleResponse.ok) {
+    const payload = sampleResponse.json;
+    const totalFromHeader = parseTotalHeader(sampleResponse.headers);
+    if (Array.isArray(payload)) {
+      details.responseShape = 'array';
+      details.sampleRecords = payload.slice(0, options.sampleLimit);
+      details.sampleRecordCount = payload.length;
+      details.recordCount = totalFromHeader !== null ? totalFromHeader : payload.length;
+      details.inUse = details.recordCount > 0;
+      if (totalFromHeader === null) {
+        details.discoveryNotes.push('No X-WP-Total header returned; recordCount reflects only the sampled page and may undercount the true total.');
+      }
+      if (candidate.routePath.startsWith('/wc/store/v1/') && !Object.keys(sampleResponse.headers || {}).some((key) => key.toLowerCase() === 'x-wp-totalpages')) {
+        details.discoveryNotes.push('WooCommerce Store API route does not advertise X-WP-TotalPages; generated readers must stop on a short page when bulk-extracting this entity.');
+      }
+      if (payload.length === 0) {
+        details.discoveryNotes.push('Endpoint returned an empty array. The entity is advertised but appears unused (no records).');
+      }
+    } else if (payload && typeof payload === 'object') {
+      details.responseShape = 'object';
+      details.sampleRecords = [payload];
+      details.sampleRecordCount = 1;
+      details.recordCount = totalFromHeader !== null ? totalFromHeader : 1;
+      details.inUse = details.recordCount > 0;
+    } else {
+      details.responseShape = typeof payload;
+      details.discoveryNotes.push(`Endpoint returned a non-object payload of type ${typeof payload}.`);
+    }
+
+    const firstRecord = details.sampleRecords[0];
+    if (firstRecord && typeof firstRecord === 'object') {
+      details.relationships = summarizeRelationships(firstRecord);
+    }
+  } else {
+    details.requestErrors.push({
+      request: 'GET',
+      routePath: candidate.routePath,
+      status: sampleResponse.status,
+      statusText: sampleResponse.statusText,
+      url: sampleResponse.url,
+      body: sampleResponse.text ? sampleResponse.text.slice(0, 1000) : '',
+    });
+  }
+
+  return details;
+}
+
+function markdownJsonBlock(value) {
+  if (value === null || value === undefined) {
+    return '\n\n`Unavailable`';
+  }
+
+  return `\n\n\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}
+
+function renderEntityFile(details) {
+  const errorLines = details.requestErrors.length > 0
+    ? details.requestErrors.map((error) => `- ${error.request} ${error.routePath}: ${error.status} ${error.statusText}`).join('\n')
+    : '- None';
+
+  const notes = details.discoveryNotes.length > 0
+    ? details.discoveryNotes.map((note) => `- ${note}`).join('\n')
+    : '- None';
+
+  const relationshipLines = details.relationships.length > 0
+    ? details.relationships
+      .map((relationship) => `- \`${relationship.rel}\`${relationship.embeddable ? ' (embeddable)' : ''} → ${relationship.hrefs.join(', ')}`)
+      .join('\n')
+    : '- None detected (no `_links` in sample record)';
+
+  const recordCountLabel = details.recordCount === null ? 'unknown' : String(details.recordCount);
+  const inUseLabel = details.inUse === null ? 'unknown' : details.inUse ? 'yes' : 'no (advertised but empty)';
+  const classificationLines = details.classification
+    ? `- Discovery category: \`${details.classification.category}\`\n` +
+      `- Discovery rule: \`${details.classification.ruleId}\`\n` +
+      `- Discovery reason: ${details.classification.reason}\n` +
+      `- Included by override: \`${details.classification.includedByOverride ? 'yes' : 'no'}\`\n` +
+      `- Excluded by override: \`${details.classification.excludedByOverride ? 'yes' : 'no'}\`\n`
+    : '';
+
+  return `# ${details.entityName}\n\n` +
+    `- Namespace: \`${details.namespace}\`\n` +
+    `- Route: \`${details.routePath}\`\n` +
+    classificationLines +
+    `- Methods: ${details.methods.map((method) => `\`${method}\``).join(', ') || '`unknown`'}\n` +
+    `- Response shape: \`${details.responseShape}\`\n` +
+    `- Record count: \`${recordCountLabel}\`\n` +
+    `- In use: \`${inUseLabel}\`\n` +
+    `- Sample records captured: ${details.sampleRecords.length}\n\n` +
+    `## Notes\n${notes}\n\n` +
+    `## Relationships\n${relationshipLines}\n\n` +
+    `## Request Errors\n${errorLines}\n\n` +
+    `## Schema${markdownJsonBlock(details.schema)}\n\n` +
+    `## Collection Args${markdownJsonBlock(details.collectionArgs)}\n\n` +
+    `## Sample Records${markdownJsonBlock(details.sampleRecords)}\n`;
+}
+
+function renderIndexFile(context) {
+  const entityRows = context.entities.map((entity) => {
+    const status = entity.requestErrors.length > 0 ? 'partial' : 'ok';
+    const recordCountLabel = entity.recordCount === null ? '?' : String(entity.recordCount);
+    const inUseLabel = entity.inUse === null ? '?' : entity.inUse ? 'yes' : 'no';
+    return `| ${entity.entityName} | \`${entity.namespace}\` | \`${entity.routePath}\` | ${recordCountLabel} | ${inUseLabel} | ${entity.sampleRecords.length} | ${status} | [${entity.fileName}](./${entity.fileName}) |`;
+  }).join('\n');
+
+  const errorLines = context.entities
+    .flatMap((entity) => entity.requestErrors.map((error) => `- ${entity.entityName}: ${error.request} ${error.routePath} -> ${error.status} ${error.statusText}`));
+  const skippedByCategoryLines = Object.entries(context.skippedByCategory || {})
+    .map(([category, count]) => `- \`${category}\`: ${count}`)
+    .join('\n') || '- None';
+  const overrideLines = [
+    `- Include routes: ${context.overrides.includeRoutes.map((route) => `\`${route}\``).join(', ') || '`none`'}`,
+    `- Include namespaces: ${context.overrides.includeNamespaces.map((namespace) => `\`${namespace}\``).join(', ') || '`none`'}`,
+    `- Include excluded categories: ${context.overrides.includeExcludedCategories.map((category) => `\`${category}\``).join(', ') || '`none`'}`,
+    `- Exclude routes: ${context.overrides.excludeRoutes.map((route) => `\`${route}\``).join(', ') || '`none`'}`,
+    `- Override reason: ${context.overrides.overrideReason ? context.overrides.overrideReason : '`none`'}`,
+  ].join('\n');
+
+  const authGatedEntities = context.entities.filter((entity) =>
+    entity.requestErrors.some((error) => error.status === 401 || error.status === 403));
+  const authWarning = authGatedEntities.length > 0
+    ? `## ⚠️ Incomplete Capture (Authentication)\n\n` +
+      `${authGatedEntities.length} entit${authGatedEntities.length === 1 ? 'y' : 'ies'} returned 401/403 and ` +
+      `could not be captured` +
+      `${context.authMode === 'none' ? ' — this run used **no credentials**' : ` with auth mode \`${context.authMode}\` (insufficient scope)`}.\n` +
+      `Their \`recordCount\`/\`inUse\` are unreliable: an auth-gated entity can look empty or errored even when the site uses it heavily (e.g. WooCommerce orders/customers, drafts, private fields).\n` +
+      `Re-run with credentials for a complete and trustworthy capture.\n\n` +
+      `Auth-gated entities: ${authGatedEntities.map((entity) => `\`${entity.entityName}\``).join(', ')}\n\n`
+    : '';
+
+  return `# WordPress Discovery\n\n` +
+    `- Generated at: \`${context.generatedAt}\`\n` +
+    `- Base URL: \`${context.baseUrl}\`\n` +
+    `- REST root: \`${context.restRoot}\`\n` +
+    `- Auth mode: \`${context.authMode}\`\n` +
+    `- Advertised auth providers: ${context.authProviders.map((provider) => `\`${provider}\``).join(', ') || '`none`'}\n` +
+    `- Namespaces advertised: ${context.namespaces.map((namespace) => `\`${namespace}\``).join(', ') || '`none`'}\n` +
+    `- Advertised routes: ${context.totalAdvertisedRoutes}\n` +
+    `- Candidate routes after generic filtering: ${context.totalCandidateRoutes}\n` +
+    `- Sampled backend data/metadata routes: ${context.sampledRoutes}\n` +
+    `- Skipped routes: ${context.skippedRoutes}\n` +
+    `- Entities documented: ${context.entities.length}\n\n` +
+    authWarning +
+    `## Route Scope\n\n` +
+    `### Skipped Routes by Category\n\n${skippedByCategoryLines}\n\n` +
+    `### Overrides\n\n${overrideLines}\n\n` +
+    `Skipped route evidence: [skipped-routes.json](./skipped-routes.json)\n\n` +
+    `## Discovery Summary\n\n` +
+    `| Entity | Namespace | Route | Records | In use | Samples | Status | File |\n` +
+    `| --- | --- | --- | ---: | --- | ---: | --- | --- |\n` +
+    `${entityRows || '| None | - | - | - | - | 0 | - | - |'}\n\n` +
+    `## Route Index Sample${markdownJsonBlock(context.routeIndexSample)}\n\n` +
+    `## Errors\n${errorLines.length > 0 ? errorLines.join('\n') : '- None'}\n`;
+}
+
+function skippedRoutesPayload(context) {
+  return {
+    generatedAt: context.generatedAt,
+    totalAdvertisedRoutes: context.totalAdvertisedRoutes,
+    totalCandidateRoutes: context.totalCandidateRoutes,
+    sampledRoutes: context.sampledRoutes,
+    skippedRoutes: context.skippedRoutes,
+    overrides: context.overrides,
+    routes: context.classifications
+      .filter((classification) => classification.effectiveAction === 'skip')
+      .map((classification) => ({
+        routePath: classification.routePath,
+        namespace: classification.namespace,
+        category: classification.category,
+        reason: classification.reason,
+        ruleId: classification.ruleId,
+        sampleByDefault: classification.sampleByDefault,
+        canIncludeByOverride: classification.canIncludeByOverride,
+        includedByOverride: classification.includedByOverride,
+        excludedByOverride: classification.excludedByOverride,
+        effectiveAction: classification.effectiveAction,
+        duplicateOf: classification.duplicateOf,
+        overrideReason: classification.overrideReason,
+      })),
+  };
+}
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function writeOutputs(outDir, context, progress) {
+  await ensureDir(outDir);
+  await fs.writeFile(path.join(outDir, 'README.md'), renderIndexFile(context), 'utf8');
+  progress?.progress('Wrote WordPress discovery index', { phase: 'discovery', step: 'write-artifact', artifact: path.join(outDir, 'README.md') });
+  await fs.writeFile(
+    path.join(outDir, 'skipped-routes.json'),
+    `${JSON.stringify(skippedRoutesPayload(context), null, 2)}\n`,
+    'utf8',
+  );
+  progress?.progress('Wrote WordPress skipped-route index', {
+    phase: 'discovery',
+    step: 'write-artifact',
+    artifact: path.join(outDir, 'skipped-routes.json'),
+  });
+
+  for (const entity of context.entities) {
+    await fs.writeFile(path.join(outDir, entity.fileName), renderEntityFile(entity), 'utf8');
+    progress?.progress(`Wrote WordPress discovery artifact for ${entity.entityName}`, {
+      phase: 'discovery',
+      step: 'write-artifact',
+      entity: entity.routePath,
+      artifact: path.join(outDir, entity.fileName),
+    });
+  }
+}
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  progress = createProgressLogger({
+    script: 'skills/replatform/resources/rp-source-wordpress/scripts/wp-discovery.js',
+    ...parsed.progress,
+  });
+  progress.start('WordPress discovery started', { phase: 'discovery' });
+
+  const args = parseArgs(parsed.args);
+  if (args.help) {
+    printUsage();
+    progress.complete('WordPress discovery help shown', { phase: 'discovery', step: 'help' });
+    return;
+  }
+
+  if (!args.baseUrl || !args.outDir) {
+    printUsage();
+    progress.error('Missing required WordPress discovery arguments', { phase: 'discovery' });
+    throw new Error('Missing required arguments: --base-url and --out-dir are required.');
+  }
+
+  configureRateLimit({ rateLimitRpm: args.rateLimitRpm, maxRetries: args.maxRetries });
+
+  const headers = buildHeaders(args);
+  const rootResponse = await fetchJson(args.baseUrl, '', {
+    headers,
+    method: 'GET',
+    timeoutMs: args.timeoutMs,
+    progress,
+    progressContext: { step: 'rest-index' },
+  });
+
+  if (!rootResponse.ok || !rootResponse.json) {
+    throw new Error(`Failed to fetch WordPress REST index from ${rootResponse.url}: ${rootResponse.status} ${rootResponse.statusText}`);
+  }
+
+  const indexJson = rootResponse.json;
+  const namespaces = Array.isArray(indexJson?.namespaces) ? indexJson.namespaces : [];
+  progress.progress('WordPress namespace enumeration completed', {
+    phase: 'discovery',
+    step: 'namespace-enumeration',
+    count: namespaces.length,
+    unit: 'namespaces',
+  });
+  const candidates = deriveEntityCandidates(indexJson, args.includeNamespaces);
+  progress.progress('WordPress endpoint candidates derived', {
+    phase: 'discovery',
+    step: 'derive-endpoints',
+    count: candidates.length,
+    unit: 'endpoints',
+  });
+  const classifications = classifyRoutes(candidates, summarizeOverrides(args));
+  const candidatesByRoute = new Map(candidates.map((candidate) => [candidate.routePath, candidate]));
+  const candidatesToInspect = classifications
+    .filter((classification) => ['sample', 'metadata'].includes(classification.effectiveAction))
+    .map((classification) => ({
+      ...candidatesByRoute.get(classification.routePath),
+      classification,
+    }));
+  const skippedByCategory = summarizeSkippedByCategory(classifications);
+  const skippedRoutes = classifications.filter((classification) => classification.effectiveAction === 'skip').length;
+  progress.progress('WordPress endpoint candidates classified', {
+    phase: 'discovery',
+    step: 'classify-endpoints',
+    count: candidatesToInspect.length,
+    total: candidates.length,
+    unit: 'endpoints',
+    details: {
+      sampledRoutes: candidatesToInspect.length,
+      skippedRoutes,
+      skippedByCategory,
+    },
+  });
+  const entities = [];
+
+  for (let i = 0; i < candidatesToInspect.length; i += 1) {
+    const candidate = candidatesToInspect[i];
+    progress.progress(`Inspecting WordPress endpoint ${candidate.routePath}`, {
+      phase: 'discovery',
+      step: 'inspect-endpoint',
+      entity: candidate.routePath,
+      count: i + 1,
+      total: candidatesToInspect.length,
+      unit: 'endpoints',
+      percent: candidatesToInspect.length ? Math.round(((i + 1) / candidatesToInspect.length) * 100) : 100,
+    });
+    const details = await inspectEntity(args.baseUrl, headers, candidate, {
+      sampleLimit: args.sampleLimit,
+      timeoutMs: args.timeoutMs,
+      progress,
+    });
+    entities.push(details);
+  }
+
+  const context = {
+    generatedAt: new Date().toISOString(),
+    baseUrl: normalizeBaseUrl(args.baseUrl),
+    restRoot: `${normalizeBaseUrl(args.baseUrl)}/wp-json`,
+    authMode: summarizeAuthMode(args),
+    authProviders: Object.keys(indexJson?.authentication || {}),
+    namespaces,
+    totalAdvertisedRoutes: Object.keys(indexJson?.routes || {}).length,
+    totalCandidateRoutes: candidates.length,
+    sampledRoutes: candidatesToInspect.length,
+    skippedRoutes,
+    skippedByCategory,
+    overrides: summarizeOverrides(args),
+    classifications,
+    routeIndexSample: Object.keys(indexJson?.routes || {}).slice(0, 50),
+    entities,
+  };
+
+  await writeOutputs(args.outDir, context, progress);
+
+  console.log(`Wrote ${entities.length + 1} markdown files and skipped-routes.json to ${args.outDir}`);
+  progress.complete('WordPress discovery completed', {
+    phase: 'discovery',
+    artifact: args.outDir,
+    count: entities.length,
+    unit: 'entities',
+  });
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    if (progress) {
+      progress.error(error && error.message ? error.message : 'WordPress discovery failed', { phase: 'discovery' });
+    }
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  parseArgs,
+  deriveEntityCandidates,
+  renderIndexFile,
+  skippedRoutesPayload,
+};