aiakiv 0.2.0 → 0.2.2

package/dist/bind.js

@@ -93,7 +93,9 @@ async function bindOAuth(ctx, client, project, dir, opts) {
         ctx.out(`  - /mcp 에서 ${name} 을 골라 브라우저로 로그인하세요.`);
     }
     else {
-        ctx.out(`  - Cursor 로 그 폴더를 열고 MCP 설정에서 ${name} 을 켠 뒤 안내에 따라 로그인하세요.`);
+        ctx.out(`  - Cursor 로 그 폴더를 열고 설정(Ctrl+Shift+J)의 Tools & MCP 에서 ${name} 을 켠 뒤 안내에 따라 로그인하세요. ` +
+            "Cursor 는 폴더 서버를 켜기 전에는 연결하지 않습니다. 전역 AiAkiv 연결도 있으면 채팅에서 " +
+            `${name} 이라고 이름을 지목하세요.`);
     }
     ctx.out("  - 클라이언트 안에서 get_save_target 을 불러 binding 이 folder 인지 확인하세요.");
     return 0;

package/dist/dashboard.js

@@ -1,12 +1,15 @@
 // `aiakiv dashboard [--json] [--dir <폴더>]`(BP-171 §5.2) — 한 화면 요약.
 //
-// 읽기 액션 여섯(list_teams, list_projects, list_permissions, list_links, list_cards,
-// list_target_history limit 5)과 MCP get_save_target 한 번. 계정 키(.aiakiv/console.json)는 MCP 가
+// 읽기 액션 일곱(list_teams, list_projects, list_permissions, list_links, list_cards,
+// list_target_history limit 5, get_usage 인자 없음)과 MCP get_save_target 한 번. 계정 키(.aiakiv/console.json)는 MCP 가
 // 거절하므로 그 키로는 get_save_target 을 부르지 않는다(BP-171 §4.3). 그 폴더에 프로젝트 키(bind 가 쓴
 // codex, gemini 설정)가 따로 있으면 그 키로 부르고, 없으면 저장 대상 칸을 건너뛴다. 환경 변수 키는
 // 종류를 알 수 없어 그대로 부른다(계정 키면 그 칸에 MCP 의 거절 이유가 적힌다). 한 칸이 실패해도(권한 꺼짐, 카드 앱
 // 미등록, 403 등) 그 칸에 이유를 적고 나머지는 그린다. 401(키 문제), 404(입구 꺼짐), 연결 실패는
-// 다른 칸도 같은 결과이므로 거기서 멈춘다(여섯 번을 다 두드리지 않는다).
+// 다른 칸도 같은 결과이므로 거기서 멈춘다(일곱 번을 다 두드리지 않는다).
+//
+// 사용량 칸(BP-171 §5.5, P2c): get_usage 가 없는 옛 서버는 200 unknown_action 을 돌려준다. 그 칸에만
+// "서버가 아직 지원하지 않음" 을 적는다. usage_unavailable(서버가 상태를 읽지 못함)도 그 칸에서 끝난다.
 //
 // 개수: 응답에 전체 수(total)가 있으면 그것을 쓴다. 팀, 프로젝트, 연결, 권한 목록은 서버가 페이지를
 // 나누지 않고 전부 주므로(control list_orgs, list_projects, list_links, 권한 카탈로그) 받은 개수가
@@ -34,6 +37,45 @@ function countText(body, list, complete) {
         return `${n}개`;
     return `받은 ${n}개(더 있을 수 있음)`;
 }
+/** 정수부에 세 자리마다 쉼표(1000 → 1,000). 숫자가 아니면 undefined. */
+function num(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return undefined;
+    const [int, frac] = String(v).split(".");
+    return `${int.replace(/\B(?=(\d{3})+(?!\d))/g, ",")}${frac ? `.${frac}` : ""}`;
+}
+/** ISO 시각을 이 컴퓨터의 시각대로 `YYYY-MM-DD HH:MM`. 읽을 수 없으면 받은 글자 그대로. */
+function localTime(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+/** `used/limit`, 한도가 없으면 `used`. */
+const usedOf = (o) => `${num(o.used) ?? "?"}${num(o.limit) !== undefined ? `/${num(o.limit)}` : ""}`;
+/** get_usage 응답(BP-171 §5.5) → 한 줄. off 는 숫자가 null 이다. total 이 null 이면 총량을 뺀다. */
+function usageLines(b) {
+    if (b.mode === "off")
+        return ["한도 없음"];
+    const parts = [];
+    if (isObj(b.daily)) {
+        const d = b.daily;
+        const extra = [
+            num(d.remaining) !== undefined ? `남은 ${num(d.remaining)}` : "",
+            typeof d.resets_at === "string" && d.resets_at ? `초기화 ${localTime(d.resets_at)}` : "",
+        ].filter(Boolean);
+        parts.push(`오늘 ${usedOf(d)} 저장${extra.length ? `(${extra.join(", ")})` : ""}`);
+    }
+    if (isObj(b.total))
+        parts.push(`총량 ${usedOf(b.total)}`);
+    let line = parts.join(", ") || "응답에 사용량 숫자가 없습니다";
+    if (b.mode === "shadow")
+        line += " (한도를 적용하지 않는 관찰 모드)";
+    else if (b.mode !== "enforce")
+        line += ` (모드 ${s(b.mode) || "?"})`;
+    return [line];
+}
 const CELLS = [
     {
         field: "teams", title: "팀", action: "list_teams", data: {},
@@ -101,6 +143,19 @@ const CELLS = [
             return lines;
         },
     },
+    {
+        field: "usage", title: "사용량", action: "get_usage", data: {},
+        render: usageLines,
+        failure: (o) => {
+            if (o.exit !== EXIT.APP_ERROR)
+                return undefined;
+            if (o.error?.code === "unknown_action")
+                return ["서버가 아직 지원하지 않음"];
+            if (o.error?.code === "usage_unavailable")
+                return ["지금 사용량을 읽을 수 없습니다(usage_unavailable). 잠시 뒤 다시 보세요."];
+            return undefined;
+        },
+    },
 ];
 /** 일찍 멈출 결과: 키 문제(401), 입구 꺼짐(404), 연결 실패. 다른 칸도 같다. */
 function stopsAll(r, o) {
@@ -188,7 +243,7 @@ export async function runDashboard(ctx, opts) {
         if (o.exit === EXIT.OK && isObj(r.body))
             row(cell.title, cell.render(r.body));
         else
-            row(cell.title, cellFailure(o));
+            row(cell.title, cell.failure?.(o) ?? cellFailure(o));
     }
     if (!anyOk) {
         ctx.err("모든 칸이 실패했습니다.");

package/dist/local/checks.js

@@ -0,0 +1,495 @@
+// `aiakiv local doctor` 의 점검 판정(docs/211 §17.4). 판정 함수는 받은 값만 보고 결과를 낸다.
+// 바깥 세계(실행기, fetch, 환경 변수)는 Ctx 로, Node 판과 OS, 디스크, 포트 묶기는 LocalHost 로만 만난다.
+// 시험은 둘 다 가짜로 넣는다.
+//
+// 문턱값의 GB 는 10^9 바이트다. Docker 가 알리는 MemTotal 은 커널이 잡아 둔 몫을 빼고 나와서, 설정에서
+// 4GB 를 준 컴퓨터가 2^30 기준으로는 4GB 미만으로 보이기 때문이다.
+import { existsSync, promises as fsp } from "node:fs";
+import { createServer } from "node:net";
+import { cpus, networkInterfaces, release, totalmem } from "node:os";
+import { posix, win32 } from "node:path";
+export const GB = 1e9;
+export const pass = (detail) => ({ status: "pass", detail });
+export const warn = (detail, fix = null) => ({ status: "warn", detail, fix });
+export const fail = (detail, fix = null) => ({ status: "fail", detail, fix });
+export const skip = (detail) => ({ status: "skip", detail });
+export const info = (detail, fix = null) => ({ status: "info", detail, fix });
+function bindOnce(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (e) => resolve({ ok: false, code: e.code, message: e.message }));
+        server.listen(port, "127.0.0.1", () => server.close(() => resolve({ ok: true })));
+    });
+}
+export function realHost() {
+    const statfs = fsp.statfs;
+    return {
+        nodeVersion: process.versions.node,
+        arch: process.arch,
+        osRelease: release(),
+        cpus: cpus().length,
+        memBytes: totalmem(),
+        interfaces: () => networkInterfaces(),
+        statfs: typeof statfs === "function" ? (p) => statfs(p) : null,
+        exists: (p) => existsSync(p),
+        tryBind: bindOnce,
+    };
+}
+/** "27.3.1", "v2.29.1-desktop.1", "20.10.24+dfsg1" 에서 [주, 부]. 못 읽으면 null. */
+export function majorMinor(v) {
+    const m = /(\d+)\.(\d+)/.exec(v ?? "");
+    return m ? [Number(m[1]), Number(m[2])] : null;
+}
+const below = (v, major, minor) => v[0] < major || (v[0] === major && v[1] < minor);
+export const gbText = (bytes) => `${(bytes / GB).toFixed(1)}GB`;
+// ---- Node, OS -------------------------------------------------------------------------------
+export function checkNodeVersion(version) {
+    const v = majorMinor(version);
+    if (!v)
+        return fail(`Node 판을 읽지 못했습니다(${version})`, "Node.js LTS 판을 설치하세요(https://nodejs.org).");
+    if (below(v, 18, 3))
+        return fail(`Node ${version} 은 18.3 보다 낮습니다`, "Node.js LTS 판을 설치하세요(https://nodejs.org).");
+    return pass(`Node ${version}`);
+}
+const WINDOWS_22H2_BUILD = 19045;
+const WINDOWS_11_BUILD = 22000;
+export function checkOs(platform, hostArch, osRelease) {
+    const archOk = hostArch === "x64" || hostArch === "arm64";
+    const unsupported = "Linux, macOS, Windows 10 22H2 이상 또는 Windows 11 의 x64, arm64 컴퓨터에서 설치하세요.";
+    if (platform === "linux" || platform === "darwin") {
+        const name = platform === "linux" ? "Linux" : "macOS";
+        if (!archOk)
+            return fail(`${name} ${hostArch} 는 지원하지 않습니다(x64, arm64 만)`, unsupported);
+        return pass(`${name} ${osRelease} ${hostArch}`);
+    }
+    if (platform === "win32") {
+        const m = /^(\d+)\.(\d+)\.(\d+)/.exec(osRelease);
+        if (!m || Number(m[1]) < 10)
+            return fail(`Windows ${osRelease} 는 지원하지 않습니다`, unsupported);
+        if (!archOk)
+            return fail(`Windows ${hostArch} 는 지원하지 않습니다(x64, arm64 만)`, unsupported);
+        const build = Number(m[3]);
+        if (build >= WINDOWS_11_BUILD)
+            return pass(`Windows 11(빌드 ${build}) ${hostArch}`);
+        if (build >= WINDOWS_22H2_BUILD)
+            return pass(`Windows 10 22H2(빌드 ${build}) ${hostArch}`);
+        return warn(`Windows 10 빌드 ${build} 는 22H2(빌드 ${WINDOWS_22H2_BUILD}) 보다 오래됐습니다`, "Windows 업데이트로 Windows 10 22H2 이상으로 올리세요.");
+    }
+    return fail(`${platform} 는 지원하지 않습니다`, unsupported);
+}
+// ---- Docker ---------------------------------------------------------------------------------
+export function dockerInstallUrl(platform) {
+    if (platform === "win32")
+        return "https://docs.docker.com/desktop/setup/install/windows-install/";
+    if (platform === "darwin")
+        return "https://docs.docker.com/desktop/setup/install/mac-install/";
+    return "https://docs.docker.com/engine/install/";
+}
+const str = (v) => (typeof v === "string" && v ? v : undefined);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+/** `docker info --format "{{json .}}"` 의 출력. 데몬에 닿지 못하면 info 없이 errors 만(ServerErrors 나 JSON 아님). */
+export function parseDockerInfo(stdout) {
+    const line = stdout.split(/\r?\n/).map((l) => l.trim()).find((l) => l.startsWith("{"));
+    if (!line)
+        return { info: null, errors: [] };
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        return { info: null, errors: [] };
+    }
+    const errors = Array.isArray(raw.ServerErrors) ? raw.ServerErrors.map(String).filter(Boolean) : [];
+    const serverVersion = str(raw.ServerVersion);
+    if (!serverVersion || errors.length)
+        return { info: null, errors };
+    return {
+        info: {
+            serverVersion,
+            osType: str(raw.OSType),
+            architecture: str(raw.Architecture),
+            memTotal: num(raw.MemTotal),
+            ncpu: num(raw.NCPU),
+            operatingSystem: str(raw.OperatingSystem),
+            kernelVersion: str(raw.KernelVersion),
+            dockerRootDir: str(raw.DockerRootDir),
+            httpProxy: str(raw.HttpProxy),
+            httpsProxy: str(raw.HttpsProxy),
+            noProxy: str(raw.NoProxy),
+        },
+        errors,
+    };
+}
+export function isPermissionDenied(text) {
+    return /permission denied/i.test(text);
+}
+export function daemonFix(platform, permissionDenied) {
+    if (platform === "linux" && permissionDenied) {
+        return "지금 사용자를 docker 그룹에 넣고(sudo usermod -aG docker $USER) 로그아웃했다가 다시 로그인하세요.";
+    }
+    if (platform === "linux")
+        return "Docker 를 켜세요(sudo systemctl start docker).";
+    return "Docker Desktop 을 켜고, 고래 아이콘이 움직임을 멈출 때까지 기다린 뒤 다시 점검하세요.";
+}
+export function checkDockerVersion(v) {
+    const mm = majorMinor(v);
+    const fix = "Docker 를 새 판으로 올리세요(Docker Engine 24 이상 또는 최신 Docker Desktop).";
+    if (!mm)
+        return warn(`Docker 서버 판을 읽지 못했습니다(${v})`, fix);
+    if (below(mm, 20, 10))
+        return fail(`Docker 서버 ${v} 는 20.10 보다 낮습니다`, fix);
+    if (mm[0] < 24)
+        return warn(`Docker 서버 ${v} 는 24 보다 낮습니다`, fix);
+    return pass(`Docker 서버 ${v}`);
+}
+/** `docker compose version --short` 결과(실패면 null)와 옛 docker-compose 실행 파일이 있는지. */
+export function checkCompose(short, hasV1, platform) {
+    const fix = platform === "linux"
+        ? "compose 플러그인을 설치하세요(배포판 꾸러미 docker-compose-v2 또는 docker-compose-plugin)."
+        : "Docker Desktop 을 새 판으로 올리세요(compose v2 가 함께 들어 있습니다).";
+    if (short === null) {
+        if (hasV1)
+            return fail("옛 docker-compose(v1) 만 있고 docker compose(v2) 가 없습니다", fix);
+        return fail("docker compose(v2) 가 없습니다", fix);
+    }
+    const v = short.trim().replace(/^v/, "");
+    const mm = majorMinor(v);
+    if (!mm)
+        return warn(`compose 판을 읽지 못했습니다(${short.trim()})`, fix);
+    if (mm[0] < 2)
+        return fail(`compose ${v} 는 v2 가 아닙니다`, fix);
+    if (below(mm, 2, 20))
+        return warn(`compose ${v} 는 2.20 보다 낮습니다`, fix);
+    return pass(`compose ${v}`);
+}
+export function checkDockerOs(osType) {
+    if (osType === "linux")
+        return pass("리눅스 컨테이너 모드");
+    if (osType === "windows") {
+        return fail("Docker 가 Windows 컨테이너 모드입니다", "작업 표시줄의 Docker 아이콘을 오른쪽 클릭해 Switch to Linux containers 를 고르세요.");
+    }
+    return fail(`Docker 컨테이너 종류를 알 수 없습니다(${osType ?? "없음"})`, "리눅스 컨테이너 모드로 바꾸세요.");
+}
+/** Docker 의 Architecture 와 process.arch 를 같은 이름(amd64, arm64)으로. 모르면 null. */
+export function normArch(a) {
+    const v = (a ?? "").toLowerCase();
+    if (v === "x86_64" || v === "amd64" || v === "x64")
+        return "amd64";
+    if (v === "aarch64" || v === "arm64")
+        return "arm64";
+    return null;
+}
+export function checkDockerArch(dockerArch, hostArch) {
+    const d = normArch(dockerArch);
+    if (!d)
+        return fail(`Docker 아키텍처 ${dockerArch ?? "없음"} 는 지원하지 않습니다(amd64, arm64 만)`, "amd64 또는 arm64 컴퓨터에서 설치하세요.");
+    const h = normArch(hostArch);
+    if (h && h !== d) {
+        return warn(`Docker 는 ${d}, 이 컴퓨터는 ${h} 입니다(에뮬레이션이라 임베딩이 느립니다)`, "이 컴퓨터의 아키텍처와 같은 Docker 를 설치하세요.");
+    }
+    return pass(`Docker ${dockerArch}(${d})`);
+}
+export function checkWsl2(kernelVersion, operatingSystem) {
+    const k = kernelVersion ?? "";
+    if (/wsl2/i.test(k))
+        return pass(`WSL2 백엔드(커널 ${k})`);
+    return warn(`WSL2 백엔드가 아닌 것으로 보입니다(커널 ${k || "알 수 없음"}${operatingSystem ? `, ${operatingSystem}` : ""})`, "Docker Desktop 의 Settings > General 에서 Use the WSL 2 based engine 을 켜세요.");
+}
+export function checkDockerMem(memTotal, platform, isDesktop) {
+    if (memTotal === undefined)
+        return warn("Docker 가 쓸 수 있는 메모리를 알 수 없습니다");
+    let fix;
+    if (platform === "win32") {
+        fix =
+            "Docker Desktop 의 Settings > Resources 에서 메모리를 6GB 이상으로 올리세요. WSL2 백엔드면 " +
+                "%UserProfile%\\.wslconfig 의 [wsl2] 아래 memory=6GB 로 적고 wsl --shutdown 뒤 Docker Desktop 을 다시 켜세요.";
+    }
+    else if (isDesktop || platform === "darwin") {
+        fix = "Docker Desktop 의 Settings > Resources > Memory 를 6GB 이상으로 올리세요.";
+    }
+    else {
+        fix = "메모리가 더 많은 컴퓨터를 쓰세요(Docker Engine 은 컴퓨터 메모리를 그대로 씁니다).";
+    }
+    if (memTotal < 4 * GB)
+        return fail(`Docker 메모리 ${gbText(memTotal)} 는 4GB 보다 적습니다`, fix);
+    if (memTotal < 6 * GB)
+        return warn(`Docker 메모리 ${gbText(memTotal)} 는 6GB 보다 적습니다`, fix);
+    return pass(`Docker 메모리 ${gbText(memTotal)}`);
+}
+export function checkDockerCpus(ncpu, isDesktop) {
+    if (ncpu === undefined)
+        return warn("Docker 가 쓸 수 있는 CPU 수를 알 수 없습니다");
+    const fix = isDesktop
+        ? "Docker Desktop 의 Settings > Resources 에서 CPU 를 4개 이상으로 올리세요."
+        : "CPU 가 더 많은 컴퓨터를 쓰세요.";
+    if (ncpu < 2)
+        return fail(`Docker CPU ${ncpu}개는 2개보다 적습니다`, fix);
+    if (ncpu < 4)
+        return warn(`Docker CPU ${ncpu}개는 4개보다 적습니다`, fix);
+    return pass(`Docker CPU ${ncpu}개`);
+}
+export function isDockerDesktop(info) {
+    return /docker desktop/i.test(info?.operatingSystem ?? "");
+}
+export function checkDesktopLicense(d) {
+    if (isDockerDesktop(d)) {
+        return info(`Docker Desktop 입니다(${d.operatingSystem})`, "직원 250명 이상이거나 연매출 1천만 달러 이상인 회사는 Docker 유료 구독이 필요합니다.");
+    }
+    return info(`Docker Desktop 이 아닙니다(${d.operatingSystem ?? "알 수 없음"}). 구독 조건과 관계없습니다`);
+}
+/** 여유 공간을 볼 경로 후보. 앞에서부터 있는 것을 쓴다. 마지막은 늘 홈 폴더(또는 그 드라이브). */
+export function diskCandidates(platform, home, env, info) {
+    if (platform === "win32") {
+        const out = [];
+        const lad = env.LOCALAPPDATA ?? env.LocalAppData;
+        if (lad) {
+            out.push({ path: win32.join(lad, "Docker", "wsl"), label: "Docker Desktop 데이터 폴더" });
+            const drive = /^[A-Za-z]:/.exec(lad)?.[0];
+            if (drive)
+                out.push({ path: `${drive}\\`, label: `Docker Desktop 데이터가 있는 ${drive} 드라이브` });
+        }
+        out.push({ path: home, label: "홈 폴더" });
+        return out;
+    }
+    if (platform === "darwin") {
+        return [
+            { path: posix.join(home, "Library", "Containers", "com.docker.docker", "Data"), label: "Docker Desktop 데이터 폴더" },
+            { path: posix.join(home, ".orbstack"), label: "OrbStack 데이터 폴더" },
+            { path: home, label: "홈 폴더" },
+        ];
+    }
+    const root = info?.dockerRootDir ?? "/var/lib/docker";
+    return [
+        { path: root, label: info?.dockerRootDir ? "Docker 데이터 폴더(DockerRootDir)" : "Docker 기본 데이터 폴더" },
+        { path: home, label: "홈 폴더" },
+    ];
+}
+/** `df -Pk <경로>` 출력에서 쓸 수 있는 바이트(Available 칸, 1K 블록). 못 읽으면 null. */
+export function parseDfAvailable(stdout) {
+    const lines = stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    for (const l of lines.slice(1).reverse()) {
+        const m = /\s(\d+)\s+(\d+)\s+(\d+)\s+(\d+)%\s+\S.*$/.exec(` ${l}`);
+        if (m)
+            return Number(m[3]) * 1024;
+    }
+    return null;
+}
+/** PowerShell `(Get-PSDrive …).Free` 의 출력(바이트 숫자 한 줄). */
+export function parsePsFree(stdout) {
+    const m = /^\s*(\d+)\s*$/m.exec(stdout);
+    return m ? Number(m[1]) : null;
+}
+export function checkDiskFree(bytes, where) {
+    const fix = "디스크 공간을 비우거나 Docker 데이터 위치를 여유가 있는 디스크로 옮기세요.";
+    if (bytes < 10 * GB)
+        return fail(`${where} 의 여유 공간 ${gbText(bytes)} 는 10GB 보다 적습니다`, fix);
+    if (bytes < 20 * GB)
+        return warn(`${where} 의 여유 공간 ${gbText(bytes)} 는 20GB 보다 적습니다`, fix);
+    return pass(`${where} 의 여유 공간 ${gbText(bytes)}`);
+}
+/** AiAkiv 엔진(k2g-mcp)의 /health 로 보이는가: status 가 글자이고 엔진만 내는 칸이 하나 이상 있다. */
+export function looksLikeEngineHealth(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return false;
+    const b = body;
+    return typeof b.status === "string" && ("edition" in b || "engine_version" in b || "first_bootstrap" in b);
+}
+export const FREE_EDITION = "self-hosted-free";
+export function checkEngineHealth(h) {
+    if (h.status === "ok")
+        return pass("엔진 /health 의 status 가 ok 입니다");
+    return fail(`엔진 /health 의 status 가 ${String(h.status)} 입니다`, "엔진 로그를 보세요(~/.aiakiv/engine 에서 docker compose -f aiakiv-compose.yml logs engine).");
+}
+export function checkEngineEdition(h) {
+    if (h.edition === FREE_EDITION)
+        return pass(`판 이름 ${FREE_EDITION}`);
+    return fail(`이 포트의 엔진은 무료 엔진이 아닙니다(edition ${h.edition === undefined ? "없음" : String(h.edition)})`, "이 포트를 쓰는 프로그램을 확인하거나 --port 로 무료 엔진의 포트를 주세요.");
+}
+export function checkEngineVersion(h) {
+    const v = h.engine_version;
+    return info(`엔진 판 ${typeof v === "string" && v ? v : "알 수 없음"}`);
+}
+/** `docker ps --format "{{.Image}}\t{{.Names}}\t{{.Ports}}"` 출력. */
+export function parseDockerPs(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .filter((l) => l.trim())
+        .map((l) => {
+        const [image = "", names = "", ports = ""] = l.split("\t");
+        return { image: image.trim(), names: names.trim(), ports: ports.trim() };
+    });
+}
+export function isEngineContainer(r) {
+    return /(^|\/)aiakiv\/engine(:|@|$)/i.test(r.image);
+}
+/** Ports 칸(`127.0.0.1:7777->7777/tcp, [::]:7777->7777/tcp`)에서 그 호스트 포트가 묶인 주소들. */
+export function hostAddrsForPort(ports, port) {
+    const out = [];
+    for (const piece of ports.split(",").map((p) => p.trim()).filter(Boolean)) {
+        const m = /^(.*):(\d+)(?:-(\d+))?->/.exec(piece);
+        if (!m)
+            continue;
+        const lo = Number(m[2]);
+        const hi = m[3] ? Number(m[3]) : lo;
+        if (port < lo || port > hi)
+            continue;
+        out.push(m[1].replace(/^\[|\]$/g, "") || "::");
+    }
+    return out;
+}
+/** 사설 또는 공인 인터넷에서 닿지 않는 IPv4 대역(사설, 루프백, 링크 로컬, 통신사 공유 대역). */
+export function isPrivateV4(a) {
+    const p = a.split(".").map(Number);
+    if (p.length !== 4 || p.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return false;
+    const [x, y] = p;
+    return (x === 10 || x === 127 || x === 0 ||
+        (x === 172 && y >= 16 && y <= 31) ||
+        (x === 192 && y === 168) ||
+        (x === 169 && y === 254) ||
+        (x === 100 && y >= 64 && y <= 127));
+}
+const isV4 = (a) => /^\d+\.\d+\.\d+\.\d+$/.test(a);
+const isLoopback = (a) => a === "::1" || a === "localhost" || (isV4(a) && a.startsWith("127."));
+/** 이 컴퓨터의 공인 IPv4(내부가 아니고 사설 대역 밖). */
+export function publicIPv4s(ifaces) {
+    const out = [];
+    for (const list of Object.values(ifaces)) {
+        for (const a of list ?? []) {
+            const v4 = a.family === "IPv4" || a.family === 4;
+            if (v4 && !a.internal && !isPrivateV4(a.address) && !out.includes(a.address))
+                out.push(a.address);
+        }
+    }
+    return out;
+}
+export function checkEngineBind(addrs, port, publicV4) {
+    const fixClose = "다른 컴퓨터에서 쓰지 않는다면 ~/.aiakiv/engine/.env 의 AIAKIV_BIND 를 127.0.0.1 로 바꾸고 " +
+        "그 폴더에서 docker compose -f aiakiv-compose.yml up -d 로 다시 올리세요.";
+    if (addrs.every(isLoopback))
+        return pass(`${addrs.join(", ")}:${port} 에만 묶여 있습니다`);
+    const exposed = [];
+    let worst = "warn";
+    for (const a of addrs) {
+        if (isLoopback(a))
+            continue;
+        if (a === "0.0.0.0" || a === "::") {
+            if (publicV4.length) {
+                worst = "fail";
+                exposed.push(`${a}(모든 주소, 이 컴퓨터의 공인 주소 ${publicV4.join(", ")} 포함)`);
+            }
+            else
+                exposed.push(`${a}(모든 주소, 공인 주소는 없음)`);
+        }
+        else if (isV4(a) && !isPrivateV4(a)) {
+            worst = "fail";
+            exposed.push(`${a}(공인 주소)`);
+        }
+        else
+            exposed.push(`${a}(사설 대역)`);
+    }
+    if (worst === "fail") {
+        return fail(`포트 ${port} 가 공인 주소에 열려 있습니다: ${exposed.join(", ")}`, fixClose);
+    }
+    return warn(`포트 ${port} 가 이 컴퓨터 밖(사설망)에 열려 있습니다: ${exposed.join(", ")}`, fixClose);
+}
+// ---- 네트워크 -------------------------------------------------------------------------------
+const PROXY_VARS = ["HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY", "NO_PROXY"];
+/** 주소의 사용자 이름과 비밀번호를 가린다. */
+export function maskProxy(v) {
+    return v.replace(/\/\/[^@/\s]*@/, "//…@");
+}
+/** 설정된 프록시 환경 변수(대소문자 둘 다). NO_PROXY 는 있는지만 알 때 쓰도록 따로 표시한다. */
+export function envProxies(env) {
+    const out = [];
+    for (const base of PROXY_VARS) {
+        for (const name of [base, base.toLowerCase()]) {
+            const v = env[name];
+            if (v && !out.some((o) => o.name.toUpperCase() === base))
+                out.push({ name, value: maskProxy(v) });
+        }
+    }
+    return out;
+}
+export function hasProxyEnv(env) {
+    return envProxies(env).some((p) => p.name.toUpperCase() !== "NO_PROXY");
+}
+/** Docker Desktop 이 늘 알리는 안쪽 중계(http.docker.internal)는 회사 프록시가 아니다. */
+export function isDesktopInternalProxy(v) {
+    return /(^|\/\/)http\.docker\.internal(:\d+)?\/?$/i.test(v.trim());
+}
+export function checkProxy(env, d) {
+    const envList = envProxies(env);
+    const dockerList = [
+        ["HttpProxy", d?.httpProxy],
+        ["HttpsProxy", d?.httpsProxy],
+        ["NoProxy", d?.noProxy],
+    ].filter((x) => !!x[1]);
+    const dockerReal = dockerList.filter(([k, v]) => k === "NoProxy" || !isDesktopInternalProxy(v));
+    const internal = dockerList.length > 0 && dockerList.some(([k, v]) => k !== "NoProxy" && isDesktopInternalProxy(v));
+    const parts = [];
+    parts.push(envList.length ? `환경 변수 ${envList.map((p) => `${p.name}=${p.value}`).join(", ")}` : "프록시 환경 변수 없음");
+    if (!d)
+        parts.push("Docker 설정은 보지 못함");
+    else if (dockerReal.some(([k]) => k !== "NoProxy")) {
+        parts.push(`Docker ${dockerReal.map(([k, v]) => `${k}=${maskProxy(v)}`).join(", ")}`);
+    }
+    else
+        parts.push(internal ? "Docker 는 Docker Desktop 안쪽 중계(http.docker.internal)만 씀" : "Docker 프록시 없음");
+    const anyProxy = hasProxyEnv(env) || dockerReal.some(([k]) => k !== "NoProxy");
+    return info(parts.join("; "), anyProxy
+        ? "회사 프록시를 쓰면 Docker 에도 같은 프록시를 설정하고, TLS 를 검사하는 프록시면 회사 인증서를 Docker 에 등록하세요."
+        : null);
+}
+export const NET_TARGETS = [
+    {
+        id: "net.docker_registry",
+        url: "https://registry-1.docker.io/v2/",
+        what: "Docker Hub",
+        fix: "Postgres 이미지를 받을 수 없으니 다른 컴퓨터에서 받아 옮기는 오프라인 설치(--image-tar)를 쓰세요.",
+    },
+    {
+        id: "net.aiakiv",
+        url: "https://www.aiakiv.com/",
+        what: "www.aiakiv.com",
+        fix: "로그인과 엔진 내려받기가 안 되니 인터넷이 되는 다른 컴퓨터에서 받아 옮기세요.",
+    },
+    {
+        id: "net.npm",
+        url: "https://registry.npmjs.org/",
+        what: "npm 저장소(registry.npmjs.org)",
+        fix: "npm 패키지를 받을 수 없으니 다른 컴퓨터에서 패키지 tgz 를 받아 옮기세요.",
+    },
+];
+export const NET_TIMEOUT_MS = 10000;
+/** 응답이 오면(상태 코드와 관계없이) 닿은 것. 시간 초과나 연결 실패면 이유 한 줄. */
+export async function reach(doFetch, url, timeoutMs) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const res = await doFetch(url, { method: "GET", redirect: "manual", signal: ac.signal });
+        try {
+            await res.body?.cancel();
+        }
+        catch {
+            /* 본문은 읽지 않는다 */
+        }
+        return { ok: true, status: res.status };
+    }
+    catch (e) {
+        const err = e;
+        if (err.name === "AbortError" || ac.signal.aborted) {
+            return { ok: false, reason: `${Math.round(timeoutMs / 1000)}초 안에 응답이 없음` };
+        }
+        return { ok: false, reason: err.cause?.code ?? err.cause?.message ?? err.message };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function netVerdict(r, what, fix, proxyEnv) {
+    const note = proxyEnv ? " (프록시 환경 변수가 있지만 직접 연결로만 시험함)" : "";
+    if (r.ok)
+        return pass(`${what} 에 닿음(HTTP ${r.status})${note}`);
+    return warn(`${what} 에 닿지 않음: ${r.reason}${note}`, fix);
+}

package/dist/local/doctor.js

@@ -0,0 +1,329 @@
+// `aiakiv local doctor [--json] [--out <파일.md>] [--port <n>] [--offline]` — 자체 설치판(무료 5인 엔진)을
+// 깔기 전에 이 컴퓨터를 점검한다(docs/211 §17.2 ~ §17.4). 엔진이 떠 있으면(그 포트의 /health 가 엔진처럼
+// 응답하면) 상태, 판 이름, 판, 포트가 묶인 주소도 본다. 보고서는 §17.3 형식이고 tool 은 aiakiv-local-doctor.
+// 호스티드 연결을 보는 `aiakiv doctor`(../doctor.ts)와는 별개다.
+//
+// 종료 코드: 0 fail 없음, 3 fail 있음, 4 docker 실행 파일이나 데몬에 닿지 못함(이때도 보고서는 낸다),
+// 1 보고서 파일을 쓰지 못함. 인자 오류(2)는 main.ts 가 낸다.
+// 비밀 값은 다루지 않는다. 프록시 주소의 사용자 이름과 비밀번호는 가린다.
+import { writeFileSync } from "node:fs";
+import { posix, resolve, win32 } from "node:path";
+import { performance } from "node:perf_hooks";
+import { failReason } from "../proc.js";
+import { table } from "../render.js";
+import { VERSION } from "../version.js";
+import { checkCompose, checkDesktopLicense, checkDiskFree, checkDockerArch, checkDockerCpus, checkDockerMem, checkDockerOs, checkDockerVersion, checkEngineBind, checkEngineEdition, checkEngineHealth, checkEngineVersion, checkNodeVersion, checkOs, checkProxy, checkWsl2, daemonFix, diskCandidates, dockerInstallUrl, fail, hasProxyEnv, hostAddrsForPort, info, isDockerDesktop, isEngineContainer, isPermissionDenied, looksLikeEngineHealth, NET_TARGETS, NET_TIMEOUT_MS, netVerdict, parseDfAvailable, parseDockerInfo, parseDockerPs, parsePsFree, pass, publicIPv4s, reach, skip, gbText, } from "./checks.js";
+export const DEFAULT_ENGINE_PORT = 7777;
+export const LOCAL_DOCTOR_TOOL = "aiakiv-local-doctor";
+const DOCKER_TIMEOUT_MS = 30_000;
+const HEALTH_TIMEOUT_MS = 3_000;
+export const STATUS_LABEL = {
+    pass: "통과",
+    warn: "주의",
+    fail: "실패",
+    skip: "건너뜀",
+    info: "알림",
+};
+/** 긴 오류 출력에서 첫 줄만, 너무 길면 자른다. */
+function oneLine(s, max = 200) {
+    const l = s.trim().split(/\r?\n/).find((x) => x.trim()) ?? "";
+    return l.length > max ? `${l.slice(0, max - 1)}…` : l;
+}
+/** 경로의 여유 공간. statfs 가 있으면 그것, 없거나 실패하면 Windows 는 PowerShell, 그 밖은 `df -Pk`. */
+async function freeBytes(ctx, host, path) {
+    let statfsWhy = "";
+    if (host.statfs) {
+        try {
+            const s = await host.statfs(path);
+            return { bytes: Number(s.bavail) * Number(s.bsize) };
+        }
+        catch (e) {
+            const err = e;
+            statfsWhy = `statfs ${err.code ?? err.message}; `;
+        }
+    }
+    if (ctx.platform === "win32") {
+        const drive = /^([A-Za-z]):/.exec(path)?.[1];
+        if (!drive)
+            return { bytes: null, reason: `${statfsWhy}드라이브를 알 수 없음` };
+        const ps = ctx.which("powershell") ?? "powershell.exe";
+        const r = await ctx.run(ps, ["-NoProfile", "-NonInteractive", "-Command", `(Get-PSDrive -Name ${drive} -PSProvider FileSystem).Free`], { capture: true, timeoutMs: 20_000 });
+        const b = r.ok ? parsePsFree(r.stdout) : null;
+        return b === null ? { bytes: null, reason: `${statfsWhy}PowerShell ${oneLine(failReason(r))}` } : { bytes: b };
+    }
+    const r = await ctx.run(ctx.which("df") ?? "df", ["-Pk", path], { capture: true, timeoutMs: 20_000 });
+    const b = r.ok ? parseDfAvailable(r.stdout) : null;
+    return b === null ? { bytes: null, reason: `${statfsWhy}df ${oneLine(failReason(r))}` } : { bytes: b };
+}
+/** 그 포트의 /health 가 AiAkiv 엔진처럼 응답하면 본문, 아니면 null. */
+async function fetchHealth(doFetch, port) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), HEALTH_TIMEOUT_MS);
+    try {
+        const res = await doFetch(`http://127.0.0.1:${port}/health`, { signal: ac.signal });
+        const body = JSON.parse(await res.text());
+        return looksLikeEngineHealth(body) ? body : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function portFix(platform, port) {
+    const find = platform === "win32" ? `netstat -ano | findstr :${port}` : `lsof -nP -iTCP:${port} -sTCP:LISTEN`;
+    return `${find} 로 그 포트를 쓰는 프로그램을 찾아 끄거나, --port 로 다른 포트를 고르세요.`;
+}
+/** 점검을 모두 돌려 보고서를 만든다. dockerUnreachable 은 종료 코드 4 의 근거. */
+export async function collectLocalReport(ctx, opts, host) {
+    const port = opts.port ?? DEFAULT_ENGINE_PORT;
+    const platform = ctx.platform;
+    const startedAt = new Date().toISOString();
+    const checks = [];
+    const push = (id, v, ms, phase = "preflight") => {
+        checks.push({ id, phase, status: v.status, detail: v.detail, fix: v.fix ?? null, ms: Math.round(ms) });
+    };
+    const add = async (id, fn, phase = "preflight") => {
+        const t0 = performance.now();
+        let v;
+        try {
+            v = await fn();
+        }
+        catch (e) {
+            v = skip(`점검 중 오류가 났습니다: ${e.message}`);
+        }
+        push(id, v, performance.now() - t0, phase);
+    };
+    // 여러 점검이 함께 쓰는 사실. 클로저 안에서 채우므로 객체로 둔다.
+    const st = { info: null, infoWhy: "docker 실행 파일이 없어 보지 않았습니다", compose: null, health: null, ps: null, psWhy: "" };
+    await add("node.version", () => checkNodeVersion(host.nodeVersion));
+    await add("os.supported", () => checkOs(platform, host.arch, host.osRelease));
+    const docker = ctx.which("docker");
+    await add("docker.cli", () => docker
+        ? pass(`docker 실행 파일 ${docker}`)
+        : fail("docker 실행 파일을 찾지 못했습니다", `Docker 를 설치하세요: ${dockerInstallUrl(platform)}`));
+    await add("docker.daemon", async () => {
+        if (!docker)
+            return skip(st.infoWhy);
+        const r = await ctx.run(docker, ["info", "--format", "{{json .}}"], { capture: true, timeoutMs: DOCKER_TIMEOUT_MS });
+        const parsed = parseDockerInfo(r.stdout);
+        if (r.ok && parsed.info) {
+            st.info = parsed.info;
+            return pass(`Docker 데몬에 닿았습니다(${parsed.info.operatingSystem ?? "운영 체제 알 수 없음"})`);
+        }
+        st.infoWhy = "Docker 데몬에 닿지 못해 보지 않았습니다";
+        const reason = parsed.errors.length ? parsed.errors.join("; ") : r.stderr.trim() || failReason(r);
+        return fail(`Docker 데몬에 닿지 못했습니다: ${oneLine(reason)}`, daemonFix(platform, isPermissionDenied(`${reason}\n${r.stderr}`)));
+    });
+    await add("docker.version", () => (st.info ? checkDockerVersion(st.info.serverVersion ?? "") : skip(st.infoWhy)));
+    await add("compose.v2", async () => {
+        if (!docker)
+            return skip("docker 실행 파일이 없어 보지 않았습니다");
+        const r = await ctx.run(docker, ["compose", "version", "--short"], { capture: true, timeoutMs: DOCKER_TIMEOUT_MS });
+        const short = r.ok ? r.stdout.trim().split(/\r?\n/)[0]?.trim() || null : null;
+        if (short)
+            st.compose = short.replace(/^v/, "");
+        return checkCompose(short, !!ctx.which("docker-compose"), platform);
+    });
+    await add("docker.os", () => (st.info ? checkDockerOs(st.info.osType) : skip(st.infoWhy)));
+    await add("docker.arch", () => (st.info ? checkDockerArch(st.info.architecture, host.arch) : skip(st.infoWhy)));
+    await add("windows.wsl2", () => {
+        if (platform !== "win32")
+            return skip("Windows 가 아니라 보지 않았습니다");
+        if (!st.info)
+            return skip(st.infoWhy);
+        if (st.info.osType === "windows")
+            return skip("Windows 컨테이너 모드라 보지 않았습니다(docker.os 를 먼저 고치세요)");
+        return checkWsl2(st.info.kernelVersion, st.info.operatingSystem);
+    });
+    await add("docker.mem", () => st.info ? checkDockerMem(st.info.memTotal, platform, isDockerDesktop(st.info)) : skip(st.infoWhy));
+    await add("docker.cpus", () => (st.info ? checkDockerCpus(st.info.ncpu, isDockerDesktop(st.info)) : skip(st.infoWhy)));
+    await add("disk.free", async () => {
+        const tried = [];
+        for (const c of diskCandidates(platform, ctx.home, ctx.env, st.info)) {
+            if (!host.exists(c.path)) {
+                tried.push(`${c.path}(없음)`);
+                continue;
+            }
+            const r = await freeBytes(ctx, host, c.path);
+            if (r.bytes !== null) {
+                const v = checkDiskFree(r.bytes, `${c.label} ${c.path}`);
+                return tried.length ? { ...v, detail: `${v.detail}(먼저 본 경로: ${tried.join(", ")})` } : v;
+            }
+            tried.push(`${c.path}(${r.reason})`);
+        }
+        return skip(`여유 공간을 확인하지 못했습니다: ${tried.join(", ")}`);
+    });
+    await add("port.free", async () => {
+        const b = await host.tryBind(port);
+        st.health = await fetchHealth(ctx.fetch, port);
+        if (b.ok)
+            return pass(`127.0.0.1:${port} 에 묶을 수 있습니다`);
+        if (st.health)
+            return info(`127.0.0.1:${port} 는 이미 AiAkiv 엔진이 쓰는 중입니다`);
+        return fail(`127.0.0.1:${port} 에 묶을 수 없습니다(${b.code ?? oneLine(b.message)})`, portFix(platform, port));
+    });
+    const netIds = [...NET_TARGETS.map((t) => t.id), "net.proxy"];
+    if (opts.offline) {
+        for (const id of netIds)
+            push(id, skip("--offline 이라 보지 않았습니다"), 0);
+    }
+    else {
+        const proxyEnv = hasProxyEnv(ctx.env);
+        const results = await Promise.all(NET_TARGETS.map(async (t) => {
+            const t0 = performance.now();
+            const r = await reach(ctx.fetch, t.url, NET_TIMEOUT_MS);
+            return { t, v: netVerdict(r, t.what, t.fix, proxyEnv), ms: performance.now() - t0 };
+        }));
+        for (const { t, v, ms } of results)
+            push(t.id, v, ms);
+        await add("net.proxy", () => checkProxy(ctx.env, st.info));
+    }
+    await add("docker.desktop_license", () => (st.info ? checkDesktopLicense(st.info) : skip(st.infoWhy)));
+    await add("install.existing", async () => {
+        const p = platform === "win32" ? win32 : posix;
+        const engineDir = p.join(ctx.home, ".aiakiv", "engine");
+        const hasDir = host.exists(engineDir);
+        if (docker && st.info) {
+            const r = await ctx.run(docker, ["ps", "--format", "{{.Image}}\t{{.Names}}\t{{.Ports}}"], {
+                capture: true,
+                timeoutMs: DOCKER_TIMEOUT_MS,
+            });
+            if (r.ok)
+                st.ps = parseDockerPs(r.stdout);
+            else
+                st.psWhy = `docker ps 실패: ${oneLine(failReason(r))}`;
+        }
+        else
+            st.psWhy = st.infoWhy;
+        const running = (st.ps ?? []).filter(isEngineContainer);
+        const parts = [hasDir ? `${engineDir} 가 있습니다` : `${engineDir} 가 없습니다`];
+        if (st.ps === null)
+            parts.push(`실행 중인 컨테이너는 보지 못했습니다(${st.psWhy})`);
+        else if (running.length)
+            parts.push(`실행 중인 엔진 컨테이너 ${running.map((x) => x.names).join(", ")}`);
+        else
+            parts.push("실행 중인 엔진 컨테이너가 없습니다");
+        if (st.health)
+            parts.push(`포트 ${port} 에서 엔진이 응답합니다`);
+        const installed = hasDir || running.length > 0 || !!st.health;
+        return info(parts.join(", "), installed ? "이미 설치돼 있습니다. 새 판으로 올리려면 aiakiv local upgrade 를 쓰세요." : null);
+    });
+    if (st.health) {
+        const h = st.health;
+        await add("engine.health", () => checkEngineHealth(h), "engine");
+        await add("engine.edition", () => checkEngineEdition(h), "engine");
+        await add("engine.version", () => checkEngineVersion(h), "engine");
+        await add("engine.bind", () => {
+            if (!st.info)
+                return skip(st.infoWhy);
+            if (st.ps === null)
+                return skip(`실행 중인 컨테이너를 보지 못했습니다(${st.psWhy})`);
+            const rows = st.ps.filter((r) => hostAddrsForPort(r.ports, port).length);
+            if (!rows.length)
+                return skip(`포트 ${port} 를 내보내는 컨테이너를 찾지 못했습니다(Docker 밖에서 도는 엔진일 수 있습니다)`);
+            const addrs = [...new Set(rows.flatMap((r) => hostAddrsForPort(r.ports, port)))];
+            const v = checkEngineBind(addrs, port, publicIPv4s(host.interfaces()));
+            return { ...v, detail: `${v.detail}(컨테이너 ${rows.map((r) => r.names).join(", ")})` };
+        }, "engine");
+    }
+    const summary = { pass: 0, warn: 0, fail: 0, skip: 0, info: 0 };
+    for (const c of checks)
+        summary[c.status] += 1;
+    const report = {
+        tool: LOCAL_DOCTOR_TOOL,
+        tool_version: VERSION,
+        started_at: startedAt,
+        finished_at: new Date().toISOString(),
+        host: {
+            os: platform,
+            os_release: host.osRelease,
+            arch: host.arch,
+            cpus: host.cpus,
+            mem_bytes: host.memBytes,
+            docker_server: st.info?.serverVersion ?? null,
+            compose: st.compose,
+            docker_os: st.info?.osType ?? null,
+            docker_arch: st.info?.architecture ?? null,
+            docker_mem_bytes: st.info?.memTotal ?? null,
+            docker_cpus: st.info?.ncpu ?? null,
+        },
+        checks,
+        measurements: {},
+        summary,
+        ok: summary.fail === 0,
+    };
+    return { report, dockerUnreachable: !docker || !st.info };
+}
+function summaryText(s) {
+    return ["pass", "warn", "fail", "skip", "info"].map((k) => `${STATUS_LABEL[k]} ${s[k]}`).join(", ");
+}
+function verdictText(r, dockerUnreachable) {
+    if (r.ok)
+        return `준비됐습니다(${summaryText(r.summary)}).`;
+    const head = dockerUnreachable ? "Docker 에 닿지 못해 준비되지 않았습니다" : "준비되지 않았습니다";
+    return `${head}. 실패 ${r.summary.fail}건을 먼저 고치세요(${summaryText(r.summary)}).`;
+}
+/** 사람용 화면. */
+export function renderText(r, port, dockerUnreachable) {
+    const lines = [];
+    lines.push(`aiakiv local doctor ${r.tool_version}: 자체 설치판(무료 5인 엔진) 설치 전 점검, 포트 ${port}`, "");
+    lines.push(...table(["상태", "점검", "내용"], r.checks.map((c) => [STATUS_LABEL[c.status], c.id, c.detail])));
+    lines.push("", `결과: ${verdictText(r, dockerUnreachable)}`);
+    const todo = r.checks.filter((c) => c.fix && c.status !== "pass");
+    if (todo.length) {
+        lines.push("", "고칠 것과 알아 둘 것:");
+        const order = ["fail", "warn", "info", "skip"];
+        todo.sort((a, b) => order.indexOf(a.status) - order.indexOf(b.status));
+        for (const c of todo)
+            lines.push(`  [${STATUS_LABEL[c.status]}] ${c.id}: ${c.fix}`);
+    }
+    return lines;
+}
+const cell = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+/** --out 의 마크다운. 화면과 같은 내용에 컴퓨터 정보를 더한다. */
+export function renderMarkdown(r, port, dockerUnreachable) {
+    const h = r.host;
+    const md = [];
+    md.push("# AiAkiv 무료 엔진 설치 전 점검", "");
+    md.push(`- 도구: ${r.tool} ${r.tool_version}`);
+    md.push(`- 시작: ${r.started_at}, 끝: ${r.finished_at}`);
+    md.push(`- 컴퓨터: ${h.os} ${h.os_release}, ${h.arch}, CPU ${h.cpus}개, 메모리 ${gbText(h.mem_bytes)}`);
+    md.push(h.docker_server
+        ? `- Docker: 서버 ${h.docker_server}, compose ${h.compose ?? "없음"}, ${h.docker_os ?? "?"}/${h.docker_arch ?? "?"}, ` +
+            `메모리 ${h.docker_mem_bytes !== null ? gbText(h.docker_mem_bytes) : "?"}, CPU ${h.docker_cpus ?? "?"}개`
+        : `- Docker: 닿지 못함(compose ${h.compose ?? "없음"})`);
+    md.push(`- 점검한 포트: ${port}`);
+    md.push(`- 결과: ${verdictText(r, dockerUnreachable)}`, "");
+    md.push("| 점검 | 단계 | 상태 | 내용 | 고칠 것 | 걸린 시간(ms) |", "|---|---|---|---|---|---|");
+    for (const c of r.checks) {
+        md.push(`| ${c.id} | ${c.phase} | ${STATUS_LABEL[c.status]} | ${cell(c.detail)} | ${cell(c.fix)} | ${c.ms} |`);
+    }
+    md.push("");
+    return md;
+}
+export async function runLocalDoctor(ctx, opts, host) {
+    const port = opts.port ?? DEFAULT_ENGINE_PORT;
+    const { report, dockerUnreachable } = await collectLocalReport(ctx, opts, host);
+    if (opts.json)
+        ctx.out(JSON.stringify(report));
+    else
+        for (const l of renderText(report, port, dockerUnreachable))
+            ctx.out(l);
+    if (opts.out) {
+        const file = resolve(ctx.cwd, opts.out);
+        try {
+            writeFileSync(file, renderMarkdown(report, port, dockerUnreachable).join("\n"), "utf8");
+        }
+        catch (e) {
+            ctx.err(`보고서 파일을 쓰지 못했습니다(${file}): ${e.message}`);
+            return 1;
+        }
+        // --json 이면 stdout 은 JSON 하나만 둔다.
+        (opts.json ? ctx.err : ctx.out)(`보고서 파일: ${file}`);
+    }
+    if (dockerUnreachable)
+        return 4;
+    return report.ok ? 0 : 3;
+}

package/dist/main.js

@@ -6,6 +6,8 @@ import { runBind } from "./bind.js";
 import { ConsoleUsageError, runConsole, runConsoleKey } from "./console.js";
 import { runDashboard } from "./dashboard.js";
 import { DEFAULT_REPORT, DOCTOR_CLIENT_IDS, runDoctor } from "./doctor.js";
+import { realHost } from "./local/checks.js";
+import { DEFAULT_ENGINE_PORT, runLocalDoctor } from "./local/doctor.js";
 import { runSetup } from "./setup.js";
 import { DEFAULT_SKILLS_TARBALL_URL } from "./skills.js";
 import { DEFAULT_CONTROL_URL, DEFAULT_MCP_URL } from "./urls.js";
@@ -21,6 +23,7 @@ export const HELP = `aiakiv ${VERSION}: 폴더에 AiAkiv 프로젝트를 고정
   npx aiakiv console describe [--json] [--dir <폴더>]
   npx aiakiv console key [--expires-days N] [--dir <폴더>] [--no-browser]
   npx aiakiv dashboard [--json] [--dir <폴더>]
+  npx aiakiv local doctor [--json] [--out <파일.md>] [--port <n>] [--offline]
 
 bind    폴더에 프로젝트를 고정합니다. 웹 콘솔의 "폴더 ZIP 받기" 와 같은 한 벌을 그 폴더에 직접 씁니다.
         claude, cursor 는 ?project= 주소(OAuth)를 쓰고, codex, gemini 는 브라우저에서 확인 버튼을 눌러
@@ -51,9 +54,18 @@ console key
         읽거나 쓸 수 없고 관리 작업만 합니다. 기본 만료 90일. 프로젝트나 팀을 고르지 않고, 속한
         모든 팀을 다룹니다(.gitignore 에 /.aiakiv/ 를 더합니다). 다시 받으면 앞선 계정 키는 폐기됩니다.
 dashboard
-        팀, 프로젝트, 저장 대상, 켜진 권한, 연결, 카드, 최근 저장 대상 이력을 한 화면에 보입니다.
+        팀, 프로젝트, 저장 대상, 켜진 권한, 연결, 카드, 최근 저장 대상 이력, 사용량(오늘 저장 수와
+        한도)을 한 화면에 보입니다.
         한 칸이 실패해도 나머지는 그립니다. 계정 키로는 저장 대상을 읽지 않고, 그 폴더에 프로젝트
         키가 있으면 그 키로 확인합니다.
+local doctor
+        자체 설치판(무료 5인 엔진)을 깔기 전에 이 컴퓨터가 준비됐는지 점검합니다. Node, OS, Docker(판,
+        compose v2, 리눅스 컨테이너 모드, 아키텍처, 메모리, CPU), 디스크 여유 공간, 포트(기본 ${DEFAULT_ENGINE_PORT}),
+        인터넷 연결(Docker Hub, www.aiakiv.com, npm 저장소), 프록시 설정, 이미 깔린 엔진을 봅니다. 그 포트에
+        엔진이 떠 있으면 엔진 상태, 판 이름, 판, 포트가 묶인 주소도 봅니다. --json 은 보고서 JSON 하나를 내고,
+        --out 은 같은 내용을 마크다운 파일로 씁니다. --port 는 볼 포트를 바꾸고, --offline 이면 인터넷 연결은
+        보지 않습니다. 종료 코드: 0 실패 없음, 3 실패 있음, 2 인자 오류, 4 Docker 를 찾지 못했거나 Docker 에
+        닿지 못함(이때도 보고서는 냅니다).
 
 console 과 dashboard 가 키를 찾는 순서: 환경 변수 AIAKIV_API_KEY, <폴더>/.aiakiv/console.json(계정 키),
 <폴더>의 .codex/config.toml 과 .gemini/settings.json(프로젝트 키). 키 평문은 화면에 내지 않고 키 id 와
@@ -91,6 +103,15 @@ function parseExpiresDays(v) {
         throw new UsageError("--expires-days 는 1 이상의 정수입니다.");
     return n;
 }
+function parsePort(v) {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!/^\d+$/.test(v.trim()) || !Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new UsageError(`--port 는 1 에서 65535 사이의 정수입니다(받은 값: ${v}).`);
+    }
+    return n;
+}
 function parseClient(v, required) {
     if (v === undefined) {
         if (required)
@@ -281,6 +302,35 @@ export async function main(argv, ctx) {
                 action: positionals[0], data: values.data, json: values.json, dir: values.dir, yes: values.yes,
             });
         }
+        if (cmd === "local") {
+            // 자체 설치판(무료 5인 엔진) 명령. 지금은 doctor 하나(docs/211 §5.1, §17). install, status 등이 같은 아래에 붙는다.
+            const [sub, ...subRest] = rest;
+            if (sub === "-h" || sub === "--help" || sub === "help")
+                return (ctx.out(HELP), 0);
+            if (!sub)
+                throw new UsageError("local 뒤에 하위 명령이 필요합니다(지금은 doctor 하나입니다).");
+            if (sub !== "doctor")
+                throw new UsageError(`local 의 모르는 하위 명령입니다: ${sub}. 지금은 doctor 하나입니다.`);
+            const { values, positionals } = parseArgs({
+                args: subRest,
+                options: {
+                    json: { type: "boolean", default: false },
+                    out: { type: "string" },
+                    port: { type: "string" },
+                    offline: { type: "boolean", default: false },
+                    help: { type: "boolean", short: "h" },
+                },
+                strict: true,
+                allowPositionals: true,
+            });
+            if (values.help)
+                return (ctx.out(HELP), 0);
+            if (positionals.length)
+                throw new UsageError(`local doctor 는 위치 인자를 받지 않습니다: ${positionals.join(" ")}`);
+            if (values.out !== undefined && !values.out.trim())
+                throw new UsageError("--out 에 파일 이름이 필요합니다.");
+            return await runLocalDoctor(ctx, { json: values.json, out: values.out, port: parsePort(values.port), offline: values.offline }, realHost());
+        }
         if (cmd === "dashboard") {
             const { values } = parseArgs({
                 args: rest,

package/dist/setup.js

@@ -221,12 +221,14 @@ async function setup(ctx, opts) {
         ctx.out("전역 스킬: --no-skills 라 건너뜁니다.");
     ctx.out("다음 할 일(사람):");
     if (opts.clients.includes("gemini")) {
-        ctx.out(`  - Gemini CLI: gemini 를 실행한 뒤 /mcp 에서 ${GLOBAL_SERVER_NAME} 가 연결됐는지 보고, ` +
-            "\"저장 대상 확인해 줘\" 라고 해서 binding 이 main 인지 확인하세요.");
+        ctx.out(`  - Gemini CLI: 신뢰한 작업 폴더에서 gemini 를 실행한 뒤 /mcp 에서 ${GLOBAL_SERVER_NAME} 가 연결됐는지 보고, ` +
+            "\"저장 대상 확인해 줘\" 라고 해서 binding 이 main 인지 확인하세요. " +
+            "신뢰하지 않은 폴더에서는 Gemini CLI 가 전역 서버도 꺼진 것으로 보여 줍니다.");
     }
     if (opts.clients.includes("antigravity")) {
-        ctx.out(`  - Antigravity: Agent 설정의 MCP Servers 에서 ${GLOBAL_SERVER_NAME} 가 보이는지 확인하세요. ` +
-            "앱이 켜져 있었다면 설정 파일을 바꿨으니 앱을 다시 시작하세요.");
+        ctx.out("  - Antigravity: 앱이 켜져 있었다면 설정 파일을 바꿨으니 앱을 다시 시작하세요. " +
+            "새 대화에서 \"저장 대상 확인해 줘\" 라고 해서 binding 이 main 인지 확인하세요. " +
+            `서버 목록은 사이드바의 Skills & Customizations 에서 ${GLOBAL_SERVER_NAME} 로 볼 수 있습니다.`);
     }
     ctx.out(`  - 확인: npx aiakiv doctor --client ${opts.clients.join(",")}`);
     // 홈 폴더 파일이라 .gitignore 로 빼 줄 수 없다. 마지막 줄로 알린다.

package/dist/snippet.js

@@ -27,17 +27,13 @@ export function mcpUrl(base, project) {
     const url = `${base}/mcp`;
     return project === undefined ? url : `${url}?project=${encodeURIComponent(project)}`;
 }
-/** 프로젝트를 지정하지 않는 OAuth 연결(전역 설치)의 주소 `{base}/mcp?apps=all`.
- * 표시 없는 `{base}/mcp` 에 OAuth 로 붙고 `?project=` 도 없으면 서버가 앱 실행 도구
- * (`run_aiakiv_app_action`)를 뺀 표면만 준다. `?apps=all` 이 전체 도구를 고른다.
- * `?project=` 주소(mcpUrl 의 project)와 함께 쓰지 않는다 — 그 연결은 이미 전체를 받는다. */
-export function mcpUrlAllApps(base) {
-    return `${mcpUrl(base)}?apps=all`;
-}
 /** Cursor 원클릭 설치 딥링크 — 전역 설치(머리글 없음, Main 을 따라간다).
- * config = base64(JSON { url }). 주소는 mcpUrlAllApps. */
+ * config = base64(JSON { url }). 주소는 표시 없는 `{base}/mcp`(BP-171 §7.1, 공개 주소에서
+ * 앱 전체 표시를 뺐다). 이 연결은 기억 도구와 카드 도구를 받고 앱 실행 도구
+ * (`run_aiakiv_app_action`)는 받지 않는다. 관리는 `npx aiakiv console`, 대화 안 앱 기능은
+ * 폴더 연결(`?project=`)이나 API 키 연결로 한다. */
 export function cursorInstallLink(base) {
-    const config = btoa(JSON.stringify({ url: mcpUrlAllApps(base) }));
+    const config = btoa(JSON.stringify({ url: mcpUrl(base) }));
     return `cursor://anysphere.cursor-deeplink/mcp/install?name=AiAkiv&config=${config}`;
 }
 /** 내 프로젝트의 연결 주소와 머리글 — 복사 스니펫과 ZIP 이 같이 쓴다.

package/dist/version.js

@@ -1,2 +1,2 @@
 // package.json 의 version 과 같아야 한다(tests/cli.test.mjs 가 확인).
-export const VERSION = "0.2.0";
+export const VERSION = "0.2.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiakiv",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AiAkiv CLI: pin a folder to an AiAkiv project (connection, folder skills, settings), check it, and run console actions and a dashboard from the shell.",
   "license": "MIT",
   "type": "module",