@flextudio/scenario 0.1.0

package/node_modules/@flextudio/contract-core/contract.mjs

@@ -0,0 +1,367 @@
+// catalog.json / rules.md / schema/v1/*.md / examples/*.json 로더.
+// 모든 경로는 meta-contract/ 폴더 안에서만 해석.
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, normalize, isAbsolute } from "node:path";
+
+import {
+  CONTRACT_ROOT,
+  SCHEMA_ROOT,
+  PATTERNS_ROOT,
+  EXAMPLES_ROOT,
+  CATALOG_PATH,
+  RULES_PATH,
+  README_PATH,
+  DESIGN_SYSTEM_PATH,
+  DESIGN_RULES_PATH,
+  SKELETON_SHELL_PATH,
+} from "./paths.mjs";
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function readText(path) {
+  return readFileSync(path, "utf8");
+}
+
+/** 외부 경로 escape 차단 — 결과 절대경로가 root 아래여야 함. */
+function safeJoin(root, name) {
+  if (typeof name !== "string" || !name)
+    throw new Error(`invalid name: ${name}`);
+  if (isAbsolute(name)) throw new Error(`absolute paths not allowed: ${name}`);
+  const full = normalize(join(root, name));
+  const rel = relative(root, full);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`path escapes root: ${name}`);
+  }
+  return full;
+}
+
+/* ----- catalog ----- */
+export function getCatalog() {
+  return readJson(CATALOG_PATH);
+}
+
+/* ----- rules / readme ----- */
+export function getRules() {
+  return readText(RULES_PATH);
+}
+export function getReadme() {
+  return readText(README_PATH);
+}
+
+/* ----- design system ----- */
+export function getDesignSystem() {
+  return readText(DESIGN_SYSTEM_PATH);
+}
+
+/**
+ * get_design_rules 도구의 진리원.
+ *
+ * DESIGN.md (디자인 토큰 + 패턴-우선 emission 정책 + 컴포넌트→패턴 매핑) 와
+ * SKELETON-SHELL.md (scenario / Steps / Step / Events / BottomButtons 의 outer
+ * shell 스켈레톤 + 고정값 gotcha) 를 하나의 응답으로 합쳐 반환한다.
+ *
+ * 두 문서를 묶는 이유:
+ * - 패턴은 Contents[] 안의 컴포지션만 커버. outer shell (ScenarioMeta + Steps +
+ *   Step 메타) 은 항상 raw 라서 LLM 이 schema 진리원에 닿을 surface 가 따로 필요.
+ * - 같은 단계 (build_sequence stage = `get_design_rules`) 에 emit 직전 필수 정보를
+ *   한 번에 제공 — 도구 호출 추가 없이 outer shell 정합성 확보.
+ *
+ * 합치는 방식: DESIGN.md 본문 + 구분자 + SKELETON-SHELL.md 본문 (단순 concat).
+ */
+export function getDesignRules() {
+  const design = readText(DESIGN_RULES_PATH);
+  const shell = readText(SKELETON_SHELL_PATH);
+  const separator =
+    "\n\n---\n\n" +
+    "<!-- ↑ DESIGN.md (tokens + pattern-first policy) — ↓ SKELETON-SHELL.md (outer wrap reference) -->\n\n";
+  return design.trimEnd() + separator + shell.trimStart();
+}
+
+/** SKELETON-SHELL.md 단독 본문. get_design_rules 응답에 포함되지만, 외부 introspection / 테스트용. */
+export function getSkeletonShell() {
+  return readText(SKELETON_SHELL_PATH);
+}
+
+/* ----- patterns (atom / molecule / organism) — 동적 카탈로그 ----- */
+
+const PATTERN_TIERS = ["atom", "molecule", "organism"];
+const PATTERN_DESC_MAX = 280;
+
+/**
+ * 단일 prop 의 JSON Schema 노드에서 LLM picker 에 유용한 요약만 추출.
+ * 깊은 nested 객체/배열의 내부 구조는 생략 — get_pattern (전체 schema) 으로 받는다.
+ */
+function summarizeProp(propSchema) {
+  if (!propSchema || typeof propSchema !== "object") return null;
+  const out = {};
+  if (propSchema.type !== undefined) out.type = propSchema.type;
+  if (Array.isArray(propSchema.enum)) out.enum = propSchema.enum;
+  if (propSchema.type === "array") {
+    if (propSchema.minItems != null) out.minItems = propSchema.minItems;
+    if (propSchema.maxItems != null) out.maxItems = propSchema.maxItems;
+    if (propSchema.items && propSchema.items.type) {
+      out.items = propSchema.items.type;
+    }
+  }
+  if (propSchema.default !== undefined) out.default = propSchema.default;
+  return out;
+}
+
+function summarizePropsForList(schema) {
+  const required = Array.isArray(schema.required) ? schema.required.slice() : [];
+  const props = {};
+  const order = [];
+  if (schema.properties && typeof schema.properties === "object") {
+    for (const [key, val] of Object.entries(schema.properties)) {
+      const s = summarizeProp(val);
+      if (s) props[key] = s;
+      order.push(key);
+    }
+  }
+  const optional = order.filter((k) => !required.includes(k));
+  return { required, optional, props };
+}
+
+function capDescription(desc, max = PATTERN_DESC_MAX) {
+  if (typeof desc !== "string") return "";
+  const trimmed = desc.trim();
+  if (trimmed.length <= max) return trimmed;
+  return trimmed.slice(0, max).trimEnd() + "...";
+}
+
+/**
+ * tier 디렉터리 1개를 스캔해서 패턴 summary 배열 반환.
+ * 디렉터리가 없으면 빈 배열 (organism 미구현 상태 등).
+ */
+function scanTier(tier) {
+  const dir = join(PATTERNS_ROOT, tier);
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".schema.json")) continue;
+    const name = entry.slice(0, -".schema.json".length);
+    let schema;
+    try {
+      schema = readJson(join(dir, entry));
+    } catch {
+      continue;
+    }
+    out.push({
+      tier,
+      name,
+      title: schema.title ?? `pattern.${tier}.${name}`,
+      description: capDescription(schema.description ?? ""),
+      tags: Array.isArray(schema["x-tags"]) ? schema["x-tags"] : [],
+      related: Array.isArray(schema["x-related"]) ? schema["x-related"] : [],
+      propsSummary: summarizePropsForList(schema),
+    });
+  }
+  return out;
+}
+
+/**
+ * 단일 패턴의 전체 schema 반환 — list_patterns 의 요약본과 달리 description /
+ * properties / examples / allOf if-then 등 본문 전체 포함. LLM 이 emission 직전
+ * prop 매핑을 확정할 때 사용.
+ *
+ *   getPattern({ name: "button" })                  // atom/molecule/organism 전체 검색
+ *   getPattern({ name: "input-pair", tier: "molecule" }) // tier 명시
+ *
+ * 응답 shape: { tier, name, path, schema }.
+ * 미존재: throw — 후보 제안 (substring 매칭) 포함.
+ * 모호 (동일 name 이 여러 tier 에 존재): throw — tier 명시 요구.
+ */
+export function getPattern({ tier, name } = {}) {
+  if (typeof name !== "string" || !name || !/^[a-z][a-z0-9-]*$/i.test(name)) {
+    throw new Error(
+      `getPattern: invalid name '${name}' — kebab-case alphanumeric ([a-z][a-z0-9-]*) 만 허용`,
+    );
+  }
+  const tryRead = (t) => {
+    const file = `${name}.schema.json`;
+    const full = join(PATTERNS_ROOT, t, file);
+    try {
+      return { tier: t, name, path: `schema/v1/patterns/${t}/${file}`, schema: readJson(full) };
+    } catch {
+      return null;
+    }
+  };
+
+  if (tier) {
+    if (!PATTERN_TIERS.includes(tier)) {
+      throw new Error(
+        `getPattern: invalid tier '${tier}' — must be one of ${PATTERN_TIERS.join("/")}`,
+      );
+    }
+    const hit = tryRead(tier);
+    if (hit) return hit;
+    throw new Error(
+      `getPattern: pattern '${tier}/${name}' not found. list_patterns 로 사용 가능한 이름 확인.`,
+    );
+  }
+
+  // tier 미지정 — 전체 검색.
+  const matches = PATTERN_TIERS.map(tryRead).filter(Boolean);
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    const tiers = matches.map((m) => m.tier).join(", ");
+    throw new Error(
+      `getPattern: ambiguous name '${name}' — 여러 tier 에 존재 (${tiers}). tier 인자로 명시.`,
+    );
+  }
+
+  // 미존재 — substring 후보 제안.
+  const candidates = [];
+  for (const t of PATTERN_TIERS) {
+    let entries;
+    try {
+      entries = readdirSync(join(PATTERNS_ROOT, t));
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.endsWith(".schema.json")) continue;
+      const candName = e.slice(0, -".schema.json".length);
+      if (
+        candName.toLowerCase().includes(name.toLowerCase()) ||
+        name.toLowerCase().includes(candName.toLowerCase())
+      ) {
+        candidates.push(`${t}/${candName}`);
+      }
+    }
+  }
+  const hint = candidates.length
+    ? ` 후보: ${candidates.slice(0, 8).join(", ")}.`
+    : " list_patterns 로 사용 가능한 이름 확인.";
+  throw new Error(`getPattern: pattern '${name}' not found.${hint}`);
+}
+
+/**
+ * 동적 패턴 카탈로그. tier / tag 필터 지원.
+ *
+ *   listPatterns()                         // 전체
+ *   listPatterns({ tier: "atom" })         // atom 만
+ *   listPatterns({ tag: "input" })         // x-tags 에 "input" 포함된 것만
+ *   listPatterns({ tier: "molecule", tag: "filter" })
+ *
+ * 응답 shape:
+ *   {
+ *     total, returned,
+ *     byTier: { atom: N, molecule: N, organism: N },
+ *     filter: { tier, tag },
+ *     patterns: [ { tier, name, title, description, tags, related, propsSummary }, ... ]
+ *   }
+ *
+ * 정렬: tier 순(atom→molecule→organism) → name 알파벳.
+ */
+export function listPatterns({ tier, tag } = {}) {
+  const tiers = tier ? [tier] : PATTERN_TIERS;
+  const all = [];
+  for (const t of tiers) all.push(...scanTier(t));
+
+  // tag 필터.
+  const filtered = tag
+    ? all.filter((p) => Array.isArray(p.tags) && p.tags.includes(tag))
+    : all;
+
+  // 정렬: tier 순서 우선, 그 안에서 name 알파벳.
+  const tierOrder = new Map(PATTERN_TIERS.map((t, i) => [t, i]));
+  filtered.sort((a, b) => {
+    const ta = tierOrder.get(a.tier) ?? 99;
+    const tb = tierOrder.get(b.tier) ?? 99;
+    if (ta !== tb) return ta - tb;
+    return a.name.localeCompare(b.name);
+  });
+
+  const byTier = { atom: 0, molecule: 0, organism: 0 };
+  for (const p of filtered) {
+    if (byTier[p.tier] != null) byTier[p.tier] += 1;
+  }
+
+  return {
+    total: filtered.length,
+    returned: filtered.length,
+    byTier,
+    filter: { tier: tier ?? null, tag: tag ?? null },
+    patterns: filtered,
+  };
+}
+
+/* ----- schema/v1/*.md docs ----- */
+function collectMd(dir, base, out = []) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) collectMd(full, base, out);
+    else if (entry.endsWith(".md"))
+      out.push(relative(base, full).split("\\").join("/"));
+  }
+  return out;
+}
+export function listSchemaDocs() {
+  return collectMd(SCHEMA_ROOT, SCHEMA_ROOT).sort();
+}
+export function getSchemaDoc(name) {
+  return readText(safeJoin(SCHEMA_ROOT, name));
+}
+
+/* ----- examples (재귀 수집, 카테고리 폴더 지원) ----- */
+function collectJson(dir, base, out = []) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) collectJson(full, base, out);
+    else if (entry.endsWith(".json"))
+      out.push(relative(base, full).split("\\").join("/"));
+  }
+  return out;
+}
+
+export function listExamples() {
+  return collectJson(EXAMPLES_ROOT, EXAMPLES_ROOT).sort();
+}
+
+/**
+ * @param {string} name examples 기준 상대 경로 (예: "basic/basic-list-detail.json")
+ *                       — 파일명만 (예: "basic-list-detail.json") 도 허용 시 모호하므로 상대경로 권장.
+ */
+export function getExample(name) {
+  return readJson(safeJoin(EXAMPLES_ROOT, name));
+}
+
+/** examples 카테고리 (1-depth 폴더명) 반환. 루트 직속 .json 은 'root' 로 분류. */
+export function listExampleCategories() {
+  const cats = new Set();
+  for (const entry of readdirSync(EXAMPLES_ROOT)) {
+    const full = join(EXAMPLES_ROOT, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) cats.add(entry);
+    else if (entry.endsWith(".json")) cats.add("root");
+  }
+  return [...cats].sort();
+}
+
+/* ----- 메타 정보 ----- */
+export function getContractInfo() {
+  const cat = getCatalog();
+  return {
+    contractRoot: CONTRACT_ROOT,
+    version: cat.version ?? "v1",
+    docs: listSchemaDocs(),
+    examples: listExamples(),
+    exampleCategories: listExampleCategories(),
+    catalogSections: Object.keys(cat).filter((k) => !k.startsWith("$")),
+    designSystem: {
+      readme: "schema/v1/design-system/README.md",
+      patterns: "schema/v1/patterns/",
+      tools: ["get_design_rules", "list_patterns"],
+    },
+  };
+}

package/node_modules/@flextudio/contract-core/index.mjs

@@ -0,0 +1,16 @@
+// @flextudio/contract-core — meta-contract 의 단일 진실 원본 진입점.
+// CLI(cli/bin/flex-scenario.mjs) · 루트 validate.mjs · bench/sanity-check.sh 가
+// 모두 동일한 함수/스키마/검증 로직을 import 한다 (단일 진실원본).
+//
+// 이 모듈은 ajv 만 사용 — 외부 의존 최소.
+//
+// re-export 카테고리:
+//   - paths:     contract root / schema / patterns / examples 경로 상수
+//   - schemas:   ajv 인스턴스 구축 + ref 해석 + fragment 추출
+//   - validators: scenario cross-check 11종 + group defaults / mock sector 헬퍼
+//   - contract:  catalog/rules/examples/patterns 로더 + getContractInfo
+
+export * from "./paths.mjs";
+export * from "./schemas.mjs";
+export * from "./validators.mjs";
+export * from "./contract.mjs";

package/node_modules/@flextudio/contract-core/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@flextudio/contract-core",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Flextudio meta-contract core: schema/validator/contract single source of truth (zero MCP dependency).",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./paths": "./paths.mjs",
+    "./schemas": "./schemas.mjs",
+    "./validators": "./validators.mjs",
+    "./contract": "./contract.mjs"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  }
+}

package/node_modules/@flextudio/contract-core/paths.mjs

@@ -0,0 +1,72 @@
+// meta-contract 의 단일 진실 원본 (schema/ + spec/{rules.md,catalog.json} + examples/ ...)
+// 위치를 해석한다. CLI · 루트 validate.mjs · build-skill-payload 어디서든 동일 동작.
+//
+// 해석 우선순위:
+//   1. process.env.FLEX_CONTRACT_ROOT — 명시적 오버라이드 (배포/테스트용)
+//   2. core 패키지 위치에서 부모로 상승하면서 schema/ + spec/rules.md 가 모두 있는 첫 디렉토리
+//   3. 폴백: 패키지 기준 한 단계 위 (개발 모노레포 = meta-contract/)
+//
+// 폴백까지 도달했는데도 schema/ 가 없으면 throw — 잘못된 환경에서 침묵하지 않는다.
+
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function isContractRoot(dir) {
+  try {
+    const schemaDir = join(dir, "schema");
+    // 마커: schema/ + spec/rules.md (rules.md·catalog.json 는 spec/ 로 이동됨).
+    const rulesPath = join(dir, "spec", "rules.md");
+    return (
+      existsSync(schemaDir) &&
+      statSync(schemaDir).isDirectory() &&
+      existsSync(rulesPath)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function findContractRoot() {
+  const envRoot = process.env.FLEX_CONTRACT_ROOT;
+  if (envRoot && envRoot.trim()) {
+    const abs = isAbsolute(envRoot) ? envRoot : resolve(process.cwd(), envRoot);
+    if (!isContractRoot(abs)) {
+      throw new Error(
+        `[contract-core] FLEX_CONTRACT_ROOT='${abs}' 에 schema/ + spec/rules.md 가 없음`,
+      );
+    }
+    return abs;
+  }
+
+  let cur = __dirname;
+  while (true) {
+    if (isContractRoot(cur)) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+
+  // 마지막 폴백: 패키지 한 단계 위 (예: meta-contract/core → meta-contract).
+  // 여기에도 없으면 환경이 잘못된 것이므로 명시적으로 throw.
+  const fallback = resolve(__dirname, "..");
+  if (isContractRoot(fallback)) return fallback;
+  throw new Error(
+    `[contract-core] contract root 를 찾지 못함 — FLEX_CONTRACT_ROOT 환경변수로 schema/ + spec/rules.md 가 있는 디렉토리를 지정`,
+  );
+}
+
+export const CONTRACT_ROOT = findContractRoot();
+
+export const SCHEMA_ROOT = resolve(CONTRACT_ROOT, "schema/v1");
+export const PATTERNS_ROOT = resolve(SCHEMA_ROOT, "patterns");
+export const EXAMPLES_ROOT = resolve(CONTRACT_ROOT, "examples");
+export const CATALOG_PATH = resolve(CONTRACT_ROOT, "spec", "catalog.json");
+export const RULES_PATH = resolve(CONTRACT_ROOT, "spec", "rules.md");
+export const README_PATH = resolve(CONTRACT_ROOT, "README.md");
+export const DESIGN_SYSTEM_DIR = resolve(SCHEMA_ROOT, "design-system");
+export const DESIGN_SYSTEM_PATH = resolve(DESIGN_SYSTEM_DIR, "README.md");
+export const DESIGN_RULES_PATH = resolve(DESIGN_SYSTEM_DIR, "DESIGN.md");
+export const SKELETON_SHELL_PATH = resolve(SCHEMA_ROOT, "SKELETON-SHELL.md");