@loopress/cli 0.33.0 → 0.35.0

package/dist/types/plugin.d.ts

@@ -16,7 +16,8 @@ export type WpNativePlugin = {
 export declare const PLUGIN_PIN: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     active: z.ZodExactOptional<z.ZodBoolean>;
     version: z.ZodString;
-}, z.core.$strip>]>;
+}, z.core.$strict>]>;
+export declare function pinProblem(slug: string, pin: unknown): string | undefined;
 export type PluginPin = z.infer<typeof PLUGIN_PIN>;
 export type PluginManifest = Record<string, PluginPin>;
 export declare const pinVersion: (pin: PluginPin) => string;

package/dist/types/plugin.js

@@ -1,7 +1,38 @@
 import { z } from 'zod';
 // A bare version string means "installed and active"; the object form records a plugin that
 // must stay installed but inactive.
-export const PLUGIN_PIN = z.union([z.string(), z.object({ active: z.boolean().exactOptional(), version: z.string() })]);
+// Strict: an unknown key is a typo (`activate` for `active`) that would otherwise be dropped.
+export const PLUGIN_PIN = z.union([z.string(), z.strictObject({ active: z.boolean().exactOptional(), version: z.string() })]);
+const PIN_KEYS = ['active', 'version'];
+// Levenshtein distance, enough to tell a typo of a pin key ("activate", "verison") from another key.
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1);
+            current.push(Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution));
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+// Why a loopress.json plugin pin is invalid, or undefined when it is fine.
+export function pinProblem(slug, pin) {
+    if (PLUGIN_PIN.safeParse(pin).success)
+        return undefined;
+    if (pin !== null && typeof pin === 'object' && !Array.isArray(pin)) {
+        const unknown = Object.keys(pin).filter((key) => !PIN_KEYS.includes(key));
+        if (unknown.length > 0) {
+            const hints = unknown.map((key) => {
+                const near = PIN_KEYS.find((known) => editDistance(key.toLowerCase(), known) <= 2);
+                return near ? `"${key}" (did you mean "${near}"?)` : `"${key}"`;
+            });
+            return `plugin "${slug}" has unknown key(s) ${hints.join(', ')}: a pin is a version string or {version, active}`;
+        }
+    }
+    return `plugin "${slug}" must map to a version string or {version, active}`;
+}
 export const pinVersion = (pin) => (typeof pin === 'string' ? pin : pin.version);
 // No pin at all (a slug loopress.json doesn't list) keeps the default: active.
 export const pinActive = (pin) => typeof pin === 'string' || pin?.active !== false;

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

@@ -30,11 +30,11 @@ export interface LoopressProjectConfiguration {
     /**
      * Directory where hook files (WordPress actions, filters, and scheduled tasks) are read from and written to, relative to rootDir.
      */
-    hooksDir?: string;
+    hookDir?: string;
     /**
      * Directory where single-page app bundles are read from and written to, relative to rootDir. Each subdirectory is one app: a loopress.app.json plus a built dist/ folder.
      */
-    appsDir?: string;
+    appDir?: string;
     /**
      * Directory where static HTML pages (one <slug>.html per WordPress page, managed by Loopress) are read from, relative to rootDir.
      */
@@ -58,7 +58,7 @@ export interface LoopressProjectConfiguration {
     /**
      * Directory where explicitly tracked WordPress options (wp_options rows) are read from and written to, relative to rootDir. Only options added via `lps option add` live here, this is never the whole options table.
      */
-    optionsDir?: string;
+    optionDir?: string;
     /**
      * Directory where custom post types (one JSON file of register_post_type() arguments per post type, named <slug>.json) are read from and written to, relative to rootDir.
      */
@@ -86,7 +86,7 @@ export interface LoopressProjectConfiguration {
     /**
      * Directory where the active block theme's Global Styles customizations (Site Editor > Styles: colors, typography, spacing) are read from and written to, relative to rootDir. Classic (non-block) themes are not supported.
      */
-    themeStylesDir?: string;
+    themeStyleDir?: string;
     /**
      * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
      */
@@ -106,6 +106,17 @@ export interface LoopressProjectConfiguration {
             active?: boolean;
         };
     };
+    /**
+     * Per-environment settings, keyed by environment name (as in `lps project config`).
+     */
+    environments?: {
+        [k: string]: {
+            /**
+             * Globs relative to rootDir (`*`, `**`, `?`) of files this environment never receives. `lps push`, `lps diff` and `lps promote` leave them alone on it: never pushed, never pruned or mirrored away, reported as held back instead of drift. A glob matching a directory covers everything inside. `lps pull` and `lps dev` ignore it.
+             */
+            exclude?: string[];
+        };
+    };
     /**
      * Keep the Loopress child theme (<parent>-loopress) active: `lps theme template push`, and so `lps push`, activates it when it isn't. Off by default, a theme switch changes the settings WordPress stores per theme.
      */

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

@@ -15,6 +15,8 @@ export declare function readLocalBlocks(dir: string): Promise<{
     blocks: LocalBlock[];
     problems: BlockProblem[];
 }>;
+export declare function excludedBlockFiles(dir: string, slug: string): string[];
+export declare function blockFilesToPush(dir: string, block: LocalBlock, site: BlockFiles | undefined): BlockFiles;
 export declare function formatBlockProblems(problems: BlockProblem[]): string;
 export declare function assertSafeBlock(block: LocalBlock): void;
 export declare function writeBlock(dir: string, block: LocalBlock): Promise<void>;

package/dist/utils/block-format.js

@@ -1,5 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { isExcluded, withoutExcluded } from '../lib/exclude.js';
 import { errorCode, isRecord } from '../lib/narrow.js';
 // A dynamic block: blocks/<slug>/ in WordPress's own block format, registered on the site as
 // loopress/<slug> (the plugin's BlocksDirectory and BlockFilesController).
@@ -53,7 +54,7 @@ export function blockProblems(slug, files) {
 export async function readLocalBlocks(dir) {
     let entries;
     try {
-        entries = await readdir(dir, { withFileTypes: true });
+        entries = withoutExcluded(dir, await readdir(dir, { withFileTypes: true }), (entry) => entry.name);
     }
     catch (error) {
         if (errorCode(error) === 'ENOENT')
@@ -69,12 +70,27 @@ export async function readLocalBlocks(dir) {
             if (file.isFile() && !file.name.startsWith('.'))
                 files[file.name] = await readFile(join(dir, slug, file.name), 'utf8');
         }
+        // Checked whole, then the environment's excluded files are dropped: a push keeps the site's
+        // copy of those (see blockFilesToPush), a diff holds the block back.
         for (const message of blockProblems(slug, files))
             problems.push({ file: join(dir, slug), message });
-        blocks.push({ files, slug });
+        const kept = new Set(withoutExcluded(join(dir, slug), Object.keys(files), (name) => name));
+        blocks.push({ files: Object.fromEntries(Object.entries(files).filter(([name]) => kept.has(name))), slug });
     }
     return { blocks, problems };
 }
+// Block files the environment excludes: never sent, so the site's copy of each one goes back in
+// the PUT (a block is replaced as a whole).
+export function excludedBlockFiles(dir, slug) {
+    return BLOCK_FILES.filter((name) => isExcluded(join(dir, slug, name)));
+}
+// What a push sends for `block`: its local files plus the site's copy of its excluded ones.
+export function blockFilesToPush(dir, block, site) {
+    const excluded = new Set(excludedBlockFiles(dir, block.slug));
+    const kept = Object.entries(block.files).filter(([name]) => !excluded.has(name));
+    const fromSite = Object.entries(site ?? {}).filter(([name]) => excluded.has(name));
+    return Object.fromEntries([...kept, ...fromSite]);
+}
 export function formatBlockProblems(problems) {
     return problems.map((problem) => `${problem.file}: ${problem.message}`).join('\n');
 }

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

@@ -26,6 +26,7 @@ export type ListedOption = {
 };
 export declare function isReservedOptionName(name: string): boolean;
 export declare function defaultReadonlyFor(name: string): boolean;
+export declare function isWindowsReservedName(name: string): boolean;
 export declare function optionFileName(name: string): string;
 export declare function partitionByReadonly(tracked: LocalOption[]): {
     skipped: LocalOption[];

package/dist/utils/option-format.js

@@ -38,7 +38,17 @@ export function isReservedOptionName(name) {
 export function defaultReadonlyFor(name) {
     return READONLY_BY_DEFAULT_OPTION_NAMES.includes(name);
 }
+// Windows refuses these device names as a file name, with or without an extension (`NUL.json`).
+const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])$/i;
+export function isWindowsReservedName(name) {
+    return WINDOWS_RESERVED_NAME.test(name.split('.', 1)[0]?.trimEnd() ?? '');
+}
+function reservedNameMessage(name) {
+    return `Option name "${name}" is a reserved Windows file name (CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9) and cannot be tracked as ${name}.json`;
+}
 export function optionFileName(name) {
+    if (isWindowsReservedName(name))
+        throw new Error(reservedNameMessage(name));
     return `${name}.json`;
 }
 // Splits tracked options into what `push` may write and what it must skip: readonly is a local
@@ -54,7 +64,10 @@ const REFS_ERROR = '"refs" must map a value path to a post type, e.g. {"purchase
 // Each check's message is the error thrown for it, the first failing one wins. Loose: unknown
 // keys (`readonly`, future ones) pass through untouched.
 const LOCAL_OPTION = z.looseObject({
-    name: z.string('missing a "name" string').min(1, 'missing a "name" string'),
+    name: z
+        .string('missing a "name" string')
+        .min(1, 'missing a "name" string')
+        .refine((name) => !isWindowsReservedName(name), { error: (issue) => reservedNameMessage(String(issue.input)) }),
     autoload: z.string('missing an "autoload" string'),
     // `value` itself is deliberately untyped (a WP option can hold any JSON-safe value, including
     // null); only the key's presence is checked, so a hand-edited file that dropped it entirely is

package/dist/utils/page-format.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
+import { withoutExcluded } from '../lib/exclude.js';
 import { errorCode, errorMessage, isOneOf } from '../lib/narrow.js';
 export const PAGES_ENDPOINT = 'loopress/v1/pages';
 // Mirrored server-side in PagesController. No leading, trailing or doubled hyphen: WordPress's
@@ -90,7 +91,7 @@ export async function readLocalPages(dir) {
 export async function readLocalHtmlFiles(dir, parse, slugRule = PAGE_SLUG_RULE) {
     let entries;
     try {
-        entries = await readdir(dir, { withFileTypes: true });
+        entries = withoutExcluded(dir, await readdir(dir, { withFileTypes: true }), (entry) => entry.name);
     }
     catch (error) {
         if (errorCode(error) === 'ENOENT')

package/dist/utils/plugins.d.ts

@@ -37,5 +37,8 @@ export type MergeResult<P extends PluginPin = PluginPin> = {
 export declare function describePin(pin: PluginPin): string;
 export declare function mergePluginManifest<P extends PluginPin>(existing: Record<string, P>, incoming: Record<string, P>): MergeResult<P>;
 export declare function parseInstalledPlugins(raw: WpNativePlugin[]): InstalledPlugin[];
+export declare function preferredCopy<P extends {
+    file: string;
+}>(copies: P[], slug: string): P | undefined;
 export declare function diffPlugins(manifest: PluginManifest, installed: InstalledPlugin[], managedSlugs?: Set<string>): PluginDiff;
 export declare function lockedWpackagistSlugs(composerLock: null | string, kind: 'plugin' | 'theme'): Set<string>;

package/dist/utils/plugins.js

@@ -46,12 +46,17 @@ export function parseInstalledPlugins(raw) {
     }))
         .filter((plugin) => !LOOPRESS_PLUGIN_SLUGS.has(plugin.slug));
 }
+// Composer installs a plugin into `<slug>/`; a site can also hold another copy under the same
+// slug (core's `hello.php` is Hello Dolly). Prefer the one in the slug's folder.
+export function preferredCopy(copies, slug) {
+    return copies.find((p) => p.file.startsWith(`${slug}/`)) ?? copies[0];
+}
 export function diffPlugins(manifest, installed, 
 // Slugs Loopress currently manages, from the local composer.lock's wpackagist-plugin/*
 // entries. Empty for a loopress.json-only project that doesn't keep a lockfile in the repo:
 // `toRemove` then stays empty (removals still happen server-side, they just aren't previewed).
 managedSlugs = new Set()) {
-    const installedMap = new Map(installed.map((p) => [p.slug, p]));
+    const installedMap = new Map(installed.map((p) => [p.slug, preferredCopy(installed.filter((q) => q.slug === p.slug), p.slug) ?? p]));
     const toInstall = [];
     const toPin = [];
     const toActivate = [];

package/dist/utils/rename-retry.d.ts

@@ -0,0 +1 @@
+export declare function renameWithRetry(from: string, to: string, attempts?: number, baseDelayMs?: number): Promise<void>;

package/dist/utils/rename-retry.js

@@ -0,0 +1,20 @@
+import { rename } from 'node:fs/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
+const RETRYABLE_CODES = new Set(['EBUSY', 'EPERM']);
+// On Windows, an editor, an antivirus or the search indexer can briefly hold a file open and make
+// rename() fail with EPERM/EBUSY. Those clear within milliseconds, so retry a few times with a
+// growing delay before giving up. Other errors (ENOENT, EEXIST...) are thrown right away.
+export async function renameWithRetry(from, to, attempts = 5, baseDelayMs = 50) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error ? String(error.code) : '';
+            if (!RETRYABLE_CODES.has(code) || attempt >= attempts)
+                throw error;
+            await sleep(baseDelayMs * attempt);
+        }
+    }
+}

package/dist/utils/resource-dirs.js

@@ -28,16 +28,16 @@ export const RESOURCE_DIR_DEFAULTS = {
 const CONFIG_KEY = {
     acf: 'acfDir',
     api: 'apiDir',
-    apps: 'appsDir',
+    apps: 'appDir',
     block: 'blockDir',
     blockCss: 'blockCssDir',
     cpt: 'cptDir',
     css: 'cssDir',
     form: 'formDir',
-    hooks: 'hooksDir',
+    hooks: 'hookDir',
     menu: 'menuDir',
     meta: 'metaDir',
-    options: 'optionsDir',
+    options: 'optionDir',
     page: 'pageDir',
     part: 'partDir',
     pattern: 'patternDir',
@@ -45,7 +45,7 @@ const CONFIG_KEY = {
     snippets: 'snippetsDir',
     taxonomy: 'taxonomyDir',
     template: 'templateDir',
-    themeStyles: 'themeStylesDir',
+    themeStyles: 'themeStyleDir',
 };
 // Resolves where a resource's files live: an explicit override wins, otherwise the
 // loopress.json `<kind>Dir` setting, otherwise the built-in default, all under `rootDir`.

package/dist/utils/version.d.ts

@@ -1,2 +1,4 @@
 export declare function isExactVersion(value: string): boolean;
 export declare function compareVersions(a: string, b: string): null | number;
+export type VersionJump = 'major' | 'minor' | 'patch';
+export declare function versionJump(from: string, to: string): null | VersionJump;

package/dist/utils/version.js

@@ -19,3 +19,24 @@ export function isExactVersion(value) {
 export function compareVersions(a, b) {
     return validate(a) && validate(b) ? cmp(a, b) : null;
 }
+// How far `from` is behind `to`: the first numeric segment that differs, major, minor, then
+// anything finer is a patch. Null when `from` is not behind `to` or either isn't comparable.
+export function versionJump(from, to) {
+    const order = compareVersions(from, to);
+    if (order === null || order >= 0)
+        return null;
+    const a = numericSegments(from);
+    const b = numericSegments(to);
+    if (a[0] !== b[0])
+        return 'major';
+    if ((a[1] ?? 0) !== (b[1] ?? 0))
+        return 'minor';
+    return 'patch';
+}
+function numericSegments(version) {
+    const core = (version.split('-', 1)[0] ?? version).replace(/^v/i, '');
+    return core.split('.').map((part) => {
+        const n = Number(part);
+        return Number.isNaN(n) ? 0 : Math.trunc(n);
+    });
+}

package/dist/utils/wporg.d.ts

@@ -0,0 +1,5 @@
+export declare const WPORG_INFO = "https://api.wordpress.org/plugins/info/1.2/";
+export declare function requestPluginInfo(slug: string, { versions }?: {
+    versions?: boolean;
+}): Promise<null | Record<string, unknown>>;
+export declare function fetchPluginInfo(slug: string): Promise<null | Record<string, unknown>>;

package/dist/utils/wporg.js

@@ -0,0 +1,41 @@
+import got from 'got';
+export const WPORG_INFO = 'https://api.wordpress.org/plugins/info/1.2/';
+// The WordPress.org plugin_information answer for one slug, or null when the plugin isn't
+// listed there (zip, premium), or {error: 'closed'} for a closed one. Throws when the API can't be reached or answers with an error.
+// `versions` adds every released version (`versions`: version -> download URL) to the answer.
+export async function requestPluginInfo(slug, { versions = false } = {}) {
+    try {
+        const body = await got(WPORG_INFO, {
+            searchParams: {
+                action: 'plugin_information',
+                'request[slug]': slug,
+                ...(versions && { 'request[fields][versions]': '1' }),
+            },
+            timeout: { request: 10_000 },
+        }).json();
+        // A removed plugin answers {error: 'closed'}: kept so callers can tell it from an unlisted one.
+        if (typeof body === 'object' && 'error' in body && body.error === 'closed')
+            return body;
+        return typeof body === 'object' && !('error' in body) ? body : null;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+}
+// Same lookup, but an unreachable API is reported as null too.
+export async function fetchPluginInfo(slug) {
+    try {
+        return await requestPluginInfo(slug);
+    }
+    catch {
+        return null;
+    }
+}
+function isNotFound(error) {
+    if (typeof error !== 'object' || error === null || !('response' in error))
+        return false;
+    const { response } = error;
+    return typeof response === 'object' && response !== null && 'statusCode' in response && response.statusCode === 404;
+}