@m1kapp/kit 0.0.37 → 0.0.39

package/bin/lib/project.mjs

@@ -0,0 +1,130 @@
+/**
+ * 프로젝트 종류 감지 + 트래커 slug 배선.
+ *
+ * `m1kkit track --write` 와 `m1kkit new` 가 공유한다. 둘 다 "slug를 발급받는 것"
+ * 까지는 쉬운데 "그 slug를 앱 코드에 꽂는 것"이 지금까지 비어 있던 단계라,
+ * 그 한 단계를 여기 한 곳에 모아둔다.
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from "fs";
+import { join, relative } from "path";
+
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".next", ".git", "coverage", ".vercel"]);
+const CODE_EXT = /\.(tsx|jsx)$/;
+
+/**
+ * Vite / Next 중 무엇인지 판별한다. env 변수 이름이 서로 달라서(그리고 서로의
+ * 이름을 쓰면 조용히 무시되기만 해서) 안내문과 .env 배선이 갈린다.
+ */
+export function detectProject(cwd = process.cwd()) {
+  const has = (f) => existsSync(join(cwd, f));
+  const pkgPath = join(cwd, "package.json");
+  let deps = {};
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    } catch {
+      /* 깨진 package.json — 파일 존재 여부로만 판별 */
+    }
+  }
+
+  const isVite =
+    has("vite.config.ts") || has("vite.config.js") || has("vite.config.mjs") || !!deps.vite;
+  const isNext = has("next.config.ts") || has("next.config.js") || has("next.config.mjs") || !!deps.next;
+
+  // 둘 다면 Next 우선 — Next 프로젝트가 vite를 도구로 물고 있는 경우가 더 흔하다.
+  if (isNext) return { kind: "next", envVar: "NEXT_PUBLIC_M1K_SLUG" };
+  if (isVite) return { kind: "vite", envVar: "VITE_M1K_SLUG" };
+  return { kind: "unknown", envVar: null };
+}
+
+/** `<Watermark` 를 쓰는 첫 소스 파일을 찾는다. */
+export function findWatermarkFile(cwd = process.cwd()) {
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return null;
+    }
+    for (const name of entries) {
+      if (SKIP_DIRS.has(name) || name.startsWith(".")) continue;
+      const full = join(dir, name);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        const found = walk(full);
+        if (found) return found;
+      } else if (CODE_EXT.test(name)) {
+        let src;
+        try {
+          src = readFileSync(full, "utf8");
+        } catch {
+          continue;
+        }
+        if (src.includes("<Watermark")) return full;
+      }
+    }
+    return null;
+  };
+  return walk(cwd);
+}
+
+/** `.env` 에 `KEY=value` 를 병합한다(기존 키는 덮어씀). */
+export function upsertEnv(cwd, key, value) {
+  const file = join(cwd, ".env");
+  const line = `${key}=${value}`;
+  if (!existsSync(file)) {
+    writeFileSync(file, line + "\n");
+    return { file, action: "created" };
+  }
+  const src = readFileSync(file, "utf8");
+  const re = new RegExp(`^${key}=.*$`, "m");
+  if (re.test(src)) {
+    if (src.match(re)[0] === line) return { file, action: "unchanged" };
+    writeFileSync(file, src.replace(re, line));
+    return { file, action: "updated" };
+  }
+  writeFileSync(file, src.endsWith("\n") ? src + line + "\n" : src + "\n" + line + "\n");
+  return { file, action: "appended" };
+}
+
+/**
+ * slug를 앱에 실제로 연결한다. `.env` 기록 + `<Watermark>` 패치를 둘 다 한다.
+ *
+ * `<Watermark>` 에 이미 `trackSlug` 가 있으면(템플릿이 심어둔
+ * `trackSlug={import.meta.env.VITE_M1K_SLUG}` 포함) 건드리지 않고 `.env` 만 쓴다.
+ * 없으면 문자열 리터럴을 박는다 — 번들러 종류와 무관하게 항상 동작하는 유일한
+ * 형태라서다. (Vite는 `import.meta.env` 를 앱 소스에서만 치환하므로 kit 내부
+ * 폴백은 존재할 수 없고, 남의 프로젝트 구조를 가정할 수도 없다.)
+ * slug 자체는 공개값이라 하드코딩해도 문제없다.
+ */
+export function wireSlug(cwd, slug, { envOnly = false } = {}) {
+  const project = detectProject(cwd);
+  const report = { kind: project.kind, patched: null, env: null, alreadyWired: false };
+
+  if (project.envVar) report.env = { ...upsertEnv(cwd, project.envVar, slug), key: project.envVar };
+
+  if (envOnly) return report;
+
+  const file = findWatermarkFile(cwd);
+  if (!file) return report;
+
+  const src = readFileSync(file, "utf8");
+  if (/<Watermark[^>]*\btrackSlug=/.test(src)) {
+    report.alreadyWired = true;
+    report.patched = relative(cwd, file);
+    return report;
+  }
+
+  const patched = src.replace(/<Watermark(?=[\s>])/, `<Watermark trackSlug="${slug}"`);
+  if (patched === src) return report;
+
+  writeFileSync(file, patched);
+  report.patched = relative(cwd, file);
+  return report;
+}

package/bin/m1kkit.mjs

@@ -15,22 +15,25 @@ if (!command || command === "--help" || command === "-h") {
 m1kkit — @m1kapp/kit CLI
 
 Commands:
+  m1kkit new <name>          새 앱 생성 (Vite + React + kit 앱쉘 템플릿)
   m1kkit favicon [options]   파비콘 자동 생성
   m1kkit skills [options]    Claude Code 스킬 설치
   m1kkit stats [options]     코드 분석 & kit 사용 현황 생성
   m1kkit track <url>         m1k 방문자 트래커에 사이트 등록(무로그인)
+  m1kkit untrack [slug]      등록 취소 — 사이트와 누적 기록 삭제
   m1kkit claim [--token=x]   등록한 사이트를 내 계정에 귀속
 
 Options:
   --help    도움말 보기
 
 Examples:
+  m1kkit new moodlog --color=#e2603f
   m1kkit favicon --text=K --color=#3B82F6
   m1kkit skills
   m1kkit skills --list
   m1kkit skills m1kapp-init
   m1kkit stats --dir=src --out=public
-  m1kkit track https://myside.app
+  m1kkit track https://myside.app --write
   m1kkit claim
 `);
   process.exit(0);
@@ -43,7 +46,10 @@ const path = await import("path");
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-if (command === "favicon") {
+if (command === "new") {
+  process.argv = [process.argv[0], process.argv[1], ...rest];
+  await import(path.join(__dirname, "new.mjs"));
+} else if (command === "favicon") {
   process.argv = [process.argv[0], process.argv[1], ...rest];
   await import(path.join(__dirname, "favicon.mjs"));
 } else if (command === "skills") {
@@ -55,6 +61,9 @@ if (command === "favicon") {
 } else if (command === "track") {
   process.argv = [process.argv[0], process.argv[1], ...rest];
   await import(path.join(__dirname, "track.mjs"));
+} else if (command === "untrack") {
+  process.argv = [process.argv[0], process.argv[1], ...rest];
+  await import(path.join(__dirname, "untrack.mjs"));
 } else if (command === "claim") {
   process.argv = [process.argv[0], process.argv[1], ...rest];
   await import(path.join(__dirname, "claim.mjs"));

package/bin/new.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * m1kkit new <name> [--color=#hex] [--title=..] [--desc=..] [--url=..]
+ *                   [--no-install] [--yes]
+ *
+ * 검증된 템플릿을 복사해서 새 Vite + @m1kapp/kit 앱을 만든다.
+ *
+ * 스킬(LLM이 산문을 읽고 매번 코드를 다시 타이핑하는 방식)이 반복해서 깨뜨렸던
+ * 것들 — `useState(colors.blue)` 리터럴 협착, `vite-env.d.ts` 누락, TODO 주석만
+ * 남은 빈 화면 — 을 파일로 고정해두고 그대로 복사한다.
+ */
+import { readdirSync, statSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+import { join, dirname, resolve, basename } from "path";
+import { fileURLToPath } from "url";
+import { spawnSync } from "child_process";
+import { createInterface } from "readline";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { wireSlug } = await import(join(__dirname, "lib", "project.mjs"));
+
+const args = process.argv.slice(2);
+const flags = Object.fromEntries(
+  args
+    .filter((a) => a.startsWith("--"))
+    .map((a) => {
+      const [k, v] = a.replace(/^--/, "").split("=");
+      return [k, v ?? true];
+    }),
+);
+const positional = args.filter((a) => !a.startsWith("--"));
+
+if (flags.help) {
+  console.log(`
+m1kkit new — 새 m1kapp 앱 만들기 (Vite + React + @m1kapp/kit)
+
+사용법:
+  npx m1kkit new <이름> [옵션]
+
+옵션:
+  --title=<이름>    화면/타이틀에 뜰 이름 (기본: <이름>)
+  --desc=<한줄>     한 줄 설명 (meta description)
+  --color=#3B82F6   테마 컬러
+  --url=<배포URL>   있으면 방문자 트래커를 지금 등록하고 코드에 배선
+  --slug=<slug>     이미 발급받은 slug — 재등록 없이 배선만
+  --no-install      npm install 건너뛰기
+  --yes             질문 없이 기본값으로 진행
+
+예시:
+  npx m1kkit new moodlog
+  npx m1kkit new moodlog --color=#e2603f --url=https://moodlog.m1k.app
+`);
+  process.exit(0);
+}
+
+const TEMPLATE = join(__dirname, "..", "templates", "vite-app");
+if (!existsSync(TEMPLATE)) {
+  console.error(`✗ 템플릿을 못 찾음: ${TEMPLATE}`);
+  process.exit(1);
+}
+
+/* ── 아주 약한 grill: 4문항, 전부 기본값 있음 ─────────────────────────── */
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q, fallback) =>
+  new Promise((res) => {
+    if (flags.yes || !process.stdin.isTTY) return res(fallback);
+    rl.question(`${q}${fallback ? ` (${fallback})` : ""}: `, (a) => res(a.trim() || fallback));
+  });
+
+const name = positional[0] || (await ask("앱 이름(폴더명)", "my-m1kapp"));
+const title = flags.title || (await ask("화면에 뜰 이름", name));
+const desc = flags.desc || (await ask("한 줄 설명", `${title} — m1kapp으로 만든 사이드 프로젝트`));
+const color = flags.color || (await ask("테마 컬러(hex)", "#3B82F6"));
+const url = flags.url || (await ask("배포 URL — 지금 알면 방문자 트래커를 바로 붙임(없으면 엔터)", ""));
+rl.close();
+
+if (!/^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/.test(color)) {
+  console.error(`✗ 테마 컬러가 hex가 아님: ${color}`);
+  process.exit(1);
+}
+
+const target = resolve(process.cwd(), name);
+if (existsSync(target) && readdirSync(target).length > 0) {
+  console.error(`✗ 이미 있고 비어있지 않은 폴더: ${target}`);
+  process.exit(1);
+}
+
+/* ── 템플릿 복사 + 치환 ──────────────────────────────────────────────── */
+
+const SUBST = {
+  __APP_NAME__: basename(name),
+  __TITLE__: title,
+  __DESC__: desc,
+  __COLOR__: color,
+};
+const TEXT_EXT = /\.(tsx?|jsx?|css|html|json|md)$/;
+// npm pack 이 `.gitignore` / 중첩 `package.json` 을 특수 취급하므로 템플릿에는
+// 밑줄 접두사로 넣어두고 복사할 때 되돌린다.
+const RENAME = { _gitignore: ".gitignore", _package_json: "package.json", "_package.json": "package.json" };
+
+function copyTree(from, to) {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from)) {
+    const src = join(from, entry);
+    const dst = join(to, RENAME[entry] ?? entry);
+    if (statSync(src).isDirectory()) {
+      copyTree(src, dst);
+      continue;
+    }
+    let content = readFileSync(src, TEXT_EXT.test(entry) || RENAME[entry] ? "utf8" : null);
+    if (typeof content === "string") {
+      for (const [k, v] of Object.entries(SUBST)) content = content.split(k).join(v);
+    }
+    writeFileSync(dst, content);
+  }
+}
+
+copyTree(TEMPLATE, target);
+console.log(`\n✓ ${name}/ 생성 완료`);
+
+/* ── 설치 ────────────────────────────────────────────────────────────── */
+
+const run = (cmd, cmdArgs) =>
+  spawnSync(cmd, cmdArgs, { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
+
+if (!flags["no-install"]) {
+  console.log(`\n› npm install …`);
+  const r = run("npm", ["install"]);
+  if (r.status !== 0) {
+    console.error(`\n✗ npm install 실패 — ${target} 에서 직접 다시 돌려주세요.`);
+    process.exit(1);
+  }
+}
+
+/* ── 방문자 트래커 배선 ──────────────────────────────────────────────── */
+
+if (flags.slug) {
+  // 이미 발급받은 slug가 있는 경우 — 재등록 없이 배선만.
+  const r = wireSlug(target, flags.slug);
+  console.log(`\n✓ 트래커 배선: ${r.patched ?? "(Watermark 파일 못 찾음)"} + .env`);
+} else if (url) {
+  console.log(`\n› 방문자 트래커 등록 …`);
+  const r = run("npx", ["m1kkit", "track", url, "--write"]);
+  if (r.status !== 0) {
+    console.log(`  ! 등록 실패 — 나중에:  npx m1kkit track ${url} --write`);
+  }
+} else {
+  console.log(`
+  · 방문자 트래커는 아직 안 붙었습니다(배포 URL 미정).
+    배포하고 나서 프로젝트 폴더에서 딱 한 줄:
+      npx m1kkit track <배포URL> --write`);
+}
+
+console.log(`
+다음 단계:
+  cd ${name}
+  npm run dev
+
+  npm run build      타입 + 번들 검증
+  npx m1kkit favicon 파비콘 생성
+  npx m1kkit claim   트래커를 내 계정에 귀속
+`);

package/bin/skills/m1kapp-clean.md

@@ -1,86 +1,166 @@
-`m1kkit stats`의 청결도 점수(quality)를 근거로 코드를 **동작 변화 없이** 정리해 등급을 올린다. 목표: 복잡 함수(CC 10+)를 줄이고, 200줄+ 파일을 쪼개고, 재실행으로 개선을 수치로 증명한다.
+`npx m1kkit stats`(내부적으로 fixearly)가 낸 점수를 근거로, **동작을 바꾸지 않고** 코드를 정리한다.
+목적은 등급 숫자가 아니라 **다음에 이 코드를 고칠 때 드는 비용**을 줄이는 것이다.
 
-점수 구조 v2 (AST 모드, 100점 감점제):
-- cognitive>15 함수 비율 ×3 (최대 -25) / cognitive>25 함수 비율 ×5 (최대 -15)
-- 최악 함수 cognitive 20 초과분 ×1 (최대 -15)
-- **중복 밀도 3% 초과분 ×2.5 (최대 -25)** — 토큰 단위 복붙 검출 (식별자 정규화, 테스트 제외)
-- 200줄 초과 파일 비율 ×2 (최대 -10) / 평균 파일 길이 80줄 초과분 ÷5 (최대 -10)
-- **루프 안 무캐시 파일읽기 ×4 (최대 -20)** — 호출 1번이 파일을 N번 읽는 구조 (`quality.io`)
-- **렌더 인질 ×3 (최대 -10)** — fetch 하나가 무관한 UI까지 막는 자리 (`quality.renderGates`)
+---
+
+## 먼저 — 고치지 말아야 할 때
+
+작업을 시작하기 전에 이 넷을 확인한다. 하나라도 걸리면 **그 항목은 건너뛴다.**
+
+1. **동결된 저장소** — 리포트 상단에 "이 저장소는 지금 고칠 이유가 없다"(최근 6개월 변경 0건)가 뜨면
+   손대지 않는다. 변경 비용은 변경이 일어날 때만 발생한다.
+2. **`안정` 태그가 붙은 항목** — 그 파일은 최근에 아무도 안 만졌다. 복잡해도 리팩터 ROI가 낮다.
+3. **선언적 마크업** — `cog ≤ 5`인데 길기만 한 함수(OG 이미지, 공유 카드, 랜딩 히어로).
+   분기가 없는 JSX 트리는 쪼개도 읽기가 안 나아진다. 스타일 상수와 데이터를 props로 릴레이하느라
+   오히려 결합만 는다. **실측: 긴 함수 목록의 약 절반이 여기 해당한다.**
+4. **평평한 가드 파이프라인** — 리포트에 `분기 대부분이 빠져나가는 가드 절이다(NN%)` 가
+   붙은 항목. `if (!url) return 400;` 이 여덟 줄 늘어선 요청 핸들러가 전형이다.
+   cog 는 이걸 3단 중첩과 같은 점수로 매기지만, 가드는 하나씩 읽고 잊으면 되므로
+   머리에 안 쌓인다. 헬퍼 뒤로 숨기면 요청 생명주기가 오히려 안 보인다.
+   고칠 게 있다면 가드가 아니라 **그 뒤 본문의 중첩**이다.
+
+> 지표는 언제나 뭔가를 지적할 수 있다. 도구가 일감을 만들어내게 두지 마라.
+
+---
+
+## 점수 구조 (규칙 v7 · 100점 감점제 · 캡 기준 배점)
+
+| 축 | 배점 | 내용 |
+|---|---|---|
+| **함수 길이** | **23** | 40줄 초과(JSX 60줄) 비율 16 · p90 3 · 상위10 평균 4 |
+| **인지 복잡도** | **37** | cog15+ 12 · cog25+ 12 · p90 9 · 상위10 평균 4 |
+| **중복** | **9** | 8% 초과분만. 70개 코퍼스에서 점수와 상관 −0.11 |
+| **파일 크기** | **8** | 평균 줄 5 · 200줄+ 비중 3 |
 
-cognitive = 중첩 깊이 가중 복잡도 (SonarQube 방식): `a && b && c`는 1, 5중 중첩 if는 flat if 5개보다 훨씬 비쌈. `??`는 미카운트. 즉 **평평하게 펴는 것(조기 반환)이 진짜 점수가 됨** — 함수 쪼개기만으론 안 오름.
+**우선순위가 예전과 바뀌었다.** 옛 스킬은 "① 중복 제거"부터 시켰지만, 중복은 배점 9점에
+대부분의 저장소에서 0점 기여다(롱테일 — 소수만 크게 맞는다). 지금 실제로 점수를 가르는 건
+**함수 길이**와 **복잡도 분포**다.
 
-`io` 축은 나머지와 성격이 다르다. cognitive·중복은 "코드가 얼마나 꼬였나"라 5줄짜리
-흠 없는 리더가 루프에서 120번 불리는 종류는 **원리상 못 잡는다** — 실제로 요청당 파일을
-492번 읽던 코드가 A+ 100점을 통과한 적이 있다. 그래서 파일을 읽는 함수(한 다리 건너
-읽는 얇은 래퍼 포함)를 찾아 루프·`map` 안에서 불리는 자리를 센다. 그 리더가 캐시를
-끼고 있으면(모듈 Map을 get/set) 반복 호출돼도 실제 읽기는 한 번이라 감점하지 않는다.
-**고치는 법은 리팩토링이 아니라 캐시를 끼우거나 한 번 읽어 재사용하도록 구조를 바꾸는 것** —
-`quality.io.worst`가 위치를 지목한다.
+**분포 항이라는 점이 중요하다.** 최악 함수 하나를 고쳐도 거의 안 움직인다 —
+상위 10개 평균을 쓰기 때문에 **여러 개를 실제로 줄여야** 내려간다.
 
-`renderGates`도 같은 성격이다. `{data && <Nav a={local} b={data.x} onChange={fn} />}`처럼
-프롭 3개 중 1개만 그 데이터에 의존하는데 전체가 대기하면, 사용자에겐 이미 아는 UI까지
-매번 로딩으로 보인다. 데이터에 의존하는 부분만 늦게 채우고 나머지는 먼저 그리는 게 답이다
-(서버가 아는 값이면 아예 서버에서 내려주면 된다).
+**그리고 점수가 안 움직이는 게 정상인 구간이 있다.** 대부분의 축은 코퍼스 중앙값까지
+유예라, 중앙보다 좋은 저장소에선 이미 감점 0 — 더 좋아져도 뺄 게 없다. 이게 v7 에서
+`p90` 항을 6점에서 3점으로 줄인 이유다. 남은 축이 그것뿐이라 순위통계 한 줄이 밀리는
+것만으로 점수가 뒤집혔다(실측: cog15+ 함수를 저장소에서 전부 없앴는데 순이익 −1점).
 
-즉 **효율 순서: ① 중복 블록 제거 (kit-stats.json `quality.duplication.worstBlocks`가 위치 지목) ② 최악 함수 중첩 평탄화 ③ cog15+ 함수들 ④ 긴 파일 분할**.
+cognitive = 중첩 깊이 가중(SonarSource S3776). `a && b && c`는 1, 5중 중첩 if는 flat if 5개보다
+훨씬 비싸다. 즉 **평평하게 펴는 것**이 점수가 되지, 함수만 쪼갠다고 오르지 않는다.
 
-`--llm` 플래그(선택): cognitive 최악 3개를 Claude(haiku)가 네이밍·응집도·본질적 복잡성 여부 자문 — 점수 미반영, `quality.llm`에 기록. "essential: true"로 나온 함수는 억지로 쪼개지 말 것.
+### 점수에 반영되지 않는 진단 (등급과 무관, 그래도 진짜 결함)
+
+`O(n²) 배열 조회` · `루프 안 파일 IO/N+1` · `await in forEach` · `스프레드 누적` ·
+`루프 안 new RegExp` · `공유 참조 fill` · `빈 catch` · `타입 위생`.
+
+특히 **O(n²)와 N+1은 n이 실제로 큰지 사람이 확인해야** 의미가 있다. 상수 목록·설정값을
+도는 자리면 고치지 말고 그 근거를 적어라. 그래서 점수에서 뺐다.
 
 ---
 
 ## Step 0: 진단
 
 ```bash
-npx m1kkit stats            # 또는 프로젝트에 맞는 --dir/--out (package.json scripts.stats 참고)
+npm run stats:report        # 또는 npx m1kkit stats --report
 ```
 
-- 콘솔의 `복잡: <함수명> CC <n> — <파일>:<줄>` 목록 = 작업 대상 우선순위.
-- `public/kit-stats.json`의 `quality.cc.worst`(상위 5개), `over10`/`over20`, `longFiles`, `maxFile`도 확인.
-- `quality.engine`이 `"regex"`면 typescript가 devDependencies에 없는 것 — 설치하면 AST 정밀 분석으로 전환된다.
-- 시작 점수·등급을 기록해 둔다 (개선 전후 비교용).
+리포트(HTML)에서 이 순서로 읽는다:
+
+1. **동결 배너** — 있으면 여기서 멈춘다.
+2. **어디쯤인가** — 같은 체급 오픈소스 안에서 내 위치. 이미 체급 중앙 이상이면 급하지 않다.
+3. **무엇부터 고칠까** — **변경 비용 순**(복잡도 × churn)으로 정렬돼 있다. 점수 순이 아니다.
+   각 줄의 `점수 영향` 칩을 본다: `점수 무관`이면 등급은 안 오르지만 진짜 결함이라는 뜻이다.
+4. **점수 지도** — `이미 지켜낸 축`(감점 0)은 건드리지 않는다.
+
+각 항목의 **[지시문]** 버튼이 그 결함 하나만 고치는 작업 지시문을 준다. 그대로 쓰면 된다.
+
+---
+
+## Step 1: 고치기 — 우선순위 순
+
+### ① 긴 함수 (배점 최대)
 
-## Step 1: 리팩토링 — CC 낮추는 표준 기법만
+**단, 위 "고치지 말아야 할 때" 3번을 먼저 통과해야 한다.** `cog ≤ 5`면 마크업이다.
 
-대상 함수를 열고 아래 순서로 적용. **기능·출력·API 시그니처 불변**이 절대 조건.
+- **로직과 렌더를 분리** — 상태·핸들러 뭉치를 커스텀 훅으로. `useXxxGame()`, `useFilters()`처럼
+  이름이 자연스럽게 붙으면 옳은 분할이다.
+- **상수를 밖으로** — 함수 안에 인라인된 딕셔너리·설정 테이블은 모듈 상수로.
+- **독립 단계 추출** — 파싱/검증/변환/포맷처럼 한 덩어리로 이름 붙는 단계.
 
-1. **조기 반환(guard clause)**: 중첩 if를 `if (!x) return`으로 평탄화 — CC는 그대로여도 가독성↑, 보통 else 제거로 CC↓
-2. **분기 → 데이터**: if/else if 체인·switch를 lookup 객체/Map/배열로. `조건 ? a : b` 체인도 테이블화. CC 감소 효과 최대
-3. **헬퍼 추출**: 한 함수 안의 독립 단계(파싱/검증/변환/포맷)를 이름 있는 함수로 분리 — 함수당 CC가 나뉜다. 단, 한 곳에서만 쓰는 3줄짜리를 억지로 쪼개지 말 것
-4. **`&&`/`||` 체인 → 이름 있는 boolean**: `const isStale = a && b || c` 처럼 의미 단위로 묶기 (CC 총량은 유지되지만 함수 분리와 병행 시 분산)
-5. **긴 컴포넌트 분할**: 200줄+ 파일은 렌더 섹션별 서브컴포넌트/훅으로. props drilling이 3단계 넘게 생기면 무리한 분할이니 중단
-6. **kit 활용**: 직접 짠 로직이 kit 컴포넌트/유틸(`AsyncList`, `fillDateSeries`, `formatKoreanNumber` 등)로 대체되면 코드 자체가 사라진다 — 청결도와 kit 반영율 동시 상승
+> **잘라낸 함수에 이름을 붙일 수 없으면 자른 게 아니다.** `Part1`·`Section2`가 나오면 되돌려라.
 
-**금지**: 과추상화(1회용 제네릭 헬퍼, 설정 객체 패턴 남발), 동작 바뀌는 "개선", 테스트 없는 공개 API 시그니처 변경, CC 점수만 노린 의미 없는 함수 쪼개기.
+### ② 복잡도 (cog 15+ / 25+)
 
-## Step 2: 검증
+리포트가 각 항목에 `깊이 N` 을 적는다. **깊이가 목표지 cog 숫자가 목표가 아니다.**
+같은 cog 라도 깊이 2와 깊이 5는 다른 문제다. 위 "고치지 말아야 할 때" 4번(가드 파이프라인)을
+먼저 통과했는지 확인하라.
+
+- **조기 반환(guard clause)** — 중첩 if를 `if (!x) return`으로. 깊이가 줄면 cog가 크게 떨어진다.
+  주의: 조기 반환으로 편 결과는 cog 가 거의 안 줄 수도 있다(가드도 +1씩 센다).
+  그래도 그게 옳은 방향이다 — 깊이가 줄었으면 성공이다.
+- **분기 → 데이터** — if/else 체인·switch를 lookup 객체나 Map으로. 효과 최대.
+- **`&&`/`||` 체인 → 이름 있는 boolean** — 의미 단위로 묶어 읽기를 낮춘다.
+
+### ③ 중복 (8% 넘을 때만)
+
+**같은 이유로 함께 바뀔 코드만** 합친다. 우연히 닮은 두 모듈에서 공용 헬퍼를 뽑으면
+결합도만 오른다. 빌드 타깃별 의도적 사본은 그대로 둔다.
+
+### ④ 파일 크기 (배점 8 — 마지막)
+
+**여기서 점수를 벌 생각이면 그만두는 게 낫다.** 같은 코드를 6파일로 쪼개기만 해도 옛 공식은
++27점을 줬고, 그래서 배점을 8점으로 낮췄다. 파일이 긴 진짜 이유(한 파일에 여러 책임)를
+먼저 확인하고, 책임이 실제로 여러 개일 때만 나눈다.
+
+### ⑤ kit 활용
+
+직접 짠 로직이 kit 컴포넌트·유틸로 대체되면 코드 자체가 사라진다 — 점수와 kit 반영율이 함께 오른다.
+`--kit` 집계의 `kit 사용: N개 요소`가 낮은데 비슷한 걸 직접 짜고 있으면 후보다.
+
+**금지**: 과추상화(1회용 제네릭 헬퍼, 설정 객체 남발), 동작이 바뀌는 "개선",
+테스트 없는 공개 API 시그니처 변경, 지표만 노린 기계적 분할, 쓰레기 헬퍼로 분모 부풀리기.
+
+---
+
+## Step 2: 검증 — 동작 불변을 증명한다
 
 ```bash
 npx tsc --noEmit && npm run build
 ```
 
-- 둘 다 통과해야 다음 함수로. 테스트 있으면 테스트도.
-- 리팩토링 전후 해당 화면/API 동작을 실제로 확인 (dev 서버·curl).
+- 둘 다 통과해야 다음 항목으로. 테스트가 있으면 테스트도.
+- 화면/API를 실제로 확인한다(dev 서버·curl).
+- **확인 안 했으면 "확인 안 함"이라고 적는다.** 추측으로 "개선했다"고 쓰지 않는다.
+
+---
 
-## Step 3: 재측정 · 반복
+## Step 3: 재측정 — 변화량으로 증명
 
 ```bash
-npx m1kkit stats
+npm run stats:report
 ```
 
-- 점수·등급 변화를 확인. 오르지 않았으면 감점 구조를 다시 보고 다른 항목 공략.
-- 기본 목표: **B(70) 이상**, 여유 되면 A(80). 사용자가 목표 등급을 줬으면 그걸 따른다.
-- 한 사이클(함수 1~3개)마다 커밋 — 대량 일괄 리팩토링 금지 (리뷰·롤백 불가능해짐).
+리포트의 **지난번 대비** 섹션이 전/후를 보여준다(`.fixearly-history.json`에 이력이 쌓인다).
+
+**점수보다 원지표를 먼저 본다** — `긴 함수 661개 → 623개(−38)`, `함수 길이 상위10 평균 372 → 336줄`.
+점수는 절대 위치고, 변화량이 당신이 한 일이다. 자기 이력과의 비교라 지표만 건드려서는 안 움직인다.
+
+- 한 사이클(항목 1~3개)마다 커밋. 대량 일괄 리팩터 금지 — 리뷰·롤백이 불가능해진다.
+- 점수가 안 올랐는데 원지표가 좋아졌으면 **성공이다**. 분포 항이라 여러 개를 고쳐야 움직인다.
+
+---
 
 ## Step 4: 마무리
 
-- 갱신된 `public/kit-stats.json` 커밋 (배포된 사이트·m1k.app dev 모드에 새 등급 반영).
-- 최종 보고: 전/후 점수·등급, 처리한 함수 목록(CC 전→후), 남은 CC10+ 함수와 이유(예: "정당한 복잡도 — 상태 머신").
+- 최종 보고: 전/후 점수·등급, **원지표 변화**, 처리한 항목 목록, 그리고 **안 고친 항목과 그 이유**.
+- 안 고치는 판단도 결과물이다 — "마크업이라 분할 이득 없음", "n이 상수 목록이라 O(n²) 무의미",
+  "churn 0이라 ROI 낮음"은 모두 정당한 결론이다.
 
 ---
 
 ## 주의
 
-- CC가 높다고 전부 나쁜 코드는 아니다. 본질적으로 분기 많은 도메인(뱃지 SVG 분기, cron 집계)은 **데이터 테이블화가 안 되면 그대로 두고 보고에 사유 명시**.
-- `(anonymous)` 함수는 콜백/핸들러 — 이름 있는 함수로 빼는 것만으로 추적 가능해진다.
-- 점수는 상대 비교용 휴리스틱. 100점 만들기가 목적이 아니라 최악 지점 제거가 목적.
+- 복잡도가 높다고 전부 나쁜 코드가 아니다. 본질적으로 분기 많은 도메인(상태 머신, SVG 분기,
+  집계 크론)은 데이터 테이블화가 안 되면 **그대로 두고 사유를 적는다**.
+- `(anonymous)` 함수는 콜백/핸들러다. 이름만 붙여도 추적이 된다.
+- 점수는 **한 가지 렌즈**다. 설계·테스트·문서·보안·성능·커뮤니티는 재지 않는다.
+  낮은 등급이 나쁜 프로젝트라는 뜻이 아니다.

package/bin/skills/m1kapp-new.md

@@ -0,0 +1,73 @@
+---
+name: m1kapp-new
+description: 새로운 m1kapp 서비스 프로젝트를 스캐폴딩 — m1kkit new 로 뼈대를 만들고, 컨셉에 맞게 첫 화면을 채운다
+---
+
+`$ARGUMENTS` 위치에 새로운 m1kapp 서비스 프로젝트를 생성해줘.
+
+**뼈대는 직접 타이핑하지 마라.** `npx m1kkit new`가 검증된 템플릿을 복사한다.
+이 스킬이 파일 내용을 산문으로 받아적던 시절엔 매번 같은 자리가 깨졌다 —
+`useState(colors.blue)` 리터럴 협착으로 `tsc` 실패, `vite-env.d.ts` 누락으로
+`import "./index.css"` 실패, 본문이 `{/* TODO */}` 하나뿐인 빈 화면.
+지금은 그게 전부 `templates/vite-app/` 안의 실제 파일로 고정되어 있고 빌드로 검증된다.
+
+네가 할 일은 **뼈대 위에 컨셉을 얹는 것**이다.
+
+## Step 1 — 아주 약한 grill (4문항)
+
+한 번에 묻는다. 인자로 이미 준 건 기본값으로 채워 제안.
+
+1. 앱 이름 (폴더명) + 화면에 뜰 이름
+2. 한 줄 컨셉 — 이게 첫 화면 구성을 정한다
+3. 테마 컬러 (hex, 없으면 `#3B82F6`)
+4. 배포 URL — 정해졌으면 지금. 그래야 방문자 트래커가 이 자리에서 붙는다. 미정이면 미정이라고만.
+
+## Step 2 — 뼈대 생성
+
+```bash
+npx m1kkit new <이름> --title=<화면이름> --desc=<한줄> --color=<hex> [--url=<배포URL>] --yes
+```
+
+- 생성 경로는 현재 디렉토리 하위. `/Users/minho/IdeaProjects/m1kapp/` 아래 만들 거면 거기서 실행한다.
+- `--url`을 주면 `m1kkit track ... --write`까지 자동으로 돌아 `.env`에 `VITE_M1K_SLUG`가 박힌다.
+- `--url` 없이 만들었으면 배포 후 프로젝트 폴더에서 한 줄:
+  `npx m1kkit track <배포URL> --write`
+
+## Step 3 — 컨셉에 맞게 첫 화면 채우기
+
+템플릿의 `src/App.tsx`는 홈/목록 두 탭 + StatChip + ListRow + EmptyState + Fab이
+더미 데이터로 이미 돌아가는 상태다. **이걸 지우고 새로 짜지 말고, 더미를 진짜로 갈아끼운다.**
+
+지킬 것:
+- `Watermark > AppShell > AppShellHeader/AppShellContent/TabBar` 트리는 유지.
+  `Watermark`가 `h-dvh` + 중앙정렬 + 하단 `PoweredByKit` 크레딧을 담당한다 —
+  빼면 콘텐츠 높이만큼 쪼그라들고 크레딧도 안 뜬다.
+- `<Watermark trackSlug={import.meta.env.VITE_M1K_SLUG}>` 줄은 **건드리지 마라.**
+  Vite는 `import.meta.env`를 앱 소스에서만 치환한다 — kit 안에서는 못 읽으므로
+  이 줄이 유일한 연결 지점이다.
+- `AppShellContent` 안은 `<Section>` 블록을 `<Divider spacing="sm" />`로 구분해 쌓는다.
+  `<div className="p-4 flex flex-col gap-4">` 같은 손수 만든 wrapper 금지.
+- 탭 이름·섹션 내용은 컨셉에 맞게 바꾸되, **비우지 마라.** `{/* TODO */}` 하나만
+  남기고 끝내면 실패다. 데이터가 아직 없으면 `EmptyState`를, 숫자가 아직 없으면
+  `StatChip value={0}`을 쓴다.
+- 테마색은 `themeColor` 상태 하나로 흐른다(`AppShell accent` / `Tab activeColor` /
+  `Fab color`). 하드코딩된 색을 새로 뿌리지 마라.
+
+자주 쓰는 kit 컴포넌트: 레이아웃 `AppShell/AppShellHeader/AppShellContent`,
+내비 `TabBar/Tab/Fab`, 표시 `Section/SectionHeader/StatChip/Badge/Avatar/EmptyState/
+Divider/Skeleton/BarList/ProgressRing/ListRow/ActionCard`, 오버레이 `Dialog/InAppSheet/
+ToastProvider·useToast/Tooltip`, 입력 `Button/IconButton/Input/Textarea/Field/Select/
+Switch/SegmentedControl/EmojiButton/InlineEdit/ColorPicker`, 모션 `Typewriter/Countdown/Carousel`.
+
+## Step 4 — 확인하고 보고
+
+1. `npm run build` — 타입·번들 통과 확인 (반드시 프로젝트 루트에서)
+2. `npm run dev` 띄우고 **첫 화면을 눈으로 본 뒤** 보고한다:
+   - 워터마크 배경이 깔렸는가
+   - 앱쉘이 화면 중앙에 꽉 찼는가 (모바일 폭에서 가로 스크롤 0)
+   - 본문이 비어 있지 않은가
+   - 하단에 `powered by @m1kapp/kit` 줄이 뜨는가
+   - 트래커를 붙였다면 `www.m1k.app/badge/<slug>.svg` 요청이 나가는가
+3. `git init` + 첫 커밋 준비 (커밋은 사용자 확인 후)
+
+추가 컨텍스트: $ARGUMENTS

package/bin/skills.mjs

@@ -16,9 +16,13 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SKILLS_SRC = path.join(__dirname, "skills");
 
 const SKILLS = [
+  {
+    name: "m1kapp-new",
+    desc: "/m1kapp-new   — 새 앱 만들기 (m1kkit new 템플릿 + 컨셉에 맞춰 첫 화면 채우기)",
+  },
   {
     name: "m1kapp-init",
-    desc: "/m1kapp-init  — Next.js 프로젝트 초기 설정 인터랙티브 스캐폴딩",
+    desc: "/m1kapp-init  — 기존 Next.js 프로젝트에 kit 초기 설정 적용",
   },
   {
     name: "m1kapp-seo",