new-branch 0.5.0 → 0.7.0

package/README.md

@@ -177,31 +177,63 @@ Disable prompts with:
 
 ---
 
-## Project Configuration
+## Project Configuration and precedence
 
-You can define a default pattern in `package.json`:
+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.
+
+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:
 
@@ -213,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

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 import { parseArgs } from "./parseArgs.js";
 import { parsePattern } from "./pattern/parsePattern.js";
-import { defaultTransforms } from "./pattern/transforms/index.js";
+import { allTransforms, 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 { loadConfigWithSource } 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";
+import { listTransforms } from "./didactic/listTransforms.js";
+import { printConfig } from "./didactic/printConfig.js";
+import { explain } from "./didactic/explain.js";
 const ok = (value) => ({ ok: true, value });
 const err = (error) => ({ ok: false, error });
 const isOk = (r) => r.ok;
@@ -50,27 +53,76 @@ 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;
     }
+    // --- Didactic mode: --list-transforms ---
+    if (args.options.listTransforms) {
+        console.log(listTransforms(allTransforms));
+        return;
+    }
     const quiet = args.options.quiet === true;
     const create = args.options.create === true;
     const prompt = args.options.prompt !== false;
+    const isExplain = args.options.explain === true;
     // Pipeline: pattern -> AST -> resolve values -> render -> sanitize -> validate -> (optional) git -> output
-    const projectConfig = await loadProjectConfig();
+    const { config: projectConfig, source: configSource } = await loadConfigWithSource();
+    // --- Didactic mode: --print-config ---
+    if (args.options.printConfig) {
+        console.log(printConfig(projectConfig, configSource));
+        return;
+    }
     // Git config (respects local -> global precedence automatically)
     let gitPattern;
-    if (!args.options.pattern && !projectConfig.pattern) {
+    if (!args.options.pattern && !args.options.use && !projectConfig.pattern) {
         gitPattern = await getGitConfig("new-branch.pattern");
     }
-    const resolvedPattern = args.options.pattern ?? projectConfig.pattern ?? gitPattern;
+    // Resolution logic for --use:
+    // If --pattern is provided, use it directly (highest precedence).
+    // If --use is provided, resolve from patterns config. Error if alias not found.
+    // Otherwise, fall back to configured pattern or git config.
+    let useAliasPattern;
+    if (!args.options.pattern && args.options.use) {
+        const aliasName = args.options.use;
+        const aliasPattern = projectConfig.patterns?.[aliasName];
+        if (!aliasPattern) {
+            fail(`Unknown pattern alias "${aliasName}". Available aliases: ${projectConfig.patterns
+                ? Object.keys(projectConfig.patterns).join(", ")
+                : "(none configured)"}`);
+        }
+        useAliasPattern = aliasPattern;
+    }
+    const resolvedPattern = args.options.pattern ?? useAliasPattern ?? projectConfig.pattern ?? gitPattern;
+    const patternSource = args.options.pattern
+        ? "CLI --pattern"
+        : useAliasPattern
+            ? `CLI --use (${args.options.use})`
+            : projectConfig.pattern
+                ? configSource
+                : gitPattern
+                    ? "git config"
+                    : "(none)";
     const patternRes = requirePattern(resolvedPattern);
     if (!isOk(patternRes))
         fail("Invalid CLI arguments.", patternRes.error);
@@ -89,13 +141,28 @@ export async function run() {
         // 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);
@@ -106,6 +173,22 @@ export async function run() {
     if (!isOk(renderedRes))
         fail("Failed to render branch name.", renderedRes.error);
     const sanitized = sanitizeGitRef(renderedRes.value);
+    // --- Didactic mode: --explain ---
+    if (isExplain) {
+        console.log(explain({
+            pattern: patternRes.value,
+            patternSource,
+            ast: astRes.value,
+            resolvedValues: valuesRes.value,
+            cliValues: toInitialValues(args),
+            builtinValues,
+            gitValues,
+            rendered: renderedRes.value,
+            sanitized,
+            transforms: defaultTransforms,
+        }));
+        return;
+    }
     const validateRes = await safeAsync(() => validateBranchName(sanitized));
     if (!isOk(validateRes))
         fail("Branch name is not valid for git.", validateRes.error);

package/dist/config/loadConfig.js

@@ -0,0 +1,35 @@
+/**
+ * @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() {
+    const { config } = await loadConfigWithSource();
+    return config;
+}
+/**
+ * Loads the first configuration found and reports which source provided it.
+ */
+export async function loadConfigWithSource() {
+    const rcRes = await rcLoader.load();
+    if (rcRes.found && rcRes.config && Object.keys(rcRes.config).length > 0)
+        return { config: rcRes.config, source: ".newbranchrc.json" };
+    const pkgRes = await packageJsonLoader.load();
+    if (pkgRes.found && pkgRes.config && Object.keys(pkgRes.config).length > 0)
+        return { config: pkgRes.config, source: "package.json" };
+    const gitRes = await gitLoader.load();
+    if (gitRes.found)
+        return { config: gitRes.config ?? {}, source: "git config" };
+    return { config: {}, source: "(none)" };
+}

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

@@ -0,0 +1,56 @@
+import { getGitConfig, getGitConfigRegexp } 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(),
+        };
+    });
+}
+const PATTERNS_PREFIX = "new-branch.patterns.";
+function parseGitPatterns(entries) {
+    if (entries.length === 0)
+        return undefined;
+    const result = {};
+    for (const [key, value] of entries) {
+        const name = key.slice(PATTERNS_PREFIX.length);
+        if (name && value) {
+            result[name] = value;
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+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");
+        const patternsEntries = await getGitConfigRegexp("^new-branch\\.patterns\\.");
+        if (!pattern && !defaultType && !typesRaw && patternsEntries.length === 0) {
+            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 patterns = parseGitPatterns(patternsEntries);
+        if (patterns)
+            cfg.patterns = patterns;
+        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,85 @@
+/**
+ * @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 ("patterns" in obj) {
+        const patternsVal = obj.patterns;
+        invariant(isObject(patternsVal), source, "patterns must be an object");
+        const entries = Object.entries(patternsVal);
+        const normalized = {};
+        for (const [key, val] of entries) {
+            invariant(isString(val), source, `patterns["${key}"] must be a string`);
+            const trimmed = trimOrUndefined(val);
+            invariant(trimmed, source, `patterns["${key}"] cannot be empty`);
+            normalized[key] = trimmed;
+        }
+        if (Object.keys(normalized).length > 0) {
+            cfg.patterns = normalized;
+        }
+    }
+    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/didactic/explain.js

@@ -0,0 +1,67 @@
+/**
+ * Produces a structured breakdown of the full branch-name pipeline.
+ *
+ * No branch is created — this is purely informational.
+ * Used by the `--explain` CLI flag.
+ */
+export function explain(input) {
+    const lines = [];
+    lines.push("Pipeline explanation:\n");
+    // 1. Pattern
+    lines.push(`  Pattern:        ${input.pattern}`);
+    lines.push(`  Pattern source: ${input.patternSource}`);
+    // 2. Variables used
+    const vars = input.ast.variablesUsed;
+    lines.push(`\n  Variables used:  ${vars.length > 0 ? vars.join(", ") : "(none)"}`);
+    // 3. Builtin values
+    const builtinEntries = Object.entries(input.builtinValues).filter(([, v]) => v !== undefined);
+    if (builtinEntries.length > 0) {
+        lines.push(`\n  Builtin values:`);
+        for (const [k, v] of builtinEntries) {
+            lines.push(`    ${k} = "${v}"`);
+        }
+    }
+    // 4. Git values
+    const gitEntries = Object.entries(input.gitValues).filter(([, v]) => v !== undefined);
+    if (gitEntries.length > 0) {
+        lines.push(`\n  Git values:`);
+        for (const [k, v] of gitEntries) {
+            lines.push(`    ${k} = "${v}"`);
+        }
+    }
+    // 5. CLI values
+    const cliEntries = Object.entries(input.cliValues).filter(([, v]) => v !== undefined);
+    if (cliEntries.length > 0) {
+        lines.push(`\n  CLI values:`);
+        for (const [k, v] of cliEntries) {
+            lines.push(`    ${k} = "${v}"`);
+        }
+    }
+    // 6. Transforms applied — with intermediate values
+    const transformNodes = input.ast.nodes.filter((n) => n.kind === "variable" && n.transforms.length > 0);
+    if (transformNodes.length > 0) {
+        lines.push(`\n  Transforms applied:`);
+        for (const node of transformNodes) {
+            if (node.kind !== "variable")
+                continue;
+            const initial = input.resolvedValues[node.name] ?? "";
+            lines.push(`    {${node.name}} = "${initial}"`);
+            let current = initial;
+            for (const t of node.transforms) {
+                const fn = input.transforms[t.name];
+                if (fn) {
+                    current = fn(current, t.args);
+                }
+                const argsStr = t.args.length > 0 ? `:${t.args.join(":")}` : "";
+                lines.push(`      → ${t.name}${argsStr} → "${current}"`);
+            }
+        }
+    }
+    // 7. Final result
+    lines.push(`\n  Rendered:       ${input.rendered}`);
+    if (input.rendered !== input.sanitized) {
+        lines.push(`  Sanitized:      ${input.sanitized}`);
+    }
+    lines.push(`\n  Final branch:   ${input.sanitized}`);
+    return lines.join("\n");
+}

package/dist/didactic/listTransforms.js

@@ -0,0 +1,21 @@
+/**
+ * Prints a formatted table of all available transforms.
+ *
+ * Each transform is listed with its name, summary and usage example.
+ * This is used by the `--list-transforms` CLI flag.
+ */
+export function listTransforms(transforms) {
+    const lines = [];
+    lines.push("Available transforms:\n");
+    const maxName = Math.max(...transforms.map((t) => t.name.length));
+    for (const t of transforms) {
+        const name = t.name.padEnd(maxName + 2);
+        const summary = t.doc?.summary ?? "(no description)";
+        const usage = t.doc?.usage?.[0] ?? "";
+        lines.push(`  ${name}${summary}`);
+        if (usage) {
+            lines.push(`  ${"".padEnd(maxName + 2)}Example: ${usage}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/didactic/printConfig.js

@@ -0,0 +1,23 @@
+/**
+ * Formats the resolved configuration for display.
+ *
+ * Shows the final resolved values from whichever source took precedence.
+ * This is used by the `--print-config` CLI flag.
+ */
+export function printConfig(config, source) {
+    const lines = [];
+    lines.push("Resolved configuration:\n");
+    lines.push(`  Source:       ${source}`);
+    lines.push(`  Pattern:      ${config.pattern ?? "(not set)"}`);
+    lines.push(`  Default type: ${config.defaultType ?? "(not set)"}`);
+    if (config.types && config.types.length > 0) {
+        lines.push(`  Types:`);
+        for (const t of config.types) {
+            lines.push(`    - ${t.value} (${t.label})`);
+        }
+    }
+    else {
+        lines.push(`  Types:        (not configured)`);
+    }
+    return lines.join("\n");
+}

package/dist/git/gitBuiltins.js

@@ -1,5 +1,5 @@
-import { execa } from "execa";
 import { getGitConfig } from "../git/gitConfig.js";
+import { execa } from "execa";
 export const GIT_BUILTIN_KEYS = [
     "shortSha",
     "currentBranch",
@@ -15,8 +15,8 @@ function pickAllKeysIfUndefined(keys) {
 }
 async function safeExec(args) {
     try {
-        const { stdout } = await execa("git", args);
-        const value = stdout.trim();
+        const { stdout } = (await execa("git", args));
+        const value = String(stdout ?? "").trim();
         return value.length ? value : undefined;
     }
     catch {

package/dist/git/gitConfig.js

@@ -1,11 +1,39 @@
 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 {
         return undefined;
     }
 }
+/**
+ * Returns all git config entries matching a key prefix using `--get-regexp`.
+ * Each entry is returned as a `[key, value]` tuple.
+ *
+ * Example: `getGitConfigRegexp("new-branch.patterns\\.")` returns
+ * `[["new-branch.patterns.hotfix", "hotfix/{id}"], ...]`
+ */
+export async function getGitConfigRegexp(pattern) {
+    try {
+        const { stdout } = (await execa("git", ["config", "--get-regexp", pattern]));
+        const raw = String(stdout ?? "").trim();
+        if (!raw.length)
+            return [];
+        return raw.split("\n").reduce((acc, line) => {
+            const idx = line.indexOf(" ");
+            if (idx === -1)
+                return acc;
+            const key = line.slice(0, idx);
+            const value = line.slice(idx + 1);
+            if (key && value)
+                acc.push([key, value]);
+            return acc;
+        }, []);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/parseArgs.js

@@ -10,25 +10,36 @@ export function parseArgs(argv = process.argv) {
     const cli = cac("new-branch");
     cli
         .option("-p, --pattern <pattern>", "Branch pattern")
+        .option("--use <name>", "Use a named pattern alias from configuration")
         .option("--id <id>", "Task id")
         .option("--title <title>", "Task title")
         .option("--type <type>", "Branch type")
         .option("--create", "Create branch")
         .option("--no-prompt", "Fail instead of prompting for missing values")
         .option("--quiet", "Suppress non-essential output")
+        .option("--explain", "Show a detailed breakdown of the branch pipeline without creating a branch")
+        .option("--list-transforms", "List all available transforms")
+        .option("--print-config", "Print the resolved configuration")
         .help();
     const cleaned = stripDoubleDash(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,
+        use: opts.use !== undefined ? String(opts.use) : 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,
+        explain: typeof opts.explain === "boolean" ? opts.explain : undefined,
+        listTransforms: typeof opts.listTransforms === "boolean" ? opts.listTransforms : undefined,
+        printConfig: typeof opts.printConfig === "boolean" ? opts.printConfig : undefined,
     };
     return {
         options,

package/dist/pattern/transforms/after.js

@@ -0,0 +1,12 @@
+export const after = {
+    name: "after",
+    fn: (value, [suffix]) => {
+        if (suffix === undefined)
+            throw new Error("after requires one argument: {var:after:suffix}");
+        return value === "" ? "" : value + suffix;
+    },
+    doc: {
+        summary: "Adds a suffix only if the value is not empty.",
+        usage: ["{title:after:-wip}"],
+    },
+};

package/dist/pattern/transforms/before.js

@@ -0,0 +1,12 @@
+export const before = {
+    name: "before",
+    fn: (value, [prefix]) => {
+        if (prefix === undefined)
+            throw new Error("before requires one argument: {var:before:prefix}");
+        return value === "" ? "" : prefix + value;
+    },
+    doc: {
+        summary: "Adds a prefix only if the value is not empty.",
+        usage: ["{title:before:hotfix-}"],
+    },
+};

package/dist/pattern/transforms/ifEmpty.js

@@ -0,0 +1,12 @@
+export const ifEmpty = {
+    name: "ifEmpty",
+    fn: (value, [fallback]) => {
+        if (fallback === undefined)
+            throw new Error("ifEmpty requires one argument: {var:ifEmpty:fallback}");
+        return value === "" ? fallback : value;
+    },
+    doc: {
+        summary: "Provides a fallback value if the result is empty.",
+        usage: ["{title:slugify:ifEmpty:no-title}"],
+    },
+};

package/dist/pattern/transforms/index.js

@@ -8,6 +8,13 @@ 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";
+import { replace } from "../../pattern/transforms/replace.js";
+import { replaceAll } from "../../pattern/transforms/replaceAll.js";
+import { remove } from "../../pattern/transforms/remove.js";
+import { stripAccents } from "../../pattern/transforms/stripAccents.js";
+import { ifEmpty } from "../../pattern/transforms/ifEmpty.js";
+import { before } from "../../pattern/transforms/before.js";
+import { after } from "../../pattern/transforms/after.js";
 export const allTransforms = [
     lower,
     upper,
@@ -18,5 +25,12 @@ export const allTransforms = [
     snake,
     title,
     words,
+    replace,
+    replaceAll,
+    remove,
+    stripAccents,
+    ifEmpty,
+    before,
+    after,
 ];
 export const defaultTransforms = buildRegistry(allTransforms);

package/dist/pattern/transforms/remove.js

@@ -0,0 +1,12 @@
+export const remove = {
+    name: "remove",
+    fn: (value, [target]) => {
+        if (target === undefined)
+            throw new Error("remove requires one argument: {var:remove:substring}");
+        return value.replaceAll(target, "");
+    },
+    doc: {
+        summary: "Removes all occurrences of a substring.",
+        usage: ["{title:remove:temp}"],
+    },
+};

package/dist/pattern/transforms/replace.js

@@ -0,0 +1,12 @@
+export const replace = {
+    name: "replace",
+    fn: (value, [search, replacement]) => {
+        if (search === undefined || replacement === undefined)
+            throw new Error("replace requires two arguments: {var:replace:search:replacement}");
+        return value.replace(search, replacement);
+    },
+    doc: {
+        summary: "Replaces the first occurrence of a substring.",
+        usage: ["{title:replace:foo:bar}"],
+    },
+};

package/dist/pattern/transforms/replaceAll.js

@@ -0,0 +1,12 @@
+export const replaceAll = {
+    name: "replaceAll",
+    fn: (value, [search, replacement]) => {
+        if (search === undefined || replacement === undefined)
+            throw new Error("replaceAll requires two arguments: {var:replaceAll:search:replacement}");
+        return value.replaceAll(search, replacement);
+    },
+    doc: {
+        summary: "Replaces all occurrences of a substring.",
+        usage: ["{title:replaceAll:foo:bar}"],
+    },
+};

package/dist/pattern/transforms/stripAccents.js

@@ -0,0 +1,9 @@
+export const stripAccents = {
+    name: "stripAccents",
+    fn: (value) => value.normalize("NFD").replace(/[\u0300-\u036f]/g, ""),
+    doc: {
+        summary: "Removes diacritics from characters.",
+        usage: ["{title:stripAccents}"],
+        examples: ["José → Jose"],
+    },
+};

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.5.0",
+  "version": "0.7.0",
   "description": "Generate and create standardized git branch names from a pattern.",
   "keywords": [
     "git",
@@ -42,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 {};
-    }
-}