@ai-kits/wp-ag-kit 1.0.0

package/skills/wp-plugin-development/references/settings-api.md

@@ -0,0 +1,22 @@
+# Settings API (admin options)
+
+Use this file when adding settings pages or storing user-configurable options.
+
+Core APIs:
+
+- `register_setting()`
+- `add_settings_section()`
+- `add_settings_field()`
+
+Upstream references:
+
+- Settings API overview: https://developer.wordpress.org/plugins/settings/settings-api/
+- Register settings: https://developer.wordpress.org/plugins/settings/registration/
+- Add settings fields: https://developer.wordpress.org/plugins/settings/settings-fields/
+
+Practical guardrails:
+
+- Use `sanitize_callback` to validate/sanitize data.
+- Use capability checks (commonly `manage_options`) for settings screens and saves.
+- Escape values on output (`esc_attr`, `esc_html`, etc.).
+

package/skills/wp-plugin-development/references/structure.md

@@ -0,0 +1,16 @@
+# Plugin structure and loading
+
+Use this file when introducing or refactoring a plugin architecture.
+
+## Core concepts
+
+- Main plugin file contains the plugin header and bootstraps the plugin.
+- Prefer predictable init:
+  - minimal boot file
+  - a loader/class that registers hooks
+  - admin-only code behind admin hooks
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/
+

package/skills/wp-plugin-development/scripts/detect_plugins.mjs

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_IGNORES = new Set([
+  ".git",
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+]);
+
+function statSafe(p) {
+  try {
+    return fs.statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function readFileSafe(p, maxBytes = 128 * 1024) {
+  try {
+    const buf = fs.readFileSync(p);
+    if (buf.byteLength > maxBytes) return buf.subarray(0, maxBytes).toString("utf8");
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function findFilesRecursive(repoRoot, predicate, { maxFiles = 6000, maxDepth = 10 } = {}) {
+  const results = [];
+  const queue = [{ dir: repoRoot, depth: 0 }];
+  let visited = 0;
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    if (depth > maxDepth) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const ent of entries) {
+      const fullPath = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (DEFAULT_IGNORES.has(ent.name)) continue;
+        queue.push({ dir: fullPath, depth: depth + 1 });
+        continue;
+      }
+      if (!ent.isFile()) continue;
+
+      visited += 1;
+      if (visited > maxFiles) return { results, truncated: true };
+      if (predicate(fullPath)) results.push(fullPath);
+    }
+  }
+
+  return { results, truncated: false };
+}
+
+function parsePluginHeader(contents) {
+  // WordPress reads plugin headers from the top of the file. We only need key fields.
+  const header = {};
+  const pairs = [
+    ["Plugin Name", "name"],
+    ["Plugin URI", "uri"],
+    ["Description", "description"],
+    ["Version", "version"],
+    ["Author", "author"],
+    ["Author URI", "authorUri"],
+    ["Text Domain", "textDomain"],
+    ["Domain Path", "domainPath"],
+  ];
+  for (const [label, key] of pairs) {
+    const m = contents.match(new RegExp(`^\\s*${label}:\\s*(.+)\\s*$`, "im"));
+    if (m) header[key] = m[1].trim();
+  }
+  if (!header.name) return null;
+  return header;
+}
+
+function main() {
+  const repoRoot = process.cwd();
+
+  const { results: phpFiles, truncated } = findFilesRecursive(repoRoot, (p) => p.toLowerCase().endsWith(".php"), {
+    maxFiles: 5000,
+    maxDepth: 10,
+  });
+
+  const plugins = [];
+
+  for (const phpPath of phpFiles) {
+    const txt = readFileSafe(phpPath);
+    if (!txt) continue;
+    if (!/Plugin Name:/i.test(txt)) continue;
+    const header = parsePluginHeader(txt);
+    if (!header) continue;
+    plugins.push({
+      pluginFile: path.relative(repoRoot, phpPath),
+      ...header,
+    });
+  }
+
+  const report = {
+    tool: { name: "detect_plugins", version: "0.1.0" },
+    repoRoot,
+    truncated,
+    count: plugins.length,
+    plugins,
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();
+

package/skills/wp-project-triage/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: wp-project-triage
+description: "Use when you need a deterministic inspection of a WordPress repository (plugin/theme/block theme/WP core/Gutenberg/full site) including tooling/tests/version hints, and a structured JSON report to guide workflows and guardrails."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Project Triage
+
+## When to use
+
+Use this skill to quickly understand what kind of WordPress repo you’re in and what commands/conventions to follow before making changes.
+
+## Inputs required
+
+- Repo root (current working directory).
+
+## Procedure
+
+1. Run the detector (prints JSON to stdout):
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. If you need the exact output contract, read:
+   - `skills/wp-project-triage/references/triage.schema.json`
+3. Use the report to select workflow guardrails:
+   - project kind(s)
+   - PHP/Node tooling present
+   - tests present
+   - version hints and sources
+4. If the report is missing signals you need, update the detector rather than guessing.
+
+## Verification
+
+- The JSON should parse and include: `project.kind`, `signals`, and `tooling`.
+- Re-run after changes that affect structure/tooling (adding `theme.json`, `block.json`, build config).
+
+## Failure modes / debugging
+
+- If it reports `unknown`, check whether the repo root is correct.
+- If scanning is slow, add/extend ignore directories in the script.

package/skills/wp-project-triage/references/triage.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentskills.local/wp-project-triage/triage.schema.json",
+  "title": "WP Project Triage Report",
+  "type": "object",
+  "required": ["tool", "project", "signals", "tooling"],
+  "properties": {
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "const": "detect_wp_project" },
+        "version": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "project": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "unknown",
+              "wp-plugin",
+              "wp-mu-plugin",
+              "wp-theme",
+              "wp-block-theme",
+              "wp-block-plugin",
+              "wp-site",
+              "wp-core",
+              "gutenberg"
+            ]
+          }
+        },
+        "primary": { "type": "string" },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "signals": {
+      "type": "object",
+      "required": ["paths"],
+      "properties": {
+        "paths": {
+          "type": "object",
+          "properties": {
+            "repoRoot": { "type": "string" },
+            "wpContent": { "type": "string" },
+            "pluginsDir": { "type": "string" },
+            "themesDir": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+        ,
+        "usesInteractivityApi": { "type": "boolean" },
+        "usesAbilitiesApi": { "type": "boolean" },
+        "usesInnerBlocks": { "type": "boolean" },
+        "usesWpCli": { "type": "boolean" },
+        "performanceHints": { "type": "object", "additionalProperties": true },
+        "interactivityHints": { "type": "object", "additionalProperties": true },
+        "abilitiesHints": { "type": "object", "additionalProperties": true },
+        "innerBlocksHints": { "type": "object", "additionalProperties": true },
+        "wpCliHints": { "type": "object", "additionalProperties": true }
+      },
+      "additionalProperties": true
+    },
+    "tooling": {
+      "type": "object",
+      "required": ["php", "node", "tests"],
+      "properties": {
+        "php": {
+          "type": "object",
+          "properties": {
+            "hasComposerJson": { "type": "boolean" },
+            "hasVendorDir": { "type": "boolean" },
+            "phpunitXml": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": true
+        },
+        "node": {
+          "type": "object",
+          "properties": {
+            "hasPackageJson": { "type": "boolean" },
+            "packageManager": { "type": ["string", "null"], "enum": ["npm", "yarn", "pnpm", "bun", null] },
+            "usesWordpressScripts": { "type": "boolean" }
+          },
+          "additionalProperties": true
+        },
+        "tests": {
+          "type": "object",
+          "properties": {
+            "hasPhpUnit": { "type": "boolean" },
+            "hasWpEnv": { "type": "boolean" },
+            "hasPlaywright": { "type": "boolean" },
+            "hasJest": { "type": "boolean" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "versions": {
+      "type": "object",
+      "properties": {
+        "wordpress": {
+          "type": "object",
+          "properties": {
+            "core": {
+              "type": "object",
+              "properties": {
+                "value": { "type": ["string", "null"] },
+                "source": { "type": ["string", "null"] }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        },
+        "gutenberg": {
+          "type": "object",
+          "properties": {
+            "value": { "type": ["string", "null"] },
+            "source": { "type": ["string", "null"] }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "recommendations": {
+      "type": "object",
+      "properties": {
+        "commands": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}