@kaydash9999/banker-plugins 0.15.1 → 0.16.0

package/skills/motion-graphic-make/references/preview-lib.mjs

@@ -0,0 +1,256 @@
+/*
+ * Shared by serve.mjs and curate.mjs: the local servers of the 3d-intro-build skill (mirrored
+ * byte-identical into motion-graphic-make by scripts/sync-adapter.js).
+ *
+ * - A port the system picks (a preferred one first when asked), bound to loopback by default.
+ * - A state file recording { pid, port, requestedPort, host, url, dir }: serve.mjs keeps it beside
+ *   the folder it serves, curate.mjs in the project folder, which it does not serve (it serves
+ *   listed takes only).
+ * - Requests whose Host is a name other than localhost are refused, so a DNS name rebound to this
+ *   machine cannot read what is served.
+ * - A stop that ends only the process answering on that port with the recorded PID (a whole number
+ *   above 1), then waits for the port to close. Nothing is matched by command line (no pkill -f).
+ * - Files open before any header goes out, so one that cannot be read gets 403 and the server
+ *   stays up, and a download the browser drops closes its file.
+ * - An optional Content-Security-Policy header, so a page is checked under the policy it ships with.
+ *
+ * Runtime: Node >=18 builtins only (node:fs / node:http / node:net / node:path). No shell.
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { pipeline } from 'node:stream';
+
+export const LOOPBACK = '127.0.0.1';
+// Answers { pid } so a stop can tell this server from another process on the same port.
+export const PID_ROUTE = '/__preview/pid';
+// As strict as a production site: no inline script or style. The scrub engine fetches its clips
+// from its own origin and plays them from blob: URLs.
+export const STRICT_CSP = [
+  "default-src 'self'", "script-src 'self'", "style-src 'self'", "img-src 'self' data: blob:",
+  "media-src 'self' blob:", "connect-src 'self'", "font-src 'self'", "object-src 'none'",
+  "base-uri 'self'", "frame-ancestors 'none'",
+].join('; ');
+
+export const MIME = {
+  '.html': 'text/html;charset=utf-8', '.css': 'text/css;charset=utf-8', '.js': 'text/javascript;charset=utf-8',
+  '.mjs': 'text/javascript;charset=utf-8', '.json': 'application/json;charset=utf-8', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.svg': 'image/svg+xml',
+  '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.woff2': 'font/woff2',
+};
+
+// `strict` is the policy above; any other text is a policy as written; nothing means no header.
+export const cspFrom = (value) => (value ? (value === 'strict' ? STRICT_CSP : String(value)) : null);
+
+export function hostWarning(host) {
+  if (!host || [LOOPBACK, 'localhost', '::1'].includes(host)) return null;
+  return `주의: ${host} 에 바인드합니다. 같은 네트워크의 기기가 아직 공개하지 않은 산출물을 볼 수 있습니다. 끝나면 --stop 으로 닫으세요.`;
+}
+
+// True for a Host header naming this machine as localhost, by an IP address, or by a name the server
+// was bound to (`names`); any other DNS name fails, which is what a rebinding attack needs.
+export function hostAllowed(hostHeader, names = []) {
+  const h = String(hostHeader || '').trim().toLowerCase();
+  if (!h) return false;
+  if (h.startsWith('[')) return /^\[[0-9a-f:.]+\](:\d+)?$/.test(h);
+  const name = h.split(':')[0];
+  return name === 'localhost' || /^\d{1,3}(\.\d{1,3}){3}$/.test(name) || names.map((n) => String(n).toLowerCase()).includes(name);
+}
+
+// The request path without its query, or null when its escapes are broken.
+export function decodePath(rawUrl) {
+  try { return decodeURIComponent(String(rawUrl || '/').split('?')[0]); } catch { return null; }
+}
+
+// The file a request path names inside `dir`, or null when the path leaves it.
+export function resolveInside(dir, urlPath) {
+  const fp = path.normalize(path.join(dir, urlPath));
+  return fp === dir || fp.startsWith(dir + path.sep) ? fp : null;
+}
+
+export function send(res, status, body, headers = {}) {
+  res.writeHead(status, { ...headers, 'Content-Type': 'text/plain;charset=utf-8', 'Cache-Control': 'no-store' });
+  res.end(String(body));
+}
+
+// Read flags that never wait: a path that has turned into a FIFO opens at once and is then refused.
+export const READ_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0);
+
+// An open regular file: { fd, size }, or { status } when there is none (404) or it cannot be read (403).
+function openRegular(fp) {
+  let fd;
+  try { fd = fs.openSync(fp, READ_FLAGS); } catch (e) { return { status: ['ENOENT', 'ENOTDIR', 'EISDIR'].includes(e.code) ? 404 : 403 }; }
+  let st = null;
+  try { st = fs.fstatSync(fd); } catch { /* a status the system cannot give (EIO on a network drive) */ }
+  if (st && st.isFile()) return { fd, size: st.size };
+  fs.closeSync(fd);
+  return { status: st ? 404 : 403 };
+}
+
+// Sends the bytes `start`..`end` of an open file (what the headers declared, even if the file grows
+// meanwhile) and closes it, also when the browser drops the download midway (a pipe would keep the
+// file open). Nothing to send closes the file and ends the response.
+function stream(res, fp, { fd, start, end }) {
+  if (end < start) {
+    fs.closeSync(fd);
+    return void res.end();
+  }
+  pipeline(fs.createReadStream(fp, { fd, start, end }), res, () => {});
+}
+
+// A file, with byte ranges for video (smoother scrubbing). Never cached: a rebuilt page is fresh.
+// The file is opened before any header goes out, so one that cannot be read gets 403 instead of
+// ending the server.
+export function sendFile(req, res, fp, headers = {}) {
+  const f = openRegular(fp);
+  if (f.status) return send(res, f.status, String(f.status), headers);
+  const type = MIME[path.extname(fp).toLowerCase()] || 'application/octet-stream';
+  const base = { ...headers, 'Content-Type': type, 'Accept-Ranges': 'bytes', 'Cache-Control': 'no-store' };
+  const range = type.startsWith('video/') ? /bytes=(\d+)-(\d*)/.exec(req.headers.range || '') : null;
+  if (range) return sendRange(res, fp, f, range, base, headers);
+  res.writeHead(200, { ...base, 'Content-Length': f.size });
+  stream(res, fp, { fd: f.fd, start: 0, end: f.size - 1 });
+}
+
+function sendRange(res, fp, f, range, base, headers) {
+  const start = Number(range[1]);
+  const end = Math.min(range[2] ? Number(range[2]) : f.size - 1, f.size - 1);
+  if (start >= f.size || start > end) {
+    fs.closeSync(f.fd);
+    res.writeHead(416, { ...headers, 'Content-Range': `bytes */${f.size}` });
+    return void res.end();
+  }
+  res.writeHead(206, { ...base, 'Content-Range': `bytes ${start}-${end}/${f.size}`, 'Content-Length': end - start + 1 });
+  stream(res, fp, { fd: f.fd, start, end });
+}
+
+// True when the request was the PID question, which this answers.
+export function answersPid(urlPath, res) {
+  if (urlPath !== PID_ROUTE) return false;
+  res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+  res.end(JSON.stringify({ pid: process.pid }));
+  return true;
+}
+
+// Listens on `port` when given and free, else on a port the system picks. Resolves to the port.
+export function listen(server, { host = LOOPBACK, port } = {}) {
+  const attempt = (p) => new Promise((resolve, reject) => {
+    const onError = (e) => { server.off('listening', onListening); reject(e); };
+    const onListening = () => { server.off('error', onError); resolve(server.address().port); };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(p, host);
+  });
+  if (!port) return attempt(0);
+  return attempt(port).catch((e) => (e.code === 'EADDRINUSE' ? attempt(0) : Promise.reject(e)));
+}
+
+// The address a person opens: localhost for loopback and the wildcard, IPv6 in brackets.
+export function urlFor(host, port) {
+  if (!host || host === LOOPBACK || host === '0.0.0.0') return `http://localhost:${port}/`;
+  if (host === '::' || host === '::1') return `http://[::1]:${port}/`;
+  return host.includes(':') ? `http://[${host}]:${port}/` : `http://${host}:${port}/`;
+}
+
+// Where a stop asks a server for its PID: the address it was bound to, a wildcard at loopback.
+export function askHost(host) {
+  if (!host || host === '0.0.0.0') return LOOPBACK;
+  return host === '::' ? '::1' : host;
+}
+/**
+ * Whether the server a state file records answers a start that asks for `port`: one that asks no
+ * port, the port it listens on, or the port its own start asked for (busy then, so it got another).
+ */
+export const portMatches = (st, port) => !port || st.port === port || st.requestedPort === port;
+
+// The state file of a server for `dir`: beside the folder, so a deployed folder never carries it.
+export const siblingState = (dir) => path.join(path.dirname(dir), `${path.basename(dir)}.server.json`);
+
+export function writeState(file, info) {
+  fs.writeFileSync(file, JSON.stringify(info, null, 2) + '\n');
+}
+
+export function readState(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+export const removeState = (file) => fs.rmSync(file, { force: true });
+
+// Removes a state file if it can. One that cannot be removed (a folder made read-only) stays; the
+// next start finds it stale. Stopping and closing go on either way.
+function dropState(file) {
+  try { removeState(file); } catch { /* left behind */ }
+}
+
+// Removes the state file when the process recorded there is this one.
+export function forgetSelf(file) {
+  if (readState(file)?.pid === process.pid) dropState(file);
+}
+
+const NONE = Symbol('none');
+// The PID the server on `port` says it has; NONE when nothing listens; null for another program.
+function askPid(port, timeoutMs, host) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: askHost(host), port, path: PID_ROUTE, timeout: timeoutMs, headers: { Host: 'localhost' } }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => { try { resolve(JSON.parse(body).pid ?? null); } catch { resolve(null); } });
+    });
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.on('error', (e) => resolve(e.code === 'ECONNREFUSED' ? NONE : null));
+  });
+}
+
+const portOpen = (port, host) => new Promise((resolve) => {
+  const s = net.connect({ host: askHost(host), port }, () => { s.destroy(); resolve(true); });
+  s.on('error', () => resolve(false));
+});
+
+async function waitClosed(port, timeoutMs, host) {
+  for (const until = Date.now() + timeoutMs; Date.now() < until;) {
+    if (!(await portOpen(port, host))) return true;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return !(await portOpen(port, host));
+}
+
+// A PID a state file may name: a whole number above 1 (never a process group, never init).
+const validPid = (pid) => Number.isInteger(pid) && pid > 1;
+
+/** True when the server a state file records still answers on its port with its PID. */
+export async function isRunning(stateFile) {
+  const st = readState(stateFile);
+  return Boolean(st && st.port) && validPid(st.pid) && (await askPid(st.port, 1500, st.host)) === st.pid;
+}
+
+function signal(pid, sig) {
+  try { process.kill(pid, sig); } catch { /* already gone */ }
+}
+
+// Stops the server a state file records. Result reasons: stopped, no-state, invalid-state (a PID
+// that is no process id; the file is left for a person to look at), not-running (the stale record
+// is removed), other-process (left alone), still-open.
+export async function stopServer(stateFile, { timeoutMs = 3000 } = {}) {
+  const st = readState(stateFile);
+  if (!st || !st.port) return { stopped: false, reason: 'no-state' };
+  if (!validPid(st.pid)) return { stopped: false, reason: 'invalid-state' };
+  const who = await askPid(st.port, Math.min(timeoutMs, 1500), st.host);
+  if (who === NONE) {
+    dropState(stateFile);
+    return { stopped: false, reason: 'not-running' };
+  }
+  if (who !== st.pid) return { stopped: false, reason: 'other-process' };
+  if (!(await terminate(st, timeoutMs))) return { stopped: false, reason: 'still-open' };
+  dropState(stateFile);
+  return { stopped: true, reason: 'stopped' };
+}
+
+// Ends a server that answered with its PID: SIGTERM, then SIGKILL while its port stays open. True
+// once the port is closed.
+async function terminate(st, timeoutMs) {
+  signal(st.pid, 'SIGTERM');
+  if (await waitClosed(st.port, timeoutMs, st.host)) return true;
+  signal(st.pid, 'SIGKILL');
+  return waitClosed(st.port, timeoutMs, st.host);
+}

package/skills/motion-graphic-make/references/serve.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/*
+ * Local preview server for an assembled intro (index.html + scrub-engine.js + assets/), so the
+ * scroll-scrubbed page is checked in a real browser. The project convention is a self-contained
+ * local page on an unused port, never a claude.ai artifact. Shared by 3d-intro-build and
+ * motion-graphic-make (scripts/sync-adapter.js keeps the copies identical).
+ *
+ * Why a server at all: the engine loads each clip with fetch() into a Blob, which file:// cannot
+ * serve, and video plays smoother with byte ranges (206).
+ *
+ * Usage:
+ *   node serve.mjs [dir] [--port N] [--csp strict|"<policy>"] [--state file]
+ *   node serve.mjs --stop [dir] [--state file]
+ *     dir      folder to serve (default: the current one)
+ *     --port   preferred port; when busy or absent the system picks a free one
+ *     --csp    sends Content-Security-Policy on every response: `strict` (no inline script or
+ *              style; blob: media) or the production policy as written. Check a page for a site
+ *              with a CSP under that same policy: a plain server hides CSP errors.
+ *     --state  state file (default: <dir>.server.json beside the folder, never inside it)
+ *     --stop   ends the server the state file records, only when it answers with that PID
+ *   A start while the recorded server still answers with the same settings only reports its
+ *   address; with other settings (another folder sharing the --state file, --csp, PREVIEW_HOST, a
+ *   --port other than the one it listens on or its own start asked for) it exits 1: --stop first.
+ *   A request whose Host is a DNS name other than localhost is refused (DNS rebinding).
+ *   On listen it writes the state file and prints  PREVIEW http://localhost:<port>/
+ *   PREVIEW_HOST=0.0.0.0 binds every interface (on-device phone checks) and prints a warning.
+ *
+ * Runtime: Node >=18 builtins only. No shell, cross-platform.
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  LOOPBACK, answersPid, cspFrom, decodePath, forgetSelf, hostAllowed, hostWarning, isRunning, listen, portMatches, readState,
+  resolveInside, send, sendFile, siblingState, stopServer, urlFor, writeState,
+} from './preview-lib.mjs';
+
+function handler(dir, headers, host) {
+  return (req, res) => {
+    if (!hostAllowed(req.headers.host, [host])) return send(res, 403, 'host not allowed', headers);
+    if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, '405', headers);
+    const urlPath = decodePath(req.url);
+    if (urlPath === null) return send(res, 400, '400', headers);
+    if (answersPid(urlPath, res)) return;
+    const fp = resolveInside(dir, urlPath === '/' ? '/index.html' : urlPath);
+    if (!fp) return send(res, 403, '403', headers);
+    sendFile(req, res, fp, headers);
+  };
+}
+
+/**
+ * Serves `dir` until close(). Resolves to { server, port, host, url, stateFile, close }.
+ * @param {{ port?: number, host?: string, csp?: string, stateFile?: string }} opts
+ */
+export async function startServe(dir, { port, host = process.env.PREVIEW_HOST || LOOPBACK, csp, stateFile } = {}) {
+  const root = path.resolve(dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`serve: not a directory: ${root}`);
+  const policy = cspFrom(csp);
+  const server = http.createServer(handler(root, policy ? { 'Content-Security-Policy': policy } : {}, host));
+  const bound = await listen(server, { host, port });
+  const url = urlFor(host, bound);
+  const file = stateFile ? path.resolve(stateFile) : siblingState(root);
+  writeState(file, {
+    pid: process.pid, port: bound, requestedPort: port || null, host, url, dir: root, csp: policy, startedAt: new Date().toISOString(),
+  });
+  const close = () => new Promise((resolve) => { forgetSelf(file); server.close(() => resolve()); });
+  return { server, port: bound, host, url, stateFile: file, close };
+}
+
+function parseArgs(argv) {
+  const o = { dir: null, port: null, csp: null, state: null, stop: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const [key, inline] = a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, null];
+    const value = () => (inline !== null ? inline : argv[++i]);
+    if (key === '--port') o.port = Number(value());
+    else if (key === '--csp') o.csp = value();
+    else if (key === '--state') o.state = value();
+    else if (key === '--stop') o.stop = true;
+    else if (!a.startsWith('--')) o.dir = a;
+  }
+  return o;
+}
+
+// Nothing left running is a success; a port held by another program, or one that stays open, is not.
+async function stopMain(o, dir) {
+  const r = await stopServer(o.state ? path.resolve(o.state) : siblingState(dir));
+  console.log(`STOP ${r.reason}`);
+  process.exit(['stopped', 'not-running', 'no-state'].includes(r.reason) ? 0 : 1);
+}
+
+// Whether the recorded server answers this start: this folder, the same CSP and host, and the port
+// asked for. A state file shared through --state can record another folder's server.
+const sameSettings = (st, o, dir) => path.resolve(String(st.dir || '')) === dir && (st.csp || null) === cspFrom(o.csp)
+  && (st.host || LOOPBACK) === (process.env.PREVIEW_HOST || LOOPBACK) && portMatches(st, o.port);
+
+// A server already running for this state file: the same settings only report its address; other
+// settings (folder, CSP, host, port) never pass for it, so a check meant to run under a CSP cannot
+// run without one, and a page meant for one folder or port is not checked on another.
+async function reportRunning(recorded, o, dir) {
+  if (!(await isRunning(recorded))) return false;
+  const st = readState(recorded);
+  if (sameSettings(st, o, dir)) {
+    console.log(`PREVIEW ${st.url} (already running, pid ${st.pid})`);
+    return true;
+  }
+  console.error(`serve: the state file records a server running with different settings (folder: ${st.dir}, `
+    + `csp: ${st.csp ? 'on' : 'off'}, host: ${st.host}, port: ${st.port}); stop it with --stop and start again`);
+  process.exit(1);
+}
+
+async function main() {
+  const o = parseArgs(process.argv.slice(2));
+  const dir = path.resolve(o.dir || process.cwd());
+  if (o.stop) return stopMain(o, dir);
+  if (await reportRunning(o.state ? path.resolve(o.state) : siblingState(dir), o, dir)) return;
+  const s = await startServe(dir, { port: o.port || undefined, csp: o.csp || undefined, stateFile: o.state || undefined });
+  const warn = hostWarning(s.host);
+  if (warn) console.warn(warn);
+  console.log(`PREVIEW ${s.url}`);
+  console.log(`serving ${dir}${o.csp ? '  (with Content-Security-Policy)' : ''}  state: ${s.stateFile}`);
+  const quit = () => { forgetSelf(s.stateFile); s.server.close(); process.exit(0); };
+  process.on('SIGINT', quit);
+  process.on('SIGTERM', quit);
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  main().catch((e) => { console.error(String(e?.message || e)); process.exit(1); });
+}

package/skills/omc-patch/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: omc-patch
+description: "OMC 플러그인이 자동 업데이트된 뒤 사라진 훅 패치를 활성 버전에 다시 적용하고 OMC 마켓플레이스 자동 업데이트를 막음. 진단, 적용, 검증, 되돌리기. 'omc-patch'/'OMC 패치'/'OMC 업데이트 뒤 패치'/'훅 timed out'/'훅 프로세스 누적'/'PC 느려짐' 시 사용."
+argument-hint: "[check | revert]"
+---
+
+# omc-patch — OMC 훅 패치 재적용과 자동 업데이트 고정
+
+OMC(oh-my-claudecode)가 새 버전으로 자동 업데이트되면 로컬 훅 패치가 사라진다. 그러면 도구 호출마다 훅 프로세스가 많이 생기고, Windows 에서는 커널 풀(paged pool)이 계속 늘어 PC 가 느려진다.
+이 스킬은 같은 폴더의 `scripts/omc-patch.mjs` 로 패치를 다시 적용하고 결과를 검증한다. 답변은 한글.
+
+패치 내용은 두 가지다.
+- 훅 스크립트 최상위의 `await import(...)` 에 10초 시간 제한을 건다. 로드가 멈춰도 훅이 끝까지 가고 프로세스가 남지 않는다.
+- `hooks.json` 의 `PostToolUse` 훅을 제거한다.
+
+추가로 OMC 마켓플레이스 저장소의 `origin` 을 `omc-pinned://<원래 URL>` 로 바꿔 자동 업데이트를 막는다.
+
+## 인자
+
+| 인자 | 동작 |
+|---|---|
+| 없음 | 진단, 사용자 확인, 적용, 검증 |
+| `check` | 진단만. 아무것도 바꾸지 않음 |
+| `revert` | 패치와 고정을 되돌림. 사용자가 명시했을 때만 |
+
+## 규칙
+
+- 이 작업은 사용자 설정 폴더(`~/.claude`)의 플러그인 캐시를 고치는 설정 변경이다. 서브에이전트에 맡기지 않고 메인 세션에서 직접 실행하고 직접 검증한다.
+- 적용은 `--no-update` 로만 실행한다. 인자 없는 apply 는 쓰지 않는다. 활성 OMC 를 도구의 `TARGET_VERSION`(5.3.0)으로 내리고, `revert` 로도 버전이 돌아오지 않는다.
+- 도구가 출력하는 `인자 없이 다시 실행하십시오.` 문구는 따르지 않는다. 이 스킬에서는 항상 `--no-update` 를 붙인다.
+- 패치 규칙은 OMC 훅 코드의 모양에 맞춰져 있다. 처음 보는 OMC 버전이면 반드시 `check` 를 먼저 실행한다.
+- `실패 N건` 이 1건 이상이면 멈추고 출력을 그대로 보고한다. 문법 오류가 난 파일은 도구가 원본으로 자동 롤백한다.
+- 판정은 출력 문구로 한다. 종료 코드 0 만으로 완료라고 보고하지 않는다.
+- 캐시에는 정션이나 심볼릭 링크로 이어진 버전 폴더가 있을 수 있다(예: 옛 버전 폴더가 새 버전을 가리킴). 이때 한 번의 변경이 두 버전 폴더에 함께 보인다. 정상이다.
+- 도구는 `os.homedir()/.claude` 를 쓴다. `CLAUDE_CONFIG_DIR` 로 설정 폴더를 옮겼다면 이 도구는 그 폴더를 보지 않는다.
+- 출력의 origin 에 `https://사용자:토큰@...` 처럼 자격증명이 들어 있으면, 보고할 때 `//***@` 로 가린다. 출력을 그대로 보고하라는 단계에서도 이 가림은 지킨다. 그 URL 은 `PINNED` 에도 평문으로 남으니 사용자에게 알린다.
+
+## 절차
+
+스크립트 경로는 `<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs` 이다. Node 18 이상과 `git` 이 필요하다. 모든 명령은 OS 구분 없이 같다.
+
+### 1. 진단
+
+```bash
+node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --check --no-update
+```
+
+- `활성 버전: X (installed_plugins.json)` 줄로 실제 활성 버전을 확인한다.
+- 그 줄이 `(추정: ...)` 로 끝나면 도구가 `installed_plugins.json` 에서 활성 버전을 찾지 못한 것이다. 적용하지 않고 출력을 그대로 보고하고 끝낸다. 추정한 폴더를 패치하면 실제 활성 버전은 그대로 남는데 `check` 는 적용된 것으로 보일 수 있다.
+- `패치 필요 N건` 은 설치된 모든 버전 폴더를 합친 수다. 판정은 맨 아래 `결과:` 줄로 한다.
+- `결과: 모두 적용된 상태입니다.` 이면 4단계 검증으로 건너뛴다.
+- `참고: 비활성 버전 ...` 은 지금 쓰지 않는 버전이라 판정에 들어가지 않는다.
+- 인자가 `check` 이면 여기서 결과만 보고하고 끝낸다.
+
+### 2. 확인 (적용 전 필수)
+
+`--check` 결과를 보여 주고 사용자에게 적용해도 되는지 묻는다. 묻기 전에 아래를 알린다.
+- 활성 OMC 버전의 `scripts/*.mjs` 와 `hooks/hooks.json` 을 고친다. 원본은 `.omcbak` 로 남는다.
+- OMC 마켓플레이스 `origin` 을 `omc-pinned://` 로 바꾼다. OMC 가 더 이상 자동 업데이트되지 않는다. 되돌리기는 `revert`.
+- 승인이 없으면 적용하지 않는다.
+
+### 3. 적용
+
+```bash
+node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --no-update
+```
+
+- `패치 N건 / 실패 0건`, `[3/4]` 의 PostToolUse 제거, `[4/4]` 의 고정 결과를 확인한다.
+- 실패가 1건 이상이면 멈추고 출력 그대로 보고한다.
+
+### 4. 검증 (세 가지 모두)
+
+1. 다시 진단한다. `결과: 모두 적용된 상태입니다.` 가 나와야 한다.
+
+   ```bash
+   node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --check --no-update
+   ```
+
+2. 패치된 훅의 문법을 확인한다. `*.omcbak` 와 짝인 파일마다 `node --check` 를 실행하고 종료 코드 0 을 확인한다.
+
+   bash:
+   ```bash
+   R=$(node -e 'const j=require(require("path").join(require("os").homedir(),".claude/plugins/installed_plugins.json"));console.log(j.plugins["oh-my-claudecode@omc"][0].installPath)')
+   for b in "$R"/scripts/*.omcbak; do [ -e "$b" ] || continue; f="${b%.omcbak}"; node --check "$f"; rc=$?; echo "$(basename "$f") syntax=$rc"; done
+   ```
+
+   PowerShell:
+   ```powershell
+   $r = (Get-Content "$env:USERPROFILE\.claude\plugins\installed_plugins.json" -Raw | ConvertFrom-Json).plugins.'oh-my-claudecode@omc'[0].installPath
+   Get-ChildItem "$r\scripts\*.omcbak" | % { $f = $_.FullName -replace '\.omcbak$',''; node --check $f; "{0} syntax={1}" -f (Split-Path $f -Leaf), $LASTEXITCODE }
+   ```
+
+3. 패치된 훅 하나를 플러그인의 `scripts/run.cjs` 로 실제 실행한다. 명령마다 새 셸일 수 있으니 경로를 다시 구한다.
+   `OMC_NOTIFY=0` 은 이 시험 실행이 사용자의 알림 채널로 `session-idle` 알림을 보내지 않게 한다.
+
+   bash:
+   ```bash
+   R=$(node -e 'const j=require(require("path").join(require("os").homedir(),".claude/plugins/installed_plugins.json"));console.log(j.plugins["oh-my-claudecode@omc"][0].installPath)')
+   echo '{"session_id":"smoke-test","cwd":"/nonexistent","hook_event_name":"Stop"}' | CLAUDE_PLUGIN_ROOT="$R" OMC_NOTIFY=0 node "$R/scripts/run.cjs" "$R/scripts/persistent-mode.mjs"; echo "exit=$?"
+   ```
+
+   PowerShell:
+   ```powershell
+   $r = (Get-Content "$env:USERPROFILE\.claude\plugins\installed_plugins.json" -Raw | ConvertFrom-Json).plugins.'oh-my-claudecode@omc'[0].installPath
+   $env:CLAUDE_PLUGIN_ROOT = $r; $env:OMC_NOTIFY = '0'
+   '{"session_id":"smoke-test","cwd":"C:\\nonexistent","hook_event_name":"Stop"}' | node "$r\scripts\run.cjs" "$r\scripts\persistent-mode.mjs"; "exit=$LASTEXITCODE"
+   Remove-Item Env:CLAUDE_PLUGIN_ROOT, Env:OMC_NOTIFY
+   ```
+
+   `{"continue":true,...}` 형태의 출력과 종료 코드 0 이면 정상. 훅 이름이 없으면 `*.omcbak` 와 짝인 다른 훅으로 바꾼다.
+
+4. 마켓플레이스 고정을 확인한다. `omc-pinned://` 로 시작하면 고정된 것이다.
+
+   ```bash
+   git -C "$HOME/.claude/plugins/marketplaces/omc" remote get-url origin
+   ```
+
+   PowerShell 에서는 `$HOME` 대신 `$env:USERPROFILE` 을 쓴다.
+
+### 5. 보고
+
+- 활성 버전, 패치 건수, PostToolUse 제거 목록, 고정 상태
+- 훅 스크립트 패치는 바로 적용된다. 훅이 호출될 때마다 파일을 새로 읽기 때문이다.
+- PostToolUse 제거는 `hooks.json` 변경이라 각 세션을 다시 시작해야 적용된다.
+- Windows 에서 이미 쌓인 커널 풀은 재부팅으로만 회수된다. 재부팅은 사용자가 직접 한다.
+
+## 되돌리기 (인자 `revert`)
+
+```bash
+node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --revert
+```
+
+- `.omcbak` 백업으로 훅 스크립트와 `hooks.json` 을 되돌리고 마켓플레이스 `origin` 을 원래 URL 로 복구한다.
+- 되돌린 뒤 Claude Code 를 다시 시작해야 반영된다.
+- `이 도구가 만들지 않은 수정이 남아 있습니다` 가 나오면 백업이 없는 손 수정이다. 출력에 적힌 복구 명령을 그대로 보고하고, 사용자 승인 없이 실행하지 않는다.
+
+## 함정
+
+- 도구의 `TARGET_VERSION`(5.3.0)은 소스에 고정돼 있다. 인자 없는 apply 만 이 값을 쓰고, 이 스킬은 그 apply 를 쓰지 않는다.
+- OMC 가 훅 코드 구조를 바꾸면 패치 대상이 0건으로 나오거나 변환이 실패할 수 있다. 이때 `실패 N건` 과 `변환 실패` 를 그대로 보고한다.
+- 고정을 풀지 않고 OMC 를 올리려면 먼저 `revert` 한다. 그렇지 않으면 마켓플레이스 fetch 가 계속 실패한다.
+- 고정 기록(`PINNED`)은 `~/.claude/omc-local-patches/PINNED` 에 생긴다. 기록일 뿐이라 지워도 고정은 풀리지 않고, 이미 고정된 상태에서는 다시 만들어지지 않는다. `revert` 는 origin 값에서 원래 URL 을 되찾는다.
+- 도구의 주석과 출력 문구는 한글이다.