selfguard 0.0.1 → 0.1.0

package/dist/semver.js

@@ -0,0 +1,65 @@
+/**
+ * Minimal SemVer 2.0.0 parser/comparator (no dependencies on purpose).
+ * Only what we need to evaluate OSV ranges for the npm ecosystem.
+ */
+const SEMVER_RE = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export function parse(input) {
+    if (typeof input !== "string" || input.length > 256)
+        return null;
+    const m = SEMVER_RE.exec(input.trim());
+    if (!m)
+        return null;
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    const patch = Number(m[3]);
+    if (![major, minor, patch].every(Number.isSafeInteger))
+        return null;
+    const pre = m[4]
+        ? m[4].split(".").map((id) => (/^\d+$/.test(id) && Number.isSafeInteger(Number(id)) ? Number(id) : id))
+        : [];
+    return { major, minor, patch, pre };
+}
+export function isValid(input) {
+    return parse(input) !== null;
+}
+function cmpNum(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function cmpIdent(a, b) {
+    const an = typeof a === "number";
+    const bn = typeof b === "number";
+    if (an && bn)
+        return cmpNum(a, b);
+    if (an)
+        return -1; // numeric identifiers have lower precedence
+    if (bn)
+        return 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function compareParsed(a, b) {
+    const core = cmpNum(a.major, b.major) || cmpNum(a.minor, b.minor) || cmpNum(a.patch, b.patch);
+    if (core !== 0)
+        return core;
+    // A version without pre-release has higher precedence than one with.
+    if (a.pre.length === 0 && b.pre.length === 0)
+        return 0;
+    if (a.pre.length === 0)
+        return 1;
+    if (b.pre.length === 0)
+        return -1;
+    const len = Math.min(a.pre.length, b.pre.length);
+    for (let i = 0; i < len; i++) {
+        const c = cmpIdent(a.pre[i], b.pre[i]);
+        if (c !== 0)
+            return c;
+    }
+    return cmpNum(a.pre.length, b.pre.length);
+}
+/** Compare two version strings. Throws if either is not valid SemVer. */
+export function compare(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa || !pb)
+        throw new Error(`invalid semver: ${!pa ? a : b}`);
+    return compareParsed(pa, pb);
+}

package/dist/setup.js

@@ -0,0 +1,233 @@
+/** `selfguard setup`: interactive wizard to choose where your repos live. */
+import { appendFileSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { candidateRoots, clampDepth, DEFAULT_DEPTH, loadConfig, MAX_DEPTH, normalizeDir, saveConfig } from "./config.js";
+import { discover, discoverAll } from "./discover.js";
+import { groupByPackage, paint, summarizeCounts, tildify, worstSeverity } from "./report.js";
+import { scanProjects } from "./scan.js";
+import { scheduleOn, scheduleStatus } from "./schedule.js";
+import { listRepos, saveRepo } from "./store.js";
+import { confirm, fitStart, isPrintable, readKeys, Screen, withSpinner } from "./tui.js";
+const out = process.stdout;
+/** Interactive folder picker. Resolves to the chosen roots, or null if cancelled. */
+async function pickRoots(initial, exclude) {
+    const c = paint(out);
+    const items = [];
+    const add = (path, selected, depth) => {
+        if (items.some((i) => i.path.toLowerCase() === path.toLowerCase()))
+            return;
+        items.push({ path, selected, depth, count: null, generation: 0 });
+    };
+    for (const r of initial)
+        add(r.path, true, r.depth);
+    for (const p of candidateRoots())
+        add(p, false, DEFAULT_DEPTH);
+    let cursor = 0; // items.length = the "add folder" row
+    let mode = "list";
+    let input = "";
+    let message = "";
+    const screen = new Screen();
+    const draw = () => {
+        const lines = [];
+        lines.push(c.bold("Where do you keep your code?"));
+        lines.push(c.dim("selfguard only looks inside the folders you pick, nothing else on your disk."));
+        lines.push("");
+        const width = Math.max(20, Math.min(50, (out.columns ?? 80) - 40));
+        items.forEach((it, i) => {
+            const pointer = i === cursor && mode === "list" ? c.cyan("›") : " ";
+            const box = it.selected ? c.green("[x]") : "[ ]";
+            const name = fitStart(tildify(it.path), width).padEnd(width);
+            const label = (it.count === null ? "counting…" : it.count === 0 ? "no JS projects" : `${it.count} project${it.count === 1 ? "" : "s"}`).padEnd(14);
+            const count = it.count ? label : c.dim(label);
+            lines.push(`${pointer} ${box} ${i === cursor ? c.bold(name) : name}  ${count} ${c.dim(`depth ${it.depth}`)}`);
+        });
+        const addRow = cursor === items.length && mode === "list";
+        lines.push(`${addRow ? c.cyan("›") : " "} ${c.cyan("+")} ${addRow ? c.bold("add another folder…") : "add another folder…"}`);
+        lines.push("");
+        if (mode === "input") {
+            lines.push(`${c.cyan("Folder:")} ${input}${c.inverseRed(" ")}`);
+            lines.push(c.dim("enter add · esc cancel · ~ = home"));
+        }
+        else {
+            lines.push(c.dim("↑/↓ move · space select · ←/→ depth · a add folder · enter continue · q quit"));
+        }
+        lines.push(message ? c.yellow(message) : "");
+        screen.render(lines);
+    };
+    const count = (it) => {
+        const gen = ++it.generation;
+        it.count = null;
+        discover(it.path, { depth: it.depth, exclude, isCancelled: () => it.generation !== gen }).then((found) => {
+            if (it.generation !== gen)
+                return;
+            it.count = found.length;
+            draw();
+        });
+    };
+    items.forEach(count);
+    draw();
+    return readKeys((key, finish) => {
+        message = "";
+        if (mode === "input") {
+            if (key.name === "escape") {
+                mode = "list";
+                input = "";
+            }
+            else if (key.name === "return" || key.name === "enter") {
+                const dir = normalizeDir(input);
+                if (!dir) {
+                    message = `Not a folder: ${input}`;
+                }
+                else if (dir === homedir() || dir === "/") {
+                    message = "Pick a more specific folder than your whole home directory.";
+                }
+                else {
+                    add(dir, true, DEFAULT_DEPTH);
+                    const it = items.find((i) => i.path === dir);
+                    it.selected = true;
+                    count(it);
+                    cursor = items.indexOf(it);
+                    mode = "list";
+                    input = "";
+                }
+            }
+            else if (key.name === "backspace") {
+                input = input.slice(0, -1);
+            }
+            else if (isPrintable(key) && input.length < 400) {
+                input += key.sequence;
+            }
+            draw();
+            return;
+        }
+        const it = items[cursor];
+        switch (key.name) {
+            case "up":
+            case "k":
+                cursor = cursor === 0 ? items.length : cursor - 1;
+                break;
+            case "down":
+            case "j":
+                cursor = cursor === items.length ? 0 : cursor + 1;
+                break;
+            case "space":
+                if (it)
+                    it.selected = !it.selected;
+                else
+                    mode = "input";
+                break;
+            case "left":
+            case "right":
+                if (it) {
+                    const d = clampDepth(it.depth + (key.name === "right" ? 1 : -1));
+                    if (d !== it.depth) {
+                        it.depth = d;
+                        count(it);
+                    }
+                    else {
+                        message = `Depth goes from 1 to ${MAX_DEPTH}.`;
+                    }
+                }
+                break;
+            case "a":
+                mode = "input";
+                break;
+            case "return":
+            case "enter":
+                if (!it && cursor === items.length) {
+                    mode = "input";
+                    break;
+                }
+                if (!items.some((i) => i.selected)) {
+                    message = "Select at least one folder (space), or press q to quit.";
+                    break;
+                }
+                screen.done();
+                finish(items.filter((i) => i.selected).map((i) => ({ path: i.path, depth: i.depth })));
+                return;
+            case "q":
+            case "escape":
+                screen.done();
+                finish(null);
+                return;
+        }
+        draw();
+    });
+}
+function hasZshHook() {
+    try {
+        return readFileSync(join(homedir(), ".zshrc"), "utf8").includes("selfguard init zsh");
+    }
+    catch {
+        return false;
+    }
+}
+function printScanSummary(outcomes) {
+    const c = paint(out);
+    const risky = outcomes
+        .filter((o) => o.record.findings.length > 0)
+        .sort((a, b) => b.record.findings.length - a.record.findings.length);
+    const unsupported = outcomes.filter((o) => o.record.error && o.record.findings.length === 0).length;
+    out.write(`\n${c.bold(`${outcomes.length} project(s) scanned.`)}\n`);
+    if (risky.length === 0)
+        out.write(`${c.green("✓")} no known vulnerabilities\n`);
+    for (const o of risky.slice(0, 10)) {
+        const w = worstSeverity(o.record.findings);
+        const color = w === "malicious" || w === "critical" || w === "high" ? c.red : c.yellow;
+        const pkgs = groupByPackage(o.record.findings).length;
+        out.write(`  ${color("●")} ${c.bold(tildify(o.record.path))}  ${pkgs} vulnerable pkg(s) ${c.dim(`(${summarizeCounts(o.record.findings)})`)}\n`);
+    }
+    if (risky.length > 10)
+        out.write(c.dim(`  …and ${risky.length - 10} more (selfguard status)\n`));
+    if (unsupported > 0)
+        out.write(c.dim(`  ${unsupported} project(s) skipped: no lockfile yet, or unreadable\n`));
+}
+export async function runSetup() {
+    const c = paint(out);
+    out.write(`\n${c.bold(c.cyan("selfguard setup"))}\n\n`);
+    const cfg = loadConfig();
+    const roots = await pickRoots(cfg.roots, cfg.exclude);
+    if (!roots) {
+        out.write("Cancelled, nothing changed.\n");
+        return 0;
+    }
+    saveConfig({ ...cfg, roots });
+    out.write(`${c.green("✓")} Saved ${roots.length} folder(s) to watch.\n\n`);
+    const projects = await withSpinner("Looking for projects…", () => discoverAll(roots, { exclude: cfg.exclude }));
+    const known = new Set(listRepos().map((r) => r.path));
+    const fresh = projects.filter((p) => !known.has(p.root));
+    out.write(`Found ${c.bold(String(projects.length))} project(s), ${c.bold(String(fresh.length))} not tracked yet.\n`);
+    for (const p of fresh.slice(0, 8))
+        out.write(c.dim(`  ${tildify(p.root)}\n`));
+    if (fresh.length > 8)
+        out.write(c.dim(`  …and ${fresh.length - 8} more\n`));
+    if (fresh.length > 0) {
+        out.write("\n");
+        if (await confirm(`Scan ${fresh.length} new project(s) now? (sends only package names+versions to OSV.dev)`)) {
+            const outcomes = await withSpinner(`Scanning ${fresh.length} project(s)…`, () => scanProjects(fresh));
+            for (const o of outcomes)
+                saveRepo(o.record);
+            printScanSummary(outcomes);
+        }
+    }
+    out.write("\n");
+    if (hasZshHook()) {
+        out.write(`${c.green("✓")} Shell hook already in ~/.zshrc\n`);
+    }
+    else if (await confirm("Add the shell hook to ~/.zshrc (alerts when you cd into a project)?")) {
+        appendFileSync(join(homedir(), ".zshrc"), `\n# selfguard: dependency vulnerability alerts\neval "$(selfguard init zsh)"\n`);
+        out.write(`${c.green("✓")} Added. Open a new terminal to activate it.\n`);
+    }
+    if (process.platform === "darwin") {
+        if (scheduleStatus().loaded) {
+            out.write(`${c.green("✓")} Background sync already enabled\n`);
+        }
+        else if (await confirm("Check for new advisories every 6h in the background, with macOS notifications?")) {
+            scheduleOn(6 * 3600);
+            out.write(`${c.green("✓")} Enabled. New repos in your folders are picked up automatically too.\n`);
+        }
+    }
+    out.write(`\nDone. ${c.dim("selfguard status · selfguard setup (change folders) · selfguard --help")}\n`);
+    return 0;
+}

package/dist/store.js

@@ -0,0 +1,37 @@
+import { readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWrite, isObject, readJsonFile, sha256 } from "./fsutil.js";
+import { reposDir } from "./paths.js";
+export const findingKey = (f) => `${f.id}|${f.name}@${f.version}`;
+function recordFile(path) {
+    return join(reposDir(), `${sha256(path).slice(0, 40)}.json`);
+}
+export function loadRepo(path) {
+    const rec = readJsonFile(recordFile(path));
+    return rec && isObject(rec) && rec.schema === 1 && rec.path === path ? rec : null;
+}
+export function saveRepo(rec) {
+    atomicWrite(recordFile(rec.path), JSON.stringify(rec));
+}
+export function forgetRepo(path) {
+    const file = recordFile(path);
+    const existed = loadRepo(path) !== null;
+    rmSync(file, { force: true });
+    return existed;
+}
+export function listRepos() {
+    let files;
+    try {
+        files = readdirSync(reposDir()).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        const rec = readJsonFile(join(reposDir(), f));
+        if (rec && isObject(rec) && rec.schema === 1 && typeof rec.path === "string")
+            out.push(rec);
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}

package/dist/tui.js

@@ -0,0 +1,132 @@
+/**
+ * Tiny dependency-free terminal UI primitives: redraw-in-place rendering and
+ * raw key handling with guaranteed terminal restore.
+ */
+import { emitKeypressEvents } from "node:readline";
+const stdin = process.stdin;
+const stdout = process.stdout;
+export function isInteractive() {
+    return Boolean(stdin.isTTY && stdout.isTTY);
+}
+const ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+export function visibleLength(s) {
+    return s.replace(ANSI, "").length;
+}
+export function columns() {
+    return Math.max(40, stdout.columns ?? 80);
+}
+/** Truncate plain (uncolored) text to fit the terminal, keeping the end of paths visible. */
+export function fitStart(s, max) {
+    return s.length <= max ? s : `…${s.slice(s.length - max + 1)}`;
+}
+/** Redraws a block of lines in place. */
+export class Screen {
+    height = 0;
+    render(lines) {
+        const width = columns() - 1;
+        // Never let a line wrap: wrapped lines would break the in-place redraw.
+        const safe = lines.map((l) => (visibleLength(l) > width ? `${l.replace(ANSI, "").slice(0, width - 1)}…` : l));
+        let out = "";
+        if (this.height > 0)
+            out += `\x1b[${this.height}A`;
+        out += "\r\x1b[J";
+        out += safe.join("\n");
+        this.height = safe.length - 1;
+        stdout.write(out);
+    }
+    /** Leave the last frame on screen and move below it. */
+    done() {
+        stdout.write("\n");
+        this.height = 0;
+    }
+    clear() {
+        if (this.height > 0)
+            stdout.write(`\x1b[${this.height}A`);
+        stdout.write("\r\x1b[J");
+        this.height = 0;
+    }
+}
+let restoreInstalled = false;
+function restoreTerminal() {
+    try {
+        if (stdin.isTTY)
+            stdin.setRawMode(false);
+    }
+    catch {
+        /* ignore */
+    }
+    stdout.write("\x1b[?25h"); // show cursor
+}
+/**
+ * Feed raw keypresses to `onKey` until it calls `finish(value)`.
+ * Ctrl+C always exits cleanly with the terminal restored.
+ */
+export function readKeys(onKey) {
+    if (!restoreInstalled) {
+        process.on("exit", restoreTerminal);
+        restoreInstalled = true;
+    }
+    emitKeypressEvents(stdin);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdout.write("\x1b[?25l"); // hide cursor
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            stdin.off("keypress", handler);
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdout.write("\x1b[?25h");
+        };
+        const handler = (str, key) => {
+            const k = { ...(key ?? {}), ...(str !== undefined ? { sequence: str } : {}) };
+            if (k.ctrl && k.name === "c") {
+                cleanup();
+                stdout.write("\n");
+                process.exit(130);
+            }
+            onKey(k, (value) => {
+                cleanup();
+                resolve(value);
+            });
+        };
+        stdin.on("keypress", handler);
+    });
+}
+/** Single-key yes/no question. Enter picks the default. */
+export async function confirm(question, def = true) {
+    const hint = def ? "[Y/n]" : "[y/N]";
+    stdout.write(`${question} ${hint} `);
+    const answer = await readKeys((key, finish) => {
+        if (key.name === "return" || key.name === "enter")
+            finish(def);
+        else if (key.name === "y")
+            finish(true);
+        else if (key.name === "n" || key.name === "escape")
+            finish(false);
+    });
+    stdout.write(`${answer ? "yes" : "no"}\n`);
+    return answer;
+}
+/** Is this a printable character we can insert into a text field? */
+export function isPrintable(key) {
+    const s = key.sequence;
+    return !key.ctrl && !key.meta && typeof s === "string" && s.length === 1 && s >= " " && s !== "\x7f";
+}
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Show a spinner with a message while `work` runs. */
+export async function withSpinner(message, work) {
+    if (!stdout.isTTY)
+        return work();
+    let i = 0;
+    stdout.write("\x1b[?25l");
+    const timer = setInterval(() => {
+        stdout.write(`\r${FRAMES[i++ % FRAMES.length]} ${message}`);
+    }, 80);
+    try {
+        return await work();
+    }
+    finally {
+        clearInterval(timer);
+        stdout.write("\r\x1b[K\x1b[?25h");
+    }
+}

package/dist/version.js

@@ -0,0 +1,2 @@
+// Kept in sync with package.json by hand (avoids reading files at runtime).
+export const VERSION = "0.1.0";

package/package.json

@@ -1,8 +1,49 @@
 {
   "name": "selfguard",
-  "version": "0.0.1",
-  "description": "Name reserved for selfguard: local-first guard for the dependencies of every JS repo you work on. First release coming soon.",
+  "version": "0.1.0",
+  "description": "Local-first guard that watches every JS repo you work on and alerts you about vulnerable or malicious dependencies.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/josseed/selfguard.git" },
-  "homepage": "https://github.com/josseed/selfguard#readme"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josseed/selfguard.git"
+  },
+  "homepage": "https://github.com/josseed/selfguard#readme",
+  "bugs": {
+    "url": "https://github.com/josseed/selfguard/issues"
+  },
+  "type": "module",
+  "bin": {
+    "selfguard": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json && node scripts/postbuild.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "security",
+    "vulnerabilities",
+    "osv",
+    "npm",
+    "supply-chain",
+    "audit",
+    "cli"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2"
+  }
 }