@loopress/cli 0.24.1 → 0.26.0

package/dist/lib/rollback-command.js

@@ -0,0 +1,180 @@
+import { confirm } from '@inquirer/prompts';
+import { Args, Flags, ux } from '@oclif/core';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pluralize } from '../utils/pluralize.js';
+import { resolveResourceDir } from '../utils/resource-dirs.js';
+import { LoopressCommand } from './base.js';
+import { compareStates, isEmptyDiff } from './diff-state.js';
+import { guardProductionPush } from './guard-production-push.js';
+import { isInteractive } from './interactive.js';
+import { getResourceStateProvider } from './resource-state.js';
+import { materializeSnapshot } from './rollback-materialize.js';
+import { listSnapshots, readSnapshot, recordToState } from './snapshot-store.js';
+const c = ux.colorize;
+function summarize(diff) {
+    return { added: diff.added, changed: diff.changed.map((change) => change.id), removed: diff.removed };
+}
+function indentPatch(patch) {
+    return patch
+        .split('\n')
+        .map((line) => (line === '' ? line : `    ${line}`))
+        .join('\n')
+        .trimEnd();
+}
+// Builds the `lps <resource> rollback` command for one resource-state-backed resource (the 9
+// listed in resource-state.ts's RESOURCE_STATE_PROVIDERS). `lps <resource> push` writes a
+// snapshot of the environment's state right before every real push (see snapshot-store.ts);
+// this command restores one: by default the most recent, or `--to <id>` for an older one.
+//
+// A rollback is only safe when nothing else touched the environment between the original push
+// and now, otherwise it silently overwrites a legitimate later change. So before restoring
+// anything, this runs the equivalent of `lps <resource> diff` between the environment's current
+// state and the state the original push expected to leave behind, and requires explicit
+// confirmation (the same interactive/`--yes` shape as guardProductionPush) when they differ.
+export function resourceRollbackCommand(resource, options) {
+    class ResourceRollback extends LoopressCommand {
+        static args = {
+            path: Args.string({ description: `Path to ${options.pathNoun} (overrides project config)` }),
+        };
+        static description = options.description;
+        static enableJsonFlag = true;
+        static examples = [
+            `$ lps ${resource} rollback`,
+            `$ lps ${resource} rollback --list`,
+            `$ lps ${resource} rollback --to 1732000000000`,
+            `$ lps ${resource} rollback --dry-run`,
+        ];
+        static flags = {
+            ...LoopressCommand.dryRunFlag,
+            ...LoopressCommand.yesFlag,
+            list: Flags.boolean({ description: 'List available snapshots instead of rolling back' }),
+            to: Flags.string({ description: 'Roll back to this snapshot id instead of the most recent one' }),
+        };
+        async run() {
+            const { args, flags } = await this.parse(ResourceRollback);
+            const provider = getResourceStateProvider(resource);
+            const rootDir = resolve(process.cwd(), this.rootDir);
+            if (flags.list) {
+                const snapshots = await listSnapshots(rootDir, resource, this.siteConfig.name);
+                this.renderList(snapshots);
+                return { snapshots, status: 'listed' };
+            }
+            const dir = resolveResourceDir(provider.dirKind, this.localConfig, args.path);
+            let snapshot;
+            try {
+                snapshot = await readSnapshot(rootDir, resource, this.siteConfig.name, flags.to);
+            }
+            catch (error) {
+                this.error(error.message);
+            }
+            await guardProductionPush({
+                dryRun: this.dryRun,
+                error: (message) => this.error(message),
+                siteConfig: this.siteConfig,
+                yes: this.yes,
+            });
+            this.log(`Rolling back ${provider.title} on ${this.siteConfig.url} to the snapshot from ${snapshot.createdAt} (${snapshot.id})`);
+            const warn = (message) => {
+                this.warn(message);
+            };
+            const currentState = await provider.remote(this.wp, warn, dir);
+            // Has anything else changed the environment since the original push? Compare its current
+            // state against what that push expected to leave behind (`afterState`), not against the
+            // snapshot we're about to restore (`beforeState`), those are expected to differ, that's
+            // the whole point of rolling back.
+            const drift = compareStates(recordToState(snapshot.afterState), currentState, {
+                left: `expected (right after the ${snapshot.createdAt} push)`,
+                right: 'current',
+            });
+            const driftSummary = isEmptyDiff(drift) ? undefined : summarize(drift);
+            if (driftSummary) {
+                this.renderDiff(`${provider.title} has changed on ${this.siteConfig.url} since that push:`, drift);
+                await this.confirmDespiteDrift();
+            }
+            const restoreState = recordToState(snapshot.beforeState);
+            const restoreDiff = compareStates(currentState, restoreState, { left: 'current', right: `snapshot ${snapshot.id}` });
+            if (isEmptyDiff(restoreDiff)) {
+                this.log('Nothing to restore, the environment already matches this snapshot.');
+                return { drift: driftSummary, id: snapshot.id, restored: summarize(restoreDiff), status: 'no-op' };
+            }
+            this.renderDiff(`This would restore ${provider.title} to:`, restoreDiff);
+            // `<resource> push` only creates and updates, it never deletes (see each resource's own
+            // push command, e.g. option push's "upsert only, never deletes an untracked option"):
+            // an item present now but absent from the snapshot stays present after "restoring" it.
+            if (restoreDiff.removed.length > 0) {
+                this.warn(`${pluralize(restoreDiff.removed.length, 'item')} present now but not in this snapshot will NOT be removed ` +
+                    `(${restoreDiff.removed.join(', ')}): restoring only creates and updates, the same as \`lps ${resource} push\`. Remove ${restoreDiff.removed.length === 1 ? 'it' : 'them'} by hand if that's part of undoing the original push.`);
+            }
+            if (this.dryRun) {
+                return { drift: driftSummary, id: snapshot.id, restored: summarize(restoreDiff), status: 'dry-run' };
+            }
+            // Only the items that actually need restoring, not the whole snapshot: an item already
+            // matching `beforeState` needs no push, and re-pushing it anyway would put every other
+            // item this resource ever had at push time (however unrelated to what actually drifted)
+            // through the delegated push's own validation, where a single unrelated failure would
+            // fail the whole rollback.
+            const idsToRestore = new Set([...restoreDiff.added, ...restoreDiff.changed.map((change) => change.id)]);
+            const stateToRestore = Object.fromEntries(Object.entries(snapshot.beforeState).filter(([id]) => idsToRestore.has(id)));
+            const tmpDir = await mkdtemp(join(tmpdir(), `loopress-rollback-${resource}-`));
+            try {
+                await materializeSnapshot(resource, stateToRestore, tmpDir);
+                // tmpDir is positional (the same [PATH] arg every resource push command takes, see e.g.
+                // commands/snippet/push.ts's `static args`), not a --path flag. --env/--yes: the
+                // production guard and the drift confirmation above already covered what the delegated
+                // push's own guard would ask again, same reasoning as the top-level `lps push`
+                // delegating to each resource's push command in commands/push.ts.
+                await this.config.runCommand(`${resource}:push`, [tmpDir, '--env', this.siteConfig.name, '--yes']);
+            }
+            finally {
+                // A cleanup failure here must never hide a real error from the push above: warn about
+                // it and let the original error (if any) keep propagating instead of being replaced.
+                await rm(tmpDir, { force: true, recursive: true }).catch((error) => {
+                    this.warn(`Could not remove the temporary directory "${tmpDir}": ${error.message}`);
+                });
+            }
+            this.log(`Rolled back ${provider.title} to the snapshot from ${snapshot.createdAt}.`);
+            return { drift: driftSummary, id: snapshot.id, restored: summarize(restoreDiff), status: 'success' };
+        }
+        async confirmDespiteDrift() {
+            if (this.dryRun || this.yes)
+                return;
+            if (!isInteractive()) {
+                this.error('The environment has changed since this snapshot was taken. Re-run with --yes to roll back anyway (overwriting those later changes).');
+            }
+            const proceed = await confirm({
+                default: false,
+                message: 'The environment has changed since this snapshot was taken. Roll back anyway, overwriting those later changes?',
+            });
+            if (!proceed)
+                this.error('Aborted.');
+        }
+        renderDiff(heading, diff) {
+            if (this.jsonEnabled())
+                return;
+            this.log(c('bold', heading));
+            for (const id of diff.added)
+                this.log(c('green', `  + ${id}`));
+            for (const id of diff.removed)
+                this.log(c('red', `  - ${id}`));
+            for (const change of diff.changed) {
+                this.log(c('yellow', `  ~ ${change.id}`));
+                this.log(indentPatch(change.patch));
+            }
+        }
+        renderList(snapshots) {
+            if (this.jsonEnabled())
+                return;
+            if (snapshots.length === 0) {
+                this.log(`No snapshots found for "${resource}" on "${this.siteConfig.name}". A snapshot is written automatically by \`lps ${resource} push\`.`);
+                return;
+            }
+            this.log(`Snapshots for "${resource}" on "${this.siteConfig.name}" (most recent first):`);
+            for (const snapshot of snapshots) {
+                this.log(`  ${snapshot.id}  ${snapshot.createdAt}`);
+            }
+        }
+    }
+    return ResourceRollback;
+}

package/dist/lib/rollback-materialize.d.ts

@@ -0,0 +1 @@
+export declare function materializeSnapshot(resource: string, state: Record<string, unknown>, dir: string): Promise<void>;

package/dist/lib/rollback-materialize.js

@@ -0,0 +1,121 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getAcfKey } from '../utils/acf-format.js';
+import { getFormId, getFormTitle } from '../utils/form-format.js';
+import { getMenuSlug } from '../utils/menu-format.js';
+import { defaultReadonlyFor, optionFileName } from '../utils/option-format.js';
+import { redirectFileBase } from '../utils/seo-format.js';
+import { buildMetaFile, buildSnippetFile } from '../utils/snippet-format.js';
+import { themeStylesFileName } from '../utils/theme-styles-format.js';
+import { toSlug } from '../utils/to-slug.js';
+const SNIPPET_EXTENSIONS = { css: 'css', html: 'html', js: 'js', php: 'php', text: 'txt' };
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(value, null, 2) + '\n');
+}
+// id: the snapshot's map key, a numeric WordPress id (snapshots only ever come from
+// `provider.remote()`, which never produces the "local:<file>" placeholder ids a not-yet-pushed
+// local file gets, see resource-state.ts). value: the canonical snippet fields resource-state.ts
+// compares (no `id`, no `description`, `code` with its `<?php` tag already stripped), exactly
+// what `normalizeSnippet` + `stripPhpOpeningTag` produce, so it plugs straight into the same
+// `buildSnippetFile`/`buildMetaFile` pair `snippet pull` uses to write files.
+async function snippet(id, value, dir) {
+    const fields = value;
+    const normalized = { ...fields, description: '', id: Number(id) };
+    const ext = SNIPPET_EXTENSIONS[normalized.type];
+    const base = `${normalized.id}-${toSlug(normalized.name)}`;
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, `${base}.${ext}`), buildSnippetFile(normalized));
+    await writeFile(join(dir, `${base}.json`), buildMetaFile(normalized));
+}
+// value is the whole form JSON (minus `modified`/`modified_gmt`), the same shape `form pull`
+// writes verbatim; `form push` re-sends it as-is.
+async function form(id, value, dir) {
+    const data = value;
+    const formId = getFormId(data) ?? Number(id);
+    const slug = toSlug(getFormTitle(data), 'untitled');
+    await writeJson(join(dir, `${formId}-${slug}.json`), data);
+}
+// id is `<type>/<key>` (see resource-state.ts's acfProvider); value is the whole ACF export
+// object (minus `modified`), already carrying its own `key`.
+async function acf(id, value, dir) {
+    const separator = id.indexOf('/');
+    const type = id.slice(0, separator);
+    const data = value;
+    const key = getAcfKey(data) ?? id.slice(separator + 1);
+    await writeJson(join(dir, type, `${key}.json`), data);
+}
+// api/hook: id is the filename (possibly nested, `/`-joined); value is the raw PHP file text.
+async function phpFile(id, value, dir) {
+    const filePath = join(dir, `${id}.php`);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, String(value));
+}
+// ids are 'settings', `post-meta/<postType>/<slug>`, or `redirects/<id>` (see resource-state.ts's
+// seoProvider). Each value round-trips to the exact file `seo pull` would have written.
+async function seo(id, value, dir) {
+    if (id === 'settings') {
+        await writeJson(join(dir, 'settings.json'), value);
+        return;
+    }
+    if (id.startsWith('post-meta/')) {
+        const rest = id.slice('post-meta/'.length);
+        const separator = rest.indexOf('/');
+        const postType = rest.slice(0, separator);
+        const slug = rest.slice(separator + 1);
+        await writeJson(join(dir, 'post-meta', postType, `${slug}.json`), value);
+        return;
+    }
+    if (id.startsWith('redirects/')) {
+        const redirect = value;
+        await writeJson(join(dir, 'redirects', `${redirectFileBase(redirect)}.json`), redirect);
+        return;
+    }
+    throw new Error(`Unrecognized SEO snapshot id "${id}"`);
+}
+// ids are 'menu-locations' or `menu/<slug>` (see resource-state.ts's menuProvider).
+async function menu(id, value, dir) {
+    if (id === 'menu-locations') {
+        await writeJson(join(dir, 'menu-locations.json'), value);
+        return;
+    }
+    const data = value;
+    const slug = getMenuSlug(data) ?? id.slice('menu/'.length);
+    await writeJson(join(dir, `${slug}.json`), data);
+}
+// `value` is `{autoload, value}` (resource-state.ts's optionsProvider deliberately drops
+// `readonly`: it's a local policy flag with no WordPress counterpart). Restoring it as writable
+// by default would silently lift that protection for a rollback that happens to include a
+// dangerous option (siteurl, home, ...); defaulting to the same policy `option add` itself uses
+// keeps a rolled-back option exactly as protected as a freshly tracked one, never less.
+async function option(id, value, dir) {
+    const { autoload, value: optionValue } = value;
+    const local = { autoload, name: id, readonly: defaultReadonlyFor(id), value: optionValue };
+    await writeJson(join(dir, optionFileName(id)), local);
+}
+// id is the stylesheet slug; value is `{settings, styles}` (canonicalGlobalStyles' shape).
+async function themeStyles(id, value, dir) {
+    await writeJson(join(dir, themeStylesFileName(id)), value);
+}
+const MATERIALIZERS = {
+    acf,
+    api: phpFile,
+    form,
+    hook: phpFile,
+    menu,
+    option,
+    seo,
+    snippet,
+    'theme-styles': themeStyles,
+};
+// Writes a snapshot's state back to `dir` in the exact on-disk layout `<resource> pull` would
+// have produced, so the existing `<resource> push` command can push it unmodified: a rollback
+// is push() applied to an archived state instead of the current local files.
+export async function materializeSnapshot(resource, state, dir) {
+    const materialize = MATERIALIZERS[resource];
+    if (!materialize)
+        throw new Error(`Rollback is not supported for "${resource}".`);
+    await mkdir(dir, { recursive: true });
+    for (const [id, value] of Object.entries(state))
+        await materialize(id, value, dir);
+}

package/dist/lib/snapshot-store.d.ts

@@ -0,0 +1,30 @@
+import { type ResourceState } from './diff-state.js';
+export declare const SNAPSHOT_RETENTION = 10;
+export type Snapshot = {
+    afterState: Record<string, unknown>;
+    beforeState: Record<string, unknown>;
+    createdAt: string;
+    environment: string;
+    resource: string;
+};
+export type SnapshotSummary = {
+    createdAt: string;
+    environment: string;
+    id: string;
+    resource: string;
+};
+export declare function stateToRecord(state: ResourceState): Record<string, unknown>;
+export declare function recordToState(record: Record<string, unknown>): ResourceState;
+export declare function writeSnapshot(options: {
+    afterState: ResourceState;
+    beforeState: ResourceState;
+    environment: string;
+    resource: string;
+    retain?: number;
+    rootDir: string;
+}): Promise<string>;
+export declare function listSnapshots(rootDir: string, resource: string, environment: string): Promise<SnapshotSummary[]>;
+export declare function readSnapshot(rootDir: string, resource: string, environment: string, id?: string): Promise<Snapshot & {
+    id: string;
+}>;
+export declare function pruneSnapshots(rootDir: string, resource: string, environment: string, retain: number): Promise<void>;

package/dist/lib/snapshot-store.js

@@ -0,0 +1,133 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// How many snapshots `writeSnapshot` keeps per resource before pruning the oldest, so the
+// cache directory doesn't grow without bound across a project's lifetime.
+export const SNAPSHOT_RETENTION = 10;
+// `ResourceState` (a Map, for O(1) lookups during comparison) has no direct JSON
+// 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)));
+}
+export function recordToState(record) {
+    return new Map(Object.entries(record));
+}
+// Environment names are free text (whatever `lps project config` was given), not guaranteed to
+// be filesystem-safe path segments; anything outside a conservative safe set becomes '-'.
+function sanitizeForPath(name) {
+    return name.replaceAll(/[^\w-]/g, '-');
+}
+// Scoped by environment, not just resource: a project with multiple environments (staging,
+// production, ...) sharing one rootDir must never let a staging push's snapshot answer a
+// production rollback, or a staging push's retention prune a production restore point.
+function snapshotsDir(rootDir, resource, environment) {
+    return join(rootDir, '.loopress', 'snapshots', resource, sanitizeForPath(environment));
+}
+function snapshotPath(rootDir, resource, environment, id) {
+    return join(snapshotsDir(rootDir, resource, environment), `${id}.json`);
+}
+function isEnoent(error) {
+    return error.code === 'ENOENT';
+}
+function isEexist(error) {
+    return error.code === 'EEXIST';
+}
+// Snapshot ids are the millisecond timestamp they were written at: sortable, unique enough for
+// a single-machine CLI run, and directly usable as `--to <id>`.
+function isSnapshotFilename(name) {
+    return /^\d+\.json$/.test(name);
+}
+// Writes a snapshot for `resource`/`environment`, then prunes down to `retain` (oldest first),
+// so a project that pushes often never accumulates an unbounded `.loopress/snapshots/`
+// directory. Returns the new snapshot's id.
+//
+// Ids are millisecond timestamps; two pushes of the same resource/environment landing in the
+// same millisecond (only realistic from concurrent processes, never a single sequential CLI
+// run) would otherwise silently overwrite one restore point with another. `wx` (exclusive
+// create) turns that into a detected collision instead, retried against the next millisecond.
+export async function writeSnapshot(options) {
+    const { afterState, beforeState, environment, resource, retain = SNAPSHOT_RETENTION, rootDir } = options;
+    const dir = snapshotsDir(rootDir, resource, environment);
+    await mkdir(dir, { recursive: true });
+    const snapshot = {
+        afterState: stateToRecord(afterState),
+        beforeState: stateToRecord(beforeState),
+        createdAt: new Date().toISOString(),
+        environment,
+        resource,
+    };
+    const content = JSON.stringify(snapshot, null, 2) + '\n';
+    let id = Date.now();
+    for (;;) {
+        try {
+            await writeFile(join(dir, `${id}.json`), content, { flag: 'wx' });
+            break;
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+            id += 1;
+        }
+    }
+    await pruneSnapshots(rootDir, resource, environment, retain);
+    return String(id);
+}
+// Newest first. A missing snapshots directory (never pushed, or pruned to nothing) reads as
+// "no snapshots", not an error, the same ENOENT tolerance every resource-state provider gives
+// a never-pulled local directory.
+export async function listSnapshots(rootDir, resource, environment) {
+    const dir = snapshotsDir(rootDir, resource, environment);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+    const summaries = [];
+    const snapshotFiles = entries.filter((entry) => isSnapshotFilename(entry));
+    for (const entry of snapshotFiles) {
+        const id = entry.slice(0, -'.json'.length);
+        try {
+            const parsed = JSON.parse(await readFile(join(dir, entry), 'utf8'));
+            summaries.push({ createdAt: parsed.createdAt, environment: parsed.environment, id, resource });
+        }
+        catch {
+            // A corrupted or partially-written snapshot file (e.g. an interrupted write) is skipped
+            // 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));
+}
+// `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
+// snapshots at all for this environment, or that specific id missing (renamed, deleted, or
+// written under a different resource/environment).
+export async function readSnapshot(rootDir, resource, environment, id) {
+    let targetId = id;
+    if (targetId === undefined) {
+        const [latest] = await listSnapshots(rootDir, resource, environment);
+        if (!latest) {
+            throw new Error(`No snapshots found for "${resource}" on "${environment}". A snapshot is written automatically by \`lps ${resource} push\`.`);
+        }
+        targetId = latest.id;
+    }
+    let raw;
+    try {
+        raw = await readFile(snapshotPath(rootDir, resource, environment, targetId), 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            throw new Error(`Snapshot "${targetId}" not found for "${resource}" on "${environment}". Run \`lps ${resource} rollback --list\` to see what's available.`, { cause: error });
+        }
+        throw error;
+    }
+    return { ...JSON.parse(raw), id: targetId };
+}
+export async function pruneSnapshots(rootDir, resource, environment, retain) {
+    const summaries = await listSnapshots(rootDir, resource, environment);
+    const stale = summaries.slice(retain);
+    await Promise.all(stale.map(async (summary) => rm(snapshotPath(rootDir, resource, environment, summary.id), { force: true })));
+}

package/dist/lib/validate-local.js

@@ -1,17 +1,20 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { configManager } from '../config/project-config.manager.js';
+import { readLocalPages } from '../utils/page-format.js';
 import { parseType } from '../utils/snippet-format.js';
 import { loadSnippets } from './load-snippets.js';
 import { readdirTolerant } from './readdir-tolerant.js';
 // Directories holding one JSON document per resource. Snippets (code file plus JSON sidecar)
 // and api routes (`.php`, not JSON) are checked separately.
-const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir'];
+const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir', 'menuDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
     formDir: 'forms',
     hooksDir: 'hooks',
+    menuDir: 'menus',
+    pageDir: 'pages',
     seoDir: 'seo',
     snippetsDir: 'snippets',
 };
@@ -37,6 +40,9 @@ export async function validateLocal(cwd) {
     checked += await checkSnippets(resolve('snippetsDir'), problems);
     checked += await checkPhpDir(resolve('apiDir'), problems, 'API route file is empty');
     checked += await checkPhpDir(resolve('hooksDir'), problems, 'Hook file is empty');
+    const pages = await readLocalPages(resolve('pageDir'));
+    checked += pages.pages.length + pages.problems.length;
+    problems.push(...pages.problems);
     return { checked, problems, valid: problems.length === 0 };
 }
 // Recursive: both api/ and hooks/ files can live in a nested path-segment directory

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

@@ -35,10 +35,22 @@ export interface LoopressProjectConfiguration {
      * Directory where single-page app bundles are read from and written to, relative to rootDir. Each subdirectory is one app: a loopress.app.json plus a built dist/ folder.
      */
     appsDir?: string;
+    /**
+     * Directory where static HTML pages (one <slug>.html per WordPress page, managed by Loopress) are read from, relative to rootDir.
+     */
+    pageDir?: 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 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.
+     */
+    menuDir?: string;
+    /**
+     * Directory where the active block theme's Global Styles customizations (Site Editor > Styles: colors, typography, spacing) are read from and written to, relative to rootDir. Classic (non-block) themes are not supported.
+     */
+    themeStylesDir?: string;
     /**
      * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
      */

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

@@ -1,4 +1,5 @@
 export declare const ACF_OBJECT_TYPES: readonly ["field-groups", "post-types", "taxonomies", "options-pages"];
 export type AcfObjectType = (typeof ACF_OBJECT_TYPES)[number];
 export declare function acfEndpoint(type: AcfObjectType): string;
+export declare function acfObjectEndpoint(type: AcfObjectType, key: string): string;
 export declare function getAcfKey(data: Record<string, unknown>): null | string;

package/dist/utils/acf-format.js

@@ -2,6 +2,12 @@ export const ACF_OBJECT_TYPES = ['field-groups', 'post-types', 'taxonomies', 'op
 export function acfEndpoint(type) {
     return `loopress/v1/acf/${type}`;
 }
+// GET/DELETE route for a single object by key, used by `acf push` to read the object's current
+// revision right before writing it (see acf/push.ts, #234). Create/update both go through
+// acfEndpoint() (a POST), the controller resolves create-vs-update server-side via `key`.
+export function acfObjectEndpoint(type, key) {
+    return `${acfEndpoint(type)}/${key}`;
+}
 // Deliberately loose: ACF's own export JSON is large, deeply nested, and versioned by ACF
 // itself (new settings appear across ACF releases). We only need `key` for filenames/identity;
 // everything else round-trips through pull/push untouched, so there's no generated type for it

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

@@ -1,3 +1,7 @@
 export declare const FORM_ENDPOINT = "loopress/v1/forms";
+export declare function formEndpoint(id: number): string;
+export type RemoteForm = Record<string, unknown> & {
+    revision: string;
+};
 export declare function getFormId(data: Record<string, unknown>): null | number;
 export declare function getFormTitle(data: Record<string, unknown>): string;

package/dist/utils/form-format.js

@@ -1,11 +1,7 @@
 export const FORM_ENDPOINT = 'loopress/v1/forms';
-// Deliberately loose, same reasoning as getAcfKey in acf-format.ts: a form plugin's own data
-// format (WPForms today: fields, settings, notifications, confirmations, providers, meta; other
-// WordPress form plugins may be supported later, same shape as snippet-format.ts's Code
-// Snippets/WPCode split) is large, deeply nested, and versioned by whichever plugin release
-// wrote it. We only need `id` for filenames/identity and `settings.form_title` for display
-// (the field WPForms itself uses; a future provider may differ), everything else round-trips
-// through pull/push untouched.
+export function formEndpoint(id) {
+    return `${FORM_ENDPOINT}/${id}`;
+}
 export function getFormId(data) {
     const id = Number(data.id);
     return Number.isSafeInteger(id) && id > 0 ? id : null;

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

@@ -0,0 +1,24 @@
+export declare const MENU_ENDPOINT = "loopress/v1/menus";
+export declare const MENU_LOCATIONS_ENDPOINT = "loopress/v1/menu-locations";
+export declare function menuEndpoint(slug: string): string;
+export type MenuItem = {
+    children: MenuItem[];
+    classes: string[];
+    description: string;
+    object: null | string;
+    objectSlug: null | string;
+    target: string;
+    title: string;
+    type: 'custom' | 'post_type' | 'taxonomy';
+    url: null | string;
+    xfn: string;
+};
+export type Menu = {
+    items: MenuItem[];
+    name: string;
+    revision: string;
+    slug: string;
+    warnings: string[];
+};
+export type MenuLocations = Record<string, null | string>;
+export declare function getMenuSlug(data: Record<string, unknown>): null | string;

package/dist/utils/menu-format.js

@@ -0,0 +1,8 @@
+export const MENU_ENDPOINT = 'loopress/v1/menus';
+export const MENU_LOCATIONS_ENDPOINT = 'loopress/v1/menu-locations';
+export function menuEndpoint(slug) {
+    return `${MENU_ENDPOINT}/${encodeURIComponent(slug)}`;
+}
+export function getMenuSlug(data) {
+    return typeof data.slug === 'string' && data.slug.trim() !== '' ? data.slug : null;
+}

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

@@ -11,6 +11,7 @@ export type LocalOption = {
 export type RemoteOption = {
     autoload: string;
     name: string;
+    revision: string;
     value: unknown;
 };
 export type ListedOption = {

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

@@ -0,0 +1,27 @@
+export declare const PAGES_ENDPOINT = "loopress/v1/pages";
+export declare const PAGE_SLUG_PATTERN: RegExp;
+export declare const PAGE_STATUSES: readonly ["draft", "publish"];
+export type PageStatus = (typeof PAGE_STATUSES)[number];
+export type Page = {
+    fullWidth: boolean;
+    hideTitle: boolean;
+    html: string;
+    slug: string;
+    status: PageStatus;
+    template: string;
+    title: string;
+};
+export type RemotePage = Page & {
+    link: string;
+};
+export type PageProblem = {
+    file: string;
+    message: string;
+};
+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 readLocalPages(dir: string): Promise<{
+    pages: Page[];
+    problems: PageProblem[];
+}>;