new-branch 0.4.0 → 0.6.0

package/README.md

@@ -102,6 +102,35 @@ Example:
 - `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
@@ -148,31 +177,63 @@ Disable prompts with:
 
 ---
 
-## Project Configuration
+## Project Configuration and precedence
+
+Configuration for `new-branch` may come from several places. The CLI resolves the first _non-empty_ configuration it finds according to the following precedence (highest → lowest):
+
+1. CLI flags (explicit `--pattern`, `--type`, etc.)
+2. `.newbranchrc.json` (a repository-local JSON config file)
+3. `package.json` under the `new-branch` key
+4. Git config (`new-branch.pattern`) — local then global
+5. Interactive prompt (only if enabled and a value is still missing)
+
+This means that if a higher-precedence source provides a non-empty value, lower-precedence sources are not consulted or merged.
 
-You can define a default pattern in `package.json`:
+Examples
+
+1. `.newbranchrc.json` (preferred when present and non-empty):
+
+```json
+{
+  "pattern": "{type}/{title:slugify}-{id}",
+  "types": [
+    { "value": "feat", "label": "Feature" },
+    { "value": "fix", "label": "Fix" }
+  ],
+  "defaultType": "feat"
+}
+```
+
+2. `package.json` fallback:
 
 ```json
 {
   "new-branch": {
-    "pattern": "{type}/{title:slugify}-{id}"
+    "pattern": "{type}/{title:slugify}-{id}",
+    "defaultType": "fix"
   }
 }
 ```
 
-### Git Configuration
-
-You can also define a default pattern using Git config:
+3. Git config fallback (local takes precedence over global):
 
 ```bash
 git config --local new-branch.pattern "{type}/{title:slugify}-{id}"
+git config --global new-branch.pattern "{type}/{title:slugify}-{id}"
 ```
 
-Or globally:
+Notes about `type` and `defaultType`
 
-```bash
-git config --global new-branch.pattern "{type}/{title:slugify}-{id}"
-```
+- Order for resolving the branch `type` follows the SPEC behavior we implemented:
+  1. CLI `--type` (explicit flag) overrides everything.
+  2. `defaultType` from the selected configuration source is used next (if present).
+  3. If the project config declares exactly one `type` in `types[]`, that single type is used as a convenience.
+  4. If the type is still not resolved and interactive prompting is allowed, the CLI will prompt for it.
+  5. If the type is still missing and `--no-prompt` (or `prompt: false`) is in effect, the CLI will fail with a helpful error.
+
+- Validation: when a configuration source provides both `types[]` and `defaultType`, the `defaultType` must match one of the declared `types[].value`. If it does not, configuration validation will surface an error.
+
+- Interactive prompts: when `types[]` are present in the chosen project config, those entries are exposed as choices to the interactive `type` select prompt so users see and can pick project-defined types.
 
 To remove the pattern from Git config:
 
@@ -184,13 +245,6 @@ git config --unset --local new-branch.pattern
 git config --unset --global new-branch.pattern
 ```
 
-When using Git config, the resolution order becomes:
-
-1. CLI flags
-2. `package.json` configuration
-3. Git config (`new-branch.pattern`)
-4. Interactive prompt (if enabled)
-
 ---
 
 ## Git Safety

package/dist/cli.js

@@ -5,8 +5,9 @@ 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 { loadConfig } from "./config/loadConfig.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";
@@ -49,13 +50,27 @@ function toInitialValues(args) {
     };
 }
 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
-    // require a pattern when the user just asked for help.
-    const argv = process.argv.slice(2);
+    // Normalize argv so it works consistently across:
+    // - node dist/cli.js --id 123
+    // - pnpm dev -- --id 123
+    // - tsx src/cli.ts --id 123
+    //
+    // Notes:
+    // - `pnpm` may inject a standalone "--" before the script flags.
+    // - `tsx` puts the script path (e.g. `src/cli.ts`) as the first item in `process.argv.slice(2)`.
+    //   That script path is not a flag, so we strip leading non-flag arguments.
+    let argv = process.argv.slice(2);
+    // Strip leading positional entries like `src/cli.ts` (common when running via `tsx`).
+    while (argv.length > 0 && argv[0] !== "--" && !argv[0].startsWith("-")) {
+        argv = argv.slice(1);
+    }
+    // Strip standalone "--" injected by pnpm.
+    if (argv[0] === "--") {
+        argv = argv.slice(1);
+    }
     const wantsHelp = argv.includes("--help") || argv.includes("-h");
-    const args = parseArgs(process.argv);
+    // Important: parseArgs should receive the reconstructed argv
+    const args = parseArgs(["node", "cli", ...argv]);
     if (wantsHelp) {
         return;
     }
@@ -63,7 +78,7 @@ export async function run() {
     const create = args.options.create === true;
     const prompt = args.options.prompt !== false;
     // Pipeline: pattern -> AST -> resolve values -> render -> sanitize -> validate -> (optional) git -> output
-    const projectConfig = await loadProjectConfig();
+    const projectConfig = await loadConfig();
     // Git config (respects local -> global precedence automatically)
     let gitPattern;
     if (!args.options.pattern && !projectConfig.pattern) {
@@ -76,13 +91,40 @@ export async function run() {
     const astRes = safe(() => parsePattern(patternRes.value));
     if (!isOk(astRes))
         fail("Invalid pattern.", astRes.error);
+    // 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;
+    }
+    // Resolve `type` from CLI or config, honoring precedence:
+    // 1. CLI --type overrides everything
+    // 2. projectConfig.defaultType (if present)
+    // 3. if only one type is declared, use that as a convenience
+    // 4. otherwise leave undefined so resolveMissingValues will prompt (if prompt===true)
+    let resolvedType = args.options.type ?? projectConfig.defaultType;
+    if (!resolvedType && projectConfig.types?.length === 1) {
+        resolvedType = projectConfig.types[0].value;
+    }
     const initialValues = {
         ...builtinValues,
+        ...gitValues,
         ...toInitialValues(args),
+        type: resolvedType,
     };
     const valuesRes = await safeAsync(() => resolveMissingValues(astRes.value, initialValues, {
         prompt,
+        // If project config defines `types`, expose them as choices for the
+        // interactive `type` select so the user sees and can choose project values.
+        typeChoices: projectConfig.types
+            ? projectConfig.types.map((t) => ({ name: t.label, value: t.value }))
+            : undefined,
     }));
     if (!isOk(valuesRes))
         fail("Failed to resolve required values.", valuesRes.error);

package/dist/config/loadConfig.js

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview
+ * Aggregates configuration sources without merging.
+ *
+ * Precedence:
+ * 1) .new-branchrc.json
+ * 2) package.json
+ * 3) git config
+ */
+import { rcLoader } from "./sources/rc.loader.js";
+import { packageJsonLoader } from "./sources/packageJson.loader.js";
+import { gitLoader } from "./sources/git.loader.js";
+/**
+ * Loads the first configuration found.
+ * No merging is performed.
+ */
+export async function loadConfig() {
+    // Load rc loader first and prefer a non-empty config. Avoid calling the
+    // git loader unless necessary because it depends on external git state
+    // and may import modules that are platform-sensitive.
+    const rcRes = await rcLoader.load();
+    if (rcRes.found && rcRes.config && Object.keys(rcRes.config).length > 0)
+        return rcRes.config;
+    const pkgRes = await packageJsonLoader.load();
+    if (pkgRes.found && pkgRes.config && Object.keys(pkgRes.config).length > 0)
+        return pkgRes.config;
+    const gitRes = await gitLoader.load();
+    if (gitRes.found)
+        return gitRes.config ?? {};
+    return {};
+}

package/dist/config/sources/git.loader.js

@@ -0,0 +1,39 @@
+import { getGitConfig } from "../../git/gitConfig.js";
+import { validateProjectConfigSource, validateProjectConfigFinal } from "../validate.js";
+function parseGitTypes(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((entry) => {
+        const idx = entry.indexOf(":");
+        if (idx === -1) {
+            return { value: entry, label: entry };
+        }
+        return {
+            value: entry.slice(0, idx).trim(),
+            label: entry.slice(idx + 1).trim(),
+        };
+    });
+}
+export const gitLoader = {
+    source: "git",
+    async load() {
+        const pattern = await getGitConfig("new-branch.pattern");
+        const defaultType = await getGitConfig("new-branch.defaultType");
+        const typesRaw = await getGitConfig("new-branch.types");
+        if (!pattern && !defaultType && !typesRaw) {
+            return { found: false, source: "git", config: undefined };
+        }
+        const cfg = {};
+        if (pattern)
+            cfg.pattern = pattern;
+        if (defaultType)
+            cfg.defaultType = defaultType;
+        if (typesRaw)
+            cfg.types = parseGitTypes(typesRaw);
+        const sourceValidated = validateProjectConfigSource(cfg, "git config");
+        const finalValidated = validateProjectConfigFinal(sourceValidated, "git config");
+        return { found: true, source: "git", config: finalValidated };
+    },
+};

package/dist/config/sources/packageJson.loader.js

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { validateProjectConfigSource, validateProjectConfigFinal } from "../validate.js";
+function isNodeFsError(e) {
+    return typeof e === "object" && e !== null && "code" in e;
+}
+export const packageJsonLoader = {
+    source: "package.json",
+    async load() {
+        try {
+            const path = join(process.cwd(), "package.json");
+            const raw = await readFile(path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== "object" || parsed === null) {
+                return { found: false, source: "package.json", config: undefined };
+            }
+            const pkg = parsed;
+            const block = pkg["new-branch"];
+            if (!block) {
+                return { found: false, source: "package.json", config: undefined };
+            }
+            const sourceValidated = validateProjectConfigSource(block, "package.json");
+            const finalValidated = validateProjectConfigFinal(sourceValidated, "package.json");
+            return {
+                found: true,
+                source: "package.json",
+                config: finalValidated,
+            };
+        }
+        catch (e) {
+            if (isNodeFsError(e) && e.code === "ENOENT") {
+                return { found: false, source: "package.json", config: undefined };
+            }
+            throw e;
+        }
+    },
+};

package/dist/config/sources/rc.loader.js

@@ -0,0 +1,26 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { validateProjectConfigSource, validateProjectConfigFinal } from "../validate.js";
+export const RC_FILENAME = ".newbranchrc.json";
+function isNodeFsError(e) {
+    return typeof e === "object" && e !== null && "code" in e;
+}
+export const rcLoader = {
+    source: "rc",
+    async load() {
+        try {
+            const path = join(process.cwd(), RC_FILENAME);
+            const raw = await readFile(path, "utf8");
+            const parsed = JSON.parse(raw);
+            const sourceValidated = validateProjectConfigSource(parsed, RC_FILENAME);
+            const finalValidated = validateProjectConfigFinal(sourceValidated, RC_FILENAME);
+            return { found: true, source: "rc", config: finalValidated };
+        }
+        catch (e) {
+            if (isNodeFsError(e) && e.code === "ENOENT") {
+                return { found: false, source: "rc", config: undefined };
+            }
+            throw e;
+        }
+    },
+};

package/dist/config/types.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview
+ * Core types for `new-branch` configuration system.
+ *
+ * Naming consistency:
+ * Always use `new-branch` (never `newBranch` or `newbranch`).
+ */
+export {};

package/dist/config/validate.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview
+ * Validation + normalization logic for `new-branch` configuration.
+ *
+ * Strategy:
+ * 1) validateProjectConfigSource → structural validation per source
+ * 2) validateProjectConfigFinal → cross-field business rules
+ */
+/**
+ * Throws a standardized configuration error.
+ */
+function invariant(condition, source, message) {
+    if (!condition) {
+        throw new Error(`Invalid new-branch config from ${source}: ${message}`);
+    }
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null;
+}
+function isString(v) {
+    return typeof v === "string";
+}
+function trimOrUndefined(v) {
+    const t = v.trim();
+    return t.length > 0 ? t : undefined;
+}
+function normalizeBranchType(raw, source) {
+    invariant(isObject(raw), source, "types[] must be an object");
+    const obj = raw;
+    const value = trimOrUndefined(String(obj.value ?? ""));
+    const label = trimOrUndefined(String(obj.label ?? ""));
+    invariant(value, source, "types[].value cannot be empty");
+    invariant(label, source, "types[].label cannot be empty");
+    return { value, label };
+}
+/**
+ * Structural validation for a single source.
+ */
+export function validateProjectConfigSource(raw, source) {
+    invariant(isObject(raw), source, "config must be an object");
+    const obj = raw;
+    const cfg = {};
+    if ("pattern" in obj) {
+        invariant(isString(obj.pattern), source, "pattern must be a string");
+        cfg.pattern = trimOrUndefined(obj.pattern);
+    }
+    if ("defaultType" in obj) {
+        invariant(isString(obj.defaultType), source, "defaultType must be a string");
+        cfg.defaultType = trimOrUndefined(obj.defaultType);
+    }
+    if ("types" in obj) {
+        const typesVal = obj.types;
+        invariant(Array.isArray(typesVal), source, "types must be an array");
+        cfg.types = typesVal.map((t) => normalizeBranchType(t, source));
+    }
+    return cfg;
+}
+/**
+ * Final cross-field validation.
+ */
+export function validateProjectConfigFinal(cfg, source) {
+    if (cfg.types) {
+        invariant(cfg.types.length > 0, source, "types cannot be empty");
+    }
+    if (cfg.defaultType && cfg.types) {
+        const exists = cfg.types.some((t) => t.value === cfg.defaultType);
+        invariant(exists, source, `defaultType "${cfg.defaultType}" must exist in types`);
+    }
+    return cfg;
+}

package/dist/git/gitBuiltins.js

@@ -0,0 +1,79 @@
+import { getGitConfig } from "../git/gitConfig.js";
+import { execa } from "execa";
+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 = String(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

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

package/dist/parseArgs.js

@@ -21,11 +21,14 @@ export function parseArgs(argv = process.argv) {
     const parsed = cli.parse(cleaned);
     const opts = parsed.options;
     const options = {
-        pattern: typeof opts.pattern === "string" ? opts.pattern : undefined,
-        id: typeof opts.id === "string" ? opts.id : undefined,
-        title: typeof opts.title === "string" ? opts.title : undefined,
-        type: typeof opts.type === "string" ? opts.type : undefined,
+        // Accept numeric or string-like values and coerce to string when present.
+        pattern: opts.pattern !== undefined ? String(opts.pattern) : undefined,
+        id: opts.id !== undefined ? String(opts.id) : undefined,
+        title: opts.title !== undefined ? String(opts.title) : undefined,
+        type: opts.type !== undefined ? String(opts.type) : undefined,
         create: typeof opts.create === "boolean" ? opts.create : undefined,
+        // CAC provides `--no-prompt` as `noPrompt` normally, but the flag will
+        // also be available as `prompt` when parsed; keep boolean handling.
         prompt: typeof opts.prompt === "boolean" ? opts.prompt : undefined,
         quiet: typeof opts.quiet === "boolean" ? opts.quiet : undefined,
         help: typeof opts.help === "boolean" ? opts.help : undefined,

package/dist/runtime/resolveMissingValues.js

@@ -1,4 +1,3 @@
-import { input, select } from "@inquirer/prompts";
 import { TYPE_CHOICES } from "../runtime/enums.js";
 /**
  * Resolves missing variable values required by a parsed pattern.
@@ -40,10 +39,17 @@ export async function resolveMissingValues(parsed, initialValues, opts) {
         if (!opts.prompt) {
             throw new Error(`Missing required value: "${name}"`);
         }
+        // Lazily import the interactive prompts to avoid importing
+        // `@inquirer/prompts` at module load time. This prevents environments
+        // with incompatible Node.js versions from failing when the CLI is
+        // executed in non-interactive mode (e.g., `--no-prompt`).
+        const prompts = await import("@inquirer/prompts");
+        const { input, select } = prompts;
         if (name === "type") {
+            const choices = opts.typeChoices ?? TYPE_CHOICES;
             const selected = await select({
                 message: "Select branch type:",
-                choices: TYPE_CHOICES,
+                choices,
             });
             values[name] = selected;
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new-branch",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -41,9 +42,6 @@
   "bugs": {
     "url": "https://github.com/teles/new-branch/issues"
   },
-  "new-branch": {
-    "pattern": "{type}/{title:lower}-{id}"
-  },
   "homepage": "https://github.com/teles/new-branch#readme",
   "packageManager": "pnpm@10.22.0",
   "devDependencies": {

package/dist/config/loadProjectConfig.js

@@ -1,19 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-export async function loadProjectConfig() {
-    try {
-        const path = join(process.cwd(), "package.json");
-        const raw = await readFile(path, "utf8");
-        const pkg = JSON.parse(raw);
-        const config = pkg["new-branch"];
-        if (!config || typeof config !== "object")
-            return {};
-        const cfg = config;
-        return {
-            pattern: typeof cfg.pattern === "string" ? cfg.pattern : undefined,
-        };
-    }
-    catch {
-        return {};
-    }
-}