@kaydash9999/banker-plugins 0.20.2 → 0.21.0

package/skills/3d-intro-build/references/curate.mjs

@@ -64,10 +64,28 @@ const MEDIA = /\.(png|jpe?g|webp|gif|mp4|webm|mov)$/i;
 function linkRefusal(dir, fp) {
   let real;
   try { real = fs.realpathSync(fp); } catch { return null; }
+  return realRefusal(dir, real);
+}
+
+function realRefusal(dir, real) {
   if (!real.startsWith(fs.realpathSync(dir) + path.sep)) return '링크가 프로젝트 폴더 밖을 가리켜 보이지 않습니다.';
   return MEDIA.test(real) ? null : '링크가 이미지나 영상이 아닌 파일을 가리켜 보이지 않습니다.';
 }
 
+// What a listed path may be served as: { dev, ino } (BigInt) of the file its links lead to, taken without
+// following a link, so a link put in its place after this check is not that file. null when there is
+// no such file, or its links leave the project or end at a file that is not an image or a video.
+function servedFile(dir, fp) {
+  try {
+    const real = fs.realpathSync(fp);
+    if (realRefusal(dir, real)) return null;
+    const st = fs.lstatSync(real, { bigint: true });
+    return { dev: st.dev, ino: st.ino };
+  } catch {
+    return null;
+  }
+}
+
 // Why a listed file is neither shown nor served nor hashed, or null when it may be: it must be an
 // image or a video inside the project, by its path and by where its links lead, so a key file or
 // a record listed by mistake never leaves the folder.
@@ -103,9 +121,11 @@ export function readDecisions(dir) {
 }
 
 // Written whole or not at all: a crash mid-write leaves the previous file.
+// The temp name is random and opened exclusively: a link a repository put at a guessable name is never written through.
 function writeJson(file, value) {
-  fs.writeFileSync(`${file}.tmp`, JSON.stringify(value, null, 2) + '\n');
-  fs.renameSync(`${file}.tmp`, file);
+  const tmp = `${file}.${crypto.randomBytes(8).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { flag: 'wx' });
+  try { fs.renameSync(tmp, file); } catch (e) { fs.rmSync(tmp, { force: true }); throw e; }
 }
 
 const writeDecisions = (dir, all) => writeJson(path.join(dir, DECISIONS), all);
@@ -247,20 +267,26 @@ export function archiveRejected(dir, { now = new Date() } = {}) {
 // path turns into one after the first check).
 const hashes = new Map();
 const notRegular = () => new Error('일반 파일 아님');
+// A file changed within this long of a hash may change again in the same timestamp step (2 s on FAT):
+// its hash is not kept, so the next view reads it again.
+const RACY_MS = 3000n;
+const keyOf = (fp, st) => `${fp}:${st.dev}:${st.ino}:${st.size}:${st.mtimeNs}:${st.ctimeNs}`;
+const racy = (st, startedNs) => startedNs - (st.ctimeNs > st.mtimeNs ? st.ctimeNs : st.mtimeNs) < RACY_MS * 1_000_000n;
 export async function hashFile(fp) {
   if (!(await fs.promises.stat(fp)).isFile()) throw notRegular();
   const fh = await fs.promises.open(fp, READ_FLAGS);
   let done;
   try {
-    const st = await fh.stat();
+    const startedNs = BigInt(Date.now()) * 1_000_000n;
+    const st = await fh.stat({ bigint: true });
     if (!st.isFile()) throw notRegular();
-    const key = `${fp}:${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`;
+    const key = keyOf(fp, st);
     done = hashes.get(key);
     if (done) return done;
-    done = sha256Of(fh, st.size);
-    done.catch(() => hashes.delete(key));
+    done = sha256Of(fh, Number(st.size));
     hashes.set(key, done);
     await done.catch(() => {});
+    if (racy(st, startedNs) || !(await done.then(() => true, () => false))) hashes.delete(key);
   } finally {
     await fh.close();
   }
@@ -287,7 +313,10 @@ async function hashText(dir, file) {
 
 // The hash text of every listed take by file, four files at a time per call (a long list must not
 // run out of file handles), before the page is drawn.
-async function takeHashes(input, dir) {
+// A take not hashed within waitMs shows that its read goes on; the next view shows its hash.
+const HASH_WAIT_MS = 5000;
+const STILL_READING = '읽는 중(새로 고치면 보임)';
+async function takeHashes(input, dir, waitMs = HASH_WAIT_MS) {
   const files = [...new Set(input.scenes.flatMap((s) => s.takes.map((t) => t.file)))];
   const out = new Map();
   let next = 0;
@@ -297,8 +326,12 @@ async function takeHashes(input, dir) {
       out.set(f, await hashText(dir, f));
     }
   };
-  await Promise.all(Array.from({ length: Math.min(4, files.length) }, worker));
-  return out;
+  const all = Promise.all(Array.from({ length: Math.min(4, files.length) }, worker));
+  let timer;
+  const late = new Promise((resolve) => { timer = setTimeout(resolve, waitMs); });
+  await Promise.race([all, late]);
+  clearTimeout(timer);
+  return new Map(files.map((f) => [f, out.has(f) ? out.get(f) : STILL_READING]));
 }
 
 function media(t, dir) {
@@ -366,11 +399,11 @@ function summary(input, entries) {
 }
 
 /** The review page for `input`. Resolves once every listed take is hashed. */
-export async function renderPage(input, decisions, { dir }) {
+export async function renderPage(input, decisions, { dir, hashWaitMs }) {
   const stage = decisions[input.stage] || { scenes: [] };
   const entries = new Map(stage.scenes.map((e) => [e.id, { ...e, rejected: e.rejected || [] }]));
   const promptLabel = input.promptLabel || (INSTRUCTION_STAGES.has(input.stage) ? '구성 지시문' : '프롬프트');
-  const ctx = { dir, promptLabel, entries, hashes: await takeHashes(input, dir) };
+  const ctx = { dir, promptLabel, entries, hashes: await takeHashes(input, dir, hashWaitMs) };
   const body = input.scenes.map((s, i) => sceneBlock(s, i, ctx)).join('\n') || '<p class="empty">curate-input.json 에 장면이 없습니다.</p>';
   return `<!doctype html>
 <html lang="ko"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
@@ -505,8 +538,9 @@ async function page(dir, res) {
 function serveListed(dir, req, res, urlPath) {
   const fp = resolveInside(dir, urlPath);
   if (!fp) return send(res, 403, '403');
-  if (!listedFiles(dir).has(fp) || linkRefusal(dir, fp)) return send(res, 404, '404');
-  sendFile(req, res, fp);
+  const expect = listedFiles(dir).has(fp) ? servedFile(dir, fp) : null;
+  if (!expect) return send(res, 404, '404');
+  sendFile(req, res, fp, {}, { expect });
 }
 
 function route(dir, req, res, urlPath) {
@@ -546,7 +580,7 @@ export async function startCurate(dir, { port, host = process.env.PREVIEW_HOST |
 // Starts hashing the listed takes, so the first view of the page does not wait for a large render.
 // An input that cannot be read hashes nothing here; the page reports it.
 function warmHashes(dir) {
-  try { return takeHashes(readInput(dir), dir).catch(() => new Map()); } catch { return Promise.resolve(new Map()); }
+  try { return takeHashes(readInput(dir), dir, 2 ** 31 - 1).catch(() => new Map()); } catch { return Promise.resolve(new Map()); }
 }
 
 // ---- CLI ------------------------------------------------------------------------

package/skills/3d-intro-build/references/preview-lib.mjs

@@ -16,11 +16,13 @@
  *
  * Runtime: Node >=18 builtins only (node:fs / node:http / node:net / node:path). No shell.
  */
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import http from 'node:http';
 import net from 'node:net';
+import os from 'node:os';
 import path from 'node:path';
-import { pipeline } from 'node:stream';
+import { Transform, 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.
@@ -80,39 +82,57 @@ export function send(res, status, body, headers = {}) {
 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) {
+// With `expect` ({ dev, ino } of the file a check passed, as BigInt), another file at the path is none:
+// the path changed between that check and this open. BigInt, since an NTFS file id is 64 bits and a
+// Number keeps only 53: two files could read as one.
+function openRegular(fp, expect) {
   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 };
+  try { st = fs.fstatSync(fd, { bigint: true }); } catch { /* a status the system cannot give (EIO on a network drive) */ }
+  if (st && st.isFile() && sameFile(st, expect)) return { fd, size: Number(st.size) };
   fs.closeSync(fd);
   return { status: st ? 404 : 403 };
 }
 
+const sameFile = (st, expect) => !expect || (st.dev === expect.dev && st.ino === expect.ino);
+
 // 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) {
+// A HEAD request gets the headers only: the file is closed unread.
+function stream(res, fp, { fd, start, end, head }) {
+  if (head || end < start) {
     fs.closeSync(fd);
     return void res.end();
   }
-  pipeline(fs.createReadStream(fp, { fd, start, end }), res, () => {});
+  pipeline(fs.createReadStream(fp, { fd, start, end }), declaredLength(end - start + 1), res, () => {});
+}
+
+// Passes the bytes on and fails at the end when they were fewer than the headers declared (the file
+// shrank since): the pipeline then destroys the response, which closes the connection. Ended as
+// usual, it would leave the browser waiting on a kept-alive connection for bytes that never come.
+function declaredLength(want) {
+  let sent = 0;
+  return new Transform({
+    transform(chunk, _enc, done) { sent += chunk.length; done(null, chunk); },
+    flush(done) { done(sent < want ? new Error('the file is shorter than its declared length') : null); },
+  });
 }
 
 // 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);
+// ending the server. `expect` ({ dev, ino }) names the only file that may go out (404 otherwise).
+export function sendFile(req, res, fp, headers = {}, { expect } = {}) {
+  const f = openRegular(fp, expect);
   if (f.status) return send(res, f.status, String(f.status), headers);
+  f.head = req.method === 'HEAD';
   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 });
+  stream(res, fp, { fd: f.fd, start: 0, end: f.size - 1, head: f.head });
 }
 
 function sendRange(res, fp, f, range, base, headers) {
@@ -124,7 +144,7 @@ function sendRange(res, fp, f, range, base, headers) {
     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 });
+  stream(res, fp, { fd: f.fd, start, end, head: f.head });
 }
 
 // True when the request was the PID question, which this answers.
@@ -169,8 +189,12 @@ export const portMatches = (st, port) => !port || st.port === port || st.request
 // 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`);
 
+// Through a fresh random name opened exclusively, then renamed over the old file: a link at the state
+// file's name (one a repository can bring) is replaced, never written through.
 export function writeState(file, info) {
-  fs.writeFileSync(file, JSON.stringify(info, null, 2) + '\n');
+  const tmp = `${file}.${crypto.randomBytes(8).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(info, null, 2) + '\n', { flag: 'wx' });
+  try { fs.renameSync(tmp, file); } catch (e) { fs.rmSync(tmp, { force: true }); throw e; }
 }
 
 export function readState(file) {
@@ -220,10 +244,22 @@ async function waitClosed(port, timeoutMs, 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;
 
+// A host a state file may name: this machine (loopback, a wildcard, an address of its own). A state file
+// can come with a repository: its host must not send a request elsewhere, nor pick the PID a signal goes to.
+// A record a stop or a start may act on: a PID that is a process id, on this machine.
+const recordedHere = (st) => validPid(st.pid) && thisMachine(st.host);
+
+// No host is the default loopback one. A loopback address counts only as an IPv4 address of 127/8: `127.evil.test`
+// or `127.256.0.1` is a DNS name, resolved anywhere (a resolver's search domain may answer it).
+export function thisMachine(host) {
+  if (!host || ['0.0.0.0', '::', '::1', 'localhost'].includes(host) || (net.isIPv4(String(host)) && String(host).startsWith('127.'))) return true;
+  return Object.values(os.networkInterfaces()).flat().some((a) => a && a.address === host);
+}
+
 /** 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;
+  return Boolean(st && st.port) && recordedHere(st) && (await askPid(st.port, 1500, st.host)) === st.pid;
 }
 
 function signal(pid, sig) {
@@ -236,7 +272,7 @@ function signal(pid, sig) {
 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' };
+  if (!recordedHere(st)) return { stopped: false, reason: 'invalid-state' };
   const who = await askPid(st.port, Math.min(timeoutMs, 1500), st.host);
   if (who === NONE) {
     dropState(stateFile);

package/skills/3d-intro-build/references/prompts.md

@@ -80,7 +80,7 @@ Subject: [SCENE.subject — 미니어처 장면을 묘사: 건물/공간, 일하
 
 - `size` = `ORIENTATION` (`720x1280` 세로 / `1280x720` 가로). Sora 크기와 반드시 일치시킨다.
 - `quality` = `low`(미리보기·저렴) 또는 `high`(최종).
-- **N3 주의:** v1 경로가 실패해 classic 폴백이 뜨면 반환 크기가 `1024x1536`(2:3)라 `720x1280` 이 아니다. `createVideo` 에 넣기 전에 Sora 크기로 리사이즈(ffmpeg `scale`)하거나 재생성한다. v1 경로(`720x1280`)가 검증된 happy path 다.
+- **N3 주의:** v1 경로가 실패해 classic 폴백이 뜨면 반환 크기가 `1024x1536`(2:3)라 `720x1280` 이 아니다. 영상 씨앗(`generateClip` 의 `firstFramePng`)으로 쓰기 전에 ORIENTATION 크기로 리사이즈(ffmpeg `scale`)하거나 재생성한다. v1 경로(`720x1280`)가 검증된 happy path 다.
 
 ### FLUX 코히전 옵트인 (`generateImageFlux` / FLUX.2-pro)
 
@@ -90,14 +90,14 @@ Subject: [SCENE.subject — 미니어처 장면을 묘사: 건물/공간, 일하
 
 ---
 
-## 4. Fly-through — forward-chaining leg 프롬프트 (`Sora-2`, `createVideo`)
+## 4. Fly-through — forward-chaining leg 프롬프트 (`generateClip`: WAN 키 풀이 먼저, 쓸 수 있는 키가 없으면 `Sora-2`)
 
 Azure `/videos` 는 `input_reference` 를 **딱 하나만** 받는다(두-이미지는 400).
 그래서 연속성은 **forward-chaining** 으로 만든다: 이전 클립의 **실제 마지막 프레임**을 다음 클립의 `input_reference` 로 넣는다.
 아래 굵은 절이 **모션 핸드오프 계약**이다 — 글자 그대로 유지하고, 씬별 표현은 가운데 MOVE 슬롯에 넣는다.
 
 **Leg 0 (씨앗) — 씬 1 스틸에서 dive-in:**
-`input_reference = 씬 1 스틸`.
+`firstFramePng = 씬 1 스틸`.
 
 ```
 Single continuous cinematic camera move, no cuts. Begin high and far, looking down at the
@@ -142,7 +142,7 @@ tilt. It only travels straight and level, the world sliding past beneath the sam
 잔잔한 전진 활공의 한 컷으로 읽혀야 한다(옆으로 흐르는 모션블러·완결 안 된 오빗 금지).
 아니면 그 leg 를 재생성한다 — 나쁜 핸드오프 프레임 하나가 뒤의 모든 leg 를 오염시킨다.
 
-어댑터 인자: `model: 'sora-2'`, `size: ORIENTATION`, `seconds`(기본 4; 예산·길이에 따라 조정).
+`generateClip` 인자: `size: ORIENTATION`, `seconds`(기본 5. WAN 은 정수 2~30초, Sora 로 폴백되면 4, 8, 12초 중 가장 가까운 값), `firstFramePng`. 모델과 provider 순서는 키 파일(`WAN_MODEL`, `AZURE_SORA_DEPLOYMENT`, `VIDEO_PROVIDER_ORDER`)이 정한다. `createVideo` 를 직접 부르지 않는다. 키 풀, 폴백, 이중 과금 방지를 건너뛴다(SKILL.md Step 4).
 
 ---
 

package/skills/3d-intro-build/references/serve.mjs

@@ -95,6 +95,9 @@ async function stopMain(o, dir) {
 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 value in one quoted piece, with "?" for what a reader takes for a line end or what changes how text shows.
+const oneLine = (v) => JSON.stringify(String(v)).replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '?');
+
 // 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.
@@ -105,7 +108,9 @@ async function reportRunning(recorded, 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}, `
+  // the folder in one quoted piece, and as "?" what a reader takes for a line end or what changes how text shows (a
+  // line or paragraph separator, NEL, a bidi override, a tag character): none of it adds a line to what an agent reads
+  console.error(`serve: the state file records a server running with different settings (folder: ${oneLine(st.dir)}, `
     + `csp: ${st.csp ? 'on' : 'off'}, host: ${st.host}, port: ${st.port}); stop it with --stop and start again`);
   process.exit(1);
 }

package/skills/3d-intro-build/references/verify-intro.mjs

@@ -18,7 +18,7 @@
  *        [--viewports 1280x800,390x844t] [--no-input] [--no-contrast] [--playwright-from-project]
  *     --viewports  a trailing t marks a touch screen, r reduced motion (default: the six below)
  *     --header     the site's fixed header (default: the engine's .sw-topbar)
- *     --playwright-from-project  also look in the current folder's node_modules, first (your own project only)
+ *     --playwright-from-project  also look in the current folder's node_modules, before the global npm root (your own project only)
  *   Exit 0 when nothing failed, 1 otherwise; the report (JSON) goes to --out or stdout.
  *
  * Needs Playwright with Chromium (setup-playwright skill: npx playwright install chromium), found
@@ -138,17 +138,24 @@ function globalRoot() {
   return String(r.stdout || '').trim();
 }
 
+// The playwright entry outside this script's folder: the project's when asked, else the global root's.
+function outsideEntry(fromProject) {
+  const fromHere = fromProject ? resolveFrom(process.cwd()) : null;
+  if (fromHere) return fromHere;
+  const root = globalRoot();
+  return root ? resolveFrom(root) : null;
+}
+
 /**
- * The playwright package: beside this script, else in the global npm root. The project's own
- * node_modules (the current folder) is read only with `fromProject` (--playwright-from-project), and
- * then first: a repository can ship a node_modules of its own, and loading it runs its code.
+ * The playwright package: beside this script (or in a folder above it), else in the global npm root.
+ * The project's own node_modules (the current folder) is read only with `fromProject`
+ * (--playwright-from-project), and then before the global root: a repository can ship a node_modules
+ * of its own, and loading it runs its code. `importBeside` replaces the first import (tests).
  * `npx playwright install chromium` alone fetches the browser, not this package.
  */
-export async function loadPlaywright({ fromProject = false } = {}) {
-  try { return await import('playwright'); } catch { /* not beside this script */ }
-  const fromHere = fromProject ? resolveFrom(process.cwd()) : null;
-  const root = fromHere ? null : globalRoot();
-  const entry = fromHere || (root && resolveFrom(root));
+export async function loadPlaywright({ fromProject = false, importBeside = () => import('playwright') } = {}) {
+  try { return await importBeside(); } catch { /* not beside this script */ }
+  const entry = outsideEntry(fromProject);
   if (entry) {
     const mod = await import(pathToFileURL(entry).href);
     return mod.chromium ? mod : mod.default;