@traisetech/autopilot 2.3.0 → 2.5.0

package/docs/CONFIGURATION.md

@@ -1,103 +1,103 @@
-# Configuration Reference - Autopilot CLI
-
-**Built by Praise Masunga (PraiseTechzw)**
-
-This document reflects the current `.autopilotrc.json` options.
-
----
-
-## File Locations
-
-- Config: `.autopilotrc.json` (repo root)
-- Ignore: `.autopilotignore` (repo root)
-
----
-
-## Full Example
-
-```json
-{
-  "debounceSeconds": 20,
-  "minSecondsBetweenCommits": 180,
-  "autoPush": true,
-  "blockBranches": ["main", "master"],
-  "requireChecks": false,
-  "checks": ["npm test"],
-  "commitMessageMode": "smart",
-  "teamMode": false,
-  "maxFileSizeMB": 50,
-  "preventSecrets": true
-}
-```
-
----
-
-## Settings
-
-### `debounceSeconds`
-- **Type:** number
-- **Default:** 20
-- **Description:** Wait time after the last file change before checking git status.
-
-### `minSecondsBetweenCommits`
-- **Type:** number
-- **Default:** 180
-- **Description:** Minimum time between commits (anti-spam).
-
-### `autoPush`
-- **Type:** boolean
-- **Default:** true
-- **Description:** Push to `origin/<branch>` after commit.
-
-### `blockedBranches`
-- **Type:** string[]
-- **Default:** `["main", "master"]`
-- **Description:** Branches where auto-commit is disabled.
-
-### `requireChecks`
-- **Type:** boolean
-- **Default:** false
-- **Description:** Run checks before commit. If any fail, commit is skipped.
-
-### `checks`
-- **Type:** string[]
-- **Default:** `[]`
-- **Description:** Shell commands executed sequentially when `requireChecks` is true.
-
-### `commitMessageMode`
-- **Type:** `"smart" | "simple" | "ai"`
-- **Default:** `"smart"`
-- **Description:** 
-  - smart: file/diff-based conventional messages
-  - simple: `chore: update changes`
-  - ai: uses configured AI provider (Gemini or Grok)
-
-### `teamMode`
-- **Type:** boolean
-- **Default:** `false`
-- **Description:** Enables pull-before-push and stricter conflict handling. Recommended for collaborative environments.
-
-### `preCommitChecks.fileSize`
-- **Type:** boolean
-- **Default:** `true`
-- **Description:** Prevent commits containing files larger than 50MB.
-
-### `preCommitChecks.secrets`
-- **Type:** boolean
-- **Default:** `true`
-- **Description:** Secret scan for common key/token patterns before committing.
-
----
-
-## Ignore File (.autopilotignore)
-
-Gitignore-style patterns. Example:
-
-```
-node_modules/
-dist/
-.env
-*.log
-```
-
-Autopilot also always ignores `.git`, `.autopilot.pid`, and `autopilot.log`.
+# Configuration Reference - Autopilot CLI
+
+**Built by Praise Masunga (PraiseTechzw)**
+
+This document reflects the current `.autopilotrc.json` options.
+
+---
+
+## File Locations
+
+- Config: `.autopilotrc.json` (repo root)
+- Ignore: `.autopilotignore` (repo root)
+
+---
+
+## Full Example
+
+```json
+{
+  "debounceSeconds": 20,
+  "minSecondsBetweenCommits": 180,
+  "autoPush": true,
+  "blockBranches": ["main", "master"],
+  "requireChecks": false,
+  "checks": ["npm test"],
+  "commitMessageMode": "smart",
+  "teamMode": false,
+  "maxFileSizeMB": 50,
+  "preventSecrets": true
+}
+```
+
+---
+
+## Settings
+
+### `debounceSeconds`
+- **Type:** number
+- **Default:** 20
+- **Description:** Wait time after the last file change before checking git status.
+
+### `minSecondsBetweenCommits`
+- **Type:** number
+- **Default:** 180
+- **Description:** Minimum time between commits (anti-spam).
+
+### `autoPush`
+- **Type:** boolean
+- **Default:** true
+- **Description:** Push to `origin/<branch>` after commit.
+
+### `blockedBranches`
+- **Type:** string[]
+- **Default:** `["main", "master"]`
+- **Description:** Branches where auto-commit is disabled.
+
+### `requireChecks`
+- **Type:** boolean
+- **Default:** false
+- **Description:** Run checks before commit. If any fail, commit is skipped.
+
+### `checks`
+- **Type:** string[]
+- **Default:** `[]`
+- **Description:** Shell commands executed sequentially when `requireChecks` is true.
+
+### `commitMessageMode`
+- **Type:** `"smart" | "simple" | "ai"`
+- **Default:** `"smart"`
+- **Description:** 
+  - smart: file/diff-based conventional messages
+  - simple: `chore: update changes`
+  - ai: uses configured AI provider (Gemini or Grok)
+
+### `teamMode`
+- **Type:** boolean
+- **Default:** `false`
+- **Description:** Enables pull-before-push and stricter conflict handling. Recommended for collaborative environments.
+
+### `preCommitChecks.fileSize`
+- **Type:** boolean
+- **Default:** `true`
+- **Description:** Prevent commits containing files larger than 50MB.
+
+### `preCommitChecks.secrets`
+- **Type:** boolean
+- **Default:** `true`
+- **Description:** Secret scan for common key/token patterns before committing.
+
+---
+
+## Ignore File (.autopilotignore)
+
+Gitignore-style patterns. Example:
+
+```
+node_modules/
+dist/
+.env
+*.log
+```
+
+Autopilot also always ignores `.git`, `.autopilot.pid`, and `autopilot.log`.

package/docs/DESIGN_PRINCIPLES.md

@@ -1,114 +1,114 @@
-# Autopilot CLI – System / Design Prompt
-
-This document serves as the design + behavior contract for Autopilot CLI. It guides internal logic, AI integrations, future contributors, and decision-making.
-
-## Core Principles
-
-- **Autopilot CLI is a local-first, developer-trust-first Git automation tool.**
-- Its primary goal is to reduce Git friction without reducing developer control.
-- The tool must always prioritize **safety, predictability, and transparency** over convenience.
-- Autopilot automates repetitive Git tasks, not developer intent.
-- Autopilot must never surprise the user.
-- Autopilot must fail loudly, pause safely, and never guess during ambiguity.
-
-## Hard Guarantees (Non-Negotiable)
-
-Autopilot will **never**:
-
-- force-push
-- commit ignored files
-- commit `.env`, secrets, or sensitive files
-- operate during merge or rebase states
-- send source code externally without explicit opt-in
-
-All automation is **reversible** via `autopilot undo`.
-
-## Failure Behavior
-
-- If a **push fails** → pause watcher, notify user.
-- If **authentication expires** → pause watcher.
-- If **merge conflicts** are detected → stop automation.
-- If **network is unavailable** → queue safely or pause.
-- If **repository state is ambiguous** → do nothing.
-
-## Commit Intelligence
-
-- Commit messages must:
-  - be deterministic and explainable
-  - reflect file-level changes
-  - follow conventional commit standards when possible
-- **AI (Gemini / Grok)** is an assistant, never an authority.
-- AI output must be reviewable, overridable, and optional.
-
-## Privacy & Local-First Design
-
-**Privacy Guarantees:**
-- Your source code **never** leaves your machine
-- No code diffs are transmitted externally
-- No file contents are sent to remote servers
-- AI commit message generation happens with metadata only (file paths, line counts, not actual code)
-
-**Local-First Architecture:**
-- Works 100% offline (except for git push operations)
-- No authentication to external services required
-- All data stored locally in your project
-- Configuration is local and version-controllable
-
-## Leaderboard & Metrics
-
-- Metrics are derived **only** from local Git activity created by Autopilot.
-- **No raw code, diffs, or file contents are ever transmitted.**
-- Leaderboard data is:
-  - opt-in (disabled by default)
-  - anonymized or pseudonymous
-  - explainable (users know exactly what is counted)
-  - aggregate only (commit counts, focus time, streak days)
-
-**What gets synced (if opted in):**
-- ✅ Commit counts
-- ✅ Focus time duration
-- ✅ Streak days
-- ✅ Anonymized username/identifier
-
-**What never gets synced:**
-- ❌ Source code
-- ❌ File names or paths
-- ❌ Commit messages
-- ❌ Repository names
-- ❌ File diffs or changes
-
-## User Experience Philosophy
-
-**When in Doubt: Pause, Explain, Wait**
-
-- Ambiguous situations should trigger clear, actionable error messages
-- Users should always understand what Autopilot is doing and why
-- Status messages should be informative without being verbose
-- Configuration should have sensible defaults but be fully customizable
-
-**Trust Through Transparency:**
-- Every action Autopilot takes should be logged
-- Users should be able to audit what happened and when
-- The system should explain its decisions in plain language
-- Documentation should be honest about limitations
-
-## Development Guidelines
-
-**For Contributors:**
-- Any feature must pass the "trust test" - would you trust this with your production code?
-- Prefer explicit over implicit behavior
-- Add clear error messages for every failure case
-- Document why, not just what
-- Test edge cases extensively, especially around git state
-
-**For AI Integration:**
-- AI should enhance, not replace, developer judgment
-- All AI suggestions must be reviewable before commit
-- Provide escape hatches for AI-generated content
-- Log AI usage for transparency
-- Allow disabling AI features entirely
-
----
-
-*Any feature (including Grok or leaderboards) must pass this test: Does it maintain developer trust, safety, and control?*
-
+# Autopilot CLI – System / Design Prompt
+
+This document serves as the design + behavior contract for Autopilot CLI. It guides internal logic, AI integrations, future contributors, and decision-making.
+
+## Core Principles
+
+- **Autopilot CLI is a local-first, developer-trust-first Git automation tool.**
+- Its primary goal is to reduce Git friction without reducing developer control.
+- The tool must always prioritize **safety, predictability, and transparency** over convenience.
+- Autopilot automates repetitive Git tasks, not developer intent.
+- Autopilot must never surprise the user.
+- Autopilot must fail loudly, pause safely, and never guess during ambiguity.
+
+## Hard Guarantees (Non-Negotiable)
+
+Autopilot will **never**:
+
+- force-push
+- commit ignored files
+- commit `.env`, secrets, or sensitive files
+- operate during merge or rebase states
+- send source code externally without explicit opt-in
+
+All automation is **reversible** via `autopilot undo`.
+
+## Failure Behavior
+
+- If a **push fails** → pause watcher, notify user.
+- If **authentication expires** → pause watcher.
+- If **merge conflicts** are detected → stop automation.
+- If **network is unavailable** → queue safely or pause.
+- If **repository state is ambiguous** → do nothing.
+
+## Commit Intelligence
+
+- Commit messages must:
+  - be deterministic and explainable
+  - reflect file-level changes
+  - follow conventional commit standards when possible
+- **AI (Gemini / Grok)** is an assistant, never an authority.
+- AI output must be reviewable, overridable, and optional.
+
+## Privacy & Local-First Design
+
+**Privacy Guarantees:**
+- Your source code **never** leaves your machine
+- No code diffs are transmitted externally
+- No file contents are sent to remote servers
+- AI commit message generation happens with metadata only (file paths, line counts, not actual code)
+
+**Local-First Architecture:**
+- Works 100% offline (except for git push operations)
+- No authentication to external services required
+- All data stored locally in your project
+- Configuration is local and version-controllable
+
+## Leaderboard & Metrics
+
+- Metrics are derived **only** from local Git activity created by Autopilot.
+- **No raw code, diffs, or file contents are ever transmitted.**
+- Leaderboard data is:
+  - opt-in (disabled by default)
+  - anonymized or pseudonymous
+  - explainable (users know exactly what is counted)
+  - aggregate only (commit counts, focus time, streak days)
+
+**What gets synced (if opted in):**
+- ✅ Commit counts
+- ✅ Focus time duration
+- ✅ Streak days
+- ✅ Anonymized username/identifier
+
+**What never gets synced:**
+- ❌ Source code
+- ❌ File names or paths
+- ❌ Commit messages
+- ❌ Repository names
+- ❌ File diffs or changes
+
+## User Experience Philosophy
+
+**When in Doubt: Pause, Explain, Wait**
+
+- Ambiguous situations should trigger clear, actionable error messages
+- Users should always understand what Autopilot is doing and why
+- Status messages should be informative without being verbose
+- Configuration should have sensible defaults but be fully customizable
+
+**Trust Through Transparency:**
+- Every action Autopilot takes should be logged
+- Users should be able to audit what happened and when
+- The system should explain its decisions in plain language
+- Documentation should be honest about limitations
+
+## Development Guidelines
+
+**For Contributors:**
+- Any feature must pass the "trust test" - would you trust this with your production code?
+- Prefer explicit over implicit behavior
+- Add clear error messages for every failure case
+- Document why, not just what
+- Test edge cases extensively, especially around git state
+
+**For AI Integration:**
+- AI should enhance, not replace, developer judgment
+- All AI suggestions must be reviewable before commit
+- Provide escape hatches for AI-generated content
+- Log AI usage for transparency
+- Allow disabling AI features entirely
+
+---
+
+*Any feature (including Grok or leaderboards) must pass this test: Does it maintain developer trust, safety, and control?*
+

package/docs/TEAM-MODE.md

@@ -1,51 +1,51 @@
-# 👥 Team Mode
-
-Autopilot V2 introduces **Team Mode**, designed to make automated Git workflows safe and efficient for collaborative environments.
-
-## How it Works
-
-When `teamMode` is enabled in your configuration, Autopilot changes its behavior to prioritize synchronization and conflict prevention.
-
-### Key Behaviors
-
-1. **Pull-Before-Push**:
-   Before attempting to push any local commits, Autopilot automatically runs `git pull --rebase`. This ensures your local branch is up-to-date with the remote, minimizing merge conflicts.
-
-2. **Conflict Abortion**:
-   If a pull operation detects conflicts, Autopilot **immediately aborts** the automation loop. It will not attempt to commit or push until you manually resolve the conflicts.
-   - **Status**: The watcher enters a "Stopped" or error state.
-   - **Notification**: You will see an error message in the logs/dashboard.
-
-3. **Remote Status Checks**:
-   Autopilot frequently checks the remote repository status to detect if your local branch has diverged.
-
-## Enabling Team Mode
-
-To enable Team Mode, run:
-
-```bash
-autopilot init
-```
-And select "Yes" when asked "Enable team mode? (pull before push)".
-
-Or manually edit your `.autopilotrc.json`:
-
-```json
-{
-  "teamMode": true
-}
-```
-
-## Best Practices for Teams
-
-- **Short Commit Intervals**: Set `commitInterval` to a lower value (e.g., 5-10 minutes) to reduce the chance of large conflicts.
-- **Feature Branches**: Continue to use feature branches (`feat/my-feature`). Autopilot works best on feature branches, leaving `main` or `develop` protected.
-- **Dashboard Monitoring**: Use `autopilot dashboard` to keep an eye on the automation status and pending changes.
-
-## Troubleshooting
-
-If Autopilot stops due to a conflict:
-1. Run `git status` to see the conflict.
-2. Resolve the conflicts manually.
-3. Run `git add .` and `git rebase --continue`.
-4. Restart Autopilot with `autopilot start`.
+# 👥 Team Mode
+
+Autopilot V2 introduces **Team Mode**, designed to make automated Git workflows safe and efficient for collaborative environments.
+
+## How it Works
+
+When `teamMode` is enabled in your configuration, Autopilot changes its behavior to prioritize synchronization and conflict prevention.
+
+### Key Behaviors
+
+1. **Pull-Before-Push**:
+   Before attempting to push any local commits, Autopilot automatically runs `git pull --rebase`. This ensures your local branch is up-to-date with the remote, minimizing merge conflicts.
+
+2. **Conflict Abortion**:
+   If a pull operation detects conflicts, Autopilot **immediately aborts** the automation loop. It will not attempt to commit or push until you manually resolve the conflicts.
+   - **Status**: The watcher enters a "Stopped" or error state.
+   - **Notification**: You will see an error message in the logs/dashboard.
+
+3. **Remote Status Checks**:
+   Autopilot frequently checks the remote repository status to detect if your local branch has diverged.
+
+## Enabling Team Mode
+
+To enable Team Mode, run:
+
+```bash
+autopilot init
+```
+And select "Yes" when asked "Enable team mode? (pull before push)".
+
+Or manually edit your `.autopilotrc.json`:
+
+```json
+{
+  "teamMode": true
+}
+```
+
+## Best Practices for Teams
+
+- **Short Commit Intervals**: Set `commitInterval` to a lower value (e.g., 5-10 minutes) to reduce the chance of large conflicts.
+- **Feature Branches**: Continue to use feature branches (`feat/my-feature`). Autopilot works best on feature branches, leaving `main` or `develop` protected.
+- **Dashboard Monitoring**: Use `autopilot dashboard` to keep an eye on the automation status and pending changes.
+
+## Troubleshooting
+
+If Autopilot stops due to a conflict:
+1. Run `git status` to see the conflict.
+2. Resolve the conflicts manually.
+3. Run `git add .` and `git rebase --continue`.
+4. Restart Autopilot with `autopilot start`.

package/docs/TROUBLESHOOTING.md

@@ -1,21 +1,21 @@
-# TROUBLESHOOTING
-
-## Common Issues
-
-### Watcher Loop / High CPU Usage (Windows)
-If Autopilot seems to be constantly triggering or consuming high CPU on Windows, it is likely due to "noisy" files that change frequently but should be ignored.
-
-**Common Culprits:**
-- `.vscode/time-analytics.json`: Some VS Code extensions write to this file constantly.
-- `autopilot.log`: If the watcher logs to a file that it is also watching, it creates a feedback loop.
-
-**Solution:**
-Autopilot v0.1.4+ includes enhanced Windows path handling to automatically ignore these files. If you still see issues:
-1. Ensure `.vscode/` and `*.log` are in your `.autopilotignore` file.
-2. Run `autopilot doctor` to verify your configuration.
-
-### "git.status is not a function"
-This was a known issue in older versions. Please upgrade to the latest version.
-
-### Permissions Errors
-Ensure you have write access to the repository and that no other process has locked the files (common on Windows with anti-virus software).
+# TROUBLESHOOTING
+
+## Common Issues
+
+### Watcher Loop / High CPU Usage (Windows)
+If Autopilot seems to be constantly triggering or consuming high CPU on Windows, it is likely due to "noisy" files that change frequently but should be ignored.
+
+**Common Culprits:**
+- `.vscode/time-analytics.json`: Some VS Code extensions write to this file constantly.
+- `autopilot.log`: If the watcher logs to a file that it is also watching, it creates a feedback loop.
+
+**Solution:**
+Autopilot v0.1.4+ includes enhanced Windows path handling to automatically ignore these files. If you still see issues:
+1. Ensure `.vscode/` and `*.log` are in your `.autopilotignore` file.
+2. Run `autopilot doctor` to verify your configuration.
+
+### "git.status is not a function"
+This was a known issue in older versions. Please upgrade to the latest version.
+
+### Permissions Errors
+Ensure you have write access to the repository and that no other process has locked the files (common on Windows with anti-virus software).