ultimate-brain 0.0.0-stage → 0.2.0

package/dist/lib/note-new.js

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { BrainError } from "./errors.js";
+import { serializeNewFile } from "./frontmatter.js";
+import { generateId, TYPE_PREFIX } from "./ids.js";
+import { assertNoProblems, escapePointer, isRecord, unknownKeys } from "./input.js";
+import { newNotePath } from "./paths.js";
+import { formatDate, formatTimestamp } from "./time.js";
+const ITEM_KEYS = ["type", "id", "title", "file_date", "frontmatter", "body"];
+const KNOWLEDGE_TYPES = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "memory"]);
+const NEW_NOTE_TYPES = new Set([...KNOWLEDGE_TYPES, "source"]);
+const FORBIDDEN_KEYS = ["id", "type", "title", "created", "updated", "lifecycle"];
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Types whose path uses the note's own `date` (spec/cli.md §3.8). */
+const DATED_BY_FIELD = new Set(["meeting", "decision"]);
+function isDate(value) {
+    if (typeof value !== "string" || !DATE.test(value))
+        return false;
+    const time = Date.parse(`${value}T00:00:00Z`);
+    return !Number.isNaN(time) && new Date(time).toISOString().startsWith(value);
+}
+/** Shape problems of one input item; `withId: false` for a proposal's `note`, which has no id. */
+export function checkNoteInput(value, pointer, withId = true) {
+    if (!isRecord(value))
+        return [{ pointer, message: "must be an object" }];
+    const problems = unknownKeys(value, withId ? ITEM_KEYS : ITEM_KEYS.filter((key) => key !== "id"), pointer);
+    const at = (key, message) => problems.push({ pointer: `${pointer}/${key}`, message });
+    if (typeof value.type !== "string" || !NEW_NOTE_TYPES.has(value.type)) {
+        at("type", `must be one of ${[...NEW_NOTE_TYPES].join(", ")} (views and proposals have their own commands)`);
+    }
+    if (typeof value.title !== "string" || value.title === "")
+        at("title", "must be a non-empty string");
+    if (value.id !== undefined) {
+        const prefix = TYPE_PREFIX[String(value.type)];
+        if (typeof value.id !== "string" || prefix === undefined || !new RegExp(`^${prefix}-[0-9a-hjkmnp-tv-z]{8}$`).test(value.id)) {
+            at("id", `must be a ${prefix ?? "<prefix>"}- id from brain id new`);
+        }
+    }
+    if (value.file_date !== undefined && !isDate(value.file_date))
+        at("file_date", "must be a real date, YYYY-MM-DD");
+    if (typeof value.body !== "string")
+        at("body", "must be a string");
+    else if (value.type === "source" && value.body.includes("\r"))
+        at("body", "must use LF line endings (a source is hashed byte for byte)");
+    if (!isRecord(value.frontmatter)) {
+        at("frontmatter", "must be an object");
+    }
+    else {
+        const forbidden = value.type === "source" ? [...FORBIDDEN_KEYS, "content_hash"] : FORBIDDEN_KEYS;
+        for (const key of Object.keys(value.frontmatter)) {
+            if (forbidden.includes(key))
+                at(`frontmatter/${escapePointer(key)}`, "is set by the CLI");
+        }
+    }
+    return problems;
+}
+/**
+ * Stage new notes in the workspace (spec/cli.md §5.5) without validating them, so a caller can
+ * stage related writes (a meeting back-reference) first. Items must have passed `checkNoteInput`.
+ * Throws ID_IN_USE when an input id already exists or repeats in the batch.
+ */
+export function stageNotes(workspace, items, pointerOf, options) {
+    const existing = workspace.ids();
+    const seen = new Set();
+    const clashes = [];
+    items.forEach((item, index) => {
+        if (item.id === undefined)
+            return;
+        if (existing.has(item.id) || seen.has(item.id))
+            clashes.push({ pointer: `${pointerOf(index)}/id`, message: `${item.id} is already in use` });
+        seen.add(item.id);
+    });
+    if (clashes.length > 0)
+        throw new BrainError("ID_IN_USE", `${clashes[0].pointer} ${clashes[0].message}`, clashes);
+    const today = formatDate(options.now);
+    const taken = new Set([...existing, ...seen]);
+    const result = { created: [], skipped: [], pointers: new Map() };
+    items.forEach((item, index) => {
+        const lf = item.body.replace(/\r\n?/g, "\n");
+        const body = lf === "" || lf.endsWith("\n") ? lf : `${lf}\n`;
+        const attributes = { type: item.type, title: item.title, ...item.frontmatter };
+        if (KNOWLEDGE_TYPES.has(item.type))
+            attributes.lifecycle = options.lifecycle ?? "draft";
+        if (item.type === "source") {
+            const hash = `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+            const sourceKey = attributes.source_key;
+            const duplicateByKey = typeof sourceKey === "string" && (sourceKey.startsWith("file:") || attributes.kind === "capture");
+            const duplicate = workspace.notes.find((note) => note.type === "source" && (note.attributes.content_hash === hash || (duplicateByKey && note.attributes.source_key === sourceKey)));
+            if (duplicate !== undefined) {
+                result.skipped.push({ input_index: index, reason: "DUPLICATE_SOURCE", existing: duplicate.id });
+                return;
+            }
+            attributes.content_hash = hash;
+            attributes.captured ??= formatTimestamp(options.now);
+        }
+        const id = item.id ?? generateId(TYPE_PREFIX[item.type], taken);
+        taken.add(id);
+        attributes.id = id;
+        attributes.created = today;
+        attributes.updated = today;
+        const ownDate = DATED_BY_FIELD.has(item.type) && isDate(item.frontmatter.date) ? item.frontmatter.date : undefined;
+        const date = ownDate ?? item.file_date ?? today;
+        const path = newNotePath(item.type, item.title, date, (candidate) => workspace.exists(candidate), attributes.source_key);
+        workspace.write(path, serializeNewFile(attributes, body));
+        result.created.push({ id, type: item.type, title: item.title, path });
+        result.pointers.set(path, pointerOf(index));
+    });
+    return result;
+}
+/**
+ * Throw INPUT_INVALID if the staged writes add lint errors anywhere in the brain (spec/cli.md
+ * §3.6.1). Errors in a staged file point at its input item; others name the file and point at `root`.
+ */
+export function assertStagedValid(workspace, pointers, root = "") {
+    const problems = workspace.newErrors().map((issue) => {
+        const pointer = pointers.get(issue.path);
+        return pointer === undefined
+            ? { pointer: root, message: `${issue.path}: ${issue.rule}: ${issue.message}` }
+            : { pointer, message: `${issue.rule}: ${issue.message}` };
+    });
+    assertNoProblems(problems);
+}

package/dist/lib/notes.js

@@ -0,0 +1,95 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+/** Folders whose `.md` files must all be notes (spec/cli.md §3.7). */
+export const NOTE_FOLDERS = [
+    "areas",
+    "goals",
+    "projects",
+    "archive",
+    "knowledge",
+    "sources",
+    "memories",
+    "_proposals",
+];
+/** Read every note in the brain. Never throws on content problems; reports them instead. */
+export async function scanNotes(root) {
+    const paths = [];
+    const problems = [];
+    for (const folder of NOTE_FOLDERS) {
+        await collectMarkdown(root, folder, paths, problems);
+    }
+    paths.sort(compareCodePoints);
+    const notes = [];
+    for (const path of paths) {
+        let source;
+        try {
+            source = await readFile(join(root, path), "utf8");
+        }
+        catch (error) {
+            problems.push({ path, code: "UNREADABLE", message: error instanceof Error ? error.message : String(error) });
+            continue;
+        }
+        const parsed = parseNote(path, source);
+        if ("code" in parsed)
+            problems.push(parsed);
+        else
+            notes.push(parsed);
+    }
+    problems.sort((a, b) => compareCodePoints(a.path, b.path));
+    return { notes, problems };
+}
+/** Parse one note file; a file that is not a readable note is reported as a problem. */
+export function parseNote(path, source) {
+    if (source.startsWith("\uFEFF"))
+        source = source.slice(1);
+    if (!/^---\r?\n/.test(source))
+        return { path, code: "NOT_A_NOTE", message: "no frontmatter" };
+    let attributes;
+    let body;
+    try {
+        ({ attributes, body } = parseFrontmatter(source));
+    }
+    catch (error) {
+        return { path, code: "UNPARSEABLE", message: error instanceof Error ? error.message : String(error) };
+    }
+    const { type } = attributes;
+    // A number or other scalar id is kept (as text) so lint reports id-format rather than "no id".
+    const id = typeof attributes.id === "number" ? String(attributes.id) : attributes.id;
+    if (typeof id !== "string" || id === "")
+        return { path, code: "NOT_A_NOTE", message: "frontmatter has no id" };
+    return { path, id, type: typeof type === "string" ? type : "", attributes, body, raw: source };
+}
+async function collectMarkdown(root, relative, out, problems) {
+    let entries;
+    try {
+        entries = await readdir(join(root, relative), { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const child = `${relative}/${entry.name}`;
+        if (entry.isSymbolicLink()) {
+            problems.push({ path: child, code: "SKIPPED_SYMLINK", message: "symbolic links are not followed" });
+        }
+        else if (entry.isDirectory())
+            await collectMarkdown(root, child, out, problems);
+        else if (entry.isFile() && entry.name.endsWith(".md"))
+            out.push(child);
+    }
+}
+/** Compare strings by Unicode code points (not UTF-16 units, not locale). */
+export function compareCodePoints(a, b) {
+    const left = Array.from(a);
+    const right = Array.from(b);
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = left[index].codePointAt(0) - right[index].codePointAt(0);
+        if (difference !== 0)
+            return difference;
+    }
+    return left.length - right.length;
+}

package/dist/lib/paths.js

@@ -0,0 +1,59 @@
+/** Slugs and paths for new files (spec/cli.md §3.8). */
+/** `"María López — PM"` → `maria-lopez-pm`; at most 60 characters, never cutting a word. */
+export function slugify(title) {
+    let slug = title
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (slug.length > 60) {
+        slug = slug.slice(0, 60);
+        const cut = slug.lastIndexOf("-");
+        if (cut !== -1)
+            slug = slug.slice(0, cut);
+    }
+    return slug === "" ? "note" : slug;
+}
+/**
+ * The path of a new file of `type`, or for a project its folder's `project.md`. `date` is the
+ * note's `date`, else the input `file_date`, else `created`. `taken` says whether a path (for
+ * projects: the folder) already exists; `-2`, `-3`, … are appended until it is free.
+ */
+export function newNotePath(type, title, date, taken, sourceKey) {
+    const base = slugify(title);
+    for (let n = 1;; n += 1) {
+        const slug = n === 1 ? base : `${base}-${n}`;
+        const { path, claim } = layout(type, slug, date, sourceKey);
+        if (!taken(claim))
+            return path;
+    }
+}
+/** The folder for a source key (decision 0032). Unknown keys stay in the legacy notion folder for schema validation. */
+export function sourceFolder(sourceKey) {
+    if (typeof sourceKey === "string") {
+        if (sourceKey.startsWith("file:"))
+            return "files";
+        if (sourceKey.startsWith("url:") || sourceKey.startsWith("agent:"))
+            return "text";
+    }
+    return "notion";
+}
+function layout(type, slug, date, sourceKey) {
+    const file = (path) => ({ path, claim: path });
+    switch (type) {
+        case "area": return file(`areas/${slug}.md`);
+        case "goal": return file(`goals/${slug}.md`);
+        case "project": return { path: `projects/${slug}/project.md`, claim: `projects/${slug}` };
+        case "person": return file(`knowledge/people/${slug}.md`);
+        case "org": return file(`knowledge/orgs/${slug}.md`);
+        case "question": return file(`knowledge/questions/${slug}.md`);
+        case "concept": return file(`knowledge/concepts/${slug}.md`);
+        case "meeting": return file(`knowledge/meetings/${date}-${slug}.md`);
+        case "decision": return file(`knowledge/decisions/${date}-${slug}.md`);
+        case "source": return file(`sources/${sourceFolder(sourceKey)}/${date}-${slug}.md`);
+        case "memory": return file(`memories/${date.slice(0, 4)}/${date.slice(5, 7)}/${date}-${slug}.md`);
+        case "proposal": return file(`_proposals/${date}-${slug}.md`);
+        default: throw new Error(`No path layout for type ${type}`);
+    }
+}

package/dist/lib/proposals.js

@@ -0,0 +1,229 @@
+import { isDeepStrictEqual } from "node:util";
+import { BrainError } from "./errors.js";
+import { serializeNewFile } from "./frontmatter.js";
+import { generateId } from "./ids.js";
+import { assertNoProblems, isRecord, unknownKeys } from "./input.js";
+import { assertStagedValid, checkNoteInput, stageNotes } from "./note-new.js";
+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_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 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"];
+/**
+ * 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.
+ */
+export function stageProposals(workspace, items, now) {
+    if (!Array.isArray(items))
+        assertNoProblems([{ pointer: "/proposals", message: "must be a list" }]);
+    const list = items;
+    const problems = [];
+    list.forEach((item, index) => problems.push(...checkShape(item, `/proposals/${index}`)));
+    assertNoProblems(problems);
+    const today = formatDate(now);
+    const created = [];
+    const skipped = [];
+    const pointers = new Map();
+    // A new_item's note is checked alone first, so errors in other items are never blamed on it.
+    list.forEach((item, index) => {
+        if (item.kind === "new_item")
+            checkNewItem(workspace, item.note, `/proposals/${index}/note`, today);
+    });
+    const start = workspace.checkpoint();
+    try {
+        list.forEach((item, index) => {
+            const pointer = `/proposals/${index}`;
+            const fields = resolveFields(workspace, item, pointer, today);
+            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" &&
+                DEDUPE_KEYS.every((key) => isDeepStrictEqual(note.attributes[key], fields[key])));
+            if (duplicate !== undefined) {
+                skipped.push({ input_index: index, reason: "DUPLICATE_PENDING", existing: duplicate.id });
+                return;
+            }
+            const id = generateId("prp", workspace.ids());
+            const attributes = { id, type: "proposal", created: today, updated: today, ...fields, status: "pending" };
+            const path = newNotePath("proposal", String(item.title), today, (candidate) => workspace.exists(candidate));
+            workspace.write(path, serializeNewFile(attributes, ""));
+            pointers.set(path, pointer);
+            const result = {
+                id,
+                kind: String(fields.kind),
+                title: String(fields.title),
+                ...(fields.target === undefined ? {} : { target: String(fields.target) }),
+                path,
+                ...(fields.before === undefined ? {} : { before: fields.before }),
+            };
+            created.push(result);
+        });
+        assertStagedValid(workspace, pointers, "/proposals");
+    }
+    catch (error) {
+        workspace.restore(start);
+        throw error;
+    }
+    return { created, skipped };
+}
+function checkShape(item, pointer) {
+    if (!isRecord(item))
+        return [{ pointer, message: "must be an object" }];
+    const problems = unknownKeys(item, INPUT_KEYS, 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"]) {
+        if (typeof item[key] !== "string" || item[key] === "")
+            at(key, "must be a non-empty string");
+    }
+    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));
+    }
+    else if (typeof item.target !== "string") {
+        at("target", "must be the id of an existing note");
+    }
+    for (const key of ["supersedes", "merge_into"]) {
+        if (item[key] !== undefined && typeof item[key] !== "string")
+            at(key, "must be a note id");
+    }
+    // Everything else (field names, value shapes, required keys per kind) is checked by the proposal schema.
+    return problems;
+}
+/** The proposal's own fields, with `before` and `from` filled in and per-kind rules checked. */
+function resolveFields(workspace, item, pointer, today) {
+    const fields = {};
+    for (const key of INPUT_KEYS)
+        if (item[key] !== undefined)
+            fields[key] = item[key];
+    const kind = item.kind;
+    const invalid = (key, message) => {
+        throw new BrainError("INPUT_INVALID", `${pointer}/${key} ${message}`, [{ pointer: `${pointer}/${key}`, message }]);
+    };
+    const existing = (key) => {
+        const id = item[key];
+        const note = typeof id === "string" ? workspace.get(id) : undefined;
+        if (note === undefined) {
+            throw new BrainError("UNKNOWN_ID", `${pointer}/${key}: no note with id ${String(id)}`, [{ pointer: `${pointer}/${key}`, message: "does not exist" }]);
+        }
+        return note;
+    };
+    if (typeof item.source === "string" && ID.test(item.source))
+        existing("source");
+    if (kind === "new_item")
+        return fields;
+    const target = existing("target");
+    if (!KNOWLEDGE_TYPES.has(target.type))
+        invalid("target", `is a ${target.type}; proposals change knowledge notes only`);
+    if (kind === "update_fact" || kind === "contradiction") {
+        if (typeof item.field !== "string")
+            invalid("field", "is required for this kind");
+        const facts = isRecord(target.attributes.facts) ? target.attributes.facts : {};
+        const current = Object.hasOwn(facts, item.field) ? facts[item.field] : undefined;
+        if (kind === "contradiction" && current === undefined)
+            invalid("field", `${target.id} has no current facts.${String(item.field)} to contradict`);
+        if (item.before !== undefined && !isDeepStrictEqual(item.before, current)) {
+            throw new BrainError("BEFORE_MISMATCH", `${pointer}/before is ${JSON.stringify(item.before)}, but ${target.id} facts.${String(item.field)} is ${current === undefined ? "absent" : JSON.stringify(current)}`, [{ pointer: `${pointer}/before`, message: "differs from the note's current value" }]);
+        }
+        if (current === undefined)
+            delete fields.before;
+        else
+            fields.before = current;
+        if (fields.from === undefined) {
+            const meeting = typeof item.source === "string" && item.source.startsWith("mtg-") ? workspace.get(item.source) : undefined;
+            fields.from = typeof meeting?.attributes.date === "string" ? meeting.attributes.date : today;
+        }
+    }
+    if (kind === "add_link") {
+        const field = typeof item.field === "string" ? item.field : "";
+        if (!ADD_LINK_FIELDS.has(field))
+            invalid("field", "must be aliases, tags, projects, people, attendees or deciders");
+        if (!loadSchemas().knownKeys(target.type)?.has(field))
+            invalid("field", `is not declared by ${target.type}`);
+        if (["projects", "people", "attendees", "deciders"].includes(field)) {
+            const linked = existing("after");
+            const prefix = field === "projects" ? "prj-" : "per-";
+            if (!linked.id.startsWith(prefix))
+                invalid("after", `must be an existing ${prefix} id for ${field}`);
+        }
+    }
+    if (kind === "supersede") {
+        const older = existing("supersedes");
+        if (older.id === target.id)
+            invalid("supersedes", "must differ from target");
+        if (older.type !== target.type)
+            invalid("supersedes", `is a ${older.type}, target is a ${target.type}`);
+        const relations = Array.isArray(older.attributes.relations) ? older.attributes.relations : [];
+        if (relations.some((relation) => isRecord(relation) && relation.type === "superseded_by"))
+            invalid("supersedes", `${older.id} is already superseded`);
+    }
+    if (kind === "merge") {
+        const survivor = existing("merge_into");
+        if (survivor.id === target.id)
+            invalid("merge_into", "must differ from target");
+        if (survivor.type !== target.type)
+            invalid("merge_into", `is a ${survivor.type}, target is a ${target.type}`);
+    }
+    return fields;
+}
+function listField(note, field) {
+    return Array.isArray(note.attributes[field]) ? note.attributes[field] : [];
+}
+/** A new_item's note must pass `note new` validation as apply would write it (spec/cli.md §5.6). */
+function checkNewItem(workspace, note, pointer, today) {
+    const before = workspace.checkpoint();
+    try {
+        const staged = stageNewItem(workspace, note, pointer, new Date(`${today}T00:00:00Z`));
+        assertStagedValid(workspace, staged.pointers, pointer);
+    }
+    finally {
+        workspace.restore(before);
+    }
+}
+/**
+ * Stage a new_item's note as a new note and add it to its meeting's `decisions` or `questions`
+ * (spec/schema.md §11.2). Not validated: the caller does that.
+ */
+export function stageNewItem(workspace, note, pointer, now) {
+    const staged = stageNotes(workspace, [note], () => pointer, { now });
+    const created = staged.created[0];
+    if (created === undefined) {
+        const existingId = staged.skipped[0]?.existing;
+        throw new BrainError("INPUT_INVALID", `${pointer} duplicates source ${String(existingId)}`, [{ pointer, message: `same content as existing source ${String(existingId)}` }]);
+    }
+    const pointers = new Map(staged.pointers);
+    const link = note.type === "decision" ? ["decided_in", "decisions"] : note.type === "question" ? ["raised_in", "questions"] : undefined;
+    const meetingId = link === undefined ? undefined : note.frontmatter[link[0]];
+    const meeting = typeof meetingId === "string" ? workspace.get(meetingId) : undefined;
+    if (link === undefined || meeting === undefined || meeting.type !== "meeting")
+        return { note: created, pointers };
+    const document = workspace.edit(meeting);
+    const ids = Array.isArray(document.attributes[link[1]]) ? document.attributes[link[1]] : [];
+    if (!ids.includes(created.id)) {
+        document.attributes[link[1]] = [...ids, created.id];
+        document.attributes.updated = formatDate(now);
+        workspace.save(meeting.path, document);
+    }
+    pointers.set(meeting.path, pointer);
+    return { note: created, meetingPath: meeting.path, pointers };
+}
+/** Proposals with these statuses and target, sorted by `created` then id (spec/cli.md §5.6). */
+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)
+        .map((note) => ({ ...note.attributes, path: note.path }))
+        .sort((a, b) => compareCodePoints(String(a.created), String(b.created)) || compareCodePoints(String(a.id), String(b.id)));
+}

package/dist/lib/query.js

@@ -0,0 +1,163 @@
+import { readFile, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { BrainError } from "./errors.js";
+import { compareCodePoints } from "./notes.js";
+/** V1 note types accepted by `brain query --types` (spec/cli.md §5.13). */
+export const QUERY_TYPES = [
+    "area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "source", "view", "memory", "proposal",
+];
+const DEFAULT_TYPES = new Set(QUERY_TYPES.filter((type) => !["view", "proposal", "memory"].includes(type)));
+const STOPWORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "by", "did", "do", "does", "for", "from", "has", "have", "how", "in", "is", "it", "of", "on", "or", "that", "the", "this", "to", "was", "we", "what", "when", "where", "which", "who", "why", "will", "with",
+    "al", "como", "con", "de", "del", "el", "en", "es", "la", "las", "lo", "los", "para", "por", "que", "se", "su", "un", "una", "y",
+]);
+/** Normalize a query or field into its query words (spec/cli.md §5.13). */
+export function queryWords(value) {
+    return value
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length >= 2 && !STOPWORDS.has(word));
+}
+/** Parse an explicit `--types` value, or select the contract's default search types. */
+export function queryTypes(value) {
+    if (value === undefined)
+        return DEFAULT_TYPES;
+    const types = value.split(",");
+    if (types.some((type) => !QUERY_TYPES.includes(type))) {
+        throw new BrainError("USAGE", `--types must contain only: ${QUERY_TYPES.join(", ")}`);
+    }
+    return new Set(types);
+}
+/** Read `.brain` context from a consuming repository, without changing it. */
+export async function queryContext(repoPath) {
+    const root = repoPath === undefined ? process.cwd() : resolve(repoPath);
+    let directory;
+    try {
+        directory = (await stat(root)).isDirectory();
+    }
+    catch {
+        directory = false;
+    }
+    if (!directory) {
+        if (repoPath === undefined)
+            return { repo: null, project: null, area: null };
+        throw new BrainError("USAGE", `--repo must be a directory: ${repoPath}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(join(root, ".brain"), "utf8");
+    }
+    catch {
+        return { repo: null, project: null, area: null };
+    }
+    let marker;
+    try {
+        marker = JSON.parse(raw);
+    }
+    catch {
+        throw new BrainError("USAGE", `.brain in ${root} is not valid JSON`);
+    }
+    if (!isMarker(marker))
+        throw new BrainError("USAGE", `.brain in ${root} has an invalid format`);
+    return {
+        repo: marker.repo ?? basename(root),
+        project: marker.project ?? null,
+        area: marker.area ?? null,
+    };
+}
+/** Rank matching notes deterministically, including repository context. */
+export function rankCandidates(notes, tokens, types, context) {
+    return notes
+        .filter((note) => types.has(note.type))
+        .map((note) => ({ candidate: candidateFor(note, tokens, context), updated: stringValue(note.attributes.updated) ?? "" }))
+        .filter((entry) => entry.candidate !== null)
+        .sort((left, right) => right.candidate.score - left.candidate.score
+        || compareCodePoints(right.updated, left.updated)
+        || compareCodePoints(left.candidate.id, right.candidate.id))
+        .map((entry) => entry.candidate);
+}
+function candidateFor(note, tokens, context) {
+    const titleWords = wordsOf(note.attributes.title);
+    const aliasWords = stringsOf(note.attributes.aliases).flatMap(queryWords);
+    const summaryWords = wordsOf(note.attributes.summary);
+    const otherWords = otherFrontmatterStrings(note.attributes).flatMap(queryWords);
+    let score = 0;
+    for (const token of tokens) {
+        if (matches(titleWords, token) || matches(aliasWords, token))
+            score += 5;
+        if (matches(summaryWords, token))
+            score += 3;
+        if (matches(otherWords, token))
+            score += 2;
+        score += Math.min(3, note.body.split(/\r?\n/).filter((line) => matches(queryWords(line), token)).length);
+    }
+    if (context.project !== null && (note.id === context.project || stringsOf(note.attributes.projects).includes(context.project))) {
+        score += 3;
+    }
+    else if (context.area !== null && note.attributes.area === context.area) {
+        score += 2;
+    }
+    if (score === 0)
+        return null;
+    return {
+        id: note.id,
+        type: note.type,
+        title: stringValue(note.attributes.title),
+        path: note.path,
+        summary: stringValue(note.attributes.summary),
+        lifecycle: stringValue(note.attributes.lifecycle),
+        assessment: stringValue(note.attributes.assessment),
+        date: stringValue(note.attributes.date),
+        score,
+        snippets: snippets(note, tokens),
+    };
+}
+function snippets(note, tokens) {
+    const offset = note.raw.slice(0, note.raw.length - note.body.length).split(/\r?\n/).length;
+    const found = [];
+    for (const [index, text] of note.body.split(/\r?\n/).entries()) {
+        if (!tokens.some((token) => matches(queryWords(text), token)))
+            continue;
+        found.push({ line: offset + index, text: text.trim().slice(0, 200) });
+        if (found.length === 3)
+            break;
+    }
+    return found;
+}
+function otherFrontmatterStrings(attributes) {
+    return Object.entries(attributes)
+        .flatMap(([key, value]) => ["title", "aliases", "summary"].includes(key) ? [] : frontmatterStrings(value));
+}
+function frontmatterStrings(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(frontmatterStrings);
+    if (typeof value !== "object" || value === null)
+        return [];
+    return Object.values(value).flatMap(frontmatterStrings);
+}
+function stringsOf(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function wordsOf(value) {
+    return typeof value === "string" ? queryWords(value) : [];
+}
+function matches(words, token) {
+    return words.some((word) => word.startsWith(token));
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : null;
+}
+function isMarker(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const marker = value;
+    return Object.keys(marker).every((key) => ["repo", "project", "area", "stacks"].includes(key))
+        && (marker.repo === undefined || typeof marker.repo === "string")
+        && (marker.project === undefined || typeof marker.project === "string")
+        && (marker.area === undefined || typeof marker.area === "string")
+        && (marker.stacks === undefined || Array.isArray(marker.stacks));
+}