kasaframe 0.1.4 → 0.1.5

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);
+}

package/packages/plan/src/asks.ts

@@ -153,7 +153,7 @@ function voicePart(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: s
   };
 }
 
-// 테마 — 시리즈가 정했거나 요청이 「리소 느낌」·「og-measure/night-amber」처럼 짚었으면 묻지 않는다(kf new 의 auto 가 그대로 짚은 판을 쓴다).
+// 테마 — 시리즈가 정했거나 요청이 「리소 느낌」·「og-measure/snow-blue」처럼 짚었으면 묻지 않는다(kf new 의 auto 가 그대로 짚은 판을 쓴다).
 // 보기는 「알아서」(= auto, 권장)와 요청·용도·분위기 낱말(사람이 준 한 마디·레퍼런스까지)에 맞는 approved 세계·변주 넷 — 수백 판을 다 늘어놓지 않는다.
 // 사람이 보기 밖으로 분위기 한 마디나 그림·주소를 주면 그걸로 넷을 다시 고른다(kf make --theme-mood·--theme-ref)
 export const THEME_PICKS = 4;

package/packages/plan/src/themes.ts

@@ -38,14 +38,20 @@ export function suggestThemes(request: string, purpose: Purpose, aspect?: Aspect
   const lookOn = hasLook(want) || !!look.ref;
   const pool = listThemes({ status: "approved", purpose, ...(aspect ? { aspect } : {}), variants: lookOn });
   const ask = new Set(requestWords(text));
+  const tagsOf = (t: Theme) => (t.tags?.use ?? []).map((u) => u.toLowerCase());
+  // 드물게 적힌 낱말일수록 그 세계를 짚는다 — 「소개」처럼 여러 세계가 적은 낱말보다 「OpenGateway」처럼 한 세계만 적은 낱말이 무겁다
+  const tagShare = (w: string) => pool.filter((t) => tagsOf(t).some((u) => u.includes(w))).length / Math.max(1, pool.length);
   const scored = pool.map((t) => {
     const hay = `${t.name} ${t.metaphor} ${t.guide} ${(t.tags?.use ?? []).join(" ")} ${(t.tags?.mood ?? []).join(" ")} ${t.variant?.desc ?? ""}`.toLowerCase();
     const hit = [...ask].filter((w) => hay.includes(w));
+    // 세계가 tags.use 에 일부러 적은 낱말은 본문에 우연히 나온 낱말보다 무겁다 — 공통 견본 브리프(「OpenGateway 소개」)의 낱말은 모든 세계 THEME.md 에 있어
+    // 본문 맞음만으로는 그 제품 전용 세계가 다른 세계와 동점이 된다
+    const tagged = hit.filter((w) => tagsOf(t).some((u) => u.includes(w)));
     const l = lookOn ? lookScore(t, want, look.ref) : { score: 0, why: [] };
     const used = use.filter((w) => (t.tags?.use ?? []).some((u) => u.includes(w)));
     const fit = use.length ? (0.9 * used.length) / use.length : 0;
     // 같은 점수면 세계 기본 판이 앞 — 바란 생김새가 없을 때 변주를 굳이 고르지 않게
-    return { t, score: hit.length + fit + l.score + (t.variant ? 0 : 0.3), hit, used, why: l.why, tie: tieKey(text, t.id) };
+    return { t, score: hit.length + tagged.reduce((s, w) => s + 0.5 * (1 - tagShare(w)), 0) + fit + l.score + (t.variant ? 0 : 0.3), hit, used, why: l.why, tie: tieKey(text, t.id) };
   });
   scored.sort((a, b) => b.score - a.score || a.tie - b.tie || a.t.id.localeCompare(b.t.id));
   const picked: typeof scored = [];
@@ -72,7 +78,7 @@ export function suggestThemes(request: string, purpose: Purpose, aspect?: Aspect
 // 사람이 짚은 것이라 review 까지 받는다(draft 는 빼고)
 export function themeFromRequest(request: string, purpose?: Purpose): ThemePick | null {
   const t = request.toLowerCase();
-  // 변주를 이름으로 짚었으면(「og-measure/night-amber 로」) 그 판
+  // 변주를 이름으로 짚었으면(「og-measure/snow-blue 로」) 그 판
   const full = /([a-z0-9-]+)\/([a-z0-9-]+)/.exec(t);
   if (full) {
     try {

package/packages/themes/kit/THEME-MAKE.md

@@ -23,9 +23,9 @@
 ## 3. 비유·스타일 — `THEME.md` 앞부분 · `style.json` · `theme.json`
 
 - 비유 한 줄: 「무엇이 무엇처럼 되며 화면이 찍힌다/드러난다」. 내용(정보가 화면에 오르는 방식)에서 나온 개념이어야 한다 — 장식 이름이 아니라 동사가 있는 문장.
-- `style.json`: 프리셋과 같은 KfStyle 꼴 통째, `name` = `{{id}}`. 잉크 2–3색 + 그 어두운 단(`colors`), 바탕 `bg`, 글 `ink`, 강조 `accent`. 글꼴 셋(`sans`·`display`·`mono`)은 **한글이 서는 글꼴로 끝나게**(Pretendard 를 마지막에), `faces` 는 **한 파일 주소**(jsdelivr `gh/google/fonts@main/ofl/<이름>/<파일>.ttf` 나 `npm/pretendard@1.3.9/.../PretendardVariable.woff2`). 구글 폰트 CSS(unicode-range 조각)는 글이 투명하게 찍히니 쓰지 않는다. `theme` 칸에 `inks`·`texture`·`movement` 를 글로.
+- `style.json`: 프리셋과 같은 KfStyle 꼴 통째, `name` = `{{id}}`. 잉크 2–3색 + 그 어두운 단(`colors`), 바탕 `bg`, 글 `ink`, 강조 `accent`. 글꼴 셋(`sans`·`display`·`mono`)은 **한글이 서는 글꼴로 끝나게**(Pretendard 를 마지막에), `faces` 는 **판을 박은 한 파일 주소**(jsdelivr `gh/google/fonts@<커밋 40자>/ofl/<이름>/<파일>.ttf` 나 `npm/pretendard@1.3.9/.../PretendardVariable.woff2` — `@main`·`@latest`·`@5` 처럼 바뀌는 판은 같은 영상이 다르게 구워진다). 구글 폰트 CSS(unicode-range 조각)는 글이 투명하게 찍히니 쓰지 않는다. 글꼴은 상업·영상·웹 임베딩이 허용된 OFL·Apache 만, 한 굵기뿐인 글꼴을 더 굵게 부르면 가짜 굵기가 된다 — 짝 목록에 있는 글꼴이면 `kf fonts list`·`kf fonts sheet` 에서 고르는 게 가장 빠르다. `theme` 칸에 `inks`·`texture`·`movement` 를 글로.
 - `theme.json`: `name`·`metaphor`·`purposes`·`aspect`. status 는 draft 그대로.
-- `theme.json` 의 `vary`·`tags`(SPEC 9 「변주」): 이 세계가 approved 되면 `kf theme vary {{id}}` 가 겉모습만 바꾼 판 15개를 뽑는다. 비유를 깨지 않는 축과 범위만 적는다 — 밝기(`scheme`), 강조 색상 범위(`hue`, OKLCH 도), 글꼴 짝(`fonts` — `packages/themes/kit/fonts.json` 의 id·`tag:<태그>`·`base`), 질감(`texture`), 선 굵기(`stroke` — 슬롯 `trace` 가 `slotkit.traceCanvas` 를 쓰면 실린다), 모서리(`radius`), 빠르기(`tempo`), 밀도(`density` — 효과가 `ctx.style.look?.density` 를 읽을 때만). 금지에 적은 것과 부딪히는 축은 빼고(「밝은 바탕 금지」면 `scheme: ["dark"]`), 재료처럼 색상이 뜻인 색 열쇠는 `fixedHue`, 늘 같은 색은 `keep`. `tags` 는 `{ mood, light, use, dims }`. 효과·슬롯 색은 `var(--kf-*)`·`ctx.style.colors` 로 읽어야 변주 색이 실린다 — 색을 코드에 박지 않는다.
+- `theme.json` 의 `vary`·`tags`(SPEC 9 「변주」): 이 세계가 approved 되면 `kf theme vary {{id}}` 가 겉모습만 바꾼 판 15개를 뽑는다. 비유를 깨지 않는 축과 범위만 적는다 — 밝기(`scheme`), 강조 색상 범위(`hue`, OKLCH 도), 글꼴 짝(`fonts` — 짝 id·`tag:<태그>`·`tag:<태그>+<태그>`(둘 다 가진 짝 — 짝이 수백이라 결이 다른 무리가 딸려 오지 않게)·`base`. 목록은 `kf fonts list`(`packages/themes/kit/fonts.json`·`kit/fonts/<무리>.json`), 견본은 `kf fonts sheet`), 질감(`texture`), 선 굵기(`stroke` — 슬롯 `trace` 가 `slotkit.traceCanvas` 를 쓰면 실린다), 모서리(`radius`), 빠르기(`tempo`), 밀도(`density` — 효과가 `ctx.style.look?.density` 를 읽을 때만). 금지에 적은 것과 부딪히는 축은 빼고(「밝은 바탕 금지」면 `scheme: ["dark"]`), 재료처럼 색상이 뜻인 색 열쇠는 `fixedHue`, 늘 같은 색은 `keep`. 브랜드 가이드가 라이트·다크 두 벌을 따로 정해 뒀으면 다른 밝기 한 벌을 `palettes.<light|dark>` 에(그 밝기 판은 뒤집어 옮기지 않고 그 벌에서 시작한다). `tags` 는 `{ mood, light, use, dims }` — `use` 에는 그 세계가 맞는 제품·주제 이름도(공통 견본 브리프 낱말은 모든 THEME.md 에 있어 `use` 가 고르기를 가른다). 효과·슬롯 색은 `var(--kf-*)`·`ctx.style.colors` 로 읽어야 변주 색이 실린다 — 색을 코드에 박지 않는다.
 - 글자 대비는 찍힌 픽셀로 3:1 이상 — 옅은 잉크로 작은 글을 쓰지 않는다.
 
 ## 4. 효과 — `effects.ts` (5–10개)