@pterodoc/wordpress 0.2.0

package/src/index.ts

@@ -0,0 +1,275 @@
+/** The WordPress target. */
+
+import { renderNavigationStub } from '@pterodoc/core/render';
+import type {
+  EnsureRequest,
+  EnsureResult,
+  MediaRef,
+  MediaUpload,
+  RemotePage,
+  RenderedPage,
+  Target,
+  TargetCapabilities,
+  TargetSession,
+} from '@pterodoc/core/target';
+import { TargetError, titleCase } from '@pterodoc/core/util';
+import { DEFAULT_RETRY, WpClient, type RetryPolicy } from './client';
+import { loadMediaIndex, uploadMedia } from './media';
+import {
+  computePrune,
+  createPage,
+  diffPage,
+  fetchPage,
+  fetchPageIndex,
+  findPage,
+  trashPage,
+  updatePage,
+  type PageInput,
+} from './pages';
+import { hrefFor, splitOwnership, type WordpressUrlPolicy } from './url';
+
+/** What WordPress can do. */
+export const WORDPRESS_CAPABILITIES: TargetCapabilities = {
+  // The navigation block lists children of a page id, so ids must exist first.
+  needsIdsBeforeRender: true,
+  supportsMedia: true,
+  supportsPrune: true,
+  supportsHierarchy: true,
+  supportsExcerpt: true,
+  supportsMeta: true,
+  supportsTemplates: true,
+  supportsDrafts: true,
+};
+
+/** Content a page holds between being created and being rendered. */
+const PLACEHOLDER = '<!-- wp:paragraph -->\n<p>Publishing…</p>\n<!-- /wp:paragraph -->';
+
+/** How to reach and shape a WordPress site. */
+export interface WordpressTargetOptions {
+  /** Site origin. */
+  url: string;
+  /** Username of the Application Password. */
+  user: string;
+  /** The Application Password. */
+  appPassword: string;
+  /** Where the tree hangs and how versions and locales are addressed. */
+  policy: WordpressUrlPolicy;
+  /** Status applied to every synced page. */
+  status: 'publish' | 'draft' | 'private';
+  /** Page template slug, or empty for the theme default. */
+  template: string;
+  /** Polylang language code. */
+  lang: string;
+  /** Prefix of the slug that identifies uploaded media. */
+  mediaSlugPrefix: string;
+  /** Send DELETE as POST with an override header. */
+  methodOverride: boolean;
+  /** Retry policy. */
+  retry?: RetryPolicy;
+}
+
+/** Injected so the target can be exercised without a network. */
+export interface WordpressTargetDeps {
+  fetch?: typeof globalThis.fetch;
+  sleep?: (ms: number) => Promise<void>;
+  log?: (message: string) => void;
+}
+
+/** Create the WordPress target. */
+export function createWordpressTarget(
+  options: WordpressTargetOptions,
+  deps: WordpressTargetDeps = {},
+): Target {
+  const log = deps.log ?? ((): void => {});
+  const { stubSegments, rootSlug } = splitOwnership(options.policy);
+
+  // The documentation root has no path of its own in the tree, so its slug is
+  // the last segment of the configured path rather than anything the model
+  // supplied.
+  const slugFor = (page: { path: string; slug: string }): string =>
+    page.path === '' ? rootSlug : page.slug;
+
+  const makeClient = (locale: string): WpClient =>
+    new WpClient({
+      baseUrl: options.url,
+      user: options.user,
+      appPassword: options.appPassword,
+      // A site with one language per subtree wants each subtree tagged.
+      lang: options.lang || (options.policy.primaryLocale && locale !== options.policy.primaryLocale ? locale : ''),
+      methodOverride: options.methodOverride,
+      retry: options.retry ?? DEFAULT_RETRY,
+      ...(deps.fetch ? { fetch: deps.fetch } : {}),
+      ...(deps.sleep ? { sleep: deps.sleep } : {}),
+      log,
+    });
+
+  return {
+    name: 'wordpress',
+    capabilities: WORDPRESS_CAPABILITIES,
+    rootPath: hrefFor(options.policy, '', { versionName: '', locale: options.policy.primaryLocale ?? '' }),
+
+    hrefFor(treePath, context) {
+      return hrefFor(options.policy, treePath, context);
+    },
+
+    async open(context): Promise<TargetSession> {
+      const client = makeClient(context.locale);
+      const dryRun = context.dryRun;
+      let index: RemotePage[] | undefined;
+
+      return {
+        async loadIndex(): Promise<RemotePage[]> {
+          index ??= await fetchPageIndex(client);
+          return index;
+        },
+
+        async ensureRootParent(): Promise<{
+          id: number | null;
+          created: { path: string; id: number | null }[];
+        }> {
+          const created: { path: string; id: number | null }[] = [];
+          let parentId: number | null = 0;
+
+          for (const slug of stubSegments) {
+            if (parentId === null) {
+              created.push({ path: `/${slug}/`, id: null });
+              continue;
+            }
+            const existing = await findPage(client, parentId, slug, index, log);
+            if (existing) {
+              if (existing.status === 'trash') {
+                throw new TargetError(
+                  `The page "/${slug}/" is in the trash. Restore it, or delete it permanently, and run again.`,
+                  { status: 409, method: 'GET', url: `/pages?slug=${slug}` },
+                );
+              }
+              parentId = existing.id;
+              continue;
+            }
+            if (dryRun) {
+              created.push({ path: `/${slug}/`, id: null });
+              parentId = null;
+              continue;
+            }
+            // A page created only so the documentation has a parent: it lists
+            // what is below it and claims nothing else.
+            const page = await createPage(client, {
+              title: titleCase(slug),
+              slug,
+              parent: parentId,
+              status: 'publish',
+              content: PLACEHOLDER,
+            });
+            await updatePage(client, page.id, { content: renderNavigationStub(page.id) });
+            created.push({ path: `/${slug}/`, id: page.id });
+            parentId = page.id;
+          }
+          return { id: parentId, created };
+        },
+
+        async ensurePage(request: EnsureRequest): Promise<EnsureResult> {
+          const warnings: string[] = [];
+          if (request.parentId === null) return { id: null, created: true, warnings };
+
+          const slug = request.isRoot ? rootSlug : request.slug;
+          const existing = await findPage(client, request.parentId, slug, index, log);
+          if (existing) {
+            if (existing.status === 'trash') {
+              warnings.push(
+                `${request.path || '(root)'} matches a page in the trash. It will be republished; restore or delete it permanently if that is not what you want.`,
+              );
+            }
+            return { id: existing.id, created: false, warnings };
+          }
+          if (dryRun) return { id: null, created: true, warnings };
+
+          // Created as a draft: a placeholder must never appear in navigation.
+          const created = await createPage(client, {
+            title: request.title,
+            slug,
+            parent: request.parentId,
+            status: 'draft',
+            menu_order: request.menuOrder,
+            content: PLACEHOLDER,
+          });
+          return { id: created.id, created: true, warnings };
+        },
+
+        async fetchPage(id: number): Promise<RemotePage> {
+          return fetchPage(client, id);
+        },
+
+        diffPage(remote: RemotePage, rendered: RenderedPage, parentId: number): string[] {
+          return diffPage(remote, rendered, {
+            parentId,
+            status: options.status,
+            template: options.template,
+            isRoot: rendered.path === '',
+            slug: slugFor(rendered),
+          });
+        },
+
+        async writePage(id, page, parentId): Promise<{ warnings: string[] }> {
+          const warnings: string[] = [];
+          const body: PageInput = {
+            title: page.title,
+            content: page.content,
+            excerpt: page.excerpt,
+            parent: parentId,
+            slug: slugFor(page),
+            status: options.status,
+            menu_order: page.menuOrder,
+            template: options.template,
+          };
+          if (Object.keys(page.meta).length > 0) body.meta = page.meta;
+
+          try {
+            await updatePage(client, id, body);
+          } catch (error) {
+            // A locked-down site may reject the metadata or the template. The
+            // page itself matters more than either, so try again without them.
+            const status = (error as { status?: number }).status;
+            if (status === 400 && (body.meta || body.template)) {
+              delete body.meta;
+              delete body.template;
+              warnings.push(
+                `${page.path || '(root)'}: WordPress refused the template or the metadata, so the page was published without them.`,
+              );
+              await updatePage(client, id, body);
+            } else throw error;
+          }
+          return { warnings };
+        },
+
+        computePrune(pages, rootId, keepIds): RemotePage[] {
+          return computePrune(pages, rootId, keepIds);
+        },
+
+        async removePage(page: RemotePage): Promise<void> {
+          await trashPage(client, page.id);
+        },
+
+        async loadMediaIndex(): Promise<Map<string, MediaRef>> {
+          return loadMediaIndex(client, options.mediaSlugPrefix);
+        },
+
+        async uploadMedia(upload: MediaUpload): Promise<MediaRef> {
+          return uploadMedia(client, upload, options.mediaSlugPrefix);
+        },
+
+        requestCount(): number {
+          return client.requestCount;
+        },
+      };
+    },
+  };
+}
+
+export { splitOwnership, hrefFor, prefixSegments } from './url';
+export type { WordpressUrlPolicy } from './url';
+export { WpClient, DEFAULT_RETRY } from './client';
+export { detectPlugin } from './plugin';
+export type { PluginStatus } from './plugin';
+export type { RetryPolicy, WpClientOptions } from './client';
+export { renderNavigationStub };
+export { PLACEHOLDER };

package/src/media.ts

@@ -0,0 +1,106 @@
+/**
+ * The WordPress media library.
+ *
+ * A file's identity is the hash of its contents, carried in the media slug.
+ * Keeping the identity on the server rather than in a local cache is what lets
+ * a fresh checkout, or a CI runner that has never seen the site, avoid
+ * uploading everything again.
+ */
+
+import { TargetError, isBlockedByDefault } from '@pterodoc/core/util';
+import type { MediaRef, MediaUpload } from '@pterodoc/core/target';
+import type { WpClient } from './client';
+
+/** WordPress's media shape, narrowed to what is read. */
+interface WpMedia {
+  id: number;
+  slug: string;
+  source_url: string;
+  mime_type: string;
+}
+
+/** The slug that identifies a file uploaded by pterodoc. */
+export function mediaSlug(prefix: string, hash: string): string {
+  return `${prefix}-${hash}`;
+}
+
+/** Read the hash back out of a slug, when the slug is one of ours. */
+export function hashFromSlug(prefix: string, slug: string): string | undefined {
+  const marker = `${prefix}-`;
+  if (!slug.startsWith(marker)) return undefined;
+  const hash = slug.slice(marker.length);
+  return /^[0-9a-f]{16}$/.test(hash) ? hash : undefined;
+}
+
+/**
+ * Everything pterodoc has already uploaded to this site, by content hash.
+ */
+export async function loadMediaIndex(
+  client: WpClient,
+  prefix: string,
+): Promise<Map<string, MediaRef>> {
+  const found = await client.listAll<WpMedia>('/media', {
+    search: `${prefix}-`,
+    _fields: 'id,slug,source_url,mime_type',
+  });
+
+  const byHash = new Map<string, MediaRef>();
+  for (const item of found) {
+    const hash = hashFromSlug(prefix, item.slug);
+    if (!hash || byHash.has(hash)) continue;
+    byHash.set(hash, {
+      id: item.id,
+      hash,
+      url: item.source_url,
+      filename: item.slug,
+      mime: item.mime_type,
+    });
+  }
+  return byHash;
+}
+
+/**
+ * Upload one file.
+ *
+ * WordPress derives a slug from the filename on create, so the identifying
+ * slug has to be set in a second request.
+ */
+export async function uploadMedia(
+  client: WpClient,
+  upload: MediaUpload,
+  prefix: string,
+): Promise<MediaRef> {
+  const slug = mediaSlug(prefix, upload.hash);
+  const form = new FormData();
+  const bytes = upload.bytes;
+  const view = new Uint8Array(bytes.byteLength);
+  view.set(bytes);
+  form.append('file', new File([view], upload.filename, { type: upload.mime }));
+  if (upload.title) form.append('title', upload.title);
+  if (upload.alt) form.append('alt_text', upload.alt);
+
+  let created: WpMedia;
+  try {
+    ({ data: created } = await client.request<WpMedia>('POST', '/media', { form }));
+  } catch (error) {
+    if (error instanceof TargetError && error.status === 400 && isBlockedByDefault(upload.mime)) {
+      throw new TargetError(
+        `${upload.filename} was refused. WordPress blocks ${upload.mime} uploads unless a plugin allows them, because such a file can carry script.`,
+        { status: error.status, code: error.code, method: error.method, url: error.url },
+      );
+    }
+    throw error;
+  }
+
+  const { data: updated } = await client.request<WpMedia>('POST', `/media/${created.id}`, {
+    body: { slug, ...(upload.title ? { title: upload.title } : {}), ...(upload.alt ? { alt_text: upload.alt } : {}) },
+  });
+
+  return {
+    id: updated.id,
+    hash: upload.hash,
+    url: updated.source_url || created.source_url,
+    filename: upload.filename,
+    mime: updated.mime_type || upload.mime,
+  };
+}

package/src/pages.ts

@@ -0,0 +1,201 @@
+/**
+ * WordPress pages: finding them, comparing them, writing them, removing them.
+ *
+ * A page's identity is its parent and its slug, which is what makes a re-run
+ * rewrite only what actually differs.
+ */
+
+import { TargetError } from '@pterodoc/core/util';
+import type { RemotePage, RenderedPage } from '@pterodoc/core/target';
+import { FULL_PAGE_FIELDS, PAGE_FIELDS, type WpClient } from './client';
+
+/** WordPress's own page shape, narrowed to what is read. */
+interface WpPage {
+  id: number;
+  parent: number;
+  slug: string;
+  status: string;
+  link: string;
+  title?: { raw?: string; rendered?: string };
+  content?: { raw?: string };
+  excerpt?: { raw?: string };
+  menu_order: number;
+  template: string;
+  meta?: Record<string, unknown>;
+}
+
+/** Convert a WordPress page into the shape the reconciler compares. */
+export function toRemotePage(page: WpPage): RemotePage {
+  return {
+    id: page.id,
+    parent: page.parent,
+    slug: page.slug,
+    status: page.status,
+    link: page.link,
+    title: page.title?.raw ?? page.title?.rendered ?? '',
+    ...(page.content?.raw !== undefined ? { content: page.content.raw } : {}),
+    ...(page.excerpt?.raw !== undefined ? { excerpt: page.excerpt.raw } : {}),
+    menuOrder: page.menu_order,
+    template: page.template,
+    meta: page.meta,
+  };
+}
+
+/** Fetch every page on the site. */
+export async function fetchPageIndex(client: WpClient): Promise<RemotePage[]> {
+  const pages = await client.listAll<WpPage>('/pages', {
+    status: 'any',
+    context: 'edit',
+    _fields: PAGE_FIELDS,
+  });
+  return pages.map(toRemotePage);
+}
+
+/** Fetch one page with the fields needed to compare it. */
+export async function fetchPage(client: WpClient, id: number): Promise<RemotePage> {
+  const { data } = await client.request<WpPage>('GET', `/pages/${id}`, {
+    query: { context: 'edit', _fields: FULL_PAGE_FIELDS },
+  });
+  return toRemotePage(data);
+}
+
+/**
+ * Find a page by its position in the tree.
+ *
+ * The index is searched when one was supplied, because a whole-site index is
+ * one request where per-page lookups are hundreds.
+ */
+export async function findPage(
+  client: WpClient,
+  parent: number,
+  slug: string,
+  index?: RemotePage[],
+  log: (message: string) => void = () => {},
+): Promise<RemotePage | undefined> {
+  let candidates: RemotePage[];
+  if (index) {
+    candidates = index.filter((page) => page.parent === parent && page.slug === slug);
+  } else {
+    const { data } = await client.request<WpPage[]>('GET', '/pages', {
+      query: { parent, slug, status: 'any', context: 'edit', per_page: 100, _fields: PAGE_FIELDS },
+    });
+    candidates = (Array.isArray(data) ? data : []).map(toRemotePage);
+  }
+  if (candidates.length > 1) {
+    log(`${candidates.length} pages share parent ${parent} and slug "${slug}"; using id ${candidates[0]!.id}.`);
+  }
+  return candidates[0];
+}
+
+/** Body sent when creating or updating a page. */
+export interface PageInput {
+  title?: string;
+  content?: string;
+  excerpt?: string;
+  parent?: number;
+  slug?: string;
+  status?: string;
+  menu_order?: number;
+  template?: string;
+  meta?: Record<string, unknown>;
+}
+
+/** Create a page, checking that WordPress honoured the slug we asked for. */
+export async function createPage(client: WpClient, input: PageInput): Promise<RemotePage> {
+  const { data } = await client.request<WpPage>('POST', '/pages', { body: input });
+  if (input.slug && data.slug !== input.slug) {
+    throw new TargetError(
+      `WordPress stored the new page as "${data.slug}" rather than "${input.slug}". Another page, possibly one in the trash, already holds that slug. The page it created is id ${data.id}.`,
+      { status: 200, method: 'POST', url: '/pages' },
+    );
+  }
+  return toRemotePage(data);
+}
+
+/** Update a page. */
+export async function updatePage(
+  client: WpClient,
+  id: number,
+  input: PageInput,
+): Promise<RemotePage> {
+  const { data } = await client.request<WpPage>('POST', `/pages/${id}`, { body: input });
+  return toRemotePage(data);
+}
+
+/**
+ * Move a page to the trash.
+ *
+ * Never a permanent delete: recovering from a mistaken prune should not
+ * require a database backup.
+ */
+export async function trashPage(client: WpClient, id: number): Promise<void> {
+  await client.request('DELETE', `/pages/${id}`);
+}
+
+/** Normalise a value for comparison, so whitespace alone is not a difference. */
+const normalise = (value: unknown): string =>
+  String(value ?? '').replace(/\r\n/g, '\n').trim();
+
+/**
+ * Which fields of an existing page differ from the rendered one.
+ *
+ * @param remote The page as WordPress holds it.
+ * @param rendered The page as pterodoc would publish it.
+ * @param context The expected parent, slug, status and template.
+ */
+export function diffPage(
+  remote: RemotePage,
+  rendered: RenderedPage,
+  context: { parentId: number; status: string; template: string; isRoot: boolean; slug: string },
+): string[] {
+  const changed: string[] = [];
+  if (normalise(remote.title) !== normalise(rendered.title)) changed.push('title');
+  if (normalise(remote.content) !== normalise(rendered.content)) changed.push('content');
+  if (normalise(remote.excerpt) !== normalise(rendered.excerpt)) changed.push('excerpt');
+  if (remote.status !== context.status) changed.push('status');
+  if (!context.isRoot && remote.menuOrder !== rendered.menuOrder) changed.push('menu_order');
+  if ((remote.template ?? '') !== context.template) changed.push('template');
+  if (remote.parent !== context.parentId) changed.push('parent');
+  if (remote.slug !== context.slug) changed.push('slug');
+
+  // Metadata is only compared where the site actually exposes the field, so a
+  // site without the SEO plugin does not report a difference on every run.
+  for (const [key, value] of Object.entries(rendered.meta)) {
+    if (remote.meta && key in remote.meta && normalise(remote.meta[key]) !== normalise(value)) {
+      changed.push(`meta.${key}`);
+    }
+  }
+  return changed;
+}
+
+/**
+ * Pages below a root that no rendered page accounts for.
+ *
+ * Deepest first, so a parent is never trashed before its children.
+ */
+export function computePrune(
+  index: RemotePage[],
+  rootId: number,
+  keepIds: Set<number>,
+): RemotePage[] {
+  const childrenOf = new Map<number, RemotePage[]>();
+  for (const page of index) {
+    const siblings = childrenOf.get(page.parent);
+    if (siblings) siblings.push(page);
+    else childrenOf.set(page.parent, [page]);
+  }
+
+  const owned: { page: RemotePage; depth: number }[] = [];
+  const walk = (parentId: number, depth: number): void => {
+    for (const page of childrenOf.get(parentId) ?? []) {
+      owned.push({ page, depth });
+      walk(page.id, depth + 1);
+    }
+  };
+  walk(rootId, 0);
+
+  return owned
+    .filter(({ page }) => !keepIds.has(page.id))
+    .sort((a, b) => b.depth - a.depth)
+    .map(({ page }) => page);
+}

package/src/plugin.ts

@@ -0,0 +1,69 @@
+/**
+ * Finding out whether the pterodoc WordPress plugin is installed.
+ *
+ * The plugin registers one option and exposes it over REST, so asking for the
+ * site's settings answers both questions at once: whether it is there, and what
+ * it is configured with. That second half matters, because the plugin styles a
+ * site by class prefix and a prefix that disagrees with the one pterodoc writes
+ * is a setup that looks broken for no visible reason.
+ */
+
+import { TargetError } from '@pterodoc/core/util';
+import type { WpClient } from './client';
+
+/** What the site said about the plugin. */
+export interface PluginStatus {
+  /** Whether the plugin answered. */
+  installed: boolean;
+  /**
+   * Why the answer is not known.
+   *
+   * Set when the site could not be asked — usually because the credentials
+   * belong to someone without `manage_options` — rather than when the plugin is
+   * known to be absent.
+   */
+  unknown?: string;
+  /** The class prefix the plugin is styling, when it is installed. */
+  classPrefix?: string;
+}
+
+/** The shape of the site settings this reads. */
+interface SiteSettings {
+  pterodoc_settings?: { classPrefix?: string };
+}
+
+/**
+ * Ask a site whether the plugin is installed.
+ *
+ * Never throws: an unreachable or unauthorised site is a thing to report in a
+ * diagnostic, not a reason to fail one.
+ *
+ * @param client A client for the site.
+ */
+export async function detectPlugin(client: WpClient): Promise<PluginStatus> {
+  try {
+    const { data } = await client.request<SiteSettings>('GET', '/settings');
+    const settings = data.pterodoc_settings;
+
+    if (!settings) return { installed: false };
+
+    return {
+      installed: true,
+      ...(settings.classPrefix ? { classPrefix: settings.classPrefix } : {}),
+    };
+  } catch (error) {
+    const status = error instanceof TargetError ? error.status : undefined;
+
+    if (status === 401 || status === 403) {
+      return {
+        installed: false,
+        unknown: 'these credentials may not read the site settings, so the plugin could not be checked',
+      };
+    }
+
+    return {
+      installed: false,
+      unknown: error instanceof Error ? error.message : 'the site could not be asked',
+    };
+  }
+}