smart-commit-copilot-cli 0.1.3 → 0.1.5

package/README.md

@@ -1,47 +1,274 @@
 # smart-commit CLI
 
-`smart-commit CLI` is a shell-first tool for automated commit review, commit-message generation, and report workflows.
+`smart-commit CLI` is a shell-first tool for AI-assisted commit review, commit-message generation, optional Git execution, and local reporting.
 
-Use it when you want the same workflow to run from a terminal, script, hook, or agent.
+Use it when you want one repeatable workflow that can run from:
+
+- your terminal
+- shell scripts
+- Git hooks
+- IDE hooks
+- external agents
 
 It can:
 
 - inspect staged changes
+- run AI review and gate on the result
 - generate or validate commit messages
-- run AI-assisted review gating
-- optionally commit and push
-- persist pass history
-- generate work reports
+- optionally create a commit
+- optionally push the current branch
+- persist successful run history
+- generate Markdown work reports
+
+## Who This Is For
+
+This tool is a good fit if you want to:
+
+- review staged changes before committing
+- standardize commit messages
+- run the same workflow locally and in automation
+- keep a lightweight history of successful review and commit runs
+- generate periodic reports from local pass history
+
+If you are using this for the first time, start with review-only mode and keep Git side effects disabled until you trust the workflow.
+
+## What Happens In A Typical Run
+
+At a high level, `smart-commit bridge` does this:
+
+1. loads config from CLI flags, environment variables, config file, and defaults
+2. resolves `env:VAR_NAME` references such as `env:SMART_COMMIT_API_KEY`
+3. verifies the target `--repo` path is inside a Git repository
+4. reads the staged diff, or auto-stages if your config allows it
+5. runs AI review
+6. generates or validates the commit message
+7. optionally commits and pushes
+8. optionally records the successful run into pass history
+
+```mermaid
+flowchart TD
+  InstallCli[InstallCLI] --> PrepareConfig[PrepareConfig]
+  PrepareConfig --> ResolveConfig[RunConfigResolve]
+  ResolveConfig --> StageChanges[StageChanges]
+  StageChanges --> DryRun[RunBridgeDryRun]
+  DryRun --> ReviewOnly[RunReviewOnly]
+  ReviewOnly --> FullRun[OptionalFullRun]
+  FullRun --> ReportGenerate[OptionalReportGenerate]
+```
+
+## Prerequisites
+
+Before you run the CLI, make sure you have:
+
+- `Node.js >= 20`
+- `git` available in your shell
+- a Git repository to operate on
+- staged changes for `bridge`, unless auto-stage is enabled
+- an OpenAI-compatible API endpoint, model, and API key for AI-backed commands
+
+Important command requirements:
+
+- `smart-commit bridge` requires `--repo`
+- `smart-commit report generate` requires `--repo`
+- `smart-commit config resolve` does not require `--repo`
+- `smart-commit config resolve` can validate config structure without a complete connection block
+- `smart-commit bridge` requires a valid connection configuration
+
+## Install
 
-Install package:
+Install globally:
 
 ```bash
 npm install -g smart-commit-copilot-cli
 ```
 
-Run command:
+Then verify:
 
 ```bash
 smart-commit --help
 ```
 
-Or use `npx` directly:
+Or use `npx` without a global install:
 
 ```bash
 npx smart-commit-copilot-cli --help
 ```
 
-## Quick Start
+If you are working from a repository checkout of this project:
 
-### 1. Prepare your API key
+```bash
+npm install
+npm run build
+node out/cli.js --help
+```
+
+## 5-Minute Quick Start
+
+This section is the safest first-use path for a real repository.
+
+### 1. Export your API key
 
 ```bash
 export SMART_COMMIT_API_KEY="your-api-key"
 ```
 
-### 2. Create a config file
+Why this matters:
+
+- the config examples below use `env:SMART_COMMIT_API_KEY`
+- environment references are resolved before validation
+- if the variable is missing, `bridge` cannot start
+
+### 2. Create a minimal config file
+
+Create `smart-commit.json` in your target repository:
+
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    },
+    "git": {
+      "autoCommit": false,
+      "autoPush": false
+    }
+  }
+}
+```
+
+The three connection fields are the most important:
+
+- `connection.baseUrl`: your OpenAI-compatible API base URL
+- `connection.apiKey`: your API key, usually referenced through `env:...`
+- `connection.model`: the model name sent to that endpoint
+
+This minimal config is intentionally safe:
+
+- `autoCommit=false` prevents local commits
+- `autoPush=false` prevents remote pushes
+
+### 3. Validate the merged config first
+
+```bash
+smart-commit config resolve --config ./smart-commit.json
+```
+
+Why start here:
+
+- it shows the final merged config after CLI args, env vars, file config, and defaults
+- it redacts secrets in output
+- it catches validation problems before the CLI touches Git or the network
+
+For a more readable terminal view:
+
+```bash
+smart-commit config resolve --config ./smart-commit.json --output text
+```
+
+What you should expect:
+
+- a valid merged config
+- no missing environment variable errors
+- no invalid booleans, regex patterns, or protocol settings
+
+### 4. Stage a change
+
+`bridge` works on staged content.
+
+```bash
+git add -A
+git status --short
+```
+
+If nothing is staged and `autoStageWhenNothingStaged` is disabled, `bridge` will block.
+
+### 5. Run a safe preflight
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run
+```
+
+Why this step matters:
+
+- it verifies the repo path
+- it checks whether the repo is inside Git
+- it checks whether staged diff input exists
+- it validates that commit-message logic can be resolved
+- it confirms the bridge input is ready
+
+What you should expect:
+
+- `status: "ready"` when the bridge can run
+- `status: "blocked"` when the repo is valid but required input is missing
+- `status: "error"` when config or runtime setup is invalid
+
+For a terminal-friendly version:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run --output text
+```
+
+### 6. Run review-only mode
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
+```
+
+This is the recommended first real run because it:
+
+- runs review
+- runs commit-message logic
+- returns structured output
+- avoids Git side effects
+
+What you should expect:
+
+- `status: "passed"` if the review passes
+- `status: "blocked"` if the review blocks or required input is missing
+- `status: "error"` if execution fails
+
+When the review returns a numeric score, the final pass or block result is determined by comparing that score with `review.threshold`.
+
+### Shortest safe path
+
+If you want the shortest sequence to first success:
+
+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`
+
+## Configuration Examples
+
+### Minimal practical config
+
+Use this when you want the smallest useful starting point:
+
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    },
+    "git": {
+      "autoCommit": false,
+      "autoPush": false
+    }
+  }
+}
+```
+
+This gives you a safe review-first setup.
+
+### Safer team rollout config
 
-Create `smart-commit.json` in your repository:
+Use this when you want a more realistic team default without enabling automatic commit or push:
 
 ```json
 {
@@ -55,17 +282,6 @@ Create `smart-commit.json` in your repository:
       "threshold": 6,
       "language": "zh"
     },
-    "commitMessage": {
-      "language": "zh",
-      "autoGenerate": true,
-      "hybridGenerate": false,
-      "validation": {
-        "protocol": "none",
-        "pattern": "",
-        "extractTicketIdFromBranch": true,
-        "requireTicketIdInMessage": false
-      }
-    },
     "git": {
       "autoStageWhenNothingStaged": true,
       "autoCommit": false,
@@ -76,15 +292,6 @@ Create `smart-commit.json` in your repository:
       "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"
@@ -93,73 +300,142 @@ Create `smart-commit.json` in your repository:
 }
 ```
 
-### 3. Validate the config
+This is usually the best starting point for teams because it:
+
+- keeps the workflow review-first
+- allows local history for reporting
+- stays safe for hooks and automation
+
+### About the example config in this repo
+
+This repository ships a fuller example at `examples/config/smart-commit.json`.
+
+That example is useful for learning the whole config surface, but note that it enables:
+
+- `git.autoCommit = true`
+- `git.autoPush = true`
+
+For first use, do not copy those values blindly. Start with `false` for both and enable them later only if you want the CLI to own those Git side effects.
+
+## Choose The Right Command
+
+Instead of memorizing every command, use this section by intent.
+
+### I want to verify my config
 
 ```bash
 smart-commit config resolve --config ./smart-commit.json
 ```
 
-This is the recommended first command because it shows:
+Use this when you want to:
+
+- inspect the merged config
+- confirm env var resolution
+- catch validation issues early
+
+Good to know:
 
-- merged config after CLI args, env vars, file config, and defaults
-- secret redaction
-- validation errors before real execution
+- `--config` is recommended, not required
+- if you omit `--config`, the CLI uses CLI flags, env vars, and built-in defaults
+- `config resolve` is the safest first command
 
-For human-readable output:
+### I want to see whether `bridge` is ready
 
 ```bash
-smart-commit config resolve --config ./smart-commit.json --output text
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run
 ```
 
-### 4. Run a safe preflight
+Use this when you want to:
 
-Stage some changes first:
+- validate repo and staged diff readiness
+- confirm commit-message logic can resolve
+- avoid a real AI review or Git side effects
+
+### I want review only, with no commit or push
 
 ```bash
-git add -A
+smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
 ```
 
-Then run:
+Use this when you want to:
+
+- review staged changes
+- generate or validate a commit message
+- integrate with hooks safely
+- onboard the CLI without touching Git history
+
+### I want a full bridge run
 
 ```bash
-smart-commit bridge --repo . --config ./smart-commit.json --dry-run
+smart-commit bridge --repo . --config ./smart-commit.json
 ```
 
-This checks:
+Use this only when your config intentionally allows the desired side effects.
 
-- repository path is valid
-- current directory is inside Git
-- staged diff exists, or whether auto-stage would happen
-- commit message can be resolved
-- bridge input is ready for execution
+Depending on config, the CLI may:
 
-### 5. Run review-only mode
+- review only
+- review and create a local commit
+- review, commit, and push
 
-This is the safest way to start using the tool in a real workflow:
+### I want to generate a report
 
 ```bash
-smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
+smart-commit report generate --repo . --config ./smart-commit.json --period weekly
 ```
 
-It will:
+Supported `--period` values:
 
-- run review
-- run commit-message logic
-- return structured output
-- avoid Git side effects
+- `daily`
+- `weekly`
+- `monthly`
+- `quarterly`
+- `yearly`
 
-When the review returns a numeric score, the final pass or block result is determined by comparing that score with `review.threshold`.
+If you omit `--period`, it defaults to `weekly`.
 
-If you only want the shortest path:
+If `passHistory.enabled=true`, successful bridge runs are written locally and later summarized into a Markdown report.
 
-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`
+Optional AI-enhanced reporting:
+
+```bash
+smart-commit report generate --repo . --config ./smart-commit.json --period weekly --report-ai
+```
+
+If AI report generation fails, the CLI falls back to local Markdown generation automatically.
+
+### I want machine-readable schemas
+
+```bash
+smart-commit schema print --target bridge
+```
+
+Supported schema targets:
+
+- `config-file`
+- `config-resolve`
+- `bridge`
+- `report-generate`
+
+Examples:
+
+```bash
+smart-commit schema print --target config-file
+smart-commit schema print --target config-resolve
+smart-commit schema print --target bridge
+smart-commit schema print --target report-generate
+```
 
-## Core Commands
+## Core Commands Reference
+
+### Help and version
+
+```bash
+smart-commit --help
+smart-commit help
+smart-commit --version
+smart-commit version
+```
 
 ### Resolve config
 
@@ -191,7 +467,7 @@ smart-commit bridge --repo . --config ./smart-commit.json
 smart-commit report generate --repo . --config ./smart-commit.json --period weekly
 ```
 
-### Print machine-readable schema
+### Print a schema
 
 ```bash
 smart-commit schema print --target bridge
@@ -199,13 +475,13 @@ smart-commit schema print --target bridge
 
 ## Output Modes
 
-Default mode is machine-facing JSON:
+Default output is machine-facing JSON:
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json
 ```
 
-For a terminal-friendly summary:
+For a human-friendly terminal summary:
 
 ```bash
 smart-commit bridge --repo . --config ./smart-commit.json --output text
@@ -213,8 +489,38 @@ smart-commit bridge --repo . --config ./smart-commit.json --output text
 
 Recommended usage:
 
-- use JSON for hooks, agents, and automation
-- use text for manual debugging
+- use `json` for hooks, agents, and scripts
+- use `text` for local debugging
+
+For machine integrations, the usual pattern is:
+
+- call `smart-commit bridge` or `smart-commit report generate`
+- consume stdout as JSON
+- branch on `schemaVersion`, `status`, and `error.code`
+
+## Exit Codes
+
+These are especially useful in shell scripts, hooks, and automation.
+
+### `bridge`
+
+- `0`: success
+- `2`: blocked
+- `3`: config error
+- `4`: runtime error
+
+Typical interpretation:
+
+- `0` means the run completed successfully
+- `2` means the change set or review result blocked progress
+- `3` means your config or CLI input is invalid
+- `4` means runtime execution failed
+
+### `report generate`
+
+- `0`: success
+- `3`: config error
+- `4`: runtime error
 
 ## Configuration Rules
 
@@ -233,29 +539,57 @@ Special rule:
 Canonical format:
 
 - `smartCommitCli` is the recommended long-term format
-- legacy `smartCommit.*` is supported for migration
+- legacy `smartCommit.*` is still accepted for migration
 
-## Automation-Friendly Capabilities
+## Common CLI Flags
 
-This package is designed to work well in shell-driven automation scenarios.
+Most practical flags for daily use:
 
-Typical examples include:
+```bash
+--repo
+--config
+--output
+--base-url
+--api-key
+--model
+--threshold
+--review-language
+--commit-language
+--commit-message
+--no-commit
+--no-push
+--dry-run
+```
 
-- Git hook style workflows
-- editor or IDE hook workflows
-- external agent workflows
-- local automation scripts
-- CI or scheduled reporting flows
+Common reporting flags:
 
-For machine integrations, the recommended pattern is:
+```bash
+--period
+--report-language
+--report-output-dir
+--report-ai
+```
 
-- call `smart-commit bridge` or `smart-commit report generate`
-- consume stdout as JSON
-- branch on `schemaVersion`, `status`, and `error.code`
+## Common Environment Variables
+
+Most practical ones:
+
+```bash
+SMART_COMMIT_API_KEY
+SMART_COMMIT_BASE_URL
+SMART_COMMIT_MODEL
+SMART_COMMIT_THRESHOLD
+SMART_COMMIT_REVIEW_LANGUAGE
+SMART_COMMIT_COMMIT_LANGUAGE
+SMART_COMMIT_AUTO_COMMIT
+SMART_COMMIT_AUTO_PUSH
+SMART_COMMIT_REPORT_LANGUAGE
+SMART_COMMIT_REPORT_OUTPUT_DIR
+```
 
 ## Reporting
 
-If `passHistory.enabled=true`, successful runs are written to local history and can be summarized later:
+If `passHistory.enabled=true`, successful bridge runs are written to local history and can be summarized later:
 
 ```bash
 smart-commit report generate --repo . --config ./smart-commit.json --period weekly
@@ -263,38 +597,27 @@ smart-commit report generate --repo . --config ./smart-commit.json --period week
 
 Successful bridge runs are categorized in pass history as:
 
-- `review_passed`
-  Review passed, but automatic commit is disabled.
-- `commit_completed`
-  A local commit was created, but automatic push is disabled.
-- `commit_push_completed`
-  A local commit was created and the current branch was pushed.
+- `review_passed`: review passed, but automatic commit is disabled
+- `commit_completed`: a local commit was created, but automatic push is disabled
+- `commit_push_completed`: a local commit was created and the current branch was pushed
 
 Report summaries use these records to show:
 
 - total successful review passes
 - local commit completions
-- commit + push completions
+- commit and push completions
 
-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 automatically.
-
-## Troubleshooting
+## Common First-Time Mistakes
 
 ### `connection.apiKey references missing environment variable`
 
-Your config contains:
+Your config contains something like:
 
 ```json
 "apiKey": "env:SMART_COMMIT_API_KEY"
 ```
 
-but the environment variable is not set.
+but the environment variable is not set in the current shell.
 
 Fix:
 
@@ -304,7 +627,13 @@ export SMART_COMMIT_API_KEY="your-api-key"
 
 ### `--repo is required`
 
-`bridge` and `report generate` require a repository path or a path inside a Git repository.
+`bridge` and `report generate` require a repository path, or a path inside a Git repository.
+
+Typical fix:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run
+```
 
 ### No staged diff found
 
@@ -321,12 +650,59 @@ git add -A
 smart-commit bridge --repo . --config ./smart-commit.json --dry-run
 ```
 
+### I expected the config file to be auto-loaded
+
+If you omit `--config`, the CLI does not magically discover every possible file name. It uses CLI flags, environment variables, and built-in defaults.
+
+If you want a specific config file to participate in resolution, pass it explicitly:
+
+```bash
+smart-commit config resolve --config ./smart-commit.json
+```
+
+### I accidentally enabled auto-commit or auto-push too early
+
+If your config or env vars enable `git.autoCommit` or `git.autoPush`, `bridge` may create side effects during a full run.
+
+For first rollout, keep these disabled:
+
+```json
+{
+  "smartCommitCli": {
+    "git": {
+      "autoCommit": false,
+      "autoPush": false
+    }
+  }
+}
+```
+
+Then use:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
+```
+
 ## Recommended First Rollout
 
-1. create `smart-commit.json`
+For a new team or repository, use this order:
+
+1. create a minimal or safer team config
 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
+5. embed the same review-only command into your hook or automation flow
 6. enable pass history
 7. add reporting
+8. only then consider automatic commit or push
+
+This sequence keeps the first rollout safe while still letting you validate the entire workflow.
+
+## Where To Go Deeper
+
+For deeper detail after the first successful run:
+
+- getting started from source: [`docs/getting-started.md`](https://unpkg.com/smart-commit-copilot-cli/docs/getting-started.md)
+- configuration details: [`docs/configuration.md`](https://unpkg.com/smart-commit-copilot-cli/docs/configuration.md)
+- integration patterns: [`docs/integrations.md`](https://unpkg.com/smart-commit-copilot-cli/docs/integrations.md)
+- machine-facing contracts: [`docs/contracts.md`](https://unpkg.com/smart-commit-copilot-cli/docs/contracts.md)