@carllee1983/tagsmith 0.2.1 → 0.3.1

package/README.md

@@ -11,6 +11,7 @@
 - 🛡️ **防呆** — 建立前驗證格式、版本可解析、嚴格遞增、tag 不重複
 - 🚀 **零設定** — 無設定檔時自動以 semver 推斷 pattern，讀 repo 既有 tag 即可用
 - 🧩 **可擴充** — 版本模型走介面抽象，新增不動核心邏輯
+- 🚧 **合併護欄** — 以 `mergePolicy` 限制受保護分支的合併來源（白 / 黑名單），由 git hook 自動把關
 
 ## 安裝
 
@@ -325,6 +326,81 @@ tagsmith list --all
 可用 git `pre-push` hook 在推送時自動驗證 tag，擋下不符規格者。
 詳見 [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 呼叫，套用政策；非日常手動輸入 |
+
 ## 結束代碼
 
 | 代碼 | 意義 |

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

@@ -7,6 +7,8 @@ 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");
@@ -93,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.1",
+  "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

@@ -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."
+        }
+      }
     }
   }
 }