@loopress/cli 0.32.2 → 0.33.0

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);
-}

package/dist/types/global-config.generated.d.ts

@@ -54,7 +54,7 @@ export interface EnvironmentConfig {
      */
     name: string;
     /**
-     * API token used to authenticate against this environment.
+     * WordPress Application Password credentials for this environment, as "user:password". Not the Loopress account token.
      */
     token?: string;
     /**

package/dist/types/plugin.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 export type InstalledPlugin = {
     active: boolean;
     file: string;
@@ -12,11 +13,12 @@ export type WpNativePlugin = {
     status: 'active' | 'inactive' | 'network-active';
     version: string;
 };
-export type PluginPin = string | {
-    active?: boolean;
-    version: string;
-};
+export declare const PLUGIN_PIN: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    active: z.ZodExactOptional<z.ZodBoolean>;
+    version: z.ZodString;
+}, z.core.$strip>]>;
+export type PluginPin = z.infer<typeof PLUGIN_PIN>;
 export type PluginManifest = Record<string, PluginPin>;
 export declare const pinVersion: (pin: PluginPin) => string;
-export declare const pinActive: (pin: PluginPin) => boolean;
+export declare const pinActive: (pin: PluginPin | undefined) => boolean;
 export declare const pinVersions: (manifest: PluginManifest) => Record<string, string>;

package/dist/types/plugin.js

@@ -1,4 +1,9 @@
+import { z } from 'zod';
+// A bare version string means "installed and active"; the object form records a plugin that
+// must stay installed but inactive.
+export const PLUGIN_PIN = z.union([z.string(), z.object({ active: z.boolean().exactOptional(), version: z.string() })]);
 export const pinVersion = (pin) => (typeof pin === 'string' ? pin : pin.version);
-export const pinActive = (pin) => typeof pin === 'string' || pin.active !== false;
+// No pin at all (a slug loopress.json doesn't list) keeps the default: active.
+export const pinActive = (pin) => typeof pin === 'string' || pin?.active !== false;
 // The version-only view the Composer sync endpoint expects.
 export const pinVersions = (manifest) => Object.fromEntries(Object.entries(manifest).map(([slug, pin]) => [slug, pinVersion(pin)]));

package/dist/types/project-config.generated.d.ts

@@ -23,6 +23,10 @@ export interface LoopressProjectConfiguration {
      * Directory where custom API route files are read from and written to, relative to rootDir.
      */
     apiDir?: string;
+    /**
+     * Directory of dynamic blocks, one <slug>/ folder holding block.json and render.php, registered as loopress/<slug>, relative to rootDir.
+     */
+    blockDir?: string;
     /**
      * Directory where hook files (WordPress actions, filters, and scheduled tasks) are read from and written to, relative to rootDir.
      */
@@ -103,7 +107,11 @@ export interface LoopressProjectConfiguration {
         };
     };
     /**
-     * WordPress.org themes managed by Loopress, installed via Composer + WPackagist on the site. Keys are theme slugs; values are an exact version or "latest". Loopress manages installed theme versions only, it never switches the active theme. Ignored when a composer.json exists in rootDir.
+     * Keep the Loopress child theme (<parent>-loopress) active: `lps theme template push`, and so `lps push`, activates it when it isn't. Off by default, a theme switch changes the settings WordPress stores per theme.
+     */
+    activateChildTheme?: boolean;
+    /**
+     * WordPress.org themes managed by Loopress, installed via Composer + WPackagist on the site. Keys are theme slugs; values are an exact version or "latest". Loopress manages installed theme versions only, it never switches the active theme (see activateChildTheme and `lps theme activate`). Ignored when a composer.json exists in rootDir.
      */
     themes?: {
         [k: string]: string;

package/dist/types/snippet.d.ts

@@ -2,8 +2,8 @@ import { type SnippetInsertMethod, type SnippetLocation, type SnippetType } from
 export type Snippet = {
     active: boolean;
     code: string;
-    description?: string;
-    id?: number;
+    description?: string | undefined;
+    id?: number | undefined;
     insertMethod: SnippetInsertMethod;
     location: SnippetLocation;
     name: string;

package/dist/types/snippet.js

@@ -1 +1 @@
-export {};
+import {} from '../utils/snippet-format.js';

package/dist/utils/acf-format.js

@@ -1,4 +1,5 @@
 import { isDeepStrictEqual } from 'node:util';
+import { isRecord } from '../lib/narrow.js';
 export const ACF_OBJECT_TYPES = ['field-groups', 'post-types', 'taxonomies', 'options-pages'];
 export function acfEndpoint(type) {
     return `loopress/v1/acf/${type}`;
@@ -23,21 +24,23 @@ export function getAcfKey(data) {
     return typeof data.key === 'string' && data.key.trim() !== '' ? data.key : null;
 }
 function topLevelFields(group) {
-    const fields = group?.fields;
+    const fields = isRecord(group) ? group.fields : undefined;
     const byKey = new Map();
     for (const field of Array.isArray(fields) ? fields : []) {
-        if (typeof field?.key === 'string')
+        if (isRecord(field) && typeof field.key === 'string')
             byKey.set(field.key, field);
     }
     return byKey;
 }
+function label(field) {
+    return typeof field.name === 'string' && field.name !== '' ? field.name : String(field.key);
+}
 // A changed field group's top-level fields, matched by `key` and named by `name` (a repeater's
 // sub-field change shows as its parent changing). Only for the dry-run preview: the push itself
 // always sends the whole group.
 export function acfFieldChanges(before, after) {
     const old = topLevelFields(before);
     const next = topLevelFields(after);
-    const label = (field) => (typeof field.name === 'string' && field.name !== '' ? field.name : String(field.key));
     const changes = { added: [], changed: [], removed: [] };
     for (const [key, field] of next) {
         if (!old.has(key))