git-cracked 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trenton Scott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# 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.
+
+---
+
+## Quickstart
+
+### You need
+
+- [Node.js v18+](https://nodejs.org)
+- A GitHub account
+- A private repo cloned to your machine (with some source code files in it)
+
+### One command
+
+```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.
+
+### Or install from source
+
+```bash
+git clone https://github.com/trentzx/git-cracked.git
+cd git-cracked
+npm install
+npm start
+```
+
+### Auto-start on boot *(so it keeps running after restarts)*
+
+From a source install:
+
+```bash
+# Windows
+npm run install-windows
+
+# macOS
+npm run install-mac
+
+# Linux
+npm run install-linux
+```
+
+---
+
+## Dashboard
+
+Once running, open **[http://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
+
+The dashboard auto-refreshes every 30 seconds.
+
+---
+
+## Changing the schedule
+
+Go to [http://localhost:4856/settings](http://localhost:4856/settings) and pick from the dropdown:
+
+| Option | Times |
+|---|---|
+| 3× per weekday *(default)* | 9am, 1pm, 4pm |
+| 2× per weekday | 9am, 3pm |
+| 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.
+
+---
+
+## 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
+
+**Supported file types:** `.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.java` `.rb` `.cs` `.cpp` `.c` `.rs` `.php` `.swift` `.kt` `.scala` `.sh`
+
+---
+
+## Stopping / removing
+
+**Kill the process** — just close the terminal, or stop the background service:
+
+**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
+```
+
+---
+
+## 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"
+```
+
+**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.
+
+---
+
+## 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
+- The tool only touches files inside the repo path you configure
+
+---
+
+## Project structure
+
+```
+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
+```

package/config.example.json

@@ -0,0 +1,11 @@
+{
+  "repoPath": "/absolute/path/to/your/private/repo",
+  "branch": "main",
+  "remoteName": "origin",
+  "pushAfterCommit": true,
+  "schedule": [
+    "0 9 * * 1-5",
+    "0 13 * * 1-5",
+    "0 16 * * 1-5"
+  ]
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "git-cracked",
+  "version": "1.2.0",
+  "description": "Auto-commits realistic-looking code changes to keep your GitHub green — free, no API key required",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "git-cracked": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "config.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "commit-now": "node src/index.js --now",
+    "setup": "node src/setup.js",
+    "install-windows": "node scripts/install-windows.js",
+    "install-mac": "node scripts/install-mac.js",
+    "install-linux": "node scripts/install-linux.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trentzx/git-cracked.git"
+  },
+  "homepage": "https://github.com/trentzx/git-cracked#readme",
+  "bugs": {
+    "url": "https://github.com/trentzx/git-cracked/issues"
+  },
+  "author": "Trenton Scott",
+  "dependencies": {
+    "node-cron": "^3.0.3",
+    "simple-git": "^3.27.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "github",
+    "contributions",
+    "commits",
+    "automation",
+    "contribution-graph",
+    "scheduler"
+  ],
+  "license": "MIT"
+}

package/scripts/install-linux.js

@@ -0,0 +1,57 @@
+/**
+ * Installs git-cracked as a systemd user service on Linux.
+ * Run once with: node scripts/install-linux.js
+ * No sudo required — installs as a user service.
+ */
+import { execSync } from 'child_process';
+import { writeFileSync, mkdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+const entryPoint = join(projectRoot, 'src', 'index.js');
+const nodePath = process.execPath;
+const serviceDir = join(homedir(), '.config', 'systemd', 'user');
+const servicePath = join(serviceDir, 'git-cracked.service');
+
+if (!existsSync(join(projectRoot, 'config.json'))) {
+  console.error('config.json not found. Run "npm run setup" first.');
+  process.exit(1);
+}
+
+const unit = `[Unit]
+Description=Git Cracked - automatic GitHub commit scheduler
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${nodePath} ${entryPoint}
+WorkingDirectory=${projectRoot}
+Restart=on-failure
+RestartSec=30
+StandardOutput=append:${projectRoot}/git-cracked.log
+StandardError=append:${projectRoot}/git-cracked.log
+
+[Install]
+WantedBy=default.target
+`;
+
+mkdirSync(serviceDir, { recursive: true });
+writeFileSync(servicePath, unit);
+
+try {
+  execSync('systemctl --user daemon-reload');
+  execSync('systemctl --user enable git-cracked.service');
+  execSync('systemctl --user start git-cracked.service');
+  console.log('systemd user service installed and started.');
+  console.log('Status:  systemctl --user status git-cracked');
+  console.log(`Logs:    ${projectRoot}/git-cracked.log`);
+  console.log('Remove:  systemctl --user disable --now git-cracked');
+} catch (err) {
+  console.error('Failed to install service:', err.message);
+  console.error('Make sure systemd user services are supported on your distro.');
+  process.exit(1);
+}

package/scripts/install-mac.js

@@ -0,0 +1,63 @@
+/**
+ * Installs git-cracked as a macOS launchd agent.
+ * Run once with: node scripts/install-mac.js
+ * No sudo required — installs for the current user only.
+ */
+import { execSync } from 'child_process';
+import { writeFileSync, mkdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+const entryPoint = join(projectRoot, 'src', 'index.js');
+const nodePath = process.execPath;
+const label = 'com.gitcracked.autocommit';
+const launchAgentsDir = join(homedir(), 'Library', 'LaunchAgents');
+const plistPath = join(launchAgentsDir, `${label}.plist`);
+
+if (!existsSync(join(projectRoot, 'config.json'))) {
+  console.error('config.json not found. Run "npm run setup" first.');
+  process.exit(1);
+}
+
+const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${entryPoint}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${projectRoot}/git-cracked.log</string>
+  <key>StandardErrorPath</key>
+  <string>${projectRoot}/git-cracked.log</string>
+  <key>WorkingDirectory</key>
+  <string>${projectRoot}</string>
+</dict>
+</plist>`;
+
+mkdirSync(launchAgentsDir, { recursive: true });
+writeFileSync(plistPath, plist);
+
+try {
+  // Unload existing agent if running
+  execSync(`launchctl unload "${plistPath}" 2>/dev/null || true`);
+  execSync(`launchctl load "${plistPath}"`);
+  console.log('LaunchAgent installed and started.');
+  console.log(`Logs: ${projectRoot}/git-cracked.log`);
+  console.log(`To remove: launchctl unload "${plistPath}" && rm "${plistPath}"`);
+} catch (err) {
+  console.error('Failed to load agent:', err.message);
+  process.exit(1);
+}

package/scripts/install-windows.js

@@ -0,0 +1,38 @@
+/**
+ * Installs git-cracked to the Windows Startup folder.
+ * Runs automatically on login. No admin rights required.
+ * Run with: node scripts/install-windows.js
+ */
+import { execSync } from 'child_process';
+import { writeFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+const entryPoint = join(projectRoot, 'src', 'cli.js');
+const nodePath = process.execPath;
+
+
+// Windows Startup folder — runs for current user, no admin needed
+const startupDir = join(
+  homedir(),
+  'AppData', 'Roaming', 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup'
+);
+const vbsPath = join(startupDir, 'git-cracked.vbs');
+const logPath = join(projectRoot, 'git-cracked.log');
+
+// VBScript launches Node hidden (no console window flashing on login)
+const vbs = `Set WshShell = CreateObject("WScript.Shell")
+WshShell.Run """${nodePath}"" ""${entryPoint}""", 0, False`;
+
+writeFileSync(vbsPath, vbs);
+
+console.log('git-cracked installed to Startup folder.');
+console.log(`Startup script: ${vbsPath}`);
+console.log(`Logs:           ${logPath}`);
+console.log('');
+console.log('It will start automatically on next login.');
+console.log(`To remove: del "${vbsPath}"`);

package/src/ai.js

@@ -0,0 +1,3 @@
+import { generateCommitMessage } from './messages.js';
+
+export { generateCommitMessage };

package/src/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { CONFIG_PATH } from './paths.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const hasConfig = existsSync(CONFIG_PATH);
+const PORT = 4856;
+
+// Start the main process
+const child = spawn(process.execPath, [join(__dirname, 'index.js')], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('exit', (code) => process.exit(code ?? 0));
+
+// Open browser after a short delay to let the server start
+setTimeout(() => {
+  const url = `http://localhost:${PORT}${hasConfig ? '' : '/setup'}`;
+  openBrowser(url);
+}, 1200);
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd =
+    platform === 'win32' ? ['cmd', ['/c', 'start', url]] :
+    platform === 'darwin' ? ['open', [url]] :
+    ['xdg-open', [url]];
+  try {
+    spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    console.log(`Open your browser to: ${url}`);
+  }
+}

package/src/committer.js

@@ -0,0 +1,37 @@
+import simpleGit from 'simple-git';
+import { existsSync } from 'fs';
+import { mutateRepo } from './mutator.js';
+import { generateCommitMessage } from './ai.js';
+import { logCommit } from './logger.js';
+
+export async function runCommit(config) {
+  if (!existsSync(config.repoPath)) {
+    throw new Error(`Repo path does not exist: ${config.repoPath}`);
+  }
+
+  const git = simpleGit(config.repoPath);
+
+  const isRepo = await git.checkIsRepo().catch(() => false);
+  if (!isRepo) {
+    throw new Error(`Not a git repository: ${config.repoPath}`);
+  }
+
+  const { changedFiles, description, relPath } = await mutateRepo(config.repoPath);
+
+  if (changedFiles.length === 0) {
+    console.log('No suitable files found to mutate — skipping commit.');
+    return;
+  }
+
+  const message = generateCommitMessage(description);
+
+  await git.add(changedFiles);
+  await git.commit(message);
+
+  if (config.pushAfterCommit) {
+    await git.push(config.remoteName, config.branch);
+  }
+
+  logCommit({ message, file: relPath, repoPath: config.repoPath });
+  console.log(`Committed: ${message}`);
+}

package/src/config.js

@@ -0,0 +1,36 @@
+import { readFileSync, existsSync } from 'fs';
+import { CONFIG_PATH } from './paths.js';
+
+export function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    console.error('ERROR: No configuration found. Run "npm start" and complete setup in the browser.');
+    process.exit(1);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    console.error(`ERROR: ${CONFIG_PATH} is not valid JSON. Delete it and run setup again.`);
+    process.exit(1);
+  }
+
+  const errors = [];
+  if (!raw.repoPath) errors.push('repoPath is required');
+  if (!Array.isArray(raw.schedule) || raw.schedule.length === 0) {
+    errors.push('schedule must be a non-empty array');
+  }
+
+  if (errors.length) {
+    console.error('ERROR: Invalid config:\n' + errors.map(e => '  - ' + e).join('\n'));
+    process.exit(1);
+  }
+
+  return {
+    repoPath: raw.repoPath,
+    branch: raw.branch ?? 'main',
+    remoteName: raw.remoteName ?? 'origin',
+    pushAfterCommit: raw.pushAfterCommit !== false,
+    schedule: raw.schedule,
+  };
+}