@loopress/cli 0.32.1 → 0.33.0

package/dist/lib/rollback-materialize.js

@@ -1,13 +1,16 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { z } from 'zod';
 import { getAcfKey } from '../utils/acf-format.js';
+import { writeBlock } from '../utils/block-format.js';
 import { CPT_SPEC, fileExtension, formatDeclaredFile, META_SPEC, PATTERN_SPEC, ROLE_SPEC, TAXONOMY_SPEC } from '../utils/declared-type-format.js';
 import { getFormId, getFormTitle } from '../utils/form-format.js';
 import { getMenuSlug } from '../utils/menu-format.js';
 import { defaultReadonlyFor, optionFileName } from '../utils/option-format.js';
-import { buildMetaFile, buildSnippetFile } from '../utils/snippet-format.js';
+import { buildMetaFile, buildSnippetFile, normalizeSnippet } from '../utils/snippet-format.js';
 import { themeStylesFileName } from '../utils/theme-styles-format.js';
 import { toSlug } from '../utils/to-slug.js';
+import { isRecord } from './narrow.js';
 const SNIPPET_EXTENSIONS = { css: 'css', html: 'html', js: 'js', php: 'php', text: 'txt' };
 async function writeJson(path, value) {
     await mkdir(dirname(path), { recursive: true });
@@ -19,9 +22,20 @@ async function writeJson(path, value) {
 // compares (no `id`, no `description`, `code` with its `<?php` tag already stripped), exactly
 // what `normalizeSnippet` + `stripPhpOpeningTag` produce, so it plugs straight into the same
 // `buildSnippetFile`/`buildMetaFile` pair `snippet pull` uses to write files.
+// A snapshot entry that should be an object: anything else is a corrupted snapshot file.
+function snapshotRecord(id, value) {
+    if (!isRecord(value))
+        throw new Error(`Snapshot entry "${id}" is not an object.`);
+    return value;
+}
+const SNAPSHOT_OPTION = z.object({ autoload: z.string(), value: z.unknown() });
 async function snippet(id, value, dir) {
-    const fields = value;
-    const normalized = { ...fields, description: '', id: Number(id) };
+    const data = snapshotRecord(id, value);
+    // normalizeSnippet would coerce it, writing a corrupted entry's code over the live snippet.
+    if (typeof data.code !== 'string')
+        throw new Error(`Snapshot entry "${id}" has a non-string "code".`);
+    // normalizeSnippet is idempotent on its own output, so it narrows `data` without changing it.
+    const normalized = { ...normalizeSnippet(data), description: '', id: Number(id) };
     const ext = SNIPPET_EXTENSIONS[normalized.type];
     const base = `${normalized.id}-${toSlug(normalized.name)}`;
     await mkdir(dir, { recursive: true });
@@ -31,7 +45,7 @@ async function snippet(id, value, dir) {
 // value is the whole form JSON (minus `modified`/`modified_gmt`), the same shape `form pull`
 // writes verbatim; `form push` re-sends it as-is.
 async function form(id, value, dir) {
-    const data = value;
+    const data = snapshotRecord(id, value);
     const formId = getFormId(data) ?? Number(id);
     const slug = toSlug(getFormTitle(data), 'untitled');
     await writeJson(join(dir, `${formId}-${slug}.json`), data);
@@ -41,7 +55,7 @@ async function form(id, value, dir) {
 async function acf(id, value, dir) {
     const separator = id.indexOf('/');
     const type = id.slice(0, separator);
-    const data = value;
+    const data = snapshotRecord(id, value);
     const key = getAcfKey(data) ?? id.slice(separator + 1);
     await writeJson(join(dir, type, `${key}.json`), data);
 }
@@ -51,13 +65,18 @@ async function phpFile(id, value, dir) {
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, String(value));
 }
+// block: id is the slug, value the folder's files (file name => text).
+async function block(id, value, dir) {
+    const files = snapshotRecord(id, value);
+    await writeBlock(dir, { files: Object.fromEntries(Object.entries(files).map(([name, content]) => [name, String(content)])), slug: id });
+}
 // ids are 'menu-locations' or `menu/<slug>` (see resource-state.ts's menuProvider).
 async function menu(id, value, dir) {
     if (id === 'menu-locations') {
         await writeJson(join(dir, 'menu-locations.json'), value);
         return;
     }
-    const data = value;
+    const data = snapshotRecord(id, value);
     const slug = getMenuSlug(data) ?? id.slice('menu/'.length);
     await writeJson(join(dir, `${slug}.json`), data);
 }
@@ -67,7 +86,7 @@ async function menu(id, value, dir) {
 // dangerous option (siteurl, home, ...); defaulting to the same policy `option add` itself uses
 // keeps a rolled-back option exactly as protected as a freshly tracked one, never less.
 async function option(id, value, dir) {
-    const { autoload, value: optionValue } = value;
+    const { autoload, value: optionValue } = SNAPSHOT_OPTION.parse(value);
     const local = { autoload, name: id, readonly: defaultReadonlyFor(id), value: optionValue };
     await writeJson(join(dir, optionFileName(id)), local);
 }
@@ -79,12 +98,13 @@ async function themeStyles(id, value, dir) {
 // written in the spec's file format like `<resource> pull` does.
 function declaredType(spec) {
     return async (id, value, dir) => {
-        await writeFile(join(dir, `${id}${fileExtension(spec)}`), formatDeclaredFile(spec, value));
+        await writeFile(join(dir, `${id}${fileExtension(spec)}`), formatDeclaredFile(spec, snapshotRecord(id, value)));
     };
 }
 const MATERIALIZERS = {
     acf,
     api: phpFile,
+    block,
     cpt: declaredType(CPT_SPEC),
     form,
     hook: phpFile,

package/dist/lib/rotate-app-password.js

@@ -1,3 +1,4 @@
+import {} from '../types/config.js';
 import { WpClient } from './wp-client.js';
 const APPLICATION_PASSWORDS_PATH = 'wp/v2/users/me/application-passwords';
 export const APP_PASSWORD_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1000;

package/dist/lib/sentry.js

@@ -20,8 +20,8 @@ export function runtimeContext() {
         os: `${platform()} ${release()}`,
     };
 }
-// Positional args and flag values can carry WordPress URLs, usernames, application passwords,
-// or tokens (e.g. `lps login --token xxx`, `lps project config <url>`). Only flag names are
+// Positional args and flag values are user input: environment names, local paths, slugs, and
+// anything else typed after a command, possibly a URL or a credential. Only flag names are
 // safe to report, they help tell which code path crashed without leaking what was passed to it.
 export function redactArgv(argv) {
     return argv.map((arg) => {

package/dist/lib/snapshot-store.d.ts

@@ -1,12 +1,14 @@
+import { z } from 'zod';
 import { type ResourceState } from './diff-state.js';
 export declare const SNAPSHOT_RETENTION = 10;
-export type Snapshot = {
-    afterState: Record<string, unknown>;
-    beforeState: Record<string, unknown>;
-    createdAt: string;
-    environment: string;
-    resource: string;
-};
+declare const SNAPSHOT: z.ZodObject<{
+    afterState: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    beforeState: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    createdAt: z.ZodString;
+    environment: z.ZodString;
+    resource: z.ZodString;
+}, z.core.$strip>;
+export type Snapshot = z.infer<typeof SNAPSHOT>;
 export type SnapshotSummary = {
     createdAt: string;
     environment: string;
@@ -28,3 +30,4 @@ export declare function readSnapshot(rootDir: string, resource: string, environm
     id: string;
 }>;
 export declare function pruneSnapshots(rootDir: string, resource: string, environment: string, retain: number): Promise<void>;
+export {};

package/dist/lib/snapshot-store.js

@@ -1,8 +1,23 @@
 import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { z } from 'zod';
+import {} from './diff-state.js';
+import { errorCode } from './narrow.js';
 // How many snapshots `writeSnapshot` keeps per resource before pruning the oldest, so the
 // cache directory doesn't grow without bound across a project's lifetime.
 export const SNAPSHOT_RETENTION = 10;
+// One `lps <resource> push` recorded as a restore point. `beforeState` is the remote state
+// read immediately before that push (the "left" side `lps diff` would have shown); `afterState`
+// is the local state that was about to be pushed (the "right" side). Rolling back restores
+// `beforeState`; comparing the environment's *current* state against `afterState` at rollback
+// time is what detects whether anything else touched the environment since.
+const SNAPSHOT = z.object({
+    afterState: z.record(z.string(), z.unknown()),
+    beforeState: z.record(z.string(), z.unknown()),
+    createdAt: z.string(),
+    environment: z.string(),
+    resource: z.string(),
+});
 // `ResourceState` (a Map, for O(1) lookups during comparison) has no direct JSON
 // representation; snapshots round-trip through a plain object instead. Keys are sorted so two
 // snapshots of the same state serialize identically (stable diffs, deterministic tests).
@@ -27,10 +42,10 @@ function snapshotPath(rootDir, resource, environment, id) {
     return join(snapshotsDir(rootDir, resource, environment), `${id}.json`);
 }
 function isEnoent(error) {
-    return error.code === 'ENOENT';
+    return errorCode(error) === 'ENOENT';
 }
 function isEexist(error) {
-    return error.code === 'EEXIST';
+    return errorCode(error) === 'EEXIST';
 }
 // Snapshot ids are the millisecond timestamp they were written at: sortable, unique enough for
 // a single-machine CLI run, and directly usable as `--to <id>`.
@@ -105,7 +120,8 @@ export async function listSnapshots(rootDir, resource, environment) {
     for (const entry of snapshotFiles) {
         const id = entry.slice(0, -'.json'.length);
         try {
-            const parsed = JSON.parse(await readFile(join(dir, entry), 'utf8'));
+            const raw = JSON.parse(await readFile(join(dir, entry), 'utf8'));
+            const parsed = SNAPSHOT.parse(raw);
             summaries.push({ createdAt: parsed.createdAt, environment: parsed.environment, id, resource });
         }
         catch {
@@ -122,7 +138,7 @@ export async function listSnapshots(rootDir, resource, environment) {
 export async function readSnapshot(rootDir, resource, environment, id) {
     let targetId = id;
     if (targetId === undefined) {
-        const [latest] = await listSnapshots(rootDir, resource, environment);
+        const latest = (await listSnapshots(rootDir, resource, environment)).at(0);
         if (!latest) {
             throw new Error(`No snapshots found for "${resource}" on "${environment}". A snapshot is written automatically by \`lps ${resource} push\`.`);
         }
@@ -138,7 +154,7 @@ export async function readSnapshot(rootDir, resource, environment, id) {
         }
         throw error;
     }
-    return { ...JSON.parse(raw), id: targetId };
+    return { ...SNAPSHOT.parse(JSON.parse(raw)), id: targetId };
 }
 export async function pruneSnapshots(rootDir, resource, environment, retain) {
     const summaries = await listSnapshots(rootDir, resource, environment);

package/dist/lib/spinner.js

@@ -16,6 +16,7 @@ function start() {
     const rawOut = process.stdout.write;
     const rawErr = process.stderr.write;
     const draw = () => {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- typed as number, but undefined when stderr is not a TTY
         const text = `${FRAMES[frame]} ${label}`.slice(0, (process.stderr.columns ?? 80) - 1);
         rawErr.call(process.stderr, `\r\u{1B}[2K${text}`);
     };
@@ -26,7 +27,10 @@ function start() {
         draw();
         return result;
     };
+    // write() is overloaded, and a single rest-args wrapper can't be typed as every overload.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- see above
     process.stdout.write = intercept(process.stdout, rawOut);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- see above
     process.stderr.write = intercept(process.stderr, rawErr);
     draw();
     const timer = setInterval(() => {

package/dist/lib/validate-local.js

@@ -1,6 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
+import { z } from 'zod';
 import { configManager } from '../config/project-config.manager.js';
+import { PLUGIN_PIN } from '../types/plugin.js';
+import { readLocalBlocks } from '../utils/block-format.js';
+import { COMPOSER_JSON } from '../utils/composer.js';
 import { CPT_SPEC, declaredFileChecker, META_SPEC, PATTERN_SPEC, ROLE_SPEC, TAXONOMY_SPEC } from '../utils/declared-type-format.js';
 import { parseLocalOption } from '../utils/option-format.js';
 import { readLocalHtmlFiles, readLocalPages } from '../utils/page-format.js';
@@ -8,6 +12,7 @@ import { RESOURCE_DIR_DEFAULTS } from '../utils/resource-dirs.js';
 import { parseType } from '../utils/snippet-format.js';
 import { readLocalTemplates } from '../utils/template-format.js';
 import { loadSnippets } from './load-snippets.js';
+import { errorCode, errorMessage, isRecord } from './narrow.js';
 import { API_FILES_RESOURCE, HOOK_FILES_RESOURCE, phpFileProblems } from './php-files-command.js';
 import { readdirTolerant } from './readdir-tolerant.js';
 // Directories holding one JSON document per resource. Snippets (code file plus JSON sidecar)
@@ -16,6 +21,7 @@ const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'menuDir', 'themeStylesDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
+    blockDir: RESOURCE_DIR_DEFAULTS.block,
     cptDir: 'cpt',
     formDir: 'forms',
     hooksDir: 'hooks',
@@ -61,6 +67,9 @@ export async function validateLocal(cwd) {
     checked += await checkSnippets(resolve('snippetsDir'), problems);
     checked += await checkPhpDir(resolve('apiDir'), problems, 'API route file is empty', API_FILES_RESOURCE);
     checked += await checkPhpDir(resolve('hooksDir'), problems, 'Hook file is empty', HOOK_FILES_RESOURCE);
+    const blocks = await readLocalBlocks(resolve('blockDir'));
+    checked += blocks.blocks.length;
+    problems.push(...blocks.problems);
     const pages = await readLocalPages(resolve('pageDir'));
     checked += pages.pages.length + pages.problems.length;
     problems.push(...pages.problems);
@@ -108,6 +117,7 @@ async function checkPhpDir(dir, problems, emptyMessage, spec) {
     }
     return checked;
 }
+const JSON_OBJECT = z.record(z.string(), z.unknown());
 async function checkComposerJson(cwd, problems) {
     let raw;
     try {
@@ -122,14 +132,13 @@ async function checkComposerJson(cwd, problems) {
         parsed = JSON.parse(raw);
     }
     catch (error) {
-        problems.push({ file: 'composer.json', message: `not valid JSON: ${error.message}` });
+        problems.push({ file: 'composer.json', message: `not valid JSON: ${errorMessage(error)}` });
         return 1;
     }
-    for (const key of ['require', 'require-dev']) {
-        const section = parsed[key];
-        if (section !== undefined && (typeof section !== 'object' || section === null || Array.isArray(section))) {
-            problems.push({ file: 'composer.json', message: `"${key}" must be an object` });
-        }
+    const result = COMPOSER_JSON.safeParse(parsed);
+    if (!result.success) {
+        for (const { message } of result.error.issues)
+            problems.push({ file: 'composer.json', message });
     }
     return 1;
 }
@@ -151,10 +160,10 @@ async function checkJsonDir(dir, problems, shape) {
             parsed = JSON.parse(raw);
         }
         catch (error) {
-            problems.push({ file: filePath, message: `not valid JSON: ${error.message}` });
+            problems.push({ file: filePath, message: `not valid JSON: ${errorMessage(error)}` });
             continue;
         }
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        if (!JSON_OBJECT.safeParse(parsed).success) {
             problems.push({ file: filePath, message: 'expected a JSON object' });
             continue;
         }
@@ -162,7 +171,7 @@ async function checkJsonDir(dir, problems, shape) {
             shape?.(raw, filePath);
         }
         catch (error) {
-            problems.push({ file: filePath, message: error.message });
+            problems.push({ file: filePath, message: errorMessage(error) });
         }
     }
     return checked;
@@ -184,19 +193,16 @@ function checkLoopressJson(localConfig, problems) {
     const { plugins } = localConfig;
     if (plugins === undefined)
         return;
-    if (typeof plugins !== 'object' || plugins === null || Array.isArray(plugins)) {
+    const manifest = JSON_OBJECT.safeParse(plugins);
+    if (!manifest.success) {
         problems.push({ file: 'loopress.json', message: '"plugins" must be an object of slug -> version string or {version, active}' });
         return;
     }
-    for (const [slug, version] of Object.entries(plugins)) {
+    for (const [slug, version] of Object.entries(manifest.data)) {
         // The object form is what `plugin pull` writes for a plugin installed but inactive (see PluginPin).
-        const isPin = typeof version === 'string' ||
-            (typeof version === 'object' &&
-                version !== null &&
-                typeof version.version === 'string' &&
-                ['boolean', 'undefined'].includes(typeof version.active));
-        if (!isPin)
+        if (!PLUGIN_PIN.safeParse(version).success) {
             problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a version string or {version, active}` });
+        }
     }
 }
 async function checkSnippets(dir, problems) {
@@ -211,7 +217,7 @@ async function checkSnippets(dir, problems) {
         });
     }
     catch (error) {
-        problems.push({ file: dir, message: error.message });
+        problems.push({ file: dir, message: errorMessage(error) });
         return 0;
     }
     // loadSnippets coerces an invalid `type` to the extension default rather than failing, so
@@ -227,6 +233,10 @@ async function checkSnippets(dir, problems) {
             problems.push({ file: filePath, message: 'not valid JSON' });
             continue;
         }
+        if (!isRecord(meta)) {
+            problems.push({ file: filePath, message: 'expected a JSON object' });
+            continue;
+        }
         if (meta.type !== undefined && parseType(meta.type) === null) {
             problems.push({ file: filePath, message: `"type": ${JSON.stringify(meta.type)} is not one of css, html, js, php, text` });
         }
@@ -245,15 +255,20 @@ async function readConfig(cwd, problems) {
         raw = await readFile(join(cwd, 'loopress.json'), 'utf8');
     }
     catch (error) {
-        if (error.code === 'ENOENT')
+        if (errorCode(error) === 'ENOENT')
             return {};
         throw error;
     }
+    let parsed;
     try {
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch {
         problems.push({ file: 'loopress.json', message: 'loopress.json is not valid JSON. Fix or delete it, then run `lps init` again.' });
         return {};
     }
+    if (isRecord(parsed) && !Array.isArray(parsed))
+        return parsed;
+    problems.push({ file: 'loopress.json', message: 'expected a JSON object' });
+    return {};
 }

package/dist/lib/wp-client.d.ts

@@ -7,8 +7,8 @@ export declare function assertSecureSiteUrl(siteUrl: string, environmentName: st
  * Paths are relative to `<site>/wp-json/`, e.g. `loopress/v1/snippets` or `wp/v2/plugins`.
  */
 export declare class WpClient {
-    private readonly siteUrl;
     private readonly client;
+    private readonly siteUrl;
     constructor(siteUrl: string, token: string, environmentName?: string);
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
@@ -28,5 +28,10 @@ export declare function isApplicative404(error: unknown, marker: string): boolea
 export declare function isConflictCode(error: unknown, code: string): boolean;
 export declare function isTimeoutError(error: unknown): boolean;
 export declare function isInvalidPageNumber(error: unknown): boolean;
+export declare function responseOf(error: unknown): {
+    body?: string | undefined;
+    statusCode?: number | undefined;
+};
+export declare function parseBody(body: string | undefined): Record<string, unknown>;
 export declare function formatWpError(error: unknown, url: string, timeoutMs?: number): string;
 export {};

package/dist/lib/wp-client.js

@@ -1,5 +1,6 @@
-import got from 'got';
+import got, {} from 'got';
 import { Buffer } from 'node:buffer';
+import { causeOf, errorCode, isRecord } from './narrow.js';
 import { withSpinner } from './spinner.js';
 export const REQUEST_TIMEOUT_MS = 30_000;
 // The one environment allowed to talk plain HTTP: Loopress's local dev environment, identified
@@ -30,11 +31,11 @@ export function assertSecureSiteUrl(siteUrl, environmentName) {
  * Paths are relative to `<site>/wp-json/`, e.g. `loopress/v1/snippets` or `wp/v2/plugins`.
  */
 export class WpClient {
-    siteUrl;
     client;
+    siteUrl;
     constructor(siteUrl, token, environmentName) {
-        this.siteUrl = siteUrl;
         assertSecureSiteUrl(siteUrl, environmentName);
+        this.siteUrl = siteUrl;
         this.client = got.extend({
             headers: { Authorization: `Basic ${Buffer.from(token).toString('base64')}` },
             prefixUrl: `${siteUrl}/wp-json`,
@@ -83,6 +84,8 @@ export class WpClient {
         const timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS;
         try {
             const response = await withSpinner(`Waiting for ${new URL(this.siteUrl).host}`, async () => this.client(path, { json, method, timeout: { request: timeoutMs } }));
+            // The REST contract boundary: each endpoint's shape is the caller's `T`, not checked here.
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- see above
             return (response.body ? JSON.parse(response.body) : undefined);
         }
         catch (error) {
@@ -91,95 +94,91 @@ export class WpClient {
     }
 }
 export function isNotFoundError(error) {
-    const cause = error?.cause;
-    return cause?.response?.statusCode === 404;
+    return responseOf(causeOf(error)).statusCode === 404;
 }
 // Authenticated but missing the capability the endpoint needs (e.g. `list_users`).
 export function isForbiddenError(error) {
-    const cause = error?.cause;
-    return cause?.response?.statusCode === 403;
+    return responseOf(causeOf(error)).statusCode === 403;
 }
 // A 404 a Loopress controller raises on purpose, identified by its JSON body's `error` field
 // (e.g. `{"error": "composer.lock not found"}` from ComposerController). Narrower than
 // isNotFoundError: a bare 404 also covers the route being absent because the plugin isn't
 // installed or predates the feature, which callers must still surface normally.
 export function isApplicative404(error, marker) {
-    if (!isNotFoundError(error))
-        return false;
-    const body = error.cause?.response?.body;
-    if (!body)
-        return false;
-    try {
-        return JSON.parse(body).error === marker;
-    }
-    catch {
-        return false;
-    }
+    return isNotFoundError(error) && parseBody(responseOf(causeOf(error)).body).error === marker;
 }
 // A 409 a Loopress controller tags with a `code`, for a refusal the CLI can act on (e.g.
 // `loopress_page_not_managed`, which `lps page push` offers to take over).
 export function isConflictCode(error, code) {
-    const response = error?.cause?.response;
-    if (response?.statusCode !== 409 || !response.body)
-        return false;
-    try {
-        return JSON.parse(response.body).code === code;
-    }
-    catch {
-        return false;
-    }
+    const { body, statusCode } = responseOf(causeOf(error));
+    return statusCode === 409 && parseBody(body).code === code;
 }
 export function isTimeoutError(error) {
-    const cause = error?.cause;
-    return cause?.name === 'TimeoutError';
+    const cause = causeOf(error);
+    return isRecord(cause) && cause.name === 'TimeoutError';
 }
 // WordPress core answers 400 with this `code` when `?page=N` is past the last page of a
 // collection, which is how `WpClient.getAll` knows it has walked them all.
 export function isInvalidPageNumber(error) {
-    const body = error.cause?.response?.body;
+    return parseBody(responseOf(causeOf(error)).body).code === 'rest_post_invalid_page_number';
+}
+// The HTTP response a got error carries, read structurally so a mocked error reads the same.
+export function responseOf(error) {
+    const response = isRecord(error) ? error.response : undefined;
+    if (!isRecord(response))
+        return {};
+    return {
+        body: typeof response.body === 'string' ? response.body : undefined,
+        statusCode: typeof response.statusCode === 'number' ? response.statusCode : undefined,
+    };
+}
+// A response body's top-level JSON fields, or none when it isn't JSON.
+export function parseBody(body) {
     if (!body)
-        return false;
+        return {};
     try {
-        return JSON.parse(body).code === 'rest_post_invalid_page_number';
+        const parsed = JSON.parse(body);
+        return isRecord(parsed) ? parsed : {};
     }
     catch {
-        return false;
+        return {};
     }
 }
 export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
-    const err = error;
-    const status = err.response?.statusCode;
+    const { body, statusCode: status } = responseOf(error);
     if (status === 401 || status === 403) {
         // A Loopress controller's own `{"error": ...}` on a 403 is a deliberate refusal of this one
         // request (e.g. OptionsController protecting a secret-looking option), not bad credentials:
         // pointing at `lps project config` there sends the user the wrong way. WordPress core's own
         // auth failures use `{code, message}` instead and keep the credentials hint.
-        const refusal = extractLoopressError(err.response?.body);
+        const refusal = extractLoopressError(body);
         if (refusal)
             return `Request refused (${status}) on ${url}: ${refusal}`;
         return `Authentication failed (${status}) on ${url}. Check your credentials with \`lps project config\`.`;
     }
     if (status === 404) {
-        const reason = extractServerErrorMessage(err.response?.body);
+        const reason = extractServerErrorMessage(body);
         return reason
             ? `Request failed (404) on ${url}: ${reason}`
             : `Endpoint not found (404) on ${url}. Is the required plugin installed and up to date on the site?`;
     }
     if (status !== undefined) {
-        const reason = extractServerErrorMessage(err.response?.body);
+        const reason = extractServerErrorMessage(body);
         return reason ? `Request failed (${status}) on ${url}: ${reason}` : `Request failed (${status}) on ${url}.`;
     }
-    if (err.name === 'TimeoutError') {
+    if (isRecord(error) && error.name === 'TimeoutError') {
         return `Request timed out after ${timeoutMs / 1000}s on ${url}. Is the site reachable?`;
     }
-    const reason = err.code ? NETWORK_ERROR_HINTS[err.code] : undefined;
+    const code = errorCode(error);
+    const reason = code ? NETWORK_ERROR_HINTS[code] : undefined;
     // The site, not the endpoint: every resource fails the same way when the site is down, so
     // `lps diff` can print it once (see DiffCommand.report).
     if (reason)
         return `Could not reach ${new URL(url).origin}: ${reason}. Run \`lps doctor\` to check the environment.`;
     // Node leaves `message` empty on some network errors (an AggregateError over IPv4 + IPv6):
     // fall back to the error code so the reason is never blank.
-    return `Request to ${url} failed: ${err.message?.length ? err.message : (err.code ?? String(error))}`;
+    const message = isRecord(error) && typeof error.message === 'string' ? error.message : '';
+    return `Request to ${url} failed: ${message || (code ?? String(error))}`;
 }
 const NETWORK_ERROR_HINTS = {
     ECONNREFUSED: 'connection refused, the site may be down',
@@ -188,15 +187,8 @@ const NETWORK_ERROR_HINTS = {
     ETIMEDOUT: 'connection timed out',
 };
 function extractLoopressError(body) {
-    if (!body)
-        return undefined;
-    try {
-        const { error } = JSON.parse(body);
-        return typeof error === 'string' && error.trim() ? decodeEntities(error) : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    const { error } = parseBody(body);
+    return typeof error === 'string' && error.trim() ? decodeEntities(error) : undefined;
 }
 // Plugin exception messages go through esc_html() (WordPress coding standards require it for
 // anything thrown), so quotes and ampersands reach the JSON body as entities. They're meant for
@@ -219,24 +211,17 @@ function decodeEntities(text) {
 // specifically so a caller that only reads `error` doesn't see it, which is exactly what this
 // function used to do, hiding the one piece of text that actually explains the failure.
 function extractServerErrorMessage(body) {
-    if (!body)
+    const parsed = parseBody(body);
+    // WP core's own generic body for a route it never registered (e.g. a plugin too old to
+    // expose this endpoint yet) is never more useful than the "is the plugin up to date?"
+    // fallback below; surfacing it verbatim buries a version-skew mismatch behind text that
+    // reads like the endpoint doesn't exist at all, pointing the user in the wrong direction.
+    if (parsed.code === 'rest_no_route')
         return undefined;
-    try {
-        const parsed = JSON.parse(body);
-        // WP core's own generic body for a route it never registered (e.g. a plugin too old to
-        // expose this endpoint yet) is never more useful than the "is the plugin up to date?"
-        // fallback below; surfacing it verbatim buries a version-skew mismatch behind text that
-        // reads like the endpoint doesn't exist at all, pointing the user in the wrong direction.
-        if (parsed.code === 'rest_no_route')
-            return undefined;
-        const reason = parsed.error ?? parsed.message;
-        const summary = typeof reason === 'string' && reason.trim() ? decodeEntities(reason) : undefined;
-        const detail = typeof parsed.output === 'string' && parsed.output.trim() ? parsed.output.trim() : undefined;
-        if (summary && detail)
-            return `${summary}\n${detail}`;
-        return summary ?? detail;
-    }
-    catch {
-        return undefined;
-    }
+    const reason = parsed.error ?? parsed.message;
+    const summary = typeof reason === 'string' && reason.trim() ? decodeEntities(reason) : undefined;
+    const detail = typeof parsed.output === 'string' && parsed.output.trim() ? parsed.output.trim() : undefined;
+    if (summary && detail)
+        return `${summary}\n${detail}`;
+    return summary ?? detail;
 }

package/dist/lib/wp-site-diagnostic.js

@@ -1,4 +1,5 @@
 import got from 'got';
+import { errorMessage, isRecord } from './narrow.js';
 import { withSpinner } from './spinner.js';
 export const REQUEST_TIMEOUT_MS = 10_000;
 /**
@@ -28,10 +29,10 @@ export async function diagnoseWpSite(siteUrl) {
     catch (error) {
         return {
             ok: false,
-            reason: `Could not reach the WordPress REST API at ${siteUrl}/wp-json/. The site may be unreachable, or a security plugin may be blocking it. (${describe(error)})`,
+            reason: `Could not reach the WordPress REST API at ${siteUrl}/wp-json/. The site may be unreachable, or a security plugin may be blocking it. (${errorMessage(error)})`,
         };
     }
-    if (!index?.authentication?.['application-passwords']) {
+    if (!isRecord(index?.authentication?.['application-passwords'])) {
         return {
             ok: false,
             reason: `Application Passwords are not available on ${siteUrl}. The site may be older than WordPress 5.6, require HTTPS, or have the feature disabled by a plugin or filter.`,
@@ -69,6 +70,3 @@ async function detectWpVersion(siteUrl) {
     }
     return undefined;
 }
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}