@loopress/cli 0.17.0 → 0.18.0

package/dist/commands/form/pull.js

@@ -0,0 +1,79 @@
+import { Args } from '@oclif/core';
+import { Listr } from 'listr2';
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import slugify from 'slugify';
+import { LoopressCommand } from '../../lib/base.js';
+import { FORM_ENDPOINT, getFormId, getFormTitle } from '../../utils/form-format.js';
+export default class Pull extends LoopressCommand {
+    static args = {
+        path: Args.string({ description: 'Path to forms directory (overrides project config)' }),
+    };
+    static description = 'Pull forms from WordPress';
+    static examples = ['$ lps form pull'];
+    static flags = {
+        ...LoopressCommand.dryRunFlag,
+    };
+    async run() {
+        const { args } = await this.parse(Pull);
+        const { url } = this.siteConfig;
+        const path = this.resolveFormPath(args.path);
+        this.log(`Pulling forms from ${url}`);
+        this.log(`Forms path: ${path}`);
+        const remoteList = await this.wp.get(FORM_ENDPOINT);
+        const withId = remoteList.filter((form) => getFormId(form) !== null);
+        const skipped = remoteList.length - withId.length;
+        const orphans = await this.findOrphanedFiles(path, new Set(withId.map((form) => getFormId(form))));
+        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(', ')}`);
+            }
+            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}-${slug(title)}.json`), JSON.stringify(form, null, 2) + '\n');
+                    task.output = `Pulled: ${title}`;
+                },
+                title: `Pull ${title}`,
+            };
+        })).run();
+        for (const file of orphans)
+            await rm(join(path, file), { force: true });
+        if (orphans.length > 0) {
+            this.warn(`Removed ${orphans.length} local file${orphans.length === 1 ? '' : 's'} in ${path} no longer present on WordPress: ${orphans.join(', ')}`);
+        }
+        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`);
+        }
+    }
+    // Only matches files following the `<id>-<slug>.json` convention pull/push themselves
+    // produce, same principle as findOrphanedFiles in commands/snippet/pull.ts.
+    async findOrphanedFiles(dir, keepIds) {
+        let files;
+        try {
+            files = await readdir(dir);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        return files.filter((file) => {
+            if (extname(file) !== '.json')
+                return false;
+            const match = /^(\d+)-/.exec(file);
+            return match !== null && !keepIds.has(Number(match[1]));
+        });
+    }
+}
+export function slug(title) {
+    return slugify(title, { lower: true, strict: true }) || 'untitled';
+}

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

@@ -0,0 +1,16 @@
+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: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    private failedCount;
+    run(): Promise<void>;
+    private ensureCanonicalFilename;
+    private loadFiles;
+    private pushForm;
+}

package/dist/commands/form/push.js

@@ -0,0 +1,130 @@
+import { Args } from '@oclif/core';
+import { Listr } from 'listr2';
+import { readdir, 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 { FORM_ENDPOINT, getFormId, getFormTitle } from '../../utils/form-format.js';
+import { slug } from './pull.js';
+export default class Push extends PushCommand {
+    static args = {
+        path: Args.string({ description: 'Path to forms directory (overrides project config)' }),
+    };
+    static description = 'Push forms to WordPress. Local files created or updated remotely are renamed on disk to the `<id>-<slug>.json` convention.';
+    static examples = ['$ lps form push'];
+    static flags = {
+        ...PushCommand.dryRunFlag,
+    };
+    failedCount = 0;
+    async run() {
+        const { args } = await this.parse(Push);
+        const { url } = this.siteConfig;
+        const path = this.resolveFormPath(args.path);
+        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();
+        if (this.failedCount > 0) {
+            this.error(`${this.failedCount} form${this.failedCount === 1 ? '' : 's'} failed to push.`);
+        }
+        if (this.dryRun)
+            return;
+        await this.recordSuccess();
+        this.log('All forms pushed.');
+    }
+    // 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
+    // commands/snippet/push.ts.
+    async ensureCanonicalFilename(filePath, id, title) {
+        const canonicalPath = join(dirname(filePath), `${id}-${slug(title)}.json`);
+        if (filePath !== canonicalPath)
+            await rename(filePath, canonicalPath);
+    }
+    // One file is read in isolation: a corrupted or hand-broken JSON file must only skip that
+    // 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 forms = [];
+        for (const file of files) {
+            if (extname(file) !== '.json')
+                continue;
+            const filePath = join(dir, file);
+            let parsed;
+            try {
+                parsed = JSON.parse(await readFile(filePath, 'utf8'));
+            }
+            catch (error) {
+                this.warn(`Skipping "${filePath}": ${error.message}`);
+                continue;
+            }
+            if (typeof parsed !== 'object' || parsed === null) {
+                this.warn(`Skipping "${filePath}": not a JSON object`);
+                continue;
+            }
+            forms.push({ data: parsed, filePath });
+        }
+        return forms;
+    }
+    // Throwing on failure (rather than returning a boolean) is what lets Listr mark the task as
+    // failed (red cross) instead of completed; `exitOnError: false` on the task list still lets
+    // sibling forms push regardless. 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) {
+            if (task)
+                task.output = `[dry-run] Would push: ${title}`;
+            return;
+        }
+        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);
+                }
+            }
+            if (task)
+                task.output = `Pushed: ${title}`;
+        }
+        catch (error) {
+            const message = `Failed to push ${title}: ${error.message}`;
+            if (task)
+                task.output = message;
+            else
+                this.warn(`  ${message}`);
+            this.failedCount++;
+            throw error;
+        }
+    }
+}

package/dist/lib/base.d.ts

@@ -14,6 +14,8 @@ export declare abstract class LoopressCommand extends Command {
     protected get wp(): WpClient;
     init(): Promise<void>;
     protected resolveAcfPath(override?: string): string;
+    protected resolveApiPath(override?: string): string;
+    protected resolveFormPath(override?: string): string;
     protected resolveSeoPath(override?: string): string;
     protected resolveSnippetsPath(override?: string): string;
     private resolveEnvironment;

package/dist/lib/base.js

@@ -40,6 +40,16 @@ export class LoopressCommand extends Command {
             return override;
         return join(this.rootDir, this.localConfig.acfDir ?? 'acf');
     }
+    resolveApiPath(override) {
+        if (override)
+            return override;
+        return join(this.rootDir, this.localConfig.apiDir ?? 'api');
+    }
+    resolveFormPath(override) {
+        if (override)
+            return override;
+        return join(this.rootDir, this.localConfig.formDir ?? 'forms');
+    }
     resolveSeoPath(override) {
         if (override)
             return override;

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

@@ -19,6 +19,14 @@ export interface LoopressProjectConfiguration {
      * Directory where SEO settings, post meta, and redirects (RankMath and Yoast SEO, whichever is active) are read from and written to, relative to rootDir.
      */
     seoDir?: string;
+    /**
+     * Directory where forms (WPForms today) are read from and written to, relative to rootDir.
+     */
+    formDir?: string;
+    /**
+     * Directory where custom API route files are read from and written to, relative to rootDir.
+     */
+    apiDir?: string;
     /**
      * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
      */

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

@@ -0,0 +1,3 @@
+export declare const FORM_ENDPOINT = "loopress/v1/forms";
+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

@@ -0,0 +1,17 @@
+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 getFormId(data) {
+    const id = Number(data.id);
+    return Number.isInteger(id) && id > 0 ? id : null;
+}
+export function getFormTitle(data) {
+    const settings = data.settings;
+    const title = settings?.form_title;
+    return typeof title === 'string' && title.trim() !== '' ? title : '(untitled)';
+}