uva-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UVA CLI Contributors
+
+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,177 @@
+<p align="center">
+  <img src="assets/uva-cli-lockup.svg" alt="uva-cli" width="420" />
+</p>
+
+<p align="center">
+  <strong>Interactive Git workflow automation for teams</strong><br>
+  Branch naming, Conventional Commits, and more — all guided, all configurable.
+</p>
+
+<p align="center">
+  <a href="https://npmjs.com/package/uva-cli">
+    <img src="https://img.shields.io/npm/v/uva-cli.svg?color=6D28D9&label=npm" alt="npm version" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-0F9D6B.svg" alt="MIT license" />
+  </a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-A78BFA.svg" alt="Node.js ≥18" />
+</p>
+
+---
+
+## What is UVA CLI?
+
+UVA CLI turns repetitive Git operations into short, interactive wizards. Instead of memorizing your team's branch naming conventions or commit message formats, the CLI guides you through them — and adapts to whatever conventions your project uses.
+
+No more "how should I name this branch?" or "what goes in the ticket field?". Just run `uva` and follow the prompts.
+
+## Features
+
+- **Per-project config** — run `uva init` once; conventions are saved to `uva.config.json`
+- **Conventional Commits** — pick the type, add a ticket (optional), write the message
+- **Branch creation** — checks out the source branch, pulls, and creates your new branch in one step
+- **Multiple formats** — commit and branch naming patterns are chosen during setup, not hard-coded
+- **Zero lock-in** — conventions changed? Re-run `uva init`
+
+## Install
+
+```bash
+npm install -g uva-cli
+```
+
+Or run without a global install:
+
+```bash
+npx uva-cli init
+```
+
+### Command not found?
+
+If your shell can't find `uva` after a global install, the npm global bin directory isn't in your `PATH`. Add this to your `~/.zshrc` (or `~/.bashrc`):
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+Then reload your shell:
+
+```bash
+source ~/.zshrc
+```
+
+## Quick start
+
+### 1. Set up your project
+
+Run this once inside any Git repository:
+
+```bash
+uva init
+```
+
+You'll be asked:
+
+- Project name
+- Do you use a ticket tracker? (Jira, Linear, GitHub Issues…)
+- Ticket prefix (e.g. `PROJ`, `ENG`, `FC`)
+- Commit message format
+- Branch naming format
+- Which branches you can branch from (e.g. `main,develop`)
+
+This creates a **`uva.config.json`** at your repository root. Commit it — everyone on your team shares the same setup automatically.
+
+### 2. Use the commands
+
+```bash
+uva start     # interactive menu — pick what to do
+uva commit    # guided commit: type → ticket → message → file selection
+uva branch    # guided branch: source → ticket → type → task name
+uva push      # confirms and pushes the current branch to origin
+```
+
+## Commands
+
+| Command        | Description                                                 |
+| :------------- | :---------------------------------------------------------- |
+| `uva init`     | Set up UVA CLI for this project — creates `uva.config.json` |
+| `uva start`    | Interactive menu with all available options                 |
+| `uva commit`   | Create an interactive commit following Conventional Commits |
+| `uva branch`   | Create a new branch from a configured source branch         |
+| `uva new-file` | Scaffold a file from a template (docs, frontend, backend)   |
+| `uva push`     | Push the current branch to origin                           |
+
+## Configuration
+
+`uva.config.json` is created by `uva init` and lives at the root of your repository. You can edit it by hand at any time.
+
+```json
+{
+  "project": {
+    "name": "My Project"
+  },
+  "commit": {
+    "ticketEnabled": true,
+    "ticketPrefix": "PROJ",
+    "ticketPlaceholder": "PROJ-42",
+    "format": "conventional-ticket"
+  },
+  "branch": {
+    "sources": ["main", "develop"],
+    "ticketEnabled": true,
+    "areaEnabled": false,
+    "areas": [],
+    "format": "type-ticket-name"
+  }
+}
+```
+
+### Commit formats
+
+| `format` value        | Example output                     |
+| :-------------------- | :--------------------------------- |
+| `conventional-ticket` | `feat(PROJ-42): add login screen`  |
+| `conventional`        | `feat: add login screen`           |
+| `ticket-conventional` | `[PROJ-42] feat: add login screen` |
+
+### Branch formats
+
+| `format` value     | Example output                  |
+| :----------------- | :------------------------------ |
+| `type-ticket-name` | `feat/PROJ-42_add-login-screen` |
+| `type-name`        | `feat/add-login-screen`         |
+| `ticket-type-name` | `PROJ-42/feat/add-login-screen` |
+
+## File templates (`uva new-file`)
+
+`uva new-file` scaffolds files from opinionated templates. The flow is: **language → category → type → title → folder**. Date and author (from `git config`) are filled in automatically.
+
+Available languages: **English** and **Português (BR)**.
+
+### Docs
+
+Documentation templates in Markdown, meant to live alongside your source code in a `docs/` folder.
+
+| Type              | When to use                                                                                                                                                                                                   | Default output             |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------- |
+| **ADR**           | Record an architectural decision: context, decision, rationale, consequences, and alternatives. Based on [Michael Nygard's format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). | `docs/decisions/<slug>.md` |
+| **Decision Log**  | Lightweight alternative to ADRs — good for product, process, or quick technical calls.                                                                                                                        | `docs/decisions/<slug>.md` |
+| **Meeting Notes** | Agenda, discussion notes, decisions made, and action items in one place.                                                                                                                                      | `docs/meetings/<slug>.md`  |
+| **RFC**           | Propose a significant change before work starts. Captures motivation, design, drawbacks, and alternatives. Inspired by the Rust and React RFC processes.                                                      | `docs/rfcs/<slug>.md`      |
+| **Runbook**       | Step-by-step operational guide for a known scenario — incident response, deployment, rollback.                                                                                                                | `docs/runbooks/<slug>.md`  |
+
+### Git
+
+GitHub workflow files written to the standard paths GitHub expects.
+
+| Type            | When to use                                                                                                                                                   | Output                             |
+| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------- |
+| **PR Template** | Standardize pull request descriptions across the team. Includes title format, dependency declaration, change description, test instructions, and a checklist. | `.github/pull_request_template.md` |
+
+## Requirements
+
+- Node.js ≥ 18
+- Git
+
+## License
+
+[MIT](LICENSE)

package/bin.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { runInit } from './commands/init.mjs'
+import { runCommit } from './commands/commit.mjs'
+import { runBranch } from './commands/branch.mjs'
+import { runNewFile } from './commands/new-file.mjs'
+import { runPush } from './commands/push.mjs'
+import { runStart } from './commands/start.mjs'
+
+const program = new Command()
+
+program.name('uva').description('UVA CLI — Git workflow automation').version('1.0.0')
+
+program.command('start').description('Show all available options interactively').action(runStart)
+
+program.command('init').description('Set up UVA CLI for this project').action(runInit)
+
+program
+  .command('commit')
+  .description('Create an interactive commit following Conventional Commits')
+  .option('--type <type>', 'commit type (feat, fix, docs, style, refactor, test, chore)')
+  .option('--ticket <id>', 'ticket ID, e.g. PROJ-42')
+  .option('--message <msg>', 'commit message')
+  .option('--files <paths>', 'files to stage, comma-separated paths')
+  .option('--all', 'stage all changed files')
+  .action(runCommit)
+
+program
+  .command('branch')
+  .description('Create a new branch from a configured source')
+  .option('--source <branch>', 'source branch to checkout from')
+  .option('--ticket <id>', 'ticket ID, e.g. PROJ-42')
+  .option('--type <type>', 'branch type (feat, fix, docs, style, refactor, test, chore)')
+  .option('--name <name>', 'task name (will be slugified into the branch name)')
+  .action(runBranch)
+
+program
+  .command('new-file')
+  .description('Scaffold a file from a template (docs, git)')
+  .option('--lang <lang>', 'language: en | pt-br')
+  .option('--category <category>', 'category: docs | git')
+  .option(
+    '--type <type>',
+    'file type: adr | decision-log | meeting-notes | rfc | runbook | pull-request',
+  )
+  .option('--name <name>', 'file title (docs only)')
+  .option('--folder <path>', 'output folder path (docs only)')
+  .action(runNewFile)
+
+program
+  .command('push')
+  .description('Push the current branch to origin')
+  .option('-y, --yes', 'skip confirmation and push immediately')
+  .action(runPush)
+
+program.parse()

package/commands/branch.mjs

@@ -0,0 +1,138 @@
+import { select, text, confirm, isCancel, log } from '@clack/prompts'
+import { bannerIntro, bannerOutro, bannerCancelled } from '../lib/banner.mjs'
+import { hasUncommittedChanges, checkout, pull, createBranch } from '../lib/git.mjs'
+import { COMMIT_TYPES } from '../lib/types.mjs'
+import { requireConfig } from '../lib/config.mjs'
+import { buildBranchName } from '../lib/format.mjs'
+
+// Called by commander as runBranch(options, command)
+export async function runBranch(opts = {}) {
+  bannerIntro('branch')
+
+  const config = requireConfig()
+
+  if (hasUncommittedChanges()) {
+    const proceed = await confirm({
+      message: 'You have uncommitted changes. They will carry over to the new branch. Continue?',
+    })
+    if (isCancel(proceed) || !proceed) {
+      log.info('Tip: run `uva commit` first to commit pending changes.')
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  // ── Source branch ────────────────────────────────────────────────────────
+  let source
+  if (opts.source) {
+    if (!config.branch.sources.includes(opts.source)) {
+      log.warn(`"${opts.source}" is not in the configured source branches. Proceeding anyway.`)
+    }
+    source = opts.source
+  } else {
+    source = await select({
+      message: 'Branch from',
+      options: config.branch.sources.map((b) => ({ value: b, label: b })),
+    })
+    if (isCancel(source)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  // ── Ticket ───────────────────────────────────────────────────────────────
+  let ticket = ''
+  if (config.branch.ticketEnabled) {
+    if (opts.ticket) {
+      ticket = opts.ticket
+    } else {
+      const input = await text({
+        message: 'Ticket',
+        placeholder: config.commit.ticketPlaceholder,
+        validate: (v) => (v.trim() ? undefined : 'Ticket cannot be empty.'),
+      })
+      if (isCancel(input)) {
+        bannerCancelled()
+        process.exit(0)
+      }
+      ticket = input.trim()
+    }
+  }
+
+  // ── Branch type ──────────────────────────────────────────────────────────
+  let type
+  if (opts.type) {
+    const valid = COMMIT_TYPES.map((t) => t.value)
+    if (!valid.includes(opts.type)) {
+      log.error(`Invalid --type "${opts.type}". Valid values: ${valid.join(', ')}`)
+      process.exit(1)
+    }
+    type = opts.type
+  } else {
+    type = await select({ message: 'Branch type', options: COMMIT_TYPES })
+    if (isCancel(type)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  // ── Task name ────────────────────────────────────────────────────────────
+  let taskName
+  if (opts.name) {
+    taskName = opts.name
+  } else {
+    const input = await text({
+      message: 'Task name',
+      placeholder: 'add login screen',
+      validate: (v) => (v.trim() ? undefined : 'Task name cannot be empty.'),
+    })
+    if (isCancel(input)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    taskName = input.trim()
+  }
+
+  const branchName = buildBranchName(config.branch.format, { type, ticket, name: taskName })
+
+  // Skip confirmation when fully scripted
+  const ticketDone = !config.branch.ticketEnabled || opts.ticket
+  const scripted = opts.source && opts.type && opts.name && ticketDone
+
+  if (!scripted) {
+    const confirmed = await confirm({ message: `Create branch:\n  ${branchName}` })
+    if (isCancel(confirmed) || !confirmed) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  try {
+    checkout(source)
+  } catch {
+    log.error(
+      `Could not switch to ${source}. Make sure the branch exists and there are no conflicts.`,
+    )
+    process.exit(1)
+  }
+
+  try {
+    pull()
+  } catch {
+    log.error('Could not pull. Check your connection or resolve any conflicts.')
+    process.exit(1)
+  }
+
+  try {
+    createBranch(branchName)
+  } catch (err) {
+    if (err.stderr?.includes('already exists') || err.message?.includes('already exists')) {
+      log.error(`Branch "${branchName}" already exists. Choose a different name or ticket.`)
+    } else {
+      log.error('Could not create the branch. Check if the name is valid.')
+    }
+    process.exit(1)
+  }
+
+  bannerOutro(`Branch created: ${branchName}`)
+}

package/commands/commit.mjs

@@ -0,0 +1,136 @@
+import { select, text, multiselect, confirm, isCancel, log } from '@clack/prompts'
+import { bannerIntro, bannerOutro, bannerCancelled } from '../lib/banner.mjs'
+import { getChangedFiles, addFiles, commit } from '../lib/git.mjs'
+import { COMMIT_TYPES } from '../lib/types.mjs'
+import { requireConfig } from '../lib/config.mjs'
+import { buildCommitMessage } from '../lib/format.mjs'
+
+// Called by commander as runCommit(options, command)
+export async function runCommit(opts = {}) {
+  bannerIntro('commit')
+
+  const config = requireConfig()
+  const files = getChangedFiles()
+
+  if (files.length === 0) {
+    log.info('Nothing to commit here.')
+    process.exit(0)
+  }
+
+  // ── Commit type ──────────────────────────────────────────────────────────
+  let type
+  if (opts.type) {
+    const valid = COMMIT_TYPES.map((t) => t.value)
+    if (!valid.includes(opts.type)) {
+      log.error(`Invalid --type "${opts.type}". Valid values: ${valid.join(', ')}`)
+      process.exit(1)
+    }
+    type = opts.type
+  } else {
+    type = await select({ message: 'Commit type', options: COMMIT_TYPES })
+    if (isCancel(type)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  // ── Ticket ───────────────────────────────────────────────────────────────
+  let ticket = ''
+  if (config.commit.ticketEnabled) {
+    if (opts.ticket) {
+      ticket = opts.ticket
+    } else {
+      const input = await text({
+        message: 'Ticket',
+        placeholder: config.commit.ticketPlaceholder,
+        validate: (v) => (v.trim() ? undefined : 'Ticket cannot be empty.'),
+      })
+      if (isCancel(input)) {
+        bannerCancelled()
+        process.exit(0)
+      }
+      ticket = input.trim()
+    }
+  }
+
+  // ── Message + files (retry loop for interactive use) ─────────────────────
+  let finalMessage
+  let selected
+
+  while (true) {
+    // Message
+    let message
+    if (opts.message) {
+      message = opts.message.trim().toLowerCase()
+    } else {
+      const input = await text({
+        message: 'Commit message',
+        placeholder: 'add login screen',
+        validate: (v) => (v.trim() ? undefined : 'Message cannot be empty.'),
+      })
+      if (isCancel(input)) {
+        bannerCancelled()
+        process.exit(0)
+      }
+      message = input.trim().toLowerCase()
+    }
+
+    if (message.length > 72) {
+      log.warn(
+        'Message is long (over 72 characters). Shorter messages are recommended, but you can continue.',
+      )
+    }
+
+    // Files
+    if (opts.all) {
+      selected = files.map((f) => f.path)
+    } else if (opts.files) {
+      const paths = opts.files
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+      const availablePaths = files.map((f) => f.path)
+      const invalid = paths.filter((p) => !availablePaths.includes(p))
+      if (invalid.length) {
+        log.error(`Unknown file(s): ${invalid.join(', ')}\nAvailable: ${availablePaths.join(', ')}`)
+        process.exit(1)
+      }
+      selected = paths
+    } else {
+      selected = await multiselect({
+        message: 'Which files to include in the commit?',
+        options: files.map((f) => ({ value: f.path, label: `${f.status.padEnd(2)}  ${f.path}` })),
+        required: true,
+      })
+      if (isCancel(selected)) {
+        bannerCancelled()
+        process.exit(0)
+      }
+    }
+
+    finalMessage = buildCommitMessage(config.commit.format, { type, ticket, message })
+
+    // Skip confirmation when fully scripted (all values came from flags)
+    const scripted = opts.type && opts.message && (opts.all || opts.files)
+    if (scripted) break
+
+    const confirmed = await confirm({ message: `Commit with message:\n  ${finalMessage}` })
+    if (isCancel(confirmed)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    if (confirmed) break
+
+    if (opts.message) break // message is fixed, can't retry
+    log.info("OK! Let's rewrite the message.")
+  }
+
+  try {
+    addFiles(selected)
+    commit(finalMessage)
+    bannerOutro(`Committed: ${finalMessage}`)
+  } catch (e) {
+    log.error(`Commit failed: ${e.message}`)
+    process.exit(1)
+  }
+}

package/commands/init.mjs

@@ -0,0 +1,160 @@
+import { text, select, confirm, isCancel } from '@clack/prompts'
+import { bannerIntro, bannerOutro, bannerCancelled } from '../lib/banner.mjs'
+import { loadConfig, saveConfig } from '../lib/config.mjs'
+import { COMMIT_FORMATS, BRANCH_FORMATS } from '../lib/types.mjs'
+
+export async function runInit() {
+  bannerIntro('init')
+
+  const existing = loadConfig()
+  if (existing) {
+    const overwrite = await confirm({
+      message: 'A configuration already exists. Do you want to overwrite it?',
+    })
+    if (isCancel(overwrite) || !overwrite) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  const projectName = await text({
+    message: 'Project name',
+    placeholder: 'My Awesome Project',
+    validate: (v) => (v.trim() ? undefined : 'Project name cannot be empty.'),
+  })
+  if (isCancel(projectName)) {
+    bannerCancelled()
+    process.exit(0)
+  }
+
+  const useTicket = await confirm({
+    message: 'Do you use a ticket/issue tracker? (e.g., Jira, Linear, GitHub Issues)',
+  })
+  if (isCancel(useTicket)) {
+    bannerCancelled()
+    process.exit(0)
+  }
+
+  let ticketPrefix = ''
+  let ticketPlaceholder = ''
+
+  if (useTicket) {
+    const prefix = await text({
+      message: 'Ticket prefix',
+      placeholder: 'PROJ',
+      validate: (v) => (v.trim() ? undefined : 'Ticket prefix cannot be empty.'),
+    })
+    if (isCancel(prefix)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    ticketPrefix = prefix.trim().toUpperCase()
+    ticketPlaceholder = `${ticketPrefix}-42`
+  }
+
+  let commitFormat = 'conventional'
+  if (useTicket) {
+    const selectedCommitFormat = await select({
+      message: 'Choose a commit message format',
+      options: COMMIT_FORMATS.map((f) => ({
+        ...f,
+        label: f.label.replace(/PROJ/g, ticketPrefix || 'PROJ'),
+      })),
+    })
+    if (isCancel(selectedCommitFormat)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    commitFormat = selectedCommitFormat
+  }
+
+  const sourcesInput = await text({
+    message: 'Branches to branch from (comma-separated)',
+    placeholder: 'main,develop',
+    initialValue: 'main,develop',
+    validate: (v) => {
+      const parts = v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+      return parts.length > 0 ? undefined : 'At least one branch is required.'
+    },
+  })
+  if (isCancel(sourcesInput)) {
+    bannerCancelled()
+    process.exit(0)
+  }
+  const sources = sourcesInput
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+
+  let branchFormat = 'type-name'
+  if (useTicket) {
+    const selectedBranchFormat = await select({
+      message: 'Choose a branch naming format',
+      options: BRANCH_FORMATS.map((f) => ({
+        ...f,
+        label: f.label.replace(/PROJ/g, ticketPrefix || 'PROJ'),
+      })),
+    })
+    if (isCancel(selectedBranchFormat)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    branchFormat = selectedBranchFormat
+  }
+
+  const useArea = await confirm({
+    message: 'Do you want to categorize branches by area? (e.g., FE, BE, DOC)',
+    initialValue: false,
+  })
+  if (isCancel(useArea)) {
+    bannerCancelled()
+    process.exit(0)
+  }
+
+  let areas = []
+  if (useArea) {
+    const areasInput = await text({
+      message: 'Area labels (comma-separated)',
+      placeholder: 'FE,BE,DOC',
+      initialValue: 'FE,BE,DOC',
+      validate: (v) => {
+        const parts = v
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+        return parts.length > 0 ? undefined : 'At least one area is required.'
+      },
+    })
+    if (isCancel(areasInput)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    areas = areasInput
+      .split(',')
+      .map((s) => s.trim().toUpperCase())
+      .filter(Boolean)
+  }
+
+  const config = {
+    project: { name: projectName.trim() },
+    commit: {
+      ticketEnabled: Boolean(useTicket),
+      ticketPrefix,
+      ticketPlaceholder,
+      format: commitFormat,
+    },
+    branch: {
+      sources,
+      ticketEnabled: Boolean(useTicket),
+      areaEnabled: Boolean(useArea),
+      areas,
+      format: branchFormat,
+    },
+  }
+
+  const configPath = saveConfig(config)
+  bannerOutro(`Configuration saved to ${configPath}`)
+}