104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# patch.moi
|
|
|
|
Git-first maintenance control plane for custom patches on top of upstream open
|
|
source software.
|
|
|
|
Canonical public host: `https://patch.moi`.
|
|
|
|
## Repository
|
|
|
|
This is a Bun monorepo:
|
|
|
|
- `apps/patch`: the Patch service, feed poller, JSONL store, Discord output,
|
|
and workspace backend adapter.
|
|
- `docs`: Tome documentation site for patch.moi.
|
|
|
|
patch.moi treats Git as the source of truth for maintained projects. Upstream
|
|
and fork remotes, patch branches, tags, and commits describe the patch stack.
|
|
Patch records update intake, dispatch attempts, and operational history around
|
|
those Git facts.
|
|
|
|
## Endpoints
|
|
|
|
```text
|
|
GET /healthz
|
|
GET /flow-events
|
|
GET /flow-events/:id
|
|
POST /flow-events/:id/retry
|
|
POST /flow-events/:id/replay
|
|
GET /maintenance-attempts
|
|
GET /maintenance-attempts/:id
|
|
POST /maintenance-attempts/:id/sync
|
|
GET /workspace-dispatches
|
|
GET /workspace-events
|
|
GET /workspace-runs
|
|
```
|
|
|
|
## Environment
|
|
|
|
```text
|
|
HOST=0.0.0.0
|
|
PORT=3000
|
|
DATA_DIR=./data
|
|
DISCORD_OUTPUT_ENABLED=false
|
|
DISCORD_WEBHOOK_URL=
|
|
DISCORD_NOTIFY_EVENTS=push,release
|
|
FEED_SOURCES_PATH=./feed-sources.json
|
|
PATCH_WORKSPACE_BACKEND_URL=
|
|
PATCH_WORKSPACE_BACKEND_SECRET=
|
|
PATCH_FLOW_BACKEND_URL=
|
|
PATCH_FLOW_DISPATCH_URL=
|
|
PATCH_FLOW_DISPATCH_SECRET=
|
|
PATCH_ADMIN_TOKEN=
|
|
CODEX_WORKSPACE_MODE=
|
|
```
|
|
|
|
Discord notifications are off by default. Set `DISCORD_OUTPUT_ENABLED=true`
|
|
and `DISCORD_WEBHOOK_URL` to send Discord output. `DISCORD_NOTIFY_EVENTS` is a
|
|
comma-separated allow list and defaults to `push,release`.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
bun install
|
|
bun run check
|
|
bun run workspace:doctor
|
|
bun run dev
|
|
```
|
|
|
|
Feed watcher events are configured in `apps/patch/feed-sources.json`. The first
|
|
poll primes `DATA_DIR/feed-state.json`; later polls append upstream activity to
|
|
`DATA_DIR/feed-events.jsonl`. Targets using `mode: "fork_sync"` append legacy
|
|
work to `DATA_DIR/feed-jobs.jsonl`. Targets using `mode: "workspace_flow"`
|
|
append generic flow events to `DATA_DIR/flow-events.jsonl`, send them to the
|
|
configured workspace backend or local adapter, and record dispatch outcomes in
|
|
`DATA_DIR/workspace-dispatches.jsonl`. Each dispatch also creates or updates a
|
|
patch.moi-owned `DATA_DIR/maintenance-attempts.jsonl` entry that links the
|
|
upstream update to workspace run ids, final flow outcome, and candidate refs.
|
|
|
|
Patch can dispatch through a configured workspace backend, through the
|
|
codex-flows Actions/local surface with `CODEX_WORKSPACE_MODE=actions`, or
|
|
through synchronous local flow execution for development. The backend does not
|
|
need to be running in this checkout unless you are explicitly testing or
|
|
operating that surface.
|
|
|
|
The harness can also be run through the repo-native workspace task:
|
|
|
|
```bash
|
|
CODEX_FLOW_FETCH=0 CODEX_FLOW_PUSH=0 bun run workspace:run:harness
|
|
```
|
|
|
|
That task writes local operator run state under `.codex/workspace/local/`,
|
|
which is ignored by Git. Patch service state remains under `DATA_DIR`.
|
|
|
|
## Documentation
|
|
|
|
The publishable docs site is a Tome project in `docs/`:
|
|
|
|
```bash
|
|
bun run docs:dev
|
|
bun run docs:build
|
|
```
|
|
|
|
Docs source follows the Diataxis framework under `docs/pages/tutorials`,
|
|
`docs/pages/guides`, `docs/pages/reference`, and `docs/pages/concepts`.
|