aiakiv 0.2.2 → 0.3.0

package/dist/enterprise/precheck.js

@@ -0,0 +1,656 @@
+// `aiakiv enterprise precheck` — 유료 기업판 설치 전 점검(K2G docs/212 BP-173 §3, P3)을 이 컴퓨터의 Docker 로
+// 돌린다. 점검 본체는 유료 기업판 엔진 이미지 안의 `aiakiv-admin precheck`(Python)이고, 이 명령은 그 앞뒤를
+// 맡는다: 설정 파일 찾기, Docker 확인, 이미지 정하기(이미 있는 것, tar, 내려받기), compose 파일 쓰기, 컨테이너
+// 실행, 로그인 주소 보이기와 브라우저 열기, 결과 정리. 점검의 동작 규격(종료 코드, --json 줄 형식, 로그인 대기
+// 줄)은 K2G packaging/enterprise/precheck/README.md §2 에 있다.
+//
+// 종료 코드: 점검의 것(0 실패 없음, 3 실패 있음, 2 설정 오류)을 그대로 돌려준다. 이 명령의 것은 2 인자 오류
+// (설정 파일 없음, --out 이 작업 폴더 밖), 4 Docker 를 쓸 수 없음(실행 파일 없음, 데몬에 닿지 못함, compose v2
+// 없음, Windows 컨테이너 모드), 5 이미지를 구하지 못함, 1 점검 컨테이너가 보고서 없이 끝남이나 보고서 파일을 쓰지 못함.
+// 작업 폴더(설정 파일이 있는 폴더)는 컨테이너의 /config 로 붙는다. 설정의 ca_bundle = "/config/corp-ca.pem" 이 여기에 기댄다.
+// 보고서 파일은 컨테이너가 아니라 이 CLI 가 <작업 폴더>/<--out>/ 에 쓴다(reportMarkdown.ts).
+// 비밀 값은 다루지 않는다. 같은 폴더의 .env 는 compose 의 env_file 로 넘길 뿐 열어 읽지 않는다. 로그인은 사람이
+// 브라우저에서 하고, 이 명령은 주소만 보인다.
+import { createHash } from "node:crypto";
+import { closeSync, createReadStream, createWriteStream, existsSync, mkdirSync, openSync, readSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { readTextIfExists, writeFileAtomic } from "../fsutil.js";
+import { failReason } from "../proc.js";
+import { truncate } from "../render.js";
+import { ENTERPRISE_ENGINE_VERSION } from "../version.js";
+import { checkCompose, checkDockerOs, daemonFix, dockerInstallUrl, isPermissionDenied, normArch, parseDockerInfo, } from "../local/checks.js";
+import { STATUS_LABEL } from "../local/doctor.js";
+import { reportJsonText, reportLanguage, toMarkdown } from "./reportMarkdown.js";
+export const PRECHECK_IMAGE_REPO = "aiakiv/engine-enterprise";
+export const DEFAULT_PRECHECK_CONFIG = "aiakiv-enterprise.toml";
+export const EXAMPLE_PRECHECK_CONFIG = "aiakiv-enterprise.example.toml";
+export const DEFAULT_PRECHECK_OUT = "report";
+/** compose 프로젝트 이름과, 작업 폴더 안에 compose 파일을 두는 폴더. */
+export const PRECHECK_PROJECT = "aiakiv-precheck";
+export const PRECHECK_DIR = ".aiakiv-precheck";
+export const ENTERPRISE_PAGE = "https://www.aiakiv.com/enterprise";
+/** 점검의 마지막 줄(보고서)의 tool 값. */
+export const PRECHECK_TOOL = "aiakiv-precheck";
+export const EXIT_OK = 0;
+export const EXIT_RUN_FAILED = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_FAILED = 3;
+export const EXIT_DOCKER = 4;
+export const EXIT_IMAGE = 5;
+const DOCKER_TIMEOUT_MS = 30_000;
+const MANIFEST_TIMEOUT_MS = 30_000;
+const LOAD_TIMEOUT_MS = 30 * 60_000;
+export function defaultImageRef() {
+    return `${PRECHECK_IMAGE_REPO}:${ENTERPRISE_ENGINE_VERSION}`;
+}
+/** 이 CLI 판에 고정한 목록 파일 주소. AIAKIV_ENTERPRISE_MANIFEST_URL 로 바꾼다(시험용). */
+export function manifestUrl(env) {
+    return (env.AIAKIV_ENTERPRISE_MANIFEST_URL?.trim() ||
+        `https://www.aiakiv.com/download/enterprise/${ENTERPRISE_ENGINE_VERSION}/manifest.json`);
+}
+/**
+ * --out 을 작업 폴더 안의 상대 경로(조각을 / 로 이은 것)로. 절대 경로, 드라이브 문자, 작업 폴더 밖으로 나가는
+ * `..`, 작업 폴더 자신이면 null. 역슬래시는 Windows 의 구분자로 보고 / 로 바꾼다.
+ */
+export function relativeOut(out) {
+    const s = out.trim().replace(/\\/g, "/");
+    if (!s || s.startsWith("/") || /^[A-Za-z]:/.test(s))
+        return null;
+    const parts = [];
+    for (const seg of s.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            if (!parts.length)
+                return null;
+            parts.pop();
+            continue;
+        }
+        parts.push(seg);
+    }
+    return parts.length ? parts.join("/") : null;
+}
+/** compose 파일에 적는 호스트 경로. Windows 는 역슬래시를 / 로(F:\work 는 F:/work, Docker Desktop 이 읽는다). */
+export function composeHostPath(p, platform) {
+    return platform === "win32" ? p.replace(/\\/g, "/") : p;
+}
+/** YAML 의 큰따옴표 글자. compose 는 값 안의 `$` 를 변수로 펼치므로 `$$` 로 적는다. */
+function yamlString(s) {
+    return JSON.stringify(s.replace(/\$/g, "$$$$"));
+}
+/**
+ * K2G packaging/enterprise/precheck/precheck-compose.yml 의 precheck 서비스와 같은 내용. 이미지는 정한 참조로
+ * 고정하고 받으러 나가지 않는다(pull_policy never). 볼륨은 Windows 드라이브 문자의 `:` 와 헷갈리지 않게 긴 형식으로
+ * 적는다. 동봉 Keycloak 서비스는 넣지 않는다.
+ */
+export function composeYaml(spec) {
+    const lines = [
+        "# aiakiv CLI(npx aiakiv enterprise precheck)가 만든 파일입니다. 돌릴 때마다 다시 쓰므로 고치지 마세요.",
+        "services:",
+        "  precheck:",
+        `    image: ${yamlString(spec.image)}`,
+        "    pull_policy: never",
+        '    entrypoint: ["aiakiv-admin", "precheck"]',
+        "    healthcheck: {disable: true}",
+        "    # 로그인 콜백은 이 컴퓨터의 127.0.0.1:7777 에서만 받습니다(브라우저가 같은 컴퓨터에 있을 때).",
+        '    ports: ["127.0.0.1:7777:7777"]',
+    ];
+    if (spec.envFile)
+        lines.push(`    env_file: [${yamlString(composeHostPath(spec.envFile, spec.platform))}]`);
+    lines.push("    volumes:", "      - type: bind", `        source: ${yamlString(composeHostPath(spec.workDir, spec.platform))}`, "        target: /config", "");
+    return lines.join("\n");
+}
+/**
+ * `docker compose ... run` 의 인자(맨 앞의 docker 는 빼고). -T 는 가상 터미널을 붙이지 않게 한다. 붙으면 점검의
+ * stderr 가 stdout 에 섞이고 줄 끝이 \r\n 이 되어 JSON 줄을 가르기 어렵다.
+ * 점검에 --out 은 넘기지 않는다. 보고서 파일은 마지막 줄을 받아 이 CLI 가 쓴다(reportMarkdown.ts 머리 주석).
+ */
+export function composeRunArgs(s) {
+    const args = [
+        "compose", "-p", PRECHECK_PROJECT, "-f", s.composeFile,
+        "run", "--rm", "--service-ports", "-T", "precheck",
+        "--config", `/config/${s.configName}`, "--json",
+    ];
+    if (s.device)
+        args.push("--device");
+    if (s.noLogin)
+        args.push("--no-login");
+    if (s.only !== undefined)
+        args.push("--only", s.only);
+    if (s.skip !== undefined)
+        args.push("--skip", s.skip);
+    if (s.redactClaims)
+        args.push("--redact-claims");
+    return args;
+}
+/** `<파일>.sha256` 의 내용(`<지문>` 또는 sha256sum 형식 `<지문>  <파일 이름>`)에서 지문. 없으면 null. */
+export function parseSha256File(text) {
+    const m = /(?:^|\s)([0-9a-fA-F]{64})(?:\s|$)/.exec(text);
+    return m ? m[1].toLowerCase() : null;
+}
+/** `docker load` 의 출력에서 불러온 이미지 참조. 태그가 있으면 마지막 태그, 없으면 이미지 id. */
+export function parseLoadOutput(stdout) {
+    let tag = null;
+    let id = null;
+    for (const l of stdout.split(/\r?\n/)) {
+        const t = /^\s*Loaded image:\s*(\S+)\s*$/.exec(l);
+        if (t)
+            tag = t[1];
+        const i = /^\s*Loaded image ID:\s*(\S+)\s*$/.exec(l);
+        if (i)
+            id = i[1];
+    }
+    return tag ?? id;
+}
+export async function sha256File(file) {
+    const h = createHash("sha256");
+    await pipeline(createReadStream(file), async (src) => {
+        for await (const chunk of src)
+            h.update(chunk);
+    });
+    return h.digest("hex");
+}
+/** 긴 오류 출력에서 첫 줄만, 너무 길면 자른다. */
+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;
+}
+const downloadFix = () => `홈페이지(${ENTERPRISE_PAGE})에서 점검용 이미지를 내려받아 --image-tar 로 넣으세요.`;
+// ---- Docker ---------------------------------------------------------------------------------
+async function checkDocker(ctx) {
+    const docker = ctx.which("docker");
+    if (!docker) {
+        return { ok: false, detail: "docker 실행 파일을 찾지 못했습니다", fix: `Docker 를 설치하세요: ${dockerInstallUrl(ctx.platform)}` };
+    }
+    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) {
+        const reason = parsed.errors.length ? parsed.errors.join("; ") : r.stderr.trim() || failReason(r);
+        return {
+            ok: false,
+            detail: `Docker 데몬에 닿지 못했습니다: ${oneLine(reason)}`,
+            fix: daemonFix(ctx.platform, isPermissionDenied(`${reason}\n${r.stderr}`)),
+        };
+    }
+    const os = checkDockerOs(parsed.info.osType);
+    if (os.status === "fail")
+        return { ok: false, detail: os.detail, fix: os.fix ?? "리눅스 컨테이너 모드로 바꾸세요." };
+    const c = await ctx.run(docker, ["compose", "version", "--short"], { capture: true, timeoutMs: DOCKER_TIMEOUT_MS });
+    const short = c.ok ? c.stdout.trim().split(/\r?\n/)[0]?.trim() || null : null;
+    const compose = checkCompose(short, !!ctx.which("docker-compose"), ctx.platform);
+    if (compose.status === "fail")
+        return { ok: false, detail: compose.detail, fix: compose.fix ?? "" };
+    return {
+        ok: true,
+        docker,
+        info: parsed.info,
+        detail: `Docker 서버 ${parsed.info.serverVersion}, ${compose.detail}`,
+    };
+}
+async function imageExists(ctx, docker, ref) {
+    const r = await ctx.run(docker, ["image", "inspect", "--format", "{{.Id}}", ref], {
+        capture: true,
+        timeoutMs: DOCKER_TIMEOUT_MS,
+    });
+    return r.ok;
+}
+async function dockerLoad(ctx, docker, file) {
+    ctx.err(`이미지를 불러오는 중입니다(docker load, 몇 분 걸릴 수 있습니다): ${file}`);
+    const r = await ctx.run(docker, ["load", "-i", file], { capture: true, timeoutMs: LOAD_TIMEOUT_MS });
+    if (!r.ok) {
+        return {
+            ok: false,
+            detail: `docker load 가 실패했습니다: ${oneLine(failReason(r))}`,
+            fix: `파일이 온전한지 확인하고 다시 내려받으세요. 계속 실패하면 ${ENTERPRISE_PAGE} 에서 받은 파일인지 확인하세요.`,
+        };
+    }
+    const image = parseLoadOutput(r.stdout);
+    if (!image) {
+        return {
+            ok: false,
+            detail: `docker load 의 출력에서 불러온 이미지를 찾지 못했습니다: ${oneLine(r.stdout || r.stderr)}`,
+            fix: "docker images 로 불러온 이미지 이름을 확인하고 --image <이름:판> 으로 주세요.",
+        };
+    }
+    return { ok: true, image };
+}
+async function imageFromTar(ctx, docker, tarArg) {
+    const file = resolve(ctx.cwd, tarArg);
+    let isFile = false;
+    try {
+        isFile = statSync(file).isFile();
+    }
+    catch {
+        /* 아래에서 알린다 */
+    }
+    if (!isFile) {
+        return { ok: false, detail: `이미지 파일이 없습니다: ${file}`, fix: "--image-tar 에 내려받은 tar 파일의 경로를 주세요." };
+    }
+    const got = await sha256File(file);
+    const sumFile = `${file}.sha256`;
+    let note = "지문 파일이 없어 비교하지 않았습니다";
+    if (existsSync(sumFile)) {
+        const want = parseSha256File(readText(sumFile));
+        if (!want) {
+            return {
+                ok: false,
+                detail: `지문 파일 ${sumFile} 에서 sha256 지문을 읽지 못했습니다`,
+                fix: "홈페이지에서 지문 파일을 다시 받거나, 지문 파일을 지우고 아래 지문을 홈페이지의 값과 직접 비교하세요.",
+            };
+        }
+        if (want !== got) {
+            return {
+                ok: false,
+                detail: `이미지 파일의 내용 지문이 다릅니다(지문 파일 ${want}, 이 파일 ${got})`,
+                fix: `파일이 손상됐거나 다른 파일입니다. ${ENTERPRISE_PAGE} 에서 다시 내려받으세요.`,
+            };
+        }
+        note = `지문 파일 ${basename(sumFile)} 과 같습니다`;
+    }
+    const loaded = await dockerLoad(ctx, docker, file);
+    if (!loaded.ok)
+        return loaded;
+    return { ok: true, image: loaded.image, source: "tar", sha256: got, detail: `${basename(file)} 를 불러왔습니다(sha256 ${got}, ${note})` };
+}
+function readText(file) {
+    // 지문 파일은 짧은 글자 파일이다. 큰 파일을 잘못 가리켜도 앞부분만 본다.
+    const buf = Buffer.alloc(4096);
+    const fd = openSync(file, "r");
+    try {
+        const n = readSync(fd, buf, 0, buf.length, 0);
+        return buf.subarray(0, n).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** 목록 파일 `{"version":…, "images":{"amd64":{url, sha256}, "arm64":{…}}}` 에서 그 아키텍처의 항목. */
+export function pickManifestImage(body, arch) {
+    if (!body || typeof body !== "object")
+        return "목록 파일이 JSON 객체가 아닙니다";
+    const images = body.images;
+    if (!images || typeof images !== "object")
+        return "목록 파일에 images 가 없습니다";
+    const it = images[arch];
+    if (!it || typeof it !== "object")
+        return `목록 파일에 ${arch} 이미지가 없습니다`;
+    const { url, sha256 } = it;
+    if (typeof url !== "string" || !url)
+        return `목록 파일의 ${arch} 항목에 url 이 없습니다`;
+    if (typeof sha256 !== "string" || !/^[0-9a-fA-F]{64}$/.test(sha256))
+        return `목록 파일의 ${arch} 항목에 sha256 지문이 없습니다`;
+    return { url, sha256: sha256.toLowerCase() };
+}
+/** 받아서 지문을 보며 임시 파일에 쓰고, 맞으면 dest 로 옮긴다. 성공이면 null, 실패면 이유. */
+async function downloadVerified(ctx, url, dest, expected) {
+    let res;
+    try {
+        res = await ctx.fetch(url, { redirect: "follow" });
+    }
+    catch (e) {
+        const err = e;
+        return `받지 못했습니다(${err.cause?.code ?? err.cause?.message ?? err.message})`;
+    }
+    if (!res.ok || !res.body) {
+        try {
+            await res.body?.cancel();
+        }
+        catch {
+            /* 본문은 읽지 않는다 */
+        }
+        return `받지 못했습니다(HTTP ${res.status})`;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    const tmp = `${dest}.part-${process.pid}`;
+    const h = createHash("sha256");
+    const body = res.body;
+    try {
+        await pipeline((async function* () {
+            for await (const chunk of body) {
+                h.update(chunk);
+                yield chunk;
+            }
+        })(), createWriteStream(tmp));
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        return `내려받다가 멈췄습니다(${e.message})`;
+    }
+    const got = h.digest("hex");
+    if (got !== expected) {
+        rmSync(tmp, { force: true });
+        return `받은 파일의 내용 지문이 목록과 다릅니다(목록 ${expected}, 받은 파일 ${got})`;
+    }
+    renameSync(tmp, dest);
+    return null;
+}
+async function imageFromDownload(ctx, docker, info) {
+    const mUrl = manifestUrl(ctx.env);
+    const arch = normArch(info.architecture) ?? normArch(process.arch);
+    if (!arch) {
+        return {
+            ok: false,
+            detail: `Docker 아키텍처 ${info.architecture ?? "알 수 없음"} 용 이미지가 없습니다(amd64, arm64 만)`,
+            fix: "amd64 또는 arm64 컴퓨터에서 점검하세요.",
+        };
+    }
+    let body;
+    try {
+        if (!/^https?:\/\//i.test(mUrl))
+            throw new Error(`http 나 https 주소가 아닙니다(${mUrl})`);
+        const res = await ctx.fetch(mUrl, { signal: AbortSignal.timeout(MANIFEST_TIMEOUT_MS) });
+        if (!res.ok) {
+            try {
+                await res.body?.cancel();
+            }
+            catch {
+                /* 본문은 읽지 않는다 */
+            }
+            return { ok: false, detail: `점검용 이미지 목록을 받지 못했습니다(HTTP ${res.status}, ${mUrl})`, fix: downloadFix() };
+        }
+        body = JSON.parse(await res.text());
+    }
+    catch (e) {
+        const err = e;
+        const why = err.name === "TimeoutError" || err.name === "AbortError"
+            ? `${MANIFEST_TIMEOUT_MS / 1000}초 안에 응답이 없음`
+            : err.cause?.code ?? err.cause?.message ?? err.message;
+        return { ok: false, detail: `점검용 이미지 목록에 닿지 못했습니다(${why}, ${mUrl})`, fix: downloadFix() };
+    }
+    const picked = pickManifestImage(body, arch);
+    if (typeof picked === "string")
+        return { ok: false, detail: `${picked}(${mUrl})`, fix: downloadFix() };
+    let tarUrl;
+    try {
+        tarUrl = new URL(picked.url, mUrl).toString();
+    }
+    catch {
+        return { ok: false, detail: `목록 파일의 주소를 읽지 못했습니다(${picked.url})`, fix: downloadFix() };
+    }
+    if (!/^https?:\/\//i.test(tarUrl)) {
+        return { ok: false, detail: `목록 파일의 주소가 http 나 https 가 아닙니다(${tarUrl})`, fix: downloadFix() };
+    }
+    const name = basename(new URL(tarUrl).pathname).replace(/[^A-Za-z0-9._-]/g, "_") ||
+        `aiakiv-engine-enterprise-${ENTERPRISE_ENGINE_VERSION}-${arch}.tar`;
+    const dest = join(ctx.home, ".aiakiv", "cache", name);
+    let reused = false;
+    if (existsSync(dest) && (await sha256File(dest)) === picked.sha256) {
+        reused = true;
+        ctx.err(`이미 받아 둔 파일을 씁니다: ${dest}`);
+    }
+    else {
+        ctx.err(`점검용 이미지(${arch})를 내려받는 중입니다: ${tarUrl}`);
+        const why = await downloadVerified(ctx, tarUrl, dest, picked.sha256);
+        if (why)
+            return { ok: false, detail: `점검용 이미지를 ${why}`, fix: downloadFix() };
+    }
+    const loaded = await dockerLoad(ctx, docker, dest);
+    if (!loaded.ok)
+        return loaded;
+    return {
+        ok: true,
+        image: loaded.image,
+        source: "download",
+        sha256: picked.sha256,
+        detail: `${reused ? "받아 둔" : "내려받은"} ${arch} 이미지를 불러왔습니다(${dest}, sha256 ${picked.sha256})`,
+    };
+}
+async function resolveImage(ctx, docker, info, opts) {
+    if (opts.image !== undefined) {
+        if (await imageExists(ctx, docker, opts.image)) {
+            return { ok: true, image: opts.image, source: "flag", detail: `이 컴퓨터에 있는 이미지 ${opts.image} 를 씁니다` };
+        }
+        return {
+            ok: false,
+            detail: `이 컴퓨터에 이미지 ${opts.image} 가 없습니다`,
+            fix: "docker images 로 이름과 판을 확인하거나, 내려받은 tar 파일을 --image-tar 로 주세요.",
+        };
+    }
+    if (opts.imageTar !== undefined)
+        return imageFromTar(ctx, docker, opts.imageTar);
+    const ref = defaultImageRef();
+    if (await imageExists(ctx, docker, ref)) {
+        return { ok: true, image: ref, source: "local", detail: `이 컴퓨터에 있는 이미지 ${ref} 를 씁니다` };
+    }
+    return imageFromDownload(ctx, docker, info);
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const label = (s) => STATUS_LABEL[s] ?? String(s);
+/** 사람용 한 줄. 점검의 detail 은 160자에서 자른다(전체는 보고서 파일에 있다). 이 명령 자신의 줄은 자르지 않는다. */
+function stepText(step, status, detail, ms, max = 160) {
+    const flat = typeof detail === "string" ? detail.replace(/\s+/g, " ") : "";
+    const d = flat ? ` ${max === Infinity ? flat : truncate(flat, max)}` : "";
+    const t = typeof ms === "number" ? ` (${ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}초`})` : "";
+    return `[${label(status)}] ${step}${t}${d}`;
+}
+/** 로그인 대기 줄을 눈에 띄게. 브라우저 방식은 login_url, 기기 코드 방식은 주소와 코드. */
+function loginLines(w) {
+    const timeout = typeof w.timeout_s === "number" ? `(최대 ${Math.round(w.timeout_s)}초 기다립니다)` : "";
+    const bar = "=".repeat(64);
+    const lines = ["", bar];
+    if (typeof w.user_code === "string") {
+        lines.push(`로그인이 필요합니다${timeout}. 휴대전화나 다른 컴퓨터의 브라우저에서 이 주소를 열고 코드를 넣으세요.`);
+        lines.push(`  주소: ${String(w.verification_uri ?? "")}`);
+        lines.push(`  코드: ${w.user_code}`);
+        if (typeof w.verification_uri_complete === "string")
+            lines.push(`  코드가 들어간 주소: ${w.verification_uri_complete}`);
+    }
+    else {
+        lines.push(`로그인이 필요합니다${timeout}. 이 컴퓨터의 브라우저에서 이 주소를 열고 시험용 계정으로 로그인하세요.`);
+        lines.push(`  ${String(w.login_url ?? "")}`);
+    }
+    lines.push("비밀번호는 이 화면에 넣지 않습니다. AI 가 점검을 돌리는 경우에도 로그인은 사람이 합니다.", bar, "");
+    return lines;
+}
+function summaryText(s) {
+    const m = isObj(s) ? s : {};
+    return ["pass", "warn", "fail", "skip", "info"].map((k) => `${STATUS_LABEL[k]} ${Number(m[k] ?? 0)}`).join(", ");
+}
+/** 사람용 끝 정리: 결과, 고칠 것, 발급 조건, 보고서 위치. */
+function finalLines(report, files) {
+    const lines = [""];
+    const s = isObj(report.summary) ? report.summary : {};
+    const fails = Number(s.fail ?? 0);
+    lines.push(report.ok ? `결과: 실패 없음(${summaryText(s)})` : `결과: 실패 ${fails}건(${summaryText(s)})`);
+    const checks = Array.isArray(report.checks) ? report.checks.filter(isObj) : [];
+    const todo = checks.filter((c) => typeof c.fix === "string" && c.fix && (c.status === "fail" || c.status === "warn"));
+    if (todo.length) {
+        lines.push("", "고칠 것:");
+        todo.sort((a, b) => (a.status === b.status ? 0 : a.status === "fail" ? -1 : 1));
+        for (const c of todo)
+            lines.push(`  [${label(c.status)}] ${String(c.id)}: ${String(c.fix)}`);
+    }
+    const q = isObj(report.quote) ? report.quote : {};
+    const left = Array.isArray(q.failed_required) ? q.failed_required.map(String) : [];
+    lines.push("", q.eligible === true
+        ? `견적과 라이선스 발급 조건(quote.eligible): 충족(로그인 방식 ${String(q.mode ?? "-")})`
+        : `견적과 라이선스 발급 조건(quote.eligible): 충족하지 못함(로그인 방식 ${String(q.mode ?? "-")}` +
+            `${left.length ? `, 채우지 못한 필수 점검: ${left.join(", ")}` : ""})`);
+    if (files.length)
+        lines.push(`보고서: ${files.join(", ")}`);
+    return lines;
+}
+// ---- 실행 -----------------------------------------------------------------------------------
+export async function runEnterprisePrecheck(ctx, opts) {
+    const json = !!opts.json;
+    /** 이 명령 자신의 단계 줄. --json 이면 한 줄 JSON, 아니면 사람용 한 줄(실패면 고칠 것도). */
+    const step = (line) => {
+        if (json) {
+            ctx.out(JSON.stringify(line));
+            return;
+        }
+        ctx.out(stepText(line.step, line.status, line.detail, undefined, Infinity));
+        if (line.fix)
+            ctx.out(`        고칠 것: ${line.fix}`);
+    };
+    const failStep = (id, f, code) => {
+        step({ step: id, status: "fail", detail: f.detail, fix: f.fix });
+        if (json)
+            ctx.err(`${f.detail}. ${f.fix}`);
+        return code;
+    };
+    // 1. 설정 파일. 그 파일이 있는 폴더가 작업 폴더이고 컨테이너의 /config 로 붙는다.
+    const configPath = resolve(ctx.cwd, opts.config ?? DEFAULT_PRECHECK_CONFIG);
+    let configOk = false;
+    try {
+        configOk = statSync(configPath).isFile();
+    }
+    catch {
+        /* 아래에서 알린다 */
+    }
+    if (!configOk) {
+        return failStep("cli.config", {
+            ok: false,
+            detail: `설정 파일이 없습니다: ${configPath}`,
+            fix: `예시 파일 ${EXAMPLE_PRECHECK_CONFIG} 을 ${DEFAULT_PRECHECK_CONFIG} 로 복사해 고친 뒤 그 폴더에서 다시 돌리거나, --config 로 설정 파일을 주세요.`,
+        }, EXIT_USAGE);
+    }
+    const workDir = dirname(configPath);
+    const configName = basename(configPath);
+    const outRel = relativeOut(opts.out ?? DEFAULT_PRECHECK_OUT);
+    if (!outRel) {
+        return failStep("cli.config", {
+            ok: false,
+            detail: `--out 은 설정 파일이 있는 폴더(${workDir}) 안의 상대 경로여야 합니다(받은 값: ${opts.out})`,
+            fix: `--out ${DEFAULT_PRECHECK_OUT} 처럼 그 폴더 안의 폴더 이름을 주세요.`,
+        }, EXIT_USAGE);
+    }
+    const envPath = join(workDir, ".env");
+    const envFile = existsSync(envPath) ? envPath : null;
+    // 2. Docker.
+    const d = await checkDocker(ctx);
+    if (!d.ok)
+        return failStep("cli.docker", d, EXIT_DOCKER);
+    step({ step: "cli.docker", status: "pass", detail: d.detail });
+    // 3. 이미지.
+    const img = await resolveImage(ctx, d.docker, d.info, opts);
+    if (!img.ok) {
+        const f = img;
+        if (json) {
+            ctx.out(JSON.stringify({ step: "cli.image", status: "fail", image: null, source: null, detail: f.detail, fix: f.fix }));
+            ctx.err(`${f.detail}. ${f.fix}`);
+        }
+        else
+            step({ step: "cli.image", status: "fail", detail: f.detail, fix: f.fix });
+        return EXIT_IMAGE;
+    }
+    const imageLine = {
+        step: "cli.image", status: "pass", image: img.image, source: img.source, detail: img.detail,
+    };
+    if (img.sha256)
+        imageLine.sha256 = img.sha256;
+    step(imageLine);
+    // 4. compose 파일.
+    const composeFile = join(workDir, PRECHECK_DIR, "compose.yml");
+    writeFileAtomic(composeFile, composeYaml({ image: img.image, workDir, envFile, platform: ctx.platform }));
+    const outHost = join(workDir, ...outRel.split("/"));
+    // 5. 실행. 점검의 표준 출력을 줄 단위 JSON 으로 읽는다.
+    const args = composeRunArgs({
+        composeFile, configName, device: opts.device, noLogin: opts.noLogin,
+        only: opts.only, skip: opts.skip, redactClaims: opts.redactClaims,
+    });
+    if (!json)
+        ctx.out(`점검을 시작합니다(이미지 ${img.image}, 설정 ${configPath}).`);
+    const st = {
+        final: null, precheckError: null, stderrTail: [], opens: [],
+    };
+    const onWaiting = (w) => {
+        for (const l of loginLines(w))
+            (json ? ctx.err : ctx.out)(l);
+        const url = typeof w.login_url === "string" ? w.login_url : "";
+        if (opts.device || opts.noBrowser || typeof w.user_code === "string" || !/^https?:\/\//i.test(url))
+            return;
+        st.opens.push(ctx.openUrl(url).then((ok) => {
+            if (!ok)
+                ctx.err("브라우저를 열지 못했습니다. 위 주소를 직접 여세요.");
+        }, () => ctx.err("브라우저를 열지 못했습니다. 위 주소를 직접 여세요.")));
+    };
+    const onStdout = (line) => {
+        const t = line.trim();
+        let obj = null;
+        if (t.startsWith("{")) {
+            try {
+                obj = JSON.parse(t);
+            }
+            catch {
+                obj = null;
+            }
+        }
+        if (!isObj(obj)) {
+            if (!json && t)
+                ctx.err(line);
+            return;
+        }
+        // --json 이면 점검의 줄은 바꾸지 않고 그대로 낸다.
+        if (json)
+            ctx.out(line);
+        if (obj.tool === PRECHECK_TOOL) {
+            st.final = obj;
+            return;
+        }
+        if (obj.ok === false && typeof obj.error === "string") {
+            st.precheckError = obj;
+            if (!json)
+                ctx.err(`점검이 설정이나 인자를 받아들이지 않았습니다(${obj.error}): ${String(obj.message ?? "")}`);
+            return;
+        }
+        if (obj.step === "oidc.login" && obj.status === "waiting") {
+            onWaiting(obj);
+            return;
+        }
+        if (!json && typeof obj.step === "string")
+            ctx.out(stepText(obj.step, obj.status, obj.detail, obj.ms));
+    };
+    const onStderr = (line) => {
+        if (!json) {
+            ctx.err(line);
+            return;
+        }
+        if (line.trim())
+            st.stderrTail = [...st.stderrTail, line].slice(-5);
+    };
+    const res = await ctx.runLines(d.docker, args, { cwd: workDir, onStdout, onStderr });
+    await Promise.all(st.opens);
+    if (res.error) {
+        return failStep("cli.run", {
+            ok: false,
+            detail: `docker compose run 을 실행하지 못했습니다: ${res.error}`,
+            fix: "Docker 가 켜져 있는지 확인하고 다시 돌리세요.",
+        }, EXIT_RUN_FAILED);
+    }
+    if (!st.final) {
+        if (res.code === EXIT_USAGE && st.precheckError)
+            return EXIT_USAGE;
+        const tail = st.stderrTail.length ? `: ${st.stderrTail.join(" / ")}` : "";
+        return failStep("cli.run", {
+            ok: false,
+            detail: `점검이 보고서를 내지 못하고 끝났습니다(종료 코드 ${res.code ?? "없음"})${json ? tail : ""}`,
+            fix: `위 오류를 보고 고친 뒤 다시 돌리세요. 포트 7777 을 다른 프로그램이 쓰고 있으면 끄고 다시 돌리세요(compose 파일 ${composeFile}).`,
+        }, EXIT_RUN_FAILED);
+    }
+    // 보고서 파일. 점검 본체의 --out 과 같은 이름과 형식(report.json, report.md)으로 이 CLI 가 쓴다.
+    const reportJson = join(outHost, "report.json");
+    const reportMd = join(outHost, "report.md");
+    let wrote = true;
+    try {
+        mkdirSync(outHost, { recursive: true });
+        writeFileSync(reportJson, reportJsonText(st.final), "utf8");
+        writeFileSync(reportMd, toMarkdown(st.final, reportLanguage(ctx.env, readTextIfExists(configPath))), "utf8");
+    }
+    catch (e) {
+        wrote = false;
+        ctx.err(`보고서 파일을 쓰지 못했습니다(${outHost}): ${e.message}`);
+    }
+    const files = wrote ? [reportJson, reportMd] : [];
+    if (!json)
+        for (const l of finalLines(st.final, files))
+            ctx.out(l);
+    else if (files.length)
+        ctx.err(`보고서: ${files.join(", ")}`);
+    if (!wrote)
+        return EXIT_RUN_FAILED;
+    if (res.code === EXIT_OK || res.code === EXIT_FAILED || res.code === EXIT_USAGE)
+        return res.code;
+    return st.final.ok ? EXIT_OK : EXIT_FAILED;
+}