@carllee1983/tagsmith 0.2.0 → 0.3.1

package/README.md

@@ -1,28 +1,56 @@
 # Tagsmith
 
+[![npm version](https://img.shields.io/npm/v/@carllee1983/tagsmith.svg)](https://www.npmjs.com/package/@carllee1983/tagsmith)
+
 定義專案的 git tag 規格、檢視現有 tag，並安全地產生下一個 git tag——避免順序錯亂或格式不一致。
 
 支援 **SemVer**、**CalVer** 與 **build number** 三種版本模型，tag 樣式可自訂（例如 `v{version}`、`release/{version}`）。
 
-- 🏷️ **規格化** — 用一個 `.tagsmith.json` 定義全專案的 tag 樣式與版本模型
+- 🏷️ **規格化** — 用 `.tagsmith.json` 定義全專案的 tag 樣式與版本模型（可選）
 - 🔍 **可檢視** — 依語義排序列出 tag，標示格式 / 順序 / 重複異常
 - 🛡️ **防呆** — 建立前驗證格式、版本可解析、嚴格遞增、tag 不重複
+- 🚀 **零設定** — 無設定檔時自動以 semver 推斷 pattern，讀 repo 既有 tag 即可用
 - 🧩 **可擴充** — 版本模型走介面抽象，新增不動核心邏輯
+- 🚧 **合併護欄** — 以 `mergePolicy` 限制受保護分支的合併來源（白 / 黑名單），由 git hook 自動把關
 
 ## 安裝
 
 ```bash
-npm install -g tagsmith
+# 全域安裝（指令名稱仍為 tagsmith）
+npm install -g @carllee1983/tagsmith
+
 # 或免安裝直接執行
-npx tagsmith <command>
+npx @carllee1983/tagsmith <command>
+
+# 專案相依（CI / husky hook 常用）
+npm install -D @carllee1983/tagsmith
+# 裝在本機後可直接：npx tagsmith <command>
 ```
 
+npm：[https://www.npmjs.com/package/@carllee1983/tagsmith](https://www.npmjs.com/package/@carllee1983/tagsmith)
+
 需求：Node.js ≥ 18、git。
 
 ## 快速開始
 
+### 零設定（無 `.tagsmith.json`）
+
+已有 semver 風格 tag（如 `v0.1.0`）的 repo 可直接使用：
+
+```bash
+tagsmith list                    # 檢視既有 tag
+tagsmith next                    # 預覽下一個 tag（預設 patch bump）
+tagsmith next --level minor      # 例如 v0.1.0 → v0.2.0
+tagsmith create --push           # 建立並推送
+```
+
+無設定檔時預設 semver、`v{version}` pattern；會從既有 tag 自動推斷格式（如 `{version}`）。
+團隊協作建議仍執行 `init` 並 commit `.tagsmith.json` 以固定規格。
+
+### 完整流程（自訂規格）
+
 ```bash
-# 1. 在 repo 內定義 tag 規格（互動式）
+# 1. 在 repo 內定義 tag 規格（互動式，可選）
 tagsmith init
 
 # 不熟指令？走一次互動式導覽
@@ -99,7 +127,7 @@ tagsmith create --level minor -m "Release 1.2.0" --push
 
 Tagsmith 載入時會自動將其視為一條名為 `default` 的單線設定；現有使用者**零修改**即可繼續使用。
 
-可在檔案加上 `"$schema": "./node_modules/tagsmith/schema.json"` 取得編輯器補全與驗證。
+可在檔案加上 `"$schema": "./node_modules/@carllee1983/tagsmith/schema.json"` 取得編輯器補全與驗證。
 
 ### 三種版本模型
 
@@ -154,7 +182,7 @@ Tagsmith 載入時會自動將其視為一條名為 `default` 的單線設定；
 ## 指令
 
 ### `tagsmith init`
-互動式產生 `.tagsmith.json`。
+互動式產生 `.tagsmith.json`（**可選**；zero-config 模式下可略過，團隊協作仍建議 commit 設定檔）。
 
 | 旗標 | 說明 |
 |------|------|
@@ -296,14 +324,89 @@ tagsmith list --all
 ## 搭配 husky 守 tag
 
 可用 git `pre-push` hook 在推送時自動驗證 tag，擋下不符規格者。
-詳見 [docs/husky-pre-push.md](docs/husky-pre-push.md)。
+詳見 [docs/husky-pre-push.md](docs/husky-pre-push.md)（需安裝 `@carllee1983/tagsmith`）。
+
+## 合併政策（merge policy）
+
+除了管 tag，Tagsmith 也能當 **git 工作流護欄**：限制哪些分支可以合併進受保護分支，
+避免誤把 `develop`、`feature/*` 直接併進 `main`。規則寫在 `.tagsmith.json` 的
+`mergePolicy` 區塊，由本機 git hook（`prepare-commit-msg` / `post-merge`）自動執行——
+**純本機檢查，不涉及 PR 或遠端 server 端政策**。
+
+### 設定
+
+```jsonc
+{
+  "pattern": "v{version}",          // 既有 tag 設定不受影響
+  "model": { "type": "semver" },
+  "initialVersion": "0.1.0",
+
+  "mergePolicy": {
+    "protectedBranches": {
+      "develop": { "allow": ["main"] },                    // 白名單：只准 main 併入
+      "main":    { "deny":  ["develop", "testing", "feature/*"] }, // 黑名單：擋這些
+      "testing": { "deny":  ["develop", "main"] }
+    },
+    "onUnknownSource": "block"        // 無法解析來源時：block（預設）| allow
+  }
+}
+```
+
+規則：
+
+- `mergePolicy` **選配**，缺省即關閉，對既有使用者完全向後相容。
+- `protectedBranches` 的 key 是受保護分支名；**只有目前所在分支落在清單時才檢查**，
+  其餘分支一律放行。
+- 每個受保護分支**二選一**：
+  - `allow`（白名單）— 只允許名單內來源合併進來，其餘封鎖。
+  - `deny`（黑名單）— 名單內來源封鎖，其餘放行。
+  - 同時提供或兩者皆缺 → 設定驗證錯誤。
+- 來源比對支援萬用字元：`*` 比對任意字元（**含 `/`**，可跨多層），`?` 比對單一字元；
+  例如 `feature/*`、`hotfix/*`。
+- `onUnknownSource` — 無法解析合併來源分支時的行為，預設 `block`。
+
+### 安裝 hooks
+
+```bash
+npm install -D @carllee1983/tagsmith   # 先把套件裝進專案
+npx tagsmith hooks install             # 寫入 git hooks
+```
+
+`hooks install` 會偵測 hook 機制：有 `.husky/` 目錄則寫入 husky，否則寫入 `.git/hooks/`。
+寫入的 hook 只負責呼叫 `tagsmith merge-check`，內容帶有 `# tagsmith-merge-policy (managed)`
+標記。若目標位置已有非 tagsmith 管理的 hook，預設中止（**不寫入任何檔案**），需加 `--force` 覆寫。
+移除用 `tagsmith hooks uninstall`（只移除帶標記的檔案，不動其他 hook）。
+
+### 攔截行為
+
+當合併違反政策時：
+
+- **建立 merge commit**（`prepare-commit-msg`，尚未 commit）— 無法乾淨回滾，直接中止，
+  提示 `git merge --abort`。
+- **fast-forward 合併**（`post-merge`，HEAD 已前進）— 自動 `git reset --hard ORIG_HEAD`
+  回到合併前狀態。
+
+訊息會列出 target 分支、source 分支與封鎖原因。緊急時可用環境變數略過檢查：
+
+```bash
+TAGSMITH_SKIP=1 git merge ...   # 略過一次（緊急用）
+HUSKY=0 git merge ...           # 同樣略過
+```
+
+### 相關指令
+
+| 指令 | 說明 |
+|------|------|
+| `tagsmith hooks install [--force]` | 安裝 merge-policy git hooks（`--force` 覆寫既有非 tagsmith hook） |
+| `tagsmith hooks uninstall` | 移除 tagsmith 管理的 hooks |
+| `tagsmith merge-check [--mode <merge-head\|post-merge>]` | 由 hook 呼叫，套用政策；非日常手動輸入 |
 
 ## 結束代碼
 
 | 代碼 | 意義 |
 |:---:|------|
 | `0` | 成功（含 `--dry-run`） |
-| `1` | 失敗：缺設定檔、非 git repo、驗證未通過、git 指令錯誤等（訊息走 stderr） |
+| `1` | 失敗：非 git repo、驗證未通過、git 指令錯誤等（訊息走 stderr） |
 
 ## 設計
 

package/dist/cli/hooks.d.ts

@@ -0,0 +1,5 @@
+export interface HooksInstallFlags {
+    force?: boolean;
+}
+export declare function runHooksInstall(cwd: string, flags: HooksInstallFlags): Promise<number>;
+export declare function runHooksUninstall(cwd: string): Promise<number>;

package/dist/cli/hooks.js

@@ -0,0 +1,99 @@
+// src/cli/hooks.ts
+import { access, chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { revParse } from "../git/git.js";
+import { info, printError, success, warn } from "./ui.js";
+const MARKER = "# tagsmith-merge-policy (managed)";
+const HOOKS = [
+    {
+        name: "prepare-commit-msg",
+        body: [
+            "#!/usr/bin/env sh",
+            MARKER,
+            'case "$2" in',
+            "  merge) npx --no -- tagsmith merge-check --mode merge-head || exit $? ;;",
+            "esac",
+            "",
+        ].join("\n"),
+    },
+    {
+        name: "post-merge",
+        body: [
+            "#!/usr/bin/env sh",
+            MARKER,
+            "npx --no -- tagsmith merge-check --mode post-merge || exit $?",
+            "",
+        ].join("\n"),
+    },
+];
+/** Resolve the directory hooks should be written to: .husky if present, else .git/hooks. */
+async function resolveHooksDir(cwd) {
+    if (await existsFile(path.join(cwd, ".husky")))
+        return path.join(cwd, ".husky");
+    // `git rev-parse --git-dir` returns the git dir (relative or absolute).
+    const raw = (await revParse({ cwd }, "--git-dir")).trim();
+    const gitDir = path.isAbsolute(raw) ? raw : path.join(cwd, raw);
+    return path.join(gitDir, "hooks");
+}
+async function existsFile(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runHooksInstall(cwd, flags) {
+    try {
+        const dir = await resolveHooksDir(cwd);
+        await mkdir(dir, { recursive: true });
+        // Pre-flight: refuse before writing anything if any hook is foreign.
+        for (const hook of HOOKS) {
+            const file = path.join(dir, hook.name);
+            if (await existsFile(file)) {
+                const current = await readFile(file, "utf8");
+                if (!current.includes(MARKER) && !flags.force) {
+                    printError(`${hook.name} already exists and is not tagsmith-managed. Re-run with --force to overwrite.`);
+                    return 1;
+                }
+            }
+        }
+        for (const hook of HOOKS) {
+            const file = path.join(dir, hook.name);
+            await writeFile(file, hook.body, "utf8");
+            await chmod(file, 0o755);
+            success(`installed ${path.relative(cwd, file)}`);
+        }
+        info("");
+        info("merge-policy hooks installed. Configure rules under `mergePolicy` in .tagsmith.json.");
+        return 0;
+    }
+    catch (err) {
+        printError(err);
+        return 1;
+    }
+}
+export async function runHooksUninstall(cwd) {
+    try {
+        const dir = await resolveHooksDir(cwd);
+        for (const hook of HOOKS) {
+            const file = path.join(dir, hook.name);
+            if (!(await existsFile(file)))
+                continue;
+            const current = await readFile(file, "utf8");
+            if (current.includes(MARKER)) {
+                await rm(file);
+                success(`removed ${path.relative(cwd, file)}`);
+            }
+            else {
+                warn(`skipped ${hook.name} (not tagsmith-managed)`);
+            }
+        }
+        return 0;
+    }
+    catch (err) {
+        printError(err);
+        return 1;
+    }
+}

package/dist/cli/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { Command } from "commander";
 import { runInit } from "./init.js";
 import { runList } from "./list.js";
@@ -6,14 +7,18 @@ import { runNext } from "./next.js";
 import { runCreate } from "./create.js";
 import { runGuide } from "./guide.js";
 import { runCheck } from "./check.js";
+import { runMergeCheck } from "./merge-check.js";
+import { runHooksInstall, runHooksUninstall } from "./hooks.js";
 import { printError } from "./ui.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
 const program = new Command();
 program
     .name("tagsmith")
     .description("Define git tag specs, view tags, and generate the next git tag safely.")
-    .version("0.1.0");
-program.addHelpText("beforeAll", "\n  Tagsmith — define a tag spec, then safely compute and create git tags.\n" +
-    "  First time here? Run `tagsmith init`, or `tagsmith guide` for a walkthrough.\n");
+    .version(version);
+program.addHelpText("beforeAll", "\n  Tagsmith (@carllee1983/tagsmith) — define a tag spec, then safely compute and create git tags.\n" +
+    "  No config yet? Try `tagsmith next` (zero-config semver), `tagsmith init`, or `tagsmith guide`.\n");
 program.addHelpText("after", `
 Examples:
   $ tagsmith init                          Define the tag spec (interactive)
@@ -26,7 +31,7 @@ Examples:
 `);
 program
     .command("init")
-    .description("Create a .tagsmith.json tag spec for this repo")
+    .description("Create a .tagsmith.json tag spec for this repo (optional; zero-config works without it)")
     .option("--pattern <pattern>", "tag pattern, must contain {version}")
     .option("--model <type>", "version model: semver | calver | build")
     .option("--initial-version <version>", "initial version")
@@ -90,6 +95,29 @@ Examples:
   $ tagsmith create --dry-run              Preview without creating
   $ tagsmith create --tag release          Create the next tag on a named tag line
 `);
+program
+    .command("merge-check")
+    .description("Enforce the mergePolicy for a protected branch (used by git hooks)")
+    .option("--mode <mode>", "hook context: merge-head | post-merge", "merge-head")
+    .action(async (opts) => {
+    process.exitCode = await runMergeCheck(process.cwd(), { mode: opts.mode });
+});
+const hooks = program
+    .command("hooks")
+    .description("Manage tagsmith git hooks (merge policy enforcement)");
+hooks
+    .command("install")
+    .description("Install merge-policy git hooks into this repo")
+    .option("--force", "overwrite existing non-tagsmith hooks")
+    .action(async (opts) => {
+    process.exitCode = await runHooksInstall(process.cwd(), { force: opts.force });
+});
+hooks
+    .command("uninstall")
+    .description("Remove tagsmith-managed git hooks")
+    .action(async () => {
+    process.exitCode = await runHooksUninstall(process.cwd());
+});
 program.parseAsync(process.argv).catch((err) => {
     printError(err);
     process.exitCode = 1;

package/dist/cli/merge-check.d.ts

@@ -0,0 +1,4 @@
+export interface MergeCheckFlags {
+    mode?: "merge-head" | "post-merge";
+}
+export declare function runMergeCheck(cwd: string, flags: MergeCheckFlags): Promise<number>;

package/dist/cli/merge-check.js

@@ -0,0 +1,73 @@
+// src/cli/merge-check.ts
+import { loadMergePolicy } from "../core/merge-policy/schema.js";
+import { validateMerge } from "../core/merge-policy/validate.js";
+import { resolveFfSource, resolveFromMergeHead, } from "../core/merge-policy/resolve.js";
+import { currentBranch, isAncestor, parentCount, resetHard, revParse, revParseVerify, } from "../git/git.js";
+import { color, info, printError } from "./ui.js";
+function skipRequested() {
+    return process.env.HUSKY === "0" || process.env.TAGSMITH_SKIP === "1";
+}
+export async function runMergeCheck(cwd, flags) {
+    if (skipRequested())
+        return 0;
+    try {
+        const policy = await loadMergePolicy(cwd);
+        if (!policy)
+            return 0;
+        // fallback guards programmatic callers; commander supplies the CLI default
+        const mode = flags.mode ?? "merge-head";
+        const current = await currentBranch({ cwd });
+        if (current === "") {
+            printError("merge-policy: detached HEAD — branch name cannot be determined.");
+            return 1;
+        }
+        if (!(current in policy.protectedBranches))
+            return 0;
+        let source;
+        let rollback = null;
+        if (mode === "post-merge") {
+            rollback = await revParseVerify({ cwd }, "ORIG_HEAD");
+            const newHead = await revParse({ cwd }, "HEAD");
+            if (!rollback || rollback === newHead)
+                return 0;
+            // A merge commit authored by this merge (>=2 parents whose first parent
+            // is the pre-merge HEAD) was already validated by the merge-head hook;
+            // its source branch no longer points at HEAD, so re-checking here would
+            // resolve no source and wrongly roll the merge back. Only true
+            // fast-forwards (which create no commit and skip merge-head) need
+            // post-merge enforcement. This also subsumes the octopus case.
+            if ((await parentCount({ cwd }, "HEAD")) >= 2) {
+                const firstParent = await revParseVerify({ cwd }, "HEAD^1");
+                if (firstParent === rollback)
+                    return 0;
+            }
+            if (!(await isAncestor({ cwd }, rollback, newHead)))
+                return 0; // not ff
+            source = await resolveFfSource({ cwd }, current);
+        }
+        else {
+            if (!(await revParseVerify({ cwd }, "MERGE_HEAD")))
+                return 0;
+            source = await resolveFromMergeHead({ cwd }, current);
+        }
+        const decision = validateMerge(policy, current, source);
+        if (decision.ok)
+            return 0;
+        if (rollback)
+            await resetHard({ cwd }, rollback);
+        info("");
+        printError(`merge-policy: merge blocked by branch policy.`);
+        info(`  target:  ${color.cyan(current)}`);
+        info(`  source:  ${color.cyan(source ?? "(unknown)")}`);
+        info(`  reason:  ${decision.reason}`);
+        info(rollback
+            ? "  branch reset to pre-merge state."
+            : "  run: git merge --abort");
+        info("  TAGSMITH_SKIP=1 git merge ...   # skip hook (emergency only)");
+        return 1;
+    }
+    catch (err) {
+        printError(err);
+        return 1;
+    }
+}

package/dist/core/merge-policy/match.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True when `branch` matches the glob `pattern`.
+ * Glob rules: `*` matches any sequence including `/`; `?` matches a single character.
+ * This intentionally differs from POSIX/shell globbing where `*` stops at `/`.
+ */
+export declare function matchSource(pattern: string, branch: string): boolean;

package/dist/core/merge-policy/match.js

@@ -0,0 +1,15 @@
+// src/core/merge-policy/match.ts
+/** Convert a branch glob (`*`, `?`) into an anchored RegExp. */
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const body = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${body}$`);
+}
+/**
+ * True when `branch` matches the glob `pattern`.
+ * Glob rules: `*` matches any sequence including `/`; `?` matches a single character.
+ * This intentionally differs from POSIX/shell globbing where `*` stops at `/`.
+ */
+export function matchSource(pattern, branch) {
+    return globToRegExp(pattern).test(branch);
+}

package/dist/core/merge-policy/resolve.d.ts

@@ -0,0 +1,7 @@
+import type { GitOptions } from "../../git/git.js";
+/** Strip remote prefixes and ^/~ suffixes from a ref name. */
+export declare function normalizeBranch(name: string): string;
+/** Resolve the source branch of an in-progress merge (MERGE_HEAD present). */
+export declare function resolveFromMergeHead(opts: GitOptions, current: string): Promise<string | null>;
+/** Resolve the source branch of a fast-forward merge (post-merge). */
+export declare function resolveFfSource(opts: GitOptions, current: string): Promise<string | null>;

package/dist/core/merge-policy/resolve.js

@@ -0,0 +1,56 @@
+import { branchesPointingAt, mergeMsg, nameRev, revParse, revParseVerify, } from "../../git/git.js";
+/** Strip remote prefixes and ^/~ suffixes from a ref name. */
+export function normalizeBranch(name) {
+    return name
+        .replace(/^remotes\/origin\//, "")
+        .replace(/^origin\//, "")
+        .replace(/[\^~].*$/, "");
+}
+function parseMergeMsg(msg) {
+    for (const line of msg.split("\n")) {
+        const m = line.match(/^Merge (?:remote-tracking )?branch '([^']+)'/);
+        if (m)
+            return normalizeBranch(m[1]);
+    }
+    return null;
+}
+/** Resolve the source branch of an in-progress merge (MERGE_HEAD present). */
+export async function resolveFromMergeHead(opts, current) {
+    const msg = await mergeMsg(opts);
+    if (msg) {
+        const parsed = parseMergeMsg(msg);
+        if (parsed)
+            return parsed;
+    }
+    const tip = await revParseVerify(opts, "MERGE_HEAD");
+    if (tip) {
+        const named = (await branchesPointingAt(opts, tip))
+            .map(normalizeBranch)
+            .filter((n) => n !== current);
+        if (named.length > 0)
+            return named.sort()[0];
+        const nr = await nameRev(opts, tip);
+        if (nr)
+            return normalizeBranch(nr);
+    }
+    return null;
+}
+/** Resolve the source branch of a fast-forward merge (post-merge). */
+export async function resolveFfSource(opts, current) {
+    const newHead = await revParse(opts, "HEAD");
+    const raw = await branchesPointingAt(opts, newHead);
+    const candidates = raw.map(normalizeBranch).filter((n) => n !== current);
+    // Prefer well-known integration branches, else first alphabetical.
+    for (const preferred of ["main", "develop", "testing"]) {
+        if (candidates.includes(preferred))
+            return preferred;
+    }
+    if (candidates.length > 0)
+        return candidates.sort()[0];
+    // No other branch points here. If a remote-tracking ref of the current branch
+    // does (e.g. origin/main when HEAD == main), this fast-forward is a pull/sync
+    // of the branch into itself — report it as such so the policy allows it.
+    // (A genuinely unresolvable source leaves only the local branch ref → null.)
+    const selfRemote = raw.some((r) => r !== current && normalizeBranch(r) === current);
+    return selfRemote ? current : null;
+}

package/dist/core/merge-policy/schema.d.ts

@@ -0,0 +1,14 @@
+export declare class MergePolicyError extends Error {
+}
+export interface BranchRule {
+    allow?: string[];
+    deny?: string[];
+}
+export interface MergePolicy {
+    protectedBranches: Record<string, BranchRule>;
+    onUnknownSource: "block" | "allow";
+}
+/** Extract & validate the optional `mergePolicy` key from a raw config object. */
+export declare function parseMergePolicy(raw: unknown): MergePolicy | null;
+/** Read `.tagsmith.json` from cwd and return its mergePolicy, or null. */
+export declare function loadMergePolicy(cwd: string): Promise<MergePolicy | null>;

package/dist/core/merge-policy/schema.js

@@ -0,0 +1,53 @@
+// src/core/merge-policy/schema.ts
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { CONFIG_FILENAME } from "../config.js";
+export class MergePolicyError extends Error {
+}
+const branchRuleSchema = z
+    .object({
+    allow: z.array(z.string().min(1)).optional(),
+    deny: z.array(z.string().min(1)).optional(),
+})
+    .refine((r) => (r.allow === undefined) !== (r.deny === undefined), {
+    message: "set exactly one of allow / deny",
+});
+const mergePolicySchema = z.object({
+    protectedBranches: z.record(z.string().min(1), branchRuleSchema),
+    onUnknownSource: z.enum(["block", "allow"]).default("block"),
+});
+/** Extract & validate the optional `mergePolicy` key from a raw config object. */
+export function parseMergePolicy(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const block = raw["mergePolicy"];
+    if (block === undefined)
+        return null;
+    const result = mergePolicySchema.safeParse(block);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new MergePolicyError(`Invalid mergePolicy:\n${issues}`);
+    }
+    return result.data;
+}
+/** Read `.tagsmith.json` from cwd and return its mergePolicy, or null. */
+export async function loadMergePolicy(cwd) {
+    let text;
+    try {
+        text = await readFile(path.join(cwd, CONFIG_FILENAME), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new MergePolicyError(`${CONFIG_FILENAME} is not valid JSON: ${err.message}`);
+    }
+    return parseMergePolicy(json);
+}

package/dist/core/merge-policy/validate.d.ts

@@ -0,0 +1,12 @@
+import type { MergePolicy } from "./schema.js";
+export type Decision = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decide whether merging `source` into `current` is permitted.
+ * `source === null` means the source branch could not be resolved.
+ */
+export declare function validateMerge(policy: MergePolicy, current: string, source: string | null): Decision;

package/dist/core/merge-policy/validate.js

@@ -0,0 +1,33 @@
+import { matchSource } from "./match.js";
+/**
+ * Decide whether merging `source` into `current` is permitted.
+ * `source === null` means the source branch could not be resolved.
+ */
+export function validateMerge(policy, current, source) {
+    const rule = policy.protectedBranches[current];
+    if (!rule)
+        return { ok: true };
+    // A branch fast-forwarding/pulling its own remote-tracking ref reports itself
+    // as the source. Merging a branch into itself is a sync, never a cross-branch
+    // merge, so it is always permitted.
+    if (source === current)
+        return { ok: true };
+    if (source === null) {
+        return policy.onUnknownSource === "allow"
+            ? { ok: true }
+            : { ok: false, reason: "could not resolve merge source" };
+    }
+    if (rule.allow) {
+        const ok = rule.allow.some((p) => matchSource(p, source));
+        return ok
+            ? { ok: true }
+            : { ok: false, reason: `${current} may only merge: ${rule.allow.join(", ")}` };
+    }
+    // rule.deny is guaranteed present when rule.allow is absent: the schema
+    // refine enforces exactly one of allow / deny. `?? []` keeps this safe even
+    // if that invariant is ever weakened.
+    const denied = (rule.deny ?? []).some((p) => matchSource(p, source));
+    return denied
+        ? { ok: false, reason: `${current} must not merge ${source}` }
+        : { ok: true };
+}

package/dist/git/git.d.ts

@@ -21,3 +21,21 @@ export interface PushTagOptions extends GitOptions {
     remote?: string;
 }
 export declare function pushTag(opts: PushTagOptions): Promise<void>;
+/** Current branch name, or "" when in detached HEAD. */
+export declare function currentBranch(opts: GitOptions): Promise<string>;
+/** Resolve a ref to a full SHA, or null when it does not exist. */
+export declare function revParseVerify(opts: GitOptions, ref: string): Promise<string | null>;
+/** Resolve a ref to a full SHA (throws via GitError when invalid). */
+export declare function revParse(opts: GitOptions, ref: string): Promise<string>;
+/** Read the MERGE_MSG file contents, or null when it is absent. */
+export declare function mergeMsg(opts: GitOptions): Promise<string | null>;
+/** Branch short-names (local + remote) that point at `ref`. */
+export declare function branchesPointingAt(opts: GitOptions, ref: string): Promise<string[]>;
+/** `git name-rev` short name for `ref`, or null when undefined. */
+export declare function nameRev(opts: GitOptions, ref: string): Promise<string | null>;
+/** True when `ancestor` is an ancestor of `descendant`. */
+export declare function isAncestor(opts: GitOptions, ancestor: string, descendant: string): Promise<boolean>;
+/** Number of parents of `ref` (2 = normal merge, >2 = octopus). */
+export declare function parentCount(opts: GitOptions, ref: string): Promise<number>;
+/** Hard-reset the working tree to `ref`. */
+export declare function resetHard(opts: GitOptions, ref: string): Promise<void>;

package/dist/git/git.js

@@ -1,4 +1,6 @@
 import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 export class GitError extends Error {
@@ -45,3 +47,76 @@ export async function createTag(opts) {
 export async function pushTag(opts) {
     await git(["push", opts.remote ?? "origin", opts.name], opts.cwd);
 }
+// --- merge-policy helpers ---
+/** Run git, returning { code, stdout } without throwing on non-zero exit. */
+async function tryGit(args, cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", args, { cwd });
+        return { code: 0, stdout };
+    }
+    catch (err) {
+        const e = err;
+        return { code: typeof e.code === "number" ? e.code : 1, stdout: e.stdout ?? "" };
+    }
+}
+/** Current branch name, or "" when in detached HEAD. */
+export async function currentBranch(opts) {
+    const { stdout } = await tryGit(["branch", "--show-current"], opts.cwd);
+    return stdout.trim();
+}
+/** Resolve a ref to a full SHA, or null when it does not exist. */
+export async function revParseVerify(opts, ref) {
+    const { code, stdout } = await tryGit(["rev-parse", "-q", "--verify", ref], opts.cwd);
+    return code === 0 ? stdout.trim() : null;
+}
+/** Resolve a ref to a full SHA (throws via GitError when invalid). */
+export async function revParse(opts, ref) {
+    return (await git(["rev-parse", ref], opts.cwd)).trim();
+}
+/** Read the MERGE_MSG file contents, or null when it is absent. */
+export async function mergeMsg(opts) {
+    const { code, stdout } = await tryGit(["rev-parse", "--git-path", "MERGE_MSG"], opts.cwd);
+    if (code !== 0)
+        return null;
+    // `--git-path` returns an absolute path under separate-git-dir / $GIT_DIR
+    // setups; resolve relative paths against cwd but keep absolute ones as-is.
+    const raw = stdout.trim();
+    const file = path.isAbsolute(raw) ? raw : path.join(opts.cwd, raw);
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Branch short-names (local + remote) that point at `ref`. */
+export async function branchesPointingAt(opts, ref) {
+    const { stdout } = await tryGit(["branch", "-a", "--points-at", ref, "--format=%(refname:short)"], opts.cwd);
+    return stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+/** `git name-rev` short name for `ref`, or null when undefined. */
+export async function nameRev(opts, ref) {
+    const { code, stdout } = await tryGit(["name-rev", "--name-only", "--exclude=tags/*", ref], opts.cwd);
+    const name = stdout.trim();
+    if (code !== 0 || name === "" || name === "undefined")
+        return null;
+    return name;
+}
+/** True when `ancestor` is an ancestor of `descendant`. */
+export async function isAncestor(opts, ancestor, descendant) {
+    const { code } = await tryGit(["merge-base", "--is-ancestor", ancestor, descendant], opts.cwd);
+    return code === 0;
+}
+/** Number of parents of `ref` (2 = normal merge, >2 = octopus). */
+export async function parentCount(opts, ref) {
+    const { stdout } = await tryGit(["rev-list", "--parents", "-1", ref], opts.cwd);
+    const words = stdout.trim().split(/\s+/).filter((w) => w.length > 0);
+    return Math.max(0, words.length - 1);
+}
+/** Hard-reset the working tree to `ref`. */
+export async function resetHard(opts, ref) {
+    await git(["reset", "--hard", ref], opts.cwd);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/tagsmith",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Define git tag specs, view tags, and generate the next git tag safely — avoiding ordering or format anomalies.",
   "type": "module",
   "publishConfig": { "access": "public" },

package/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://github.com/CMG/tagsmith/schema.json",
+  "$id": "https://github.com/CarlLee1983/Tagsmith/schema.json",
   "title": "Tagsmith config",
   "description": "Tag specification for the tagsmith CLI (.tagsmith.json).",
   "type": "object",
@@ -54,6 +54,41 @@
     "push": {
       "type": "boolean",
       "description": "Default push behaviour for `tagsmith create`."
+    },
+    "mergePolicy": {
+      "type": "object",
+      "description": "Optional branch merge guardrails enforced by `tagsmith merge-check` via git hooks.",
+      "additionalProperties": false,
+      "required": ["protectedBranches"],
+      "properties": {
+        "protectedBranches": {
+          "type": "object",
+          "description": "Map of protected branch name -> merge rule. Only the current branch is checked; others pass.",
+          "additionalProperties": {
+            "type": "object",
+            "description": "Set exactly one of allow (whitelist) or deny (blacklist). Sources support glob (* and ?).",
+            "additionalProperties": false,
+            "oneOf": [{ "required": ["allow"] }, { "required": ["deny"] }],
+            "properties": {
+              "allow": {
+                "type": "array",
+                "description": "Only these sources may merge in; all others are blocked.",
+                "items": { "type": "string", "minLength": 1 }
+              },
+              "deny": {
+                "type": "array",
+                "description": "These sources are blocked; all others pass.",
+                "items": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        },
+        "onUnknownSource": {
+          "enum": ["block", "allow"],
+          "default": "block",
+          "description": "Behaviour when the merge source branch cannot be resolved."
+        }
+      }
     }
   }
 }