# 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

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

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

| Forge | `"provider"` | Token env |
|-------|--------------|-----------|
| Gitea | `gitea-api` | `GITEA_TOKEN` |
| GitHub | `github-api` | `GITHUB_TOKEN` or `GH_TOKEN` |
| GitLab | `gitlab-api` | `GITLAB_TOKEN` |

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](.remogram.operator.json.example) outside git). Missing id → `write_not_configured`.

| Write id | Command | Notes |
|----------|---------|-------|
| `cr_open` | `cr open` | Separate from merge |
| `cr_close` | `cr close` | Gitea lifecycle |
| `merge` | `merge execute` | Requires `--expected-base-sha` / `--expected-head-sha`; not implied by `cr_open` |
| `publish_branch` | `publish execute` | Git push to configured remote |
| `status_set` | `status set` | Commit status POST |
| issue / `cr_edit` ids | matching commands | See `contract --json` |

**`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/<provider>-<owner>-<repo>.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.

| Concept | Packet field | Notes |
|---------|--------------|-------|
| PR base | `forge_target_branch_ref` | Forge-reported |
| PR head | `forge_source_branch_ref` | Evidence only |
| Default branch | `default_branch` | Not integration authority |

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](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

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

| Package | Role |
|---------|------|
| `@remogram/cli` | CLI |
| `@remogram/mcp` | MCP adapter |
| `@remogram/core` | Envelope, config, caps |
| `@remogram/provider-{gitea,github,gitlab}-api` | Supported forge backends |

## 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](CONTRIBUTING.md).