atomcommit

atomcommit is a local-first CLI that turns staged and unstaged git diffs into deterministic atomic commit plans.

Status

Early V0.1 release candidate. The planner is useful for local git diffs, but it does not stage files, create commits, push branches, or infer product intent.

Install from a checkout

git clone https://github.com/rogerchappel/atomcommit.git
cd atomcommit
npm install

After publication, install the CLI with npm:

npm install -g atomcommit

Quickstart

From a checkout, generate an atomic commit plan for the current repository:

node src/index.js plan

After installing the package binary, use the shorter command:

atomcommit
atomcommit plan

Use JSON output for automation:

atomcommit plan --json

Print version or help without needing to be inside a git repository:

atomcommit --version
atomcommit --help

What it reads

atomcommit shells out to read-only git diff commands:

• git diff --name-status
• git diff --cached --name-status
• git diff --numstat
• git diff --stat

It groups changes by repository area such as documentation, tests, source code, package metadata, and CI automation. It also flags review risks such as deletions, renames, lockfiles, large changes, binary files, and sensitive-looking paths.

Fixture smoke

The repository includes a deterministic mixed-change fixture:

bash fixtures/setup-mixed-changes.sh /tmp/atomcommit-fixture
cd /tmp/atomcommit-fixture
node /path/to/atomcommit/src/index.js plan --json

The fixture covers source edits, docs, tests, workflow changes, a rename, and a deletion.

Verification

npm test
npm run check
npm run smoke
npm run package:smoke
npm run release:check
bash scripts/validate.sh

Limitations

• The package is still a v0.1.0 project and its JSON shape may change before 1.0.
• Commit boundaries are structural suggestions. Humans still choose the final history.
• Sensitive-path flags are heuristics, not a secret scanner or compliance control.
• Git rename detection follows git diff --name-status; unusual diff settings can affect rename reporting.

Contributing

See CONTRIBUTING.md. Keep changes small, update the PRD or README when scope changes, and include the exact verification command in every pull request.

Security

See SECURITY.md. Do not include secrets, private tokens, proprietary dependency data, or sensitive logs in public issues or examples.

License

MIT

Release Verification

Before publishing or tagging a release, run the local verification path that matches CI:

• npm run release:check
• npm run package:smoke

The release checklist in docs/release-readiness.md captures the package surface, CLI bins, and reviewer notes for future release PRs.