@loopress/cli 0.29.0 → 0.31.0

package/dist/lib/spinner.js

@@ -0,0 +1,72 @@
+// The one spinner behind every pending wait: WpClient and ApiClient requests, the browser
+// callback, a build, a third-party lookup. Refcounted so overlapping waits share one line (the
+// outermost label wins), on stderr and only on an interactive one, so `--json`, pipes and CI
+// output never see a frame. While it spins, every stdout/stderr write clears the line first and
+// redraws it after, so a this.log() mid-wait lands above it instead of on it.
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+let depth = 0;
+let paused = 0;
+let label = '';
+let frame = 0;
+let stopSpinning;
+function isEnabled() {
+    return process.stderr.isTTY && !process.env.CI;
+}
+function start() {
+    const rawOut = process.stdout.write;
+    const rawErr = process.stderr.write;
+    const draw = () => {
+        const text = `${FRAMES[frame]} ${label}`.slice(0, (process.stderr.columns ?? 80) - 1);
+        rawErr.call(process.stderr, `\r\u{1B}[2K${text}`);
+    };
+    const clear = () => rawErr.call(process.stderr, '\r\u{1B}[2K');
+    const intercept = (stream, raw) => (...args) => {
+        clear();
+        const result = raw.apply(stream, args);
+        draw();
+        return result;
+    };
+    process.stdout.write = intercept(process.stdout, rawOut);
+    process.stderr.write = intercept(process.stderr, rawErr);
+    draw();
+    const timer = setInterval(() => {
+        frame = (frame + 1) % FRAMES.length;
+        draw();
+    }, 80);
+    timer.unref();
+    stopSpinning = () => {
+        clearInterval(timer);
+        process.stdout.write = rawOut;
+        process.stderr.write = rawErr;
+        clear();
+        stopSpinning = undefined;
+    };
+}
+export async function withSpinner(message, work) {
+    if (!isEnabled())
+        return work();
+    if (depth++ === 0)
+        label = message;
+    if (paused === 0 && !stopSpinning)
+        start();
+    try {
+        return await work();
+    }
+    finally {
+        if (--depth === 0)
+            stopSpinning?.();
+    }
+}
+// For code that draws its own progress (Listr renderers, which already spin per task) or reads
+// from the terminal (prompts): the spinner steps aside, then comes back if a wait is still pending.
+export async function withoutSpinner(work) {
+    paused++;
+    stopSpinning?.();
+    try {
+        return await work();
+    }
+    finally {
+        if (--paused === 0 && depth > 0 && isEnabled())
+            start();
+    }
+}

package/dist/lib/temp-admin.d.ts

@@ -16,4 +16,13 @@ export declare function createTempAdmin(wp: WpClient): Promise<TempAdmin>;
  * cleanup that silently fails would leave a live administrator with a random password on the
  * target site, discoverable only by someone reading logs closely.
  */
-export declare function deleteTempAdmin(wp: WpClient, admin: TempAdmin): Promise<void>;
+export declare function deleteTempAdmin(wp: WpClient, admin: Pick<TempAdmin, 'id' | 'username'>): Promise<void>;
+/**
+ * Lists temporary admins a previous bootstrap left behind: a process killed with SIGKILL, a
+ * machine that lost power, or a network drop during deleteTempAdmin() skips every cleanup path.
+ * Matching both the username prefix and the `.invalid` email keeps a real user who happens to
+ * be named `lps-temp-...` out of it. `context=edit` exposes `username` and `email` and lists
+ * every user, not only those with published posts.
+ */
+export declare function findTempAdmins(wp: WpClient): Promise<Array<Pick<TempAdmin, 'id' | 'username'>>>;
+export declare function sweepTempAdmins(wp: WpClient): Promise<string[]>;

package/dist/lib/temp-admin.js

@@ -1,5 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { isNotFoundError } from './wp-client.js';
+const TEMP_ADMIN_PREFIX = 'lps-temp-';
+const TEMP_ADMIN_EMAIL_DOMAIN = '@lps-temp.invalid';
 // Only role that carries `install_plugins`/`activate_plugins`; there's nothing narrower to grant.
 const TEMP_ADMIN_ROLE = 'administrator';
 /**
@@ -8,10 +10,10 @@ const TEMP_ADMIN_ROLE = 'administrator';
  * addresses guaranteed not to be real, appropriate for an account that has no real mailbox.
  */
 export async function createTempAdmin(wp) {
-    const username = `lps-temp-${Date.now().toString(36)}`;
+    const username = `${TEMP_ADMIN_PREFIX}${Date.now().toString(36)}`;
     const password = randomBytes(24).toString('base64url');
     const user = await wp.post('wp/v2/users', {
-        email: `${username}@lps-temp.invalid`,
+        email: `${username}${TEMP_ADMIN_EMAIL_DOMAIN}`,
         password,
         roles: [TEMP_ADMIN_ROLE],
         username,
@@ -44,3 +46,26 @@ export async function deleteTempAdmin(wp, admin) {
         throw new Error(`Temporary admin account "${admin.username}" (id ${admin.id}) still exists after deletion. Remove it manually from wp-admin.`);
     }
 }
+/**
+ * Lists temporary admins a previous bootstrap left behind: a process killed with SIGKILL, a
+ * machine that lost power, or a network drop during deleteTempAdmin() skips every cleanup path.
+ * Matching both the username prefix and the `.invalid` email keeps a real user who happens to
+ * be named `lps-temp-...` out of it. `context=edit` exposes `username` and `email` and lists
+ * every user, not only those with published posts.
+ */
+export async function findTempAdmins(wp) {
+    const users = await wp.getAll(`wp/v2/users?context=edit&search=${TEMP_ADMIN_PREFIX}`);
+    return users
+        .filter((user) => user.username.startsWith(TEMP_ADMIN_PREFIX) && user.email.endsWith(TEMP_ADMIN_EMAIL_DOMAIN))
+        .map(({ id, username }) => ({ id, username }));
+}
+// Deletes every leftover temp admin, returning the usernames removed. Throws on the first one
+// that can't be removed, naming it (deleteTempAdmin's own error).
+export async function sweepTempAdmins(wp) {
+    const leftovers = await findTempAdmins(wp);
+    for (const admin of leftovers) {
+        // Sequential on purpose: the first failure stops the sweep, naming its account.
+        await deleteTempAdmin(wp, admin);
+    }
+    return leftovers.map((admin) => admin.username);
+}

package/dist/lib/validate-local.js

@@ -1,27 +1,33 @@
 import { readFile } from 'node:fs/promises';
 import { join } 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';
-import { readLocalPages } from '../utils/page-format.js';
+import { readLocalHtmlFiles, readLocalPages } from '../utils/page-format.js';
+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 { 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).
-const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir', 'menuDir', 'themeStylesDir'];
+const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'menuDir', 'themeStylesDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
+    cptDir: 'cpt',
     formDir: 'forms',
     hooksDir: 'hooks',
     menuDir: 'menus',
+    metaDir: 'meta',
     optionsDir: 'options',
     pageDir: 'pages',
-    partDir: 'parts',
-    seoDir: 'seo',
+    partDir: RESOURCE_DIR_DEFAULTS.part,
+    patternDir: RESOURCE_DIR_DEFAULTS.pattern,
+    roleDir: RESOURCE_DIR_DEFAULTS.role,
     snippetsDir: 'snippets',
-    templateDir: 'templates',
+    taxonomyDir: 'taxonomies',
+    templateDir: RESOURCE_DIR_DEFAULTS.template,
     themeStylesDir: 'theme',
 };
 // Inspects the local tracked files under `cwd` without contacting WordPress: JSON files parse
@@ -46,6 +52,11 @@ export async function validateLocal(cwd) {
     // Same reader `option push` uses: a file missing "name", "autoload" or "value" is skipped
     // there with a warning, so it's a problem here.
     checked += await checkJsonDir(resolve('optionsDir'), problems, parseLocalOption);
+    checked += await checkJsonDir(resolve('cptDir'), problems, declaredFileChecker(CPT_SPEC));
+    checked += await checkJsonDir(resolve('taxonomyDir'), problems, declaredFileChecker(TAXONOMY_SPEC));
+    checked += await checkJsonDir(resolve('metaDir'), problems, declaredFileChecker(META_SPEC));
+    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');
@@ -57,6 +68,18 @@ export async function validateLocal(cwd) {
     problems.push(...templates.problems);
     return { checked, problems, valid: problems.length === 0 };
 }
+// Same directory rules as pages (flat, .html only), then the same checks as `pattern push`.
+async function checkPatterns(dir, problems) {
+    const check = declaredFileChecker(PATTERN_SPEC);
+    const { files, problems: found } = await readLocalHtmlFiles(dir, (slug, raw) => {
+        check(raw, join(dir, `${slug}.html`));
+    }, {
+        message: `the file name must be 1 to ${PATTERN_SPEC.slugMaxLength} lowercase letters, digits, "_" or "-"`,
+        pattern: new RegExp(`^[a-z0-9_-]{1,${PATTERN_SPEC.slugMaxLength}}$`),
+    });
+    problems.push(...found);
+    return files.length + found.length;
+}
 // 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.
@@ -103,9 +126,8 @@ async function checkComposerJson(cwd, problems) {
     }
     return 1;
 }
-// Recursive: ACF keeps one subdirectory per object type (acf/field-groups/*.json) and SEO its
-// post meta and redirects (seo/post-meta/<type>/*.json, seo/redirects/*.json); a top-level-only
-// scan silently never checked any of those. `shape` runs on files that are JSON objects and
+// Recursive: ACF keeps one subdirectory per object type (acf/field-groups/*.json); a
+// top-level-only scan silently never checked those. `shape` runs on files that are JSON objects and
 // throws to report a resource-specific problem.
 async function checkJsonDir(dir, problems, shape) {
     const entries = await readdirTolerant(dir, { recursive: true, withFileTypes: true });
@@ -130,7 +152,7 @@ async function checkJsonDir(dir, problems, shape) {
             continue;
         }
         try {
-            shape?.(raw);
+            shape?.(raw, filePath);
         }
         catch (error) {
             problems.push({ file: filePath, message: error.message });
@@ -156,12 +178,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

@@ -23,6 +23,7 @@ type RequestOptions = {
     timeoutMs?: number;
 };
 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 isTimeoutError(error: unknown): boolean;
 export declare function isInvalidPageNumber(error: unknown): boolean;

package/dist/lib/wp-client.js

@@ -1,5 +1,6 @@
 import got from 'got';
 import { Buffer } from 'node:buffer';
+import { withSpinner } from './spinner.js';
 export const REQUEST_TIMEOUT_MS = 30_000;
 // The one environment allowed to talk plain HTTP: Loopress's local dev environment, identified
 // by its config name (the same "local" environment `lps dev` targets), never by the URL's host.
@@ -81,7 +82,7 @@ export class WpClient {
     async request(method, path, json, options) {
         const timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS;
         try {
-            const response = await this.client(path, { json, method, timeout: { request: timeoutMs } });
+            const response = await withSpinner(`Waiting for ${new URL(this.siteUrl).host}`, async () => this.client(path, { json, method, timeout: { request: timeoutMs } }));
             return (response.body ? JSON.parse(response.body) : undefined);
         }
         catch (error) {
@@ -93,6 +94,11 @@ export function isNotFoundError(error) {
     const cause = error?.cause;
     return cause?.response?.statusCode === 404;
 }
+// Authenticated but missing the capability the endpoint needs (e.g. `list_users`).
+export function isForbiddenError(error) {
+    const cause = error?.cause;
+    return cause?.response?.statusCode === 403;
+}
 // A 404 a Loopress controller raises on purpose, identified by its JSON body's `error` field
 // (e.g. `{"error": "composer.lock not found"}` from ComposerController). Narrower than
 // isNotFoundError: a bare 404 also covers the route being absent because the plugin isn't
@@ -153,8 +159,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/lib/wp-site-diagnostic.js

@@ -1,4 +1,5 @@
 import got from 'got';
+import { withSpinner } from './spinner.js';
 export const REQUEST_TIMEOUT_MS = 10_000;
 /**
  * WordPress 7.0 is the first version that accepts a loopback `http://127.0.0.1` success_url on
@@ -22,7 +23,7 @@ const MIN_BROWSER_AUTH_MAJOR = 7;
 export async function diagnoseWpSite(siteUrl) {
     let index;
     try {
-        index = await got.get(`${siteUrl}/wp-json/`, { timeout: { request: REQUEST_TIMEOUT_MS } }).json();
+        index = await withSpinner(`Checking ${siteUrl}`, async () => got.get(`${siteUrl}/wp-json/`, { timeout: { request: REQUEST_TIMEOUT_MS } }).json());
     }
     catch (error) {
         return {
@@ -57,7 +58,7 @@ async function detectWpVersion(siteUrl) {
     ];
     for (const { pattern, url } of sources) {
         try {
-            const body = await got.get(url, { timeout: { request: REQUEST_TIMEOUT_MS } }).text();
+            const body = await withSpinner(`Checking ${siteUrl}`, async () => got.get(url, { timeout: { request: REQUEST_TIMEOUT_MS } }).text());
             const version = pattern.exec(body)?.[1];
             if (version)
                 return version;

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

@@ -3,7 +3,7 @@
  */
 export interface LoopressGlobalConfiguration {
     /**
-     * Pointer to the currently active project and environment, or null if none is selected.
+     * Pointer to the currently active project, or null if none is selected. The environment is not stored: commands use --env, else the project's "local" environment, else its only one.
      */
     currentProject: null | CurrentProjectPointer;
     /**
@@ -15,10 +15,6 @@ export interface LoopressGlobalConfiguration {
     telemetry?: TelemetryConfig;
 }
 export interface CurrentProjectPointer {
-    /**
-     * Name of the currently active environment.
-     */
-    env: string;
     /**
      * Id of the currently active project.
      */

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

@@ -15,10 +15,6 @@ export interface LoopressProjectConfiguration {
      * Directory where ACF field groups, post types, taxonomies and options pages are read from and written to, relative to rootDir.
      */
     acfDir?: string;
-    /**
-     * Directory where SEO settings, post meta, and redirects (RankMath and Yoast SEO, whichever is active) are read from and written to, relative to rootDir.
-     */
-    seoDir?: string;
     /**
      * Directory where forms (WPForms today) are read from and written to, relative to rootDir.
      */
@@ -47,10 +43,38 @@ export interface LoopressProjectConfiguration {
      * Directory where block template parts (one <slug>.html per part, written to the Loopress child theme of the active block theme) are read from, relative to rootDir.
      */
     partDir?: string;
+    /**
+     * Directory of the theme's global CSS, relative to rootDir. Its style.css is the entry: it @imports the other files, bundled into the style.css of the Loopress child theme and loaded on every page.
+     */
+    cssDir?: string;
+    /**
+     * Directory of per-block CSS (one <namespace>/<block>.css per block, e.g. core/button.css), relative to rootDir. Each file is bundled into the Loopress child theme and only loaded on pages that render that block.
+     */
+    blockCssDir?: string;
     /**
      * 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;
+    /**
+     * 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.
+     */
+    cptDir?: string;
+    /**
+     * Directory where taxonomies (one JSON file of register_taxonomy() arguments plus "object_type" per taxonomy, named <slug>.json) are read from and written to, relative to rootDir.
+     */
+    taxonomyDir?: string;
+    /**
+     * Directory where user roles (one JSON file of "name" and "capabilities" per role, named <slug>.json) are read from and written to, relative to rootDir.
+     */
+    roleDir?: string;
+    /**
+     * Directory where block patterns (one <slug>.html of block markup per pattern, registered as loopress/<slug>) are read from and written to, relative to rootDir.
+     */
+    patternDir?: string;
+    /**
+     * Directory where post meta keys (one JSON file per post type, named <post-type>.json, mapping each meta key to its register_post_meta() arguments) are read from and written to, relative to rootDir.
+     */
+    metaDir?: string;
     /**
      * Directory where nav menus (one JSON file per menu, plus menu-locations.json for the active theme's menu locations) are read from and written to, relative to rootDir.
      */

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/composer.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import writeFileAtomic from 'write-file-atomic';
+import { withSpinner } from '../lib/spinner.js';
 import { isExactVersion } from './version.js';
 // Why pullIntoComposerJson skips a plugin it can't install: premium or custom, not on WPackagist.
 export const NOT_ON_WORDPRESS_ORG = 'not on WordPress.org';
@@ -44,7 +45,7 @@ async function isOnWordPressOrg(kind, slug) {
         'Loopress only adds packages WPackagist can serve. Retry once api.wordpress.org is reachable.');
     let response;
     try {
-        response = await fetch(url);
+        response = await withSpinner(`Checking WordPress.org for ${slug}`, async () => fetch(url));
     }
     catch (error) {
         throw fail(`network error: ${error.message}`);

package/dist/utils/declared-type-format.d.ts

@@ -0,0 +1,52 @@
+import { type ResourceDirKind } from './resource-dirs.js';
+export type DeclaredTypeSpec = {
+    arrayArgs: Record<string, unknown[]>;
+    checkArgs?: (args: DeclaredArgs) => void;
+    cliName: 'cpt' | 'meta' | 'pattern' | 'role' | 'taxonomy';
+    codeArgs: string[];
+    dir: string;
+    dirKind: ResourceDirKind;
+    endpoint: string;
+    file?: {
+        extension: string;
+        format(args: DeclaredArgs): string;
+        parse(slug: string, raw: string): DeclaredArgs;
+    };
+    noun: string;
+    plural: string;
+    registeredEndpoint: string;
+    registerFunction: string;
+    slugMaxLength: number;
+    termArgs: string[];
+};
+export declare const CPT_SPEC: DeclaredTypeSpec;
+export declare const TAXONOMY_SPEC: DeclaredTypeSpec;
+export declare const META_SPEC: DeclaredTypeSpec;
+export declare const ROLE_SPEC: DeclaredTypeSpec;
+export declare function parsePatternFile(slug: string, raw: string): DeclaredArgs;
+export declare function formatPatternFile(args: DeclaredArgs): string;
+export declare const PATTERN_SPEC: DeclaredTypeSpec;
+export declare function fileExtension(spec: DeclaredTypeSpec): string;
+export declare function parseDeclaredFile(spec: DeclaredTypeSpec, filePath: string, raw: string): {
+    args: DeclaredArgs;
+    slug: string;
+};
+export declare function formatDeclaredFile(spec: DeclaredTypeSpec, args: DeclaredArgs): string;
+export declare function itemEndpoint(spec: DeclaredTypeSpec, slug: string): string;
+export type DeclaredArgs = Record<string, unknown>;
+export type RemoteDeclaredType = {
+    args: DeclaredArgs;
+    revision: string;
+    slug: string;
+};
+export type RegisteredItem = {
+    conflict: boolean;
+    count: number;
+    label: string;
+    managed: boolean;
+    objectTypes?: string[];
+    slug: string;
+    source: 'acf' | 'cptui' | 'loopress' | 'other' | 'wordpress';
+};
+export declare function parseDeclaredArgs(raw: string): DeclaredArgs;
+export declare function declaredFileChecker(spec: DeclaredTypeSpec): (raw: string, filePath: string) => void;