@loopress/cli 0.28.0 → 0.29.0

package/dist/lib/push-command.js

@@ -1,3 +1,4 @@
+import { Flags } from '@oclif/core';
 import got from 'got';
 import { Listr } from 'listr2';
 import { resolve } from 'node:path';
@@ -7,19 +8,28 @@ import { LoopressCommand } from './base.js';
 import { guardProductionPush } from './guard-production-push.js';
 import { writeSnapshot } from './snapshot-store.js';
 export class PushCommand extends LoopressCommand {
+    // Passed by an aggregate command (`lps theme push`) that already confirmed production once,
+    // so its steps skip that prompt while still asking their own confirmations (uninstalls).
+    static baseFlags = {
+        ...LoopressCommand.baseFlags,
+        'production-confirmed': Flags.boolean({ hidden: true }),
+    };
     failedCount = 0;
     // Refusals of the production guard never reach the site, so they must not pollute the
     // deployment history with failure records.
     refusedByGuard = false;
     // Reads `provider`'s remote state right before a real push, for `writeAfterPushSnapshot` to
-    // pair with the actual post-push remote state once the push completes. A dry run changes
-    // nothing, so there is nothing to snapshot. Best-effort: a read failure (the site briefly
-    // unreachable) must never block the push itself, the same "never interrupt the push flow"
-    // stance recordDeployment takes; `undefined` tells `writeAfterPushSnapshot` there is no
-    // restore point to complete.
+    // pair with the actual post-push remote state once the push completes. Best-effort: a read
+    // failure (the site briefly unreachable) must never block the push itself, the same "never
+    // interrupt the push flow" stance recordDeployment takes; `undefined` tells
+    // `writeAfterPushSnapshot` there is no restore point to complete.
+    //
+    // On a dry run, the same read is the preview's check against the site (see previewRemote).
     async captureBeforePushState(provider, dir) {
-        if (this.dryRun)
+        if (this.dryRun) {
+            await this.previewRemote(provider, dir);
             return undefined;
+        }
         try {
             return await provider.remote(this.wp, (message) => {
                 this.warn(message);
@@ -34,7 +44,7 @@ export class PushCommand extends LoopressCommand {
         if (!this.dryRun && !this.refusedByGuard && this.siteConfig) {
             await this.recordDeployment('failure');
         }
-        return super.catch(err);
+        await super.catch(err);
     }
     async guardProductionPush() {
         await guardProductionPush({
@@ -44,13 +54,25 @@ export class PushCommand extends LoopressCommand {
                 this.refusedByGuard = true;
             },
             siteConfig: this.siteConfig,
-            yes: this.yes,
+            yes: this.yes || this.productionConfirmed,
         });
     }
     async init() {
         await super.init();
         await this.guardProductionPush();
     }
+    // A dry run used to stay local, so it announced "pushed" for a resource the site would refuse
+    // (ACF or Rank Math missing: a 400 or 409 on the real push). It now reads the site the same way
+    // `lps diff` does and fails the same way, so the preview, and the MCP server's preview and
+    // pre-apply check built on it, see what the real push will hit.
+    async previewRemote(provider, dir) {
+        try {
+            await provider.remote(this.wp, () => { }, dir);
+        }
+        catch (error) {
+            this.error(`The site would refuse this push: ${error.message}`);
+        }
+    }
     async recordDeployment(status) {
         const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token ?? null;
         if (!token)

package/dist/lib/resource-state.js

@@ -7,7 +7,7 @@ import { optionEndpoint, parseLocalOption } from '../utils/option-format.js';
 import { formatPageProblems, PAGES_ENDPOINT, readLocalHtmlFiles, readLocalPages } from '../utils/page-format.js';
 import { DEFAULT_POST_TYPES, SEO_REDIRECTS_ENDPOINT, SEO_SETTINGS_ENDPOINT, seoPostMetaEndpoint, } from '../utils/seo-format.js';
 import { normalizeSnippet, SNIPPETS_ENDPOINT, stripPhpOpeningTag } from '../utils/snippet-format.js';
-import { CHILD_THEME_ENDPOINT, parsePartFile, parseTemplateFile } from '../utils/template-format.js';
+import { CHILD_THEME_ENDPOINT, parsePartFile, parseTemplateFile, TEMPLATE_SLUG_RULE } from '../utils/template-format.js';
 import { canonicalGlobalStyles, getActiveThemeGlobalStyles, globalStylesEndpoint, THEME_STYLES_FILE_SUFFIX, } from '../utils/theme-styles-format.js';
 import { loadFiles } from './load-files.js';
 import { loadSnippets } from './load-snippets.js';
@@ -236,7 +236,7 @@ async function childThemeState(wp, kind) {
 const templateProvider = {
     dirKind: 'template',
     async local(dir) {
-        const { files, problems } = await readLocalHtmlFiles(dir, parseTemplateFile);
+        const { files, problems } = await readLocalHtmlFiles(dir, parseTemplateFile, TEMPLATE_SLUG_RULE);
         if (problems.length > 0)
             throw new Error(formatPageProblems(problems));
         return new Map(files.map(({ slug, ...rest }) => [slug, rest]));
@@ -248,7 +248,7 @@ const templateProvider = {
 const partProvider = {
     dirKind: 'part',
     async local(dir) {
-        const { files, problems } = await readLocalHtmlFiles(dir, parsePartFile);
+        const { files, problems } = await readLocalHtmlFiles(dir, parsePartFile, TEMPLATE_SLUG_RULE);
         if (problems.length > 0)
             throw new Error(formatPageProblems(problems));
         return new Map(files.map(({ slug, ...rest }) => [slug, rest]));
@@ -408,12 +408,13 @@ const optionsProvider = {
         const tracked = await loadFiles(dir, {
             extension: '.json',
             onSkip: onWarn,
-            parse: (raw) => parseLocalOption(raw).name,
+            parse: parseLocalOption,
         });
         const state = new Map();
-        for (const name of tracked) {
+        for (const { name, refs } of tracked) {
             try {
-                const option = await wp.get(optionEndpoint(name));
+                // With the file's refs, so post references compare as paths on both sides.
+                const option = await wp.get(optionEndpoint(name, refs));
                 state.set(name, { autoload: option.autoload, value: option.value });
             }
             catch (error) {

package/dist/lib/snapshot-store.js

@@ -7,7 +7,7 @@ export const SNAPSHOT_RETENTION = 10;
 // representation; snapshots round-trip through a plain object instead. Keys are sorted so two
 // snapshots of the same state serialize identically (stable diffs, deterministic tests).
 export function stateToRecord(state) {
-    return Object.fromEntries([...state].sort(([a], [b]) => a.localeCompare(b)));
+    return Object.fromEntries([...state].toSorted(([a], [b]) => a.localeCompare(b)));
 }
 export function recordToState(record) {
     return new Map(Object.entries(record));
@@ -113,7 +113,7 @@ export async function listSnapshots(rootDir, resource, environment) {
             // rather than failing the whole listing; it stays on disk for a human to inspect.
         }
     }
-    return summaries.sort((a, b) => Number(b.id) - Number(a.id));
+    return summaries.toSorted((a, b) => Number(b.id) - Number(a.id));
 }
 // `id` undefined reads the most recent snapshot for this environment (the common
 // `lps <resource> rollback` case). Throws a message ready to show the user directly: no

package/dist/lib/wp-authorize-flow.d.ts

@@ -3,24 +3,17 @@ export type AuthorizeResult = {
     userLogin: string;
 };
 /**
- * Relays the authorization through the Loopress API so that WordPress's
- * `success_url` / `reject_url` can be valid HTTPS URLs.  The API receives the
- * redirect from WordPress and forwards the credentials back to a local callback
- * server via a form POST (keeping them out of the browser's address bar).
+ * Asks WordPress for an Application Password through its own authorize-application.php page,
+ * with the CLI's loopback server as `success_url` / `reject_url`:
  *
- * Flow:
- *   1. Start a local HTTP server on `127.0.0.1`.
- *   2. Open the browser to `https://api.loopress.dev/auth/wp-authorize` with the local
- *      callback URL and the target WordPress site as query params.
- *   3. That page redirects the user to WordPress's authorize-application.php,
- *      passing the API's callback endpoint as `success_url` (HTTPS).
- *   4. After the user approves, WordPress redirects to the API callback.
- *   5. The API callback returns an HTML page that POSTs a form with the
- *      Application Password to the local callback server.
- *   6. The local server extracts the credentials and resolves the promise.
+ *   1. Start a local HTTP server on 127.0.0.1.
+ *   2. Open the browser on `<site>/wp-admin/authorize-application.php`.
+ *   3. After the user approves, WordPress redirects to the loopback URL with `user_login` and
+ *      `password` appended to its query string (`state` is kept, WordPress only adds params).
  *
- * The `state` value is threaded through `callbackUrl` (the relay copies it verbatim into the
- * form's POST target), so it comes back as a query param on the credential POST and
- * `waitForLocalCallback` can match it before this handler runs.
+ * The callback host must be the literal `127.0.0.1`, not `localhost`: WordPress 7.0+ only exempts
+ * `127.0.0.1` and `[::1]` from its HTTPS requirement on these URLs. Older versions are screened
+ * out beforehand by `diagnoseWpSite`. The credentials land in the browser history as part of the
+ * callback URL, so the result page rewrites that history entry (see `renderResultPage`).
  */
 export declare function authorizeWithBrowser(siteUrl: string, log: (message: string) => void): Promise<AuthorizeResult>;

package/dist/lib/wp-authorize-flow.js

@@ -1,44 +1,40 @@
 import { renderResultPage, waitForLocalCallback } from './local-callback-server.js';
 /**
- * Relays the authorization through the Loopress API so that WordPress's
- * `success_url` / `reject_url` can be valid HTTPS URLs.  The API receives the
- * redirect from WordPress and forwards the credentials back to a local callback
- * server via a form POST (keeping them out of the browser's address bar).
+ * Asks WordPress for an Application Password through its own authorize-application.php page,
+ * with the CLI's loopback server as `success_url` / `reject_url`:
  *
- * Flow:
- *   1. Start a local HTTP server on `127.0.0.1`.
- *   2. Open the browser to `https://api.loopress.dev/auth/wp-authorize` with the local
- *      callback URL and the target WordPress site as query params.
- *   3. That page redirects the user to WordPress's authorize-application.php,
- *      passing the API's callback endpoint as `success_url` (HTTPS).
- *   4. After the user approves, WordPress redirects to the API callback.
- *   5. The API callback returns an HTML page that POSTs a form with the
- *      Application Password to the local callback server.
- *   6. The local server extracts the credentials and resolves the promise.
+ *   1. Start a local HTTP server on 127.0.0.1.
+ *   2. Open the browser on `<site>/wp-admin/authorize-application.php`.
+ *   3. After the user approves, WordPress redirects to the loopback URL with `user_login` and
+ *      `password` appended to its query string (`state` is kept, WordPress only adds params).
  *
- * The `state` value is threaded through `callbackUrl` (the relay copies it verbatim into the
- * form's POST target), so it comes back as a query param on the credential POST and
- * `waitForLocalCallback` can match it before this handler runs.
+ * The callback host must be the literal `127.0.0.1`, not `localhost`: WordPress 7.0+ only exempts
+ * `127.0.0.1` and `[::1]` from its HTTPS requirement on these URLs. Older versions are screened
+ * out beforehand by `diagnoseWpSite`. The credentials land in the browser history as part of the
+ * callback URL, so the result page rewrites that history entry (see `renderResultPage`).
  */
 export async function authorizeWithBrowser(siteUrl, log) {
     return waitForLocalCallback({
-        allowedOrigins: ['https://api.loopress.dev'],
+        // WordPress reaches the callback through a top-level GET redirect, which carries no Origin,
+        // so any request that does carry one isn't WordPress.
+        allowedOrigins: [],
         buildUrl(callbackBaseUrl, state) {
-            const relayUrl = 'https://api.loopress.dev/auth/wp-authorize';
+            const callbackUrl = `${callbackBaseUrl}/?state=${state}`;
             const params = new URLSearchParams({
-                callbackUrl: `${callbackBaseUrl}?state=${state}`,
-                wpUrl: siteUrl,
+                app_name: 'Loopress',
+                reject_url: `${callbackUrl}&cancelled=1`,
+                success_url: callbackUrl,
             });
-            return `${relayUrl}?${params}`;
+            return `${siteUrl}/wp-admin/authorize-application.php?${params}`;
         },
-        handleRequest(url, { resolveWithPage, rejectWithPage, respondBadRequest, body }) {
-            if (url.searchParams.has('cancelled') || body.cancelled) {
+        callbackHost: '127.0.0.1',
+        handleRequest(url, { resolveWithPage, rejectWithPage, respondBadRequest }) {
+            if (url.searchParams.has('cancelled')) {
                 rejectWithPage(REJECTED_PAGE, new Error('Authorization rejected in WordPress.'));
                 return;
             }
-            // Credentials come from the relay's form POST only. Reading them from the query string
-            // would let them land in shell history, proxy logs and the browser address bar (F24).
-            const { password, user_login: userLogin } = body;
+            const password = url.searchParams.get('password');
+            const userLogin = url.searchParams.get('user_login');
             if (!password || !userLogin) {
                 respondBadRequest('Missing password or user_login');
                 return;
@@ -46,7 +42,7 @@ export async function authorizeWithBrowser(siteUrl, log) {
             resolveWithPage(SUCCESS_PAGE, { password, userLogin });
         },
         log,
-        openingMessage: 'Opening WordPress in your browser to authorize Loopress...',
+        openingMessage: 'Opening WordPress in your browser to authorize Loopress...\nIf WordPress says the URL must be served over a secure connection (WordPress older than 7.0), press Ctrl-C and run `lps project config` again, choosing manual entry.',
         timeoutMessage: 'Authorization timed out after 5 minutes.',
     });
 }

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

@@ -1,5 +1,12 @@
 import got from 'got';
 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
@@ -29,8 +36,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 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/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

@@ -3,6 +3,8 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import writeFileAtomic from 'write-file-atomic';
 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))
@@ -100,7 +102,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 +121,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 +161,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/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.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
-// The default subdirectory for each file-backed resource, relative to rootDir. `lps init`
-// writes these same defaults into loopress.json, keep the two in sync.
+// The default subdirectory for each file-backed resource, relative to rootDir. Used whenever
+// loopress.json has no `<kind>Dir` key, which is the case for a fresh `lps init`.
 export const RESOURCE_DIR_DEFAULTS = {
     acf: 'acf',
     api: 'api',

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

@@ -1,5 +1,6 @@
-import { type PageProblem } from './page-format.js';
+import { type PageProblem, type SlugRule } from './page-format.js';
 export declare const CHILD_THEME_ENDPOINT = "loopress/v1/child-theme";
+export declare const TEMPLATE_SLUG_RULE: SlugRule;
 export type Template = {
     html: string;
     postTypes?: string[];

package/dist/utils/template-format.js

@@ -1,5 +1,12 @@
 import { parseHtmlHeader, readLocalHtmlFiles, titleFromSlug } from './page-format.js';
 export const CHILD_THEME_ENDPOINT = 'loopress/v1/child-theme';
+// Mirrored server-side in ChildThemeController. Looser than a page slug: the template hierarchy
+// embeds post type and taxonomy slugs as is (`taxonomy-download_tag`, `single-my_type`), and those
+// follow sanitize_key(), so lowercase letters, digits, `_` and `-`.
+export const TEMPLATE_SLUG_RULE = {
+    message: 'the file name must be lowercase letters, digits, "_" and "-" (e.g. "taxonomy-download_tag.html")',
+    pattern: /^[a-z0-9_-]+$/,
+};
 // A block delimiter as the first line (`<!-- wp:template-part ... /-->`, the usual one) is markup,
 // not a header.
 const BLOCK_START = /^\s*<!--\s*\/?wp:/;
@@ -28,9 +35,9 @@ export function parsePartFile(slug, raw) {
     const nameArea = /^(header|footer)(-|$)/.exec(slug)?.[1] ?? 'uncategorized';
     return { area: meta.area || nameArea, html: body, slug, title: meta.title || titleFromSlug(slug) };
 }
-// Same directory rules as pages/ (flat, `.html` only, strict slugs), every problem at once.
+// Same directory rules as pages/ (flat, `.html` only), with template slugs, every problem at once.
 export async function readLocalTemplates(templatesDir, partsDir) {
-    const templates = await readLocalHtmlFiles(templatesDir, parseTemplateFile);
-    const parts = await readLocalHtmlFiles(partsDir, parsePartFile);
+    const templates = await readLocalHtmlFiles(templatesDir, parseTemplateFile, TEMPLATE_SLUG_RULE);
+    const parts = await readLocalHtmlFiles(partsDir, parsePartFile, TEMPLATE_SLUG_RULE);
     return { parts: parts.files, problems: [...templates.problems, ...parts.problems], templates: templates.files };
 }