@wrongstack/plugins 0.281.1 → 0.282.0

package/dist/agent-handoff.js

@@ -0,0 +1,298 @@
+// src/agent-handoff/index.ts
+var API_VERSION = "^0.1.10";
+var state = {
+  invocationCount: 0,
+  sentCount: 0,
+  skippedCount: 0,
+  errorCount: 0,
+  lastMessageId: null,
+  lastPayloadHash: "",
+  eventUnsubscribers: []
+};
+var DEFAULTS = {
+  enabled: true,
+  subjectPrefix: "handoff: ",
+  includeResult: true,
+  includeTodos: true,
+  maxBodyChars: 4e3,
+  to: "leader"
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  return {
+    enabled: r["enabled"] !== false,
+    subjectPrefix: typeof r["subjectPrefix"] === "string" ? r["subjectPrefix"] : DEFAULTS.subjectPrefix,
+    includeResult: r["includeResult"] !== false,
+    includeTodos: r["includeTodos"] !== false,
+    maxBodyChars: typeof r["maxBodyChars"] === "number" && r["maxBodyChars"] >= 500 ? r["maxBodyChars"] : DEFAULTS.maxBodyChars,
+    to: typeof r["to"] === "string" ? r["to"] : DEFAULTS.to
+  };
+}
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max) + `
+
+[truncated ${s.length - max} chars]` : s;
+}
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = h * 16777619 >>> 0;
+  }
+  return h.toString(16);
+}
+function buildBody(payload, cfg) {
+  const lines = [];
+  lines.push("# Handoff note");
+  if (payload.agentName || payload.agentId) {
+    lines.push(`**From:** ${payload.agentName ?? payload.agentId ?? "unknown"}`);
+  }
+  if (payload.task) lines.push(`**Task:** ${payload.task}`);
+  if (payload.status) lines.push(`**Status:** ${payload.status}`);
+  lines.push(`**Time:** ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  lines.push("");
+  if (cfg.includeResult && payload.result !== void 0) {
+    lines.push("## Result");
+    lines.push("```json");
+    lines.push(JSON.stringify(payload.result, null, 2));
+    lines.push("```");
+    lines.push("");
+  }
+  if (payload.summary) {
+    lines.push("## Summary");
+    lines.push(payload.summary);
+    lines.push("");
+  }
+  if (cfg.includeTodos && Array.isArray(payload.todos) && payload.todos.length > 0) {
+    lines.push("## Todos");
+    for (const t of payload.todos) {
+      const status = t.status ?? "unknown";
+      const content = t.content ?? t.id ?? "untitled";
+      lines.push(`- [${status}] ${content}`);
+    }
+    lines.push("");
+  }
+  return truncate(lines.join("\n"), cfg.maxBodyChars);
+}
+async function sendHandoff(cfg, mailbox, payload) {
+  const body = buildBody(payload, cfg);
+  const hash = hashString(body);
+  if (hash === state.lastPayloadHash) {
+    state.skippedCount += 1;
+    return;
+  }
+  const subject = `${cfg.subjectPrefix}${payload.agentName ?? payload.agentId ?? "subagent"} \u2014 ${payload.status ?? "done"}`.slice(
+    0,
+    200
+  );
+  const sendInput = {
+    from: "plugin:agent-handoff",
+    to: cfg.to,
+    type: "status",
+    subject,
+    body,
+    priority: "normal"
+  };
+  const result = await mailbox.send(sendInput);
+  state.sentCount += 1;
+  state.lastMessageId = result.id ?? null;
+  state.lastPayloadHash = hash;
+}
+var plugin = {
+  name: "agent-handoff",
+  version: "0.1.0",
+  description: "Listens for subagent.done events and posts structured handoff notes to the project mailbox",
+  apiVersion: API_VERSION,
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: { type: "boolean", default: true, description: "Master switch." },
+      subjectPrefix: {
+        type: "string",
+        default: DEFAULTS.subjectPrefix,
+        description: "Prepended to handoff message subjects."
+      },
+      includeResult: {
+        type: "boolean",
+        default: true,
+        description: "Include the subagent result payload in the handoff body."
+      },
+      includeTodos: {
+        type: "boolean",
+        default: true,
+        description: "Include remaining/completed todos from the subagent."
+      },
+      maxBodyChars: {
+        type: "number",
+        minimum: 500,
+        default: 4e3,
+        description: "Hard cap on handoff body size."
+      },
+      to: {
+        type: "string",
+        default: "leader",
+        description: "Default mailbox recipient for handoff notes."
+      }
+    }
+  },
+  setup(api) {
+    state.invocationCount = 0;
+    state.sentCount = 0;
+    state.skippedCount = 0;
+    state.errorCount = 0;
+    state.lastMessageId = null;
+    state.lastPayloadHash = "";
+    for (const off of state.eventUnsubscribers) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    state.eventUnsubscribers = [];
+    const cfg = readConfig(api.config.extensions?.["agent-handoff"]);
+    const mailbox = api.mailbox;
+    if (cfg.enabled && api.onEvent) {
+      const offDone = api.onEvent("subagent.done", (payload) => {
+        state.invocationCount += 1;
+        if (!mailbox) {
+          state.skippedCount += 1;
+          return;
+        }
+        const p = payload ?? {};
+        sendHandoff(cfg, mailbox, p).catch((err) => {
+          state.errorCount += 1;
+          api.log.warn("agent-handoff: mailbox.send failed", {
+            error: err instanceof Error ? err.message : String(err)
+          });
+        });
+      });
+      state.eventUnsubscribers.push(offDone);
+    }
+    api.tools.register({
+      name: "handoff_note",
+      description: "Manually compose and send a handoff note to another agent via the project mailbox.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          to: { type: "string", description: "Recipient (default: leader)." },
+          task: { type: "string", description: "Short task description." },
+          summary: { type: "string", description: "What the next agent needs to know." },
+          todos: {
+            type: "array",
+            items: { type: "object" },
+            description: "Optional todo list to carry forward."
+          },
+          result: { description: "Optional structured result payload." }
+        }
+      },
+      permission: "auto",
+      category: "Coordination",
+      mutating: false,
+      async execute(input) {
+        if (!cfg.enabled) return { ok: false, error: "agent-handoff is disabled" };
+        if (!mailbox) return { ok: false, error: "mailbox not available" };
+        const payload = {
+          agentName: "manual",
+          task: input.task,
+          summary: input.summary,
+          result: input.result,
+          todos: Array.isArray(input.todos) ? input.todos : void 0
+        };
+        const recipient = input.to ?? cfg.to;
+        try {
+          const body = buildBody(payload, cfg);
+          const result = await mailbox.send({
+            from: "plugin:agent-handoff",
+            to: recipient,
+            type: "status",
+            subject: `${cfg.subjectPrefix}manual note \u2014 ${payload.task ?? "handoff"}`.slice(0, 200),
+            body,
+            priority: "normal"
+          });
+          state.sentCount += 1;
+          state.lastMessageId = result.id ?? null;
+          return { ok: true, messageId: result.id, to: recipient };
+        } catch (err) {
+          state.errorCount += 1;
+          return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      }
+    });
+    api.tools.register({
+      name: "handoff_status",
+      description: "Reports agent-handoff counters and the last handoff message id.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          subjectPrefix: cfg.subjectPrefix,
+          includeResult: cfg.includeResult,
+          includeTodos: cfg.includeTodos,
+          maxBodyChars: cfg.maxBodyChars,
+          defaultRecipient: cfg.to,
+          mailboxAvailable: Boolean(mailbox),
+          counters: {
+            invocations: state.invocationCount,
+            sent: state.sentCount,
+            skipped: state.skippedCount,
+            errors: state.errorCount
+          },
+          lastMessageId: state.lastMessageId
+        };
+      }
+    });
+    api.log.info("agent-handoff plugin loaded", {
+      version: "0.1.0",
+      enabled: cfg.enabled,
+      mailboxAvailable: Boolean(mailbox)
+    });
+  },
+  teardown(api) {
+    for (const off of state.eventUnsubscribers) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    state.eventUnsubscribers = [];
+    const final = {
+      invocations: state.invocationCount,
+      sent: state.sentCount,
+      skipped: state.skippedCount,
+      errors: state.errorCount
+    };
+    state.invocationCount = 0;
+    state.sentCount = 0;
+    state.skippedCount = 0;
+    state.errorCount = 0;
+    state.lastMessageId = null;
+    state.lastPayloadHash = "";
+    api.log.info("agent-handoff: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: `agent-handoff: ${state.invocationCount} event(s), ${state.sentCount} sent, ${state.skippedCount} skipped, ${state.errorCount} error(s)`,
+      counters: {
+        invocations: state.invocationCount,
+        sent: state.sentCount,
+        skipped: state.skippedCount,
+        errors: state.errorCount
+      },
+      lastMessageId: state.lastMessageId
+    };
+  }
+};
+var agent_handoff_default = plugin;
+
+export { agent_handoff_default as default };

package/dist/api-compatibility-gate.d.ts

@@ -0,0 +1,38 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * api-compatibility-gate plugin — guards public API surface changes.
+ *
+ * Registers a PostToolUse hook on `write|edit` to entry-point files
+ * (`index.ts`, `src/index.ts`, or package `main`/`module`/`exports`
+ * targets). For each such edit it reads the previous version from git
+ * (`git show HEAD:<path>`), parses exported identifiers with simple
+ * regex heuristics, and reports any removed exports as breaking changes.
+ *
+ * Tools registered:
+ * - api_compat_status : Show config + per-session counters.
+ *
+ * Hooks registered:
+ * - PostToolUse with matcher `write|edit`.
+ *
+ * Config (`config.extensions['api-compatibility-gate']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "severity": "warn",          // "warn" | "block"
+ *   "entryPointPatterns": [      // glob-style patterns
+ *     "**&#47;index.ts",
+ *     "**&#47;index.js",
+ *     "**&#47;src/index.ts"
+ *   ],
+ *   "trackGitHistory": true      // read pre-edit source from git
+ * }
+ * ```
+ *
+ * @public
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };

package/dist/api-compatibility-gate.js

@@ -0,0 +1,357 @@
+import { execFileSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { relative, isAbsolute, dirname, resolve, basename, extname } from 'path';
+
+// src/api-compatibility-gate/index.ts
+var API_VERSION = "^0.1.10";
+var state = {
+  invocationCount: 0,
+  skippedCount: 0,
+  checkedCount: 0,
+  cleanCount: 0,
+  breakingCount: 0,
+  errorCount: 0,
+  lastResult: null,
+  hookUnregister: null
+};
+var DEFAULTS = {
+  enabled: false,
+  severity: "warn",
+  entryPointPatterns: ["**/index.ts", "**/index.js", "**/src/index.ts", "src/index.ts"],
+  trackGitHistory: true
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  return {
+    enabled: r["enabled"] !== false,
+    severity: r["severity"] === "block" ? "block" : DEFAULTS.severity,
+    entryPointPatterns: Array.isArray(r["entryPointPatterns"]) ? r["entryPointPatterns"].filter((x) => typeof x === "string") : DEFAULTS.entryPointPatterns,
+    trackGitHistory: r["trackGitHistory"] !== false
+  };
+}
+function normalizePath(p) {
+  return p.replace(/\\/g, "/");
+}
+function patternToRegex(pattern) {
+  const normalized = normalizePath(pattern);
+  let regex = "^";
+  let i = 0;
+  while (i < normalized.length) {
+    const c = normalized[i];
+    if (c === "*" && normalized[i + 1] === "*") {
+      if (normalized[i + 2] === "/") {
+        regex += "(?:.*/)?";
+        i += 3;
+      } else {
+        regex += ".*";
+        i += 2;
+      }
+    } else if (c === "*") {
+      regex += "[^/]*";
+      i += 1;
+    } else if (c === "?") {
+      regex += "[^/]";
+      i += 1;
+    } else {
+      regex += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+      i += 1;
+    }
+  }
+  regex += "$";
+  return new RegExp(regex);
+}
+function matchesAnyPattern(filePath, patterns) {
+  const normalized = normalizePath(filePath);
+  return patterns.some((p) => patternToRegex(p).test(normalized));
+}
+function resolveToProjectRoot(filePath) {
+  if (isAbsolute(filePath)) return resolve(filePath);
+  return resolve(process.cwd(), filePath);
+}
+function withinProject(filePath) {
+  if (typeof filePath !== "string" || filePath.length === 0 || filePath.length > 4096) return false;
+  const resolved = resolveToProjectRoot(filePath);
+  const rel = relative(process.cwd(), resolved);
+  if (rel === "" || rel === ".") return true;
+  if (rel.startsWith("..")) return false;
+  if (isAbsolute(rel)) return false;
+  return true;
+}
+function isPackageEntryPoint(filePath) {
+  const resolved = resolveToProjectRoot(filePath);
+  const dir = dirname(resolved);
+  const pkgPath = resolve(dir, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const entries = [];
+    if (pkg.main) entries.push(pkg.main);
+    if (pkg.module) entries.push(pkg.module);
+    if (pkg.exports) {
+      if (typeof pkg.exports === "string") {
+        entries.push(pkg.exports);
+      } else if (typeof pkg.exports === "object" && pkg.exports !== null) {
+        const dot = pkg.exports["."];
+        if (typeof dot === "string") entries.push(dot);
+        else if (dot && typeof dot === "object") {
+          for (const v of Object.values(dot)) {
+            if (typeof v === "string") entries.push(v);
+          }
+        }
+      }
+    }
+    for (const entry of entries) {
+      const entryResolved = resolve(dir, entry);
+      if (entryResolved === resolved) return true;
+      if (basename(dirname(entryResolved)) === basename(dirname(resolved)) && basename(entryResolved, extname(entryResolved)) === basename(resolved, extname(resolved))) {
+        return true;
+      }
+    }
+  } catch {
+  }
+  return false;
+}
+function isEntryPoint(filePath, patterns) {
+  if (!withinProject(filePath)) return false;
+  if (matchesAnyPattern(filePath, patterns)) return true;
+  return isPackageEntryPoint(filePath);
+}
+function extractExports(source) {
+  const exports = /* @__PURE__ */ new Set();
+  const declRegex = /export\s+(?:async\s+)?(?:const|let|var|function|class|interface|type|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+  for (const match of source.matchAll(declRegex)) {
+    exports.add(match[1]);
+  }
+  const namedRegex = /export\s*\{([^}]*)\}/g;
+  for (const match of source.matchAll(namedRegex)) {
+    const clauses = match[1].split(",").map((s) => s.trim()).filter(Boolean);
+    for (const clause of clauses) {
+      const parts = clause.split(/\s+as\s+/);
+      const exportedName = parts.length > 1 ? parts[parts.length - 1].trim() : parts[0].trim();
+      if (exportedName) exports.add(exportedName);
+    }
+  }
+  const starRegex = /export\s*\*\s*from\s*['"]([^'"]+)['"]/g;
+  for (const match of source.matchAll(starRegex)) {
+    exports.add(`* from '${match[1]}'`);
+  }
+  if (/\bexport\s+default\b/.test(source)) {
+    exports.add("default");
+  }
+  const cjsRegex = /module\.exports\s*=\s*\{([^}]*)\}/g;
+  for (const match of source.matchAll(cjsRegex)) {
+    const clauses = match[1].split(",").map((s) => s.trim()).filter(Boolean);
+    for (const clause of clauses) {
+      const key = clause.split(":")[0].trim().replace(/['"]/g, "");
+      if (key) exports.add(key);
+    }
+  }
+  const cjsPropRegex = /module\.exports\.([A-Za-z_$][A-Za-z0-9_$]*)\s*=/g;
+  for (const match of source.matchAll(cjsPropRegex)) {
+    exports.add(match[1]);
+  }
+  return exports;
+}
+function readGitVersion(filePath) {
+  const resolved = resolveToProjectRoot(filePath);
+  const relPath = normalizePath(relative(process.cwd(), resolved));
+  try {
+    const out = execFileSync("git", ["show", `HEAD:${relPath}`], {
+      encoding: "utf-8",
+      cwd: process.cwd(),
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return out;
+  } catch {
+    return null;
+  }
+}
+function readCurrentFile(filePath) {
+  try {
+    const resolved = resolveToProjectRoot(filePath);
+    return readFileSync(resolved, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function compareExports(before, after) {
+  const beforeExports = extractExports(before);
+  const afterExports = extractExports(after);
+  const removed = [...beforeExports].filter((e) => !afterExports.has(e)).sort();
+  const added = [...afterExports].filter((e) => !beforeExports.has(e)).sort();
+  return { removed, added };
+}
+var plugin = {
+  name: "api-compatibility-gate",
+  version: "0.1.0",
+  description: "PostToolUse hook that detects breaking API changes (removed exports) in entry-point files after writes or edits",
+  apiVersion: API_VERSION,
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: { type: "boolean", default: true, description: "Master switch." },
+      severity: {
+        type: "string",
+        enum: ["warn", "block"],
+        default: "warn",
+        description: "warn = inject context; block = refuse the mutating tool."
+      },
+      entryPointPatterns: {
+        type: "array",
+        items: { type: "string" },
+        default: DEFAULTS.entryPointPatterns,
+        description: "Glob-style patterns for entry-point files to guard."
+      },
+      trackGitHistory: {
+        type: "boolean",
+        default: true,
+        description: "Read the pre-edit version from git HEAD to compute removed exports."
+      }
+    }
+  },
+  setup(api) {
+    state.invocationCount = 0;
+    state.skippedCount = 0;
+    state.checkedCount = 0;
+    state.cleanCount = 0;
+    state.breakingCount = 0;
+    state.errorCount = 0;
+    state.lastResult = null;
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const cfg = readConfig(api.config.extensions?.["api-compatibility-gate"]);
+    const hook = (input) => {
+      if (!cfg.enabled) return;
+      if (input.toolResult?.isError) return;
+      const inp = input.toolInput ?? {};
+      const filePath = inp["path"];
+      if (!filePath || typeof filePath !== "string") return;
+      state.invocationCount += 1;
+      if (!isEntryPoint(filePath, cfg.entryPointPatterns)) {
+        state.skippedCount += 1;
+        return;
+      }
+      if (!cfg.trackGitHistory) {
+        state.skippedCount += 1;
+        return;
+      }
+      const before = readGitVersion(filePath);
+      if (before === null) {
+        state.skippedCount += 1;
+        return;
+      }
+      const after = readCurrentFile(filePath);
+      if (after === null) {
+        state.errorCount += 1;
+        return;
+      }
+      state.checkedCount += 1;
+      const { removed, added } = compareExports(before, after);
+      state.lastResult = {
+        filePath,
+        removed,
+        added,
+        when: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      if (removed.length === 0) {
+        state.cleanCount += 1;
+        return;
+      }
+      state.breakingCount += 1;
+      const addedLine = added.length > 0 ? `Added exports: ${added.join(", ")}
+` : "";
+      const message = `
+\u26A0\uFE0F api-compatibility-gate: ${filePath} removed exported identifiers: ${removed.join(", ")}
+` + addedLine + `These removals are breaking changes. Restore them or bump the major version.`;
+      if (cfg.severity === "block") {
+        return {
+          decision: "block",
+          reason: message,
+          additionalContext: message
+        };
+      }
+      return { additionalContext: message };
+    };
+    state.hookUnregister = api.registerHook("PostToolUse", "write|edit", hook);
+    api.tools.register({
+      name: "api_compat_status",
+      description: "Reports api-compatibility-gate state: severity, entry-point patterns, and per-session counters.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          severity: cfg.severity,
+          entryPointPatterns: cfg.entryPointPatterns,
+          trackGitHistory: cfg.trackGitHistory,
+          counters: {
+            invocations: state.invocationCount,
+            skipped: state.skippedCount,
+            checked: state.checkedCount,
+            clean: state.cleanCount,
+            breaking: state.breakingCount,
+            errors: state.errorCount
+          },
+          lastResult: state.lastResult
+        };
+      }
+    });
+    api.log.info("api-compatibility-gate plugin loaded", {
+      version: "0.1.0",
+      severity: cfg.severity,
+      entryPointPatterns: cfg.entryPointPatterns
+    });
+  },
+  teardown(api) {
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const final = {
+      invocations: state.invocationCount,
+      checked: state.checkedCount,
+      clean: state.cleanCount,
+      breaking: state.breakingCount,
+      errors: state.errorCount
+    };
+    state.invocationCount = 0;
+    state.skippedCount = 0;
+    state.checkedCount = 0;
+    state.cleanCount = 0;
+    state.breakingCount = 0;
+    state.errorCount = 0;
+    state.lastResult = null;
+    api.log.info("api-compatibility-gate: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: state.errorCount === 0,
+      message: state.lastResult ? `api-compatibility-gate: ${state.checkedCount} checked, last ${state.lastResult.removed.length > 0 ? "BREAKING" : "clean"} (${state.lastResult.removed.length} removed)` : `api-compatibility-gate: ${state.invocationCount} invocation(s), ${state.checkedCount} checked`,
+      counters: {
+        invocations: state.invocationCount,
+        skipped: state.skippedCount,
+        checked: state.checkedCount,
+        clean: state.cleanCount,
+        breaking: state.breakingCount,
+        errors: state.errorCount
+      }
+    };
+  }
+};
+var api_compatibility_gate_default = plugin;
+
+export { api_compatibility_gate_default as default };