smart-commit-copilot-cli 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.1.11] - 2026-05-23
+
+### Changed
+
+- README now documents staged change summaries, PR/MR creation, the `bridge` step table, a full inline `smartCommitCli` config example, and expanded CLI flag and environment variable references
+- example config now includes `connection.extraHeaders`, `connection.requestTimeoutMs`, and illustrative review and commit-message `promptTuning` values aligned with the README
+- publish guidance now points to the `0.1.11` release draft during pre-publish review
+
 ## [0.1.10] - 2026-05-22
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # smart-commit CLI
 
-`smart-commit CLI` is a shell-first tool for AI-assisted commit review, commit-message generation, optional Git execution, and local reporting.
+`smart-commit CLI` is a shell-first tool for AI-assisted commit review, commit-message generation, optional Git execution, staged change summaries, PR/MR creation, and local reporting.
 
 Use it when you want one repeatable workflow that can run from:
 
@@ -19,8 +19,11 @@ It can:
 - use bundled review skills, including `c-code-review`, with diff-aware generic fallback
 - optionally create a commit
 - optionally push the current branch
-- persist successful run history
-- generate daily, yesterday, weekly, last-week, monthly, last-month, quarterly, last-quarter, or yearly Markdown work reports
+- generate staged change summaries after successful review, commit, or push flows
+- auto-create GitHub PRs or GitLab MRs after a successful push when configured
+- create or dry-run PR/MR content through standalone `pull-request create`
+- persist successful run history in pass history
+- generate local or AI-enhanced daily, yesterday, weekly, last-week, monthly, last-month, quarterly, last-quarter, or yearly Markdown work reports
 
 ## Who This Is For
 
@@ -29,35 +32,46 @@ 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
+- automate review-to-PR/MR flows from the CLI, hooks, or agents
+- generate staged-change or PR/MR-ready summaries without opening another tool
+- keep a lightweight pass history for successful automation 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.
+If you are using this for the first time, start with review-only mode and keep Git side effects disabled. Enable commit, push, staged summaries, and PR/MR creation gradually after 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]
+1. resolves config and `env:VAR_NAME` references
+2. verifies `--repo` and reads the staged diff, auto-staging only if configured
+3. generates or validates the commit message
+4. runs AI review and applies the score threshold
+5. optionally creates a local commit, pushes, writes a staged change summary, and creates a PR/MR
+6. optionally records the furthest successful stage into pass history
+
+| Step | When it runs | What it does | Output / side effect |
+| --- | --- | --- | --- |
+| Resolve config | Every `bridge` run | Merges CLI flags, environment variables, config file values, and defaults; resolves `env:...` references. | Validated runtime config with secrets redacted from output. |
+| Prepare Git input | Every `bridge` run | Verifies `--repo` is inside a Git repository and reads the staged diff. If the index is empty and `git.autoStageWhenNothingStaged=true`, it can run `git add -A`. | A staged diff snapshot for review and commit-message generation. |
+| Commit message | Every run that reaches review prep | Uses `commitMessage.input`, generates a message, or refines a draft depending on config. Validation can enforce structure, protocol, ticket IDs, and regex rules. | Final commit message or a blocked result before review. |
+| AI review | Every non-dry-run `bridge` execution | Reviews the staged diff and compares the final score with `review.threshold`. | `passed`, `blocked`, or `error` bridge output. |
+| Commit | Only when review passes and `git.autoCommit=true` | Creates a local Git commit with the final commit message. | New local commit. |
+| Push | Only when commit succeeds and `git.autoPush=true` | Pushes the current branch to its configured upstream. | Remote branch update, or a push-phase runtime error. |
+| Staged change summary | Only after a successful review-only, commit-only, or push run when `stagedChangeSummary.enabled=true` | Writes a Markdown summary for the reviewed staged change. | Markdown file under the configured summary directory. |
+| PR/MR auto-create | Only after a successful push when `pullRequest.autoCreateAfterPush=true` | Creates or detects an existing GitHub pull request or GitLab merge request. | `pullRequestCreation` details in bridge JSON output. |
+| Pass history | Only when `passHistory.enabled=true` and the configured `passHistory.writeStage` is reached | Records or upgrades the successful run to the furthest completed stage. | Local pass-history record for later reporting. |
+
+Optional follow-up commands:
+
+```bash
+smart-commit pull-request create --repo . --config ./smart-commit.json --target-branch main --dry-run
+smart-commit pull-request create --repo . --config ./smart-commit.json --target-branch main
+smart-commit report generate --repo . --config ./smart-commit.json --period weekly
 ```
 
+`smart-commit pull-request create` is an independent PR/MR command. `smart-commit report generate` summarizes existing pass-history records; it is not part of every `bridge` run.
+
 ## Prerequisites
 
 Before you run the CLI, make sure you have:
@@ -318,17 +332,113 @@ If you set `review.skill.path`, the CLI keeps the current file-based custom-skil
 
 `connection.llmResponseCorrectionRetryCount` controls how many extra repair or regeneration attempts the CLI may request when a review result or generated commit message fails protocol, JSON-shape, or language validation. The default is `3`, the supported range is `0..10`, and network, HTTP, timeout, or provider failures are not retried by this setting.
 
-### About the example config in this repo
+### Full Configuration Example
 
-This repository ships a fuller example at `examples/config/smart-commit.json`.
+This example shows the complete `smartCommitCli` config surface in one place.
 
-That example is useful for learning the whole config surface, but note that it enables:
+It is useful for learning all available config fields, 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.
 
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5",
+      "extraHeaders": {
+        "X-Client": "smart-commit-cli"
+      },
+      "requestTimeoutMs": 1000000,
+      "llmResponseCorrectionRetryCount": 3
+    },
+    "review": {
+      "threshold": 6,
+      "language": "zh-cn",
+      "maxDiffChars": 100000,
+      "skill": {
+        "id": "code-review",
+        "path": "",
+        "promptTuning": "Ignore findings that only complain about the project's required logging wrapper."
+      }
+    },
+    "commitMessage": {
+      "input": "",
+      "language": "zh-cn",
+      "maxDiffChars": 150000,
+      "structure": "subjectOnly",
+      "autoGenerate": true,
+      "hybridGenerate": false,
+      "skill": {
+        "id": "conventional",
+        "path": "",
+        "promptTuning": "Prefer the feat type for user-visible behavior changes when it still matches the staged diff."
+      },
+      "validation": {
+        "protocol": "none",
+        "pattern": "",
+        "extractTicketIdFromBranch": true,
+        "requireTicketIdInMessage": false
+      }
+    },
+    "git": {
+      "autoStageWhenNothingStaged": true,
+      "autoCommit": true,
+      "autoPush": true,
+      "pushTimeoutMs": 180000
+    },
+    "passHistory": {
+      "enabled": true,
+      "writeStage": "review_passed",
+      "dirPath": ".smart-commit-cli",
+      "maxEntries": 3000
+    },
+    "reporting": {
+      "language": "zh-cn",
+      "weekStartsOn": "monday",
+      "outputDirPath": ".smart-commit-cli/reports",
+      "maxInputChars": 200000,
+      "prompt": "",
+      "ai": {
+        "enabled": false
+      }
+    },
+    "stagedChangeSummary": {
+      "enabled": false,
+      "language": "zh-cn",
+      "maxDiffChars": 200000,
+      "outputDirPath": ".smart-commit-cli/staged-change-summaries",
+      "prompt": ""
+    },
+    "pullRequest": {
+      "autoCreateAfterPush": false,
+      "targetBranch": "",
+      "provider": "auto",
+      "apiBaseUrl": "",
+      "titlePrompt": "",
+      "descriptionPrompt": "",
+      "maxDiffChars": 200000,
+      "assignees": [],
+      "reviewers": [],
+      "labels": [],
+      "milestone": "",
+      "draft": false,
+      "removeSourceBranch": false,
+      "skipBranches": ["main", "master", "develop"],
+      "authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"
+    },
+    "output": {
+      "format": "json",
+      "logLevel": "info"
+    }
+  }
+}
+```
+
 ## Choose The Right Command
 
 Instead of memorizing every command, use this section by intent.
@@ -576,75 +686,233 @@ Canonical format:
 - `smartCommitCli` is the recommended long-term format
 - legacy `smartCommit.*` is still accepted for migration
 
-## Common CLI Flags
-
-Most practical flags for daily use:
-
-```bash
---repo
---config
---output
---base-url
---api-key
---model
---threshold
---llm-response-correction-retry-count
---review-language
---code-review-skill-id
---commit-language
---commit-message-structure
---commit-message
---pass-history-write-stage
---enable-staged-change-summary
---staged-change-summary-language
---staged-change-summary-output-dir
---staged-change-summary-prompt
---target-branch
---provider
---auth-token
---assignee
---reviewer
---label
+## CLI Flags Reference
+
+Runtime and output:
+
+```bash
+--repo <path>
+--config <path>
+--output <json|text>
+--log-level <debug|info|warn|error>
+--dry-run
+```
+
+`--dry-run` is used by `bridge` preflight and `pull-request create`; it is not a config field.
+
+Connection:
+
+```bash
+--base-url <url>
+--api-key <key>
+--model <model-id>
+--request-timeout-ms <number>
+--llm-response-correction-retry-count <0-10>
+```
+
+Review:
+
+```bash
+--threshold <number>
+--review-max-diff-chars <number>
+--review-language <zh-cn|zh-tw|en|...>
+--code-review-skill-id <skill-id>
+--code-review-skill-path <path>
+--code-review-skill-prompt-tuning <text>
+```
+
+Commit message:
+
+```bash
+--commit-message <text>
+--commit-language <zh-cn|zh-tw|en|...>
+--commit-message-max-diff-chars <number>
+--commit-message-structure <subjectOnly|subjectBody|subjectBodyFooter>
+--auto-generate-commit-message <true|false>
+--hybrid-generate-commit-message <true|false>
+--validation-protocol <none|conventional|semantic|gitmoji>
+--validation-pattern <regex>
+--extract-ticket-id-from-branch <true|false>
+--require-ticket-id <true|false>
+--commit-skill-id <skill-id>
+--commit-skill-path <path>
+--commit-skill-prompt-tuning <text>
+```
+
+Git:
+
+```bash
+--auto-stage
+--no-auto-stage
+--auto-commit
 --no-commit
+--auto-push
 --no-push
---dry-run
+--push-timeout-ms <number>
+```
+
+Pass history:
+
+```bash
+--enable-pass-history <true|false>
+--pass-history-write-stage <review_passed|commit_completed|commit_push_completed>
+--pass-history-dir <path>
+--pass-history-max-entries <number>
 ```
 
-Common reporting flags:
+Reporting:
 
 ```bash
---period
---report-language
---report-output-dir
+--period <daily|yesterday|weekly|last-week|monthly|last-month|quarterly|last-quarter|yearly>
+--report-language <zh-cn|zh-tw|en|...>
+--report-week-starts-on <monday|sunday>
+--report-output-dir <path>
+--report-max-input-chars <number>
+--report-prompt <text>
 --report-ai
+--no-report-ai
 ```
 
-## Common Environment Variables
+`--period` belongs to `report generate`; it is not a global config override for `bridge`.
 
-Most practical ones:
+Staged change summary:
+
+```bash
+--enable-staged-change-summary <true|false>
+--staged-change-summary-language <zh-cn|zh-tw|en|...>
+--staged-change-summary-max-diff-chars <number>
+--staged-change-summary-output-dir <path>
+--staged-change-summary-prompt <text>
+```
+
+Pull request / merge request:
+
+```bash
+--auto-create-pull-request-after-push <true|false>
+--target-branch <branch>
+--pull-request-target-branch <branch>
+--provider <auto|github|gitlab>
+--pull-request-provider <auto|github|gitlab>
+--api-base-url <url>
+--pull-request-api-base-url <url>
+--auth-token <token>
+--pull-request-auth-token <token>
+--pull-request-title-prompt <text>
+--pull-request-description-prompt <text>
+--pull-request-max-diff-chars <number>
+--assignee <user>
+--pull-request-assignee <user>
+--reviewer <user-or-team>
+--pull-request-reviewer <user-or-team>
+--label <label>
+--pull-request-label <label>
+--milestone <milestone>
+--pull-request-milestone <milestone>
+--draft <true|false>
+--pull-request-draft <true|false>
+--remove-source-branch <true|false>
+--pull-request-remove-source-branch <true|false>
+--skip-branch <branch>
+--pull-request-skip-branch <branch>
+```
+
+Repeat `--assignee`, `--reviewer`, `--label`, or `--skip-branch` to pass multiple values.
+
+## Environment Variables Reference
+
+Boolean environment variables accept `true`, `false`, `1`, or `0`. Pull request array variables use comma-separated values. Secrets such as API keys and PR/MR auth tokens are redacted from config output and error text.
+
+Connection and output:
 
 ```bash
-SMART_COMMIT_API_KEY
 SMART_COMMIT_BASE_URL
+SMART_COMMIT_API_KEY
 SMART_COMMIT_MODEL
-SMART_COMMIT_THRESHOLD
+SMART_COMMIT_REQUEST_TIMEOUT_MS
 SMART_COMMIT_LLM_RESPONSE_CORRECTION_RETRY_COUNT
+SMART_COMMIT_OUTPUT_FORMAT
+SMART_COMMIT_LOG_LEVEL
+```
+
+Review:
+
+```bash
+SMART_COMMIT_THRESHOLD
 SMART_COMMIT_REVIEW_LANGUAGE
+SMART_COMMIT_REVIEW_MAX_DIFF_CHARS
 SMART_COMMIT_CODE_REVIEW_SKILL_ID
+SMART_COMMIT_CODE_REVIEW_SKILL_PATH
+SMART_COMMIT_CODE_REVIEW_SKILL_PROMPT_TUNING
+```
+
+Commit message:
+
+```bash
 SMART_COMMIT_COMMIT_LANGUAGE
 SMART_COMMIT_COMMIT_MESSAGE_STRUCTURE
+SMART_COMMIT_COMMIT_MESSAGE_MAX_DIFF_CHARS
+SMART_COMMIT_AUTO_GENERATE_COMMIT_MESSAGE
+SMART_COMMIT_HYBRID_GENERATE_COMMIT_MESSAGE
+SMART_COMMIT_VALIDATION_PROTOCOL
+SMART_COMMIT_VALIDATION_PATTERN
+SMART_COMMIT_EXTRACT_TICKET_ID_FROM_BRANCH
+SMART_COMMIT_REQUIRE_TICKET_ID
+SMART_COMMIT_COMMIT_SKILL_ID
+SMART_COMMIT_COMMIT_SKILL_PATH
+SMART_COMMIT_COMMIT_SKILL_PROMPT_TUNING
+```
+
+Git and pass history:
+
+```bash
+SMART_COMMIT_AUTO_STAGE
 SMART_COMMIT_AUTO_COMMIT
 SMART_COMMIT_AUTO_PUSH
+SMART_COMMIT_PUSH_TIMEOUT_MS
+SMART_COMMIT_ENABLE_PASS_HISTORY
 SMART_COMMIT_PASS_HISTORY_WRITE_STAGE
+SMART_COMMIT_PASS_HISTORY_DIR
+SMART_COMMIT_PASS_HISTORY_MAX_ENTRIES
+```
+
+Reporting:
+
+```bash
 SMART_COMMIT_REPORT_LANGUAGE
+SMART_COMMIT_REPORT_WEEK_STARTS_ON
 SMART_COMMIT_REPORT_OUTPUT_DIR
+SMART_COMMIT_REPORT_MAX_INPUT_CHARS
+SMART_COMMIT_REPORT_PROMPT
+SMART_COMMIT_REPORT_USE_AI
+```
+
+Staged change summary:
+
+```bash
 SMART_COMMIT_ENABLE_STAGED_CHANGE_SUMMARY
 SMART_COMMIT_STAGED_CHANGE_SUMMARY_LANGUAGE
+SMART_COMMIT_STAGED_CHANGE_SUMMARY_MAX_DIFF_CHARS
 SMART_COMMIT_STAGED_CHANGE_SUMMARY_OUTPUT_DIR
 SMART_COMMIT_STAGED_CHANGE_SUMMARY_PROMPT
+```
+
+Pull request / merge request:
+
+```bash
 SMART_COMMIT_AUTO_CREATE_PULL_REQUEST_AFTER_PUSH
 SMART_COMMIT_PULL_REQUEST_TARGET_BRANCH
 SMART_COMMIT_PULL_REQUEST_PROVIDER
+SMART_COMMIT_PULL_REQUEST_API_BASE_URL
+SMART_COMMIT_PULL_REQUEST_TITLE_PROMPT
+SMART_COMMIT_PULL_REQUEST_DESCRIPTION_PROMPT
+SMART_COMMIT_PULL_REQUEST_MAX_DIFF_CHARS
+SMART_COMMIT_PULL_REQUEST_ASSIGNEES
+SMART_COMMIT_PULL_REQUEST_REVIEWERS
+SMART_COMMIT_PULL_REQUEST_LABELS
+SMART_COMMIT_PULL_REQUEST_MILESTONE
+SMART_COMMIT_PULL_REQUEST_DRAFT
+SMART_COMMIT_PULL_REQUEST_REMOVE_SOURCE_BRANCH
+SMART_COMMIT_PULL_REQUEST_SKIP_BRANCHES
 SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN
 ```
 

package/docs/publish.md

@@ -21,7 +21,7 @@ Current package name:
 3. Run `npm run pack:dry-run`
 4. Review [`CHANGELOG.md`](../CHANGELOG.md)
 5. Review [`docs/release-checklist.md`](./release-checklist.md)
-6. Review the matching release draft in [`docs/releases/0.1.10-draft.md`](./releases/0.1.10-draft.md)
+6. Review the matching release draft in [`docs/releases/0.1.11-draft.md`](./releases/0.1.11-draft.md)
 
 ## Recommended Release Order
 

package/docs/releases/0.1.11-draft.md

@@ -0,0 +1,52 @@
+# `smart-commit-copilot-cli` 0.1.11 Draft Release Notes
+
+## Summary
+
+`smart-commit-copilot-cli` 0.1.11 is a documentation alignment release for the standalone CLI.
+
+This release focuses on making the README and example config reflect the full current command surface, including staged change summaries, PR/MR workflows, and the expanded configuration and flag reference.
+
+## Highlights
+
+- README now covers staged change summaries, PR/MR auto-create, standalone `pull-request create`, and optional follow-up commands
+- `bridge` workflow is documented with a step table instead of a high-level diagram only
+- full inline `smartCommitCli` config example plus grouped CLI flag and environment variable references
+- example config aligned with the README, including `extraHeaders`, `requestTimeoutMs`, and sample `promptTuning` values
+
+## Why This Release Matters
+
+This version improves onboarding and day-to-day reference quality without changing runtime behavior:
+
+- new users can see the full `bridge` side-effect path in one place
+- operators configuring PR/MR or staged summaries have matching README, example config, and flag/env docs
+- maintainers have a release draft aligned with the `0.1.11` publish target
+
+## Notable Documentation Updates
+
+### README
+
+- introduction and capability list now include staged change summaries and PR/MR creation
+- typical `bridge` run documented as a step table with triggers and side effects
+- full configuration example embedded for learning the complete `smartCommitCli` surface
+- CLI flags and environment variables reorganized into topical reference sections
+
+### Example config
+
+- `examples/config/smart-commit.json` now mirrors the README full example for connection headers, timeouts, and prompt tuning samples
+
+### Publish guide
+
+- the pre-publish checklist now points at the `0.1.11` draft
+
+## Suggested Upgrade Path
+
+1. update to `0.1.11`
+2. run `npm test`
+3. run `npm run smoke:test`
+4. run `npm run pack:dry-run`
+5. publish only after all three checks pass
+
+## Known Follow-Up Areas
+
+- optional README link validation from published tarball surfaces after npm release
+- consider a dedicated configuration reference page if the inline README example grows further

package/examples/config/smart-commit.json

@@ -4,6 +4,10 @@
       "baseUrl": "https://api.openai.com/v1",
       "apiKey": "env:SMART_COMMIT_API_KEY",
       "model": "gpt-5",
+      "extraHeaders": {
+        "X-Client": "smart-commit-cli"
+      },
+      "requestTimeoutMs": 1000000,
       "llmResponseCorrectionRetryCount": 3
     },
     "review": {
@@ -13,7 +17,7 @@
       "skill": {
         "id": "code-review",
         "path": "",
-        "promptTuning": ""
+        "promptTuning": "Ignore findings that only complain about the project's required logging wrapper."
       }
     },
     "commitMessage": {
@@ -26,7 +30,7 @@
       "skill": {
         "id": "conventional",
         "path": "",
-        "promptTuning": ""
+        "promptTuning": "Prefer the feat type for user-visible behavior changes when it still matches the staged diff."
       },
       "validation": {
         "protocol": "none",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-commit-copilot-cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "description": "CLI for AI-assisted commit review, commit message generation, Git workflow automation, and work reports.",
   "license": "MIT",