residoo 0.3.8 → 0.3.9

package/README.md

@@ -121,13 +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.
-- Every report opens with the exact version and timestamp it was run with
-  (`residoo v0.3.8 · 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. On an
-  interactive terminal, a lightweight spinner shows scan progress on
-  stderr; it is a complete no-op when stdout/stderr are piped, redirected,
-  or run in CI, so it can never interleave with `--json`/`--sarif` output.
+- 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
@@ -324,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.8
+  - uses: dandovdub/residoo@v0.3.9
 ```
 
 As a pre-commit hook:
@@ -332,7 +337,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.8
+    rev: v0.3.9
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.8",
+  "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, makeProgressReporter } = 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,7 @@ async function main(argv) {
     return failOnFind && integrityWarnCount(integrity) > 0 ? 1 : 0;
   }
 
-  const progress = makeProgressReporter();
+  const progress = makeProgressReporter(noColor);
   const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress });
   progress.stop();
   const integrity = wantsIntegrity ? runIntegrity() : null;

package/src/report.js

@@ -32,35 +32,58 @@ function ageDays(mtimeMs) {
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 /**
- * A minimal progress indicator for the scan phase, wired to scan()'s own
+ * 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. `stop()` clears the
- * line so whatever prints next (the report, on stdout, is unaffected
- * either way since this never touched stdout, but a plain-text stderr
- * reader watching live should not see a stale line lingering) starts
+ * 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() {
+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) => {
+  const write = (s, visibleLen) => {
     process.stderr.write("\r" + " ".repeat(lastLineLen) + "\r" + s);
-    lastLineLen = s.length;
+    lastLineLen = visibleLen;
   };
-  const onProgress = ({ source }) => {
+  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;
-    write(`${SPINNER_FRAMES[frame]} scanning… ${count} file${count === 1 ? "" : "s"} checked (${source})`);
+    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 };
@@ -304,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");
 }
@@ -450,4 +477,4 @@ function renderSarif(result) {
   }, null, 2);
 }
 
-module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, makeProgressReporter };
+module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, makeProgressReporter, printIntro };