@flextudio/scenario 0.1.0

package/bin/flex-scenario.mjs

@@ -0,0 +1,895 @@
+#!/usr/bin/env node
+// flex-scenario — 배포용 진입점 CLI (클린: otel/벤치 gen 없음).
+//
+// 서브커맨드:
+//   init [--agent <name>]      현재 폴더에 스킬/커맨드 재배치 (postinstall 수동 재실행).
+//                              --agent claude|codex|antigravity. 미지정 시 메뉴로 물어봄.
+//                              contract-root 는 전역 ~/.flex-scenario 에 둔다.
+//   validate <scenario.json>   buildAjv + runAllCrossChecks 로 전체 검증.
+//   validate --schema <name> <fragment.json>
+//                              지정 schema 로 단편 검증.
+//   catalog --section <name>   catalog.json 의 한 섹션 출력.
+//   examples list              examples 디렉토리 트리.
+//   examples cat <relpath>     해당 example 본문 출력.
+//   contract info              contract 메타 (version, schemas count) 출력.
+//   session {start|status|finish}  build 세션 관리.
+//   doctor                     환경 점검 — 에이전트 바이너리(optional) / SKILL.md / contract-root / core 모듈.
+//   uninstall [--scope <s>]    삭제 범위 메뉴(현재 폴더/모든 설치 폴더/완전 삭제/취소).
+//                              full 은 cleanup 후 전역 패키지 제거까지 자동 실행
+//                              (PM 은 receipt 의 userAgent 로 판별 — npm/pnpm/yarn/bun).
+//                              (npm 7+ 는 preuninstall lifecycle 을 실행하지 않는다 —
+//                               삭제의 단일 진입점은 이 커맨드.) --scope here|all|full.
+//   version                    버전 출력.
+//
+// 환경변수:
+//   FLEX_CONTRACT_ROOT         schema/+rules.md 가 있는 디렉토리. 미지정 시 자동 추론.
+//
+// 시나리오 생성(gen)은 벤치 전용 — bench/cli_bench/bin/flex-gen.mjs 참조.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync, readdirSync } from "node:fs";
+// (readdirSync, statSync 는 examples/findLatestScenario 가 공유)
+import { spawn, spawnSync } from "node:child_process";
+import { dirname, join, resolve, relative, isAbsolute, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, "..");
+const importScript = (name) => import(pathToFileURL(join(PACKAGE_ROOT, "scripts", name)).href);
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+/* ─── arg parsing (no external dep) ─────────────────────────────────────── */
+// 값 없는 boolean flag — 다음 토큰을 값으로 흡수하지 않는다.
+// 누락 시 `--report scenario.json` 같은 호출에서 scenario.json 이 report 값으로
+// 흡수되어 positional 이 비어 폭발하는 함정이 생긴다.
+const BOOLEAN_FLAGS = new Set(["report", "no-write"]);
+
+function parseArgs(argv) {
+  const positional = [];
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--") { positional.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const eq = key.indexOf("=");
+      if (eq >= 0) {
+        opts[key.slice(0, eq)] = key.slice(eq + 1);
+      } else if (BOOLEAN_FLAGS.has(key)) {
+        opts[key] = true;
+      } else {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--")) {
+          opts[key] = true;
+        } else {
+          opts[key] = next;
+          i += 1;
+        }
+      }
+    } else if (a.startsWith("-")) {
+      opts[a.slice(1)] = true;
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, opts };
+}
+
+/* ─── contract root 결정 ───────────────────────────────────────────────── */
+function resolveContractRoot() {
+  const candidates = [];
+  if (process.env.FLEX_CONTRACT_ROOT) candidates.push(process.env.FLEX_CONTRACT_ROOT);
+  candidates.push(join(homedir(), ".flex-scenario", "contract-root"));
+  candidates.push(join(PACKAGE_ROOT, "contract-data"));
+  // 워크스페이스 모드: cli/ → repo root (한 단계 위)
+  candidates.push(resolve(PACKAGE_ROOT, ".."));
+  for (const c of candidates) {
+    try {
+      if (
+        existsSync(join(c, "schema")) &&
+        statSync(join(c, "schema")).isDirectory() &&
+        existsSync(join(c, "spec", "rules.md"))
+      ) {
+        return c;
+      }
+    } catch { /* try next */ }
+  }
+  return null;
+}
+
+const CONTRACT_ROOT = resolveContractRoot();
+if (CONTRACT_ROOT) process.env.FLEX_CONTRACT_ROOT = CONTRACT_ROOT;
+
+/* ─── 출력 헬퍼 ─────────────────────────────────────────────────────────── */
+const out  = (m) => process.stdout.write(m + "\n");
+const err  = (m) => process.stderr.write(m + "\n");
+const ok   = (m) => out(`✔ ${m}`);
+const bad  = (m) => err(`✘ ${m}`);
+
+/* ─── cross-check 분류 키 → 1줄 fix-hint ──────────────────────────────────
+ * validate 결과의 errors[].hint 로 흘러간다. 모델이 자가검증 루프에서 어떤
+ * 방향으로 고칠지 즉시 알 수 있도록. raw 메시지보다 짧고 강한 1줄.
+ * 진실원본은 각각의 진실원본 (skill-guides/INTENT.md/design-rules.md) — 본 dict
+ * 은 단순 포인터 + 정책 한 줄 요약.
+ * ───────────────────────────────────────────────────────────────────── */
+const CROSS_CHECK_FIX_HINTS = Object.freeze({
+  "caption-row":
+    "캡션 입력 + 비캡션 컨트롤(버튼 등)을 한 가로 행에 두지 말 것 — top 캡션이 박스 높이를 키워 세로 정렬이 어긋난다. 캡션을 별도 Label 로 행 위에 올리고(컬럼 gap 4), 입력+컨트롤만 같은 높이로 한 행에. DESIGN.md §Layout \"Captioned input in a row\".",
+  "back-button":
+    "Step.UseBackButton:true + 헤더에 표준 BackButton 컨트롤 (Next:'None'). 첫 Step 은 닫기, 이후 Step 은 이전 Step 복귀. skill-guides/step-navigation.md.",
+  "dialog-host":
+    "Combo/Search/InputDate 본체에 Dialog.Layouts[0].Controls[0] 자식 (ComboList/List/Calendar) 필수. memory: feedback_dialog_host_required.",
+  "dc-parent-ctx":
+    "Parent 필터는 조상 Group 에 DataConnection 이 있을 때만 — 독립 목록이면 Parent 필터 제거(일반 query), 1:N 이면 부모 Group 에 DC 먼저. data-objects.md §3.2.",
+  "embed-bind":
+    "Embed raw HTML 안 {=Field} 는 치환 안 됨 — 섹터 값은 {%return Load.sector.Field; %} (LoadScript 토큰). Load.sector 는 조상 DC 그룹 아래에서만 유효 (DC 밖이면 조용히 빈 문자열). 값 변경 시 f.Content(<부모그룹 fid>, <그 그룹을 그린 섹터>).reload() 타겟 리로드 필수. control/embed.md §섹터 값 바인딩.",
+  "template-script":
+    "{=Field} 토큰은 display 전용. Step 간 값 전달은 intent.script:{kind:'copyStepValues', from, to, map, reload?}. INTENT.md §copyStepValues.",
+  "script-allow":
+    "Script 본문은 intent.script 1순위 (dialog/updateActive/clearCategory/reloadGroup/deleteActive/copyStepValues). raw 는 표현 불가일 때만. INTENT.md.",
+  "no-inner-block":
+    "반복은 DataConnection.DataUsage:'query'. UseInnerBlock/InnerBlockKey/RepeatStyle 금지.",
+  "no-service":
+    "DataSourceType 은 Fixed 또는 Grid 만. Service/API/Collection 금지. EmbedScenarioPrefix 키 자체 금지.",
+  "mock-init":
+    "시작 Step.Init Action 에 intent.mock:{Ctg<Name>:[{...}]} 으로 카테고리 mock 섹터 박을 것. INTENT.md §mock.",
+  "category-name":
+    "카테고리명 'Ctg' 접두 + PascalCase. Ckeys/CategoryName 에 예약어(_SUID/for/class/length) 금지.",
+  "v1-only":
+    "v1 컨트롤 12종 외 사용 금지. 진실원본: catalog.json $.controlTypes.",
+  "event-ref":
+    "Action:'LinkedEvent' / dialog 의 button.event 는 scenario.Events 키에 정의되어 있어야 함.",
+  "display-key":
+    "DataSource 기반 Combo/Search 본체에 CtrlDisplayCkey 또는 비어있지 않은 DisplayValue 필수.",
+  "ds-key":
+    "ComboList/List 의 Title 에 DataSource 키 중 표시할 키 연결 필수 (예: ItemName/ItemValue) — 없으면 리스트에 명칭 안 보임. 본체-자식 Ckeys 도 동일해야. combo.md §ComboList.Title.",
+  "strict-fields":
+    "schema 미정의 키 발견. design 키는 허용(materialize 단계가 raw 로 expand) — 그 외엔 schema 본체 Read 후 정의된 키만 사용.",
+  "residual":
+    "design/intent short-form 이 전개 안 된 채 남음 — 거짓 완료 차단. 호스트 노드를 정상 컨테이너(Group Contents / Dialog.Layouts[*].Controls / Step FixedContents) 안으로 옮기거나 해당 키를 raw 필드로 직접 작성. design-system/materialize.mjs · INTENT.md.",
+});
+
+/* ─── 서브커맨드: version ─────────────────────────────────────────────── */
+function cmdVersion() { out(`flex-scenario ${VERSION}`); }
+
+/* ─── 서브커맨드: help ─────────────────────────────────────────────────── */
+function cmdHelp() {
+  out(`flex-scenario ${VERSION} — flextudio meta-contract v1 시나리오 CLI
+
+USAGE
+  flex-scenario <subcommand> [options]      (단축 별칭: fscn)
+
+SUBCOMMANDS
+  init [--agent <name>]             postinstall 재실행 (claude|codex|antigravity, 미지정 시 메뉴)
+  validate <scenario.json>          전체 시나리오 검증 (stdout=작은 ok 리포트, 산출물은 파일로 write-back)
+  validate --schema <name> <file>   단편 검증
+  validate ... --emit-materialized <path>   materialized 본문을 별도 경로에도 저장 (stdout 아님)
+  validate ... --no-write           검증만 (파일 write-back 안 함)
+  catalog --section <name>          catalog.json 의 한 섹션 출력
+  examples list                     examples 디렉토리 트리
+  examples cat <relpath>            해당 example 본문 출력
+  contract info                     contract 메타 (version, schemas count) (MCP contract_info 동형)
+  session start                     build_id 발급 (MCP start_build_sequence 동형)
+  session status --id <build_id>    현재 stage + next 힌트
+  session finish --id <build_id> [--artifact <path>]   세션 종료 + 산출물 경로 반환
+  doctor                            환경 점검
+  login                             OIDC 로그인
+  logout                            저장된 토큰 삭제
+  create --file <scenario.json>     시나리오 메타 파일을 새 시나리오로 생성
+  uninstall [--scope here|all|full] 삭제 범위 메뉴 (full = cleanup + 전역 패키지 자동 제거)
+  version                           버전
+  help                              이 도움말
+
+ENVIRONMENT
+  FLEX_CONTRACT_ROOT                schema/+rules.md 위치 (자동 추론 가능)
+  FLEX_AGENT                        설치 대상 에이전트 (claude|codex|antigravity). init/postinstall 에서 사용
+  FLEX_SCENARIO_FORCE_UNINSTALL     =1 이면 workspace dev 환경에서도 uninstall --scope full 의 npm 단계 수행
+`);
+}
+
+/* ─── 서브커맨드: init (postinstall 재실행) ───────────────────────────── */
+//   flex-scenario init [--agent <claude|codex|antigravity>]
+//   --agent 미지정 시 postinstall 이 TTY 메뉴(claude/codex/antigravity/나중에)로 물어본다.
+async function cmdInit(opts = {}) {
+  const script = join(PACKAGE_ROOT, "scripts", "postinstall.mjs");
+  // init 은 "지금 있는 폴더"에 깐다 — postinstall 에 타겟을 명시 전달.
+  // (env 없으면 postinstall 은 INIT_CWD→cwd 순으로 폴백한다.)
+  const env = { ...process.env, FLEX_SCENARIO_INSTALL_DIR: process.cwd() };
+  if (opts.agent) env.FLEX_AGENT = String(opts.agent);
+  const res = spawnSync(process.execPath, [script], { stdio: "inherit", env });
+  process.exit(res.status ?? 1);
+}
+
+// SKILL.md 경로 해석 — 프로젝트 로컬 우선, 없으면 전역 폴백.
+//   1. FLEX_SKILL_DIR 환경변수 (명시 override)
+//   2. 베이스(cwd / CONTRACT_ROOT / home) × 에이전트 레이아웃(.claude / .agents / .agent)
+// gen·doctor 가 공유한다. 모두 없으면 경고용으로 마지막 후보 경로를 반환.
+function resolveSkillPath() {
+  const c = [];
+  if (process.env.FLEX_SKILL_DIR) c.push(join(process.env.FLEX_SKILL_DIR, "SKILL.md"));
+  const dotDirs = [".claude", ".agents", ".agent"];
+  const bases = [process.cwd(), CONTRACT_ROOT, homedir()].filter(Boolean);
+  for (const base of bases) {
+    for (const dot of dotDirs) c.push(join(base, dot, "skills", "scenario-gen", "SKILL.md"));
+  }
+  return c.find((p) => existsSync(p)) || c[c.length - 1];
+}
+
+/* ─── 서브커맨드: uninstall ───────────────────────────────────────────── */
+// 삭제의 단일 진입점 — npm 7+ 는 preuninstall lifecycle 을 실행하지 않으므로
+// ("npm v7 does not [run] uninstall scripts" — npm 공식 문서) 삭제 시점은 여기서 만든다.
+// 범위: here(현재 폴더의 설치) / all(모든 설치 폴더) / full(전부 + 전역 패키지 자동 제거).
+// 순서 중요: cleanup/tty-menu/install-paths 와 패키지명은 spawn 전에 로드/확보 완료 →
+// 패키지 디렉토리가 삭제돼도 (POSIX) 안전. spawn 이후엔 PACKAGE_ROOT 를 다시 읽지 않는다.
+const UNINSTALL_SCOPES = new Set(["here", "all", "full"]);
+
+// 전역 제거 커맨드 — postinstall 이 receipt 에 기록한 npm_config_user_agent
+// ("pnpm/9.x npm/? node/…") 의 첫 토큰으로 설치 PM 을 판별한다. pnpm/yarn 전역
+// 설치 사용자의 full 단계가 npm 으로 엉뚱한 제거를 시도하지 않도록. 미기록/미인식 → npm.
+function resolvePmRemove(userAgent, pkgName) {
+  const pm = String(userAgent ?? "").trim().split("/")[0].toLowerCase();
+  if (pm === "pnpm") return { bin: "pnpm", args: ["remove", "-g", pkgName] };
+  if (pm === "yarn") return { bin: "yarn", args: ["global", "remove", pkgName] };
+  if (pm === "bun")  return { bin: "bun",  args: ["remove", "-g", pkgName] };
+  return { bin: "npm", args: ["uninstall", "-g", pkgName] };
+}
+
+async function cmdUninstall(opts = {}) {
+  const { cleanup, collectInstalls, findInstallAt } =
+    await importScript("cleanup.mjs");
+  const { isWorkspaceDevEnv, INSTALL_RECEIPT } =
+    await importScript("install-paths.mjs");
+  const { resolveTTY, promptMenu } = await importScript("tty-menu.mjs");
+
+  // 패키지명은 manifest 에서 — prepack 이 프로파일별로 name 을 바꿔도 안전.
+  let pkgName = "@flextudio/scenario";
+  try {
+    pkgName = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8")).name || pkgName;
+  } catch { /* 폴백 이름 사용 */ }
+  // 설치 PM 판별 근거(userAgent)도 spawn 전에 확보.
+  let installUserAgent = null;
+  try {
+    installUserAgent = JSON.parse(readFileSync(INSTALL_RECEIPT, "utf-8")).userAgent ?? null;
+  } catch { /* receipt 없음/손상 → npm 폴백 */ }
+  const pmRemove = resolvePmRemove(installUserAgent, pkgName);
+  const manualCmd = `${pmRemove.bin} ${pmRemove.args.join(" ")}`;
+
+  const cwd = resolve(process.cwd());
+  // here = 현재 폴더가 receipt 에 기록된 설치 폴더 자신일 때만 (하위/부모 불인정,
+  // 심링크 차이만 realpath 로 흡수). 다른 위치의 설치는 all|full 로.
+  const hereInstall = findInstallAt(cwd);
+
+  // 범위 결정: --scope 플래그 → 검증 / 없으면 TTY 메뉴 / 비TTY+무플래그 → 안전 거부.
+  // (postinstall 의 "기본값 폴백"과 달리 파괴적 동작이라 묻지 못하면 지우지 않는다.)
+  let scope = opts.scope;
+  if (scope !== undefined) {
+    if (!UNINSTALL_SCOPES.has(scope)) {
+      bad(`--scope 는 here|all|full 중 하나여야 합니다 (받음: ${scope})`);
+      process.exit(2);
+    }
+    if (scope === "here" && !hereInstall) {
+      bad(`현재 폴더(${cwd})는 설치 기록(receipt)에 없습니다 — --scope all|full 을 사용하세요.`);
+      const dirs = [...new Set(collectInstalls().map((t) => t.dir))];
+      if (dirs.length) {
+        err("  설치 기록 폴더:");
+        for (const d of dirs) err(`    - ${d}`);
+      }
+      process.exit(2);
+    }
+  } else {
+    const io = resolveTTY();
+    if (!io) {
+      bad("비대화형 환경 — 삭제 범위를 물을 수 없습니다. --scope here|all|full 로 지정하세요.");
+      process.exit(2);
+    }
+    const items = [
+      ...(hereInstall ? [{ key: "here", label: "현재 폴더만 — 이 폴더의 스킬/커맨드 삭제" }] : []),
+      { key: "all",    label: "모든 설치 폴더 — 설치된 모든 폴더의 스킬/커맨드 삭제" },
+      { key: "full",   label: "완전 삭제 — 모든 설치 폴더 + ~/.flex-scenario 삭제 후 전역 패키지 제거" },
+      { key: "cancel", label: "취소" },
+    ];
+    try {
+      scope = await promptMenu(io, { header: "삭제 범위를 선택하세요.", items, cancelKey: "cancel" });
+    } finally { io.close(); }
+    if (scope === "cancel") { out("취소했습니다."); return; }
+  }
+
+  if (scope === "full") {
+    try {
+      const m = await importScript("auth.mjs");
+      await m.runLogout();
+    } catch {}
+  }
+
+  // here 는 receipt 에 기록된 값(심링크 정규화 전 원본)을 넘겨 cleanup 의 dir 비교와 일치시킨다.
+  cleanup({ verbose: true, scope, dir: hereInstall?.dir ?? cwd }); // best-effort — 절대 throw 하지 않는다
+
+  if (scope !== "full") {
+    out("");
+    ok(`정리 완료 (${scope === "here" ? "현재 폴더" : "모든 설치 폴더"}) — CLI 와 ~/.flex-scenario 는 유지됩니다.`);
+    out(`  완전 삭제: flex-scenario uninstall --scope full`);
+    return;
+  }
+
+  if (process.env.FLEX_SCENARIO_FORCE_UNINSTALL !== "1" && isWorkspaceDevEnv()) {
+    out("");
+    out("· workspace dev 환경 감지 — 전역 패키지는 건드리지 않습니다 (cleanup 만 수행).");
+    out(`  전역 설치본까지 지우려면: ${manualCmd}  (또는 FLEX_SCENARIO_FORCE_UNINSTALL=1)`);
+    return;
+  }
+
+  out("");
+  out(`→ ${manualCmd}`);
+  // win32: npm.cmd/pnpm.cmd/yarn.cmd 는 shell 없이는 spawn 불가 (Node 18.20+/20.12+ EINVAL).
+  //        실행 중인 .cmd shim 삭제로 종료 직후 cosmetic 한 cmd 경고가 날 수 있으나 무해.
+  const res = spawnSync(pmRemove.bin, pmRemove.args, {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  if (res.error || res.status !== 0) {
+    bad(`${pmRemove.bin} 전역 제거 실패${res.error ? ` — ${res.error.code || res.error.message}` : ` (exit=${res.status})`}`);
+    err("cleanup 은 완료됐습니다. 패키지 제거만 수동으로 마무리하세요:");
+    err(`  ${manualCmd}`);
+    err("  (EACCES 면 sudo, 다른 PM 으로 전역 설치했다면 해당 PM 의 global remove 사용)");
+    process.exit(1);
+  }
+  out("");
+  ok(`완전 삭제 완료 — 설치 폴더 정리 + ~/.flex-scenario 삭제 + ${pkgName} 전역 패키지 제거.`);
+}
+
+/* ─── 서브커맨드: catalog ─────────────────────────────────────────────── */
+function cmdCatalog(opts) {
+  if (!CONTRACT_ROOT) {
+    bad("contract root 를 찾지 못함. FLEX_CONTRACT_ROOT 또는 'flex-scenario init' 실행 후 다시 시도.");
+    process.exit(2);
+  }
+  const section = opts.section;
+  const catalog = JSON.parse(readFileSync(join(CONTRACT_ROOT, "spec", "catalog.json"), "utf-8"));
+  if (!section) {
+    out("catalog sections:");
+    for (const k of Object.keys(catalog)) {
+      if (k.startsWith("$")) continue;
+      const v = catalog[k];
+      const size = Array.isArray(v) ? `[${v.length}]` : typeof v;
+      out(`  - ${k}  ${size}`);
+    }
+    out("\nusage: flex-scenario catalog --section <name>");
+    return;
+  }
+  if (!(section in catalog)) {
+    bad(`unknown section: ${section}`);
+    process.exit(2);
+  }
+  out(JSON.stringify(catalog[section], null, 2));
+}
+
+/* ─── 서브커맨드: examples ───────────────────────────────────────────── */
+function cmdExamples(positional /* [sub, arg] */) {
+  if (!CONTRACT_ROOT) {
+    bad("contract root 를 찾지 못함. FLEX_CONTRACT_ROOT 또는 'flex-scenario init' 실행 후 다시 시도.");
+    process.exit(2);
+  }
+  const sub = positional[0] ?? "list";
+  const root = join(CONTRACT_ROOT, "examples");
+  if (!existsSync(root)) { bad(`examples 디렉토리 없음: ${root}`); process.exit(2); }
+
+  if (sub === "list") {
+    const files = [];
+    (function walk(d) {
+      for (const e of readdirSync(d)) {
+        const f = join(d, e);
+        const st = statSync(f);
+        if (st.isDirectory()) walk(f);
+        else if (e.endsWith(".json")) files.push(relative(root, f));
+      }
+    })(root);
+    files.sort();
+    for (const f of files) out(f);
+    return;
+  }
+  if (sub === "cat") {
+    const rel = positional[1];
+    if (!rel) { bad("usage: flex-scenario examples cat <relative-path>"); process.exit(2); }
+    if (rel.includes("..") || isAbsolute(rel)) {
+      bad("examples 외부 경로 금지"); process.exit(2);
+    }
+    const f = join(root, rel);
+    if (!existsSync(f)) { bad(`not found: ${rel}`); process.exit(2); }
+    out(readFileSync(f, "utf-8"));
+    return;
+  }
+  bad(`unknown subcommand: examples ${sub}`); process.exit(2);
+}
+
+/* ─── 서브커맨드: validate ────────────────────────────────────────────── */
+async function cmdValidate(positional, opts) {
+  if (!CONTRACT_ROOT) {
+    bad("contract root 를 찾지 못함. FLEX_CONTRACT_ROOT 또는 'flex-scenario init' 실행 후 다시 시도.");
+    process.exit(2);
+  }
+  const file = positional[0];
+  if (!file) { bad("usage: flex-scenario validate [--schema <name>] <file>"); process.exit(2); }
+  if (!existsSync(file)) { bad(`not found: ${file}`); process.exit(2); }
+
+  // contract-core 는 schema/+rules.md 위치를 FLEX_CONTRACT_ROOT 로 받는다 — 이미 set.
+  const { buildAjv, runAllCrossChecks, buildKnownProps, denoiseErrors, foldOneOfCascade, surfaceControlBranchErrors } =
+    await import("@flextudio/contract-core");
+
+  // ajv 인스턴스 빌드 (stderr 로 timing 보고 — 무시 가능).
+  const { ajv, ajvStrict, schemaIndex, schemaCache } = buildAjv();
+  // oneOf 분기 cascade 노이즈 필터용 — MCP validate 경로와 동일 (대칭).
+  const knownProps = buildKnownProps(schemaCache);
+
+  const text = readFileSync(file, "utf-8");
+  let payload;
+  try { payload = JSON.parse(text); }
+  catch (e) { bad(`JSON parse 실패: ${e.message}`); process.exit(1); }
+
+  // schema 키 결정.
+  // --schema <name>:
+  //   "scenario" → "scenario.schema.json"
+  //   "step"     → "step.schema.json"
+  //   "group"    → "group.schema.json"
+  //   직접 경로  → 그대로
+  const schemaArg = opts.schema || (opts.s === true ? null : opts.s);
+  const schemaKey = resolveSchemaKey(schemaArg ?? "scenario", schemaIndex);
+  if (!schemaKey) {
+    bad(`unknown schema: ${schemaArg}. 사용 가능: ${listSchemaShorthands(schemaIndex).join(", ")}`);
+    process.exit(2);
+  }
+
+  const errors = [];
+
+  // ─── [phase: materialize] ─────────────────────────────────────────────
+  // MCP 서버와 동일하게 strict-fields 진입 전에 pattern invocation 과
+  // raw control 의 `design` 키를 풀 메타데이터로 expand. 이 단계가 없으면
+  // 정상적인 `design` 키도 strict 가 `[strict-fields]` 로 거부한다.
+  try {
+    const materializeUrl = pathToFileURL(
+      join(CONTRACT_ROOT, "schema/v1/patterns/_base.materialize.mjs"),
+    ).href;
+    const { materializeScenario, materializeFragment } = await import(materializeUrl);
+    const mr = schemaKey === "scenario.schema.json"
+      ? await materializeScenario(payload)
+      : await materializeFragment(payload);
+    if (mr && typeof mr === "object") {
+      if (mr.scenario && typeof mr.scenario === "object") payload = mr.scenario;
+      else if (mr.fragment && typeof mr.fragment === "object") payload = mr.fragment;
+      for (const e of mr.errors ?? []) {
+        errors.push({
+          kind: e.kind ?? "materialize",
+          path: e.path ?? "<root>",
+          schemaPath: e.schemaPath,
+          message: e.message,
+          ...(e.patternName ? { patternName: e.patternName } : {}),
+          ...(e.hint ? { hint: e.hint } : {}),
+        });
+      }
+    }
+  } catch (e) {
+    errors.push({
+      kind: "materialize",
+      path: "<root>",
+      message: `materialize 단계 catastrophic: ${e.message}`,
+    });
+  }
+
+  // ─── [phase: intent] ──────────────────────────────────────────────────
+  // pattern + design 펼침 (materialize) 다음 단계로 intent (런타임 영역
+  // short-form) 펼침을 별도 모듈에서 호출. _base.materialize.mjs 와 책임 분리
+  // — pattern/design 은 컨트롤 트리, intent 는 컬렉션/스크립트/카테고리.
+  // 진실원본: runtime/v1/intent-system/INTENT.md, materialize.mjs
+  try {
+    const intentUrl = pathToFileURL(
+      join(CONTRACT_ROOT, "runtime/v1/intent-system/materialize.mjs"),
+    ).href;
+    const { applyIntentToScenario, applyIntentToFragment } = await import(intentUrl);
+    const ir = schemaKey === "scenario.schema.json"
+      ? applyIntentToScenario(payload)
+      : applyIntentToFragment(payload);
+    if (ir && typeof ir === "object") {
+      if (ir.scenario && typeof ir.scenario === "object") payload = ir.scenario;
+      else if (ir.fragment && typeof ir.fragment === "object") payload = ir.fragment;
+      for (const e of ir.errors ?? []) {
+        errors.push({
+          kind: e.kind ?? "intent",
+          path: e.path ?? "<root>",
+          message: e.message,
+          ...(e.phase ? { phase: e.phase } : {}),
+          ...(e.scope ? { scope: e.scope } : {}),
+          ...(e.slot ? { slot: e.slot } : {}),
+          ...(e.allowedScopes ? { allowedScopes: e.allowedScopes } : {}),
+          ...(e.hint ? { hint: e.hint } : {}),
+        });
+      }
+    }
+  } catch (e) {
+    errors.push({
+      kind: "intent",
+      path: "<root>",
+      message: `intent 단계 catastrophic: ${e.message}`,
+    });
+  }
+
+  const validate = ajv.getSchema(schemaKey);
+  if (!validate) { bad(`schema 미등록: ${schemaKey}`); process.exit(2); }
+  const validateStrict = ajvStrict.getSchema(schemaKey);
+
+  const passed = validate(payload);
+  if (!passed) {
+    // loose ajv 의 oneOf 분기 cascade 를 denoise → 남은 redundant oneOf wrapper fold
+    // → leaf 로 남은 oneOf wrapper 는 노드의 실제 ControlType/ContentsType 으로 재검증해
+    //   actionable 한 concrete 에러(빠진 required 등)로 표면화 (bare wrapper 방지).
+    const looseErrors = surfaceControlBranchErrors(
+      foldOneOfCascade(denoiseErrors(validate.errors ?? [], knownProps)),
+      payload, ajv, schemaCache,
+    );
+    for (const e of looseErrors) {
+      errors.push({
+        kind: "schema",
+        path: e.instancePath || "<root>",
+        schemaPath: e.schemaPath,
+        message: e.message,
+        params: e.params,
+      });
+    }
+  }
+  if (validateStrict) {
+    const okStrict = validateStrict(payload);
+    if (!okStrict) {
+      // strict 변종은 cascade 가 가장 심함 — denoise 후 진짜 unknown 키만 남는다.
+      for (const e of denoiseErrors(validateStrict.errors ?? [], knownProps)) {
+        if (e.keyword !== "additionalProperties" && e.keyword !== "unevaluatedProperties") continue;
+        const extra = e.params?.additionalProperty ?? e.params?.unevaluatedProperty;
+        errors.push({
+          kind: "strict-fields",
+          path: e.instancePath || "<root>",
+          schemaPath: e.schemaPath,
+          message: `스키마 미정의 필드 '${extra}' — strict_fields ON.`,
+          params: e.params,
+          hint: CROSS_CHECK_FIX_HINTS["strict-fields"],
+        });
+      }
+    }
+  }
+
+  // cross-check 는 전체 시나리오일 때만.
+  let crossCheckSummary = null;
+  if (schemaKey === "scenario.schema.json") {
+    const cross = runAllCrossChecks(payload, {
+      strictSample: true, strictImage: true, strictProto: true,
+      strictV1Controls: true, strictStepNav: true, strictNoInnerBlock: true,
+      strictNoService: true, strictScript: true, strictMockInit: true,
+      strictCategoryName: true,
+    });
+    crossCheckSummary = {};
+    for (const [tag, msgs] of Object.entries(cross)) {
+      crossCheckSummary[tag] = msgs.length;
+      const hint = CROSS_CHECK_FIX_HINTS[tag];
+      for (const m of msgs) errors.push({ kind: tag, message: m, ...(hint ? { hint } : {}) });
+    }
+  }
+
+  // 실패 시 errors 는 상한 N 개로 잘라 신호를 작게 유지 (통과/실패 출력 대칭).
+  const ERROR_CAP = 30;
+  const result = {
+    ok: errors.length === 0,
+    schemaKey,
+    errorCount: errors.length,
+    ...(crossCheckSummary ? { crossCheckSummary } : {}),
+    errors: errors.slice(0, ERROR_CAP),
+    ...(errors.length > ERROR_CAP ? { truncated: true, errorTotal: errors.length } : {}),
+  };
+
+  // ─── [phase: write-back] ───────────────────────────────────────────────
+  // ok:true 일 때 materialized payload (design → raw expand 완료본) 를 입력
+  // 파일에 덮어쓴다. 런타임 엔진은 raw 스타일 필드만 소비하므로 design 키가
+  // 남아있으면 렌더 불가. ★ 이 파일이 곧 회수 대상(artifact) — 큰 산출물은
+  // 디스크 파일로만 존재하고 stdout/응답 채널을 통과시키지 않는다.
+  // --no-write 로 비활성 (dry-run / CI 검증 등). ok:false 면 절대 덮어쓰지 않음.
+  // 이미 materialize 된 파일이면 변경 없음 (idempotent).
+  if (result.ok && !opts["no-write"]) {
+    try {
+      writeFileSync(file, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+      result.materialized = true;
+      result.writtenTo = file;
+      result.artifact = file; // 회수 대상 = materialized 입력 파일.
+    } catch (e) {
+      result.materialized = false;
+      result.writeError = e.message;
+    }
+  } else if (result.ok && opts["no-write"]) {
+    result.materialized = false;
+    result.writeSkipped = "--no-write";
+  }
+
+  // --emit-materialized <path>: materialized 본문을 별도 경로에도 저장한다 (stdout 아님).
+  // 입력 파일과 다른 위치로 산출물을 분리하고 싶을 때만. stdout 엔 절대 본문을 안 냄.
+  const emitPath = opts["emit-materialized"];
+  if (result.ok && typeof emitPath === "string" && emitPath) {
+    try {
+      mkdirSync(dirname(resolve(emitPath)), { recursive: true });
+      writeFileSync(emitPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+      result.emittedTo = emitPath;
+      if (!result.artifact) result.artifact = resolve(emitPath);
+    } catch (e) {
+      result.emitError = e.message;
+    }
+  }
+
+  // ─── [phase: emit] ─────────────────────────────────────────────────────
+  // 검증 신호(작음)와 산출물(큼)은 다른 채널. stdout 에는 통과/실패 모두 동일한
+  // 필드 집합의 작은 리포트({ ok, errorCount, errors?, artifact? }) 만 출력한다 —
+  // materialized 본문은 절대 stdout 에 싣지 않는다 (에이전트가 컨텍스트로 재독하지
+  // 않도록). 산출물은 write-back / --emit-materialized 로 파일에만 존재하고, 회수
+  // 주체는 result.artifact 경로로 직접 읽는다. exit code 와 ok 는 항상 일치.
+  out(JSON.stringify(result, null, 2));
+  if (result.ok) {
+    err(`✔ flex-scenario validate: ok (errors:0)${result.artifact ? ` — artifact → ${result.artifact}` : ""}`);
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function resolveSchemaKey(name, schemaIndex) {
+  // 1. exact match (file key)
+  for (const s of schemaIndex) if (s.key === name) return s.key;
+  // 2. .schema.json suffix
+  for (const s of schemaIndex) if (s.key === `${name}.schema.json`) return s.key;
+  // 3. basename match (예: name="scenario" → "scenario.schema.json")
+  for (const s of schemaIndex) if (s.basename === name) return s.key;
+  // 4. tail match — group / step 등 nested key 도 잡힘
+  const matches = schemaIndex.filter((s) => s.basename === name || s.key.endsWith(`/${name}.schema.json`));
+  if (matches.length === 1) return matches[0].key;
+  return null;
+}
+
+function listSchemaShorthands(schemaIndex) {
+  // 상위 ~30 개만 노출.
+  return [...new Set(schemaIndex.map((s) => s.basename))].sort().slice(0, 30);
+}
+
+/* ─── 서브커맨드: doctor ─────────────────────────────────────────────── */
+// PATH 에서 실행 파일 탐색 — win32 엔 which 가 없으므로 where 사용 (여러 줄 반환 → 첫 줄).
+function findOnPath(bin) {
+  const r = spawnSync(process.platform === "win32" ? "where" : "which", [bin], { encoding: "utf-8" });
+  if (r.status !== 0 || !r.stdout) return null;
+  return r.stdout.split(/\r?\n/).map((s) => s.trim()).find(Boolean) ?? null;
+}
+
+async function cmdDoctor() {
+  const checks = [];
+
+  // 1. 에이전트 바이너리 — receipt 에 기록된 설치 에이전트별로 점검 (기록 없으면 기본 에이전트).
+  //    optional: 바이너리 부재가 스킬 자산 설치 상태를 깨뜨리진 않는다 — codex/antigravity
+  //    설치를 claude 부재로 실패 처리하지 않기 위함. PATH 바이너리가 없는 에이전트
+  //    (antigravity = IDE 앱, AGENTS[].bin=null)는 점검 줄 자체를 생략.
+  const { collectInstalls } = await importScript("cleanup.mjs");
+  const { AGENTS, DEFAULT_AGENT } = await importScript("install-paths.mjs");
+  const installedAgents = [...new Set(collectInstalls().map((t) => t.agent))];
+  if (installedAgents.length === 0) installedAgents.push(DEFAULT_AGENT);
+  for (const agent of installedAgents) {
+    const bin = AGENTS[agent]?.bin;
+    if (!bin) continue;
+    const binPath = findOnPath(bin);
+    checks.push({
+      name: `${bin} binary`,
+      ok: !!binPath,
+      optional: true,
+      detail: binPath ?? `not found (PATH 에 ${bin} 없음)`,
+    });
+  }
+
+  // 2. SKILL.md 존재 — 프로젝트 로컬(cwd/.claude) 우선, 없으면 전역 폴백.
+  const skillPath = resolveSkillPath();
+  checks.push({ name: "SKILL.md installed", ok: existsSync(skillPath), detail: skillPath });
+
+  // 3. contract root.
+  checks.push({ name: "contract root", ok: !!CONTRACT_ROOT, detail: CONTRACT_ROOT ?? "(미해결)" });
+
+  // 4. core 모듈 require 가능 여부.
+  let coreOk = false; let coreDetail = "";
+  try {
+    const mod = await import("@flextudio/contract-core");
+    coreOk = typeof mod.buildAjv === "function" && typeof mod.runAllCrossChecks === "function";
+    coreDetail = coreOk ? "buildAjv + runAllCrossChecks 로드됨" : "import 성공했지만 expected exports 없음";
+  } catch (e) {
+    coreDetail = `import 실패: ${e.message}`;
+  }
+  checks.push({ name: "@flextudio/contract-core", ok: coreOk, detail: coreDetail });
+
+  out("flex-scenario doctor");
+  out("─".repeat(60));
+  let allOk = true;
+  for (const c of checks) {
+    const mark = c.ok ? "✔" : (c.optional ? "○" : "✘");
+    if (!c.ok && !c.optional) allOk = false;
+    const tag = (!c.ok && c.optional) ? "  (optional)" : "";
+    out(`${mark} ${c.name.padEnd(34)}  ${c.detail}${tag}`);
+  }
+  out("─".repeat(60));
+  out(allOk ? "all required checks passed." : "일부 필수 항목 실패 — 위 detail 참고.");
+  process.exit(allOk ? 0 : 1);
+}
+
+/* ─── 서브커맨드: contract info ─────────────────────────────────────── */
+function cmdContract(positional) {
+  const sub = positional[0] ?? "info";
+  if (sub !== "info") { bad(`unknown subcommand: contract ${sub}`); process.exit(2); }
+  if (!CONTRACT_ROOT) {
+    bad("contract root 를 찾지 못함. FLEX_CONTRACT_ROOT 또는 'flex-scenario init' 실행 후 다시 시도.");
+    process.exit(2);
+  }
+  const catalog = (() => {
+    try { return JSON.parse(readFileSync(join(CONTRACT_ROOT, "spec", "catalog.json"), "utf-8")); }
+    catch { return {}; }
+  })();
+  const schemaDir = join(CONTRACT_ROOT, "schema", "v1");
+  let schemaCount = 0;
+  try {
+    const walk = (d) => {
+      for (const e of readdirSync(d)) {
+        const f = join(d, e);
+        const st = statSync(f);
+        if (st.isDirectory()) walk(f);
+        else if (e.endsWith(".schema.json")) schemaCount += 1;
+      }
+    };
+    walk(schemaDir);
+  } catch { /* ignore */ }
+  out(JSON.stringify({
+    contract: "flextudio meta-contract",
+    version: "v1",
+    contractRoot: CONTRACT_ROOT,
+    schemas: schemaCount,
+    catalogSections: Object.keys(catalog).filter((k) => !k.startsWith("$")),
+  }, null, 2));
+}
+
+/* ─── 서브커맨드: session start/status/finish (MCP build_sequence 동형) ── */
+const SESSIONS_DIR = join(homedir(), ".flex-scenario", "sessions");
+function sessionPath(id) { return join(SESSIONS_DIR, `${id}.json`); }
+function loadSession(id) {
+  const p = sessionPath(id);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, "utf-8")); }
+  catch { return null; }
+}
+function saveSession(s) {
+  mkdirSync(SESSIONS_DIR, { recursive: true });
+  writeFileSync(sessionPath(s.build_id), JSON.stringify(s, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * 주어진 폴더 최상위에서 가장 최근의 시나리오 *.json (Steps 키 보유) 경로를 찾는다.
+ * 산출물 회수의 파일 기반 폴백 — 큰 본문을 stdout/응답으로 받지 않고 디스크에서 직접 읽는다.
+ * schema 파일($schema/$id 보유, Steps 없음)은 자동 배제.
+ * ★ 산출물은 "현재 작업 폴더(cwd)" 에 쓴다.
+ */
+function findLatestScenario(root) {
+  if (!root) return null;
+  let entries;
+  try { entries = readdirSync(root); } catch { return null; }
+  let best = null;
+  let bestMtime = -1;
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    const p = join(root, name);
+    let st;
+    try { st = statSync(p); } catch { continue; }
+    if (!st.isFile()) continue;
+    try {
+      const j = JSON.parse(readFileSync(p, "utf-8"));
+      if (j && typeof j === "object" && !Array.isArray(j) && j.Steps && typeof j.Steps === "object") {
+        if (st.mtimeMs > bestMtime) { bestMtime = st.mtimeMs; best = p; }
+      }
+    } catch { /* 비 JSON / 부분 쓰기 무시 */ }
+  }
+  return best;
+}
+
+function cmdSession(positional, opts) {
+  const sub = positional[0];
+  if (!sub) { bad("usage: flex-scenario session {start|status|finish} [--id <build_id>]"); process.exit(2); }
+
+  if (sub === "start") {
+    const build_id = randomBytes(8).toString("hex");
+    const session = {
+      build_id,
+      stage: "started",
+      next: "context_ready → README.md / examples/index.json Read",
+      created: new Date().toISOString(),
+      updated: new Date().toISOString(),
+    };
+    saveSession(session);
+    out(JSON.stringify({ build_id, stage: session.stage, next: session.next }, null, 2));
+    return;
+  }
+
+  const id = opts.id;
+  if (!id) { bad("usage: flex-scenario session {status|finish} --id <build_id>"); process.exit(2); }
+  const s = loadSession(id);
+  if (!s) { bad(`session not found: ${id}`); process.exit(2); }
+
+  if (sub === "status") {
+    out(JSON.stringify(s, null, 2));
+    return;
+  }
+  if (sub === "finish") {
+    s.stage = "finished";
+    s.updated = new Date().toISOString();
+    // 산출물 경로 결정 — 회수 주체가 stdout 파싱 없이 이 경로만 신뢰한다.
+    //   1) --artifact <path> 명시.  2) 현재 작업 폴더(cwd) 내 최신 시나리오 *.json.
+    let artifact = null;
+    if (typeof opts.artifact === "string" && opts.artifact) {
+      artifact = resolve(opts.artifact);
+    } else {
+      artifact = findLatestScenario(process.cwd());
+    }
+    if (artifact) s.artifact = artifact;
+    saveSession(s);
+    out(JSON.stringify({ build_id: id, stage: "finished", artifact }, null, 2));
+    return;
+  }
+  bad(`unknown subcommand: session ${sub}`);
+  process.exit(2);
+}
+
+/* ─── 디스패치 ───────────────────────────────────────────────────────── */
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) { cmdHelp(); return; }
+  const [cmd, ...rest] = argv;
+  const { positional, opts } = parseArgs(rest);
+  switch (cmd) {
+    case "version": case "--version": case "-v":
+      return cmdVersion();
+    case "help": case "--help": case "-h":
+      return cmdHelp();
+    case "init":
+      return cmdInit(opts);
+    case "uninstall":
+      return cmdUninstall(opts);
+    case "catalog":
+      return cmdCatalog(opts);
+    case "examples":
+      return cmdExamples(positional);
+    case "validate":
+      return cmdValidate(positional, opts);
+    case "contract":
+      return cmdContract(positional);
+    case "session":
+      return cmdSession(positional, opts);
+    case "doctor":
+      return cmdDoctor();
+    case "login": {
+      const m = await importScript("auth.mjs");
+      return m.runLogin(rest);
+    }
+    case "logout": {
+      const m = await importScript("auth.mjs");
+      return m.runLogout(rest);
+    }
+    case "create": {
+      const m = await importScript("api-call.mjs");
+      return m.runApiCall(rest);
+    }
+    default:
+      bad(`unknown subcommand: ${cmd}`);
+      out("");
+      cmdHelp();
+      process.exit(2);
+  }
+}
+
+main().catch((e) => {
+  bad(e?.stack || e?.message || String(e));
+  process.exit(1);
+});