@loopress/cli 0.9.0 → 0.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loopress/cli",
   "description": "CLI tool for syncing WordPress code snippets, plugins, and Composer dependencies via the REST API",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "author": "jean-smaug",
   "bin": {
     "loopress": "bin/run.js",
@@ -26,6 +26,8 @@
     "@eslint/compat": "2.1.0",
     "@oclif/prettier-config": "^0.2.1",
     "@oclif/test": "^4.1.20",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "26.0.1",
     "@types/write-file-atomic": "^4.0.3",
     "@vitest/coverage-v8": "4.1.9",
@@ -36,6 +38,7 @@
     "oclif": "^4.23.24",
     "prettier": "3.9.4",
     "shx": "^0.4.0",
+    "ts-node": "10.9.2",
     "tsx": "4.22.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
@@ -46,6 +49,7 @@
   "files": [
     "./bin",
     "./dist",
+    "./schemas",
     "./oclif.manifest.json"
   ],
   "homepage": "https://github.com/loopress/loopress",
@@ -110,6 +114,8 @@
     "posttest": "pnpm run lint",
     "schema:types": "tsx scripts/generate-config-types.ts",
     "test": "vitest run",
+    "pretest:mutation": "pnpm run schema:types",
+    "test:mutation": "stryker run",
     "version": "oclif readme && git add README.md",
     "format": "prettier . --write"
   }

package/schemas/global-config.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loopress.dev/schema/global-config.json",
+  "title": "Loopress global configuration",
+  "description": "Global CLI state stored at ~/.loopress/config.json: known projects, their environments, and which one is currently active.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["currentProject", "projects"],
+  "properties": {
+    "currentProject": {
+      "description": "Pointer to the currently active project and environment, or null if none is selected.",
+      "oneOf": [{"type": "null"}, {"$ref": "#/definitions/CurrentProjectPointer"}]
+    },
+    "projects": {
+      "type": "object",
+      "description": "Known projects, keyed by project id.",
+      "additionalProperties": {"$ref": "#/definitions/ProjectConfig"}
+    }
+  },
+  "definitions": {
+    "CurrentProjectPointer": {
+      "title": "CurrentProjectPointer",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["env", "id"],
+      "properties": {
+        "env": {
+          "type": "string",
+          "description": "Name of the currently active environment."
+        },
+        "id": {
+          "type": "string",
+          "description": "Id of the currently active project."
+        }
+      }
+    },
+    "ProjectConfig": {
+      "title": "ProjectConfig",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["addedAt", "environments", "name"],
+      "properties": {
+        "addedAt": {
+          "type": "string",
+          "description": "ISO timestamp of when the project was added."
+        },
+        "apiProjectId": {
+          "type": "string",
+          "description": "Id of the matching project on the Loopress API, once synced via `lps project sync`."
+        },
+        "environments": {
+          "type": "object",
+          "description": "Environments for this project, keyed by environment name.",
+          "additionalProperties": {"$ref": "#/definitions/EnvironmentConfig"}
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable project name."
+        }
+      }
+    },
+    "EnvironmentConfig": {
+      "title": "EnvironmentConfig",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["addedAt", "name", "url"],
+      "properties": {
+        "addedAt": {
+          "type": "string",
+          "description": "ISO timestamp of when the environment was added."
+        },
+        "apiEnvironmentId": {
+          "type": "string",
+          "description": "Id of the matching environment on the Loopress API, once synced via `lps project sync`."
+        },
+        "name": {
+          "type": "string",
+          "description": "Environment name (e.g. \"production\", \"staging\")."
+        },
+        "token": {
+          "type": "string",
+          "description": "API token used to authenticate against this environment."
+        },
+        "url": {
+          "type": "string",
+          "description": "Base URL of the WordPress site for this environment."
+        }
+      }
+    }
+  }
+}

package/schemas/project-config.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loopress.dev/schema/project-config.json",
+  "title": "Loopress project configuration",
+  "description": "Project-level config for the Loopress CLI (loopress.json).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "rootDir": {
+      "type": "string",
+      "description": "Base directory for all Loopress paths. All other path options are resolved relative to this directory.",
+      "default": "."
+    },
+    "snippetsDir": {
+      "type": "string",
+      "description": "Directory where code snippets are read from and written to, relative to rootDir.",
+      "default": "snippets"
+    },
+    "projectId": {
+      "type": "string",
+      "description": "Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config."
+    },
+    "plugins": {
+      "type": "object",
+      "description": "Pinned plugin versions. Keys are WordPress.org plugin slugs, values are version constraints.",
+      "additionalProperties": {
+        "type": "string",
+        "description": "Version to pin. Use an exact version (e.g. \"8.9.1\") or \"latest\".",
+        "examples": ["8.9.1", "latest"]
+      },
+      "examples": [
+        {
+          "woocommerce": "8.9.1",
+          "contact-form-7": "latest"
+        }
+      ]
+    }
+  }
+}

package/schemas/snippet.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loopress.dev/schema/snippet.json",
+  "title": "Loopress snippet metadata",
+  "description": "Sidecar .json file paired with a snippet's code file in the snippets directory (e.g. `123-my-snippet.php` + `123-my-snippet.json`).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "id": {
+      "type": "integer",
+      "description": "Remote snippet id. Omitted until the snippet has been pushed for the first time."
+    },
+    "name": {
+      "type": "string",
+      "description": "Snippet name/title. Defaults to the code file's name when omitted."
+    },
+    "type": {
+      "type": "string",
+      "description": "Snippet language. Defaults to the type inferred from the code file's extension when omitted.",
+      "enum": ["css", "html", "js", "php", "text"]
+    },
+    "active": {
+      "type": "boolean",
+      "description": "Whether the snippet is enabled.",
+      "default": false
+    },
+    "location": {
+      "type": "string",
+      "description": "Where the snippet runs. Supported values depend on the target plugin and snippet type.",
+      "enum": ["admin", "body", "everywhere", "footer", "frontend", "header", "once"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Free-text note about the snippet."
+    },
+    "tags": {
+      "type": "array",
+      "description": "Tags for organizing snippets.",
+      "items": {"type": "string"}
+    },
+    "insertMethod": {
+      "type": "string",
+      "description": "How the snippet is inserted into the page.",
+      "enum": ["auto", "shortcode"],
+      "default": "auto"
+    },
+    "priority": {
+      "type": "integer",
+      "description": "Execution priority. Lower runs earlier.",
+      "default": 10
+    },
+    "shortcodeAttributes": {
+      "type": "array",
+      "description": "Attribute names accepted by the snippet's shortcode, used when insertMethod is \"shortcode\".",
+      "items": {"type": "string"}
+    }
+  }
+}

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

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

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

@@ -1,8 +0,0 @@
-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.js

@@ -1,232 +0,0 @@
-export function parseType(raw) {
-    const valid = ['css', 'html', 'js', 'php', 'text'];
-    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('<?'))
-        return 'php';
-    if (firstLine.startsWith('<'))
-        return 'html';
-    return 'php';
-}
-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 {
-    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,
-        };
-    }
-    toPayload({ active, code, location, name, path, priority, tags, type }) {
-        return {
-            active,
-            code: stripPhpOpeningTag(code),
-            desc: `Imported from ${path}`,
-            name,
-            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 {
-    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,
-        };
-    }
-    toPayload({ active, code, insertMethod, location, name, path, priority, shortcodeAttributes, tags, type, }) {
-        const placement = insertMethod === 'shortcode'
-            ? { 'shortcode_attributes': shortcodeAttributes }
-            : { location: wpcodeLocationTerm(type, location) };
-        return {
-            active,
-            code: stripPhpOpeningTag(code),
-            note: `Imported from ${path}`,
-            priority,
-            tags,
-            title: name,
-            type,
-            ...placement,
-            'insert_method': insertMethod,
-        };
-    }
-}
-export function getSnippetPlugin(name) {
-    switch (name) {
-        case 'wpcode': {
-            return new WPCodePlugin();
-        }
-        case 'code-snippets':
-        default: {
-            return new CodeSnippetsPlugin();
-        }
-    }
-}