@wrongstack/plugins 0.277.2 → 0.280.0

package/dist/branch-guard.js

@@ -0,0 +1,228 @@
+import { execSync } from 'child_process';
+
+// src/branch-guard/index.ts
+var API_VERSION = "^0.1.10";
+var state = {
+  invocationCount: 0,
+  blockCount: 0,
+  warnCount: 0,
+  hookUnregister: null,
+  lastBlock: null
+};
+var DEFAULTS = {
+  branches: ["main", "master"],
+  mode: "block",
+  blockCommit: true,
+  blockPush: true,
+  blockMerge: true
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  const branches = Array.isArray(r["branches"]) ? r["branches"].filter((b) => typeof b === "string") : DEFAULTS.branches;
+  return {
+    branches: branches.length > 0 ? branches : DEFAULTS.branches,
+    mode: r["mode"] === "warn" ? "warn" : "block",
+    blockCommit: r["blockCommit"] !== false,
+    blockPush: r["blockPush"] !== false,
+    blockMerge: r["blockMerge"] !== false
+  };
+}
+function getCurrentBranch(cwd) {
+  try {
+    const branch = execSync("git branch --show-current", {
+      encoding: "utf-8",
+      timeout: 3e3,
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    return branch || null;
+  } catch {
+    return null;
+  }
+}
+function detectUncommittedChanges(cwd) {
+  try {
+    const output = execSync("git status --porcelain", {
+      encoding: "utf-8",
+      timeout: 3e3,
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    return output.length > 0;
+  } catch {
+    return false;
+  }
+}
+function detectGitCommand(command) {
+  const cmd = command.trim();
+  if (/\bgit\s+commit\b/.test(cmd)) {
+    return { type: "commit", snippet: cmd.slice(0, 120) };
+  }
+  if (/\bgit\s+push\b/.test(cmd)) {
+    return { type: "push", snippet: cmd.slice(0, 120) };
+  }
+  if (/\bgit\s+merge\s/.test(cmd)) {
+    return { type: "merge", snippet: cmd.slice(0, 120) };
+  }
+  return null;
+}
+function shouldBlock(op, cfg) {
+  if (op === "commit") return cfg.blockCommit;
+  if (op === "push") return cfg.blockPush;
+  if (op === "merge") return cfg.blockMerge;
+  return false;
+}
+var plugin = {
+  name: "branch-guard",
+  version: "0.1.0",
+  description: "Pre-tool hook that blocks commits, pushes, and merges to protected branches (default: main, master)",
+  apiVersion: API_VERSION,
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      branches: {
+        type: "array",
+        items: { type: "string" },
+        default: ["main", "master"],
+        description: "Branch names that are protected."
+      },
+      mode: {
+        type: "string",
+        enum: ["block", "warn"],
+        default: "block",
+        description: '"block" refuses the call; "warn" injects context but lets it through.'
+      },
+      blockCommit: { type: "boolean", default: true, description: "Block commits on protected branches." },
+      blockPush: { type: "boolean", default: true, description: "Block pushes from protected branches." },
+      blockMerge: { type: "boolean", default: true, description: "Block merges into protected branches." }
+    }
+  },
+  setup(api) {
+    state.invocationCount = 0;
+    state.blockCount = 0;
+    state.warnCount = 0;
+    state.hookUnregister = null;
+    state.lastBlock = null;
+    const cfg = readConfig(api.config.extensions?.["branch-guard"]);
+    const cwd = typeof process.cwd === "function" ? process.cwd() : void 0;
+    const protectedSet = new Set(cfg.branches);
+    const hook = (input) => {
+      const toolName = input.toolName ?? "";
+      const inp = input.toolInput ?? {};
+      state.invocationCount += 1;
+      let gitOp = null;
+      if (toolName === "git_autocommit") {
+        gitOp = { type: "commit", snippet: "git_autocommit" };
+      } else if (toolName === "bash") {
+        const command = inp["command"];
+        if (typeof command !== "string") return;
+        gitOp = detectGitCommand(command);
+      }
+      if (!gitOp) return;
+      if (!shouldBlock(gitOp.type, cfg)) return;
+      const branch = getCurrentBranch(cwd);
+      if (!branch) return;
+      if (!protectedSet.has(branch)) return;
+      const when = (/* @__PURE__ */ new Date()).toISOString();
+      const opVerb = gitOp.type === "commit" ? "committing to" : gitOp.type === "push" ? "pushing from" : "merging into";
+      const hasUncommitted = detectUncommittedChanges(cwd);
+      const suggestionParts = [];
+      if (hasUncommitted) {
+        suggestionParts.push("git stash");
+      }
+      suggestionParts.push("git checkout -b feat/my-change");
+      if (hasUncommitted) {
+        suggestionParts.push("git stash pop");
+      }
+      suggestionParts.push(`git ${gitOp.type} ...`);
+      const suggestion = suggestionParts.join(" \u2192 ");
+      const reason = `branch-guard: refused to ${gitOp.type} on protected branch '${branch}'. You're on a protected branch. Use a feature branch instead.
+` + (hasUncommitted ? `You have uncommitted changes. Safe workflow:
+  ${suggestion}
+` : `Safe workflow:
+  ${suggestion}
+`) + `Protected branches: ${cfg.branches.join(", ")}.`;
+      state.lastBlock = { tool: toolName, branch, command: gitOp.snippet, when };
+      if (cfg.mode === "block") {
+        state.blockCount += 1;
+        return {
+          decision: "block",
+          reason
+        };
+      }
+      state.warnCount += 1;
+      return {
+        decision: "allow",
+        additionalContext: `
+\u26A0\uFE0F branch-guard: you are ${opVerb} protected branch '${branch}'. ` + (hasUncommitted ? `You have uncommitted changes \u2014 consider \`git stash\` before switching branches. ` : "") + `Use a feature branch instead. Protected: ${cfg.branches.join(", ")}.`
+      };
+    };
+    state.hookUnregister = api.registerHook("PreToolUse", "bash|git_autocommit", hook);
+    api.tools.register({
+      name: "branch_guard_status",
+      description: "Reports branch-guard state: protected branches, mode, and per-session invocation/block/warn counters.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Git",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          branches: cfg.branches,
+          mode: cfg.mode,
+          blockCommit: cfg.blockCommit,
+          blockPush: cfg.blockPush,
+          blockMerge: cfg.blockMerge,
+          counters: {
+            invocations: state.invocationCount,
+            blocks: state.blockCount,
+            warns: state.warnCount
+          },
+          lastBlock: state.lastBlock
+        };
+      }
+    });
+    api.log.info("branch-guard plugin loaded", {
+      version: "0.1.0",
+      branches: cfg.branches,
+      mode: cfg.mode
+    });
+  },
+  teardown(api) {
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const final = {
+      invocations: state.invocationCount,
+      blocks: state.blockCount,
+      warns: state.warnCount
+    };
+    state.invocationCount = 0;
+    state.blockCount = 0;
+    state.warnCount = 0;
+    state.lastBlock = null;
+    api.log.info("branch-guard: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: state.lastBlock === null ? `branch-guard: ${state.invocationCount} invocation(s), ${state.blockCount} block(s)` : `branch-guard: last block on '${state.lastBlock.branch}' (${state.lastBlock.command}) at ${state.lastBlock.when}`,
+      counters: {
+        invocations: state.invocationCount,
+        blocks: state.blockCount,
+        warns: state.warnCount
+      },
+      lastBlock: state.lastBlock
+    };
+  }
+};
+var branch_guard_default = plugin;
+
+export { branch_guard_default as default };

package/dist/changelog-writer.d.ts

@@ -0,0 +1,73 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * changelog-writer plugin — turns session activity into
+ * Keep-a-Changelog entries.
+ *
+ * While the session runs, the plugin passively collects work signals
+ * from the event bus: files touched by `write`/`edit`, and commit
+ * subjects observed from `git_autocommit` / `bash git commit`
+ * invocations. Commit subjects in conventional-commit format are
+ * mapped to Keep-a-Changelog sections:
+ *
+ *   feat → Added · fix → Fixed · perf/refactor → Changed ·
+ *   docs → Documentation · chore/build/ci → Maintenance ·
+ *   revert/remove → Removed · sec/security → Security
+ *
+ * Tools:
+ *  - `changelog_add`     — record an entry manually ("Added dark mode")
+ *  - `changelog_preview` — render the pending Unreleased block
+ *  - `changelog_write`   — merge the pending entries into
+ *    `CHANGELOG.md` under `## [Unreleased]` (creates the file with a
+ *    Keep-a-Changelog header when missing); pending entries are
+ *    cleared after a successful write
+ *
+ * Both `changelog_preview` and `changelog_write` accept `polish: true`
+ * to rewrite the block into user-facing release-notes wording via the
+ * host LLM (`api.llm`) — provider/model follow the plugin's
+ * `config.extensions['changelog-writer'].llm` override, then the
+ * session default. Polish is best-effort: on any LLM failure (or when
+ * the response stops looking like the block) the raw entries are used.
+ *
+ * Config (`config.extensions['changelog-writer']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "filePath": "CHANGELOG.md",
+ *   "collectCommits": true,
+ *   "maxEntries": 200
+ * }
+ * ```
+ *
+ * Toggle off with `{ "name": "changelog-writer", "enabled": false }`
+ * in `config.plugins`, or `"enabled": false` in the options above.
+ *
+ * @public
+ */
+
+type Section = 'Added' | 'Changed' | 'Fixed' | 'Removed' | 'Security' | 'Documentation' | 'Maintenance';
+interface ChangelogEntry {
+    section: Section;
+    text: string;
+    origin: 'commit' | 'manual';
+    when: string;
+}
+/** Parse "feat(scope): add dark mode" → { section: Added, text: "add dark mode (scope)" }. */
+declare function commitToEntry(subject: string): {
+    section: Section;
+    text: string;
+};
+/** Extract the commit subject from a `git commit -m "..."` command, if any. */
+declare function commitSubjectFromCommand(command: string): string | null;
+declare function renderUnreleasedBlock(entries: ChangelogEntry[]): string;
+/**
+ * Merge a rendered Unreleased block into existing changelog content:
+ * inserted directly under `## [Unreleased]` (existing unreleased
+ * content is preserved below the new lines). Creates the standard
+ * header when the file has no Unreleased heading.
+ */
+declare function mergeIntoChangelog(existing: string | null, block: string): string;
+declare const plugin: Plugin;
+
+export { type ChangelogEntry, commitSubjectFromCommand, commitToEntry, plugin as default, mergeIntoChangelog, renderUnreleasedBlock };

package/dist/changelog-writer.js

@@ -0,0 +1,369 @@
+import { readFileSync, writeFileSync } from 'fs';
+
+// src/changelog-writer/index.ts
+var state = {
+  entries: [],
+  filesTouched: /* @__PURE__ */ new Set(),
+  commitsSeen: 0,
+  writes: 0,
+  polishes: 0,
+  polishErrors: 0,
+  eventUnsubscribers: []
+};
+var DEFAULTS = {
+  enabled: true,
+  filePath: "CHANGELOG.md",
+  collectCommits: true,
+  maxEntries: 200
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  return {
+    enabled: r["enabled"] !== false,
+    filePath: typeof r["filePath"] === "string" && r["filePath"].length > 0 ? r["filePath"] : DEFAULTS.filePath,
+    collectCommits: r["collectCommits"] !== false,
+    maxEntries: typeof r["maxEntries"] === "number" && r["maxEntries"] >= 10 ? r["maxEntries"] : DEFAULTS.maxEntries
+  };
+}
+var TYPE_TO_SECTION = {
+  feat: "Added",
+  feature: "Added",
+  fix: "Fixed",
+  bugfix: "Fixed",
+  perf: "Changed",
+  refactor: "Changed",
+  style: "Changed",
+  docs: "Documentation",
+  doc: "Documentation",
+  chore: "Maintenance",
+  build: "Maintenance",
+  ci: "Maintenance",
+  test: "Maintenance",
+  revert: "Removed",
+  remove: "Removed",
+  sec: "Security",
+  security: "Security"
+};
+var SECTION_ORDER = [
+  "Added",
+  "Changed",
+  "Fixed",
+  "Removed",
+  "Security",
+  "Documentation",
+  "Maintenance"
+];
+function commitToEntry(subject) {
+  const m = /^(\w+)(?:\(([^)]*)\))?!?:\s*(.+)$/.exec(subject.trim());
+  if (m?.[1] && m[3]) {
+    const section = TYPE_TO_SECTION[m[1].toLowerCase()] ?? "Changed";
+    const scope = m[2] ? ` (${m[2]})` : "";
+    return { section, text: `${m[3].trim()}${scope}` };
+  }
+  return { section: "Changed", text: subject.trim() };
+}
+function commitSubjectFromCommand(command) {
+  if (!/\bgit\s+commit\b/.test(command)) return null;
+  const m = /-m\s+(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(command);
+  const subject = m?.[1] ?? m?.[2] ?? m?.[3] ?? null;
+  if (!subject) return null;
+  return subject.split("\n")[0]?.trim() || null;
+}
+var CHANGELOG_HEADER = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+`;
+function renderUnreleasedBlock(entries) {
+  const bySection = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const list = bySection.get(e.section) ?? [];
+    if (!list.includes(e.text)) list.push(e.text);
+    bySection.set(e.section, list);
+  }
+  const parts = [];
+  for (const section of SECTION_ORDER) {
+    const items = bySection.get(section);
+    if (!items || items.length === 0) continue;
+    parts.push(`### ${section}`);
+    parts.push(...items.map((t) => `- ${t}`));
+    parts.push("");
+  }
+  return parts.join("\n").trimEnd();
+}
+function mergeIntoChangelog(existing, block) {
+  if (!existing?.trim()) {
+    return `${CHANGELOG_HEADER}
+${block}
+`;
+  }
+  const unreleasedRe = /^##\s*\[?unreleased\]?.*$/im;
+  const m = unreleasedRe.exec(existing);
+  if (!m || m.index === void 0) {
+    const h1 = /^#\s.*$/m.exec(existing);
+    if (h1 && h1.index !== void 0) {
+      const insertAt2 = h1.index + h1[0].length;
+      return `${existing.slice(0, insertAt2)}
+
+## [Unreleased]
+
+${block}
+${existing.slice(insertAt2)}`;
+    }
+    return `## [Unreleased]
+
+${block}
+
+${existing}`;
+  }
+  const insertAt = m.index + m[0].length;
+  return `${existing.slice(0, insertAt)}
+
+${block}
+${existing.slice(insertAt)}`;
+}
+var plugin = {
+  name: "changelog-writer",
+  version: "0.1.0",
+  description: "Collects session work (commits, edits, manual notes) and writes Keep-a-Changelog entries under [Unreleased] on demand",
+  apiVersion: "^0.1.10",
+  capabilities: { tools: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: { type: "boolean", default: true, description: "Master switch." },
+      filePath: {
+        type: "string",
+        default: "CHANGELOG.md",
+        description: "Changelog file path (relative to the session cwd or absolute)."
+      },
+      collectCommits: {
+        type: "boolean",
+        default: true,
+        description: "Auto-collect entries from conventional commit subjects seen this session."
+      },
+      maxEntries: {
+        type: "number",
+        minimum: 10,
+        default: 200,
+        description: "Cap on pending entries held in memory."
+      }
+    }
+  },
+  setup(api) {
+    state.entries = [];
+    state.filesTouched = /* @__PURE__ */ new Set();
+    state.commitsSeen = 0;
+    state.writes = 0;
+    for (const off of state.eventUnsubscribers) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    state.eventUnsubscribers = [];
+    const cfg = readConfig(api.config.extensions?.["changelog-writer"]);
+    const addEntry = (entry) => {
+      state.entries.push(entry);
+      if (state.entries.length > cfg.maxEntries) {
+        state.entries.splice(0, state.entries.length - cfg.maxEntries);
+      }
+    };
+    const maybePolish = async (block, polish) => {
+      if (!polish || !block || !api.llm) return block;
+      try {
+        const result = await api.llm.complete(
+          'Rewrite this Keep-a-Changelog block into concise, user-facing release-notes wording. Keep the EXACT markdown structure: the same "### Section" headings, one "- " bullet per entry, no entries added or removed. Output ONLY the markdown block.\n\n' + block,
+          { system: "You are a precise technical release-notes editor.", maxTokens: 1500 }
+        );
+        const text = result.text.trim();
+        if (!text.startsWith("###")) return block;
+        state.polishes += 1;
+        api.metrics.counter("polishes");
+        return text;
+      } catch {
+        state.polishErrors += 1;
+        return block;
+      }
+    };
+    if (cfg.enabled && cfg.collectCommits) {
+      const off = api.onPattern("tool.*", (eventName, payload) => {
+        if (!/completed|result|executed/.test(eventName)) return;
+        const p = payload;
+        if (p?.isError) return;
+        const toolName = p?.tool ?? p?.name ?? "";
+        const input = p?.input ?? {};
+        if (toolName === "write" || toolName === "edit") {
+          const raw = input["path"] ?? input["file_path"] ?? input["filePath"];
+          if (typeof raw === "string" && raw) state.filesTouched.add(raw);
+          return;
+        }
+        if (toolName === "bash" || toolName === "exec") {
+          const command = typeof input["command"] === "string" ? input["command"] : "";
+          const subject = command ? commitSubjectFromCommand(command) : null;
+          if (subject) {
+            state.commitsSeen += 1;
+            api.metrics.counter("commits_seen");
+            const { section, text } = commitToEntry(subject);
+            addEntry({ section, text, origin: "commit", when: (/* @__PURE__ */ new Date()).toISOString() });
+          }
+        }
+      });
+      state.eventUnsubscribers.push(off);
+    }
+    api.tools.register({
+      name: "changelog_add",
+      description: "Record a changelog entry for the pending [Unreleased] block (written later via changelog_write).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          text: { type: "string", description: "The entry text, user-facing wording." },
+          section: {
+            type: "string",
+            enum: SECTION_ORDER,
+            description: "Keep-a-Changelog section (default Changed)."
+          }
+        },
+        required: ["text"]
+      },
+      permission: "auto",
+      category: "Docs",
+      mutating: false,
+      async execute(input) {
+        if (!cfg.enabled) return { ok: false, error: "changelog-writer is disabled" };
+        const text = String(input.text ?? "").trim();
+        if (!text) return { ok: false, error: "entry text must not be empty" };
+        const section = SECTION_ORDER.includes(input.section) ? input.section : "Changed";
+        addEntry({ section, text, origin: "manual", when: (/* @__PURE__ */ new Date()).toISOString() });
+        return { ok: true, pendingEntries: state.entries.length };
+      }
+    });
+    api.tools.register({
+      name: "changelog_preview",
+      description: "Render the pending [Unreleased] changelog block collected this session without writing anything. Pass polish:true to rewrite entries into user-facing wording via the LLM.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          polish: {
+            type: "boolean",
+            description: "Rewrite entries into user-facing wording via the LLM (api.llm)."
+          }
+        }
+      },
+      permission: "auto",
+      category: "Docs",
+      mutating: false,
+      async execute(input) {
+        const raw = renderUnreleasedBlock(state.entries);
+        const markdown = raw ? await maybePolish(raw, input.polish === true) : "";
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          filePath: cfg.filePath,
+          pendingEntries: state.entries.length,
+          filesTouched: [...state.filesTouched].slice(0, 50),
+          commitsSeen: state.commitsSeen,
+          polished: input.polish === true && markdown !== raw,
+          llmAvailable: Boolean(api.llm),
+          markdown: markdown || "(no pending entries)"
+        };
+      }
+    });
+    api.tools.register({
+      name: "changelog_write",
+      description: "Merge the pending entries into the changelog file under ## [Unreleased] (creates the file when missing). Clears pending entries on success. Pass polish:true to rewrite entries into user-facing wording via the LLM first.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          polish: {
+            type: "boolean",
+            description: "Rewrite entries into user-facing wording via the LLM (api.llm) before writing."
+          }
+        }
+      },
+      permission: "confirm",
+      category: "Docs",
+      mutating: true,
+      async execute(input) {
+        if (!cfg.enabled) return { ok: false, error: "changelog-writer is disabled" };
+        if (state.entries.length === 0) {
+          return { ok: false, error: "no pending entries \u2014 add some with changelog_add first" };
+        }
+        const block = await maybePolish(
+          renderUnreleasedBlock(state.entries),
+          input.polish === true
+        );
+        let existing = null;
+        try {
+          existing = readFileSync(cfg.filePath, "utf-8");
+        } catch {
+          existing = null;
+        }
+        try {
+          writeFileSync(cfg.filePath, mergeIntoChangelog(existing, block));
+        } catch (err) {
+          return {
+            ok: false,
+            error: `failed to write ${cfg.filePath}: ${err instanceof Error ? err.message : String(err)}`
+          };
+        }
+        const written = state.entries.length;
+        state.entries = [];
+        state.writes += 1;
+        api.metrics.counter("writes");
+        return {
+          ok: true,
+          filePath: cfg.filePath,
+          entriesWritten: written,
+          created: existing === null
+        };
+      }
+    });
+    api.log.info("changelog-writer plugin loaded", {
+      version: "0.1.0",
+      enabled: cfg.enabled,
+      filePath: cfg.filePath,
+      collectCommits: cfg.collectCommits
+    });
+  },
+  teardown(api) {
+    for (const off of state.eventUnsubscribers) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    state.eventUnsubscribers = [];
+    const final = {
+      pendingEntries: state.entries.length,
+      commitsSeen: state.commitsSeen,
+      writes: state.writes,
+      filesTouched: state.filesTouched.size
+    };
+    state.entries = [];
+    state.filesTouched = /* @__PURE__ */ new Set();
+    state.commitsSeen = 0;
+    state.writes = 0;
+    api.log.info("changelog-writer: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: `changelog-writer: ${state.entries.length} pending entr(ies), ${state.commitsSeen} commit(s) collected, ${state.writes} write(s)`,
+      counters: {
+        pendingEntries: state.entries.length,
+        commitsSeen: state.commitsSeen,
+        writes: state.writes,
+        filesTouched: state.filesTouched.size
+      }
+    };
+  }
+};
+var changelog_writer_default = plugin;
+
+export { commitSubjectFromCommand, commitToEntry, changelog_writer_default as default, mergeIntoChangelog, renderUnreleasedBlock };