@loopress/cli 0.29.0 → 0.31.0

package/dist/utils/declared-type-format.js

@@ -0,0 +1,233 @@
+import { basename } from 'node:path';
+import { parseHtmlHeader, titleFromSlug } from './page-format.js';
+export const CPT_SPEC = {
+    arrayArgs: { capabilities: [], labels: [], rewrite: [true, false], supports: [false], taxonomies: [], template: [] },
+    cliName: 'cpt',
+    codeArgs: ['register_meta_box_cb', 'rest_controller_class', 'autosave_rest_controller_class', 'revisions_rest_controller_class'],
+    dir: 'cpt',
+    dirKind: 'cpt',
+    endpoint: 'loopress/v1/post-types',
+    noun: 'post type',
+    plural: 'post types',
+    registeredEndpoint: 'loopress/v1/registered-post-types',
+    registerFunction: 'register_post_type()',
+    slugMaxLength: 20,
+    termArgs: [],
+};
+// `object_type` is the one key that isn't a register_taxonomy() argument: its second parameter,
+// the post types the taxonomy attaches to. Kept in the same file, split off by the plugin.
+export const TAXONOMY_SPEC = {
+    arrayArgs: { capabilities: [], labels: [], object_type: [], rewrite: [true, false] },
+    cliName: 'taxonomy',
+    codeArgs: ['meta_box_cb', 'meta_box_sanitize_cb', 'update_count_callback', 'rest_controller_class'],
+    dir: 'taxonomies',
+    dirKind: 'taxonomy',
+    endpoint: 'loopress/v1/taxonomies',
+    noun: 'taxonomy',
+    plural: 'taxonomies',
+    registeredEndpoint: 'loopress/v1/registered-taxonomies',
+    registerFunction: 'register_taxonomy()',
+    slugMaxLength: 32,
+    // register_taxonomy() creates the default term when it doesn't exist yet.
+    termArgs: ['default_term'],
+};
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// register_post_meta()'s `type` values, each with the check its `default` must pass.
+const META_TYPES = {
+    array: Array.isArray,
+    boolean: (value) => typeof value === 'boolean',
+    integer: Number.isSafeInteger,
+    number: (value) => typeof value === 'number',
+    object: isObject,
+    string: (value) => typeof value === 'string',
+};
+function checkMetaRest(key, type, rest) {
+    if (typeof rest !== 'boolean' && !isObject(rest))
+        throw new Error(`"${key}": "show_in_rest" must be true, false or an object`);
+    // WordPress calls it with each value on every REST read (WP_REST_Meta_Fields).
+    if (isObject(rest) && Object.hasOwn(rest, 'prepare_callback')) {
+        throw new Error(`"${key}": "show_in_rest.prepare_callback" runs PHP code, use a hook instead of a file for it`);
+    }
+    // WordPress silently leaves an array or object key out of REST without a schema.
+    if (rest !== false && (type === 'array' || type === 'object') && !(isObject(rest) && isObject(rest.schema))) {
+        throw new Error(`"${key}": a ${type} exposed in REST needs "show_in_rest": { "schema": {...} }`);
+    }
+}
+function checkMetaKey(key, meta) {
+    if (!/^[a-zA-Z0-9_-]{1,255}$/.test(key))
+        throw new Error(`"${key}" is not a valid meta key: 1 to 255 letters, digits, "_" or "-"`);
+    if (!isObject(meta))
+        throw new Error(`"${key}" must be a JSON object of register_post_meta() arguments`);
+    const code = ['sanitize_callback', 'auth_callback'].find((name) => Object.hasOwn(meta, name));
+    if (code)
+        throw new Error(`"${key}": "${code}" runs PHP code, use a hook instead of a file for it`);
+    const { type } = meta;
+    if (typeof type !== 'string' || !Object.hasOwn(META_TYPES, type)) {
+        throw new Error(`"${key}": "type" must be one of ${Object.keys(META_TYPES).join(', ')}`);
+    }
+    if (Object.hasOwn(meta, 'single') && typeof meta.single !== 'boolean')
+        throw new Error(`"${key}": "single" must be true or false`);
+    checkMetaRest(key, type, meta.show_in_rest ?? false);
+    if (Object.hasOwn(meta, 'default') && !META_TYPES[type](meta.default))
+        throw new Error(`"${key}": "default" must be a ${type}`);
+}
+// Same checks as the plugin's PostMetaService::assertArgs(): the file is `key => register_post_meta()
+// arguments`, so the code and type checks are one level deeper than for post types.
+function checkMetaArgs(args) {
+    for (const [key, meta] of Object.entries(args))
+        checkMetaKey(key, meta);
+}
+// The file name is the post type (`post` and `page` included), the keys are meta keys. Only the
+// keys are declared, never their values.
+export const META_SPEC = {
+    arrayArgs: {},
+    checkArgs: checkMetaArgs,
+    cliName: 'meta',
+    codeArgs: [],
+    dir: 'meta',
+    dirKind: 'meta',
+    endpoint: 'loopress/v1/post-meta',
+    noun: 'post meta',
+    plural: 'post meta',
+    registeredEndpoint: 'loopress/v1/registered-post-meta',
+    registerFunction: 'register_post_meta()',
+    slugMaxLength: 20,
+    termArgs: [],
+};
+// Same checks as the plugin's RoleService::assertArgs().
+function checkRoleArgs(args) {
+    if (typeof args.name !== 'string' || args.name.trim() === '')
+        throw new Error('"name" must be a non-empty string');
+    const capabilities = args.capabilities ?? {};
+    if (!isObject(capabilities) || Object.values(capabilities).some((granted) => typeof granted !== 'boolean')) {
+        throw new Error('"capabilities" must map each capability name to true or false');
+    }
+}
+// `{"name": ..., "capabilities": {cap: bool}}`, added in memory on every request, never written
+// to the roles option. Built-in roles are refused by the plugin.
+export const ROLE_SPEC = {
+    arrayArgs: { capabilities: [] },
+    checkArgs: checkRoleArgs,
+    cliName: 'role',
+    codeArgs: [],
+    dir: 'roles',
+    dirKind: 'role',
+    endpoint: 'loopress/v1/roles',
+    noun: 'role',
+    plural: 'roles',
+    registeredEndpoint: 'loopress/v1/registered-roles',
+    registerFunction: 'add_role()',
+    slugMaxLength: 50,
+    termArgs: [],
+};
+// Header key => register_block_pattern() property, and how its text is read.
+const PATTERN_HEADER = {
+    'block-types': { key: 'blockTypes', type: 'list' },
+    categories: { key: 'categories', type: 'list' },
+    description: { key: 'description', type: 'text' },
+    inserter: { key: 'inserter', type: 'boolean' },
+    keywords: { key: 'keywords', type: 'list' },
+    'post-types': { key: 'postTypes', type: 'list' },
+    'template-types': { key: 'templateTypes', type: 'list' },
+    title: { key: 'title', type: 'text' },
+    'viewport-width': { key: 'viewportWidth', type: 'integer' },
+};
+function readPatternValue(header, type, value) {
+    if (type === 'list')
+        return value.split(',').map((item) => item.trim()).filter(Boolean);
+    if (type === 'boolean') {
+        if (value !== 'true' && value !== 'false')
+            throw new Error(`"${header}" must be "true" or "false", got "${value}"`);
+        return value === 'true';
+    }
+    if (type === 'integer') {
+        if (!/^\d+$/.test(value))
+            throw new Error(`"${header}" must be a whole number, got "${value}"`);
+        return Number(value);
+    }
+    return value;
+}
+// A pattern file is its block markup, opened by the same `key: value` comment header as a page.
+export function parsePatternFile(slug, raw) {
+    const { body, meta } = parseHtmlHeader(raw, Object.keys(PATTERN_HEADER));
+    const args = { title: titleFromSlug(slug) };
+    for (const [header, value] of Object.entries(meta)) {
+        const { key, type } = PATTERN_HEADER[header];
+        args[key] = readPatternValue(header, type, value);
+    }
+    args.content = body;
+    return args;
+}
+export function formatPatternFile(args) {
+    const lines = Object.entries(PATTERN_HEADER)
+        .filter(([, { key }]) => args[key] !== undefined)
+        .map(([header, { key }]) => `${header}: ${Array.isArray(args[key]) ? args[key].join(', ') : String(args[key])}`);
+    return `<!--\n${lines.join('\n')}\n-->\n${typeof args.content === 'string' ? args.content : ''}`;
+}
+function checkPatternArgs(args) {
+    if (typeof args.title !== 'string' || args.title.trim() === '')
+        throw new Error('"title" must be a non-empty string');
+}
+// Registered as `loopress/<slug>`, referenced with `<!-- wp:pattern {"slug":"loopress/<slug>"} /-->`.
+export const PATTERN_SPEC = {
+    arrayArgs: { blockTypes: [], categories: [], keywords: [], postTypes: [], templateTypes: [] },
+    checkArgs: checkPatternArgs,
+    cliName: 'pattern',
+    codeArgs: ['filePath'],
+    dir: 'patterns',
+    dirKind: 'pattern',
+    endpoint: 'loopress/v1/patterns',
+    file: { extension: '.html', format: formatPatternFile, parse: parsePatternFile },
+    noun: 'pattern',
+    plural: 'patterns',
+    registeredEndpoint: 'loopress/v1/registered-patterns',
+    registerFunction: 'register_block_pattern()',
+    slugMaxLength: 100,
+    termArgs: [],
+};
+export function fileExtension(spec) {
+    return spec.file?.extension ?? '.json';
+}
+export function parseDeclaredFile(spec, filePath, raw) {
+    const slug = basename(filePath, fileExtension(spec));
+    return { args: spec.file ? spec.file.parse(slug, raw) : parseDeclaredArgs(raw), slug };
+}
+export function formatDeclaredFile(spec, args) {
+    return spec.file ? spec.file.format(args) : JSON.stringify(args, null, 2) + '\n';
+}
+export function itemEndpoint(spec, slug) {
+    return `${spec.endpoint}/${encodeURIComponent(slug)}`;
+}
+export function parseDeclaredArgs(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('not a JSON object of arguments');
+    }
+    return parsed;
+}
+// `lps validate`'s check of one file: the file name is a valid slug, array arguments are arrays,
+// and no argument is code.
+export function declaredFileChecker(spec) {
+    const slugPattern = new RegExp(`^[a-z0-9_-]{1,${spec.slugMaxLength}}$`);
+    return (raw, filePath) => {
+        const slug = basename(filePath, fileExtension(spec));
+        if (!slugPattern.test(slug)) {
+            throw new Error(`"${slug}" is not a valid ${spec.noun} slug: 1 to ${spec.slugMaxLength} lowercase letters, digits, "_" or "-"`);
+        }
+        const { args } = parseDeclaredFile(spec, filePath, raw);
+        for (const [key, alsoAllowed] of Object.entries(spec.arrayArgs)) {
+            const value = args[key];
+            if (Object.hasOwn(args, key) && (typeof value !== 'object' || value === null) && !alsoAllowed.includes(value)) {
+                const or = alsoAllowed.length > 0 ? ' (or ' + alsoAllowed.join(', ') + ')' : '';
+                throw new Error(`"${key}" must be a JSON object or array${or}`);
+            }
+        }
+        const term = spec.termArgs.find((key) => Object.hasOwn(args, key));
+        if (term)
+            throw new Error(`"${term}" creates a term, and Loopress doesn't sync terms: remove it and create the term in wp-admin`);
+        const code = spec.codeArgs.find((key) => Object.hasOwn(args, key));
+        if (code)
+            throw new Error(`"${code}" runs PHP code, use a hook instead of a file for it`);
+        spec.checkArgs?.(args);
+    };
+}

package/dist/utils/resource-dirs.d.ts

@@ -3,15 +3,21 @@ export declare const RESOURCE_DIR_DEFAULTS: {
     readonly acf: "acf";
     readonly api: "api";
     readonly apps: "apps";
+    readonly blockCss: "theme/blocks";
+    readonly cpt: "cpt";
+    readonly css: "theme/css";
     readonly form: "forms";
     readonly hooks: "hooks";
     readonly menu: "menus";
+    readonly meta: "meta";
     readonly options: "options";
     readonly page: "pages";
-    readonly part: "parts";
-    readonly seo: "seo";
+    readonly part: "theme/parts";
+    readonly pattern: "patterns";
+    readonly role: "roles";
     readonly snippets: "snippets";
-    readonly template: "templates";
+    readonly taxonomy: "taxonomies";
+    readonly template: "theme/templates";
     readonly themeStyles: "theme";
 };
 export type ResourceDirKind = keyof typeof RESOURCE_DIR_DEFAULTS;

package/dist/utils/resource-dirs.js

@@ -5,29 +5,41 @@ export const RESOURCE_DIR_DEFAULTS = {
     acf: 'acf',
     api: 'api',
     apps: 'apps',
+    blockCss: 'theme/blocks',
+    cpt: 'cpt',
+    css: 'theme/css',
     form: 'forms',
     hooks: 'hooks',
     menu: 'menus',
+    meta: 'meta',
     options: 'options',
     page: 'pages',
-    part: 'parts',
-    seo: 'seo',
+    part: 'theme/parts',
+    pattern: 'patterns',
+    role: 'roles',
     snippets: 'snippets',
-    template: 'templates',
+    taxonomy: 'taxonomies',
+    template: 'theme/templates',
     themeStyles: 'theme',
 };
 const CONFIG_KEY = {
     acf: 'acfDir',
     api: 'apiDir',
     apps: 'appsDir',
+    blockCss: 'blockCssDir',
+    cpt: 'cptDir',
+    css: 'cssDir',
     form: 'formDir',
     hooks: 'hooksDir',
     menu: 'menuDir',
+    meta: 'metaDir',
     options: 'optionsDir',
     page: 'pageDir',
     part: 'partDir',
-    seo: 'seoDir',
+    pattern: 'patternDir',
+    role: 'roleDir',
     snippets: 'snippetsDir',
+    taxonomy: 'taxonomyDir',
     template: 'templateDir',
     themeStyles: 'themeStylesDir',
 };

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

@@ -21,6 +21,7 @@ export type ChildTheme = {
     parts: Part[];
     stylesheet: string;
     templates: Template[];
+    unknownBlocks?: string[];
 };
 export declare function parseTemplateFile(slug: string, raw: string): Template;
 export declare function parsePartFile(slug: string, raw: string): Part;

package/dist/utils/theme-css.d.ts

@@ -0,0 +1,19 @@
+import { type PageProblem } from './page-format.js';
+export type BlockStyle = {
+    css: string;
+    name: string;
+};
+export type ThemeAsset = {
+    content: string;
+    path: string;
+};
+export type ThemeCss = {
+    assets: ThemeAsset[];
+    blocks: BlockStyle[];
+    style: string;
+};
+export declare const STYLE_ENTRY = "style.css";
+export declare function bundleThemeCss(cssDir: string, blocksDir: string): Promise<{
+    css: ThemeCss;
+    problems: PageProblem[];
+}>;

package/dist/utils/theme-css.js

@@ -0,0 +1,100 @@
+import { build } from 'esbuild';
+import { Buffer } from 'node:buffer';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { extname, join, relative, resolve, sep } from 'node:path';
+// The global stylesheet's entry: it @imports the rest of theme/css/ in cascade order.
+export const STYLE_ENTRY = 'style.css';
+// WordPress's own block name rule (register_block_type): lowercase letters, digits and dashes,
+// starting with a letter, on both sides of the slash.
+const BLOCK_SEGMENT = /^[a-z][a-z0-9-]*$/;
+const ASSET_EXTENSIONS = ['.avif', '.eot', '.gif', '.jpeg', '.jpg', '.otf', '.png', '.svg', '.ttf', '.webp', '.woff', '.woff2'];
+async function listFiles(dir) {
+    try {
+        const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && !entry.name.startsWith('.'))
+            .map((entry) => join(entry.parentPath, entry.name))
+            .toSorted((a, b) => a.localeCompare(b));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+async function readBlockEntries(blocksDir, problems) {
+    const entries = [];
+    for (const file of await listFiles(blocksDir)) {
+        const segments = relative(blocksDir, file).split(sep);
+        const [namespace, block] = [segments[0], segments[1]?.replace(/\.css$/, '')];
+        if (segments.length !== 2 || extname(file) !== '.css' || !BLOCK_SEGMENT.test(namespace) || !BLOCK_SEGMENT.test(block)) {
+            problems.push({ file, message: `must be <namespace>/<block>.css, named after a block (e.g. ${join(blocksDir, 'core', 'button.css')})` });
+            continue;
+        }
+        entries.push({ file, name: `${namespace}/${block}` });
+    }
+    return entries;
+}
+function buildProblems(error) {
+    const { errors } = error;
+    if (!Array.isArray(errors))
+        throw error;
+    return errors.map((message) => ({
+        file: message.location ? `${message.location.file}:${message.location.line}` : 'esbuild',
+        message: message.text,
+    }));
+}
+// Bundles theme/css/style.css and every theme/blocks/<namespace>/<block>.css with esbuild:
+// @import resolved, relative url() copied to assets/ and rewritten, minified. Paths in the result
+// are the child theme's: style.css, blocks/core/button.css, assets/inter-HASH.woff2.
+export async function bundleThemeCss(cssDir, blocksDir) {
+    const problems = [];
+    const empty = { assets: [], blocks: [], style: '' };
+    const styleEntry = join(cssDir, STYLE_ENTRY);
+    const hasStyle = existsSync(styleEntry);
+    if (!hasStyle && (await listFiles(cssDir)).some((file) => extname(file) === '.css')) {
+        problems.push({ file: cssDir, message: `has CSS files but no ${STYLE_ENTRY}, the entry that @imports them: nothing in it would be loaded` });
+    }
+    const blocks = await readBlockEntries(blocksDir, problems);
+    if (problems.length > 0)
+        return { css: empty, problems };
+    const entryPoints = [
+        ...(hasStyle ? [{ in: resolve(styleEntry), out: 'style' }] : []),
+        ...blocks.map((block) => ({ in: resolve(block.file), out: `blocks/${block.name}` })),
+    ];
+    if (entryPoints.length === 0)
+        return { css: empty, problems };
+    // Never written: outdir only anchors the output paths and the relative url() rewrites.
+    const outdir = resolve('/loopress-child');
+    let outputFiles;
+    try {
+        ;
+        ({ outputFiles } = await build({
+            assetNames: 'assets/[name]-[hash]',
+            bundle: true,
+            charset: 'utf8',
+            entryPoints,
+            loader: Object.fromEntries(ASSET_EXTENSIONS.map((extension) => [extension, 'file'])),
+            logLevel: 'silent',
+            minify: true,
+            outdir,
+            write: false,
+        }));
+    }
+    catch (error) {
+        return { css: empty, problems: buildProblems(error) };
+    }
+    const css = { assets: [], blocks: [], style: '' };
+    for (const output of outputFiles) {
+        const path = relative(outdir, output.path).split(sep).join('/');
+        if (path === STYLE_ENTRY)
+            css.style = output.text;
+        else if (path.startsWith('blocks/') && path.endsWith('.css'))
+            css.blocks.push({ css: output.text, name: path.slice('blocks/'.length, -'.css'.length) });
+        else
+            css.assets.push({ content: Buffer.from(output.contents).toString('base64'), path });
+    }
+    css.blocks.sort((a, b) => a.name.localeCompare(b.name));
+    return { css, problems };
+}