@loopress/cli 0.23.0 → 0.24.1

package/dist/lib/local-callback-server.js

@@ -1,4 +1,5 @@
 import { Buffer } from 'node:buffer';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import { openBrowser } from './open-browser.js';
 async function readBody(req) {
@@ -10,12 +11,31 @@ async function readBody(req) {
 function parseFormData(body) {
     return Object.fromEntries(new URLSearchParams(body));
 }
+/** Constant-time compare that also tolerates a length mismatch without throwing. */
+function safeEqual(a, b) {
+    const bufferA = Buffer.from(a);
+    const bufferB = Buffer.from(b);
+    return bufferA.length === bufferB.length && timingSafeEqual(bufferA, bufferB);
+}
 /**
  * Sends the user to a URL in their browser and catches the resulting redirect on a short-lived
  * local server; this factors out the server setup, timeout, and browser-opening boilerplate.
+ *
+ * The loopback server is unauthenticated, so any local process or web page open during the wait
+ * could otherwise POST forged credentials to it (RFC 8252 section 8.9). Two guards close that:
+ *
+ * - a 32-byte `state` generated here, threaded into the authorize URL by `buildUrl`, and required
+ *   back (constant-time compare) on any request that carries credentials;
+ * - an `Origin` allowlist: a browser sends `Origin` on the relay's cross-site form POST, so a
+ *   stray page's POST (carrying its own origin) is rejected. Top-level navigations send no
+ *   `Origin` and are allowed, which is why `state` is the primary control.
+ *
+ * The first request that looks like a callback (valid or not) shuts the server down, so a
+ * failed guess gets no second try within the window.
  */
 export async function waitForLocalCallback(options) {
     const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
+    const state = randomBytes(32).toString('hex');
     return new Promise((resolve, reject) => {
         function finish(res, page) {
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
@@ -23,10 +43,29 @@ export async function waitForLocalCallback(options) {
             clearTimeout(timer);
             server.close();
         }
+        function rejectRequest(res, message) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end(message);
+            clearTimeout(timer);
+            server.close();
+            reject(new Error(message));
+        }
         async function handleIncoming(req, res) {
             try {
                 const url = new URL(req.url ?? '/', 'http://localhost');
                 const body = req.method === 'POST' ? parseFormData(await readBody(req)) : {};
+                const looksLikeCallback = url.searchParams.has('state') || Object.keys(body).length > 0;
+                if (looksLikeCallback) {
+                    const { origin } = req.headers;
+                    if (origin !== undefined && !options.allowedOrigins.includes(origin)) {
+                        rejectRequest(res, 'Rejected a cross-origin request to the login callback server.');
+                        return;
+                    }
+                    if (!safeEqual(url.searchParams.get('state') ?? '', state)) {
+                        rejectRequest(res, 'Rejected a login callback with a missing or invalid state value.');
+                        return;
+                    }
+                }
                 options.handleRequest(url, {
                     rejectWithPage(page, error) {
                         finish(res, page);
@@ -61,7 +100,7 @@ export async function waitForLocalCallback(options) {
         }, timeoutMs);
         server.listen(0, '127.0.0.1', () => {
             const { port } = server.address();
-            const targetUrl = options.buildUrl(`http://localhost:${port}`);
+            const targetUrl = options.buildUrl(`http://localhost:${port}`, state);
             options.log(options.openingMessage);
             options.log(`\nIf it doesn't open automatically, visit:\n${targetUrl}\n`);
             openBrowser(targetUrl);

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

@@ -0,0 +1,67 @@
+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;
+    rmDescription: string;
+};
+type RemotePhpFile = {
+    content?: string;
+    error?: string;
+    filename: string;
+    public?: boolean;
+};
+type PushResult = {
+    pruned: string[];
+    pushed: string[];
+    status: 'dry-run' | 'success';
+};
+type PullResult = {
+    orphans: string[];
+    pulled: string[];
+    status: 'dry-run' | 'success';
+};
+type RmResult = {
+    filename: string;
+    removed: boolean;
+    status: 'aborted' | '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<RemotePhpFile[]>;
+};
+export type RmFilesCommand = Omit<LoopressCommand, 'run'> & {
+    run(): Promise<RmResult>;
+};
+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 function resourceRmCommand(spec: PhpFilesResource): CommandClass<RmFilesCommand>;
+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,338 @@
+import { confirm } from '@inquirer/prompts';
+import { Args, Flags } 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 { isInteractive } from './interactive.js';
+import { loadFiles as loadDirectoryFiles } from './load-files.js';
+import { PushCommand } from './push-command.js';
+import { isApplicative404 } from './wp-client.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]}`,
+            `$ lps ${spec.cliName} push --prune`,
+        ];
+        static flags = {
+            ...PushCommand.dryRunFlag,
+            ...PushCommand.yesFlag,
+            prune: Flags.boolean({
+                default: false,
+                description: `Delete server-side ${spec.noun}s not present locally after pushing`,
+            }),
+        };
+        async run() {
+            const { args, flags } = 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 = [];
+            const publicRoutes = [];
+            await this.runPushTasks(files, (file) => file.filename, async (file, task) => {
+                const result = await this.pushFile(file, task);
+                pushed.push(file.filename);
+                if (result?.public)
+                    publicRoutes.push(file.filename);
+            });
+            if (this.failedCount > 0) {
+                this.error(`${pluralize(this.failedCount, spec.noun)} failed to push.`);
+            }
+            for (const route of publicRoutes) {
+                this.warn(`${route}: PUBLIC route, no authentication required. Anyone on the internet can call it. See https://loopress.dev/api/routes/#authentication-and-permissions`);
+            }
+            const pruned = flags.prune ? await this.prune(new Set(files.map((file) => file.filename))) : [];
+            if (this.dryRun)
+                return { pruned, pushed, status: 'dry-run' };
+            await this.recordSuccess();
+            await spec.afterPush?.({ filenames: pushed, siteConfig: this.siteConfig });
+            this.log(`All ${spec.label} pushed.`);
+            return { pruned, pushed, status: 'success' };
+        }
+        async loadFiles(path) {
+            return loadPhpFiles(this, path);
+        }
+        // Mirror of `pull`'s local orphan cleanup, aimed at the server: any file on WordPress with
+        // no local counterpart is deleted. Opt-in (`--prune`) because it removes code from a live
+        // site. In a non-TTY without `--yes` it refuses rather than prunes: a stray local path in
+        // CI must not silently wipe production routes, and unlike `pull`'s local deletions these
+        // are not recoverable from the repo.
+        async prune(localFilenames) {
+            const remote = await this.wp.get(spec.endpoint);
+            const orphans = remote.map((file) => file.filename).filter((name) => !localFilenames.has(name));
+            if (orphans.length === 0)
+                return [];
+            const summary = `${pluralize(orphans.length, spec.noun)} on ${this.siteConfig.url} not present locally: ${orphans.join(', ')}`;
+            if (this.dryRun) {
+                this.log(`[dry-run] Would prune ${summary}`);
+                return orphans;
+            }
+            if (!this.yes) {
+                if (!isInteractive()) {
+                    const count = pluralize(orphans.length, `server-side ${spec.noun}`);
+                    this.error(`--prune would delete ${count} but stdin is not a TTY. Re-run with --yes to confirm, or without --prune.`);
+                }
+                const ok = await confirm({ default: false, message: `Prune ${summary}?` });
+                if (!ok) {
+                    this.log('Kept the server-side files, nothing pruned.');
+                    return [];
+                }
+            }
+            // Sequential, like runPushTasks: keeps the "Pruned: …" lines ordered and the WordPress
+            // writes serial.
+            const deleted = [];
+            for (const filename of orphans) {
+                await this.wp.delete(`${spec.endpoint}?filename=${encodeURIComponent(filename)}`);
+                this.log(`Pruned: ${filename}`);
+                deleted.push(filename);
+            }
+            return deleted;
+        }
+        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 undefined;
+            }
+            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}`;
+                }
+                return result;
+            }
+            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 file the server would not read back (over the size limit, see LP-SEC-02) arrives
+            // with no content: report it and leave any local copy untouched rather than overwriting
+            // it with nothing.
+            const unreadable = files.filter((file) => typeof file.content !== 'string');
+            for (const file of unreadable) {
+                this.warn(`Skipped ${file.filename}: ${file.error ?? 'the server did not return its content'}`);
+            }
+            const readable = files.filter((file) => typeof file.content === 'string');
+            // 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`). The
+            // unreadable ones still exist remotely, so keep them out of the orphan set.
+            const orphans = await findOrphanedFiles(path, new Set(files.map((file) => file.filename)), {
+                extensions: ['.php'],
+                key: basenameKey,
+                recursive: true,
+            });
+            const pulled = readable.map((file) => file.filename);
+            await this.pullDirectory(path, readable, orphans, {
+                alwaysCreateDir: true,
+                dryRunMessage: `Would pull ${pluralize(readable.length, spec.noun)} to ${path}`,
+                orphanReason: spec.orphanReason,
+                pulledMessage: `Pulled ${pluralize(readable.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) {
+                const badges = [file.public ? '[PUBLIC]' : '', file.error ? `(${file.error})` : ''].filter(Boolean).join('  ');
+                this.log(badges ? `  ${file.filename}  ${badges}` : `  ${file.filename}`);
+            }
+            if (files.some((file) => file.public)) {
+                this.log('');
+                this.warn('[PUBLIC] routes run for anyone, with no authentication. Review them.');
+            }
+            return files;
+        }
+    }
+    return ResourceList;
+}
+export function resourceRmCommand(spec) {
+    class ResourceRm extends LoopressCommand {
+        static args = {
+            filename: Args.string({
+                description: `The ${spec.noun} to remove, its slug without the .php extension (e.g. "hello" or "invoice-pdf/[order_id]")`,
+                required: true,
+            }),
+        };
+        static description = spec.rmDescription;
+        static enableJsonFlag = true;
+        static examples = [`$ lps ${spec.cliName} rm hello`, `$ lps ${spec.cliName} rm hello --yes`];
+        static flags = { ...LoopressCommand.dryRunFlag, ...LoopressCommand.yesFlag };
+        async run() {
+            const { args } = await this.parse(ResourceRm);
+            const { filename } = args;
+            const { url } = this.siteConfig;
+            if (!spec.filenamePattern.test(filename)) {
+                this.error(`Invalid filename "${filename}": ${spec.invalidFilenameHint}`);
+            }
+            if (this.dryRun) {
+                this.log(`[dry-run] Would remove ${filename} from ${url}`);
+                return { filename, removed: false, status: 'dry-run' };
+            }
+            if (!this.yes) {
+                if (!isInteractive()) {
+                    this.error(`Removing ${filename} needs confirmation. Re-run with --yes.`);
+                }
+                const ok = await confirm({ default: false, message: `Remove ${filename} from ${url}?` });
+                if (!ok) {
+                    this.log('Aborted.');
+                    return { filename, removed: false, status: 'aborted' };
+                }
+            }
+            try {
+                await this.wp.delete(`${spec.endpoint}?filename=${encodeURIComponent(filename)}`);
+            }
+            catch (error) {
+                if (isApplicative404(error, 'File not found')) {
+                    this.error(`${filename} is not on ${url}.`);
+                }
+                throw error;
+            }
+            this.log(`Removed ${filename} from ${url}`);
+            return { filename, removed: true, status: 'success' };
+        }
+    }
+    return ResourceRm;
+}
+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',
+    rmDescription: 'Remove a custom API route file from 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',
+    rmDescription: 'Remove a hook file (action, filter, cron) from 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>;