@loopress/cli 0.7.0 → 0.9.0

package/dist/lib/sentry.js

@@ -0,0 +1,24 @@
+import { platform, release } from 'node:os';
+// DSNs are write-only and safe to embed in a distributed CLI, see https://docs.sentry.io/product/security/#can-i-make-my-sentry-dsn-private
+export const SENTRY_DSN = 'https://a08dd56bfffc2a45d5b8f665e4cb8b7d@o4511586904309760.ingest.de.sentry.io/4511673275973712';
+export function consumeErrorReportingFlag(argv) {
+    const index = argv.indexOf('--no-error-reporting');
+    if (index === -1)
+        return;
+    argv.splice(index, 1);
+    process.env.LOOPRESS_TELEMETRY_DISABLED = '1';
+}
+export function isTelemetryDisabled() {
+    return process.env.LOOPRESS_TELEMETRY_DISABLED === '1';
+}
+export function resolveEnvironment() {
+    if (process.env.SENTRY_ENVIRONMENT)
+        return process.env.SENTRY_ENVIRONMENT;
+    return process.env.NODE_ENV === 'development' ? 'development' : 'production';
+}
+export function runtimeContext() {
+    return {
+        node: process.version,
+        os: `${platform()} ${release()}`,
+    };
+}

package/dist/lib/wp-client.d.ts

@@ -0,0 +1,15 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/**
+ * HTTP client for a WordPress site's REST API.
+ * Paths are relative to `<site>/wp-json/`, e.g. `loopress/v1/plugins`.
+ */
+export declare class WpClient {
+    private readonly siteUrl;
+    private readonly client;
+    constructor(siteUrl: string, token: string);
+    get<T>(path: string): Promise<T>;
+    post<T = unknown>(path: string, json?: Record<string, unknown>): Promise<T>;
+    put<T = unknown>(path: string, json?: Record<string, unknown>): Promise<T>;
+    private request;
+}
+export declare function formatWpError(error: unknown, url: string): string;

package/dist/lib/wp-client.js

@@ -0,0 +1,53 @@
+import got from 'got';
+export const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * HTTP client for a WordPress site's REST API.
+ * Paths are relative to `<site>/wp-json/`, e.g. `loopress/v1/plugins`.
+ */
+export class WpClient {
+    siteUrl;
+    client;
+    constructor(siteUrl, token) {
+        this.siteUrl = siteUrl;
+        this.client = got.extend({
+            headers: { Authorization: `Basic ${Buffer.from(token).toString('base64')}` },
+            prefixUrl: `${siteUrl}/wp-json`,
+            timeout: { request: REQUEST_TIMEOUT_MS },
+        });
+    }
+    async get(path) {
+        return this.request('get', path);
+    }
+    async post(path, json) {
+        return this.request('post', path, json);
+    }
+    async put(path, json) {
+        return this.request('put', path, json);
+    }
+    async request(method, path, json) {
+        try {
+            const response = await this.client(path, { json, method });
+            return (response.body ? JSON.parse(response.body) : undefined);
+        }
+        catch (error) {
+            throw new Error(formatWpError(error, `${this.siteUrl}/wp-json/${path}`), { cause: error });
+        }
+    }
+}
+export function formatWpError(error, url) {
+    const err = error;
+    const status = err.response?.statusCode;
+    if (status === 401 || status === 403) {
+        return `Authentication failed (${status}) on ${url}. Check your credentials with \`lps project config\`.`;
+    }
+    if (status === 404) {
+        return `Endpoint not found (404) on ${url}. Is the required plugin installed and up to date on the site?`;
+    }
+    if (status !== undefined) {
+        return `Request failed (${status}) on ${url}.`;
+    }
+    if (err.name === 'TimeoutError') {
+        return `Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s on ${url}. Is the site reachable?`;
+    }
+    return `Request to ${url} failed: ${err.message ?? String(error)}`;
+}

package/dist/types/config.d.ts

@@ -0,0 +1 @@
+export type { CurrentProjectPointer, EnvironmentConfig, LoopressGlobalConfiguration as LoopressConfig, ProjectConfig, } from './global-config.generated.js';

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

@@ -0,0 +1,59 @@
+/**
+ * Global CLI state stored at ~/.loopress/config.json: known projects, their environments, and which one is currently active.
+ */
+export interface LoopressGlobalConfiguration {
+    /**
+     * Pointer to the currently active project and environment, or null if none is selected.
+     */
+    currentProject: null | CurrentProjectPointer;
+    /**
+     * Known projects, keyed by project id.
+     */
+    projects: {
+        [k: string]: ProjectConfig;
+    };
+}
+export interface CurrentProjectPointer {
+    /**
+     * Name of the currently active environment.
+     */
+    env: string;
+    /**
+     * Id of the currently active project.
+     */
+    id: string;
+}
+export interface ProjectConfig {
+    /**
+     * ISO timestamp of when the project was added.
+     */
+    addedAt: string;
+    /**
+     * Environments for this project, keyed by environment name.
+     */
+    environments: {
+        [k: string]: EnvironmentConfig;
+    };
+    /**
+     * Human-readable project name.
+     */
+    name: string;
+}
+export interface EnvironmentConfig {
+    /**
+     * ISO timestamp of when the environment was added.
+     */
+    addedAt: string;
+    /**
+     * Environment name (e.g. "production", "staging").
+     */
+    name: string;
+    /**
+     * API token used to authenticate against this environment.
+     */
+    token?: string;
+    /**
+     * Base URL of the WordPress site for this environment.
+     */
+    url: string;
+}

package/dist/types/global-config.generated.js

@@ -0,0 +1,2 @@
+// This file is generated from schemas/global-config.schema.json by `pnpm run schema:types`. Do not edit by hand.
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * Project-level config for the Loopress CLI (loopress.json).
+ */
+export interface LoopressProjectConfiguration {
+    $schema?: string;
+    /**
+     * Base directory for all Loopress paths. All other path options are resolved relative to this directory.
+     */
+    rootDir?: string;
+    /**
+     * Directory where code snippets are read from and written to, relative to rootDir.
+     */
+    snippetsDir?: string;
+    /**
+     * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
+     */
+    projectId?: string;
+    /**
+     * WordPress snippet plugin to use for pull and push commands.
+     */
+    snippetPlugin?: 'wpcode' | 'code-snippets';
+    /**
+     * Pinned plugin versions. Keys are WordPress.org plugin slugs, values are version constraints.
+     */
+    plugins?: {
+        /**
+         * Version to pin. Use an exact version (e.g. "8.9.1") or "latest".
+         */
+        [k: string]: string;
+    };
+}

package/dist/types/project-config.generated.js

@@ -0,0 +1,2 @@
+// This file is generated from schemas/project-config.schema.json by `pnpm run schema:types`. Do not edit by hand.
+export {};

package/dist/types/snippet.d.ts

@@ -1,8 +1,14 @@
-import { SnippetType } from '../utils/snippet-plugin.js';
+import { SnippetInsertMethod, SnippetLocation, SnippetType } from '../utils/snippet-plugin.js';
 export interface Snippet {
+    active: boolean;
     code: string;
     id?: number;
+    insertMethod: SnippetInsertMethod;
+    location: SnippetLocation;
     name: string;
     path: string;
+    priority: number;
+    shortcodeAttributes: string[];
+    tags: string[];
     type: SnippetType;
 }

package/dist/types/snippet.generated.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Sidecar .json file paired with a snippet's code file in the snippets directory (e.g. `123-my-snippet.php` + `123-my-snippet.json`).
+ */
+export interface LoopressSnippetMetadata {
+    $schema?: string;
+    /**
+     * Remote snippet id. Omitted until the snippet has been pushed for the first time.
+     */
+    id?: number;
+    /**
+     * Snippet name/title. Defaults to the code file's name when omitted.
+     */
+    name?: string;
+    /**
+     * Snippet language. Defaults to the type inferred from the code file's extension when omitted.
+     */
+    type?: 'css' | 'html' | 'js' | 'php' | 'text';
+    /**
+     * Whether the snippet is enabled.
+     */
+    active?: boolean;
+    /**
+     * Where the snippet runs. Supported values depend on the target plugin and snippet type.
+     */
+    location?: 'admin' | 'body' | 'everywhere' | 'footer' | 'frontend' | 'header' | 'once';
+    /**
+     * Free-text note about the snippet.
+     */
+    description?: string;
+    /**
+     * Tags for organizing snippets.
+     */
+    tags?: string[];
+    /**
+     * How the snippet is inserted into the page.
+     */
+    insertMethod?: 'auto' | 'shortcode';
+    /**
+     * Execution priority. Lower runs earlier.
+     */
+    priority?: number;
+    /**
+     * Attribute names accepted by the snippet's shortcode, used when insertMethod is "shortcode".
+     */
+    shortcodeAttributes?: string[];
+}

package/dist/types/snippet.generated.js

@@ -0,0 +1,2 @@
+// This file is generated from schemas/snippet.schema.json by `pnpm run schema:types`. Do not edit by hand.
+export {};

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

@@ -1,9 +1,4 @@
-export interface LoopressLocalConfig {
-    plugins?: Record<string, string>;
-    projectId?: string;
-    rootDir?: string;
-    snippetPlugin?: 'code-snippets' | 'wpcode';
-    snippetsDir?: string;
-}
+import { LoopressProjectConfiguration } from '../types/project-config.generated.js';
+export type LoopressLocalConfig = LoopressProjectConfiguration;
 export declare function readLocalConfig(): Promise<LoopressLocalConfig>;
 export declare function writeLocalConfig(config: LoopressLocalConfig): Promise<void>;

package/dist/utils/loopress-config.js

@@ -1,16 +1,19 @@
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+// Only a missing file is treated as "no config" (returns {}). A file that exists but
+// fails to read or parse throws, so callers don't silently fall back to the global
+// current environment when loopress.json is actually broken.
 export async function readLocalConfig() {
     const configPath = join(process.cwd(), 'loopress.json');
     if (!existsSync(configPath))
         return {};
+    const content = await readFile(configPath, 'utf8');
     try {
-        const content = await readFile(configPath, 'utf8');
         return JSON.parse(content);
     }
     catch {
-        return {};
+        throw new Error('loopress.json is not valid JSON. Fix or delete it, then run `lps init` again.');
     }
 }
 export async function writeLocalConfig(config) {

package/dist/utils/snippet-plugin-flag.d.ts

@@ -0,0 +1,3 @@
+export declare const snippetPluginFlag: {
+    plugin: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};

package/dist/utils/snippet-plugin-flag.js

@@ -0,0 +1,8 @@
+import { Flags } from '@oclif/core';
+export const snippetPluginFlag = {
+    plugin: Flags.string({
+        char: 'p',
+        description: 'WordPress snippet plugin to target (overrides loopress.json)',
+        options: ['code-snippets', 'wpcode'],
+    }),
+};

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

@@ -1,18 +1,39 @@
 export type PluginName = 'code-snippets' | 'wpcode';
 export type SnippetType = 'css' | 'html' | 'js' | 'php' | 'text';
+export type SnippetInsertMethod = 'auto' | 'shortcode';
+export type SnippetLocation = 'admin' | 'body' | 'everywhere' | 'footer' | 'frontend' | 'header' | 'once';
 export interface NormalizedSnippet {
     active: boolean;
     code: string;
     description: string;
     id: number;
+    insertMethod: SnippetInsertMethod;
+    location: SnippetLocation;
     name: string;
+    priority: number;
+    shortcodeAttributes: string[];
     tags: string[];
     type: SnippetType;
 }
 export declare function parseType(raw: unknown): null | SnippetType;
+export declare function parseLocation(raw: unknown): null | SnippetLocation;
+export declare function parseInsertMethod(raw: unknown): null | SnippetInsertMethod;
+export declare function defaultLocationForType(type: SnippetType): SnippetLocation;
+export interface SnippetPayloadInput {
+    active: boolean;
+    code: string;
+    insertMethod: SnippetInsertMethod;
+    location: SnippetLocation;
+    name: string;
+    path: string;
+    priority: number;
+    shortcodeAttributes: string[];
+    tags: string[];
+    type: SnippetType;
+}
 export interface SnippetPlugin {
-    endpoint(siteUrl: string): string;
+    endpointPath(): string;
     fromRemote(data: Record<string, unknown>): NormalizedSnippet;
-    toPayload(name: string, code: string, path: string, type: SnippetType): Record<string, unknown>;
+    toPayload(snippet: SnippetPayloadInput): Record<string, unknown>;
 }
 export declare function getSnippetPlugin(name: PluginName): SnippetPlugin;

package/dist/utils/snippet-plugin.js

@@ -3,6 +3,30 @@ export function parseType(raw) {
     const value = String(raw ?? '').toLowerCase();
     return valid.includes(value) ? value : null;
 }
+const VALID_LOCATIONS = new Set(['admin', 'body', 'everywhere', 'footer', 'frontend', 'header', 'once']);
+export function parseLocation(raw) {
+    const value = String(raw ?? '').toLowerCase();
+    return VALID_LOCATIONS.has(value) ? value : null;
+}
+export function parseInsertMethod(raw) {
+    return raw === 'auto' || raw === 'shortcode' ? raw : null;
+}
+// The sensible default placement for a freshly pushed snippet that doesn't specify a location.
+export function defaultLocationForType(type) {
+    switch (type) {
+        case 'css': {
+            return 'header';
+        }
+        case 'html':
+        case 'js':
+        case 'text': {
+            return 'footer';
+        }
+        case 'php': {
+            return 'everywhere';
+        }
+    }
+}
 function inferTypeFromCode(code) {
     const firstLine = code.trimStart().split('\n')[0].trimStart();
     if (firstLine.startsWith('<?'))
@@ -14,53 +38,184 @@ function inferTypeFromCode(code) {
 function resolveType(raw, code) {
     return parseType(raw) ?? inferTypeFromCode(code);
 }
+function resolvePriority(raw) {
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : 10;
+}
+// Snippet files on disk keep the <?php opening tag so they're valid, syntax-highlighted PHP files.
+// Both plugins store just the executable body, so it's stripped before push and restored on pull
+// (see buildSnippetFile in commands/snippet/pull.ts).
+function stripPhpOpeningTag(code) {
+    return code.replace(/^<\?php\s*/i, '');
+}
+// The real Code Snippets plugin has no independent "type" field: its REST API only has `scope`,
+// and the snippet type is derived from it (see WPCode_Snippet::get_type_from_scope() upstream).
+// Sending a `type` key (as this adapter used to) is silently ignored by that plugin.
+const CODE_SNIPPETS_SCOPE_TO_LOCATION = {
+    admin: 'admin',
+    'admin-css': 'admin',
+    content: 'everywhere',
+    'footer-content': 'footer',
+    'front-end': 'frontend',
+    global: 'everywhere',
+    'head-content': 'header',
+    'single-use': 'once',
+    'site-css': 'frontend',
+    'site-footer-js': 'footer',
+    'site-head-js': 'header',
+};
+function typeFromScope(scope) {
+    if (scope.endsWith('-css'))
+        return 'css';
+    if (scope.endsWith('-js'))
+        return 'js';
+    if (scope.endsWith('content'))
+        return 'html';
+    return 'php';
+}
+function scopeFromTypeAndLocation(type, location) {
+    switch (type) {
+        case 'css': {
+            if (location === 'frontend')
+                return 'site-css';
+            if (location === 'admin')
+                return 'admin-css';
+            throw new Error(`Code Snippets does not support the "${location}" location for CSS snippets. Use one of: frontend, admin.`);
+        }
+        case 'html': {
+            if (location === 'header')
+                return 'head-content';
+            if (location === 'footer')
+                return 'footer-content';
+            if (location === 'everywhere')
+                return 'content';
+            throw new Error(`Code Snippets does not support the "${location}" location for HTML snippets. Use one of: header, footer, everywhere.`);
+        }
+        case 'js': {
+            if (location === 'header')
+                return 'site-head-js';
+            if (location === 'footer')
+                return 'site-footer-js';
+            throw new Error(`Code Snippets does not support the "${location}" location for JS snippets. Use one of: header, footer.`);
+        }
+        case 'php': {
+            if (location === 'everywhere')
+                return 'global';
+            if (location === 'frontend')
+                return 'front-end';
+            if (location === 'admin')
+                return 'admin';
+            if (location === 'once')
+                return 'single-use';
+            throw new Error(`Code Snippets does not support the "${location}" location for PHP snippets. Use one of: everywhere, frontend, admin, once.`);
+        }
+        case 'text': {
+            throw new Error('Code Snippets has no "text" snippet type. Change the sidecar "type", or push this snippet to "wpcode" instead.');
+        }
+    }
+}
 class CodeSnippetsPlugin {
-    endpoint(siteUrl) {
-        return `${siteUrl}/wp-json/code-snippets/v1/snippets`;
+    endpointPath() {
+        return 'code-snippets/v1/snippets';
     }
     fromRemote(data) {
+        const scope = String(data.scope ?? 'global');
+        const type = typeFromScope(scope);
         return {
             active: Boolean(data.active),
             code: String(data.code ?? ''),
             description: String(data.desc ?? ''),
             id: Number(data.id),
+            insertMethod: 'auto',
+            location: CODE_SNIPPETS_SCOPE_TO_LOCATION[scope] ?? defaultLocationForType(type),
             name: String(data.name ?? ''),
+            priority: resolvePriority(data.priority),
+            shortcodeAttributes: [],
             tags: Array.isArray(data.tags) ? data.tags : [],
-            type: resolveType(data.type, String(data.code ?? '')),
+            type,
         };
     }
-    toPayload(name, code, path, type) {
+    toPayload({ active, code, location, name, path, priority, tags, type }) {
         return {
-            code: code.replace(/^<\?php\s*/i, ''),
+            active,
+            code: stripPhpOpeningTag(code),
             desc: `Imported from ${path}`,
             name,
-            tags: ['cli-import'],
-            type,
+            priority,
+            scope: scopeFromTypeAndLocation(type, location),
+            tags,
         };
     }
 }
+// WPCode taxonomy term slugs (see wpcode_register_taxonomies() and the auto-insert location
+// classes upstream). 'everywhere' | 'frontend_only' | 'admin_only' | 'on_demand' only apply to
+// PHP snippets; 'site_wide_header' | 'site_wide_body' | 'site_wide_footer' apply to any type.
+const WPCODE_PHP_ONLY_LOCATIONS = {
+    admin: 'admin_only',
+    everywhere: 'everywhere',
+    frontend: 'frontend_only',
+    once: 'on_demand',
+};
+const WPCODE_UNIVERSAL_LOCATIONS = {
+    body: 'site_wide_body',
+    footer: 'site_wide_footer',
+    header: 'site_wide_header',
+};
+const WPCODE_LOCATION_TO_CANONICAL = {
+    'admin_only': 'admin',
+    everywhere: 'everywhere',
+    'frontend_only': 'frontend',
+    'on_demand': 'once',
+    'site_wide_body': 'body',
+    'site_wide_footer': 'footer',
+    'site_wide_header': 'header',
+};
+function wpcodeLocationTerm(type, location) {
+    const universal = WPCODE_UNIVERSAL_LOCATIONS[location];
+    if (universal)
+        return universal;
+    if (type === 'php') {
+        const phpOnly = WPCODE_PHP_ONLY_LOCATIONS[location];
+        if (phpOnly)
+            return phpOnly;
+    }
+    const allowed = type === 'php' ? 'header, body, footer, everywhere, frontend, admin, once' : 'header, body, footer';
+    throw new Error(`WPCode does not support the "${location}" location for ${type} snippets. Use one of: ${allowed}.`);
+}
 class WPCodePlugin {
-    endpoint(siteUrl) {
-        return `${siteUrl}/wp-json/loopress/v1/wpcode/snippets`;
+    endpointPath() {
+        return 'loopress/v1/wpcode/snippets';
     }
     fromRemote(data) {
+        const type = resolveType(data.type, String(data.code ?? ''));
         return {
             active: Boolean(data.active),
             code: String(data.code ?? ''),
             description: String(data.note ?? ''),
             id: Number(data.id),
+            insertMethod: data.insert_method === 'shortcode' ? 'shortcode' : 'auto',
+            location: WPCODE_LOCATION_TO_CANONICAL[String(data.location)] ?? defaultLocationForType(type),
             name: String(data.title ?? ''),
+            priority: resolvePriority(data.priority),
+            shortcodeAttributes: Array.isArray(data.shortcode_attributes) ? data.shortcode_attributes.map(String) : [],
             tags: Array.isArray(data.tags) ? data.tags : [],
-            type: resolveType(data.type, String(data.code ?? '')),
+            type,
         };
     }
-    toPayload(name, code, path, type) {
+    toPayload({ active, code, insertMethod, location, name, path, priority, shortcodeAttributes, tags, type, }) {
+        const placement = insertMethod === 'shortcode'
+            ? { 'shortcode_attributes': shortcodeAttributes }
+            : { location: wpcodeLocationTerm(type, location) };
         return {
-            code,
+            active,
+            code: stripPhpOpeningTag(code),
             note: `Imported from ${path}`,
-            tags: ['cli-import'],
+            priority,
+            tags,
             title: name,
             type,
+            ...placement,
+            'insert_method': insertMethod,
         };
     }
 }