@kaydash9999/banker-plugins 0.23.3 → 0.24.1

package/skills/init-dir/scripts/marker-block.mjs

@@ -0,0 +1,321 @@
+/**
+ * marker-block: puts one marked block of lines into a text file, replaces it or takes it out, and leaves every
+ * byte outside the block as it was.
+ *
+ * The canonical copy is skills/init-dir/scripts/marker-block.mjs. tune-tmux and git-init carry byte-identical
+ * copies, since Codex installs every skill folder on its own; scripts/sync-adapter.js mirrors and checks them.
+ * Edit the canonical copy only.
+ *
+ * Policy (one place for every skill that edits a user's file):
+ * - Markers are whole lines `<open> <id>:start <close>` and `<open> <id>:end <close>`, with the comment syntax
+ *   given (`#` or `<!-- -->`). A marker inside a sentence, an unpaired marker, an end before a start or a second
+ *   block is refused: nothing is cut on a guess.
+ * - Bytes outside the block stay as they were. CRLF files get CRLF blocks, a byte order mark stays in front.
+ *   A file that is not UTF-8 is refused.
+ * - A folder, FIFO, socket or device at the name is refused without being read.
+ * - A symbolic link is refused (refused: "symlink") unless followSymlink is set; then the file it leads to is
+ *   written and the link stays a link. A link to nothing is refused either way ("dangling").
+ * - A file with two or more hard links is refused ("hardlink"): the rename below would split them.
+ * - A file owned by another user is refused ("owner"). The permission bits of the file carry over to the new
+ *   file. Windows has no owner or permission bits to check.
+ * - Writes go to a temp file in the same folder and a rename. A failed write removes the temp file.
+ * - When the bytes change, the first original is kept in `<file>.<skill>.bak`; an existing backup is never
+ *   overwritten.
+ *
+ * Results are { ok, changed, refused?, message, path, file }. Callers map refused to exit status 1.
+ */
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+/** Comment syntaxes. */
+export const HTML = Object.freeze({ open: "<!--", close: "-->" });
+export const HASH = Object.freeze({ open: "#", close: "" });
+
+const BOM = "\u{FEFF}";
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const MAX_BYTES = 32 * 1024 * 1024;
+const NEW_FILE_MODE = 0o644;
+const BACKUP_MODE = 0o600;
+
+/** The start and end marker lines for id in a comment syntax. */
+export function markers(comment, id) {
+  const tail = comment.close ? ` ${comment.close}` : "";
+  return { start: `${comment.open} ${id}:start${tail}`, end: `${comment.open} ${id}:end${tail}` };
+}
+
+const refusal = (code, message, path) => ({ ok: false, changed: false, refused: code, message, path });
+const bare = (line) => line.replace(/\r?\n$/, "").replace(/[ \t]+$/, "");
+const eolOf = (text) => (text.includes("\r\n") ? "\r\n" : "\n");
+const readlinkOr = (path) => {
+  try {
+    return readlinkSync(path);
+  } catch {
+    return "?";
+  }
+};
+const nativeReal = (path) => {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return resolve(path);
+  }
+};
+const realOrNull = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return null;
+  }
+};
+
+// Where the bytes live: the path itself, or with followSymlink the file a link leads to.
+function locate(path, follow) {
+  const lst = lstatSync(path, { throwIfNoEntry: false });
+  if (!lst) return { file: path, exists: false };
+  if (!lst.isSymbolicLink()) return { file: path, exists: true };
+  const target = readlinkOr(path);
+  if (!follow) return { refuse: refusal("symlink", `심볼릭 링크라 그대로 둠: ${path} -> ${target}`, path) };
+  const real = realOrNull(path);
+  if (real === null) return { refuse: refusal("dangling", `끊어진 링크라 그대로 둠: ${path} -> ${target}`, path) };
+  return { file: real, exists: true, link: path };
+}
+
+// Why the file at file may not be read or replaced, or null.
+function fileProblem(st, file, uid) {
+  if (!st.isFile()) return refusal("special", `일반 파일이 아니라 그대로 둠: ${file}`, file);
+  if (st.nlink > 1) return refusal("hardlink", `하드 링크가 ${st.nlink}개라 그대로 둠: ${file}`, file);
+  if (uid !== undefined && st.uid !== uid) return refusal("owner", `다른 사용자 소유라 그대로 둠: ${file}`, file);
+  if (st.size > MAX_BYTES) return refusal("too-big", `32MiB 보다 커서 그대로 둠: ${file}`, file);
+  return null;
+}
+
+// The file's stat and bytes, opened without blocking so a FIFO planted after the look never waits. id: the same
+// file's bigint stat for telling files apart (an NTFS file id passes 2^53, so as a Number two files can share one).
+function readChecked(file, uid) {
+  const first = statSync(file);
+  const problem = fileProblem(first, file, uid);
+  if (problem) return { refuse: problem };
+  const fd = openSync(file, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+  try {
+    const st = fstatSync(fd);
+    const late = fileProblem(st, file, uid);
+    return late ? { refuse: late } : { st, id: fstatSync(fd, { bigint: true }), bytes: readFileSync(fd) };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// What one line is: "start", "end", "inline" (a marker inside other text) or null.
+function kindOf(line, mk) {
+  const b = bare(line);
+  if (b === mk.start) return "start";
+  if (b === mk.end) return "end";
+  return line.includes(mk.start) || line.includes(mk.end) ? "inline" : null;
+}
+
+// Takes line i of kind into state; returns why the markers are broken, or null.
+function step(state, kind, i) {
+  if (kind === "inline") return `문장 안에 표지가 있음(${i + 1}행)`;
+  if (kind === "start") {
+    if (state.open !== -1 || state.found) return `표지 짝이 맞지 않거나 블록이 둘 이상(${i + 1}행)`;
+    state.open = i;
+  } else if (kind === "end") {
+    if (state.open === -1) return `끝 표지가 시작 표지보다 먼저(${i + 1}행)`;
+    state.found = { first: state.open, last: i };
+    state.open = -1;
+  }
+  return null;
+}
+
+/** The block's first and last line in lines, null when there is none, or { error } when markers are broken. */
+export function findBlock(lines, mk) {
+  const state = { open: -1, found: null };
+  for (let i = 0; i < lines.length; i++) {
+    const error = step(state, kindOf(lines[i], mk), i);
+    if (error) return { error };
+  }
+  if (state.open !== -1) return { error: `짝 없는 시작 표지(${state.open + 1}행)` };
+  return state.found;
+}
+
+// Whether line i sits inside an open wrap region (more wrap opens than closes before it).
+function insideWrap(lines, i, wrap) {
+  let depth = 0;
+  for (let j = 0; j < i; j++) {
+    const b = bare(lines[j]);
+    if (b === wrap.open) depth++;
+    else if (b === wrap.close && depth > 0) depth--;
+  }
+  return depth > 0;
+}
+
+// The span [first, last] widened to wrap lines directly around it, and whether new text must bring its own wrap.
+function spanOf(lines, found, wrap) {
+  if (!wrap) return { ...found, wrapNew: false };
+  const wrapped = found.first > 0 && bare(lines[found.first - 1]) === wrap.open && bare(lines[found.last + 1] ?? "") === wrap.close;
+  if (wrapped) return { first: found.first - 1, last: found.last + 1, wrapNew: true };
+  return { ...found, wrapNew: !insideWrap(lines, found.first, wrap) };
+}
+
+const blockText = (mk, body, wrap, eol) => {
+  const inner = [mk.start, ...body.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n"), mk.end];
+  return [...(wrap ? [wrap.open, ...inner, wrap.close] : inner), ""].join(eol);
+};
+
+// The text with the block put in, replaced or (body null) taken out. Appending puts one line break between the
+// text and the block; taking a block out at the end of the file takes that break back, so add then remove gives
+// the bytes from before.
+function render(text, found, o) {
+  const lines = text.split(/(?<=\n)/);
+  const eol = eolOf(text);
+  if (!found) {
+    if (o.body === null) return text;
+    return text === "" ? blockText(o.mk, o.body, o.wrap, eol) : text + eol + blockText(o.mk, o.body, o.wrap, eol);
+  }
+  const span = spanOf(lines, found, o.wrap);
+  const before = lines.slice(0, span.first).join("");
+  const after = lines.slice(span.last + 1).join("");
+  if (o.body !== null) return before + blockText(o.mk, o.body, span.wrapNew ? o.wrap : null, eol) + after;
+  return after === "" ? before.replace(/\r?\n$/, "") : before + after;
+}
+
+function checkBody(o) {
+  if (o.body === null) return;
+  const forbidden = [o.mk.start, o.mk.end, ...(o.wrap ? [o.wrap.open, o.wrap.close] : [])];
+  if (o.body.split(/\r?\n/).some((line) => forbidden.includes(bare(line)))) throw new Error("block body holds a marker line");
+}
+
+// The new bytes for the old ones, or { refuse } when the old ones may not be edited.
+function nextBytes(bytes, o, file) {
+  let text;
+  try {
+    text = UTF8.decode(bytes);
+  } catch {
+    return { refuse: refusal("encoding", `UTF-8 이 아니라 그대로 둠: ${file}`, file) };
+  }
+  const bom = text.startsWith(BOM) ? BOM : "";
+  const plain = text.slice(bom.length);
+  const found = findBlock(plain.split(/(?<=\n)/), o.mk);
+  if (found?.error) return { refuse: refusal("markers", `표지 손상이라 그대로 둠: ${file}: ${found.error}`, file) };
+  return { bytes: Buffer.from(bom + render(plain, found, o), "utf8") };
+}
+
+const options = (opts) => ({
+  mk: markers(opts.comment, opts.id),
+  body: opts.body ?? null,
+  wrap: opts.wrap ?? null,
+  skill: opts.skill,
+  follow: opts.followSymlink === true,
+  uid: "uid" in opts ? opts.uid : process.getuid?.(),
+});
+
+/**
+ * Works out what applyBlock would write, without writing: { ok, changed, refused?, message, path, file, key,
+ * before, after, mode }. key names the file (device and inode, or the path of a file not there yet).
+ */
+export function planBlock(path, opts) {
+  const o = options(opts);
+  checkBody(o);
+  const at = locate(path, o.follow);
+  if (at.refuse) return at.refuse;
+  if (!at.exists) {
+    const after = o.body === null ? null : Buffer.from(blockText(o.mk, o.body, o.wrap, "\n"), "utf8");
+    return { ok: true, changed: after !== null, path, file: at.file, key: `path:${resolve(at.file)}`, before: null, after, mode: NEW_FILE_MODE };
+  }
+  const read = readChecked(at.file, o.uid);
+  if (read.refuse) return read.refuse;
+  const next = nextBytes(read.bytes, o, at.file);
+  if (next.refuse) return next.refuse;
+  const changed = !next.bytes.equals(read.bytes);
+  // ino 0 (a file system without file ids) tells nothing apart: then the path as the file system spells it is the
+  // key (realpathSync.native gives one spelling for names that differ only in case where case is ignored).
+  const key = read.id.ino === 0n ? `path:${nativeReal(at.file)}` : `ino:${read.id.dev}:${read.id.ino}`;
+  return { ok: true, changed, path, file: at.file, key, before: read.bytes, after: next.bytes, mode: read.st.mode & 0o7777 };
+}
+
+// Writes data to a fresh temp file beside file and renames it over file.
+function writeAtomic(file, data, mode) {
+  const tmp = join(dirname(file), `.${basename(file)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+  let fd = openSync(tmp, "wx", mode);
+  try {
+    writeFileSync(fd, data);
+    closeSync(fd);
+    fd = null;
+    if (process.platform !== "win32") chmodSync(tmp, mode);
+    renameSync(tmp, file);
+  } catch (e) {
+    if (fd !== null) closeSync(fd);
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+// Keeps the first original: writes <file>.<skill>.bak only when nothing is at that name yet.
+function backup(file, skill, bytes) {
+  const bak = `${file}.${skill}.bak`;
+  if (lstatSync(bak, { throwIfNoEntry: false })) return null;
+  const fd = openSync(bak, "wx", BACKUP_MODE);
+  try {
+    writeFileSync(fd, bytes);
+  } finally {
+    closeSync(fd);
+  }
+  return bak;
+}
+
+/** Writes what planBlock worked out. A plan that changes nothing or was refused is returned as a result. */
+export function commitBlock(plan, skill) {
+  if (!plan.ok) return plan;
+  const result = { ok: true, changed: plan.changed, path: plan.path, file: plan.file };
+  if (!plan.changed) return { ...result, message: `변경 없음: ${plan.path}` };
+  if (plan.before === null && plan.after !== null) {
+    const fd = openSync(plan.file, "wx", plan.mode);
+    try {
+      writeFileSync(fd, plan.after);
+    } finally {
+      closeSync(fd);
+    }
+    return { ...result, created: true, message: `새로 만듦: ${plan.path}` };
+  }
+  const bak = backup(plan.file, skill, plan.before);
+  writeAtomic(plan.file, plan.after, plan.mode);
+  return { ...result, backup: bak, message: `바꿈: ${plan.path}` };
+}
+
+/** Puts in, replaces or (body null) takes out the block in one file. dryRun plans only. */
+export function applyBlock(path, opts) {
+  const plan = planBlock(path, opts);
+  if (opts.dryRun || !plan.ok) return plan;
+  return commitBlock(plan, opts.skill);
+}
+
+/**
+ * Applies blocks to several files, each entry { path, ...opts }. Every file is planned first: one refusal and
+ * none is written. Two entries naming one file (after links are followed) write it once, by the first entry.
+ */
+export function applyBlocks(entries, { dryRun = false } = {}) {
+  const plans = entries.map((e) => ({ entry: e, plan: planBlock(e.path, e) }));
+  const refused = plans.filter((p) => !p.plan.ok).map((p) => p.plan);
+  if (refused.length > 0) return { ok: false, refused, results: plans.map((p) => p.plan) };
+  const seen = new Map();
+  const results = plans.map(({ entry, plan }) => {
+    if (seen.has(plan.key)) return { ok: true, changed: false, path: plan.path, file: plan.file, sameAs: seen.get(plan.key), message: `같은 파일이라 한 번만 씀: ${plan.path}` };
+    seen.set(plan.key, plan.path);
+    return dryRun ? plan : commitBlock(plan, entry.skill);
+  });
+  return { ok: true, refused: [], results };
+}

package/skills/init-dir/scripts/templates.mjs

@@ -0,0 +1,100 @@
+/**
+ * templates: the folders init-dir manages, the purpose of each, and the template files a newly made folder gets.
+ *
+ * The template sources live in ../templates/<folder>/. A few are renamed on the way out: gitignore becomes
+ * .gitignore (a real .gitignore in the skill would apply to the skill folder itself and is dropped by npm).
+ * .cmd files are written with CRLF line ends, .sh files with LF and mode 0755. Files are created with "wx", so
+ * an existing file is never overwritten.
+ */
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The managed folders, in the order they are listed. */
+export const FOLDERS = ["logs", "scripts", "work", "mockup", "tests", "docs", "KB"];
+
+/** One line per folder: what it is for and the rule to keep. */
+export const PURPOSES = {
+  logs: "서비스 로그. 표준 출력은 `<이름>.out.log`, 표준 오류는 `<이름>.err.log` 로 나눠 저장. 100MB 마다 로테이션, 스트림마다 현재 파일 포함 최대 7개",
+  scripts:
+    "서비스 관리 스크립트. `./scripts/start.sh`, `./scripts/stop.sh`, `./scripts/status.sh`, `./scripts/restart.sh` 로 실행(Windows 는 같은 이름의 `.cmd`). 실행할 명령은 `scripts/service.conf` 의 `command=`",
+  work: "사용자와 상호작용하는 작업공간. 사용자가 코딩 에이전트에게 전달할 파일을 여기에 둠. 비밀값 금지",
+  mockup: "목업 파일을 관리하는 공간",
+  tests:
+    "단위 시험(`tests/unit/`)과 통합 시험(`tests/integration/`) 스크립트. `./tests/run.sh`(Windows `tests\\run.cmd`)가 스위트마다 한 줄로 결과를 간결하게 출력. 스위트 명령은 `tests/tests.conf`",
+  docs: "문서를 관리하는 영역. evidence와 ADR도 포함하여 보관한다.",
+  KB: "knowledge base. OMC 나 OMX 위키 밖에서 사용자가 알고 있어야 할 내용을 보관하는 2차 위키. 색인은 `KB/README.md`",
+};
+
+const TEMPLATE_DIR = fileURLToPath(new URL("../templates/", import.meta.url));
+const SCRIPT_NAMES = ["start", "stop", "status", "restart"];
+
+// What each folder gets: a source path under templates/<folder>/, or { to, from } to rename, or { to } for an
+// empty file.
+const FILES = {
+  logs: ["README.md", { from: "gitignore", to: ".gitignore" }],
+  scripts: [...SCRIPT_NAMES.map((n) => `${n}.sh`), ...SCRIPT_NAMES.map((n) => `${n}.cmd`), "service.conf", "lib/service.mjs", "README.md"],
+  work: ["README.md"],
+  mockup: ["README.md"],
+  tests: ["run.sh", "run.cmd", "run.mjs", "tests.conf", "README.md", { to: "unit/.gitkeep" }, { to: "integration/.gitkeep" }],
+  docs: ["README.md", { to: "evidence/.gitkeep" }, { to: "adr/.gitkeep" }],
+  KB: ["README.md"],
+};
+
+const crlf = (text) => text.replace(/\r?\n/g, "\r\n");
+const lf = (text) => text.replace(/\r\n/g, "\n");
+
+// The bytes a target file gets, line ends set by its kind.
+function contentOf(folder, spec) {
+  if (spec.from === undefined) return Buffer.alloc(0);
+  const text = readFileSync(join(TEMPLATE_DIR, folder, ...spec.from.split("/")), "utf8");
+  return Buffer.from(spec.to.endsWith(".cmd") ? crlf(text) : lf(text), "utf8");
+}
+
+/** The template files of folder: [{ rel, data, mode }], rel relative to the project root with "/" separators. */
+export function templateFiles(folder) {
+  const specs = FILES[folder];
+  if (!specs) throw new Error(`unknown folder: ${folder}`);
+  return specs.map((s) => {
+    const spec = typeof s === "string" ? { from: s, to: s } : s;
+    return { rel: `${folder}/${spec.to}`, data: contentOf(folder, spec), mode: spec.to.endsWith(".sh") ? 0o755 : 0o644 };
+  });
+}
+
+/**
+ * Writes the template files of folder into dest (by default root/folder), never over an existing file. Returns the
+ * rel paths written. opts.failAt=<rel> makes it throw right after writing that file (a failure midway, for tests).
+ */
+export function writeTemplates(root, folder, dest = join(root, folder), opts = {}) {
+  const written = [];
+  for (const f of templateFiles(folder)) {
+    const path = join(dest, ...f.rel.split("/").slice(1));
+    mkdirSync(dirname(path), { recursive: true });
+    const fd = openSync(path, "wx", f.mode);
+    try {
+      writeFileSync(fd, f.data);
+    } finally {
+      closeSync(fd);
+    }
+    if (process.platform !== "win32") chmodSync(path, f.mode);
+    written.push(f.rel);
+    if (opts.failAt === f.rel) throw new Error(`주입한 실패: ${f.rel}`);
+  }
+  return written;
+}
+
+/** The summary lines for the folders present, in FOLDERS order. */
+export function summaryLines(present) {
+  return FOLDERS.filter((f) => present.includes(f)).map((f) => `- \`${f}/\`: ${PURPOSES[f]}`);
+}
+
+/** The instructions-file block body: the same bytes for the same folders present. */
+export function blockBody(present) {
+  return [
+    "## 프로젝트 폴더 (banker init-dir)",
+    "",
+    "이 프로젝트의 관리 폴더와 목적. 해당하는 파일은 그 폴더에 둔다. 이 블록은 init-dir 이 다시 쓴다(직접 고치지 않음).",
+    "",
+    ...summaryLines(present),
+  ].join("\n");
+}

package/skills/init-dir/templates/KB/README.md

@@ -0,0 +1,15 @@
+# KB
+
+knowledge base. OMC 나 OMX 위키 밖에서 사용자가 알고 있어야 할 내용을 두는 2차 위키. banker init-dir 이 만든 틀이다.
+
+- 대상: 사용자가 직접 읽고 판단해야 하는 내용(운영 연락처 위치, 업무 규칙, 외부 시스템 사용법, 반복되는 결정의 배경)
+- 에이전트용 지식은 OMC 위키(`.omc/wiki`)나 OMX 위키(`omx_wiki/`)에 둔다. 같은 내용을 두 곳에 쓰지 않는다
+- 비밀값을 적지 않는다
+
+## 색인 규칙
+
+- 페이지 하나에 주제 하나. 파일 이름은 `<주제>.md`(소문자, 하이픈)
+- 새 페이지를 만들면 아래 색인에 한 줄을 더한다: `- [제목](파일.md): 한 줄 요약`
+- 페이지 첫 줄은 `# 제목`, 둘째 단락에 마지막 확인 날짜
+
+## 색인

package/skills/init-dir/templates/docs/README.md

@@ -0,0 +1,14 @@
+# docs
+
+프로젝트 문서를 관리하는 폴더. evidence 와 ADR 도 여기에 보관한다. banker init-dir 이 만든 틀이다.
+
+| 폴더 | 둘 것 |
+|---|---|
+| `docs/` | 설계, 사용법, 운영 절차 문서 |
+| `docs/evidence/` | evidence. 구현한 기능이 동작함을 다른 사람이 확인할 수 있는 근거(시험 출력, 실행 기록, 화면 캡처, 측정 결과) |
+| `docs/adr/` | ADR(Architecture Decision Record). 결정 하나에 파일 하나. 맥락, 선택지, 결론과 그 이유 |
+
+- 문서 하나에 주제 하나. 파일 이름은 주제를 드러내게 짓는다
+- evidence 는 무엇을 언제 어떻게 확인했는지 남긴다(예: `2026-11-01-login-e2e.md`). 지어낸 결과를 쓰지 않는다
+- ADR 파일 이름은 번호와 주제(예: `0001-db-choice.md`). 결정을 뒤집으면 새 ADR 을 쓰고, 옛 ADR 에 대체한 ADR 번호를 적는다
+- banker progress-mon 의 ADR 탭은 이 폴더의 ADR 과 evidence 를 결정과 증거의 근거 출처로 참조한다

package/skills/init-dir/templates/logs/README.md

@@ -0,0 +1,14 @@
+# logs
+
+서비스 로그 폴더. banker init-dir 이 만든 틀이다.
+
+- 서비스마다 표준 출력과 표준 오류를 나눠 저장
+  - `<이름>.out.log`: 표준 출력
+  - `<이름>.err.log`: 표준 오류
+- 로테이션: 쓰기 전에 "현재 크기 + 쓸 양" 이 100MB 를 넘으면 돌림
+  - `<이름>.out.log` 가 `<이름>.out.1.log` 로, `.1` 이 `.2` 로 밀림
+  - 현재 파일 포함 스트림마다 최대 7개. 가장 오래된 `.6` 은 지움
+  - 스트림당 최대 700MB
+- `<이름>.pid`: 실행 중인 감독과 자식의 PID
+- 로그를 쓰는 도구: `./scripts/start.sh`(Windows `scripts\start.cmd`)
+- 이 폴더의 로그는 git 에 올리지 않음(`.gitignore`)

package/skills/init-dir/templates/logs/gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!README.md

package/skills/init-dir/templates/mockup/README.md

@@ -0,0 +1,7 @@
+# mockup
+
+목업 파일을 관리하는 폴더. banker init-dir 이 만든 틀이다.
+
+- 화면 목업, 와이어프레임, 시안 이미지, 정적 HTML 목업을 둔다
+- 파일 이름에 화면 이름과 판을 적는다(예: `login-v2.html`)
+- 승인된 목업은 문서(`docs/`)나 구현 이슈에서 이 경로로 가리킨다

package/skills/init-dir/templates/scripts/README.md

@@ -0,0 +1,39 @@
+# scripts
+
+서비스 관리 스크립트. banker init-dir 이 만든 틀이다.
+
+| 명령 | Windows | 하는 일 |
+|---|---|---|
+| `./scripts/start.sh` | `scripts\start.cmd` | `service.conf` 의 `command` 를 감독 프로세스로 시작 |
+| `./scripts/stop.sh` | `scripts\stop.cmd` | 서비스와 감독 프로세스를 멈춤 |
+| `./scripts/status.sh` | `scripts\status.cmd` | 감독과 자식의 실행 여부, 로그 크기를 따로 보고 |
+| `./scripts/restart.sh` | `scripts\restart.cmd` | stop 뒤 start |
+
+- 설정: `service.conf` 의 `name=`(기본 `app`), `command=`(한 줄)
+- 로그: `logs/<name>.out.log`(표준 출력), `logs/<name>.err.log`(표준 오류). 100MB 마다 로테이션, 스트림마다 현재 파일 포함 최대 7개
+- PID 파일: `logs/<name>.pid`(감독 PID, 자식 PID, 시작 시각, 자식 명령)
+- 필요: Node 18 이상. 없으면 종료 3. 다른 Node 를 쓰려면 환경 변수 `NODE` 에 경로
+- 종료 코드: 0 성공, 1 실패(시작 2초 안에 멈춤, 멈추지 못함, status 에서 실행 중이 아님), 2 설정 없음, 3 Node 없음
+
+## 동작
+
+- `start` 는 분리된 감독 프로세스를 띄운다. 감독이 `command` 를 자식으로 실행하고 출력을 로그 파일에 쓴다
+- `stop` 은 감독에 SIGTERM 을 보낸다. 감독이 자식의 프로세스 그룹에 넘기고, 10초 뒤에도 살아 있으면 강제로 끝낸다. Windows 는 `taskkill /T`, 10초 뒤 `taskkill /T /F`
+- 감독이 죽으면 자식은 다음 출력 때 SIGPIPE 로 죽을 수 있다. `status` 는 감독과 자식을 따로 보고한다. 감독 없이 자식만 남았으면 `stop` 이 자식을 끝낸다
+- Windows 는 감독이 죽으면 셸(cmd.exe)도 함께 끝나고, 셸이 띄운 프로그램은 남는다. 부모가 기록된 셸 PID 이고 명령줄에 `command=` 가 들어 있으면 그 프로그램을 자식으로 보고 `status`, `stop` 이 다룬다
+- PID 파일의 PID 는 확인한 뒤에만 이 서비스로 본다. 시작 시각이 마지막 부팅보다 이르면 낡은 파일이다. 명령줄에 `service.mjs` 와 `__supervise`(감독) 또는 기록된 `command`(자식)가 없으면 다른 프로세스다. 명령줄은 Linux 는 `/proc/<pid>/cmdline` 다음 `ps`, 그 밖의 POSIX 는 `ps`, Windows 는 PowerShell `Get-CimInstance` 로 읽는다. 다른 프로세스로 판정한 PID 에는 신호를 보내지 않고 사유를 출력한다
+- 살아 있는 PID 의 명령줄을 끝내 읽지 못하면(`/proc` 도 `ps` 도 없음) start, stop, status, restart 는 `확인 불가: <사유>` 와 종료 1. 신호를 보내지 않고 PID 파일을 남긴다
+- `start` 를 동시에 여러 번 실행해도 감독은 하나만 뜬다. `start` 는 `logs/<name>.start.lock` 을 새 파일로만 만들어(자기 PID 와 시각을 씀) 잡고, 끝나면 지운다. 잠금이 있으면 최대 `SERVICE_START_CHECK_MS` + 5초 기다린 뒤 이어서 진행하므로 나중 실행은 `이미 실행 중` 을 보고한다
+- 잠금의 PID 가 죽었거나 다른 프로그램이거나, 잠금이 30초 + `SERVICE_START_CHECK_MS` 보다 오래되면 낡은 잠금으로 보고 지운 뒤 다시 잡는다
+- 낡은 잠금은 한 번에 `start` 하나만 지운다. `logs/<name>.start.lock.break` 를 새 파일로만 만든 `start` 가 잠금을 다시 읽어, 낡다고 본 그 잠금일 때만 지운다. 그 사이 다른 `start` 가 새로 잡은 잠금은 지우지 않는다. `.break` 가 5초 넘게 남으면 다음 `start` 가 지운다. 정리는 보통 수 ms 라 정리하던 `start` 가 죽었거나 멈춘 것으로 본다
+- Windows 에서 지우는 중인 잠금이나 `.break` 가 내는 EPERM, EACCES, EBUSY 는 실패가 아니라 바쁨으로 보고 다시 시도한다(기다림 상한은 같다)
+- 잠금이나 `.break` 자리에 링크나 폴더가 있으면 거부하고 종료 1
+- 로테이션이 실패하면(Windows 에서 다른 프로그램이 로그를 연 경우 등) 표준 오류 로그에 `service:` 경고 한 줄을 쓰고 현재 파일에 이어 쓴다
+
+## 조정용 환경 변수
+
+| 변수 | 기본 | 뜻 |
+|---|---|---|
+| `SERVICE_LOG_ROTATE_BYTES` | 104857600 | 로테이션 기준 바이트 |
+| `SERVICE_STOP_GRACE_MS` | 10000 | 강제 종료 전 기다리는 시간 |
+| `SERVICE_START_CHECK_MS` | 2000 | 시작 뒤 살아 있는지 확인하기까지 기다리는 시간. 시작 잠금의 대기와 낡음 기준도 이만큼 늘어남 |