new-branch 0.3.1 → 0.5.0

package/README.md

@@ -4,10 +4,16 @@
   <img src="./logo.svg" width="180" alt="new-branch logo" />
 </p>
 
+> “Explicit is better than implicit.”
+> — The Zen of Python (PEP 20)
+
 A composable CLI to generate and optionally create standardized Git branch names using a pattern + transform pipeline.
 
 ![demo](./demo.gif)
 
+[![CI](https://github.com/teles/new-branch/actions/workflows/ci.yml/badge.svg)](https://github.com/teles/new-branch/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/teles/new-branch/branch/main/graph/badge.svg)](https://codecov.io/gh/teles/new-branch)
+
 ---
 
 ## Why
@@ -82,10 +88,49 @@ Example:
 
 ## Built-in Variables
 
+### Core Variables
+
 - `type`
 - `title`
 - `id`
 
+### Date Built-ins (derived from local system time)
+
+- `year` → YYYY
+- `month` → MM (zero padded)
+- `day` → DD (zero padded)
+- `date` → YYYY-MM-DD
+- `dateCompact` → YYYYMMDD
+
+### Git Built-ins (derived from current Git repository)
+
+- `currentBranch` → Current Git branch name (e.g. `main`, `feature/PROJ-123`)
+- `shortSha` → Short SHA of `HEAD` (e.g. `a1b2c3d`)
+- `repoName` → Repository directory name
+- `userName` → Git user name (`git config user.name`)
+- `lastTag` → Most recent Git tag (`git describe --tags --abbrev=0`)
+
+> Note:
+>
+> - Git built-ins are resolved lazily and only when referenced in the pattern.
+> - They are never prompted interactively.
+> - When unavailable (e.g. outside a Git repository), they resolve to an empty string.
+
+#### Example with Git built-ins
+
+```bash
+new-branch \
+  --pattern "{currentBranch}-{shortSha}-{type}-{title:slugify}" \
+  --type feat \
+  --title "Improve logging"
+```
+
+Example output:
+
+```
+main-a1b2c3d-feat-improve-logging
+```
+
 ---
 
 ## Built-in Transforms
@@ -144,11 +189,36 @@ You can define a default pattern in `package.json`:
 }
 ```
 
-Resolution order:
+### Git Configuration
+
+You can also define a default pattern using Git config:
+
+```bash
+git config --local new-branch.pattern "{type}/{title:slugify}-{id}"
+```
+
+Or globally:
+
+```bash
+git config --global new-branch.pattern "{type}/{title:slugify}-{id}"
+```
+
+To remove the pattern from Git config:
+
+```bash
+# Remove from local repository
+git config --unset --local new-branch.pattern
+
+# Remove from global config
+git config --unset --global new-branch.pattern
+```
+
+When using Git config, the resolution order becomes:
 
 1. CLI flags
 2. `package.json` configuration
-3. Interactive prompt (if enabled)
+3. Git config (`new-branch.pattern`)
+4. Interactive prompt (if enabled)
 
 ---
 

package/dist/cli.js

@@ -4,7 +4,10 @@ import { parsePattern } from "./pattern/parsePattern.js";
 import { defaultTransforms } from "./pattern/transforms/index.js";
 import { renderPattern } from "./pattern/transforms/renderPattern.js";
 import { resolveMissingValues } from "./runtime/resolveMissingValues.js";
+import { getBuiltinValues } from "./runtime/builtins.js";
 import { loadProjectConfig } from "./config/loadProjectConfig.js";
+import { getGitConfig } from "./git/gitConfig.js";
+import { extractGitBuiltinKeysFromPattern, getGitBuiltins, patternNeedsGitBuiltins, } from "./git/gitBuiltins.js";
 import { sanitizeGitRef } from "./git/sanitizeGitRef.js";
 import { validateBranchName } from "./git/validateBranchName.js";
 import { createBranch } from "./git/createBranch.js";
@@ -46,7 +49,7 @@ function toInitialValues(args) {
         type: args.options.type,
     };
 }
-async function run() {
+export async function run() {
     // Step 0: args/options
     // Note: CAC prints help, but depending on our parseArgs wrapper we might not
     // expose `help` in `args.options`. We still want to exit early and never
@@ -62,14 +65,35 @@ async function run() {
     const prompt = args.options.prompt !== false;
     // Pipeline: pattern -> AST -> resolve values -> render -> sanitize -> validate -> (optional) git -> output
     const projectConfig = await loadProjectConfig();
-    const resolvedPattern = args.options.pattern ?? projectConfig.pattern;
+    // Git config (respects local -> global precedence automatically)
+    let gitPattern;
+    if (!args.options.pattern && !projectConfig.pattern) {
+        gitPattern = await getGitConfig("new-branch.pattern");
+    }
+    const resolvedPattern = args.options.pattern ?? projectConfig.pattern ?? gitPattern;
     const patternRes = requirePattern(resolvedPattern);
     if (!isOk(patternRes))
         fail("Invalid CLI arguments.", patternRes.error);
     const astRes = safe(() => parsePattern(patternRes.value));
     if (!isOk(astRes))
         fail("Invalid pattern.", astRes.error);
-    const initialValues = toInitialValues(args);
+    // Runtime built-ins (date, etc.)
+    const builtinValues = getBuiltinValues();
+    // Git built-ins (only if the pattern references them)
+    let gitValues = {};
+    if (patternNeedsGitBuiltins(patternRes.value)) {
+        const gitKeys = extractGitBuiltinKeysFromPattern(patternRes.value);
+        const gitRes = await safeAsync(() => getGitBuiltins(gitKeys));
+        if (!isOk(gitRes))
+            fail("Failed to resolve git builtins.", gitRes.error);
+        // GitBuiltins is compatible with RenderValues (string | undefined)
+        gitValues = gitRes.value;
+    }
+    const initialValues = {
+        ...builtinValues,
+        ...gitValues,
+        ...toInitialValues(args),
+    };
     const valuesRes = await safeAsync(() => resolveMissingValues(astRes.value, initialValues, {
         prompt,
     }));
@@ -106,4 +130,8 @@ async function run() {
         }
     }
 }
-run().catch((e) => fail("Unexpected error in CLI.", e));
+// Only execute the CLI automatically when not running tests.
+// In tests, `run` can be imported and called directly.
+if (process.env.NODE_ENV !== "test") {
+    run().catch((e) => fail("Unexpected error in CLI.", e));
+}

package/dist/git/gitBuiltins.js

@@ -0,0 +1,79 @@
+import { execa } from "execa";
+import { getGitConfig } from "../git/gitConfig.js";
+export const GIT_BUILTIN_KEYS = [
+    "shortSha",
+    "currentBranch",
+    "userName",
+    "repoName",
+    "lastTag",
+];
+function uniqueKeys(keys) {
+    return Array.from(new Set(keys));
+}
+function pickAllKeysIfUndefined(keys) {
+    return keys?.length ? uniqueKeys(keys) : GIT_BUILTIN_KEYS;
+}
+async function safeExec(args) {
+    try {
+        const { stdout } = await execa("git", args);
+        const value = stdout.trim();
+        return value.length ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function deriveRepoName(repoRoot) {
+    const parts = repoRoot.split(/[\\/]/).filter(Boolean);
+    return parts.length ? parts[parts.length - 1] : undefined;
+}
+const RESOLVERS = {
+    shortSha: () => safeExec(["rev-parse", "--short", "HEAD"]),
+    currentBranch: async () => {
+        const value = await safeExec(["rev-parse", "--abbrev-ref", "HEAD"]);
+        return value === "HEAD" ? undefined : value;
+    },
+    repoName: async () => {
+        const repoRoot = await safeExec(["rev-parse", "--show-toplevel"]);
+        return repoRoot ? deriveRepoName(repoRoot) : undefined;
+    },
+    lastTag: () => safeExec(["describe", "--tags", "--abbrev=0"]),
+    userName: async () => {
+        const value = await getGitConfig("user.name");
+        return value ?? process.env.USER ?? process.env.USERNAME ?? undefined;
+    },
+};
+async function resolveGitBuiltins(keys) {
+    const wanted = pickAllKeysIfUndefined(keys);
+    const entries = await Promise.all(wanted.map(async (key) => {
+        const value = await RESOLVERS[key]();
+        return [key, value];
+    }));
+    return entries.reduce((acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+    }, {});
+}
+/**
+ * Resolves git-based built-in variables.
+ *
+ * - If `keys` is omitted, resolves all supported git builtins.
+ * - If `keys` is provided, resolves only those keys.
+ */
+export async function getGitBuiltins(keys) {
+    return resolveGitBuiltins(keys);
+}
+/**
+ * Returns true if the pattern contains at least one git builtin key.
+ * (Call this before `getGitBuiltins()` if you want to avoid running git at all.)
+ */
+export function patternNeedsGitBuiltins(pattern) {
+    return GIT_BUILTIN_KEYS.some((key) => pattern.includes(key));
+}
+/**
+ * Extracts which git builtin keys are present in the pattern.
+ * (Use the returned keys to resolve only what you need.)
+ */
+export function extractGitBuiltinKeysFromPattern(pattern) {
+    return GIT_BUILTIN_KEYS.filter((key) => pattern.includes(key));
+}

package/dist/git/gitConfig.js

@@ -0,0 +1,11 @@
+import { execa } from "execa";
+export async function getGitConfig(key) {
+    try {
+        const { stdout } = await execa("git", ["config", "--get", key]);
+        const value = stdout.trim();
+        return value.length ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/pattern/transforms/index.js

@@ -1,16 +1,22 @@
+import { buildRegistry } from "../../pattern/transforms/registry.js";
 import { lower } from "../../pattern/transforms/lower.js";
 import { upper } from "../../pattern/transforms/upper.js";
 import { max } from "../../pattern/transforms/max.js";
-// import { replace } from "./replace.js";
-import { slugify } from "./slugify.js";
-export const allTransforms = [lower, upper, max, slugify];
-export function buildRegistry(defs) {
-    const registry = {};
-    for (const d of defs) {
-        if (registry[d.name])
-            throw new Error(`Duplicate transform name: "${d.name}"`);
-        registry[d.name] = d.fn;
-    }
-    return registry;
-}
+import { slugify } from "../../pattern/transforms/slugify.js";
+import { camel } from "../../pattern/transforms/camel.js";
+import { kebab } from "../../pattern/transforms/kebab.js";
+import { snake } from "../../pattern/transforms/snake.js";
+import { title } from "../../pattern/transforms/title.js";
+import { words } from "../../pattern/transforms/words.js";
+export const allTransforms = [
+    lower,
+    upper,
+    max,
+    slugify,
+    camel,
+    kebab,
+    snake,
+    title,
+    words,
+];
 export const defaultTransforms = buildRegistry(allTransforms);

package/dist/pattern/transforms/registry.js

@@ -0,0 +1,10 @@
+export function buildRegistry(defs) {
+    const registry = {};
+    for (const d of defs) {
+        if (registry[d.name]) {
+            throw new Error(`Duplicate transform name: "${d.name}"`);
+        }
+        registry[d.name] = d.fn;
+    }
+    return registry;
+}

package/dist/runtime/builtins.js

@@ -0,0 +1,44 @@
+/**
+ * Pads a number with a leading zero when necessary.
+ *
+ * @param n - Number to pad.
+ * @returns A zero-padded string (e.g., 2 → "02").
+ */
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+/**
+ * Returns built-in date-based variables derived from
+ * the local system time.
+ *
+ * This function is intentionally synchronous and pure.
+ * The optional `now` parameter allows deterministic testing.
+ *
+ * Provided variables:
+ *
+ * - `year`        → YYYY
+ * - `month`       → MM (zero padded)
+ * - `day`         → DD (zero padded)
+ * - `date`        → YYYY-MM-DD
+ * - `dateCompact` → YYYYMMDD
+ *
+ * @param now - Optional Date instance used to generate values.
+ *              Defaults to the current system date/time.
+ * @returns An object containing built-in date variables.
+ *
+ * @example
+ * const builtins = getBuiltinValues(new Date("2026-02-19"));
+ * builtins.date; // "2026-02-19"
+ */
+export function getBuiltinValues(now = new Date()) {
+    const year = String(now.getFullYear());
+    const month = pad(now.getMonth() + 1);
+    const day = pad(now.getDate());
+    return {
+        year,
+        month,
+        day,
+        date: `${year}-${month}-${day}`,
+        dateCompact: `${year}${month}${day}`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new-branch",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Generate and create standardized git branch names from a pattern.",
   "keywords": [
     "git",
@@ -26,8 +26,9 @@
     "lint": "eslint src --ext .ts"
   },
   "bin": {
-    "new-branch": "./dist/cli.js",
-    "git-nb": "./dist/cli.js"
+    "new-branch": "dist/cli.js",
+    "git-new-branch": "dist/cli.js",
+    "git-nb": "dist/cli.js"
   },
   "author": "Teles <github.com/teles>",
   "license": "MIT",
@@ -48,10 +49,17 @@
   "packageManager": "pnpm@10.22.0",
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.4",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/node": "25.2.3",
     "@vitest/coverage-v8": "4.0.18",
     "eslint": "10.0.0",
     "prettier": "3.8.1",
+    "semantic-release": "^25.0.3",
     "tsc-alias": "1.8.16",
     "tsx": "4.21.0",
     "typescript": "5.9.3",