From a0bafceae9aa8fca827b7a9ca893e739290c74fc Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 6 Jul 2026 09:31:56 +0900 Subject: [PATCH] sync: agent-contract & agent-test updates --- agent-contract/index.md | 6 +- .../provided/gito-forgejo-branch-events-v1.md | 37 ++++++++--- agent-test/dev/rules.md | 63 +++++++++++++++++++ agent-test/local/rules.md | 4 +- 4 files changed, 96 insertions(+), 14 deletions(-) create mode 100644 agent-test/dev/rules.md diff --git a/agent-contract/index.md b/agent-contract/index.md index 0eca7bb..112372d 100644 --- a/agent-contract/index.md +++ b/agent-contract/index.md @@ -6,9 +6,9 @@ ## 제공 계약 -| id | 읽는 조건 | path | -| --- | --- | --- | -| `gito.forgejo-branch-events.v1` | Forgejo webhook, `branch.updated`, outbound HTTP webhook delivery, nomadcode branch event wakeup, `/callbacks/forgejo/push`, `/api/listeners/branches`, `/api/webhook-subscriptions` | `agent-contract/provided/gito-forgejo-branch-events-v1.md` | +| id | 읽는 조건　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 | path | +| ---------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------| +| `gito.forgejo-branch-events.v1` | Forgejo webhook, `branch.updated`, outbound HTTP webhook delivery, NomadCode branch event wakeup, Gito local/dev port profiles `18060/18061`, NomadCode webhook targets `18010/18011`, `/callbacks/forgejo/push`, `/api/listeners/branches`, `/api/webhook-subscriptions` | `agent-contract/provided/gito-forgejo-branch-events-v1.md` | ## 소비 계약 diff --git a/agent-contract/provided/gito-forgejo-branch-events-v1.md b/agent-contract/provided/gito-forgejo-branch-events-v1.md index df7e926..57f9555 100644 --- a/agent-contract/provided/gito-forgejo-branch-events-v1.md +++ b/agent-contract/provided/gito-forgejo-branch-events-v1.md @@ -12,6 +12,17 @@ - proto-socket은 Gito 내부 control/runtime transport이며 이 외부 계약의 일부가 아니다. - gRPC는 이 계약 범위가 아니다. +## Environment Port Profiles + +포트 profile은 원격 host에서 local용 환경과 dev용 환경을 동시에 분리 운영하기 위한 기본값이다. API path, headers, request/response schema는 profile과 무관하게 동일하다. + +| Profile | Gito base URL | NomadCode webhook target | Preview | Optional wire | DB/cache 후보 | +| --- | --- | --- | ---: | ---: | ---: | +| remote local | `http://127.0.0.1:18060` | `http://127.0.0.1:18010/api/integrations/gito/webhook` | `13060` | `19060` | `15460/16360` | +| remote dev | `http://127.0.0.1:18061` | `http://127.0.0.1:18011/api/integrations/gito/webhook` | `13061` | `19061` | `15461/16361` | + +Gito Core process/container 내부 listen 포트는 제품 기본값 `8080`을 유지할 수 있다. workspace 충돌 관리는 host publish 또는 direct smoke 포트(`18060`/`18061`)에서 처리한다. IOP dev model endpoint `http://toki-labs.com:18083/v1`은 NomadCode 실행 의존성이지 Gito-owned port가 아니다. + ## REST Callback ### `POST /callbacks/forgejo/push` @@ -156,7 +167,7 @@ Request: ```json { "name": "nomadcode-develop-wakeup", - "target_url": "https://consumer.example.invalid/gito/events", + "target_url": "http://127.0.0.1:18010/api/integrations/gito/webhook", "events": ["branch.updated"], "repo_id": "nomadcode", "branch": "develop", @@ -179,8 +190,7 @@ Response: } ``` -`target_url` and `secret_ref` are examples only. Raw signing secrets, tokens, or -private endpoint values must not be stored in tracked docs. +`target_url`은 remote local profile 예시다. remote dev profile에서는 `http://127.0.0.1:18011/api/integrations/gito/webhook`을 사용한다. `secret_ref`는 예시 참조값이며 raw signing secrets, tokens, or private endpoint values must not be stored in tracked docs. ## Event Inspection @@ -332,6 +342,8 @@ NomadCode 또는 다른 consumer가 Gito branch event webhook delivery를 연동 listener bootstrap, webhook subscription, `/api/listeners/branches`, `/api/events`를 secret 없이 재현 가능하게 확인하는 절차다. +예시는 remote local profile 기준이다. remote dev profile에서는 `GITO_BASE_URL=http://127.0.0.1:18061`, `GITO_NOMADCODE_TARGET_URL=http://127.0.0.1:18011/api/integrations/gito/webhook`으로 바꾼다. + ### 필요한 환경 변수 | 변수 | 필수 | 기본값 | 설명 | @@ -339,13 +351,20 @@ listener bootstrap, webhook subscription, `/api/listeners/branches`, `/api/event | `APP_ENV` | 아니오 | `development` | 앱 환경 | | `FORGEJO_WEBHOOK_SECRET` | 아니오 | (없으면 서명 검증 생략) | Forgejo webhook 서명 키 | | `DATABASE_URL` | 아니오 | (없으면 in-memory) | PostgreSQL DSN | +| `GITO_BASE_URL` | 아니오 | `http://127.0.0.1:18060` | Gito profile별 base URL | +| `GITO_NOMADCODE_TARGET_URL` | 아니오 | `http://127.0.0.1:18010/api/integrations/gito/webhook` | NomadCode consumer endpoint | 기본 smoke는 `FORGEJO_WEBHOOK_SECRET`과 `DATABASE_URL` 없이 실행할 수 있다. +```bash +GITO_BASE_URL="${GITO_BASE_URL:-http://127.0.0.1:18060}" +GITO_NOMADCODE_TARGET_URL="${GITO_NOMADCODE_TARGET_URL:-http://127.0.0.1:18010/api/integrations/gito/webhook}" +``` + ### Step 1 — Branch watch 등록 ```bash -curl -s -X POST http://localhost:8080/api/listeners/branches \ +curl -s -X POST "$GITO_BASE_URL/api/listeners/branches" \ -H "Content-Type: application/json" \ -d '{"repo_id":"nomadcode","branch":"develop","provider":"forgejo"}' ``` @@ -355,15 +374,15 @@ curl -s -X POST http://localhost:8080/api/listeners/branches \ ### Step 2 — 등록된 watch 목록 확인 ```bash -curl -s http://localhost:8080/api/listeners/branches +curl -s "$GITO_BASE_URL/api/listeners/branches" ``` ### Step 3 — webhook subscription 등록 ```bash -curl -s -X POST http://localhost:8080/api/webhook-subscriptions \ +curl -s -X POST "$GITO_BASE_URL/api/webhook-subscriptions" \ -H "Content-Type: application/json" \ - -d '{"name":"nomadcode-develop-wakeup","target_url":"https://consumer.example.invalid/gito/events","events":["branch.updated"],"repo_id":"nomadcode","branch":"develop","secret_ref":"secret://gito/webhooks/nomadcode"}' + -d "{\"name\":\"nomadcode-develop-wakeup\",\"target_url\":\"$GITO_NOMADCODE_TARGET_URL\",\"events\":[\"branch.updated\"],\"repo_id\":\"nomadcode\",\"branch\":\"develop\",\"secret_ref\":\"secret://gito/webhooks/nomadcode\"}" ``` 기대 응답: `201 Created`, `{"subscription": {...}}` @@ -380,7 +399,7 @@ cd services/core && go test -run TestWebhookDeliveryBranchUpdated ./internal/con ### Step 5 — Forgejo push 트리거 (서명 없는 경우) ```bash -curl -s -X POST "http://localhost:8080/callbacks/forgejo/push?repo_id=nomadcode" \ +curl -s -X POST "$GITO_BASE_URL/callbacks/forgejo/push?repo_id=nomadcode" \ -H "Content-Type: application/json" \ -H "X-Forgejo-Event: push" \ -H "X-Forgejo-Delivery: smoke-delivery-1" \ @@ -392,7 +411,7 @@ curl -s -X POST "http://localhost:8080/callbacks/forgejo/push?repo_id=nomadcode" ### Step 6 — 발행된 event 확인 ```bash -curl -s http://localhost:8080/api/events +curl -s "$GITO_BASE_URL/api/events" ``` 기대 응답에 `"type":"branch.updated"`, `"before":"old-sha"`, `"after":"new-sha"`, `changed_files`가 포함된다. diff --git a/agent-test/dev/rules.md b/agent-test/dev/rules.md new file mode 100644 index 0000000..9c73fb9 --- /dev/null +++ b/agent-test/dev/rules.md @@ -0,0 +1,63 @@ +--- +test_env: dev +last_rule_updated_at: 2026-07-01 +--- + +# dev 테스트 규칙 + +**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.** +**dev 환경은 remote local profile과 같은 host에서 분리 운영하는 Gito/NomadCode 연동 검증용 profile이다.** + +## 공통 규칙 + +- dev 테스트/검증은 이 파일을 기준으로 판단한다. +- 원격 host에서 local profile 포트와 dev profile 포트를 동시에 띄울 수 있어야 한다. +- 환경값, secret, private endpoint 원문은 tracked docs/roadmap/task log/최종 응답에 기록하지 않는다. +- raw token, password, webhook secret, provider credential, private key는 ignored local profile 또는 remote secret store에서만 주입한다. +- 컨테이너 내부 listen 포트는 제품 기본값을 우선 유지하고, workspace 충돌 관리는 host publish/direct smoke 포트로 처리한다. +- 테스트용 Docker subnet을 새로 만들 때는 `192.168.0.0/24` 대역을 사용하지 않는다. + +## 기본 환경 + +- host: standard remote runner `toki@toki-labs.com`. +- checkout: dev profile은 `$HOME/agent-work/gito-dev`를 기준으로 둔다. 아직 없으면 현재 검증 대상 branch/commit으로 생성 또는 동기화한 뒤 사용한다. +- runtime: repo root helper(`bin/test`, `bin/lint`, `bin/build`)와 변경 범위별 Go, Flutter/Dart toolchain. +- package manager: Go modules, Flutter pub. +- docker: 별도 compose를 추가하거나 복제할 때는 project/network 이름을 local profile과 분리하고 host publish 기본값을 `GITO_CORE_HOST_PORT=18061`, `GITO_POSTGRES_HOST_PORT=15461`, `GITO_REDIS_HOST_PORT=16361` 계열로 둔다. +- external service: Forgejo/Gitea/GitHub/GitLab/Jira/IOP 같은 provider 또는 runner 연동은 도메인/검증 시나리오별 문서가 명시한 경우에만 사용한다. +- credential: ignored local file 또는 `credential_ref` only. + +## 포트 매핑 + +| 용도 | local profile | dev profile | +| --- | ---: | ---: | +| Flutter/project preview | `13060` | `13061` | +| Gito Core HTTP host publish/direct smoke | `18060` | `18061` | +| optional proto-socket/agent transport | `19060` | `19061` | +| PostgreSQL host publish 후보 | `15460` | `15461` | +| Redis host publish 후보 | `16360` | `16361` | +| NomadCode webhook consumer target | `18010` | `18011` | + +dev Gito의 NomadCode delivery target은 `http://127.0.0.1:18011/api/integrations/gito/webhook`이다. local profile target은 `http://127.0.0.1:18010/api/integrations/gito/webhook`으로 유지한다. + +## Gito-NomadCode 연동 기준 + +- Gito provider intake는 dev profile에서 `http://127.0.0.1:18061/callbacks/forgejo/push`를 기준으로 검증한다. +- branch watch 등록은 `POST http://127.0.0.1:18061/api/listeners/branches`로 수행한다. +- webhook subscription은 event `branch.updated`, repo `nomadcode`, branch `develop`, target URL `http://127.0.0.1:18011/api/integrations/gito/webhook`을 기준으로 한다. +- signing secret 원문은 `secret_ref` 또는 ignored local profile에만 두고 tracked 문서에는 쓰지 않는다. +- 계약 원문은 `agent-contract/provided/gito-forgejo-branch-events-v1.md`를 따른다. + +## 라우팅 + +- workspace-ops / smoke / root helpers, docs, agent rules, roadmap, local/dev test rules: `agent-test/local/workspace-ops-smoke.md` +- core / smoke / services/core backend, control plane, worker, shell baseline: `agent-test/local/core-smoke.md` +- contracts / smoke / packages/contracts and agent-contract notes baseline: `agent-test/local/contracts-smoke.md` +- client / smoke / apps/client Flutter control surface baseline: `agent-test/local/client-smoke.md` + +## 라우팅 규칙 + +- 여러 항목이 맞으면 모두 읽는다. +- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `-smoke` 문서를 기본 baseline으로 둔다. +- 도메인이 아직 없을 때만 `project-smoke`를 fallback baseline으로 둔다. +- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다. diff --git a/agent-test/local/rules.md b/agent-test/local/rules.md index 86589f8..5b26557 100644 --- a/agent-test/local/rules.md +++ b/agent-test/local/rules.md @@ -1,6 +1,6 @@ --- test_env: local -last_rule_updated_at: 2026-06-14 +last_rule_updated_at: 2026-07-01 --- # local 테스트 규칙 @@ -24,7 +24,7 @@ last_rule_updated_at: 2026-06-14 ## 기본 환경 - host: standard remote runner `toki@toki-labs.com`, code-server compose checkout. Host path is `$HOME/docker/services/code-server/data/volume/workspace/gito`; container path is `/config/workspace/gito`. `$HOME/agent-work/gito` is not the baseline checkout for gito. -- port: Flutter/project preview는 `13060`, Core HTTP host publish 또는 direct smoke는 `18060`을 쓴다. Core process/container 내부 기본 listen은 `8080`으로 유지하고, `127.0.0.1:8080`은 명시적 product compatibility 확인에만 사용한다. proto-socket/agent transport를 Core HTTP와 분리해 host publish해야 할 때는 `19060`을 gito-owned 후보로 쓴다. code-server service 자체는 `$HOME/docker/services/code-server/compose/docker-compose.yml`가 관리하며, gito 테스트 포트로 재정의하지 않는다. PostgreSQL/Redis는 기본적으로 같은 compose의 internal service(`code-server-postgres:5432`, `code-server-redis:6379`)를 사용하고, 별도 host publish가 필요할 때만 `15460/16360` 후보를 쓴다. +- port: remote local profile은 Flutter/project preview `13060`, Core HTTP host publish 또는 direct smoke `18060`, optional proto-socket/agent transport `19060`, PostgreSQL/Redis host publish 후보 `15460/16360`을 쓴다. Core process/container 내부 기본 listen은 `8080`으로 유지하고, `127.0.0.1:8080`은 명시적 product compatibility 확인에만 사용한다. NomadCode local consumer target은 `http://127.0.0.1:18010/api/integrations/gito/webhook`이다. dev profile은 `agent-test/dev/rules.md`의 `13061/18061/19061/15461/16361`과 NomadCode dev `18011`을 사용한다. code-server service 자체는 `$HOME/docker/services/code-server/compose/docker-compose.yml`가 관리하며, gito 테스트 포트로 재정의하지 않는다. - runtime: repo root helper(`bin/test`, `bin/lint`, `bin/build`)와 변경 범위별 Go, Flutter/Dart toolchain. - package manager: Go modules, Flutter pub. - docker: 기본 runner는 `$HOME/docker/services/code-server/compose/docker-compose.yml`의 `code-server`, `code-server-postgres`, `code-server-redis`를 사용한다. 비대화형 ssh에서 Docker CLI가 PATH에 없으면 `/usr/local/bin/docker`를 사용한다. gito 전용 DB 검증은 `code-server-postgres`에 `gito_test` DB를 만들고, code-server 컨테이너의 `DATABASE_URL`에서 DB 이름만 `gito_test`로 바꿔 `GITO_TEST_DATABASE_URL`에 주입한다. raw DSN/password는 출력하거나 tracked 파일에 기록하지 않는다. 별도 compose를 추가하거나 복제할 때는 project/network 이름을 `gito`로 분리하고 host publish 기본값을 `GITO_CORE_HOST_PORT=18060`, `GITO_POSTGRES_HOST_PORT=15460`, `GITO_REDIS_HOST_PORT=16360` 계열로 둔다.