uva-cli 1.0.0

package/commands/new-file.mjs

@@ -0,0 +1,240 @@
+import { select, text, confirm, isCancel, log } from '@clack/prompts'
+import { bannerIntro, bannerOutro, bannerCancelled } from '../lib/banner.mjs'
+import { getGitRoot } from '../lib/git.mjs'
+import { slugify } from '../lib/slugify.mjs'
+import { execSync } from 'child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ── Template registry ──────────────────────────────────────────────────────
+
+const CATEGORIES = {
+  docs: {
+    label: 'Docs — documentation files',
+    types: [
+      {
+        value: 'adr',
+        label: 'ADR            Architecture Decision Record',
+        folder: 'docs/decisions',
+      },
+      {
+        value: 'decision-log',
+        label: 'Decision Log   Lightweight decision entry',
+        folder: 'docs/decisions',
+      },
+      {
+        value: 'meeting-notes',
+        label: 'Meeting Notes  Agenda, notes, and action items',
+        folder: 'docs/meetings',
+      },
+      { value: 'rfc', label: 'RFC            Technical proposal / spec', folder: 'docs/rfcs' },
+      {
+        value: 'runbook',
+        label: 'Runbook        Operational step-by-step guide',
+        folder: 'docs/runbooks',
+      },
+    ],
+  },
+  git: {
+    label: 'Git — GitHub workflow files',
+    types: [
+      {
+        value: 'pull-request',
+        label: 'PR Template    GitHub pull request template',
+        folder: '.github',
+        fixedName: 'pull_request_template.md',
+      },
+    ],
+  },
+}
+
+const LANGUAGES = [
+  { value: 'en', label: 'English' },
+  { value: 'pt-br', label: 'Português (BR)' },
+]
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function getAuthor() {
+  try {
+    return execSync('git config user.name', { encoding: 'utf-8' }).trim() || 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function getDate() {
+  return new Date().toISOString().split('T')[0]
+}
+
+function applyTemplate(content, vars) {
+  return content
+    .replace(/\{\{title\}\}/g, vars.title)
+    .replace(/\{\{date\}\}/g, vars.date)
+    .replace(/\{\{author\}\}/g, vars.author)
+}
+
+// ── Command ────────────────────────────────────────────────────────────────
+
+// Called by commander as runNewFile(options, command)
+export async function runNewFile(opts = {}) {
+  bannerIntro('new-file')
+
+  // ── Language ─────────────────────────────────────────────────────────────
+  let lang
+  if (opts.lang) {
+    const valid = LANGUAGES.map((l) => l.value)
+    if (!valid.includes(opts.lang)) {
+      log.error(`Invalid --lang "${opts.lang}". Valid values: ${valid.join(', ')}`)
+      process.exit(1)
+    }
+    lang = opts.lang
+  } else {
+    lang = await select({ message: 'Language', options: LANGUAGES })
+    if (isCancel(lang)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  // ── Category ─────────────────────────────────────────────────────────────
+  let category
+  if (opts.category) {
+    const valid = Object.keys(CATEGORIES)
+    if (!valid.includes(opts.category)) {
+      log.error(`Invalid --category "${opts.category}". Valid values: ${valid.join(', ')}`)
+      process.exit(1)
+    }
+    category = opts.category
+  } else {
+    category = await select({
+      message: 'Category',
+      options: Object.entries(CATEGORIES).map(([value, { label }]) => ({ value, label })),
+    })
+    if (isCancel(category)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  // ── Type ─────────────────────────────────────────────────────────────────
+  const types = CATEGORIES[category].types
+  let type
+  if (opts.type) {
+    const valid = types.map((t) => t.value)
+    if (!valid.includes(opts.type)) {
+      log.error(
+        `Invalid --type "${opts.type}" for category "${category}". Valid values: ${valid.join(', ')}`,
+      )
+      process.exit(1)
+    }
+    type = opts.type
+  } else {
+    type = await select({
+      message: 'File type',
+      options: types.map((t) => ({ value: t.value, label: t.label })),
+    })
+    if (isCancel(type)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  const def = types.find((t) => t.value === type)
+  const templatePath = join(__dirname, '../templates', lang, category, `${type}.md`)
+
+  if (!existsSync(templatePath)) {
+    log.error(`Template not found: templates/${lang}/${category}/${type}.md`)
+    process.exit(1)
+  }
+
+  const author = getAuthor()
+  const date = getDate()
+
+  // ── Git templates: fixed output path, no name needed ─────────────────────
+  if (def.fixedName) {
+    const root = getGitRoot()
+    const absFolder = join(root, def.folder)
+    const absFile = join(absFolder, def.fixedName)
+    const relPath = join(def.folder, def.fixedName)
+
+    if (existsSync(absFile)) {
+      const overwrite = await confirm({ message: `"${relPath}" already exists. Overwrite?` })
+      if (isCancel(overwrite) || !overwrite) {
+        bannerCancelled()
+        process.exit(0)
+      }
+    }
+
+    const content = applyTemplate(readFileSync(templatePath, { encoding: 'utf-8' }), {
+      title: '',
+      date,
+      author,
+    })
+    if (!existsSync(absFolder)) mkdirSync(absFolder, { recursive: true })
+    writeFileSync(absFile, content, { encoding: 'utf-8' })
+    bannerOutro(`Created: ${relPath}`)
+    return
+  }
+
+  // ── Docs templates: need a title and output folder ────────────────────────
+  let rawName
+  if (opts.name) {
+    rawName = opts.name
+  } else {
+    const input = await text({
+      message: 'Title',
+      placeholder: 'Switch auth library to Lucia',
+      validate: (v) => (v.trim() ? undefined : 'Title cannot be empty.'),
+    })
+    if (isCancel(input)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    rawName = input.trim()
+  }
+
+  const fileName = `${slugify(rawName)}.md`
+
+  let outputFolder
+  if (opts.folder) {
+    outputFolder = opts.folder
+  } else {
+    const input = await text({
+      message: 'Output folder',
+      initialValue: def.folder,
+      validate: (v) => (v.trim() ? undefined : 'Folder cannot be empty.'),
+    })
+    if (isCancel(input)) {
+      bannerCancelled()
+      process.exit(0)
+    }
+    outputFolder = input.trim()
+  }
+
+  const root = getGitRoot()
+  const absFolder = join(root, outputFolder)
+  const absFile = join(absFolder, fileName)
+  const relPath = join(outputFolder, fileName)
+
+  if (existsSync(absFile)) {
+    const overwrite = await confirm({ message: `"${relPath}" already exists. Overwrite?` })
+    if (isCancel(overwrite) || !overwrite) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  const content = applyTemplate(readFileSync(templatePath, { encoding: 'utf-8' }), {
+    title: rawName,
+    date,
+    author,
+  })
+
+  if (!existsSync(absFolder)) mkdirSync(absFolder, { recursive: true })
+  writeFileSync(absFile, content, { encoding: 'utf-8' })
+  bannerOutro(`Created: ${relPath}`)
+}

package/commands/push.mjs

@@ -0,0 +1,31 @@
+import { confirm, isCancel, log } from '@clack/prompts'
+import { bannerIntro, bannerOutro, bannerCancelled } from '../lib/banner.mjs'
+import { getCurrentBranch } from '../lib/git.mjs'
+import { spawnSync } from 'child_process'
+
+// Called by commander as runPush(options, command)
+export async function runPush(opts = {}) {
+  bannerIntro('push')
+
+  const branch = getCurrentBranch()
+
+  if (!opts.yes) {
+    const confirmed = await confirm({
+      message: `Push current branch: ${branch}?`,
+    })
+    if (isCancel(confirmed) || !confirmed) {
+      bannerCancelled()
+      process.exit(0)
+    }
+  }
+
+  const result = spawnSync('git', ['push', 'origin', branch], {
+    stdio: ['pipe', 'inherit', 'inherit'],
+  })
+  if (result.status !== 0) {
+    log.error('Push failed — see the output above.')
+    process.exit(1)
+  }
+
+  bannerOutro(`Pushed: origin/${branch}`)
+}

package/commands/start.mjs

@@ -0,0 +1,63 @@
+import { select, isCancel, intro, outro } from '@clack/prompts'
+import pc from 'picocolors'
+import { banner as brandBanner, uva, folha } from '../lib/colors.mjs'
+import { runInit } from './init.mjs'
+import { runCommit } from './commit.mjs'
+import { runBranch } from './branch.mjs'
+import { runNewFile } from './new-file.mjs'
+import { runPush } from './push.mjs'
+
+export async function runStart() {
+  intro(brandBanner('UVA CLI'))
+
+  console.log('')
+  console.log(uva('  uva-cli') + pc.dim(' — Git workflow automation'))
+  console.log('')
+  console.log(pc.dim('  Guides your team through branch creation and commits'))
+  console.log(pc.dim('  following whatever conventions your project defines.'))
+  console.log('')
+
+  const action = await select({
+    message: 'What do you want to do?',
+    options: [
+      {
+        value: 'init',
+        label: folha('uva init') + '     Set up UVA CLI for this project',
+        hint: 'configure commit and branch patterns',
+      },
+      {
+        value: 'commit',
+        label: uva('uva commit') + '   Create an interactive commit',
+        hint: 'select files, type, ticket and message',
+      },
+      {
+        value: 'branch',
+        label: uva('uva branch') + '   Create a new branch',
+        hint: 'checks out source and pulls automatically',
+      },
+      {
+        value: 'new-file',
+        label: uva('uva new-file') + ' Scaffold a file from a template',
+        hint: 'docs, frontend (React), or backend (Express)',
+      },
+      {
+        value: 'push',
+        label: uva('uva push') + '     Push the current branch to origin',
+        hint: 'confirms the branch and runs git push',
+      },
+    ],
+  })
+
+  if (isCancel(action)) {
+    outro(pc.dim('Operation cancelled.'))
+    process.exit(0)
+  }
+
+  console.log('')
+
+  if (action === 'init') return runInit()
+  if (action === 'commit') return runCommit()
+  if (action === 'branch') return runBranch()
+  if (action === 'new-file') return runNewFile()
+  if (action === 'push') return runPush()
+}

package/lib/banner.mjs

@@ -0,0 +1,15 @@
+import { intro, outro } from '@clack/prompts'
+import pc from 'picocolors'
+import { banner as brandBanner, folha } from './colors.mjs'
+
+export function bannerIntro(command) {
+  intro(brandBanner('UVA CLI') + '  ' + pc.dim(command))
+}
+
+export function bannerOutro(message) {
+  outro(folha('+ ' + message))
+}
+
+export function bannerCancelled() {
+  outro(pc.dim('Operation cancelled.'))
+}

package/lib/colors.mjs

@@ -0,0 +1,50 @@
+/**
+ * Brand colors — ANSI true color (24-bit).
+ * Falls back to basic ANSI if the terminal reports no true-color support.
+ *
+ * Dark-mode palette used for terminal output:
+ *   uva    #A78BFA  (light purple — readable on dark bg)
+ *   folha  #34D399  (light green)
+ *   bg     #6D28D9  (deep purple — banner background)
+ *   tinta  #1C1B22  (near-black ink)
+ */
+
+const TRUE_COLOR =
+  process.env.COLORTERM === 'truecolor' ||
+  process.env.COLORTERM === '24bit' ||
+  process.env.TERM_PROGRAM === 'iTerm.app' ||
+  process.env.TERM_PROGRAM === 'vscode'
+
+function hexRgb(hex) {
+  const n = parseInt(hex.replace('#', ''), 16)
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+}
+
+/** Apply foreground and/or background hex color to text. */
+function paint(text, { fg, bg } = {}) {
+  if (!TRUE_COLOR) return text
+  let codes = ''
+  if (bg) {
+    const [r, g, b] = hexRgb(bg)
+    codes += `\x1b[48;2;${r};${g};${b}m`
+  }
+  if (fg) {
+    const [r, g, b] = hexRgb(fg)
+    codes += `\x1b[38;2;${r};${g};${b}m`
+  }
+  return `${codes}${text}\x1b[0m`
+}
+
+// ── Brand helpers ──────────────────────────────────────────────────────────
+
+/** Light purple text — for general UVA highlights. */
+export const uva = (text) => paint(text, { fg: '#A78BFA' })
+
+/** Light green text — for success messages and outros. */
+export const folha = (text) => paint(text, { fg: '#34D399' })
+
+/** Deep-purple background + light-purple text — for the intro banner pill. */
+export const banner = (text) => paint(` ${text} `, { fg: '#A78BFA', bg: '#6D28D9' })
+
+/** Light-purple dim text — for secondary info (falls back to the raw string). */
+export const dim = (text) => paint(text, { fg: '#6D4FA8' })

package/lib/config.mjs

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { log } from '@clack/prompts'
+import { getGitRoot } from './git.mjs'
+
+function getConfigPath() {
+  const root = getGitRoot()
+  return join(root, 'uva.config.json')
+}
+
+export function loadConfig() {
+  const path = getConfigPath()
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(readFileSync(path, { encoding: 'utf-8' }))
+  } catch {
+    return null
+  }
+}
+
+export function saveConfig(config) {
+  const path = getConfigPath()
+  writeFileSync(path, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8' })
+  return path
+}
+
+export function requireConfig() {
+  const config = loadConfig()
+  if (!config) {
+    log.error('No configuration found. Run `uva init` to set up your project.')
+    process.exit(1)
+  }
+  return config
+}

package/lib/format.mjs

@@ -0,0 +1,26 @@
+import { slugify } from './slugify.mjs'
+
+export function buildCommitMessage(format, { type, ticket, message }) {
+  switch (format) {
+    case 'conventional-ticket':
+      return `${type}(${ticket}): ${message}`
+    case 'ticket-conventional':
+      return `[${ticket}] ${type}: ${message}`
+    case 'conventional':
+    default:
+      return `${type}: ${message}`
+  }
+}
+
+export function buildBranchName(format, { type, ticket, name }) {
+  const slug = slugify(name)
+  switch (format) {
+    case 'type-ticket-name':
+      return `${type}/${ticket}_${slug}`
+    case 'ticket-type-name':
+      return `${ticket}/${type}/${slug}`
+    case 'type-name':
+    default:
+      return `${type}/${slug}`
+  }
+}

package/lib/git.mjs

@@ -0,0 +1,67 @@
+import { execSync, spawnSync } from 'child_process'
+
+function exec(cmd) {
+  return execSync(cmd, { encoding: 'utf-8', stdio: 'pipe' }).trim()
+}
+
+export function getCurrentBranch() {
+  return exec('git rev-parse --abbrev-ref HEAD')
+}
+
+export function getGitRoot() {
+  return exec('git rev-parse --show-toplevel')
+}
+
+export function getChangedFiles() {
+  const output = exec('git status --porcelain')
+  if (!output) return []
+  return output
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => {
+      // format: XY<space>path (3 chars) or X<space>path (2 chars when Y is space)
+      const pathStart = line[2] === ' ' ? 3 : 2
+      return {
+        status: line.slice(0, pathStart - 1).trim(),
+        path: line.slice(pathStart).trim(),
+      }
+    })
+}
+
+export function hasUncommittedChanges() {
+  return getChangedFiles().length > 0
+}
+
+export function checkout(branch) {
+  exec(`git checkout ${branch}`)
+}
+
+export function pull() {
+  exec('git pull')
+}
+
+export function createBranch(name) {
+  exec(`git checkout -b ${name}`)
+}
+
+export function addFiles(paths) {
+  // spawnSync with an array of args avoids any shell quoting issues
+  const result = spawnSync('git', ['add', '--', ...paths], {
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  })
+  if (result.status !== 0) {
+    throw new Error(result.stderr || 'git add falhou')
+  }
+}
+
+export function commit(message) {
+  // pipe stdin to avoid conflicts with the interactive terminal of clack
+  // inherit stdout/stderr so that lefthook/commitlint appear normally
+  const result = spawnSync('git', ['commit', '-m', message], {
+    stdio: ['pipe', 'inherit', 'inherit'],
+  })
+  if (result.status !== 0) {
+    throw new Error('git commit falhou — veja a saída acima')
+  }
+}

package/lib/slugify.mjs

@@ -0,0 +1,14 @@
+/**
+ * Converts free text to kebab-case without accents.
+ * Example: "Add Login Screen" -> "add-login-screen"
+ */
+export function slugify(text) {
+  return text
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '') // remove diacritics
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}

package/lib/types.mjs

@@ -0,0 +1,45 @@
+export const COMMIT_TYPES = [
+  { value: 'feat', label: 'feat     · New feature' },
+  { value: 'fix', label: 'fix      · Bug fix' },
+  { value: 'docs', label: 'docs     · Documentation change' },
+  { value: 'style', label: 'style    · Formatting, no logic change' },
+  { value: 'refactor', label: 'refactor · Refactor without behavior change' },
+  { value: 'test', label: 'test     · Add or fix tests' },
+  { value: 'chore', label: 'chore    · Build tasks, configs, dependencies' },
+]
+
+export const COMMIT_FORMATS = [
+  {
+    value: 'conventional-ticket',
+    label: 'feat(PROJ-42): add login screen',
+    hint: 'Conventional Commits with ticket',
+  },
+  {
+    value: 'conventional',
+    label: 'feat: add login screen',
+    hint: 'Conventional Commits, no ticket',
+  },
+  {
+    value: 'ticket-conventional',
+    label: '[PROJ-42] feat: add login screen',
+    hint: 'Ticket first, then conventional type',
+  },
+]
+
+export const BRANCH_FORMATS = [
+  {
+    value: 'type-ticket-name',
+    label: 'feat/PROJ-42_add-login-screen',
+    hint: 'type/ticket_name',
+  },
+  {
+    value: 'type-name',
+    label: 'feat/add-login-screen',
+    hint: 'type/name (no ticket in branch)',
+  },
+  {
+    value: 'ticket-type-name',
+    label: 'PROJ-42/feat/add-login-screen',
+    hint: 'ticket/type/name',
+  },
+]

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "uva-cli",
+  "version": "1.0.0",
+  "description": "UVA CLI — Interactive Git workflow automation for teams",
+  "type": "module",
+  "bin": {
+    "uva": "./bin.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin.mjs",
+    "commands/",
+    "lib/",
+    "templates/"
+  ],
+  "keywords": [
+    "cli",
+    "git",
+    "conventional-commits",
+    "workflow",
+    "automation",
+    "interactive",
+    "branching"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test tests/slugify.test.mjs tests/format.test.mjs",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "lefthook install",
+    "prepublishOnly": "npm run format:check && npm run lint && npm test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0",
+    "commander": "^12.0.0",
+    "picocolors": "^1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.10.0",
+    "lefthook": "^2.1.12",
+    "prettier": "^3.9.6"
+  }
+}

package/templates/en/docs/adr.md

@@ -0,0 +1,45 @@
+# ADR: {{title}}
+
+**Date:** {{date}}
+**Author:** {{author}}
+**Status:** Proposed
+
+---
+
+## Context
+
+<!-- What is the situation? What forces are at play — technical, product, team, or otherwise?
+     Include enough background for someone unfamiliar with the problem to understand it. -->
+
+## Decision
+
+<!-- State the decision clearly and directly. -->
+
+## Rationale
+
+<!-- Why this option over the others? What trade-offs were accepted? -->
+
+## Consequences
+
+### Positive
+
+-
+
+### Negative
+
+-
+
+### Risks
+
+-
+
+## Alternatives Considered
+
+| Alternative | Why it was not chosen |
+| :---------- | :-------------------- |
+|             |                       |
+|             |                       |
+
+## References
+
+-