@mcptoolshop/housekeeping 0.0.0 → 1.3.1

package/src/lockfile.mjs

@@ -0,0 +1,272 @@
+// Pure functions for auditing a committed package-lock.json or pnpm-lock.yaml
+// against the npm advisory registry -- no network here, so every branch is
+// unit-testable.
+//
+// Why this exists: on 2026-09-17 GitHub's Dependabot alert coverage turned out
+// to be silently per-manifest. One repo reported alerts on its root lockfile
+// and ZERO on site/package-lock.json; another had the same two files and
+// reported zero on both, while npm audit found a critical in each. No API
+// forces a re-parse, pushes do not repopulate the graph, and the SBOM
+// endpoint's 404 turned out not to be the signal (a repo can answer 404 while
+// counting). So the warehouse stops trusting the counter and reads the
+// lockfiles itself. Absent renders as fine; this is the counter switched on.
+
+/**
+ * Map every resolved package in a lockfile to the set of versions it appears
+ * at. Handles lockfileVersion 2/3 (`packages`, keyed by path) and 1
+ * (`dependencies`, nested). The root entry ("") is the project itself and is
+ * skipped. A name is the path after the LAST `node_modules/`, so a nested
+ * duplicate (`node_modules/a/node_modules/b`) counts as `b`, which is what the
+ * advisory registry is keyed on.
+ *
+ * Returns { name: [version, ...] } with versions deduplicated and sorted, so
+ * two lockfiles resolving to the same set produce byte-identical maps.
+ */
+export function packageMapFromLockfile(lock) {
+  const out = new Map();
+  const add = (name, version) => {
+    if (!name || !version || typeof version !== 'string') return;
+    if (!out.has(name)) out.set(name, new Set());
+    out.get(name).add(version);
+  };
+
+  if (lock && typeof lock.packages === 'object' && lock.packages) {
+    for (const [path, entry] of Object.entries(lock.packages)) {
+      if (!path || !entry || typeof entry !== 'object') continue;   // "" is the root
+      if (entry.link) continue;                                      // workspace symlink, not a resolved package
+      const name = entry.name ?? path.slice(path.lastIndexOf('node_modules/') + 'node_modules/'.length);
+      add(name, entry.version);
+    }
+  } else if (lock && typeof lock.dependencies === 'object' && lock.dependencies) {
+    const walk = (deps) => {
+      for (const [name, entry] of Object.entries(deps)) {
+        if (!entry || typeof entry !== 'object') continue;
+        add(name, entry.version);
+        if (entry.dependencies) walk(entry.dependencies);
+      }
+    };
+    walk(lock.dependencies);
+  }
+
+  return Object.fromEntries(
+    [...out.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, [...v].sort()]),
+  );
+}
+
+/**
+ * Names that appear in the lockfile ONLY as dev dependencies (`dev: true` on
+ * every entry). A name resolved as prod anywhere in the tree is prod: the
+ * shipped surface is what matters, and one prod edge is enough to ship it.
+ *
+ * Kept apart from the package map because the map is the registry payload and
+ * must stay {name: [versions]}; dev-ness is a second axis the report needs
+ * because many audit gates run `--omit=dev`, and a critical in a test
+ * runner is a different finding from a critical in what users install.
+ */
+export function devOnlyPackages(lock) {
+  const prod = new Set(), dev = new Set();
+  const see = (name, entry) => {
+    if (!name || !entry || typeof entry !== 'object') return;
+    (entry.dev === true ? dev : prod).add(name);
+  };
+  if (lock && typeof lock.packages === 'object' && lock.packages) {
+    for (const [path, entry] of Object.entries(lock.packages)) {
+      if (!path || entry?.link) continue;
+      see(entry.name ?? path.slice(path.lastIndexOf('node_modules/') + 'node_modules/'.length), entry);
+    }
+  } else if (lock && typeof lock.dependencies === 'object' && lock.dependencies) {
+    const walk = (deps) => {
+      for (const [name, entry] of Object.entries(deps)) {
+        see(name, entry);
+        if (entry?.dependencies) walk(entry.dependencies);
+      }
+    };
+    walk(lock.dependencies);
+  }
+  return [...dev].filter(n => !prod.has(n)).sort();
+}
+
+/**
+ * The npm bulk endpoint (POST /-/npm/v1/security/advisories/bulk) takes exactly
+ * the { name: [versions] } map above and answers { name: [advisory...] } with
+ * only the advisories whose `vulnerable_versions` range matches a version sent.
+ * Flatten that to one row per (package, version, advisory) so a finding can
+ * name the version that is actually resolved.
+ *
+ * `vulnerable_versions` is a semver range string; the registry has already
+ * applied it, so this does NOT re-evaluate it -- doing so with a home-grown
+ * range parser is how a rule ends up disagreeing with the tool it cites.
+ */
+export function advisoriesFromBulk(packageMap, response, devOnly = []) {
+  const rows = [];
+  if (!response || typeof response !== 'object') return rows;
+  const dev = new Set(devOnly);
+  for (const [name, list] of Object.entries(response)) {
+    const versions = packageMap[name] ?? [];
+    for (const a of Array.isArray(list) ? list : []) {
+      const ghsa = (a.url ?? '').split('/').pop() || (a.id != null ? String(a.id) : null);
+      for (const version of versions) {
+        rows.push({
+          package: name,
+          version,
+          severity: normaliseSeverity(a.severity),
+          ghsa,
+          title: (a.title ?? '').slice(0, 200),
+          url: a.url ?? null,
+          vulnerable_versions: a.vulnerable_versions ?? null,
+          dev: dev.has(name),
+        });
+      }
+    }
+  }
+  return rows;
+}
+
+// npm says "moderate"; GitHub says "medium". The report already speaks
+// GitHub's dialect (repo_security.medium), so translate at the boundary once.
+export function normaliseSeverity(s) {
+  const v = String(s ?? '').toLowerCase();
+  if (v === 'moderate') return 'medium';
+  if (['critical', 'high', 'medium', 'low'].includes(v)) return v;
+  return 'unknown';
+}
+
+/**
+ * Per-severity counts in the shape repo_security uses, plus the prod-only
+ * subset. Count distinct advisories, not (advisory x version) rows: a package
+ * resolved at two vulnerable versions is one exposure to fix, not two.
+ */
+export function countBySeverity(advisories) {
+  const c = { critical: 0, high: 0, medium: 0, low: 0, prod_critical: 0, prod_high: 0 };
+  const seen = new Set();
+  for (const a of advisories) {
+    const key = `${a.package}|${a.ghsa}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (a.severity in c) c[a.severity]++;
+    if (!a.dev && (a.severity === 'critical' || a.severity === 'high')) c[`prod_${a.severity}`]++;
+  }
+  return c;
+}
+
+// A lockfile's kind, from its file name. Both kinds resolve packages from the
+// npm registry, so both are audited against the same advisory endpoint.
+const LOCK_KINDS = { 'package-lock.json': 'npm', 'pnpm-lock.yaml': 'pnpm' };
+
+/** Tree entries that are committed npm or pnpm lockfiles worth auditing. */
+export function lockfilePathsFromTree(entries) {
+  return (entries ?? [])
+    .filter(e => e && e.type === 'blob' && typeof e.path === 'string')
+    .map(e => ({ e, kind: LOCK_KINDS[e.path.split('/').pop()] }))
+    .filter(({ kind }) => kind)
+    // A vendored node_modules tree is someone else's lockfile.
+    .filter(({ e }) => !e.path.includes('node_modules/'))
+    .map(({ e, kind }) => ({ path: e.path, sha: e.sha, size: e.size ?? null, kind }));
+}
+
+// ---- pnpm ---------------------------------------------------------------
+//
+// pnpm-lock.yaml keys its packages by name and version, in three spellings
+// across lockfile versions:
+//   9.x   `name@1.2.3` in `packages`, and `name@1.2.3(peer@2.0.0)` in
+//         `snapshots`, which carries the dependency edges
+//   6.x   `/name@1.2.3` or `/name@1.2.3(peer@2.0.0)`, with `dev: true|false`
+//   5.x   `/name/1.2.3` or `/name/1.2.3_peer@2.0.0`, with `dev: true|false`
+// A scoped name keeps its leading `@`, so the version starts after the LAST
+// `@` (or, in 5.x, the last `/`). A key whose version is not a registry
+// version -- a git or tarball URL, `file:`, `link:` -- is not in the advisory
+// registry and is left out, as the npm path leaves out workspace links.
+
+const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?$/;
+
+/** { name, version, key } for one pnpm package key, or null. Pure. */
+// A package name: an optional `@scope/`, then a name with no `/` or `@`.
+// 5.x is tried first because its peer suffix (`_peer@1.0.0`) carries an `@`
+// of its own, which the 6.x/9.x spelling would take for the version's.
+const PNPM_V5_KEY = /^\/((?:@[^/@]+\/)?[^/@]+)\/([^/_(]+)(?:_.*)?$/;
+const PNPM_KEY = /^\/?((?:@[^/@]+\/)?[^/@]+)@([^(]+)(?:\(.*)?$/;
+
+export function parsePnpmKey(key) {
+  if (typeof key !== 'string' || !key) return null;
+  const m = PNPM_V5_KEY.exec(key) ?? PNPM_KEY.exec(key);
+  if (!m) return null;
+  const [, name, version] = m;
+  return SEMVER.test(version) ? { name, version } : null;
+}
+
+/**
+ * The package map and dev-only names of a parsed pnpm-lock.yaml. Pure.
+ *
+ * Dev-ness: 5.x and 6.x mark each package `dev: true|false`, read like npm's
+ * flag. 9.x marks nothing, so what ships is computed: every package reachable
+ * through `snapshots` from any importer's `dependencies` or
+ * `optionalDependencies` is prod; the rest of the lock is dev-only. A 9.x
+ * lock with no `snapshots` cannot be walked, and then nothing is called
+ * dev-only -- the louder reading, never a guess that hides a shipped package.
+ */
+export function pnpmPackageMap(lock) {
+  const out = new Map();
+  const add = (name, version) => {
+    if (!out.has(name)) out.set(name, new Set());
+    out.get(name).add(version);
+  };
+  const pkgs = lock?.packages && typeof lock.packages === 'object' ? lock.packages : {};
+  const flagged = { prod: new Set(), dev: new Set() };
+  let anyFlag = false;
+  for (const [key, entry] of Object.entries(pkgs)) {
+    const p = parsePnpmKey(key);
+    if (!p) continue;
+    add(p.name, p.version);
+    if (entry && typeof entry.dev === 'boolean') { anyFlag = true; (entry.dev ? flagged.dev : flagged.prod).add(p.name); }
+  }
+  const packages = Object.fromEntries(
+    [...out.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, [...v].sort()]),
+  );
+
+  let dev = [];
+  if (anyFlag) {
+    dev = [...flagged.dev].filter(n => !flagged.prod.has(n));
+  } else if (lock?.snapshots && typeof lock.snapshots === 'object') {
+    const snaps = lock.snapshots;
+    const prod = new Set();
+    const queue = [];
+    const visit = (name, ver) => {
+      if (typeof ver !== 'string' || ver.startsWith('link:') || ver.startsWith('file:')) return;
+      const key = `${name}@${ver}`;
+      if (prod.has(key)) return;
+      prod.add(key);
+      queue.push(key);
+    };
+    for (const imp of Object.values(lock.importers ?? {})) {
+      for (const field of ['dependencies', 'optionalDependencies']) {
+        for (const [name, d] of Object.entries(imp?.[field] ?? {})) visit(name, typeof d === 'string' ? d : d?.version);
+      }
+    }
+    while (queue.length) {
+      const s = snaps[queue.shift()];
+      for (const field of ['dependencies', 'optionalDependencies']) {
+        for (const [name, ver] of Object.entries(s?.[field] ?? {})) visit(name, ver);
+      }
+    }
+    const prodNames = new Set([...prod].map(k => parsePnpmKey(k)?.name).filter(Boolean));
+    dev = Object.keys(packages).filter(n => !prodNames.has(n));
+  }
+  return { packages, dev: dev.sort() };
+}
+
+/**
+ * One committed lockfile, read: { version, packages, dev }. Pure apart from
+ * parsing. `kind` is lockfilePathsFromTree's. Throws on a file that does not
+ * parse; the collector records that as not measured.
+ */
+export function readLockfile(text, kind, parseYaml) {
+  if (kind === 'pnpm') {
+    const lock = parseYaml(text);
+    if (!lock || typeof lock !== 'object') throw new Error('pnpm-lock.yaml does not parse to a mapping');
+    const { packages, dev } = pnpmPackageMap(lock);
+    const v = parseFloat(lock.lockfileVersion);
+    return { version: Number.isFinite(v) ? v : null, packages, dev };
+  }
+  const lock = JSON.parse(text);
+  return { version: lock.lockfileVersion ?? null, packages: packageMapFromLockfile(lock), dev: devOnlyPackages(lock) };
+}

package/src/log.mjs

@@ -0,0 +1,41 @@
+// How much the tool says on stderr. stdout is for results only.
+//
+//   silent   errors only
+//   normal   one line per pass of a sweep, and what was written (the default)
+//   verbose  adds one line per GitHub call
+//   debug    adds stack traces on errors
+//
+// Set with --quiet / --verbose / --debug on the CLI, or HK_LOG in the
+// environment. Nothing logged at any level can hold a credential: the tool
+// never reads one. Authentication belongs to `gh`.
+import { userError } from './errors.mjs';
+
+export const LEVELS = ['silent', 'normal', 'verbose', 'debug'];
+
+/** The level a name stands for. An unknown name is an error, never a silent default. Pure. */
+export function parseLevel(name) {
+  if (name === undefined || name === null || name === '') return 'normal';
+  const level = String(name).toLowerCase();
+  if (!LEVELS.includes(level)) {
+    throw userError('CONFIG_INVALID', `unknown log level "${name}"`, `HK_LOG must be one of: ${LEVELS.join(', ')}`);
+  }
+  return level;
+}
+
+/** The level CLI flags ask for; null when none is given. The loudest flag wins. Pure. */
+export function levelFromFlags(flags) {
+  if (flags.has('--debug')) return 'debug';
+  if (flags.has('--verbose')) return 'verbose';
+  if (flags.has('--quiet')) return 'silent';
+  return null;
+}
+
+const rank = level => LEVELS.indexOf(level);
+const current = () => parseLevel(process.env.HK_LOG);
+export const setLevel = level => { process.env.HK_LOG = parseLevel(level); };
+export const isDebug = () => current() === 'debug';
+
+/** A `normal`-level line. */
+export const info = (...a) => { if (rank(current()) >= rank('normal')) console.error(...a); };
+/** A `verbose`-level line. */
+export const verbose = (...a) => { if (rank(current()) >= rank('verbose')) console.error(...a); };

package/src/mcp.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// MCP server over the housekeeping warehouse.
+//
+// Why this exists: the raw snapshot is ~3 MB of JSON. Pulling that into a model's
+// context to answer "which repos have red CI" is the wrong shape. These tools
+// answer questions and return small tables instead.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EXIT, formatError, readOnlyQuery, structured, userError } from './errors.mjs';
+import { DATA_DIR, PACKAGE_ROOT } from './paths.mjs';
+import { HEAD_CHECKS_RED } from './analyze.mjs';
+
+const DB_FILE = process.env.HK_DB || join(DATA_DIR, 'housekeeping.db');
+const VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+
+if (!existsSync(DB_FILE)) {
+  console.error(formatError(userError('NO_DATABASE', `no database at ${DB_FILE}`, 'run `hk refresh` first')));
+  process.exit(EXIT.USER);
+}
+const db = new DatabaseSync(DB_FILE, { readOnly: true });
+const sid = () => db.prepare('SELECT MAX(id) AS id FROM snapshot').get().id;
+
+/** Render rows as a pipe table: far cheaper in tokens than pretty-printed JSON. */
+function asTable(rows, note) {
+  if (!rows.length) return (note ? note + '\n' : '') + '(no rows)';
+  const cols = Object.keys(rows[0]);
+  const body = [
+    cols.join(' | '),
+    cols.map(() => '---').join(' | '),
+    ...rows.map(r => cols.map(c => String(r[c] ?? '').replace(/\n/g, ' ')).join(' | ')),
+  ].join('\n');
+  return (note ? note + '\n\n' : '') + body + `\n\n(${rows.length} rows)`;
+}
+
+const str = (d) => ({ type: 'string', description: d });
+const int = (d) => ({ type: 'integer', description: d });
+
+const TOOLS = [
+  {
+    name: 'hk_summary',
+    description: 'Portfolio totals for the newest snapshot: repo/issue/PR/workflow/finding counts.',
+    inputSchema: { type: 'object', properties: {} },
+    run: () => {
+      const s = db.prepare('SELECT * FROM snapshot WHERE id=?').get(sid());
+      const t = db.prepare(`SELECT
+        (SELECT COUNT(*) FROM repo WHERE snapshot_id=?1) repos,
+        (SELECT COUNT(*) FROM repo WHERE snapshot_id=?1 AND is_archived=1) archived,
+        (SELECT COUNT(*) FROM repo WHERE snapshot_id=?1 AND is_private=1) private,
+        (SELECT COUNT(*) FROM issue WHERE snapshot_id=?1) open_issues,
+        (SELECT COUNT(*) FROM pull_request WHERE snapshot_id=?1) open_prs,
+        (SELECT COUNT(*) FROM workflow WHERE snapshot_id=?1) workflows,
+        (SELECT COUNT(*) FROM finding WHERE snapshot_id=?1) findings`).get(sid());
+      return asTable([t], `snapshot ${s.id} of ${s.org}, collected ${s.taken_at}`);
+    },
+  },
+  {
+    name: 'hk_findings',
+    description: 'Audit findings, optionally filtered. Omit all filters for counts grouped by code.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        severity: str('critical | high | medium | low | info'),
+        category: str('ci | security | actions | version | hygiene | metadata | docs | backlog | lifecycle | atlas'),
+        code: str('exact finding code, e.g. CI_RUN_FAILING'),
+        repo: str('repo name'),
+        limit: int('max rows, default 100'),
+      },
+    },
+    run: ({ severity, category, code, repo, limit = 100 }) => {
+      const where = ['snapshot_id = ?'], args = [sid()];
+      for (const [col, val] of [['severity', severity], ['category', category], ['code', code], ['repo', repo]]) {
+        if (val) { where.push(`${col} = ?`); args.push(val); }
+      }
+      if (!severity && !category && !code && !repo) {
+        return asTable(db.prepare(`SELECT severity, category, code, COUNT(*) n,
+          COUNT(DISTINCT repo) repos FROM finding WHERE snapshot_id=?
+          GROUP BY severity, category, code
+          ORDER BY CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1
+            WHEN 'medium' THEN 2 WHEN 'low' THEN 3 ELSE 4 END, n DESC`).all(sid()),
+          'All findings grouped by code. Pass a filter to see individual rows.');
+      }
+      return asTable(db.prepare(`SELECT repo, severity, code, message, evidence
+        FROM finding WHERE ${where.join(' AND ')} ORDER BY repo LIMIT ?`).all(...args, limit));
+    },
+  },
+  {
+    name: 'hk_ci',
+    description: 'CI health. Default lists repos whose DEFAULT BRANCH is red (the ones that matter).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scope: str('red_main (default) | scheduled | branches | none | all_runs'),
+      },
+    },
+    run: ({ scope = 'red_main' }) => {
+      if (scope === 'scheduled' || scope === 'branches' || scope === 'none') {
+        const codes = {
+          scheduled: ['CI_SCHEDULED_FAILING'],
+          branches: ['CI_DEPENDABOT_FAILING', 'CI_BRANCH_FAILING'],
+          none: ['CI_NO_WORKFLOWS', 'CI_NEVER_RAN'],
+        }[scope];
+        return asTable(db.prepare(`SELECT repo, code, message, evidence FROM finding
+          WHERE snapshot_id=? AND code IN (${codes.map(() => '?').join(',')})
+          ORDER BY repo`).all(sid(), ...codes));
+      }
+      if (scope === 'all_runs') {
+        return asTable(db.prepare(`SELECT conclusion, COUNT(*) runs FROM workflow_run
+          WHERE snapshot_id=? GROUP BY conclusion ORDER BY runs DESC`).all(sid()));
+      }
+      return asTable(db.prepare(`SELECT r.name repo, r.default_branch branch, r.ci_rollup rollup,
+          (SELECT GROUP_CONCAT(wr.workflow_name, '; ') FROM workflow_run wr
+            WHERE wr.snapshot_id=r.snapshot_id AND wr.repo=r.name AND wr.is_latest_on_default=1
+              AND wr.conclusion='failure' AND wr.event NOT IN ('dynamic','schedule')) failing
+        FROM repo r WHERE r.snapshot_id=? AND r.is_archived=0
+          AND (${HEAD_CHECKS_RED} OR EXISTS (
+            SELECT 1 FROM workflow_run wr WHERE wr.snapshot_id=r.snapshot_id AND wr.repo=r.name
+              AND wr.is_latest_on_default=1 AND wr.conclusion='failure'
+              AND wr.event NOT IN ('dynamic','schedule')))
+        ORDER BY r.name`).all(sid()), 'Repos whose default branch is failing.');
+    },
+  },
+  {
+    name: 'hk_repo',
+    description: 'Everything known about one repo: metadata, findings, workflows, open PRs and issues.',
+    inputSchema: {
+      type: 'object',
+      properties: { name: str('repo name') },
+      required: ['name'],
+    },
+    run: ({ name }) => {
+      const r = db.prepare('SELECT * FROM repo WHERE snapshot_id=? AND name=?').get(sid(), name);
+      if (!r) return `No repo named "${name}" in the newest snapshot.`;
+      const part = (label, rows) => `\n### ${label}\n${asTable(rows)}`;
+      return [
+        asTable([r], `## ${name}`),
+        part('findings', db.prepare('SELECT severity, code, message FROM finding WHERE snapshot_id=? AND repo=? ORDER BY severity').all(sid(), name)),
+        part('workflows', db.prepare('SELECT path, on_triggers, has_paths_filter, has_concurrency, runners, job_count FROM workflow WHERE snapshot_id=? AND repo=?').all(sid(), name)),
+        part('open PRs', db.prepare('SELECT number, age_days, mergeable, author, title FROM pull_request WHERE snapshot_id=? AND repo=? ORDER BY age_days DESC').all(sid(), name)),
+        part('open issues', db.prepare('SELECT number, age_days, stale_days, author, title FROM issue WHERE snapshot_id=? AND repo=? ORDER BY stale_days DESC').all(sid(), name)),
+      ].join('\n');
+    },
+  },
+  {
+    name: 'hk_backlog',
+    description: 'Open pull requests or issues across the org, oldest first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: str('prs (default) | issues'),
+        repo: str('restrict to one repo'),
+        min_age_days: int('only items older than this'),
+        limit: int('max rows, default 50'),
+      },
+    },
+    run: ({ kind = 'prs', repo, min_age_days = 0, limit = 50 }) => {
+      const t = kind === 'issues' ? 'issue' : 'pull_request';
+      const cols = kind === 'issues'
+        ? 'repo, number, age_days, stale_days, comments, author, title'
+        : 'repo, number, age_days, mergeable, is_draft, author, title';
+      const where = ['snapshot_id = ?', 'age_days >= ?'], args = [sid(), min_age_days];
+      if (repo) { where.push('repo = ?'); args.push(repo); }
+      return asTable(db.prepare(`SELECT ${cols} FROM ${t}
+        WHERE ${where.join(' AND ')} ORDER BY age_days DESC LIMIT ?`).all(...args, limit));
+    },
+  },
+  {
+    name: 'hk_health',
+    description: 'Per-repo health score (100 minus severity-weighted findings), worst first.',
+    inputSchema: { type: 'object', properties: { limit: int('default 25') } },
+    run: ({ limit = 25 }) => asTable(db.prepare(`
+      SELECT r.name repo,
+        COALESCE(SUM(CASE f.severity WHEN 'high' THEN 15 WHEN 'medium' THEN 6
+                                     WHEN 'low' THEN 2 ELSE 0 END),0) penalty,
+        COUNT(f.code) findings
+      FROM repo r LEFT JOIN finding f ON f.snapshot_id=r.snapshot_id AND f.repo=r.name
+      WHERE r.snapshot_id=? AND r.is_archived=0
+      GROUP BY r.name ORDER BY penalty DESC, r.name LIMIT ?`).all(sid(), limit)),
+  },
+  {
+    name: 'hk_cost',
+    description: 'GitHub Actions spend. `scope` picks the grain: "repo" (the invoice, per repo), '
+      + '"workflow" or "job" (computed from per-job durations). IMPORTANT: gross and net are '
+      + 'different numbers. GitHub meters public repos at full price and discounts them to zero, '
+      + 'so gross is compute consumed and net is money owed - never report gross as a bill. '
+      + 'Workflow and job grains cover only the repos whose totals reconciled against the invoice; '
+      + 'a repo missing from them was not measured, which is not the same as costing nothing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scope: str('repo | workflow | job (default repo)'),
+        repo: str('restrict to one repo'),
+        limit: int('default 25'),
+      },
+    },
+    run: ({ scope = 'repo', repo, limit = 25 }) => {
+      const s = sid();
+      const has = db.prepare(
+        "SELECT COUNT(*) n FROM billing_usage WHERE snapshot_id=? AND product='actions'").get(s);
+      if (!has.n) return 'No cost data in this snapshot (billing pass absent or unauthorized). '
+        + 'This means NOT MEASURED, not zero cost.';
+      if (scope === 'repo') {
+        return asTable(db.prepare(`SELECT b.repo,
+            ROUND(SUM(b.gross),2) gross_usd, ROUND(SUM(b.net),2) net_usd,
+            CASE WHEN r.is_private=1 THEN 'private' ELSE 'public' END visibility,
+            ROUND(SUM(CASE WHEN b.sku='Actions Linux'       THEN b.quantity ELSE 0 END)) linux_min,
+            ROUND(SUM(CASE WHEN b.sku='Actions Windows'     THEN b.quantity ELSE 0 END)) windows_min,
+            ROUND(SUM(CASE WHEN b.sku LIKE 'Actions macOS%' THEN b.quantity ELSE 0 END)) macos_min
+          FROM billing_usage b LEFT JOIN repo r ON r.snapshot_id=b.snapshot_id AND r.name=b.repo
+          WHERE b.snapshot_id=? AND b.product='actions' AND b.sku<>'Actions storage'
+            AND b.repo IS NOT NULL AND (?2 IS NULL OR b.repo=?2)
+          GROUP BY b.repo ORDER BY SUM(b.gross) DESC LIMIT ?3`).all(s, repo ?? null, limit));
+      }
+      if (scope === 'workflow') {
+        return asTable(db.prepare(`SELECT c.repo, c.workflow_name workflow, COUNT(*) runs,
+            SUM(c.billable_minutes) billable_min, ROUND(SUM(c.cost_usd),2) cost_usd,
+            ROUND(AVG(c.billed_job_count),1) jobs_per_run,
+            SUM(CASE WHEN c.conclusion='failure' THEN c.billable_minutes ELSE 0 END) failed_min,
+            SUM(CASE WHEN c.conclusion='cancelled' THEN c.billable_minutes ELSE 0 END) cancelled_min
+          FROM run_cost c
+          JOIN cost_reconciliation x ON x.snapshot_id=c.snapshot_id AND x.repo=c.repo
+          WHERE c.snapshot_id=? AND x.trustworthy=1 AND (?2 IS NULL OR c.repo=?2)
+          GROUP BY c.repo, c.workflow_name ORDER BY SUM(c.cost_usd) DESC LIMIT ?3`)
+          .all(s, repo ?? null, limit));
+      }
+      return asTable(db.prepare(`SELECT j.repo, c.workflow_name workflow,
+          TRIM(CASE WHEN j.name LIKE '%(%)' THEN SUBSTR(j.name,1,INSTR(j.name,' (')-1)
+                    ELSE j.name END) job,
+          COUNT(DISTINCT j.name) matrix_cells, SUM(j.minutes) billable_min,
+          ROUND(SUM(j.cost_usd),2) cost_usd
+        FROM run_cost_job j JOIN run_cost c
+          ON c.snapshot_id=j.snapshot_id AND c.run_id=j.run_id
+        JOIN cost_reconciliation x ON x.snapshot_id=j.snapshot_id AND x.repo=j.repo
+        WHERE j.snapshot_id=? AND x.trustworthy=1 AND (?2 IS NULL OR j.repo=?2)
+        GROUP BY j.repo, c.workflow_name, job ORDER BY SUM(j.cost_usd) DESC LIMIT ?3`)
+        .all(s, repo ?? null, limit));
+    },
+  },
+  {
+    name: 'hk_sql',
+    description: 'Read-only SQL against the warehouse. Tables: snapshot, repo, topic, language, '
+      + 'issue, pull_request, release, workflow, workflow_run, file_presence, finding, collect_error, '
+      + 'billing_usage, run_cost, run_cost_job, cost_reconciliation. '
+      + 'Every table is keyed by snapshot_id.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: str('a single SELECT or WITH statement') },
+      required: ['query'],
+    },
+    run: ({ query }) => {
+      return asTable(db.prepare(readOnlyQuery(query)).all());
+    },
+  },
+  {
+    name: 'hk_schema',
+    description: 'The warehouse schema - table and column names, for writing hk_sql queries.',
+    inputSchema: { type: 'object', properties: { table: str('one table, or omit for all') } },
+    run: ({ table }) => {
+      const tables = table ? [table]
+        : db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name")
+            .all().map(r => r.name);
+      return tables.map(t => {
+        const cols = db.prepare(`PRAGMA table_info(${t})`).all();
+        if (!cols.length) return `${t}: (unknown table)`;
+        return `${t}(${cols.map(c => c.name).join(', ')})`;
+      }).join('\n');
+    },
+  },
+];
+
+const server = new Server(
+  { name: 'housekeeping', version: VERSION },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = TOOLS.find(t => t.name === req.params.name);
+  // Every failure is a structured result: { code, message, hint, retryable }.
+  // A bad argument or a failing query must never take the server down, and a
+  // stack trace is never sent to the caller.
+  const fail = e => ({ isError: true, content: [{ type: 'text', text: JSON.stringify(structured(e)) }] });
+  if (!tool) return fail(userError('UNKNOWN_TOOL', `unknown tool "${req.params.name}"`, `tools: ${TOOLS.map(t => t.name).join(', ')}`));
+  try {
+    return { content: [{ type: 'text', text: tool.run(req.params.arguments ?? {}) }] };
+  } catch (e) {
+    return fail(e);
+  }
+});
+
+await server.connect(new StdioServerTransport());
+console.error(`[hk-mcp] serving ${TOOLS.length} tools from ${DB_FILE}`);

package/src/paths.mjs

@@ -0,0 +1,31 @@
+// Where housekeeping reads its own files and where it writes yours.
+//
+// Two kinds of path, kept apart on purpose:
+//
+//   PACKAGE_ROOT  what ships inside the package: src/schema.sql, package.json.
+//                 Always relative to this file.
+//   WORK_DIR      what a sweep writes and reads back: data/ (snapshots, the
+//                 database, the caches, the sweep log), reports/, and
+//                 housekeeping.config.json.
+//
+// WORK_DIR is HK_HOME when it is set. Otherwise it is the package root when
+// housekeeping runs from a git checkout -- a clone, or `npm link` of one --
+// which is how it has always behaved; and the current directory when it runs
+// from an installed package, the way git and npm themselves work. Writing into
+// an installed package would put a warehouse inside node_modules, where it can
+// be read-only and where the next upgrade deletes it.
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The directory housekeeping writes to. Pure given its inputs. */
+export function workDir({ env = process.env, root = PACKAGE_ROOT, cwd = process.cwd(), exists = existsSync } = {}) {
+  if (env.HK_HOME) return resolve(env.HK_HOME);
+  return exists(join(root, '.git')) ? root : cwd;
+}
+
+export const WORK_DIR = workDir();
+export const DATA_DIR = join(WORK_DIR, 'data');
+export const REPORTS_DIR = join(WORK_DIR, 'reports');