pqcheck 0.1.1 → 0.2.0

package/README.md

@@ -55,20 +55,45 @@ $ npx pqcheck chase.com
 ## Usage
 
 ```
-npx pqcheck <domain>           Scan and print human-readable report
-npx pqcheck <domain> --json    Output raw JSON for piping / scripting
-npx pqcheck --help             Show all options
-npx pqcheck --version          Show version
+npx pqcheck <domain>                      Scan and print human-readable report
+npx pqcheck <domain> --format json        Output raw JSON for piping / scripting
+npx pqcheck <domain> --threshold 7        Exit 2 if score ≥ 7 (CI gate)
+npx pqcheck <domain> --quiet              Print only the numeric score
+npx pqcheck --help                        Show all options
+npx pqcheck --version                     Show version
 ```
 
-The `--json` flag is useful for integrating into CI / monitoring tools:
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success — score below threshold (or no threshold set) |
+| 1    | Usage / network / scan error |
+| 2    | Score met or exceeded `--threshold` |
+
+### CI integration
+
+The `--threshold` flag turns `pqcheck` into a quantum-risk gate for any pipeline:
+
+```yaml
+# .github/workflows/quantum-risk-gate.yml
+- name: Check public-surface quantum-decryption risk
+  run: npx pqcheck mycompany.com --threshold 7
+```
+
+If the score is 7.0 or higher, the step fails and the PR can't merge.
+
+For finer control, combine `--quiet` with shell logic:
+
+```bash
+SCORE=$(npx pqcheck mybank.com --quiet)
+echo "Public surface blast radius: $SCORE / 10"
+```
+
+Or grab the full JSON for richer analysis:
 
 ```bash
-# In a GitHub Actions workflow:
-SCORE=$(npx pqcheck mybank.com --json | jq '.score')
-if (( $(echo "$SCORE > 7" | bc -l) )); then
-  echo "Score regressed above threshold"; exit 1
-fi
+npx pqcheck mybank.com --format json | jq '.findings[] | select(.severity=="high")'
 ```
 
 ## Web version

package/bin/pqcheck.js

@@ -7,7 +7,7 @@
 // =============================================================================
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://quantapact.com";
-const VERSION = "0.1.1";
+const VERSION = "0.2.0";
 
 const ANSI = {
   reset:   "\x1b[0m",
@@ -41,16 +41,22 @@ async function main() {
     process.exit(1);
   }
 
-  const json = args.includes("--json");
+  const quiet = args.includes("--quiet") || args.includes("-q");
+  const format = parseFormat(args);
+  const threshold = parseThreshold(args);
+  if (threshold === "invalid") {
+    console.error(color("red", "error: --threshold requires a number 0-10"));
+    process.exit(1);
+  }
 
-  process.stderr.write(color("dim", `Scanning ${domain} ...`));
+  if (!quiet) process.stderr.write(color("dim", `Scanning ${domain} ...`));
   let report;
   try {
     const resp = await fetch(`${API_BASE}/api/scan?domain=${encodeURIComponent(domain)}`, {
       method: "GET",
       headers: { accept: "application/json", "user-agent": `pqcheck-cli/${VERSION}` },
     });
-    process.stderr.write("\r\x1b[K"); // clear "Scanning ..." line
+    if (!quiet) process.stderr.write("\r\x1b[K"); // clear "Scanning ..." line
     if (!resp.ok) {
       const errBody = await safeJSON(resp);
       console.error(color("red", `error: ${resp.status} ${errBody?.error || resp.statusText}`));
@@ -59,17 +65,45 @@ async function main() {
     }
     report = await resp.json();
   } catch (err) {
-    process.stderr.write("\r\x1b[K");
+    if (!quiet) process.stderr.write("\r\x1b[K");
     console.error(color("red", `error: ${err.message}`));
     process.exit(1);
   }
 
-  if (json) {
+  if (quiet) {
+    // Numeric score on stdout, nothing else. Suitable for piping.
+    console.log(typeof report.score === "number" ? report.score : "");
+  } else if (format === "json") {
     console.log(JSON.stringify(report, null, 2));
-    process.exit(0);
+  } else {
+    printReport(report);
   }
 
-  printReport(report);
+  // Threshold gating: exit 2 if score >= threshold (distinct from exit 1 = error)
+  if (threshold !== null && typeof report.score === "number" && report.score >= threshold) {
+    if (!quiet) {
+      console.error(color("red", `threshold breach: score ${report.score} >= ${threshold}`));
+    }
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+function parseFormat(args) {
+  if (args.includes("--json")) return "json"; // back-compat alias
+  const i = args.indexOf("--format");
+  if (i === -1) return "text";
+  const v = (args[i + 1] || "").toLowerCase();
+  return v === "json" ? "json" : "text";
+}
+
+function parseThreshold(args) {
+  const i = args.indexOf("--threshold");
+  if (i === -1) return null;
+  const raw = args[i + 1];
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 10) return "invalid";
+  return n;
 }
 
 function printReport(r) {
@@ -163,17 +197,29 @@ ${color("bold", "pqcheck")} ${color("dim", `v${VERSION}`)}
 Public Surface Blast Radius — quantum-decryption risk for any domain.
 
 ${color("bold", "Usage:")}
-  npx pqcheck <domain>           Scan and print human-readable report
-  npx pqcheck <domain> --json    Output raw JSON
+  npx pqcheck <domain>                       Scan and print human-readable report
+  npx pqcheck <domain> --format json         Output raw JSON
+  npx pqcheck <domain> --threshold 7         Exit 2 if score ≥ 7 (CI-friendly)
+  npx pqcheck <domain> --quiet               Print just the score, nothing else
 
 ${color("bold", "Options:")}
-  -h, --help        Show this help
-  -v, --version     Show version
-  --json            Print raw JSON output
+  -h, --help                Show this help
+  -v, --version             Show version
+  --format <text|json>      Output format (default: text)
+  --json                    Alias for --format json
+  --threshold <0-10>        Exit code 2 if score meets/exceeds this value
+  -q, --quiet               Print only the numeric score (pipe-friendly)
+
+${color("bold", "Exit codes:")}
+  0   success
+  1   usage / network / scan error
+  2   score met or exceeded --threshold
 
 ${color("bold", "Examples:")}
   npx pqcheck chase.com
-  npx pqcheck quantapact.com --json
+  npx pqcheck quantapact.com --format json
+  npx pqcheck mybank.com --threshold 7      ${color("dim", "# fail CI if exposed")}
+  echo "score: $(npx pqcheck mybank.com -q)"
 
 Backed by the patented Decryption Blast Radius methodology.
 ${color("violet", "https://quantapact.com")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Decryption Blast Radius scanner — find out how much of your data unlocks when quantum decryption arrives.",
   "keywords": [
     "post-quantum",