@loopress/cli 0.30.0 → 0.32.0

package/dist/lib/push-command.d.ts

@@ -1,18 +1,36 @@
 import { LoopressCommand } from './base.js';
 import { type ResourceState } from './diff-state.js';
 import { type ResourceStateProvider } from './resource-state.js';
+export type PushChange = {
+    id: string;
+    status: 'changed' | 'created' | 'removed' | 'unchanged';
+};
+export declare function pushChanges(local: ResourceState, remote: ResourceState, options?: {
+    mirror?: boolean;
+    writes?: (id: string) => boolean;
+}): PushChange[];
+export declare function logChanges(log: (message: string) => void, changes: Array<{
+    id: string;
+    status: string;
+}>, prefix?: string): void;
 export declare abstract class PushCommand extends LoopressCommand {
     static baseFlags: {
+        overwrite: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'production-confirmed': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     protected failedCount: number;
+    protected previewChanges: PushChange[];
+    protected previewStates?: {
+        local: ResourceState;
+        remote: ResourceState;
+    };
     private refusedByGuard;
-    protected captureBeforePushState(provider: ResourceStateProvider, dir: string): Promise<ResourceState | undefined>;
+    protected captureBeforePushState(provider: ResourceStateProvider, dir: string, writes?: (id: string) => boolean): Promise<ResourceState | undefined>;
     catch(err: Error): Promise<void>;
     protected guardProductionPush(): Promise<void>;
     init(): Promise<void>;
-    protected previewRemote(provider: ResourceStateProvider, dir: string): Promise<void>;
+    protected previewRemote(provider: ResourceStateProvider, dir: string): Promise<ResourceState>;
     protected recordDeployment(status: 'failure' | 'success'): Promise<void>;
     protected recordSuccess(): Promise<void>;
     protected reportPushToSite(): Promise<void>;
@@ -23,4 +41,5 @@ export declare abstract class PushCommand extends LoopressCommand {
         output: string;
     }) => Promise<void>): Promise<void>;
     protected writeAfterPushSnapshot(provider: ResourceStateProvider, dir: string, beforeState: ResourceState | undefined): Promise<void>;
+    private guardOutsideEdits;
 }

package/dist/lib/push-command.js

@@ -1,21 +1,51 @@
+import { confirm } from '@inquirer/prompts';
 import { Flags } from '@oclif/core';
 import got from 'got';
 import { Listr } from 'listr2';
 import { resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { authManager } from '../config/auth.manager.js';
 import { API_URL } from './api-client.js';
 import { LoopressCommand } from './base.js';
 import { guardProductionPush } from './guard-production-push.js';
-import { writeSnapshot } from './snapshot-store.js';
+import { isInteractive } from './interactive.js';
+import { readSnapshot, recordToState, writeSnapshot } from './snapshot-store.js';
 import { withoutSpinner, withSpinner } from './spinner.js';
+export function pushChanges(local, remote, options = {}) {
+    const changes = [...local.keys()]
+        .filter((id) => options.writes?.(id) ?? true)
+        .map((id) => {
+        if (!remote.has(id))
+            return { id, status: 'created' };
+        return { id, status: isDeepStrictEqual(local.get(id), remote.get(id)) ? 'unchanged' : 'changed' };
+    });
+    if (options.mirror) {
+        for (const id of remote.keys())
+            if (!local.has(id))
+                changes.push({ id, status: 'removed' });
+    }
+    return changes.toSorted((a, b) => a.id.localeCompare(b.id));
+}
+export function logChanges(log, changes, prefix = '') {
+    for (const change of changes)
+        log(`[dry-run] ${change.status}: ${prefix}${change.id}`);
+}
 export class PushCommand extends LoopressCommand {
     // Passed by an aggregate command (`lps theme push`) that already confirmed production once,
     // so its steps skip that prompt while still asking their own confirmations (uninstalls).
     static baseFlags = {
         ...LoopressCommand.baseFlags,
+        overwrite: Flags.boolean({
+            description: 'Push even over changes made on the site outside Loopress since your last push. Pages: also take over a same-slug page Loopress did not create',
+        }),
         'production-confirmed': Flags.boolean({ hidden: true }),
     };
     failedCount = 0;
+    // A dry run's per-item preview, set by captureBeforePushState: what the push would create,
+    // change or leave as it is on the site.
+    previewChanges = [];
+    // Both sides those statuses were computed from, for a push that details a changed item.
+    previewStates;
     // Refusals of the production guard never reach the site, so they must not pollute the
     // deployment history with failure records.
     refusedByGuard = false;
@@ -25,14 +55,31 @@ export class PushCommand extends LoopressCommand {
     // interrupt the push flow" stance recordDeployment takes; `undefined` tells
     // `writeAfterPushSnapshot` there is no restore point to complete.
     //
-    // On a dry run, the same read is the preview's check against the site (see previewRemote).
-    async captureBeforePushState(provider, dir) {
+    // On a dry run, the same read is the preview's check against the site (see previewRemote), and
+    // the reference for its per-item statuses (`previewChanges`).
+    //
+    // `writes` narrows the outside-edit check to the ids this push actually writes, for a push that
+    // skips some local items (`lps page push <slug>`, readonly options, `lps acf push --type`).
+    async captureBeforePushState(provider, dir, writes) {
         if (this.dryRun) {
-            await this.previewRemote(provider, dir);
+            const remote = await this.previewRemote(provider, dir);
+            await this.guardOutsideEdits(provider, dir, remote, writes);
+            try {
+                const local = await provider.local(dir, () => { });
+                this.previewStates = { local, remote };
+                this.previewChanges = pushChanges(local, remote, { writes });
+            }
+            catch (error) {
+                // The push reports the unreadable files itself, but an empty `changes` must not read as
+                // "nothing changes".
+                this.warn(`Could not list what this push would change: ${error.message}`);
+            }
+            logChanges((message) => { this.log(message); }, this.previewChanges);
             return undefined;
         }
+        let remote;
         try {
-            return await provider.remote(this.wp, (message) => {
+            remote = await provider.remote(this.wp, (message) => {
                 this.warn(message);
             }, dir);
         }
@@ -40,6 +87,8 @@ export class PushCommand extends LoopressCommand {
             this.warn(`Could not read remote state for a rollback snapshot: ${error.message}`);
             return undefined;
         }
+        await this.guardOutsideEdits(provider, dir, remote, writes);
+        return remote;
     }
     async catch(err) {
         if (!this.dryRun && !this.refusedByGuard && this.siteConfig) {
@@ -68,7 +117,7 @@ export class PushCommand extends LoopressCommand {
     // pre-apply check built on it, see what the real push will hit.
     async previewRemote(provider, dir) {
         try {
-            await provider.remote(this.wp, () => { }, dir);
+            return await provider.remote(this.wp, () => { }, dir);
         }
         catch (error) {
             this.error(`The site would refuse this push: ${error.message}`);
@@ -165,4 +214,54 @@ export class PushCommand extends LoopressCommand {
             this.warn(`Could not save a rollback snapshot after this push: ${error.message}`);
         }
     }
+    // Refuses to silently overwrite a change made on the site outside Loopress (wp-admin, another
+    // tool) since this machine's last push. Flags an id only when both hold:
+    // - the site no longer matches what that push left (the latest snapshot's `afterState`, the
+    //   same reference rollback's drift check uses), and
+    // - this push would write a different value over it (local differs from the site), so a
+    //   `pull` that already brought the change into the local files is no reason to stop.
+    // Only ids present locally count: a push is additive, it never touches a site-only id. And
+    // only ids the site still has with readable content: pushing over a deletion (`lps <resource>
+    // rm`, or wp-admin) loses nothing, and a file the site lists without its content (too large
+    // to send) can't be compared, so it would otherwise block every push.
+    // Ceiling: snapshots live in git-ignored `.loopress/`, so only the machine that pushed last
+    // is protected; a record kept on the site would cover teammates and CI.
+    async guardOutsideEdits(provider, dir, remote, writes) {
+        if (this.overwrite)
+            return;
+        let expected;
+        let local;
+        let pushedAt;
+        try {
+            const snapshot = await readSnapshot(resolve(process.cwd(), this.rootDir), provider.resource, this.siteConfig.name);
+            expected = recordToState(snapshot.afterState);
+            pushedAt = snapshot.createdAt;
+            local = await provider.local(dir, () => { });
+        }
+        catch {
+            // No earlier push from this machine, or unreadable local files the push reports itself.
+            return;
+        }
+        const overwritten = [...local.keys()].filter((id) => (writes?.(id) ?? true) &&
+            remote.get(id) !== undefined &&
+            !sameEntry(remote, expected, id) &&
+            !sameEntry(local, remote, id));
+        if (overwritten.length === 0)
+            return;
+        const message = `Changed on ${this.siteConfig.url} outside Loopress since your last push (${pushedAt}), this push would overwrite: ${overwritten.join(', ')}. ` +
+            `Review with \`lps diff --only ${provider.resource}\`, bring the site's version into your files, or pass --overwrite.`;
+        // A dry run only previews: say what the real push would stop on.
+        if (this.dryRun) {
+            this.warn(message);
+            return;
+        }
+        if (!isInteractive())
+            this.error(message);
+        this.warn(message);
+        if (!(await confirm({ default: false, message: 'Overwrite those changes?' })))
+            this.error('Aborted.');
+    }
+}
+function sameEntry(left, right, id) {
+    return left.has(id) === right.has(id) && isDeepStrictEqual(left.get(id), right.get(id));
 }

package/dist/lib/resource-state.js

@@ -31,14 +31,14 @@ 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'];
 // ---- 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.
+// `description` is dropped: a sidecar without one gets "Imported from <path>" on push, so
+// comparing it would flag every such snippet as drifted. `id` becomes the map key. A PHP
+// snippet's `code` has its leading `<?php` stripped on both sides: `snippet pull` re-adds it
+// for editor friendliness, WordPress stores only the body. Other types keep it, it's content.
 function canonicalSnippet(snippet) {
     return {
         active: snippet.active,
-        code: stripPhpOpeningTag(snippet.code),
+        code: snippet.type === 'php' ? stripPhpOpeningTag(snippet.code) : snippet.code,
         insertMethod: snippet.insertMethod,
         location: snippet.location,
         name: snippet.name,

package/dist/lib/rollback-command.js

@@ -126,8 +126,15 @@ export function resourceRollbackCommand(resource, options) {
                 // commands/snippet/push.ts's `static args`), not a --path flag. --env/--yes: the
                 // production guard and the drift confirmation above already covered what the delegated
                 // push's own guard would ask again, same reasoning as the top-level `lps push`
-                // delegating to each resource's push command in commands/push.ts.
-                await this.config.runCommand(`${command.replaceAll(' ', ':')}:push`, [tmpDir, '--env', this.siteConfig.name, '--yes']);
+                // delegating to each resource's push command in commands/push.ts. --overwrite: the drift
+                // check above is the same question as the push's outside-edit check, already answered.
+                await this.config.runCommand(`${command.replaceAll(' ', ':')}:push`, [
+                    tmpDir,
+                    '--env',
+                    this.siteConfig.name,
+                    '--yes',
+                    '--overwrite',
+                ]);
             }
             finally {
                 // A cleanup failure here must never hide a real error from the push above: warn about

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;
 }
@@ -178,12 +185,18 @@ function checkLoopressJson(localConfig, problems) {
     if (plugins === undefined)
         return;
     if (typeof plugins !== 'object' || plugins === null || Array.isArray(plugins)) {
-        problems.push({ file: 'loopress.json', message: '"plugins" must be an object of slug -> version string' });
+        problems.push({ file: 'loopress.json', message: '"plugins" must be an object of slug -> version string or {version, active}' });
         return;
     }
     for (const [slug, version] of Object.entries(plugins)) {
-        if (typeof version !== 'string')
-            problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a string` });
+        // The object form is what `plugin pull` writes for a plugin installed but inactive (see PluginPin).
+        const isPin = typeof version === 'string' ||
+            (typeof version === 'object' &&
+                version !== null &&
+                typeof version.version === 'string' &&
+                ['boolean', 'undefined'].includes(typeof version.active));
+        if (!isPin)
+            problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a version string or {version, active}` });
     }
 }
 async function checkSnippets(dir, problems) {

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';
@@ -159,8 +172,21 @@ export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     if (err.name === 'TimeoutError') {
         return `Request timed out after ${timeoutMs / 1000}s on ${url}. Is the site reachable?`;
     }
-    return `Request to ${url} failed: ${err.message ?? String(error)}`;
+    const reason = err.code ? NETWORK_ERROR_HINTS[err.code] : undefined;
+    // The site, not the endpoint: every resource fails the same way when the site is down, so
+    // `lps diff` can print it once (see DiffCommand.report).
+    if (reason)
+        return `Could not reach ${new URL(url).origin}: ${reason}. Run \`lps doctor\` to check the environment.`;
+    // Node leaves `message` empty on some network errors (an AggregateError over IPv4 + IPv6):
+    // fall back to the error code so the reason is never blank.
+    return `Request to ${url} failed: ${err.message?.length ? err.message : (err.code ?? String(error))}`;
 }
+const NETWORK_ERROR_HINTS = {
+    ECONNREFUSED: 'connection refused, the site may be down',
+    ECONNRESET: 'connection reset by the server',
+    ENOTFOUND: 'host not found, check the URL',
+    ETIMEDOUT: 'connection timed out',
+};
 function extractLoopressError(body) {
     if (!body)
         return undefined;

package/dist/types/snippet.d.ts

@@ -2,6 +2,7 @@ import { type SnippetInsertMethod, type SnippetLocation, type SnippetType } from
 export type Snippet = {
     active: boolean;
     code: string;
+    description?: string;
     id?: number;
     insertMethod: SnippetInsertMethod;
     location: SnippetLocation;

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,148 @@
+// 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') {
+        state.atStart = true;
+        return token.text === '' ? null : 'inline HTML after ?>';
+    }
+    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;
+        }
+    }
+}
+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;