hitloop 0.0.0-stage → 0.1.1

package/dist/r/model.js

@@ -0,0 +1,323 @@
+// Reviews: things an agent puts in front of the human to look at, review or approve, and what the human says back.
+// Everything here is pure: the store reads and writes the files.
+//
+// A review is one file, .hitl/reviews/<id>.json: a title, an intro, a mode, and a list of items. An item is one thing
+// to look at: a project file (or a few lines of one, or its changes since a git revision), raw content (code, text,
+// markdown, JSON), a diff, a picture, a diagram, an HTML mockup or a link, with the agent's note on what to look at.
+//   mode "review":  the human gives each item a verdict (looks good / needs changes / no) and comments
+//   mode "show":    just look; comments welcome, no verdicts asked for
+//   mode "approve": one yes or no for the whole thing (a gate: `hitl approve` waits on it)
+export const KINDS = ['file', 'code', 'text', 'md', 'json', 'diff', 'image', 'mermaid', 'html', 'link'];
+export const MODES = ['review', 'show', 'approve'];
+// ── feedback ──
+export const VERDICTS = ['ok', 'changes', 'no'];
+export const VERDICT_TEXT = { ok: 'looks good', changes: 'needs changes', no: 'no' };
+export const APPROVE_TEXT = { ok: 'approved', changes: 'not yet (changes asked for)', no: 'refused' };
+export const emptyFeedback = () => ({ version: 1, kind: 'review', seq: 0, readSeq: 0, items: {}, comments: [] });
+// ── helpers ──
+export const REVIEW_ID = /^[a-z0-9][a-z0-9._-]{0,79}$/i;
+const ITEM_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$/;
+export function slug(s, max = 40) {
+    return (s
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, max)
+        .replace(/-+$/, '') || 'x');
+}
+/** A short, stable fingerprint (FNV-1a, 32-bit, base 36). */
+export function hash(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+const str = (v) => (typeof v === 'string' ? v : v === undefined || v === null ? '' : String(v));
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const CONTENT = ['file', 'code', 'text', 'md', 'json', 'diff', 'image', 'mermaid', 'html', 'link'];
+const KNOWN = new Set(['id', 'title', 'note', 'ask', 'lines', 'against', 'snapshot', 'snap', 'lang', 'name', 'alt', 'before', 'height', 'label', 'collapsed', ...CONTENT]);
+/** which content field an item has */
+export function kindOf(i) {
+    for (const k of CONTENT)
+        if (i[k] !== undefined && (k === 'json' || typeof i[k] === 'string'))
+            return k;
+    return undefined;
+}
+/** a title for an item without one */
+export function defaultTitle(i, kind) {
+    switch (kind) {
+        case 'file':
+            return (i.file ?? '') + (i.lines !== undefined ? `:${i.lines}` : '') + (i.against ? ` (since ${i.against})` : '');
+        case 'code':
+            return i.name || (i.lang ? `Code (${i.lang})` : 'Code');
+        case 'text':
+            return i.name || 'Text';
+        case 'md':
+            return i.name || 'Notes';
+        case 'json':
+            return i.name || 'Data';
+        case 'diff':
+            return diffFiles(i.diff ?? '').join(', ') || 'Changes';
+        case 'image':
+            return i.alt || (/^data:/.test(i.image ?? '') ? 'Picture' : (i.image ?? '').replace(/[?#].*$/, '').split('/').pop() || 'Picture');
+        case 'mermaid':
+            return 'Diagram';
+        case 'html':
+            return 'Mockup';
+        case 'link':
+            return i.label || i.link || 'Link';
+    }
+}
+/** the files a unified diff touches */
+export function diffFiles(diff) {
+    const out = [];
+    for (const m of diff.matchAll(/^\+\+\+ (?:b\/)?(.+)$/gm)) {
+        const f = (m[1] ?? '').trim();
+        if (f && f !== '/dev/null' && !out.includes(f))
+            out.push(f);
+    }
+    return out;
+}
+function itemRev(i) {
+    const { id: _id, title: _t, note: _n, ask: _a, collapsed: _c, rev: _r, snap, ...content } = i;
+    return hash(JSON.stringify({ ...content, snap: snap?.sha }));
+}
+/** An item id from its title or file: short, readable, unique among `taken`. */
+export function itemIdFor(i, taken) {
+    const kind = kindOf(i);
+    const base = slug(i.title || (kind === 'file' ? (i.file ?? '').split('/').pop() || 'file' : kind ? defaultTitle(i, kind) : 'item'), 32);
+    let id = base, n = 2;
+    while (taken.has(id))
+        id = `${base}-${n++}`;
+    return id;
+}
+export function normalise(id, input) {
+    const errors = [];
+    const warnings = [];
+    const raw = isObj(input) ? input : {};
+    if (!isObj(input))
+        errors.push('A review is a JSON object: { title, intro, mode, items: [...] }');
+    const mode = MODES.includes(str(raw.mode)) ? raw.mode : 'review';
+    if (raw.mode !== undefined && !MODES.includes(str(raw.mode)))
+        errors.push(`mode is one of ${MODES.join(', ')}`);
+    const review = {
+        id,
+        title: str(raw.title) || id,
+        intro: str(raw.intro),
+        mode,
+        status: raw.status === 'closed' ? 'closed' : 'open',
+        from: str(raw.from),
+        created: str(raw.created),
+        updated: str(raw.updated),
+        items: [],
+    };
+    const seen = new Set();
+    const list = Array.isArray(raw.items) ? raw.items : [];
+    if (raw.items !== undefined && !Array.isArray(raw.items))
+        errors.push('items must be a list');
+    list.forEach((ii, n) => {
+        const at = `items[${n}]`;
+        if (!isObj(ii))
+            return void errors.push(`${at}: an item is an object, like { "file": "src/x.ts" } or { "code": "…", "lang": "ts" }`);
+        const input = ii;
+        const present = CONTENT.filter((k) => input[k] !== undefined);
+        const kind = kindOf(input);
+        if (!kind)
+            return void errors.push(`${at}: no content (give one of: ${CONTENT.join(', ')})`);
+        if (present.length > 1)
+            warnings.push(`${at}: more than one content field (${present.join(', ')}); showing ${kind}`);
+        for (const k of Object.keys(input))
+            if (!KNOWN.has(k))
+                warnings.push(`${at}: unknown field "${k}"`);
+        let iid = str(input.id);
+        if (!iid)
+            iid = itemIdFor(input, seen);
+        else if (!ITEM_ID.test(iid))
+            return void errors.push(`${at}: bad id "${iid}" (letters, digits, . _ : -)`);
+        if (seen.has(iid))
+            return void errors.push(`${at}: the id "${iid}" is used twice`);
+        seen.add(iid);
+        const lines = input.lines === undefined ? undefined : String(input.lines);
+        if (lines !== undefined && !/^\d+(-\d+)?$/.test(lines))
+            errors.push(`${at}: lines is "10" or "10-40"`);
+        if (kind === 'file' && /(^|[\\/])\.\.([\\/]|$)/.test(input.file ?? ''))
+            errors.push(`${at}: file must be inside the project`);
+        if (kind === 'link' && !/^https?:\/\//i.test(input.link ?? ''))
+            errors.push(`${at}: a link starts with http:// or https://`);
+        for (const k of ['image', 'before'])
+            if (/^(javascript|vbscript):/i.test(str(input[k])))
+                errors.push(`${at}: ${k} isn't a picture`);
+        if (input.against !== undefined && (kind !== 'file' || !/^[A-Za-z0-9._/~^@{}-]{1,100}$/.test(str(input.against)) || str(input.against).startsWith('-')))
+            errors.push(`${at}: against is a git revision (like HEAD or main), with file`);
+        const item = { id: iid, kind, title: str(input.title) || defaultTitle(input, kind), note: str(input.note), ask: str(input.ask), collapsed: input.collapsed === true, rev: '' };
+        const set = (k, v) => {
+            if (v !== undefined && v !== '')
+                item[k] = v;
+        };
+        switch (kind) {
+            case 'file':
+                set('file', str(input.file).replace(/\\/g, '/').replace(/^\.\//, ''));
+                set('lines', lines);
+                set('against', input.against ? str(input.against) : undefined);
+                if (isObj(input.snap) && typeof input.snap.path === 'string' && typeof input.snap.sha === 'string')
+                    item.snap = input.snap;
+                break;
+            case 'code':
+                set('code', input.code);
+                set('lang', str(input.lang) || undefined);
+                set('name', str(input.name) || undefined);
+                set('before', typeof input.before === 'string' ? input.before : undefined);
+                break;
+            case 'text':
+                set('text', input.text);
+                set('name', str(input.name) || undefined);
+                set('before', typeof input.before === 'string' ? input.before : undefined);
+                break;
+            case 'md':
+                set('md', input.md);
+                break;
+            case 'json':
+                item.json = input.json;
+                set('name', str(input.name) || undefined);
+                break;
+            case 'diff':
+                set('diff', input.diff);
+                break;
+            case 'image':
+                set('image', input.image);
+                set('alt', str(input.alt) || undefined);
+                set('before', typeof input.before === 'string' ? input.before : undefined);
+                break;
+            case 'mermaid':
+                set('mermaid', input.mermaid);
+                break;
+            case 'html':
+                set('html', input.html);
+                item.height = typeof input.height === 'number' && input.height > 40 ? Math.min(4000, input.height) : 360;
+                break;
+            case 'link':
+                set('link', input.link);
+                set('label', str(input.label) || undefined);
+                break;
+        }
+        item.rev = itemRev(item);
+        review.items.push(item);
+    });
+    if (!review.items.length && mode !== 'approve' && !errors.length)
+        warnings.push('Nothing to look at yet: add items');
+    return { review, errors, warnings };
+}
+export const isStale = (item, v) => !!item && !!v && v.rev !== item.rev;
+export function summarise(review, fb, errors = 0) {
+    let reviewed = 0, ok = 0, changes = 0, no = 0, stale = 0;
+    for (const it of review.items) {
+        const v = fb.items[it.id];
+        if (!v)
+            continue;
+        reviewed++;
+        if (v.verdict === 'ok')
+            ok++;
+        else if (v.verdict === 'changes')
+            changes++;
+        else
+            no++;
+        if (isStale(it, v))
+            stale++;
+    }
+    return {
+        id: review.id,
+        kind: 'review',
+        title: review.title,
+        mode: review.mode,
+        status: review.status,
+        from: review.from,
+        items: review.items.length,
+        reviewed,
+        ok,
+        changes,
+        no,
+        open: fb.comments.filter((c) => c.status === 'open' && c.from === 'owner').length,
+        comments: fb.comments.length,
+        overall: fb.overall?.verdict,
+        done: !!fb.overall,
+        unread: countNew(fb),
+        stale,
+        created: review.created,
+        updated: review.updated,
+        errors,
+    };
+}
+/** how many things the human did since the agent last read */
+export function countNew(fb) {
+    let n = 0;
+    if (fb.overall && fb.overall.seq > fb.readSeq)
+        n++;
+    for (const v of Object.values(fb.items))
+        if (v.seq > fb.readSeq)
+            n++;
+    for (const c of fb.comments) {
+        if (c.from === 'owner' && c.seq > fb.readSeq)
+            n++;
+        for (const r of c.replies)
+            if (r.from === 'owner' && r.seq > fb.readSeq)
+                n++;
+    }
+    return n;
+}
+export function whereText(c) {
+    if (c.strokes?.length)
+        return c.area ? `marked area ${c.area.w}×${c.area.h} at ${c.area.x},${c.area.y}` : 'marked area';
+    if (c.line)
+        return `${c.side === 'old' ? 'removed ' : ''}${c.endLine && c.endLine !== c.line ? `lines ${c.line}-${c.endLine}` : `line ${c.line}`}`;
+    return '';
+}
+export function verdictText(r, v) {
+    return r.mode === 'approve' ? APPROVE_TEXT[v] : VERDICT_TEXT[v];
+}
+/** The feedback as readable markdown, for .hitl/answers/<id>.md */
+export function feedbackMarkdown(review, fb) {
+    const s = summarise(review, fb);
+    const head = review.mode === 'approve'
+        ? fb.overall
+            ? `**${APPROVE_TEXT[fb.overall.verdict]}**${fb.overall.note ? `: ${fb.overall.note}` : ''}`
+            : 'Not answered yet.'
+        : `${s.reviewed} of ${s.items} items reviewed (${s.ok} good, ${s.changes} need changes, ${s.no} no), ${s.open} open comment${s.open === 1 ? '' : 's'}.${fb.overall ? ` Overall: **${VERDICT_TEXT[fb.overall.verdict]}**${fb.overall.note ? `: ${fb.overall.note}` : ''}.` : ''}`;
+    const out = [`# ${review.title}: feedback`, '', head, '', `Written by hitl; the data is in the .json next to this file. What's new: \`npx hitloop news\`.`, ''];
+    const byItem = new Map();
+    for (const c of fb.comments) {
+        const l = byItem.get(c.item) ?? [];
+        l.push(c);
+        byItem.set(c.item, l);
+    }
+    const ids = ['', ...review.items.map((i) => i.id), ...[...byItem.keys(), ...Object.keys(fb.items)].filter((k) => k && !review.items.some((i) => i.id === k))];
+    for (const iid of [...new Set(ids)]) {
+        const it = review.items.find((i) => i.id === iid);
+        const v = fb.items[iid];
+        const cs = byItem.get(iid) ?? [];
+        if (!v && !cs.length)
+            continue;
+        out.push(`## ${iid === '' ? 'The whole review' : it ? it.title : `${iid} (removed)`}`, '');
+        if (it?.kind === 'file')
+            out.push(`\`${it.file}${it.lines ? ':' + it.lines : ''}\``, '');
+        if (v)
+            out.push(`**${VERDICT_TEXT[v.verdict]}**${v.note ? `: ${v.note}` : ''}${isStale(it, v) ? ' _(given to an earlier version)_' : ''}${v.ack ? ` — done: ${v.ack.note}` : ''}`, '');
+        for (const c of cs) {
+            const w = whereText(c);
+            out.push(`- [${c.status === 'open' ? ' ' : 'x'}] \`${c.id}\`${w ? ` (${w})` : ''}: ${c.body.replace(/\n/g, '\n  ')}`);
+            if (c.quote)
+                out.push(`  > ${c.quote.split('\n').slice(0, 12).join('\n  > ')}`);
+            if (c.marked)
+                out.push(`  ![marked](../../${c.marked})`);
+            for (const p of c.photos ?? [])
+                out.push(`  ![photo](../../${p})`);
+            for (const r of c.replies)
+                out.push(`  - ${r.from === 'owner' ? 'human' : 'agent'}: ${r.body.replace(/\n/g, '\n    ')}`);
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}

package/dist/r/schema.js

@@ -0,0 +1,53 @@
+// The review format as JSON Schema: published as schema/reviews.schema.json, printed by `hitl schema reviews`, and
+// given to agents in the MCP tools' input schemas.
+export const itemSchema = {
+    type: 'object',
+    description: 'One thing to look at. Give exactly one content field: file (a project path; with lines "10-40" for part of it, or against "HEAD"/"main" for its changes since then), files (several paths at once), code (+ lang, name), text, md, json, diff (unified), image (project path, https URL or data:image URL), mermaid, html (sandboxed mockup, no scripts; height), link (+ label). Add title, note (markdown: what to look at), ask (the question for this item), before (an earlier picture or text, for a before/after view), collapsed.',
+    properties: {
+        id: { type: 'string', description: 'Stable id (made from the title or file if left out)' },
+        title: { type: 'string' },
+        note: { type: 'string', description: 'Markdown: what to look at, what changed, what you want to know' },
+        ask: { type: 'string', description: 'What you are asking about this item ("Is the spacing right?")' },
+        file: { type: 'string', description: 'A path relative to the project folder' },
+        files: { type: 'array', items: { type: 'string' }, description: 'Several project paths: one item each' },
+        lines: { oneOf: [{ type: 'string', pattern: '^\\d+(-\\d+)?$' }, { type: 'integer' }] },
+        against: { type: 'string', description: 'With file: show its changes since this git revision (HEAD, main, a hash)' },
+        snapshot: { type: 'boolean', description: 'With file: keep a copy as it is now (default true) so later edits show as changed' },
+        code: { type: 'string' },
+        lang: { type: 'string' },
+        name: { type: 'string', description: 'A file name to show (and to guess the language from)' },
+        text: { type: 'string' },
+        md: { type: 'string' },
+        json: { description: 'Any JSON value, shown as a tree' },
+        diff: { type: 'string', description: 'A unified diff' },
+        image: { type: 'string', description: 'A project path, an https: URL, or a data:image/…;base64 URL' },
+        alt: { type: 'string' },
+        before: { type: 'string', description: 'Before/after: the earlier picture (path, URL or data URL) for image, or the earlier text for code/text' },
+        mermaid: { type: 'string' },
+        html: { type: 'string' },
+        height: { type: 'number' },
+        link: { type: 'string' },
+        label: { type: 'string' },
+        collapsed: { type: 'boolean' },
+    },
+    additionalProperties: false,
+};
+export const reviewSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://unpkg.com/hitloop/schema/reviews.schema.json',
+    title: 'hitl review',
+    description: 'Things an agent shows the human to look at, review or approve (.hitl/reviews/<id>.json).',
+    type: 'object',
+    properties: {
+        $schema: { type: 'string' },
+        title: { type: 'string' },
+        intro: { type: 'string', description: 'Markdown at the top: what this is and what you want' },
+        mode: { enum: ['review', 'show', 'approve'], description: 'review: a verdict per item; show: just look; approve: one yes or no' },
+        status: { enum: ['open', 'closed'] },
+        from: { type: 'string', description: "Who's asking: an agent session's name, a branch" },
+        created: { type: 'string' },
+        updated: { type: 'string' },
+        items: { type: 'array', items: itemSchema },
+    },
+    additionalProperties: false,
+};