git-cracked 1.3.0 → 1.4.0

package/README.md

@@ -1,26 +1,68 @@
+<div align="center">
+
 # git-cracked
 
-Keep your GitHub contribution graph green automatically. Commits realistic-looking code changes to a private repo on a schedule — completely free, no API key needed.
+**Keep your GitHub contribution graph green — automatically.**
+
+[![npm version](https://img.shields.io/npm/v/git-cracked?color=3fb950&label=npm)](https://www.npmjs.com/package/git-cracked)
+[![node](https://img.shields.io/badge/node-18%2B-3fb950)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![no api key](https://img.shields.io/badge/API%20key-not%20required-blue)](#)
+
+[![stars](https://img.shields.io/github/stars/trentzx/git-cracked?style=flat&color=8b949e)](https://github.com/trentzx/git-cracked/stargazers)
+[![forks](https://img.shields.io/github/forks/trentzx/git-cracked?style=flat&color=8b949e)](https://github.com/trentzx/git-cracked/network/members)
+[![issues](https://img.shields.io/github/issues/trentzx/git-cracked?style=flat&color=f0a500)](https://github.com/trentzx/git-cracked/issues)
+[![prs](https://img.shields.io/github/issues-pr/trentzx/git-cracked?style=flat&color=3fb950)](https://github.com/trentzx/git-cracked/pulls)
+
+git-cracked makes small, realistic-looking code changes to a private repo on a
+schedule and commits them for you — so your activity graph stays active without
+you lifting a finger. Free, local, and no API key required.
+
+</div>
+
+<table>
+<tr>
+<td valign="top" width="50%">
+
+**What it does**
+
+- Commits on a schedule (e.g. 9am, 1pm, 4pm weekdays)
+- Makes realistic code changes across 18 languages
+- Generates matching commit messages
+- Catches up missed commits after sleep/shutdown
+- Pushes to your private repo automatically
+
+</td>
+<td valign="top" width="50%">
 
----
+**What it uses**
 
-## Quickstart
+- Node.js (cross-platform: Win / macOS / Linux)
+- `simple-git` for git operations
+- `node-cron` for scheduling
+- A built-in local web dashboard
+- Zero external services or API keys
 
-### You need
+</td>
+</tr>
+</table>
 
-- [Node.js v18+](https://nodejs.org)
-- A GitHub account
-- A private repo cloned to your machine (with some source code files in it)
+## Quick Start
 
-### One command
+One command — it opens your browser to a 30-second setup form:
 
 ```bash
 npx git-cracked
 ```
 
-Your browser opens automatically. If this is your first time, you'll see a setup page — fill in the path to your private repo and click save. That's it.
+On the setup page, click **+** to browse for your private repo folder (or paste
+the path), pick a schedule, and save. That's the whole install.
 
-### Or install from source
+> **You need:** Node.js 18+, a GitHub account, and a **private** repo cloned
+> locally with a few source files in it. Don't have one?
+> [Create one on GitHub](https://github.com/new).
+
+### Install from source instead
 
 ```bash
 git clone https://github.com/trentzx/git-cracked.git
@@ -29,40 +71,30 @@ npm install
 npm start
 ```
 
-### Auto-start on boot *(so it keeps running after restarts)*
-
-From a source install:
+### Keep it running after reboots
 
 ```bash
-# Windows
-npm run install-windows
-
-# macOS
-npm run install-mac
-
-# Linux
-npm run install-linux
+npm run install-windows   # or: install-mac / install-linux
 ```
 
----
+This registers git-cracked to start automatically on login and run quietly in
+the background.
 
 ## Dashboard
 
-Once running, open **[http://localhost:4856](http://localhost:4856)** to see:
+Once running, open **[localhost:4856](http://localhost:4856)** to see:
 
-- Total commits (all time + today)
-- Next scheduled commit times with countdown
-- Full commit history — message, file changed, how long ago
-- **Commit Now** button to test instantly
-- Settings page to change your repo, schedule, or branch
+- Total commits — all time and today
+- Next scheduled commit times with a live countdown
+- Full commit history (message, file changed, when)
+- A **⚡ Commit now** button to fire one instantly
+- A **Settings** page to change repo, branch, or schedule
 
 The dashboard auto-refreshes every 30 seconds.
 
----
+## Schedule
 
-## Changing the schedule
-
-Go to [http://localhost:4856/settings](http://localhost:4856/settings) and pick from the dropdown:
+Change it any time on the [Settings page](http://localhost:4856/settings):
 
 | Option | Times |
 |---|---|
@@ -71,86 +103,52 @@ Go to [http://localhost:4856/settings](http://localhost:4856/settings) and pick
 | 4× per weekday | 9am, 12pm, 3pm, 6pm |
 | 1× per weekday | 10am |
 
-All times use your computer's local time zone, so it works the same anywhere in the world.
-
----
+All times use your computer's local time zone, so it works the same anywhere in
+the world. If your machine is asleep at a scheduled time, git-cracked commits as
+soon as it wakes up so you don't miss a day.
 
 ## How it works
 
 1. At each scheduled time, a random source file in your repo is selected
-2. A small, realistic change is applied — fixing whitespace, normalising quotes, adjusting a constant, sorting imports, etc.
-3. A commit message is picked from a bank of 130+ realistic conventional commit messages that match the change type
-4. The commit is pushed to your private repo automatically
+2. A small, realistic change is applied — whitespace, quote style, `let`→`const`,
+   strict equality, import sorting, an adjusted constant, etc.
+3. A matching message is chosen from a bank of 130+ conventional commit messages
+4. The change is committed and pushed to your private repo
 
-**Supported file types:** `.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.java` `.rb` `.cs` `.cpp` `.c` `.rs` `.php` `.swift` `.kt` `.scala` `.sh`
+**Supported file types:** `.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.java`
+`.rb` `.cs` `.cpp` `.c` `.rs` `.php` `.swift` `.kt` `.scala` `.sh`
 
----
-
-## Stopping / removing
+## Show private commits on your graph
 
-**Kill the process** — just close the terminal, or stop the background service:
+Commits to private repos don't appear on your public graph by default. To count
+them: profile → **Contribution settings** → enable **Private contributions**.
+Visitors will see the activity, not the repo or code.
 
-**Windows** — delete the startup file:
-```
-del "%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\git-cracked.vbs"
-```
-
-**macOS:**
-```bash
-launchctl unload ~/Library/LaunchAgents/com.gitcracked.autocommit.plist
-rm ~/Library/LaunchAgents/com.gitcracked.autocommit.plist
-```
-
-**Linux:**
-```bash
-systemctl --user disable --now git-cracked
-```
+## Stopping / removing
 
----
+| Platform | Command |
+|---|---|
+| Windows | `del "%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\git-cracked.vbs"` |
+| macOS | `launchctl unload ~/Library/LaunchAgents/com.gitcracked.autocommit.plist && rm ~/Library/LaunchAgents/com.gitcracked.autocommit.plist` |
+| Linux | `systemctl --user disable --now git-cracked` |
 
 ## Troubleshooting
 
-**"No suitable files found to mutate"**
-Your private repo needs real source code files (`.js`, `.py`, `.ts`, etc.) that are at least 5 lines long and not minified.
-
-**Commits don't show on my GitHub graph**
-Make sure `git config user.email` in your private repo matches your GitHub account email:
-```bash
-cd path/to/your/private/repo
-git config user.email "you@example.com"
-```
+**"No suitable files found to mutate"** — your repo needs real source files
+(`.js`, `.py`, etc.) that are at least 5 lines long and not minified.
 
-**Push fails**
-You need GitHub credentials set up for HTTPS. Run `gh auth login` if you have the GitHub CLI, or set up SSH keys.
+**Commits don't show on my graph** — make sure `git config user.email` in your
+repo matches your GitHub account email, and enable private contributions (above).
 
----
+**Push fails** — you need GitHub credentials for HTTPS. Run `gh auth login` or
+set up SSH keys.
 
 ## Security
 
-- Your settings live in `~/.git-cracked/` on your machine and are never committed or uploaded
-- No data is sent anywhere — commit messages are generated locally
+- Settings live in `~/.git-cracked/` on your machine and are never uploaded
+- The dashboard binds to localhost only and rejects cross-origin requests
 - The tool only touches files inside the repo path you configure
 
----
-
-## Project structure
+## License
 
-```
-git-cracked/
-├── src/
-│   ├── cli.js          Entry point — starts app and opens browser
-│   ├── index.js        Scheduler
-│   ├── dashboard.js    Web dashboard + setup wizard (port 4856)
-│   ├── committer.js    Runs mutate → commit → push
-│   ├── mutator.js      Applies realistic code changes
-│   ├── messages.js     130+ commit message bank
-│   ├── logger.js       Saves activity to activity.json
-│   ├── config.js       Loads and validates config.json
-│   └── setup.js        CLI setup wizard (alternative to web UI)
-├── scripts/
-│   ├── install-windows.js
-│   ├── install-mac.js
-│   └── install-linux.js
-├── config.example.json
-└── package.json
-```
+MIT © [Trenton Scott](https://github.com/trentzx)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-cracked",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Auto-commits realistic-looking code changes to keep your GitHub green — free, no API key required",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -3,6 +3,7 @@ import { existsSync } from 'fs';
 import { loadConfig } from './config.js';
 import { runCommit } from './committer.js';
 import { startDashboard } from './dashboard.js';
+import { getActivity } from './logger.js';
 import { CONFIG_PATH } from './paths.js';
 
 const args = process.argv.slice(2);
@@ -21,13 +22,86 @@ if (runNow) {
   process.exit(0);
 }
 
+// How often the catch-up checker runs (ms). Catches scheduled slots that were
+// missed because the machine was asleep / shut down at the exact cron minute.
+const CATCHUP_INTERVAL_MS = 15 * 60 * 1000;
+
 let scheduled = false;
+let committing = false;
+let activeConfig = null;
 const activeTasks = [];
+let catchupTimer = null;
+
+// Single-flight wrapper so the cron jobs and the catch-up checker can never
+// run a commit at the same time (which would risk a double commit).
+async function safeCommit(config, reason) {
+  if (committing) return;
+  committing = true;
+  try {
+    await runCommit(config);
+  } catch (err) {
+    console.error(`${reason} failed:`, err.message);
+  } finally {
+    committing = false;
+  }
+}
+
+// Parse a 5-field cron expression into { h, m, dows } for catch-up math.
+// Returns null for expressions with ranges/lists in the minute or hour field,
+// which the catch-up checker simply skips (the live cron job still covers them).
+function parseExpr(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return null;
+  const [min, hour, , , dow] = parts;
+  const m = parseInt(min, 10);
+  const h = parseInt(hour, 10);
+  if (Number.isNaN(m) || Number.isNaN(h)) return null;
+
+  const dows = new Set();
+  if (dow === '*') {
+    for (let i = 0; i <= 6; i++) dows.add(i);
+  } else {
+    for (const p of dow.split(',')) {
+      if (p.includes('-')) {
+        const [a, b] = p.split('-').map(Number);
+        for (let i = a; i <= b; i++) dows.add(i % 7);
+      } else {
+        dows.add(Number(p) % 7);
+      }
+    }
+  }
+  return { h, m, dows };
+}
+
+// If a scheduled slot has already passed today (on a matching weekday) and no
+// commit has happened since, commit once to catch up.
+async function checkMissedCommits(config) {
+  const now = new Date();
+  let latestPassed = null;
+
+  for (const expr of config.schedule) {
+    const p = parseExpr(expr);
+    if (!p || !p.dows.has(now.getDay())) continue;
+    const slot = new Date(now);
+    slot.setHours(p.h, p.m, 0, 0);
+    if (slot <= now && (!latestPassed || slot > latestPassed)) latestPassed = slot;
+  }
+
+  if (!latestPassed) return; // nothing scheduled has passed today
+
+  const commits = getActivity().commits;
+  const last = commits[0] ? new Date(commits[0].timestamp) : null;
+  if (last && last >= latestPassed) return; // already committed since that slot
+
+  console.log(`[${now.toISOString()}] Catching up missed scheduled commit`);
+  await safeCommit(config, 'Catch-up commit');
+}
 
 function startSchedule(config) {
   // Replace any previously registered jobs (e.g. after a settings change)
   for (const task of activeTasks) task.stop();
   activeTasks.length = 0;
+  activeConfig = config;
 
   for (const expression of config.schedule) {
     if (!cron.validate(expression)) {
@@ -36,16 +110,21 @@ function startSchedule(config) {
     }
     const task = cron.schedule(expression, async () => {
       console.log(`[${new Date().toISOString()}] Cron triggered`);
-      try {
-        await runCommit(config);
-      } catch (err) {
-        console.error('Commit failed:', err.message);
-      }
+      await safeCommit(config, 'Scheduled commit');
     });
     activeTasks.push(task);
   }
+
   scheduled = true;
   console.log('Schedule active:', config.schedule.join(', '));
+
+  // Catch up anything missed while the machine was off, then poll periodically.
+  checkMissedCommits(config);
+  if (!catchupTimer) {
+    catchupTimer = setInterval(() => {
+      if (activeConfig) checkMissedCommits(activeConfig);
+    }, CATCHUP_INTERVAL_MS);
+  }
 }
 
 console.log('Git Cracked running.');