@flextudio/scenario 0.1.0

package/scripts/postinstall.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// postinstall — npm i -g @flextudio/scenario 후 / `flex-scenario init` 에서 자동 실행.
+//
+// 0. 어느 에이전트용으로 깔지 선택: claude / codex / antigravity / 나중에(4).
+//    - FLEX_AGENT 환경변수(=플래그)로 지정되면 그 값 사용.
+//    - 미지정 + 대화형(TTY)이면 메뉴로 물어본다.
+//    - 미지정 + 비TTY(npm i 자동)면 기본값(claude). "나중에" 는 아무것도 안 깔고 종료.
+// 1. skill/ 전체를 <설치폴더>/.<agent>/skills/scenario-gen/ 로 복사 (덮어쓰기 — 백업 안 함)
+// 2. command(flex-spec) 를 커맨드 위치로 복사 (claude 만 — codex/antigravity 는
+//    commandRel=null, 별도 진입점 없이 스킬의 스펙 요청으로 진입)
+// 3. contract-data/ 를 ~/.flex-scenario/contract-root/ 로 복사 (validate 진실원본)
+// 4. install-receipt.json 기록 — 어떤 폴더에 어느 에이전트로 깔았는지 (uninstall 이 정확히 되돌리게)
+// 5. "next: flex-scenario doctor" 안내
+//
+// 안전 원칙:
+//   - 실패 시에도 throw 하지 않음 (npm i 자체가 실패하면 사용자 경험 나쁨).
+//     단, 실패한 항목은 stderr 로 명시.
+//   - --ignore-scripts 같은 경우엔 이 스크립트가 안 돈다 (그건 npm 책임).
+
+import { mkdirSync, copyFileSync, cpSync, rmSync, writeFileSync, statSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import {
+  PACKAGE_ROOT, HOME,
+  SKILL_SRC, COMMAND_SRC, CONTRACT_DATA_SRC,
+  CONTRACT_DATA_DST, INSTALL_RECEIPT,
+  resolveInstallDir, skillPaths, isWorkspaceDevEnv,
+  AGENTS, DEFAULT_AGENT, resolveAgent,
+} from "./install-paths.mjs";
+import { resolveTTY, promptMenu } from "./tty-menu.mjs";
+
+const log  = (msg) => process.stdout.write(msg + "\n");
+const warn = (msg) => process.stderr.write(msg + "\n");
+
+/**
+ * Skip when running inside the meta-contract workspace dev-install.
+ * postinstall is meant for the user's machine *after* `npm i -g`.
+ * 워크스페이스 root 에 같은 패키지가 workspace 로 등록돼 있으면 dev 환경으로 본다.
+ * FLEX_SCENARIO_FORCE_POSTINSTALL=1 로 강제 가능.
+ */
+function shouldSkipForDev() {
+  if (process.env.FLEX_SCENARIO_FORCE_POSTINSTALL === "1") return false;
+  // npm 글로벌 install 시 npm_config_global=true 가 들어온다 — 그러면 절대 skip 하지 않음.
+  if (process.env.npm_config_global === "true") return false;
+  // 워크스페이스 dev install 판별은 install-paths.mjs 의 단일 구현 공유 (uninstall 가드와 동일).
+  return isWorkspaceDevEnv();
+}
+
+if (shouldSkipForDev()) {
+  log("[postinstall] workspace dev-install detected — ~/.claude 변경 skip.");
+  log("              (글로벌 설치 시점에만 사용자 머신에 깐다. FLEX_SCENARIO_FORCE_POSTINSTALL=1 로 우회 가능.)");
+  process.exit(0);
+}
+
+function ensureDir(p) { mkdirSync(p, { recursive: true }); }
+
+function exists(p) {
+  try { statSync(p); return true; } catch { return false; }
+}
+
+const MENU_ITEMS = [
+  { key: "claude",      label: AGENTS.claude.label },
+  { key: "codex",       label: AGENTS.codex.label },
+  { key: "antigravity", label: AGENTS.antigravity.label },
+  { key: "later",       label: "나중에 설치" },
+];
+
+// 설치할 에이전트 결정: FLEX_AGENT 우선 → TTY(직접 또는 /dev/tty) 면 메뉴 → 아니면 기본값.
+// 메뉴 조작감(방향키/숫자키/Esc=나중에/줄입력 폴백)은 tty-menu.mjs 공유 구현.
+async function decideAgent() {
+  const fromEnv = resolveAgent(process.env.FLEX_AGENT);
+  if (fromEnv) return { agent: fromEnv, source: "env" };
+  const io = resolveTTY();
+  if (io) {
+    try {
+      const agent = await promptMenu(io, {
+        header: "어느 에이전트용으로 설치할까요?",
+        items: MENU_ITEMS,
+        cancelKey: "later",
+        lineDefaultKey: DEFAULT_AGENT,
+        resolveAnswer: resolveAgent,
+      });
+      return { agent, source: "prompt" };
+    } finally { io.close(); }
+  }
+  return { agent: DEFAULT_AGENT, source: "default" };
+}
+
+async function main() {
+  const { agent, source } = await decideAgent();
+
+  if (agent === "later") {
+    log("");
+    log("· 설치를 건너뜁니다 (나중에 설치).");
+    log("  원할 때 설치 폴더에서: flex-scenario init --agent <claude|codex|antigravity>");
+    return;
+  }
+
+  // 설치 타겟 폴더 — "명령 친 폴더".
+  const installDir = resolveInstallDir();
+  const prof = AGENTS[agent];
+  const { DOT_DIR, SKILL_DST, COMMAND_DST } = skillPaths(installDir, agent);
+
+  if (source === "default") {
+    log(`[postinstall] 에이전트 미지정 → 기본값 ${prof.label} 으로 설치합니다.`);
+    log(`              다른 에이전트는: flex-scenario init --agent <codex|antigravity>`);
+  } else {
+    log(`[postinstall] 에이전트: ${prof.label}`);
+  }
+
+  // 타겟이 홈이면 사실상 전역 — 막지는 않되 경고.
+  if (installDir === resolve(HOME)) {
+    warn(`[postinstall] ⚠ 설치 타겟이 홈 디렉토리(${HOME}) — 사실상 전역에 깔립니다.`);
+    warn(`              특정 프로젝트 폴더로 이동해서 실행하면 그 폴더에만 깔립니다.`);
+  }
+
+  // 이전 설치 목록을 읽어 현재 (폴더, 에이전트) 와 union — uninstall 이 여러 설치를 한 번에 정리.
+  let priorInstalls = [];
+  let priorSkillDirs = [];
+  let priorUserAgent = null;
+  try {
+    if (exists(INSTALL_RECEIPT)) {
+      const prev = JSON.parse(readFileSync(INSTALL_RECEIPT, "utf-8"));
+      if (Array.isArray(prev.installs)) {
+        priorInstalls = prev.installs.filter((x) => x && typeof x.dir === "string");
+      } else if (Array.isArray(prev.skillDirs)) {
+        // 구버전 receipt(에이전트 정보 없음) → claude 로 간주.
+        priorInstalls = prev.skillDirs.filter((d) => typeof d === "string").map((d) => ({ dir: d, agent: "claude" }));
+      }
+      if (typeof prev.userAgent === "string" && prev.userAgent) priorUserAgent = prev.userAgent;
+    }
+  } catch { /* 손상된 receipt 는 무시하고 새로 쓴다 */ }
+
+  // (dir, agent) 키로 dedupe + 현재 설치 추가.
+  const seen = new Map();
+  for (const it of [...priorInstalls, { dir: installDir, agent }]) {
+    seen.set(`${resolve(it.dir)}::${it.agent}`, { dir: resolve(it.dir), agent: it.agent });
+  }
+  const installs = [...seen.values()];
+  // skillDirs: 구버전 cleanup 호환용으로 폴더 목록도 유지.
+  priorSkillDirs = [...new Set(installs.map((x) => x.dir))];
+
+  let pkgVersion = "0.0.0";
+  try {
+    pkgVersion = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8")).version || pkgVersion;
+  } catch { /* manifest 없으면 폴백 */ }
+
+  const receipt = {
+    version: pkgVersion,
+    installedAt: new Date().toISOString(),
+    packageRoot: PACKAGE_ROOT,
+    installDir,
+    agent,
+    // 설치에 쓰인 패키지 매니저 흔적 (예: "pnpm/9.x npm/? node/v20.x") — uninstall full 의
+    // 전역 제거 PM 판별(resolvePmRemove) 근거. `flex-scenario init` 재실행은 npm 환경
+    // 밖이라 env 가 비므로, 원래 전역 설치의 기록을 보존한다.
+    userAgent: process.env.npm_config_user_agent ?? priorUserAgent,
+    installs,
+    skillDirs: priorSkillDirs,
+  };
+
+  log(`[postinstall] 설치 폴더: ${installDir}`);
+  log(`              ${DOT_DIR}`);
+
+  // 1. Skill — 덮어쓰기 (백업 안 함)
+  if (!exists(SKILL_SRC)) {
+    warn(`[postinstall] skill/ 원본 없음: ${SKILL_SRC}`);
+  } else {
+    if (exists(SKILL_DST)) rmSync(SKILL_DST, { recursive: true, force: true });
+    ensureDir(dirname(SKILL_DST));
+    cpSync(SKILL_SRC, SKILL_DST, { recursive: true });
+    log(`✔ ${SKILL_DST}`);
+  }
+
+  // 1b. flex-spec (스펙 기반 생성 진입) — claude 만 슬래시 커맨드 파일로 깐다.
+  //     codex/antigravity 는 commandRel=null (별도 진입점 없이 스킬의 스펙 요청으로 진입).
+  if (!COMMAND_DST) {
+    log(`· ${prof.label} 은 flex-spec 진입점이 없습니다 — skip`);
+  } else if (!exists(COMMAND_SRC)) {
+    log(`· flex-spec 원본 없음 (구버전 tarball?) — skip`);
+  } else {
+    ensureDir(dirname(COMMAND_DST));
+    copyFileSync(COMMAND_SRC, COMMAND_DST);
+    log(`✔ ${COMMAND_DST}`);
+  }
+
+  // 2. Contract data (schema/examples/rules.md/catalog.json) — validate 의 진실원본. 덮어쓰기.
+  if (!exists(CONTRACT_DATA_SRC)) {
+    warn(`[postinstall] contract-data/ 원본 없음: ${CONTRACT_DATA_SRC}`);
+    warn(`  validate 서브커맨드가 동작하려면 FLEX_CONTRACT_ROOT 를 직접 지정해야 합니다.`);
+  } else {
+    if (exists(CONTRACT_DATA_DST)) rmSync(CONTRACT_DATA_DST, { recursive: true, force: true });
+    ensureDir(dirname(CONTRACT_DATA_DST));
+    cpSync(CONTRACT_DATA_SRC, CONTRACT_DATA_DST, { recursive: true });
+    log(`✔ ${CONTRACT_DATA_DST}`);
+  }
+
+  // 3. Receipt
+  try {
+    ensureDir(dirname(INSTALL_RECEIPT));
+    writeFileSync(INSTALL_RECEIPT, JSON.stringify(receipt, null, 2) + "\n", "utf-8");
+  } catch (e) {
+    warn(`[postinstall] receipt 기록 실패: ${e.message}`);
+  }
+
+  log("");
+  log(`✔ 설치 완료 (${prof.label}): ${DOT_DIR}`);
+  log("  이 폴더(또는 하위)에서 해당 에이전트를 열면 scenario-gen 스킬이 인식됩니다.");
+  log("  다른 폴더/에이전트로 쓰려면: flex-scenario init --agent <claude|codex|antigravity>");
+  log("");
+  log("next step: flex-scenario doctor");
+}
+
+main().catch((e) => {
+  // 절대로 npm install 자체가 실패하지 않도록 swallow.
+  warn(`[postinstall] 예기치 못한 에러: ${e?.stack || e?.message || e}`);
+  process.exit(0);
+});

package/scripts/postpack.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// postpack — prepack 이 일시 생성한 contract-data/ 를 정리.
+// 워크스페이스가 더러워지지 않게 항상 cleanup.
+//
+// 환경변수 FLEX_KEEP_CONTRACT_DATA=1 이면 정리 생략 (디버깅용).
+
+import { existsSync, rmSync, renameSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PACKAGE_ROOT = dirname(__dirname);
+const CONTRACT_DATA = join(PACKAGE_ROOT, "contract-data");
+// commands/ 는 staging 이 아니라 패키지 안 진실원본(git 추적)이므로 postpack 정리 대상 아님.
+
+if (process.env.FLEX_KEEP_CONTRACT_DATA === "1") {
+  process.stdout.write(`[postpack] FLEX_KEEP_CONTRACT_DATA=1 → ${CONTRACT_DATA} 보존\n`);
+  process.exit(0);
+}
+
+if (existsSync(CONTRACT_DATA)) {
+  rmSync(CONTRACT_DATA, { recursive: true, force: true });
+  process.stdout.write(`[postpack] cleanup ${CONTRACT_DATA}\n`);
+}
+
+// prepack 이 일시 갱신한 package.json 복구.
+const pkgPath = join(PACKAGE_ROOT, "package.json");
+const backupPkgPath = join(PACKAGE_ROOT, "package.json.prepack-bak");
+if (existsSync(backupPkgPath)) {
+  rmSync(pkgPath, { force: true });
+  renameSync(backupPkgPath, pkgPath);
+  process.stdout.write(`[postpack] package.json 복원\n`);
+}
+
+// prepack 이 vendoring 한 workspace + 모든 transitive deps 도 정리 → 다시 npm install
+// 시 정상적으로 hoist 되도록.
+const PKG_NODE_MODULES = join(PACKAGE_ROOT, "node_modules");
+if (existsSync(PKG_NODE_MODULES)) {
+  rmSync(PKG_NODE_MODULES, { recursive: true, force: true });
+  process.stdout.write(`[postpack] cleanup ${PKG_NODE_MODULES}\n`);
+}

package/scripts/prepack.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// prepack — npm pack / publish 직전에 단일 진실 원본 + 프로파일별 의존을 패키지로 동봉.
+//
+// 목적:
+//   - meta-contract 의 schema/ + catalog.json + rules.md + examples/ + README.md 는
+//     단일 진실 원본 (다른 위치에 중복 둘 수 없음). 그러나 npm i -g 한 사용자의
+//     머신엔 워크스페이스가 없으므로 이 데이터가 어딘가에 함께 들어가야 한다.
+//   - 그래서 npm pack 시점에만 contract-data/ 디렉토리를 일시 생성해 tarball 에
+//     동봉하고, postpack 에서 그 디렉토리를 삭제한다 (workspace 상태를 깨끗히).
+//
+// 빌드: @flextudio/scenario (otel 없는 클린 배포본). core 만 vendor.
+//   (벤치/otel 빌드는 분리 — bench/cli_bench 는 pack 없이 워크스페이스에서 직접 실행.)
+//
+// 동기화 대상(contract-data):
+//   <repo-root>/schema            → ./contract-data/schema
+//   <repo-root>/examples          → ./contract-data/examples
+//   <repo-root>/runtime           → ./contract-data/runtime
+//   <repo-root>/spec/catalog.json → ./contract-data/spec/catalog.json
+//   <repo-root>/spec/rules.md     → ./contract-data/spec/rules.md
+//   <repo-root>/README.md         → ./contract-data/README.md
+
+import { existsSync, mkdirSync, cpSync, rmSync, copyFileSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PACKAGE_ROOT = dirname(__dirname);
+// cli/ 는 repo 루트 바로 아래 → 한 단계 위가 REPO_ROOT.
+const REPO_ROOT = resolve(PACKAGE_ROOT, "..");
+const CONTRACT_DATA = join(PACKAGE_ROOT, "contract-data");
+
+// rules.md·catalog.json 은 spec/ 아래. 설치된 contract-root 도 동일 구조(spec/)여야
+// core/paths.mjs (RULES_PATH/CATALOG_PATH = CONTRACT_ROOT/spec/…) 가 해석된다.
+const SOURCES = [
+  { src: join(REPO_ROOT, "schema"),            dst: join(CONTRACT_DATA, "schema"),            type: "dir" },
+  { src: join(REPO_ROOT, "examples"),          dst: join(CONTRACT_DATA, "examples"),          type: "dir" },
+  { src: join(REPO_ROOT, "runtime"),           dst: join(CONTRACT_DATA, "runtime"),           type: "dir" },
+  { src: join(REPO_ROOT, "spec", "catalog.json"), dst: join(CONTRACT_DATA, "spec", "catalog.json"), type: "file" },
+  { src: join(REPO_ROOT, "spec", "rules.md"),     dst: join(CONTRACT_DATA, "spec", "rules.md"),     type: "file" },
+  { src: join(REPO_ROOT, "README.md"),         dst: join(CONTRACT_DATA, "README.md"),         type: "file" },
+];
+
+function exists(p) { try { statSync(p); return true; } catch { return false; } }
+
+const log = (msg) => process.stdout.write(`[prepack] ${msg}\n`);
+
+if (existsSync(CONTRACT_DATA)) {
+  rmSync(CONTRACT_DATA, { recursive: true, force: true });
+}
+mkdirSync(CONTRACT_DATA, { recursive: true });
+
+let missing = [];
+for (const { src, dst, type } of SOURCES) {
+  if (!exists(src)) {
+    missing.push(src);
+    continue;
+  }
+  if (type === "dir") {
+    cpSync(src, dst, { recursive: true });
+  } else {
+    mkdirSync(dirname(dst), { recursive: true });
+    copyFileSync(src, dst);
+  }
+  log(`copy ${src} → ${dst}`);
+}
+
+if (missing.length) {
+  process.stderr.write(`[prepack] 다음 source 가 없습니다:\n${missing.map((m) => "  - " + m).join("\n")}\n`);
+  process.exit(1);
+}
+
+log(`contract-data ready: ${CONTRACT_DATA}`);
+
+/* ─── 슬래시 커맨드 동봉 sanity (/flex-spec) ──────────────────────────
+ * 진실원본은 패키지 안 cli/commands/flex-spec.md (git 추적, files=["commands"]
+ * 로 자동 동봉). staging 불필요 — 존재만 확인하고 postinstall 이 ~/.claude/commands/
+ * 로 깐다. (.claude/commands/ 미러는 SOURCE-MAP 전파 절차로 동기화.)
+ */
+const COMMAND_PKG = join(PACKAGE_ROOT, "commands", "flex-spec.md");
+if (!exists(COMMAND_PKG)) {
+  process.stderr.write(`[prepack] 슬래시 커맨드 원본 없음: ${COMMAND_PKG}\n`);
+  process.exit(1);
+}
+log(`command bundled: ${COMMAND_PKG}`);
+
+/* ─── workspace deps vendoring ────────────────────────────────────────────
+ * 워크스페이스 환경에서 npm 은 의존성을 root node_modules 로 hoist 한다.
+ * 그래서 패키지 자체의 node_modules 가 비어 있어 bundleDependencies 가 묶을
+ * 대상이 없다. prepack 단계에서 workspace 의존을 패키지 안 node_modules 로
+ * 명시적으로 복사 → bundleDependencies 가 정상 동작하게 한다.
+ *
+ * 외부 OSS 의존성(ajv)은 npm install 이 root node_modules 에 깔아두며, 아래
+ * transitive vendoring 이 패키지 안으로 복사해 번들한다.
+ *
+ * symlink 가 아닌 실제 copy 로 떠야 npm pack 이 tarball 에 포함시킨다.
+ */
+const VENDOR_TARGETS = [
+  { name: "@flextudio/contract-core", src: join(REPO_ROOT, "core") },
+];
+
+const PKG_NODE_MODULES = join(PACKAGE_ROOT, "node_modules");
+mkdirSync(PKG_NODE_MODULES, { recursive: true });
+
+for (const { name, src } of VENDOR_TARGETS) {
+  const dst = join(PKG_NODE_MODULES, name);
+  if (existsSync(dst)) {
+    rmSync(dst, { recursive: true, force: true });
+  }
+  if (!exists(src)) {
+    process.stderr.write(`[prepack] workspace source 없음: ${src}\n`);
+    process.exit(1);
+  }
+  cpSync(src, dst, {
+    recursive: true,
+    filter: (p) => !p.includes(`${dst.split(name)[0]}node_modules`) && !p.endsWith("/.DS_Store"),
+  });
+  log(`vendor ${src} → ${dst}`);
+}
+
+/* ─── full transitive vendoring ───────────────────────────────────────────
+ * protobufjs 7.6.0 의 npm registry tarball 결함 등으로 글로벌 install 시 외부
+ * dep tree 일부가 깨질 수 있다. 우리 패키지 dependencies + transitive 까지 모두
+ * hoisted REPO_ROOT/node_modules 에서 PACKAGE_ROOT/node_modules 로 미리 복사
+ * 하고, bundleDependencies 로 한꺼번에 묶어 외부 install 을 0 으로 만든다.
+ *
+ * package.json 의 bundleDependencies 필드는 prepack 종료 시점에 transitive 까지
+ * 자동 갱신한다 (npm pack 이 그 시점의 값으로 tar.gz 메타에 기록).
+ */
+function readPkg(absPath) {
+  try { return JSON.parse(readFileSync(join(absPath, "package.json"), "utf-8")); }
+  catch { return null; }
+}
+
+function findHoistedPath(name) {
+  // 1. REPO_ROOT/node_modules/<name>
+  const a = join(REPO_ROOT, "node_modules", name);
+  if (exists(a)) return a;
+  // 2. PACKAGE_ROOT/node_modules/<name> (이미 우리가 vendor 한 워크스페이스 의존이면 거기)
+  const b = join(PACKAGE_ROOT, "node_modules", name);
+  if (exists(b)) return b;
+  return null;
+}
+
+function collectTransitive(rootDeps) {
+  const visited = new Set();
+  const stack = [...rootDeps];
+  while (stack.length) {
+    const name = stack.pop();
+    if (visited.has(name)) continue;
+    const hoisted = findHoistedPath(name);
+    if (!hoisted) continue;  // 누락 → 외부 dep 으로 일반 install 위임
+    visited.add(name);
+    const pkg = readPkg(hoisted);
+    if (!pkg) continue;
+    for (const dep of Object.keys(pkg.dependencies ?? {})) {
+      if (!visited.has(dep)) stack.push(dep);
+    }
+  }
+  return visited;
+}
+
+// ─── package.json dependencies 확정 ───────────────────────────────
+// on-disk package.json: dependencies = { contract-core, ajv }.
+const selfPkg = readPkg(PACKAGE_ROOT);
+const baseDeps = { ...(selfPkg.dependencies ?? {}) };
+selfPkg.dependencies = baseDeps;
+// devDependencies 는 tarball 메타에서 제거 (런타임 무관, 깨끗한 manifest).
+delete selfPkg.devDependencies;
+
+const rootDeps = Object.keys(selfPkg.dependencies);
+const allDeps = collectTransitive(rootDeps);
+// 우리가 위에서 vendor 한 워크스페이스 의존은 별도 처리 — 이 트리에 포함되므로 skip.
+const SKIP = new Set(VENDOR_TARGETS.map((t) => t.name));
+
+let vendoredCount = 0;
+for (const name of allDeps) {
+  if (SKIP.has(name)) continue;
+  const src = findHoistedPath(name);
+  if (!src) {
+    process.stderr.write(`[prepack] hoisted 위치를 찾지 못한 dep: ${name}\n`);
+    continue;
+  }
+  const dst = join(PKG_NODE_MODULES, name);
+  if (existsSync(dst)) rmSync(dst, { recursive: true, force: true });
+  // npm 정책: 패키지의 node_modules 는 다시 복사하지 않는다 (또 다른 hoist 단계).
+  cpSync(src, dst, {
+    recursive: true,
+    filter: (p) => {
+      const rel = p.slice(src.length);
+      return !rel.startsWith("/node_modules") && !p.endsWith("/.DS_Store");
+    },
+  });
+  vendoredCount += 1;
+}
+log(`vendored ${vendoredCount} transitive dep(s) into ${PKG_NODE_MODULES}`);
+
+// bundleDependencies 갱신 — workspace deps + 모든 transitive 외부 deps.
+const bundle = new Set([
+  ...VENDOR_TARGETS.map((t) => t.name),
+  ...[...allDeps].filter((d) => !SKIP.has(d)),
+]);
+selfPkg.bundleDependencies = [...bundle].sort();
+// package.json 자체를 일시적으로 갱신 (name/dependencies/bundleDependencies). postpack 에서 원상 복귀.
+const pkgPath = join(PACKAGE_ROOT, "package.json");
+const backupPkgPath = join(PACKAGE_ROOT, "package.json.prepack-bak");
+copyFileSync(pkgPath, backupPkgPath);
+writeFileSync(pkgPath, JSON.stringify(selfPkg, null, 2) + "\n", "utf-8");
+log(`package.json: name=${selfPkg.name}, bundleDependencies=${bundle.size} entries — backup at ${backupPkgPath}`);
+
+// build-skill-payload — 계약 진실원본(core/contract.mjs + schema/v1 + examples + catalog/rules)을
+// skill/ 아래로 펼침. (prepack 끝 단계에서 1회. tgz 안에 정적 자산이 동봉됨.)
+log(`build-skill-payload …`);
+const { spawnSync: _spawnSync } = await import("node:child_process");
+const skillBuild = _spawnSync(process.execPath,
+  [join(__dirname, "build-skill-payload.mjs")],
+  { stdio: "inherit" });
+if (skillBuild.status !== 0) {
+  process.stderr.write(`[prepack] build-skill-payload 실패 (exit=${skillBuild.status})\n`);
+  process.exit(skillBuild.status ?? 1);
+}

package/scripts/tty-menu.mjs

@@ -0,0 +1,100 @@
+// 대화형 TTY 메뉴 공유 헬퍼 — postinstall(에이전트 선택)과 bin 의
+// uninstall(삭제 범위 선택)이 같은 조작감을 공유한다.
+//   - 방향키(↑/↓) 이동 + Enter 선택, 숫자키 1..n 즉시선택
+//   - Esc / q / Ctrl-C → cancelKey 반환
+//   - raw mode 불가(일부 CI/터미널) → 줄입력 메뉴로 폴백
+
+import { openSync } from "node:fs";
+import { createInterface, emitKeypressEvents } from "node:readline";
+import tty from "node:tty";
+
+// 사용자와 대화할 TTY 확보:
+//   1. process.stdin/stdout 이 둘 다 TTY (예: `flex-scenario init`) → 그대로 사용.
+//   2. 아니면(예: `npm i` 는 stdin/stdout 을 파이프로 막음) /dev/tty 를 직접 열어 사용.
+//   3. /dev/tty 도 없으면(CI·비대화형) null → 호출측이 기본값/안전 거부로 폴백.
+export function resolveTTY() {
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    return { input: process.stdin, output: process.stdout, close() {} };
+  }
+  try {
+    const input = new tty.ReadStream(openSync("/dev/tty", "r"));
+    const output = new tty.WriteStream(openSync("/dev/tty", "w"));
+    if (!input.isTTY) { try { input.destroy(); output.destroy(); } catch {} return null; }
+    return {
+      input, output,
+      close() { try { input.destroy(); } catch {} try { output.destroy(); } catch {} },
+    };
+  } catch { return null; }
+}
+
+// 방향키 메뉴 — items=[{key,label}], 반환 Promise<선택된 key>.
+//   header        : 질문 한 줄 (raw 메뉴에선 "(↑/↓ 이동 · Enter 선택)" 가 붙는다)
+//   cancelKey     : Esc/q/Ctrl-C 가 반환할 key
+//   lineDefaultKey: 줄입력 폴백에서 빈 입력 시 반환할 key (기본 cancelKey)
+//   resolveAnswer : 줄입력 폴백의 자유 입력 해석기 (선택 — 없으면 1..n 숫자만)
+export function promptMenu(io, { header, items, cancelKey, lineDefaultKey, resolveAnswer } = {}) {
+  if (!io.input.setRawMode) {
+    return promptMenuLine(io, { header, items, cancelKey, lineDefaultKey, resolveAnswer }); // raw 불가 → 폴백
+  }
+
+  return new Promise((res) => {
+    let idx = 0;
+    const HEADER = `${header} (↑/↓ 이동 · Enter 선택)`;
+    emitKeypressEvents(io.input);
+    const wasRaw = !!io.input.isRaw;
+    io.input.setRawMode(true);
+    io.input.resume();
+
+    const draw = (first) => {
+      if (!first) io.output.write(`\x1b[${items.length + 1}A`); // 헤더+항목 줄 수만큼 위로
+      io.output.write(HEADER + "\x1b[K\n");
+      items.forEach((it, i) => {
+        const on = i === idx;
+        io.output.write(`${on ? "\x1b[36m❯ " : "  "}${it.label}${on ? "\x1b[0m" : ""}\x1b[K\n`);
+      });
+    };
+    const finish = (picked) => {
+      io.input.removeListener("keypress", onKey);
+      try { io.input.setRawMode(wasRaw); } catch {}
+      io.input.pause();
+      io.output.write("\n");
+      res(picked);
+    };
+    const onKey = (str, key) => {
+      if (!key) return;
+      if (key.name === "up")        { idx = (idx - 1 + items.length) % items.length; draw(false); }
+      else if (key.name === "down") { idx = (idx + 1) % items.length; draw(false); }
+      else if (key.name === "return" || key.name === "enter") finish(items[idx].key);
+      else if ((key.name === "c" && key.ctrl) || key.name === "escape" || key.name === "q") finish(cancelKey);
+      else if (/^[1-9]$/.test(str ?? "") && Number(str) <= items.length) finish(items[Number(str) - 1].key);
+    };
+    draw(true);
+    io.input.on("keypress", onKey);
+  });
+}
+
+// 폴백: raw mode 불가 환경(일부 CI/터미널)에서 줄입력 메뉴.
+function promptMenuLine(io, { header, items, cancelKey, lineDefaultKey, resolveAnswer }) {
+  const defKey = lineDefaultKey ?? cancelKey;
+  const defLabel = items.find((it) => it.key === defKey)?.label ?? defKey;
+  return new Promise((res) => {
+    const rl = createInterface({ input: io.input, output: io.output });
+    const menu =
+      `\n${header}\n` +
+      items.map((it, i) => `  ${i + 1}) ${it.label}`).join("\n") +
+      `\n선택 [1-${items.length}] (기본 ${defLabel}): `;
+    const ask = () => rl.question(menu, (ans) => {
+      const a = String(ans).trim();
+      if (a === "") { rl.close(); return res(defKey); }
+      const byCustom = resolveAnswer ? resolveAnswer(a) : null;
+      const byIndex = /^[0-9]+$/.test(a) && Number(a) >= 1 && Number(a) <= items.length
+        ? items[Number(a) - 1].key
+        : null;
+      const picked = byCustom ?? byIndex;
+      if (picked) { rl.close(); return res(picked); }
+      io.output.write(`  ↳ 1~${items.length} 중에서 골라주세요.\n`);
+      ask();
+    });
+    ask();
+  });
+}

package/skill/README.md

@@ -0,0 +1,55 @@
+# scenario-gen — 생성 오리엔테이션
+
+flextudio meta-contract v1 화면 시나리오 JSON 을 만드는 스킬의 **생성 관점 전용** 안내.
+(컨트랙트 내부 구조·폴더 레이아웃·엔진 호환은 생성과 무관하므로 제외 — 필요 시 repo 루트 `README.md`.)
+권위 절차는 `SKILL.md`, 스타일 어휘는 `design-rules.md`, 런타임 short-form 은 `intent-rules.md`.
+
+## ★ 생성 결정 규칙 (노드를 만들기 전에 먼저 판정)
+
+생성 오류의 대부분은 아래 결정을 건너뛰어 발생한다. 컨트롤/그룹을 쓰기 전에 판정할 것.
+
+- **A. 데이터 표시 — 정적 vs 동적** (`[proto]` 차단 1차 원인):
+  - 정적 문구·단건 라벨 → `Label` (`LabelType:'labeltext'` + `labeltext:'값'`). `DataConnection`/`Ckeys`/`LabelCKey` 박지 말 것.
+  - 리스트 반복·Combo/Search 선택지·Calendar 데이터 → Group `UseDataConnection:true` + `DataConnection`(**객체** `{TargetType:'category', DataUsage, CategoryName}`) + 자식 `Ckeys`/`LabelCKey`. **이때 반드시 시작 Step.Init 에 mock 동반** — `Step.Events.Init:"<핸들러>"`(문자열) + `scenario.Events.<핸들러>` 안에 `intent.mock:{ Ctg<X>:[{...}] }`. (인라인 배열 Init / named 핸들러 밖 intent.mock 금지.)
+  - 예외: 실제 `scenario.DataSources`(`Fixed`/`Grid`) 가 있으면 mock 없이도 정상 바인딩.
+- **B. 작성 형식 — short-form 우선**:
+  - 스타일 → `design` 키 (Group/Control). 표현 불가 시에만 raw escape. 상세 `design-rules.md`.
+  - 데이터/스크립트 → `intent` 키 (`mock`/`script`). 상세 `intent-rules.md`. 펼침 후 raw 는 화이트리스트 검사.
+  - 반복 렌더링 → `DataConnection.DataUsage:'query'` (`UseInnerBlock`/`RepeatStyle` 금지).
+- **컨트롤 선택**: v1 15종만(아래 범위). 컨트롤별 필수/옵션·흔한 오해(InputType↔MaskType, LabelType, 버튼 Click, InputFile Module, Fixed Combo SaveNameKey)는 `skill-guides/control-options.md`.
+- **모든 Group 에 `UseDataConnection` 명시**(비연결도 `false`). `Collections`/`ServiceBinding` 은 `{}` 고정.
+
+상세 작성 순서·자가검증 루프·실패 복구는 `SKILL.md` 와 `skill-guides/failure-discipline.md`.
+
+## v1 컨트랙트 범위
+
+### 노드
+- **Step**: `StepView` (`""`/`SlideUp`/`PopUp`), `StepSub`
+- **Group**: 단일 (Layout 흡수). DataConnection 5종 (`default`/`new`/`update`/`detail`/`query`)
+- **Control 15종**: `InputText`, `InputNumber`, `InputMask`, `InputDate`, `MultiInputBox`, `Combo`, `Search`, `CheckBox`, `RadioBox`, `Label`, `ImageBox`, `InputFile`, `Tree`, `Tab`, `Embed`
+
+### 범위 외 (부분 통과)
+- 그 외 ControlType (`Button`/`Calendar`(단독)/`ComboList`(단독)/`List`(단독)/`Signature`/`Line` 등) — `OtherControl` fallback 으로 통과만.
+- ServiceBinding/Events 핸들러/DataSources 상세, LoadScript/Event Script DSL 검증.
+
+v1 은 범위 외 노드도 `additionalProperties:true` 로 받아넘기므로 **부분 검증**은 통과한다.
+
+## 검증 (자가검증 루프의 도구)
+
+CLI 진입은 `flex-scenario` (PATH). command not found 면 `node "$(npm root -g)/@flextudio/scenario/bin/flex-scenario.mjs" ...`.
+
+```bash
+flex-scenario validate <scenario.json>              # 전체 시나리오 (schema + 모든 cross-check)
+flex-scenario validate --schema <ref> <fragment>    # 단편(Group/Control/DataSource) — cross-check 없이 schema 만
+flex-scenario validate --no-write <file>            # 검증만 (materialized write-back 안 함)
+```
+
+`<ref>` 4형태: file key(`control/input-text.schema.json`) · `$id` · shorthand(`input-text`/`group`) · 부분 문자열(단일 매칭). `#/$defs/<name>` JSON Pointer 도 가능.
+
+```bash
+flex-scenario validate --schema input-text fragment.json
+flex-scenario validate --schema group group-fragment.json
+flex-scenario validate --schema 'data-sources#/$defs/dataSource' ds.json
+```
+
+**에러 읽기**: `errorCount` 는 볼륨(한 원인의 cascade). `kind:schema` 를 가장 깊은 `instancePath` 부터, `oneOf`("must match exactly one schema")·`strict-fields` 는 대개 cascade 노이즈. 태그(`[proto]`/`[mock-init]`/`[date]`/`[ds-key]`/`[combo-fixed]`/`[group-dc]`/`[step-nav]`/`[event-ref]`/`[display-key]` …) ↔ 룰 매핑은 `design-rules.md`, 복구 규율은 `skill-guides/failure-discipline.md`. fragment-first 로 좁히고 한 번에 한 곳만 고친다.