@traisetech/autopilot 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,19 +1,35 @@
 # Changelog
 
-## [2.4.0] - 2026-02-18
 
-### Added
-- **Intelligent Guide System**: New `autopilot guide` command for interactive onboarding and documentation.
-- **Enhanced Visual Identity**: Modernized branding and professional documentation aesthetics.
-- **Premium Command Reference**: Redesigned website command library with grouped categories and interactive cards.
+## [2.5.0] - 2026-03-28
 
-### Improved
-- **Developer Experience**: Added explicit guide callouts in the documentation hero section.
-- **Onboarding Flow**: Simplified the initial setup path for new users.
+### Added (v2.5.0)
+
+- **VS Code Extension Engine**:
+  - Implemented `.autopilot-state.json` for real-time state synchronization (PID, status, uptime, branch, etc.).
+  - Added `.autopilot.log` with automatic rotation (500KB cap) for fast, incremental streaming in extension UI.
+  - Implemented 5s heartbeat in watcher to keep remote UIs perfectly synchronized.
+- **Improved Process Lifecycle**:
+  - `autopilot stop` now performs deep cleanup of state, log, and PID files.
+  - Enforced `.autopilot-state.json` and `.autopilot.log` as reserved system files, auto-ignored by the watcher.
+
+### Improved (v2.5.0)
+
+- **Logger Engine**: Pipe all CLI output to `.autopilot.log` by default.
+- **Persistence**: Re-aligned `startedAt` timestamps to ISO strings for cross-tool compatibility.
+
+## [2.4.0] - 2026-03-10
+
+### Added (v2.4.0)
+
+- **Focus Engine Upgrades**: Improved detection of deep work sessions and productivity streaks.
+- **Enhanced AI Logic**: More accurate conventional commit categorization for mixed changes.
 
 ## [2.3.0] - 2026-02-18
 
-### Added
+### Added (v2.3.0)
+
+
 - **Production-Ready Leaderboard**:
   - Implemented secure Row-Level Security (RLS) policies for anonymized stat synchronization.
   - Enhanced API response to include real-time global ranking.

package/README.md

@@ -1,106 +1,215 @@
-# 🚀 Autopilot
-
-<div align="center">
-
-<img src="https://autopilot-cli.vercel.app/favicon.svg" width="120" height="120" alt="Autopilot Logo" />
-
-# Autopilot CLI v2.4.0
-**The Intelligent Git Engine That Respects Your Flow.**
-
-[![npm version](https://img.shields.io/npm/v/@traisetech/autopilot?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@traisetech/autopilot)
-[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
-[![Downloads](https://img.shields.io/npm/dm/@traisetech/autopilot?style=for-the-badge&color=violet)](https://www.npmjs.com/package/@traisetech/autopilot)
-[![GitHub Stars](https://img.shields.io/github/stars/PraiseTechzw/autopilot-cli?style=for-the-badge&color=ffd700)](https://github.com/PraiseTechzw/autopilot-cli/stargazers)
-
-[**Explore Documentation**](https://autopilot-cli.vercel.app) • [**View Leaderboard**](https://autopilot-cli.vercel.app/leaderboard) • [**Report Bug**](https://github.com/PraiseTechzw/autopilot-cli/issues)
-
-</div>
-
----
-
-## 💎 Why Autopilot?
-
-Autopilot isn't just a "git commit" wrapper. It's a **flow-state companion** designed for high-velocity developers who don't want to break their concentration for repetitive git operations.
-
--   **Intelligent Sync**: Automates the commit-push cycle with smart debouncing that respects your typing patterns.
--   **Local-First Architecture**: Your code NEVER leaves your machine. Automation is 100% local.
--   **Zero-Config Simplicity**: Works out of the box with `autopilot init`, but offers surgical control for power users.
--   **AI-Assisted Clarity**: Optional integration with Gemini or Grok to generate meaningful, human-readable commit messages.
--   **Focus Engine**: Track your coding streaks and focus minutes without external time trackers.
-
----
-
-## 🛠️ Performance & Safety Rails
-
-We built Autopilot with a **"Trust First"** philosophy. It includes hard-coded safety guarantees that make it impossible to break your repository history.
-
-### 🛡️ Non-Negotiable Guarantees
--   **No Force-Pushes**: Autopilot will never overwrite remote history.
--   **Conflict Awareness**: Automatically pauses if a merge conflict is detected.
--   **Secret Prevention**: Scans and blocks commits containing `.env` files or potential API keys.
--   **Implicit Reversibility**: Every automated action can be reverted instantly with `autopilot undo`.
-
----
-
-## 🚀 Getting Started
-
-### 1. Installation
-```bash
-npm install -g @traisetech/autopilot
-```
-
-### 2. Quick Setup
-Run the interactive guide to learn the ropes:
-```bash
-autopilot guide
-```
-
-### 3. Initialize Your Repo
-```bash
-cd /path/to/project
-autopilot init
-```
-
-### 4. Lift Off
-```bash
-autopilot start
-```
-
----
-
-## 📊 The Command Suite
-
-| Command | Purpose |
-| :--- | :--- |
-| `autopilot start` | Launch the intelligent background watcher. |
-| `autopilot dashboard` | View real-time activity in a high-fidelity TUI. |
-| `autopilot insights` | Deep-dive into your productivity and streak data. |
-| `autopilot undo` | Roll back the last automated commit & preserve changes. |
-| `autopilot guide` | **(NEW)** Interactive walkthrough and onboarding. |
-| `autopilot doctor` | Validate your environment and diagnostic health. |
-| `autopilot status` | Instant pulse-check on the automation engine. |
-
----
-
-## 🔒 Privacy & AI Transparency
-
--   **Opt-In AI**: AI features are strictly disabled by default. You provide your own keys; we never see them.
--   **No Code Collection**: We do not store, proxy, or train on your source code.
--   **Anonymized Metrics**: Leaderboard data uses cryptographic hashes to preserve your identity while celebrating your progress.
-
----
-
-## 🤝 Contributing
-
-Autopilot is built by the community. Want to help?
-1. Check out our [Architecture Overview](docs/ARCHITECTURE.md).
-2. Look for `good-first-issue` labels.
-3. Join the mission to automate developer productivity.
-
----
-
-<div align="center">
-Built with ❤️ by <b>Praise Masunga (PraiseTechzw)</b>
-<br/>
-<i>Git automation that respects your control.</i>
-</div>
+# 🚀 Autopilot
+
+<div align="center">
+
+![Autopilot Logo](https://img.shields.io/badge/Autopilot-blue?style=for-the-badge&logo=git&logoColor=white)
+
+**An intelligent Git automation CLI that safely commits and pushes your code so you can focus on building.**
+
+[![npm version](https://img.shields.io/npm/v/@traisetech/autopilot?style=flat-square&color=success)](https://www.npmjs.com/package/@traisetech/autopilot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square)](https://nodejs.org)
+[![Downloads](https://img.shields.io/npm/dm/@traisetech/autopilot?style=flat-square&color=blue)](https://www.npmjs.com/package/@traisetech/autopilot)
+[![GitHub Stars](https://img.shields.io/github/stars/PraiseTechzw/autopilot-cli?style=flat-square&color=gold)](https://github.com/PraiseTechzw/autopilot-cli/stargazers)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/PraiseTechzw/autopilot-cli/ci.yml?style=flat-square)](https://github.com/PraiseTechzw/autopilot-cli/actions)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+
+**Built by [Praise Masunga](https://github.com/PraiseTechzw) (PraiseTechzw)**
+
+[Features](#-features) • [Installation](#-installation) • [How It Works](#-how-autopilot-works) • [Safety & Guarantees](#-safety--guarantees) • [Commands](#-commands)
+
+</div>
+
+---
+
+## 📖 Table of Contents
+
+- [How Autopilot Works](#-how-autopilot-works)
+- [Safety & Guarantees](#-safety--guarantees)
+- [Failure & Recovery](#-failure--recovery)
+- [AI & Privacy](#-ai--privacy)
+- [Leaderboard & Metrics](#-leaderboard--metrics)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Commands](#-commands)
+- [Configuration](#-configuration)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+---
+
+## 🔍 How Autopilot Works
+
+Autopilot is a local CLI tool that runs in the background of your terminal. It watches your file system for changes and automates the Git workflow based on your configuration.
+
+**No Magic. Just Automation.**
+
+1.  **Watch**: It monitors your project directory for file modifications, creations, and deletions.
+2.  **Wait**: It uses a smart debounce timer (default: 20s) to wait until you stop typing.
+3.  **Check**: It verifies the repository status (branch, remote, conflicts) before acting.
+4.  **Commit**: It stages changes and creates a commit. If AI is enabled, it generates a meaningful message; otherwise, it uses a smart template.
+5.  **Push**: It pushes to your remote repository (optional, enabled by default).
+
+You can stop, pause, or undo Autopilot at any time.
+
+---
+
+## 🛡️ Safety & Guarantees
+
+We prioritize the safety of your code above all else. Autopilot follows strict rules to ensure your work is never lost or corrupted.
+
+### Non-Negotiable Guarantees
+
+-   **Never force-pushes**: Autopilot only performs standard `git push` operations. It will never overwrite remote history.
+-   **Never commits ignored files**: It strictly respects your `.gitignore` and `.autopilotignore` rules.
+-   **Never operates during merge/rebase**: If your repo is in a merge, rebase, or cherry-pick state, Autopilot pauses automatically.
+-   **Never transmits source code without opt-in**: Your code stays local. It is only sent to an AI provider (Gemini/Grok) if you explicitly enable AI features and provide your own API key.
+-   **Pauses when uncertain**: If a git error occurs, a conflict is detected, or the network fails, Autopilot pauses and waits for your intervention.
+-   **Allows all actions to be undone**: The `autopilot undo` command safely reverts the last automated commit without losing your file changes.
+
+---
+
+## ⚠️ Failure & Recovery
+
+What happens when things go wrong? Autopilot is designed to fail safely.
+
+-   **Merge Conflicts**: If a `git pull` results in a conflict, Autopilot aborts the operation and notifies you. It will not attempt to resolve conflicts automatically.
+-   **Network Issues**: If the internet disconnects, Autopilot will queue commits locally and attempt to push when connectivity is restored (if auto-push is enabled).
+-   **Accidental Commits**: If Autopilot commits something you didn't intend, simply run `autopilot undo`. Your files will remain modified in your working directory, but the commit will be removed.
+
+---
+
+## 🤖 AI & Privacy
+
+Autopilot offers **optional** AI integration (Google Gemini or xAI Grok) to generate context-aware commit messages.
+
+-   **Opt-In Only**: AI features are disabled by default. You must enable them and provide your own API key.
+-   **Data Usage**: When enabled, only the `git diff` (text changes) is sent to the AI provider to generate the message.
+-   **Privacy**: Your code is not trained on by Autopilot. We do not store or proxy your code. Interactions are directly between your machine and the AI provider.
+-   **Ranking**: AI usage does not affect your position on the Leaderboard.
+
+---
+
+## 🏆 Leaderboard & Metrics
+
+Autopilot includes a Focus Engine that tracks your local productivity (coding time, commit streaks). You can optionally sync this data to the global Leaderboard.
+
+-   **Participation is Opt-In**: You must explicitly enable syncing with `autopilot config set leaderboard.sync true`.
+-   **Privacy-Safe**: We do not send your email or username directly. IDs are hashed/anonymized.
+-   **No Code Collected**: The leaderboard tracks *metrics* (time, counts), not code. No file contents are ever synced.
+-   **Insight over Competition**: The goal is to help you understand your habits, not to gamify commit spam. Rankings favor consistency and quality.
+
+---
+
+## ⬇️ Installation
+
+Install Autopilot globally using npm:
+
+```bash
+npm install -g @traisetech/autopilot
+```
+
+Or run it directly via npx:
+
+```bash
+npx @traisetech/autopilot start
+```
+
+---
+
+## 🚀 Quick Start
+
+1.  **Navigate to your Git repository:**
+    ```bash
+    cd /path/to/my-project
+    ```
+
+2.  **Initialize Autopilot:**
+    ```bash
+    autopilot init
+    ```
+    Follow the interactive prompts to configure settings (or accept defaults).
+
+3.  **Start the watcher:**
+    ```bash
+    autopilot start
+    ```
+
+    **Autopilot is now running!** It will monitor file changes and automatically commit/push them based on your configuration.
+
+4.  **View the Dashboard:**
+    Open a new terminal and run:
+    ```bash
+    autopilot dashboard
+    ```
+
+---
+
+## 🎨 VS Code Extension (Recommended)
+
+Prefer a GUI? Use our official **Autopilot VS Code Extension**:
+
+-   **Live Sidebar**: Monitor status, branch, and queue at a glance.
+-   **Integrated Logs**: View color-coded process output directly in your editor.
+-   **Quick Actions**: Start, stop, pause, and undo with a single click from the status bar.
+-   **Settings UI**: Form-based configuration of your `.autopilotrc.json`.
+
+**[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=praisetechzw.autopilot-vscode)**
+
+---
+
+## 🛠️ Commands
+
+| Command | Description |
+|---------|-------------|
+| `autopilot init` | Initialize configuration in the current repo. |
+| `autopilot start` | Start the watcher process (foreground). |
+| `autopilot stop` | Stop the running watcher process. |
+| `autopilot status` | Check if Autopilot is running. |
+| `autopilot dashboard` | View real-time status and activity UI. |
+| `autopilot undo` | Revert the last Autopilot commit. |
+| `autopilot pause` | Temporarily pause automation. |
+| `autopilot resume` | Resume automation. |
+| `autopilot insights` | View productivity stats and analytics. |
+| `autopilot doctor` | Diagnose configuration and environment issues. |
+
+---
+
+## ⚙️ Configuration
+
+Autopilot uses an `.autopilotrc.json` file in your project root.
+
+```json
+{
+  "debounceSeconds": 20,
+  "minSecondsBetweenCommits": 180,
+  "autoPush": true,
+  "blockBranches": ["main", "master"],
+  "teamMode": true,
+  "preventSecrets": true,
+  "ai": {
+    "enabled": true,
+    "provider": "gemini"
+  }
+}
+```
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for full details.
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+1.  Fork the repo
+2.  Create a feature branch (`git checkout -b feature/amazing-feature`)
+3.  Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4.  Push to the branch (`git push origin feature/amazing-feature`)
+5.  Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/bin/autopilot.js

@@ -149,5 +149,5 @@ program
 
 (async () => {
   await checkForUpdate();
-  program.parse(process.argv);
+  await program.parseAsync(process.argv);
 })();

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`.