🛡️ LocalCI Guard

Run GitHub Actions CI/CD checks locally before pushing to GitHub — a VS Code extension powered by act.

---

✨ Features

	Feature	Description
🔍	Workflow Detection	Auto-discovers .github/workflows/*.yml with live YAML validation
⚡	Local Act Runner	Runs full workflows, individual jobs, or specific events via act
🔒	Pre-Push Hook	Automatically blocks pushes when CI fails
✅	Pre-Commit Hook	Runs lint + tests before every commit
📊	Status Bar	Live CI status: Idle / Running / Passing / Failing
🌲	Workflow Sidebar	Browse and run workflows, jobs, and steps visually
🐳	Docker & act Check	Validates dependencies, shows guided install instructions
❌	Error Highlighting	Inline YAML diagnostics in the editor
🌐	Multi-Language	Go, Python, Node.js, and generic project support

---

📋 Requirements

Docker

act requires Docker to spin up containers that simulate GitHub Actions runners.

Platform	Command
macOS	brew install --cask docker
Ubuntu/Debian	sudo apt-get install docker.io && sudo systemctl start docker
Windows	Docker Desktop

act

Platform	Command
macOS	brew install act
Linux	curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
Windows	choco install act-cli or scoop install act

---

🚀 Quick Start

Install from Marketplace

Search for LocalCI Guard in the VS Code Extensions panel, or:

code --install-extension localci-guard.localci-guard

Install from Source

# 1 — Clone
git clone https://github.com/souvik03-136/localci-guard.git
cd localci-guard

# 2 — Install dependencies & compile
npm install && npm run compile

# 3 — Package
npm run package
# → dist/localci-guard-1.0.0.vsix

# 4 — Install in VS Code
code --install-extension dist/localci-guard-1.0.0.vsix

Development Mode

npm install
# Press F5 in VS Code → Extension Development Host opens

---

🛠️ Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command	Description
LocalCI Guard: Run Local CI	Run CI with the default event
LocalCI Guard: Run Workflow	Pick a workflow and run it
LocalCI Guard: Run Job	Run a specific job from the sidebar
LocalCI Guard: Install Git Hooks	Install pre-push and pre-commit hooks
LocalCI Guard: Open CI Logs	Show the output panel
LocalCI Guard: Check Dependencies	Verify Docker and act are installed
LocalCI Guard: Stop Running CI	Cancel active run
LocalCI Guard: Refresh Workflows	Reload the sidebar tree

---

⚙️ Configuration

Add these to your .vscode/settings.json or VS Code global settings:

{
  // Automatically run CI checks when workflow files are saved
  "localci.autoRunOnSave": false,

  // Run CI checks before git push (requires git hooks)
  "localci.runOnPush": true,

  // Enable pre-commit quality checks
  "localci.enablePreCommit": true,

  // Default GitHub Actions event to simulate
  "localci.defaultEvent": "push",   // "push" | "pull_request" | "workflow_dispatch"

  // Path to the 'act' binary (default: "act")
  "localci.actPath": "act",

  // Path to the Docker binary (default: "docker")
  "localci.dockerPath": "docker",

  // Timeout in seconds for CI runs
  "localci.timeout": 300,

  // Enable verbose logging
  "localci.verbose": false
}

---

🌐 Multi-Language Hook Support

The pre-commit hook auto-detects your project language and runs appropriate checks:

Language	Detected By	Lint	Tests
Go	go.mod	golangci-lint / go vet	go test ./... -short
Python	requirements.txt / pyproject.toml	flake8	pytest -q
Node.js	package.json	eslint / npm run lint	npm test
Generic	fallback	workflow only	workflow only

---

🏗️ Architecture

src/
├── extension.ts             entry point — wires all services together
├── commands/
│   ├── runCI.ts             Run CI / workflow / job commands
│   └── installHooks.ts      git hook install/uninstall
├── services/
│   ├── actRunner.ts         spawns act, streams logs, owns CIStatus
│   ├── workflowParser.ts    parses YAML, validates, emits diagnostics
│   ├── gitHookManager.ts    writes pre-push/pre-commit scripts
│   └── dockerChecker.ts     checks docker + act, shows install guide
├── ui/
│   ├── statusBar.ts         bottom-bar status indicator
│   └── workflowTreeView.ts  sidebar tree provider
└── utils/
    ├── logger.ts            output channel wrapper
    └── shell.ts             safe spawn/execFile + sanitisation

---

🔒 Security

• All shell commands use spawn / execFile with shell: false — no injection possible
• User arguments pass through sanitizeArg() (strips metacharacters) before use
• Path traversal prevented by validatePath() checks
• Existing git hooks are backed up before overwriting
• No credentials or tokens are ever written to logs
• Nothing executes without explicit user action

---

📦 Publishing a Release

1. Add GitHub repository secrets

Go to your repo → Settings → Secrets and variables → Actions and add:

Secret	Value
VSCE_PAT	Your VS Code Marketplace Personal Access Token
OVSX_TOKEN	Your Open VSX token (optional)

Create a GitHub Actions environment named marketplace.

2. Cut a release

# Automated (recommended)
./scripts/release.sh patch    # bumps 1.0.0 → 1.0.1, commits, tags, pushes

# Manual
npm version patch
git add package.json CHANGELOG.md
git commit -m "chore: release v1.0.1"
git tag v1.0.1
git push origin main --tags

3. What happens automatically

git push tag
    │
    ▼
GitHub Actions: release.yml
    ├── lint & type-check
    ├── build (TypeScript compile)
    ├── test (unit tests)
    ├── docker (build + push image to GHCR)
    ├── package (build .vsix)
    ├── release (create GitHub Release, attach .vsix)
    └── publish-marketplace (VS Code Marketplace + Open VSX)

---

🤝 Contributing

See CONTRIBUTING.md for development setup, coding standards, and PR process.

📜 Changelog

See CHANGELOG.md.

🔐 Security

See SECURITY.md to report vulnerabilities privately.

📄 License

MIT © LocalCI Guard Contributors