@loopress/cli 0.25.0 → 0.27.0

package/dist/lib/validate-local.js

@@ -1,20 +1,25 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { configManager } from '../config/project-config.manager.js';
+import { parseLocalOption } from '../utils/option-format.js';
+import { readLocalPages } from '../utils/page-format.js';
 import { parseType } from '../utils/snippet-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.
-const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir', 'menuDir'];
+// and api routes (`.php`, not JSON) are checked separately, options too (a stricter shape).
+const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir', 'menuDir', 'themeStylesDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
     formDir: 'forms',
     hooksDir: 'hooks',
     menuDir: 'menus',
+    optionsDir: 'options',
+    pageDir: 'pages',
     seoDir: 'seo',
     snippetsDir: 'snippets',
+    themeStylesDir: 'theme',
 };
 // Inspects the local tracked files under `cwd` without contacting WordPress: JSON files parse
 // and have the right shape, snippet sidecars use a known type, `loopress.json` points at a
@@ -35,9 +40,15 @@ export async function validateLocal(cwd) {
     for (const key of JSON_RESOURCE_DIRS) {
         checked += await checkJsonDir(resolve(key), problems);
     }
+    // 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 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');
+    const pages = await readLocalPages(resolve('pageDir'));
+    checked += pages.pages.length + pages.problems.length;
+    problems.push(...pages.problems);
     return { checked, problems, valid: problems.length === 0 };
 }
 // Recursive: both api/ and hooks/ files can live in a nested path-segment directory
@@ -86,15 +97,23 @@ async function checkComposerJson(cwd, problems) {
     }
     return 1;
 }
-async function checkJsonDir(dir, problems) {
-    const files = (await readdirTolerant(dir)).filter((file) => file.endsWith('.json'));
+// 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
+// throws to report a resource-specific problem.
+async function checkJsonDir(dir, problems, shape) {
+    const entries = await readdirTolerant(dir, { recursive: true, withFileTypes: true });
     let checked = 0;
-    for (const file of files) {
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
         checked += 1;
-        const filePath = join(dir, file);
+        // parentPath, not dir: see checkPhpDir.
+        const filePath = join(entry.parentPath, entry.name);
+        const raw = await readFile(filePath, 'utf8');
         let parsed;
         try {
-            parsed = JSON.parse(await readFile(filePath, 'utf8'));
+            parsed = JSON.parse(raw);
         }
         catch (error) {
             problems.push({ file: filePath, message: `not valid JSON: ${error.message}` });
@@ -102,6 +121,13 @@ async function checkJsonDir(dir, problems) {
         }
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
             problems.push({ file: filePath, message: 'expected a JSON object' });
+            continue;
+        }
+        try {
+            shape?.(raw);
+        }
+        catch (error) {
+            problems.push({ file: filePath, message: error.message });
         }
     }
     return checked;

package/dist/lib/wp-client.js

@@ -107,6 +107,13 @@ export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     const err = error;
     const status = err.response?.statusCode;
     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);
+        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) {
@@ -124,6 +131,28 @@ export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     }
     return `Request to ${url} failed: ${err.message ?? String(error)}`;
 }
+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;
+    }
+}
+// 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
+// a terminal here, not an HTML page. `&` last, so """ stays a literal """.
+function decodeEntities(text) {
+    return text
+        .replaceAll('"', '"')
+        .replaceAll(''', "'")
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&amp;', '&');
+}
 // The Loopress plugin's own controllers reply with `{"error": "..."}`; a WP_Error-based
 // core response (e.g. an uncaught fatal formatted by WordPress itself) uses `{"message": "..."}`.
 // Surfacing this is what makes a deliberately clear server-side error (e.g. "Multiple snippet
@@ -131,7 +160,7 @@ export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
 //
 // Some controllers (ComposerController::sync(), notably) pair a short, generic `error` (e.g.
 // "Sync failed.") with the real detail in a separate `output` field (the raw Composer trace),
-// specifically so a caller that only reads `error` doesn't see it — which is exactly what this
+// 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)
@@ -145,7 +174,7 @@ function extractServerErrorMessage(body) {
         if (parsed.code === 'rest_no_route')
             return undefined;
         const reason = parsed.error ?? parsed.message;
-        const summary = typeof reason === 'string' && reason.trim() ? reason : undefined;
+        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}`;

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

@@ -35,6 +35,10 @@ export interface LoopressProjectConfiguration {
      * 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;
+    /**
+     * Directory where static HTML pages (one <slug>.html per WordPress page, managed by Loopress) are read from, relative to rootDir.
+     */
+    pageDir?: 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.
      */

package/dist/utils/loopress-config.d.ts

@@ -2,3 +2,4 @@ import { type LoopressProjectConfiguration } from '../types/project-config.gener
 export type LoopressLocalConfig = LoopressProjectConfiguration;
 export declare function readLocalConfig(): Promise<LoopressLocalConfig>;
 export declare function writeLocalConfig(config: LoopressLocalConfig): Promise<void>;
+export declare function ensureLfGitattributes(): Promise<boolean>;

package/dist/utils/loopress-config.js

@@ -20,3 +20,17 @@ export async function writeLocalConfig(config) {
     const configPath = join(process.cwd(), 'loopress.json');
     await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
 }
+// Git for Windows checks text files out as CRLF by default (core.autocrlf=true), so the same
+// snippet would differ byte for byte between a Windows checkout and what `pull` writes (LF).
+// Pinning LF in the repo keeps synced files identical on every OS. Returns false when the rule
+// is already there, so re-running `lps init` never duplicates it. The rule goes first: in
+// .gitattributes a later line wins, so existing exceptions (`*.bat text eol=crlf`) keep theirs.
+const LF_RULE = '* text=auto eol=lf';
+export async function ensureLfGitattributes() {
+    const path = join(process.cwd(), '.gitattributes');
+    const current = existsSync(path) ? await readFile(path, 'utf8') : '';
+    if (current.split(/\r?\n/).some((line) => line.trim() === LF_RULE))
+        return false;
+    await writeFile(path, `${LF_RULE}\n${current}`, 'utf8');
+    return true;
+}

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

@@ -0,0 +1,31 @@
+export declare const PAGES_ENDPOINT = "loopress/v1/pages";
+export declare const PAGE_SLUG_PATTERN: RegExp;
+export declare const PAGE_STATUSES: readonly ["draft", "publish"];
+export type PageStatus = (typeof PAGE_STATUSES)[number];
+export type Page = {
+    fullWidth: boolean;
+    hideTitle: boolean;
+    html: string;
+    slug: string;
+    status: PageStatus;
+    template: string;
+    title: string;
+};
+export type RemotePage = Page & {
+    link: string;
+};
+export type PushedPage = RemotePage & {
+    frontPage?: 'set' | 'unset';
+};
+export type PageProblem = {
+    file: string;
+    message: string;
+};
+export declare function formatPageProblems(problems: PageProblem[]): string;
+export declare function titleFromSlug(slug: string): string;
+export declare function parsePageFile(slug: string, raw: string): Page;
+export declare function readLocalPages(dir: string): Promise<{
+    pages: Page[];
+    problems: PageProblem[];
+}>;
+export declare function frontPageNote(page: PushedPage): string;

package/dist/utils/page-format.js

@@ -0,0 +1,118 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+export const PAGES_ENDPOINT = 'loopress/v1/pages';
+// Mirrored server-side in PagesController. No leading, trailing or doubled hyphen: WordPress's
+// sanitize_title() would rewrite those, and the page would no longer match its file name.
+export const PAGE_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const PAGE_STATUSES = ['draft', 'publish'];
+const HEADER_KEYS = ['title', 'status', 'full-width', 'hide-title', 'template'];
+function parseBoolean(key, value) {
+    if (value === undefined)
+        return false;
+    if (value !== 'true' && value !== 'false')
+        throw new Error(`"${key}" must be "true" or "false", got "${value}"`);
+    return value === 'true';
+}
+const FRONT_PAGE_NOTES = {
+    set: 'now the site front page',
+    unset: 'no longer the front page, the site shows its latest posts',
+};
+export function formatPageProblems(problems) {
+    return problems.map((problem) => `${problem.file}: ${problem.message}`).join('\n  ');
+}
+// `legal-notice` -> `Legal notice`.
+export function titleFromSlug(slug) {
+    const words = slug.split('-').filter(Boolean).join(' ');
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+// A page file is plain HTML, optionally opened by an HTML comment of `key: value` lines:
+//
+//   <!--
+//   title: Legal notice
+//   status: publish
+//   template: page-no-title
+//   -->
+//
+// A comment rather than YAML front matter so the file stays valid HTML, previewable as is in a
+// browser. The header is stripped from what gets pushed. Throws on an unknown key or status so a
+// typo never silently falls back to a default. `template` is the active theme's own template
+// slug (a block theme's templates/<slug>.html, or a classic theme's page-<slug>.php); unlike
+// `status`, it's never validated here, an unknown slug just makes WordPress fall back to the
+// default template, the same silent no-op as `full-width`/`hide-title` on a theme that doesn't
+// support them.
+export function parsePageFile(slug, raw) {
+    const header = /^\s*<!--([\s\S]*?)-->\r?\n?/.exec(raw);
+    const meta = {};
+    if (header) {
+        for (const line of header[1].split(/\r?\n/)) {
+            if (line.trim() === '')
+                continue;
+            const colon = line.indexOf(':');
+            if (colon === -1)
+                throw new Error(`header line "${line.trim()}" is not a "key: value" pair`);
+            const key = line.slice(0, colon).trim();
+            if (!HEADER_KEYS.includes(key))
+                throw new Error(`unknown header key "${key}" (allowed: ${HEADER_KEYS.join(', ')})`);
+            meta[key] = line.slice(colon + 1).trim();
+        }
+    }
+    const status = meta.status ?? 'draft';
+    if (!PAGE_STATUSES.includes(status)) {
+        throw new Error(`status "${status}" is not one of ${PAGE_STATUSES.join(', ')}`);
+    }
+    return {
+        fullWidth: parseBoolean('full-width', meta['full-width']),
+        hideTitle: parseBoolean('hide-title', meta['hide-title']),
+        html: header ? raw.slice(header[0].length) : raw,
+        slug,
+        status: status,
+        template: meta.template ?? '',
+        title: meta.title || titleFromSlug(slug),
+    };
+}
+// Reads every page of `dir` and reports every problem at once instead of skipping bad files
+// like the other resources do: a page push is declarative, so anything unexpected in the
+// directory (a `.php`, a subdirectory, a bad header) must stop it before any network call.
+// Dotfiles (.DS_Store, editor droppings) are ignored. A missing directory is "no pages".
+export async function readLocalPages(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { pages: [], problems: [] };
+        throw error;
+    }
+    const pages = [];
+    const problems = [];
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const filePath = join(dir, entry.name);
+        if (!entry.isFile()) {
+            problems.push({ file: filePath, message: `subdirectories are not supported, keep every page at the top of ${dir}` });
+            continue;
+        }
+        if (extname(entry.name) !== '.html') {
+            problems.push({ file: filePath, message: `only .html files are allowed in ${dir}` });
+            continue;
+        }
+        const slug = basename(entry.name, '.html');
+        if (!PAGE_SLUG_PATTERN.test(slug)) {
+            problems.push({ file: filePath, message: 'the file name must be lowercase letters and digits separated by single hyphens (e.g. "legal-notice.html")' });
+            continue;
+        }
+        try {
+            pages.push(parsePageFile(slug, await readFile(filePath, 'utf8')));
+        }
+        catch (error) {
+            problems.push({ file: filePath, message: error.message });
+        }
+    }
+    return { pages, problems };
+}
+export function frontPageNote(page) {
+    return page.frontPage === undefined ? '' : ` (${FRONT_PAGE_NOTES[page.frontPage]})`;
+}

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

@@ -7,6 +7,7 @@ export declare const RESOURCE_DIR_DEFAULTS: {
     readonly hooks: "hooks";
     readonly menu: "menus";
     readonly options: "options";
+    readonly page: "pages";
     readonly seo: "seo";
     readonly snippets: "snippets";
     readonly themeStyles: "theme";

package/dist/utils/resource-dirs.js

@@ -9,6 +9,7 @@ export const RESOURCE_DIR_DEFAULTS = {
     hooks: 'hooks',
     menu: 'menus',
     options: 'options',
+    page: 'pages',
     seo: 'seo',
     snippets: 'snippets',
     themeStyles: 'theme',
@@ -21,6 +22,7 @@ const CONFIG_KEY = {
     hooks: 'hooksDir',
     menu: 'menuDir',
     options: 'optionsDir',
+    page: 'pageDir',
     seo: 'seoDir',
     snippets: 'snippetsDir',
     themeStyles: 'themeStylesDir',