gespann 0.0.0-stage → 0.1.0

package/dist/cloud.js

@@ -0,0 +1,214 @@
+import { createHmac } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { BUILTIN_RULES } from './rules.js';
+import { git } from './sources/git.js';
+import { UsageError } from './util.js';
+/**
+ * Gespann Cloud: `login`, `sync`, `logout`. Sync sends metadata only. The shape is
+ * fixed here and the server rejects anything else (see SyncPayload).
+ */
+export const DEFAULT_API = 'https://gespann.app';
+export function configDir(env, home) {
+    if (env.GESPANN_CONFIG_DIR)
+        return env.GESPANN_CONFIG_DIR;
+    return join(env.XDG_CONFIG_HOME || join(home, '.config'), 'gespann');
+}
+export function isApiKey(key) {
+    return /^gsp_(live|test)_[\w-]{32}$/.test(key);
+}
+/** The key never goes over plain http, except to a local test server. */
+export function checkApiUrl(url) {
+    const u = url.replace(/\/+$/, '');
+    if (!/^https:\/\/[^/]+$/.test(u) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(u)) {
+        throw new UsageError(`API URL must be https: ${url}`);
+    }
+    return u;
+}
+export function readCredentials(env, home) {
+    const api = checkApiUrl(env.GESPANN_API_URL || DEFAULT_API);
+    if (env.GESPANN_API_KEY)
+        return { api, key: env.GESPANN_API_KEY.trim() };
+    const path = join(configDir(env, home), 'credentials.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const c = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof c.key !== 'string')
+            return null;
+        return { api: env.GESPANN_API_URL ? api : checkApiUrl(c.api ?? DEFAULT_API), key: c.key };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCredentials(env, home, creds) {
+    const dir = configDir(env, home);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, 'credentials.json');
+    writeFileSync(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return path;
+}
+export function deleteCredentials(env, home) {
+    const path = join(configDir(env, home), 'credentials.json');
+    if (!existsSync(path))
+        return false;
+    rmSync(path);
+    return true;
+}
+/** github.com/owner/repo for every common remote URL form. */
+export function normalizeRemote(url) {
+    let u = url.trim();
+    const scp = /^[\w.-]+@([^:/]+):(.+)$/.exec(u);
+    if (scp)
+        u = `${scp[1]}/${scp[2]}`;
+    else
+        u = u.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').replace(/^[^@/]+@/, '');
+    u = u.replace(/\.git$/, '').replace(/\/+$/, '');
+    const slash = u.indexOf('/');
+    return slash < 0 ? u.toLowerCase() : u.slice(0, slash).toLowerCase() + u.slice(slash);
+}
+/**
+ * Ids and the repo are hashed with the account's hash key (from /api/v1/me), so a
+ * hash cannot be reversed by guessing file names or public repo URLs. Members of
+ * one team share the key, so the same repo gets the same hash.
+ */
+export const PREVIEW_KEY = 'gespann-preview';
+const hmac = (key, s) => createHmac('sha256', key).update(s).digest('hex');
+export function repoIdentity(repo, key) {
+    let remote = '';
+    try {
+        remote = git(repo, ['remote', 'get-url', 'origin']).trim();
+    }
+    catch {
+        // No origin: the path identifies the repo on this machine only.
+    }
+    const id = remote ? normalizeRemote(remote) : `local:${repo}`;
+    const raw = remote ? (id.split('/').pop() ?? '') : basename(repo);
+    const name = raw.replace(/[^\w.-]/g, '-').slice(0, 100) || 'repo';
+    return { hash: hmac(key, `repo:${id}`), name };
+}
+const PUBLIC_IDS = new Set([...BUILTIN_RULES.map((r) => `cmd-${r.id}`), 'reverts']);
+/**
+ * Ids can contain words from commit messages, file names or prompts. Only built-in
+ * ids leave the machine as they are, unless the user asks for names.
+ */
+export function publicId(id, names, key) {
+    if (PUBLIC_IDS.has(id))
+        return id;
+    if (names && /^[a-z0-9][a-z0-9-]{0,63}$/.test(id))
+        return id;
+    return `h:${hmac(key, `id:${id}`).slice(0, 12)}`;
+}
+/** Blocks counted by installed hooks, per guardrail and day, for the last 35 days. */
+export function readBlocks(repo, now) {
+    const path = join(repo, '.gespann', 'local', 'blocks.jsonl');
+    if (!existsSync(path))
+        return [];
+    const since = new Date(now.getTime() - 35 * 86_400_000).toISOString().slice(0, 10);
+    const counts = new Map();
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        try {
+            const e = JSON.parse(line);
+            if (typeof e.id !== 'string' || typeof e.at !== 'string')
+                continue;
+            const day = e.at.slice(0, 10);
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || day < since)
+                continue;
+            const k = `${e.id}\u0000${day}`;
+            counts.set(k, (counts.get(k) ?? 0) + 1);
+        }
+        catch {
+            // Skip a torn line.
+        }
+    }
+    return [...counts].map(([k, count]) => {
+        const [id, day] = k.split('\u0000');
+        return { id, day, count };
+    });
+}
+const day = (iso) => iso.slice(0, 10);
+export function buildPayload(opts) {
+    const { report, names, key } = opts;
+    const windowMs = Date.parse(report.generatedAt) - Date.parse(report.since);
+    const merged = new Map();
+    for (const b of opts.blocks) {
+        const guardrail = publicId(b.id, names, key);
+        const k = `${guardrail} ${b.day}`;
+        const prev = merged.get(k);
+        merged.set(k, {
+            guardrail,
+            day: b.day,
+            count: Math.min(100_000, (prev?.count ?? 0) + b.count),
+        });
+    }
+    return {
+        version: 1,
+        cli_version: opts.version,
+        taken_at: opts.now.toISOString(),
+        repo: names ? { hash: opts.repo.hash, name: opts.repo.name } : { hash: opts.repo.hash },
+        window_days: Math.min(3650, Math.max(1, Math.ceil(windowMs / 86_400_000) || 1)),
+        stats: {
+            commits: report.stats.gitCommits,
+            fix_commits: report.stats.fixCommits,
+            reverts: report.stats.reverts,
+            sessions: report.stats.claudeSessions + report.stats.codexSessions,
+            incidents: report.stats.incidents,
+        },
+        mistakes: report.clusters.slice(0, 500).map((c) => ({
+            id: publicId(c.id, names, key),
+            kind: c.kind,
+            suggestion: c.suggestion,
+            count: c.count,
+            sessions: c.sessions,
+            fix_commits: c.cost.fixCommits,
+            minutes: Math.round(c.cost.minutes),
+            first_seen: day(c.firstSeen),
+            last_seen: day(c.lastSeen),
+        })),
+        guardrails: opts.checks
+            .filter((g) => ['hook', 'lint', 'prose'].includes(g.kind))
+            .slice(0, 500)
+            .map((g) => ({ id: publicId(g.id, names, key), kind: g.kind, ok: g.ok, warn: g.warn })),
+        blocks: [...merged.values()].slice(0, 5000),
+    };
+}
+export class CloudError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export async function cloudRequest(doFetch, creds, method, path, body) {
+    let res;
+    try {
+        res = await doFetch(`${creds.api}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${creds.key}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch (e) {
+        throw new CloudError(`Could not reach ${creds.api}: ${e.message}`, 0);
+    }
+    const text = await res.text();
+    let data = {};
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        // Not JSON: use the status below.
+    }
+    if (!res.ok) {
+        const msg = typeof data.message === 'string' ? data.message : `HTTP ${res.status}`;
+        throw new CloudError(msg, res.status);
+    }
+    return data;
+}

package/dist/cluster.js

@@ -0,0 +1,339 @@
+import { adviceFor } from './harness.js';
+import { incidentMinutes } from './sources/analyze.js';
+import { slugify } from './util.js';
+/** Docs change with almost every fix; they are not where the mistake is. */
+const DOC_FILE = /\.(?:md|mdx|txt|rst)$|(?:^|\/)(?:CHANGELOG|LICENSE)[^/]*$/i;
+/**
+ * How much one occurrence weighs in the ranking. A broken explicit rule or a human correction
+ * counts more than a single fix commit, because it is a mistake the agent was told about.
+ */
+const WEIGHT = {
+    'rule-violation': 3,
+    correction: 3,
+    revert: 2,
+    'user-rejected': 2,
+    interrupt: 2,
+    'fix-commit': 1,
+    'fix-hotspot': 1,
+    'hook-block': 1,
+    'command-not-found': 1,
+    'tool-misuse': 1,
+};
+const STOPWORDS = new Set(`the and for that this with you your are was were not but have has had from they them then than
+  what when why how which who will would should could can cant can't dont don't does did doing done
+  just also again still only into onto out over under there here its it's all any some more most
+  very really please now yes okay make made use used using want need get got let lets see look
+  der die das und oder aber nicht noch schon wieder doch mal ich du wir ihr sie ist sind war waren
+  hat habe hast haben ein eine einen einem einer mit von für auf aus bei nach wie was wer warum
+  dass dem den des sich auch nur jetzt bitte kann kannst soll sollst muss musst hier dort immer
+  nein falsch wrong again stop wenn dann eigentlich genau alles andere anderen ersten erste einzige
+  einfach gerade also weil denn sondern ganz gibt geht machen macht sein seine diese dieser dieses
+  diesen etwas viel mehr frage fragt beispiel thing things something everything work works working
+  should've think know like sure maybe`.split(/\s+/));
+function tokens(text) {
+    const out = new Set();
+    for (const m of text.matchAll(/`([^`]{2,40})`/g))
+        out.add(`\`${(m[1] ?? '').toLowerCase()}\``);
+    for (const w of text.toLowerCase().split(/[^a-z0-9äöüß_.-]+/)) {
+        const t = w.replace(/^[.-]+|[.-]+$/g, '');
+        if (t.length >= 4 && !STOPWORDS.has(t) && !/^\d+$/.test(t))
+            out.add(t);
+    }
+    return out;
+}
+/** Group corrections that share at least two uncommon words (single link). */
+export function clusterCorrections(items) {
+    const toks = items.map((i) => tokens(i.text));
+    const df = new Map();
+    for (const t of toks)
+        for (const w of t)
+            df.set(w, (df.get(w) ?? 0) + 1);
+    const maxDf = Math.max(5, Math.floor(items.length * 0.3));
+    const salient = toks.map((t) => new Set([...t].filter((w) => (df.get(w) ?? 0) >= 2 && (df.get(w) ?? 0) <= maxDf)));
+    const parent = items.map((_, i) => i);
+    const find = (i) => {
+        let r = i;
+        while (parent[r] !== r)
+            r = parent[r] ?? r;
+        parent[i] = r;
+        return r;
+    };
+    for (let i = 0; i < items.length; i++) {
+        for (let j = i + 1; j < items.length; j++) {
+            const a = salient[i];
+            const b = salient[j];
+            if (!a || !b)
+                continue;
+            let shared = 0;
+            for (const w of a)
+                if (b.has(w))
+                    shared++;
+            if (shared >= 2)
+                parent[find(j)] = find(i);
+        }
+    }
+    const groups = new Map();
+    items.forEach((it, i) => {
+        const r = find(i);
+        const g = groups.get(r) ?? [];
+        g.push(it);
+        groups.set(r, g);
+    });
+    return [...groups.values()];
+}
+function topSharedTokens(items, n = 3) {
+    const count = new Map();
+    for (const it of items)
+        for (const w of tokens(it.text))
+            count.set(w, (count.get(w) ?? 0) + 1);
+    return [...count.entries()]
+        .filter(([, c]) => c >= 2)
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, n)
+        .map(([w]) => w);
+}
+function evidenceOf(items, max) {
+    const seen = new Set();
+    const out = [];
+    for (const it of [...items].sort((a, b) => b.at.localeCompare(a.at))) {
+        if (seen.has(it.text))
+            continue;
+        seen.add(it.text);
+        out.push({ source: it.source, ref: it.ref, at: it.at, text: it.text });
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+function describe(key, items, rules) {
+    const first = items[0];
+    if (!first)
+        return undefined;
+    const label = first.label ?? '';
+    const n = items.length;
+    const [prefix, ...rest] = key.split(':');
+    const tail = rest.join(':');
+    switch (prefix) {
+        case 'rule': {
+            const rule = rules.find((r) => r.id === tail);
+            if (!rule)
+                return undefined;
+            return {
+                id: `cmd-${rule.id}`,
+                kind: 'rule-violation',
+                title: rule.title,
+                summary: `Agents ran a blocked command pattern ${n} times. ${rule.advice}`,
+                suggestion: 'hook',
+                rule,
+            };
+        }
+        case 'hook':
+            return {
+                id: `hook-${tail}`.slice(0, 60),
+                kind: 'hook-block',
+                title: `A hook keeps blocking: ${label}`,
+                summary: `An existing hook blocked agents ${n} times. They retry instead of following the rule.`,
+                suggestion: 'prose',
+            };
+        case 'not-found':
+            return {
+                id: `missing-${tail}`,
+                kind: 'command-not-found',
+                title: `Calls \`${label}\`, which is not installed`,
+                summary: `Agents called \`${label}\` ${n} times and got "command not found".`,
+                suggestion: 'prose',
+            };
+        case 'misuse': {
+            const titles = {
+                'edit-before-read': 'Edits a file before reading it',
+                'edit-string-not-found': 'Edits with text that is not in the file',
+                'unknown-tool': 'Calls a tool that does not exist',
+            };
+            return {
+                id: `misuse-${tail}`,
+                kind: 'tool-misuse',
+                title: titles[tail] ?? `Tool misuse: ${tail}`,
+                summary: `The tool call failed the same way ${n} times.`,
+                suggestion: 'prose',
+            };
+        }
+        case 'rejected':
+        case 'denied':
+            return {
+                id: `${prefix}-${tail}`,
+                kind: 'user-rejected',
+                title: prefix === 'rejected' ? `User rejects ${tail} calls` : `Permission denied for ${tail}`,
+                summary: `A human or policy said no ${n} times.`,
+                suggestion: 'prose',
+            };
+        case 'interrupt':
+            return {
+                id: `stopped-${rest.join('-')}`.slice(0, 60),
+                kind: 'interrupt',
+                title: `User stops \`${label}\` mid-run`,
+                summary: `The user interrupted this tool call ${n} times.`,
+                suggestion: 'prose',
+            };
+        case 'fix-scope':
+            return {
+                id: `fixes-${slugify(tail, 40)}`,
+                kind: 'fix-commit',
+                title: `Repeated fixes in \`${tail}\``,
+                summary: `${n} fix commits touched the \`${tail}\` area.`,
+                suggestion: 'prose',
+            };
+        case 'revert':
+            return {
+                id: 'reverts',
+                kind: 'revert',
+                title: 'Commits get reverted',
+                summary: `${n} commits were reverted.`,
+                suggestion: 'prose',
+            };
+        default:
+            return undefined;
+    }
+}
+/** Incidents and minutes per day, oldest first. */
+export function timelineOf(items) {
+    const days = new Map();
+    for (const it of items) {
+        const day = it.at.slice(0, 10);
+        const d = days.get(day) ?? { day, n: 0, minutes: 0, blocked: 0 };
+        d.n++;
+        d.minutes += incidentMinutes(it);
+        if (it.blockedBy)
+            d.blocked++;
+        days.set(day, d);
+    }
+    return [...days.values()]
+        .map((d) => ({ ...d, minutes: Math.round(d.minutes * 10) / 10 }))
+        .sort((a, b) => a.day.localeCompare(b.day));
+}
+/** Distinct sessions per harness. */
+function harnessCounts(items) {
+    const seen = new Map();
+    for (const it of items) {
+        if (!it.harness || !it.session)
+            continue;
+        const s = seen.get(it.harness) ?? new Set();
+        s.add(it.session);
+        seen.set(it.harness, s);
+    }
+    return Object.fromEntries([...seen].map(([h, s]) => [h, s.size]));
+}
+/** Group incidents into ranked clusters. */
+export function clusterIncidents(incidents, opts) {
+    const minCount = opts.minCount ?? 2;
+    const fixCount = new Set(incidents.filter((i) => i.kind === 'fix-commit').map((i) => i.ref)).size;
+    const hotspotMin = opts.hotspotMin ?? Math.max(3, Math.ceil(fixCount * 0.02));
+    const maxEvidence = opts.maxEvidence ?? 5;
+    const drafts = [];
+    const byKey = new Map();
+    for (const it of incidents) {
+        if (it.kind === 'correction' || it.key === 'fix')
+            continue;
+        const g = byKey.get(it.key) ?? [];
+        g.push(it);
+        byKey.set(it.key, g);
+    }
+    for (const [key, items] of byKey) {
+        const d = describe(key, items, opts.rules);
+        if (d)
+            drafts.push({ ...d, items });
+    }
+    // Corrections: group by shared words.
+    for (const group of clusterCorrections(incidents.filter((i) => i.kind === 'correction'))) {
+        const words = topSharedTokens(group);
+        if (words.length === 0)
+            continue;
+        const shortest = [...group].sort((a, b) => a.text.length - b.text.length)[0];
+        drafts.push({
+            id: `correction-${slugify(words.join('-'), 40)}`,
+            kind: 'correction',
+            title: `User corrects the agent about ${words.join(', ')}`,
+            summary: `The user corrected agents ${group.length} times on this topic, e.g. "${shortest?.text.slice(0, 100) ?? ''}".`,
+            suggestion: 'prose',
+            items: group,
+        });
+    }
+    // Fix hotspots: files touched by many fix commits.
+    const perFile = new Map();
+    for (const it of incidents) {
+        if (it.kind !== 'fix-commit')
+            continue;
+        for (const f of it.files ?? []) {
+            if (DOC_FILE.test(f))
+                continue;
+            const g = perFile.get(f) ?? [];
+            g.push(it);
+            perFile.set(f, g);
+        }
+    }
+    for (const [file, items] of perFile) {
+        if (items.length < hotspotMin)
+            continue;
+        drafts.push({
+            id: `hotspot-${slugify(file, 50)}`,
+            kind: 'fix-hotspot',
+            title: `Fix hotspot: \`${file}\``,
+            summary: `${items.length} fix commits changed \`${file}\`.`,
+            suggestion: 'prose',
+            items,
+            files: [file],
+        });
+    }
+    const clusters = [];
+    const usedIds = new Map();
+    for (const d of drafts) {
+        if (d.items.length < minCount)
+            continue;
+        const sorted = [...d.items].sort((a, b) => a.at.localeCompare(b.at));
+        const git = d.items.filter((i) => i.source === 'git');
+        const fixCommits = new Set(git.map((i) => i.ref)).size;
+        const linesChanged = git.reduce((n, i) => n + (i.linesChanged ?? 0), 0);
+        const minutes = Math.round(d.items.reduce((n, i) => n + incidentMinutes(i), 0));
+        const sources = [...new Set(d.items.map((i) => i.source))].sort();
+        const sessions = new Set(d.items.filter((i) => i.session).map((i) => i.session)).size;
+        const harnesses = harnessCounts(d.items);
+        // Occurrences: separate sessions for transcripts, separate commits for git.
+        const occurrences = sessions + fixCommits;
+        const score = occurrences * WEIGHT[d.kind];
+        let id = d.id;
+        const dup = usedIds.get(id) ?? 0;
+        usedIds.set(id, dup + 1);
+        if (dup > 0)
+            id = `${id}-${dup + 1}`;
+        const advice = adviceFor({ id, rule: d.rule });
+        clusters.push({
+            id,
+            rank: 0,
+            kind: d.kind,
+            title: d.title,
+            summary: d.summary,
+            count: d.items.length,
+            sessions,
+            score,
+            firstSeen: sorted[0]?.at ?? '',
+            lastSeen: sorted[sorted.length - 1]?.at ?? '',
+            cost: { fixCommits, linesChanged, minutes },
+            sources,
+            evidence: evidenceOf(d.items, maxEvidence),
+            suggestion: d.suggestion,
+            ...(d.rule ? { rule: d.rule } : {}),
+            ...(d.files ? { files: d.files } : {}),
+            ...(Object.keys(harnesses).length ? { harnesses } : {}),
+            ...(Object.keys(advice).length ? { advice } : {}),
+            timeline: timelineOf(d.items),
+        });
+    }
+    clusters.sort((a, b) => b.score - a.score ||
+        b.cost.minutes - a.cost.minutes ||
+        b.count - a.count ||
+        b.lastSeen.localeCompare(a.lastSeen) ||
+        a.id.localeCompare(b.id));
+    clusters.forEach((c, i) => {
+        c.rank = i + 1;
+    });
+    return clusters;
+}