@loopress/cli 0.27.0 → 0.29.0

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/types/plugin.d.ts

@@ -12,4 +12,11 @@ export type WpNativePlugin = {
     status: 'active' | 'inactive' | 'network-active';
     version: string;
 };
-export type PluginManifest = Record<string, string>;
+export type PluginPin = string | {
+    active?: boolean;
+    version: string;
+};
+export type PluginManifest = Record<string, PluginPin>;
+export declare const pinVersion: (pin: PluginPin) => string;
+export declare const pinActive: (pin: PluginPin) => boolean;
+export declare const pinVersions: (manifest: PluginManifest) => Record<string, string>;

package/dist/types/plugin.js

@@ -1 +1,4 @@
-export {};
+export const pinVersion = (pin) => (typeof pin === 'string' ? pin : pin.version);
+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

@@ -39,6 +39,14 @@ export interface LoopressProjectConfiguration {
      * Directory where static HTML pages (one <slug>.html per WordPress page, managed by Loopress) are read from, relative to rootDir.
      */
     pageDir?: string;
+    /**
+     * Directory where block templates (one <slug>.html per template, written to the Loopress child theme of the active block theme) are read from, relative to rootDir. A static page uses one with its `template` header.
+     */
+    templateDir?: string;
+    /**
+     * 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 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.
      */
@@ -56,10 +64,19 @@ export interface LoopressProjectConfiguration {
      */
     projectId?: string;
     /**
-     * WordPress.org plugins managed by Loopress, installed via Composer + WPackagist on the site. Keys are plugin slugs. A value is either an exact version to pin (e.g. "9.4.2") or "latest" to track the newest release on every push. Removing an entry uninstalls the plugin on the next push. Ignored when a composer.json exists in rootDir (that file becomes authoritative).
+     * WordPress.org plugins managed by Loopress, installed via Composer + WPackagist on the site. Keys are plugin slugs. A value is either an exact version to pin (e.g. "9.4.2") or "latest" to track the newest release on every push, and the plugin is kept active. An object with "active": false keeps the plugin installed but inactive. Removing an entry uninstalls the plugin on the next push. Ignored when a composer.json exists in rootDir (that file becomes authoritative).
      */
     plugins?: {
-        [k: string]: string;
+        [k: string]: string | {
+            /**
+             * Exact version to pin, or "latest".
+             */
+            version: string;
+            /**
+             * false keeps the plugin installed but inactive. Defaults to true.
+             */
+            active?: 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. Ignored when a composer.json exists in rootDir.

package/dist/utils/composer.d.ts

@@ -1,3 +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>;
@@ -16,3 +19,16 @@ export type ComposerJson = {
 export declare function readComposerJson(): Promise<ComposerJson | null>;
 export declare function readComposerLock(): Promise<null | string>;
 export declare function getComposerManagedSlugs(composerJson: ComposerJson): string[];
+export type ComposerPullResult = MergeResult<string> & {
+    skipped: Array<{
+        reason: string;
+        slug: string;
+    }>;
+};
+export declare function pullIntoComposerJson(path: string, kind: 'plugin' | 'theme', incoming: Record<string, string>, { dryRun, log }: {
+    dryRun: boolean;
+    log: (message: string) => void;
+}): Promise<ComposerPullResult>;
+export declare function toIntent(require: Record<string, string>): SyncIntent;
+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

@@ -1,6 +1,10 @@
 import { existsSync } from 'node:fs';
 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))
@@ -31,3 +35,143 @@ export function getComposerManagedSlugs(composerJson) {
         .filter((pkg) => pkg.startsWith('wpackagist-plugin/'))
         .map((pkg) => pkg.slice('wpackagist-plugin/'.length));
 }
+// A slug WPackagist can't serve makes `composer update` fail for the whole file, libraries
+// included. WPackagist mirrors WordPress.org, whose API answers a clean 404 for premium and
+// custom plugins/themes. Any other failure throws before composer.json is written.
+async function isOnWordPressOrg(kind, slug) {
+    const url = `https://api.wordpress.org/${kind}s/info/1.2/?action=${kind}_information&slug=${encodeURIComponent(slug)}`;
+    const fail = (why) => new Error(`Could not check whether the ${kind} "${slug}" is on WordPress.org (${why}), so composer.json was not modified. ` +
+        'Loopress only adds packages WPackagist can serve. Retry once api.wordpress.org is reachable.');
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (error) {
+        throw fail(`network error: ${error.message}`);
+    }
+    if (response.status === 404)
+        return false;
+    if (!response.ok)
+        throw fail(`HTTP ${response.status}`);
+    return true;
+}
+// Rewrites a JSON file the way it was indented (Composer itself writes 4 spaces), so a pull only
+// shows the entries it changed in the git diff. A file with no indentation to copy gets 4 spaces.
+function stringifyLike(original, value) {
+    const indent = /^([ \t]+)"/m.exec(original)?.[1] ?? ' '.repeat(4);
+    return JSON.stringify(value, null, indent) + (original.endsWith('\n') ? '\n' : '');
+}
+// A package already declared in composer.json: `pin` means the pull may move it (an exact pin,
+// or already live), `skip` gives the reason it must stay as is.
+function classifyDeclared(declared, live, inRequire) {
+    if (!inRequire)
+        return { skip: 'declared in require-dev' };
+    if (declared === live || isExactVersion(declared))
+        return { pin: declared };
+    return { skip: `keeps constraint ${declared}, live ${live}` };
+}
+// Sorts every installed package into the result, and returns the undeclared slugs that still
+// need a WordPress.org lookup before they can be added.
+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('/'))
+        .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));
+            if ('skip' in outcome) {
+                result.skipped.push({ reason: outcome.skip, slug });
+                continue;
+            }
+            result.merged[slug] = version;
+            if (outcome.pin !== version)
+                result.updated.push({ from: outcome.pin, slug, to: version });
+        }
+        else if (provider) {
+            result.skipped.push({ reason: `provided by ${provider}`, slug });
+        }
+        else {
+            candidates.push(slug);
+        }
+    }
+    return { candidates, result };
+}
+// `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
+//   exact pin moves to the live version.
+// - Slugs already declared in require-dev stay there instead of being duplicated into require.
+// - 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 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]) {
+            result.added.push(slug);
+            result.merged[slug] = incoming[slug];
+        }
+        else {
+            result.skipped.push({ reason: NOT_ON_WORDPRESS_ORG, slug });
+        }
+    }
+    if (!dryRun) {
+        const require = { ...composerJson.require };
+        for (const [slug, version] of Object.entries(result.merged))
+            require[prefix + slug] = version;
+        // Atomic: an interrupted write must never leave the user's committed composer.json truncated.
+        await writeFileAtomic(path, stringifyLike(raw, { ...composerJson, require }), 'utf8');
+    }
+    log(`${dryRun ? '[dry-run] Would pin' : 'Pinned'} ${Object.keys(result.merged).length} ${kind}s in composer.json`);
+    if (result.added.length > 0)
+        log(`  + Added: ${result.added.join(', ')}`);
+    for (const u of result.updated)
+        log(`  ~ Updated: ${u.slug} ${u.from} → ${u.to}`);
+    for (const s of result.skipped)
+        log(`  - Skipped: ${s.slug} (${s.reason})`);
+    if (!dryRun && (result.added.length > 0 || result.updated.length > 0))
+        log('Run `lps composer push` to apply.');
+    return result;
+}
+// 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: {} };
+    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;
+        }
+        else if (name.startsWith('wpackagist-theme/')) {
+            intent.themes[name.slice('wpackagist-theme/'.length)] = constraint;
+        }
+        else {
+            intent.libraries[name] = constraint;
+        }
+    }
+    return intent;
+}
+// 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(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 = {
@@ -24,8 +28,16 @@ export type PageProblem = {
 export declare function formatPageProblems(problems: PageProblem[]): string;
 export declare function titleFromSlug(slug: string): string;
 export declare function parsePageFile(slug: string, raw: string): Page;
+export declare function parseHtmlHeader(raw: string, keys: readonly string[]): {
+    body: string;
+    meta: Record<string, string>;
+};
 export declare function readLocalPages(dir: string): Promise<{
     pages: Page[];
     problems: PageProblem[];
 }>;
+export declare function readLocalHtmlFiles<T>(dir: string, parse: (slug: string, raw: string) => T, slugRule?: SlugRule): Promise<{
+    files: T[];
+    problems: PageProblem[];
+}>;
 export declare function frontPageNote(page: PushedPage): string;

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) {
@@ -35,27 +39,11 @@ export function titleFromSlug(slug) {
 //
 // A comment rather than YAML front matter so the file stays valid HTML, previewable as is in a
 // browser. The header is stripped from what gets pushed. Throws on an unknown key or status so a
-// typo never silently falls back to a default. `template` is the active theme's own template
-// slug (a block theme's templates/<slug>.html, or a classic theme's page-<slug>.php); unlike
-// `status`, it's never validated here, an unknown slug just makes WordPress fall back to the
-// default template, the same silent no-op as `full-width`/`hide-title` on a theme that doesn't
-// support them.
+// typo never silently falls back to a default. `template` is a template slug the active theme
+// offers for pages (one it ships, or a custom one from templates/); it isn't validated here,
+// WordPress itself refuses an unknown one ("Invalid page template") and fails that page's push.
 export function parsePageFile(slug, raw) {
-    const header = /^\s*<!--([\s\S]*?)-->\r?\n?/.exec(raw);
-    const meta = {};
-    if (header) {
-        for (const line of header[1].split(/\r?\n/)) {
-            if (line.trim() === '')
-                continue;
-            const colon = line.indexOf(':');
-            if (colon === -1)
-                throw new Error(`header line "${line.trim()}" is not a "key: value" pair`);
-            const key = line.slice(0, colon).trim();
-            if (!HEADER_KEYS.includes(key))
-                throw new Error(`unknown header key "${key}" (allowed: ${HEADER_KEYS.join(', ')})`);
-            meta[key] = line.slice(colon + 1).trim();
-        }
-    }
+    const { body, meta } = parseHtmlHeader(raw, HEADER_KEYS);
     const status = meta.status ?? 'draft';
     if (!PAGE_STATUSES.includes(status)) {
         throw new Error(`status "${status}" is not one of ${PAGE_STATUSES.join(', ')}`);
@@ -63,28 +51,52 @@ export function parsePageFile(slug, raw) {
     return {
         fullWidth: parseBoolean('full-width', meta['full-width']),
         hideTitle: parseBoolean('hide-title', meta['hide-title']),
-        html: header ? raw.slice(header[0].length) : raw,
+        html: body,
         slug,
         status: status,
         template: meta.template ?? '',
         title: meta.title || titleFromSlug(slug),
     };
 }
+// Splits the optional `key: value` HTML comment header off `raw`. Shared with templates/.
+export function parseHtmlHeader(raw, keys) {
+    const header = /^\s*<!--([\s\S]*?)-->\r?\n?/.exec(raw);
+    const meta = {};
+    if (!header)
+        return { body: raw, meta };
+    for (const line of header[1].split(/\r?\n/)) {
+        if (line.trim() === '')
+            continue;
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            throw new Error(`header line "${line.trim()}" is not a "key: value" pair`);
+        const key = line.slice(0, colon).trim();
+        if (!keys.includes(key))
+            throw new Error(`unknown header key "${key}" (allowed: ${keys.join(', ')})`);
+        meta[key] = line.slice(colon + 1).trim();
+    }
+    return { body: raw.slice(header[0].length), meta };
+}
 // Reads every page of `dir` and reports every problem at once instead of skipping bad files
 // like the other resources do: a page push is declarative, so anything unexpected in the
 // directory (a `.php`, a subdirectory, a bad header) must stop it before any network call.
 // Dotfiles (.DS_Store, editor droppings) are ignored. A missing directory is "no pages".
 export async function readLocalPages(dir) {
+    const { files, problems } = await readLocalHtmlFiles(dir, parsePageFile);
+    return { pages: files, problems };
+}
+// The directory rules of readLocalPages(), for any flat folder of `<slug>.html` files.
+export async function readLocalHtmlFiles(dir, parse, slugRule = PAGE_SLUG_RULE) {
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
     }
     catch (error) {
         if (error.code === 'ENOENT')
-            return { pages: [], problems: [] };
+            return { files: [], problems: [] };
         throw error;
     }
-    const pages = [];
+    const files = [];
     const problems = [];
     entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
@@ -92,7 +104,7 @@ export async function readLocalPages(dir) {
             continue;
         const filePath = join(dir, entry.name);
         if (!entry.isFile()) {
-            problems.push({ file: filePath, message: `subdirectories are not supported, keep every page at the top of ${dir}` });
+            problems.push({ file: filePath, message: `subdirectories are not supported, keep every file at the top of ${dir}` });
             continue;
         }
         if (extname(entry.name) !== '.html') {
@@ -100,18 +112,18 @@ export async function readLocalPages(dir) {
             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 {
-            pages.push(parsePageFile(slug, await readFile(filePath, 'utf8')));
+            files.push(parse(slug, await readFile(filePath, 'utf8')));
         }
         catch (error) {
             problems.push({ file: filePath, message: error.message });
         }
     }
-    return { pages, problems };
+    return { files, problems };
 }
 export function frontPageNote(page) {
     return page.frontPage === undefined ? '' : ` (${FRONT_PAGE_NOTES[page.frontPage]})`;

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

@@ -1,4 +1,4 @@
-import { type InstalledPlugin, type PluginManifest, type WpNativePlugin } from '../types/plugin.js';
+import { type InstalledPlugin, type PluginManifest, type PluginPin, type WpNativePlugin } from '../types/plugin.js';
 export type PluginDiff = {
     collisions: Array<{
         installedVersion: string;
@@ -9,6 +9,10 @@ export type PluginDiff = {
         file: string;
         slug: string;
     }>;
+    toDeactivate: Array<{
+        file: string;
+        slug: string;
+    }>;
     toInstall: Array<{
         slug: string;
         version: string;
@@ -21,16 +25,17 @@ export type PluginDiff = {
     toRemove: string[];
     untrackedActive: string[];
 };
-export type MergeResult = {
+export type MergeResult<P extends PluginPin = PluginPin> = {
     added: string[];
-    merged: PluginManifest;
+    merged: Record<string, P>;
     updated: Array<{
         from: string;
         slug: string;
         to: string;
     }>;
 };
-export declare function mergePluginManifest(existing: PluginManifest, incoming: PluginManifest): MergeResult;
+export declare function describePin(pin: PluginPin): string;
+export declare function mergePluginManifest<P extends PluginPin>(existing: Record<string, P>, incoming: Record<string, P>): MergeResult<P>;
 export declare function parseInstalledPlugins(raw: WpNativePlugin[]): InstalledPlugin[];
 export declare function diffPlugins(manifest: PluginManifest, installed: InstalledPlugin[], managedSlugs?: Set<string>): PluginDiff;
 export declare function lockedWpackagistSlugs(composerLock: null | string, kind: 'plugin' | 'theme'): Set<string>;

package/dist/utils/plugins.js

@@ -1,3 +1,9 @@
+import { pinActive, pinVersion, } from '../types/plugin.js';
+import { isExactVersion } from './version.js';
+// "1.7.2", or "1.7.2 (inactive)" for a pin that keeps the plugin inactive.
+export function describePin(pin) {
+    return pinActive(pin) ? pinVersion(pin) : `${pinVersion(pin)} (inactive)`;
+}
 // Loopress must never manage itself: pulling it into loopress.json would make a later
 // `plugin push` try to reinstall it from WordPress.org, where it doesn't exist, potentially
 // clobbering the plugin's own directory in the process. Checked against every slug this
@@ -8,8 +14,8 @@ export function mergePluginManifest(existing, incoming) {
     const merged = { ...existing, ...incoming };
     const added = Object.keys(incoming).filter((s) => !Object.hasOwn(existing, s));
     const updated = Object.keys(incoming)
-        .filter((s) => Object.hasOwn(existing, s) && existing[s] !== incoming[s])
-        .map((s) => ({ from: existing[s], slug: s, to: incoming[s] }));
+        .filter((s) => Object.hasOwn(existing, s) && describePin(existing[s]) !== describePin(incoming[s]))
+        .map((s) => ({ from: describePin(existing[s]), slug: s, to: describePin(incoming[s]) }));
     return { added, merged, updated };
 }
 // WordPress core identifies each plugin by a `<folder>/<file>` id (or a bare `<file>` for a
@@ -47,9 +53,11 @@ managedSlugs = new Set()) {
     const toInstall = [];
     const toPin = [];
     const toActivate = [];
+    const toDeactivate = [];
     const collisions = [];
     const inSync = [];
-    for (const [slug, wanted] of Object.entries(manifest)) {
+    for (const [slug, pin] of Object.entries(manifest)) {
+        const wanted = pinVersion(pin);
         const live = installedMap.get(slug);
         if (!live) {
             toInstall.push({ slug, version: wanted });
@@ -61,12 +69,13 @@ managedSlugs = new Set()) {
             collisions.push({ installedVersion: live.version, slug });
             continue;
         }
-        if (wanted !== 'latest' && live.version !== wanted) {
+        if (isExactVersion(wanted) && live.version !== wanted) {
             toPin.push({ from: live.version, slug, to: wanted });
             continue;
         }
-        if (!live.active) {
-            toActivate.push({ file: live.file, slug });
+        if (live.active !== pinActive(pin)) {
+            ;
+            (live.active ? toDeactivate : toActivate).push({ file: live.file, slug });
             continue;
         }
         inSync.push(slug);
@@ -75,7 +84,7 @@ managedSlugs = new Set()) {
     const untrackedActive = installed
         .filter((p) => p.active && !Object.hasOwn(manifest, p.slug) && !managedSlugs.has(p.slug))
         .map((p) => p.slug);
-    return { collisions, inSync, toActivate, toInstall, toPin, toRemove, untrackedActive };
+    return { collisions, inSync, toActivate, toDeactivate, toInstall, toPin, toRemove, untrackedActive };
 }
 // wpackagist-plugin/<slug> or wpackagist-theme/<slug> entries from a composer.lock string.
 export function lockedWpackagistSlugs(composerLock, kind) {

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

@@ -8,8 +8,10 @@ export declare const RESOURCE_DIR_DEFAULTS: {
     readonly menu: "menus";
     readonly options: "options";
     readonly page: "pages";
+    readonly part: "parts";
     readonly seo: "seo";
     readonly snippets: "snippets";
+    readonly template: "templates";
     readonly themeStyles: "theme";
 };
 export type ResourceDirKind = keyof typeof RESOURCE_DIR_DEFAULTS;

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',
@@ -10,8 +10,10 @@ export const RESOURCE_DIR_DEFAULTS = {
     menu: 'menus',
     options: 'options',
     page: 'pages',
+    part: 'parts',
     seo: 'seo',
     snippets: 'snippets',
+    template: 'templates',
     themeStyles: 'theme',
 };
 const CONFIG_KEY = {
@@ -23,8 +25,10 @@ const CONFIG_KEY = {
     menu: 'menuDir',
     options: 'optionsDir',
     page: 'pageDir',
+    part: 'partDir',
     seo: 'seoDir',
     snippets: 'snippetsDir',
+    template: 'templateDir',
     themeStyles: 'themeStylesDir',
 };
 // Resolves where a resource's files live: an explicit override wins, otherwise the