@vibecodetown/mcp-server 2.2.0 → 2.2.1

package/build/tools/vibe_pm/ingress.js

@@ -0,0 +1,645 @@
+// adapters/mcp-ts/src/tools/vibe_pm/ingress.ts
+// vibe_pm.ingress - Ingress v2 runtime entrypoint (writes ingress_resolution + optional context_scan artifacts)
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+import { encode as encodeMsgpack } from "@msgpack/msgpack";
+import { simpleGit } from "simple-git";
+import { validateToolInput } from "../../security/input-validator.js";
+import { invokeSystem } from "../../runtime/cli_invoker.js";
+import { generateRunId, resolveProjectId, findLatestRunId, getRunContext } from "./context.js";
+import { IngressResolutionFileSchema } from "../../generated/ingress_resolution_file.js";
+import { IngressSummaryFileSchema } from "../../generated/ingress_summary_file.js";
+function toRelPath(basePath, absPath) {
+    const rel = path.relative(basePath, absPath);
+    return rel.replace(/\\\\/g, "/");
+}
+async function writeJsonAtomic(absPath, doc) {
+    await fsPromises.mkdir(path.dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await fsPromises.writeFile(tmp, JSON.stringify(doc, null, 2) + "\n", "utf-8");
+    await fsPromises.rename(tmp, absPath);
+}
+async function writeBinaryAtomic(absPath, bytes) {
+    await fsPromises.mkdir(path.dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await fsPromises.writeFile(tmp, bytes);
+    await fsPromises.rename(tmp, absPath);
+}
+async function writeJsonlAtomic(absPath, lines) {
+    await fsPromises.mkdir(path.dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await fsPromises.writeFile(tmp, lines.join("\n") + "\n", "utf-8");
+    await fsPromises.rename(tmp, absPath);
+}
+function existsDir(p) {
+    try {
+        return fs.existsSync(p) && fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function safeReadJsonFile(absPath) {
+    try {
+        if (!fs.existsSync(absPath))
+            return null;
+        return JSON.parse(fs.readFileSync(absPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function listTopLevelDirs(workspacePath) {
+    try {
+        const entries = fs.readdirSync(workspacePath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .filter((name) => name !== ".git" && name !== "node_modules" && name !== ".vibe" && name !== "dist" && name !== "build")
+            .slice(0, 50);
+    }
+    catch {
+        return [];
+    }
+}
+function detectStackSignals(workspacePath) {
+    const signals = [];
+    const has = (rel) => fs.existsSync(path.join(workspacePath, rel));
+    const hasAny = (rels) => rels.some((r) => has(r));
+    if (has("package.json"))
+        signals.push("package.json");
+    if (has("tsconfig.json"))
+        signals.push("tsconfig.json");
+    if (has("pnpm-lock.yaml"))
+        signals.push("pnpm-lock.yaml");
+    if (has("yarn.lock"))
+        signals.push("yarn.lock");
+    if (has("pyproject.toml"))
+        signals.push("pyproject.toml");
+    if (hasAny(["requirements.txt", "requirements-dev.txt"]))
+        signals.push("requirements.txt");
+    if (has("Cargo.toml"))
+        signals.push("Cargo.toml");
+    if (has("go.mod"))
+        signals.push("go.mod");
+    if (hasAny(["pom.xml", "build.gradle", "build.gradle.kts"]))
+        signals.push("java_build");
+    try {
+        if (fs.readdirSync(workspacePath).some((n) => n.endsWith(".csproj")))
+            signals.push("dotnet_csproj");
+    }
+    catch {
+        // ignore
+    }
+    const languages_hint = [];
+    if (signals.includes("tsconfig.json"))
+        languages_hint.push({ id: "ts", confidence: 5 });
+    if (signals.includes("package.json") && !signals.includes("tsconfig.json"))
+        languages_hint.push({ id: "js", confidence: 4 });
+    if (signals.includes("pyproject.toml") || signals.includes("requirements.txt"))
+        languages_hint.push({ id: "py", confidence: 4 });
+    if (signals.includes("Cargo.toml"))
+        languages_hint.push({ id: "rs", confidence: 4 });
+    if (signals.includes("go.mod"))
+        languages_hint.push({ id: "go", confidence: 4 });
+    if (signals.includes("java_build"))
+        languages_hint.push({ id: "java", confidence: 3 });
+    if (signals.includes("dotnet_csproj"))
+        languages_hint.push({ id: "dotnet", confidence: 3 });
+    const topDirs = listTopLevelDirs(workspacePath);
+    const monorepo_hint = languages_hint.length >= 2 ||
+        topDirs.includes("apps") ||
+        topDirs.includes("packages") ||
+        topDirs.includes("services");
+    return { signals, languages_hint, monorepo_hint };
+}
+function deriveEntrypoints(workspacePath) {
+    const run_candidates = [];
+    const test_candidates = [];
+    const pkgPath = path.join(workspacePath, "package.json");
+    const pkg = safeReadJsonFile(pkgPath);
+    const scripts = pkg && typeof pkg === "object" ? (pkg.scripts ?? {}) : {};
+    const hasScript = (k) => typeof scripts?.[k] === "string" && scripts[k].trim().length > 0;
+    if (fs.existsSync(pkgPath) && scripts && typeof scripts === "object") {
+        if (hasScript("dev")) {
+            run_candidates.push({
+                key: "A",
+                label: "개발 서버 켜기",
+                kind: "dev_server",
+                confidence: 4,
+                cwd: ".",
+                command: ["npm", "run", "dev"],
+                evidence: ["package.json:scripts.dev"]
+            });
+        }
+        if (hasScript("start")) {
+            run_candidates.push({
+                key: run_candidates.length === 0 ? "A" : run_candidates.length === 1 ? "B" : "C",
+                label: "앱 실행",
+                kind: "start",
+                confidence: 3,
+                cwd: ".",
+                command: ["npm", "run", "start"],
+                evidence: ["package.json:scripts.start"]
+            });
+        }
+        if (hasScript("test")) {
+            test_candidates.push({
+                key: "A",
+                label: "테스트 실행",
+                kind: "test",
+                confidence: 4,
+                cwd: ".",
+                command: ["npm", "test"],
+                evidence: ["package.json:scripts.test"]
+            });
+        }
+    }
+    // Python
+    if (run_candidates.length === 0 && (fs.existsSync(path.join(workspacePath, "pyproject.toml")) || fs.existsSync(path.join(workspacePath, "requirements.txt")))) {
+        run_candidates.push({
+            key: "A",
+            label: "파이썬 실행",
+            kind: "python_run",
+            confidence: 2,
+            cwd: ".",
+            command: ["python", "-m", "app"],
+            evidence: ["pyproject.toml|requirements.txt"]
+        });
+        test_candidates.push({
+            key: "A",
+            label: "pytest 실행",
+            kind: "test",
+            confidence: 3,
+            cwd: ".",
+            command: ["python", "-m", "pytest"],
+            evidence: ["pyproject.toml|requirements.txt"]
+        });
+    }
+    // Rust
+    if (run_candidates.length === 0 && fs.existsSync(path.join(workspacePath, "Cargo.toml"))) {
+        test_candidates.push({
+            key: "A",
+            label: "cargo test",
+            kind: "test",
+            confidence: 4,
+            cwd: ".",
+            command: ["cargo", "test"],
+            evidence: ["Cargo.toml"]
+        });
+    }
+    const entrypoint_ambiguous = run_candidates.length >= 2;
+    return { run_candidates, test_candidates, entrypoint_ambiguous };
+}
+function resolveIngressScanBinary(basePath) {
+    const override = (process.env.VIBECODE_INGRESS_SCAN_BIN ?? "").trim();
+    const exe = process.platform === "win32" ? "vpm-back.exe" : "vpm-back";
+    const candidates = [];
+    if (override) {
+        candidates.push(path.isAbsolute(override) ? override : path.resolve(basePath, override));
+    }
+    // Dev-friendly defaults (repo-local builds)
+    candidates.push(path.join(basePath, "engines", "target", "release", exe));
+    candidates.push(path.join(basePath, "engines", "target", "debug", exe));
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c) && fs.statSync(c).isFile())
+                return c;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
+async function runIngressScanBinary(args) {
+    const warnings = [];
+    const res = await invokeSystem(args.binPath, [
+        "ingress-scan",
+        "--repo-root",
+        args.workspacePath,
+        "--run-dir",
+        args.runDir,
+        "--run-id",
+        args.run_id
+    ], args.basePath, { timeoutMs: 120_000 });
+    if (res.exitCode !== 0) {
+        return { ok: false, error: `ingress_scan_failed: exitCode=${res.exitCode} stderr=${res.stderr.trim()}` };
+    }
+    for (const rel of args.requiredFiles) {
+        const abs = path.join(args.runDir, "ingress", rel);
+        if (!fs.existsSync(abs)) {
+            return { ok: false, error: `ingress_scan_missing_output: ${rel}` };
+        }
+    }
+    // Validate summary contract (Front consumption baseline)
+    const summaryAbs = path.join(args.runDir, "ingress", "ingress_summary.json");
+    try {
+        const raw = JSON.parse(fs.readFileSync(summaryAbs, "utf-8"));
+        const parsed = IngressSummaryFileSchema.safeParse(raw);
+        if (!parsed.success)
+            return { ok: false, error: "ingress_scan_invalid_summary" };
+    }
+    catch {
+        return { ok: false, error: "ingress_scan_invalid_summary" };
+    }
+    warnings.push("CONTEXT_SCAN_BIN_USED");
+    return { ok: true, warnings };
+}
+async function indexDocsJsonl(workspacePath, run_id) {
+    const out = [];
+    const header = {
+        type: "__header__",
+        format_version: "ingress.docs_index.v1",
+        run_id,
+        created_at: new Date().toISOString(),
+        producer: { name: "vibe_pm.ingress", version: "v1" }
+    };
+    out.push(JSON.stringify(header));
+    const candidates = ["README.md", "docs/README.md", "docs/SSOT.md", "docs/CURRENT_SPEC.md"].map((p) => path.join(workspacePath, p));
+    let docsCount = 0;
+    for (const abs of candidates) {
+        try {
+            if (!fs.existsSync(abs))
+                continue;
+            const st = fs.statSync(abs);
+            if (!st.isFile())
+                continue;
+            const rel = path.relative(workspacePath, abs).replace(/\\\\/g, "/");
+            out.push(JSON.stringify({
+                type: "doc",
+                path: rel,
+                kind: rel.toLowerCase().includes("ssot") ? "ssot" : rel.toLowerCase().includes("readme") ? "readme" : "doc",
+                bytes: st.size,
+                mtime: st.mtime.toISOString(),
+                signals: []
+            }));
+            docsCount += 1;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { lines: out, docs_count: docsCount };
+}
+async function writeContextScanArtifacts(opts) {
+    const warnings = [];
+    const ingressDirAbs = path.join(opts.runDir, "ingress");
+    const projectFingerprintAbs = path.join(ingressDirAbs, "project_fingerprint.json");
+    const repoMapAbs = path.join(ingressDirAbs, "repo_map.msgpack");
+    const entrypointsAbs = path.join(ingressDirAbs, "entrypoints.msgpack");
+    const docsIndexAbs = path.join(ingressDirAbs, "docs_index.jsonl");
+    const riskFlagsAbs = path.join(ingressDirAbs, "risk_flags.json");
+    const ingressSummaryAbs = path.join(ingressDirAbs, "ingress_summary.json");
+    const artifactsRel = {
+        project_fingerprint: toRelPath(opts.basePath, projectFingerprintAbs),
+        repo_map: toRelPath(opts.basePath, repoMapAbs),
+        entrypoints: toRelPath(opts.basePath, entrypointsAbs),
+        docs_index: toRelPath(opts.basePath, docsIndexAbs),
+        risk_flags: toRelPath(opts.basePath, riskFlagsAbs),
+        ingress_summary: toRelPath(opts.basePath, ingressSummaryAbs)
+    };
+    if (!opts.write_files) {
+        return {
+            completed: false,
+            warnings: ["WRITE_SKIPPED: write_files=false"],
+            artifacts: artifactsRel,
+            risk_flags: { entrypoint_ambiguous: true, monorepo_suspected: false }
+        };
+    }
+    let completed = true;
+    // Prefer back binary when available (P28). Fall back to TS scan on failure.
+    const binPath = resolveIngressScanBinary(opts.basePath);
+    if (binPath) {
+        try {
+            const required = [
+                "project_fingerprint.json",
+                "repo_map.msgpack",
+                "entrypoints.msgpack",
+                "docs_index.jsonl",
+                "risk_flags.json",
+                "ingress_summary.json"
+            ];
+            const bin = await runIngressScanBinary({
+                basePath: opts.basePath,
+                binPath,
+                workspacePath: opts.workspacePath,
+                runDir: opts.runDir,
+                run_id: opts.run_id,
+                requiredFiles: required
+            });
+            if (bin.ok) {
+                warnings.push(...bin.warnings);
+                // Derive minimal risk flags for auto-trigger (cheap read)
+                let entrypointAmbiguous = true;
+                let monorepoSuspected = false;
+                try {
+                    const raw = JSON.parse(fs.readFileSync(riskFlagsAbs, "utf-8"));
+                    entrypointAmbiguous = Boolean(raw?.flags?.entrypoint_ambiguous);
+                    monorepoSuspected = Boolean(raw?.flags?.monorepo_suspected);
+                }
+                catch {
+                    // keep defaults
+                }
+                return {
+                    completed: true,
+                    warnings,
+                    artifacts: artifactsRel,
+                    risk_flags: { entrypoint_ambiguous: entrypointAmbiguous, monorepo_suspected: monorepoSuspected }
+                };
+            }
+            else {
+                warnings.push(`CONTEXT_SCAN_BIN_FAILED: ${bin.error}`);
+            }
+        }
+        catch (e) {
+            warnings.push(`CONTEXT_SCAN_BIN_FAILED: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // 1) project_fingerprint.json (best-effort)
+    try {
+        const git = simpleGit({ baseDir: opts.workspacePath });
+        const isRepo = await git.checkIsRepo();
+        let remoteUrl = null;
+        let branch = null;
+        let head = null;
+        let dirty = false;
+        if (isRepo) {
+            try {
+                remoteUrl = (await git.raw(["remote", "get-url", "origin"])).trim() || null;
+            }
+            catch {
+                remoteUrl = null;
+            }
+            try {
+                const b = await git.branch();
+                branch = b.current || null;
+            }
+            catch {
+                branch = null;
+            }
+            try {
+                head = (await git.revparse(["HEAD"])).trim() || null;
+            }
+            catch {
+                head = null;
+            }
+            try {
+                const st = await git.status();
+                dirty = (st.files?.length ?? 0) > 0;
+            }
+            catch {
+                dirty = false;
+            }
+        }
+        await writeJsonAtomic(projectFingerprintAbs, {
+            format_version: "ingress.project_fingerprint.v1",
+            run_id: opts.run_id,
+            created_at: new Date().toISOString(),
+            producer: { name: "vibe_pm.ingress", version: "v1" },
+            repo_root: path.resolve(opts.workspacePath),
+            is_git: isRepo,
+            git: isRepo
+                ? { remote_url: remoteUrl, branch, head_commit: head, dirty }
+                : null
+        });
+    }
+    catch (e) {
+        completed = false;
+        warnings.push(`FINGERPRINT_FAILED: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // 2) repo_map.msgpack (best-effort)
+    const stack = detectStackSignals(opts.workspacePath);
+    try {
+        const topDirs = listTopLevelDirs(opts.workspacePath);
+        const doc = {
+            format_version: "ingress.repo_map.v1",
+            run_id: opts.run_id,
+            created_at: new Date().toISOString(),
+            producer: { name: "vibe_pm.ingress", version: "v1" },
+            summary: {
+                top_dirs: topDirs,
+                languages_hint: stack.languages_hint,
+                monorepo_hint: stack.monorepo_hint,
+                signals: stack.signals
+            }
+        };
+        await writeBinaryAtomic(repoMapAbs, encodeMsgpack(doc));
+    }
+    catch (e) {
+        completed = false;
+        warnings.push(`REPO_MAP_FAILED: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // 3) entrypoints.msgpack (best-effort)
+    const entry = deriveEntrypoints(opts.workspacePath);
+    try {
+        const doc = {
+            format_version: "ingress.entrypoints.v1",
+            run_id: opts.run_id,
+            created_at: new Date().toISOString(),
+            producer: { name: "vibe_pm.ingress", version: "v1" },
+            run_candidates: entry.run_candidates,
+            test_candidates: entry.test_candidates
+        };
+        await writeBinaryAtomic(entrypointsAbs, encodeMsgpack(doc));
+    }
+    catch (e) {
+        completed = false;
+        warnings.push(`ENTRYPOINTS_FAILED: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // 4) docs_index.jsonl (best-effort)
+    let docsIndexCount = 0;
+    try {
+        const docs = await indexDocsJsonl(opts.workspacePath, opts.run_id);
+        docsIndexCount = docs.docs_count;
+        await writeJsonlAtomic(docsIndexAbs, docs.lines);
+    }
+    catch (e) {
+        completed = false;
+        warnings.push(`DOCS_INDEX_FAILED: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // 5) risk_flags.json (best-effort)
+    const hasEnvFiles = fs.existsSync(path.join(opts.workspacePath, ".env")) || fs.existsSync(path.join(opts.workspacePath, ".env.local"));
+    let hasSecretsLikeFiles = existsDir(path.join(opts.workspacePath, ".ssh"));
+    if (!hasSecretsLikeFiles) {
+        try {
+            hasSecretsLikeFiles = fs.readdirSync(opts.workspacePath).some((n) => n.endsWith(".pem") || n.endsWith(".key"));
+        }
+        catch {
+            hasSecretsLikeFiles = false;
+        }
+    }
+    const risk = {
+        entrypoint_ambiguous: entry.entrypoint_ambiguous,
+        monorepo_suspected: stack.monorepo_hint
+    };
+    try {
+        await writeJsonAtomic(riskFlagsAbs, {
+            format_version: "ingress.risk_flags.v1",
+            run_id: opts.run_id,
+            created_at: new Date().toISOString(),
+            producer: { name: "vibe_pm.ingress", version: "v1" },
+            flags: {
+                has_secrets_like_files: hasSecretsLikeFiles,
+                has_env_files: hasEnvFiles,
+                monorepo_suspected: stack.monorepo_hint,
+                entrypoint_ambiguous: entry.entrypoint_ambiguous,
+                huge_repo: fs.existsSync(path.join(opts.workspacePath, "node_modules"))
+            }
+        });
+    }
+    catch (e) {
+        completed = false;
+        warnings.push(`RISK_FLAGS_FAILED: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // 6) ingress_summary.json (best-effort, required for Front consumption)
+    try {
+        const entrypointAmbiguous = entry.run_candidates.length > 1 || entry.test_candidates.length > 1;
+        const entrypointStatus = entry.run_candidates.length === 0 && entry.test_candidates.length === 0
+            ? "NONE"
+            : entrypointAmbiguous
+                ? "AMBIGUOUS"
+                : "OK";
+        const clarificationReasons = [];
+        if (entrypointAmbiguous)
+            clarificationReasons.push("ENTRYPOINT_AMBIGUOUS");
+        if (stack.monorepo_hint)
+            clarificationReasons.push("MONOREPO_SUSPECTED");
+        const repoKindHint = stack.languages_hint.length === 0
+            ? "unknown"
+            : stack.languages_hint
+                .slice(0, 3)
+                .map((x) => x.id)
+                .join("+") + (stack.monorepo_hint ? " monorepo" : "");
+        const summaryDoc = IngressSummaryFileSchema.parse({
+            format_version: "ingress.summary.v1",
+            run_id: opts.run_id,
+            created_at: new Date().toISOString(),
+            producer: { name: "vibe_pm.ingress", version: "v1" },
+            pointers: {
+                project_fingerprint: "project_fingerprint.json",
+                repo_map: "repo_map.msgpack",
+                entrypoints: "entrypoints.msgpack",
+                docs_index: "docs_index.jsonl",
+                risk_flags: "risk_flags.json"
+            },
+            high_level: {
+                repo_kind_hint: repoKindHint,
+                entrypoint_status: entrypointStatus,
+                clarification_recommended: clarificationReasons.length > 0,
+                clarification_reasons: clarificationReasons,
+                docs_index_count: docsIndexCount
+            },
+            consumption_policy: {
+                front_reads: ["ingress_summary.json", "risk_flags.json"],
+                bridge_reads: ["repo_map.msgpack", "docs_index.jsonl", "entrypoints.msgpack"],
+                back_reads: ["*"]
+            }
+        });
+        await writeJsonAtomic(ingressSummaryAbs, summaryDoc);
+    }
+    catch (e) {
+        completed = false;
+        warnings.push(`INGRESS_SUMMARY_FAILED: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { completed, warnings, artifacts: artifactsRel, risk_flags: risk };
+}
+export async function ingress(input, basePath = process.cwd()) {
+    validateToolInput({ project_id: input.project_id, run_id: input.run_id });
+    const workspacePath = path.resolve(basePath, input.workspace_path ?? ".");
+    if (!existsDir(workspacePath)) {
+        throw new Error(`workspace_path not found: ${workspacePath}`);
+    }
+    const resolution = input.resolution;
+    const hasVibeState = fs.existsSync(path.join(workspacePath, ".vibe"));
+    const preferredId = input.run_id ?? input.project_id;
+    // run_id resolution:
+    // - RESUME prefers existing latest run when not provided.
+    // - NEW_TASK/ADOPT generates a new run_id when not provided.
+    let run_id = null;
+    if (typeof preferredId === "string" && preferredId.trim()) {
+        run_id = preferredId.trim();
+    }
+    else if (resolution === "INGRESS_RESOLVED_RESUME") {
+        run_id = findLatestRunId(basePath);
+        if (!run_id) {
+            throw new Error("resume requires an existing run_id");
+        }
+    }
+    else {
+        const project_id_guess = resolveProjectId(undefined, basePath);
+        run_id = generateRunId(project_id_guess, basePath);
+    }
+    const project_id = resolveProjectId(run_id, basePath);
+    // Ensure Spec-High run root exists so future tools resolve the same run_dir.
+    const specHighRunDir = path.join(basePath, "engines", "spec_high", "runs", run_id);
+    await fsPromises.mkdir(specHighRunDir, { recursive: true });
+    const context = getRunContext(run_id, basePath);
+    const ingressDirAbs = path.join(context.runs_path, "ingress");
+    const ingressResolutionAbs = path.join(ingressDirAbs, "ingress_resolution.json");
+    const ingressResolutionRel = toRelPath(basePath, ingressResolutionAbs);
+    const context_scan_required = resolution !== "INGRESS_ABORTED";
+    const doScan = input.context_scan !== false && context_scan_required;
+    const writeFiles = input.write_files !== false;
+    let scanCompleted = false;
+    let artifacts;
+    const warnings = [];
+    if (doScan) {
+        const scan = await writeContextScanArtifacts({
+            basePath,
+            workspacePath,
+            run_id,
+            runDir: context.runs_path,
+            write_files: writeFiles
+        });
+        scanCompleted = scan.completed;
+        artifacts = scan.artifacts;
+        warnings.push(...scan.warnings);
+    }
+    else {
+        scanCompleted = !context_scan_required;
+    }
+    const resolutionDoc = IngressResolutionFileSchema.parse({
+        schema_version: "ingress.resolution.v2",
+        run_id,
+        project_id,
+        workspace_path: workspacePath,
+        resolution,
+        has_vibe_state: hasVibeState,
+        context_scan_required,
+        context_scan_completed: scanCompleted,
+        created_at: new Date().toISOString()
+    });
+    if (writeFiles) {
+        await writeJsonAtomic(ingressResolutionAbs, resolutionDoc);
+    }
+    else {
+        warnings.push("WRITE_SKIPPED: ingress_resolution.json not written (write_files=false)");
+    }
+    const next_action = resolution === "INGRESS_ABORTED"
+        ? null
+        : scanCompleted
+            ? { tool: "vibe_pm.get_decision", reason: "이제 결재 단계로 넘어갈 수 있습니다." }
+            : { tool: "vibe_pm.ingress", reason: "사전 점검(컨텍스트 스캔)을 완료해야 합니다." };
+    const message = resolution === "INGRESS_ABORTED"
+        ? "Ingress가 중단 상태로 기록되었습니다."
+        : scanCompleted
+            ? "Ingress 및 사전 점검(컨텍스트 스캔)을 완료했습니다."
+            : "Ingress 상태를 기록했습니다. 사전 점검(컨텍스트 스캔)이 아직 완료되지 않았습니다.";
+    return {
+        success: true,
+        project_id,
+        run_id,
+        workspace_path: workspacePath,
+        has_vibe_state: hasVibeState,
+        resolution,
+        context_scan_required,
+        context_scan_completed: scanCompleted,
+        ingress_resolution_path: ingressResolutionRel,
+        artifacts,
+        warnings: warnings.length > 0 ? warnings : undefined,
+        message,
+        next_action
+    };
+}