clembot-doorman 0.1.0

package/doorman/scripts/vet.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * /vet, as a program.
+ *
+ *   node scripts/vet.mjs <url|repo|path> --needed-for "what you want it for"
+ *   node scripts/vet.mjs <...> --type repo        force the candidate type
+ *   node scripts/vet.mjs <...> --dry-run          fit only, never touch the scorecard
+ *
+ * Fit first, money second. A redundant candidate returns before a scorecard
+ * client is constructed, which is why the slash command is a thin wrapper over
+ * this rather than prose that asks an agent to remember the order.
+ *
+ * Env: ANTHROPIC_API_KEY, DOORMAN_MODEL, DOORMAN_INVENTORY_ROOT,
+ *      DOORMAN_VAULT_PATH, SCORECARD_API,
+ *      DOORMAN_MAX_USDC_PER_RUN, DOORMAN_MAX_USDC_PER_DAY. See env.example.
+ *
+ * Never calls process.exit(): on Node 25 / Windows that trips a libuv assertion
+ * during teardown and replaces the real exit code with 127.
+ */
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { anthropicClient, MissingApiKeyError } from '../src/llm.mjs';
+import { openBudget, DEFAULT_PER_DAY_USDC, DEFAULT_PER_RUN_USDC } from '../src/budget.mjs';
+import { scorecardClient } from '../src/scorecard.mjs';
+import { runVet } from '../src/vet.mjs';
+import { writeNote } from '../src/note.mjs';
+import { findInventoryRoot, gatherInventory } from '../src/inventory.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REGISTRY = join(HERE, '..', 'registry');
+
+const args = parse(process.argv.slice(2));
+const target = args._[0];
+
+if (!target || args.help) {
+  console.log(`
+doorman vet
+
+  node scripts/vet.mjs <url|repo|path> [options]
+
+  --needed-for TXT   what you want it for. Seeds the fit review and the probes.
+  --type TYPE        mcp-server | skill | repo. Overrides detection.
+  --dry-run          fit review only. Never constructs a scorecard client.
+  --no-note          print the result, write no note.
+  --max-usdc N       per-run spend cap. Default DOORMAN_MAX_USDC_PER_RUN, else 1.
+  --max-usdc-day N   per-day spend cap. Default DOORMAN_MAX_USDC_PER_DAY, else 5.
+
+The price is read from the service, never assumed. If it cannot be read the
+run stops without spending: an unknown price is not a free one.
+
+Fit runs first and is free. The paid grade only fires if fit passes AND the
+candidate is an MCP server. A redundant candidate costs nothing.
+`);
+  process.exitCode = target ? 0 : 1;
+} else {
+  await main().catch((e) => {
+    console.error('\n' + (e instanceof MissingApiKeyError ? e.message : `error: ${e.message}`) + '\n');
+    process.exitCode = 1;
+  });
+}
+
+async function main() {
+  const root = process.env.DOORMAN_INVENTORY_ROOT || findInventoryRoot(process.cwd());
+  const inventory = gatherInventory({ root, registryDir: REGISTRY });
+
+  console.log(`\n  candidate  ${target}`);
+  console.log(`  inventory  ${root ?? 'NONE FOUND'} - ${inventory.agents.length} agents, ` +
+              `${inventory.skills.length} skills, ${inventory.mcpServers.length} mcp servers`);
+  for (const n of inventory.notes) console.log(`             gap: ${n}`);
+
+  const llm = anthropicClient({
+    apiKey: process.env.ANTHROPIC_API_KEY,
+    model: process.env.DOORMAN_MODEL,
+  });
+
+  const budget = args['dry-run'] ? undefined : openBudget({
+    ledgerPath: join(REGISTRY, 'spend.ndjson'),
+    perRunUsdc: num(args['max-usdc'], process.env.DOORMAN_MAX_USDC_PER_RUN, DEFAULT_PER_RUN_USDC),
+    perDayUsdc: num(args['max-usdc-day'], process.env.DOORMAN_MAX_USDC_PER_DAY, DEFAULT_PER_DAY_USDC),
+  });
+  if (budget) {
+    console.log(`  budget     ${budget.spentToday()} spent today, ${budget.remainingToday()} of ` +
+                `${budget.perDayUsdc} left. Per-run cap ${budget.perRunUsdc}.`);
+    if (budget.damagedLines) {
+      console.log(`  WARNING    ${budget.damagedLines} unreadable line(s) in the spend ledger. ` +
+                  'Today may be under-counted.');
+    }
+  }
+
+  const api = process.env.SCORECARD_API;
+  const makeScorecard = args['dry-run']
+    ? undefined
+    : () => {
+        if (!api) throw new Error('SCORECARD_API is not set, so the paid grade cannot run');
+        return scorecardClient({ api, budget });
+      };
+
+  const result = await runVet(target, {
+    llm, makeScorecard, budget, inventory,
+    needed_for: args['needed-for'],
+    type: args.type,
+  });
+
+  report(result);
+
+  if (!args['no-note']) {
+    const w = writeNote(result, {
+      vaultPath: process.env.DOORMAN_VAULT_PATH,
+      registryDir: REGISTRY,
+    });
+    if (w.warning) console.log(`\n  WARNING  ${w.warning}`);
+    console.log(`\n  note     ${w.path}${w.fellBack ? '  (fallback, not the vault)' : ''}`);
+    console.log('           status: pending. Nothing is allowlisted until you flip it.');
+  }
+}
+
+/** One blank line. Written this way so no anchor in this file needs an escape. */
+const BLANK = String.fromCharCode(10);
+
+function report(r) {
+  const f = r.fit;
+  console.log(`\n  FIT      ${f.verdict.toUpperCase()}${f.owner ? ' -> ' + f.owner : ''}`);
+  console.log(`           ${f.rationale}`);
+  if (f.overlaps.length) {
+    console.log('\n  Already covered by:');
+    for (const o of f.overlaps) console.log(`    - ${o.kind} ${o.name}: ${o.why}`);
+  }
+
+  if (r.stopped_at === 'fit') {
+    console.log('\n  STOPPED before the paid grade. $0.00 spent.');
+    console.log('           Nothing was sent to the scorecard, and no client was built.');
+    return;
+  }
+  if (r.stopped_at === 'budget') {
+    console.log(BLANK + '  REFUSED  the spend cap said no. $0.00 spent.');
+    console.log('           ' + r.why);
+    console.log('           Raise it with --max-usdc / --max-usdc-day if you mean to.');
+    return;
+  }
+  if (r.stopped_at === 'price-unknown') {
+    console.log(BLANK + '  REFUSED  could not read the price, so nothing was bought.');
+    console.log('           ' + r.why);
+    console.log('           An unknown price is not a free one.');
+    return;
+  }
+  if (r.stopped_at === 'scan') {
+    console.log(`\n  SCAN     ${r.scan.hard} hard, ${r.scan.steering} steering ` +
+                `over ${r.scan.scanned_chars} chars${r.scan.truncated ? ' (TRUNCATED)' : ''}`);
+    console.log('           behavioral grade: n/a - no tools to probe');
+    for (const m of r.scan.failure_modes.slice(0, 3)) console.log(`    - ${m}`);
+    return;
+  }
+  if (r.stopped_at === 'queued') {
+    console.log(BLANK + `  SPENT    ${r.cost_usdc} USDC` +
+                (r.cost_usdc === 0 ? '  (the service states it is free right now)' : ''));
+  }
+  if (r.grade) {
+    console.log(`\n  GRADE    ${r.grade.grade} ${r.grade.score}/100  (cached)`);
+    if (r.grade.hard_fail) console.log(`           HARD FAIL: ${r.grade.hard_fail}`);
+    console.log(`           tape: ${r.transcripts}`);
+    return;
+  }
+  console.log(`\n  QUEUED   audit ${r.audit_id}`);
+  console.log('           No grade yet, and no estimate of one. Run the probe runner.');
+  console.log(`           tape (once it exists): ${r.transcripts}`);
+}
+
+/** First finite number among a CLI flag, an env var, and a default. */
+function num(...candidates) {
+  for (const c of candidates) {
+    const n = typeof c === 'number' ? c : Number(c);
+    if (c !== undefined && c !== true && c !== '' && Number.isFinite(n)) return n;
+  }
+  return undefined;
+}
+
+function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) { out[k] = next; i++; }
+      else out[k] = true;
+    } else out._.push(a);
+  }
+  return out;
+}

package/doorman/skills/doorman-guide/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: doorman-guide
+description: Package manager and security gate for agent tools. Inspects your build, analyzes prompt history to recommend safe MCP servers, audits candidate tools for prompt injections, runs local fit reviews against existing skills, and blocks rogue tools at the gate.
+---
+
+# Doorman Skill
+
+The package manager and security doorman for AI agents.
+
+Use this skill when:
+- Setting up a net-new agent build or inspecting what tools your project can currently reach.
+- Recommending or discovering new MCP tools and skills based on real user prompt history.
+- Evaluating a candidate MCP server, GitHub repository, or new skill before installing it.
+- Checking whether a proposed capability is already covered by existing skills or subagents.
+- Verifying the local offline security hook (`PreToolUse` gate).
+
+---
+
+## Capabilities & Commands
+
+### 1. Inspect Your Build (`doorman doctor`)
+```bash
+doorman doctor
+```
+- **L0 check**: 100% local, read-only, costs zero tokens.
+- Reports active harness (Claude Code, Cursor, Windsurf, Copilot, Gemini), reachable MCP servers, subagents, and gate wiring status.
+- Calculates agent-to-tool exposure ratios to stop tool bloat.
+
+### 2. Discover Needs from Prompts (`doorman needs`)
+```bash
+doorman needs
+```
+- Reads local session transcripts (`~/.claude/projects/`).
+- Strips tool outputs, compaction summaries, and slash-command expansions to isolate real human asks.
+- Categorizes needs across 12 taxonomies (`docs-lookup`, `web-search`, `database`, `browser-automation`, `cloud-deploy`, `observability`, `payments`, `comms`, `design-assets`, `knowledge-base`, `code-host`, `data-files`).
+- Suppresses recommendations for needs already satisfied (`COVERED`).
+- Pairs unmet needs with pre-vetted Grade A/B candidates from `scorecard.wanessalabs.com/feed` (`worth-measuring`), flags malicious ones (`blocked`), or notes ecosystem gaps (`GAP`).
+
+### 3. Two-Phase Fit Review (`scripts/vet.mjs --dry-run`)
+```bash
+node scripts/vet.mjs <candidate-url-or-repo> --dry-run
+```
+- **Fit first, money second**: Ingests YAML frontmatter (`name`, `description`) of all installed skills and agents.
+- If an existing skill already handles the ask, it returns `REDUNDANT` and cites the exact skill name.
+- Stops immediately at Phase 1 ($0.00 spent) before contacting any external scorecard.
+
+### 4. Static Protocol & Injection Scan (`doorman report <url>`)
+```bash
+doorman report <url>
+```
+- Scans MCP tool descriptions for prompt injection, hidden steering ads, and protocol violations.
+- Caught WebZum's 6,290-character in-context steering ad on live internet.
+- Caps hostile tools at Grade F.
+
+### 5. Monitor Live Feed (`doorman watch`)
+```bash
+doorman watch --all
+```
+- Streams newly graded candidates from the public feed.
+- Categorizes them against local inventory: `already-installed`, `blocked`, `unreviewed`.
+- Warns if an installed server suffers a security demotion.
+
+---
+
+## Guiding Principles
+
+1. **Say No to Redundant Tools**: A tool that duplicates an existing skill costs tokens, pollutes context, and increases hallucination risk. Always run the fit review first.
+2. **Never Grade Documentation as Proof**: Documentation describes what authors wish was true. Doorman measures what tools actually do when an agent executes them.
+3. **Fail Closed**: If a tool is unapproved or cannot be verified, the gate blocks it at exit 2. Never bypass the security hook.

package/doorman/src/budget.mjs

@@ -0,0 +1,236 @@
+/**
+ * The spend cap. The doorman's second refusal, after fit.
+ *
+ * Fit answers "does my system need this at all". This answers "can I afford to
+ * find out". They are different refusals and both have to be structural,
+ * because an agent that can spend money on your behalf while you are asleep is
+ * only as safe as the thing that says no.
+ *
+ * ## The guarantee, and why it is a permit
+ *
+ * `scorecard.enqueue()` will not spend without a **permit**, and a permit is
+ * single-use. That is stronger than checking a number before calling: a check
+ * can be skipped by a new code path, forgotten in a refactor, or bypassed by a
+ * caller that does not know it exists. A required argument cannot.
+ *
+ *     const permit = budget.reserve({ price_usdc, server });   // may throw
+ *     await scorecard.enqueue({ ..., permit });                // throws without
+ *     budget.settle(permit, { audit_id });
+ *
+ * Same shape as invariant 13: a path that CANNOT spend is easier to prove than
+ * a path that remembers not to.
+ *
+ * ## An unknown price is not free
+ *
+ * `reserve()` refuses a null, undefined, negative or non-finite price. The
+ * tempting default is 0, and 0 passes every cap forever. This is the same
+ * mistake as scoring an unmeasured layer zero, pointed at money instead of at
+ * a grade.
+ *
+ * ## Reservations count against the cap until they are released
+ *
+ * The ledger is written BEFORE the call, not after. If the process dies
+ * mid-request, the ledger shows a reservation that never settled, and today's
+ * spend is over-counted rather than under-counted. Over-counting refuses a call
+ * you could have afforded; under-counting spends money you did not have. Only
+ * one of those is recoverable by waiting until tomorrow.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export class BudgetError extends Error {}
+export class BudgetExceededError extends BudgetError {}
+
+/** Deliberately small. A cap you have to raise on purpose is doing its job. */
+export const DEFAULT_PER_RUN_USDC = 1;
+export const DEFAULT_PER_DAY_USDC = 5;
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.ledgerPath]     NDJSON, append-only. Omit for in-memory.
+ * @param {number} [opts.perRunUsdc]
+ * @param {number} [opts.perDayUsdc]
+ * @param {Function} [opts.now]          injectable clock
+ * @param {Function} [opts.randomId]     injectable id, for deterministic tests
+ */
+export function openBudget(opts = {}) {
+  const {
+    ledgerPath,
+    perRunUsdc = DEFAULT_PER_RUN_USDC,
+    perDayUsdc = DEFAULT_PER_DAY_USDC,
+    now = () => new Date(),
+    randomId = () => 'permit_' + Math.random().toString(36).slice(2, 10),
+  } = opts;
+
+  for (const [k, v] of Object.entries({ perRunUsdc, perDayUsdc })) {
+    if (!Number.isFinite(v) || v < 0) {
+      throw new BudgetError(`${k} must be a finite number >= 0, got ${v}`);
+    }
+  }
+  if (perRunUsdc > perDayUsdc) {
+    // Not a hypothetical: it means one call can exceed the daily cap, so the
+    // daily cap silently does nothing. Better to refuse the configuration.
+    throw new BudgetError(
+      `perRunUsdc (${perRunUsdc}) is above perDayUsdc (${perDayUsdc}), so the ` +
+      'daily cap could never bind. Fix the configuration rather than shipping ' +
+      'a limit that does not limit.',
+    );
+  }
+
+  /** In-memory mirror. The file is the record; this avoids re-reading per call. */
+  const loaded = ledgerPath ? readLedger(ledgerPath) : { entries: [], skipped: 0 };
+  const entries = loaded.entries;
+  const open = new Map();          // permit id -> reservation, unsettled
+
+  const write = (entry) => {
+    entries.push(entry);
+    if (!ledgerPath) return;
+    mkdirSync(dirname(ledgerPath), { recursive: true });
+    appendFileSync(ledgerPath, JSON.stringify(entry) + '\n', 'utf8');
+  };
+
+  const today = () => now().toISOString().slice(0, 10);
+
+  /**
+   * Committed plus outstanding, for today only.
+   *
+   * A `release` cancels its own `reserve`. A `settle` does not: settling means
+   * the money went out, so it stays counted.
+   */
+  const spentToday = () => {
+    const day = today();
+    const released = new Set(
+      entries.filter((e) => e.event === 'release').map((e) => e.permit),
+    );
+    return round4(
+      entries
+        .filter((e) => e.event === 'reserve' && e.ts.slice(0, 10) === day)
+        .filter((e) => !released.has(e.permit))
+        .reduce((a, e) => a + e.price_usdc, 0),
+    );
+  };
+
+  return {
+    perRunUsdc,
+    perDayUsdc,
+    ledgerPath: ledgerPath ?? null,
+    spentToday,
+    remainingToday: () => round4(Math.max(0, perDayUsdc - spentToday())),
+    entries: () => entries.slice(),
+    /** Unparseable ledger lines found at open. Reported, never silently zero. */
+    damagedLines: loaded.skipped,
+
+    /**
+     * Claim headroom for one paid call. Throws rather than returning a falsy
+     * value: a caller that ignores a return value must not end up spending.
+     * @returns {{id: string, price_usdc: number, server: string, ts: string}}
+     */
+    reserve({ price_usdc, server = '(unnamed)' } = {}) {
+      if (typeof price_usdc !== 'number' || !Number.isFinite(price_usdc)) {
+        throw new BudgetError(
+          'reserve() needs a numeric price_usdc. An unknown price is not a free ' +
+          'one: refusing to spend against a number nobody supplied. Read the ' +
+          'price from the 402 challenge, or set it in config.',
+        );
+      }
+      if (price_usdc < 0) throw new BudgetError('price_usdc cannot be negative');
+
+      if (price_usdc > perRunUsdc) {
+        throw new BudgetExceededError(
+          `this call costs ${price_usdc} USDC and the per-run cap is ${perRunUsdc}. ` +
+          'Nothing was spent.',
+        );
+      }
+      const after = round4(spentToday() + price_usdc);
+      if (after > perDayUsdc) {
+        throw new BudgetExceededError(
+          `this call costs ${price_usdc} USDC, today's spend is already ` +
+          `${spentToday()}, and the daily cap is ${perDayUsdc}. Nothing was spent.`,
+        );
+      }
+
+      const permit = {
+        id: randomId(),
+        price_usdc,
+        server,
+        ts: now().toISOString(),
+      };
+      open.set(permit.id, permit);
+      write({
+        event: 'reserve', permit: permit.id, price_usdc,
+        server, ts: permit.ts,
+      });
+      return permit;
+    },
+
+    /** The call happened. The money is spent and stays counted. */
+    settle(permit, { audit_id = null } = {}) {
+      assertOpen(open, permit);
+      open.delete(permit.id);
+      write({
+        event: 'settle', permit: permit.id, price_usdc: permit.price_usdc,
+        server: permit.server, audit_id, ts: now().toISOString(),
+      });
+      return permit;
+    },
+
+    /** The call did not happen. Give the headroom back, with a reason. */
+    release(permit, reason = 'unspecified') {
+      assertOpen(open, permit);
+      open.delete(permit.id);
+      write({
+        event: 'release', permit: permit.id, price_usdc: permit.price_usdc,
+        server: permit.server, reason, ts: now().toISOString(),
+      });
+      return permit;
+    },
+
+    /**
+     * Used by the paid client. A permit is valid exactly once and only while
+     * open, so a replayed or already-settled permit cannot buy a second audit.
+     */
+    isOpen: (permit) => Boolean(permit?.id) && open.has(permit.id),
+  };
+}
+
+function assertOpen(open, permit) {
+  if (!permit?.id) throw new BudgetError('not a permit');
+  if (!open.has(permit.id)) {
+    throw new BudgetError(
+      `permit ${permit.id} is not open: it was already settled or released. ` +
+      'Reserve a new one rather than reusing this.',
+    );
+  }
+}
+
+/**
+ * Read an NDJSON ledger, skipping lines that do not parse.
+ *
+ * A corrupt line is skipped rather than thrown on, because a half-written line
+ * from a killed process must not lock the doorman out of spending forever. It
+ * is counted in `skipped` so the CLI can say the ledger is damaged instead of
+ * quietly under-counting the day.
+ *
+ * @returns {{entries: object[], skipped: number}}
+ */
+export function readLedger(path) {
+  if (!existsSync(path)) return { entries: [], skipped: 0 };
+  const out = [];
+  let skipped = 0;
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e.price_usdc === 'number' && typeof e.ts === 'string') out.push(e);
+      else skipped++;
+    } catch {
+      skipped++;
+    }
+  }
+  return { entries: out, skipped };
+}
+
+function round4(n) {
+  return Math.round(n * 10000) / 10000;
+}

package/doorman/src/candidate.mjs

@@ -0,0 +1,132 @@
+/**
+ * What kind of thing are we being asked to vet?
+ *
+ * ── Syntactic, and offline ───────────────────────────────────────────────────
+ *
+ * The obvious implementation probes the URL and sees whether it speaks MCP.
+ * This does not, for two reasons. CI has to run with no network, and a probe
+ * would mean connecting to an unvetted endpoint as the FIRST thing we do,
+ * before anything has decided the candidate is worth touching at all.
+ *
+ * So detection reads the string. It will occasionally be wrong, which is why
+ * `--type` exists and why the type is printed in the report.
+ *
+ * ── Why the type decides the money ───────────────────────────────────────────
+ *
+ * Only `mcp-server` may reach the paid scorecard. A skill or a repo has no
+ * tools to drive, so a behavioural grade is not a thing that can exist for it,
+ * and the report says `behavioral grade: n/a` rather than implying one ran.
+ * `mayBeGraded()` is the single place that rule lives.
+ */
+
+export const CANDIDATE_TYPES = ['mcp-server', 'skill', 'repo'];
+
+/** Only this type may ever be sent to the paid scorecard. */
+export function mayBeGraded(type) {
+  return type === 'mcp-server';
+}
+
+export class CandidateError extends Error {}
+
+/**
+ * @param {string} input  a url, or a local path to a markdown file
+ * @param {object} [opts] `{ type }` forces the answer
+ * @returns {{ id, type, kind, host, forced }}
+ */
+export function detectCandidate(input, { type } = {}) {
+  const raw = String(input ?? '').trim();
+  if (!raw) throw new CandidateError('no candidate given');
+
+  if (type !== undefined) {
+    if (!CANDIDATE_TYPES.includes(type)) {
+      throw new CandidateError(
+        `unknown --type ${JSON.stringify(type)}; must be one of ` + CANDIDATE_TYPES.join(', '),
+      );
+    }
+    return { id: raw, type, host: hostOf(raw), forced: true };
+  }
+
+  // A local path. Only markdown is a skill; anything else we decline to guess
+  // about rather than sending a directory to the grader.
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    if (/\.md$/i.test(raw)) return { id: raw, type: 'skill', host: null, forced: false };
+    throw new CandidateError(
+      `"${raw}" is not a url and is not a .md file, so its type cannot be inferred. ` +
+      'Pass --type mcp-server|skill|repo.',
+    );
+  }
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new CandidateError(`"${raw}" is not a valid url`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new CandidateError(`unsupported scheme ${url.protocol} in "${raw}"`);
+  }
+
+  const host = url.hostname.toLowerCase();
+  const path = url.pathname.replace(/\/+$/, '');
+
+  // A gist is a skill. A raw .md anywhere is a skill.
+  if (host === 'gist.github.com' || /\.md$/i.test(path)) {
+    return { id: raw, type: 'skill', host, forced: false };
+  }
+
+  if (host === 'github.com' || host === 'www.github.com') {
+    const segments = path.split('/').filter(Boolean);
+    // /owner/repo/blob/... points at a file, which is a skill, not a repo.
+    if (segments.length >= 4 && (segments[2] === 'blob' || segments[2] === 'raw')) {
+      return { id: raw, type: 'skill', host, forced: false };
+    }
+    if (segments.length >= 2) {
+      return { id: raw, type: 'repo', host, forced: false };
+    }
+    // github.com with one segment or none is a user or the site itself.
+    throw new CandidateError(
+      `"${raw}" points at github.com but names no repository. ` +
+      'Pass --type, or give a full owner/repo url.',
+    );
+  }
+
+  // Everything else that is an http(s) endpoint is treated as an MCP server.
+  // This is the only branch that can lead to a paid grade, and it is the
+  // default rather than a special case because that is what people paste.
+  return { id: raw, type: 'mcp-server', host, forced: false };
+}
+
+function hostOf(raw) {
+  try {
+    return new URL(raw).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A filesystem-safe slug for the review note filename.
+ *
+ * Uses the FULL hostname for a url. The scorecard's poller learned this the
+ * hard way: keying on the first label collapsed every `mcp.<vendor>.com` onto
+ * the key `mcp`, so allowlisting one vendor silently allowlisted another. A
+ * filename is not a trust decision, but two candidates sharing a note file
+ * would overwrite each other's evidence, which is bad in the same direction.
+ */
+export function candidateSlug(candidate) {
+  const raw = candidate.id ?? String(candidate);
+  let base;
+  try {
+    const u = new URL(raw);
+    base = u.hostname + u.pathname;
+  } catch {
+    base = raw.replace(/^.*[\\/]/, '');           // a local path: keep the filename
+  }
+  const slug = base
+    .toLowerCase()
+    .replace(/\.md$/, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+  return slug || 'candidate';
+}