Architecture

ContribSutra is a small, dependency-free Node.js program organized around one idea: read-only evidence in, sealed reports out, a human decides.

System context

 contributor / maintainer
        |  chooses a local repo + (optionally) an exported issue snapshot
        v
 +-------------------------- contribsutra CLI --------------------------+
 |  bounded readers -> heuristics -> sealed JSON -> Markdown / HTML     |
 +----------------------------------------------------------------------+
        |  writes only files you name, outside the inspected repo
        v
 reports/  (json + md + html)       skills copied into .claude/skills etc.

Outside the trust boundary: GitHub, any IDE agent, the inspected repository's text, issue text.

Modules

ModuleResponsibility
scan.mjsInventory, license heuristic, policy signals, manifests, CI list, injection flags
doctor.mjsFixed version probes, range matcher, requirement comparison
issues.mjsSnapshot loading, decline rules, scoring, warnings
plan.mjsLearning plan, lifecycle, PR packet
verify.mjsSeal and source freshness checks
audit.mjs30 assurance checks, evidence tiers, verdict
install.mjsProject-local skill copying
reporting/index.mjsOne block model, two renderers (Markdown, HTML)
server/index.mjsLocalhost sealed-report endpoint
cli/index.mjsArgument parsing, exit codes, safe output writing

Bounded contexts

Repository Knowledge (scan), Contribution Policy (policy signals), Toolchain and Environment (doctor), Opportunity Discovery (issues), Learning Path (plan), Evidence and Tests (PR packet, verify), Maintainer Consent (decline rules, warnings), Integrations (future), Governance (rules, policies), Reporting (renderers).

Human-controlled lifecycle

discovered → understood → shortlisted → approved_scope → planning → implementation_authorized → observed_tests → review_ready → submitted_by_human

The tool can place an issue at shortlisted or planning. Every other transition requires a person, so there is no automatic path from a recommendation to an account write.

Data model

All reports share: schemaVersion ("1.0"), kind (contribsutra.*), semantic fields, seal {method, hash}. The seal is the SHA-256 of the JSON serialization of all preceding fields. Schemas live in schemas/.

Key design decisions

DecisionReason
Zero dependenciesNothing to audit or compromise in the supply chain; installs in seconds
Offline onlyNo consent problem, no rate limits, no tokens to leak
Heuristics are labelledA regex match is pattern_match_inferred, never "verified"
Reports are data firstOne block model feeds Markdown and HTML so they cannot disagree
Skills are textA SKILL.md cannot enforce anything; enforcement lives in the CLI
argv[1] is resolved with realpathnpm bin shims are symlinks; a naive entry check made the CLI silently do nothing under npx
npm probe on Windows via cmd.exe with constant argumentsNode refuses to spawn .cmd files directly; no user input reaches the command line

Deployment modes

Solo offline CLI (supported). Assisted IDE mode with copied skills (copy supported; activation not verified). Local-only report server (supported, not a public service). Authenticated multi-tenant hosting (future; requires OIDC, RBAC, TLS, audit logs and a new threat model).