jeo-code 0.1.0 → 0.4.5

package/README.ja.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <img src="assets/hero.png" alt="jeo-code 自律コーディングエージェントのヒーローイラスト" width="100%" />
+</p>
+
+<h1 align="center">jeo-code (jeo)</h1>
+
+<p align="center">
+  <strong>Encode intention. Decode software.</strong><br />
+  Bun ベースの AI コーディングエージェント CLI — インタビュー、レビュー済みプラン、ゲート付き実行、誠実な検証。
+</p>
+
+<p align="center">
+  <a href="https://github.com/akillness/jeo-code"><img alt="license" src="https://img.shields.io/badge/license-MIT-green?style=flat-square"></a>
+  <img alt="runtime" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3.14-f9f1e1?style=flat-square&logo=bun&logoColor=black">
+  <img alt="zero native deps" src="https://img.shields.io/badge/native%20deps-0-blue?style=flat-square">
+</p>
+
+<p align="center">
+  <img src="assets/character.png" alt="jeo-code キャラクターマスコット" width="320" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> ·
+  <a href="README.ko.md">한국어</a> ·
+  <b>日本語</b> ·
+  <a href="README.zh.md">中文</a>
+</p>
+
+リポジトリ内で `jeo` を実行すると、ファイルを読み・編集し・コマンドを実行してタスクを完了まで進めます — 全ステップがスクロールバック親和なインライン TUI でライブ配信されます。
+
+## ハイライト
+
+- **マルチプロバイダ・単一ループ** — Anthropic / OpenAI(+Codex) / Gemini / Antigravity / Ollama を均一な JSON ツールループで。入力欄から OAuth ログイン(`/provider login`)、モデル選択は即座にデフォルトとして永続化。
+- **編集の完全性** — read 出力にコンテンツアンカー(`42ab|`)が付き、アンカー付き編集は現在のファイルと照合・行移動時は自動再マッピング・不一致時は最新内容と共に拒否されます。
+- **自己修正の検証ループ** — post-edit フック(tsc / eslint / テスト)を設定すると、エージェントが診断を*自ら読み*ループ内で修正します。フックが赤のままだと `done` はブロックされます。
+- **芝居なしの本物のゲート** — `ralplan` の合議はリポジトリを実際に読む critic サブエージェントで、`[OKAY]` 評決が永続化され `jeo approve` がそれを*要求*します。`ultragoal` は誠実に報告します(スイート1回実行はグローバル信号であり、基準ごとの合格を捏造しません)。
+- **クラッシュ耐久・ローカルファースト** — 全状態は `.jeo/` 配下にアトミック書き込み、プロセス間ロック、失敗タスクマーカー + 再開時の部分編集警告。
+- **動的ステップ予算** — 直近のツール呼び出しが新規の進捗を示す間は延長され、停滞すれば要約に収束。サブエージェントは厳密なステップ契約を維持。
+- **インライン TUI** — 完了した作業は実スクロールバックに流れ(ターン中も tmux ホイール可)、エージェント実行中も通常のクエリ入力欄が表示されたまま編集できます。Ctrl+O の詳細トグル、テーマ、クリップボード画像貼り付け(Ctrl+V)、CJK/絵文字対応の幅計算。
+
+## インストール
+
+Bun `1.3.14+` が必要です。
+
+```bash
+bun install -g jeo-code
+jeo --version
+```
+
+## クイックスタート
+
+```bash
+jeo                      # 現在のリポジトリで対話エージェント
+jeo "README を整えてテストを実行して"   # ワンショット要求
+jeo doctor               # 設定 + ライブモデル接続チェック
+jeo setup                # API キー / OAuth / ローカルモデル設定
+jeo --tmux               # 独立した tmux セッションで実行
+```
+
+## スラッシュコマンド
+
+`jeo` REPL 内で使用(Tab 補完、`/` でパレット)。
+
+| コマンド | 説明 |
+| --- | --- |
+| `/model` · `/provider` | モデル/プロバイダ選択; `/model` でデフォルト/ロールバッジ、Ralph 風の入れ子ロール・thinking 選択、OpenAI Codex ロールプリセットを一つの流れで設定 |
+| `/provider login <name>` · `/logout` | 入力欄から OAuth ログイン/ログアウト |
+| `/agents [role]` · `/subagent` | ロール別(executor/planner/architect/critic)モデル・thinking・ステップ設定 |
+| `/thinking [level]` | デフォルト推論予算(minimal…xhigh)の表示/設定 |
+| `/fast [on|off|status]` | 現在のモデルが minimal/low 推論をサポートする場合に fast thinking モードを切替 |
+| `/skill` · `$<skill> [intent]` | ワークフロースキルの一覧/実行(`$team "task"` 形式) |
+| `/view` · `/diff` · `/find` · `/search` | コード表示、git diff、ファイル/パターン検索 |
+| `/new` · `/resume` · `/sessions` | セッション管理 |
+| `/history [n|all]` · `/export` | 作業アクティビティ履歴を読みやすくスクロールバックへ再出力・トランスクリプト出力 |
+| `/retry` · `/btw <q>` | 直前要求の再試行 · 履歴に残らないサイド質問 |
+| `/usage` · `/context` · `/compact` | トークン使用量、コンテキスト内訳、手動コンパクション |
+| `/theme` · `/config` · `/help` | テーマ、ランタイム設定、ヘルプ |
+| `jeo autopilot status` | スコア方向、keep/revert 数、次アクションを示す ratchet ステータスフィールド |
+
+## Spec-first ワークフロー
+
+要件 → プラン → 承認 → 実行 → 検証が `.jeo/state/` で繋がり、各ハンドオフに**ブロック可能な本物のゲート**があります:
+
+```bash
+jeo deep-interview "作りたいものを説明"
+jeo ralplan
+jeo approve <プランパス>
+jeo team
+jeo ultragoal
+```
+
+- **deep-interview** — 曖昧度スコアリングのソクラテス式ループ。基準が具体的な場合のみシードを凍結(曖昧のみの基準は拒否)、シードは自身のパーサをラウンドトリップで通過する必要があります。新しいアイデアが完了済みインタビューを黙って再利用することはありません。
+- **ralplan** — ドラフトパス + **リポジトリを実際に読む critic サブエージェントゲート**: `[OKAY]`/`[ITERATE]`/`[REJECT]` 評決が強制・永続化されます。無効なプラン(スキーマ・未知ロール)は complete になりません。
+- **approve** — `team` が実行する契約(スキーマ+ロール)を検証し、永続化された `[OKAY]` 評決まで要求します。
+- **team** — 直列プラン実行器: プロセス間ロック、stale プランのリセット、タスク別サブエージェント契約、親側の変更監査(書き込み0件の「完了」はフラグ)、失敗マーカー + 再開時の部分編集警告。
+- **ultragoal** — 誠実な検証: スイートはグローバル信号として1回実行され、基準は記録されるのみで個別合格には捏造されません。
+
+## 検証フック(自己修正)
+
+グローバルで一度有効化(`~/.jeo/config.json` に `"hooks": { "enabled": true }`)し、プロジェクトごとに post-edit チェックを追加すると、エージェントは失敗を読み `done` の前に修正します:
+
+```jsonc
+// .jeo/hooks.json
+{
+  "enabled": true,
+  "hooks": [
+    { "event": "post-turn", "match": { "tool": "edit|write" }, "run": "bun x tsc --noEmit" }
+  ]
+}
+```
+
+非ゼロ終了したフックの出力はモデルが読むツール結果に付加され(バッチ内で重複排除)、フックが赤のまま `done` を呼ぶとフック名付きでプッシュバックされます。
+
+## ローカルモデル
+
+```bash
+ollama pull qwen2.5:0.5b
+export JEO_DEFAULT_MODEL=ollama/qwen2.5:0.5b
+jeo doctor && jeo
+```
+
+## 設定
+
+- グローバル設定: `~/.jeo/config.json`(モデル選択は MRU 永続)
+- プロジェクト状態/セッション: `<project>/.jeo/`
+
+```bash
+ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...
+JEO_DEFAULT_MODEL=...           # 例: ollama/qwen2.5:0.5b
+OLLAMA_HOST=http://localhost:11434
+JEO_TUI_THEME=cosmic            # cosmic/matrix/solar/red-claw/blue-crab/mono/aurora/synthwave/sakura
+JEO_TUI_ALT_SCREEN=1            # レガシー alt-screen ターン(デフォルト: インラインスクロールバック)
+JEO_STEP_BASE=24                # 動的ステップ予算のローリングベース
+JEO_STEP_HARD_CAP=600           # 絶対終了保証
+JEO_STREAM_MAX_MS=300000        # オプトインの全体ストリーム期限(デフォルト off; スロードリップ遮断)
+JEO_TOOL_OUTPUT_MAX=4000        # モデル可視のツール出力上限(全文はアーティファクトへ)
+```
+
+リトライ動作は `~/.jeo/config.json` の `retry` で調整します(`requestMaxRetries`、`streamMaxRetries`、`rateLimitRetries`、`failFastStatuses` など)。ステップ予算はデフォルトで動的 — 新規進捗が見える間は延長され、停滞時は要約に収束します。`--max-steps N` で有限フローに戻ります。
+
+## 公開 (Publishing)
+
+CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリース公開時に自動、または `workflow_dispatch` の手動実行(ドライラン可)。ワークフローは型チェック・テスト・トークン検証(`npm whoami`)の後、`npm publish --provenance` を実行します。
+
+必要な npm トークン権限(リポジトリシークレット `NPM_TOKEN`):
+
+- `jeo-code` パッケージへの Read/Write 権限を持つ **Granular Access Token**、またはクラシック **Automation** トークン
+- 「公開時の **bypass 2FA**」許可が必須 — Automation トークンは常にバイパス、granular トークンはオプションの有効化が必要
+
+## 変更履歴 (Changelog)
+
+<!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.4.5]** (2026-06-14) — First-class filesystem make/remove tools.
+- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
+- **[0.4.3]** (2026-06-13) — Readability pass for autopilot, subagent activity, and worked-history review.
+- **[0.4.2]** (2026-06-13) — Thinking-loop termination guarantees (cycle guard + turn wall-clock budget), unboxed live status without step counters, self-contained `.jeo` namespace, live next-prompt input card, role-targeted model/thinking picker.
+- **[0.4.1]** (2026-06-12) — TUI card parity polish + done-time todo reconciliation.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+<!-- CHANGELOG:END -->

package/README.ko.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <img src="assets/hero.png" alt="jeo-code 자율 코딩 에이전트 히어로 일러스트" width="100%" />
+</p>
+
+<h1 align="center">jeo-code (jeo)</h1>
+
+<p align="center">
+  <strong>Encode intention. Decode software.</strong><br />
+  Bun 기반 AI 코딩 에이전트 CLI — 인터뷰, 검토된 플랜, 게이트된 실행, 정직한 검증.
+</p>
+
+<p align="center">
+  <a href="https://github.com/akillness/jeo-code"><img alt="license" src="https://img.shields.io/badge/license-MIT-green?style=flat-square"></a>
+  <img alt="runtime" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3.14-f9f1e1?style=flat-square&logo=bun&logoColor=black">
+  <img alt="zero native deps" src="https://img.shields.io/badge/native%20deps-0-blue?style=flat-square">
+</p>
+
+<p align="center">
+  <img src="assets/character.png" alt="jeo-code 캐릭터 마스코트" width="320" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> ·
+  <b>한국어</b> ·
+  <a href="README.ja.md">日本語</a> ·
+  <a href="README.zh.md">中文</a>
+</p>
+
+저장소 안에서 `jeo`를 실행하면 파일을 읽고, 수정하고, 명령을 실행하며 작업을 완료까지 끌고 갑니다 — 모든 스텝이 스크롤백 친화적인 인라인 TUI로 실시간 스트리밍됩니다.
+
+## 하이라이트
+
+- **멀티 프로바이더, 단일 루프** — Anthropic / OpenAI(+Codex) / Gemini / Antigravity / Ollama를 균일한 JSON 도구 루프로. 입력창에서 바로 OAuth 로그인(`/provider login`), 모델 선택은 즉시 기본값으로 영속.
+- **편집 무결성** — read 출력에 콘텐츠 앵커(`42ab|`)가 붙고, 앵커 편집은 현재 파일과 대조 검증·줄 이동 시 자동 재매핑·불일치 시 최신 내용과 함께 거부 — 파일을 오염시키지 않습니다.
+- **자기수정 검증 루프** — post-edit 훅(tsc / eslint / 테스트)을 설정하면 에이전트가 진단을 *직접 읽고* 루프 안에서 수정합니다. 훅이 빨간 상태면 `done`이 차단됩니다.
+- **연극 없는 진짜 게이트** — `ralplan` 합의는 실제 저장소를 읽는 critic 서브에이전트이며 `[OKAY]` 평결이 영속되고 `jeo approve`가 이를 *요구*합니다. `ultragoal`은 정직하게 보고합니다(스위트 1회 실행은 전역 신호일 뿐, 기준별 통과를 조작하지 않음).
+- **크래시 내구·로컬 우선** — 모든 상태는 `.jeo/` 아래 원자적 쓰기, 크로스 프로세스 런 락, 실패 태스크 마커 + 재개 시 부분 편집 경고.
+- **동적 스텝 버짓** — 최근 도구 호출이 새로운 진전을 보이는 동안 연장되고, 정체되면 정리 요약으로 수렴. 서브에이전트는 정확한 스텝 계약 유지.
+- **인라인 TUI** — 완료된 작업은 실제 스크롤백으로 흘러가고(턴 중에도 tmux 휠 스크롤 가능), 에이전트가 실행 중이어도 기존 쿼리 입력창이 그대로 보이며 편집됩니다. Ctrl+O 상세 토글, 테마, 클립보드 이미지 붙여넣기(Ctrl+V), CJK/이모지 안전 폭 계산.
+
+## 설치
+
+Bun `1.3.14+` 필요.
+
+```bash
+bun install -g jeo-code
+jeo --version
+```
+
+## 빠른 시작
+
+```bash
+jeo                      # 현재 저장소에서 대화형 에이전트
+jeo "README 정리하고 테스트 돌려줘"   # 원샷 요청
+jeo doctor               # 설정 + 라이브 모델 연결 점검
+jeo setup                # API 키 / OAuth / 로컬 모델 설정
+jeo --tmux               # 독립 tmux 세션에서 실행
+```
+
+## 슬래시 명령
+
+`jeo` REPL 안에서 사용(Tab 자동완성, `/` 입력 시 팔레트).
+
+| 명령 | 설명 |
+| --- | --- |
+| `/model` · `/provider` | 모델/프로바이더 선택; `/model`에서 기본/역할 배지, Ralph식 하위 리스트 역할·thinking 선택, OpenAI Codex 역할 프리셋을 한 흐름으로 설정 |
+| `/provider login <name>` · `/logout` | 입력창에서 OAuth 로그인/로그아웃 |
+| `/agents [role]` · `/subagent` | 역할별(executor/planner/architect/critic) 모델·thinking·스텝 구성 |
+| `/thinking [level]` | 기본 추론 예산(minimal…xhigh) 조회/설정 |
+| `/fast [on|off|status]` | 현재 모델이 minimal/low 추론을 지원하면 fast thinking 모드를 켜고 끔 |
+| `/skill` · `$<skill> [intent]` | 워크플로 스킬 목록/실행(`$team "작업"` 스타일) |
+| `/view` · `/diff` · `/find` · `/search` | 코드 보기, git diff, 파일/패턴 검색 |
+| `/new` · `/resume` · `/sessions` | 세션 관리 |
+| `/history [n|all]` · `/export` | 작업 활동 히스토리를 읽기 좋게 스크롤백에 재출력 · 트랜스크립트 내보내기 |
+| `/retry` · `/btw <질문>` | 마지막 요청 재시도 · 히스토리에 안 남는 사이드 질문 |
+| `/usage` · `/context` · `/compact` | 토큰 사용량, 컨텍스트 내역, 수동 컴팩션 |
+| `/theme` · `/config` · `/help` | 테마, 런타임 설정, 도움말 |
+| `jeo autopilot status` | 점수 방향, keep/revert 횟수, 다음 액션을 보여주는 ratchet 상태 필드 |
+
+## Spec-first 워크플로
+
+요구사항 → 플랜 → 승인 → 실행 → 검증이 `.jeo/state/`로 이어지며, 모든 핸드오프에 **차단 가능한 진짜 게이트**가 있습니다:
+
+```bash
+jeo deep-interview "만들고 싶은 것을 설명"
+jeo ralplan
+jeo approve <플랜경로>
+jeo team
+jeo ultragoal
+```
+
+- **deep-interview** — 모호성 스코어링 기반 소크라테스 루프. 기준이 구체적일 때만 시드 동결(vague-only 기준은 거부), 시드는 자체 파서 라운드트립을 통과해야 합니다. 새 아이디어가 완료된 인터뷰를 조용히 재사용하지 않습니다.
+- **ralplan** — 드래프팅 패스 + **저장소를 직접 읽는 critic 서브에이전트 게이트**: `[OKAY]`/`[ITERATE]`/`[REJECT]` 평결이 강제·영속됩니다. 무효 플랜(스키마·미지 역할)은 complete로 마킹되지 않습니다.
+- **approve** — `team`이 실행하는 계약(스키마+역할)을 검증하고 영속된 `[OKAY]` 평결까지 요구합니다.
+- **team** — 직렬 플랜 실행기: 크로스 프로세스 런 락, stale 플랜 리셋, 태스크별 서브에이전트 계약, 부모측 변이 감사(쓰기 0건의 "완료"는 플래그), 실패 마커 + 재개 시 부분 편집 경고.
+- **ultragoal** — 정직한 검증: 스위트는 전역 신호로 1회 실행, 기준은 기록될 뿐 개별 통과로 조작되지 않습니다.
+
+## 검증 훅 (자기수정)
+
+전역에서 한 번 활성화(`~/.jeo/config.json`에 `"hooks": { "enabled": true }`)한 뒤 프로젝트별 post-edit 검사를 추가하면, 에이전트가 실패를 읽고 `done` 전에 고칩니다:
+
+```jsonc
+// .jeo/hooks.json
+{
+  "enabled": true,
+  "hooks": [
+    { "event": "post-turn", "match": { "tool": "edit|write" }, "run": "bun x tsc --noEmit" }
+  ]
+}
+```
+
+비정상 종료한 훅의 출력은 모델이 읽는 도구 결과에 첨부되고(배치 내 중복 제거), 훅이 빨간 채로 `done`을 부르면 훅 이름과 함께 푸시백됩니다.
+
+## 로컬 모델
+
+```bash
+ollama pull qwen2.5:0.5b
+export JEO_DEFAULT_MODEL=ollama/qwen2.5:0.5b
+jeo doctor && jeo
+```
+
+## 설정
+
+- 전역 설정: `~/.jeo/config.json` (모델 선택은 MRU 영속)
+- 프로젝트 상태/세션: `<project>/.jeo/`
+
+```bash
+ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...
+JEO_DEFAULT_MODEL=...           # 예: ollama/qwen2.5:0.5b
+OLLAMA_HOST=http://localhost:11434
+JEO_TUI_THEME=cosmic            # cosmic/matrix/solar/red-claw/blue-crab/mono/aurora/synthwave/sakura
+JEO_TUI_ALT_SCREEN=1            # 레거시 alt-screen 턴(기본: 인라인 스크롤백)
+JEO_STEP_BASE=24                # 동적 스텝 버짓의 롤링 베이스
+JEO_STEP_HARD_CAP=600           # 절대 종료 보증
+JEO_STREAM_MAX_MS=300000        # 옵트인 전체 스트림 데드라인(기본 off; 슬로우드립 차단)
+JEO_TOOL_OUTPUT_MAX=4000        # 모델 가시 도구 출력 캡(전체는 아티팩트로 스필)
+```
+
+재시도 동작은 `~/.jeo/config.json`의 `retry`로 조정합니다(`requestMaxRetries`, `streamMaxRetries`, `rateLimitRetries`, `failFastStatuses`, …). 스텝 버짓은 기본 동적 — 새로운 진전이 보이는 동안 연장되고 정체 시 요약으로 수렴하며, `--max-steps N`이면 유한 플로로 복귀합니다.
+
+## 배포 (Publishing)
+
+CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리즈 게시 시 자동, 또는 `workflow_dispatch` 수동 실행(드라이런 옵션). 워크플로는 타입체크·테스트·토큰 검증(`npm whoami`) 후 `npm publish --provenance`를 실행합니다.
+
+필요한 npm 토큰 권한(저장소 시크릿 `NPM_TOKEN`):
+
+- `jeo-code` 패키지에 Read/Write 권한이 있는 **Granular Access Token**, 또는 클래식 **Automation** 토큰
+- "배포 시 **bypass 2FA**" 허용 필수 — Automation 토큰은 항상 우회, granular 토큰은 옵션 활성화 필요
+
+## 변경 이력 (Changelog)
+
+<!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.4.5]** (2026-06-14) — First-class filesystem make/remove tools.
+- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
+- **[0.4.3]** (2026-06-13) — Readability pass for autopilot, subagent activity, and worked-history review.
+- **[0.4.2]** (2026-06-13) — Thinking-loop termination guarantees (cycle guard + turn wall-clock budget), unboxed live status without step counters, self-contained `.jeo` namespace, live next-prompt input card, role-targeted model/thinking picker.
+- **[0.4.1]** (2026-06-12) — TUI card parity polish + done-time todo reconciliation.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+<!-- CHANGELOG:END -->