@loopress/cli 0.22.0 → 0.24.0

package/dist/lib/diff-command.js

@@ -0,0 +1,180 @@
+import { Args, Flags, ux } from '@oclif/core';
+import { resolve } from 'node:path';
+import { configManager } from '../config/project-config.manager.js';
+import { resolveResourceDir } from '../utils/resource-dirs.js';
+import { LoopressCommand } from './base.js';
+import { compareStates, isEmptyDiff } from './diff-state.js';
+import { composerLocalState, composerRemoteState, getResourceStateProvider } from './resource-state.js';
+import { WpClient } from './wp-client.js';
+const c = ux.colorize;
+// Shared machinery for `lps diff` and the per-resource `lps <resource> diff` commands: the
+// `--against` flag, resolving the two sides, turning a provider into a comparison target, and
+// running + rendering the comparison with a CI-friendly exit code.
+export class DiffCommand extends LoopressCommand {
+    // Spread into each concrete command's `static flags`, same pattern as PushCommand.dryRunFlag.
+    static againstFlag = {
+        against: Flags.string({
+            description: 'Compare the primary environment against this second environment instead of against local files',
+        }),
+    };
+    composerTarget(sides) {
+        // resolve(), not join(): an absolute `rootDir` in loopress.json must stay absolute rather
+        // than being prefixed with the cwd, so Composer is read from the same place as the
+        // file-backed resources.
+        const localRoot = resolve(process.cwd(), this.rootDir);
+        return {
+            left: async () => composerRemoteState(this.wp),
+            resource: 'composer',
+            right: sides.againstWp ? async () => composerRemoteState(sides.againstWp) : async () => composerLocalState(localRoot),
+            title: 'Composer',
+        };
+    }
+    // Turns a directory-backed provider into a target; `dirOverride` is the optional `[PATH]`
+    // arg the per-resource commands accept.
+    providerTarget(provider, sides, dirOverride) {
+        if (dirOverride !== undefined && sides.againstWp) {
+            this.error('A [PATH] argument cannot be combined with --against: --against compares two environments, not local files.');
+        }
+        const dir = resolveResourceDir(provider.dirKind, this.localConfig, dirOverride);
+        return {
+            left: async () => provider.remote(this.wp, sides.warn, dir),
+            resource: provider.resource,
+            right: sides.againstWp ? async () => provider.remote(sides.againstWp, sides.warn, dir) : async () => provider.local(dir, sides.warn),
+            title: provider.title,
+        };
+    }
+    // Runs every target (concurrently), prints a git-style section per resource in target order,
+    // a tally, and the verdict, then returns the structured result. Exit code: 1 on drift, 2
+    // when a resource could not be compared (inconclusive), so the command doubles as a CI gate.
+    async report(targets, sides) {
+        this.out(`Comparing ${c('bold', sides.leftLabel)} ${c('dim', '→')} ${c('bold', sides.rightLabel)}\n`);
+        const results = await Promise.all(targets.map(async (target) => this.computeResource(target, sides)));
+        const resources = {};
+        let drift = false;
+        let failed = false;
+        let compared = 0;
+        let added = 0;
+        let removed = 0;
+        let changed = 0;
+        for (const result of results) {
+            resources[result.resource] = result.json;
+            if (result.json.error !== undefined) {
+                failed = true;
+                const errorLabel = c('red', `error: ${result.json.error}`);
+                this.out(`${c('bold', result.title)}  ${errorLabel}`);
+                continue;
+            }
+            compared += 1;
+            added += result.json.added.length;
+            removed += result.json.removed.length;
+            changed += result.json.changed.length;
+            if (result.stateDiff)
+                this.renderSection(result.title, result.stateDiff);
+            if (result.drift)
+                drift = true;
+        }
+        this.out(`\n${compared} compared: ${changed} changed, ${added} added, ${removed} removed`);
+        if (failed)
+            this.out(c('red', 'Some resources could not be compared; this run is inconclusive.'));
+        else
+            this.out(drift ? c('yellow', 'Drift detected.') : c('green', 'Everything is in sync.'));
+        if (failed)
+            process.exitCode = 2;
+        else if (drift)
+            process.exitCode = 1;
+        return { drift, left: sides.leftLabel, resources, right: sides.rightLabel };
+    }
+    resolveSides(against) {
+        if (against === this.siteConfig.name) {
+            this.error('--against must be a different environment from the one being compared.');
+        }
+        return {
+            againstWp: against ? this.wpForEnvironment(against) : undefined,
+            leftLabel: this.siteConfig.name,
+            rightLabel: against ?? 'local',
+            warn: (message) => {
+                this.warn(message);
+            },
+        };
+    }
+    // Fetches and compares one target. No output (so targets can run concurrently); `report`
+    // renders `stateDiff` afterwards in a fixed order.
+    async computeResource(target, sides) {
+        try {
+            const [leftState, rightState] = await Promise.all([target.left(), target.right()]);
+            const stateDiff = compareStates(leftState, rightState, { left: sides.leftLabel, right: sides.rightLabel });
+            return {
+                drift: !isEmptyDiff(stateDiff),
+                json: { added: stateDiff.added, changed: stateDiff.changed, removed: stateDiff.removed },
+                resource: target.resource,
+                stateDiff,
+                title: target.title,
+            };
+        }
+        catch (error) {
+            const { message } = error;
+            return { drift: false, json: { added: [], changed: [], error: message, removed: [] }, resource: target.resource, title: target.title };
+        }
+    }
+    out(message) {
+        if (!this.jsonEnabled())
+            this.log(message);
+    }
+    renderSection(title, stateDiff) {
+        if (isEmptyDiff(stateDiff)) {
+            this.out(`${c('bold', title)}  ${c('dim', 'in sync')}`);
+            return;
+        }
+        this.out(c('bold', title));
+        for (const id of stateDiff.added)
+            this.out(c('green', `  + ${id}`));
+        for (const id of stateDiff.removed)
+            this.out(c('red', `  - ${id}`));
+        for (const change of stateDiff.changed) {
+            this.out(c('yellow', `  ~ ${change.id}`));
+            this.out(indentPatch(change.patch));
+        }
+    }
+    wpForEnvironment(envName) {
+        const env = configManager.getEnvironment(this.projectId, envName);
+        if (!env) {
+            this.error(`Environment "${envName}" not found in this project.`);
+        }
+        if (!env.token) {
+            this.error(`No credentials configured for "${envName}". Run \`lps project config\` to add them.`);
+        }
+        return new WpClient(env.url, env.token);
+    }
+}
+// Builds the `lps <resource> diff` command class for one directory-backed resource. They differ
+// only in wording and which provider they target, so the whole body lives here.
+export function resourceDiffCommand(resource, options) {
+    class ResourceDiff extends DiffCommand {
+        static args = {
+            path: Args.string({ description: `Path to ${options.pathNoun} (overrides project config)` }),
+        };
+        static description = options.description;
+        static enableJsonFlag = true;
+        static examples = [
+            `$ lps ${resource} diff`,
+            `$ lps ${resource} diff --env staging`,
+            `$ lps ${resource} diff --env staging --against production`,
+        ];
+        static flags = { ...DiffCommand.againstFlag };
+        async run() {
+            const { args, flags } = await this.parse(ResourceDiff);
+            const sides = this.resolveSides(flags.against);
+            return this.report([this.providerTarget(getResourceStateProvider(resource), sides, args.path)], sides);
+        }
+    }
+    return ResourceDiff;
+}
+// Indents an already-formatted change block (a per-field list or a header-less unified diff)
+// so it sits visually under the `~ id` line.
+function indentPatch(patch) {
+    return patch
+        .split('\n')
+        .map((line) => (line === '' ? line : `    ${line}`))
+        .join('\n')
+        .trimEnd();
+}

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

@@ -0,0 +1,22 @@
+export type ResourceState = Map<string, unknown>;
+export type FieldChange = {
+    from?: unknown;
+    kind: 'added' | 'changed' | 'removed';
+    path: string;
+    to?: unknown;
+};
+export type StateChange = {
+    fields?: FieldChange[];
+    id: string;
+    patch: string;
+};
+export type StateDiff = {
+    added: string[];
+    changed: StateChange[];
+    removed: string[];
+};
+export declare function compareStates(left: ResourceState, right: ResourceState, labels: {
+    left: string;
+    right: string;
+}): StateDiff;
+export declare function isEmptyDiff(diff: StateDiff): boolean;

package/dist/lib/diff-state.js

@@ -0,0 +1,88 @@
+import { createTwoFilesPatch } from 'diff';
+import microdiff from 'microdiff';
+import { isDeepStrictEqual } from 'node:util';
+const MAX_VALUE_LENGTH = 200;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function formatValue(value) {
+    const text = JSON.stringify(value) ?? String(value);
+    return text.length > MAX_VALUE_LENGTH ? `${text.slice(0, MAX_VALUE_LENGTH - 1)}…` : text;
+}
+// createTwoFilesPatch treats a missing final newline as a "" hunk
+// line, noise when both sides lack it; normalize so only real differences surface.
+function ensureTrailingNewline(text) {
+    return text.endsWith('\n') ? text : `${text}\n`;
+}
+// Two strings (an API route file, a hook file, composer.json): a real line diff. Only the
+// `Index:` / `===` preamble createTwoFilesPatch emits is dropped; the `--- <left>` / `+++
+// <right>` lines are kept so each hunk still states its own direction.
+function renderTextChange(id, left, right, labels) {
+    const patch = createTwoFilesPatch(id, id, ensureTrailingNewline(left), ensureTrailingNewline(right), labels.left, labels.right);
+    const lines = patch.split('\n');
+    const start = lines.findIndex((line) => line.startsWith('--- '));
+    return (start === -1 ? lines : lines.slice(start)).join('\n').trimEnd();
+}
+// Two objects: microdiff walks them structurally and returns one entry per changed leaf, so
+// key ordering never matters and a big nested blob (a WPForms definition, an ACF group)
+// reduces to just the fields that moved.
+function objectFieldChanges(left, right) {
+    return microdiff(left, right, { cyclesFix: false }).map((change) => {
+        const path = change.path.join('.');
+        if (change.type === 'CREATE')
+            return { kind: 'added', path, to: change.value };
+        if (change.type === 'REMOVE')
+            return { from: change.oldValue, kind: 'removed', path };
+        return { from: change.oldValue, kind: 'changed', path, to: change.value };
+    });
+}
+function renderFieldChanges(changes) {
+    return changes
+        .map((change) => {
+        if (change.kind === 'added')
+            return `+ ${change.path}: ${formatValue(change.to)}`;
+        if (change.kind === 'removed')
+            return `- ${change.path}: ${formatValue(change.from)}`;
+        return `~ ${change.path}: ${formatValue(change.from)} → ${formatValue(change.to)}`;
+    })
+        .join('\n');
+}
+function changeFor(id, left, right, labels) {
+    if (typeof left === 'string' && typeof right === 'string') {
+        return { id, patch: renderTextChange(id, left, right, labels) };
+    }
+    if (isRecord(left) && isRecord(right)) {
+        const fields = objectFieldChanges(left, right);
+        return { fields, id, patch: renderFieldChanges(fields) };
+    }
+    // Type mismatch between the two sides (e.g. a field that was a string and is now an object).
+    return { id, patch: `~ ${formatValue(left)} → ${formatValue(right)}` };
+}
+// `left` is the reference, `right` is the subject. For `lps diff` with no env-vs-env args
+// that's remote (left) vs local (right), so `added` reads as "present locally, not on the
+// site" and `removed` as "on the site, not locally".
+export function compareStates(left, right, labels) {
+    const diff = { added: [], changed: [], removed: [] };
+    for (const id of right.keys()) {
+        if (!left.has(id))
+            diff.added.push(id);
+    }
+    for (const id of left.keys()) {
+        if (!right.has(id)) {
+            diff.removed.push(id);
+            continue;
+        }
+        const leftValue = left.get(id);
+        const rightValue = right.get(id);
+        if (isDeepStrictEqual(leftValue, rightValue))
+            continue;
+        diff.changed.push(changeFor(id, leftValue, rightValue, labels));
+    }
+    diff.added.sort((a, b) => a.localeCompare(b));
+    diff.removed.sort((a, b) => a.localeCompare(b));
+    diff.changed.sort((a, b) => a.id.localeCompare(b.id));
+    return diff;
+}
+export function isEmptyDiff(diff) {
+    return diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0;
+}

package/dist/lib/find-orphaned-files.js

@@ -1,7 +1,7 @@
 import { readdir } from 'node:fs/promises';
 import { extname, join } from 'node:path';
 // Same shape as load-files.ts's own walker, kept separate rather than shared: this one
-// filters against a list of extensions (page/snippet pull need more than one), that one
+// filters against a list of extensions (snippet pull needs more than one), that one
 // against a single extension, and reconciling the two would cost more than the ~15 duplicated
 // lines it would save.
 async function walk(dir, extensions) {

package/dist/lib/interactive.d.ts

@@ -1 +1,2 @@
 export declare function isInteractive(): boolean;
+export declare function confirmUninstall(toRemove: string[], yes: boolean): Promise<boolean>;

package/dist/lib/interactive.js

@@ -1,3 +1,4 @@
+import { confirm } from '@inquirer/prompts';
 // Whether prompts can be shown at all: a real terminal on both ends, and not a CI runner.
 // CI=1 with a pseudo-TTY still counts as non-interactive, which is what CI users expect.
 // Every command that prompts routes its decision through this so the CLI never hangs on a
@@ -5,3 +6,12 @@
 export function isInteractive() {
     return process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;
 }
+// The "about to uninstall N plugins/themes from the site" gate shared by `plugin push` and
+// `theme push`. Returns whether the caller may proceed: nothing to remove, --yes, or a
+// non-interactive shell all pass straight through; otherwise the user is asked and a "no"
+// returns false so the caller can abort.
+export async function confirmUninstall(toRemove, yes) {
+    if (yes || toRemove.length === 0 || !isInteractive())
+        return true;
+    return confirm({ default: false, message: `Uninstall ${toRemove.join(', ')} from the site?` });
+}

package/dist/lib/php-files-command.d.ts

@@ -0,0 +1,54 @@
+import { type Config } from '@oclif/core';
+import { type EnvironmentConfig } from '../types/config.js';
+import { type ResourceDirKind } from '../utils/resource-dirs.js';
+import { LoopressCommand } from './base.js';
+import { PushCommand } from './push-command.js';
+export type PhpFilesResource = {
+    afterPush?: (context: {
+        filenames: string[];
+        siteConfig: EnvironmentConfig;
+    }) => Promise<void>;
+    cliName: string;
+    dirKind: ResourceDirKind;
+    emptyListMessage: string;
+    endpoint: string;
+    filenamePattern: RegExp;
+    invalidFilenameHint: string;
+    label: string;
+    listDescription: string;
+    noun: string;
+    orphanReason: string;
+    pathLabel: string;
+    pathNoun: string;
+    pullDescription: string;
+    pushDescription: string;
+};
+type PhpFile = {
+    content: string;
+    filename: string;
+};
+type PushResult = {
+    pushed: string[];
+    status: 'dry-run' | 'success';
+};
+type PullResult = {
+    orphans: string[];
+    pulled: string[];
+    status: 'dry-run' | 'success';
+};
+export type CommandClass<TInstance> = new (argv: string[], config: Config) => TInstance;
+export type PushFilesCommand = Omit<PushCommand, 'run'> & {
+    run(): Promise<PushResult>;
+};
+export type PullFilesCommand = Omit<LoopressCommand, 'run'> & {
+    run(): Promise<PullResult>;
+};
+export type ListFilesCommand = Omit<LoopressCommand, 'run'> & {
+    run(): Promise<PhpFile[]>;
+};
+export declare function resourcePushCommand(spec: PhpFilesResource): CommandClass<PushFilesCommand>;
+export declare function resourcePullCommand(spec: PhpFilesResource): CommandClass<PullFilesCommand>;
+export declare function resourceListCommand(spec: PhpFilesResource): CommandClass<ListFilesCommand>;
+export declare const API_FILES_RESOURCE: PhpFilesResource;
+export declare const HOOK_FILES_RESOURCE: PhpFilesResource;
+export {};

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