@kaydash9999/banker-plugins 0.16.3 → 0.17.0

package/skills/ultra-chain/references/chain-report.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+// Process view for /banker:ultra-chain. Renders a run folder's ledger (run.json, events.jsonl, task.md) into
+// one self-contained index.html in that folder: the stage timeline, review verdicts, the OS test matrix, the
+// visual board (mock beside actual), the human checklist and the artifacts. No script and no external
+// resource: every text is escaped and links go only to files inside the run folder.
+//
+//   node chain-report.mjs <run> [--out <file name>]
+//
+// Exit codes: 0 written, 1 the ledger could not be read or the page not written, 2 usage.
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { STAGES, readEvents, readRun, runPath, summarize } from "./chain-ledger.mjs";
+
+const STATUS_LABEL = {
+  pending: "대기", started: "진행 중", done: "완료", failed: "실패", skipped: "건너뜀", stopped: "멈춤", note: "기록",
+  running: "진행 중", pass: "통과", fail: "실패", unverified: "미검증", revise: "고칠 것",
+};
+const LABEL = Object.fromEntries(STAGES.map((s) => [s.id, s.label]));
+
+export const esc = (v) => String(v ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+// A link inside the run folder, or null. Each path segment is percent-encoded.
+export function href(p) {
+  const rel = runPath(p);
+  return rel ? `./${rel.split("/").map(encodeURIComponent).join("/")}` : null;
+}
+
+// A link only to a file the run folder holds (`ctx.exists`); a folder, a missing file or a note such as
+// "02-spec.md AC-10" stays words, so no link on the page is dead.
+const linkable = (p, ctx) => Boolean(href(p)) && ctx.exists(runPath(p));
+const link = (p, text, ctx) => (linkable(p, ctx) ? `<a href="${esc(href(p))}">${esc(text ?? p)}</a>` : esc(text ?? p ?? ""));
+
+export function duration(ms) {
+  if (ms === null || ms === undefined) return "";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}초`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}분 ${s % 60}초`;
+  return `${Math.floor(m / 60)}시간 ${m % 60}분`;
+}
+
+const pad = (n) => String(n).padStart(2, "0");
+export function when(iso) {
+  const d = new Date(iso);
+  if (!iso || Number.isNaN(d.getTime())) return "";
+  return `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+const badge = (status) => `<span class="s s-${esc(status)}">${esc(STATUS_LABEL[status] ?? status)}</span>`;
+
+function table(head, rows) {
+  if (!rows.length) return '<p class="none">없음</p>';
+  const th = head.map((h) => `<th>${esc(h)}</th>`).join("");
+  return `<table><thead><tr>${th}</tr></thead><tbody>${rows.map((r) => `<tr>${r.join("")}</tr>`).join("\n")}</tbody></table>`;
+}
+
+const td = (html, cls) => `<td${cls ? ` class="${cls}"` : ""}>${html}</td>`;
+
+// ── sections ─────────────────────────────────────────────────────────────────
+
+// task.md's first line is the argument line as given and the rest the task: with no flags the two say the
+// same, so the second is left out.
+export function taskText(task) {
+  const lines = String(task).split(/\r?\n/);
+  return lines.length > 1 && lines[1].trim() && lines[1].trim() === lines[0].trim() ? [lines[0], ...lines.slice(2)].join("\n") : String(task);
+}
+
+function renderHeader(run, task, sum, generatedAt) {
+  const total = sum.stages.reduce((a, s) => a + (s.ms ?? 0), 0);
+  const current = sum.current ? `${esc(LABEL[sum.current])} 단계` : "모든 단계 끝";
+  const facts = [
+    ["실행", esc(run.id)], ["상태", `${badge(sum.overall)} ${current}`], ["시작", esc(when(run.createdAt))],
+    ["단계 시간 합", esc(duration(total))], ["런타임", esc(run.runtime ?? "미상")],
+    ["기준 커밋", esc((run.baseCommit ?? "").slice(0, 12))], ["브랜치", esc(run.branch ?? "")], ["보고서 생성", esc(when(generatedAt))],
+  ];
+  const dl = facts.map(([k, v]) => `<div><dt>${esc(k)}</dt><dd>${v}</dd></div>`).join("");
+  const ask = task ? `<pre class="task">${esc(taskText(task))}</pre>` : '<p class="none">task.md 없음</p>';
+  return `<header><h1>ultra-chain 과정</h1><dl class="facts">${dl}</dl><h2>요청</h2>${ask}</header>`;
+}
+
+function renderTimeline(stages) {
+  const rows = stages.map((s, i) => [td(String(i)), td(esc(s.label)), td(badge(s.status)), td(esc(when(s.start))), td(esc(when(s.end))),
+    td(esc(duration(s.ms))), td(s.rounds ? String(s.rounds) : ""), td(esc(s.summary ?? ""), "wrap")]);
+  return `<section><h2>단계</h2>${table(["#", "단계", "상태", "시작", "끝", "걸린 시간", "회차", "요약"], rows)}</section>`;
+}
+
+// A verdict word keeps its own text; only the color says pass (APPROVE, PASS), revise (ITERATE) or fail.
+const VERDICT_TONE = { APPROVE: "pass", PASS: "pass", ITERATE: "revise" };
+const verdictBadge = (word) => `<span class="s s-${VERDICT_TONE[word] ?? "fail"}">${esc(word)}</span>`;
+
+function renderVerdict(e) {
+  const v = e.verdict;
+  const seats = (v.seats ?? []).map((s) => [td(esc(s.id)), td(esc(s.lens ?? "")), td(esc(s.model ?? "")), td(verdictBadge(s.verdict))]);
+  const blockers = v.blockers?.length ? `<ul>${v.blockers.map((b) => `<li>${esc(b)}</li>`).join("")}</ul>` : "";
+  const round = e.round ? ` ${e.round}회차` : "";
+  return `<article class="verdict"><h3>${esc(LABEL[e.stage])}${esc(round)}: ${esc(v.by)} ${verdictBadge(v.result)}</h3>`
+    + `${v.note ? `<p>${esc(v.note)}</p>` : ""}${seats.length ? table(["검토자", "관점", "모델", "판정"], seats) : ""}${blockers}</article>`;
+}
+
+function renderVerdicts(events) {
+  const list = events.filter((e) => e.verdict);
+  return `<section><h2>검토 판정</h2>${list.length ? list.map(renderVerdict).join("\n") : '<p class="none">없음</p>'}</section>`;
+}
+
+function renderTests(events, ctx) {
+  const rows = events.flatMap((e) => (e.tests ?? []).map((t) => [td(esc(`${LABEL[e.stage]}${e.round ? ` ${e.round}회차` : ""}`)),
+    td(esc(t.where)), td(esc(t.os ?? "")), td(badge(t.status)), td(esc([t.pass, t.fail, t.skipped].map((n) => n ?? "-").join(" / "))),
+    td(esc(t.note ?? ""), "wrap"), td(t.log && linkable(t.log, ctx) ? link(t.log, "로그", ctx) : "")]));
+  return `<section><h2>시험 (이 머신과 OS 박스)</h2>${table(["단계", "위치", "OS", "결과", "통과 / 실패 / 건너뜀", "비고", "로그"], rows)}</section>`;
+}
+
+// The latest entry per view name: a later visual check replaces an earlier one.
+function latestVisual(events) {
+  const byName = new Map();
+  for (const e of events) for (const v of e.visual ?? []) byName.set(v.name, v);
+  return [...byName.values()];
+}
+
+function renderShot(p, caption, ctx) {
+  const h = href(p);
+  if (!h || !ctx.exists(runPath(p))) return `<figure class="shot empty"><figcaption>${esc(caption)}: 없음</figcaption></figure>`;
+  return `<figure class="shot"><a href="${esc(h)}"><img src="${esc(h)}" alt="${esc(caption)}" loading="lazy"></a><figcaption>${esc(caption)}</figcaption></figure>`;
+}
+
+function renderVisual(events, ctx) {
+  const cards = latestVisual(events).map((v) => {
+    const score = v.score === undefined ? "" : ` ${v.score}점`;
+    const intended = v.intended ? ' <span class="s s-note">의도한 차이</span>' : "";
+    return `<article class="card"><h3>${esc(v.name)}${esc(score)} ${v.verdict ? badge(v.verdict) : ""}${intended}</h3>`
+      + `<div class="pair">${renderShot(v.mock, "목업", ctx)}${renderShot(v.actual, "실제", ctx)}</div>${v.note ? `<p>${esc(v.note)}</p>` : ""}</article>`;
+  });
+  return `<section><h2>시각 검토</h2>${cards.length ? cards.join("\n") : '<p class="none">없음</p>'}</section>`;
+}
+
+// One entry per item and what tells it apart: its ref, or its reason when it has no ref. The same words about
+// two views stay two entries; a bare repeat (no ref, no reason) of an item that has more adds nothing.
+const checkKey = (c) => (c.ref ? `ref:${c.ref}` : `why:${c.why ?? ""}`);
+
+export function checklistItems(events) {
+  const groups = new Map();
+  for (const e of events) {
+    for (const c of e.checklist ?? []) {
+      const g = groups.get(c.item) ?? new Map();
+      if (!g.has(checkKey(c))) g.set(checkKey(c), c);
+      groups.set(c.item, g);
+    }
+  }
+  return [...groups.values()].flatMap((g) => {
+    const full = [...g.entries()].filter(([key]) => key !== "why:").map(([, c]) => c);
+    return full.length ? full : [g.get("why:")];
+  });
+}
+
+// An item's ref: a link where it names a file of the run folder, else its own words.
+const refOf = (ref, ctx) => (linkable(ref, ctx) ? link(ref, "근거", ctx) : `<span class="why">근거: ${esc(ref)}</span>`);
+
+function renderChecklist(events, ctx) {
+  const items = checklistItems(events).map((c) => `<li><b>${esc(c.item)}</b>${c.why ? ` <span class="why">${esc(c.why)}</span>` : ""}${c.ref ? ` ${refOf(c.ref, ctx)}` : ""}</li>`);
+  return `<section class="check"><h2>사람이 볼 것 (${items.length})</h2>${items.length ? `<ol>${items.join("")}</ol>` : '<p class="none">없음</p>'}</section>`;
+}
+
+function renderArtifacts(events, ctx) {
+  const seen = new Map();
+  for (const e of events) for (const a of e.artifacts ?? []) if (!seen.has(a.path)) seen.set(a.path, { ...a, stage: e.stage });
+  const missing = (a) => (linkable(a.path, ctx) ? "" : ` <span class="why">(파일 아님: ${esc(a.path)})</span>`);
+  const rows = [...seen.values()].map((a) => [td(esc(LABEL[a.stage])), td(`${link(a.path, a.label ?? a.path, ctx)}${missing(a)}`)]);
+  return `<section><h2>산출물</h2>${table(["단계", "파일"], rows)}</section>`;
+}
+
+function renderLog(events, bad) {
+  const rows = events.map((e) => [td(esc(when(e.t))), td(esc(LABEL[e.stage])), td(badge(e.status)), td(Number.isInteger(e.round) ? String(e.round) : ""),
+    td(esc(e.summary ?? e.reason ?? ""), "wrap")]);
+  const warn = bad.length ? `<p class="warn">읽지 못한 기록 줄: ${esc(bad.join(", "))}</p>` : "";
+  return `<section><details><summary>전체 기록 (${events.length}줄)</summary>${warn}${table(["시각", "단계", "상태", "회차", "내용"], rows)}</details></section>`;
+}
+
+const CSS = `:root{color-scheme:light dark;--bg:#fff;--fg:#1d1d1f;--mute:#6e6e73;--line:#d2d2d7;--card:#f5f5f7}
+@media (prefers-color-scheme:dark){:root{--bg:#1c1c1e;--fg:#f5f5f7;--mute:#a1a1a6;--line:#3a3a3c;--card:#2c2c2e}}
+body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.55 system-ui,-apple-system,"Segoe UI","Noto Sans KR",sans-serif}
+main{max-width:1200px;margin:0 auto;padding:24px}h1{font-size:24px;margin:0 0 12px}h2{font-size:18px;margin:28px 0 10px}h3{font-size:15px;margin:8px 0}
+.facts{display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:8px;margin:0}.facts div{background:var(--card);border-radius:8px;padding:8px 10px}
+dt{color:var(--mute);font-size:12px}dd{margin:0}pre.task{white-space:pre-wrap;background:var(--card);border-radius:8px;padding:12px;margin:0}
+table{border-collapse:collapse;width:100%;font-size:14px}th,td{border-bottom:1px solid var(--line);padding:6px 8px;text-align:left;vertical-align:top}
+th{color:var(--mute);font-weight:600}td.wrap{white-space:pre-wrap;word-break:break-word}
+.s{display:inline-block;border-radius:999px;padding:1px 8px;font-size:12px;font-weight:600;background:var(--line)}
+.s-done,.s-pass{background:#d1f2dc;color:#0b6b2e}.s-started,.s-running{background:#d6e8ff;color:#0b4ea2}
+.s-failed,.s-fail,.s-stopped{background:#ffd9d6;color:#a1150b}.s-revise,.s-unverified{background:#ffefc7;color:#7a5200}
+.s-skipped,.s-pending,.s-note{background:var(--line);color:var(--mute)}
+.card,.verdict{background:var(--card);border-radius:10px;padding:10px 14px;margin:10px 0}
+.pair{display:grid;grid-template-columns:1fr 1fr;gap:12px}.shot{margin:0}.shot img{width:100%;height:auto;border:1px solid var(--line);border-radius:6px}
+figcaption{color:var(--mute);font-size:12px}.none{color:var(--mute)}.why{color:var(--mute)}.warn{color:#a1150b}
+.check ol{background:var(--card);border-radius:10px;padding:10px 10px 10px 34px}a{color:#0b63ce}`;
+
+// No script, plugin, form or base change may run in the page, whatever a ledger line holds.
+const CSP = "script-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+
+// The whole page. generatedAt is the time printed as "보고서 생성". exists(rel) says whether the run folder
+// holds that file; without it every path in the folder counts as one.
+export function renderReport({ run, task, events, bad = [], generatedAt = new Date().toISOString(), exists = () => true }) {
+  const sum = summarize(events);
+  const ctx = { exists };
+  const body = [renderHeader(run, task, sum, generatedAt), renderChecklist(events, ctx), renderTimeline(sum.stages), renderVerdicts(events),
+    renderTests(events, ctx), renderVisual(events, ctx), renderArtifacts(events, ctx), renderLog(events, bad)].join("\n");
+  return `<!doctype html>\n<html lang="ko"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">`
+    + `<meta http-equiv="Content-Security-Policy" content="${CSP}">`
+    + `<title>ultra-chain ${esc(run.id)}</title><style>${CSS}</style></head><body><main>\n${body}\n</main></body></html>\n`;
+}
+
+// ── command line ─────────────────────────────────────────────────────────────
+
+export function writeReport(dir, out = "index.html") {
+  if (!/^[\w.-]+\.html$/.test(out)) throw new Error(`--out 은 실행 폴더 안의 .html 파일 이름입니다: ${out}`);
+  const run = readRun(dir);
+  const { events, bad } = readEvents(dir);
+  const taskFile = join(dir, "task.md");
+  const task = existsSync(taskFile) ? readFileSync(taskFile, "utf8").slice(0, 8000) : null;
+  const file = join(dir, out);
+  const exists = (rel) => {
+    try {
+      return statSync(join(dir, rel)).isFile();
+    } catch {
+      return false;
+    }
+  };
+  writeFileSync(file, renderReport({ run, task, events, bad, exists }));
+  return file;
+}
+
+export function main(argv, out = process.stdout, err = process.stderr) {
+  const outAt = argv.indexOf("--out");
+  const name = outAt >= 0 ? argv[outAt + 1] : "index.html";
+  const rest = outAt >= 0 ? argv.filter((_, i) => i !== outAt && i !== outAt + 1) : argv;
+  if (rest.length !== 1 || !name) {
+    err.write("usage: node chain-report.mjs <run> [--out <file name>]\n");
+    return 2;
+  }
+  try {
+    out.write(`${writeReport(resolve(rest[0]), name)}\n`);
+    return 0;
+  } catch (e) {
+    err.write(`chain-report: ${e.message}\n`);
+    return 1;
+  }
+}
+
+// Run as a command, also when reached through a symlinked path: Node resolves
+// symlinks for import.meta.url but not for process.argv[1].
+const invokedDirectly = () => {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+};
+
+if (invokedDirectly()) process.exitCode = main(process.argv.slice(2));

package/skills/ultra-chain/references/preview-lib.mjs

@@ -0,0 +1,258 @@
+/*
+ * 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',
+  // Notes and logs a report links to open as text in the browser instead of downloading.
+  '.md': 'text/plain;charset=utf-8', '.txt': 'text/plain;charset=utf-8', '.log': 'text/plain;charset=utf-8', '.jsonl': 'text/plain;charset=utf-8',
+};
+
+// `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/ultra-chain/references/serve.mjs

@@ -0,0 +1,139 @@
+#!/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);
+}
+
+// Node resolves links for import.meta.url but not for process.argv[1], so both go through realpath:
+// compared as given, a run through a linked folder would exit 0 without doing anything.
+const invokedDirectly = () => {
+  try {
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+};
+if (invokedDirectly()) {
+  main().catch((e) => { console.error(String(e?.message || e)); process.exit(1); });
+}