smart-commit-copilot-cli 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [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
+
 ## [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": 5000
+    },
+    "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:
-
-- `smartCommitCli`
-- `apiKey: "env:SMART_COMMIT_API_KEY"`
-- JSON output by default
+### 4. Run a safe preflight
 
-### 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,63 @@ 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:
-
-- review runs
-- commit message logic runs
-- no Git side effects happen
+It will:
 
-## Fastest Path To Value
+- run review
+- run commit-message logic
+- return structured output
+- avoid Git side effects
 
-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 +197,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 +226,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 +287,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 +304,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/publish.md

@@ -1,6 +1,6 @@
 # Publish Guide
 
-This guide covers the practical steps for turning the current repository state into a first public release.
+This guide covers the practical steps for publishing the next npm release of this package.
 
 ## Current Assumption
 
@@ -26,10 +26,12 @@ Current package name:
 
 For the current repository state, the safest order is:
 
-1. create and push a Git tag for `v0.1.0`
-2. create a GitHub Release using the release draft text
+1. update the package version and changelog
+2. run the release verification commands
+3. create and push a Git tag for the target version
+4. create a GitHub Release using the matching release draft text
 3. log in to npm
-4. publish `smart-commit-copilot-cli@0.1.0`
+4. publish the matching `smart-commit-copilot-cli` version
 
 This gives you:
 
@@ -65,20 +67,30 @@ npm run pack:dry-run
 
 This shows the exact files that would be included in the published tarball, based on the `files` field in [`package.json`](../package.json).
 
+## Release Verification Commands
+
+Run:
+
+```bash
+npm test
+npm run smoke:test
+npm run pack:dry-run
+```
+
 ## Exact GitHub Release Steps
 
 Create and push the release tag:
 
 ```bash
-git tag v0.1.0
-git push smart-commit-cli v0.1.0
+git tag vX.Y.Z
+git push smart-commit-cli vX.Y.Z
 ```
 
 Then create a GitHub Release:
 
-- tag: `v0.1.0`
-- title: `v0.1.0`
-- description: use the content from [`docs/releases/0.1.0-draft.md`](./releases/0.1.0-draft.md)
+- tag: `vX.Y.Z`
+- title: `vX.Y.Z`
+- description: use the content from the matching draft in [`docs/releases`](./releases)
 
 ## Exact npm Publish Steps
 
@@ -102,7 +114,7 @@ npm publish --access public
 
 Package that will be published:
 
-- `smart-commit-copilot-cli@0.1.0`
+- `smart-commit-copilot-cli@X.Y.Z`
 
 ## Suggested Final Verification After Publish
 
@@ -115,21 +127,5 @@ npm view smart-commit-copilot-cli version
 Then test a fresh install path:
 
 ```bash
-npx smart-commit-copilot-cli --help
+npx smart-commit-copilot-cli@X.Y.Z --help
 ```
-
-## Suggested First Release Shape
-
-Recommended first public scope:
-
-- `config resolve`
-- `bridge`
-- `report generate`
-- `schema print`
-- example configs and integration templates
-
-Recommended non-goals for the first release:
-
-- broad plugin ecosystem promises
-- advanced multi-repository orchestration
-- unstable breaking changes to machine-facing JSON contracts

package/docs/release-checklist.md

@@ -13,16 +13,18 @@ Use this checklist before the first public release and for later release candida
 ## Build
 
 - Run `npm test`
+- Run `npm run smoke:test`
 - Run `smart-commit schema print --target bridge` and spot-check the output
 - Run `smart-commit config resolve` against the example config
 - Confirm GitHub Actions CI passes on the target branch
 
 ## Runtime
 
-- Dry-run `bridge` in a temporary Git repository
-- Run `bridge` with mock review and commit-message providers
-- Run `report generate` from a repository with pass-history records
-- Run `report generate --report-ai` with a mock provider and confirm fallback behavior still works
+- Confirm `docs/verification.md` still matches the actual command coverage
+- If a manual spot-check is still needed, dry-run `bridge` in a temporary Git repository
+- If a manual spot-check is still needed, run `bridge` with mock review and commit-message providers
+- If a manual spot-check is still needed, run `report generate` from a repository with pass-history records
+- If a manual spot-check is still needed, run `report generate --report-ai` with a mock provider and confirm fallback behavior still works
 
 ## Package
 

package/docs/releases/0.1.1-draft.md

@@ -0,0 +1,55 @@
+# `smart-commit-copilot-cli` 0.1.1 Draft Release Notes
+
+## Summary
+
+`smart-commit-copilot-cli` 0.1.1 is a stability and release-quality update for the standalone CLI.
+
+This release focuses on making the core command paths easier to verify before publish and safer to evolve during later iterations.
+
+## Highlights
+
+- repeatable `npm run smoke:test` regression command
+- command-level verification coverage for the main onboarding commands
+- AI report fallback now covered in the smoke regression flow
+- CI now runs both unit tests and smoke verification
+- clearer verification and release-check guidance for follow-up versions
+
+## Why This Release Matters
+
+This version improves confidence in the CLI as it continues to evolve:
+
+- command explanations can now be backed by a repeatable regression path
+- release validation no longer depends only on manual spot-checks
+- the most important user-facing commands have a stronger end-to-end safety net
+
+## Included Verification Coverage
+
+The smoke regression flow now covers:
+
+1. `smart-commit config resolve --config ./smart-commit.json --output text`
+2. `smart-commit config resolve --config /absolute/path/to/smart-commit.json`
+3. `smart-commit bridge --repo . --config ./smart-commit.json --dry-run`
+4. `smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push`
+5. `smart-commit report generate --repo . --config ./smart-commit.json --period weekly`
+6. `smart-commit report generate --repo . --config ./smart-commit.json --period weekly --report-ai`
+7. `smart-commit report generate --repo . --config ./smart-commit.json --period weekly --report-ai` with AI fallback
+8. `smart-commit bridge --repo . --config ./smart-commit.json`
+
+## Stability Notes
+
+- `smartCommitCli` remains the canonical config format
+- legacy `smartCommit.*` remains a compatibility input layer
+- command-level regression coverage is stronger, but no breaking contract change is introduced in this release
+
+## Suggested Upgrade Path
+
+1. update to `0.1.1`
+2. run `npm test`
+3. run `npm run smoke:test`
+4. publish only after both checks pass
+
+## Known Follow-Up Areas
+
+- upstream/push-path smoke coverage if remote validation needs to be exercised regularly
+- broader release automation once the versioning flow is stable
+- continued refinement of user onboarding and reporting depth

package/docs/verification.md

@@ -0,0 +1,48 @@
+# Verification
+
+Use this document when you want a fast regression check for the core CLI commands.
+
+## Command
+
+Run:
+
+```bash
+npm run smoke:test
+```
+
+This command:
+
+- builds the CLI
+- creates temporary Git repositories
+- uses mock providers instead of real external AI calls
+- verifies the core command paths discussed during onboarding
+
+## Covered Commands
+
+The smoke test checks these command shapes:
+
+- `smart-commit config resolve --config ./smart-commit.json --output text`
+- `smart-commit config resolve --config /absolute/path/to/smart-commit.json`
+- `smart-commit bridge --repo . --config ./smart-commit.json --dry-run`
+- `smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push`
+- `smart-commit report generate --repo . --config ./smart-commit.json --period weekly`
+- `smart-commit report generate --repo . --config ./smart-commit.json --period weekly --report-ai`
+- `smart-commit report generate --repo . --config ./smart-commit.json --period weekly --report-ai` with AI failure fallback
+- `smart-commit bridge --repo . --config ./smart-commit.json`
+
+## What It Verifies
+
+- relative and absolute `--config` paths both work
+- `config resolve` returns the expected merged config shape
+- `bridge --dry-run` completes preflight without creating a commit
+- `bridge --no-commit --no-push` runs review without changing `HEAD`
+- `report generate` writes a local Markdown report from pass history
+- `report generate --report-ai` uses the AI report path when enabled
+- `report generate --report-ai` falls back to local Markdown if AI generation fails
+- default `bridge` creates a local commit when `autoCommit=true` and `autoPush=false`
+
+## Notes
+
+- The smoke test does not push to a remote
+- The smoke test does not require a real API key value
+- Temporary repositories are created under the system temp directory

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "smart-commit-copilot-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
-  "description": "Standalone CLI-first automation runtime for smart-commit workflows across shell, Husky, Cursor hook, and external agents.",
+  "description": "CLI for AI-assisted commit review, commit message generation, Git workflow automation, and work reports.",
   "license": "MIT",
   "type": "commonjs",
   "engines": {
@@ -19,9 +19,14 @@
     "smart-commit",
     "cli",
     "git",
-    "husky",
-    "cursor",
-    "hooks",
+    "commit",
+    "commit-message",
+    "code-review",
+    "ai",
+    "copilot",
+    "git-hooks",
+    "hook",
+    "reporting",
     "automation",
     "agent"
   ],
@@ -33,6 +38,7 @@
     "build": "npm run clean && tsc -p ./tsconfig.build.json",
     "test": "npm run clean && tsc -p ./tsconfig.json && node --test --test-reporter=spec out/test/*.test.js",
     "check": "npm test",
+    "smoke:test": "npm run build && node ./scripts/smoke-test.mjs",
     "pack:dry-run": "npm pack --dry-run",
     "prepack": "npm run build",
     "prepublishOnly": "npm test"