aiakiv 0.2.1 → 0.3.0

package/dist/local/portable.js

@@ -0,0 +1,495 @@
+// `aiakiv local export` 와 `aiakiv local import` — 자체 설치판(무료 5인 엔진) 팀 기억을 파일로 내보내고 받는다
+// (K2G docs/211 BP-172 §5.1 표, §5.2, §7). 본체는 엔진 컨테이너 안의 `aiakiv-admin export`, `aiakiv-admin import`
+// (K2G src/k2g/selfhost/admin/exporting.py, importing.py)이고, 이 명령은 그 앞뒤를 맡는다: Docker 확인, 엔진
+// 컨테이너 찾기, 호스트 파일을 컨테이너 안으로(또는 거꾸로) 옮기기(docker cp), docker exec 로 부르기, 옮기려고 만든
+// 컨테이너 안 임시 폴더 지우기. 파일 내용(아카이브, 벡터)은 읽지도 바꾸지도 않는다. 벡터 처리는 엔진이 한다.
+//
+// 출력(§5.2): 표준 출력은 JSON 만 낸다. export 는 JSON 한 문서. import 는 엔진의 줄(진행 `{"step","done","total"}`,
+// 마지막 줄이 결과)을 받는 대로 바꾸지 않고 낸다. 엔진이 실패를 알린 JSON(이유, 남은 수, record id)도 그대로다.
+// 사람용 안내와 엔진의 로그는 표준 오류로 낸다.
+//
+// 종료 코드: 엔진의 것(0 성공, 2 입력 오류나 --yes 없이 계획만, 3 거절, 4 엔진 DB 연결 실패, 5 가져오기 검증 실패,
+// 1 예기치 못한 오류)을 그대로 돌려준다. 이 명령의 것은 enterprise precheck 와 같은 번호로 2 인자 오류(파일 없음,
+// 호스트에 이미 있는 파일), 4 Docker 를 쓸 수 없음이나 엔진 컨테이너가 떠 있지 않음, 1 컨테이너와 파일을 주고받지
+// 못함이나 엔진이 결과 없이 끝남. 인자 해석의 오류(2)는 main.ts 가 낸다.
+//
+// 경로: `--to` 와 import 의 <파일> 은 호스트 경로이고(작업 폴더 기준, Windows 드라이브 문자와 역슬래시와 공백 그대로),
+// 엔진에는 이 명령이 만든 컨테이너 안 경로(/data/exports/aiakiv-cli-…, /data/imports/aiakiv-cli-…)만 넘긴다.
+// docker cp 에는 호스트 쪽을 늘 절대 경로로 준다(상대 경로의 `C:` 같은 콜론을 컨테이너 이름으로 읽지 않게).
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { failReason } from "../proc.js";
+import { daemonFix, dockerInstallUrl, isPermissionDenied, parseDockerInfo } from "./checks.js";
+/** enterprise precheck 와 같은 번호(src/enterprise/precheck.ts). */
+export const EXIT_OK = 0;
+export const EXIT_RUN_FAILED = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_DOCKER = 4;
+/** 엔진 compose 의 서비스 이름(K2G packaging/selfhost/aiakiv-compose.yml). 같은 이미지의 control 과 가른다. */
+export const ENGINE_SERVICE = "engine";
+/** 컨테이너 안 자리. 엔진의 데이터 볼륨(DATA_DIR=/data) 아래, K2G packaging/selfhost/README.md 3.1절과 같은 폴더. */
+export const CONTAINER_EXPORT_DIR = "/data/exports";
+export const CONTAINER_IMPORT_DIR = "/data/imports";
+/** 이 명령이 컨테이너 안에 만드는 임시 폴더 이름의 머리. 이 이름의 폴더만 지운다. */
+export const TEMP_PREFIX = "aiakiv-cli-";
+/** 엔진 compose 파일의 기본 자리(사람에게 보이는 안내에만 쓴다). */
+export const ENGINE_COMPOSE = "~/.aiakiv/engine/aiakiv-compose.yml";
+const DOCKER_TIMEOUT_MS = 30_000;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** 실패를 JSON 한 문서로 표준 출력에, 사람용 한 줄을 표준 오류에 낸다. */
+function emitFail(ctx, f) {
+    ctx.out(JSON.stringify({ ok: false, error: f.error, message: f.message, fix: f.fix, ...(f.extra ?? {}) }));
+    ctx.err(`${f.message}. ${f.fix}`);
+    return f.code;
+}
+/** 긴 오류 출력에서 첫 줄만, 너무 길면 자른다. */
+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;
+}
+/** 호스트 경로를 작업 폴더 기준 절대 경로로. Windows 는 win32 규칙(드라이브 문자, 역슬래시)으로 푼다. */
+export function hostPath(cwd, p, platform) {
+    return (platform === "win32" ? win32 : posix).resolve(cwd, p);
+}
+/** 호스트 경로의 마지막 이름. Windows 는 역슬래시도 구분자로 본다. */
+export function hostBase(p, platform) {
+    return (platform === "win32" ? win32 : posix).basename(p);
+}
+/** 컨테이너 안 임시 폴더. 시각과 무작위 글자로 겹치지 않게 한다(동시에 두 번 돌려도). */
+export function tempDirName(now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+    return `${TEMP_PREFIX}${stamp}-${randomBytes(3).toString("hex")}`;
+}
+// ---- Docker 와 엔진 컨테이너 -----------------------------------------------------------------
+/** docker 실행 파일과 데몬. 안 되면 종료 코드 4 의 실패. */
+async function dockerReady(ctx) {
+    const docker = ctx.which("docker");
+    if (!docker) {
+        return {
+            ok: false,
+            fail: {
+                error: "docker_not_found",
+                message: "docker 실행 파일을 찾지 못했습니다",
+                fix: `이 명령은 엔진이 설치된 컴퓨터에서 실행하세요. Docker 가 없으면 설치하세요: ${dockerInstallUrl(ctx.platform)}`,
+                code: EXIT_DOCKER,
+            },
+        };
+    }
+    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,
+            fail: {
+                error: "docker_unreachable",
+                message: `Docker 데몬에 닿지 못했습니다: ${oneLine(reason)}`,
+                fix: daemonFix(ctx.platform, isPermissionDenied(`${reason}\n${r.stderr}`)),
+                code: EXIT_DOCKER,
+            },
+        };
+    }
+    return { ok: true, docker };
+}
+/** `docker ps -a` 의 `--format` 값. 칸은 탭으로 나눈다. */
+export const PS_FORMAT = '{{.ID}}\t{{.Image}}\t{{.Names}}\t{{.Label "com.docker.compose.service"}}\t{{.State}}';
+export function parseContainerRows(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .filter((l) => l.trim())
+        .map((l) => {
+        const [id = "", image = "", names = "", service = "", state = ""] = l.split("\t");
+        // 연결(link)이 있으면 Names 칸에 이름이 쉼표로 여럿 온다. 앞의 것이 컨테이너 자신의 이름이다.
+        return { id: id.trim(), image: image.trim(), name: names.split(",")[0].trim(), service: service.trim(), state: state.trim() };
+    });
+}
+/** 무료판(aiakiv/engine)과 유료 기업판(aiakiv/engine-enterprise) 엔진 이미지. 레지스트리 앞머리는 무엇이든. */
+export function isEngineImage(image) {
+    return /(^|\/)aiakiv\/engine(-enterprise)?(:|@|$)/i.test(image);
+}
+/**
+ * 엔진 컨테이너. 엔진 이미지이면서 compose 서비스가 engine 이거나 compose 밖에서 띄운 것. 같은 이미지로 도는
+ * 유료 기업판 control 컨테이너는 서비스 이름으로 뺀다. local doctor 의 isEngineContainer(이미지로 찾기)와 같은
+ * 생각이고, control 을 가르려고 서비스 라벨을 더 본다.
+ */
+export function isEngineRow(r) {
+    return isEngineImage(r.image) && (r.service === ENGINE_SERVICE || r.service === "");
+}
+const upFix = () => `엔진을 켜세요: docker compose -f ${ENGINE_COMPOSE} up -d (설치 폴더가 다르면 그 폴더의 compose 파일로). ` +
+    "엔진이 다른 이름으로 떠 있으면 --container <이름> 으로 고르세요.";
+/**
+ * 컨테이너 목록에서 엔진 컨테이너(멈춘 것 포함)와 그중 떠 있는 것. findEngine 과 local doctor 의 engine.vectors 가
+ * 같이 쓴다. 떠 있는 것이 하나면 그것이 엔진이다.
+ */
+export function pickEngine(rows) {
+    const engines = rows.filter(isEngineRow);
+    return { engines, running: engines.filter((x) => x.state === "running") };
+}
+/** `docker ps -a` 로 모든 컨테이너(멈춘 것 포함)를 읽는다. 실패하면 RunResult 를 그대로 돌려준다. */
+export async function listContainers(ctx, docker) {
+    const r = await ctx.run(docker, ["ps", "-a", "--no-trunc", "--format", PS_FORMAT], {
+        capture: true,
+        timeoutMs: DOCKER_TIMEOUT_MS,
+    });
+    return r.ok ? { ok: true, rows: parseContainerRows(r.stdout) } : { ok: false, run: r };
+}
+/** 떠 있는 엔진 컨테이너 하나. 없거나 여럿이면 실패(안내 포함). */
+export async function findEngine(ctx, docker, want) {
+    const listed = await listContainers(ctx, docker);
+    if (!listed.ok) {
+        const r = listed.run;
+        return {
+            ok: false,
+            fail: {
+                error: "docker_unreachable",
+                message: `docker ps 가 실패했습니다: ${oneLine(failReason(r))}`,
+                fix: daemonFix(ctx.platform, isPermissionDenied(r.stderr)),
+                code: EXIT_DOCKER,
+            },
+        };
+    }
+    const rows = listed.rows;
+    if (want) {
+        // 사람이 고른 것은 이미지를 따지지 않는다(직접 붙인 태그일 수 있다). 이름이나 id 앞부분으로 찾는다.
+        const hit = rows.find((x) => x.name === want || (want.length >= 4 && x.id.startsWith(want)));
+        if (!hit) {
+            return {
+                ok: false,
+                fail: {
+                    error: "engine_not_found",
+                    message: `--container ${want} 인 컨테이너가 없습니다`,
+                    fix: "docker ps 로 엔진 컨테이너 이름을 확인하고 다시 주세요.",
+                    code: EXIT_DOCKER,
+                },
+            };
+        }
+        if (hit.state !== "running") {
+            return {
+                ok: false,
+                fail: {
+                    error: "engine_not_running",
+                    message: `엔진 컨테이너 ${hit.name} 가 떠 있지 않습니다(상태 ${hit.state || "알 수 없음"})`,
+                    fix: `docker start ${hit.name} 로 켜거나, ${upFix()}`,
+                    code: EXIT_DOCKER,
+                },
+            };
+        }
+        return { ok: true, container: hit };
+    }
+    const pick = pickEngine(rows);
+    if (pick.running.length === 1)
+        return { ok: true, container: pick.running[0] };
+    const running = pick.running;
+    if (running.length > 1) {
+        return {
+            ok: false,
+            fail: {
+                error: "engine_ambiguous",
+                message: `떠 있는 엔진 컨테이너가 여럿입니다: ${running.map((x) => x.name).join(", ")}`,
+                fix: "--container <이름> 으로 하나를 고르세요.",
+                code: EXIT_USAGE,
+                extra: { containers: running.map((x) => x.name) },
+            },
+        };
+    }
+    const stopped = pick.engines.map((x) => `${x.name}(${x.state || "알 수 없음"})`);
+    return {
+        ok: false,
+        fail: {
+            error: "engine_not_running",
+            message: stopped.length
+                ? `엔진 컨테이너가 떠 있지 않습니다: ${stopped.join(", ")}`
+                : "엔진 컨테이너를 찾지 못했습니다(aiakiv/engine 이미지로 도는 컨테이너가 없습니다)",
+            fix: upFix(),
+            code: EXIT_DOCKER,
+        },
+    };
+}
+/** 컨테이너 안 임시 폴더를 만든다. 엔진의 기본 사용자로 만들어 엔진이 그 안에 쓸 수 있게 한다. */
+async function makeTempDir(ctx, docker, c, dir) {
+    const r = await ctx.run(docker, ["exec", c.name, "mkdir", "-p", dir], { capture: true, timeoutMs: DOCKER_TIMEOUT_MS });
+    if (r.ok)
+        return null;
+    return {
+        error: "container_mkdir_failed",
+        message: `엔진 컨테이너 ${c.name} 안에 ${dir} 를 만들지 못했습니다: ${oneLine(failReason(r))}`,
+        fix: "엔진이 떠 있는지(docker ps), 데이터 볼륨 /data 에 쓸 수 있는지 확인하세요.",
+        code: EXIT_RUN_FAILED,
+    };
+}
+/**
+ * 이 명령이 만든 임시 폴더를 지운다. docker cp 로 넣은 파일은 root 소유라 root 로 지운다. 이 명령이 만든 이름
+ * (TEMP_PREFIX)이 아니면 지우지 않는다. 실패해도 결과는 바꾸지 않고 표준 오류에 알린다.
+ */
+async function removeTempDir(ctx, docker, c, dir) {
+    if (!posix.basename(dir).startsWith(TEMP_PREFIX))
+        return false;
+    const r = await ctx.run(docker, ["exec", "-u", "0", c.name, "rm", "-rf", dir], {
+        capture: true,
+        timeoutMs: DOCKER_TIMEOUT_MS,
+    });
+    if (!r.ok) {
+        ctx.err(`엔진 컨테이너 안의 임시 폴더 ${dir} 를 지우지 못했습니다(${oneLine(failReason(r))}). ` +
+            `docker exec -u 0 ${c.name} rm -rf ${dir} 로 지우세요.`);
+    }
+    return r.ok;
+}
+/** 엔진의 JSON 한 문서(사람용 들여쓰기 JSON 이어도). 못 읽으면 null. */
+export function parseEngineDoc(stdout) {
+    const t = stdout.trim();
+    const start = t.indexOf("{");
+    if (start < 0)
+        return null;
+    try {
+        const v = JSON.parse(t.slice(start));
+        return isObj(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 엔진의 종료 코드가 없거나(실행 실패) 엔진의 결과가 없을 때의 실패. */
+function noResultFail(command, code, stderrTail) {
+    const tail = stderrTail.length ? `: ${stderrTail.join(" / ")}` : "";
+    return {
+        error: "engine_no_result",
+        message: `aiakiv-admin ${command} 가 결과 없이 끝났습니다(종료 코드 ${code ?? "없음"})${tail}`,
+        fix: "엔진 로그(docker logs <엔진 컨테이너>)를 보고 고친 뒤 다시 돌리세요. 엔진 판이 이 명령보다 오래됐으면 엔진을 새 판으로 올리세요.",
+        code: EXIT_RUN_FAILED,
+    };
+}
+// ---- export ---------------------------------------------------------------------------------
+export async function runLocalExport(ctx, opts) {
+    const hp = ctx.platform === "win32" ? win32 : posix;
+    // 1. 호스트 쪽 자리. 이미 있는 파일은 --yes 가 있어야 덮어쓴다. 폴더(이미 있는 폴더, 또는 끝이 / 나 \ 인 경로)면
+    //    그 안에 둔다(엔진의 --to 와 같은 규칙).
+    const dest = hostPath(ctx.cwd, opts.to, ctx.platform);
+    const destIsDir = isDir(dest) || (ctx.platform === "win32" ? /[\\/]$/ : /\/$/).test(opts.to);
+    if (!destIsDir && existsSync(dest) && !opts.yes) {
+        return emitFail(ctx, {
+            error: "target_exists",
+            message: `${dest} 가 이미 있습니다`,
+            fix: "덮어쓰려면 --yes 를 붙이거나, --to 에 다른 파일 이름이나 폴더를 주세요.",
+            code: EXIT_USAGE,
+            extra: { path: dest },
+        });
+    }
+    // 2. Docker 와 엔진 컨테이너.
+    const d = await dockerReady(ctx);
+    if (!d.ok)
+        return emitFail(ctx, d.fail);
+    const e = await findEngine(ctx, d.docker, opts.container);
+    if (!e.ok)
+        return emitFail(ctx, e.fail);
+    const c = e.container;
+    // 3. 컨테이너 안 임시 폴더에 내보낸다. 새로 만든 빈 폴더라 엔진에는 --yes 를 준다(폴더가 이미 있다는 거절을 피하려고).
+    //    엔진은 도메인이 하나면 그 폴더 안에 <팀>_<도메인>_<시각>.mweft.tar.gz 를, 여럿이면 그 폴더에 묶음을 쓴다.
+    const tmp = posix.join(CONTAINER_EXPORT_DIR, tempDirName());
+    const mk = await makeTempDir(ctx, d.docker, c, tmp);
+    if (mk)
+        return emitFail(ctx, mk);
+    const args = ["exec", c.name, "aiakiv-admin", "export", opts.team, "--to", tmp, "--yes", "--json"];
+    if (opts.domain !== undefined)
+        args.push("--domain", opts.domain);
+    const stdout = [];
+    const stderrTail = [];
+    const res = await ctx.runLines(d.docker, args, {
+        onStdout: (l) => stdout.push(l),
+        onStderr: (l) => {
+            ctx.err(l);
+            if (l.trim())
+                stderrTail.splice(0, stderrTail.length, ...[...stderrTail, l].slice(-5));
+        },
+    });
+    const doc = res.error ? null : parseEngineDoc(stdout.join("\n"));
+    if (!doc || typeof doc.ok !== "boolean") {
+        await removeTempDir(ctx, d.docker, c, tmp);
+        if (res.error) {
+            return emitFail(ctx, {
+                error: "docker_exec_failed",
+                message: `docker exec 를 실행하지 못했습니다: ${res.error}`,
+                fix: "Docker 가 켜져 있는지 확인하고 다시 돌리세요.",
+                code: EXIT_RUN_FAILED,
+            });
+        }
+        return emitFail(ctx, noResultFail("export", res.code, stderrTail));
+    }
+    if (doc.ok !== true || res.code !== EXIT_OK) {
+        // 엔진의 실패는 그 JSON 과 종료 코드 그대로.
+        await removeTempDir(ctx, d.docker, c, tmp);
+        ctx.out(JSON.stringify(doc));
+        return res.code ?? EXIT_RUN_FAILED;
+    }
+    // 4. 호스트로 꺼낸다. 하나(archive)는 파일, 묶음(bundle)은 폴더의 내용을 --to 폴더에.
+    const kind = doc.kind === "bundle" ? "bundle" : "archive";
+    const cpath = typeof doc.path === "string" && doc.path ? doc.path : tmp;
+    let target;
+    let src;
+    if (kind === "archive") {
+        target = destIsDir ? hp.join(dest, posix.basename(cpath)) : dest;
+        src = cpath;
+    }
+    else {
+        // 묶음은 폴더의 내용(`<폴더>/.`)을 --to 폴더에 꺼낸다. 없는 폴더면 docker cp 가 만든다.
+        target = dest;
+        src = `${cpath.replace(/\/+$/, "")}/.`;
+        let refuse = null;
+        if (existsSync(dest) && !destIsDir) {
+            refuse = {
+                error: "target_not_directory",
+                message: `${dest} 는 파일인데, 이 팀은 도메인이 여럿이라 묶음(폴더)으로 나왔습니다`,
+                fix: "--to 에 새 폴더 경로를 주거나, --domain 으로 도메인 하나만 내보내세요.",
+                code: EXIT_USAGE,
+            };
+        }
+        else if (destIsDir && existsSync(hp.join(dest, "org_manifest.json")) && !opts.yes) {
+            refuse = {
+                error: "target_exists",
+                message: `${dest} 에 이미 묶음(org_manifest.json)이 있습니다`,
+                fix: "--to 에 새 폴더 경로를 주거나, 그 폴더의 묶음을 덮어쓰려면 --yes 를 붙이세요.",
+                code: EXIT_USAGE,
+            };
+        }
+        if (refuse) {
+            await removeTempDir(ctx, d.docker, c, tmp);
+            return emitFail(ctx, { ...refuse, extra: { path: dest, kind } });
+        }
+    }
+    try {
+        mkdirSync(kind === "bundle" ? dest : hp.dirname(target), { recursive: true });
+    }
+    catch {
+        /* 아래 docker cp 가 이유를 낸다 */
+    }
+    const cp = await ctx.run(d.docker, ["cp", `${c.name}:${src}`, target], { capture: true });
+    if (!cp.ok) {
+        // 꺼내지 못했으면 컨테이너 안 파일은 남겨 두고 손으로 꺼내는 명령을 알린다.
+        return emitFail(ctx, {
+            error: "copy_failed",
+            message: `내보낸 파일을 호스트로 꺼내지 못했습니다(docker cp): ${oneLine(failReason(cp))}`,
+            fix: `--to 의 폴더에 쓸 수 있는지 확인하세요. 파일은 엔진 컨테이너 안 ${cpath} 에 남아 있습니다: docker cp ${c.name}:${src} "${target}"`,
+            code: EXIT_RUN_FAILED,
+            extra: { container: { name: c.name, path: cpath, removed: false }, engine: doc },
+        });
+    }
+    const removed = await removeTempDir(ctx, d.docker, c, tmp);
+    ctx.out(JSON.stringify({
+        ok: true,
+        command: "local export",
+        kind,
+        path: target,
+        container: { name: c.name, path: cpath, removed },
+        engine: doc,
+    }));
+    return EXIT_OK;
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// ---- import ---------------------------------------------------------------------------------
+export async function runLocalImport(ctx, opts) {
+    // 1. 호스트 파일(아카이브 하나 또는 묶음 폴더). 내용은 엔진이 본다.
+    const src = hostPath(ctx.cwd, opts.file, ctx.platform);
+    if (!existsSync(src)) {
+        return emitFail(ctx, {
+            error: "file_not_found",
+            message: `${src} 가 없습니다`,
+            fix: "가져올 .mweft.tar.gz 파일(또는 묶음 폴더)의 경로를 확인하세요. 상대 경로는 지금 폴더 기준입니다.",
+            code: EXIT_USAGE,
+            extra: { path: src },
+        });
+    }
+    // 2. Docker 와 엔진 컨테이너.
+    const d = await dockerReady(ctx);
+    if (!d.ok)
+        return emitFail(ctx, d.fail);
+    const e = await findEngine(ctx, d.docker, opts.container);
+    if (!e.ok)
+        return emitFail(ctx, e.fail);
+    const c = e.container;
+    // 3. 컨테이너 안 임시 폴더로 옮긴다. 이름은 호스트의 것 그대로(엔진의 안내 문장에 나온다).
+    const tmp = posix.join(CONTAINER_IMPORT_DIR, tempDirName());
+    const mk = await makeTempDir(ctx, d.docker, c, tmp);
+    if (mk)
+        return emitFail(ctx, mk);
+    const cpath = posix.join(tmp, hostBase(src, ctx.platform) || "import.mweft.tar.gz");
+    const cp = await ctx.run(d.docker, ["cp", src, `${c.name}:${cpath}`], { capture: true });
+    if (!cp.ok) {
+        await removeTempDir(ctx, d.docker, c, tmp);
+        return emitFail(ctx, {
+            error: "copy_failed",
+            message: `파일을 엔진 컨테이너 안으로 옮기지 못했습니다(docker cp): ${oneLine(failReason(cp))}`,
+            fix: "파일을 읽을 수 있는지, 엔진의 데이터 볼륨에 빈 자리가 있는지 확인하세요.",
+            code: EXIT_RUN_FAILED,
+        });
+    }
+    ctx.out(JSON.stringify({ step: "cli.copy", done: 1, total: 1, container: c.name, path: cpath }));
+    // 4. 엔진의 가져오기. 줄마다 받는 대로 낸다. --yes 가 없으면 엔진이 계획만 내고 종료 코드 2 로 끝난다.
+    const args = ["exec", c.name, "aiakiv-admin", "import", cpath, "--team", opts.team];
+    if (opts.as !== undefined)
+        args.push("--as", opts.as);
+    if (opts.domain !== undefined)
+        args.push("--domain", opts.domain);
+    if (opts.dryRun)
+        args.push("--dry-run");
+    if (opts.resume)
+        args.push("--resume");
+    if (opts.yes)
+        args.push("--yes");
+    args.push("--json");
+    let result = null;
+    const stderrTail = [];
+    const res = await ctx.runLines(d.docker, args, {
+        onStdout: (line) => {
+            const t = line.trim();
+            let obj = null;
+            if (t.startsWith("{")) {
+                try {
+                    obj = JSON.parse(t);
+                }
+                catch {
+                    obj = null;
+                }
+            }
+            if (!isObj(obj)) {
+                // 표준 출력은 JSON 만 둔다. 엔진이 JSON 이 아닌 줄을 내면 표준 오류로 옮긴다.
+                if (t)
+                    ctx.err(line);
+                return;
+            }
+            ctx.out(line);
+            if (typeof obj.ok === "boolean")
+                result = obj;
+        },
+        onStderr: (l) => {
+            ctx.err(l);
+            if (l.trim())
+                stderrTail.splice(0, stderrTail.length, ...[...stderrTail, l].slice(-5));
+        },
+    });
+    // 5. 임시 폴더는 결과와 상관없이 지운다. --resume 은 호스트 파일을 다시 옮겨 오므로 남길 필요가 없다
+    //    (엔진은 파일 이름이 아니라 내용 지문으로 가져오기 기록을 찾는다).
+    await removeTempDir(ctx, d.docker, c, tmp);
+    if (res.error) {
+        return emitFail(ctx, {
+            error: "docker_exec_failed",
+            message: `docker exec 를 실행하지 못했습니다: ${res.error}`,
+            fix: "Docker 가 켜져 있는지 확인하고 다시 돌리세요.",
+            code: EXIT_RUN_FAILED,
+        });
+    }
+    const final = result;
+    if (!final)
+        return emitFail(ctx, noResultFail("import", res.code, stderrTail));
+    if (final.error === "confirmation_required") {
+        // --yes 없이 계획만 낸 경우(엔진 종료 코드 2). 사람에게 다음 걸음을 알린다.
+        ctx.err("계획만 냈습니다. 위 계획대로 가져오려면 같은 명령에 --yes 를 붙여 다시 돌리세요.");
+    }
+    return res.code ?? EXIT_RUN_FAILED;
+}