smart-commit-copilot-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows Semantic Versioning once public releases begin.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-13
+
+### Added
+
+- standalone `smart-commit CLI` repository structure and TypeScript build/test setup
+- canonical `smartCommitCli` JSON configuration schema
+- compatibility layer for legacy `smartCommit.*` config keys
+- merged config resolution across CLI args, environment variables, config files, and defaults
+- `config resolve` command for inspecting final merged config
+- `bridge` command with repository validation, staged diff handling, auto-stage behavior, review execution, commit-message generation, local commit, and optional push
+- `passHistory` persistence using `pass-history.jsonl`
+- `report generate` command with local Markdown rendering
+- optional AI-enhanced report generation with local fallback
+- machine-facing JSON schemas via `schema print`
+- integration examples for Husky, Cursor hook, and external agents
+
+### Changed
+
+- README now documents stable CLI contracts, integration examples, and automation usage patterns
+
+### Tested
+
+- focused unit and integration coverage for config, review, commit message, bridge, pass history, reporting, and CLI command dispatch

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nie Tao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,392 @@
+# smart-commit CLI
+
+Standalone CLI-first automation runtime for shell, Husky, Cursor hook, and external agent 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.
+
+## What It Does
+
+`smart-commit CLI` helps you automate four common steps around code changes:
+
+1. Inspect staged changes
+2. Generate or validate commit messages
+3. Run AI-assisted review gating
+4. Persist pass history and generate work reports
+
+The current product surface includes:
+
+- `config resolve`
+- `bridge`
+- `report generate`
+- `schema print`
+
+## Who It Is For
+
+This CLI is useful when you want `smart-commit` to run outside the editor:
+
+- shell scripts
+- Husky hooks
+- Cursor hooks
+- external agents
+- CI or local automation
+
+## Before You Start
+
+Current repository state:
+
+- 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`
+
+If you have not linked the binary yet, replace `smart-commit` with:
+
+```bash
+node out/cli.js
+```
+
+## 5-Minute Quick Start
+
+### 1. Prepare the CLI
+
+```bash
+npm install
+npm run build
+```
+
+Optional, if you want the `smart-commit` command in your shell:
+
+```bash
+npm link
+```
+
+### 2. Prepare your API key
+
+```bash
+export SMART_COMMIT_API_KEY="your-api-key"
+```
+
+### 3. Copy the example config
+
+```bash
+cp examples/config/smart-commit.json ./smart-commit.json
+```
+
+The example config already demonstrates the recommended canonical format:
+
+- `smartCommitCli`
+- `apiKey: "env:SMART_COMMIT_API_KEY"`
+- JSON output by default
+
+### 4. Validate the merged config
+
+```bash
+smart-commit config resolve --config ./smart-commit.json
+```
+
+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
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run
+```
+
+This is the recommended first real command. It checks:
+
+- 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
+
+### 6. Run review-only mode
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
+```
+
+This is the safest production onboarding mode:
+
+- review runs
+- commit message logic runs
+- no Git side effects happen
+
+## Fastest Path To Value
+
+If you only want the shortest route to practical usage, use this sequence:
+
+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`
+
+## Core Commands
+
+### `config resolve`
+
+Use this to inspect the final config after all sources are merged.
+
+```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:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run
+```
+
+- review only:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
+```
+
+- full execution:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json
+```
+
+### `report generate`
+
+Generate a Markdown report from pass history.
+
+```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.
+
+```bash
+smart-commit schema print --target bridge
+```
+
+## Output Modes
+
+Default machine-facing mode:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json
+```
+
+Human-readable mode:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --output text
+```
+
+Use JSON when:
+
+- integrating with hooks or agents
+- branching on `status` and `error.code`
+
+Use text when:
+
+- debugging manually
+- checking behavior in a terminal
+
+## How Configuration Works
+
+Config precedence from high to low:
+
+1. CLI arguments
+2. environment variables
+3. `smartCommitCli` in a JSON config file
+4. legacy `smartCommit.*` keys
+5. built-in defaults
+
+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.
+
+Reference file:
+
+- [`examples/hooks/cursor-bridge-wrapper.sh`](./examples/hooks/cursor-bridge-wrapper.sh)
+
+### External Agent
+
+Consume stdout as JSON and branch on:
+
+- `schemaVersion`
+- `status`
+- `error.code`
+
+Reference files:
+
+- [`examples/agent/bridge-agent.mjs`](./examples/agent/bridge-agent.mjs)
+- [`examples/agent/report-agent.mjs`](./examples/agent/report-agent.mjs)
+
+## Pass History And Reporting
+
+When `passHistory.enabled=true`, successful bridge runs are written to `pass-history.jsonl`.
+
+Then you can generate reports:
+
+```bash
+smart-commit report generate --repo . --config ./smart-commit.json --period weekly
+```
+
+AI-enhanced reporting is optional:
+
+```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.
+
+## Troubleshooting
+
+### `connection.apiKey references missing environment variable`
+
+Your config contains something like:
+
+```json
+"apiKey": "env:SMART_COMMIT_API_KEY"
+```
+
+but the environment variable is not set.
+
+Fix:
+
+```bash
+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.
+
+### No staged diff found
+
+Possible causes:
+
+- nothing is staged
+- working tree is clean
+- auto-stage is disabled
+
+Try:
+
+```bash
+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:
+
+- [`.github/workflows/ci.yml`](./.github/workflows/ci.yml)

package/docs/configuration.md

@@ -0,0 +1,262 @@
+# Configuration Guide
+
+This document explains how `smart-commit CLI` resolves configuration and which settings matter most in practice.
+
+## Recommended Format
+
+Use the canonical JSON format:
+
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    }
+  }
+}
+```
+
+Legacy `smartCommit.*` keys are still accepted for migration, but they are compatibility input only.
+
+## Precedence
+
+Merged from high to low:
+
+1. CLI arguments
+2. environment variables
+3. `smartCommitCli`
+4. legacy `smartCommit.*`
+5. built-in defaults
+
+Example:
+
+- config file sets `git.autoPush = true`
+- environment variable sets `SMART_COMMIT_AUTO_PUSH=false`
+- CLI passes `--auto-push`
+
+Final result:
+
+- `git.autoPush = true` from CLI
+
+## `env:VAR_NAME` References
+
+String values that begin with `env:` are resolved from the current process environment after merge and before validation.
+
+Example:
+
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "apiKey": "env:SMART_COMMIT_API_KEY"
+    }
+  }
+}
+```
+
+Required shell setup:
+
+```bash
+export SMART_COMMIT_API_KEY="your-api-key"
+```
+
+## High-Value Settings
+
+These are the fields most users usually need first.
+
+### Connection
+
+- `connection.baseUrl`
+- `connection.apiKey`
+- `connection.model`
+- `connection.requestTimeoutMs`
+- `connection.extraHeaders`
+
+### Review
+
+- `review.threshold`
+- `review.language`
+- `review.maxDiffChars`
+- `review.skill.id`
+- `review.skill.path`
+- `review.skill.promptTuning`
+
+### Commit Message
+
+- `commitMessage.input`
+- `commitMessage.language`
+- `commitMessage.autoGenerate`
+- `commitMessage.hybridGenerate`
+- `commitMessage.validation.protocol`
+- `commitMessage.validation.pattern`
+- `commitMessage.validation.extractTicketIdFromBranch`
+- `commitMessage.validation.requireTicketIdInMessage`
+- `commitMessage.skill.id`
+- `commitMessage.skill.path`
+- `commitMessage.skill.promptTuning`
+
+### Git
+
+- `git.autoStageWhenNothingStaged`
+- `git.autoCommit`
+- `git.autoPush`
+- `git.pushTimeoutMs`
+
+### Pass History
+
+- `passHistory.enabled`
+- `passHistory.dirPath`
+- `passHistory.maxEntries`
+
+### Reporting
+
+- `reporting.language`
+- `reporting.weekStartsOn`
+- `reporting.outputDirPath`
+- `reporting.prompt`
+- `reporting.ai.enabled`
+
+### Output
+
+- `output.format`
+- `output.logLevel`
+
+## Common CLI Flags
+
+Most frequently used:
+
+```bash
+--repo
+--config
+--output
+--base-url
+--api-key
+--model
+--threshold
+--review-language
+--commit-language
+--commit-message
+--no-commit
+--no-push
+--dry-run
+```
+
+Common reporting flags:
+
+```bash
+--period
+--report-language
+--report-output-dir
+--report-ai
+```
+
+## 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
+```
+
+## Minimal Practical Config
+
+If 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 starting point.
+
+## Safer Team Rollout Config
+
+Recommended early team setup:
+
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    },
+    "git": {
+      "autoStageWhenNothingStaged": true,
+      "autoCommit": false,
+      "autoPush": false
+    },
+    "passHistory": {
+      "enabled": true,
+      "dirPath": ".smart-commit-cli",
+      "maxEntries": 5000
+    },
+    "output": {
+      "format": "json",
+      "logLevel": "info"
+    }
+  }
+}
+```
+
+## Notes On Skills
+
+`review.skill.path` and `commitMessage.skill.path` let you point to custom instruction files.
+
+Use them when:
+
+- your team has custom review standards
+- your team has custom commit-message style guidance
+
+`promptTuning` is useful when you want small additive guidance without creating a separate skill file.
+
+## Notes On Output
+
+Use:
+
+- `output.format = "json"` for hooks, agents, and automation
+- `output.format = "text"` for humans in the terminal
+
+Use:
+
+- `output.logLevel = "debug"` when diagnosing behavior
+- `output.logLevel = "info"` for normal use
+- `output.logLevel = "warn"` when you only care about warnings and errors
+
+## Validation Tips
+
+Always validate the final config before integration:
+
+```bash
+smart-commit config resolve --config ./smart-commit.json
+```
+
+This is the fastest way to catch:
+
+- missing environment variables
+- invalid booleans or numbers
+- invalid protocol values
+- invalid regex patterns
+- unsupported skill ids