salvatron 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,6 @@
+{
+  "enabledMcpjsonServers": [
+    "claude-history",
+    "claw-bridge"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jon Hammant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# salvatron
+
+AI-assisted coding means you start projects faster than you finish them. The
+result is a dev directory full of half-built, uncommitted, unpublished work —
+a personal garbage dimension, growing by the week.
+
+**Salvatron patrols it.** One command inventories every project, flags the
+uncommitted work you're about to lose, and ranks the almost-done ones worth
+shipping instead of rebuilding.
+
+```bash
+salvatron report ~/dev --tyrant
+```
+
+```text
+SALVATRON SWEEP COMPLETE
+
+  263 projects scanned
+  162 under git · 101 with no version control
+  45 repos carrying uncommitted work
+  18 repos with no remote (nowhere but this disk)
+  29 untouched for 6+ months
+
+SHIP CANDIDATES — closest to launch, not yet published
+
+   90/100  LocalRealtimeChat   3mo ago   needs: LICENSE
+   85/100  sideband            17d ago   needs: 5+ commits
+   ...
+
+AH-HA
+
+  ◉ 8 projects orbit "claude": claude-history-cloud, claude-history-mcp,
+    ClaudeHistoryMCP, … One idea — which is canonical?
+  ◉ LocalRealtimeChat is 90/100 shippable (needs: LICENSE) and has sat
+    still for 3 months.
+  ◉ scraper-medic echoes gym-scraper, untouched for 6+ months. Salvage
+    before you rebuild.
+
+  ⏣ 263 projects. This is not a dev directory, it is a garbage dimension.
+  ⏣ ASSESSMENT COMPLETE. REPORTING NOTHING TO RICK.
+```
+
+## Install
+
+```bash
+npm install -g salvatron
+```
+
+Or run it straight from a clone — zero dependencies, Node 18+:
+
+```bash
+node src/cli.mjs report ~/dev
+```
+
+## Commands
+
+| Command | What it does |
+| ------- | ------------ |
+| `salvatron scan [dir]` | Inventory: git state, staleness, risk counts |
+| `salvatron dirty [dir]` | Repos with uncommitted work, most at-risk first |
+| `salvatron ship [dir]` | Unpublished projects closest to launch, and what each still needs |
+| `salvatron stale [dir]` | Cleanup candidates: unmodified for ages, with last-*accessed* times so you can tell truly dead from consulted-but-not-edited |
+| `salvatron aha [dir]` | Insights: duplicate-idea clusters, near-misses, "you're rebuilding something you already built" echoes |
+| `salvatron snapshot [dir]` | Record this sweep in the ledger and diff against last time |
+| `salvatron archive <path…>` | Move projects into a `SalvatronArchive/` dir beside them; the ledger marks them archived (never confused with dead) and future scans skip the archive |
+| `salvatron graveyard` | Projects deleted or archived, as remembered in the ledger |
+| `salvatron report [dir]` | The full digest |
+
+Options: `--json` for machine-readable output, `-n <count>` to limit lists,
+`--stale <days>` to bound ship-candidate staleness (default 120),
+`--tyrant` to let Salvatron say what it really thinks.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["~/dev<br>one dir per project"] --> B["scan<br>git state · staleness<br>last-accessed · README/tests"]
+    B --> C["dirty · ship · stale<br>risk + readiness views"]
+    B --> D["aha<br>clusters · echoes<br>near-misses"]
+    B --> E["snapshot"]
+    E --> F[("ledger<br>~/.salvatron")]
+    F --> D
+    F --> G["graveyard<br>the remembered dead"]
+    H["archive<br>move aside, never forget"] --> F
+```
+
+Pure filesystem + git plumbing. No index, no daemon, no network, nothing
+leaves your machine.
+
+## Why
+
+- **Uncommitted work is one disk failure from gone.** `salvatron dirty` is
+  loss prevention.
+- **Your graveyard is a backlog.** `salvatron ship` scores every unpublished
+  project on distance-to-shippable (README, LICENSE, tests, commits, clean
+  tree) so the 80%-done ones get rescued instead of rebuilt.
+- **It never deletes anything.** Salvatron recommends; you decide. We all saw
+  what happens when the salvage bot gets unilateral power.
+- **Cleanup without amnesia.** `snapshot` keeps a ledger in `~/.salvatron/`;
+  when a project disappears from disk it becomes a tombstone — name, final
+  state, and remote URL remembered forever. Age things out; forget nothing.
+
+Everything except `snapshot` is strictly read-only: directory listings, file
+stats, and read-only git queries. No file contents are read, nothing is
+modified, and nothing touches the network.
+
+Inspired by a certain garbage-dimension warden from a certain interdimensional
+cartoon (S8E9). This project is not affiliated with it in any way.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "salvatron",
+  "version": "0.1.0",
+  "description": "The salvage bot for AI-assisted development. Inventories your graveyard of side projects and tells you what's worth rescuing.",
+  "type": "module",
+  "bin": {
+    "salvatron": "./src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cli",
+    "git",
+    "projects",
+    "inventory",
+    "salvage",
+    "ai",
+    "developer-tools"
+  ],
+  "author": "Jon Hammant",
+  "license": "MIT"
+}

package/src/aha.mjs

@@ -0,0 +1,97 @@
+// Heuristic "ah ha" moments: deterministic insights mined from the scan and
+// ledger. No LLM, no network — just patterns you stopped being able to see.
+
+import { shipCandidates } from './ship.mjs';
+
+const STOP = new Set([
+  'app', 'apps', 'test', 'demo', 'the', 'new', 'old', 'video', 'site',
+  'bot', 'tool', 'tools', 'skill', 'cli', 'ios', 'web', 'lite', 'pro',
+  'ops', 'lab', 'setup', 'config', 'promo', 'infra',
+]);
+
+export function nameTokens(name) {
+  return [
+    ...new Set(
+      name
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z]+/)
+        .filter((t) => t.length >= 3 && !STOP.has(t)),
+    ),
+  ];
+}
+
+// Projects sharing a distinctive name token — one idea, many directories.
+export function clusters(projects, { min = 3 } = {}) {
+  const byToken = new Map();
+  for (const p of projects) {
+    for (const t of nameTokens(p.name)) {
+      if (!byToken.has(t)) byToken.set(t, []);
+      byToken.get(t).push(p.name);
+    }
+  }
+  return [...byToken.entries()]
+    .filter(([, names]) => names.length >= min)
+    .sort((a, b) => b[1].length - a[1].length)
+    .map(([token, names]) => ({ token, names }));
+}
+
+// Nearly shippable and sitting still: one push from done, for months.
+export function nearMisses(projects, { minScore = 80, minStaleDays = 60 } = {}) {
+  return shipCandidates(projects, { limit: 1000, maxStaleDays: 10_000 })
+    .filter((p) => p.score >= minScore && p.staleDays >= minStaleDays);
+}
+
+// A fresh project that rhymes with an old or dead one — a probable rebuild.
+export function echoes(projects, tombstoned = []) {
+  const recent = projects.filter((p) => p.staleDays <= 30);
+  const old = [
+    ...projects.filter((p) => p.staleDays >= 180),
+    ...tombstoned,
+  ];
+  const found = [];
+  for (const r of recent) {
+    const rTokens = new Set(nameTokens(r.name));
+    for (const o of old) {
+      if (o.path === r.path) continue;
+      const shared = nameTokens(o.name).filter((t) => rTokens.has(t));
+      if (shared.length) {
+        found.push({
+          fresh: r.name,
+          echo: o.name,
+          token: shared[0],
+          gone: Boolean(o.gone),
+        });
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+export function ahaMoments(projects, tombstoned = []) {
+  const moments = [];
+
+  for (const c of clusters(projects).slice(0, 4)) {
+    moments.push(
+      `${c.names.length} projects orbit "${c.token}": ${c.names.join(', ')}. One idea — which is canonical?`,
+    );
+  }
+
+  for (const p of nearMisses(projects).slice(0, 3)) {
+    const months = Math.round(p.staleDays / 30);
+    moments.push(
+      `${p.name} is ${p.score}/100 shippable (needs: ${p.missing.join(', ')}) and has sat still for ${months} month${months === 1 ? '' : 's'}.`,
+    );
+  }
+
+  for (const e of echoes(projects, tombstoned).slice(0, 3)) {
+    moments.push(
+      e.gone
+        ? `${e.fresh} echoes ${e.echo} — which you already built and deleted. The ledger remembers it.`
+        : `${e.fresh} echoes ${e.echo}, untouched for 6+ months. Salvage before you rebuild.`,
+    );
+  }
+
+  return moments;
+}

package/src/cli.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { scanDir, stats } from './scan.mjs';
+import { shipCandidates, dirtyRepos, unversioned, staleProjects } from './ship.mjs';
+import {
+  loadLedger, saveLedger, updateLedger, tombstones, archiveProjects, archived,
+} from './ledger.mjs';
+import { ahaMoments } from './aha.mjs';
+import {
+  renderScan, renderDirty, renderShip, renderStale, renderReport,
+  renderAha, renderSnapshot, renderGraveyard,
+} from './report.mjs';
+
+const HELP = `salvatron — the salvage bot for AI-assisted development
+
+Usage: salvatron <command> [dir] [options]
+
+Commands:
+  scan     Inventory every project: git state, staleness, risk counts
+  dirty    Repos with uncommitted work, most at-risk first
+  ship     Unpublished projects closest to launch, with what's missing
+  stale    Cleanup candidates: untouched for ages, with last-accessed times
+  aha      Insights: duplicate-idea clusters, near-misses, rebuild echoes
+  snapshot Record this sweep in the ledger; diff vs last time (writes state)
+  archive  Move projects into SalvatronArchive/ next to them (ledger remembers)
+  graveyard Projects deleted or archived, as remembered in the ledger
+  report   The full digest (scan + dirty + ship + unversioned + ah-has)
+
+Options:
+  --json          Machine-readable output
+  -n <count>      Limit list length (default 10)
+  --stale <days>  Max staleness for ship candidates (default 120)
+  --tyrant        Let Salvatron say what it really thinks
+  -h, --help      This help
+
+[dir] defaults to the current directory. Point it at the graveyard:
+  salvatron report ~/dev --tyrant
+`;
+
+function parseArgs(argv) {
+  const args = { command: null, paths: [], json: false, tyrant: false, limit: 10, maxStaleDays: 120 };
+  const rest = [...argv];
+  while (rest.length) {
+    const a = rest.shift();
+    if (a === '-h' || a === '--help') return { help: true };
+    else if (a === '--json') args.json = true;
+    else if (a === '--tyrant') args.tyrant = true;
+    else if (a === '-n') args.limit = Number(rest.shift()) || 10;
+    else if (a === '--stale') args.maxStaleDays = Number(rest.shift()) || 120;
+    else if (!args.command) args.command = a;
+    else args.paths.push(a);
+  }
+  args.dir = args.paths[0] ?? process.cwd();
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help || !args.command) {
+  console.log(HELP);
+  process.exit(args.help ? 0 : 1);
+}
+
+const NEEDS_SCAN = new Set(['scan', 'dirty', 'ship', 'stale', 'aha', 'snapshot', 'report']);
+let projects = [];
+if (NEEDS_SCAN.has(args.command)) {
+  try {
+    projects = scanDir(args.dir);
+  } catch (err) {
+    console.error(`salvatron: cannot scan ${args.dir}: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+const opts = { limit: args.limit, maxStaleDays: args.maxStaleDays };
+
+switch (args.command) {
+  case 'scan':
+    if (args.json) console.log(JSON.stringify({ stats: stats(projects), projects }, null, 2));
+    else console.log(renderScan(projects));
+    break;
+  case 'dirty':
+    if (args.json) console.log(JSON.stringify(dirtyRepos(projects), null, 2));
+    else console.log(renderDirty(projects, args.limit));
+    break;
+  case 'ship':
+    if (args.json) console.log(JSON.stringify(shipCandidates(projects, opts), null, 2));
+    else console.log(renderShip(projects, opts));
+    break;
+  case 'stale':
+    if (args.json) console.log(JSON.stringify(staleProjects(projects, { minStaleDays: args.maxStaleDays }), null, 2));
+    else console.log(renderStale(projects, { minStaleDays: args.maxStaleDays, limit: args.limit }));
+    break;
+  case 'aha': {
+    const moments = ahaMoments(projects, tombstones(loadLedger()));
+    if (args.json) console.log(JSON.stringify(moments, null, 2));
+    else console.log(renderAha(moments));
+    break;
+  }
+  case 'snapshot': {
+    const ledger = loadLedger();
+    const diff = updateLedger(ledger, projects, resolve(args.dir));
+    const path = saveLedger(ledger);
+    if (args.json) console.log(JSON.stringify({ diff, ledger: path }, null, 2));
+    else console.log(renderSnapshot(diff, ledger));
+    break;
+  }
+  case 'archive': {
+    if (!args.paths.length) {
+      console.error('salvatron: archive needs at least one project path');
+      process.exit(1);
+    }
+    const ledger = loadLedger();
+    const result = archiveProjects(ledger, args.paths);
+    saveLedger(ledger);
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      for (const m of result.moved) console.log(`archived  ${m.name} → ${m.to}`);
+      for (const s of result.skipped) console.log(`skipped   ${s.name} (${s.reason})`);
+      console.log(`\n${result.moved.length} archived. The ledger remembers them all.`);
+    }
+    break;
+  }
+  case 'graveyard': {
+    const ledger = loadLedger();
+    if (args.json) console.log(JSON.stringify({ dead: tombstones(ledger), archived: archived(ledger) }, null, 2));
+    else console.log(renderGraveyard(tombstones(ledger), archived(ledger)));
+    break;
+  }
+  case 'report':
+    if (args.json) {
+      console.log(JSON.stringify({
+        stats: stats(projects),
+        dirty: dirtyRepos(projects),
+        shipCandidates: shipCandidates(projects, opts),
+        unversioned: unversioned(projects),
+      }, null, 2));
+    } else console.log(renderReport(projects, {
+      tyrant: args.tyrant,
+      ahas: ahaMoments(projects, tombstones(loadLedger())),
+      ...opts,
+    }));
+    break;
+  default:
+    console.error(`salvatron: unknown command '${args.command}'\n`);
+    console.log(HELP);
+    process.exit(1);
+}

package/src/git.mjs

@@ -0,0 +1,14 @@
+import { execFileSync } from 'node:child_process';
+
+// Returns trimmed stdout, or null if git fails (not a repo, unborn HEAD, etc.)
+export function git(repo, args) {
+  try {
+    return execFileSync('git', ['-C', repo, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 15_000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}

package/src/ledger.mjs

@@ -0,0 +1,111 @@
+// The ledger is salvatron's memory: every snapshot refreshes what's on disk,
+// and projects that vanish become tombstones — remembered with their final
+// state and remote URL, so cleanup never means amnesia.
+
+import { readFileSync, writeFileSync, mkdirSync, renameSync, existsSync } from 'node:fs';
+import { join, dirname, basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+export const ARCHIVE_DIRNAME = 'SalvatronArchive';
+
+export function ledgerPath() {
+  const dir = process.env.SALVATRON_HOME || join(homedir(), '.salvatron');
+  return join(dir, 'ledger.json');
+}
+
+export function loadLedger() {
+  try {
+    return JSON.parse(readFileSync(ledgerPath(), 'utf8'));
+  } catch {
+    return { updatedAt: null, projects: {} };
+  }
+}
+
+export function saveLedger(ledger) {
+  const path = ledgerPath();
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(ledger, null, 2));
+  return path;
+}
+
+export function updateLedger(ledger, scanned, root, { now = Date.now() } = {}) {
+  const today = new Date(now).toISOString().slice(0, 10);
+  const seen = new Set();
+  const diff = { added: [], returned: [], gone: [], newlyDirty: [], cleaned: [] };
+
+  for (const p of scanned) {
+    seen.add(p.path);
+    const prev = ledger.projects[p.path];
+    if (!prev) diff.added.push(p.name);
+    else {
+      if (prev.gone) diff.returned.push(p.name);
+      if ((prev.dirty ?? 0) === 0 && p.dirty > 0) diff.newlyDirty.push(p.name);
+      if ((prev.dirty ?? 0) > 0 && p.dirty === 0) diff.cleaned.push(p.name);
+    }
+    ledger.projects[p.path] = {
+      ...p,
+      firstSeen: prev?.firstSeen ?? today,
+      lastSeen: today,
+      gone: false,
+      goneSince: null,
+    };
+  }
+
+  // Only tombstone entries under the scanned root — scanning one directory
+  // must not declare projects elsewhere dead.
+  for (const rec of Object.values(ledger.projects)) {
+    if (!seen.has(rec.path) && !rec.gone && !rec.archived && rec.path.startsWith(root + '/')) {
+      rec.gone = true;
+      rec.goneSince = today;
+      diff.gone.push(rec.name);
+    }
+  }
+
+  ledger.updatedAt = today;
+  return diff;
+}
+
+// Move projects into a sibling SalvatronArchive/ dir and record it in the
+// ledger as archived — aged out, still on disk, never confused with dead.
+export function archiveProjects(ledger, paths, { now = Date.now() } = {}) {
+  const today = new Date(now).toISOString().slice(0, 10);
+  const moved = [];
+  const skipped = [];
+  for (const target of paths) {
+    const from = resolve(target);
+    if (!existsSync(from)) {
+      skipped.push({ name: basename(from), reason: 'not found' });
+      continue;
+    }
+    const to = join(dirname(from), ARCHIVE_DIRNAME, basename(from));
+    if (existsSync(to)) {
+      skipped.push({ name: basename(from), reason: 'already archived' });
+      continue;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    renameSync(from, to);
+    const rec = ledger.projects[from] ?? { name: basename(from), path: from };
+    ledger.projects[from] = {
+      ...rec,
+      archived: true,
+      archivedTo: to,
+      archivedOn: today,
+      gone: false,
+      goneSince: null,
+    };
+    moved.push({ name: basename(from), to });
+  }
+  return { moved, skipped };
+}
+
+export function archived(ledger) {
+  return Object.values(ledger.projects)
+    .filter((p) => p.archived && !p.gone)
+    .sort((a, b) => (b.archivedOn ?? '').localeCompare(a.archivedOn ?? ''));
+}
+
+export function tombstones(ledger) {
+  return Object.values(ledger.projects)
+    .filter((p) => p.gone)
+    .sort((a, b) => (b.goneSince ?? '').localeCompare(a.goneSince ?? ''));
+}

package/src/report.mjs

@@ -0,0 +1,161 @@
+import { stats } from './scan.mjs';
+import { shipCandidates, dirtyRepos, unversioned, staleProjects } from './ship.mjs';
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const bold = (s) => c('1', s);
+export const red = (s) => c('31', s);
+export const green = (s) => c('32', s);
+export const yellow = (s) => c('33', s);
+export const dim = (s) => c('2', s);
+
+function age(p) {
+  if (!Number.isFinite(p.staleDays)) return 'unknown';
+  if (p.staleDays === 0) return 'today';
+  if (p.staleDays < 30) return `${p.staleDays}d ago`;
+  if (p.staleDays < 365) return `${Math.round(p.staleDays / 30)}mo ago`;
+  return `${(p.staleDays / 365).toFixed(1)}y ago`;
+}
+
+export function renderScan(projects) {
+  const s = stats(projects);
+  const lines = [];
+  lines.push(bold('SALVATRON SWEEP COMPLETE'));
+  lines.push('');
+  lines.push(`  ${bold(String(s.total))} projects scanned`);
+  lines.push(`  ${green(String(s.gitRepos))} under git · ${red(String(s.noGit))} with no version control`);
+  lines.push(`  ${red(String(s.dirty))} repos carrying uncommitted work`);
+  lines.push(`  ${yellow(String(s.noRemote))} repos with no remote (nowhere but this disk)`);
+  lines.push(`  ${dim(String(s.stale180))} untouched for 6+ months`);
+  return lines.join('\n');
+}
+
+export function renderDirty(projects, limit = 25) {
+  const dirty = dirtyRepos(projects).slice(0, limit);
+  if (!dirty.length) return green('No uncommitted work found. Suspiciously tidy.');
+  const lines = [bold(`UNCOMMITTED WORK — ${dirty.length} repos at risk`), ''];
+  for (const p of dirty) {
+    lines.push(`  ${red(String(p.dirty).padStart(4))} files  ${bold(p.name)}  ${dim(age(p))}`);
+  }
+  lines.push('');
+  lines.push(dim('One spilled coffee from oblivion. Commit or stash.'));
+  return lines.join('\n');
+}
+
+export function renderShip(projects, opts) {
+  const cands = shipCandidates(projects, opts);
+  if (!cands.length) return 'No ship candidates in range. Everything is either published or fossilised.';
+  const lines = [bold('SHIP CANDIDATES — closest to launch, not yet published'), ''];
+  for (const p of cands) {
+    const needs = p.missing.length ? `needs: ${p.missing.join(', ')}` : 'ready';
+    lines.push(`  ${green(String(p.score).padStart(3))}/100  ${bold(p.name.padEnd(28))} ${dim(age(p).padEnd(9))} ${yellow(needs)}`);
+  }
+  return lines.join('\n');
+}
+
+function accessAge(p) {
+  if (p.accessDays == null) return 'accessed: unknown';
+  if (p.accessDays === 0) return 'accessed today';
+  if (p.accessDays < 30) return `accessed ${p.accessDays}d ago`;
+  if (p.accessDays < 365) return `accessed ${Math.round(p.accessDays / 30)}mo ago`;
+  return `accessed ${(p.accessDays / 365).toFixed(1)}y ago`;
+}
+
+export function renderStale(projects, { minStaleDays = 180, limit = 20 } = {}) {
+  const stale = staleProjects(projects, { minStaleDays });
+  if (!stale.length) return green(`Nothing untouched for ${minStaleDays}+ days. Impressive, or a lie.`);
+  const lines = [
+    bold(`CLEANUP CANDIDATES — no changes in ${minStaleDays}+ days, least-recently-accessed first`),
+    '',
+  ];
+  for (const p of stale.slice(0, limit)) {
+    const vcs = p.git ? (p.remote ? green('pushed') : yellow('local-only')) : red('no git');
+    lines.push(
+      `  ${bold(p.name.padEnd(28))} modified ${age(p).padEnd(9)} ${dim(accessAge(p).padEnd(19))} ${vcs}`,
+    );
+  }
+  if (stale.length > limit) lines.push(dim(`  … and ${stale.length - limit} more (use -n)`));
+  lines.push('');
+  lines.push(dim('local-only / no git means deleting it deletes the only copy. Archive first.'));
+  return lines.join('\n');
+}
+
+export function renderAha(moments) {
+  if (!moments.length) return dim('No ah-ha moments this sweep. The graveyard keeps its secrets.');
+  const lines = [bold('AH-HA'), ''];
+  for (const m of moments) lines.push(`  ${yellow('◉')} ${m}`);
+  return lines.join('\n');
+}
+
+export function renderSnapshot(diff, ledger) {
+  const total = Object.keys(ledger.projects).length;
+  const dead = Object.values(ledger.projects).filter((p) => p.gone).length;
+  const lines = [bold('SNAPSHOT RECORDED'), ''];
+  const row = (label, names, color = yellow) =>
+    names.length && lines.push(`  ${color(String(names.length).padStart(3))}  ${label}: ${names.slice(0, 8).join(', ')}${names.length > 8 ? ', …' : ''}`);
+  row('new since last snapshot', diff.added, green);
+  row('returned from the dead', diff.returned, green);
+  row('gone — now tombstoned, still remembered', diff.gone, red);
+  row('newly dirty', diff.newlyDirty, red);
+  row('cleaned up', diff.cleaned, green);
+  if (lines.length === 2) lines.push(dim('  No changes since last snapshot.'));
+  lines.push('');
+  lines.push(dim(`  Ledger: ${total} projects remembered, ${dead} tombstones.`));
+  return lines.join('\n');
+}
+
+export function renderGraveyard(dead, resting = []) {
+  const lines = [];
+  if (dead.length) {
+    lines.push(bold(`GRAVEYARD — ${dead.length} projects remembered after deletion`), '');
+    for (const p of dead) {
+      const recover = p.remoteUrl ? dim(p.remoteUrl) : red('no remote — it is truly gone');
+      lines.push(`  ${bold(p.name.padEnd(28))} died ${p.goneSince ?? '?'}  ${recover}`);
+    }
+  }
+  if (resting.length) {
+    if (lines.length) lines.push('');
+    lines.push(bold(`ARCHIVED — ${resting.length} projects aged out, still on disk`), '');
+    for (const p of resting) {
+      lines.push(`  ${bold(p.name.padEnd(28))} archived ${p.archivedOn ?? '?'}  ${dim(p.archivedTo ?? '')}`);
+    }
+  }
+  if (!lines.length) return dim('No tombstones, nothing archived. Nothing has been forgotten — because nothing has left.');
+  return lines.join('\n');
+}
+
+export function tyrantLines(projects) {
+  const s = stats(projects);
+  const lines = [];
+  if (s.total > 100) lines.push(`${s.total} projects. This is not a dev directory, it is a garbage dimension.`);
+  if (s.dirty > 10) lines.push(`${s.dirty} repos with uncommitted changes. Your work exists at the pleasure of your hardware.`);
+  if (s.noGit > 20) lines.push(`${s.noGit} directories with no version control. Bold. Doomed, but bold.`);
+  if (s.stale180 > 50) lines.push(`${s.stale180} projects untouched for six months. They dream of being finished.`);
+  lines.push('ASSESSMENT COMPLETE. REPORTING NOTHING TO RICK.');
+  return lines.map((l) => red(bold(`  ⏣ ${l}`))).join('\n');
+}
+
+export function renderReport(projects, { tyrant = false, ahas = [], ...opts } = {}) {
+  const parts = [
+    renderScan(projects),
+    '',
+    renderDirty(projects, 10),
+    '',
+    renderShip(projects, opts),
+  ];
+  if (ahas.length) {
+    parts.push('');
+    parts.push(renderAha(ahas.slice(0, 5)));
+  }
+  const unv = unversioned(projects);
+  if (unv.length) {
+    parts.push('');
+    parts.push(bold(`NO VERSION CONTROL — ${unv.length} dirs, most recent first`));
+    parts.push(unv.slice(0, 10).map((p) => `  ${bold(p.name.padEnd(28))} ${dim(age(p))}`).join('\n'));
+  }
+  if (tyrant) {
+    parts.push('');
+    parts.push(tyrantLines(projects));
+  }
+  return parts.join('\n');
+}

package/src/scan.mjs

@@ -0,0 +1,131 @@
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { git } from './git.mjs';
+
+const MANIFESTS = [
+  'package.json', 'pyproject.toml', 'setup.py', 'requirements.txt',
+  'Cargo.toml', 'go.mod', 'Gemfile', 'Package.swift', 'pom.xml',
+  'build.gradle', 'Makefile', 'CMakeLists.txt',
+];
+const TEST_MARKERS = ['test', 'tests', '__tests__', 'spec'];
+const LICENSES = ['LICENSE', 'LICENSE.md', 'LICENSE.txt', 'COPYING'];
+
+const MS_PER_DAY = 86_400_000;
+
+function anyExists(dir, names) {
+  return names.some((n) => existsSync(join(dir, n)));
+}
+
+function hasReadme(dir) {
+  try {
+    return readdirSync(dir).some((f) => /^readme(\.|$)/i.test(f));
+  } catch {
+    return false;
+  }
+}
+
+// Newest atime across a sample of the project's files (top level + one down).
+// stat() reads metadata without touching atime, so scanning stays read-only.
+// Caveat: indexers/backup tools also bump atime, so treat as "no later than".
+function newestAtimeMs(dir) {
+  let newest = 0;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  let checked = 0;
+  for (const e of entries) {
+    if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+    const p = join(dir, e.name);
+    try {
+      const st = statSync(p);
+      if (!e.isDirectory()) newest = Math.max(newest, st.atimeMs);
+      else if (checked < 30) {
+        for (const f of readdirSync(p).slice(0, 20)) {
+          try {
+            newest = Math.max(newest, statSync(join(p, f)).atimeMs);
+          } catch {}
+        }
+      }
+      checked++;
+    } catch {}
+    if (checked >= 60) break;
+  }
+  return newest || null;
+}
+
+export function scanProject(path, { now = Date.now() } = {}) {
+  const p = {
+    name: basename(path),
+    path,
+    git: existsSync(join(path, '.git')),
+    remote: false,
+    dirty: 0,
+    commits: 0,
+    lastActivity: null,
+    hasReadme: hasReadme(path),
+    hasLicense: anyExists(path, LICENSES),
+    hasTests: anyExists(path, TEST_MARKERS),
+    hasManifest: anyExists(path, MANIFESTS),
+  };
+
+  if (p.git) {
+    const status = git(path, ['status', '--porcelain']);
+    p.dirty = status ? status.split('\n').filter(Boolean).length : 0;
+    p.remote = Boolean(git(path, ['remote']));
+    p.remoteUrl = p.remote ? git(path, ['remote', 'get-url', 'origin']) : null;
+    p.commits = Number(git(path, ['rev-list', '--count', 'HEAD'])) || 0;
+    p.lastActivity = git(path, ['log', '-1', '--format=%cs']) || null;
+  }
+
+  if (!p.lastActivity) {
+    try {
+      p.lastActivity = statSync(path).mtime.toISOString().slice(0, 10);
+    } catch {
+      p.lastActivity = null;
+    }
+  }
+
+  p.staleDays = p.lastActivity
+    ? Math.max(0, Math.floor((now - Date.parse(p.lastActivity)) / MS_PER_DAY))
+    : Infinity;
+
+  const atime = newestAtimeMs(path);
+  p.lastAccessed = atime ? new Date(atime).toISOString().slice(0, 10) : null;
+  p.accessDays = atime ? Math.max(0, Math.floor((now - atime) / MS_PER_DAY)) : null;
+
+  return p;
+}
+
+export function scanDir(root, opts = {}) {
+  const abs = resolve(root);
+  const entries = readdirSync(abs, { withFileTypes: true }).filter(
+    (e) =>
+      e.isDirectory() && !e.name.startsWith('.') && e.name !== 'SalvatronArchive',
+  );
+
+  const projects = [];
+  for (const e of entries) {
+    try {
+      projects.push(scanProject(join(abs, e.name), opts));
+    } catch {
+      // unreadable dir — skip, never crash the sweep
+    }
+  }
+  return projects.sort((a, b) =>
+    (a.lastActivity ?? '').localeCompare(b.lastActivity ?? ''),
+  );
+}
+
+export function stats(projects) {
+  return {
+    total: projects.length,
+    gitRepos: projects.filter((p) => p.git).length,
+    noGit: projects.filter((p) => !p.git).length,
+    dirty: projects.filter((p) => p.dirty > 0).length,
+    noRemote: projects.filter((p) => p.git && !p.remote).length,
+    stale180: projects.filter((p) => p.staleDays >= 180).length,
+  };
+}

package/src/ship.mjs

@@ -0,0 +1,57 @@
+// Ship-readiness scoring: how close is a project to being publishable,
+// and what's still missing. A remote counts as "already shipped".
+
+const CHECKS = [
+  { label: 'README', points: 20, pass: (p) => p.hasReadme },
+  { label: 'LICENSE', points: 10, pass: (p) => p.hasLicense },
+  { label: 'git repo', points: 15, pass: (p) => p.git },
+  { label: 'tests', points: 15, pass: (p) => p.hasTests },
+  { label: 'manifest', points: 15, pass: (p) => p.hasManifest },
+  { label: 'clean tree', points: 10, pass: (p) => p.git && p.dirty === 0 },
+  { label: '5+ commits', points: 15, pass: (p) => p.commits >= 5 },
+];
+
+export function shipScore(project) {
+  let score = 0;
+  const missing = [];
+  for (const check of CHECKS) {
+    if (check.pass(project)) score += check.points;
+    else missing.push(check.label);
+  }
+  return { score, missing };
+}
+
+// Unpublished projects (no remote), freshest and most complete first.
+export function shipCandidates(projects, { limit = 10, maxStaleDays = 120 } = {}) {
+  return projects
+    .map((p) => ({ ...p, ...shipScore(p) }))
+    .filter((p) => !p.remote && p.staleDays <= maxStaleDays)
+    .sort((a, b) => b.score - a.score || a.staleDays - b.staleDays)
+    .slice(0, limit);
+}
+
+// Repos with uncommitted work — the stuff one bad `rm -rf` loses forever.
+export function dirtyRepos(projects) {
+  return projects
+    .filter((p) => p.dirty > 0)
+    .sort((a, b) => b.dirty - a.dirty);
+}
+
+// Cleanup candidates: nothing modified in ages. Shown with last-accessed so
+// you can tell truly dead (old atime too) from consulted-but-not-edited.
+export function staleProjects(projects, { minStaleDays = 180 } = {}) {
+  return projects
+    .filter((p) => p.staleDays >= minStaleDays)
+    .sort(
+      (a, b) =>
+        (b.accessDays ?? -1) - (a.accessDays ?? -1) ||
+        b.staleDays - a.staleDays,
+    );
+}
+
+// Directories with no version control at all.
+export function unversioned(projects) {
+  return projects
+    .filter((p) => !p.git)
+    .sort((a, b) => a.staleDays - b.staleDays);
+}

package/test/salvatron.test.mjs

@@ -0,0 +1,237 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { scanDir, scanProject, stats } from '../src/scan.mjs';
+import { shipScore, shipCandidates, dirtyRepos, unversioned, staleProjects } from '../src/ship.mjs';
+
+function sh(cwd, cmd, cmdArgs) {
+  execFileSync(cmd, cmdArgs, { cwd, stdio: 'ignore' });
+}
+
+function gitInit(dir) {
+  sh(dir, 'git', ['init', '-q']);
+  sh(dir, 'git', ['config', 'user.email', 'test@test.invalid']);
+  sh(dir, 'git', ['config', 'user.name', 'test']);
+}
+
+function commit(dir, msg) {
+  sh(dir, 'git', ['add', '-A']);
+  sh(dir, 'git', ['commit', '-q', '-m', msg, '--no-gpg-sign']);
+}
+
+// Fixture graveyard: one shippable repo, one dirty repo, one unversioned dir.
+function makeGraveyard() {
+  const root = mkdtempSync(join(tmpdir(), 'salvatron-'));
+
+  const shippable = join(root, 'shippable');
+  mkdirSync(shippable);
+  writeFileSync(join(shippable, 'README.md'), '# shippable');
+  writeFileSync(join(shippable, 'LICENSE'), 'MIT');
+  writeFileSync(join(shippable, 'package.json'), '{}');
+  mkdirSync(join(shippable, 'test'));
+  writeFileSync(join(shippable, 'test', 'x.test.js'), '');
+  gitInit(shippable);
+  for (let i = 0; i < 5; i++) {
+    writeFileSync(join(shippable, `f${i}.js`), String(i));
+    commit(shippable, `commit ${i}`);
+  }
+
+  const dirty = join(root, 'dirty');
+  mkdirSync(dirty);
+  gitInit(dirty);
+  writeFileSync(join(dirty, 'a.js'), '1');
+  commit(dirty, 'initial');
+  writeFileSync(join(dirty, 'a.js'), '2');
+  writeFileSync(join(dirty, 'b.js'), 'new');
+
+  mkdirSync(join(root, 'loose'));
+  writeFileSync(join(root, 'loose', 'notes.txt'), 'no git here');
+
+  return root;
+}
+
+test('salvatron end-to-end on a fixture graveyard', (t) => {
+  const root = makeGraveyard();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const projects = scanDir(root);
+  assert.equal(projects.length, 3);
+
+  const s = stats(projects);
+  assert.equal(s.gitRepos, 2);
+  assert.equal(s.noGit, 1);
+  assert.equal(s.dirty, 1);
+  assert.equal(s.noRemote, 2);
+
+  const byName = Object.fromEntries(projects.map((p) => [p.name, p]));
+
+  assert.equal(byName.shippable.commits, 5);
+  assert.equal(byName.shippable.dirty, 0);
+  assert.ok(byName.shippable.hasReadme);
+  assert.ok(byName.shippable.hasTests);
+
+  assert.equal(byName.dirty.dirty, 2, 'one modified + one untracked file');
+  assert.ok(!byName.loose.git);
+
+  const { score, missing } = shipScore(byName.shippable);
+  assert.equal(score, 100);
+  assert.deepEqual(missing, []);
+
+  const cands = shipCandidates(projects, { maxStaleDays: 365 });
+  assert.equal(cands[0].name, 'shippable', 'most shippable ranks first');
+
+  assert.equal(dirtyRepos(projects).length, 1);
+  assert.equal(unversioned(projects).length, 1);
+  assert.equal(unversioned(projects)[0].name, 'loose');
+});
+
+test('lastAccessed is populated and staleProjects filters by modification age', (t) => {
+  const root = makeGraveyard();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const projects = scanDir(root);
+  for (const p of projects) {
+    assert.ok(p.lastAccessed, `${p.name} has a lastAccessed date`);
+    assert.equal(typeof p.accessDays, 'number');
+    assert.ok(p.accessDays <= 1, 'fixture files were just created, so accessed now');
+  }
+
+  // Fixtures are brand new — nothing should qualify as stale.
+  assert.equal(staleProjects(projects, { minStaleDays: 180 }).length, 0);
+
+  // Fabricated old projects rank least-recently-accessed first.
+  const old = [
+    { name: 'deadest', staleDays: 900, accessDays: 800 },
+    { name: 'consulted', staleDays: 900, accessDays: 5 },
+    { name: 'fresh', staleDays: 10, accessDays: 1 },
+  ];
+  const stale = staleProjects(old, { minStaleDays: 180 });
+  assert.deepEqual(stale.map((p) => p.name), ['deadest', 'consulted']);
+});
+
+test('scanProject survives a repo with no commits', (t) => {
+  const root = mkdtempSync(join(tmpdir(), 'salvatron-empty-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const empty = join(root, 'empty');
+  mkdirSync(empty);
+  gitInit(empty);
+
+  const p = scanProject(empty);
+  assert.equal(p.commits, 0);
+  assert.ok(p.lastActivity, 'falls back to directory mtime');
+});
+
+test('ledger remembers deleted projects as tombstones', (t) => {
+  const root = makeGraveyard();
+  const home = mkdtempSync(join(tmpdir(), 'salvatron-home-'));
+  t.after(() => {
+    rmSync(root, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  const { loadLedger, saveLedger, updateLedger, tombstones } = awaitImportLedger();
+  process.env.SALVATRON_HOME = home;
+
+  const ledger = loadLedger();
+  const first = updateLedger(ledger, scanDir(root), root);
+  assert.equal(first.added.length, 3);
+  saveLedger(ledger);
+
+  rmSync(join(root, 'dirty'), { recursive: true, force: true });
+
+  const again = loadLedger();
+  const second = updateLedger(again, scanDir(root), root);
+  assert.deepEqual(second.gone, ['dirty']);
+
+  const dead = tombstones(again);
+  assert.equal(dead.length, 1);
+  assert.equal(dead[0].name, 'dirty');
+  assert.ok(dead[0].goneSince, 'tombstone records when it died');
+  assert.equal(dead[0].dirty, 2, 'final state is preserved');
+
+  delete process.env.SALVATRON_HOME;
+});
+
+test('archive moves projects aside and the ledger never tombstones them', (t) => {
+  const root = makeGraveyard();
+  const home = mkdtempSync(join(tmpdir(), 'salvatron-home-'));
+  t.after(() => {
+    rmSync(root, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+    delete process.env.SALVATRON_HOME;
+  });
+
+  const { loadLedger, saveLedger, updateLedger, tombstones, archiveProjects, archived } = ledgerMod;
+  process.env.SALVATRON_HOME = home;
+
+  const ledger = loadLedger();
+  updateLedger(ledger, scanDir(root), root);
+
+  const { moved, skipped } = archiveProjects(ledger, [join(root, 'loose'), join(root, 'nonexistent')]);
+  assert.equal(moved.length, 1);
+  assert.equal(skipped[0].reason, 'not found');
+  assert.ok(existsSync(join(root, 'SalvatronArchive', 'loose')), 'moved into SalvatronArchive');
+  saveLedger(ledger);
+
+  // Next sweep: loose is off the scan (archive dir is excluded) but must be
+  // recorded as archived, not dead.
+  const diff = updateLedger(ledger, scanDir(root), root);
+  assert.deepEqual(diff.gone, [], 'archived projects are not tombstoned');
+  assert.equal(tombstones(ledger).length, 0);
+  assert.equal(archived(ledger)[0].name, 'loose');
+  assert.equal(scanDir(root).length, 2, 'SalvatronArchive itself is not scanned');
+});
+
+test('aha finds clusters, near-misses and echoes', async () => {
+  const { clusters, nearMisses, echoes } = await import('../src/aha.mjs');
+
+  const mk = (name, extra = {}) => ({
+    name, path: `/x/${name}`, git: true, remote: false, dirty: 0, commits: 9,
+    hasReadme: true, hasLicense: true, hasTests: true, hasManifest: true,
+    staleDays: 5, ...extra,
+  });
+
+  const projects = [
+    mk('glasto'), mk('glasto-infra', { staleDays: 400 }), mk('GlastoBot', { staleDays: 400 }),
+    mk('almost-done', { staleDays: 90 }),
+    mk('scraper-medic'),
+    mk('gym-scraper', { staleDays: 2000 }),
+  ];
+
+  const c = clusters(projects);
+  assert.equal(c[0].token, 'glasto');
+  assert.equal(c[0].names.length, 3);
+
+  const near = nearMisses(projects);
+  assert.ok(near.some((p) => p.name === 'almost-done'));
+
+  const e = echoes(projects, [{ name: 'scraper-old', path: '/dead/scraper-old', gone: true }]);
+  assert.ok(e.some((x) => x.fresh === 'scraper-medic' && x.echo === 'gym-scraper'));
+});
+
+// node:test runs test files as ESM; a tiny sync-looking helper keeps the
+// tombstone test readable while the import stays at module scope.
+import * as ledgerMod from '../src/ledger.mjs';
+function awaitImportLedger() {
+  return ledgerMod;
+}
+
+test('CLI runs and produces the report', (t) => {
+  const root = makeGraveyard();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const out = execFileSync(process.execPath, [
+    new URL('../src/cli.mjs', import.meta.url).pathname,
+    'report', root, '--json',
+  ], { encoding: 'utf8' });
+
+  const report = JSON.parse(out);
+  assert.equal(report.stats.total, 3);
+  assert.equal(report.dirty.length, 1);
+  assert.equal(report.unversioned.length, 1);
+});