{"id":41780792,"url":"https://github.com/alejandrochvs/devflow-cli","last_synced_at":"2026-01-25T04:00:56.181Z","repository":{"id":334291016,"uuid":"1140881686","full_name":"alejandrochvs/devflow-cli","owner":"alejandrochvs","description":"Interactive CLI for branch creation, conventional commits, and PR management","archived":false,"fork":false,"pushed_at":"2026-01-24T02:42:27.000Z","size":5421,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T10:59:22.050Z","etag":null,"topics":["cli","conventional-commits","developer-tools","git","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://devflow.alejandrochaves.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alejandrochvs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-23T21:55:50.000Z","updated_at":"2026-01-24T02:46:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alejandrochvs/devflow-cli","commit_stats":null,"previous_names":["alejandrochvs/devflow-cli"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/alejandrochvs/devflow-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrochvs%2Fdevflow-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrochvs%2Fdevflow-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrochvs%2Fdevflow-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrochvs%2Fdevflow-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alejandrochvs","download_url":"https://codeload.github.com/alejandrochvs/devflow-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrochvs%2Fdevflow-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28742983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T02:46:29.005Z","status":"ssl_error","status_checked_at":"2026-01-25T02:44:29.968Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","conventional-commits","developer-tools","git","nodejs","typescript"],"created_at":"2026-01-25T04:00:55.436Z","updated_at":"2026-01-25T04:00:56.170Z","avatar_url":"https://github.com/alejandrochvs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @alejandrochaves/devflow-cli\n\nInteractive CLI for branch creation, conventional commits, and PR management.\n\n## Install\n\n```bash\nnpm install -D @alejandrochaves/devflow-cli\n```\n\n## Quick Start\n\n```bash\n# Initialize config in your project\nnpx devflow init\n\n# Create a branch\nnpx devflow branch\n\n# Stage files and commit\nnpx devflow commit\n\n# Create or update a PR\nnpx devflow pr\n```\n\nOr add scripts to your `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"branch\": \"devflow branch\",\n    \"commit\": \"devflow commit\",\n    \"pr\": \"devflow pr\"\n  }\n}\n```\n\n## Commands\n\n### `devflow init`\n\nInteractive setup wizard that configures your entire project. Walks you through:\n\n1. **Ticket base URL** — for linking tickets in PRs\n2. **Scopes** — add project-specific scopes one by one (or use defaults)\n3. **PR checklist** — customize or use defaults\n4. **package.json scripts** — auto-adds `commit`, `branch`, `pr` scripts\n5. **Commitlint** — creates config with the devflow parser preset, installs deps\n6. **Husky** — installs, initializes, creates `commit-msg` hook + optional `pre-push` hook (lint + typecheck)\n7. **CI workflow** — optionally generates `.github/workflows/ci.yml` (lint, typecheck, test)\n\n### `devflow branch` (alias: `b`)\n\nInteractive branch creation with consistent naming.\n\n**Flow:**\n1. Select branch type (feat, fix, chore, refactor, docs, test, release, hotfix)\n2. Enter ticket number (or leave blank for `UNTRACKED`)\n3. Enter short description (auto-kebab-cased)\n4. Preview and confirm\n\n**Branch format:**\n```\ntype/TICKET_description\n```\n\n**Examples:**\n```\nfeat/ENV-123_add-budget-sharing\nfix/PROJ-45_correct-calculation-overflow\nchore/UNTRACKED_update-dependencies\n```\n\n### `devflow commit` (alias: `c`)\n\nInteractive conventional commit with file staging, scope selection, and ticket inference.\n\n**Branch protection:** If you're on `main`, `master`, `develop`, or `production`, devflow warns you and asks for confirmation before proceeding.\n\n**Flow:**\n1. If no files are staged, select files to stage (checkbox selection)\n2. Select commit type\n3. Select or enter scope (searchable list if configured, free text otherwise)\n4. Enter commit subject\n5. Optional: enter commit body (longer description)\n6. Confirm if breaking change (adds `BREAKING CHANGE:` footer)\n7. Optional: enter ticket reference (added as `Refs: TICKET` footer)\n8. Preview and confirm\n\n**Commit format:**\n```\ntype[ticket](scope): message\n```\n\nThe ticket is automatically inferred from the branch name. If the branch doesn't follow the `type/TICKET_description` format, it defaults to `UNTRACKED`.\n\n**Examples:**\n```\nfeat[ENV-123](auth): add biometric login\nfix[PROJ-45](budget): correct calculation overflow\nchore[UNTRACKED](deps): update dependencies\nrefactor[ENV-200]!(api): restructure endpoints\n```\n\nThe `!` after the ticket indicates a breaking change.\n\n### `devflow pr` (alias: `p`)\n\nCreate or update a pull request with an auto-filled template.\n\n**Flow:**\n1. Checks if a PR already exists for the current branch (offers to update)\n2. Infers the base branch (closest remote branch by merge-base)\n3. Enter PR title (pre-filled from branch description)\n4. Enter optional summary\n5. Preview PR body with template\n6. Confirm and create/update\n\n**Features:**\n- Auto-detects existing PRs and offers update flow\n- Infers base branch using `git merge-base` comparison\n- Pre-fills commit list in the summary\n- Auto-labels from branch type (feat → `feature`, fix → `bug`, etc.)\n- Auto-labels from commit scopes\n- Self-assigns with `@me`\n- Creates as draft by default\n- Links ticket if `ticketBaseUrl` is configured\n\n**PR template includes:**\n- Summary (with commit list)\n- Ticket (linked if base URL configured)\n- Type of Change (checkboxes, auto-checked from branch type)\n- Screenshots table\n- Test Plan\n- Checklist (customizable via config)\n\n### `devflow test-plan` (alias: `tp`)\n\nView or edit the test plan for the current branch. Test plan steps are stored locally and automatically included in the PR body.\n\n**Flow:**\n- If a test plan exists: view steps and choose to add, replace, or clear\n- If no test plan: prompted to add steps\n\nSteps are also optionally collected during `devflow branch` creation.\n\nWhen you run `devflow pr`, stored test plan steps auto-populate the \"Test Plan\" section as checkboxes:\n\n```markdown\n## Test Plan\n\n- [ ] Verify login flow with valid credentials\n- [ ] Test error handling for expired tokens\n- [ ] Confirm logout clears session data\n```\n\n### `devflow release` (alias: `rel`)\n\nAutomated release flow: version bump, changelog update, git tag, push, and GitHub release.\n\n**Flow:**\n1. Detects current version from `package.json`\n2. Analyzes commits since last tag to suggest bump type (patch/minor/major)\n3. Confirm version\n4. Updates `CHANGELOG.md` with grouped commits\n5. Commits version bump and changelog\n6. Creates git tag\n7. Pushes tag and commits\n8. Creates GitHub release with changelog body\n\nRequires `gh` CLI for the GitHub release step.\n\n### `devflow review` (alias: `rv`)\n\nList and interact with open pull requests.\n\n**Flow:**\n1. Lists open PRs for the repo with author, title, and status\n2. Select a PR to inspect\n3. Shows diff stat summary\n4. Choose an action: checkout, approve, comment, request changes, or open in browser\n\nRequires `gh` CLI.\n\n### `devflow comments` (alias: `cm`)\n\nShow PR reviews and inline comments with diff context. Displays all reviews and inline code comments grouped by file, with the surrounding diff hunk so you can see exactly what was commented on.\n\n**Usage:**\n```bash\n# Comments for the current branch's PR\ndevflow comments\n\n# Comments for a specific PR\ndevflow comments --number 303\n```\n\nRequires `gh` CLI.\n\n### `devflow issue` (alias: `i`)\n\nCreate GitHub issues using Scrum-style templates with an interactive flow.\n\n**Issue Types:**\n\n| Type | Label | Branch Type |\n|------|-------|-------------|\n| User Story | `feature` | `feat/` |\n| Bug | `bug` | `fix/` |\n| Task | `task` | `chore/` |\n| Spike | `spike` | `chore/` |\n| Tech Debt | `tech-debt` | `refactor/` |\n\n**Flow:**\n1. Select issue type\n2. Fill in type-specific fields (guided prompts)\n3. Preview the issue\n4. Confirm and create via `gh issue create`\n5. Optionally create a branch and start working\n\n**Example:**\n```\n$ devflow issue\n? Select issue type: › User Story\n? As a: › logged-in user\n? I want to: › export my data as CSV\n? So that: › I can use it in spreadsheets\n? Acceptance criteria:\n  1. CSV includes all user data\n  2. (blank to finish)\n\n─── Issue Preview ───\nType:   User Story\nTitle:  export my data as CSV\nLabels: feature\n\n? Create this issue? › Yes\n✓ Issue created: https://github.com/owner/repo/issues/42\n\n? Create a branch and start working on this issue? › Yes\n? Short branch description: › export-csv\n✓ Branch created: feat/#42_export-csv\n```\n\nRequires `gh` CLI.\n\n### `devflow stash` (alias: `st`)\n\nNamed stash management with an interactive interface.\n\n**Actions:**\n- **Save** — stash with a descriptive name, optionally include untracked files\n- **Pop** — apply and remove a stash\n- **Apply** — apply without removing\n- **Drop** — delete a stash\n- **Show** — view the stash diff\n\n### `devflow worktree` (alias: `wt`)\n\nManage git worktrees for working on multiple branches in parallel.\n\n**Actions:**\n- **Add** — create a new worktree (auto-creates branch if needed), suggests a path based on repo root\n- **Remove** — select and remove a worktree (with force option for dirty trees)\n\nShows all existing worktrees with the current one highlighted.\n\n### `devflow log` (alias: `l`)\n\nInteractive commit history with actions.\n\n**Flow:**\n1. Shows commits on the current branch (since diverging from base)\n2. Select a commit to inspect\n3. Shows commit details and file stats\n4. Choose an action: cherry-pick, revert, create fixup, or view full diff\n\n### `devflow stats`\n\nShow commit pattern analytics for the repository:\n\n- **Commit types** — distribution with bar chart (feat, fix, chore, etc.)\n- **Top scopes** — most frequently used scopes\n- **Contributors** — commit counts per author\n- **Summary** — total commits, local branches, first commit date\n\n### `devflow lint-config` (alias: `lint`)\n\nValidate `.devflow/config.json` for errors and warnings. Designed to run in CI pipelines (exits with code 1 on errors).\n\n**Checks:**\n- Valid JSON syntax\n- Config structure validation (via `validateConfig`)\n- Scopes have descriptions\n- Scope path patterns contain globs or path separators\n- PR template sections are recognized values\n- Commit format placeholders are valid\n\n```bash\n# In CI\nnpx devflow lint-config\n```\n\n### `devflow undo` (alias: `u`)\n\nUndo the last commit, keeping changes staged. Shows a preview of the commit that will be undone before confirming.\n\n### `devflow fixup` (alias: `f`)\n\nCreate a fixup commit targeting a previous commit on the branch:\n\n1. Shows recent commits on the branch\n2. Select which commit to fix\n3. Stage files (if needed)\n4. Optionally auto-squash via interactive rebase\n\n### `devflow merge` (alias: `m`)\n\nMerge the current branch's PR via GitHub CLI:\n\n1. Detects the PR for the current branch\n2. Select merge strategy (squash, merge, rebase)\n3. Optionally delete the branch and switch back to main\n\nRequires `gh` CLI to be installed and authenticated.\n\n### `devflow status` (alias: `s`)\n\nAt-a-glance view of your current branch context:\n- Branch name, type, ticket, and description\n- Inferred base branch\n- Commit count with recent messages\n- Working tree status (staged/modified/untracked)\n- PR link and state (if exists)\n\n### `devflow amend` (alias: `a`)\n\nRe-edit the last commit message using the same guided prompts. Pre-fills all fields from the existing message. Also includes any staged changes in the amend.\n\n### `devflow cleanup`\n\nFinds and deletes local branches that are:\n- Merged into `main`\n- Tracking a remote branch that no longer exists\n\nFetches remote state first, shows checkbox selection, and asks for confirmation before force-deleting unmerged branches.\n\n### `devflow changelog`\n\nGenerates a changelog entry from conventional commits since the last git tag:\n- Groups by type (Features, Bug Fixes, etc.)\n- Highlights breaking changes\n- Auto-suggests the next version (semver bump based on commit types)\n- Prepends to `CHANGELOG.md`\n\n### `devflow doctor`\n\nChecks that all devflow dependencies are properly configured:\n- git, node (\u003e= 20), gh CLI + auth\n- `.devflow/config.json`, commitlint config, husky hooks\n- `package.json` scripts\n\n### `devflow completions`\n\nOutputs shell completion scripts for tab-completion of commands:\n\n```bash\n# zsh (add to ~/.zshrc)\neval \"$(devflow completions --shell zsh)\"\n\n# bash (add to ~/.bashrc)\neval \"$(devflow completions --shell bash)\"\n```\n\n## Command Aliases\n\n| Command | Alias |\n|---------|-------|\n| `devflow branch` | `devflow b` |\n| `devflow commit` | `devflow c` |\n| `devflow pr` | `devflow p` |\n| `devflow amend` | `devflow a` |\n| `devflow undo` | `devflow u` |\n| `devflow fixup` | `devflow f` |\n| `devflow merge` | `devflow m` |\n| `devflow release` | `devflow rel` |\n| `devflow review` | `devflow rv` |\n| `devflow comments` | `devflow cm` |\n| `devflow issue` | `devflow i` |\n| `devflow stash` | `devflow st` |\n| `devflow worktree` | `devflow wt` |\n| `devflow log` | `devflow l` |\n| `devflow status` | `devflow s` |\n| `devflow test-plan` | `devflow tp` |\n| `devflow lint-config` | `devflow lint` |\n\n## Global Options\n\nCommands that modify git state support `--dry-run` to preview without executing:\n\n```bash\ndevflow commit --dry-run\ndevflow branch --dry-run\ndevflow pr --dry-run\ndevflow amend --dry-run\ndevflow undo --dry-run\ndevflow fixup --dry-run\ndevflow merge --dry-run\ndevflow cleanup --dry-run\ndevflow changelog --dry-run\ndevflow issue --dry-run\n```\n\n## Configuration\n\nCreate a `.devflow/config.json` in your project (or run `devflow init`):\n\n```json\n{\n  \"ticketBaseUrl\": \"https://github.com/org/repo/issues\",\n  \"scopes\": [\n    { \"value\": \"auth\", \"description\": \"Authentication \u0026 login\", \"paths\": [\"src/auth/**\"] },\n    { \"value\": \"ui\", \"description\": \"UI components\", \"paths\": [\"src/components/**\"] },\n    { \"value\": \"api\", \"description\": \"API layer\", \"paths\": [\"src/api/**\", \"src/services/**\"] }\n  ],\n  \"branchTypes\": [\"feat\", \"fix\", \"chore\", \"refactor\", \"docs\", \"test\", \"release\", \"hotfix\"],\n  \"commitTypes\": [\n    { \"value\": \"feat\", \"label\": \"feat:     A new feature\" },\n    { \"value\": \"fix\", \"label\": \"fix:      A bug fix\" }\n  ],\n  \"commitFormat\": \"{type}[{ticket}]{breaking}({scope}): {message}\",\n  \"checklist\": [\n    \"Code follows project conventions\",\n    \"Self-reviewed the changes\",\n    \"No new warnings or errors introduced\"\n  ],\n  \"prTemplate\": {\n    \"sections\": [\"summary\", \"ticket\", \"type\", \"screenshots\", \"testPlan\", \"checklist\"],\n    \"screenshotsTable\": true\n  },\n  \"prReviewers\": [\"copilot\"]\n}\n```\n\n### Config Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `ticketBaseUrl` | Base URL for linking tickets in PRs | — |\n| `scopes` | List of scopes with `value`, `description`, and optional `paths` for auto-inference | `[]` (free text input) |\n| `scopes[].paths` | Glob patterns to auto-suggest this scope when matching files are staged | — |\n| `branchTypes` | Allowed branch type prefixes | `[\"feat\", \"fix\", \"chore\", ...]` |\n| `commitTypes` | Commit types shown in selection menu (`value` + `label`) | Standard conventional types |\n| `commitFormat` | Commit message format with `{type}`, `{ticket}`, `{breaking}`, `{scope}`, `{message}` placeholders | `{type}[{ticket}]{breaking}({scope}): {message}` |\n| `checklist` | PR checklist items | Basic code review items |\n| `prTemplate.sections` | PR body sections to include | All sections |\n| `prTemplate.screenshotsTable` | Include before/after screenshots table | `true` |\n| `prReviewers` | Default PR reviewers (GitHub usernames) | — |\n\n### Shareable Configs (`extends`)\n\nShare a base configuration across projects using the `extends` field:\n\n```json\n{\n  \"extends\": \"@myorg/devflow-config\",\n  \"ticketBaseUrl\": \"https://jira.myorg.com/browse\"\n}\n```\n\nThe `extends` value can be:\n- An npm package name (resolved from `node_modules`)\n- A relative file path (e.g., `\"./config/devflow-base.json\"`)\n\nThe extended config is merged with local overrides — local fields take precedence.\n\n### Monorepo Awareness\n\ndevflow automatically detects monorepo workspace setups and uses workspace packages as commit scopes when no scopes are configured. Supported:\n\n- **npm/yarn workspaces** — `workspaces` field in `package.json`\n- **pnpm workspaces** — `pnpm-workspace.yaml`\n- **Lerna** — `lerna.json`\n- **Nx** — `nx.json` with `project.json` files\n- **Turborepo** — `turbo.json` (uses package.json workspaces)\n\nEach workspace package becomes a scope with its directory as the `paths` pattern for auto-inference. For example, in a monorepo with `packages/auth` and `packages/ui`, staging a file in `packages/auth/src/login.ts` auto-suggests the `auth` scope.\n\n### Scopes\n\nWhen `scopes` is an empty array, the commit command shows a free text input for scope. When populated, it shows a searchable list that can be filtered by typing.\n\n**Scope inference** works in two ways (first match wins):\n\n1. **From file paths** — if a scope has `paths` configured, staged files are matched against those glob patterns. The scope with the most matching files is suggested.\n2. **From git history** — previous commits on the branch (`git log main..HEAD`) are parsed for existing scopes.\n\nExample with paths:\n```json\n{\n  \"scopes\": [\n    { \"value\": \"auth\", \"description\": \"Authentication\", \"paths\": [\"src/auth/**\", \"src/hooks/useAuth*\"] },\n    { \"value\": \"ui\", \"description\": \"UI components\", \"paths\": [\"src/components/**\"] }\n  ]\n}\n```\n\nIf you stage `src/auth/login.ts`, the `auth` scope is auto-suggested.\n\n## Commitlint Integration\n\nIf you use [commitlint](https://commitlint.js.org/) to enforce commit conventions, add this parser preset to handle the `type[ticket](scope): message` format:\n\n```javascript\n// commitlint.config.js\nmodule.exports = {\n  extends: ['@commitlint/config-conventional'],\n  parserPreset: {\n    parserOpts: {\n      headerPattern: /^(\\w+)\\[.*?\\]!?\\((.+)\\): (.+)$/,\n      headerCorrespondence: ['type', 'scope', 'subject'],\n    },\n  },\n  rules: {\n    'subject-case': [0],\n  },\n};\n```\n\n## Git Hooks\n\nPair with [husky](https://typicode.github.io/husky/) for a guided commit experience:\n\n```bash\n# .husky/commit-msg\nnpx --no -- commitlint --edit $1 || {\n  echo \"\"\n  echo \"  Commit message does not follow the required format.\"\n  echo \"  Use: npm run commit\"\n  echo \"\"\n  exit 1\n}\n```\n\nThe `devflow init` wizard can also set up a **pre-push** hook that runs lint and type checking before push:\n\n```bash\n# .husky/pre-push\nnpm run lint\nnpx tsc --noEmit\n```\n\n## Update Notifications\n\ndevflow checks for newer versions on npm once every 24 hours and displays a non-blocking notification if an update is available:\n\n```\n─ Update available: 0.2.0 → 0.3.0 (npm update @alejandrochaves/devflow-cli) ─\n```\n\n## Plugins\n\nExtend devflow with custom commands via the plugin system. Plugins are automatically discovered from:\n\n1. **npm packages** — any dependency matching `devflow-plugin-*` or `@scope/devflow-plugin-*`\n2. **Config** — explicit list in `.devflow/config.json`:\n\n```json\n{\n  \"plugins\": [\"devflow-plugin-jira\", \"@myorg/devflow-plugin-deploy\"]\n}\n```\n\n### Writing a Plugin\n\nA plugin is an npm package that exports a `register` function:\n\n```typescript\nimport { Command } from \"commander\";\n\nexport function register(program: Command): void {\n  program\n    .command(\"deploy\")\n    .description(\"Deploy the current branch\")\n    .action(() =\u003e {\n      // your logic here\n    });\n}\n```\n\nPlugins receive the Commander `program` instance and can add commands, options, or hooks.\n\n## Requirements\n\n- Node.js \u003e= 20.12\n- Git\n- [GitHub CLI (gh)](https://cli.github.com/) — required for the `pr` command\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandrochvs%2Fdevflow-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falejandrochvs%2Fdevflow-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandrochvs%2Fdevflow-cli/lists"}