@loopress/cli 0.24.1 → 0.25.0

package/dist/lib/resource-state.js

@@ -2,9 +2,11 @@ import { readFile } from 'node:fs/promises';
 import { basename, join, relative, sep } from 'node:path';
 import { ACF_OBJECT_TYPES, acfEndpoint, getAcfKey } from '../utils/acf-format.js';
 import { FORM_ENDPOINT, getFormId } from '../utils/form-format.js';
+import { getMenuSlug, MENU_ENDPOINT, MENU_LOCATIONS_ENDPOINT } from '../utils/menu-format.js';
 import { optionEndpoint, parseLocalOption } from '../utils/option-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 { 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';
 import { isApplicative404, isNotFoundError } from './wp-client.js';
@@ -239,12 +241,16 @@ const seoProvider = {
     },
     async remote(wp, onWarn) {
         const state = new Map();
-        const settings = await wp.get(SEO_SETTINGS_ENDPOINT);
+        // `revision` (#234) is dropped from both, same as optionsProvider.remote() does for
+        // RemoteOption.revision below: it's bookkeeping for the conditional-write precondition, not
+        // configuration, and comparing it here would flag drift whenever the mere act of reading
+        // changed nothing meaningful.
+        const { settings } = await wp.get(SEO_SETTINGS_ENDPOINT);
         state.set('settings', settings);
         for (const postType of DEFAULT_POST_TYPES) {
             const posts = await wp.get(seoPostMetaEndpoint(postType));
-            for (const post of posts)
-                state.set(`post-meta/${postType}/${post.slug}`, post);
+            for (const { meta, slug, title } of posts)
+                state.set(`post-meta/${postType}/${slug}`, { meta, slug, title });
         }
         // Redirects are a RankMath-only feature; on Yoast the endpoint 404s, same graceful skip
         // as `seo pull`.
@@ -264,6 +270,55 @@ const seoProvider = {
     resource: 'seo',
     title: 'SEO',
 };
+// ---- Menus --------------------------------------------------------------------------------
+// Every item's post_type/taxonomy target is already resolved to `object`/`objectSlug` by the
+// REST layer (MenuService), never a raw `_menu_item_object_id`, so the exported tree is already
+// portable and compared as-is. `warnings` is diagnostic (a dangling item, an off-environment
+// custom URL, ...), not tracked configuration, so it's dropped before comparing, the same
+// "volatile key" treatment ACF/forms/redirects give their own server-computed fields. `revision`
+// (#234) is bookkeeping for menu push's conditional-write precondition, not tracked configuration
+// either: it's a pure hash of name + items, so it never disagrees when they don't, but a local
+// file pulled before this field existed simply wouldn't have it, which must never show up as
+// drift on its own.
+const MENU_VOLATILE_KEYS = ['revision', 'warnings'];
+// The reserved local filename for menu locations, see commands/menu/pull.ts.
+const MENU_LOCATIONS_FILE = 'menu-locations';
+function canonicalMenu(menu) {
+    return omit(menu, MENU_VOLATILE_KEYS);
+}
+const menuProvider = {
+    dirKind: 'menu',
+    async local(dir, onWarn) {
+        const state = new Map();
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: (raw, filePath) => ({ file: basename(filePath, '.json'), value: readJson(raw) }),
+        });
+        for (const { file, value } of entries) {
+            if (file === MENU_LOCATIONS_FILE) {
+                state.set(MENU_LOCATIONS_FILE, value);
+                continue;
+            }
+            const slug = getMenuSlug(value) ?? `local:${file}`;
+            state.set(`menu/${slug}`, canonicalMenu(value));
+        }
+        return state;
+    },
+    async remote(wp) {
+        const state = new Map();
+        const menus = await wp.get(MENU_ENDPOINT);
+        for (const menu of menus) {
+            const slug = getMenuSlug(menu);
+            if (slug !== null)
+                state.set(`menu/${slug}`, canonicalMenu(menu));
+        }
+        state.set(MENU_LOCATIONS_FILE, await wp.get(MENU_LOCATIONS_ENDPOINT));
+        return state;
+    },
+    resource: 'menu',
+    title: 'Menus',
+};
 // ---- Options ------------------------------------------------------------------------------
 // Unlike every provider above, remote() has no "everything" endpoint to read: GET /options only
 // lists names, never values (by design, see OptionsController), so both sides compare exactly
@@ -310,6 +365,38 @@ const optionsProvider = {
     resource: 'option',
     title: 'Options',
 };
+// ---- Theme styles (Global Styles) ----------------------------------------------------------
+// Local files are named `<stylesheet>-global-styles.json`, keyed by stylesheet so a directory
+// that has accumulated files from more than one previously-active theme still compares each one
+// individually rather than colliding on a single key.
+const themeStylesProvider = {
+    dirKind: 'themeStyles',
+    async local(dir, onWarn) {
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse(raw, filePath) {
+                const name = basename(filePath);
+                const stylesheet = name.endsWith(THEME_STYLES_FILE_SUFFIX) ? name.slice(0, -THEME_STYLES_FILE_SUFFIX.length) : basename(filePath, '.json');
+                return { stylesheet, value: readJson(raw) };
+            },
+        });
+        const state = new Map();
+        for (const { stylesheet, value } of entries)
+            state.set(stylesheet, canonicalGlobalStyles(value));
+        return state;
+    },
+    // Only the active theme's Global Styles are compared (see theme-styles-format.ts): a classic
+    // active theme has no Styles screen at all, surfaced here as a normal provider error, the same
+    // "inconclusive for this resource" treatment DiffCommand gives any other fetch failure.
+    async remote(wp) {
+        const { id, stylesheet } = await getActiveThemeGlobalStyles(wp);
+        const item = await wp.get(globalStylesEndpoint(id));
+        return new Map([[stylesheet, canonicalGlobalStyles(item)]]);
+    },
+    resource: 'theme-styles',
+    title: 'Theme styles',
+};
 export const RESOURCE_STATE_PROVIDERS = [
     snippetProvider,
     formProvider,
@@ -317,7 +404,9 @@ export const RESOURCE_STATE_PROVIDERS = [
     apiProvider,
     hookProvider,
     seoProvider,
+    menuProvider,
     optionsProvider,
+    themeStylesProvider,
 ];
 export function getResourceStateProvider(resource) {
     const provider = RESOURCE_STATE_PROVIDERS.find((candidate) => candidate.resource === resource);

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

@@ -0,0 +1,21 @@
+import { LoopressCommand } from './base.js';
+import { type SnapshotSummary } from './snapshot-store.js';
+export type RollbackResult = {
+    drift?: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+    };
+    id?: string;
+    restored?: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+    };
+    snapshots?: SnapshotSummary[];
+    status: 'dry-run' | 'listed' | 'no-op' | 'success';
+};
+export declare function resourceRollbackCommand(resource: string, options: {
+    description: string;
+    pathNoun: string;
+}): typeof LoopressCommand;

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

@@ -6,12 +6,13 @@ 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',
     seoDir: 'seo',
     snippetsDir: 'snippets',
 };

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

@@ -39,6 +39,14 @@ export interface LoopressProjectConfiguration {
      * 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.
      */