hitloop 0.0.0-stage → 0.1.0

package/dist/q/schema.js

@@ -0,0 +1,133 @@
+// The question-set format as JSON Schema: published as schema/questions.schema.json, printed by `hitl schema questions`, and
+// given to agents in the MCP tools' input schemas.
+const strs = { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] };
+export const blockSchema = {
+    description: 'Rich content. A markdown string, or one block: {md}, {file: "path/in/project", lines?: "10-40"} (rendered by type: code highlighted, markdown, images, mermaid, html preview, csv, pdf, audio/video), {code, lang?} (e.g. proposed code), {diff} (a unified diff of proposed work), {mermaid}, {image: "path or https URL", alt?}, {html, height?} (a sandboxed mockup, no scripts), {link: "https://…", label?}. Any block may have title and collapsed: true.',
+    oneOf: [
+        { type: 'string' },
+        {
+            type: 'object',
+            properties: {
+                md: { type: 'string' },
+                file: { type: 'string', description: 'A path relative to the project folder' },
+                lines: { oneOf: [{ type: 'string', pattern: '^\\d+(-\\d+)?$' }, { type: 'integer' }] },
+                code: { type: 'string' },
+                lang: { type: 'string' },
+                diff: { type: 'string' },
+                mermaid: { type: 'string' },
+                image: { type: 'string' },
+                alt: { type: 'string' },
+                html: { type: 'string' },
+                height: { type: 'number' },
+                link: { type: 'string' },
+                label: { type: 'string' },
+                title: { type: 'string' },
+                collapsed: { type: 'boolean' },
+            },
+            additionalProperties: false,
+        },
+    ],
+};
+const content = { oneOf: [blockSchema, { type: 'array', items: blockSchema }] };
+const conditionOne = {
+    type: 'object',
+    required: ['question'],
+    properties: {
+        question: { type: 'string' },
+        any: { ...strs, description: 'any of these options is picked' },
+        all: { ...strs, description: 'all of these options are picked' },
+        none: { ...strs, description: 'answered, and none of these is picked' },
+        answered: { type: 'boolean' },
+        gte: { type: 'number' },
+        lte: { type: 'number' },
+    },
+    additionalProperties: false,
+};
+export const conditionSchema = {
+    description: 'Shown only when this holds (an array: all must hold). Names a question by id and the option ids that count.',
+    oneOf: [conditionOne, { type: 'array', items: conditionOne }],
+};
+export const optionSchema = {
+    oneOf: [
+        { type: 'string', description: 'Just the label (its id is made from it)' },
+        {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Stable id (default: made from the label)' },
+                label: { type: 'string' },
+                description: { type: 'string', description: 'Markdown: what picking this means' },
+                recommended: { type: 'boolean' },
+                content: { ...content, description: 'A preview of this option: a mockup, code, a diagram, a picture' },
+                shows: { ...strs, description: 'Picking this shows these questions or sections (ids), even if hidden by default' },
+                hides: { ...strs, description: 'Picking this hides these questions or sections (ids)' },
+            },
+            required: ['label'],
+            additionalProperties: false,
+        },
+    ],
+};
+export const questionSchema = {
+    type: 'object',
+    required: ['id', 'question'],
+    properties: {
+        id: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$', description: 'Stable id, unique in the set (questions and sections share ids)' },
+        question: { type: 'string', description: 'Markdown: the question itself, short' },
+        type: {
+            enum: ['single', 'multi', 'yesno', 'text', 'number', 'scale', 'rank'],
+            description: 'Default: single when it has options, else text. scale is min..max (default 1..5); rank orders the options.',
+        },
+        header: { type: 'string', description: 'A short label above the question' },
+        why: { type: 'string', description: 'Markdown: what the answer changes' },
+        content: { ...content, description: 'Context: findings, files, proposed code or diffs, diagrams, pictures' },
+        options: { type: 'array', items: optionSchema },
+        recommended: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }, { type: 'number' }], description: 'Recommended option id(s), or a value for number/scale/text' },
+        priority: { enum: ['blocking', 'high', 'normal', 'low'] },
+        blocking: { type: 'boolean', description: 'Same as priority: "blocking": you cannot go on without it' },
+        hidden: { type: 'boolean', description: 'Hidden until an option `shows` it or `showIf` holds (default visible)' },
+        showIf: conditionSchema,
+        allowOther: { type: 'boolean', description: 'Offer "Other…" on single/multi (default true)' },
+        allowNote: { type: 'boolean', description: 'Offer a free note (default true)' },
+        min: { type: 'number' },
+        max: { type: 'number' },
+        step: { type: 'number' },
+        unit: { type: 'string' },
+        minLabel: { type: 'string' },
+        maxLabel: { type: 'string' },
+        placeholder: { type: 'string' },
+        multiline: { type: 'boolean' },
+        tags: { type: 'array', items: { type: 'string' } },
+    },
+    additionalProperties: false,
+};
+export const sectionSchema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string', description: 'Stable id (questions and sections share ids)' },
+        title: { type: 'string' },
+        intro: { type: 'string', description: 'Markdown shown above the questions: what you found, what this section decides' },
+        content,
+        hidden: { type: 'boolean' },
+        showIf: conditionSchema,
+        questions: { type: 'array', items: questionSchema },
+    },
+    additionalProperties: false,
+};
+export const setSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://unpkg.com/hitloop/schema/questions.schema.json',
+    title: 'hitl question set',
+    description: 'Questions for a person to answer on their phone. Save as .hitl/questions/<set-id>.json in the project.',
+    type: 'object',
+    properties: {
+        $schema: { type: 'string' },
+        title: { type: 'string' },
+        intro: { type: 'string', description: 'Markdown at the top of the set' },
+        content,
+        status: { enum: ['open', 'closed'] },
+        created: { type: 'string' },
+        updated: { type: 'string' },
+        sections: { type: 'array', items: sectionSchema },
+        questions: { type: 'array', items: questionSchema, description: 'Questions outside any section' },
+    },
+    additionalProperties: false,
+};

package/dist/q/store.js

@@ -0,0 +1,413 @@
+// A project's question sets on disk:
+//   <folder>/.hitl/questions/<set>.json   the questions (the agent writes these)
+//   <folder>/.hitl/answers/<set>.json     the answers, replies and read marks (hitl writes these)
+//   <folder>/.hitl/answers/<set>.md       the same answers, readable
+// Every write is a locked read-modify-write with an atomic rename, so the page, the MCP server and the CLI can all
+// write at once from different processes.
+import fs from 'node:fs';
+import path from 'node:path';
+import { StoreError, ensureReadme, stripBom, withLock, writeAtomic } from '../hub/atomic.js';
+export { StoreError };
+import { SET_ID, answersMarkdown, checkAnswer, emptyAnswers, normalise, questionById, recommendedAnswer, summarise, } from './model.js';
+export const DIR = '.hitl';
+export const SCHEMA_URL = 'https://unpkg.com/hitloop/schema/questions.schema.json';
+export class Questions {
+    root;
+    dir;
+    setsDir;
+    answersDir;
+    cache = new Map();
+    constructor(root, dirName = DIR) {
+        this.root = root;
+        this.root = path.resolve(root);
+        this.dir = path.resolve(this.root, dirName);
+        this.setsDir = path.join(this.dir, 'questions');
+        this.answersDir = path.join(this.dir, 'answers');
+    }
+    get exists() {
+        return fs.existsSync(this.setsDir);
+    }
+    ensure() {
+        fs.mkdirSync(this.setsDir, { recursive: true });
+        fs.mkdirSync(this.answersDir, { recursive: true });
+        ensureReadme(this.dir);
+    }
+    setPath(id) {
+        checkId(id);
+        return path.join(this.setsDir, id + '.json');
+    }
+    answersPath(id) {
+        checkId(id);
+        return path.join(this.answersDir, id + '.json');
+    }
+    markdownPath(id) {
+        checkId(id);
+        return path.join(this.answersDir, id + '.md');
+    }
+    /** set ids, from the files in sets/ */
+    ids() {
+        try {
+            return fs
+                .readdirSync(this.setsDir)
+                .filter((f) => f.endsWith('.json') && SET_ID.test(f.slice(0, -5)))
+                .map((f) => f.slice(0, -5))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    has(id) {
+        return SET_ID.test(id) && fs.existsSync(this.setPath(id));
+    }
+    /** the set, normalised (cached until the file changes), or undefined when there's no such set */
+    load(id) {
+        if (!SET_ID.test(id))
+            return undefined;
+        const file = this.setPath(id);
+        let st;
+        try {
+            st = fs.statSync(file);
+        }
+        catch {
+            return undefined;
+        }
+        const hit = this.cache.get(id);
+        if (hit && hit.mtime === st.mtimeMs && hit.size === st.size)
+            return hit.loaded;
+        let raw;
+        let parseError = '';
+        try {
+            raw = JSON.parse(stripBom(fs.readFileSync(file, 'utf8')));
+        }
+        catch (e) {
+            parseError = `${path.basename(file)} isn't valid JSON: ${e instanceof Error ? e.message : String(e)}`;
+            raw = {};
+        }
+        const n = normalise(id, raw);
+        if (parseError)
+            n.errors.unshift(parseError);
+        const loaded = { ...n, raw: raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {}, mtime: st.mtimeMs };
+        this.cache.set(id, { mtime: st.mtimeMs, size: st.size, loaded });
+        return loaded;
+    }
+    answers(id) {
+        try {
+            const data = JSON.parse(stripBom(fs.readFileSync(this.answersPath(id), 'utf8')));
+            if (!data || typeof data !== 'object')
+                return emptyAnswers();
+            const d = data;
+            return {
+                version: 1,
+                seq: typeof d.seq === 'number' ? d.seq : 0,
+                readSeq: typeof d.readSeq === 'number' ? d.readSeq : 0,
+                answers: d.answers && typeof d.answers === 'object' ? d.answers : {},
+                threads: d.threads && typeof d.threads === 'object' ? d.threads : {},
+            };
+        }
+        catch {
+            return emptyAnswers();
+        }
+    }
+    summary(id) {
+        const l = this.load(id);
+        if (!l)
+            return undefined;
+        return summarise(l.set, this.answers(id), l.errors.length);
+    }
+    summaries() {
+        return this.ids()
+            .map((id) => this.summary(id))
+            .filter((s) => !!s);
+    }
+    // ── writing answers ──
+    /** Change the answers file under its lock; the markdown copy is rewritten too. */
+    mutateAnswers(id, fn) {
+        if (!this.has(id))
+            throw new StoreError(`No set "${id}"`);
+        fs.mkdirSync(this.answersDir, { recursive: true });
+        return withLock(this.answersPath(id), () => {
+            const af = this.answers(id);
+            const result = fn(af);
+            writeAtomic(this.answersPath(id), JSON.stringify(af, null, 2) + '\n');
+            const l = this.load(id);
+            if (l)
+                writeAtomic(this.markdownPath(id), answersMarkdown(l.set, af));
+            return result;
+        });
+    }
+    /** Answer a question (from the page or the CLI). Returns the stored answer. */
+    answer(id, qid, input) {
+        const l = this.mustLoad(id);
+        const q = questionById(l.set, qid);
+        if (!q)
+            throw new StoreError(`No question "${qid}" in "${id}"`);
+        const checked = checkAnswer(q, input);
+        if (!checked.ok)
+            throw new StoreError(checked.error);
+        return this.mutateAnswers(id, (af) => {
+            const prev = af.answers[qid];
+            const a = { ...checked.answer, rev: q.rev, at: new Date().toISOString(), seq: ++af.seq };
+            // the agent's "applied" note stays only while the answer says the same thing
+            if (prev?.ack && same(prev, a))
+                a.ack = prev.ack;
+            af.answers[qid] = a;
+            return a;
+        });
+    }
+    clear(id, qid) {
+        this.mutateAnswers(id, (af) => {
+            if (af.answers[qid]) {
+                delete af.answers[qid];
+                af.seq++;
+            }
+        });
+    }
+    /** Take the recommendation for each of these questions that has one and isn't answered. Returns the ids taken. */
+    acceptRecommended(id, qids) {
+        const l = this.mustLoad(id);
+        return this.mutateAnswers(id, (af) => {
+            const taken = [];
+            for (const qid of qids) {
+                const q = questionById(l.set, qid);
+                if (!q || (af.answers[qid] && af.answers[qid]?.status !== 'later'))
+                    continue;
+                const rec = recommendedAnswer(q);
+                if (!rec)
+                    continue;
+                const checked = checkAnswer(q, rec);
+                if (!checked.ok)
+                    continue;
+                af.answers[qid] = { ...checked.answer, rev: q.rev, at: new Date().toISOString(), seq: ++af.seq };
+                taken.push(qid);
+            }
+            return taken;
+        });
+    }
+    /** A message on a question's thread, from the owner (the page) or the agent. */
+    message(id, qid, from, body) {
+        const l = this.mustLoad(id);
+        if (!questionById(l.set, qid))
+            throw new StoreError(`No question "${qid}" in "${id}"`);
+        if (!body.trim())
+            throw new StoreError('The message is empty');
+        return this.mutateAnswers(id, (af) => {
+            const m = { from, body: body.slice(0, 20000), at: new Date().toISOString(), seq: ++af.seq };
+            (af.threads[qid] ??= []).push(m);
+            return m;
+        });
+    }
+    /** The agent applied these answers: mark them, with a note the owner sees. Returns the ids marked. */
+    ack(id, qids, note) {
+        return this.mutateAnswers(id, (af) => {
+            const done = [];
+            for (const qid of qids) {
+                const a = af.answers[qid];
+                if (!a)
+                    continue;
+                a.ack = { at: new Date().toISOString(), note: note.slice(0, 2000) };
+                done.push(qid);
+            }
+            if (done.length)
+                af.seq++;
+            return done;
+        });
+    }
+    /** The agent has read everything so far. */
+    markRead(id, upTo) {
+        this.mutateAnswers(id, (af) => {
+            af.readSeq = Math.max(af.readSeq, Math.min(upTo ?? af.seq, af.seq));
+        });
+    }
+    // ── writing sets ──
+    /** Change the set file (as written, not normalised) under its lock. Rejects the change if it leaves errors. */
+    mutateSet(id, fn, opts = {}) {
+        checkId(id);
+        this.ensure();
+        const file = this.setPath(id);
+        return withLock(file, () => {
+            let raw;
+            if (fs.existsSync(file)) {
+                try {
+                    raw = JSON.parse(stripBom(fs.readFileSync(file, 'utf8')));
+                }
+                catch (e) {
+                    throw new StoreError(`${path.basename(file)} isn't valid JSON (${e instanceof Error ? e.message : String(e)}); fix it by hand first`);
+                }
+            }
+            else if (opts.create)
+                raw = { $schema: SCHEMA_URL, title: id, created: new Date().toISOString(), sections: [] };
+            else
+                throw new StoreError(`No set "${id}"`);
+            const before = normalise(id, raw).errors.length;
+            const result = fn(raw);
+            raw.updated = new Date().toISOString();
+            const n = normalise(id, raw);
+            if (n.errors.length > before && !opts.force)
+                throw new StoreError('That would make the set invalid:\n' + n.errors.map((e) => '  ' + e).join('\n'));
+            writeAtomic(file, JSON.stringify(raw, null, 2) + '\n');
+            this.cache.delete(id);
+            return { result, normalised: n };
+        });
+    }
+    /** Add questions to a section (made if needed). Questions without ids get one from their text. */
+    addQuestions(id, questions, section, opts = {}) {
+        const { result, normalised } = this.mutateSet(id, (raw) => {
+            if (opts.title && (!raw.title || raw.title === id))
+                raw.title = opts.title;
+            if (opts.from && !raw.from)
+                raw.from = opts.from;
+            raw.sections ??= [];
+            const sec = typeof section === 'string' ? { id: section } : section;
+            let target;
+            if (sec?.id || sec?.title) {
+                const sid = sec.id ?? undefined;
+                target = raw.sections.find((s) => (sid ? s.id === sid : s.title === sec.title));
+                if (!target) {
+                    target = { ...sec, questions: [] };
+                    raw.sections.push(target);
+                }
+                else {
+                    for (const k of ['title', 'intro', 'content', 'hidden', 'showIf'])
+                        if (sec[k] !== undefined && target[k] === undefined)
+                            Object.assign(target, { [k]: sec[k] });
+                }
+            }
+            else if (raw.questions || !raw.sections.length) {
+                raw.questions ??= [];
+                target = { questions: raw.questions };
+            }
+            else {
+                target = raw.sections[raw.sections.length - 1];
+            }
+            if (!target)
+                throw new StoreError('No section to add to');
+            target.questions ??= [];
+            const taken = new Set(existingIds(raw));
+            const ids = [];
+            for (const q of questions) {
+                const copy = { ...q };
+                if (!copy.id) {
+                    const base = slugOf(copy.question ?? copy.q ?? 'q');
+                    let qid = base, n = 2;
+                    while (taken.has(qid))
+                        qid = `${base}-${n++}`;
+                    copy.id = qid;
+                }
+                if (taken.has(copy.id))
+                    throw new StoreError(`The id "${copy.id}" is already in the set (use update_question to change it)`);
+                taken.add(copy.id);
+                ids.push(copy.id);
+                const at = opts.before ? target.questions.findIndex((x) => x.id === opts.before) : -1;
+                if (at >= 0)
+                    target.questions.splice(at, 0, copy);
+                else
+                    target.questions.push(copy);
+            }
+            return ids;
+        }, { create: true });
+        return { ids: result, normalised };
+    }
+    /** Change one question: the patch's fields replace the question's (null removes one). */
+    updateQuestion(id, qid, patch) {
+        return this.mutateSet(id, (raw) => {
+            const q = findRaw(raw, qid);
+            if (!q)
+                throw new StoreError(`No question "${qid}" in "${id}"`);
+            for (const [k, v] of Object.entries(patch)) {
+                if (k === 'id')
+                    continue;
+                if (v === null)
+                    delete q[k];
+                else
+                    q[k] = v;
+            }
+        }).normalised;
+    }
+    removeQuestions(id, qids) {
+        return this.mutateSet(id, (raw) => {
+            const removed = [];
+            const lists = [raw.questions ?? [], ...(raw.sections ?? []).map((s) => s.questions ?? [])];
+            for (const list of lists)
+                for (let i = list.length - 1; i >= 0; i--) {
+                    const q = list[i];
+                    if (q?.id && qids.includes(q.id)) {
+                        list.splice(i, 1);
+                        removed.push(q.id);
+                    }
+                }
+            return removed;
+        }, { force: true }).result;
+    }
+    /** Set-level fields: title, intro, content, status. */
+    updateSet(id, patch, create = false) {
+        return this.mutateSet(id, (raw) => {
+            for (const [k, v] of Object.entries(patch))
+                if (v !== undefined)
+                    raw[k] = v;
+        }, { create }).normalised;
+    }
+    /** Change or add a section's own fields (not its questions). */
+    updateSection(id, sid, patch) {
+        return this.mutateSet(id, (raw) => {
+            raw.sections ??= [];
+            let s = raw.sections.find((x) => x.id === sid);
+            if (!s) {
+                s = { id: sid, questions: [] };
+                raw.sections.push(s);
+            }
+            for (const [k, v] of Object.entries(patch)) {
+                if (v === null)
+                    delete s[k];
+                else if (v !== undefined)
+                    s[k] = v;
+            }
+        }).normalised;
+    }
+    mustLoad(id) {
+        const l = this.load(id);
+        if (!l)
+            throw new StoreError(`No set "${id}"`);
+        return l;
+    }
+}
+function checkId(id) {
+    if (!SET_ID.test(id))
+        throw new StoreError(`Bad set id "${id}": letters, digits, . _ - (up to 80)`);
+}
+function existingIds(raw) {
+    const out = [];
+    for (const q of raw.questions ?? [])
+        if (q.id)
+            out.push(q.id);
+    for (const s of raw.sections ?? []) {
+        if (s.id)
+            out.push(s.id);
+        for (const q of s.questions ?? [])
+            if (q.id)
+                out.push(q.id);
+    }
+    return out;
+}
+function findRaw(raw, qid) {
+    for (const q of raw.questions ?? [])
+        if (q.id === qid)
+            return q;
+    for (const s of raw.sections ?? [])
+        for (const q of s.questions ?? [])
+            if (q.id === qid)
+                return q;
+    return undefined;
+}
+function slugOf(s) {
+    return (s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40)
+        .replace(/-+$/, '') || 'q');
+}
+function same(a, b) {
+    const pick = (x) => JSON.stringify([x.status, x.picked ?? [], x.other ?? '', x.text ?? '', x.number ?? null, x.order ?? [], x.note ?? '']);
+    return pick(a) === pick(b);
+}