smart-commit-copilot-cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,48 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-04-14
+
+### Added
+
+- `bridge` output now includes structured `reviewDetails` in both JSON and text render paths
+- bundled commit-message skill context is now injected for built-in `conventional`, `semantic`, and `gitmoji` profiles
+- focused regression coverage for config resolution, OpenAI-compatible request handling, Git utilities, output rendering, reporting, and CLI report command branches
+- dedicated Git utility tests for repository root resolution, detached HEAD fallback, upstream detection, working-tree state, and staged deleted-file snapshots
+
+### Changed
+
+- default `passHistory.maxEntries` is now `3000`
+- pass-history record field ordering now follows the legacy Smart Commit compatibility shape more closely
+- built-in commit-message prompt builders now carry explicit protocol rules into generation and repair prompts
+- conventional commit generation guidance now aligns more closely with the VS Code plugin behavior
+
+### Fixed
+
+- review gating continues to follow the numeric-score-first rule consistently across bridge execution and smoke verification
+- report command coverage now includes missing `--repo`, omitted `--period`, non-Git paths, file-path misuse, missing pass-history, and missing AI connection config scenarios
+- release docs are now aligned with the current `0.1.2` publish target instead of older draft references
+
+## [0.1.1] - 2026-04-14
+
+### Added
+
+- repeatable `npm run smoke:test` command for real CLI command-path regression checks
+- `docs/verification.md` to document the command-level verification flow
+- AI report fallback coverage in the smoke regression path
+
+### Changed
+
+- GitHub Actions CI now runs `npm run smoke:test` on Node 20 in addition to `npm test`
+- release checklist now points to the repeatable verification flow instead of relying only on manual spot-checks
+- publish guidance is now easier to reuse for follow-up releases after `0.1.0`
+
+### Fixed
+
+- command-level release verification now explicitly covers relative and absolute `--config` paths
+- command-level release verification now explicitly checks that `--no-commit --no-push` leaves `HEAD` unchanged
+- review gating now aligns with the VS Code plugin: when a numeric score exists, score vs threshold is the final pass or block standard
+
 ## [0.1.0] - 2026-04-13
 
 ### Added

package/README.md

@@ -1,101 +1,131 @@
 # smart-commit CLI
 
-Standalone CLI-first automation runtime for shell, Husky, Cursor hook, and external agent workflows.
+`smart-commit CLI` is a shell-first tool for automated commit review, commit-message generation, and report workflows.
 
-This project is intentionally separate from the VS Code extension runtime. Its goal is simple: expose a stable CLI that can be embedded into real engineering workflows.
+Use it when you want the same workflow to run from a terminal, script, hook, or agent.
 
-## What It Does
+It can:
 
-`smart-commit CLI` helps you automate four common steps around code changes:
+- inspect staged changes
+- generate or validate commit messages
+- run AI-assisted review gating
+- optionally commit and push
+- persist pass history
+- generate work reports
 
-1. Inspect staged changes
-2. Generate or validate commit messages
-3. Run AI-assisted review gating
-4. Persist pass history and generate work reports
+Install package:
 
-The current product surface includes:
-
-- `config resolve`
-- `bridge`
-- `report generate`
-- `schema print`
-
-## Who It Is For
+```bash
+npm install -g smart-commit-copilot-cli
+```
 
-This CLI is useful when you want `smart-commit` to run outside the editor:
+Run command:
 
-- shell scripts
-- Husky hooks
-- Cursor hooks
-- external agents
-- CI or local automation
+```bash
+smart-commit --help
+```
 
-## Before You Start
+Or use `npx` directly:
 
-Current repository state:
+```bash
+npx smart-commit-copilot-cli --help
+```
 
-- the package is now configured for npm publication
-- the easiest way to try it is from a local checkout
-- command examples below use `smart-commit`
+## Quick Start
 
-If you have not linked the binary yet, replace `smart-commit` with:
+### 1. Prepare your API key
 
 ```bash
-node out/cli.js
+export SMART_COMMIT_API_KEY="your-api-key"
 ```
 
-## 5-Minute Quick Start
+### 2. Create a config file
 
-### 1. Prepare the CLI
+Create `smart-commit.json` in your repository:
 
-```bash
-npm install
-npm run build
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    },
+    "review": {
+      "threshold": 6,
+      "language": "zh"
+    },
+    "commitMessage": {
+      "language": "zh",
+      "autoGenerate": true,
+      "hybridGenerate": false,
+      "validation": {
+        "protocol": "none",
+        "pattern": "",
+        "extractTicketIdFromBranch": true,
+        "requireTicketIdInMessage": false
+      }
+    },
+    "git": {
+      "autoStageWhenNothingStaged": true,
+      "autoCommit": false,
+      "autoPush": false
+    },
+    "passHistory": {
+      "enabled": true,
+      "dirPath": ".smart-commit-cli",
+      "maxEntries": 3000
+    },
+    "reporting": {
+      "language": "zh",
+      "weekStartsOn": "monday",
+      "outputDirPath": ".smart-commit-cli/reports",
+      "prompt": "",
+      "ai": {
+        "enabled": false
+      }
+    },
+    "output": {
+      "format": "json",
+      "logLevel": "info"
+    }
+  }
+}
 ```
 
-Optional, if you want the `smart-commit` command in your shell:
+### 3. Validate the config
 
 ```bash
-npm link
+smart-commit config resolve --config ./smart-commit.json
 ```
 
-### 2. Prepare your API key
+This is the recommended first command because it shows:
 
-```bash
-export SMART_COMMIT_API_KEY="your-api-key"
-```
+- merged config after CLI args, env vars, file config, and defaults
+- secret redaction
+- validation errors before real execution
 
-### 3. Copy the example config
+For human-readable output:
 
 ```bash
-cp examples/config/smart-commit.json ./smart-commit.json
+smart-commit config resolve --config ./smart-commit.json --output text
 ```
 
-The example config already demonstrates the recommended canonical format:
+### 4. Run a safe preflight
 
-- `smartCommitCli`
-- `apiKey: "env:SMART_COMMIT_API_KEY"`
-- JSON output by default
-
-### 4. Validate the merged config
+Stage some changes first:
 
 ```bash
-smart-commit config resolve --config ./smart-commit.json
+git add -A
 ```
 
-What this gives you:
-
-- final merged config after CLI args, env vars, file config, and defaults
-- secret redaction in output
-- early validation before real automation wiring
-
-### 5. Run a safe preflight on your repo
+Then run:
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json --dry-run
 ```
 
-This is the recommended first real command. It checks:
+This checks:
 
 - repository path is valid
 - current directory is inside Git
@@ -103,90 +133,65 @@ This is the recommended first real command. It checks:
 - commit message can be resolved
 - bridge input is ready for execution
 
-### 6. Run review-only mode
+### 5. Run review-only mode
+
+This is the safest way to start using the tool in a real workflow:
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
 ```
 
-This is the safest production onboarding mode:
+It will:
 
-- review runs
-- commit message logic runs
-- no Git side effects happen
+- run review
+- run commit-message logic
+- return structured output
+- avoid Git side effects
 
-## Fastest Path To Value
+When the review returns a numeric score, the final pass or block result is determined by comparing that score with `review.threshold`.
 
-If you only want the shortest route to practical usage, use this sequence:
+If you only want the shortest path:
 
-1. `smart-commit config resolve --config ./smart-commit.json`
-2. `smart-commit bridge --repo . --config ./smart-commit.json --dry-run`
-3. `smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push`
-4. wire the same command into Husky or Cursor hook
-5. enable `passHistory`
-6. add `report generate`
+1. install `smart-commit-copilot-cli`
+2. export `SMART_COMMIT_API_KEY`
+3. create `smart-commit.json`
+4. run `smart-commit config resolve`
+5. run `smart-commit bridge --dry-run`
+6. run `smart-commit bridge --no-commit --no-push`
 
 ## Core Commands
 
-### `config resolve`
-
-Use this to inspect the final config after all sources are merged.
+### Resolve config
 
 ```bash
 smart-commit config resolve --config ./smart-commit.json
 ```
 
-Useful when:
-
-- you are debugging precedence issues
-- you want to verify `env:VAR_NAME` resolution
-- you want to confirm defaults before automation rollout
-
-### `bridge`
-
-This is the main automation entrypoint.
-
-```bash
-smart-commit bridge --repo . --config ./smart-commit.json
-```
-
-Typical modes:
-
-- preflight only:
+### Bridge preflight
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json --dry-run
 ```
 
-- review only:
+### Review-only bridge
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
 ```
 
-- full execution:
+### Full bridge execution
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json
 ```
 
-### `report generate`
-
-Generate a Markdown report from pass history.
+### Generate a report
 
 ```bash
 smart-commit report generate --repo . --config ./smart-commit.json --period weekly
 ```
 
-Useful when:
-
-- you want a local work report
-- you want scheduled summaries
-- you want agent-readable reporting output
-
-### `schema print`
-
-Print machine-facing JSON Schema for integration contracts.
+### Print machine-readable schema
 
 ```bash
 smart-commit schema print --target bridge
@@ -194,29 +199,24 @@ smart-commit schema print --target bridge
 
 ## Output Modes
 
-Default machine-facing mode:
+Default mode is machine-facing JSON:
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json
 ```
 
-Human-readable mode:
+For a terminal-friendly summary:
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json --output text
 ```
 
-Use JSON when:
+Recommended usage:
 
-- integrating with hooks or agents
-- branching on `status` and `error.code`
+- use JSON for hooks, agents, and automation
+- use text for manual debugging
 
-Use text when:
-
-- debugging manually
-- checking behavior in a terminal
-
-## How Configuration Works
+## Configuration Rules
 
 Config precedence from high to low:
 
@@ -228,99 +228,52 @@ Config precedence from high to low:
 
 Special rule:
 
-- string values like `env:SMART_COMMIT_API_KEY` are resolved from the current process environment after merge and before validation
-
-Recommended format:
-
-```json
-{
-  "smartCommitCli": {
-    "connection": {
-      "baseUrl": "https://api.openai.com/v1",
-      "apiKey": "env:SMART_COMMIT_API_KEY",
-      "model": "gpt-5"
-    },
-    "review": {
-      "threshold": 6,
-      "language": "zh"
-    },
-    "git": {
-      "autoCommit": true,
-      "autoPush": true
-    }
-  }
-}
-```
-
-The CLI still supports legacy `smartCommit.*` keys for migration, but `smartCommitCli` is the long-term recommended format.
-
-## Common Rollout Patterns
-
-### Local Manual Testing
-
-Use:
-
-```bash
-smart-commit bridge --repo . --config ./smart-commit.json --dry-run --output text
-```
-
-### Husky Pre-Commit
-
-Use review-only mode:
-
-```bash
-smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
-```
-
-Reference files:
-
-- [`examples/hooks/smart-commit-bridge.sh`](./examples/hooks/smart-commit-bridge.sh)
-- [`examples/hooks/husky-pre-commit.sh`](./examples/hooks/husky-pre-commit.sh)
-
-### Cursor Hook
-
-Use the same review-only bridge command behind a shell wrapper.
+- values like `env:SMART_COMMIT_API_KEY` are resolved from the current process environment after merge and before validation
 
-Reference file:
+Canonical format:
 
-- [`examples/hooks/cursor-bridge-wrapper.sh`](./examples/hooks/cursor-bridge-wrapper.sh)
+- `smartCommitCli` is the recommended long-term format
+- legacy `smartCommit.*` is supported for migration
 
-### External Agent
+## Automation-Friendly Capabilities
 
-Consume stdout as JSON and branch on:
+This package is designed to work well in shell-driven automation scenarios.
 
-- `schemaVersion`
-- `status`
-- `error.code`
+Typical examples include:
 
-Reference files:
+- Git hook style workflows
+- editor or IDE hook workflows
+- external agent workflows
+- local automation scripts
+- CI or scheduled reporting flows
 
-- [`examples/agent/bridge-agent.mjs`](./examples/agent/bridge-agent.mjs)
-- [`examples/agent/report-agent.mjs`](./examples/agent/report-agent.mjs)
+For machine integrations, the recommended pattern is:
 
-## Pass History And Reporting
+- call `smart-commit bridge` or `smart-commit report generate`
+- consume stdout as JSON
+- branch on `schemaVersion`, `status`, and `error.code`
 
-When `passHistory.enabled=true`, successful bridge runs are written to `pass-history.jsonl`.
+## Reporting
 
-Then you can generate reports:
+If `passHistory.enabled=true`, successful runs are written to local history and can be summarized later:
 
 ```bash
 smart-commit report generate --repo . --config ./smart-commit.json --period weekly
 ```
 
-AI-enhanced reporting is optional:
+Optional AI-enhanced reporting:
 
 ```bash
 smart-commit report generate --repo . --config ./smart-commit.json --period weekly --report-ai
 ```
 
-If AI generation fails, the CLI falls back to local Markdown rendering automatically.
+If AI generation fails, the CLI falls back to local Markdown automatically.
 
 ## Troubleshooting
 
 ### `connection.apiKey references missing environment variable`
 
-Your config contains something like:
+Your config contains:
 
 ```json
 "apiKey": "env:SMART_COMMIT_API_KEY"
@@ -336,7 +289,7 @@ export SMART_COMMIT_API_KEY="your-api-key"
 
 ### `--repo is required`
 
-`bridge` and `report generate` both require a repository root or a path inside a Git repository.
+`bridge` and `report generate` require a repository path or a path inside a Git repository.
 
 ### No staged diff found
 
@@ -353,40 +306,12 @@ git add -A
 smart-commit bridge --repo . --config ./smart-commit.json --dry-run
 ```
 
-## Documentation Map
-
-Start here first:
-
-- [`docs/getting-started.md`](./docs/getting-started.md)
-
-Then use these based on task:
-
-- [`docs/configuration.md`](./docs/configuration.md)
-- [`docs/integrations.md`](./docs/integrations.md)
-- [`docs/contracts.md`](./docs/contracts.md)
-- [`examples/config/smart-commit.json`](./examples/config/smart-commit.json)
-
-Release and maintenance docs:
-
-- [`docs/release-checklist.md`](./docs/release-checklist.md)
-- [`docs/publish.md`](./docs/publish.md)
-- [`docs/releases/0.1.0-draft.md`](./docs/releases/0.1.0-draft.md)
-- [`docs/roadmap.md`](./docs/roadmap.md)
-
-## Development
-
-Build:
-
-```bash
-npm run build
-```
-
-Test:
-
-```bash
-npm test
-```
-
-CI:
+## Recommended First Rollout
 
-- [`.github/workflows/ci.yml`](./.github/workflows/ci.yml)
+1. create `smart-commit.json`
+2. run `smart-commit config resolve`
+3. run `smart-commit bridge --dry-run`
+4. run `smart-commit bridge --no-commit --no-push`
+5. embed the same command into your automation flow
+6. enable pass history
+7. add reporting

package/docs/configuration.md

@@ -83,6 +83,12 @@ These are the fields most users usually need first.
 - `review.skill.path`
 - `review.skill.promptTuning`
 
+Numeric review scores are the final gating signal:
+
+- `score <= review.threshold` blocks
+- `score > review.threshold` passes
+- if a review returns `score = null`, the model decision is used
+
 ### Commit Message
 
 - `commitMessage.input`
@@ -211,7 +217,7 @@ Recommended early team setup:
     "passHistory": {
       "enabled": true,
       "dirPath": ".smart-commit-cli",
-      "maxEntries": 5000
+      "maxEntries": 3000
     },
     "output": {
       "format": "json",

package/docs/getting-started.md

@@ -133,6 +133,8 @@ This lets you verify:
 
 without creating a commit or pushing to remote.
 
+When the review returns a numeric score, the final pass or block result is determined by comparing that score with the configured threshold.
+
 ## Step 8: Enable Pass History
 
 If you want reporting later, enable pass history: