🔄 GitMorph CLI (gitmorph-dev)

GitMorph CLI is a secure, lightweight, and completely decentralized command-line tool designed to schedule, automate, and monitor your Git contributions on GitHub.

By analyzing local repository history (git log) and generating serverless GitHub Actions workflows, GitMorph CLI acts as its own offline database—eliminating external database dependencies (no Firebase) and cloud hosting entirely.

🚀 Key Features

• 🔐 Direct CLI Authentication: Logs in directly with your GitHub Personal Access Token (PAT) via secure local storage.
• 🛡️ Security-First Design: Global configuration files (~/.gitmorph/config.json) are stored with restricted 0600 owner-only permissions.
• 📅 Multi-Week Commit Ranges: Set schedules for 1 Week, 1 Month, or 6 Months.
• 🎲 Smart Range Randomization: Input weekday and weekend commit ranges (e.g. 10-20 on weekdays, 0-5 on weekends), and let the CLI generate a randomized daily schedule.
• 📊 Interactive History & Progress: Renders a gorgeous terminal dashboard. Select a process to view progress bars ([██████░░░░] 60%) and day-by-day logs of scheduled vs. completed commits.
• ☁️ Serverless Automation: Generates standard GitHub Actions workflows (.github/workflows/auto-commit.yml) to perform the commits on GitHub's servers, keeping your local machine offline.

📦 Installation

Install GitMorph CLI globally using npm:

npm install -g gitmorph-dev

⚙️ Quick Start

1. Authenticate with GitHub

Start by logging in with a GitHub Personal Access Token (PAT):

gitmorph login

Note: Make sure your PAT has repo, workflow, and read:user permissions enabled.

2. Configure Commit Automation

Navigate to the root directory of any GitHub repository you want to automate and run:

gitmorph set

You will be prompted for:

1. Process Name (default is your folder name).
2. Duration (1 week, 1 month, or 6 months).
3. Weekday Range (e.g., 10-15 commits).
4. Weekend Range (e.g., 0-5 commits).
5. Commit Message Template.

The CLI will:

• Generate your daily randomized schedule and save it locally in .gitmorph.json.
• Write auto_commit_script.js and .github/workflows/auto-commit.yml to your repository.
• Prompt to commit, push the files, and immediately trigger the Action workflow run on GitHub!

3. Track History & Daily Progress

Monitor all your automated repositories on this machine from any directory:

gitmorph history

• Select the target process from the interactive menu using Arrow keys and Enter.
• View overall completion rates and select a week to inspect the day-by-day log table showing:
  • Date & Weekday
  • Scheduled target
  • Actual commits completed (extracted directly from local git log analytics)
  • Status (✔ Met, ⏳ In Progress, ✖ Missed, or ➖ No commits scheduled)

4. Logout (Optional)

To clear your GitHub credentials and local access tokens from the machine:

gitmorph logout

📊 Architecture Flow

flowchart TB
  subgraph CLI["Your Machine — gitmorph CLI"]
    SET["gitmorph set"] --> GHAPI1
    HIST["gitmorph history"] --> GHAPI2
    DEL["gitmorph delete"] --> GHAPI3

    GHAPI1["GET /user/repos → pick repo"]
    GHAPI1 --> GEN["Generate 3 files:<br/>• auto_commit_script.js<br/>• .github/workflows/auto-commit.yml<br/>• .gitmorph.json"]
    GEN --> UPLOAD["PUT /repos/{repo}/contents/{path}<br/>(base64, overwrites if exists)"]
    UPLOAD --> DISPATCH["POST .../dispatches<br/>→ trigger first run"]

    GHAPI2["GET /user/repos → for each:<br/>GET /.gitmorph.json"]
    GHAPI2 --> PICK["Pick process → GET /commits<br/>?since=..&until=.. (paginated)"]
    PICK --> COMPARE["Filter by message prefix<br/>Compare dates vs schedule<br/>→ show dashboard"]

    GHAPI3["Same scan as history"]
    GHAPI3 --> CANCEL["POST /actions/runs/{id}/cancel<br/>on all queued/in_progress runs"]
  end

  subgraph GH["GitHub Repository"]
    FILES["• .gitmorph.json (schedule + config)<br/>• auto_commit_script.js<br/>• .github/workflows/auto-commit.yml"]
  end

  subgraph RUNNER["GitHub Actions Runner"]
    TRIGGER["Cron fires at e.g. 8:42 AM"]
    TRIGGER --> EXEC["node auto_commit_script.js"]
    EXEC --> READCFG["Read .gitmorph.json<br/>→ today = N commits"]
    READCFG --> DELAYS["Calculate delays:<br/>• 90% in 9AM–9PM working hours<br/>• 10% in off-hours<br/>• ±25% jitter<br/>• cap at 5.5h runtime"]
    DELAYS --> LOOP["Loop N times:"]
    LOOP --> COMMIT["create commit-{ts}-{n}.txt<br/>→ git add → git commit<br/>→ git push → sleep(delay)"]
  end

  UPLOAD --> FILES
  DISPATCH --> TRIGGER
  FILES --> READCFG

🛡️ Security Details

• Local Encryption & Permissions: The CLI uses fs.chmodSync to restrict global token stores to 0o600 permissions. No other user account or process on the machine can read your GitHub access tokens.
• Safe Command Runs: All Git commands are executed using child_process.spawn with array-parameterized arguments, blocking shell-injection vulnerabilities.
• No Database Over-Sharing: Your configurations remain local in .gitmorph.json within your repository. There is no central server storing your repository details or schedules.

📜 License

This project is licensed under the MIT License.