new-branch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,490 @@
+# new-branch CLI --- Specification
+
+## 1. Overview
+
+`new-branch` is a CLI tool for generating standardized Git branch names
+based on a configurable pattern and optional interactive prompts.
+
+It can be executed in two ways:
+
+```bash
+npx new-branch
+git nb
+```
+
+---
+
+## 2. Goals
+
+- Standardize branch naming across teams.
+- Provide interactive and non-interactive modes.
+- Support a composable transformation pipeline (functional style).
+- Ensure generated names are always valid Git references.
+- Be easily extensible via custom transforms.
+
+---
+
+## 3. Usage
+
+### 3.1 Basic
+
+```bash
+npx new-branch
+```
+
+Runs in interactive mode if required fields are missing.
+
+---
+
+### 3.2 With config file
+
+```bash
+npx new-branch --config .newbranchrc
+```
+
+Alias:
+
+```bash
+npx new-branch -c .newbranchrc
+```
+
+---
+
+### 3.3 With custom pattern
+
+```bash
+npx new-branch --pattern "{type}/{title:slugify;max:25}-{id}"
+```
+
+Alias:
+
+```bash
+npx new-branch -p "{type}/{title:slugify;max:25}-{id}"
+```
+
+---
+
+### 3.4 Non-interactive mode
+
+```bash
+npx new-branch   --pattern "{type}/{title:slugify;max:25}-{id}"   --id STK-123   --title "My very interesting task"   --type feat
+```
+
+If all required variables are provided, no prompt is shown.
+
+---
+
+## 4. Configuration Precedence
+
+Resolution order (highest priority first):
+
+1.  CLI flags
+2.  Environment variables
+3.  Config file (.newbranchrc)
+4.  Defaults
+5.  Interactive prompt (only if required values are missing)
+
+---
+
+## 5. Pattern Language
+
+### 5.1 Syntax
+
+Pattern example:
+
+    {type}/{title:slugify;max:25}-{id}
+
+Structure:
+
+    {variable:transform1;transform2;transformWithArg:arg}
+
+### 5.2 Parsing Model
+
+Each token is parsed into:
+
+- variable name
+- ordered list of transforms
+- optional arguments per transform
+
+Example AST representation:
+
+```json
+{
+  "variable": "title",
+  "pipeline": [{ "fn": "slugify" }, { "fn": "max", "args": [25] }]
+}
+```
+
+---
+
+## 6. Built-in Variables
+
+Variable Description
+
+---
+
+type Branch type (feat, fix, etc.)
+title Human-readable task title
+id Task identifier (e.g., STK-123)
+
+---
+
+## 7. Built-in Transforms
+
+All transforms must be pure functions.
+
+### 7.1 String Transforms
+
+| Transform \| Description \|
+
+\|------------\|-------------\| slugify \| Converts to URL-safe slug \|
+\| lowercase \| Converts to lowercase \| \| uppercase \| Converts to
+uppercase \| \| trim \| Trims whitespace \| \| titlecase \| Capitalizes
+words \|
+
+### 7.2 Argument-based Transforms
+
+| Transform \| Description \| Example \|
+
+\|------------\|-------------\|---------\| max \| Truncates string to
+max length \| max:25 \| \| pad \| Pads string to length \| pad:10 \|
+
+### 7.3 Validation Transforms
+
+Validation transforms do not modify value but throw errors if invalid.
+
+| Transform \| Description \|
+
+\|------------\|-------------\| required \| Ensures value is not empty
+\| \| match \| Validates via regex \|
+
+---
+
+## 8. Functional Pipeline Execution
+
+Each variable pipeline is executed using reduce semantics:
+
+```js
+pipeline.reduce((acc, step) => {
+  return transforms[step.fn](acc, ...step.args);
+}, baseValue);
+```
+
+All transforms must be registered in a dictionary:
+
+```js
+const transforms = {
+  slugify,
+  lowercase,
+  uppercase,
+  max,
+  trim,
+};
+```
+
+---
+
+## 9. Git Ref Sanitization
+
+After full pattern rendering, a final sanitization step must run:
+
+- Remove invalid Git characters
+- Prevent:
+  - trailing slash
+  - double dots
+  - leading dash
+  - spaces
+- Ensure valid Git ref format
+
+Final step example:
+
+```js
+branchName = sanitizeGitRef(branchName);
+```
+
+---
+
+## 10. Branch Type Standardization
+
+Supported types:
+
+- feat
+- fix
+- chore
+- docs
+- refactor
+- test
+- perf
+- build
+- ci
+
+Optional alias mapping:
+
+- feature → feat
+- bugfix → fix
+
+---
+
+## 11. Interactive Mode Behavior
+
+If required values are missing:
+
+Prompt user for: - type - id - title
+
+Validation must occur immediately after input.
+
+---
+
+## 12. Optional Flags
+
+Flag Description
+
+---
+
+--create Creates branch using `git switch -c`
+--print Prints branch name only (default behavior)
+
+---
+
+## 13. Example Outputs
+
+Input:
+
+    type = feat
+    title = My very interesting task
+    id = STK-123
+
+Pattern:
+
+    {type}/{title:slugify;max:25}-{id}
+
+Output:
+
+    feat/my-very-interesting-task-STK-123
+
+---
+
+## 14. Future Extensions
+
+- Custom transform plugins
+- Jira integration (auto-fetch title from ID)
+- Branch existence check
+- Automatic incremental suffixing
+- Conventional commits integration
+
+---
+
+## 15. Summary
+
+`new-branch` is a composable, functional, extensible CLI tool for
+standardized Git branch naming.
+
+Core principles:
+
+- Functional pipeline transforms
+- Deterministic output
+- Git-safe sanitization
+- Clear precedence rules
+- Interactive fallback
+
+# new-branch
+
+A small CLI tool to generate and optionally create standardized Git branch names
+based on a composable pattern language.
+
+---
+
+## Installation
+
+Using npx:
+
+```bash
+npx new-branch
+```
+
+Or install globally:
+
+```bash
+npm install -g new-branch
+```
+
+---
+
+## Usage
+
+### Generate a branch name
+
+```bash
+new-branch \
+  --pattern "{type}/{title:slugify}-{id}" \
+  --type feat \
+  --title "My task" \
+  --id STK-123
+```
+
+Output:
+
+```
+feat/minha-tarefa-STK-123
+```
+
+---
+
+### Create the branch automatically
+
+```bash
+new-branch \
+  --pattern "{type:upper}/{title:slugify}-{id}" \
+  --type feat \
+  --title "My task" \
+  --id STK-123 \
+  --create
+```
+
+This runs:
+
+```
+git switch -c <generated-branch>
+```
+
+---
+
+### Interactive mode
+
+If required variables in the pattern are missing, the CLI will prompt for them.
+
+Example:
+
+```bash
+new-branch \
+  --pattern "{type:upper}/{title:slugify}-{id}" \
+  --title "My task" \
+  --id STK-123 \
+  --create
+```
+
+You will be prompted for `type`.
+
+---
+
+## CLI Options
+
+| Option                    | Description                                  |
+| ------------------------- | -------------------------------------------- |
+| `-p, --pattern <pattern>` | Branch name pattern                          |
+| `--id <id>`               | Task ID                                      |
+| `--title <title>`         | Task title                                   |
+| `--type <type>`           | Branch type                                  |
+| `--create`                | Create the branch using `git switch -c`      |
+| `--no-prompt`             | Fail instead of prompting for missing values |
+| `--quiet`                 | Do not print any output                      |
+
+---
+
+## Pattern Language
+
+Branch names are generated from a pattern string.
+
+Example:
+
+```
+{type}/{title:slugify;max:25}-{id}
+```
+
+### Syntax
+
+```
+{variable:transform1;transform2:arg}
+```
+
+- Variables are wrapped in `{}`
+- Transforms are separated by `;`
+- Transform arguments are separated by `:`
+
+---
+
+## Built-in Variables
+
+These variables are currently supported:
+
+- `type`
+- `title`
+- `id`
+
+---
+
+## Built-in Transforms
+
+All transforms are pure functions and executed left-to-right.
+
+### String transforms
+
+| Transform | Description                 |
+| --------- | --------------------------- |
+| `lower`   | Lowercases the value        |
+| `upper`   | Uppercases the value        |
+| `slugify` | Converts to a git-safe slug |
+
+### Argument-based transforms
+
+| Transform | Description                    | Example  |
+| --------- | ------------------------------ | -------- |
+| `max`     | Truncates string to max length | `max:25` |
+
+Example:
+
+```
+{title:slugify;max:25}
+```
+
+---
+
+## Git Ref Validation
+
+After rendering, branch names are:
+
+1. Lightly sanitized
+2. Validated using `git check-ref-format --branch`
+
+If invalid, the command fails.
+
+---
+
+## Example
+
+Input:
+
+```
+type = feat
+title = My task
+id = STK-123
+```
+
+Pattern:
+
+```
+{type}/{title:slugify;max:25}-{id}
+```
+
+Output:
+
+```
+feat/my-task-STK-123
+```
+
+---
+
+## Roadmap
+
+Planned future features:
+
+- Config file support
+- Custom transform plugins
+- Additional variable providers (e.g. git username, date)
+- Branch existence checks
+
+---
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { parseArgs } from "./parseArgs.js";
+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 { sanitizeGitRef } from "./git/sanitizeGitRef.js";
+import { validateBranchName } from "./git/validateBranchName.js";
+import { createBranch } from "./git/createBranch.js";
+const ok = (value) => ({ ok: true, value });
+const err = (error) => ({ ok: false, error });
+const isOk = (r) => r.ok;
+function fail(msg, e) {
+    console.error(`\n❌ ${msg}`);
+    if (e)
+        console.error(e);
+    process.exit(1);
+}
+function safe(fn) {
+    try {
+        return ok(fn());
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+async function safeAsync(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+function requirePattern(pattern) {
+    if (!pattern || pattern.trim().length === 0) {
+        return err(new Error("Pattern is required. Use --pattern to specify it."));
+    }
+    return ok(pattern);
+}
+function toInitialValues(args) {
+    return {
+        id: args.options.id,
+        title: args.options.title,
+        type: args.options.type,
+    };
+}
+async function run() {
+    // Step 0: args/options
+    const args = parseArgs(process.argv);
+    if (args.options.help) {
+        return;
+    }
+    const quiet = args.options.quiet === true;
+    const create = args.options.create === true;
+    const prompt = args.options.prompt !== false;
+    // Pipeline: pattern -> AST -> resolve values -> render -> sanitize -> validate -> (optional) git -> output
+    const patternRes = requirePattern(args.options.pattern);
+    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);
+    const valuesRes = await safeAsync(() => resolveMissingValues(astRes.value, initialValues, {
+        prompt,
+    }));
+    if (!isOk(valuesRes))
+        fail("Failed to resolve required values.", valuesRes.error);
+    const renderedRes = safe(() => renderPattern(astRes.value, valuesRes.value, {
+        transforms: defaultTransforms,
+        strict: true,
+    }));
+    if (!isOk(renderedRes))
+        fail("Failed to render branch name.", renderedRes.error);
+    const sanitized = sanitizeGitRef(renderedRes.value);
+    const validateRes = await safeAsync(() => validateBranchName(sanitized));
+    if (!isOk(validateRes))
+        fail("Branch name is not valid for git.", validateRes.error);
+    const ctx = {
+        quiet,
+        create,
+        prompt,
+        pattern: patternRes.value,
+        ast: astRes.value,
+        values: valuesRes.value,
+        branchName: sanitized,
+    };
+    const createRes = create ? await safeAsync(() => createBranch(ctx.branchName)) : ok(undefined);
+    if (!isOk(createRes))
+        fail("Failed to create branch.", createRes.error);
+    if (!ctx.quiet) {
+        if (ctx.create) {
+            console.log(`\n✅ Branch created and switched to: ${ctx.branchName}`);
+        }
+        else {
+            console.log(ctx.branchName);
+        }
+    }
+}
+run().catch((e) => fail("Unexpected error in CLI.", e));

package/dist/git/createBranch.js

@@ -0,0 +1,25 @@
+import { execa } from "execa";
+/**
+ * Creates and switches to a new Git branch.
+ *
+ * Strategy:
+ * 1. Try `git switch -c <name>` (modern Git ≥ 2.23).
+ * 2. Fallback to `git checkout -b <name>` if switch is unavailable.
+ *
+ * @throws Error if branch creation fails.
+ */
+export async function createBranch(name) {
+    try {
+        await execa("git", ["switch", "-c", name]);
+        return;
+    }
+    catch {
+        try {
+            await execa("git", ["checkout", "-b", name]);
+            return;
+        }
+        catch {
+            throw new Error(`Failed to create branch "${name}"`);
+        }
+    }
+}

package/dist/git/sanitizeGitRef.js

@@ -0,0 +1,32 @@
+/**
+ * Performs a lightweight sanitization before delegating
+ * full validation to Git.
+ *
+ * This does NOT try to fully reimplement Git rules.
+ * Final validation must be done via:
+ *   git check-ref-format --branch
+ */
+export function sanitizeGitRef(input) {
+    let name = input.trim();
+    // Replace whitespace with "-"
+    name = name.replace(/\s+/g, "-");
+    // Remove characters Git never allows in refs
+    // ~ ^ : ? * [ \ and ASCII control chars
+    name = name.replace(/[~^:?*[\]\\]/g, "");
+    //   name = name.replace(/[\u0000-\u001F\u007F]/g, "");
+    // Remove occurrences of "@{"
+    name = name.replace(/@\{/g, "");
+    // Collapse multiple slashes
+    name = name.replace(/\/+/g, "/");
+    // Remove repeated dots
+    name = name.replace(/\.\.+/g, ".");
+    // Prevent leading dash or slash
+    name = name.replace(/^[-/]+/, "");
+    // Prevent trailing slash or dot
+    name = name.replace(/[/.]+$/, "");
+    // Prevent ending with ".lock"
+    if (name.endsWith(".lock")) {
+        name = name.slice(0, -5);
+    }
+    return name;
+}

package/dist/git/sanitizeGitRef.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { sanitizeGitRef } from "./sanitizeGitRef.js";
+describe("sanitizeGitRef", () => {
+    it("trims input and replaces whitespace with dashes", () => {
+        expect(sanitizeGitRef("  feature  new   ")).toBe("feature-new");
+    });
+    it("removes forbidden characters and sequences", () => {
+        const input = "~^:??*[\\]name@{weird}";
+        // forbidden chars removed and @{ removed
+        expect(sanitizeGitRef(input)).toBe("nameweird}");
+    });
+    it("collapses multiple slashes and removes leading/trailing slashes", () => {
+        expect(sanitizeGitRef("///a//b/c///")).toBe("a/b/c");
+    });
+    it("collapses repeated dots and trims trailing dots", () => {
+        expect(sanitizeGitRef("v1..0...")).toBe("v1.0");
+    });
+    it("prevents leading dash or slash and trailing dot or slash", () => {
+        expect(sanitizeGitRef("-/--abc/.")).toBe("abc");
+    });
+    it("removes trailing .lock suffix", () => {
+        expect(sanitizeGitRef("release.lock")).toBe("release");
+        // multiple .lock occurrences only remove final suffix
+        expect(sanitizeGitRef("a.lock.lock")).toBe("a.lock");
+    });
+    it("works with an empty-ish result (keeps dot/punctuations according to sanitizer)", () => {
+        // Implementation collapses dots and slashes but does not remove the leading dot
+        expect(sanitizeGitRef("   ....///--- ")).toBe("./---");
+    });
+});

package/dist/git/validateBranchName.js

@@ -0,0 +1,17 @@
+import { execa } from "execa";
+/**
+ * Validates a branch name by delegating to Git itself.
+ *
+ * Uses:
+ *   git check-ref-format --branch <name>
+ *
+ * Throws if invalid.
+ */
+export async function validateBranchName(name) {
+    try {
+        await execa("git", ["check-ref-format", "--branch", name]);
+    }
+    catch {
+        throw new Error(`Invalid git branch name: "${name}"`);
+    }
+}

package/dist/parseArgs.js

@@ -0,0 +1,37 @@
+import { cac } from "cac";
+function stripDoubleDash(argv) {
+    const idx = argv.indexOf("--");
+    if (idx === -1)
+        return [...argv];
+    // keep node + script, remove the "--" separator and retain the rest
+    return [...argv.slice(0, idx), ...argv.slice(idx + 1)];
+}
+export function parseArgs(argv = process.argv) {
+    const cli = cac("new-branch");
+    cli
+        .option("-p, --pattern <pattern>", "Branch pattern")
+        .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")
+        .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,
+        create: typeof opts.create === "boolean" ? opts.create : undefined,
+        prompt: typeof opts.prompt === "boolean" ? opts.prompt : undefined,
+        quiet: typeof opts.quiet === "boolean" ? opts.quiet : undefined,
+        help: typeof opts.help === "boolean" ? opts.help : undefined,
+    };
+    return {
+        options,
+        args: parsed.args,
+    };
+}

package/dist/parseArgs.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { parseArgs } from "./parseArgs.js";
+describe("parseArgs", () => {
+    it("parses long options", () => {
+        const argv = [
+            "node",
+            "cli",
+            "--pattern",
+            "{type}/{title}-{id}",
+            "--id",
+            "STK-123",
+            "--title",
+            "Minha tarefa",
+            "--type",
+            "feat",
+            "--create",
+        ];
+        const res = parseArgs(argv);
+        expect(res.options.pattern).toBe("{type}/{title}-{id}");
+        expect(res.options.id).toBe("STK-123");
+        expect(res.options.title).toBe("Minha tarefa");
+        expect(res.options.type).toBe("feat");
+        expect(res.options.create).toBe(true);
+        expect(res.args).toEqual([]);
+    });
+    it("parses short -p as pattern", () => {
+        const argv = ["node", "cli", "-p", "{type}/{title}-{id}"];
+        const res = parseArgs(argv);
+        expect(res.options.pattern).toBe("{type}/{title}-{id}");
+    });
+    it("strips tsx double-dash separator", () => {
+        const argv = [
+            "node",
+            "cli",
+            "--",
+            "--pattern",
+            "{type}/{title}-{id}",
+            "--id",
+            "STK-123",
+        ];
+        const res = parseArgs(argv);
+        expect(res.options.pattern).toBe("{type}/{title}-{id}");
+        expect(res.options.id).toBe("STK-123");
+    });
+    it("supports --no-prompt", () => {
+        const argv = ["node", "cli", "--no-prompt"];
+        const res = parseArgs(argv);
+        expect(res.options.prompt).toBe(false);
+    });
+});

package/dist/pattern/parsePattern.js

@@ -0,0 +1,147 @@
+/**
+ * Parses a branch name pattern string and produces an abstract syntax tree (AST)
+ * representation along with the list of variables used.
+ *
+ * @remarks
+ * ## Pattern Grammar (v1)
+ *
+ * - **Literals**: Any text outside of `{}` is treated as a literal segment.
+ * - **Variables**: Declared inside curly braces, e.g. `{name}`.
+ * - **Transforms**: Optional transforms can be applied using `:` and `;`:
+ *   - `{name:transform}`
+ *   - `{name:transform;transform:arg}`
+ * - **Transform arguments**: Separated by `:`, for example:
+ *   - `{title:max:25}`
+ *   - `{title:slugify;max:25}`
+ *
+ * This parser does **not** validate transform names or arguments.
+ * Validation should be handled in a later stage of the pipeline.
+ *
+ * @param input - The raw pattern string to parse.
+ *
+ * @returns An object containing:
+ * - `nodes`: An ordered list of parsed pattern nodes (literals and variables).
+ * - `variablesUsed`: A deduplicated list of variable names in appearance order.
+ *
+ * @throws Error
+ * - If a variable block is missing a closing `}`.
+ * - If a `{` is found inside a variable block.
+ * - If a variable block is empty (`{}`).
+ * - If a variable name is missing.
+ *
+ * @example
+ * Basic usage:
+ *
+ * ```ts
+ * parsePattern("{type}/{title}-{id}");
+ * ```
+ *
+ * @example
+ * With transforms:
+ *
+ * ```ts
+ * parsePattern("{type}/{title:slugify;max:25}-{id}");
+ * ```
+ *
+ * @example
+ * Returned structure:
+ *
+ * ```ts
+ * {
+ *   nodes: [
+ *     { kind: "variable", name: "type", transforms: [] },
+ *     { kind: "literal", value: "/" },
+ *     {
+ *       kind: "variable",
+ *       name: "title",
+ *       transforms: [
+ *         { name: "slugify", args: [] },
+ *         { name: "max", args: ["25"] }
+ *       ]
+ *     },
+ *     { kind: "literal", value: "-" },
+ *     { kind: "variable", name: "id", transforms: [] }
+ *   ],
+ *   variablesUsed: ["type", "title", "id"]
+ * }
+ * ```
+ */
+export function parsePattern(input) {
+    const nodes = [];
+    const variablesUsed = [];
+    let i = 0;
+    let literalBuffer = "";
+    const flushLiteral = () => {
+        if (literalBuffer.length > 0) {
+            nodes.push({ kind: "literal", value: literalBuffer });
+            literalBuffer = "";
+        }
+    };
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch !== "{") {
+            literalBuffer += ch;
+            i += 1;
+            continue;
+        }
+        // We found "{": start of a variable block.
+        flushLiteral();
+        const end = input.indexOf("}", i + 1);
+        if (end === -1) {
+            throw new Error(`Invalid pattern: missing "}" (at index ${i})`);
+        }
+        const inside = input.slice(i + 1, end).trim();
+        if (inside.includes("{")) {
+            throw new Error(`Invalid pattern: unexpected "{" inside "{}" (at index ${i})`);
+        }
+        if (!inside) {
+            throw new Error(`Invalid pattern: empty "{}" (at index ${i})`);
+        }
+        const [rawName, ...rest] = inside.split(":");
+        const name = rawName.trim();
+        if (!name) {
+            throw new Error(`Invalid pattern: missing variable name (at index ${i})`);
+        }
+        // If there was ":" in the inside, everything after the first ":" is the transform section.
+        const transformSection = rest.length > 0 ? rest.join(":").trim() : "";
+        const transforms = transformSection
+            ? transformSection
+                .split(";")
+                .map((s) => s.trim())
+                .filter(Boolean)
+                .map(parseTransform)
+            : [];
+        nodes.push({ kind: "variable", name, transforms });
+        variablesUsed.push(name);
+        i = end + 1;
+    }
+    flushLiteral();
+    return {
+        nodes,
+        variablesUsed: uniquePreserveOrder(variablesUsed),
+    };
+}
+function parseTransform(segment) {
+    // segment examples:
+    // - "slugify"
+    // - "max:25"
+    // - "replace:_:-"  (args are ["_", "-"])  (still v1, no quoting rules yet)
+    const parts = segment.split(":").map((p) => p.trim());
+    const name = parts[0];
+    const args = parts.slice(1);
+    if (!name) {
+        throw new Error(`Invalid transform: "${segment}"`);
+    }
+    return { name, args };
+}
+function uniquePreserveOrder(items) {
+    const seen = new Set();
+    const out = [];
+    for (const it of items) {
+        if (!seen.has(it)) {
+            seen.add(it);
+            out.push(it);
+        }
+    }
+    return out;
+}

package/dist/pattern/parsePattern.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import { parsePattern } from "./parsePattern.js";
+describe("parsePattern", () => {
+    it("parses literals + variables + transforms", () => {
+        const res = parsePattern("{type}/{title:slugify;max:25}-{id}");
+        expect(res.variablesUsed).toEqual(["type", "title", "id"]);
+        expect(res.nodes).toEqual([
+            { kind: "variable", name: "type", transforms: [] },
+            { kind: "literal", value: "/" },
+            {
+                kind: "variable",
+                name: "title",
+                transforms: [
+                    { name: "slugify", args: [] },
+                    { name: "max", args: ["25"] },
+                ],
+            },
+            { kind: "literal", value: "-" },
+            { kind: "variable", name: "id", transforms: [] },
+        ]);
+    });
+    it("throws on missing closing brace", () => {
+        expect(() => parsePattern("{type/{id}")).toThrow(/missing "}"|Invalid pattern/);
+    });
+});

package/dist/pattern/transforms/index.js

@@ -0,0 +1,16 @@
+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;
+}
+export const defaultTransforms = buildRegistry(allTransforms);

package/dist/pattern/transforms/lower.js

@@ -0,0 +1,8 @@
+export const lower = {
+    name: "lower",
+    fn: (value) => value.toLowerCase(),
+    doc: {
+        summary: "Lowercases the value.",
+        usage: ["{name:lower}"],
+    },
+};

package/dist/pattern/transforms/lower.test.js

@@ -0,0 +1,10 @@
+import { describe, it, expect } from "vitest";
+import { lower } from "./lower.js";
+describe("lower transform", () => {
+    it("converts to lowercase", () => {
+        expect(lower.fn("Hello WORLD", [])).toBe("hello world");
+    });
+    it("keeps non-letter characters", () => {
+        expect(lower.fn("123-ÁÉ!", [])).toBe("123-áé!");
+    });
+});

package/dist/pattern/transforms/max.js

@@ -0,0 +1,13 @@
+export const max = {
+    name: "max",
+    fn: (value, [n]) => {
+        const size = Number(n);
+        if (!Number.isFinite(size) || size < 0)
+            throw new Error(`max expects a non-negative number, got "${n ?? ""}"`);
+        return value.slice(0, size);
+    },
+    doc: {
+        summary: "Truncates the value to a maximum length.",
+        usage: ["{name:max:25}"],
+    },
+};

package/dist/pattern/transforms/max.test.js

@@ -0,0 +1,13 @@
+import { describe, it, expect } from "vitest";
+import { max } from "./max.js";
+describe("max transform", () => {
+    it("truncates the value to the given length", () => {
+        expect(max.fn("abcdef", ["3"])).toBe("abc");
+        expect(max.fn("short", ["10"])).toBe("short");
+    });
+    it("throws on negative or non-finite sizes", () => {
+        expect(() => max.fn("abc", ["-1"])).toThrow();
+        expect(() => max.fn("abc", ["not-a-number"])).toThrow();
+        expect(() => max.fn("abc", [])).toThrow();
+    });
+});

package/dist/pattern/transforms/renderPattern.js

@@ -0,0 +1,37 @@
+/**
+ * Renders a parsed pattern AST into its final string representation.
+ *
+ * @param parsed - The parsed pattern AST.
+ * @param values - A map of variable values.
+ * @param opts - Rendering options including transform registry.
+ *
+ * @returns The rendered string.
+ *
+ * @throws Error If a required variable is missing in strict mode.
+ * @throws Error If an unknown transform is encountered.
+ */
+export function renderPattern(parsed, values, opts) {
+    const strict = opts.strict ?? true;
+    return parsed.nodes.map((node) => renderNode(node, values, opts.transforms, strict)).join("");
+}
+function renderNode(node, values, transforms, strict) {
+    if (node.kind === "literal") {
+        return node.value;
+    }
+    const raw = values[node.name];
+    if (raw == null) {
+        if (strict) {
+            throw new Error(`Missing value for "{${node.name}}"`);
+        }
+        return "";
+    }
+    let result = raw;
+    for (const transform of node.transforms) {
+        const fn = transforms[transform.name];
+        if (!fn) {
+            throw new Error(`Unknown transform "${transform.name}" on "{${node.name}}"`);
+        }
+        result = fn(result, transform.args);
+    }
+    return result;
+}

package/dist/pattern/transforms/renderPattern.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { renderPattern } from "./renderPattern.js";
+import { parsePattern } from "../parsePattern.js";
+import { lower } from "./lower.js";
+import { upper } from "./upper.js";
+import { max } from "./max.js";
+import { slugify } from "./slugify.js";
+const defaultTransforms = {
+    [lower.name]: lower.fn,
+    [upper.name]: upper.fn,
+    [max.name]: max.fn,
+    [slugify.name]: slugify.fn,
+};
+describe("renderPattern", () => {
+    it("renders literals and variables without transforms", () => {
+        const parsed = parsePattern("{type}/{title}-{id}");
+        const out = renderPattern(parsed, { type: "feat", title: "My Task", id: "123" }, { transforms: defaultTransforms });
+        expect(out).toBe("feat/My Task-123");
+    });
+    it("applies transforms in order (slugify then max)", () => {
+        const parsed = parsePattern("{title:slugify;max:5}");
+        const out = renderPattern(parsed, { title: "Título grande" }, { transforms: defaultTransforms });
+        // slugify -> "titulo-grande" then max:5 -> "titul"
+        expect(out).toBe("titul");
+    });
+    it("throws when an unknown transform is used", () => {
+        const parsed = {
+            nodes: [{ kind: "variable", name: "foo", transforms: [{ name: "nope", args: [] }] }],
+            variablesUsed: ["foo"],
+        };
+        expect(() => renderPattern(parsed, { foo: "bar" }, { transforms: defaultTransforms })).toThrow(/Unknown transform/i);
+    });
+    it("throws on missing variable in strict mode (default)", () => {
+        const parsed = parsePattern("{id}");
+        expect(() => renderPattern(parsed, {}, { transforms: defaultTransforms })).toThrow(/Missing value/);
+    });
+    it("returns empty for missing variable when strict is false", () => {
+        const parsed = parsePattern("pre-{id}-post");
+        const out = renderPattern(parsed, {}, { transforms: defaultTransforms, strict: false });
+        expect(out).toBe("pre--post");
+    });
+    it("propagates transform errors (invalid max arg)", () => {
+        const parsed = parsePattern("{title:max:-1}");
+        expect(() => renderPattern(parsed, { title: "abc" }, { transforms: defaultTransforms })).toThrow();
+    });
+});

package/dist/pattern/transforms/slugify.js

@@ -0,0 +1,14 @@
+export const slugify = {
+    name: "slugify",
+    fn: (value) => value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, ""),
+    doc: {
+        summary: "Slugifies to a git-friendly format.",
+        usage: ["{title:slugify}"],
+    },
+};

package/dist/pattern/transforms/slugify.test.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest";
+import { slugify } from "./slugify.js";
+describe("slugify transform", () => {
+    it("removes accents, lowercases and replaces non-alphanum with dashes", () => {
+        const input = "Título com Acentos & símbolos!";
+        const out = slugify.fn(input, []);
+        expect(out).toBe("titulo-com-acentos-simbolos");
+    });
+    it("collapses multiple separators into one and trims dashes", () => {
+        const input = "  --Hello___World--  ";
+        const out = slugify.fn(input, []);
+        expect(out).toBe("hello-world");
+    });
+});

package/dist/pattern/transforms/types.js

@@ -0,0 +1 @@
+export {};

package/dist/pattern/transforms/upper.js

@@ -0,0 +1,8 @@
+export const upper = {
+    name: "upper",
+    fn: (value) => value.toUpperCase(),
+    doc: {
+        summary: "Uppercases the value.",
+        usage: ["{name:upper}"],
+    },
+};

package/dist/pattern/transforms/upper.test.js

@@ -0,0 +1,10 @@
+import { describe, it, expect } from "vitest";
+import { upper } from "./upper.js";
+describe("upper transform", () => {
+    it("converts to uppercase", () => {
+        expect(upper.fn("Hello world", [])).toBe("HELLO WORLD");
+    });
+    it("keeps non-letter characters", () => {
+        expect(upper.fn("123-áé!", [])).toBe("123-ÁÉ!");
+    });
+});

package/dist/pattern/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/resolveMissingValues.js

@@ -0,0 +1,24 @@
+import { input } from "@inquirer/prompts";
+/**
+ * Resolves missing variable values required by the pattern.
+ *
+ * Rule (v1):
+ * - Any variable used in the pattern is considered required.
+ */
+export async function resolveMissingValues(parsed, initialValues, opts) {
+    const requiredVars = parsed.variablesUsed;
+    const values = { ...initialValues };
+    for (const name of requiredVars) {
+        if (values[name])
+            continue;
+        if (!opts.prompt) {
+            throw new Error(`Missing required value: "${name}"`);
+        }
+        const answer = await input({
+            message: `Enter ${name}:`,
+            validate: (v) => (v.trim() ? true : `${name} cannot be empty`),
+        });
+        values[name] = answer;
+    }
+    return values;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "new-branch",
+  "version": "0.1.0",
+  "description": "Generate and create standardized git branch names from a pattern.",
+  "keywords": [
+    "git",
+    "branch",
+    "cli",
+    "tool"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "pnpm build && pnpm test:run",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "lint": "eslint src --ext .ts"
+  },
+  "bin": {
+    "new-branch": "./dist/cli.js"
+  },
+  "author": "Teles <github.com/teles>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teles/new-branch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/teles/new-branch/issues"
+  },
+  "homepage": "https://github.com/teles/new-branch#readme",
+  "packageManager": "pnpm@10.22.0",
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "25.2.3",
+    "eslint": "10.0.0",
+    "prettier": "3.8.1",
+    "tsc-alias": "1.8.16",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.56.0",
+    "vitest": "4.0.18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "8.2.1",
+    "cac": "6.7.14",
+    "execa": "9.6.1"
+  }
+}