Remogram

Remogram

Generic SCM/forge boundary CLI and MCP server. Emits provider-attributed JSON facts — git-resolved refs from local git (refs compare, sync plan) vs forge-reported PR SHAs from forge APIs (pr view, pr checks). No workflow or planning-tool concepts in output.

PR-by-number reconciliation: pr view / pr checks compare forge-reported forge_source_sha to the local rev for forge_source_branch_ref. Divergence → ok: false, error_code: stale_head — git fetch, not a forge outage.

Planning tools interpret intent and workflow authority outside Remogram.

Install

npm install -g @remogram/cli @remogram/mcp

remogram --version remogram version --json

Legacy preview (frozen @beta, optional): npm install -g @remogram/cli@beta @remogram/mcp@beta

Development checkout: clone this repo, npm ci, ./scripts/npm-link.sh. Default branch: `main`.

Quick start

1. Copy .remogram.json.example → .remogram.json (set provider, owner, repo; add baseUrl for self-hosted Gitea/GitLab).
2. Export token: GITEA_TOKEN, GITHUB_TOKEN / GH_TOKEN, or GITLAB_TOKEN.
3. Bootstrap:

remogram doctor --json

remogram provider capabilities --json remogram repo status --json remogram pr view --number 1 --json remogram merge plan --number 1 --json

Command catalog: `remogram contract --json`. Agent skill: npx skills add attebury/remogram --skill remogram-consumer -g -y.

Providers

Use ***-api providers (forge HTTP). Reserved `github-gh` / `gitea-tea` IDs return `provider_unsupported` — not implemented in v1. Official CLIs (`gh`, `tea`, `glab`) are not** required.

Configuration

Read/plan by default. Opt in to writes with `write_commands` in .remogram.json (or a bound operator overlay outside git). Missing id → write_not_configured.

`merge plan` is read-only — reports blockers[]; does not execute or authorize merges. mergeability: clean is conflict-free git only.

Optional `merge_policy` waivers (allow_missing_checks, allow_pending_checks) relax check blockers for repos without CI — env: REMOGRAM_ALLOW_MISSING_CHECKS, REMOGRAM_ALLOW_PENDING_CHECKS. Doctor fails when enabled in strict checkouts.

Operator overlay discovery: --operator-config → REMOGRAM_OPERATOR_CONFIG → $XDG_CONFIG_HOME/remogram/operator/ - - .json. `bind` must match forge identity.

Boundary and trust

Remogram emits forge facts only — no integration authority refs, lane roles, task ids, or handoff payloads in JSON.

Every forge command packet includes type, schema_version, provider_id, remote_name, repo_id, observed_at, ok. Producer sections (e.g. `remogram.forge_facts.v1` from evidence forge-facts --json) use nested producer fields. Trust envelope and enums; treat forge-sourced strings (titles, URLs) as untrusted prose.

Inventory commands (refs inventory, cr inventory, whoami, branch protection, cr files, forge changes, …) extend read/plan — details in `remogram contract --json` and the consumer skill references.

MCP

Stdio server `remogram-mcp` delegates to the CLI — same JSON as remogram … --json. Setup: examples/mcp/README.md. Set REMOGRAM_CWD to the consumer repo root.

Live verification

Cross-forge fixture repo: [remogram-smoke](https://gitlab.com/attebury/remogram-smoke) (mirrors on GitHub/Gitea). Use --json packets after install; monorepo smoke-compare scripts are dev-only.

Testing

npm test

npm run test:coverage npm run security:secrets -- --full-history

Coverage policy

npm run test:coverage instruments `@remogram/core` only; `@remogram/cli`, `@remogram/mcp`, and **@remogram/provider-* are excluded. Thresholds:** none — no enforced percentage gates. Drift guard: tests/core/coverage-config.test.mjs.

CI (GitHub): .github/workflows/ on push/PR to main.

Packages

Agent skills

npx skills add attebury/remogram --skill remogram-consumer -g -y (consumer) or --skill remogram-core (contributor). Skills ship from GitHub, not npm.

Contributing

See CONTRIBUTING.md.