@loopress/cli 0.23.0 → 0.24.1

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/sentry.d.ts

@@ -1,3 +1,4 @@
+import type { ErrorEvent } from '@sentry/node';
 export declare const SENTRY_DSN = "https://a08dd56bfffc2a45d5b8f665e4cb8b7d@o4511586904309760.ingest.de.sentry.io/4511673275973712";
 export declare function isTelemetryDisabled(): boolean;
 export declare function resolveEnvironment(): string;
@@ -6,3 +7,5 @@ export declare function runtimeContext(): {
     os: string;
 };
 export declare function redactArgv(argv: string[]): string[];
+export declare function scrubErrorMessage(value: string): string;
+export declare function scrubEvent(event: ErrorEvent): ErrorEvent;

package/dist/lib/sentry.js

@@ -31,3 +31,33 @@ export function redactArgv(argv) {
         return eqIndex === -1 ? arg : arg.slice(0, eqIndex);
     });
 }
+// The site origin in front of a `/wp-json/` REST path: collapse it but keep the path, which is
+// Loopress's own API surface (identical on every site, no user data) and useful for triage.
+const SITE_PREFIX = /\bhttps?:\/\/[^\s"'<>)]*?\/wp-json\//gi;
+// Any other absolute URL (bare site root, a package URL on the summary line): blank it whole.
+const ANY_URL = /\bhttps?:\/\/[^\s"'<>)]+/gi;
+// A WordPress request failure (`formatWpError`) puts the site URL on the first line and, for a
+// 4xx/5xx, appends the server's raw response body after a newline: a Composer trace, a WP fatal,
+// sometimes absolute server paths, package URLs or a connection string. None of that should
+// leave the user's machine. Keep the first line (the "which endpoint, which status" summary)
+// with the site host blanked, and drop everything after it. The terminal still prints the
+// full, unmodified message.
+export function scrubErrorMessage(value) {
+    const firstLine = value.split('\n', 1)[0] ?? '';
+    return firstLine.replaceAll(SITE_PREFIX, '<site>/wp-json/').replaceAll(ANY_URL, '<site>').slice(0, 300);
+}
+// Sentry `beforeSend`: runs on every event before it is sent. Scrubs the exception message(s)
+// (including chained `cause` errors, which the linkedErrors integration copies in) and drops
+// any request context. `extra.argv` is already redacted upstream by `redactArgv`.
+export function scrubEvent(event) {
+    if (typeof event.message === 'string') {
+        event.message = scrubErrorMessage(event.message);
+    }
+    for (const exception of event.exception?.values ?? []) {
+        if (typeof exception.value === 'string') {
+            exception.value = scrubErrorMessage(exception.value);
+        }
+    }
+    delete event.request;
+    return event;
+}

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;
 }

package/dist/lib/wp-authorize-flow.d.ts

@@ -18,5 +18,9 @@ export type AuthorizeResult = {
  *   5. The API callback returns an HTML page that POSTs a form with the
  *      Application Password to the local callback server.
  *   6. The local server extracts the credentials and resolves the promise.
+ *
+ * The `state` value is threaded through `callbackUrl` (the relay copies it verbatim into the
+ * form's POST target), so it comes back as a query param on the credential POST and
+ * `waitForLocalCallback` can match it before this handler runs.
  */
 export declare function authorizeWithBrowser(siteUrl: string, log: (message: string) => void): Promise<AuthorizeResult>;

package/dist/lib/wp-authorize-flow.js

@@ -15,13 +15,18 @@ import { renderResultPage, waitForLocalCallback } from './local-callback-server.
  *   5. The API callback returns an HTML page that POSTs a form with the
  *      Application Password to the local callback server.
  *   6. The local server extracts the credentials and resolves the promise.
+ *
+ * The `state` value is threaded through `callbackUrl` (the relay copies it verbatim into the
+ * form's POST target), so it comes back as a query param on the credential POST and
+ * `waitForLocalCallback` can match it before this handler runs.
  */
 export async function authorizeWithBrowser(siteUrl, log) {
     return waitForLocalCallback({
-        buildUrl(callbackBaseUrl) {
+        allowedOrigins: ['https://api.loopress.dev'],
+        buildUrl(callbackBaseUrl, state) {
             const relayUrl = 'https://api.loopress.dev/auth/wp-authorize';
             const params = new URLSearchParams({
-                callbackUrl: callbackBaseUrl,
+                callbackUrl: `${callbackBaseUrl}?state=${state}`,
                 wpUrl: siteUrl,
             });
             return `${relayUrl}?${params}`;
@@ -31,12 +36,9 @@ export async function authorizeWithBrowser(siteUrl, log) {
                 rejectWithPage(REJECTED_PAGE, new Error('Authorization rejected in WordPress.'));
                 return;
             }
-            // `||`, not `??`: an empty-string field counts as absent here, same as the `!password`
-            // check below, so falls through to the query-param fallback instead of stopping at "".
-            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-            const password = body.password || url.searchParams.get('password') || '';
-            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-            const userLogin = body.user_login || url.searchParams.get('user_login') || '';
+            // Credentials come from the relay's form POST only. Reading them from the query string
+            // would let them land in shell history, proxy logs and the browser address bar (F24).
+            const { password, user_login: userLogin } = body;
             if (!password || !userLogin) {
                 respondBadRequest('Missing password or user_login');
                 return;

package/dist/lib/wp-client.d.ts

@@ -9,6 +9,9 @@ export declare class WpClient {
     constructor(siteUrl: string, token: string);
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
+    getAll<T>(path: string, options?: RequestOptions & {
+        perPage?: number;
+    }): Promise<T[]>;
     post<T = unknown>(path: string, json?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
     put<T = unknown>(path: string, json?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
     private request;
@@ -17,6 +20,8 @@ type RequestOptions = {
     timeoutMs?: number;
 };
 export declare function isNotFoundError(error: unknown): boolean;
+export declare function isApplicative404(error: unknown, marker: string): boolean;
 export declare function isTimeoutError(error: unknown): boolean;
+export declare function isInvalidPageNumber(error: unknown): boolean;
 export declare function formatWpError(error: unknown, url: string, timeoutMs?: number): string;
 export {};

package/dist/lib/wp-client.js

@@ -22,6 +22,32 @@ export class WpClient {
     async get(path, options) {
         return this.request('get', path, undefined, options);
     }
+    // Fetches every page of a paginated WP REST collection by walking `?page=N`, stopping on the
+    // first short page or on WordPress core's 400 "rest_post_invalid_page_number" past the last
+    // one. `path` may already carry query params. Use for `wp/v2/*` list endpoints, which cap at
+    // 100 items per request.
+    async getAll(path, options) {
+        const perPage = options?.perPage ?? 100;
+        const separator = path.includes('?') ? '&' : '?';
+        const all = [];
+        for (let page = 1;; page += 1) {
+            let batch;
+            try {
+                batch = await this.get(`${path}${separator}per_page=${perPage}&page=${page}`, options);
+            }
+            catch (error) {
+                if (isInvalidPageNumber(error))
+                    break;
+                throw error;
+            }
+            if (!Array.isArray(batch) || batch.length === 0)
+                break;
+            all.push(...batch);
+            if (batch.length < perPage)
+                break;
+        }
+        return all;
+    }
     async post(path, json, options) {
         return this.request('post', path, json, options);
     }
@@ -43,10 +69,40 @@ export function isNotFoundError(error) {
     const cause = error?.cause;
     return cause?.response?.statusCode === 404;
 }
+// A 404 a Loopress controller raises on purpose, identified by its JSON body's `error` field
+// (e.g. `{"error": "composer.lock not found"}` from ComposerController). Narrower than
+// isNotFoundError: a bare 404 also covers the route being absent because the plugin isn't
+// installed or predates the feature, which callers must still surface normally.
+export function isApplicative404(error, marker) {
+    if (!isNotFoundError(error))
+        return false;
+    const body = error.cause?.response?.body;
+    if (!body)
+        return false;
+    try {
+        return JSON.parse(body).error === marker;
+    }
+    catch {
+        return false;
+    }
+}
 export function isTimeoutError(error) {
     const cause = error?.cause;
     return cause?.name === 'TimeoutError';
 }
+// WordPress core answers 400 with this `code` when `?page=N` is past the last page of a
+// collection, which is how `WpClient.getAll` knows it has walked them all.
+export function isInvalidPageNumber(error) {
+    const body = error.cause?.response?.body;
+    if (!body)
+        return false;
+    try {
+        return JSON.parse(body).code === 'rest_post_invalid_page_number';
+    }
+    catch {
+        return false;
+    }
+}
 export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     const err = error;
     const status = err.response?.statusCode;

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

@@ -23,18 +23,22 @@ export interface LoopressProjectConfiguration {
      * Directory where forms (WPForms today) are read from and written to, relative to rootDir.
      */
     formDir?: string;
-    /**
-     * Directory where WordPress pages are read from and written to, relative to rootDir.
-     */
-    pageDir?: string;
     /**
      * Directory where custom API route files are read from and written to, relative to rootDir.
      */
     apiDir?: string;
+    /**
+     * Directory where hook files (WordPress actions, filters, and scheduled tasks) are read from and written to, relative to rootDir.
+     */
+    hooksDir?: string;
     /**
      * Directory where single-page app bundles are read from and written to, relative to rootDir. Each subdirectory is one app: a loopress.app.json plus a built dist/ folder.
      */
     appsDir?: string;
+    /**
+     * Directory where explicitly tracked WordPress options (wp_options rows) are read from and written to, relative to rootDir. Only options added via `lps option add` live here, this is never the whole options table.
+     */
+    optionsDir?: string;
     /**
      * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
      */

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

@@ -0,0 +1,31 @@
+export declare const OPTIONS_ENDPOINT = "loopress/v1/options";
+export declare function optionEndpoint(name: string): string;
+export declare const RESERVED_OPTION_NAMES: readonly ["active_plugins", "stylesheet", "template"];
+export declare const READONLY_BY_DEFAULT_OPTION_NAMES: readonly ["siteurl", "home", "db_version", "initial_db_version", "cron", "rewrite_rules", "WPLANG", "default_role", "users_can_register", "uninstall_plugins", "mailserver_url", "mailserver_login", "mailserver_pass", "mailserver_port"];
+export type LocalOption = {
+    autoload: string;
+    name: string;
+    readonly?: boolean;
+    value: unknown;
+};
+export type RemoteOption = {
+    autoload: string;
+    name: string;
+    value: unknown;
+};
+export type ListedOption = {
+    autoload: string;
+    confirmed: boolean;
+    core: boolean;
+    guess: null | string;
+    name: string;
+    pluginName: null | string;
+};
+export declare function isReservedOptionName(name: string): boolean;
+export declare function defaultReadonlyFor(name: string): boolean;
+export declare function optionFileName(name: string): string;
+export declare function partitionByReadonly(tracked: LocalOption[]): {
+    skipped: LocalOption[];
+    writable: LocalOption[];
+};
+export declare function parseLocalOption(raw: string): LocalOption;