aiakiv 0.2.1 → 0.3.0

package/dist/local/doctor.js

@@ -0,0 +1,355 @@
+// `aiakiv local doctor [--json] [--out <파일.md>] [--port <n>] [--offline]` — 자체 설치판(무료 5인 엔진)을
+// 깔기 전에 이 컴퓨터를 점검한다(docs/211 §17.2 ~ §17.4). 엔진이 떠 있으면(그 포트의 /health 가 엔진처럼
+// 응답하면) 상태, 판 이름, 판, 포트가 묶인 주소도 본다. 엔진 컨테이너가 떠 있으면 엔진의 `aiakiv-admin status` 에서
+// 벡터 없는 기억(vectors 칸)도 본다(engine.vectors). 보고서는 §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, checkEngineVectors, 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";
+import { listContainers, parseEngineDoc, pickEngine } from "./portable.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");
+    }
+    // 무료 5인판 엔진 컨테이너가 있으면 엔진의 status 에서 벡터 없는 기억(검색에 나오지 않음)을 본다. 컨테이너 찾기는
+    // local export, import 와 같다(portable.ts). 엔진 컨테이너가 하나도 없으면(설치 전) 이 줄을 내지 않는다.
+    // 엔진을 부르다 실패해도 주의나 알림까지만 낸다(종료 코드는 fail 만 바꾼다).
+    if (docker && st.info) {
+        const listed = await listContainers(ctx, docker);
+        const pick = listed.ok ? pickEngine(listed.rows) : null;
+        if (pick && pick.engines.length) {
+            await add("engine.vectors", async () => {
+                if (pick.running.length > 1) {
+                    return skip(`떠 있는 엔진 컨테이너가 여럿이라 보지 않았습니다(${pick.running.map((x) => x.name).join(", ")})`);
+                }
+                if (!pick.running.length) {
+                    const stopped = pick.engines.map((x) => `${x.name}(${x.state || "알 수 없음"})`).join(", ");
+                    return skip(`엔진 컨테이너가 떠 있지 않아 보지 않았습니다(${stopped})`);
+                }
+                const c = pick.running[0];
+                // 이 보고서의 말에 맞춰 엔진 문장도 한국어로 받는다(이 호출에만, 설치 언어는 그대로).
+                const r = await ctx.run(docker, ["exec", "-e", "AIAKIV_LANGUAGE=ko", c.name, "aiakiv-admin", "--json", "status"], { capture: true, timeoutMs: DOCKER_TIMEOUT_MS });
+                // 엔진은 실패해도(DB 연결 실패 등) JSON 문서를 낸다. 문서가 없을 때만 실행 실패로 본다.
+                const v = checkEngineVectors(parseEngineDoc(r.stdout), oneLine(failReason(r)));
+                return { ...v, detail: `${v.detail}(컨테이너 ${c.name})` };
+            }, "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;
+}