@loopress/cli 0.20.1 → 0.22.0

package/dist/commands/dev.js

@@ -0,0 +1,97 @@
+import { Command, Flags } from '@oclif/core';
+import { watch as watchFiles } from 'chokidar';
+import { basename } from 'node:path';
+import { configManager } from '../config/project-config.manager.js';
+import { buildWatchTargets, createDebouncedBatcher, resolveResourceTypes, RESOURCE_TYPES, resourceTypeForPath } from '../lib/dev-watch.js';
+import { readLocalConfig } from '../utils/loopress-config.js';
+const DEBOUNCE_MS = 400;
+// Noise no one wants pushed: VCS internals, deps, and editor/OS droppings.
+const IGNORED = /(?:(^|[/\\])(\.git|node_modules|\.DS_Store)(?:[/\\]|$))|(?:\.swp$)/;
+export default class Dev extends Command {
+    static description = 'Watch project files and push changes to the local WordPress instance as they happen. Always targets the "local" environment, run `lps snippet push` etc. directly for any other environment.';
+    static examples = ['$ lps dev', '$ lps dev --only=snippets,pages', '$ lps dev --skip=plugins'];
+    static flags = {
+        only: Flags.string({ description: `Only watch these resource types (comma-separated): ${RESOURCE_TYPES.join(', ')}` }),
+        skip: Flags.string({ description: `Skip these resource types (comma-separated): ${RESOURCE_TYPES.join(', ')}` }),
+    };
+    async run() {
+        const { flags } = await this.parse(Dev);
+        const only = flags.only ? this.parseTypeFlag(flags.only, 'only') : undefined;
+        const skip = flags.skip ? this.parseTypeFlag(flags.skip, 'skip') : [];
+        const types = resolveResourceTypes(only, skip);
+        const localConfig = await readLocalConfig();
+        const projectId = localConfig.projectId ?? configManager.getCurrentProject()?.id;
+        if (!projectId)
+            this.error('No project configured. Run `lps project config` first.');
+        if (!configManager.getEnvironment(projectId, 'local')) {
+            this.error('No "local" environment configured for this project. Run `lps project config` and add a "local" environment.');
+        }
+        const targets = buildWatchTargets(types, localConfig, process.cwd());
+        if (targets.length === 0) {
+            this.error('Nothing to watch: none of the selected resource directories exist yet.');
+        }
+        for (const target of targets)
+            this.log(`Watching ${target.type}: ${target.path}`);
+        await this.watch(targets);
+    }
+    parseTypeFlag(raw, flagName) {
+        return raw
+            .split(',')
+            .map((value) => value.trim())
+            .filter(Boolean)
+            .map((value) => {
+            if (!RESOURCE_TYPES.includes(value)) {
+                this.error(`Unknown resource type "${value}" in --${flagName}. Valid types: ${RESOURCE_TYPES.join(', ')}`);
+            }
+            return value;
+        });
+    }
+    // Sequential on purpose (see notes technique: parallelizing push is out of scope). A failed
+    // push is logged and swallowed here, never thrown, so one bad batch can't take the watcher down.
+    async pushBatch(changesByType, targets) {
+        for (const [type, paths] of changesByType) {
+            const target = targets.find((t) => t.type === type);
+            if (!target)
+                continue;
+            this.log(`\n→ ${type} changed (${paths.map((path) => basename(path)).join(', ')}), pushing to local...`);
+            try {
+                await this.config.runCommand(target.commandId, ['--env', 'local']);
+                this.log(`✓ ${type} synced`);
+            }
+            catch (error) {
+                this.log(`✗ ${type} failed: ${error.message}`);
+            }
+        }
+    }
+    async watch(targets) {
+        const batcher = createDebouncedBatcher(async (paths) => {
+            const changesByType = new Map();
+            for (const path of paths) {
+                const type = resourceTypeForPath(path, targets);
+                if (!type)
+                    continue;
+                changesByType.set(type, [...(changesByType.get(type) ?? []), path]);
+            }
+            await this.pushBatch(changesByType, targets);
+        }, DEBOUNCE_MS);
+        const watcher = watchFiles(targets.map((target) => target.path), {
+            awaitWriteFinish: { pollInterval: 100, stabilityThreshold: 300 },
+            ignoreInitial: true,
+            ignored: (path) => IGNORED.test(path),
+        });
+        watcher
+            .on('add', batcher.queue)
+            .on('change', batcher.queue)
+            .on('unlink', (filePath) => { this.log(`⚠ ${filePath} deleted locally, not synced automatically`); });
+        this.log('\nWatching for changes. Press Ctrl+C to stop.\n');
+        await new Promise((resolve) => {
+            process.once('SIGINT', () => { resolve(); });
+        });
+        batcher.cancel();
+        await watcher.close();
+        // A push failure mid-session sets process.exitCode; stopping the watcher on purpose is a
+        // clean exit regardless of that history (see AC: no meaningful exit code needed for `dev`).
+        process.exitCode = 0;
+        this.log('\nStopped watching.');
+    }
+}

package/dist/commands/doctor.js

@@ -2,6 +2,7 @@ import { configManager } from '../config/project-config.manager.js';
 import { LoopressCommand } from '../lib/base.js';
 import { isNotFoundError } from '../lib/wp-client.js';
 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 examples = ['$ lps doctor', '$ lps doctor --env production'];
@@ -15,12 +16,12 @@ export default class Doctor extends LoopressCommand {
         this.log(`URL:          ${url}`);
         this.log('');
         let failed = 0;
-        const reachable = await this.check('WordPress REST API reachable', async () => {
+        const isReachable = await this.check('WordPress REST API reachable', async () => {
             const diagnostic = await diagnoseWpSite(url);
             if (!diagnostic.ok)
                 throw new Error(diagnostic.reason);
         });
-        if (!reachable) {
+        if (!isReachable) {
             failed++;
             this.log('- Remaining checks skipped while the site is unreachable.');
             this.error('1 check failed.', { exit: 1 });
@@ -34,18 +35,18 @@ export default class Doctor extends LoopressCommand {
         // 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)', () => this.wp.get('loopress/v1')))) {
+        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)', () => this.wp.get('wp/v2/users/me')))) {
+        if (!(await this.check('Credentials accepted (authenticated request)', async () => this.wp.get('wp/v2/users/me')))) {
             failed++;
         }
         await this.reportPluginVersion();
         this.log('');
         if (failed > 0) {
-            this.error(`${failed} check${failed === 1 ? '' : 's'} failed.`, { exit: 1 });
+            this.error(`${pluralize(failed, 'check')} failed.`, { exit: 1 });
         }
         this.log('All checks passed.');
     }

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

@@ -1,9 +1,7 @@
 import { LoopressCommand } from '../../lib/base.js';
 export default class List extends LoopressCommand {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
-    static flags: {
-        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    };
-    run(): Promise<void>;
+    run(): Promise<Array<Record<string, unknown>>>;
 }

package/dist/commands/form/list.js

@@ -1,26 +1,19 @@
-import { Flags } from '@oclif/core';
 import { LoopressCommand } from '../../lib/base.js';
 import { FORM_ENDPOINT, getFormId, getFormTitle } from '../../utils/form-format.js';
 export default class List extends LoopressCommand {
     static description = 'List forms from WordPress';
+    static enableJsonFlag = true;
     static examples = ['$ lps form list'];
-    static flags = {
-        json: Flags.boolean({ char: 'j', description: 'Output in JSON format' }),
-    };
     async run() {
-        const { flags } = await this.parse(List);
         const forms = await this.wp.get(FORM_ENDPOINT);
-        if (flags.json) {
-            this.log(JSON.stringify(forms, null, 2));
-            return;
-        }
         this.log(`Forms (${forms.length}):`);
         if (forms.length === 0) {
             this.log('  (none)');
-            return;
+            return forms;
         }
         for (const form of forms) {
             this.log(`  ${getFormId(form) ?? '(no id)'}. ${getFormTitle(form)}`);
         }
+        return forms;
     }
 }

package/dist/commands/form/pull.js

@@ -1,10 +1,10 @@
 import { Args } from '@oclif/core';
-import { Listr } from 'listr2';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { LoopressCommand } from '../../lib/base.js';
 import { findOrphanedFiles, numericPrefixKey } from '../../lib/find-orphaned-files.js';
 import { FORM_ENDPOINT, getFormId, getFormTitle } from '../../utils/form-format.js';
+import { pluralize } from '../../utils/pluralize.js';
 import { toSlug } from '../../utils/to-slug.js';
 export default class Pull extends LoopressCommand {
     static args = {
@@ -31,30 +31,21 @@ export default class Pull extends LoopressCommand {
             extensions: ['.json'],
             key: numericPrefixKey,
         });
-        if (this.dryRun) {
-            this.log(`[dry-run] Would pull ${withId.length} form${withId.length === 1 ? '' : 's'} to ${path}`);
-            if (orphans.length > 0) {
-                this.log(`[dry-run] Would remove ${orphans.length} local file${orphans.length === 1 ? '' : 's'} in ${path} no longer present on WordPress: ${orphans.join(', ')}`);
-            }
+        await this.pullDirectory(path, withId, orphans, {
+            dryRunMessage: `Would pull ${pluralize(withId.length, 'form')} to ${path}`,
+            orphanReason: `in ${path} no longer present on WordPress`,
+            pulledMessage: `Pulled ${pluralize(withId.length, 'form')} to ${path}`,
+            title: (form) => getFormTitle(form),
+            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');
+            },
+        });
+        if (this.dryRun)
             return;
-        }
-        if (withId.length > 0)
-            await mkdir(path, { recursive: true });
-        await new Listr(withId.map((form) => {
-            const id = getFormId(form);
-            const title = getFormTitle(form);
-            return {
-                async task(_ctx, task) {
-                    await writeFile(join(path, `${id}-${toSlug(title, 'untitled')}.json`), JSON.stringify(form, null, 2) + '\n');
-                    task.output = `Pulled: ${title}`;
-                },
-                title: `Pull ${title}`,
-            };
-        })).run();
-        await this.removeOrphanedFiles(path, orphans, `in ${path} no longer present on WordPress`);
-        this.log(`Pulled ${withId.length} form${withId.length === 1 ? '' : 's'} to ${path}`);
         if (skipped > 0) {
-            this.warn(`${skipped} form${skipped === 1 ? '' : 's'} skipped because they have no id`);
+            this.warn(`${pluralize(skipped, 'form')} skipped because they have no id`);
         }
     }
 }

package/dist/commands/form/push.js

@@ -1,10 +1,11 @@
 import { Args } from '@oclif/core';
-import { Listr } from 'listr2';
-import { readdir, readFile, rename } from 'node:fs/promises';
+import { readFile, rename } from 'node:fs/promises';
 import { dirname, extname, join } from 'node:path';
 import { PushCommand } from '../../lib/push-command.js';
-import { isNotFoundError } from '../../lib/wp-client.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 { pluralize } from '../../utils/pluralize.js';
 import { toSlug } from '../../utils/to-slug.js';
 export default class Push extends PushCommand {
     static args = {
@@ -23,13 +24,10 @@ export default class Push extends PushCommand {
         this.log(`Pushing forms to ${url}`);
         this.log(`Forms path: ${path}`);
         const files = await this.loadFiles(path);
-        this.log(`Found ${files.length} form${files.length === 1 ? '' : 's'} to push`);
-        await new Listr(files.map(({ data, filePath }) => ({
-            task: async (_ctx, task) => this.pushForm(filePath, data, task),
-            title: `Push ${getFormTitle(data)}`,
-        })), { concurrent: false, exitOnError: false }).run();
+        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));
         if (this.failedCount > 0) {
-            this.error(`${this.failedCount} form${this.failedCount === 1 ? '' : 's'} failed to push.`);
+            this.error(`${pluralize(this.failedCount, 'form')} failed to push.`);
         }
         if (this.dryRun)
             return;
@@ -49,15 +47,7 @@ export default class Push extends PushCommand {
     // form, not abort loading the rest of the directory, same principle as loadObjects() in
     // commands/acf/push.ts.
     async loadFiles(dir) {
-        let files;
-        try {
-            files = await readdir(dir);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return [];
-            throw error;
-        }
+        const files = await readdirTolerant(dir);
         const forms = [];
         for (const file of files) {
             if (extname(file) !== '.json')
@@ -79,8 +69,6 @@ export default class Push extends PushCommand {
         }
         return forms;
     }
-    // PUT-then-404-fallback-POST is the same dance as commands/snippet/push.ts, forms are
-    // id-based like snippets, not key-based like ACF.
     async pushForm(filePath, data, task) {
         const title = getFormTitle(data);
         if (this.dryRun) {
@@ -90,28 +78,15 @@ export default class Push extends PushCommand {
         }
         try {
             const id = getFormId(data);
-            if (id === null) {
-                const created = await this.wp.post(FORM_ENDPOINT, data);
-                const newId = getFormId(created);
-                if (newId !== null)
-                    await this.ensureCanonicalFilename(filePath, newId, title);
-            }
-            else {
-                try {
-                    await this.wp.put(`${FORM_ENDPOINT}/${id}`, data);
-                    await this.ensureCanonicalFilename(filePath, id, title);
-                }
-                catch (error) {
-                    // The id recorded locally doesn't exist on this site (e.g. a fresh install): create
-                    // it instead of failing, and adopt whatever id the site assigns.
-                    if (!isNotFoundError(error))
-                        throw error;
-                    const created = await this.wp.post(FORM_ENDPOINT, data);
-                    const newId = getFormId(created);
-                    if (newId !== null)
-                        await this.ensureCanonicalFilename(filePath, newId, title);
-                }
-            }
+            const { body, created } = await putOrCreate(this.wp, {
+                id,
+                payload: data,
+                postEndpoint: FORM_ENDPOINT,
+                putEndpoint: (formId) => `${FORM_ENDPOINT}/${formId}`,
+            });
+            const canonicalId = created ? getFormId(body) : id;
+            if (canonicalId !== null)
+                await this.ensureCanonicalFilename(filePath, canonicalId, title);
             if (task)
                 task.output = `Pushed: ${title}`;
         }

package/dist/commands/init.js

@@ -29,11 +29,11 @@ export default class Init extends Command {
         }
         const configPath = join(process.cwd(), 'loopress.json');
         if (existsSync(configPath)) {
-            const overwrite = await confirm({
+            const isOverwrite = await confirm({
                 default: false,
                 message: 'loopress.json already exists. Overwrite?',
             });
-            if (!overwrite) {
+            if (!isOverwrite) {
                 this.log('Aborted.');
                 return;
             }
@@ -65,11 +65,11 @@ export default class Init extends Command {
                 config[feature.key] = feature.dir;
         }
         await writeLocalConfig(config);
-        let providerAdded = false;
+        let isProviderAdded = false;
         if (providerChoice !== '__none__') {
             try {
                 await this.config.runCommand('plugin:add', [providerChoice]);
-                providerAdded = true;
+                isProviderAdded = true;
             }
             catch (error) {
                 this.warn(error.message);
@@ -83,7 +83,7 @@ export default class Init extends Command {
                 this.log(`  ${feature.label}:${' '.repeat(Math.max(1, 9 - feature.label.length))}${join(rootDir, feature.dir)}`);
             }
         }
-        if (providerAdded) {
+        if (isProviderAdded) {
             this.log(`  Plugin:   ${providerChoice}`);
         }
         this.log('\n→ Next: run `lps snippet pull` to fetch what is already on the site, or `lps doctor` to verify the connection.');
@@ -102,8 +102,8 @@ export default class Init extends Command {
         let projects = configManager.listProjects();
         if (projects.length === 0) {
             this.log('No projects configured yet.');
-            const runConfig = await confirm({ default: true, message: 'Run `lps project config` now to add one?' });
-            if (!runConfig) {
+            const isRunConfig = await confirm({ default: true, message: 'Run `lps project config` now to add one?' });
+            if (!isRunConfig) {
                 return this.promptManualProjectId();
             }
             await this.config.runCommand('project:config');

package/dist/commands/login.js

@@ -8,21 +8,25 @@ export default class Login extends Command {
     async run() {
         const { email, token } = await this.waitForCallback();
         authManager.setAuth({ email, savedAt: new Date().toISOString(), token });
-        this.log(`\nLogged in${email ? ` as ${email}` : ''}. You're all set!`);
+        const emailSuffix = email ? ` as ${email}` : '';
+        this.log(`\nLogged in${emailSuffix}. You're all set!`);
     }
-    waitForCallback() {
+    async waitForCallback() {
         return waitForLocalCallback({
-            buildUrl: (callbackBaseUrl) => `${CONSOLE_URL}/cli-auth?callbackUrl=${encodeURIComponent(`${callbackBaseUrl}/callback`)}`,
+            buildUrl(callbackBaseUrl) {
+                const callbackUrl = encodeURIComponent(`${callbackBaseUrl}/callback`);
+                return `${CONSOLE_URL}/cli-auth?callbackUrl=${callbackUrl}`;
+            },
             handleRequest(url, { resolveWithPage, respondBadRequest }) {
                 const token = url.searchParams.get('token');
-                const email = url.searchParams.get('email') ?? undefined;
                 if (!token) {
                     respondBadRequest('Missing token');
                     return;
                 }
+                const email = url.searchParams.get('email') ?? undefined;
                 resolveWithPage(SUCCESS_PAGE, { email, token });
             },
-            log: (message) => this.log(message),
+            log: (message) => { this.log(message); },
             openingMessage: 'Opening Loopress console in your browser...',
             timeoutMessage: 'Login timed out after 5 minutes. Please try again.',
         });

package/dist/commands/logout.js

@@ -10,6 +10,7 @@ export default class Logout extends Command {
             return;
         }
         authManager.clearAuth();
-        this.log(`Logged out${auth.email ? ` (${auth.email})` : ''}.`);
+        const emailSuffix = auth.email ? ` (${auth.email})` : '';
+        this.log(`Logged out${emailSuffix}.`);
     }
 }

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

@@ -1,9 +1,7 @@
 import { LoopressCommand } from '../../lib/base.js';
 export default class List extends LoopressCommand {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
-    static flags: {
-        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    };
-    run(): Promise<void>;
+    run(): Promise<Array<Record<string, unknown>>>;
 }

package/dist/commands/page/list.js

@@ -1,26 +1,19 @@
-import { Flags } from '@oclif/core';
 import { LoopressCommand } from '../../lib/base.js';
 import { getPageId, getPageTitle, PAGE_ENDPOINT, PAGE_LIST_QUERY } from '../../utils/page-format.js';
 export default class List extends LoopressCommand {
     static description = 'List pages from WordPress';
+    static enableJsonFlag = true;
     static examples = ['$ lps page list'];
-    static flags = {
-        json: Flags.boolean({ char: 'j', description: 'Output in JSON format' }),
-    };
     async run() {
-        const { flags } = await this.parse(List);
         const pages = await this.wp.get(`${PAGE_ENDPOINT}?${PAGE_LIST_QUERY}`);
-        if (flags.json) {
-            this.log(JSON.stringify(pages, null, 2));
-            return;
-        }
         this.log(`Pages (${pages.length}):`);
         if (pages.length === 0) {
             this.log('  (none)');
-            return;
+            return pages;
         }
         for (const page of pages) {
             this.log(`  ${getPageId(page) ?? '(no id)'}. ${getPageTitle(page)}`);
         }
+        return pages;
     }
 }

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

@@ -1,13 +1,25 @@
 import { LoopressCommand } from '../../lib/base.js';
+type PulledPage = {
+    id: number;
+    title: string;
+};
+type PullResult = {
+    orphans: string[];
+    pulled: PulledPage[];
+    skipped: number;
+    status: 'dry-run' | 'success';
+};
 export default class Pull extends LoopressCommand {
     static args: {
         path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    run(): Promise<void>;
+    run(): Promise<PullResult>;
 }
+export {};

package/dist/commands/page/pull.js

@@ -1,15 +1,16 @@
 import { Args } from '@oclif/core';
-import { Listr } from 'listr2';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { LoopressCommand } from '../../lib/base.js';
 import { findOrphanedFiles, numericPrefixKey } from '../../lib/find-orphaned-files.js';
 import { getPageContent, getPageId, getPageTitle, PAGE_ENDPOINT, PAGE_LIST_QUERY, pageFileBase, pickPageMeta } from '../../utils/page-format.js';
+import { pluralize } from '../../utils/pluralize.js';
 export default class Pull extends LoopressCommand {
     static args = {
         path: Args.string({ description: 'Path to pages directory (overrides project config)' }),
     };
     static description = 'Pull pages from WordPress';
+    static enableJsonFlag = true;
     static examples = ['$ lps page pull'];
     static flags = {
         ...LoopressCommand.dryRunFlag,
@@ -32,34 +33,25 @@ export default class Pull extends LoopressCommand {
             extensions: ['.json', '.html'],
             key: numericPrefixKey,
         });
-        if (this.dryRun) {
-            this.log(`[dry-run] Would pull ${withId.length} page${withId.length === 1 ? '' : 's'} to ${path}`);
-            if (orphans.length > 0) {
-                this.log(`[dry-run] Would remove ${orphans.length} local file${orphans.length === 1 ? '' : 's'} in ${path} no longer present on WordPress: ${orphans.join(', ')}`);
-            }
-            return;
-        }
-        if (withId.length > 0)
-            await mkdir(path, { recursive: true });
-        await new Listr(withId.map((page) => {
-            const id = getPageId(page);
-            const title = getPageTitle(page);
-            return {
-                async task(_ctx, task) {
-                    const base = pageFileBase(id, title);
-                    // `content` lives entirely in the `.html` file; the `.json` sidecar keeps only the
-                    // fields WordPress actually accepts back on write, see pickPageMeta.
-                    await writeFile(join(path, `${base}.html`), getPageContent(page));
-                    await writeFile(join(path, `${base}.json`), JSON.stringify(pickPageMeta(page), null, 2) + '\n');
-                    task.output = `Pulled: ${title}`;
-                },
-                title: `Pull ${title}`,
-            };
-        })).run();
-        await this.removeOrphanedFiles(path, orphans, `in ${path} no longer present on WordPress`);
-        this.log(`Pulled ${withId.length} page${withId.length === 1 ? '' : 's'} to ${path}`);
+        const pulled = withId.map((page) => ({ id: getPageId(page), title: getPageTitle(page) }));
+        await this.pullDirectory(path, withId, orphans, {
+            dryRunMessage: `Would pull ${pluralize(withId.length, 'page')} to ${path}`,
+            orphanReason: `in ${path} no longer present on WordPress`,
+            pulledMessage: `Pulled ${pluralize(withId.length, 'page')} to ${path}`,
+            title: (page) => getPageTitle(page),
+            async write(page, writeDir) {
+                const base = pageFileBase(getPageId(page), getPageTitle(page));
+                // `content` lives entirely in the `.html` file; the `.json` sidecar keeps only the
+                // fields WordPress actually accepts back on write, see pickPageMeta.
+                await writeFile(join(writeDir, `${base}.html`), getPageContent(page));
+                await writeFile(join(writeDir, `${base}.json`), JSON.stringify(pickPageMeta(page), null, 2) + '\n');
+            },
+        });
+        if (this.dryRun)
+            return { orphans, pulled, skipped, status: 'dry-run' };
         if (skipped > 0) {
-            this.warn(`${skipped} page${skipped === 1 ? '' : 's'} skipped because they have no id`);
+            this.warn(`${pluralize(skipped, 'page')} skipped because they have no id`);
         }
+        return { orphans, pulled, skipped, status: 'success' };
     }
 }

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

@@ -1,16 +1,26 @@
 import { PushCommand } from '../../lib/push-command.js';
+type PushedPage = {
+    id: null | number;
+    title: string;
+};
+type PushResult = {
+    pushed: PushedPage[];
+    status: 'dry-run' | 'success';
+};
 export default class Push extends PushCommand {
     static args: {
         path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    run(): Promise<void>;
+    run(): Promise<PushResult>;
     private ensureCanonicalFilename;
     private loadFiles;
     private pushPage;
 }
+export {};