wordpress-agent-kit 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/.agents/skills/wp-bootstrap/SKILL.md +314 -0
  2. package/.agents/skills/wp-bootstrap/references/composer-setup.md +275 -0
  3. package/.agents/skills/wp-bootstrap/references/monorepo-patterns.md +184 -0
  4. package/.agents/skills/wp-bootstrap/scripts/bootstrap.sh +151 -0
  5. package/.agents/skills/wp-bootstrap/scripts/detect-structure.mjs +466 -0
  6. package/.agents/skills/wp-bootstrap/scripts/package-wp.sh +173 -0
  7. package/.agents/skills/wp-bootstrap/scripts/playground-start.sh +148 -0
  8. package/.agents/skills/wp-bootstrap/scripts/playground-verify.sh +165 -0
  9. package/.agents/skills/wp-bootstrap/scripts/setup-github.sh +417 -0
  10. package/.agents/skills/wp-wpengine/SKILL.md +76 -12
  11. package/.agents/skills/wp-wpengine/references/github-actions-deploy.md +16 -9
  12. package/README.md +1 -1
  13. package/dist/cli.js +2 -0
  14. package/dist/commands/bootstrap.js +105 -0
  15. package/dist/lib/api.js +1 -0
  16. package/dist/lib/bootstrap.js +352 -0
  17. package/extensions/wp-agent-kit/index.ts +143 -3
  18. package/package.json +1 -1
  19. package/skills-custom/wp-bootstrap/SKILL.md +314 -0
  20. package/skills-custom/wp-bootstrap/references/composer-setup.md +275 -0
  21. package/skills-custom/wp-bootstrap/references/monorepo-patterns.md +184 -0
  22. package/skills-custom/wp-bootstrap/scripts/bootstrap.sh +151 -0
  23. package/skills-custom/wp-bootstrap/scripts/detect-structure.mjs +466 -0
  24. package/skills-custom/wp-bootstrap/scripts/package-wp.sh +173 -0
  25. package/skills-custom/wp-bootstrap/scripts/playground-start.sh +148 -0
  26. package/skills-custom/wp-bootstrap/scripts/playground-verify.sh +165 -0
  27. package/skills-custom/wp-bootstrap/scripts/setup-github.sh +417 -0
  28. package/skills-custom/wp-wpengine/SKILL.md +76 -12
  29. package/skills-custom/wp-wpengine/references/github-actions-deploy.md +16 -9
  30. package/.github/skills/blueprint/SKILL.md +0 -418
  31. package/.github/skills/wordpress-router/SKILL.md +0 -52
  32. package/.github/skills/wordpress-router/references/decision-tree.md +0 -55
  33. package/.github/skills/wp-abilities-api/SKILL.md +0 -108
  34. package/.github/skills/wp-abilities-api/references/delegate-helper-pattern.md +0 -241
  35. package/.github/skills/wp-abilities-api/references/domain-vs-projection.md +0 -113
  36. package/.github/skills/wp-abilities-api/references/error-code-vocabulary.md +0 -123
  37. package/.github/skills/wp-abilities-api/references/grouping-heuristic.md +0 -89
  38. package/.github/skills/wp-abilities-api/references/input-schema-gotchas.md +0 -265
  39. package/.github/skills/wp-abilities-api/references/php-registration.md +0 -94
  40. package/.github/skills/wp-abilities-api/references/plugin-family-patterns.md +0 -233
  41. package/.github/skills/wp-abilities-api/references/rest-api.md +0 -13
  42. package/.github/skills/wp-abilities-api/references/shared-core-service.md +0 -184
  43. package/.github/skills/wp-abilities-audit/SKILL.md +0 -199
  44. package/.github/skills/wp-abilities-audit/references/audit-schema.md +0 -300
  45. package/.github/skills/wp-abilities-audit/references/capability-gate-tracing.md +0 -197
  46. package/.github/skills/wp-abilities-audit/references/controller-enumeration.md +0 -116
  47. package/.github/skills/wp-abilities-verify/SKILL.md +0 -215
  48. package/.github/skills/wp-abilities-verify/references/annotation-correctness.md +0 -154
  49. package/.github/skills/wp-abilities-verify/references/audit-schema-validation.md +0 -131
  50. package/.github/skills/wp-abilities-verify/references/permission-roundtrip.md +0 -190
  51. package/.github/skills/wp-abilities-verify/references/runtime-harness.md +0 -462
  52. package/.github/skills/wp-abilities-verify/references/schema-lints.md +0 -118
  53. package/.github/skills/wp-abilities-verify/references/static-enumeration.md +0 -126
  54. package/.github/skills/wp-block-development/SKILL.md +0 -175
  55. package/.github/skills/wp-block-development/references/attributes-and-serialization.md +0 -22
  56. package/.github/skills/wp-block-development/references/block-json.md +0 -49
  57. package/.github/skills/wp-block-development/references/creating-new-blocks.md +0 -46
  58. package/.github/skills/wp-block-development/references/debugging.md +0 -36
  59. package/.github/skills/wp-block-development/references/deprecations.md +0 -24
  60. package/.github/skills/wp-block-development/references/dynamic-rendering.md +0 -23
  61. package/.github/skills/wp-block-development/references/inner-blocks.md +0 -25
  62. package/.github/skills/wp-block-development/references/registration.md +0 -30
  63. package/.github/skills/wp-block-development/references/supports-and-wrappers.md +0 -18
  64. package/.github/skills/wp-block-development/references/tooling-and-testing.md +0 -21
  65. package/.github/skills/wp-block-development/scripts/list_blocks.mjs +0 -121
  66. package/.github/skills/wp-block-themes/SKILL.md +0 -117
  67. package/.github/skills/wp-block-themes/references/creating-new-block-theme.md +0 -37
  68. package/.github/skills/wp-block-themes/references/debugging.md +0 -24
  69. package/.github/skills/wp-block-themes/references/patterns.md +0 -18
  70. package/.github/skills/wp-block-themes/references/style-variations.md +0 -14
  71. package/.github/skills/wp-block-themes/references/templates-and-parts.md +0 -16
  72. package/.github/skills/wp-block-themes/references/theme-json.md +0 -59
  73. package/.github/skills/wp-block-themes/scripts/detect_block_themes.mjs +0 -117
  74. package/.github/skills/wp-interactivity-api/SKILL.md +0 -180
  75. package/.github/skills/wp-interactivity-api/references/debugging.md +0 -29
  76. package/.github/skills/wp-interactivity-api/references/directives-quickref.md +0 -30
  77. package/.github/skills/wp-interactivity-api/references/server-side-rendering.md +0 -310
  78. package/.github/skills/wp-performance/SKILL.md +0 -147
  79. package/.github/skills/wp-performance/references/autoload-options.md +0 -24
  80. package/.github/skills/wp-performance/references/cron.md +0 -20
  81. package/.github/skills/wp-performance/references/database.md +0 -20
  82. package/.github/skills/wp-performance/references/http-api.md +0 -15
  83. package/.github/skills/wp-performance/references/measurement.md +0 -21
  84. package/.github/skills/wp-performance/references/object-cache.md +0 -24
  85. package/.github/skills/wp-performance/references/query-monitor-headless.md +0 -38
  86. package/.github/skills/wp-performance/references/server-timing.md +0 -22
  87. package/.github/skills/wp-performance/references/wp-cli-doctor.md +0 -24
  88. package/.github/skills/wp-performance/references/wp-cli-profile.md +0 -32
  89. package/.github/skills/wp-performance/scripts/perf_inspect.mjs +0 -128
  90. package/.github/skills/wp-phpstan/SKILL.md +0 -98
  91. package/.github/skills/wp-phpstan/references/configuration.md +0 -52
  92. package/.github/skills/wp-phpstan/references/third-party-classes.md +0 -76
  93. package/.github/skills/wp-phpstan/references/wordpress-annotations.md +0 -124
  94. package/.github/skills/wp-phpstan/scripts/phpstan_inspect.mjs +0 -263
  95. package/.github/skills/wp-playground/SKILL.md +0 -233
  96. package/.github/skills/wp-playground/references/blueprints.md +0 -36
  97. package/.github/skills/wp-playground/references/cli-commands.md +0 -39
  98. package/.github/skills/wp-playground/references/debugging.md +0 -16
  99. package/.github/skills/wp-playground/references/e2e-playwright.md +0 -115
  100. package/.github/skills/wp-plugin-development/SKILL.md +0 -113
  101. package/.github/skills/wp-plugin-development/references/data-and-cron.md +0 -19
  102. package/.github/skills/wp-plugin-development/references/debugging.md +0 -19
  103. package/.github/skills/wp-plugin-development/references/lifecycle.md +0 -33
  104. package/.github/skills/wp-plugin-development/references/security.md +0 -29
  105. package/.github/skills/wp-plugin-development/references/settings-api.md +0 -22
  106. package/.github/skills/wp-plugin-development/references/structure.md +0 -16
  107. package/.github/skills/wp-plugin-development/scripts/detect_plugins.mjs +0 -122
  108. package/.github/skills/wp-plugin-directory-guidelines/SKILL.md +0 -133
  109. package/.github/skills/wp-plugin-directory-guidelines/references/gpl-compliance.md +0 -217
  110. package/.github/skills/wp-plugin-directory-guidelines/references/guideline-review-checklist.md +0 -592
  111. package/.github/skills/wp-plugin-directory-guidelines/references/naming-rules.md +0 -121
  112. package/.github/skills/wp-project-triage/SKILL.md +0 -39
  113. package/.github/skills/wp-project-triage/references/triage.schema.json +0 -143
  114. package/.github/skills/wp-project-triage/scripts/detect_wp_project.mjs +0 -610
  115. package/.github/skills/wp-rest-api/SKILL.md +0 -115
  116. package/.github/skills/wp-rest-api/references/authentication.md +0 -18
  117. package/.github/skills/wp-rest-api/references/custom-content-types.md +0 -20
  118. package/.github/skills/wp-rest-api/references/discovery-and-params.md +0 -20
  119. package/.github/skills/wp-rest-api/references/responses-and-fields.md +0 -30
  120. package/.github/skills/wp-rest-api/references/routes-and-endpoints.md +0 -36
  121. package/.github/skills/wp-rest-api/references/schema.md +0 -22
  122. package/.github/skills/wp-wpcli-and-ops/SKILL.md +0 -124
  123. package/.github/skills/wp-wpcli-and-ops/references/automation.md +0 -30
  124. package/.github/skills/wp-wpcli-and-ops/references/cron-and-cache.md +0 -23
  125. package/.github/skills/wp-wpcli-and-ops/references/debugging.md +0 -17
  126. package/.github/skills/wp-wpcli-and-ops/references/multisite.md +0 -22
  127. package/.github/skills/wp-wpcli-and-ops/references/packages-and-updates.md +0 -22
  128. package/.github/skills/wp-wpcli-and-ops/references/safety.md +0 -30
  129. package/.github/skills/wp-wpcli-and-ops/references/search-replace.md +0 -40
  130. package/.github/skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs +0 -90
  131. package/.github/skills/wp-wpengine/SKILL.md +0 -127
  132. package/.github/skills/wpds/SKILL.md +0 -59
@@ -1,115 +0,0 @@
1
- ---
2
- name: wp-rest-api
3
- description: "Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing CPTs/taxonomies via show_in_rest."
4
- license: GPL-2.0-or-later
5
- compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
6
- ---
7
-
8
- # WP REST API
9
-
10
- ## When to use
11
-
12
- Use this skill when you need to:
13
-
14
- - create or update REST routes/endpoints
15
- - debug 401/403/404 errors or permission/nonce issues
16
- - add custom fields/meta to REST responses
17
- - expose custom post types or taxonomies via REST
18
- - implement schema + argument validation
19
- - adjust response links/embedding/pagination
20
-
21
- ## Inputs required
22
-
23
- - Repo root + target plugin/theme/mu-plugin (path to entrypoint).
24
- - Desired namespace + version (e.g. `my-plugin/v1`) and routes.
25
- - Authentication mode (cookie + nonce vs application passwords vs auth plugin).
26
- - Target WordPress version constraints (if below 6.9, call out).
27
-
28
- ## Procedure
29
-
30
- ### 0) Triage and locate REST usage
31
-
32
- 1. Run triage:
33
- - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
34
- 2. Search for existing REST usage:
35
- - `register_rest_route`
36
- - `WP_REST_Controller`
37
- - `rest_api_init`
38
- - `show_in_rest`, `rest_base`, `rest_controller_class`
39
-
40
- If this is a full site repo, pick the specific plugin/theme before changing code.
41
-
42
- ### 1) Choose the right approach
43
-
44
- - **Expose CPT/taxonomy in `wp/v2`:**
45
- - Use `show_in_rest => true` + `rest_base` if needed.
46
- - Optionally provide `rest_controller_class`.
47
- - Read `references/custom-content-types.md`.
48
- - **Custom endpoints:**
49
- - Use `register_rest_route()` on `rest_api_init`.
50
- - Prefer a controller class (`WP_REST_Controller` subclass) for anything non-trivial.
51
- - Read `references/routes-and-endpoints.md` and `references/schema.md`.
52
-
53
- ### 2) Register routes safely (namespaces, methods, permissions)
54
-
55
- - Use a unique namespace `vendor/v1`; avoid `wp/*` unless core.
56
- - Always provide `permission_callback` (use `__return_true` for public endpoints).
57
- - Use `WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE` constants.
58
- - Return data via `rest_ensure_response()` or `WP_REST_Response`.
59
- - Return errors via `WP_Error` with an explicit `status`.
60
-
61
- Read `references/routes-and-endpoints.md`.
62
-
63
- ### 3) Validate/sanitize request args
64
-
65
- - Define `args` with `type`, `default`, `required`, `validate_callback`, `sanitize_callback`.
66
- - Prefer JSON Schema validation with `rest_validate_value_from_schema` then `rest_sanitize_value_from_schema`.
67
- - Never read `$_GET`/`$_POST` directly inside endpoints; use `WP_REST_Request`.
68
-
69
- Read `references/schema.md`.
70
-
71
- ### 4) Responses, fields, and links
72
-
73
- - Do **not** remove core fields from default endpoints; add fields instead.
74
- - Use `register_rest_field` for computed fields; `register_meta` with `show_in_rest` for meta.
75
- - For `object`/`array` meta, define schema in `show_in_rest.schema`.
76
- - If you need unfiltered post content (e.g., ToC plugins injecting HTML), request `?context=edit` to access `content.raw` (auth required). Pair with `_fields=content.raw` to keep responses small.
77
- - Add related resource links via `WP_REST_Response::add_link()`.
78
-
79
- Read `references/responses-and-fields.md`.
80
-
81
- ### 5) Authentication and authorization
82
-
83
- - For wp-admin/JS: cookie auth + `X-WP-Nonce` (action `wp_rest`).
84
- - For external clients: application passwords (basic auth) or an auth plugin.
85
- - Use capability checks in `permission_callback` (authorization), not just “logged in”.
86
-
87
- Read `references/authentication.md`.
88
-
89
- ### 6) Client-facing behavior (discovery, pagination, embeds)
90
-
91
- - Ensure discovery works (`Link` header or `<link rel="https://api.w.org/">`).
92
- - Support `_fields`, `_embed`, `_method`, `_envelope`, pagination headers.
93
- - Remember `per_page` is capped at 100.
94
-
95
- Read `references/discovery-and-params.md`.
96
-
97
- ## Verification
98
-
99
- - `/wp-json/` index includes your namespace.
100
- - `OPTIONS` on your route returns schema (when provided).
101
- - Endpoint returns expected data; permission failures return 401/403 as appropriate.
102
- - CPT/taxonomy routes appear under `wp/v2` when `show_in_rest` is true.
103
- - Run repo lint/tests and any PHP/JS build steps.
104
-
105
- ## Failure modes / debugging
106
-
107
- - 404: `rest_api_init` not firing, route typo, or permalinks off (use `?rest_route=`).
108
- - 401/403: missing nonce/auth, or `permission_callback` too strict.
109
- - `_doing_it_wrong` for missing `permission_callback`: add it (use `__return_true` if public).
110
- - Invalid params: missing/incorrect `args` schema or validation callbacks.
111
- - Fields missing: `show_in_rest` false, meta not registered, or CPT lacks `custom-fields` support.
112
-
113
- ## Escalation
114
-
115
- If version support or behavior is unclear, consult the REST API Handbook and core docs before inventing patterns.
@@ -1,18 +0,0 @@
1
- # Authentication (summary)
2
-
3
- ## Cookie authentication (in-dashboard / same-site)
4
-
5
- - Standard for wp-admin and theme/plugin JS.
6
- - Requires a REST nonce (`wp_rest`) sent as `X-WP-Nonce` header or `_wpnonce` param.
7
- - If the nonce is missing, the request is treated as unauthenticated even if cookies exist.
8
-
9
- ## Application Passwords (external clients)
10
-
11
- - Available in WordPress 5.6+.
12
- - Use HTTPS + Basic Auth with the application password.
13
- - Recommended over the legacy Basic Auth plugin.
14
-
15
- ## Auth plugins
16
-
17
- - OAuth 1.0a or JWT plugins are common for external apps.
18
- - Use only if required; follow plugin docs and security guidance.
@@ -1,20 +0,0 @@
1
- # Custom Content Types (summary)
2
-
3
- ## Custom post types
4
-
5
- - Set `show_in_rest => true` in `register_post_type()` to expose in `wp/v2`.
6
- - Use `rest_base` to change the route slug.
7
- - Optionally set `rest_controller_class` (must extend `WP_REST_Controller`).
8
-
9
- ## Custom taxonomies
10
-
11
- - Set `show_in_rest => true` in `register_taxonomy()`.
12
- - Use `rest_base` and optional `rest_controller_class` (default `WP_REST_Terms_Controller`).
13
-
14
- ## Adding REST support to existing types
15
-
16
- - Use `register_post_type_args` or `register_taxonomy_args` filters to enable `show_in_rest` for types you do not control.
17
-
18
- ## Discovery links for custom controllers
19
-
20
- - If you use a custom controller class, use `rest_route_for_post` or `rest_route_for_term` filters to map objects to routes.
@@ -1,20 +0,0 @@
1
- # Discovery and Global Parameters (summary)
2
-
3
- ## API discovery
4
-
5
- - REST API root is discovered via the `Link` header: `rel="https://api.w.org/"`.
6
- - HTML pages also include a `<link rel="https://api.w.org/" href="...">` element.
7
- - For non-pretty permalinks, use `?rest_route=/`.
8
-
9
- ## Global parameters
10
-
11
- - `_fields` limits response fields (supports nested meta keys).
12
- - `_embed` includes linked resources in `_embedded`.
13
- - `_method` or `X-HTTP-Method-Override` allows POST to simulate PUT/DELETE.
14
- - `_envelope` puts headers/status in the response body.
15
- - `_jsonp` enables JSONP for legacy clients.
16
-
17
- ## Pagination
18
-
19
- - Collections accept `page`, `per_page` (1-100), and `offset`.
20
- - Pagination headers: `X-WP-Total` and `X-WP-TotalPages`.
@@ -1,30 +0,0 @@
1
- # Responses and Fields (summary)
2
-
3
- ## Do not remove core fields
4
-
5
- - Removing or changing core fields breaks clients (including wp-admin).
6
- - Prefer adding new fields or using `_fields` to limit response size.
7
-
8
- ## register_rest_field
9
-
10
- - Use for computed or custom fields.
11
- - Provide `get_callback`, optional `update_callback`, and `schema`.
12
- - Register on `rest_api_init`.
13
-
14
- ## Raw vs rendered content
15
-
16
- - For posts, `content.rendered` reflects filters (plugins like ToC inject HTML).
17
- - Use `?context=edit` (authenticated) to access `content.raw`.
18
- - Combine with `_fields=content.raw` when you only need the editable body.
19
-
20
- ## register_meta / register_post_meta / register_term_meta
21
-
22
- - Use when the data is stored as meta.
23
- - Set `show_in_rest => true` to expose under `.meta`.
24
- - For `object` or `array` types, provide a JSON schema in `show_in_rest.schema`.
25
-
26
- ## Links and embedding
27
-
28
- - Add links with `WP_REST_Response::add_link( $rel, $href, $attrs )`.
29
- - Use `embeddable => true` to allow `_embed`.
30
- - Use IANA rels or a custom URI relation; CURIEs can be registered via `rest_response_link_curies`.
@@ -1,36 +0,0 @@
1
- # Routes and Endpoints (summary)
2
-
3
- ## Registering routes
4
-
5
- - Register routes on the `rest_api_init` hook with `register_rest_route( $namespace, $route, $args )`.
6
- - A **route** is the URL pattern; an **endpoint** is the method + callback bound to that route.
7
- - For non-pretty permalinks, the route is accessed via `?rest_route=/namespace/route`.
8
-
9
- ## Namespacing
10
-
11
- - Always namespace routes (`vendor/v1`).
12
- - **Do not** use the `wp/*` namespace unless you are targeting core.
13
-
14
- ## Methods
15
-
16
- - Use `WP_REST_Server::READABLE` (GET), `CREATABLE` (POST), `EDITABLE` (PUT/PATCH), `DELETABLE` (DELETE).
17
- - Multiple endpoints can share a route, one per method.
18
-
19
- ## permission_callback (required)
20
-
21
- - Always provide `permission_callback`.
22
- - Public endpoints should use `__return_true`.
23
- - For restricted endpoints, use capability checks (`current_user_can`) or object-level authorization.
24
- - Missing `permission_callback` emits a `_doing_it_wrong` notice in modern WP.
25
-
26
- ## Arguments
27
-
28
- - Register `args` to validate and sanitize inputs.
29
- - Use `type`, `required`, `default`, `validate_callback`, `sanitize_callback`.
30
- - Access params via the `WP_REST_Request` object, not `$_GET`/`$_POST`.
31
-
32
- ## Return values
33
-
34
- - Return data via `rest_ensure_response()` or a `WP_REST_Response`.
35
- - Return `WP_Error` with a `status` in `data` for error responses.
36
- - Do not call `wp_send_json()` in REST callbacks.
@@ -1,22 +0,0 @@
1
- # Schema and Argument Validation (summary)
2
-
3
- ## JSON Schema in WordPress
4
-
5
- - REST API uses JSON Schema (draft 4 subset) for resource and argument definitions.
6
- - Provide schema via `get_item_schema()` on controllers or `schema` callbacks on routes.
7
- - Schema enables discovery (`OPTIONS`) and validation.
8
-
9
- ## Validation + sanitization
10
-
11
- - Use `rest_validate_value_from_schema( $value, $schema )` then `rest_sanitize_value_from_schema( $value, $schema )`.
12
- - If you override `sanitize_callback`, built-in schema validation will not run; use `rest_validate_request_arg` to keep it.
13
- - `WP_REST_Controller::get_endpoint_args_for_item_schema()` wires validation automatically.
14
-
15
- ## Schema caching
16
-
17
- - Cache the generated schema on the controller instance (`$this->schema`) to avoid recomputation.
18
-
19
- ## Formats and types
20
-
21
- - Common formats: `date-time`, `uri`, `email`, `ip`, `uuid`, `hex-color`.
22
- - For `array` and `object` types, you must define `items` or `properties` schemas.
@@ -1,124 +0,0 @@
1
- ---
2
- name: wp-wpcli-and-ops
3
- description: "Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml."
4
- license: GPL-2.0-or-later
5
- compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WP-CLI in the execution environment."
6
- ---
7
-
8
- # WP-CLI and Ops
9
-
10
- ## When to use
11
-
12
- Use this skill when the task involves WordPress operational work via WP-CLI, including:
13
-
14
- - `wp search-replace` (URL changes, domain migrations, protocol switch)
15
- - DB export/import, resets, and inspections (`wp db *`)
16
- - plugin/theme install/activate/update, language packs
17
- - cron event listing/running
18
- - cache/rewrite flushing
19
- - multisite operations (`wp site *`, `--url`, `--network`)
20
- - building repeatable scripts (`wp-cli.yml`, shell scripts, CI jobs)
21
-
22
- ## Inputs required
23
-
24
- - Where WP-CLI will run (local dev, staging, production) and whether it’s safe to run.
25
- - How to target the correct site root:
26
- - `--path=<wordpress-root>` and (multisite) `--url=<site-url>`
27
- - Whether this is multisite and whether commands should run network-wide.
28
- - Any constraints (no downtime, no DB writes, maintenance window).
29
-
30
- ## Procedure
31
-
32
- ### 0) Guardrails: confirm environment and blast radius
33
-
34
- WP-CLI commands can be destructive. Before running anything that writes:
35
-
36
- 1. Confirm environment (dev/staging/prod).
37
- 2. Confirm targeting (path/url) so you don’t hit the wrong site.
38
- 3. Make a backup when performing risky operations.
39
-
40
- Read:
41
- - `references/safety.md`
42
-
43
- ### 1) Inspect WP-CLI and site targeting (deterministic)
44
-
45
- Run the inspector:
46
-
47
- - `node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]`
48
-
49
- If WP-CLI isn’t available, fall back to installing it via the project’s documented tooling (Composer, container, or system package), or ask for the expected execution environment.
50
-
51
- ### 2) Choose the right workflow
52
-
53
- #### A) Safe URL/domain migration (`search-replace`)
54
-
55
- Follow a safe sequence:
56
-
57
- 1. `wp db export` (backup)
58
- 2. `wp search-replace --dry-run` (review impact)
59
- 3. Run the real replace with appropriate flags
60
- 4. Flush caches/rewrite if needed
61
-
62
- Read:
63
- - `references/search-replace.md`
64
-
65
- #### B) Plugin/theme operations
66
-
67
- Use `wp plugin *` / `wp theme *` and confirm you’re acting on the intended site (and network) first.
68
-
69
- Read:
70
- - `references/packages-and-updates.md`
71
-
72
- #### C) Cron and queues
73
-
74
- Inspect cron state and run individual events for debugging rather than “run everything blindly”.
75
-
76
- Read:
77
- - `references/cron-and-cache.md`
78
-
79
- #### D) Multisite operations
80
-
81
- Multisite changes can affect many sites. Always decide whether you’re operating:
82
-
83
- - on a single site (`--url=`), or
84
- - network-wide (`--network` / iterating sites)
85
-
86
- Read:
87
- - `references/multisite.md`
88
-
89
- ### 3) Automation patterns (scripts + wp-cli.yml)
90
-
91
- For repeatable ops, prefer:
92
-
93
- - `wp-cli.yml` for defaults (path/url, PHP memory limits)
94
- - shell scripts that log commands and stop on error
95
- - CI jobs that run read-only checks by default
96
-
97
- Read:
98
- - `references/automation.md`
99
-
100
- ## Verification
101
-
102
- - Re-run `wpcli_inspect` after changes that could affect targeting or config.
103
- - Confirm intended side effects:
104
- - correct URLs updated
105
- - plugins/themes in expected state
106
- - cron/caches flushed where needed
107
- - If there’s a health check endpoint or smoke test suite, run it after ops changes.
108
-
109
- ## Failure modes / debugging
110
-
111
- - “Error: This does not seem to be a WordPress installation.”
112
- - wrong `--path`, wrong container, or missing `wp-config.php`
113
- - Multisite commands affecting the wrong site
114
- - missing `--url` or wrong URL
115
- - Search-replace causes unexpected serialization issues
116
- - wrong flags or changing serialized data unsafely
117
-
118
- See:
119
- - `references/debugging.md`
120
-
121
- ## Escalation
122
-
123
- - If you cannot confirm environment safety, do not run write operations.
124
- - If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.
@@ -1,30 +0,0 @@
1
- # Automation with WP-CLI
2
-
3
- Use this file when turning an ops sequence into a repeatable script or CI job.
4
-
5
- ## `wp-cli.yml`
6
-
7
- If the repo uses `wp-cli.yml`, use it to standardize:
8
-
9
- - `path:` (WordPress root)
10
- - `url:` (default site)
11
- - PHP settings (memory limits)
12
-
13
- ## Shell scripting
14
-
15
- Guardrails for scripts:
16
-
17
- - `set -euo pipefail`
18
- - print commands before running them
19
- - make destructive operations require an explicit flag (e.g. `--apply`)
20
-
21
- ## CI jobs
22
-
23
- Prefer CI jobs that are read-only by default:
24
-
25
- - `wp core version`
26
- - `wp plugin list`
27
- - `wp theme list`
28
-
29
- Only enable write operations in dedicated deploy/maintenance workflows.
30
-
@@ -1,23 +0,0 @@
1
- # Cron, caches, and rewrites
2
-
3
- Use this file when debugging background jobs or “changes not visible”.
4
-
5
- ## Cron
6
-
7
- - List scheduled events:
8
- - `wp cron event list`
9
- - Run a specific event now:
10
- - `wp cron event run <hook>`
11
-
12
- ## Cache + rewrite
13
-
14
- - Flush object cache:
15
- - `wp cache flush`
16
- - Flush rewrite rules:
17
- - `wp rewrite flush`
18
-
19
- ## Guardrails
20
-
21
- - Don’t “run all cron events” on production without understanding impact.
22
- - Cache flush can cause load spikes; coordinate if needed.
23
-
@@ -1,17 +0,0 @@
1
- # Debugging WP-CLI
2
-
3
- ## WP not found / wrong WP root
4
-
5
- - Run `wp --info`.
6
- - Provide `--path=<wordpress-root>` if WP is not in the current directory.
7
- - Confirm `wp-config.php` exists in the expected root.
8
-
9
- ## HTTP/URL targeting issues
10
-
11
- - On multisite, include `--url=<site-url>` for site-specific actions.
12
-
13
- ## Permission/file ownership issues
14
-
15
- - If running in containers, ensure you’re using the same user/volume mapping as the app.
16
- - Avoid `--allow-root` unless you understand the environment and have no alternative.
17
-
@@ -1,22 +0,0 @@
1
- # Multisite targeting
2
-
3
- Use this file any time you might be operating on multisite.
4
-
5
- ## Key flags
6
-
7
- - `--url=<site-url>` targets a specific site/blog context.
8
- - `--network` applies to the network where supported.
9
-
10
- ## Common commands
11
-
12
- - List sites:
13
- - `wp site list`
14
- - Get site options for a specific site:
15
- - `wp option get siteurl --url=<site-url>`
16
-
17
- ## Guardrails
18
-
19
- - Always include `--url` when you mean “one site” in a multisite install.
20
- - If you need to run something across sites, prefer scripting:
21
- - list sites → iterate → run a safe per-site command.
22
-
@@ -1,22 +0,0 @@
1
- # Plugin/theme operations
2
-
3
- Use this file for installs, activation, updates, and listing state.
4
-
5
- ## Common commands
6
-
7
- - Plugins:
8
- - `wp plugin list`
9
- - `wp plugin status <slug>`
10
- - `wp plugin activate <slug>`
11
- - `wp plugin deactivate <slug>`
12
- - `wp plugin update --all`
13
- - Themes:
14
- - `wp theme list`
15
- - `wp theme activate <slug>`
16
- - `wp theme update --all`
17
-
18
- ## Guardrails
19
-
20
- - On production, avoid `update --all` without a maintenance window.
21
- - On multisite, plugin activation may be per-site or network-wide; confirm intent.
22
-
@@ -1,30 +0,0 @@
1
- # Safety rules (WP-CLI)
2
-
3
- Use this file before running any write operations.
4
-
5
- ## Golden rules
6
-
7
- - Assume production is **unsafe** unless explicitly confirmed.
8
- - Always confirm targeting:
9
- - `--path` (WordPress root)
10
- - `--url` (multisite / specific site targeting)
11
- - Prefer a backup (`wp db export`) before risky operations.
12
- - Prefer `--dry-run` where available (especially `search-replace`).
13
-
14
- ## High-risk commands (require explicit confirmation)
15
-
16
- - `wp db reset`
17
- - `wp db import` (overwrites data)
18
- - `wp search-replace` (can affect serialized data and URLs)
19
- - bulk deletes (`wp post delete --force --all`, `wp user delete --reassign`, etc.)
20
- - plugin/theme mass updates on production
21
-
22
- ## Logging
23
-
24
- For ops scripts, log:
25
-
26
- - date/time
27
- - environment (dev/staging/prod)
28
- - exact WP-CLI commands
29
- - exit codes
30
-
@@ -1,40 +0,0 @@
1
- # Safe `wp search-replace`
2
-
3
- Use this file when migrating domains, switching http→https, or changing paths.
4
-
5
- ## Recommended workflow
6
-
7
- 1. Backup:
8
- - `wp db export`
9
- 2. Dry run:
10
- - `wp search-replace OLD NEW --dry-run`
11
- 3. Run for real (carefully choose scope):
12
- - consider `--all-tables-with-prefix` if you need to include non-core tables with the WP prefix
13
- 4. Flush:
14
- - `wp cache flush`
15
- - `wp rewrite flush`
16
-
17
- ## Multisite notes
18
-
19
- For multisite, decide whether you’re replacing:
20
-
21
- - a single site (`--url=...`), or
22
- - across the network (`--network` or iterating `wp site list`).
23
-
24
- Read:
25
- - `references/multisite.md`
26
-
27
- ## Common flags
28
-
29
- - `--dry-run`
30
- - `--precise` (slower but can be safer in complex cases)
31
- - `--skip-columns=...` (avoid touching large/binary columns)
32
- - `--report-changed-only`
33
-
34
- ## Serialization caution
35
-
36
- WP-CLI search-replace is designed to handle PHP serialized data, but you must still:
37
-
38
- - avoid replacing within binary/blob columns
39
- - validate results with application smoke tests
40
-
@@ -1,90 +0,0 @@
1
- import { spawnSync } from "node:child_process";
2
-
3
- const TOOL_VERSION = "0.1.0";
4
-
5
- function parseArgs(argv) {
6
- const args = { path: null, url: null, allowRoot: false };
7
- for (const a of argv) {
8
- if (a === "--allow-root") args.allowRoot = true;
9
- if (a.startsWith("--path=")) args.path = a.slice("--path=".length);
10
- if (a.startsWith("--url=")) args.url = a.slice("--url=".length);
11
- }
12
- return args;
13
- }
14
-
15
- function runWp(cmdArgs, { pathArg, urlArg, allowRoot }) {
16
- const args = [];
17
- if (allowRoot) args.push("--allow-root");
18
- if (pathArg) args.push(`--path=${pathArg}`);
19
- if (urlArg) args.push(`--url=${urlArg}`);
20
- args.push(...cmdArgs);
21
-
22
- const out = spawnSync("wp", args, { encoding: "utf8" });
23
- return {
24
- ok: out.status === 0,
25
- status: out.status,
26
- error: out.error ? { message: out.error.message, code: out.error.code } : null,
27
- stdout: (out.stdout || "").trim(),
28
- stderr: (out.stderr || "").trim(),
29
- args,
30
- };
31
- }
32
-
33
- function main() {
34
- const opts = parseArgs(process.argv.slice(2));
35
-
36
- const info = runWp(["--info"], { pathArg: null, urlArg: null, allowRoot: opts.allowRoot });
37
- const report = {
38
- tool: { name: "wpcli_inspect", version: TOOL_VERSION },
39
- wpCli: {
40
- available: info.ok,
41
- info,
42
- },
43
- wordpress: {
44
- path: opts.path,
45
- url: opts.url,
46
- isInstalled: null,
47
- coreVersion: null,
48
- isMultisite: null,
49
- siteurl: null,
50
- home: null,
51
- },
52
- notes: [],
53
- };
54
-
55
- if (!info.ok) {
56
- report.notes.push("WP-CLI not available on PATH. Install WP-CLI or run inside the intended container/environment.");
57
- process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
58
- return;
59
- }
60
-
61
- const isInstalled = runWp(["core", "is-installed"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
62
- report.wordpress.isInstalled = isInstalled.ok;
63
-
64
- if (!isInstalled.ok) {
65
- report.notes.push("WordPress not detected at the given path/url. Check --path/--url (multisite) and that wp-config.php is present.");
66
- process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
67
- return;
68
- }
69
-
70
- const coreVersion = runWp(["core", "version"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
71
- report.wordpress.coreVersion = coreVersion.ok ? coreVersion.stdout : null;
72
-
73
- const isMultisite = runWp(["core", "is-installed", "--network"], {
74
- pathArg: opts.path,
75
- urlArg: opts.url,
76
- allowRoot: opts.allowRoot,
77
- });
78
- // If network check passes, we can assume multisite. If it fails, it might still be multisite depending on context.
79
- report.wordpress.isMultisite = isMultisite.ok;
80
-
81
- const siteurl = runWp(["option", "get", "siteurl"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
82
- report.wordpress.siteurl = siteurl.ok ? siteurl.stdout : null;
83
-
84
- const home = runWp(["option", "get", "home"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
85
- report.wordpress.home = home.ok ? home.stdout : null;
86
-
87
- process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
88
- }
89
-
90
- main();