# 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

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

`args.json` contains the full arguments object:

```json
{
  "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:

```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

```bash
npx -y @reneturcios/guardfile mcp
```

MCP client config:

```json
{
  "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

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

## Development

```bash
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