@wrongstack/plugins 0.277.1 → 0.280.0

package/dist/checkpoint.d.ts

@@ -0,0 +1,55 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * checkpoint plugin — in-session file snapshots with one-call undo.
+ *
+ * Before every `write`/`edit` the plugin captures the file's current
+ * content (a `PreToolUse` hook reads the file from disk *before* the
+ * tool mutates it). Snapshots are held in an in-memory ring, so the
+ * agent can always roll back a bad edit — even one made outside git
+ * (untracked files, mid-refactor states, dirty worktrees).
+ *
+ * Tools:
+ *  - `checkpoint_list`    — list captured snapshots (newest first)
+ *  - `checkpoint_restore` — restore a file (or all files of a
+ *    checkpoint) to its captured content; files that did not exist
+ *    at capture time are noted, never deleted
+ *  - `checkpoint_create`  — manually snapshot a list of files before
+ *    a risky operation (bulk rename, codemod, script run)
+ *
+ * This deliberately complements git: `git checkout` needs a commit
+ * to restore to; checkpoint restores to *any* pre-edit state from
+ * this session, including states that were never committed.
+ *
+ * Config (`config.extensions['checkpoint']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "autoCapture": true,     // snapshot before every write/edit
+ *   "maxSnapshots": 50,      // ring size
+ *   "maxFileBytes": 1048576  // skip files larger than this (1 MiB)
+ * }
+ * ```
+ *
+ * Toggle off with `{ "name": "checkpoint", "enabled": false }` in
+ * `config.plugins`, or `"enabled": false` in the options above.
+ *
+ * @public
+ */
+
+interface Snapshot {
+    id: string;
+    createdAt: string;
+    /** What triggered the capture: 'auto:write', 'auto:edit', or 'manual'. */
+    origin: string;
+    files: Array<{
+        path: string;
+        /** null = file did not exist at capture time. */
+        content: string | null;
+        bytes: number;
+    }>;
+}
+declare const plugin: Plugin;
+
+export { type Snapshot, plugin as default };

package/dist/checkpoint.js

@@ -0,0 +1,305 @@
+import { mkdirSync, writeFileSync, statSync, readFileSync } from 'fs';
+import { dirname } from 'path';
+
+// src/checkpoint/index.ts
+var state = {
+  snapshots: [],
+  nextId: 1,
+  captures: 0,
+  restores: 0,
+  skippedLarge: 0,
+  hookUnregister: null
+};
+var DEFAULTS = {
+  enabled: true,
+  autoCapture: true,
+  maxSnapshots: 50,
+  maxFileBytes: 1048576
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  return {
+    enabled: r["enabled"] !== false,
+    autoCapture: r["autoCapture"] !== false,
+    maxSnapshots: typeof r["maxSnapshots"] === "number" && r["maxSnapshots"] >= 1 && r["maxSnapshots"] <= 500 ? r["maxSnapshots"] : DEFAULTS.maxSnapshots,
+    maxFileBytes: typeof r["maxFileBytes"] === "number" && r["maxFileBytes"] >= 1024 ? r["maxFileBytes"] : DEFAULTS.maxFileBytes
+  };
+}
+function captureFile(path, maxBytes) {
+  try {
+    const st = statSync(path);
+    if (st.size > maxBytes) return "too-large";
+    const content = readFileSync(path, "utf-8");
+    return { path, content, bytes: st.size };
+  } catch {
+    return { path, content: null, bytes: 0 };
+  }
+}
+function pushSnapshot(snapshot, maxSnapshots) {
+  state.snapshots.push(snapshot);
+  if (state.snapshots.length > maxSnapshots) {
+    state.snapshots.splice(0, state.snapshots.length - maxSnapshots);
+  }
+}
+var plugin = {
+  name: "checkpoint",
+  version: "0.1.0",
+  description: "In-session file snapshots: auto-captures content before every write/edit and restores any pre-edit state on demand",
+  apiVersion: "^0.1.10",
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: { type: "boolean", default: true, description: "Master switch." },
+      autoCapture: {
+        type: "boolean",
+        default: true,
+        description: "Snapshot the target file before every write/edit tool call."
+      },
+      maxSnapshots: {
+        type: "number",
+        minimum: 1,
+        maximum: 500,
+        default: 50,
+        description: "Snapshot ring size \u2014 oldest snapshots are dropped first."
+      },
+      maxFileBytes: {
+        type: "number",
+        minimum: 1024,
+        default: 1048576,
+        description: "Files larger than this are not captured."
+      }
+    }
+  },
+  setup(api) {
+    state.snapshots = [];
+    state.nextId = 1;
+    state.captures = 0;
+    state.restores = 0;
+    state.skippedLarge = 0;
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const cfg = readConfig(api.config.extensions?.["checkpoint"]);
+    if (cfg.enabled && cfg.autoCapture) {
+      const hook = (input) => {
+        const ti = input.toolInput ?? {};
+        const raw = ti["path"] ?? ti["file_path"] ?? ti["filePath"];
+        if (typeof raw !== "string" || raw.length === 0) return;
+        const captured = captureFile(raw, cfg.maxFileBytes);
+        if (captured === "too-large") {
+          state.skippedLarge += 1;
+          return;
+        }
+        pushSnapshot(
+          {
+            id: `cp-${state.nextId++}`,
+            createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+            origin: `auto:${input.toolName ?? "unknown"}`,
+            files: [captured]
+          },
+          cfg.maxSnapshots
+        );
+        state.captures += 1;
+        api.metrics.counter("captures");
+      };
+      state.hookUnregister = api.registerHook("PreToolUse", "write|edit", hook);
+    }
+    api.tools.register({
+      name: "checkpoint_create",
+      description: "Manually snapshot the current content of one or more files before a risky operation (codemod, bulk rename, script run). Restore later with checkpoint_restore.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "File paths to snapshot."
+          },
+          label: { type: "string", description: "Optional label recorded as the origin." }
+        },
+        required: ["paths"]
+      },
+      permission: "auto",
+      category: "Safety",
+      mutating: false,
+      async execute(input) {
+        if (!cfg.enabled) return { ok: false, error: "checkpoint is disabled" };
+        const paths = Array.isArray(input.paths) ? input.paths.filter((p) => typeof p === "string" && p.length > 0) : [];
+        if (paths.length === 0) return { ok: false, error: "paths must not be empty" };
+        const files = [];
+        let skipped = 0;
+        for (const p of paths) {
+          const captured = captureFile(p, cfg.maxFileBytes);
+          if (captured === "too-large") {
+            skipped += 1;
+            state.skippedLarge += 1;
+            continue;
+          }
+          files.push(captured);
+        }
+        if (files.length === 0) {
+          return { ok: false, error: "all files were skipped (too large)" };
+        }
+        const snapshot = {
+          id: `cp-${state.nextId++}`,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          origin: input.label?.trim() ? `manual:${input.label.trim()}` : "manual",
+          files
+        };
+        pushSnapshot(snapshot, cfg.maxSnapshots);
+        state.captures += 1;
+        api.metrics.counter("captures");
+        return {
+          ok: true,
+          id: snapshot.id,
+          capturedFiles: files.map((f) => ({ path: f.path, existed: f.content !== null })),
+          skippedTooLarge: skipped
+        };
+      }
+    });
+    api.tools.register({
+      name: "checkpoint_list",
+      description: "List captured file snapshots (newest first) with ids for checkpoint_restore.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit: { type: "number", description: "Max entries to return (default 20)." }
+        }
+      },
+      permission: "auto",
+      category: "Safety",
+      mutating: false,
+      async execute(input) {
+        const limit = typeof input.limit === "number" && input.limit >= 1 ? Math.floor(input.limit) : 20;
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          autoCapture: cfg.autoCapture,
+          total: state.snapshots.length,
+          snapshots: [...state.snapshots].reverse().slice(0, limit).map((s) => ({
+            id: s.id,
+            createdAt: s.createdAt,
+            origin: s.origin,
+            files: s.files.map((f) => ({
+              path: f.path,
+              existed: f.content !== null,
+              bytes: f.bytes
+            }))
+          })),
+          counters: {
+            captures: state.captures,
+            restores: state.restores,
+            skippedLarge: state.skippedLarge
+          }
+        };
+      }
+    });
+    api.tools.register({
+      name: "checkpoint_restore",
+      description: "Restore file(s) to the content captured in a snapshot (see checkpoint_list). Restores every file in the snapshot, or a single file when `path` is given. Files that did not exist at capture time are reported but never deleted.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Snapshot id (cp-N). Default: the newest snapshot." },
+          path: {
+            type: "string",
+            description: "Restore only this file from the snapshot (optional)."
+          }
+        }
+      },
+      permission: "confirm",
+      category: "Safety",
+      mutating: true,
+      async execute(input) {
+        if (!cfg.enabled) return { ok: false, error: "checkpoint is disabled" };
+        const snapshot = input.id ? state.snapshots.find((s) => s.id === input.id) : state.snapshots[state.snapshots.length - 1];
+        if (!snapshot) {
+          return {
+            ok: false,
+            error: input.id ? `no snapshot with id "${input.id}"` : "no snapshots captured yet"
+          };
+        }
+        const targets = input.path ? snapshot.files.filter((f) => f.path === input.path) : snapshot.files;
+        if (targets.length === 0) {
+          return { ok: false, error: `snapshot ${snapshot.id} has no entry for "${input.path}"` };
+        }
+        const restored = [];
+        const createdByTool = [];
+        const errors = [];
+        for (const f of targets) {
+          if (f.content === null) {
+            createdByTool.push(f.path);
+            continue;
+          }
+          try {
+            mkdirSync(dirname(f.path), { recursive: true });
+            writeFileSync(f.path, f.content);
+            restored.push(f.path);
+          } catch (err) {
+            errors.push({ path: f.path, error: err instanceof Error ? err.message : String(err) });
+          }
+        }
+        if (restored.length > 0) {
+          state.restores += 1;
+          api.metrics.counter("restores");
+        }
+        return {
+          ok: errors.length === 0,
+          snapshotId: snapshot.id,
+          restored,
+          notRestoredFileDidNotExist: createdByTool,
+          errors
+        };
+      }
+    });
+    api.log.info("checkpoint plugin loaded", {
+      version: "0.1.0",
+      enabled: cfg.enabled,
+      autoCapture: cfg.autoCapture,
+      maxSnapshots: cfg.maxSnapshots
+    });
+  },
+  teardown(api) {
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const final = {
+      captures: state.captures,
+      restores: state.restores,
+      skippedLarge: state.skippedLarge,
+      snapshotsHeld: state.snapshots.length
+    };
+    state.snapshots = [];
+    state.nextId = 1;
+    state.captures = 0;
+    state.restores = 0;
+    state.skippedLarge = 0;
+    api.log.info("checkpoint: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: `checkpoint: ${state.snapshots.length} snapshot(s) held, ${state.captures} capture(s), ${state.restores} restore(s), ${state.skippedLarge} skipped (too large)`,
+      counters: {
+        snapshotsHeld: state.snapshots.length,
+        captures: state.captures,
+        restores: state.restores,
+        skippedLarge: state.skippedLarge
+      }
+    };
+  }
+};
+var checkpoint_default = plugin;
+
+export { checkpoint_default as default };

package/dist/commit-validator.d.ts

@@ -0,0 +1,33 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * commit-message-validator plugin — PreToolUse hook that validates
+ * conventional-commit format on `git_autocommit` and `bash` (git commit)
+ * before the commit is created.
+ *
+ * Tools registered:
+ * - commit_validator_status : Show config + per-session counters.
+ *
+ * Hooks registered:
+ * - PreToolUse with matcher `bash|git_autocommit`. Inspects the
+ *   commit message (from toolInput.message for git_autocommit, or
+ *   parsed from `-m` flag for bash git commit). If the message does
+ *   not match the conventional-commit format, the call is blocked.
+ *
+ * Config (`config.extensions['commit-validator']`):
+ *
+ * ```jsonc
+ * {
+ *   "mode": "block",        // "block" | "warn"
+ *   "requireScope": false,  // require a scope in parentheses
+ *   "allowedTypes": [],     // empty = all types allowed; or ["feat","fix","docs",...]
+ *   "maxSubjectLength": 72  // subject line character limit
+ * }
+ * ```
+ *
+ * @public
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };