residoo 0.3.7 → 0.3.9

package/README.md

@@ -121,6 +121,18 @@ won't be built into the tool that writes it.
 - Redacts everything in its own output. You get a shape and a first/last-4
   preview, never the real value, including in `--json` mode. A decoded or
   rejoined secret is redacted exactly like a plain one.
+- On an interactive terminal, prints who it is and where it lives before
+  scanning starts (`residoo v0.3.9 · find secrets your AI coding agent left
+  on disk` plus the repo URL), then a live spinner naming the current file
+  as it scans. Every report also opens with the exact version and timestamp
+  it was run with (`residoo v0.3.9 · scanned 2026-01-01 12:00`; `--json`
+  carries the same as `residooVersion`/`scannedAt`), so a report pasted or
+  screenshotted later never leaves you guessing which build produced it.
+  When there are findings, the report closes with a "Next steps" pointer to
+  `--json` and `--seal`. All of the interactive chatter (the intro, the
+  spinner) goes to stderr only and is a complete no-op when stdout/stderr
+  are piped, redirected, or run in CI, so none of it can ever interleave
+  with `--json`/`--sarif` output.
 - `--sarif` emits SARIF 2.1.0 for GitHub code scanning's Security tab and
   inline pull-request annotations, the same format gitleaks/trufflehog/
   agentsweep already speak, so residoo's own Action and pre-commit hook plug
@@ -317,7 +329,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.3.7
+  - uses: dandovdub/residoo@v0.3.9
 ```
 
 As a pre-commit hook:
@@ -325,7 +337,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.7
+    rev: v0.3.9
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",

package/src/cli.js

@@ -5,7 +5,7 @@ const fs = require("fs");
 const crypto = require("crypto");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
-const { render, renderIntegrity, renderJson, renderSarif } = require("./report");
+const { render, renderIntegrity, renderJson, renderSarif, makeProgressReporter, printIntro } = require("./report");
 const { checkIntegrity } = require("./integrity");
 const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, ackFinding, renderRotation,
@@ -404,6 +404,7 @@ async function main(argv) {
   // mutated env var would leak past this one invocation and silently kill
   // color for a later call that never asked for that.
   const noColor = args.includes("--no-color");
+  printIntro(noColor);
 
   // Integrity runs by default: a scan that reports "no secrets leaked" while
   // a planted SessionStart hook sits ready to re-leak them next session is
@@ -494,7 +495,9 @@ async function main(argv) {
     return failOnFind && integrityWarnCount(integrity) > 0 ? 1 : 0;
   }
 
-  const result = await scan({ sources, includeNoisy, includeSuppressed });
+  const progress = makeProgressReporter(noColor);
+  const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress });
+  progress.stop();
   const integrity = wantsIntegrity ? runIntegrity() : null;
   const rotation = renderRotation(result.findings, acks);
   process.stdout.write((wantsSarif

package/src/report.js

@@ -29,6 +29,66 @@ function ageDays(mtimeMs) {
   return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86400000));
 }
 
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * Printed once, before scanning starts: what this is, what version, where
+ * it lives. Answers exactly the question a first-time (or every-time)
+ * reader has before results ever appear, without waiting for the report.
+ * Same TTY gate and same stream as the progress spinner below and for the
+ * same reason: stderr only, so a --json/--sarif consumer's stdout is
+ * untouched, and a complete no-op under redirection, piping, or CI.
+ */
+function printIntro(noColor) {
+  if (!process.stderr.isTTY) return;
+  const paint = makePaint(noColor);
+  const { version } = require("../package.json");
+  process.stderr.write(
+    paint(c.bold + c.cyan, `residoo v${version}`) +
+    paint(c.dim, " · find secrets your AI coding agent left on disk\n") +
+    paint(c.dim, "https://github.com/dandovdub/residoo\n\n")
+  );
+}
+
+/**
+ * A progress indicator for the scan phase, wired to scan()'s own
+ * onProgress callback. Writes to STDERR only, never stdout: --json/--sarif
+ * consumers pipe stdout into a parser, and a spinner corrupting that would
+ * be a much worse bug than not having one. Gated on stderr actually being a
+ * TTY, so it is a complete no-op under redirection, piping, or CI, exactly
+ * the contexts where carriage-return spam in a captured log would be
+ * useless or actively annoying, not merely invisible. Shows the actual
+ * current file (basename only, through the same safeBasename() every other
+ * displayed path in this report goes through — control bytes stripped,
+ * invisible code points made visible), not just a running count: real
+ * signal, not just motion, and genuinely useful if a scan stalls on one
+ * huge file. `stop()` clears the line so whatever prints next starts
+ * clean.
+ */
+function makeProgressReporter(noColor) {
+  if (!process.stderr.isTTY) return { onProgress: null, stop() {} };
+  const paint = makePaint(noColor);
+  let count = 0;
+  let lastWriteMs = 0;
+  let lastLineLen = 0;
+  let frame = 0;
+  const write = (s, visibleLen) => {
+    process.stderr.write("\r" + " ".repeat(lastLineLen) + "\r" + s);
+    lastLineLen = visibleLen;
+  };
+  const onProgress = ({ source, file }) => {
+    count++;
+    const now = Date.now();
+    if (now - lastWriteMs < 80) return; // throttled: avoid flicker on a fast scan
+    lastWriteMs = now;
+    frame = (frame + 1) % SPINNER_FRAMES.length;
+    const label = `scanning ${source}… ${count} file${count === 1 ? "" : "s"}  ${safeBasename(file)}`;
+    write(paint(c.bold + c.cyan, SPINNER_FRAMES[frame]) + " " + paint(c.dim, label), 2 + label.length);
+  };
+  const stop = () => { if (lastLineLen > 0) process.stderr.write("\r" + " ".repeat(lastLineLen) + "\r"); };
+  return { onProgress, stop };
+}
+
 // File NAMES are attacker-controllable text headed for a terminal: in
 // --project mode a hostile checkout chooses its own filenames, and a name
 // carrying raw ESC bytes could clear the screen or overwrite the findings
@@ -160,11 +220,23 @@ function renderIntegrity(integrity, { noColor = false } = {}) {
   return lines.join("\n");
 }
 
+/** "YYYY-MM-DD HH:MM" in local time — matches the user's own system clock, not UTC. */
+function localTimestamp(d) {
+  const p2 = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p2(d.getMonth() + 1)}-${p2(d.getDate())} ${p2(d.getHours())}:${p2(d.getMinutes())}`;
+}
+
 function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount = 0, distinctCounts = {}, unreadableFiles = [] }, { noColor = false, integrity = null, rotation = null } = {}) {
   const paint = makePaint(noColor);
   const lines = [];
   const push = (s = "") => lines.push(s);
 
+  // Which build ran and when, up front: a report pasted or screenshotted
+  // hours later (or a "why don't I see feature X" question) should never
+  // require asking "what version were you even running."
+  const { version } = require("../package.json");
+  push(paint(c.dim, `residoo v${version} · scanned ${localTimestamp(new Date())}`));
+
   const suppressedNote = suppressedCount > 0
     ? paint(c.dim, ` (${suppressedCount} more matched but looked like placeholder/example text; see --include-suppressed)`)
     : "";
@@ -255,9 +327,13 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
     push(renderIntegrity(integrity, { noColor }));
   }
 
+  push();
+  push(paint(c.bold, "Next steps:"));
+  push(`  residoo scan --json          ${paint(c.dim, "machine-readable output, full detail")}`);
+  push(`  residoo scan --seal          ${paint(c.dim, "encrypt the affected files into a local vault (originals untouched)")}`);
   push();
   push(paint(c.dim, "Values are redacted in this report (first/last 4 characters only). Nothing scanned"));
-  push(paint(c.dim, "here left your machine; residoo makes no network calls. Run with --json for full detail."));
+  push(paint(c.dim, "here left your machine; residoo makes no network calls."));
 
   return lines.join("\n");
 }
@@ -271,8 +347,11 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
 // way, since it is derived from already-redacted material and is what
 // "residoo ack" takes.
 function renderJson(result, integrity = null, rotation = null) {
+  const { version } = require("../package.json");
   return JSON.stringify(
     {
+      residooVersion: version,
+      scannedAt: new Date().toISOString(),
       summary: {
         findingCount: result.findings.length,
         filesScanned: result.filesScanned,
@@ -398,4 +477,4 @@ function renderSarif(result) {
   }, null, 2);
 }
 
-module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif };
+module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, makeProgressReporter, printIntro };