ShipGuard

Open-source CLI that scans repos for demo/deploy risks, scores readiness, and generates AI-guided fixes with CI support. Built with Kilo Code.

Comment

Inspiration

Every developer has had a demo or deployment go wrong because of one small issue: a missing environment variable, a leaked secret, a risky Docker config, or a reliability problem that was easy to miss under time pressure.

I wanted to build a tool that answers one practical question before a demo or release:

"Is this repo safe enough to ship right now?"

That became ShipGuard — a fast, open-source CLI designed to catch demo/deploy risks early and give developers an actionable path to fix them.

What it does

ShipGuard is an AI-powered CLI for pre-demo and pre-deploy checks.

It scans a repository for common risk patterns and produces:

  • Severity-based findings (Critical / Medium / Low)
  • An explainable risk score
  • An AI-guided review with prioritized fixes
  • A fix patch preview (with safe auto-apply for selected fixes)
  • CI integration support with exit codes and JSON output

Examples of issues it detects

  • Hardcoded secrets (API keys, private key patterns)
  • Missing .env.example while .env exists
  • Risky Docker configuration (e.g. exposed DB port 5432)
  • Reliability issues like excessive console.log usage

The goal is not to replace testing or security tools. The goal is to catch the most common "demo gremlins" quickly and make the output immediately useful for developers.

How I built it

ShipGuard is built as a TypeScript + Node.js CLI.

Core architecture

  • Scanner engine: recursively scans project files
  • Rule system: modular per-rule checks for secrets, env integrity, Docker config, and reliability
  • Scoring engine: calculates an explainable readiness score
  • AI review module: generates prioritized recommendations and quick fixes
  • Fix engine: creates patch previews and supports safe auto-fixes
  • CLI output layer: polished terminal UX for fast reading
  • CI workflow: GitHub Actions integration using exit codes and score thresholds

I also added:

  • --json output for automation and pipelines
  • CI-friendly exit behavior (fail builds under a score threshold)

This makes ShipGuard useful both locally and in team workflows.

How Kilo Code helped

I built ShipGuard during DeveloperWeek 2026 and used Kilo Code heavily to move fast while keeping the project modular and maintainable.

Kilo Code helped with:

  • CLI scaffolding and command iteration
  • Rule module implementation and refactors
  • Terminal UX polish
  • Fix patch generation logic
  • Cleanup and TypeScript error resolution

This made it possible to ship a real, usable developer tool (not just a prototype) within the hackathon time limit.

Challenges I ran into

The biggest challenge was balancing speed and quality.

At first, the scanner/rule integration had an API mismatch, which caused rules to load incorrectly and return no findings. I refactored the rule system to a cleaner modular API so the scanner could run rules reliably per file/context.

I also had to be careful with the fix engine:

  • Some fixes can be safely auto-applied (like creating .env.example)
  • Others should be patch suggestions only (like Docker config or large logging changes)

Another challenge was keeping the output useful for both:

  • Humans in the terminal
  • CI pipelines and automation (--json, exit codes)

What I learned

This project reinforced that developer tools win when they are:

  1. Fast
  2. Practical
  3. Explainable
  4. Easy to integrate

I also learned that AI is most useful here when it prioritizes and explains what to fix, instead of trying to replace deterministic checks.

The combination of:

  • deterministic rules + scoring
  • AI-guided prioritization
  • CI enforcement

creates a much stronger workflow than any one of those alone.

What's next for ShipGuard

I want to continue ShipGuard as a developer reliability tool.

Planned next steps:

  • More framework-specific rules (Next.js, Express, Bun, etc.)
  • shipguard.config.json for team policies
  • GitHub App integration (PR comments / score reports)
  • Historical score tracking over time
  • More auto-fix recipes
  • VS Code integration

Long term, ShipGuard can evolve into a full workflow product for teams that want to reduce demo/deploy risk and ship more confidently.

Built With

Share this project:

Updates