Technical reference

Requirements and install

Node.js 20 or newer. No other dependency.

npx contribsutra-ai --version
npm install --save-dev contribsutra-ai      # optional local install

Binaries: contribsutra and contribsutra-ai (identical).

Commands

CommandRequired optionsOptionalOutput
doctornone--root DIRcontribsutra.environment-doctor
scan--root DIR--out FILEcontribsutra.repository-scan
issues--issues FILE--skills a,b --as-of ISO --out FILEcontribsutra.issue-shortlist
plan--root --issues --issue N--mode --skills --as-of --outcontribsutra.learning-plan
pr-check--root DIR--issue N --evidence FILE --out FILEcontribsutra.pr-readiness
verify--report FILE--root DIRJSON verdict on stdout
render--report --out`--format mdhtml`one file
audit--out DIR--root DIR --issues FILEHTML + MD + JSON + artifacts + checksums
install-skills--ide --project DIRJSON summary
serve--report FILE--port Nlocal HTTP endpoint
demononeregenerates examples/reports/

Global flags: --json, --quiet, --force, -h/--help, -v/--version.

--out takes a stem. --out reports/scan.json writes scan.json, scan.md and scan.html. Output must be outside the inspected repository. Existing files are not overwritten without --force.

Exit codes

CodeMeaning
0Success
1verify failed, or audit verdict is ASSURANCE_FAILED
2Usage, input or runtime error

Input formats

Issue snapshot: a JSON array (maximum 250 items, 512 KiB). Fields used: number, title, state, labels (strings or {name}), assignee, assignees, locked, pull_request, body, updated_at (or updatedAt).

Evidence file for pr-check:

{"aiAssistance":"assisted","changedFiles":["README.md"],"tests":[{"name":"npm test","status":"passed","evidenceFile":"run.log"}]}

aiAssistance is none, assisted or generated. Any other value counts as undeclared.

Scoring (issues)

SignalEffect
good first issue label+50
help wanted label+20
documentation or docs label+8
Declared skill equals a label+12
Declared skill appears in title+6
Large-scope label or title−25 (floor 0)
Stale beyond 180 days (needs --as-of)−10
Any decline rulescore 0, eligible: false

Decline rules: not open, pull request, assigned, locked, restricted label (security, private, blocked, wontfix, invalid, needs-triage, duplicate), security-like title, instruction-like text. Ties are broken by issue number, so output is deterministic.

Limits

LimitValue
Document size256 KiB each
Issue snapshot512 KiB, 250 items
Report read8 MiB
Documented commands40
Policy excerpt140 characters
Probe timeout8 s each

Programmatic use

The packages are ES modules: scanRepository, environmentDoctor, rankIssues, createLearningPlan, checkPullRequest, verifyReport, runAudit, renderMarkdown, renderHtml. Import from contribsutra-ai/packages/.... The public contract is the JSON in schemas/; internal function signatures may change between minor versions.

Local server

CONTRIBSUTRA_SERVER_TOKEN=<at least 16 characters> contribsutra serve --report reports/scan.json
curl -H "Authorization: Bearer $CONTRIBSUTRA_SERVER_TOKEN" http://127.0.0.1:PORT/report

Routes: GET /health (no auth), GET /report, GET /report.html. Everything else is 404/405. Wrong Host header returns 421.