kasaframe 0.1.4 → 0.1.6

package/packages/cli/src/sfx.ts

@@ -0,0 +1,429 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SFX_ROLES, type SfxRole } from "@kasaframe/core";
+import { loadTheme } from "@kasaframe/themes";
+
+// 효과음 — 장면 움직임이 남긴 소리 자리(__kf.events 의 sfx)를 뜻 있는 것만 적게 고르고, 테마가 고른 결의 파일을 곡 둘레 크기에 맞춰 깔고
+// 그 순간 곡을 짧게 눌러 자리를 낸다. 같은 자리·같은 설정이면 같은 소리 — 고르기·음높이 흔들기는 시각과 역할의 해시로만 정한다
+
+const SR = 48000;
+
+export interface SfxSettings {
+  /** 소리 결 — sfx/tags.json 의 sets */
+  set: string;
+  /** 둘레 곡(소리 자리 앞뒤 0.2초) 크기 대비 dB — 0 이면 곡과 비슷하게 */
+  db: number;
+  /** 1초에 몇 개까지(2초 창으로 센다 — 0.5 면 2초에 하나) */
+  perSec: number;
+  only: SfxRole[] | null;
+  /** 목소리가 있으면 더 낮춘다 */
+  voiceDb: number;
+  /** 잔소리(낱낱이 나타남·숫자 째깍·타자)도 깐다 — 기본은 뜻 있는 자리만 */
+  chatter: boolean;
+  /** 소리마다 곡을 이만큼(dB) 짧게 눌러 자리를 낸다 */
+  duck: number;
+}
+
+const DEFAULT: SfxSettings = { set: "ui", db: -2, perSec: 1, only: null, voiceDb: -4, chatter: false, duck: 3 };
+
+// 역할마다 결 크기 위아래(db)·밀도가 넘칠 때 남기는 차례(prio 높은 것부터)·저역을 걷는 곳(Hz — 킥·베이스와 안 겹치게, 드롭 쿵만 낮게 둔다)
+export const ROLE: Record<SfxRole, { db: number; prio: number; cut: number }> = {
+  drop: { db: 2, prio: 10, cut: 60 },
+  end: { db: 1, prio: 9, cut: 250 },
+  whoosh: { db: -1, prio: 8, cut: 250 },
+  land: { db: 0, prio: 7, cut: 150 },
+  stick: { db: 0, prio: 6, cut: 200 },
+  burst: { db: 0, prio: 6, cut: 250 },
+  hop: { db: -1, prio: 5, cut: 200 },
+  select: { db: -1, prio: 4, cut: 250 },
+  appear: { db: -2, prio: 3, cut: 250 },
+  tick: { db: -4, prio: 2, cut: 300 },
+  type: { db: -4, prio: 1, cut: 300 },
+};
+
+/** 같은 역할은 이 안에 하나 */
+const SAME_ROLE = 0.1;
+/** 아무 소리끼리 이만큼 띄운다 — 붙어 나면 하나로 뭉개진다 */
+const MIN_GAP = 0.25;
+/** 드롭 앞뒤 이 안은 드롭만 */
+const DROP_CLEAR = 0.35;
+/** 밀도를 세는 창(초) */
+const WINDOW = 2;
+/** 가려짐 목표 — 소리 대역에서 소리 순간에 효과음이 곡보다 이만큼(dB) 위. 모자라면 BOOST 까지 더 키운다 */
+const SMR_TARGET = 4;
+const BOOST = 6;
+/**
+ * 소리가 차지하는 대역 후보(Hz) — 소리마다 제 가장 센 대역에서 10dB 안쪽인 대역들(그 소리가 실제로 차지하는 곳)을 잡고, 그중 곡을 가장 넘는 대역에서
+ * 가려짐을 잰다(귀는 소리가 곡을 넘는 대역에서 그 소리를 듣는다). 낮은 몸에 2–6kHz 어택을 얹은 소리는 어택 대역이 잡힌다
+ */
+export const BANDS: readonly [number, number][] = [
+  [40, 150],
+  [150, 600],
+  [600, 2000],
+  [2000, 6000],
+  [6000, 12000],
+];
+
+export const sfxDir = (): string => process.env.KF_SFX_DIR || fileURLToPath(new URL("../../../sfx/", import.meta.url));
+
+interface BankFile {
+  path: string;
+  lead: number;
+  level: number;
+}
+
+export interface SfxBank {
+  dir: string;
+  sets: string[];
+  file(set: string, role: SfxRole): BankFile | null;
+}
+
+export function loadBank(dir = sfxDir()): SfxBank {
+  const tags = JSON.parse(readFileSync(join(dir, "tags.json"), "utf8")) as { sets: Record<string, unknown>; files: Record<string, { set: string; role: string; lead: number; level: number }> };
+  const by = new Map(Object.entries(tags.files).map(([rel, f]) => [`${f.set}/${f.role}`, { path: join(dir, rel), lead: f.lead, level: f.level }]));
+  return { dir, sets: Object.keys(tags.sets), file: (set, role) => by.get(`${set}/${role}`) ?? null };
+}
+
+const isRole = (r: unknown): r is SfxRole => (SFX_ROLES as readonly unknown[]).includes(r);
+
+/**
+ * 이 프로젝트의 효과음 설정 — 기본 ← theme.json sfx ← kf.json sfx. 끄면 null.
+ * flag 는 kf render|make --sfx: off 면 끈다, on 이면 kf.json sfx: false 도 이 판만 켠다
+ */
+export function sfxSettings(dir: string, flag?: string): SfxSettings | null {
+  if (flag === "off") return null;
+  type Loose = Partial<Omit<SfxSettings, "only">> & { only?: string[] | null };
+  const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) as { theme?: string; sfx?: false | Loose };
+  if (kf.sfx === false && flag !== "on") return null;
+  let theme: Loose = {};
+  if (kf.theme) {
+    try {
+      theme = loadTheme(kf.theme).sfx ?? {};
+    } catch {}
+  }
+  const over = kf.sfx && typeof kf.sfx === "object" ? kf.sfx : {};
+  const s: Loose & Omit<SfxSettings, "only"> = { ...DEFAULT, ...theme, ...over };
+  const only = s.only ? s.only.filter(isRole) : null;
+  return {
+    set: s.set,
+    db: Number(s.db),
+    perSec: Math.max(0.1, Number(s.perSec)),
+    only: only?.length ? only : null,
+    voiceDb: Number(s.voiceDb),
+    chatter: !!s.chatter,
+    duck: Math.max(0, Number(s.duck)),
+  };
+}
+
+export interface SfxCue {
+  t: number;
+  role: SfxRole;
+  source: string;
+  weight: number;
+  /** 잔소리 — chatter 가 아니면 안 깐다 */
+  minor?: boolean;
+}
+
+/** 페이지가 남긴 기록에서 소리 자리를, 곡의 드롭(beats.json — 영상 0초 기준)은 드롭 쿵으로 */
+export function cuesOf(events: readonly { t: number; kind: string; source: string; name?: string; value?: number; minor?: boolean }[], drops: readonly number[] = []): SfxCue[] {
+  const out: SfxCue[] = [];
+  for (const e of events)
+    if (e.kind === "sfx" && isRole(e.name)) out.push({ t: e.t, role: e.name, source: e.source, weight: Math.min(1, Math.max(0.05, e.value ?? 1)), ...(e.minor ? { minor: true } : {}) });
+  for (const d of drops) out.push({ t: Math.round(d * 1000) / 1000, role: "drop", source: "beats", weight: 1 });
+  return out;
+}
+
+export function projectDrops(dir: string): number[] {
+  try {
+    const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) as { beats?: string };
+    if (!kf.beats) return [];
+    return (JSON.parse(readFileSync(resolve(dir, kf.beats), "utf8")) as { drops?: number[] }).drops ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export interface SfxHit {
+  t: number;
+  role: SfxRole;
+  /** 결 안 역할 파일 — 섞을 때 bank 에서 찾는다 */
+  set: string;
+  /** 역할 크기 + 무게 + 흔들기(dB) */
+  db: number;
+  /** 음높이 배수 — 같은 소리가 줄줄이 나도 기계음처럼 안 들리게 */
+  rate: number;
+}
+
+// 시각·역할 → 0..1 두 개(fnv1a). 같은 자리면 어느 기계에서나 같은 흔들기
+function hash2(key: string): [number, number] {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < key.length; i++) h = Math.imul(h ^ key.charCodeAt(i), 0x01000193) >>> 0;
+  const a = (h & 0xffff) / 0x10000;
+  const b = (h >>> 16) / 0x10000;
+  return [a, b];
+}
+
+/**
+ * 소리 자리를 깔 소리로 — 잔소리(chatter 가 아니면)·결에 없는 역할·only 밖 역할은 빼고, 같은 역할은 SAME_ROLE 안에 하나, 차례(ROLE.prio)대로
+ * 드롭 앞뒤를 비우고 MIN_GAP 을 띄우고 아무 2초 창에 perSec×2 개(적어도 하나)까지 남긴다. 결과는 시각 차례
+ */
+export function placeSfx(cues: readonly SfxCue[], s: SfxSettings, bank: Pick<SfxBank, "file">, o: { from: number; to: number }): SfxHit[] {
+  const ok = cues
+    .filter((c) => c.t >= o.from - 1e-9 && c.t < o.to - 1e-9 && (s.chatter || !c.minor) && (!s.only || s.only.includes(c.role)) && bank.file(s.set, c.role))
+    .sort((a, b) => a.t - b.t || ROLE[b.role].prio - ROLE[a.role].prio || (a.source < b.source ? -1 : a.source > b.source ? 1 : 0));
+  const merged: SfxCue[] = [];
+  const last = new Map<SfxRole, SfxCue>();
+  for (const c of ok) {
+    const prev = last.get(c.role);
+    if (prev && c.t - prev.t < SAME_ROLE) {
+      prev.weight = Math.max(prev.weight, c.weight);
+      continue;
+    }
+    const m = { ...c };
+    merged.push(m);
+    last.set(c.role, m);
+  }
+  const order = [...merged].sort((a, b) => ROLE[b.role].prio - ROLE[a.role].prio || a.t - b.t);
+  const kept: SfxCue[] = [];
+  const most = Math.max(1, Math.round(s.perSec * WINDOW));
+  // t 를 품은 어느 창 [w, w+WINDOW) 이 most 를 넘나 — 가장 붐비는 창은 t 앞 WINDOW 안의 소리(t 포함)에서 시작한다
+  const crowded = (t: number) => {
+    const xs = [...kept.map((k) => k.t), t];
+    return xs.filter((w) => w <= t && w > t - WINDOW).some((w) => xs.filter((x) => x >= w && x < w + WINDOW).length > most);
+  };
+  for (const c of order) {
+    if (kept.some((k) => Math.abs(k.t - c.t) < MIN_GAP)) continue;
+    if (c.role !== "drop" && kept.some((k) => k.role === "drop" && Math.abs(k.t - c.t) < DROP_CLEAR)) continue;
+    if (crowded(c.t)) continue;
+    kept.push(c);
+  }
+  return kept
+    .sort((a, b) => a.t - b.t)
+    .map((c) => {
+      const [h1, h2] = hash2(`${c.role}|${c.t.toFixed(3)}`);
+      return { t: c.t, role: c.role, set: s.set, db: Math.round((ROLE[c.role].db + 20 * Math.log10(c.weight) + (h1 - 0.5) * 2) * 100) / 100, rate: Math.round((1 + (h2 - 0.5) * 0.06) * 10000) / 10000 };
+    });
+}
+
+// --- 소리 다루기: 2차 버터워스 거르개(RBJ) — 같은 입력이면 같은 출력
+
+type Biquad = [number, number, number, number, number];
+
+function biquad(kind: "lp" | "hp", f: number): Biquad {
+  const w = (2 * Math.PI * f) / SR;
+  const c = Math.cos(w);
+  const a = Math.sin(w) / Math.SQRT2;
+  const b0 = kind === "lp" ? (1 - c) / 2 : (1 + c) / 2;
+  const b1 = kind === "lp" ? 1 - c : -(1 + c);
+  const a0 = 1 + a;
+  return [b0 / a0, b1 / a0, b0 / a0, (-2 * c) / a0, (1 - a) / a0];
+}
+
+function filter(x: Float32Array, q: Biquad): Float32Array {
+  const [b0, b1, b2, a1, a2] = q;
+  const y = new Float32Array(x.length);
+  let x1 = 0;
+  let x2 = 0;
+  let y1 = 0;
+  let y2 = 0;
+  for (let i = 0; i < x.length; i++) {
+    const v = b0 * x[i] + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
+    x2 = x1;
+    x1 = x[i];
+    y2 = y1;
+    y1 = v;
+    y[i] = v;
+  }
+  return y;
+}
+
+/** 대역 [lo, hi] 만 — 높은·낮은 거르개를 두 번씩(4차) */
+function band(x: Float32Array, [lo, hi]: readonly [number, number]): Float32Array {
+  const h = biquad("hp", lo);
+  const l = biquad("lp", Math.min(hi, SR * 0.45));
+  return filter(filter(filter(filter(x, h), h), l), l);
+}
+
+// [a, b) 창 평균 에너지 — 창이 소리 끝·앞을 넘으면 넘은 자리는 0 으로 친다(잘린 길이로 나누면 짧은 소리가 5dB 넘게 부풀었다)
+const energy = (x: Float32Array, a: number, b: number): number => {
+  let e = 0;
+  for (let i = Math.max(0, a); i < Math.min(x.length, b); i++) e += x[i] * x[i];
+  return b > a ? e / (b - a) : 0;
+};
+const db = (e: number): number => 10 * Math.log10(e + 1e-15);
+
+// 100ms 창 RMS 최댓값(dBFS) — tools/sfx/build.ts 의 level 과 같은 잣대
+function peak100(y: Float32Array): number {
+  const win = Math.round(SR * 0.1);
+  let best = 0;
+  for (let i = 0; i < Math.max(1, y.length - win + 1); i += Math.round(SR * 0.01)) best = Math.max(best, energy(y, i, i + win));
+  return db(best);
+}
+
+// sfx/ 의 16비트 모노 wav — tools/sfx/build.ts 가 쓴 꼴만
+const raw = new Map<string, Float32Array>();
+function samples(path: string): Float32Array {
+  const hit = raw.get(path);
+  if (hit) return hit;
+  const b = readFileSync(path);
+  let p = 12;
+  let data: Buffer | null = null;
+  let bits = 16;
+  let channels = 1;
+  while (p + 8 <= b.length) {
+    const id = b.toString("ascii", p, p + 4);
+    const size = b.readUInt32LE(p + 4);
+    if (id === "fmt ") {
+      channels = b.readUInt16LE(p + 10);
+      bits = b.readUInt16LE(p + 22);
+    } else if (id === "data") data = b.subarray(p + 8, p + 8 + size);
+    p += 8 + size + (size & 1);
+  }
+  if (!data || bits !== 16 || channels !== 1) throw new Error(`효과음 파일 꼴이 아니다(16비트 모노 wav): ${path}`);
+  const y = new Float32Array(data.length / 2);
+  for (let i = 0; i < y.length; i++) y[i] = data.readInt16LE(i * 2) / 32768;
+  raw.set(path, y);
+  return y;
+}
+
+interface Voiced {
+  y: Float32Array;
+  /** 파일 시작 → 꼭대기(샘플) */
+  lead: number;
+  level: number;
+  /** 소리가 차지하는 대역들과 그 대역으로 거른 소리 */
+  bands: { band: readonly [number, number]; y: Float32Array }[];
+}
+
+// 음높이를 옮기고(선형 보간) 저역을 걷은 소리 — 크기·대역은 걷은 뒤에 잰다
+const voiced = new Map<string, Voiced>();
+function voice(f: BankFile, rate: number, cut: number): Voiced {
+  const key = `${f.path}|${rate}|${cut}`;
+  const hit = voiced.get(key);
+  if (hit) return hit;
+  const src = samples(f.path);
+  const len = Math.floor((src.length - 1) / rate);
+  const moved = new Float32Array(len);
+  for (let i = 0; i < len; i++) {
+    const x = i * rate;
+    const k = Math.floor(x);
+    moved[i] = src[k] + (src[k + 1] - src[k]) * (x - k);
+  }
+  const hp = biquad("hp", cut);
+  const y = filter(filter(moved, hp), hp);
+  const split = BANDS.map((b) => ({ band: b, y: band(y, b) }));
+  const loud = split.map((x) => db(energy(x.y, 0, x.y.length)));
+  const top = Math.max(...loud);
+  const v = { y, lead: Math.round((f.lead / rate) * SR), level: peak100(y), bands: split.filter((_, i) => loud[i] >= top - 10) };
+  voiced.set(key, v);
+  return v;
+}
+
+export interface SfxPlaced extends SfxHit {
+  /** 둘레 곡 크기(앞뒤 0.2초 RMS, dBFS) */
+  local: number;
+  /** 소리 크기(100ms 창, dBFS) − 둘레 곡 */
+  over: number;
+  /** 가려짐을 잰 대역(Hz) */
+  band: readonly [number, number];
+  /** 그 대역에서 소리 순간(꼭대기 앞 10ms·뒤 90ms) 효과음 ÷ 눌린 곡(dB) */
+  smr: number;
+  /** 가려져서 더 키운 dB */
+  boost: number;
+}
+
+/**
+ * 곡(·목소리)을 섞은 판 bed(스테레오, 영상 from 초가 0)에 효과음을 깐다 — 소리마다
+ * ① 크기: 둘레 곡 크기 + s.db + 역할 크기(목소리가 있으면 voiceDb 더) ② 그 순간 곡을 s.duck dB 짧게(소리 시작 10ms 앞부터 꼭대기 100ms 뒤까지) 눌러 자리를 내고
+ * ③ 소리 대역에서 효과음이 눌린 곡보다 SMR_TARGET 위가 안 되면 BOOST 까지 더 키운다. bed 를 바꿔 쓰고, 깐 소리와 잰 값을 돌려준다
+ */
+export function laySfx(bed: [Float32Array, Float32Array], hits: readonly SfxHit[], bank: Pick<SfxBank, "file">, s: SfxSettings, o: { from: number; voice: boolean }): { stem: Float32Array; placed: SfxPlaced[] } {
+  const [L, R] = bed;
+  const n = L.length;
+  const mono = new Float32Array(n);
+  for (let i = 0; i < n; i++) mono[i] = (L[i] + R[i]) / 2;
+  // 곡이 비었거나 아주 조용한 곳은 판 전체(무음 뺀 400ms 창 평균)에서 12dB 아래를 바닥으로
+  const blocks: number[] = [];
+  for (let i = 0; i + 0.4 * SR <= n; i += 0.1 * SR) {
+    const e = energy(mono, i, i + 0.4 * SR);
+    if (e > 1e-7) blocks.push(e);
+  }
+  const floor = blocks.length ? db(blocks.reduce((x, y) => x + y, 0) / blocks.length) - 12 : -32;
+  const at = (t: number) => Math.round((t - o.from) * SR);
+  const items = hits.flatMap((h) => {
+    const f = bank.file(h.set, h.role);
+    if (!f) return [];
+    const v = voice(f, h.rate, ROLE[h.role].cut);
+    const peak = at(h.t);
+    return [{ h, v, peak, start: peak - v.lead, local: Math.max(floor, db(energy(mono, peak - 0.2 * SR, peak + 0.2 * SR))) }];
+  });
+  // 누르기 — 소리마다 작은 골짜기, 겹치면 깊은 쪽
+  const env = new Float32Array(n).fill(1);
+  const dip = 10 ** (-s.duck / 20);
+  const rampIn = Math.round(0.01 * SR);
+  const rampOut = Math.round(0.04 * SR);
+  for (const it of items) {
+    const a = it.start - rampIn;
+    const b = it.peak + Math.round(0.1 * SR);
+    for (let i = Math.max(0, a - rampIn); i < Math.min(n, b + rampOut); i++) {
+      const k = i < a ? (i - (a - rampIn)) / rampIn : i > b ? 1 - (i - b) / rampOut : 1;
+      env[i] = Math.min(env[i], 1 - (1 - dip) * Math.max(0, Math.min(1, k)));
+    }
+  }
+  const ducked = new Float32Array(n);
+  for (let i = 0; i < n; i++) ducked[i] = mono[i] * env[i];
+  const stem = new Float32Array(n);
+  const placed: SfxPlaced[] = [];
+  const pre = Math.round(0.2 * SR);
+  for (const it of items) {
+    const { h, v } = it;
+    const target = it.local + s.db + h.db + (o.voice ? s.voiceDb : 0);
+    let gain = target - v.level;
+    // 가려짐 — 소리 꼭대기 앞 10ms·뒤 90ms 를 그 소리 대역마다. 곡 쪽은 거르개가 자리 잡게 앞 0.2초부터 걸러 뒤만 잰다
+    const a = it.peak - Math.round(0.01 * SR);
+    const b = it.peak + Math.round(0.09 * SR);
+    const ref = ducked.subarray(Math.max(0, a - pre), Math.min(n, b));
+    const per = v.bands.map((x) => ({
+      band: x.band,
+      smr: db(energy(x.y, v.lead - Math.round(0.01 * SR), v.lead + Math.round(0.09 * SR)) * 10 ** (gain / 10)) - db(energy(band(ref, x.band), a - Math.max(0, a - pre), ref.length)),
+    }));
+    const best = per.reduce((p, q) => (q.smr > p.smr ? q : p));
+    const smr0 = best.smr;
+    const boost = Math.min(BOOST, Math.max(0, SMR_TARGET - smr0));
+    gain += boost;
+    const k = 10 ** (gain / 20);
+    for (let i = Math.max(0, -it.start); i < v.y.length && it.start + i < n; i++) stem[it.start + i] += k * v.y[i];
+    const r = (x: number) => Math.round(x * 10) / 10;
+    placed.push({ ...h, local: r(it.local), over: r(v.level + gain - it.local), band: best.band, smr: r(smr0 + boost), boost: r(boost) });
+  }
+  for (let i = 0; i < n; i++) {
+    L[i] = L[i] * env[i] + stem[i];
+    R[i] = R[i] * env[i] + stem[i];
+  }
+  return { stem, placed };
+}
+
+/** 32비트 실수 wav — 채널을 받은 차례로 엇갈려 쓴다 */
+export function writeFloatWav(path: string, channels: Float32Array[]): string {
+  const c = channels.length;
+  const n = channels[0].length;
+  const body = new Float32Array(n * c);
+  for (let i = 0; i < n; i++) for (let k = 0; k < c; k++) body[i * c + k] = channels[k][i];
+  const data = Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+  const head = Buffer.alloc(44);
+  head.write("RIFF", 0);
+  head.writeUInt32LE(36 + data.length, 4);
+  head.write("WAVEfmt ", 8);
+  head.writeUInt32LE(16, 16);
+  head.writeUInt16LE(3, 20);
+  head.writeUInt16LE(c, 22);
+  head.writeUInt32LE(SR, 24);
+  head.writeUInt32LE(SR * 4 * c, 28);
+  head.writeUInt16LE(4 * c, 32);
+  head.writeUInt16LE(32, 34);
+  head.write("data", 36);
+  head.writeUInt32LE(data.length, 40);
+  writeFileSync(path, Buffer.concat([head, data]));
+  return path;
+}

package/packages/cli/src/update.ts

@@ -0,0 +1,250 @@
+// 새 판 알림 — Codex CLI 처럼 확인은 떨어진 자식이 뒤에서 하고 결과를 캐시에 둔다. kf 는 네트워크를 기다리지 않고 지난 확인 결과로 묻거나 알린다.
+// 여기는 모든 kf 명령 앞에서 불리니 무거운 것을 import 하지 않는다.
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE = "kasaframe";
+const root = fileURLToPath(new URL("../../../", import.meta.url));
+const versionAt = (dir: string): string => JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+export const current = versionAt(root);
+// 몇 시간에 한 번 — 하루에 몇 번 켜도 레지스트리는 한두 번만 본다
+export const CHECK_EVERY_MS = 6 * 3600_000;
+
+export interface UpdateCache {
+  latest?: string;
+  checkedAt?: string;
+  /** 「이 판은 다시 묻지 않기」로 넘긴 판 — 더 새 판이 나오면 다시 묻는다 */
+  dismissed?: string;
+}
+
+export const cacheFile = (): string => join(process.env.KF_CACHE_DIR ?? join(homedir(), ".cache", "kasaframe"), "update.json");
+
+export function readCache(): UpdateCache {
+  try {
+    return JSON.parse(readFileSync(cacheFile(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// kf 여럿이 한꺼번에 써도 반쯤 쓴 파일을 읽지 않게 다른 이름에 쓰고 옮긴다
+export function writeCache(c: UpdateCache): void {
+  const file = cacheFile();
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(c)}\n`);
+  renameSync(tmp, file);
+}
+
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** latest 가 now 보다 새 정식 판인가 — 미리보기 판(prerelease)은 권하지 않는다 */
+export function isNewer(latest: string, now: string): boolean {
+  const l = SEMVER.exec(latest.trim());
+  const c = SEMVER.exec(now.trim());
+  if (!l || !c || l[4]) return false;
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(l[i]) - Number(c[i]);
+    if (d) return d > 0;
+  }
+  return !!c[4];
+}
+
+export type Manager = "npm" | "pnpm" | "bun" | "yarn";
+export interface Install {
+  manager: Manager;
+  /** npm 전역 자리 — 기본 자리가 아니면 올릴 때도 거기에 깔아야 이 kf 가 바뀐다 */
+  prefix?: string;
+}
+
+/** 패키지가 놓인 자리로 어느 관리자의 전역 설치인가. 레포 체크아웃·npx 가 잠깐 받은 것·프로젝트 의존성은 null — 판은 그쪽이 정한다 */
+export function installOf(dir: string, win = process.platform === "win32"): Install | null {
+  const p = dir.replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!p.includes("/node_modules/")) return null;
+  if (p.includes("/_npx/")) return null;
+  if (p.includes("/.bun/install/global/")) return { manager: "bun" };
+  if (/\/pnpm\/global\//i.test(p)) return { manager: "pnpm" };
+  if (/\/yarn\/(data\/)?global\/node_modules\//i.test(p)) return { manager: "yarn" };
+  const npm = (win ? /^(.+)\/node_modules\/kasaframe$/ : /^(.+)\/lib\/node_modules\/kasaframe$/).exec(p);
+  return npm ? { manager: "npm", prefix: win ? npm[1].replace(/\//g, "\\") : npm[1] } : null;
+}
+
+export function updateCommand(inst: Install, version: string, npmDefaultPrefix?: string): string[] {
+  const spec = `${PACKAGE}@${version}`;
+  if (inst.manager === "pnpm") return ["pnpm", "add", "-g", spec];
+  if (inst.manager === "bun") return ["bun", "add", "-g", spec];
+  if (inst.manager === "yarn") return ["yarn", "global", "add", spec];
+  const custom = inst.prefix && npmDefaultPrefix !== undefined && !samePath(inst.prefix, npmDefaultPrefix);
+  return ["npm", "i", "-g", spec, ...(custom ? ["--prefix", inst.prefix!] : [])];
+}
+
+function samePath(a: string, b: string): boolean {
+  const real = (p: string) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(a) === real(b);
+}
+
+const shell = process.platform === "win32";
+
+function npmPrefix(): string | undefined {
+  const r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", shell, timeout: 10_000 });
+  return r.status === 0 ? r.stdout.trim() : undefined;
+}
+
+/** 이 kf 를 올리는 명령 — npm 이면 기본 전역 자리와 비교해야 해서 npm 을 한 번 부른다(묻거나 올릴 때만) */
+export function commandFor(version: string): string[] | null {
+  const inst = installOf(root);
+  return inst && updateCommand(inst, version, inst.manager === "npm" && inst.prefix ? npmPrefix() : undefined);
+}
+
+// 환경 변수 → npm 설정(사용자·전역·프로젝트 .npmrc) — 올리는 명령도 같은 npm 설정을 따른다
+export function registry(env: NodeJS.ProcessEnv = process.env): string {
+  const set = env.npm_config_registry ?? env.NPM_CONFIG_REGISTRY;
+  if (set) return set;
+  const r = spawnSync("npm", ["config", "get", "registry"], { encoding: "utf8", shell, timeout: 10_000 });
+  const got = r.status === 0 ? r.stdout.trim() : "";
+  return /^https?:\/\//.test(got) ? got : "https://registry.npmjs.org/";
+}
+
+export async function fetchLatest(timeoutMs: number): Promise<string> {
+  const url = `${registry().replace(/\/+$/, "")}/${PACKAGE}`;
+  const r = await fetch(url, {
+    headers: { accept: "application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8" },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!r.ok) throw new Error(`${url} → HTTP ${r.status}`);
+  const latest = ((await r.json()) as { "dist-tags"?: { latest?: unknown } })["dist-tags"]?.latest;
+  if (typeof latest !== "string") throw new Error(`${url} 에 dist-tags.latest 가 없다`);
+  return latest;
+}
+
+/** 레지스트리를 지금 보고 캐시에 적는다 — kf update·kf doctor 와 뒤에서 도는 자식이 쓴다 */
+export async function refresh(timeoutMs = 8000): Promise<string> {
+  const latest = await fetchLatest(timeoutMs);
+  writeCache({ ...readCache(), latest, checkedAt: new Date().toISOString() });
+  return latest;
+}
+
+const on = (v: string | undefined) => !!v && v !== "0" && v.toLowerCase() !== "false";
+
+export interface Decision {
+  show: "prompt" | "notice" | "none";
+  refresh: boolean;
+  latest?: string;
+}
+
+export function decide(i: { current: string; cache: UpdateCache; install: Install | null; tty: boolean; env: NodeJS.ProcessEnv; now: number }): Decision {
+  if (!i.install || on(i.env.KF_NO_UPDATE_CHECK) || on(i.env.CI)) return { show: "none", refresh: false };
+  // 시각이 없거나 미래(시계가 돌아갔다)면 지금 본다
+  const age = i.now - Date.parse(i.cache.checkedAt ?? "");
+  const refresh = !(age >= 0 && age < CHECK_EVERY_MS);
+  const latest = i.cache.latest;
+  if (!latest || !isNewer(latest, i.current) || i.cache.dismissed === latest) return { show: "none", refresh };
+  return { show: i.tty ? "prompt" : "notice", refresh, latest };
+}
+
+// 뜻이 고정된 한 줄 — 에이전트가 이 꼴을 보고 kf update --yes 를 돌린다(skills/kasaframe/SKILL.md)
+export const noticeLine = (latest: string, now = current): string => `[kasaframe] 새 판 ${latest} (지금 ${now}) — kf update`;
+
+// 확인이 안 돼도(캐시 자리를 못 쓰거나 오프라인) kf 명령은 그대로 돈다
+function refreshInBackground(): void {
+  try {
+    // 같이 뜬 kf 들이 저마다 확인을 띄우지 않게 시각부터 적는다 — 실패하면 다음 주기에 다시 본다
+    writeCache({ ...readCache(), checkedAt: new Date().toISOString() });
+    const code = `const m = await import(${JSON.stringify(import.meta.url)}); await m.refresh(15000).catch(() => {});`;
+    spawn(process.execPath, ["--input-type=module", "-e", code], { detached: true, stdio: "ignore", windowsHide: true })
+      .on("error", () => {})
+      .unref();
+  } catch {}
+}
+
+// 설치본 입구가 NODE_OPTIONS 에 넣은 형 지우기 훅 — 새 판으로 다시 띄울 땐 빼야 새 입구가 제 훅을 넣는다(pnpm 은 옛 판 자리를 지운다)
+const hooksArg = `--import=${new URL("../../../bin/hooks.mjs", import.meta.url).href}`;
+
+function install(cmd: string[]): { ok: boolean; why: string } {
+  const r = spawnSync(cmd[0], cmd.slice(1), { stdio: "inherit", shell });
+  if (r.error) return { ok: false, why: r.error.message };
+  return { ok: r.status === 0, why: r.signal ? `신호 ${r.signal}` : `종료 ${r.status}` };
+}
+
+/** 사람이 친 kf 입구(심볼릭 링크 그대로)가 이제 가리키는 판 */
+function versionBehind(entry: string): string | null {
+  try {
+    return versionAt(join(dirname(realpathSync(entry)), ".."));
+  } catch {
+    return null;
+  }
+}
+
+/** 올리고, 이 kf 입구가 실제로 새 판을 가리키는지까지 본다 */
+export function upgrade(cmd: string[], latest: string, entry = process.argv[1]): boolean {
+  process.stderr.write(`\n${cmd.join(" ")}\n`);
+  const r = install(cmd);
+  if (!r.ok) {
+    process.stderr.write(`\n올리지 못했다(${r.why}). 직접 올리려면: ${cmd.join(" ")}\n`);
+    return false;
+  }
+  const now = versionBehind(entry);
+  if (now !== latest) {
+    process.stderr.write(`\n설치는 끝났는데 이 kf(${entry})는 ${now ?? "?"} 그대로다 — 다른 자리에 깔렸다. 직접: ${cmd.join(" ")}\n`);
+    return false;
+  }
+  return true;
+}
+
+async function ask(latest: string, cmd: string[]): Promise<"update" | "skip" | "dismiss"> {
+  // 묻는 동안 표준 출력이 터미널임은 확인했다 — 표준 오류가 파일로 가 있어도 보이게 표준 출력에 묻는다
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  rl.on("SIGINT", () => {
+    rl.close();
+    process.exit(130);
+  });
+  try {
+    const a = (
+      await rl.question(
+        `\n새 판이 있다 · kasaframe ${current} → ${latest}\n  1) 지금 업데이트 (${cmd.join(" ")})\n  2) 건너뛰기\n  3) 이 판은 다시 묻지 않기\n번호(엔터 = 1): `,
+      )
+    ).trim();
+    return a === "" || a === "1" ? "update" : a === "3" ? "dismiss" : "skip";
+  } catch {
+    return "skip";
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * 명령 앞 관문. 터미널이면 보기 셋을 묻고, 아니면 표준 오류에 한 줄(표준 출력은 --json 을 읽는 도구가 있어 건드리지 않는다).
+ * 「지금 업데이트」가 되면 원래 명령을 새 판으로 다시 띄우고 그 종료 코드를, 아니면 null(지금 판으로 이어 간다)
+ */
+export async function updateGate(argv: string[]): Promise<number | null> {
+  const env = process.env;
+  const d = decide({ current, cache: readCache(), install: installOf(root), tty: !!(process.stdin.isTTY && process.stdout.isTTY), env, now: Date.now() });
+  // kf 가 띄우는 kf(make → render 따위)는 다시 묻거나 찍지 않는다
+  env.KF_NO_UPDATE_CHECK = "1";
+  if (d.refresh) refreshInBackground();
+  if (d.show === "notice") process.stderr.write(`${noticeLine(d.latest!)}\n`);
+  if (d.show !== "prompt") return null;
+
+  const cmd = commandFor(d.latest!)!;
+  const pick = await ask(d.latest!, cmd);
+  if (pick === "dismiss") writeCache({ ...readCache(), dismissed: d.latest });
+  if (pick !== "update") return null;
+  if (!upgrade(cmd, d.latest!)) {
+    process.stderr.write(`${current} 로 이어 간다\n\n`);
+    return null;
+  }
+  process.stderr.write(`\nkasaframe ${d.latest} 로 올렸다 — 이어서 kf ${argv.join(" ")}\n\n`);
+  const nodeOptions = (env.NODE_OPTIONS ?? "").split(" ").filter((t) => t && t !== hooksArg).join(" ");
+  const r = spawnSync(process.execPath, [process.argv[1], ...argv], { stdio: "inherit", env: { ...env, NODE_OPTIONS: nodeOptions } });
+  return r.status ?? (r.signal === "SIGINT" ? 130 : 1);
+}