@loopress/cli 0.22.0 → 0.23.0

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

@@ -0,0 +1,21 @@
+import { LoopressCommand } from '../../lib/base.js';
+type PullResult = {
+    added: string[];
+    merged: Record<string, string>;
+    status: 'composer-managed' | 'dry-run' | 'success';
+    updated: Array<{
+        from: string;
+        slug: string;
+        to: string;
+    }>;
+};
+export default class Pull extends LoopressCommand {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<PullResult>;
+}
+export {};

package/dist/commands/theme/pull.js

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { LoopressCommand } from '../../lib/base.js';
+import { writeLocalConfig } from '../../utils/loopress-config.js';
+import { mergePluginManifest } from '../../utils/plugins.js';
+import { parseInstalledThemes } from '../../utils/themes.js';
+export default class Pull extends LoopressCommand {
+    static description = 'Pull installed themes from WordPress into loopress.json, pinned to their live versions';
+    static enableJsonFlag = true;
+    static examples = ['$ lps theme pull'];
+    static flags = {
+        ...LoopressCommand.dryRunFlag,
+    };
+    async run() {
+        const { url } = this.siteConfig;
+        if (existsSync(join(process.cwd(), this.rootDir, 'composer.json'))) {
+            this.warn('This project has a composer.json, which is authoritative. Run `lps composer pull` instead.');
+            return { added: [], merged: this.localConfig.themes ?? {}, status: 'composer-managed', updated: [] };
+        }
+        this.log(`Pulling themes from ${url}`);
+        const raw = await this.wp.get('wp/v2/themes');
+        const installed = parseInstalledThemes(raw);
+        const incoming = Object.fromEntries(installed.map((t) => [t.slug, t.version]));
+        const { added, merged, updated } = mergePluginManifest(this.localConfig.themes ?? {}, incoming);
+        if (this.dryRun) {
+            this.log(`[dry-run] Would write ${Object.keys(merged).length} themes to loopress.json`);
+            return { added, merged, status: 'dry-run', updated };
+        }
+        await writeLocalConfig({ ...this.localConfig, themes: merged });
+        this.log(`Wrote ${Object.keys(merged).length} themes to loopress.json`);
+        if (added.length > 0)
+            this.log(`  + Added: ${added.join(', ')}`);
+        for (const u of updated)
+            this.log(`  ~ Updated: ${u.slug} ${u.from} → ${u.to}`);
+        return { added, merged, status: 'success', updated };
+    }
+}

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

@@ -0,0 +1,23 @@
+import { PushCommand } from '../../lib/push-command.js';
+type PushResult = {
+    installed: string[];
+    pinned: string[];
+    removed: string[];
+    status: 'composer-managed' | 'dry-run' | 'in-sync' | 'success';
+};
+export default class Push extends PushCommand {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<PushResult>;
+    private confirmRemovals;
+    private fetchInstanceLock;
+    private guardForce;
+    private sync;
+}
+export {};

package/dist/commands/theme/push.js

@@ -0,0 +1,130 @@
+import { confirm } from '@inquirer/prompts';
+import { Flags } from '@oclif/core';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isInteractive } from '../../lib/interactive.js';
+import { PushCommand } from '../../lib/push-command.js';
+import { isNotFoundError } from '../../lib/wp-client.js';
+import { isDowngrade, parseCollisions, SYNC_TIMEOUT_MS } from '../../utils/plugin-sync.js';
+import { lockedWpackagistSlugs } from '../../utils/plugins.js';
+import { diffThemes, parseInstalledThemes } from '../../utils/themes.js';
+const IN_SYNC = { installed: [], pinned: [], removed: [], status: 'in-sync' };
+export default class Push extends PushCommand {
+    static description = 'Install themes on WordPress to match loopress.json (versions only, never switches the active theme)';
+    static enableJsonFlag = true;
+    static examples = ['$ lps theme push', '$ lps theme push --force'];
+    static flags = {
+        ...PushCommand.dryRunFlag,
+        ...PushCommand.yesFlag,
+        force: Flags.boolean({ default: false, description: 'Allow downgrades and take over themes installed outside Loopress' }),
+    };
+    async run() {
+        const { flags } = await this.parse(Push);
+        const { force } = flags;
+        if (existsSync(join(process.cwd(), this.rootDir, 'composer.json'))) {
+            this.warn('This project has a composer.json, which is authoritative. Run `lps composer push` instead.');
+            return { ...IN_SYNC, status: 'composer-managed' };
+        }
+        const manifest = this.localConfig.themes ?? {};
+        if (Object.keys(manifest).length === 0) {
+            this.error('No themes found in loopress.json. Run `lps theme pull` first.');
+        }
+        this.log(`Pushing themes to ${this.siteConfig.url}`);
+        const raw = await this.wp.get('wp/v2/themes');
+        const installed = parseInstalledThemes(raw);
+        const managed = lockedWpackagistSlugs(await this.fetchInstanceLock(), 'theme');
+        const diff = diffThemes(manifest, installed, managed);
+        this.guardForce(diff, force);
+        // Uninstalling the theme WordPress is currently rendering leaves the site with no active
+        // theme, which is a hard fatal. --force does not override this: switch the active theme
+        // on the site first, then the removal is safe. A --force takeover of a collision hits the
+        // same fatal: the server moves the existing folder out of the way before reinstalling it,
+        // so the active theme is briefly missing either way, an active collision is just as
+        // dangerous as an active removal.
+        const activeRemoval = [...diff.toRemove, ...diff.collisions.map((c) => c.slug)].find((slug) => installed.find((t) => t.slug === slug)?.active);
+        if (activeRemoval) {
+            this.error(`Refusing to uninstall "${activeRemoval}": it is the site's active theme. ` +
+                'Switch the site to another theme, then re-run to remove it.');
+        }
+        // A "latest" pin never shows as drift, but its newest upstream release may have moved, so
+        // a push must still run `composer update` to pick it up.
+        const hasLatestPin = Object.values(manifest).includes('latest');
+        if (!hasLatestPin && isNoop(diff)) {
+            this.log('Everything is already in sync.');
+            return { ...IN_SYNC };
+        }
+        if (isNoop(diff))
+            this.log('Refreshing themes pinned to "latest" to their newest releases.');
+        for (const a of diff.toInstall)
+            this.log(`  + ${a.slug} ${a.version}`);
+        for (const p of diff.toPin)
+            this.log(`  ~ ${p.slug} ${p.from} to ${p.to}`);
+        for (const s of diff.toRemove)
+            this.log(`  - ${s}`);
+        for (const c of diff.collisions)
+            this.log(`  ! ${c.slug} (take over)`);
+        if (this.dryRun)
+            return result(diff, 'dry-run', diff.toRemove, true);
+        await this.confirmRemovals(diff.toRemove);
+        const response = await this.sync(manifest, force);
+        if (response.output.trim())
+            this.log(response.output.trim());
+        this.log('Themes synced.');
+        await this.recordSuccess();
+        return result(diff, 'success', response.removed ?? diff.toRemove, force);
+    }
+    async confirmRemovals(toRemove) {
+        if (toRemove.length === 0 || this.yes || !isInteractive())
+            return;
+        const ok = await confirm({ default: false, message: `Uninstall ${toRemove.join(', ')} from the site?` });
+        if (!ok)
+            this.error('Aborted.');
+    }
+    async fetchInstanceLock() {
+        try {
+            const { composerLock } = await this.wp.get('loopress/v1/composer/lock');
+            return composerLock;
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
+        }
+    }
+    guardForce(diff, force) {
+        if (force)
+            return;
+        if (diff.collisions.length > 0) {
+            const list = diff.collisions.map((c) => `${c.slug} (${c.installedVersion})`).join(', ');
+            this.error(`${list} installed outside Loopress. Re-run with --force to take them over, or remove them from loopress.json.`);
+        }
+        const downgrades = diff.toPin.filter((p) => isDowngrade(p.from, p.to));
+        if (downgrades.length > 0) {
+            const list = downgrades.map((p) => `${p.slug} ${p.from} to ${p.to}`).join(', ');
+            this.error(`Refusing to downgrade: ${list}. Re-run with --force.`);
+        }
+    }
+    async sync(manifest, force) {
+        try {
+            return await this.wp.post('loopress/v1/composer/sync', { force, intent: { themes: manifest }, lock: null }, { timeoutMs: SYNC_TIMEOUT_MS });
+        }
+        catch (error) {
+            if (parseCollisions(error)) {
+                this.error('The site rejected the push: themes installed outside Loopress. Re-run with --force.');
+            }
+            throw error;
+        }
+    }
+}
+function isNoop(diff) {
+    return (diff.toInstall.length === 0 && diff.toPin.length === 0 && diff.toRemove.length === 0 && diff.collisions.length === 0);
+}
+function result(diff, status, removed, includeCollisions) {
+    const collisionSlugs = includeCollisions ? diff.collisions.map((c) => c.slug) : [];
+    return {
+        installed: [...diff.toInstall.map((a) => a.slug), ...collisionSlugs],
+        pinned: diff.toPin.map((p) => p.slug),
+        removed,
+        status,
+    };
+}

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

@@ -0,0 +1,20 @@
+import { LoopressCommand } from '../../lib/base.js';
+type StatusResult = {
+    drift: boolean;
+    missing: string[];
+    status: 'composer-managed' | 'drift' | 'in-sync';
+    wrongVersion: Array<{
+        live: string;
+        pinned: string;
+        slug: string;
+    }>;
+};
+export default class Status extends LoopressCommand {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {};
+    run(): Promise<StatusResult>;
+    private fetchInstanceLock;
+}
+export {};

package/dist/commands/theme/status.js

@@ -0,0 +1,51 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { LoopressCommand } from '../../lib/base.js';
+import { isNotFoundError } from '../../lib/wp-client.js';
+import { lockedWpackagistSlugs } from '../../utils/plugins.js';
+import { diffThemes, parseInstalledThemes } from '../../utils/themes.js';
+export default class Status extends LoopressCommand {
+    static description = 'Compare the themes on WordPress against loopress.json and report version drift';
+    static enableJsonFlag = true;
+    static examples = ['$ lps theme status'];
+    static flags = {};
+    async run() {
+        const { url } = this.siteConfig;
+        if (existsSync(join(process.cwd(), this.rootDir, 'composer.json'))) {
+            this.warn('This project has a composer.json, which is authoritative. Run `lps composer` commands instead.');
+            return { drift: false, missing: [], status: 'composer-managed', wrongVersion: [] };
+        }
+        const manifest = this.localConfig.themes ?? {};
+        const raw = await this.wp.get('wp/v2/themes');
+        const installed = parseInstalledThemes(raw);
+        const managed = lockedWpackagistSlugs(await this.fetchInstanceLock(), 'theme');
+        const diff = diffThemes(manifest, installed, managed);
+        const missing = [...diff.toInstall.map((a) => a.slug), ...diff.collisions.map((c) => c.slug)];
+        const wrongVersion = diff.toPin.map((p) => ({ live: p.from, pinned: p.to, slug: p.slug }));
+        const drift = missing.length > 0 || wrongVersion.length > 0 || diff.toRemove.length > 0;
+        if (!drift) {
+            this.log(`In sync with loopress.json (${url})`);
+            return { drift: false, missing: [], status: 'in-sync', wrongVersion: [] };
+        }
+        if (diff.toInstall.length > 0)
+            this.log(`Not installed: ${diff.toInstall.map((a) => a.slug).join(', ')}`);
+        if (diff.collisions.length > 0)
+            this.log(`Installed outside Loopress: ${diff.collisions.map((c) => c.slug).join(', ')}`);
+        for (const w of wrongVersion)
+            this.log(`Version drift: ${w.slug} is ${w.live}, loopress.json pins ${w.pinned}`);
+        if (diff.toRemove.length > 0)
+            this.log(`Managed by Loopress but dropped from loopress.json: ${diff.toRemove.join(', ')}`);
+        this.exit(1);
+    }
+    async fetchInstanceLock() {
+        try {
+            const { composerLock } = await this.wp.get('loopress/v1/composer/lock');
+            return composerLock;
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
+        }
+    }
+}

package/dist/lib/app-manifest.d.ts

@@ -0,0 +1,36 @@
+export type AppFile = {
+    path: string;
+    sha256: string;
+    size: number;
+};
+export type AppEntry = {
+    scripts: string[];
+    styles: string[];
+};
+export type AppConfigFile = {
+    assetsDir?: string;
+    entry?: AppEntry;
+    mountSelector?: string;
+    name?: string;
+    routing?: string;
+};
+export type AppManifest = {
+    buildId: string;
+    entry: AppEntry;
+    files: AppFile[];
+    mountSelector: string;
+    name: string;
+    routing: 'hash';
+};
+export declare const APP_CONFIG_FILENAME = "loopress.app.json";
+export declare function isAllowedAsset(relPath: string): boolean;
+export declare function buildFileList(distDir: string): Promise<AppFile[]>;
+export declare function computeBuildId(files: AppFile[]): string;
+export declare function deriveEntry(indexHtml: string): AppEntry;
+export declare function diffFiles(local: AppFile[], remote: AppFile[]): AppFile[];
+export declare function parseAppConfig(raw: string, appDir: string): AppConfigFile;
+export declare function loadAppManifest(appDir: string, dirName: string): Promise<{
+    configPath: string;
+    distDir: string;
+    manifest: AppManifest;
+}>;

package/dist/lib/app-manifest.js

@@ -0,0 +1,162 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+export const APP_CONFIG_FILENAME = 'loopress.app.json';
+const DEFAULT_ASSETS_DIR = 'dist';
+// Static assets a bundler emits, mirrors the server's AppsDirectory::ALLOWED_EXTENSIONS.
+// `.php` and friends are absent on purpose: these files are served straight off wp-content/.
+const ALLOWED_EXTENSIONS = new Set([
+    '.avif', '.bmp', '.cjs', '.css', '.csv', '.eot', '.gif', '.htm', '.html', '.ico', '.jpeg',
+    '.jpg', '.js', '.json', '.map', '.mjs', '.mp3', '.mp4', '.ogg', '.otf',
+    '.pdf', '.png', '.svg', '.ttf', '.txt',
+    '.wasm', '.webm', '.webmanifest', '.webp', '.woff', '.woff2', '.xml',
+]);
+export function isAllowedAsset(relPath) {
+    return ALLOWED_EXTENSIONS.has(extname(relPath).toLowerCase());
+}
+async function walk(dir, root) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const entry of entries) {
+        const abs = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await walk(abs, root)));
+        }
+        else if (entry.isFile()) {
+            // Identity is always '/'-joined, never the OS separator: it travels over HTTP and is
+            // matched against the server's own '/'-joined paths.
+            out.push(relative(root, abs).replaceAll(/[\\/]/g, '/'));
+        }
+    }
+    return out;
+}
+// Builds the sorted file list of a dist directory. Throws on a file whose extension the
+// server would reject, so the push fails locally with a clear message instead of a 400
+// halfway through the upload.
+export async function buildFileList(distDir) {
+    const relPaths = (await walk(distDir, distDir)).sort((a, b) => a.localeCompare(b));
+    const files = [];
+    for (const path of relPaths) {
+        if (!isAllowedAsset(path)) {
+            throw new Error(`${path}: extension ${extname(path) || '(none)'} is not an allowed static asset. Remove it from the build output or the bundle.`);
+        }
+        const buf = await readFile(join(distDir, path));
+        files.push({ path, sha256: createHash('sha256').update(buf).digest('hex'), size: buf.length });
+    }
+    return files;
+}
+// A stable content hash of the whole build: changes if and only if some file's bytes change.
+// Used as the enqueue `?ver` (cache busting) and as the build identity in `app list`.
+export function computeBuildId(files) {
+    const digest = createHash('sha256');
+    for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+        digest.update(`${file.path}:${file.sha256}\n`);
+    }
+    return digest.digest('hex').slice(0, 12);
+}
+function normalizeAssetUrl(url) {
+    let path = url.trim();
+    const schemeMatch = /^(?:[a-z]+:)?\/\/[^/]+(\/.*)$/i.exec(path);
+    if (schemeMatch)
+        path = schemeMatch[1];
+    path = path.replace(/^\.?\//, '');
+    return path;
+}
+// Reads the <script type="module"> and <link rel="stylesheet"> the build's own index.html
+// declares. This is what a bundler already writes; Loopress does not guess or reorder.
+export function deriveEntry(indexHtml) {
+    const scripts = [];
+    for (const tag of indexHtml.match(/<script\b[^>]*>/gi) ?? []) {
+        if (!/\btype=["']module["']/i.test(tag))
+            continue;
+        const src = /\bsrc=["']([^"']+)["']/i.exec(tag);
+        if (src)
+            scripts.push(normalizeAssetUrl(src[1]));
+    }
+    const styles = [];
+    for (const tag of indexHtml.match(/<link\b[^>]*>/gi) ?? []) {
+        if (!/\brel=["']stylesheet["']/i.test(tag))
+            continue;
+        const href = /\bhref=["']([^"']+)["']/i.exec(tag);
+        if (href)
+            styles.push(normalizeAssetUrl(href[1]));
+    }
+    return { scripts, styles };
+}
+// Files new on this build or whose hash moved. Deletions are handled server-side on commit
+// (with a one-generation grace for in-flight sessions), never by this diff.
+export function diffFiles(local, remote) {
+    const remoteByPath = new Map(remote.map((file) => [file.path, file.sha256]));
+    return local.filter((file) => remoteByPath.get(file.path) !== file.sha256);
+}
+export function parseAppConfig(raw, appDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${join(appDir, APP_CONFIG_FILENAME)} is not valid JSON`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`${join(appDir, APP_CONFIG_FILENAME)} must be a JSON object`);
+    }
+    const config = parsed;
+    if (config.routing !== undefined && config.routing !== 'hash') {
+        throw new Error(`${join(appDir, APP_CONFIG_FILENAME)}: routing "${config.routing}" is not supported, only "hash" works without a server rewrite`);
+    }
+    return config;
+}
+// Assembles the full manifest for one app directory: reads loopress.app.json, hashes the
+// dist directory, derives the entry from index.html (or takes it from the config), computes
+// the build id.
+export async function loadAppManifest(appDir, dirName) {
+    const configPath = join(appDir, APP_CONFIG_FILENAME);
+    const config = parseAppConfig(await readFile(configPath, 'utf8'), appDir);
+    const name = config.name ?? dirName;
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(name)) {
+        throw new Error(`Invalid app name "${name}": lowercase letters, digits and hyphens only, no leading or trailing hyphen`);
+    }
+    const distDir = join(appDir, config.assetsDir ?? DEFAULT_ASSETS_DIR);
+    const files = await buildFileList(distDir);
+    if (files.length === 0) {
+        throw new Error(`No files in ${distDir}. Build the app first, then run \`lps app push\`.`);
+    }
+    const filePaths = new Set(files.map((file) => file.path));
+    let entry;
+    if (config.entry) {
+        entry = config.entry;
+    }
+    else if (filePaths.has('index.html')) {
+        entry = deriveEntry(await readFile(join(distDir, 'index.html'), 'utf8'));
+    }
+    else {
+        throw new Error(`${distDir} has no index.html to read the entry from. Add an "entry" object to ${APP_CONFIG_FILENAME}.`);
+    }
+    const missing = [...entry.scripts, ...entry.styles].filter((ref) => !filePaths.has(ref));
+    if (missing.length > 0) {
+        throw new Error(`Entry references files not in the build output: ${missing.join(', ')}`);
+    }
+    if (entry.scripts.length === 0) {
+        throw new Error(`No <script type="module"> entry found for app "${name}".`);
+    }
+    return {
+        configPath,
+        distDir,
+        manifest: {
+            buildId: computeBuildId(files),
+            entry,
+            files,
+            mountSelector: config.mountSelector ?? `#loopress-app-${name}`,
+            name,
+            routing: 'hash',
+        },
+    };
+}

package/dist/lib/base.d.ts

@@ -33,6 +33,7 @@ export declare abstract class LoopressCommand extends Command {
     protected removeOrphanedFiles(dir: string, orphans: string[], reason: string): Promise<void>;
     protected resolveAcfPath(override?: string): string;
     protected resolveApiPath(override?: string): string;
+    protected resolveAppsPath(override?: string): string;
     protected resolveFormPath(override?: string): string;
     protected resolvePagePath(override?: string): string;
     protected resolveSeoPath(override?: string): string;

package/dist/lib/base.js

@@ -141,6 +141,11 @@ export class LoopressCommand extends Command {
             return override;
         return join(this.rootDir, this.localConfig.apiDir ?? 'api');
     }
+    resolveAppsPath(override) {
+        if (override)
+            return override;
+        return join(this.rootDir, this.localConfig.appsDir ?? 'apps');
+    }
     resolveFormPath(override) {
         if (override)
             return override;

package/dist/types/plugin.d.ts

@@ -8,6 +8,7 @@ export type InstalledPlugin = {
 export type WpNativePlugin = {
     name: string;
     plugin: string;
+    plugin_uri: string;
     status: 'active' | 'inactive' | 'network-active';
     version: string;
 };

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

@@ -31,14 +31,24 @@ export interface LoopressProjectConfiguration {
      * Directory where custom API route files are read from and written to, relative to rootDir.
      */
     apiDir?: 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;
     /**
      * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
      */
     projectId?: string;
     /**
-     * WordPress.org plugins managed by Loopress. Keys are plugin slugs; values are written as "latest" since installs go through WordPress's native plugin API, which only installs the current version. Older files may still have a pinned version string here from before this was the case; it is read but no longer acted on.
+     * WordPress.org plugins managed by Loopress, installed via Composer + WPackagist on the site. Keys are plugin slugs. A value is either an exact version to pin (e.g. "9.4.2") or "latest" to track the newest release on every push. Removing an entry uninstalls the plugin on the next push. Ignored when a composer.json exists in rootDir (that file becomes authoritative).
      */
     plugins?: {
         [k: string]: string;
     };
+    /**
+     * 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.
+     */
+    themes?: {
+        [k: string]: string;
+    };
 }

package/dist/utils/plugin-sync.d.ts

@@ -0,0 +1,26 @@
+export declare const SYNC_TIMEOUT_MS = 600000;
+export type SyncIntent = {
+    libraries?: Record<string, string>;
+    plugins?: Record<string, string>;
+    themes?: Record<string, string>;
+};
+export type SyncPayload = {
+    force: boolean;
+    intent: SyncIntent;
+    lock: null | string;
+};
+export type SyncResponse = {
+    composerJson: string;
+    composerLock: string;
+    message: string;
+    output: string;
+    removed: string[];
+};
+export type Collision = {
+    installedVersion: string;
+    path: string;
+    slug: string;
+    type: 'plugin' | 'theme';
+};
+export declare function parseCollisions(error: unknown): Collision[] | null;
+export declare function isDowngrade(from: string, to: string): boolean;

package/dist/utils/plugin-sync.js

@@ -0,0 +1,31 @@
+// Shared helpers for driving the server-side `loopress/v1/composer/sync` endpoint, used by
+// `lps plugin push`, `lps theme push` and `lps composer push`. The endpoint runs Composer +
+// WPackagist inside WordPress; the CLI only ever sends intent (which slugs at which versions),
+// never a composer.json, so the plugin stays the single authority on that file's shape.
+import { compareVersions } from './version.js';
+// A cold `composer update` on a fresh site easily exceeds the global 30s WpClient timeout.
+export const SYNC_TIMEOUT_MS = 600_000;
+// 422 from the sync endpoint when the intent references a plugin/theme whose folder already
+// exists on the site but isn't tracked in composer.lock (installed by hand through wp-admin).
+// Re-running with --force lets the server remove the folder so Composer can take it over.
+export function parseCollisions(error) {
+    const body = error.cause?.response;
+    if (body?.statusCode !== 422 || !body.body)
+        return null;
+    try {
+        const parsed = JSON.parse(body.body);
+        if (parsed.error === 'unmanaged_plugins_present' && Array.isArray(parsed.collisions)) {
+            return parsed.collisions;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+// Only gates whether a version change needs --force. Unorderable inputs ("latest", a
+// constraint) count as "not a downgrade" so they don't block the push.
+export function isDowngrade(from, to) {
+    const order = compareVersions(to, from);
+    return order !== null && order < 0;
+}

package/dist/utils/plugins.d.ts

@@ -1,13 +1,25 @@
 import { type InstalledPlugin, type PluginManifest, type WpNativePlugin } from '../types/plugin.js';
 export type PluginDiff = {
+    collisions: Array<{
+        installedVersion: string;
+        slug: string;
+    }>;
+    inSync: string[];
     toActivate: Array<{
         file: string;
         slug: string;
     }>;
     toInstall: Array<{
         slug: string;
+        version: string;
+    }>;
+    toPin: Array<{
+        from: string;
+        slug: string;
+        to: string;
     }>;
-    upToDate: string[];
+    toRemove: string[];
+    untrackedActive: string[];
 };
 export type MergeResult = {
     added: string[];
@@ -20,4 +32,5 @@ export type MergeResult = {
 };
 export declare function mergePluginManifest(existing: PluginManifest, incoming: PluginManifest): MergeResult;
 export declare function parseInstalledPlugins(raw: WpNativePlugin[]): InstalledPlugin[];
-export declare function diffPlugins(manifest: PluginManifest, installed: InstalledPlugin[]): PluginDiff;
+export declare function diffPlugins(manifest: PluginManifest, installed: InstalledPlugin[], managedSlugs?: Set<string>): PluginDiff;
+export declare function lockedWpackagistSlugs(composerLock: null | string, kind: 'plugin' | 'theme'): Set<string>;