@loopress/cli 0.23.0 → 0.24.0

package/dist/lib/php-files-command.js

@@ -0,0 +1,216 @@
+import { Args } from '@oclif/core';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { authManager } from '../config/auth.manager.js';
+import { pluralize } from '../utils/pluralize.js';
+import { resolveResourceDir, RESOURCE_DIR_DEFAULTS } from '../utils/resource-dirs.js';
+import { ApiClient } from './api-client.js';
+import { LoopressCommand } from './base.js';
+import { basenameKey, findOrphanedFiles } from './find-orphaned-files.js';
+import { loadFiles as loadDirectoryFiles } from './load-files.js';
+import { PushCommand } from './push-command.js';
+// Mirrors wordpress-plugin FileWriter::DECLARE_PATTERN / withGuard(): the server rejects both
+// an absent declare(strict_types=1); and one that appears more than once (it needs a single
+// unambiguous insertion point for the ABSPATH guard). Matching "exactly once" here, not just
+// presence, so a file that would still fail server-side doesn't falsely pass this check.
+const DECLARE_PATTERN = /declare\s*\(\s*strict_types\s*=\s*1\s*\)\s*;/g;
+function pathArg(pathNoun) {
+    return { path: Args.string({ description: `Path to ${pathNoun} (overrides project config)` }) };
+}
+// relative()'s separator is OS-specific ('\\' on Windows); the server only ever expects '/',
+// same as any URL or import path.
+async function loadPhpFiles(command, dir) {
+    return loadDirectoryFiles(dir, {
+        extension: '.php',
+        onSkip(message) { command.warn(message); },
+        parse: (raw, filePath) => ({
+            content: raw,
+            filename: relative(dir, filePath).slice(0, -'.php'.length).split(sep).join('/'),
+        }),
+        recursive: true,
+    });
+}
+export function resourcePushCommand(spec) {
+    class ResourcePush extends PushCommand {
+        static args = pathArg(spec.pathNoun);
+        static description = spec.pushDescription;
+        static enableJsonFlag = true;
+        static examples = [`$ lps ${spec.cliName} push`, `$ lps ${spec.cliName} push --path ./${RESOURCE_DIR_DEFAULTS[spec.dirKind]}`];
+        static flags = { ...PushCommand.dryRunFlag, ...PushCommand.yesFlag };
+        async run() {
+            const { args } = await this.parse(ResourcePush);
+            const { url } = this.siteConfig;
+            const path = resolveResourceDir(spec.dirKind, this.localConfig, args.path);
+            this.log(`Pushing ${spec.label} to ${url}`);
+            this.log(`${spec.pathLabel} path: ${path}`);
+            const files = await this.loadFiles(path);
+            this.log(`Found ${pluralize(files.length, spec.noun)} to push`);
+            const pushed = [];
+            await this.runPushTasks(files, (file) => file.filename, async (file, task) => {
+                await this.pushFile(file, task);
+                pushed.push(file.filename);
+            });
+            if (this.failedCount > 0) {
+                this.error(`${pluralize(this.failedCount, spec.noun)} failed to push.`);
+            }
+            if (this.dryRun)
+                return { pushed, status: 'dry-run' };
+            await this.recordSuccess();
+            await spec.afterPush?.({ filenames: pushed, siteConfig: this.siteConfig });
+            this.log(`All ${spec.label} pushed.`);
+            return { pushed, status: 'success' };
+        }
+        async loadFiles(path) {
+            return loadPhpFiles(this, path);
+        }
+        async pushFile(file, task) {
+            if (!spec.filenamePattern.test(file.filename)) {
+                const message = `Invalid filename "${file.filename}": ${spec.invalidFilenameHint}`;
+                this.reportTaskFailure(message, new Error(message), task);
+            }
+            const declareCount = file.content.match(DECLARE_PATTERN)?.length ?? 0;
+            if (declareCount !== 1) {
+                const reason = declareCount === 0 ? 'is missing' : 'appears more than once';
+                const message = `${file.filename}.php: "declare(strict_types=1);" ${reason}, it must appear exactly once as the first statement`;
+                this.reportTaskFailure(message, new Error(message), task);
+            }
+            if (this.dryRun) {
+                if (task)
+                    task.output = `[dry-run] Would push: ${file.filename}`;
+                return;
+            }
+            try {
+                const result = await this.wp.put(spec.endpoint, {
+                    content: file.content,
+                    filename: file.filename,
+                });
+                if (task) {
+                    task.output =
+                        result.syntax_check === 'skipped'
+                            ? `Pushed: ${file.filename} (syntax check skipped, unavailable on this host)`
+                            : `Pushed: ${file.filename}`;
+                }
+            }
+            catch (error) {
+                this.reportTaskFailure(`Failed to push ${file.filename}: ${error.message}`, error, task);
+            }
+        }
+    }
+    return ResourcePush;
+}
+export function resourcePullCommand(spec) {
+    class ResourcePull extends LoopressCommand {
+        static args = pathArg(spec.pathNoun);
+        static description = spec.pullDescription;
+        static enableJsonFlag = true;
+        static examples = [`$ lps ${spec.cliName} pull`, `$ lps ${spec.cliName} pull --path ./${RESOURCE_DIR_DEFAULTS[spec.dirKind]}`];
+        static flags = { ...LoopressCommand.dryRunFlag, ...LoopressCommand.yesFlag };
+        async run() {
+            const { args } = await this.parse(ResourcePull);
+            const { url } = this.siteConfig;
+            const path = resolveResourceDir(spec.dirKind, this.localConfig, args.path);
+            this.log(`Pulling ${spec.label} from ${url}`);
+            this.log(`${spec.pathLabel} path: ${path}`);
+            const files = await this.wp.get(spec.endpoint);
+            // A `<filename>.php` no longer present remotely was deleted on WordPress (push stays
+            // additive-only, but pull already cleans up locally, same as `snippet pull`).
+            const orphans = await findOrphanedFiles(path, new Set(files.map((file) => file.filename)), {
+                extensions: ['.php'],
+                key: basenameKey,
+                recursive: true,
+            });
+            const pulled = files.map((file) => file.filename);
+            await this.pullDirectory(path, files, orphans, {
+                alwaysCreateDir: true,
+                dryRunMessage: `Would pull ${pluralize(files.length, spec.noun)} to ${path}`,
+                orphanReason: spec.orphanReason,
+                pulledMessage: `Pulled ${pluralize(files.length, spec.noun)} to ${path}`,
+                title: (file) => file.filename,
+                async write(file, writeDir) {
+                    const filePath = join(writeDir, `${file.filename}.php`);
+                    // filename can contain '/' (a nested slug, e.g. content/filters or a path-param
+                    // route invoice-pdf/[order_id]): writeFile() doesn't create parent directories on
+                    // its own the way mkdir()'s recursive option does above for the top-level path.
+                    await mkdir(dirname(filePath), { recursive: true });
+                    await writeFile(filePath, file.content);
+                },
+            });
+            if (this.dryRun)
+                return { orphans, pulled, status: 'dry-run' };
+            return { orphans, pulled, status: 'success' };
+        }
+    }
+    return ResourcePull;
+}
+export function resourceListCommand(spec) {
+    class ResourceList extends LoopressCommand {
+        static description = spec.listDescription;
+        static enableJsonFlag = true;
+        static examples = [`$ lps ${spec.cliName} list`];
+        async run() {
+            const files = await this.wp.get(spec.endpoint);
+            if (files.length === 0) {
+                this.log(spec.emptyListMessage);
+                return files;
+            }
+            this.log(`Found ${pluralize(files.length, spec.noun)}:`);
+            this.log('');
+            for (const file of files) {
+                this.log(`  ${file.filename}`);
+            }
+            return files;
+        }
+    }
+    return ResourceList;
+}
+export const API_FILES_RESOURCE = {
+    // Best-effort report of the current route list to the Loopress cloud, purely for console
+    // visibility (US-18): the routes are already live on WordPress by this point, so this can
+    // never block or fail the push, same reasoning as `recordDeployment` in PushCommand.
+    async afterPush({ filenames, siteConfig }) {
+        const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token;
+        const { apiEnvironmentId } = siteConfig;
+        if (!token || !apiEnvironmentId)
+            return;
+        try {
+            await new ApiClient(token).put('api-routes', { environmentId: apiEnvironmentId, filenames });
+        }
+        catch {
+            // non-blocking: reporting the route list must never interrupt the push flow
+        }
+    },
+    cliName: 'api',
+    dirKind: 'api',
+    emptyListMessage: 'No API route files found',
+    endpoint: 'loopress/v1/api-files',
+    // Mirrors ApiFilesController::isValidFilename(): kebab-case segments or a bracketed dynamic
+    // segment like [order_id], joined by '/'.
+    filenamePattern: /^(?:[a-z0-9-]+|\[[A-Za-z_]\w*\])(?:\/(?:[a-z0-9-]+|\[[A-Za-z_]\w*\]))*$/,
+    invalidFilenameHint: 'each path segment must be lowercase letters, digits, and hyphens, or a bracketed dynamic segment like "[order_id]" (e.g. "invoice-pdf/[order_id].php")',
+    label: 'API routes',
+    listDescription: 'List custom API route files from WordPress',
+    noun: 'route file',
+    orphanReason: 'whose route no longer exists on WordPress',
+    pathLabel: 'API',
+    pathNoun: 'api directory',
+    pullDescription: 'Pull custom API route files from WordPress',
+    pushDescription: 'Push custom API route files to WordPress',
+};
+export const HOOK_FILES_RESOURCE = {
+    cliName: 'hook',
+    dirKind: 'hooks',
+    emptyListMessage: 'No hook files found',
+    endpoint: 'loopress/v1/hook-files',
+    // Mirrors HookFilesController::isValidFilename(): kebab-case segments joined by '/', no
+    // bracketed dynamic-segment alternative (a hook slug is never a URL path).
+    filenamePattern: /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/,
+    invalidFilenameHint: 'each path segment must be lowercase letters, digits, and hyphens (e.g. "content-filters.php" or "content/filters.php")',
+    label: 'hooks',
+    listDescription: 'List hook files (actions, filters, cron) from WordPress',
+    noun: 'hook file',
+    orphanReason: 'no longer present on WordPress',
+    pathLabel: 'Hooks',
+    pathNoun: 'hooks directory',
+    pullDescription: 'Pull hook files (actions, filters, cron) from WordPress',
+    pushDescription: 'Push hook files (actions, filters, cron) to WordPress',
+};

package/dist/lib/put-or-create.js

@@ -1,5 +1,5 @@
 import { isNotFoundError } from './wp-client.js';
-// Update-or-create dance shared by every id-based resource (form, page, seo redirect,
+// Update-or-create dance shared by every id-based resource (form, seo redirect,
 // snippet, unlike ACF which is key-based and only ever POSTs): PUT to the known id, and only
 // fall back to POST when the site doesn't recognize that id (404), e.g. a fresh install or a
 // database reset.

package/dist/lib/readdir-tolerant.d.ts

@@ -1,5 +1,6 @@
 import { type Dirent } from 'node:fs';
 export declare function readdirTolerant(dir: string): Promise<string[]>;
 export declare function readdirTolerant(dir: string, options: {
+    recursive?: boolean;
     withFileTypes: true;
 }): Promise<Dirent[]>;

package/dist/lib/readdir-tolerant.js

@@ -1,7 +1,9 @@
 import { readdir } from 'node:fs/promises';
 export async function readdirTolerant(dir, options) {
     try {
-        return options?.withFileTypes ? await readdir(dir, { withFileTypes: true }) : await readdir(dir);
+        return options?.withFileTypes
+            ? await readdir(dir, { recursive: options.recursive, withFileTypes: true })
+            : await readdir(dir, { recursive: options?.recursive });
     }
     catch (error) {
         if (error.code === 'ENOENT')

package/dist/lib/resource-state.d.ts

@@ -0,0 +1,14 @@
+import { type ResourceDirKind } from '../utils/resource-dirs.js';
+import { type ResourceState } from './diff-state.js';
+import { type WpClient } from './wp-client.js';
+export type ResourceStateProvider = {
+    dirKind: ResourceDirKind;
+    local(dir: string, onWarn: (message: string) => void): Promise<ResourceState>;
+    remote(wp: WpClient, onWarn: (message: string) => void, dir: string): Promise<ResourceState>;
+    resource: string;
+    title: string;
+};
+export declare const RESOURCE_STATE_PROVIDERS: ResourceStateProvider[];
+export declare function getResourceStateProvider(resource: string): ResourceStateProvider;
+export declare function composerRemoteState(wp: WpClient): Promise<ResourceState>;
+export declare function composerLocalState(rootDir: string): Promise<ResourceState>;

package/dist/lib/resource-state.js

@@ -0,0 +1,361 @@
+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 { 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 { loadFiles } from './load-files.js';
+import { loadSnippets } from './load-snippets.js';
+import { isApplicative404, isNotFoundError } from './wp-client.js';
+function readJson(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('not a JSON object');
+    }
+    return parsed;
+}
+// Removes top-level keys that the server rewrites without the tracked configuration itself
+// changing (save timestamps, hit counters), so a `diff` between two independently-configured
+// environments reports real differences only. Top-level only: a nested user field that happens
+// to share a name is never touched.
+function omit(object, keys) {
+    return Object.fromEntries(Object.entries(object).filter(([key]) => !keys.includes(key)));
+}
+// ACF's export JSON carries `modified` (a unix timestamp bumped on every save in wp-admin).
+const ACF_VOLATILE_KEYS = ['modified'];
+// A WPForms form is a WP post; `modified`/`modified_gmt` move on every edit.
+const FORM_VOLATILE_KEYS = ['modified', 'modified_gmt'];
+// A RankMath redirect's `hits` is a live visit counter.
+const REDIRECT_VOLATILE_KEYS = ['hits'];
+// ---- snippets -------------------------------------------------------------------------------
+// `description` is dropped: `snippet push` overwrites it with "Imported from <path>" on every
+// push and `loadSnippets` never reads it back, so it is not part of the synced state. `id`
+// becomes the map key. `code` has its leading `<?php` stripped on both sides: `snippet pull`
+// re-adds it to PHP files for editor friendliness, WordPress stores only the body.
+function canonicalSnippet(snippet) {
+    return {
+        active: snippet.active,
+        code: stripPhpOpeningTag(snippet.code),
+        insertMethod: snippet.insertMethod,
+        location: snippet.location,
+        name: snippet.name,
+        priority: snippet.priority,
+        shortcodeAttributes: [...snippet.shortcodeAttributes],
+        tags: [...snippet.tags],
+        type: snippet.type,
+    };
+}
+const snippetProvider = {
+    dirKind: 'snippets',
+    async local(dir) {
+        const state = new Map();
+        let snippets;
+        try {
+            snippets = await loadSnippets(dir);
+        }
+        catch (error) {
+            // A directory that was never created is "nothing tracked locally", the same tolerance
+            // loadFiles/readdirTolerant already have; loadSnippets wraps the ENOENT in its own Error.
+            if (error.cause?.code === 'ENOENT')
+                return state;
+            throw error;
+        }
+        for (const snippet of snippets) {
+            const id = snippet.id === undefined ? `local:${basename(snippet.path)}` : String(snippet.id);
+            state.set(id, canonicalSnippet(snippet));
+        }
+        return state;
+    },
+    async remote(wp) {
+        const raw = await wp.get(SNIPPETS_ENDPOINT);
+        const state = new Map();
+        for (const item of raw) {
+            const snippet = normalizeSnippet(item);
+            state.set(String(snippet.id), canonicalSnippet(snippet));
+        }
+        return state;
+    },
+    resource: 'snippet',
+    title: 'Snippets',
+};
+// ---- forms -------------------------------------------------------------------------------
+// The form plugin's own JSON (WPForms today) round-trips untouched through pull/push, so
+// (minus save timestamps) the whole object is the compared value, same "deliberately loose"
+// stance as form-format.ts.
+const formProvider = {
+    dirKind: 'form',
+    async local(dir, onWarn) {
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: (raw, filePath) => ({ file: basename(filePath, '.json'), value: readJson(raw) }),
+        });
+        const state = new Map();
+        for (const { file, value } of entries) {
+            const formId = getFormId(value);
+            state.set(formId === null ? `local:${file}` : String(formId), omit(value, FORM_VOLATILE_KEYS));
+        }
+        return state;
+    },
+    async remote(wp) {
+        const raw = await wp.get(FORM_ENDPOINT);
+        const state = new Map();
+        for (const form of raw) {
+            const formId = getFormId(form);
+            if (formId !== null)
+                state.set(String(formId), omit(form, FORM_VOLATILE_KEYS));
+        }
+        return state;
+    },
+    resource: 'form',
+    title: 'Forms',
+};
+// ---- ACF --------------------------------------------------------------------------------
+// ACF's export JSON is large, deeply nested, and versioned by ACF itself; `key` is the stable
+// identity and the whole object (minus the `modified` timestamp) round-trips untouched, so it
+// is all compared. Ids are namespaced by object type (`field-groups/group_x`) since keys are
+// only unique within a type.
+const acfProvider = {
+    dirKind: 'acf',
+    async local(dir, onWarn) {
+        const state = new Map();
+        for (const type of ACF_OBJECT_TYPES) {
+            const objects = await loadFiles(join(dir, type), {
+                extension: '.json',
+                onSkip: onWarn,
+                parse: readJson,
+            });
+            for (const object of objects) {
+                const key = getAcfKey(object);
+                if (key !== null)
+                    state.set(`${type}/${key}`, omit(object, ACF_VOLATILE_KEYS));
+            }
+        }
+        return state;
+    },
+    async remote(wp) {
+        const state = new Map();
+        for (const type of ACF_OBJECT_TYPES) {
+            const raw = await wp.get(acfEndpoint(type));
+            for (const object of raw) {
+                const key = getAcfKey(object);
+                if (key !== null)
+                    state.set(`${type}/${key}`, omit(object, ACF_VOLATILE_KEYS));
+            }
+        }
+        return state;
+    },
+    resource: 'acf',
+    title: 'ACF',
+};
+// ---- PHP file directories (API routes, hooks) -----------------------------------------
+// api/ and hooks/ are both just a recursive directory of PHP files whose text is compared
+// verbatim (line diff on change), no server-side normalization to undo. Only the directory
+// kind, the endpoint and the labels differ.
+function phpFilesProvider(spec) {
+    const toState = (files) => {
+        const state = new Map();
+        for (const file of files)
+            state.set(file.filename, file.content);
+        return state;
+    };
+    return {
+        dirKind: spec.dirKind,
+        async local(dir, onWarn) {
+            return toState(await loadFiles(dir, {
+                extension: '.php',
+                onSkip: onWarn,
+                parse: (raw, filePath) => ({
+                    content: raw,
+                    filename: relative(dir, filePath).slice(0, -'.php'.length).split(sep).join('/'),
+                }),
+                recursive: true,
+            }));
+        },
+        async remote(wp) {
+            return toState(await wp.get(spec.endpoint));
+        },
+        resource: spec.resource,
+        title: spec.title,
+    };
+}
+const apiProvider = phpFilesProvider({
+    dirKind: 'api',
+    endpoint: 'loopress/v1/api-files',
+    resource: 'api',
+    title: 'API routes',
+});
+const hookProvider = phpFilesProvider({
+    dirKind: 'hooks',
+    endpoint: 'loopress/v1/hook-files',
+    resource: 'hook',
+    title: 'Hooks',
+});
+// ---- SEO --------------------------------------------------------------------------------
+function canonicalRedirect(redirect) {
+    return omit(redirect, REDIRECT_VOLATILE_KEYS);
+}
+const seoProvider = {
+    dirKind: 'seo',
+    async local(dir, onWarn) {
+        const state = new Map();
+        // The provider settings blob (Yoast / RankMath) is compared whole. If a real payload turns
+        // out to carry install-specific noise (a plugin version, a license hash), add those keys
+        // to an omit() list here, the e2e round-trip is what will surface them.
+        const settingsPath = join(dir, 'settings.json');
+        try {
+            const settings = readJson(await readFile(settingsPath, 'utf8'));
+            state.set('settings', settings);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                onWarn(`Skipping "${settingsPath}": ${error.message}`);
+            }
+        }
+        for (const postType of DEFAULT_POST_TYPES) {
+            const metaDir = join(dir, 'post-meta', postType);
+            const entries = await loadFiles(metaDir, {
+                extension: '.json',
+                onSkip: onWarn,
+                parse: (raw, filePath) => ({ file: basename(filePath, '.json'), value: readJson(raw) }),
+            });
+            for (const { file, value } of entries) {
+                const slug = typeof value.slug === 'string' && value.slug !== '' ? value.slug : `local:${file}`;
+                state.set(`post-meta/${postType}/${slug}`, value);
+            }
+        }
+        const redirects = await loadFiles(join(dir, 'redirects'), {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: readJson,
+        });
+        for (const redirect of redirects) {
+            const id = Number(redirect.id);
+            if (Number.isSafeInteger(id) && id > 0)
+                state.set(`redirects/${id}`, canonicalRedirect(redirect));
+        }
+        return state;
+    },
+    async remote(wp, onWarn) {
+        const state = new Map();
+        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);
+        }
+        // Redirects are a RankMath-only feature; on Yoast the endpoint 404s, same graceful skip
+        // as `seo pull`.
+        try {
+            const redirects = await wp.get(SEO_REDIRECTS_ENDPOINT);
+            for (const redirect of redirects) {
+                state.set(`redirects/${redirect.id}`, canonicalRedirect(redirect));
+            }
+        }
+        catch (error) {
+            if (!isNotFoundError(error))
+                throw error;
+            onWarn(`Skipping redirects: not supported by the active SEO plugin`);
+        }
+        return state;
+    },
+    resource: 'seo',
+    title: 'SEO',
+};
+// ---- 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
+// the locally tracked set, read from `dir` on the remote side too (see ResourceStateProvider's
+// docstring). `readonly` is a local policy flag with no WordPress counterpart, left out of both
+// sides so it can never itself show up as drift.
+const optionsProvider = {
+    dirKind: 'options',
+    async local(dir, onWarn) {
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse(raw) {
+                const option = parseLocalOption(raw);
+                return { autoload: option.autoload, name: option.name, value: option.value };
+            },
+        });
+        const state = new Map();
+        for (const { autoload, name, value } of entries)
+            state.set(name, { autoload, value });
+        return state;
+    },
+    async remote(wp, onWarn, dir) {
+        const tracked = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: (raw) => parseLocalOption(raw).name,
+        });
+        const state = new Map();
+        for (const name of tracked) {
+            try {
+                const option = await wp.get(optionEndpoint(name));
+                state.set(name, { autoload: option.autoload, value: option.value });
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+                // Absent on this environment (never pushed here, or deleted there): left out of the
+                // map, which reads as "removed" on this side, exactly the right signal.
+            }
+        }
+        return state;
+    },
+    resource: 'option',
+    title: 'Options',
+};
+export const RESOURCE_STATE_PROVIDERS = [
+    snippetProvider,
+    formProvider,
+    acfProvider,
+    apiProvider,
+    hookProvider,
+    seoProvider,
+    optionsProvider,
+];
+export function getResourceStateProvider(resource) {
+    const provider = RESOURCE_STATE_PROVIDERS.find((candidate) => candidate.resource === resource);
+    if (!provider)
+        throw new Error(`No resource-state provider for "${resource}"`);
+    return provider;
+}
+// ---- Composer ---------------------------------------------------------------------------
+// Composer isn't a directory of items but two files at the project root, so it sits outside
+// RESOURCE_STATE_PROVIDERS. The compared value is each file's text.
+const COMPOSER_JSON_ENDPOINT = 'loopress/v1/composer/json';
+const COMPOSER_LOCK_ENDPOINT = 'loopress/v1/composer/lock';
+export async function composerRemoteState(wp) {
+    const state = new Map();
+    const { composerJson } = await wp.get(COMPOSER_JSON_ENDPOINT);
+    state.set('composer.json', composerJson);
+    try {
+        const { composerLock } = await wp.get(COMPOSER_LOCK_ENDPOINT);
+        state.set('composer.lock', composerLock);
+    }
+    catch (error) {
+        // A site that never pushed Composer dependencies has no lock yet, the same tolerated 404
+        // as `composer pull`.
+        if (!isApplicative404(error, 'composer.lock not found'))
+            throw error;
+    }
+    return state;
+}
+export async function composerLocalState(rootDir) {
+    const state = new Map();
+    for (const file of ['composer.json', 'composer.lock']) {
+        try {
+            state.set(file, await readFile(join(rootDir, file), 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return state;
+}

package/dist/lib/validate-local.js

@@ -6,12 +6,12 @@ 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', 'pageDir', 'seoDir'];
+const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
     formDir: 'forms',
-    pageDir: 'pages',
+    hooksDir: 'hooks',
     seoDir: 'seo',
     snippetsDir: 'snippets',
 };
@@ -35,20 +35,28 @@ export async function validateLocal(cwd) {
         checked += await checkJsonDir(resolve(key), problems);
     }
     checked += await checkSnippets(resolve('snippetsDir'), problems);
-    checked += await checkApiDir(resolve('apiDir'), problems);
+    checked += await checkPhpDir(resolve('apiDir'), problems, 'API route file is empty');
+    checked += await checkPhpDir(resolve('hooksDir'), problems, 'Hook file is empty');
     return { checked, problems, valid: problems.length === 0 };
 }
-async function checkApiDir(dir, problems) {
-    const entries = await readdirTolerant(dir, { withFileTypes: true });
+// Recursive: both api/ and hooks/ files can live in a nested path-segment directory
+// (invoice-pdf/[order_id].php, content/filters.php), a non-recursive scan would silently
+// never check those.
+async function checkPhpDir(dir, problems, emptyMessage) {
+    const entries = await readdirTolerant(dir, { recursive: true, withFileTypes: true });
     let checked = 0;
     for (const entry of entries) {
         if (!entry.isFile() || !entry.name.endsWith('.php'))
             continue;
         checked += 1;
-        const filePath = join(dir, entry.name);
+        // parentPath is the entry's actual containing directory, which only equals `dir` itself
+        // for a top-level file: recursive readdir() nests entry.name to the basename alone, so
+        // join(dir, entry.name) would silently point at the wrong (top-level) path for anything
+        // one level deep or more.
+        const filePath = join(entry.parentPath, entry.name);
         const content = await readFile(filePath, 'utf8');
         if (content.trim() === '')
-            problems.push({ file: filePath, message: 'API route file is empty' });
+            problems.push({ file: filePath, message: emptyMessage });
     }
     return checked;
 }