Hanfani Guard

A deterministic AI governance layer for your Git workflow.

Hanfani Guard is an open-source CLI that enforces your coding, Git, and project policies automatically — so you stop repeating the same operational instructions to every AI coding assistant.

Instead of telling Cursor, Claude Code, Codex, Copilot, Gemini CLI, or Windsurf the same things over and over:

• "Don't add Co-authored-by."
• "Use Conventional Commits."
• "Don't add a commit body."
• "Keep comments minimal."
• "Add tests."
• "Don't break existing features."

…you configure these rules once and let Hanfani Guard enforce them on every commit and push. It is not another AI coding agent — it is the deterministic guardrail that sits between AI-generated code and your repository.

Why

AI assistants generate code brilliantly, but they still need the same operational reminders in every project and every session. Hanfani Guard removes that friction by acting as a policy engine that runs locally, produces predictable results, and works regardless of which assistant wrote the code.

• Deterministic first — every rule produces predictable, repeatable results.
• AI-agnostic — works with any assistant (or none at all).
• Language-agnostic — operates on Git and config, not on a specific language.
• Local-first — no cloud service required; you own your configuration.
• Extensible — every policy can be independently enabled, disabled, or tuned.

Install

# one-off
npx @hanfani/guard init

# or globally
npm install -g @hanfani/guard
hanfani init

Requires Node.js >= 20.

Quick start

# 1. Create hanfani.config.ts and install Git hooks
hanfani init

# 2. Validate your working tree at any time
hanfani check

# 3. Commit with automatic policy enforcement + message sanitizing
git add .
hanfani commit -m "feat(api): add rate limiting"

# 4. Audit the whole repository
hanfani review

# 5. Verify your installation and hooks
hanfani doctor

Once hooks are installed, every commit is governed automatically — even git commit made by your AI assistant. Disallowed commit bodies, Co-authored-by trailers, and AI tool signatures are stripped deterministically; debug statements, secrets, and policy violations block the commit.

Commands

| Command | Description | | ------------------- | --------------------------------------------------------------------- | | hanfani init | Create hanfani.config.ts and install Git hooks. | | hanfani check | Run every configured policy against your changes. | | hanfani commit | Sanitize the message, validate all policies, then commit. | | hanfani review | Full repository audit with recommendations. | | hanfani doctor | Verify installation, hooks, and configuration integrity. | | hanfani policies | List all built-in policies. | | hanfani uninstall | Remove Hanfani-managed Git hooks (leaves your config untouched). |

Useful flags: --json (machine-readable output), --quiet (only show failures), -C, --cwd <dir> (run in another directory), --dry-run (for commit).

Configuration

hanfani init creates a typed hanfani.config.ts:

import { defineConfig } from "@hanfani/guard/config";

export default defineConfig({
  commits: {
    conventional: true, // enforce Conventional Commits
    body: false,        // strip / block commit bodies
    coAuthors: false,   // strip / block Co-authored-by trailers
  },

  comments: {
    style: "minimal",   // "off" | "minimal" | "strict"
  },

  testing: {
    required: false,        // require tests alongside source changes
    changedFilesOnly: true,
  },

  github: {
    requireCI: false, // require a GitHub Actions workflow
  },

  code: {
    todos: "warn",            // "off" | "warn" | "error"
    debugStatements: "error", // console.log, debugger, print(), …
    duplication: "warn",      // copy-pasted blocks; "off" | "warn" | "error"
    duplicationMinLines: 6,   // minimum significant lines per duplicated block
    syntax: "error",          // unparseable JS/TS/JSX; "off" | "warn" | "error"
  },

  security: {
    secrets: "error", // scan changed files for hardcoded credentials
    patterns: [],     // custom regex patterns for secrets
  },

  regression: {
    enabled: false, // warn on risky changes (e.g. deleted source)
  },

  hooks: {
    preCommit: true,
    commitMsg: true,
    prePush: false,
  },
});

Every rule is configurable. Config files can also be .js, .mjs, .cjs, or .json. Unknown, namespaced keys are preserved so future policy plugins can read their own options.

To disable a specific policy without changing its category settings:

export default defineConfig({
  disable: ["code/todos"],
});

Suppressing a single line

Add hanfani-allow in a comment on any line to acknowledge an intentional match (e.g. a real console.log you want to keep):

console.log("intentional"); // hanfani-allow

Built-in policies

| ID | Stage(s) | What it enforces | | ------------------------ | -------------------------------- | -------------------------------------------------- | | commits/conventional | commit-msg | Conventional Commit subject format. | | commits/no-body | commit-msg | Blocks commit bodies when disabled. | | commits/no-co-authors | commit-msg | Blocks Co-authored-by: and AI signatures. | | code/todos | pre-commit, check, review | TODO / FIXME / XXX / HACK / BUG markers. | | code/debug-statements | pre-commit, check, review | Leftover debug statements (multi-language). | | code/duplication | pre-commit, check, review | Copy-pasted code blocks within/across files. | | code/syntax | pre-commit, check, review, push | Unparseable JS/TS/JSX (parse errors). | | comments/style | pre-commit, check, review | Redundant, narrating comments and comment density. | | security/secrets | pre-commit, check, review, push | Hardcoded credentials (AWS, GitHub, OpenAI, etc.). | | testing/required | pre-commit, check, push, review | Tests accompany source changes. | | github/require-ci | check, push, review | A GitHub Actions workflow exists. | | docs/require-readme | check, review | A README exists at the repo root. | | regression/guard | pre-commit, check, push, review | Warns on risky changes (deleted source, API). |

Git integration

hanfani init installs managed hooks (pre-commit, commit-msg, and optionally pre-push). The hooks are marked with a header so Hanfani can update or remove them safely, and they never overwrite an existing non-Hanfani hook unless you pass --force. Each hook resolves hanfani from a global install, a local node_modules/.bin, or npx — in that order.

Bypass in an emergency with git commit --no-verify (not recommended).

1. Expanded Secret Scanning

The security/secrets policy now detects 35+ provider-specific patterns:

• Cloud: AWS, Azure, Google Cloud, Firebase
• Source: GitHub (standard + fine-grained PAT), GitLab, npm, PyPI
• SaaS: OpenAI, Anthropic, Slack, Discord, Telegram, Twilio, Stripe, SendGrid, Shopify, Postman, Datadog
• Credentials in URLs and bearer tokens
• Entropy fallback: catches bespoke/rotated credentials via Shannon entropy analysis

Example:

const apiKey = "gT7xQ2vLpZ9kW4mB8nR1cE6sD3aF5hJ0"; // hanfani-allow — example: flagged as high-entropy secret
const token = process.env.API_KEY; // ← Allowed (env reference)

2. Code Duplication Detection

The code/duplication policy flags copy-pasted blocks within and across files:

• Normalizes source (strips whitespace, comments, imports)
• Hashes sliding windows of 6+ significant lines
• Reports duplicates with origin location
• Precise: ignores boilerplate and trivial lines

Example:

$ hanfani check
✗ Code / component duplication
    → Duplicated block of 6+ lines — matches src/cart.ts:10. (src/checkout.ts:1)

Configure with:

code: {
  duplication: "warn",      // "off" | "warn" | "error"
  duplicationMinLines: 6,   // minimum lines per block
}

3. Syntax / Parse Validation

The code/syntax policy catches parse errors before they land:

• Uses TypeScript compiler API for accurate parsing
• Supports .ts, .tsx, .js, .jsx, .mjs, .cjs
• Ignores non-script files (Python, Go, etc.)
• Prevents "Parsing ecmascript source code failed" at runtime

Example:

$ hanfani check
✗ Syntax / parse validation
    → Parse error: ':' expected. (src/api.ts:15)
      hint: The file does not parse. Fix the syntax before committing.

Programmatic API

Hanfani Guard also ships a typed library so you can embed the engine or author custom policies:

import { Engine, buildContext, loadConfig, builtinPolicies } from "@hanfani/guard";

const { config } = await loadConfig(process.cwd());
const ctx = await buildContext({ stage: "check", cwd: process.cwd(), config });
const run = await new Engine(builtinPolicies).run(ctx);
console.log(run.summary);

Roadmap

The architecture is plugin-oriented to support, over time: AI policy plugins, team/organization policy sharing, security rule packs, CI/CD and IDE integrations, GitHub/GitLab/Bitbucket apps, multi-language analyzers, and AI-assisted regression detection — without changing the deterministic core.

Distribution beyond npm (Homebrew, Winget, apt, Chocolatey, Docker, standalone binaries) is planned; the engine is intentionally platform-agnostic.

Development

npm install
npm run build      # bundle with tsup (ESM + type declarations)
npm run typecheck  # tsc --noEmit
npm test           # vitest

See CONTRIBUTING.md for how to add a policy and open a PR, and CHANGELOG.md for release history.

License

MIT License © Fruitizz