@cheongfish/bouncer 0.0.0-stage → 0.1.10

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @cheongfish/bouncer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bouncer CLI runtime npm package입니다. `bouncer`와 `bouncer-root` 실행 파일,
+CommonJS runtime output인 `dist/`를 제공합니다. plugin은 별도 설치물이며
+runtime과 같은 version이어야 합니다.
+
+기본 설치는 전역입니다. registry에 공개된 plugin release와 같은 version을
+선택하세요.
+
+```bash
+npm install --global @cheongfish/bouncer@0.1.10
+```
+
+프로젝트 local 설치도 지원합니다. 일반 터미널은 `node_modules/.bin`의 shim을
+PATH에 추가할 수 있지만, plugin hook이 호스트 PATH를 상속하지 않는 환경에서는
+`BOUNCER_BIN`에 `node_modules/.bin/bouncer`의 절대 경로를 지정하세요.
+`npm config get bin-links`가 `false`이면 `npm config set bin-links true`로 바꾼 뒤
+runtime을 다시 설치해야 shim이 생성됩니다.
+
+```bash
+npm install --save-dev @cheongfish/bouncer@0.1.10
+```
+
+PowerShell은 local 설치의 `node_modules/.bin/bouncer.cmd`를, 전역 설치는 PATH에
+등록된 `bouncer.cmd`를 실행할 수 있습니다.
+
+저장소 checkout은 root에서 `npm ci` 후 `npm run build`로 이 workspace를
+빌드합니다. packed runtime에는 컴파일된 파일이 들어 있으므로 설치 중 source를
+빌드하지 않습니다.

package/bin/bouncer

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const packageRoot = path.join(__dirname, '..');
+const cliEntry = path.join(packageRoot, 'dist', 'cli.js');
+if (!fs.existsSync(cliEntry)) {
+  process.stderr.write(
+    `bouncer: packages/cli/dist is missing; run \`npm run build\` in ${path.join(packageRoot, '..', '..')}\n`,
+  );
+  process.exit(1);
+}
+
+// npm tarball에는 src가 없으므로 source hash 검사는 checkout에서만 수행한다.
+const sourceDir = path.join(packageRoot, 'src');
+if (fs.existsSync(sourceDir) && !require('./build-stamp').checkBuildFresh(packageRoot).ok) {
+  process.stderr.write(
+    `bouncer: stale-build: packages/cli/dist does not match packages/cli/src; `
+    + `run \`npm run build\` in ${path.join(packageRoot, '..', '..')}\n`,
+  );
+  process.exit(1);
+}
+
+const { runCli } = require('../dist/cli');
+process.exit(runCli(process.argv.slice(2)));

package/bin/bouncer-root

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const packageRoot = path.join(__dirname, '..');
+const rootEntry = path.join(packageRoot, 'dist', 'bouncer-root.js');
+if (!fs.existsSync(rootEntry)) {
+  process.stderr.write(
+    `bouncer: packages/cli/dist is missing; run \`npm run build\` in ${path.join(packageRoot, '..', '..')}\n`,
+  );
+  process.exit(1);
+}
+
+const sourceDir = path.join(packageRoot, 'src');
+if (fs.existsSync(sourceDir) && !require('./build-stamp').checkBuildFresh(packageRoot).ok) {
+  process.stderr.write(
+    `bouncer: stale-build: packages/cli/dist does not match packages/cli/src; `
+    + `run \`npm run build\` in ${path.join(packageRoot, '..', '..')}\n`,
+  );
+  process.exit(1);
+}
+
+const { runBouncerRoot } = require('../dist/bouncer-root');
+process.exit(runBouncerRoot(process.argv.slice(2)));

package/bin/build-stamp.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+'use strict';
+// 컴파일 산출물(dist)이 소스(src)와 어긋난 채 실행되는 것을 막는
+// plain JS helper. 이 검사를 scripts/src에 두면 검사 자체가 오래된 산출물로
+// 실행되므로 컴파일 대상 밖에 둔다.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STAMP_RELATIVE = path.join('dist', '.build-stamp');
+
+/**
+ * packages/cli/src 아래 .ts 파일을 posix 상대 경로로 모은다.
+ *
+ * @param {string} dir - 탐색할 디렉터리
+ * @param {string} rel - dir의 root 기준 posix 상대 경로
+ * @returns {string[]} root 기준 posix 상대 경로 목록
+ */
+function listTsFiles(dir, rel) {
+  const found = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const childRel = `${rel}/${entry.name}`;
+    if (entry.isDirectory()) found.push(...listTsFiles(path.join(dir, entry.name), childRel));
+    else if (entry.isFile() && entry.name.endsWith('.ts')) found.push(childRel);
+  }
+  return found;
+}
+
+/**
+ * 소스 트리 해시를 계산한다. scripts/src/**\/*.ts와 tsconfig.json을 정렬된
+ * 상대 경로 순으로 `<경로>\0<바이트>\0`씩 sha256에 넣는다. 줄바꿈은 정규화하지
+ * 않는다 — 바이트가 바뀌면 산출물도 달라질 수 있기 때문이다.
+ *
+ * @param {string} root - 저장소(플러그인) root
+ * @returns {string} `sha256:<64hex>`
+ */
+function computeSourceHash(root) {
+  const files = [...listTsFiles(path.join(root, 'src'), 'src'), 'tsconfig.json'].sort();
+  const hash = crypto.createHash('sha256');
+  for (const rel of files) {
+    hash.update(`${rel}\0`);
+    hash.update(fs.readFileSync(path.join(root, rel)));
+    hash.update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+/**
+ * 기록된 stamp를 읽는다. 파일이 없을 때만 null이고 다른 읽기 오류는 던진다.
+ *
+ * @param {string} root - 저장소(플러그인) root
+ * @returns {string|null} 개행을 뗀 stamp, 없으면 null
+ */
+function readStamp(root) {
+  try {
+    return fs.readFileSync(path.join(root, STAMP_RELATIVE), 'utf8').trim();
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/**
+ * 현재 소스 해시가 stamp와 같은지 판정한다.
+ *
+ * @param {string} root - 저장소(플러그인) root
+ * @returns {{ok: true} | {ok: false, reason: 'stale-build'}} stamp 부재도 stale이다
+ */
+function checkBuildFresh(root) {
+  return readStamp(root) === computeSourceHash(root) ? { ok: true } : { ok: false, reason: 'stale-build' };
+}
+
+if (require.main === module && process.argv[2] === '--write') {
+  const root = path.join(__dirname, '..');
+  fs.writeFileSync(path.join(root, STAMP_RELATIVE), `${computeSourceHash(root)}\n`);
+}
+
+module.exports = { computeSourceHash, readStamp, checkBuildFresh };

package/dist/.build-stamp

@@ -0,0 +1 @@
+sha256:7abe62097bbb29562f470a8e2eb46654e2dbf1cba03f5a19b9e01199371e2826

package/dist/approval-snapshot.js

@@ -0,0 +1,99 @@
+'use strict';
+const canonicalJsonMod = require("./canonical-json");
+const { sha256Canonical } = canonicalJsonMod;
+const guards = require("./guards");
+const { isRecord } = guards;
+const path = require('node:path');
+const tasksDocs = require("./tasks-docs");
+const { listTasksDocs } = tasksDocs;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const config = require("./config");
+const { readVerifyPolicy } = config;
+const paths = require("./paths");
+const { toPosix } = paths;
+function bouncerOf(data) {
+    if (!isRecord(data) || !isRecord(data.bouncer))
+        return {};
+    return data.bouncer;
+}
+/**
+ * tasks.md frontmatter에서 승인 범위에 넣는 세 필드만 고른다.
+ * verify는 원본 문자열만 쓴다 — `readVerifyCommand`의 config 폴백을 넣으면
+ * 문서가 안 바뀌었는데도 allowlist·기본 verify 변경이 task.verify 항목으로 위장된다.
+ *
+ * @param {{ rel: string, id: string | null }} entry - listTasksDocs 엔트리
+ * @param {string} repoRoot - 저장소 루트 절대 경로
+ * @returns {{ id: string, affected_paths: unknown, verify: string | null }} id순 정렬에 쓸 task 레코드
+ */
+function taskFromEntry(entry, repoRoot) {
+    const { data } = readDoc(path.join(repoRoot, entry.rel));
+    const bouncer = bouncerOf(data);
+    const id = typeof bouncer.id === 'string' && bouncer.id
+        ? bouncer.id
+        : (typeof entry.id === 'string' && entry.id ? entry.id : 'TASKS-unknown');
+    const affected_paths = Object.prototype.hasOwnProperty.call(bouncer, 'affected_paths')
+        ? bouncer.affected_paths
+        : [];
+    const verify = typeof bouncer.verify === 'string' ? bouncer.verify : null;
+    return { id, affected_paths, verify };
+}
+/**
+ * blueprint의 승인 digest와 항목별 digest를 계산한다.
+ * 게이트 G24와 `current --set`이 같은 hex를 써야 활성화 직후 대조가 어긋나지 않는다.
+ *
+ * @param {{ repoRoot: string, blueprintDir: string }} opts - 저장소 루트와 blueprint 상대 경로
+ * @returns {{ digest: string, parts: Record<string, string> }}
+ *   `digest`는 `{ tasks, verify_allowlist }`의 sha256Canonical.
+ *   `parts`는 `TASKS-NNN.affected_paths`·`TASKS-NNN.verify`·`verify_allowlist`·`tasks`(id 목록)별 digest
+ */
+function computeApprovalDigest({ repoRoot, blueprintDir }) {
+    const listing = listTasksDocs({ repoRoot, blueprintDir: toPosix(blueprintDir) });
+    const tasks = listing.entries
+        .map((entry) => taskFromEntry(entry, repoRoot))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const policy = readVerifyPolicy(repoRoot);
+    // invalid config는 기본 목록으로 넓히지 않는다. 파손된 allowlist를 통과시키면
+    // 운영자가 막은 명령이 승인 스냅샷에 실려 G24가 침묵한다.
+    const verify_allowlist = policy.ok === true ? [...policy.allowlist] : null;
+    const parts = {
+        tasks: sha256Canonical(tasks.map((task) => task.id)),
+        verify_allowlist: sha256Canonical(verify_allowlist),
+    };
+    for (const task of tasks) {
+        parts[`${task.id}.affected_paths`] = sha256Canonical(task.affected_paths);
+        parts[`${task.id}.verify`] = sha256Canonical(task.verify);
+    }
+    return {
+        digest: sha256Canonical({ tasks, verify_allowlist }),
+        parts,
+    };
+}
+const TASK_LEAF_RE = /^TASKS-\d{3}\.(affected_paths|verify)$/;
+/**
+ * 승인 파일 `parts`와 현재 `parts`에서 바뀐 항목 이름을 고른다.
+ * task 추가·삭제로만 생긴 `TASKS-NNN.*` 키는 `tasks` 항목으로 대표한다 —
+ * 같은 사건을 세 이름으로 나열하면 G24 메시지가 재승인 대상을 흐린다.
+ *
+ * @param {Record<string, string>} approved - 승인 파일의 parts
+ * @param {Record<string, string>} current - 지금 계산한 parts
+ * @returns {string[]} 사전순 항목 이름
+ */
+function diffApprovalParts(approved, current) {
+    const names = new Set([...Object.keys(approved), ...Object.keys(current)]);
+    const changed = [];
+    for (const name of [...names].sort()) {
+        if (approved[name] === current[name])
+            continue;
+        if (TASK_LEAF_RE.test(name)) {
+            if (Object.prototype.hasOwnProperty.call(approved, name)
+                && Object.prototype.hasOwnProperty.call(current, name)) {
+                changed.push(name);
+            }
+            continue;
+        }
+        changed.push(name);
+    }
+    return changed;
+}
+module.exports = { computeApprovalDigest, diffApprovalParts, sha256Canonical };

package/dist/bouncer-root.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBouncerRoot = runBouncerRoot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const plugin_root_1 = require("./plugin-root");
+function runBouncerRoot(argv, io = {}) {
+    const out = io.out ?? ((text) => process.stdout.write(text));
+    const err = io.err ?? ((text) => process.stderr.write(text));
+    let host;
+    let select = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        if (flag === '--auto')
+            continue;
+        if (flag === '--select') {
+            select = true;
+            continue;
+        }
+        if (flag === '--host') {
+            const parsedHost = (0, plugin_root_1.parseHost)(argv[index + 1]);
+            if (!parsedHost) {
+                err('bouncer-root: --host must be claude, codex, or antigravity\n');
+                return 1;
+            }
+            host = parsedHost;
+            index += 1;
+            continue;
+        }
+        err(`bouncer-root: unknown argument: ${flag}\n`);
+        return 1;
+    }
+    if (select) {
+        if (!(io.isTTY ?? process.stdin.isTTY)) {
+            err('bouncer-root: --select requires a TTY\n');
+            return 1;
+        }
+        if ((io.env ?? process.env).BOUNCER_HOME !== undefined) {
+            try {
+                out(`${(0, plugin_root_1.resolvePluginRoot)(io, host ?? undefined).path}\n`);
+                return 0;
+            }
+            catch (error) {
+                err(`bouncer-root: ${error.message}\n`);
+                return 1;
+            }
+        }
+        const candidates = (0, plugin_root_1.findPluginCandidates)(io, host ?? undefined);
+        if (!candidates.length) {
+            err('bouncer-root: no valid Bouncer plugin roots found\n');
+            return 1;
+        }
+        candidates.forEach((candidate, index) => err(`${index + 1}) ${candidate.path} (${candidate.version})\n`));
+        const input = (io.readInput ?? (() => node_fs_1.default.readFileSync(0, 'utf8')))().trim();
+        const selected = /^\d+$/.test(input) ? candidates[Number(input) - 1] : undefined;
+        if (!selected) {
+            err('bouncer-root: invalid selection\n');
+            return 1;
+        }
+        try {
+            (0, plugin_root_1.assertPluginVersion)(selected);
+        }
+        catch (error) {
+            err(`bouncer-root: ${error.message}\n`);
+            return 1;
+        }
+        out(`${selected.path}\n`);
+        return 0;
+    }
+    try {
+        out(`${(0, plugin_root_1.resolvePluginRoot)(io, host ?? undefined).path}\n`);
+        return 0;
+    }
+    catch (error) {
+        err(`bouncer-root: ${error.message}\n`);
+        return 1;
+    }
+}

package/dist/canonical-json.js

@@ -0,0 +1,37 @@
+'use strict';
+const { createHash } = require('node:crypto');
+// digest 단일 정의. 승인·검증·게이트 증적이 같은 입력에서 같은 hex를 내야 하므로
+// 복사본을 두지 않는다. Node 내장 모듈만 import해 어느 모듈에서든 순환 없이 로드된다.
+/**
+ * 객체의 키를 재귀적으로 정렬한 뒤 UTF-8 JSON으로 직렬화한다.
+ * digest가 키 삽입 순서에 흔들리면 같은 범위가 서로 다른 값으로 갈라진다.
+ *
+ * @param {unknown} value - 직렬화할 값
+ * @returns {string} canonical JSON 문자열
+ */
+function canonicalJson(value) {
+    const normalize = (input) => {
+        if (Array.isArray(input))
+            return input.map(normalize);
+        if (input && typeof input === 'object') {
+            const record = input;
+            const sorted = {};
+            for (const key of Object.keys(record).sort()) {
+                sorted[key] = normalize(record[key]);
+            }
+            return sorted;
+        }
+        return input;
+    };
+    return JSON.stringify(normalize(value));
+}
+/**
+ * canonical JSON의 SHA-256 hex를 돌려준다.
+ *
+ * @param {unknown} value - 해시할 값
+ * @returns {string} 64자 hex digest
+ */
+function sha256Canonical(value) {
+    return createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex');
+}
+module.exports = { canonicalJson, sha256Canonical };

package/dist/cli-commit-guard-command.js

@@ -0,0 +1,74 @@
+'use strict';
+const cliUsage = require("./cli-usage");
+const cliFlags = require("./cli-flags");
+const { parseFlags } = cliFlags;
+const commitHook = require("./commit-hook");
+const { evaluateStaged, evaluateCommit } = commitHook;
+const fs = require("node:fs");
+const USAGE = `usage: bouncer commit-guard (--staged | --command-stdin) [--repo <dir>]
+
+`;
+/**
+ * 커밋 범위 검사 CLI. 두 모드 중 정확히 하나만 받는다.
+ * - `--staged`: git pre-commit 훅용. staged 인덱스를 판정한다.
+ * - `--command-stdin`: PreToolUse 훅용. stdin 전체를 명령 원문으로 읽어
+ *   `evaluateCommit`으로 판정한다(명령 탐지·alias·FAIL_CLOSED 규칙 포함).
+ * 둘 다 있거나 둘 다 없으면 사용법 오류(exit 2)로 끝내 판정 예외(exit 1,
+ * 커밋 차단)와 구분한다.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.argv - `commit-guard` 뒤 인자
+ * @param {string} opts.cwd - `--repo`가 없을 때 쓸 저장소 루트
+ * @param {Function} [opts.evaluate] - 기본 `evaluateStaged`. 테스트 seam
+ * @param {Function} [opts.evaluateCommand] - 기본 `evaluateCommit`. 테스트 seam
+ * @param {Function} [opts.readInput] - 기본 stdin 전체 읽기. 테스트 seam
+ * @param {Function} [opts.stderr] - 차단 사유·사용법 싱크. 생략 시 stderr
+ * @returns {number} 0 허용, 1 차단 또는 내부 오류, 2 사용법
+ */
+function runCommitGuard({ argv, cwd, evaluate, evaluateCommand, readInput, stderr, }) {
+    const err = stderr || ((s) => {
+        process.stderr.write(s);
+    });
+    const staged = argv.includes('--staged');
+    const commandStdin = argv.includes('--command-stdin');
+    // 상호 배타: 둘 다 주면 어느 판정을 원하는지 모호하므로 사용법 오류로 거절한다.
+    if (staged === commandStdin) {
+        err(USAGE);
+        return 2;
+    }
+    const flags = parseFlags(argv);
+    const repoRoot = typeof flags.repo === 'string' && flags.repo ? flags.repo : cwd;
+    const judge = evaluate || evaluateStaged;
+    let result;
+    try {
+        if (commandStdin) {
+            const judgeCommand = evaluateCommand || evaluateCommit;
+            const read = readInput || (() => fs.readFileSync(0, 'utf8'));
+            // stdin 읽기 실패도 이 try 안에서 internal error(exit 1)로 막는다.
+            result = judgeCommand({ command: read(), repoRoot });
+        }
+        else {
+            result = judge({ repoRoot });
+        }
+    }
+    catch (error) {
+        // evaluate가 던지는 모든 예외를 흡수한다. hook 안에서 uncaught로 죽으면
+        // git은 막히지만 정해진 진단 문자열이 아니라 스택이 나와 복구 힌트가 없다.
+        const message = error instanceof Error ? error.message : String(error);
+        err(`commit-guard: internal error, blocking commit: ${message}\n`);
+        return 1;
+    }
+    if (result.block) {
+        err(`${result.reason || 'commit blocked'}\n`);
+        return 1;
+    }
+    return 0;
+}
+function cmdCommitGuard(rest, io) {
+    return runCommitGuard({ argv: rest, cwd: process.cwd(), stderr: io.err });
+}
+module.exports = {
+    runCommitGuard,
+    run: cmdCommitGuard,
+    usage: cliUsage.COMMAND_USAGE['commit-guard'],
+};