boilerforge

Architecture governance wedge for AI-built codebases — doctor-first health checks and guardrails for production teams.

Boilerforge is now doctor-first. Instead of starting from a boilerplate registry, you start by checking architecture quality:

boilerforge doctor .

It scores your project, detects stack metadata, validates governance guardrails, and gives actionable recommendations.

---

Quickstart

npx -y @cometforge/boilerforge@latest doctor .

CI gate:

boilerforge doctor . --ci --min-score 70

Badge snippet:

boilerforge doctor . --badge

Example output:

![Boilerforge Score](https://img.shields.io/badge/boilerforge-78%2F100-yellow)

---

Commands

boilerforge doctor [path]

Architecture health report with weighted score (/100).

Flags:

• --json output machine-readable JSON
• --ci fail with non-zero exit if below threshold
• --min-score <number> threshold for --ci (default 70)
• --badge print markdown badge snippet + score

boilerforge analyze [path]

Detect stack metadata:

• language/runtime
• framework
• package manager
• baseline project metadata

boilerforge validate [path]

Evaluate architecture guardrails and return:

• pass/fail
• score
• categorized issues (critical, warning, info)
• recommendations

boilerforge extract [path] [--name <template-name>]

Extract current project into local template registry:

• writes .boilerforge-template.yaml in source project
• creates template under ~/.boilerforge/registry/<template-name>/
• copies sane files only (excludes .git, node_modules, dist, build artifacts, env secrets)

boilerforge create <template-name> [target-path]

Scaffold a project from local registry template and write lockfile (boilerforge.lock.json).

boilerforge upgrade [path]

Upgrade project based on lockfile + local template version:

• compares locked template version vs latest local registry
• applies migration hooks in order when present (writeFile, appendFile, deleteFile, copyFromTemplate, patchJSON)
• writes updated lockfile

---

Doctor Rule Engine (100 points)

1. CI workflow exists — 12
2. Env schema validation present — 10
3. Typecheck script exists — 10
4. Test script + test files exist — 12
5. Lint configured — 10
6. Security headers configured (web stacks) — 10
7. Centralized logging present — 8
8. Observability hook present (Sentry/OpenTelemetry/etc) — 8
9. Dependency hygiene — 10
10. Docs baseline (README + setup) — 10

Outputs include:

• score /100
• detected stack summary
• categorized issues
• actionable recommendations

---

Local Registry Model

Registry root:

~/.boilerforge/registry

Template layout:

<template>/
  template.yaml
  files/
  migrations/   (optional)

template.yaml accepts YAML (not just JSON), and is strictly validated for required fields (name, version, createdAt) with clear parse/validation errors.

Lockfile (boilerforge.lock.json) stores template name/version/source for deterministic upgrades.

---

Lifecycle Compatibility

Existing lifecycle workflows remain supported:

boilerforge init <project-name> [--workflow=claude]
boilerforge update [--dry-run]
boilerforge protect add <category> <name>
boilerforge protect remove <category> <name>
boilerforge status

---

MCP Server Tools (unchanged)

• list_boilerplates
• get_boilerplate
• search_boilerplates
• scaffold_project
• check_project_updates

Running the package without CLI args in non-interactive MCP context still starts the MCP server.

---

CI/CD

GitHub Actions workflows included:

• ci.yml: install, lint, typecheck, test, build, doctor --ci --min-score 70, CLI smoke checks, and npm package integrity (npm pack) verification.
• publish.yml: release-driven publish pipeline (lint + typecheck + test + build + doctor gate + npm publish with provenance).

Minimal CI snippet for your own repos:

- name: Architecture gate
  run: boilerforge doctor . --ci --min-score 70

doctor --ci exits non-zero when below threshold, so it can be used as a hard merge/release gate.

---

Development

git clone https://github.com/MRKT365-India/boilerforge.git
cd boilerforge
npm install
npm run build
npm test