@meshxdata/fops 0.0.1

package/src/plugins/api.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi } from "vitest";
+import { createPluginApi } from "./api.js";
+import { createRegistry } from "./registry.js";
+
+describe("plugins/api", () => {
+  describe("createPluginApi", () => {
+    it("returns api with id and methods", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test-plugin", registry);
+      expect(api.id).toBe("test-plugin");
+      expect(typeof api.registerCommand).toBe("function");
+      expect(typeof api.registerDoctorCheck).toBe("function");
+      expect(typeof api.registerHook).toBe("function");
+    });
+
+    it("has config property (empty by default)", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test-plugin", registry);
+      expect(api.config).toEqual({});
+    });
+
+    it("registerCommand adds to registry.commands", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test-plugin", registry);
+      const spec = { name: "my-cmd", description: "A command" };
+      api.registerCommand(spec);
+      expect(registry.commands).toHaveLength(1);
+      expect(registry.commands[0]).toEqual({ pluginId: "test-plugin", spec });
+    });
+
+    it("registerCommand can add multiple commands", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test-plugin", registry);
+      api.registerCommand({ name: "cmd1" });
+      api.registerCommand({ name: "cmd2" });
+      api.registerCommand({ name: "cmd3" });
+      expect(registry.commands).toHaveLength(3);
+    });
+
+    it("registerDoctorCheck adds to registry.doctorChecks", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test-plugin", registry);
+      const fn = vi.fn();
+      api.registerDoctorCheck({ name: "check-foo", fn });
+      expect(registry.doctorChecks).toHaveLength(1);
+      expect(registry.doctorChecks[0].name).toBe("check-foo");
+      expect(registry.doctorChecks[0].fn).toBe(fn);
+      expect(registry.doctorChecks[0].pluginId).toBe("test-plugin");
+    });
+
+    it("registerHook adds to registry.hooks with default priority", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test-plugin", registry);
+      const handler = vi.fn();
+      api.registerHook("pre:up", handler);
+      expect(registry.hooks).toHaveLength(1);
+      expect(registry.hooks[0]).toEqual({
+        pluginId: "test-plugin",
+        event: "pre:up",
+        handler,
+        priority: 0,
+      });
+    });
+
+    it("registerHook respects custom priority", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test-plugin", registry);
+      const handler = vi.fn();
+      api.registerHook("post:up", handler, 10);
+      expect(registry.hooks[0].priority).toBe(10);
+    });
+
+    it("multiple plugins can register on same registry", () => {
+      const registry = createRegistry();
+      const api1 = createPluginApi("plugin-a", registry);
+      const api2 = createPluginApi("plugin-b", registry);
+      api1.registerCommand({ name: "cmd-a" });
+      api2.registerCommand({ name: "cmd-b" });
+      api1.registerHook("pre:up", vi.fn());
+      api2.registerHook("pre:up", vi.fn());
+      expect(registry.commands).toHaveLength(2);
+      expect(registry.hooks).toHaveLength(2);
+      expect(registry.commands[0].pluginId).toBe("plugin-a");
+      expect(registry.commands[1].pluginId).toBe("plugin-b");
+    });
+
+    it("registerDoctorCheck preserves fn reference", () => {
+      const registry = createRegistry();
+      const api = createPluginApi("test", registry);
+      const checkFn = async (ok, warn, fail) => { ok("test passed"); };
+      api.registerDoctorCheck({ name: "my-check", fn: checkFn });
+      expect(registry.doctorChecks[0].fn).toBe(checkFn);
+    });
+  });
+});

package/src/plugins/discovery.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Discover plugin candidates from two sources:
+ * 1. ~/.fops/plugins/<name>/ (user-global, each must have fops.plugin.json)
+ * 2. npm packages matching fops-plugin-* or @*\/fops-plugin-* in the CLI's node_modules
+ *
+ * Returns array of { id, path, source: "global" | "npm" }.
+ */
+export function discoverPlugins() {
+  const candidates = [];
+
+  // 1. User-global plugins: ~/.fops/plugins/
+  const globalDir = path.join(os.homedir(), ".fops", "plugins");
+  if (fs.existsSync(globalDir)) {
+    try {
+      const entries = fs.readdirSync(globalDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const pluginPath = path.join(globalDir, entry.name);
+        if (fs.existsSync(path.join(pluginPath, "fops.plugin.json"))) {
+          candidates.push({ id: entry.name, path: pluginPath, source: "global" });
+        }
+      }
+    } catch {
+      // ignore read errors
+    }
+  }
+
+  // 2. npm packages: look in the CLI's own node_modules
+  const cliRoot = path.resolve(__dirname, "../..");
+  const nodeModules = path.join(cliRoot, "node_modules");
+  if (fs.existsSync(nodeModules)) {
+    try {
+      const entries = fs.readdirSync(nodeModules, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+
+        // Scoped packages: @scope/fops-plugin-*
+        if (entry.name.startsWith("@") && entry.isDirectory()) {
+          const scopeDir = path.join(nodeModules, entry.name);
+          try {
+            const scopedEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
+            for (const scoped of scopedEntries) {
+              if (scoped.name.startsWith("fops-plugin-") && scoped.isDirectory()) {
+                const pkgPath = path.join(scopeDir, scoped.name);
+                if (fs.existsSync(path.join(pkgPath, "fops.plugin.json"))) {
+                  candidates.push({ id: `${entry.name}/${scoped.name}`, path: pkgPath, source: "npm" });
+                }
+              }
+            }
+          } catch {
+            // ignore
+          }
+          continue;
+        }
+
+        // Unscoped packages: fops-plugin-*
+        if (entry.name.startsWith("fops-plugin-") && entry.isDirectory()) {
+          const pkgPath = path.join(nodeModules, entry.name);
+          if (fs.existsSync(path.join(pkgPath, "fops.plugin.json"))) {
+            candidates.push({ id: entry.name, path: pkgPath, source: "npm" });
+          }
+        }
+      }
+    } catch {
+      // ignore read errors
+    }
+  }
+
+  return candidates;
+}

package/src/plugins/discovery.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+describe("plugins/discovery", () => {
+  let tmpHome;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "fops-home-"));
+    vi.spyOn(os, "homedir").mockReturnValue(tmpHome);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  it("returns empty when no plugin dirs exist", async () => {
+    vi.resetModules();
+    const { discoverPlugins } = await import("./discovery.js");
+    const result = discoverPlugins();
+    const globalPlugins = result.filter((p) => p.source === "global");
+    expect(globalPlugins).toHaveLength(0);
+  });
+
+  it("discovers global plugins with fops.plugin.json", async () => {
+    const pluginDir = path.join(tmpHome, ".fops", "plugins", "my-plugin");
+    fs.mkdirSync(pluginDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(pluginDir, "fops.plugin.json"),
+      JSON.stringify({ id: "my-plugin", name: "My Plugin", version: "1.0.0" })
+    );
+
+    vi.resetModules();
+    const { discoverPlugins } = await import("./discovery.js");
+    const result = discoverPlugins();
+    const globalPlugins = result.filter((p) => p.source === "global");
+    expect(globalPlugins).toHaveLength(1);
+    expect(globalPlugins[0].id).toBe("my-plugin");
+    expect(globalPlugins[0].path).toBe(pluginDir);
+    expect(globalPlugins[0].source).toBe("global");
+  });
+
+  it("skips global dirs without fops.plugin.json", async () => {
+    const pluginDir = path.join(tmpHome, ".fops", "plugins", "no-manifest");
+    fs.mkdirSync(pluginDir, { recursive: true });
+    fs.writeFileSync(path.join(pluginDir, "index.js"), "");
+
+    vi.resetModules();
+    const { discoverPlugins } = await import("./discovery.js");
+    const result = discoverPlugins();
+    const globalPlugins = result.filter((p) => p.source === "global");
+    expect(globalPlugins).toHaveLength(0);
+  });
+
+  it("discovers multiple global plugins", async () => {
+    for (const name of ["plugin-a", "plugin-b", "plugin-c"]) {
+      const dir = path.join(tmpHome, ".fops", "plugins", name);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, "fops.plugin.json"),
+        JSON.stringify({ id: name, name, version: "1.0.0" })
+      );
+    }
+
+    vi.resetModules();
+    const { discoverPlugins } = await import("./discovery.js");
+    const result = discoverPlugins();
+    const globalPlugins = result.filter((p) => p.source === "global");
+    expect(globalPlugins).toHaveLength(3);
+  });
+
+  it("skips files (non-directories) in plugins dir", async () => {
+    const pluginsDir = path.join(tmpHome, ".fops", "plugins");
+    fs.mkdirSync(pluginsDir, { recursive: true });
+    fs.writeFileSync(path.join(pluginsDir, "not-a-dir.txt"), "");
+
+    vi.resetModules();
+    const { discoverPlugins } = await import("./discovery.js");
+    const result = discoverPlugins();
+    const globalPlugins = result.filter((p) => p.source === "global");
+    expect(globalPlugins).toHaveLength(0);
+  });
+
+  it("returns array even when ~/.fops/plugins does not exist", async () => {
+    vi.resetModules();
+    const { discoverPlugins } = await import("./discovery.js");
+    const result = discoverPlugins();
+    expect(Array.isArray(result)).toBe(true);
+  });
+});

package/src/plugins/hooks.js

@@ -0,0 +1,13 @@
+/**
+ * Hook execution engine.
+ * Collects all handlers for an event, sorts by priority (higher first), runs sequentially.
+ */
+export async function runHook(registry, event, context = {}) {
+  const handlers = registry.hooks
+    .filter((h) => h.event === event)
+    .sort((a, b) => b.priority - a.priority);
+
+  for (const h of handlers) {
+    await h.handler(context);
+  }
+}

package/src/plugins/hooks.test.js

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi } from "vitest";
+import { runHook } from "./hooks.js";
+
+describe("plugins/hooks", () => {
+  describe("runHook", () => {
+    it("runs matching handlers", async () => {
+      const handler = vi.fn();
+      const registry = {
+        hooks: [{ event: "pre:up", handler, priority: 0 }],
+      };
+      await runHook(registry, "pre:up", { root: "/project" });
+      expect(handler).toHaveBeenCalledWith({ root: "/project" });
+    });
+
+    it("skips non-matching events", async () => {
+      const handler = vi.fn();
+      const registry = {
+        hooks: [{ event: "pre:up", handler, priority: 0 }],
+      };
+      await runHook(registry, "post:up");
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it("sorts by priority (higher first)", async () => {
+      const order = [];
+      const low = vi.fn(() => order.push("low"));
+      const high = vi.fn(() => order.push("high"));
+      const registry = {
+        hooks: [
+          { event: "pre:up", handler: low, priority: 1 },
+          { event: "pre:up", handler: high, priority: 10 },
+        ],
+      };
+      await runHook(registry, "pre:up");
+      expect(order).toEqual(["high", "low"]);
+    });
+
+    it("runs handlers sequentially (not parallel)", async () => {
+      const order = [];
+      const slow = vi.fn(async () => {
+        await new Promise((r) => setTimeout(r, 10));
+        order.push("slow");
+      });
+      const fast = vi.fn(() => order.push("fast"));
+      const registry = {
+        hooks: [
+          { event: "test", handler: slow, priority: 10 },
+          { event: "test", handler: fast, priority: 0 },
+        ],
+      };
+      await runHook(registry, "test");
+      expect(order).toEqual(["slow", "fast"]);
+    });
+
+    it("handles empty hooks array", async () => {
+      const registry = { hooks: [] };
+      await expect(runHook(registry, "pre:up")).resolves.toBeUndefined();
+    });
+
+    it("passes context to all handlers", async () => {
+      const h1 = vi.fn();
+      const h2 = vi.fn();
+      const ctx = { root: "/proj", extra: "data" };
+      const registry = {
+        hooks: [
+          { event: "test", handler: h1, priority: 0 },
+          { event: "test", handler: h2, priority: 0 },
+        ],
+      };
+      await runHook(registry, "test", ctx);
+      expect(h1).toHaveBeenCalledWith(ctx);
+      expect(h2).toHaveBeenCalledWith(ctx);
+    });
+
+    it("uses empty object as default context", async () => {
+      const handler = vi.fn();
+      const registry = {
+        hooks: [{ event: "test", handler, priority: 0 }],
+      };
+      await runHook(registry, "test");
+      expect(handler).toHaveBeenCalledWith({});
+    });
+
+    it("handles three priority levels correctly", async () => {
+      const order = [];
+      const registry = {
+        hooks: [
+          { event: "e", handler: () => order.push("med"), priority: 5 },
+          { event: "e", handler: () => order.push("low"), priority: 1 },
+          { event: "e", handler: () => order.push("high"), priority: 10 },
+        ],
+      };
+      await runHook(registry, "e");
+      expect(order).toEqual(["high", "med", "low"]);
+    });
+
+    it("only runs handlers for the exact event name", async () => {
+      const h1 = vi.fn();
+      const h2 = vi.fn();
+      const registry = {
+        hooks: [
+          { event: "pre:up", handler: h1, priority: 0 },
+          { event: "pre:down", handler: h2, priority: 0 },
+        ],
+      };
+      await runHook(registry, "pre:up");
+      expect(h1).toHaveBeenCalled();
+      expect(h2).not.toHaveBeenCalled();
+    });
+
+    it("handler errors propagate", async () => {
+      const registry = {
+        hooks: [{ event: "test", handler: () => { throw new Error("boom"); }, priority: 0 }],
+      };
+      await expect(runHook(registry, "test")).rejects.toThrow("boom");
+    });
+  });
+});

package/src/plugins/index.js

@@ -0,0 +1,3 @@
+export { loadPlugins } from "./loader.js";
+export { runHook } from "./hooks.js";
+export { loadSkills } from "./skills.js";

package/src/plugins/loader.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRegistry } from "./registry.js";
+import { validateManifest } from "./manifest.js";
+import { discoverPlugins } from "./discovery.js";
+import { createPluginApi } from "./api.js";
+
+/**
+ * Parse SKILL.md frontmatter (lightweight, same logic as skills.js).
+ */
+function parseSkillFrontmatter(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+  if (!match) return { meta: {}, body: content };
+  const meta = {};
+  for (const line of match[1].split("\n")) {
+    const kv = line.match(/^(\w+)\s*:\s*(.+)/);
+    if (kv) meta[kv[1]] = kv[2].trim();
+  }
+  return { meta, body: match[2] };
+}
+
+/**
+ * Check if a plugin is enabled in ~/.fops.json.
+ * Default: enabled unless explicitly set to false.
+ */
+function isPluginEnabled(pluginId) {
+  try {
+    const fopsConfig = path.join(os.homedir(), ".fops.json");
+    if (!fs.existsSync(fopsConfig)) return true;
+    const raw = JSON.parse(fs.readFileSync(fopsConfig, "utf8"));
+    const entry = raw?.plugins?.entries?.[pluginId];
+    if (entry && entry.enabled === false) return false;
+  } catch {
+    // ignore parse errors
+  }
+  return true;
+}
+
+/**
+ * Load and activate all discovered plugins.
+ * Returns a populated PluginRegistry.
+ */
+export async function loadPlugins() {
+  const registry = createRegistry();
+  const candidates = discoverPlugins();
+
+  for (const candidate of candidates) {
+    // Validate manifest
+    const manifest = validateManifest(candidate.path);
+    if (!manifest) continue;
+
+    // Check enable/disable state
+    if (!isPluginEnabled(manifest.id)) continue;
+
+    // Load plugin skills from manifest "skills" array
+    if (manifest.skills && Array.isArray(manifest.skills)) {
+      for (const skillRelPath of manifest.skills) {
+        const skillMd = path.join(candidate.path, skillRelPath, "SKILL.md");
+        if (fs.existsSync(skillMd)) {
+          const raw = fs.readFileSync(skillMd, "utf8");
+          const { meta, body } = parseSkillFrontmatter(raw);
+          registry.skills.push({
+            pluginId: manifest.id,
+            name: meta.name || path.basename(skillRelPath),
+            description: meta.description || "",
+            content: body.trim(),
+          });
+        }
+      }
+    }
+
+    // Dynamic import the plugin entry point
+    const entryPoint = path.join(candidate.path, "index.js");
+    if (!fs.existsSync(entryPoint)) {
+      // Plugin with only skills and no code is valid
+      registry.plugins.push({
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        path: candidate.path,
+        source: candidate.source,
+      });
+      continue;
+    }
+
+    try {
+      const mod = await import(entryPoint);
+      const plugin = mod.default || mod;
+
+      if (typeof plugin.register === "function") {
+        const api = createPluginApi(manifest.id, registry);
+        await plugin.register(api);
+      }
+
+      registry.plugins.push({
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        path: candidate.path,
+        source: candidate.source,
+      });
+    } catch (err) {
+      // Skip plugins that fail to load — log for debugging
+      console.error(`  Plugin "${manifest.id}" failed to load: ${err.message}`);
+    }
+  }
+
+  return registry;
+}

package/src/plugins/manifest.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const REQUIRED_FIELDS = ["id", "name", "version"];
+
+/**
+ * Read and validate fops.plugin.json from a plugin directory.
+ * Returns the parsed manifest or null if invalid.
+ */
+export function validateManifest(pluginPath) {
+  const manifestPath = path.join(pluginPath, "fops.plugin.json");
+  if (!fs.existsSync(manifestPath)) return null;
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!manifest[field] || typeof manifest[field] !== "string") return null;
+  }
+
+  return manifest;
+}

package/src/plugins/manifest.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { validateManifest } from "./manifest.js";
+
+describe("plugins/manifest", () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fops-manifest-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns null when no fops.plugin.json exists", () => {
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null for invalid JSON", () => {
+    fs.writeFileSync(path.join(tmpDir, "fops.plugin.json"), "not json{{{");
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null when id is missing", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "fops.plugin.json"),
+      JSON.stringify({ name: "Test", version: "1.0.0" })
+    );
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null when name is missing", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "fops.plugin.json"),
+      JSON.stringify({ id: "test", version: "1.0.0" })
+    );
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null when version is missing", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "fops.plugin.json"),
+      JSON.stringify({ id: "test", name: "Test" })
+    );
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null when fields are not strings", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "fops.plugin.json"),
+      JSON.stringify({ id: "test", name: "Test", version: 1 })
+    );
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null when id is empty string", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "fops.plugin.json"),
+      JSON.stringify({ id: "", name: "Test", version: "1.0.0" })
+    );
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null when fields are numbers", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "fops.plugin.json"),
+      JSON.stringify({ id: 1, name: 2, version: 3 })
+    );
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns manifest when all required fields present", () => {
+    const manifest = { id: "test-plugin", name: "Test Plugin", version: "1.0.0" };
+    fs.writeFileSync(path.join(tmpDir, "fops.plugin.json"), JSON.stringify(manifest));
+    const result = validateManifest(tmpDir);
+    expect(result).toEqual(manifest);
+  });
+
+  it("preserves extra fields in manifest", () => {
+    const manifest = {
+      id: "test-plugin",
+      name: "Test Plugin",
+      version: "1.0.0",
+      description: "A test",
+      author: "test",
+      skills: ["skills/foo"],
+    };
+    fs.writeFileSync(path.join(tmpDir, "fops.plugin.json"), JSON.stringify(manifest));
+    const result = validateManifest(tmpDir);
+    expect(result.description).toBe("A test");
+    expect(result.skills).toEqual(["skills/foo"]);
+  });
+
+  it("returns null for empty JSON object", () => {
+    fs.writeFileSync(path.join(tmpDir, "fops.plugin.json"), "{}");
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+
+  it("returns null for empty file", () => {
+    fs.writeFileSync(path.join(tmpDir, "fops.plugin.json"), "");
+    expect(validateManifest(tmpDir)).toBe(null);
+  });
+});

package/src/plugins/registry.js

@@ -0,0 +1,14 @@
+/**
+ * PluginRegistry — flat store for all registered plugin extensions.
+ * Created once at startup, passed through the system.
+ */
+
+export function createRegistry() {
+  return {
+    plugins: [],       // { id, name, version, path, source }
+    commands: [],      // { pluginId, spec }
+    doctorChecks: [],  // { pluginId, name, fn }
+    hooks: [],         // { pluginId, event, handler, priority }
+    skills: [],        // { pluginId, name, description, content }
+  };
+}