@loopress/cli 0.28.0 → 0.30.0

package/dist/lib/wp-client.js

@@ -1,5 +1,6 @@
 import got from 'got';
 import { Buffer } from 'node:buffer';
+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
 // by its config name (the same "local" environment `lps dev` targets), never by the URL's host.
@@ -81,7 +82,7 @@ export class WpClient {
     async request(method, path, json, options) {
         const timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS;
         try {
-            const response = await this.client(path, { json, method, timeout: { request: timeoutMs } });
+            const response = await withSpinner(`Waiting for ${new URL(this.siteUrl).host}`, async () => this.client(path, { json, method, timeout: { request: timeoutMs } }));
             return (response.body ? JSON.parse(response.body) : undefined);
         }
         catch (error) {
@@ -93,6 +94,11 @@ export function isNotFoundError(error) {
     const cause = error?.cause;
     return cause?.response?.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;
+}
 // 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

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

@@ -1,5 +1,13 @@
 import got from 'got';
+import { withSpinner } from './spinner.js';
 export const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * WordPress 7.0 is the first version that accepts a loopback `http://127.0.0.1` success_url on
+ * authorize-application.php whatever the site's environment type (wp_is_authorize_application_redirect_url_valid).
+ * Earlier versions only accept it when WP_ENVIRONMENT_TYPE is `local`, which isn't exposed publicly,
+ * so a 6.x site is sent to manual entry even though a local one would have worked.
+ */
+const MIN_BROWSER_AUTH_MAJOR = 7;
 /**
  * Pre-flight checks run before starting the browser authorization flow, so failures
  * (unreachable site, blocked REST API, Application Passwords disabled) surface as an
@@ -15,7 +23,7 @@ export const REQUEST_TIMEOUT_MS = 10_000;
 export async function diagnoseWpSite(siteUrl) {
     let index;
     try {
-        index = await got.get(`${siteUrl}/wp-json/`, { timeout: { request: REQUEST_TIMEOUT_MS } }).json();
+        index = await withSpinner(`Checking ${siteUrl}`, async () => got.get(`${siteUrl}/wp-json/`, { timeout: { request: REQUEST_TIMEOUT_MS } }).json());
     }
     catch (error) {
         return {
@@ -29,8 +37,38 @@ export async function diagnoseWpSite(siteUrl) {
             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.`,
         };
     }
+    const version = await detectWpVersion(siteUrl);
+    if (version && Number(version.split('.', 1)[0]) < MIN_BROWSER_AUTH_MAJOR) {
+        return {
+            ok: false,
+            reason: `${siteUrl} runs WordPress ${version}. Before WordPress ${MIN_BROWSER_AUTH_MAJOR}.0, WordPress refuses to send the Application Password back to the CLI on this machine (http://127.0.0.1), so authorizing in the browser is not possible. Create an Application Password in wp-admin (Users > Profile) and enter it below.`,
+        };
+    }
     return { ok: true };
 }
+/**
+ * Best effort, from the public generator tag: the feed's `<generator>` first, then the home page
+ * `<meta name="generator">`. Security plugins often strip both, in which case this returns
+ * undefined and the browser flow is attempted anyway.
+ */
+async function detectWpVersion(siteUrl) {
+    const sources = [
+        { pattern: /<generator>[^<]*[?&]v=(\d+(?:\.\d+)*)/, url: `${siteUrl}/feed/` },
+        { pattern: /<meta name="generator" content="WordPress (\d+(?:\.\d+)*)/, url: `${siteUrl}/` },
+    ];
+    for (const { pattern, url } of sources) {
+        try {
+            const body = await withSpinner(`Checking ${siteUrl}`, async () => got.get(url, { timeout: { request: REQUEST_TIMEOUT_MS } }).text());
+            const version = pattern.exec(body)?.[1];
+            if (version)
+                return version;
+        }
+        catch {
+            // Feed disabled or page unreachable: try the next source.
+        }
+    }
+    return undefined;
+}
 function describe(error) {
     return error instanceof Error ? error.message : String(error);
 }

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

@@ -3,7 +3,7 @@
  */
 export interface LoopressGlobalConfiguration {
     /**
-     * Pointer to the currently active project and environment, or null if none is selected.
+     * Pointer to the currently active project, or null if none is selected. The environment is not stored: commands use --env, else the project's "local" environment, else its only one.
      */
     currentProject: null | CurrentProjectPointer;
     /**
@@ -15,10 +15,6 @@ export interface LoopressGlobalConfiguration {
     telemetry?: TelemetryConfig;
 }
 export interface CurrentProjectPointer {
-    /**
-     * Name of the currently active environment.
-     */
-    env: string;
     /**
      * Id of the currently active project.
      */

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

@@ -15,10 +15,6 @@ export interface LoopressProjectConfiguration {
      * Directory where ACF field groups, post types, taxonomies and options pages are read from and written to, relative to rootDir.
      */
     acfDir?: string;
-    /**
-     * Directory where SEO settings, post meta, and redirects (RankMath and Yoast SEO, whichever is active) are read from and written to, relative to rootDir.
-     */
-    seoDir?: string;
     /**
      * Directory where forms (WPForms today) are read from and written to, relative to rootDir.
      */
@@ -47,10 +43,38 @@ export interface LoopressProjectConfiguration {
      * Directory where block template parts (one <slug>.html per part, written to the Loopress child theme of the active block theme) are read from, relative to rootDir.
      */
     partDir?: string;
+    /**
+     * Directory of the theme's global CSS, relative to rootDir. Its style.css is the entry: it @imports the other files, bundled into the style.css of the Loopress child theme and loaded on every page.
+     */
+    cssDir?: string;
+    /**
+     * Directory of per-block CSS (one <namespace>/<block>.css per block, e.g. core/button.css), relative to rootDir. Each file is bundled into the Loopress child theme and only loaded on pages that render that block.
+     */
+    blockCssDir?: string;
     /**
      * Directory where explicitly tracked WordPress options (wp_options rows) are read from and written to, relative to rootDir. Only options added via `lps option add` live here, this is never the whole options table.
      */
     optionsDir?: string;
+    /**
+     * Directory where custom post types (one JSON file of register_post_type() arguments per post type, named <slug>.json) are read from and written to, relative to rootDir.
+     */
+    cptDir?: string;
+    /**
+     * Directory where taxonomies (one JSON file of register_taxonomy() arguments plus "object_type" per taxonomy, named <slug>.json) are read from and written to, relative to rootDir.
+     */
+    taxonomyDir?: string;
+    /**
+     * Directory where user roles (one JSON file of "name" and "capabilities" per role, named <slug>.json) are read from and written to, relative to rootDir.
+     */
+    roleDir?: string;
+    /**
+     * Directory where block patterns (one <slug>.html of block markup per pattern, registered as loopress/<slug>) are read from and written to, relative to rootDir.
+     */
+    patternDir?: string;
+    /**
+     * Directory where post meta keys (one JSON file per post type, named <post-type>.json, mapping each meta key to its register_post_meta() arguments) are read from and written to, relative to rootDir.
+     */
+    metaDir?: string;
     /**
      * Directory where nav menus (one JSON file per menu, plus menu-locations.json for the active theme's menu locations) are read from and written to, relative to rootDir.
      */

package/dist/utils/composer.d.ts

@@ -1,5 +1,6 @@
 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>;
@@ -29,4 +30,5 @@ export declare function pullIntoComposerJson(path: string, kind: 'plugin' | 'the
     log: (message: string) => void;
 }): Promise<ComposerPullResult>;
 export declare function toIntent(require: Record<string, string>): SyncIntent;
-export declare function wpackagistRequire(composerJson: ComposerJson, kind: 'plugin' | 'theme'): Record<string, string>;
+export declare function requireToInstall(composerJson: ComposerJson, includeDev: boolean): Record<string, string>;
+export declare function wpackagistRequire(composerJson: ComposerJson, kind: 'plugin' | 'theme', includeDev?: boolean): Record<string, string>;

package/dist/utils/composer.js

@@ -2,7 +2,10 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import writeFileAtomic from 'write-file-atomic';
+import { withSpinner } from '../lib/spinner.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';
 export async function readComposerJson() {
     const path = join(process.cwd(), 'composer.json');
     if (!existsSync(path))
@@ -42,7 +45,7 @@ async function isOnWordPressOrg(kind, slug) {
         'Loopress only adds packages WPackagist can serve. Retry once api.wordpress.org is reachable.');
     let response;
     try {
-        response = await fetch(url);
+        response = await withSpinner(`Checking WordPress.org for ${slug}`, async () => fetch(url));
     }
     catch (error) {
         throw fail(`network error: ${error.message}`);
@@ -100,7 +103,7 @@ function planComposerPull(composerJson, prefix, incoming) {
     }
     return { candidates, result };
 }
-// `lps plugin pull` / `lps theme pull` on a project that has a composer.json: pin installed
+// `lps plugin pull` / `lps theme version pull` on a project that has a composer.json: pin installed
 // packages to their live versions as `wpackagist-<kind>/<slug>` under `require`, leaving every
 // other key untouched. The server adds the WPackagist repository and composer/installers on push.
 // - A declared version constraint (^9.4, *, ...) is the user's intent: never overwritten, only an
@@ -119,7 +122,7 @@ export async function pullIntoComposerJson(path, kind, incoming, { dryRun, log }
             result.merged[slug] = incoming[slug];
         }
         else {
-            result.skipped.push({ reason: 'not on WordPress.org', slug });
+            result.skipped.push({ reason: NOT_ON_WORDPRESS_ORG, slug });
         }
     }
     if (!dryRun) {
@@ -159,11 +162,17 @@ export function toIntent(require) {
     }
     return intent;
 }
-// The `wpackagist-<kind>/<slug>` entries of a composer.json `require`, keyed by slug, with the
-// version or constraint as written.
-export function wpackagistRequire(composerJson, kind) {
+// 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
+// `require-dev`, the same split as `composer install --no-dev` on a production server.
+export function requireToInstall(composerJson, includeDev) {
+    return includeDev ? { ...composerJson.require, ...composerJson['require-dev'] } : { ...composerJson.require };
+}
+// The `wpackagist-<kind>/<slug>` entries of what a push installs (see requireToInstall), keyed
+// by slug, with the version or constraint as written.
+export function wpackagistRequire(composerJson, kind, includeDev = false) {
     const prefix = `wpackagist-${kind}/`;
-    return Object.fromEntries(Object.entries(composerJson.require ?? {})
+    return Object.fromEntries(Object.entries(requireToInstall(composerJson, includeDev))
         .filter(([name]) => name.startsWith(prefix))
         .map(([name, version]) => [name.slice(prefix.length), version]));
 }

package/dist/utils/declared-type-format.d.ts

@@ -0,0 +1,52 @@
+import { type ResourceDirKind } from './resource-dirs.js';
+export type DeclaredTypeSpec = {
+    arrayArgs: Record<string, unknown[]>;
+    checkArgs?: (args: DeclaredArgs) => void;
+    cliName: 'cpt' | 'meta' | 'pattern' | 'role' | 'taxonomy';
+    codeArgs: string[];
+    dir: string;
+    dirKind: ResourceDirKind;
+    endpoint: string;
+    file?: {
+        extension: string;
+        format(args: DeclaredArgs): string;
+        parse(slug: string, raw: string): DeclaredArgs;
+    };
+    noun: string;
+    plural: string;
+    registeredEndpoint: string;
+    registerFunction: string;
+    slugMaxLength: number;
+    termArgs: string[];
+};
+export declare const CPT_SPEC: DeclaredTypeSpec;
+export declare const TAXONOMY_SPEC: DeclaredTypeSpec;
+export declare const META_SPEC: DeclaredTypeSpec;
+export declare const ROLE_SPEC: DeclaredTypeSpec;
+export declare function parsePatternFile(slug: string, raw: string): DeclaredArgs;
+export declare function formatPatternFile(args: DeclaredArgs): string;
+export declare const PATTERN_SPEC: DeclaredTypeSpec;
+export declare function fileExtension(spec: DeclaredTypeSpec): string;
+export declare function parseDeclaredFile(spec: DeclaredTypeSpec, filePath: string, raw: string): {
+    args: DeclaredArgs;
+    slug: string;
+};
+export declare function formatDeclaredFile(spec: DeclaredTypeSpec, args: DeclaredArgs): string;
+export declare function itemEndpoint(spec: DeclaredTypeSpec, slug: string): string;
+export type DeclaredArgs = Record<string, unknown>;
+export type RemoteDeclaredType = {
+    args: DeclaredArgs;
+    revision: string;
+    slug: string;
+};
+export type RegisteredItem = {
+    conflict: boolean;
+    count: number;
+    label: string;
+    managed: boolean;
+    objectTypes?: string[];
+    slug: string;
+    source: 'acf' | 'cptui' | 'loopress' | 'other' | 'wordpress';
+};
+export declare function parseDeclaredArgs(raw: string): DeclaredArgs;
+export declare function declaredFileChecker(spec: DeclaredTypeSpec): (raw: string, filePath: string) => void;

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

@@ -0,0 +1,233 @@
+import { basename } from 'node:path';
+import { parseHtmlHeader, titleFromSlug } from './page-format.js';
+export const CPT_SPEC = {
+    arrayArgs: { capabilities: [], labels: [], rewrite: [true, false], supports: [false], taxonomies: [], template: [] },
+    cliName: 'cpt',
+    codeArgs: ['register_meta_box_cb', 'rest_controller_class', 'autosave_rest_controller_class', 'revisions_rest_controller_class'],
+    dir: 'cpt',
+    dirKind: 'cpt',
+    endpoint: 'loopress/v1/post-types',
+    noun: 'post type',
+    plural: 'post types',
+    registeredEndpoint: 'loopress/v1/registered-post-types',
+    registerFunction: 'register_post_type()',
+    slugMaxLength: 20,
+    termArgs: [],
+};
+// `object_type` is the one key that isn't a register_taxonomy() argument: its second parameter,
+// the post types the taxonomy attaches to. Kept in the same file, split off by the plugin.
+export const TAXONOMY_SPEC = {
+    arrayArgs: { capabilities: [], labels: [], object_type: [], rewrite: [true, false] },
+    cliName: 'taxonomy',
+    codeArgs: ['meta_box_cb', 'meta_box_sanitize_cb', 'update_count_callback', 'rest_controller_class'],
+    dir: 'taxonomies',
+    dirKind: 'taxonomy',
+    endpoint: 'loopress/v1/taxonomies',
+    noun: 'taxonomy',
+    plural: 'taxonomies',
+    registeredEndpoint: 'loopress/v1/registered-taxonomies',
+    registerFunction: 'register_taxonomy()',
+    slugMaxLength: 32,
+    // 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 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',
+};
+function checkMetaRest(key, type, rest) {
+    if (typeof rest !== 'boolean' && !isObject(rest))
+        throw new Error(`"${key}": "show_in_rest" must be true, false or an object`);
+    // WordPress calls it with each value on every REST read (WP_REST_Meta_Fields).
+    if (isObject(rest) && Object.hasOwn(rest, 'prepare_callback')) {
+        throw new Error(`"${key}": "show_in_rest.prepare_callback" runs PHP code, use a hook instead of a file for it`);
+    }
+    // WordPress silently leaves an array or object key out of REST without a schema.
+    if (rest !== false && (type === 'array' || type === 'object') && !(isObject(rest) && isObject(rest.schema))) {
+        throw new Error(`"${key}": a ${type} exposed in REST needs "show_in_rest": { "schema": {...} }`);
+    }
+}
+function checkMetaKey(key, meta) {
+    if (!/^[a-zA-Z0-9_-]{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`);
+    const code = ['sanitize_callback', 'auth_callback'].find((name) => Object.hasOwn(meta, name));
+    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)) {
+        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))
+        throw new Error(`"${key}": "default" must be a ${type}`);
+}
+// Same checks as the plugin's PostMetaService::assertArgs(): the file is `key => register_post_meta()
+// arguments`, so the code and type checks are one level deeper than for post types.
+function checkMetaArgs(args) {
+    for (const [key, meta] of Object.entries(args))
+        checkMetaKey(key, meta);
+}
+// The file name is the post type (`post` and `page` included), the keys are meta keys. Only the
+// keys are declared, never their values.
+export const META_SPEC = {
+    arrayArgs: {},
+    checkArgs: checkMetaArgs,
+    cliName: 'meta',
+    codeArgs: [],
+    dir: 'meta',
+    dirKind: 'meta',
+    endpoint: 'loopress/v1/post-meta',
+    noun: 'post meta',
+    plural: 'post meta',
+    registeredEndpoint: 'loopress/v1/registered-post-meta',
+    registerFunction: 'register_post_meta()',
+    slugMaxLength: 20,
+    termArgs: [],
+};
+// Same checks as the plugin's RoleService::assertArgs().
+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')) {
+        throw new Error('"capabilities" must map each capability name to true or false');
+    }
+}
+// `{"name": ..., "capabilities": {cap: bool}}`, added in memory on every request, never written
+// to the roles option. Built-in roles are refused by the plugin.
+export const ROLE_SPEC = {
+    arrayArgs: { capabilities: [] },
+    checkArgs: checkRoleArgs,
+    cliName: 'role',
+    codeArgs: [],
+    dir: 'roles',
+    dirKind: 'role',
+    endpoint: 'loopress/v1/roles',
+    noun: 'role',
+    plural: 'roles',
+    registeredEndpoint: 'loopress/v1/registered-roles',
+    registerFunction: 'add_role()',
+    slugMaxLength: 50,
+    termArgs: [],
+};
+// Header key => register_block_pattern() property, and how its text is read.
+const PATTERN_HEADER = {
+    'block-types': { key: 'blockTypes', type: 'list' },
+    categories: { key: 'categories', type: 'list' },
+    description: { key: 'description', type: 'text' },
+    inserter: { key: 'inserter', type: 'boolean' },
+    keywords: { key: 'keywords', type: 'list' },
+    'post-types': { key: 'postTypes', type: 'list' },
+    'template-types': { key: 'templateTypes', type: 'list' },
+    title: { key: 'title', type: 'text' },
+    'viewport-width': { key: 'viewportWidth', type: 'integer' },
+};
+function readPatternValue(header, type, value) {
+    if (type === 'list')
+        return value.split(',').map((item) => item.trim()).filter(Boolean);
+    if (type === 'boolean') {
+        if (value !== 'true' && value !== 'false')
+            throw new Error(`"${header}" must be "true" or "false", got "${value}"`);
+        return value === 'true';
+    }
+    if (type === 'integer') {
+        if (!/^\d+$/.test(value))
+            throw new Error(`"${header}" must be a whole number, got "${value}"`);
+        return Number(value);
+    }
+    return value;
+}
+// A pattern file is its block markup, opened by the same `key: value` comment header as a page.
+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);
+    }
+    args.content = body;
+    return args;
+}
+export function formatPatternFile(args) {
+    const lines = Object.entries(PATTERN_HEADER)
+        .filter(([, { key }]) => args[key] !== undefined)
+        .map(([header, { key }]) => `${header}: ${Array.isArray(args[key]) ? args[key].join(', ') : String(args[key])}`);
+    return `<!--\n${lines.join('\n')}\n-->\n${typeof args.content === 'string' ? args.content : ''}`;
+}
+function checkPatternArgs(args) {
+    if (typeof args.title !== 'string' || args.title.trim() === '')
+        throw new Error('"title" must be a non-empty string');
+}
+// Registered as `loopress/<slug>`, referenced with `<!-- wp:pattern {"slug":"loopress/<slug>"} /-->`.
+export const PATTERN_SPEC = {
+    arrayArgs: { blockTypes: [], categories: [], keywords: [], postTypes: [], templateTypes: [] },
+    checkArgs: checkPatternArgs,
+    cliName: 'pattern',
+    codeArgs: ['filePath'],
+    dir: 'patterns',
+    dirKind: 'pattern',
+    endpoint: 'loopress/v1/patterns',
+    file: { extension: '.html', format: formatPatternFile, parse: parsePatternFile },
+    noun: 'pattern',
+    plural: 'patterns',
+    registeredEndpoint: 'loopress/v1/registered-patterns',
+    registerFunction: 'register_block_pattern()',
+    slugMaxLength: 100,
+    termArgs: [],
+};
+export function fileExtension(spec) {
+    return spec.file?.extension ?? '.json';
+}
+export function parseDeclaredFile(spec, filePath, raw) {
+    const slug = basename(filePath, fileExtension(spec));
+    return { args: spec.file ? spec.file.parse(slug, raw) : parseDeclaredArgs(raw), slug };
+}
+export function formatDeclaredFile(spec, args) {
+    return spec.file ? spec.file.format(args) : JSON.stringify(args, null, 2) + '\n';
+}
+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)) {
+        throw new Error('not a JSON object of arguments');
+    }
+    return parsed;
+}
+// `lps validate`'s check of one file: the file name is a valid slug, array arguments are arrays,
+// and no argument is code.
+export function declaredFileChecker(spec) {
+    const slugPattern = new RegExp(`^[a-z0-9_-]{1,${spec.slugMaxLength}}$`);
+    return (raw, filePath) => {
+        const slug = basename(filePath, fileExtension(spec));
+        if (!slugPattern.test(slug)) {
+            throw new Error(`"${slug}" is not a valid ${spec.noun} slug: 1 to ${spec.slugMaxLength} lowercase letters, digits, "_" or "-"`);
+        }
+        const { args } = parseDeclaredFile(spec, filePath, raw);
+        for (const [key, alsoAllowed] of Object.entries(spec.arrayArgs)) {
+            const value = args[key];
+            if (Object.hasOwn(args, key) && (typeof value !== 'object' || value === null) && !alsoAllowed.includes(value)) {
+                const or = alsoAllowed.length > 0 ? ' (or ' + alsoAllowed.join(', ') + ')' : '';
+                throw new Error(`"${key}" must be a JSON object or array${or}`);
+            }
+        }
+        const term = spec.termArgs.find((key) => Object.hasOwn(args, key));
+        if (term)
+            throw new Error(`"${term}" creates a term, and Loopress doesn't sync terms: remove it and create the term in wp-admin`);
+        const code = spec.codeArgs.find((key) => Object.hasOwn(args, key));
+        if (code)
+            throw new Error(`"${code}" runs PHP code, use a hook instead of a file for it`);
+        spec.checkArgs?.(args);
+    };
+}

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

@@ -1,11 +1,13 @@
 export declare const OPTIONS_ENDPOINT = "loopress/v1/options";
-export declare function optionEndpoint(name: string): string;
+export declare function optionEndpoint(name: string, refs?: OptionRefs): string;
 export declare const RESERVED_OPTION_NAMES: readonly ["active_plugins", "stylesheet", "template"];
 export declare const READONLY_BY_DEFAULT_OPTION_NAMES: readonly ["siteurl", "home", "db_version", "initial_db_version", "cron", "rewrite_rules", "WPLANG", "default_role", "users_can_register", "uninstall_plugins", "mailserver_url", "mailserver_login", "mailserver_pass", "mailserver_port"];
+export type OptionRefs = Record<string, string>;
 export type LocalOption = {
     autoload: string;
     name: string;
     readonly?: boolean;
+    refs?: OptionRefs;
     value: unknown;
 };
 export type RemoteOption = {

package/dist/utils/option-format.js

@@ -1,6 +1,8 @@
 export const OPTIONS_ENDPOINT = 'loopress/v1/options';
-export function optionEndpoint(name) {
-    return `${OPTIONS_ENDPOINT}/${encodeURIComponent(name)}`;
+// `refs` asks WordPress to return the declared post references as paths (see OptionRefs).
+export function optionEndpoint(name, refs) {
+    const endpoint = `${OPTIONS_ENDPOINT}/${encodeURIComponent(name)}`;
+    return refs && Object.keys(refs).length > 0 ? `${endpoint}?refs=${encodeURIComponent(JSON.stringify(refs))}` : endpoint;
 }
 // Mirrors OptionsService::RESERVED_NAMES on the WordPress side (the actual, unbypassable
 // enforcement lives there). Checked here too so `option add` fails fast with a clear pointer to
@@ -52,7 +54,7 @@ export function parseLocalOption(raw) {
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
         throw new Error('not a JSON object');
     }
-    const { autoload, name, value } = parsed;
+    const { autoload, name, refs, value } = parsed;
     if (typeof name !== 'string' || name === '') {
         throw new Error('missing a "name" string');
     }
@@ -65,5 +67,14 @@ export function parseLocalOption(raw) {
     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 !== ''));
+}

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

@@ -1,5 +1,9 @@
 export declare const PAGES_ENDPOINT = "loopress/v1/pages";
 export declare const PAGE_SLUG_PATTERN: RegExp;
+export type SlugRule = {
+    message: string;
+    pattern: RegExp;
+};
 export declare const PAGE_STATUSES: readonly ["draft", "publish"];
 export type PageStatus = (typeof PAGE_STATUSES)[number];
 export type Page = {
@@ -32,7 +36,7 @@ export declare function readLocalPages(dir: string): Promise<{
     pages: Page[];
     problems: PageProblem[];
 }>;
-export declare function readLocalHtmlFiles<T>(dir: string, parse: (slug: string, raw: string) => T): Promise<{
+export declare function readLocalHtmlFiles<T>(dir: string, parse: (slug: string, raw: string) => T, slugRule?: SlugRule): Promise<{
     files: T[];
     problems: PageProblem[];
 }>;

package/dist/utils/page-format.js

@@ -4,6 +4,10 @@ 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.
 export const PAGE_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PAGE_SLUG_RULE = {
+    message: 'the file name must be lowercase letters and digits separated by single hyphens (e.g. "legal-notice.html")',
+    pattern: PAGE_SLUG_PATTERN,
+};
 export const PAGE_STATUSES = ['draft', 'publish'];
 const HEADER_KEYS = ['title', 'status', 'full-width', 'hide-title', 'template'];
 function parseBoolean(key, value) {
@@ -82,7 +86,7 @@ export async function readLocalPages(dir) {
     return { pages: files, problems };
 }
 // The directory rules of readLocalPages(), for any flat folder of `<slug>.html` files.
-export async function readLocalHtmlFiles(dir, parse) {
+export async function readLocalHtmlFiles(dir, parse, slugRule = PAGE_SLUG_RULE) {
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
@@ -108,8 +112,8 @@ export async function readLocalHtmlFiles(dir, parse) {
             continue;
         }
         const slug = basename(entry.name, '.html');
-        if (!PAGE_SLUG_PATTERN.test(slug)) {
-            problems.push({ file: filePath, message: 'the file name must be lowercase letters and digits separated by single hyphens (e.g. "legal-notice.html")' });
+        if (!slugRule.pattern.test(slug)) {
+            problems.push({ file: filePath, message: slugRule.message });
             continue;
         }
         try {

package/dist/utils/plugin-sync.js

@@ -1,5 +1,5 @@
 // Shared helpers for driving the server-side `loopress/v1/composer/sync` endpoint, used by
-// `lps plugin push`, `lps theme push` and `lps composer push`. The endpoint runs Composer +
+// `lps plugin push`, `lps theme version push` and `lps composer push`. The endpoint runs Composer +
 // WPackagist inside WordPress; the CLI only ever sends intent (which slugs at which versions),
 // never a composer.json, so the plugin stays the single authority on that file's shape.
 import { compareVersions } from './version.js';

package/dist/utils/resource-dirs.d.ts

@@ -3,15 +3,21 @@ export declare const RESOURCE_DIR_DEFAULTS: {
     readonly acf: "acf";
     readonly api: "api";
     readonly apps: "apps";
+    readonly blockCss: "theme/blocks";
+    readonly cpt: "cpt";
+    readonly css: "theme/css";
     readonly form: "forms";
     readonly hooks: "hooks";
     readonly menu: "menus";
+    readonly meta: "meta";
     readonly options: "options";
     readonly page: "pages";
-    readonly part: "parts";
-    readonly seo: "seo";
+    readonly part: "theme/parts";
+    readonly pattern: "patterns";
+    readonly role: "roles";
     readonly snippets: "snippets";
-    readonly template: "templates";
+    readonly taxonomy: "taxonomies";
+    readonly template: "theme/templates";
     readonly themeStyles: "theme";
 };
 export type ResourceDirKind = keyof typeof RESOURCE_DIR_DEFAULTS;