@wrongstack/plugins 0.305.1 → 0.306.2

package/dist/audit/index.d.ts

@@ -142,6 +142,12 @@ export declare const OFFICIAL_PLUGIN_AUDIT_ENTRIES: readonly [{
     readonly summary: 'Detects runaway tool-call loops (identical repeats and A-B-A-B oscillation) — warns the model, then blocks';
     readonly defaultState: 'active';
     readonly canDisable: true;
+}, {
+    readonly name: 'gitignore-guard';
+    readonly risk: 'low';
+    readonly summary: 'PostToolUse hook that suggests or appends .gitignore entries for build-artifact-looking files after every write or edit';
+    readonly defaultState: 'inactive';
+    readonly canDisable: true;
 }, {
     readonly name: 'path-guard';
     readonly risk: 'medium';

package/dist/audit.js

@@ -168,6 +168,13 @@ var OFFICIAL_PLUGIN_AUDIT_ENTRIES = [
     defaultState: "active",
     canDisable: true
   },
+  {
+    name: "gitignore-guard",
+    risk: "low",
+    summary: "PostToolUse hook that suggests or appends .gitignore entries for build-artifact-looking files after every write or edit",
+    defaultState: "inactive",
+    canDisable: true
+  },
   {
     name: "path-guard",
     risk: "medium",

package/dist/factories/index.d.ts

@@ -1,4 +1,4 @@
 import type { Plugin } from '@wrongstack/core/types';
-export declare const OFFICIAL_PLUGIN_SPECIFIERS: readonly ['@wrongstack/plugins/agent-handoff', '@wrongstack/plugins/cost-tracker', '@wrongstack/plugins/file-watcher', '@wrongstack/plugins/git-autocommit', '@wrongstack/plugins/auto-doc', '@wrongstack/plugins/shell-check', '@wrongstack/plugins/cron', '@wrongstack/plugins/template-engine', '@wrongstack/plugins/semver-bump', '@wrongstack/plugins/secret-scanner', '@wrongstack/plugins/todo-tracker', '@wrongstack/plugins/token-budget', '@wrongstack/plugins/lint-gate', '@wrongstack/plugins/branch-guard', '@wrongstack/plugins/diff-summary', '@wrongstack/plugins/commit-validator', '@wrongstack/plugins/format-on-save', '@wrongstack/plugins/test-runner-gate', '@wrongstack/plugins/import-organizer', '@wrongstack/plugins/knowledge-graph', '@wrongstack/plugins/todo-listener', '@wrongstack/plugins/session-recap', '@wrongstack/plugins/spec-linker', '@wrongstack/plugins/loop-breaker', '@wrongstack/plugins/path-guard', '@wrongstack/plugins/process-guard', '@wrongstack/plugins/context-pins', '@wrongstack/plugins/checkpoint', '@wrongstack/plugins/error-lens', '@wrongstack/plugins/dep-guard', '@wrongstack/plugins/config-validator', '@wrongstack/plugins/notify-hub', '@wrongstack/plugins/changelog-writer', '@wrongstack/plugins/injection-shield', '@wrongstack/plugins/llm-cache', '@wrongstack/plugins/model-router', '@wrongstack/plugins/pr-drafter', '@wrongstack/plugins/prompt-firewall', '@wrongstack/plugins/auto-escalate', '@wrongstack/plugins/test-coverage-gate', '@wrongstack/plugins/type-gate', '@wrongstack/plugins/token-throttle', '@wrongstack/plugins/plugin-stack-observer', '@wrongstack/plugins/dependency-vulnerability-gate', '@wrongstack/plugins/migration-planner', '@wrongstack/plugins/semantic-search-indexer', '@wrongstack/plugins/auto-i18n-extractor', '@wrongstack/plugins/doc-sync-guard', '@wrongstack/plugins/api-compatibility-gate', '@wrongstack/plugins/performance-regression-gate', '@wrongstack/plugins/test-flake-detector', '@wrongstack/plugins/schema-evolution-guard', '@wrongstack/plugins/license-audit-gate', '@wrongstack/plugins/accessibility-auditor', '@wrongstack/plugins/security-hotspot-scanner', '@wrongstack/plugins/dead-code-detector', '@wrongstack/plugins/duplicate-code-detector', '@wrongstack/plugins/code-metrics', '@wrongstack/plugins/refactor-suggester', '@wrongstack/plugins/test-generator', '@wrongstack/plugins/release-notes-generator', '@wrongstack/plugins/smart-rename', '@wrongstack/plugins/feature-flag-tracker', '@wrongstack/plugins/interface-contract-guard'];
+export declare const OFFICIAL_PLUGIN_SPECIFIERS: readonly ['@wrongstack/plugins/agent-handoff', '@wrongstack/plugins/cost-tracker', '@wrongstack/plugins/file-watcher', '@wrongstack/plugins/git-autocommit', '@wrongstack/plugins/auto-doc', '@wrongstack/plugins/shell-check', '@wrongstack/plugins/cron', '@wrongstack/plugins/template-engine', '@wrongstack/plugins/semver-bump', '@wrongstack/plugins/secret-scanner', '@wrongstack/plugins/todo-tracker', '@wrongstack/plugins/token-budget', '@wrongstack/plugins/lint-gate', '@wrongstack/plugins/branch-guard', '@wrongstack/plugins/diff-summary', '@wrongstack/plugins/commit-validator', '@wrongstack/plugins/format-on-save', '@wrongstack/plugins/test-runner-gate', '@wrongstack/plugins/import-organizer', '@wrongstack/plugins/knowledge-graph', '@wrongstack/plugins/todo-listener', '@wrongstack/plugins/session-recap', '@wrongstack/plugins/spec-linker', '@wrongstack/plugins/loop-breaker', '@wrongstack/plugins/gitignore-guard', '@wrongstack/plugins/path-guard', '@wrongstack/plugins/process-guard', '@wrongstack/plugins/context-pins', '@wrongstack/plugins/checkpoint', '@wrongstack/plugins/error-lens', '@wrongstack/plugins/dep-guard', '@wrongstack/plugins/config-validator', '@wrongstack/plugins/notify-hub', '@wrongstack/plugins/changelog-writer', '@wrongstack/plugins/injection-shield', '@wrongstack/plugins/llm-cache', '@wrongstack/plugins/model-router', '@wrongstack/plugins/pr-drafter', '@wrongstack/plugins/prompt-firewall', '@wrongstack/plugins/auto-escalate', '@wrongstack/plugins/test-coverage-gate', '@wrongstack/plugins/type-gate', '@wrongstack/plugins/token-throttle', '@wrongstack/plugins/plugin-stack-observer', '@wrongstack/plugins/dependency-vulnerability-gate', '@wrongstack/plugins/migration-planner', '@wrongstack/plugins/semantic-search-indexer', '@wrongstack/plugins/auto-i18n-extractor', '@wrongstack/plugins/doc-sync-guard', '@wrongstack/plugins/api-compatibility-gate', '@wrongstack/plugins/performance-regression-gate', '@wrongstack/plugins/test-flake-detector', '@wrongstack/plugins/schema-evolution-guard', '@wrongstack/plugins/license-audit-gate', '@wrongstack/plugins/accessibility-auditor', '@wrongstack/plugins/security-hotspot-scanner', '@wrongstack/plugins/dead-code-detector', '@wrongstack/plugins/duplicate-code-detector', '@wrongstack/plugins/code-metrics', '@wrongstack/plugins/refactor-suggester', '@wrongstack/plugins/test-generator', '@wrongstack/plugins/release-notes-generator', '@wrongstack/plugins/smart-rename', '@wrongstack/plugins/feature-flag-tracker', '@wrongstack/plugins/interface-contract-guard'];
 export declare const OFFICIAL_PLUGIN_FACTORIES: readonly (() => Promise<Plugin>)[];
 //# sourceMappingURL=index.d.ts.map

package/dist/factories.js

@@ -24,6 +24,7 @@ var OFFICIAL_PLUGIN_SPECIFIERS = [
   "@wrongstack/plugins/session-recap",
   "@wrongstack/plugins/spec-linker",
   "@wrongstack/plugins/loop-breaker",
+  "@wrongstack/plugins/gitignore-guard",
   "@wrongstack/plugins/path-guard",
   "@wrongstack/plugins/process-guard",
   "@wrongstack/plugins/context-pins",

package/dist/generated-plugin-exports.d.ts

@@ -24,6 +24,7 @@ export { default as featureFlagTrackerPlugin } from './feature-flag-tracker/inde
 export { default as fileWatcherPlugin } from './file-watcher/index.js';
 export { default as formatOnSavePlugin } from './format-on-save/index.js';
 export { default as gitAutocommitPlugin } from './git-autocommit/index.js';
+export { default as gitignoreGuardPlugin } from './gitignore-guard/index.js';
 export { default as importOrganizerPlugin } from './import-organizer/index.js';
 export { default as injectionShieldPlugin } from './injection-shield/index.js';
 export { default as interfaceContractGuardPlugin } from './interface-contract-guard/index.js';

package/dist/gitignore-guard/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * gitignore-guard plugin — repo hygiene for generated files.
+ *
+ * PostToolUse hook that detects writes of build-artifact-looking files
+ * (`dist/`, `coverage/`, `node_modules/`, `*.env`, …) and either
+ * *suggests* a `.gitignore` entry (default) or *appends* it for you.
+ *
+ * Deliberately orthogonal to path-guard: path-guard BLOCKS writes/edits
+ * to protected paths (lockfiles, .env, .git, migrations); gitignore-guard
+ * never blocks a tool — it keeps generated files out of the repository by
+ * growing the project's `.gitignore`. Both hooks can be active at once.
+ *
+ * What counts as a build artifact is configurable (`artifactPatterns`),
+ * with a curated high-precision default list. Patterns use gitignore-style
+ * semantics implemented in `matchGitignorePattern`:
+ *
+ *   - trailing `/`   → directory pattern. Bare name (e.g. `dist/`) matches a
+ *                      directory with that name at any depth; an internal slash
+ *                      (e.g. `docs/generated/`) anchors it to the root.
+ *   - contains `/`   → anchored glob matched against the path relative to
+ *                      the project root, e.g. `docs/generated`
+ *   - otherwise      → glob matched against the basename at any depth,
+ *                      e.g. `*.env` matches `.env` and `config/.env`
+ *
+ * The hook only ever touches `.gitignore` files inside the project root
+ * (containment is checked against the hook's `cwd`). In `append` mode it
+ * appends missing pattern lines to the first existing `.gitignore` walking
+ * from the root down toward the artifact, creating a root `.gitignore` when
+ * none exists. It never rewrites or removes existing lines.
+ *
+ * Tools registered:
+ * - gitignore_guard_status : config + per-session counters.
+ * - gitignore_guard_append : append an entry for a path (or an explicit
+ *   pattern) on demand — the completion path for a `suggest`-mode notice.
+ *
+ * Hooks registered:
+ * - PostToolUse, matcher `write|edit`. Skips tool errors, paths outside
+ *   the project, `.gitignore` writes themselves, paths that already match
+ *   an existing `.gitignore` line, and paths matched by `ignorePatterns`.
+ *
+ * Config (`config.extensions['gitignore-guard']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,             // master switch
+ *   "mode": "suggest",           // "suggest" | "append"
+ *   "artifactPatterns": [...],   // patterns that flag a file as an artifact
+ *   "ignorePatterns": [],        // patterns that never flag (opt-outs)
+ *   "maxAppendPerCall": 5        // append cap per hook invocation
+ * }
+ * ```
+ *
+ * @public
+ */
+import type { Plugin } from '@wrongstack/core/types';
+/**
+ * Curated default list of build-artifact-looking names. High precision on
+ * purpose: this hook fires on every write/edit, so the defaults avoid
+ * ambiguous names (e.g. `build/` and `out/` are committed by some repos).
+ * Users extend or replace the list via `config.extensions['gitignore-guard']`.
+ */
+export declare const DEFAULT_ARTIFACT_PATTERNS: readonly string[];
+/**
+ * Gitignore-style match of `pattern` against `relPath` (project-relative,
+ * forward slashes). See the module doc for the three pattern shapes.
+ */
+export declare function matchGitignorePattern(relPath: string, pattern: string): boolean;
+/** First artifact pattern matching `relPath`, or null when none match. */
+export declare function classifyArtifact(relPath: string, patterns: readonly string[]): string | null;
+export interface GitignoreGuardConfig {
+    enabled: boolean;
+    mode: 'suggest' | 'append';
+    artifactPatterns: readonly string[];
+    ignorePatterns: readonly string[];
+    maxAppendPerCall: number;
+}
+export declare const DEFAULTS: GitignoreGuardConfig;
+/** Read and validate config; every bad field falls back to its default. */
+export declare function readConfig(raw: unknown): GitignoreGuardConfig;
+declare const plugin: Plugin;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/gitignore-guard.d.ts

@@ -0,0 +1,2 @@
+export * from './gitignore-guard/index.js';
+export { default } from './gitignore-guard/index.js';

package/dist/gitignore-guard.js

@@ -0,0 +1,442 @@
+// src/gitignore-guard/index.ts
+import { access, readFile, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+var API_VERSION = "^0.1.10";
+var DEFAULT_ARTIFACT_PATTERNS = Object.freeze([
+  "dist/",
+  "coverage/",
+  "node_modules/",
+  ".next/",
+  ".nuxt/",
+  ".output/",
+  ".cache/",
+  ".parcel-cache/",
+  ".turbo/",
+  ".vite/",
+  ".swc/",
+  ".pytest_cache/",
+  ".mypy_cache/",
+  "__pycache__/",
+  ".venv/",
+  "venv/",
+  "target/",
+  ".eslintcache",
+  "*.tsbuildinfo",
+  "*.pyc",
+  "*.env",
+  "*.env.*"
+]);
+function toForwardSlashes(p) {
+  return sep === "/" ? p : p.split(sep).join("/");
+}
+function globToSource(glob) {
+  return glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+}
+function globToRegExp(glob) {
+  return new RegExp(`^${globToSource(glob)}$`);
+}
+function matchGitignorePattern(relPath, pattern) {
+  const rel = toForwardSlashes(relPath);
+  const pat = pattern.trim();
+  if (pat.length === 0 || pat.startsWith("#")) return false;
+  const segments = rel.split("/");
+  if (pat.endsWith("/")) {
+    const dir = pat.slice(0, -1);
+    if (dir.length === 0) return false;
+    if (dir.includes("/")) {
+      return new RegExp(`^${globToSource(dir)}(?:/|$)`).test(rel);
+    }
+    return segments.some((s) => s === dir);
+  }
+  if (pat.includes("/")) {
+    return globToRegExp(toForwardSlashes(pat)).test(rel);
+  }
+  const base = segments[segments.length - 1] ?? "";
+  return globToRegExp(pat).test(base);
+}
+function classifyArtifact(relPath, patterns) {
+  for (const p of patterns) {
+    if (matchGitignorePattern(relPath, p)) return p;
+  }
+  return null;
+}
+async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readGitignoreLines(file) {
+  if (!await pathExists(file)) return [];
+  try {
+    const content = await readFile(file, "utf8");
+    return content.split(/\r?\n/);
+  } catch {
+    return [];
+  }
+}
+function isCoveredByLines(lines, relPath) {
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    if (matchGitignorePattern(relPath, line)) return true;
+  }
+  return false;
+}
+function gitignoreCandidates(relDir, root) {
+  const parts = relDir === "" ? [] : toForwardSlashes(relDir).split("/");
+  const out = [join(root, ".gitignore")];
+  let cur = root;
+  for (const part of parts) {
+    cur = join(cur, part);
+    out.push(join(cur, ".gitignore"));
+  }
+  return out;
+}
+function relDirOf(rel) {
+  const idx = rel.lastIndexOf("/");
+  return idx < 0 ? "" : rel.slice(0, idx);
+}
+async function firstExistingGitignore(candidates) {
+  for (const c of candidates) {
+    if (await pathExists(c)) return c;
+  }
+  return null;
+}
+async function appendPatterns(target, patterns, limit) {
+  const existing = await readGitignoreLines(target);
+  const seen = new Set(
+    existing.map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"))
+  );
+  const missing = patterns.filter((p) => !seen.has(p)).slice(0, limit);
+  if (missing.length === 0) return { appended: [] };
+  const current = await pathExists(target) ? await readFile(target, "utf8") : "";
+  const base = current.length === 0 ? "" : current.endsWith("\n") ? current : `${current}
+`;
+  const next = `${base}${missing.map((p) => `${p}
+`).join("")}`;
+  await writeFile(target, next, "utf8");
+  return { appended: missing };
+}
+function projectRelativePath(rawPath, cwd) {
+  const root = cwd ?? process.cwd();
+  const abs = isAbsolute(rawPath) ? rawPath : resolve(root, rawPath);
+  const rel = toForwardSlashes(relative(root, abs));
+  if (rel.startsWith("..") || isAbsolute(rel) || rel === "") return null;
+  return { abs, rel, root };
+}
+var DEFAULTS = {
+  enabled: true,
+  mode: "suggest",
+  artifactPatterns: DEFAULT_ARTIFACT_PATTERNS,
+  ignorePatterns: [],
+  maxAppendPerCall: 5
+};
+function normalizePatterns(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const v of value) {
+    if (typeof v !== "string") continue;
+    const t = v.trim();
+    if (t.length === 0 || t.startsWith("#")) continue;
+    out.push(t);
+  }
+  return out;
+}
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") {
+    return { ...DEFAULTS, artifactPatterns: [...DEFAULTS.artifactPatterns] };
+  }
+  const r = raw;
+  const artifact = normalizePatterns(r["artifactPatterns"]);
+  return {
+    enabled: r["enabled"] !== false,
+    mode: r["mode"] === "append" ? "append" : "suggest",
+    artifactPatterns: artifact.length > 0 ? artifact : [...DEFAULTS.artifactPatterns],
+    ignorePatterns: normalizePatterns(r["ignorePatterns"]),
+    maxAppendPerCall: typeof r["maxAppendPerCall"] === "number" && Number.isInteger(r["maxAppendPerCall"]) && r["maxAppendPerCall"] > 0 ? Math.min(r["maxAppendPerCall"], 50) : DEFAULTS.maxAppendPerCall
+  };
+}
+var state = {
+  invocationCount: 0,
+  /** Artifacts detected after ignore/coverage checks passed. */
+  matchedCount: 0,
+  /** Suggest-mode notices injected into the tool result. */
+  suggestCount: 0,
+  /** Lines appended to a .gitignore (hook or append tool). */
+  appendCount: 0,
+  /** Paths skipped because an existing .gitignore line already covers them. */
+  coveredSkipCount: 0,
+  errorCount: 0,
+  /** Hook handle for teardown. */
+  hookUnregister: null,
+  /** Last detection — surfaced by health() + status tool. */
+  lastResult: null
+};
+function clearRegistrations() {
+  if (state.hookUnregister) {
+    try {
+      state.hookUnregister();
+    } catch {
+    }
+    state.hookUnregister = null;
+  }
+}
+var plugin = {
+  name: "gitignore-guard",
+  version: "0.1.0",
+  description: "PostToolUse hook that suggests or appends .gitignore entries for build-artifact-looking files after every write or edit",
+  apiVersion: API_VERSION,
+  capabilities: { hooks: true, tools: true },
+  configFields: {
+    enabled: { lifecycle: "hot" },
+    mode: { lifecycle: "hot" },
+    artifactPatterns: { lifecycle: "hot" },
+    ignorePatterns: { lifecycle: "hot" },
+    maxAppendPerCall: { lifecycle: "hot" }
+  },
+  defaultConfig: {
+    enabled: DEFAULTS.enabled,
+    mode: DEFAULTS.mode,
+    artifactPatterns: [...DEFAULTS.artifactPatterns],
+    ignorePatterns: [],
+    maxAppendPerCall: DEFAULTS.maxAppendPerCall
+  },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: {
+        type: "boolean",
+        default: true,
+        description: "Master switch. When false, the hook is a no-op."
+      },
+      mode: {
+        type: "string",
+        enum: ["suggest", "append"],
+        default: "suggest",
+        description: '"suggest" injects a notice into the tool result; "append" writes the missing pattern to a .gitignore automatically.'
+      },
+      artifactPatterns: {
+        type: "array",
+        items: { type: "string" },
+        default: [...DEFAULTS.artifactPatterns],
+        description: "Gitignore-style patterns that flag a written file as a build artifact. Empty array falls back to the curated defaults."
+      },
+      ignorePatterns: {
+        type: "array",
+        items: { type: "string" },
+        default: [],
+        description: "Gitignore-style patterns that never flag a file, even when artifactPatterns matches. Use for intentionally-committed generated files."
+      },
+      maxAppendPerCall: {
+        type: "integer",
+        minimum: 1,
+        maximum: 50,
+        default: 5,
+        description: "Maximum number of lines appended per hook invocation."
+      }
+    }
+  },
+  async setup(api) {
+    clearRegistrations();
+    state.invocationCount = 0;
+    state.matchedCount = 0;
+    state.suggestCount = 0;
+    state.appendCount = 0;
+    state.coveredSkipCount = 0;
+    state.errorCount = 0;
+    state.lastResult = null;
+    const hook = async (input) => {
+      const cfg = readConfig(api.config.extensions?.["gitignore-guard"]);
+      if (!cfg.enabled) return;
+      if (input.toolResult?.isError) return;
+      const toolName = input.toolName ?? "";
+      const inp = input.toolInput ?? {};
+      const rawPath = inp["path"];
+      if (typeof rawPath !== "string" || rawPath.trim().length === 0) return;
+      if (basename(rawPath) === ".gitignore") return;
+      const resolved = projectRelativePath(rawPath, input.cwd);
+      if (!resolved) return;
+      state.invocationCount += 1;
+      const matched = classifyArtifact(resolved.rel, cfg.artifactPatterns);
+      if (!matched) return;
+      if (classifyArtifact(resolved.rel, cfg.ignorePatterns)) return;
+      state.matchedCount += 1;
+      const candidates = gitignoreCandidates(relDirOf(resolved.rel), resolved.root);
+      for (const candidate of candidates) {
+        const lines = await readGitignoreLines(candidate);
+        if (isCoveredByLines(lines, resolved.rel)) {
+          state.coveredSkipCount += 1;
+          return;
+        }
+      }
+      state.lastResult = {
+        path: resolved.rel,
+        tool: toolName,
+        pattern: matched,
+        mode: cfg.mode,
+        when: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      if (cfg.mode === "append") {
+        const nearest = await firstExistingGitignore(candidates);
+        const target = nearest ?? join(resolved.root, ".gitignore");
+        const { appended } = await appendPatterns(target, [matched], cfg.maxAppendPerCall);
+        if (appended.length === 0) {
+          state.coveredSkipCount += 1;
+          return;
+        }
+        state.appendCount += 1;
+        api.metrics.counter("append");
+        api.log.info(`gitignore-guard: appended '${matched}' to ${target}`, {
+          path: resolved.rel,
+          tool: toolName
+        });
+        return {
+          additionalContext: `
+\u{1F4E6} gitignore-guard: '${resolved.rel}' looks like a build artifact (pattern '${matched}'). Appended '${matched}' to ${target}.`
+        };
+      }
+      state.suggestCount += 1;
+      api.metrics.counter("suggest");
+      api.log.info(`gitignore-guard: suggested '${matched}' for ${resolved.rel}`, {
+        path: resolved.rel,
+        tool: toolName
+      });
+      return {
+        additionalContext: `
+\u{1F4E6} gitignore-guard: '${resolved.rel}' looks like a build artifact (pattern '${matched}'). Add '${matched}' to .gitignore \u2014 call the gitignore_guard_append tool with path: "${resolved.rel}" to append it now, or set config mode to "append" to do this automatically.`
+      };
+    };
+    state.hookUnregister = api.registerHook("PostToolUse", "write|edit", hook, {
+      name: "gitignore-guard"
+    });
+    api.tools.register({
+      name: "gitignore_guard_status",
+      description: "Reports gitignore-guard state: mode, active pattern lists, and per-session suggest/append/skip counters.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Code Quality",
+      mutating: false,
+      async execute() {
+        const cfg = readConfig(api.config.extensions?.["gitignore-guard"]);
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          mode: cfg.mode,
+          artifactPatterns: cfg.artifactPatterns,
+          ignorePatterns: cfg.ignorePatterns,
+          maxAppendPerCall: cfg.maxAppendPerCall,
+          counters: {
+            invocations: state.invocationCount,
+            matched: state.matchedCount,
+            suggests: state.suggestCount,
+            appends: state.appendCount,
+            coveredSkips: state.coveredSkipCount,
+            errors: state.errorCount
+          },
+          lastResult: state.lastResult
+        };
+      }
+    });
+    api.tools.register({
+      name: "gitignore_guard_append",
+      description: "Appends a .gitignore entry for a build-artifact-looking path (or an explicit pattern). Use after gitignore-guard suggests an entry, or to ignore a generated file proactively.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            description: "Path of the artifact file or directory, relative to the project root or absolute."
+          },
+          pattern: {
+            type: "string",
+            description: "Optional explicit gitignore pattern to append. When omitted, the pattern is derived from the path via artifactPatterns."
+          }
+        },
+        required: ["path"]
+      },
+      permission: "auto",
+      category: "Code Quality",
+      mutating: true,
+      async execute(input) {
+        const rawPath = typeof input?.path === "string" ? input.path : "";
+        if (rawPath.length === 0) return { ok: false, reason: "path is required" };
+        const resolved = projectRelativePath(rawPath, process.cwd());
+        if (!resolved) {
+          return { ok: false, reason: `path outside project root: ${rawPath}` };
+        }
+        const cfg = readConfig(api.config.extensions?.["gitignore-guard"]);
+        const explicit = typeof input?.pattern === "string" && input.pattern.trim().length > 0 ? input.pattern.trim() : null;
+        const pattern = explicit ?? classifyArtifact(resolved.rel, cfg.artifactPatterns);
+        if (!pattern) {
+          return {
+            ok: false,
+            reason: `'${resolved.rel}' does not match any configured artifact pattern; pass an explicit pattern`
+          };
+        }
+        const candidates = gitignoreCandidates(relDirOf(resolved.rel), resolved.root);
+        const nearest = await firstExistingGitignore(candidates);
+        const target = nearest ?? join(resolved.root, ".gitignore");
+        const { appended } = await appendPatterns(target, [pattern], cfg.maxAppendPerCall);
+        if (appended.length === 0) {
+          state.coveredSkipCount += 1;
+          return { ok: true, alreadyCovered: true, gitignore: target, appended: [] };
+        }
+        state.appendCount += 1;
+        api.log.info(`gitignore-guard: manual append '${pattern}' to ${target}`, {
+          path: resolved.rel
+        });
+        return { ok: true, alreadyCovered: false, gitignore: target, appended };
+      }
+    });
+    api.log.info("gitignore-guard plugin loaded", {
+      version: "0.1.0",
+      mode: readConfig(api.config.extensions?.["gitignore-guard"]).mode
+    });
+  },
+  teardown(api) {
+    clearRegistrations();
+    const final = {
+      invocations: state.invocationCount,
+      matched: state.matchedCount,
+      suggests: state.suggestCount,
+      appends: state.appendCount,
+      coveredSkips: state.coveredSkipCount,
+      errors: state.errorCount
+    };
+    state.invocationCount = 0;
+    state.matchedCount = 0;
+    state.suggestCount = 0;
+    state.appendCount = 0;
+    state.coveredSkipCount = 0;
+    state.errorCount = 0;
+    state.lastResult = null;
+    api.log.info("gitignore-guard: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: state.lastResult === null ? `gitignore-guard: ${state.invocationCount} invocation(s), ${state.suggestCount} suggested, ${state.appendCount} appended, ${state.coveredSkipCount} already-covered` : `gitignore-guard: last '${state.lastResult.pattern}' for ${state.lastResult.path} (${state.lastResult.tool}, ${state.lastResult.mode} mode) at ${state.lastResult.when}`,
+      counters: {
+        invocations: state.invocationCount,
+        matched: state.matchedCount,
+        suggests: state.suggestCount,
+        appends: state.appendCount,
+        coveredSkips: state.coveredSkipCount,
+        errors: state.errorCount
+      },
+      lastResult: state.lastResult
+    };
+  }
+};
+var gitignore_guard_default = plugin;
+export {
+  DEFAULTS,
+  DEFAULT_ARTIFACT_PATTERNS,
+  classifyArtifact,
+  gitignore_guard_default as default,
+  matchGitignorePattern,
+  readConfig
+};