@redential/cli 0.1.0

package/dist/skill-detect.js

@@ -0,0 +1,234 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { getCommitAddedLines } from "./git.js";
+import { isExcludedPath, heuristicallyGeneratedPaths } from "./churn-exclusions.js";
+import { extractImportedPackages } from "./import-detect.js";
+import { ScanError } from "./errors.js";
+// Default locations ship alongside dist/ in the published package (see
+// package.json's "files") — src/ and dist/ sit at the same depth from the
+// package root, so this resolves correctly both in dev and post-build.
+const DEFAULT_SIGNATURES_DIR = fileURLToPath(new URL("../signatures", import.meta.url));
+const DEFAULT_TAXONOMY_PATH = fileURLToPath(new URL("../taxonomy.json", import.meta.url));
+const DEFAULT_PACKAGE_MAP_PATH = fileURLToPath(new URL("../signatures/package-map.json", import.meta.url));
+// A single added line long enough to be minified/generated noise, not a
+// hand-authored import or API call — never worth pattern-matching, and
+// bounds worst-case regex time on pathological input.
+const MAX_MATCHED_LINE_LENGTH = 2000;
+function boundedAddedLines(addedLines) {
+    return addedLines
+        .split("\n")
+        .filter((line) => line.length <= MAX_MATCHED_LINE_LENGTH)
+        .join("\n");
+}
+// package-map.json is Tier 1's own data file, sitting directly under
+// signatures/ (not inside a category subdirectory) — it has a different
+// shape entirely ({"map": {...}}, not {"slug", "fixtures", ...}) and must
+// never be picked up as if it were a Tier 2 signature file.
+const PACKAGE_MAP_FILENAME = "package-map.json";
+function listJsonFilesRecursive(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...listJsonFilesRecursive(full));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".json") && entry.name !== PACKAGE_MAP_FILENAME) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * Loads every `signatures/**\/*.json` file EXCEPT package-map.json (Tier
+ * 1's own data file — see loadPackageMap). `dir` is overridable ONLY so
+ * tests (including the privacy test that proves a hostile signature can't
+ * escape) can point detection at a fixture directory instead of the real
+ * shipped one — production code always uses the default.
+ */
+export function loadSignatures(dir = DEFAULT_SIGNATURES_DIR) {
+    return listJsonFilesRecursive(dir).map((file) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            // Never echo file content in the error — just which file is broken.
+            throw new ScanError(`Malformed signature file: ${file}`);
+        }
+        const sig = parsed;
+        if (typeof sig.slug !== "string" || !sig.fixtures) {
+            throw new ScanError(`Signature file missing required fields: ${file}`);
+        }
+        return sig;
+    });
+}
+/** Same override rationale as loadSignatures. */
+export function loadTaxonomySlugs(path = DEFAULT_TAXONOMY_PATH) {
+    const taxonomy = JSON.parse(readFileSync(path, "utf8"));
+    return new Set(taxonomy.skills.map((s) => s.slug));
+}
+/**
+ * Tier 1's data source (docs/signatures.md): flat package-name -> slug map.
+ * Same override rationale as loadSignatures/loadTaxonomySlugs — production
+ * always uses the shipped default.
+ */
+export function loadPackageMap(path = DEFAULT_PACKAGE_MAP_PATH) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new ScanError(`Malformed package map file: ${path}`);
+    }
+    const map = parsed.map;
+    if (!map)
+        throw new ScanError(`Package map file missing "map" field: ${path}`);
+    return new Map(Object.entries(map));
+}
+function compile(signatures, taxonomySlugs) {
+    return signatures.map((sig) => {
+        // Defense in depth: the closed-vocabulary rule is enforced HERE, inside
+        // the function runScan actually calls (see scan.ts) — not just as a
+        // standalone check a future refactor could unwire without failing any
+        // test. A signature file naming a slug outside taxonomy.json can never
+        // reach matching, let alone the bundle.
+        if (!taxonomySlugs.has(sig.slug)) {
+            throw new ScanError(`Signature slug "${sig.slug}" is not in taxonomy.json.`);
+        }
+        try {
+            return compileOne(sig);
+        }
+        catch {
+            // Never echo the (possibly-malformed) pattern source, just which
+            // signature it came from.
+            throw new ScanError(`Signature "${sig.slug}" has an invalid regex pattern.`);
+        }
+    });
+}
+function matches(file, sig) {
+    if (sig.configFileRegexes.some((r) => r.test(file.path)))
+        return true;
+    const text = boundedAddedLines(file.addedLines);
+    if (sig.importRegexes.some((r) => r.test(text)))
+        return true;
+    if (sig.apiRegexes.some((r) => r.test(text)))
+        return true;
+    return false;
+}
+function compileOne(sig) {
+    return {
+        slug: sig.slug,
+        importRegexes: (sig.importPatterns ?? []).map((p) => new RegExp(p)),
+        apiRegexes: (sig.apiPatterns ?? []).map((p) => new RegExp(p)),
+        configFileRegexes: (sig.configFilePatterns ?? []).map((p) => new RegExp(p)),
+    };
+}
+/**
+ * Test-only entry point (exported so test/skill-detect.test.ts exercises
+ * the SAME matching primitive `detectSkills` uses, not a reimplementation
+ * of it — same rationale as the fixtures living inside each signature
+ * file). Not used by production scanning, which always goes through
+ * `detectSkills`'s per-commit loop.
+ */
+export function fixtureMatches(sig, fixture) {
+    return matches({ path: fixture.path, addedLines: fixture.diff }, compileOne(sig));
+}
+/** Per-pattern hit map for one fixture against one signature — lets the
+ * generic test assert every declared pattern is exercised by at least one
+ * positive fixture, catching a dead or typo'd pattern that would otherwise
+ * silently never fire. */
+export function fixtureCoverage(sig, fixture) {
+    const compiled = compileOne(sig);
+    return {
+        importPatterns: compiled.importRegexes.map((r) => r.test(fixture.diff)),
+        apiPatterns: compiled.apiRegexes.map((r) => r.test(fixture.diff)),
+        configFilePatterns: compiled.configFileRegexes.map((r) => r.test(fixture.path)),
+    };
+}
+/**
+ * Deterministic, local, two-tier skill detection (principle 3, "Bounded
+ * output") — see docs/signatures.md. Tier 1: generic import parsing
+ * (src/import-detect.ts) against signatures/package-map.json's flat
+ * package-name -> slug map, for the common case where a bare import
+ * unambiguously identifies the slug. Tier 2: the remaining signatures/*.json
+ * files, for config-file-based tech (no import at all, e.g. Docker) or
+ * usage ambiguous by import alone (e.g. @supabase/supabase-js serves both
+ * auth/supabase-auth and db/supabase — deliberately absent from the map,
+ * disambiguated by API-call shape instead). Zero network, no LLMs.
+ *
+ * Merge commits are skipped, same as getAllCommits' own numstat (which
+ * emits none for them) — no combined-diff handling needed. Files excluded
+ * from churn (lockfiles, build output, single-commit generated dumps —
+ * src/churn-exclusions.ts) are excluded here too, for BOTH tiers: a
+ * vendored dependency's content matching an import pattern would be a
+ * false "you wrote this" signal, not a real one.
+ */
+export function detectSkills(userCommits, repoPath, opts = {}) {
+    const signatures = loadSignatures(opts.signaturesDir);
+    const taxonomySlugs = loadTaxonomySlugs(opts.taxonomyPath);
+    const compiled = compile(signatures, taxonomySlugs);
+    const packageMap = loadPackageMap(opts.packageMapPath);
+    // Same defense-in-depth rationale as compile()'s per-signature check:
+    // enforced inside the function runScan actually calls, not just in a
+    // standalone test, so a future refactor can't silently unwire it.
+    for (const slug of packageMap.values()) {
+        if (!taxonomySlugs.has(slug)) {
+            throw new ScanError(`Package map entry targets slug "${slug}", which is not in taxonomy.json.`);
+        }
+    }
+    const generatedPaths = heuristicallyGeneratedPaths(userCommits);
+    const matchedCommits = new Map();
+    const matchedDates = new Map();
+    const recordMatch = (slug, commit) => {
+        if (matchedCommits.get(slug)?.has(commit.sha))
+            return;
+        if (!matchedCommits.has(slug))
+            matchedCommits.set(slug, new Set());
+        matchedCommits.get(slug).add(commit.sha);
+        if (!matchedDates.has(slug))
+            matchedDates.set(slug, []);
+        matchedDates.get(slug).push(commit.authorDate);
+    };
+    for (const commit of userCommits) {
+        if (commit.isMerge)
+            continue;
+        const files = getCommitAddedLines(repoPath, commit.sha).filter((f) => !isExcludedPath(f.path) && !generatedPaths.has(f.path));
+        if (files.length === 0)
+            continue;
+        for (const file of files) {
+            // Tier 1: generic import detection against the flat package map.
+            for (const pkg of extractImportedPackages(file.addedLines, file.path)) {
+                const slug = packageMap.get(pkg);
+                if (slug)
+                    recordMatch(slug, commit);
+            }
+        }
+        // Tier 2: config-file/API-usage signatures.
+        for (const sig of compiled) {
+            if (matchedCommits.get(sig.slug)?.has(commit.sha))
+                continue;
+            if (files.some((f) => matches(f, sig)))
+                recordMatch(sig.slug, commit);
+        }
+    }
+    const result = [];
+    for (const [slug, shas] of matchedCommits) {
+        const dates = matchedDates.get(slug);
+        const sorted = [...dates].sort((a, b) => a.getTime() - b.getTime());
+        result.push({
+            slug,
+            commit_count: shas.size,
+            first_seen: sorted[0].toISOString(),
+            last_seen: sorted[sorted.length - 1].toISOString(),
+        });
+    }
+    // Deterministic output (principle 4, "User-reviewed": the printed bundle
+    // must be byte-identical across runs over the same history) — Map
+    // insertion order otherwise depends on which commit happened to match
+    // which signature first.
+    result.sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+    return result;
+}

package/dist/submit-command.js

@@ -0,0 +1,49 @@
+import { buildBundleInteractively } from "./build-bundle.js";
+import { AuthError, SubmitError } from "./errors.js";
+import { getSiteUrl } from "./config.js";
+import { readCredentials } from "./credentials.js";
+import { getRemoteUrl } from "./git.js";
+import { checkVisibilityGate, postBundle } from "./submit.js";
+import { promptConfirmUpload } from "./prompt.js";
+import { checkForUpdate } from "./version-check.js";
+/**
+ * `submit`'s actual behavior, independent of commander wiring. Builds the
+ * bundle through the exact same path `scan` uses, prints it (byte-for-byte
+ * what gets uploaded — see submit.ts's postBundle), then gates on: a
+ * matching stored session, explicit upload confirmation, and the remote
+ * visibility check.
+ */
+export async function executeSubmitCommand(opts) {
+    const log = opts.log ?? console.log;
+    const warn = opts.warn ?? console.error;
+    const siteUrl = getSiteUrl();
+    const credentials = readCredentials(opts.configDir);
+    if (!credentials) {
+        throw new AuthError("Not logged in. Run `redential login` first.");
+    }
+    if (credentials.site_url !== siteUrl) {
+        throw new AuthError("Stored session belongs to a different site. Run `redential login` again.");
+    }
+    const bundle = await buildBundleInteractively(opts);
+    const bundleJson = JSON.stringify(bundle, null, 2);
+    log(bundleJson);
+    const confirmedUpload = opts.confirmUpload || (await (opts.promptConfirmUploadFn ?? promptConfirmUpload)());
+    if (!confirmedUpload) {
+        log("Aborted — nothing was uploaded.");
+        return;
+    }
+    const visibility = opts.probeFn
+        ? await checkVisibilityGate(getRemoteUrl(opts.repoPath), opts.probeFn)
+        : await checkVisibilityGate(getRemoteUrl(opts.repoPath));
+    if (visibility.message)
+        warn(visibility.message);
+    if (visibility.blocked) {
+        throw new SubmitError("Submit refused: see the message above.");
+    }
+    const result = await postBundle(siteUrl, credentials.access_token, bundleJson);
+    log(`Uploaded. Bundle id: ${result.id}`);
+    // Best-effort only, after the upload itself has already fully succeeded
+    // — never allowed to turn a successful submit into a failure
+    // (checkForUpdate never throws by contract).
+    await (opts.checkForUpdateFn ?? (() => checkForUpdate({ log: warn, currentVersion: opts.toolVersion })))();
+}

package/dist/submit.js

@@ -0,0 +1,71 @@
+import { NetworkError } from "./errors.js";
+import { isKnownPublicHost, publicHostWarning } from "./public-remote.js";
+import { headRequest, postRawJson } from "./http-client.js";
+const HEAD_TIMEOUT_MS = 5000;
+/**
+ * Converts a git remote URL (https, scp-like `git@host:org/repo.git`, or
+ * `ssh://`) into an https URL worth HEAD-requesting. Only ever called after
+ * isKnownPublicHost has already confirmed the URL carries no embedded
+ * credentials or token, so nothing sensitive can end up in the probe.
+ */
+function toProbeUrl(remoteUrl) {
+    const scpMatch = !remoteUrl.includes("://") && remoteUrl.match(/^(?:[^@\s]+@)?([^:/\s]+):(.+)$/);
+    if (scpMatch) {
+        const [, host, path] = scpMatch;
+        return `https://${host}/${path.replace(/\.git$/, "")}`;
+    }
+    try {
+        const u = new URL(remoteUrl);
+        if (u.protocol !== "http:" && u.protocol !== "https:" && u.protocol !== "ssh:")
+            return null;
+        return `https://${u.host}${u.pathname.replace(/\.git$/, "")}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Only probes known-public-host remotes (github.com/gitlab.com/bitbucket.org
+ * shaped, per public-remote.ts) — never an arbitrary self-hosted URL. A
+ * confirmed 2xx/3xx blocks submit; anything else (private, unreachable,
+ * unparseable) proceeds, matching scan's "known host != publicly
+ * accessible" stance and the advisor-required fail-open behavior for
+ * network blips.
+ */
+export async function checkVisibilityGate(remoteUrl, probeFn = headRequest) {
+    if (!isKnownPublicHost(remoteUrl))
+        return { blocked: false, message: null };
+    const probeUrl = toProbeUrl(remoteUrl);
+    if (!probeUrl)
+        return { blocked: false, message: publicHostWarning(remoteUrl) };
+    const result = await probeFn(probeUrl, HEAD_TIMEOUT_MS);
+    if (result === null) {
+        // Inconclusive (network error, timeout, host down) — never louder than
+        // scan's own warning, never treated as a confirmed answer either way.
+        return { blocked: false, message: publicHostWarning(remoteUrl) };
+    }
+    if (result.status >= 200 && result.status < 400) {
+        return {
+            blocked: true,
+            message: "Refusing to submit: this repository's remote answered as publicly reachable " +
+                `(HTTP ${result.status}). Connect the GitHub App instead — it reads the real code ` +
+                "and grants a stronger tier than a local metadata scan. If this repo is actually " +
+                "private, this check was wrong; please report it.",
+        };
+    }
+    return { blocked: false, message: null };
+}
+/**
+ * `bundleJson` must be the exact string already shown to the user (see
+ * submit-command.ts) — sent verbatim via postRawJson, never re-derived from
+ * the parsed object, so what was reviewed is byte-for-byte what is sent.
+ */
+export async function postBundle(siteUrl, accessToken, bundleJson) {
+    const response = await postRawJson(`${siteUrl}/api/cli/bundles`, bundleJson, {
+        authorization: `Bearer ${accessToken}`,
+    });
+    if (typeof response.id !== "string") {
+        throw new NetworkError("Unexpected response from the submit server.");
+    }
+    return response;
+}

package/dist/summary.js

@@ -0,0 +1,148 @@
+/**
+ * Renders a human-facing "wrapped" summary of an already-computed bundle for
+ * TTY stdout. Pure formatting only — every value comes from `Bundle`, no new
+ * data collection, no network. See `docs/scan.md`.
+ */
+const WIDTH = 60;
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const GRAY = "\x1b[90m";
+const WEEKDAY_LABELS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const SPARK_LEVELS = ["·", "▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+function humanizeSpan(days) {
+    if (days <= 0)
+        return "a single day";
+    const years = Math.floor(days / 365);
+    if (years >= 1)
+        return `${years} year${years === 1 ? "" : "s"}`;
+    const months = Math.floor(days / 30);
+    if (months >= 1)
+        return `${months} month${months === 1 ? "" : "s"}`;
+    return `${days} day${days === 1 ? "" : "s"}`;
+}
+function pct(fraction) {
+    return `${Math.round(fraction * 100)}%`;
+}
+function bar(fraction, width) {
+    const clamped = Math.max(0, Math.min(1, fraction));
+    const filled = Math.round(clamped * width);
+    return "█".repeat(filled) + "░".repeat(width - filled);
+}
+function sparkline(values) {
+    const max = Math.max(...values, 0);
+    if (max === 0)
+        return SPARK_LEVELS[0].repeat(values.length);
+    return values
+        .map((v) => {
+        if (v === 0)
+            return SPARK_LEVELS[0];
+        const level = Math.max(1, Math.round((v / max) * (SPARK_LEVELS.length - 1)));
+        return SPARK_LEVELS[level];
+    })
+        .join("");
+}
+function hourAxis() {
+    const chars = new Array(24).fill(" ");
+    for (const [pos, label] of [
+        [0, "0"],
+        [6, "6"],
+        [12, "12"],
+        [18, "18"],
+    ]) {
+        for (let i = 0; i < label.length; i++)
+            chars[pos + i] = label[i];
+    }
+    return chars.join("");
+}
+function heading(label) {
+    return `  ${BOLD}${GRAY}${label}${RESET}`;
+}
+function sectionOrTeaser(items, render, teaser) {
+    return items.length > 0 ? render(items) : [`  ${DIM}${teaser}${RESET}`];
+}
+function weekdaySection(histogram) {
+    const max = Math.max(...histogram, 1);
+    const barWidth = 20;
+    return histogram.map((count, i) => {
+        const filled = Math.round((count / max) * barWidth);
+        const b = "█".repeat(filled) + "░".repeat(barWidth - filled);
+        return `  ${WEEKDAY_LABELS[i]}  ${GREEN}${b}${RESET}  ${count}`;
+    });
+}
+function shareSection(items, maxItems) {
+    const top = [...items].sort((a, b) => b.share - a.share).slice(0, maxItems);
+    const max = Math.max(...top.map((i) => i.share), 0.0001);
+    const labelWidth = Math.max(...top.map((i) => i.label.length), 4);
+    return top.map((item) => {
+        const b = bar(item.share / max, 20);
+        const label = item.label.padEnd(labelWidth);
+        const suffix = item.suffix ? `  ${DIM}${item.suffix}${RESET}` : "";
+        return `  ${label}  ${GREEN}${b}${RESET}  ${YELLOW}${pct(item.share).padStart(4)}${RESET}${suffix}`;
+    });
+}
+function skillsSection(bundle) {
+    const skills = [...bundle.detected_skills].sort((a, b) => b.commit_count - a.commit_count);
+    if (skills.length === 0) {
+        return [
+            `  ${DIM}No skills detected yet — signature matching covers 100+`,
+            `  technologies (auth, payments, AI, infra, and more). Keep`,
+            `  committing and rerun \`redential scan\`.${RESET}`,
+        ];
+    }
+    const shown = skills.slice(0, 8);
+    const labelWidth = Math.max(...shown.map((s) => s.slug.length), 4);
+    const lines = shown.map((s) => `  ${s.slug.padEnd(labelWidth)}  ${GREEN}${String(s.commit_count).padStart(4)} commits${RESET}`);
+    if (skills.length > shown.length) {
+        lines.push(`  ${DIM}+${skills.length - shown.length} more${RESET}`);
+    }
+    return lines;
+}
+export function formatSummary(bundle) {
+    const lines = [];
+    // Printed after the JSON (scan-command.ts) so this is the last thing on
+    // screen when the command ends — the divider marks where the JSON above
+    // ends and the human-readable summary begins.
+    lines.push(`  ${GRAY}${"─".repeat(WIDTH)}${RESET}`);
+    lines.push("");
+    const title = "YOUR PRIVATE REPO, WRAPPED";
+    const pad = Math.max(0, Math.floor((WIDTH - title.length) / 2));
+    lines.push(`  ${CYAN}${"╔" + "═".repeat(WIDTH) + "╗"}${RESET}`);
+    lines.push(`  ${CYAN}║${RESET}${" ".repeat(pad)}${BOLD}${CYAN}${title}${RESET}${" ".repeat(WIDTH - pad - title.length)}${CYAN}║${RESET}`);
+    lines.push(`  ${CYAN}${"╚" + "═".repeat(WIDTH) + "╝"}${RESET}`);
+    lines.push("");
+    const commitCount = bundle.commits.user_total.toLocaleString("en-US");
+    lines.push(`  ${BOLD}${humanizeSpan(bundle.commits.span_days)}, ${commitCount} commits${RESET}`);
+    lines.push("");
+    lines.push(heading("COMMITS BY HOUR (UTC)"));
+    lines.push(`  ${hourAxis()}`);
+    lines.push(`  ${GREEN}${sparkline(bundle.commits.hour_histogram)}${RESET}`);
+    lines.push("");
+    lines.push(heading("COMMITS BY WEEKDAY"));
+    lines.push(...weekdaySection(bundle.commits.weekday_histogram));
+    lines.push("");
+    lines.push(heading("TOP LANGUAGES"));
+    lines.push(...sectionOrTeaser(bundle.languages, (langs) => shareSection(langs.map((l) => ({ label: l.extension, share: l.share })), 5), "No language data — every change so far was excluded (lockfiles, build output, generated dumps)."));
+    lines.push("");
+    lines.push(heading("TOP CATEGORIES"));
+    lines.push(...sectionOrTeaser(bundle.categories, (cats) => shareSection(cats.map((c) => ({
+        label: c.name,
+        share: c.churn_share,
+        suffix: `(${c.commit_count} commit${c.commit_count === 1 ? "" : "s"})`,
+    })), 5), "No category data yet."));
+    lines.push("");
+    lines.push(heading("SKILLS DETECTED"));
+    lines.push(...skillsSection(bundle));
+    lines.push("");
+    lines.push(`  ${BOLD}Ownership${RESET}       ${YELLOW}${pct(bundle.ownership.user_commit_ratio)}${RESET} of this repo's commits are yours`);
+    lines.push(`  ${BOLD}Signed commits${RESET}  ${YELLOW}${pct(bundle.signed.ratio)}${RESET} of your commits are cryptographically signed`);
+    if (bundle.signed.ratio === 0) {
+        lines.push(`  ${DIM}Tip: sign your commits (git config commit.gpgsign true) — signed history is the strongest anchor for your credential.${RESET}`);
+    }
+    lines.push("");
+    lines.push(`  ${DIM}Nothing left your machine. Verify: github.com/Jppblue/redential-cli${RESET}`);
+    return lines.join("\n");
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+export const CATEGORY_NAMES = [
+    "auth",
+    "payments",
+    "infra",
+    "frontend",
+    "backend",
+    "data",
+    "testing",
+    "ai-workflow",
+    "docs",
+    "other",
+];

package/dist/version-check.js

@@ -0,0 +1,62 @@
+import { readFileSync } from "node:fs";
+import { getJson } from "./http-client.js";
+/**
+ * Best-effort, non-blocking "a newer version exists" notice, checked against
+ * the public npm registry. ONLY ever wired into `login.ts` and
+ * `submit-command.ts` — both already make network calls, so this adds no new
+ * network surface to the command. It must NEVER be called from
+ * `scan-command.ts`: `scan` makes zero network calls, full stop (CLAUDE.md's
+ * inviolable rule, and see docs/login-submit.md's "Version check" section
+ * for the boundary this file exists inside). Nothing about the scanned repo
+ * is ever sent — the only outbound data is a GET to a fixed, public URL.
+ */
+const PACKAGE_NAME = "@redential/cli";
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+const DEFAULT_TIMEOUT_MS = 1500;
+function getInstalledVersion() {
+    const pkgUrl = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
+    return pkg.version;
+}
+/** Parses a `major.minor.patch`-leading version string; null if it doesn't
+ * parse cleanly — a malformed registry response must skip the notice, never
+ * crash the command it's attached to. */
+function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function isNewer(current, latest) {
+    const c = parseVersion(current);
+    const l = parseVersion(latest);
+    if (!c || !l)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (l[i] > c[i])
+            return true;
+        if (l[i] < c[i])
+            return false;
+    }
+    return false;
+}
+export async function checkForUpdate(opts = {}) {
+    const log = opts.log ?? console.error;
+    const currentVersion = opts.currentVersion ?? getInstalledVersion();
+    const registryUrl = opts.registryUrl ?? NPM_REGISTRY_URL;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchFn = opts.fetchFn ?? (getJson);
+    let latest;
+    try {
+        latest = await fetchFn(registryUrl, timeoutMs);
+    }
+    catch {
+        // fetchFn is injectable (tests, future callers) and isn't guaranteed to
+        // share getJson's own never-throws contract — this check must stay
+        // best-effort regardless of what's plugged in.
+        return;
+    }
+    if (!latest?.version || !isNewer(currentVersion, latest.version))
+        return;
+    log(`A newer version of ${PACKAGE_NAME} is available: ${latest.version} (you have ${currentVersion}). Run \`npm install -g ${PACKAGE_NAME}\` to update.`);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@redential/cli",
+  "version": "0.1.0",
+  "description": "Local, metadata-only proof bundles from git history. Source code never leaves your machine.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "redential": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "signatures",
+    "taxonomy.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jppblue/redential-cli.git"
+  },
+  "homepage": "https://github.com/Jppblue/redential-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Jppblue/redential-cli/issues"
+  },
+  "keywords": [
+    "cli",
+    "git",
+    "credential-verification",
+    "proof-of-work",
+    "developer-portfolio",
+    "privacy"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/signatures/ai/vector-search.json

@@ -0,0 +1,39 @@
+{
+  "slug": "ai/vector-search",
+  "importPatterns": [
+    "from\\s+[\"']@pinecone-database/pinecone[\"']",
+    "from\\s+[\"']chromadb[\"']",
+    "from\\s+[\"']@qdrant/js-client-rest[\"']"
+  ],
+  "apiPatterns": [
+    "\\.similaritySearch\\(",
+    "new\\s+PineconeClient\\("
+  ],
+  "configFilePatterns": [],
+  "fixtures": {
+    "positive": [
+      {
+        "path": "src/lib/pinecone.ts",
+        "diff": "import { PineconeClient } from \"@pinecone-database/pinecone\";\nconst pinecone = new PineconeClient();\nawait pinecone.Index(\"docs\").upsert({ vectors });"
+      },
+      {
+        "path": "src/lib/chroma.ts",
+        "diff": "import { ChromaClient } from \"chromadb\";\nconst collection = await client.getOrCreateCollection({ name: \"docs\" });\nconst results = await collection.similaritySearch(\"query text\", 5);"
+      },
+      {
+        "path": "src/lib/qdrant.ts",
+        "diff": "import { QdrantClient } from \"@qdrant/js-client-rest\";\nconst client = new QdrantClient({ url: \"http://localhost:6333\" });\nawait client.upsert(\"docs\", { points });"
+      }
+    ],
+    "negative": [
+      {
+        "path": "README.md",
+        "diff": "We evaluated pinecone, chromadb, and qdrant for vector search but decided pgvector inside Postgres covers our similarity search needs without a separate vector database."
+      },
+      {
+        "path": "src/db/users.ts",
+        "diff": "await prisma.user.upsert({ where: { id }, create: data, update: data });"
+      }
+    ]
+  }
+}