@loopress/cli 0.32.1 → 0.33.0

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.d.ts

@@ -2,6 +2,7 @@ export declare const ACF_OBJECT_TYPES: readonly ["field-groups", "post-types", "
 export type AcfObjectType = (typeof ACF_OBJECT_TYPES)[number];
 export declare function acfEndpoint(type: AcfObjectType): string;
 export declare function acfObjectEndpoint(type: AcfObjectType, key: string): string;
+export declare function acfNormalizeEndpoint(type: AcfObjectType): string;
 export declare function getAcfKey(data: Record<string, unknown>): null | string;
 export declare function acfFieldChanges(before: unknown, after: unknown): {
     added: string[];

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}`;
@@ -9,6 +10,11 @@ export function acfEndpoint(type) {
 export function acfObjectEndpoint(type, key) {
     return `${acfEndpoint(type)}/${key}`;
 }
+// POST route returning local objects the way the site would store them, defaults filled in,
+// nothing saved (see resource-state.ts's acfProvider).
+export function acfNormalizeEndpoint(type) {
+    return `loopress/v1/acf/normalize/${type}`;
+}
 // Deliberately loose: ACF's own export JSON is large, deeply nested, and versioned by ACF
 // itself (new settings appear across ACF releases). We only need `key` for filenames/identity;
 // everything else round-trips through pull/push untouched, so there's no generated type for it
@@ -18,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))

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 = {