@loopress/cli 0.24.1 → 0.25.0

package/dist/commands/acf/push.d.ts

@@ -11,6 +11,7 @@ export default class Push extends PushCommand {
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    private currentRevision;
     private loadObjects;
     private pushObject;
     private pushType;

package/dist/commands/acf/push.js

@@ -2,7 +2,9 @@ import { Args, Flags } from '@oclif/core';
 import { join } from 'node:path';
 import { loadFiles } from '../../lib/load-files.js';
 import { PushCommand } from '../../lib/push-command.js';
-import { ACF_OBJECT_TYPES, acfEndpoint, getAcfKey } from '../../utils/acf-format.js';
+import { getResourceStateProvider } from '../../lib/resource-state.js';
+import { isNotFoundError } from '../../lib/wp-client.js';
+import { ACF_OBJECT_TYPES, acfEndpoint, acfObjectEndpoint, getAcfKey } from '../../utils/acf-format.js';
 import { pluralize } from '../../utils/pluralize.js';
 export default class Push extends PushCommand {
     static args = {
@@ -22,9 +24,12 @@ export default class Push extends PushCommand {
         const types = (flags.type && flags.type.length > 0 ? flags.type : ACF_OBJECT_TYPES);
         this.log(`Pushing ACF configuration to ${url}`);
         this.log(`ACF path: ${path}`);
+        const provider = getResourceStateProvider('acf');
+        const beforeState = await this.captureBeforePushState(provider, path);
         for (const type of types) {
             await this.pushType(type, path);
         }
+        await this.writeAfterPushSnapshot(provider, path, beforeState);
         if (this.failedCount > 0) {
             this.error(`${pluralize(this.failedCount, 'ACF object')} failed to push.`);
         }
@@ -33,6 +38,17 @@ export default class Push extends PushCommand {
         await this.recordSuccess();
         this.log('All ACF objects pushed.');
     }
+    async currentRevision(type, key) {
+        try {
+            const current = await this.wp.get(acfObjectEndpoint(type, key));
+            return current.revision;
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return undefined;
+            throw error;
+        }
+    }
     async loadObjects(dir) {
         return loadFiles(dir, {
             extension: '.json',
@@ -57,7 +73,14 @@ export default class Push extends PushCommand {
             return;
         }
         try {
-            await this.wp.post(acfEndpoint(type), object);
+            // Read the object's current revision right before writing it, and send it back as
+            // `expectedRevision`: WordPress refuses the write (412) if something else changed the
+            // object in between, instead of this push silently overwriting it (#234). No revision to
+            // condition on for an object that doesn't exist remotely yet (a first push, an upsert
+            // create): falls back to today's unconditional write, same as before this existed.
+            const expectedRevision = await this.currentRevision(type, key);
+            const body = expectedRevision === undefined ? object : { ...object, expectedRevision };
+            await this.wp.post(acfEndpoint(type), body);
             if (task)
                 task.output = `Pushed: ${key}`;
         }

package/dist/commands/acf/rollback.d.ts

@@ -0,0 +1,2 @@
+declare const _default: typeof import("../../lib/base.js").LoopressCommand;
+export default _default;

package/dist/commands/acf/rollback.js

@@ -0,0 +1,5 @@
+import { resourceRollbackCommand } from '../../lib/rollback-command.js';
+export default resourceRollbackCommand('acf', {
+    description: 'Restore ACF field groups, post types, taxonomies, and options pages to a snapshot taken automatically before an earlier `lps acf push`',
+    pathNoun: 'ACF directory',
+});

package/dist/commands/api/rollback.d.ts

@@ -0,0 +1,2 @@
+declare const _default: typeof import("../../lib/base.js").LoopressCommand;
+export default _default;

package/dist/commands/api/rollback.js

@@ -0,0 +1,5 @@
+import { resourceRollbackCommand } from '../../lib/rollback-command.js';
+export default resourceRollbackCommand('api', {
+    description: 'Restore API route files to a snapshot taken automatically before an earlier `lps api push`',
+    pathNoun: 'api directory',
+});

package/dist/commands/diff.js

@@ -7,7 +7,7 @@ const RESOURCES = [...RESOURCE_STATE_PROVIDERS.map((provider) => provider.resour
 export default class Diff extends DiffCommand {
     static description = [
         'Show what differs between your local tracked files and a WordPress environment, or between two environments.',
-        'Covers snippets, forms, ACF, API routes, Hooks, SEO, and Composer. Plugins and themes have their own `lps plugin status` / `lps theme status`.',
+        'Covers snippets, forms, ACF, API routes, Hooks, SEO, Options, Menus, Theme styles, and Composer. Plugins and themes have their own `lps plugin status` / `lps theme status`.',
         'Exit code: 0 in sync, 1 on drift, 2 when a resource could not be compared, so it doubles as a CI drift gate.',
     ].join(' ');
     static enableJsonFlag = true;

package/dist/commands/doctor.d.ts

@@ -1,8 +1,24 @@
 import { LoopressCommand } from '../lib/base.js';
+export type DoctorCheck = {
+    message?: string;
+    ok: boolean;
+    title: string;
+};
+export type DoctorResult = {
+    checks: DoctorCheck[];
+    environment: string;
+    ok: boolean;
+    pluginVersion?: string;
+    project: string;
+    url: string;
+};
 export default class Doctor extends LoopressCommand {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
-    run(): Promise<void>;
+    private readonly checks;
+    run(): Promise<DoctorResult>;
     private check;
+    private out;
     private reportPluginVersion;
 }

package/dist/commands/doctor.js

@@ -5,76 +5,93 @@ import { diagnoseWpSite } from '../lib/wp-site-diagnostic.js';
 import { pluralize } from '../utils/pluralize.js';
 export default class Doctor extends LoopressCommand {
     static description = 'Diagnose connectivity, plugin and credential problems for the targeted environment';
+    static enableJsonFlag = true;
     static examples = ['$ lps doctor', '$ lps doctor --env production'];
+    checks = [];
     async run() {
         const { name, token, url } = this.siteConfig;
         const project = this.localConfig.projectId
             ? configManager.getProject(this.localConfig.projectId)
             : configManager.getCurrentProject();
-        this.log(`Project:      ${project?.name ?? '(unknown)'}`);
-        this.log(`Environment:  ${name}`);
-        this.log(`URL:          ${url}`);
-        this.log('');
-        let failed = 0;
+        const projectName = project?.name ?? '(unknown)';
+        this.out(`Project:      ${projectName}`);
+        this.out(`Environment:  ${name}`);
+        this.out(`URL:          ${url}`);
+        this.out('');
+        let pluginVersion;
         const isReachable = await this.check('WordPress REST API reachable', async () => {
             const diagnostic = await diagnoseWpSite(url);
             if (!diagnostic.ok)
                 throw new Error(diagnostic.reason);
         });
-        if (!isReachable) {
-            failed++;
-            this.log('- Remaining checks skipped while the site is unreachable.');
-            this.error('1 check failed.', { exit: 1 });
-        }
-        if (!token) {
-            this.log('✗ Credentials configured');
-            this.log(`  No credentials stored for ${url}. Run \`lps project config\` to add them.`);
-            this.log('- Remaining checks skipped without credentials.');
-            this.error('1 check failed.', { exit: 1 });
-        }
-        // The namespace index answers regardless of which Loopress features are active, so a 404
-        // here can only mean the plugin itself is missing or outdated (WpClient's 404 message
-        // already says exactly that).
-        if (!(await this.check('Loopress plugin installed (loopress/v1 endpoints)', async () => this.wp.get('loopress/v1')))) {
-            failed++;
-        }
-        // wp/v2/users/me is WordPress core and requires authentication, so it validates the
-        // application password without depending on any Loopress feature.
-        if (!(await this.check('Credentials accepted (authenticated request)', async () => this.wp.get('wp/v2/users/me')))) {
-            failed++;
+        if (isReachable) {
+            if (token) {
+                // The namespace index answers regardless of which Loopress features are active, so a
+                // 404 here can only mean the plugin itself is missing or outdated (WpClient's 404
+                // message already says exactly that).
+                await this.check('Loopress plugin installed (loopress/v1 endpoints)', async () => this.wp.get('loopress/v1'));
+                // wp/v2/users/me is WordPress core and requires authentication, so it validates the
+                // application password without depending on any Loopress feature.
+                await this.check('Credentials accepted (authenticated request)', async () => this.wp.get('wp/v2/users/me'));
+                pluginVersion = await this.reportPluginVersion();
+            }
+            else {
+                this.checks.push({
+                    message: `No credentials stored for ${url}. Run \`lps project config\` to add them.`,
+                    ok: false,
+                    title: 'Credentials configured',
+                });
+                this.out('✗ Credentials configured');
+                this.out(`  No credentials stored for ${url}. Run \`lps project config\` to add them.`);
+                this.out('- Remaining checks skipped without credentials.');
+            }
         }
-        await this.reportPluginVersion();
-        this.log('');
-        if (failed > 0) {
-            this.error(`${pluralize(failed, 'check')} failed.`, { exit: 1 });
+        else {
+            this.out('- Remaining checks skipped while the site is unreachable.');
         }
-        this.log('All checks passed.');
+        const failed = this.checks.filter((check) => !check.ok).length;
+        const ok = failed === 0;
+        this.out('');
+        this.out(ok ? 'All checks passed.' : `${pluralize(failed, 'check')} failed.`);
+        if (!ok)
+            process.exitCode = 1;
+        return { checks: this.checks, environment: name, ok, pluginVersion, project: projectName, url };
     }
     async check(title, run) {
         try {
             await run();
-            this.log(`✓ ${title}`);
+            this.checks.push({ ok: true, title });
+            this.out(`✓ ${title}`);
             return true;
         }
         catch (error) {
-            this.log(`✗ ${title}`);
-            this.log(`  ${error.message}`);
+            const { message } = error;
+            this.checks.push({ message, ok: false, title });
+            this.out(`✗ ${title}`);
+            this.out(`  ${message}`);
             return false;
         }
     }
+    out(message) {
+        if (!this.jsonEnabled())
+            this.log(message);
+    }
     // Informational only: Loopress Light does not expose loopress/v1/update, and an old plugin
     // predates it, neither should flip the doctor to a failure when everything else works.
     async reportPluginVersion() {
         try {
             const status = await this.wp.get('loopress/v1/update');
-            this.log(`✓ Plugin version: ${status.current_version ?? '(unknown)'}`);
+            const version = status.current_version ?? '(unknown)';
+            this.out(`✓ Plugin version: ${version}`);
+            return version;
         }
         catch (error) {
             if (isNotFoundError(error)) {
-                this.log('- Plugin version: not exposed by this plugin edition.');
-                return;
+                this.out('- Plugin version: not exposed by this plugin edition.');
+                return undefined;
             }
-            this.log(`- Plugin version: could not be read. ${error.message}`);
+            this.out(`- Plugin version: could not be read. ${error.message}`);
+            return undefined;
         }
     }
 }

package/dist/commands/form/pull.js

@@ -39,7 +39,10 @@ export default class Pull extends LoopressCommand {
             async write(form, writeDir) {
                 const id = getFormId(form);
                 const title = getFormTitle(form);
-                await writeFile(join(writeDir, `${id}-${toSlug(title, 'untitled')}.json`), JSON.stringify(form, null, 2) + '\n');
+                // `revision` is server bookkeeping (see RemoteForm in form-format.ts), never part of
+                // the tracked configuration: never persisted locally.
+                const local = Object.fromEntries(Object.entries(form).filter(([key]) => key !== 'revision'));
+                await writeFile(join(writeDir, `${id}-${toSlug(title, 'untitled')}.json`), JSON.stringify(local, null, 2) + '\n');
             },
         });
         if (this.dryRun)

package/dist/commands/form/push.d.ts

@@ -12,6 +12,7 @@ export default class Push extends PushCommand {
     };
     private allowNotifications;
     run(): Promise<void>;
+    private currentRevision;
     private ensureCanonicalFilename;
     private loadFiles;
     private pushForm;

package/dist/commands/form/push.js

@@ -4,7 +4,9 @@ import { dirname, extname, join } from 'node:path';
 import { PushCommand } from '../../lib/push-command.js';
 import { putOrCreate } from '../../lib/put-or-create.js';
 import { readdirTolerant } from '../../lib/readdir-tolerant.js';
-import { FORM_ENDPOINT, getFormId, getFormTitle } from '../../utils/form-format.js';
+import { getResourceStateProvider } from '../../lib/resource-state.js';
+import { isNotFoundError } from '../../lib/wp-client.js';
+import { FORM_ENDPOINT, formEndpoint, getFormId, getFormTitle } from '../../utils/form-format.js';
 import { pluralize } from '../../utils/pluralize.js';
 import { toSlug } from '../../utils/to-slug.js';
 export default class Push extends PushCommand {
@@ -29,9 +31,12 @@ export default class Push extends PushCommand {
         this.allowNotifications = flags['allow-notifications'];
         this.log(`Pushing forms to ${url}`);
         this.log(`Forms path: ${path}`);
+        const provider = getResourceStateProvider('form');
+        const beforeState = await this.captureBeforePushState(provider, path);
         const files = await this.loadFiles(path);
         this.log(`Found ${pluralize(files.length, 'form')} to push`);
         await this.runPushTasks(files, ({ data }) => getFormTitle(data), async ({ data, filePath }, task) => this.pushForm(filePath, data, task));
+        await this.writeAfterPushSnapshot(provider, path, beforeState);
         if (this.failedCount > 0) {
             this.error(`${pluralize(this.failedCount, 'form')} failed to push.`);
         }
@@ -40,6 +45,17 @@ export default class Push extends PushCommand {
         await this.recordSuccess();
         this.log('All forms pushed.');
     }
+    async currentRevision(id) {
+        try {
+            const current = await this.wp.get(formEndpoint(id));
+            return current.revision;
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return undefined;
+            throw error;
+        }
+    }
     // Renames the local file to the `<id>-<slug>.json` convention used by `form pull`
     // whenever it doesn't already match (a hand-created file with no id, or a stale slug after
     // a title change in the WordPress admin), same principle as ensureCanonicalFilename in
@@ -85,11 +101,21 @@ export default class Push extends PushCommand {
         try {
             const id = getFormId(data);
             const payload = this.allowNotifications ? { ...data, allowNotifications: true } : data;
+            // Read the form's current revision right before writing it, and send it back as
+            // `expectedRevision`: WordPress refuses the write (412) if something else changed the
+            // form in between, instead of this push silently overwriting it (#234). No revision to
+            // condition on for a form that doesn't exist remotely yet (a first push, or one whose id
+            // 404s below and falls back to create): that PUT attempt just 404s too, same as before
+            // this existed. Kept out of the POST fallback body (`postPayload`): it is a precondition
+            // on an existing resource, meaningless (and never persisted) on a freshly created one.
+            const expectedRevision = id === null ? undefined : await this.currentRevision(id);
+            const putPayload = expectedRevision === undefined ? payload : { ...payload, expectedRevision };
             const { body, created } = await putOrCreate(this.wp, {
                 id,
-                payload,
+                payload: putPayload,
                 postEndpoint: FORM_ENDPOINT,
-                putEndpoint: (formId) => `${FORM_ENDPOINT}/${formId}`,
+                postPayload: payload,
+                putEndpoint: formEndpoint,
             });
             const canonicalId = created ? getFormId(body) : id;
             if (canonicalId !== null)

package/dist/commands/form/rollback.d.ts

@@ -0,0 +1,2 @@
+declare const _default: typeof import("../../lib/base.js").LoopressCommand;
+export default _default;

package/dist/commands/form/rollback.js

@@ -0,0 +1,5 @@
+import { resourceRollbackCommand } from '../../lib/rollback-command.js';
+export default resourceRollbackCommand('form', {
+    description: 'Restore forms to a snapshot taken automatically before an earlier `lps form push`',
+    pathNoun: 'forms directory',
+});

package/dist/commands/hook/rollback.d.ts

@@ -0,0 +1,2 @@
+declare const _default: typeof import("../../lib/base.js").LoopressCommand;
+export default _default;

package/dist/commands/hook/rollback.js

@@ -0,0 +1,5 @@
+import { resourceRollbackCommand } from '../../lib/rollback-command.js';
+export default resourceRollbackCommand('hook', {
+    description: 'Restore hook files to a snapshot taken automatically before an earlier `lps hook push`',
+    pathNoun: 'hooks directory',
+});

package/dist/commands/init.js

@@ -15,6 +15,7 @@ const SNIPPET_PROVIDERS = [
 const FEATURES = [
     { dir: 'acf', key: 'acfDir', label: 'ACF' },
     { dir: 'seo', key: 'seoDir', label: 'SEO' },
+    { dir: 'menus', key: 'menuDir', label: 'Menus' },
     { dir: 'forms', key: 'formDir', label: 'Forms' },
     { dir: 'api', key: 'apiDir', label: 'Custom API routes' },
     { dir: 'hooks', key: 'hooksDir', label: 'Hooks (actions, filters, cron)' },

package/dist/commands/menu/diff.d.ts

@@ -0,0 +1,2 @@
+declare const _default: typeof import("../../lib/diff-command.js").DiffCommand;
+export default _default;

package/dist/commands/menu/diff.js

@@ -0,0 +1,5 @@
+import { resourceDiffCommand } from '../../lib/diff-command.js';
+export default resourceDiffCommand('menu', {
+    description: 'Show what differs in nav menus and the active theme menu locations between your local files and a WordPress environment, or between two environments',
+    pathNoun: 'menus directory',
+});

package/dist/commands/menu/list.d.ts

@@ -0,0 +1,13 @@
+import { LoopressCommand } from '../../lib/base.js';
+import { type Menu, type MenuLocations } from '../../utils/menu-format.js';
+type ListResult = {
+    locations: MenuLocations;
+    menus: Menu[];
+};
+export default class List extends LoopressCommand {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    run(): Promise<ListResult>;
+}
+export {};

package/dist/commands/menu/list.js

@@ -0,0 +1,32 @@
+import { LoopressCommand } from '../../lib/base.js';
+import { MENU_ENDPOINT, MENU_LOCATIONS_ENDPOINT } from '../../utils/menu-format.js';
+function countItems(items) {
+    return items.reduce((total, item) => total + 1 + countItems(item.children), 0);
+}
+export default class List extends LoopressCommand {
+    static description = 'List nav menus and the active theme menu locations on WordPress';
+    static enableJsonFlag = true;
+    static examples = ['$ lps menu list'];
+    async run() {
+        const menus = await this.wp.get(MENU_ENDPOINT);
+        const locations = await this.wp.get(MENU_LOCATIONS_ENDPOINT);
+        if (menus.length === 0) {
+            this.log('(no menus)');
+        }
+        for (const menu of menus) {
+            this.log(`${menu.slug} (${menu.name}): ${countItems(menu.items)} item(s)`);
+            for (const warning of menu.warnings)
+                this.warn(`${menu.slug}: ${warning}`);
+        }
+        this.log('');
+        this.log('locations:');
+        const entries = Object.entries(locations);
+        if (entries.length === 0) {
+            this.log('  (none registered by the active theme)');
+        }
+        for (const [location, slug] of entries) {
+            this.log(`  ${location}: ${slug ?? '(unassigned)'}`);
+        }
+        return { locations, menus };
+    }
+}

package/dist/commands/menu/pull.d.ts

@@ -0,0 +1,15 @@
+import { LoopressCommand } from '../../lib/base.js';
+export default class Pull extends LoopressCommand {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private pullLocations;
+    private pullMenus;
+}

package/dist/commands/menu/pull.js

@@ -0,0 +1,72 @@
+import { Args } from '@oclif/core';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { LoopressCommand } from '../../lib/base.js';
+import { basenameKey, findOrphanedFiles } from '../../lib/find-orphaned-files.js';
+import { MENU_ENDPOINT, MENU_LOCATIONS_ENDPOINT } from '../../utils/menu-format.js';
+// The reserved local filename for menu locations (see pullLocations()): a menu genuinely slugged
+// "menu-locations" would collide with it, so it's skipped rather than silently overwriting that file.
+const LOCATIONS_FILE_BASENAME = 'menu-locations';
+export default class Pull extends LoopressCommand {
+    static args = {
+        path: Args.string({ description: 'Path to menus directory (overrides project config)' }),
+    };
+    static description = 'Pull nav menus and the active theme menu locations from WordPress';
+    static examples = ['$ lps menu pull'];
+    static flags = {
+        ...LoopressCommand.dryRunFlag,
+        ...LoopressCommand.yesFlag,
+    };
+    async run() {
+        const { args } = await this.parse(Pull);
+        const { url } = this.siteConfig;
+        const path = this.resolveMenuPath(args.path);
+        this.log(`Pulling nav menus from ${url}`);
+        this.log(`Menus path: ${path}`);
+        await this.pullMenus(path);
+        await this.pullLocations(path);
+    }
+    async pullLocations(basePath) {
+        const file = join(basePath, `${LOCATIONS_FILE_BASENAME}.json`);
+        const locations = await this.wp.get(MENU_LOCATIONS_ENDPOINT);
+        if (this.dryRun) {
+            this.log(`[dry-run] Would pull locations to ${file}`);
+            return;
+        }
+        await mkdir(basePath, { recursive: true });
+        await writeFile(file, JSON.stringify(locations, null, 2) + '\n');
+        this.log(`Pulled locations to ${file}`);
+    }
+    async pullMenus(dir) {
+        const fetched = await this.wp.get(MENU_ENDPOINT);
+        const remote = fetched.filter((menu) => {
+            if (menu.slug === LOCATIONS_FILE_BASENAME) {
+                this.warn(`Skipping menu "${menu.slug}": this filename is reserved for ${LOCATIONS_FILE_BASENAME}.json`);
+                return false;
+            }
+            return true;
+        });
+        const orphans = await findOrphanedFiles(dir, new Set(remote.map((menu) => menu.slug)), {
+            extensions: ['.json'],
+            key: (base) => (base === LOCATIONS_FILE_BASENAME ? null : basenameKey(base)),
+        });
+        await this.pullDirectory(dir, remote, orphans, {
+            dryRunMessage: `Would pull ${remote.length} menu(s) to ${dir}`,
+            orphanReason: `in ${dir} no longer present on WordPress`,
+            pulledMessage: `Pulled ${remote.length} menu(s) to ${dir}`,
+            title: (menu) => menu.slug,
+            // revision/warnings are server bookkeeping, never part of the tracked configuration (see
+            // their doc comments on Menu in menu-format.ts): never persisted locally.
+            async write(menu, writeDir) {
+                const local = { items: menu.items, name: menu.name, slug: menu.slug };
+                await writeFile(join(writeDir, `${menu.slug}.json`), JSON.stringify(local, null, 2) + '\n');
+            },
+        });
+        if (this.dryRun)
+            return;
+        for (const menu of remote) {
+            for (const warning of menu.warnings)
+                this.warn(`${menu.slug}: ${warning}`);
+        }
+    }
+}

package/dist/commands/menu/push.d.ts

@@ -0,0 +1,17 @@
+import { PushCommand } from '../../lib/push-command.js';
+export default class Push extends PushCommand {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private currentRevision;
+    private pushLocations;
+    private pushMenuFile;
+    private pushMenus;
+}