aiakiv 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OnMinimum (AiAkiv)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# aiakiv
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+폴더 하나를 AiAkiv 프로젝트에 고정하는 명령줄 도구입니다(Claude Code, Codex, Gemini CLI, Cursor).
+폴더 고정과 확인을 명령 두 개로 합니다. 설계는 K2G `docs/204_blue_print-165-aiakiv_cli_setup_and_key_handoff.md` 에 있습니다.
+
+```
+npx aiakiv bind   --client codex|claude|gemini|cursor --project <이름> [--dir <폴더>] [--expires-days N] [--no-browser] [--no-skills]
+npx aiakiv doctor [--client <클라이언트>[,...]] [--dir <폴더>] [--out aiakiv-verification-test.md] [--no-probe]
+```
+
+전역 설치(계정 연결과 전역 스킬)는 이 도구가 하지 않습니다. 설치 프롬프트나 플러그인 마켓
+(`AiAkiv/aiakiv-plugins`)으로 합니다. 첫 판에 있던 `setup` 명령은 없어졌고, 치면 이 안내를 보여 주고 끝납니다.
+
+## 필요한 것
+
+- Node.js 18.3 이상(`npx` 포함). 없으면 설치합니다.
+  - Windows: `winget install OpenJS.NodeJS.LTS`
+  - macOS: `brew install node`
+  - Linux: 배포판 패키지(`sudo apt install nodejs npm` 등) 또는 nvm
+- doctor 가 전역 등록 목록을 볼 때 쓰는 클라이언트 CLI(`claude`, `codex`). 없으면 "없음" 으로 적고 계속합니다.
+  Codex 는 PATH 에 없어도 Windows 앱 설치 위치(`%LOCALAPPDATA%\OpenAI\Codex\bin\<폴더>\codex.exe`)에서 찾습니다.
+
+## bind: 폴더에 프로젝트 고정
+
+bind 는 웹 콘솔의 "폴더 ZIP 받기" 와 같은 한 벌을 그 폴더에 직접 씁니다(정본은 k2g-console-web
+`src/lib/folderBundle.ts`). ZIP 의 `README.md` 는 쓰지 않고, 안내는 화면에 냅니다.
+
+| 클라이언트 | 연결 설정 | 함께 쓰는 것 |
+|---|---|---|
+| claude | `.mcp.json` | `.claude/settings.json` 의 `enabledMcpjsonServers` 에 서버 이름, 폴더 스킬 `.claude/skills/<이름>/` |
+| cursor | `.cursor/mcp.json` | 폴더 스킬 `.agents/skills/<이름>/` |
+| codex | `.codex/config.toml` | 폴더 스킬 `.agents/skills/<이름>/`, `.gitignore` 에 `/.codex/config.toml` |
+| gemini | `.gemini/settings.json` | 폴더 스킬 `.agents/skills/<이름>/`, `.gitignore` 에 `/.gemini/settings.json` |
+
+### 폴더 스킬
+
+- 스킬 일곱 개(`aiakiv-onboarding`, `aiakiv-save-and-recall`, `aiakiv-graph-query`, `aiakiv-links`, `aiakiv-cards`,
+  `aiakiv-console`, `aiakiv-contents`)를 공개 저장소 [AiAkiv/aiakiv-plugins](https://github.com/AiAkiv/aiakiv-plugins)
+  에서 받습니다. 받는 주소는 `https://codeload.github.com/AiAkiv/aiakiv-plugins/tar.gz/refs/heads/main` 이고,
+  압축 파일 안의 플러그인 매니페스트(`aiakiv/.claude-plugin/plugin.json`)가 가리키는 `skills/` 아래만 꺼냅니다.
+  각 스킬 폴더의 참고 파일도 모두 복사하고, 판 번호는 그 매니페스트에서 읽어 화면에 냅니다
+  (예: `폴더 스킬 7개: .agents/skills (판 0.4.24)`).
+- 자리는 콘솔 ZIP 과 같습니다. Claude Code 는 `.claude/skills`, Codex 와 Gemini CLI 는 `.agents/skills` 한 벌입니다
+  (둘이 같은 자리를 읽어 두 벌 두면 Codex 에서 겹쳐 보입니다).
+- Cursor 도 `.agents/skills` 에 넣습니다. Cursor 문서(cursor.com/docs/context/skills)가 이 자리를 프로젝트 스킬
+  자리로 적고 있고, Skills CLI 의 cursor 설정도 같은 자리입니다(2026-10-14 확인). 콘솔 ZIP 에는 Cursor 가 없습니다.
+- 같은 이름의 스킬 폴더는 통째로 바꾸고(그 안의 예전 파일은 사라집니다), 그 밖의 파일과 다른 스킬은 건드리지 않습니다.
+  같은 이름 자리가 심볼릭 링크나 정션이면 링크만 지우고 가리키던 곳은 그대로 둡니다.
+- 압축 파일 안에 절대 경로나 `..` 가 든 경로가 하나라도 있거나, 스킬 자리 안에 심볼릭 링크, 하드 링크, Windows 에서
+  쓸 수 없는 이름이 있으면 스킬을 하나도 쓰지 않습니다.
+- 받기에 실패해도 bind 는 멈추지 않습니다(연결 설정은 이미 썼고 종료 코드는 0). 대신 그 폴더에서 칠 명령을 보여 줍니다:
+  `npx -y skills add AiAkiv/aiakiv-plugins -a <claude-code|codex|gemini-cli|cursor> -s '*' -y`
+  (`--all` 과 `-g` 는 쓰지 않습니다. `--all` 은 모든 에이전트 폴더에 퍼지고, `-g` 는 전역에 넣습니다).
+- `--no-skills` 면 스킬만 건너뜁니다. 연결 설정, `.claude/settings.json`, `.gitignore` 는 그대로 씁니다.
+
+### Claude 의 enabledMcpjsonServers
+
+`.claude/settings.json` 의 `enabledMcpjsonServers` 배열에 서버 이름을 더합니다. 폴더를 신뢰한 뒤에는 Claude Code 가
+이 서버를 묻지 않고 켭니다. 다른 키와 다른 값은 그대로 두고, 이미 있으면 파일을 다시 쓰지 않습니다. 주석이나 끝 쉼표가
+있는 파일은 읽되 다시 쓸 때 원본을 `<파일>.aiakiv-backup` 으로 남깁니다. 배열이 아니면 바꾸지 않고 알리기만 합니다.
+
+### 키 파일과 .gitignore
+
+Codex 와 Gemini 는 설정 파일에 키가 들어갑니다. 그 폴더가 git 저장소이거나 `.gitignore` 가 이미 있으면
+`/.codex/config.toml`, `/.gemini/settings.json` 줄을 그 폴더의 `.gitignore` 에 더합니다(이미 무시되면 더하지 않습니다).
+둘 다 아니면 더하지 않고 경고만 합니다.
+
+### 연결 설정의 모양
+
+| 클라이언트 | 설정 파일(폴더 기준) | 인증 | 쓰는 내용 |
+|---|---|---|---|
+| claude | `.mcp.json` | OAuth | `mcpServers["AiAkiv-<프로젝트>"] = {type: "http", url: ".../mcp?project=<이름>", headers?}` |
+| cursor | `.cursor/mcp.json` | OAuth | claude 와 같은 모양 |
+| codex | `.codex/config.toml` | 프로젝트 키 | `[mcp_servers.AiAkiv-<프로젝트>]` 의 `url`, `http_headers = { "Authorization" = "Bearer <키>" }` |
+| gemini | `.gemini/settings.json` | 프로젝트 키 | `mcpServers["AiAkiv-<프로젝트>"] = {httpUrl, headers: {Authorization: "Bearer <키>"}}` |
+
+- 서버 이름 규칙은 웹 콘솔(k2g-console-web `src/lib/mcpSnippet.ts`)과 같은 코드입니다(`src/snippet.ts`).
+- 기존 설정 파일의 다른 항목은 그대로 두고, 같은 이름의 항목만 덮어씁니다. 읽을 수 없는 파일은 건드리지 않고 멈춥니다.
+- JSON 설정 파일에 주석이나 끝 쉼표가 있으면(Cursor 의 `mcp.json` 은 이것을 받아 줍니다) 읽기는 하지만, 다시 쓸 때
+  표준 JSON 이 되면서 주석과 끝 쉼표가 사라집니다. 그때는 원본을 `<파일>.aiakiv-backup` 으로 남기고 알립니다.
+  원본에 예전 키가 들어 있을 수 있으니 확인한 뒤 지우세요.
+
+### codex, gemini: 브라우저 인계로 키 받기
+
+1. CLI 가 `127.0.0.1` 의 빈 포트에서 기다리고, 웹 콘솔의 인계 화면
+   (`<콘솔>/account/cli/handoff?project=…&port=…&state=…&client=…`)을 브라우저로 엽니다.
+   브라우저가 열리지 않으면 화면에 나온 주소를 직접 엽니다(`--no-browser` 는 열지 않고 주소만 보여 줍니다).
+2. 웹 콘솔에서 로그인하고 확인 단추를 누릅니다. 프로젝트가 없으면 그 화면에서 만들 수 있습니다.
+3. 콘솔이 일회용 코드를 들려 `http://127.0.0.1:<포트>/callback` 으로 돌려보내면, CLI 가 `state` 를 대조하고
+   `POST <콘솔>/api/cli/exchange` 로 코드를 키로 바꿉니다. 5분 안에 확인이 오지 않으면 끝냅니다.
+4. 키를 그 폴더의 설정 파일에 쓰고, 화면에는 키 id, 서버 이름, 파일 경로만 냅니다.
+
+### claude, cursor: 이름 규칙의 한계
+
+OAuth 길은 키를 받지 않으므로 프로젝트 id 를 모릅니다. 콘솔은 영문이 아닌 글자가 든 이름이나 긴 이름에
+프로젝트 id 조각을 붙이는데(`K2G-연구` 는 `AiAkiv-K2G-3f9a1c`), CLI 는 그 자리에 **프로젝트 이름의 해시 6자**를
+붙입니다(`AiAkiv-K2G-<해시>`). 그래서 이런 이름은 콘솔이 주는 이름과 다릅니다. 서버 이름은 이 PC 안의 꼬리표라
+동작은 같고, 같은 이름을 원하면 콘솔에서 복사하라고 안내합니다. 같은 프로젝트 주소를 가리키는 `AiAkiv…` 항목이
+이미 있으면 그 이름을 그대로 씁니다. 영문 19자 이내의 이름은 콘솔과 똑같습니다.
+
+이 길은 프로젝트가 있는지도 확인하지 않습니다. 없는 프로젝트면 도구를 부를 때 막히므로 콘솔에서 먼저 만듭니다.
+
+## doctor: 확인
+
+- 폴더의 설정 파일 네 개와 전역 `~/.cursor/mcp.json`, `~/.gemini/settings.json` 에서 AiAkiv 항목을 찾아
+  이름, 주소, 인증 방식(OAuth `?project=`, OAuth Main, API 키 Bearer, 환경 변수 키)을 적습니다.
+- `claude mcp list`, `claude plugin list --json`, `codex mcp list --json` 에서 **AiAkiv 항목만** 옮깁니다.
+  명령이 없으면 "없음" 으로 적고 계속합니다. 전역 등록은 bind 와 상관없지만, 폴더 연결과 겹치는 연결을 사람이
+  알 수 있게 계속 봅니다.
+- 스킬 위치(`~/.claude/skills`, `~/.claude/plugins/cache/aiakiv/aiakiv/*/skills`, `~/.agents/skills`,
+  `~/.cursor/skills`, `~/.gemini/skills`, `$CODEX_HOME/skills`, 폴더의 `.claude/skills`, `.agents/skills`)를 봅니다.
+- bind 가 넣는 폴더 스킬 자리(`.claude/skills`, `.agents/skills`)에 일곱 개가 다 있는지 적습니다. 그 자리를 읽는
+  클라이언트가 이 폴더에 고정돼 있는데 빠진 스킬이 있으면 다음 단계에 bind 를 다시 하거나 칠 명령을 적습니다.
+- 폴더 `.mcp.json` 의 AiAkiv 항목마다 `.claude/settings.json`(또는 `.claude/settings.local.json`)의
+  `enabledMcpjsonServers` 에 그 이름이 있는지 적습니다.
+- 키로 묶인 항목은 MCP `get_save_target` 을 직접 불러 팀, 프로젝트, binding 을 적습니다
+  (`initialize`, `notifications/initialized`, `tools/call` 순서, 프로토콜 판 `2025-06-18`, 응답이 SSE 여도 읽음).
+  `--no-probe` 면 부르지 않습니다. OAuth 항목은 "클라이언트 안에서 get_save_target 을 부르라" 는 다음 단계를 적습니다.
+- 결과는 `aiakiv-verification-test.md`(기본은 그 폴더)에 씁니다. 키로 묶인 연결이 실패하면 종료 코드 1 입니다.
+
+## 키 평문을 내지 않는 원칙
+
+- 받은 키 평문은 **그 폴더의 설정 파일에만** 씁니다. 화면, 로그, 오류 문구, doctor 결과 파일에는 쓰지 않습니다
+  (키 id 만, doctor 는 앞 8자 + `…`).
+- CLI 는 토큰이나 키를 홈 폴더 같은 자기 저장소에 두지 않습니다. `login` 명령이 없습니다.
+- macOS, Linux 에서는 키가 든 설정 파일을 주인만 읽게(0600) 씁니다.
+- 키가 든 설정 파일은 git 저장소이거나 `.gitignore` 가 있는 폴더면 `.gitignore` 에 더하고, 아니면 경고합니다.
+  **키가 든 파일을 저장소에 올리지 마세요.**
+
+## TOML 주석 주의
+
+`.codex/config.toml` 에 **새 이름**을 더할 때는 파일 끝에 표 하나를 덧붙이고 다시 읽어 확인하므로 주석과 줄 모양이
+그대로 남습니다. **같은 이름의 항목을 바꿀 때**(또는 `mcp_servers` 를 인라인 표로 적어 덧붙일 수 없을 때)는
+파일을 읽어 고친 뒤 다시 쓰므로 **그 파일의 주석과 원래 줄 모양이 사라집니다**(값은 보존). 그렇게 됐을 때는
+화면에 알립니다.
+
+## 환경 변수
+
+| 이름 | 기본값 | 뜻 |
+|---|---|---|
+| `AIAKIV_MCP_URL` | `https://mcp.aiakiv.com/mcp` | MCP 주소. 끝의 `/mcp` 는 빼고 줘도 됩니다. |
+| `AIAKIV_CONTROL_URL` | `https://app.aiakiv.com` | 웹 콘솔 주소(인계 화면과 키 교환). |
+| `AIAKIV_SKILLS_TARBALL_URL` | `https://codeload.github.com/AiAkiv/aiakiv-plugins/tar.gz/refs/heads/main` | 폴더 스킬을 받는 tar.gz 주소(http 나 https). 시험은 로컬 서버로 바꿉니다. |
+| `CODEX_HOME` | `~/.codex` | Codex 설정 위치(플러그인 캐시, 스킬 확인에 씁니다). |
+
+## 개발
+
+```
+npm install
+npm run build    # tsc 가 dist/ 를 만듭니다
+npm test         # build 뒤 node --test (외부 시험 도구 없음)
+```
+
+의존성은 TOML 파서 `smol-toml` 하나입니다. 인자 해석은 `node:util` 의 `parseArgs`, HTTP 는 내장 `http` 와 `fetch`,
+폴더 스킬의 tar.gz 는 내장 `zlib` 와 작은 tar 읽기(`src/tar.ts`, ustar 와 pax 긴 이름),
+브라우저 열기는 운영체제 명령(Windows `cmd /c start`, macOS `open`, Linux `xdg-open`)을 씁니다.
+
+## 라이선스
+
+MIT

package/dist/bind.js

@@ -0,0 +1,273 @@
+// `aiakiv bind --client … --project <이름> [--dir <폴더>]` — 폴더에 프로젝트를 고정한다.
+//
+// - claude, cursor: `.mcp.json`, `.cursor/mcp.json` 에 `?project=` 주소(OAuth). 키를 받지 않으므로
+//   프로젝트 id 를 모른다. 서버 이름은 folderServerNameWithoutId(영문 19자 이내 이름은 콘솔과 같고,
+//   id 조각이 필요한 이름만 이름 해시로 대신한다). 같은 프로젝트 주소의 AiAkiv 항목이 이미 있으면
+//   그 이름을 그대로 쓴다(콘솔에서 복사해 둔 항목과 겹치지 않게).
+// - codex, gemini: 브라우저 인계(handoff.ts)로 프로젝트 키를 받아 `.codex/config.toml`,
+//   `.gemini/settings.json` 에 Bearer 로 쓴다. 평문은 그 파일에만 있다.
+//
+// 연결 설정 뒤에 웹 콘솔 "폴더 ZIP 받기" 와 같은 나머지를 더한다(정본 k2g-console-web
+// `src/lib/folderBundle.ts`):
+//   - 폴더 스킬(skills.ts). `--no-skills` 면 건너뛴다. 받기에 실패해도 bind 는 성공으로 끝난다.
+//   - claude: `.claude/settings.json` 의 enabledMcpjsonServers 에 서버 이름(폴더를 신뢰한 뒤 묻지 않고 켠다).
+//   - codex, gemini: 키가 든 설정 파일을 `.gitignore` 에 더한다(git 저장소이거나 `.gitignore` 가 있을 때).
+// ZIP 의 README.md 는 쓰지 않는다(안내는 화면에 낸다).
+import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { CLAUDE_FOLDER_SETTINGS, FOLDER_CONFIG } from "./clients/types.js";
+import { addToJsonArray, jsonServers, readJsonObject, upsertJsonServer } from "./config/json.js";
+import { upsertCodexServer } from "./config/toml.js";
+import { exchangeCode, handoffUrl, HANDOFF_TIMEOUT_MS, newState, startLoopback } from "./handoff.js";
+import { installFolderSkills } from "./skills.js";
+import { folderServerName, folderServerNameWithoutId, projectBinding } from "./snippet.js";
+import { canonicalMcpUrl, controlBase, mcpBase } from "./urls.js";
+function resolveDir(ctx, dir) {
+    const d = resolve(ctx.cwd, dir ?? ".");
+    if (!existsSync(d) || !statSync(d).isDirectory())
+        throw new Error(`폴더가 없습니다: ${d}`);
+    return d;
+}
+export async function runBind(ctx, opts) {
+    const project = opts.project;
+    if (!project.trim()) {
+        ctx.err("--project 에 프로젝트 이름을 주세요.");
+        return 2;
+    }
+    let dir;
+    try {
+        dir = resolveDir(ctx, opts.dir);
+    }
+    catch (e) {
+        ctx.err(e.message);
+        return 1;
+    }
+    try {
+        return opts.client === "claude" || opts.client === "cursor"
+            ? await bindOAuth(ctx, opts.client, project, dir, opts)
+            : await bindKey(ctx, opts.client, project, dir, opts);
+    }
+    catch (e) {
+        ctx.err(e.message);
+        return 1;
+    }
+}
+async function bindOAuth(ctx, client, project, dir, opts) {
+    const file = join(dir, FOLDER_CONFIG[client]);
+    const b = projectBinding("oauth", mcpBase(ctx.env), project, "");
+    const servers = jsonServers(readJsonObject(file));
+    const reuse = Object.entries(servers).find(([n, e]) => /^AiAkiv/.test(n) && e.url === b.url)?.[0];
+    let name;
+    if (reuse) {
+        name = reuse;
+        ctx.out(`같은 프로젝트를 가리키는 항목 ${name} 이 이미 있어 그 이름을 씁니다.`);
+    }
+    else {
+        const n = folderServerNameWithoutId(project);
+        name = n.name;
+        if (n.needsId) {
+            ctx.out("프로젝트 이름에 영문이 아닌 글자가 있거나 길어서, 서버 이름에 콘솔은 프로젝트 id 조각을 붙입니다.");
+            ctx.out(`CLI 는 id 를 모르므로 이름에서 만든 조각을 붙였습니다: ${name}`);
+            ctx.out("콘솔의 '이 프로젝트 MCP 설정' 과 같은 이름을 원하면 거기서 복사하세요. 동작에는 차이가 없습니다.");
+        }
+    }
+    const entry = { type: "http", url: b.url, ...(Object.keys(b.headers).length ? { headers: b.headers } : {}) };
+    const r = upsertJsonServer(file, name, entry);
+    ctx.out(`${r.replaced ? "바꿨습니다" : "더했습니다"}: ${file}`);
+    ctx.out(`  서버 이름 ${name}`);
+    ctx.out(`  주소 ${b.url}`);
+    if (r.backup)
+        ctx.out(`  참고: 원래 파일에 주석이나 끝 쉼표가 있어 표준 JSON 으로 다시 썼습니다. 원본은 ${r.backup} 에 남겼습니다.`);
+    ctx.out("이 폴더 고정은 OAuth 입니다. 키를 받지 않고, 프로젝트가 있는지도 여기서는 확인하지 않습니다.");
+    ctx.out("프로젝트가 없으면 도구를 부를 때 막히니 웹 콘솔에서 먼저 만들어 두세요.");
+    const enabled = client === "claude" ? enableClaudeFolderServer(ctx, dir, name) : false;
+    if (opts.skills !== false)
+        await installFolderSkills(ctx, client, dir);
+    else
+        ctx.out("폴더 스킬: --no-skills 라 건너뜁니다.");
+    ctx.out("다음 할 일(사람):");
+    if (client === "claude") {
+        ctx.out(enabled
+            ? "  - 그 폴더에서 claude 를 실행하고, 이 폴더를 신뢰하겠냐고 물으면 신뢰한다고 답하세요(이 서버는 미리 켜 두었습니다)."
+            : "  - 그 폴더에서 claude 를 실행하고, 이 폴더의 MCP 설정을 신뢰할지 물으면 승인하세요.");
+        ctx.out(`  - /mcp 에서 ${name} 을 골라 브라우저로 로그인하세요.`);
+    }
+    else {
+        ctx.out(`  - Cursor 로 그 폴더를 열고 MCP 설정에서 ${name} 을 켠 뒤 안내에 따라 로그인하세요.`);
+    }
+    ctx.out("  - 클라이언트 안에서 get_save_target 을 불러 binding 이 folder 인지 확인하세요.");
+    return 0;
+}
+/** `.claude/settings.json` 의 enabledMcpjsonServers 에 서버 이름을 더한다. 목록에 들어 있으면 true.
+ * 파일을 읽을 수 없으면 알리기만 하고 false(연결 설정은 이미 썼다). */
+function enableClaudeFolderServer(ctx, dir, name) {
+    const file = join(dir, CLAUDE_FOLDER_SETTINGS);
+    try {
+        const r = addToJsonArray(file, "enabledMcpjsonServers", name);
+        ctx.out(r.added ? `더했습니다: ${file}` : `그대로 둡니다: ${file}`);
+        ctx.out(`  enabledMcpjsonServers 에 ${name} ${r.added ? "을 더했습니다" : "이 이미 있습니다"}`);
+        if (r.backup)
+            ctx.out(`  참고: 원래 파일에 주석이나 끝 쉼표가 있어 표준 JSON 으로 다시 썼습니다. 원본은 ${r.backup} 에 남겼습니다.`);
+        return true;
+    }
+    catch (e) {
+        ctx.err(`${e.message}`);
+        ctx.err(`  ${file} 의 enabledMcpjsonServers 에 "${name}" 을 직접 더하거나, Claude Code 가 물을 때 승인하세요.`);
+        return false;
+    }
+}
+/** 키가 든 설정 파일이 git 에서 빠져 있는가와, 그 폴더가 git 저장소인가. 알 수 없으면 둘 다 false. */
+export async function gitIgnoreStatus(ctx, dir, rel) {
+    const git = ctx.which("git");
+    if (git) {
+        const r = await ctx.run(git, ["-C", dir, "check-ignore", "-q", rel], { timeoutMs: 15_000 });
+        if (r.code === 0)
+            return { ignored: true, repo: true };
+        if (r.code === 1)
+            return { ignored: false, repo: true };
+        // 128 = git 저장소가 아니다. 아래 단순 확인으로.
+    }
+    let repo = false;
+    for (let d = dir;; d = dirname(d)) {
+        if (existsSync(join(d, ".git"))) {
+            repo = true;
+            break;
+        }
+        if (dirname(d) === d)
+            break;
+    }
+    const gi = join(dir, ".gitignore");
+    if (!existsSync(gi))
+        return { ignored: false, repo };
+    const first = rel.split("/")[0];
+    const wanted = new Set([rel, `/${rel}`, first, `${first}/`, `/${first}`, `/${first}/`]);
+    const ignored = readFileSync(gi, "utf8")
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .some((l) => wanted.has(l));
+    return { ignored, repo };
+}
+/** 키가 든 파일을 그 폴더의 `.gitignore` 에 더한다(git 저장소이거나 `.gitignore` 가 이미 있을 때만).
+ * - "already": 이미 무시된다  - "added": `/<rel>` 줄을 더했다  - "warn": 더하지 않았다(사람에게 알린다) */
+export async function ensureGitIgnored(ctx, dir, rel) {
+    const st = await gitIgnoreStatus(ctx, dir, rel);
+    if (st.ignored)
+        return "already";
+    const gi = join(dir, ".gitignore");
+    const exists = existsSync(gi);
+    if (!st.repo && !exists)
+        return "warn";
+    const line = `/${rel}`;
+    const text = exists ? readFileSync(gi, "utf8") : "";
+    // 같은 줄이 있는데도 무시되지 않으면(뒤의 `!` 줄 등) 더해도 소용없다. 사람에게 넘긴다.
+    if (text.split(/\r?\n/).some((l) => l.trim() === line))
+        return "warn";
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const lead = text && !text.endsWith("\n") ? eol : "";
+    appendFileSync(gi, `${lead}${line}${eol}`, "utf8");
+    return "added";
+}
+function safeMcpUrl(ctx, given) {
+    if (typeof given === "string") {
+        try {
+            const u = new URL(given);
+            if (u.protocol === "https:" || u.protocol === "http:")
+                return given;
+        }
+        catch {
+            /* 아래 기본값 */
+        }
+    }
+    return canonicalMcpUrl(ctx.env);
+}
+async function bindKey(ctx, client, project, dir, opts) {
+    const control = controlBase(ctx.env);
+    const state = newState();
+    const lb = await startLoopback(state, opts.timeoutMs ?? HANDOFF_TIMEOUT_MS);
+    const url = handoffUrl(control, { project, port: lb.port, state, client, expiresDays: opts.expiresDays });
+    ctx.out(`웹 콘솔에서 프로젝트 ${project} 의 키를 이 PC 로 넘깁니다(프로젝트가 없으면 그 화면에서 만들 수 있습니다).`);
+    ctx.out("브라우저에서 로그인하고 확인 단추를 누르세요. 브라우저가 열리지 않으면 이 주소를 직접 여세요:");
+    ctx.out(`  ${url}`);
+    if (!opts.noBrowser) {
+        const opened = await ctx.openUrl(url);
+        if (!opened)
+            ctx.err("브라우저를 열지 못했습니다. 위 주소를 직접 여세요.");
+    }
+    ctx.out(`기다리는 중(최대 ${Math.round((opts.timeoutMs ?? HANDOFF_TIMEOUT_MS) / 60_000)}분, 127.0.0.1:${lb.port})...`);
+    let code;
+    try {
+        code = await lb.code;
+    }
+    catch (e) {
+        lb.close();
+        ctx.err(e.message);
+        ctx.err("명령을 다시 실행하세요.");
+        return 1;
+    }
+    const res = await exchangeCode(ctx.fetch, control, { code, state, port: lb.port });
+    const name = res.project_id
+        ? folderServerName(res.project, res.project_id)
+        : folderServerNameWithoutId(res.project).name;
+    const mcpUrl = safeMcpUrl(ctx, res.mcp_url);
+    const headers = { Authorization: `Bearer ${res.plaintext}` };
+    const rel = FOLDER_CONFIG[client];
+    const file = join(dir, rel);
+    let rewritten = false;
+    let backup;
+    let replaced;
+    if (client === "codex") {
+        const r = upsertCodexServer(file, name, mcpUrl, headers, { secret: true });
+        rewritten = r.rewritten;
+        replaced = r.replaced;
+    }
+    else {
+        const r = upsertJsonServer(file, name, { httpUrl: mcpUrl, headers }, { secret: true });
+        replaced = r.replaced;
+        backup = r.backup;
+    }
+    ctx.out();
+    ctx.out(`프로젝트 키를 받았습니다. 키 id ${res.key_id}`);
+    if (res.created_project)
+        ctx.out(`프로젝트 ${res.project} 를 새로 만들었습니다.`);
+    if (res.org_name)
+        ctx.out(`팀 ${res.org_name}`);
+    if (res.expires_at)
+        ctx.out(`만료 ${res.expires_at}`);
+    if (typeof res.superseded === "number" && res.superseded > 0) {
+        ctx.out(`이전 키 ${res.superseded}개를 폐기했습니다. 다른 폴더에 같은 프로젝트 키를 넣어 두었다면 그 폴더도 다시 bind 하세요.`);
+    }
+    ctx.out(`${replaced ? "바꿨습니다" : "더했습니다"}: ${file}`);
+    ctx.out(`  서버 이름 ${name}`);
+    ctx.out(`  주소 ${mcpUrl}`);
+    if (backup) {
+        ctx.out(`  참고: 원래 파일에 주석이나 끝 쉼표가 있어 표준 JSON 으로 다시 썼습니다. 원본은 ${backup} 에 남겼습니다. 원본에는 예전 키가 들어 있을 수 있으니 확인한 뒤 지우세요.`);
+    }
+    if (rewritten)
+        ctx.out("  참고: 같은 이름의 항목을 바꾸느라 파일을 다시 썼습니다. 이 파일에 있던 주석은 사라졌습니다.");
+    let ignore;
+    try {
+        ignore = await ensureGitIgnored(ctx, dir, rel);
+    }
+    catch (e) {
+        ctx.err(`.gitignore 를 고치지 못했습니다(${e.message}).`);
+        ignore = "warn";
+    }
+    if (ignore === "added")
+        ctx.out(`더했습니다: ${join(dir, ".gitignore")} 에 /${rel}`);
+    if (ignore === "warn") {
+        ctx.err(`주의: ${rel} 이 .gitignore 에 없습니다. 키가 든 파일이니 저장소에 올리지 마세요(.gitignore 에 /${rel} 을 더하세요).`);
+    }
+    if (opts.skills !== false)
+        await installFolderSkills(ctx, client, dir);
+    else
+        ctx.out("폴더 스킬: --no-skills 라 건너뜁니다.");
+    ctx.out("다음 할 일:");
+    if (client === "codex") {
+        ctx.out("  - 그 폴더에서 codex 를 실행하고, 이 폴더를 신뢰하겠냐고 물으면 신뢰한다고 답하세요. 앱은 다시 시작하세요.");
+    }
+    else {
+        ctx.out("  - 그 폴더에서 gemini 를 실행하세요.");
+    }
+    ctx.out(`  - 확인: npx aiakiv doctor --dir "${dir}"`);
+    return 0;
+}

package/dist/browser.js

@@ -0,0 +1,43 @@
+// 브라우저 열기. `open` 패키지 대신 운영체제 명령을 직접 부른다.
+//
+// Windows 는 `cmd /c start "" "<주소>"` 인데, 주소를 명령줄에 그대로 넣으면 cmd 가 `&` 를 명령
+// 구분자로, `%XX%` 를 환경 변수로 읽는다(프로젝트 이름은 퍼센트 인코딩돼 들어온다). 그래서 주소는
+// 환경 변수 AIAKIV_OPEN_URL 로 넘기고 명령줄에는 "%AIAKIV_OPEN_URL%" 만 적는다. cmd 는 변수를
+// 한 번만 펼치고 펼친 값 안의 `%` 는 다시 읽지 않으며, 큰따옴표 안의 `&` 는 글자로 둔다.
+import { spawn } from "node:child_process";
+/** 운영체제별 브라우저 열기 명령. `verb` 는 시험용(Windows 에서 start 대신 echo 로 바꿔 본다). */
+export function openCommand(url, platform, verb = 'start ""') {
+    if (platform === "win32") {
+        return {
+            file: "cmd.exe",
+            args: ["/d", "/c", `${verb} "%AIAKIV_OPEN_URL%"`],
+            env: { ...process.env, AIAKIV_OPEN_URL: url },
+            windowsVerbatimArguments: true,
+        };
+    }
+    if (platform === "darwin")
+        return { file: "open", args: [url] };
+    return { file: "xdg-open", args: [url] };
+}
+export function openUrl(url, platform) {
+    const c = openCommand(url, platform);
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(c.file, c.args, {
+                stdio: "ignore",
+                detached: platform !== "win32",
+                env: c.env ?? process.env,
+                windowsVerbatimArguments: c.windowsVerbatimArguments,
+                windowsHide: true,
+            });
+            child.on("error", () => resolve(false));
+            child.on("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { realCtx } from "./ctx.js";
+import { main } from "./main.js";
+main(process.argv.slice(2), realCtx()).then((code) => {
+    process.exitCode = code;
+}, (e) => {
+    process.stderr.write(`오류: ${e?.message ?? String(e)}\n`);
+    process.exitCode = 1;
+});

package/dist/clients/claude.js

@@ -0,0 +1,43 @@
+// Claude Code. doctor 가 전역 등록 목록을 읽는 데 쓴다(겹치는 연결을 사람에게 알리는 용도).
+// 확인한 명령: `claude mcp list`, `claude plugin list --json`.
+/** `claude mcp list` 의 `<이름>: <주소 또는 명령> - <상태>` 줄을 읽는다. */
+export function parseClaudeMcpList(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = /^(\S.*?): (\S.*) - (\S.*)$/.exec(line.trim());
+        if (m)
+            out.push({ name: m[1], target: m[2].replace(/\s+\((SSE|HTTP|stdio)\)$/i, ""), status: m[3] });
+    }
+    return out;
+}
+/** 연결 이름으로 종류를 가른다(binding 은 셋 다 main 이라 못 가른다). */
+export function classifyClaudeName(name) {
+    if (/^claude\.ai /.test(name))
+        return "account";
+    if (/^plugin:/.test(name))
+        return "plugin";
+    if (/^AiAkiv-/.test(name))
+        return "folder";
+    return "direct";
+}
+export const CLAUDE_KIND_LABEL = {
+    account: "claude.ai 계정 커넥터(Main 을 따라감)",
+    plugin: "플러그인 연결(Main 을 따라감)",
+    folder: "폴더 연결(프로젝트에 고정)",
+    direct: "직접 등록한 연결",
+};
+/** `claude plugin list --json` 에서 설치된 플러그인 id 들. JSON 이 아니면 글자로 찾는다. */
+export function installedPluginIds(text) {
+    try {
+        const v = JSON.parse(text);
+        if (Array.isArray(v))
+            return v.map((p) => String(p?.id ?? "")).filter(Boolean);
+    }
+    catch {
+        /* 아래 글자 찾기로 */
+    }
+    return [...text.matchAll(/❯\s+(\S+@\S+)/g)].map((m) => m[1]);
+}
+export function findClaude(ctx) {
+    return ctx.which("claude");
+}

package/dist/clients/codex.js

@@ -0,0 +1,56 @@
+// Codex(ChatGPT 앱의 CLI). doctor 가 전역 등록 목록(`codex mcp list --json`)을 읽는 데 쓴다.
+// codex 는 PATH 에 없을 수 있다. Windows 는 앱이 `%LOCALAPPDATA%\OpenAI\Codex\bin\<해시>\codex.exe` 에
+// 두므로 그 아래를 훑는다(해시 폴더 이름은 판마다 바뀌어 고정하지 않는다).
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+function subdirs(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => join(dir, d.name));
+    }
+    catch {
+        return [];
+    }
+}
+export function findCodex(ctx) {
+    const onPath = ctx.which("codex");
+    if (onPath)
+        return onPath;
+    if (ctx.platform !== "win32")
+        return null;
+    const local = ctx.env.LOCALAPPDATA ?? join(ctx.home, "AppData", "Local");
+    const found = subdirs(join(local, "OpenAI", "Codex", "bin"))
+        .map((d) => join(d, "codex.exe"))
+        .filter((p) => existsSync(p))
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    return found[0] ?? null;
+}
+export function codexHome(ctx) {
+    return ctx.env.CODEX_HOME?.trim() || join(ctx.home, ".codex");
+}
+/** `codex mcp list --json` 을 읽는다. JSON 이 아니면 표의 첫 열(이름)만. */
+export function parseCodexMcpList(text) {
+    try {
+        const v = JSON.parse(text);
+        if (Array.isArray(v)) {
+            return v.map((s) => ({
+                name: String(s?.name ?? ""),
+                url: typeof s?.transport?.url === "string" ? s.transport.url : undefined,
+                enabled: typeof s?.enabled === "boolean" ? s.enabled : undefined,
+            })).filter((s) => s.name);
+        }
+    }
+    catch {
+        /* 표로 */
+    }
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const cols = line.trim().split(/\s{2,}/);
+        if (!cols[0] || cols[0] === "Name")
+            continue;
+        const url = cols.find((c) => /^https?:\/\//.test(c));
+        out.push({ name: cols[0], url });
+    }
+    return out;
+}

package/dist/clients/cursor.js

@@ -0,0 +1,5 @@
+// Cursor. doctor 가 전역 설정 ~/.cursor/mcp.json 의 AiAkiv 항목을 읽는 데 쓴다.
+import { join } from "node:path";
+export function cursorGlobalConfig(ctx) {
+    return join(ctx.home, ".cursor", "mcp.json");
+}

package/dist/clients/types.js

@@ -0,0 +1,16 @@
+export const CLIENT_IDS = ["codex", "claude", "gemini", "cursor"];
+/** 폴더 고정 설정 파일(폴더 기준 상대 경로). */
+export const FOLDER_CONFIG = {
+    claude: ".mcp.json",
+    cursor: ".cursor/mcp.json",
+    codex: ".codex/config.toml",
+    gemini: ".gemini/settings.json",
+};
+/** Claude Code 가 폴더 `.mcp.json` 의 서버를 묻지 않고 켜는 목록(enabledMcpjsonServers)이 든 파일. */
+export const CLAUDE_FOLDER_SETTINGS = ".claude/settings.json";
+/** 같은 목록을 둘 수 있는 개인용 설정 파일(보통 git 에서 빠진다). doctor 는 둘 다 본다. */
+export const CLAUDE_FOLDER_SETTINGS_LOCAL = ".claude/settings.local.json";
+/** 이 연결이 AiAkiv 것인가 — 이름이나 주소로 가린다. */
+export function looksLikeAiAkiv(name, url, mcpBase) {
+    return /aiakiv/i.test(name) || /aiakiv/i.test(url ?? "") || (!!url && url.startsWith(mcpBase));
+}