@loopress/cli 0.26.0 → 0.27.0

package/dist/commands/init.js

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { configManager } from '../config/project-config.manager.js';
 import { isInteractive } from '../lib/interactive.js';
-import { writeLocalConfig } from '../utils/loopress-config.js';
+import { ensureLfGitattributes, writeLocalConfig } from '../utils/loopress-config.js';
 // WordPress.org slugs for the two snippet plugins the Loopress WordPress plugin supports
 // (see SnippetModule.php, which wires up both providers and auto-detects the active one).
 const SNIPPET_PROVIDERS = [
@@ -68,6 +68,7 @@ export default class Init extends Command {
                 config[feature.key] = feature.dir;
         }
         await writeLocalConfig(config);
+        const isGitattributesUpdated = await ensureLfGitattributes();
         let isProviderAdded = false;
         if (providerChoice !== '__none__') {
             try {
@@ -89,6 +90,9 @@ export default class Init extends Command {
         if (isProviderAdded) {
             this.log(`  Plugin:   ${providerChoice}`);
         }
+        if (isGitattributesUpdated) {
+            this.log('✓ .gitattributes: LF line endings, so files match across macOS, Linux and Windows');
+        }
         this.log('\n→ Next: run `lps snippet pull` to fetch what is already on the site, or `lps doctor` to verify the connection.');
     }
     // When nothing is configured yet, the useful path is configuring a project right here, not

package/dist/commands/page/push.js

@@ -1,6 +1,6 @@
 import { Args } from '@oclif/core';
 import { PushCommand } from '../../lib/push-command.js';
-import { formatPageProblems, PAGES_ENDPOINT, readLocalPages } from '../../utils/page-format.js';
+import { formatPageProblems, frontPageNote, PAGES_ENDPOINT, readLocalPages } from '../../utils/page-format.js';
 import { pluralize } from '../../utils/pluralize.js';
 import { resolveResourceDir } from '../../utils/resource-dirs.js';
 export default class Push extends PushCommand {
@@ -51,7 +51,7 @@ export default class Push extends PushCommand {
         try {
             const result = await this.wp.put(PAGES_ENDPOINT, page);
             if (task)
-                task.output = `Pushed: ${page.slug} (${result.status}) ${result.link}`;
+                task.output = `Pushed: ${page.slug} (${result.status}) ${result.link}${frontPageNote(result)}`;
         }
         catch (error) {
             this.reportTaskFailure(`Failed to push ${page.slug}: ${error.message}`, error, task);

package/dist/commands/plugin/add.d.ts

@@ -1,13 +1,20 @@
 import { LoopressCommand } from '../../lib/base.js';
+type AddResult = {
+    slug: string;
+    status: 'added' | 'dry-run' | 'unchanged' | 'updated';
+    version: string;
+};
 export default class Add extends LoopressCommand {
     static args: {
         slug: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
         version: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    run(): Promise<void>;
+    run(): Promise<AddResult>;
 }
+export {};

package/dist/commands/plugin/add.js

@@ -7,6 +7,7 @@ export default class Add extends LoopressCommand {
         slug: Args.string({ description: 'Plugin slug on WordPress.org', required: true }),
     };
     static description = 'Add a WordPress.org plugin to loopress.json';
+    static enableJsonFlag = true;
     static examples = [
         '$ lps plugin add woocommerce',
         '$ lps plugin add woocommerce --version 9.4.2',
@@ -26,17 +27,18 @@ export default class Add extends LoopressCommand {
         const existing = this.localConfig.plugins ?? {};
         if (existing[slug] === version) {
             this.log(`${slug} is already pinned to ${version} in loopress.json, nothing to do.`);
-            return;
+            return { slug, status: 'unchanged', version };
         }
         const isUpdated = existing[slug] !== undefined;
         if (this.dryRun) {
             this.log(`[dry-run] Would ${isUpdated ? 'update' : 'add'} ${slug} (${version}) in loopress.json`);
-            return;
+            return { slug, status: 'dry-run', version };
         }
         await writeLocalConfig({
             ...this.localConfig,
             plugins: { ...existing, [slug]: version },
         });
         this.log(`${isUpdated ? 'Updated' : 'Added'} ${slug} (${version}). Run \`lps plugin push\` to apply.`);
+        return { slug, status: isUpdated ? 'updated' : 'added', version };
     }
 }

package/dist/commands/promote.js

@@ -3,6 +3,7 @@ import { Args, Command } from '@oclif/core';
 import { configManager } from '../config/project-config.manager.js';
 import { LoopressCommand } from '../lib/base.js';
 import { isInteractive } from '../lib/interactive.js';
+import { stdoutToStderr } from '../lib/json-delegation.js';
 import { readLocalConfig } from '../utils/loopress-config.js';
 export default class Promote extends Command {
     static args = {
@@ -30,14 +31,14 @@ export default class Promote extends Command {
             await this.confirmPromotion(from.name, to.name, to.url, yes);
         this.log(`\n=== Pulling from ${from.name} (${from.url}) ===`);
         try {
-            await this.config.runCommand('pull', this.delegateArgv(from.name, dryRun));
+            await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('pull', this.delegateArgv(from.name, dryRun)));
         }
         catch (error) {
             // A partial pull must never be pushed onward: stop before touching <to>.
             this.error(`Pull from ${from.name} failed, ${to.name} left untouched: ${error.message}`);
         }
         this.log(`\n=== Pushing to ${to.name} (${to.url}) ===`);
-        await this.config.runCommand('push', this.delegateArgv(to.name, dryRun));
+        await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('push', this.delegateArgv(to.name, dryRun)));
         this.log(dryRun ? `\n[dry-run] ${from.name} would be promoted to ${to.name}.` : `\n${from.name} promoted to ${to.name}.`);
         return { from: from.name, status: dryRun ? 'dry-run' : 'promoted', to: to.name };
     }

package/dist/commands/pull.js

@@ -1,4 +1,5 @@
 import { LoopressCommand } from '../lib/base.js';
+import { stdoutToStderr } from '../lib/json-delegation.js';
 import { pluralize } from '../utils/pluralize.js';
 // composer before plugins: `plugin:pull` reads the local composer.json to skip
 // Composer-managed plugins, so it needs the freshly pulled one. The rest write to independent
@@ -29,7 +30,7 @@ export default class Pull extends LoopressCommand {
         for (const target of PULL_TARGETS) {
             this.log(`\n→ Pulling ${target.label}...`);
             try {
-                await this.config.runCommand(target.commandId, this.buildArgv(target));
+                await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand(target.commandId, this.buildArgv(target)));
                 this.log(`✓ ${target.label} pulled`);
                 results.push({ label: target.label, status: 'pulled' });
             }
@@ -41,7 +42,10 @@ export default class Pull extends LoopressCommand {
             }
         }
         if (this.failedCount > 0) {
-            this.error(`${pluralize(this.failedCount, 'resource')} failed to pull.`);
+            // Each failure's own reason, not just the count: under --json the per-resource lines above
+            // never reach stdout, and this message is all an MCP caller or a script gets to see.
+            const failures = results.filter((result) => result.status === 'failed').map((result) => `${result.label}: ${result.error}`);
+            this.error(`${pluralize(this.failedCount, 'resource')} failed to pull. ${failures.join('; ')}`);
         }
         this.log('\nAll resources pulled.');
         return { results };

package/dist/commands/push.js

@@ -1,5 +1,6 @@
 import { LoopressCommand } from '../lib/base.js';
 import { guardProductionPush } from '../lib/guard-production-push.js';
+import { stdoutToStderr } from '../lib/json-delegation.js';
 import { pluralize } from '../utils/pluralize.js';
 // Dependency-ish order: code first (plugins, composer), then the ACF definitions content
 // relies on, then content itself.
@@ -32,7 +33,7 @@ export default class Push extends LoopressCommand {
         for (const target of PUSH_TARGETS) {
             this.log(`\n→ Pushing ${target.label}...`);
             try {
-                await this.config.runCommand(target.commandId, argv);
+                await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand(target.commandId, argv));
                 this.log(`✓ ${target.label} pushed`);
                 results.push({ label: target.label, status: 'pushed' });
             }
@@ -44,7 +45,10 @@ export default class Push extends LoopressCommand {
             }
         }
         if (this.failedCount > 0) {
-            this.error(`${pluralize(this.failedCount, 'resource')} failed to push.`);
+            // Each failure's own reason, not just the count: under --json the per-resource lines above
+            // never reach stdout, and this message is all an MCP caller or a script gets to see.
+            const failures = results.filter((result) => result.status === 'failed').map((result) => `${result.label}: ${result.error}`);
+            this.error(`${pluralize(this.failedCount, 'resource')} failed to push. ${failures.join('; ')}`);
         }
         this.log('\nAll resources pushed.');
         return { results };

package/dist/commands/theme/add.d.ts

@@ -1,13 +1,20 @@
 import { LoopressCommand } from '../../lib/base.js';
+type AddResult = {
+    slug: string;
+    status: 'added' | 'dry-run' | 'unchanged' | 'updated';
+    version: string;
+};
 export default class Add extends LoopressCommand {
     static args: {
         slug: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
         version: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    run(): Promise<void>;
+    run(): Promise<AddResult>;
 }
+export {};

package/dist/commands/theme/add.js

@@ -7,6 +7,7 @@ export default class Add extends LoopressCommand {
         slug: Args.string({ description: 'Theme slug on WordPress.org', required: true }),
     };
     static description = 'Add a WordPress.org theme to loopress.json';
+    static enableJsonFlag = true;
     static examples = ['$ lps theme add generatepress', '$ lps theme add generatepress --version 3.4.0'];
     static flags = {
         ...LoopressCommand.dryRunFlag,
@@ -22,14 +23,15 @@ export default class Add extends LoopressCommand {
         const existing = this.localConfig.themes ?? {};
         if (existing[slug] === version) {
             this.log(`${slug} is already pinned to ${version}, nothing to do.`);
-            return;
+            return { slug, status: 'unchanged', version };
         }
         const isUpdated = existing[slug] !== undefined;
         if (this.dryRun) {
             this.log(`[dry-run] Would ${isUpdated ? 'update' : 'add'} ${slug} (${version})`);
-            return;
+            return { slug, status: 'dry-run', version };
         }
         await writeLocalConfig({ ...this.localConfig, themes: { ...existing, [slug]: version } });
         this.log(`${isUpdated ? 'Updated' : 'Added'} ${slug} (${version}). Run \`lps theme push\` to apply.`);
+        return { slug, status: isUpdated ? 'updated' : 'added', version };
     }
 }

package/dist/lib/api-client.js

@@ -43,11 +43,34 @@ function formatApiError(error, url, timeoutMs) {
     if (status === 401) {
         return `Not logged in or session expired on ${url}. Run \`lps login\` again.`;
     }
+    const reason = nestErrorMessage(err.response?.body);
     if (status === 403) {
-        return `Request rejected (${status}) on ${url}: ${err.response?.body ?? err.message}`;
+        return `Request rejected (${status}) on ${url}: ${reason ?? err.response?.body ?? err.message}`;
+    }
+    // Any other API refusal (a 400 validation error, a 409 conflict) carries its explanation in
+    // the body; got's own message ("Request failed with status code 400") never does.
+    if (status !== undefined && reason) {
+        return `Request failed (${status}) on ${url}: ${reason}`;
     }
     if (err.name === 'TimeoutError') {
         return `Request timed out after ${timeoutMs / 1000}s on ${url}. Check your network connection, or the Loopress API may be temporarily unreachable.`;
     }
     return err.message ?? String(error);
 }
+// NestJS's HttpException body: `{statusCode, message, error}`, where `message` is a list for a
+// ValidationPipe failure (one entry per invalid field).
+function nestErrorMessage(body) {
+    if (!body)
+        return undefined;
+    try {
+        const { message } = JSON.parse(body);
+        if (typeof message === 'string' && message.trim())
+            return message;
+        if (Array.isArray(message) && message.length > 0)
+            return message.join('; ');
+    }
+    catch {
+        // not JSON (a proxy's HTML error page): nothing to extract
+    }
+    return undefined;
+}

package/dist/lib/dev-watch.d.ts

@@ -1,5 +1,5 @@
 import { type LoopressLocalConfig } from '../utils/loopress-config.js';
-export type ResourceType = 'api' | 'pages' | 'plugins' | 'snippets';
+export type ResourceType = 'api' | 'hooks' | 'pages' | 'plugins' | 'snippets';
 export declare const RESOURCE_TYPES: ResourceType[];
 export type WatchTarget = {
     commandId: string;

package/dist/lib/dev-watch.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { join, sep } from 'node:path';
-export const RESOURCE_TYPES = ['snippets', 'pages', 'api', 'plugins'];
+export const RESOURCE_TYPES = ['snippets', 'pages', 'api', 'hooks', 'plugins'];
 // `only` narrows the default set, `skip` then removes from whatever that set is, same
 // precedence a combined `--only=a,b --skip=b` reads as: watch a, b, then drop b.
 export function resolveResourceTypes(only, skip = []) {
@@ -15,6 +15,7 @@ export function buildWatchTargets(types, localConfig, cwd) {
     const rootDir = join(cwd, localConfig.rootDir ?? '.');
     const candidates = {
         api: { commandId: 'api:push', path: join(rootDir, localConfig.apiDir ?? 'api'), type: 'api' },
+        hooks: { commandId: 'hook:push', path: join(rootDir, localConfig.hooksDir ?? 'hooks'), type: 'hooks' },
         pages: { commandId: 'page:push', path: join(rootDir, localConfig.pageDir ?? 'pages'), type: 'pages' },
         plugins: { commandId: 'plugin:push', path: join(cwd, 'loopress.json'), type: 'plugins' },
         snippets: { commandId: 'snippet:push', path: join(rootDir, localConfig.snippetsDir ?? 'snippets'), type: 'snippets' },

package/dist/lib/json-delegation.d.ts

@@ -0,0 +1 @@
+export declare function stdoutToStderr<T>(enabled: boolean, work: () => Promise<T>): Promise<T>;

package/dist/lib/json-delegation.js

@@ -0,0 +1,18 @@
+// `lps push`/`pull`/`promote --json` must put exactly one JSON document on stdout: that's what
+// the MCP server (and any script) parses. The resource commands they delegate to aren't in JSON
+// mode themselves, so their progress lines and Listr renderers would land on stdout ahead of it.
+// While `enabled`, their stdout goes to stderr instead: still visible to a human, out of the
+// JSON. Patching the stream's write is the one place every writer goes through (oclif's
+// ux.stdout, Listr's renderers, a stray console.log).
+export async function stdoutToStderr(enabled, work) {
+    if (!enabled)
+        return work();
+    const original = process.stdout.write;
+    process.stdout.write = process.stderr.write.bind(process.stderr);
+    try {
+        return await work();
+    }
+    finally {
+        process.stdout.write = original;
+    }
+}

package/dist/lib/load-snippets.js

@@ -70,7 +70,7 @@ async function loadSnippet(path, file, onSkip) {
     };
 }
 // Shared by `snippet push` (pushes to the project's own WordPress site) and `snippet publish`
-// (publishes to the Loopress api as a shared source) — both read the same local `snippets/`
+// (publishes to the Loopress api as a shared source): both read the same local `snippets/`
 // directory the same way. `onSkip` is optional so callers that don't care about per-file
 // warnings (e.g. `snippet publish`) can ignore them; skipped files are simply left out either way.
 export async function loadSnippets(path, onSkip) {

package/dist/lib/php-files-command.js

@@ -341,9 +341,10 @@ export const API_FILES_RESOURCE = {
     emptyListMessage: 'No API route files found',
     endpoint: 'loopress/v1/api-files',
     // Mirrors ApiFilesController::isValidFilename(): kebab-case segments or a bracketed dynamic
-    // segment like [order_id], joined by '/'.
-    filenamePattern: /^(?:[a-z0-9-]+|\[[A-Za-z_]\w*\])(?:\/(?:[a-z0-9-]+|\[[A-Za-z_]\w*\]))*$/,
-    invalidFilenameHint: 'each path segment must be lowercase letters, digits, and hyphens, or a bracketed dynamic segment like "[order_id]" (e.g. "invoice-pdf/[order_id].php")',
+    // segment like [order_id], joined by '/', and never a root "index" (api/index.php is
+    // reserved; a nested orders/index.php is the /orders route).
+    filenamePattern: /^(?!index$)(?:[a-z0-9-]+|\[[A-Za-z_]\w*\])(?:\/(?:[a-z0-9-]+|\[[A-Za-z_]\w*\]))*$/,
+    invalidFilenameHint: 'each path segment must be lowercase letters, digits, and hyphens, or a bracketed dynamic segment like "[order_id]" (e.g. "invoice-pdf/[order_id].php"), and a root "index.php" is reserved: name the file, or nest it (orders/index.php is the /orders route)',
     label: 'API routes',
     listDescription: 'List custom API route files from WordPress',
     noun: 'route file',

package/dist/lib/readdir-tolerant.js

@@ -1,4 +1,4 @@
-import { readdir } from 'node:fs/promises';
+import { readdir, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 export async function readdirTolerant(dir, options) {
     try {
@@ -16,10 +16,20 @@ export async function readdirTolerant(dir, options) {
 // never the OS separator: callers match these identities against server-sent filenames
 // (which are always '/'-joined) or embed them in an API payload, so a Windows run must
 // produce the exact same strings as a POSIX one. ENOENT on `dir` itself yields no files,
-// same tolerance as readdirTolerant.
+// same tolerance as readdirTolerant. A symlink to a file counts as that file (a project can
+// link a route in from a shared checkout); a broken one, or one to a directory, is skipped.
 export async function walkFiles(dir) {
     const entries = await readdirTolerant(dir, { recursive: true, withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isFile())
-        .map((entry) => relative(dir, join(entry.parentPath, entry.name)).split(sep).join('/'));
+    const files = [];
+    for (const entry of entries) {
+        const path = join(entry.parentPath, entry.name);
+        if (entry.isFile() || (entry.isSymbolicLink() && (await isFile(path))))
+            files.push(relative(dir, path).split(sep).join('/'));
+    }
+    return files;
+}
+async function isFile(path) {
+    return stat(path)
+        .then((s) => s.isFile())
+        .catch(() => false);
 }

package/dist/lib/snapshot-store.js

@@ -49,6 +49,7 @@ export async function writeSnapshot(options) {
     const { afterState, beforeState, environment, resource, retain = SNAPSHOT_RETENTION, rootDir } = options;
     const dir = snapshotsDir(rootDir, resource, environment);
     await mkdir(dir, { recursive: true });
+    await ignoreCacheDirInGit(rootDir);
     const snapshot = {
         afterState: stateToRecord(afterState),
         beforeState: stateToRecord(beforeState),
@@ -72,6 +73,19 @@ export async function writeSnapshot(options) {
     await pruneSnapshots(rootDir, resource, environment, retain);
     return String(id);
 }
+// `.loopress/` lives inside the user's project and holds the environment's full remote state
+// (snippet code, form definitions, option values): a `git add .` must never pick it up. The
+// directory ignores itself, the way `.pytest_cache` does, instead of relying on every project
+// to add it to its own .gitignore. `wx` so a hand-edited file is never overwritten.
+async function ignoreCacheDirInGit(rootDir) {
+    try {
+        await writeFile(join(rootDir, '.loopress', '.gitignore'), '# Written by the Loopress CLI: local rollback snapshots, never commit them.\n*\n', { flag: 'wx' });
+    }
+    catch (error) {
+        if (!isEexist(error))
+            throw error;
+    }
+}
 // Newest first. A missing snapshots directory (never pushed, or pruned to nothing) reads as
 // "no snapshots", not an error, the same ENOENT tolerance every resource-state provider gives
 // a never-pulled local directory.

package/dist/lib/validate-local.js

@@ -1,22 +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
@@ -37,6 +40,9 @@ 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');
@@ -91,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}` });
@@ -107,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/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

@@ -14,6 +14,9 @@ export type Page = {
 export type RemotePage = Page & {
     link: string;
 };
+export type PushedPage = RemotePage & {
+    frontPage?: 'set' | 'unset';
+};
 export type PageProblem = {
     file: string;
     message: string;
@@ -25,3 +28,4 @@ export declare function readLocalPages(dir: string): Promise<{
     pages: Page[];
     problems: PageProblem[];
 }>;
+export declare function frontPageNote(page: PushedPage): string;

package/dist/utils/page-format.js

@@ -13,6 +13,10 @@ function parseBoolean(key, value) {
         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  ');
 }
@@ -109,3 +113,6 @@ export async function readLocalPages(dir) {
     }
     return { pages, problems };
 }
+export function frontPageNote(page) {
+    return page.frontPage === undefined ? '' : ` (${FRONT_PAGE_NOTES[page.frontPage]})`;
+}