zapdev：轻量级 TypeScript CLI，自动生成 Conventional Commit 并扫描密钥

Project Introduction

zapdev is a lightweight TypeScript CLI that makes small, repetitive Git chores fast and precise.

It stages changes, scans them for secrets, and generates Conventional Commit messages for one repository or several direct child repositories in a single review flow.

Project Architecture

flowchart LR
  Entry["src/index.ts"] --> CLI["src/cli.ts"]
  CLI --> Commands["src/commands"]
  Commands --> Lib["src/lib"]
  Commands --> Types["src/types"]
  Lib --> Prompts["src/prompts"]
  Lib --> Types
  Lib --> Tools["Git, Gitleaks, LLM API"]

Loading

• src/index.ts: bin launcher; enables the V8 compile cache, then loads cli.js.
• src/cli.ts: CLI entry; registers commit as the default command.
• src/commands/: command UI and orchestration.
• src/lib/: pure logic and isolated Git, Gitleaks, and LLM side effects.
• src/prompts/: LLM prompts inlined into the bundle at build time.
• src/types/: shared type declarations.

Environment Variables

The LLM settings have no defaults, automatic provider detection, or backup models. CLI flags override these settings. Legacy OLLAMA_* variables are no longer read.

Requests use the OpenAI Chat Completions format over plain fetch, without a provider SDK. No authentication headers are sent; use an endpoint that does not require them. The endpoint and model must support reasoning_effort.

Setup

Requirements

• Node.js >= 20 (required): runs the CLI.
• Git (required): provides the repository operations.
• OpenAI-compatible Chat Completions endpoint (required for commit): generates Conventional Commit messages.
• Gitleaks (recommended): scans staged changes before message generation when available on PATH.

Install

Install zapdev globally for daily use:

npm install -g zapdev

or

bun install -g zapdev

Configure your endpoint and model before running commit (replace these example values):

export ZD_URL="http://localhost:1234/v1/chat/completions"
export ZD_MODEL="your-model-id"
export ZD_EFFORT="low"

Or run it once without installing:

npx zapdev commit

Development Setup

From a clone:

npm install
npm run zapdev      # build then run the CLI in dev
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm run test        # vitest
npm run build       # bundle to dist/ with esbuild

npm link exposes the local zapdev binary after npm run build.

Usage

Run zapdev or zapdev commit to start the commit flow. Both accept the flags below.

zapdev commit

Stages changes, scans for secrets with Gitleaks when installed, generates Conventional Commit messages, then lets you review and optionally push.

• Repositories: uses the current Git repository (including from a subdirectory), or direct child repositories when outside one. No recursive search; node_modules is excluded.
• Review: commit all, commit one repository, edit a message, or cancel. Unselected changes remain staged.
• Push: asks once, only for repositories committed during this run. Use --push to skip confirmation or --no-push to keep commits local. With --yes, nothing is pushed unless --push is explicitly set.

zapdev commit              # review messages, commit, then confirm push
zapdev commit -t feat      # force the commit type
zapdev commit -t 'feat!'   # force a breaking change
zapdev commit -syp         # commit staged changes and push without review
zapdev commit --pull       # pull first, then follow the normal flow

Supported types: feat, fix, deps, chore, docs, style, refactor, perf, test, build, ci, revert. Messages are limited to 72 characters; the model can add ! for breaking changes.

All explicit flags override --yes, regardless of argument order: -T asks for the type and breaking change, -A asks for branches, --push pushes, --no-push keeps commits local, --pull pulls first, and --staged commits only already-staged changes. --type, --url, --model, and --effort still apply. Unrequested prompts stay skipped; --type preselects the type when -T is set.

Branches: before committing on main, master, principal, dev, or development, zapdev asks for a local branch unless --yes is set. A different name switches to an existing branch or creates it before the commit. Prompts reuse the previous input; empty input keeps the current branch. -A asks on every branch, including with --yes.

Safety: a failed Gitleaks scan stops the flow before any commit or sending that repository's diff to the LLM. Without Gitleaks, scanning is skipped. Commit context is sent to your configured endpoint, which may be remote; binary content and patches matching src/config/diff.gitignore are omitted, but those files are still committed.

Git: --pull only pulls repositories with changes to commit and a configured upstream, without rebase or automatic stash. Push uses the current branch's name and its upstream remote, then origin, then the only remote; ambiguous or missing remotes are skipped. No force-push. Errors stop the flow without undoing earlier pulls or commits; cancelling branch selection also stops all pushes.

Without a terminal: review is skipped, explicit -T / -A prompts are refused even with --yes, and protected branches require --yes to commit without a branch prompt. Commits stay local unless --push is set. Git hooks have a 60-second timeout (ZD_HOOK_TIMEOUT to override); interactive hooks must use /dev/tty.

Zed IDE

For a faster review and commit workflow, review and stage changes from Zed's Git panel, then run zapdev commit -syp from a task. The command commits only staged changes, skips all prompts, and pushes the current branch, including protected branches.

Add the following tasks to .zed/tasks.json:

[
  {
    "label": "zapdev commit",
    "command": "zapdev commit --yes",
    "reveal": "always",
    "hide": "on_success",
    "reveal_target": "center"
  }
]

Add this entry to Zed's keymap.json to run the commit task with ctrl-cmd-enter:

{
  "context": "Pane",
  "bindings": {
    "ctrl-cmd-enter": ["task::Spawn", { "task_name": "zapdev commit" }]
  }
}

Shell Aliases

alias commit="zapdev commit --yes"

Other

zapdev is available under the MIT license.