io.github.CloudCorpRecords/guardfile

guardfile

A repo can claim all sorts of contribution guardrails — sign your commits, agree to the licence terms, add a changeset — but the claim only means something if you can point at the files that put each one in force. guardfile does that pointing: you hand it a repo's files, and it hands back one checkable report of which guardrails are actually present, with the evidence for each.

Four guardrails are detected, by fixed rules:

• DCO — a file whose basename is exactly DCO (any case), or any content naming the Developer Certificate of Origin.
• CLA — a file whose basename starts with CLA (any case, as in CLA.md), or any content naming the Contributor License Agreement.
• changesets — a path containing .changeset/, a path ending in /.changeset, a path that is exactly .changeset, or any content naming the @changesets/ scope.
• sign-off — any content carrying a Signed-off-by: line. The colon is part of the rule: a bare Signed-off-by mention does not count.

All content matching is case-insensitive. For each guardrail the report lists the paths that triggered it, sorted, with each path appearing at most once even when a single file triggers the same guardrail by both its path and its content. Alongside the four verdicts the report gives the number present, the names of the ones missing (in the fixed order dco, cla, changeset, signoff), and a complete flag that is true only when all four are present.

Malformed input — a missing or empty file list, an entry that is not an object, a missing, empty, or duplicated path, or content that is missing or not a string — is a validation error naming the offending path (for example files[1].content must be a string), and no partial report is produced. The computation is pure and local: no network, no configuration, and no files read beyond the input you pass in.

CLI

npx @reneturcios/guardfile extract --input args.json
npx @reneturcios/guardfile --version

args.json contains the full arguments object:

{
  "files": [
    { "path": "DCO", "content": "Developer Certificate of Origin\n\nVersion 1.1" },
    { "path": "docs/contributing.md", "content": "Please add a Signed-off-by: line." },
    { "path": ".changeset/bright-foxes-jump.md", "content": "---\n\"pkg\": patch\n---\n" }
  ]
}

The report is printed as JSON:

{
  "guardrails": {
    "dco": { "present": true, "evidence": ["DCO"] },
    "cla": { "present": false, "evidence": [] },
    "changeset": { "present": true, "evidence": [".changeset/bright-foxes-jump.md"] },
    "signoff": { "present": true, "evidence": ["docs/contributing.md"] }
  },
  "present_count": 3,
  "missing": ["cla"],
  "complete": false
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/guardfile mcp

MCP client config:

{
  "mcpServers": {
    "guardfile": {
      "command": "npx",
      "args": ["-y", "@reneturcios/guardfile", "mcp"]
    }
  }
}

Tools

• extract_guardrails — Extract a repo's guardrails from its files.

  • files (array, required, at least one) — repo files as {path, content} objects; path is a repo-relative path unique across the set and content is the file's content, which may be empty

  Returns {guardrails, present_count, missing, complete}.

Docker

docker run -i ghcr.io/cloudcorprecords/guardfile
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/guardfile extract --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios