@loopress/cli 0.31.0 → 0.32.1

package/dist/lib/validate-local.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 import { configManager } from '../config/project-config.manager.js';
 import { CPT_SPEC, declaredFileChecker, META_SPEC, PATTERN_SPEC, ROLE_SPEC, TAXONOMY_SPEC } from '../utils/declared-type-format.js';
 import { parseLocalOption } from '../utils/option-format.js';
@@ -8,6 +8,7 @@ import { RESOURCE_DIR_DEFAULTS } from '../utils/resource-dirs.js';
 import { parseType } from '../utils/snippet-format.js';
 import { readLocalTemplates } from '../utils/template-format.js';
 import { loadSnippets } from './load-snippets.js';
+import { API_FILES_RESOURCE, HOOK_FILES_RESOURCE, phpFileProblems } from './php-files-command.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, options too (a stricter shape).
@@ -58,8 +59,8 @@ export async function validateLocal(cwd) {
     checked += await checkJsonDir(resolve('roleDir'), problems, declaredFileChecker(ROLE_SPEC));
     checked += await checkPatterns(resolve('patternDir'), problems);
     checked += await checkSnippets(resolve('snippetsDir'), problems);
-    checked += await checkPhpDir(resolve('apiDir'), problems, 'API route file is empty');
-    checked += await checkPhpDir(resolve('hooksDir'), problems, 'Hook file is empty');
+    checked += await checkPhpDir(resolve('apiDir'), problems, 'API route file is empty', API_FILES_RESOURCE);
+    checked += await checkPhpDir(resolve('hooksDir'), problems, 'Hook file is empty', HOOK_FILES_RESOURCE);
     const pages = await readLocalPages(resolve('pageDir'));
     checked += pages.pages.length + pages.problems.length;
     problems.push(...pages.problems);
@@ -83,7 +84,7 @@ async function checkPatterns(dir, problems) {
 // 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) {
+async function checkPhpDir(dir, problems, emptyMessage, spec) {
     const entries = await readdirTolerant(dir, { recursive: true, withFileTypes: true });
     let checked = 0;
     for (const entry of entries) {
@@ -96,8 +97,14 @@ async function checkPhpDir(dir, problems, emptyMessage) {
         // one level deep or more.
         const filePath = join(entry.parentPath, entry.name);
         const content = await readFile(filePath, 'utf8');
-        if (content.trim() === '')
+        if (content.trim() === '') {
             problems.push({ file: filePath, message: emptyMessage });
+            continue;
+        }
+        // The same checks push runs, so a file that passes here doesn't fail there.
+        const filename = relative(dir, filePath).replaceAll(sep, '/').replace(/\.php$/, '');
+        for (const message of phpFileProblems(spec, filename, content))
+            problems.push({ file: filePath, message });
     }
     return checked;
 }

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

@@ -25,6 +25,7 @@ type RequestOptions = {
 export declare function isNotFoundError(error: unknown): boolean;
 export declare function isForbiddenError(error: unknown): boolean;
 export declare function isApplicative404(error: unknown, marker: string): boolean;
+export declare function isConflictCode(error: unknown, code: 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;

package/dist/lib/wp-client.js

@@ -116,6 +116,19 @@ export function isApplicative404(error, marker) {
         return false;
     }
 }
+// A 409 a Loopress controller tags with a `code`, for a refusal the CLI can act on (e.g.
+// `loopress_page_not_managed`, which `lps page push` offers to take over).
+export function isConflictCode(error, code) {
+    const response = error?.cause?.response;
+    if (response?.statusCode !== 409 || !response.body)
+        return false;
+    try {
+        return JSON.parse(response.body).code === code;
+    }
+    catch {
+        return false;
+    }
+}
 export function isTimeoutError(error) {
     const cause = error?.cause;
     return cause?.name === 'TimeoutError';

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

@@ -3,3 +3,8 @@ export type AcfObjectType = (typeof ACF_OBJECT_TYPES)[number];
 export declare function acfEndpoint(type: AcfObjectType): string;
 export declare function acfObjectEndpoint(type: AcfObjectType, key: string): string;
 export declare function getAcfKey(data: Record<string, unknown>): null | string;
+export declare function acfFieldChanges(before: unknown, after: unknown): {
+    added: string[];
+    changed: string[];
+    removed: string[];
+};

package/dist/utils/acf-format.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from 'node:util';
 export const ACF_OBJECT_TYPES = ['field-groups', 'post-types', 'taxonomies', 'options-pages'];
 export function acfEndpoint(type) {
     return `loopress/v1/acf/${type}`;
@@ -16,3 +17,31 @@ export function acfObjectEndpoint(type, key) {
 export function getAcfKey(data) {
     return typeof data.key === 'string' && data.key.trim() !== '' ? data.key : null;
 }
+function topLevelFields(group) {
+    const fields = group?.fields;
+    const byKey = new Map();
+    for (const field of Array.isArray(fields) ? fields : []) {
+        if (typeof field?.key === 'string')
+            byKey.set(field.key, field);
+    }
+    return byKey;
+}
+// A changed field group's top-level fields, matched by `key` and named by `name` (a repeater's
+// sub-field change shows as its parent changing). Only for the dry-run preview: the push itself
+// always sends the whole group.
+export function acfFieldChanges(before, after) {
+    const old = topLevelFields(before);
+    const next = topLevelFields(after);
+    const label = (field) => (typeof field.name === 'string' && field.name !== '' ? field.name : String(field.key));
+    const changes = { added: [], changed: [], removed: [] };
+    for (const [key, field] of next) {
+        if (!old.has(key))
+            changes.added.push(label(field));
+        else if (!isDeepStrictEqual(old.get(key), field))
+            changes.changed.push(label(field));
+    }
+    for (const [key, field] of old)
+        if (!next.has(key))
+            changes.removed.push(label(field));
+    return changes;
+}

package/dist/utils/php-top-level.d.ts

@@ -0,0 +1,2 @@
+export declare function firstTopLevelSideEffect(content: string): null | string;
+export declare function startsWithStrictTypes(content: string): boolean;

package/dist/utils/php-top-level.js

@@ -0,0 +1,153 @@
+// Port of the plugin's ClassScanner::firstTopLevelSideEffect(): the first statement at the top
+// level (brace depth 0) that would run when the file is loaded, or null when the file only
+// declares things. The server rejects such a file at push ("code outside the class"); checking
+// it here lets `lps validate` catch it first, a hand-written ABSPATH guard included (the plugin
+// adds its own). PHP has no tokenizer in Node, so this is a minimal lexer: it only needs to skip
+// comments, strings and heredocs correctly, and to see keywords, braces and ';'.
+const ALLOWED = new Set(['abstract', 'class', 'const', 'declare', 'enum', 'final', 'function', 'interface', 'namespace', 'readonly', 'trait', 'use']);
+const OPEN_TAG = /<\?php\b/i;
+// Returns a short description of the offending token, for the error message.
+export function firstTopLevelSideEffect(content) {
+    if (content.search(OPEN_TAG) !== 0)
+        return 'inline HTML before <?php';
+    const state = { atStart: true, braces: [], depth: 0, namespaceHeader: false };
+    for (const token of lex(content.slice(5))) {
+        const found = step(state, token);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+// True when the file's first statement is `declare(strict_types=1);` (PHP refuses it anywhere
+// else). A count of the text alone would also accept one that only sits in a comment.
+export function startsWithStrictTypes(content) {
+    if (content.search(OPEN_TAG) !== 0)
+        return false;
+    const texts = [];
+    for (const token of lex(content.slice(5))) {
+        texts.push(token.text.toLowerCase());
+        if (texts.length === 7)
+            break;
+    }
+    return texts.join('') === 'declare(strict_types=1);';
+}
+// Advances the brace depth and "a statement starts here" flag past one token; returns the token
+// when it starts a top-level statement that isn't a declaration.
+function step(state, token) {
+    if (token.type === 'html')
+        return inlineHtml(state, token);
+    const statementStart = state.depth === 0 && state.atStart;
+    switch (token.text) {
+        case ';': {
+            if (state.depth === 0) {
+                state.atStart = true;
+                state.namespaceHeader = false;
+            }
+            return null;
+        }
+        case '{': {
+            return openBrace(state, statementStart);
+        }
+        case '}': {
+            if (state.braces.pop() !== true)
+                state.depth = Math.max(0, state.depth - 1);
+            if (state.depth === 0)
+                state.atStart = true;
+            return null;
+        }
+        default: {
+            if (!statementStart)
+                return null;
+            state.atStart = false;
+            state.namespaceHeader = token.text.toLowerCase() === 'namespace';
+            return isDeclaration(token) ? null : token.text;
+        }
+    }
+}
+// A template inside a class or function body (`?> <p>...</p> <?php`) only runs when it is called.
+function inlineHtml(state, token) {
+    if (state.depth > 0)
+        return null;
+    state.atStart = true;
+    return token.text === '' ? null : 'inline HTML after ?>';
+}
+function openBrace(state, statementStart) {
+    if (state.namespaceHeader) {
+        state.namespaceHeader = false;
+        state.braces.push(true);
+        state.atStart = true;
+        return null;
+    }
+    // A '{' starting a statement is a bare block, its body runs at load time.
+    if (statementStart)
+        return '{';
+    state.braces.push(false);
+    state.depth += 1;
+    return null;
+}
+function isDeclaration(token) {
+    return token.type === 'attribute' || (token.type === 'word' && ALLOWED.has(token.text.toLowerCase()));
+}
+function* lex(source) {
+    let i = skipTrivia(source, 0);
+    while (i < source.length) {
+        const [token, end] = readToken(source, i);
+        yield token;
+        i = skipTrivia(source, end);
+    }
+}
+// Skips whitespace and comments (`#[` is an attribute, not a comment).
+function skipTrivia(source, start) {
+    let i = start;
+    for (;;) {
+        if (/\s/.test(source[i] ?? '')) {
+            i += 1;
+        }
+        else if (source.startsWith('//', i) || (source[i] === '#' && source[i + 1] !== '[')) {
+            // A line comment also ends at a closing tag, PHP outputs what follows it.
+            const end = source.slice(i).search(/\n|\?>/);
+            i = end === -1 ? source.length : i + end;
+        }
+        else if (source.startsWith('/*', i)) {
+            const end = source.indexOf('*/', i + 2);
+            i = end === -1 ? source.length : end + 2;
+        }
+        else {
+            return i;
+        }
+    }
+}
+function readToken(source, i) {
+    if (source.startsWith('?>', i)) {
+        // Closing tag: everything up to the next <?php is output, but for one newline PHP eats.
+        const next = source.slice(i + 2).search(OPEN_TAG);
+        const html = next === -1 ? source.slice(i + 2) : source.slice(i + 2, i + 2 + next);
+        return [{ text: html.replace(/^\r?\n/, ''), type: 'html' }, next === -1 ? source.length : i + 2 + next + 5];
+    }
+    if (source.startsWith('#[', i))
+        return [{ text: '#[', type: 'attribute' }, i + 2];
+    if (source.startsWith('<<<', i) || `'"\``.includes(source[i])) {
+        return [{ text: source[i] === '`' ? '`' : 'a string', type: 'string' }, skipString(source, i)];
+    }
+    const word = /^[\w$\\]+/.exec(source.slice(i));
+    if (word)
+        return [{ text: word[0], type: 'word' }, i + word[0].length];
+    return [{ text: source[i], type: 'punct' }, i + 1];
+}
+// Index right after the string (quoted, backtick, heredoc or nowdoc) starting at `i`.
+function skipString(source, i) {
+    if (source[i] === '<') {
+        const head = /^<<<[ \t]*(["']?)(\w+)\1\r?\n/.exec(source.slice(i));
+        if (!head)
+            return i + 3;
+        // PHP 7.3+: the closing identifier may be indented and followed by anything but a word char.
+        const bodyStart = i + head[0].length - 1;
+        const close = new RegExp(String.raw `\n[ \t]*${head[2]}\b`).exec(source.slice(bodyStart));
+        return close ? bodyStart + close.index + close[0].length : source.length;
+    }
+    const quote = source[i];
+    let j = i + 1;
+    while (j < source.length && source[j] !== quote)
+        j += source[j] === '\\' ? 2 : 1;
+    return j + 1;
+}

package/dist/utils/resource-dirs.d.ts

@@ -22,3 +22,4 @@ export declare const RESOURCE_DIR_DEFAULTS: {
 };
 export type ResourceDirKind = keyof typeof RESOURCE_DIR_DEFAULTS;
 export declare function resolveResourceDir(kind: ResourceDirKind, localConfig: LoopressLocalConfig, override?: string): string;
+export declare function projectUses(kind: ResourceDirKind, localConfig: LoopressLocalConfig): boolean;

package/dist/utils/resource-dirs.js

@@ -1,4 +1,5 @@
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 // The default subdirectory for each file-backed resource, relative to rootDir. Used whenever
 // loopress.json has no `<kind>Dir` key, which is the case for a fresh `lps init`.
 export const RESOURCE_DIR_DEFAULTS = {
@@ -54,3 +55,8 @@ export function resolveResourceDir(kind, localConfig, override) {
     const configured = localConfig[CONFIG_KEY[kind]];
     return join(rootDir, configured ?? RESOURCE_DIR_DEFAULTS[kind]);
 }
+// Whether the project uses a resource at all: its directory exists. What the aggregate `lps push`,
+// `lps pull` and `lps diff` go by for a resource backed by a plugin the site may not have.
+export function projectUses(kind, localConfig) {
+    return existsSync(resolve(resolveResourceDir(kind, localConfig)));
+}

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

@@ -15,6 +15,7 @@ export type Part = {
 };
 export type ChildTheme = {
     active: boolean;
+    css?: Record<string, string>;
     customized: string[];
     exists: boolean;
     parent: string;

package/dist/utils/theme-styles-format.d.ts

@@ -12,6 +12,8 @@ export type WpThemeSupportInfo = {
 };
 export declare function isBlockTheme(theme: Pick<WpThemeSupportInfo, 'theme_supports'>): boolean;
 export declare function getUserGlobalStylesId(theme: Pick<WpThemeSupportInfo, '_links'>): null | number;
+export declare function globalStylesFiles(dir: string): Promise<string[]>;
+export declare function globalStylesSkipNote(wp: WpClient, dir: string, action: 'pull' | 'push'): Promise<string | undefined>;
 export declare function getActiveThemeGlobalStyles(wp: WpClient): Promise<{
     id: number;
     stylesheet: string;

package/dist/utils/theme-styles-format.js

@@ -1,3 +1,5 @@
+import { resolve } from 'node:path';
+import { readdirTolerant } from '../lib/readdir-tolerant.js';
 // Global Styles are the user's customizations from the Site Editor's "Styles" screen (colors,
 // typography, spacing), stored by WordPress core in a `wp_global_styles` post, one per theme.
 // This is separate from the theme's own theme.json file, which lives in the theme's repo and is
@@ -30,14 +32,40 @@ export function getUserGlobalStylesId(theme) {
     const match = /\/wp\/v2\/global-styles\/(\d+)/.exec(href);
     return match ? Number(match[1]) : null;
 }
-// Resolves the active theme's stylesheet slug and the id of its editable Global Styles post in
-// one call, failing clearly (rather than with a raw REST error later) when the active theme
-// isn't a block theme: classic themes have no Styles screen and no `wp_global_styles` post at all.
-export async function getActiveThemeGlobalStyles(wp) {
+async function getActiveTheme(wp) {
     const themes = await wp.get('wp/v2/themes');
     const active = themes.find((theme) => theme.status === 'active');
     if (!active)
         throw new Error('Could not determine the active theme on WordPress.');
+    return active;
+}
+// The project's Global Styles files, one per theme it was pulled from. None: the project doesn't
+// track them.
+export async function globalStylesFiles(dir) {
+    return (await readdirTolerant(resolve(dir))).filter((file) => file.endsWith(THEME_STYLES_FILE_SUFFIX));
+}
+// Why the aggregate `lps push` / `lps pull` leave Global Styles out of this run, or undefined to
+// include them. Only a project that tracks them (a `*-global-styles.json` file in `dir`) on a
+// site whose active theme is a block theme qualifies: unlike `lps theme style push`, a classic
+// theme is no error there, the rest of the run must go on. A push also needs the active theme's
+// own file, there is nothing to send otherwise.
+export async function globalStylesSkipNote(wp, dir, action) {
+    const files = await globalStylesFiles(dir);
+    if (files.length === 0)
+        return 'not configured, skipped';
+    const active = await getActiveTheme(wp);
+    if (!isBlockTheme(active))
+        return `the active theme "${active.stylesheet}" is a classic theme, skipped`;
+    if (action === 'push' && !files.includes(themeStylesFileName(active.stylesheet))) {
+        return `no file for the active theme "${active.stylesheet}", skipped`;
+    }
+    return undefined;
+}
+// Resolves the active theme's stylesheet slug and the id of its editable Global Styles post in
+// one call, failing clearly (rather than with a raw REST error later) when the active theme
+// isn't a block theme: classic themes have no Styles screen and no `wp_global_styles` post at all.
+export async function getActiveThemeGlobalStyles(wp) {
+    const active = await getActiveTheme(wp);
     if (!isBlockTheme(active)) {
         throw new Error(`Global Styles sync only supports block themes (Full Site Editing). The active theme "${active.stylesheet}" is a classic theme.`);
     }