@pinta-ai/pinta-gemini 0.1.0

package/LICENSE

@@ -0,0 +1,136 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software.  Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Pinta AI (https://pinta.sh)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make
+changes and new works based on the software for any permitted
+purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law.  These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control
+of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+---
+
+Required Notice: Copyright (c) 2026 Pinta AI

package/README.md

@@ -0,0 +1,68 @@
+# pinta-gemini
+
+단일 어댑터로 **세 호스트**의 hook 이벤트를 받아 (1) OTLP/HTTP span 으로 forward(관측),
+(2) tool 호출을 원격 guard 로 allow/deny(집행)한다. `pinta-cc`/`pinta-codex`/`pinta-copilot` 의 자매 어댑터로,
+core(otlp/transport/retry-queue/redact/guard/trace)를 공유 패턴으로 재사용한다.
+
+| 호스트 | `--agent` | hook 메커니즘 (실측 검증) |
+|---|---|---|
+| Google Gemini CLI | `gemini` | **extension** `~/.gemini/extensions/pinta-gemini/` (folder-trust 우회) |
+| Antigravity CLI (agy v1.0.x) | `antigravity` | 전역 `~/.gemini/config/hooks.json` |
+| Antigravity 2.0 | `antigravity` | 전역 `~/.gemini/config/hooks.json` (동일) 또는 workspace `.agents/hooks.json` |
+
+> 상태: **v0.1 (검증 완료)**. 2026-06-15 실측에서 gemini 8/8, antigravity 5/5 이벤트 커버리지 +
+> payload 형상·deny/allow·인자보존 확인. 자세한 건 [`docs/SPEC.md`](./docs/SPEC.md), [`docs/BACKGROUND_RESEARCH.md`](./docs/BACKGROUND_RESEARCH.md) PART F 참조.
+
+## 저장소 구조
+```
+src/
+  index.ts            진입점 (loadEnv → parse argv → normalize → guard → forward → decision → exit 0)
+  env-file.ts         ~/.gemini/pinta-gemini.env 로더 (호스트가 env 안 주므로 주입 벡터)
+  core/
+    types.ts          Agent/Canonical 타입 + 호스트 family helper(gate/identity)
+    agent.ts          --agent/--event 파싱 + antigravity 제품 서브라벨(transcriptPath)
+    normalize.ts      호스트 payload → canonical (snake/camel 흡수)
+    config.ts         endpoint/headers/guard/data-dir 해석
+    guard.ts          원격 guard 평가 (50ms, fail-open)       ← pinta-cc 재사용
+    decision.ts       호스트별 allow/deny 출력
+    otlp.ts           멀티호스트 Bronze flatten + ingest.type/prefix/service.name
+    transport.ts      OTLP/HTTP POST (5s) + 실패 시 retry-queue
+    retry-queue.ts    파일 JSONL 큐 (cap 1000, 파일락)        ← pinta-cc 재사용
+    redact.ts         시크릿 마스킹 + truncation              ← pinta-cc 재사용
+    trace.ts          session 키 ULID trace map
+    invocation-log.ts DEBUG 감사 로그 (invocations.jsonl)
+tools/
+  install-hooks.ts    호스트별 설치 (gemini=extension / antigravity=전역 config; lifecycle=flat 구조)
+  doctor.ts           설치/엔드포인트 헬스체크
+  hook-verify.ts      실측 검증 watcher (watch/report/teardown/selftest)
+  e2e-hooks.ts        오프라인 계약 테스트 (mock guard+collector + reference stub)
+  e2e-from-config.ts  오프라인 install→read→fire 테스트 (sandbox)
+  demo-trace.ts       모든 이벤트 발사 + payload 관측 데모
+tests/core.test.ts    단위 테스트 (normalize/decision/agent/otlp)
+docs/                 SPEC + 배경연구
+```
+
+## 빠른 시작
+```bash
+npm install                    # devDeps (esbuild/tsx/vitest)
+npm run build                  # → dist/index.js (install 전 필수)
+npm test                       # vitest 단위 테스트
+npm run e2e                    # 오프라인 계약 테스트 (3 호스트 형상)
+
+# 실제 호스트 검증 (CLI 는 직접 실행)
+npm run verify                 # ~/.gemini 에 설치 + watcher; 다른 터미널서 gemini/agy 실행
+#   antigravity2 workspace:  npm run verify -- --workspace /path/to/project
+npx tsx tools/hook-verify.ts report     # 누적 invocations.jsonl 채점
+npm run doctor                 # 설치/엔드포인트 상태
+npx tsx tools/hook-verify.ts teardown   # 원복 (hook 제거, jsonl 보존)
+```
+
+## 동작 계약 (요약 — 상세 [SPEC §7](./docs/SPEC.md))
+- 이벤트/agent 식별: install 시 command 에 박는 `--agent`/`--event` 인자가 유일 수단(인자보존 실측 확정).
+- 출력: stdout 에 **항상 단일 JSON**, **항상 exit 0**(fail-open).
+- deny: gemini `{decision,reason,systemMessage}` / antigravity `{decision,reason}`. allow: gemini `{}` / antigravity PreToolUse `{decision:"allow"}`.
+- guard: `PINTA_GUARD_ENDPOINT` POST, 50ms, fail-open. 텔레메트리: `GEMINI_PLUGIN_OPTION_*` > `OTEL_EXPORTER_OTLP_*`.
+- 설정 주입: 호스트가 hook 에 env 를 안 주므로 `~/.gemini/pinta-gemini.env`(어댑터가 읽음)로 주입.
+
+## 라이선스
+PolyForm Noncommercial 1.0.0