smart-commit-copilot-cli 0.1.0

package/docs/contracts.md

@@ -0,0 +1,134 @@
+# Contracts
+
+This document summarizes the stable machine-facing contracts exposed by `smart-commit CLI`.
+
+If you are trying the CLI for the first time, start with [`getting-started.md`](./getting-started.md). This document is mainly for machine integrations and contract consumers.
+
+For formal JSON Schema output, use:
+
+```bash
+smart-commit schema print --target bridge
+smart-commit schema print --target report-generate
+```
+
+## Shared Rules
+
+- All machine-facing JSON payloads include `schemaVersion`
+- Parse stdout as JSON
+- Treat stderr as supplemental human-readable context
+- Prefer `status` and `error.code` over string matching in `summary`
+
+## `config resolve`
+
+Command:
+
+```bash
+smart-commit config resolve --config ./smart-commit.json
+```
+
+Stable top-level fields:
+
+- `schemaVersion`
+- `status`
+- `command`
+- `runtime`
+- `config`
+
+Use it to validate merged config before wiring `bridge` or `report generate` into automation.
+
+## `bridge`
+
+Command:
+
+```bash
+smart-commit bridge --repo /path/to/repo --config ./smart-commit.json
+```
+
+Stable top-level fields:
+
+- `schemaVersion`
+- `status`
+- `command`
+- `repositoryPath`
+- `phase`
+- `didCommit`
+- `didPush`
+- `commitSha`
+- `passHistory`
+- `reviewDecision`
+- `score`
+- `summary`
+- `error`
+
+Status semantics:
+
+- `ready`
+  Returned for dry-run preflight success.
+- `passed`
+  Returned when execution succeeds through review, or through commit/push depending on config.
+- `blocked`
+  Returned for expected business outcomes such as review blocking or staged-diff gating.
+- `error`
+  Returned for configuration or runtime failures.
+
+Important `error.code` values:
+
+- `CONFIG_ERROR`
+- `RUNTIME_ERROR`
+- `NO_CHANGES`
+- `NO_STAGED_DIFF`
+- `WOULD_AUTO_STAGE`
+- `COMMIT_MESSAGE_REQUIRED`
+- `COMMIT_MESSAGE_INVALID`
+- `REVIEW_BLOCKED`
+
+Recommended automation behavior:
+
+- continue on `ready` or `passed`
+- stop on `blocked` and surface `error.code` plus `summary`
+- fail on `error`
+
+## `report generate`
+
+Command:
+
+```bash
+smart-commit report generate --repo /path/to/repo --period weekly
+```
+
+Stable top-level fields:
+
+- `schemaVersion`
+- `status`
+- `command`
+- `repositoryPath`
+- `periodType`
+- `passHistoryFilePath`
+- `outputFilePath`
+- `renderMode`
+- `reportProvider`
+- `warnings`
+- `facts`
+- `summary`
+- `error`
+
+`renderMode` semantics:
+
+- `local`
+  Local deterministic Markdown generation was used.
+- `ai`
+  AI-enhanced report generation succeeded.
+- `ai-fallback-local`
+  AI generation failed and the CLI fell back to local Markdown.
+
+Recommended automation behavior:
+
+- archive or upload `outputFilePath` on success
+- inspect `warnings` when `renderMode` is `ai-fallback-local`
+- fail on `status: "error"`
+
+## Versioning Guidance
+
+- treat `schemaVersion` as the primary compatibility gate
+- use JSON Schema for strict validation when integrating with agents or services
+- expect additive fields to be the preferred evolution path

package/docs/getting-started.md

@@ -0,0 +1,177 @@
+# Getting Started
+
+This guide is the fastest path from a fresh checkout to a successful `bridge` run.
+
+## Goal
+
+By the end of this guide, you will:
+
+1. build the CLI
+2. prepare a config file
+3. validate the merged config
+4. run a safe bridge preflight
+5. run review-only mode
+
+## Prerequisites
+
+- Node.js 20+
+- Git repository with staged changes
+- an OpenAI-compatible API endpoint and API key
+
+## Step 1: Install And Build
+
+From the repository root:
+
+```bash
+npm install
+npm run build
+```
+
+Optional, if you want the `smart-commit` binary available globally in your shell:
+
+```bash
+npm link
+```
+
+If you do not run `npm link`, replace `smart-commit` in the examples below with:
+
+```bash
+node out/cli.js
+```
+
+## Step 2: Export Your API Key
+
+```bash
+export SMART_COMMIT_API_KEY="your-api-key"
+```
+
+The example config uses `env:SMART_COMMIT_API_KEY`, so this environment variable must exist before validation.
+
+## Step 3: Create A Config File
+
+Start from the example:
+
+```bash
+cp examples/config/smart-commit.json ./smart-commit.json
+```
+
+You can keep the example mostly as-is for first use. The important part is:
+
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    }
+  }
+}
+```
+
+## Step 4: Validate The Final Config
+
+```bash
+smart-commit config resolve --config ./smart-commit.json
+```
+
+This command is important because it shows:
+
+- merged values after precedence rules
+- secret redaction
+- validation errors before execution
+
+For a more readable terminal view:
+
+```bash
+smart-commit config resolve --config ./smart-commit.json --output text
+```
+
+## Step 5: Prepare Some Staged Changes
+
+Inside your target repo:
+
+```bash
+git add -A
+git status --short
+```
+
+`bridge` works on staged changes, so this step matters.
+
+## Step 6: Run A Safe Preflight
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run
+```
+
+Expected result:
+
+- `status: "ready"` if everything is prepared
+- `status: "blocked"` if changes are missing or staging rules prevent execution
+- `status: "error"` if config or runtime setup is invalid
+
+Human-readable version:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --dry-run --output text
+```
+
+## Step 7: Run Review-Only Mode
+
+This is the safest way to onboard the CLI into a real workflow:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
+```
+
+This lets you verify:
+
+- review path
+- commit-message generation path
+- threshold behavior
+- structured JSON output
+
+without creating a commit or pushing to remote.
+
+## Step 8: Enable Pass History
+
+If you want reporting later, enable pass history:
+
+```bash
+smart-commit bridge \
+  --repo . \
+  --config ./smart-commit.json \
+  --enable-pass-history=true \
+  --no-commit \
+  --no-push
+```
+
+This writes local JSONL history for successful bridge runs.
+
+## Step 9: Generate A Report
+
+```bash
+smart-commit report generate --repo . --config ./smart-commit.json --period weekly
+```
+
+Useful follow-up checks:
+
+- confirm `outputFilePath`
+- confirm `renderMode`
+- inspect generated Markdown
+
+## Recommended First Production Rollout
+
+1. validate config with `config resolve`
+2. run `bridge --dry-run`
+3. run `bridge --no-commit --no-push`
+4. wire the same review-only command into Husky or Cursor hook
+5. enable pass history
+6. add reporting
+7. only then enable automatic commit or push if you really want the CLI to own those side effects
+
+## Where To Go Next
+
+- configuration details: [`configuration.md`](./configuration.md)
+- integration patterns: [`integrations.md`](./integrations.md)
+- machine-facing contracts: [`contracts.md`](./contracts.md)

package/docs/integrations.md

@@ -0,0 +1,85 @@
+# Integrations
+
+This document shows recommended integration patterns for `smart-commit CLI` in shell-first automation.
+
+If you have not run the CLI manually yet, start with [`getting-started.md`](./getting-started.md) first. Integration is much easier after you have already verified `config resolve` and `bridge --dry-run`.
+
+## Principles
+
+- Prefer `bridge` as the enforcement entrypoint for hooks and agents
+- Prefer `report generate` as the reporting entrypoint for scheduled or post-task automation
+- Parse JSON output instead of scraping stderr
+- Gate logic on `schemaVersion`, `status`, and `error.code`
+- Keep hook integrations in `--no-commit --no-push` mode unless you explicitly want the CLI to own Git side effects
+
+## Husky
+
+Recommended use:
+
+- Use `pre-commit` to review staged changes before Git creates a commit
+- Keep Husky in review-only mode with `--no-commit --no-push`
+- Let Git itself continue to own the actual commit lifecycle
+
+Suggested layout:
+
+- Wrapper script: [`examples/hooks/smart-commit-bridge.sh`](../examples/hooks/smart-commit-bridge.sh)
+- Husky example: [`examples/hooks/husky-pre-commit.sh`](../examples/hooks/husky-pre-commit.sh)
+
+Example:
+
+```sh
+cp examples/hooks/husky-pre-commit.sh .husky/pre-commit
+chmod +x .husky/pre-commit
+```
+
+## Cursor Hook
+
+Cursor hook registration details can vary by version, so the most stable approach is:
+
+- register a shell script as the hook target
+- let the shell script invoke `smart-commit bridge`
+- consume JSON output if your hook host supports it
+
+Suggested wrapper:
+
+- [`examples/hooks/cursor-bridge-wrapper.sh`](../examples/hooks/cursor-bridge-wrapper.sh)
+
+Recommended behavior:
+
+- run before commit or before custom repo actions
+- use `--no-commit --no-push`
+- inspect `status`
+  `ready` and `passed` mean continue
+  `blocked` means stop and surface the review reason
+  `error` means stop and surface the runtime or config problem
+
+## External Agent
+
+For custom agents, CI bots, or local automation runners:
+
+- spawn `smart-commit bridge` or `smart-commit report generate`
+- parse stdout as JSON
+- check `schemaVersion`
+- branch behavior on `status`
+
+Example consumers:
+
+- [`examples/agent/bridge-agent.mjs`](../examples/agent/bridge-agent.mjs)
+- [`examples/agent/report-agent.mjs`](../examples/agent/report-agent.mjs)
+
+## Exit Codes
+
+- `0`: success
+- `2`: blocked business decision, such as review blocked or auto-stage dry-run warning
+- `3`: config error
+- `4`: runtime error
+
+JSON payloads should remain the primary contract. Exit codes are best used as a coarse first filter.
+
+## Recommended Rollout
+
+1. Start with `smart-commit config resolve` in CI or local scripts to verify merged config.
+2. Wire `bridge` into Husky or Cursor hook in `--no-commit --no-push` mode.
+3. Enable `passHistory`.
+4. Add `report generate` in scheduled automation or agent workflows.
+5. Optionally enable AI reporting with local fallback after the local flow is already stable.

package/docs/publish.md

@@ -0,0 +1,135 @@
+# Publish Guide
+
+This guide covers the practical steps for turning the current repository state into a first public release.
+
+## Current Assumption
+
+The project is now configured to allow npm publication. Before you publish, you still need to confirm:
+
+- the final package name
+- the canonical Git remote
+- whether the package should be published to npm, GitHub Packages, or stay private
+
+Current package name:
+
+- `smart-commit-copilot-cli`
+
+## Pre-Publish Checklist
+
+1. Run `npm test`
+2. Run `npm run pack:dry-run`
+3. Review [`CHANGELOG.md`](../CHANGELOG.md)
+4. Review [`docs/release-checklist.md`](./release-checklist.md)
+5. Review the release draft in [`docs/releases/0.1.0-draft.md`](./releases/0.1.0-draft.md)
+
+## Recommended Release Order
+
+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
+3. log in to npm
+4. publish `smart-commit-copilot-cli@0.1.0`
+
+This gives you:
+
+- a fixed release checkpoint on GitHub
+- a stable version label for discussion and changelog references
+- a clean follow-up path for npm publication
+
+## Metadata To Finalize Before Public Publish
+
+Update [`package.json`](../package.json) with:
+
+- `repository`
+- `homepage`
+- `bugs`
+
+If the package will be public on npm:
+
+1. confirm the package name is available
+2. run `npm publish --access public`
+
+If the package will remain private for now:
+
+- set `"private": true` again before any publish attempt
+- continue distributing via source checkout, internal package registry, or tarball
+
+## Dry-Run Packaging
+
+Use:
+
+```bash
+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).
+
+## Exact GitHub Release Steps
+
+Create and push the release tag:
+
+```bash
+git tag v0.1.0
+git push smart-commit-cli v0.1.0
+```
+
+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)
+
+## Exact npm Publish Steps
+
+Log in first:
+
+```bash
+npm login
+```
+
+Optional verification:
+
+```bash
+npm whoami
+```
+
+Publish:
+
+```bash
+npm publish --access public
+```
+
+Package that will be published:
+
+- `smart-commit-copilot-cli@0.1.0`
+
+## Suggested Final Verification After Publish
+
+After npm publish succeeds, verify:
+
+```bash
+npm view smart-commit-copilot-cli version
+```
+
+Then test a fresh install path:
+
+```bash
+npx smart-commit-copilot-cli --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

@@ -0,0 +1,39 @@
+# Release Checklist
+
+Use this checklist before the first public release and for later release candidates.
+
+## Product
+
+- Confirm README reflects the current command surface and examples
+- Confirm `docs/integrations.md` still matches the recommended Husky, Cursor hook, and agent patterns
+- Confirm `docs/contracts.md` matches the actual JSON payloads and schema output
+- Confirm `CHANGELOG.md` is updated for the release
+- Confirm the release draft in `docs/releases/0.1.0-draft.md` matches the intended release scope
+
+## Build
+
+- Run `npm 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
+
+## Package
+
+- Confirm `package.json` version is correct
+- Confirm `package.json` `files` list still includes all runtime assets that should ship
+- Confirm `node` engine requirement still matches the codebase
+- Run `npm run pack:dry-run` and inspect the tarball file list
+
+## Optional Publish Readiness
+
+- Add repository metadata once the canonical remote URL is finalized
+- Add homepage and bugs metadata if the project will be published externally
+- Add CI workflow badges and installation instructions if distribution is planned
+- Revisit whether the package should continue publishing from this repository state or move to a scoped package later

package/docs/releases/0.1.0-draft.md

@@ -0,0 +1,52 @@
+# `smart-commit-copilot-cli` 0.1.0 Draft Release Notes
+
+## Summary
+
+`smart-commit-copilot-cli` 0.1.0 is the first standalone CLI-first release of the Smart Commit automation runtime.
+
+This release establishes the product as an independent repository and focuses on shell, Husky, Cursor hook, and agent integration rather than VS Code extension settings as the primary runtime model.
+
+## Highlights
+
+- standalone CLI-first repository and runtime
+- npm package name: `smart-commit-copilot-cli`
+- canonical `smartCommitCli` configuration format
+- compatibility input layer for legacy `smartCommit.*`
+- `bridge` command for review, commit-message generation, optional commit, and optional push
+- `passHistory` persistence for successful runs
+- `report generate` for local Markdown work reports
+- optional AI-enhanced reporting with deterministic fallback
+- machine-facing JSON contracts with `schemaVersion`
+- `schema print` for formal JSON Schema output
+- ready-to-copy examples for Husky, Cursor hook, and external agents
+
+## Why This Release Matters
+
+This version is the foundation for embedding Smart Commit behavior into normal engineering workflows:
+
+- shell scripts
+- Git hooks
+- Cursor hooks
+- external agents
+- future scheduled automation
+
+## Stability Notes
+
+- `smartCommitCli` is the canonical config format going forward
+- `smartCommit.*` remains supported as a compatibility input layer
+- machine-facing JSON outputs are versioned with `schemaVersion`
+- additive changes are preferred over breaking contract changes during the `0.1.x` phase
+
+## Suggested Upgrade Path
+
+1. start with `smart-commit config resolve`
+2. wire `smart-commit bridge` into hook or agent workflows in `--no-commit --no-push` mode
+3. enable `passHistory`
+4. add `report generate`
+5. optionally enable AI reporting after the local workflow is stable
+
+## Known Follow-Up Areas
+
+- release metadata finalization in `package.json`
+- repository metadata once a public homepage or repository URL is ready
+- continued improvements to integration ergonomics and reporting depth

package/docs/roadmap.md

@@ -0,0 +1,94 @@
+# Roadmap
+
+This document defines the intended stability boundary for the `0.x` phase of `smart-commit CLI`.
+
+## Current Position
+
+The project already has a usable standalone automation loop:
+
+- config resolution
+- bridge execution
+- pass-history persistence
+- report generation
+- AI-enhanced reporting with local fallback
+- machine-facing JSON schemas
+
+The next goal is to move from "feature-complete prototype" to "stable automation product".
+
+## Version Strategy
+
+## `0.1.x`
+
+Focus:
+
+- keep command surface stable enough for real integrations
+- continue tightening docs, examples, and CI
+- prefer additive changes over behavior churn
+
+Expected stability:
+
+- `schemaVersion: "1.0.0"` machine contracts should remain stable unless there is a strong reason to break them
+- `smartCommitCli` remains the canonical config namespace
+- legacy `smartCommit.*` remains compatibility-only
+
+Allowed changes:
+
+- additive output fields
+- new optional flags
+- more examples and docs
+- richer reporting content
+- more integration helpers
+
+Avoid during `0.1.x`:
+
+- renaming canonical config groups
+- changing precedence rules
+- changing `bridge` and `report generate` exit-code semantics
+
+## `0.2.x`
+
+Focus:
+
+- broader workflow automation
+- stronger hook ergonomics
+- richer agent-facing integrations
+
+Candidate scope:
+
+- more explicit machine-facing schemas for sub-objects
+- reusable shell installers or bootstrap commands
+- additional reporting modes
+- optional chunked review or larger-diff orchestration
+
+## `0.3.x`
+
+Focus:
+
+- release hardening and external distribution readiness
+
+Candidate scope:
+
+- package publish readiness
+- repository metadata finalization
+- CI release workflows
+- migration guides
+- long-term deprecation policy for legacy config input
+
+## Toward `1.0`
+
+The project is ready to target `1.0` when all of the following are true:
+
+- machine-facing contracts are treated as stable product APIs
+- `bridge` and `report generate` are used in real automation without frequent breaking adjustments
+- documentation covers the common adoption paths clearly
+- legacy compatibility behavior has an explicit support window
+- release and test automation are routine rather than manual
+
+## Product Rules
+
+When making future changes, prefer these rules:
+
+1. Preserve JSON contract compatibility when possible.
+2. Prefer additive evolution over renaming or removing fields.
+3. Keep local-first behavior available even when AI features are enabled.
+4. Treat Husky, Cursor hook, and agent integrations as first-class use cases rather than examples only.