ultimate-brain 0.3.1 → 0.4.0

package/dist/lib/proposals.js

@@ -8,15 +8,15 @@ import { compareCodePoints } from "./notes.js";
 import { newNotePath } from "./paths.js";
 import { loadSchemas } from "./schemas.js";
 import { formatDate } from "./time.js";
-export const PROPOSAL_KINDS = ["update_fact", "add_to_note", "add_link", "supersede", "contradiction", "merge", "new_item"];
+export const PROPOSAL_KINDS = ["update_fact", "add_to_note", "add_link", "supersede", "contradiction", "merge", "new_item", "review_notes", "answer"];
 export const PROPOSAL_STATUSES = ["pending", "approved", "rejected", "edited", "applied", "closed"];
 /** Input keys of `proposal new`: the schema §11 fields the CLI does not set (spec/cli.md §5.6). */
-const INPUT_KEYS = ["title", "kind", "target", "field", "before", "after", "from", "content", "note", "supersedes", "merge_into", "why", "source"];
+const INPUT_KEYS = ["title", "kind", "target", "field", "notes", "answer", "answer_note", "before", "after", "from", "content", "note", "supersedes", "merge_into", "why", "source"];
 const ID = /^[a-z]{2,4}-[0-9a-hjkmnp-tv-z]{8}$/;
 const KNOWLEDGE_TYPES = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "memory"]);
 const ADD_LINK_FIELDS = new Set(["aliases", "tags", "projects", "people", "attendees", "deciders"]);
 /** Fields that make two pending proposals the same change (dedupe, spec/cli.md §5.6). */
-const DEDUPE_KEYS = ["kind", "target", "field", "after", "content", "note", "supersedes", "merge_into"];
+const DEDUPE_KEYS = ["kind", "target", "field", "after", "content", "note", "supersedes", "merge_into", "answer", "answer_note"];
 /**
  * Stage proposals for `proposal new` (spec/cli.md §5.6) and validate them. Throws INPUT_INVALID,
  * UNKNOWN_ID or BEFORE_MISMATCH for the whole batch; nothing is staged in that case.
@@ -40,18 +40,38 @@ export function stageProposals(workspace, items, now) {
         if (item.kind === "new_item")
             checkNewItem(workspace, item.note, `/proposals/${index}/note`, today);
     });
+    // One review_notes per source; it takes in that source's add_link items (spec/cli.md §5.6, 0043).
+    const reviews = new Map();
+    list.forEach((item, index) => {
+        if (item.kind !== "review_notes")
+            return;
+        const source = String(item.source);
+        if (reviews.has(source))
+            assertNoProblems([{ pointer: `/proposals/${index}/source`, message: `a second review_notes for ${source} in one input` }]);
+        checkReviewNotes(workspace, item, `/proposals/${index}`);
+        reviews.set(source, { index, item, links: [] });
+    });
     const start = workspace.checkpoint();
     try {
         list.forEach((item, index) => {
             const pointer = `/proposals/${index}`;
+            if (item.kind === "review_notes")
+                return;
             const fields = resolveFields(workspace, item, pointer, today);
+            if (item.kind === "answer" && workspace.get(String(fields.target)).attributes.answer !== undefined) {
+                skipped.push({ input_index: index, reason: "ALREADY_ANSWERED" });
+                return;
+            }
+            const review = item.kind === "add_link" ? reviews.get(String(fields.source)) : undefined;
             if (item.kind === "add_link" && listField(workspace.get(String(fields.target)), String(fields.field)).some((value) => isDeepStrictEqual(value, fields.after))) {
                 skipped.push({ input_index: index, reason: "ALREADY_LINKED" });
                 return;
             }
             const duplicate = workspace.notes.find((note) => note.type === "proposal" && note.attributes.status === "pending" &&
                 (item.kind === "add_link"
-                    ? note.attributes.target === fields.target && proposalLinks(note.attributes).some((link) => link.field === fields.field && isDeepStrictEqual(link.value, fields.after))
+                    ? (note.attributes.kind === "review_notes"
+                        ? review !== undefined && reviewLinks(note.attributes).some((link) => link.target === fields.target && link.field === fields.field && isDeepStrictEqual(link.value, fields.after))
+                        : note.attributes.target === fields.target && proposalLinks(note.attributes).some((link) => link.field === fields.field && isDeepStrictEqual(link.value, fields.after)))
                     : DEDUPE_KEYS.every((key) => isDeepStrictEqual(note.attributes[key], fields[key]))));
             if (duplicate !== undefined) {
                 skipped.push({ input_index: index, reason: "DUPLICATE_PENDING", existing: duplicate.id });
@@ -64,7 +84,10 @@ export function stageProposals(workspace, items, now) {
                     return;
                 }
                 linkKeys.set(key, index);
-                links.push({ item, index, fields });
+                if (review !== undefined)
+                    review.links.push({ index, fields });
+                else
+                    links.push({ item, index, fields });
                 return;
             }
             createProposal(workspace, fields, [index], today, pointer, pointers, created);
@@ -86,6 +109,25 @@ export function stageProposals(workspace, items, now) {
             for (const link of group)
                 createdLinks.set(JSON.stringify([link.fields.target, link.fields.source, link.fields.field, link.fields.after]), proposal.id);
         }
+        for (const review of reviews.values()) {
+            const notes = review.item.notes;
+            if (notes.length === 0 && review.links.length === 0) {
+                skipped.push({ input_index: review.index, reason: "NOTHING_TO_REVIEW" });
+                continue;
+            }
+            const source = String(review.item.source);
+            const fields = {
+                kind: "review_notes",
+                title: review.item.title ?? reviewTitle(workspace, source, notes.length, review.links.length),
+                notes,
+                links: review.links.map(({ fields }) => ({ target: fields.target, field: fields.field, value: fields.after })),
+                why: review.item.why ?? `New notes and links from ${sourceTitle(workspace, source)}`,
+                source,
+            };
+            const proposal = createProposal(workspace, fields, [review.index, ...review.links.map(({ index }) => index)].sort((a, b) => a - b), today, `/proposals/${review.index}`, pointers, created);
+            for (const link of review.links)
+                createdLinks.set(JSON.stringify([link.fields.target, link.fields.source, link.fields.field, link.fields.after]), proposal.id);
+        }
         for (const duplicate of duplicateLinks)
             skipped.push({ input_index: duplicate.input_index, reason: "DUPLICATE_PENDING", existing: createdLinks.get(duplicate.key) });
         assertStagedValid(workspace, pointers, "/proposals");
@@ -106,6 +148,60 @@ function createProposal(workspace, fields, inputIndexes, today, pointer, pointer
     created.push(proposal);
     return proposal;
 }
+/** The `{target, field, value}` links of a review_notes proposal. */
+function reviewLinks(attributes) {
+    return Array.isArray(attributes.links) ? attributes.links.filter(isRecord).map((link) => ({ target: link.target, field: link.field, value: link.value })) : [];
+}
+/** Ids listed by every review_notes proposal, any status (spec/cli.md §5.6). */
+function reviewedIds(workspace) {
+    const listed = new Map();
+    for (const note of workspace.notes) {
+        if (note.type !== "proposal" || note.attributes.kind !== "review_notes" || !Array.isArray(note.attributes.notes))
+            continue;
+        for (const id of note.attributes.notes)
+            if (typeof id === "string" && !listed.has(id))
+                listed.set(id, note.id);
+    }
+    return listed;
+}
+/** The meeting's title for a meeting id, else the source's (spec/cli.md §5.6). */
+function sourceTitle(workspace, source) {
+    return String(workspace.get(source)?.attributes.title ?? source);
+}
+function reviewTitle(workspace, source, notes, links) {
+    const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    const from = sourceTitle(workspace, source);
+    const title = notes === 0
+        ? `Accept ${count(links, "link", "links")} from ${from}`
+        : `Accept ${count(notes, "new note", "new notes")} from ${from}${links === 0 ? "" : `, and ${count(links, "link", "links")}`}`;
+    return title.length > 120 ? `${title.slice(0, 119)}…` : title;
+}
+/** A review_notes item's notes: existing knowledge notes, listed once here and by no other review_notes. */
+function checkReviewNotes(workspace, item, pointer) {
+    const source = workspace.get(String(item.source));
+    if (source === undefined)
+        throw new BrainError("UNKNOWN_ID", `${pointer}/source: no note with id ${String(item.source)}`, [{ pointer: `${pointer}/source`, message: "does not exist" }]);
+    if (source.type !== "meeting" && source.type !== "source")
+        assertNoProblems([{ pointer: `${pointer}/source`, message: "must be a meeting or a source" }]);
+    const listed = reviewedIds(workspace);
+    const seen = new Set();
+    const problems = [];
+    item.notes.forEach((id, index) => {
+        const at = `${pointer}/notes/${index}`;
+        const note = typeof id === "string" ? workspace.get(id) : undefined;
+        if (note === undefined)
+            problems.push({ pointer: at, message: `no note with id ${String(id)}` });
+        else if (!KNOWLEDGE_TYPES.has(note.type))
+            problems.push({ pointer: at, message: `is a ${note.type}, not a knowledge note` });
+        else if (seen.has(note.id))
+            problems.push({ pointer: at, message: "is listed twice" });
+        else if (listed.has(note.id))
+            problems.push({ pointer: at, message: `is already listed by ${listed.get(note.id)}` });
+        if (typeof id === "string")
+            seen.add(id);
+    });
+    assertNoProblems(problems);
+}
 function proposalLinks(attributes) {
     if (Array.isArray(attributes.links))
         return attributes.links.filter(isRecord).map((link) => ({ field: link.field, value: link.value }));
@@ -133,11 +229,34 @@ function checkShape(item, pointer) {
     const at = (key, message) => problems.push({ pointer: `${pointer}/${key}`, message });
     if (!PROPOSAL_KINDS.includes(item.kind))
         at("kind", `must be one of ${PROPOSAL_KINDS.join(", ")}`);
-    for (const key of ["title", "why", "source"]) {
+    for (const key of item.kind === "review_notes" ? ["source"] : ["title", "why", "source"]) {
         if (typeof item[key] !== "string" || item[key] === "")
             at(key, "must be a non-empty string");
     }
-    if (item.kind === "new_item") {
+    for (const key of item.kind === "review_notes" ? ["title", "why"] : []) {
+        if (item[key] !== undefined && (typeof item[key] !== "string" || item[key] === ""))
+            at(key, "must be a non-empty string");
+    }
+    if (item.kind === "review_notes") {
+        if (item.target !== undefined)
+            at("target", "a review_notes has no target");
+        if (!Array.isArray(item.notes))
+            at("notes", "must be a list of note ids");
+    }
+    else if (item.notes !== undefined) {
+        at("notes", "is only allowed on review_notes");
+    }
+    if (item.kind === "answer" && (typeof item.answer !== "string" || item.answer.trim() === ""))
+        at("answer", "must be a non-empty string");
+    if (item.kind !== "answer") {
+        for (const key of ["answer", "answer_note"])
+            if (item[key] !== undefined)
+                at(key, "is only allowed on answer");
+    }
+    if (item.kind === "review_notes") {
+        // Checked against the brain in checkReviewNotes.
+    }
+    else if (item.kind === "new_item") {
         if (item.target !== undefined)
             at("target", "a new_item has no target");
         problems.push(...checkNoteInput(item.note, `${pointer}/note`, false));
@@ -177,6 +296,15 @@ function resolveFields(workspace, item, pointer, today) {
     const target = existing("target");
     if (!KNOWLEDGE_TYPES.has(target.type))
         invalid("target", `is a ${target.type}; proposals change knowledge notes only`);
+    if (kind === "answer") {
+        if (target.type !== "question")
+            invalid("target", `is a ${target.type}; an answer targets a question`);
+        if (item.answer_note !== undefined) {
+            const note = existing("answer_note");
+            if (!KNOWLEDGE_TYPES.has(note.type))
+                invalid("answer_note", `is a ${note.type}, not a knowledge note`);
+        }
+    }
     if (kind === "update_fact" || kind === "contradiction") {
         if (typeof item.field !== "string")
             invalid("field", "is required for this kind");
@@ -274,7 +402,54 @@ export function listProposals(workspace, statuses, target) {
     return workspace.notes
         .filter((note) => note.type === "proposal")
         .filter((note) => statuses.length === 0 || statuses.includes(String(note.attributes.status)))
-        .filter((note) => target === undefined || note.attributes.target === target)
+        .filter((note) => target === undefined || note.attributes.target === target
+        || (note.attributes.kind === "review_notes" && ((Array.isArray(note.attributes.notes) && note.attributes.notes.includes(target)) || reviewLinks(note.attributes).some((link) => link.target === target))))
         .map((note) => ({ ...note.attributes, path: note.path }))
         .sort((a, b) => compareCodePoints(String(a.created), String(b.created)) || compareCodePoints(String(a.id), String(b.id)));
 }
+/**
+ * `proposal backlog` (spec/cli.md §5.6, 0041): one review_notes per source over the `draft`
+ * notes nobody has accepted yet, for a brain made before 0.4.0. A second run writes nothing.
+ */
+export function stageBacklog(workspace, now) {
+    const today = formatDate(now);
+    const listed = reviewedIds(workspace);
+    const claimed = new Set();
+    const created = [];
+    const pointers = new Map();
+    const sources = workspace.notes
+        .filter((note) => note.type === "source")
+        .sort((a, b) => compareCodePoints(String(a.attributes.captured ?? ""), String(b.attributes.captured ?? "")) || compareCodePoints(a.id, b.id));
+    const start = workspace.checkpoint();
+    try {
+        for (const source of sources) {
+            const minutes = (source.attributes.kind ?? "minutes") === "minutes";
+            const meeting = minutes ? workspace.notes.find((note) => note.type === "meeting" && note.attributes.source === source.id) : undefined;
+            const provenance = meeting?.id ?? source.id;
+            const notes = workspace.notes
+                .filter((note) => KNOWLEDGE_TYPES.has(note.type) && note.attributes.lifecycle === "draft" && !listed.has(note.id) && !claimed.has(note.id)
+                && (note.id === meeting?.id || (Array.isArray(note.attributes.sources) && note.attributes.sources.includes(provenance))))
+                .sort((a, b) => compareCodePoints(String(a.attributes.created), String(b.attributes.created)) || compareCodePoints(a.id, b.id));
+            if (notes.length === 0)
+                continue;
+            for (const note of notes)
+                claimed.add(note.id);
+            const fields = {
+                kind: "review_notes",
+                title: reviewTitle(workspace, provenance, notes.length, 0),
+                notes: notes.map((note) => note.id),
+                links: [],
+                why: `Notes from ${sourceTitle(workspace, provenance)} waiting for your review`,
+                source: provenance,
+            };
+            const { input_indexes: _unused, ...proposal } = createProposal(workspace, fields, [], today, "", pointers, []);
+            created.push(proposal);
+        }
+        assertStagedValid(workspace, pointers, "");
+    }
+    catch (error) {
+        workspace.restore(start);
+        throw error;
+    }
+    return created;
+}

package/dist/lib/repos.js

@@ -0,0 +1,129 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { BrainError } from "./errors.js";
+import { isRecord } from "./input.js";
+import { formatTimestamp } from "./time.js";
+const exec = promisify(execFile);
+/** The `repos` list of a brain.json, `[]` when absent. */
+export function linkedRepos(config) {
+    return Array.isArray(config.repos) ? config.repos.filter(isRecord) : [];
+}
+/** The repo named `name`, or REPO_NOT_FOUND. */
+export function findRepo(config, name) {
+    const repo = linkedRepos(config).find((entry) => entry.name === name);
+    if (repo === undefined)
+        throw new BrainError("REPO_NOT_FOUND", `No linked repo named ${name} in brain.json repos`);
+    return repo;
+}
+/** A stored path with `~/` expanded. */
+export function expandPath(path, home = homedir()) {
+    return path === "~" ? home : path.startsWith("~/") ? join(home, path.slice(2)) : path;
+}
+async function git(path, args, input) {
+    const child = exec("git", ["-C", path, ...args], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    if (input !== undefined)
+        child.child.stdin?.end(input);
+    return (await child).stdout;
+}
+async function gitBytes(path, args) {
+    const { stdout } = await exec("git", ["-C", path, ...args], { encoding: "buffer", maxBuffer: 256 * 1024 * 1024 });
+    return stdout;
+}
+/** The real path of the top of the working tree at `path`, or null when it isn't one. */
+export async function workTreeTop(path) {
+    try {
+        const top = (await git(path, ["rev-parse", "--show-toplevel"])).trim();
+        return await realpath(top);
+    }
+    catch {
+        return null;
+    }
+}
+/** The repo's working tree, checked: REPO_NOT_FOUND when `path` isn't the top of one. */
+export async function openRepo(repo, home) {
+    const path = expandPath(repo.path, home);
+    const top = await workTreeTop(path);
+    let real = null;
+    try {
+        real = await realpath(path);
+    }
+    catch { /* missing */ }
+    if (top === null || real !== top)
+        throw new BrainError("REPO_NOT_FOUND", `${repo.path} is not the top of a Git working tree`);
+    return top;
+}
+/** The full id of `rev` as a commit, or REPO_COMMIT_UNKNOWN. */
+export async function resolveCommit(path, rev) {
+    try {
+        return (await git(path, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`])).trim();
+    }
+    catch {
+        throw new BrainError("REPO_COMMIT_UNKNOWN", `${rev} is not a commit in this repo`);
+    }
+}
+/** REPO_COMMIT_UNKNOWN unless `ancestor` is an ancestor of (or equal to) `commit`. */
+export async function assertAncestor(path, ancestor, commit) {
+    try {
+        await git(path, ["merge-base", "--is-ancestor", ancestor, commit]);
+    }
+    catch {
+        throw new BrainError("REPO_COMMIT_UNKNOWN", `${ancestor} is not an ancestor of ${commit}`);
+    }
+}
+const pathspecs = (patterns) => ["--", ...patterns.map((pattern) => `:(glob)${pattern}`)];
+/**
+ * The files matching the patterns that changed from `from` (`""`: none) to `to` (spec/cli.md §5.16):
+ * added or modified ones with the last commit in the range that touched them, oldest first, and
+ * deleted ones apart. No rename detection.
+ */
+export async function repoChanges(path, patterns, from, to) {
+    const changed = new Map();
+    const deleted = [];
+    // A first ingest compares with the empty tree, so every matching file is added.
+    const base = from === "" ? (await git(path, ["hash-object", "-t", "tree", "--stdin"], "")).trim() : from;
+    const fields = (await git(path, ["diff", "--name-status", "-z", "--no-renames", "--diff-filter=AMDT", base, to, ...pathspecs(patterns)])).split("\0").filter(Boolean);
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const status = fields[i][0];
+        const file = fields[i + 1];
+        if (status === "D")
+            deleted.push(file);
+        else
+            changed.set(file, status === "A" ? "added" : "modified");
+    }
+    // The newest commit in the range that touched each file: the first one `git log` names.
+    const last = new Map();
+    const range = from === "" ? [to] : [`${from}..${to}`];
+    const log = await git(path, ["log", "-z", "--no-renames", "--format=%x01%H %ct", "--name-only", ...range, ...pathspecs(patterns)]);
+    for (const block of log.split("\x01").filter(Boolean)) {
+        const [head, ...names] = block.split("\0");
+        const [header, firstName] = head.split("\n");
+        const [commit, time] = header.split(" ");
+        for (const name of [firstName, ...names].map((name) => name?.replace(/^\n/, "")).filter((name) => name !== undefined && name !== "")) {
+            if (!last.has(name))
+                last.set(name, { commit, time: Number(time) });
+        }
+    }
+    const files = [];
+    for (const [file, status] of changed) {
+        const bytes = await gitBytes(path, ["cat-file", "blob", `${to}:${file}`]);
+        const touched = last.get(file);
+        if (touched === undefined)
+            throw new Error(`git log names no commit for ${file}`);
+        files.push({ path: file, status, commit: touched.commit, committed_at: formatTimestamp(new Date(touched.time * 1000)), sha256: createHash("sha256").update(bytes).digest("hex"), bytes: bytes.length });
+    }
+    files.sort((a, b) => a.committed_at.localeCompare(b.committed_at) || (last.get(a.path).time - last.get(b.path).time) || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    deleted.sort();
+    return { files, deleted };
+}
+/** Whether the working tree has uncommitted changes (tracked or untracked). */
+export async function isDirty(path) {
+    return (await git(path, ["status", "--porcelain"])).trim() !== "";
+}
+/** The repo's HEAD commit, or REPO_COMMIT_UNKNOWN for a repo with no commits. */
+export async function headCommit(path) {
+    return resolveCommit(path, "HEAD");
+}