@loopress/cli 0.26.0 → 0.28.0

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/resource-state.js

@@ -4,9 +4,10 @@ import { ACF_OBJECT_TYPES, acfEndpoint, getAcfKey } from '../utils/acf-format.js
 import { FORM_ENDPOINT, getFormId } from '../utils/form-format.js';
 import { getMenuSlug, MENU_ENDPOINT, MENU_LOCATIONS_ENDPOINT } from '../utils/menu-format.js';
 import { optionEndpoint, parseLocalOption } from '../utils/option-format.js';
-import { formatPageProblems, PAGES_ENDPOINT, readLocalPages } from '../utils/page-format.js';
+import { formatPageProblems, PAGES_ENDPOINT, readLocalHtmlFiles, readLocalPages } from '../utils/page-format.js';
 import { DEFAULT_POST_TYPES, SEO_REDIRECTS_ENDPOINT, SEO_SETTINGS_ENDPOINT, seoPostMetaEndpoint, } from '../utils/seo-format.js';
 import { normalizeSnippet, SNIPPETS_ENDPOINT, stripPhpOpeningTag } from '../utils/snippet-format.js';
+import { CHILD_THEME_ENDPOINT, parsePartFile, parseTemplateFile } from '../utils/template-format.js';
 import { canonicalGlobalStyles, getActiveThemeGlobalStyles, globalStylesEndpoint, THEME_STYLES_FILE_SUFFIX, } from '../utils/theme-styles-format.js';
 import { loadFiles } from './load-files.js';
 import { loadSnippets } from './load-snippets.js';
@@ -217,6 +218,45 @@ const pageProvider = {
     resource: 'page',
     title: 'Pages',
 };
+// ---- Templates and parts ---------------------------------------------------------------
+// Both live in the Loopress child theme (ChildThemeController), one GET answers for both. A
+// template or part edited in the Site Editor gets `siteEditor: 'customized'` on the remote side
+// only, so it always shows as drift: its database copy is what the site renders, not the file.
+async function childThemeState(wp, kind) {
+    const child = await wp.get(CHILD_THEME_ENDPOINT);
+    const files = child[kind];
+    const state = new Map(files.map(({ slug, ...rest }) => [slug, rest]));
+    for (const entry of child.customized) {
+        const [dir, slug] = entry.split('/', 2);
+        if (dir === kind)
+            state.set(slug, { ...state.get(slug), siteEditor: 'customized' });
+    }
+    return state;
+}
+const templateProvider = {
+    dirKind: 'template',
+    async local(dir) {
+        const { files, problems } = await readLocalHtmlFiles(dir, parseTemplateFile);
+        if (problems.length > 0)
+            throw new Error(formatPageProblems(problems));
+        return new Map(files.map(({ slug, ...rest }) => [slug, rest]));
+    },
+    remote: async (wp) => childThemeState(wp, 'templates'),
+    resource: 'template',
+    title: 'Templates',
+};
+const partProvider = {
+    dirKind: 'part',
+    async local(dir) {
+        const { files, problems } = await readLocalHtmlFiles(dir, parsePartFile);
+        if (problems.length > 0)
+            throw new Error(formatPageProblems(problems));
+        return new Map(files.map(({ slug, ...rest }) => [slug, rest]));
+    },
+    remote: async (wp) => childThemeState(wp, 'parts'),
+    resource: 'part',
+    title: 'Template parts',
+};
 // ---- SEO --------------------------------------------------------------------------------
 function canonicalRedirect(redirect) {
     return omit(redirect, REDIRECT_VOLATILE_KEYS);
@@ -426,6 +466,8 @@ export const RESOURCE_STATE_PROVIDERS = [
     acfProvider,
     apiProvider,
     hookProvider,
+    templateProvider,
+    partProvider,
     pageProvider,
     seoProvider,
     menuProvider,

package/dist/lib/rollback-command.d.ts

@@ -16,6 +16,7 @@ export type RollbackResult = {
     status: 'dry-run' | 'listed' | 'no-op' | 'success';
 };
 export declare function resourceRollbackCommand(resource: string, options: {
+    command?: string;
     description: string;
     pathNoun: string;
 }): typeof LoopressCommand;

package/dist/lib/rollback-command.js

@@ -33,7 +33,9 @@ function indentPatch(patch) {
 // anything, this runs the equivalent of `lps <resource> diff` between the environment's current
 // state and the state the original push expected to leave behind, and requires explicit
 // confirmation (the same interactive/`--yes` shape as guardProductionPush) when they differ.
+// `command` is the CLI topic when it isn't the resource key (e.g. `theme style` for theme-styles).
 export function resourceRollbackCommand(resource, options) {
+    const command = options.command ?? resource;
     class ResourceRollback extends LoopressCommand {
         static args = {
             path: Args.string({ description: `Path to ${options.pathNoun} (overrides project config)` }),
@@ -41,10 +43,10 @@ export function resourceRollbackCommand(resource, options) {
         static description = options.description;
         static enableJsonFlag = true;
         static examples = [
-            `$ lps ${resource} rollback`,
-            `$ lps ${resource} rollback --list`,
-            `$ lps ${resource} rollback --to 1732000000000`,
-            `$ lps ${resource} rollback --dry-run`,
+            `$ lps ${command} rollback`,
+            `$ lps ${command} rollback --list`,
+            `$ lps ${command} rollback --to 1732000000000`,
+            `$ lps ${command} rollback --dry-run`,
         ];
         static flags = {
             ...LoopressCommand.dryRunFlag,
@@ -105,7 +107,7 @@ export function resourceRollbackCommand(resource, options) {
             // an item present now but absent from the snapshot stays present after "restoring" it.
             if (restoreDiff.removed.length > 0) {
                 this.warn(`${pluralize(restoreDiff.removed.length, 'item')} present now but not in this snapshot will NOT be removed ` +
-                    `(${restoreDiff.removed.join(', ')}): restoring only creates and updates, the same as \`lps ${resource} push\`. Remove ${restoreDiff.removed.length === 1 ? 'it' : 'them'} by hand if that's part of undoing the original push.`);
+                    `(${restoreDiff.removed.join(', ')}): restoring only creates and updates, the same as \`lps ${command} push\`. Remove ${restoreDiff.removed.length === 1 ? 'it' : 'them'} by hand if that's part of undoing the original push.`);
             }
             if (this.dryRun) {
                 return { drift: driftSummary, id: snapshot.id, restored: summarize(restoreDiff), status: 'dry-run' };
@@ -125,7 +127,7 @@ export function resourceRollbackCommand(resource, options) {
                 // production guard and the drift confirmation above already covered what the delegated
                 // push's own guard would ask again, same reasoning as the top-level `lps push`
                 // delegating to each resource's push command in commands/push.ts.
-                await this.config.runCommand(`${resource}:push`, [tmpDir, '--env', this.siteConfig.name, '--yes']);
+                await this.config.runCommand(`${command.replaceAll(' ', ':')}:push`, [tmpDir, '--env', this.siteConfig.name, '--yes']);
             }
             finally {
                 // A cleanup failure here must never hide a real error from the push above: warn about

package/dist/lib/rotate-app-password.js

@@ -8,14 +8,14 @@ export function isAppPasswordStale(addedAt) {
 // the old one. Reversing this order risks locking the user out if the new one is somehow bad.
 export async function rotateAppPassword(env) {
     const [user] = env.token.split(':', 1);
-    const oldClient = new WpClient(env.url, env.token);
+    const oldClient = new WpClient(env.url, env.token, env.name);
     const old = await oldClient.get(`${APPLICATION_PASSWORDS_PATH}/introspect`);
     const created = await oldClient.post(APPLICATION_PASSWORDS_PATH, { name: 'Loopress' });
     if (!created.password) {
         throw new Error(`WordPress did not return a password when creating the new application password on ${env.url}.`);
     }
     const newToken = `${user}:${created.password}`;
-    const newClient = new WpClient(env.url, newToken);
+    const newClient = new WpClient(env.url, newToken, env.name);
     try {
         await newClient.get(`${APPLICATION_PASSWORDS_PATH}/introspect`);
     }

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,28 @@
 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 { readLocalTemplates } from '../utils/template-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',
+    partDir: 'parts',
     seoDir: 'seo',
     snippetsDir: 'snippets',
+    templateDir: 'templates',
+    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,12 +43,18 @@ 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);
+    const templates = await readLocalTemplates(resolve('templateDir'), resolve('partDir'));
+    checked += templates.templates.length + templates.parts.length + templates.problems.length;
+    problems.push(...templates.problems);
     return { checked, problems, valid: problems.length === 0 };
 }
 // Recursive: both api/ and hooks/ files can live in a nested path-segment directory
@@ -91,15 +103,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 +127,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.d.ts

@@ -1,4 +1,7 @@
 export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const LOCAL_ENVIRONMENT_NAME = "local";
+export declare function isLocalEnvironment(environmentName: string | undefined): boolean;
+export declare function assertSecureSiteUrl(siteUrl: string, environmentName: string | undefined): void;
 /**
  * HTTP client for a WordPress site's REST API.
  * Paths are relative to `<site>/wp-json/`, e.g. `loopress/v1/snippets` or `wp/v2/plugins`.
@@ -6,7 +9,7 @@ export declare const REQUEST_TIMEOUT_MS = 30000;
 export declare class WpClient {
     private readonly siteUrl;
     private readonly client;
-    constructor(siteUrl: string, token: string);
+    constructor(siteUrl: string, token: string, environmentName?: string);
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
     getAll<T>(path: string, options?: RequestOptions & {

package/dist/lib/wp-client.js

@@ -1,6 +1,29 @@
 import got from 'got';
 import { Buffer } from 'node:buffer';
 export const REQUEST_TIMEOUT_MS = 30_000;
+// The one environment allowed to talk plain HTTP: Loopress's local dev environment, identified
+// by its config name (the same "local" environment `lps dev` targets), never by the URL's host.
+// Locality is a property of the configured environment, not of a hostname, so a real remote site
+// can never opt into cleartext just by resolving to a `.local`/loopback-looking name.
+export const LOCAL_ENVIRONMENT_NAME = 'local';
+export function isLocalEnvironment(environmentName) {
+    return environmentName === LOCAL_ENVIRONMENT_NAME;
+}
+// Throws when a URL would send credentials in cleartext: http:// for any environment other than
+// the local one. The trust boundary is here, at the client, so a hand-edited config.json or
+// loopress.json cannot bypass the check the interactive prompt also applies.
+export function assertSecureSiteUrl(siteUrl, environmentName) {
+    let parsed;
+    try {
+        parsed = new URL(siteUrl);
+    }
+    catch {
+        throw new Error(`Invalid site URL: ${siteUrl}`);
+    }
+    if (parsed.protocol === 'http:' && !isLocalEnvironment(environmentName)) {
+        throw new Error(`Refusing to send credentials over plain HTTP for the "${environmentName ?? 'unknown'}" environment: the Application Password would travel in cleartext. Use HTTPS. Plain HTTP is allowed only for the "${LOCAL_ENVIRONMENT_NAME}" environment.`);
+    }
+}
 /**
  * HTTP client for a WordPress site's REST API.
  * Paths are relative to `<site>/wp-json/`, e.g. `loopress/v1/snippets` or `wp/v2/plugins`.
@@ -8,8 +31,9 @@ export const REQUEST_TIMEOUT_MS = 30_000;
 export class WpClient {
     siteUrl;
     client;
-    constructor(siteUrl, token) {
+    constructor(siteUrl, token, environmentName) {
         this.siteUrl = siteUrl;
+        assertSecureSiteUrl(siteUrl, environmentName);
         this.client = got.extend({
             headers: { Authorization: `Basic ${Buffer.from(token).toString('base64')}` },
             prefixUrl: `${siteUrl}/wp-json`,
@@ -107,6 +131,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 +155,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. `&amp;` last, so "&amp;quot;" stays a literal "&quot;".
+function decodeEntities(text) {
+    return text
+        .replaceAll('&quot;', '"')
+        .replaceAll('&#039;', "'")
+        .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 +184,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 +198,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/plugin.d.ts

@@ -12,4 +12,11 @@ export type WpNativePlugin = {
     status: 'active' | 'inactive' | 'network-active';
     version: string;
 };
-export type PluginManifest = Record<string, string>;
+export type PluginPin = string | {
+    active?: boolean;
+    version: string;
+};
+export type PluginManifest = Record<string, PluginPin>;
+export declare const pinVersion: (pin: PluginPin) => string;
+export declare const pinActive: (pin: PluginPin) => boolean;
+export declare const pinVersions: (manifest: PluginManifest) => Record<string, string>;

package/dist/types/plugin.js

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

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

@@ -39,6 +39,14 @@ export interface LoopressProjectConfiguration {
      * Directory where static HTML pages (one <slug>.html per WordPress page, managed by Loopress) are read from, relative to rootDir.
      */
     pageDir?: string;
+    /**
+     * Directory where block templates (one <slug>.html per template, written to the Loopress child theme of the active block theme) are read from, relative to rootDir. A static page uses one with its `template` header.
+     */
+    templateDir?: string;
+    /**
+     * Directory where block template parts (one <slug>.html per part, written to the Loopress child theme of the active block theme) are read from, relative to rootDir.
+     */
+    partDir?: 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.
      */
@@ -56,10 +64,19 @@ export interface LoopressProjectConfiguration {
      */
     projectId?: string;
     /**
-     * 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).
+     * 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, and the plugin is kept active. An object with "active": false keeps the plugin installed but inactive. 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;
+        [k: string]: string | {
+            /**
+             * Exact version to pin, or "latest".
+             */
+            version: string;
+            /**
+             * false keeps the plugin installed but inactive. Defaults to true.
+             */
+            active?: boolean;
+        };
     };
     /**
      * WordPress.org themes managed by Loopress, installed via Composer + WPackagist on the site. Keys are theme slugs; values are an exact version or "latest". Loopress manages installed theme versions only, it never switches the active theme. Ignored when a composer.json exists in rootDir.

package/dist/utils/composer.d.ts

@@ -1,3 +1,5 @@
+import { type SyncIntent } from './plugin-sync.js';
+import { type MergeResult } from './plugins.js';
 export type ComposerJson = {
     config?: {
         'allow-plugins'?: Record<string, boolean>;
@@ -16,3 +18,15 @@ export type ComposerJson = {
 export declare function readComposerJson(): Promise<ComposerJson | null>;
 export declare function readComposerLock(): Promise<null | string>;
 export declare function getComposerManagedSlugs(composerJson: ComposerJson): string[];
+export type ComposerPullResult = MergeResult<string> & {
+    skipped: Array<{
+        reason: string;
+        slug: string;
+    }>;
+};
+export declare function pullIntoComposerJson(path: string, kind: 'plugin' | 'theme', incoming: Record<string, string>, { dryRun, log }: {
+    dryRun: boolean;
+    log: (message: string) => void;
+}): Promise<ComposerPullResult>;
+export declare function toIntent(require: Record<string, string>): SyncIntent;
+export declare function wpackagistRequire(composerJson: ComposerJson, kind: 'plugin' | 'theme'): Record<string, string>;