selfguard 0.1.0 → 0.2.0

package/dist/events.js

@@ -0,0 +1,61 @@
+/**
+ * Append-only activity log (~/.selfguard/events.jsonl): what appeared, what got fixed and
+ * which reminders were sent. Feeds the dashboard's activity feed. Local only.
+ */
+import { appendFileSync, readFileSync, statSync } from "node:fs";
+import { atomicWrite, ensureDir, isObject } from "./fsutil.js";
+import { eventsFile, stateRoot } from "./paths.js";
+import { groupByPackage } from "./report.js";
+const MAX_BYTES = 512 * 1024;
+const KEEP_LINES = 1000;
+const MAX_PACKAGES = 20;
+export function eventPackages(findings) {
+    const groups = groupByPackage(findings);
+    return {
+        total: groups.length,
+        packages: groups.slice(0, MAX_PACKAGES).map((g) => ({ name: g.name, version: g.version, severity: g.worst })),
+    };
+}
+export function appendEvents(events) {
+    if (events.length === 0)
+        return;
+    ensureDir(stateRoot());
+    const file = eventsFile();
+    appendFileSync(file, events.map((e) => `${JSON.stringify(e)}\n`).join(""), { mode: 0o600 });
+    try {
+        if (statSync(file).size > MAX_BYTES) {
+            const lines = readFileSync(file, "utf8").split("\n").filter(Boolean);
+            atomicWrite(file, `${lines.slice(-KEEP_LINES).join("\n")}\n`);
+        }
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Most recent events first. */
+export function readEvents(limit = 100) {
+    let text;
+    try {
+        text = readFileSync(eventsFile(), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0 && out.length < limit; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (isObject(e) && typeof e.at === "string" && typeof e.kind === "string" && Array.isArray(e.packages)) {
+                out.push(e);
+            }
+        }
+        catch {
+            /* skip corrupt line */
+        }
+    }
+    return out;
+}

package/dist/guide.js

@@ -19,14 +19,21 @@ project code or package managers.
 - repo groups: git worktrees and separate clones of the same repo (same remote + same subfolder) are
   grouped. status returns "repos" (grouped, with each checkout's branch) and "projects" (flat).
   A finding usually needs fixing once on the main branch; mention branches that are worse.
+- active: a checkout with git activity in the last N days (default 30). Inactive checkouts are listed
+  but only alert for malicious packages. Repo-level counts in status cover active checkouts.
+- attention: what the user's daily reminder is about: malicious packages, critical findings outside dev
+  dependencies, and high findings in direct dependencies, judged on each repo's main checkout.
 
 ## Use it via MCP (preferred) or the CLI with --json
 | Goal | MCP tool | CLI |
 |---|---|---|
+| What to fix first | selfguard_attention | selfguard remind --dry-run --json |
 | Overview of all projects | selfguard_status | selfguard status --json |
 | Findings for one project (cached) | selfguard_project_report | selfguard report <dir> --json |
 | Re-scan one project now | selfguard_scan | selfguard scan <dir> --json |
 | Check everything for new advisories | selfguard_sync | selfguard sync --json |
+| Re-check projects whose lockfile changed | selfguard_check | selfguard check --json |
+| Alert settings | (CLI only) | selfguard settings [--remind daily|weekly|off] [--active-days N] --json |
 | Is package X used anywhere? | selfguard_where | selfguard where <pkg> --json |
 | Explain an advisory | selfguard_vulnerability | selfguard vuln <id> --json |
 | Watched folders | selfguard_roots_list / _add / _remove | selfguard roots [add|remove] --json |
@@ -37,13 +44,14 @@ CLI conventions: with --json, stdout is a single JSON document; errors are {"err
 Exit codes: 0 ok, 1 scan found vulnerabilities, 2 usage or runtime error. No prompts without a TTY.
 
 ## How to help the user
-1. Start with status; prioritize malicious, then critical/high, and direct over transitive deps.
+1. Start with attention (or status); prioritize malicious, then critical/high, and direct over transitive deps.
 2. Malicious package: tell the user to remove it immediately and rotate credentials that were
    available on that machine/CI (npm tokens, cloud keys, SSH keys). Do not just upgrade it.
 3. Direct dependency: propose bumping it to >= upgradeTo in package.json, then the user runs the install.
 4. Transitive dependency: find which direct dependency pulls it in; propose upgrading that one, or an
    npm "overrides" entry pinning the package to >= upgradeTo.
-5. After the user installs, run selfguard_scan on the project to verify.
+5. After the user installs, run selfguard_check (or selfguard_scan on the project) to verify.
+   The user can also follow everything in the local dashboard: selfguard ui.
 6. Dev-only findings matter less for production but still matter for developer machines and CI.
 
 ## Rules

package/dist/mcp.js

@@ -6,7 +6,9 @@
  * names are third-party data; tool descriptions tell the model to treat them as such.
  */
 import { createInterface } from "node:readline";
+import { needsAttention } from "./alerts.js";
 import * as api from "./api.js";
+import { groupByPackage } from "./report.js";
 import { GUIDE } from "./guide.js";
 import { VERSION } from "./version.js";
 const KNOWN_PROTOCOLS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
@@ -29,11 +31,37 @@ export const TOOLS = [
     {
         name: "selfguard_status",
         title: "List tracked projects",
-        description: "Risk overview of everything selfguard tracks. `repos` groups git worktrees and clones of the same repository (each checkout with its branch and counts); `projects` is the flat list. Reads local state only, no network. Start here.",
+        description: "Risk overview of everything selfguard tracks. `repos` groups git worktrees and clones of the same repository (each checkout with its branch, counts and whether it is `active`: git activity in the last N days); `projects` is the flat list. Repo counts cover active checkouts. Reads local state only, no network. Start here (or with selfguard_attention for the short list).",
         inputSchema: obj({ onlyVulnerable: { type: "boolean", description: "Only projects with findings." } }),
         annotations: { readOnlyHint: true, openWorldHint: false },
         run: (a) => api.getStatus({ onlyVulnerable: bool(a, "onlyVulnerable") ?? false }),
     },
+    {
+        name: "selfguard_attention",
+        title: "What needs attention",
+        description: "The short list the user's reminders are about: per repo, the serious findings (malicious packages, critical vulnerabilities outside dev dependencies, high ones in direct dependencies) on the checkout that represents it (the active main clone, or the most recently active checkout). Inactive checkouts are excluded. No network. Use it to decide what to fix first." +
+            UNTRUSTED,
+        inputSchema: obj({}),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        run: () => ({
+            repos: api
+                .getAttention()
+                .map((r) => ({
+                repo: r.label,
+                path: r.path,
+                branch: r.branch,
+                packages: groupByPackage(r.findings.filter(needsAttention)).map((g) => ({
+                    name: g.name,
+                    version: g.version,
+                    worstSeverity: g.worst,
+                    direct: g.direct,
+                    upgradeTo: g.worst === "malicious" ? null : (g.upgradeTo ?? null),
+                    advisories: g.findings.map((f) => f.id),
+                })),
+            }))
+                .filter((r) => r.packages.length > 0),
+        }),
+    },
     {
         name: "selfguard_project_report",
         title: "Project vulnerability report",
@@ -63,6 +91,14 @@ export const TOOLS = [
             return rest;
         },
     },
+    {
+        name: "selfguard_check",
+        title: "Re-check changed lockfiles",
+        description: "Re-scan only the tracked projects whose lockfile changed since their last scan (after installs, git pull or branch switches). Fast; use it to verify a fix instead of a full sync.",
+        inputSchema: obj({}),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        run: () => api.check({ notify: false }),
+    },
     {
         name: "selfguard_where",
         title: "Where is a package used",

package/dist/paths.js

@@ -11,3 +11,6 @@ export const reposDir = () => join(stateRoot(), "repos");
 export const vulnCacheDir = () => join(stateRoot(), "cache", "vulns");
 export const locksDir = () => join(stateRoot(), "locks");
 export const logFile = () => join(stateRoot(), "selfguard.log");
+export const eventsFile = () => join(stateRoot(), "events.jsonl");
+export const stateFile = () => join(stateRoot(), "state.json");
+export const uiFile = () => join(stateRoot(), "ui.json");

package/dist/repoid.js

@@ -24,6 +24,19 @@ function readSmall(file) {
             closeSync(fd);
     }
 }
+/** Newest mtime among this checkout's own git files (not the shared ones, like FETCH_HEAD). */
+function lastActivityOf(gitDir) {
+    let newest = 0;
+    for (const f of ["HEAD", "index", join("logs", "HEAD")]) {
+        try {
+            newest = Math.max(newest, statSync(join(gitDir, f)).mtimeMs);
+        }
+        catch {
+            /* missing */
+        }
+    }
+    return newest > 0 ? new Date(newest).toISOString() : null;
+}
 function isDir(p) {
     try {
         return statSync(p).isDirectory();
@@ -114,6 +127,18 @@ export function repoIdentity(projectRoot) {
                 worktree = true;
             }
         }
+        if (gitDir && worktree && !isDir(gitDir)) {
+            // The main repository was deleted: this folder is a leftover, not part of any repo.
+            const sub = relative(dir, resolve(projectRoot)).split(sep).join("/");
+            return {
+                key: `orphan:${dir}${sub ? `#${sub}` : ""}`,
+                label: `${basename(dir)}${sub ? `/${sub}` : ""} (orphaned worktree)`,
+                branch: null,
+                worktree: true,
+                orphaned: true,
+                lastActivity: null,
+            };
+        }
         if (gitDir) {
             // Linked worktrees point at <common>/.git/worktrees/<name>; "commondir" leads back.
             const commondir = worktree ? readSmall(join(gitDir, "commondir"))?.trim() : undefined;
@@ -134,6 +159,7 @@ export function repoIdentity(projectRoot) {
                 label: sub ? `${repoName}/${sub}` : repoName,
                 branch: branchFrom(readSmall(join(gitDir, "HEAD"))),
                 worktree,
+                lastActivity: lastActivityOf(gitDir),
             };
         }
         const parent = dirname(dir);

package/dist/scan.js

@@ -4,6 +4,7 @@ import { sha256 } from "./fsutil.js";
 import { isSupported, parseLockfile } from "./lockfile/index.js";
 import { evaluate, severityOf, severityRank } from "./match.js";
 import { getVulns, queryBatch } from "./osv.js";
+import { repoIdentity } from "./repoid.js";
 import { clean } from "./sanitize.js";
 import { findingKey, loadRepo } from "./store.js";
 const MAX_LOCKFILE_BYTES = 100 * 1024 * 1024;
@@ -51,6 +52,7 @@ function inventory(project) {
         deps: [],
         skipped: 0,
         findings: [],
+        branch: repoIdentity(project.root)?.branch ?? null,
     };
     if (!project.lockfile || !project.lockType) {
         record.error = "no lockfile found (run your package manager's install to create one)";
@@ -121,6 +123,26 @@ function buildFindings(deps, refsPerDep, vulns, previous, now) {
     }
     return findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity) || Number(b.direct) - Number(a.direct) || a.name.localeCompare(b.name));
 }
+const SEEN_TTL_MS = 180 * 24 * 60 * 60 * 1000;
+const SEEN_MAX = 5000;
+/** Remember every finding this checkout has had recently, on any branch. */
+function updateSeen(previous, findings, now) {
+    const seen = Object.create(null);
+    const cutoff = Date.parse(now) - SEEN_TTL_MS;
+    for (const [k, at] of Object.entries(previous?.seen ?? {})) {
+        if (typeof at === "string" && Date.parse(at) >= cutoff)
+            seen[k] = at;
+    }
+    for (const f of previous?.findings ?? [])
+        seen[findingKey(f)] ??= previous?.scannedAt ?? now;
+    for (const f of findings)
+        seen[findingKey(f)] = now;
+    const entries = Object.entries(seen);
+    if (entries.length <= SEEN_MAX)
+        return seen;
+    entries.sort((a, b) => b[1].localeCompare(a[1]));
+    return Object.fromEntries(entries.slice(0, SEEN_MAX));
+}
 /**
  * Scan one or many projects with a single deduplicated OSV query.
  * Records are returned, not saved: the caller decides.
@@ -155,14 +177,21 @@ export async function scanProjects(projects) {
             record.error = networkError;
             record.findings = previous?.findings ?? [];
             record.scannedAt = previous?.scannedAt ?? null;
-            return { record, newFindings: [], firstScan: previous === null };
+            record.seen = previous?.seen ?? {};
+            return { record, newFindings: [], resolvedFindings: [], firstScan: previous === null };
         }
         if (!record.error) {
             record.findings = buildFindings(record.deps, refsPerDep, vulns, previous, now);
             record.scannedAt = now;
         }
         const before = new Set((previous?.findings ?? []).map(findingKey));
-        const newFindings = record.findings.filter((f) => !before.has(findingKey(f)));
-        return { record, newFindings, firstScan: previous === null };
+        const history = previous?.seen ?? {};
+        const newFindings = record.findings.filter((f) => !before.has(findingKey(f)) && !Object.hasOwn(history, findingKey(f)));
+        const after = new Set(record.findings.map(findingKey));
+        // Only a successful scan on the same branch can say something was fixed.
+        const sameBranch = previous?.branch === undefined || previous.branch === record.branch;
+        const resolvedFindings = previous && !record.error && sameBranch ? previous.findings.filter((f) => !after.has(findingKey(f))) : [];
+        record.seen = updateSeen(previous, record.findings, now);
+        return { record, newFindings, resolvedFindings, firstScan: previous === null };
     });
 }

package/dist/schedule.js

@@ -1,13 +1,21 @@
-/** Periodic `selfguard sync` via a per-user launchd agent (macOS). */
+/**
+ * Background work via per-user launchd agents (macOS):
+ * - dev.selfguard.sync: `selfguard sync` every N hours (discovery, new advisories, reminders);
+ * - dev.selfguard.watch: `selfguard check` as soon as a lockfile of an active checkout changes
+ *   (git pull, installs, merges), so fixes and new risks show up in seconds.
+ */
 import { execFileSync } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { join } from "node:path";
 import { atomicWrite } from "./fsutil.js";
 import { cliEntry } from "./hook.js";
 import { logFile } from "./paths.js";
-const LABEL = "dev.selfguard.sync";
-const plistPath = () => join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+const SYNC_LABEL = "dev.selfguard.sync";
+const WATCH_LABEL = "dev.selfguard.watch";
+/** launchd watches each path with a kqueue descriptor; keep the set bounded. */
+export const MAX_WATCH_PATHS = 200;
+const plistPath = (label) => join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
 const domain = () => `gui/${userInfo().uid}`;
 function xml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -25,58 +33,110 @@ function assertMac() {
     if (process.platform !== "darwin")
         throw new Error("scheduling is only implemented for macOS (launchd) for now");
 }
-export function scheduleOn(seconds) {
-    assertMac();
-    const args = [process.execPath, cliEntry(), "sync", "--background"];
-    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+/** Plist for one of our agents. Pure: tested directly. */
+export function agentPlist(label, args, trigger, log) {
+    const triggerXml = "interval" in trigger
+        ? `  <key>StartInterval</key><integer>${trigger.interval}</integer>\n  <key>RunAtLoad</key><true/>`
+        : `  <key>WatchPaths</key>\n  <array>\n${trigger.watch.map((p) => `    <string>${xml(p)}</string>`).join("\n")}\n  </array>\n  <key>ThrottleInterval</key><integer>15</integer>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-  <key>Label</key><string>${LABEL}</string>
+  <key>Label</key><string>${xml(label)}</string>
   <key>ProgramArguments</key>
   <array>
 ${args.map((a) => `    <string>${xml(a)}</string>`).join("\n")}
   </array>
-  <key>StartInterval</key><integer>${seconds}</integer>
-  <key>RunAtLoad</key><true/>
+${triggerXml}
   <key>ProcessType</key><string>Background</string>
   <key>LowPriorityIO</key><true/>
-  <key>StandardOutPath</key><string>${xml(logFile())}</string>
-  <key>StandardErrorPath</key><string>${xml(logFile())}</string>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
 </dict>
 </plist>
 `;
+}
+function unload(label) {
     try {
-        execFileSync("/bin/launchctl", ["bootout", `${domain()}/${LABEL}`], { stdio: "ignore" });
+        execFileSync("/bin/launchctl", ["bootout", `${domain()}/${label}`], { stdio: "ignore" });
     }
     catch {
         /* not loaded */
     }
-    atomicWrite(plistPath(), plist);
-    execFileSync("/bin/launchctl", ["bootstrap", domain(), plistPath()], { stdio: "ignore" });
-    return plistPath();
 }
-export function scheduleOff() {
+function install(label, plist) {
+    unload(label);
+    atomicWrite(plistPath(label), plist);
+    execFileSync("/bin/launchctl", ["bootstrap", domain(), plistPath(label)], { stdio: "ignore" });
+}
+function isLoaded(label) {
+    try {
+        execFileSync("/bin/launchctl", ["print", `${domain()}/${label}`], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function scheduleOn(seconds, watchPaths) {
     assertMac();
+    install(SYNC_LABEL, agentPlist(SYNC_LABEL, [process.execPath, cliEntry(), "sync", "--background"], { interval: seconds }, logFile()));
+    updateWatcher(watchPaths, { force: true });
+    return plistPath(SYNC_LABEL);
+}
+/**
+ * (Re)install the lockfile watcher with these paths, only when the schedule is on and the
+ * path set changed. Never call it from the watcher's own run: unloading would kill it.
+ */
+export function updateWatcher(paths, opts = {}) {
+    if (process.platform !== "darwin" || process.env.SELFGUARD_NO_LAUNCHD === "1")
+        return { watching: 0, changed: false };
+    if (!opts.force && !existsSync(plistPath(SYNC_LABEL)))
+        return { watching: 0, changed: false };
+    const list = [...new Set(paths)].slice(0, MAX_WATCH_PATHS);
+    if (list.length === 0) {
+        const had = existsSync(plistPath(WATCH_LABEL));
+        unload(WATCH_LABEL);
+        rmSync(plistPath(WATCH_LABEL), { force: true });
+        return { watching: 0, changed: had };
+    }
+    const plist = agentPlist(WATCH_LABEL, [process.execPath, cliEntry(), "check", "--background"], { watch: list }, logFile());
+    let current = "";
     try {
-        execFileSync("/bin/launchctl", ["bootout", `${domain()}/${LABEL}`], { stdio: "ignore" });
+        current = readFileSync(plistPath(WATCH_LABEL), "utf8");
     }
     catch {
-        /* not loaded */
+        /* not installed */
+    }
+    if (current === plist && isLoaded(WATCH_LABEL))
+        return { watching: list.length, changed: false };
+    install(WATCH_LABEL, plist);
+    return { watching: list.length, changed: true };
+}
+export function scheduleOff() {
+    assertMac();
+    let existed = false;
+    for (const label of [SYNC_LABEL, WATCH_LABEL]) {
+        unload(label);
+        existed = existsSync(plistPath(label)) || existed;
+        rmSync(plistPath(label), { force: true });
     }
-    const existed = existsSync(plistPath());
-    rmSync(plistPath(), { force: true });
     return existed;
 }
 export function scheduleStatus() {
     assertMac();
-    let loaded = false;
+    let paths = 0;
     try {
-        execFileSync("/bin/launchctl", ["print", `${domain()}/${LABEL}`], { stdio: "ignore" });
-        loaded = true;
+        const section = /<key>WatchPaths<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(readFileSync(plistPath(WATCH_LABEL), "utf8"));
+        paths = section?.[1]?.match(/<string>/g)?.length ?? 0;
     }
     catch {
-        loaded = false;
+        paths = 0;
     }
-    return { installed: existsSync(plistPath()), loaded, plist: plistPath() };
+    return {
+        installed: existsSync(plistPath(SYNC_LABEL)),
+        loaded: isLoaded(SYNC_LABEL),
+        plist: plistPath(SYNC_LABEL),
+        watcher: { installed: existsSync(plistPath(WATCH_LABEL)), loaded: isLoaded(WATCH_LABEL), paths },
+    };
 }

package/dist/setup.js

@@ -7,6 +7,8 @@ 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 { watchTargets } from "./api.js";
+import { announce } from "./announce.js";
 import { listRepos, saveRepo } from "./store.js";
 import { confirm, fitStart, isPrintable, readKeys, Screen, withSpinner } from "./tui.js";
 const out = process.stdout;
@@ -208,6 +210,7 @@ export async function runSetup() {
             const outcomes = await withSpinner(`Scanning ${fresh.length} project(s)…`, () => scanProjects(fresh));
             for (const o of outcomes)
                 saveRepo(o.record);
+            await announce(outcomes, { notify: false });
             printScanSummary(outcomes);
         }
     }
@@ -223,11 +226,11 @@ export async function runSetup() {
         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`);
+        else if (await confirm("Watch your repos in the background (macOS notifications, daily reminder of serious issues)?")) {
+            scheduleOn(6 * 3600, watchTargets());
+            out.write(`${c.green("✓")} Enabled. Lockfile changes are checked right away; new repos are picked up every 6h.\n`);
         }
     }
-    out.write(`\nDone. ${c.dim("selfguard status · selfguard setup (change folders) · selfguard --help")}\n`);
+    out.write(`\nDone. ${c.dim("selfguard ui (dashboard) · selfguard status · selfguard --help")}\n`);
     return 0;
 }

package/dist/state.js

@@ -0,0 +1,19 @@
+/** Small runtime state that isn't configuration (e.g. when the last reminder was sent). */
+import { atomicWrite, isObject, readJsonFile } from "./fsutil.js";
+import { stateFile } from "./paths.js";
+export function loadState() {
+    const raw = readJsonFile(stateFile());
+    if (!raw || !isObject(raw))
+        return {};
+    const out = {};
+    for (const k of ["lastReminder", "lastSync", "lastCheck"]) {
+        if (typeof raw[k] === "string")
+            out[k] = raw[k];
+    }
+    return out;
+}
+export function updateState(patch) {
+    const next = { ...loadState(), ...patch };
+    atomicWrite(stateFile(), JSON.stringify(next));
+    return next;
+}