@loopress/cli 0.32.2 → 0.33.0

package/dist/utils/block-format.d.ts

@@ -0,0 +1,27 @@
+export declare const BLOCKS_ENDPOINT = "loopress/v1/block-files";
+export declare const BLOCK_FILES: readonly ["block.json", "render.php", "style.css", "view.js"];
+export declare const BLOCK_SLUG: RegExp;
+export type BlockFiles = Record<string, string>;
+export type LocalBlock = {
+    files: BlockFiles;
+    slug: string;
+};
+export type BlockProblem = {
+    file: string;
+    message: string;
+};
+export declare function blockProblems(slug: string, files: BlockFiles): string[];
+export declare function readLocalBlocks(dir: string): Promise<{
+    blocks: LocalBlock[];
+    problems: BlockProblem[];
+}>;
+export declare function formatBlockProblems(problems: BlockProblem[]): string;
+export declare function assertSafeBlock(block: LocalBlock): void;
+export declare function writeBlock(dir: string, block: LocalBlock): Promise<void>;
+export type RemoteBlock = LocalBlock & {
+    error?: string;
+    runtimeError?: {
+        at: string;
+        message: string;
+    };
+};

package/dist/utils/block-format.js

@@ -0,0 +1,93 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errorCode, isRecord } from '../lib/narrow.js';
+// A dynamic block: blocks/<slug>/ in WordPress's own block format, registered on the site as
+// loopress/<slug> (the plugin's BlocksDirectory and BlockFilesController).
+export const BLOCKS_ENDPOINT = 'loopress/v1/block-files';
+// The only files a block folder may hold, mirrors BlocksDirectory::FILES.
+export const BLOCK_FILES = ['block.json', 'render.php', 'style.css', 'view.js'];
+// WordPress's block name segment rule, capped like the plugin's slug pattern.
+export const BLOCK_SLUG = /^[a-z][a-z0-9-]{0,63}$/;
+// Every `file:./x` path a block.json field points at (style, viewScriptModule, ...), top level
+// only, as a string or an array of strings, like WordPress reads them.
+function referencedFiles(metadata) {
+    return Object.values(metadata)
+        .flatMap((value) => (Array.isArray(value) ? value : [value]))
+        .filter((value) => typeof value === 'string' && value.startsWith('file:'))
+        .map((value) => value.slice('file:'.length).replace(/^\.\//, ''));
+}
+// Local checks `lps block push` and `lps validate` share. The site checks the same again,
+// plus render.php's syntax.
+export function blockProblems(slug, files) {
+    if (!BLOCK_SLUG.test(slug))
+        return ['the folder name must be lowercase letters, digits and hyphens, starting with a letter'];
+    const problems = [];
+    for (const name of Object.keys(files)) {
+        if (!BLOCK_FILES.includes(name))
+            problems.push(`${name} is not a block file, a block folder holds only ${BLOCK_FILES.join(', ')}`);
+    }
+    if (files['render.php'] === undefined)
+        problems.push('render.php is missing');
+    const raw = files['block.json'];
+    if (raw === undefined)
+        return [...problems, 'block.json is missing'];
+    let metadata;
+    try {
+        metadata = JSON.parse(raw);
+    }
+    catch {
+        return [...problems, 'block.json is not valid JSON'];
+    }
+    if (!isRecord(metadata) || Array.isArray(metadata))
+        return [...problems, 'block.json is not a JSON object'];
+    if (metadata.name !== `loopress/${slug}`)
+        problems.push(`block.json "name" must be "loopress/${slug}"`);
+    for (const file of referencedFiles(metadata)) {
+        if (files[file] === undefined)
+            problems.push(`block.json references file:./${file}, which is not in the folder`);
+    }
+    return problems;
+}
+// Every blocks/<slug>/ folder with its files. Unknown files are read too, so blockProblems()
+// reports them instead of push silently dropping them.
+export async function readLocalBlocks(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return { blocks: [], problems: [] };
+        throw error;
+    }
+    const blocks = [];
+    const problems = [];
+    for (const entry of entries.filter((candidate) => candidate.isDirectory()).toSorted((a, b) => a.name.localeCompare(b.name))) {
+        const slug = entry.name;
+        const files = {};
+        for (const file of await readdir(join(dir, slug), { withFileTypes: true })) {
+            if (file.isFile() && !file.name.startsWith('.'))
+                files[file.name] = await readFile(join(dir, slug, file.name), 'utf8');
+        }
+        for (const message of blockProblems(slug, files))
+            problems.push({ file: join(dir, slug), message });
+        blocks.push({ files, slug });
+    }
+    return { blocks, problems };
+}
+export function formatBlockProblems(problems) {
+    return problems.map((problem) => `${problem.file}: ${problem.message}`).join('\n');
+}
+// A block from the site or a snapshot names a folder and files on disk: anything but a valid
+// slug and the known file names could write or delete outside blocks/.
+export function assertSafeBlock(block) {
+    const unsafe = !BLOCK_SLUG.test(block.slug) || Object.keys(block.files).some((name) => !BLOCK_FILES.includes(name));
+    if (unsafe)
+        throw new Error(`Refusing block "${block.slug}": invalid slug or file name (${Object.keys(block.files).join(', ')})`);
+}
+export async function writeBlock(dir, block) {
+    assertSafeBlock(block);
+    await mkdir(join(dir, block.slug), { recursive: true });
+    for (const [name, content] of Object.entries(block.files))
+        await writeFile(join(dir, block.slug, name), content);
+}

package/dist/utils/composer.d.ts

@@ -1,21 +1,13 @@
+import { z } from 'zod';
 import { type SyncIntent } from './plugin-sync.js';
 import { type MergeResult } from './plugins.js';
 export declare const NOT_ON_WORDPRESS_ORG = "not on WordPress.org";
-export type ComposerJson = {
-    config?: {
-        'allow-plugins'?: Record<string, boolean>;
-    };
-    extra?: {
-        'installer-paths'?: Record<string, string[]>;
-    };
-    name?: string;
-    repositories?: Array<{
-        type: string;
-        url: string;
-    }>;
-    require?: Record<string, string>;
-    'require-dev'?: Record<string, string>;
-};
+export declare const COMPOSER_JSON: z.ZodObject<{
+    require: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    'require-dev': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$loose>;
+export type ComposerJson = z.infer<typeof COMPOSER_JSON>;
+export declare function parseComposerJson(raw: string): ComposerJson;
 export declare function readComposerJson(): Promise<ComposerJson | null>;
 export declare function readComposerLock(): Promise<null | string>;
 export declare function getComposerManagedSlugs(composerJson: ComposerJson): string[];

package/dist/utils/composer.js

@@ -2,17 +2,41 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import writeFileAtomic from 'write-file-atomic';
+import { z } from 'zod';
+import { errorMessage } from '../lib/narrow.js';
 import { withSpinner } from '../lib/spinner.js';
+import {} from './plugin-sync.js';
+import {} from './plugins.js';
 import { isExactVersion } from './version.js';
 // Why pullIntoComposerJson skips a plugin it can't install: premium or custom, not on WPackagist.
 export const NOT_ON_WORDPRESS_ORG = 'not on WordPress.org';
+// Only the sections the CLI reads are checked: the rest is Composer's own business, and goes
+// back to disk untouched.
+export const COMPOSER_JSON = z.looseObject({
+    require: z.record(z.string(), z.string('"require" must map each package to a version constraint'), '"require" must be an object').optional(),
+    'require-dev': z
+        .record(z.string(), z.string('"require-dev" must map each package to a version constraint'), '"require-dev" must be an object')
+        .optional(),
+}, 'expected a JSON object');
+// Returns the parsed object itself, not zod's copy: zod's output moves the checked keys first, and
+// pullIntoComposerJson writes this object back to the user's composer.json.
+export function parseComposerJson(raw) {
+    const parsed = JSON.parse(raw);
+    if (isComposerJson(parsed))
+        return parsed;
+    const issues = COMPOSER_JSON.safeParse(parsed).error?.issues ?? [];
+    throw new Error(`Invalid composer.json: ${issues.map(({ message }) => message).join(', ')}`);
+}
+function isComposerJson(value) {
+    return COMPOSER_JSON.safeParse(value).success;
+}
 export async function readComposerJson() {
     const path = join(process.cwd(), 'composer.json');
     if (!existsSync(path))
         return null;
     try {
         const content = await readFile(path, 'utf8');
-        return JSON.parse(content);
+        return parseComposerJson(content);
     }
     catch {
         return null;
@@ -48,7 +72,7 @@ async function isOnWordPressOrg(kind, slug) {
         response = await withSpinner(`Checking WordPress.org for ${slug}`, async () => fetch(url));
     }
     catch (error) {
-        throw fail(`network error: ${error.message}`);
+        throw fail(`network error: ${errorMessage(error)}`);
     }
     if (response.status === 404)
         return false;
@@ -77,15 +101,16 @@ function planComposerPull(composerJson, prefix, incoming) {
     const require = composerJson.require ?? {};
     const allPackages = { ...require, ...composerJson['require-dev'] };
     const providedBy = new Map(Object.keys(allPackages)
-        .filter((name) => !name.startsWith(prefix) && name.includes('/'))
+        .filter((name) => !name.startsWith('wpackagist-plugin/') && !name.startsWith('wpackagist-theme/') && name.includes('/'))
         .map((name) => [name.split('/', 2)[1], name]));
     const result = { added: [], merged: {}, skipped: [], updated: [] };
     const candidates = [];
     for (const [slug, version] of Object.entries(incoming)) {
         const name = prefix + slug;
         const provider = providedBy.get(slug);
-        if (Object.hasOwn(allPackages, name)) {
-            const outcome = classifyDeclared(allPackages[name], version, Object.hasOwn(require, name));
+        const declared = Object.hasOwn(allPackages, name) ? allPackages[name] : undefined;
+        if (declared !== undefined) {
+            const outcome = classifyDeclared(declared, version, Object.hasOwn(require, name));
             if ('skip' in outcome) {
                 result.skipped.push({ reason: outcome.skip, slug });
                 continue;
@@ -98,7 +123,7 @@ function planComposerPull(composerJson, prefix, incoming) {
             result.skipped.push({ reason: `provided by ${provider}`, slug });
         }
         else {
-            candidates.push(slug);
+            candidates.push([slug, version]);
         }
     }
     return { candidates, result };
@@ -112,14 +137,14 @@ function planComposerPull(composerJson, prefix, incoming) {
 // - A slug provided by another package (acme/<slug>) or absent from WordPress.org is skipped.
 export async function pullIntoComposerJson(path, kind, incoming, { dryRun, log }) {
     const raw = await readFile(path, 'utf8');
-    const composerJson = JSON.parse(raw);
+    const composerJson = parseComposerJson(raw);
     const prefix = `wpackagist-${kind}/`;
     const { candidates, result } = planComposerPull(composerJson, prefix, incoming);
-    const found = await Promise.all(candidates.map(async (slug) => isOnWordPressOrg(kind, slug)));
-    for (const [i, slug] of candidates.entries()) {
-        if (found[i]) {
+    const checked = await Promise.all(candidates.map(async ([slug, version]) => ({ onWordPressOrg: await isOnWordPressOrg(kind, slug), slug, version })));
+    for (const { onWordPressOrg, slug, version } of checked) {
+        if (onWordPressOrg) {
             result.added.push(slug);
-            result.merged[slug] = incoming[slug];
+            result.merged[slug] = version;
         }
         else {
             result.skipped.push({ reason: NOT_ON_WORDPRESS_ORG, slug });
@@ -146,21 +171,23 @@ export async function pullIntoComposerJson(path, kind, incoming, { dryRun, log }
 // Split a composer.json `require` map into the three intent namespaces the sync endpoint
 // understands. `composer/installers` is owned by the server scaffold, never sent.
 export function toIntent(require) {
-    const intent = { libraries: {}, plugins: {}, themes: {} };
+    const plugins = {};
+    const themes = {};
+    const libraries = {};
     for (const [name, constraint] of Object.entries(require)) {
         if (name === 'composer/installers')
             continue;
         if (name.startsWith('wpackagist-plugin/')) {
-            intent.plugins[name.slice('wpackagist-plugin/'.length)] = constraint;
+            plugins[name.slice('wpackagist-plugin/'.length)] = constraint;
         }
         else if (name.startsWith('wpackagist-theme/')) {
-            intent.themes[name.slice('wpackagist-theme/'.length)] = constraint;
+            themes[name.slice('wpackagist-theme/'.length)] = constraint;
         }
         else {
-            intent.libraries[name] = constraint;
+            libraries[name] = constraint;
         }
     }
-    return intent;
+    return { libraries, plugins, themes };
 }
 // What a push installs: `require`, plus `require-dev` on the local environment only (Query
 // Monitor, or a premium plugin's free edition to develop against). A remote site never gets

package/dist/utils/declared-type-format.js

@@ -1,5 +1,7 @@
 import { basename } from 'node:path';
+import { z } from 'zod';
 import { parseHtmlHeader, titleFromSlug } from './page-format.js';
+import {} from './resource-dirs.js';
 export const CPT_SPEC = {
     arrayArgs: { capabilities: [], labels: [], rewrite: [true, false], supports: [false], taxonomies: [], template: [] },
     cliName: 'cpt',
@@ -31,15 +33,16 @@ export const TAXONOMY_SPEC = {
     // register_taxonomy() creates the default term when it doesn't exist yet.
     termArgs: ['default_term'],
 };
-const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-// register_post_meta()'s `type` values, each with the check its `default` must pass.
+const JSON_OBJECT = z.record(z.string(), z.unknown());
+const isObject = (value) => JSON_OBJECT.safeParse(value).success;
+// register_post_meta()'s `type` values, each with the schema its `default` must pass.
 const META_TYPES = {
-    array: Array.isArray,
-    boolean: (value) => typeof value === 'boolean',
-    integer: Number.isSafeInteger,
-    number: (value) => typeof value === 'number',
-    object: isObject,
-    string: (value) => typeof value === 'string',
+    array: z.array(z.unknown()),
+    boolean: z.boolean(),
+    integer: z.int(),
+    number: z.number(),
+    object: JSON_OBJECT,
+    string: z.string(),
 };
 function checkMetaRest(key, type, rest) {
     if (typeof rest !== 'boolean' && !isObject(rest))
@@ -54,7 +57,7 @@ function checkMetaRest(key, type, rest) {
     }
 }
 function checkMetaKey(key, meta) {
-    if (!/^[a-zA-Z0-9_-]{1,255}$/.test(key))
+    if (!/^[\w-]{1,255}$/.test(key))
         throw new Error(`"${key}" is not a valid meta key: 1 to 255 letters, digits, "_" or "-"`);
     if (!isObject(meta))
         throw new Error(`"${key}" must be a JSON object of register_post_meta() arguments`);
@@ -62,13 +65,14 @@ function checkMetaKey(key, meta) {
     if (code)
         throw new Error(`"${key}": "${code}" runs PHP code, use a hook instead of a file for it`);
     const { type } = meta;
-    if (typeof type !== 'string' || !Object.hasOwn(META_TYPES, type)) {
+    const schema = typeof type === 'string' && Object.hasOwn(META_TYPES, type) ? META_TYPES[type] : undefined;
+    if (typeof type !== 'string' || !schema) {
         throw new Error(`"${key}": "type" must be one of ${Object.keys(META_TYPES).join(', ')}`);
     }
     if (Object.hasOwn(meta, 'single') && typeof meta.single !== 'boolean')
         throw new Error(`"${key}": "single" must be true or false`);
-    checkMetaRest(key, type, meta.show_in_rest ?? false);
-    if (Object.hasOwn(meta, 'default') && !META_TYPES[type](meta.default))
+    checkMetaRest(key, type, Object.hasOwn(meta, 'show_in_rest') ? meta.show_in_rest : false);
+    if (Object.hasOwn(meta, 'default') && !schema.safeParse(meta.default).success)
         throw new Error(`"${key}": "default" must be a ${type}`);
 }
 // Same checks as the plugin's PostMetaService::assertArgs(): the file is `key => register_post_meta()
@@ -99,7 +103,7 @@ function checkRoleArgs(args) {
     if (typeof args.name !== 'string' || args.name.trim() === '')
         throw new Error('"name" must be a non-empty string');
     const capabilities = args.capabilities ?? {};
-    if (!isObject(capabilities) || Object.values(capabilities).some((granted) => typeof granted !== 'boolean')) {
+    if (!z.record(z.string(), z.boolean()).safeParse(capabilities).success) {
         throw new Error('"capabilities" must map each capability name to true or false');
     }
 }
@@ -132,6 +136,8 @@ const PATTERN_HEADER = {
     title: { key: 'title', type: 'text' },
     'viewport-width': { key: 'viewportWidth', type: 'integer' },
 };
+// Typed lookups by header name: a plain object index needs `keyof typeof` on a string.
+const PATTERN_HEADER_BY_NAME = new Map(Object.entries(PATTERN_HEADER));
 function readPatternValue(header, type, value) {
     if (type === 'list')
         return value.split(',').map((item) => item.trim()).filter(Boolean);
@@ -152,8 +158,10 @@ export function parsePatternFile(slug, raw) {
     const { body, meta } = parseHtmlHeader(raw, Object.keys(PATTERN_HEADER));
     const args = { title: titleFromSlug(slug) };
     for (const [header, value] of Object.entries(meta)) {
-        const { key, type } = PATTERN_HEADER[header];
-        args[key] = readPatternValue(header, type, value);
+        // parseHtmlHeader already refuses any other header name.
+        const spec = PATTERN_HEADER_BY_NAME.get(header);
+        if (spec)
+            args[spec.key] = readPatternValue(header, spec.type, value);
     }
     args.content = body;
     return args;
@@ -199,11 +207,10 @@ export function itemEndpoint(spec, slug) {
     return `${spec.endpoint}/${encodeURIComponent(slug)}`;
 }
 export function parseDeclaredArgs(raw) {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    const result = JSON_OBJECT.safeParse(JSON.parse(raw));
+    if (!result.success)
         throw new Error('not a JSON object of arguments');
-    }
-    return parsed;
+    return result.data;
 }
 // `lps validate`'s check of one file: the file name is a valid slug, array arguments are arrays,
 // and no argument is code.

package/dist/utils/form-format.js

@@ -1,3 +1,4 @@
+import { isRecord } from '../lib/narrow.js';
 export const FORM_ENDPOINT = 'loopress/v1/forms';
 export function formEndpoint(id) {
     return `${FORM_ENDPOINT}/${id}`;
@@ -7,7 +8,6 @@ export function getFormId(data) {
     return Number.isSafeInteger(id) && id > 0 ? id : null;
 }
 export function getFormTitle(data) {
-    const settings = data.settings;
-    const title = settings?.form_title;
+    const title = isRecord(data.settings) ? data.settings.form_title : undefined;
     return typeof title === 'string' && title.trim() !== '' ? title : '(untitled)';
 }

package/dist/utils/loopress-config.js

@@ -1,6 +1,8 @@
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { isRecord } from '../lib/narrow.js';
+import {} from '../types/project-config.generated.js';
 // Only a missing file is treated as "no config" (returns {}). A file that exists but
 // fails to read or parse throws, so callers don't silently fall back to the global
 // current environment when loopress.json is actually broken.
@@ -9,12 +11,18 @@ export async function readLocalConfig() {
     if (!existsSync(configPath))
         return {};
     const content = await readFile(configPath, 'utf8');
+    let parsed;
     try {
-        return JSON.parse(content);
+        parsed = JSON.parse(content);
     }
     catch {
         throw new Error('loopress.json is not valid JSON. Fix or delete it, then run `lps init` again.');
     }
+    if (!isRecord(parsed) || Array.isArray(parsed))
+        throw new Error('loopress.json must be a JSON object. Fix or delete it, then run `lps init` again.');
+    // Its keys are checked by `lps validate` (lib/validate-local.ts), not here: schemas/project-config.schema.json
+    // refuses unknown keys, which would stop every command over one stray key.
+    return parsed;
 }
 export async function writeLocalConfig(config) {
     const configPath = join(process.cwd(), 'loopress.json');

package/dist/utils/menu-format.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 export declare const MENU_ENDPOINT = "loopress/v1/menus";
 export declare const MENU_LOCATIONS_ENDPOINT = "loopress/v1/menu-locations";
 export declare function menuEndpoint(slug: string): string;
@@ -20,5 +21,6 @@ export type Menu = {
     slug: string;
     warnings: string[];
 };
-export type MenuLocations = Record<string, null | string>;
+export declare const MENU_LOCATIONS: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>;
+export type MenuLocations = z.infer<typeof MENU_LOCATIONS>;
 export declare function getMenuSlug(data: Record<string, unknown>): null | string;

package/dist/utils/menu-format.js

@@ -1,8 +1,13 @@
+import { z } from 'zod';
 export const MENU_ENDPOINT = 'loopress/v1/menus';
 export const MENU_LOCATIONS_ENDPOINT = 'loopress/v1/menu-locations';
 export function menuEndpoint(slug) {
     return `${MENU_ENDPOINT}/${encodeURIComponent(slug)}`;
 }
+// location => menu slug, or null when unassigned. Scoped to whichever theme is active on
+// whichever environment answered the request (a theme_mod, see MenuService::getLocations()).
+// Location slug -> assigned menu slug, null for an unassigned location.
+export const MENU_LOCATIONS = z.record(z.string(), z.string().nullable());
 export function getMenuSlug(data) {
     return typeof data.slug === 'string' && data.slug.trim() !== '' ? data.slug : null;
 }

package/dist/utils/option-format.d.ts

@@ -6,8 +6,8 @@ export type OptionRefs = Record<string, string>;
 export type LocalOption = {
     autoload: string;
     name: string;
-    readonly?: boolean;
-    refs?: OptionRefs;
+    readonly?: boolean | undefined;
+    refs?: OptionRefs | undefined;
     value: unknown;
 };
 export type RemoteOption = {

package/dist/utils/option-format.js

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 export const OPTIONS_ENDPOINT = 'loopress/v1/options';
 // `refs` asks WordPress to return the declared post references as paths (see OptionRefs).
 export function optionEndpoint(name, refs) {
@@ -49,32 +50,21 @@ export function partitionByReadonly(tracked) {
         (option.readonly ? skipped : writable).push(option);
     return { skipped, writable };
 }
-export function parseLocalOption(raw) {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error('not a JSON object');
-    }
-    const { autoload, name, refs, value } = parsed;
-    if (typeof name !== 'string' || name === '') {
-        throw new Error('missing a "name" string');
-    }
-    if (typeof autoload !== 'string') {
-        throw new TypeError('missing an "autoload" string');
-    }
+const REFS_ERROR = '"refs" must map a value path to a post type, e.g. {"purchase_page": "page"}';
+// Each check's message is the error thrown for it, the first failing one wins. Loose: unknown
+// keys (`readonly`, future ones) pass through untouched.
+const LOCAL_OPTION = z.looseObject({
+    name: z.string('missing a "name" string').min(1, 'missing a "name" string'),
+    autoload: z.string('missing an "autoload" string'),
     // `value` itself is deliberately untyped (a WP option can hold any JSON-safe value, including
     // null); only the key's presence is checked, so a hand-edited file that dropped it entirely is
     // rejected here rather than silently pushing an `undefined` value to WordPress.
-    if (value === undefined) {
-        throw new Error('missing a "value" field');
-    }
-    if (refs !== undefined && !isOptionRefs(refs)) {
-        throw new TypeError('"refs" must map a value path to a post type, e.g. {"purchase_page": "page"}');
-    }
-    return parsed;
-}
-function isOptionRefs(refs) {
-    return (typeof refs === 'object' &&
-        refs !== null &&
-        !Array.isArray(refs) &&
-        Object.entries(refs).every(([path, postType]) => path !== '' && typeof postType === 'string' && postType !== ''));
+    value: z.custom((value) => value !== undefined, 'missing a "value" field'),
+    refs: z.record(z.string().min(1, REFS_ERROR), z.string(REFS_ERROR).min(1, REFS_ERROR), REFS_ERROR).optional(),
+}, 'not a JSON object');
+export function parseLocalOption(raw) {
+    const result = LOCAL_OPTION.safeParse(JSON.parse(raw));
+    if (!result.success)
+        throw new TypeError(result.error.issues[0]?.message);
+    return result.data;
 }

package/dist/utils/page-format.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
+import { errorCode, errorMessage, isOneOf } from '../lib/narrow.js';
 export const PAGES_ENDPOINT = 'loopress/v1/pages';
 // Mirrored server-side in PagesController. No leading, trailing or doubled hyphen: WordPress's
 // sanitize_title() would rewrite those, and the page would no longer match its file name.
@@ -45,7 +46,7 @@ export function titleFromSlug(slug) {
 export function parsePageFile(slug, raw) {
     const { body, meta } = parseHtmlHeader(raw, HEADER_KEYS);
     const status = meta.status ?? 'draft';
-    if (!PAGE_STATUSES.includes(status)) {
+    if (!isOneOf(PAGE_STATUSES, status)) {
         throw new Error(`status "${status}" is not one of ${PAGE_STATUSES.join(', ')}`);
     }
     return {
@@ -53,9 +54,9 @@ export function parsePageFile(slug, raw) {
         hideTitle: parseBoolean('hide-title', meta['hide-title']),
         html: body,
         slug,
-        status: status,
+        status,
         template: meta.template ?? '',
-        title: meta.title || titleFromSlug(slug),
+        title: (meta.title ?? '') || titleFromSlug(slug),
     };
 }
 // Splits the optional `key: value` HTML comment header off `raw`. Shared with templates/.
@@ -64,7 +65,7 @@ export function parseHtmlHeader(raw, keys) {
     const meta = {};
     if (!header)
         return { body: raw, meta };
-    for (const line of header[1].split(/\r?\n/)) {
+    for (const line of (header[1] ?? '').split(/\r?\n/)) {
         if (line.trim() === '')
             continue;
         const colon = line.indexOf(':');
@@ -92,7 +93,7 @@ export async function readLocalHtmlFiles(dir, parse, slugRule = PAGE_SLUG_RULE)
         entries = await readdir(dir, { withFileTypes: true });
     }
     catch (error) {
-        if (error.code === 'ENOENT')
+        if (errorCode(error) === 'ENOENT')
             return { files: [], problems: [] };
         throw error;
     }
@@ -120,7 +121,7 @@ export async function readLocalHtmlFiles(dir, parse, slugRule = PAGE_SLUG_RULE)
             files.push(parse(slug, await readFile(filePath, 'utf8')));
         }
         catch (error) {
-            problems.push({ file: filePath, message: error.message });
+            problems.push({ file: filePath, message: errorMessage(error) });
         }
     }
     return { files, problems };

package/dist/utils/php-top-level.js

@@ -10,7 +10,7 @@ const OPEN_TAG = /<\?php\b/i;
 export function firstTopLevelSideEffect(content) {
     if (content.search(OPEN_TAG) !== 0)
         return 'inline HTML before <?php';
-    const state = { atStart: true, braces: [], depth: 0, namespaceHeader: false };
+    const state = { atStart: true, attribute: 0, braces: [], depth: 0, namespaceHeader: false };
     for (const token of lex(content.slice(5))) {
         const found = step(state, token);
         if (found !== null)
@@ -36,6 +36,8 @@ export function startsWithStrictTypes(content) {
 function step(state, token) {
     if (token.type === 'html')
         return inlineHtml(state, token);
+    if (state.attribute > 0 || token.type === 'attribute')
+        return skipAttribute(state, token);
     const statementStart = state.depth === 0 && state.atStart;
     switch (token.text) {
         case ';': {
@@ -64,6 +66,15 @@ function step(state, token) {
         }
     }
 }
+// An attribute (`#[Attr(...)]`) only decorates what follows it, so the statement still starts
+// after its closing `]`: `#[Attr] foo();` must report `foo`.
+function skipAttribute(state, token) {
+    if (token.type === 'attribute' || token.text === '[')
+        state.attribute += 1;
+    else if (token.text === ']')
+        state.attribute -= 1;
+    return null;
+}
 // A template inside a class or function body (`?> <p>...</p> <?php`) only runs when it is called.
 function inlineHtml(state, token) {
     if (state.depth > 0)
@@ -86,7 +97,7 @@ function openBrace(state, statementStart) {
     return null;
 }
 function isDeclaration(token) {
-    return token.type === 'attribute' || (token.type === 'word' && ALLOWED.has(token.text.toLowerCase()));
+    return token.type === 'word' && ALLOWED.has(token.text.toLowerCase());
 }
 function* lex(source) {
     let i = skipTrivia(source, 0);
@@ -126,13 +137,13 @@ function readToken(source, i) {
     }
     if (source.startsWith('#[', i))
         return [{ text: '#[', type: 'attribute' }, i + 2];
-    if (source.startsWith('<<<', i) || `'"\``.includes(source[i])) {
+    if (source.startsWith('<<<', i) || `'"\``.includes(source.charAt(i))) {
         return [{ text: source[i] === '`' ? '`' : 'a string', type: 'string' }, skipString(source, i)];
     }
     const word = /^[\w$\\]+/.exec(source.slice(i));
     if (word)
         return [{ text: word[0], type: 'word' }, i + word[0].length];
-    return [{ text: source[i], type: 'punct' }, i + 1];
+    return [{ text: source.charAt(i), type: 'punct' }, i + 1];
 }
 // Index right after the string (quoted, backtick, heredoc or nowdoc) starting at `i`.
 function skipString(source, i) {