@loopress/cli 0.32.2 → 0.34.0

package/dist/lib/wp-client.js

@@ -1,5 +1,6 @@
-import got from 'got';
+import got, {} from 'got';
 import { Buffer } from 'node:buffer';
+import { causeOf, errorCode, isRecord } from './narrow.js';
 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
@@ -30,11 +31,11 @@ export function assertSecureSiteUrl(siteUrl, environmentName) {
  * Paths are relative to `<site>/wp-json/`, e.g. `loopress/v1/snippets` or `wp/v2/plugins`.
  */
 export class WpClient {
-    siteUrl;
     client;
+    siteUrl;
     constructor(siteUrl, token, environmentName) {
-        this.siteUrl = siteUrl;
         assertSecureSiteUrl(siteUrl, environmentName);
+        this.siteUrl = siteUrl;
         this.client = got.extend({
             headers: { Authorization: `Basic ${Buffer.from(token).toString('base64')}` },
             prefixUrl: `${siteUrl}/wp-json`,
@@ -83,6 +84,8 @@ export class WpClient {
         const timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS;
         try {
             const response = await withSpinner(`Waiting for ${new URL(this.siteUrl).host}`, async () => this.client(path, { json, method, timeout: { request: timeoutMs } }));
+            // The REST contract boundary: each endpoint's shape is the caller's `T`, not checked here.
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- see above
             return (response.body ? JSON.parse(response.body) : undefined);
         }
         catch (error) {
@@ -91,95 +94,97 @@ export class WpClient {
     }
 }
 export function isNotFoundError(error) {
-    const cause = error?.cause;
-    return cause?.response?.statusCode === 404;
+    return responseOf(causeOf(error)).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;
+    return responseOf(causeOf(error)).statusCode === 403;
+}
+// WordPress core answers the authenticated request with this `code` when Application
+// Passwords are turned off for the user (a security plugin, `wp_is_application_passwords_available`
+// filter or the user's role), as opposed to `incorrect_password`/`invalid_username` for bad credentials.
+export function isApplicationPasswordsDisabled(error) {
+    return parseBody(responseOf(causeOf(error)).body).code === 'application_passwords_disabled_for_user';
 }
 // 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
 // installed or predates the feature, which callers must still surface normally.
 export function isApplicative404(error, marker) {
-    if (!isNotFoundError(error))
-        return false;
-    const body = error.cause?.response?.body;
-    if (!body)
-        return false;
-    try {
-        return JSON.parse(body).error === marker;
-    }
-    catch {
-        return false;
-    }
+    return isNotFoundError(error) && parseBody(responseOf(causeOf(error)).body).error === marker;
 }
 // A 409 a Loopress controller tags with a `code`, for a refusal the CLI can act on (e.g.
 // `loopress_page_not_managed`, which `lps page push` offers to take over).
 export function isConflictCode(error, code) {
-    const response = error?.cause?.response;
-    if (response?.statusCode !== 409 || !response.body)
-        return false;
-    try {
-        return JSON.parse(response.body).code === code;
-    }
-    catch {
-        return false;
-    }
+    const { body, statusCode } = responseOf(causeOf(error));
+    return statusCode === 409 && parseBody(body).code === code;
 }
 export function isTimeoutError(error) {
-    const cause = error?.cause;
-    return cause?.name === 'TimeoutError';
+    const cause = causeOf(error);
+    return isRecord(cause) && cause.name === 'TimeoutError';
 }
 // WordPress core answers 400 with this `code` when `?page=N` is past the last page of a
 // collection, which is how `WpClient.getAll` knows it has walked them all.
 export function isInvalidPageNumber(error) {
-    const body = error.cause?.response?.body;
+    return parseBody(responseOf(causeOf(error)).body).code === 'rest_post_invalid_page_number';
+}
+// The HTTP response a got error carries, read structurally so a mocked error reads the same.
+export function responseOf(error) {
+    const response = isRecord(error) ? error.response : undefined;
+    if (!isRecord(response))
+        return {};
+    return {
+        body: typeof response.body === 'string' ? response.body : undefined,
+        statusCode: typeof response.statusCode === 'number' ? response.statusCode : undefined,
+    };
+}
+// A response body's top-level JSON fields, or none when it isn't JSON.
+export function parseBody(body) {
     if (!body)
-        return false;
+        return {};
     try {
-        return JSON.parse(body).code === 'rest_post_invalid_page_number';
+        const parsed = JSON.parse(body);
+        return isRecord(parsed) ? parsed : {};
     }
     catch {
-        return false;
+        return {};
     }
 }
 export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
-    const err = error;
-    const status = err.response?.statusCode;
+    const { body, statusCode: status } = responseOf(error);
     if (status === 401 || status === 403) {
         // A Loopress controller's own `{"error": ...}` on a 403 is a deliberate refusal of this one
         // request (e.g. OptionsController protecting a secret-looking option), not bad credentials:
         // pointing at `lps project config` there sends the user the wrong way. WordPress core's own
         // auth failures use `{code, message}` instead and keep the credentials hint.
-        const refusal = extractLoopressError(err.response?.body);
+        const refusal = extractLoopressError(body);
         if (refusal)
             return `Request refused (${status}) on ${url}: ${refusal}`;
         return `Authentication failed (${status}) on ${url}. Check your credentials with \`lps project config\`.`;
     }
     if (status === 404) {
-        const reason = extractServerErrorMessage(err.response?.body);
+        const reason = extractServerErrorMessage(body);
         return reason
             ? `Request failed (404) on ${url}: ${reason}`
             : `Endpoint not found (404) on ${url}. Is the required plugin installed and up to date on the site?`;
     }
     if (status !== undefined) {
-        const reason = extractServerErrorMessage(err.response?.body);
+        const reason = extractServerErrorMessage(body);
         return reason ? `Request failed (${status}) on ${url}: ${reason}` : `Request failed (${status}) on ${url}.`;
     }
-    if (err.name === 'TimeoutError') {
+    if (isRecord(error) && error.name === 'TimeoutError') {
         return `Request timed out after ${timeoutMs / 1000}s on ${url}. Is the site reachable?`;
     }
-    const reason = err.code ? NETWORK_ERROR_HINTS[err.code] : undefined;
+    const code = errorCode(error);
+    const reason = code ? NETWORK_ERROR_HINTS[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 message = isRecord(error) && typeof error.message === 'string' ? error.message : '';
+    return `Request to ${url} failed: ${message || (code ?? String(error))}`;
 }
 const NETWORK_ERROR_HINTS = {
     ECONNREFUSED: 'connection refused, the site may be down',
@@ -188,15 +193,8 @@ const NETWORK_ERROR_HINTS = {
     ETIMEDOUT: 'connection timed out',
 };
 function extractLoopressError(body) {
-    if (!body)
-        return undefined;
-    try {
-        const { error } = JSON.parse(body);
-        return typeof error === 'string' && error.trim() ? decodeEntities(error) : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    const { error } = parseBody(body);
+    return typeof error === 'string' && error.trim() ? decodeEntities(error) : undefined;
 }
 // Plugin exception messages go through esc_html() (WordPress coding standards require it for
 // anything thrown), so quotes and ampersands reach the JSON body as entities. They're meant for
@@ -219,24 +217,17 @@ function decodeEntities(text) {
 // specifically so a caller that only reads `error` doesn't see it, which is exactly what this
 // function used to do, hiding the one piece of text that actually explains the failure.
 function extractServerErrorMessage(body) {
-    if (!body)
+    const parsed = parseBody(body);
+    // WP core's own generic body for a route it never registered (e.g. a plugin too old to
+    // expose this endpoint yet) is never more useful than the "is the plugin up to date?"
+    // fallback below; surfacing it verbatim buries a version-skew mismatch behind text that
+    // reads like the endpoint doesn't exist at all, pointing the user in the wrong direction.
+    if (parsed.code === 'rest_no_route')
         return undefined;
-    try {
-        const parsed = JSON.parse(body);
-        // WP core's own generic body for a route it never registered (e.g. a plugin too old to
-        // expose this endpoint yet) is never more useful than the "is the plugin up to date?"
-        // fallback below; surfacing it verbatim buries a version-skew mismatch behind text that
-        // reads like the endpoint doesn't exist at all, pointing the user in the wrong direction.
-        if (parsed.code === 'rest_no_route')
-            return undefined;
-        const reason = parsed.error ?? parsed.message;
-        const summary = typeof reason === 'string' && reason.trim() ? decodeEntities(reason) : undefined;
-        const detail = typeof parsed.output === 'string' && parsed.output.trim() ? parsed.output.trim() : undefined;
-        if (summary && detail)
-            return `${summary}\n${detail}`;
-        return summary ?? detail;
-    }
-    catch {
-        return undefined;
-    }
+    const reason = parsed.error ?? parsed.message;
+    const summary = typeof reason === 'string' && reason.trim() ? decodeEntities(reason) : undefined;
+    const detail = typeof parsed.output === 'string' && parsed.output.trim() ? parsed.output.trim() : undefined;
+    if (summary && detail)
+        return `${summary}\n${detail}`;
+    return summary ?? detail;
 }

package/dist/lib/wp-site-diagnostic.js

@@ -1,4 +1,5 @@
 import got from 'got';
+import { errorMessage, isRecord } from './narrow.js';
 import { withSpinner } from './spinner.js';
 export const REQUEST_TIMEOUT_MS = 10_000;
 /**
@@ -28,10 +29,10 @@ export async function diagnoseWpSite(siteUrl) {
     catch (error) {
         return {
             ok: false,
-            reason: `Could not reach the WordPress REST API at ${siteUrl}/wp-json/. The site may be unreachable, or a security plugin may be blocking it. (${describe(error)})`,
+            reason: `Could not reach the WordPress REST API at ${siteUrl}/wp-json/. The site may be unreachable, or a security plugin may be blocking it. (${errorMessage(error)})`,
         };
     }
-    if (!index?.authentication?.['application-passwords']) {
+    if (!isRecord(index?.authentication?.['application-passwords'])) {
         return {
             ok: false,
             reason: `Application Passwords are not available on ${siteUrl}. The site may be older than WordPress 5.6, require HTTPS, or have the feature disabled by a plugin or filter.`,
@@ -69,6 +70,3 @@ async function detectWpVersion(siteUrl) {
     }
     return undefined;
 }
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}

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

@@ -54,7 +54,7 @@ export interface EnvironmentConfig {
      */
     name: string;
     /**
-     * API token used to authenticate against this environment.
+     * WordPress Application Password credentials for this environment, as "user:password". Not the Loopress account token.
      */
     token?: string;
     /**

package/dist/types/plugin.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 export type InstalledPlugin = {
     active: boolean;
     file: string;
@@ -12,11 +13,12 @@ export type WpNativePlugin = {
     status: 'active' | 'inactive' | 'network-active';
     version: string;
 };
-export type PluginPin = string | {
-    active?: boolean;
-    version: string;
-};
+export declare const PLUGIN_PIN: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    active: z.ZodExactOptional<z.ZodBoolean>;
+    version: z.ZodString;
+}, z.core.$strip>]>;
+export type PluginPin = z.infer<typeof PLUGIN_PIN>;
 export type PluginManifest = Record<string, PluginPin>;
 export declare const pinVersion: (pin: PluginPin) => string;
-export declare const pinActive: (pin: PluginPin) => boolean;
+export declare const pinActive: (pin: PluginPin | undefined) => boolean;
 export declare const pinVersions: (manifest: PluginManifest) => Record<string, string>;

package/dist/types/plugin.js

@@ -1,4 +1,9 @@
+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() })]);
 export const pinVersion = (pin) => (typeof pin === 'string' ? pin : pin.version);
-export const pinActive = (pin) => typeof pin === 'string' || pin.active !== false;
+// 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;
 // The version-only view the Composer sync endpoint expects.
 export const pinVersions = (manifest) => Object.fromEntries(Object.entries(manifest).map(([slug, pin]) => [slug, pinVersion(pin)]));

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

@@ -23,14 +23,18 @@ export interface LoopressProjectConfiguration {
      * Directory where custom API route files are read from and written to, relative to rootDir.
      */
     apiDir?: string;
+    /**
+     * Directory of dynamic blocks, one <slug>/ folder holding block.json and render.php, registered as loopress/<slug>, relative to rootDir.
+     */
+    blockDir?: string;
     /**
      * 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.
      */
@@ -54,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.
      */
@@ -82,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.
      */
@@ -103,7 +107,22 @@ export interface LoopressProjectConfiguration {
         };
     };
     /**
-     * WordPress.org themes managed by Loopress, installed via Composer + WPackagist on the site. Keys are theme slugs; values are an exact version or "latest". Loopress manages installed theme versions only, it never switches the active theme. Ignored when a composer.json exists in rootDir.
+     * 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.
+     */
+    activateChildTheme?: boolean;
+    /**
+     * WordPress.org themes managed by Loopress, installed via Composer + WPackagist on the site. Keys are theme slugs; values are an exact version or "latest". Loopress manages installed theme versions only, it never switches the active theme (see activateChildTheme and `lps theme activate`). Ignored when a composer.json exists in rootDir.
      */
     themes?: {
         [k: string]: string;

package/dist/types/snippet.d.ts

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

package/dist/types/snippet.js

@@ -1 +1 @@
-export {};
+import {} from '../utils/snippet-format.js';

package/dist/utils/acf-format.js

@@ -1,4 +1,5 @@
 import { isDeepStrictEqual } from 'node:util';
+import { isRecord } from '../lib/narrow.js';
 export const ACF_OBJECT_TYPES = ['field-groups', 'post-types', 'taxonomies', 'options-pages'];
 export function acfEndpoint(type) {
     return `loopress/v1/acf/${type}`;
@@ -23,21 +24,23 @@ export function getAcfKey(data) {
     return typeof data.key === 'string' && data.key.trim() !== '' ? data.key : null;
 }
 function topLevelFields(group) {
-    const fields = group?.fields;
+    const fields = isRecord(group) ? group.fields : undefined;
     const byKey = new Map();
     for (const field of Array.isArray(fields) ? fields : []) {
-        if (typeof field?.key === 'string')
+        if (isRecord(field) && typeof field.key === 'string')
             byKey.set(field.key, field);
     }
     return byKey;
 }
+function label(field) {
+    return typeof field.name === 'string' && field.name !== '' ? field.name : String(field.key);
+}
 // A changed field group's top-level fields, matched by `key` and named by `name` (a repeater's
 // sub-field change shows as its parent changing). Only for the dry-run preview: the push itself
 // always sends the whole group.
 export function acfFieldChanges(before, after) {
     const old = topLevelFields(before);
     const next = topLevelFields(after);
-    const label = (field) => (typeof field.name === 'string' && field.name !== '' ? field.name : String(field.key));
     const changes = { added: [], changed: [], removed: [] };
     for (const [key, field] of next) {
         if (!old.has(key))

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

@@ -0,0 +1,29 @@
+export declare const BLOCKS_ENDPOINT = "loopress/v1/block-files";
+export declare const BLOCK_FILES: readonly ["block.json", "render.php", "style.css", "view.js"];
+export declare const BLOCK_SLUG: RegExp;
+export type BlockFiles = Record<string, string>;
+export type LocalBlock = {
+    files: BlockFiles;
+    slug: string;
+};
+export type BlockProblem = {
+    file: string;
+    message: string;
+};
+export declare function blockProblems(slug: string, files: BlockFiles): string[];
+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>;
+export type RemoteBlock = LocalBlock & {
+    error?: string;
+    runtimeError?: {
+        at: string;
+        message: string;
+    };
+};

package/dist/utils/block-format.js

@@ -0,0 +1,109 @@
+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).
+export const BLOCKS_ENDPOINT = 'loopress/v1/block-files';
+// The only files a block folder may hold, mirrors BlocksDirectory::FILES.
+export const BLOCK_FILES = ['block.json', 'render.php', 'style.css', 'view.js'];
+// WordPress's block name segment rule, capped like the plugin's slug pattern.
+export const BLOCK_SLUG = /^[a-z][a-z0-9-]{0,63}$/;
+// Every `file:./x` path a block.json field points at (style, viewScriptModule, ...), top level
+// only, as a string or an array of strings, like WordPress reads them.
+function referencedFiles(metadata) {
+    return Object.values(metadata)
+        .flatMap((value) => (Array.isArray(value) ? value : [value]))
+        .filter((value) => typeof value === 'string' && value.startsWith('file:'))
+        .map((value) => value.slice('file:'.length).replace(/^\.\//, ''));
+}
+// Local checks `lps block push` and `lps validate` share. The site checks the same again,
+// plus render.php's syntax.
+export function blockProblems(slug, files) {
+    if (!BLOCK_SLUG.test(slug))
+        return ['the folder name must be lowercase letters, digits and hyphens, starting with a letter'];
+    const problems = [];
+    for (const name of Object.keys(files)) {
+        if (!BLOCK_FILES.includes(name))
+            problems.push(`${name} is not a block file, a block folder holds only ${BLOCK_FILES.join(', ')}`);
+    }
+    if (files['render.php'] === undefined)
+        problems.push('render.php is missing');
+    const raw = files['block.json'];
+    if (raw === undefined)
+        return [...problems, 'block.json is missing'];
+    let metadata;
+    try {
+        metadata = JSON.parse(raw);
+    }
+    catch {
+        return [...problems, 'block.json is not valid JSON'];
+    }
+    if (!isRecord(metadata) || Array.isArray(metadata))
+        return [...problems, 'block.json is not a JSON object'];
+    if (metadata.name !== `loopress/${slug}`)
+        problems.push(`block.json "name" must be "loopress/${slug}"`);
+    for (const file of referencedFiles(metadata)) {
+        if (files[file] === undefined)
+            problems.push(`block.json references file:./${file}, which is not in the folder`);
+    }
+    return problems;
+}
+// Every blocks/<slug>/ folder with its files. Unknown files are read too, so blockProblems()
+// reports them instead of push silently dropping them.
+export async function readLocalBlocks(dir) {
+    let entries;
+    try {
+        entries = withoutExcluded(dir, await readdir(dir, { withFileTypes: true }), (entry) => entry.name);
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return { blocks: [], problems: [] };
+        throw error;
+    }
+    const blocks = [];
+    const problems = [];
+    for (const entry of entries.filter((candidate) => candidate.isDirectory()).toSorted((a, b) => a.name.localeCompare(b.name))) {
+        const slug = entry.name;
+        const files = {};
+        for (const file of await readdir(join(dir, slug), { withFileTypes: true })) {
+            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 });
+        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');
+}
+// A block from the site or a snapshot names a folder and files on disk: anything but a valid
+// slug and the known file names could write or delete outside blocks/.
+export function assertSafeBlock(block) {
+    const unsafe = !BLOCK_SLUG.test(block.slug) || Object.keys(block.files).some((name) => !BLOCK_FILES.includes(name));
+    if (unsafe)
+        throw new Error(`Refusing block "${block.slug}": invalid slug or file name (${Object.keys(block.files).join(', ')})`);
+}
+export async function writeBlock(dir, block) {
+    assertSafeBlock(block);
+    await mkdir(join(dir, block.slug), { recursive: true });
+    for (const [name, content] of Object.entries(block.files))
+        await writeFile(join(dir, block.slug, name), content);
+}

package/dist/utils/composer.d.ts

@@ -1,21 +1,13 @@
+import { z } from 'zod';
 import { type SyncIntent } from './plugin-sync.js';
 import { type MergeResult } from './plugins.js';
 export declare const NOT_ON_WORDPRESS_ORG = "not on WordPress.org";
-export type ComposerJson = {
-    config?: {
-        'allow-plugins'?: Record<string, boolean>;
-    };
-    extra?: {
-        'installer-paths'?: Record<string, string[]>;
-    };
-    name?: string;
-    repositories?: Array<{
-        type: string;
-        url: string;
-    }>;
-    require?: Record<string, string>;
-    'require-dev'?: Record<string, string>;
-};
+export declare const COMPOSER_JSON: z.ZodObject<{
+    require: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    'require-dev': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$loose>;
+export type ComposerJson = z.infer<typeof COMPOSER_JSON>;
+export declare function parseComposerJson(raw: string): ComposerJson;
 export declare function readComposerJson(): Promise<ComposerJson | null>;
 export declare function readComposerLock(): Promise<null | string>;
 export declare function getComposerManagedSlugs(composerJson: ComposerJson): string[];