# samplebeacon

**Community CLI — catch mock data, fiction KPIs, and credential leaks before merge.**

[![npm version](https://img.shields.io/npm/v/samplebeacon)](https://www.npmjs.com/package/samplebeacon)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Community ($0):** unlimited local scans · JSON + text reports · gate policy (`--gate`) · GitHub Action + pre-commit hooks · zero runtime dependencies.

Hosted dashboard and cloud sync live at [simplebeacon.ai](https://simplebeacon.ai) (Cloud Teams / Enterprise).

## Why Samplebeacon

AI-assisted development produces repos full of:

- Inflated KPIs (`74.17% completion`, `47 features`)
- Hardcoded `-sample.json` paths in production code
- Demo credentials that look real
- Mock data shipped as if it were measured

Samplebeacon scans your codebase and **fails CI** when fiction tries to ship.

## Install

```bash
npm install -D samplebeacon
# or zero-install
npx samplebeacon init
npx samplebeacon hook install
```

## Quick start

```bash
npx samplebeacon init                  # auto-detects project layout
npx samplebeacon scan                  # scan and report (text)
npx samplebeacon scan --gate           # exit 1 on blocking issues
npx samplebeacon scan --format json --output .samplebeacon/report.json
npx samplebeacon hook install          # pre-commit gate
npx samplebeacon baseline sync         # sync Jest counts after green tests
```

### Profiles

```bash
npx samplebeacon init --profile minimal    # credentials + production-leak only
npx samplebeacon init --profile standard   # all rules, generic defaults
npx samplebeacon init --profile cascade    # ai-platform dashboard preset
```

## Commands

| Command | Description |
|---------|-------------|
| `samplebeacon init` | Create `.samplebeacon/config.json` and `baseline.json` |
| `samplebeacon scan` | Scan project; `--gate` exits 1 on blocking issues |
| `samplebeacon baseline sync` | Run Jest and write pass counts to baseline |
| `samplebeacon comment` | Post PR comment from JSON report |
| `samplebeacon assess` | Build customer assessment JSON from scan report |
| `samplebeacon hook install` | Write pre-commit or pre-push hook (Husky or `.git/hooks`) |

### Scan flags

| Flag | Description |
|------|-------------|
| `--path <dir>` | Project root (default: cwd) |
| `--config <file>` | Config path |
| `--format text\|json` | Output format |
| `--output <file>` | Write report to file |
| `--gate` | Fail when severities in `gate.failOn` are found |
| `--fail-on high,medium` | Override gate severities |
| `--with-jest` | Run tests and compare to baseline |
| `--verbose` | Show config warnings and scan paths |
| `--profile` | Force init profile |

## Rules

| Rule | Severity | Detects |
|------|----------|---------|
| `credentials` | high/medium | AWS keys, JWT, GitHub PATs, OpenAI keys, private keys |
| `json-schema` | high | Sample JSON violating page specs |
| `sample-consistency` | high | Cross-file KPI drift vs baseline |
| `roadmap` | medium | Legacy fiction roadmaps, oversized exports |
| `production-leak` | high/medium | Mock/sample paths in production code |
| `jest-baseline` | high | Jest pass count drift (optional, `--with-jest`) |

See [docs/RULES.md](docs/RULES.md) and [docs/CONFIG.md](docs/CONFIG.md).

**Go-to-market:** [docs/OUTREACH.md](docs/OUTREACH.md) · [Assessment report template](docs/examples/assessment-report-template.json) · [Production leak triage](docs/PRODUCTION-LEAK-TRIAGE.md)

## Complementary stack

```text
Snyk / GHAS     → known CVEs
SonarQube       → code smells, coverage
Samplebeacon    → fiction KPIs in sample JSON, mock paths in prod code, credential patterns
```

Run Samplebeacon in the same CI job as your existing security tools — it gates on different artifacts.

## GitHub Actions

Copy [examples/github-action/samplebeacon.yml](examples/github-action/samplebeacon.yml) to `.github/workflows/samplebeacon.yml`, or use the snippet below.

### Standalone repo

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: '20'
- run: npx samplebeacon init --profile minimal
- run: npx samplebeacon scan --gate --format json --output .samplebeacon/report.json
```

### Composite action

```yaml
- uses: ./ai-platform/action
  with:
    path: .
    fail-on: high
    post-comment: true
```

See [docs/GITHUB-ACTION-QUICKSTART.md](docs/GITHUB-ACTION-QUICKSTART.md), [docs/PRE-COMMIT.md](docs/PRE-COMMIT.md), and [docs/CI.md](docs/CI.md).

## Starter template

Copy [examples/starter/.samplebeacon/](examples/starter/.samplebeacon/) into your repo for a minimal working config.

## Documentation

- [Configuration](docs/CONFIG.md)
- [Pre-commit hooks](docs/PRE-COMMIT.md)
- [CI Integration](docs/CI.md)
- [Rules reference](docs/RULES.md)
- [Marketing claims (verified)](docs/MARKETING.md)
- [Naming & branding research](docs/NAMING.md)

## Publish

```bash
cd packages/samplebeacon-cli
npm test
npm publish --access public
```

## Development

```bash
cd packages/samplebeacon-cli
npm test
node bin/samplebeacon.js scan --path ../.. --gate
```

## License

MIT
